Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -1,13 +1,12 @@
# TypeScript SDK — `@toolctrl/api-client-ts`
# TypeScript SDK — `@hivegrid/api-client-ts`
The official TypeScript SDK for the toolctrl boilerplate REST API. Pairs a
The official TypeScript SDK for the HiveGrid REST API. Pairs a
`@hey-api/openapi-ts`-generated typed client with a hand-written Higher-Level
wrapper that handles auth, retry, idempotency, pagination, and webhook
signature verification.
- Source: `packages/api-client-ts/`
- Types-only sibling: `packages/api-types/` (`@toolctrl/api-types`)
- Spec: `docs/improvement-plan/08-mobile-cli-storybook-sdk/ts-sdk.md`
- Types-only sibling: `packages/api-types/` (`@hivegrid/api-types`)
## Installation
@@ -17,7 +16,7 @@ consumer inside this monorepo:
```jsonc
{
"dependencies": {
"@toolctrl/api-client-ts": "workspace:*"
"@hivegrid/api-client-ts": "workspace:*"
}
}
```
@@ -25,7 +24,7 @@ consumer inside this monorepo:
After the SDK is published to the internal registry it becomes:
```bash
npm install @toolctrl/api-client-ts @toolctrl/api-types
npm install @hivegrid/api-client-ts @hivegrid/api-types
```
The package targets Node 18+ and modern browsers (uses native `fetch` and
@@ -34,12 +33,12 @@ The package targets Node 18+ and modern browsers (uses native `fetch` and
## Quickstart
```ts
import { createToolctrlClient } from "@toolctrl/api-client-ts";
import { createHiveGridClient } from "@hivegrid/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 client = createHiveGridClient({
baseUrl: "https://api.hivegrid.de",
auth: { apiKey: process.env.HIVEGRID_API_KEY! },
tenantId: process.env.HIVEGRID_TENANT_ID,
});
// Typed REST call — falls back to `unknown` if T is omitted.
@@ -55,15 +54,15 @@ Three modes are supported via the `auth` field.
```ts
// Bearer token — `Authorization: Bearer <token>` on every call.
createToolctrlClient({ baseUrl, auth: { bearerToken: jwt } });
createHiveGridClient({ baseUrl, auth: { bearerToken: jwt } });
// API key — sent as `X-API-Key: <key>`.
createToolctrlClient({ baseUrl, auth: { apiKey: process.env.TOOLCTRL_API_KEY! } });
createHiveGridClient({ baseUrl, auth: { apiKey: process.env.HIVEGRID_API_KEY! } });
// Async getter — used for refresh-aware JWT flows. Resolved before every
// outgoing request; the result is cached until `client.refreshAuth()` is
// called or the getter returns a new value.
createToolctrlClient({
createHiveGridClient({
baseUrl,
auth: { getToken: () => loadTokenFromKeychain() },
});
@@ -87,7 +86,7 @@ By default the client retries on `408`, `425`, `429`, `500`, `502`, `503`,
are honored verbatim and capped at the configured `maxDelayMs`.
```ts
createToolctrlClient({
createHiveGridClient({
baseUrl,
retry: {
maxAttempts: 5, // default 5 (initial request counts as attempt 1)
@@ -97,21 +96,21 @@ createToolctrlClient({
});
```
Non-retryable 4xx responses surface as `ToolctrlApiError`:
Non-retryable 4xx responses surface as `HiveGridApiError`:
```ts
import { ToolctrlApiError } from "@toolctrl/api-client-ts";
import { HiveGridApiError } from "@hivegrid/api-client-ts";
try {
await client.request({ method: "GET", path: "/v1/missing" });
} catch (err) {
if (err instanceof ToolctrlApiError) {
if (err instanceof HiveGridApiError) {
console.error(err.status, err.requestId, err.body);
}
}
```
Exhausted retries throw `ToolctrlNetworkError` with the underlying `cause`.
Exhausted retries throw `HiveGridNetworkError` with the underlying `cause`.
## Idempotency
@@ -129,7 +128,7 @@ await client.request({
});
// Disable auto-generation globally.
createToolctrlClient({ baseUrl, idempotency: { autoGenerate: false } });
createHiveGridClient({ baseUrl, idempotency: { autoGenerate: false } });
```
GET / HEAD / DELETE requests never receive an auto-generated key.
@@ -161,18 +160,18 @@ payload data. The helper uses HMAC-SHA256 plus constant-time compare and
applies a 5-minute replay window.
```ts
import { verifyWebhookSignature } from "@toolctrl/api-client-ts";
import { verifyWebhookSignature } from "@hivegrid/api-client-ts";
export async function action({ request }: Route.ActionArgs) {
const signature = request.headers.get("X-Toolctrl-Signature");
const timestamp = request.headers.get("X-Toolctrl-Timestamp");
const signature = request.headers.get("X-HiveGrid-Signature");
const timestamp = request.headers.get("X-HiveGrid-Timestamp");
const payload = await request.text();
if (
!signature ||
!timestamp ||
!verifyWebhookSignature({
secret: process.env.TOOLCTRL_WEBHOOK_SECRET!,
secret: process.env.HIVEGRID_WEBHOOK_SECRET!,
payload,
signature,
timestamp,
@@ -189,10 +188,10 @@ The companion `signWebhookPayload` is exported for tests and webhook senders
that produce signatures in JS land:
```ts
import { signWebhookPayload } from "@toolctrl/api-client-ts";
import { signWebhookPayload } from "@hivegrid/api-client-ts";
const signature = signWebhookPayload({
secret: process.env.TOOLCTRL_WEBHOOK_SECRET!,
secret: process.env.HIVEGRID_WEBHOOK_SECRET!,
payload,
timestamp: Math.floor(Date.now() / 1000),
});
@@ -204,7 +203,7 @@ If the calling context provides `sentry-trace` and/or `baggage` headers, pass
them through via `sentry`:
```ts
createToolctrlClient({
createHiveGridClient({
baseUrl,
sentry: {
trace: getActiveSentryTrace(),
@@ -214,17 +213,17 @@ createToolctrlClient({
```
The SDK forwards both headers verbatim, enabling end-to-end Sentry trace
linking between consumer and toolctrl API.
linking between consumer and hivegrid API.
## Regenerating the client
When the upstream API changes, regenerate locally:
```bash
pnpm --filter @toolctrl/api-client-ts generate-spec
pnpm --filter @toolctrl/api-client-ts generate
pnpm --filter @hivegrid/api-client-ts generate-spec
pnpm --filter @hivegrid/api-client-ts generate
# Or both in one shot:
pnpm --filter @toolctrl/api-client-ts generate:all
pnpm --filter @hivegrid/api-client-ts generate:all
```
The CI workflow `.github/workflows/sdk-codegen.yml` regenerates on every PR
@@ -236,8 +235,8 @@ document.
| Class | When it fires | Notable fields |
| ---------------------- | ------------------------------------------- | --------------------------------------------- |
| `ToolctrlApiError` | API returned a non-retryable HTTP error | `status`, `body`, `requestId` (`x-request-id`) |
| `ToolctrlNetworkError` | Network failure after all retries exhausted | `cause` (the underlying transport error) |
| `HiveGridApiError` | API returned a non-retryable HTTP error | `status`, `body`, `requestId` (`x-request-id`) |
| `HiveGridNetworkError` | Network failure after all retries exhausted | `cause` (the underlying transport error) |
Both inherit from the built-in `Error` so existing `instanceof Error` checks
continue to work.