Skip to main content
@gavai/sdk-typescript targets the signed /api/v1/* admin surface — a different base path and a different auth scheme from the bearer-token public API. By the end of this page you will know how to install it, sign every request with HMAC-SHA256, verify response signatures before reading the payload, and map every error class to the failure mode that produced it.
Most integrators want @gavai/sdk, not this package. Reach for @gavai/sdk-typescript only when you need mutual HMAC signing or are building platform tooling against the admin surface.

​
Install

bun add @gavai/sdk-typescript

​
Runtime support

The package has no native dependencies. It uses Web Crypto and globalThis.fetch, so it runs anywhere both are available.

​
Minimal example

Read your workspace identity, invite a member with an auto-minted idempotency key, then invite a second member with a caller-supplied key so the call is safe to retry.
admin.ts
import { GavaiClient } from "@gavai/sdk-typescript";

const client = new GavaiClient(process.env.GAVAI_API_KEY!);

// Read
const me = await client.workspaces.me();

// Write — the SDK mints a UUID v4 idempotency key for you
await client.workspaces.members.invite("acme", {
  email: "alice@example.com",
  role: "member",
});

// Write — caller-supplied key, safe to retry from any client
await client.workspaces.members.invite(
  "acme",
  { email: "bob@example.com", role: "member" },
  { idempotencyKey: "invite-bob-2026-05-10" },
);

​
How signing works

Every request is HMAC-SHA256 signed and sent with the X-Gavai-Signature header. Every response carries an X-Gavai-Response-Signature header, and the SDK verifies it before the promise resolves to the caller. If the signature is missing or fails to verify, the SDK throws GavaiSignatureError and the response payload is never returned. There is no opt-out. The practical effect: by the time you have a result in hand, the server is cryptographically attested. Code downstream of an awaited call can treat the payload as trusted without re-checking.

​
API key format

Keys for this SDK are distinct from the bearer-token keys used by @gavai/sdk.
format
gavai_<env>_<keyid>_<secret>
       |     |       |
       |     |       64 lowercase hex chars (256-bit CSPRNG secret)
       |     12 lowercase hex chars (public lookup id)
       opaque environment slug
Generate keys at https://console.gavai.app/settings/api-keys. Treat the secret like a password — store it in your secret manager, never commit it to git.

​
Constructor options

options.ts
const client = new GavaiClient(apiKey, {
  baseUrl: "https://staging.console.gavai.app",
  fetch: customFetch, // any spec-compliant fetch implementation
});

​
Errors

Every error extends GavaiError. Pattern-match with instanceof to handle a specific failure without swallowing the rest.
retry.ts
import { GavaiRateLimitError } from "@gavai/sdk-typescript/errors";

try {
  await client.workspaces.me();
} catch (err) {
  if (err instanceof GavaiRateLimitError) {
    await sleep(err.retryAfterSec * 1000);
    // retry...
  }
  throw err;
}
A GavaiSignatureError is never safe to retry without investigation — the response could not be authenticated, and a second attempt against the same compromised path will produce the same outcome.

​
Status

Surfaces are stable, but response types are unknown until the companion @gavai/schema/api/responses.ts ships typed schemas. The originating route handler is referenced in JSDoc on each method — check it when you need a concrete shape.

​
Next steps