19 KiB
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-Compat02-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-tsals Peer-Dependency referenzieren11-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— 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:
- Build-Script
packages/api-client-ts/scripts/generate-spec.tsruftApiSpecsService.generateSpecs()headless auf, schreibt Spec nachpackages/api-client-ts/openapi.json @hey-api/openapi-tsliestopenapi.json, generiert nachpackages/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)
- Higher-Level-Wrapper in
packages/api-client-ts/src/client.tsre-exportiert und wrappt - Generierter Code wird ins Repo committed (kein build-time-Generierung beim Konsumenten) — reproducible Builds, kein OpenAPI-Spec-Fetch zur Install-Zeit
- Pre-Build-Hook in
packages/api-client-ts/package.json:prebuildregeneriert; 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:
export interface ToolctrlClientConfig {
baseUrl: string;
auth: { type: 'apiKey'; key: string }
| { type: 'serviceToken'; token: string }
| { type: 'jwt'; token: string }
| { type: 'getter'; getToken: () => Promise<string> };
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<T>(resource, opts): Promise<PaginatedResult<T>>;
paginate<T>(resource, opts): AsyncIterableIterator<T>; // auto-paginate
static verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
}
Features im Higher-Level-Wrapper:
- 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)
- 3 Token-Typen: API-Key (Header
- 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
- Idempotency-Key-Auto-Generation:
- Für POST/PATCH/DELETE: automatisch
Idempotency-Key: <crypto.randomUUID()>außer expliziter Key gesetzt - Konfigurierbar via
idempotency.autoGenerate: false
- Für POST/PATCH/DELETE: automatisch
- 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/
- Static-Method
- Pagination-Async-Iterator:
client.paginate(resource, opts)returntAsyncIterableIterator<T>- Auto-Follows
nextCursor/nextPage-Header oderlinks.nextaus Response - Konsument:
for await (const contact of client.paginate('contacts', { tenantId })) { ... }
Tenant-Scope-Enforcement:
- Wenn
tenantIdin Config gesetzt → wird automatisch an alle Resource-Calls als HeaderX-Tenant-IDoder Query-Param weitergegeben (matched Backend-Convention) - Pro-Call-Override möglich via Method-Parameter
Veröffentlichung:
@toolctrl/api-client-tsals npm-public-Package (oder GitHub-Packages-private wenn vorerst intern)@toolctrl/api-typesals sub-package: re-exportiert nur Types, kein Runtime- Beide nutzen
tsupfür Dual-CJS+ESM-Output
Implementation Steps
-
Package-Skeleton
api-client-ts+api-types- Files:
packages/api-client-ts/package.json,tsconfig.json,tsup.config.ts,src/index.ts,README.mdpackages/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 builderfolgreich - Commit:
08-mobile/ts-sdk: scaffold api-client-ts and api-types packages
- Files:
-
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
- Files:
-
@hey-api/openapi-ts Client-Generation
- Files:
packages/api-client-ts/openapi-ts.config.ts, generatedsrc/generated/*(Client, Schemas, Types) - Config: Zod-Schemas aktiviert, fetch-Client, tree-shaking-friendly
- Run:
pnpm --filter @toolctrl/api-client-ts generate→ schreibtsrc/generated/ - Generated Output committed
- Commit:
08-mobile/ts-sdk: generate typed client from openapi spec via hey-api
- Files:
-
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
- Files:
-
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
- Files:
-
Idempotency-Key-Auto-Generation
- Files:
src/idempotency.ts,src/idempotency.test.ts - Auto-add
Idempotency-Key: <crypto.randomUUID()>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
- Files:
-
Webhook-HMAC-Verify-Helper
- Files:
src/webhooks.ts,src/webhooks.test.ts - Static-Method
ToolctrlClient.verifyWebhookSignature(payload, signature, secret) - HMAC-SHA256 via
node:crypto(odercrypto.subtlefü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
- Files:
-
Pagination-Async-Iterator
- Files:
src/pagination.ts,src/pagination.test.ts paginate<T>(fetcher, opts): AsyncIterableIterator<T>- Auto-Detect Cursor/Page/Link-Header-Pagination via Response-Shape
- Stop-Conditions:
nullcursor, 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
- Files:
-
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
- Files:
-
@toolctrl/api-typesRe-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
- Files:
-
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
- Files:
-
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, korrekteexports-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
- Files:
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 intest-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:
<source>.test.tsco-located; Integration insrc/__integration__/; Type-Tests intest-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/undpackages/api-types/existieren, builden grün, sind npm-publishable- OpenAPI-Spec-Generation aus
ApiSpecsService.generateSpecs()funktioniert viapnpm --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 testgrün- Coverage ≥ 90 % im Higher-Level-Wrapper
docs/api/typescript-sdk.mdmit Quickstart, Auth-Examples, Pagination-Examples, Webhook-Verify-Examplepackages/api-client-ts/README.md+packages/api-types/README.mdmit Install + Quickstart- Detail-MD Progress Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
- SDK-Packages sind additiv:
git revert <range>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
- SDK loggt niemals vollständige Tokens, nur masked Prefix (
- Webhook-Verify:
- Constant-Time-Compare via
crypto.timingSafeEqual— verhindert Timing-Side-Channels - Doku-Beispiel zeigt expliziten Pattern:
if (!verify(...)) return 403BEFORE any payload-handling
- Constant-Time-Compare via
- 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/)
- Auto-generated UUIDs via
- 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
- SDK forward
- OpenAPI-Spec-Leak-Vermeidung:
openapi.jsondarf keine Internal-Admin-Endpoints enthalten →ApiSpecsServicefiltert 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)
- 2FA-required für
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-verifierprüft Acceptance-Criteria + Drift-Check + Integration-Test-Grün - Code-Review:
gsd-code-reviewernach Schritt 12, Fokus auf Token-Logging-Sicherheit, Webhook-Constant-Time-Compare, Idempotency-Auto-Gen-Korrektheit
Staging-Deployment-Steps
- Branch
agent/08-ts-sdkpushen - CI baut beide Packages + npm-pack als Artifact
- Manueller Test auf Staging:
# 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=<staging-key> TEST_TENANT_ID=<staging-tenant> node test.mjs - Webhook-Verify-Test gegen Staging:
- Trigger Test-Webhook über Staging-Workflow-Engine
- SDK-Konsument verifiziert Signature
- Pre-Publish-Verification:
npm pack --dry-run # zeigt was published wird npm publish --dry-run --access public - 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)