@oxyhq/services 5.26.4 → 5.27.0

package/dist/web/types/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;

package/dist/web/types/assets/illustrations/HighFive.d.ts

@@ -0,0 +1,8 @@
+import type React from 'react';
+interface HighFiveProps {
+    width?: number;
+    height?: number;
+    color?: string;
+}
+declare const HighFive: React.FC<HighFiveProps>;
+export default HighFive;

package/dist/web/types/constants/version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Package version and metadata constants
+ * This file is auto-generated to avoid runtime dependency on package.json
+ */
+export declare const packageInfo: {
+    readonly name: "@oxyhq/services";
+    readonly version: "5.2.1";
+    readonly description: "Reusable OxyHQ module to handle authentication, user management, karma system and more 🚀";
+    readonly main: "lib/commonjs/node/index.js";
+    readonly module: "lib/module/node/index.js";
+    readonly types: "lib/typescript/node/index.d.ts";
+};
+export declare const name: "@oxyhq/services", version: "5.2.1", description: "Reusable OxyHQ module to handle authentication, user management, karma system and more 🚀";

package/dist/web/types/core/AuthManager.d.ts

@@ -0,0 +1,143 @@
+/**
+ * AuthManager - Centralized Authentication Manager
+ *
+ * Provides a unified authentication interface for all platforms.
+ * Handles token storage, session management, and auth state changes.
+ *
+ * @module core/AuthManager
+ */
+import type { OxyServices } from './OxyServices';
+import type { SessionLoginResponse, MinimalUserData } from '../models/session';
+/**
+ * Storage adapter interface for platform-agnostic storage.
+ */
+export interface StorageAdapter {
+    getItem: (key: string) => Promise<string | null> | string | null;
+    setItem: (key: string, value: string) => Promise<void> | void;
+    removeItem: (key: string) => Promise<void> | void;
+}
+/**
+ * Auth state change callback type.
+ */
+export type AuthStateChangeCallback = (user: MinimalUserData | null) => void;
+/**
+ * Auth method types.
+ */
+export type AuthMethod = 'fedcm' | 'popup' | 'redirect' | 'credentials' | 'identity';
+/**
+ * Auth manager configuration.
+ */
+export interface AuthManagerConfig {
+    /** Storage adapter (localStorage, AsyncStorage, etc.) */
+    storage?: StorageAdapter;
+    /** Whether to auto-refresh tokens */
+    autoRefresh?: boolean;
+    /** Token refresh interval in milliseconds (default: 5 minutes before expiry) */
+    refreshBuffer?: number;
+}
+/**
+ * AuthManager - Centralized authentication management.
+ *
+ * Provides a single point of control for:
+ * - Token storage and retrieval
+ * - Session management
+ * - Auth state change notifications
+ * - Multiple auth method support
+ *
+ * @example
+ * ```typescript
+ * const authManager = new AuthManager(oxyServices);
+ *
+ * // Listen for auth changes
+ * authManager.onAuthStateChange((user) => {
+ *   console.log('Auth state changed:', user);
+ * });
+ *
+ * // Handle successful auth
+ * await authManager.handleAuthSuccess(session);
+ *
+ * // Sign out
+ * await authManager.signOut();
+ * ```
+ */
+export declare class AuthManager {
+    private oxyServices;
+    private storage;
+    private listeners;
+    private currentUser;
+    private refreshTimer;
+    private config;
+    constructor(oxyServices: OxyServices, config?: AuthManagerConfig);
+    /**
+     * Get default storage based on environment.
+     */
+    private getDefaultStorage;
+    /**
+     * Subscribe to auth state changes.
+     *
+     * @param callback - Function called when auth state changes
+     * @returns Unsubscribe function
+     */
+    onAuthStateChange(callback: AuthStateChangeCallback): () => void;
+    /**
+     * Notify all listeners of auth state change.
+     */
+    private notifyListeners;
+    /**
+     * Handle successful authentication.
+     *
+     * @param session - Session response from auth
+     * @param method - Auth method used
+     */
+    handleAuthSuccess(session: SessionLoginResponse, method?: AuthMethod): Promise<void>;
+    /**
+     * Setup automatic token refresh.
+     */
+    private setupTokenRefresh;
+    /**
+     * Refresh the access token.
+     */
+    refreshToken(): Promise<boolean>;
+    /**
+     * Sign out and clear all auth data.
+     */
+    signOut(): Promise<void>;
+    /**
+     * Clear session data from storage.
+     */
+    private clearSession;
+    /**
+     * Get current user.
+     */
+    getCurrentUser(): MinimalUserData | null;
+    /**
+     * Check if user is authenticated.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get stored access token.
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Get the auth method used for current session.
+     */
+    getAuthMethod(): Promise<AuthMethod | null>;
+    /**
+     * Initialize auth state from storage.
+     *
+     * Call this on app startup to restore previous session.
+     */
+    initialize(): Promise<MinimalUserData | null>;
+    /**
+     * Destroy the auth manager and clean up resources.
+     */
+    destroy(): void;
+}
+/**
+ * Create an AuthManager instance.
+ *
+ * @param oxyServices - OxyServices instance
+ * @param config - Optional configuration
+ * @returns AuthManager instance
+ */
+export declare function createAuthManager(oxyServices: OxyServices, config?: AuthManagerConfig): AuthManager;

