@abloatai/ablo 0.3.0

package/dist/stores/SyncActionStore.js

@@ -0,0 +1,481 @@
+/**
+ * Linear Sync Engine - Sync Action Store
+ *
+ * Stores and manages sync actions received from the server.
+ * Critical for delta sync and maintaining sync state consistency.
+ */
+/**
+ * SyncActionStore - Manages sync actions (deltas)
+ *
+ * Features:
+ * - Stores sync actions by ID for replay
+ * - Tracks applied vs pending actions
+ * - Enables rewind/replay for conflict resolution
+ * - Maintains sync watermark
+ */
+export class SyncActionStore {
+    db;
+    storeName = 'sync_action_table';
+    lastAppliedSyncId = 0;
+    pendingActions = new Map();
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Initialize store (create if needed)
+     */
+    async initialize() {
+        // Store is created during database migration
+        // Load last applied sync ID from metadata
+        const metadata = await this.getMetadata();
+        if (metadata) {
+            this.lastAppliedSyncId = metadata.lastSyncId || 0;
+        }
+    }
+    /**
+     * Store a sync action
+     */
+    async storeSyncAction(action) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const request = store.put({
+                ...action,
+                storedAt: Date.now(),
+                applied: false,
+            });
+            tx.oncomplete = () => {
+                // Add to pending if not yet applied
+                if (action.id > this.lastAppliedSyncId) {
+                    this.pendingActions.set(action.id, action);
+                }
+                resolve();
+            };
+            tx.onerror = () => reject(tx.error);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Store multiple sync actions
+     */
+    async storeSyncActions(actions) {
+        if (actions.length === 0)
+            return;
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            let completed = 0;
+            const total = actions.length;
+            for (const action of actions) {
+                const request = store.put({
+                    ...action,
+                    storedAt: Date.now(),
+                    applied: false,
+                });
+                request.onsuccess = () => {
+                    completed++;
+                    if (completed === total) {
+                        // Add to pending
+                        for (const action of actions) {
+                            if (action.id > this.lastAppliedSyncId) {
+                                this.pendingActions.set(action.id, action);
+                            }
+                        }
+                    }
+                };
+                request.onerror = () => reject(request.error);
+            }
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    /**
+     * Get sync action by ID
+     */
+    async getSyncAction(id) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const request = store.get(id);
+            request.onsuccess = () => {
+                const data = request.result;
+                if (!data) {
+                    resolve(undefined);
+                    return;
+                }
+                const { storedAt, applied, ...action } = data;
+                resolve(action);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Get sync actions in range
+     */
+    async getSyncActionsInRange(startId, endId) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('syncId');
+            const range = IDBKeyRange.bound(startId, endId);
+            const request = index.getAll(range);
+            request.onsuccess = () => {
+                const allData = request.result;
+                const actions = allData.map(({ storedAt, applied, ...action }) => action);
+                resolve(actions);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Get pending sync actions (not yet applied)
+     */
+    async getPendingSyncActions() {
+        if (this.pendingActions.size === 0) {
+            return [];
+        }
+        // Return sorted by sync ID
+        const sorted = Array.from(this.pendingActions.values()).sort((a, b) => a.id - b.id);
+        return sorted;
+    }
+    /**
+     * Mark sync action as applied
+     */
+    async markAsApplied(syncId) {
+        return new Promise(async (resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const getRequest = store.get(syncId);
+            getRequest.onsuccess = () => {
+                const existing = getRequest.result;
+                if (existing) {
+                    existing.applied = true;
+                    existing.appliedAt = Date.now();
+                    const putRequest = store.put(existing);
+                    putRequest.onerror = () => reject(putRequest.error);
+                }
+            };
+            getRequest.onerror = () => reject(getRequest.error);
+            tx.oncomplete = async () => {
+                // Update tracking
+                if (syncId > this.lastAppliedSyncId) {
+                    this.lastAppliedSyncId = syncId;
+                }
+                // Remove from pending
+                this.pendingActions.delete(syncId);
+                // Update metadata
+                try {
+                    await this.updateLastSyncId(syncId);
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    /**
+     * Mark multiple actions as applied
+     */
+    async markManyAsApplied(syncIds) {
+        if (syncIds.length === 0)
+            return;
+        return new Promise(async (resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            let processed = 0;
+            const total = syncIds.length;
+            for (const syncId of syncIds) {
+                const getRequest = store.get(syncId);
+                getRequest.onsuccess = () => {
+                    const existing = getRequest.result;
+                    if (existing) {
+                        existing.applied = true;
+                        existing.appliedAt = Date.now();
+                        const putRequest = store.put(existing);
+                        putRequest.onsuccess = () => {
+                            processed++;
+                            // Remove from pending
+                            this.pendingActions.delete(syncId);
+                            if (processed === total) {
+                                // All processed, update last applied ID
+                                const maxId = Math.max(...syncIds);
+                                if (maxId > this.lastAppliedSyncId) {
+                                    this.lastAppliedSyncId = maxId;
+                                }
+                            }
+                        };
+                        putRequest.onerror = () => reject(putRequest.error);
+                    }
+                    else {
+                        processed++;
+                        this.pendingActions.delete(syncId);
+                    }
+                };
+                getRequest.onerror = () => reject(getRequest.error);
+            }
+            tx.oncomplete = async () => {
+                // Update metadata with the highest sync ID
+                const maxId = Math.max(...syncIds);
+                if (maxId > this.lastAppliedSyncId) {
+                    try {
+                        await this.updateLastSyncId(maxId);
+                        resolve();
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                }
+                else {
+                    resolve();
+                }
+            };
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    /**
+     * Get last applied sync ID
+     */
+    getLastAppliedSyncId() {
+        return this.lastAppliedSyncId;
+    }
+    /**
+     * Check if we have a gap in sync IDs
+     */
+    async hasGap(fromId, toId) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('syncId');
+            let currentId = fromId;
+            let hasGap = false;
+            const checkNext = () => {
+                if (currentId > toId) {
+                    resolve(hasGap);
+                    return;
+                }
+                const request = index.get(currentId);
+                request.onsuccess = () => {
+                    if (!request.result) {
+                        hasGap = true;
+                        resolve(true);
+                        return;
+                    }
+                    currentId++;
+                    checkNext();
+                };
+                request.onerror = () => reject(request.error);
+            };
+            checkNext();
+        });
+    }
+    /**
+     * Get missing sync IDs in range
+     */
+    async getMissingSyncIds(fromId, toId) {
+        return new Promise((resolve, reject) => {
+            const missing = [];
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('syncId');
+            let currentId = fromId;
+            const checkNext = () => {
+                if (currentId > toId) {
+                    resolve(missing);
+                    return;
+                }
+                const request = index.get(currentId);
+                request.onsuccess = () => {
+                    if (!request.result) {
+                        missing.push(currentId);
+                    }
+                    currentId++;
+                    checkNext();
+                };
+                request.onerror = () => reject(request.error);
+            };
+            checkNext();
+        });
+    }
+    /**
+     * Clean up old sync actions
+     */
+    async cleanup(keepDays = 7) {
+        return new Promise((resolve, reject) => {
+            const cutoff = Date.now() - keepDays * 24 * 60 * 60 * 1000;
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const request = store.openCursor();
+            let cleaned = 0;
+            request.onsuccess = (event) => {
+                const cursor = event.target.result;
+                if (cursor) {
+                    if (cursor.value.applied && cursor.value.appliedAt < cutoff) {
+                        const deleteRequest = cursor.delete();
+                        deleteRequest.onsuccess = () => {
+                            cleaned++;
+                            cursor.continue();
+                        };
+                        deleteRequest.onerror = () => reject(deleteRequest.error);
+                    }
+                    else {
+                        cursor.continue();
+                    }
+                }
+                else {
+                    // Cursor finished
+                    resolve(cleaned);
+                }
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Clear all sync actions
+     */
+    async clear() {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const request = store.clear();
+            tx.oncomplete = () => {
+                this.pendingActions.clear();
+                this.lastAppliedSyncId = 0;
+                resolve();
+            };
+            tx.onerror = () => reject(tx.error);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Get statistics
+     */
+    async getStats() {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const request = store.getAll();
+            request.onsuccess = () => {
+                const allActions = request.result;
+                const applied = allActions.filter((a) => a.applied).length;
+                const pending = allActions.filter((a) => !a.applied).length;
+                const timestamps = allActions
+                    .map((a) => a.storedAt)
+                    .filter(Boolean)
+                    .sort();
+                resolve({
+                    total: allActions.length,
+                    applied,
+                    pending,
+                    lastAppliedId: this.lastAppliedSyncId,
+                    oldestAction: timestamps.length > 0 ? new Date(timestamps[0]) : null,
+                    newestAction: timestamps.length > 0 ? new Date(timestamps[timestamps.length - 1]) : null,
+                });
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Update last sync ID in metadata
+     */
+    async updateLastSyncId(syncId) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction(['__meta'], 'readwrite');
+            const store = tx.objectStore('__meta');
+            const getRequest = store.get('metadata');
+            getRequest.onsuccess = () => {
+                const metadata = getRequest.result || {};
+                metadata.lastSyncId = syncId;
+                metadata.updatedAt = new Date();
+                const putRequest = store.put(metadata, 'metadata');
+                putRequest.onerror = () => reject(putRequest.error);
+            };
+            getRequest.onerror = () => reject(getRequest.error);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    /**
+     * Get metadata. Shape mirrors what's written by the database manager
+     * — currently only `lastSyncId` is consumed here (in `initialize`),
+     * so the return type is narrowed to that read surface. Returns
+     * `undefined` when the row hasn't been written yet (fresh DB).
+     */
+    async getMetadata() {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction(['__meta'], 'readonly');
+            const store = tx.objectStore('__meta');
+            const request = store.get('metadata');
+            request.onsuccess = () => {
+                const raw = request.result;
+                if (raw && typeof raw === 'object' && 'lastSyncId' in raw) {
+                    resolve(raw);
+                }
+                else {
+                    resolve(undefined);
+                }
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Rewind to a specific sync ID (for conflict resolution)
+     */
+    async rewindTo(syncId) {
+        return new Promise(async (resolve, reject) => {
+            // Get all actions after this sync ID
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('syncId');
+            const range = IDBKeyRange.lowerBound(syncId, false);
+            const request = index.getAll(range);
+            request.onsuccess = async () => {
+                const actionsToRewind = request.result;
+                // Mark them as not applied
+                const writeTx = this.db.transaction([this.storeName], 'readwrite');
+                const writeStore = writeTx.objectStore(this.storeName);
+                let processed = 0;
+                const total = actionsToRewind.length;
+                if (total === 0) {
+                    this.lastAppliedSyncId = syncId - 1;
+                    try {
+                        await this.updateLastSyncId(this.lastAppliedSyncId);
+                        resolve([]);
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                    return;
+                }
+                for (const action of actionsToRewind) {
+                    action.applied = false;
+                    delete action.appliedAt;
+                    const putRequest = writeStore.put(action);
+                    putRequest.onsuccess = () => {
+                        processed++;
+                        // Add back to pending
+                        this.pendingActions.set(action.id, action);
+                        if (processed === total) {
+                            // All processed
+                            this.lastAppliedSyncId = syncId - 1;
+                        }
+                    };
+                    putRequest.onerror = () => reject(putRequest.error);
+                }
+                writeTx.oncomplete = async () => {
+                    try {
+                        await this.updateLastSyncId(this.lastAppliedSyncId);
+                        const result = actionsToRewind.map(({ storedAt, applied, ...action }) => action);
+                        resolve(result);
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                };
+                writeTx.onerror = () => reject(writeTx.error);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+}

package/dist/sync/BootstrapHelper.d.ts

@@ -0,0 +1,127 @@
+/**
+ * BootstrapHelper - Fixed to always fetch fresh data
+ * Removed problematic caching that was serving stale data
+ */
+export interface BootstrapData {
+    type: 'full' | 'partial';
+    lastSyncId: number;
+    /**
+     * Model rows keyed by typename. Each row is opaque to the SDK at this
+     * boundary — the per-model shape is asserted by the consumer (sync
+     * engine reduce + IDB write) using the registered schema.
+     */
+    models?: {
+        [typename: string]: unknown[];
+    };
+    deltas?: ValidatedServerDelta[];
+    deltaCount?: number;
+    /** Model types whose server-side query failed (timeout, RLS error, etc.) */
+    failedModels?: string[];
+    timestamp: number;
+}
+export interface BootstrapFetchResult {
+    notModified: boolean;
+    data?: BootstrapData;
+    etag?: string | null;
+}
+export interface BootstrapOptions {
+    /**
+     * Full base URL of the sync server's HTTP API, **including the `/api`
+     * prefix**. The bootstrap endpoint is appended as `/sync/bootstrap`, so
+     * the final request hits `${baseUrl}/sync/bootstrap`.
+     *
+     * Example: `'http://localhost:8080/api'` → `http://localhost:8080/api/sync/bootstrap`
+     *
+     * Default: `'http://localhost:8080/api'`.
+     */
+    baseUrl?: string;
+    /**
+     * Private cache namespace for offline bootstrap fallback. Hosted SDK
+     * callers do not pass this; Ablo sets it after auth resolves the
+     * account scope.
+     */
+    cacheScope?: string | null;
+    /**
+     * @deprecated Use `cacheScope`. Kept so older self-hosted code that
+     * still constructs BootstrapHelper directly keeps its cache namespace.
+     */
+    organizationId?: string;
+    syncGroups?: string[];
+    maxRetries?: number;
+    retryDelay?: number;
+    /** Timeout for individual fetch requests in ms (default: 30000) */
+    fetchTimeout?: number;
+    /**
+     * Model names to request in bootstrap. When set, the server only returns
+     * these models — everything else is skipped. Derived from the schema's
+     * `load` strategy: only models with `load: 'instant'` (or unset, which
+     * defaults to instant) are included.
+     *
+     * When absent, the server returns all models (backward compatible with
+     * old clients that don't send a models param).
+     */
+    instantModels?: string[];
+}
+import { type ValidatedServerDelta } from './schemas.js';
+export declare class BootstrapHelper {
+    private options;
+    private abortController;
+    get baseUrl(): string;
+    constructor(options: BootstrapOptions);
+    /**
+     * Update the offline-cache namespace once auth has resolved the server-side
+     * account scope. This is intentionally not a public organizationId input.
+     */
+    setCacheScope(cacheScope: string): void;
+    setSyncGroups(syncGroups: readonly string[] | undefined): void;
+    setAuthToken(authToken: string | undefined): void;
+    /**
+     * Create a promise that rejects after a timeout
+     * Used to race against fetch requests that may hang indefinitely
+     */
+    private createTimeoutPromise;
+    /**
+     * Wrap a promise with a timeout - if the promise doesn't resolve within
+     * the timeout period, the AbortController is triggered and an error is thrown
+     */
+    private withTimeout;
+    /**
+     * Fetch bootstrap data from sync engine with partial bootstrap support
+     * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
+     * @returns Bootstrap data (either full snapshot or delta batch)
+     */
+    fetchBootstrap(lastSyncId?: number): Promise<BootstrapData>;
+    /**
+     * Fetch bootstrap with ETag, returning 304 hints
+     */
+    fetchBootstrapWithETag(): Promise<BootstrapFetchResult>;
+    /**
+     * Perform the actual fetch request with timeout protection
+     */
+    private performFetch;
+    /**
+     * Fetch a single entity by ID (on-demand self-healing).
+     * Returns `null` for 404 (entity deleted) — this is an expected state, not an error.
+     * Throws for unexpected HTTP errors (5xx, network failures).
+     */
+    fetchEntity(modelName: string, id: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Clear all cached bootstrap data
+     */
+    clearCache(): void;
+    private getBootstrapCacheKey;
+    private saveCachedBootstrap;
+    private loadCachedBootstrap;
+    /**
+     * Abort ongoing fetch request
+     */
+    abort(): void;
+    /**
+     * Helper to delay execution
+     */
+    private delay;
+    /**
+     * Get health status of sync engine
+     */
+    checkHealth(): Promise<boolean>;
+}