> ## Documentation Index
> Fetch the complete documentation index at: https://game-narrative.docs.kitefrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Zero-dependency TypeScript client for Node.js, Deno, and browsers.

# TypeScript SDK

Zero-dependency client that works in Node.js 18+, Deno, and modern browsers.
Uses native `fetch` - no axios, no node-fetch, no dependencies.

SDKs are per-pack. This page covers the **shared core** every per-pack
client is built on (`@kitefrost/core`, installed automatically as a
dependency) - auth, transport, and the resources common to every pack. For
pack-specific resources (characters, continuity, dialogue, encounters,
sessions, ...), see your pack's own quickstart and
[API reference](/api-reference).

## Installation

SDKs are per-pack - there is no single `@kitefrost/sdk` package. Install the
one for your pack, e.g.:

<CodeGroup>
  ```bash npm theme={null}
  npm install @kitefrost/game-narrative   # or @kitefrost/ttrpg-gm
  ```

  ```bash yarn theme={null}
  yarn add @kitefrost/game-narrative
  ```

  ```bash pnpm theme={null}
  pnpm add @kitefrost/game-narrative
  ```
</CodeGroup>

See [SDKs overview](overview) for the exact package name per pack, or your pack's own quickstart for a working example.

## Quick Start

```typescript theme={null}
import { GameNarrativeClient } from '@kitefrost/game-narrative';

const client = new GameNarrativeClient({ apiKey: 'sk_your_key_here' });

// every per-pack client exposes the shared core at .core
const health = await client.core.health.check();
console.log(health);  // { status: "ok", version: "..." }
```

All calls are **asynchronous** - every method returns a `Promise`.

## Shared Core Resources

Available as `client.core.<resource>` on every per-pack client.

### Health

```typescript theme={null}
await client.core.health.check();  // liveness probe - no auth required
```

### Auth

```typescript theme={null}
await client.core.auth.whoami();  // introspect the current API key
```

### Projects

```typescript theme={null}
await client.core.projects.list();
await client.core.projects.get(projectId);
await client.core.projects.create({ name: 'my-project' });
```

### API Keys

```typescript theme={null}
await client.core.keys.list();
await client.core.keys.create({ scopes: ['read', 'write'] });
await client.core.keys.revoke(keyId);
```

### Billing

```typescript theme={null}
await client.core.billing.usage();
```

### Events

```typescript theme={null}
// Send a client/telemetry event
await client.core.events.send({ eventType: '...', payload: { ... } });
```

### Context

```typescript theme={null}
await client.core.context.get(projectId);
```

### BYOK (Bring Your Own Key)

```typescript theme={null}
await client.core.byok.list();
await client.core.byok.set({ provider: '...', apiKey: '...' });
```

### Webhooks

```typescript theme={null}
await client.core.webhooks.list();
await client.core.webhooks.create({ url: 'https://your-server.com/hook', events: [...] });
await client.core.webhooks.delete(webhookId);
```

## Error Handling

<Note>
  TypeScript's error class names differ slightly from Python's for the same
  statuses - `KiteFrostApiError` is the base (Python: `KiteFrostError`),
  `KiteFrostAuthError` covers 401/403 (Python: `AuthError`),
  `KiteFrostNotFoundError` covers 404 (Python: `NotFoundError`).
</Note>

```
KiteFrostApiError
├── KiteFrostAuthError      (401/403) - missing, invalid, or under-permissioned API key
├── KiteFrostNotFoundError  (404)     - project/entity/resource not found
├── ValidationError         (422)     - malformed request payload
├── RateLimited             (429)     - too many requests; check .retryAfter
└── ServerError             (5xx)     - unexpected server error
```

All errors carry `statusCode`, `message`, and `feedbackId`. There is no
automatic retry beyond a one-shot re-auth on a 401. On `RateLimited`, back
off yourself using `.retryAfter` (seconds, may be `undefined`):

```typescript theme={null}
import { RateLimited, ValidationError, KiteFrostApiError } from '@kitefrost/core';

try {
  await client.core.projects.create({ name: 'my-project' });
} catch (error) {
  if (error instanceof RateLimited) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.log(`Bad request: ${error.message}`);
  } else if (error instanceof KiteFrostApiError) {
    console.log(`API error ${error.statusCode}: ${error.message}`);
    if (error.feedbackId) {
      console.log(`Feedback reference: ${error.feedbackId}`);
    }
  }
}
```

See [Telemetry & Privacy](../core-concepts/telemetry) for what `feedbackId` is and how to use it.

## Source

The core is at `sdk/typescript/packages/core/` and per-pack clients at
`sdk/typescript/packages/<pack>/` in the main repository.