@insforge/sdk 1.4.3 → 1.4.4

package/dist/index.js

@@ -32,6 +32,7 @@ var src_exports = {};
 __export(src_exports, {
   AI: () => AI,
   Auth: () => Auth,
+  AuthChangeEvent: () => AuthChangeEvent,
   Database: () => Database,
   Emails: () => Emails,
   Functions: () => Functions,
@@ -43,7 +44,6 @@ __export(src_exports, {
   Realtime: () => Realtime,
   Storage: () => Storage,
   StorageBucket: () => StorageBucket,
-  TokenManager: () => TokenManager,
   createAdminClient: () => createAdminClient,
   createClient: () => createClient,
   default: () => src_default
@@ -97,7 +97,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);
@@ -106,7 +108,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)) {
@@ -121,7 +125,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);
@@ -158,7 +164,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);
@@ -172,7 +180,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);
@@ -186,7 +196,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);
@@ -203,10 +215,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))}`);
     }
@@ -227,10 +239,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;
@@ -245,21 +257,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}`;
 }
@@ -268,25 +293,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
@@ -301,11 +327,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);
     }
   }
   /**
@@ -327,22 +353,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;
   }
@@ -350,7 +428,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 {
@@ -452,31 +532,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) {
@@ -518,7 +591,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}`,
@@ -527,10 +602,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(
@@ -552,11 +631,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.
@@ -636,31 +711,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) {
@@ -745,12 +804,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 {
@@ -764,12 +818,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) {
@@ -863,10 +912,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);
     }
@@ -962,11 +1031,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;
     }
@@ -978,7 +1051,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);
@@ -992,7 +1065,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");
@@ -1100,11 +1175,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;
@@ -1179,10 +1250,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");
     }
   }
   /**
@@ -1209,10 +1277,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");
     }
   }
   // ============================================================================
@@ -1253,14 +1318,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");
     }
   }
   /**
@@ -1271,11 +1333,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 };
       }
@@ -1313,25 +1375,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({
@@ -1341,10 +1395,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");
     }
   }
   // ============================================================================
@@ -1357,10 +1408,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) {
@@ -1376,10 +1424,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");
     }
   }
   // ============================================================================
@@ -1392,10 +1437,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) {
@@ -1407,10 +1449,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) {
@@ -1422,10 +1461,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");
     }
   }
   // ============================================================================
@@ -1433,16 +1469,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");
     }
   }
 };
@@ -1600,11 +1632,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")
       };
     }
   }
@@ -1650,11 +1678,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")
       };
     }
   }
@@ -1682,13 +1706,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 {
@@ -1703,11 +1724,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");
     }
   }
   /**
@@ -1761,11 +1778,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")
       };
     }
   }
@@ -1800,7 +1813,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 }
@@ -1876,10 +1891,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 }
@@ -1888,11 +1911,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")
       };
     }
   }
@@ -1909,11 +1928,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")
       };
     }
   }
@@ -2035,14 +2050,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");
@@ -2090,7 +2102,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() || "";
@@ -2138,7 +2152,7 @@ var ChatCompletions = class {
                   reader.releaseLock();
                   return;
                 }
-              } catch (e) {
+              } catch {
                 console.warn("Failed to parse SSE data:", dataStr);
               }
             }
@@ -2191,10 +2205,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,
@@ -2280,7 +2291,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 {
@@ -2326,7 +2339,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(
@@ -2345,7 +2360,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 {
@@ -2364,7 +2381,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(
@@ -2379,32 +2398,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();
@@ -2412,210 +2436,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);
@@ -2623,13 +2761,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() ?? []];
   }
 };
 
@@ -2644,13 +2780,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(
@@ -2733,10 +2868,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) {
@@ -2747,10 +2879,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) {
@@ -2859,7 +2988,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);
@@ -2879,32 +3009,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);
     }
   }
   /**
@@ -2938,6 +3071,7 @@ var src_default = InsForgeClient;
 0 && (module.exports = {
   AI,
   Auth,
+  AuthChangeEvent,
   Database,
   Emails,
   Functions,
@@ -2949,7 +3083,6 @@ var src_default = InsForgeClient;
   Realtime,
   Storage,
   StorageBucket,
-  TokenManager,
   createAdminClient,
   createClient
 });