@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/transport/httpClient.d.ts

@@ -0,0 +1,131 @@
+import type { HttpClientConfig } from './httpOptions.js';
+import type { CommitResource, HttpClaimApi, HttpClaimsResource, ModelReadOptions, CreateSessionParams, AbloSession } from '../resources/httpResources.js';
+import type { ModelCreateParams, ModelDeleteParams, ServerReadOptions, ModelRetrieveParams, ModelTrackParams, ModelTrackResult, ModelUpdateParams } from '../resources/modelOperations.js';
+import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
+import type { ModelUpdater, ContentionOptions } from '../resources/functionalUpdate.js';
+export interface AbloHttpClientOptions<S extends SchemaRecord> extends HttpClientConfig<S> {
+    /**
+     * Per-request deadline. A black-holed HTTP request otherwise has no platform
+     * timeout and can stall a headless worker forever. Pass `0` to disable it.
+     * @default 30_000
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * The per-model surface of the stateless HTTP client — everything reachable over
+ * request/response: reads (`retrieve` and `list`), writes (`create`, `update`,
+ * and `delete`), the durable-lease {@link HttpClaimApi | claim} plane for
+ * coordinated writes, and `track`, which registers a durable premise on a row.
+ * It deliberately omits the stateful client's local-only
+ * reads (the `local` namespace) and live subscriptions (`onChange`), which need
+ * a resident graph and a persistent socket; those are absent from the type, so
+ * reaching for one is a compile error rather than a runtime gap.
+ *
+ * This is also the base the reactive per-model surface is composed from, rather
+ * than a parallel list it happens to agree with — a verb added here arrives
+ * there without a second edit.
+ *
+ * The typed model contract is transport-independent: `retrieve` returns one row,
+ * `list` returns rows, `create`/`update` return the resulting row, and `delete`
+ * returns nothing. The low-level protocol client keeps its read watermark and
+ * commit receipt envelopes internally; callers should not have to change data
+ * access syntax when they switch transport.
+ */
+export interface HttpModelClient<T, C = T> {
+    /**
+     * Reads one row by id. Resolves to `undefined` when no such row exists — a
+     * miss is data-absence, not an error.
+     *
+     * This is the default "get me this row", and the one a stateless client
+     * wants, since it holds nothing locally. A client with a resident graph
+     * answers from it first and falls back to the network, which is why the
+     * synchronous `local.retrieve` exists alongside this: same read, restricted
+     * to what is already here.
+     */
+    retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<T | undefined>;
+    /**
+     * Reads the rows matching a filter. Same resolution as `retrieve`, in bulk,
+     * and deduplicated so concurrent identical calls share one request.
+     */
+    list(options?: ServerReadOptions<T>): Promise<T[]>;
+    /**
+     * Creates a row and returns it, including any framework-applied defaults.
+     * Passing an id that already exists is idempotent: the existing row is
+     * returned unchanged.
+     *
+     * When the client keeps a local graph the write is optimistic — it resolves
+     * once the mutation is queued locally, and a server rejection rolls it back
+     * (watch `sync.syncStatus`). A stateless client has no local graph to roll
+     * back, so it resolves on the server's confirmation instead. The same is true
+     * of `update` and `delete`.
+     */
+    create(params: ModelCreateParams<T, C>): Promise<T>;
+    update(params: ModelUpdateParams<T>): Promise<T>;
+    /**
+     * Updates a row with a function of its latest value — `update(id, current =>
+     * next)`, the data-layer equivalent of a `setState(prev => next)` reducer. The
+     * client reads the freshest row, runs your updater, and writes the result as a
+     * compare-and-swap against the row's watermark; if another write landed first it
+     * re-reads and re-runs. No claim or conflict handling is needed: the write either
+     * lands or throws `AbloContentionError` once its retry budget is spent. Return
+     * `null` or `undefined` from the updater to skip the write.
+     */
+    update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<T | undefined>;
+    delete(params: ModelDeleteParams<T>): Promise<void>;
+    claim: HttpClaimApi<T>;
+    /**
+     * Registers a durable premise on a row — "keep telling me about this one".
+     * Any change that lands on the tracked row rides back on the `notifications`
+     * of this client's next commit, so a long-running agent learns its context
+     * went stale without re-reading. A track it already holds is refreshed, not
+     * duplicated.
+     *
+     * ```ts
+     * await ablo.tasks.track({ id: 'task_42' });
+     * // …minutes of other work later, on the next write…
+     * const res = await ablo.commits.create({ operations: [ … ] });
+     * res.notifications; // populated if task_42 moved in the meantime
+     * ```
+     *
+     * The returned `notifications` are only the tracks that had ALREADY fired at
+     * registration time; the ongoing signal arrives on later receipts.
+     */
+    track(params: ModelTrackParams): Promise<ModelTrackResult>;
+}
+/**
+ * The type of the stateless HTTP client: a typed {@link HttpModelClient} per
+ * schema model, plus `commits`, `dispose`, and the session-mint surface. It
+ * exposes only what request/response transport can do, so reaching for a
+ * stateful-only capability — the `local` reads, `onChange`, or the synchronous
+ * `claim.state`/`queue`/`reorder` reads — is a compile error rather than a value
+ * that is `undefined` at runtime.
+ */
+export type AbloHttpClient<S extends SchemaRecord> = {
+    readonly [K in keyof S & string]: HttpModelClient<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
+} & {
+    /** Runs one-time setup (durable-outbox scope resolution and replay) before the client is used. It also runs lazily ahead of the first request, so calling it yourself is optional. */
+    ready(): Promise<void>;
+    /** Replays every pending durable HTTP write in seal order and waits for settlement. */
+    waitForFlush(): Promise<void>;
+    readonly commits: CommitResource;
+    /**
+     * Claim-ticket operations keyed by `claimId`: `retrieve` polls a queued
+     * ticket to its grant, `heartbeat` keeps one lease (held or queued) alive,
+     * `heartbeatAll` beats every lease this identity holds in one round trip.
+     * The id comes from `AbloClaimedError('claim_queued')`, which carries it on
+     * `error.claims`.
+     */
+    readonly claims: HttpClaimsResource;
+    dispose(): Promise<void>;
+    /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
+    getAuthToken(): Promise<string | null>;
+    /**
+     * Mints a short-lived, scoped session token. Minting is itself a stateless
+     * request, so it is available here even though the local-cache reads are not.
+     * Pass `{ user }` to mint an end-user key (`ek_`) or `{ agent, can }` to mint a
+     * scoped agent key (`rk_`). See {@link CreateSessionParams}.
+    */
+    readonly sessions: {
+        create(params: CreateSessionParams<S>): Promise<AbloSession>;
+    };
+};

package/dist/{client → transaction/transport}/httpClient.js

@@ -18,6 +18,7 @@
  * stateful client offers.
  */
 import { createHttpTransport, } from './httpTransport.js';
+import { modelWireNames } from '../auth/capability.js';
 import { AbloConnectionError, AbloValidationError } from '../errors.js';
 /**
  * Private transport members that pass straight through the facade. Everything
@@ -28,6 +29,7 @@ const PROTOCOL_MEMBERS = new Set([
     'waitForFlush',
     'dispose',
     'commits',
+    'claims',
     'getAuthToken',
     'sessions',
 ]);
@@ -96,6 +98,7 @@ function createHttpModelClient(protocol) {
             await protocol.delete(mutationOptions(params));
         },
         claim: protocol.claim,
+        track: (params) => protocol.track(params),
     };
 }
 /**
@@ -107,13 +110,11 @@ function createHttpModelClient(protocol) {
 /** @internal Constructed only through the public `Ablo({ transport: 'http' })` factory. */
 export function createAbloHttpClient(options) {
     const { schema, ...rest } = options;
-    const modelTypenames = Object.fromEntries(Object.entries(schema.models).map(([key, definition]) => [
-        key,
-        definition.typename ?? key,
-    ]));
     const transport = createHttpTransport({
         ...rest,
-        modelTypenames,
+        // Derived from the schema this client is bound to, never assembled by hand
+        // — see `auth/capability.ts`.
+        modelTypenames: modelWireNames(schema.models),
     });
     const schemaModels = new Set(Object.keys(schema.models));
     const models = new Map();

package/dist/transaction/transport/httpOptions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The slice of client configuration the HTTP transport reads.
+ *
+ * The composed `Ablo({ ... })` bag is assembled by the consumer and carries far
+ * more than this — persistence, offline, reactivity. The transport needs only
+ * the fields below, so the core declares them and stays out of the composition
+ * surface (ADR 0016).
+ *
+ * TypeScript is structural, so a consumer's full options object satisfies this
+ * without declaring `extends`; the composition root keeps owning its own type.
+ */
+import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type { AuthClientOptions } from '../auth/apiKey.js';
+import type { CoordinationObservability } from '../observability.js';
+import type { CommitOutboxScope } from '../transactions/settlement/commitEnvelope.js';
+import type { DurableWriteStore, DurableWritesConfig } from '../durableWrites.js';
+export interface HttpClientConfig<S extends SchemaRecord = SchemaRecord> extends AuthClientOptions {
+    schema: Schema<S>;
+    /** Overrides where credential exchange and bootstrap are reached. */
+    bootstrapBaseUrl?: string;
+    fetch?: typeof fetch | undefined;
+    defaultHeaders?: Record<string, string | null | undefined> | undefined;
+    defaultQuery?: Record<string, string | undefined> | undefined;
+    observability?: CoordinationObservability;
+    /** Crash-durable writes: the outbox is sealed before a request is dispatched. */
+    durableWrites?: DurableWritesConfig;
+    /** Compatibility input for pre-`durableWrites` clients. */
+    commitOutbox?: DurableWriteStore;
+    /** Compatibility input and internal child-client identity seam. */
+    commitOutboxScope?: CommitOutboxScope;
+    /** Which transport carries this client's traffic. */
+    transport?: 'websocket' | 'http' | undefined;
+}

package/dist/transaction/transport/httpOptions.js

@@ -0,0 +1,12 @@
+/**
+ * The slice of client configuration the HTTP transport reads.
+ *
+ * The composed `Ablo({ ... })` bag is assembled by the consumer and carries far
+ * more than this — persistence, offline, reactivity. The transport needs only
+ * the fields below, so the core declares them and stays out of the composition
+ * surface (ADR 0016).
+ *
+ * TypeScript is structural, so a consumer's full options object satisfies this
+ * without declaring `extends`; the composition root keeps owning its own type.
+ */
+export {};