HiveGrid-Wireframes/hivegrid-cloud/packages/api-client-ts/README.md

@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

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:

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