@pooflabs/core 0.0.31 → 0.0.33

package/dist/client/operations.d.ts

@@ -17,6 +17,10 @@ export type GetOptions = {
     includeSubPaths?: boolean;
     /** Shape object for relationship resolution - specifies which related documents to include */
     shape?: Record<string, any>;
+    /** Maximum number of items to return (opt-in pagination) */
+    limit?: number;
+    /** Opaque cursor for cursor-based pagination (used with limit) */
+    cursor?: string;
     /** Internal overrides for headers */
     _overrides?: {
         headers?: Record<string, string>;
@@ -27,6 +31,79 @@ export type RunQueryOptions = {
         headers?: Record<string, string>;
     };
 };
+/**
+ * Supported aggregate operations for count/aggregate queries.
+ */
+export type AggregateOperation = 'count' | 'uniqueCount' | 'sum' | 'avg' | 'min' | 'max';
+/**
+ * Result of a count or aggregate query — always a single numeric value.
+ */
+export type AggregateResult = {
+    value: number;
+};
+/**
+ * Options for the count function.
+ */
+export type CountOptions = {
+    /** Natural language filter prompt (e.g., "posts created in the last 7 days") */
+    prompt?: string;
+    /** Internal overrides for headers */
+    _overrides?: {
+        headers?: Record<string, string>;
+    };
+};
+/**
+ * Options for the aggregate function.
+ */
+export type AggregateOptions = {
+    /** Natural language filter prompt */
+    prompt?: string;
+    /** Field name to aggregate on (required for sum, avg, min, max) */
+    field?: string;
+    /** Internal overrides for headers */
+    _overrides?: {
+        headers?: Record<string, string>;
+    };
+};
+/**
+ * Count items in a collection path. Returns a numeric result.
+ *
+ * This uses the AI query engine with a count-specific prompt prefix,
+ * so TaroBase will generate a $count aggregation pipeline and return
+ * just the count rather than full documents.
+ *
+ * IMPORTANT: This only works for collections where the read policy is "true".
+ * If the read policy requires per-document checks, the server will return
+ * an error because aggregate counts cannot be performed without pulling all
+ * documents for access control evaluation.
+ *
+ * @param path - Collection path (e.g., "posts", "users/abc/comments")
+ * @param opts - Optional filter prompt and overrides
+ * @returns AggregateResult with the count value
+ */
+export declare function count(path: string, opts?: CountOptions): Promise<AggregateResult>;
+/**
+ * Run an aggregate operation on a collection path. Returns a numeric result.
+ *
+ * Supported operations:
+ * - count: Total number of documents
+ * - uniqueCount: Number of distinct values for a field
+ * - sum: Sum of a numeric field
+ * - avg: Average of a numeric field
+ * - min: Minimum value of a numeric field
+ * - max: Maximum value of a numeric field
+ *
+ * IMPORTANT: This only works for collections where the read policy is "true".
+ * If the read policy requires per-document checks, the server will return
+ * an error because aggregate operations cannot be performed without pulling
+ * all documents for access control evaluation.
+ *
+ * @param path - Collection path (e.g., "posts", "users/abc/comments")
+ * @param operation - The aggregate operation to perform
+ * @param opts - Options including optional filter prompt and field name
+ * @returns AggregateResult with the computed numeric value
+ */
+export declare function aggregate(path: string, operation: AggregateOperation, opts?: AggregateOptions): Promise<AggregateResult>;
 export declare function get(path: string, opts?: GetOptions): Promise<any>;
 export type RunExpressionOptions = {
     returnType?: 'Bool' | 'String' | 'Int' | 'UInt';
@@ -66,8 +143,16 @@ export declare function setMany(many: {
 export declare function clearCache(path?: string, opts?: {
     prompt?: string;
 }): void;
-export declare function getFiles(path: string): Promise<any>;
-export declare function setFile(path: string, file: File | null): Promise<boolean>;
+export declare function getFiles(path: string, options?: {
+    _overrides?: {
+        headers?: Record<string, string>;
+    };
+}): Promise<any>;
+export declare function setFile(path: string, file: File | null, options?: {
+    _overrides?: {
+        headers?: Record<string, string>;
+    };
+}): Promise<boolean>;
 export declare function signMessage(message: string): Promise<string>;
 export declare function signTransaction(transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
 export declare function signAndSubmitTransaction(transaction: Transaction | VersionedTransaction, feePayer?: PublicKey): Promise<string>;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { init } from './client/config';
 export { getConfig, ClientConfig } from './client/config';
-export { get, set, setMany, setFile, getFiles, runQuery, runQueryMany, runExpression, runExpressionMany, signMessage, signTransaction, signAndSubmitTransaction, SetOptions, GetOptions, RunExpressionOptions, RunExpressionResult } from './client/operations';
+export { get, set, setMany, setFile, getFiles, runQuery, runQueryMany, runExpression, runExpressionMany, signMessage, signTransaction, signAndSubmitTransaction, count, aggregate, SetOptions, GetOptions, CountOptions, AggregateOptions, AggregateOperation, AggregateResult, RunExpressionOptions, RunExpressionResult } from './client/operations';
 export { subscribe, closeAllSubscriptions, clearCache, getCachedData, reconnectWithNewAuth } from './client/subscription';
 export * from './types';
 export { getIdToken } from './utils/utils';

package/dist/index.js

@@ -139,10 +139,14 @@ class WebSessionManager {
                     const newObj = JSON.parse(newSession);
                     return { address: newObj.address, session: newObj };
                 }
+                // Refresh failed — clear stale session to prevent retry loops
+                this.clearSession();
                 return null;
             }
         }
         catch (err) {
+            // Token decode or refresh failed — clear stale session to prevent retry loops
+            this.clearSession();
             return null;
         }
         return { address: sessionObj.address, session: sessionObj };
@@ -3066,15 +3070,30 @@ class ServerSessionManager {
     constructor() {
         /* Private cache (lives for the life of the process) */
         this.session = null;
+        /* Coalesce concurrent getSession() calls into a single in-flight request */
+        this.pendingSession = null;
     }
     /* ---------------------------------------------- *
      * GET (lazy-fetch)
      * ---------------------------------------------- */
     async getSession() {
-        if (this.session === null) {
-            this.session = await createSession();
+        if (this.session !== null) {
+            return this.session;
+        }
+        // If a session creation is already in-flight, reuse that promise
+        // instead of firing a second concurrent request.
+        if (this.pendingSession !== null) {
+            return this.pendingSession;
         }
-        return this.session;
+        this.pendingSession = createSession()
+            .then((session) => {
+            this.session = session;
+            return session;
+        })
+            .finally(() => {
+            this.pendingSession = null;
+        });
+        return this.pendingSession;
     }
     /* ---------------------------------------------- *
      * STORE  (overwrites the cached value)
@@ -3087,6 +3106,7 @@ class ServerSessionManager {
      * ---------------------------------------------- */
     clearSession() {
         this.session = null;
+        this.pendingSession = null;
     }
     /* ---------------------------------------------- *
      * QUICK helpers
@@ -3240,7 +3260,7 @@ async function makeApiRequest(method, urlPath, data, _overrides) {
             requestConfig.data = data ? JSON.stringify(data) : {};
         }
         const response = await axios(requestConfig);
-        return { data: response.data, status: response.status };
+        return { data: response.data, status: response.status, headers: response.headers };
     }
     try {
         return await executeRequest();
@@ -3382,6 +3402,157 @@ const pendingRequests = {};
 const GET_CACHE_TTL = 500; // Adjust this value as needed (in milliseconds)
 // Last time we cleaned up the cache
 let lastCacheCleanup = Date.now();
+function hashForKey$1(value) {
+    let h = 5381;
+    for (let i = 0; i < value.length; i++) {
+        h = ((h << 5) + h + value.charCodeAt(i)) & 0x7fffffff;
+    }
+    return h.toString(36);
+}
+/**
+ * Validates that a field name is a safe identifier (alphanumeric, underscores, dots for nested paths).
+ * Prevents prompt injection via crafted field names.
+ */
+function validateFieldName(field) {
+    if (!/^[a-zA-Z0-9_.]+$/.test(field)) {
+        throw new Error(`Invalid field name "${field}". Field names must only contain letters, numbers, underscores, and dots.`);
+    }
+}
+/**
+ * Parses a raw aggregation result (e.g. [{ count: 42 }] or [{ _id: null, total: 100 }])
+ * into a single numeric value.
+ */
+function parseAggregateValue(result) {
+    if (typeof result === 'number')
+        return result;
+    if (Array.isArray(result)) {
+        if (result.length === 0)
+            return 0;
+        // Multiple elements — not a collapsed aggregate result
+        if (result.length > 1) {
+            throw new Error(`Unexpected aggregate result: got array with ${result.length} elements. The AI may have returned full documents instead of an aggregation.`);
+        }
+        const first = result[0];
+        if (typeof first === 'number')
+            return first;
+        if (first && typeof first === 'object') {
+            // $count stage returns { count: N }
+            if (typeof first.count === 'number')
+                return first.count;
+            // $group stage returns { _id: null, result: N } — expect _id + one numeric field
+            const numericEntries = Object.entries(first).filter(([key, val]) => key !== '_id' && typeof val === 'number');
+            if (numericEntries.length === 1)
+                return numericEntries[0][1];
+        }
+        // Avoid leaking document contents into error messages
+        const shape = first && typeof first === 'object' ? `{${Object.keys(first).join(', ')}}` : String(first);
+        throw new Error(`Unexpected aggregate result shape: ${shape}. Expected {count: N} or {_id: null, <field>: N}.`);
+    }
+    if (result && typeof result === 'object' && typeof result.count === 'number') {
+        return result.count;
+    }
+    throw new Error(`Unexpected aggregate result type: ${typeof result}. Expected a number, array, or object with a count field.`);
+}
+/**
+ * Count items in a collection path. Returns a numeric result.
+ *
+ * This uses the AI query engine with a count-specific prompt prefix,
+ * so TaroBase will generate a $count aggregation pipeline and return
+ * just the count rather than full documents.
+ *
+ * IMPORTANT: This only works for collections where the read policy is "true".
+ * If the read policy requires per-document checks, the server will return
+ * an error because aggregate counts cannot be performed without pulling all
+ * documents for access control evaluation.
+ *
+ * @param path - Collection path (e.g., "posts", "users/abc/comments")
+ * @param opts - Optional filter prompt and overrides
+ * @returns AggregateResult with the count value
+ */
+async function count(path, opts = {}) {
+    const prefix = 'Return ONLY the total count of matching documents. Use the $count stage to produce a field named "count". Do NOT return the documents themselves.';
+    const fullPrompt = opts.prompt
+        ? `${prefix} Filter: ${opts.prompt}`
+        : prefix;
+    const result = await get(path, { prompt: fullPrompt, bypassCache: true, _overrides: opts._overrides });
+    return { value: parseAggregateValue(result) };
+}
+/**
+ * Run an aggregate operation on a collection path. Returns a numeric result.
+ *
+ * Supported operations:
+ * - count: Total number of documents
+ * - uniqueCount: Number of distinct values for a field
+ * - sum: Sum of a numeric field
+ * - avg: Average of a numeric field
+ * - min: Minimum value of a numeric field
+ * - max: Maximum value of a numeric field
+ *
+ * IMPORTANT: This only works for collections where the read policy is "true".
+ * If the read policy requires per-document checks, the server will return
+ * an error because aggregate operations cannot be performed without pulling
+ * all documents for access control evaluation.
+ *
+ * @param path - Collection path (e.g., "posts", "users/abc/comments")
+ * @param operation - The aggregate operation to perform
+ * @param opts - Options including optional filter prompt and field name
+ * @returns AggregateResult with the computed numeric value
+ */
+async function aggregate(path, operation, opts = {}) {
+    let prefix;
+    switch (operation) {
+        case 'count':
+            prefix = 'Return ONLY the total count of matching documents. Use the $count stage to produce a field named "count". Do NOT return the documents themselves.';
+            break;
+        case 'uniqueCount':
+            if (!opts.field)
+                throw new Error('aggregate "uniqueCount" requires a field option');
+            validateFieldName(opts.field);
+            prefix = `Return ONLY the count of unique/distinct values of the "${opts.field}" field. Use $group with _id set to "$${opts.field}" then $count to produce a field named "count". Do NOT return the documents themselves.`;
+            break;
+        case 'sum':
+            if (!opts.field)
+                throw new Error('aggregate "sum" requires a field option');
+            validateFieldName(opts.field);
+            prefix = `Return ONLY the sum of the "${opts.field}" field across all matching documents. Use $group with _id: null and result: { $sum: "$${opts.field}" }. Do NOT return the documents themselves.`;
+            break;
+        case 'avg':
+            if (!opts.field)
+                throw new Error('aggregate "avg" requires a field option');
+            validateFieldName(opts.field);
+            prefix = `Return ONLY the average of the "${opts.field}" field across all matching documents. Use $group with _id: null and result: { $avg: "$${opts.field}" }. Do NOT return the documents themselves.`;
+            break;
+        case 'min':
+            if (!opts.field)
+                throw new Error('aggregate "min" requires a field option');
+            validateFieldName(opts.field);
+            prefix = `Return ONLY the minimum value of the "${opts.field}" field across all matching documents. Use $group with _id: null and result: { $min: "$${opts.field}" }. Do NOT return the documents themselves.`;
+            break;
+        case 'max':
+            if (!opts.field)
+                throw new Error('aggregate "max" requires a field option');
+            validateFieldName(opts.field);
+            prefix = `Return ONLY the maximum value of the "${opts.field}" field across all matching documents. Use $group with _id: null and result: { $max: "$${opts.field}" }. Do NOT return the documents themselves.`;
+            break;
+        default:
+            throw new Error(`Unsupported aggregate operation: ${operation}`);
+    }
+    const fullPrompt = opts.prompt
+        ? `${prefix} Filter: ${opts.prompt}`
+        : prefix;
+    const result = await get(path, { prompt: fullPrompt, bypassCache: true, _overrides: opts._overrides });
+    // For uniqueCount, the AI may return $group results without the final $count
+    // stage, producing [{_id: "val1"}, {_id: "val2"}, ...]. Verify elements look
+    // like $group output (only _id key) before using array length as the count.
+    if (operation === 'uniqueCount' && Array.isArray(result) && result.length > 1) {
+        const looksLikeGroupOutput = result.every((el) => el && typeof el === 'object' && Object.keys(el).length === 1 && '_id' in el);
+        if (looksLikeGroupOutput) {
+            return { value: result.length };
+        }
+        throw new Error(`Unexpected uniqueCount result: got ${result.length} elements that don't match $group output shape.`);
+    }
+    return { value: parseAggregateValue(result) };
+}
 async function get(path, opts = {}) {
     try {
         let normalizedPath = path.startsWith("/") ? path.slice(1) : path;
@@ -3392,10 +3563,12 @@ async function get(path, opts = {}) {
         if (!normalizedPath || normalizedPath.length === 0) {
             return new Error("Invalid path provided.");
         }
-        // Create cache key combining path, prompt, includeSubPaths, and shape
+        // Create cache key combining path, prompt, includeSubPaths, shape, limit, and cursor
         const shapeKey = opts.shape ? JSON.stringify(opts.shape) : '';
         const includeSubPathsKey = opts.includeSubPaths ? ':subpaths' : '';
-        const cacheKey = `${normalizedPath}:${opts.prompt || ''}${includeSubPathsKey}:${shapeKey}`;
+        const limitKey = opts.limit !== undefined ? `:l${opts.limit}` : '';
+        const cursorKey = opts.cursor ? `:c${hashForKey$1(opts.cursor)}` : '';
+        const cacheKey = `${normalizedPath}:${opts.prompt || ''}${includeSubPathsKey}:${shapeKey}${limitKey}${cursorKey}`;
         const now = Date.now();
         // Check for valid cache entry if not bypassing cache
         if (!opts.bypassCache && getCache[cacheKey] && now < getCache[cacheKey].expiresAt) {
@@ -3419,6 +3592,8 @@ async function get(path, opts = {}) {
                 // Build common query params
                 const includeSubPathsParam = opts.includeSubPaths ? '&includeSubPaths=true' : '';
                 const shapeParam = opts.shape ? `&shape=${encodeURIComponent(JSON.stringify(opts.shape))}` : '';
+                const limitParam = opts.limit !== undefined ? `&limit=${opts.limit}` : '';
+                const cursorParam = opts.cursor ? `&cursor=${encodeURIComponent(opts.cursor)}` : '';
                 if (pathIsDocument) {
                     const itemId = encodeURIComponent(normalizedPath);
                     // For documents, query params go after the path
@@ -3429,13 +3604,14 @@ async function get(path, opts = {}) {
                 else {
                     const path = encodeURIComponent(normalizedPath);
                     const promptQueryParam = (opts === null || opts === void 0 ? void 0 : opts.prompt) ? `&prompt=${btoa(opts.prompt)}` : "";
-                    const apiPath = `items?path=${path}${promptQueryParam}${includeSubPathsParam}${shapeParam}`;
+                    const apiPath = `items?path=${path}${promptQueryParam}${includeSubPathsParam}${shapeParam}${limitParam}${cursorParam}`;
                     response = await makeApiRequest('GET', apiPath, null, opts._overrides);
                 }
+                const responseData = response.data;
                 // Cache the response (unless bypassing cache)
                 if (!opts.bypassCache) {
                     getCache[cacheKey] = {
-                        data: response.data,
+                        data: responseData,
                         expiresAt: now + GET_CACHE_TTL
                     };
                     // Periodically clean up expired cache entries (every 5 seconds)
@@ -3445,7 +3621,7 @@ async function get(path, opts = {}) {
                     }
                 }
                 // Return the data from the response
-                return response.data;
+                return responseData;
             }
             finally {
                 // Remove this request from pendingRequests regardless of success/failure
@@ -3742,21 +3918,21 @@ function clearCacheByPrefix(prefix) {
         }
     });
 }
-async function getFiles(path) {
+async function getFiles(path, options) {
     try {
         const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
         if (!normalizedPath || normalizedPath.length === 0) {
             return new Error("Invalid path provided.");
         }
         const apiPath = `storage?path=${normalizedPath}`;
-        const response = await makeApiRequest('GET', apiPath, null, undefined);
+        const response = await makeApiRequest('GET', apiPath, null, options === null || options === void 0 ? void 0 : options._overrides);
         return response.data;
     }
     catch (error) {
         throw error;
     }
 }
-async function setFile(path, file) {
+async function setFile(path, file, options) {
     var _a;
     // 1) Get the presigned URL from your backend
     const requestBody = {
@@ -3767,7 +3943,7 @@ async function setFile(path, file) {
     if (file) {
         requestBody.contentLength = file.size;
     }
-    const response = await makeApiRequest('POST', 'storage/url', requestBody, undefined);
+    const response = await makeApiRequest('POST', 'storage/url', requestBody, options === null || options === void 0 ? void 0 : options._overrides);
     if (file == null) {
         return true;
     }
@@ -3843,7 +4019,7 @@ const BASE_MIN_RECONNECT_DELAY_MS = 1000;
 const MIN_RECONNECT_DELAY_JITTER_MS = 1000;
 const MAX_RECONNECT_DELAY_MS = 300000;
 const RECONNECT_DELAY_GROW_FACTOR = 1.8;
-const MIN_BROWSER_RECONNECT_INTERVAL_MS = 30000;
+const MIN_BROWSER_RECONNECT_INTERVAL_MS = 5000;
 const WS_CONFIG = {
     // Keep retrying indefinitely so long outages recover without page refresh.
     maxRetries: Infinity,
@@ -3863,10 +4039,19 @@ let lastBrowserTriggeredReconnectAt = 0;
 function generateSubscriptionId() {
     return `sub_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
 }
-function getCacheKey(path, prompt, shape) {
+function hashForKey(value) {
+    let h = 5381;
+    for (let i = 0; i < value.length; i++) {
+        h = ((h << 5) + h + value.charCodeAt(i)) & 0x7fffffff;
+    }
+    return h.toString(36);
+}
+function getCacheKey(path, prompt, shape, limit, cursor) {
     const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
     const shapeKey = shape && Object.keys(shape).length > 0 ? JSON.stringify(shape) : '';
-    return `${normalizedPath}:${prompt || 'default'}:${shapeKey}`;
+    const limitKey = limit !== undefined ? `:l${limit}` : '';
+    const cursorKey = cursor ? `:c${hashForKey(cursor)}` : '';
+    return `${normalizedPath}:${prompt || 'default'}:${shapeKey}${limitKey}${cursorKey}`;
 }
 function isTokenExpired(token) {
     try {
@@ -3999,6 +4184,8 @@ async function getOrCreateConnection(appId, isServer) {
         isConnected: false,
         appId,
         tokenRefreshTimer: null,
+        lastMessageAt: Date.now(),
+        keepaliveTimer: null,
     };
     connections.set(appId, connection);
     // URL provider for reconnection with fresh tokens
@@ -4007,8 +4194,12 @@ async function getOrCreateConnection(appId, isServer) {
         const wsUrl = new URL(config.wsApiUrl);
         // Always use v2 path
         wsUrl.pathname = WS_V2_PATH;
-        // Set appId
-        if (typeof window !== 'undefined' && window.CUSTOM_TAROBASE_APP_ID_HEADER) {
+        // Set appId — prefer the explicit appId passed to getOrCreateConnection,
+        // fall back to window global for legacy callers, then config default
+        if (appId && appId !== config.appId) {
+            wsUrl.searchParams.append('appId', appId);
+        }
+        else if (typeof window !== 'undefined' && window.CUSTOM_TAROBASE_APP_ID_HEADER) {
             wsUrl.searchParams.append('appId', window.CUSTOM_TAROBASE_APP_ID_HEADER);
         }
         else {
@@ -4031,6 +4222,7 @@ async function getOrCreateConnection(appId, isServer) {
     ws.addEventListener('open', () => {
         connection.isConnecting = false;
         connection.isConnected = true;
+        connection.lastMessageAt = Date.now();
         // Schedule token refresh before expiry
         (async () => {
             const token = await getIdToken(isServer);
@@ -4038,11 +4230,28 @@ async function getOrCreateConnection(appId, isServer) {
         })();
         // Re-subscribe to all existing subscriptions after reconnect
         for (const sub of connection.subscriptions.values()) {
+            sub.lastData = undefined;
             sendSubscribe(connection, sub);
         }
+        // Start keepalive detection — if no messages for 90s, force reconnect
+        if (connection.keepaliveTimer) {
+            clearInterval(connection.keepaliveTimer);
+        }
+        connection.keepaliveTimer = setInterval(() => {
+            var _a;
+            if (Date.now() - connection.lastMessageAt > 90000) {
+                console.warn('[WS v2] No messages received for 90s, forcing reconnect');
+                if (connection.keepaliveTimer) {
+                    clearInterval(connection.keepaliveTimer);
+                    connection.keepaliveTimer = null;
+                }
+                (_a = connection.ws) === null || _a === void 0 ? void 0 : _a.reconnect();
+            }
+        }, 30000);
     });
     // Handle incoming messages
     ws.addEventListener('message', (event) => {
+        connection.lastMessageAt = Date.now();
         try {
             const message = JSON.parse(event.data);
             handleServerMessage(connection, message);
@@ -4054,20 +4263,22 @@ async function getOrCreateConnection(appId, isServer) {
     // Handle errors
     ws.addEventListener('error', (event) => {
         console.error('[WS v2] WebSocket error:', event);
-        // Reject all pending subscriptions
-        for (const [id, pending] of connection.pendingSubscriptions) {
+        for (const [, pending] of connection.pendingSubscriptions) {
             pending.reject(new Error('WebSocket error'));
-            connection.pendingSubscriptions.delete(id);
         }
+        connection.pendingSubscriptions.clear();
     });
     // Handle close
     ws.addEventListener('close', () => {
         connection.isConnected = false;
-        // Clear token refresh timer
         if (connection.tokenRefreshTimer) {
             clearTimeout(connection.tokenRefreshTimer);
             connection.tokenRefreshTimer = null;
         }
+        if (connection.keepaliveTimer) {
+            clearInterval(connection.keepaliveTimer);
+            connection.keepaliveTimer = null;
+        }
     });
     return connection;
 }
@@ -4081,7 +4292,7 @@ function handleServerMessage(connection, message) {
                 // If we already received data for this subscription, treat subscribed
                 // as an ack only and avoid regressing to an older snapshot.
                 if (subscription.lastData === undefined) {
-                    const cacheKey = getCacheKey(subscription.path, subscription.prompt, subscription.shape);
+                    const cacheKey = getCacheKey(subscription.path, subscription.prompt, subscription.shape, subscription.limit, subscription.cursor);
                     responseCache.set(cacheKey, { data: message.data, timestamp: Date.now() });
                     subscription.lastData = message.data;
                     notifyCallbacks(subscription, message.data);
@@ -4108,7 +4319,7 @@ function handleServerMessage(connection, message) {
             const subscription = connection.subscriptions.get(message.subscriptionId);
             if (subscription) {
                 // Update cache
-                const cacheKey = getCacheKey(subscription.path, subscription.prompt, subscription.shape);
+                const cacheKey = getCacheKey(subscription.path, subscription.prompt, subscription.shape, subscription.limit, subscription.cursor);
                 responseCache.set(cacheKey, { data: message.data, timestamp: Date.now() });
                 // Store last data
                 subscription.lastData = message.data;
@@ -4165,6 +4376,8 @@ function sendSubscribe(connection, subscription) {
         shape: subscription.shape && Object.keys(subscription.shape).length > 0
             ? subscription.shape
             : undefined,
+        limit: subscription.limit,
+        cursor: subscription.cursor,
     };
     try {
         connection.ws.send(JSON.stringify(message));
@@ -4196,7 +4409,7 @@ function sendUnsubscribe(connection, subscriptionId) {
 async function subscribeV2(path, subscriptionOptions) {
     const config = await getConfig();
     const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
-    const cacheKey = getCacheKey(normalizedPath, subscriptionOptions.prompt, subscriptionOptions.shape);
+    const cacheKey = getCacheKey(normalizedPath, subscriptionOptions.prompt, subscriptionOptions.shape, subscriptionOptions.limit, subscriptionOptions.cursor);
     // Deliver cached data immediately if available
     const cachedEntry = responseCache.get(cacheKey);
     if (cachedEntry && Date.now() - cachedEntry.timestamp < CACHE_TTL && subscriptionOptions.onData) {
@@ -4205,14 +4418,16 @@ async function subscribeV2(path, subscriptionOptions) {
             (_a = subscriptionOptions.onData) === null || _a === void 0 ? void 0 : _a.call(subscriptionOptions, cachedEntry.data);
         }, 0);
     }
+    // Use explicit appId override if provided, otherwise fall back to config
+    const effectiveAppId = subscriptionOptions.appId || config.appId;
     // Get or create connection for this appId
-    const connection = await getOrCreateConnection(config.appId, config.isServer);
-    // Check if we already have a subscription for this path+prompt+shape
+    const connection = await getOrCreateConnection(effectiveAppId, config.isServer);
+    // Check if we already have a subscription for this path+prompt+shape+limit+cursor
     const shapeKey = subscriptionOptions.shape ? JSON.stringify(subscriptionOptions.shape) : '';
     let existingSubscription;
     for (const sub of connection.subscriptions.values()) {
         const subShapeKey = sub.shape ? JSON.stringify(sub.shape) : '';
-        if (sub.path === normalizedPath && sub.prompt === subscriptionOptions.prompt && subShapeKey === shapeKey) {
+        if (sub.path === normalizedPath && sub.prompt === subscriptionOptions.prompt && subShapeKey === shapeKey && sub.limit === subscriptionOptions.limit && sub.cursor === subscriptionOptions.cursor) {
             existingSubscription = sub;
             break;
         }
@@ -4238,6 +4453,8 @@ async function subscribeV2(path, subscriptionOptions) {
         path: normalizedPath,
         prompt: subscriptionOptions.prompt,
         shape: subscriptionOptions.shape,
+        limit: subscriptionOptions.limit,
+        cursor: subscriptionOptions.cursor,
         includeSubPaths: false,
         callbacks: [subscriptionOptions],
         lastData: undefined,
@@ -4261,9 +4478,7 @@ async function subscribeV2(path, subscriptionOptions) {
             await subscriptionPromise;
         }
         catch (error) {
-            // Remove subscription on error
-            connection.subscriptions.delete(subscriptionId);
-            throw error;
+            console.warn('[WS v2] Subscription confirmation failed, keeping for reconnect recovery:', error);
         }
     }
     // Return unsubscribe function
@@ -4379,8 +4594,6 @@ async function reconnectWithNewAuthV2() {
         if (!connection.ws) {
             continue;
         }
-        // Reject any pending subscriptions - they'll need to be retried after reconnect
-        // This prevents hanging promises during auth transitions
         for (const [, pending] of connection.pendingSubscriptions) {
             pending.reject(new Error('Connection reconnecting due to auth change'));
         }
@@ -4474,10 +4687,12 @@ async function reconnectWithNewAuth() {
 
 exports.ServerSessionManager = ServerSessionManager;
 exports.WebSessionManager = WebSessionManager;
+exports.aggregate = aggregate;
 exports.buildSetDocumentsTransaction = buildSetDocumentsTransaction;
 exports.clearCache = clearCache;
 exports.closeAllSubscriptions = closeAllSubscriptions;
 exports.convertRemainingAccounts = convertRemainingAccounts;
+exports.count = count;
 exports.createSessionWithPrivy = createSessionWithPrivy;
 exports.createSessionWithSignature = createSessionWithSignature;
 exports.genAuthNonce = genAuthNonce;