@abloatai/ablo 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 0.9.0
+
+A single options object for every model verb, and a disposable `claim` handle.
+
+### Breaking Changes
+
+- **One options object per verb.** `create`, `update`, `delete`, and the async
+  server `retrieve` each take a single options object instead of positional
+  arguments, so the id, the data, and every modifier live as named siblings:
+  `create({ data, id? })`, `update({ id, data, ...options })`,
+  `delete({ id, ...options })`, `retrieve({ id, ...options })`. Reactive local
+  reads stay on `get(id)` (synchronous) —
+  `useAblo((ablo) => ablo.tasks.get(id))`.
+
+  ```diff
+  - await ablo.tasks.update(id, { status: 'done' }, { wait: 'confirmed' })
+  + await ablo.tasks.update({ id, data: { status: 'done' }, wait: 'confirmed' })
+
+  - await ablo.tasks.retrieve(id)
+  + await ablo.tasks.retrieve({ id })
+
+  - useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask
+  + useAblo((ablo) => ablo.tasks.get(id)) ?? serverTask
+  ```
+
+- **`claim` returns a disposable handle** instead of taking a callback. The
+  handle exposes the fresh row on `.data` and is released on scope exit
+  (`await using`) or explicitly via `.release()`. `claim.state`, `claim.queue`,
+  `claim.release`, and `claim.reorder` also take the options object.
+
+  ```diff
+  - await ablo.tasks.claim(id, async (task) => {
+  -   await ablo.tasks.update(task.id, { status: 'in_review' })
+  - })
+  + await using claim = await ablo.tasks.claim({ id })
+  + const task = claim.data
+  + await ablo.tasks.update({ id: task.id, data: { status: 'in_review' } })
+  ```
+
+## 0.8.0
+
+A callable `claim` coordination namespace and bring-your-own-database support
+via a new `databaseUrl` option.
+
+### Minor Changes
+
+- **Callable `claim` coordination namespace.** Taking a claim and inspecting its
+  state now live under one accessor: `claim(id, work)` acquires a claim and runs
+  `work` while it's held, and `claim.state(id)`, `claim.queue(id)`,
+  `claim.release(id)`, and `claim.reorder(id, order)` cover the surrounding
+  lifecycle. The README leads with the problem (who is allowed to act, and in
+  what order) and the Quick Start now demonstrates `claim` directly.
+
+- **Bring-your-own-database via `databaseUrl`.** Point a project at your own
+  Postgres with `Ablo({ schema, apiKey, databaseUrl })`. Ablo writes synced rows
+  back into your database, so your data stays canonical. Server-side only;
+  defaults to `process.env.DATABASE_URL`. See the data-sources guide for setup
+  and role requirements.
+
+### Breaking
+
+- The flat coordination methods `claimState`, `queue`, `release`, and `reorder`
+  are removed in favor of the `claim` namespace above.
+
+  ```diff
+  - await ablo.task.claimState(id)
+  - await ablo.task.release(id)
+  + await ablo.task.claim.state(id)
+  + await ablo.task.claim.release(id)
+  ```
+
 ## 0.7.0
 
 ### Minor Changes
@@ -293,7 +364,7 @@ The SDK covers exactly three integration shapes. Each has a canonical example in
 ### Env / config
 
 - `ABLO_API_KEY` — required for server-side use.
-- `ABLO_BASE_URL` — optional override for staging / local-dev (defaults to `https://mesh.ablo.finance`). Not a customer-facing self-hosting path.
+- `baseURL` — optional override for private deployments / local-dev (defaults to `wss://api.abloatai.com`).
 - `organizationId` — **no longer required** in `createMesh`. The API key or session binds the caller to one org; the capability mint response echoes it back.
 - `createMeshFromEnv` — removed. `new Ablo({ schema })` auto-reads env.
 

package/README.md

