# @toolctrl/api-client-ts

Official TypeScript SDK for the toolctrl boilerplate 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`
- 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 { createToolctrlClient } from "@toolctrl/api-client-ts";

const client = createToolctrlClient({
  baseUrl: "https://api.toolctrl.de",
  auth: { apiKey: process.env.TOOLCTRL_API_KEY! },
  tenantId: process.env.TOOLCTRL_TENANT_ID,
});

const me = await client.request({ method: "GET", path: "/v1/me" });

for await (const contact of client.paginate("/v1/contacts")) {
  console.log(contact);
}
```

## Codegen

The `src/generated/` directory is produced from the upstream OpenAPI document
checked into this package as `openapi.json`. Regenerate with:

```bash
pnpm --filter @toolctrl/api-client-ts generate:all
```

The CI workflow `.github/workflows/sdk-codegen.yml` rejects PRs 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