@affectively/dash 5.3.1 → 5.4.0

package/dist/src/sync/aeon/presence-adapter.js

@@ -0,0 +1,157 @@
+/**
+ * Presence Adapter for Dash
+ *
+ * Bridges Yjs awareness protocol with Aeon's AgentPresenceManager.
+ * Provides rich presence features: cursor tracking, active sections, roles.
+ */
+import { AgentPresenceManager, } from '@affectively/aeon';
+/**
+ * Adapter that syncs Yjs awareness with Aeon presence
+ */
+export class DashPresenceAdapter {
+    aeonPresence;
+    yjsAwareness;
+    localAgentId;
+    roomId;
+    constructor(roomId, awareness) {
+        this.roomId = roomId;
+        this.yjsAwareness = awareness;
+        this.localAgentId = `agent-${awareness.clientID}`;
+        this.aeonPresence = new AgentPresenceManager(roomId);
+        // Register local agent
+        this.aeonPresence.agentJoined(this.localAgentId, `User ${awareness.clientID}`, 'user');
+        // Bidirectional sync setup
+        this.setupYjsToAeonSync();
+        this.setupAeonToYjsSync();
+    }
+    /**
+     * Sync Yjs awareness updates to Aeon presence
+     */
+    setupYjsToAeonSync() {
+        this.yjsAwareness.on('update', ({ added, updated, removed }) => {
+            const states = this.yjsAwareness.getStates();
+            // Handle added/updated
+            for (const clientId of [...added, ...updated]) {
+                const state = states.get(clientId);
+                if (state) {
+                    const agentId = `agent-${clientId}`;
+                    if (added.includes(clientId)) {
+                        this.aeonPresence.agentJoined(agentId, state.user?.name || `User ${clientId}`, state.user?.role || 'user', state.metadata);
+                    }
+                    // Sync cursor and section if present
+                    if (state.cursor) {
+                        this.aeonPresence.updateCursor(agentId, state.cursor.x ?? 0, state.cursor.y ?? 0, state.cursor.path ?? '');
+                    }
+                    if (state.activeSection) {
+                        this.aeonPresence.updateActiveSection(agentId, state.activeSection);
+                    }
+                    // Heartbeat to keep presence alive
+                    this.aeonPresence.heartbeat(agentId);
+                }
+            }
+            // Handle removed
+            for (const clientId of removed) {
+                this.aeonPresence.agentLeft(`agent-${clientId}`);
+            }
+        });
+    }
+    /**
+     * Sync Aeon presence updates back to Yjs awareness
+     */
+    setupAeonToYjsSync() {
+        // When local presence updates via Aeon API, reflect to Yjs
+        this.aeonPresence.on('cursor_updated', ({ agentId, cursorPosition }) => {
+            if (agentId === this.localAgentId) {
+                this.yjsAwareness.setLocalStateField('cursor', cursorPosition);
+            }
+        });
+        this.aeonPresence.on('section_updated', ({ agentId, activeSection }) => {
+            if (agentId === this.localAgentId) {
+                this.yjsAwareness.setLocalStateField('activeSection', activeSection);
+            }
+        });
+    }
+    // ============================================
+    // Rich Presence API
+    // ============================================
+    /**
+     * Update local cursor position
+     */
+    updateCursor(x, y, path) {
+        this.aeonPresence.updateCursor(this.localAgentId, x, y, path);
+    }
+    /**
+     * Update local active section
+     */
+    updateActiveSection(section) {
+        this.aeonPresence.updateActiveSection(this.localAgentId, section);
+    }
+    /**
+     * Update local user info
+     */
+    updateUserInfo(name, role = 'user') {
+        this.aeonPresence.updatePresence(this.localAgentId, {
+            agentId: this.localAgentId,
+            name,
+            role,
+            status: 'online',
+        });
+        // Also sync to Yjs awareness
+        this.yjsAwareness.setLocalStateField('user', { name, role });
+    }
+    /**
+     * Get all online agents
+     */
+    getOnlineAgents() {
+        return this.aeonPresence.getOnlineAgents();
+    }
+    /**
+     * Get all agents (including offline)
+     */
+    getAllAgents() {
+        return this.aeonPresence.getAllAgents();
+    }
+    /**
+     * Get presence for specific agent
+     */
+    getPresence(agentId) {
+        return this.aeonPresence.getPresence(agentId);
+    }
+    /**
+     * Get agents in a specific section
+     */
+    getAgentsInSection(section) {
+        return this.aeonPresence.getInSection(section);
+    }
+    /**
+     * Get presence statistics
+     */
+    getStats() {
+        return this.aeonPresence.getPresenceStats();
+    }
+    /**
+     * Get local agent ID
+     */
+    getLocalAgentId() {
+        return this.localAgentId;
+    }
+    /**
+     * Subscribe to presence events
+     */
+    on(event, handler) {
+        this.aeonPresence.on(event, handler);
+    }
+    /**
+     * Unsubscribe from presence events
+     */
+    off(event, handler) {
+        this.aeonPresence.off(event, handler);
+    }
+    /**
+     * Cleanup
+     */
+    destroy() {
+        this.aeonPresence.agentLeft(this.localAgentId);
+        this.aeonPresence.destroy();
+    }
+}

