@insforge/sdk 1.4.3 → 1.4.5-beta.0

package/dist/ssr.js

@@ -94,7 +94,9 @@ function redactHeaders(headers) {
   return redacted;
 }
 function sanitizeBody(body) {
-  if (body === null || body === void 0) return body;
+  if (body === null || body === void 0) {
+    return body;
+  }
   if (typeof body === "string") {
     try {
       const parsed = JSON.parse(body);
@@ -103,7 +105,9 @@ function sanitizeBody(body) {
       return body;
     }
   }
-  if (Array.isArray(body)) return body.map(sanitizeBody);
+  if (Array.isArray(body)) {
+    return body.map(sanitizeBody);
+  }
   if (typeof body === "object") {
     const sanitized = {};
     for (const [key, value] of Object.entries(body)) {
@@ -118,7 +122,9 @@ function sanitizeBody(body) {
   return body;
 }
 function formatBody(body) {
-  if (body === void 0 || body === null) return "";
+  if (body === void 0 || body === null) {
+    return "";
+  }
   if (typeof body === "string") {
     try {
       return JSON.stringify(JSON.parse(body), null, 2);
@@ -155,7 +161,9 @@ var Logger = class {
    * @param args - Additional arguments to pass to the log function
    */
   log(message, ...args) {
-    if (!this.enabled) return;
+    if (!this.enabled) {
+      return;
+    }
     const formatted = `[InsForge Debug] ${message}`;
     if (this.customLog) {
       this.customLog(formatted, ...args);
@@ -169,7 +177,9 @@ var Logger = class {
    * @param args - Additional arguments to pass to the log function
    */
   warn(message, ...args) {
-    if (!this.enabled) return;
+    if (!this.enabled) {
+      return;
+    }
     const formatted = `[InsForge Debug] ${message}`;
     if (this.customLog) {
       this.customLog(formatted, ...args);
@@ -183,7 +193,9 @@ var Logger = class {
    * @param args - Additional arguments to pass to the log function
    */
   error(message, ...args) {
-    if (!this.enabled) return;
+    if (!this.enabled) {
+      return;
+    }
     const formatted = `[InsForge Debug] ${message}`;
     if (this.customLog) {
       this.customLog(formatted, ...args);
@@ -200,10 +212,10 @@ var Logger = class {
    * @param body - Request body (sensitive fields will be masked)
    */
   logRequest(method, url, headers, body) {
-    if (!this.enabled) return;
-    const parts = [
-      `\u2192 ${method} ${url}`
-    ];
+    if (!this.enabled) {
+      return;
+    }
+    const parts = [`\u2192 ${method} ${url}`];
     if (headers && Object.keys(headers).length > 0) {
       parts.push(`  Headers: ${JSON.stringify(redactHeaders(headers))}`);
     }
@@ -224,10 +236,10 @@ var Logger = class {
    * @param body - Response body (sensitive fields will be masked, large bodies truncated)
    */
   logResponse(method, url, status, durationMs, body) {
-    if (!this.enabled) return;
-    const parts = [
-      `\u2190 ${method} ${url} ${status} (${durationMs}ms)`
-    ];
+    if (!this.enabled) {
+      return;
+    }
+    const parts = [`\u2190 ${method} ${url} ${status} (${durationMs}ms)`];
     const formattedBody = formatBody(sanitizeBody(body));
     if (formattedBody) {
       const truncated = formattedBody.length > 1e3 ? formattedBody.slice(0, 1e3) + "... [truncated]" : formattedBody;
@@ -242,21 +254,34 @@ var Logger = class {
 };
 
 // src/lib/token-manager.ts
+var AuthChangeEvent = {
+  SIGNED_IN: "signedIn",
+  SIGNED_OUT: "signedOut",
+  TOKEN_REFRESHED: "tokenRefreshed"
+};
 var CSRF_TOKEN_COOKIE = "insforge_csrf_token";
 function getCsrfToken() {
-  if (typeof document === "undefined") return null;
+  if (typeof document === "undefined") {
+    return null;
+  }
   const match = document.cookie.split(";").find((c) => c.trim().startsWith(`${CSRF_TOKEN_COOKIE}=`));
-  if (!match) return null;
+  if (!match) {
+    return null;
+  }
   return match.split("=")[1] || null;
 }
 function setCsrfToken(token) {
-  if (typeof document === "undefined") return;
+  if (typeof document === "undefined") {
+    return;
+  }
   const maxAge = 7 * 24 * 60 * 60;
   const secure = typeof window !== "undefined" && window.location.protocol === "https:" ? "; Secure" : "";
   document.cookie = `${CSRF_TOKEN_COOKIE}=${encodeURIComponent(token)}; path=/; max-age=${maxAge}; SameSite=Lax${secure}`;
 }
 function clearCsrfToken() {
-  if (typeof document === "undefined") return;
+  if (typeof document === "undefined") {
+    return;
+  }
   const secure = typeof window !== "undefined" && window.location.protocol === "https:" ? "; Secure" : "";
   document.cookie = `${CSRF_TOKEN_COOKIE}=; path=/; max-age=0; SameSite=Lax${secure}`;
 }
@@ -265,25 +290,26 @@ var TokenManager = class {
     // In-memory storage
     this.accessToken = null;
     this.user = null;
-    // Callback for token changes (used by realtime to reconnect with new token)
-    this.onTokenChange = null;
+    this.authStateChangeCallbacks = /* @__PURE__ */ new Map();
   }
   /**
    * Save session in memory
    */
-  saveSession(session) {
+  saveSession(session, event = AuthChangeEvent.SIGNED_IN) {
     const tokenChanged = session.accessToken !== this.accessToken;
     this.accessToken = session.accessToken;
     this.user = session.user;
-    if (tokenChanged && this.onTokenChange) {
-      this.onTokenChange();
+    if (tokenChanged) {
+      this.notifyAuthStateChange(event);
     }
   }
   /**
    * Get current session
    */
   getSession() {
-    if (!this.accessToken || !this.user) return null;
+    if (!this.accessToken || !this.user) {
+      return null;
+    }
     return {
       accessToken: this.accessToken,
       user: this.user
@@ -298,11 +324,11 @@ var TokenManager = class {
   /**
    * Set access token
    */
-  setAccessToken(token) {
+  setAccessToken(token, event = AuthChangeEvent.SIGNED_IN) {
     const tokenChanged = token !== this.accessToken;
     this.accessToken = token;
-    if (tokenChanged && this.onTokenChange) {
-      this.onTokenChange();
+    if (tokenChanged) {
+      this.notifyAuthStateChange(event);
     }
   }
   /**
@@ -324,22 +350,74 @@ var TokenManager = class {
     const hadToken = this.accessToken !== null;
     this.accessToken = null;
     this.user = null;
-    if (hadToken && this.onTokenChange) {
-      this.onTokenChange();
+    if (hadToken) {
+      this.notifyAuthStateChange(AuthChangeEvent.SIGNED_OUT);
+    }
+  }
+  onAuthStateChange(callback) {
+    const id = Symbol("auth-state-change");
+    this.authStateChangeCallbacks.set(id, callback);
+    return () => this.authStateChangeCallbacks.delete(id);
+  }
+  notifyAuthStateChange(event) {
+    for (const callback of this.authStateChangeCallbacks.values()) {
+      try {
+        callback(event);
+      } catch (error) {
+        console.error("Error in auth state change callback:", error);
+      }
     }
   }
 };
 
+// src/lib/jwt.ts
+function decodeBase64Url(input) {
+  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized.padEnd(normalized.length + (4 - normalized.length % 4) % 4, "=");
+  const binary = atob(padded);
+  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+function getJwtExpiration(token) {
+  if (!token) {
+    return null;
+  }
+  const [, payload] = token.split(".");
+  if (!payload) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(decodeBase64Url(payload));
+    if (typeof parsed.exp !== "number" || !Number.isFinite(parsed.exp)) {
+      return null;
+    }
+    return new Date(parsed.exp * 1e3);
+  } catch {
+    return null;
+  }
+}
+function isJwtExpiredOrExpiring(token, leewaySeconds = 60) {
+  if (!token) {
+    return false;
+  }
+  const expires = getJwtExpiration(token);
+  if (!expires) {
+    return true;
+  }
+  return expires.getTime() <= Date.now() + leewaySeconds * 1e3;
+}
+
 // src/lib/http-client.ts
 var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([500, 502, 503, 504]);
 var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
-var REFRESHABLE_AUTH_ERROR_CODES = /* @__PURE__ */ new Set([
-  "AUTH_UNAUTHORIZED",
-  "PGRST301"
-]);
+var REFRESHABLE_AUTH_ERROR_CODES = /* @__PURE__ */ new Set(["AUTH_UNAUTHORIZED", "PGRST301"]);
 function serializeBody(method, body, headers) {
-  if (body === void 0) return void 0;
-  if (method === "GET" || method === "HEAD") return void 0;
+  if (body === void 0) {
+    return void 0;
+  }
+  if (method === "GET" || method === "HEAD") {
+    return void 0;
+  }
   if (typeof FormData !== "undefined" && body instanceof FormData) {
     return body;
   }
@@ -347,7 +425,9 @@ function serializeBody(method, body, headers) {
   return JSON.stringify(body);
 }
 async function parseResponse(response) {
-  if (response.status === 204) return void 0;
+  if (response.status === 204) {
+    return void 0;
+  }
   let data;
   const contentType = response.headers.get("content-type");
   try {
@@ -449,31 +529,24 @@ var HttpClient = class {
     return statusCode === 401 && REFRESHABLE_AUTH_ERROR_CODES.has(errorCode ?? "") && !this.config.isServerMode && !this.config.accessToken && !this.config.edgeFunctionToken && !options.skipAuthRefresh && authToken !== null;
   }
   async fetchWithRetry(args) {
-    const {
-      method,
-      url,
-      headers,
-      body,
-      fetchOptions,
-      callerSignal,
-      maxAttempts
-    } = args;
+    const { method, url, headers, body, fetchOptions, callerSignal, maxAttempts } = args;
     let lastError;
     for (let attempt = 0; attempt <= maxAttempts; attempt++) {
       if (attempt > 0) {
         const delay = this.computeRetryDelay(attempt);
-        this.logger.warn(
-          `Retry ${attempt}/${maxAttempts} for ${method} ${url} in ${delay}ms`
-        );
-        if (callerSignal?.aborted) throw callerSignal.reason;
+        this.logger.warn(`Retry ${attempt}/${maxAttempts} for ${method} ${url} in ${delay}ms`);
+        if (callerSignal?.aborted) {
+          throw callerSignal.reason;
+        }
         await new Promise((resolve, reject) => {
           const onAbort = () => {
             clearTimeout(timer2);
             reject(callerSignal.reason);
           };
           const timer2 = setTimeout(() => {
-            if (callerSignal)
+            if (callerSignal) {
               callerSignal.removeEventListener("abort", onAbort);
+            }
             resolve();
           }, delay);
           if (callerSignal) {
@@ -515,7 +588,9 @@ var HttpClient = class {
           ...controller ? { signal: controller.signal } : {}
         });
         if (this.isRetryableStatus(response.status) && attempt < maxAttempts) {
-          if (timer !== void 0) clearTimeout(timer);
+          if (timer !== void 0) {
+            clearTimeout(timer);
+          }
           await response.body?.cancel();
           lastError = new InsForgeError(
             `Server error: ${response.status} ${response.statusText}`,
@@ -524,10 +599,14 @@ var HttpClient = class {
           );
           continue;
         }
-        if (timer !== void 0) clearTimeout(timer);
+        if (timer !== void 0) {
+          clearTimeout(timer);
+        }
         return response;
       } catch (err) {
-        if (timer !== void 0) clearTimeout(timer);
+        if (timer !== void 0) {
+          clearTimeout(timer);
+        }
         if (err?.name === "AbortError") {
           if (controller && controller.signal.aborted && this.timeout > 0 && !callerSignal?.aborted) {
             throw new InsForgeError(
@@ -549,11 +628,7 @@ var HttpClient = class {
         );
       }
     }
-    throw lastError || new InsForgeError(
-      "Request failed after all retry attempts",
-      0,
-      "NETWORK_ERROR"
-    );
+    throw lastError || new InsForgeError("Request failed after all retry attempts", 0, "NETWORK_ERROR");
   }
   /**
    * Performs an HTTP request with automatic retry and timeout handling.
@@ -633,31 +708,15 @@ var HttpClient = class {
       }
       throw err;
     }
-    this.logger.logResponse(
-      method,
-      url,
-      response.status,
-      Date.now() - startTime,
-      data
-    );
+    this.logger.logResponse(method, url, response.status, Date.now() - startTime, data);
     return data;
   }
   async request(method, path, options = {}) {
     const tokenUsed = this.userToken;
     try {
-      return await this.handleRequest(
-        method,
-        path,
-        { ...options },
-        tokenUsed
-      );
+      return await this.handleRequest(method, path, { ...options }, tokenUsed);
     } catch (error) {
-      if (!(error instanceof InsForgeError) || !this.shouldRefreshAccessToken(
-        error.statusCode,
-        error.error,
-        tokenUsed,
-        options
-      )) {
+      if (!(error instanceof InsForgeError) || !this.shouldRefreshAccessToken(error.statusCode, error.error, tokenUsed, options)) {
         throw error;
       }
       if (tokenUsed !== this.userToken) {
@@ -742,12 +801,7 @@ var HttpClient = class {
       callerSignal,
       maxAttempts
     });
-    this.logger.logResponse(
-      method,
-      url,
-      response.status,
-      Date.now() - startTime
-    );
+    this.logger.logResponse(method, url, response.status, Date.now() - startTime);
     let errorCode = null;
     if (response.status === 401) {
       try {
@@ -761,12 +815,7 @@ var HttpClient = class {
       } catch {
       }
     }
-    if (!this.shouldRefreshAccessToken(
-      response.status,
-      errorCode,
-      tokenUsed,
-      options
-    )) {
+    if (!this.shouldRefreshAccessToken(response.status, errorCode, tokenUsed, options)) {
       return response;
     }
     if (tokenUsed !== this.userToken) {
@@ -860,10 +909,30 @@ var HttpClient = class {
     })();
     return this.refreshPromise;
   }
+  /** Returns a token safe to use for a new connection handshake. */
+  async getValidAccessToken(leewaySeconds = 60) {
+    const accessToken = this.tokenManager.getAccessToken() ?? this.userToken;
+    if (!accessToken || !isJwtExpiredOrExpiring(accessToken, leewaySeconds)) {
+      return accessToken;
+    }
+    const canRefresh = !this.config.isServerMode && !this.config.accessToken && !this.config.edgeFunctionToken && this.userToken !== null;
+    if (!canRefresh) {
+      return accessToken;
+    }
+    try {
+      const refreshed = await this.refreshAndSaveSession();
+      return refreshed.accessToken;
+    } catch (error) {
+      if (error instanceof InsForgeError && (error.statusCode === 401 || error.statusCode === 403) && this.userToken === accessToken) {
+        this.clearAuthSession();
+      }
+      throw error;
+    }
+  }
   async refreshAndSaveSession() {
     const newTokenData = await this.refreshAccessToken();
     this.setAuthToken(newTokenData.accessToken);
-    this.tokenManager.saveSession(newTokenData);
+    this.tokenManager.saveSession(newTokenData, AuthChangeEvent.TOKEN_REFRESHED);
     if (newTokenData.csrfToken) {
       setCsrfToken(newTokenData.csrfToken);
     }
@@ -959,11 +1028,15 @@ var Auth = class {
   isServerMode() {
     return !!this.options.isServerMode;
   }
+  /** Subscribe to SDK authentication state changes. */
+  onAuthStateChange(callback) {
+    return this.tokenManager.onAuthStateChange(callback);
+  }
   /**
    * Save session from API response
    * Handles token storage, CSRF token, and HTTP auth header
    */
-  saveSessionFromResponse(response) {
+  saveSessionFromResponse(response, event = AuthChangeEvent.SIGNED_IN) {
     if (!response.accessToken || !response.user) {
       return false;
     }
@@ -975,7 +1048,7 @@ var Auth = class {
       setCsrfToken(response.csrfToken);
     }
     if (!this.isServerMode()) {
-      this.tokenManager.saveSession(session);
+      this.tokenManager.saveSession(session, event);
     }
     this.http.setAuthToken(response.accessToken);
     this.http.setRefreshToken(response.refreshToken ?? null);
@@ -989,7 +1062,9 @@ var Auth = class {
    * Supports PKCE flow (insforge_code)
    */
   async detectAuthCallback() {
-    if (this.isServerMode() || typeof window === "undefined") return;
+    if (this.isServerMode() || typeof window === "undefined") {
+      return;
+    }
     try {
       const params = new URLSearchParams(window.location.search);
       const error = params.get("error");
@@ -1097,11 +1172,7 @@ var Auth = class {
       if (!signInOptions || !signInOptions.redirectTo) {
         return {
           data: {},
-          error: new InsForgeError(
-            "Redirect URI is required",
-            400,
-            import_shared_schemas.ERROR_CODES.INVALID_INPUT
-          )
+          error: new InsForgeError("Redirect URI is required", 400, import_shared_schemas.ERROR_CODES.INVALID_INPUT)
         };
       }
       const { provider } = signInOptions;
@@ -1176,10 +1247,7 @@ var Auth = class {
         error: null
       };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred during OAuth code exchange"
-      );
+      return wrapError(error, "An unexpected error occurred during OAuth code exchange");
     }
   }
   /**
@@ -1206,10 +1274,7 @@ var Auth = class {
         error: null
       };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred during ID token sign in"
-      );
+      return wrapError(error, "An unexpected error occurred during ID token sign in");
     }
   }
   // ============================================================================
@@ -1250,14 +1315,11 @@ var Auth = class {
         }
       );
       if (response.accessToken) {
-        this.saveSessionFromResponse(response);
+        this.saveSessionFromResponse(response, AuthChangeEvent.TOKEN_REFRESHED);
       }
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred during session refresh"
-      );
+      return wrapError(error, "An unexpected error occurred during session refresh");
     }
   }
   /**
@@ -1268,11 +1330,11 @@ var Auth = class {
     try {
       if (this.isServerMode()) {
         const accessToken = this.tokenManager.getAccessToken();
-        if (!accessToken) return { data: { user: null }, error: null };
+        if (!accessToken) {
+          return { data: { user: null }, error: null };
+        }
         this.http.setAuthToken(accessToken);
-        const response = await this.http.get(
-          "/api/auth/sessions/current"
-        );
+        const response = await this.http.get("/api/auth/sessions/current");
         const user = response.user ?? null;
         return { data: { user }, error: null };
       }
@@ -1310,25 +1372,17 @@ var Auth = class {
   // ============================================================================
   async getProfile(userId) {
     try {
-      const response = await this.http.get(
-        `/api/auth/profiles/${userId}`
-      );
+      const response = await this.http.get(`/api/auth/profiles/${userId}`);
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred while fetching user profile"
-      );
+      return wrapError(error, "An unexpected error occurred while fetching user profile");
     }
   }
   async setProfile(profile) {
     try {
-      const response = await this.http.patch(
-        "/api/auth/profiles/current",
-        {
-          profile
-        }
-      );
+      const response = await this.http.patch("/api/auth/profiles/current", {
+        profile
+      });
       const currentUser = this.tokenManager.getUser();
       if (!this.isServerMode() && currentUser && response.profile !== void 0) {
         this.tokenManager.setUser({
@@ -1338,10 +1392,7 @@ var Auth = class {
       }
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred while updating user profile"
-      );
+      return wrapError(error, "An unexpected error occurred while updating user profile");
     }
   }
   // ============================================================================
@@ -1354,10 +1405,7 @@ var Auth = class {
       });
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred while sending verification email"
-      );
+      return wrapError(error, "An unexpected error occurred while sending verification email");
     }
   }
   async verifyEmail(request) {
@@ -1373,10 +1421,7 @@ var Auth = class {
       }
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred while verifying email"
-      );
+      return wrapError(error, "An unexpected error occurred while verifying email");
     }
   }
   // ============================================================================
@@ -1389,10 +1434,7 @@ var Auth = class {
       });
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred while sending password reset email"
-      );
+      return wrapError(error, "An unexpected error occurred while sending password reset email");
     }
   }
   async exchangeResetPasswordToken(request) {
@@ -1404,10 +1446,7 @@ var Auth = class {
       );
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred while verifying reset code"
-      );
+      return wrapError(error, "An unexpected error occurred while verifying reset code");
     }
   }
   async resetPassword(request) {
@@ -1419,10 +1458,7 @@ var Auth = class {
       );
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred while resetting password"
-      );
+      return wrapError(error, "An unexpected error occurred while resetting password");
     }
   }
   // ============================================================================
@@ -1430,16 +1466,12 @@ var Auth = class {
   // ============================================================================
   async getPublicAuthConfig() {
     try {
-      const response = await this.http.get(
-        "/api/auth/public-config",
-        { skipAuthRefresh: true }
-      );
+      const response = await this.http.get("/api/auth/public-config", {
+        skipAuthRefresh: true
+      });
       return { data: response, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "An unexpected error occurred while fetching auth configuration"
-      );
+      return wrapError(error, "An unexpected error occurred while fetching auth configuration");
     }
   }
 };
@@ -1597,11 +1629,7 @@ var StorageBucket = class {
     } catch (error) {
       return {
         data: null,
-        error: error instanceof InsForgeError ? error : new InsForgeError(
-          "Upload failed",
-          500,
-          "STORAGE_ERROR"
-        )
+        error: error instanceof InsForgeError ? error : new InsForgeError("Upload failed", 500, "STORAGE_ERROR")
       };
     }
   }
@@ -1647,11 +1675,7 @@ var StorageBucket = class {
     } catch (error) {
       return {
         data: null,
-        error: error instanceof InsForgeError ? error : new InsForgeError(
-          "Upload failed",
-          500,
-          "STORAGE_ERROR"
-        )
+        error: error instanceof InsForgeError ? error : new InsForgeError("Upload failed", 500, "STORAGE_ERROR")
       };
     }
   }
@@ -1679,13 +1703,10 @@ var StorageBucket = class {
         );
       }
       if (strategy.confirmRequired && strategy.confirmUrl) {
-        const confirmResponse = await this.http.post(
-          strategy.confirmUrl,
-          {
-            size: file.size,
-            contentType: file.type || "application/octet-stream"
-          }
-        );
+        const confirmResponse = await this.http.post(strategy.confirmUrl, {
+          size: file.size,
+          contentType: file.type || "application/octet-stream"
+        });
         return { data: confirmResponse, error: null };
       }
       return {
@@ -1700,11 +1721,7 @@ var StorageBucket = class {
         error: null
       };
     } catch (error) {
-      throw error instanceof InsForgeError ? error : new InsForgeError(
-        "Presigned upload failed",
-        500,
-        "STORAGE_ERROR"
-      );
+      throw error instanceof InsForgeError ? error : new InsForgeError("Presigned upload failed", 500, "STORAGE_ERROR");
     }
   }
   /**
@@ -1758,11 +1775,7 @@ var StorageBucket = class {
     } catch (error) {
       return {
         data: null,
-        error: error instanceof InsForgeError ? error : new InsForgeError(
-          "Download failed",
-          500,
-          "STORAGE_ERROR"
-        )
+        error: error instanceof InsForgeError ? error : new InsForgeError("Download failed", 500, "STORAGE_ERROR")
       };
     }
   }
@@ -1797,7 +1810,9 @@ var StorageBucket = class {
     } catch (error) {
       const status = error instanceof InsForgeError ? error.statusCode : void 0;
       const isMissingRoute = (status === 404 || status === 405) && !(error instanceof InsForgeError && error.error === "STORAGE_NOT_FOUND");
-      if (!isMissingRoute) throw error;
+      if (!isMissingRoute) {
+        throw error;
+      }
       return await this.http.post(
         `/api/storage/buckets/${this.bucketName}/objects/${encoded}/download-strategy`,
         { expiresIn }
@@ -1873,10 +1888,18 @@ var StorageBucket = class {
   async list(options) {
     try {
       const params = {};
-      if (options?.prefix) params.prefix = options.prefix;
-      if (options?.search) params.search = options.search;
-      if (options?.limit) params.limit = options.limit.toString();
-      if (options?.offset) params.offset = options.offset.toString();
+      if (options?.prefix) {
+        params.prefix = options.prefix;
+      }
+      if (options?.search) {
+        params.search = options.search;
+      }
+      if (options?.limit) {
+        params.limit = options.limit.toString();
+      }
+      if (options?.offset) {
+        params.offset = options.offset.toString();
+      }
       const response = await this.http.get(
         `/api/storage/buckets/${this.bucketName}/objects`,
         { params }
@@ -1885,11 +1908,7 @@ var StorageBucket = class {
     } catch (error) {
       return {
         data: null,
-        error: error instanceof InsForgeError ? error : new InsForgeError(
-          "List failed",
-          500,
-          "STORAGE_ERROR"
-        )
+        error: error instanceof InsForgeError ? error : new InsForgeError("List failed", 500, "STORAGE_ERROR")
       };
     }
   }
@@ -1906,11 +1925,7 @@ var StorageBucket = class {
     } catch (error) {
       return {
         data: null,
-        error: error instanceof InsForgeError ? error : new InsForgeError(
-          "Delete failed",
-          500,
-          "STORAGE_ERROR"
-        )
+        error: error instanceof InsForgeError ? error : new InsForgeError("Delete failed", 500, "STORAGE_ERROR")
       };
     }
   }
@@ -2032,14 +2047,11 @@ var ChatCompletions = class {
     if (params.stream) {
       const headers = this.http.getHeaders();
       headers["Content-Type"] = "application/json";
-      const response2 = await this.http.fetch(
-        `${this.http.baseUrl}/api/ai/chat/completion`,
-        {
-          method: "POST",
-          headers,
-          body: JSON.stringify(backendParams)
-        }
-      );
+      const response2 = await this.http.fetch(`${this.http.baseUrl}/api/ai/chat/completion`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(backendParams)
+      });
       if (!response2.ok) {
         const error = await response2.json();
         throw new Error(error.error || "Stream request failed");
@@ -2087,7 +2099,9 @@ var ChatCompletions = class {
     try {
       while (true) {
         const { done, value } = await reader.read();
-        if (done) break;
+        if (done) {
+          break;
+        }
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");
         buffer = lines.pop() || "";
@@ -2135,7 +2149,7 @@ var ChatCompletions = class {
                   reader.releaseLock();
                   return;
                 }
-              } catch (e) {
+              } catch {
                 console.warn("Failed to parse SSE data:", dataStr);
               }
             }
@@ -2188,10 +2202,7 @@ var Embeddings = class {
    * ```
    */
   async create(params) {
-    const response = await this.http.post(
-      "/api/ai/embeddings",
-      params
-    );
+    const response = await this.http.post("/api/ai/embeddings", params);
     return {
       object: response.object,
       data: response.data,
@@ -2277,7 +2288,9 @@ var Functions = class _Functions {
   static deriveSubhostingUrl(baseUrl) {
     try {
       const { hostname } = new URL(baseUrl);
-      if (!hostname.endsWith(".insforge.app")) return void 0;
+      if (!hostname.endsWith(".insforge.app")) {
+        return void 0;
+      }
       const appKey = hostname.split(".")[0];
       return `https://${appKey}.functions.insforge.app`;
     } catch {
@@ -2323,7 +2336,9 @@ var Functions = class _Functions {
         const data = await parseResponse(res);
         return { data, error: null };
       } catch (error) {
-        if (error instanceof Error && error.name === "AbortError") throw error;
+        if (error instanceof Error && error.name === "AbortError") {
+          throw error;
+        }
         return {
           data: null,
           error: error instanceof InsForgeError ? error : new InsForgeError(
@@ -2342,7 +2357,9 @@ var Functions = class _Functions {
         });
         return { data, error: null };
       } catch (error) {
-        if (error instanceof Error && error.name === "AbortError") throw error;
+        if (error instanceof Error && error.name === "AbortError") {
+          throw error;
+        }
         if (error instanceof InsForgeError && error.statusCode === 404) {
         } else {
           return {
@@ -2361,7 +2378,9 @@ var Functions = class _Functions {
       const data = await this.http.request(method, path, { body, headers });
       return { data, error: null };
     } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw error;
+      }
       return {
         data: null,
         error: error instanceof InsForgeError ? error : new InsForgeError(
@@ -2376,32 +2395,37 @@ var Functions = class _Functions {
 
 // src/modules/realtime.ts
 var CONNECT_TIMEOUT = 1e4;
+var SUBSCRIBE_TIMEOUT = 1e4;
 var Realtime = class {
-  constructor(baseUrl, tokenManager, anonKey) {
-    this.socket = null;
-    this.connectPromise = null;
-    this.subscribedChannels = /* @__PURE__ */ new Set();
-    this.eventListeners = /* @__PURE__ */ new Map();
+  constructor(baseUrl, tokenManager, anonKey, getValidAccessToken = async () => tokenManager.getAccessToken()) {
     this.baseUrl = baseUrl;
     this.tokenManager = tokenManager;
     this.anonKey = anonKey;
-    this.tokenManager.onTokenChange = () => this.onTokenChange();
+    this.getValidAccessToken = getValidAccessToken;
+    this.socket = null;
+    this.connectPromise = null;
+    this.connectionAttempt = null;
+    this.nextConnectionAttemptId = 0;
+    this.subscriptions = /* @__PURE__ */ new Map();
+    this.eventListeners = /* @__PURE__ */ new Map();
+    this.tokenManager.onAuthStateChange((event) => {
+      if (event !== AuthChangeEvent.TOKEN_REFRESHED) {
+        this.reconnectForAuthChange();
+      }
+    });
   }
   notifyListeners(event, payload) {
-    const listeners = this.eventListeners.get(event);
-    if (!listeners) return;
-    for (const cb of listeners) {
+    for (const callback of this.eventListeners.get(event) ?? []) {
       try {
-        cb(payload);
-      } catch (err) {
-        console.error(`Error in ${event} callback:`, err);
+        callback(payload);
+      } catch (error) {
+        console.error(`Error in ${event} callback:`, error);
       }
     }
   }
-  /**
-   * Connect to the realtime server
-   * @returns Promise that resolves when connected
-   */
+  async getHandshakeToken() {
+    return await this.getValidAccessToken() ?? this.anonKey ?? null;
+  }
   connect() {
     if (this.socket?.connected) {
       return Promise.resolve();
@@ -2409,210 +2433,324 @@ var Realtime = class {
     if (this.connectPromise) {
       return this.connectPromise;
     }
-    this.connectPromise = (async () => {
-      try {
-        const { io } = await import("socket.io-client");
-        await new Promise((resolve, reject) => {
-          const token = this.tokenManager.getAccessToken() ?? this.anonKey;
-          this.socket = io(this.baseUrl, {
-            transports: ["websocket"],
-            auth: token ? { token } : void 0
-          });
-          let initialConnection = true;
-          let timeoutId = null;
-          const cleanup = () => {
-            if (timeoutId) {
-              clearTimeout(timeoutId);
-              timeoutId = null;
-            }
-          };
-          timeoutId = setTimeout(() => {
-            if (initialConnection) {
-              initialConnection = false;
-              this.connectPromise = null;
-              this.socket?.disconnect();
-              this.socket = null;
-              reject(new Error(`Connection timeout after ${CONNECT_TIMEOUT}ms`));
-            }
-          }, CONNECT_TIMEOUT);
-          this.socket.on("connect", () => {
-            cleanup();
-            for (const channel of this.subscribedChannels) {
-              this.socket.emit("realtime:subscribe", { channel });
-            }
-            this.notifyListeners("connect");
-            if (initialConnection) {
-              initialConnection = false;
-              this.connectPromise = null;
-              resolve();
-            }
-          });
-          this.socket.on("connect_error", (error) => {
-            cleanup();
-            this.notifyListeners("connect_error", error);
-            if (initialConnection) {
-              initialConnection = false;
-              this.connectPromise = null;
-              reject(error);
-            }
-          });
-          this.socket.on("disconnect", (reason) => {
-            this.notifyListeners("disconnect", reason);
-          });
-          this.socket.on("realtime:error", (error) => {
-            this.notifyListeners("error", error);
-          });
-          this.socket.onAny((event, message) => {
-            if (event === "realtime:error") return;
-            this.notifyListeners(event, message);
-          });
+    const attemptId = ++this.nextConnectionAttemptId;
+    const connection = (async () => {
+      const { io } = await import("socket.io-client");
+      if (attemptId !== this.nextConnectionAttemptId) {
+        throw new Error("Connection cancelled");
+      }
+      await new Promise((resolve, reject) => {
+        const socket = io(this.baseUrl, {
+          transports: ["websocket"],
+          auth: (callback) => {
+            void this.getHandshakeToken().then(
+              (token) => callback(token ? { token } : {}),
+              () => callback({})
+            );
+          }
         });
-      } catch (error) {
+        this.socket = socket;
+        let initialConnection = true;
+        let timeoutId = null;
+        const clearConnectTimeout = () => {
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+          }
+        };
+        const dispose = () => {
+          clearConnectTimeout();
+          socket.off("connect", onConnect);
+          socket.off("connect_error", onConnectError);
+          socket.off("disconnect", onDisconnect);
+          socket.off("realtime:error", onRealtimeError);
+          socket.offAny(onAny);
+          socket.disconnect();
+          if (this.socket === socket) {
+            this.socket = null;
+          }
+          if (this.connectionAttempt?.id === attemptId) {
+            this.connectionAttempt = null;
+          }
+        };
+        const fail = (error) => {
+          if (!initialConnection) {
+            return;
+          }
+          initialConnection = false;
+          dispose();
+          reject(error);
+        };
+        const onConnect = () => {
+          if (this.socket !== socket) {
+            return;
+          }
+          clearConnectTimeout();
+          this.resubscribeChannels();
+          this.notifyListeners("connect");
+          if (initialConnection) {
+            initialConnection = false;
+            if (this.connectionAttempt?.id === attemptId) {
+              this.connectionAttempt = null;
+            }
+            resolve();
+          }
+        };
+        const onConnectError = (error) => {
+          clearConnectTimeout();
+          this.notifyListeners("connect_error", error);
+          if (initialConnection) {
+            fail(error);
+          }
+        };
+        const onDisconnect = (reason) => {
+          this.handleDisconnect(reason);
+        };
+        const onRealtimeError = (error) => {
+          this.notifyListeners("error", error);
+        };
+        const onAny = (event, message) => {
+          if (event === "realtime:error") {
+            return;
+          }
+          this.applyPresenceEvent(event, message);
+          this.notifyListeners(event, message);
+        };
+        this.connectionAttempt = { id: attemptId, socket, cancel: fail };
+        socket.on("connect", onConnect);
+        socket.on("connect_error", onConnectError);
+        socket.on("disconnect", onDisconnect);
+        socket.on("realtime:error", onRealtimeError);
+        socket.onAny(onAny);
+        timeoutId = setTimeout(
+          () => fail(new Error(`Connection timeout after ${CONNECT_TIMEOUT}ms`)),
+          CONNECT_TIMEOUT
+        );
+      });
+    })();
+    const trackedConnection = connection.finally(() => {
+      if (this.connectPromise === trackedConnection) {
         this.connectPromise = null;
-        throw error;
       }
-    })();
-    return this.connectPromise;
+    });
+    this.connectPromise = trackedConnection;
+    return trackedConnection;
   }
-  /**
-   * Disconnect from the realtime server
-   */
   disconnect() {
-    if (this.socket) {
-      this.socket.disconnect();
-      this.socket = null;
+    this.nextConnectionAttemptId++;
+    this.connectionAttempt?.cancel(new Error("Disconnected"));
+    this.socket?.disconnect();
+    this.socket = null;
+    this.connectPromise = null;
+    for (const subscription of this.subscriptions.values()) {
+      this.settleSubscription(
+        subscription,
+        {
+          ok: false,
+          channel: subscription.channel,
+          error: { code: "DISCONNECTED", message: "Disconnected" }
+        },
+        false
+      );
     }
-    this.subscribedChannels.clear();
+    this.subscriptions.clear();
   }
-  /**
-   * Handle token changes (e.g., after auth refresh)
-   * Updates socket auth so reconnects use the new token
-   * If connected, triggers reconnect to apply new token immediately
-   */
-  onTokenChange() {
-    const token = this.tokenManager.getAccessToken() ?? this.anonKey;
-    if (this.socket) {
-      this.socket.auth = token ? { token } : {};
+  reconnectForAuthChange() {
+    for (const subscription of this.subscriptions.values()) {
+      if (subscription.status === "rejected") {
+        subscription.status = "pending";
+      }
     }
-    if (this.socket && (this.socket.connected || this.connectPromise)) {
-      this.socket.disconnect();
-      this.socket.connect();
+    if (!this.socket) {
+      return;
+    }
+    this.socket.disconnect();
+    this.socket.connect();
+  }
+  handleDisconnect(reason) {
+    for (const subscription of this.subscriptions.values()) {
+      if (subscription.status === "rejected") {
+        continue;
+      }
+      subscription.status = "pending";
+      this.settleSubscription(
+        subscription,
+        {
+          ok: false,
+          channel: subscription.channel,
+          error: { code: "DISCONNECTED", message: "Connection lost before subscription completed" }
+        },
+        true
+      );
+    }
+    this.notifyListeners("disconnect", reason);
+  }
+  resubscribeChannels() {
+    for (const [channel, subscription] of this.subscriptions) {
+      if (subscription.status === "pending") {
+        this.requestSubscription(channel, subscription);
+      }
+    }
+  }
+  requestSubscription(channel, subscription) {
+    if (subscription.pending) {
+      return subscription.pending;
+    }
+    const socket = this.socket;
+    if (!socket?.connected) {
+      return Promise.resolve({
+        ok: false,
+        channel,
+        error: { code: "CONNECTION_FAILED", message: "Not connected to realtime server" }
+      });
+    }
+    subscription.status = "pending";
+    const epoch = ++subscription.epoch;
+    let timeoutId;
+    subscription.pending = new Promise((resolve) => {
+      subscription.settlePending = (response) => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+        subscription.pending = void 0;
+        subscription.settlePending = void 0;
+        resolve(response);
+      };
+      timeoutId = setTimeout(() => {
+        if (this.subscriptions.get(channel) === subscription && subscription.epoch === epoch) {
+          this.settleSubscription(
+            subscription,
+            {
+              ok: false,
+              channel,
+              error: {
+                code: "SUBSCRIBE_TIMEOUT",
+                message: "Subscription acknowledgement timed out"
+              }
+            },
+            true
+          );
+        }
+      }, SUBSCRIBE_TIMEOUT);
+      socket.emit("realtime:subscribe", { channel }, (response) => {
+        if (this.subscriptions.get(channel) !== subscription || subscription.epoch !== epoch) {
+          return;
+        }
+        if (response.ok) {
+          subscription.status = "subscribed";
+          subscription.members = new Map(
+            response.presence.members.map((member) => [member.presenceId, member])
+          );
+        } else {
+          subscription.status = "rejected";
+          subscription.members.clear();
+        }
+        this.settleSubscription(subscription, response, false);
+      });
+    });
+    return subscription.pending;
+  }
+  settleSubscription(subscription, response, incrementEpoch) {
+    if (incrementEpoch) {
+      subscription.epoch++;
+    }
+    subscription.settlePending?.(response);
+  }
+  applyPresenceEvent(event, message) {
+    if (event !== "presence:join" && event !== "presence:leave") {
+      return;
+    }
+    const presenceEvent = message;
+    const channel = presenceEvent.meta?.channel;
+    const member = presenceEvent.member;
+    if (!channel || !member) {
+      return;
+    }
+    const subscription = this.subscriptions.get(channel);
+    if (!subscription) {
+      return;
+    }
+    if (event === "presence:join") {
+      subscription.members.set(member.presenceId, member);
+    } else {
+      subscription.members.delete(member.presenceId);
     }
   }
-  /**
-   * Check if connected to the realtime server
-   */
   get isConnected() {
     return this.socket?.connected ?? false;
   }
-  /**
-   * Get the current connection state
-   */
   get connectionState() {
-    if (!this.socket) return "disconnected";
-    if (this.socket.connected) return "connected";
-    return "connecting";
+    if (!this.socket) {
+      return "disconnected";
+    }
+    return this.socket.connected ? "connected" : "connecting";
   }
-  /**
-   * Get the socket ID (if connected)
-   */
   get socketId() {
     return this.socket?.id;
   }
-  /**
-   * Subscribe to a channel
-   *
-   * Automatically connects if not already connected.
-   *
-   * @param channel - Channel name (e.g., 'orders:123', 'broadcast')
-   * @returns Promise with the subscription response
-   */
   async subscribe(channel) {
-    if (this.subscribedChannels.has(channel)) {
-      return { ok: true, channel, presence: { members: [] } };
+    let subscription = this.subscriptions.get(channel);
+    if (subscription) {
+      if (subscription.pending) {
+        return subscription.pending;
+      }
+      if (subscription.status === "subscribed") {
+        return { ok: true, channel, presence: { members: [...subscription.members.values()] } };
+      }
+    } else {
+      subscription = { channel, epoch: 0, status: "pending", members: /* @__PURE__ */ new Map() };
+      this.subscriptions.set(channel, subscription);
     }
     if (!this.socket?.connected) {
       try {
         await this.connect();
       } catch (error) {
+        if (this.subscriptions.get(channel) === subscription) {
+          this.subscriptions.delete(channel);
+        }
         const message = error instanceof Error ? error.message : "Connection failed";
         return { ok: false, channel, error: { code: "CONNECTION_FAILED", message } };
       }
     }
-    return new Promise((resolve) => {
-      this.socket.emit("realtime:subscribe", { channel }, (response) => {
-        if (response.ok) {
-          this.subscribedChannels.add(channel);
-        }
-        resolve(response);
-      });
-    });
+    return subscription.pending ?? this.requestSubscription(channel, subscription);
   }
-  /**
-   * Unsubscribe from a channel (fire-and-forget)
-   *
-   * @param channel - Channel name to unsubscribe from
-   */
   unsubscribe(channel) {
-    this.subscribedChannels.delete(channel);
+    const subscription = this.subscriptions.get(channel);
+    if (!subscription) {
+      return;
+    }
+    this.subscriptions.delete(channel);
+    this.settleSubscription(
+      subscription,
+      {
+        ok: false,
+        channel,
+        error: { code: "SUBSCRIPTION_CANCELLED", message: "Subscription cancelled" }
+      },
+      true
+    );
     if (this.socket?.connected) {
       this.socket.emit("realtime:unsubscribe", { channel });
     }
   }
-  /**
-   * Publish a message to a channel
-   *
-   * @param channel - Channel name
-   * @param event - Event name
-   * @param payload - Message payload
-   */
   async publish(channel, event, payload) {
     if (!this.socket?.connected) {
       throw new Error("Not connected to realtime server. Call connect() first.");
     }
     this.socket.emit("realtime:publish", { channel, event, payload });
   }
-  /**
-   * Listen for events
-   *
-   * Reserved event names:
-   * - 'connect' - Fired when connected to the server
-   * - 'connect_error' - Fired when connection fails (payload: Error)
-   * - 'disconnect' - Fired when disconnected (payload: reason string)
-   * - 'error' - Fired when a realtime error occurs (payload: RealtimeErrorPayload)
-   *
-   * All other events receive a `SocketMessage` payload with metadata.
-   *
-   * @param event - Event name to listen for
-   * @param callback - Callback function when event is received
-   */
   on(event, callback) {
-    if (!this.eventListeners.has(event)) {
-      this.eventListeners.set(event, /* @__PURE__ */ new Set());
-    }
-    this.eventListeners.get(event).add(callback);
+    const listeners = this.eventListeners.get(event) ?? /* @__PURE__ */ new Set();
+    listeners.add(callback);
+    this.eventListeners.set(event, listeners);
   }
-  /**
-   * Remove a listener for a specific event
-   *
-   * @param event - Event name
-   * @param callback - The callback function to remove
-   */
   off(event, callback) {
     const listeners = this.eventListeners.get(event);
-    if (listeners) {
-      listeners.delete(callback);
-      if (listeners.size === 0) {
-        this.eventListeners.delete(event);
-      }
+    listeners?.delete(callback);
+    if (listeners?.size === 0) {
+      this.eventListeners.delete(event);
     }
   }
-  /**
-   * Listen for an event only once, then automatically remove the listener
-   *
-   * @param event - Event name to listen for
-   * @param callback - Callback function when event is received
-   */
   once(event, callback) {
     const wrapper = (payload) => {
       this.off(event, wrapper);
@@ -2620,13 +2758,11 @@ var Realtime = class {
     };
     this.on(event, wrapper);
   }
-  /**
-   * Get all currently subscribed channels
-   *
-   * @returns Array of channel names
-   */
   getSubscribedChannels() {
-    return Array.from(this.subscribedChannels);
+    return [...this.subscriptions.values()].filter((subscription) => subscription.status === "subscribed").map((subscription) => subscription.channel);
+  }
+  getPresenceState(channel) {
+    return [...this.subscriptions.get(channel)?.members.values() ?? []];
   }
 };
 
@@ -2641,13 +2777,12 @@ var Emails = class {
    */
   async send(options) {
     try {
-      const data = await this.http.post(
-        "/api/email/send-raw",
-        options
-      );
+      const data = await this.http.post("/api/email/send-raw", options);
       return { data, error: null };
     } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw error;
+      }
       return {
         data: null,
         error: error instanceof InsForgeError ? error : new InsForgeError(
@@ -2730,10 +2865,7 @@ var RazorpayPayments = class {
       );
       return { data, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "Razorpay order creation failed"
-      );
+      return wrapError(error, "Razorpay order creation failed");
     }
   }
   async verifyOrder(environment, request) {
@@ -2744,10 +2876,7 @@ var RazorpayPayments = class {
       );
       return { data, error: null };
     } catch (error) {
-      return wrapError(
-        error,
-        "Razorpay order verification failed"
-      );
+      return wrapError(error, "Razorpay order verification failed");
     }
   }
   async createSubscription(environment, request) {
@@ -2856,7 +2985,8 @@ var InsForgeClient = class {
     this.realtime = new Realtime(
       this.http.baseUrl,
       this.tokenManager,
-      config.anonKey
+      config.anonKey,
+      () => this.http.getValidAccessToken()
     );
     this.emails = new Emails(this.http);
     this.payments = new Payments(this.http);
@@ -2876,32 +3006,35 @@ var InsForgeClient = class {
   /**
    * Set the access token used by every SDK surface. Updates both the HTTP
    * client (database / storage / functions / AI / emails) and the realtime
-   * token manager (which fires `onTokenChange` to reconnect the WebSocket
-   * with the new bearer). Pass `null` to clear.
+   * token manager. Pass `null` to sign out. By default a token replacement is
+   * treated as a sign-in boundary and reconnects realtime. Pass
+   * `AuthChangeEvent.TOKEN_REFRESHED` for a same-identity refresh to preserve a live socket; the
+   * refreshed token is then used at the next handshake.
    *
    * Use this when an external auth provider (Better Auth, Clerk, Auth0,
    * WorkOS, Kinde, Stytch, …) issues the JWT and you need to keep the
    * long-lived InsForge client in sync. Without this, you'd have to call
    * `client.getHttpClient().setAuthToken(token)` AND reach into the private
-   * `client.realtime.tokenManager.setAccessToken(token)` separately —
-   * forgetting the second one silently breaks realtime auth.
+   * realtime token manager separately.
    *
    * @example
    * ```typescript
+   * import { AuthChangeEvent } from '@insforge/sdk';
+   *
    * // Refresh a third-party-issued JWT periodically
    * const { token } = await fetch('/api/insforge-token').then((r) => r.json());
-   * client.setAccessToken(token);
+   * client.setAccessToken(token, AuthChangeEvent.TOKEN_REFRESHED);
    *
    * // Sign-out
    * client.setAccessToken(null);
    * ```
    */
-  setAccessToken(token) {
+  setAccessToken(token, event = AuthChangeEvent.SIGNED_IN) {
     this.http.setAuthToken(token);
     if (token === null) {
       this.tokenManager.clearSession();
     } else {
-      this.tokenManager.setAccessToken(token);
+      this.tokenManager.setAccessToken(token, event);
     }
   }
   /**
@@ -2914,38 +3047,6 @@ var InsForgeClient = class {
    */
 };
 
-// src/lib/jwt.ts
-function decodeBase64Url(input) {
-  const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = normalized.padEnd(
-    normalized.length + (4 - normalized.length % 4) % 4,
-    "="
-  );
-  const binary = atob(padded);
-  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
-  return new TextDecoder().decode(bytes);
-}
-function getJwtExpiration(token) {
-  if (!token) return null;
-  const [, payload] = token.split(".");
-  if (!payload) return null;
-  try {
-    const parsed = JSON.parse(decodeBase64Url(payload));
-    if (typeof parsed.exp !== "number" || !Number.isFinite(parsed.exp)) {
-      return null;
-    }
-    return new Date(parsed.exp * 1e3);
-  } catch {
-    return null;
-  }
-}
-function isJwtExpiredOrExpiring(token, leewaySeconds = 60) {
-  if (!token) return false;
-  const expires = getJwtExpiration(token);
-  if (!expires) return true;
-  return expires.getTime() <= Date.now() + leewaySeconds * 1e3;
-}
-
 // src/ssr/browser-client.ts
 var import_shared_schemas2 = require("@insforge/shared-schemas");
 
@@ -2960,18 +3061,28 @@ function getRefreshTokenCookieName(names) {
   return names?.refreshToken ?? DEFAULT_REFRESH_TOKEN_COOKIE;
 }
 function getCookieValue(cookies, name) {
-  if (!cookies) return null;
+  if (!cookies) {
+    return null;
+  }
   const value = cookies.get(name);
-  if (typeof value === "string") return value || null;
-  if (value && typeof value.value === "string") return value.value || null;
+  if (typeof value === "string") {
+    return value || null;
+  }
+  if (value && typeof value.value === "string") {
+    return value.value || null;
+  }
   return null;
 }
 function getCookieValueFromHeader(cookieHeader, name) {
-  if (!cookieHeader) return null;
+  if (!cookieHeader) {
+    return null;
+  }
   const parts = cookieHeader.split(";");
   for (const part of parts) {
     const [rawName, ...rawValue] = part.trim().split("=");
-    if (rawName !== name) continue;
+    if (rawName !== name) {
+      continue;
+    }
     try {
       return decodeURIComponent(rawValue.join("="));
     } catch {
@@ -2981,7 +3092,9 @@ function getCookieValueFromHeader(cookieHeader, name) {
   return null;
 }
 function getBrowserCookie(name) {
-  if (typeof document === "undefined") return null;
+  if (typeof document === "undefined") {
+    return null;
+  }
   return getCookieValueFromHeader(document.cookie, name);
 }
 function defaultCookieOptions() {
@@ -3018,11 +3131,15 @@ function expiredCookieOptions(overrides) {
   };
 }
 function setCookie(cookies, name, value, options) {
-  if (!cookies?.set) return;
+  if (!cookies?.set) {
+    return;
+  }
   cookies.set(name, value, options);
 }
 function deleteCookie(cookies, name, options) {
-  if (!cookies) return;
+  if (!cookies) {
+    return;
+  }
   if (cookies.set) {
     cookies.set(name, "", expiredCookieOptions(options));
     return;
@@ -3031,12 +3148,24 @@ function deleteCookie(cookies, name, options) {
 }
 function serializeCookie(name, value, options = {}) {
   const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
-  if (options.maxAge !== void 0) parts.push(`Max-Age=${options.maxAge}`);
-  if (options.domain) parts.push(`Domain=${options.domain}`);
-  if (options.path) parts.push(`Path=${options.path}`);
-  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
-  if (options.httpOnly) parts.push("HttpOnly");
-  if (options.secure) parts.push("Secure");
+  if (options.maxAge !== void 0) {
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+  if (options.domain) {
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (options.path) {
+    parts.push(`Path=${options.path}`);
+  }
+  if (options.expires) {
+    parts.push(`Expires=${options.expires.toUTCString()}`);
+  }
+  if (options.httpOnly) {
+    parts.push("HttpOnly");
+  }
+  if (options.secure) {
+    parts.push("Secure");
+  }
   if (options.sameSite) {
     const sameSite = options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1);
     parts.push(`SameSite=${sameSite}`);
@@ -3049,20 +3178,14 @@ function appendSetCookie(headers, name, value, options) {
 function setAuthCookies(cookies, tokens, settings = {}) {
   const accessName = getAccessTokenCookieName(settings.names);
   const refreshName = getRefreshTokenCookieName(settings.names);
-  const accessOptions = accessTokenCookieOptions(
-    tokens.accessToken,
-    settings.options?.accessToken
-  );
+  const accessOptions = accessTokenCookieOptions(tokens.accessToken, settings.options?.accessToken);
   setCookie(cookies, accessName, tokens.accessToken, accessOptions);
   if (tokens.refreshToken) {
     setCookie(
       cookies,
       refreshName,
       tokens.refreshToken,
-      refreshTokenCookieOptions(
-        tokens.refreshToken,
-        settings.options?.refreshToken
-      )
+      refreshTokenCookieOptions(tokens.refreshToken, settings.options?.refreshToken)
     );
   }
 }
@@ -3088,10 +3211,7 @@ function setAuthCookieHeaders(headers, tokens, settings = {}) {
       headers,
       refreshName,
       tokens.refreshToken,
-      refreshTokenCookieOptions(
-        tokens.refreshToken,
-        settings.options?.refreshToken
-      )
+      refreshTokenCookieOptions(tokens.refreshToken, settings.options?.refreshToken)
     );
   }
 }
@@ -3134,10 +3254,14 @@ function toRefreshError(response, body) {
   );
 }
 async function readErrorCode(response) {
-  if (response.status !== 401) return null;
+  if (response.status !== 401) {
+    return null;
+  }
   try {
     const body = await response.clone().json();
-    if (!body || typeof body !== "object") return null;
+    if (!body || typeof body !== "object") {
+      return null;
+    }
     const candidate = body.error ?? body.code;
     return typeof candidate === "string" ? candidate : null;
   } catch {
@@ -3156,7 +3280,9 @@ function withAuthHeader(init, token) {
   };
 }
 function getRequestUrl(input) {
-  if (typeof input === "string") return input;
+  if (typeof input === "string") {
+    return input;
+  }
   if (typeof Request !== "undefined" && input instanceof Request) {
     return input.url;
   }
@@ -3174,21 +3300,19 @@ function createBrowserClient(options = {}) {
       "Missing InsForge baseUrl or anonKey. Pass baseUrl and anonKey to createBrowserClient() or set NEXT_PUBLIC_INSFORGE_URL and NEXT_PUBLIC_INSFORGE_ANON_KEY."
     );
   }
-  let accessToken = getBrowserCookie(
-    getAccessTokenCookieName(options.names)
-  );
+  let accessToken = getBrowserCookie(getAccessTokenCookieName(options.names));
   const refreshUrl = options.refreshUrl ?? "/api/auth/refresh";
   const fetchImpl = options.fetch ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
   let client;
   let sessionChecked = false;
   let refreshPromise = null;
   const refreshFromRoute = () => {
-    if (refreshPromise) return refreshPromise;
+    if (refreshPromise) {
+      return refreshPromise;
+    }
     refreshPromise = (async () => {
       if (!fetchImpl) {
-        throw new Error(
-          "Fetch is not available. Please provide a fetch implementation."
-        );
+        throw new Error("Fetch is not available. Please provide a fetch implementation.");
       }
       const response = await fetchImpl(refreshUrl, {
         method: "POST",
@@ -3205,11 +3329,15 @@ function createBrowserClient(options = {}) {
         }
         throw error;
       }
-      if (!body || typeof body !== "object") return null;
+      if (!body || typeof body !== "object") {
+        return null;
+      }
       const refreshBody = body;
-      if (!refreshBody.accessToken || !refreshBody.user) return null;
+      if (!refreshBody.accessToken || !refreshBody.user) {
+        return null;
+      }
       accessToken = refreshBody.accessToken;
-      client?.setAccessToken(refreshBody.accessToken);
+      client?.setAccessToken(refreshBody.accessToken, AuthChangeEvent.TOKEN_REFRESHED);
       return refreshBody;
     })().finally(() => {
       sessionChecked = true;
@@ -3223,9 +3351,7 @@ function createBrowserClient(options = {}) {
   };
   const ssrFetch = async (input, init) => {
     if (!fetchImpl) {
-      throw new Error(
-        "Fetch is not available. Please provide a fetch implementation."
-      );
+      throw new Error("Fetch is not available. Please provide a fetch implementation.");
     }
     if (shouldSkipRefresh(input)) {
       return fetchImpl(input, init);
@@ -3262,9 +3388,9 @@ function createBrowserClient(options = {}) {
     }
   });
   const setAccessToken = client.setAccessToken.bind(client);
-  client.setAccessToken = (token) => {
+  client.setAccessToken = (token, event) => {
     accessToken = token;
-    setAccessToken(token);
+    setAccessToken(token, event);
   };
   if (accessToken) {
     client.setAccessToken(accessToken);
@@ -3288,10 +3414,7 @@ function createServerClient(options = {}) {
       "Missing InsForge baseUrl or anonKey. Pass baseUrl and anonKey to createServerClient() or set NEXT_PUBLIC_INSFORGE_URL and NEXT_PUBLIC_INSFORGE_ANON_KEY."
     );
   }
-  const accessToken = options.accessToken ?? getCookieValue(
-    options.cookies,
-    getAccessTokenCookieName(options.names)
-  );
+  const accessToken = options.accessToken ?? getCookieValue(options.cookies, getAccessTokenCookieName(options.names));
   return new InsForgeClient({
     ...options,
     baseUrl,
@@ -3314,7 +3437,9 @@ function jsonResponse(body, init = {}, headers = new Headers(init.headers)) {
   });
 }
 function normalizeError(error) {
-  if (error instanceof InsForgeError) return error;
+  if (error instanceof InsForgeError) {
+    return error;
+  }
   if (error && typeof error === "object") {
     const body = error;
     return new InsForgeError(
@@ -3331,18 +3456,21 @@ function normalizeError(error) {
 }
 async function readJson(response) {
   const contentType = response.headers.get("content-type");
-  if (!contentType?.includes("json")) return null;
+  if (!contentType?.includes("json")) {
+    return null;
+  }
   return response.json();
 }
 function readRefreshToken(options) {
-  if (options.refreshToken) return options.refreshToken;
+  if (options.refreshToken) {
+    return options.refreshToken;
+  }
   const refreshCookieName = getRefreshTokenCookieName(options.names);
   const cookieValue = getCookieValue(options.cookies, refreshCookieName);
-  if (cookieValue) return cookieValue;
-  return getCookieValueFromHeader(
-    options.request?.headers.get("cookie"),
-    refreshCookieName
-  );
+  if (cookieValue) {
+    return cookieValue;
+  }
+  return getCookieValueFromHeader(options.request?.headers.get("cookie"), refreshCookieName);
 }
 async function refreshAuth(options = {}) {
   const headers = new Headers();
@@ -3383,9 +3511,7 @@ async function refreshAuth(options = {}) {
   }
   const fetchImpl = options.fetch ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
   if (!fetchImpl) {
-    throw new Error(
-      "Fetch is not available. Please provide a fetch implementation."
-    );
+    throw new Error("Fetch is not available. Please provide a fetch implementation.");
   }
   const requestHeaders = new Headers(options.headers);
   requestHeaders.set("Authorization", `Bearer ${anonKey}`);
@@ -3466,7 +3592,9 @@ function createRefreshAuthRouter(options = {}) {
 
 // src/ssr/auth-actions.ts
 function persistSessionCookies(cookies, data, settings) {
-  if (!data?.accessToken) return;
+  if (!data?.accessToken) {
+    return;
+  }
   setAuthCookies(
     cookies,
     {
@@ -3477,7 +3605,9 @@ function persistSessionCookies(cookies, data, settings) {
   );
 }
 function sanitizeAuthData(data) {
-  if (!data) return null;
+  if (!data) {
+    return null;
+  }
   const {
     accessToken: _accessToken,
     refreshToken: _refreshToken,
@@ -3527,32 +3657,20 @@ function createAuthActions(options = {}) {
     signInWithPassword: async (request) => {
       const result = await createClient().auth.signInWithPassword(request);
       persistSessionCookies(writeCookies, result.data, cookieSettings);
-      return toSafeAuthResult(
-        result
-      );
+      return toSafeAuthResult(result);
     },
     signInWithOAuth: async (providerOrOptions, signInOptions) => {
-      return createClient().auth.signInWithOAuth(
-        providerOrOptions,
-        signInOptions
-      );
+      return createClient().auth.signInWithOAuth(providerOrOptions, signInOptions);
     },
     signInWithIdToken: async (credentials) => {
       const result = await createClient().auth.signInWithIdToken(credentials);
       persistSessionCookies(writeCookies, result.data, cookieSettings);
-      return toSafeAuthResult(
-        result
-      );
+      return toSafeAuthResult(result);
     },
     exchangeOAuthCode: async (code, codeVerifier) => {
-      const result = await createClient().auth.exchangeOAuthCode(
-        code,
-        codeVerifier
-      );
+      const result = await createClient().auth.exchangeOAuthCode(code, codeVerifier);
       persistSessionCookies(writeCookies, result.data, cookieSettings);
-      return toSafeAuthResult(
-        result
-      );
+      return toSafeAuthResult(result);
     },
     verifyEmail: async (request) => {
       const result = await createClient().auth.verifyEmail(request);
@@ -3571,10 +3689,7 @@ function createAuthActions(options = {}) {
 async function updateSession(options) {
   const accessCookieName = getAccessTokenCookieName(options.names);
   const refreshCookieName = getRefreshTokenCookieName(options.names);
-  const accessToken = getCookieValue(
-    options.requestCookies,
-    accessCookieName
-  );
+  const accessToken = getCookieValue(options.requestCookies, accessCookieName);
   if (accessToken && !isJwtExpiredOrExpiring(accessToken, options.refreshLeewaySeconds)) {
     return {
       refreshed: false,
@@ -3582,10 +3697,7 @@ async function updateSession(options) {
       error: null
     };
   }
-  const refreshToken = getCookieValue(
-    options.requestCookies,
-    refreshCookieName
-  );
+  const refreshToken = getCookieValue(options.requestCookies, refreshCookieName);
   if (!refreshToken) {
     if (accessToken) {
       clearAuthCookies(options.requestCookies, options);