@abloatai/ablo 0.34.1 → 0.35.0

package/dist/client/options.d.ts

@@ -4,19 +4,21 @@
  * construction surface exposed through `@abloatai/ablo/core`.
  * This module holds only types and has no runtime imports.
  */
-import type { Schema, SchemaRecord } from '../schema/schema.js';
-import type { SyncEngineConfig, SyncLogger, MutationExecutor, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
-import type { AbloPersistence } from './persistence.js';
-import type { DurableWriteStore, DurableWritesConfig } from '../transactions/durableWriteStore.js';
-import type { CommitOutboxScope } from '../transactions/commitEnvelope.js';
+import type { Schema, SchemaRecord } from '../transaction/schema/schema.js';
+import type { RuntimeConfig, Logger, MutationExecutor, ObservabilityProvider, Analytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
+import type { AbloPersistence } from '../transaction/persistence.js';
+import type { DurableWriteStore, DurableWritesConfig } from '../transaction/durableWrites.js';
+import type { CommitOutboxScope } from '../transaction/transactions/settlement/commitEnvelope.js';
 /**
  * An async function that resolves an apiKey at request time. Use it for credential
  * rotation — read from a vault, refresh from session storage, or pull from an
  * existing auth session. The canonical definition lives in `./auth`; it is
  * re-exported here for convenience.
  */
-export type { ApiKeySetter } from './auth.js';
-import type { ApiKeySetter } from './auth.js';
+export type { ApiKeySetter } from '../transaction/auth/apiKey.js';
+import type { ApiKeySetter } from '../transaction/auth/apiKey.js';
+import type { AbloPlugin } from '../transaction/plugin.js';
+import type { ParticipantKind } from '../transaction/types/participant.js';
 /**
  * Options for the {@link Ablo} client.
  *
@@ -39,6 +41,13 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * pass; start here.
      */
     schema: Schema<S>;
+    /**
+     * The capabilities installed on this client. Each plugin appears once in
+     * the list; a duplicate, or a plugin the chosen transport cannot carry,
+     * fails while the client is being constructed with an error naming the
+     * plugin. Omitted, the client installs `humans()` — today's default.
+     */
+    plugins?: readonly AbloPlugin[];
     /**
      * The API key — the auth field most apps set. It accepts three shapes:
      *
@@ -117,6 +126,15 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * })
      * ```
      */
+    /**
+     * Wire message types to surface as collaboration events, e.g.
+     * `['document:selection', 'document:cursor']`.
+     *
+     * These name your application's own concepts, so the SDK ships no default —
+     * a schema with no documents should never receive document events. Declare
+     * the ones you broadcast.
+     */
+    collaborationEvents?: readonly string[];
     durableWrites?: DurableWritesConfig;
     /**
      * @deprecated Use `durableWrites: { store, namespace }`.
@@ -142,8 +160,8 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * serverless handlers. It offers the same `ablo.<model>` surface and coordination
      * plane, but every call is a single HTTP round-trip, identity rides the bearer
      * credential, and no socket is opened. With `'http'` the return type narrows to
-     * {@link AbloHttpClient}, so stateful-only capabilities such as `get`, `getAll`,
-     * and `onChange` become compile errors instead of runtime gaps.
+     * {@link AbloHttpClient}, so stateful-only capabilities such as the `local`
+     * reads and `onChange` become compile errors instead of runtime gaps.
      *
      * Session minting through `sessions.create` is available on both transports.
      *
@@ -154,12 +172,18 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Turns Ablo's diagnostic logging on or off. `true` surfaces the `[Ablo]`
      * coordination trace — claims requested, queued, granted, and released, agent
      * handovers, and connection state — so you can watch the coordination between
-     * humans and agents while debugging. Omitting it, or `false`, keeps the quiet
+     * agents and people while debugging. Omitting it, or `false`, keeps the quiet
      * default of warnings and errors only. For a middle ground use {@link logLevel}.
      * The `ABLO_LOG_LEVEL` environment variable overrides it, and a custom logger
      * takes precedence.
      */
     debug?: boolean | undefined;
+    /**
+     * Route Ablo's log lines through your own logger (pino, winston, a test spy)
+     * instead of the default console `[Ablo]` logger. Supplying one bypasses
+     * {@link debug}/{@link logLevel} — your logger owns the thresholds.
+     */
+    logger?: Logger;
     /**
      * The log threshold for the default `[Ablo]` logger; takes precedence over
      * {@link debug}. `'info'` shows coordination and connection events without the
@@ -189,6 +213,33 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * session token (`ek_`/`rk_`) or you route through a controlled server proxy.
      */
     dangerouslyAllowBrowser?: boolean | undefined;
+    /**
+     * How far a write goes before its promise settles, for every model write on
+     * this client. The same word each write already takes per call
+     * (`create({ …, wait: 'confirmed' })`); setting it here makes it the default
+     * instead of repeating it.
+     *
+     * A write resolves as soon as it is applied locally and queued. That is what
+     * makes the UI immediate, and it is right for most writes — but it means a
+     * write the server later REFUSES has no caller left to tell. The rejection
+     * reverts the local row and reaches `ablo.onMutationFailure(…)`, and an
+     * application that subscribes to neither shows the change, then loses it,
+     * with nothing thrown anywhere.
+     *
+     * ```ts
+     * const ablo = new Ablo({ schema, apiKey, wait: 'confirmed' });
+     * try {
+     *   await ablo.documents.update({ id, data });   // throws if refused
+     * } catch (err) {
+     *   if (err instanceof AbloError) show(err.message);
+     * }
+     * ```
+     *
+     * The cost is real: each write now waits for the server's answer, so it is a
+     * choice between immediacy and certainty rather than a strict improvement.
+     * A per-call `wait` still wins over this.
+     */
+    wait?: 'queued' | 'confirmed' | undefined;
 }
 export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
@@ -257,7 +308,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * @deprecated The server derives the participant kind from the apiKey's scope.
      * Pass `apiKey` only.
      */
-    kind?: 'user' | 'agent' | 'system';
+    kind?: ParticipantKind;
     /**
      * @deprecated The server derives user identity from the apiKey's scope, or from
      * the `Ablo-Acting-User` request header for multi-tenant setups. Pass `apiKey`
@@ -277,12 +328,12 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     capabilityToken?: string;
     /** Custom logger (default: console). Supplying one bypasses {@link debug}/{@link logLevel}. */
-    logger?: SyncLogger;
+    logger?: Logger;
     /**
      * Turns Ablo's diagnostic logging on or off. `true` surfaces the `[Ablo]`
      * coordination trace — claims acquired, queued, granted, and released, agent
      * handovers, and connection state — along with internal lifecycle events, so you
-     * can watch the coordination between humans and agents. Omitting it, or `false`,
+     * can watch the coordination between agents and people. Omitting it, or `false`,
      * keeps the quiet default of warnings and errors only. For a middle ground use
      * {@link logLevel}. The `ABLO_LOG_LEVEL` environment variable overrides it, and a
      * custom {@link logger} takes precedence.
@@ -307,6 +358,8 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     persistence?: AbloPersistence;
     /** Internal mirror of {@link AbloOptions.durableWrites}. */
+    /** Wire message types to surface as collaboration events. Empty unless declared. */
+    collaborationEvents?: readonly string[];
     durableWrites?: DurableWritesConfig;
     /** @deprecated Internal mirror of {@link AbloOptions.commitOutbox}. */
     commitOutbox?: DurableWriteStore;
@@ -344,12 +397,12 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Custom observability provider (Sentry, Honeycomb, OTel, etc.).
      * Default: a noop implementation that drops all breadcrumbs and spans.
      */
-    observability?: SyncObservabilityProvider;
+    observability?: ObservabilityProvider;
     /**
      * Custom analytics provider (PostHog, Amplitude, Segment, etc.).
      * Default: a noop implementation that drops all events.
      */
-    analytics?: SyncAnalytics;
+    analytics?: Analytics;
     /**
      * Detect whether an error from a mutation/bootstrap response means the
      * user's session has expired. Used to surface re-auth prompts. Default:
@@ -371,12 +424,12 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     mutationExecutor?: MutationExecutor;
     /**
-     * Partial overrides for the auto-derived `SyncEngineConfig`. Merged on
+     * Partial overrides for the auto-derived `RuntimeConfig`. Merged on
      * top of `deriveConfigFromSchema(schema)`. Use this when you need
      * specific `modelCreatePriority`, `batchableModels`, or
      * `essentialFields` settings that the schema cannot express.
      */
-    configOverrides?: Partial<SyncEngineConfig>;
+    configOverrides?: Partial<RuntimeConfig>;
     /**
      * The sync groups (entity scopes) this client subscribes to. Normally the server
      * derives these from the apiKey's scope; pass them explicitly when the key does
@@ -402,4 +455,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * identity from the token through the identity endpoint instead.
      */
     organizationId?: string;
+    /** The client-wide write default — see {@link AbloOptions.wait}. Projected
+     *  from the public option rather than restated, so the two cannot diverge. */
+    wait?: AbloOptions['wait'];
 }

