@abloatai/ablo 0.36.0 → 0.37.0

package/dist/client/Ablo.d.ts

@@ -1,231 +0,0 @@
-/**
- * `Ablo` — the one-call entry point to the sync engine client. It hides the
- * internal wiring — the object pool, local database, sync client, WebSocket,
- * bootstrap, and offline queue — behind a single function that returns a typed
- * client with one property per model in your schema.
- *
- * Usage:
- *   import { Ablo } from '@abloatai/ablo';
- *   import { schema } from './schema';
- *
- *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- *
- *   const reports = sync.reports.list({ where: { status: 'todo' } });
- *   await sync.reports.create({ data: { title: 'Fix bug' } });
- *   await sync.reports.update({
- *     id: reportId,
- *     data: { status: 'ready' },
- *   });
- *   await sync.reports.delete({ id: reportId });
- *
- * This module is the composition root and the merge point, and only those.
- * `Ablo` is three declarations sharing one name — the factory, the client
- * type, and the `Ablo.*` namespace — and TypeScript merges declarations only
- * within a single file, so the three have to sit together. Their bodies do
- * not: the client's shape is `./abloClient`, the pass over the options bag is
- * `./clientPrelude`, and the client this dispatches to is `./reactiveEngine`.
- */
-import type { SchemaRecord } from '../transaction/schema/schema.js';
-import { type AbloHttpClient, type AbloHttpClientOptions } from '../transaction/transport/httpClient.js';
-import { type AbloPlugin, type PluginById, type MergedSurface } from '../transaction/plugin.js';
-import { type AbloCoreClient } from './coreClient.js';
-import type { AbloOptions } from './options.js';
-import type { AbloClient, AbloReads } from './abloClient.js';
-export type { ApiKeySetter, AbloOptions, InternalAbloOptions } from './options.js';
-export type { AbloReads } from './abloClient.js';
-export type { ModelTarget, ModelClaim } from './resourceTypes.js';
-/**
- * The typed sync engine client — one property per model in the schema.
- *
- * The shape itself is declared in `./abloClient`; this alias is what merges
- * with the factory and the namespace under the one `Ablo` name.
- */
-export type Ablo<S extends SchemaRecord> = AbloClient<S>;
-/**
- * Create a sync engine client in one call.
- *
- * ```ts
- * const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- *
- * const reports = sync.weatherReports.list({ where: { status: 'pending' } });
- * await sync.weatherReports.create({ location: 'Stockholm', status: 'pending' });
- * ```
- *
- * In the browser (or any client that shouldn't hold a secret key), point
- * `authEndpoint` at your session-mint route instead — the SDK fetches it, keeps the
- * short-lived token fresh, and re-mints on expiry:
- *
- * ```ts
- * const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
- * ```
- *
- * Pass `transport: 'http'` for the stateless server-side client (agents,
- * workers, serverless) — same `ablo.<model>` surface, no socket:
- *
- * ```ts
- * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
- * await ablo.tasks.update({ id, data: { status: 'done' } });
- * ```
- *
- * Pass `plugins: []` for the core client — the same stateless surface plus
- * the live feed (pushed deltas, presence, claim grants and losses), and no
- * local copy of anything:
- *
- * ```ts
- * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, plugins: [] });
- * await ablo.connect();
- * ablo.subscribe('claim_granted', (grant) => { ... });
- * ```
- */
-export declare function Ablo<const S extends SchemaRecord, const P extends readonly AbloPlugin[] = readonly []>(options: AbloHttpClientOptions<S> & {
-    transport: 'http';
-    plugins?: P;
-}): AbloHttpClient<S> & MergedSurface<P>;
-export declare function Ablo<const S extends SchemaRecord, const P extends readonly AbloPlugin[]>(options: AbloOptions<S> & {
-    plugins: P;
-}): PluginById<P, 'humans'> extends never ? AbloCoreClient<S> & MergedSurface<P> : Ablo<S>;
-export declare function Ablo<const S extends SchemaRecord>(options: AbloOptions<S>): Ablo<S>;
-import type * as _Streams from '../transaction/types/streams.js';
-import type * as _Participants from '../sync/participants.js';
-import type * as _Policy from '../transaction/policy/types.js';
-import type * as _Mutators from '../mutators/defineMutators.js';
-import type * as _Tx from '../mutators/Transaction.js';
-import type * as _Undo from '../mutators/UndoManager.js';
-import type * as _SchemaTypes from '../transaction/schema/schema.js';
-import type * as _Global from '../transaction/types/global.js';
-/**
- * The canonical type namespace.
- *
- * Rules applied uniformly to every addition:
- *
- *   1. Flat by default. `Ablo.X`. Fewest dots wins.
- *   2. Sub-namespace only when (a) four or more types share a single conceptual
- *      prefix and (b) the names read better with it (`Conflict.Kind` over
- *      `ConflictKind`). If the cluster is heterogeneous (streams, data, handles),
- *      keep it flat.
- *   3. Only types a consumer would write `: Ablo.X` for. Inferred-only types stay
- *      unexported.
- *   4. Wire shapes never appear on `Ablo.*` — engine vocabulary only.
- *   5. Advanced or framework-integration types stay internal unless they graduate
- *      into one of the public subpaths.
- */
-export declare namespace Ablo {
-    type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
-    /**
-     * The read view of the client that `useAblo` selectors receive: model reads
-     * typed as reactive rows (data fields + computeds, no relation accessors).
-     */
-    type Reads<S extends SchemaRecord = SchemaRecord> = AbloReads<S>;
-    type IfClaimedPolicy = import('./resourceTypes.js').IfClaimedPolicy;
-    type ClaimedOptions = import('./resourceTypes.js').ClaimedOptions;
-    type ClaimTarget = _Streams.ClaimTarget;
-    type PresenceTarget = _Streams.PresenceTarget;
-    type TargetRange = _Streams.TargetRange;
-    type Duration = _Streams.Duration;
-    type PresenceStream = _Streams.PresenceStream;
-    type ClaimStream = _Streams.ClaimStream;
-    type Peer = _Streams.Peer;
-    type Activity = _Streams.Activity;
-    type Claim = _Streams.Claim;
-    type ClaimRejection = _Streams.ClaimRejection;
-    type ClaimLost = _Streams.ClaimLost;
-    type ClaimHeartbeat = _Streams.ClaimHeartbeat;
-    type ClaimHeartbeatOptions = _Streams.ClaimHeartbeatOptions;
-    type Snapshot<TSchema extends _SchemaTypes.Schema = _SchemaTypes.Schema, K extends keyof TSchema['models'] = keyof TSchema['models']> = _Streams.Snapshot<TSchema, K>;
-    namespace Auth {
-        type Actor = _Streams.ParticipantRef;
-    }
-    namespace Participant {
-        type Manager = _Participants.ParticipantManager;
-        type Joined = _Participants.JoinedParticipant;
-        type Scope = _Participants.ParticipantScope;
-        type Status = _Participants.ParticipantStatus;
-        type JoinOptions = _Participants.ParticipantJoinOptions;
-    }
-    type Schema<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord> = _SchemaTypes.Schema<S>;
-    /**
-     * The schema this program has registered via `interface Register { Schema }`
-     * (falls back to a loose shape when unregistered). Use it where shared code
-     * needs "this app's schema" without importing a specific one —
-     * `Ablo<Ablo.ResolveSchema['models']>` resolves to whatever the consuming
-     * app registered, so one component types correctly across apps that bind
-     * different schemas.
-     */
-    type ResolveSchema = _Global.ResolveSchema;
-    /**
-     * `ResolveSchema` guaranteed to satisfy the `Schema` bound. `ResolveSchema`
-     * falls back to a loose `{ models }` shape when nothing is registered, which
-     * doesn't extend the branded `Schema` type — so generics bounded by `Schema`
-     * (mutator anchors, `Transaction<S>`) can't take `ResolveSchema` directly.
-     * `RegisteredSchema` collapses that fallback to `Schema`, so shared mutator
-     * code can anchor "this app's schema" and stay assignable at the consumer,
-     * which reads the same `Register`. Both resolve in lockstep per app.
-     */
-    type RegisteredSchema = _Global.ResolveSchema extends _SchemaTypes.Schema ? _Global.ResolveSchema : _SchemaTypes.Schema;
-    namespace Schema {
-        type Model<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.Model<S, K>;
-        type InferCreate<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferCreate<S, K>;
-        /**
-         * The reactive-row companion to {@link Model}: data fields + computed
-         * getters, no relation accessors, no model methods — the shape `useAblo`
-         * reads return.
-         */
-        type InferRow<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferRow<S, K>;
-        type InferModelNames<S extends _SchemaTypes.Schema> = _SchemaTypes.InferModelNames<S>;
-    }
-    type Conflict = _Policy.Conflict;
-    namespace Conflict {
-        type Kind = _Policy.ConflictKind;
-        type Operation = _Policy.ConflictOperation;
-        type Decision = _Policy.ConflictDecision;
-        type Policy = _Policy.ConflictPolicy;
-        type Axis = _Policy.ConflictAxis;
-    }
-    namespace Commit {
-        type Wait = import('./resourceTypes.js').CommitWait;
-        type OperationAction = import('./resourceTypes.js').ModelOperationAction;
-        type OperationInput = import('./resourceTypes.js').CommitOperationInput;
-        type CreateOptions = import('./resourceTypes.js').CommitCreateOptions;
-        type Receipt = import('./resourceTypes.js').CommitReceipt;
-        type Client = import('./resourceTypes.js').CommitResource;
-    }
-    namespace Claim {
-        type Handle = import('./resourceTypes.js').Claim;
-        type Held<T = Record<string, unknown>> = import('../transaction/types/streams.js').HeldClaim<T>;
-        type CreateOptions = import('./resourceTypes.js').ClaimCreateOptions;
-        type WaitOptions = import('./resourceTypes.js').ClaimWaitOptions;
-        type Client = import('./resourceTypes.js').ClaimResource;
-    }
-    namespace Model {
-        type Target = import('./resourceTypes.js').ModelTarget;
-        type Claim = import('./resourceTypes.js').ModelClaim;
-        type Operations<T, CreateInput = T> = import('./createModelProxy.js').ModelOperations<T, CreateInput>;
-        type ClaimOptions<T = Record<string, unknown>> = import('./createModelProxy.js').ClaimOptions<T>;
-        type ClaimParams<T = Record<string, unknown>> = import('./createModelProxy.js').ClaimParams<T>;
-        type ClaimLookupParams<T = Record<string, unknown>> = import('./createModelProxy.js').ClaimLookupParams<T>;
-        type ClaimReorderParams<T = Record<string, unknown>> = import('./createModelProxy.js').ClaimReorderParams<T>;
-        type MutationOptions = import('./resourceTypes.js').ModelMutationOptions;
-    }
-    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;
-        type Options<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord, TAuth = unknown> = import('../source/index.js').DataSourceOptions<S, TAuth>;
-        type ModelHandlers<Row, CreateInput, TAuth = unknown> = import('../source/index.js').SourceModelHandlers<Row, CreateInput, TAuth>;
-        type SignatureVerificationResult = import('../source/index.js').SourceSignatureVerificationResult;
-        namespace Commit {
-            type Params<TAuth = unknown> = import('../source/index.js').SourceCommitParams<TAuth>;
-            type Result<Row = Record<string, unknown>> = import('../source/index.js').SourceCommitResult<Row>;
-        }
-    }
-    namespace Mutator {
-        type Fn<S extends _SchemaTypes.Schema, TArgs, TResult = void> = _Mutators.MutatorFn<S, TArgs, TResult>;
-        type Transaction<S extends _SchemaTypes.Schema> = _Tx.Transaction<S>;
-        type UndoEntry = _Undo.UndoEntry;
-        type UndoScope<S extends _SchemaTypes.Schema = _SchemaTypes.Schema> = _Undo.UndoScope<S>;
-        type InverseOp = _Undo.InverseOp;
-    }
-}