package/dist/src/sync/aeon/schema-adapter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Schema Adapter for Dash
+ *
+ * Bridges Aeon's SchemaVersionManager with Dash's LensEngine.
+ * Provides migration tracking, version compatibility checks, and audit trails.
+ */
+import { type SchemaVersion, type Migration, type MigrationResult } from '@affectively/aeon';
+import { LensEngine, type LensOp } from '../../schema/lens.js';
+/**
+ * Adapter that bridges Aeon versioning with Dash's Lens system
+ */
+export declare class DashSchemaAdapter {
+    private versionManager;
+    private migrationEngine;
+    private migrationTracker;
+    private lensEngine;
+    constructor(lensEngine: LensEngine);
+    /**
+     * Register a schema version with associated Lens operations
+     */
+    registerVersion(version: string, description: string, lensOps?: LensOp[], breaking?: boolean): void;
+    /**
+     * Register a migration for a version upgrade
+     */
+    registerMigration(id: string, fromVersion: string, toVersion: string, migrate: (data: unknown) => unknown, rollback?: (data: unknown) => unknown): void;
+    /**
+     * Execute a migration on data
+     */
+    executeMigration(migrationId: string, data: unknown): Promise<MigrationResult>;
+    /**
+     * Rollback a migration
+     */
+    rollbackMigration(migrationId: string, data: unknown): Promise<MigrationResult>;
+    /**
+     * Migrate data using Lens transformations
+     */
+    migrateWithLens(data: Record<string, unknown>, fromVersion: number, toVersion: number): Record<string, unknown>;
+    /**
+     * Get current version
+     */
+    getCurrentVersion(): SchemaVersion;
+    /**
+     * Get a specific version by string
+     */
+    getVersion(version: string): SchemaVersion | undefined;
+    /**
+     * Get migration by ID
+     */
+    getMigration(id: string): Migration | undefined;
+    /**
+     * Check if migration is needed
+     */
+    needsMigration(fromVersion: string, toVersion: string): boolean;
+    /**
+     * Get migration path between versions
+     */
+    getMigrationPath(fromVersion: string, toVersion: string): SchemaVersion[];
+    /**
+     * Get pending migrations
+     */
+    getPendingMigrations(): Migration[];
+    /**
+     * Get migration statistics
+     */
+    getStatistics(): {
+        engine: {
+            totalExecuted: number;
+            successful: number;
+            failed: number;
+            successRate: number;
+            totalDurationMs: number;
+            averageDurationMs: number;
+            totalAffected: number;
+        };
+        tracker: {
+            total: number;
+            applied: number;
+            failed: number;
+            pending: number;
+            rolledBack: number;
+            successRate: number;
+            totalDurationMs: number;
+            averageDurationMs: number;
+            totalItemsAffected: number;
+        };
+    };
+    /**
+     * Format version for display
+     */
+    formatVersion(version: SchemaVersion): string;
+}
+/**
+ * Create a schema adapter from an existing LensEngine
+ */
+export declare function createSchemaAdapter(lensEngine: LensEngine): DashSchemaAdapter;

package/dist/src/sync/aeon/schema-adapter.js

