@benmore/bm 2.7.310 → 2.7.312

package/index.d.ts

@@ -5,6 +5,10 @@ export interface User {
   last_name?: string | null;
   role: string;
   verified: number;
+  /** Every role the user holds: global roles plus the current tenant's roles. */
+  roles?: string[];
+  /** A groups: app's current tenant id (an admin's act-as tenant while stepped in); null without one. */
+  group_id?: string | null;
   [field: string]: unknown;
 }
 
@@ -16,6 +20,16 @@ export interface ListOpts {
   /** Column to order by (snake_case, as stored). */
   sort?: string;
   order?: 'asc' | 'desc';
+  /** REST shorthand for sort + order: 'starts_at:asc'. Ignored when sort is set. */
+  orderBy?: string;
+  /** Related rows to embed (?include=): 'author' or ['author', 'comments']. */
+  include?: string | string[];
+  /** Columns to return (?fields=). */
+  fields?: string | string[];
+  /** Page number for page/per_page pagination (list() still returns the rows only). */
+  page?: number;
+  per_page?: number;
+  /** Equality filters (col: value) and operator filters (col__gte: value). Other top-level keys are not sent. */
   where?: Record<string, string | number | boolean>;
 }
 
@@ -131,11 +145,28 @@ export interface RoomClient {
   readonly raw: WebSocket;
 }
 
+/** POST /api/<table>/<id>/transition answer. */
+export interface WorkflowTransitionResult {
+  status: 'transitioned';
+  from: string;
+  to: string;
+  /** The row id as it appeared in the URL (a string). */
+  id: string;
+}
+
+/** GET /api/<table>/<id>/transitions answer: the row's state and the moves this caller may make. */
+export interface WorkflowAvailable {
+  current: string;
+  /** role is set when the transition is role-gated (the caller holds it). */
+  transitions: Array<{ to: string; role?: string }>;
+}
+
 export interface WorkflowClient {
   readonly table: string;
   readonly id: number | string;
-  transitionTo(state: string): Promise<{ state: string }>;
-  available(): Promise<string[]>;
+  transitionTo(state: string): Promise<WorkflowTransitionResult>;
+  available(): Promise<WorkflowAvailable>;
+  /** The state stored in the workflow's own field (workflows.yaml field:). */
   current(): Promise<string>;
 }
 

package/index.js

@@ -48,16 +48,30 @@ async function request(method, path, body, options) {
   return { ok: res.ok, status: res.status, data };
 }
 
+// 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.
+function apiError(res, fallback) {
+  const data = res.data;
+  let text = fallback;
+  let code;
+  if (data && typeof data === 'object') {
+    if (typeof data.error === 'string' && data.error) { code = data.error; text = data.error; }
+    if (typeof data.message === 'string' && data.message) text = data.message;
+  }
+  const err = new Error(text);
+  err.status = res.status;
+  err.body = data;
+  if (code) err.code = code;
+  return err;
+}
+
 // Convenience: unwrap or throw. Most agent code wants this shape:
 //   const message = await bm.api.post('/api/messages', {...});
 async function unwrap(res) {
-  if (!res.ok) {
-    const msg = res.data?.error || `HTTP ${res.status}`;
-    const err = new Error(msg);
-    err.status = res.status;
-    err.body = res.data;
-    throw err;
-  }
+  if (!res.ok) throw apiError(res, `HTTP ${res.status}`);
   return res.data;
 }
 
