Add onAuthStateChange listener and refactor popup auth to use setToken

- Add onAuthStateChange(callback) to auth module, fires SIGNED_IN,
  SIGNED_OUT, and TOKEN_REFRESHED events with an unsubscribe pattern
- Refactor popup OAuth to call setToken instead of redirecting, so
  auth state propagates via events without a page reload
- Export AuthEvent, AuthEventData, AuthStateChangeCallback types
- Add unit tests for onAuthStateChange

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: roymiloh

src/index.ts

@@ -50,6 +50,9 @@ export type {
 
 export type {
   AuthModule,
+  AuthEvent,
+  AuthEventData,
+  AuthStateChangeCallback,
   LoginResponse,
   RegisterParams,
   VerifyOtpParams,

src/modules/auth.ts

@@ -2,6 +2,9 @@ import { AxiosInstance } from "axios";
 import {
   AuthModule,
   AuthModuleOptions,
+  AuthEvent,
+  AuthEventData,
+  AuthStateChangeCallback,
   VerifyOtpParams,
   ChangePasswordParams,
   ResetPasswordParams,
@@ -14,18 +17,17 @@ function isInsideIframe(): boolean {
 
 /**
  * Opens a URL in a centered popup and waits for the backend to postMessage
- * the auth result back. On success, redirects the current window to
- * redirectUrl with the token params appended, preserving the same behaviour
- * as a normal full-page redirect flow.
+ * the auth result back. On success, calls onToken so the SDK can set the
+ * token and fire auth state change events — no page redirect needed.
  *
  * @param url - The login URL to open in the popup (should include popup_origin).
- * @param redirectUrl - Where to redirect after auth (the original fromUrl).
  * @param expectedOrigin - The origin we expect the postMessage to come from.
+ * @param onToken - Callback invoked with the access_token when auth completes.
  */
 function loginViaPopup(
   url: string,
-  redirectUrl: string,
-  expectedOrigin: string
+  expectedOrigin: string,
+  onToken: (accessToken: string) => void
 ): void {
   const width = 500;
   const height = 600;
@@ -54,19 +56,7 @@ function loginViaPopup(
     if (!event.data?.access_token) return;
 
     cleanup();
-
-    // Append the token params to redirectUrl so the app processes them
-    // exactly as it would from a normal OAuth callback redirect.
-    const callbackUrl = new URL(redirectUrl);
-    const { access_token, is_new_user } = event.data;
-
-    callbackUrl.searchParams.set("access_token", access_token);
-
-    if (is_new_user != null) {
-      callbackUrl.searchParams.set("is_new_user", String(is_new_user));
-    }
-
-    window.location.href = callbackUrl.toString();
+    onToken(event.data.access_token);
   };
 
   // Only used to detect the user closing the popup before auth completes
@@ -93,6 +83,13 @@ export function createAuthModule(
   appId: string,
   options: AuthModuleOptions
 ): AuthModule {
+  const listeners = new Set<AuthStateChangeCallback>();
+  let hasToken = false;
+
+  function notify(event: AuthEvent, data: AuthEventData = {}) {
+    listeners.forEach((cb) => cb(event, data));
+  }
+
   return {
     // Get current user information
     async me() {
@@ -148,7 +145,9 @@ export function createAuthModule(
       // blocking iframe navigation.
       if (isInsideIframe()) {
         const popupLoginUrl = `${loginUrl}&popup_origin=${encodeURIComponent(window.location.origin)}`;
-        return loginViaPopup(popupLoginUrl, redirectUrl, window.location.origin);
+        return loginViaPopup(popupLoginUrl, window.location.origin, (token) => {
+          this.setToken(token);
+        });
       }
 
       // Default: full-page redirect
@@ -159,6 +158,8 @@ export function createAuthModule(
     logout(redirectUrl?: string) {
       // Remove token from axios headers (always do this)
       delete axios.defaults.headers.common["Authorization"];
+      hasToken = false;
+      notify("SIGNED_OUT");
 
       // Only do the rest if in a browser environment
       if (typeof window !== "undefined") {
@@ -186,6 +187,8 @@ export function createAuthModule(
     setToken(token: string, saveToStorage = true) {
       if (!token) return;
 
+      const event: AuthEvent = hasToken ? "TOKEN_REFRESHED" : "SIGNED_IN";
+
       // handle token change for axios clients
       axios.defaults.headers.common["Authorization"] = `Bearer ${token}`;
       functionsAxiosClient.defaults.headers.common[
@@ -206,6 +209,9 @@ export function createAuthModule(
           console.error("Failed to save token to localStorage:", e);
         }
       }
+
+      hasToken = true;
+      notify(event, { access_token: token });
     },
 
     // Login using username and password
@@ -311,5 +317,13 @@ export function createAuthModule(
         new_password: newPassword,
       });
     },
+
+    // Subscribe to auth state changes
+    onAuthStateChange(callback: AuthStateChangeCallback) {
+      listeners.add(callback);
+      return () => {
+        listeners.delete(callback);
+      };
+    },
   };
 }

src/modules/auth.types.ts

@@ -102,6 +102,29 @@ export interface AuthModuleOptions {
   appBaseUrl: string;
 }
 
+/**
+ * Auth state change event types.
+ */
+export type AuthEvent = "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED";
+
+/**
+ * Data passed to auth state change callbacks.
+ */
+export interface AuthEventData {
+  /** JWT access token, present on SIGNED_IN and TOKEN_REFRESHED events. */
+  access_token?: string;
+  /** User data, present on SIGNED_IN when available. */
+  user?: User;
+}
+
+/**
+ * Callback for auth state changes.
+ */
+export type AuthStateChangeCallback = (
+  event: AuthEvent,
+  data: AuthEventData
+) => void;
+
 /**
  * Authentication module for managing user authentication and authorization. The module automatically stores tokens in local storage when available and manages authorization headers for API requests.
  *
@@ -507,4 +530,34 @@ export interface AuthModule {
    * ```
    */
   changePassword(params: ChangePasswordParams): Promise<any>;
+
+  /**
+   * Registers a callback that fires whenever the authentication state changes.
+   *
+   * Events:
+   * - `SIGNED_IN` — fired after a successful login (email/password, OAuth, or popup).
+   * - `SIGNED_OUT` — fired after logout.
+   * - `TOKEN_REFRESHED` — fired when `setToken` is called while already authenticated.
+   *
+   * Returns an unsubscribe function. Call it to stop receiving events.
+   *
+   * @param callback - Function called with the event type and associated data.
+   * @returns Unsubscribe function.
+   *
+   * @example
+   * ```typescript
+   * // In a React AuthContext provider
+   * useEffect(() => {
+   *   const unsubscribe = base44.auth.onAuthStateChange((event, data) => {
+   *     if (event === 'SIGNED_IN') {
+   *       setUser(data.user);
+   *     } else if (event === 'SIGNED_OUT') {
+   *       setUser(null);
+   *     }
+   *   });
+   *   return unsubscribe;
+   * }, []);
+   * ```
+   */
+  onAuthStateChange(callback: AuthStateChangeCallback): () => void;
 }

tests/unit/auth.test.js

@@ -632,15 +632,99 @@ describe('Auth Module', () => {
       // Mock network error
       scope.get(`/api/apps/${appId}/entities/User/me`)
         .replyWithError('Network error');
-        
+
       // Call the API
       const result = await base44.auth.isAuthenticated();
-      
+
       // Verify the response
       expect(result).toBe(false);
-      
+
       // Verify all mocks were called
       expect(scope.isDone()).toBe(true);
     });
   });
+
+  describe('onAuthStateChange()', () => {
+    test('should fire SIGNED_IN when setToken is called for the first time', () => {
+      const callback = vi.fn();
+      base44.auth.onAuthStateChange(callback);
+
+      base44.auth.setToken('token-1', false);
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith('SIGNED_IN', { access_token: 'token-1' });
+    });
+
+    test('should fire TOKEN_REFRESHED when setToken is called again', () => {
+      const callback = vi.fn();
+      base44.auth.onAuthStateChange(callback);
+
+      base44.auth.setToken('token-1', false);
+      base44.auth.setToken('token-2', false);
+
+      expect(callback).toHaveBeenCalledTimes(2);
+      expect(callback).toHaveBeenCalledWith('TOKEN_REFRESHED', { access_token: 'token-2' });
+    });
+
+    test('should fire SIGNED_OUT on logout', () => {
+      const callback = vi.fn();
+      base44.auth.onAuthStateChange(callback);
+
+      base44.auth.logout();
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith('SIGNED_OUT', {});
+    });
+
+    test('should fire SIGNED_IN on loginViaEmailPassword', async () => {
+      const callback = vi.fn();
+      base44.auth.onAuthStateChange(callback);
+
+      scope.post(`/api/apps/${appId}/auth/login`)
+        .reply(200, { access_token: 'login-token', user: { id: 'u1', email: 'a@b.com' } });
+
+      await base44.auth.loginViaEmailPassword('a@b.com', 'pass');
+
+      expect(callback).toHaveBeenCalledWith('SIGNED_IN', { access_token: 'login-token' });
+    });
+
+    test('should stop firing after unsubscribe', () => {
+      const callback = vi.fn();
+      const unsubscribe = base44.auth.onAuthStateChange(callback);
+
+      base44.auth.setToken('token-1', false);
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+
+      base44.auth.setToken('token-2', false);
+      expect(callback).toHaveBeenCalledTimes(1); // no additional call
+    });
+
+    test('should support multiple listeners', () => {
+      const cb1 = vi.fn();
+      const cb2 = vi.fn();
+      base44.auth.onAuthStateChange(cb1);
+      base44.auth.onAuthStateChange(cb2);
+
+      base44.auth.setToken('token-1', false);
+
+      expect(cb1).toHaveBeenCalledTimes(1);
+      expect(cb2).toHaveBeenCalledTimes(1);
+    });
+
+    test('should fire SIGNED_IN again after logout and new setToken', () => {
+      const callback = vi.fn();
+      base44.auth.onAuthStateChange(callback);
+
+      base44.auth.setToken('token-1', false);
+      expect(callback).toHaveBeenCalledWith('SIGNED_IN', { access_token: 'token-1' });
+
+      base44.auth.logout();
+      expect(callback).toHaveBeenCalledWith('SIGNED_OUT', {});
+
+      base44.auth.setToken('token-2', false);
+      expect(callback).toHaveBeenCalledWith('SIGNED_IN', { access_token: 'token-2' });
+    });
+  });
 });