@oxyhq/services 0.1.13 → 0.1.16

package/README.md

@@ -1,350 +1,181 @@
 # Oxy Services Module
 
-A comprehensive authentication, user management, and karma system module for Oxy applications.
+A unified client library for the Oxy API (authentication, user management, notifications, payments, analytics, wallet, and karma).
 
-## Features
+## Table of Contents
 
-- Authentication system with JWT support
-- User profile management
-- Karma/reputation system
-- Wallet and transaction management
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+  - [OxyConfig](#oxyconfig)
+  - [Class: OxyServices](#class-oxyservices)
+- [Examples](#examples)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Overview
+
+The `@oxyhq/services` package provides a simple, promise-based client to interact with the Oxy API. It wraps HTTP calls to endpoints for:
+
+- Authentication (signup, login, token refresh, logout, validation)
+- User & profile operations (fetch, update, follow/unfollow)
+- Real‑time notifications (list, create, mark read, delete)
+- Payments & wallet (process payment, validate method, transfer funds, purchase, withdrawal)
+- Analytics & content insights (time‑series data, viewers, follower stats)
+- Karma system (leaderboard, rules, award/deduct points)
+
+This library is framework-agnostic and works in Node.js, browser, and React Native environments.
 
 ## Installation
 
 ```bash
-npm install @oxyhq/services
+npm install @oxyhq/services axios jwt-decode
 ```
 
-## Usage
+> **Peer Dependencies**: React, React Native, and optional storage libraries if used in mobile apps.
 
-### Backend Usage
+## Usage
 
 ```typescript
-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);
-  }
-};
-
-// Use user service
-const getUserProfile = async (userId) => {
-  const response = await oxyBackend.users.getUserById(userId);
-  if (response.success) {
-    console.log('User profile:', response.data);
-  }
-};
-
-// Use karma service
-const getUserKarma = async (userId) => {
-  const response = await oxyBackend.karma.getUserKarma(userId);
-  if (response.success) {
-    console.log('User karma:', response.data.karma);
-  }
-};
-
-// Use wallet service
-const getWallet = async (userId) => {
-  const response = await oxyBackend.wallet.getWallet(userId);
-  if (response.success) {
-    console.log('Wallet balance:', response.data.balance);
-  }
-};
+import OxyServices, { OxyConfig } from '@oxyhq/services';
+
+const config: OxyConfig = { baseURL: 'https://api.mention.earth' };
+const client = new OxyServices(config);
+
+// Authenticate and start using API
+(async () => {
+  const login = await client.login('alice', 'Secret123!');
+  console.log('Logged in user:', login.user);
+  const profile = await client.getProfileByUsername('bob');
+  console.log('Bob’s profile:', profile);
+})();
 ```
 
-### Frontend Usage (React)
+## Configuration
 
-#### Using OxyProvider (Recommended)
-
-```typescript
-import React, { useState, useEffect } from 'react';
-import { OxyProvider, useAuth, useUser, useKarma, useWallet } from '@oxyhq/services';
-
-// Wrap your app with OxyProvider
-function App() {
-  return (
-    <OxyProvider apiUrl="https://api.oxy.example.com" storage="local">
-      <AuthenticatedApp />
-    </OxyProvider>
-  );
-}
+`OxyConfig`:
 
-// 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();
-  
-  // State for login form
-  const [username, setUsername] = useState('');
-  const [password, setPassword] = useState('');
-  const [authStatus, setAuthStatus] = useState(false);
-  
-  // Check authentication status on component mount and when auth changes
-  useEffect(() => {
-    const checkAuth = async () => {
-      const isAuthenticated = await auth.isAuthenticated();
-      setAuthStatus(isAuthenticated);
-      
-      // If authenticated but no user data, fetch the user profile
-      if (isAuthenticated && !auth.user) {
-        await auth.getCurrentUser();
-      }
-    };
-    
-    checkAuth();
-  }, [auth]);
-  
-  const handleLogin = async () => {
-    const result = await auth.login({
-      username,
-      password
-    });
-    
-    if (result.success) {
-      console.log('Logged in successfully');
-      // User data should be automatically set from the response
-      // which may include a user object directly
-    }
-  };
-
-  return (
-    <div>
-      {authStatus ? (
-        <div>
-          <h2>Welcome, {auth.user?.username}</h2>
-          <button onClick={auth.logout}>Logout</button>
-        </div>
-      ) : (
-        <form onSubmit={(e) => {
-          e.preventDefault();
-          handleLogin();
-        }}>
-          <input 
-            type="text"
-            value={username}
-            onChange={(e) => setUsername(e.target.value)}
-            placeholder="Username" 
-          />
-          <input 
-            type="password"
-            value={password}
-            onChange={(e) => setPassword(e.target.value)}
-            placeholder="Password" 
-          />
-          <button type="submit">Login</button>
-        </form>
-      )}
-    </div>
-  );
+```ts
+interface OxyConfig {
+  /** Base URL of the Oxy API, e.g. https://api.mention.earth */
+  baseURL: string;
+  /** Optional timeout in milliseconds (default: 0 for no timeout) */
+  timeout?: number;
 }
-
-export default App;
 ```
 
-#### Direct Usage (Without Provider)
-
-```typescript
-import React, { useState, useEffect } 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
-  });
-
-  // Use user management hook
-  const user = useUser({
-    apiUrl: 'https://api.oxy.example.com',
-    getToken: auth.getToken
-  });
-
-  // Use karma hook
-  const karma = useKarma({
-    apiUrl: 'https://api.oxy.example.com',
-    getToken: auth.getToken
-  });
-
-  // Use wallet hook
-  const wallet = useWallet({
-    apiUrl: 'https://api.oxy.example.com',
-    getToken: auth.getToken
-  });
-
-  // State for login form and auth status
-  const [username, setUsername] = useState('');
-  const [password, setPassword] = useState('');
-  const [authStatus, setAuthStatus] = useState(false);
-  
-  // Check authentication status on component mount and when auth changes
-  useEffect(() => {
-    const checkAuth = async () => {
-      const isAuthenticated = await auth.isAuthenticated();
-      setAuthStatus(isAuthenticated);
-      
-      // If authenticated but no user data, fetch the user profile
-      if (isAuthenticated && !auth.user) {
-        await auth.getCurrentUser();
-      }
-    };
-    
-    checkAuth();
-  }, [auth]);
-
-  const handleLogin = async () => {
-    const result = await auth.login({
-      username,
-      password
-    });
-    
-    if (result.success) {
-      console.log('Logged in successfully');
-      // User data should be automatically set from the response
-    }
-  };
-
-  return (
-    <div>
-      {authStatus ? (
-        <div>
-          <h2>Welcome, {auth.user?.username}</h2>
-          <button onClick={auth.logout}>Logout</button>
-        </div>
-      ) : (
-        <form onSubmit={(e) => {
-          e.preventDefault();
-          handleLogin();
-        }}>
-          <input 
-            type="text"
-            value={username}
-            onChange={(e) => setUsername(e.target.value)}
-            placeholder="Username" 
-          />
-          <input 
-            type="password"
-            value={password}
-            onChange={(e) => setPassword(e.target.value)}
-            placeholder="Password" 
-          />
-          <button type="submit">Login</button>
-        </form>
-      )}
-    </div>
-  );
-}
-
-export default App;
-```
+- Requests use `axios` under the hood. You can set `timeout` or other axios defaults via config or by accessing `client.client.defaults`.
+- Tokens are stored in-memory; for persistence (e.g. React Native storage), handle saving and restoring external to this library.
 
 ## API Reference
 
-### Backend Services
-
-- `OxyAuthBackend` - Authentication services
-- `OxyUsersBackend` - User management services
-- `OxyKarmaBackend` - Karma/reputation services
-- `OxyWalletBackend` - Wallet and transaction services
-
-### Frontend Hooks & Context
+### OxyConfig
 
-- `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
+| Property | Type      | Required | Description                           |
+| -------- | --------- | -------- | ------------------------------------- |
+| baseURL  | `string`  | Yes      | Root URL of the Oxy API server        |
+| timeout  | `number`  | No       | Request timeout in milliseconds       |
 