package/dist/web/types/core/CrossDomainAuth.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Cross-Domain Authentication Helper
+ *
+ * Provides a simplified API for cross-domain SSO authentication that automatically
+ * selects the best authentication method based on browser capabilities:
+ *
+ * 1. FedCM (if supported) - Modern, Google-style browser-native auth
+ * 2. Popup (fallback) - OAuth2-style popup window
+ * 3. Redirect (final fallback) - Traditional full-page redirect
+ *
+ * Usage:
+ * ```typescript
+ * import { CrossDomainAuth } from '@oxyhq/services';
+ *
+ * const auth = new CrossDomainAuth(oxyServices);
+ *
+ * // Automatic method selection
+ * const session = await auth.signIn();
+ *
+ * // Or use specific method
+ * const session = await auth.signInWithPopup();
+ * ```
+ */
+import type { OxyServices } from './OxyServices';
+import type { SessionLoginResponse } from '../models/session';
+export interface CrossDomainAuthOptions {
+    /**
+     * Preferred authentication method
+     * - 'auto': Automatically select best method (default)
+     * - 'fedcm': Use FedCM (browser-native)
+     * - 'popup': Use popup window
+     * - 'redirect': Use full-page redirect
+     */
+    method?: 'auto' | 'fedcm' | 'popup' | 'redirect';
+    /**
+     * Custom redirect URI (for redirect method)
+     */
+    redirectUri?: string;
+    /**
+     * Whether to open signup page instead of login
+     */
+    isSignup?: boolean;
+    /**
+     * Popup window dimensions (for popup method)
+     */
+    popupDimensions?: {
+        width?: number;
+        height?: number;
+    };
+    /**
+     * Callback when auth method is selected
+     */
+    onMethodSelected?: (method: 'fedcm' | 'popup' | 'redirect') => void;
+}
+export declare class CrossDomainAuth {
+    private oxyServices;
+    constructor(oxyServices: OxyServices);
+    /**
+     * Sign in with automatic method selection
+     *
+     * Tries methods in this order:
+     * 1. FedCM (if supported and not in private browsing)
+     * 2. Popup (if not blocked)
+     * 3. Redirect (always works)
+     *
+     * @param options - Authentication options
+     * @returns Session with user data and access token
+     */
+    signIn(options?: CrossDomainAuthOptions): Promise<SessionLoginResponse | null>;
+    /**
+     * Automatic sign-in with progressive enhancement
+     *
+     * @private
+     */
+    private autoSignIn;
+    /**
+     * Sign in using FedCM (Federated Credential Management)
+     *
+     * Best method - browser-native, no popups, Google-like experience
+     */
+    signInWithFedCM(options?: CrossDomainAuthOptions): Promise<SessionLoginResponse>;
+    /**
+     * Sign in using popup window
+     *
+     * Good method - preserves app state, no full page reload
+     */
+    signInWithPopup(options?: CrossDomainAuthOptions): Promise<SessionLoginResponse>;
+    /**
+     * Sign in using full-page redirect
+     *
+     * Fallback method - works everywhere but loses app state
+     */
+    signInWithRedirect(options?: CrossDomainAuthOptions): void;
+    /**
+     * Handle redirect callback
+     *
+     * Call this on app startup to check if we're returning from auth redirect
+     */
+    handleRedirectCallback(): SessionLoginResponse | null;
+    /**
+     * Silent sign-in (check for existing session)
+     *
+     * Tries to automatically sign in without user interaction.
+     * Works with both FedCM and popup/iframe methods.
+     *
+     * @returns Session if user is already signed in, null otherwise
+     */
+    silentSignIn(): Promise<SessionLoginResponse | null>;
+    /**
+     * Restore session from storage
+     *
+     * For redirect method - restores previously authenticated session from localStorage
+     */
+    restoreSession(): boolean;
+    /**
+     * Check if FedCM is supported in current browser
+     */
+    isFedCMSupported(): boolean;
+    /**
+     * Get recommended authentication method for current environment
+     *
+     * @returns Recommended method name and reason
+     */
+    getRecommendedMethod(): {
+        method: 'fedcm' | 'popup' | 'redirect';
+        reason: string;
+    };
+    /**
+     * Initialize cross-domain auth on app startup
+     *
+     * This handles:
+     * 1. Redirect callback (if returning from auth.oxy.so)
+     * 2. Session restoration (from localStorage)
+     * 3. Silent sign-in (check for existing SSO session)
+     *
+     * @returns Session if user is authenticated, null otherwise
+     */
+    initialize(): Promise<SessionLoginResponse | null>;
+}
+/**
+ * Helper function to create CrossDomainAuth instance
+ *
+ * @example
+ * ```typescript
+ * import { createCrossDomainAuth } from '@oxyhq/services';
+ *
+ * const oxyServices = new OxyServices({ baseURL: 'https://api.oxy.so' });
+ * const auth = createCrossDomainAuth(oxyServices);
+ *
+ * // On app startup
+ * const session = await auth.initialize();
+ * if (session) {
+ *   console.log('User is signed in:', session.user);
+ * }
+ *
+ * // Sign in button click
+ * const session = await auth.signIn();
+ * ```
+ */
+export declare function createCrossDomainAuth(oxyServices: OxyServices): CrossDomainAuth;

