@oxyhq/services 6.9.13 → 6.9.15

package/lib/typescript/ui/types/fileManagement.d.ts

@@ -0,0 +1,40 @@
+import type { BaseScreenProps } from './navigation';
+import type { FileMetadata } from '@oxyhq/core';
+export type OnConfirmFileSelection = (files: FileMetadata[]) => void;
+export interface FileManagementScreenProps extends BaseScreenProps {
+    userId?: string;
+    containerWidth?: number;
+    selectMode?: boolean;
+    multiSelect?: boolean;
+    onSelect?: (file: FileMetadata) => void;
+    onConfirmSelection?: OnConfirmFileSelection;
+    initialSelectedIds?: string[];
+    maxSelection?: number;
+    disabledMimeTypes?: string[];
+    /**
+     * What to do after a single selection (non-multiSelect) is made.
+     * 'close' (default) will dismiss the bottom sheet via onClose.
+     * 'back' will navigate back to the previous screen (e.g., return to AccountSettings without closing sheet).
+     * 'none' will keep the picker open (caller can manually close or navigate).
+     */
+    afterSelect?: 'close' | 'back' | 'none';
+    allowUploadInSelectMode?: boolean;
+    /**
+     * Default visibility for uploaded files in this screen
+     * Useful for third-party apps that want files to be public (e.g., GIF selector)
+     */
+    defaultVisibility?: 'private' | 'public' | 'unlisted';
+    /**
+     * Link context for tracking file usage by third-party apps
+     * When provided, selected files will be linked to this entity
+     */
+    linkContext?: {
+        app: string;
+        entityType: string;
+        entityId: string;
+        webhookUrl?: string;
+    };
+}
+export type ViewMode = 'all' | 'photos' | 'videos' | 'documents' | 'audio';
+export type SortBy = 'date' | 'size' | 'name' | 'type';
+export type SortOrder = 'asc' | 'desc';

package/lib/typescript/ui/types/navigation.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode, RefObject } from 'react';
+import type { QueryClient } from '@tanstack/react-query';
+import type { RouteName } from '../navigation/routes';
+export type { RouteName };
+export interface StepController {
+    canGoBack: () => boolean;
+    goBack: () => void;
+}
+export interface BaseScreenProps {
+    navigate?: (screen: RouteName, props?: Record<string, unknown>) => void;
+    goBack?: () => void;
+    onClose?: () => void;
+    onAuthenticated?: (payload?: unknown) => void;
+    theme?: 'light' | 'dark' | string;
+    initialStep?: number;
+    stepControllerRef?: RefObject<StepController | null>;
+    onStepChange?: (currentStep: number, totalSteps: number) => void;
+    currentScreen?: RouteName;
+    scrollTo?: (y: number, animated?: boolean) => void;
+    username?: string;
+    email?: string;
+    password?: string;
+    confirmPassword?: string;
+    userProfile?: unknown;
+    [key: string]: unknown;
+}
+export interface OxyProviderProps {
+    oxyServices?: unknown;
+    children?: ReactNode;
+    onAuthStateChange?: (user: unknown) => void;
+    storageKeyPrefix?: string;
+    baseURL?: string;
+    authWebUrl?: string;
+    authRedirectUri?: string;
+    queryClient?: QueryClient;
+}

package/lib/typescript/ui/utils/avatarUtils.d.ts

@@ -0,0 +1,22 @@
+import type { OxyServices, User } from '@oxyhq/core';
+import type { QueryClient } from '@tanstack/react-query';
+/**
+ * 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 declare function refreshAvatarInStore(sessionId: string, avatarFileId: string, oxyServices: OxyServices): void;
+/**
+ * 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 declare function updateProfileWithAvatar(updates: Partial<User>, oxyServices: OxyServices, activeSessionId: string | null, queryClient: QueryClient, syncSession?: () => Promise<User>): Promise<User>;

package/lib/typescript/ui/utils/colorUtils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Color Utility Functions
+ *
+ * Re-exports from shared module for cleaner internal imports.
+ * External consumers should use '@oxyhq/services/shared' directly.
+ *
+ * @module ui/utils/colorUtils
+ */
+export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from '@oxyhq/core';

package/lib/typescript/ui/utils/confirmAction.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cross-platform confirm dialog. Uses window.confirm on web, Alert.alert on native.
+ * @param message The message to display
+ * @param onConfirm Callback if user confirms
+ */
+export declare function confirmAction(message: string, onConfirm: () => void): void;

