@oxyhq/services 5.7.4 → 5.8.1

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 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.
+A TypeScript client library for the Oxy API providing authentication, user management, and UI components for React and React Native applications.
 
 ## Table of Contents
 
-- [Zero-Config Guide](#-zero-config-quick-start)  
 - [Features](#features)
-- [Installation](#installation)
-- [Complete Examples](#complete-examples)
-- [Advanced Usage](#advanced-usage)
+- [Quick Start](#quick-start)
 - [Documentation](#documentation)
-- [Migration Guide](#migration-guide)
+- [UI Components](#ui-components)
+- [Package Exports](#package-exports)
+- [Requirements](#requirements)
+- [Development](#development)
+- [Integration](#integration)
+- [License](#license)
 
 ## Features
 
-- 🚀 **Zero-Config**: Get authentication working in 2-3 lines of code
-- 🔐 **Automatic Token Management**: Tokens saved, restored, and refreshed automatically
+- 🔐 **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  
+- 🎨 **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
+- 🚀 **Performance**: Optimized with automatic caching and state management
 
-## Installation
+## Quick Start
 
 ```bash
 npm install @oxyhq/services
 ```
 
-## Complete Examples
+### Streamlined Authentication (Recommended)
 
-### React Application
-
-**App.js**
-```jsx
-import React from 'react';
-import { OxyZeroConfigProvider } from '@oxyhq/services/ui';
-import Dashboard from './Dashboard';
+```typescript
+import { OxyProvider, useOxy } from '@oxyhq/services';
 
-export default function App() {
+function App() {
   return (
-    <OxyZeroConfigProvider>
-      <Dashboard />
-    </OxyZeroConfigProvider>
+    <OxyProvider baseURL="https://api.example.com">
+      <YourApp />
+    </OxyProvider>
   );
 }
+
+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();
+  };
+}
 ```
 
-**Dashboard.js**
-```jsx
-import React from 'react';
-import { useOxyZeroConfig } from '@oxyhq/services/ui';
+### With Built-in Bottom Sheet
 
-export default function Dashboard() {
-  const { user, login, logout, isAuthenticated, isLoading } = useOxyZeroConfig();
+The OxyProvider now includes a built-in gorhom bottom sheet - no manual setup required!
 
-  if (isLoading) return <div>Loading...</div>;
+```typescript
+import { OxyProvider, useOxy, OxySignInButton } from '@oxyhq/services';
 
-  if (!isAuthenticated) {
-    return (
-      <div>
-        <h1>Please log in</h1>
-        <button onClick={() => login('demo', 'password')}>Login</button>
-      </div>
-    );
-  }
+function App() {
+  return (
+    <OxyProvider 
+      baseURL="https://api.example.com"
+      initialScreen="SignIn"
+      theme="light"
+    >
+      <YourApp />
+    </OxyProvider>
+  );
+}
 
+function Component() {
+  const { showBottomSheet } = useOxy();
+  
+  const openSignIn = () => {
+    showBottomSheet('SignIn'); // Works automatically!
+  };
+  
   return (
     <div>
-      <h1>Welcome, {user.username}!</h1>
-      <button onClick={logout}>Logout</button>
+      <button onClick={openSignIn}>Sign In</button>
+      <OxySignInButton /> {/* Also works automatically! */}
     </div>
   );
 }
 ```
 
-### Express.js Backend
+### Traditional Usage
 
-**server.js**
-```js
-import express from 'express';
-import { createOxyAuth } from '@oxyhq/services/node';
-
-const app = express();
-app.use(express.json());
+```typescript
+import { OxyServices } from '@oxyhq/services';
 
-// Public routes
-app.get('/', (req, res) => {
-  res.json({ message: 'Public endpoint' });
+const oxy = new OxyServices({
+  baseURL: 'http://localhost:3000'
 });
 
-// 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 
-  });
+// Authenticate
+const response = await oxy.auth.login({
+  email: 'user@example.com',
+  password: 'password'
 });
 
-app.listen(3000, () => console.log('Server running on port 3000'));
-```
-
-### Next.js Full-Stack
-
-**pages/_app.js**
-```jsx
-import { OxyZeroConfigProvider } from '@oxyhq/services/ui';
-
-export default function App({ Component, pageProps }) {
-  return (
-    <OxyZeroConfigProvider>
-      <Component {...pageProps} />
-    </OxyZeroConfigProvider>
-  );
-}
-```
-
-**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 });
-}
+// Get current user
+const user = await oxy.users.getCurrentUser();
 ```
 
-## Advanced Usage
-
-### Configuration Options
-
-**Frontend**
-```jsx
-<OxyZeroConfigProvider
-  apiUrl="https://your-api.com"
-  onAuthChange={(user) => console.log('Auth changed:', user)}
->
-  <App />
-</OxyZeroConfigProvider>
-```
-
-**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 });
-  }
-}));
-```
-
-### Direct API Access
-
-```jsx
-import { useOxyApi } from '@oxyhq/services/ui';
-
-function ProfileForm() {
-  const api = useOxyApi();
-
-  const updateProfile = async (data) => {
-    const user = await api.updateProfile(data);
-    // Token automatically included in request
-  };
+## Documentation
 
-  return <button onClick={() => updateProfile({ name: 'New Name' })}>Update</button>;
-}
-```
+For comprehensive documentation, API reference, and examples:
 
-### Optional Authentication
+- [📚 Full Documentation](./docs/README.md)
+- [🚀 Quick Start Guide](./docs/quick-start.md)
+- [🔐 Core API Reference](./docs/core-api.md)
+- [⚡ Streamlined Authentication](./docs/core-api.md#streamlined-authentication) - **NEW!**
+- [💼 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
-
-### Zero-Config Guide
-- **[🚀 Zero-Config Setup Guide](./docs/zero-config.md)** - Complete guide with examples
-
-### 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
+## Package Exports
 
-## Migration Guide
+The library provides multiple entry points:
 
-### 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>
-  );
-}
+// Full package (Core + UI)
+import { OxyServices, OxyProvider } from '@oxyhq/services/full';
 ```
 
-**After (zero-config):**
-```jsx
-import { OxyZeroConfigProvider, useOxyZeroConfig } from '@oxyhq/services/ui';
+## Zero-Config Express Router
 
-function App() {
-  return (
-    <OxyZeroConfigProvider>
-      <Dashboard />
-    </OxyZeroConfigProvider>
-  );
-}
-```
-
-Just change the provider and hook names - the API is nearly identical!
-
-### 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
+
+### Additional Dependencies
+
+For React Native projects, you may need to install peer dependencies:
 
-**"useOxyZeroConfig must be used within an OxyZeroConfigProvider"**
-- Make sure your component is wrapped with `<OxyZeroConfigProvider>`
+```bash
+npm install axios jwt-decode invariant
+```
 
-**"req.user is undefined"**
-- Ensure the middleware is applied: `app.use('/api', createOxyAuth())`
-- Check that the client sends `Authorization: Bearer <token>` header
+## 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:
 
-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)
+```
+ReferenceError: Property 'FormData' doesn't exist, js engine: hermes
+```
+
+---
 
 ## 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
 

package/lib/commonjs/core/index.js

@@ -516,9 +516,17 @@ class OxyServices {
    */
   async getCurrentUser() {
     try {
+      console.log('OxyServices: Fetching current user...');
       const res = await this.client.get('/users/me');
+      console.log('OxyServices: Current user response:', {
+        hasUser: !!res.data,
+        userLinksMetadata: res.data?.linksMetadata,
+        userLinks: res.data?.links,
+        userWebsite: res.data?.website
+      });
       return res.data;
     } catch (error) {
+      console.error('OxyServices: Error fetching current user:', error);
       throw this.handleError(error);
     }
   }
@@ -530,9 +538,12 @@ class OxyServices {
    */
   async updateProfile(updates) {
     try {
+      console.log('OxyServices: Updating profile with:', updates);
       const res = await this.client.put('/users/me', updates);
+      console.log('OxyServices: Profile update response:', res.data);
       return res.data;
     } catch (error) {
+      console.error('OxyServices: Error updating profile:', error);
       throw this.handleError(error);
     }
   }
@@ -1246,10 +1257,13 @@ class OxyServices {
    * @returns Array of user sessions
    */
   async getSessionsBySessionId(sessionId) {
+    console.log('getSessionsBySessionId called with sessionId:', sessionId);
     try {
       const res = await this.client.get(`/secure-session/sessions/${sessionId}`);
+      console.log('getSessionsBySessionId response:', res.data);
       return res.data.sessions;
     } catch (error) {
+      console.error('getSessionsBySessionId error:', error);
       throw this.handleError(error);
     }
   }
@@ -1718,6 +1732,164 @@ class OxyServices {
       throw this.handleError(error);
     }
   }
+
+  /**
+   * Fetch metadata for a URL (title, description, image)
+   * @param url - The URL to fetch metadata for
+   * @returns Promise with metadata object
+   */
+  async fetchLinkMetadata(url) {
+    try {
+      const response = await this.client.post('/link-metadata/fetch-metadata', {
+        url
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Search for locations using the enhanced location search API
+   * @param query - Search query string
+   * @param limit - Maximum number of results (default: 5)
+   * @param countrycodes - Optional country codes filter (e.g., "us,ca")
+   * @returns Promise with array of location results
+   */
+  async searchLocations(query, limit = 5, countrycodes) {
+    try {
+      const params = new URLSearchParams({
+        query,
+        limit: limit.toString()
+      });
+      if (countrycodes) {
+        params.append('countrycodes', countrycodes);
+      }
+      const res = await this.client.get(`/location-search/search?${params.toString()}`);
+      return res.data.results;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Get detailed information about a specific location by coordinates
+   * @param lat - Latitude
+   * @param lon - Longitude
+   * @returns Promise with detailed location information
+   */
+  async getLocationDetails(lat, lon) {
+    try {
+      const res = await this.client.get(`/location-search/details?lat=${lat}&lon=${lon}`);
+      return res.data.result;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Find locations near a point using geospatial queries
+   * @param lat - Latitude
+   * @param lon - Longitude
+   * @param maxDistance - Maximum distance in meters (default: 10000)
+   * @param limit - Maximum number of results (default: 10)
+   * @param skip - Number of results to skip (default: 0)
+   * @returns Promise with nearby locations
+   */
+  async findLocationsNear(lat, lon, maxDistance = 10000, limit = 10, skip = 0) {
+    try {
+      const params = new URLSearchParams({
+        lat: lat.toString(),
+        lon: lon.toString(),
+        maxDistance: maxDistance.toString(),
+        limit: limit.toString(),
+        skip: skip.toString()
+      });
+      const res = await this.client.get(`/location-search/near?${params.toString()}`);
+      return res.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Search locations in database by text
+   * @param query - Search query
+   * @param limit - Maximum number of results (default: 10)
+   * @param skip - Number of results to skip (default: 0)
+   * @param type - Filter by location type
+   * @param country - Filter by country
+   * @param city - Filter by city
+   * @returns Promise with search results
+   */
+  async searchLocationsInDB(query, limit = 10, skip = 0, type, country, city) {
+    try {
+      const params = new URLSearchParams({
+        query,
+        limit: limit.toString(),
+        skip: skip.toString()
+      });
+      if (type) params.append('type', type);
+      if (country) params.append('country', country);
+      if (city) params.append('city', city);
+      const res = await this.client.get(`/location-search/db-search?${params.toString()}`);
+      return res.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Get location statistics
+   * @returns Promise with location statistics
+   */
+  async getLocationStats() {
+    try {
+      const res = await this.client.get('/location-search/stats');
+      return res.data.stats;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Get cache statistics
+   * @returns Promise with cache statistics
+   */
+  async getLocationCacheStats() {
+    try {
+      const res = await this.client.get('/location-search/cache/stats');
+      return res.data.stats;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Clear location cache
+   * @returns Promise with success status
+   */
+  async clearLocationCache() {
+    try {
+      const res = await this.client.delete('/location-search/cache');
+      return res.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+
+  /**
+   * Get performance statistics
+   * @returns Promise with performance statistics
+   */
+  async getLocationPerformanceStats() {
+    try {
+      const res = await this.client.get('/location-search/performance');
+      return res.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
 }
 
 // Default export for backward compatibility