@oxyhq/services 5.7.4 → 5.7.5

package/README.md

@@ -1,347 +1,201 @@
 # OxyHQServices
 
-A TypeScript client library for the Oxy API providing **zero-config** authentication, user management, and UI components for React and React Native applications.
+🚀 **Zero-config authentication and user management** for React, React Native, and Node.js applications. No manual token handling, no interceptor setup, no middleware configuration required.
 
-## ✨ Zero-Config Quick Start
+## ✨ Quick Start (Zero Config)
 
-### Frontend (React/Next.js) - 2 lines of code:
+### Frontend (React/React Native)
 
-```jsx
-import { OxyZeroConfigProvider, useOxyZeroConfig } from '@oxyhq/services/ui';
+```tsx
+import React from 'react';
+import { AuthProvider, useAuth } from '@oxyhq/services';
 
-// 1. Wrap your app
+// 1. Wrap your app (that's it for setup!)
 function App() {
   return (
-    <OxyZeroConfigProvider>
-      <YourApp />
-    </OxyZeroConfigProvider>
+    <AuthProvider baseURL="https://api.oxy.so">
+      <MainApp />
+    </AuthProvider>
   );
 }
 
 // 2. Use authentication anywhere
-function Dashboard() {
-  const { user, login, logout, isAuthenticated } = useOxyZeroConfig();
-  
-  if (isAuthenticated) {
-    return <div>Welcome {user.username}! <button onClick={logout}>Logout</button></div>;
-  }
+function MainApp() {
+  const { isAuthenticated, user, login, logout } = useAuth();
   
-  return <button onClick={() => login('user', 'password')}>Login</button>;
-}
-```
-
-### Backend (Express.js) - 1 line of code:
-
-```js
-import express from 'express';
-import { createOxyAuth } from '@oxyhq/services/node';
-
-const app = express();
-
-// Zero-config auth - req.user automatically available
-app.use('/api', createOxyAuth());
-
-app.get('/api/profile', (req, res) => {
-  res.json({ user: req.user }); // req.user populated automatically!
-});
-```
-
-**That's it!** No complex configuration, no manual token management, no middleware setup.
-
-## Table of Contents
-
-- [Zero-Config Guide](#-zero-config-quick-start)  
-- [Features](#features)
-- [Installation](#installation)
-- [Complete Examples](#complete-examples)
-- [Advanced Usage](#advanced-usage)
-- [Documentation](#documentation)
-- [Migration Guide](#migration-guide)
-
-## Features
-
-- 🚀 **Zero-Config**: Get authentication working in 2-3 lines of code
-- 🔐 **Automatic Token Management**: Tokens saved, restored, and refreshed automatically
-- 👥 **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
-- 🔄 **Auto Backend Integration**: Frontend automatically sends tokens to backend
-- 📦 **Express Middleware**: One-line backend authentication with `req.user` support
-
-## Installation
-
-```bash
-npm install @oxyhq/services
-```
-
-## Complete Examples
-
-### React Application
-
-**App.js**
-```jsx
-import React from 'react';
-import { OxyZeroConfigProvider } from '@oxyhq/services/ui';
-import Dashboard from './Dashboard';
-
-export default function App() {
-  return (
-    <OxyZeroConfigProvider>
-      <Dashboard />
-    </OxyZeroConfigProvider>
-  );
-}
-```
-
-**Dashboard.js**
-```jsx
-import React from 'react';
-import { useOxyZeroConfig } from '@oxyhq/services/ui';
-
-export default function Dashboard() {
-  const { user, login, logout, isAuthenticated, isLoading } = useOxyZeroConfig();
-
-  if (isLoading) return <div>Loading...</div>;
-
   if (!isAuthenticated) {
-    return (
-      <div>
-        <h1>Please log in</h1>
-        <button onClick={() => login('demo', 'password')}>Login</button>
-      </div>
-    );
+    return <button onClick={() => login('user', 'pass')}>Login</button>;
   }
-
+  
   return (
     <div>
-      <h1>Welcome, {user.username}!</h1>
+      <h1>Welcome {user?.username}!</h1>
       <button onClick={logout}>Logout</button>
     </div>
   );
 }
 ```
 
-### Express.js Backend
+### Backend (Express.js)
 
-**server.js**
-```js
+```typescript
 import express from 'express';
-import { createOxyAuth } from '@oxyhq/services/node';
+import { authenticateRequest, OxyRequest } from '@oxyhq/services/api';
 
 const app = express();
-app.use(express.json());
-
-// Public routes
-app.get('/', (req, res) => {
-  res.json({ message: 'Public endpoint' });
-});
-
-// Protected routes - zero config!
-app.use('/api', createOxyAuth());
 
-// req.user is automatically available
-app.get('/api/profile', (req, res) => {
+// Zero-config authentication - just add the middleware
+app.get('/profile', authenticateRequest(), (req: OxyRequest, res) => {
+  // req.user is automatically populated!
   res.json({ 
-    message: `Hello ${req.user.username}!`,
+    message: `Hello ${req.user!.username}!`,
     user: req.user 
   });
 });
-
-app.listen(3000, () => console.log('Server running on port 3000'));
 ```
 
-### Next.js Full-Stack
+That's it! 🎉 Authentication is now fully automated with:
+- ✅ Automatic token management and refresh
+- ✅ Secure storage across app restarts  
+- ✅ Built-in error handling and retry logic
+- ✅ Cross-platform support (React Native + Web)
+- ✅ TypeScript support throughout
 
-**pages/_app.js**
-```jsx
-import { OxyZeroConfigProvider } from '@oxyhq/services/ui';
+## 📖 Documentation
 
-export default function App({ Component, pageProps }) {
-  return (
-    <OxyZeroConfigProvider>
-      <Component {...pageProps} />
-    </OxyZeroConfigProvider>
-  );
-}
-```
+- **[🚀 Zero-Config Authentication Guide](./packages/services/ZERO_CONFIG_AUTH.md)** - Complete setup guide
+- **[🔧 Migration Guide](./packages/services/ZERO_CONFIG_AUTH.md#migration-from-legacy-authentication)** - Upgrade from legacy auth
+- **[📚 Examples](./packages/services/examples/)** - Complete integration examples
+- **[🔐 API Reference](./packages/services/ZERO_CONFIG_AUTH.md#complete-api-reference)** - All components and hooks
 
-**pages/api/user.js**
-```js
-import { createOxyAuth } from '@oxyhq/services/node';
+## Table of Contents
 
-const auth = createOxyAuth();
+- [Legacy Features](#features)
+- [Legacy Quick Start](#quick-start)
+- [Package Exports](#package-exports)
+- [Requirements](#requirements)
+- [Development](#development)
+- [Integration](#integration)
+- [License](#license)
 
-export default async function handler(req, res) {
-  // Apply authentication
-  await new Promise((resolve, reject) => {
-    auth(req, res, (err) => {
-      if (err) reject(err);
-      else resolve();
-    });
-  });
+---
 
-  // req.user is now available
-  res.json({ user: req.user });
-}
-```
+## Legacy Features (Still Supported)
 
-## Advanced Usage
+A TypeScript client library for the Oxy API providing authentication, user management, and UI components for React and React Native applications.
 
-### Configuration Options
+- 🔐 **Authentication**: JWT-based auth with automatic token refresh
+- 👥 **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
 
-**Frontend**
-```jsx
-<OxyZeroConfigProvider
-  apiUrl="https://your-api.com"
-  onAuthChange={(user) => console.log('Auth changed:', user)}
->
-  <App />
-</OxyZeroConfigProvider>
-```
+## Legacy Quick Start
 
-**Backend**
-```js
-app.use('/api', createOxyAuth({
-  baseURL: 'https://your-oxy-api.com',
-  loadUser: true,
-  publicPaths: ['/api/health'],
-  onError: (error, req, res) => {
-    res.status(error.status).json({ error: error.message });
-  }
-}));
+```bash
+npm install @oxyhq/services
 ```
 
-### Direct API Access
-
-```jsx
-import { useOxyApi } from '@oxyhq/services/ui';
+```typescript
+import { OxyServices } from '@oxyhq/services';
 
-function ProfileForm() {
-  const api = useOxyApi();
+const oxy = new OxyServices({
+  baseURL: 'http://localhost:3000'
+});
 
-  const updateProfile = async (data) => {
-    const user = await api.updateProfile(data);
-    // Token automatically included in request
-  };
+// Authenticate
+const response = await oxy.auth.login({
+  email: 'user@example.com',
+  password: 'password'
+});
 
-  return <button onClick={() => updateProfile({ name: 'New Name' })}>Update</button>;
-}
+// Get current user
+const user = await oxy.users.getCurrentUser();
 ```
 
-### Optional Authentication
+- [📚 Full Documentation](./docs/README.md)
+- [🚀 Quick Start Guide](./docs/quick-start.md)
+- [🔐 Core API Reference](./docs/core-api.md)
+- [💼 Integration Examples](./docs/examples/)
 
-```js
-import { createOptionalOxyAuth } from '@oxyhq/services/node';
+## UI Components
 
-// Works with or without authentication
-app.use('/api/content', createOptionalOxyAuth());
+Import and use pre-built React components:
 
-app.get('/api/content', (req, res) => {
-  if (req.user) {
-    res.json({ content: 'personalized', user: req.user });
-  } else {
-    res.json({ content: 'public' });
-  }
-});
+```typescript
+import { OxyProvider, Avatar, FollowButton } from '@oxyhq/services/ui';
 ```
 
-## Documentation
+## Package Exports
 
-### Zero-Config Guide
-- **[🚀 Zero-Config Setup Guide](./docs/zero-config.md)** - Complete guide with examples
+The library provides multiple entry points:
 
-### Advanced Documentation  
-- **[📚 Full Documentation](./docs/README.md)** - Complete system documentation
-- **[🚀 Quick Start Guide](./docs/quick-start.md)** - Traditional setup guide
-- **[🔐 Core API Reference](./docs/core-api.md)** - Detailed API documentation
-- **[💼 Integration Examples](./docs/examples/)** - More integration examples
-
-### UI Components
-- **[🎨 UI Components Guide](./docs/ui-components.md)** - React/RN component usage
-
-## Migration Guide
-
-### From Complex Setup
-
-**Before (complex setup):**
-```jsx
-import { OxyProvider, useOxy } from '@oxyhq/services/ui';
+```typescript
+// Core services only (Node.js/Express)
 import { OxyServices } from '@oxyhq/services';
 
-const oxy = new OxyServices({ baseURL: 'http://localhost:3001' });
+// UI components only (React/React Native)
+import { OxyProvider, Avatar } from '@oxyhq/services/ui';
 
-function App() {
-  return (
-    <OxyProvider oxyServices={oxy}>
-      <Dashboard />
-    </OxyProvider>
-  );
-}
-```
-
-**After (zero-config):**
-```jsx
-import { OxyZeroConfigProvider, useOxyZeroConfig } from '@oxyhq/services/ui';
-
-function App() {
-  return (
-    <OxyZeroConfigProvider>
-      <Dashboard />
-    </OxyZeroConfigProvider>
-  );
-}
+// Full package (Core + UI)
+import { OxyServices, OxyProvider } from '@oxyhq/services/full';
 ```
 
-Just change the provider and hook names - the API is nearly identical!
+## Zero-Config Express Router
 
-### Package Exports
-
-The library provides multiple entry points for different use cases:
+Quickly mount authentication routes in any Express app:
 
 ```typescript
-// Zero-config frontend
-import { OxyZeroConfigProvider, useOxyZeroConfig } from '@oxyhq/services/ui';
-
-// Zero-config backend
-import { createOxyAuth } from '@oxyhq/services/node';
-
-// Core services only (traditional)
-import { OxyServices } from '@oxyhq/services';
+import express from 'express';
+import { createAuth } from '@oxyhq/services/core';
 
-// Full package (Core + UI + Node)
-import { OxyServices, OxyProvider, createOxyAuth } from '@oxyhq/services/full';
+const app = express();
+app.use('/auth', createAuth({ baseURL: 'http://localhost:3000' }).middleware());
 ```
 
+This automatically provides sign-up, login, logout, refresh, and session management endpoints.
+
 ## Requirements
 
 - **Node.js** 16+ (for backend usage)
-- **React** 16.8+ (for React components)  
+- **React** 16.8+ (for React components)
 - **React Native** 0.60+ (for mobile components)
 - **TypeScript** 4.0+ (optional but recommended)
 
 ## Troubleshooting
 
-### Common Issues
+### FormData Issues in React Native/Expo
+
+If you encounter `ReferenceError: Property 'FormData' doesn't exist` when using Expo with Hermes engine:
+
+**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
 
-**"useOxyZeroConfig must be used within an OxyZeroConfigProvider"**
-- Make sure your component is wrapped with `<OxyZeroConfigProvider>`
+### Additional Dependencies
 
-**"req.user is undefined"**
-- Ensure the middleware is applied: `app.use('/api', createOxyAuth())`
-- Check that the client sends `Authorization: Bearer <token>` header
+For React Native projects, you may need to install peer dependencies:
+
+```bash
+npm install axios jwt-decode invariant
+```
+
+## Important for React Native Hermes Users
+
+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):
 
-**FormData Issues in React Native/Expo**  
-Add this import as the first line of your app entry file:
 ```js
 import 'react-native-url-polyfill/auto';
 ```
 
-### Getting Help
+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:
+
+```
+ReferenceError: Property 'FormData' doesn't exist, js engine: hermes
+```
 
-1. Check the [Zero-Config Guide](./docs/zero-config.md) for complete examples
-2. Review [Troubleshooting Guide](./docs/troubleshooting.md) for common issues  
-3. Open an issue on [GitHub](https://github.com/oxyhq/services/issues)
+---
 
 ## Development
 
@@ -352,17 +206,20 @@ npm install
 # Build the library
 npm run build
 
-# Run tests  
+# Run tests
 npm test
+
+# Development mode
+npm run dev
 ```
 
 ## Integration
 
 This library works with:
-- **[Oxy API](../api/)** - The companion authentication server
-- **Express.js** - Built-in zero-config middleware support  
-- **React/React Native** - Zero-config UI components and hooks
-- **Next.js** - SSR/SSG authentication support
+- **[Oxy API](../oxy-api/)** - The companion authentication server
+- **Express.js** - Built-in middleware support
+- **React/React Native** - UI components and hooks
+- **Next.js** - SSR/SSG authentication
 
 ## License