@oxyhq/core 1.0.0

package/src/mixins/mixinHelpers.ts

@@ -0,0 +1,69 @@
+/**
+ * Helper utilities for mixin classes
+ * Provides common patterns to reduce code duplication
+ */
+
+import type { OxyServicesBase } from '../OxyServices.base';
+
+/**
+ * Wraps an async method with standard error handling
+ * Reduces boilerplate in mixin methods
+ */
+export async function withErrorHandling<T>(
+  operation: () => Promise<T>,
+  handleError: (error: any) => Error
+): Promise<T> {
+  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<T>(
+  makeRequest: OxyServicesBase['makeRequest'],
+  handleError: OxyServicesBase['handleError'],
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  url: string | ((...args: any[]) => string),
+  options: {
+    cache?: boolean;
+    cacheTTL?: number;
+    retry?: boolean;
+    transformData?: (data: any) => any;
+    transformResponse?: (response: any) => T;
+  } = {}
+) {
+  return async (...args: any[]): Promise<T> => {
+    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<T>(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
+} as const;
+

package/src/models/interfaces.ts

@@ -0,0 +1,511 @@
+export interface OxyConfig {
+  baseURL: string;
+  cloudURL?: string;
+  authWebUrl?: string;
+  authRedirectUri?: string;
+  // Performance & caching options
+  enableCache?: boolean;
+  cacheTTL?: number; // Cache TTL in milliseconds (default: 5 minutes)
+  enableRequestDeduplication?: boolean;
+  enableRetry?: boolean;
+  maxRetries?: number;
+  retryDelay?: number;
+  requestTimeout?: number; // Default timeout in milliseconds (default: 5000)
+  // Rate limiting
+  maxConcurrentRequests?: number;
+  requestQueueSize?: number;
+  // Logging
+  enableLogging?: boolean;
+  logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
+  // Performance monitoring
+  onRequestStart?: (url: string, method: string) => void;
+  onRequestEnd?: (url: string, method: string, duration: number, success: boolean) => void;
+  onRequestError?: (url: string, method: string, error: Error) => void;
+}
+
+export interface User {
+  id: string;
+  publicKey: string;
+  username: string;
+  email?: string;
+  // Avatar file id (asset id)
+  avatar?: string;
+  // Privacy and security settings
+  privacySettings?: {
+    [key: string]: unknown;
+  };
+  name?: {
+    first?: string;
+    last?: string;
+    full?: string; // virtual, not stored in DB, returned by API
+    [key: string]: unknown;
+  };
+  bio?: string;
+  karma?: number;
+  location?: string;
+  website?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  links?: Array<{
+    title?: string;
+    description?: string;
+    image?: string;
+    link: string;
+  }>;
+  // Social counts
+  _count?: {
+    followers?: number;
+    following?: number;
+  };
+  accountExpiresAfterInactivityDays?: number | null; // Days of inactivity before account expires (null = never expire)
+  [key: string]: unknown;
+}
+
+export interface LoginResponse {
+  accessToken?: string;
+  refreshToken?: string;
+  token?: string; // For backwards compatibility
+  user: User;
+  message?: string;
+}
+
+export interface Notification {
+  id: string;
+  message: string;
+  // Add other notification fields as needed
+}
+
+export interface Wallet {
+  id: string;
+  balance: number;
+  // Add other wallet fields as needed
+}
+
+export interface Transaction {
+  id: string;
+  amount: number;
+  type: string;
+  timestamp: string;
+  // Add other transaction fields as needed
+}
+
+export interface BlockedUser {
+  _id?: string;
+  blockedId: string | {
+    _id: string;
+    username: string;
+    avatar?: string;
+  };
+  userId: string;
+  createdAt?: string;
+  blockedAt?: string;
+  username?: string;
+  avatar?: string;
+}
+
+export interface RestrictedUser {
+  _id?: string;
+  restrictedId: string | {
+    _id: string;
+    username: string;
+    avatar?: string;
+  };
+  userId: string;
+  createdAt?: string;
+  restrictedAt?: string;
+  username?: string;
+  avatar?: string;
+}
+
+export interface TransferFundsRequest {
+  fromUserId: string;
+  toUserId: string;
+  amount: number;
+}
+
+export interface PurchaseRequest {
+  userId: string;
+  itemId: string;
+  amount: number;
+}
+
+export interface WithdrawalRequest {
+  userId: string;
+  amount: number;
+  address: string;
+}
+
+export interface TransactionResponse {
+  success: boolean;
+  transaction: Transaction;
+}
+
+export interface PaginationInfo {
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+export interface SearchProfilesResponse {
+  data: User[];
+  pagination: PaginationInfo;
+}
+
+export interface KarmaRule {
+  id: string;
+  description: string;
+  // Add other karma rule fields as needed
+}
+
+export interface KarmaHistory {
+  id: string;
+  userId: string;
+  points: number;
+  // Add other karma history fields as needed
+}
+
+export interface KarmaLeaderboardEntry {
+  userId: string;
+  total: number;
+}
+
+export interface KarmaAwardRequest {
+  userId: string;
+  points: number;
+  reason?: string;
+}
+
+export interface ApiError {
+  message: string;
+  code: string;
+  status: number;
+  details?: Record<string, unknown>;
+}
+
+export interface PaymentMethod {
+  id: string;
+  type: string;
+  // Add other payment method fields as needed
+}
+
+export interface PaymentRequest {
+  userId: string;
+  planId: string;
+  paymentMethodId: string;
+}
+
+export interface PaymentResponse {
+  transactionId: string;
+  status: string;
+}
+
+export interface AnalyticsData {
+  userId: string;
+  // Add other analytics fields as needed
+}
+
+export interface FollowerDetails {
+  userId: string;
+  followers: number;
+  // Add other follower details as needed
+}
+
+export interface ContentViewer {
+  userId: string;
+  viewedAt: string;
+  // Add other content viewer fields as needed
+}
+
+/**
+ * File management interfaces
+ */
+export interface FileMetadata {
+  id: string;
+  filename: string;
+  contentType: string;
+  length: number;
+  chunkSize: number;
+  uploadDate: string;
+  metadata?: {
+    userId?: string;
+    description?: string;
+    title?: string;
+    tags?: string[];
+    [key: string]: unknown;
+  };
+  variants?: Array<{
+    type: string; // e.g. 'thumb', 'poster'
+    key: string; // storage key/path
+    width?: number;
+    height?: number;
+    readyAt?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
+export interface FileUploadResponse {
+  files: FileMetadata[];
+}
+
+export interface FileListResponse {
+  files: FileMetadata[];
+  total: number;
+  hasMore: boolean;
+}
+
+export interface FileUpdateRequest {
+  filename?: string;
+  metadata?: {
+    description?: string;
+    title?: string;
+    tags?: string[];
+    [key: string]: unknown;
+  };
+}
+
+export interface FileDeleteResponse {
+  success: boolean;
+  message: string;
+  fileId: string;
+}
+
+/**
+ * Central Asset Service interfaces
+ */
+
+/**
+ * File visibility levels
+ * - private: Only accessible by owner (default)
+ * - public: Accessible by anyone without authentication (e.g., avatars, public profile content)
+ * - unlisted: Accessible with direct link but not listed publicly
+ */
+export type FileVisibility = 'private' | 'public' | 'unlisted';
+
+export interface AssetLink {
+  app: string;
+  entityType: string;
+  entityId: string;
+  createdBy: string;
+  createdAt: string;
+}
+
+export type AssetMetadata = Record<string, string | number | boolean | null | undefined>;
+
+export interface AssetVariant {
+  type: string;
+  key: string;
+  width?: number;
+  height?: number;
+  readyAt?: string;
+  size?: number;
+  metadata?: AssetMetadata;
+}
+
+export interface Asset {
+  id: string;
+  sha256: string;
+  size: number;
+  mime: string;
+  ext: string;
+  originalName?: string;
+  ownerUserId: string;
+  status: 'active' | 'trash' | 'deleted';
+  visibility: FileVisibility;
+  usageCount: number;
+  createdAt: string;
+  updatedAt: string;
+  links: AssetLink[];
+  variants: AssetVariant[];
+  metadata?: AssetMetadata;
+}
+
+export interface AssetInitRequest {
+  sha256: string;
+  size: number;
+  mime: string;
+}
+
+export interface AssetInitResponse {
+  uploadUrl: string;
+  fileId: string;
+  sha256: string;
+}
+
+export interface AssetCompleteRequest {
+  fileId: string;
+  originalName: string;
+  size: number;
+  mime: string;
+  visibility?: FileVisibility;
+  metadata?: AssetMetadata;
+}
+
+export interface AssetLinkRequest {
+  app: string;
+  entityType: string;
+  entityId: string;
+  visibility?: FileVisibility;
+}
+
+export interface AssetUnlinkRequest {
+  app: string;
+  entityType: string;
+  entityId: string;
+}
+
+export interface AssetUrlResponse {
+  success: boolean;
+  url: string;
+  variant?: string;
+  expiresIn: number;
+}
+
+export interface AssetDeleteSummary {
+  fileId: string;
+  wouldDelete: boolean;
+  affectedApps: string[];
+  remainingLinks: number;
+  variants: string[];
+}
+
+export interface AssetUpdateVisibilityRequest {
+  visibility: FileVisibility;
+}
+
+export interface AssetUpdateVisibilityResponse {
+  success: boolean;
+  file: {
+    id: string;
+    visibility: FileVisibility;
+    updatedAt: string;
+  };
+}
+
+/**
+ * Account storage usage (server-side usage, not local AsyncStorage)
+ */
+export interface AccountStorageCategoryUsage {
+  bytes: number;
+  count: number;
+}
+
+export interface AccountStorageUsageResponse {
+  plan: 'basic' | 'pro' | 'business';
+  totalUsedBytes: number;
+  totalLimitBytes: number;
+  categories: {
+    documents: AccountStorageCategoryUsage;
+    mail: AccountStorageCategoryUsage;
+    photosVideos: AccountStorageCategoryUsage;
+    recordings: AccountStorageCategoryUsage;
+    family: AccountStorageCategoryUsage;
+    other: AccountStorageCategoryUsage;
+  };
+  updatedAt: string;
+}
+
+/**
+ * Security activity event types
+ */
+export type SecurityEventType = 
+  | 'sign_in'
+  | 'sign_out'
+  | 'email_changed'
+  | 'profile_updated'
+  | 'device_added'
+  | 'device_removed'
+  | 'account_recovery'
+  | 'security_settings_changed'
+  | 'private_key_exported'
+  | 'backup_created'
+  | 'suspicious_activity';
+
+/**
+ * Security event severity levels
+ */
+export type SecurityEventSeverity = 'low' | 'medium' | 'high' | 'critical';
+
+/**
+ * Security event severity mapping (single source of truth)
+ * Maps each event type to its default severity level
+ */
+export const SECURITY_EVENT_SEVERITY_MAP: Record<SecurityEventType, SecurityEventSeverity> = {
+  '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',
+};
+
+/**
+ * Security activity event
+ */
+export interface SecurityActivity {
+  id: string;
+  userId: string;
+  eventType: SecurityEventType;
+  eventDescription: string;
+  metadata?: Record<string, any>;
+  ipAddress?: string;
+  userAgent?: string;
+  deviceId?: string;
+  timestamp: string;
+  severity: SecurityEventSeverity;
+  createdAt: string;
+}
+
+/**
+ * Security activity response with pagination
+ */
+export interface SecurityActivityResponse {
+  data: SecurityActivity[];
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+export interface AssetUploadProgress {
+  fileId: string;
+  uploaded: number;
+  total: number;
+  percentage: number;
+  status: 'uploading' | 'processing' | 'complete' | 'error';
+  error?: string;
+}
+
+// Device Session interfaces
+export interface DeviceSession {
+  sessionId: string;
+  deviceId: string;
+  deviceName: string;
+  isActive: boolean;
+  lastActive: string;
+  expiresAt: string;
+  isCurrent: boolean;
+  user?: User;
+  createdAt?: string;
+}
+
+export interface DeviceSessionsResponse {
+  deviceId: string;
+  sessions: DeviceSession[];
+}
+
+export interface DeviceSessionLogoutResponse {
+  message: string;
+  deviceId: string;
+  sessionsTerminated: number;
+}
+
+export interface UpdateDeviceNameResponse {
+  message: string;
+  deviceName: string;
+}

package/src/models/session.ts

@@ -0,0 +1,30 @@
+export interface ClientSession {
+  sessionId: string;
+  deviceId: string;
+  expiresAt: string;
+  lastActive: string;
+  userId?: string;
+  isCurrent?: boolean;
+}
+
+export interface StorageKeys {
+  sessions: string; // Array of ClientSession objects
+  activeSessionId: string; // ID of currently active session
+}
+
+export interface MinimalUserData {
+  id: string;
+  username: string;
+  avatar?: string; // file id
+}
+
+export interface SessionLoginResponse {
+  sessionId: string;
+  deviceId: string;
+  expiresAt: string;
+  user: MinimalUserData;
+  /** JWT access token for API authentication */
+  accessToken?: string;
+  /** Refresh token for obtaining new access tokens */
+  refreshToken?: string;
+} 

package/src/shared/index.ts

@@ -0,0 +1,82 @@
+/**
+ * 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';
+export type { ThemeValue } 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';
+export type {
+  CircuitBreakerState,
+  CircuitBreakerConfig,
+} from './utils/networkUtils';
+
+// Debug utilities
+export {
+  isDev,
+  debugLog,
+  debugWarn,
+  debugError,
+  createDebugLogger,
+} from './utils/debugUtils';