@@ -0,0 +1,163 @@
+/**
+ * Schema Adapter for Dash
+ *
+ * Bridges Aeon's SchemaVersionManager with Dash's LensEngine.
+ * Provides migration tracking, version compatibility checks, and audit trails.
+ */
+import { SchemaVersionManager, MigrationEngine, MigrationTracker, } from '@affectively/aeon';
+/**
+ * Adapter that bridges Aeon versioning with Dash's Lens system
+ */
+export class DashSchemaAdapter {
+    versionManager;
+    migrationEngine;
+    migrationTracker;
+    lensEngine;
+    constructor(lensEngine) {
+        this.versionManager = new SchemaVersionManager();
+        this.migrationEngine = new MigrationEngine();
+        this.migrationTracker = new MigrationTracker();
+        this.lensEngine = lensEngine;
+    }
+    /**
+     * Register a schema version with associated Lens operations
+     */
+    registerVersion(version, description, lensOps, breaking = false) {
+        const [major, minor, patch] = version.split('.').map(Number);
+        // Register with Aeon
+        this.versionManager.registerVersion({
+            major,
+            minor,
+            patch,
+            timestamp: new Date().toISOString(),
+            description,
+            breaking,
+        });
+        // Register Lens if provided
+        if (lensOps && major > 1) {
+            this.lensEngine.registerLens(major - 1, major, lensOps);
+        }
+    }
+    /**
+     * Register a migration for a version upgrade
+     */
+    registerMigration(id, fromVersion, toVersion, migrate, rollback) {
+        const migration = {
+            id,
+            name: `${fromVersion} -> ${toVersion}`,
+            version: toVersion,
+            description: `Migrate from ${fromVersion} to ${toVersion}`,
+            timestamp: new Date().toISOString(),
+            up: migrate,
+            down: rollback,
+        };
+        this.migrationEngine.registerMigration(migration);
+    }
+    /**
+     * Execute a migration on data
+     */
+    async executeMigration(migrationId, data) {
+        const result = await this.migrationEngine.executeMigration(migrationId, data);
+        // Track the migration
+        const record = {
+            id: `record-${Date.now()}`,
+            migrationId,
+            timestamp: new Date().toISOString(),
+            version: result.migrationId,
+            direction: 'up',
+            status: result.success ? 'applied' : 'failed',
+            duration: result.duration,
+            itemsAffected: result.itemsAffected,
+            errorMessage: result.errors.length > 0 ? result.errors.join(', ') : undefined,
+            appliedBy: 'dash-schema-adapter',
+        };
+        this.migrationTracker.recordMigration(record);
+        return result;
+    }
+    /**
+     * Rollback a migration
+     */
+    async rollbackMigration(migrationId, data) {
+        const result = await this.migrationEngine.rollbackMigration(migrationId, data);
+        // Track the rollback
+        const record = {
+            id: `record-${Date.now()}`,
+            migrationId,
+            timestamp: new Date().toISOString(),
+            version: result.migrationId,
+            direction: 'down',
+            status: result.success ? 'rolled-back' : 'failed',
+            duration: result.duration,
+            itemsAffected: result.itemsAffected,
+            errorMessage: result.errors.length > 0 ? result.errors.join(', ') : undefined,
+            appliedBy: 'dash-schema-adapter',
+        };
+        this.migrationTracker.recordMigration(record);
+        return result;
+    }
+    /**
+     * Migrate data using Lens transformations
+     */
+    migrateWithLens(data, fromVersion, toVersion) {
+        return this.lensEngine.migrate(data, fromVersion, toVersion);
+    }
+    /**
+     * Get current version
+     */
+    getCurrentVersion() {
+        return this.versionManager.getCurrentVersion();
+    }
+    /**
+     * Get a specific version by string
+     */
+    getVersion(version) {
+        return this.versionManager.getVersion(version);
+    }
+    /**
+     * Get migration by ID
+     */
+    getMigration(id) {
+        return this.migrationEngine.getMigration(id);
+    }
+    /**
+     * Check if migration is needed
+     */
+    needsMigration(fromVersion, toVersion) {
+        return this.versionManager.canMigrate(fromVersion, toVersion);
+    }
+    /**
+     * Get migration path between versions
+     */
+    getMigrationPath(fromVersion, toVersion) {
+        const from = this.versionManager.parseVersion(fromVersion);
+        const to = this.versionManager.parseVersion(toVersion);
+        return this.versionManager.getMigrationPath(from, to);
+    }
+    /**
+     * Get pending migrations
+     */
+    getPendingMigrations() {
+        return this.migrationEngine.getPendingMigrations();
+    }
+    /**
+     * Get migration statistics
+     */
+    getStatistics() {
+        return {
+            engine: this.migrationEngine.getStatistics(),
+            tracker: this.migrationTracker.getStatistics(),
+        };
+    }
+    /**
+     * Format version for display
+     */
+    formatVersion(version) {
+        return `${version.major}.${version.minor}.${version.patch}`;
+    }
+}
+/**
+ * Create a schema adapter from an existing LensEngine
+ */
+export function createSchemaAdapter(lensEngine) {
+    return new DashSchemaAdapter(lensEngine);
+}

