@oxyhq/services 5.10.15 → 5.10.16

package/README.md

@@ -1,242 +1,655 @@
 # OxyHQServices
 
-A TypeScript client library for the Oxy API providing authentication, user management, and UI components for React and React Native applications.
+A comprehensive TypeScript client library for the Oxy API providing authentication, user management, and UI components for React Native, Expo, and Node.js applications.
 
-## Table of Contents
+## 📋 Table of Contents
 
 - [Features](#features)
+- [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Documentation](#documentation)
+- [Usage Patterns](#usage-patterns)
+  - [Frontend (React/React Native)](#frontend-reactreact-native)
+  - [Backend (Node.js)](#backend-nodejs)
+  - [Mixed Applications](#mixed-applications)
+- [API Reference](#api-reference)
+- [Configuration](#configuration)
+- [Authentication](#authentication)
 - [UI Components](#ui-components)
-- [Package Exports](#package-exports)
+- [Troubleshooting](#troubleshooting)
 - [Requirements](#requirements)
-- [Development](#development)
-- [Integration](#integration)
-- [License](#license)
 
-## Features
+## ✨ Features
 
-- 🔐 **Streamlined Authentication**: Zero-config authentication with automatic token management
-- 🔄 **Auto Token Refresh**: Seamless token lifecycle management behind the scenes
-- 👥 **User Management**: Profile operations and social features
-- 🎨 **UI Components**: Pre-built React components for common functionality
-- 📱 **Cross-Platform**: Works in React Native and web applications
-- 🔧 **TypeScript**: Full type safety and IntelliSense support
-- 🚀 **Performance**: Optimized with automatic caching and state management
-- ✨ **Simple API**: All functionality in one unified class - no need to manage multiple service instances
+- 🔐 **Zero-Config Authentication**: Automatic token management and refresh
+- 📱 **React Native First**: Optimized for React Native and Expo applications
+- 🎨 **UI Components**: Pre-built React Native components with built-in bottom sheet
+- 🔄 **Cross-Platform**: Works seamlessly in React Native, Expo, and Node.js
+- 📱 **Multi-Session Support**: Manage multiple user sessions simultaneously
+- 🔧 **TypeScript First**: Full type safety and IntelliSense support
+- 🚀 **Performance Optimized**: Automatic caching and state management
+- 🛡️ **Production Ready**: Error handling, retry logic, and security best practices
 
-## Quick Start
+## 📦 Installation
 
 ```bash
 npm install @oxyhq/services
 ```
 
-### Simple & Unified API
+### React Native/Expo Setup
 
-The new OxyServices provides all functionality in one simple class:
+For React Native and Expo projects, add the polyfill import at the very top of your entry file:
 
-```typescript
-import { OxyServices } from '@oxyhq/services';
-
-const oxy = new OxyServices({ baseURL: 'https://api.example.com' });
+```javascript
+// index.js or App.js (very first line)
+import 'react-native-url-polyfill/auto';
+```
 
-// Authentication
-await oxy.signIn('username', 'password');
-await oxy.signUp('username', 'email', 'password');
+## 🚀 Quick Start
 
-// User operations
-const user = await oxy.getCurrentUser();
-await oxy.updateProfile({ name: 'John Doe' });
-await oxy.followUser('user123');
+### React Native/Expo
 
-// Social features
-const followers = await oxy.getUserFollowers('user123');
-const notifications = await oxy.getNotifications();
+```typescript
+import { OxyProvider, useOxy } from '@oxyhq/services';
 
-// File uploads
-const fileData = await oxy.uploadFile(file);
+function App() {
+  return (
+    <OxyProvider baseURL="https://cloud.oxy.so">
+      <YourApp />
+    </OxyProvider>
+  );
+}
 
-// Payments
-const payment = await oxy.createPayment(paymentData);
+function UserProfile() {
+  const { oxyServices, user, isAuthenticated } = useOxy();
+  
+  if (!isAuthenticated) {
+    return <Text>Please sign in</Text>;
+  }
+  
+  return <Text>Welcome, {user?.name}!</Text>;
+}
+```
 
-// Location services
-await oxy.updateLocation(40.7128, -74.0060);
-const nearby = await oxy.getNearbyUsers();
+### Backend (Node.js)
 
-// Analytics
-await oxy.trackEvent('user_action', { action: 'click' });
+```typescript
+import { oxyClient } from '@oxyhq/services';
 
-// Everything in one place - no more managing multiple service instances!
+// Ready to use - no configuration needed!
+app.get('/api/user', async (req, res) => {
+  const user = await oxyClient.getCurrentUser();
+  res.json(user);
+});
 ```
 
-### Streamlined Authentication (Recommended)
+## 📖 Usage Patterns
+
+### React Native/Expo
+
+#### 1. **OxyProvider + useOxy Hook (Recommended)**
+
+This pattern provides full React Native integration with automatic state management, UI components, and authentication flow.
 
 ```typescript
 import { OxyProvider, useOxy } from '@oxyhq/services';
 
+// App.tsx - Setup the provider
 function App() {
   return (
-    <OxyProvider baseURL="https://api.example.com">
+    <OxyProvider 
+      baseURL="https://cloud.oxy.so"
+      onAuthStateChange={(user) => {
+        console.log('Auth state changed:', user ? 'logged in' : 'logged out');
+      }}
+    >
       <YourApp />
     </OxyProvider>
   );
 }
 
+// Component.tsx - Use the hook
 function UserProfile() {
-  const { oxyServices } = useOxy();
-  
-  const fetchData = async () => {
-    // No manual authentication needed - everything is automatic!
-    const user = await oxyServices.getCurrentUser();
-    const notifications = await oxyServices.getNotifications();
+  const { 
+    oxyServices,    // OxyServices instance
+    user,           // Current user data
+    isAuthenticated, // Authentication state
+    login,          // Login method
+    logout,         // Logout method
+    showBottomSheet // UI methods
+  } = useOxy();
+
+  const handleLogin = async () => {
+    try {
+      await login('username', 'password');
+    } catch (error) {
+      console.error('Login failed:', error);
+    }
+  };
+
+  const openSignIn = () => {
+    showBottomSheet('SignIn');
   };
+
+  return (
+    <View>
+      {isAuthenticated ? (
+        <View>
+          <Text style={styles.title}>Welcome, {user?.name}!</Text>
+          <TouchableOpacity onPress={logout} style={styles.button}>
+            <Text>Sign Out</Text>
+          </TouchableOpacity>
+        </View>
+      ) : (
+        <TouchableOpacity onPress={openSignIn} style={styles.button}>
+          <Text>Sign In</Text>
+        </TouchableOpacity>
+      )}
+    </View>
+  );
 }
 ```
 
-### With Built-in Bottom Sheet
+#### 2. **Direct Import (Non-React Files)**
+
+For utility functions, services, or non-React Native files:
+
+```typescript
+import { oxyClient } from '@oxyhq/services';
+
+// utils/api.ts
+export const userUtils = {
+  async fetchUserProfile(userId: string) {
+    return await oxyClient.getUserById(userId);
+  },
+  
+  async updateUserProfile(updates: any) {
+    return await oxyClient.updateProfile(updates);
+  }
+};
+```
+
+### Backend (Node.js)
+
+#### 1. **Pre-configured Client (Recommended)**
+
+Use the pre-configured `oxyClient` for immediate access:
+
+```typescript
+import { oxyClient } from '@oxyhq/services';
+
+// routes/auth.ts
+export const signIn = async (req, res) => {
+  try {
+    const { username, password } = req.body;
+    const response = await oxyClient.signIn(username, password);
+    res.json(response);
+  } catch (error) {
+    res.status(401).json({ error: error.message });
+  }
+};
+
+// routes/users.ts
+export const getUserProfile = async (req, res) => {
+  try {
+    const { userId } = req.params;
+    const user = await oxyClient.getUserById(userId);
+    res.json(user);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+};
+
+// routes/social.ts
+export const getFollowers = async (req, res) => {
+  try {
+    const { userId } = req.params;
+    const followers = await oxyClient.getUserFollowers(userId);
+    res.json(followers);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+};
+```
+
+#### 2. **Custom Configuration**
+
+Create your own instance with custom settings:
+
+```typescript
+import { OxyServices, OXY_CLOUD_URL } from '@oxyhq/services';
+
+const oxy = new OxyServices({ 
+  baseURL: process.env.OXY_API_URL || OXY_CLOUD_URL 
+});
+
+export { oxy };
+```
+
+### Mixed Applications (React Native + Backend)
 
-The OxyProvider now includes a built-in gorhom bottom sheet - no manual setup required!
+You can use both patterns in the same application:
 
 ```typescript
-import { OxyProvider, useOxy, OxySignInButton } from '@oxyhq/services';
+// App.tsx - React Native setup
+import { OxyProvider } from '@oxyhq/services';
 
 function App() {
   return (
-    <OxyProvider 
-      baseURL="https://api.example.com"
-      initialScreen="SignIn"
-      theme="light"
-    >
+    <OxyProvider baseURL="https://cloud.oxy.so">
       <YourApp />
     </OxyProvider>
   );
 }
 
+// utils/api.ts - Direct import
+import { oxyClient } from '@oxyhq/services';
+
+export const apiUtils = {
+  async fetchData() {
+    return await oxyClient.getCurrentUser();
+  }
+};
+
+// Component.tsx - React Native hook
+import { useOxy } from '@oxyhq/services';
+
 function Component() {
-  const { showBottomSheet } = useOxy();
-  
-  const openSignIn = () => {
-    showBottomSheet('SignIn'); // Works automatically!
-  };
-  
-  return (
-    <div>
-      <button onClick={openSignIn}>Sign In</button>
-      <OxySignInButton /> {/* Also works automatically! */}
-    </div>
-  );
+  const { oxyServices } = useOxy();
+  // Both oxyServices and oxyClient share the same tokens!
 }
 ```
 
-### Simple & Unified API
+## 🔧 API Reference
+
+### Core Exports
 
 ```typescript
-import { OxyServices } from '@oxyhq/services';
+import { 
+  OxyServices,           // Main service class
+  oxyClient,            // Pre-configured instance
+  OXY_CLOUD_URL,        // Default API URL
+  OxyAuthenticationError,
+  OxyAuthenticationTimeoutError
+} from '@oxyhq/services';
+```
 
-const oxy = new OxyServices({
-  baseURL: 'http://localhost:3000'
-});
+### React Native Exports
+
+```typescript
+import { 
+  OxyProvider,          // Context provider
+  useOxy,              // React Native hook
+  OxySignInButton,     // UI components
+  Avatar,
+  FollowButton
+} from '@oxyhq/services';
+```
+
+### OxyServices Methods
 
+```typescript
 // Authentication
-const response = await oxy.signIn('username', 'password');
+await oxyClient.signIn(username, password);
+await oxyClient.signUp(username, email, password);
+await oxyClient.logout();
 
-// User operations
-const user = await oxy.getCurrentUser();
-await oxy.updateProfile({ name: 'John Doe' });
-await oxy.followUser('user123');
+// User Management
+const user = await oxyClient.getCurrentUser();
+await oxyClient.updateProfile({ name: 'John Doe' });
+const userById = await oxyClient.getUserById('user123');
 
-// Social features
-const followers = await oxy.getUserFollowers('user123');
-const notifications = await oxy.getNotifications();
+// Social Features
+await oxyClient.followUser('user123');
+const followers = await oxyClient.getUserFollowers('user123');
+const notifications = await oxyClient.getNotifications();
+
+// File Management
+const fileData = await oxyClient.uploadFile(file);
+const downloadUrl = oxyClient.getFileDownloadUrl(fileId);
+
+// Payments
+const payment = await oxyClient.createPayment(paymentData);
 
-// File operations
-const fileData = await oxy.uploadFile(file);
-const downloadUrl = oxy.getFileDownloadUrl(fileId);
+// Location Services
+await oxyClient.updateLocation(40.7128, -74.0060);
+const nearby = await oxyClient.getNearbyUsers();
 
-// Everything is available directly on the oxy instance!
+// Analytics
+await oxyClient.trackEvent('user_action', { action: 'click' });
 ```
 
-## Documentation
+### useOxy Hook
 
-This package provides a TypeScript client library for the Oxy API with authentication, user management, and UI components.
+```typescript
+const { 
+  // Service instance
+  oxyServices,
+  
+  // Authentication state
+  user,
+  isAuthenticated,
+  isLoading,
+  error,
+  
+  // Authentication methods
+  login,
+  logout,
+  signUp,
+  
+  // Session management
+  sessions,
+  activeSessionId,
+  switchSession,
+  removeSession,
+  
+  // UI methods
+  showBottomSheet,
+  hideBottomSheet
+} = useOxy();
+```
 
-## UI Components
+## ⚙️ Configuration
 
-Import and use pre-built React components:
+### OxyProvider Props
 
 ```typescript
-import { OxyProvider, Avatar, FollowButton } from '@oxyhq/services/ui';
+<OxyProvider
+  baseURL="https://cloud.oxy.so"           // API base URL
+  storageKeyPrefix="oxy_session"          // Storage key prefix
+  onAuthStateChange={(user) => {}}        // Auth state callback
+  onError={(error) => {}}                 // Error callback
+  bottomSheetRef={bottomSheetRef}         // Bottom sheet ref
+>
+  {children}
+</OxyProvider>
 ```
 
-## Package Exports
+### Environment Variables
+
+```bash
+# .env
+OXY_API_URL=https://cloud.oxy.so
+NODE_ENV=production
+```
 
-The library provides a unified API:
+### Custom Configuration
 
 ```typescript
-// Unified OxyServices class (recommended)
 import { OxyServices } from '@oxyhq/services';
 
-// All functionality is available directly on the OxyServices instance
-const oxy = new OxyServices({ baseURL: 'https://api.example.com' });
+const oxy = new OxyServices({
+  baseURL: process.env.OXY_API_URL || 'https://cloud.oxy.so'
+});
+```
+
+## 🔐 Authentication
+
+### Automatic Token Management
+
+The library handles authentication automatically:
 
-// UI components (React/React Native)
-import { OxyProvider, Avatar } from '@oxyhq/services/ui';
+- **Token Storage**: Secure storage across sessions
+- **Token Refresh**: Automatic refresh before expiration
+- **Session Management**: Multi-session support
+- **Error Handling**: Graceful handling of auth errors
+
+### Manual Token Management
+
+```typescript
+import { oxyClient } from '@oxyhq/services';
+
+// Set tokens manually
+oxyClient.setTokens(accessToken, refreshToken);
+
+// Clear tokens
+oxyClient.clearTokens();
+
+// Check authentication
+const isAuthenticated = oxyClient.hasValidToken();
 ```
 
+## 🎨 UI Components
+
+### Built-in Components
+
+```typescript
+import { 
+  OxySignInButton,
+  Avatar,
+  FollowButton,
+  OxyLogo
+} from '@oxyhq/services';
+
+function MyComponent() {
+  return (
+    <View style={styles.container}>
+      <OxyLogo />
+      <Avatar userId="user123" size={40} />
+      <FollowButton userId="user123" />
+      <OxySignInButton />
+    </View>
+  );
+}
 
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 16,
+  },
+});
+```
 
-## Requirements
+### Bottom Sheet Integration
 
-- **Node.js** 16+ (for backend usage)
-- **React** 16.8+ (for React components)
-- **React Native** 0.60+ (for mobile components)
-- **TypeScript** 4.0+ (optional but recommended)
+```typescript
+import { useOxy } from '@oxyhq/services';
 
-## Troubleshooting
+function MyComponent() {
+  const { showBottomSheet } = useOxy();
+  
+  const openSignIn = () => {
+    showBottomSheet('SignIn');
+  };
+  
+  const openProfile = () => {
+    showBottomSheet('Profile');
+  };
+  
+  return (
+    <View style={styles.container}>
+      <TouchableOpacity onPress={openSignIn} style={styles.button}>
+        <Text>Sign In</Text>
+      </TouchableOpacity>
+      <TouchableOpacity onPress={openProfile} style={styles.button}>
+        <Text>Profile</Text>
+      </TouchableOpacity>
+    </View>
+  );
+}
+```
 
-### FormData Issues in React Native/Expo
+## 🛠️ Troubleshooting
 
-If you encounter `ReferenceError: Property 'FormData' doesn't exist` when using Expo with Hermes engine:
+### Common Issues
 
-**For file uploads in React Native/Expo:**
-- The library handles this automatically - no additional setup required
-- File uploads will work with both native FormData (when available) and the polyfilled version
-- Ensure you're using the latest version of the package
+#### 1. **"useOxy must be used within an OxyContextProvider"**
 
-### Additional Dependencies
+**Solution**: Wrap your app with `OxyProvider`
 
-For React Native projects, you may need to install peer dependencies:
+```typescript
+import { OxyProvider } from '@oxyhq/services';
 
-```bash
-npm install axios jwt-decode invariant
+function App() {
+  return (
+    <OxyProvider baseURL="https://cloud.oxy.so">
+      <YourApp />
+    </OxyProvider>
+  );
+}
 ```
 
-## Important for React Native Hermes Users
+#### 2. **FormData Issues in React Native/Expo**
 
-If you use this package in a React Native app with the Hermes engine, you must add the following import as the very first line of your app's entry file (e.g., App.js or index.js):
+**Solution**: Add polyfill import at the very top of your entry file
 
-```js
+```javascript
+// index.js or App.js (very first line)
 import 'react-native-url-polyfill/auto';
 ```
 
-This ensures that FormData and other web APIs are polyfilled before any dependencies are loaded. If you do not do this, you may see errors like:
+#### 3. **Authentication Not Persisting**
+
+**Solution**: Check storage configuration
 
+```typescript
+<OxyProvider 
+  baseURL="https://cloud.oxy.so"
+  storageKeyPrefix="my_app_oxy"  // Custom storage key
+>
+  {children}
+</OxyProvider>
 ```
-ReferenceError: Property 'FormData' doesn't exist, js engine: hermes
+
+### Error Handling
+
+```typescript
+import { OxyAuthenticationError } from '@oxyhq/services';
+
+try {
+  await oxyClient.getCurrentUser();
+} catch (error) {
+  if (error instanceof OxyAuthenticationError) {
+    // Handle authentication errors
+    console.log('Auth error:', error.message);
+  } else {
+    // Handle other errors
+    console.log('Other error:', error.message);
+  }
+}
 ```
 
----
+## 📋 Requirements
+
+- **Node.js**: 16+ (for backend usage)
+- **React Native**: 0.60+ (for mobile components)
+- **Expo**: 44+ (recommended)
+- **TypeScript**: 4.0+ (optional but recommended)
 
-## Development
+### Peer Dependencies
+
+For React Native/Expo projects:
 
 ```bash
-# Install dependencies
-npm install
+npm install axios jwt-decode invariant react-native-url-polyfill
+```
+
+## 📚 Examples
+
+### Complete React Native App
+
+```typescript
+// App.tsx
+import { OxyProvider } from '@oxyhq/services';
+
+function App() {
+  return (
+    <OxyProvider baseURL="https://cloud.oxy.so">
+      <UserDashboard />
+    </OxyProvider>
+  );
+}
+
+// UserDashboard.tsx
+import { useOxy } from '@oxyhq/services';
+import { View, Text, StyleSheet } from 'react-native';
 
-# Build the library
-npm run build
+function UserDashboard() {
+  const { user, isAuthenticated, oxyServices } = useOxy();
+  
+  const [followers, setFollowers] = useState([]);
+  
+  useEffect(() => {
+    if (isAuthenticated && user) {
+      oxyServices.getUserFollowers(user.id).then(setFollowers);
+    }
+  }, [isAuthenticated, user]);
+  
+  if (!isAuthenticated) {
+    return <Text>Please sign in</Text>;
+  }
+  
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Welcome, {user?.name}!</Text>
+      <Text>Followers: {followers.length}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 16,
+    justifyContent: 'center',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 16,
+  },
+});
+```
+
+### Complete Backend API
+
+```typescript
+// server.ts
+import express from 'express';
+import { oxyClient } from '@oxyhq/services';
+
+const app = express();
+app.use(express.json());
+
+// Auth routes
+app.post('/api/auth/signin', async (req, res) => {
+  try {
+    const { username, password } = req.body;
+    const response = await oxyClient.signIn(username, password);
+    res.json(response);
+  } catch (error) {
+    res.status(401).json({ error: error.message });
+  }
+});
+
+// User routes
+app.get('/api/users/:userId', async (req, res) => {
+  try {
+    const { userId } = req.params;
+    const user = await oxyClient.getUserById(userId);
+    res.json(user);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+// Social routes
+app.get('/api/users/:userId/followers', async (req, res) => {
+  try {
+    const { userId } = req.params;
+    const followers = await oxyClient.getUserFollowers(userId);
+    res.json(followers);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
 ```
 
-## License
+---
+
+## 📄 License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.