@abloatai/ablo 0.25.0 → 0.27.0

package/dist/client/createModelProxy.js

@@ -1,25 +1,23 @@
 /**
- * Per-model client factory.
+ * Builds the typed client for a single schema model — the object reached as
+ * `ablo.<model>`.
  *
- * Mirrors Anthropic SDK's per-endpoint module pattern: each model client
- * has its own file, and the root client just instantiates
- * one per model. Extracted from `Ablo.ts` so the proxy logic is
- * testable in isolation and the constructor doesn't carry it.
- *
- * Each schema model gets one `ModelOperations<T, CreateInput>` —
- * exposes the async server reads `retrieve` / `list`, the synchronous
- * local-graph snapshots `get` / `getAll` / `getCount`, the writes
- * `create` / `update` / `delete`, the coordination namespace `claim`
- * (`claim({ id })` plus `claim.state` / `claim.queue` / `claim.release` /
- * `claim.reorder`), and `onChange`. The factory returns a plain object; the
- * client assembles the `ablo.<model>` lookup table from these.
+ * Each schema model gets one {@link ModelOperations}: the async server reads
+ * `retrieve` and `list`, the synchronous local-graph snapshots `get`, `getAll`,
+ * and `getCount`, the writes `create`, `update`, and `delete`, the coordination
+ * namespace `claim` (callable as `claim({ id })`, plus `claim.state`,
+ * `claim.queue`, `claim.release`, and `claim.reorder`), `watch`, and `onChange`.
+ * The factory returns a plain object; the client assembles the `ablo.<model>`
+ * lookup table from one of these per model.
  */
 import { autorun } from 'mobx';
-import { AbloClaimedError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
+import { AbloClaimedError, AbloStaleContextError, AbloValidationError, formatClaimedErrorMessage, toAbloError, } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { Model, modelAsRow } from '../Model.js';
 import { toMs } from '../utils/duration.js';
+import { LEASE_TTL_MS } from '../wire/protocol.js';
+import { heartbeatCadenceMs, resolveHeartbeatOptions, startClaimHeartbeatLoop, } from './claimHeartbeatLoop.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
 import { ModelScope } from '../types/index.js';
 const modelClientMeta = new WeakMap();
@@ -34,15 +32,15 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         throw new AbloValidationError(`Ablo: schema model "${schemaKey}" resolved to "${registeredModelName}", ` +
             'but no matching constructor was registered.', { code: 'model_not_registered' });
     }
-    // The coordination plane (claims/claims) must speak the SAME wire dialect
-    // as the commit plane: the lowercased TYPENAME (`task`), not the schema key
-    // (`tasks`). The server's commit-time claim guard probes the lease store
-    // with the commit op's model name; a lease recorded under the schema key
-    // never collides with it — which silently disarmed the guard for every
-    // model whose schema key differs from its typename (i.e. nearly all of
-    // them, plural key vs singular typename). Public surfaces (Claim.
-    // target.model) keep the schema key; only the wire/coordination targets
-    // use this.
+    // The coordination plane must speak the same wire dialect as the commit
+    // plane: the lowercased typename (`task`), not the schema key (`tasks`). The
+    // server's commit-time claim guard probes the lease store with the commit
+    // operation's model name, so a lease recorded under the schema key never
+    // matches — which would silently disarm the guard for every model whose
+    // schema key differs from its typename (a plural key against a singular
+    // typename, i.e. nearly all of them). Public surfaces such as
+    // `Claim.target.model` keep the schema key; only the wire and coordination
+    // targets use this.
     const wireModel = registeredModelName.toLowerCase();
     // Last-line guarantee for the public surface: any rejection from a lower
     // layer (transport timeout, IndexedDB failure, a third-party throw) is
@@ -75,19 +73,22 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         await syncClient.waitForConfirmation(model.getModelName(), model.id);
     };
     // Claims this proxy currently holds, keyed by entity id. Lets the flat
-    // `release({ id })` and `update({ id, data })` find the lease + snapshot a `claim({ id })`
-    // took — no per-call handle. Released on dispose, explicit release, or TTL.
+    // `release({ id })` and `update({ id, data })` find the lease and snapshot a
+    // `claim({ id })` took, without a per-call handle. Released on dispose,
+    // explicit release, or TTL expiry.
     //
