@starcite/sdk 0.0.3 → 0.0.5

package/README.md

@@ -2,262 +2,324 @@
 
 TypeScript SDK for [Starcite](https://starcite.ai), built for multi-agent systems.
 
-Built for teams where multiple producers need shared, ordered context.
+If you need a single ordered session stream across multiple producers, this is the SDK you use.
 
-`@starcite/sdk` helps you:
+## Install
 
-- listen and monitor what multiple agents are doing,
-- keep frontend state consistent with a single ordered event source,
-- replay history and continue sessions reliably.
+```bash
+npm install @starcite/sdk
+```
 
-Typical flow:
+## Runtime Requirements
 
-1. create a session
-2. list sessions when needed
-3. append ordered events
-4. tail from a cursor over WebSocket
+- Node.js 22+ (or Bun / modern runtime with `fetch` + `WebSocket`)
+- Starcite base URL (for example `https://<your-instance>.starcite.io`)
+- API key JWT for backend flows
+- Session token JWTs for frontend/session-scoped flows
 
-For multi-agent systems:
+The SDK normalizes the API URL to `/v1` automatically.
 
-- a) listen and monitor all producers in real time,
-- b) keep frontend consistency by reading from the same ordered stream.
+## The Core Model
 
-## Install
+- `Starcite`: tenant-scoped client
+- `StarciteIdentity`: `user` or `agent` principal tied to tenant
+- `StarciteSession`: session-scoped handle for append/tail/consume/live-sync
 
-```bash
-npm install @starcite/sdk
-```
+The key split:
 
-## Requirements
+- backend: construct `Starcite` with `apiKey`
+- frontend: construct `Starcite` without `apiKey`, bind with `session({ token })`
 
-- Node.js 22+, Bun, or any modern runtime with `fetch` and `WebSocket`
-- Your Starcite Cloud instance URL (`https://<your-instance>.starcite.io`)
-- Your Starcite API key / service JWT
+## How You Use This SDK
 
-The SDK normalizes the base URL to `/v1` automatically.
+This is the practical shape teams end up using in production.
 
-## Quick Start
+### A) Agent Backend (worker/service)
+
+Use the identity flow. This creates or binds a session and mints a session token.
 
 ```ts
-import { createStarciteClient } from "@starcite/sdk";
+import { InMemoryCursorStore, Starcite } from "@starcite/sdk";
 
-const client = createStarciteClient({
-  baseUrl: process.env.STARCITE_BASE_URL ?? "https://<your-instance>.starcite.io",
+const starcite = new Starcite({
+  baseUrl: process.env.STARCITE_BASE_URL,
   apiKey: process.env.STARCITE_API_KEY,
 });
 
-const session = await client.create({
-  id: "ses_demo",
-  title: "Draft contract",
-  metadata: { tenant_id: "acme" },
+// Use a persistent store in production
+const cursorStore = new InMemoryCursorStore();
+
+export async function runPlanner(prompt: string, sessionId?: string) {
+  const planner = starcite.agent({ id: "planner" });
+
+  const session = await starcite.session({
+    identity: planner,
+    id: sessionId,
+    title: "Planning session",
+    metadata: { workflow: "planner" },
+  });
+
+  await session.append({ text: `Planning started: ${prompt}` });
+
+  await session.consume({
+    cursorStore,
+    reconnectPolicy: { mode: "fixed", initialDelayMs: 500, maxAttempts: 20 },
+    handler: async (event) => {
+      if (event.type === "content") {
+        // Your business logic here.
+      }
+    },
+  });
+
+  await session.append({ text: "Planning complete." });
+
+  return {
+    sessionId: session.id,
+    sessionToken: session.token, // hand off to UI when needed
+  };
+}
+```
+
+### B) User Frontend (browser)
+
+Do not use API keys in browser code. Your backend mints a per-session token and sends it to the UI.
+
+```ts
+import { Starcite } from "@starcite/sdk";
+
+const starcite = new Starcite({
+  baseUrl: import.meta.env.VITE_STARCITE_BASE_URL,
 });
 
-await session.append({
-  agent: "researcher",
-  producerId: "producer:researcher",
-  producerSeq: 1,
-  text: "Found 8 relevant cases.",
+const { token } = await fetch("/api/chat/session", {
+  method: "POST",
+}).then((res) => res.json());
+
+const session = starcite.session({ token });
+
+const stopEvents = session.on("event", (event) => {
+  // Replay + live events from canonical ordered session log.
+  renderEvent(event);
 });
 
-await session.append({
-  agent: "drafter",
-  producerId: "producer:drafter",
-  producerSeq: 1,
-  text: "Drafted clause 4.2 with references.",
+session.on("error", (error) => {
+  console.error("Session live-sync error", error);
 });
 
-for await (const event of session.tail({ cursor: 0 })) {
-  const actor = event.agent ?? event.actor;
-  const text =
-    event.text ?? (typeof event.payload.text === "string" ? event.payload.text : "");
+await session.append({
+  text: "Can you summarize the last 3 updates?",
+  source: "user",
+});
 
-  console.log(`[${actor}] ${text}`);
-}
+// cleanup on unmount/navigation
+stopEvents();
+session.disconnect();
 ```
 