package/dist/src/sync/backup.d.ts

@@ -0,0 +1,12 @@
+import * as Y from 'yjs';
+export interface CloudStorageAdapter {
+    upload(name: string, data: Uint8Array): Promise<void>;
+    download(name: string): Promise<Uint8Array | null>;
+}
+export declare function generateKey(): Promise<CryptoKey>;
+export declare function exportKey(key: CryptoKey): Promise<string>;
+export declare function importKey(jwkString: string): Promise<CryptoKey>;
+export declare function encrypt(data: Uint8Array, key: CryptoKey): Promise<Uint8Array>;
+export declare function decrypt(data: Uint8Array, key: CryptoKey): Promise<Uint8Array>;
+export declare function backup(roomName: string, doc: Y.Doc, key: CryptoKey, adapter: CloudStorageAdapter): Promise<void>;
+export declare function restore(roomName: string, doc: Y.Doc, key: CryptoKey, adapter: CloudStorageAdapter): Promise<void>;

package/dist/src/sync/backup.js

@@ -0,0 +1,44 @@
+import * as Y from 'yjs';
+// AES-GCM Encryption
+export async function generateKey() {
+    return await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+}
+export async function exportKey(key) {
+    const exported = await crypto.subtle.exportKey('jwk', key);
+    return JSON.stringify(exported);
+}
+export async function importKey(jwkString) {
+    const jwk = JSON.parse(jwkString);
+    return await crypto.subtle.importKey('jwk', jwk, { name: 'AES-GCM' }, true, ['encrypt', 'decrypt']);
+}
+export async function encrypt(data, key) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    // Ensure we have a proper ArrayBuffer (not SharedArrayBuffer) by creating a copy
+    const dataCopy = new Uint8Array(data);
+    const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, dataCopy);
+    // Combine IV and Encrypted Data
+    const combined = new Uint8Array(iv.length + encrypted.byteLength);
+    combined.set(iv);
+    combined.set(new Uint8Array(encrypted), iv.length);
+    return combined;
+}
+export async function decrypt(data, key) {
+    const iv = data.slice(0, 12);
+    const ciphertext = data.slice(12);
+    const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+    return new Uint8Array(decrypted);
+}
+export async function backup(roomName, doc, key, adapter) {
+    const state = Y.encodeStateAsUpdate(doc);
+    const encrypted = await encrypt(state, key);
+    await adapter.upload(`backup_${roomName}`, encrypted);
+}
+export async function restore(roomName, doc, key, adapter) {
+    const encrypted = await adapter.download(`backup_${roomName}`);
+    if (!encrypted) {
+        console.warn(`[CloudBackup] No backup found for room ${roomName}`);
+        return;
+    }
+    const state = await decrypt(encrypted, key);
+    Y.applyUpdate(doc, state);
+}

package/dist/src/sync/connection.d.ts

@@ -0,0 +1,20 @@
+import * as Y from 'yjs';
+export interface SyncConnectionConfig {
+    type?: 'webrtc' | 'webtransport';
+    roomName: string;
+    doc: Y.Doc;
+    signalingServers?: string[];
+    password?: string | null;
+    url?: string;
+    awareness?: any;
+}
+export declare class SyncConnection {
+    private provider;
+    roomName: string;
+    constructor(config: SyncConnectionConfig);
+    disconnect(): void;
+    get awareness(): any;
+}
+export declare class WebRTCConnection extends SyncConnection {
+    constructor(config: Omit<SyncConnectionConfig, 'type'>);
+}

package/dist/src/sync/connection.js

