@oxyhq/auth 1.0.0

package/dist/esm/utils/authHelpers.js

@@ -0,0 +1,145 @@
+/**
+ * Authentication helper utilities to reduce code duplication across hooks and utilities.
+ * These functions handle common token validation and authentication error patterns.
+ */
+/**
+ * Error thrown when session sync is required
+ */
+export class SessionSyncRequiredError extends Error {
+    constructor(message = 'Session needs to be synced. Please try again.') {
+        super(message);
+        this.name = 'SessionSyncRequiredError';
+    }
+}
+/**
+ * Error thrown when authentication fails
+ */
+export class AuthenticationFailedError extends Error {
+    constructor(message = 'Authentication failed. Please sign in again.') {
+        super(message);
+        this.name = 'AuthenticationFailedError';
+    }
+}
+/**
+ * Ensures a valid token exists before making authenticated API calls.
+ * If no valid token exists and an active session ID is available,
+ * attempts to refresh the token using the session.
+ *
+ * @param oxyServices - The OxyServices instance
+ * @param activeSessionId - The active session ID (if available)
+ * @throws {SessionSyncRequiredError} If the session needs to be synced (offline session)
+ * @throws {Error} If token refresh fails for other reasons
+ *
+ * @example
+ * ```ts
+ * // In a mutation or query function:
+ * await ensureValidToken(oxyServices, activeSessionId);
+ * return await oxyServices.updateProfile(updates);
+ * ```
+ */
+export async function ensureValidToken(oxyServices, activeSessionId) {
+    if (oxyServices.hasValidToken() || !activeSessionId) {
+        return;
+    }
+    try {
+        await oxyServices.getTokenBySession(activeSessionId);
+    }
+    catch (tokenError) {
+        const errorMessage = tokenError instanceof Error ? tokenError.message : String(tokenError);
+        if (errorMessage.includes('AUTH_REQUIRED_OFFLINE_SESSION') || errorMessage.includes('offline')) {
+            throw new SessionSyncRequiredError();
+        }
+        throw tokenError;
+    }
+}
+/**
+ * Checks if an error is an authentication error (401 or auth-related message)
+ *
+ * @param error - The error to check
+ * @returns True if the error is an authentication error
+ */
+export function isAuthenticationError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const errorObj = error;
+    const errorMessage = errorObj.message || '';
+    const status = errorObj.status || errorObj.response?.status;
+    return (status === 401 ||
+        errorMessage.includes('Authentication required') ||
+        errorMessage.includes('Invalid or missing authorization header'));
+}
+/**
+ * Wraps an API call with authentication error handling.
+ * If an authentication error occurs, it can optionally attempt to sync the session and retry.
+ *
+ * @param apiCall - The API call function to execute
+ * @param options - Optional error handling configuration
+ * @returns The result of the API call
+ * @throws {AuthenticationFailedError} If authentication fails and cannot be recovered
+ * @throws {Error} If the API call fails for non-auth reasons
+ *
+ * @example
+ * ```ts
+ * // Simple usage:
+ * const result = await withAuthErrorHandling(
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ *
+ * // With retry on auth failure:
+ * const result = await withAuthErrorHandling(
+ *   () => oxyServices.updateProfile(updates),
+ *   { syncSession, activeSessionId, oxyServices }
+ * );
+ * ```
+ */
+export async function withAuthErrorHandling(apiCall, options) {
+    try {
+        return await apiCall();
+    }
+    catch (error) {
+        if (!isAuthenticationError(error)) {
+            throw error;
+        }
+        // If we have sync capabilities, try to recover
+        if (options?.syncSession && options?.activeSessionId && options?.oxyServices) {
+            try {
+                await options.syncSession();
+                await options.oxyServices.getTokenBySession(options.activeSessionId);
+                // Retry the API call after refreshing token
+                return await apiCall();
+            }
+            catch {
+                throw new AuthenticationFailedError();
+            }
+        }
+        throw new AuthenticationFailedError();
+    }
+}
+/**
+ * Combines token validation and auth error handling for a complete authenticated API call.
+ * This is the recommended helper for most authenticated API operations.
+ *
+ * @param oxyServices - The OxyServices instance
+ * @param activeSessionId - The active session ID
+ * @param apiCall - The API call function to execute
+ * @param syncSession - Optional callback to sync session on auth failure
+ * @returns The result of the API call
+ *
+ * @example
+ * ```ts
+ * return await authenticatedApiCall(
+ *   oxyServices,
+ *   activeSessionId,
+ *   () => oxyServices.updateProfile(updates)
+ * );
+ * ```
+ */
+export async function authenticatedApiCall(oxyServices, activeSessionId, apiCall, syncSession) {
+    await ensureValidToken(oxyServices, activeSessionId);
+    return withAuthErrorHandling(apiCall, {
+        syncSession,
+        activeSessionId,
+        oxyServices,
+    });
+}