@@ -185,12 +199,7 @@ async function refreshMe() {
 // Returns the user object on success; throws { status, body } on failure.
 async function signIn(identifier, password) {
   const res = await request('POST', '/login', { email: identifier, password });
-  if (!res.ok) {
-    const err = new Error(res.data?.error || 'Invalid credentials');
-    err.status = res.status;
-    err.body = res.data;
-    throw err;
-  }
+  if (!res.ok) throw apiError(res, 'Invalid credentials');
   return res.data?.user || null;
 }
 
@@ -200,10 +209,7 @@ async function signIn(identifier, password) {
 async function signUp(fields) {
   const res = await request('POST', '/signup', fields);
   if (!res.ok) {
-    const err = new Error(res.data?.error || 'Sign-up failed');
-    err.status = res.status;
-    err.body = res.data;
-    throw err;
+    throw apiError(res, 'Sign-up failed');
   }
   return res.data?.user || null;
 }
@@ -234,10 +240,7 @@ function _bufToB64u(buf) {
 async function _passkeyCall(method, path, body, fallback) {
   const res = await request(method, path, body);
   if (!res.ok) {
-    const err = new Error(res.data?.error || fallback);
-    err.status = res.status;
-    err.body = res.data;
-    throw err;
+    throw apiError(res, fallback);
   }
   return res.data;
 }
@@ -368,6 +371,21 @@ function _seg(v) {
   return e;
 }
 
+// list() options it sends. Anything else (a filter written at the top level
+// instead of under where:, a misspelled option) never reaches the server, so
+// say so once per table and key instead of returning unfiltered rows quietly.
+const _LIST_OPTS = new Set(['limit', 'offset', 'cursor', 'q', 'sort', 'order', 'orderBy', 'order_by',
+  'include', 'fields', 'page', 'per_page', 'perPage', 'where']);
+const _warnedListOpts = new Set();
+function _warnUnknownListOpts(table, opts) {
+  for (const k of Object.keys(opts || {})) {
+    if (_LIST_OPTS.has(k) || _warnedListOpts.has(table + '\u0000' + k)) continue;
+    _warnedListOpts.add(table + '\u0000' + k);
+    console.warn(`bm.table('${table}').list(): option "${k}" is not sent. ` +
+      `Filters go under where: { ${k}: ... }; list options are ${[..._LIST_OPTS].join(', ')}.`);
+  }
+}
+
 export function table(name) {
   if (!name || typeof name !== 'string') {
     throw new Error('bm.table(name) requires a string table name');
@@ -386,9 +404,21 @@ export function table(name) {
       if (opts.q)      qs.set('q',      String(opts.q));
       if (opts.sort)   qs.set('sort',   String(opts.sort));
       if (opts.order)  qs.set('order',  String(opts.order));
+      // The REST list parameters under their REST names: orderBy=col:dir,
+      // include=rel,rel, page/per_page, fields=a,b. They used to be dropped
+      // here without a word, so the server never saw them.
+      const orderBy = opts.orderBy ?? opts.order_by;
+      if (orderBy) qs.set('orderBy', String(orderBy));
+      const csv = (v) => (Array.isArray(v) ? v.join(',') : String(v));
+      if (opts.include) qs.set('include', csv(opts.include));
+      if (opts.fields)  qs.set('fields',  csv(opts.fields));
+      if (opts.page != null) qs.set('page', String(opts.page));
+      const perPage = opts.per_page ?? opts.perPage;
+      if (perPage != null) qs.set('per_page', String(perPage));
       if (opts.where) {
         for (const [k, v] of Object.entries(opts.where)) qs.set(k, String(v));
       }
+      _warnUnknownListOpts(t, opts);
       const path = base + (qs.toString() ? '?' + qs : '');
       const r = await api.get(path);
       // Offset lists are bare arrays; cursor/page lists use { data: [...] }.
@@ -717,12 +747,22 @@ async function loadFlowsRegistry() {
   return _flowsRegistry;
 }
 
-// Registry keys are camelCase (company_setup / company-setup → companySetup).
-// Accept snake_case and kebab-case aliases too - agents naturally write
-// bm.flows.company_setup when the file is flows/company-setup.yaml, and
-// making the obvious spelling work beats making them learn the mapping.
+// Registry keys are camelCase (company_setup / company-setup → companySetup;
+// bm_types.go flowSDKName is the same rule). Accept snake_case and
+// kebab-case spellings too - agents naturally write bm.flows.company_setup
+// when the file is flows/company-setup.yaml, and making the obvious spelling
+// work beats making them learn the mapping.
 function camelizeFlowName(name) {
-  return name.replace(/[-_]+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase());
+  const parts = String(name).split(/[-_]+/).filter(Boolean);
+  if (!parts.length) return name;
+  return parts.map((p, i) => (i === 0 ? p.charAt(0).toLowerCase() : p.charAt(0).toUpperCase()) + p.slice(1)).join('');
+}
+
+// Own keys only: a name such as 'constructor' must not resolve through the
+// prototype chain of the parsed registry.
+function flowRegistryEntry(reg, name) {
+  const own = (k) => (Object.prototype.hasOwnProperty.call(reg, k) ? reg[k] : undefined);
+  return own(name) || own(camelizeFlowName(name));
 }
 
 export const flows = new Proxy({}, {
@@ -730,19 +770,20 @@ export const flows = new Proxy({}, {
     if (typeof flowName !== 'string') return undefined;
     return async (params = {}, body) => {
       let reg = await loadFlowsRegistry();
-      let entry = reg[flowName] || reg[camelizeFlowName(flowName)];
+      let entry = flowRegistryEntry(reg, flowName);
       if (!entry) {
         // The registry lists only flows THIS caller may call, so one loaded
         // before sign-in (or before a role grant) can be missing the flow.
         // Refetch once before reporting it as undeclared.
         _flowsRegistry = null;
         reg = await loadFlowsRegistry();
-        entry = reg[flowName] || reg[camelizeFlowName(flowName)];
+        entry = flowRegistryEntry(reg, flowName);
       }
       if (!entry) {
         const available = Object.keys(reg).sort();
+        const call = (n) => (/^[A-Za-z_$][\w$]*$/.test(n) ? `bm.flows.${n}()` : `bm.flows[${JSON.stringify(n)}]()`);
         const listing = available.length
-          ? `Available flows: ${available.map(n => `bm.flows.${n}()`).join(', ')}.`
+          ? `Available flows: ${available.map(call).join(', ')}.`
           : 'No flows are registered (flows.yaml / flows/*.yaml define none with on.request triggers).';
         throw new Error(
           `bm.flows.${flowName} is not declared in flows.yaml. ${listing} ` +
@@ -757,11 +798,7 @@ export const flows = new Proxy({}, {
       }
       const method = (entry.method || 'POST').toUpperCase();
       const res = await request(method, path, body);
-      if (!res.ok) {
-        const err = new Error(res.data?.error || `flow ${flowName} failed (${res.status})`);
-        err.status = res.status; err.body = res.data;
-        throw err;
-      }
+      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) {
         return makeJob(res.data.job_id, res.data.status_url);
@@ -786,12 +823,22 @@ export function workflow(table, id) {
   return {
     table,
     id,
-    // Server expects { to: <newState> } (workflows.go handleTransition).
+    // Server expects { to: <newState> } (workflows.go handleTransition) and
+    // answers { status: 'transitioned', from, to, id }.
     transitionTo: (state) => api.post(`${base}/transition`, { to: state }),
+    // { current, transitions: [{ to, role? }] } (handleAvailableTransitions).
     available:    () => api.get(`${base}/transitions`),
+    // The transitions endpoint reads the workflow's own field (workflows.yaml
+    // field:), whatever it is named; reading row.state ?? row.status missed
+    // any other field. It needs a signed-in caller, so an anonymous reader of
+    // a public table falls back to the row.
     current:      async () => {
-      const row = await api.get(base);
-      return row.state ?? row.status;
+      const res = await request('GET', `${base}/transitions`);
+      if (res.status === 401) {
+        const row = await api.get(base);
+        return row?.state ?? row?.status;
+      }
+      return (await unwrap(res))?.current;
     },
   };
 }
@@ -1119,10 +1166,7 @@ function waitForICEGathering(pc) {
 async function broadcastSDPExchange(path, slug, sdpOffer) {
   const res = await request('POST', path, { slug, sdp: sdpOffer });
   if (!res.ok) {
-    const err = new Error(res.data?.error || 'broadcast: SDP exchange failed');
-    err.status = res.status;
-    err.body = res.data;
-    throw err;
+    throw apiError(res, 'broadcast: SDP exchange failed');
   }
   return res.data; // { sdp, session_id, slug }
 }

package/package.json

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