@abloatai/ablo 0.3.0

package/dist/SyncClient.d.ts

@@ -0,0 +1,489 @@
+/**
+ * SyncClient - Mutation and offline queue manager
+ *
+ * Responsibilities:
+ * - Handle model mutations (create, update, delete, archive)
+ * - Manage offline mutation queue with persistence
+ * - Send mutations to server via API client
+ * - Handle conflict resolution for local changes
+ */
+import { ObjectPool } from './ObjectPool.js';
+import { Model } from './Model.js';
+import { EventEmitter } from 'events';
+import { TransactionQueue } from './transactions/TransactionQueue.js';
+import { type OptimisticEchoMetrics } from './transactions/OptimisticEchoTracker.js';
+import type { Database } from './Database.js';
+import type { MutationOptions } from './interfaces/index.js';
+interface SyncObserver {
+    onSync?: (event: SyncEvent) => void;
+}
+interface SyncEvent {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'rollback';
+    modelType: string;
+    model?: Model;
+    modelId?: string;
+    transactionType?: string;
+}
+interface SyncState {
+    connectionState: 'connected' | 'disconnected' | 'connecting';
+    pendingMutations: number;
+    lastSyncAt?: Date;
+    error?: Error;
+}
+export interface RehydrationStats {
+    added: number;
+    updated: number;
+    removed: number;
+    skipped: number;
+    healed: number;
+    elapsedMs: number;
+}
+type MutationWriteOptions = Pick<MutationOptions, 'readAt' | 'onStale'>;
+export declare class SyncClient extends EventEmitter {
+    private objectPool;
+    private database;
+    private get mutationExecutor();
+    private networkMonitor;
+    private transactionQueue;
+    private observers;
+    private userId;
+    private organizationId;
+    private pendingMutations;
+    /**
+     * Tracks transaction ids the client has optimistically applied but
+     * the server has not yet confirmed. The receive path consults it
+     * to recognize delta echoes of own mutations and suppress the
+     * (otherwise-redundant) pool mutation — the IDB write still runs
+     * because the delta is the authoritative version of the row.
+     *
+     * The receive-layer discriminator named in
+     * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`. Without
+     * it, an optimistically-applied DELETE followed by a
+     * server-confirming CREATE echo resurrects the row for the window
+     * between the two confirmations (the chart-delete flicker).
+     *
+     * Bounded with FIFO eviction; observability via `getEchoMetrics()`.
+     */
+    private readonly echoTracker;
+    private connectionState;
+    private offlineSince?;
+    private maxRetries;
+    private isDisposed;
+    constructor(objectPool: ObjectPool, database: Database);
+    /**
+     * Setup network monitoring handlers
+     */
+    private setupNetworkMonitoring;
+    /**
+     * Handle transaction rollback. Two distinct shapes flow through this
+     * event:
+     *
+     *   1. **Server-rejected rollback** (`reason === 'permanent_error'`,
+     *      `'max_retries_exhausted'`, `'conflict_server_wins'`) — the
+     *      optimistic state is wrong, the row exists, restore previous
+     *      state and notify the UI.
+     *
+     *   2. **Local-cancellation cleanup** (`reason === 'model_cancelled'`,
+     *      `'cascade_parent_deleted'`) — the user deleted this model (or
+     *      its parent), so a pending UPDATE on it gets cancelled. There's
+     *      nothing to restore (the model is doomed) and no UI notification
+     *      needed (the delete itself already triggered re-renders). Just
+     *      discard the optimistic state silently.
+     *
+     * Treating both paths the same caused the deletion-flicker bug: every
+     * cancelled update on a multi-layer chart fired a per-model observer
+     * event and a `[SyncClient.rollback]` warn, producing N renders and N
+     * spam log lines for one user-initiated delete.
+     */
+    private setupTransactionRollbackHandling;
+    /**
+     * Forward reconciliation requests from TransactionQueue to the sync layer.
+     * When delta confirmation times out, TransactionQueue emits 'reconciliation:needed'
+     * instead of rolling back — following the Replicache/PowerSync pattern of never
+     * destroying optimistic state that the server may have committed.
+     */
+    private setupReconciliationForwarding;
+    /**
+     * LINEAR PATTERN: Persist unconfirmed transactions to IndexedDB.
+     * When delta confirmation retries exhaust, the transaction data is cached in IDB
+     * so it survives tab close. On next session, WebSocket reconnect + delta catch-up
+     * will deliver the missing deltas and naturally confirm the transaction.
+     */
+    private setupAwaitingTransactionPersistence;
+    /**
+     * Initialize sync client with authentication
+     */
+    initialize(userId: string, organizationId: string): Promise<void>;
+    /**
+     * Self-healing helper for individual model records.
+     *
+     * Two registry-driven repair passes run on every row hydrated from
+     * IDB or merged from a delta:
+     *
+     * 1. **Auto-fill** — for each `autoFill` rule the consumer's schema
+     *    declares on this model, copy the corresponding identity value
+     *    (`organizationId` / `userId`) onto the row when it's missing.
+     *    Repairs rows from a past version that didn't write the field.
+     *
+     * 2. **Required-field gate** — if the row is missing any field listed
+     *    in the model's `requiredFields`, return `null` so the caller
+     *    skips this record. Used for FK columns whose absence renders the
+     *    row unrecoverable (e.g. a SlideLayer with no slideId).
+     *
+     * The engine itself is product-neutral: model identity (which fields
+     * to back-fill, which absences are fatal) lives entirely in the
+     * consumer schema.
+     */
+    healModelRecord(modelType: string, data: Record<string, unknown>): {
+        data: Record<string, unknown>;
+        healed: boolean;
+    } | null;
+    /**
+     * Hydrate ObjectPool with data from Database
+     * Called after bootstrap is complete
+     */
+    hydrateFromDatabase(): Promise<void>;
+    /**
+     * Re-hydrate ObjectPool from IndexedDB when the pool already has data.
+     *
+     * Unlike hydrateFromDatabase() (which uses addBatch and skips existing IDs),
+     * this method properly:
+     *   1. Upserts models — updates existing models in-place, adds new ones
+     *   2. Removes ghosts — deletes models from the pool that no longer exist in IndexedDB
+     *
+     * Used by background bootstrap, network recovery, and server-triggered re-bootstrap.
+     */
+    rehydrateFromDatabase(): Promise<RehydrationStats>;
+    /**
+     * Mutate model optimistically and queue for server sync.
+     * IndexedDB is only updated when server confirms via delta packet.
+     *
+     * CRITICAL: Changes are captured BEFORE poolAction to prevent data loss.
+     * The captured changes are frozen and passed to queueMutation.
+     *
+     * @see src/sync-engine/types/TrackableModel.ts for change capture pattern
+     */
+    private mutate;
+    private pendingChangedTypes;
+    private markModelChanged;
+    /**
+     * Capture model changes immutably BEFORE any pool operations
+     * This prevents the fragile pattern of reading changes after state modification
+     */
+    private captureModelChanges;
+    /** Add new model (CREATE) - works offline */
+    add(model: Model, options?: MutationWriteOptions): void;
+    /** Update existing model (UPDATE) - works offline */
+    update(model: Model, options?: MutationWriteOptions): void;
+    /**
+     * Update existing model with pre-computed changes.
+     * Used by saveManyOptimized when incoming models have empty change-tracking
+     * (e.g. freshly constructed SpreadsheetCellModels from decomposeSpreadsheetDocument).
+     */
+    updateWithChanges(model: Model, changes?: Record<string, unknown>): void;
+    /** Expose the GraphQL client for atomic mutations (e.g., createSlideWithLayers).
+     *  Used by SyncedStore for operations that bypass the transaction queue
+     *  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?: MutationWriteOptions): void;
+    /**
+     * Clear all pending mutations for a specific model
+     * Called before deletion to prevent "layer not found" errors on the server
+     */
+    private clearPendingMutationsForModel;
+    /**
+     * Upload file and create attachment (UPLOAD operation)
+     * Uses Linear-style pattern with immediate URL generation
+     */
+    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[]>;
+    /** Archive model (ARCHIVE) - works offline */
+    archive(model: Model): void;
+    /**
+     * Append a mutation and schedule its sync work.
+     *
+     * IDB persistence and the server push are deferred to a microtask so N
+     * pushes inside the same tick collapse into ONE IDB serialization + ONE
+     * process call. Without the deferral, queueing 100 mutations (paste,
+     * PPTX import, AI sandbox layer creation) reserializes the entire
+     * growing queue 100× — O(N²) `model.toJSON()`.
+     *
+     * @param mutation.capturedChanges - Pre-captured changes (frozen), used
+     *   to avoid re-reading changes after pool ops that might clear them.
+     */
+    private queueMutation;
+    private syncScheduled;
+    private scheduleSync;
+    /**
+     * Persist mutation queue to IndexedDB
+     */
+    private persistMutationQueue;
+    /**
+     * Restore mutation queue from IndexedDB
+     */
+    private restoreMutationQueue;
+    /**
+     * Process pending mutations - can be called by SyncedStore when online
+     *
+     * Best Practice: Only sync models that still exist locally (local-first principle)
+     * - If a model was deleted locally → skip any pending updates/creates for it
+     * - This prevents "layer not found" errors from fast copy-paste-delete workflows
+     */
+    processPendingMutations(): Promise<void>;
+    /**
+     * Stage mutation to TransactionQueue - mutations in same tick are batched via microtask
+     *
+     * @param mutation.capturedChanges - Pre-captured changes to use instead of re-reading from model
+     */
+    private stageMutation;
+    /**
+     * Resolve conflicts between local and server data
+     * Used when processing deltas from WebSocket
+     *
+     * CRITICAL: Always respects certain server states (deletes, deactivations)
+     * even when there are local changes, to maintain data consistency.
+     */
+    resolveConflicts(localModel: Model, serverData: any): Model;
+    /**
+     * Extract critical state fields from server data
+     * These are states that must always be respected, even with local changes
+     */
+    private extractCriticalState;
+    /**
+     * Check if critical state changes exist that require forcing server state
+     */
+    private hasCriticalStateChange;
+    /**
+     * Handle network reconnection
+     */
+    private handleReconnection;
+    /**
+     * Handle network disconnection
+     */
+    private handleDisconnection;
+    /**
+     * Get current sync state
+     */
+    getState(): SyncState;
+    /**
+     * Set connection state
+     */
+    private setConnectionState;
+    /**
+     * Subscribe to events with disposer pattern
+     */
+    subscribe(event: string, handler: (data?: unknown) => void): () => void;
+    /**
+     * Add observer for sync events
+     */
+    addObserver(observer: SyncObserver): void;
+    /**
+     * Remove observer
+     */
+    removeObserver(observer: SyncObserver): void;
+    /**
+     * Notify all observers
+     */
+    private notifyObservers;
+    /**
+     * Disconnect from sync
+     */
+    disconnect(): void;
+    /**
+     * Mark the sync client as connected
+     * Called when WebSocket successfully connects (can happen independently of browser online/offline)
+     */
+    markConnected(): void;
+    /**
+     * Dispose and cleanup
+     */
+    dispose(): void;
+    /**
+     * LINEAR PATTERN: Notify TransactionQueue of incoming delta for sync ID threshold confirmation.
+     * Transactions are confirmed when any delta with id >= their lastSyncId threshold arrives.
+     * @param syncId - The sync ID of the received delta
+     */
+    onDeltaReceived(syncId: number): void;
+    /**
+     * LINEAR PATTERN: Cancel transactions for orphaned child entities
+     *
+     * Called by SyncedStore when a DELETE delta arrives for a parent entity.
+     * Cancels pending transactions for children that reference the deleted parent.
+     *
+     * @param childModelName - The child model type (e.g., 'SlideLayer')
+     * @param foreignKey - The FK property name (e.g., 'slideId')
+     * @param parentId - The deleted parent's ID
+     * @returns Number of transactions cancelled
+     */
+    cancelTransactionsByForeignKey(childModelName: string, foreignKey: string, parentId: string): number;
+    /**
+     * Wait for a transaction to be confirmed via delta echo (Linear pattern)
+     * Delegates to TransactionQueue which already handles timeouts
+     */
+    waitForDeltaConfirmation(transactionId: string): Promise<void>;
+    /**
+     * Force sync now - process pending mutations
+     */
+    syncNow(): Promise<void>;
+    /**
+     * Get sync statistics. Return type is inferred from the literal so
+     * the call site sees the actual shape — `connectionState` narrowed
+     * to its three states, `objectPoolStats` typed by `ObjectPool.getStats`.
+     */
+    getSyncStats(): {
+        connectionState: 'connected' | 'disconnected' | 'connecting';
+        pendingMutations: number;
+        objectPoolStats: ReturnType<ObjectPool['getStats']>;
+    };
+    /**
+     * Get pending transaction count from TransactionQueue
+     * Used by SyncedStore to compute hasUnsyncedChanges
+     */
+    getPendingTransactionCount(): number;
+    /**
+     * Subscribe to transaction events for sync status tracking
+     * Returns unsubscribe function
+     */
+    onTransactionEvent(event: 'created' | 'completed' | 'failed', callback: () => void): () => void;
+    /**
+     * Subscribe to mutation failures with the full payload. Mirrors the
+     * underlying TransactionQueue 'transaction:failed' shape so consumers
+     * can render typed UI (toast keyed by `AbloError.type`, route-level
+     * "this entity reverted" boundaries, telemetry).
+     *
+     * Distinct from `onTransactionEvent('failed', cb)`, which exists only
+     * for the legacy parameterless `pendingChanges` counter and intentionally
+     * drops the payload. The two coexist — keep the counter callback fast
+     * and the typed listener for user-visible surfaces.
+     */
+    onMutationFailure(listener: (payload: {
+        transaction: import('./transactions/TransactionQueue.js').Transaction;
+        error: Error;
+        permanent?: boolean;
+    }) => void): () => void;
+    /**
+     * Wait for the latest in-flight transaction for (modelName, modelId)
+     * to be confirmed by the server, or reject if it's rolled back.
+     * Resolves immediately when no transaction is in flight — see
+     * `TransactionQueue.confirmationFor` for the lookup contract.
+     *
+     * Distinct from `waitForDeltaConfirmation(transactionId)` which keys
+     * off a known tx id; this variant is for call sites that hold a
+     * Model reference but never see the underlying transaction.
+     */
+    waitForConfirmation(modelName: string, modelId: string): Promise<void>;
+    /**
+     * Get detailed debug info for the sync debug page
+     */
+    getDebugInfo(): {
+        connectionState: "connected" | "disconnected" | "connecting";
+        pendingMutationsCount: number;
+        transactionQueue: {
+            lastSeenSyncId: number;
+            awaitingDeltaCount: number;
+            awaitingDeltaTransactions: {
+                id: string;
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                modelName: string;
+                modelId: string;
+                syncIdNeeded: number | undefined;
+                createdAt: number;
+                age: number;
+            }[];
+            pendingTransactions: {
+                id: string;
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                modelName: string;
+                modelId: string;
+            }[];
+            executingTransactions: {
+                id: string;
+                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                modelName: string;
+                modelId: string;
+            }[];
+        };
+    };
+    unassignEntity(entityType: string, entityId: string): Promise<void>;
+    reassignEntity(entityType: string, entityId: string, assigneeType: string, assigneeId: string, id?: string): Promise<void>;
+    /**
+     * Apply a batch of delta results from Database to the ObjectPool.
+     * Owns: model creation, upsert, remove, archive, conflict resolution.
+     * Returns: nothing — ObjectPool is updated in place.
+     */
+    /**
+     * Mark a local transaction as optimistically applied. The matching
+     * server delta (when it arrives with the same `transactionId`) will
+     * be recognized as an echo and skip the pool mutation. Called
+     * automatically by `TransactionQueue` when a transaction is staged;
+     * exposed publicly so tests can drive the API directly.
+     */
+    markTransactionPending(transactionId: string): void;
+    /**
+     * Read echo-detection counters: hits, rollbacks, evictions, and the
+     * current pending-set size. Surfaced for production observability
+     * — a sustained `evictions > 0` rate or `rollbacks` spike is a
+     * health signal worth alerting on.
+     */
+    getEchoMetrics(): Readonly<OptimisticEchoMetrics>;
+    /**
+     * Package-internal accessor for the TransactionQueue. Used by
+     * `Ablo.commits.create()` to route raw multi-op envelopes through the
+     * same retry-on-reconnect lane as the Model proxy path, and by tests
+     * to exercise the queue ↔ markTransactionPending wiring on the real
+     * instance the SyncClient subscribes to. NOT re-exported to SDK
+     * consumers — `Ablo` itself is the public surface.
+     */
+    getTransactionQueue(): TransactionQueue;
+    applyDeltaBatchToPool(dbResults: Array<{
+        action: string;
+        modelName: string;
+        modelId: string;
+        data?: Record<string, unknown> | null;
+        /**
+         * Server-stamped transaction id, echoing the client's commit op
+         * id. Used by echo detection to recognize "this is the
+         * confirmation of a mutation I've already applied locally."
+         * Optional because system-emitted deltas (sync_group changes,
+         * schema-derived deltas, etc.) don't have a client transaction.
+         */
+        transactionId?: string;
+    }>, enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>): void;
+    /**
+     * Apply bootstrap data to the ObjectPool with ghost removal.
+     * Owns: model creation, batch upsert, ghost detection + removal.
+     */
+    applyBootstrapDataToPool(bootstrapData: {
+        models?: Record<string, unknown[]>;
+        failedModels?: string[];
+    }, protectedIds?: ReadonlySet<string>): {
+        added: number;
+        updated: number;
+        removed: number;
+        skipped: number;
+        healed: number;
+    };
+}
+export {};