js-bao-wss-client 2.2.0-alpha.8 → 3.4.0

package/README.md

@@ -17,9 +17,7 @@ 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
 - **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 +122,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 +137,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)
@@ -505,7 +532,7 @@ const client = await bootstrap();
 #### Default behaviors
 
 - `offline` mode is enabled unless you pass `offline: false`.
-- `databaseConfig` defaults to `{ type: "sqljs" }`. Supply a different engine only if you need it.
+- `databaseConfig` defaults to `{ type: "sqljs" }`. Supply a different engine only if you need it. A web app that opens large documents (`documentFormat: 2`) passes `{ type: "opfs", options: { workerURL?, brokerURL?, locateFile? } }` — an OPFS-backed store in a dedicated worker that survives a reload; ordinary documents keep the SQL.js engine underneath. `brokerURL` points at `js-bao/format2-broker`, a small SharedWorker that lets several tabs of the same app share one document's store: one tab hosts the engine and the others reach it through a port the broker hands over. Without it a second tab of the same document is refused. Needs js-bao 0.8.0 or newer; with an older js-bao the client throws `OPFS_ENGINE_UNAVAILABLE`.
 
 ### 2. Listen to Connection Events
 
@@ -567,7 +594,6 @@ The client exposes a buffered analytics queue that batches events, retries on re
 - `client.analytics.logEvent({ action, feature, context_json?, ... })`: enqueue a single event. `context_json` accepts an object (auto-serialized) or a JSON string.
 - `client.analytics.flush()`: attempt to send the queue immediately; also runs automatically on reconnect and right before unload/destroy.
 - `client.analytics.setPlanOverride(plan)` and `.setAppVersionOverride(version)`: stamp metadata onto every subsequent event until you clear or replace it.
-- `client.getLlmAnalyticsContext()`: returns `{ logEvent, isEnabled }` when any LLM auto phases are enabled so higher-level features can coordinate their own analytics.
 
 Queued events are persisted in IndexedDB when offline storage is active, so short offline windows or reloads do not drop data. Everything funnels through the same `analytics.batch` WebSocket channel used by the live event test.
 
@@ -580,9 +606,6 @@ All automatic emitters are on by default; pass `analyticsAutoEvents` when constr
 - `sync_error` (`"sync"`, toggle: `analyticsAutoEvents.syncErrors.enabled`): records the `documentId` and `reason` when flush/send attempts fail (with interval throttling).
 - `blob_upload_started` / `blob_upload_succeeded` / `blob_upload_failed` (`"blobs"`, toggles: `analyticsAutoEvents.blobUploads.{start|success|failure}`): include blob/document identifiers, attempt counts, byte size, and retry details (with truncated error text on failure).
 - `session_end` (`"session"`, toggle: `analyticsAutoEvents.sessionEnd`): emitted on `beforeunload` and `client.destroy()`, including `duration_ms` and exit reason.
-- `prompt_started` / `prompt_succeeded` / `prompt_failed` (`"llm"` or `"gemini"`, toggles: `analyticsAutoEvents.llm.{start|success|failure}` and `analyticsAutoEvents.gemini.{start|success|failure}`): unified prompt lifecycle events emitted by `client.llm.chat()` and `client.gemini.generate()`/`client.gemini.countTokens()`. The `feature` field distinguishes the provider.
-
-When `analyticsAutoEvents.llm` enables any of `start`, `success`, or `failure`, `client.getLlmAnalyticsContext()` becomes non-null so LLM helpers can emit structured events without guessing configuration. `analyticsAutoEvents.gemini` controls `client.getGeminiAnalyticsContext()`, which powers automatic logging inside the Gemini namespace.
 
 **Removed events** (no longer emitted, and their option flags have been removed from `analyticsAutoEvents`): `client_boot` (`boot`), `first_doc_open` (`firstDocOpen`), `first_doc_edit` (`firstDocEdit`), `offline_recovery` (`offlineRecovery`), `service_worker_control` / `service_worker_token_update` (`serviceWorker`), `llm_request_*`, `gemini_request_*`.
 
