@abloatai/ablo 0.7.0 → 0.9.0

package/dist/auth/schemas.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { AbloAuthenticationError } from '../errors.js';
+const AuthParticipantKindSchema = z.enum(['user', 'agent', 'system']);
+export const AuthTokenSchema = z.string().trim().min(1);
+export const CapabilityExchangeResponseSchema = z
+    .object({
+    capabilityId: z.string().min(1),
+    token: AuthTokenSchema,
+    expiresAt: z.string().min(1),
+    organizationId: z.string().min(1),
+    scope: z
+        .object({
+        organizationId: z.string().min(1),
+        syncGroups: z.array(z.string()),
+        operations: z.array(z.string()),
+        participantKind: AuthParticipantKindSchema,
+        participantId: z.string().min(1),
+    })
+        .passthrough(),
+    userMeta: z.record(z.string(), z.unknown()),
+})
+    .passthrough();
+export const IdentityResolveResponseSchema = z
+    .object({
+    participantKind: AuthParticipantKindSchema,
+    participantId: z.string().min(1),
+    accountScope: z.string().min(1),
+    syncGroups: z.array(z.string()),
+    userMeta: z.record(z.string(), z.unknown()),
+})
+    .passthrough();
+function formatIssues(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+        return `${path}: ${issue.message}`;
+    })
+        .join('; ');
+}
+export function parseCapabilityExchangeResponse(raw) {
+    const parsed = CapabilityExchangeResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new AbloAuthenticationError(`apiKey exchange response was malformed: ${formatIssues(parsed.error)}`, { code: 'exchange_malformed_response', cause: parsed.error });
+    }
+    return parsed.data;
+}
+export function parseIdentityResolveResponse(raw) {
+    const parsed = IdentityResolveResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new AbloAuthenticationError(`identity resolve response was malformed: ${formatIssues(parsed.error)}`, { code: 'identity_resolve_failed', cause: parsed.error });
+    }
+    return parsed.data;
+}

package/dist/client/Ablo.d.ts

@@ -11,9 +11,12 @@
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
  *
  *   const reports = sync.reports.list({ where: { status: 'todo' } });
