@abloatai/ablo 0.8.0 → 0.9.0

package/dist/auth/credentialSource.js

@@ -0,0 +1,63 @@
+/**
+ * Single mutable source for the SDK's active bearer credential.
+ *
+ * Every transport should read from this object at request/connect time:
+ * bootstrap HTTP, lazy query HTTP, identity/probe HTTP, and WebSocket URL
+ * auth. Token refresh writes here once; consumers observe the new value
+ * through their getter without being manually patched one by one.
+ */
+/**
+ * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
+ *
+ * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
+ * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
+ * credential out of the query string, which ALB access logs, proxies, and
+ * browser history capture. The server reads the token from the subprotocol and
+ * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Shared with
+ * the sync-server so client and server can never drift on the wire format.
+ */
+export const WS_BEARER_SUBPROTOCOL_PREFIX = 'ablo.bearer.';
+export const WS_SYNC_SUBPROTOCOL = 'ablo.sync.v1';
+export function createAuthCredentialSource(initialToken) {
+    let authToken = normalizeToken(initialToken);
+    return {
+        getAuthToken: () => authToken,
+        setAuthToken(token) {
+            authToken = normalizeToken(token);
+        },
+        authorizationHeader() {
+            return authorizationHeaderForToken(authToken);
+        },
+        withAuthHeaders(headers = {}) {
+            const authorization = authorizationHeaderForToken(authToken);
+            return authorization ? { ...headers, Authorization: authorization } : { ...headers };
+        },
+        applyAuthQueryParam(params, paramName = 'authorization') {
+            applyAuthToQueryParams(params, () => authToken, paramName);
+        },
+    };
+}
+export function resolveAuthToken(getAuthToken, fallbackToken) {
+    return normalizeToken(getAuthToken?.() ?? fallbackToken) ?? undefined;
+}
+export function authorizationHeaderForToken(token) {
+    const normalized = normalizeToken(token);
+    return normalized ? `Bearer ${normalized}` : undefined;
+}
+export function withAuthHeaders(getAuthToken, headers = {}, fallbackToken) {
+    const authorization = authorizationHeaderForToken(resolveAuthToken(getAuthToken, fallbackToken));
+    return authorization ? { ...headers, Authorization: authorization } : { ...headers };
+}
+export function applyAuthToQueryParams(params, getAuthToken, paramName = 'authorization', fallbackToken) {
+    const authorization = authorizationHeaderForToken(resolveAuthToken(getAuthToken, fallbackToken));
+    if (authorization) {
+        params.set(paramName, authorization);
+    }
+}
+function normalizeToken(token) {
+    if (!token)
+        return null;
+    const trimmed = token.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}

package/dist/auth/index.d.ts

@@ -11,21 +11,8 @@
  * SDKs hide their internal auth-handshake — the apiKey is the only
  * credential the consumer touches.
  */
