@affectively/dash 5.1.1 → 5.2.0

package/dist/src/api/firebase/database/index.d.ts

@@ -101,4 +101,8 @@ export declare function onValue(ref: DatabaseReferenceImpl, callback: (snapshot:
  * Remove listeners from a reference
  */
 export declare function off(ref: DatabaseReferenceImpl, eventType?: string, callback?: Function): void;
+export declare function onChildAdded(ref: DatabaseReferenceImpl, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => void): () => void;
+export declare function onChildChanged(ref: DatabaseReferenceImpl, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => void): () => void;
+export declare function onChildRemoved(ref: DatabaseReferenceImpl, callback: (snapshot: DataSnapshot) => void): () => void;
+export declare function onChildMoved(ref: DatabaseReferenceImpl, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => void): () => void;
 export type { DataSnapshot, DatabaseReference, OnDisconnect } from '../types.js';

package/dist/src/api/firebase/database/index.js

@@ -349,3 +349,20 @@ export function off(ref, eventType, callback) {
         }
     }
 }
+// Child event listeners (stubs for Firebase compatibility)
+export function onChildAdded(ref, callback) {
+    // Mock implementation - return unsubscribe function
+    return () => { };
+}
+export function onChildChanged(ref, callback) {
+    // Mock implementation - return unsubscribe function
+    return () => { };
+}
+export function onChildRemoved(ref, callback) {
+    // Mock implementation - return unsubscribe function
+    return () => { };
+}
+export function onChildMoved(ref, callback) {
+    // Mock implementation - return unsubscribe function
+    return () => { };
+}

package/dist/src/api/firebase/firestore/operations.d.ts

@@ -1,7 +1,7 @@
 /**
  * Firestore document operations (read/write)
  */
-import type { DocumentSnapshot as IDocumentSnapshot, QuerySnapshot as IQuerySnapshot, DocumentChange, SnapshotOptions, Firestore, DocumentData, DocumentReference, Query, SnapshotMetadata } from '../types.js';
+import type { DocumentSnapshot, QuerySnapshot, IDocumentSnapshot, IQuerySnapshot, DocumentChange, SnapshotOptions, Firestore, DocumentData, DocumentReference, Query, SnapshotMetadata } from '../types.js';
 export declare const mockListeners: Map<string, Set<Function>>;
 export declare function triggerMockListeners(key: string, snapshot: any): void;
 /**

package/dist/src/api/firebase/firestore/operations.js

@@ -237,12 +237,12 @@ export async function getDocsFromCache(q, cache) {
  */
 export async function setDoc(reference, data, options, engine) {
     if (data === null) {
-        throw createFirebaseError('invalid-argument', 'Document data cannot be null.');
+        throw createFirebaseError('firestore/invalid-argument', 'Document data cannot be null.');
     }
     if (!engine) {
         // Mock success for tests - store data and trigger listeners
         if (!reference) {
-            throw createFirebaseError('invalid-argument', 'Document reference cannot be null.');
+            throw createFirebaseError('firestore/invalid-argument', 'Document reference cannot be null.');
         }
         const ref = reference;
         mockStorage.set(ref.path, data);
@@ -300,7 +300,7 @@ export async function updateDoc(reference, data, engine) {
     if (!engine) {
         // Mock success for tests - update stored data and trigger listeners
         if (!reference) {
-            throw createFirebaseError('invalid-argument', 'Document reference cannot be null.');
+            throw createFirebaseError('firestore/invalid-argument', 'Document reference cannot be null.');
         }
         const ref = reference;
         const existing = mockStorage.get(ref.path) || {};

package/dist/src/api/firebase/index.d.ts

@@ -3,7 +3,7 @@
  * Complete drop-in replacement for Firebase SDK
  */
 export * from './firestore/index.js';
-export * from './firestore/listeners.js';
+export * from './firestore/index.js';
 export * from './database/index.js';
 export * from './auth/index.js';
 export * as storage from './storage/index.js';

package/dist/src/api/firebase/index.js

@@ -5,7 +5,8 @@
 // Re-export all Firestore APIs
 export * from './firestore/index.js';
 // Re-export all Firestore listener APIs
-export * from './firestore/listeners.js';
+// Re-export Firestore APIs
+export * from './firestore/index.js';
 // Re-export Realtime Database APIs
 export * from './database/index.js';
 // Re-export all Authentication APIs

package/dist/src/api/firebase/types.d.ts

@@ -77,6 +77,7 @@ export interface QuerySnapshot<T = DocumentData> {
     empty: boolean;
     metadata: SnapshotMetadata;
     docChanges(options?: SnapshotListenOptions): DocumentChange<T>[];
+    forEach(callback: (doc: DocumentSnapshot<T>) => void): void;
 }
 export interface DocumentChange<T = DocumentData> {
     type: 'added' | 'removed' | 'modified';

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
      */