@@ -593,7 +616,7 @@ const client = await initializeClient({
   ...options,
   analyticsAutoEvents: {
     blobUploads: { start: false, success: true, failure: true },
-    llm: { start: true, success: true, failure: false },
+    sessionEnd: false,
   },
 });
 ```
@@ -1160,6 +1183,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 +1275,20 @@ 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 the whole create vocabulary — `tags`, `metadata` and
+// `documentFormat` — with the same meaning they have on `create()`: applied when
+// the call creates the document. The response echoes what it applied, and omits
+// `documentFormat` for an ordinary document.
+const ledger = await client.documents.createWithAlias({
+  title: "Ledger",
+  alias: { scope: "user", aliasKey: "ledger" },
+  tags: ["ledger", "q3"],
+  metadata: { owner: "finance" },
+  documentFormat: 2,
+});
+console.log(ledger.documentFormat); // 2
+console.log(ledger.tags); // ["ledger", "q3"]
+
 // Attempting to create with an existing alias throws HTTP 409
 try {
   await client.documents.createWithAlias({
@@ -1252,6 +1309,27 @@ try {
 
 Use `createWithAlias()` when you need guaranteed uniqueness based on an alias (e.g., "only one home page per app"). Use regular `create()` + `aliases.set()` when offline support is needed or when the document should be created regardless of alias conflicts.
 
+#### Get-or-Create with Alias
+
+When you want the document to exist rather than to be new — "this user's ledger" — `getOrCreateWithAlias()` is the idempotent form: the first call creates it, every later one returns the same document. It takes the same options, applied only when the call creates the document:
+
+```typescript
+const ledger = await client.documents.getOrCreateWithAlias({
+  title: "Ledger",
+  alias: { scope: "user", aliasKey: "ledger" },
+  tags: ["ledger"],
+  documentFormat: 2,
+});
+
+console.log(ledger.created); // true on the call that made it, false after
+console.log(ledger.documentFormat); // 2 either way
+console.log(ledger.tags); // ["ledger"] on the create; absent afterwards
+```
+
+A stated `documentFormat` is also a statement about a document the alias already names. If the stored format **differs**, the call is refused with `DOCUMENT_FORMAT_MISMATCH` (409) naming the document and both formats, and nothing is created — being handed an ordinary document when you asked for a large one is the mistake this route exists to prevent. If it agrees, the format is echoed. Omit it and an existing binding is answered exactly as it always was.
+
+> All three create routes refuse a top-level body key they do not read, with 400 `VALIDATION_FAILED` and a `details` entry naming it. The typed methods above send only keys the routes read; this reaches you only if you build a request body by hand.
+
 ### Manage Permissions
 
 ```typescript
@@ -1719,888 +1797,138 @@ const user = await client.users.getBasic("u01H...");
 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.
-
-```typescript
-// List available models
-const { models, defaultModel } = await client.llm.models();
-console.log("Default model:", defaultModel);
-
-// Basic chat
-const reply = await client.llm.chat({
-  // model is optional; uses server default when omitted
-  messages: [
-    { role: "system", content: "You are a helpful assistant." },
-    { role: "user", content: "Summarize: Collaborative editing with Yjs." },
-  ],
-  temperature: 0.2,
-  max_tokens: 512,
-  reasoning: {
-    effort: "medium",
-    exclude: false,
-  },
-});
-console.log(reply.content);
-
-// Chat with image attachment (base64-encoded PNG)
-const imageBase64 = await loadImageAsBase64("/path/to/screenshot.png");
-const imageReply = await client.llm.chat({
-  messages: [
-    {
-      role: "system",
-      content: "You analyze screenshots and respond helpfully.",
-    },
-    { role: "user", content: "Describe what you see in this image." },
-  ],
-  attachments: [
-    {
-      type: "image",
-      mime: "image/png",
-      base64: imageBase64,
-    },
-  ],
-});
-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.
-
-```typescript
-// Text generation with optional structured output
-const result = await client.gemini.generate({
-  messages: [
-    {
-      role: "system",
-      parts: [{ type: "text", text: "Reply in JSON with keys title and summary." }],
-    },
-    {
-      role: "user",
-      parts: [{ type: "text", text: "Summarize collaborative editing with Yjs." }],
-    },
-  ],
-  structuredOutput: {
-    responseMimeType: "application/json",
-    responseJsonSchema: {
-      type: "object",
-      properties: {
-        title: { type: "string" },
-        summary: { type: "string" },
-      },
-      required: ["title", "summary"],
-    },
-  },
-});
-console.log(result.message.parts[0].text);
-
-// Multimodal prompt with inline image data
-const screenshot = await loadImageAsBase64("/path/to/screenshot.png");
-await client.gemini.generate({
-  messages: [
-    {
-      role: "user",
-      parts: [
-        { type: "text", text: "Describe this screenshot." },
-        { type: "image", mimeType: "image/png", base64Data: screenshot },
-      ],
-    },
-  ],
-});
-
-// Raw passthrough using Google's payload schema
-const rawPayload = {
-  contents: [
-    {
-      role: "user",
-      parts: [
-        {
-          text: "Summarize this JSON.",
-        },
-        {
-          inline_data: {
-            mimeType: "application/json",
-            data: someBase64Json,
-          },
-        },
-      ],
-    },
-  ],
-};
-const rawResponse = await client.gemini.generateRaw({
-  model: "models/gemini-2.5-flash",
-  body: rawPayload,
-});
-console.log(rawResponse.candidates?.[0]?.content);
-
-// Token usage estimation
-const tokens = await client.gemini.countTokens({
-  model: "models/gemini-2.5-flash",
-  messages: [{ role: "user", parts: [{ type: "text", text: "How many tokens?" }] }],
-});
-console.log(tokens.totalTokens);
-```
-
-### Gemini Configuration & Notes
-
-- `client.gemini` proxies to server-side routes:
-  - `GET /gemini/models` → `client.gemini.models()`
-  - `POST /gemini/generate` → `client.gemini.generate(...)`
-  - `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.
-- 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
-
-```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",
-});
-
-// 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.
-
-### 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:
-
-```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",
-});
-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",
-});
-```
+## Server Functions
 
-If `contextDocId` is omitted, the user's root document is used by default.
+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.
 
-### Waiting for Workflow Completion
+### Invoking a Function
 
-For an async run, `waitFor(runId)` resolves once the run reaches a terminal
-state — no manual subscribe/poll/timeout loop:
+`client.functions.invoke` runs the function inside the request and resolves
+with its result:
 
 ```typescript