-    // `target` / `reason` / `expiresAt` are kept alongside the lease so
+    // `target`, `reason`, and `expiresAt` are kept alongside the lease so
     // `claim.state` can synthesize a self-claim: the server excludes a holder's
-    // own presence frames, so the local proxy is the ONLY place that knows "I
-    // hold this." `expiresAt` is the client's best estimate from the requested
-    // TTL (a genuine epoch-ms expiry, not a fabricated watermark), defaulting to
-    // the server's keepalive lease window when no TTL was requested.
+    // own presence frames, so this proxy is the only place that knows the client
+    // holds the row. `expiresAt` is the client's best estimate from the requested
+    // TTL (a real epoch-millisecond expiry, not a fabricated watermark), defaulting
+    // to the server's keepalive lease window when no TTL was requested.
     const activeClaims = new Map();
-    // Server keepalive lease window (Hub `LEASE_RENEW_TTL_MS`). The fallback
-    // expiry estimate when a claim is taken without an explicit TTL.
-    const DEFAULT_LEASE_TTL_MS = 90_000;
+    // Server keepalive lease window — the same `LEASE_TTL_MS` the wire protocol
+    // declares, so the client's estimate and the server's lease cannot drift.
+    // This is the fallback expiry estimate when a claim is taken without an
+    // explicit TTL.
+    const DEFAULT_LEASE_TTL_MS = LEASE_TTL_MS;
     const isClaimHandle = (value) => typeof value === 'object' &&
         value !== null &&
         value.object === 'claim' &&
@@ -121,9 +122,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     };
     const mutationOptions = (params) => {
         const { id: _id, data: _data, claim: _claim, ...rest } = params;
-        // THE write-options schema — runtime twin of the compile-time params.
-        // Catches plain-JS callers (`onStale: 'rejct'`) at the call site with
-        // a typed error instead of a silent no-op or a server 400.
+        // The write-options schema — the runtime twin of the compile-time params.
+        // Catches plain-JavaScript callers (for example `onStale: 'rejct'`) at the
+        // call site with a typed error instead of a silent no-op or a server 400.
         assertWriteOptions(rest, `${schemaKey} write`);
         return rest;
     };
@@ -139,12 +140,12 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
         }
         const { id, ...options } = params;
-        // Is someone ELSE already on this target? Read the local coordination
-        // snapshot up front — it decides whether we'll need to re-read after the
-        // claim (a free / already-mine target can't have changed under us).
+        // Is someone else already on this target? Read the local coordination
+        // snapshot up front — it decides whether a re-read is needed after the
+        // claim (a free or already-held target cannot have changed underneath us).
         const held = collaboration.state({ model: wireModel, id });
         const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
-        const failFast = options?.queue === false;
+        const failFast = options.queue === false;
         // Fail-fast (`queue: false`): if another participant already holds it,
         // reject now instead of queuing. Best-effort at the client (a racing
         // claim not yet synced into our snapshot slips through here) — the
@@ -152,13 +153,13 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // the loser's first write. For work-distribution dedup that's exactly
         // right: don't wait (that would double-process), skip.
         if (failFast && contended) {
-            const claim = held ? claimContextFromClaim(held) : undefined;
+            const claim = claimContextFromClaim(held);
             throw new AbloClaimedError(formatClaimedErrorMessage({
                 targetLabel: `${registeredModelName}/${id}`,
-                heldBy: held?.heldBy,
+                heldBy: held.heldBy,
                 claim,
-                fallback: `${registeredModelName}/${id} is held by ${held?.heldBy ?? 'another participant'}.`,
-            }), { code: 'entity_claimed', claims: claim ? [claim] : undefined });
+                fallback: `${registeredModelName}/${id} is held by ${held.heldBy ?? 'another participant'}.`,
+            }), { code: 'entity_claimed', claims: [claim] });
         }
         // Ensure the row exists locally before claiming.
         let model = objectPool.get(id);
@@ -169,65 +170,65 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         if (!model) {
             throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
         }