-## Authentication
+### C) Admin Panel (ops/audit)
+
+Typical split:
 
-Use your service JWT/API key once at client creation. The SDK injects
-`Authorization: Bearer <token>` for all HTTP calls and WebSocket tail upgrades.
+1. Backend lists sessions using API key.
+2. Backend mints an admin viewer token for a selected session.
+3. Frontend binds with `session({ token })` and tails/replays safely.
+
+Backend:
 
 ```ts
-import { createStarciteClient } from "@starcite/sdk";
+import { Starcite } from "@starcite/sdk";
 
-const client = createStarciteClient({
-  baseUrl: process.env.STARCITE_BASE_URL ?? "https://<your-instance>.starcite.io",
+const starcite = new Starcite({
+  baseUrl: process.env.STARCITE_BASE_URL,
   apiKey: process.env.STARCITE_API_KEY,
+  authUrl: process.env.STARCITE_AUTH_URL,
 });
-```
 
-Token refresh is not built in. If a key is revoked/rotated and requests start
-returning `401`, create a new client with the replacement key and reconnect
-tails from your last processed cursor.
+export async function listSessionsForAdmin() {
+  return await starcite.listSessions({ limit: 50 });
+}
+
+export async function mintAdminViewerToken(sessionId: string) {
+  const response = await fetch(
+    `${process.env.STARCITE_AUTH_URL}/api/v1/session-tokens`,
+    {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${process.env.STARCITE_API_KEY}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        session_id: sessionId,
+        principal: { type: "user", id: "admin:dashboard" },
+        scopes: ["session:read"],
+      }),
+    }
+  );
+
+  if (!response.ok) {
+    throw new Error(`Failed to mint admin token: ${response.status}`);
+  }
 
-## List Sessions
+  return (await response.json()) as { token: string; expires_in: number };
+}
+```
+
+Frontend admin inspector:
 
 ```ts