package/dist/web/types/core/HttpService.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Unified HTTP Service
+ *
+ * Consolidates HttpClient + RequestManager into a single efficient class.
+ * Uses native fetch instead of axios for smaller bundle size.
+ *
+ * Handles:
+ * - Authentication (token management, auto-refresh)
+ * - Caching (TTL-based)
+ * - Deduplication (concurrent requests)
+ * - Retry logic
+ * - Error handling
+ * - Request queuing
+ */
+import type { OxyConfig } from '../models/interfaces';
+export interface RequestOptions {
+    cache?: boolean;
+    cacheTTL?: number;
+    deduplicate?: boolean;
+    retry?: boolean;
+    maxRetries?: number;
+    timeout?: number;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+interface RequestConfig extends RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string;
+    data?: unknown;
+    params?: Record<string, unknown>;
+}
+/**
+ * Unified HTTP Service
+ *
+ * Consolidates HttpClient + RequestManager into a single efficient class.
+ * Uses native fetch instead of axios for smaller bundle size.
+ */
+export declare class HttpService {
+    private baseURL;
+    private tokenStore;
+    private cache;
+    private deduplicator;
+    private requestQueue;
+    private logger;
+    private config;
+    private requestMetrics;
+    constructor(config: OxyConfig);
+    /**
+     * Robust FormData detection that works in browser and Node.js environments
+     * Checks multiple conditions to handle different FormData implementations
+     */
+    private isFormData;
+    /**
+     * Main request method - handles everything in one place
+     */
+    request<T = unknown>(config: RequestConfig): Promise<T>;
+    /**
+     * Generate cache key efficiently
+     * Uses simple hash for large objects to avoid expensive JSON.stringify
+     */
+    private generateCacheKey;
+    /**
+     * Build full URL with query params
+     */
+    private buildURL;
+    /**
+     * Fetch CSRF token from server (with deduplication)
+     * Required for state-changing requests (POST, PUT, PATCH, DELETE)
+     */
+    private fetchCsrfToken;
+    /**
+     * Get auth header with automatic token refresh
+     */
+    private getAuthHeader;
+    /**
+     * Unwrap standardized API response format
+     */
+    private unwrapResponse;
+    /**
+     * Update request metrics
+     */
+    private updateMetrics;
+    /**
+     * GET request convenience method
+     */
+    get<T = unknown>(url: string, config?: Omit<RequestConfig, 'method' | 'url'>): Promise<{
+        data: T;
+    }>;
+    /**
+     * POST request convenience method
+     * Supports FormData uploads - Content-Type will be set automatically for FormData
+     * @param url - Request URL
+     * @param data - Request body (can be FormData for file uploads)
+     * @param config - Request configuration including optional headers
+     * @example
+     * ```typescript
+     * const formData = new FormData();
+     * formData.append('file', file);
+     * await api.post('/upload', formData, { headers: { 'X-Custom-Header': 'value' } });
+     * ```
+     */
+    post<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'method' | 'url' | 'data'>): Promise<{
+        data: T;
+    }>;
+    /**
+     * PUT request convenience method
+     * Supports FormData uploads - Content-Type will be set automatically for FormData
+     * @param url - Request URL
+     * @param data - Request body (can be FormData for file uploads)
+     * @param config - Request configuration including optional headers
+     * @example
+     * ```typescript
+     * const formData = new FormData();
+     * formData.append('file', file);
+     * await api.put('/upload', formData, { headers: { 'X-Custom-Header': 'value' } });
+     * ```
+     */
+    put<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'method' | 'url' | 'data'>): Promise<{
+        data: T;
+    }>;
+    /**
+     * PATCH request convenience method
+     * Supports FormData uploads - Content-Type will be set automatically for FormData
+     * @param url - Request URL
+     * @param data - Request body (can be FormData for file uploads)
+     * @param config - Request configuration including optional headers
+     * @example
+     * ```typescript
+     * const formData = new FormData();
+     * formData.append('file', file);
+     * await api.patch('/upload', formData, { headers: { 'X-Custom-Header': 'value' } });
+     * ```
+     */
+    patch<T = unknown>(url: string, data?: unknown, config?: Omit<RequestConfig, 'method' | 'url' | 'data'>): Promise<{
+        data: T;
+    }>;
+    delete<T = unknown>(url: string, config?: Omit<RequestConfig, 'method' | 'url'>): Promise<{
+        data: T;
+    }>;
+    setTokens(accessToken: string, refreshToken?: string): void;
+    clearTokens(): void;
+    getAccessToken(): string | null;
+    hasAccessToken(): boolean;
+    getBaseURL(): string;
+    clearCache(): void;
+    clearCacheEntry(key: string): void;
+    getCacheStats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    getMetrics(): {
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        cacheHits: number;
+        cacheMisses: number;
+        averageResponseTime: number;
+    };
+    static __resetTokensForTests(): void;
+}
+export {};

