js-bao-wss-client 2.0.3 → 2.0.5

package/README.md

@@ -345,6 +345,9 @@ async function testSync() {
 # Core (always required)
 npm install js-bao-wss-client yjs lib0 js-bao
 
+# WebSocket transport (required in Node.js — the browser uses the global WebSocket)
+npm install ws
+
 # For SQLite storage (optional, recommended for persistence)
 npm install better-sqlite3
 
@@ -352,7 +355,82 @@ npm install better-sqlite3
 npm install y-sqlite3
 ```
 
-Note: `better-sqlite3` and `y-sqlite3` are native modules requiring compilation. If you encounter build issues, ensure you have the appropriate build tools installed (Python, C++ compiler).
+Note: `ws`, `better-sqlite3`, and `y-sqlite3` are declared as **optional peer
+dependencies**. In Node.js the client connects over WebSocket via `ws` (it
+dynamically `import("ws")` when there is no global `WebSocket`), so `ws` must be
+installed for any test or script that opens a document or database — otherwise
+the connection attempt fails with `Cannot find package 'ws'`. `better-sqlite3`
+and `y-sqlite3` are native modules requiring compilation; if you encounter build
+issues, ensure you have the appropriate build tools installed (Python, C++
+compiler). None are needed in the browser.
+
+### Testing in Node.js (dual-context tests)
+
+The same test can run in **two contexts** — interactively in an app's in-browser
+test-harness panel, and headlessly in Node under a normal test runner (e.g.
+[Vitest](https://vitest.dev)) to gate CI — because `JsBaoClient` runs the full
+document / Yjs / database / blob lifecycle in Node with no browser. Author the
+test once; run it in the panel while developing and under `vitest run` in CI.
+
+**Authenticate from Node with no browser and no email delivery.** Use the
+`+primitivetest` OTP bypass: `otpVerify(email, "000000")` authenticates and
+connects a fresh test user, provided the email's base address is on the app's
+`testAccountBaseEmails` whitelist (the app owner's per-app consent gate). No admin
+credentials, no pre-existing user — the user is auto-provisioned on first verify.
+
+Prerequisites:
+
+- The app's `testAccountBaseEmails` includes the base of your sign-in email — set
+  it with `primitive apps update <appId> --test-account-bases <base@example.com>`.
+  The sign-in email is then any `<base>+primitivetest<suffix>@example.com`
+  derivative (e.g. `alice+primitivetest-ci@example.com`). Reuse a **stable
+  suffix** per CI project so the same test user is reused across runs (the
+  provisioner is find-or-create) rather than accumulating one user per run.
+- `ws` is installed (see Required Packages above).
+- Storage defaults to `auto` — SQLite via `better-sqlite3` when present, in-memory
+  otherwise. No native dependency is required to run ephemeral tests.
+
+```typescript
+import { initializeClient } from "js-bao-wss-client";
+
+// Author once — this same async body is what a browser harness test runs too.
+const client = await initializeClient({
+  apiUrl: "https://your-api.example.com",
+  wsUrl: "wss://your-ws.example.com",
+  appId: "your-app-id",
+  models: [/* the models your tests need, as in the browser */],
+  // storageConfig defaults to { type: "auto" } — memory fallback in Node,
+  // no native deps required.
+});
+
+// #1413 OTP bypass: whitelisted +primitivetest email + code "000000".
+// On success the client is authenticated AND connected — no browser.
+await client.otpVerify("alice+primitivetest-ci@example.com", "000000");
+
+// From here the client behaves exactly as in the browser.
+const doc = await client.documents.create();
+await client.documents.open(doc.id);
+```
+
+Under `vitest run`, a failing assertion or a group that throws surfaces as a test
+failure and yields a **non-zero exit** natively (all passing → exit `0`), so the
+suite gates a merge with no bespoke runner. Emit JUnit for CI with
+`vitest run --reporter=junit`.
+
+**Failure mode.** If the sign-in email is **not** whitelisted (its base is absent
+from `testAccountBaseEmails`, or the app's mode rejects the provisioning),
+`otpVerify` rejects with a clear authentication error rather than hanging — catch
+it and fail the test:
+
+```typescript
+await expect(
+  client.otpVerify("not-whitelisted@example.com", "000000"),
+).rejects.toThrow(/otp|auth|verif/i);
+```
+
+> The in-browser test-harness panel and this Node path run the **same registered
+> tests**. Nothing in the test authoring contract requires a DOM — every browser
+> API the client touches is guarded with `typeof window === "undefined"`.
 
 ## Quick Start
 
@@ -1092,14 +1170,12 @@ await client.documents.delete(documentId, { forceCloseIfOpen: true }); // auto-c
 
 ### Document Aliases
 
-```typescript
-// Create or update an app-scoped alias
-await client.documents.aliases.set({
-  scope: "app",
-  aliasKey: "home",
-  documentId,
-});
+> **Note:** Only `scope: "user"` is supported. App-scoped aliases were removed
+> in #1168 — they conferred no access (there is no app-wide document-sharing
+> primitive) and only named a document every caller had to already be permitted
+> to open.
 
