rehive 4.1.4 → 4.2.0

package/src/auth/create-auth.ts

@@ -14,10 +14,16 @@ import type {
 import { WebStorageAdapter, MemoryStorageAdapter } from './core/storage-adapters.js';
 import { ApiError, normalizeFetch } from '../shared/api-utils.js';
 import type {
+  AuthEvent,
+  AuthEventListener,
+  AuthRecoveryState,
   AuthSession,
+  AuthSnapshot,
   AuthState,
-  SessionListener,
+  AuthStateListener,
+  AuthStatus,
   ErrorListener,
+  SessionListener,
   StorageAdapter,
 } from './types/index.js';
 
@@ -43,6 +49,21 @@ export type RegisterParams = {
 
 export type RegisterCompanyParams = RegisterCompanyRequestWritable;
 
+export interface ImportTokenOptions {
+  company?: string;
+  expires?: number;
+  sessionDuration?: number;
+}
+
+export interface ValidateSessionOptions {
+  retryCount?: number;
+  retryDelayMs?: number;
+}
+
+export type SessionPatch =
+  | Partial<AuthSession>
+  | ((session: AuthSession) => AuthSession);
+
 export interface AuthConfig {
   baseUrl?: string;
   storage?: 'local' | 'memory' | StorageAdapter;
@@ -61,11 +82,25 @@ export interface Auth {
   getActiveSession(): AuthSession | null;
   getSessions(): AuthSession[];
   getSessionsByCompany(company: string): AuthSession[];
+  getState(): AuthSnapshot;
+  getStatus(): AuthStatus;
+  getRecoveryState(): AuthRecoveryState;
   switchToSession(userId: string, company?: string): Promise<AuthSession | null>;
   clearAllSessions(): Promise<void>;
   deleteChallenge(challengeId: string): Promise<void>;
+  importToken(token: string, options?: ImportTokenOptions): Promise<AuthSession>;
+  validateActiveSession(options?: ValidateSessionOptions): Promise<boolean>;
+  syncActiveSessionUser(): Promise<AuthSession | null>;
+  updateSession(
+    userId: string,
+    company: string | undefined,
+    patch: SessionPatch,
+  ): Promise<AuthSession | null>;
+  expireActiveSession(): Promise<AuthRecoveryState>;
   subscribe(listener: SessionListener): () => void;
   subscribeToErrors(listener: ErrorListener): () => void;
+  subscribeToState(listener: AuthStateListener): () => void;
+  subscribeToEvents(listener: AuthEventListener): () => void;
   readonly baseUrl: string;
 }
 
@@ -106,46 +141,195 @@ function errorHandlingFetch(baseFetch: typeof fetch): typeof fetch {
   };
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function getSessionCompany(session: AuthSession): string | undefined {
+  return session.company ?? session.user?.company;
+}
+
+function cloneSessions(sessions: AuthSession[]): AuthSession[] {
+  return [...sessions];
+}
+
 export function createAuth(config: AuthConfig = {}): Auth {
   const baseUrl = config.baseUrl || 'https://api.rehive.com';
   const storage = resolveStorage(config.storage);
   const permanentToken = config.token;
   const enableCrossTabSync = config.enableCrossTabSync ?? true;
   const storageKey = 'rehive_auth_state';
+  const baseFetch = normalizeFetch(globalThis.fetch);
 
   const client = createClient({
     baseUrl,
     responseStyle: 'data' as const,
-    fetch: errorHandlingFetch(normalizeFetch(globalThis.fetch)),
+    fetch: errorHandlingFetch(baseFetch),
   });
 
   let sessions: AuthSession[] = [];
   let activeSessionIndex = -1;
   let sessionListeners: SessionListener[] = [];
   let errorListeners: ErrorListener[] = [];
+  let stateListeners: AuthStateListener[] = [];
+  let eventListeners: AuthEventListener[] = [];
   let refreshPromise: Promise<void> | null = null;
   let isRefreshing = false;
   let loadAuthStatePromise: Promise<AuthState> | null = null;
   let initialized = false;
+  let initializePromise: Promise<void> | null = null;
+  let cachedSnapshot: AuthSnapshot | null = null;
+  let lastError: Error | null = null;
+  let lastExpiredSession: AuthSession | null = null;
 
   function isTokenExpired(expires: number): boolean {
     return Date.now() >= expires - 30 * 1000;
   }
 
-  function getActiveSession(): AuthSession | null {
-    if (activeSessionIndex >= 0 && activeSessionIndex < sessions.length) {
-      return sessions[activeSessionIndex];
+  function getActiveSessionFromState(state: AuthState): AuthSession | null {
+    if (
+      state.activeSessionIndex >= 0 &&
+      state.activeSessionIndex < state.sessions.length
+    ) {
+      return state.sessions[state.activeSessionIndex];
     }
     return null;
   }
 
-  function notifySessionListeners(): void {
-    const session = getActiveSession();
-    sessionListeners.forEach((listener) => listener(session));
+  function getCurrentState(): AuthState {
+    return {
+      sessions: cloneSessions(sessions),
+      activeSessionIndex,
+    };
+  }
+
+  function getActiveSession(): AuthSession | null {
+    return getActiveSessionFromState(getCurrentState());
+  }
+
+  function buildRecoveryState(state: AuthState = getCurrentState()): AuthRecoveryState {
+    const session = getActiveSessionFromState(state);
+    const pending = !permanentToken && !session && state.sessions.length > 0;
+
+    return {
+      pending,
+      expiredSession: pending ? lastExpiredSession : null,
+      remainingSessions: pending ? cloneSessions(state.sessions) : [],
+    };
   }
 
-  function notifyErrorListeners(error: Error | null): void {
-    errorListeners.forEach((listener) => listener(error));
+  function getStatus(state: AuthState = getCurrentState()): AuthStatus {
+    if (!initialized && !permanentToken) {
+      return 'loading';
+    }
+    if (isRefreshing) {
+      return 'refreshing';
+    }
+    if (permanentToken) {
+      return 'authenticated';
+    }
+    if (getActiveSessionFromState(state)) {
+      return 'authenticated';
+    }
+    if (state.sessions.length > 0) {
+      return 'recoverable';
+    }
+    return 'unauthenticated';
+  }
+
+  function getState(): AuthSnapshot {
+    if (cachedSnapshot) {
+      return cachedSnapshot;
+    }
+    const state = getCurrentState();
+    cachedSnapshot = {
+      status: getStatus(state),
+      session: getActiveSessionFromState(state),
+      sessions: state.sessions,
+      activeSessionIndex: state.activeSessionIndex,
+      isRefreshing,
+      initialized: initialized || !!permanentToken,
+      error: lastError,
+      recovery: buildRecoveryState(state),
+    };
+    return cachedSnapshot;
+  }
+
+  function invalidateSnapshot(): void {
+    cachedSnapshot = null;
+  }
+
+  function emit(event: Omit<AuthEvent, 'snapshot'>): void {
+    const snapshot = getState();
+    const payload: AuthEvent = {
+      ...event,
+      snapshot,
+    };
+    eventListeners.forEach((listener) => listener(payload));
+  }
+
+  function notifyAll(event?: Omit<AuthEvent, 'snapshot'>): void {
+    invalidateSnapshot();
+    const snapshot = getState();
+    sessionListeners.forEach((listener) => listener(snapshot.session));
+    errorListeners.forEach((listener) => listener(snapshot.error));
+    stateListeners.forEach((listener) => listener(snapshot));
+
+    if (event) {
+      emit(event);
+    }
+  }
+
+  function setError(error: Error | null): void {
+    lastError = error;
+  }
+
+  async function persistState(state: AuthState): Promise<void> {
+    if (permanentToken) {
+      return;
+    }
+
+    await storage.setItem(storageKey, JSON.stringify(state));
+  }
+
+  async function applyState(
+    state: AuthState,
+    options: {
+      clearExpiredSession?: boolean;
+      expiredSession?: AuthSession | null;
+      error?: Error | null;
+      event?: Omit<AuthEvent, 'snapshot'>;
+    } = {},
+  ): Promise<void> {
+    sessions = cloneSessions(state.sessions);
+    activeSessionIndex =
+      state.activeSessionIndex >= 0 && state.activeSessionIndex < sessions.length
+        ? state.activeSessionIndex
+        : -1;
+
+    if (options.clearExpiredSession || activeSessionIndex >= 0 || sessions.length === 0) {
+      lastExpiredSession = null;
+    }
+    if (Object.prototype.hasOwnProperty.call(options, 'expiredSession')) {
+      lastExpiredSession = options.expiredSession ?? null;
+    }
+    if (Object.prototype.hasOwnProperty.call(options, 'error')) {
+      setError(options.error ?? null);
+    }
+
+    try {
+      await persistState({
+        sessions,
+        activeSessionIndex,
+      });
+    } catch (error) {
+      console.error('Failed to save auth state:', error);
+      if (!lastError && error instanceof Error) {
+        setError(error);
+      }
+    }
+
+    notifyAll(options.event);
   }
 
   async function loadAuthState(): Promise<AuthState> {
@@ -168,9 +352,17 @@ export function createAuth(config: AuthConfig = {}): Auth {
       } catch (error) {
         console.error('Failed to load auth state:', error);
       }
+
       sessions = state.sessions;
-      activeSessionIndex = state.activeSessionIndex;
-      return state;
+      activeSessionIndex =
+        state.activeSessionIndex >= 0 && state.activeSessionIndex < state.sessions.length
+          ? state.activeSessionIndex
+          : -1;
+
+      return {
+        sessions: cloneSessions(sessions),
+        activeSessionIndex,
+      };
     })();
 
     try {
@@ -180,51 +372,133 @@ export function createAuth(config: AuthConfig = {}): Auth {
     }
   }
 
-  async function saveAuthState(state: AuthState): Promise<void> {
-    try {
-      await storage.setItem(storageKey, JSON.stringify(state));
-      sessions = state.sessions;
-      activeSessionIndex = state.activeSessionIndex;
-      notifySessionListeners();
-    } catch (error) {
-      console.error('Failed to save auth state:', error);
-    }
-  }
-
   function setupCrossTabSync(): void {
     if (typeof window !== 'undefined') {
       window.addEventListener('storage', (event: StorageEvent) => {
-        if (event.key === storageKey && event.newValue) {
-          try {
-            const newState = JSON.parse(event.newValue);
-            sessions = Array.isArray(newState.sessions) ? newState.sessions : [];
-            activeSessionIndex =
-              typeof newState.activeSessionIndex === 'number'
-                ? newState.activeSessionIndex
-                : -1;
-            notifySessionListeners();
-          } catch (error) {
-            console.error('Failed to sync auth state from storage event:', error);
-          }
+        if (event.key !== storageKey) {
+          return;
+        }
+
+        if (!event.newValue) {
+          void applyState(
+            { sessions: [], activeSessionIndex: -1 },
+            { clearExpiredSession: true },
+          );
+          return;
+        }
+
+        try {
+          const newState = JSON.parse(event.newValue);
+          void applyState(
+            {
+              sessions: Array.isArray(newState.sessions) ? newState.sessions : [],
+              activeSessionIndex:
+                typeof newState.activeSessionIndex === 'number'
+                  ? newState.activeSessionIndex
+                  : -1,
+            },
+            {},
+          );
+        } catch (error) {
+          console.error('Failed to sync auth state from storage event:', error);
         }
       });
     }
   }
 
   async function initialize(): Promise<void> {
-    if (initialized) return;
-    initialized = true;
+    if (initialized) {
+      return;
+    }
+    if (initializePromise) {
+      return initializePromise;
+    }
+
+    initializePromise = (async () => {
+      if (!permanentToken) {
+        if (enableCrossTabSync) {
+          setupCrossTabSync();
+        }
+        await loadAuthState();
+      }
+      initialized = true;
+      notifyAll({ type: 'initialized' });
+    })();
+
+    return initializePromise;
+  }
+
+  async function fetchUserForToken(token: string): Promise<any> {
+    const response = await baseFetch(`${baseUrl.replace(/\/$/, '')}/3/user/`, {
+      headers: {
+        Authorization: `Token ${token}`,
+        'Content-Type': 'application/json',
+      },
+    });
 
-    if (!permanentToken) {
-      if (enableCrossTabSync) {
-        setupCrossTabSync();
+    if (!response.ok) {
+      const errorText = await response.text();
+      let errorJson: any = null;
+      try {
+        errorJson = JSON.parse(errorText);
+      } catch {
+        // not JSON
       }
-      await loadAuthState();
-      notifySessionListeners();
+
+      throw new ApiError({
+        status: response.status,
+        error: errorJson || errorText,
+        message:
+          errorJson?.error ||
+          errorJson?.message ||
+          'A server error occurred. HTTPStatus: ' + response.status,
+      });
     }
+
+    const payload = await response.json();
+    return payload?.data ?? payload;
+  }
+
+  async function upsertSession(
+    newSession: AuthSession,
+    eventType: AuthEvent['type'],
+  ): Promise<AuthSession> {
+    await initialize();
+    const currentState = await loadAuthState();
+    const sessionCompany = getSessionCompany(newSession);
+    const existingIdx = currentState.sessions.findIndex(
+      (session) =>
+        session.user.id === newSession.user.id &&
+        getSessionCompany(session) === sessionCompany,
+    );
+
+    let nextState: AuthState;
+    if (existingIdx >= 0) {
+      const updatedSessions = cloneSessions(currentState.sessions);
+      updatedSessions[existingIdx] = newSession;
+      nextState = {
+        sessions: updatedSessions,
+        activeSessionIndex: existingIdx,
+      };
+    } else {
+      nextState = {
+        sessions: [...currentState.sessions, newSession],
+        activeSessionIndex: currentState.sessions.length,
+      };
+    }
+
+    await applyState(nextState, {
+      clearExpiredSession: true,
+      error: null,
+      event: {
+        type: eventType,
+        session: newSession,
+      },
+    });
+
+    return newSession;
   }
 
-  // Kick off initialization (non-blocking)
   if (!permanentToken) {
     initialize().catch(console.error);
   }
@@ -244,40 +518,25 @@ export function createAuth(config: AuthConfig = {}): Auth {
       const result: any = await authLogin({ client, body, throwOnError: true });
       const data = result?.data ?? result;
 
-      const newSession: AuthSession = {
-        user: data.user,
-        token: data.token,
-        refresh_token: data.refresh_token,
-        challenges: data.challenges,
-        expires: data.expires,
-        session_duration: sessionDuration,
-        company: params.company,
-      };
-
-      const currentState = await loadAuthState();
-      const existingIdx = currentState.sessions.findIndex(
-        (s: AuthSession) =>
-          s.user.id === newSession.user.id && s.company === newSession.company,
+      return await upsertSession(
+        {
+          user: data.user,
+          token: data.token,
+          refresh_token: data.refresh_token,
+          challenges: data.challenges,
+          expires: data.expires,
+          session_duration: sessionDuration,
+          company: params.company,
+        },
+        'login',
       );
-
-      let newState: AuthState;
-      if (existingIdx !== -1) {
-        const updated = [...currentState.sessions];
-        updated[existingIdx] = newSession;
-        newState = { ...currentState, sessions: updated, activeSessionIndex: existingIdx };
-      } else {
-        newState = {
-          sessions: [...currentState.sessions, newSession],
-          activeSessionIndex: currentState.sessions.length,
-        };
-      }
-
-      await saveAuthState(newState);
-      notifyErrorListeners(null);
-      return newSession;
     } catch (e) {
       const error = e instanceof ApiError ? e : new Error('Login failed');
-      notifyErrorListeners(error);
+      setError(error);
+      notifyAll({
+        type: 'error',
+        error,
+      });
       throw e;
     }
   }
@@ -303,28 +562,25 @@ export function createAuth(config: AuthConfig = {}): Auth {
       const result: any = await authRegister({ client, body, throwOnError: true });
       const data = result?.data ?? result;
 
-      const newSession: AuthSession = {
-        user: data.user,
-        token: data.token,
-        refresh_token: data.refresh_token,
-        challenges: data.challenges,
-        expires: data.expires,
-        session_duration: sessionDuration,
-        company: params.company,
-      };
-
-      const currentState = await loadAuthState();
-      const newState: AuthState = {
-        sessions: [...currentState.sessions, newSession],
-        activeSessionIndex: currentState.sessions.length,
-      };
-
-      await saveAuthState(newState);
-      notifyErrorListeners(null);
-      return newSession;
+      return await upsertSession(
+        {
+          user: data.user,
+          token: data.token,
+          refresh_token: data.refresh_token,
+          challenges: data.challenges,
+          expires: data.expires,
+          session_duration: sessionDuration,
+          company: params.company,
+        },
+        'register',
+      );
     } catch (e) {
       const error = e instanceof ApiError ? e : new Error('Registration failed');
-      notifyErrorListeners(error);
+      setError(error);
+      notifyAll({
+        type: 'error',
+        error,
+      });
       throw e;
     }
   }
@@ -332,47 +588,45 @@ export function createAuth(config: AuthConfig = {}): Auth {
   async function registerCompanyFn(params: RegisterCompanyParams): Promise<AuthSession> {
     await initialize();
     try {
-      const body: RegisterCompanyRequestWritable = params;
-      const result: any = await authRegisterCompany({ client, body, throwOnError: true });
+      const result: any = await authRegisterCompany({
+        client,
+        body: params,
+        throwOnError: true,
+      });
       const data = result?.data ?? result;
-
-      const newSession: AuthSession = {
-        user: data.user,
-        token: data.token,
-        refresh_token: data.refresh_token,
-        challenges: data.challenges,
-        expires: data.expires,
-        session_duration: 900,
-        company: typeof params.company === 'string' ? params.company : (params.company as any)?.id,
-      };
-
-      const currentState = await loadAuthState();
-      const newState: AuthState = {
-        sessions: [...currentState.sessions, newSession],
-        activeSessionIndex: currentState.sessions.length,
-      };
-
-      await saveAuthState(newState);
-      notifyErrorListeners(null);
-      return newSession;
+      const company =
+        typeof params.company === 'string'
+          ? params.company
+          : (params.company as any)?.id;
+
+      return await upsertSession(
+        {
+          user: data.user,
+          token: data.token,
+          refresh_token: data.refresh_token,
+          challenges: data.challenges,
+          expires: data.expires,
+          session_duration: 900,
+          company,
+        },
+        'register-company',
+      );
     } catch (e) {
-      const error = e instanceof ApiError ? e : new Error('Company registration failed');
-      notifyErrorListeners(error);
+      const error =
+        e instanceof ApiError ? e : new Error('Company registration failed');
+      setError(error);
+      notifyAll({
+        type: 'error',
+        error,
+      });
       throw e;
     }
   }
 
   async function logout(): Promise<void> {
+    await initialize();
     const currentState = await loadAuthState();
-    const session = currentState.sessions[currentState.activeSessionIndex];
-
-    const newState: AuthState = {
-      ...currentState,
-      sessions: currentState.sessions.filter(
-        (_: AuthSession, i: number) => i !== currentState.activeSessionIndex,
-      ),
-      activeSessionIndex: -1,
-    };
+    const session = getActiveSessionFromState(currentState);
 
     if (session?.token) {
       try {
@@ -383,19 +637,34 @@ export function createAuth(config: AuthConfig = {}): Auth {
           throwOnError: true,
         });
       } catch {
-        // Continue with local logout even if API call fails
+        // Continue with local logout even if API call fails.
       }
     }
 
-    await saveAuthState(newState);
-    notifyErrorListeners(null);
+    await applyState(
+      {
+        sessions: currentState.sessions.filter(
+          (_session, index) => index !== currentState.activeSessionIndex,
+        ),
+        activeSessionIndex: -1,
+      },
+      {
+        clearExpiredSession: true,
+        error: null,
+        event: {
+          type: 'logout',
+          session,
+        },
+      },
+    );
   }
 
   async function logoutAll(): Promise<void> {
+    await initialize();
     const currentState = await loadAuthState();
 
     await Promise.all(
-      currentState.sessions.map(async (session: AuthSession) => {
+      currentState.sessions.map(async (session) => {
         try {
           await authLogout({
             client,
@@ -404,26 +673,44 @@ export function createAuth(config: AuthConfig = {}): Auth {
             throwOnError: true,
           });
         } catch {
-          // Log but continue
+          // Continue clearing local sessions even if API logout fails.
         }
       }),
     );
 
-    await saveAuthState({ sessions: [], activeSessionIndex: -1 });
-    notifyErrorListeners(null);
+    await applyState(
+      {
+        sessions: [],
+        activeSessionIndex: -1,
+      },
+      {
+        clearExpiredSession: true,
+        error: null,
+        event: {
+          type: 'logout-all',
+        },
+      },
+    );
   }
 
   async function refresh(): Promise<void> {
-    if (refreshPromise) return refreshPromise;
+    if (refreshPromise) {
+      return refreshPromise;
+    }
 
     refreshPromise = (async () => {
       isRefreshing = true;
+      notifyAll();
+
+      let sessionBeforeRefresh: AuthSession | null = null;
+
       try {
         const currentState = await loadAuthState();
         const idx = currentState.activeSessionIndex;
-        const session = currentState.sessions[idx];
+        const session = getActiveSessionFromState(currentState);
+        sessionBeforeRefresh = session;
 
-        if (!session?.token || !session?.refresh_token) {
+        if (idx < 0 || !session?.token || !session.refresh_token) {
           throw new Error('No active session, token, or refresh token found');
         }
 
@@ -435,33 +722,60 @@ export function createAuth(config: AuthConfig = {}): Auth {
         });
         const data = result?.data ?? result;
 
-        const updatedSessions = [...currentState.sessions];
+        const updatedSessions = cloneSessions(currentState.sessions);
         updatedSessions[idx] = {
           ...session,
-          refresh_token: data.refresh_token,
-          expires: data.expires,
+          token: data.token ?? session.token,
+          refresh_token: data.refresh_token ?? session.refresh_token,
+          expires: data.expires ?? session.expires,
           session_duration: session.session_duration ?? 900,
-          company: session.company,
+          company: getSessionCompany(session),
         };
 
-        await saveAuthState({ ...currentState, sessions: updatedSessions });
-        notifyErrorListeners(null);
+        await applyState(
+          {
+            sessions: updatedSessions,
+            activeSessionIndex: idx,
+          },
+          {
+            clearExpiredSession: true,
+            error: null,
+            event: {
+              type: 'refresh',
+              session: updatedSessions[idx],
+            },
+          },
+        );
       } catch (e) {
         const error = e instanceof ApiError ? e : new Error('Refresh failed');
-        notifyErrorListeners(error);
-
         const currentState = await loadAuthState();
-        await saveAuthState({
-          ...currentState,
-          sessions: currentState.sessions.filter(
-            (_: AuthSession, i: number) => i !== currentState.activeSessionIndex,
-          ),
-          activeSessionIndex: -1,
-        });
+        const expiredSession =
+          sessionBeforeRefresh ??
+          getActiveSessionFromState(currentState);
+        const nextSessions = currentState.sessions.filter(
+          (_session, index) => index !== currentState.activeSessionIndex,
+        );
+
+        await applyState(
+          {
+            sessions: nextSessions,
+            activeSessionIndex: -1,
+          },
+          {
+            expiredSession: expiredSession ?? null,
+            error,
+            event: {
+              type: 'session-expired',
+              session: expiredSession,
+              error,
+            },
+          },
+        );
         throw e;
       } finally {
         isRefreshing = false;
         refreshPromise = null;
+        notifyAll();
       }
     })();
 
@@ -469,11 +783,15 @@ export function createAuth(config: AuthConfig = {}): Auth {
   }
 
   async function getToken(): Promise<string | undefined> {
-    if (permanentToken) return permanentToken;
+    if (permanentToken) {
+      return permanentToken;
+    }
 
     await initialize();
     const session = getActiveSession();
-    if (!session) return undefined;
+    if (!session) {
+      return undefined;
+    }
 
     if (session.expires && isTokenExpired(session.expires)) {
       try {
@@ -491,17 +809,34 @@ export function createAuth(config: AuthConfig = {}): Auth {
     userId: string,
     company?: string,
   ): Promise<AuthSession | null> {
+    await initialize();
     const currentState = await loadAuthState();
     const idx = currentState.sessions.findIndex(
-      (s: AuthSession) => s.user.id === userId && s.company === company,
+      (session) =>
+        session.user.id === userId && getSessionCompany(session) === company,
     );
 
-    if (idx === -1) return null;
+    if (idx === -1) {
+      return null;
+    }
 
-    const session = currentState.sessions[idx];
-    await saveAuthState({ ...currentState, activeSessionIndex: idx });
+    await applyState(
+      {
+        sessions: currentState.sessions,
+        activeSessionIndex: idx,
+      },
+      {
+        clearExpiredSession: true,
+        error: null,
+        event: {
+          type: 'session-switched',
+          session: currentState.sessions[idx],
+        },
+      },
+    );
 
-    if (session.expires && isTokenExpired(session.expires)) {
+    const session = getActiveSession();
+    if (session?.expires && isTokenExpired(session.expires)) {
       await refresh();
       return getActiveSession();
     }
@@ -510,23 +845,272 @@ export function createAuth(config: AuthConfig = {}): Auth {
   }
 
   async function clearAllSessions(): Promise<void> {
-    await saveAuthState({ sessions: [], activeSessionIndex: -1 });
-    notifyErrorListeners(null);
+    await initialize();
+    await applyState(
+      {
+        sessions: [],
+        activeSessionIndex: -1,
+      },
+      {
+        clearExpiredSession: true,
+        error: null,
+        event: {
+          type: 'session-cleared',
+        },
+      },
+    );
   }
 
   async function deleteChallenge(challengeId: string): Promise<void> {
+    await initialize();
     const currentState = await loadAuthState();
     const idx = currentState.activeSessionIndex;
-    if (idx < 0 || idx >= currentState.sessions.length) return;
+
+    if (idx < 0 || idx >= currentState.sessions.length) {
+      return;
+    }
 
     const session = currentState.sessions[idx];
-    const updatedSessions = [...currentState.sessions];
+    const updatedSessions = cloneSessions(currentState.sessions);
     updatedSessions[idx] = {
       ...session,
-      challenges: session.challenges?.filter((c: any) => c.id !== challengeId) || [],
+      challenges:
+        session.challenges?.filter((challenge: any) => challenge.id !== challengeId) ||
+        [],
     };
 
-    await saveAuthState({ ...currentState, sessions: updatedSessions });
+    await applyState(
+      {
+        sessions: updatedSessions,
+        activeSessionIndex: idx,
+      },
+      {
+        error: null,
+      },
+    );
+  }
+
+  async function importToken(
+    token: string,
+    options: ImportTokenOptions = {},
+  ): Promise<AuthSession> {
+    await initialize();
+    const user = await fetchUserForToken(token);
+    const sessionDuration = options.sessionDuration ?? 900;
+
+    return upsertSession(
+      {
+        user,
+        token,
+        refresh_token: '',
+        challenges: [],
+        expires: options.expires ?? Date.now() + 30 * 24 * 60 * 60 * 1000,
+        session_duration: sessionDuration,
+        company: options.company ?? user?.company,
+      },
+      'session-imported',
+    );
+  }
+
+  async function validateActiveSession(
+    options: ValidateSessionOptions = {},
+  ): Promise<boolean> {
+    await initialize();
+    if (!getActiveSession()?.token) {
+      return false;
+    }
+
+    const retryCount = options.retryCount ?? 1;
+    const retryDelayMs = options.retryDelayMs ?? 400;
+    let refreshAttempted = false;
+
+    for (let attempt = 0; attempt <= retryCount; attempt += 1) {
+      const activeSession = getActiveSession();
+
+      if (!activeSession?.token) {
+        return false;
+      }
+
+      try {
+        await fetchUserForToken(activeSession.token);
+        return true;
+      } catch (error) {
+        const status =
+          error instanceof ApiError
+            ? error.status
+            : typeof error === 'object' &&
+                error &&
+                'status' in error &&
+                typeof (error as any).status === 'number'
+              ? (error as any).status
+              : undefined;
+
+        if (status === 401 || status === 403) {
+          if (!refreshAttempted && activeSession.refresh_token) {
+            refreshAttempted = true;
+
+            try {
+              await refresh();
+            } catch {
+              await expireActiveSession();
+              return false;
+            }
+
+            const refreshedSession = getActiveSession();
+            if (!refreshedSession?.token) {
+              return false;
+            }
+
+            try {
+              await fetchUserForToken(refreshedSession.token);
+              return true;
+            } catch {
+              await expireActiveSession();
+              return false;
+            }
+          }
+
+          if (attempt < retryCount) {
+            await sleep(retryDelayMs);
+            continue;
+          }
+          await expireActiveSession();
+          return false;
+        }
+
+        if (attempt < retryCount) {
+          await sleep(retryDelayMs);
+          continue;
+        }
+
+        return false;
+      }
+    }
+
+    return false;
+  }
+
+  async function syncActiveSessionUser(): Promise<AuthSession | null> {
+    await initialize();
+    const currentState = await loadAuthState();
+    const idx = currentState.activeSessionIndex;
+    const session = getActiveSessionFromState(currentState);
+
+    if (idx < 0 || !session?.token) {
+      return null;
+    }
+
+    const user = await fetchUserForToken(session.token);
+    const updatedSession: AuthSession = {
+      ...session,
+      user: {
+        ...session.user,
+        ...user,
+      },
+      company: user?.company ?? getSessionCompany(session),
+    };
+
+    const updatedSessions = cloneSessions(currentState.sessions);
+    updatedSessions[idx] = updatedSession;
+
+    await applyState(
+      {
+        sessions: updatedSessions,
+        activeSessionIndex: idx,
+      },
+      {
+        error: null,
+        event: {
+          type: 'session-updated',
+          session: updatedSession,
+        },
+      },
+    );
+
+    return updatedSession;
+  }
+
+  async function updateSession(
+    userId: string,
+    company: string | undefined,
+    patch: SessionPatch,
+  ): Promise<AuthSession | null> {
+    await initialize();
+    const currentState = await loadAuthState();
+    const idx = currentState.sessions.findIndex(
+      (session) =>
+        session.user.id === userId && getSessionCompany(session) === company,
+    );
+
+    if (idx === -1) {
+      return null;
+    }
+
+    const currentSession = currentState.sessions[idx];
+    const updatedSession =
+      typeof patch === 'function'
+        ? patch(currentSession)
+        : {
+            ...currentSession,
+            ...patch,
+            user: patch.user
+              ? {
+                  ...currentSession.user,
+                  ...patch.user,
+                }
+              : currentSession.user,
+            company:
+              patch.company ??
+              patch.user?.company ??
+              getSessionCompany(currentSession),
+          };
+
+    const updatedSessions = cloneSessions(currentState.sessions);
+    updatedSessions[idx] = updatedSession;
+
+    await applyState(
+      {
+        sessions: updatedSessions,
+        activeSessionIndex: currentState.activeSessionIndex,
+      },
+      {
+        error: null,
+        event: {
+          type: 'session-updated',
+          session: updatedSession,
+        },
+      },
+    );
+
+    return updatedSession;
+  }
+
+  async function expireActiveSession(): Promise<AuthRecoveryState> {
+    await initialize();
+    const currentState = await loadAuthState();
+    const session = getActiveSessionFromState(currentState);
+
+    if (!session) {
+      return buildRecoveryState(currentState);
+    }
+
+    const nextState: AuthState = {
+      sessions: currentState.sessions.filter(
+        (_entry, index) => index !== currentState.activeSessionIndex,
+      ),
+      activeSessionIndex: -1,
+    };
+
+    await applyState(nextState, {
+      expiredSession: session,
+      error: null,
+      event: {
+        type: 'session-expired',
+        session,
+      },
+    });
+
+    return buildRecoveryState();
   }
 
   return {
@@ -538,22 +1122,42 @@ export function createAuth(config: AuthConfig = {}): Auth {
     refresh,
     getToken,
     getActiveSession,
-    getSessions: () => [...sessions],
+    getSessions: () => cloneSessions(sessions),
     getSessionsByCompany: (company: string) =>
-      sessions.filter((s) => s.company === company),
+      sessions.filter((session) => getSessionCompany(session) === company),
+    getState,
+    getStatus: () => getStatus(),
+    getRecoveryState: () => buildRecoveryState(),
     switchToSession,
     clearAllSessions,
     deleteChallenge,
+    importToken,
+    validateActiveSession,
+    syncActiveSessionUser,
+    updateSession,
+    expireActiveSession,
     subscribe(listener: SessionListener): () => void {
       sessionListeners.push(listener);
       return () => {
-        sessionListeners = sessionListeners.filter((l) => l !== listener);
+        sessionListeners = sessionListeners.filter((entry) => entry !== listener);
       };
     },
     subscribeToErrors(listener: ErrorListener): () => void {
       errorListeners.push(listener);
       return () => {
-        errorListeners = errorListeners.filter((l) => l !== listener);
+        errorListeners = errorListeners.filter((entry) => entry !== listener);
+      };
+    },
+    subscribeToState(listener: AuthStateListener): () => void {
+      stateListeners.push(listener);
+      return () => {
+        stateListeners = stateListeners.filter((entry) => entry !== listener);
+      };
+    },
+    subscribeToEvents(listener: AuthEventListener): () => void {
+      eventListeners.push(listener);
+      return () => {
+        eventListeners = eventListeners.filter((entry) => entry !== listener);
       };
     },
     get baseUrl() {