@abloatai/ablo 0.25.0 → 0.27.0

package/dist/query/client.js

@@ -1,28 +1,28 @@
 /**
- * HTTP client for the generic /sync/query endpoint.
+ * The HTTP client for the sync query endpoint.
  *
- * Thin wrapper over fetch() that:
- *   - POSTs a QueryBatch as JSON
- *   - Sends the bearer credential via withAuthHeaders (Authorization header)
- *   - Throws on non-2xx responses
- *   - Parses the response into a typed QueryBatchResult
+ * {@link postQuery} is a small wrapper over `fetch` that POSTs a
+ * {@link QueryBatch} as JSON to `/sync/query`, attaches the bearer credential
+ * as an `Authorization` header, and parses the response into a typed
+ * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
+ * every query in the batch comes back with an empty result, so a
+ * fire-and-forget caller cannot crash on an unhandled rejection.
  *
- * The higher-level BootstrapHelper methods (fetchDeckSlideLayers,
- * fetchChatMessages, etc.) use this to issue structured queries
- * without duplicating the fetch boilerplate.
+ * Higher-level query helpers build on this to issue structured queries without
+ * repeating the fetch and error-handling boilerplate.
  */
 import { z } from 'zod';
 import { translateHttpError } from '../errors.js';
+import { classifyRecovery } from '../errorCodes.js';
 import { withAuthHeaders } from '../auth/credentialSource.js';
 import { getContext } from '../context.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