@@ -5,35 +5,40 @@
 [![types](https://img.shields.io/badge/types-included-blue.svg)](#)
 [![runtime](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](#keys--runtime)
 
-Ablo is a typed sync engine for shared app state — the kind that humans,
-server code, and AI agents all edit at once.
+**Let people and AI agents work on the same data without overwriting each other.**
 
-Reach for it when those edits need to show up everywhere in real time, not
-silently overwrite each other, expose who's working on what, and leave a record
-of who changed what.
+When an agent and a person change the same thing at once, work gets lost: one
+edit silently clobbers another, or the agent acts on data that already moved.
+Ablo gives them one shared, typed write path so people, server actions, and
+agents can all work on the same rows without working blind.
+
+The core idea is a **claim**. An agent's work is rarely one instant write; it
+reads something, thinks, calls an LLM or tool, then writes back. While that is
+happening, the row can change underneath it. So before slow work starts, the
+agent claims the row. If someone else is already working on it, `claim` waits,
+re-reads the fresh row, then hands it over. No stale overwrite, no separate
+agent mutation path.
+
+Under the hood, you define a Zod schema once and get typed model clients for
+every actor:
 
 ```txt
 schema -> ablo.<model>.create/retrieve/update/claim(...)
 ```
 
-## Why Ablo
-
-- **Real-time by default.** Every `create` / `update` / `delete` fans out
-  confirmed deltas to all subscribers — humans and agents — with no separate
-  "multiplayer mode" to switch on.
-- **No silent clobbers.** Writes are guarded against stale reads, and `claim`
-  holds a row across a slow read → LLM → write gap so concurrent edits queue
-  instead of overwriting.
-- **Built for agents.** See who's mid-edit (`claimState` / `queue`), coordinate a
-  fair line, and ship an `llms.txt` so coding agents integrate from the real API.
-- **Typed end to end.** Your Zod schema produces typed model proxies
-  (`ablo.<model>.update(...)`), optimistic local reads, and reactive React hooks.
-- **Bring your own auth and database.** Ablo scopes realtime data to *sync
-  groups* from your existing identity, and can leave your database as the source
-  of truth via a Data Source.
-
-**Built for:** collaborative editors, AI agent workflows, internal tools, and any
-app where multiple actors mutate shared state and everyone must see it live.
+The schema is the public contract. It gives you typed model methods, realtime
+fanout, React selectors, agent writes, and the HTTP/Data Source shape for
+non-JavaScript services. Every confirmed change shows up everywhere, and active
+claims are visible while the work is still in progress.
+
+[Get started ↓](#quick-start) · point your coding agent at the shipped `llms.txt`
+
+It works with the auth and database you already have: realtime data is scoped to
+*sync groups* from your own identity, and your database can stay the source of
+truth via a Data Source.
+
+**Built for** collaborative editors, AI agent workflows, and internal tools —
+anywhere people and agents change shared state and everyone has to see it live.
 
 ## Set up
 
@@ -79,16 +84,22 @@ const ablo = Ablo({
 await ablo.ready();
 
 const created = await ablo.weatherReports.create({
-  location: 'Stockholm',
-  status: 'pending',
+  data: {
+    location: 'Stockholm',
+    status: 'pending',
+  },
 });
 
-const updated = await ablo.weatherReports.update(created.id, {
-  status: 'ready',
-  forecast: 'Light rain, 13C',
-});
+// An agent claims the row, does its slow work, then writes back. While the
+// claim is held nobody else can overwrite it; anyone else who tries waits in
+// line and re-reads the result. This is the whole point of Ablo.
+await using claim = await ablo.weatherReports.claim({ id: created.id });
+const report = claim.data;
+const forecast = await fetchForecast(report.location); // slow: API or LLM call
+await ablo.weatherReports.update({ id: report.id, data: { status: 'ready', forecast } });
 
-console.log({ id: updated.id, status: updated.status });
+const ready = ablo.weatherReports.get(created.id);
+console.log({ id: ready.id, status: ready.status });
 
 await ablo.dispose();
 ```
@@ -99,31 +110,30 @@ Expected output:
 { id: '...', status: 'ready' }
 ```
 
-Pass `schema` to get typed models like `ablo.weatherReports.update(...)`.
-
 ## Reading
 
-`retrieve(id)` returns one row from the local cache — synchronous, no round-trip.
-`list(...)` filters and sorts what's already synced; it's also synchronous, and
-reactive under `useAblo`/`subscribe`. `load(...)` fetches from the server when a
-row may not be local yet.
+Two ways to read, depending on whether you can wait. `get(id)` / `getAll({ where })`
+/ `getCount({ where })` are instant — they read what's already local and re-render
+on their own when it changes, so they're what your UI uses. `retrieve(id)` /
+`list({ where })` go ask the server and return a `Promise`, for when you need the
+authoritative answer right now.
 
 ```ts
-ablo.weatherReports.retrieve('report_stockholm');
+ablo.weatherReports.get('report_stockholm');
 
-const pending = ablo.weatherReports.list({
+const pending = ablo.weatherReports.getAll({
   where: { status: 'pending' },
   orderBy: { location: 'asc' },
   limit: 20,
 });
 
-const ready = await ablo.weatherReports.load({
+const ready = await ablo.weatherReports.list({
   where: { status: 'ready' },
   type: 'complete',
 });
 ```
 
-An array value in `where` means `IN`. On `load`, `type: 'complete'` waits for
+An array value in `where` means `IN`. On `list`, `type: 'complete'` waits for
 the server; `'unknown'` returns what's local now and refreshes in the background.
 
 ## Writing
@@ -137,7 +147,7 @@ matter day to day:
 | `idempotencyKey` | `string` | Auto-generated per call. Override only when you own the retry boundary (e.g. a job id) so a re-run dedupes server-side. |
 
 ```ts
-await ablo.weatherReports.update(id, { status: 'ready' }, { wait: 'confirmed' });
+await ablo.weatherReports.update({ id, data: { status: 'ready' }, wait: 'confirmed' });
 ```
 
 To guard a write against a row that changed under you, pass `readAt` + `onStale`
@@ -149,33 +159,35 @@ An agent reads a row, thinks for 30s, writes back — and clobbers whatever chan
 meanwhile, or worse, acts on stale state. `claim` holds the row across that gap:
 
 ```ts
-await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  const forecast = await weatherAgent.getWeather(report.location);
-  await ablo.weatherReports.update(report.id, { forecast, status: 'ready' });
-});
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const report = claim.data;
+const forecast = await weatherAgent.getWeather(report.location);
+await ablo.weatherReports.update({ id: report.id, data: { forecast, status: 'ready' } });
 ```
 
 If someone else holds the row, `claim()` waits in a fair queue, then re-reads —
 so `report` is the current row, never a stale snapshot. Reads stay open by
-default; only acting on the row serializes. The claim releases when the callback
-returns or throws.
+default; only acting on the row serializes. The claim releases when the `await
+using` scope exits.
 
 See who's mid-edit before you act — decide to wait, or skip:
 
 ```ts
-ablo.weatherReports.claimState('report_stockholm');
-ablo.weatherReports.queue('report_stockholm');
+ablo.weatherReports.claim.state({ id: 'report_stockholm' });
+ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 
-await ablo.weatherReports.claim(id, async (report) => {
+{
+  await using claim = await ablo.weatherReports.claim({ id, wait: false });
   /* do the held work */
-}, { wait: false });
+}
 
-await ablo.weatherReports.claim(id, async (report) => {
+{
+  await using claim = await ablo.weatherReports.claim({ id, maxQueueDepth: 2 });
   /* do the held work */
-}, { maxQueueDepth: 2 });
+}
 ```
 
-`claimState` returns the holder (or `null`); `queue` returns the line waiting
+`claim.state` returns the holder (or `null`); `claim.queue` returns the line waiting
 behind it. `wait: false` skips rather than waiting when the row is held;
 `maxQueueDepth: 2` bails when two or more are already ahead.
 
@@ -186,17 +198,18 @@ Even an unclaimed write can't land on stale reasoning — the commit is guarded:
 
 ```ts
 try {
-  await ablo.weatherReports.update(id, { status: 'ready' }, { readAt, onStale: 'reject' });
+  await ablo.weatherReports.update({ id, data: { status: 'ready' }, readAt, onStale: 'reject' });
 } catch (e) {
   if (e instanceof AbloStaleContextError) { /* row moved under you — re-read, retry */ }
 }
 ```
 
-> Prefer the callback form for ordinary held work. Manual scoped claims are
-> available for wider lifetimes, but callback claims are the docs default.
+> Use `await using` for ordinary held work — the claim releases when the scope
+> exits. Call `claim.release({ id })` only to give a manually held claim back
+> early.
 
-See [Coordination](./docs/coordination.md) for the full `claim` / `claimState` /
-`queue` / `release` reference.
+See [Coordination](./docs/coordination.md) for the full `claim` / `claim.state` /
+`claim.queue` / `claim.release` reference.
 
 ## React
 
@@ -217,13 +230,13 @@ function App() {
 }
 
 function Report({ id }: { id: string }) {
-  const report = useAblo((ablo) => ablo.weatherReports.retrieve(id));
+  const report = useAblo((ablo) => ablo.weatherReports.get(id));
   const ablo = useAblo();
 
   if (!report) return null;
 
   return (
-    <button onClick={() => ablo?.weatherReports.update(id, { status: 'ready' })}>
+    <button onClick={() => ablo?.weatherReports.update({ id, data: { status: 'ready' } })}>
       {report.status}
     </button>
   );
@@ -277,7 +290,7 @@ each other's changes in real time — that's the default, not a feature you turn
 
 - `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
 - `useAblo(...)` gives React clients the live row, kept current automatically.
-- `ablo.<model>.claim(id)` / `claimState(id)` / `queue(id)` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
+- `ablo.<model>.claim({ id })` / `claim.state({ id })` / `claim.queue({ id })` let humans and agents coordinate (and observe) active work on a row — and the line waiting behind it — before a write lands.
 
 Always write through Ablo — either the SDK model methods
 (`ablo.<model>.create/update/delete`) or the HTTP write endpoint below. If you
@@ -306,7 +319,7 @@ curl https://api.abloatai.com/v1/commits \
 ## Connect Your Database
 
 Every schema model has a backing store. By default, Ablo stores rows for the
-models you declare, so `ablo.weatherReports.create(...)` and `ablo.weatherReports.update(...)`
+models you declare, so `ablo.weatherReports.create({ data })` and `ablo.weatherReports.update({ id, data })`
 write to Ablo-managed state.
 
 If your existing database stays the source of truth, connect it as a Data
@@ -324,7 +337,7 @@ See [Connect Your Database](./docs/data-sources.md) for the integration shape.
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `baseURL` | `string` | `wss://mesh.ablo.finance` | Point at a self-hosted or staging mesh |
+| `baseURL` | `string` | `wss://api.abloatai.com` | Point at a self-hosted or private API |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated
@@ -340,7 +353,7 @@ survives worker / `postMessage` boundaries, where `instanceof` does not:
 
 ```ts
 try {
-  await ablo.weatherReports.update(id, { status: 'ready' }, { readAt, onStale: 'reject' });
+  await ablo.weatherReports.update({ id, data: { status: 'ready' }, readAt, onStale: 'reject' });
 } catch (e) {
   if (e instanceof AbloStaleContextError) { /* row moved under you — re-read, retry */ }
   if ((e as AbloError).type === 'AbloClaimedError') { /* another participant holds it */ }
@@ -372,10 +385,11 @@ contract; there are no retry or timeout knobs to tune.
 ## Production Reference
 
 - [Identity & Sync Groups](./docs/identity.md) — bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
+- [Schema Contract](./docs/schema-contract.md) — one schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, claim coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.
 - [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
-- [Coordination](./docs/coordination.md) — `claim` / `claimState` / `queue` / `release` reference: hold a row across slow agent work, and observe the line waiting behind it.
+- [Coordination](./docs/coordination.md) — `claim` / `claim.state` / `claim.queue` / `claim.release` reference: hold a row across slow agent work, and observe the line waiting behind it.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
 - [Connect Your Database](./docs/data-sources.md) — keep canonical rows in your app database without giving Ablo database credentials.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.

package/dist/BaseSyncedStore.d.ts

@@ -22,6 +22,7 @@ import { Model } from './Model.js';
 import { ModelScope } from './ObjectPool.js';
 import type { Schema } from './schema/schema.js';
 import { type ReaderActions } from './mutators/readerActions.js';
+import type { AuthCredentialSource } from './auth/credentialSource.js';
 /** Constructor type for Model subclasses (accepts abstract classes) */
 export type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
 /** Concrete constructor type for instantiation */
@@ -240,6 +241,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected readonly database: Database;
     protected readonly objectPool: ObjectPool;
     protected readonly modelRegistry: ModelRegistry;
+    protected readonly auth?: AuthCredentialSource;
     /**
      * Schema the store was constructed with. Persisted so the `query`
      * accessor namespace can build typed per-model reader actions lazily
@@ -308,6 +310,8 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
         schema?: TSchema;
         /** Sync server URL for WebSocket connection. Converted to wss:// automatically. */
         url?: string;
+        /** Shared bearer credential source for every auth-aware transport. */
+        auth?: AuthCredentialSource;
     }, config?: SyncedStoreConfig);
     /**
      * Register foreign key indexes for O(1) lookups.
@@ -355,6 +359,24 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * return null.
      */
     protected connectionManager: import('./sync/ConnectionManager.js').ConnectionManager | null;
+    /**
+     * Re-mint hook for the short-lived access credential (the Stripe-style
+     * `ek_`/`rk_`). Wired by the React provider from its `getToken`/`authEndpoint`
+     * — the engine owns WHEN to refresh (a stale-credential probe / an external
+     * nudge), the integrator owns HOW to mint. Mirrors the `getToken` contract:
+     * resolves a token string on success, `null` when the long-lived login is
+     * gone (terminal), and THROWS on a transient/offline failure. Used by
+     * {@link performCredentialRefresh}. Absent ⇒ no silent re-mint (e.g. a static
+     * `apiKey` deployment whose credential source refreshes out-of-band).
+     */
+    private credentialRefresher;
+    /** Single-flight guard so a wake nudge + an in-flight request + a probe don't
+     *  all mint at once (the classic "token thrash → random logout" bug). */
+    private inFlightCredentialRefresh;
+    /** Teardown for the proactive credential lifecycle (refresh timer + wake/
+     *  online/focus listeners) installed by {@link startCredentialLifecycle};
+     *  cleared on {@link disconnect}. Null when no resolver is wired. */
+    private credentialLifecycleTeardown;
     /**
      * Listeners registered via `subscribeSessionError()`. Fired when the
      * WebSocket closes with a session-invalid code (1008/4001/4003) or a
@@ -404,6 +426,57 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
     protected resetBootstrapState(): void;
     /** Perform reconnect: bootstrap + WS reconnect. Returns outcome for state machine. */
     performReconnect(): Promise<'success' | 'session_error' | 'network_error'>;
+    /**
+     * Register the access-credential re-mint hook. Called by the React provider
+     * with a thunk that mints a fresh `ek_`/`rk_` (typically its `getToken`).
+     * See {@link credentialRefresher}.
+     */
+    setCredentialRefresher(refresher: (() => Promise<string | null>) | null): void;
+    /**
+     * Re-mint the short-lived access credential and push it into the credential
+     * source, reporting a tri-state outcome the {@link ConnectionManager} maps to
+     * its FSM. The contract mirrors `getToken` (and PowerSync's `fetchCredentials`
+     * / Liveblocks' `authEndpoint`, but made explicit instead of overloading
+     * return/throw):
+     *   - token string  → `'refreshed'`     (fresh key in place; re-probe & reconnect)
+     *   - `null`        → `'session_error'` (login itself is gone → terminal, sign out)
+     *   - throw         → `'network_error'` (couldn't reach the mint endpoint → transient)
+     *
+     * SINGLE-FLIGHT: concurrent callers (a wake nudge, an in-flight request, the
+     * probe) share one in-flight promise so we never double-mint — the canonical
+     * fix for the "every 401 mints a token → thrash → spurious logout" anti-pattern.
+     *
+     * No refresher wired ⇒ `'refreshed'` (a no-op re-probe): a static-`apiKey`
+     * deployment has no session to re-mint from; its credential source refreshes
+     * out-of-band, so we just re-probe with whatever it currently holds.
+     */
+    performCredentialRefresh(): Promise<'refreshed' | 'session_error' | 'network_error'>;
+    /**
+     * Nudge the connection FSM to re-probe with the current credential. Idempotent
+     * and safe in any state (ignored while `connected`). Call after pushing a
+     * freshly-minted token via `setAuthToken`, or on an OS-wake signal, so a
+     * connection parked in `offline` / `backoff` / `auth_blocked` picks the new
+     * credential up immediately instead of waiting for the 30s watchdog.
+     */
+    nudgeReconnect(): void;
+    /**
+     * Install the access-credential lifecycle the CLIENT owns (this used to live
+     * in the React provider — wrong layer). Two parts:
+     *   1. REACTIVE — register `getToken` as the re-mint hook the FSM calls when a
+     *      probe finds the key stale (`credential_stale`) or on a nudge.
+     *   2. PROACTIVE — keep the short-lived key fresh ahead of trouble: a refresh
+     *      timer inside the TTL, plus re-mint on OS wake / network-online / tab
+     *      focus. Browser-only triggers are env-gated, so Node/agent hosts get
+     *      only the timer (a no-op there — agents use a static `apiKey`, no
+     *      resolver, so this is never called for them).
+     *
+     * Config-driven and invisible, like Supabase's `autoRefreshToken` — consumers
+     * never call a refresh method. Idempotent (a second call replaces the first);
+     * torn down on {@link disconnect}.
+     */
+    startCredentialLifecycle(getToken: () => Promise<string | null>): void;
+    /** Tear down the proactive credential lifecycle (idempotent). */
+    private stopCredentialLifecycle;
     /**
      * Handle an actionType 'G' delta.
      *