Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/08-mobile-cli-storybook-sdk/ts-sdk.md
T

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-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 — 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:

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:

  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: <crypto.randomUUID()> 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<T>
    • 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: <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
  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<T>(fetcher, opts): AsyncIterableIterator<T>
    • 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: <source>.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 <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
  • 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:
    # 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
    
  4. Webhook-Verify-Test gegen Staging:
    • Trigger Test-Webhook über Staging-Workflow-Engine
    • SDK-Konsument verifiziert Signature
  5. Pre-Publish-Verification:
    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)