@oxyhq/auth 1.0.0

package/src/stores/followStore.ts

@@ -0,0 +1,181 @@
+import { create } from 'zustand';
+import type { OxyServices } from '@oxyhq/core';
+
+interface FollowState {
+  followingUsers: Record<string, boolean>;
+  loadingUsers: Record<string, boolean>;
+  fetchingUsers: Record<string, boolean>;
+  errors: Record<string, string | null>;
+  // Follower counts for each user
+  followerCounts: Record<string, number>;
+  followingCounts: Record<string, number>;
+  // Loading states for counts
+  loadingCounts: Record<string, boolean>;
+  setFollowingStatus: (userId: string, isFollowing: boolean) => void;
+  clearFollowError: (userId: string) => void;
+  resetFollowState: () => void;
+  fetchFollowStatus: (userId: string, oxyServices: OxyServices) => Promise<void>;
+  toggleFollowUser: (userId: string, oxyServices: OxyServices, isCurrentlyFollowing: boolean) => Promise<void>;
+  // New methods for follower counts
+  setFollowerCount: (userId: string, count: number) => void;
+  setFollowingCount: (userId: string, count: number) => void;
+  updateCountsFromFollowAction: (targetUserId: string, action: 'follow' | 'unfollow', counts: { followers: number; following: number }, currentUserId?: string) => void;
+  fetchUserCounts: (userId: string, oxyServices: OxyServices) => Promise<void>;
+}
+
+export const useFollowStore = create<FollowState>((set: any, get: any) => ({
+  followingUsers: {},
+  loadingUsers: {},
+  fetchingUsers: {},
+  errors: {},
+  followerCounts: {},
+  followingCounts: {},
+  loadingCounts: {},
+  setFollowingStatus: (userId: string, isFollowing: boolean) => set((state: FollowState) => ({
+    followingUsers: { ...state.followingUsers, [userId]: isFollowing },
+    errors: { ...state.errors, [userId]: null },
+  })),
+  clearFollowError: (userId: string) => set((state: FollowState) => ({
+    errors: { ...state.errors, [userId]: null },
+  })),
+  resetFollowState: () => set({
+    followingUsers: {},
+    loadingUsers: {},
+    fetchingUsers: {},
+    errors: {},
+    followerCounts: {},
+    followingCounts: {},
+    loadingCounts: {},
+  }),
+  fetchFollowStatus: async (userId: string, oxyServices: OxyServices) => {
+    set((state: FollowState) => ({
+      fetchingUsers: { ...state.fetchingUsers, [userId]: true },
+      errors: { ...state.errors, [userId]: null },
+    }));
+    try {
+      const response = await oxyServices.getFollowStatus(userId);
+      set((state: FollowState) => ({
+        followingUsers: { ...state.followingUsers, [userId]: response.isFollowing },
+        fetchingUsers: { ...state.fetchingUsers, [userId]: false },
+        errors: { ...state.errors, [userId]: null },
+      }));
+    } catch (error: any) {
+      set((state: FollowState) => ({
+        fetchingUsers: { ...state.fetchingUsers, [userId]: false },
+        errors: { ...state.errors, [userId]: error?.message || 'Failed to fetch follow status' },
+      }));
+    }
+  },
+  toggleFollowUser: async (userId: string, oxyServices: OxyServices, isCurrentlyFollowing: boolean) => {
+    set((state: FollowState) => ({
+      loadingUsers: { ...state.loadingUsers, [userId]: true },
+      errors: { ...state.errors, [userId]: null },
+    }));
+    try {
+      let response: any;
+      let newFollowState;
+      if (isCurrentlyFollowing) {
+        response = await oxyServices.unfollowUser(userId);
+        newFollowState = false;
+      } else {
+        response = await oxyServices.followUser(userId);
+        newFollowState = true;
+      }
+      
+      // Update follow status
+      set((state: FollowState) => ({
+        followingUsers: { ...state.followingUsers, [userId]: newFollowState },
+        loadingUsers: { ...state.loadingUsers, [userId]: false },
+        errors: { ...state.errors, [userId]: null },
+      }));
+
+      // Update counts if the response includes them
+      // The API returns counts for both users:
+      // - followers: target user's follower count (the user being followed)
+      // - following: current user's following count (the user doing the following)
+      if (response && response.counts) {
+        const { counts } = response;
+        
+        // Get current user ID from oxyServices
+        const currentUserId = oxyServices.getCurrentUserId();
+        
+        set((state: FollowState) => {
+          const updates: any = {};
+          
+          // Update target user's follower count (the user being followed)
+          updates.followerCounts = { 
+            ...state.followerCounts, 
+            [userId]: counts.followers 
+          };
+          
+          // Update current user's following count (the user doing the following)
+          if (currentUserId) {
+            updates.followingCounts = { 
+              ...state.followingCounts, 
+              [currentUserId]: counts.following 
+            };
+          }
+          
+          return updates;
+        });
+      }
+    } catch (error: any) {
+      set((state: FollowState) => ({
+        loadingUsers: { ...state.loadingUsers, [userId]: false },
+        errors: { ...state.errors, [userId]: error?.message || 'Failed to update follow status' },
+      }));
+    }
+  },
+  setFollowerCount: (userId: string, count: number) => set((state: FollowState) => ({
+    followerCounts: { ...state.followerCounts, [userId]: count },
+  })),
+  setFollowingCount: (userId: string, count: number) => set((state: FollowState) => ({
+    followingCounts: { ...state.followingCounts, [userId]: count },
+  })),
+  updateCountsFromFollowAction: (targetUserId: string, action: 'follow' | 'unfollow', counts: { followers: number; following: number }, currentUserId?: string) => {
+    set((state: FollowState) => {
+      const updates: any = {};
+      
+      // Update target user's follower count (the user being followed)
+      updates.followerCounts = { 
+        ...state.followerCounts, 
+        [targetUserId]: counts.followers 
+      };
+      
+      // Update current user's following count (the user doing the following)
+      if (currentUserId) {
+        updates.followingCounts = { 
+          ...state.followingCounts, 
+          [currentUserId]: counts.following 
+        };
+      }
+      
+      return updates;
+    });
+  },
+  fetchUserCounts: async (userId: string, oxyServices: OxyServices) => {
+    set((state: FollowState) => ({
+      loadingCounts: { ...state.loadingCounts, [userId]: true },
+    }));
+    try {
+      const user = await oxyServices.getUserById(userId);
+      if (user && user._count) {
+        set((state: FollowState) => ({
+          followerCounts: { 
+            ...state.followerCounts, 
+            [userId]: user._count?.followers || 0 
+          },
+          followingCounts: { 
+            ...state.followingCounts, 
+            [userId]: user._count?.following || 0 
+          },
+          loadingCounts: { ...state.loadingCounts, [userId]: false },
+        }));
+      }
+    } catch (error: unknown) {
+      set((state: FollowState) => ({
+        loadingCounts: { ...state.loadingCounts, [userId]: false },
+      }));
+    }
+  },
+})); 

package/src/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 '@oxyhq/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/utils/avatarUtils.ts

@@ -0,0 +1,103 @@
+import type { OxyServices } from '@oxyhq/core';
+import type { User } from '@oxyhq/core';
+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.
+ * 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: string | undefined,
+  oxyServices: OxyServices,
+  contextName: string = 'AvatarUtils'
+): Promise<void> {
+  // 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: any) {
+    // 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: string,
+  avatarFileId: string,
+  oxyServices: OxyServices
+): void {
+  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: Partial<User>,
+  oxyServices: OxyServices,
+  activeSessionId: string | null,
+  queryClient: QueryClient,
+  syncSession?: () => Promise<User>
+): Promise<User> {
+  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);
+  }
+
+  // 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/utils/errorHandlers.ts

@@ -0,0 +1,194 @@
+import type { ApiError } from '@oxyhq/core';
+
+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;
+  }
+
+  // Check error.status directly (HttpService sets this)
+  if ((error as any).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: unknown): boolean => {
+  if (!isObject(error) && !(error instanceof Error)) {
+    return false;
+  }
+
+  const message = extractErrorMessage(error, '').toLowerCase();
+  const errorCode = (error as any).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: 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;
+};
+
+