@benmore/bm 2.7.317 → 2.7.330

package/index.d.ts

@@ -36,6 +36,14 @@ export interface ListOpts {
 export interface ApiResult<T = unknown> {
   ok: boolean;
   status: number;
+  /**
+   * Parsed JSON; the text of a 2xx text/* answer; a Blob for a 2xx answer of
+   * any other type (an image, PDF or ZIP); {error, body} for a failed answer
+   * that is not JSON (body is the text as received; error is that text when it
+   * is one short line of plain text, else "Request failed (HTTP <status>)", so
+   * an HTML error page never becomes a thrown Error's message); null for an
+   * empty body.
+   */
   data: T | null;
 }
 
@@ -66,6 +74,11 @@ export interface AuthCalls {
   me(): Promise<User | null>;
   signOut(): Promise<void>;
   refreshMe(): Promise<User | null>;
+  /**
+   * When the sign-in still needs a step ({otp_required | mfa_required |
+   * mfa_setup_required, redirect}), the browser goes to that page (/verify-otp,
+   * /verify-mfa, /mfa-setup, keeping ?next=) and the promise does not settle.
+   */
   signIn(identifier: string, password: string): Promise<User | null>;
   signUp(fields: { email: string; password: string; [extraField: string]: unknown }): Promise<User | null>;
   /** Passkeys (WebAuthn): Face ID, Touch ID, Windows Hello, a phone. */
@@ -115,11 +128,17 @@ export interface VersionHistory {
   id: string;
   versions: VersionMetadata[];
 }
+export interface RevertKeptColumn {
+  column: string;
+  reason: 'command_owned' | 'workflow_state' | 'protected' | 'hidden' | 'not_in_version';
+}
 export interface RevertReceipt {
   status: 'reverted';
   id: string;
   reverted_to_version: string;
   owned_fields_kept: string[] | null;
+  /** Columns that kept their current value instead of the version's, and why. */
+  kept: RevertKeptColumn[];
 }
 
 export interface TableClient<Row = Record<string, unknown>> {
@@ -135,13 +154,44 @@ export interface TableClient<Row = Record<string, unknown>> {
   revertTo(id: number | string, version: number): Promise<RevertReceipt>;
 }
 
+/** bm.room() connection state, delivered as the 'bm:status' event (from is null). */
+export interface RoomStatus {
+  state: 'open' | 'reconnecting' | 'closed';
+  /** 'open' after a reconnect: messages sent while it was down are not replayed. */
+  reconnected?: boolean;
+  /** 'reconnecting': retry number, delay in ms, and the socket's close code. */
+  attempt?: number;
+  retryIn?: number;
+  code?: number;
+  /** 'reconnecting' after a failed handshake: the GET /ws answer (429, 502, ...). */
+  http?: number;
+  /** 'closed': why the room ended for good. */
+  reason?: 'left' | 'refused' | 'unauthorized' | 'forbidden';
+  /** 'closed': queued messages that were never sent. */
+  unsent?: number;
+}
+
+/** A refused join or handshake, delivered as the 'bm:error' event (from is null). The room then closes. */
+export interface RoomError {
+  code: 'not_member' | 'too_many_rooms' | 'join_refused' | 'unauthorized' | 'forbidden';
+  message: string;
+  room: string;
+}
+
 export interface RoomClient {
   readonly name: string;
+  /** Reconnects with backoff after a drop; 'closed' is final (leave, refused join, 401/403). */
+  readonly state: 'connecting' | 'open' | 'reconnecting' | 'closed';
+  on(kind: 'bm:status', fn: (status: RoomStatus, from: null) => void): this;
+  on(kind: 'bm:error', fn: (error: RoomError, from: null) => void): this;
   on(kind: string, fn: (payload: unknown, from: number | string) => void): this;
-  onAny(fn: (payload: unknown, from: number | string, kind: string) => void): this;
+  onAny(fn: (payload: unknown, from: number | string | null, kind: string) => void): this;
   off(kind: string, fn: Function): this;
-  send(payload: unknown): void;
+  /** true: sent; false: queued (16 max) until the room is open again.
+   *  Throws (code 'room_closed' or 'room_queue_full') instead of dropping. */
+  send(payload: unknown): boolean;
   leave(): void;
+  /** The current WebSocket; a reconnect replaces it. */
   readonly raw: WebSocket;
 }
 
@@ -323,6 +373,13 @@ export namespace live {
 }
 
 export function room(name: string): RoomClient;
+/**
+ * Call a flow by name. params fill the route's :path segments; a GET or HEAD
+ * flow sends the other params as its query string (it has no body). Resolves
+ * the parsed JSON answer, the text of a text/* answer (a CSV), or a Blob for
+ * any other type (the image or PDF of run: proxy / serve_file); an async flow
+ * resolves a Job.
+ */
 export const flows: Record<string, (params?: Record<string, unknown>, body?: unknown) => Promise<unknown | Job>>;
 export function workflow(table: string, id: number | string): WorkflowClient;
 export function aggregate<Result = unknown>(name: string): Promise<Result | null>;
@@ -358,9 +415,12 @@ export const broadcast: {
 };
 export const webrtc: { iceServers(): Promise<IceServer[]> };
 export const mfa: {
-  enroll(): Promise<{ qr_data_url: string; secret: string; backup_codes: string[] }>;
-  verify(code: string): Promise<{ ok: boolean }>;
-  disable(password: string): Promise<{ ok: boolean }>;
+  /** From a signed-in session pass the current password; on the /mfa-setup page after a sign-in that requires enrollment, pass nothing. */
+  enroll(password?: string): Promise<{ secret: string; otpauth_uri: string; backup_codes: string[] }>;
+  /** After a sign-in that required enrollment this also signs the person in (token, user_id, email). */
+  verify(code: string): Promise<{ status: "mfa_enabled"; token?: string; user_id?: number; email?: string }>;
+  /** Turns the factor off. Takes a current 6-digit code from the authenticator (not the password, not a backup code). */
+  disable(code: string): Promise<{ status: "mfa_disabled" }>;
 };
 export function html(strings: TemplateStringsArray, ...values: unknown[]): SafeHtml;
 export function raw(value: string): SafeHtml;
@@ -374,8 +434,11 @@ export const query: {
   fetch<T = unknown>(key: unknown, fetcher: () => Promise<T> | T, opts?: QueryFetchOpts): Promise<T>;
   refetch<T = unknown>(key: unknown): Promise<T | undefined>;
   invalidate(match: unknown | ((rawKey: unknown, stableKey: string) => boolean), opts?: { refetch?: boolean }): string[];
-  tableKey(table: string, spec?: Record<string, unknown>): unknown[];
+  /** The key table(table, opts) caches under, for the same arguments: opts.key when given, else derived from the request. Pass it to subscribe/get/set/invalidate/mutate. */
+  tableKey(table: string, opts?: Omit<QuerySpec, "table"> & QueryFetchOpts): unknown;
+  /** Cached under opts.key when given: name one to subscribe to the result. */
   read<T = unknown>(spec: QuerySpec, opts?: QueryFetchOpts): Promise<T[]>;
+  /** Cached under tableKey(table, opts). */
   table<T = unknown>(table: string, opts?: Omit<QuerySpec, "table"> & QueryFetchOpts): Promise<T[]>;
   invalidateTable(table: string, opts?: { refetch?: boolean }): string[];
   mutate<T = unknown>(opts: QueryMutateOpts<T>): Promise<T>;
@@ -389,7 +452,14 @@ declare const cache: {
   persistent(name: string, version: string | number): CacheClient | null;
 };
 
+export function captureError(err: unknown, options?: { tags?: Record<string, string> }): void;
+export function captureMessage(message: string, level?: 'warning' | 'error' | 'fatal'): void;
+export function setTag(key: string, value: string): void;
+
 declare const bm: {
+  captureError: typeof captureError;
+  captureMessage: typeof captureMessage;
+  setTag: typeof setTag;
   api: typeof api;
   auth: typeof auth;
   users: typeof users;

package/index.js

@@ -15,11 +15,22 @@
 
 const CSRF_META = () => document.querySelector('meta[name="csrf-token"]')?.content || '';
 
+// Requests the SDK sends with nobody at the tab (a live query's refetch after
+// a realtime event, heartbeats, the refresh when a tab becomes visible) carry
+// X-Benmore-Background: 1, so they do not count as activity for
+// auth.idle_timeout. inBackground marks every request fn starts synchronously.
+let _backgroundDepth = 0;
+function inBackground(fn) {
+  _backgroundDepth++;
+  try { return fn(); } finally { _backgroundDepth--; }
+}
+
 async function request(method, path, body, options) {
   const headers = new Headers({ Accept: 'application/json' });
   if (options?.headers) {
     new Headers(options.headers).forEach((value, name) => headers.set(name, value));
   }
+  if (_backgroundDepth > 0 || options?.background) headers.set('X-Benmore-Background', '1');
   const init = { method, credentials: 'same-origin', headers };
   if (options?.signal !== undefined) init.signal = options.signal;
   if (body !== undefined && body !== null) {
@@ -29,30 +40,73 @@ async function request(method, path, body, options) {
   if (method !== 'GET' && method !== 'HEAD') {
     headers.set('X-CSRF-Token', CSRF_META());
   }
-  const res = await fetch(path, init);
+  const started = Date.now();
+  let res;
+  try {
+    res = await fetch(path, init);
+  } catch (err) {
+    captureRequest(method, path, 0, started, null, err);
+    throw err;
+  }
   if (res.status === 204) {
+    captureRequest(method, path, res.status, started);
     observeSessionResponse(method, path, true, null);
     return { ok: true, status: 204, data: null };
   }
-  const text = await res.text();
-  const ct = (res.headers.get('content-type') || '').toLowerCase();
-  let data = null;
-  if (text) {
-    if (ct.includes('application/json')) {
-      try { data = JSON.parse(text); } catch { data = { error: text }; }
-    } else {
-      data = { error: text };
-    }
+  let data;
+  try {
+    data = await responseData(res, method);
+  } catch (err) {
+    captureRequest(method, path, res.status, started, res.headers.get('X-Request-Id'), err);
+    throw err;
   }
   observeSessionResponse(method, path, res.ok, data);
+  captureRequest(method, path, res.status, started, (data && typeof data === 'object' && typeof data.request_id === 'string' && data.request_id) || res.headers.get('X-Request-Id'));
   return { ok: res.ok, status: res.status, data, redirected: !!res.redirected, url: res.url || '' };
 }
 
+// responseData reads a response body by its Content-Type:
+//   JSON (application/json, any +json)  the parsed value ({error: text} if it does not parse;
+//                                       a failed one as below)
+//   2xx text/* (CSV, plain text, HTML)  the text, a string
+//   2xx of any other type               a Blob: an image, audio, PDF or ZIP from
+//                                       run: proxy or run: serve_file
+//   non-2xx that is not JSON            {error, body}: see failedText
+//   empty body, HEAD                    null
+// A non-JSON success used to come back as {error: text}, which made a flow
+// that answers an image resolve to {error: "<PNG bytes>"} with the bytes lost.
+async function responseData(res, method) {
+  if (method === 'HEAD') return null;
+  const ct = (res.headers.get('content-type') || '').toLowerCase();
+  const type = ct.split(';', 1)[0].trim();
+  const json = ct.includes('application/json') || type.endsWith('+json');
+  if (res.ok && type && !json && !type.startsWith('text/')) return res.blob();
+  const text = await res.text();
+  if (!text) return null;
+  if (json) {
+    try { return JSON.parse(text); } catch { return res.ok ? { error: text } : failedText(res, type, text); }
+  }
+  return res.ok ? text : failedText(res, type, text);
+}
+
+// failedText is a failed answer whose body is not JSON (a 404 page, a
+// proxy's error page, a plain-text error) as {error, body}: body is the text
+// as received; error, which becomes the thrown Error's message, is that text
+// only when it is one short line of plain text, else "Request failed (HTTP
+// <status>)". The whole HTML page used to become the message, and a sign-in
+// form showed it to the person.
+function failedText(res, type, text) {
+  const line = text.trim();
+  const plain = type !== 'text/html' && line.length <= 200 && !/[\r\n<]/.test(line);
+  return { error: plain && line ? line : `Request failed (HTTP ${res.status})`, body: text };
+}
+
 // apiError builds the Error a failed request throws. The framework's JSON
 // errors carry a short code in `error` and, when there is more to say, the
 // explanation in `message` (a refused write, a flow that failed): the Error's
 // message is that explanation, else the code, else fallback, and err.code is
-// the code. err.status and err.body are the response as received.
+// the code. err.status and err.body are the response as received (for a body
+// that is not JSON, {error, body} with the text in body: see failedText).
 function apiError(res, fallback) {
   const data = res.data;
   let text = fallback;
@@ -151,6 +205,11 @@ function resetSessionState(profile = undefined) {
   const bus = _liveConns.get('__bus__');
   if (bus) bus.reconnect(profile !== null);
   _sessionListeners.forEach(reset => reset(profile !== null));
+  // Error context belongs to the session that recorded it: the next
+  // account's reports must not carry its console text, paths or tags.
+  errorCrumbs.length = 0;
+  errorSent.length = 0;
+  for (const key of Object.keys(errorTags)) delete errorTags[key];
 }
 
 // These native endpoints change the cookie session or its active tenant. A
@@ -206,9 +265,12 @@ async function signIn(identifier, password) {
 }
 
 // A sign-in or sign-up that still needs a second step (the emailed or texted
-// code with auth.otp, an authenticator code with MFA) has not made a session:
-// the server answers {otp_required: true, redirect} (or mfa_required), or
-// redirects the request to the step's page. signInStepURL returns that page,
+// code with auth.otp, an authenticator code with MFA, enrolling an
+// authenticator for a role in auth.require_mfa_for_roles) has not made a
+// session: the server answers {otp_required: true, redirect} (or mfa_required,
+// or mfa_setup_required), or redirects the request to the step's page. The
+// app serves those pages (the scaffold's static/verify-otp.html,
+// verify-mfa.html, mfa-setup.html). signInStepURL returns that page,
 // same-origin and carrying the current page's ?next=, else null (also when
 // there is no page: outside a browser the calls resolve null as before).
 // Callers send the browser there, as a form post would, and do not return: code written as
@@ -218,7 +280,7 @@ function signInStepURL(path, res, loc) {
   if (!loc || typeof loc.assign !== 'function') return null;
   const data = res && res.data;
   let to = '';
-  if (data && typeof data === 'object' && (data.otp_required || data.mfa_required) && typeof data.redirect === 'string') {
+  if (data && typeof data === 'object' && (data.otp_required || data.mfa_required || data.mfa_setup_required) && typeof data.redirect === 'string') {
     to = data.redirect;
   } else if (res && res.redirected && typeof res.url === 'string' && loc.origin && res.url.startsWith(loc.origin + '/')) {
     const target = res.url.slice(loc.origin.length);
@@ -330,7 +392,8 @@ const passkey = {
       },
     }, 'Passkey sign-in failed');
     // With auth.otp the passkey proves the account and the emailed code
-    // still has to be entered before there is a session.
+    // still has to be entered before there is a session; a role that requires
+    // MFA enrollment goes to the setup page first.
     const step = signInStepURL('/api/_auth/passkeys/login', { data }, _pageLocation());
     if (step) return _goToSignInStep(step);
     return data.user || null;
@@ -650,7 +713,7 @@ live.scoped = function liveScoped(tableOrStar, fetchAndRender, opts) {
     if (running) { queued = true; return; }
     running = true;
     try {
-      const result = fetchAndRender();
+      const result = inBackground(fetchAndRender);
       if (result && typeof result.then === 'function') {
         await result;
       }
@@ -714,64 +777,216 @@ live.scoped = function liveScoped(tableOrStar, fetchAndRender, opts) {
 //   const room = bm.room('lobby');
 //   room.on('hello',   (payload, from) => greet(from));
 //   room.onAny((payload, from) => log(payload));
+//   room.on('bm:status', s => setBadge(s.state));  // open / reconnecting / closed
+//   room.on('bm:error',  e => toast(e.message));     // e.g. not a member
 //   room.send({ kind: 'hello' });
 //   room.leave();
+//
+// One WebSocket per room. A dropped socket (app restart, env change, the
+// server's heartbeat close after sign-out or a tenant switch) reconnects with
+// jittered exponential backoff (0.5 s doubling, 30 s ceiling; ten stable
+// seconds start it over) and joins the room again. Messages others sent
+// while it was down are not replayed: refetch durable state on
+// {state:'open', reconnected:true}. It stops for good after leave(), a
+// refused join ({type:'error'} from the server: ws_rooms membership) or a
+// refused handshake (401/403). Sends while not open are queued (16 max,
+// sent in order after the join); send() throws once the room is closed or
+// the queue is full, so nothing is dropped silently. SDK events carry
+// from === null; peers' frames never do.
 // =================================================================
 
+const ROOM_QUEUE_MAX = 16;       // below the server's 20 frames/s per connection
+const ROOM_RETRY_BASE_MS = 500;
+const ROOM_RETRY_MAX_MS = 30000;
+const ROOM_STABLE_MS = 10000;
+
+// The server's refused-join bodies (websocket.go), as stable codes.
+function roomErrorCode(body) {
+  if (body === 'not a member of this room') return 'not_member';
+  if (body === 'too many rooms on this connection') return 'too_many_rooms';
+  return 'join_refused';
+}
+
+function roomError(code, message, name) {
+  const err = new Error(message);
+  err.code = code;
+  err.room = name;
+  return err;
+}
+
 export function room(name) {
   if (!name || typeof name !== 'string') {
     throw new Error('bm.room(name) requires a string room name');
   }
   const proto = location.protocol === 'https:' ? 'wss' : 'ws';
-  const ws = new WebSocket(`${proto}://${location.host}/ws`);
+  const url = `${proto}://${location.host}/ws`;
   const namedHandlers = new Map(); // kind -> Set<fn>
   const anyHandlers = new Set();
-  let queue = [];
-  let open = false;
-
-  ws.onopen = () => {
-    open = true;
-    ws.send(JSON.stringify({ type: 'join', room: name }));
-    queue.forEach(p => ws.send(JSON.stringify({ type: 'broadcast', room: name, payload: p })));
-    queue = null;
-  };
-  ws.onmessage = (ev) => {
-    let msg;
-    try { msg = JSON.parse(ev.data); } catch { return; }
-    if (msg.type !== 'message' && msg.type !== 'presence') return;
-    const payload = msg.payload || {};
-    const from = msg.from;
-    const kind = payload.kind || msg.type; // 'presence' has no kind
+  let queue = [];          // serialized broadcast frames waiting for the next join
+  let ws = null;
+  let state = 'connecting'; // 'connecting' | 'open' | 'reconnecting' | 'closed'
+  let closedReason = null;
+  let attempt = 0;
+  let everOpened = false;
+  let timer = null;
+  let gen = 0;             // bumps on every new socket or close; stale callbacks compare
+
+  const dispatch = (kind, payload, from) => {
     const set = namedHandlers.get(kind);
-    if (set) set.forEach(fn => { try { fn(payload, from); } catch (e) { console.error(e); } });
-    anyHandlers.forEach(fn => { try { fn(payload, from, kind); } catch (e) { console.error(e); } });
+    if (set) [...set].forEach(fn => { try { fn(payload, from); } catch (e) { console.error(e); } });
+    [...anyHandlers].forEach(fn => { try { fn(payload, from, kind); } catch (e) { console.error(e); } });
+  };
+  const setStatus = (next, info) => {
+    state = next;
+    dispatch('bm:status', Object.assign({ state: next }, info), null);
+  };
+  const dropSocket = () => {
+    gen++;
+    if (timer !== null) { clearTimeout(timer); timer = null; }
+    if (ws && ws.readyState <= WebSocket.OPEN) { try { ws.close(1000); } catch { /* already closing */ } }
   };
+  const finish = (reason, info) => {
+    if (state === 'closed') return;
+    if (reason === 'left' && ws && ws.readyState === WebSocket.OPEN) {
+      try { ws.send(JSON.stringify({ type: 'leave', room: name })); } catch { /* closing anyway */ }
+    }
+    dropSocket();
+    if (reason === 'left') _sessionListeners.delete(onSession);
+    const unsent = queue.length;
+    queue = [];
+    closedReason = reason;
+    setStatus('closed', Object.assign({ reason }, info, unsent ? { unsent } : {}));
+  };
+  const retry = (info) => {
+    const ceiling = Math.min(ROOM_RETRY_MAX_MS, ROOM_RETRY_BASE_MS * Math.pow(2, attempt));
+    const delay = Math.round(ceiling / 2 + Math.random() * ceiling / 2);
+    attempt++;
+    // Arm the timer before telling handlers, so a leave() from a status
+    // handler cancels it.
+    timer = setTimeout(connect, delay);
+    setStatus('reconnecting', Object.assign({ attempt, retryIn: delay }, info));
+  };
+  // A handshake that failed before opening: browsers hide the HTTP status,
+  // so ask /ws with a plain GET. 401/403 are the upgrade's own refusals and
+  // cannot change by retrying; 400 (it would upgrade), 429, 5xx and network
+  // errors (a restart in progress) are transient.
+  const probe = () => (typeof fetch === 'function'
+    ? fetch('/ws', { credentials: 'same-origin', cache: 'no-store' }).then(r => r.status, () => 0)
+    : Promise.resolve(0));
+
+  function connect() {
+    timer = null;
+    if (state === 'closed') return;
+    const my = ++gen;
+    let openedAt = -1;
+    const sock = ws = new WebSocket(url);
+    sock.onopen = () => {
+      if (my !== gen) return;
+      openedAt = Date.now();
+      sock.send(JSON.stringify({ type: 'join', room: name }));
+      const pending = queue;
+      queue = [];
+      pending.forEach(frame => sock.send(frame));
+      const reconnected = everOpened;
+      everOpened = true;
+      setStatus('open', reconnected ? { reconnected: true } : {});
+    };
+    sock.onmessage = (ev) => {
+      if (my !== gen) return;
+      let msg;
+      try { msg = JSON.parse(ev.data); } catch { return; }
+      if (!msg || typeof msg !== 'object') return;
+      if (msg.type === 'error') {
+        // An error frame with `tables` answers a table subscribe sent on
+        // this socket (unknown table names): it is not about the room.
+        if (Array.isArray(msg.tables)) return;
+        // Every other error frame refuses a join; on this room's own
+        // connection that refusal is final.
+        const message = typeof msg.body === 'string' && msg.body ? msg.body : 'room error';
+        const code = roomErrorCode(msg.body);
+        dispatch('bm:error', { code, message, room: msg.room || name }, null);
+        if (!msg.room || msg.room === name) finish('refused');
+        return;
+      }
+      if (msg.type !== 'message' && msg.type !== 'presence') return;
+      const payload = msg.payload || {};
+      const from = msg.from;
+      const kind = payload.kind || msg.type; // 'presence' has no kind
+      dispatch(kind, payload, from);
+    };
+    sock.onerror = () => { /* onclose follows */ };
+    sock.onclose = (ev) => {
+      if (my !== gen) return;
+      const code = ev && ev.code;
+      if (openedAt >= 0) {
+        if (Date.now() - openedAt >= ROOM_STABLE_MS) attempt = 0;
+        retry({ code });
+        return;
+      }
+      probe().then((status) => {
+        if (my !== gen || state === 'closed') return;
+        if (status === 401 || status === 403) {
+          const reason = status === 401 ? 'unauthorized' : 'forbidden';
+          dispatch('bm:error', { code: reason, message: `the server refused the WebSocket connection (HTTP ${status})`, room: name }, null);
+          finish(reason);
+          return;
+        }
+        retry(status ? { code, http: status } : { code });
+      });
+    };
+  }
 
-  return {
+  // The socket carries the session it opened with. When the page's session
+  // changes (bm.auth sign-in/out, tenant switch, act-as), open a fresh one,
+  // like the bm.live stream; a refused room gets another try with the new
+  // identity. A room the app left stays closed.
+  function onSession() {
+    if (closedReason === 'left') return;
+    dropSocket();
+    attempt = 0;
+    closedReason = null;
+    if (everOpened) setStatus('reconnecting', { attempt: 0, retryIn: 0 });
+    else state = 'connecting';
+    connect();
+  }
+  _sessionListeners.add(onSession);
+  connect();
+
+  const client = {
     name,
+    /** 'connecting' | 'open' | 'reconnecting' | 'closed' */
+    get state() { return state; },
+    /** The current (or last) WebSocket; it changes on reconnect. */
+    get raw() { return ws; },
     on(kind, fn) {
       if (!namedHandlers.has(kind)) namedHandlers.set(kind, new Set());
       namedHandlers.get(kind).add(fn);
-      return this;
+      return client;
     },
-    onAny(fn) { anyHandlers.add(fn); return this; },
+    onAny(fn) { anyHandlers.add(fn); return client; },
     off(kind, fn) {
       namedHandlers.get(kind)?.delete(fn);
-      return this;
+      return client;
     },
+    // true: written to the open socket; false: queued for the next join.
     send(payload) {
-      if (open) {
-        ws.send(JSON.stringify({ type: 'broadcast', room: name, payload }));
-      } else {
-        queue.push(payload);
+      if (state === 'closed') {
+        throw roomError('room_closed', `bm.room('${name}') is closed (${closedReason}); call bm.room() to join again`, name);
       }
+      const frame = JSON.stringify({ type: 'broadcast', room: name, payload });
+      if (state === 'open' && ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(frame);
+        return true;
+      }
+      if (queue.length >= ROOM_QUEUE_MAX) {
+        throw roomError('room_queue_full', `bm.room('${name}') is not connected and already holds ${ROOM_QUEUE_MAX} unsent messages`, name);
+      }
+      queue.push(frame);
+      return false;
     },
-    leave() {
-      if (open) ws.send(JSON.stringify({ type: 'leave', room: name }));
-      ws.close();
-    },
-    raw: ws,
+    leave() { finish('left'); },
   };
+  return client;
 }
 
 // =================================================================
@@ -782,6 +997,12 @@ export function room(name) {
 // looking up a runtime registry written by the type generator at
 // /_internal/flows.json. We Proxy() the lookup so unknown names
 // throw a clear runtime error to match the TS error.
+//
+// params fill the route's :path segments; a GET or HEAD flow takes the rest
+// as its query string (it has no body): bm.flows.img({ id: 7, kind: 'png' })
+// → GET /api/img/7?kind=png. The call resolves what responseData reads: the
+// parsed JSON, the text of a text/* answer (a CSV), or a Blob for any other
+// type (the image or PDF a run: proxy or run: serve_file flow answers).
 // =================================================================
 
 let _flowsRegistry = null;
@@ -813,6 +1034,41 @@ function flowRegistryEntry(reg, name) {
   return own(name) || own(camelizeFlowName(name));
 }
 
+// flowRequestPath builds the URL a flow call requests. Each `:name` path
+// segment takes params[name] (else query[name]) as one encoded segment (never '.' or '..').
+// For a GET or HEAD flow (`query` not null) the params no segment used go in
+// the query string, where the flow binds them, followed by the fields of
+// `query` (the body a caller passed; FlowForm and FlowButton pass one) that
+// params did not name. Objects and arrays travel as JSON text, as a JSON body
+// binds them; null and undefined are left out. A flow with a body passes null.
+function flowRequestPath(template, params, query) {
+  const used = new Set();
+  let path = String(template || '').split('/').map((seg) => {
+    if (seg[0] !== ':') return seg;
+    const name = seg.slice(1);
+    // A GET body naming the path parameter fills it too: repeating it in the
+    // query would conflict with the routed value (400).
+    const own = (o) => o && typeof o === 'object' && Object.prototype.hasOwnProperty.call(o, name);
+    const src = own(params) ? params : (own(query) && query[name] != null ? query : null);
+    if (!src) return seg;
+    used.add(name);
+    return _seg(src[name]);
+  }).join('/');
+  if (!query) return path;
+  const pairs = [];
+  const add = (k, v) => {
+    if (used.has(k) || v === undefined || v === null) return;
+    used.add(k);
+    const text = typeof v !== 'object' ? String(v)
+      : typeof v.toJSON === 'function' ? String(v.toJSON()) : JSON.stringify(v);
+    pairs.push(encodeURIComponent(k) + '=' + encodeURIComponent(text));
+  };
+  for (const [k, v] of Object.entries(params)) add(k, v);
+  for (const [k, v] of Object.entries(query)) add(k, v);
+  if (pairs.length) path += (path.includes('?') ? '&' : '?') + pairs.join('&');
+  return path;
+}
+
 export const flows = new Proxy({}, {
   get(_target, flowName) {
     if (typeof flowName !== 'string') return undefined;
@@ -839,13 +1095,13 @@ export const flows = new Proxy({}, {
           `(file name, camelCased) - snake/kebab spellings of the same name also resolve.`
         );
       }
-      // Substitute :path params, each one encoded segment (never '.'/'..').
-      let path = entry.path;
-      for (const [k, v] of Object.entries(params)) {
-        if (path.includes(`:${k}`)) path = path.replace(`:${k}`, _seg(v));
-      }
       const method = (entry.method || 'POST').toUpperCase();
-      const res = await request(method, path, body);
+      const noBody = method === 'GET' || method === 'HEAD';
+      if (noBody && body !== undefined && body !== null && (typeof body !== 'object' || Array.isArray(body))) {
+        throw new Error(`bm.flows.${flowName} is a ${method} flow: pass its inputs as fields of params, which are sent as the query string (a ${method} request has no body).`);
+      }
+      const path = flowRequestPath(entry.path, params || {}, noBody ? (body || {}) : null);
+      const res = await request(method, path, noBody ? undefined : body);
       if (!res.ok) throw apiError(res, `flow ${flowName} failed (${res.status})`);
       // Async flows return {job_id, status_url} - wrap into a Job handle.
       if (res.data && res.data.job_id && res.data.status_url) {
@@ -1059,8 +1315,9 @@ export async function upload(file, opts = {}) {
     body: fd,
   });
   if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`upload failed (${res.status}): ${text}`);
+    // Same Error shape as bm.api: a proxy's HTML "413 Request Entity Too
+    // Large" page stays in err.body, not in the message.
+    throw apiError({ status: res.status, data: await responseData(res, 'POST') }, `upload failed (HTTP ${res.status})`);
   }
   return res.json();
 }
@@ -1358,7 +1615,7 @@ export const broadcast = {
     // Keep the slug claimed while live: a publisher that stops
     // heartbeating is treated as crashed and its slug can be taken over.
     const heartbeat = setInterval(() => {
-      if (!stopped) request('POST', '/api/_broadcast/heartbeat', { slug }).catch(() => {});
+      if (!stopped) request('POST', '/api/_broadcast/heartbeat', { slug }, { background: true }).catch(() => {});
     }, 60000);
     return {
       slug,
@@ -1473,7 +1730,9 @@ export const mfa = {
   // setup token path (require_mfa_for_roles) needs none.
   enroll:  (password) => api.post('/api/_auth/mfa/setup', password ? { password } : {}),
   verify:  (code)     => api.post('/api/_auth/mfa/verify', { code }),
-  disable: (password) => api.post('/api/_auth/mfa/disable', { password }),
+  // Turning the factor off takes a current authenticator code (not the
+  // password, and not a backup code): the endpoint reads { code }.
+  disable: (code)     => api.post('/api/_auth/mfa/disable', { code }),
 };
 
 // =================================================================
@@ -1686,7 +1945,7 @@ function presence(slug) {
   let heartbeatTimer = null;
   let onChangeUnsub = null;
 
-  const post = (action) => api.post('/api/_presence/heartbeat', { slug, action }).catch(() => {});
+  const post = (action) => api.post('/api/_presence/heartbeat', { slug, action }, action === 'heartbeat' ? { background: true } : undefined).catch(() => {});
   const sendBeaconLeave = () => {
     // Beacon survives tab close - fetch with keepalive is the right
     // primitive but sendBeacon is the only one with universal support.
@@ -1995,6 +2254,26 @@ function rememberTableKey(tableName, key) {
   _queryTableKeys.get(tableName).add(k);
 }
 
+// The key a table read is cached under, and the request it sends. One
+// function answers both bm.query.table and bm.query.tableKey, so a subscriber
+// to tableKey(name, opts) reads the entry table(name, opts) writes.
+function defaultReadKey(spec) {
+  return ['query', spec];
+}
+
+function tableRead(tableName, opts) {
+  // Separate client control options (which never affect the server result)
+  // from the server-affecting query spec. Only the spec may influence the
+  // cache key, otherwise two identical reads that differ only in staleTime/
+  // force/live would fragment into distinct cache entries and defeat dedupe.
+  const { staleTime, staleMs, force, live, key, ...serverOpts } = opts || {};
+  const spec = { ...serverOpts, table: tableName };
+  // The default is read()'s ['query', spec] key shape, so that a
+  // bm.query.table('posts') and bm.query.read({ table: 'posts' }) targeting
+  // identical rows collapse onto one shared cache entry.
+  return { spec, key: key || defaultReadKey(spec), control: { staleTime, staleMs, force, live } };
+}
+
 function ensureQueryLiveInvalidation() {
   if (_queryLiveStop || typeof live !== 'function' || typeof EventSource === 'undefined') return;
   const stop = live('*', (ev) => {
@@ -2010,7 +2289,7 @@ function ensureQueryLiveInvalidation() {
     }
     const t = setTimeout(() => {
       _queryLiveTimers.delete(table);
-      const opts = { refetch: _queryLiveConfig.refetch };
+      const opts = { refetch: _queryLiveConfig.refetch, background: true };
       if (table) query.invalidateTable(table, opts);
       else {
         const keys = new Set([..._queryTableKeys.values()].flatMap(keys => [...keys]));
@@ -2059,7 +2338,7 @@ export const query = {
     e.staleTime = staleTime;
     const revision = e.revision;
     const pending = Promise.resolve()
-      .then(fetcher)
+      .then(opts.background ? () => inBackground(fetcher) : fetcher)
       .then((data) => {
         if (e.revision === revision) {
           e.revision++;
@@ -2087,10 +2366,10 @@ export const query = {
     notifyQuery(e);
     return pending;
   },
-  async refetch(key) {
+  async refetch(key, opts = {}) {
     const e = queryEntry(key);
     if (!e.fetcher) return e.data;
-    return query.fetch(e.rawKey, e.fetcher, { force: true, staleTime: e.staleTime });
+    return query.fetch(e.rawKey, e.fetcher, { force: true, staleTime: e.staleTime, background: !!opts.background });
   },
   invalidate(match, opts = {}) {
     const keys = [];
@@ -2099,7 +2378,7 @@ export const query = {
     // We deliberately avoid raw string startsWith on the stable-stringified key
     // because that produced false positives (e.g. {a:1} matching {a:1,b:2}, or
     // ['user'] matching ['username']). Array-prefix is predictable for the
-    // common ['table', name, spec] / ['query', spec] key shapes used here.
+    // ['query', spec] key shape used here and for an app's own array keys.
     const matchExact = typeof match !== 'function' ? queryKey(match) : null;
     const matchPrefix = (typeof match !== 'function' && Array.isArray(match)) ? match : null;
     const isArrayPrefix = (prefix, raw) => {
@@ -2119,16 +2398,19 @@ export const query = {
       e.updatedAt = 0;
       keys.push(stable);
       notifyQuery(e);
-      if (opts.refetch && e.fetcher) query.refetch(e.rawKey).catch(() => {});
+      if (opts.refetch && e.fetcher) query.refetch(e.rawKey, { background: !!opts.background }).catch(() => {});
     }
     return keys;
   },
-  tableKey(tableName, spec = {}) {
-    return ['table', tableName, spec];
+  // The key bm.query.table(tableName, opts) caches under, for subscribe/get/
+  // set/invalidate/mutate: opts.key when the caller names one, otherwise the
+  // key derived from the request.
+  tableKey(tableName, opts = {}) {
+    return tableRead(tableName, opts).key;
   },
   async read(spec, opts = {}) {
     if (!spec || !spec.table) throw new Error('bm.query.read({ table, ... }) requires table');
-    const key = opts.key || ['query', spec];
+    const key = opts.key || defaultReadKey(spec);
     if (opts.live !== false) {
       rememberTableKey(spec.table, key);
       ensureQueryLiveInvalidation();
@@ -2139,17 +2421,10 @@ export const query = {
     }, opts);
   },
   table(tableName, opts = {}) {
-    // Separate client control options (which never affect the server result)
-    // from the server-affecting query spec. Only the spec may influence the
-    // cache key, otherwise two identical reads that differ only in staleTime/
-    // force/live would fragment into distinct cache entries and defeat dedupe.
-    const { staleTime, staleMs, force, live, key, ...serverOpts } = opts;
-    const spec = { ...serverOpts, table: tableName };
-    // Route through read() with the same ['query', spec] key shape so that a
-    // bm.query.table('posts') and bm.query.read({ table: 'posts' }) targeting
-    // identical rows collapse onto one shared cache entry. Forward every client
-    // control option (staleTime/staleMs/force/live) so none are silently dropped.
-    return query.read(spec, { key: key, staleTime, staleMs, force, live });
+    // Forward every client control option (staleTime/staleMs/force/live) so
+    // none are silently dropped.
+    const { spec, key, control } = tableRead(tableName, opts);
+    return query.read(spec, { ...control, key });
   },
   invalidateTable(tableName, opts = {}) {
     const keys = _queryTableKeys.get(tableName);
@@ -2233,7 +2508,7 @@ const bm = {
   flows, workflow, aggregate, aggregates, jobs,
   notifications, upload, audit, permissions, signedUrl,
   t, mfa, webrtc, broadcast, markdown, markdownBatch, presence, cache,
-  createStore, query, html, raw,
+  createStore, query, html, raw, captureError, captureMessage, setTag,
 };
 export default bm;
 
@@ -2241,55 +2516,184 @@ export default bm;
 if (typeof window !== 'undefined') window.bm = bm;
 
 // =================================================================
-//  Client error capture → POST /api/_errors → _benmore_client_errors.
-//  Powers the get_client_errors MCP tool + Sentry/Slack forwarding.
-//  Installs window.onerror + unhandledrejection (the two ways JS
-//  surfaces an uncaught failure - the 404-from-a-fetch case is an
-//  unhandled rejection, so BOTH are required). Throttled + deduped so
-//  an error loop can't spam the endpoint.
+//  Same-origin error reporting. Context stays bounded and excludes URL
+//  queries and form contents; the app scrubs it again before export.
 // =================================================================
-if (typeof window !== 'undefined') {
-  let _errSent = 0, _errLast = '';
-  const _ERR_CAP = 25;
-  const _postErr = (p) => {
-    if (_errSent >= _ERR_CAP) return;
-    const key = (p.message || '') + '|' + (p.source || '') + '|' + (p.line || 0);
-    if (key === _errLast) return; // collapse immediate duplicates
-    _errLast = key; _errSent++;
-    try {
+const errorTags = Object.create(null),
+  errorCrumbs = [],
+  errorSent = [];
+const errorTagRE = /^[a-z0-9_.]{1,32}$/,
+  errorRequestIDRE = /^[0-9a-f]{8,32}$/;
+
+function validErrorTags(input) {
+  const out = Object.create(null);
+  if (!input || typeof input !== 'object') return out;
+  for (const [key, value] of Object.entries(input)) {
+    if (Object.keys(out).length >= 10) break;
+    if (errorTagRE.test(key) && typeof value === 'string' && Array.from(value).length <= 200) out[key] = value;
+  }
+  return out;
+}
+
+export function setTag(key, value) {
+  if (typeof key !== 'string' || !errorTagRE.test(key) || typeof value !== 'string' || Array.from(value).length > 200) return;
+  if (!Object.hasOwn(errorTags, key) && Object.keys(errorTags).length >= 10) return;
+  errorTags[key] = value;
+}
+
+function errorPath(value) {
+  try {
+    return new URL(value, typeof location === 'undefined' ? 'https://invalid.example' : location.href).pathname;
+  } catch {
+    return '';
+  }
+}
+
+function addErrorCrumb(type, message, data) {
+  errorCrumbs.push({
+    timestamp: new Date(Date.now()).toISOString(),
+    type,
+    message: String(message).slice(0, 300),
+    ...(data ? { data } : {}),
+  });
+  if (errorCrumbs.length > 30) errorCrumbs.shift();
+}
+
+function postError(payload) {
+  if (typeof fetch !== 'function') return;
+  try {
+    const now = Date.now();
+    while (errorSent.length && errorSent[0].time <= now - 600000) errorSent.shift();
+    const top = (payload.stack || '').split('\n').find((line) => /^\s*at\s/.test(line) || /@.*:\d+/.test(line)) || payload.source || '';
+    // A local warning must not hide a later error/fatal occurrence.
+    const key = (payload.level || 'error') + '|' + payload.message + '|' + top;
+    if (errorSent.length >= 25 || errorSent.some((item) => item.key === key)) return;
+    errorSent.push({ time: now, key });
+    const body = {
+      ...payload,
+      url: typeof location === 'undefined' ? '' : errorPath(location.href),
+      tags: validErrorTags({ ...payload.tags, ...errorTags }),
+      breadcrumbs: errorCrumbs.slice(),
+    };
+    Promise.resolve(
       fetch('/api/_errors', {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(p),
+        // A report is not activity: a background refetch that keeps failing
+        // must not hold an idle session open (auth.idle_timeout).
+        headers: { 'Content-Type': 'application/json', 'X-Benmore-Background': '1' },
+        body: JSON.stringify(body),
         keepalive: true,
         credentials: 'same-origin',
-      }).catch(() => {}); // never let reporting throw (would loop)
-    } catch (_) {}
+      }),
+    ).catch(() => {});
+  } catch (_) {} // Reporting must never create another failure.
+}
+
+function errorPayload(err) {
+  return {
+    message: String(err?.message || (typeof err === 'string' ? err : 'Unknown error')).slice(0, 2000),
+    stack: typeof err?.stack === 'string' ? err.stack.slice(0, 8000) : '',
+    ...(typeof err?.status === 'number' ? { status: err.status } : {}),
+    ...(errorRequestIDRE.test(err?.body?.request_id || '') ? { request_id: err.body.request_id } : {}),
   };
+}
+
+export function captureError(err, options = {}) {
+  try {
+    postError({ ...errorPayload(err), kind: 'manual', level: 'error', tags: options?.tags });
+  } catch (_) {}
+}
+
+export function captureMessage(message, level = 'error') {
+  try {
+    postError({
+      kind: 'message',
+      message: String(message).slice(0, 2000),
+      level: ['warning', 'error', 'fatal'].includes(level) ? level : 'error',
+    });
+  } catch (_) {}
+}
+
+function captureRequest(method, path, status, started, requestID, err) {
+  try {
+    if (typeof location === 'undefined') return;
+    const url = new URL(path, location.href);
+    if (url.origin !== location.origin || url.pathname === '/api/_errors') return;
+    const cleanPath = url.pathname;
+    addErrorCrumb('http', method + ' ' + cleanPath, {
+      method,
+      path: cleanPath.slice(0, 300),
+      status,
+      ms: Math.max(0, Date.now() - started),
+    });
+    if (status >= 500 || err)
+      postError({
+        kind: 'http',
+        level: 'error',
+        message: method + ' ' + cleanPath + (err ? ' network failure' : ' ' + status),
+        method,
+        path: cleanPath,
+        status,
+        ...(errorRequestIDRE.test(requestID || '') ? { request_id: requestID } : {}),
+      });
+  } catch (_) {}
+}
+
+if (typeof window !== 'undefined') {
   window.addEventListener('error', (e) => {
     // Resource-load errors (img/script 404s) have no .message - skip them.
     if (!e || !e.message) return;
-    _postErr({
+    postError({
       kind: 'error',
       message: String(e.message).slice(0, 2000),
       stack: e.error && e.error.stack ? String(e.error.stack).slice(0, 8000) : '',
       source: e.filename || '',
       line: e.lineno || 0,
       col: e.colno || 0,
-      url: location.href,
     });
   });
   window.addEventListener('unhandledrejection', (e) => {
     const r = e && e.reason;
-    const msg = r && r.message ? r.message : (typeof r === 'string' ? r : 'Unhandled promise rejection');
-    _postErr({
-      kind: 'unhandledrejection',
-      message: String(msg).slice(0, 2000),
-      stack: r && r.stack ? String(r.stack).slice(0, 8000) : '',
-      source: '',
-      line: 0,
-      col: 0,
-      url: location.href,
-    });
+    try {
+      postError({ ...errorPayload(r), kind: 'unhandledrejection' });
+    } catch (_) {}
   });
+  for (const name of ['pushState', 'replaceState']) {
+    const original = window.history?.[name];
+    if (typeof original !== 'function') continue;
+    window.history[name] = function (...args) {
+      const result = original.apply(this, args);
+      addErrorCrumb('navigation', errorPath(window.location.href));
+      return result;
+    };
+  }
+  window.addEventListener('popstate', () => addErrorCrumb('navigation', errorPath(window.location.href)));
+  for (const name of ['error', 'warn']) {
+    const original = console[name];
+    console[name] = function (...args) {
+      try {
+        const message = args
+          .map((arg) => {
+            try {
+              return typeof arg === 'string' ? arg : JSON.stringify(arg);
+            } catch {
+              return '[unserializable]';
+            }
+          })
+          .join(' ')
+          .slice(0, 300);
+        addErrorCrumb('console', message, { level: name });
+      } catch (_) {}
+      return original.apply(this, args);
+    };
+  }
+  window.document?.addEventListener(
+    'click',
+    (e) => {
+      const target = e.target;
+      if (!target || typeof target.getAttribute !== 'function') return;
+      addErrorCrumb('click', target.getAttribute('data-testid') || String(target.tagName || '') + (target.id ? '#' + target.id : ''));
+    },
+    true,
+  );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benmore/bm",
-  "version": "2.7.317",
+  "version": "2.7.330",
   "description": "Zero-dependency browser SDK for external Benmore frontends",
   "type": "module",
   "module": "./index.js",