@oxyhq/core 1.0.0

package/src/mixins/OxyServices.user.ts

@@ -0,0 +1,392 @@
+/**
+ * User Management Methods Mixin
+ */
+import type { User, Notification, SearchProfilesResponse, PaginationInfo } from '../models/interfaces';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { buildSearchParams, buildPaginationParams, type PaginationParams } from '../utils/apiUtils';
+
+export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+    /**
+     * Get profile by username
+     */
+    async getProfileByUsername(username: string): Promise<User> {
+      try {
+        return await this.makeRequest<User>('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: string, pagination?: PaginationParams): Promise<SearchProfilesResponse> {
+      try {
+        const params = { query, ...pagination };
+        const searchParams = buildSearchParams(params);
+        const paramsObj = Object.fromEntries(searchParams.entries());
+
+        const response = await this.makeRequest<SearchProfilesResponse | User[]>(
+          'GET',
+          '/api/profiles/search',
+          paramsObj,
+          {
+            cache: true,
+            cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+          }
+        );
+
+        // New API shape: { data: User[], pagination: {...} }
+        const isSearchProfilesResponse = (payload: unknown): payload is SearchProfilesResponse =>
+          typeof payload === 'object' &&
+          payload !== null &&
+          Array.isArray((payload as SearchProfilesResponse).data);
+
+        if (isSearchProfilesResponse(response)) {
+          const typedResponse = response;
+          const paginationInfo: 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: PaginationInfo = {
+            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(): Promise<Array<{
+      id: string;
+      username: string;
+      name?: { first?: string; last?: string; full?: string };
+      description?: string;
+      _count?: { followers: number; following: number };
+      [key: string]: any;
+    }>> {
+      return this.withAuthRetry(async () => {
+        return await this.makeRequest('GET', '/api/profiles/recommendations', undefined, { cache: true });
+      }, 'getProfileRecommendations');
+    }
+
+    /**
+     * Get user by ID
+     */
+    async getUserById(userId: string): Promise<User> {
+      try {
+        return await this.makeRequest<User>('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(): Promise<User> {
+      return this.withAuthRetry(async () => {
+        return await this.makeRequest<User>('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: Record<string, any>): Promise<User> {
+      try {
+        return await this.makeRequest<User>('PUT', '/api/users/me', updates, { cache: false });
+      } catch (error) {
+        const errorAny = error as any;
+        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?: string): Promise<any> {
+      try {
+        const id = userId || (await this.getCurrentUser()).id;
+        return await this.makeRequest<any>('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: Record<string, any>, userId?: string): Promise<any> {
+      try {
+        const id = userId || (await this.getCurrentUser()).id;
+        return await this.makeRequest<any>('PATCH', `/api/privacy/${id}/privacy`, settings, {
+          cache: false,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Request account verification
+     */
+    async requestAccountVerification(reason: string, evidence?: string): Promise<{ message: string; requestId: string }> {
+      try {
+        return await this.makeRequest<{ message: string; requestId: string }>('POST', '/api/users/verify/request', {
+          reason,
+          evidence,
+        }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Download account data export
+     */
+    async downloadAccountData(format: 'json' | 'csv' = 'json'): Promise<Blob> {
+      try {
+        // Use httpService for blob responses (it handles blob responses automatically)
+        const result = await this.getClient().request<Blob>({
+          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: string, confirmText: string): Promise<{ message: string }> {
+      try {
+        return await this.makeRequest<{ message: string }>('DELETE', '/api/users/me', {
+          password,
+          confirmText,
+        }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+
+    /**
+     * Follow a user
+     */
+    async followUser(userId: string): Promise<{ success: boolean; message: string }> {
+      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: string): Promise<{ success: boolean; message: string }> {
+      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: string): Promise<{ isFollowing: boolean }> {
+      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: string,
+      pagination?: PaginationParams
+    ): Promise<{ followers: User[]; total: number; hasMore: boolean }> {
+      try {
+        const params = buildPaginationParams(pagination || {});
+        const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('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: string,
+      pagination?: PaginationParams
+    ): Promise<{ following: User[]; total: number; hasMore: boolean }> {
+      try {
+        const params = buildPaginationParams(pagination || {});
+        const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('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(): Promise<Notification[]> {
+      return this.withAuthRetry(async () => {
+        return await this.makeRequest<Notification[]>('GET', '/api/notifications', undefined, {
+          cache: false, // Don't cache notifications - always get fresh data
+        });
+      }, 'getNotifications');
+    }
+
+    /**
+     * Get unread notification count
+     */
+    async getUnreadCount(): Promise<number> {
+      try {
+        const res = await this.makeRequest<{ count: number }>('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: Partial<Notification>): Promise<Notification> {
+      try {
+        return await this.makeRequest<Notification>('POST', '/api/notifications', data, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Mark notification as read
+     */
+    async markNotificationAsRead(notificationId: string): Promise<void> {
+      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(): Promise<void> {
+      try {
+        await this.makeRequest('PUT', '/api/notifications/read-all', undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Delete notification
+     */
+    async deleteNotification(notificationId: string): Promise<void> {
+      try {
+        await this.makeRequest('DELETE', `/api/notifications/${notificationId}`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}
+

package/src/mixins/OxyServices.utility.ts

@@ -0,0 +1,191 @@
+/**
+ * Utility Methods Mixin
+ * 
+ * Provides utility methods including link metadata fetching
+ * and Express.js authentication middleware
+ */
+import { jwtDecode } from 'jwt-decode';
+import type { ApiError, User } from '../models/interfaces';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { CACHE_TIMES } from './mixinHelpers';
+
+interface JwtPayload {
+  exp?: number;
+  userId?: string;
+  id?: string;
+  sessionId?: string;
+  [key: string]: any;
+}
+
+export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+    /**
+     * Fetch link metadata
+     */
+    async fetchLinkMetadata(url: string): Promise<{
+      url: string;
+      title: string;
+      description: string;
+      image?: string;
+    }> {
+      try {
+        return await this.makeRequest<{
+          url: string;
+          title: string;
+          description: string;
+          image?: string;
+        }>('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: {
+      debug?: boolean;
+      onError?: (error: ApiError) => any;
+      loadUser?: boolean;
+      session?: boolean;
+    } = {}) {
+      const { debug = false, onError, loadUser = false, session = false } = options;
+      
+      // Return a synchronous middleware function
+      return (req: any, res: any, next: any) => {
+        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: JwtPayload;
+          try {
+            decoded = jwtDecode<JwtPayload>(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 } as User;
+          
+          // 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) as any;
+          
+          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/src/mixins/index.ts

@@ -0,0 +1,91 @@
+/**
+ * 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';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type MixinFunction = (Base: any) => any;
+
+/**
+ * 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: MixinFunction[] = [
+    // 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 as unknown as ReturnType<MixinFunction>
+    );
+}
+
+// Export the pipeline for testing/debugging
+export { MIXIN_PIPELINE };
+