@oxyhq/services 0.1.0 → 0.1.2

package/README.md

@@ -1,17 +1,13 @@
-# OxyHQ Services Module
+# Oxy Services Module
 
-A comprehensive module for interacting with the OxyHQ platform APIs. This module provides authentication, profile management, file handling, and other services.
+A comprehensive authentication, user management, and karma system module for Oxy applications.
 
 ## Features
 
-- 🔐 **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
+- Authentication system with JWT support
+- User profile management
+- Karma/reputation system
+- Wallet and transaction management
 
 ## Installation
 
@@ -19,286 +15,184 @@ A comprehensive module for interacting with the OxyHQ platform APIs. This module
 npm install @oxyhq/services
 ```
 
-## Quick Start
+## Usage
+
+### Backend Usage
 
 ```typescript
-import { initialize, authService, oxyClient } from '@oxyhq/services';
-
-// Initialize the module with custom configuration
-initialize({
-  apiUrl: 'https://api.your-instance.oxy.so',
-  enableLogging: true,
-  logLevel: 'debug'
-});
-
-// 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);
+import { OxyBackend } from '@oxyhq/services';
+
+// Initialize the backend services
+const oxyBackend = new OxyBackend('https://api.oxy.example.com');
+
+// Use authentication service
+const login = async (username, password) => {
+  const response = await oxyBackend.auth.login({ username, password });
+  if (response.success) {
+    // Handle successful login
+    console.log('Tokens:', response.data);
+  } else {
+    // Handle login failure
+    console.error('Login failed:', response.error);
   }
 };
 
-// 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);
+// Use user service
+const getUserProfile = async (userId) => {
+  const response = await oxyBackend.users.getUserById(userId);
+  if (response.success) {
+    console.log('User profile:', response.data);
   }
 };
-```
-
-## Architecture
-
-The OxyHQ Services module is built with a focus on performance, maintainability, and developer experience. Key architectural features include:
-
-### Service Layer
-
-The module is organized into specialized services, each responsible for a specific domain:
-
-- **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
-
-### Lazy Loading
-
-Services are lazy-loaded to minimize initial bundle size and improve startup performance. The module exports getter functions that instantiate services only when needed:
-
-```typescript
-import { getAuthService, getOxyClient } from '@oxyhq/services';
-
-// Service is instantiated only when called
-const auth = getAuthService();
-```
-
-### Caching System
-
-The module includes a sophisticated caching system to minimize network requests:
-
-- **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
-
-### Error Handling
-
-Comprehensive error handling with:
-
-- **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
-
-### Logging
 
-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']);
+// Use karma service
+const getUserKarma = async (userId) => {
+  const response = await oxyBackend.karma.getUserKarma(userId);
+  if (response.success) {
+    console.log('User karma:', response.data.karma);
+  }
+};
 
-// Get recommendations
-const recommendations = await oxyClient.getRecommendations(10);
+// Use wallet service
+const getWallet = async (userId) => {
+  const response = await oxyBackend.wallet.getWallet(userId);
+  if (response.success) {
+    console.log('Wallet balance:', response.data.balance);
+  }
+};
 ```
 
-### 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();
-```
+### Frontend Usage (React)
 
-### User Management
+#### Using OxyProvider (Recommended)
 
 ```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'
-});
+import React from 'react';
+import { OxyProvider, useAuth, useUser, useKarma, useWallet } from '@oxyhq/services';
 
-// Follow a user
-await userService.followUser('user-id-to-follow');
-
-// Unfollow a user
-await userService.unfollowUser('user-id-to-unfollow');
-```
-
-### File Management
+// Wrap your app with OxyProvider
+function App() {
+  return (
+    <OxyProvider apiUrl="https://api.oxy.example.com" storage="local">
+      <AuthenticatedApp />
+    </OxyProvider>
+  );
+}
 
-```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);
+// Then in your components, you don't need to specify apiUrl
+function AuthenticatedApp() {
+  // Use hooks without needing to specify apiUrl each time
+  const auth = useAuth();
+  const user = useUser();
+  const karma = useKarma();
+  const wallet = useWallet();
+  
+  const handleLogin = async () => {
+    const result = await auth.login({
+      username: 'user123',
+      password: 'secure-password'
+    });
+    
+    if (result.success) {
+      console.log('Logged in successfully');
+    }
   };
 
   return (
     <div>
-      <input type="file" onChange={(e) => handleUpload(e.target.files[0])} />
-      {isUploading && <p>Uploading...</p>}
+      {auth.isAuthenticated ? (
+        <div>
+          <h2>Welcome, {auth.user?.username}</h2>
+          <button onClick={auth.logout}>Logout</button>
+        </div>
+      ) : (
+        <button onClick={handleLogin}>Login</button>
+      )}
     </div>
   );
 }
