@oxyhq/services 5.7.2 → 5.7.4

package/README.md

@@ -1,137 +1,347 @@
 # OxyHQServices
 
-A TypeScript client library for the Oxy API providing authentication, user management, and UI components for React and React Native applications.
+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 Quick Start
+
+### Frontend (React/Next.js) - 2 lines of code:
+
+```jsx
+import { OxyZeroConfigProvider, useOxyZeroConfig } from '@oxyhq/services/ui';
+
+// 1. Wrap your app
+function App() {
+  return (
+    <OxyZeroConfigProvider>
+      <YourApp />
+    </OxyZeroConfigProvider>
+  );
+}
+
+// 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>;
+  }
+  
+  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)
-- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Complete Examples](#complete-examples)
+- [Advanced Usage](#advanced-usage)
 - [Documentation](#documentation)
-- [UI Components](#ui-components)
-- [Package Exports](#package-exports)
-- [Requirements](#requirements)
-- [Development](#development)
-- [Integration](#integration)
-- [License](#license)
+- [Migration Guide](#migration-guide)
 
 ## Features
 
-- 🔐 **Authentication**: JWT-based auth with automatic token refresh
+- 🚀 **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
+- 🎨 **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
 
-## Quick Start
+## Installation
 
 ```bash
 npm install @oxyhq/services
 ```
 
-```typescript
-import { OxyServices } from '@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 (
+    <div>
+      <h1>Welcome, {user.username}!</h1>
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+### Express.js Backend
+
+**server.js**
+```js
+import express from 'express';
+import { createOxyAuth } from '@oxyhq/services/node';
 
-const oxy = new OxyServices({
-  baseURL: 'http://localhost:3000'
+const app = express();
+app.use(express.json());
+
+// Public routes
+app.get('/', (req, res) => {
+  res.json({ message: 'Public endpoint' });
 });
 
-// Authenticate
-const response = await oxy.auth.login({
-  email: 'user@example.com',
-  password: 'password'
+// Protected routes - zero config!
+app.use('/api', createOxyAuth());
+
+// req.user is automatically available
+app.get('/api/profile', (req, res) => {
+  res.json({ 
+    message: `Hello ${req.user.username}!`,
+    user: req.user 
+  });
 });
 
-// Get current user
-const user = await oxy.users.getCurrentUser();
+app.listen(3000, () => console.log('Server running on port 3000'));
 ```
 
-## Documentation
+### Next.js Full-Stack
 
-For comprehensive documentation, API reference, and examples:
+**pages/_app.js**
+```jsx
+import { OxyZeroConfigProvider } from '@oxyhq/services/ui';
 
-- [📚 Full Documentation](./docs/README.md)
-- [🚀 Quick Start Guide](./docs/quick-start.md)
-- [🔐 Core API Reference](./docs/core-api.md)
-- [💼 Integration Examples](./docs/examples/)
+export default function App({ Component, pageProps }) {
+  return (
+    <OxyZeroConfigProvider>
+      <Component {...pageProps} />
+    </OxyZeroConfigProvider>
+  );
+}
+```
 
-## UI Components
+**pages/api/user.js**
+```js
+import { createOxyAuth } from '@oxyhq/services/node';
+
+const auth = createOxyAuth();
+
+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 });
+}
+```
 
-Import and use pre-built React components:
+## Advanced Usage
 
-```typescript
-import { OxyProvider, Avatar, FollowButton } from '@oxyhq/services/ui';
+### Configuration Options
+
+**Frontend**
+```jsx
+<OxyZeroConfigProvider
+  apiUrl="https://your-api.com"
+  onAuthChange={(user) => console.log('Auth changed:', user)}
+>
+  <App />
+</OxyZeroConfigProvider>
 ```
 
-## Package Exports
+**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 });
+  }
+}));
+```
 
-The library provides multiple entry points:
+### Direct API Access
 
-```typescript
-// Core services only (Node.js/Express)
-import { OxyServices } from '@oxyhq/services';
+```jsx
+import { useOxyApi } from '@oxyhq/services/ui';
+
+function ProfileForm() {
+  const api = useOxyApi();
 
-// UI components only (React/React Native)
-import { OxyProvider, Avatar } from '@oxyhq/services/ui';
+  const updateProfile = async (data) => {
+    const user = await api.updateProfile(data);
+    // Token automatically included in request
+  };
 
-// Full package (Core + UI)
-import { OxyServices, OxyProvider } from '@oxyhq/services/full';
+  return <button onClick={() => updateProfile({ name: 'New Name' })}>Update</button>;
+}
 ```
 
-## Zero-Config Express Router
+### Optional Authentication
 
-Quickly mount authentication routes in any Express app:
+```js
+import { createOptionalOxyAuth } from '@oxyhq/services/node';
 
-```typescript
-import express from 'express';
-import { createAuth } from '@oxyhq/services/core';
+// Works with or without authentication
+app.use('/api/content', createOptionalOxyAuth());
 
-const app = express();
-app.use('/auth', createAuth({ baseURL: 'http://localhost:3000' }).middleware());
+app.get('/api/content', (req, res) => {
+  if (req.user) {
+    res.json({ content: 'personalized', user: req.user });
+  } else {
+    res.json({ content: 'public' });
+  }
+});
 ```
 
-This automatically provides sign-up, login, logout, refresh, and session management endpoints.
+## Documentation
 
