# @hivegrid/api-client-ts Official TypeScript SDK for the HiveGrid REST API. The SDK couples a `@hey-api/openapi-ts`-generated typed client with a hand-written Higher-Level-Wrapper that adds: - Bearer-token, API-key, and async-getter auth modes - Retry with exponential backoff and jitter, honoring `Retry-After` - HTTPS/same-origin request enforcement with redirects disabled - Per-attempt timeouts and bounded response-body streaming - Auto-generated `Idempotency-Key` headers on POST/PUT/PATCH - Async iterator pagination (cursor / token / page) - HMAC-SHA256 webhook signature verification with constant-time compare ## Quickstart ```ts import { createHiveGridClient } from "@hivegrid/api-client-ts"; const client = createHiveGridClient({ baseUrl: "https://api.hivegrid.de", auth: { apiKey: process.env.HIVEGRID_API_KEY! }, tenantId: process.env.HIVEGRID_TENANT_ID, timeoutMs: 30_000, maxResponseBodyBytes: 10 * 1024 * 1024, }); const me = await client.request({ method: "GET", path: "/v1/me" }); for await (const contact of client.paginate("/v1/contacts")) { console.log(contact); } ``` `baseUrl` must use HTTPS. Local HTTP development requires the explicit `allowInsecureLocalhost: true` option and is restricted to loopback hosts. Request paths may be relative or absolute same-origin URLs; cross-origin paths and redirects fail closed so auth, tenant, and trace headers cannot leak. ## Codegen The `src/generated/` directory is produced from the upstream OpenAPI document checked into this package as `openapi.json`. Regenerate with: ```bash pnpm --filter @hivegrid/api-client-ts generate:all ``` The CI workflow `.gitea/workflows/sdk-codegen.yml` rejects pull requests whose generated output drifts from the committed spec. ## See also - `docs/sdks/typescript.md` — full usage guide - `docs/improvement-plan/08-mobile-cli-storybook-sdk/ts-sdk.md` — spec