@abloatai/humans 0.59.2 → 0.61.0

package/README.md

@@ -25,7 +25,7 @@ import { Ablo } from '@abloatai/ablo/client';
 
 const ablo = Ablo({
   schema,
-  authEndpoint: '/api/ablo-session',
+  session: { endpoint: '/api/ablo-session' },
 });
 
 await ablo.ready();

package/dist/Ablo.d.ts

@@ -50,11 +50,11 @@ export type Ablo<S extends SchemaRecord> = AbloClient<S>;
  * ```
  *
  * 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
+ * `session.endpoint` 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' });
+ * const ablo = Ablo({ schema, session: { endpoint: '/api/ablo-session' } });
  * ```
  *
  * Server-side agents, workers, and services use `@abloatai/transaction`.
@@ -64,7 +64,6 @@ export declare function Ablo<const S extends SchemaRecord, const P extends reado
 }): 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 _Mutators from './local/mutators/defineMutators.js';
 import type * as _Tx from './local/mutators/Transaction.js';
 import type * as _Undo from './local/mutators/UndoManager.js';
@@ -110,13 +109,6 @@ export declare namespace Ablo {
     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 }`

package/dist/Ablo.js

@@ -115,6 +115,5 @@ export function Ablo(options) {
         transport,
         presence: humansSurface.presence,
         cluster,
-        createSibling: (siblingOptions) => Ablo(siblingOptions),
     }), installedPlugins);
 }

package/dist/client.d.ts

@@ -17,7 +17,7 @@ import type { SyncStoreContract } from './react/context.js';
 import type { SyncWebSocket, CoreSyncEventMap } from './local/sync/SyncWebSocket.js';
 import type { SyncStatus } from './local/BaseSyncedStore.js';
 import type { ModelOperations } from './local/client/createModelOperations.js';
-import type { ClaimResource, CommitResource, CreateAgentClientParams, SessionResource } from '@abloatai/transaction/client/resources/httpResources';
+import type { ClaimResource, CommitResource } from '@abloatai/transaction/client/resources/httpResources';
 import type { EffectiveAuthority } from '@abloatai/transaction/auth';
 import type { ReadDependency } from '@abloatai/transaction/coordination';
 import type { CapturedRow } from '@abloatai/transaction/transport/http';
@@ -102,53 +102,6 @@ export type AbloClient<S extends SchemaRecord> = {
      * the watchdog.
      */
     nudgeReconnect(): void;
-    /**
-     * Mint a short-lived, scoped session token for one end user. Call this on your
-     * backend, where the `sk_` secret key lives, then hand the returned `token` to
-     * that user's browser — typically through a token route the browser's `apiKey`
-     * resolver fetches. The browser presents the token as its bearer, and the
-     * server verifies it. The browser must never see the `sk_` key, only the
-     * per-user session token.
-     *
-     * Pass `{ user: { id }, can: { items: ['read', 'update'] } }` for an end-user
-     * session. It mints an `ek_` and attributes writes to a user (recorded as
-     * `actor_kind` on the delta row). Pass `{ agent: { id }, can: {
-     * items: ['update'] } }` for a scoped agent session, which mints an `rk_`.
-     * Both kinds require `can`, typed against your schema's model names. This
-     * always authenticates with the original `sk_`, never the client's exchanged
-     * sync credential.
-     */
-    sessions: SessionResource<S>;
-    /**
-     * Mint a scoped **agent identity** and return a ready-to-use client bound to
-     * it — the `ablo.<resource>.<verb>` shape for the agent use case. One call
-     * replaces `sessions.create({ agent, can })` + constructing a second
-     * `Ablo({ apiKey: token })`:
-     *
-     * ```ts
-     * const agent = await ablo.agents.create({
-     *   name: 'researcher',                  // readable label (optional)
-     *   can: { records: ['read', 'update'] },
-     *   // id omitted → a fresh uuid: a distinct, independent participant
-     * });
-     * await agent.records.update({ id, data, claim });
-     * await agent.dispose(); // when the agent is done
-     * ```
-     *
-     * Server-side only: it requires the `sk_` secret key (like `sessions.create`)
-     * and throws `AbloAuthenticationError` in the browser. The returned client
-     * holds its own auto-refreshing `rk_`, so a long run never hits token expiry,
-     * and the `sk_` never leaves this process. Each call is a distinct participant
-     * by default (omit `id` for a fresh uuid), so even two agents sharing a `name`
-     * queue behind one another on a contended row — `name` is display only and
-     * never collapses identity. Humans don't get a server-built client; ship them a
-     * token via `sessions.create({ user, can })`. If you need the raw token for
-     * revocation, or a stable re-attachable id, use `sessions.create({ agent, can })`
-     * or pass `id`.
-     */
-    agents: {
-        create(params: CreateAgentClientParams<S>): Promise<AbloClient<S>>;
-    };
     /**
      * The organization this client resolved to — `null` until `ready()`
      * completes. Use it instead of scraping CLI output or hardcoding env vars:

package/dist/humans.d.ts

@@ -13,7 +13,7 @@ export interface HumansSurface {
     readonly [kStoreCluster]?: StoreCluster;
 }
 export declare function humans(): {
-    readonly id: 'humans';
+    readonly id: "humans";
     readonly requires: {
         readonly duplex: true;
     };

package/dist/local/BaseSyncedStore.d.ts

@@ -13,7 +13,7 @@
 import type { RecoveryClass } from '@abloatai/transaction/errorCodes';
 import { ConnectionManager } from './sync/ConnectionManager.js';
 import { SubscriptionManager } from './sync/SubscriptionManager.js';
-import { type ParticipantScope } from './sync/participants.js';
+import { type GroupScope } from './sync/scopeGroups.js';
 import type { SyncClient } from './SyncClient.js';
 import type { Database, BootstrapResult, BootstrapRequirements } from './Database.js';
 import type { InstanceCache } from './InstanceCache.js';
@@ -254,7 +254,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * Hydration is best-effort — a failed backfill never rejects `enterScope`,
      * and the live delta stream keeps flowing regardless.
      */
-    enterScope(scope: ParticipantScope, opts?: {
+    enterScope(scope: GroupScope, opts?: {
         hydrate?: boolean;
     }): Promise<void>;
     /**
@@ -266,11 +266,11 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      */
     protected hydrateGroups(syncGroups: readonly string[]): Promise<void>;
     /** Leave a scope → its groups go warm (hysteresis), then drop on sweep. */
-    leaveScope(scope: ParticipantScope): Promise<void>;
+    leaveScope(scope: GroupScope): Promise<void>;
     /** Pin a scope (active claim / prominence) → never warms while pinned. */
-    pinScope(scope: ParticipantScope): Promise<void>;
+    pinScope(scope: GroupScope): Promise<void>;
     /** Release a pin → the group transitions to warm rather than dropping. */
-    unpinScope(scope: ParticipantScope): Promise<void>;
+    unpinScope(scope: GroupScope): Promise<void>;
     protected readonly queryProcessor: QueryProcessor;
     /**
      * Runtime behavior flags only — the schema/config arrays

package/dist/local/BaseSyncedStore.js

@@ -15,7 +15,7 @@ import { AbloConnectionError, AbloValidationError, toAbloError } from '@abloatai
 import { ConnectionManager } from './sync/ConnectionManager.js';
 import { contextLogger, contextSocketObservability } from './sync/contextPorts.js';
 import { SubscriptionManager } from './sync/SubscriptionManager.js';
-import { resolveParticipantSyncGroups, } from './sync/participants.js';
+import { resolveScopeGroups, } from './sync/scopeGroups.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { PropertyType } from '@abloatai/transaction/types';
 import { SyncWebSocket, } from './sync/SyncWebSocket.js';
@@ -180,7 +180,7 @@ export class BaseSyncedStore {
     // {@link SubscriptionManager.reconcile}); the on-connect `resync` pushes
     // whatever interest accumulated.
     scopeToGroups(scope) {
-        return resolveParticipantSyncGroups(scope, this.schema);
+        return resolveScopeGroups(scope, this.schema);
     }
     /**
      * Bring a scope into view and subscribe to its sync groups. With
@@ -1334,10 +1334,10 @@ export class BaseSyncedStore {
         const isCreate = !this.objectPool.get(model.id);
         if (isCreate) {
             model.updatedAt = new Date();
-            this.syncClient.add(model);
+            await this.syncClient.add(model);
         }
         else {
-            this.syncClient.update(model);
+            await this.syncClient.update(model);
         }
     }
     /** Save with an atomic server mutation (e.g., createSectionWithBlocks) */
@@ -1350,19 +1350,19 @@ export class BaseSyncedStore {
         const model = rowAsModel(entity);
         this.pendingDeletes.add(model.id);
         // SyncClient.delete handles: pool remove, transaction queue
-        this.syncClient.delete(model);
+        await this.syncClient.delete(model);
     }
     /** Archive a model. Accepts schema-inferred entity shapes (see `save`). */
     async archive(entity) {
         const model = rowAsModel(entity);
         model.archivedAt = new Date();
-        this.syncClient.archive(model);
+        await this.syncClient.archive(model);
     }
     /** Unarchive a model. Accepts schema-inferred entity shapes (see `save`). */
     async unarchive(entity) {
         const model = rowAsModel(entity);
         model.archivedAt = null;
-        this.syncClient.update(model);
+        await this.syncClient.update(model);
     }
     // ── Query API ────────────────────────────────────────────────────────────
     // `ablo.<model>.local.get` / `.local.list` is the read surface for

package/dist/local/Database.d.ts

@@ -101,7 +101,7 @@ export declare class Database {
      * where a missing store points to silent data loss. Callers that
      * already expect optional behavior (e.g. lazy lookups) can omit it.
      */
-    getStore(modelName: string, context?: string): InMemoryObjectStore | import("./stores/ObjectStore.js").ObjectStore | undefined;
+    getStore(modelName: string, context?: string): import("./stores/ObjectStore.js").ObjectStore | InMemoryObjectStore | undefined;
     /** Get store or throw if not found (for operations that require the store). */
     private getRequiredStore;
     /** Log preserved fields during partial UPDATE merge (debug helper) */
@@ -274,7 +274,7 @@ export declare class Database {
      * `getStore(modelName, context?)` is defined near the top of this
      * class — single accessor for both inMemory and IDB modes.
      */
-    getAllStores(): Map<string, InMemoryObjectStore> | Map<string, import("./stores/ObjectStore.js").ObjectStore>;
+    getAllStores(): Map<string, import("./stores/ObjectStore.js").ObjectStore> | Map<string, InMemoryObjectStore>;
     /**
      * Model persistence tracking
      */

package/dist/local/LazyReferenceCollection.d.ts

@@ -65,7 +65,7 @@ export declare class LazyReferenceCollection<T extends Model> {
     private get database();
     /** Get objectPool from static dependencies */
     private get objectPool();
-    constructor(modelName: string, parent: Model, foreignKey: string, customQuery?: any, options?: LazyCollectionOptions);
+    constructor(modelName: string, parent: Model, foreignKey: string, customQuery?: any | undefined, options?: LazyCollectionOptions);
     /**
      * Set up MobX observation lifecycle hooks
      * When React components observe this collection, we prevent GC of the parent model

package/dist/local/Model.js

@@ -311,7 +311,7 @@ export class Model {
         for (const key of keys) {
             if (key === 'id')
                 continue;
-            const mod = modified?.get(key);
+            const mod = modified.get(key);
             if (mod) {
                 out[key] = mod.old;
             }
@@ -358,25 +358,23 @@ export class Model {
         const errors = [];
         const modelName = this.getModelName();
         const properties = getActiveRegistry().getProperties(modelName);
-        if (properties) {
-            const json = this.toJSON();
-            for (const [propName, metadata] of properties) {
-                // Check required fields
-                if (!metadata.nullable && !metadata.optional) {
-                    const value = json[propName];
-                    if (value == null || value === '') {
-                        errors.push(`${propName} is required`);
-                    }
+        const json = this.toJSON();
+        for (const [propName, metadata] of properties) {
+            // Check required fields
+            if (!metadata.nullable && !metadata.optional) {
+                const value = json[propName];
+                if (value == null || value === '') {
+                    errors.push(`${propName} is required`);
                 }
-                // Run custom validation rules
-                const rules = this.validationRules[propName];
-                if (rules) {
-                    const value = json[propName];
-                    for (const rule of rules) {
-                        const error = rule(value);
-                        if (error)
-                            errors.push(error);
-                    }
+            }
+            // Run custom validation rules
+            const rules = this.validationRules[propName];
+            if (rules) {
+                const value = json[propName];
+                for (const rule of rules) {
+                    const error = rule(value);
+                    if (error)
+                        errors.push(error);
                 }
             }
         }
@@ -679,20 +677,18 @@ export class Model {
         if (this.archivedAt !== undefined) {
             result.archivedAt = this.archivedAt?.toISOString() ?? null;
         }
-        if (properties) {
-            const self = this;
-            for (const [propName, metadata] of properties) {
-                // Skip certain types
-                if (metadata.type === 'ephemeralProperty')
-                    continue;
-                if (metadata.type === 'referenceModel')
-                    continue;
-                if (metadata.type === 'referenceCollection')
-                    continue;
-                const value = self[propName];
-                if (value !== undefined) {
-                    result[propName] = value;
-                }
+        const self = this;
+        for (const [propName, metadata] of properties) {
+            // Skip certain types
+            if (metadata.type === 'ephemeralProperty')
+                continue;
+            if (metadata.type === 'referenceModel')
+                continue;
+            if (metadata.type === 'referenceCollection')
+                continue;
+            const value = self[propName];
+            if (value !== undefined) {
+                result[propName] = value;
             }
         }
         return result;
@@ -793,14 +789,12 @@ export class Model {
         if (hasActiveRegistry()) {
             const modelName = this.getModelName();
             const properties = getActiveRegistry().getProperties(modelName);
-            if (properties) {
-                const self = this;
-                for (const [propName, metadata] of properties) {
-                    if (metadata.type === 'referenceCollection') {
-                        const collection = self[propName];
-                        if (collection?.dispose) {
-                            collection.dispose();
-                        }
+            const self = this;
+            for (const [propName, metadata] of properties) {
+                if (metadata.type === 'referenceCollection') {
+                    const collection = self[propName];
+                    if (collection) {
+                        collection.dispose();
                     }
                 }
             }
@@ -825,11 +819,9 @@ export class Model {
         const snapshot = {};
         const modelName = this.getModelName();
         const properties = getActiveRegistry().getProperties(modelName);
-        if (properties) {
-            const json = this.toJSON();
-            for (const [propName] of properties) {
-                snapshot[propName] = json[propName];
-            }
+        const json = this.toJSON();
+        for (const [propName] of properties) {
+            snapshot[propName] = json[propName];
         }
         return snapshot;
     }
@@ -874,17 +866,15 @@ export class Model {
             snapshot.archivedAt = this.archivedAt;
         const properties = getActiveRegistry().getProperties(this.getModelName());
         const self = this;
-        if (properties) {
-            for (const [propName, metadata] of properties) {
-                if (metadata.type === 'ephemeralProperty' ||
-                    metadata.type === 'referenceModel' ||
-                    metadata.type === 'referenceCollection') {
-                    continue;
-                }
-                // Reading through the observable getter is the point: it subscribes the
-                // enclosing MobX reaction to this field.
-                snapshot[propName] = self[propName];
+        for (const [propName, metadata] of properties) {
+            if (metadata.type === 'ephemeralProperty' ||
+                metadata.type === 'referenceModel' ||
+                metadata.type === 'referenceCollection') {
+                continue;
             }
+            // Reading through the observable getter is the point: it subscribes the
+            // enclosing MobX reaction to this field.
+            snapshot[propName] = self[propName];
         }
         for (const name of this.getDerivedGetterNames()) {
             Object.defineProperty(snapshot, name, {

package/dist/local/NetworkMonitor.js

@@ -12,6 +12,8 @@ export class NetworkMonitor extends EventEmitter {
     // Only `navigator.onLine === false` means offline. Node 18+ exposes a global
     // `navigator` with `onLine === undefined`, so the naive `navigator.onLine`
     // would seed `false` (offline) on every server client — start optimistic.
+    // DOM types say `onLine` is boolean, but Node exposes it as undefined.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-boolean-literal-compare
     isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
     lastOnlineCheck = new Date();
     constructor(runtime = globalRuntime) {

package/dist/local/RuntimeContext.js

@@ -47,6 +47,8 @@ export const browserOnlineStatus = {
         // signal. Don't use `!navigator.onLine`: Node 18+ exposes a global
         // `navigator` whose `onLine` is `undefined`, which `!` would read as offline —
         // wedging every Node/server client (agents, worker, MCP) into a false offline.
+        // DOM types say `onLine` is boolean, but Node exposes it as undefined.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-boolean-literal-compare
         return !(typeof navigator !== 'undefined' && navigator.onLine === false);
     },
 };

package/dist/local/SyncClient.d.ts

@@ -21,6 +21,7 @@ import type { WriteOptions } from './interfaces/index.js';
 import { LogPosition } from './logPosition.js';
 import { type RehydrationStats, type SyncObserver, type SyncState } from './syncClientTypes.js';
 import type { BootstrapSnapshot } from './syncClientTypes.js';
+import { type BatchFileUploadOptions, type FileUploadOptions } from './fileUploads.js';
 export type { BootstrapSnapshot, RehydrationStats } from './syncClientTypes.js';
 export declare class SyncClient extends EventEmitter {
     private readonly runtime;
@@ -186,9 +187,9 @@ export declare class SyncClient extends EventEmitter {
      */
     private captureModelChanges;
     /** Add new model (CREATE) - works offline */
-    add(model: Model, options?: WriteOptions): void;
+    add(model: Model, options?: WriteOptions): Promise<void> | undefined;
     /** Update existing model (UPDATE) - works offline */
-    update(model: Model, options?: WriteOptions): void;
+    update(model: Model, options?: WriteOptions, capturedChanges?: Record<string, unknown>): Promise<void> | undefined;
     /**
      * Update existing model with pre-computed changes.
      * Used by saveManyOptimized when incoming models have empty change-tracking
@@ -200,37 +201,12 @@ export declare class SyncClient extends EventEmitter {
      *  but still need optimistic pool updates at the sync layer. */
     get gql(): import("./interfaces/index.js").MutationExecutor;
     /** Delete model (DELETE) - works offline */
-    delete(model: Model, options?: WriteOptions): void;
-    /**
-     * Upload a file and create its attachment record. The upload runs through
-     * the {@link MutationQueue}, and a model is built from the server's
-     * response and added to the pool.
-     */
-    uploadFile(file: File, options: {
-        id: string;
-        attachableType: string;
-        attachableId: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<Model | null>;
-    /**
-     * Batch upload files — single GraphQL call + parallel S3 PUTs.
-     *
-     * Returns the raw `Model[]` built by the object pool (typename is
-     * determined by the payload the server returns — currently always
-     * `Attachment`). The SDK has no knowledge of app-specific model classes,
-     * so it cannot honestly claim a narrower return type; consumers that
-     * need an `Attachment[]` project through their own typed accessor
-     * (e.g. `store.query.attachments.findMany({ where: { id: IN ids } })`)
-     * after the upload resolves.
-     */
-    batchUploadFiles(files: File[], options: {
-        ids: string[];
-        attachableType: string;
-        attachableId: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<Model[]>;
+    delete(model: Model, options?: WriteOptions): Promise<void> | undefined;
+    private fileUploadContext;
+    uploadFile(file: File, options: FileUploadOptions): Promise<Model | null>;
+    batchUploadFiles(files: File[], options: BatchFileUploadOptions): Promise<Model[]>;
     /** Archive model (ARCHIVE) - works offline */
-    archive(model: Model): void;
+    archive(model: Model): Promise<void> | undefined;
     /**
      * Append a mutation to the pending queue and schedule its sync work.
      *
@@ -409,14 +385,14 @@ export declare class SyncClient extends EventEmitter {
      * Get detailed debug info for the sync debug page
      */
     getDebugInfo(): {
-        connectionState: "connected" | "connecting" | "disconnected";
+        connectionState: "connected" | "disconnected" | "connecting";
         pendingMutationsCount: number;
         mutationQueue: {
             lastSeenSyncId: number;
             awaitingDeltaCount: number;
             awaitingDeltaTransactions: {
                 id: string;
-                type: "archive" | "create" | "delete" | "unarchive" | "update";
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
                 modelName: string;
                 modelId: string;
                 syncIdNeeded: number | undefined;
@@ -425,13 +401,13 @@ export declare class SyncClient extends EventEmitter {
             }[];
             pendingTransactions: {
                 id: string;
-                type: "archive" | "create" | "delete" | "unarchive" | "update";
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
                 modelName: string;
                 modelId: string;
             }[];
             executingTransactions: {
                 id: string;
-                type: "archive" | "create" | "delete" | "unarchive" | "update";
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
                 modelName: string;
                 modelId: string;
             }[];