-## Requirements
+### Zero-Config Guide
+- **[🚀 Zero-Config Setup Guide](./docs/zero-config.md)** - Complete guide with examples
 
-- **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)
+### 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
 
-## Troubleshooting
+### UI Components
+- **[🎨 UI Components Guide](./docs/ui-components.md)** - React/RN component usage
 
-### FormData Issues in React Native/Expo
+## Migration Guide
 
-If you encounter `ReferenceError: Property 'FormData' doesn't exist` when using Expo with Hermes engine:
+### From Complex Setup
 
-**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
+**Before (complex setup):**
+```jsx
+import { OxyProvider, useOxy } from '@oxyhq/services/ui';
+import { OxyServices } from '@oxyhq/services';
 
-### Additional Dependencies
+const oxy = new OxyServices({ baseURL: 'http://localhost:3001' });
 
-For React Native projects, you may need to install peer dependencies:
+function App() {
+  return (
+    <OxyProvider oxyServices={oxy}>
+      <Dashboard />
+    </OxyProvider>
+  );
+}
+```
 
-```bash
-npm install axios jwt-decode invariant
+**After (zero-config):**
+```jsx
+import { OxyZeroConfigProvider, useOxyZeroConfig } from '@oxyhq/services/ui';
+
+function App() {
+  return (
+    <OxyZeroConfigProvider>
+      <Dashboard />
+    </OxyZeroConfigProvider>
+  );
+}
 ```
 
-## Important for React Native Hermes Users
+Just change the provider and hook names - the API is nearly identical!
 
-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):
+### Package Exports
 
-```js
-import 'react-native-url-polyfill/auto';
-```
+The library provides multiple entry points for different use cases:
+
+```typescript
+// Zero-config frontend
+import { OxyZeroConfigProvider, useOxyZeroConfig } from '@oxyhq/services/ui';
 
-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:
+// Zero-config backend
+import { createOxyAuth } from '@oxyhq/services/node';
 
+// Core services only (traditional)
+import { OxyServices } from '@oxyhq/services';
+
+// Full package (Core + UI + Node)
+import { OxyServices, OxyProvider, createOxyAuth } from '@oxyhq/services/full';
 ```
-ReferenceError: Property 'FormData' doesn't exist, js engine: hermes
+
+## Requirements
+
+- **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)
+
+## Troubleshooting
+
+### Common Issues
+
+**"useOxyZeroConfig must be used within an OxyZeroConfigProvider"**
+- Make sure your component is wrapped with `<OxyZeroConfigProvider>`
+
+**"req.user is undefined"**
+- Ensure the middleware is applied: `app.use('/api', createOxyAuth())`
+- Check that the client sends `Authorization: Bearer <token>` header
+
+**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
+
+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
 
@@ -142,20 +352,17 @@ 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](../oxy-api/)** - The companion authentication server
-- **Express.js** - Built-in middleware support
-- **React/React Native** - UI components and hooks
-- **Next.js** - SSR/SSG authentication
+- **[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
 
 ## License
 

package/lib/commonjs/core/index.js

@@ -1396,22 +1396,6 @@ class OxyServices {
           });
         }
 
-        // Validate JWT format before attempting to decode
-        if (!this.isValidJwtFormat(token)) {
-          const error = {
-            message: 'Invalid token format',
-            code: 'INVALID_TOKEN_FORMAT',
-            status: 401
-          };
-          if (onError) {
-            return onError(error);
-          }
-          return res.status(401).json({
-            message: 'Invalid token format',
-            code: 'INVALID_TOKEN_FORMAT'
-          });
-        }
-
         // Create a temporary OxyServices instance with the token to validate it
         const tempOxyServices = new OxyServices({
           baseURL: this.client.defaults.baseURL || ''
@@ -1441,8 +1425,6 @@ class OxyServices {
           const decoded = (0, _jwtDecode.jwtDecode)(token);
           userId = decoded.userId || decoded.id;
         } catch (decodeError) {
-          console.error('JWT decode error:', decodeError);
-          console.error('Token being decoded:', token.substring(0, 20) + '...');
           const error = {
             message: 'Invalid token payload',
             code: 'INVALID_PAYLOAD',
@@ -1520,14 +1502,6 @@ class OxyServices {
         };
       }
 
-      // Validate JWT format before attempting to decode
-      if (!this.isValidJwtFormat(token)) {
-        return {
-          valid: false,
-          error: 'Invalid token format'
-        };
-      }
-
       // Create a temporary OxyServices instance with the token
       const tempOxyServices = new OxyServices({
         baseURL: this.client.defaults.baseURL || ''
@@ -1584,37 +1558,6 @@ class OxyServices {
     }
   }
 
-  /**
-   * Validate JWT token format
-   * @param token - The token to validate
-   * @returns Boolean indicating if the token has valid JWT format
-   */
-  isValidJwtFormat(token) {
-    if (!token || typeof token !== 'string') {
-      return false;
-    }
-
-    // JWT tokens should have 3 parts separated by dots
-    const parts = token.split('.');
-    if (parts.length !== 3) {
-      return false;
-    }
-
-    // Each part should be a valid base64 string
-    try {
-      parts.forEach(part => {
-        if (!part || part.trim() === '') {
-          throw new Error('Empty part');
-        }
-        // Try to decode base64 (this will throw if invalid)
-        Buffer.from(part, 'base64');
-      });
-      return true;
-    } catch (error) {
-      return false;
-    }
-  }
-
   /**
    * Centralized error handling
    * @private