+```typescript
 // User-scoped alias (defaults userId to the current user)
 await client.documents.aliases.set({
   scope: "user",
@@ -1109,21 +1185,21 @@ await client.documents.aliases.set({
 
 // Resolve an alias
 const alias = await client.documents.aliases.resolve({
-  scope: "app",
-  aliasKey: "home",
+  scope: "user",
+  aliasKey: "current-draft",
 });
 
 // Open a document via alias (same return shape as documents.open)
 const { doc } = await client.documents.openAlias({
-  scope: "app",
-  aliasKey: "home",
+  scope: "user",
+  aliasKey: "current-draft",
 });
 
 // List aliases for a document (requires document access)
 const aliases = await client.documents.aliases.listForDocument(documentId);
 
 // Delete an alias (no error if already missing)
-await client.documents.aliases.delete({ scope: "app", aliasKey: "home" });
+await client.documents.aliases.delete({ scope: "user", aliasKey: "current-draft" });
 ```
 
 #### Atomic Create with Alias
@@ -1131,21 +1207,8 @@ await client.documents.aliases.delete({ scope: "app", aliasKey: "home" });
 Create a document and alias in a single atomic operation. This is an **online-only** operation that only creates the document if the alias doesn't already exist:
 
 ```typescript
-// Create document with app-scoped alias (requires admin/owner role)
+// Create document with a user-scoped alias
 const result = await client.documents.createWithAlias({
-  title: "Home Page",
-  alias: {
-    scope: "app",
-    aliasKey: "home",
-  },
-});
-
-console.log(result.documentId); // The created document ID
-console.log(result.alias.aliasKey); // "home"
-console.log(result.alias.documentId); // Same as documentId
-
-// Create document with user-scoped alias
-const userResult = await client.documents.createWithAlias({
   title: "My Draft",
   alias: {
     scope: "user",
@@ -1153,11 +1216,15 @@ const userResult = await client.documents.createWithAlias({
   },
 });
 
-// Attempting to create with existing alias throws HTTP 409
+console.log(result.documentId); // The created document ID
+console.log(result.alias.aliasKey); // "current-draft"
+console.log(result.alias.documentId); // Same as documentId
+
+// Attempting to create with an existing alias throws HTTP 409
 try {
   await client.documents.createWithAlias({
-    title: "Another Home",
-    alias: { scope: "app", aliasKey: "home" },
+    title: "Another Draft",
+    alias: { scope: "user", aliasKey: "current-draft" },
   });
 } catch (err) {
   console.log("Alias already exists");
@@ -1988,6 +2055,67 @@ const status = await client.workflows.getStatus({
 
 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`,
+  and the apply-ready states `apply_pending` / `apply_claimed` (the run
+  finished and its result is available for the client-side apply step). It also
+  treats any run whose `endedAt` is set as terminal regardless of its reported
+  `status`, so it never hangs on a stale status.
+- **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
+  }
+}
+```
+
+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:
@@ -2054,7 +2182,7 @@ const runs = await client.workflows.listRuns();
 console.log("Total runs:", runs.items.length);
 
 runs.items.forEach((run) => {
-  console.log(run.runKey, run.status, run.createdAt);
+  console.log(run.runKey, run.status, run.startedAt);
 });
 
 // Filter by workflow
@@ -2097,6 +2225,15 @@ const combined = await client.workflows.listRuns({
 #### Run Record Fields
 
 ```typescript