-## License
-
-MIT 
-
-## Authentication Changes (v0.1.12)
-
-### Important Updates
-
-1. **Robust Authentication State Management**:
-   - Changed `isAuthenticated` from a boolean state to an async function that checks for tokens in real-time
-   - Eliminates race conditions and ensures authentication state is always current
-   - Provides more reliable session handling across the entire application
-
-2. **Improved Session Persistence**:
-   - Authentication state now directly reflects the presence of valid tokens rather than a separate state
-   - More reliable initialization of user data when app is reloaded with existing tokens
-
-3. **Better Dependency Management**:
-   - Fixed circular dependencies in authentication-related functions
-   - Made hook dependencies more explicit and safer to prevent potential bugs
-
-4. **Consistent Token Storage Key Names**:
-   - Fixed critical bug where token storage keys were inconsistent between OxyContext and ApiClient
-   - Standardized all token keys to `oxy_access_token` and `oxy_refresh_token` across all components
-
-5. **Automatic User Profile Loading**:
-   - Added automatic user profile loading on initialization when a valid token exists
-   - Ensures the user profile is available as soon as possible after authentication
+### Class: OxyServices
 
-6. **Cookie Storage Support**:
-   - Improved cookie-based token storage with proper implementation
-   - Added cookie expiration handling for improved security
-
-7. **Fixed Authentication Token Storage**:
-   - Resolved issues with token storage and retrieval by making all token operations asynchronous
-   - Added direct token storage via ApiClient during login/register for consistent token management
-   - Properly implemented `/auth/me` endpoint in the API to fetch user profiles
-
-8. **Enhanced Login/Register Response Handling**:
-   - Both `login()` and `register()` functions now support receiving the user object directly in the API response
-   - If the API returns a user object with the tokens, it will be stored automatically without making an extra `/auth/me` request
-
-9. **Client-side Validation**:
-   - Added input validation for login and registration requests
-   - Provides detailed error feedback with field-specific error messages
-   - Prevents unnecessary API calls when required fields are missing
-
-10. **Async Authentication Methods**:
-    - All authentication methods are now properly asynchronous and return Promises
-    - Use `await auth.isAuthenticated()` to get the current authentication status
+Instantiate with:
+```ts
+const client = new OxyServices(config);
+```
 
