@abloatai/ablo 0.8.0 → 0.9.1

package/dist/mutators/undoApply.js

@@ -0,0 +1,143 @@
+/**
+ * undoApply.ts — conflict-aware resolution of undo/redo ops (per-user undo).
+ *
+ * The undo stack is already per-client (only local mutator invocations call
+ * `UndoScope.record`; a collaborator's edits arrive as inbound sync deltas and
+ * never land here). What this module adds is the second half of "undo per
+ * user": when replaying a recorded op, only touch a field whose CURRENT value
+ * still equals what THIS op established — so undo reverts your own change only
+ * where it still stands, and never clobbers a field a collaborator changed
+ * after you (the Yjs/CRDT "selective undo" principle, adapted to our
+ * field-level last-writer-wins model).
+ *
+ * `resolveOps(apply, paired, store, policy)`:
+ *   - `apply`  — the ops we're about to replay (inverses on undo, forwards on redo).
+ *   - `paired` — their counterparts, carrying the value this op established
+ *     (forwards on undo = "what I set"; inverses on redo = "what undo restored").
+ *   - For `update`/`updateMany` ops it drops fields whose live value no longer
+ *     matches the established value. `create`/`delete` families are structural
+ *     and applied unconditionally (undoing your create removes the row you
+ *     added; undoing your delete restores it).
+ *
+ * With no collaborator, the live value always equals what you set, so nothing
+ * is dropped — single-user undo is byte-for-byte unchanged.
+ */
+export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    if (aArr) {
+        const av = a;
+        const bv = b;
+        if (av.length !== bv.length)
+            return false;
+        for (let i = 0; i < av.length; i++) {
+            if (!deepEqual(av[i], bv[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao);
+    const bk = Object.keys(bo);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k))
+            return false;
+        if (!deepEqual(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Map `id → { field: establishedValue }` from the paired ops. Only update-family
+ * ops carry per-field values worth comparing.
+ */
+function buildEstablished(paired) {
+    const map = new Map();
+    for (const op of paired) {
+        if (op.kind === 'update') {
+            map.set(op.patch.id, op.patch);
+        }
+        else if (op.kind === 'updateMany') {
+            for (const p of op.patches)
+                map.set(p.id, p);
+        }
+    }
+    return map;
+}
+/** Read the live value of a field from the store's pool, or `undefined`. */
+function readCurrentField(store, id, field) {
+    const model = store.pool.get(id);
+    if (!model)
+        return undefined;
+    const json = model.toJSON?.();
+    return json ? json[field] : undefined;
+}
+/**
+ * Keep only the fields whose live value still equals what this op established
+ * (`established[field]`). Returns `null` if nothing survives (the whole op is a
+ * no-op — every field was superseded by a collaborator).
+ */
+function filterStalePatch(store, patch, established) {
+    const out = { id: patch.id };
+    let kept = 0;
+    for (const field of Object.keys(patch)) {
+        if (field === 'id')
+            continue;
+        if (established && field in established) {
+            // Apply only if the field still holds the value WE established — i.e. no
+            // collaborator overwrote it since. Otherwise skip (don't clobber them).
+            if (deepEqual(readCurrentField(store, patch.id, field), established[field])) {
+                out[field] = patch[field];
+                kept++;
+            }
+        }
+        else {
+            // No paired value to compare against. The recorder always pairs fields,
+            // so this is theoretical; apply to preserve undo functionality.
+            out[field] = patch[field];
+            kept++;
+        }
+    }
+    return kept > 0 ? out : null;
+}
+/**
+ * Filter the ops to apply so they don't clobber concurrent collaborator edits.
+ * See the module docblock. `last-writer-wins` returns the ops unchanged.
+ */
+export function resolveOps(apply, paired, store, policy) {
+    if (policy === 'last-writer-wins')
+        return apply;
+    const established = buildEstablished(paired);
+    const out = [];
+    for (const op of apply) {
+        if (op.kind === 'update') {
+            const filtered = filterStalePatch(store, op.patch, established.get(op.patch.id));
+            if (filtered)
+                out.push({ kind: 'update', modelKey: op.modelKey, patch: filtered });
+        }
+        else if (op.kind === 'updateMany') {
+            const patches = op.patches
+                .map((p) => filterStalePatch(store, p, established.get(p.id)))
+                .filter((p) => p !== null);
+            if (patches.length > 0) {
+                out.push({ kind: 'updateMany', modelKey: op.modelKey, patches });
+            }
+        }
+        else {
+            // create / createMany / delete / deleteMany — structural, applied as-is.
+            out.push(op);
+        }
+    }
+    return out;
+}

package/dist/query/client.d.ts

@@ -3,7 +3,7 @@
  *
  * Thin wrapper over fetch() that:
  *   - POSTs a QueryBatch as JSON
- *   - Handles auth via `credentials: 'include'` (session cookie)
+ *   - Sends the bearer credential via withAuthHeaders (Authorization header)
  *   - Throws on non-2xx responses
  *   - Parses the response into a typed QueryBatchResult
  *
@@ -12,6 +12,7 @@
  * without duplicating the fetch boilerplate.
  */
 import type { QueryBatch, QueryBatchResult } from './types.js';
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
 export interface PostQueryOptions {
     /**
      * Full base URL of the sync server including the `/api` prefix.
@@ -22,14 +23,14 @@ export interface PostQueryOptions {
     /** Timeout in ms for the fetch request. Default: 30000. */
     fetchTimeout?: number;
     /**
-     * Bearer credential — a restricted (`rk_`) API key — attached as
-     * `Authorization: Bearer <token>`. Required for Node consumers
-     * (agent-worker, server-side tests) that have no session cookie to
-     * ride. Browser consumers can omit this and fall back to
-     * `credentials: 'include'`. When both are present the server prefers
-     * the Bearer header (see `apiKeyProvider` in
-     * `apps/sync-server/src/auth`), so passing the token in browser code
-     * is harmless. (Field name predates the Biscuit→opaque-key migration.)
+     * Live bearer credential getter. Preferred over `capabilityToken` because it
+     * is read per request, so token refreshes propagate without reconstructing
+     * query helpers.
+     */
+    getAuthToken?: AuthTokenGetter;
+    /**
+     * Compatibility fallback for callers that have only a copied token string.
+     * New SDK internals should pass `getAuthToken`.
      */
     capabilityToken?: string;
 }

package/dist/query/client.js

@@ -3,7 +3,7 @@
  *
  * Thin wrapper over fetch() that:
  *   - POSTs a QueryBatch as JSON
- *   - Handles auth via `credentials: 'include'` (session cookie)
+ *   - Sends the bearer credential via withAuthHeaders (Authorization header)
  *   - Throws on non-2xx responses
  *   - Parses the response into a typed QueryBatchResult
  *
@@ -13,6 +13,7 @@
  */
 import { z } from 'zod';
 import { translateHttpError } from '../errors.js';
+import { withAuthHeaders } from '../auth/credentialSource.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
 // Each result slot is an array of rows (or an object for bundled
@@ -49,14 +50,10 @@ export async function postQuery(options, batch) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-        const headers = { 'Content-Type': 'application/json' };
-        if (options.capabilityToken) {
-            headers.Authorization = `Bearer ${options.capabilityToken}`;
-        }
+        const headers = withAuthHeaders(options.getAuthToken, { 'Content-Type': 'application/json' }, options.capabilityToken);
         const response = await fetch(url, {
             method: 'POST',
             headers,
-            credentials: 'include',
             body: JSON.stringify(batch),
             signal: controller.signal,
         });

package/dist/react/AbloProvider.d.ts

@@ -1,10 +1,6 @@
 import { type ReactNode } from 'react';
-import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type { SchemaRecord } from '../schema/schema.js';
 import { Ablo } from '../client/Ablo.js';
-import type { AbloPersistence } from '../client/persistence.js';
-import type { SyncEngineConfig, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, SyncLogger, SyncObservabilityProvider } from '../config/index.js';
-import type { UseMutatorsOptions } from './useMutators.js';
-import type { MutatorDefs } from '../mutators/defineMutators.js';
 import type { ActiveIntent, Peer } from '../types/streams.js';
 import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../sync/participants.js';
 import { type SyncStoreContract } from './context.js';
@@ -49,140 +45,41 @@ import { type SyncStoreContract } from './context.js';
  */
 export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
     /**
-     * Schema from `defineSchema()`. Determines the typed hook surface.
-     * This is the only prop most apps pass — start here.
-     */
-    schema: Schema<R>;
-    /**
-     * WebSocket URL of the sync server (`wss://...` or `ws://...`).
-     * Hosted apps omit this.
+     * 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.
      */
-    url?: string;
+    client: Ablo<R>;
     /**
-     * Optional app user id for app-owned fields. Ablo resolves sync
-     * participant identity from auth; this is not required to connect.
+     * 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;
-    /** Team IDs the user belongs to. Expanded into sync groups. */
-    teamIds?: string[];
-    /**
-     * API key for engine bootstrap auth. Used by the bootstrap fetch
-     * path; falls back to `credentials: 'include'` (session cookie)
-     * when unset. Browser apps typically omit this and rely on
-     * same-origin session cookies.
-     */
-    apiKey?: string;
-    /**
-     * Static bearer auth token, sent as `Authorization: Bearer <token>` on the
-     * WebSocket upgrade + HTTP. For a token that must be refreshed (e.g. a
-     * short-lived JWT), prefer {@link getToken}.
-     */
-    authToken?: string | null;
     /**
-     * Async resolver for a short-lived bearer token. Called once before the
-     * engine connects (so the first connection carries a fresh token) and then on
-     * a refresh interval ahead of expiry — each result is pushed via
-     * `engine.setAuthToken` without tearing down the connection. Wire this to
-     * a resolver that mints a short-lived session token (`ek_`/`rk_`) — e.g.
-     * `getSyncCapabilityToken` — or your own. Takes precedence over
-     * {@link authEndpoint}.
-     */
-    getToken?: () => Promise<string | null>;
-    /**
-     * Liveblocks/Stripe-style auth endpoint: a URL on YOUR backend that returns
-     * `{ token }` — the `ek_` ephemeral key your server minted for the logged-in
-     * user with `ablo.sessions.create({ user: { id } })`. The provider POSTs to it
-     * (with cookies) to fetch + refresh the bearer, so the browser carries no
-     * secret. Shorthand for a {@link getToken} that does the fetch; ignored when
-     * `getToken` is set.
-     */
-    authEndpoint?: string;
-    /** Optional Zero-style custom mutators. */
-    mutators?: MutatorDefs<Schema<R>>;
-    /** Options forwarded to the internal `useMutators` call (e.g., `undoScope`). */
-    mutatorOptions?: UseMutatorsOptions<Schema<R>>;
-    /**
-     * Block browser tab close when there are unsynced local writes.
-     * Triggers the standard `beforeunload` "Leave site?" prompt.
-     * Browsers ignore custom messages — do not pass one. Consumers
-     * who want telemetry should read
-     * `useSyncStatus().hasUnsyncedChanges` directly.
+     * Block tab close while there are unsynced local writes (the standard
+     * `beforeunload` prompt). Browsers ignore custom messages — don't pass one.
      */
     preventUnsavedChanges?: boolean;
     /**
-     * Milliseconds to tolerate connection loss before `useSyncStatus()`
-     * flips to `disconnected`. Defaults to 5000. Set to 0 to
-     * disable the grace period (immediate transition).
-     *
-     * v0.3.0 scope: reserved for future wiring. Current transition is
-     * driven by the engine's built-in state machine.
-     */
-    lostConnectionTimeout?: number;
-    /**
-     * Fired when the server rejects the session. The provider has
-     * ALREADY called `engine.purge()` (disposed + wiped IndexedDB) by
-     * the time this runs — the callback is for app-level side effects
-     * (e.g., redirect to sign-in, clear analytics identity).
+     * 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 errors,
-     * WebSocket errors, uncaught `postBootstrap` exceptions. Use for
-     * Sentry / Datadog. Consumers who only want errors inside React
-     * can use the `useErrorListener()` hook instead.
+     * Fired on any error the provider surfaces (engine/WebSocket/bootstrap). For
+     * Sentry/Datadog. React-only consumers can use `useErrorListener()` instead.
      */
     onError?: (error: Error) => void;
-    observability?: SyncObservabilityProvider;
-    logger?: SyncLogger;
-    mutationExecutor?: MutationExecutor;
-    mutationDispatcher?: MutationDispatcher;
-    sessionErrorDetector?: SessionErrorDetector;
-    onlineStatus?: OnlineStatusProvider;
-    configOverrides?: SyncEngineConfig;
-    /**
-     * Raw sync-group strings for the initial connection. Prefer {@link scope} —
-     * the model form (`{ decks: deckId }`) that the engine resolves through the
-     * schema's `scope`, so you never hand-write a `deck:<id>` string. Both merge.
-     */
-    syncGroups?: string[];
-    /**
-     * Model-form connection scope: `{ decks: deckId, documents: documentId }` or
-     * entity refs. Resolved through the schema's per-model `scope` into group
-     * strings (so typename `SlideDeck` → `deck:<id>`), unioned with {@link syncGroups}.
-     * Memoize the object if it's derived, to avoid rotating the engine each render.
-     */
-    scope?: ParticipantScope;
-    bootstrapBaseUrl?: string;
-    maxPoolSize?: number;
-    /**
-     * Local persistence mode for the underlying `Ablo` client. Defaults
-     * to `volatile` — pass `'indexeddb'` to opt back into offline-queue +
-     * reload-surviving cache in a browser. See `AbloOptions.persistence`
-     * for the full semantics.
-     */
-    persistence?: AbloPersistence;
-    /**
-     * How aggressively this provider pulls baseline state at startup.
-     *
-     *  - `'full'` (default): pull every delta in the configured sync
-     *    groups before the engine reports ready — a local replica of the
-     *    org's tenant plane. Right for collaborative editors and any page
-     *    that reads a lot of shared state.
-     *  - `'none'`: open the connection and process live deltas only — no
-     *    baseline fetch. Reads round-trip via `ablo.<model>.retrieve(...)`
-     *    and subscriptions populate the pool lazily. Right for read-light
-     *    pages (a mostly-static dashboard, a settings screen) that don't
-     *    want to download the whole org to render.
-     *
-     * Note: `'none'` still opens the realtime connection — it skips the
-     * baseline pull, not the socket. A fully connection-free mode for
-     * pages that do zero multiplayer is a separate follow-up (the socket
-     * open lives inside `engine.ready()`, so deferring it needs
-     * engine-level lazy-connect support, not just a provider prop).
-     *
-     * Mirrors `AbloOptions.bootstrapMode`. Changing it rotates the engine.
-     */
-    bootstrapMode?: 'full' | 'none';
+    /** @internal placeholder so the old WS-URL prop shape doesn't silently leak in. */
+    url?: never;
     /**
      * Rendered in place of `children` during the *first* bootstrap pass —
      * while the engine is actively transitioning from `initial` →