-```
 
-### Configuration
+export default App;
+```
 
-The module can be configured using the `initialize` function:
+#### Direct Usage (Without Provider)
 
 ```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
-});
-```
+import React from 'react';
+import { useAuth, useUser, useKarma, useWallet } from '@oxyhq/services';
+
+function App() {
+  // Use authentication hook
+  const auth = useAuth({
+    apiUrl: 'https://api.oxy.example.com',
+    storage: 'local',
+    tokenRefreshInterval: 1000 * 60 * 15 // 15 minutes
+  });
 
-## Advanced Usage
+  // Use user management hook
+  const user = useUser({
+    apiUrl: 'https://api.oxy.example.com',
+    getToken: auth.getToken
+  });
 
-### Custom Error Handling
+  // Use karma hook
+  const karma = useKarma({
+    apiUrl: 'https://api.oxy.example.com',
+    getToken: auth.getToken
+  });
 
-```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
-    }
+  // Use wallet hook
+  const wallet = useWallet({
+    apiUrl: 'https://api.oxy.example.com',
+    getToken: auth.getToken
   });
-}
-```
 
-### Performance Logging
+  const handleLogin = async () => {
+    const result = await auth.login({
+      username: 'user123',
+      password: 'secure-password'
+    });
+    
+    if (result.success) {
+      console.log('Logged in successfully');
+    }
+  };
 
-```typescript
-import { logger } from '@oxyhq/services';
+  return (
+    <div>
+      {auth.isAuthenticated ? (
+        <div>
+          <h2>Welcome, {auth.user?.username}</h2>
+          <button onClick={auth.logout}>Logout</button>
+        </div>
+      ) : (
+        <button onClick={handleLogin}>Login</button>
+      )}
+    </div>
+  );
+}
 
-const performOperation = async () => {
-  const startTime = Date.now();
-  
-  try {
-    // Perform operation
-    await someExpensiveOperation();
-  } finally {
-    // Log performance metrics
-    logger.logPerformance('someExpensiveOperation', startTime, 'MyComponent');
-  }
-};
+export default App;
 ```
 
-### Scoped Logging
-
-```typescript
-import { logger } from '@oxyhq/services';
+## API Reference
 
-// Create a logger scoped to a specific context
-const componentLogger = logger.createScopedLogger('MyComponent');
+### Backend Services
 
-componentLogger.info('Component initialized');
-componentLogger.error('Error in component', { details: 'error details' });
-```
+- `OxyAuthBackend` - Authentication services
+- `OxyUsersBackend` - User management services
+- `OxyKarmaBackend` - Karma/reputation services
+- `OxyWalletBackend` - Wallet and transaction services
 
-## Contributing
+### Frontend Hooks & Context
 
-We welcome contributions to the OxyHQ Services module! Please see our [Contributing Guide](CONTRIBUTING.md) for more information.
+- `OxyProvider` - Context provider for API URL and authentication
+- `useOxyContext` - Hook to access the Oxy context
+- `useAuth()` - Authentication hooks
+- `useUser()` - User management hooks
+- `useKarma()` - Karma/reputation hooks
+- `useWallet()` - Wallet and transaction hooks
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT 

package/dist/backend/auth.d.ts

@@ -0,0 +1,37 @@
+import { ApiResponse, AuthTokens, UserCredentials, UserProfile, UserRegistration } from '../shared/types';
+export declare class OxyAuthBackend {
+    private apiClient;
+    constructor(apiUrl: string);
+    /**
+     * Authenticate a user with username/email and password
+     */
+    login(credentials: UserCredentials): Promise<ApiResponse<AuthTokens>>;
+    /**
+     * Register a new user
+     */
+    register(userData: UserRegistration): Promise<ApiResponse<AuthTokens>>;
+    /**
+     * Refresh the authentication token
+     */
+    refreshToken(refreshToken: string): Promise<ApiResponse<AuthTokens>>;
+    /**
+     * Logout the current user
+     */
+    logout(refreshToken: string): Promise<ApiResponse<void>>;
+    /**
+     * Validate if a token is valid
+     */
+    validateToken(token: string): Promise<ApiResponse<{
+        valid: boolean;
+    }>>;
+    /**
+     * Get the current user's profile
+     */
+    getCurrentUser(token: string): Promise<ApiResponse<UserProfile>>;
+    /**
+     * Check if a username is available
+     */
+    checkUsernameAvailability(username: string): Promise<ApiResponse<{
+        available: boolean;
+    }>>;
+}

package/dist/backend/index.d.ts

@@ -0,0 +1,12 @@
+import { OxyAuthBackend } from './auth';
+import { OxyUsersBackend } from './users';
+import { OxyKarmaBackend } from './karma';
+import { OxyWalletBackend } from './wallet';
+export { OxyAuthBackend, OxyUsersBackend, OxyKarmaBackend, OxyWalletBackend };
+export declare class OxyBackend {
+    auth: OxyAuthBackend;
+    users: OxyUsersBackend;
+    karma: OxyKarmaBackend;
+    wallet: OxyWalletBackend;
+    constructor(apiUrl: string);
+}

package/dist/backend/karma.d.ts

@@ -0,0 +1,45 @@
+import { ApiResponse, KarmaAction, KarmaHistory, KarmaRule } from '../shared/types';
+export declare class OxyKarmaBackend {
+    private apiClient;
+    constructor(apiUrl: string);
+    /**
+     * Get a user's karma total
+     */
+    getUserKarma(userId: string): Promise<ApiResponse<{
+        karma: number;
+    }>>;
+    /**
+     * Get a user's karma history (actions that affected karma)
+     */
+    getUserKarmaHistory(userId: string, limit?: number, offset?: number): Promise<ApiResponse<KarmaHistory>>;
+    /**
+     * Award karma points to a user for a specific action
+     */
+    awardKarma(karmaAction: KarmaAction): Promise<ApiResponse<{
+        success: boolean;
+        newTotal: number;
+    }>>;
+    /**
+     * Deduct karma points from a user for a specific action
+     */
+    deductKarma(karmaAction: KarmaAction): Promise<ApiResponse<{
+        success: boolean;
+        newTotal: number;
+    }>>;
+    /**
+     * Get the karma leaderboard (top users by karma)
+     */
+    getKarmaLeaderboard(limit?: number, offset?: number): Promise<ApiResponse<Array<{
+        userId: string;
+        username: string;
+        karma: number;
+    }>>>;
+    /**
+     * Get karma rules configuration
+     */
+    getKarmaRules(): Promise<ApiResponse<KarmaRule[]>>;
+    /**
+     * Admin only: Create or update a karma rule
+     */
+    createOrUpdateKarmaRule(rule: KarmaRule): Promise<ApiResponse<KarmaRule>>;
+}

package/dist/backend/users.d.ts

@@ -0,0 +1,39 @@
+import { ApiResponse, UserProfile, PrivacySettings } from '../shared/types';
+export declare class OxyUsersBackend {
+    private apiClient;
+    constructor(apiUrl: string);
+    /**
+     * Get a user by ID
+     */
+    getUserById(userId: string): Promise<ApiResponse<UserProfile>>;
+    /**
+     * Get a user by username
+     */
+    getUserByUsername(username: string): Promise<ApiResponse<UserProfile>>;
+    /**
+     * Update a user's profile
+     */
+    updateUserProfile(userId: string, profileData: Partial<UserProfile>): Promise<ApiResponse<UserProfile>>;
+    /**
+     * Update a user's privacy settings
+     */
+    updatePrivacySettings(userId: string, settings: Partial<PrivacySettings>): Promise<ApiResponse<PrivacySettings>>;
+    /**
+     * Get a user's privacy settings
+     */
+    getPrivacySettings(userId: string): Promise<ApiResponse<PrivacySettings>>;
+    /**
+     * Convert username to user ID
+     */
+    getUserIdFromUsername(username: string): Promise<ApiResponse<{
+        userId: string;
+    }>>;
+    /**
+     * Follow a user
+     */
+    followUser(userId: string, targetUserId: string): Promise<ApiResponse<void>>;
+    /**
+     * Unfollow a user
+     */
+    unfollowUser(userId: string, targetUserId: string): Promise<ApiResponse<void>>;
+}

package/dist/backend/wallet.d.ts

@@ -0,0 +1,29 @@
+import { ApiResponse, WalletInfo, TransactionInfo, TransferRequest, PurchaseRequest, WithdrawalRequest } from '../shared/types';
+export declare class OxyWalletBackend {
+    private apiClient;
+    constructor(apiUrl: string);
+    /**
+     * Get wallet information for a user
+     */
+    getWallet(userId: string): Promise<ApiResponse<WalletInfo>>;
+    /**
+     * Get transaction history for a user
+     */
+    getTransactionHistory(userId: string, limit?: number, offset?: number): Promise<ApiResponse<TransactionInfo[]>>;
+    /**
+     * Transfer funds to another user
+     */
+    transferFunds(transferRequest: TransferRequest): Promise<ApiResponse<TransactionInfo>>;
+    /**
+     * Process a purchase
+     */
+    processPurchase(purchaseRequest: PurchaseRequest): Promise<ApiResponse<TransactionInfo>>;
+    /**
+     * Request a withdrawal
+     */
+    requestWithdrawal(withdrawalRequest: WithdrawalRequest): Promise<ApiResponse<TransactionInfo>>;
+    /**
+     * Get a specific transaction
+     */
+    getTransaction(transactionId: string): Promise<ApiResponse<TransactionInfo>>;
+}