-const page = await client.listSessions({
-  limit: 20,
-  metadata: { tenant_id: "acme" },
+import { Starcite } from "@starcite/sdk";
+
+const starcite = new Starcite({
+  baseUrl: import.meta.env.VITE_STARCITE_BASE_URL,
 });
 
-for (const session of page.sessions) {
-  console.log(session.id, session.title, session.created_at);
-}
+export async function inspectSession(sessionId: string) {
+  const { token } = await fetch(`/admin/api/sessions/${sessionId}/viewer-token`).then(
+    (res) => res.json()
+  );
 
-console.log("next cursor:", page.next_cursor);
-```
+  const session = starcite.session({ token });
 
-## Append Modes
+  const stop = session.on("event", (event) => {
+    appendAuditRow(event);
+  });
 
-Every append requires producer identity fields:
+  session.on("error", (error) => {
+    showBanner(`Stream error: ${error.message}`);
+  });
 
-- `producerId`: stable producer identifier (for example `producer:drafter`)
-- `producerSeq`: per-producer positive sequence number (1, 2, 3, ...)
+  return () => {
+    stop();
+    session.disconnect();
+  };
+}
+```
 
-High-level append:
+## Public API (Current)
 
 ```ts
-await client.session("ses_demo").append({
-  agent: "drafter",
-  producerId: "producer:drafter",
-  producerSeq: 1,
-  text: "Reviewing clause 4.2...",
-});
-```
+import {
+  MemoryStore,
+  Starcite,
+  type AppendResult,
+  type SessionEvent,
+  type SessionStore,
+  type StarciteWebSocket,
+} from "@starcite/sdk";
 
-Raw append:
+// ── Construction ────────────────────────────────────────────────────────────
 
-```ts
-await client.session("ses_demo").appendRaw({
-  type: "content",
-  actor: "agent:drafter",
-  producer_id: "producer:drafter",
-  producer_seq: 3,
-  payload: { text: "Reviewing clause 4.2..." },
-  idempotency_key: "req-123",
-  expected_seq: 3,
+const starcite = new Starcite({
+  apiKey: process.env.STARCITE_API_KEY, // required for server-side session creation
+  baseUrl: process.env.STARCITE_BASE_URL, // default: STARCITE_BASE_URL or http://localhost:4000
+  authUrl: process.env.STARCITE_AUTH_URL, // overrides iss-derived auth URL for token minting
+  fetch: globalThis.fetch,
+  websocketFactory: (url) => new WebSocket(url),
+  store: new MemoryStore(), // cursor + event persistence (default: MemoryStore)
 });
-```
 
-## Tail Options
+// WebSocketFactory — simplified, auth is always in access_token query string.
+type WebSocketFactory = (url: string) => StarciteWebSocket;
 
-```ts
-const session = client.session("ses_demo");
-const controller = new AbortController();
-
-setTimeout(() => controller.abort(), 5000);
-
-for await (const event of session.tail({
-  cursor: 0,
-  agent: "drafter",
-  reconnect: true,
-  reconnectDelayMs: 3000,
-  signal: controller.signal,
-})) {
-  console.log(event);
-}
-```
+// ── Identities (server-side, require apiKey) ───────────────────────────────
 
-`tail()` replays `seq > cursor`, streams live events, and automatically reconnects
-on transport failures while resuming from the last observed `seq`.
+const alice = starcite.user({ id: "u_123" });
+const bot = starcite.agent({ id: "planner" });
 
-- Set `reconnect: false` to disable automatic reconnect behavior.
-- By default, reconnect retries continue until the stream is aborted or closes gracefully.
-- Use `reconnectDelayMs` to control retry cadence for spotty networks.
+// ── Sessions ────────────────────────────────────────────────────────────────
 
-## Browser Restart Resilience
+// Server-side: creates session + mints token (async)
+const aliceSession = await starcite.session({ identity: alice });
+const botSession = await starcite.session({
+  identity: bot,
+  id: aliceSession.id,
+});
 
-`tail()` reconnects robustly for transport failures, but browser refresh/crash
-resets in-memory state. Persist your last processed `seq` and restart from it.
+// Client-side: wraps existing JWT (sync, no network calls)
+const session = starcite.session({ token: "<jwt>" });
 
-```ts
-const sessionId = "ses_demo";
-const cursorKey = `starcite:${sessionId}:lastSeq`;
+// ── Session properties ──────────────────────────────────────────────────────
 
-const rawCursor = localStorage.getItem(cursorKey) ?? "0";
-let lastSeq = Number.parseInt(rawCursor, 10);
+session.id; // string
+session.token; // string
+session.identity; // StarciteIdentity
+session.log; // SessionLog — canonical source of truth
 
-if (!Number.isInteger(lastSeq) || lastSeq < 0) {
-  lastSeq = 0;
-}
+// ── Session log ─────────────────────────────────────────────────────────────
 
-for await (const event of client.session(sessionId).tail({
-  cursor: lastSeq,
-  reconnect: true,
-  reconnectDelayMs: 3000,
-})) {
-  // Process event first, then persist cursor when your side effects succeed.
-  await renderOrStore(event);
-  lastSeq = event.seq;
-  localStorage.setItem(cursorKey, `${lastSeq}`);
-}
-```
+session.log.events; // readonly SessionEvent[] — ordered by seq, no gaps
+session.log.cursor; // number — highest applied seq
 
-This pattern protects against missed events across browser restarts. Design your
-event handler to be idempotent by `seq` to safely tolerate replays.
+// ── Append ──────────────────────────────────────────────────────────────────
 
-## Error Handling
+await session.append({ text: "hello" });
+await session.append({ payload: { ok: true }, type: "custom", source: "user" });
+// -> Promise<AppendResult> = { seq: number, deduped: boolean }
 
-```ts
-import {
-  StarciteApiError,
-  StarciteConnectionError,
-  createStarciteClient,
-} from "@starcite/sdk";
+// ── Subscribe ───────────────────────────────────────────────────────────────
 
-const client = createStarciteClient({
-  baseUrl: process.env.STARCITE_BASE_URL ?? "https://<your-instance>.starcite.io",
-  apiKey: process.env.STARCITE_API_KEY,
+// Late subscribers get synchronous replay of log.events, then live events.
+// WS connects lazily on first subscriber, disconnects when all leave.
+const unsub = session.on("event", (event) => {
+  console.log(event.seq);
 });
 
-try {
-  await client.create();
-} catch (error) {
-  if (error instanceof StarciteApiError) {
-    console.error(error.status, error.code, error.message);
-  } else if (error instanceof StarciteConnectionError) {
-    console.error(error.message);
-  } else {
-    throw error;
-  }
-}
+// Fatal errors only (for example token expiry). Transient drops auto-reconnect.
+const unsubErr = session.on("error", (error) => {
+  console.error(error.message);
+});
+
+unsub();
+unsubErr();
+
+// ── Teardown ────────────────────────────────────────────────────────────────
+
+session.disconnect(); // stops WS immediately, removes all listeners
 ```
 
-## API Surface
-
-- `createStarciteClient(options?)`
-- `starcite` (default client instance)
-- `StarciteClient`
-  - `create(input?)`
-  - `createSession(input?)`
-  - `listSessions(options?)`
-  - `session(id, record?)`
-  - `appendEvent(sessionId, input)`
-  - `tailEvents(sessionId, options?)`
-  - `tailRawEvents(sessionId, options?)`
-- `StarciteSession`
-  - `append(input)`
-  - `appendRaw(input)`
-  - `tail(options?)`
-  - `tailRaw(options?)`
+## Tail Reliability Controls
+
+`SessionTailOptions` supports:
+
+- `cursor`, `batchSize`, `agent`
+- `follow`, `reconnect`, `reconnectPolicy`
+- `connectionTimeoutMs`, `inactivityTimeoutMs`
+- `maxBufferedBatches`
+- `signal`
+- `onLifecycleEvent`
+
+This is designed for robust reconnect + resume semantics in long-running multi-agent workflows.
+
+## Session Stores
+
+`new Starcite({ store })` accepts a `SessionStore` for cursor + retained-event
+persistence across session rebinds.
+
+- Default: `MemoryStore`
+- Bring your own by implementing:
+  - `load(sessionId)`
+  - `save(sessionId, { cursor, events })`
+  - optional `clear(sessionId)`
+
+## Error Types You Should Handle
+
+- `StarciteApiError` for non-2xx responses
+- `StarciteConnectionError` for transport/JSON issues
+- `StarciteTailError` for streaming failures
+- `StarciteTokenExpiredError` when close code `4001` is observed
+- `StarciteRetryLimitError` when reconnect budget is exhausted
+- `StarciteBackpressureError` when consumer buffering limits are exceeded
 
 ## Local Development
 
 ```bash
 bun install
 bun run --cwd packages/typescript-sdk build
-bun run --cwd packages/typescript-sdk test
-```
-
-Optional reconnect soak test (runs ~40s, disabled by default):
-
-```bash
-STARCITE_SDK_RUN_SOAK=1 bun run --cwd packages/typescript-sdk test -- test/client.reconnect.integration.test.ts
+bun run --cwd packages/typescript-sdk check
+bun run --cwd packages/typescript-sdk check:browser:all
 ```
 
 ## Links
 
-- Product docs and examples: https://starcite.ai
-- API contract: https://github.com/fastpaca/starcite/blob/main/docs/api/rest.md
-- WebSocket tail docs: https://github.com/fastpaca/starcite/blob/main/docs/api/websocket.md
+- Product: <https://starcite.ai>
+- Repository: <https://github.com/fastpaca/starcite-clients>