@affectively/dash 5.1.0 → 5.2.0

package/dist/src/engine/sqlite.d.ts

@@ -1,12 +1,63 @@
 import { LensEngine } from '../schema/lens.js';
+/**
+ * Cloud sync configuration - enables automatic D1/R2 sync
+ *
+ * Cloud sync is ON BY DEFAULT when:
+ * - Running in a Cloudflare environment (detected via env vars)
+ * - A sync endpoint is available
+ *
+ * It gracefully degrades if sync fails - local data still works.
+ */
+export interface CloudConfig {
+    /** Base URL for the sync endpoint (e.g., 'https://api.example.com'). Auto-detected from env if not provided. */
+    baseUrl?: string;
+    /** Auth token getter - called before each sync */
+    getAuthToken?: () => Promise<string | null>;
+    /** Sync interval in ms (default: 30000 = 30s). Set to 0 to disable auto-sync. */
+    syncInterval?: number;
+    /** Tables to exclude from sync (internal tables are always excluded) */
+    excludeTables?: string[];
+    /** Callback when sync completes */
+    onSyncComplete?: (result: CloudSyncResult) => void;
+    /** Callback when sync fails */
+    onSyncError?: (error: Error) => void;
+    /** Explicitly disable cloud sync (default: false - sync is enabled if endpoint available) */
+    disabled?: boolean;
+}
+export interface CloudSyncResult {
+    pushed: number;
+    pulled: number;
+    errors: string[];
+    timestamp: number;
+}
 export declare class DashEngine {
     private db;
     private readyPromise;
     private listeners;
     lens: LensEngine;
     currentSchemaVersion: number;
+    private cloudConfig;
+    private cloudSyncTimer;
+    private isCloudSyncing;
+    private lastCloudSyncTime;
+    private cloudSyncEnabled;
+    private syncedTables;
+    private readonly INTERNAL_TABLES;
     constructor();
     private init;
+    /**
+     * Try to auto-enable cloud sync from environment
+     * Cloud sync is ON BY DEFAULT when a sync endpoint is detected
+     */
+    private tryAutoEnableCloudSync;
+    /**
+     * Detect sync endpoint from environment variables
+     */
+    private detectSyncEndpoint;
+    /**
+     * Get default auth token from common auth patterns
+     */
+    private getDefaultAuthToken;
     private initializeSchema;
     ready(): Promise<void>;
     private tableListeners;
@@ -30,6 +81,84 @@ export declare class DashEngine {
         maxZ: number;
     }): Promise<any[]>;
     close(): void;
+    /**
+     * Enable cloud sync - changes automatically sync to D1/R2
+     * Just call this once with your config, and sync happens magically.
+     *
+     * Cloud sync is ON BY DEFAULT when running in a Cloudflare environment.
+     * Call this to customize the config or explicitly enable/disable.
+     *
+     * @example
+     * ```ts
+     * await dash.ready();
+     * // Option 1: Use auto-detected endpoint (default)
+     * // Cloud sync is already enabled if DASH_SYNC_URL env var is set
+     *
+     * // Option 2: Explicit config
+     * dash.enableCloudSync({
+     *   baseUrl: 'https://api.example.com',
+     *   getAuthToken: async () => auth.token,
+     * });
+     *
+     * // Option 3: Disable cloud sync
+     * dash.enableCloudSync({ disabled: true });
+     * ```
+     */
+    enableCloudSync(config?: CloudConfig): void;
+    /**
+     * Initialize cloud sync schema (queue and metadata tables)
+     */
+    private initializeCloudSyncSchema;
+    /**
+     * Set up sync triggers for all user tables
+     */
+    private setupAllTableTriggers;
+    /**
+     * Check if a table should be synced
+     */
+    private shouldSyncTable;
+    /**
+     * Set up sync triggers for a specific table
+     */
+    private setupTableSyncTriggers;
+    /**
+     * Build json_object() arguments for a table's columns
+     */
+    private buildJsonObjectArgs;
+    /**
+     * Start automatic cloud sync
+     */
+    private startCloudSync;
+    /**
+     * Stop automatic cloud sync
+     */
+    stopCloudSync(): void;
+    /**
+     * Perform a sync to cloud (D1/R2)
+     */
+    syncToCloud(): Promise<CloudSyncResult>;
+    /**
+     * Apply a single server change locally
+     */
+    private applyServerChange;
+    /**
+     * Force a full cloud sync (reset last sync time)
+     */
+    forceCloudSync(): Promise<CloudSyncResult>;
+    /**
+     * Get cloud sync status
+     */
+    getCloudSyncStatus(): {
+        enabled: boolean;
+        syncing: boolean;
+        lastSyncTime: number;
+        pendingChanges: number;
+        syncedTables: string[];
+    };
+    /**
+     * Disable cloud sync
+     */
+    disableCloudSync(): void;
     /**
      * Get information about all tables in the database
      */