hyperstack-react 0.5.9 → 0.6.0

package/dist/index.esm.js

@@ -6768,6 +6768,19 @@ const DEFAULT_CONFIG = {
     maxReconnectAttempts: 5,
     maxEntriesPerView: DEFAULT_MAX_ENTRIES_PER_VIEW,
 };
+/**
+ * Determines if the error indicates the client should fetch a new token
+ */
+function shouldRefreshToken(code) {
+    return [
+        'TOKEN_EXPIRED',
+        'TOKEN_INVALID_SIGNATURE',
+        'TOKEN_INVALID_FORMAT',
+        'TOKEN_INVALID_ISSUER',
+        'TOKEN_INVALID_AUDIENCE',
+        'TOKEN_KEY_NOT_FOUND',
+    ].includes(code);
+}
 class HyperStackError extends Error {
     constructor(message, code, details) {
         super(message);
@@ -6776,6 +6789,42 @@ class HyperStackError extends Error {
         this.name = 'HyperStackError';
     }
 }
+/**
+ * Parse a kebab-case error code string (from X-Error-Code header) to AuthErrorCode
+ */
+function parseErrorCode(errorCode) {
+    const codeMap = {
+        'token-missing': 'TOKEN_MISSING',
+        'token-expired': 'TOKEN_EXPIRED',
+        'token-invalid-signature': 'TOKEN_INVALID_SIGNATURE',
+        'token-invalid-format': 'TOKEN_INVALID_FORMAT',
+        'token-invalid-issuer': 'TOKEN_INVALID_ISSUER',
+        'token-invalid-audience': 'TOKEN_INVALID_AUDIENCE',
+        'token-missing-claim': 'TOKEN_MISSING_CLAIM',
+        'token-key-not-found': 'TOKEN_KEY_NOT_FOUND',
+        'origin-mismatch': 'ORIGIN_MISMATCH',
+        'origin-required': 'ORIGIN_REQUIRED',
+        'origin-not-allowed': 'ORIGIN_NOT_ALLOWED',
+        'rate-limit-exceeded': 'RATE_LIMIT_EXCEEDED',
+        'websocket-session-rate-limit-exceeded': 'WEBSOCKET_SESSION_RATE_LIMIT_EXCEEDED',
+        'connection-limit-exceeded': 'CONNECTION_LIMIT_EXCEEDED',
+        'subscription-limit-exceeded': 'SUBSCRIPTION_LIMIT_EXCEEDED',
+        'snapshot-limit-exceeded': 'SNAPSHOT_LIMIT_EXCEEDED',
+        'egress-limit-exceeded': 'EGRESS_LIMIT_EXCEEDED',
+        'invalid-static-token': 'INVALID_STATIC_TOKEN',
+        'internal-error': 'INTERNAL_ERROR',
+        'auth-required': 'AUTH_REQUIRED',
+        'missing-authorization-header': 'MISSING_AUTHORIZATION_HEADER',
+        'invalid-authorization-format': 'INVALID_AUTHORIZATION_FORMAT',
+        'invalid-api-key': 'INVALID_API_KEY',
+        'expired-api-key': 'EXPIRED_API_KEY',
+        'user-not-found': 'USER_NOT_FOUND',
+        'secret-key-required': 'SECRET_KEY_REQUIRED',
+        'deployment-access-denied': 'DEPLOYMENT_ACCESS_DENIED',
+        'quota-exceeded': 'QUOTA_EXCEEDED',
+    };
+    return codeMap[errorCode.toLowerCase()] || 'INTERNAL_ERROR';
+}
 
 const GZIP_MAGIC_0 = 0x1f;
 const GZIP_MAGIC_1 = 0x8b;
@@ -6823,27 +6872,364 @@ function isValidFrame(frame) {
         ['create', 'upsert', 'patch', 'delete'].includes(f['op']));
 }
 