-const { runId } = await client.workflows.start({
-  workflowKey: "process-document",
-  input: { action: "analyze" },
+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
 });
 
-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);
-});
-
-// Filter by workflow
-const filtered = await client.workflows.listRuns({
-  workflowKey: "my-workflow",
+const run = await client.functions.start("order-sync", {
+  input: { orderId },
+  runKey: `order-${orderId}`, // a repeat replays the existing run (existing: true)
 });
 
-// Filter by status
-const running = await client.workflows.listRuns({
-  status: "running",
-});
+// Poll once…
+const now = await client.functions.getStatus(run.runId);
+console.log(now.status);
 
-// Filter by document - list runs associated with a specific document
-const docRuns = await client.workflows.listRuns({
-  contextDocId: "doc-123",
+// …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
 });
-
-// Pagination
-const page1 = await client.workflows.listRuns({ limit: 10 });
-if (page1.cursor) {
-  const page2 = await client.workflows.listRuns({
-    limit: 10,
-    cursor: page1.cursor,
-  });
+if (settled.status === "failed") {
+  console.error("order-sync failed:", settled.error?.message);
+} else {
+  console.log(settled.status, settled.output?.confirmedAt);
 }
 
-// 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()
-}
+// Stop a run that is still going.
+await client.functions.terminate({ functionKey: "order-sync", runKey: run.runKey });
 ```
 
-### Terminating a Workflow
+- `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`.
 
-Cancel a running workflow:
+### Channels
 
-```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)
-  }
-}
-```
-
-### Sending File Attachments (PDFs, Images)
-
-Workflows can process files like PDFs and images. Files must be base64-encoded before sending:
+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
-/**
- * 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",
-      },
-    ],
-  },
-});
-```
-
-#### Loading from File Input (Browser)
+// 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;
 
-```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);
-  });
-}
+// 2. Present the grant on the socket the client already has.
+const subscription = await client.subscribeToChannel(
+  `orders:${orderId}`,
+  result.output.grant
+);
 
-// Handle file input
-const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
-fileInput.addEventListener("change", async () => {
-  const file = fileInput.files?.[0];
-  if (!file) return;
-
-  const base64Data = await fileToBase64(file);
-
-  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;
-}
+// Later: leave. Idempotent — the same as client.unsubscribeFromChannel(channel).
+subscription.unsubscribe();
 ```
 
-### Polling for Completion
+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.
 
-If you prefer polling over WebSocket events:
+### Deprecated Client APIs
 
-```typescript
-async function waitForCompletion(
-  client: JsBaoClient,
-  workflowKey: string,
-  runKey: string,
-  timeoutMs = 60000,
-  intervalMs = 2000
-): Promise<any> {
-  const startTime = Date.now();
+These client APIs still work but are deprecated. Each has a server-function
+replacement:
 
-  while (Date.now() - startTime < timeoutMs) {
-    const status = await client.workflows.getStatus({ workflowKey, runKey });
+- `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.
 
-    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);
-```
-
-### Permissions
-
-Control per-user access to databases. Only the database owner can add or remove managers.
-
-```typescript
-// List permissions on a database
-const perms = await client.databases.listPermissions(databaseId);
-
-// Add a user as a manager
-await client.databases.addManager(databaseId, {
-  userId: "user-123",
-});
-
-// Remove a manager
-await client.databases.removeManager(databaseId, "user-123");
-```
-
-> **Deprecated:** `grantPermission()` and `revokePermission()` still work but are deprecated aliases for `addManager()` and `removeManager()`.
-
-### Groups
+## Groups
 
 Groups allow batch permission grants. A group has a `groupType` and `groupId`.
 
@@ -2648,90 +1976,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
@@ -3052,7 +2296,7 @@ await client.me.update({
   avatarUrl: null,
 });
 
-// Upload avatar image (stored in R2, proxied through the API)
+// Upload avatar image (stored by the platform, proxied through the API)
 const imageBlob = await fetch("/path/to/image.png").then((r) => r.blob());
 const { avatarUrl } = await client.me.uploadAvatar(imageBlob, "image/png");
 console.log("New avatar URL:", avatarUrl);