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

# TypeScript SDK

> Use @wazoo/client to manage Wazoo platform resources.

`@wazoo/client` is the primary TypeScript SDK for the
[Wazoo Platform API](/platform/api). It provides a typed interface for managing
your Wazoo infrastructure: provisioning Worlds, managing API tokens (`wzp_` and
`wzw_`), and tracking resource usage and billing.

## Install

<CodeGroup>
  ```bash npm theme={null}
  npx jsr add @wazoo/client
  ```

  ```bash deno theme={null}
  deno add jsr:@wazoo/client
  ```

  ```bash pnpm theme={null}
  pnpm dlx jsr add @wazoo/client
  ```

  ```bash yarn theme={null}
  yarn dlx jsr add @wazoo/client
  ```

  ```bash bun theme={null}
  bunx jsr add @wazoo/client
  ```
</CodeGroup>

## Quickstart

```typescript theme={null}
import { listWorlds } from "@wazoo/client";

// Connects to https://api.wazoo.dev and reads process.env.WAZOO_PLATFORM_TOKEN out of the box
const { data, error } = await listWorlds();
console.log(data?.worlds);
```

Platform tokens require the `wzp_` prefix.

## Worlds

```typescript theme={null}
import {
  listWorlds,
  createWorld,
  getWorld,
  updateWorld,
  deleteWorld,
} from "@wazoo/client";

// List active worlds
const { data } = await listWorlds();
console.log(data?.worlds);

// Create a world
const created = await createWorld({
  body: {
    worldId: "support-knowledge",
    world: { displayName: "Support Knowledge", region: "auto" },
  },
});

// Get a world by ID
const world = await getWorld({
  path: { worldId: "support-knowledge" },
});

// Update display name
await updateWorld({
  path: { worldId: "support-knowledge" },
  body: {
    updateMask: "displayName",
    world: { displayName: "Support Knowledge Base" },
  },
});

// Soft-delete (recoverable for 30 days)
await deleteWorld({ path: { worldId: "support-knowledge" } });
```

Creating a platform world provisions a per-World Turso database. Use
`worlds-api.wazoo.dev` or [`@worlds/client`](/projects/worlds) for graph data
operations inside that world.

## Platform API tokens

```typescript theme={null}
import {
  listPlatformTokens,
  createPlatformToken,
  deletePlatformToken,
} from "@wazoo/client";

// List tokens
const { data } = await listPlatformTokens();

// Create a token (secret shown once)
const created = await createPlatformToken({
  body: {
    name: "my-read-token",
    scope: "users.read worlds.read usage.read",
  },
});
console.log(created.data?.token); // wzp_...

// Revoke a token by name
await deletePlatformToken({ path: { tokenName: "my-read-token" } });
```

## World auth tokens

World data-plane tokens use the `wzw_` prefix. They are scoped to a single
namespace and optionally a single world.

```typescript theme={null}
import {
  listWorldTokens,
  createWorldToken,
  deleteWorldToken,
} from "@wazoo/client";

const { data } = await listWorldTokens({
  path: { worldId: "support-knowledge" },
});

const created = await createWorldToken({
  path: { worldId: "support-knowledge" },
});
console.log(created.data?.token); // one-time secret

await deleteWorldToken({
  path: { worldId: "support-knowledge", tokenUid: created.data!.token.uid },
});
```

## Usage and limits

```typescript theme={null}
import { getWorldUsage, getWorldLimits } from "@wazoo/client";

const usage = await getWorldUsage({
  path: { worldId: "support-knowledge" },
});
console.log(usage.data?.usage.total);

const limits = await getWorldLimits({
  path: { worldId: "support-knowledge" },
});
```

## Billing

```typescript theme={null}
import { getWorldBilling } from "@wazoo/client";

const billing = await getWorldBilling({
  path: { worldId: "support-knowledge" },
});
console.log(billing.data?.billing.state);
```

## Custom client configuration

By default, SDK functions automatically use the built-in client. You can
configure global defaults or create isolated custom client instances:

```typescript theme={null}
import { client, createClient, listWorlds } from "@wazoo/client";

// Configure default client globally (e.g. set global headers or custom token)
client.setConfig({
  auth: process.env.CUSTOM_PLATFORM_TOKEN,
});

// Or create an isolated client instance for multi-tenant setups
const customClient = createClient({
  baseUrl: "https://api.wazoo.dev",
  auth: "wzp_custom_token",
});

const { data } = await listWorlds({ client: customClient });
```

## Error handling

The SDK returns a discriminated union by default:

```typescript theme={null}
const r = await listWorlds();
if (r.error) {
  console.error(r.error.error.code, r.error.error.message);
} else {
  console.log(r.data?.worlds);
}
```

Set `throwOnError: true` on the client for exception-based handling.

## Runtime

The SDK is a fetch-based ESM package published on JSR. It runs in any modern
JavaScript runtime that provides `fetch`: Node.js, Cloudflare Workers, Deno,
Bun, and browsers.