@oxyhq/services 5.14.0 → 5.15.1

package/src/ui/context/hooks/useSessionManagement.ts

@@ -0,0 +1,378 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+import type { ApiError, User } from '../../../models/interfaces';
+import type { ClientSession } from '../../../models/session';
+import { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual } from '../../../utils/sessionUtils';
+import { fetchSessionsWithFallback, mapSessionsToClient, validateSessionBatch } from '../utils/sessionHelpers';
+import { getStorageKeys, type StorageInterface } from '../utils/storageHelpers';
+import { handleAuthError, isInvalidSessionError } from '../utils/errorHandlers';
+import type { OxyServices } from '../../../core';
+
+export interface UseSessionManagementOptions {
+  oxyServices: OxyServices;
+  storage: StorageInterface | null;
+  storageKeyPrefix?: string;
+  loginSuccess: (user: User) => void;
+  logoutStore: () => void;
+  applyLanguagePreference: (user: User) => Promise<void>;
+  onAuthStateChange?: (user: User | null) => void;
+  onError?: (error: ApiError) => void;
+  setAuthError?: (message: string | null) => void;
+  logger?: (message: string, error?: unknown) => void;
+  setTokenReady?: (ready: boolean) => void;
+}
+
+export interface UseSessionManagementResult {
+  sessions: ClientSession[];
+  activeSessionId: string | null;
+  setActiveSessionId: (sessionId: string | null) => void;
+  updateSessions: (incoming: ClientSession[], options?: { merge?: boolean }) => void;
+  switchSession: (sessionId: string) => Promise<User>;
+  refreshSessions: (activeUserId?: string) => Promise<void>;
+  clearSessionState: () => Promise<void>;
+  saveActiveSessionId: (sessionId: string) => Promise<void>;
+  trackRemovedSession: (sessionId: string) => void;
+  storageKeys: ReturnType<typeof getStorageKeys>;
+  isRefreshInFlight: boolean;
+}
+
+const DEFAULT_SAVE_ERROR_MESSAGE = 'Failed to save session data';
+const CLEAR_STORAGE_ERROR = 'Failed to clear storage';
+
+/**
+ * Manage session state, persistence, and high-level multi-session operations.
+ *
+ * @param options - Session management configuration
+ */
+export const useSessionManagement = ({
+  oxyServices,
+  storage,
+  storageKeyPrefix,
+  loginSuccess,
+  logoutStore,
+  applyLanguagePreference,
+  onAuthStateChange,
+  onError,
+  setAuthError,
+  logger,
+  setTokenReady,
+}: UseSessionManagementOptions): UseSessionManagementResult => {
+  const [sessions, setSessions] = useState<ClientSession[]>([]);
+  const [activeSessionId, setActiveSessionId] = useState<string | null>(null);
+
+  const refreshInFlightRef = useRef<Promise<void> | null>(null);
+  const removedSessionsRef = useRef<Set<string>>(new Set());
+  const lastRefreshRef = useRef<number>(0);
+
+  const storageKeys = useMemo(() => getStorageKeys(storageKeyPrefix), [storageKeyPrefix]);
+
+  const saveSessionIds = useCallback(
+    async (sessionIds: string[]): Promise<void> => {
+      if (!storage) return;
+      try {
+        const uniqueIds = Array.from(new Set(sessionIds));
+        await storage.setItem(storageKeys.sessionIds, JSON.stringify(uniqueIds));
+      } catch (error) {
+        if (logger) {
+          logger(DEFAULT_SAVE_ERROR_MESSAGE, error);
+        } else if (__DEV__) {
+          console.warn('Failed to save session IDs:', error);
+        }
+      }
+    },
+    [logger, storage, storageKeys.sessionIds],
+  );
+
+  const updateSessions = useCallback(
+    (incoming: ClientSession[], options: { merge?: boolean } = {}): void => {
+      setSessions((prevSessions) => {
+        const processed = options.merge
+          ? mergeSessions(prevSessions, incoming, activeSessionId, false)
+          : normalizeAndSortSessions(incoming, activeSessionId, false);
+
+        if (storage) {
+          void saveSessionIds(processed.map((session) => session.sessionId));
+        }
+
+        if (sessionsArraysEqual(prevSessions, processed)) {
+          return prevSessions;
+        }
+        return processed;
+      });
+    },
+    [activeSessionId, saveSessionIds, storage],
+  );
+
+  const saveActiveSessionId = useCallback(
+    async (sessionId: string): Promise<void> => {
+      if (!storage) return;
+      try {
+        await storage.setItem(storageKeys.activeSessionId, sessionId);
+      } catch (error) {
+        handleAuthError(error, {
+          defaultMessage: DEFAULT_SAVE_ERROR_MESSAGE,
+          code: 'SESSION_PERSISTENCE_ERROR',
+          onError,
+          setAuthError,
+          logger,
+        });
+      }
+    },
+    [logger, onError, setAuthError, storage, storageKeys.activeSessionId],
+  );
+
+  const removeActiveSessionId = useCallback(async (): Promise<void> => {
+    if (!storage) return;
+    try {
+      await storage.removeItem(storageKeys.activeSessionId);
+    } catch (error) {
+      handleAuthError(error, {
+        defaultMessage: DEFAULT_SAVE_ERROR_MESSAGE,
+        code: 'SESSION_PERSISTENCE_ERROR',
+        onError,
+        setAuthError,
+        logger,
+      });
+    }
+  }, [logger, onError, setAuthError, storage, storageKeys.activeSessionId]);
+
+  const clearSessionStorage = useCallback(async (): Promise<void> => {
+    if (!storage) return;
+    try {
+      await storage.removeItem(storageKeys.activeSessionId);
+      await storage.removeItem(storageKeys.sessionIds);
+    } catch (error) {
+      handleAuthError(error, {
+        defaultMessage: CLEAR_STORAGE_ERROR,
+        code: 'STORAGE_ERROR',
+        onError,
+        setAuthError,
+        logger,
+      });
+    }
+  }, [logger, onError, setAuthError, storage, storageKeys.activeSessionId, storageKeys.sessionIds]);
+
+  const clearSessionState = useCallback(async (): Promise<void> => {
+    setSessions([]);
+    setActiveSessionId(null);
+    logoutStore();
+    await clearSessionStorage();
+    onAuthStateChange?.(null);
+  }, [clearSessionStorage, logoutStore, onAuthStateChange]);
+
+  const activateSession = useCallback(
+    async (sessionId: string, user: User): Promise<void> => {
+      await oxyServices.getTokenBySession(sessionId);
+      setTokenReady?.(true);
+      setActiveSessionId(sessionId);
+      loginSuccess(user);
+      await saveActiveSessionId(sessionId);
+      await applyLanguagePreference(user);
+      onAuthStateChange?.(user);
+    },
+    [
+      applyLanguagePreference,
+      loginSuccess,
+      onAuthStateChange,
+      oxyServices,
+      saveActiveSessionId,
+      setTokenReady,
+    ],
+  );
+
+  const trackRemovedSession = useCallback((sessionId: string) => {
+    removedSessionsRef.current.add(sessionId);
+    setTimeout(() => {
+      removedSessionsRef.current.delete(sessionId);
+    }, 5000);
+  }, []);
+
+  const findReplacementSession = useCallback(
+    async (sessionIds: string[]): Promise<User | null> => {
+      if (!sessionIds.length) {
+        return null;
+      }
+
+      const validationResults = await validateSessionBatch(oxyServices, sessionIds, {
+        maxConcurrency: 3,
+      });
+
+      const validSession = validationResults.find((result) => result.valid);
+      if (!validSession) {
+        return null;
+      }
+
+      const validation = await oxyServices.validateSession(validSession.sessionId, {
+        useHeaderValidation: true,
+      });
+
+      if (!validation?.valid || !validation.user) {
+        return null;
+      }
+
+      const user = validation.user as User;
+      await activateSession(validSession.sessionId, user);
+      return user;
+    },
+    [activateSession, oxyServices],
+  );
+
+  const switchSession = useCallback(
+    async (sessionId: string): Promise<User> => {
+      try {
+        const validation = await oxyServices.validateSession(sessionId, { useHeaderValidation: true });
+        if (!validation?.valid) {
+          throw new Error('Session is invalid or expired');
+        }
+
+        if (!validation.user) {
+          throw new Error('User data not available from session validation');
+        }
+
+        const user = validation.user as User;
+        await activateSession(sessionId, user);
+
+        try {
+          const deviceSessions = await fetchSessionsWithFallback(oxyServices, sessionId, {
+            fallbackUserId: user.id,
+            logger,
+          });
+          updateSessions(deviceSessions, { merge: true });
+        } catch (error) {
+          if (__DEV__) {
+            console.warn('Failed to synchronize sessions after switch:', error);
+          }
+        }
+
+        return user;
+      } catch (error) {
+        const invalidSession = isInvalidSessionError(error);
+
+        if (invalidSession) {
+          updateSessions(sessions.filter((session) => session.sessionId !== sessionId), {
+            merge: false,
+          });
+          if (sessionId === activeSessionId) {
+            const otherSessionIds = sessions
+              .filter(
+                (session) =>
+                  session.sessionId !== sessionId && !removedSessionsRef.current.has(session.sessionId),
+              )
+              .map((session) => session.sessionId);
+
+            const replacementUser = await findReplacementSession(otherSessionIds);
+            if (replacementUser) {
+              return replacementUser;
+            }
+          }
+        }
+
+        handleAuthError(error, {
+          defaultMessage: 'Failed to switch session',
+          code: invalidSession ? 'INVALID_SESSION' : 'SESSION_SWITCH_ERROR',
+          onError,
+          setAuthError,
+          logger,
+        });
+        throw error instanceof Error ? error : new Error('Failed to switch session');
+      }
+    },
+    [
+      activateSession,
+      activeSessionId,
+      findReplacementSession,
+      logger,
+      loginSuccess,
+      onError,
+      oxyServices,
+      sessions,
+      setAuthError,
+      updateSessions,
+    ],
+  );
+
+  const refreshSessions = useCallback(
+    async (activeUserId?: string): Promise<void> => {
+      if (!activeSessionId) return;
+
+      if (refreshInFlightRef.current) {
+        await refreshInFlightRef.current;
+        return;
+      }
+
+      const now = Date.now();
+      if (now - lastRefreshRef.current < 500) {
+        return;
+      }
+      lastRefreshRef.current = now;
+
+      const refreshPromise = (async () => {
+        try {
+          const deviceSessions = await fetchSessionsWithFallback(oxyServices, activeSessionId, {
+            fallbackUserId: activeUserId,
+            logger,
+          });
+          updateSessions(deviceSessions, { merge: true });
+        } catch (error) {
+          if (isInvalidSessionError(error)) {
+            const otherSessions = sessions
+              .filter(
+                (session) =>
+                  session.sessionId !== activeSessionId &&
+                  !removedSessionsRef.current.has(session.sessionId),
+              )
+              .map((session) => session.sessionId);
+
+            const replacementUser = await findReplacementSession(otherSessions);
+            if (!replacementUser) {
+              await clearSessionState();
+            }
+            return;
+          }
+
+          handleAuthError(error, {
+            defaultMessage: 'Failed to refresh sessions',
+            code: 'SESSION_REFRESH_ERROR',
+            onError,
+            setAuthError,
+            logger,
+          });
+        } finally {
+          refreshInFlightRef.current = null;
+          lastRefreshRef.current = Date.now();
+        }
+      })();
+
+      refreshInFlightRef.current = refreshPromise;
+      await refreshPromise;
+    },
+    [
+      activeSessionId,
+      clearSessionState,
+      findReplacementSession,
+      logger,
+      onError,
+      oxyServices,
+      sessions,
+      setAuthError,
+      updateSessions,
+    ],
+  );
+
+  const isRefreshInFlight = Boolean(refreshInFlightRef.current);
+
+  return {
+    sessions,
+    activeSessionId,
+    setActiveSessionId,
+    updateSessions,
+    switchSession,
+    refreshSessions,
+    clearSessionState,
+    saveActiveSessionId,
+    trackRemovedSession,
+    storageKeys,
+    isRefreshInFlight,
+  };
+};
+
+

