js-bao-wss-client 2.2.0-alpha.11 → 2.2.0-alpha.13

package/README.md

@@ -17,9 +17,8 @@ A TypeScript/JavaScript client library for js-bao-wss that provides HTTP APIs an
 - **Token Management**: Proactive refresh in HTTP calls
 - **Analytics**: Buffered event logging API with optional automatic lifecycle events
 - **Blob Storage**: Upload/list/get/downloadUrl/delete per document with offline cache
-- **LLM**: Chat API and model listing _(deprecated — use managed prompts (`client.prompts.execute`) or workflow LLM steps instead)_
-- **Workflows**: Server-side multi-step processes with LLM, delays, and transformations
-- **Workflow Apply**: Single-client claim/confirm flow for applying workflow results to Yjs documents
+- **Server Functions**: Invoke your app's server functions, start and wait on long-running runs, and join the channels they authorize
+- **LLM**: Chat API and model listing _(deprecated — run a managed prompt from a server function (`ctx.prompts.run`) instead)_
 - **Offline-first Open**: Non-blocking open with IndexedDB-backed cache
 - **Offline Blob Cache**: Cache API + IndexedDB backed uploads/reads with eviction and retry
 - **Network Controls**: Online/offline modes, reachability, connection control
@@ -124,9 +123,10 @@ const client = await initializeClient({
   appId: "my-app",
   models: [Task, Project],
 
-  // Yjs document persistence for Node.js
-  yjsPersistence: (docId, ydoc, { appId, userId }) => {
-    return new SqlitePersistence(docId, ydoc, {
+  // Yjs document persistence for Node.js. The first argument is the store
+  // name — see "What the first argument is" below.
+  yjsPersistence: (storeName, ydoc, { appId, userId }) => {
+    return new SqlitePersistence(storeName, ydoc, {
       dbPath: `${process.env.HOME}/.my-app/${appId}/${userId}/yjs.sqlite`
     });
   },
@@ -138,6 +138,34 @@ const { ydoc } = await client.documents.open("doc-123", {
 });
 ```
 
+**What the first argument is**
+
+The factory's first argument is the **store name** to persist this Yjs state
+under, not necessarily the document id. For an ordinary document, and for a
+large document (`documentFormat: 2`) that has not rotated yet, the two are the
+same value.
+
+A large document's Yjs state is an epoch *overlay* rather than the document
+itself, so once it rotates each epoch gets its own store name,
+`{documentId}@{epoch}`. A rotation attaches a provider for the fresh epoch and
+then clears the sealed one, so a factory that put both epochs under one name
+would lose every write made since the rotation to that clear. Keying your
+storage on the first argument — as the example above does — is correct for both
+kinds of document, and needs no change when a document grows large.
+
+The third argument carries the rest of what the store is for:
+
+| Field | Meaning |
+|-------|---------|
+| `appId` | The application id |
+| `userId` | The authenticated user, or `"anon"` |
+| `documentId` | The plain document id, without the epoch suffix |
+| `documentFormat` | `2` for a large document, `1` for an ordinary one — absent on the very first open of a document created elsewhere, whose format nothing local knows yet |
+| `epoch` | The epoch the store name is scoped to, or `null` when the name is the plain document id |
+
+Use `context.documentId` when you want to group every store belonging to one
+document; use the first argument whenever you are naming storage.
+
 **Why two storage systems?**
 
 - `storageConfig` → General key-value data (auth, cache, metadata)
@@ -1160,6 +1188,26 @@ const { metadata } = await client.documents.create({
 });
 console.log("Created document:", metadata.documentId);
 
+// Create a LARGE document (`documentFormat: 2`) — records live in a persisted
+// local store and in the server's own table, so it scales far past an ordinary
+// document's ~10 MB. The choice is made here and is never migrated. The
+// returned metadata reports the format immediately, before the server commit
+// lands, and `documents.get(id).documentFormat` reports it afterwards.
+const large = await client.documents.create({
+  title: "Ledger",
+  documentFormat: 2,
+});
+console.log("Format:", large.metadata.documentFormat); // 2
+
+// Omitting `documentFormat` (or passing `1`) creates an ordinary document and
+// sends nothing extra. Any other value is refused before anything is created,
+// with `JsBaoError` code `INVALID_ARGUMENT`; `localOnly: true` cannot be
+// combined with `documentFormat: 2` (`LOCAL_ONLY_UNSUPPORTED_OPTION`), because
+// a large document's records live in a store only the server's room opens.
+// `documents.createWithAlias` takes the same option with the same effect.
+// A large document needs a local store that outlives the session: Node has
+// one, and a browser needs `databaseConfig: { type: "opfs", ... }`.
+
 // List documents. There are two readers, and they are disjoint: the documents
 // the user owns, and the documents shared with them. Reading both is what it
 // takes to see everything the user has access to.
@@ -1232,6 +1280,16 @@ console.log(result.documentId); // The created document ID
 console.log(result.alias.aliasKey); // "current-draft"
 console.log(result.alias.documentId); // Same as documentId
 
+// The alias create takes `documentFormat` too, so a large document can be
+// created with its alias atomically. The response carries `documentFormat: 2`
+// for a large document and omits the key for an ordinary one.
+const ledger = await client.documents.createWithAlias({
+  title: "Ledger",
+  alias: { scope: "user", aliasKey: "ledger" },
+  documentFormat: 2,
+});
+console.log(ledger.documentFormat); // 2
+
 // Attempting to create with an existing alias throws HTTP 409
 try {
   await client.documents.createWithAlias({
@@ -1721,7 +1779,7 @@ console.log(user.name, user.email, user.appRole);
 
 ## Large Language Models (LLM)
 
-> **Deprecated.** The direct LLM client API (`client.llm.*`) is deprecated and will be removed in a future major release. Use managed prompts (`client.prompts.execute`) or a workflow `llm.chat` step instead.
+> **Deprecated.** The direct LLM client API (`client.llm.*`) is deprecated and will be removed in a future major release. Run a managed prompt from a server function (`ctx.prompts.run`) instead.
 
 ```typescript
 // List available models
@@ -1767,7 +1825,7 @@ console.log(imageReply.content);
 
 ## Gemini
 
-> **Deprecated.** The direct Gemini client API (`client.gemini.*`) is deprecated and will be removed in a future major release. Use managed prompts (`client.prompts.execute`) or a workflow `gemini.generate` step instead.
+> **Deprecated.** The direct Gemini client API (`client.gemini.*`) is deprecated and will be removed in a future major release. Run a managed prompt from a server function (`ctx.prompts.run`) instead.
 
 ```typescript
 // Text generation with optional structured output
@@ -1851,756 +1909,142 @@ console.log(tokens.totalTokens);
   - `POST /gemini/count-tokens` → `client.gemini.countTokens(...)`
   - `POST /gemini/generate-raw` → `client.gemini.generateRaw({ model, body })`
   These endpoints run server-side, so browser clients never see Google credentials.
-- Deployments must configure a Gemini key in the worker environment (`GEMINI_API_KEY`, `GEMINI_API_TOKEN`, or `GEMINI_KEY`). Optional helpers:
-  - `GEMINI_DEFAULT_MODEL` (e.g. `models/gemini-2.5-flash`)
-  - `GEMINI_ALLOWED_MODELS` (comma-separated allowlist such as `models/gemini-2.5-flash,models/gemini-2.5-pro`).
-- Inline multimodal content uses base64 `parts` (text, image, file). Large file uploads can be added later via the Gemini Files API; V1 augments prompts with base64-inlined payloads up to ~25 MB.
+- Inline multimodal content uses base64 `parts` (text, image, file), up to about 25 MB per request.
 - Structured output leverages `generationConfig.responseMimeType` plus optional `responseSchema` / `responseJsonSchema` so Gemini can return deterministic JSON. The full server response is always available via the `raw` field when you need annotations or safety metadata.
 - Error handling surfaces `JsBaoError` with `code: "GEMINI_ERROR"`; the `details` property contains the raw upstream payload so you can log or render troubleshooting info.
-- See `.dev.local.example` for sample environment values and `docs/gemini-direct-plan.md` for architectural details.
-
-## Workflows
-
-Workflows allow you to execute server-side, multi-step processes that can include LLM calls, delays, transformations, and more. The client provides APIs to start workflows, monitor their status, and receive real-time completion events.
-
-### Starting a Workflow
-
-```typescript
-// Start a workflow with input data
-const result = await client.workflows.start({
-  workflowKey: "my-workflow-key",
-  input: {
-    message: "Hello world",
-    value: 42,
-  },
-});
-
-console.log("Run started:", result.runKey);
-console.log("Run ID:", result.runId);
-console.log("Status:", result.status);
-```
 
-#### Start Options
+## Server Functions
 
-```typescript
-const result = await client.workflows.start({
-  // The workflow key (required)
-  workflowKey: "my-workflow-key",
-  // Input data passed to the workflow (optional, defaults to {})
-  input: { message: "Hello" },
-  // Provide a custom runKey for idempotency (auto-generated if omitted)
-  runKey: "unique-run-identifier",
-  // Associate the run with a document
-  contextDocId: "doc-123",
-  // Pass additional metadata (max 1KB, returned in listRuns/getStatus)
-  meta: { source: "user-action", priority: "high" },
-});
-```
-
-### Document-Scoped Workflows
-
-Workflows can be scoped to a specific document using `contextDocId`. This is useful when:
-- Processing document-specific data
-- Running workflows in the context of a particular document
-- Allowing the same `runKey` to be used across different documents
-
-The workflow instance ID is built from `{appId}:{contextDocId}:{runKey}`, so a workflow started with one `contextDocId` cannot be accessed with a different one.
-
-```typescript
-// Start a workflow scoped to a document
-const result = await client.workflows.start({
-  workflowKey: "process-document",
-  input: { action: "analyze" },
-  contextDocId: "doc-123",
-  runKey: "analyze-v1",
-});
+A server function is TypeScript your app's team writes in its config tree and
+pushes with `primitive config push`. The client calls it by key, and the
+function's `access` gate decides who may. Inside, the function works on the
+app's authority: it reads and writes databases and documents, runs saved
+prompts, calls integrations, and publishes to channels. The Server Functions
+guide covers writing one; this section covers calling one.
 
-// Must use the same contextDocId for all operations
-const status = await client.workflows.getStatus({
-  workflowKey: "process-document",
-  runKey: "analyze-v1",
-  contextDocId: "doc-123",
-});
-await client.workflows.terminate({
-  workflowKey: "process-document",
-  runKey: "analyze-v1",
-  contextDocId: "doc-123",
-});
-
-// List runs for this document
-const runs = await client.workflows.listRuns({ contextDocId: "doc-123" });
-```
-
-If `contextDocId` is omitted, the user's root document is used by default.
+### Invoking a Function
 
-### Duplicate Workflow Protection (Idempotency)
-
-When you provide a `runKey`, the server ensures only one workflow run exists for that key. If you call `start()` again with the same `runKey`, the existing run is returned instead of creating a new one:
+`client.functions.invoke` runs the function inside the request and resolves
+with its result:
 
 ```typescript
-// First call creates the workflow
-const first = await client.workflows.start({
-  workflowKey: "process-document",
-  input: { docId: "abc" },
-  runKey: "process-abc-v1",
-});
-console.log(first.existing); // false - new run created
-
-// Second call with same runKey returns existing run
-const second = await client.workflows.start({
-  workflowKey: "process-document",
-  input: { docId: "abc" },
-  runKey: "process-abc-v1",
+const result = await client.functions.invoke<{ message: string }>("greet", {
+  input: { name: "Ada" }, // what the handler receives as `input`
+  timeoutMs: 10_000, // default 5 000, clamped to 30 000
 });
-console.log(second.existing); // true - existing run returned
-console.log(second.runId === first.runId); // true - same run
-```
-
-This is useful for:
-- Preventing duplicate processing when users click a button multiple times
-- Safely retrying failed requests without creating duplicate work
-- Implementing exactly-once semantics for critical operations
-
-### Checking Workflow Status
-
-Poll the status of a running workflow:
-
-```typescript
-const status = await client.workflows.getStatus({
-  workflowKey: "my-workflow-key",
-  runKey,
-});
-
-// One canonical value: "queued" | "running" | "apply_pending" | "apply_claimed"
-// | "completed" | "failed" | "terminated" | "missing" | "skipped"
-console.log("Status:", status.status);
-
-if (status.status === "completed") {
-  console.log("Output:", status.output);
-}
-
-if (status.status === "failed") {
-  console.log("Error:", status.error);
-  // A platform-classified failure also carries a machine-readable code, so you
-  // never have to match `error` text: "LOCK_CONTENTION" | "LOCK_TIMEOUT" | null
-  if (status.run?.errorCode === "LOCK_CONTENTION") {
-    console.log("An import is already in progress");
-  }
-}
-
-if (status.status === "skipped") {
-  // The run did not run and did not fail: its declarative lock was held and the
-  // workflow declared `onContention = "ignore"`. `skipReason` says why.
-  console.log("Did not run:", status.skipReason); // "LOCK_CONTENTION"
-}
-```
-
-If you started the workflow with a specific `contextDocId`, you must provide the same `contextDocId` when checking status:
-
-```typescript
-// Start workflow with contextDocId
-const result = await client.workflows.start({
-  workflowKey: "my-workflow",
-  input: { data: "..." },
-  contextDocId: "doc-123",
-});
-
-// Get status - must provide the same contextDocId
-const status = await client.workflows.getStatus({
-  workflowKey: "my-workflow",
-  runKey: result.runKey,
-  contextDocId: "doc-123",
-});
-```
-
-If `contextDocId` is omitted, the user's root document is used by default.
-
-### Waiting for Workflow Completion
-
-For an async run, `waitFor(runId)` resolves once the run reaches a terminal
-state — no manual subscribe/poll/timeout loop:
-
-```typescript
-const { runId } = await client.workflows.start({
-  workflowKey: "process-document",
-  input: { action: "analyze" },
-});
-
-const result = await client.workflows.waitFor(runId);
-// result: { status, output?, error? }
 
 if (result.status === "completed") {
-  console.log("Output:", result.output);
-} else if (result.status === "failed") {
-  console.log("Error:", result.error); // a failed run RESOLVES — it does not reject
-}
-```
-
-`waitFor` is event-driven: it subscribes to the same `workflowStatus`
-WebSocket frame (no polling) and does a single reconcile fetch right after
-subscribing to catch a run that already finished before you called it. On a
-WebSocket reconnect it re-runs that single reconcile — there is no interval
-timer.
-
-- **Resolves on every terminal state**: `completed`, `failed`, `terminated`,
-  `skipped`, and the apply-ready states `apply_pending` / `apply_claimed` (the
-  run finished and its result is available for the client-side apply step). The
-  server reconciles a run's status before reporting it, so the reported
-  terminal state is the run's real one — a terminated run resolves as
-  `"terminated"`, never as `"completed"`.
-- **`skipped` needs this client at 2.1.0 or newer.** It is the outcome of a run
-  whose declarative lock was held under `onContention = "ignore"`: the run did
-  not run and did not fail, and `result.skipReason` says why
-  (`"LOCK_CONTENTION"`). An older client does not recognise it as terminal, so
-  a wait on an elided run keeps waiting until its own timeout instead of
-  returning — upgrade before you switch a workflow to `ignore`.
-- **Rejects only** on two conditions: the run is unknown or not readable by the
-  caller (a `NOT_FOUND` `JsBaoError`, surfaced immediately — it does not wait
-  for the timeout), or the timeout elapses (a `WORKFLOW_WAIT_TIMEOUT`
-  `JsBaoError`).
-
-```typescript
-import { isJsBaoError } from "js-bao-wss-client";
-
-try {
-  const result = await client.workflows.waitFor(runId, { timeoutMs: 60000 });
-  // ...
-} catch (err) {
-  if (isJsBaoError(err) && err.code === "WORKFLOW_WAIT_TIMEOUT") {
-    // still running after the deadline
-  } else if (isJsBaoError(err) && err.code === "NOT_FOUND") {
-    // unknown or not-owned runId
-  }
+  console.log(result.output?.message); // "hello Ada"
+} else {
+  // "failed" — the handler threw or its output failed outputSchema — or "timeout"
+  console.error(result.status, result.error, result.errorCode);
 }
 ```
 
-The default `timeoutMs` is 15 minutes. Set it to `0` or `Infinity` to disable
-the timeout — but then the returned promise and its listener live until the run
-terminates, so only do this for runs you know will end.
-
-To receive the resolving `workflowStatus` frame promptly you need an active
-WebSocket connection (see [Listening for Workflow
-Events](#listening-for-workflow-events) below); without one, `waitFor` still
-resolves via its reconcile fetch, just less immediately.
-
-### Listening for Workflow Events
-
-Subscribe to real-time workflow events via WebSocket:
-
-```typescript
-// Listen for when a workflow starts
-client.on("workflowStarted", (event) => {
-  console.log("Workflow started:", event.workflowKey, event.runKey);
-  console.log("Instance:", event.instanceId);
-  console.log("Meta:", event.meta);
-});
-
-// Listen for workflow completion/failure
-client.on("workflowStatus", (event) => {
-  console.log("Workflow event:", event.workflowKey, event.runKey);
-  // "completed" | "failed" | "terminated" | "skipped"
-  console.log("Status:", event.status);
-
-  if (event.status === "completed") {
-    console.log("Output:", event.output);
-  }
-
-  if (event.status === "failed") {
-    console.log("Error:", event.error);
-    // Classified failures also carry a code, so you branch on a constant
-    // instead of matching `error` text: "LOCK_CONTENTION" | "LOCK_TIMEOUT".
-    if (event.errorCode === "LOCK_CONTENTION") {
-      console.log("An import is already in progress");
-    }
-  }
-
-  if (event.status === "skipped") {
-    // The run did not run and did not fail: its declarative lock was held and
-    // the workflow declared `onContention = "ignore"`. No `error` is sent.
-    console.log("Did not run:", event.skipReason); // "LOCK_CONTENTION"
-  }
-});
-```
-
-**Note**: To receive workflow events, you must have an active WebSocket connection. Opening a document establishes this connection:
-
-```typescript
-// Open a document to establish WebSocket for receiving notifications
-await client.documents.open(documentId);
-
-// Now workflow events will be delivered
-const result = await client.workflows.start({ workflowKey: "my-workflow", input: { data: "..." } });
-```
-
-#### Event Payload
-
-```typescript
-interface WorkflowStatusEvent {
-  type: "workflowStatus";
-  workflowKey: string;
-  workflowId: string;
-  runKey: string;
-  runId: string;
-  // "skipped" needs this client at 2.1.0 or newer (see Waiting for Workflow
-  // Completion). It is the outcome of a run whose declarative lock was held
-  // and whose workflow declared `onContention = "ignore"`.
-  status: "completed" | "failed" | "terminated" | "skipped";
-  output?: any;
-  error?: string;
-  // Platform classification of a FAILED run. Absent on every other status, and
-  // absent on a failure the platform did not classify.
-  errorCode?: "LOCK_CONTENTION" | "LOCK_TIMEOUT";
-  // Why a "skipped" run did not run. Absent on every other status; a skipped
-  // frame carries no `error`.
-  skipReason?: "LOCK_CONTENTION";
-  contextDocId?: string;
-  needsApply?: boolean; // true when workflow requires client-side apply
-  startedByUserId?: string;
-  meta?: Record<string, any>; // custom metadata passed to workflows.start()
-}
-```
+- `status` is `completed`, `failed`, or `timeout`. All three resolve: the call
+  reached the function and the function has an answer. The promise rejects only
+  when the platform refused before the code ran — the `access` gate or a
+  disabled function (`403`), an unknown key (`404`), a function with no pushed
+  code (`409`), or the rate ceiling (`429`, or `503` when the ceiling cannot be
+  checked).
+- Options are all optional: `input`, `contextDocId` (a document the call is
+  about), `meta` (caller metadata, at most 1 KB encoded), and `timeoutMs`.
+- `invocationId` names the invocation-log record for the call. Pass it to
+  `primitive functions logs <functionId> --invocation <id>` to read what the
+  function printed and the error it threw.
 
-### Listing Workflow Runs
+### Starting a Long-Running Run
 
-View all workflow runs for the current user:
+`client.functions.start` runs the same function as a task: it answers with a
+run id immediately and the code keeps running. Every pushed function accepts
+both `invoke` and `start`; the caller chooses.
 
 ```typescript
-// List all runs
-const runs = await client.workflows.listRuns();
-console.log("Total runs:", runs.items.length);
-
-runs.items.forEach((run) => {
-  console.log(run.runKey, run.status, run.startedAt);
+const run = await client.functions.start("order-sync", {
+  input: { orderId },
+  runKey: `order-${orderId}`, // a repeat replays the existing run (existing: true)
 });
 
-// Filter by workflow
-const filtered = await client.workflows.listRuns({
-  workflowKey: "my-workflow",
-});
+// Poll once…
+const now = await client.functions.getStatus(run.runId);
+console.log(now.status);
 
-// Filter by status
-const running = await client.workflows.listRuns({
-  status: "running",
+// …or wait for a terminal state.
+const settled = await client.functions.waitFor<{ confirmedAt: number }>(run.runId, {
+  timeoutMs: 60_000, // default 15 minutes; throws WORKFLOW_WAIT_TIMEOUT past it
 });
-
-// Filter by document - list runs associated with a specific document
-const docRuns = await client.workflows.listRuns({
-  contextDocId: "doc-123",
-});
-
-// Pagination
-const page1 = await client.workflows.listRuns({ limit: 10 });
-if (page1.cursor) {
-  const page2 = await client.workflows.listRuns({
-    limit: 10,
-    cursor: page1.cursor,
-  });
-}
-
-// Sort order - default is newest first (descending by modifiedAt)
-const newestFirst = await client.workflows.listRuns(); // default
-const oldestFirst = await client.workflows.listRuns({ forward: true });
-
-// Combine filters
-const combined = await client.workflows.listRuns({
-  contextDocId: "doc-123",
-  status: "completed",
-  forward: true,
-  limit: 20,
-});
-```
-
-#### Run Record Fields
-
-```typescript
-type WorkflowRunStatus =
-  | "queued"
-  | "running"
-  | "apply_pending"
-  | "apply_claimed"
-  | "completed"
-  | "failed"
-  | "terminated"
-  | "missing"
-  | "skipped";
-
-interface WorkflowRun {
-  runId: string;
-  runKey: string;
-  instanceId: string;
-  workflowId: string;
-  workflowKey: string;
-  revisionId: string;
-  contextDocId?: string;
-  status: WorkflowRunStatus;
-  startedAt?: string; // ISO timestamp stamped when the run started
-  endedAt?: string;
-  errorMessage?: string | null; // set when status is "failed", null otherwise
-  // The platform's own classification of a failure, when it has one:
-  // "LOCK_CONTENTION" (a declarative lock was held under onContention = "fail")
-  // or "LOCK_TIMEOUT" (an onContention = "block" budget ran out). null for every
-  // unclassified failure. Branch on this rather than on errorMessage text.
-  errorCode?: "LOCK_CONTENTION" | "LOCK_TIMEOUT" | null;
-  // Why a "skipped" run did not run: "LOCK_CONTENTION". null for any other
-  // status. Such a run carries no errorMessage and emits no error analytics.
-  skipReason?: "LOCK_CONTENTION" | null;
-  meta?: Record<string, any>; // custom metadata passed to workflows.start()
+if (settled.status === "failed") {
+  console.error("order-sync failed:", settled.error?.message);
+} else {
+  console.log(settled.status, settled.output?.confirmedAt);
 }
-```
-
-### Terminating a Workflow
-
-Cancel a running workflow:
-
-```typescript
-const result = await client.workflows.terminate({
-  workflowKey: "my-workflow-key",
-  runKey,
-});
-console.log("Terminated, final status:", result.status);
-```
-
-If you started the workflow with a specific `contextDocId`, you must provide the same `contextDocId` when terminating:
-
-```typescript
-// Terminate a workflow started with contextDocId
-const result = await client.workflows.terminate({
-  workflowKey: "my-workflow-key",
-  runKey,
-  contextDocId: "doc-123",
-});
-```
-
-### Applying Workflow Results to Documents
-
-When a workflow completes, its result can be applied to a Yjs document by exactly one connected client. This prevents duplicate writes when multiple tabs or devices are connected to the same document.
-
-Use `workflows.define()` to register an apply handler at initialization. The client automatically claims, applies, and confirms workflow results:
 
-```typescript
-// Define a workflow with its apply handler (call once at startup)
-client.workflows.define("my-workflow-key", {
-  onApply: async ({ output, workflowKey, runKey, contextDocId, meta }) => {
-    // Use models to apply the workflow result to the document
-    const contact = new Contact({
-      name: output.contactName,
-      email: output.contactEmail,
-    });
-    await contact.save({ targetDocument: contextDocId });
-
-    // `meta` contains custom metadata passed to workflows.start()
-    if (meta?.notify) {
-      console.log("Apply completed for", meta.source);
-    }
-  },
-});
-```
-
-**How it works:**
-
-1. Workflow completes → server sets status to `apply_pending`
-2. All connected clients receive a `workflowStatus` event with `needsApply: true`
-3. The first client to call `claimApply` wins (conditional DynamoDB update)
-4. The claiming client runs the registered `onApply` handler
-5. On success, `confirmApply` marks the run as `completed`
-6. On failure, `releaseApply` releases the claim so another client can retry
-7. A 30-second lease timeout handles crashed clients
-8. On reconnect, the server automatically pushes any pending applies — no client-side polling needed
-
-The claim/confirm/release cycle is handled automatically when you use `workflows.define()`. For manual control:
-
-```typescript
-// Manual claim/confirm flow
-const claim = await client.workflows.claimApply({
-  workflowKey: "my-workflow-key",
-  runKey: "run-123",
-  contextDocId: "doc-456",
-});
-
-if (claim.claimed) {
-  try {
-    // Apply result to document...
-    await client.workflows.confirmApply({
-      workflowKey: "my-workflow-key",
-      runKey: "run-123",
-      contextDocId: "doc-456",
-    });
-  } catch (err) {
-    // Release so another client can retry
-    // (handled automatically with workflows.define)
-  }
-}
+// Stop a run that is still going.
+await client.functions.terminate({ functionKey: "order-sync", runKey: run.runKey });
 ```
 
-### Sending File Attachments (PDFs, Images)
-
-Workflows can process files like PDFs and images. Files must be base64-encoded before sending:
+- `runKey` makes the start idempotent per caller and `contextDocId`: repeating
+  it answers the run that already exists, with `existing: true`, instead of
+  starting a second one.
+- `waitFor` settles on `completed`, `failed`, or `terminated`. A failed run
+  resolves with `status: "failed"` and its `error`; it does not reject.
+- `getStatus` is one read. A run id that is not this app's, or does not exist,
+  rejects with `NOT_FOUND`.
 
-```typescript
-/**
- * Load a file and convert to base64.
- * Works in browsers with fetch + FileReader or ArrayBuffer.
- */
-async function loadFileAsBase64(url: string): Promise<string> {
-  const response = await fetch(url);
-  const arrayBuffer = await response.arrayBuffer();
-  const bytes = new Uint8Array(arrayBuffer);
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  return btoa(binary);
-}
-
-// Load a PDF and send to workflow
-const pdfBase64 = await loadFileAsBase64("/path/to/document.pdf");
-
-const result = await client.workflows.start({
-  workflowKey: "extract-pdf-data",
-  input: {
-    attachments: [
-      {
-        data: pdfBase64,
-        type: "application/pdf",
-      },
-    ],
-  },
-});
-```
+### Channels
 
-#### Loading from File Input (Browser)
+A channel delivers what server functions publish to whoever has joined it. A
+function authorizes the caller for one channel with `ctx.channels.authorize`
+and returns the grant; the client presents it with `subscribeToChannel`, and
+every `ctx.channels.publish` to that channel arrives as a `channelMessage`
+event:
 
 ```typescript
-async function fileToBase64(file: File): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onload = () => {
-      const dataUrl = reader.result as string;
-      // Remove the data URL prefix (e.g., "data:application/pdf;base64,")
-      const base64 = dataUrl.split(",")[1];
-      resolve(base64);
-    };
-    reader.onerror = reject;
-    reader.readAsDataURL(file);
-  });
-}
-
-// Handle file input
-const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
-fileInput.addEventListener("change", async () => {
-  const file = fileInput.files?.[0];
-  if (!file) return;
+// 1. Ask the authorizing function for a grant; it names this caller and one channel.
+const result = await client.functions.invoke<{ grant: string; expiresAt: number }>(
+  "order-room",
+  { input: { orderId } }
+);
+if (result.status !== "completed" || !result.output) return;
 
-  const base64Data = await fileToBase64(file);
+// 2. Present the grant on the socket the client already has.
+const subscription = await client.subscribeToChannel(
+  `orders:${orderId}`,
+  result.output.grant
+);
 
-  const result = await client.workflows.start({
-    workflowKey: "process-upload",
-    input: {
-      attachments: [
-        {
-          data: base64Data,
-          type: file.type, // e.g., "image/png", "application/pdf"
-          filename: file.name,
-        },
-      ],
-    },
-  });
+client.on("channelMessage", (event) => {
+  // event.channel, event.payload, event.functionKey, event.sentAt
+  console.log(event.channel, event.payload);
 });
-```
-
-#### Loading from URL (Node.js)
-
-```typescript
-import * as fs from "fs";
-import * as path from "path";
 
-function loadFileAsBase64Sync(filePath: string): string {
-  const buffer = fs.readFileSync(filePath);
-  return buffer.toString("base64");
-}
-
-const pdfPath = path.join(__dirname, "document.pdf");
-const pdfBase64 = loadFileAsBase64Sync(pdfPath);
-
-const result = await client.workflows.start({
-  workflowKey: "analyze-document",
-  input: {
-    attachments: [
-      {
-        data: pdfBase64,
-        type: "application/pdf",
-      },
-    ],
-  },
+// A grant that expired while the socket was down is refused on reconnect —
+// invoke the function again and subscribe again.
+client.on("channelSubscribeFailed", (event) => {
+  console.warn("renew", event.channel, event.message);
 });
-```
-
-### Complete Example: PDF Processing Workflow
-
-```typescript
-import { initializeClient } from "js-bao-wss-client";
-
-async function processPDF(pdfUrl: string) {
-  const client = await initializeClient({
-    apiUrl: "https://api.example.com",
-    wsUrl: "wss://ws.example.com",
-    appId: "my-app",
-    token: "jwt-token",
-    databaseConfig: { type: "sqljs" },
-  });
-
-  // Set up event listener for completion
-  const completionPromise = new Promise<any>((resolve) => {
-    client.on("workflowStatus", (event) => {
-      if (event.status === "completed") {
-        resolve(event.output);
-      }
-    });
-  });
-
-  // Open a document to establish WebSocket connection
-  const { metadata } = await client.documents.create({ title: "temp" });
-  await client.documents.open(metadata.documentId);
-
-  // Load and encode the PDF
-  const response = await fetch(pdfUrl);
-  const arrayBuffer = await response.arrayBuffer();
-  const bytes = new Uint8Array(arrayBuffer);
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  const pdfBase64 = btoa(binary);
-
-  // Start the workflow
-  const result = await client.workflows.start({
-    workflowKey: "extract-pdf-data",
-    input: {
-      attachments: [
-        {
-          data: pdfBase64,
-          type: "application/pdf",
-        },
-      ],
-    },
-  });
-
-  console.log("Workflow started:", result.runKey);
-
-  // Wait for completion (or poll with getStatus)
-  const output = await completionPromise;
-  console.log("Extracted data:", output);
-
-  // Cleanup
-  await client.documents.delete(metadata.documentId);
-  await client.destroy();
-
-  return output;
-}
-```
-
-### Polling for Completion
-
-If you prefer polling over WebSocket events:
-
-```typescript
-async function waitForCompletion(
-  client: JsBaoClient,
-  workflowKey: string,
-  runKey: string,
-  timeoutMs = 60000,
-  intervalMs = 2000
-): Promise<any> {
-  const startTime = Date.now();
-
-  while (Date.now() - startTime < timeoutMs) {
-    const status = await client.workflows.getStatus({ workflowKey, runKey });
-
-    if (status.status === "completed") {
-      return status.output;
-    }
-
-    if (status.status === "failed") {
-      throw new Error(`Workflow failed: ${status.error}`);
-    }
-
-    if (status.status === "terminated") {
-      throw new Error("Workflow was terminated");
-    }
-
-    // Still running, wait and retry
-    await new Promise((r) => setTimeout(r, intervalMs));
-  }
-
-  throw new Error("Workflow timed out");
-}
-
-// Usage
-const result = await client.workflows.start({ workflowKey: "my-workflow", input: { data: "..." } });
-const output = await waitForCompletion(client, "my-workflow", result.runKey);
-```
-
-## Online Databases
-
-Online databases provide schemaless record storage with user permissions, groups, and group-based access control. All database operations are accessed through `client.databases`.
-
-### Database Management
-
-```typescript
-// Create a database
-const db = await client.databases.create({ title: "My Database" });
-console.log(db.databaseId, db.title);
-
-// List databases accessible to the current user
-const databases = await client.databases.list();
-
-// Get database details
-const info = await client.databases.get(databaseId);
-
-// Delete a database (owner only)
-await client.databases.delete(databaseId);
-```
-
-### Connecting to a Database (Record Engine)
-
-Use `connect()` to get a `DoDb` record engine instance for reading and writing records:
-
-```typescript
-const db = client.databases.connect(databaseId);
 
-// Insert a record
-const record = await db.insert("contacts", { name: "Alice", email: "alice@example.com" });
-
-// Query records
-const contacts = await db.query("contacts");
-
-// Update a record
-await db.update("contacts", record.id, { email: "new@example.com" });
-
-// Delete a record
-await db.delete("contacts", record.id);
+// Later: leave. Idempotent — the same as client.unsubscribeFromChannel(channel).
+subscription.unsubscribe();
 ```
 
-### Permissions
-
-Control per-user access to databases. Only the database owner can add or remove managers.
+A membership lasts until the grant's `expiresAt` (epoch milliseconds, also on
+the returned subscription). To keep listening, invoke the authorizing function
+again before then and call `subscribeToChannel` with the new grant; that
+replaces the membership rather than adding a second one.
 
-```typescript
-// List permissions on a database
-const perms = await client.databases.listPermissions(databaseId);
+### Deprecated Client APIs
 
-// Add a user as a manager
-await client.databases.addManager(databaseId, {
-  userId: "user-123",
-});
-
-// Remove a manager
-await client.databases.removeManager(databaseId, "user-123");
-```
+These client APIs still work but are deprecated. Each has a server-function
+replacement:
 
-> **Deprecated:** `grantPermission()` and `revokePermission()` still work but are deprecated aliases for `addManager()` and `removeManager()`.
+- `client.workflows.*` — call a server function: `client.functions.invoke` for a result, or `client.functions.start` / `getStatus` / `waitFor` for a long-running run.
+- `client.prompts.execute` — call a server function that runs the prompt with `ctx.prompts.run`.
+- `client.integrations.call` — call a server function that calls the integration with `ctx.integrations.call`.
+- `client.databases.*` — call a server function that reads and writes records with `ctx.db` and manages databases with `ctx.api.databases`; for live updates, join a channel the function publishes to.
+- `client.cronTriggers.*` — schedule a server function by declaring `[[function.triggers.cron]]` in its config.
 
-### Groups
+## Groups
 
 Groups allow batch permission grants. A group has a `groupType` and `groupId`.
 
@@ -2648,90 +2092,6 @@ await client.groups.removeMember("team", "engineering", { email: "alice@example.
 const memberships = await client.groups.listUserMemberships("user-123");
 ```
 
-### Group Permissions on Databases
-
-Grant database access to an entire group instead of individual users:
-
-```typescript
-// Grant a group permission on a database
-await client.databases.grantGroupPermission(databaseId, {
-  groupType: "team",
-  groupId: "engineering",
-  permission: "read-write",
-});
-
-// List group permissions
-const gperms = await client.databases.listGroupPermissions(databaseId);
-
-// Revoke group permission
-await client.databases.revokeGroupPermission(databaseId, "team", "engineering");
-```
-
-## Integrations API
-
-Proxy HTTP calls through the tenant-specific integrations defined in the admin UI:
-
-```typescript
-const response = await client.integrations.call({
-  integrationKey: "weather-api",
-  method: "GET",
-  path: "/current",
-  query: { city: "San Francisco" },
-  headers: { "X-Debug": "true" },
-});
-
-console.log(response.status);     // Upstream status code
-console.log(response.body);       // JSON returned by the provider
-console.log(response.traceId);    // Proxy trace id (mirrors admin logs)
-console.log(response.durationMs); // Milliseconds spent in the worker
-```
-
-- `integrationKey` – slug chosen in the admin UI. Keys are per-app.
-- `method`, `path`, `query`, `headers`, `body` – forwarded exactly as provided, but the worker enforces the integration’s allowlisted methods/paths, forwarded headers/query params, max body size, and timeout.
-- Success responses include the upstream `status`, `headers`, `body`, optional `traceId`, and `durationMs`.
-
-### Errors
-
-`client.integrations.call` throws `JsBaoError` with rich codes:
-
-- `OFFLINE` – The SDK is forced offline (`networkMode = "offline"`).
-- `ACCESS_DENIED` – Missing/expired JWT.
-- `INTEGRATION_NOT_FOUND` – Integration removed/archived or typo in `integrationKey`.
-- `INTEGRATION_SECRET_MISSING` – Retired. Current servers never emit this code; it is retained for compatibility with older servers.
-- `INTEGRATION_REQUEST_INVALID` – Method/path/query/body violate guard rails (`DISALLOWED_METHOD`, `REQUEST_BODY_TOO_LARGE`, etc.).
-- `INTEGRATION_PROXY_FAILED` – Upstream timeout/5xx. Inspect `error.details.traceId` to correlate with admin logs.
-
-Example handler:
-
-```typescript
-import { isJsBaoError } from "js-bao-wss-client";
-
-try {
-  await client.integrations.call({ integrationKey: "crm", method: "POST", path: "/contacts", body: { email: "hi" } });
-} catch (error) {
-  if (isJsBaoError(error)) {
-    switch (error.code) {
-      case "INTEGRATION_NOT_FOUND":
-        alert("This integration is not available. Contact your admin.");
-        break;
-      case "INTEGRATION_SECRET_MISSING":
-        alert("Configuration incomplete. Try again later.");
-        break;
-      case "INTEGRATION_REQUEST_INVALID":
-        console.error("Request violates integration config", error.details);
-        break;
-      case "INTEGRATION_PROXY_FAILED":
-        console.error("Upstream failed", error.details?.traceId);
-        break;
-      default:
-        throw error;
-    }
-  } else {
-    throw error;
-  }
-}
-```
-
 ## Real-time Collaboration
 
 ### Open and Edit Documents