package/dist/esm/utils/avatarUtils.js

@@ -0,0 +1,72 @@
+import { useAccountStore } from '../stores/accountStore';
+import { useAuthStore } from '../stores/authStore';
+import { queryKeys, invalidateUserQueries, invalidateAccountQueries } from '../hooks/queries/queryKeys';
+import { authenticatedApiCall } from './authHelpers';
+/**
+ * Updates file visibility to public for avatar use.
+ * Handles errors gracefully, only logging non-404 errors.
+ *
+ * @param fileId - The file ID to update visibility for
+ * @param oxyServices - OxyServices instance
+ * @param contextName - Optional context name for logging
+ * @returns Promise that resolves when visibility is updated (or skipped)
+ */
+export async function updateAvatarVisibility(fileId, oxyServices, contextName = 'AvatarUtils') {
+    // Skip if temporary asset ID or no file ID
+    if (!fileId || fileId.startsWith('temp-')) {
+        return;
+    }
+    try {
+        await oxyServices.assetUpdateVisibility(fileId, 'public');
+        // Visibility update is logged by the API
+    }
+    catch (visError) {
+        // Silently handle errors - 404 means asset doesn't exist yet (which is OK)
+        // Other errors are logged by the API, so no need to log here
+        // Function continues gracefully regardless of visibility update success
+    }
+}
+/**
+ * Refreshes avatar in accountStore with cache-busted URL to force image reload.
+ *
+ * @param sessionId - The session ID for the account to update
+ * @param avatarFileId - The new avatar file ID
+ * @param oxyServices - OxyServices instance to generate download URL
+ */
+export function refreshAvatarInStore(sessionId, avatarFileId, oxyServices) {
+    const { updateAccount } = useAccountStore.getState();
+    const cacheBustedUrl = oxyServices.getFileDownloadUrl(avatarFileId, 'thumb') + `?t=${Date.now()}`;
+    updateAccount(sessionId, {
+        avatar: avatarFileId,
+        avatarUrl: cacheBustedUrl,
+    });
+}
+/**
+ * Updates user profile with avatar and handles all side effects (query invalidation, accountStore update).
+ * This function can be used from within OxyContext provider without requiring useOxy hook.
+ *
+ * @param updates - Profile updates including avatar
+ * @param oxyServices - OxyServices instance
+ * @param activeSessionId - Active session ID
+ * @param queryClient - TanStack Query client
+ * @param syncSession - Optional function to sync session/refresh token when auth errors occur
+ * @returns Promise that resolves with updated user data
+ */
+export async function updateProfileWithAvatar(updates, oxyServices, activeSessionId, queryClient, syncSession) {
+    const data = await authenticatedApiCall(oxyServices, activeSessionId, () => oxyServices.updateProfile(updates), syncSession);
+    // Update cache with server response
+    queryClient.setQueryData(queryKeys.accounts.current(), data);
+    if (activeSessionId) {
+        queryClient.setQueryData(queryKeys.users.profile(activeSessionId), data);
+    }
+    // Update authStore so frontend components see the changes immediately
+    useAuthStore.getState().setUser(data);
+    // If avatar was updated, refresh accountStore with cache-busted URL
+    if (updates.avatar && activeSessionId) {
+        refreshAvatarInStore(activeSessionId, updates.avatar, oxyServices);
+    }
+    // Invalidate all related queries to refresh everywhere
+    invalidateUserQueries(queryClient);
+    invalidateAccountQueries(queryClient);
+    return data;
+}

package/dist/esm/utils/errorHandlers.js

