@abloatai/ablo 0.11.1 → 0.12.0

package/dist/client/Ablo.js

@@ -27,7 +27,7 @@ import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
 import { alwaysOnline } from '../adapters/alwaysOnline.js';
 import { validateAbloOptions } from './validateAbloOptions.js';
-import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
+import { mintSession } from './sessionMint.js';
 import { createAuthCredentialSource } from '../auth/credentialSource.js';
 import { createInternalComponents } from './createInternalComponents.js';
 import { resolveParticipantIdentity } from './identity.js';
@@ -670,32 +670,20 @@ function createDefaultMutationDispatcher(executor) {
 // ── Auth normalization ─────────────────────────────────────────────────────
 /**
  * The one resolver the credential lifecycle needs: an async `() => token | null`,
- * or `null` when auth is static (a plain long-lived `apiKey` with no refresh —
- * the common case). Only the short-lived per-user path sets this, via `getToken`
- * (the primitive) or `authEndpoint` (sugar that POSTs for `{ token }`).
+ * or `null` when auth is static (a plain long-lived `apiKey` STRING with no
+ * refresh — the common case).
+ *
+ * The short-lived per-user browser path passes a FUNCTION `apiKey` (an
+ * `ApiKeySetter`): the SDK then drives the full credential lifecycle off it —
+ * mint-before-connect, the proactive refresh timer + wake/online/focus re-mint,
+ * and the reactive `credential_stale` re-mint. The resolver's contract is the
+ * `ApiKeySetter` contract end-to-end: resolve a token, resolve `null` when the
+ * login is gone (terminal → `session_expired` → sign out), or THROW on a
+ * transient failure (→ back off, never sign out).
  */
-function resolveCredentialResolver(options) {
-    if (options.getToken)
-        return options.getToken;
-    if (options.authEndpoint) {
-        const endpoint = options.authEndpoint;
-        const fetchImpl = options.fetch ?? globalThis.fetch;
-        return async () => {
-            // The endpoint lives on the consumer's OWN backend and is authed by the
-            // user's session cookie (hence `credentials: 'include'`); it returns the
-            // `ek_` to carry to the sync-server. A non-OK response is terminal
-            // (`null` → sign out), matching the `getToken` contract.
-            const res = await fetchImpl(endpoint, {
-                method: 'POST',
-                credentials: 'include',
-                headers: { 'Content-Type': 'application/json' },
-            });
-            if (!res.ok)
-                return null;
-            const body = (await res.json());
-            return body.token ?? null;
-        };
-    }
+function resolveCredentialResolver(apiKey) {
+    if (typeof apiKey === 'function')
+        return apiKey;
     return null;
 }
 export function Ablo(options) {
@@ -716,7 +704,7 @@ export function Ablo(options) {
     // drives both the reactive re-mint (FSM `credential_stale`) and the proactive
     // refresh timer + wake/online/focus triggers. Null for the common static
     // `apiKey` path — no refresh needed.
-    const credentialResolver = resolveCredentialResolver(options);
+    const credentialResolver = resolveCredentialResolver(configuredApiKey);
     const authCredentials = createAuthCredentialSource(internalOptions.capabilityToken ?? configuredAuthToken);
     const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
     assertBrowserSafety({
@@ -900,7 +888,7 @@ export function Ablo(options) {
                 // WebSocket upgrade + bootstrap carry a valid bearer (no tokenless first
                 // connect that has to self-heal). Only when a refreshing resolver is
                 // wired AND no static credential is already present. Contract mirrors
-                // `getToken`: `null` ⇒ the login is gone (terminal — fail ready so the
+                // the `apiKey` resolver: `null` ⇒ the login is gone (terminal — fail ready so the
                 // app shows sign-in); a THROW ⇒ transient (rethrown; autoStart swallows
                 // and the lifecycle's online/wake triggers retry).
                 if (credentialResolver && !authCredentials.getAuthToken()) {
@@ -933,8 +921,9 @@ export function Ablo(options) {
                     kind,
                     configuredApiKey,
                     // Resolve identity against the LIVE token, not the construction-time
-                    // `configuredAuthToken`. Consumers using `getToken` (apps/web) never
-                    // pass `authToken` at construction — they call `setAuthToken()` before
+                    // `configuredAuthToken`. Consumers using a function `apiKey` (apps/web)
+                    // never pass `authToken` at construction — the lifecycle mints the
+                    // first `ek_`/`rk_` and calls `setAuthToken()` before
                     // `ready()`, which updates the shared credential source. Reading the frozen
                     // `configuredAuthToken` here made `/auth/identity` fire with no Bearer
                     // (→ `no_matching_provider` / `session_expired`) even though the JWT
@@ -1135,7 +1124,7 @@ export function Ablo(options) {
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            action: claim.reason,
+            reason: claim.reason,
             ...(description ? { description } : {}),
             field: claim.target.field,
             status: 'active',
@@ -1155,7 +1144,7 @@ export function Ablo(options) {
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            action: claim.action,
+            reason: claim.reason,
             ...(claim.description ? { description: claim.description } : {}),
             field: claim.target.field,
             status: 'queued',
@@ -1247,14 +1236,8 @@ export function Ablo(options) {
         const current = listModelClaims(target);
         if (current.length === 0)
             return;
-        if (policy === 'fail')
-            throw claimedError(target, current, 'model_claimed');
-        const queue = listModelClaimQueue(target);
-        if (options?.maxQueueDepth !== undefined &&
-            queue.length >= options.maxQueueDepth) {
-            throw claimedError(target, current, 'queue_too_deep');
-        }
-        await waitForModelUnclaimed(target, { timeout: options?.claimedTimeout });
+        // policy === 'fail' — gate the read only when the caller opts in.
+        throw claimedError(target, current, 'model_claimed');
     }
     function wrapClaimHandle(claim, waited = false) {
         const release = async () => {
@@ -1263,7 +1246,7 @@ export function Ablo(options) {
         return {
             object: 'claim',
             claimId: claim.claimId,
-            action: claim.action,
+            reason: claim.reason,
             target: claim.target,
             waited,
             release,
@@ -1282,7 +1265,7 @@ export function Ablo(options) {
                 field: claimOptions.target.field,
                 meta: claimOptions.target.meta,
             }, {
-                reason: claimOptions.action,
+                reason: claimOptions.reason,
                 ttl: claimOptions.ttl,
                 queue: claimOptions.queue,
             });
@@ -1365,7 +1348,7 @@ export function Ablo(options) {
                         ...(held.target.field ? { field: held.target.field } : {}),
                         ...(held.target.meta ? { meta: held.target.meta } : {}),
                     },
-                    action: held.action,
+                    reason: held.reason,
                     heldBy: held.actor,
                     participantKind: held.participantKind,
                     expiresAt: held.expiresAt,
@@ -1385,6 +1368,14 @@ export function Ablo(options) {
             // errors so read interest never makes a read reject or stall.
             enterScope: (scope) => store.enterScope(scope),
             pinScope: (scope) => store.pinScope(scope),
+            // `ablo.<model>.watch(ids, { ttl })` → a scoped participant join on
+            // this model's sync group(s). The model-scoped relocation of the old
+            // `ablo.participants.join({ scope: { <model>: ids } })`. WebSocket
+            // only — `join` throws AbloConnectionError if the socket isn't ready.
+            createWatch: (modelKey, ids, options) => participantManager.join({
+                scope: { [modelKey]: ids },
+                ...(options?.ttl !== undefined ? { ttlSeconds: options.ttl } : {}),
+            }),
         });
     }
     const commits = {
@@ -1544,6 +1535,9 @@ export function Ablo(options) {
      * (a wide-scope `rk_` on the hosted path), which control-plane routes
      * rightly refuse (e.g. the user-session mint is sk_-gated). Counterpart to
      * `getAuthToken()`, which resolves the sync-plane token.
+     *
+     * The sk_-only rule is enforced server-side; the credential KIND taxonomy
+     * (secret/restricted/ephemeral/publishable) lives in `auth/credentialPolicy`.
      */
     async function controlPlaneApiKey() {
         return resolveApiKeyValue(configuredApiKey);
@@ -1564,7 +1558,7 @@ export function Ablo(options) {
             store.nudgeReconnect();
         },
         async getAuthToken() {
-            // The live short-lived bearer (set via `setAuthToken`/`getToken` refresh)
+            // The live short-lived bearer (set via `setAuthToken` / `apiKey`-resolver refresh)
             // is the canonical credential; fall back to a configured API key.
             //
             // This is the SYNC-PLANE token (bootstrap, WS, query HTTP). Control-plane
@@ -1608,66 +1602,15 @@ export function Ablo(options) {
                     url,
                     bootstrapBaseUrl: internalOptions.bootstrapBaseUrl,
                 });
-                // Discriminate the union onto the server's TWO mint doors:
-                //   `{ user }`  → POST /auth/ephemeral-keys → `ek_` (sk_-gated; the
-                //                 user-session door). Routing this arm through
-                //                 /auth/capability is structurally impossible — that
-                //                 route rejects participantKind 'user' outright
-                //                 (`invalid_participant_kind`, the 2026-06-11 Pulse
-                //                 cascade: the SDK's own blessed pattern 403'd and
-                //                 integrators fell back to minting humans as agents).
-                //   `{ agent }` → POST /auth/capability → scoped `rk_`.
-                //                 `can: { tasks: ['update'] }` serializes to the wire
-                //                 allowlist (`tasks.update`); the Hub matches it
-                //                 against every registered alias of the model.
-                if (params.user) {
-                    const res = await mintUserSessionKey({
-                        apiKey,
-                        baseUrl,
-                        userId: params.user.id,
-                        ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
-                        ttlSeconds: params.ttlSeconds ?? 900,
-                        ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
-                    });
-                    return {
-                        object: 'session',
-                        id: res.id,
-                        token: res.token,
-                        expiresAt: res.expiresAt,
-                        organizationId: res.organizationId,
-                        // The ephemeral mint stores scope on the key row; reshape its flat
-                        // response into the session resource's scope block.
-                        scope: {
-                            organizationId: res.organizationId,
-                            syncGroups: res.syncGroups,
-                            operations: [],
-                            participantKind: 'user',
-                            participantId: res.participantId,
-                        },
-                        userMeta: params.userMeta ?? { id: res.participantId },
-                    };
-                }
-                const operations = Object.entries(params.can).flatMap(([model, ops]) => (ops ?? []).map((op) => `${model.toLowerCase()}.${op}`));
-                const res = await exchangeApiKey({
+                // The two mint doors (`{ user }` → /auth/ephemeral-keys → `ek_`,
+                // `{ agent, can }` → /auth/capability → scoped `rk_`) live in the shared
+                // `mintSession` so this stateful client and the stateless HTTP client can
+                // never drift on how a token is minted.
+                return mintSession(params, {
                     apiKey,
                     baseUrl,
-                    participantKind: 'agent',
-                    participantId: params.agent.id,
-                    ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
-                    operations,
-                    ttlSeconds: params.ttlSeconds ?? 900,
-                    ...(params.userMeta ? { userMeta: params.userMeta } : {}),
                     ...(internalOptions.fetch ? { fetch: internalOptions.fetch } : {}),
                 });
-                return {
-                    object: 'session',
-                    id: res.capabilityId,
-                    token: res.token,
-                    expiresAt: res.expiresAt,
-                    organizationId: res.organizationId,
-                    scope: res.scope,
-                    userMeta: res.userMeta,
-                };
             },
         },
         async dispose() {
@@ -1736,9 +1679,6 @@ export function Ablo(options) {
         claims: publicClaims,
         commits,
         model,
-        /** Structured multiplayer participation — target-first, no
-     *  sync-group strings in the common path. */
-        participants: participantManager,
         /** Context-staleness snapshot — see `engine.snapshot(...)` JSDoc. */
         snapshot(entities) {
             return createSnapshot({

package/dist/client/ApiClient.d.ts

@@ -5,7 +5,8 @@
  * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget } from './Ablo.js';
+import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget, CreateSessionParams, AbloSession } from './Ablo.js';
+import type { SchemaRecord } from '../schema/schema.js';
 import type { ClaimHandle } from './createModelProxy.js';
 import type { Duration } from '../utils/duration.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
@@ -133,5 +134,13 @@ export interface AbloApi {
      * server with the credential this client already holds — no re-mint.
      */
     getAuthToken(): Promise<string | null>;
+    /**
+     * Mint a short-lived scoped session — the Stripe `ephemeralKeys.create` shape.
+     * Minting is a control-plane HTTP call (no socket), so it lives on this stateless
+     * client too, not only the realtime one. `{ user }` → `ek_`, `{ agent, can }` → `rk_`.
+     */
+    readonly sessions: {
+        create(params: CreateSessionParams<SchemaRecord>): Promise<AbloSession>;
+    };
 }
 export declare function createProtocolClient(options: AbloApiClientOptions): AbloApi;

package/dist/client/ApiClient.js

@@ -9,7 +9,20 @@ import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloVal
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { toSeconds } from '../utils/duration.js';
+import { mintSession } from './sessionMint.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
+/**
+ * The `/v1/claims` and model-query routes still emit the wire field `action`
+ * for the claim phase; the public `Claim` / `ModelClaim` expose it as `reason`.
+ * Heal on read so the SDK shape is consistent without a coordinated server
+ * deploy — `reason ?? action`. When the server adopts `reason`, this is a no-op.
+ */
+function healClaimPhase(claim) {
+    const raw = claim;
+    if (raw.reason !== undefined)
+        return claim;
+    return { ...claim, reason: raw.action ?? 'editing' };
+}
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
@@ -172,8 +185,8 @@ export function createProtocolClient(options) {
         const suffix = params.toString();
         const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
         return {
-            active: body.claims ?? [],
-            queue: body.queue ?? [],
+            active: (body.claims ?? []).map(healClaimPhase),
+            queue: (body.queue ?? []).map(healClaimPhase),
         };
     }
     function delay(ms, signal) {
@@ -228,20 +241,11 @@ export function createProtocolClient(options) {
         const policy = options?.ifClaimed ?? defaultPolicy;
         if (policy === 'return')
             return;
+        // policy === 'fail' — gate the read only when the caller opts in.
         const state = await listClaimState(target);
         if (state.active.length === 0)
             return;
-        if (policy === 'fail') {
-            throw claimedError(target, state.active, 'model_claimed');
-        }
-        if (options?.maxQueueDepth !== undefined &&
-            state.queue.length >= options.maxQueueDepth) {
-            throw claimedError(target, state.active, 'queue_too_deep');
-        }
-        await waitForNoClaims(target, {
-            timeout: options?.claimedTimeout,
-            pollInterval: options?.claimedPollInterval,
-        });
+        throw claimedError(target, state.active, 'model_claimed');
     }
     const commits = {
         async create(commitOptions) {
@@ -382,7 +386,8 @@ export function createProtocolClient(options) {
                 body: JSON.stringify({
                     claimId,
                     target: claimOptions.target,
-                    action: claimOptions.action,
+                    // Wire field stays `action`; public option is `reason`.
+                    action: claimOptions.reason,
                     ttl: claimOptions.ttl,
                     queue: claimOptions.queue,
                 }),
@@ -408,7 +413,7 @@ export function createProtocolClient(options) {
             return {
                 object: 'claim',
                 claimId: id,
-                action: claimOptions.action,
+                reason: claimOptions.reason,
                 target: claimOptions.target,
                 release,
                 revoke: () => {
@@ -459,7 +464,7 @@ export function createProtocolClient(options) {
         return {
             data,
             stamp: query.stamp ?? 0,
-            claims: query.claims ?? [],
+            claims: (query.claims ?? []).map(healClaimPhase),
         };
     }
     /**
@@ -541,13 +546,14 @@ export function createProtocolClient(options) {
             const body = await requestJson(claimPath(params.id), {
                 method: 'POST',
                 body: JSON.stringify({
-                    action: params.action ?? 'editing',
+                    // Wire field stays `action`; public option is `reason`.
+                    action: params.reason ?? 'editing',
                     ...(params.ttl !== undefined ? { ttl: params.ttl } : {}),
                     ...(params.description !== undefined ? { description: params.description } : {}),
                     ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
-                    // `wait` (default true) → queue behind the holder; false → fail-fast
+                    // `queue` (default true) → queue behind the holder; false → fail-fast
                     // with AbloClaimedError (work-distribution dedup).
-                    queue: params.wait ?? true,
+                    queue: params.queue ?? true,
                 }),
             });
             if (body.status === 'queued') {
@@ -573,7 +579,7 @@ export function createProtocolClient(options) {
                     ...(params.range ? { range: params.range } : {}),
                     ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
                 },
-                action: params.action ?? 'editing',
+                reason: params.reason ?? 'editing',
                 ...(params.description ? { description: params.description } : {}),
                 data,
                 release,
@@ -588,11 +594,12 @@ export function createProtocolClient(options) {
             release: releaseClaim,
             state: async (params) => {
                 const res = await claimsForEntity(params);
-                return res.claims?.[0] ?? null;
+                const first = res.claims?.[0];
+                return first ? healClaimPhase(first) : null;
             },
             queue: async (params) => {
                 const res = await claimsForEntity(params);
-                return { object: 'list', data: res.queue ?? [] };
+                return { object: 'list', data: (res.queue ?? []).map(healClaimPhase) };
             },
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
@@ -656,6 +663,22 @@ export function createProtocolClient(options) {
         claims,
         commits,
         model,
+        sessions: {
+            async create(params) {
+                // Stateless mint: the configured key IS the control-plane credential here
+                // (no startup `rk_` exchange runs on this client). Reuse the resolved base
+                // URL + fetch; the shared `mintSession` owns the two server doors.
+                const apiKey = await resolveApiKeyValue(configuredApiKey);
+                if (!apiKey) {
+                    throw new AbloAuthenticationError('sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.', { code: 'apikey_missing' });
+                }
+                return mintSession(params, {
+                    apiKey,
+                    baseUrl: apiBaseUrl,
+                    ...(options.fetch ? { fetch: options.fetch } : {}),
+                });
+            },
+        },
         async getAuthToken() {
             // Mirror `authHeaders()`: a configured API key wins, else the
             // construction-time auth token. Resolve the (possibly async) key setter.

package/dist/client/auth.d.ts

@@ -12,13 +12,20 @@
  * explicit options so generated apps do not accrete hidden env knobs.
  */
 /**
- * Async callable that resolves to a fresh API key. Mirrors the shape
+ * Async callable that resolves the current credential. Mirrors the shape
  * Anthropic / OpenAI / Stripe ship — used for credential rotation
- * (e.g. AWS STS, GCP IAM, Vault). Re-exported from `./Ablo` so
- * existing import paths work; defined here so this module has no
- * circular dependency back to `Ablo.ts`.
+ * (e.g. AWS STS, GCP IAM, Vault) AND the short-lived per-user browser
+ * path (mint a fresh `ek_`/`rk_` from the signed-in session). Re-exported
+ * from `./Ablo` so existing import paths work; defined here so this module
+ * has no circular dependency back to `Ablo.ts`.
+ *
+ * Contract: 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, never
+ * sign out). A long-lived static `apiKey` string needs none of this — it is
+ * used as-is. This is the single credential resolver the SDK supports.
  */
-export type ApiKeySetter = () => Promise<string>;
+export type ApiKeySetter = () => Promise<string | null>;
 export interface AuthResolveInput {
     /**
      * The full options bag the caller passed to `Ablo()`. Resolvers

package/dist/client/auth.js

@@ -12,6 +12,7 @@
  * explicit options so generated apps do not accrete hidden env knobs.
  */
 import { AbloAuthenticationError } from '../errors.js';
+import { classifyCredentialKind } from '../auth/credentialPolicy.js';
 /**
  * Read `process.env` defensively. Works in browser (where `process`
  * is undefined), Node, and edge runtimes that expose a partial
@@ -137,7 +138,7 @@ export function assertBrowserSafety(input) {
     if (!input.dangerouslyAllowBrowser &&
         inBrowser &&
         typeof input.apiKey === 'string' &&
-        input.apiKey.startsWith('sk_')) {
+        classifyCredentialKind(input.apiKey) === 'secret') {
         throw new AbloAuthenticationError("It looks like you're running in a browser-like environment.\n\n" +
             'This is disabled by default — your secret API key would be ' +
             "exposed to every visitor's network tab. If you understand the risks " +