- *   await sync.reports.create({ title: 'Fix bug' });
- *   await sync.reports.update(reportId, { status: 'ready' });
- *   await sync.reports.delete(reportId);
+ *   await sync.reports.create({ data: { title: 'Fix bug' } });
+ *   await sync.reports.update({
+ *     id: reportId,
+ *     data: { status: 'ready' },
+ *   });
+ *   await sync.reports.delete({ id: reportId });
  */
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
 import type { SyncEngineConfig, SyncLogger, MutationExecutor, MutationDispatcher, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
@@ -23,7 +26,7 @@ import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
 import type { IntentStream, IntentWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
 import type { ParticipantManager } from '../sync/participants.js';
-import type { ActiveIntent, Duration, TargetRange } from '../types/streams.js';
+import type { ActiveIntent, Duration, Intent, TargetRange } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiIntents } from './ApiClient.js';
 /**
  * Handle returned by `engine.beginTurn()`. While alive, every commit
@@ -71,7 +74,7 @@ import { type AbloPersistence } from './persistence.js';
  * the way you'd reach for the equivalent option on the Stripe / OpenAI
  * / Anthropic clients: rarely, and deliberately.
  *
- * @see https://docs.ablo.finance — full option reference
+ * @see https://docs.abloatai.com — full option reference
  */
 export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
@@ -81,13 +84,55 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     schema: Schema<S>;
     /**
-     * API key used for authentication.
+     * API key — **the one auth field most apps set.** Server-side this is your
+     * secret `sk_` (and it defaults to `process.env['ABLO_API_KEY']`, so you
+     * usually pass nothing). A long-lived key needs no refresh; the client uses
+     * it as-is.
      *
-     * Accepts a static string (`sk_live_...`) or an async function that
-     * resolves to one. Defaults to `process.env['ABLO_API_KEY']`, so you
-     * usually don't pass this explicitly server-side.
+     * Accepts a static string or an async `() => Promise<string>` resolver if you
+     * rotate keys out-of-band (resolved at bootstrap).
+     *
+     * Browser apps that mint a SHORT-LIVED per-user key (`ek_`) from a login can't
+     * ship a secret — those use {@link getToken} (or {@link authEndpoint}) instead,
+     * which the client refreshes for you. That's the only case that isn't "just
+     * `apiKey`".
      */
     apiKey?: string | ApiKeySetter | null | undefined;
+    /**
+     * Opt-in for the SHORT-LIVED per-user browser case: an async resolver for a
+     * fresh bearer (`ek_`/`rk_`) your backend minted for the signed-in user. The
+     * client calls it once before connect and then keeps the key fresh for you —
+     * a refresh timer ahead of expiry plus re-mint on OS-wake / network-online /
+     * tab-focus, and a reactive re-mint when a probe finds the key stale. You
+     * never call a refresh method (Supabase `autoRefreshToken` model).
+     *
+     * Contract: resolve a token, resolve `null` when the login itself is gone
+     * (terminal → sign out), or THROW on a transient failure (→ back off, never
+     * sign out). Leave unset for the static-`apiKey` path.
+     */
+    getToken?: (() => Promise<string | null>) | undefined;
+    /**
+     * Convenience over {@link getToken}: a URL on YOUR backend that returns
+     * `{ token }`. The client POSTs to it (with cookies, so it's authed by the
+     * user's session) to mint + refresh the bearer. Ignored when `getToken` is
+     * set. Pure sugar — `getToken: () => fetch(url).then(r => r.json()).then(b => b.token)`.
+     */
+    authEndpoint?: string | undefined;
+    /**
+     * Direct-URL convenience connector: a connection string to your own Postgres
+     * that Ablo can register for a dedicated tenant.
+     *
+     * This is NOT the default Data Source path. For the Zero-shaped default, keep
+     * `DATABASE_URL` in your app, expose `dataSource(...)`, and let your server
+     * write the database while Ablo coordinates the sync stream.
+     *
+     * SERVER-ONLY: this carries credentials, so it is never sent from the browser
+     * — constructing a client with `databaseUrl` and `dangerouslyAllowBrowser`
+     * throws. If you opt into this connector, provide a NON-superuser,
+     * non-`BYPASSRLS` role; the direct connector rejects privileged roles that
+     * cannot enforce RLS.
+     */
+    databaseUrl?: string | null | undefined;
     /**
      * Local persistence mode. Pass `indexeddb` only when you want offline
      * queueing and a reload-surviving browser cache.
@@ -112,8 +157,8 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
     defaultQuery?: Record<string, string | undefined> | undefined;
     /**
      * Client-side use is disabled by default because private API keys should
-     * not ship to browsers. Set this only when using a publishable/browser-safe
-     * key or a controlled server proxy.
+     * not ship to browsers. Set this only when the browser holds a minted
+     * session token (`ek_`/`rk_`) or you route through a controlled server proxy.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
 }
@@ -144,8 +189,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     authToken?: string | null | undefined;
     /**
      * Override the default base URL. Defaults to
-     * `wss://mesh.ablo.finance` for hosted production; pass an explicit
-     * URL for self-hosted or staging (e.g. `wss://mesh-staging.ablo.finance`).
+     * `wss://api.abloatai.com` for hosted production; pass an explicit
+     * URL for self-hosted or private deployments.
      */
     baseURL?: string | null | undefined;
     /**
@@ -168,7 +213,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Client-side use of this SDK is disabled by default — your apiKey
      * would ship to every visitor's network tab. Only set this to
      * `true` if you've understood the risk and have appropriate
-     * mitigations (a publishable key, a server-side proxy, etc).
+     * mitigations (a minted session token, a server-side proxy, etc).
      */
     dangerouslyAllowBrowser?: boolean | undefined;
     /**
@@ -179,6 +224,18 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * only for the advanced Model / Claim / Commit client.
      */
     schema: Schema<S>;
+    /**
+     * Short-lived-bearer resolver for the per-user browser path (mirrors the
+     * public {@link AbloOptions.getToken}). The client mints the first token
+     * before connect and refreshes it (timer + wake/online/focus) — see
+     * {@link resolveCredentialResolver}.
+     */
+    getToken?: (() => Promise<string | null>) | undefined;
+    /**
+     * Backend URL returning `{ token }`; sugar over {@link getToken}. Mirrors the
+     * public {@link AbloOptions.authEndpoint}.
+     */
+    authEndpoint?: string | undefined;
     /**
      * @deprecated Server derives participant kind from the apiKey's
      * scope. Pass apiKey only; this option will be removed once the
@@ -274,8 +331,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * `commit` method against `${url}/graphql`) with one that uses your own
      * GraphQL client, auth headers, retry policy, and observability hooks.
      *
-     * Default: a fetch-based executor that targets `${url}/graphql` with
-     * `credentials: 'include'` (cookie auth) when no `apiKey` is set.
+     * Default: a fetch-based executor that targets `${url}/graphql` and sends
+     * the configured bearer (`apiKey` / backend-minted token) as `Authorization`.
      */
     mutationExecutor?: MutationExecutor;
     /**
@@ -321,18 +378,14 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  * Operations available on each model in the sync engine.
  *
  * Naming aligns with Stripe / OpenAI / Anthropic conventions:
- *   `retrieve(id)` — single entity by id (sync, from local pool)
- *   `list({where})` — collection with filter (sync, from local pool)
- *   `count({where})` — count (sync, from local pool)
- *   `load({where})` — async hydrate through pool → IDB → network
- *   `create / update / delete` — optimistic writes
- *
- * The old verb set (`findById`, `findMany`, `findFirst`) is kept as
- * deprecated aliases for one release cycle so consumers can migrate
- * without a flag day.
+ *   `retrieve({ id })` — async single-row server read
+ *   `list({ where })` — async collection server read
+ *   `get(id)` / `getAll(...)` / `getCount(...)` — local graph snapshots
+ *   `create({ data })` / `update({ id, data })` / `delete({ id })` — writes
+ *   `claim({ id })` — durable claim handle for coordinated writes
  */
-export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ClaimOptions, ClaimedRow, ModelOperations, } from './createModelProxy.js';
-import type { ModelOperations } from './createModelProxy.js';
+export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './createModelProxy.js';
+import type { ModelOperations, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelLoadOptions } from './createModelProxy.js';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
 export interface ModelTarget {
@@ -349,6 +402,7 @@ export interface ModelClaim {
     readonly actor: string;
     readonly participantKind: ActiveIntent['participantKind'];
     readonly action: string;
+    readonly description?: string;
     readonly field?: string;
     readonly status?: 'active' | 'queued';
     readonly position?: number;
@@ -450,14 +504,130 @@ export interface ModelMutationOptions extends ClaimedOptions {
     readonly readAt?: number | null;
     readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
     readonly wait?: CommitWait;
+    readonly claim?: ClaimHandle | ClaimOptions | null;
+}
+/**
+ * The HTTP/stateless claim surface. Normal tools usually put `claim` directly
+ * on the write (`update({ id, data, claim })`) and let the SDK release it. Use
+ * this namespace for multi-step handles and coordination screens.
+ */
+export interface HttpClaimApi<T> {
+    /** Take a manual claim handle for multi-step work. Release it when done. */
+    (params: ClaimParams<T>): Promise<ClaimHandle<T>>;
+    /** Release a manual claim you hold. */
+    release(params: ClaimLookupParams<T> | ClaimHandle<T>): Promise<void>;
+    /**
+     * Current holder of the lease on a row, or `null` when free. For UI badges,
+     * preflight checks, and operators.
+     */
+    state(params: ClaimLookupParams<T>): Promise<Intent | null>;
+    /**
+     * FIFO wait line behind the holder. Advanced: useful for operator UIs and
+     * schedulers.
+     */
+    queue(params: ClaimLookupParams<T>): Promise<{
+        readonly object: 'list';
+        readonly data: readonly Intent[];
+    }>;
+    /**
+     * Re-rank the wait line. Advanced and permission-gated.
+     */
+    reorder(params: ClaimReorderParams<T>): Promise<void>;
 }
 export interface ModelClient<T = Record<string, unknown>> {
-    retrieve(id: string, options?: ModelReadOptions): Promise<ModelRead<T>>;
-    create(data: Record<string, unknown>, options?: ModelMutationOptions & {
+    retrieve(params: ModelReadOptions & {
+        readonly id: string;
+    }): Promise<ModelRead<T>>;
+    /**
+     * Collection read over HTTP (server round-trip). Equality `where`, `orderBy`,
+     * `limit`. Present on the stateless protocol client; the store-backed
+     * `.model(name)` accessor omits it (use the typed `ablo.<model>.list` there).
+     */
+    list?(options?: ModelLoadOptions<T>): Promise<T[]>;
+    create(params: ModelMutationOptions & {
+        readonly data: Record<string, unknown>;
         readonly id?: string | null;
     }): Promise<CommitReceipt>;
-    update(id: string, data: Record<string, unknown>, options?: ModelMutationOptions): Promise<CommitReceipt>;
-    delete(id: string, options?: ModelMutationOptions): Promise<CommitReceipt>;
+    update(params: ModelMutationOptions & {
+        readonly id: string;
+        readonly data: Record<string, unknown>;
+    }): Promise<CommitReceipt>;
+    delete(params: ModelMutationOptions & {
+        readonly id: string;
+    }): Promise<CommitReceipt>;
+    /**
+     * Durable lease + FIFO wait-line over HTTP — coordination without a socket.
+     * Present on the stateless protocol client (`Ablo({ schema: null })` /
+     * `createAbloHttpClient`); the store-backed `.model(name)` accessor omits it
+     * (the typed `ablo.<model>.claim` proxy is the full reactive namespace there).
+     */
+    claim?: HttpClaimApi<T>;
+}
+/** A single data operation a scoped **agent** session may perform on a model. */
+export type SessionOperation = 'read' | 'create' | 'update' | 'delete';
+/** Mint params for an **end-user** session — full data authority within the
+ *  org (the Stripe `ephemeralKeys.create` / Supabase session shape). Mints an
+ *  `ek_` token. `user.id` is your end user's external IdP id (becomes the
+ *  session's `participantId`); Ablo does not model your users, so it's an
+ *  honest string at the trust boundary. */
+export interface CreateUserSessionParams {
+    /** Your end user. `id` becomes the token's `participantId`. */
+    user: {
+        id: string;
+    };
+    /** Sync groups this session may subscribe to. Omit to inherit the key's scope. */
+    syncGroups?: readonly string[];
+    /** Token lifetime in seconds. Defaults to 900 (15m, the Stripe ephemeral default). */
+    ttlSeconds?: number;
+    /** Opaque identity blob echoed back to the client as `ablo.user`. */
+    userMeta?: Record<string, unknown>;
+    agent?: never;
+    can?: never;
+}
+/** Mint params for a scoped **agent** session — mints a restricted `rk_` token
+ *  gated to exactly the operations named in `can`. `can` is typed off your
+ *  schema (no magic `'task.update'` strings): `{ Task: ['update'], Deck: ['read'] }`
+ *  — the SDK serializes each entry to the wire allowlist (`task.update`). */
+export interface CreateAgentSessionParams<S extends SchemaRecord> {
+    /** Your agent. `id` becomes the token's `participantId`. */
+    agent: {
+        id: string;
+    };
+    /** Per-model operation allowlist, typed against the schema's model names. */
+    can: {
+        [M in keyof S & string]?: readonly SessionOperation[];
+    };
+    /** Sync groups this session may subscribe to. Omit to inherit the key's scope. */
+    syncGroups?: readonly string[];
+    /** Token lifetime in seconds. Defaults to 900 (15m, the Stripe ephemeral default). */
+    ttlSeconds?: number;
+    /** Opaque identity blob echoed back to the client as `ablo.agent`. */
+    userMeta?: Record<string, unknown>;
+    user?: never;
+}
+/** Params for {@link Ablo.sessions}.create — a discriminated union: pass
+ *  `{ user }` for a full-authority end-user session (`ek_`) or `{ agent, can }`
+ *  for a scoped agent session (`rk_`). */
+export type CreateSessionParams<S extends SchemaRecord> = CreateUserSessionParams | CreateAgentSessionParams<S>;
+/** A minted end-user session token — the Stripe ephemeral-key / Supabase
+ *  session resource. `token` is the secret the browser presents as its bearer. */
+export interface AbloSession {
+    object: 'session';
+    /** Stable id of the minted credential (for revocation). */
+    id: string;
+    /** The short-lived `rk_` session token. Hand this to the user's browser. */
+    token: string;
+    /** ISO-8601 expiry. */
+    expiresAt: string;
+    organizationId: string;
+    scope: {
+        organizationId: string;
+        syncGroups: readonly string[];
+        operations: readonly string[];
+        participantKind: 'user' | 'agent' | 'system';
+        participantId: string;
+    };
+    userMeta: Record<string, unknown>;
 }
 /** The typed sync engine client — one property per model in the schema */
 export type Ablo<S extends SchemaRecord> = {
@@ -491,8 +661,8 @@ export type Ablo<S extends SchemaRecord> = {
      * offline, this waits until reconnect + flush completes.
      *
      * ```ts
-     * await sync.reports.create({ title: 'A' });
-     * await sync.reports.create({ title: 'B' });
+     * await sync.reports.create({ data: { title: 'A' } });
+     * await sync.reports.create({ data: { title: 'B' } });
      * await sync.waitForFlush(); // server has both reports
      * ```
      *
@@ -502,6 +672,59 @@ export type Ablo<S extends SchemaRecord> = {
     waitForFlush(timeoutMs?: number): Promise<void>;
     /** Disconnect and clean up */
     dispose(): Promise<void>;
+    /**
+     * Replace the bearer auth token used for the WebSocket upgrade and HTTP
+     * requests, WITHOUT tearing down the engine. Use to push a refreshed
+     * short-lived access key (the Stripe-style `ek_`/`rk_`) before it expires —
+     * `<AbloProvider>`'s `getToken` refresh loop calls this. Reuses the same
+     * rotation path as the internal capability-token refresh; safe to call before
+     * `ready()`. Also nudges a parked connection to re-probe with the new token.
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Resolve the active bearer credential this engine authenticates with — the
+     * live `ek_`/`rk_` the WebSocket and HTTP transports currently carry (kept
+     * fresh by the `getToken` refresh loop), falling back to a configured API
+     * key. Returns `null` when no credential is set yet. Use it to authenticate
+     * a side-band request to the same sync-server (e.g. the S3 presign endpoint)
+     * with the very token this client already holds — no extra mint round-trip.
+     */
+    getAuthToken(): Promise<string | null>;
+    /**
+     * Register a re-mint hook for the short-lived access key. The connection
+     * layer calls it WHEN it finds the key stale (a `credential_stale` probe) or
+     * on an external nudge; the hook mints a fresh `ek_`/`rk_` from the still-valid
+     * login. Mirrors the `getToken` contract: resolve a token, resolve `null` when
+     * the login itself is gone (→ sign out), or THROW on a transient failure (→
+     * back off, never sign out). `<AbloProvider>` wires this from its
+     * `getToken`/`authEndpoint`. Safe to call before `ready()`.
+     */
+    setCredentialRefresher(refresher: (() => Promise<string | null>) | null): void;
+    /**
+     * Ask the connection layer to re-probe and reconnect now, using the current
+     * credential. Idempotent and safe in any state (a no-op while connected).
+     * Call after an OS-wake signal (Electron `powerMonitor` 'resume') so a
+     * connection parked since sleep recovers immediately instead of waiting for
+     * the watchdog.
+     */
+    nudgeReconnect(): void;
+    /**
+     * Mint a short-lived, scoped **session token** for one end user — the
+     * Stripe `ephemeralKeys.create` / Supabase session shape. Call this on YOUR
+     * BACKEND (where the `sk_` secret key lives), then hand the returned
+     * `token` to that user's browser (typically via an authEndpoint the client
+     * fetches). The browser presents it as the bearer; the sync-server verifies
+     * the scoped `rk_` token via `apiKeyProvider`.
+     *
+     * The browser must NEVER see the `sk_` key — only the per-user session token.
+     *
+     * Pass `{ user: { id } }` for a full-authority end-user session (mints `ek_`),
+     * or `{ agent: { id }, can: { Task: ['update'] } }` for a scoped agent
+     * session (mints `rk_`); `can` is typed against your schema's model names.
+     */
+    sessions: {
+        create(params: CreateSessionParams<S>): Promise<AbloSession>;
+    };
     /**
      * Destroy every IndexedDB database owned by this engine. Disconnects
      * the WebSocket, releases timers, and deletes all `ablo_*` / `ablo-*`
@@ -766,6 +989,8 @@ export declare namespace Ablo {
     type CapabilityRecord = import('./ApiClient.js').CapabilityRecord;
     type CapabilityResource = import('./ApiClient.js').CapabilityResource;
     type CapabilityRevocation = import('./ApiClient.js').CapabilityRevocation;
+    type CapabilityRotateOptions = import('./ApiClient.js').CapabilityRotateOptions;
+    type RotatedCapability = import('./ApiClient.js').RotatedCapability;
     type Task = import('./ApiClient.js').Task;
     type TaskCreateOptions = import('./ApiClient.js').TaskCreateOptions;
     type TaskCloseOptions = import('./ApiClient.js').TaskCloseOptions;
@@ -838,6 +1063,7 @@ export declare namespace Ablo {
     namespace Source {
         type Operation = import('../source/index.js').SourceOperation;
         type Event = import('../source/index.js').SourceEvent;
+        type EventForOperationOptions = import('../source/index.js').SourceEventForOperationOptions;
         type EventsResult = import('../source/index.js').SourceEventsResult;
         type Scope = import('../source/index.js').SourceScope;
         type ApiKey = import('../source/index.js').SourceApiKey;