@oxyhq/services 5.21.6 → 5.22.0

package/src/ui/utils/authHelpers.ts

@@ -0,0 +1,183 @@
+/**
+ * Authentication helper utilities to reduce code duplication across hooks and utilities.
+ * These functions handle common token validation and authentication error patterns.
+ */
+
+import type { OxyServices } from '../../core';
+
+/**
+ * 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: OxyServices,
+  activeSessionId: string | null | undefined
+): Promise<void> {
+  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;
+  }
+}
+
+/**
+ * Options for handling API authentication errors
+ */
+export interface HandleApiErrorOptions {
+  /** Optional callback to attempt session sync and retry */
+  syncSession?: () => Promise<unknown>;
+  /** The active session ID for retry attempts */
+  activeSessionId?: string | null;
+  /** The OxyServices instance for retry attempts */
+  oxyServices?: OxyServices;
+}
+
+/**
+ * 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: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+
+  const errorObj = error as { message?: string; status?: number; response?: { status?: number } };
+  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<T>(
+  apiCall: () => Promise<T>,
+  options?: HandleApiErrorOptions
+): Promise<T> {
+  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<T>(
+  oxyServices: OxyServices,
+  activeSessionId: string | null | undefined,
+  apiCall: () => Promise<T>,
+  syncSession?: () => Promise<unknown>
+): Promise<T> {
+  await ensureValidToken(oxyServices, activeSessionId);
+
+  return withAuthErrorHandling(apiCall, {
+    syncSession,
+    activeSessionId,
+    oxyServices,
+  });
+}

package/src/ui/utils/avatarUtils.ts

@@ -4,6 +4,7 @@ import { useAccountStore } from '../stores/accountStore';
 import { useAuthStore } from '../stores/authStore';
 import { QueryClient } from '@tanstack/react-query';
 import { queryKeys, invalidateUserQueries, invalidateAccountQueries } from '../hooks/queries/queryKeys';
+import { authenticatedApiCall } from './authHelpers';
 
 /**
  * Updates file visibility to public for avatar use.
@@ -57,7 +58,7 @@ export function refreshAvatarInStore(
 /**
  * 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
@@ -72,72 +73,31 @@ export async function updateProfileWithAvatar(
   queryClient: QueryClient,
   syncSession?: () => Promise<User>
 ): Promise<User> {
-  // Ensure we have a valid token before making the request
-  if (!oxyServices.hasValidToken() && activeSessionId) {
-    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')) {
-        if (syncSession) {
-          try {
-            await syncSession();
-            await oxyServices.getTokenBySession(activeSessionId);
-          } catch (syncError) {
-            throw new Error('Session needs to be synced. Please try again.');
-          }
-        } else {
-          throw tokenError;
-        }
-      } else {
-        throw tokenError;
-      }
-    }
+  const data = await authenticatedApiCall<User>(
+    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);
   }
 
-  try {
-    const data = await oxyServices.updateProfile(updates);
-    
-    // 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;
-  } catch (error: any) {
-    const errorMessage = error?.message || '';
-    const status = error?.status || error?.response?.status;
-    
-    // Handle authentication errors
-    if (status === 401 || errorMessage.includes('Authentication required') || errorMessage.includes('Invalid or missing authorization header')) {
-      if (activeSessionId && syncSession) {
-        try {
-          await syncSession();
-          await oxyServices.getTokenBySession(activeSessionId);
-          // Retry the update after getting token
-          return await updateProfileWithAvatar(updates, oxyServices, activeSessionId, queryClient, syncSession);
-        } catch (retryError) {
-          throw new Error('Authentication failed. Please sign in again.');
-        }
-      } else {
-        throw new Error('No active session. Please sign in.');
-      }
-    }
-    
-    throw error;
+  // 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/src/web.ts

@@ -0,0 +1,230 @@
+/**
+ * OxyHQServices Web Entry Point - Pure React/Next.js Apps
+ *
+ * This entry point is optimized for pure web applications without Expo or React Native.
+ * It excludes all React Native dependencies for a smaller bundle size.
+ *
+ * Use this for:
+ * - Pure React apps (Vite, Create React App)
+ * - Next.js apps
+ * - Any web-only application
+ *
+ * For Expo apps (native + web), use the main entry point instead:
+ * import { OxyProvider } from '@oxyhq/services';
+ */
+
+// IMPORTANT: Import crypto module first to ensure polyfills are loaded
+import './crypto/polyfill';
+
+// Core exports (no React Native dependencies)
+export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './core';
+export { OXY_CLOUD_URL, oxyClient } from './core';
+
+// Cross-domain authentication (Web SSO via FedCM/popup/redirect)
+export { CrossDomainAuth, createCrossDomainAuth } from './core';
+export type { CrossDomainAuthOptions } from './core';
+
+// Crypto/Identity exports
+export {
+  KeyManager,
+  SignatureService,
+  RecoveryPhraseService
+} from './crypto';
+export type {
+  KeyPair,
+  SignedMessage,
+  AuthChallenge,
+  RecoveryPhraseResult
+} from './crypto';
+
+// React context and auth hooks
+export { useOxy } from './ui/context/OxyContext';
+export { useAuth } from './ui/hooks/useAuth';
+export type { AuthState, AuthActions, UseAuthReturn } from './ui/hooks/useAuth';
+
+// Web-only provider (NO React Native dependencies)
+export { default as WebOxyProvider } from './ui/components/WebOxyProvider';
+
+// Device management
+export { DeviceManager } from './utils/deviceManager';
+export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
+
+// Language utilities
+export {
+  SUPPORTED_LANGUAGES,
+  getLanguageMetadata,
+  getLanguageName,
+  getNativeLanguageName,
+  normalizeLanguageCode
+} from './utils/languageUtils';
+export type { LanguageMetadata } from './utils/languageUtils';
+
+// Type exports
+export type {
+  OxyConfig,
+  User,
+  LoginResponse,
+  Notification,
+  Wallet,
+  Transaction,
+  TransferFundsRequest,
+  PurchaseRequest,
+  WithdrawalRequest,
+  TransactionResponse,
+  KarmaRule,
+  KarmaHistory,
+  KarmaLeaderboardEntry,
+  KarmaAwardRequest,
+  ApiError,
+  PaymentMethod,
+  PaymentRequest,
+  PaymentResponse,
+  AnalyticsData,
+  FollowerDetails,
+  ContentViewer,
+  FileMetadata,
+  FileUploadResponse,
+  FileListResponse,
+  FileUpdateRequest,
+  FileDeleteResponse,
+  DeviceSession,
+  DeviceSessionsResponse,
+  DeviceSessionLogoutResponse,
+  UpdateDeviceNameResponse,
+  BlockedUser,
+  RestrictedUser,
+  FileVisibility,
+  AssetLink,
+  AssetVariant,
+  Asset,
+  AssetInitRequest,
+  AssetInitResponse,
+  AssetCompleteRequest,
+  AssetLinkRequest,
+  AssetUnlinkRequest,
+  AssetUrlResponse,
+  AssetDeleteSummary,
+  AssetUploadProgress,
+  AssetUpdateVisibilityRequest,
+  AssetUpdateVisibilityResponse,
+  AccountStorageCategoryUsage,
+  AccountStorageUsageResponse,
+  SecurityEventType,
+  SecurityEventSeverity,
+  SecurityActivity,
+  SecurityActivityResponse
+} from './models/interfaces';
+
+export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
+
+export type {
+  SessionLoginResponse,
+  ClientSession,
+  MinimalUserData
+} from './models/session';
+
+// UI hooks - Stores
+export { useAuthStore } from './ui/stores/authStore';
+export {
+  useAssetStore,
+  useAssets as useAssetsStore,
+  useAsset,
+  useUploadProgress,
+  useAssetLoading,
+  useAssetErrors,
+  useAssetsByApp,
+  useAssetsByEntity,
+  useAssetUsageCount,
+  useIsAssetLinked
+} from './ui/stores/assetStore';
+
+// UI hooks - Custom hooks
+export { useSessionSocket } from './ui/hooks/useSessionSocket';
+export { useAssets, setOxyAssetInstance } from './ui/hooks/useAssets';
+export { useFileDownloadUrl, setOxyFileUrlInstance } from './ui/hooks/useFileDownloadUrl';
+
+// UI hooks - Query hooks (TanStack Query)
+export {
+  useUserProfile,
+  useUserProfiles,
+  useCurrentUser,
+  useUserById,
+  useUserByUsername,
+  useUsersBySessions,
+  usePrivacySettings,
+  useSessions,
+  useSession,
+  useDeviceSessions,
+  useUserDevices,
+  useSecurityInfo,
+  useSecurityActivity,
+  useRecentSecurityActivity,
+} from './ui/hooks/queries';
+
+// UI hooks - Mutation hooks (TanStack Query)
+export {
+  useUpdateProfile,
+  useUploadAvatar,
+  useUpdateAccountSettings,
+  useUpdatePrivacySettings,
+  useUploadFile,
+  useSwitchSession,
+  useLogoutSession,
+  useLogoutAll,
+  useUpdateDeviceName,
+  useRemoveDevice,
+} from './ui/hooks/mutations';
+
+// Mutation factory utilities
+export {
+  createProfileMutation,
+  createGenericMutation,
+} from './ui/hooks/mutations/mutationFactory';
+export type {
+  ProfileMutationConfig,
+  GenericMutationConfig,
+} from './ui/hooks/mutations/mutationFactory';
+
+// Authentication helpers
+export {
+  ensureValidToken,
+  withAuthErrorHandling,
+  authenticatedApiCall,
+  isAuthenticationError,
+  SessionSyncRequiredError,
+  AuthenticationFailedError,
+} from './ui/utils/authHelpers';
+export type { HandleApiErrorOptions } from './ui/utils/authHelpers';
+
+// File filtering hook
+export { useFileFiltering } from './ui/hooks/useFileFiltering';
+export type { ViewMode, SortBy, SortOrder } from './ui/hooks/useFileFiltering';
+
+// Web-compatible UI components (no React Native dependencies)
+export { OxySignInButton } from './ui/components/OxySignInButton';
+export { OxyLogo } from './ui/components/OxyLogo';
+
+// Utilities
+export * from './utils/apiUtils';
+export {
+  ErrorCodes,
+  createApiError,
+  handleHttpError,
+  validateRequiredFields,
+  retryWithBackoff
+} from './utils/errorUtils';
+export * from './utils/validationUtils';
+export {
+  logger,
+  LogLevel,
+  LogContext,
+  logAuth,
+  logApi,
+  logSession,
+  logUser,
+  logDevice,
+  logPayment,
+  logPerformance
+} from './utils/loggerUtils';
+export * from './utils/asyncUtils';
+export * from './utils/hookUtils';