@@ -0,0 +1,121 @@
+const DEFAULT_INVALID_SESSION_MESSAGES = [
+    'Invalid or expired session',
+    'Session is invalid',
+    'Session not found',
+    'Session expired',
+];
+const isObject = (value) => typeof value === 'object' && value !== null;
+const getResponseStatus = (error) => {
+    if (!isObject(error))
+        return undefined;
+    const response = error.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) => {
+    const status = getResponseStatus(error);
+    if (status === 401) {
+        return true;
+    }
+    if (!isObject(error)) {
+        return false;
+    }
+    // Check error.status directly (HttpService sets this)
+    if (error.status === 401) {
+        return true;
+    }
+    const normalizedMessage = extractErrorMessage(error)?.toLowerCase();
+    if (!normalizedMessage) {
+        return false;
+    }
+    // Check for HTTP 401 in message (HttpService creates errors with "HTTP 401:" format)
+    if (normalizedMessage.includes('http 401') || normalizedMessage.includes('401')) {
+        return true;
+    }
+    return DEFAULT_INVALID_SESSION_MESSAGES.some((msg) => normalizedMessage.includes(msg.toLowerCase()));
+};
+/**
+ * Determine whether the error represents a timeout or network error.
+ * These are expected when the device is offline or has poor connectivity.
+ */
+export const isTimeoutOrNetworkError = (error) => {
+    if (!isObject(error) && !(error instanceof Error)) {
+        return false;
+    }
+    const message = extractErrorMessage(error, '').toLowerCase();
+    const errorCode = error.code;
+    // Check for timeout/cancelled messages
+    if (message.includes('timeout') ||
+        message.includes('cancelled') ||
+        message.includes('econnaborted') ||
+        message.includes('aborted') ||
+        message.includes('request timeout or cancelled')) {
+        return true;
+    }
+    // Check for timeout/network error codes
+    if (errorCode === 'TIMEOUT' || errorCode === 'NETWORK_ERROR' || errorCode === 'ECONNABORTED') {
+        return true;
+    }
+    // Check for AbortError
+    if (error instanceof Error && error.name === 'AbortError') {
+        return true;
+    }
+    // Check for network-related TypeErrors
+    if (error instanceof TypeError) {
+        const typeErrorMessage = error.message.toLowerCase();
+        if (typeErrorMessage.includes('fetch') ||
+            typeErrorMessage.includes('network') ||
+            typeErrorMessage.includes('failed to fetch')) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * 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, fallbackMessage = 'Unexpected error') => {
+    if (typeof error === 'string' && error.trim().length > 0) {
+        return error;
+    }
+    if (!isObject(error)) {
+        return fallbackMessage;
+    }
+    const withMessage = error;
+    if (withMessage.message && withMessage.message.trim().length > 0) {
+        return withMessage.message;
+    }
+    const withResponse = error;
+    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, { defaultMessage, code, status, onError, setAuthError, logger, }) => {
+    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;
+};

package/dist/esm/utils/sessionHelpers.js

@@ -0,0 +1,84 @@
+/**
+ * Normalize backend session payloads into `ClientSession` objects.
+ *
+ * @param sessions - Raw session array returned from the API
+ * @param fallbackDeviceId - Device identifier to use when missing from payload
+ * @param fallbackUserId - User identifier to use when missing from payload
+ */
+export const mapSessionsToClient = (sessions, fallbackDeviceId, fallbackUserId) => {
+    const now = new Date();
+    return sessions.map((session) => ({
+        sessionId: session.sessionId,
+        deviceId: session.deviceId || fallbackDeviceId || '',
+        expiresAt: session.expiresAt || new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+        lastActive: session.lastActive || now.toISOString(),
+        userId: session.user?.id ||
+            session.userId ||
+            (session.user?._id ? session.user._id.toString() : undefined) ||
+            fallbackUserId ||
+            '',
+        isCurrent: Boolean(session.isCurrent),
+    }));
+};
+/**
+ * Fetch device sessions with fallback to the legacy session endpoint when needed.
+ *
+ * @param oxyServices - Oxy service instance
+ * @param sessionId - Session identifier to fetch
+ * @param options - Optional fallback options
+ */
+export const fetchSessionsWithFallback = async (oxyServices, sessionId, { fallbackDeviceId, fallbackUserId, logger, } = {}) => {
+    try {
+        const deviceSessions = await oxyServices.getDeviceSessions(sessionId);
+        return mapSessionsToClient(deviceSessions, fallbackDeviceId, fallbackUserId);
+    }
+    catch (error) {
+        if (__DEV__ && logger) {
+            logger('Failed to get device sessions, falling back to user sessions', error);
+        }
+        const userSessions = await oxyServices.getSessionsBySessionId(sessionId);
+        return mapSessionsToClient(userSessions, fallbackDeviceId, fallbackUserId);
+    }
+};
+/**
+ * Validate multiple sessions concurrently with configurable concurrency.
+ *
+ * @param oxyServices - Oxy service instance
+ * @param sessionIds - Session identifiers to validate
+ * @param options - Validation options
+ */
+export const validateSessionBatch = async (oxyServices, sessionIds, { useHeaderValidation = true, maxConcurrency = 5 } = {}) => {
+    if (!sessionIds.length) {
+        return [];
+    }
+    const uniqueSessionIds = Array.from(new Set(sessionIds));
+    const safeConcurrency = Math.max(1, Math.min(maxConcurrency, uniqueSessionIds.length));
+    const results = [];
+    let index = 0;
+    const worker = async () => {
+        while (index < uniqueSessionIds.length) {
+            const currentIndex = index;
+            index += 1;
+            const sessionId = uniqueSessionIds[currentIndex];
+            try {
+                const validation = await oxyServices.validateSession(sessionId, { useHeaderValidation });
+                const valid = Boolean(validation?.valid);
+                results.push({
+                    sessionId,
+                    valid,
+                    user: validation?.user,
+                    raw: validation,
+                });
+            }
+            catch (error) {
+                results.push({
+                    sessionId,
+                    valid: false,
+                    error,
+                });
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: safeConcurrency }, worker));
+    return results;
+};

package/dist/esm/utils/storageHelpers.js

@@ -0,0 +1,108 @@
+/**
+ * Create an in-memory storage implementation used as a safe fallback.
+ */
+const MEMORY_STORAGE = () => {
+    const store = new Map();
+    return {
+        async getItem(key) {
+            return store.has(key) ? store.get(key) : null;
+        },
+        async setItem(key, value) {
+            store.set(key, value);
+        },
+        async removeItem(key) {
+            store.delete(key);
+        },
+        async clear() {
+            store.clear();
+        },
+    };
+};
+/**
+ * Create a web storage implementation backed by `localStorage`.
+ * Falls back to in-memory storage when unavailable.
+ */
+const createWebStorage = () => {
+    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
+        return MEMORY_STORAGE();
+    }
+    return {
+        async getItem(key) {
+            try {
+                return window.localStorage.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        async setItem(key, value) {
+            try {
+                window.localStorage.setItem(key, value);
+            }
+            catch {
+                // Ignore quota or access issues for now.
+            }
+        },
+        async removeItem(key) {
+            try {
+                window.localStorage.removeItem(key);
+            }
+            catch {
+                // Ignore failures.
+            }
+        },
+        async clear() {
+            try {
+                window.localStorage.clear();
+            }
+            catch {
+                // Ignore failures.
+            }
+        },
+    };
+};
+let asyncStorageInstance = null;
+/**
+ * Lazily import React Native AsyncStorage implementation.
+ */
+const createNativeStorage = async () => {
+    if (asyncStorageInstance) {
+        return asyncStorageInstance;
+    }
+    try {
+        const asyncStorageModule = await import('@react-native-async-storage/async-storage');
+        asyncStorageInstance = asyncStorageModule.default;
+        return asyncStorageInstance;
+    }
+    catch (error) {
+        if (__DEV__) {
+            console.error('Failed to import AsyncStorage:', error);
+        }
+        throw new Error('AsyncStorage is required in React Native environment');
+    }
+};
+/**
+ * Detect whether the current runtime is React Native.
+ */
+export const isReactNative = () => typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+/**
+ * Create a platform-appropriate storage implementation.
+ * Defaults to in-memory storage when no platform storage is available.
+ */
+export const createPlatformStorage = async () => {
+    if (isReactNative()) {
+        return createNativeStorage();
+    }
+    return createWebStorage();
+};
+export const STORAGE_KEY_PREFIX = 'oxy_session';
+/**
+ * Produce strongly typed storage key names for the supplied prefix.
+ *
+ * @param prefix - Storage key prefix
+ */
+export const getStorageKeys = (prefix = STORAGE_KEY_PREFIX) => ({
+    activeSessionId: `${prefix}_active_session_id`,
+    sessionIds: `${prefix}_session_ids`,
+    language: `${prefix}_language`,
+});

package/dist/types/WebOxyProvider.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @oxyhq/auth — Web Authentication Provider
+ *
+ * Clean implementation with ZERO React Native dependencies.
+ * Provides FedCM, popup, and redirect authentication methods.
+ * Uses centralized AuthManager for token and session management.
+ */
+import { type ReactNode } from 'react';
+import { OxyServices, CrossDomainAuth, AuthManager } from '@oxyhq/core';
+import type { User, ClientSession } from '@oxyhq/core';
+export interface WebAuthState {
+    user: User | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    error: string | null;
+    activeSessionId: string | null;
+    sessions: ClientSession[];
+}
+export interface WebAuthActions {
+    signIn: () => Promise<void>;
+    signInWithFedCM: () => Promise<void>;
+    signInWithPopup: () => Promise<void>;
+    signInWithRedirect: () => void;
+    signOut: () => Promise<void>;
+    isFedCMSupported: () => boolean;
+    switchSession: (sessionId: string) => Promise<void>;
+    clearSessionState: () => Promise<void>;
+}
+export interface WebOxyContextValue extends WebAuthState, WebAuthActions {
+    oxyServices: OxyServices;
+    crossDomainAuth: CrossDomainAuth;
+    authManager: AuthManager;
+}
+export interface WebOxyProviderProps {
+    children: ReactNode;
+    baseURL: string;
+    authWebUrl?: string;
+    onAuthStateChange?: (user: User | null) => void;
+    onError?: (error: Error) => void;
+    preferredAuthMethod?: 'auto' | 'fedcm' | 'popup' | 'redirect';
+    skipAutoCheck?: boolean;
+}
+/**
+ * Web-only Oxy Provider
+ *
+ * Provides authentication context for pure web applications (React, Next.js, Vite).
+ * Supports FedCM, popup, and redirect authentication methods.
+ *
+ * @example
+ * ```tsx
+ * import { WebOxyProvider, useAuth } from '@oxyhq/auth';
+ *
+ * function App() {
+ *   return (
+ *     <WebOxyProvider baseURL="https://api.oxy.so">
+ *       <YourApp />
+ *     </WebOxyProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function WebOxyProvider({ children, baseURL, authWebUrl, onAuthStateChange, onError, preferredAuthMethod, skipAutoCheck, }: WebOxyProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the full Web Oxy context.
+ */
+export declare function useWebOxy(): WebOxyContextValue;
+/**
+ * Hook for authentication in web apps.
+ *
+ * @example
+ * ```tsx
+ * function LoginPage() {
+ *   const { user, isAuthenticated, signIn, signOut } = useAuth();
+ *   if (!isAuthenticated) return <button onClick={signIn}>Sign in</button>;
+ *   return <button onClick={signOut}>Sign out</button>;
+ * }
+ * ```
+ */
+export declare function useAuth(): {
+    user: User | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    isReady: boolean;
+    error: string | null;
+    activeSessionId: string | null;
+    sessions: ClientSession[];
+    signIn: () => Promise<void>;
+    signInWithFedCM: () => Promise<void>;
+    signInWithPopup: () => Promise<void>;
+    signInWithRedirect: () => void;
+    signOut: () => Promise<void>;
+    isFedCMSupported: () => boolean;
+    switchSession: (sessionId: string) => Promise<void>;
+    oxyServices: OxyServices;
+    authManager: AuthManager;
+};
+export default WebOxyProvider;

package/dist/types/hooks/mutations/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Mutation Hooks
+ *
+ * TanStack Query mutation hooks for updating Oxy services data.
+ * All mutations handle authentication, error handling, and query invalidation.
+ */
+export { useUpdateProfile, useUploadAvatar, useUpdateAccountSettings, useUpdatePrivacySettings, useUploadFile, } from './useAccountMutations';
+export { useSwitchSession, useLogoutSession, useLogoutAll, useUpdateDeviceName, useRemoveDevice, } from './useServicesMutations';