@oxyhq/core 1.0.0

package/dist/esm/mixins/OxyServices.user.js

@@ -0,0 +1,352 @@
+import { buildSearchParams, buildPaginationParams } from '../utils/apiUtils';
+export function OxyServicesUserMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Get profile by username
+         */
+        async getProfileByUsername(username) {
+            try {
+                return await this.makeRequest('GET', `/api/profiles/username/${username}`, undefined, {
+                    cache: true,
+                    cacheTTL: 5 * 60 * 1000, // 5 minutes cache for profiles
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Search user profiles
+         */
+        async searchProfiles(query, pagination) {
+            try {
+                const params = { query, ...pagination };
+                const searchParams = buildSearchParams(params);
+                const paramsObj = Object.fromEntries(searchParams.entries());
+                const response = await this.makeRequest('GET', '/api/profiles/search', paramsObj, {
+                    cache: true,
+                    cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                });
+                // New API shape: { data: User[], pagination: {...} }
+                const isSearchProfilesResponse = (payload) => typeof payload === 'object' &&
+                    payload !== null &&
+                    Array.isArray(payload.data);
+                if (isSearchProfilesResponse(response)) {
+                    const typedResponse = response;
+                    const paginationInfo = typedResponse.pagination ?? {
+                        total: typedResponse.data.length,
+                        limit: pagination?.limit ?? typedResponse.data.length,
+                        offset: pagination?.offset ?? 0,
+                        hasMore: typedResponse.data.length === (pagination?.limit ?? typedResponse.data.length) &&
+                            (pagination?.limit ?? typedResponse.data.length) > 0,
+                    };
+                    return {
+                        data: typedResponse.data,
+                        pagination: paginationInfo,
+                    };
+                }
+                // Legacy API shape: returns raw User[]
+                if (Array.isArray(response)) {
+                    const fallbackLimit = pagination?.limit ?? response.length;
+                    const fallbackPagination = {
+                        total: response.length,
+                        limit: fallbackLimit,
+                        offset: pagination?.offset ?? 0,
+                        hasMore: fallbackLimit > 0 && response.length === fallbackLimit,
+                    };
+                    return { data: response, pagination: fallbackPagination };
+                }
+                // If response is unexpected, throw an error
+                throw new Error('Unexpected search response format');
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get profile recommendations
+         */
+        async getProfileRecommendations() {
+            return this.withAuthRetry(async () => {
+                return await this.makeRequest('GET', '/api/profiles/recommendations', undefined, { cache: true });
+            }, 'getProfileRecommendations');
+        }
+        /**
+         * Get user by ID
+         */
+        async getUserById(userId) {
+            try {
+                return await this.makeRequest('GET', `/api/users/${userId}`, undefined, {
+                    cache: true,
+                    cacheTTL: 5 * 60 * 1000, // 5 minutes cache
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get current user
+         */
+        async getCurrentUser() {
+            return this.withAuthRetry(async () => {
+                return await this.makeRequest('GET', '/api/users/me', undefined, {
+                    cache: true,
+                    cacheTTL: 1 * 60 * 1000, // 1 minute cache for current user
+                });
+            }, 'getCurrentUser');
+        }
+        /**
+         * Update user profile
+         * TanStack Query handles offline queuing automatically
+         */
+        async updateProfile(updates) {
+            try {
+                return await this.makeRequest('PUT', '/api/users/me', updates, { cache: false });
+            }
+            catch (error) {
+                const errorAny = error;
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const status = errorAny?.status || errorAny?.response?.status;
+                // Check if it's an authentication error (401)
+                const isAuthError = status === 401 ||
+                    errorMessage.includes('Authentication required') ||
+                    errorMessage.includes('Invalid or missing authorization header');
+                // If authentication error and we don't have a token, this might be an offline session
+                // The caller should handle syncing the session before retrying
+                if (isAuthError && !this.hasValidToken()) {
+                    // Re-throw with a specific message so the caller knows to sync
+                    throw new Error('AUTH_REQUIRED_OFFLINE_SESSION: Session needs to be synced to get a token');
+                }
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get privacy settings for a user
+         * @param userId - The user ID (defaults to current user)
+         */
+        async getPrivacySettings(userId) {
+            try {
+                const id = userId || (await this.getCurrentUser()).id;
+                return await this.makeRequest('GET', `/api/privacy/${id}/privacy`, undefined, {
+                    cache: true,
+                    cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Update privacy settings
+         * @param settings - Partial privacy settings object
+         * @param userId - The user ID (defaults to current user)
+         */
+        async updatePrivacySettings(settings, userId) {
+            try {
+                const id = userId || (await this.getCurrentUser()).id;
+                return await this.makeRequest('PATCH', `/api/privacy/${id}/privacy`, settings, {
+                    cache: false,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Request account verification
+         */
+        async requestAccountVerification(reason, evidence) {
+            try {
+                return await this.makeRequest('POST', '/api/users/verify/request', {
+                    reason,
+                    evidence,
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Download account data export
+         */
+        async downloadAccountData(format = 'json') {
+            try {
+                // Use httpService for blob responses (it handles blob responses automatically)
+                const result = await this.getClient().request({
+                    method: 'GET',
+                    url: `/api/users/me/data`,
+                    params: { format },
+                    cache: false,
+                });
+                return result;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Delete account permanently
+         * @param password - User password for confirmation
+         * @param confirmText - Confirmation text (usually username)
+         */
+        async deleteAccount(password, confirmText) {
+            try {
+                return await this.makeRequest('DELETE', '/api/users/me', {
+                    password,
+                    confirmText,
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Follow a user
+         */
+        async followUser(userId) {
+            try {
+                return await this.makeRequest('POST', `/api/users/${userId}/follow`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Unfollow a user
+         */
+        async unfollowUser(userId) {
+            try {
+                return await this.makeRequest('DELETE', `/api/users/${userId}/follow`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get follow status
+         */
+        async getFollowStatus(userId) {
+            try {
+                return await this.makeRequest('GET', `/api/users/${userId}/follow-status`, undefined, {
+                    cache: true,
+                    cacheTTL: 1 * 60 * 1000, // 1 minute cache
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get user followers
+         */
+        async getUserFollowers(userId, pagination) {
+            try {
+                const params = buildPaginationParams(pagination || {});
+                const response = await this.makeRequest('GET', `/api/users/${userId}/followers`, params, {
+                    cache: true,
+                    cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                });
+                return {
+                    followers: response.data || [],
+                    total: response.pagination.total,
+                    hasMore: response.pagination.hasMore,
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get user following
+         */
+        async getUserFollowing(userId, pagination) {
+            try {
+                const params = buildPaginationParams(pagination || {});
+                const response = await this.makeRequest('GET', `/api/users/${userId}/following`, params, {
+                    cache: true,
+                    cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                });
+                return {
+                    following: response.data || [],
+                    total: response.pagination.total,
+                    hasMore: response.pagination.hasMore,
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get notifications
+         */
+        async getNotifications() {
+            return this.withAuthRetry(async () => {
+                return await this.makeRequest('GET', '/api/notifications', undefined, {
+                    cache: false, // Don't cache notifications - always get fresh data
+                });
+            }, 'getNotifications');
+        }
+        /**
+         * Get unread notification count
+         */
+        async getUnreadCount() {
+            try {
+                const res = await this.makeRequest('GET', '/api/notifications/unread-count', undefined, {
+                    cache: false, // Don't cache unread count - always get fresh data
+                });
+                return res.count;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Create notification
+         */
+        async createNotification(data) {
+            try {
+                return await this.makeRequest('POST', '/api/notifications', data, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Mark notification as read
+         */
+        async markNotificationAsRead(notificationId) {
+            try {
+                await this.makeRequest('PUT', `/api/notifications/${notificationId}/read`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Mark all notifications as read
+         */
+        async markAllNotificationsAsRead() {
+            try {
+                await this.makeRequest('PUT', '/api/notifications/read-all', undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Delete notification
+         */
+        async deleteNotification(notificationId) {
+            try {
+                await this.makeRequest('DELETE', `/api/notifications/${notificationId}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.utility.js

@@ -0,0 +1,153 @@
+/**
+ * Utility Methods Mixin
+ *
+ * Provides utility methods including link metadata fetching
+ * and Express.js authentication middleware
+ */
+import { jwtDecode } from 'jwt-decode';
+import { CACHE_TIMES } from './mixinHelpers';
+export function OxyServicesUtilityMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Fetch link metadata
+         */
+        async fetchLinkMetadata(url) {
+            try {
+                return await this.makeRequest('GET', '/api/link-metadata', { url }, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.EXTRA_LONG,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Simple Express.js authentication middleware
+         *
+         * Built-in authentication middleware that validates JWT tokens and adds user data to requests.
+         *
+         * @example
+         * ```typescript
+         * // Basic usage - just add it to your routes
+         * app.use('/api/protected', oxyServices.auth());
+         *
+         * // With debug logging
+         * app.use('/api/protected', oxyServices.auth({ debug: true }));
+         *
+         * // With custom error handling
+         * app.use('/api/protected', oxyServices.auth({
+         *   onError: (error) => console.error('Auth failed:', error)
+         * }));
+         *
+         * // Load full user data
+         * app.use('/api/protected', oxyServices.auth({ loadUser: true }));
+         * ```
+         *
+         * @param options Optional configuration
+         * @param options.debug Enable debug logging (default: false)
+         * @param options.onError Custom error handler
+         * @param options.loadUser Load full user data (default: false for performance)
+         * @param options.session Use session-based validation (default: false)
+         * @returns Express middleware function
+         */
+        auth(options = {}) {
+            const { debug = false, onError, loadUser = false, session = false } = options;
+            // Return a synchronous middleware function
+            return (req, res, next) => {
+                try {
+                    // Extract token from Authorization header
+                    const authHeader = req.headers['authorization'];
+                    const token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
+                    if (debug) {
+                        console.log(`🔐 Auth: Processing ${req.method} ${req.path}`);
+                        console.log(`🔐 Auth: Token present: ${!!token}`);
+                    }
+                    if (!token) {
+                        const error = {
+                            message: 'Access token required',
+                            code: 'MISSING_TOKEN',
+                            status: 401
+                        };
+                        if (debug)
+                            console.log(`❌ Auth: Missing token`);
+                        if (onError)
+                            return onError(error);
+                        return res.status(401).json(error);
+                    }
+                    // Decode and validate token
+                    let decoded;
+                    try {
+                        decoded = jwtDecode(token);
+                        if (debug) {
+                            console.log(`🔐 Auth: Token decoded, User ID: ${decoded.userId || decoded.id}`);
+                        }
+                    }
+                    catch (decodeError) {
+                        const error = {
+                            message: 'Invalid token format',
+                            code: 'INVALID_TOKEN_FORMAT',
+                            status: 403
+                        };
+                        if (debug)
+                            console.log(`❌ Auth: Token decode failed`);
+                        if (onError)
+                            return onError(error);
+                        return res.status(403).json(error);
+                    }
+                    const userId = decoded.userId || decoded.id;
+                    if (!userId) {
+                        const error = {
+                            message: 'Token missing user ID',
+                            code: 'INVALID_TOKEN_PAYLOAD',
+                            status: 403
+                        };
+                        if (debug)
+                            console.log(`❌ Auth: Token missing user ID`);
+                        if (onError)
+                            return onError(error);
+                        return res.status(403).json(error);
+                    }
+                    // Check token expiration
+                    if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
+                        const error = {
+                            message: 'Token expired',
+                            code: 'TOKEN_EXPIRED',
+                            status: 403
+                        };
+                        if (debug)
+                            console.log(`❌ Auth: Token expired`);
+                        if (onError)
+                            return onError(error);
+                        return res.status(403).json(error);
+                    }
+                    // For now, skip session validation to keep it simple
+                    // Session validation can be added later if needed
+                    // Set request properties immediately
+                    req.userId = userId;
+                    req.accessToken = token;
+                    req.user = { id: userId };
+                    // Automatically authenticate the OxyServices instance so all subsequent API calls are authenticated
+                    this.setTokens(token);
+                    if (debug) {
+                        console.log(`✅ Auth: Authentication successful for user ${userId}`);
+                    }
+                    next();
+                }
+                catch (error) {
+                    const apiError = this.handleError(error);
+                    if (debug) {
+                        // Debug logging - using console.log is acceptable here for development
+                        console.log(`❌ Auth: Unexpected error:`, apiError);
+                    }
+                    if (onError)
+                        return onError(apiError);
+                    return res.status((apiError && apiError.status) || 500).json(apiError);
+                }
+            };
+        }
+    };
+}

package/dist/esm/mixins/index.js

@@ -0,0 +1,76 @@
+/**
+ * Centralized mixin exports and composition helper
+ *
+ * This module provides a clean way to compose all mixins
+ * and ensures consistent ordering for better maintainability
+ */
+import { OxyServicesBase } from '../OxyServices.base';
+import { OxyServicesAuthMixin } from './OxyServices.auth';
+import { OxyServicesFedCMMixin } from './OxyServices.fedcm';
+import { OxyServicesPopupAuthMixin } from './OxyServices.popup';
+import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect';
+import { OxyServicesUserMixin } from './OxyServices.user';
+import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
+import { OxyServicesLanguageMixin } from './OxyServices.language';
+import { OxyServicesPaymentMixin } from './OxyServices.payment';
+import { OxyServicesKarmaMixin } from './OxyServices.karma';
+import { OxyServicesAssetsMixin } from './OxyServices.assets';
+import { OxyServicesDeveloperMixin } from './OxyServices.developer';
+import { OxyServicesLocationMixin } from './OxyServices.location';
+import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
+import { OxyServicesDevicesMixin } from './OxyServices.devices';
+import { OxyServicesSecurityMixin } from './OxyServices.security';
+import { OxyServicesUtilityMixin } from './OxyServices.utility';
+import { OxyServicesFeaturesMixin } from './OxyServices.features';
+/**
+ * Mixin pipeline - applied in order from first to last.
+ *
+ * Order matters for dependencies:
+ * 1. Base auth mixin first (required by all others)
+ * 2. Cross-domain auth mixins (FedCM, Popup, Redirect)
+ * 3. User mixin (requires auth)
+ * 4. Feature mixins (can depend on user)
+ * 5. Utility mixin last (augments all)
+ *
+ * To add a new mixin: insert it at the appropriate position in this array.
+ */
+const MIXIN_PIPELINE = [
+    // Base authentication
+    OxyServicesAuthMixin,
+    // Cross-domain authentication (web-only)
+    // - FedCM: Modern browser-native identity federation (Google-style)
+    // - Popup: OAuth2-style popup authentication
+    // - Redirect: Traditional redirect-based authentication
+    OxyServicesFedCMMixin,
+    OxyServicesPopupAuthMixin,
+    OxyServicesRedirectAuthMixin,
+    // User management (requires auth)
+    OxyServicesUserMixin,
+    OxyServicesPrivacyMixin,
+    // Feature mixins
+    OxyServicesLanguageMixin,
+    OxyServicesPaymentMixin,
+    OxyServicesKarmaMixin,
+    OxyServicesAssetsMixin,
+    OxyServicesDeveloperMixin,
+    OxyServicesLocationMixin,
+    OxyServicesAnalyticsMixin,
+    OxyServicesDevicesMixin,
+    OxyServicesSecurityMixin,
+    OxyServicesFeaturesMixin,
+    // Utility (last, can use all above)
+    OxyServicesUtilityMixin,
+];
+/**
+ * Composes all OxyServices mixins using a pipeline pattern.
+ *
+ * This is equivalent to the nested calls but more readable and maintainable.
+ * Adding a new mixin: just add it to MIXIN_PIPELINE at the appropriate position.
+ *
+ * @returns The fully composed OxyServices class with all mixins applied
+ */
+export function composeOxyServices() {
+    return MIXIN_PIPELINE.reduce((Base, mixin) => mixin(Base), OxyServicesBase);
+}
+// Export the pipeline for testing/debugging
+export { MIXIN_PIPELINE };

package/dist/esm/mixins/mixinHelpers.js

@@ -0,0 +1,48 @@
+/**
+ * Helper utilities for mixin classes
+ * Provides common patterns to reduce code duplication
+ */
+/**
+ * Wraps an async method with standard error handling
+ * Reduces boilerplate in mixin methods
+ */
+export async function withErrorHandling(operation, handleError) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw handleError(error);
+    }
+}
+/**
+ * Creates a standard API request method with error handling
+ * Reduces duplication across mixin methods
+ */
+export function createApiMethod(makeRequest, handleError, method, url, options = {}) {
+    return async (...args) => {
+        const urlString = typeof url === 'function' ? url(...args) : url;
+        const requestData = options.transformData ? options.transformData(args) : args[0];
+        const requestOptions = {
+            cache: options.cache ?? true,
+            cacheTTL: options.cacheTTL,
+            retry: options.retry ?? true,
+        };
+        try {
+            const response = await makeRequest(method, urlString, requestData, requestOptions);
+            return options.transformResponse ? options.transformResponse(response) : response;
+        }
+        catch (error) {
+            throw handleError(error);
+        }
+    };
+}
+/**
+ * Cache time constants (in milliseconds)
+ */
+export const CACHE_TIMES = {
+    SHORT: 1 * 60 * 1000, // 1 minute
+    MEDIUM: 2 * 60 * 1000, // 2 minutes
+    LONG: 5 * 60 * 1000, // 5 minutes
+    VERY_LONG: 10 * 60 * 1000, // 10 minutes
+    EXTRA_LONG: 30 * 60 * 1000, // 30 minutes
+};

package/dist/esm/models/interfaces.js

@@ -0,0 +1,17 @@
+/**
+ * Security event severity mapping (single source of truth)
+ * Maps each event type to its default severity level
+ */
+export const SECURITY_EVENT_SEVERITY_MAP = {
+    'sign_in': 'low',
+    'sign_out': 'low',
+    'profile_updated': 'low',
+    'email_changed': 'medium',
+    'device_added': 'medium',
+    'device_removed': 'medium',
+    'security_settings_changed': 'medium',
+    'account_recovery': 'high',
+    'private_key_exported': 'high',
+    'backup_created': 'high',
+    'suspicious_activity': 'critical',
+};

package/dist/esm/models/session.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/shared/index.js

@@ -0,0 +1,31 @@
+/**
+ * OxyServices Shared Module
+ *
+ * Platform-agnostic utilities and helpers that work everywhere:
+ * - Browser (Web, Expo Web)
+ * - React Native (iOS, Android)
+ * - Node.js (Backend)
+ *
+ * This module contains NO React Native or browser-specific dependencies.
+ *
+ * @module shared
+ *
+ * @example
+ * ```ts
+ * import { darkenColor, normalizeTheme, withRetry } from '@oxyhq/services/shared';
+ *
+ * const darkBlue = darkenColor('#0066FF', 0.3);
+ * const theme = normalizeTheme(userPreference);
+ * const data = await withRetry(() => fetchData(), { maxRetries: 3 });
+ * ```
+ */
+// Color utilities
+export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from './utils/colorUtils';
+// Theme utilities
+export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from './utils/themeUtils';
+// Error utilities
+export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './utils/errorUtils';
+// Network utilities
+export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './utils/networkUtils';
+// Debug utilities
+export { isDev, debugLog, debugWarn, debugError, createDebugLogger, } from './utils/debugUtils';