@abloatai/humans 0.37.0

package/README.md

@@ -0,0 +1,52 @@
+<p align="center">
+  <a href="https://abloatai.com">
+    <img src="https://raw.githubusercontent.com/Abloatai/ablo/main/assets/banner.png" alt="Ablo" width="480" />
+  </a>
+</p>
+
+# @abloatai/humans
+
+The interactive local-state runtime behind Ablo applications.
+
+It turns Ablo's ordered transaction stream into WebSocket-backed local state
+with optimistic updates, rollback, object identity, persistence, presence,
+live queries, MobX integration, and React bindings.
+
+Application code should install the branded Ablo SDK:
+
+```sh
+npm install @abloatai/ablo
+```
+
+For a live client:
+
+```ts
+import { Ablo } from '@abloatai/ablo/client';
+
+const ablo = Ablo({
+  schema,
+  authEndpoint: '/api/ablo-session',
+});
+
+await ablo.ready();
+
+const order = ablo.orders.local.get(orderId);
+```
+
+For React:
+
+```tsx
+import { AbloProvider, useAblo } from '@abloatai/ablo/react';
+```
+
+Use `@abloatai/humans` directly only when building Ablo client plugins or
+framework integrations. Normal applications use `@abloatai/ablo/client` and
+`@abloatai/ablo/react`, which delegate to this package.
+
+## Links
+
+- [Documentation](https://docs.abloatai.com)
+- [Quickstart](https://docs.abloatai.com/quickstart)
+- [API reference](https://docs.abloatai.com/api)
+- [Source](https://github.com/Abloatai/ablo/tree/main/packages/humans)
+- [Apache-2.0 license](https://github.com/Abloatai/ablo/blob/main/LICENSE)

package/dist/Ablo.d.ts

@@ -0,0 +1,208 @@
+/**
+ * `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/humans';
+ *   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 '@abloatai/transaction/schema/schema';
+import { type AbloPlugin, type MergedSurface } from '@abloatai/humans/plugin';
+import type { AbloOptions } from './local/client/options.js';
+import type { AbloClient, AbloReads } from './client.js';
+export type { CredentialProvider, AbloOptions, InternalAbloOptions, } from './local/client/options.js';
+export type { AbloReads } from './client.js';
+export type { ModelTarget, ModelClaim } from './local/client/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' });
+ * ```
+ *
+ * Server-side agents, workers, and services use `@abloatai/transaction`.
+ */
+export declare function Ablo<const S extends SchemaRecord, const P extends readonly AbloPlugin[]>(options: AbloOptions<S> & {
+    plugins: P;
+}): Ablo<S> & MergedSurface<P>;
+export declare function Ablo<const S extends SchemaRecord>(options: AbloOptions<S>): Ablo<S>;
+import type * as _Streams from '@abloatai/transaction/types/streams';
+import type * as _Participants from './local/sync/participants.js';
+import type * as _Policy from '@abloatai/transaction/policy/types';
+import type * as _Mutators from './local/mutators/defineMutators.js';
+import type * as _Tx from './local/mutators/Transaction.js';
+import type * as _Undo from './local/mutators/UndoManager.js';
+import type * as _SchemaTypes from '@abloatai/transaction/schema/schema';
+import type * as _Global from '@abloatai/transaction/types/global';
+/**
+ * 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('./local/client/resourceTypes.js').IfClaimedPolicy;
+    type ClaimedOptions = import('./local/client/resourceTypes.js').ClaimedOptions;
+    type ClaimTarget = _Streams.ClaimTarget;
+    type PresenceTarget = _Streams.PresenceTarget;
+    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('./local/client/resourceTypes.js').CommitWait;
+        type OperationAction = import('./local/client/resourceTypes.js').ModelOperationAction;
+        type OperationInput = import('./local/client/resourceTypes.js').CommitOperationInput;
+        type CreateOptions = import('./local/client/resourceTypes.js').CommitCreateOptions;
+        type Receipt = import('./local/client/resourceTypes.js').CommitReceipt;
+        type Client = import('./local/client/resourceTypes.js').CommitResource;
+    }
+    namespace Claim {
+        type Handle = import('./local/client/resourceTypes.js').Claim;
+        type Held<T = Record<string, unknown>> = import('@abloatai/transaction/types/streams').HeldClaim<T>;
+        type CreateOptions = import('./local/client/resourceTypes.js').ClaimCreateOptions;
+        type WaitOptions = import('./local/client/resourceTypes.js').ClaimWaitOptions;
+        type Client = import('./local/client/resourceTypes.js').ClaimResource;
+    }
+    namespace Model {
+        type Target = import('./local/client/resourceTypes.js').ModelTarget;
+        type Claim = import('./local/client/resourceTypes.js').ModelClaim;
+        type Operations<T, CreateInput = T> = import('./local/client/createModelProxy.js').ModelOperations<T, CreateInput>;
+        type ClaimOptions<T = Record<string, unknown>> = import('./local/client/createModelProxy.js').ClaimOptions<T>;
+        type ClaimParams<T = Record<string, unknown>> = import('./local/client/createModelProxy.js').ClaimParams<T>;
+        type ClaimLookupParams<T = Record<string, unknown>> = import('./local/client/createModelProxy.js').ClaimLookupParams<T>;
+        type ClaimReorderParams<T = Record<string, unknown>> = import('./local/client/createModelProxy.js').ClaimReorderParams<T>;
+        type MutationOptions = import('./local/client/resourceTypes.js').ModelMutationOptions;
+    }
+    namespace Source {
+        type Operation = import('@abloatai/transaction/source').SourceOperation;
+        type Event = import('@abloatai/transaction/source').SourceEvent;
+        type EventForOperationOptions = import('@abloatai/transaction/source').SourceEventForOperationOptions;
+        type EventsResult = import('@abloatai/transaction/source').SourceEventsResult;
+        type Scope = import('@abloatai/transaction/source').SourceScope;
+        type ApiKey = import('@abloatai/transaction/source').SourceApiKey;
+        type Options<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord, TAuth = unknown> = import('@abloatai/transaction/source').DataSourceOptions<S, TAuth>;
+        type ModelHandlers<Row, CreateInput, TAuth = unknown> = import('@abloatai/transaction/source').SourceModelHandlers<Row, CreateInput, TAuth>;
+        type SignatureVerificationResult = import('@abloatai/transaction/source').SourceSignatureVerificationResult;
+        namespace Commit {
+            type Params<TAuth = unknown> = import('@abloatai/transaction/source').SourceCommitParams<TAuth>;
+            type Result<Row = Record<string, unknown>> = import('@abloatai/transaction/source').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/Ablo.js

@@ -0,0 +1,120 @@
+/**
+ * `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/humans';
+ *   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 '@abloatai/transaction/errors';
+import { SyncWebSocket } from './local/sync/SyncWebSocket.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 '@abloatai/humans/plugin';
+import { humans } from './humans.js';
+import { kStoreCluster } from './local/client/storeCluster.js';
+import { buildReactiveEngine } from './local/client/reactiveEngine.js';
+import { resolveClientPrelude } from './local/client/clientPrelude.js';
+export function Ablo(options) {
+    // 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.
+    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 local store is installed.
+    // 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) {
+        throw new AbloValidationError('The humans client requires the humans() materializer plugin.', { 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);
+}