-// Each result slot is an array of rows (or an object for bundled
-// responses). Server-side per-query failures surface here as `[]`, but
-// the server logs them via `console.error('[query.error] ...')` — alert
-// on that prefix, not on emptiness. Parsing through Zod normalizes
-// `null` slots into empty arrays so downstream callers never see raw
-// null.
+// Each result slot is an array of rows, or an object for a bundled response.
+// A per-query failure on the server surfaces here as an empty array rather
+// than an error, so emptiness alone does not distinguish "no rows" from
+// "the query failed." Parsing through Zod normalizes a `null` slot into an
+// empty array, so callers never receive a raw null.
 const QueryResultSchema = z
     .union([z.array(z.unknown()), z.record(z.string(), z.unknown()), z.null()])
     .transform((val) => {
@@ -36,71 +36,102 @@ const QueryBatchResultSchema = z
 })
     .passthrough();
 /**
- * POST a batch of queries to /sync/query. Returns the parsed
- * QueryBatchResult. Throws a descriptive error on HTTP failure.
+ * Sends a batch of queries to `/sync/query` and returns the parsed
+ * {@link QueryBatchResult}. An HTTP failure is not thrown: it is logged, and
+ * every query in the batch comes back with an empty result, which keeps a
+ * fire-and-forget caller from crashing on an unhandled rejection. A 401 may
+ * first be handed to {@link PostQueryOptions.recoverCredential} for a single
+ * retry.
  *
- * The server guarantees results[i] corresponds to queries[i] in the
- * request — callers can rely on index alignment to extract typed
- * results from a multi-query batch.
+ * The response preserves order: `results[i]` corresponds to the query at
+ * `queries[i]`, so callers can rely on index alignment to pull typed results
+ * out of a multi-query batch.
  */
 export async function postQuery(options, batch) {
     const url = `${options.baseUrl}/sync/query`;
     const timeout = options.fetchTimeout ?? 30_000;
-    // Race the fetch against a timeout so hung requests don't block
-    // the calling helper indefinitely.
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeout);
-    try {
-        const headers = withAuthHeaders(options.getAuthToken, { 'Content-Type': 'application/json' }, options.capabilityToken);
-        const response = await fetch(url, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(batch),
-            signal: controller.signal,
-        });
-        if (!response.ok) {
-            // Build the typed AbloError for this HTTP failure (same code→class
-            // map the throwing paths use) so the log is tagged + carries a
-            // registry `code` (e.g. AbloAuthenticationError/session_expired on a
-            // 401) instead of a bare status. We deliberately DON'T throw —
-            // fire-and-forget callers would kill the Next.js router on an
-            // unhandled rejection — and still return empty slots, but the failure
-            // is now legible as an Ablo error. Routed through the gated logger so it
-            // obeys ABLO_LOG_LEVEL like everything else: a consumer-register `warn`
-            // (their models + the typed message + a wire `code`) with the forensics on
-            // a `debug` companion. Actionable and not self-healing — the read returns
-            // empty until the underlying cause (auth, network) is resolved.
-            let body = null;
-            try {
-                body = await response.clone().json();
+    // At most two attempts: the original request, plus one replay after a
+    // successful credential recovery (see `recoverCredential`). A second auth
+    // rejection falls through to the log-and-empty path, so a wedged credential
+    // can never retry-loop.
+    for (let attempt = 0;; attempt++) {
+        // Race the fetch against a timeout so hung requests don't block
+        // the calling helper indefinitely. Fresh controller per attempt.
+        const controller = new AbortController();
+        const timer = setTimeout(() => { controller.abort(); }, timeout);
+        try {
+            // Recomputed per attempt: `withAuthHeaders` reads the live credential
+            // source, so a replay after recovery carries the freshly-minted key.
+            const headers = withAuthHeaders(options.getAuthToken, { 'Content-Type': 'application/json' }, options.capabilityToken);
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(batch),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                // Build the typed AbloError for this HTTP failure (the same
+                // code-to-class map the throwing paths use) so the log carries a
+                // registry `code` — for example an authentication error with
+                // `session_expired` on a 401 — rather than a bare status. This path
+                // deliberately does not throw, since a fire-and-forget caller could
+                // crash on an unhandled rejection. It returns empty slots while still
+                // logging a legible Ablo error.
+                let body = null;
+                try {
+                    body = await response.clone().json();
+                }
+                catch {
+                    // non-JSON error page — translateHttpError falls back to status text
+                }
+                const err = translateHttpError(response.status, body);
+                // On a 401, hand the failure to the recovery hook once. The recovery
+                // class routes the outcome: an expired access credential is re-minted
+                // and the request replays; a lost session is terminal and stops here;
+                // anything else stops. A bare 401 with no readable code is treated as
+                // an expired access credential, so the only terminal path is the
+                // re-mint itself coming back empty, never an ambiguous status.
+                if (attempt === 0 && response.status === 401 && options.recoverCredential) {
+                    const recovery = typeof err.code === 'string'
+                        ? classifyRecovery(err.code)
+                        : 'access_credential_expiry';
+                    const outcome = await options.recoverCredential(recovery);
+                    if (outcome === 'retry') {
+                        getContext().logger.debug('[postQuery] credential recovered — replaying query once', {
+                            code: err.code ?? response.status,
+                        });
+                        continue;
+                    }
+                }
+                // Logged through the level-gated logger, so it honors ABLO_LOG_LEVEL:
+                // a `warn` line the app developer can read (the models, the typed
+                // message, and a wire `code`), with the forensic detail on a companion
+                // `debug` line. The read stays empty until the underlying cause, such
+                // as auth or network, is resolved.
+                const models = batch.queries.map((q) => q.model).join(', ');
+                getContext().logger.warn(`Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`);
+                getContext().logger.debug('[postQuery.error] query http failure', {
+                    type: err.type,
+                    code: err.code ?? response.status,
+                    models,
+                    message: err.message,
+                });
+                return { results: batch.queries.map(() => []) };
             }
-            catch {
-                // non-JSON error page — translateHttpError falls back to status text
+            const raw = await response.json();
+            const parsed = QueryBatchResultSchema.safeParse(raw);
+            if (!parsed.success) {
+                // A malformed server response isn't something the consumer can act on
+                // (server/protocol issue) → debug, gated like everything else.
+                getContext().logger.debug('[postQuery.error] malformed response', {
+                    issues: parsed.error.issues,
+                });
+                return { results: batch.queries.map(() => []) };
             }
-            const err = translateHttpError(response.status, body);
-            const models = batch.queries.map((q) => q.model).join(', ');
-            getContext().logger.warn(`Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`);
-            getContext().logger.debug('[postQuery.error] query http failure', {
-                type: err.type,
-                code: err.code ?? response.status,
-                models,
-                message: err.message,
-            });
-            return { results: batch.queries.map(() => []) };
+            return parsed.data;
         }
-        const raw = await response.json();
-        const parsed = QueryBatchResultSchema.safeParse(raw);
-        if (!parsed.success) {
-            // A malformed server response isn't something the consumer can act on
-            // (server/protocol issue) → debug, gated like everything else.
-            getContext().logger.debug('[postQuery.error] malformed response', {
-                issues: parsed.error.issues,
-            });
-            return { results: batch.queries.map(() => []) };
+        finally {
+            clearTimeout(timer);
         }
-        return parsed.data;
-    }
-    finally {
-        clearTimeout(timer);
     }
 }

package/dist/query/types.d.ts

@@ -1,44 +1,25 @@
 /**
- * Structured query types for the generic /sync/query endpoint.
+ * Structured query types for the `/sync/query` endpoint.
  *
- * Zero-shaped ZQL-ish wire format: `where` is a flat list of `[col, op, val]`
- * tuples (AND'd together), and `related` is a list of schema-declared
- * relation names to traverse. The server compiler reads the schema's
- * relation metadata to turn `related: ['layers']` into the right JOIN.
+ * A query describes a filtered read in a compact wire format. `where` is a flat
+ * list of `[column, operator, value]` conditions combined with AND, and
+ * `related` names the schema relations to fetch alongside each row. The server
+ * compiles a query against your schema: it reads the model's relation metadata
+ * to turn `related: ['layers']` into the right join, and turns each condition
+ * into a WHERE fragment. The protocol carries no model-specific logic, so
+ * adding a model or relation is a schema change rather than a server change.
  *
- * # Why this shape
- *
- * An earlier revision used equality-only `where: Record<string, unknown>`
- * plus a PK-only `ids: string[]` batch field. That worked for simple cases
- * but collapsed on two real workloads:
- *
- *   1. "Fetch all layers for these slide IDs" — the IDs are foreign keys
- *      (`SlideLayer.slideId`), not primary keys. The old `ids` field
- *      filtered on `id`, silently returning empty.
- *
- *   2. "Fetch all layers for this deck" — needs a JOIN through
- *      `slides.deck_id → slide_layers.slide_id`. Equality-only `where` had
- *      no way to express it, so the Go server hardcoded a dispatch case.
- *
- * Both are generic patterns ("batch by FK column", "filter via relation")
- * that should be first-class in the protocol, not model-specific escape
- * hatches on the server. This shape matches Zero's ZQL:
- *
- *   - `where('slideId', 'IN', ids)` → `['slideId', 'IN', ids]`
- *   - `.related('layers')` → `related: ['layers']`
- *
- * The server's compiler stays schema-driven: given a model name, it reads
- * the schema's declared relations to emit JOIN SQL, and given a `[col, op,
- * val]` tuple it emits a WHERE fragment — never a switch on specific model
- * names. Adding a new model or relation is a schema change, not a server
- * change.
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every layer whose `slideId` falls in a set of
+ * ids.
  */
 /** Primitive operand types allowed in a where clause. */
 export type WherePrimitive = string | number | boolean | null;
 /**
- * Comparison operators. Mirrors Zero's ZQL set so client authors can
- * lean on familiar semantics and server compilers that already target
- * ZQL stay portable.
+ * The comparison operators a {@link WhereClause} may use: equality and
+ * inequality, ordering, set membership (`IN` / `NOT IN`), null checks
+ * (`IS` / `IS NOT`), and case-sensitive or case-insensitive pattern
+ * matching (`LIKE`, `ILIKE`, and their negations).
  */
 export type WhereOp = '=' | '!=' | '<' | '<=' | '>' | '>=' | 'IN' | 'NOT IN' | 'IS' | 'IS NOT' | 'LIKE' | 'NOT LIKE' | 'ILIKE' | 'NOT ILIKE';
 /**
@@ -77,20 +58,17 @@ export interface Query {
      */
     model: string;
     /**
-     * List of where clauses AND'd together. Empty or omitted means "no
-     * filter" (still subject to server-side org scoping).
-     *
-     * Use `['col', 'IN', values]` to batch by any column — the old
-     * primary-key-only `ids` field is subsumed by this form.
+     * The conditions to filter by, combined with AND. Empty or omitted returns
+     * every row the caller may see; reads are still scoped to the caller's
+     * organization on the server. Use `['col', 'IN', values]` to batch a read by
+     * any column.
      */
     where?: readonly WhereClause[];
     /**
-     * Relation names declared in the schema for this model. The server's
-     * compiler resolves each name via the schema's relation metadata
-     * (`relation.hasMany` / `relation.belongsTo`) and emits the JOIN
-     * SQL — no model-specific dispatch on the server.
-     *
-     * Results come back as nested objects under the relation key:
+     * The relations to fetch with each row, named as they are declared on this
+     * model in the schema. The server resolves each name from the schema's
+     * relation metadata and joins the related rows in. They come back nested
+     * under the relation key:
      *
      *   { __typename: 'Slide', id: '…', layers: [{ __typename: 'SlideLayer', … }] }
      */
@@ -119,25 +97,24 @@ export interface QueryBatch {
 /** Response body from POST /sync/query. */
 export interface QueryBatchResult {
     /**
-     * Per-query results in request order. `results[i]` corresponds to
-     * `queries[i]`. Each element is an array of rows for array-shaped
-     * queries, or a bundled object for providers that return multiple
-     * collections under named keys.
-     *
-     * Each row carries `__typename` for client-side model dispatch, plus
-     * any `related` keys nested under the row.
+     * The result of each query, in request order: `results[i]` corresponds to
+     * `queries[i]`. Each element is an array of rows, or an object bundling
+     * several named row collections when the source returns more than one. Every
+     * row carries a `__typename` field naming its model, so callers can dispatch
+     * on it, along with any requested `related` rows nested under their relation
+     * key.
      *
-     * Failed queries surface as empty arrays. The server logs them via
-     * `console.error('[query.error] ...')` — alert on that prefix rather
-     * than trying to infer failure from empty results. A tagged-union
-     * wire shape that forces caller acknowledgement is the right next
-     * step once every `postQuery` consumer is updated at once.
+     * A query that fails on the server comes back as an empty array, which is
+     * indistinguishable from a query that simply matched nothing — treat an empty
+     * result as "no rows", not as proof the query succeeded. The element type is
+     * `unknown` because one batch can mix row shapes, so narrow each result
+     * before use.
      */
     results: unknown[];
     /**
-     * Server watermark observed after the batch ran. Public model reads
-     * expose this as `stamp` and callers thread it into `commits.create({
-     * readAt })` to reject stale writes.
+     * The server watermark observed after the batch ran. Model reads expose this
+     * as `stamp`, and callers thread it into `commits.create({ readAt })` so the
+     * server can reject a write built on stale data.
      */
     lastSyncId?: number;
 }

package/dist/query/types.js

@@ -1,36 +1,16 @@
 /**
- * Structured query types for the generic /sync/query endpoint.
- *
- * Zero-shaped ZQL-ish wire format: `where` is a flat list of `[col, op, val]`
- * tuples (AND'd together), and `related` is a list of schema-declared
- * relation names to traverse. The server compiler reads the schema's
- * relation metadata to turn `related: ['layers']` into the right JOIN.
- *
- * # Why this shape
- *
- * An earlier revision used equality-only `where: Record<string, unknown>`
- * plus a PK-only `ids: string[]` batch field. That worked for simple cases
- * but collapsed on two real workloads:
- *
- *   1. "Fetch all layers for these slide IDs" — the IDs are foreign keys
- *      (`SlideLayer.slideId`), not primary keys. The old `ids` field
- *      filtered on `id`, silently returning empty.
- *
- *   2. "Fetch all layers for this deck" — needs a JOIN through
- *      `slides.deck_id → slide_layers.slide_id`. Equality-only `where` had
- *      no way to express it, so the Go server hardcoded a dispatch case.
- *
- * Both are generic patterns ("batch by FK column", "filter via relation")
- * that should be first-class in the protocol, not model-specific escape
- * hatches on the server. This shape matches Zero's ZQL:
- *
- *   - `where('slideId', 'IN', ids)` → `['slideId', 'IN', ids]`
- *   - `.related('layers')` → `related: ['layers']`
- *
- * The server's compiler stays schema-driven: given a model name, it reads
- * the schema's declared relations to emit JOIN SQL, and given a `[col, op,
- * val]` tuple it emits a WHERE fragment — never a switch on specific model
- * names. Adding a new model or relation is a schema change, not a server
- * change.
+ * Structured query types for the `/sync/query` endpoint.
+ *
+ * A query describes a filtered read in a compact wire format. `where` is a flat
+ * list of `[column, operator, value]` conditions combined with AND, and
+ * `related` names the schema relations to fetch alongside each row. The server
+ * compiles a query against your schema: it reads the model's relation metadata
+ * to turn `related: ['layers']` into the right join, and turns each condition
+ * into a WHERE fragment. The protocol carries no model-specific logic, so
+ * adding a model or relation is a schema change rather than a server change.
+ *
+ * The `IN` operator lets you batch a read by any column, including a foreign
+ * key — for example, fetching every layer whose `slideId` falls in a set of
+ * ids.
  */
 export {};

package/dist/react/AbloProvider.d.ts

@@ -34,13 +34,9 @@ import { type SyncStoreContract } from './context.js';
  *
  * ```tsx
  * // Build once at module scope — a new instance per render tears down the socket.
- * const ablo = Ablo({
- *   schema,
- *   apiKey: () =>
- *     fetch('/api/ablo-session', { method: 'POST' })
- *       .then((r) => r.json())
- *       .then((d) => d.token),
- * });
+ * // The endpoint string points at your session-mint route (`ablo init`
+ * // scaffolds it); the SDK fetches it and keeps the token fresh.
+ * const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
  *
  * <AbloProvider client={ablo}>
  *   <App />
@@ -152,9 +148,9 @@ export type MeshParticipantStatus = ParticipantStatus;
 export interface UseWatchReturn {
     readonly participant: EngineParticipant | null;
     /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
-    readonly peers: ReadonlyArray<Peer>;
+    readonly peers: readonly Peer[];
     /** Active claim claims by peers (`participant.claims.others`), bridged to React. */
-    readonly claims: ReadonlyArray<Claim>;
+    readonly claims: readonly Claim[];
     readonly status: ParticipantStatus;
     readonly error: Error | null;
 }
@@ -196,7 +192,7 @@ export declare function useWatch(opts: UseWatchOptions): UseWatchReturn;
  * const alone = !peers.some((p) => p.participantKind === 'user');
  * ```
  */
-export declare function usePeers(scope?: ParticipantScope): ReadonlyArray<Peer>;
+export declare function usePeers(scope?: ParticipantScope): readonly Peer[];
 /**
  * Returns the raw `SyncEngine` proxy. Typically you want the typed
  * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases
@@ -217,7 +213,7 @@ export declare function useSync<R extends SchemaRecord = SchemaRecord>(): Ablo<R
 /**
  * Returns the underlying `SyncStoreContract` (the BaseSyncedStore).
  * Most consumers should prefer the typed hooks (`useQuery` etc.); this
- * is for advanced cases like direct ObjectPool access or custom
+ * is for advanced cases like direct InstanceCache access or custom
  * reactive bridges. Throws if the provider hasn't mounted the store
  * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
  *

package/dist/react/AbloProvider.js

@@ -1,6 +1,7 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
-import { useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef, useState, createContext, } from 'react';
+import { Ablo } from '../client/Ablo.js';
 import { createParticipantClaimId, parseParticipantTtlSeconds, resolveParticipantSyncGroups, } from '../sync/participants.js';
 import { SyncContext } from './context.js';
 import { AbloInternalContext } from './internalContext.js';
@@ -77,18 +78,24 @@ export function AbloProvider(props) {
     // It does NOT dispose the client (consumer-owned) and does NOT touch auth.
     useEffect(() => {
         let stale = false;
-        const unsubscribeSession = engine.onSessionError(async (err) => {
+        const unsubscribeSession = engine.onSessionError((err) => {
             errorEmitter.emit(err);
-            try {
-                await engine.purge();
-            }
-            catch { }
-            try {
-                await onSessionExpiredRef.current?.();
-            }
-            catch (hookErr) {
-                errorEmitter.emit(hookErr);
-            }
+            void (async () => {
+                try {
+                    await engine.purge();
+                }
+                catch { }
+                try {
+                    await onSessionExpiredRef.current?.();
+                }
+                catch (hookErr) {
+                    errorEmitter.emit(hookErr);
+                }
+            })().catch(() => {
+                // Only a throwing errorEmitter subscriber can land here — it was
+                // already the error-reporting path, so swallow rather than surface
+                // an unhandled rejection loop.
+            });
         });
         engine
             .ready()
@@ -122,7 +129,7 @@ export function AbloProvider(props) {
             }
         };
         window.addEventListener('beforeunload', handler);
-        return () => window.removeEventListener('beforeunload', handler);
+        return () => { window.removeEventListener('beforeunload', handler); };
     }, [engine, preventUnsavedChanges]);
     // ── SyncContext value (for useQuery/useOne/useMutate hooks) ──────
     //
@@ -259,7 +266,7 @@ export function useWatch(opts) {
     // Subscribe the connection to the scope's sync groups while mounted +
     // connected — the area-of-interest navigation primitive. No claim, no
     // TTL: a viewer just receives the scope's deltas. Hysteresis (warm TTL)
-    // lives in the store's AreaOfInterestManager, so a quick unmount/remount
+    // lives in the store's SubscriptionManager, so a quick unmount/remount
     // (tab flip) doesn't re-bootstrap.
     useEffect(() => {
         const scope = opts.scope;
@@ -389,7 +396,7 @@ export function usePeers(scope) {
         // rarely; a frame of stale presence is harmless (same rationale as
         // useWatch's peers bridge).
         setPeers(compute());
-        return presence.onChange(() => setPeers(compute()));
+        return presence.onChange(() => { setPeers(compute()); });
     }, [engine, scopeKey]);
     return peers;
 }
@@ -424,7 +431,7 @@ export function useSync() {
 /**
  * Returns the underlying `SyncStoreContract` (the BaseSyncedStore).
  * Most consumers should prefer the typed hooks (`useQuery` etc.); this
- * is for advanced cases like direct ObjectPool access or custom
+ * is for advanced cases like direct InstanceCache access or custom
  * reactive bridges. Throws if the provider hasn't mounted the store
  * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
  *
@@ -442,7 +449,7 @@ export function useSync() {
  */
 export function useSyncStore() {
     const sync = useContext(SyncContext);
-    if (!sync || !sync.store) {
+    if (!sync?.store) {
         throw new AbloValidationError('useSyncStore: the sync engine has not yet initialized. Wrap ' +
             'consumers in <ClientSideSuspense> or guard on useSyncStatus().', { code: 'sync_not_ready' });
     }