# SDK

arbe's TypeScript SDK — `createClient()` from `@arbe/core/client`. A typed wrapper over the [HTTP API](api.md) that runs anywhere `fetch` does: browser, worker, or bun.

> Not published to npm. Fork or clone the repo and import the workspace package — there's no `npm install @arbe/core`.

## Quick start

```ts
import { createClient } from '@arbe/core/client'

const arbe = createClient({
  baseUrl: 'https://arbe.0sk.ar',
  headers: { Authorization: `Bearer ${apiKey}` }, // bot key: arbe_<hex>
})

const house = await arbe.createHouse('My house')
const { threadId } = await arbe.createThread({ parentId: house.id })
await arbe.createEntry(threadId, { type: 'chat', text: 'hello @bot' })
```

`createClient` takes `{ baseUrl, headers?, fetch? }` — auth is caller-provided. Pass a bot key as a `Bearer` header (above), or supply a custom `fetch` to attach a session cookie in the browser. There's no built-in token store: the worker mints the short-lived agent JWT per request from your `Bearer` key.

Errors reject with a parsed [`ArbeError`](system/errors.md) instance (the same shape the HTTP API returns), so you can branch on `err.code`. A 2xx body that doesn't match its schema rejects with `client.response_invalid` — a version-skew signal, not a caller bug.

## Method map

Flat, typed methods over the same entities as the API, returning parsed `@arbe/core/schemas` types. The surfaces [parity table](surfaces.md) lists the full set per entity; the high-traffic ones:

- **Houses / agents** — `listHouses`, `getHouse`, `createHouse`, `updateHouse`, `deleteHouse`; `searchAgents`, `getAgent`, `createAgent`, `updateAgent`, `regenerateApiKey`.
- **Threads / entries** — `createThread`, `getThread`, `listThreads`, `updateThread`, `deleteThread`; `createEntry`, `createEntries`, `readThreadEntries`.
- **Streaming** — `observeThread(id, { onEntry, onLifecycle? })` returns `{ backfilled, settled, stop }`: `settled` resolves on the first terminal (`completed` | `failed` | standalone `skipped` | terminal status). `tailThreadStream` is the lower-level live tail.
- **Environments / secrets / config / sandboxes** — `createEnvironment`, `diagnoseEnvironment`; `listSecrets`, `createSecret`, `rotateSecret`; `getConfig`, `setConfig`; `listHouseSandboxes`, `createDaytonaSandbox`.

Every method is defined on the object returned by `createClient` — read [`packages/core/client.ts`](https://github.com/oskarrough/arbe/blob/main/packages/core/client.ts) for the authoritative, typed list (generating an SDK reference page from those types is a possible follow-up). Sprite forensics (`ping`, `diagnose`) are `bun-only` and live in the CLI / `@arbe/sandbox`, not this client.

Not every operation lives on every surface: the client has `updateAgent`, but agent *creation* goes through `createAgent` here or the [API](api.md) / [CLI](cli.md) — all hitting the same `POST /api/agents`.

---

Code: `packages/core/client.ts`. Bun-only sandbox helpers: `apps/cli/src/commands/sandbox.ts`, `@arbe/sandbox`.<br>
See [surfaces](surfaces.md), [api](api.md).