HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/api-client-ts

@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

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:

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