@pooflabs/core 0.0.48 → 0.0.91

package/dist/index.js

@@ -4009,9 +4009,40 @@ async function get(path, opts = {}) {
         }
         // Create a new request promise and store it
         const requestPromise = (async () => {
+            var _a;
             try {
-                // Cache miss or bypass - proceed with API request
+                // For realtime chains, prefer WebSocket reads (lower latency, already connected)
+                const config = await getConfig();
                 const pathIsDocument = normalizedPath.split("/").length % 2 === 0;
+                if (((_a = config.chain) === null || _a === void 0 ? void 0 : _a.startsWith('realtime_')) && !config.isServer && !opts.prompt && !opts.shape && !opts.cursor) {
+                    try {
+                        const { wsGet, wsQuery, hasActiveConnection } = await Promise.resolve().then(function () { return subscriptionV2; });
+                        if (hasActiveConnection()) {
+                            if (pathIsDocument) {
+                                const wsResult = await wsGet(normalizedPath);
+                                const responseData = wsResult;
+                                if (!opts.bypassCache) {
+                                    getCache[cacheKey] = { data: responseData, expiresAt: now + GET_CACHE_TTL };
+                                }
+                                return responseData;
+                            }
+                            else if (!opts.limit) {
+                                const wsResult = await wsQuery(normalizedPath, {
+                                    filter: undefined,
+                                    sort: undefined,
+                                    includeSubPaths: opts.includeSubPaths,
+                                });
+                                const responseData = wsResult;
+                                if (!opts.bypassCache) {
+                                    getCache[cacheKey] = { data: responseData, expiresAt: now + GET_CACHE_TTL };
+                                }
+                                return responseData;
+                            }
+                        }
+                    }
+                    catch ( /* fall through to HTTP */_b) { /* fall through to HTTP */ }
+                }
+                // Cache miss or bypass - proceed with HTTP API request
                 let response;
                 // Build common query params
                 const includeSubPathsParam = opts.includeSubPaths ? '&includeSubPaths=true' : '';
@@ -4020,7 +4051,6 @@ async function get(path, opts = {}) {
                 const cursorParam = opts.cursor ? `&cursor=${encodeURIComponent(opts.cursor)}` : '';
                 if (pathIsDocument) {
                     const itemId = encodeURIComponent(normalizedPath);
-                    // For documents, query params go after the path
                     const queryParams = [includeSubPathsParam, shapeParam].filter(p => p).join('');
                     const apiPath = queryParams ? `items/${itemId}?${queryParams.substring(1)}` : `items/${itemId}`;
                     response = await makeApiRequest('GET', apiPath, null, opts._overrides);
@@ -4215,7 +4245,7 @@ async function set(path, document, options) {
     return result;
 }
 async function setMany(many, options) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     // Returns the data that was set, or undefined if the document was already set.
     try {
         const config = await getConfig();
@@ -4252,13 +4282,28 @@ async function setMany(many, options) {
         }
         let setResponse;
         try {
-            setResponse = await makeApiRequest('PUT', `items`, { documents }, options === null || options === void 0 ? void 0 : options._overrides);
+            // For realtime chains, prefer WebSocket if a connection is active (lower latency)
+            const useWs = ((_c = config.chain) === null || _c === void 0 ? void 0 : _c.startsWith('realtime_')) && !config.isServer;
+            if (useWs) {
+                try {
+                    const { wsSet, hasActiveConnection } = await Promise.resolve().then(function () { return subscriptionV2; });
+                    if (hasActiveConnection()) {
+                        const wsResult = await wsSet(documents);
+                        // Normalize to same shape as HTTP 200 response so downstream handling is identical
+                        setResponse = { data: wsResult, status: 200 };
+                    }
+                }
+                catch ( /* fall through to HTTP */_j) { /* fall through to HTTP */ }
+            }
+            if (!setResponse) {
+                setResponse = await makeApiRequest('PUT', `items`, { documents }, options === null || options === void 0 ? void 0 : options._overrides);
+            }
         }
         catch (error) {
             if ((error === null || error === void 0 ? void 0 : error.statusCode) === 402 && (error === null || error === void 0 ? void 0 : error.error) === 'INSUFFICIENT_BALANCE') {
-                const deficitLamports = Number((_c = error.deficitLamports) !== null && _c !== void 0 ? _c : 0);
-                const deficitSol = Number((_d = error.deficitSol) !== null && _d !== void 0 ? _d : deficitLamports / 1000000000);
-                throw new InsufficientBalanceError(String((_e = error.address) !== null && _e !== void 0 ? _e : ''), Number((_f = error.balanceLamports) !== null && _f !== void 0 ? _f : 0), Number((_g = error.estimatedCostLamports) !== null && _g !== void 0 ? _g : 0), deficitLamports, deficitSol);
+                const deficitLamports = Number((_d = error.deficitLamports) !== null && _d !== void 0 ? _d : 0);
+                const deficitSol = Number((_e = error.deficitSol) !== null && _e !== void 0 ? _e : deficitLamports / 1000000000);
+                throw new InsufficientBalanceError(String((_f = error.address) !== null && _f !== void 0 ? _f : ''), Number((_g = error.balanceLamports) !== null && _g !== void 0 ? _g : 0), Number((_h = error.estimatedCostLamports) !== null && _h !== void 0 ? _h : 0), deficitLamports, deficitSol);
             }
             throw error;
         }
@@ -4302,7 +4347,7 @@ async function setMany(many, options) {
             else if (setResponse.data &&
                 typeof setResponse.data === 'object' &&
                 setResponse.data.success === true) {
-                const _h = setResponse.data, { success: _success } = _h, rest = __rest(_h, ["success"]);
+                const _k = setResponse.data, { success: _success } = _k, rest = __rest(_k, ["success"]);
                 return Object.assign(Object.assign(Object.assign({}, documents.map(d => d.document)), rest), { transactionId: null });
             }
             else {
@@ -4764,6 +4809,7 @@ async function getOrCreateConnection(appId, isServer) {
         subscriptions: new Map(),
         pendingSubscriptions: new Map(),
         pendingUnsubscriptions: new Map(),
+        pendingRequests: new Map(),
         isConnecting: false,
         isConnected: false,
         appId,
@@ -4862,11 +4908,17 @@ async function getOrCreateConnection(appId, isServer) {
             clearInterval(connection.tokenRefreshTimer);
             connection.tokenRefreshTimer = null;
         }
+        // Reject all pending WS CRUD requests on disconnect (fail fast)
+        for (const [id, pending] of connection.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('WebSocket disconnected'));
+        }
+        connection.pendingRequests.clear();
     });
     return connection;
 }
 function handleServerMessage(connection, message) {
-    var _a;
+    var _a, _b;
     switch (message.type) {
         case 'subscribed': {
             const subscription = connection.subscriptions.get(message.subscriptionId);
@@ -4911,8 +4963,45 @@ function handleServerMessage(connection, message) {
             }
             break;
         }
+        case 'response': {
+            const pendingReq = connection.pendingRequests.get(message.requestId);
+            if (pendingReq) {
+                connection.pendingRequests.delete(message.requestId);
+                clearTimeout(pendingReq.timer);
+                if (message.status >= 400) {
+                    pendingReq.reject(new Error(`Request failed with status ${message.status}`));
+                }
+                else {
+                    pendingReq.resolve(message.data);
+                }
+            }
+            break;
+        }
+        case 'setResponse': {
+            const pendingSet = connection.pendingRequests.get(message.requestId);
+            if (pendingSet) {
+                connection.pendingRequests.delete(message.requestId);
+                clearTimeout(pendingSet.timer);
+                if (message.statusCode >= 400) {
+                    pendingSet.reject(new Error(((_a = message.body) === null || _a === void 0 ? void 0 : _a.message) || `Set failed with status ${message.statusCode}`));
+                }
+                else {
+                    pendingSet.resolve(message.body);
+                }
+            }
+            break;
+        }
         case 'error': {
             console.error('[WS v2] Server error:', message.code, message.message);
+            // Handle CRUD request errors (requestId present)
+            if (message.requestId) {
+                const pendingReq = connection.pendingRequests.get(message.requestId);
+                if (pendingReq) {
+                    connection.pendingRequests.delete(message.requestId);
+                    clearTimeout(pendingReq.timer);
+                    pendingReq.reject(new Error(`${message.code}: ${message.message}`));
+                }
+            }
             if (message.subscriptionId) {
                 // Reject pending subscription if this is a subscription error
                 const pending = connection.pendingSubscriptions.get(message.subscriptionId);
@@ -4924,7 +5013,7 @@ function handleServerMessage(connection, message) {
                 const subscription = connection.subscriptions.get(message.subscriptionId);
                 if (subscription) {
                     for (const callback of subscription.callbacks) {
-                        (_a = callback.onError) === null || _a === void 0 ? void 0 : _a.call(callback, new Error(`${message.code}: ${message.message}`));
+                        (_b = callback.onError) === null || _b === void 0 ? void 0 : _b.call(callback, new Error(`${message.code}: ${message.message}`));
                     }
                 }
             }
@@ -5213,6 +5302,112 @@ async function doReconnectWithNewAuth() {
         }
     }
 }
+// ============ CRUD over WebSocket ============
+const WS_REQUEST_TIMEOUT_MS = 30000;
+function generateRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+/**
+ * Returns true if there is an active v2 WebSocket connection open.
+ */
+function hasActiveConnection() {
+    for (const connection of connections.values()) {
+        if (connection.ws && connection.isConnected) {
+            return true;
+        }
+    }
+    return false;
+}
+async function sendRequest(msgBuilder) {
+    const config = await getConfig();
+    const appId = config.appId;
+    const connection = await getOrCreateConnection(appId, config.isServer);
+    // Wait for the connection to be open (getOrCreateConnection may return
+    // while still connecting).
+    if (!connection.isConnected && connection.ws) {
+        await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                var _a;
+                (_a = connection.ws) === null || _a === void 0 ? void 0 : _a.removeEventListener('open', onOpen);
+                reject(new Error('WebSocket connection timeout'));
+            }, 10000);
+            const onOpen = () => { clearTimeout(timeout); resolve(); };
+            if (connection.isConnected) {
+                clearTimeout(timeout);
+                resolve();
+                return;
+            }
+            connection.ws.addEventListener('open', onOpen);
+        });
+    }
+    if (!connection.ws || !connection.isConnected) {
+        throw new Error('WebSocket connection not available');
+    }
+    const requestId = generateRequestId();
+    const message = msgBuilder(requestId);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            connection.pendingRequests.delete(requestId);
+            reject(new Error(`WebSocket request timed out after ${WS_REQUEST_TIMEOUT_MS}ms`));
+        }, WS_REQUEST_TIMEOUT_MS);
+        connection.pendingRequests.set(requestId, { resolve, reject, timer });
+        try {
+            connection.ws.send(JSON.stringify(message));
+        }
+        catch (error) {
+            connection.pendingRequests.delete(requestId);
+            clearTimeout(timer);
+            reject(error);
+        }
+    });
+}
+async function wsGet(path) {
+    return sendRequest((requestId) => ({
+        type: 'get',
+        requestId,
+        path,
+    }));
+}
+async function wsSet(documents) {
+    return sendRequest((requestId) => ({
+        type: 'set',
+        requestId,
+        documents,
+    }));
+}
+async function wsQuery(path, opts) {
+    return sendRequest((requestId) => (Object.assign(Object.assign(Object.assign(Object.assign({ type: 'query', requestId,
+        path }, ((opts === null || opts === void 0 ? void 0 : opts.filter) ? { filter: opts.filter } : {})), ((opts === null || opts === void 0 ? void 0 : opts.sort) ? { sort: opts.sort } : {})), ((opts === null || opts === void 0 ? void 0 : opts.limit) !== undefined ? { limit: opts.limit } : {})), ((opts === null || opts === void 0 ? void 0 : opts.includeSubPaths) ? { includeSubPaths: opts.includeSubPaths } : {}))));
+}
+async function wsDelete(path) {
+    return sendRequest((requestId) => ({
+        type: 'delete',
+        requestId,
+        path,
+    }));
+}
+async function wsGetMany(paths) {
+    return sendRequest((requestId) => ({
+        type: 'getMany',
+        requestId,
+        paths,
+    }));
+}
+
+var subscriptionV2 = /*#__PURE__*/Object.freeze({
+	__proto__: null,
+	clearCacheV2: clearCacheV2,
+	closeAllSubscriptionsV2: closeAllSubscriptionsV2,
+	getCachedDataV2: getCachedDataV2,
+	hasActiveConnection: hasActiveConnection,
+	reconnectWithNewAuthV2: reconnectWithNewAuthV2,
+	subscribeV2: subscribeV2,
+	wsDelete: wsDelete,
+	wsGet: wsGet,
+	wsGetMany: wsGetMany,
+	wsQuery: wsQuery,
+	wsSet: wsSet
+});
 
 /**
  * WebSocket Subscription Module
@@ -5467,8 +5662,789 @@ class ReactNativeSessionManager {
 }
 ReactNativeSessionManager.TAROBASE_SESSION_STORAGE_KEY = "tarobase_session_storage";
 
+// ---------------------------------------------------------------------------
+// realtime-store.ts — Client-side state manager for realtime apps.
+//
+// Manages: WS connection, in-memory state, IDB persistence, optimistic
+// writes, delta accumulation, loading states, ephemeral/durable tiers.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// IDB helpers (lazy-loaded, non-blocking)
+// ---------------------------------------------------------------------------
+const IDB_NAME = 'tarobase-realtime';
+const IDB_STORE = 'subscriptions';
+const IDB_VERSION = 1;
+let idbPromise = null;
+function getIDB() {
+    if (idbPromise)
+        return idbPromise;
+    if (typeof indexedDB === 'undefined') {
+        return Promise.reject(new Error('IndexedDB not available'));
+    }
+    idbPromise = new Promise((resolve, reject) => {
+        const req = indexedDB.open(IDB_NAME, IDB_VERSION);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(IDB_STORE)) {
+                db.createObjectStore(IDB_STORE);
+            }
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+    return idbPromise;
+}
+async function idbGet(key) {
+    try {
+        const db = await getIDB();
+        return new Promise((resolve) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const store = tx.objectStore(IDB_STORE);
+            const req = store.get(key);
+            req.onsuccess = () => { var _a; return resolve((_a = req.result) !== null && _a !== void 0 ? _a : null); };
+            req.onerror = () => resolve(null);
+        });
+    }
+    catch (_a) {
+        return null;
+    }
+}
+async function idbSet(key, value) {
+    try {
+        const db = await getIDB();
+        return new Promise((resolve) => {
+            const tx = db.transaction(IDB_STORE, 'readwrite');
+            const store = tx.objectStore(IDB_STORE);
+            store.put(value, key);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => resolve();
+        });
+    }
+    catch (_a) {
+        // Best-effort persistence
+    }
+}
+// ---------------------------------------------------------------------------
+// RealtimeStore
+// ---------------------------------------------------------------------------
+let nextRequestId = 1;
+class RealtimeStore {
+    constructor() {
+        this.ws = null;
+        this.wsUrl = '';
+        this.appId = '';
+        this.subscriptions = new Map();
+        this.pendingRequests = new Map();
+        this.connectPromise = null;
+        this.reconnectTimer = null;
+        this.reconnectDelay = 1000;
+        this.maxReconnectDelay = 30000;
+        this.idbFlushTimer = null;
+        this.idbDirtyKeys = new Set();
+        this.closed = false;
+        this.authToken = null;
+    }
+    // -----------------------------------------------------------------------
+    // Initialization
+    // -----------------------------------------------------------------------
+    async init() {
+        var _a, _b;
+        const config = await getConfig();
+        this.appId = config.appId;
+        this.wsUrl = config.wsApiUrl;
+        if (config.authProvider) {
+            try {
+                const headers = await ((_b = (_a = config.authProvider).getAuthHeaders) === null || _b === void 0 ? void 0 : _b.call(_a));
+                if (headers === null || headers === void 0 ? void 0 : headers.Authorization) {
+                    this.authToken = headers.Authorization.replace('Bearer ', '');
+                }
+            }
+            catch ( /* no auth */_c) { /* no auth */ }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // WebSocket connection
+    // -----------------------------------------------------------------------
+    async ensureConnected() {
+        var _a;
+        if (((_a = this.ws) === null || _a === void 0 ? void 0 : _a.readyState) === WebSocket.OPEN)
+            return;
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.connectPromise = this.connect();
+        return this.connectPromise;
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            if (this.closed) {
+                reject(new Error('Store closed'));
+                return;
+            }
+            const params = new URLSearchParams();
+            params.set('apiKey', this.appId);
+            // Auth token sent via subprotocol to avoid leaking in URL/logs
+            const url = `${this.wsUrl}?${params.toString()}`;
+            const protocols = this.authToken ? [`bearer-${this.authToken}`] : undefined;
+            const ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);
+            this.ws = ws;
+            const onOpen = () => {
+                ws.removeEventListener('error', onError);
+                this.reconnectDelay = 1000;
+                this.connectPromise = null;
+                this.resubscribeAll();
+                resolve();
+            };
+            const onError = (e) => {
+                ws.removeEventListener('open', onOpen);
+                this.connectPromise = null;
+                reject(new Error('WebSocket connection failed'));
+            };
+            ws.addEventListener('open', onOpen, { once: true });
+            ws.addEventListener('error', onError, { once: true });
+            ws.addEventListener('message', (event) => {
+                this.handleMessage(event.data);
+            });
+            ws.addEventListener('close', () => {
+                this.ws = null;
+                this.connectPromise = null;
+                this.rejectAllPending('WebSocket closed');
+                this.setAllSubscriptionStatus('reconnecting');
+                this.scheduleReconnect();
+            });
+        });
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = setTimeout(() => {
+            this.ensureConnected().catch(() => {
+                this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
+                this.scheduleReconnect();
+            });
+        }, this.reconnectDelay);
+    }
+    resubscribeAll() {
+        for (const sub of this.subscriptions.values()) {
+            this.sendSubscribe(sub);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Message handling
+    // -----------------------------------------------------------------------
+    handleMessage(raw) {
+        const text = typeof raw === 'string' ? raw : new TextDecoder().decode(raw);
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch (_a) {
+            return;
+        }
+        switch (msg.type) {
+            case 'snapshot':
+                this.handleSnapshot(msg);
+                break;
+            case 'delta':
+                this.handleDelta(msg);
+                break;
+            case 'result':
+                this.handleResult(msg);
+                break;
+            case 'error':
+                this.handleError(msg);
+                break;
+            case 'pong':
+                break;
+            // v1 compat: handle legacy message types during transition
+            case 'subscribed':
+                this.handleSnapshot(Object.assign(Object.assign({}, msg), { type: 'snapshot', docs: msg.data }));
+                break;
+            case 'data':
+                // Legacy full-snapshot delta — treat as snapshot replacement
+                this.handleLegacyData(msg);
+                break;
+            case 'response':
+                this.handleResult(Object.assign(Object.assign({}, msg), { type: 'result', ok: msg.status === 200, doc: msg.data }));
+                break;
+        }
+    }
+    handleSnapshot(msg) {
+        var _a, _b, _c;
+        const subId = (_a = msg.id) !== null && _a !== void 0 ? _a : msg.subscriptionId;
+        if (!subId)
+            return;
+        const sub = this.findSubscriptionById(subId);
+        if (!sub)
+            return;
+        const docs = (_c = (_b = msg.docs) !== null && _b !== void 0 ? _b : msg.data) !== null && _c !== void 0 ? _c : [];
+        const docsArray = Array.isArray(docs) ? docs : [docs];
+        sub.docs.clear();
+        for (const doc of docsArray) {
+            if (doc && doc._id) {
+                sub.docs.set(doc._id, doc);
+            }
+        }
+        sub.ref.current = sub.docs;
+        sub.status = 'live';
+        sub.isStale = false;
+        sub.error = null;
+        this.notifySubscription(sub);
+        this.markIdbDirty(sub.path);
+    }
+    handleDelta(msg) {
+        var _a, _b;
+        const subId = (_a = msg.id) !== null && _a !== void 0 ? _a : msg.subscriptionId;
+        if (!subId)
+            return;
+        const sub = this.findSubscriptionById(subId);
+        if (!sub)
+            return;
+        if (sub.tier === 'ephemeral') {
+            // Ephemeral: just overwrite, no accumulation logic
+            if (msg.change === 'removed' && msg.docId) {
+                sub.docs.delete(msg.docId);
+            }
+            else if (msg.doc && msg.doc._id) {
+                sub.docs.set(msg.doc._id, msg.doc);
+            }
+            sub.ref.current = sub.docs;
+            if (sub.options.mode !== 'ref') {
+                this.notifySubscription(sub);
+            }
+            return;
+        }
+        // Durable/checkpointed: full delta handling
+        switch (msg.change) {
+            case 'added':
+            case 'modified':
+                if (msg.doc && msg.doc._id) {
+                    sub.docs.set(msg.doc._id, msg.doc);
+                }
+                break;
+            case 'removed':
+                if (msg.docId) {
+                    sub.docs.delete(msg.docId);
+                }
+                else if ((_b = msg.doc) === null || _b === void 0 ? void 0 : _b._id) {
+                    sub.docs.delete(msg.doc._id);
+                }
+                break;
+        }
+        sub.ref.current = sub.docs;
+        this.notifySubscription(sub);
+        this.markIdbDirty(sub.path);
+    }
+    handleLegacyData(msg) {
+        // Legacy v1 format: 'data' message with full snapshot or single doc
+        const subId = msg.subscriptionId;
+        if (!subId)
+            return;
+        const sub = this.findSubscriptionById(subId);
+        if (!sub)
+            return;
+        if (Array.isArray(msg.data)) {
+            // Full snapshot replacement
+            sub.docs.clear();
+            for (const doc of msg.data) {
+                if (doc && doc._id)
+                    sub.docs.set(doc._id, doc);
+            }
+        }
+        else if (msg.data && msg.data._id) {
+            // Single doc update
+            sub.docs.set(msg.data._id, msg.data);
+        }
+        else if (msg.data === null) ;
+        sub.ref.current = sub.docs;
+        sub.status = 'live';
+        sub.isStale = false;
+        this.notifySubscription(sub);
+        this.markIdbDirty(sub.path);
+    }
+    handleResult(msg) {
+        var _a, _b, _c, _d;
+        const requestId = msg.requestId;
+        if (!requestId)
+            return;
+        const pending = this.pendingRequests.get(requestId);
+        if (!pending)
+            return;
+        this.pendingRequests.delete(requestId);
+        clearTimeout(pending.timeout);
+        const ok = (_a = msg.ok) !== null && _a !== void 0 ? _a : (msg.status === 200);
+        if (ok) {
+            pending.resolve((_c = (_b = msg.doc) !== null && _b !== void 0 ? _b : msg.data) !== null && _c !== void 0 ? _c : true);
+        }
+        else {
+            pending.reject(new Error((_d = msg.error) !== null && _d !== void 0 ? _d : 'Operation failed'));
+        }
+    }
+    handleError(msg) {
+        var _a;
+        const requestId = msg.requestId;
+        if (requestId) {
+            const pending = this.pendingRequests.get(requestId);
+            if (pending) {
+                this.pendingRequests.delete(requestId);
+                clearTimeout(pending.timeout);
+                pending.reject(new Error((_a = msg.message) !== null && _a !== void 0 ? _a : 'Server error'));
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Subscribe
+    // -----------------------------------------------------------------------
+    async subscribe(path, opts = {}) {
+        var _a;
+        const tier = (_a = opts.tier) !== null && _a !== void 0 ? _a : 'durable';
+        const subKey = this.getSubKey(path, opts);
+        let sub = this.subscriptions.get(subKey);
+        if (sub) {
+            // Existing subscription — add callback
+            if (opts.onData)
+                sub.callbacks.add(opts.onData);
+            if (opts.onState)
+                sub.stateCallbacks.add(opts.onState);
+            // Immediately deliver current state
+            if (opts.onData && sub.docs.size > 0) {
+                opts.onData(this.docsToArray(sub));
+            }
+            if (opts.onState) {
+                opts.onState(this.getState(sub));
+            }
+            return this.createUnsubscribe(subKey, opts.onData, opts.onState);
+        }
+        // New subscription
+        const subId = `sub_${nextRequestId++}`;
+        sub = {
+            id: subId,
+            path,
+            tier,
+            options: opts,
+            docs: new Map(),
+            status: 'idle',
+            isStale: false,
+            error: null,
+            callbacks: new Set(opts.onData ? [opts.onData] : []),
+            stateCallbacks: new Set(opts.onState ? [opts.onState] : []),
+            ref: { current: new Map() },
+        };
+        this.subscriptions.set(subKey, sub);
+        // Step 1: Load from IDB (durable/checkpointed only)
+        if (tier !== 'ephemeral') {
+            const cached = await idbGet(this.idbKey(path));
+            if (cached && Array.isArray(cached)) {
+                for (const doc of cached) {
+                    if (doc && doc._id)
+                        sub.docs.set(doc._id, doc);
+                }
+                sub.ref.current = sub.docs;
+                sub.status = 'cached';
+                sub.isStale = true;
+                this.notifySubscription(sub);
+            }
+        }
+        // Step 2: Connect and subscribe via WS
+        sub.status = sub.docs.size > 0 ? 'cached' : 'loading';
+        this.notifyState(sub);
+        try {
+            await this.ensureConnected();
+            this.sendSubscribe(sub);
+        }
+        catch (_b) {
+            sub.status = 'error';
+            sub.error = new Error('Connection failed');
+            this.notifyState(sub);
+        }
+        return this.createUnsubscribe(subKey, opts.onData, opts.onState);
+    }
+    getRef(path, opts = {}) {
+        var _a;
+        const subKey = this.getSubKey(path, opts);
+        const sub = this.subscriptions.get(subKey);
+        if (sub)
+            return sub.ref;
+        // Auto-subscribe in ref mode
+        const ref = { current: new Map() };
+        this.subscribe(path, Object.assign(Object.assign({}, opts), { mode: 'ref', tier: 'ephemeral' })).catch(() => { });
+        const newSub = this.subscriptions.get(this.getSubKey(path, Object.assign(Object.assign({}, opts), { tier: 'ephemeral' })));
+        return (_a = newSub === null || newSub === void 0 ? void 0 : newSub.ref) !== null && _a !== void 0 ? _a : ref;
+    }
+    // -----------------------------------------------------------------------
+    // CRUD operations
+    // -----------------------------------------------------------------------
+    async set(path, doc) {
+        var _a;
+        await this.ensureConnected();
+        // Resolve operations (Increment, Time.Now) client-side for optimistic update
+        const resolvedDoc = this.resolveOperations(doc, path);
+        // Optimistic update: apply to local state immediately
+        const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+        const collectionPath = this.getCollectionPath(normalizedPath);
+        const optimisticDoc = Object.assign(Object.assign({ _id: normalizedPath, pathId: normalizedPath }, resolvedDoc), { tarobase_updated_at: Date.now() });
+        const sub = this.findSubscriptionByPath(collectionPath);
+        let prevDoc = null;
+        if (sub) {
+            prevDoc = (_a = sub.docs.get(normalizedPath)) !== null && _a !== void 0 ? _a : null;
+            sub.docs.set(normalizedPath, optimisticDoc);
+            sub.ref.current = sub.docs;
+            this.notifySubscription(sub);
+        }
+        // Send to server
+        const requestId = `r_${nextRequestId++}`;
+        try {
+            const result = await this.sendRequest(requestId, {
+                type: 'set',
+                requestId,
+                documents: [{ destinationPath: normalizedPath, document: doc }],
+            });
+            // Replace optimistic doc with server-confirmed version
+            if (sub && result && typeof result === 'object') {
+                const serverDoc = Array.isArray(result) ? result[0] : result;
+                if (serverDoc && serverDoc._id) {
+                    sub.docs.set(serverDoc._id, serverDoc);
+                    sub.ref.current = sub.docs;
+                    this.notifySubscription(sub);
+                    this.markIdbDirty(collectionPath);
+                }
+            }
+            return Array.isArray(result) ? result[0] : result;
+        }
+        catch (err) {
+            // Revert optimistic update
+            if (sub) {
+                if (prevDoc) {
+                    sub.docs.set(normalizedPath, prevDoc);
+                }
+                else {
+                    sub.docs.delete(normalizedPath);
+                }
+                sub.ref.current = sub.docs;
+                this.notifySubscription(sub);
+            }
+            throw err;
+        }
+    }
+    async get(path) {
+        const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+        // Check local subscriptions first
+        const collectionPath = this.getCollectionPath(normalizedPath);
+        const sub = this.findSubscriptionByPath(collectionPath);
+        if (sub && sub.status === 'live') {
+            const doc = sub.docs.get(normalizedPath);
+            return doc !== null && doc !== void 0 ? doc : null;
+        }
+        // One-shot WS fetch
+        await this.ensureConnected();
+        const requestId = `r_${nextRequestId++}`;
+        return this.sendRequest(requestId, {
+            type: 'get',
+            requestId,
+            path: normalizedPath,
+        });
+    }
+    async getMany(paths) {
+        await this.ensureConnected();
+        const normalizedPaths = paths.map(p => p.startsWith('/') ? p.slice(1) : p);
+        const requestId = `r_${nextRequestId++}`;
+        return this.sendRequest(requestId, {
+            type: 'getMany',
+            requestId,
+            paths: normalizedPaths,
+        });
+    }
+    async delete(path) {
+        var _a;
+        await this.ensureConnected();
+        const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+        // Optimistic: remove from local state
+        const collectionPath = this.getCollectionPath(normalizedPath);
+        const sub = this.findSubscriptionByPath(collectionPath);
+        let prevDoc = null;
+        if (sub) {
+            prevDoc = (_a = sub.docs.get(normalizedPath)) !== null && _a !== void 0 ? _a : null;
+            sub.docs.delete(normalizedPath);
+            sub.ref.current = sub.docs;
+            this.notifySubscription(sub);
+        }
+        const requestId = `r_${nextRequestId++}`;
+        try {
+            await this.sendRequest(requestId, {
+                type: 'delete',
+                requestId,
+                path: normalizedPath,
+            });
+            if (sub)
+                this.markIdbDirty(collectionPath);
+        }
+        catch (err) {
+            // Revert
+            if (sub && prevDoc) {
+                sub.docs.set(normalizedPath, prevDoc);
+                sub.ref.current = sub.docs;
+                this.notifySubscription(sub);
+            }
+            throw err;
+        }
+    }
+    async query(path, opts) {
+        await this.ensureConnected();
+        const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+        const requestId = `r_${nextRequestId++}`;
+        return this.sendRequest(requestId, Object.assign(Object.assign(Object.assign(Object.assign({ type: 'query', requestId, path: normalizedPath }, ((opts === null || opts === void 0 ? void 0 : opts.filter) ? { filter: opts.filter } : {})), ((opts === null || opts === void 0 ? void 0 : opts.sort) ? { sort: opts.sort } : {})), ((opts === null || opts === void 0 ? void 0 : opts.limit) !== undefined ? { limit: opts.limit } : {})), ((opts === null || opts === void 0 ? void 0 : opts.includeSubPaths) ? { includeSubPaths: true } : {})));
+    }
+    async count(path) {
+        var _a;
+        await this.ensureConnected();
+        const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+        const requestId = `r_${nextRequestId++}`;
+        const result = await this.sendRequest(requestId, {
+            type: 'count',
+            requestId,
+            path: normalizedPath,
+        });
+        return typeof result === 'number' ? result : ((_a = result === null || result === void 0 ? void 0 : result.value) !== null && _a !== void 0 ? _a : 0);
+    }
+    async aggregate(path, operation, opts) {
+        await this.ensureConnected();
+        const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+        const requestId = `r_${nextRequestId++}`;
+        return this.sendRequest(requestId, Object.assign({ type: 'aggregate', requestId, path: normalizedPath, operation }, ((opts === null || opts === void 0 ? void 0 : opts.field) ? { field: opts.field } : {})));
+    }
+    // -----------------------------------------------------------------------
+    // Helpers
+    // -----------------------------------------------------------------------
+    sendSubscribe(sub) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        const msg = {
+            type: 'subscribe',
+            subscriptionId: sub.id,
+            path: sub.path,
+        };
+        if (sub.options.filter)
+            msg.filter = sub.options.filter;
+        if (sub.options.includeSubPaths)
+            msg.includeSubPaths = true;
+        if (sub.options.limit)
+            msg.limit = sub.options.limit;
+        if (sub.options.prompt)
+            msg.prompt = sub.options.prompt;
+        this.ws.send(JSON.stringify(msg));
+    }
+    sendRequest(requestId, msg) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(new Error('Request timed out'));
+            }, 30000);
+            this.pendingRequests.set(requestId, { resolve, reject, timeout });
+            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                this.ws.send(JSON.stringify(msg));
+            }
+            else {
+                this.pendingRequests.delete(requestId);
+                clearTimeout(timeout);
+                reject(new Error('WebSocket not connected'));
+            }
+        });
+    }
+    notifySubscription(sub) {
+        const data = this.docsToArray(sub);
+        const callbacks = Array.from(sub.callbacks);
+        for (const cb of callbacks) {
+            try {
+                cb(data);
+            }
+            catch ( /* swallow callback errors */_a) { /* swallow callback errors */ }
+        }
+        this.notifyState(sub);
+    }
+    notifyState(sub) {
+        const state = this.getState(sub);
+        const callbacks = Array.from(sub.stateCallbacks);
+        for (const cb of callbacks) {
+            try {
+                cb(state);
+            }
+            catch ( /* swallow */_a) { /* swallow */ }
+        }
+    }
+    getState(sub) {
+        return {
+            data: this.docsToArray(sub),
+            status: sub.status,
+            isStale: sub.isStale,
+            error: sub.error,
+        };
+    }
+    docsToArray(sub) {
+        return Array.from(sub.docs.values());
+    }
+    findSubscriptionById(id) {
+        for (const sub of this.subscriptions.values()) {
+            if (sub.id === id)
+                return sub;
+        }
+        return undefined;
+    }
+    findSubscriptionByPath(collectionPath) {
+        for (const sub of this.subscriptions.values()) {
+            const subPath = sub.path.startsWith('/') ? sub.path.slice(1) : sub.path;
+            if (subPath === collectionPath)
+                return sub;
+            if (collectionPath.startsWith(subPath + '/'))
+                return sub;
+        }
+        return undefined;
+    }
+    getCollectionPath(docPath) {
+        const segments = docPath.split('/');
+        if (segments.length % 2 === 0) {
+            return segments.slice(0, -1).join('/');
+        }
+        return docPath;
+    }
+    getSubKey(path, opts) {
+        const parts = [path];
+        if (opts.filter)
+            parts.push(JSON.stringify(opts.filter));
+        if (opts.prompt)
+            parts.push(opts.prompt);
+        if (opts.tier)
+            parts.push(opts.tier);
+        return parts.join('::');
+    }
+    idbKey(path) {
+        return `${this.appId}:${path}`;
+    }
+    markIdbDirty(path) {
+        const sub = this.findSubscriptionByPath(path);
+        if (sub && sub.tier === 'ephemeral')
+            return;
+        this.idbDirtyKeys.add(path);
+        if (!this.idbFlushTimer) {
+            this.idbFlushTimer = setTimeout(() => {
+                this.flushIdb();
+                this.idbFlushTimer = null;
+            }, 500);
+        }
+    }
+    async flushIdb() {
+        const keys = Array.from(this.idbDirtyKeys);
+        this.idbDirtyKeys.clear();
+        for (const path of keys) {
+            const sub = this.findSubscriptionByPath(path);
+            if (sub && sub.tier !== 'ephemeral') {
+                const docs = this.docsToArray(sub);
+                await idbSet(this.idbKey(path), docs);
+            }
+        }
+    }
+    createUnsubscribe(subKey, onData, onState) {
+        return async () => {
+            const sub = this.subscriptions.get(subKey);
+            if (!sub)
+                return;
+            if (onData)
+                sub.callbacks.delete(onData);
+            if (onState)
+                sub.stateCallbacks.delete(onState);
+            // If no more callbacks, unsubscribe entirely
+            if (sub.callbacks.size === 0 && sub.stateCallbacks.size === 0) {
+                this.subscriptions.delete(subKey);
+                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                    this.ws.send(JSON.stringify({
+                        type: 'unsubscribe',
+                        subscriptionId: sub.id,
+                    }));
+                }
+            }
+        };
+    }
+    resolveOperations(doc, path) {
+        var _a;
+        if (!doc || typeof doc !== 'object')
+            return doc;
+        const resolved = {};
+        for (const [key, value] of Object.entries(doc)) {
+            if (value && typeof value === 'object' && !Array.isArray(value) && value.operation) {
+                const op = value;
+                if (op.operation === 'time' && op.value === 'now') {
+                    resolved[key] = Math.floor(Date.now() / 1000);
+                }
+                else if (op.operation === 'increment') {
+                    // For optimistic: get current value and add
+                    const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+                    const collectionPath = this.getCollectionPath(normalizedPath);
+                    const sub = this.findSubscriptionByPath(collectionPath);
+                    const existing = sub === null || sub === void 0 ? void 0 : sub.docs.get(normalizedPath);
+                    const current = (_a = existing === null || existing === void 0 ? void 0 : existing[key]) !== null && _a !== void 0 ? _a : 0;
+                    resolved[key] = (typeof current === 'number' ? current : 0) + op.value;
+                }
+                else {
+                    resolved[key] = value;
+                }
+            }
+            else {
+                resolved[key] = value;
+            }
+        }
+        return resolved;
+    }
+    rejectAllPending(reason) {
+        for (const [requestId, pending] of this.pendingRequests) {
+            clearTimeout(pending.timeout);
+            pending.reject(new Error(reason));
+        }
+        this.pendingRequests.clear();
+    }
+    setAllSubscriptionStatus(status) {
+        for (const sub of this.subscriptions.values()) {
+            sub.status = status;
+            this.notifyState(sub);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Lifecycle
+    // -----------------------------------------------------------------------
+    close() {
+        this.closed = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        if (this.idbFlushTimer)
+            clearTimeout(this.idbFlushTimer);
+        this.flushIdb();
+        if (this.ws) {
+            this.ws.close(1000, 'Store closed');
+            this.ws = null;
+        }
+        this.rejectAllPending('Store closed');
+        this.subscriptions.clear();
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton instance
+// ---------------------------------------------------------------------------
+let storeInstance = null;
+function getRealtimeStore() {
+    if (!storeInstance) {
+        storeInstance = new RealtimeStore();
+    }
+    return storeInstance;
+}
+function resetRealtimeStore() {
+    if (storeInstance) {
+        storeInstance.close();
+        storeInstance = null;
+    }
+}
+
 exports.InsufficientBalanceError = InsufficientBalanceError;
 exports.ReactNativeSessionManager = ReactNativeSessionManager;
+exports.RealtimeStore = RealtimeStore;
 exports.ServerSessionManager = ServerSessionManager;
 exports.WebSessionManager = WebSessionManager;
 exports.aggregate = aggregate;
@@ -5487,9 +6463,12 @@ exports.getConfig = getConfig;
 exports.getFiles = getFiles;
 exports.getIdToken = getIdToken;
 exports.getMany = getMany;
+exports.getRealtimeStore = getRealtimeStore;
+exports.hasActiveConnection = hasActiveConnection;
 exports.init = init;
 exports.reconnectWithNewAuth = reconnectWithNewAuth;
 exports.refreshSession = refreshSession;
+exports.resetRealtimeStore = resetRealtimeStore;
 exports.runExpression = runExpression;
 exports.runExpressionMany = runExpressionMany;
 exports.runQuery = runQuery;
@@ -5502,4 +6481,9 @@ exports.signMessage = signMessage;
 exports.signSessionCreateMessage = signSessionCreateMessage;
 exports.signTransaction = signTransaction;
 exports.subscribe = subscribe;
+exports.wsDelete = wsDelete;
+exports.wsGet = wsGet;
+exports.wsGetMany = wsGetMany;
+exports.wsQuery = wsQuery;
+exports.wsSet = wsSet;
 //# sourceMappingURL=index.js.map