package/lib/typescript/ui/utils/errorHandlers.d.ts

@@ -0,0 +1,34 @@
+import type { ApiError } from '@oxyhq/core';
+export interface HandleAuthErrorOptions {
+    defaultMessage: string;
+    code: string;
+    status?: number;
+    onError?: (error: ApiError) => void;
+    setAuthError?: (message: string) => void;
+    logger?: (message: string, error?: unknown) => void;
+}
+/**
+ * Determine whether the error represents an invalid session condition.
+ * This centralizes 401 detection across different fetch clients.
+ */
+export declare const isInvalidSessionError: (error: unknown) => boolean;
+/**
+ * Determine whether the error represents a timeout or network error.
+ * These are expected when the device is offline or has poor connectivity.
+ */
+export declare const isTimeoutOrNetworkError: (error: unknown) => boolean;
+/**
+ * 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 declare const extractErrorMessage: (error: unknown, fallbackMessage?: string) => string;
+/**
+ * Centralized error handler for auth-related operations.
+ *
+ * @param error - Unknown error object
+ * @param options - Error handling configuration
+ * @returns Resolved error message
+ */
+export declare const handleAuthError: (error: unknown, { defaultMessage, code, status, onError, setAuthError, logger, }: HandleAuthErrorOptions) => string;

package/lib/typescript/ui/utils/fileManagement.d.ts

@@ -0,0 +1,86 @@
+import type { FileMetadata } from '@oxyhq/core';
+import type { RouteName } from '../navigation/routes';
+/**
+ * Format file size in bytes to human-readable string
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Get icon name for file based on content type
+ */
+export declare function getFileIcon(contentType: string): string;
+/**
+ * Unified confirmation dialog - uses Alert.alert for all platforms
+ */
+export declare function confirmAction(message: string, title?: string, confirmText?: string, cancelText?: string): Promise<boolean>;
+/**
+ * Convert DocumentPicker asset to File object
+ * Handles both web (native File API) and mobile (URI-based) file sources
+ * Expo 54 compatible - works across all platforms
+ */
+export declare function convertDocumentPickerAssetToFile(doc: {
+    file?: File | Blob;
+    uri?: string;
+    name?: string | null;
+    mimeType?: string | null;
+    size?: number | null;
+}, index: number): Promise<File | null>;
+/**
+ * Helper to safely request a thumbnail variant only for image mime types.
+ * Prevents backend warnings: "Variant thumb not supported for mime application/pdf".
+ *
+ * @param file - File metadata
+ * @param variant - Variant type (default: 'thumb')
+ * @param getFileDownloadUrl - Function to get download URL from oxyServices
+ */
+export declare function getSafeDownloadUrl(file: FileMetadata, variant: string, getFileDownloadUrl: (fileId: string, variant?: string) => string): string;
+/**
+ * Upload file raw - helper function for file uploads
+ */
+export declare function uploadFileRaw(file: File | Blob, userId: string, oxyServices: any, visibility?: 'private' | 'public' | 'unlisted'): Promise<any>;
+/**
+ * Configuration for creating an avatar picker handler
+ */
+export interface AvatarPickerConfig {
+    /** Navigation function from BaseScreenProps */
+    navigate?: (screen: RouteName, props?: Record<string, unknown>) => void;
+    /** OxyServices instance */
+    oxyServices: any;
+    /** TanStack Query mutation for updating profile */
+    updateProfileMutation: {
+        mutateAsync: (updates: {
+            avatar: string;
+        }) => Promise<unknown>;
+    };
+    /** Callback to update local avatar state */
+    onAvatarSelected?: (fileId: string) => void;
+    /** i18n translation function */
+    t: (key: string) => string | undefined;
+    /** Optional context name for logging (e.g., 'AccountSettings', 'WelcomeNewUser') */
+    contextName?: string;
+}
+/**
+ * Creates a reusable avatar picker handler function.
+ *
+ * This function navigates to the FileManagement screen and handles:
+ * - Image file validation
+ * - File visibility update to public
+ * - Profile avatar update via mutation
+ * - Success/error toast notifications
+ *
+ * @example
+ * ```tsx
+ * const openAvatarPicker = createAvatarPickerHandler({
+ *   navigate,
+ *   oxyServices,
+ *   updateProfileMutation,
+ *   onAvatarSelected: setAvatarFileId,
+ *   t,
+ *   contextName: 'AccountSettings'
+ * });
+ *
+ * <TouchableOpacity onPress={openAvatarPicker}>
+ *   <Text>Change Avatar</Text>
+ * </TouchableOpacity>
+ * ```
+ */
+export declare function createAvatarPickerHandler(config: AvatarPickerConfig): () => void;

