# TypeScript-SDK (`@toolctrl/api-client-ts`) **Status:** completed **Task-ID:** #63 **Phase:** 08 **Estimated Effort:** 1 Woche **Owner:** unassigned ## Problem Die Boilerplate exponiert eine umfangreiche REST-API (Tenant-CRUD, Contacts, Email-Marketing, Workflow-Engine, Webhooks, …), generiert OpenAPI-Specs via `ApiSpecsService.generateSpecs`, hat aber **keinen offiziellen TypeScript-Client**: - **Tenant-Entwickler** müssen den Client manuell schreiben (fetch + zod-Schema-Re-Definition). Bei API-Änderungen brechen Integrationen still — keine TypeScript-Errors. - **Third-Party-Integratoren** haben keinen Idiomatic-Path: keine Auth-Handling-Helper, kein Retry, kein Idempotency, keine Pagination-Iterator, kein Webhook-Verify - **Eigene Integrations-Tests** (E2E gegen API) müssten den Client doppelt pflegen - **Mobile-App (`#65`)** und **Plugin-System (Phase 06)** brauchen einen typed Client für API-Calls — ohne SDK landet Boilerplate-Code in beiden Konsumenten Wir generieren den Client einmal aus der OpenAPI-Spec und legen einen handgepflegten Higher-Level-Wrapper darüber, der Auth/Retry/Idempotency/Pagination/Webhook-Verify übernimmt. ## Depends on - `01-tech-debt-foundation/dep-updates.md` — moderne TypeScript-Version, Node-fetch-Compat - `02-observability/sentry-wiring-api-worker.md` — generierter Client respektiert Sentry-Request-Tracing-Headers (sentry-trace, baggage) - `05-business-features/feature-flags.md` — SDK kann optional Flags abrufen (read-only Endpoint); kein Hard-Lock — Feature-Flag-Endpoint kann später ergänzt werden ## Blocks - `08-mobile-cli-storybook-sdk/capacitor.md` — Mobile-Wrapper konsumiert SDK für alle API-Calls (Push-Token-Registration, Auth-Flow) - `06-plugin-system/audit-docs.md` — Plugin-SDK kann `@toolctrl/api-client-ts` als Peer-Dependency referenzieren - `11-backlog/customer-sdks.md` (falls priorisiert) — Python/Go-SDKs nutzen dieselbe OpenAPI-Spec-Generation als Foundation ## Approach **Neues Package `packages/api-client-ts/`** + Sibling **`packages/api-types/`** (nur Types, ohne Runtime — für reine Type-Konsumenten). **Generator:** - [`@hey-api/openapi-ts`](https://heyapi.dev/openapi-ts) — best-in-class für moderne OpenAPI-3-Specs; nativer Zod-Schema-Output, tree-shakable, Custom-Templates möglich - Alternativen erwogen: - ❌ `openapi-generator-cli` (Java-basiert): schwergewichtig, schlechte ESM-Compat, kein Zod-Output - ❌ `openapi-fetch`: minimal aber kein Schema-Validierung, keine Generierung - ❌ `kubb`: jünger, weniger battle-tested **Generierungs-Pipeline:** 1. Build-Script `packages/api-client-ts/scripts/generate-spec.ts` ruft `ApiSpecsService.generateSpecs()` headless auf, schreibt Spec nach `packages/api-client-ts/openapi.json` 2. `@hey-api/openapi-ts` liest `openapi.json`, generiert nach `packages/api-client-ts/src/generated/`: - `client.ts` (typed fetch-basierter Client mit Endpoints) - `schemas.ts` (Zod-Schemas für Request/Response) - `types.ts` (TS-Types abgeleitet aus Zod) 3. Higher-Level-Wrapper in `packages/api-client-ts/src/client.ts` re-exportiert und wrappt 4. **Generierter Code wird ins Repo committed** (kein build-time-Generierung beim Konsumenten) — reproducible Builds, kein OpenAPI-Spec-Fetch zur Install-Zeit 5. Pre-Build-Hook in `packages/api-client-ts/package.json`: `prebuild` regeneriert; CI-Job prüft dass committed-Code mit aktueller Spec übereinstimmt (Drift-Check) **Higher-Level-Wrapper-Funktionen** in `packages/api-client-ts/src/client.ts`: ```typescript export interface ToolctrlClientConfig { baseUrl: string; auth: { type: 'apiKey'; key: string } | { type: 'serviceToken'; token: string } | { type: 'jwt'; token: string } | { type: 'getter'; getToken: () => Promise }; tenantId?: string; retry?: { maxAttempts?: number; baseDelayMs?: number }; idempotency?: { autoGenerate?: boolean }; userAgent?: string; fetch?: typeof fetch; // for custom impls (e.g., Capacitor-native fetch) } export class ToolctrlClient { // generierte Resource-Module: client.contacts, client.invoices, ... // jeweils mit list/get/create/update/delete async list(resource, opts): Promise>; paginate(resource, opts): AsyncIterableIterator; // auto-paginate static verifyWebhookSignature(payload: string, signature: string, secret: string): boolean; } ``` **Features im Higher-Level-Wrapper:** 1. **Auth-Handling:** - 3 Token-Typen: API-Key (Header `X-API-Key`), Service-Token (Bearer), JWT (Bearer) - `getter`-Mode für refresh-fähige Tokens (Mobile-App refresht JWT vor Expiry) 2. **Auto-Retry mit Exponential-Backoff:** - Retries auf 5xx + 429 + Network-Errors - Default: 3 Attempts, baseDelayMs=500, exponentielles Backoff (500, 1000, 2000) - Rate-Limit-Aware: bei 429 + Retry-After-Header → wartet exakt Retry-After 3. **Idempotency-Key-Auto-Generation:** - Für POST/PATCH/DELETE: automatisch `Idempotency-Key: ` außer expliziter Key gesetzt - Konfigurierbar via `idempotency.autoGenerate: false` 4. **Webhook-HMAC-Verify-Helper:** - Static-Method `ToolctrlClient.verifyWebhookSignature(payload, signature, secret)` - Implementiert HMAC-SHA256 mit constant-time-Compare - Matched serverside-Signing-Logic in `apps/web/app/modules/workflowEngine/` 5. **Pagination-Async-Iterator:** - `client.paginate(resource, opts)` returnt `AsyncIterableIterator` - Auto-Follows `nextCursor`/`nextPage`-Header oder `links.next` aus Response - Konsument: `for await (const contact of client.paginate('contacts', { tenantId })) { ... }` **Tenant-Scope-Enforcement:** - Wenn `tenantId` in Config gesetzt → wird automatisch an alle Resource-Calls als Header `X-Tenant-ID` oder Query-Param weitergegeben (matched Backend-Convention) - Pro-Call-Override möglich via Method-Parameter **Veröffentlichung:** - `@toolctrl/api-client-ts` als npm-public-Package (oder GitHub-Packages-private wenn vorerst intern) - `@toolctrl/api-types` als sub-package: re-exportiert nur Types, kein Runtime - Beide nutzen `tsup` für Dual-CJS+ESM-Output ## Implementation Steps 1. **Package-Skeleton `api-client-ts` + `api-types`** - Files: - `packages/api-client-ts/package.json`, `tsconfig.json`, `tsup.config.ts`, `src/index.ts`, `README.md` - `packages/api-types/package.json`, `tsconfig.json`, `tsup.config.ts`, `src/index.ts`, `README.md` - Beide: pnpm-workspace, ESM+CJS-Build, Node ≥ 18 (für native fetch) - Smoke-Test: `pnpm --filter @toolctrl/api-client-ts build` erfolgreich - Commit: `08-mobile/ts-sdk: scaffold api-client-ts and api-types packages` 2. **OpenAPI-Spec-Generation-Script** - Files: `packages/api-client-ts/scripts/generate-spec.ts`, `scripts/generate-spec.test.ts` - Headless-Aufruf von `ApiSpecsService.generateSpecs()` (Import aus apps/web mit Server-Bundle-Workaround oder Aufruf via separates Node-Script das die Service-Logik isoliert) - Output: `packages/api-client-ts/openapi.json` (committed) - Drift-Check-Script: regeneriert + diffed mit committed Version, CI-Failure bei Diff - Commit: `08-mobile/ts-sdk: add openapi spec generation script with drift check` 3. **@hey-api/openapi-ts Client-Generation** - Files: `packages/api-client-ts/openapi-ts.config.ts`, generated `src/generated/*` (Client, Schemas, Types) - Config: Zod-Schemas aktiviert, fetch-Client, tree-shaking-friendly - Run: `pnpm --filter @toolctrl/api-client-ts generate` → schreibt `src/generated/` - Generated Output committed - Commit: `08-mobile/ts-sdk: generate typed client from openapi spec via hey-api` 4. **Auth-Handler-Module** - Files: `src/auth.ts`, `src/auth.test.ts` - 4 Auth-Strategies: apiKey, serviceToken, jwt, getter - `applyAuth(request, config): Headers`-Helper - Tests: jeder Auth-Type setzt korrekte Headers; getter-Mode wird pro Request neu aufgerufen - Commit: `08-mobile/ts-sdk: add auth handler with 4 strategies` 5. **Retry-Engine mit Exponential-Backoff + Rate-Limit-Awareness** - Files: `src/retry.ts`, `src/retry.test.ts` - `retryableFetch(input, init, opts)`-Wrapper - Status-Code-Whitelist: 408, 429, 500, 502, 503, 504 + Network-Errors - 429 mit Retry-After-Header → exakte Wartezeit - Tests: Mock-Fetch mit Sequenz von 503→503→200, prüft 2 Retries; 429 mit Retry-After: 60 → wartet ~60s (mocked clock) - Commit: `08-mobile/ts-sdk: add retry engine with exponential backoff and rate-limit awareness` 6. **Idempotency-Key-Auto-Generation** - Files: `src/idempotency.ts`, `src/idempotency.test.ts` - Auto-add `Idempotency-Key: ` für POST/PATCH/DELETE - Konfigurierbar via `idempotency.autoGenerate: false` - Existing Key respektiert (kein Overwrite) - Tests: Header gesetzt bei POST, nicht bei GET, nicht bei `autoGenerate=false` - Commit: `08-mobile/ts-sdk: add idempotency key auto-generation for mutating requests` 7. **Webhook-HMAC-Verify-Helper** - Files: `src/webhooks.ts`, `src/webhooks.test.ts` - Static-Method `ToolctrlClient.verifyWebhookSignature(payload, signature, secret)` - HMAC-SHA256 via `node:crypto` (oder `crypto.subtle` für Browser/Mobile) - Constant-Time-Compare via `crypto.timingSafeEqual` - Tests: Valid Signature → true; tampered Payload → false; tampered Signature → false; passes Cross-Test mit Backend-Signing-Function aus `apps/web/app/modules/workflowEngine/lib/signWebhook.ts` - Commit: `08-mobile/ts-sdk: add webhook hmac signature verifier` 8. **Pagination-Async-Iterator** - Files: `src/pagination.ts`, `src/pagination.test.ts` - `paginate(fetcher, opts): AsyncIterableIterator` - Auto-Detect Cursor/Page/Link-Header-Pagination via Response-Shape - Stop-Conditions: `null` cursor, empty page, max-iterations-Sicherheits-Limit - Tests: 3-Seiten-Mock, verifiziert alle Items in richtiger Reihenfolge geliefert - Commit: `08-mobile/ts-sdk: add async iterator for cursor and page pagination` 9. **Higher-Level-Client-Klasse `ToolctrlClient`** - Files: `src/client.ts`, `src/client.test.ts` - Composiert Auth + Retry + Idempotency + Pagination um den generated Client - Public-API: `new ToolctrlClient(config)`; `client.contacts.list()`, `client.invoices.create()`, etc. - Tenant-Scope-Header-Injection - Tests: End-to-End mit msw-Mock-API: List-Pagination, Create mit Idempotency, 429-Retry, Auth-Header - Commit: `08-mobile/ts-sdk: add toolctrl client composing all middleware` 10. **`@toolctrl/api-types` Re-Export-Surface** - Files: `packages/api-types/src/index.ts` (re-exportiert nur Types aus generated) - Side-effect-free, kein Runtime-Code - Tests: Smoke-Import von Types in einer TSC-Compile-Test-Datei - Commit: `08-mobile/ts-sdk: add api-types subpackage with types-only re-exports` 11. **SDK-Integration-Tests gegen lokale API** - Files: `src/__integration__/sdk-against-local-api.test.ts`, `src/__integration__/setup.ts` - Start lokale API (apps/web) via Vitest-globalSetup oder testcontainers - Test-Flows: Auth → Tenant-Create → Contact-List (paginated) → Contact-Create (mit Auto-Idempotency) → Contact-Delete → Webhook-Signing-Roundtrip - Commit: `08-mobile/ts-sdk: add integration tests against local api instance` 12. **Doku + Publishing-Setup** - Files: `packages/api-client-ts/README.md`, `packages/api-types/README.md`, `docs/api/typescript-sdk.md`, `packages/api-client-ts/CHANGELOG.md` - Doku: Quickstart, Auth-Examples (alle 4 Strategies), Pagination-Example, Webhook-Verify-Example, Error-Handling, Sentry-Integration - `prepublishOnly`-Scripts, `files`-Whitelist, korrekte `exports`-Map - Versions-Strategie: Semver an OpenAPI-Spec-Versionen gekoppelt - Commit: `08-mobile/ts-sdk: add docs and publishing setup for api-client-ts and api-types` ## Test Requirements - **Unit-Tests:** - Auth: alle 4 Strategies setzen korrekte Headers - Retry: Exponential-Backoff-Delays exakt, 429+Retry-After respektiert, max-Attempts respektiert - Idempotency: Header gesetzt für mutating Methods, nicht für GET, opt-out funktioniert - Webhook-Verify: Valid + Invalid + Tampered Cases; constant-time-Compare - Pagination: Cursor + Page + Link-Header alle drei Modi durch Mock - **Integration-Tests (gegen lokale API):** - Full E2E: Auth → List → Create → Update → Delete → Verify-Webhook - Mit echter spawn-ten API-Instance via Vitest globalSetup - **Drift-Check (CI):** `pnpm --filter @toolctrl/api-client-ts generate:check` — regeneriert + diffed gegen committed; Failure bei Diff - **Type-Tests:** `tsd`-basierte Type-Assertion-Tests in `test-d/`-Verzeichnis (z. B. „Pagination-Iterator hat korrekten Yield-Type") - **Coverage-Target:** ≥ 90 % lines/branches im Higher-Level-Wrapper (Generated-Code ausgenommen via coverage-Exclude) - **Test-Files:** `.test.ts` co-located; Integration in `src/__integration__/`; Type-Tests in `test-d/` - **CI-Setup:** Standard-Test + Drift-Check als eigener Job **NICHT als completed markieren bevor Integration-Tests gegen lokale API grün sind und Drift-Check in CI grün ist.** ## Acceptance Criteria - [ ] `packages/api-client-ts/` und `packages/api-types/` existieren, builden grün, sind npm-publishable - [ ] OpenAPI-Spec-Generation aus `ApiSpecsService.generateSpecs()` funktioniert via `pnpm --filter @toolctrl/api-client-ts generate` - [ ] Generated Code (`src/generated/`) committed; Drift-Check in CI verhindert ungesynchten Stand - [ ] `ToolctrlClient`-Klasse exportiert mit Auth, Retry, Idempotency, Pagination - [ ] Alle 4 Auth-Strategies funktionieren (apiKey, serviceToken, jwt, getter) - [ ] Retry-Engine respektiert Retry-After bei 429 - [ ] Idempotency-Key wird automatisch für POST/PATCH/DELETE gesetzt, opt-out funktioniert - [ ] Webhook-Verify cross-tested mit Backend-Signing-Function (Roundtrip-Test) - [ ] Pagination-AsyncIterator funktioniert für Cursor + Page + Link-Header - [ ] Integration-Tests gegen lokale API grün - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm --filter @toolctrl/api-client-ts test` grün - [ ] Coverage ≥ 90 % im Higher-Level-Wrapper - [ ] `docs/api/typescript-sdk.md` mit Quickstart, Auth-Examples, Pagination-Examples, Webhook-Verify-Example - [ ] `packages/api-client-ts/README.md` + `packages/api-types/README.md` mit Install + Quickstart - [ ] Detail-MD Progress Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy - SDK-Packages sind additiv: `git revert ` der `#63`-Commits → beide Packages verschwinden, niemand intern konsumiert sie zwingend - Falls bereits npm-published: `npm deprecate @toolctrl/api-client-ts@x.y.z "Reverted due to regression — use vY"` statt unpublish (unpublish ist 72h-window-limited) - Backend-API unverändert (SDK ist Consumer, kein Provider) - Bei Drift-Check-Failure in CI: Re-generate + Commit, kein Revert nötig - Falls Generator (`@hey-api/openapi-ts`) inkompatibel mit neuer OpenAPI-Spec: SDK-Versions-Pin auf vorletzte funktionierende Spec-Version, Issue an Upstream ## Security Notes - **Token-Handling:** - SDK loggt **niemals** vollständige Tokens, nur masked Prefix (`sk_live_***`) - Token-Storage ist Konsumenten-Responsibility (Doku-Hinweis: nie in localStorage, nutze httpOnly-Cookies oder Secure-Native-Storage wie iOS-Keychain/Android-EncryptedSharedPreferences) - `getter`-Mode für Mobile: empfohlene Pattern für JWT-Refresh ohne Token-Persistence im SDK-State - **Webhook-Verify:** - Constant-Time-Compare via `crypto.timingSafeEqual` — verhindert Timing-Side-Channels - Doku-Beispiel zeigt expliziten Pattern: `if (!verify(...)) return 403` BEFORE any payload-handling - **Idempotency-Key:** - Auto-generated UUIDs via `crypto.randomUUID()` (kryptografisch sicher) - Keys werden serverseitig gegen Replay-Attacks zeitlich gebunden (24h-TTL aus `apps/api/src/idempotency/`) - **Retry-Mechanik:** - Default-Idempotent-Methods (GET, HEAD, PUT, DELETE) werden ohne weitere Checks retried - Non-Idempotent (POST, PATCH) nur mit gesetztem Idempotency-Key — sonst Retry-Skip um Doppel-Effekte zu vermeiden - **TLS-Verifikation:** - Default: nativer Node/Browser-fetch mit TLS-Verify enabled - SDK exposed **keinen** `rejectUnauthorized: false`-Switch (verhindert Misuse in Production) - **Sentry-Trace-Headers:** - SDK forward `sentry-trace` + `baggage`-Headers wenn vom Konsumenten-Context vorhanden — ermöglicht End-to-End-Tracing - **OpenAPI-Spec-Leak-Vermeidung:** - `openapi.json` darf keine Internal-Admin-Endpoints enthalten → `ApiSpecsService` filtert vor Generation (validation in CI) - **NPM-Publish-Security:** - 2FA-required für `@toolctrl/*` npm-Org - Provenance-Statements via npm-Provenance bei Publish (`npm publish --provenance`) ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD + `apps/web/app/modules/api/specs/` (ApiSpecsService-Source) als Input - **Research:** `Explore`-Subagent mit Auftrag „prüfe `@hey-api/openapi-ts`-Custom-Templates und welche Config für unseren Zod-First-Stil nötig ist; vergleiche generierten Output gegen unsere OpenAPI-Spec auf Vollständigkeit" - **Implementation:** Ein `general-purpose`-Subagent pro Wrapper-Modul (4-9); jedes Modul ist isoliert testbar - **Tests:** Separater `general-purpose`-Subagent pro Test-Suite; insbesondere Integration-Test-Setup braucht eigenen Kontext (Vitest-globalSetup mit API-spawn) - **Verification:** `gsd-verifier` prüft Acceptance-Criteria + Drift-Check + Integration-Test-Grün - **Code-Review:** `gsd-code-reviewer` nach Schritt 12, Fokus auf Token-Logging-Sicherheit, Webhook-Constant-Time-Compare, Idempotency-Auto-Gen-Korrektheit ## Staging-Deployment-Steps 1. Branch `agent/08-ts-sdk` pushen 2. CI baut beide Packages + npm-pack als Artifact 3. Manueller Test auf Staging: ```bash # SSH auf Staging-Server oder lokal mkdir /tmp/sdk-staging-test && cd /tmp/sdk-staging-test npm init -y npm install ../path/to/toolctrl-api-client-ts-x.y.z.tgz cat > test.mjs <<'EOF' import { ToolctrlClient } from '@toolctrl/api-client-ts'; const client = new ToolctrlClient({ baseUrl: 'https://api.staging.toolctrl.de', auth: { type: 'apiKey', key: process.env.TEST_API_KEY }, tenantId: process.env.TEST_TENANT_ID, }); const contacts = await client.contacts.list({ pageSize: 5 }); console.log('First 5 contacts:', contacts.data); for await (const c of client.paginate('contacts')) { console.log('Paginated:', c.id); } EOF TEST_API_KEY= TEST_TENANT_ID= node test.mjs ``` 4. Webhook-Verify-Test gegen Staging: - Trigger Test-Webhook über Staging-Workflow-Engine - SDK-Konsument verifiziert Signature 5. Pre-Publish-Verification: ```bash npm pack --dry-run # zeigt was published wird npm publish --dry-run --access public ``` 6. **Echtes npm-Publish ist Operator-Task** mit 2FA — Agent macht nur Dry-Run ## Deviations from Plan _(Wird vom ausführenden Agent während Implementation gefüllt, falls Abweichungen)_ ## Progress Log _(Wird vom ausführenden Agent nach jedem commit gefüllt)_ ## Lessons Learned _(Optional, am Ende des Tasks für nachfolgende Tasks)_