+type WorkflowRunStatus =
+  | "queued"
+  | "running"
+  | "completed"
+  | "failed"
+  | "terminated"
+  | "apply_pending"
+  | "apply_claimed";
+
 interface WorkflowRun {
   runId: string;
   runKey: string;
@@ -2105,9 +2242,11 @@ interface WorkflowRun {
   workflowKey: string;
   revisionId: string;
   contextDocId?: string;
-  status: string;
-  createdAt: string;
+  status: WorkflowRunStatus;
+  startedAt?: string; // ISO timestamp stamped when the run started
   endedAt?: string;
+  errorMessage?: string | null; // set when status is "failed", null otherwise
+  meta?: Record<string, any>; // custom metadata passed to workflows.start()
 }
 ```
 
@@ -2933,21 +3072,85 @@ console.log("Last activity:", session.lastActivity);
 
 ## Error Handling
 
+HTTP operations throw **typed errors** so you can branch on the kind of failure
+without parsing message strings:
+
+- **`JsBaoApiError`** — the server responded with a non-2xx status. Carries:
+  - `status: number` — the HTTP status code (always present).
+  - `code?: string` — a stable, machine-readable code from the server body
+    (e.g. `"alias_exists"` on a 409), or `undefined` when the server didn't
+    supply one.
+  - `body?: unknown` — the parsed JSON error body
+    (`{ error, status, timestamp, code?, details? }`), the raw text for a
+    non-JSON body, or `null` for an empty body.
+  - `message` — keeps the legacy `HTTP <status>: <text>` prefix, so older code
+    that regex-parses `.message` keeps working.
+- **`JsBaoNetworkError`** — the request never reached the server (unreachable
+  host, refused connection, DNS failure, abort). A network failure is
+  inherently retryable; decide retries with `instanceof JsBaoNetworkError`.
+- **`JsBaoError`** — client-side logical errors with a `code` (e.g. `"OFFLINE"`
+  when the client is in offline mode). Unchanged.
+
+Use the guards `isJsBaoApiError` / `isJsBaoNetworkError` / `isJsBaoError`, or
+`instanceof`. Neither `JsBaoApiError` nor `JsBaoNetworkError` exposes a
+`retryable` field — the class already tells you whether a retry makes sense.
+
 ```typescript
+import {
+  JsBaoApiError,
+  JsBaoNetworkError,
+  isJsBaoApiError,
+  isJsBaoNetworkError,
+} from "js-bao-wss-client";
+
 try {
-  // HTTP operations throw exceptions
   const res = await client.documents.create({ title: "Test" });
 } catch (error) {
-  if ((error as any).message?.includes("401")) {
-    console.error("Authentication failed");
-  } else if ((error as any).message?.includes("403")) {
-    console.error("Permission denied");
+  if (isJsBaoNetworkError(error)) {
+    console.error("Server unreachable — safe to retry");
+  } else if (isJsBaoApiError(error)) {
+    switch (error.status) {
+      case 401:
+        console.error("Authentication failed");
+        break;
+      case 403:
+        console.error("Permission denied");
+        break;
+      case 404:
+        console.error("Not found");
+        break;
+      default:
+        console.error(`API error ${error.status} (${error.code ?? "no code"})`);
+    }
   } else if ((error as any).code === "OFFLINE") {
     console.error("Client offline");
   } else {
-    console.error("API error:", (error as any).message);
+    throw error;
+  }
+}
+```
+
+### Idempotent add/remove without string parsing
+
+Branch on `status`/`code` to treat an expected conflict as success:
+
+```typescript
+// Adding an item that already exists (409) is success for an idempotent add.
+async function addOnce() {
+  try {
+    await client.makeRequest("PUT", `/document-aliases/app/${key}`, {
+      documentId,
+      mustNotExist: true,
+    });
+    return "created";
+  } catch (error) {
+    if (isJsBaoApiError(error) && error.status === 409) {
+      return "already-exists"; // idempotent — not a real failure
+    }
+    throw error;
   }
 }
+```
 
 // WebSocket errors are handled via events
 client.on("connection-error", (error) => {