package/dist/web/types/core/OxyServices.base.d.ts

@@ -0,0 +1,126 @@
+import type { OxyConfig as OxyConfigBase } from '../models/interfaces';
+import { HttpService, type RequestOptions } from './HttpService';
+export interface OxyConfig extends OxyConfigBase {
+    cloudURL?: string;
+}
+/**
+ * Base class for OxyServices with core infrastructure
+ */
+export declare class OxyServicesBase {
+    httpService: HttpService;
+    cloudURL: string;
+    config: OxyConfig;
+    constructor(...args: any[]);
+    static __resetTokensForTests(): void;
+    /**
+     * Make a request with all performance optimizations
+     * This is the main method for all API calls - ensures authentication and performance features
+     */
+    makeRequest<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', url: string, data?: any, options?: RequestOptions): Promise<T>;
+    /**
+     * Get the configured Oxy API base URL
+     */
+    getBaseURL(): string;
+    /**
+     * Get the HTTP service instance
+     * Useful for advanced use cases where direct access to the HTTP service is needed
+     */
+    getClient(): HttpService;
+    /**
+     * Get performance metrics
+     */
+    getMetrics(): {
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        cacheHits: number;
+        cacheMisses: number;
+        averageResponseTime: number;
+    };
+    /**
+     * Clear request cache
+     */
+    clearCache(): void;
+    /**
+     * Clear specific cache entry
+     */
+    clearCacheEntry(key: string): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    /**
+     * Get the configured Oxy Cloud (file storage/CDN) URL
+     */
+    getCloudURL(): string;
+    /**
+     * Set authentication tokens
+     */
+    setTokens(accessToken: string, refreshToken?: string): void;
+    /**
+     * Clear stored authentication tokens
+     */
+    clearTokens(): void;
+    /**
+     * Get the current user ID from the access token
+     */
+    getCurrentUserId(): string | null;
+    /**
+     * Check if the client has a valid access token (public method)
+     */
+    hasValidToken(): boolean;
+    /**
+     * Get the raw access token (for constructing anchor URLs when needed)
+     */
+    getAccessToken(): string | null;
+    /**
+     * Wait for authentication to be ready
+     *
+     * Optimized for high-scale usage with immediate synchronous check and adaptive polling.
+     * Returns immediately if token is already available (0ms delay), otherwise uses
+     * adaptive polling that starts fast (50ms) and gradually increases to reduce CPU usage.
+     *
+     * @param timeoutMs Maximum time to wait in milliseconds (default: 5000ms)
+     * @returns Promise that resolves to true if authentication is ready, false if timeout
+     *
+     * @example
+     * ```typescript
+     * const isReady = await oxyServices.waitForAuth(3000);
+     * if (isReady) {
+     *   // Proceed with authenticated operations
+     * }
+     * ```
+     */
+    waitForAuth(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Execute a function with automatic authentication retry logic
+     * This handles the common case where API calls are made before authentication completes
+     */
+    withAuthRetry<T>(operation: () => Promise<T>, operationName: string, options?: {
+        maxRetries?: number;
+        retryDelay?: number;
+        authTimeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * Validate the current access token with the server
+     */
+    validate(): Promise<boolean>;
+    /**
+     * Centralized error handling
+     */
+    handleError(error: unknown): Error;
+    /**
+     * Health check endpoint
+     */
+    healthCheck(): Promise<{
+        status: string;
+        users?: number;
+        timestamp?: string;
+        [key: string]: any;
+    }>;
+}