package/dist/client/Ablo.js

@@ -1,160 +0,0 @@
-/**
- * `Ablo` — the one-call entry point to the sync engine client. It hides the
- * internal wiring — the object pool, local database, sync client, WebSocket,
- * bootstrap, and offline queue — behind a single function that returns a typed
- * client with one property per model in your schema.
- *
- * Usage:
- *   import { Ablo } from '@abloatai/ablo';
- *   import { schema } from './schema';
- *
- *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- *
- *   const reports = sync.reports.list({ where: { status: 'todo' } });
- *   await sync.reports.create({ data: { title: 'Fix bug' } });
- *   await sync.reports.update({
- *     id: reportId,
- *     data: { status: 'ready' },
- *   });
- *   await sync.reports.delete({ id: reportId });
- *
- * This module is the composition root and the merge point, and only those.
- * `Ablo` is three declarations sharing one name — the factory, the client
- * type, and the `Ablo.*` namespace — and TypeScript merges declarations only
- * within a single file, so the three have to sit together. Their bodies do
- * not: the client's shape is `./abloClient`, the pass over the options bag is
- * `./clientPrelude`, and the client this dispatches to is `./reactiveEngine`.
- */
-import { AbloValidationError } from '../transaction/errors.js';
-import { SyncWebSocket } from '../sync/SyncWebSocket.js';
-// Value import is cycle-safe: httpClient.js and httpTransport.js take the client
-// types from the `options`/`resourceTypes` leaves, never from this module.
-import { createAbloHttpClient, } from '../transaction/transport/httpClient.js';
-// Both halves of the plugin lifecycle: `resolvePlugins` turns the declared list
-// into a surface, `layerPluginSurface` merges that surface onto the built client.
-import { layerPluginSurface, resolvePlugins, } from '../transaction/plugin.js';
-import { noopLogger } from '../transaction/logger.js';
-import { humans } from './humans.js';
-import { kStoreCluster } from './storeCluster.js';
-import { createCoreClient } from './coreClient.js';
-import { buildReactiveEngine } from './reactiveEngine.js';
-import { resolveClientPrelude } from './clientPrelude.js';
-export function Ablo(options) {
-    if (options.transport === 'http') {
-        // Capabilities are declared above transport (ADR 0016): the plugin list
-        // is checked against the selected transport before anything is built, so
-        // a duplex-requiring plugin — humans() — on a request-response client
-        // fails right here, with a typed error naming the plugin, rather than as
-        // a subscription that never delivers.
-        const surface = resolvePlugins(options.plugins ?? [], { duplex: false }, {
-            logger: noopLogger,
-            options,
-        });
-        return layerPluginSurface(createAbloHttpClient(options), surface);
-    }
-    // 1. One pass over the options bag settles the credential and its refresh
-    //    resolver, the base URL, the logger, and this participant's identity —
-    //    and fails on a misconfiguration before anything is constructed.
-    const prelude = resolveClientPrelude(options);
-    const { internalOptions, authCredentials, logger, url, participantId, kind } = prelude;
-    // 2. The connection, built here in the composition root — before the plugin
-    //    list resolves, so `PluginContext.transport` carries the instance a
-    //    plugin holds for the client's lifetime. It holds no socket until
-    //    `connect()`, and `deferConnect` keeps even that closed until the store
-    //    has seeded identity and read scope during `ready()` — the late-bound
-    //    values (`kind`, the credential, `syncGroups`, the resume cursor) are
-    //    seeded there, not here. Whether to build it is read off what the
-    //    listed plugins DECLARE — a plugin that requires a duplex transport
-    //    gets one to attach to — never off a plugin's name; interrogating the
-    //    assembly by id is the context's `hasPlugin`, a capability for
-    //    plugins, not a dispatch key for this root. The empty list builds
-    //    nothing here: the core client (`plugins: []`) constructs its own
-    //    feed, and no plugin runs on that path to read this one.
-    const pluginList = options.plugins ?? [humans()];
-    const transport = pluginList.some((plugin) => plugin.requires?.duplex === true)
-        ? new SyncWebSocket({
-            baseUrl: url,
-            kind,
-            getAuthToken: authCredentials.getAuthToken,
-            collaborationEvents: [...(internalOptions.collaborationEvents ?? [])],
-            syncGroups: [...(internalOptions.syncGroups ?? [])],
-            deferConnect: true,
-        })
-        : null;
-    // Resolve the capability list before anything heavy is constructed
-    // (ADR 0016). The two configuration gates — a duplicate id, a transport
-    // mismatch — fire here, while the stack still points at the caller's own
-    // setup. With no list given, the reactive materialiser is installed:
-    // today's default client. (Flipping the bare default to the stateless core
-    // is the mirror-flip step, decided with the published version identity —
-    // not here.) The context carries the host's resolved values — url,
-    // credential source, identity — so `humans().init` constructs the store
-    // cluster right here, during resolution.
-    const installedPlugins = resolvePlugins(pluginList, { duplex: true }, {
-        logger,
-        observability: internalOptions.observability,
-        // The raw options bag plus the host's resolved values, so plugins
-        // read configuration without re-deriving identity.
-        options,
-        ...(transport ? { transport } : {}),
-        participant: { id: participantId, kind },
-        syncGroups: internalOptions.syncGroups ?? [],
-        url,
-        auth: authCredentials,
-    });
-    const humansSurface = installedPlugins.humans;
-    if (!humansSurface) {
-        // No materialiser requested. The empty list is the core client — the
-        // stateless surface plus the live feed, nothing else. A non-empty list
-        // without humans() has asked for a composition that does not exist yet
-        // (no other plugin is published), so it fails rather than guessing.
-        if ((options.plugins ?? []).length === 0) {
-            return layerPluginSurface(createCoreClient({
-                options,
-                baseUrl: url,
-                participantId,
-                kind,
-                syncGroups: internalOptions.syncGroups ?? [],
-                getAuthToken: authCredentials.getAuthToken,
-                logger,
-                observability: internalOptions.observability,
-            }), installedPlugins);
-        }
-        throw new AbloValidationError('Add humans() to the plugins list, pass an empty list for the core client, ' +
-            'or leave plugins out to get the default.', { code: 'invalid_options', param: 'plugins' });
-    }
-    if (!humansSurface.presence) {
-        // A foreign plugin is squatting on the reserved 'humans' id — its surface
-        // is not the one this client is built from.
-        throw new AbloValidationError("The 'humans' plugin id is reserved for the SDK's own humans() plugin. " +
-            'Rename the custom plugin.', { code: 'invalid_options', param: 'plugins' });
-    }
-    if (!transport) {
-        // Unreachable: the humans surface exists only when the list contained
-        // 'humans', which is exactly the condition the transport was built under.
-        throw new AbloValidationError('The reactive client was selected but no connection was constructed.', { code: 'invalid_options', param: 'plugins' });
-    }
-    const cluster = humansSurface[kStoreCluster];
-    if (!cluster) {
-        // Unreachable on this path: the context above carries everything the
-        // cluster needs (connection, url, credential source, schema). A missing
-        // cluster means the context and the plugin disagree — say so rather
-        // than building a client with no store.
-        throw new AbloValidationError('The reactive client was selected but no store was constructed.', { code: 'invalid_options', param: 'plugins' });
-    }
-    // The reactive engine is the humans() capability: `init` constructed the
-    // store cluster (runtime, component graph, store) from the widened
-    // context; what remains here builds in `./reactiveEngine.ts`, fed the
-    // prelude plus the plugin's contributions. The host owns assembly;
-    // plugins declare and construct their own parts. A plugin surface that
-    // hands back a whole-client constructor inverts that relationship —
-    // tried and rejected (ADR 0016, follow-up 3b).
-    return layerPluginSurface(buildReactiveEngine({
-        ...prelude,
-        options,
-        transport,
-        presence: humansSurface.presence,
-        cluster,
-        createSibling: (siblingOptions) => Ablo(siblingOptions),
-    }), installedPlugins);
-}