@topgunbuild/client 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { LWWRecord, ORMapRecord, PredicateNode, ConflictResolverDef, MergeRejection, Timestamp, LWWMap, ORMap, HLC, EntryProcessorDef, EntryProcessorResult, SearchOptions, PNCounter, PNCounterState, JournalEvent, JournalEventType, NodeHealth, ConnectionPoolConfig, PartitionRouterConfig, PartitionMap, ClusterClientConfig } from '@topgunbuild/core';
+import { LWWRecord, ORMapRecord, PredicateNode, ConflictResolverDef, MergeRejection, Timestamp, LWWMap, ORMap, HLC, EntryProcessorDef, EntryProcessorResult, SearchOptions, HybridQueryRespPayload, HybridQueryDeltaPayload, PNCounter, PNCounterState, JournalEvent, JournalEventType, NodeHealth, ConnectionPoolConfig, PartitionRouterConfig, PartitionMap, ClusterClientConfig } from '@topgunbuild/core';
 export { LWWMap, LWWRecord, PredicateNode, Predicates } from '@topgunbuild/core';
 import pino from 'pino';
 
@@ -99,12 +99,12 @@ interface QueryFilter {
     predicate?: PredicateNode;
     sort?: Record<string, 'asc' | 'desc'>;
     limit?: number;
-    /** Cursor for pagination (Phase 14.1: replaces offset) */
+    /** Cursor for pagination */
     cursor?: string;
 }
-/** Cursor status for debugging (Phase 14.1) */
+/** Cursor status for debugging */
 type CursorStatus = 'valid' | 'expired' | 'invalid' | 'none';