-/** Server response shape — matches Phase 1A + 1B wire output. */
-export interface CapabilityExchangeResponse {
-    readonly capabilityId: string;
-    readonly token: string;
-    readonly expiresAt: string;
-    readonly organizationId: string;
-    readonly scope: {
-        readonly organizationId: string;
-        readonly syncGroups: readonly string[];
-        readonly operations: readonly string[];
-        readonly participantKind: 'user' | 'agent' | 'system';
-        readonly participantId: string;
-    };
-    readonly userMeta: Record<string, unknown>;
-}
+import { type CapabilityExchangeResponse, type IdentityResolveResponse } from './schemas.js';
+export type { CapabilityExchangeResponse, IdentityResolveResponse } from './schemas.js';
 export interface ExchangeApiKeyRequest {
     readonly apiKey: string;
     readonly baseUrl: string;
@@ -41,13 +28,6 @@ export interface ExchangeApiKeyRequest {
     readonly timeoutMs?: number;
 }
 export declare function exchangeApiKey(options: ExchangeApiKeyRequest): Promise<CapabilityExchangeResponse>;
-export interface IdentityResolveResponse {
-    readonly participantKind: 'user' | 'agent' | 'system';
-    readonly participantId: string;
-    readonly accountScope: string;
-    readonly syncGroups: readonly string[];
-    readonly userMeta: Record<string, unknown>;
-}
 export interface ResolveIdentityRequest {
     readonly baseUrl: string;
     readonly authToken?: string;

package/dist/auth/index.js

@@ -11,25 +11,8 @@
  * SDKs hide their internal auth-handshake — the apiKey is the only
  * credential the consumer touches.
  */
-import { AbloAuthenticationError, translateHttpError } from '../errors.js';
-/**
- * Whether an HTTP error body carries a code `translateHttpError` can read —
- * a top-level `code`, a nested `error.code`, or a string `error`. When it
- * doesn't (empty body, non-JSON, or a non-Ablo proxy 401), the caller falls
- * back to its own default code rather than emitting a code-less error.
- */
-function hasWireCode(body) {
-    if (typeof body !== 'object' || body === null)
-        return false;
-    const b = body;
-    if (typeof b.code === 'string')
-        return true;
-    if (typeof b.error === 'string')
-        return true;
-    return (typeof b.error === 'object' &&
-        b.error !== null &&
-        typeof b.error.code === 'string');
-}
+import { parseCapabilityExchangeResponse, parseIdentityResolveResponse, } from './schemas.js';
+import { AbloAuthenticationError, hasWireCode, translateHttpError } from '../errors.js';
 export async function exchangeApiKey(options) {
     if (!options.apiKey) {
         throw new AbloAuthenticationError('apiKey is required for capability exchange', { code: 'apikey_missing' });
@@ -88,27 +71,7 @@ export async function exchangeApiKey(options) {
             ? translateHttpError(response.status, body, requestId)
             : new AbloAuthenticationError(`apiKey exchange rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
     }
-    const raw = (await response.json());
-    if (!isCapabilityExchangeResponse(raw)) {
-        throw new AbloAuthenticationError('apiKey exchange response was malformed — missing required fields', { code: 'exchange_malformed_response' });
-    }
-    return raw;
-}
-function isCapabilityExchangeResponse(raw) {
-    if (!raw || typeof raw !== 'object')
-        return false;
-    const o = raw;
-    if (typeof o.token !== 'string')
-        return false;
-    if (typeof o.expiresAt !== 'string')
-        return false;
-    if (typeof o.organizationId !== 'string')
-        return false;
-    if (typeof o.scope !== 'object' || o.scope === null)
-        return false;
-    if (typeof o.userMeta !== 'object' || o.userMeta === null)
-        return false;
-    return true;
+    return parseCapabilityExchangeResponse(await response.json());
 }
 /**
  * Resolve the caller's Ablo identity from the authenticated request
@@ -135,7 +98,6 @@ export async function resolveIdentity(options) {
         response = await fetcher(url, {
             method: 'GET',
             headers,
-            credentials: 'include',
             signal: controller.signal,
         });
     }
@@ -164,7 +126,7 @@ export async function resolveIdentity(options) {
             ? translateHttpError(response.status, body, requestId)
             : new AbloAuthenticationError(`identity resolve rejected (${response.status})`, { code: 'identity_resolve_failed', httpStatus: response.status });
     }
-    return (await response.json());
+    return parseIdentityResolveResponse(await response.json());
 }
 const DEFAULT_BUFFER_FLOOR_MS = 60_000;
 const DEFAULT_BUFFER_RATIO = 0.1;

package/dist/auth/schemas.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export declare const AuthTokenSchema: z.ZodString;
+export declare const CapabilityExchangeResponseSchema: z.ZodObject<{
+    capabilityId: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodString;
+    organizationId: z.ZodString;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        syncGroups: z.ZodArray<z.ZodString>;
+        operations: z.ZodArray<z.ZodString>;
+        participantKind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        participantId: z.ZodString;
+    }, z.core.$loose>;
+    userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$loose>;
+export type CapabilityExchangeResponse = z.infer<typeof CapabilityExchangeResponseSchema>;
+export declare const IdentityResolveResponseSchema: z.ZodObject<{
+    participantKind: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    participantId: z.ZodString;
+    accountScope: z.ZodString;
+    syncGroups: z.ZodArray<z.ZodString>;
+    userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$loose>;
+export type IdentityResolveResponse = z.infer<typeof IdentityResolveResponseSchema>;
+export declare function parseCapabilityExchangeResponse(raw: unknown): CapabilityExchangeResponse;
+export declare function parseIdentityResolveResponse(raw: unknown): IdentityResolveResponse;

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,26 +84,53 @@ 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;
     /**
-     * Connection string to YOUR OWN Postgres. When set, Ablo registers this
-     * database as your project's data store and writes synced rows back into it
-     * (dedicated/BYO tenant), so your data stays canonical in your DB while Ablo
-     * runs the sync/coordination plane. Defaults to `process.env['DATABASE_URL']`.
+     * 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. Provide Ablo a NON-superuser, non-`BYPASSRLS` role: the server runs
-     * the tenant plane with row-level security forced, and rejects a privileged
-     * role that couldn't enforce isolation.
-     *
-     * Omit it to use Ablo-managed storage (the hosted default).
+     * 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;
     /**
@@ -159,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;
     /**
@@ -194,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
@@ -289,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;
     /**
@@ -336,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 {
@@ -364,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;
@@ -465,14 +504,64 @@ 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';
@@ -572,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
      * ```
      *
@@ -586,11 +675,39 @@ export type Ablo<S extends SchemaRecord> = {
     /**
      * 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 token (e.g. a 15m JWT) 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()`.
+     * 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
@@ -946,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;