@@ -0,0 +1,50 @@
+import { WebrtcProvider } from 'y-webrtc';
+import { HybridProvider } from './hybrid-provider.js';
+export class SyncConnection {
+    provider;
+    roomName;
+    constructor(config) {
+        this.roomName = config.roomName;
+        const type = config.type || 'webrtc'; // Default to WebRTC for backward compatibility
+        if (type === 'webtransport') {
+            if (!config.url) {
+                throw new Error('WebTransport requires a "url" in config');
+            }
+            this.provider = new HybridProvider(config.url, config.roomName, config.doc, { awareness: config.awareness });
+        }
+        else {
+            // Default signaling servers if none provided
+            // Note: In production, users should host their own signaling servers
+            const signaling = config.signalingServers || [
+                'wss://signaling.yjs.dev',
+                'wss://y-webrtc-signaling-eu.herokuapp.com',
+                'wss://y-webrtc-signaling-us.herokuapp.com'
+            ];
+            this.provider = new WebrtcProvider(config.roomName, config.doc, {
+                signaling,
+                password: config.password || undefined,
+                awareness: config.awareness
+            });
+        }
+        this.provider.on('synced', (event) => {
+            console.log(`[${type === 'webtransport' ? 'WebTransport' : 'WebRTC'}] Room: ${this.roomName}, Synced: ${event.synced}`);
+        });
+        // Relay status from provider if available
+        this.provider.on('status', (event) => {
+            // loose typing for event forwarding
+            console.log(`[${type}] Status update:`, event);
+        });
+    }
+    disconnect() {
+        this.provider.destroy();
+    }
+    get awareness() {
+        return this.provider.awareness;
+    }
+}
+// Backward compatibility alias
+export class WebRTCConnection extends SyncConnection {
+    constructor(config) {
+        super({ ...config, type: 'webrtc' });
+    }
+}

package/dist/src/sync/d1-provider.d.ts

@@ -0,0 +1,103 @@
+/**
+ * D1 Sync Provider
+ *
+ * Provides HTTP-based sync between local Dash SQLite (WASM) and Cloudflare D1.
+ *
+ * Unlike the HybridProvider which syncs Yjs CRDT documents over WebSocket,
+ * this provider syncs regular SQL tables via HTTP REST API.
+ *
+ * Architecture:
+ * - Local changes are tracked in a sync_queue table
+ * - Sync runs periodically or on-demand
+ * - Conflicts are resolved using last-write-wins with _lastModified timestamps
+ *
+ * Security:
+ * - Table/column names are validated against allowed patterns
+ * - All user data uses parameterized queries
+ */
+export interface D1SyncConfig {
+    /** Base URL for the sync endpoint (e.g., 'https://example.com/api') */
+    baseUrl: string;
+    /** Tables to sync (e.g., ['reflections', 'users']) */
+    tables: 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;
+    /** Callback when sync completes */
+    onSyncComplete?: (result: SyncResult) => void;
+    /** Callback when sync fails */
+    onSyncError?: (error: Error) => void;
+}
+export interface SyncResult {
+    pushed: number;
+    pulled: number;
+    errors: string[];
+    timestamp: number;
+}
+export interface SyncQueueEntry {
+    id: number;
+    table_name: string;
+    row_id: string;
+    operation: 'create' | 'update' | 'delete';
+    data: string | null;
+    created_at: number;
+    synced: number;
+}
+export declare class D1SyncProvider {
+    private config;
+    private syncTimer;
+    private isSyncing;
+    private lastSyncTime;
+    private initialized;
+    constructor(config: D1SyncConfig);
+    /**
+     * Initialize the sync provider - must be called before syncing
+     */
+    initialize(): Promise<void>;
+    /**
+     * Set up SQLite triggers to track changes for a table
+     * Uses validated identifiers to prevent SQL injection
+     */
+    private setupTableTriggers;
+    /**
+     * Start automatic sync at the configured interval
+     */
+    startAutoSync(): void;
+    /**
+     * Stop automatic sync
+     */
+    stopAutoSync(): void;
+    /**
+     * Perform a sync operation
+     */
+    sync(): Promise<SyncResult>;
+    /**
+     * Apply changes received from the server with Last-Write-Wins (LWW) conflict resolution
+     * Server changes only win if their _lastModified is newer than local
+     */
+    private applyServerChanges;
+    /**
+     * Queue a change manually (for cases where triggers can't be used)
+     */
+    queueChange(tableName: string, rowId: string, operation: 'create' | 'update' | 'delete', data?: any): void;
+    /**
+     * Get the current sync status
+     */
+    getStatus(): {
+        initialized: boolean;
+        syncing: boolean;
+        lastSyncTime: number;
+        pendingChanges: number;
+    };
+    /**
+     * Force a full sync by resetting last sync time
+     */
+    forceFullSync(): Promise<SyncResult>;
+    /**
+     * Destroy the provider and clean up
+     */
+    destroy(): void;
+}
+export declare function getD1SyncProvider(config?: D1SyncConfig): D1SyncProvider;
+export declare function resetD1SyncProvider(): void;