@synclib-io/sync 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,978 @@
+import { Change, SynclibDatabase } from '@synclib-io/core';
+
+/**
+ * Base interface for all sync protocol messages
+ */
+interface SyncMessage {
+    type: string;
+    toMap(): Record<string, any>;
+}
+/**
+ * Initial handshake message from client to server
+ */
+interface HelloMessage extends SyncMessage {
+    type: 'hello';
+    client_id: string;
+    last_seqnum?: number;
+    schema_version: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Represents a single database change to sync
+ */
+interface ChangeMessage extends SyncMessage {
+    type: 'change';
+    table: string;
+    operation: 'insert' | 'update' | 'delete';
+    row_id: string;
+    data?: Record<string, any>;
+    seqnum?: number;
+    timestamp?: Date;
+}
+/**
+ * Batch of changes (for efficient syncing)
+ */
+interface ChangesBatchMessage extends SyncMessage {
+    type: 'changes_batch';
+    changes: ChangeMessage[];
+    from_seqnum?: number;
+    to_seqnum?: number;
+}
+/**
+ * Acknowledgment that changes were received and processed
+ */
+interface AckMessage extends SyncMessage {
+    type: 'ack';
+    seqnum: number;
+    success: boolean;
+    error?: string;
+    /** Server-assigned seqnum for the row (set by Postgres trigger).
+     * Client should update the local row's seqnum column with this value. */
+    server_seqnum?: number;
+    /** Server-computed row_hash (set by Postgres trigger).
+     * Client should store this value locally — never compute row_hash on client. */
+    row_hash?: string;
+}
+/**
+ * Request for changes from server
+ */
+interface RequestChangesMessage extends SyncMessage {
+    type: 'request_changes';
+    since_seqnum?: number;
+    limit?: number;
+    table?: string;
+}
+/**
+ * Error message
+ */
+interface ErrorMessage extends SyncMessage {
+    type: 'error';
+    code: string;
+    message: string;
+    details?: Record<string, any>;
+}
+/**
+ * Phoenix channel reply message (for hello response)
+ */
+interface PhoenixReplyMessage extends SyncMessage {
+    type: 'phx_reply';
+    status: string;
+    response: Record<string, any>;
+}
+/**
+ * Schema migration confirmation message
+ */
+interface SchemaConfirmMessage extends SyncMessage {
+    type: 'schema_migrated';
+    version: number;
+}
+/**
+ * Snapshot batch message (streaming table data)
+ */
+interface SnapshotBatchMessage extends SyncMessage {
+    type: 'snapshot_batch';
+    stream_id: string;
+    table: string;
+    rows: Array<Record<string, any>>;
+}
+/**
+ * Snapshot complete message (marks end of snapshot stream)
+ */
+interface SnapshotCompleteMessage extends SyncMessage {
+    type: 'snapshot_complete';
+    stream_id: string;
+    channel_id: string;
+}
+/**
+ * Job update message (from ECS tasks via webhook)
+ */
+interface JobUpdateMessage extends SyncMessage {
+    type: 'job_update';
+    current_step: number;
+    total_steps: number;
+    step_type: string;
+    job_id: string;
+    user_id: string;
+    phoenix_channel_id: string;
+    filename?: string;
+}
+/**
+ * Schema update notification message
+ */
+interface SchemaUpdateMessage extends SyncMessage {
+    type: 'schema_update';
+    new_version: number;
+    migrations?: Array<{
+        version: number;
+        description: string;
+        sql: string[];
+    }>;
+    timestamp: number;
+}
+/**
+ * Livestream event message
+ */
+interface LivestreamMessage extends SyncMessage {
+    type: 'livestream:started' | 'livestream:stopped';
+    stream_id?: string;
+    tribe_id?: string;
+    user_id?: string;
+    hls_url?: string;
+    timestamp: number;
+}
+/**
+ * Conversation event message
+ */
+interface ConversationMessage extends SyncMessage {
+    type: 'conversation:user_joined' | 'conversation:user_left' | 'conversation:message_sent' | 'conversation:online_count';
+    conversation_id?: string;
+    user_id?: string;
+    message_id?: string;
+    online_count?: number;
+    metadata?: Record<string, any>;
+    timestamp: number;
+}
+/**
+ * Single change acknowledgment (used within ChangeAcksMessage)
+ */
+interface ChangeAck {
+    local_seqnum: number;
+    success: boolean;
+    server_seqnum?: number;
+    error?: string;
+    /** Server-computed row_hash (set by Postgres trigger). */
+    row_hash?: string;
+}
+/**
+ * Batch of change acknowledgments (unified sync protocol)
+ */
+interface ChangeAcksMessage extends SyncMessage {
+    type: 'change_acks';
+    stream_id?: string;
+    acks: ChangeAck[];
+}
+/**
+ * Unified sync data batch from server
+ */
+interface SyncDataBatchMessage extends SyncMessage {
+    type: 'sync_data_batch' | 'sync_batch';
+    stream_id?: string;
+    table: string;
+    rows: Array<Record<string, any>>;
+}
+/**
+ * Unified sync completion signal with statistics
+ */
+interface SyncCompleteMessage extends SyncMessage {
+    type: 'sync_complete';
+    stream_id?: string;
+    schema_version: number;
+    table_seqnums: Record<string, number>;
+    stats?: {
+        schema_upgraded?: boolean;
+        migrations_applied?: number;
+        push_total?: number;
+        push_success?: number;
+        push_failed?: number;
+        push_by_table?: Record<string, Record<string, any>>;
+        pull_total?: number;
+        pull_by_table?: Record<string, Record<string, any>>;
+        elapsed_ms?: number;
+    };
+}
+/**
+ * Server response to merkle_push_blocks (client pushes rows to server)
+ */
+interface MerklePushBlocksResponse extends SyncMessage {
+    type: 'merkle_push_blocks_response';
+    table: string;
+    block_index: number;
+    applied: number;
+    rejected: number;
+    deleted: number;
+    errors: Array<Record<string, any>>;
+}
+/**
+ * Server response to merkle_lww_blocks (last-write-wins resolution)
+ */
+interface MerkleLwwBlocksResponse extends SyncMessage {
+    type: 'merkle_lww_blocks_response';
+    table: string;
+    block_index: number;
+    client_wins: string[];
+    server_wins: Array<Record<string, any>>;
+    applied_from_client: number;
+    sent_to_client: number;
+}
+/**
+ * Message factory functions
+ */
+declare const MessageFactory: {
+    /**
+     * Create a HelloMessage
+     */
+    hello(clientId: string, schemaVersion?: number, lastSeqnum?: number, metadata?: Record<string, any>): HelloMessage;
+    /**
+     * Create a ChangeMessage from a synclib Change object
+     */
+    fromChange(change: Change): ChangeMessage;
+    /**
+     * Create a ChangesBatchMessage
+     */
+    changesBatch(changes: ChangeMessage[], fromSeqnum?: number, toSeqnum?: number): ChangesBatchMessage;
+    /**
+     * Create a RequestChangesMessage
+     */
+    requestChanges(sinceSeqnum?: number, limit?: number, table?: string): RequestChangesMessage;
+    /**
+     * Create a SchemaConfirmMessage
+     */
+    schemaConfirm(version: number): SchemaConfirmMessage;
+    /**
+     * Parse a message from a map
+     */
+    fromMap(map: Record<string, any>): SyncMessage;
+};
+
+/**
+ * Connection state
+ */
+declare enum ConnectionState {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    RECONNECTING = "reconnecting",
+    FAILED = "failed",
+    AUTH_FAILED = "auth_failed"
+}
+/**
+ * WebSocket connection manager using Phoenix Channels
+ */
+declare class WebSocketManager {
+    private url;
+    private reconnectDelay;
+    private maxReconnectAttempts;
+    private socket;
+    private channels;
+    private state;
+    private messageListeners;
+    private stateListeners;
+    private reconnectAttempts;
+    private connectionParams?;
+    private connectStartTime;
+    private intentionalDisconnect;
+    private quickFailureCount;
+    private static readonly QUICK_FAILURE_THRESHOLD;
+    private onAuthFailureCallback?;
+    private authFailureFired;
+    constructor(url: string, reconnectDelay?: number, maxReconnectAttempts?: number);
+    /**
+     * Register a callback fired when the connection is rejected due to auth
+     * (e.g. expired JWT). The callback can refresh the token via setToken() and
+     * then call connect() again to retry.
+     */
+    setOnAuthFailure(callback: () => void): void;
+    /**
+     * Update the JWT (or other auth param) used for subsequent connect/reconnect
+     * attempts. The Socket reads its `params` via a thunk so the next reconnect
+     * picks up the new value without recreating the socket.
+     *
+     * If the connection is currently in AUTH_FAILED (reconnects were halted), a
+     * fresh token implies the caller wants to retry — we tear down the failed
+     * socket, reset state, and schedule a new connect.
+     */
+    setToken(token: string): void;
+    /**
+     * Build the string params map from current connectionParams. Called on every
+     * Phoenix reconnect attempt so token refreshes (via setToken) take effect
+     * without tearing down the socket.
+     */
+    private buildStringParams;
+    /**
+     * Connect to WebSocket server
+     */
+    connect(params?: Record<string, any>): Promise<void>;
+    /**
+     * Join a Phoenix channel
+     */
+    joinChannel(topic: string, params?: Record<string, any>): Promise<Record<string, any>>;
+    /**
+     * Check if a channel is currently joined
+     */
+    isChannelJoined(topic: string): boolean;
+    /**
+     * Get all currently joined channel topics
+     */
+    getJoinedChannels(): string[];
+    /**
+     * Leave a specific channel by topic
+     */
+    leaveChannel(topic: string): Promise<void>;
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a message to the server
+     */
+    send(message: SyncMessage, channelTopic?: string): Promise<void>;
+    /**
+     * Send a raw message with custom event and payload, returns server response
+     */
+    sendRaw(event: string, payload: Record<string, any>, channelTopic?: string): Promise<Record<string, any>>;
+    /**
+     * Handle incoming message
+     */
+    private handleIncomingMessage;
+    /**
+     * Handle channel reply messages
+     */
+    private handleChannelReply;
+    /**
+     * Handle WebSocket error
+     */
+    private onError;
+    /**
+     * Handle WebSocket close
+     */
+    private onClose;
+    /**
+     * Schedule automatic reconnection
+     */
+    private scheduleReconnect;
+    /**
+     * Update connection state and notify listeners
+     */
+    private updateState;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get current connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Subscribe to messages
+     */
+    onMessage(listener: (message: SyncMessage) => void): () => void;
+    /**
+     * Subscribe to state changes
+     */
+    onStateChange(listener: (state: ConnectionState) => void): () => void;
+    /**
+     * Dispose resources
+     */
+    dispose(): Promise<void>;
+}
+
+/**
+ * Sync readiness state (legacy - kept for backward compatibility)
+ */
+declare enum SyncReadyState {
+    WAITING_FOR_HELLO = "waiting_for_hello",
+    APPLYING_MIGRATIONS = "applying_migrations",
+    READY = "ready"
+}
+/**
+ * Unified sync state - lifecycle of sync operations
+ */
+declare enum SyncState {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    SYNCING = "syncing",
+    READY = "ready",
+    ERROR = "error"
+}
+/**
+ * Progress during sync operation
+ */
+interface SyncProgress {
+    phase: 'pushing' | 'pulling' | 'migrating' | 'complete';
+    table?: string;
+    rowCount?: number;
+    changesPushed?: number;
+    changesAcked?: number;
+}
+/**
+ * Per-table sync statistics
+ */
+interface SyncTableStats {
+    rowsPulled: number;
+    changesPushed: number;
+    changesSucceeded: number;
+    changesFailed: number;
+}
+/**
+ * Sync completion event with detailed statistics
+ */
+interface SyncCompleteEvent {
+    streamId?: string;
+    schemaVersion: number;
+    tableSeqnums: Record<string, number>;
+    schemaUpgraded: boolean;
+    migrationsApplied: number;
+    totalRowsPulled: number;
+    totalChangesPushed: number;
+    totalChangesSucceeded: number;
+    totalChangesFailed: number;
+    pullStats: Record<string, SyncTableStats>;
+    pushStats: Record<string, SyncTableStats>;
+}
+/**
+ * Event emitted when Merkle verification completes
+ * Fires after background verification, especially useful when repairs occurred
+ */
+interface MerkleVerificationEvent {
+    /** Tables that were repaired (empty if all matched) */
+    repairedTables: string[];
+    /** Whether any repairs were made */
+    hadMismatches: boolean;
+}
+/**
+ * Direction of repair when data differs between client and server.
+ * Applies to both seqnum-based sync and merkle tree verification.
+ */
+declare enum RepairDirection {
+    /** Server is authoritative. Client overwrites local data with server data. */
+    PULL = "pull",
+    /** Client is authoritative. Client sends its rows to server. */
+    PUSH = "push",
+    /** Last-write-wins. Compare last_modified_ms per row. */
+    LWW = "lww"
+}
+/**
+ * Role of a channel in sync topology.
+ */
+declare enum ChannelRole {
+    /** Client pushes its own data on this channel (e.g., user channel). */
+    PUSH = "push",
+    /** Client pulls shared data from this channel (e.g., tribe channel). */
+    PULL = "pull",
+    /** Channel supports both push and pull. */
+    BIDIRECTIONAL = "bidirectional"
+}
+/**
+ * A table associated with a sync channel.
+ * direction overrides the channel's default repair direction for this table.
+ * If omitted, defaults to the channel role's implied direction.
+ */
+interface SyncTable {
+    name: string;
+    direction?: RepairDirection;
+    /** Columns to include in merkle hash (besides id). When set, only these columns
+     *  are hashed, bypassing the precomputed row_hash fast path. */
+    hashColumns?: string[];
+}
+/**
+ * A sync channel: its topic, role, associated tables, and join params.
+ *
+ * Used for both seqnum-based sync (which tables to push/pull) and merkle
+ * tree verification (which tables to verify and how to repair).
+ */
+interface SyncChannel {
+    /** The Phoenix channel topic (e.g., "sync:tribe:trainer123", "sync:user:user456") */
+    topic: string;
+    /** Role of this channel in the sync topology. */
+    role: ChannelRole;
+    /** Tables on this channel. Used for both seqnum sync and merkle verification. */
+    tables?: SyncTable[];
+    /** Optional params to send when joining this channel. */
+    params?: Record<string, string>;
+}
+/**
+ * Configuration for sync client
+ */
+interface SyncClientConfig {
+    /** Synclib database instance */
+    db: SynclibDatabase;
+    /** WebSocket server URL */
+    serverUrl: string;
+    /** Unique client identifier */
+    clientId: string;
+    /** Channels to connect to and sync on. */
+    channels: SyncChannel[];
+    /** Batch size for pushing changes */
+    pushBatchSize?: number;
+    /** Optional metadata to send in hello message */
+    metadata?: Record<string, any>;
+    /** Debounce duration in ms for notifyLocalChange().
+     * Batches rapid writes together before pushing.
+     * Defaults to 100ms. */
+    syncOnWriteDebounce?: number;
+    /** Connection timeout in ms for waitForConnection().
+     * Defaults to 30000 (30 seconds). */
+    connectionTimeout?: number;
+    /** Sync operation timeout in ms.
+     * Defaults to 300000 (5 minutes). */
+    syncTimeout?: number;
+    /** Interval in ms for periodic background sync.
+     * When set, a timer calls syncUnified() at this interval.
+     * When undefined, sync is purely reactive (notifyLocalChange + manual calls).
+     * Defaults to undefined (disabled). */
+    periodicSyncInterval?: number;
+    /** Interval in ms for periodic Merkle integrity verification.
+     * When set, the client will periodically verify data integrity
+     * for the specified tables using Merkle tree comparison.
+     * Defaults to undefined (disabled). */
+    merkleVerifyInterval?: number;
+}
+/**
+ * Conflict resolver callback
+ */
+type ConflictResolver = (local: ChangeMessage, remote: ChangeMessage) => Promise<ChangeMessage | null>;
+/**
+ * Main sync client orchestrating bidirectional sync
+ */
+declare class SyncClient {
+    private ws;
+    private db;
+    private config;
+    private serverMerkleBlockSize?;
+    private serverHashColumns?;
+    private isInitialized;
+    private hasConnectedOnce;
+    private pendingAcks;
+    private pendingChangeInfo;
+    private remoteChangeListeners;
+    private snapshotCompleteListeners;
+    private jobUpdateListeners;
+    private livestreamListeners;
+    private conversationListeners;
+    private syncReadyStateListeners;
+    private readyState;
+    private batchQueue;
+    private batchLock;
+    private messageQueue;
+    private processingMessages;
+    private conflictResolver?;
+    private helloHandshakeResolve?;
+    private syncOnWriteDebounceTimer?;
+    private periodicSyncTimer?;
+    private syncState;
+    private isSyncing;
+    private tableSeqnums;
+    private activeSyncCompleters;
+    private syncStateListeners;
+    private syncProgressListeners;
+    private syncCompleteListeners;
+    private merkleVerificationListeners;
+    constructor(config: SyncClientConfig);
+    /** Get channels that push (push or bidirectional role). */
+    private get pushChannels();
+    /** Get channels that pull (pull or bidirectional role). */
+    private get pullChannels();
+    /** Get all sync table names from channels config. */
+    private get allSyncTables();
+    /**
+     * One-time migration: switch to server-authoritative row_hash.
+     * Sets all local row_hash values to '' (sentinel) so merkle comparison
+     * detects mismatch and triggers repair from server.
+     */
+    private migrateToServerAuthoritativeRowHash;
+    /**
+     * Initialize the sync client
+     */
+    initialize(): Promise<void>;
+    /**
+     * Connect to sync server.
+     * `extra` is forwarded as additional Phoenix socket connect params —
+     * used for `slug` and `env` so the server can route the per-app
+     * Postgres schema ({slug}_dev vs {slug}_prod).
+     */
+    connect(token: string, extra?: Record<string, string>): Promise<void>;
+    /**
+     * Update the auth token used on subsequent (re)connects without tearing
+     * down the socket. Use this when the host app refreshes a JWT — typically
+     * either proactively (on a timer) or reactively (in response to
+     * setOnAuthFailure).
+     */
+    setToken(token: string): void;
+    /**
+     * Register a callback fired when the WebSocket is rejected due to bad/expired
+     * auth. The host app should refresh the token, call setToken(newToken), then
+     * call connect() again (or rely on the next scheduled reconnect, after we
+     * clear AUTH_FAILED state).
+     */
+    setOnAuthFailure(callback: () => void): void;
+    /**
+     * Join all configured channels
+     */
+    private joinChannels;
+    /**
+     * Join an additional channel after initial connection
+     */
+    joinChannel(channel: SyncChannel): Promise<void>;
+    /**
+     * Check if a channel is currently joined
+     */
+    isChannelJoined(channel: SyncChannel): boolean;
+    /**
+     * Get all currently joined channel topics
+     */
+    getJoinedChannels(): string[];
+    /**
+     * Update the channel configuration dynamically.
+     * Useful when new tables are discovered (e.g. after schema_update migration).
+     * The allSyncTables getter automatically uses config.channels.
+     */
+    updateChannels(channels: SyncChannel[]): void;
+    /**
+     * Leave a channel
+     */
+    leaveChannel(channel: SyncChannel): Promise<void>;
+    /**
+     * Leave a channel by its topic ID (e.g., "sync:user:123")
+     */
+    leaveChannelById(channelId: string): Promise<void>;
+    /**
+     * Disconnect from sync server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Manually trigger a sync cycle.
+     * Calls syncUnified() which handles push, pull, schema, and stripped content.
+     */
+    sync(): Promise<void>;
+    /**
+     * Unified sync - single operation that handles push, pull, and schema in one request.
+     *
+     * This is the recommended sync method that matches the Flutter implementation.
+     * It prevents concurrent syncs and waits for connection if disconnected.
+     */
+    syncUnified(options?: {
+        forceRefresh?: string[];
+        includeStripped?: boolean;
+    }): Promise<void>;
+    /**
+     * Wait for WebSocket connection with timeout
+     */
+    private waitForConnection;
+    /**
+     * Get per-table seqnums for incremental sync
+     */
+    private getPerTableSeqnums;
+    /**
+     * Wait for sync complete message
+     */
+    private waitForSyncComplete;
+    /**
+     * Update sync state and notify listeners
+     */
+    private updateSyncState;
+    /**
+     * Emit sync progress event
+     */
+    private emitSyncProgress;
+    /**
+     * Extract server-driven hash_columns from a channel join response.
+     */
+    private extractServerHashColumns;
+    /**
+     * Send hello message to server
+     */
+    private sendHello;
+    /**
+     * Enqueue a message for serialized processing.
+     * Prevents interleaving when multiple async messages arrive rapidly.
+     */
+    private enqueueMessage;
+    /**
+     * Process queued messages one at a time.
+     */
+    private processMessageQueue;
+    /**
+     * Handle incoming message from server
+     */
+    private handleMessage;
+    /**
+     * Apply a single remote change to local database
+     */
+    private applyRemoteChange;
+    /**
+     * Apply multiple remote changes
+     */
+    private applyRemoteChanges;
+    /**
+     * Handle acknowledgment from server
+     */
+    private handleAck;
+    /**
+     * Update the seqnum column on a local row after server assigns it
+     */
+    private updateLocalSeqnum;
+    /**
+     * Update the row_hash column on a local row with the server-computed value
+     */
+    private updateLocalRowHash;
+    /**
+     * Handle error message from server
+     */
+    private handleError;
+    /**
+     * Queue snapshot batch for processing
+     */
+    private queueSnapshotBatch;
+    /**
+     * Process all batches in the queue serially
+     */
+    private processBatchQueue;
+    /**
+     * Handle snapshot batch message
+     */
+    private handleSnapshotBatch;
+    /**
+     * Handle snapshot complete message
+     */
+    private handleSnapshotComplete;
+    /**
+     * Handle job update message
+     */
+    private handleJobUpdate;
+    /**
+     * Handle livestream message
+     */
+    private handleLivestream;
+    /**
+     * Handle conversation message
+     */
+    private handleConversation;
+    /**
+     * Handle schema update notification
+     */
+    private handleSchemaUpdate;
+    /**
+     * Handle batch of change acknowledgments (unified sync protocol)
+     */
+    private handleChangeAcks;
+    /**
+     * Handle sync data batch (unified sync protocol)
+     */
+    private handleSyncDataBatch;
+    /**
+     * Handle sync complete message (unified sync protocol)
+     */
+    private handleSyncComplete;
+    /**
+     * Handle Phoenix reply messages
+     */
+    private handlePhoenixReply;
+    /**
+     * Apply schema migrations from server
+     */
+    private applyMigrations;
+    /**
+     * Update sync ready state
+     */
+    private updateReadyState;
+    /**
+     * Handle connection state changes
+     */
+    private handleStateChange;
+    /**
+     * Generate SQL statement from change message
+     */
+    private generateSql;
+    /**
+     * Format a value for SQL
+     */
+    private formatSqlValue;
+    /**
+     * Escape single quotes in SQL strings
+     */
+    private escapeSql;
+    /**
+     * Quote a SQL identifier (table or column name) to prevent SQL injection.
+     */
+    private quoteId;
+    /**
+     * Convert operation string to SynclibOperation
+     */
+    private toSynclibOperation;
+    /**
+     * Execute function with batch lock (serial processing)
+     */
+    private withBatchLock;
+    /**
+     * Stream snapshot of tables from server
+     */
+    streamSnapshot(tables: string[], options?: {
+        incremental?: boolean;
+        channelTopic?: string;
+    }): Promise<void>;
+    /**
+     * Fetch a full row from the server
+     */
+    fetchRow(table: string, rowId: string): Promise<Record<string, any>>;
+    /**
+     * Send a custom message to the server and wait for reply
+     */
+    sendMessage(event: string, payload: Record<string, any>, channelTopic?: string): Promise<Record<string, any>>;
+    /**
+     * Send a conversation presence event
+     */
+    sendConversationPresence(options: {
+        conversationId: string;
+        userId: string;
+        event: 'conversation:user_joined' | 'conversation:user_left';
+        channelTopic?: string;
+    }): Promise<void>;
+    /**
+     * Set conflict resolver
+     */
+    setConflictResolver(resolver: ConflictResolver): void;
+    /**
+     * Notify the sync client that a local change occurred.
+     *
+     * Call this after writing to the database to trigger an immediate push.
+     * Uses debouncing to batch rapid writes together (configurable via syncOnWriteDebounce).
+     *
+     * Example:
+     * ```typescript
+     * // After writing to the database
+     * await db.write({ tableName: 'users', rowId: '123', ... });
+     * syncClient.notifyLocalChange();
+     * ```
+     */
+    notifyLocalChange(): void;
+    /** Start periodic background sync timer if configured. */
+    private startPeriodicSync;
+    /** Stop periodic background sync timer. */
+    private stopPeriodicSync;
+    /**
+     * Event listeners
+     */
+    onRemoteChange(listener: (change: ChangeMessage) => void): () => void;
+    onSnapshotComplete(listener: (streamId: string, channelId: string) => void): () => void;
+    onJobUpdate(listener: (update: JobUpdateMessage) => void): () => void;
+    onLivestream(listener: (message: LivestreamMessage) => void): () => void;
+    onConversation(listener: (message: ConversationMessage) => void): () => void;
+    onSyncReadyStateChange(listener: (state: SyncReadyState) => void): () => void;
+    onStateChange(listener: (state: ConnectionState) => void): () => void;
+    /**
+     * Listen to unified sync state changes
+     */
+    onSyncStateChange(listener: (state: SyncState) => void): () => void;
+    /**
+     * Listen to sync progress events
+     */
+    onSyncProgress(listener: (progress: SyncProgress) => void): () => void;
+    /**
+     * Listen to sync complete events
+     */
+    onSyncComplete(listener: (event: SyncCompleteEvent) => void): () => void;
+    /**
+     * Listen to Merkle verification events
+     * Fires after background verification completes, especially useful when repairs occurred.
+     * Subscribe to invalidate caches/refs when data was repaired.
+     */
+    onMerkleVerification(listener: (event: MerkleVerificationEvent) => void): () => void;
+    /**
+     * Getters
+     */
+    get connectionState(): ConnectionState;
+    get isReady(): boolean;
+    get currentReadyState(): SyncReadyState;
+    /**
+     * Get current unified sync state
+     */
+    get currentSyncState(): SyncState;
+    /**
+     * Check if Merkle verification is needed based on staleness.
+     * Called at the end of syncUnified to run verification if interval has elapsed.
+     */
+    private checkMerkleVerification;
+    /**
+     * Merkle verification using the new channels config.
+     * Verifies all tables per channel, then dispatches repair by direction.
+     */
+    private merkleVerifyFromChannels;
+    /**
+     * Legacy merkle verification using old config fields (backward compat).
+     */
+    /**
+     * Compare local Merkle roots against server and return mismatches.
+     * Shared root-verification step used by the channels config path.
+     */
+    private verifyRoots;
+    /**
+     * Verify data integrity using Merkle trees.
+     *
+     * Compares local Merkle roots against server and repairs any mismatched blocks.
+     * This is a consistency audit that catches:
+     * - Data corruption during development
+     * - Seqnum drift from manual database edits
+     * - Missed changes from network issues
+     * - Any state where seqnums match but data differs
+     *
+     * @param options - Verification options
+     * @returns List of tables that were repaired. Empty array means all matched.
+     *
+     * @example
+     * ```typescript
+     * const repairedTables = await syncClient.verifyIntegrity({
+     *   tables: ['users', 'workouts'],
+     *   blockSize: 100,
+     * });
+     * if (repairedTables.length > 0) {
+     *   console.log('Repaired tables:', repairedTables);
+     * }
+     * ```
+     */
+    verifyIntegrity(options?: {
+        tables?: string[];
+        blockSize?: number;
+        channelTopic?: string;
+    }): Promise<string[]>;
+    /**
+     * Repair a table by fetching differing blocks from server (pull: server → client)
+     */
+    private repairTablePull;
+    /**
+     * Fetch a block from server and apply to local database
+     */
+    private fetchAndApplyBlock;
+    /**
+     * Repair a table by pushing local rows to server (push: client → server)
+     */
+    private repairTablePush;
+    /**
+     * Read local rows for a block and push them to the server.
+     */
+    private pushBlockToServer;
+    /**
+     * Repair a table using last-write-wins (LWW) resolution.
+     * Sends local rows to server which compares last_modified_ms timestamps.
+     */
+    private repairTableLww;
+    /**
+     * Resolve a single block using last-write-wins.
+     */
+    private lwwResolveBlock;
+    /**
+     * Dispose resources
+     */
+    dispose(): Promise<void>;
+}
+
+export { type AckMessage, type ChangeAck, type ChangeAcksMessage, type ChangeMessage, type ChangesBatchMessage, ChannelRole, type ConflictResolver, ConnectionState, type ConversationMessage, type ErrorMessage, type HelloMessage, type JobUpdateMessage, type LivestreamMessage, type MerkleLwwBlocksResponse, type MerklePushBlocksResponse, type MerkleVerificationEvent, MessageFactory, type PhoenixReplyMessage, RepairDirection, type RequestChangesMessage, type SchemaConfirmMessage, type SchemaUpdateMessage, type SnapshotBatchMessage, type SnapshotCompleteMessage, type SyncChannel, SyncClient, type SyncClientConfig, type SyncCompleteEvent, type SyncCompleteMessage, type SyncDataBatchMessage, type SyncMessage, type SyncProgress, SyncReadyState, SyncState, type SyncTable, type SyncTableStats, WebSocketManager };