# @oberik/sdk

TypeScript client for [Oberik](https://oberik.com) — give your product AI over your
customers' own data: retrieval with citations, your own tools, sandboxed compute, files and
media, scheduling.

```bash
npm install @oberik/sdk
```

## Quick start

Your backend mints a short-lived token for one end-user; the SDK asks for a new one when it
expires, so an expiry never surfaces at a call site.

```ts
import { createClient } from "@oberik/sdk";

const ai = createClient({
  // baseUrl defaults to the hosted API; set it for a self-hosted deployment.
  getToken: async ({ expired }) => fetchTokenFromYourBackend({ force: expired }),
});

const res = await ai.chat.send({ message: "How did Q3 revenue trend?", tags: ["finance"] });

res.content;    // grounded answer
res.citations;  // document · page · quote
```

Streaming, which is what you want in a UI:

```ts
const handle = ai.chat.stream(
  { message: input },
  {
    onToken: (_delta, full) => render(full),
    onReasoning: (_delta, full) => showThinking(full),   // reasoning models
    onToolStart: (name) => setStatus(`Running ${name}…`),
    onCitations: (cs) => showSources(cs),
    onAttachments: (files) => offerDownloads(files),
  },
);
const done = await handle.done;
```

A dropped connection resumes the *same run* rather than restarting it, so a closed laptop
lid mid-answer doesn't lose the answer or pay for it twice.

## What's in the box

- **Chat** — blocking or streaming, with citations, unified source pills, guardrail flags
  and `finish_reason`.
- **Your own tools** — register a handler and `chat.run`/`chat.stream` dispatch it and
  resume for you; or drive the pause/resume loop yourself.
- **Documents** — resumable presigned multipart upload straight to storage, ranged
  resumable download, retrieval, chunk inspection, ACLs.
- **Sandboxed compute** — start, pause, resume and reattach a workspace; push and pull
  files.
- **Scheduling, connected sources, audit** — the rest of the API, typed.

Zero dependencies, works in Node 18+ and in the browser, ESM and CommonJS.

## Docs

Full documentation, including how to mint tokens and which capabilities gate what:
**https://oberik.com/docs**

## Development

The client is a single file kept at `client/agent-framework.ts` in the Oberik repository;
`src/index.ts` here is a symlink to it, so the published package, the dashboard's own
playground and the docs all use one source. Building emits ESM, CommonJS and types:

```bash
npm run build     # dist/esm, dist/cjs, .d.ts
npm run check     # asserts the tarball is actually usable before publishing
```

`npm publish` runs both automatically via `prepublishOnly`.