@oxyhq/services 0.0.85 → 0.1.0

package/README.md

@@ -1,114 +1,304 @@
-# Oxy Services Module 🚀
+# OxyHQ Services Module
 
-The Oxy Services Module is a comprehensive package designed to provide reusable services and components for building front-end applications with Oxy. It includes hooks and components for session management, user handling, and more, making it easier to integrate Oxy-based functionalities into your React applications.
+A comprehensive module for interacting with the OxyHQ platform APIs. This module provides authentication, profile management, file handling, and other services.
 
-## Features ✨
-- **Session Management**: Easily manage user sessions with hooks like `useOxySession`.
-- **User Handling**: Fetch and display user information using functions like `getUserById`.
-- **Components**: Ready-to-use components such as `SignInButton`, `AccountSwitcherModal`, and `SessionOwnerButton`.
+## Features
 
-## Usage Instructions
+- 🔐 **Authentication**: Complete authentication flow with token management
+- 👤 **Profile Management**: User profile creation, retrieval, and updates
+- 📁 **File Handling**: Upload, download, and manage files
+- 💳 **Payments**: Process payments and manage subscriptions
+- 🔄 **Caching**: Efficient data caching for improved performance
+- 🔌 **Offline Support**: Graceful handling of offline scenarios
+- 📊 **Analytics**: User activity tracking and reporting
+- 🚀 **Performance Optimized**: Lazy loading, request deduplication, and more
 
-To use the OxyServicesModule, follow these steps:
+## Installation
 
-1. Install the package:
-   ```bash
-   npm install @oxyhq/services
-   ```
+```bash
+npm install @oxyhq/services
+```
 
-2. Import the necessary components and hooks in your project:
-   ```javascript
-   import { useOxySession, getUserById, SignInButton, AccountSwitcherModal, SessionOwnerButton } from '@oxyhq/services';
-   ```
+## Quick Start
 
-3. Use the components and hooks in your application. For example, to use the `SignInButton` component:
-   ```javascript
-   import React from 'react';
-   import { SignInButton } from '@oxyhq/services';
+```typescript
+import { initialize, authService, oxyClient } from '@oxyhq/services';
 
-   const App = () => {
-     return (
-       <div>
-         <SignInButton />
-       </div>
-     );
-   };
+// Initialize the module with custom configuration
+initialize({
+  apiUrl: 'https://api.your-instance.oxy.so',
+  enableLogging: true,
+  logLevel: 'debug'
+});
 
-   export default App;
-   ```
+// Use the authentication service
+const login = async () => {
+  try {
+    const result = await authService.login({
+      email: 'user@example.com',
+      password: 'password123'
+    });
+    console.log('Logged in successfully', result.user);
+  } catch (error) {
+    console.error('Login failed', error);
+  }
+};
 
-## Examples
+// Get a user profile
+const getProfile = async (userId) => {
+  try {
+    const profile = await oxyClient.getProfile(userId);
+    console.log('Profile retrieved', profile);
+  } catch (error) {
+    console.error('Failed to get profile', error);
+  }
+};
+```
 
-### Example 1: Using `useOxySession` Hook
+## Architecture
 
-The `useOxySession` hook fetches session data and provides error handling and status management.
+The OxyHQ Services module is built with a focus on performance, maintainability, and developer experience. Key architectural features include:
 
-```javascript
-import React from 'react';
-import { useOxySession } from '@oxyhq/services';
+### Service Layer
 
-const SessionComponent = () => {
-  const { session, status, error } = useOxySession();
+The module is organized into specialized services, each responsible for a specific domain:
 
-  if (status === 'loading') {
-    return <div>Loading...</div>;
-  }
+- **ApiService**: Core HTTP client with caching, retry logic, and token management
+- **AuthService**: Authentication and session management
+- **OxyClient**: High-level client for OxyHQ platform features
+- **ProfileService**: User profile management
+- **PaymentService**: Payment processing
+- **SubscriptionService**: Subscription management
+- **PrivacyService**: Privacy settings management
 
-  if (status === 'error') {
-    return <div>Error: {error}</div>;
-  }
+### Lazy Loading
 
-  return (
-    <div>
-      <h1>Welcome, {session.user.name}!</h1>
-      <p>Email: {session.user.email}</p>
-    </div>
-  );
-};
+Services are lazy-loaded to minimize initial bundle size and improve startup performance. The module exports getter functions that instantiate services only when needed:
 
-export default SessionComponent;
+```typescript
+import { getAuthService, getOxyClient } from '@oxyhq/services';
+
+// Service is instantiated only when called
+const auth = getAuthService();
 ```
 
-### Example 2: Using `getUserById` Function
+### Caching System
 
-The `getUserById` function fetches user data by ID and handles possible errors.
+The module includes a sophisticated caching system to minimize network requests:
 
-```javascript
-import React, { useEffect, useState } from 'react';
-import { getUserById } from '@oxyhq/services';
+- **In-memory Cache**: Fast access to recently used data
+- **Persistent Cache**: Data is stored for offline access
+- **Cache Invalidation**: Automatic and manual cache invalidation strategies
+- **TTL Support**: Time-based expiration for cached items
 