-### Migration Guide
+#### Authentication
+
+| Method               | Signature                                                   | Description                                    |
+| -------------------- | ----------------------------------------------------------- | ---------------------------------------------- |
+| `signUp`             | `(username: string, email: string, password: string) => Promise<{ message: string; token: string; user: User }>` | Create a new user and receive a token         |
+| `login`              | `(username: string, password: string) => Promise<LoginResponse>` | Authenticate and store access & refresh tokens |
+| `logout`             | `() => Promise<void>`                                       | Revoke current refresh token                   |
+| `refreshTokens`      | `() => Promise<{ accessToken: string; refreshToken: string }>` | Obtain new tokens using stored refresh token   |
+| `validate`           | `() => Promise<boolean>`                                     | Check if current access token is valid         |
+
+#### User & Profiles
+
+| Method                       | Signature                                       | Description                                                                |
+| ---------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------- |
+| `getProfileByUsername`       | `(username: string) => Promise<any>`            | Fetch public profile by username                                           |
+| `searchProfiles`             | `(query: string, limit?: number, offset?: number) => Promise<any[]>` | Full-text search for profiles                     |
+| `getUserById`                | `(userId: string) => Promise<any>`              | Fetch user data by user ID                                                  |
+| `updateUser`                 | `(userId: string, updates: Record<string, any>) => Promise<any>` | Update fields on authenticated user profile                                  |
+| `followUser` / `unfollowUser`| `(userId: string) => Promise<any>`              | Toggle following relationship with target user                              |
+
+#### Notifications
+
+| Method                          | Signature                                 | Description                               |
+| ------------------------------- | ----------------------------------------- | ----------------------------------------- |
+| `getNotifications`              | `() => Promise<Notification[]>`           | Retrieve all notifications for current user|
+| `getUnreadCount`                | `() => Promise<number>`                   | Count unread notifications                |
+| `createNotification`            | `(data: Partial<Notification>) => Promise<Notification>` | (Admin) create custom notification         |
+| `markNotificationAsRead`        | `(id: string) => Promise<void>`           | Mark one notification as read              |
+| `markAllNotificationsAsRead`    | `() => Promise<void>`                     | Mark all notifications as read             |
+| `deleteNotification`            | `(id: string) => Promise<void>`           | Delete a notification                      |
+
+#### Payments & Wallet
+
+| Method                   | Signature                                                       | Description                              |
+| ------------------------ | --------------------------------------------------------------- | ---------------------------------------- |
+| `processPayment`         | `(data: { userId: string; plan: string; paymentMethod: any; platform: string }) => Promise<{ success: boolean; transactionId: string }>` | Charge user for subscription or plan       |
+| `validatePaymentMethod`  | `(paymentMethod: any) => Promise<{ valid: boolean }>`            | Pre-validate payment method               |
+| `getPaymentMethods`      | `(userId: string) => Promise<any>`                              | List saved payment methods                |
+| `getWallet`              | `(userId: string) => Promise<any>`                              | Fetch or initialize wallet balance        |
+| `getTransactionHistory`  | `(userId: string, limit?: number, offset?: number) => Promise<any>` | Retrieve paginated transaction history     |
+| `getTransaction`         | `(transactionId: string) => Promise<any>`                       | Fetch details for a specific transaction  |
+| `transferFunds`          | `(data: { fromUserId: string; toUserId: string; amount: number; description?: string }) => Promise<any>` | Transfer funds between users                |
+| `processPurchase`        | `(data: { userId: string; amount: number; itemId: string; itemType: string; description?: string }) => Promise<any>` | Debit wallet for an in‑app purchase         |
+| `requestWithdrawal`      | `(data: { userId: string; amount: number; address: string }) => Promise<any>` | Initiate a withdrawal request               |
+
+#### Analytics
+
+| Method                   | Signature                                                      | Description                               |
+| ------------------------ | -------------------------------------------------------------- | ----------------------------------------- |
+| `getAnalytics`           | `(userId: string, period?: string) => Promise<any>`            | Time‑series metrics for a user            |
+| `updateAnalytics`        | `(userId: string, type: string, data: Record<string, any>) => Promise<{ message: string }>` | Increment analytics counters               |
+| `getContentViewers`      | `(userId: string, period?: string) => Promise<any[]>`          | List viewers of user content               |
+| `getFollowerDetails`     | `(userId: string, period?: string) => Promise<any>`            | Insights on follower growth                |
+
+#### Karma System
+
+| Method                      | Signature                                                   | Description                                   |
+| --------------------------- | ----------------------------------------------------------- | --------------------------------------------- |
+| `getKarmaLeaderboard`       | `() => Promise<any[]>`                                      | Global leaderboard of top karma earners       |
+| `getKarmaRules`             | `() => Promise<any[]>`                                      | List configured karma rules                   |
+| `getUserKarmaTotal`         | `(userId: string) => Promise<{ total: number }>`            | Fetch total karma for a user                  |
+| `getUserKarmaHistory`       | `(userId: string, limit?: number, offset?: number) => Promise<any>` | User’s karma event history                     |
+| `awardKarma` / `deductKarma`| `(data: { userId: string; points: number; reason?: string }) => Promise<any>` | Modify user karma (requires auth)            |
+| `createOrUpdateKarmaRule`   | `(data: any) => Promise<any>`                                | (Admin) define or update karma rules         |
+
+## Examples
+
+See usage in the [Fast Start](#usage) section above. For advanced scenarios (e.g., external token storage, Axios customization), refer to source code: `src/index.ts`.
+
+## Development
 
-When updating from previous versions, make the following changes to your code:
+```bash
+# Install dev deps
+tonpm install
+# Build library
+npm run build
+# Run tests (no tests by default)
+npm test
+``` 
+
+## Contributing
+
+1. Fork the repo
+2. Create feature branch
+3. Code and add tests
+4. Build and commit
+5. Open PR for review
 
-```typescript
-// Before
-if (auth.isAuthenticated) {
-  // User is logged in
-}
+## License
 
-// After - with async/await
-const checkAuth = async () => {
-  if (await auth.isAuthenticated()) {
-    // User is logged in
-  }
-};
-
-// After - with useEffect
-useEffect(() => {
-  const checkAuth = async () => {
-    const isAuthenticated = await auth.isAuthenticated();
-    // Update your component state
-  };
-  
-  checkAuth();
-}, [auth]);
-``` 
+MIT © Oxy

package/dist/index.d.ts

@@ -1,3 +1,152 @@
-export * from './shared/types';
-export { OxyAuthBackend, OxyUsersBackend, OxyKarmaBackend, OxyWalletBackend } from './backend';
-export { useAuth, useUser, useKarma, useWallet, OxyProvider, useOxyContext } from './frontend';
+export interface OxyConfig {
+    /** Base URL of the Oxy API, e.g. https://api.mention.earth or http://localhost:3001 */
+    baseURL: string;
+}
+export interface User {
+    id: string;
+    username: string;
+    email: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LoginResponse {
+    accessToken: string;
+    refreshToken: string;
+    user: User;
+}
+export interface Notification {
+    id: string;
+    recipientId: string;
+    actorId: string;
+    type: string;
+    entityId: string;
+    entityType: string;
+    read: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare class OxyServices {
+    private client;
+    private accessToken;
+    private refreshToken;
+    constructor(config: OxyConfig);
+    /** Sign up a new user */
+    signUp(username: string, email: string, password: string): Promise<{
+        message: string;
+        token: string;
+        user: User;
+    }>;
+    /** Log in and store tokens */
+    login(username: string, password: string): Promise<LoginResponse>;
+    /** Log out user */
+    logout(): Promise<void>;
+    /** Refresh access and refresh tokens */
+    refreshTokens(): Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    /** Validate current access token */
+    validate(): Promise<boolean>;
+    /** Fetch profile by username */
+    getProfileByUsername(username: string): Promise<any>;
+    /** Search profiles */
+    searchProfiles(query: string, limit?: number, offset?: number): Promise<any[]>;
+    /** Get general user by ID */
+    getUserById(userId: string): Promise<any>;
+    /** Update user profile (requires auth) */
+    updateUser(userId: string, updates: Record<string, any>): Promise<any>;
+    /** Follow a user */
+    followUser(userId: string): Promise<any>;
+    /** Unfollow a user */
+    unfollowUser(userId: string): Promise<any>;
+    /** Fetch all notifications for the authenticated user */
+    getNotifications(): Promise<Notification[]>;
+    /** Get count of unread notifications */
+    getUnreadCount(): Promise<number>;
+    /** Create a new notification (admin use) */
+    createNotification(data: Partial<Notification>): Promise<Notification>;
+    /** Mark a single notification as read */
+    markNotificationAsRead(notificationId: string): Promise<void>;
+    /** Mark all notifications as read */
+    markAllNotificationsAsRead(): Promise<void>;
+    /** Delete a notification */
+    deleteNotification(notificationId: string): Promise<void>;
+    /** Process a payment */
+    processPayment(data: {
+        userId: string;
+        plan: string;
+        paymentMethod: any;
+        platform: string;
+    }): Promise<{
+        success: boolean;
+        transactionId: string;
+    }>;
+    /** Validate a payment method */
+    validatePaymentMethod(paymentMethod: any): Promise<{
+        valid: boolean;
+    }>;
+    /** Get saved payment methods for a user */
+    getPaymentMethods(userId: string): Promise<any>;
+    /** Get analytics data */
+    getAnalytics(userId: string, period?: string): Promise<any>;
+    /** Update analytics (internal use) */
+    updateAnalytics(userId: string, type: string, data: Record<string, any>): Promise<{
+        message: string;
+    }>;
+    /** Get content viewers analytics */
+    getContentViewers(userId: string, period?: string): Promise<any[]>;
+    /** Get follower analytics details */
+    getFollowerDetails(userId: string, period?: string): Promise<any>;
+    /** Get wallet info */
+    getWallet(userId: string): Promise<any>;
+    /** Get transaction history */
+    getTransactionHistory(userId: string, limit?: number, offset?: number): Promise<any>;
+    /** Get a specific transaction */
+    getTransaction(transactionId: string): Promise<any>;
+    /** Transfer funds */
+    transferFunds(data: {
+        fromUserId: string;
+        toUserId: string;
+        amount: number;
+        description?: string;
+    }): Promise<any>;
+    /** Process a purchase */
+    processPurchase(data: {
+        userId: string;
+        amount: number;
+        itemId: string;
+        itemType: string;
+        description?: string;
+    }): Promise<any>;
+    /** Request a withdrawal */
+    requestWithdrawal(data: {
+        userId: string;
+        amount: number;
+        address: string;
+    }): Promise<any>;
+    /** Karma: get leaderboard */
+    getKarmaLeaderboard(): Promise<any[]>;
+    /** Karma: get rules */
+    getKarmaRules(): Promise<any[]>;
+    /** Karma: get total for a user */
+    getUserKarmaTotal(userId: string): Promise<{
+        total: number;
+    }>;
+    /** Karma: get history for a user */
+    getUserKarmaHistory(userId: string, limit?: number, offset?: number): Promise<any>;
+    /** Karma: award points */
+    awardKarma(data: {
+        userId: string;
+        points: number;
+        reason?: string;
+    }): Promise<any>;
+    /** Karma: deduct points */
+    deductKarma(data: {
+        userId: string;
+        points: number;
+        reason?: string;
+    }): Promise<any>;
+    /** Karma: create or update rule (admin) */
+    createOrUpdateKarmaRule(data: any): Promise<any>;
+}
+export default OxyServices;