package/lib/typescript/ui/utils/iconNames.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Type-safe icon name utilities
+ *
+ * Provides centralized, typed icon name mappings to eliminate `as any` casts
+ * when using dynamic icon names with @expo/vector-icons.
+ */
+/**
+ * Profile field icons (MaterialCommunityIcons)
+ */
+export declare const PROFILE_FIELD_ICONS: {
+    readonly displayName: "account-outline";
+    readonly username: "at";
+    readonly email: "email-outline";
+    readonly bio: "text-box-outline";
+    readonly location: "map-marker-outline";
+    readonly links: "link-variant";
+    readonly website: "web";
+    readonly phone: "phone-outline";
+    readonly birthday: "cake-variant-outline";
+};
+export type ProfileFieldIconKey = keyof typeof PROFILE_FIELD_ICONS;
+/**
+ * Get icon name for a profile field
+ */
+export declare function getProfileFieldIcon(field: string): string;
+/**
+ * Settings section icons (MaterialCommunityIcons)
+ */
+export declare const SETTINGS_ICONS: {
+    readonly account: "account-cog-outline";
+    readonly privacy: "shield-account-outline";
+    readonly security: "lock-outline";
+    readonly notifications: "bell-outline";
+    readonly language: "translate";
+    readonly appearance: "palette-outline";
+    readonly storage: "folder-outline";
+    readonly help: "help-circle-outline";
+    readonly about: "information-outline";
+    readonly logout: "logout";
+};
+export type SettingsIconKey = keyof typeof SETTINGS_ICONS;
+/**
+ * Get icon name for a settings section
+ */
+export declare function getSettingsIcon(section: string): string;
+/**
+ * File type icons (MaterialCommunityIcons)
+ */
+export declare const FILE_TYPE_ICONS: {
+    readonly image: "image-outline";
+    readonly video: "video-outline";
+    readonly audio: "music-note-outline";
+    readonly document: "file-document-outline";
+    readonly pdf: "file-pdf-box";
+    readonly archive: "folder-zip-outline";
+    readonly code: "code-tags";
+    readonly spreadsheet: "file-excel-outline";
+    readonly presentation: "file-presentation-outline";
+    readonly text: "file-document-edit-outline";
+    readonly unknown: "file-outline";
+};
+export type FileTypeIconKey = keyof typeof FILE_TYPE_ICONS;
+/**
+ * Get icon name for a file type
+ */
+export declare function getFileTypeIcon(type: string): string;
+/**
+ * Action icons (Ionicons)
+ */
+export declare const ACTION_ICONS: {
+    readonly close: "close";
+    readonly back: "chevron-back";
+    readonly forward: "chevron-forward";
+    readonly add: "add";
+    readonly remove: "remove";
+    readonly delete: "trash-outline";
+    readonly edit: "pencil-outline";
+    readonly save: "checkmark";
+    readonly cancel: "close";
+    readonly search: "search-outline";
+    readonly filter: "filter-outline";
+    readonly sort: "swap-vertical-outline";
+    readonly refresh: "refresh-outline";
+    readonly share: "share-outline";
+    readonly copy: "copy-outline";
+    readonly download: "download-outline";
+    readonly upload: "cloud-upload-outline";
+};
+export type ActionIconKey = keyof typeof ACTION_ICONS;
+/**
+ * Get icon name for an action
+ */
+export declare function getActionIcon(action: string): string;
+/**
+ * Status icons (Ionicons)
+ */
+export declare const STATUS_ICONS: {
+    readonly success: "checkmark-circle";
+    readonly error: "alert-circle";
+    readonly warning: "warning";
+    readonly info: "information-circle";
+    readonly loading: "hourglass-outline";
+    readonly pending: "time-outline";
+    readonly online: "ellipse";
+    readonly offline: "ellipse-outline";
+};
+export type StatusIconKey = keyof typeof STATUS_ICONS;
+/**
+ * Get icon name for a status
+ */
+export declare function getStatusIcon(status: string): string;

package/lib/typescript/ui/utils/sessionHelpers.d.ts