-const UserComponent = ({ userId }) => {
-  const [user, setUser] = useState(null);
-  const [error, setError] = useState(null);
+### Error Handling
 
-  useEffect(() => {
-    const fetchUser = async () => {
-      try {
-        const fetchedUser = await getUserById(userId);
-        setUser(fetchedUser);
-      } catch (err) {
-        setError(err.message);
-      }
-    };
+Comprehensive error handling with:
 
-    fetchUser();
-  }, [userId]);
+- **Error Normalization**: Consistent error format across services
+- **Retry Logic**: Automatic retry for transient failures
+- **Offline Detection**: Graceful handling of network unavailability
+- **Detailed Logging**: Contextual error information for debugging
 
-  if (error) {
-    return <div>Error: {error}</div>;
-  }
+### Logging
 
-  if (!user) {
-    return <div>Loading...</div>;
-  }
+A centralized logging system with:
+
+- **Log Levels**: DEBUG, INFO, WARN, ERROR, FATAL
+- **Context Support**: Logs include contextual information
+- **Remote Logging**: Optional sending of logs to a remote server
+- **Performance Metrics**: Timing of operations for performance analysis
+- **Sensitive Data Redaction**: Automatic redaction of sensitive information
+
+## API Reference
+
+### Core Services
+
+#### ApiService
+
+Low-level HTTP client with caching, retry logic, and token management.
+
+```typescript
+import { apiService } from '@oxyhq/services';
+
+// GET request with caching
+const data = await apiService.get('/endpoint', { 
+  useCache: true,
+  cacheTTL: 5 * 60 * 1000 // 5 minutes
+});
+
+// POST request
+const result = await apiService.post('/endpoint', { data: 'value' });
+
+// Cancel requests
+apiService.cancelAllRequests();
+```
+
+#### OxyClient
+
+High-level client for OxyHQ platform features.
+
+```typescript
+import { oxyClient } from '@oxyhq/services';
+
+// Get user profile
+const profile = await oxyClient.getProfile('user-id');
+
+// Get file data
+const files = await oxyClient.getFilesData(['file-id-1', 'file-id-2']);
+
+// Get recommendations
+const recommendations = await oxyClient.getRecommendations(10);
+```
+
+### Authentication
+
+```typescript
+import { authService } from '@oxyhq/services';
+
+// Login
+const loginResult = await authService.login({
+  email: 'user@example.com',
+  password: 'password123'
+});
+
+// Register
+const registerResult = await authService.register({
+  username: 'newuser',
+  email: 'newuser@example.com',
+  password: 'password123'
+});
+
+// Logout
+await authService.logout();
+
+// Check if user is authenticated
+const isAuthenticated = await authService.isAuthenticated();
+```
+
+### User Management
+
+```typescript
+import { userService } from '@oxyhq/services';
+
+// Get current user
+const currentUser = await userService.getCurrentUser();
+
+// Update user profile
+await userService.updateProfile({
+  name: {
+    first: 'John',
+    last: 'Doe'
+  },
+  avatar: 'avatar-url'
+});
+
+// Follow a user
+await userService.followUser('user-id-to-follow');
+
+// Unfollow a user
+await userService.unfollowUser('user-id-to-unfollow');
+```
+
+### File Management
+
+```typescript
+import { useFiles } from '@oxyhq/services';
+
+// In a React component
+function MyComponent() {
+  const { 
+    uploadFile, 
+    deleteFile, 
+    getFileUrl, 
+    isUploading 
+  } = useFiles();
+
+  const handleUpload = async (file) => {
+    const fileId = await uploadFile(file);
+    console.log('File uploaded with ID:', fileId);
+  };
 
   return (
     <div>
-      <h1>{user.name}</h1>
-      <p>Email: {user.email}</p>
+      <input type="file" onChange={(e) => handleUpload(e.target.files[0])} />
+      {isUploading && <p>Uploading...</p>}
     </div>
   );
+}
+```
+
+### Configuration
+
+The module can be configured using the `initialize` function:
+
+```typescript
+import { initialize } from '@oxyhq/services';
+
+initialize({
+  apiUrl: 'https://api.custom-instance.oxy.so',
+  cloudUrl: 'https://files.custom-instance.oxy.so',
+  enableLogging: true,
+  logLevel: 'debug',
+  enableOfflineMode: true
+});
+```
+
+## Advanced Usage
+
+### Custom Error Handling
+
+```typescript
+import { errorHandler } from '@oxyhq/services';
+
+try {
+  // Your code
+} catch (error) {
+  errorHandler.handleError(error, {
+    context: 'Custom operation',
+    fallbackMessage: 'Operation failed',
+    showToast: true,
+    onAuthError: () => {
+      // Handle authentication errors
+    }
+  });
+}
+```
+
+### Performance Logging
+
+```typescript
+import { logger } from '@oxyhq/services';
+
+const performOperation = async () => {
+  const startTime = Date.now();
+  
+  try {
+    // Perform operation
+    await someExpensiveOperation();
+  } finally {
+    // Log performance metrics
+    logger.logPerformance('someExpensiveOperation', startTime, 'MyComponent');
+  }
 };
+```
+
+### Scoped Logging
+
+```typescript
+import { logger } from '@oxyhq/services';
+
+// Create a logger scoped to a specific context
+const componentLogger = logger.createScopedLogger('MyComponent');
 
-export default UserComponent;
+componentLogger.info('Component initialized');
+componentLogger.error('Error in component', { details: 'error details' });
 ```
+
+## Contributing
+
+We welcome contributions to the OxyHQ Services module! Please see our [Contributing Guide](CONTRIBUTING.md) for more information.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/components/AuthBottomSheet/types.d.ts

@@ -0,0 +1,24 @@
+import { OxyProfile } from '../../types';
+export type AuthMode = 'signin' | 'signup' | 'session';
+export interface AuthBottomSheetProps {
+    /** Initial auth mode to display */
+    initialMode?: AuthMode;
+    /** Whether to show the logo in the header (default: true) */
+    showLogo?: boolean;
+    /** Callback when authentication is successful */
+    onSuccess?: () => void;
+}
+export interface UserSession {
+    id: string;
+    username: string;
+    name?: {
+        first?: string;
+        last?: string;
+    };
+    avatar?: string;
+}
+export interface Session {
+    id: string;
+    profile: OxyProfile;
+    lastActive: Date;
+}

package/dist/components/AuthBottomSheet/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/components/FileSelectorModal/types.d.ts

@@ -0,0 +1,35 @@
+export interface FileType {
+    _id: string;
+    filename: string;
+    contentType: string;
+    uploadDate: string;
+    length: number;
+    metadata?: {
+        userID: string;
+        originalname?: string;
+        sanitizedFilename?: string;
+        size?: number;
+        uploadDate?: string;
+    };
+}
+export interface FileSelectorModalProps {
+    isVisible: boolean;
+    onClose: () => void;
+    onSelect: (files: FileType[]) => void;
+    options?: {
+        fileTypeFilter?: string[];
+        maxFiles?: number;
+    };
+}
+export interface UseFilesOptions {
+    fileTypeFilter?: string[];
+    maxFiles?: number;
+    userId?: string;
+}
+export interface FileItemProps {
+    file: FileType;
+    isSelected: boolean;
+    onSelect: (file: FileType) => void;
+    onDelete: (fileId: string) => void;
+    baseUrl: string;
+}

package/dist/components/FileSelectorModal/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/components/SessionProvider.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+import type { User } from '../services/auth.service';
+import type { UserSession } from '../services/user.service';
+interface SessionState {
+    userId: string | null;
+    loading: boolean;
+    error: string | null;
+    user: User | null;
+    sessions: UserSession[];
+    lastActivity: number;
+}
+export interface SessionContextType {
+    state: SessionState;
+    loginUser: (username: string, password: string) => Promise<void>;
+    logoutUser: () => Promise<boolean>;
+    getCurrentUserId: () => string | null;
+    switchSession: (userId: string) => Promise<void>;
+    refreshTokenIfNeeded: () => Promise<boolean>;
+    sessions: UserSession[];
+    isAuthenticated: boolean;
+}
+export declare const SessionContext: import("react").Context<SessionContextType | null>;
+export declare function SessionProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export {};