+const TOKEN_REFRESH_BUFFER_SECONDS = 60;
+const MIN_REFRESH_DELAY_MS = 1000;
+const DEFAULT_QUERY_PARAMETER = 'hs_token';
+const DEFAULT_HOSTED_TOKEN_ENDPOINT = 'https://api.usehyperstack.com/ws/sessions';
+const HOSTED_WEBSOCKET_SUFFIX = '.stack.usehyperstack.com';
+function normalizeTokenResult(result) {
+    if (typeof result === 'string') {
+        return { token: result };
+    }
+    return result;
+}
+function decodeBase64Url(value) {
+    const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+    if (typeof atob === 'function') {
+        return atob(padded);
+    }
+    const bufferCtor = globalThis.Buffer;
+    if (bufferCtor) {
+        return bufferCtor.from(padded, 'base64').toString('utf-8');
+    }
+    return undefined;
+}
+function parseJwtExpiry(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    const payload = decodeBase64Url(parts[1] ?? '');
+    if (!payload) {
+        return undefined;
+    }
+    try {
+        const decoded = JSON.parse(payload);
+        return typeof decoded.exp === 'number' ? decoded.exp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeExpiryTimestamp(expiresAt, expires_at) {
+    return expiresAt ?? expires_at;
+}
+function isRefreshAuthResponseMessage(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate['success'] === 'boolean'
+        && !('op' in candidate)
+        && !('entity' in candidate)
+        && !('mode' in candidate);
+}
+function isSocketIssueMessage(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return candidate['type'] === 'error'
+        && typeof candidate['message'] === 'string'
+        && typeof candidate['code'] === 'string'
+        && typeof candidate['retryable'] === 'boolean'
+        && typeof candidate['fatal'] === 'boolean';
+}
+function isHostedHyperstackWebsocketUrl(websocketUrl) {
+    try {
+        return new URL(websocketUrl).hostname.toLowerCase().endsWith(HOSTED_WEBSOCKET_SUFFIX);
+    }
+    catch {
+        return false;
+    }
+}
 class ConnectionManager {
     constructor(config) {
         this.ws = null;
         this.reconnectAttempts = 0;
         this.reconnectTimeout = null;
         this.pingInterval = null;
+        this.tokenRefreshTimeout = null;
+        this.tokenRefreshInFlight = null;
         this.currentState = 'disconnected';
         this.subscriptionQueue = [];
         this.activeSubscriptions = new Set();
         this.frameHandlers = new Set();
         this.stateHandlers = new Set();
+        this.socketIssueHandlers = new Set();
+        this.reconnectForTokenRefresh = false;
         if (!config.websocketUrl) {
             throw new HyperStackError('websocketUrl is required', 'INVALID_CONFIG');
         }
         this.websocketUrl = config.websocketUrl;
+        this.hostedHyperstackUrl = isHostedHyperstackWebsocketUrl(config.websocketUrl);
         this.reconnectIntervals = config.reconnectIntervals ?? DEFAULT_CONFIG.reconnectIntervals;
-        this.maxReconnectAttempts = config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts;
+        this.maxReconnectAttempts =
+            config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts;
+        this.authConfig = config.auth;
         if (config.initialSubscriptions) {
             this.subscriptionQueue.push(...config.initialSubscriptions);
         }
     }
+    getTokenEndpoint() {
+        if (this.authConfig?.tokenEndpoint) {
+            return this.authConfig.tokenEndpoint;
+        }
+        if (this.hostedHyperstackUrl && this.authConfig?.publishableKey) {
+            return DEFAULT_HOSTED_TOKEN_ENDPOINT;
+        }
+        return undefined;
+    }
+    getAuthStrategy() {
+        if (this.authConfig?.token) {
+            return { kind: 'static-token', token: this.authConfig.token };
+        }
+        if (this.authConfig?.getToken) {
+            return { kind: 'token-provider', getToken: this.authConfig.getToken };
+        }
+        const tokenEndpoint = this.getTokenEndpoint();
+        if (tokenEndpoint) {
+            return { kind: 'token-endpoint', endpoint: tokenEndpoint };
+        }
+        return { kind: 'none' };
+    }
+    hasRefreshableAuth() {
+        const strategy = this.getAuthStrategy();
+        return strategy.kind === 'token-provider' || strategy.kind === 'token-endpoint';
+    }
+    updateTokenState(result) {
+        const normalized = normalizeTokenResult(result);
+        if (!normalized.token) {
+            throw new HyperStackError('Authentication provider returned an empty token', 'TOKEN_INVALID');
+        }
+        this.currentToken = normalized.token;
+        this.tokenExpiry = normalizeExpiryTimestamp(normalized.expiresAt, normalized.expires_at)
+            ?? parseJwtExpiry(normalized.token);
+        if (this.isTokenExpired()) {
+            throw new HyperStackError('Authentication token is expired', 'TOKEN_EXPIRED');
+        }
+        return normalized.token;
+    }
+    clearTokenState() {
+        this.currentToken = undefined;
+        this.tokenExpiry = undefined;
+    }
+    async getOrRefreshToken(forceRefresh = false) {
+        if (!forceRefresh && this.currentToken && !this.isTokenExpired()) {
+            return this.currentToken;
+        }
+        const strategy = this.getAuthStrategy();
+        if (strategy.kind === 'none' && this.hostedHyperstackUrl) {
+            throw new HyperStackError('Hosted Hyperstack websocket connections require auth.publishableKey, auth.getToken, auth.tokenEndpoint, or auth.token', 'AUTH_REQUIRED');
+        }
+        switch (strategy.kind) {
+            case 'static-token':
+                return this.updateTokenState(strategy.token);
+            case 'token-provider':
+                try {
+                    return this.updateTokenState(await strategy.getToken());
+                }
+                catch (error) {
+                    if (error instanceof HyperStackError) {
+                        throw error;
+                    }
+                    throw new HyperStackError('Failed to get authentication token', 'AUTH_REQUIRED', error);
+                }
+            case 'token-endpoint':
+                try {
+                    return this.updateTokenState(await this.fetchTokenFromEndpoint(strategy.endpoint));
+                }
+                catch (error) {
+                    if (error instanceof HyperStackError) {
+                        throw error;
+                    }
+                    throw new HyperStackError('Failed to fetch authentication token from endpoint', 'AUTH_REQUIRED', error);
+                }
+            case 'none':
+                return undefined;
+        }
+    }
+    createTokenEndpointRequestBody() {
+        return {
+            websocket_url: this.websocketUrl,
+        };
+    }
+    async fetchTokenFromEndpoint(tokenEndpoint) {
+        const response = await fetch(tokenEndpoint, {
+            method: 'POST',
+            headers: {
+                ...(this.authConfig?.publishableKey
+                    ? { Authorization: `Bearer ${this.authConfig.publishableKey}` }
+                    : {}),
+                ...(this.authConfig?.tokenEndpointHeaders ?? {}),
+                'Content-Type': 'application/json',
+            },
+            credentials: this.authConfig?.tokenEndpointCredentials,
+            body: JSON.stringify(this.createTokenEndpointRequestBody()),
+        });
+        if (!response.ok) {
+            const rawError = await response.text();
+            let parsedError;
+            if (rawError) {
+                try {
+                    parsedError = JSON.parse(rawError);
+                }
+                catch {
+                    parsedError = undefined;
+                }
+            }
+            const wireErrorCode = response.headers.get('X-Error-Code')
+                ?? (typeof parsedError?.code === 'string' ? parsedError.code : null);
+            const errorCode = wireErrorCode
+                ? parseErrorCode(wireErrorCode)
+                : response.status === 429
+                    ? 'QUOTA_EXCEEDED'
+                    : 'AUTH_REQUIRED';
+            const errorMessage = typeof parsedError?.error === 'string' && parsedError.error.length > 0
+                ? parsedError.error
+                : rawError || response.statusText || 'Authentication request failed';
+            throw new HyperStackError(`Token endpoint returned ${response.status}: ${errorMessage}`, errorCode, {
+                status: response.status,
+                wireErrorCode,
+                responseBody: rawError || null,
+            });
+        }
+        const data = (await response.json());
+        if (!data.token) {
+            throw new HyperStackError('Token endpoint did not return a token', 'TOKEN_INVALID');
+        }
+        return data;
+    }
+    isTokenExpired() {
+        if (!this.tokenExpiry) {
+            return false;
+        }
+        return Date.now() >= (this.tokenExpiry - TOKEN_REFRESH_BUFFER_SECONDS) * 1000;
+    }
+    scheduleTokenRefresh() {
+        this.clearTokenRefreshTimeout();
+        if (!this.hasRefreshableAuth() || !this.tokenExpiry) {
+            return;
+        }
+        const refreshAtMs = Math.max(Date.now() + MIN_REFRESH_DELAY_MS, (this.tokenExpiry - TOKEN_REFRESH_BUFFER_SECONDS) * 1000);
+        const delayMs = Math.max(MIN_REFRESH_DELAY_MS, refreshAtMs - Date.now());
+        this.tokenRefreshTimeout = setTimeout(() => {
+            void this.refreshTokenInBackground();
+        }, delayMs);
+    }
+    clearTokenRefreshTimeout() {
+        if (this.tokenRefreshTimeout) {
+            clearTimeout(this.tokenRefreshTimeout);
+            this.tokenRefreshTimeout = null;
+        }
+    }
+    async refreshTokenInBackground() {
+        if (!this.hasRefreshableAuth()) {
+            return;
+        }
+        if (this.tokenRefreshInFlight) {
+            return this.tokenRefreshInFlight;
+        }
+        this.tokenRefreshInFlight = (async () => {
+            const previousToken = this.currentToken;
+            try {
+                await this.getOrRefreshToken(true);
+                if (previousToken &&
+                    this.currentToken &&
+                    this.currentToken !== previousToken &&
+                    this.ws?.readyState === WebSocket.OPEN) {
+                    // Try in-band auth refresh first
+                    const refreshed = await this.sendInBandAuthRefresh(this.currentToken);
+                    if (!refreshed) {
+                        // Fall back to reconnecting if in-band refresh failed
+                        this.rotateConnectionForTokenRefresh();
+                    }
+                }
+                this.scheduleTokenRefresh();
+            }
+            catch {
+                this.scheduleTokenRefresh();
+            }
+            finally {
+                this.tokenRefreshInFlight = null;
+            }
+        })();
+        return this.tokenRefreshInFlight;
+    }
+    async sendInBandAuthRefresh(token) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            return false;
+        }
+        try {
+            const message = JSON.stringify({
+                type: 'refresh_auth',
+                token: token,
+            });
+            this.ws.send(message);
+            return true;
+        }
+        catch (error) {
+            console.warn('Failed to send in-band auth refresh:', error);
+            return false;
+        }
+    }
+    handleRefreshAuthResponse(message) {
+        if (message.success) {
+            const expiresAt = normalizeExpiryTimestamp(message.expiresAt, message.expires_at);
+            if (typeof expiresAt === 'number') {
+                this.tokenExpiry = expiresAt;
+            }
+            this.scheduleTokenRefresh();
+            return true;
+        }
+        const errorCode = message.error ? parseErrorCode(message.error) : 'INTERNAL_ERROR';
+        if (shouldRefreshToken(errorCode)) {
+            this.clearTokenState();
+        }
+        this.rotateConnectionForTokenRefresh();
+        return true;
+    }
+    handleSocketIssueMessage(message) {
+        this.notifySocketIssue(message);
+        if (message.fatal) {
+            this.updateState('error', message.message);
+        }
+        return true;
+    }
+    rotateConnectionForTokenRefresh() {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN || this.reconnectForTokenRefresh) {
+            return;
+        }
+        this.reconnectForTokenRefresh = true;
+        this.updateState('reconnecting');
+        this.ws.close(1000, 'token refresh');
+    }
+    buildAuthUrl(token) {
+        if (this.authConfig?.tokenTransport === 'bearer') {
+            return this.websocketUrl;
+        }
+        if (!token) {
+            return this.websocketUrl;
+        }
+        const separator = this.websocketUrl.includes('?') ? '&' : '?';
+        return `${this.websocketUrl}${separator}${DEFAULT_QUERY_PARAMETER}=${encodeURIComponent(token)}`;
+    }
+    createWebSocket(url, token) {
+        if (this.authConfig?.tokenTransport === 'bearer') {
+            const init = token
+                ? { headers: { Authorization: `Bearer ${token}` } }
+                : undefined;
+            if (this.authConfig.websocketFactory) {
+                return this.authConfig.websocketFactory(url, init);
+            }
+            throw new HyperStackError('auth.tokenTransport="bearer" requires auth.websocketFactory in this environment', 'INVALID_CONFIG');
+        }
+        if (this.authConfig?.websocketFactory) {
+            return this.authConfig.websocketFactory(url);
+        }
+        return new WebSocket(url);
+    }
     getState() {
         return this.currentState;
     }
@@ -6859,21 +7245,52 @@ class ConnectionManager {
             this.stateHandlers.delete(handler);
         };
     }
-    connect() {
+    onSocketIssue(handler) {
+        this.socketIssueHandlers.add(handler);
+        return () => {
+            this.socketIssueHandlers.delete(handler);
+        };
+    }
+    notifySocketIssue(message) {
+        const issue = {
+            error: message.error,
+            message: message.message,
+            code: parseErrorCode(message.code),
+            retryable: message.retryable,
+            retryAfter: message.retry_after,
+            suggestedAction: message.suggested_action,
+            docsUrl: message.docs_url,
+            fatal: message.fatal,
+        };
+        for (const handler of this.socketIssueHandlers) {
+            handler(issue);
+        }
+        return issue;
+    }
+    async connect() {
+        if (this.ws?.readyState === WebSocket.OPEN ||
+            this.ws?.readyState === WebSocket.CONNECTING ||
+            this.currentState === 'connecting') {
+            return;
+        }
+        this.updateState('connecting');
+        let token;
+        try {
+            token = await this.getOrRefreshToken();
+        }
+        catch (error) {
+            this.updateState('error', error instanceof Error ? error.message : 'Failed to get token');
+            throw error;
+        }
+        const wsUrl = this.buildAuthUrl(token);
         return new Promise((resolve, reject) => {
-            if (this.ws?.readyState === WebSocket.OPEN ||
-                this.ws?.readyState === WebSocket.CONNECTING ||
-                this.currentState === 'connecting') {
-                resolve();
-                return;
-            }
-            this.updateState('connecting');
             try {
-                this.ws = new WebSocket(this.websocketUrl);
+                this.ws = this.createWebSocket(wsUrl, token);
                 this.ws.onopen = () => {
                     this.reconnectAttempts = 0;
                     this.updateState('connected');
                     this.startPingInterval();
+                    this.scheduleTokenRefresh();
                     this.resubscribeActive();
                     this.flushSubscriptionQueue();
                     resolve();
@@ -6888,14 +7305,23 @@ class ConnectionManager {
                             frame = await parseFrameFromBlob(event.data);
                         }
                         else if (typeof event.data === 'string') {
-                            frame = parseFrame(event.data);
+                            const parsed = JSON.parse(event.data);
+                            if (isRefreshAuthResponseMessage(parsed)) {
+                                this.handleRefreshAuthResponse(parsed);
+                                return;
+                            }
+                            if (isSocketIssueMessage(parsed)) {
+                                this.handleSocketIssueMessage(parsed);
+                                return;
+                            }
+                            frame = parseFrame(JSON.stringify(parsed));
                         }
                         else {
                             throw new HyperStackError(`Unsupported message type: ${typeof event.data}`, 'PARSE_ERROR');
                         }
                         this.notifyFrameHandlers(frame);
                     }
-                    catch (error) {
+                    catch {
                         this.updateState('error', 'Failed to parse frame from server');
                     }
                 };
@@ -6906,9 +7332,44 @@ class ConnectionManager {
                         reject(error);
                     }
                 };
-                this.ws.onclose = () => {
+                this.ws.onclose = (event) => {
                     this.stopPingInterval();
+                    this.clearTokenRefreshTimeout();
                     this.ws = null;
+                    if (this.reconnectForTokenRefresh) {
+                        this.reconnectForTokenRefresh = false;
+                        void this.connect().catch(() => {
+                            this.handleReconnect();
+                        });
+                        return;
+                    }
+                    // Parse close reason for error codes (e.g., "token-expired: Token has expired")
+                    const closeReason = event.reason || '';
+                    const errorCodeMatch = closeReason.match(/^([\w-]+):/);
+                    const errorCode = errorCodeMatch ? parseErrorCode(errorCodeMatch[1]) : null;
+                    // Check for auth errors that require token refresh
+                    if (event.code === 1008 || errorCode) {
+                        const isAuthError = errorCode
+                            ? shouldRefreshToken(errorCode)
+                            : /expired|invalid|token/i.test(closeReason);
+                        if (isAuthError) {
+                            this.clearTokenState();
+                            // Try to reconnect immediately with a fresh token
+                            void this.connect().catch(() => {
+                                this.handleReconnect();
+                            });
+                            return;
+                        }
+                        // Check for rate limit errors
+                        const isRateLimit = errorCode === 'RATE_LIMIT_EXCEEDED' ||
+                            errorCode === 'CONNECTION_LIMIT_EXCEEDED' ||
+                            /rate.?limit|quota|limit.?exceeded/i.test(closeReason);
+                        if (isRateLimit) {
+                            this.updateState('error', `Rate limit exceeded: ${closeReason}`);
+                            // Don't auto-reconnect on rate limits, let user handle it
+                            return;
+                        }
+                    }
                     if (this.currentState !== 'disconnected') {
                         this.handleReconnect();
                     }
@@ -6924,6 +7385,8 @@ class ConnectionManager {
     disconnect() {
         this.clearReconnectTimeout();
         this.stopPingInterval();
+        this.clearTokenRefreshTimeout();
+        this.reconnectForTokenRefresh = false;
         this.updateState('disconnected');
         if (this.ws) {
             this.ws.close();
@@ -6941,7 +7404,7 @@ class ConnectionManager {
             this.activeSubscriptions.add(subKey);
         }
         else {
-            const alreadyQueued = this.subscriptionQueue.some((s) => this.makeSubKey(s) === subKey);
+            const alreadyQueued = this.subscriptionQueue.some((queuedSubscription) => this.makeSubKey(queuedSubscription) === subKey);
             if (!alreadyQueued) {
                 this.subscriptionQueue.push(subscription);
             }
@@ -6966,9 +7429,9 @@ class ConnectionManager {
     }
     flushSubscriptionQueue() {
         while (this.subscriptionQueue.length > 0) {
-            const sub = this.subscriptionQueue.shift();
-            if (sub) {
-                this.subscribe(sub);
+            const subscription = this.subscriptionQueue.shift();
+            if (subscription) {
+                this.subscribe(subscription);
             }
         }
     }
@@ -8688,6 +9151,7 @@ class HyperStack {
             websocketUrl: url,
             reconnectIntervals: options.reconnectIntervals,
             maxReconnectAttempts: options.maxReconnectAttempts,
+            auth: options.auth,
         });
         this.subscriptionRegistry = new SubscriptionRegistry(this.connection);
         this.connection.onFrame((frame) => {
@@ -8721,6 +9185,7 @@ class HyperStack {
             reconnectIntervals: options?.reconnectIntervals,
             maxReconnectAttempts: options?.maxReconnectAttempts,
             validateFrames: options?.validateFrames,
+            auth: options?.auth,
         };
         const client = new HyperStack(url, internalOptions);
         if (options?.autoReconnect !== false) {
@@ -8749,6 +9214,9 @@ class HyperStack {
     onFrame(callback) {
         return this.connection.onFrame(callback);
     }
+    onSocketIssue(callback) {
+        return this.connection.onSocketIssue(callback);
+    }
     async connect() {
         await this.connection.connect();
     }
@@ -8974,6 +9442,7 @@ function HyperstackProvider({ children, fallback = null, ...config }) {
             maxReconnectAttempts: config.maxReconnectAttempts,
             maxEntriesPerView: config.maxEntriesPerView,
             flushIntervalMs: config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS,
+            auth: config.auth,
         }).then((client) => {
             client.onConnectionStateChange((state, error) => {
                 adapter.setConnectionState(state, error);
@@ -8989,7 +9458,7 @@ function HyperstackProvider({ children, fallback = null, ...config }) {
         });
         connectingRef.current.set(cacheKey, connectionPromise);
         return connectionPromise;
-    }, [config.autoConnect, config.reconnectIntervals, config.maxReconnectAttempts, config.maxEntriesPerView, notifyClientChange]);
+    }, [config.autoConnect, config.reconnectIntervals, config.maxReconnectAttempts, config.maxEntriesPerView, config.flushIntervalMs, config.auth, notifyClientChange]);
     const getClient = useCallback((stack) => {
         if (!stack) {
             if (clientsRef.current.size === 1) {
@@ -9102,7 +9571,7 @@ function shallowArrayEqual(a, b) {
     return true;
 }
 function useStateView(viewDef, client, key, options) {
-    const [isLoading, setIsLoading] = useState(!options?.initialData);
+    const [isLoading, setIsLoading] = useState(!options?.initialData && options?.withSnapshot !== false);
     const [error, setError] = useState();
     const clientRef = useRef(client);
     clientRef.current = client;
@@ -9110,13 +9579,24 @@ function useStateView(viewDef, client, key, options) {
     const keyString = key ? Object.values(key)[0] : undefined;
     const enabled = options?.enabled !== false;
     const schema = options?.schema;
+    const withSnapshot = options?.withSnapshot;
+    const after = options?.after;
+    const snapshotLimit = options?.snapshotLimit;
     useEffect(() => {
         if (!enabled || !clientRef.current)
             return undefined;
         try {
             const registry = clientRef.current.getSubscriptionRegistry();
-            const unsubscribe = registry.subscribe({ view: viewDef.view, key: keyString });
-            setIsLoading(true);
+            const unsubscribe = registry.subscribe({
+                view: viewDef.view,
+                key: keyString,
+                withSnapshot,
+                after,
+                snapshotLimit
+            });
+            if (withSnapshot !== false) {
+                setIsLoading(true);
+            }
             return () => {
                 try {
                     unsubscribe();
@@ -9131,14 +9611,23 @@ function useStateView(viewDef, client, key, options) {
             setIsLoading(false);
             return undefined;
         }
-    }, [viewDef.view, keyString, enabled, client]);
+    }, [viewDef.view, keyString, enabled, withSnapshot, after, snapshotLimit, client]);
     const refresh = useCallback(() => {
         if (!enabled || !clientRef.current)
             return;
         try {
             const registry = clientRef.current.getSubscriptionRegistry();
-            const unsubscribe = registry.subscribe({ view: viewDef.view, key: keyString });
-            setIsLoading(true);
+            const unsubscribe = registry.subscribe({
+                view: viewDef.view,
+                key: keyString,
+                withSnapshot,
+                after,
+                snapshotLimit
+            });
+            const shouldLoad = withSnapshot ?? true;
+            if (shouldLoad) {
+                setIsLoading(true);
+            }
             setTimeout(() => {
                 try {
                     unsubscribe();
@@ -9152,7 +9641,7 @@ function useStateView(viewDef, client, key, options) {
             setError(err instanceof Error ? err : new Error('Refresh failed'));
             setIsLoading(false);
         }
-    }, [viewDef.view, keyString, enabled]);
+    }, [viewDef.view, keyString, enabled, withSnapshot, after, snapshotLimit]);
     const subscribe = useCallback((callback) => {
         if (!clientRef.current)
             return () => { };
@@ -9186,7 +9675,7 @@ function useStateView(viewDef, client, key, options) {
     };
 }
 function useListView(viewDef, client, params, options) {
-    const [isLoading, setIsLoading] = useState(!options?.initialData);
+    const [isLoading, setIsLoading] = useState(!options?.initialData && params?.withSnapshot !== false);
     const [error, setError] = useState();
     const clientRef = useRef(client);
     clientRef.current = client;
@@ -9199,6 +9688,9 @@ function useListView(viewDef, client, params, options) {
     const filtersJson = params?.filters ? JSON.stringify(params.filters) : undefined;
     const limit = params?.limit;
     const schema = params?.schema;
+    const withSnapshot = params?.withSnapshot;
+    const after = params?.after;
+    const snapshotLimit = params?.snapshotLimit;
     useEffect(() => {
         if (!enabled || !clientRef.current)
             return undefined;
@@ -9209,9 +9701,14 @@ function useListView(viewDef, client, params, options) {
                 key,
                 filters: params?.filters,
                 take,
-                skip
+                skip,
+                withSnapshot,
+                after,
+                snapshotLimit
             });
-            setIsLoading(true);
+            if (withSnapshot !== false) {
+                setIsLoading(true);
+            }
             return () => {
                 try {
                     unsubscribe();
@@ -9226,7 +9723,7 @@ function useListView(viewDef, client, params, options) {
             setIsLoading(false);
             return undefined;
         }
-    }, [viewDef.view, enabled, key, filtersJson, take, skip, client]);
+    }, [viewDef.view, enabled, key, filtersJson, take, skip, withSnapshot, after, snapshotLimit, client]);
     const refresh = useCallback(() => {
         if (!enabled || !clientRef.current)
             return;
@@ -9237,9 +9734,15 @@ function useListView(viewDef, client, params, options) {
                 key,
                 filters: params?.filters,
                 take,
-                skip
+                skip,
+                withSnapshot,
+                after,
+                snapshotLimit
             });
-            setIsLoading(true);
+            const shouldLoad = withSnapshot ?? true;
+            if (shouldLoad) {
+                setIsLoading(true);
+            }
             setTimeout(() => {
                 try {
                     unsubscribe();
@@ -9253,7 +9756,7 @@ function useListView(viewDef, client, params, options) {
             setError(err instanceof Error ? err : new Error('Refresh failed'));
             setIsLoading(false);
         }
-    }, [viewDef.view, enabled, key, filtersJson, take, skip]);
+    }, [viewDef.view, enabled, key, filtersJson, take, skip, withSnapshot, after, snapshotLimit]);
     const subscribe = useCallback((callback) => {
         if (!clientRef.current)
             return () => { };