package/src/ui/context/hooks/useStorage.ts

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ApiError } from '../../../models/interfaces';
+import { createPlatformStorage, type StorageInterface } from '../utils/storageHelpers';
+import { extractErrorMessage } from '../utils/errorHandlers';
+
+export interface UseStorageOptions {
+  onError?: (error: ApiError) => void;
+  logger?: (message: string, error?: unknown) => void;
+  errorCode?: string;
+}
+
+export interface UseStorageResult {
+  storage: StorageInterface | null;
+  isReady: boolean;
+  error: string | null;
+  refresh: () => Promise<StorageInterface | null>;
+  withStorage: <T>(callback: (storage: StorageInterface) => Promise<T>) => Promise<T | null>;
+}
+
+const DEFAULT_ERROR_CODE = 'STORAGE_INIT_ERROR';
+
+/**
+ * React hook that exposes a platform-agnostic storage reference.
+ * Handles initialization, error propagation, and lazy re-initialization.
+ *
+ * @param options - Optional configuration for error reporting and logging
+ */
+export const useStorage = ({
+  onError,
+  logger,
+  errorCode = DEFAULT_ERROR_CODE,
+}: UseStorageOptions = {}): UseStorageResult => {
+  const [storage, setStorage] = useState<StorageInterface | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const initializingRef = useRef<Promise<StorageInterface | null> | null>(null);
+
+  const notifyError = useCallback(
+    (err: unknown) => {
+      const message = extractErrorMessage(err, 'Failed to initialize storage');
+      setError(message);
+
+      if (logger) {
+        logger(message, err);
+      }
+
+      onError?.({
+        message,
+        code: errorCode,
+        status: 500,
+      });
+    },
+    [errorCode, logger, onError],
+  );
+
+  const createStorageInstance = useCallback(async (): Promise<StorageInterface | null> => {
+    try {
+      const platformStorage = await createPlatformStorage();
+      setStorage(platformStorage);
+      setError(null);
+      return platformStorage;
+    } catch (err) {
+      notifyError(err);
+      setStorage(null);
+      return null;
+    }
+  }, [notifyError]);
+
+  const refresh = useCallback(async (): Promise<StorageInterface | null> => {
+    if (!initializingRef.current) {
+      initializingRef.current = createStorageInstance().finally(() => {
+        initializingRef.current = null;
+      });
+    }
+
+    return initializingRef.current;
+  }, [createStorageInstance]);
+
+  useEffect(() => {
+    refresh().catch((err) => {
+      notifyError(err);
+    });
+  }, [refresh, notifyError]);
+
+  const withStorage = useCallback(
+    async <T,>(callback: (resolvedStorage: StorageInterface) => Promise<T>): Promise<T | null> => {
+      const resolvedStorage = storage ?? (await refresh());
+      if (!resolvedStorage) {
+        return null;
+      }
+      return callback(resolvedStorage);
+    },
+    [refresh, storage],
+  );
+
+  return {
+    storage,
+    isReady: Boolean(storage) && !error,
+    error,
+    refresh,
+    withStorage,
+  };
+};
+
+