package/dist/client/reactiveEngine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The reactive engine build — everything `humans()` means at construction
+ * time (ADR 0016). `Ablo({ ... })` resolves auth and capabilities, then hands
+ * this module the prelude; from here on it is all materialisation: the
+ * runtime context, the internal components, the store and its credential
+ * lifecycle, presence and claim streams, the typed model proxies, and the
+ * commit/claim/session resources — assembled into the reactive client.
+ *
+ * Extracted from the factory so the composition root stays a root: resolve,
+ * dispatch, return. The construction moves behind `humans().init` proper when
+ * the plugin context can carry these inputs — until then the factory calls
+ * this directly for the humans-installed path.
+ */
+import type { SchemaRecord } from '../transaction/schema/schema.js';
+import type { MutationExecutor } from '../interfaces/index.js';
+import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
+import type { AttachablePresenceStream } from '../sync/createPresenceStream.js';
+import type { AbloOptions } from './options.js';
+import type { ClientPrelude } from './clientPrelude.js';
+import type { Ablo } from './Ablo.js';
+/**
+ * What the reactive build is fed: the factory's pass over the options bag
+ * ({@link ClientPrelude} — auth, url, logging, identity, shared with the other
+ * client shapes), plus the four things that must exist before the store does.
+ *
+ * The prelude half is extended, never restated. A second copy of those fields
+ * would drift the moment one side gained a resolver the other did not.
+ */
+export interface ReactiveEngineInputs<S extends SchemaRecord> extends ClientPrelude<S> {
+    options: AbloOptions<S>;
+    executor: MutationExecutor;
+    /**
+     * The connection, constructed by the factory before the plugin list
+     * resolved — the same instance `PluginContext.transport` carries. The
+     * store takes it as a dependency and owns the lifecycle.
+     */
+    transport: SyncWebSocket;
+    /** The humans() plugin's contribution — built by its `init`, already
+     *  attached to the connection the context carried. */
+    presence: AttachablePresenceStream;
+    /**
+     * Constructs a sibling client (`ablo.agents.create(...)` mints a scoped key
+     * and builds a second engine with it). Injected by the factory — a direct
+     * import back into it would close a runtime cycle.
+     */
+    createSibling: (options: AbloOptions<S>) => Ablo<S>;
+}
+export declare function buildReactiveEngine<const S extends SchemaRecord>(inputs: ReactiveEngineInputs<S>): Ablo<S>;