-        // Write-intent: enter the entity scope BEFORE acquiring the lease so the
-        // holder's claim presence broadcasts to whoever is in this entity group —
-        // including a peer that subscribed just before us. Pinning before the
-        // lease (rather than after) closes the subscribe-vs-broadcast race: the
-        // server fans `broadcastPresenceChange` out at claim time, so we must be
-        // in the group when `createClaim` lands. Awaited because the broadcast
-        // ordering depends on it; still soft (the store swallows reconcile errors).
+        // Write intent: enter the entity scope before acquiring the lease so the
+        // holder's claim presence broadcasts to everyone in this entity group,
+        // including a peer that subscribed just before us. Pinning before the lease
+        // rather than after closes the subscribe-versus-broadcast race: the server
+        // fans presence out at claim time, so this client must be in the group when
+        // the claim lands. Awaited because the broadcast ordering depends on it;
+        // still best-effort (the store swallows reconcile errors).
         await collaboration.pinScope?.({ [schemaKey]: id });
-        // Acquire the lease. Default (`queue` !== false) goes through the server's
-        // fair FIFO queue — `queue: true` resolves only once the lease is genuinely
-        // ours, blocking behind any current holder, with no TOCTOU gap (the server
-        // orders contenders). Fail-fast skips the queue: we already rejected an
-        // observed conflict above, so this just records our lease.
+        // Acquire the lease. By default (`queue` is not false) this goes through the
+        // server's fair FIFO queue: `queue: true` resolves only once the lease is
+        // genuinely ours, blocking behind any current holder, with no check-then-act
+        // gap because the server orders contenders. Fail-fast skips the queue: an
+        // observed conflict was already rejected above, so this just records the lease.
         const lease = await collaboration.createClaim({
             target: {
                 model: wireModel,
                 id,
-                ...(options?.field ? { field: options.field } : {}),
-                ...(options?.path ? { path: options.path } : {}),
-                ...(options?.range ? { range: options.range } : {}),
+                ...(options.field ? { field: options.field } : {}),
+                ...(options.path ? { path: options.path } : {}),
+                ...(options.range ? { range: options.range } : {}),
                 ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
             },
-            reason: options?.reason ?? 'editing',
-            ttl: options?.ttl,
+            reason: options.reason ?? 'editing',
+            ttl: options.ttl,
             queue: !failFast,
-            maxQueueDepth: options?.maxQueueDepth,
+            maxQueueDepth: options.maxQueueDepth,
         });