@@ -0,0 +1,64 @@
+import type { ClientSession } from '@oxyhq/core';
+interface DeviceSession {
+    sessionId: string;
+    deviceId?: string;
+    deviceName?: string;
+    expiresAt?: string;
+    lastActive?: string;
+    user?: {
+        id?: string;
+        _id?: {
+            toString(): string;
+        };
+    };
+    userId?: string;
+    isCurrent?: boolean;
+}
+/**
+ * Service type for session helpers.
+ * Uses 'unknown' to work around TypeScript mixin composition type inference issues.
+ * The OxyServices class has these methods but TypeScript can't see them due to the mixin pattern.
+ * Methods are accessed dynamically, so callers must pass a properly typed instance.
+ */
+type OxyServicesAny = any;
+export interface FetchSessionsWithFallbackOptions {
+    fallbackDeviceId?: string;
+    fallbackUserId?: string;
+    logger?: (message: string, error?: unknown) => void;
+}
+export interface ValidateSessionBatchOptions {
+    useHeaderValidation?: boolean;
+    maxConcurrency?: number;
+}
+export interface SessionValidationResult {
+    sessionId: string;
+    valid: boolean;
+    user?: unknown;
+    raw?: unknown;
+    error?: unknown;
+}
+/**
+ * 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 declare const mapSessionsToClient: (sessions: DeviceSession[], fallbackDeviceId?: string, fallbackUserId?: string) => ClientSession[];
+/**
+ * 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 declare const fetchSessionsWithFallback: (oxyServices: OxyServicesAny, sessionId: string, { fallbackDeviceId, fallbackUserId, logger, }?: FetchSessionsWithFallbackOptions) => Promise<ClientSession[]>;
+/**
+ * Validate multiple sessions concurrently with configurable concurrency.
+ *
+ * @param oxyServices - Oxy service instance
+ * @param sessionIds - Session identifiers to validate
+ * @param options - Validation options
+ */
+export declare const validateSessionBatch: (oxyServices: OxyServicesAny, sessionIds: string[], { useHeaderValidation, maxConcurrency }?: ValidateSessionBatchOptions) => Promise<SessionValidationResult[]>;
+export {};

package/lib/typescript/ui/utils/storageHelpers.d.ts

@@ -0,0 +1,27 @@
+export interface StorageInterface {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+    clear: () => Promise<void>;
+}
+export interface SessionStorageKeys {
+    activeSessionId: string;
+    sessionIds: string;
+    language: string;
+}
+/**
+ * Detect whether the current runtime is React Native.
+ */
+export declare const isReactNative: () => boolean;
+/**
+ * Create a platform-appropriate storage implementation.
+ * Defaults to in-memory storage when no platform storage is available.
+ */
+export declare const createPlatformStorage: () => Promise<StorageInterface>;
+export declare const STORAGE_KEY_PREFIX = "oxy_session";
+/**
+ * Produce strongly typed storage key names for the supplied prefix.
+ *
+ * @param prefix - Storage key prefix
+ */
+export declare const getStorageKeys: (prefix?: string) => SessionStorageKeys;

package/lib/typescript/ui/utils/themeUtils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Theme Utility Functions
+ *
+ * Re-exports from shared module for cleaner internal imports.
+ * External consumers should use '@oxyhq/services/shared' directly.
+ *
+ * @module ui/utils/themeUtils
+ */
+export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from '@oxyhq/core';
+export type { ThemeValue } from '@oxyhq/core';

package/lib/typescript/ui/utils/userUtils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * User display name and date formatting utilities
+ */
+/**
+ * Formats a date string to a readable format (e.g., "Feb 21, 2025")
+ */
+export declare const formatDate: (dateString: string | undefined | null | Date) => string;
+/**
+ * Gets a display name from user data
+ */
+export declare const getDisplayName: (user: {
+    name?: {
+        full?: string;
+        first?: string;
+        last?: string;
+    };
+    username?: string;
+} | null | undefined) => string;
+/**
+ * Gets a short display name (first name or username)
+ */
+export declare const getShortDisplayName: (user: {
+    name?: {
+        first?: string;
+        full?: string;
+    };
+    username?: string;
+} | null | undefined) => string;

package/lib/typescript/utils/hookUtils.d.ts

