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

# TypeScript SDK

> Install, authenticate, and use the Sazabi TypeScript SDK (@sazabi/sdk) — threads, logs, issues, streaming, and device authorization.

The Sazabi TypeScript SDK (`@sazabi/sdk`) is a typed client for the Sazabi API. It wraps every operation — threads, logs, issues, projects, and more — and adds streaming transports and device-authorization helpers. It is an ES-module package for server-side JavaScript and TypeScript.

For browser telemetry, use the [browser SDK](https://docs.sazabi.com/reference/browser-sdk.md) instead — it sends data with a public key, whereas this SDK reads and writes the API with a secret key.

## Install

```bash theme={"system"}
npm install @sazabi/sdk
```

## Create a client

Construct a client with `createClient`. Provide a `credentialProvider` whose `getToken()` returns your secret key (the SDK adds the `Bearer` prefix itself), and optionally the active organization and project:

```ts title="client.ts" theme={"system"}
import { createClient } from "@sazabi/sdk";

export const sazabi = createClient({
  credentialProvider: {
    getToken: () => process.env.SAZABI_SECRET_KEY!,
  },
});
```

Options:

| Option | Required | Purpose |
| - | - | - |
| `credentialProvider` | Yes | Supplies `getToken()` (your secret key, without a `Bearer` prefix) and optional `getOrganizationId()` / `getProjectId()`. |
| `apiBaseUrl` | No | Overrides the API base URL. Defaults to the production API. |
| `intakeBaseUrl` | No | Overrides the log intake base URL used by `logs.forward`. |
| `fetch` | No | A custom `fetch` implementation. |

Create the secret key in the dashboard under [**Settings > Secret keys**](https://app.sazabi.com/settings/secret-keys) (or with `sazabi secret-keys create <name>`), and read it from an environment variable — never hard-code it.

## Core usage

The client groups operations into namespaces. A few common ones:

### Threads

```ts theme={"system"}
// Start an agent thread and wait for the run to finish.
const handle = await sazabi.threads.create({
  message: "Why did checkout error spike?",
});
const run = await handle.waitForCompletion();

// List and fetch threads.
const { threads } = await sazabi.threads.list();
const thread = await sazabi.threads.get({ threadId: threads[0].id });
```

`threads.create` and `messages.append` start long-running agent work and return a deferred handle; call `waitForCompletion()` (or `poll()`) to get the run.

### Logs

```ts theme={"system"}
// Ask a natural-language question. Returns a plain-language `answer`, an
// `explanation` of what was measured over which window, and a `queryId`.
// `results: true` adds the rows, value, table or series the answer was written from.
// A question is at most 2,000 characters. It is answered, or reported as taking too
// long (a 504), within about a minute; the SDK sets no timeout of its own, so pass a
// `fetch` that aborts (for example with `AbortSignal.timeout`) to bound a call.
const asked = await sazabi.logs.ask({
  question: "Which checkout errors happened in the last hour?",
  results: true,
});

// Run the same query again with no model. Without a `window` it reads the
// same times the answer read; a relative window ends now, so this asks the
// same question over the last day. Each run returns its own `queryId`. A
// `not_found` answer has a `queryId` too; it is absent only when nothing was
// planned, as for a question refused with `rejection.code` `not_about_logs`
// or `other_project`.
if (asked.queryId) {
  const rerun = await sazabi.logs.executeQuery({
    queryId: asked.queryId,
    window: { kind: "relative", lookbackSeconds: 86400 },
    limit: 100,
  });
}

// Or run a log query spec you write, with no model: which lines, grouped by
// what, measured how. The window defaults to the last hour; the reply's
// `queryId` runs it again later.
const perService = await sazabi.logs.executeQuery({
  spec: {
    version: 2,
    predicate: { op: "and", children: [] },
    dimensions: [{ kind: "service" }],
    measure: { op: "count" },
    output: "table",
  },
  window: { kind: "relative", lookbackSeconds: 21600 },
});
```

### Issues

```ts theme={"system"}
const { issues } = await sazabi.issues.list();
const issue = await sazabi.issues.get({ issueId: issues[0].id });
await sazabi.issues.resolve({ issueId: issue.id });
```

## Streaming transports

The SDK streams live data over async iterables. Each returns an object you can iterate with `for await`, and close when you are done.

```ts theme={"system"}
// Stream agent events for a run.
const stream = await sazabi.runs.stream({ runId });
for await (const event of stream) {
  // handle event
}
await stream.close();
```

| Transport | Method | Streams |
| - | - | - |
| Agent run events | `runs.stream({ runId })` | Live agent events for a run. |
| Agent thread events | `threads.stream({ threadId })` | Live agent events for a thread's active run. |
| Log forward | `logs.forward({ publicKey, logs })` | Forwards OTLP log records into intake. |

The agent-event streams expose a `cursor`; pass it back on reconnect to resume where you left off.

## Device authorization

For interactive tools that sign a user in without a pre-provisioned key, the SDK exposes the device-authorization flow:

```ts theme={"system"}
import { startDeviceAuthorization, pollDeviceAuthorization } from "@sazabi/sdk";

const start = await startDeviceAuthorization();
// Show start.verificationUriComplete to the user, then poll:
const result = await pollDeviceAuthorization({ deviceCode: start.deviceCode });
if (result.status === "authorized") {
  // result.accessToken is now usable as the credential.
}
```

`pollDeviceAuthorization` reports `pending`, `authorized`, `denied`, or `expired`. Poll on the interval the start response returns until the status is terminal.

## Further reading

> [card] [API reference](https://docs.sazabi.com/reference/api.md)
>
> Every operation the SDK wraps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.