Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
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.
|
||||
Reference in new issue
Block a user