@abloatai/ablo 0.36.0 → 0.37.1

package/dist/query/client.js

@@ -1,138 +0,0 @@
-/**
- * The HTTP client for the sync query endpoint.
- *
- * {@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.
- *
- * 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 '../transaction/errors.js';
-import { classifyRecovery } from '../transaction/errorCodes.js';
-import { withAuthHeaders } from '../transaction/auth/credentialSource.js';
-import { globalRuntime } from '../context.js';
-// ── Response validation ─────────────────────────────────────────────────
-//
-// 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) => {
-    if (val === null)
-        return [];
-    return val;
-});
-const QueryBatchResultSchema = z
-    .object({
-    results: z.array(QueryResultSchema),
-})
-    .loose();
-/**
- * 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 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;
-    const runtime = options.runtime ?? globalRuntime;
-    // 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') {
-                        runtime.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(', ');
-                runtime.logger.warn(`Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`);
-                runtime.logger.debug('[postQuery.error] query http failure', {
-                    type: err.type,
-                    code: err.code ?? response.status,
-                    models,
-                    message: err.message,
-                });
-                return { results: batch.queries.map(() => []) };
-            }
-            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.
-                runtime.logger.debug('[postQuery.error] malformed response', {
-                    issues: parsed.error.issues,
-                });
-                return { results: batch.queries.map(() => []) };
-            }
-            return parsed.data;
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    }
-}

package/dist/query/types.d.ts

@@ -1,85 +0,0 @@
-/**
- * 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: ['blocks']` 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 block whose `sectionId` falls in a set of
- * ids.
- */
-export type { WherePrimitive, WhereOp, WhereClause, LoadWhere, } from '../transaction/resources/where.js';
-import type { WhereClause } from '../transaction/resources/where.js';
-/** A single structured fetch request. */
-export interface Query {
-    /**
-     * Client-facing model name (e.g. "File", "Block", "Message").
-     * The server's adapter maps this to the actual database table.
-     */
-    model: string;
-    /**
-     * 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[];
-    /**
-     * 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: 'Section', id: '…', blocks: [{ __typename: 'Block', … }] }
-     */
-    related?: readonly string[];
-    /**
-     * Row limit. Applied after where + JOIN, before related nesting.
-     * Omit for no limit.
-     */
-    limit?: number;
-    /**
-     * Column to order by. For stable pagination. Omit for unordered.
-     */
-    orderBy?: string;
-    /** Order direction. Defaults to `'asc'`. */
-    order?: 'asc' | 'desc';
-}
-/** Request body for POST /sync/query. */
-export interface QueryBatch {
-    /**
-     * Batch of queries to execute in one round trip. Results are
-     * returned in request order at the same indices. Keep batches
-     * small — the server caps at 16 queries per batch by default.
-     */
-    queries: Query[];
-}
-/** Response body from POST /sync/query. */
-export interface QueryBatchResult {
-    /**
-     * 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.
-     *
-     * 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[];
-    /**
-     * 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,16 +0,0 @@
-/**
- * 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: ['blocks']` 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 block whose `sectionId` falls in a set of
- * ids.
- */
-export {};

package/dist/react/AbloProvider.d.ts

@@ -1,242 +0,0 @@
-import { type ReactNode } from 'react';
-import type { SchemaRecord } from '../transaction/schema/schema.js';
-import { Ablo } from '../client/Ablo.js';
-import type { Claim, Duration, Peer } from '../transaction/types/streams.js';
-import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../sync/participants.js';
-import { type SyncStoreContract } from './context.js';
-/**
- * Ablo umbrella provider — owns the sync engine, multiplayer, and
- * the full lifecycle (Strict-Mode-safe singleton, `beforeunload`,
- * session-expiry handling, post-bootstrap hooks).
- *
- * Design goals (borrowed from Liveblocks' `LiveblocksProvider` and
- * Zero's `ZeroProvider`):
- *
- *   - **One component, one import.** Consumers write the provider
- *     once at the root; nothing else needs to plumb the engine.
- *   - **Multiplayer is default.** React consumers are always browsers doing
- *     multiplayer UI, so `useJoin()` / `useAblo()` are always
- *     available. No opt-in prop.
- *   - **Declarative props for app glue.** `preventUnsavedChanges`,
- *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
- *     absorbs a class of integration code that previously lived in
- *     userland.
- *   - **Singleton safety.** The engine lives in a ref and rotates
- *     only when `userId` / account scope / `url` change. React
- *     Strict Mode double-mount does not leak a second WebSocket.
- */
-/**
- * Props for `<AbloProvider>`.
- *
- * The one required prop is a prebuilt {@link Ablo} client — the client
- * owns auth and the credential lifecycle; this provider is the reactive
- * binding over it (Stripe's `<Elements stripe={...}>` model):
- *
- * ```tsx
- * // Build once at module scope — a new instance per render tears down the socket.
- * // 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 />
- * </AbloProvider>
- * ```
- *
- * That's it for most apps. `userId` is informational; the `fallback`,
- * `preventUnsavedChanges`, and `on*` props are opt-in app glue; and the
- * block tagged "Optional DI (advanced)" below is escape-hatch wiring for
- * tests and platform builders — if you don't recognize a prop there, you
- * don't need it.
- */
-export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
-    /**
-     * A prebuilt {@link Ablo} client — **the only way to configure the engine.**
-     * Construct it yourself with `Ablo({ schema, apiKey, ... })` and pass the
-     * instance: the CLIENT owns auth, the credential lifecycle, transport, and
-     * connection; this provider is the thin REACTIVE binding over it (context,
-     * the bootstrap gate, error/​session forwarding). Mirrors Stripe
-     * `<Elements stripe={...}>` and a Supabase client passed into a context.
-     *
-     * Memoize it (build it once, e.g. with `useMemo` or module scope) — a new
-     * instance each render re-keys the bootstrap gate and tears down the socket.
-     */
-    client: Ablo<R>;
-    /**
-     * The app user id, surfaced via `useCurrentUserId()` for app-owned fields.
-     * Purely informational for the React tree — sync identity is resolved by the
-     * client from its auth, not from this. Optional.
-     */
-    userId?: string;
-    /**
-     * Block tab close while there are unsynced local writes (the standard
-     * `beforeunload` prompt). Browsers ignore custom messages — don't pass one.
-     */
-    preventUnsavedChanges?: boolean;
-    /**
-     * Fired when the server rejects the session. The provider has ALREADY called
-     * `client.purge()` (disposed + wiped IndexedDB) by the time this runs — use it
-     * for app side effects (redirect to sign-in, clear analytics identity).
-     */
-    onSessionExpired?: () => void | Promise<void>;
-    /**
-     * Fired on any error the provider surfaces (engine/WebSocket/bootstrap). For
-     * Sentry/Datadog. React-only consumers can use `useErrorListener()` instead.
-     */
-    onError?: (error: Error) => void;
-    /**
-     * Rendered in place of `children` during the *first* bootstrap pass —
-     * while the engine is actively transitioning from `initial` →
-     * `connected` and has never successfully connected before. Once the
-     * engine reaches `connected` the gate latches open for the lifetime
-     * of this provider instance; transient `reconnecting` / `needs-auth`
-     * states do NOT re-show the fallback (the app's own UI handles those
-     * by then).
-     *
-     * Defaults to `<DefaultFallback />` — a neutral theme-adaptive
-     * spinner that uses `currentColor`, ships with zero design-system
-     * dependencies, and self-centers in a full-parent container. Pass
-     * your own `<Skeleton />` for a branded loading UX. Pass `null` to
-     * render nothing during bootstrap. Pass the string literal
-     * `"passthrough"` to opt out of the gate entirely — children render
-     * immediately and consumers are responsible for their own gating
-     * (`<ClientSideSuspense>` or manual `useSyncStatus()` checks).
-     * Useful for pages that mount debug helpers, error boundaries, or
-     * analytics that must run pre-ready.
-     */
-    fallback?: ReactNode | 'passthrough';
-    children: ReactNode;
-}
-export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
-export type { EngineParticipant, ParticipantScope, ParticipantStatus };
-/**
- * Options for `useJoin`. The hook reuses the engine's single
- * WebSocket and opens a scoped claim on it when `scope` is provided:
- * one TCP connection, N logical sub-syncgroup participants.
- */
-export interface UseJoinOptions {
-    readonly scope?: ParticipantScope;
-    /**
-     * Lease TTL for the participant claim, as a compact duration (`'5m'`) or a
-     * number of seconds. The same dial and the same spelling as
-     * `ablo.<model>.join(ids, { ttl })` and every other lease in the SDK.
-     */
-    readonly ttl?: Duration;
-    /**
-     * @deprecated Use `ttl`. Removed in 0.37.0.
-     *
-     * The same rename as on `ParticipantJoinOptions`: one lease, and the seconds
-     * spelling was the one that misled, because it accepted duration strings too.
-     */
-    readonly ttlSeconds?: number | string | null;
-    /** Tear down + don't re-join while true. */
-    readonly paused?: boolean;
-    /**
-     * Acquire a write-claim CLAIM on the scope, in addition to read interest.
-     *
-     * Default `false`: opening a scope subscribes the connection to its deltas
-     * (read interest, via `update_subscription`) but does NOT claim it — a
-     * viewer is not a claimant. Set `true` when the participant intends to
-     * WRITE (editing a report, an agent staking work): the claim is sent so peers
-     * observe it, and the scope is pinned so it stays subscribed (never warms)
-     * for as long as the claim is held.
-     */
-    readonly claim?: boolean;
-    /**
-     * Backfill the scope's CURRENT state into the pool on enter, in addition to
-     * tailing live changes.
-     *
-     * Default `false`: entering a scope subscribes to its FUTURE deltas only — if
-     * the scope's rows aren't already loaded, the view is empty until something
-     * changes. Set `true` when opening an entity that may not be loaded yet (a
-     * deep-linked report, a never-opened ledger) so its current rows are fetched and
-     * injected once, then kept fresh by the live tail. The fetch is single-flight
-     * and runs once per group; a failure soft-fails (the live tail still flows).
-     */
-    readonly hydrate?: boolean;
-}
-export interface UseJoinReturn {
-    readonly participant: EngineParticipant | null;
-    /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
-    readonly peers: readonly Peer[];
-    /** Active claim claims by peers (`participant.claims.others`), bridged to React. */
-    readonly claims: readonly Claim[];
-    readonly status: ParticipantStatus;
-    readonly error: Error | null;
-}
-/**
- * Join multiplayer for a given scope. Returns the participant and its
- * lifecycle status. Auto-cleans up on unmount or when `paused`
- * flips to true.
- *
- * `useJoin` is the React form of `ablo.<model>.join` — scope-level
- * read-interest + presence; returns the reactive participant facade
- * (peers/claims/status).
- *
- * The returned `participant` is an `EngineParticipant` — `.presence`
- * + `.claims` only — backed by the engine's existing socket. For
- * headless-bot patterns (a separate identity in the same browser
- * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
- */
-export declare function useJoin(opts: UseJoinOptions): UseJoinReturn;
-/**
- * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useJoin}, this does
- * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
- * it is a pure reader of the engine's already-flowing presence stream.
- *
- * Pass `scope` to narrow to the peers on that scope's sync group(s); omit
- * it to get everyone on the engine's groups. Membership is driven entirely
- * by the presence channel (set server-side on connect, independent of any
- * cursor/collaboration traffic), so reading it never affects what the
- * connection is subscribed to and can't deadlock against a gated channel.
- *
- * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
- * broadcasts while alone — when some OTHER mount already owns the scope's
- * read interest (scope `leave` is not reference-counted, so a second
- * `useJoin` on the same scope would warm-drop the owner's
- * subscription on unmount).
- *
- * ```ts
- * const peers = usePeers({ reports: reportId });
- * const alone = !peers.some((p) => p.participantKind === 'user');
- * ```
- */
-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
- * where you need direct access (e.g., `sync.tasks.onChange(cb)`).
- *
- * The generic parameter narrows the return type to your schema's
- * model record so call sites get typed `sync.tasks.findMany()` /
- * `sync.sections.create(...)` without a cast at the call site:
- *
- * ```ts
- * const sync = useSync<(typeof schema)['models']>();
- * ```
- *
- * The runtime value is the exact engine the provider constructed;
- * the generic just widens the compile-time type.
- */
-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 InstanceCache access or custom
- * reactive bridges. Throws if the provider hasn't mounted the store
- * yet — wrap consumers in `<ClientSideSuspense>` to gate correctly.
- *
- * The generic parameter lets consumers widen the return type to a
- * concrete `BaseSyncedStore<...>` subclass if they track one:
- *
- * ```ts
- * type AppStore = BaseSyncedStore<AppEvents, typeof schema>;
- * const store = useSyncStore<AppStore>();  // no cast needed at call site
- * ```
- *
- * The runtime value is always the concrete store the SDK constructed,
- * so widening the type is safe. The bounded generic (`T extends
- * SyncStoreContract`) keeps the widening honest.
- */
-export declare function useSyncStore<T extends SyncStoreContract = SyncStoreContract>(): T;