@abloatai/humans 0.59.2 → 0.61.0

package/src/local/Model.ts

@@ -416,7 +416,7 @@ export abstract class Model {
     const original = this.getOriginalSnapshot();
     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;
       } else if (original && key in original) {
@@ -463,25 +463,23 @@ export abstract class Model {
     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);
         }
       }
     }
@@ -816,18 +814,16 @@ export abstract class Model {
       result.archivedAt = this.archivedAt?.toISOString() ?? null;
     }
 
-    if (properties) {
-      const self = this as Record<string, unknown>;
-      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 as Record<string, unknown>;
+    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;
       }
     }
 
@@ -946,14 +942,12 @@ export abstract class Model {
       const modelName = this.getModelName();
       const properties = getActiveRegistry().getProperties(modelName);
 
-      if (properties) {
-        const self = this as Record<string, unknown>;
-        for (const [propName, metadata] of properties) {
-          if (metadata.type === 'referenceCollection') {
-            const collection = self[propName] as Disposable | undefined;
-            if (collection?.dispose) {
-              collection.dispose();
-            }
+      const self = this as Record<string, unknown>;
+      for (const [propName, metadata] of properties) {
+        if (metadata.type === 'referenceCollection') {
+          const collection = self[propName] as Disposable | undefined;
+          if (collection) {
+            collection.dispose();
           }
         }
       }
@@ -983,11 +977,9 @@ export abstract class Model {
     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;
@@ -1034,19 +1026,17 @@ export abstract class Model {
 
     const properties = getActiveRegistry().getProperties(this.getModelName());
     const self = this as Record<string, unknown>;
-    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()) {

package/src/local/NetworkMonitor.ts

@@ -14,6 +14,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
   private isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
   private lastOnlineCheck: Date = new Date();
 

package/src/local/RuntimeContext.ts

@@ -106,6 +106,8 @@ export const browserOnlineStatus: OnlineStatusProvider = {
     // 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/src/local/SyncClient.ts

@@ -18,7 +18,7 @@ import { deepEqual, snapshotJsonValue } from '@abloatai/transaction/utils/json';
 import { LoadStrategy } from '@abloatai/transaction/types';
 import { globalRuntime } from './context.js';
 import type { RuntimeContext } from './RuntimeContext.js';
-import { AbloAuthenticationError, AbloError, AbloValidationError } from '@abloatai/transaction/errors';
+import { AbloError, AbloValidationError } from '@abloatai/transaction/errors';
 import { EventEmitter } from 'events';
 import { NetworkMonitor } from './NetworkMonitor.js';
 import {
@@ -51,9 +51,16 @@ import {
   type SyncState,
 } from './syncClientTypes.js';
 import type { BootstrapSnapshot } from './syncClientTypes.js';
+import {
+  batchUploadFiles,
+  uploadFile,
+  type BatchFileUploadOptions,
+  type FileUploadContext,
+  type FileUploadOptions,
+} from './fileUploads.js';
 
 export type { BootstrapSnapshot, RehydrationStats } from './syncClientTypes.js';
-
+const ignoreSeparatelyObservedMutationFailure = (): undefined => undefined;
 export class SyncClient extends EventEmitter {
   private objectPool: InstanceCache;
   private database: Database;
@@ -935,7 +942,8 @@ export class SyncClient extends EventEmitter {
     model: Model,
     poolAction: () => void,
     writeOptions?: WriteOptions,
-  ): void {
+    capturedChangesOverride?: Record<string, unknown>,
+  ): Promise<void> | undefined {
     // No-op UPDATE guard (O(1)). An update with no dirty fields would travel
     // to the server, get dropped by `coalesceOperations` Rule 4 (empty input),
     // and — if it was the only op — come back as `lastSyncId: 0`. That trips
@@ -949,24 +957,32 @@ export class SyncClient extends EventEmitter {
     // is false → we fall through to the normal path rather than risk dropping a
     // real write. Only a genuine Model with an empty dirty-set is skipped.
     const hasChanges: unknown = model.hasChanges;
-    if (type === 'update' && hasChanges === false) {
-      return;
+    if (
+      type === 'update' &&
+      hasChanges === false &&
+      capturedChangesOverride === undefined
+    ) {
+      return Promise.resolve();
     }
 
     // Capture changes before the pool action runs. Pool operations —
     // upsert in particular — can clear the model's local changes, so
     // capturing first ensures they are never lost.
-    const capturedChanges =
-      type === 'update' || type === 'create' ? this.captureModelChanges(model) : undefined;
+    const capturedChanges = capturedChangesOverride !== undefined
+      ? Object.freeze({ ...capturedChangesOverride })
+      : type === 'update' || type === 'create'
+        ? this.captureModelChanges(model)
+        : undefined;
 
     poolAction();
-    this.stageMutation(type, model, capturedChanges, writeOptions);
+    const confirmation = this.stageMutation(type, model, capturedChanges, writeOptions);
     this.notifyObservers({
       type,
       modelType: model.getModelName(),
       model: type !== 'delete' ? model : undefined,
       modelId: model.id,
     });
+    return confirmation;
 
     // QueryProcessor uses `models:changed` to invalidate caches. Coalesce
     // to one event per microtask: a paste of 100 rows should re-run
@@ -1004,13 +1020,23 @@ export class SyncClient extends EventEmitter {
   }
 
   /** Add new model (CREATE) - works offline */
-  add(model: Model, options?: WriteOptions): void {
-    this.mutate('create', model, () => { this.objectPool.add(model, ModelScope.live); }, options);
+  add(model: Model, options?: WriteOptions): Promise<void> | undefined {
+    return this.mutate('create', model, () => { this.objectPool.add(model, ModelScope.live); }, options);
   }
 
   /** Update existing model (UPDATE) - works offline */
-  update(model: Model, options?: WriteOptions): void {
-    this.mutate('update', model, () => { this.objectPool.upsert(model, ModelScope.live); }, options);
+  update(
+    model: Model,
+    options?: WriteOptions,
+    capturedChanges?: Record<string, unknown>,
+  ): Promise<void> | undefined {
+    return this.mutate(
+      'update',
+      model,
+      () => { this.objectPool.upsert(model, ModelScope.live); },
+      options,
+      capturedChanges,
+    );
   }
 
   /**
@@ -1038,7 +1064,7 @@ export class SyncClient extends EventEmitter {
     if (capturedChanges === undefined) return;
 
     this.objectPool.upsert(model, ModelScope.live);
-    this.stageMutation('update', model, capturedChanges);
+    void this.stageMutation('update', model, capturedChanges);
     this.notifyObservers({
       type: 'update',
       modelType: model.getModelName(),
@@ -1055,134 +1081,36 @@ export class SyncClient extends EventEmitter {
   }
 
   /** Delete model (DELETE) - works offline */
-  delete(model: Model, options?: WriteOptions): void {
+  delete(model: Model, options?: WriteOptions): Promise<void> | undefined {
     // Clear pending mutations first to prevent "not found" errors on fast delete
     this.mutationQueue.cancelTransactionsForModel(model.id);
-    this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
+    return this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
   }
 
-  /**
-   * 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.
-   */
-  async uploadFile(
-    file: File,
-    options: {
-      id: string;
-      attachableType: string;
-      attachableId: string;
-      metadata?: Record<string, unknown>;
-    }
-  ): Promise<Model | null> {
-    if (!this.userId || !this.organizationId) {
-      throw new AbloAuthenticationError('Authentication required for file uploads', {
-        code: 'file_upload_auth_required',
-      });
-    }
-
-    try {
-      // Use MutationQueue to handle the upload mutation
-      const result = await this.mutationQueue.uploadAttachment(
-        file,
-        {
-          id: options.id,
-          attachableType: options.attachableType,
-          attachableId: options.attachableId,
-          metadata: options.metadata,
-        },
-        {
-          userId: this.userId,
-          organizationId: this.organizationId,
-        }
-      );
-
-      if (result) {
-        // Create model from response using ModelRegistry (generic — no concrete class import)
-        const model = this.objectPool.createFromData({
-          id: options.id,
-          ...result,
-        });
-
-        if (model) {
-          this.objectPool.add(model, ModelScope.live);
-          this.notifyObservers({
-            type: 'create',
-            modelType: model.getModelName(),
-            model,
-          });
-          return model;
-        }
-      }
-
-      return null;
-    } catch (error) {
-      this.runtime.observability.captureMutationFailure({
-        context: 'file-upload',
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-      throw error;
-    }
-  }
-
-  /**
-   * 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.
-   */
-  async batchUploadFiles(
-    files: File[],
-    options: {
-      ids: string[];
-      attachableType: string;
-      attachableId: string;
-      metadata?: Record<string, unknown>;
-    }
-  ): Promise<Model[]> {
-    if (!this.userId || !this.organizationId) {
-      throw new AbloAuthenticationError('Authentication required for file uploads', {
-        code: 'file_upload_auth_required',
-      });
-    }
-
-    const items = options.ids.map((id) => ({
-      id,
-      attachableType: options.attachableType,
-      attachableId: options.attachableId,
-      metadata: options.metadata,
-    }));
-
-    const results = await this.mutationQueue.batchUploadAttachments(files, items, {
+  private fileUploadContext(): FileUploadContext {
+    return {
       userId: this.userId,
       organizationId: this.organizationId,
-    });
+      mutationQueue: this.mutationQueue,
+      objectPool: this.objectPool,
+      observability: this.runtime.observability,
+      notifyCreated: (model) => {
+        this.notifyObservers({ type: 'create', modelType: model.getModelName(), model });
+      },
+    };
+  }
 
-    const models: Model[] = [];
-    for (const result of results) {
-      const model = this.objectPool.createFromData({ ...result });
-      if (model) {
-        this.objectPool.add(model, ModelScope.live);
-        this.notifyObservers({
-          type: 'create',
-          modelType: model.getModelName(),
-          model,
-        });
-        models.push(model);
-      }
-    }
+  uploadFile(file: File, options: FileUploadOptions): Promise<Model | null> {
+    return uploadFile(this.fileUploadContext(), file, options);
+  }
 
-    return models;
+  batchUploadFiles(files: File[], options: BatchFileUploadOptions): Promise<Model[]> {
+    return batchUploadFiles(this.fileUploadContext(), files, options);
   }
 
   /** Archive model (ARCHIVE) - works offline */
-  archive(model: Model): void {
-    this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
+  archive(model: Model): Promise<void> | undefined {
+    return this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
   }
 
   /**
@@ -1204,8 +1132,8 @@ export class SyncClient extends EventEmitter {
     model: Model,
     capturedChanges?: Record<string, unknown>,
     writeOptions?: WriteOptions,
-  ): void {
-    if (this.isDisposed) return;
+  ): Promise<void> | undefined {
+    if (this.isDisposed) return Promise.resolve();
     if (!this.userId || !this.organizationId) {
       this.mutationQueue.deferMutation(type, model, capturedChanges, writeOptions);
       return;
@@ -1218,6 +1146,13 @@ export class SyncClient extends EventEmitter {
       capturedChanges,
       writeOptions,
     );
+    const confirmation = staging.then(async (transaction) => {
+      await transaction.confirmation;
+    });
+    // Most internal callers intentionally use fire-and-forget writes. Observe
+    // their rejection without replacing the exact promise returned to model
+    // operations that need authoritative per-transaction confirmation.
+    void confirmation.catch(ignoreSeparatelyObservedMutationFailure);
     const pending = staging.then(() => undefined).catch((error: Error) => {
       this.runtime.observability.captureMutationFailure({
         context: `stage-mutation-${type}`,
@@ -1228,6 +1163,7 @@ export class SyncClient extends EventEmitter {
     });
     this.pendingStages.add(pending);
     void pending.finally(() => this.pendingStages.delete(pending));
+    return confirmation;
   }
 
   private scheduleSync(): void {
@@ -1468,14 +1404,11 @@ export class SyncClient extends EventEmitter {
   markConnected(): void {
     this.setConnectionState('connected');
     // Browser online state may have marked the client connected before the
-    // WebSocket itself was ready. Always kick both durable lanes on the real
-    // socket event, even when the high-level state did not change.
-    void this.drainPendingConfirmations().catch((error: unknown) => {
-      this.runtime.observability.captureMutationFailure({
-        context: 'restore-commit-outbox',
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-    });
+    // WebSocket itself was ready. Kick the durable lanes through the staging
+    // barrier: a model mutation enters the in-memory store before its journal
+    // row finishes saving, so a direct reconnect drain can otherwise try to
+    // seal a source record that does not exist yet. The pending drain also
+    // starts the atomic commit lane, so one ordered entry point covers both.
     void this.processPendingMutations();
   }