@oberik/sdk 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @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`.