-/** Pagination info from server (Phase 14.1) */
+/** Pagination info from server */
 interface PaginationInfo {
     /** Cursor for fetching next page */
     nextCursor?: string;
@@ -156,7 +156,7 @@ declare class QueryHandle<T> {
      */
     onUpdate(key: string, value: T | null): void;
     /**
-     * Subscribe to change events (Phase 5.1).
+     * Subscribe to change events.
      * Returns an unsubscribe function.
      *
      * @example
@@ -172,25 +172,25 @@ declare class QueryHandle<T> {
      */
     onChanges(listener: (changes: ChangeEvent<T>[]) => void): () => void;
     /**
-     * Get and clear pending changes (Phase 5.1).
+     * Get and clear pending changes.
      * Call this to retrieve all changes since the last consume.
      */
     consumeChanges(): ChangeEvent<T>[];
     /**
-     * Get last change without consuming (Phase 5.1).
+     * Get last change without consuming.
      * Returns null if no pending changes.
      */
     getLastChange(): ChangeEvent<T> | null;
     /**
-     * Get all pending changes without consuming (Phase 5.1).
+     * Get all pending changes without consuming.
      */
     getPendingChanges(): ChangeEvent<T>[];
     /**
-     * Clear all pending changes (Phase 5.1).
+     * Clear all pending changes.
      */
     clearChanges(): void;
     /**
-     * Reset change tracker (Phase 5.1).
+     * Reset change tracker.
      * Use when query filter changes or on reconnect.
      */
     resetChangeTracker(): void;
@@ -230,8 +230,6 @@ declare class QueryHandle<T> {
  * - Score-based sorting (_score field)
  * - Hybrid queries combining FTS with traditional filters
  *
- * Part of Phase 12: Unified Search
- *
  * @module HybridQueryHandle
  */
 
@@ -247,7 +245,7 @@ interface HybridQueryFilter {
     sort?: Record<string, 'asc' | 'desc'>;
     /** Maximum results */
     limit?: number;
-    /** Cursor for pagination (Phase 14.1: replaces offset) */
+    /** Cursor for pagination */
     cursor?: string;
 }
 /**
@@ -386,7 +384,7 @@ declare class HybridQueryHandle<T> {
     private notifyPaginationListeners;
 }
 
-type TopicCallback = (data: any, context: {
+type TopicCallback<T = unknown> = (data: T, context: {
     timestamp: number;
     publisherId?: string;
 }) => void;
@@ -399,7 +397,7 @@ declare class TopicHandle {
     /**
      * Publish a message to the topic
      */
-    publish(data: any): void;
+    publish(data: unknown): void;
     /**
      * Subscribe to the topic
      */
@@ -408,7 +406,7 @@ declare class TopicHandle {
     /**
      * Called by SyncEngine when a message is received
      */
-    onMessage(data: any, context: {
+    onMessage(data: unknown, context: {
         timestamp: number;
         publisherId?: string;
     }): void;
@@ -837,6 +835,13 @@ declare class ConflictResolverClient {
     get rejectionListenerCount(): number;
 }
 
+/**
+ * Sync Module Types
+ *
+ * Types and interfaces for the sync module that handles
+ * WebSocket/connection operations and query management for SyncEngine.
+ */
+
 /**
  * Search result item from server.
  */
@@ -846,6 +851,7 @@ interface SearchResult<T> {
     score: number;
     matchedTerms: string[];
 }
+
 interface HeartbeatConfig {
     intervalMs: number;
     timeoutMs: number;
@@ -863,50 +869,63 @@ interface BackoffConfig {
     /** Maximum number of retry attempts before entering ERROR state (default: 10) */
     maxRetries: number;
 }
+interface TopicQueueConfig {
+    /** Maximum queued topic messages when offline (default: 100) */
+    maxSize: number;
+    /** Strategy when queue is full: 'drop-oldest' | 'drop-newest' (default: 'drop-oldest') */
+    strategy: 'drop-oldest' | 'drop-newest';
+}
 interface SyncEngineConfig {
     nodeId: string;
-    /** @deprecated Use connectionProvider instead */
-    serverUrl?: string;
-    /** Connection provider (preferred over serverUrl) */
-    connectionProvider?: IConnectionProvider;
+    /** Connection provider for WebSocket connections */
+    connectionProvider: IConnectionProvider;
     storageAdapter: IStorageAdapter;
     reconnectInterval?: number;
     heartbeat?: Partial<HeartbeatConfig>;
     backoff?: Partial<BackoffConfig>;
     backpressure?: Partial<BackpressureConfig>;
+    /** Configuration for offline topic message queue */
+    topicQueue?: Partial<TopicQueueConfig>;
 }
 declare class SyncEngine {
     private readonly nodeId;
-    private readonly serverUrl;
     private readonly storageAdapter;
     private readonly hlc;
     private readonly stateMachine;
+    private readonly heartbeatConfig;
     private readonly backoffConfig;
-    private readonly connectionProvider;
-    private readonly useConnectionProvider;
-    private websocket;
+    private readonly webSocketManager;
+    private readonly queryManager;
+    private readonly topicManager;
+    private readonly lockManager;
+    private readonly writeConcernManager;
+    private readonly counterManager;
+    private readonly entryProcessorClient;
+    private readonly searchClient;
+    private readonly merkleSyncHandler;
+    private readonly orMapSyncHandler;
+    private readonly messageRouter;
     private opLog;
     private maps;
-    private queries;
-    private topics;
-    private pendingLockRequests;
     private lastSyncTimestamp;
-    private reconnectTimer;
     private authToken;
     private tokenProvider;
-    private backoffAttempt;
-    private readonly heartbeatConfig;
-    private heartbeatInterval;
-    private lastPongReceived;
-    private lastRoundTripTime;
     private readonly backpressureConfig;
-    private backpressurePaused;
-    private waitingForCapacity;
-    private highWaterMarkEmitted;
-    private backpressureListeners;
-    private pendingWriteConcernPromises;
+    private readonly backpressureController;
     private readonly conflictResolverClient;
     constructor(config: SyncEngineConfig);
+    /**
+     * Called when connection is established (initial or reconnect).
+     */
+    private handleConnectionEstablished;
+    /**
+     * Called when connection is lost.
+     */
+    private handleConnectionLost;
+    /**
+     * Called when reconnection succeeds.
+     */
+    private handleReconnection;
     /**
      * Get the current connection state
      */
@@ -932,33 +951,11 @@ declare class SyncEngine {
      * Check if fully connected and synced
      */
     private isConnected;
-    /**
-     * Initialize connection using IConnectionProvider (Phase 4.5 cluster mode).
-     * Sets up event handlers for the connection provider.
-     */
-    private initConnectionProvider;
-    /**
-     * Initialize connection using direct WebSocket (legacy single-server mode).
-     */
-    private initConnection;
-    private scheduleReconnect;
-    private calculateBackoffDelay;
-    /**
-     * Reset backoff counter (called on successful connection)
-     */
-    private resetBackoff;
     /**
      * Send a message through the current connection.
-     * Uses connectionProvider if in cluster mode, otherwise uses direct websocket.
-     * @param message Message object to serialize and send
-     * @param key Optional key for routing (cluster mode only)
-     * @returns true if message was sent, false otherwise
+     * Delegates to WebSocketManager.
      */
     private sendMessage;
-    /**
-     * Check if we can send messages (connection is ready).
-     */
-    private canSend;
     private loadOpLog;
     private saveOpLog;
     registerMap(mapName: string, map: LWWMap<any, any> | ORMap<any, any>): void;
@@ -973,25 +970,69 @@ declare class SyncEngine {
     setAuthToken(token: string): void;
     setTokenProvider(provider: () => Promise<string | null>): void;
     private sendAuth;
+    /**
+     * Subscribe to a standard query.
+     * Delegates to QueryManager.
+     */
     subscribeToQuery(query: QueryHandle<any>): void;
+    /**
+     * Subscribe to a topic.
+     * Delegates to TopicManager.
+     */
     subscribeToTopic(topic: string, handle: TopicHandle): void;
+    /**
+     * Unsubscribe from a topic.
+     * Delegates to TopicManager.
+     */
     unsubscribeFromTopic(topic: string): void;
-    publishTopic(topic: string, data: any): void;
-    private sendTopicSubscription;
     /**
-     * Executes a query against local storage immediately
+     * Publish a message to a topic.
+     * Delegates to TopicManager.
+     */
+    publishTopic(topic: string, data: unknown): void;
+    /**
+     * Get topic queue status.
+     * Delegates to TopicManager.
+     */
+    getTopicQueueStatus(): {
+        size: number;
+        maxSize: number;
+    };
+    /**
+     * Executes a query against local storage immediately.
+     * Delegates to QueryManager.
      */
     runLocalQuery(mapName: string, filter: QueryFilter): Promise<{
         key: string;
         value: any;
     }[]>;
+    /**
+     * Unsubscribe from a query.
+     * Delegates to QueryManager.
+     */
     unsubscribeFromQuery(queryId: string): void;
-    private sendQuerySubscription;
+    /**
+     * Request a distributed lock.
+     * Delegates to LockManager.
+     */
     requestLock(name: string, requestId: string, ttl: number): Promise<{
         fencingToken: number;
     }>;
+    /**
+     * Release a distributed lock.
+     * Delegates to LockManager.
+     */
     releaseLock(name: string, requestId: string, fencingToken: number): Promise<boolean>;
     private handleServerMessage;
+    private handleBatch;
+    private handleAuthAck;
+    private handleAuthFail;
+    private handleOpAck;
+    private handleQueryResp;
+    private handleQueryUpdate;
+    private handleServerEvent;
+    private handleServerBatchEvent;
+    private handleGcPrune;
     getHLC(): HLC;
     /**
      * Helper method to apply a single server event to the local map.
@@ -1045,26 +1086,6 @@ declare class SyncEngine {
      */
     getConnectionProvider(): IConnectionProvider;
     private resetMap;
-    /**
-     * Starts the heartbeat mechanism after successful connection.
-     */
-    private startHeartbeat;
-    /**
-     * Stops the heartbeat mechanism.
-     */
-    private stopHeartbeat;
-    /**
-     * Sends a PING message to the server.
-     */
-    private sendPing;
-    /**
-     * Handles incoming PONG message from server.
-     */
-    private handlePong;
-    /**
-     * Checks if heartbeat has timed out and triggers reconnection if needed.
-     */
-    private checkHeartbeatTimeout;
     /**
      * Returns the last measured round-trip time in milliseconds.
      * Returns null if no PONG has been received yet.
@@ -1076,108 +1097,68 @@ declare class SyncEngine {
      * a PONG within the timeout window.
      */
     isConnectionHealthy(): boolean;
-    /**
-     * Push local ORMap diff to server for the given keys.
-     * Sends local records and tombstones that the server might not have.
-     */
-    private pushORMapDiff;
     /**
      * Get the current number of pending (unsynced) operations.
+     * Delegates to BackpressureController.
      */
     getPendingOpsCount(): number;
     /**
      * Get the current backpressure status.
+     * Delegates to BackpressureController.
      */
     getBackpressureStatus(): BackpressureStatus;
     /**
      * Returns true if writes are currently paused due to backpressure.
+     * Delegates to BackpressureController.
      */
     isBackpressurePaused(): boolean;
     /**
      * Subscribe to backpressure events.
+     * Delegates to BackpressureController.
      * @param event Event name: 'backpressure:high', 'backpressure:low', 'backpressure:paused', 'backpressure:resumed', 'operation:dropped'
      * @param listener Callback function
      * @returns Unsubscribe function
      */
     onBackpressure(event: 'backpressure:high' | 'backpressure:low' | 'backpressure:paused' | 'backpressure:resumed' | 'operation:dropped', listener: (data?: BackpressureThresholdEvent | OperationDroppedEvent) => void): () => void;
-    /**
-     * Emit a backpressure event to all listeners.
-     */
-    private emitBackpressureEvent;
-    /**
-     * Check backpressure before adding a new operation.
-     * May pause, throw, or drop depending on strategy.
-     */
-    private checkBackpressure;
-    /**
-     * Check high water mark and emit event if threshold reached.
-     */
-    private checkHighWaterMark;
-    /**
-     * Check low water mark and resume paused writes if threshold reached.
-     */
-    private checkLowWaterMark;
-    /**
-     * Wait for capacity to become available (used by 'pause' strategy).
-     */
-    private waitForCapacity;
-    /**
-     * Drop the oldest pending operation (used by 'drop-oldest' strategy).
-     */
-    private dropOldestOp;
     /**
      * Register a pending Write Concern promise for an operation.
-     * The promise will be resolved when the server sends an ACK with the operation result.
+     * Delegates to WriteConcernManager.
      *
      * @param opId - Operation ID
      * @param timeout - Timeout in ms (default: 5000)
      * @returns Promise that resolves with the Write Concern result
      */
     registerWriteConcernPromise(opId: string, timeout?: number): Promise<any>;
-    /**
-     * Resolve a pending Write Concern promise with the server result.
-     *
-     * @param opId - Operation ID
-     * @param result - Result from server ACK
-     */
-    private resolveWriteConcernPromise;
-    /**
-     * Cancel all pending Write Concern promises (e.g., on disconnect).
-     */
-    private cancelAllWriteConcernPromises;
-    /** Counter update listeners by name */
-    private counterUpdateListeners;
     /**
      * Subscribe to counter updates from server.
+     * Delegates to CounterManager.
      * @param name Counter name
      * @param listener Callback when counter state is updated
      * @returns Unsubscribe function
      */
-    onCounterUpdate(name: string, listener: (state: any) => void): () => void;
+    onCounterUpdate(name: string, listener: (state: {
+        positive: Map<string, number>;
+        negative: Map<string, number>;
+    }) => void): () => void;
     /**
      * Request initial counter state from server.
+     * Delegates to CounterManager.
      * @param name Counter name
      */
     requestCounter(name: string): void;
     /**
      * Sync local counter state to server.
+     * Delegates to CounterManager.
      * @param name Counter name
      * @param state Counter state to sync
      */
-    syncCounter(name: string, state: any): void;
-    /**
-     * Handle incoming counter update from server.
-     * Called by handleServerMessage for COUNTER_UPDATE messages.
-     */
-    private handleCounterUpdate;
-    /** Pending entry processor requests by requestId */
-    private pendingProcessorRequests;
-    /** Pending batch entry processor requests by requestId */
-    private pendingBatchProcessorRequests;
-    /** Default timeout for entry processor requests (ms) */
-    private static readonly PROCESSOR_TIMEOUT;
+    syncCounter(name: string, state: {
+        positive: Map<string, number>;
+        negative: Map<string, number>;
+    }): void;
     /**
      * Execute an entry processor on a single key atomically.
+     * Delegates to EntryProcessorClient.
      *
      * @param mapName Name of the map
      * @param key Key to process
@@ -1187,6 +1168,7 @@ declare class SyncEngine {
     executeOnKey<V, R = V>(mapName: string, key: string, processor: EntryProcessorDef<V, R>): Promise<EntryProcessorResult<R>>;
     /**
      * Execute an entry processor on multiple keys.
+     * Delegates to EntryProcessorClient.
      *
      * @param mapName Name of the map
      * @param keys Keys to process
@@ -1194,16 +1176,6 @@ declare class SyncEngine {
      * @returns Promise resolving to a map of key -> result
      */
     executeOnKeys<V, R = V>(mapName: string, keys: string[], processor: EntryProcessorDef<V, R>): Promise<Map<string, EntryProcessorResult<R>>>;
-    /**
-     * Handle entry processor response from server.
-     * Called by handleServerMessage for ENTRY_PROCESS_RESPONSE messages.
-     */
-    private handleEntryProcessResponse;
-    /**
-     * Handle entry processor batch response from server.
-     * Called by handleServerMessage for ENTRY_PROCESS_BATCH_RESPONSE messages.
-     */
-    private handleEntryProcessBatchResponse;
     /** Message listeners for journal and other generic messages */
     private messageListeners;
     /**
@@ -1213,32 +1185,29 @@ declare class SyncEngine {
      * @param event Event type (currently only 'message')
      * @param handler Message handler
      */
-    on(event: 'message', handler: (message: any) => void): void;
+    on(event: 'message', handler: (message: unknown) => void): void;
     /**
      * Unsubscribe from incoming messages.
      *
      * @param event Event type (currently only 'message')
      * @param handler Message handler to remove
      */
-    off(event: 'message', handler: (message: any) => void): void;
+    off(event: 'message', handler: (message: unknown) => void): void;
     /**
      * Send a message to the server.
      * Public method for EventJournalReader and other components.
      *
      * @param message Message object to send
      */
-    send(message: any): void;
+    send(message: unknown): void;
     /**
      * Emit message to all listeners.
      * Called internally when a message is received.
      */
     private emitMessage;
-    /** Pending search requests by requestId */
-    private pendingSearchRequests;
-    /** Default timeout for search requests (ms) */
-    private static readonly SEARCH_TIMEOUT;
     /**
      * Perform a one-shot BM25 search on the server.
+     * Delegates to SearchClient.
      *
      * @param mapName Name of the map to search
      * @param query Search query text
@@ -1246,33 +1215,24 @@ declare class SyncEngine {
      * @returns Promise resolving to search results
      */
     search<T>(mapName: string, query: string, options?: SearchOptions): Promise<SearchResult<T>[]>;
-    /**
-     * Handle search response from server.
-     */
-    private handleSearchResponse;
     /**
      * Get the conflict resolver client for registering custom resolvers
      * and subscribing to merge rejection events.
      */
     getConflictResolverClient(): ConflictResolverClient;
-    /** Active hybrid query subscriptions */
-    private hybridQueries;
     /**
      * Subscribe to a hybrid query (FTS + filter combination).
+     * Delegates to QueryManager.
      */
     subscribeToHybridQuery<T>(query: HybridQueryHandle<T>): void;
     /**
      * Unsubscribe from a hybrid query.
+     * Delegates to QueryManager.
      */
     unsubscribeFromHybridQuery(queryId: string): void;
-    /**
-     * Send hybrid query subscription to server.
-     */
-    private sendHybridQuerySubscription;
     /**
      * Run a local hybrid query (FTS + filter combination).
-     * For FTS predicates, returns results with score = 0 (local-only mode).
-     * Server provides actual FTS scoring.
+     * Delegates to QueryManager.
      */
     runLocalHybridQuery<T>(mapName: string, filter: HybridQueryFilter): Promise<Array<{
         key: string;
@@ -1283,29 +1243,11 @@ declare class SyncEngine {
     /**
      * Handle hybrid query response from server.
      */
-    handleHybridQueryResponse(payload: {
-        subscriptionId: string;
-        results: Array<{
-            key: string;
-            value: unknown;
-            score: number;
-            matchedTerms: string[];
-        }>;
-        nextCursor?: string;
-        hasMore?: boolean;
-        cursorStatus?: 'valid' | 'expired' | 'invalid' | 'none';
-    }): void;
+    handleHybridQueryResponse(payload: HybridQueryRespPayload): void;
     /**
      * Handle hybrid query delta update from server.
      */
-    handleHybridQueryDelta(payload: {
-        subscriptionId: string;
-        key: string;
-        value: unknown | null;
-        score?: number;
-        matchedTerms?: string[];
-        type: 'ENTER' | 'UPDATE' | 'LEAVE';
-    }): void;
+    handleHybridQueryDelta(payload: HybridQueryDeltaPayload): void;
 }
 
 interface ILock {
@@ -1488,7 +1430,6 @@ declare class EventJournalReader {
  * SearchHandle - Client-side Live Search Subscription Handle
  *
  * Manages a live search subscription with delta updates.
- * Part of Phase 11.1b: Live Search Subscriptions.
  *
  * @module SearchHandle
  */
@@ -2197,8 +2138,6 @@ declare class BackpressureError extends Error {
 /**
  * ConnectionPool - Manages WebSocket connections to multiple cluster nodes
  *
- * Phase 4: Partition-Aware Client Routing
- *
  * Features:
  * - Maintains connections to all known cluster nodes
  * - Automatic reconnection with exponential backoff
@@ -2305,8 +2244,6 @@ declare class ConnectionPool {
 /**
  * PartitionRouter - Routes operations to the correct cluster node
  *
- * Phase 4: Partition-Aware Client Routing
- *
  * Features:
  * - Maintains local copy of partition map
  * - Routes keys to owner nodes using consistent hashing
@@ -2439,9 +2376,7 @@ declare class PartitionRouter {
 /**
  * ClusterClient - Cluster-aware client wrapper
  *
- * Phase 4: Partition-Aware Client Routing
- * Phase 4.5: Implements IConnectionProvider for SyncEngine abstraction
- *
+ * Implements IConnectionProvider for SyncEngine abstraction.
  * Wraps the standard TopGunClient with cluster-aware routing capabilities.
  * Coordinates between ConnectionPool and PartitionRouter for optimal
  * request routing in a clustered environment.
@@ -2572,11 +2507,6 @@ declare class ClusterClient implements IConnectionProvider {
      * Set authentication token
      */
     setAuthToken(token: string): void;
-    /**
-     * Send operation with automatic routing (legacy API for cluster operations).
-     * @deprecated Use send(data, key) for IConnectionProvider interface
-     */
-    sendMessage(key: string, message: any): boolean;
     /**
      * Send directly to partition owner
      */
@@ -2762,6 +2692,207 @@ declare class SingleServerProvider implements IConnectionProvider {
     resetReconnectAttempts(): void;
 }
 
+/**
+ * Configuration for HttpSyncProvider.
+ */
+interface HttpSyncProviderConfig {
+    /** HTTP URL of the TopGun server (e.g., 'http://localhost:8080') */
+    url: string;
+    /** Client identifier for the server to track HLC state */
+    clientId: string;
+    /** Hybrid Logical Clock instance for causality tracking */
+    hlc: HLC;
+    /** JWT auth token for Authorization header */
+    authToken?: string;
+    /** Polling interval in milliseconds (default: 5000) */
+    pollIntervalMs?: number;
+    /** HTTP request timeout in milliseconds (default: 30000) */
+    requestTimeoutMs?: number;
+    /** Map names to sync deltas for on each poll */
+    syncMaps?: string[];
+    /** Custom fetch implementation for testing or platform compatibility */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * HTTP-based connection provider for serverless environments.
+ *
+ * Implements IConnectionProvider by translating WebSocket-style send() calls
+ * into queued operations that are flushed via HTTP POST /sync at regular
+ * polling intervals. Responses are translated back into synthetic message
+ * events that SyncEngine understands.
+ *
+ * This provider is completely stateless on the server side -- each request
+ * carries the client's HLC state and the server computes deltas without
+ * maintaining per-client state.
+ */
+declare class HttpSyncProvider implements IConnectionProvider {
+    private readonly url;
+    private readonly clientId;
+    private readonly hlc;
+    private readonly pollIntervalMs;
+    private readonly requestTimeoutMs;
+    private readonly syncMaps;
+    private readonly fetchImpl;
+    private authToken;
+    private listeners;
+    private pollTimer;
+    /** Queued operations to send on next poll */
+    private pendingOperations;
+    /** Queued one-shot queries to send on next poll */
+    private pendingQueries;
+    /** Per-map last sync timestamps for delta tracking */
+    private lastSyncTimestamps;
+    /** Whether the last HTTP request succeeded */
+    private connected;
+    /** Whether we were previously connected (for reconnected event) */
+    private wasConnected;
+    constructor(config: HttpSyncProviderConfig);
+    /**
+     * Connect by sending an initial sync request to verify auth and get state.
+     */
+    connect(): Promise<void>;
+    /**
+     * Get connection for a specific key.
+     * HTTP mode does not expose raw WebSocket connections.
+     */
+    getConnection(_key: string): WebSocket;
+    /**
+     * Get any available connection.
+     * HTTP mode does not expose raw WebSocket connections.
+     */
+    getAnyConnection(): WebSocket;
+    /**
+     * Check if connected (last HTTP request succeeded).
+     */
+    isConnected(): boolean;
+    /**
+     * Get connected node IDs.
+     * Returns ['http'] when connected, [] when not.
+     */
+    getConnectedNodes(): string[];
+    /**
+     * Subscribe to connection events.
+     */
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Unsubscribe from connection events.
+     */
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    /**
+     * Send data via the HTTP sync provider.
+     *
+     * Deserializes the msgpackr binary to extract the message type and routes:
+     * - OP_BATCH / CLIENT_OP: queued as operations for next poll
+     * - AUTH: silently ignored (auth via HTTP header)
+     * - SYNC_INIT: silently ignored (HTTP uses timestamp-based deltas)
+     * - QUERY_SUB: queued as one-shot query for next poll
+     * - All other types: silently dropped with debug log
+     */
+    send(data: ArrayBuffer | Uint8Array, _key?: string): void;
+    /**
+     * Close the HTTP sync provider.
+     * Stops the polling loop, clears queued operations, and sets disconnected state.
+     */
+    close(): Promise<void>;
+    /**
+     * Update the auth token (e.g., after token refresh).
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Send an HTTP sync request with queued operations and receive deltas.
+     */
+    private doSyncRequest;
+    /**
+     * Start the polling loop.
+     */
+    private startPolling;
+    /**
+     * Stop the polling loop.
+     */
+    private stopPolling;
+    /**
+     * Emit an event to all listeners.
+     */
+    private emit;
+}
+
+/**
+ * Configuration for AutoConnectionProvider.
+ */
+interface AutoConnectionProviderConfig {
+    /** Server URL (ws:// or http://) */
+    url: string;
+    /** Client identifier */
+    clientId: string;
+    /** Hybrid Logical Clock instance */
+    hlc: HLC;
+    /** Max WebSocket connection attempts before falling back to HTTP (default: 3) */
+    maxWsAttempts?: number;
+    /** JWT auth token */
+    authToken?: string;
+    /** Skip WebSocket and go HTTP-only */
+    httpOnly?: boolean;
+    /** HTTP polling interval in ms (default: 5000) */
+    httpPollIntervalMs?: number;
+    /** Map names to sync via HTTP */
+    syncMaps?: string[];
+    /** Custom fetch implementation for HTTP mode */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * AutoConnectionProvider implements protocol negotiation by trying WebSocket
+ * first and falling back to HTTP sync when WebSocket connection fails.
+ *
+ * This enables seamless deployment in both traditional server environments
+ * (using WebSockets) and serverless environments (using HTTP polling).
+ */
+declare class AutoConnectionProvider implements IConnectionProvider {
+    private readonly config;
+    private readonly maxWsAttempts;
+    /** The active underlying provider */
+    private activeProvider;
+    /** Whether we're using HTTP mode */
+    private isHttpMode;
+    private listeners;
+    constructor(config: AutoConnectionProviderConfig);
+    /**
+     * Connect using WebSocket first, falling back to HTTP after maxWsAttempts failures.
+     * If httpOnly is true, skips WebSocket entirely.
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect using HTTP sync provider.
+     */
+    private connectHttp;
+    getConnection(key: string): WebSocket;
+    getAnyConnection(): WebSocket;
+    isConnected(): boolean;
+    getConnectedNodes(): string[];
+    on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
+    send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Close the active underlying provider.
+     */
+    close(): Promise<void>;
+    /**
+     * Whether currently using HTTP mode.
+     */
+    isUsingHttp(): boolean;
+    /**
+     * Proxy events from the underlying provider to our listeners.
+     */
+    private proxyEvents;
+    /**
+     * Convert a URL to WebSocket URL format.
+     */
+    private toWsUrl;
+    /**
+     * Convert a URL to HTTP URL format.
+     */
+    private toHttpUrl;
+}
+
 declare const logger: pino.Logger<never, boolean>;
 
-export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, SingleServerProvider, type SingleServerProviderConfig, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopGunClientConfig, type TopGunClusterConfig, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };
+export { AutoConnectionProvider, type AutoConnectionProviderConfig, type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, HttpSyncProvider, type HttpSyncProviderConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, SingleServerProvider, type SingleServerProviderConfig, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopGunClientConfig, type TopGunClusterConfig, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };