@23blocks/sdk 13.4.0 → 13.5.1

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## 13.5.1 (2026-03-14)
+
+### 🩹 Fixes
+
+- **@23blocks/sdk:** fix token lifecycle security and correctness issues ([0886883](https://github.com/23blocks-OS/frontend-sdk/commit/0886883))
+
+### 📖 Documentation
+
+- update llms.txt and JSDoc for token lifecycle across all packages ([74d8319](https://github.com/23blocks-OS/frontend-sdk/commit/74d8319))
+
+### ❤️ Thank You
+
+- Claude Opus 4.6
+- Juan Pelaez
+
+## 13.5.0 (2026-03-14)
+
+### 🚀 Features
+
+- **@23blocks/sdk:** add token lifecycle management with auto-refresh and 401 retry ([5426358](https://github.com/23blocks-OS/frontend-sdk/commit/5426358))
+
+### 📖 Documentation
+
+- add token lifecycle to llms.txt ([f42d730](https://github.com/23blocks-OS/frontend-sdk/commit/f42d730))
+
+### ❤️ Thank You
+
+- Claude Opus 4.6
+- Juan Pelaez
+
 ## 13.4.0 (2026-03-09)
 
 ### 🚀 Features

package/dist/index.esm.js

@@ -55,6 +55,7 @@ export { blockOnboarding as onboarding };
 import { createUniversityBlock } from '@23blocks/block-university';
 import * as blockUniversity from '@23blocks/block-university';
 export { blockUniversity as university };
+import { BlockErrorException } from '@23blocks/contracts';
 export * from '@23blocks/contracts';
 export * from '@23blocks/jsonapi-codec';
 import * as blockRag from '@23blocks/block-rag';
@@ -204,6 +205,258 @@ export { blockRag as rag };
     };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// JWT Decode Utility
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Decode the `exp` claim from a JWT without external dependencies.
+ * Returns the expiry as a Unix timestamp (seconds), or null if unavailable.
+ */ function decodeJwtExp(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3) return null;
+        // Base64url → Base64
+        let payload = parts[1];
+        payload = payload.replace(/-/g, '+').replace(/_/g, '/');
+        // Pad to multiple of 4
+        const pad = payload.length % 4;
+        if (pad) {
+            payload += '='.repeat(4 - pad);
+        }
+        // Decode — works in browser (atob) and Node 16+ (Buffer)
+        let decoded;
+        if (typeof atob === 'function') {
+            decoded = atob(payload);
+        } else if (typeof Buffer !== 'undefined') {
+            decoded = Buffer.from(payload, 'base64').toString('utf-8');
+        } else {
+            return null;
+        }
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed.exp === 'number') {
+            return parsed.exp;
+        }
+        return null;
+    } catch (e) {
+        return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Lifecycle Manager Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a token lifecycle manager that automatically refreshes tokens,
+ * handles tab visibility, and notifies listeners of auth state changes.
+ *
+ * @param tokenManager - Token storage (read/write tokens)
+ * @param refreshFn - Function to call the backend refresh endpoint
+ * @param config - Lifecycle configuration
+ */ function createTokenLifecycleManager(tokenManager, refreshFn, config = {}) {
+    const { refreshBufferSeconds = 120, enableVisibilityRefresh = true, enableProactiveRefresh = true } = config;
+    const listeners = new Set();
+    let refreshTimer = null;
+    let refreshPromise = null;
+    let visibilityHandler = null;
+    let destroyed = false;
+    let running = false;
+    function notify(event) {
+        listeners.forEach((listener)=>{
+            try {
+                listener(event);
+            } catch (e) {
+            // Listener errors should not break the lifecycle
+            }
+        });
+    }
+    function clearTimer() {
+        if (refreshTimer !== null) {
+            clearTimeout(refreshTimer);
+            refreshTimer = null;
+        }
+    }
+    function scheduleRefresh() {
+        if (!enableProactiveRefresh || destroyed || !running) return;
+        clearTimer();
+        const accessToken = tokenManager.getAccessToken();
+        if (!accessToken) return;
+        const exp = decodeJwtExp(accessToken);
+        if (!exp) return;
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const secondsUntilExpiry = exp - nowSeconds;
+        const refreshInSeconds = secondsUntilExpiry - refreshBufferSeconds;
+        if (refreshInSeconds <= 0) {
+            // Token is already expired or within buffer — refresh immediately
+            refreshNow().catch(()=>{
+            // Error handled inside refreshNow
+            });
+            return;
+        }
+        refreshTimer = setTimeout(()=>{
+            if (!destroyed && running) {
+                refreshNow().catch(()=>{
+                // Error handled inside refreshNow
+                });
+            }
+        }, refreshInSeconds * 1000);
+    }
+    function handleVisibilityChange() {
+        if (destroyed || !running) return;
+        if (typeof document === 'undefined') return;
+        if (document.visibilityState === 'visible') {
+            const accessToken = tokenManager.getAccessToken();
+            if (!accessToken) return;
+            const exp = decodeJwtExp(accessToken);
+            if (!exp) {
+                // No exp claim — refresh to be safe
+                refreshNow().catch(()=>{});
+                return;
+            }
+            const nowSeconds = Math.floor(Date.now() / 1000);
+            const secondsUntilExpiry = exp - nowSeconds;
+            // Refresh if expired or within buffer
+            if (secondsUntilExpiry <= refreshBufferSeconds) {
+                refreshNow().catch(()=>{});
+            } else {
+                // Reschedule proactive refresh (timer may have drifted during sleep)
+                scheduleRefresh();
+            }
+        }
+    }
+    function registerVisibilityListener() {
+        if (!enableVisibilityRefresh || !isBrowser$1() || visibilityHandler) return;
+        if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+            visibilityHandler = handleVisibilityChange;
+            document.addEventListener('visibilitychange', visibilityHandler);
+        }
+    }
+    function removeVisibilityListener() {
+        if (visibilityHandler && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', visibilityHandler);
+            visibilityHandler = null;
+        }
+    }
+    async function refreshNow() {
+        if (destroyed) {
+            throw new Error('[23blocks] Token lifecycle manager has been destroyed');
+        }
+        // Concurrency lock — all callers share the same in-flight promise
+        if (refreshPromise) {
+            return refreshPromise;
+        }
+        refreshPromise = (async ()=>{
+            try {
+                const refreshToken = tokenManager.getRefreshToken();
+                if (!refreshToken) {
+                    throw new Error('No refresh token available');
+                }
+                const result = await refreshFn(refreshToken);
+                // Guard: don't store tokens if lifecycle was stopped/destroyed during the async call
+                if (!running || destroyed) {
+                    return result.accessToken;
+                }
+                // Store new tokens
+                tokenManager.setTokens(result.accessToken, result.refreshToken);
+                // Reschedule proactive refresh
+                scheduleRefresh();
+                notify('TOKEN_REFRESHED');
+                return result.accessToken;
+            } catch (error) {
+                // Refresh failed — session is dead
+                clearTimer();
+                tokenManager.clearTokens();
+                running = false;
+                notify('SESSION_EXPIRED');
+                throw error;
+            } finally{
+                refreshPromise = null;
+            }
+        })();
+        return refreshPromise;
+    }
+    function start() {
+        if (destroyed) return;
+        running = true;
+        scheduleRefresh();
+        registerVisibilityListener();
+        notify('SIGNED_IN');
+    }
+    function stop() {
+        running = false;
+        clearTimer();
+        refreshPromise = null;
+        notify('SIGNED_OUT');
+    }
+    function destroy() {
+        destroyed = true;
+        stop();
+        removeVisibilityListener();
+        listeners.clear();
+    }
+    function onAuthStateChanged(listener) {
+        listeners.add(listener);
+        return ()=>{
+            listeners.delete(listener);
+        };
+    }
+    return {
+        start,
+        stop,
+        onAuthStateChanged,
+        refreshNow,
+        destroy
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Retrying Transport Wrapper
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Wrap a transport with automatic 401 retry via token refresh.
+ *
+ * On a 401 BlockErrorException, the wrapper calls `getLifecycle().refreshNow()`
+ * to obtain a fresh token, then retries the request once.
+ *
+ * @param baseTransport - The underlying HTTP transport
+ * @param getLifecycle - Lazy getter for the lifecycle manager (supports React refs and late init)
+ */ function createRetryingTransport(baseTransport, getLifecycle) {
+    async function withRetry(fn) {
+        try {
+            return await fn();
+        } catch (error) {
+            if (error instanceof BlockErrorException && error.status === 401) {
+                const lifecycle = getLifecycle();
+                if (lifecycle) {
+                    try {
+                        await lifecycle.refreshNow();
+                        // Retry once — transport reads fresh token from tokenManager on next call
+                        return await fn();
+                    } catch (e) {
+                        // Refresh failed — throw original 401
+                        throw error;
+                    }
+                }
+            }
+            throw error;
+        }
+    }
+    return {
+        get (path, options) {
+            return withRetry(()=>baseTransport.get(path, options));
+        },
+        post (path, body, options) {
+            return withRetry(()=>baseTransport.post(path, body, options));
+        },
+        patch (path, body, options) {
+            return withRetry(()=>baseTransport.patch(path, body, options));
+        },
+        put (path, body, options) {
+            return withRetry(()=>baseTransport.put(path, body, options));
+        },
+        delete (path, options) {
+            return withRetry(()=>baseTransport.delete(path, options));
+        }
+    };
+}
+
 /**
  * Detect browser environment.
  * Uses try/catch to handle edge runtimes (Lambda@Edge, Cloudflare Workers)
@@ -269,7 +522,7 @@ export { blockRag as rag };
  * });
  * ```
  */ function create23BlocksClient(config) {
-    const { urls, apiKey, tenantId, authMode = 'token', storage = isBrowser() ? 'localStorage' : 'memory', headers: staticHeaders = {}, timeout } = config;
+    const { urls, apiKey, tenantId, authMode = 'token', storage = isBrowser() ? 'localStorage' : 'memory', headers: staticHeaders = {}, timeout, tokenLifecycle: lifecycleConfig = {} } = config;
     // Create token manager for token mode
     let tokenManager = null;
     if (authMode === 'token') {
@@ -279,8 +532,11 @@ export { blockRag as rag };
             storage
         });
     }
-    // Factory to create transport for a specific service URL
-    function createServiceTransport(baseUrl) {
+    // Token lifecycle manager (created lazily after auth block exists)
+    let lifecycle = null;
+    const lifecycleEnabled = authMode === 'token' && lifecycleConfig !== false;
+    // Factory to create base transport for a specific service URL
+    function createBaseTransport(baseUrl) {
         return createHttpTransport({
             baseUrl,
             timeout,
@@ -303,6 +559,14 @@ export { blockRag as rag };
             }
         });
     }
+    // Factory to create transport with optional 401 retry
+    function createServiceTransport(baseUrl) {
+        const base = createBaseTransport(baseUrl);
+        if (lifecycleEnabled) {
+            return createRetryingTransport(base, ()=>lifecycle);
+        }
+        return base;
+    }
     // Helper to create a proxy that throws when accessing unconfigured service
     function createUnconfiguredServiceProxy(serviceName, urlKey) {
         return new Proxy({}, {
@@ -335,12 +599,33 @@ export { blockRag as rag };
     const jarvisBlock = urls.jarvis ? createJarvisBlock(createServiceTransport(urls.jarvis), blockConfig) : null;
     const onboardingBlock = urls.onboarding ? createOnboardingBlock(createServiceTransport(urls.onboarding), blockConfig) : null;
     const universityBlock = urls.university ? createUniversityBlock(createServiceTransport(urls.university), blockConfig) : null;
+    // Create lifecycle manager if enabled and auth block is available
+    if (lifecycleEnabled && tokenManager && urls.authentication) {
+        // Dedicated transport for refresh calls — NOT wrapped with retry to avoid circular 401 handling
+        const refreshAuthBlock = createAuthenticationBlock(createBaseTransport(urls.authentication), blockConfig);
+        const lifecycleRefreshFn = async (refreshToken)=>{
+            const response = await refreshAuthBlock.auth.refreshToken({
+                refreshToken
+            });
+            return {
+                accessToken: response.accessToken,
+                refreshToken: response.refreshToken,
+                expiresIn: response.expiresIn
+            };
+        };
+        lifecycle = createTokenLifecycleManager(tokenManager, lifecycleRefreshFn, typeof lifecycleConfig === 'object' ? lifecycleConfig : {});
+        // Auto-start if tokens already exist (page reload scenario)
+        if (tokenManager.getAccessToken() && tokenManager.getRefreshToken()) {
+            lifecycle.start();
+        }
+    }
     // Create managed auth service with automatic token handling (only if auth URL configured)
     const managedAuth = authenticationBlock ? {
         async signIn (request) {
             const response = await authenticationBlock.auth.signIn(request);
             if (authMode === 'token' && tokenManager && response.accessToken) {
                 tokenManager.setTokens(response.accessToken, response.refreshToken);
+                lifecycle == null ? void 0 : lifecycle.start();
             }
             return response;
         },
@@ -348,10 +633,12 @@ export { blockRag as rag };
             const response = await authenticationBlock.auth.signUp(request);
             if (authMode === 'token' && tokenManager && response.accessToken) {
                 tokenManager.setTokens(response.accessToken);
+                lifecycle == null ? void 0 : lifecycle.start();
             }
             return response;
         },
         async signOut () {
+            lifecycle == null ? void 0 : lifecycle.stop();
             await authenticationBlock.auth.signOut();
             if (authMode === 'token' && tokenManager) {
                 tokenManager.clearTokens();
@@ -361,6 +648,7 @@ export { blockRag as rag };
             const response = await authenticationBlock.auth.verifyMagicLink(request);
             if (authMode === 'token' && tokenManager && response.accessToken) {
                 tokenManager.setTokens(response.accessToken, response.refreshToken);
+                lifecycle == null ? void 0 : lifecycle.start();
             }
             return response;
         },
@@ -368,6 +656,7 @@ export { blockRag as rag };
             const response = await authenticationBlock.auth.acceptInvitation(request);
             if (authMode === 'token' && tokenManager && response.accessToken) {
                 tokenManager.setTokens(response.accessToken, response.refreshToken);
+                lifecycle == null ? void 0 : lifecycle.start();
             }
             return response;
         },
@@ -375,6 +664,7 @@ export { blockRag as rag };
             const response = await authenticationBlock.auth.verifyPasswordOtp(request);
             if (authMode === 'token' && tokenManager && response.accessToken) {
                 tokenManager.setTokens(response.accessToken, response.refreshToken);
+                lifecycle == null ? void 0 : lifecycle.start();
             }
             return response;
         },
@@ -445,8 +735,25 @@ export { blockRag as rag };
                 return null;
             }
             return tokenManager ? !!tokenManager.getAccessToken() : false;
+        },
+        onAuthStateChanged (listener) {
+            if (lifecycle) {
+                return lifecycle.onAuthStateChanged(listener);
+            }
+            // No lifecycle — return no-op unsubscribe
+            return ()=>{};
+        },
+        async refreshSession () {
+            if (!lifecycle) {
+                throw new Error('[23blocks] Token lifecycle is not available. ' + 'Ensure authMode is "token" and tokenLifecycle is not disabled.');
+            }
+            return lifecycle.refreshNow();
+        },
+        destroy () {
+            lifecycle == null ? void 0 : lifecycle.destroy();
+            lifecycle = null;
         }
     };
 }
 
-export { create23BlocksClient, createTokenManager };
+export { create23BlocksClient, createRetryingTransport, createTokenLifecycleManager, createTokenManager, isBrowser$1 as isBrowser };

package/dist/src/lib/client.d.ts

@@ -17,6 +17,7 @@ import { type JarvisBlock } from '@23blocks/block-jarvis';
 import { type OnboardingBlock } from '@23blocks/block-onboarding';
 import { type UniversityBlock } from '@23blocks/block-university';
 import { type StorageType } from './token-manager.js';
+import { type TokenLifecycleConfig, type AuthStateListener } from './token-lifecycle.js';
 /**
  * Authentication mode
  * - 'token': Store tokens in browser storage, attach Authorization header
@@ -114,6 +115,16 @@ export interface ClientConfig {
      * @default 30000
      */
     timeout?: number;
+    /**
+     * Token lifecycle configuration for automatic refresh and 401 retry.
+     * - Pass an object to customize (e.g., `{ refreshBufferSeconds: 60 }`)
+     * - Pass `false` to disable entirely
+     * - Omit or pass `{}` to use defaults (enabled with 120s buffer)
+     *
+     * Only applies in token mode. Ignored in cookie mode.
+     * @default {} (enabled with defaults)
+     */
+    tokenLifecycle?: TokenLifecycleConfig | false;
 }
 /**
  * Auth service wrapper with automatic token management
@@ -286,6 +297,22 @@ export interface Blocks23Client {
      * In cookie mode: always returns null (check with validateToken instead)
      */
     isAuthenticated(): boolean | null;
+    /**
+     * Subscribe to auth state changes (token refreshed, session expired, etc.).
+     * Returns an unsubscribe function.
+     * Only active when tokenLifecycle is enabled (token mode).
+     */
+    onAuthStateChanged(listener: AuthStateListener): () => void;
+    /**
+     * Force an immediate token refresh.
+     * Returns the new access token. Throws if no lifecycle or refresh fails.
+     */
+    refreshSession(): Promise<string>;
+    /**
+     * Destroy the client — stops lifecycle timers and cleans up listeners.
+     * Call when the client is no longer needed (e.g., component unmount).
+     */
+    destroy(): void;
 }
 /**
  * Create a 23blocks client instance

package/dist/src/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/client.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC5F,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAClG,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACzF,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAEzF,OAAO,EAAsB,KAAK,WAAW,EAAqB,MAAM,oBAAoB,CAAC;AAE7F;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,WAAW,CAAC;IAElB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;IAC3K;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAExD;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAExD;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAE1E;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAE5E;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/E;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAK7B;;;OAGG;IACH,IAAI,EAAE,kBAAkB,CAAC;IAEzB;;;OAGG;IACH,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAEpC;;;OAGG;IACH,KAAK,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAEpC;;;OAGG;IACH,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAExC;;;OAGG;IACH,cAAc,EAAE,mBAAmB,CAAC;IAEpC;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;IAExB;;;OAGG;IACH,GAAG,EAAE,QAAQ,CAAC;IAEd;;;OAGG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,WAAW,EAAE,gBAAgB,CAAC;IAE9B;;;OAGG;IACH,aAAa,EAAE,kBAAkB,CAAC;IAElC;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAC;IAElB;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAC;IAElB;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;;OAGG;IACH,SAAS,EAAE,cAAc,CAAC;IAE1B;;;OAGG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAC;IAElB;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;;OAGG;IACH,UAAU,EAAE,eAAe,CAAC;IAE5B;;;OAGG;IACH,UAAU,EAAE,eAAe,CAAC;IAM5B;;;OAGG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI,CAAC;IAEhC;;;OAGG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;;OAGG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5D;;OAEG;IACH,YAAY,IAAI,IAAI,CAAC;IAErB;;;;OAIG;IACH,eAAe,IAAI,OAAO,GAAG,IAAI,CAAC;CACnC;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAyQzE;AAGD,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/client.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/sdk.d.ts

@@ -1,5 +1,6 @@
 export { create23BlocksClient, type AuthMode, type ClientConfig, type ServiceUrls, type Blocks23Client, type ManagedAuthService, type StorageType, type TokenManager, } from './client.js';
-export { createTokenManager } from './token-manager.js';
+export { createTokenManager, isBrowser } from './token-manager.js';
+export { createTokenLifecycleManager, createRetryingTransport, type AuthStateEvent, type AuthStateListener, type RefreshTokenFn, type TokenLifecycleConfig, type TokenLifecycleManager, } from './token-lifecycle.js';
 export * from '@23blocks/contracts';
 export * from '@23blocks/jsonapi-codec';
 export * from '@23blocks/transport-http';

package/dist/src/lib/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/lib/sdk.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAMxD,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AAqBzC,OAAO,KAAK,cAAc,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAC;AACnD,OAAO,KAAK,WAAW,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,aAAa,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,KAAK,MAAM,uBAAuB,CAAC;AAC/C,OAAO,KAAK,KAAK,MAAM,uBAAuB,CAAC;AAC/C,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,SAAS,MAAM,2BAA2B,CAAC;AACvD,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAC;AACnD,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAC;AACnD,OAAO,KAAK,KAAK,MAAM,uBAAuB,CAAC;AAC/C,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/lib/sdk.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAM9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AAqBzC,OAAO,KAAK,cAAc,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAC;AACnD,OAAO,KAAK,WAAW,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,aAAa,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,KAAK,MAAM,uBAAuB,CAAC;AAC/C,OAAO,KAAK,KAAK,MAAM,uBAAuB,CAAC;AAC/C,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,SAAS,MAAM,2BAA2B,CAAC;AACvD,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAC;AACnD,OAAO,KAAK,OAAO,MAAM,yBAAyB,CAAC;AACnD,OAAO,KAAK,KAAK,MAAM,uBAAuB,CAAC;AAC/C,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC"}

package/dist/src/lib/token-lifecycle.d.ts

@@ -0,0 +1,95 @@
+import type { Transport } from '@23blocks/contracts';
+import type { TokenManager } from './token-manager.js';
+/**
+ * Auth state change events emitted by the lifecycle manager.
+ *
+ * - `SIGNED_IN` — User signed in and lifecycle started
+ * - `SIGNED_OUT` — User signed out and lifecycle stopped
+ * - `TOKEN_REFRESHED` — Access token was silently refreshed
+ * - `SESSION_EXPIRED` — Refresh failed, tokens cleared, user must re-authenticate
+ */
+export type AuthStateEvent = 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'SESSION_EXPIRED';
+/**
+ * Callback invoked when auth state changes
+ */
+export type AuthStateListener = (event: AuthStateEvent) => void;
+/**
+ * Function that performs the actual token refresh against the backend.
+ * Accepts the current refresh token and returns new credentials.
+ */
+export type RefreshTokenFn = (refreshToken: string) => Promise<{
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+}>;
+/**
+ * Configuration for automatic token lifecycle management
+ */
+export interface TokenLifecycleConfig {
+    /**
+     * Seconds before token expiry to trigger a proactive refresh.
+     * @default 120
+     */
+    refreshBufferSeconds?: number;
+    /**
+     * Refresh token when tab becomes visible (handles laptop sleep/wake).
+     * @default true
+     */
+    enableVisibilityRefresh?: boolean;
+    /**
+     * Schedule proactive refresh based on JWT `exp` claim.
+     * @default true
+     */
+    enableProactiveRefresh?: boolean;
+}
+/**
+ * Token lifecycle manager interface.
+ * Manages automatic token refresh, tab visibility sync, and auth state notifications.
+ */
+export interface TokenLifecycleManager {
+    /**
+     * Start the lifecycle — schedule proactive refresh and register visibility listener.
+     * Call after successful sign-in.
+     */
+    start(): void;
+    /**
+     * Stop the lifecycle — clear timers and listeners but keep the manager reusable.
+     * Call on sign-out.
+     */
+    stop(): void;
+    /**
+     * Subscribe to auth state changes.
+     * Returns an unsubscribe function.
+     */
+    onAuthStateChanged(listener: AuthStateListener): () => void;
+    /**
+     * Force an immediate token refresh.
+     * Multiple concurrent calls share the same in-flight promise (concurrency lock).
+     * Returns the new access token on success.
+     */
+    refreshNow(): Promise<string>;
+    /**
+     * Permanently destroy the manager — clears everything and prevents reuse.
+     */
+    destroy(): void;
+}
+/**
+ * Create a token lifecycle manager that automatically refreshes tokens,
+ * handles tab visibility, and notifies listeners of auth state changes.
+ *
+ * @param tokenManager - Token storage (read/write tokens)
+ * @param refreshFn - Function to call the backend refresh endpoint
+ * @param config - Lifecycle configuration
+ */
+export declare function createTokenLifecycleManager(tokenManager: TokenManager, refreshFn: RefreshTokenFn, config?: TokenLifecycleConfig): TokenLifecycleManager;
+/**
+ * Wrap a transport with automatic 401 retry via token refresh.
+ *
+ * On a 401 BlockErrorException, the wrapper calls `getLifecycle().refreshNow()`
+ * to obtain a fresh token, then retries the request once.
+ *
+ * @param baseTransport - The underlying HTTP transport
+ * @param getLifecycle - Lazy getter for the lifecycle manager (supports React refs and late init)
+ */
+export declare function createRetryingTransport(baseTransport: Transport, getLifecycle: () => TokenLifecycleManager | null): Transport;
+//# sourceMappingURL=token-lifecycle.d.ts.map

package/dist/src/lib/token-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/lib/token-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,qBAAqB,CAAC;AAErE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOvD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAEhG;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;;OAGG;IACH,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAC;IAE5D;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9B;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAiDD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,cAAc,EACzB,MAAM,GAAE,oBAAyB,GAChC,qBAAqB,CA8LvB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,SAAS,EACxB,YAAY,EAAE,MAAM,qBAAqB,GAAG,IAAI,GAC/C,SAAS,CAuCX"}

package/dist/src/lib/token-manager.d.ts

@@ -47,6 +47,12 @@ export interface TokenManager {
      */
     onStorageChange(callback: () => void): () => void;
 }
+/**
+ * Detect if we're running in a browser environment.
+ * Uses try/catch to handle edge runtimes (Lambda@Edge, Cloudflare Workers)
+ * that may throw on property access.
+ */
+export declare function isBrowser(): boolean;
 /**
  * Create a token manager instance
  *

package/dist/src/lib/token-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../../src/lib/token-manager.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,gBAAgB,GAAG,QAAQ,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI,CAAC;IAEhC;;OAEG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;OAEG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5D;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CACnD;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAwE3E"}
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../../src/lib/token-manager.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,gBAAgB,GAAG,QAAQ,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI,CAAC;IAEhC;;OAEG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;OAEG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5D;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CACnD;AA6BD;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,OAAO,CASnC;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAwE3E"}

package/llms.txt

@@ -294,6 +294,33 @@ The client provides:
 - `client.authentication` - Full authentication block
 - `client.{blockName}` - All other blocks
 - `client.getAccessToken()`, `client.setTokens()`, `client.clearSession()` - Token utilities
+- `client.onAuthStateChanged(listener)` - Subscribe to auth state changes (TOKEN_REFRESHED, SESSION_EXPIRED)
+- `client.refreshSession()` - Force immediate token refresh
+- `client.destroy()` - Cleanup lifecycle timers and listeners
+
+### Token Lifecycle (Auto-Refresh & 401 Retry)
+
+Enabled by default in token mode. Handles:
+- **Proactive refresh** - Decodes JWT `exp`, schedules refresh 120s before expiry
+- **401 retry** - On 401 errors, refreshes token and retries the request once
+- **Tab visibility** - Refreshes stale tokens when tab becomes visible (laptop sleep/wake)
+- **Concurrency lock** - Multiple simultaneous 401s share a single refresh call
+- **Session expiry** - Clears tokens and emits SESSION_EXPIRED if refresh fails
+
+Auth events: `SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`, `SESSION_EXPIRED`
+
+```typescript
+// Disable lifecycle
+const client = create23BlocksClient({ ..., tokenLifecycle: false });
+
+// Custom config
+const client = create23BlocksClient({ ..., tokenLifecycle: { refreshBufferSeconds: 60 } });
+
+// Listen for events
+const unsub = client.onAuthStateChanged((event) => {
+  if (event === 'SESSION_EXPIRED') redirectToLogin();
+});
+```
 
 ## Health Check
 
@@ -546,23 +573,36 @@ const [authHealth, crmHealth] = await Promise.all([
 ## React Integration
 
 ```typescript
-import { Blocks23Provider, useAuth, useSearch, useRagBlock } from '@23blocks/react';
+import { Provider, useAuth, useClient } from '@23blocks/react';
 
 function App() {
   return (
-    <Blocks23Provider config={{
-      apiKey: 'your-api-key',
-      urls: { authentication: '...', search: '...' },
-    }}>
+    <Provider
+      apiKey="your-api-key"
+      urls={{ authentication: '...', crm: '...', search: '...' }}
+      // tokenLifecycle enabled by default in token mode
+    >
       <MyComponent />
-    </Blocks23Provider>
+    </Provider>
   );
 }
 
 function MyComponent() {
-  const auth = useAuth();        // AuthenticationBlock
-  const search = useSearch();    // SearchBlock
-  // Blocks are memoized - stable references across re-renders
+  const { signIn, signOut, isAuthenticated, onAuthStateChanged, refreshSession } = useAuth();
+  const { crm, search } = useClient();
+
+  // Token lifecycle is automatic:
+  // - Proactive refresh before JWT expiry
+  // - 401 retry with token refresh
+  // - Tab visibility refresh (laptop sleep/wake)
+  // - SESSION_EXPIRED event when refresh fails
+
+  useEffect(() => {
+    const unsub = onAuthStateChanged((event) => {
+      if (event === 'SESSION_EXPIRED') router.push('/login');
+    });
+    return unsub;
+  }, [onAuthStateChanged]);
 }
 ```
 
@@ -577,6 +617,7 @@ export const appConfig = {
     provideBlocks23({
       apiKey: 'your-api-key',
       urls: { authentication: '...', crm: '...' },
+      // tokenLifecycle enabled by default in token mode
     }),
   ],
 };
@@ -589,8 +630,16 @@ export class MyComponent {
   private auth = inject(AuthenticationService);
   private crm = inject(CrmService);
 
-  // Angular services delegate to block sub-services via typed getters
+  // Auth-flow methods return Observables with automatic token + lifecycle management:
+  // auth.signIn({ email, password }).subscribe(...)
+  // auth.signOut().subscribe(...)
+
+  // Sub-services are Promise-based getters:
   // auth.users.list() returns Promise<PageResult<User>>
-  // auth.auth.signIn() wraps in Observable with token management
+  // auth.roles.list() returns Promise<PageResult<Role>>
+
+  // Token lifecycle:
+  // auth.onAuthStateChanged(event => { ... }) — subscribe to SIGNED_IN, TOKEN_REFRESHED, SESSION_EXPIRED
+  // auth.refreshSession() — force immediate token refresh
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@23blocks/sdk",
-  "version": "13.4.0",
+  "version": "13.5.1",
   "description": "23blocks SDK - unified meta-package re-exporting all blocks and utilities",
   "license": "MIT",
   "author": "23blocks <hello@23blocks.com>",