package/src/ui/context/utils/errorHandlers.ts

@@ -0,0 +1,136 @@
+import type { ApiError } from '../../../models/interfaces';
+
+type ErrorWithMessage = {
+  message?: string;
+};
+
+type ErrorWithResponse = {
+  response?: {
+    status?: number;
+    data?: {
+      message?: string;
+      error?: string;
+    };
+  };
+};
+
+export interface HandleAuthErrorOptions {
+  defaultMessage: string;
+  code: string;
+  status?: number;
+  onError?: (error: ApiError) => void;
+  setAuthError?: (message: string) => void;
+  logger?: (message: string, error?: unknown) => void;
+}
+
+const DEFAULT_INVALID_SESSION_MESSAGES = [
+  'Invalid or expired session',
+  'Session is invalid',
+  'Session not found',
+  'Session expired',
+];
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const getResponseStatus = (error: unknown): number | undefined => {
+  if (!isObject(error)) return undefined;
+  const response = (error as ErrorWithResponse).response;
+  return response?.status;
+};
+
+/**
+ * Determine whether the error represents an invalid session condition.
+ * This centralizes 401 detection across different fetch clients.
+ */
+export const isInvalidSessionError = (error: unknown): boolean => {
+  const status = getResponseStatus(error);
+  if (status === 401) {
+    return true;
+  }
+
+  if (!isObject(error)) {
+    return false;
+  }
+
+  const normalizedMessage = extractErrorMessage(error)?.toLowerCase();
+  if (!normalizedMessage) {
+    return false;
+  }
+
+  return DEFAULT_INVALID_SESSION_MESSAGES.some((msg) =>
+    normalizedMessage.includes(msg.toLowerCase()),
+  );
+};
+
+/**
+ * Extract a consistent error message from unknown error shapes.
+ *
+ * @param error - The unknown error payload
+ * @param fallbackMessage - Message to return when no concrete message is available
+ */
+export const extractErrorMessage = (
+  error: unknown,
+  fallbackMessage = 'Unexpected error',
+): string => {
+  if (typeof error === 'string' && error.trim().length > 0) {
+    return error;
+  }
+
+  if (!isObject(error)) {
+    return fallbackMessage;
+  }
+
+  const withMessage = error as ErrorWithMessage;
+  if (withMessage.message && withMessage.message.trim().length > 0) {
+    return withMessage.message;
+  }
+
+  const withResponse = error as ErrorWithResponse;
+  const responseMessage =
+    withResponse.response?.data?.message ?? withResponse.response?.data?.error;
+
+  if (typeof responseMessage === 'string' && responseMessage.trim().length > 0) {
+    return responseMessage;
+  }
+
+  return fallbackMessage;
+};
+
+/**
+ * Centralized error handler for auth-related operations.
+ *
+ * @param error - Unknown error object
+ * @param options - Error handling configuration
+ * @returns Resolved error message
+ */
+export const handleAuthError = (
+  error: unknown,
+  {
+    defaultMessage,
+    code,
+    status,
+    onError,
+    setAuthError,
+    logger,
+  }: HandleAuthErrorOptions,
+): string => {
+  const resolvedStatus = status ?? getResponseStatus(error) ?? (isInvalidSessionError(error) ? 401 : 500);
+  const message = extractErrorMessage(error, defaultMessage);
+
+  if (logger) {
+    logger(message, error);
+  }
+
+  setAuthError?.(message);
+
+  onError?.({
+    message,
+    code,
+    status: resolvedStatus,
+  });
+
+  return message;
+};
+
+