@@ -0,0 +1,101 @@
+/**
+ * React hook utilities for common patterns and state management
+ */
+/**
+ * Hook for managing async operations with loading, error, and data states
+ */
+export declare function useAsync<T>(asyncFn: () => Promise<T>, deps?: React.DependencyList): {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    execute: () => Promise<T>;
+};
+/**
+ * Hook for managing async operations that execute on mount
+ */
+export declare function useAsyncEffect<T>(asyncFn: () => Promise<T>, deps?: React.DependencyList): {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for debounced values
+ */
+export declare function useDebounce<T>(value: T, delay: number): T;
+/**
+ * Hook for throttled values
+ */
+export declare function useThrottle<T>(value: T, delay: number): T;
+/**
+ * Hook for previous value
+ */
+export declare function usePrevious<T>(value: T): T | undefined;
+/**
+ * Hook for boolean state with toggle
+ */
+export declare function useToggle(initialValue?: boolean): {
+    value: boolean;
+    toggle: () => void;
+    setTrue: () => void;
+    setFalse: () => void;
+    setValue: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+};
+/**
+ * Hook for counter state
+ */
+export declare function useCounter(initialValue?: number): {
+    count: number;
+    increment: () => void;
+    decrement: () => void;
+    reset: () => void;
+    setValue: (value: number) => void;
+};
+/**
+ * Hook for local storage (platform-safe)
+ */
+export declare function useLocalStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * Hook for session storage (platform-safe)
+ */
+export declare function useSessionStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * Hook for window size (platform-safe)
+ */
+export declare function useWindowSize(): {
+    width: number;
+    height: number;
+};
+/**
+ * Hook for scroll position (platform-safe)
+ */
+export declare function useScrollPosition(): number;
+/**
+ * Hook for online/offline status (platform-safe)
+ */
+export declare function useOnlineStatus(): boolean;
+/**
+ * Hook for media queries (platform-safe)
+ */
+export declare function useMediaQuery(query: string): boolean;
+/**
+ * Hook for keyboard events (platform-safe)
+ */
+export declare function useKeyPress(targetKey: string): boolean;
+/**
+ * Hook for click outside detection (platform-safe)
+ */
+export declare function useClickOutside(ref: React.RefObject<HTMLElement>, handler: () => void): void;
+/**
+ * Hook for form validation
+ */
+export declare function useFormValidation<T extends Record<string, unknown>>(initialValues: T, validationSchema: (values: T) => Partial<Record<keyof T, string>>): {
+    values: T;
+    errors: Partial<Record<keyof T, string>>;
+    touched: Partial<Record<keyof T, boolean>>;
+    isValid: boolean;
+    setValue: (field: keyof T, value: T[keyof T]) => void;
+    setTouchedField: (field: keyof T) => void;
+    setValues: import("react").Dispatch<import("react").SetStateAction<T>>;
+    setErrors: import("react").Dispatch<import("react").SetStateAction<Partial<Record<keyof T, string>>>>;
+    setTouched: import("react").Dispatch<import("react").SetStateAction<Partial<Record<keyof T, boolean>>>>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/services",
-  "version": "6.9.13",
+  "version": "6.9.15",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -75,7 +75,6 @@
     "@oxyhq/core": "*",
     "@react-native-async-storage/async-storage": "2.2.0",
     "@react-native-community/netinfo": "^11.4.1",
-    "@tanstack/react-query": "^5.90.20",
     "@types/react": "*",
     "copyfiles": "^2.4.1",
     "expo-blur": "~55.0.8",
@@ -135,7 +134,8 @@
     "react-native-gesture-handler": "~2.30.0",
     "react-native-reanimated": ">=4.2.0",
     "react-native-safe-area-context": "~5.6.0",
-    "react-native-svg": ">=13.0.0"
+    "react-native-svg": ">=13.0.0",
+    "@tanstack/react-query": ">=5.0.0"
   },
   "peerDependenciesMeta": {
     "@expo/vector-icons": {

package/src/assets/icons/OxyServices.d.ts

@@ -0,0 +1,28 @@
+import type React from 'react';
+import type { ViewStyle } from 'react-native';
+interface OxyLogoProps {
+    width?: number;
+    height?: number;
+    style?: ViewStyle;
+    /**
+     * Primary fill color for the logo
+     * If not provided, the theme's primary color will be used
+     */
+    fillColor?: string;
+    /**
+     * Secondary fill color for the inner glow effect
+     * If not provided, a lighter shade of the fillColor will be used
+     */
+    secondaryFillColor?: string;
+    /**
+     * Theme to use for the logo colors
+     * @default 'light'
+     */
+    theme?: 'light' | 'dark';
+}
+/**
+ * SVG logo component for Oxy
+ * This component renders the Oxy logo as an SVG and uses theme colors by default
+ */
+export declare const OxyServicesLogo: React.FC<OxyLogoProps>;
+export default OxyServicesLogo;