-        // Only when we actually waited behind another holder can the row have
-        // changed underneath us — re-read so the claimed snapshot reflects what
-        // they committed before releasing. Two signals, either suffices:
-        //   - `lease.waited` — the server granted via `claim_granted`, i.e. we
-        //     provably queued behind a holder. Authoritative; works even when
-        //     the local snapshot is blind (claim fan-out is entity-scoped, so
-        //     org-wide-subscribed clients never observe peers' claims).
-        //   - `contended` — the local snapshot saw a holder up front. Kept for
-        //     the no-queue paths where no grant frame exists.
+        // Only when the claim actually waited behind another holder can the row have
+        // changed underneath us — re-read so the claimed snapshot reflects what that
+        // holder committed before releasing. Either of two signals suffices:
+        //   - `lease.waited` — the server granted the claim after the client
+        //     provably queued behind a holder. Authoritative; it works even when the
+        //     local snapshot is blind, since claim fan-out is entity-scoped and a
+        //     broadly-subscribed client never observes peers' claims.
+        //   - `contended` — the local snapshot saw a holder up front. Kept for the
+        //     no-queue paths, where no grant frame exists.
         if ((contended || lease.waited === true) && !failFast) {
-            // `type: 'complete'` forces the round-trip: the hydration ledger
-            // otherwise serves the LOCAL row for an already-hydrated id, and the
-            // holder's final write may not have fanned out to us yet — the exact
-            // stale-snapshot race this re-read exists to close.
+            // `type: 'complete'` forces the round-trip: the hydration ledger would
+            // otherwise serve the local row for an already-hydrated id, and the
+            // holder's final write may not have fanned out yet — the exact
+            // stale-snapshot race this re-read closes.
             await load({ where: [['id', id]], type: 'complete' });
             model = objectPool.get(id) ?? model;
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
-        const reason = options?.reason ?? 'editing';
+        const reason = options.reason ?? 'editing';
         // The self-claim's `ClaimTarget` mirrors what a peer's `claim.state` would
-        // report (`state` maps `held.target.model` → `type`), so a holder and a
-        // peer see the SAME target.type for one row — the wire model token.
+        // report (`state` maps `held.target.model` to `type`), so a holder and a
+        // peer see the same `target.type` for one row — the wire model token.
         const selfTarget = {
             type: wireModel,
             id,
-            ...(options?.field ? { field: options.field } : {}),
-            ...(options?.path ? { path: options.path } : {}),
-            ...(options?.range ? { range: options.range } : {}),
+            ...(options.field ? { field: options.field } : {}),
+            ...(options.path ? { path: options.path } : {}),
+            ...(options.range ? { range: options.range } : {}),
             ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
         };
-        const expiresAt = Date.now() +
-            (options?.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS);
+        const ttlMs = options.ttl !== undefined ? toMs(options.ttl) : DEFAULT_LEASE_TTL_MS;
+        const expiresAt = Date.now() + ttlMs;
         activeClaims.set(id, {
             lease,
             snapshot,
@@ -238,24 +239,57 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         const target = {
             type: schemaKey,
             id,
-            ...(options?.field ? { field: options.field } : {}),
-            ...(options?.path ? { path: options.path } : {}),
-            ...(options?.range ? { range: options.range } : {}),
+            ...(options.field ? { field: options.field } : {}),
+            ...(options.path ? { path: options.path } : {}),
+            ...(options.range ? { range: options.range } : {}),
             ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
         };
-        const release = () => releaseClaim(id);
+        // A beat resolves with the server's extended expiry; keep the local
+        // self-claim estimate in step so `claim.state` renders the real window,
+        // and surface every answer through `onHeartbeat` (pressure signal).
+        const heartbeat = async (beatOptions) => {
+            if (!lease.heartbeat) {
+                throw new AbloValidationError('This claim handle has no heartbeat wiring, which the standard Ablo({ schema, apiKey }) client provides on every claim. This appears only when a claim is minted through an internal path that predates heartbeats.', { code: 'claim_not_wired' });
+            }
+            const resolved = resolveHeartbeatOptions(beatOptions);
+            const beat = await lease.heartbeat({
+                ttl: resolved.ttl ?? options.ttl,
+                ...(resolved.details !== undefined ? { details: resolved.details } : {}),
+            });
+            const held = activeClaims.get(id);
+            if (held)
+                held.expiresAt = beat.expiresAt;
+            options.onHeartbeat?.(beat);
+            return beat;
+        };
+        // Opt-in auto-heartbeat: the loop beats until release, and a definitive
+        // loss stops it and surfaces through `onHeartbeatLost`.
+        const stopHeartbeatLoop = options.heartbeat
+            ? startClaimHeartbeatLoop({
+                beat: () => heartbeat(),
+                intervalMs: heartbeatCadenceMs(ttlMs, options.heartbeat),
+                ...(options.onHeartbeatLost
+                    ? { onLost: options.onHeartbeatLost }
+                    : {}),
+            })
+            : undefined;
+        const release = () => {
+            stopHeartbeatLoop?.();
+            return releaseClaim(id);
+        };
         return {
             object: 'claim',
             id: lease.id,
             readAt: snapshot.stamp,
             target,
             reason,
-            ...(options?.description ? { description: options.description } : {}),
+            ...(options.description ? { description: options.description } : {}),
             data: modelAsRow(model),
             release,
             revoke: () => {
                 void release();
             },
+            heartbeat,
             [Symbol.asyncDispose]: release,
         };
     };
@@ -266,15 +300,15 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // are the same object.
     const claimApi = Object.assign(guard(claim), {
         state(params) {
-            // Read-interest: a passive observer subscribing to a row's claim state
-            // must enter that row's entity scope, or it sits on `org:`/`user:`
-            // groups only and never receives the holder's entity-scoped claim
-            // presence. Soft + fire-and-forget — never blocks or rejects the read.
+            // Read interest: a passive observer of a row's claim state must enter that
+            // row's entity scope, or it sits only on broader `org:`/`user:` groups and
+            // never receives the holder's entity-scoped claim presence. Best-effort
+            // and fire-and-forget — it never blocks or rejects the read.
             void collaboration?.enterScope?.({ [schemaKey]: params.id });
-            // Self-awareness: the server excludes a holder's OWN presence frames and
-            // the client skips them, so `state` returns null for a row WE hold.
-            // Synthesize the active claim for self from the stored lease so the
-            // holder sees its own claim (the JSDoc contract on `claim.state`).
+            // Self-awareness: the server excludes a holder's own presence frames and
+            // the client skips them, so `state` would return null for a row this client
+            // holds. Synthesize the active claim from the stored lease so the holder
+            // sees its own claim, honoring the documented contract on `claim.state`.
             const own = activeClaims.get(params.id);
             if (own) {
                 return {
@@ -303,10 +337,10 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     });
     const operations = {
         retrieve: guard(async (params) => {
-            // Read-interest enrolment: READ a row → enter its entity scope, so a
-            // Node/agent client lands in the same group the holder's claim presence
-            // fans out on and `claim.state`/`claim.queue` report peers. Soft +
-            // fire-and-forget — never make the read reject or slower.
+            // Read-interest enrolment: reading a row enters its entity scope, so a
+            // client lands in the same group the holder's claim presence fans out
+            // on and `claim.state`/`claim.queue` report peers. Best-effort and
+            // fire-and-forget — it never makes the read reject or run slower.
             void collaboration?.enterScope?.({ [schemaKey]: params.id });
             const rows = await load({
                 ...params,
@@ -315,9 +349,8 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             });
             return rows[0];
         }),
-        // NB: no auto scope enrolment on bulk `list`/`getAll` — that would
-        // subscribe to an unbounded set of rows' entity groups. Bulk-list scope
-        // enrolment is a deliberate follow-up (a bounded, opt-in policy).
+        // No automatic scope enrolment on bulk `list`/`getAll`: that would subscribe
+        // to an unbounded set of rows' entity groups.
         list: guard(load),
         get(id) {
             return objectPool.get(id);
@@ -338,8 +371,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             if (options?.filter) {
                 result = result.filter(options.filter);
             }
-            if (options?.orderBy) {
-                const [field, dir] = Object.entries(options.orderBy)[0];
+            const orderEntry = options?.orderBy ? Object.entries(options.orderBy)[0] : undefined;
+            if (orderEntry) {
+                const [field, dir] = orderEntry;
                 result = [...result].sort((a, b) => {
                     const av = a[field];
                     const bv = b[field];
@@ -367,11 +401,11 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 if (!collaboration) {
                     throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
                 }
-                // Write-intent: enter the new row's entity scope BEFORE acquiring the
-                // create-claim so the holder's claim presence broadcasts to whoever is
-                // already in this entity group (closing the subscribe-vs-broadcast
+                // Write intent: enter the new row's entity scope before acquiring the
+                // create-claim so the holder's claim presence broadcasts to everyone
+                // already in this entity group (closing the subscribe-versus-broadcast
                 // race — see `takeClaim`). Released with the lease in the `finally`
-                // below. Awaited for broadcast ordering; still soft.
+                // below. Awaited for broadcast ordering; still best-effort.
                 await collaboration.pinScope?.({ [schemaKey]: id });
                 autoLease = await collaboration.createClaim({
                     target: {
@@ -388,10 +422,10 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     maxQueueDepth: claim.maxQueueDepth,
                 });
             }
-            // Default `organizationId` from the client's identity exactly like the
-            // mutator path (`buildModelForCreate`) — without this, a caller that
-            // omits it creates an org-unscoped row on one write door but not the
-            // other. An explicit value in `data` still wins via the spread.
+            // Default `organizationId` from the client's identity, matching the other
+            // write path — without this, a caller that omits it would create an
+            // org-unscoped row on one write path but not the other. An explicit value
+            // in `data` still wins via the spread.
             const orgDefault = params.data.organizationId ??
                 syncClient.getOrganizationId();
             const model = new ModelClass({
@@ -477,7 +511,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         return await operations.update({ ...params, claim: handle });
                     }
                     finally {
-                        await handle.release?.();
+                        await handle.release();
                     }
                 }
                 const { id } = params;
@@ -511,10 +545,10 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         ...opts,
                         ...(handle ? { claim: { id: handle.id } } : {}),
                     };
-                // Local user update: `applyChanges` keeps change tracking ON so
-                // the edited fields land in `modifiedProperties` and actually get
-                // sent to the server. (`updateFromData` is the hydration path and
-                // would discard the tracking → empty `input: {}` no-op mutation.)
+                // Local user update: `applyChanges` keeps change tracking on so the
+                // edited fields land in `modifiedProperties` and are actually sent to
+                // the server. (`updateFromData` is the hydration path and would discard
+                // the tracking, producing an empty `input: {}` no-op mutation.)
                 model.applyChanges(params.data);
                 syncClient.update(model, effective);
                 await waitForMutation(model, effective);
@@ -533,17 +567,17 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     await operations.delete({ ...params, claim: handle });
                 }
                 finally {
-                    await handle.release?.();
+                    await handle.release();
                 }
                 return;
             }
             const { id } = params;
             const model = objectPool.get(id);
-            // Idempotent delete (AIP-135 for client-assigned ids): "ensure absent". A
-            // row that isn't in our replicated view is already gone from our
-            // perspective, so a delete is a no-op success — not an `entity_not_found`
-            // error. This matches the HTTP client (which never threw here) and makes
-            // delete safe to retry / race (two actors deleting the same row).
+            // Idempotent delete: "ensure absent". A row that isn't in this client's
+            // replicated view is already gone from its perspective, so a delete is a
+            // no-op success rather than an `entity_not_found` error. This matches the
+            // HTTP client and makes delete safe to retry or race (two actors deleting
+            // the same row).
             if (!model)
                 return;
             const claimed = activeClaims.get(id);

package/dist/client/credentialEndpoint.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Support for the endpoint-string form of `apiKey`.
+ *
+ * With `Ablo({ schema, apiKey: '/api/ablo-session' })`, you point the client at
+ * your own session-mint route and the client owns the exchange: it POSTs to the
+ * endpoint, parses the minted token, keeps it fresh, and classifies failures
+ * onto the resolver's three outcomes. The string form covers the common case;
+ * the function form of `apiKey` remains the escape hatch for custom headers,
+ * bodies, or non-HTTP mints.
+ *
+ * The form is detected by prefix: a string starting with `/`, `http://`, or
+ * `https://` is an endpoint, and anything else is a literal key. Ablo keys are
+ * prefixed (`sk_`/`pk_`/`ek_`/`rk_`), so the two shapes cannot collide. An
+ * `ABLO_API_KEY` environment value is never treated as an endpoint — it is
+ * always a literal key (see `resolveApiKey`).
+ *
+ * Wire contract:
+ *   POST <endpoint>  (same-origin, `credentials: 'include'` so cookies flow)
+ *   → 200 `{ token, expiresAt? }`       a fresh short-lived `ek_`/`rk_`
+ *   → 200 `{ token: null }` or 401/403  the login itself is gone (sign out)
+ *   → anything else                     transient — retry, do not sign out
+ *
+ * The three-way mapping is the reason to build this in. Hand-written token
+ * fetchers routinely get it wrong — mapping any non-OK response to `null` signs
+ * the user out on a 500. Encoded here once, every consumer inherits the correct
+ * split between a terminal sign-out and a transient retry.
+ */
+/**
+ * An async callable that resolves the current credential. It serves two uses:
+ * credential rotation (for example against AWS STS, GCP IAM, or Vault) and the
+ * short-lived per-user browser path (minting a fresh `ek_`/`rk_` from the
+ * signed-in session). It is re-exported from `./auth` so existing import paths
+ * keep working, and defined here so the resolver it types has no import cycle.
+ *
+ * The contract has three outcomes: resolve a token; resolve `null` when the
+ * login itself is gone (terminal — the credential lifecycle treats this as
+ * `session_expired` and signs out); or throw on a transient failure (back off
+ * and retry, without signing out). A long-lived static `apiKey` string needs
+ * none of this and is used as-is.
+ */
+export type ApiKeySetter = () => Promise<string | null>;
+/**
+ * Is this `apiKey` string a session-mint endpoint rather than a literal key?
+ * Prefix rule: `/relative/path`, `http://…`, or `https://…`.
+ */
+export declare function isCredentialEndpoint(value: string): boolean;
+/**
+ * Builds the resolver behind an endpoint-string `apiKey`. It follows the
+ * {@link ApiKeySetter} contract end to end:
+ *   - resolves the minted token string on success;
+ *   - resolves `null` when the login is gone (a 401 or 403, or an explicit
+ *     `{ token: null }`) — terminal, so the client signs out;
+ *   - throws on anything transient (a network failure, a 5xx or 429, or a
+ *     malformed response) — so the lifecycle backs off and retries without
+ *     signing out.
+ *
+ * A relative endpoint invoked on a server (where `fetch` has no origin) throws,
+ * which is transient by contract; the credential lifecycle translates that exact
+ * failure into an actionable "use an absolute URL server-side" warning.
+ */
+export declare function createEndpointCredentialResolver(endpoint: string): ApiKeySetter;

package/dist/client/credentialEndpoint.js

@@ -0,0 +1,86 @@
+/**
+ * Support for the endpoint-string form of `apiKey`.
+ *
+ * With `Ablo({ schema, apiKey: '/api/ablo-session' })`, you point the client at
+ * your own session-mint route and the client owns the exchange: it POSTs to the
+ * endpoint, parses the minted token, keeps it fresh, and classifies failures
+ * onto the resolver's three outcomes. The string form covers the common case;
+ * the function form of `apiKey` remains the escape hatch for custom headers,
+ * bodies, or non-HTTP mints.
+ *
+ * The form is detected by prefix: a string starting with `/`, `http://`, or
+ * `https://` is an endpoint, and anything else is a literal key. Ablo keys are
+ * prefixed (`sk_`/`pk_`/`ek_`/`rk_`), so the two shapes cannot collide. An
+ * `ABLO_API_KEY` environment value is never treated as an endpoint — it is
+ * always a literal key (see `resolveApiKey`).
+ *
+ * Wire contract:
+ *   POST <endpoint>  (same-origin, `credentials: 'include'` so cookies flow)
+ *   → 200 `{ token, expiresAt? }`       a fresh short-lived `ek_`/`rk_`
+ *   → 200 `{ token: null }` or 401/403  the login itself is gone (sign out)
+ *   → anything else                     transient — retry, do not sign out
+ *
+ * The three-way mapping is the reason to build this in. Hand-written token
+ * fetchers routinely get it wrong — mapping any non-OK response to `null` signs
+ * the user out on a 500. Encoded here once, every consumer inherits the correct
+ * split between a terminal sign-out and a transient retry.
+ */
+/**
+ * Is this `apiKey` string a session-mint endpoint rather than a literal key?
+ * Prefix rule: `/relative/path`, `http://…`, or `https://…`.
+ */
+export function isCredentialEndpoint(value) {
+    return value.startsWith('/') || /^https?:\/\//i.test(value);
+}
+/**
+ * Builds the resolver behind an endpoint-string `apiKey`. It follows the
+ * {@link ApiKeySetter} contract end to end:
+ *   - resolves the minted token string on success;
+ *   - resolves `null` when the login is gone (a 401 or 403, or an explicit
+ *     `{ token: null }`) — terminal, so the client signs out;
+ *   - throws on anything transient (a network failure, a 5xx or 429, or a
+ *     malformed response) — so the lifecycle backs off and retries without
+ *     signing out.
+ *
+ * A relative endpoint invoked on a server (where `fetch` has no origin) throws,
+ * which is transient by contract; the credential lifecycle translates that exact
+ * failure into an actionable "use an absolute URL server-side" warning.
+ */
+export function createEndpointCredentialResolver(endpoint) {
+    return async () => {
+        // `fetch()` rejections (offline, DNS, a relative URL on a server) propagate
+        // as-is: a throw is the transient signal in the resolver contract.
+        const res = await fetch(endpoint, {
+            method: 'POST',
+            credentials: 'include',
+        });
+        // The login itself is gone — terminal. Only these two statuses sign out.
+        if (res.status === 401 || res.status === 403)
+            return null;
+        // 5xx / 429 / anything unexpected: the login may be perfectly valid —
+        // transient, retry later.
+        if (!res.ok) {
+            throw new Error(`credential endpoint ${endpoint} answered ${res.status} — transient, will retry`);
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            throw new Error(`credential endpoint ${endpoint} returned non-JSON — expected { token }`);
+        }
+        // Distinguish "explicitly signed out" (`{ token: null }`) from "not a mint
+        // endpoint at all" (no `token` key). A misconfiguration must fail loudly and
+        // transiently, never as a silent sign-out.
+        if (typeof body !== 'object' || body === null || !('token' in body)) {
+            throw new Error(`credential endpoint ${endpoint} returned no \`token\` field — expected { token }`);
+        }
+        const token = body.token;
+        if (token === null || token === undefined)
+            return null;
+        if (typeof token !== 'string') {
+            throw new Error(`credential endpoint ${endpoint} returned a non-string \`token\``);
+        }
+        return token;
+    };
+}