Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,326 @@
# 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<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:
```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=<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:
```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)_