57 lines
1.8 KiB
Markdown
57 lines
1.8 KiB
Markdown
# @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
|