@truworth/twc-auth 1.1.0 → 1.2.2

package/README.md

@@ -1,343 +1,276 @@
-# TWC Auth Package
+# @truworth/twc-auth
 
-A React authentication package for The Wellness Corner that provides a simple email/password login component with callback-based API integration.
+Truworth Auth Module - A comprehensive authentication solution for React Native and Web applications.
 
-## Features
+## Table of Contents
 
-- ✅ Email/password authentication flow
-- ✅ Two-step verification (email check → password entry)
-- ✅ Callback-based API integration
-- ✅ TypeScript support
-- ✅ Lightweight and configurable
-- ✅ No external dependencies (except React)
+- [Installation](#installation)
+  - [React Native](#react-native)
+  - [Web](#web)
+- [Development](#development-configure-hot-reloading)
+  - [React Native Setup for Hot Reloading](#react-native-setup-for-hot-reloading)
+  - [Next.js Setup for Hot Reloading](#nextjs-setup-for-hot-reloading)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+- [Troubleshooting](#troubleshooting)
 
 ## Installation
 
-```bash
-npm install @truworth/twc-package-auth
-# or
-yarn add @truworth/twc-package-auth
+### React Native
+
+1. Install the package:
+
+   ```bash
+   npm install @truworth/twc-auth
+   ```
+
+2. Install peer dependencies:
+
+   ```bash
+   npm install \
+     @react-native-community/datetimepicker \
+     @react-navigation/native \
+     @react-navigation/native-stack \
+     @truworth/twc-rn-common \
+     @eva-design/eva \
+     @ui-kitten/components \
+     react-native-gesture-handler \
+     react-native-linear-gradient \
+     react-native-modalize \
+     react-native-reanimated \
+     react-native-screens \
+     react-native-safe-area-context \
+     react-native-svg \
+     react-native-vector-icons \
+     react@^18.2.0 \
+     react-native@^0.74.5
+   ```
+
+3. For iOS, install pods:
+
+   ```bash
+   npx pod-install
+   ```
+
+4. For React Native Reanimated, follow the [installation steps](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/installation/) if you haven't already.
+
+5. For React Navigation, wrap your app with `NavigationContainer` and ensure you've followed the [getting started guide](https://reactnavigation.org/docs/getting-started/).
+
+#### React Native Dependencies
+
+| Package                                | Version  |
+| -------------------------------------- | -------- |
+| @react-native-community/datetimepicker | >=8.1.1  |
+| @react-navigation/native               | >=6.1.17 |
+| @react-navigation/native-stack         | >=6.10.0 |
+| @truworth/twc-rn-common                | >=1.0.12 |
+| @ui-kitten/components                  | >=5.1.2  |
+| @eva-design/eva                        | >=2.2.0  |
+| lottie-react-native                    | >=6.7.2  |
+| react                                  | >=18.2.0 |
+| react-native                           | >=0.74.5 |
+| react-native-fast-image                | >=8.6.3  |
+| react-native-freshchat-sdk             | >=4.6.6  |
+| react-native-gesture-handler           | >=2.16.0 |
+| react-native-linear-gradient           | >=2.8.3  |
+| react-native-modalize                  | >=2.1.1  |
+| react-native-reanimated                | >=3.13.0 |
+| react-native-safe-area-context         | >=5.3.0  |
+| react-native-screens                   | >=3.31.1 |
+| react-native-svg                       | >=15.8.0 |
+| react-native-vector-icons              | >=9.2.0  |
+
+> Note: lottie-react-native, react-native-fast-image, and react-native-freshchat-sdk are optional and only needed if your app uses features that depend on them.
+
+#### Web Dependencies
+
+| Package                  | Version  |
+| ------------------------ | -------- |
+| @truworth/twc-web-common | ^1.0.11  |
+| @truworth/twc-web-design | ^1.9.0   |
+| antd                     | ^5.6.3   |
+| framer-motion            | ^12.6.2  |
+| lodash                   | ^4.17.21 |
+| lucide-react             | ^0.483.0 |
+| next                     | ^15.0.4  |
+| react                    | ^18.2.0  |
+| react-dom                | ^18.2.0  |
+
+### Web
+
+1. Install the package:
+
+   ```bash
+   npm install @truworth/twc-auth
+   ```
+
+2. Install peer dependencies:
+   ```bash
+   npm install \
+     next@^15.0.4 \
+     @truworth/twc-web-common@^1.0.11 \
+     @truworth/twc-web-design@^1.9.0 \
+     antd@^5.6.3 \
+     framer-motion@^12.6.2 \
+     lodash@^4.17.21 \
+     lucide-react@^0.483.0 \
+     react@^18.2.0 \
+     react-dom@^18.2.0
+   ```
+
+## Development: Configure Hot Reloading
+
+### React Native Setup for Hot Reloading
+
+#### Prerequisites
+
+Update main field in `package.json` to `./src/index.tsx`
+
+```diff
+//package.json
+{
+  ...
+- "main": "./build/src/index.js"
++ "main": "./src/index.tsx"
+  ...
+}
 ```
 
-## Usage
-
-### Basic Implementation
-
-```tsx
-import AuthLogin, { type EmailExistsCallback, type LoginSubmitCallback } from '@truworth/twc-package-auth';
-
-function LoginPage() {
-  const handleEmailExists: EmailExistsCallback = async (email: string) => {
-    try {
-      const response = await fetch('/api/email-exists', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ email })
-      });
-      
-      if (response.ok) {
-        return { exists: true };
-      } else if (response.status === 404) {
-        return { exists: false };
-      }
-      throw new Error('Network error');
-    } catch (error) {
-      throw error;
-    }
-  };
-
-  const handleLogin: LoginSubmitCallback = async (email: string, password: string) => {
-    const response = await fetch('/api/login', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email, password })
-    });
-    
-    if (!response.ok) {
-      throw new Error('Login failed');
-    }
-    
-    const data = await response.json();
-    return { token: data.token };
-  };
-
-  const handleSuccess = (token: string) => {
-    // Handle successful login
-    localStorage.setItem('token', token);
-    window.location.href = '/dashboard';
-  };
-
-  const handleError = (error: any) => {
-    // Handle errors
-    if (error.type === 'USER_NOT_FOUND') {
-      // Redirect to registration
-      window.location.href = `/register?email=${error.email}`;
-    } else {
-      console.error('Login error:', error);
-    }
-  };
-
-  return (
-    <AuthLogin
-      onEmailExists={handleEmailExists}
-      onLogin={handleLogin}
-      onSuccess={handleSuccess}
-      onError={handleError}
-      initialEmail=""
-      className="custom-login-styles"
-    />
-  );
+> Note: This change is for local development (hot reloading) only. Before publishing,
+> restore "main" to the built JS (e.g., ./build/src/index.js) or use the "exports" field
+> to map dev vs prod entry points.
+
+Add package to your main project's `package.json` file's `dependencies` field
+
+```diff
+//package.json
+{
+  ...
+  "dependencies": {
+    ...
++    "@truworth/twc-auth": "file:relative/path/to/package"
+    ...
+  }
+  ...
 }
 ```
 
-### API Integration
+#### React Native
 
-The package expects two API endpoints:
+Copy [`get-metro-config.js`](./get-metro-config.js) in your main project
 
-#### 1. Email Exists Check (`/api/email-exists`)
+Import `getMetroConfig` from `get-metro-config.js` and use it to merge with your project's metro config
 
-```typescript
-// POST /api/email-exists
-// Request: { email: string }
-// Response: { exists: boolean, loginType?: number }
-// 404 status for non-existent users
-```
-
-#### 2. Login (`/api/login`)
-
-```typescript
-// POST /api/login  
-// Request: { email: string, password: string }
-// Response: { token: string }
-// 400 status for invalid credentials
+```diff
+// mainProject/metro.config.js
++ const { getMetroConfig } = require('./get-metro-config')
++ const packageConfig = getMetroConfig(__dirname, 'relative/path/to/package')
+...
+- module.exports = mergeConfig(defaultConfig, config);
++ module.exports = mergeConfig(defaultConfig, config, packageConfig);
 ```
 
-### Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `onEmailExists` | `EmailExistsCallback` | ✅ | Function to check if email exists |
-| `onLogin` | `LoginSubmitCallback` | ✅ | Function to handle login |
-| `onSuccess` | `(token: string) => void` | ✅ | Callback when login succeeds |
-| `onError` | `(error: any) => void` | ❌ | Callback for error handling |
-| `initialEmail` | `string` | ❌ | Pre-fill email field |
-| `className` | `string` | ❌ | Additional CSS classes |
-
-### Error Handling
-
-The package provides structured error handling:
-
-```typescript
-interface LoginError {
-  type?: 'USER_NOT_FOUND' | 'INVALID_CREDENTIALS' | 'NETWORK_ERROR';
-  message: string;
-  email?: string; // Available for USER_NOT_FOUND errors
-  redirectToRegistration?: boolean;
+#### Next.js Setup for Hot Reloading
+
+Copy [`get-next-config.js`](./get-next-config.js) in your main project
+
+Import `getNextConfig` from `get-next-config.js` and use it to merge with your project's next config
+
+```diff
+// mainProject/next.config.js
++ const { getNextConfig } = require('./get-next-config')
++ const packageConfig = getNextConfig(__dirname, 'relative/path/to/package')
+...
+const nextConfig = {
+...
++ transpilePackages: [packageConfig.packageName],
+  webpack: (config) => {
+    ...
++   config.resolve.alias = {
++   ...config.resolve.alias,
++   ...packageConfig.webpackAlias
++   }
+    ...
+    return config;
+  },
 }
+...
+module.exports = nextConfig;
 ```
 
-## Development
-
-### Building the Package
-
-```bash
-npm run build
-```
-
-### Linking for Local Development
+## Usage
 
-```bash
-# In the auth package directory
-npm link
+### React Native
 
-# In your host application
-npm link @truworth/twc-package-auth
-```
+```tsx
+import React, { useEffect } from "react";
+import { createNativeStackNavigator } from "@react-navigation/native-stack";
+import { NavigationContainer } from "@react-navigation/native";
+import { AuthNavigator, AuthProvider } from "@truworth/twc-auth";
+import type { LoginResponse } from "@truworth/twc-auth";
+import Home from "./screens/Home";
+
+const { Navigator, Screen } = createNativeStackNavigator();
+
+const ExampleAppNavigator = () => {
+  const onLogin = async (result: LoginResponse) => {
+    //TODO: Store token in secure storage & redirect to home screen
+  };
 
-### Project Structure
+  return (
+    <NavigationContainer>
+      <AuthProvider onLogin={onLogin}>
+        <Navigator screenOptions={{ headerShown: false }}>
+          <Screen name="AuthNavigator" component={AuthNavigator} />
+        </Navigator>
+      </AuthProvider>
+    </NavigationContainer>
+  );
+};
 
+export default ExampleAppNavigator;
 ```
-src/
-├── components/
-│   └── AuthLogin.tsx     # Main login component
-├── types.ts              # TypeScript type definitions
-└── index.ts             # Package exports
-```
-
-## Integration Example
-
-See the complete integration example in the host application:
-
-- **API Routes**: `pages/api/email-exists.ts` and `pages/api/login.ts`
-- **Login Page**: `pages/login.tsx`
-- **Index Redirect**: `pages/index.tsx`
 
-## Migration from Hardcoded Token
+### Web (Next.js)
 
-The package replaces hardcoded token entry with proper authentication:
-
-**Before**: Manual token entry via `_enter-token.tsx`
-**After**: Email/password login with proper backend integration
-
-## Styling
-
-The component uses minimal inline styles and accepts a `className` prop for customization. Default styles include:
-
-- Responsive design
-- Form validation states
-- Loading indicators
-- Error messages
-
-## License
-
-Private package for The Wellness Corner internal use.
-
-# TWC Auth Package Development
-
-## Project Overview
-A comprehensive authentication package (`@truworth/twc-package-auth`) built for TWC partner integrations. The package provides a complete login/registration UI that can be integrated into host applications.
-
-## 🚀 **Current Status: Phase 2 - Complete UI Implementation**
-
-### ✅ **Phase 1 Completed:**
-- Basic email/password login working
-- Token management and auth context integration  
-- Host app successfully using auth package
-- API callback system functional
-
-### 🔄 **Phase 2 In Progress:**
-Implementing complete production UI from `/Users/soumik.acharjee/twc-repos/twc-v2/pages/login/index.tsx`
-
-**Features to Implement:**
-1. **Complete LoginForm Component**
-   - Email validation step with proper UI
-   - Password entry step with validation
-   - Back navigation between steps
-   - Forgot password integration
-
-2. **SSO Login Flow**
-   - Organization search with autocomplete
-   - SSO initiation and redirect handling
-   - Multi-step UI with transitions
-
-3. **OTP/Mobile Sign-in**
-   - OTP request and verification
-   - Mobile number handling
-   - Modal-based UI flow
-
-4. **Password Reset Flow**
-   - Email-based reset initiation
-   - OTP verification for reset
-   - New password setting
-
-5. **Enhanced UI/UX**
-   - Left panel with background image and carousel
-   - Smooth transitions between states
-   - Proper loading states and error handling
-   - Responsive design matching production
-
-**Excluded Features:**
-- ❌ Google Sign-in (removed)
-- ❌ Facebook Sign-in (removed)
-
-## Architecture Principles
-
-### **Pure UI Package with Callbacks**
-- Auth package contains ONLY UI components and logic
-- ALL API calls handled by host application via callbacks
-- No direct API dependencies in the package
-- Host app passes callback functions for all backend operations
-
-### **Production Reference**
-- **Source:** `/Users/soumik.acharjee/twc-repos/twc-v2/pages/login/index.tsx`
-- **Target:** `/Users/soumik.acharjee/twc-repos/twc-web-package-host`
-- **Design System:** `@truworth/twc-web-design` for exact UI match
-
-## Development Tasks Breakdown
-
-### **Task 1: Enhanced Types & Interfaces**
-- [ ] Update `AuthLoginProps` with all callback functions
-- [ ] Add interfaces for SSO, OTP, and Reset Password
-- [ ] Define error types for different scenarios
-
-### **Task 2: Complete LoginForm Component**
-- [ ] Implement two-step email/password flow
-- [ ] Add form validation and error states
-- [ ] Integrate forgot password trigger
-
-### **Task 3: SSO Login Component**
-- [ ] Build organization search with autocomplete
-- [ ] Create SSO selection and initiation UI
-- [ ] Handle SSO redirect flow
-
-### **Task 4: OTP/Mobile Sign-in Component**
-- [ ] Create modal-based OTP interface
-- [ ] Implement OTP request and verification
-- [ ] Add mobile number validation
-
-### **Task 5: Password Reset Component**
-- [ ] Build reset password modal
-- [ ] Create OTP verification for reset
-- [ ] Add new password setting form
-
-### **Task 6: Main Auth Component Integration**
-- [ ] Create state management for different flows
-- [ ] Implement smooth transitions between states
-- [ ] Add comprehensive error handling
-
-### **Task 7: Host App Integration**
-- [ ] Update login.tsx with all callback handlers
-- [ ] Create API route handlers for new endpoints
-- [ ] Test complete integration flow
-
-## Current Implementation Status
-
-```typescript
-// Current working callbacks
-interface AuthLoginProps {
-  onEmailExists: (email: string) => void;
-  onLogin: (email: string, password: string) => void;
-  onSuccess: (token: string) => void;
-  onError?: (error: AuthError | any) => void;
-  makeRequest: (params: MakeRequestParams) => void;
-}
+```tsx
+// pages/_app.tsx
+import { AuthProvider } from "@truworth/twc-auth";
+import type { LoginResponse } from "@truworth/twc-auth";
+import type { AppProps } from "next/app";
+
+export default function App({ Component, pageProps }: AppProps) {
+  const onLogin = (result: LoginResponse) => {
+    //TODO: Store token in secure storage & redirect to home screen
+  };
 
-// Next: Expand to include all production features
-interface CompleteAuthLoginProps extends AuthLoginProps {
-  onSSOSearch: (query: string, callback: (results: any[]) => void) => void;
-  onSSOLogin: (clientId: string, callback: (authUrl: string) => void) => void;
-  onOTPRequest: (email: string, callback: (success: boolean) => void) => void;
-  onOTPVerify: (email: string, otp: string, callback: (token: string) => void) => void;
-  onPasswordReset: (email: string, callback: (success: boolean) => void) => void;
-  // ... additional callbacks
+  return (
+    <AuthProvider onLogin={onLogin}>
+      <Component {...pageProps} />
+    </AuthProvider>
+  );
 }
 ```
 
-## Integration Pattern
+## API Reference
 
-The host app handles all API calls and passes results back to the auth package via callbacks:
+### Hooks
+
+#### `useAuthContext()`
 
 ```typescript
-// Host app implementation
-const handleSSOSearch = (query: string, callback: (results: any[]) => void) => {
-  makeRequest({
-    url: '/auth/login-sso/search-clients',
-    method: 'POST',
-    data: { query },
-    onSuccess: (data) => callback(data),
-    onError: (err) => callback([])
-  });
-};
+const { onLogin, logout, onLaunchAuthSession, LogoComponent } = useAuthContext();
 ```
 
-## Build Commands
+## Troubleshooting
 
-```bash
-# Development
-npm run dev          # Start dev server
-npm run build        # Build package
+### Common Issues
 
-# Integration Testing
-cd ../twc-web-package-host
-npm run dev          # Test complete integration
-```
+1. **Module not found**
+
+   - Ensure all peer dependencies are installed
+   - Clear Metro bundler cache: `npx react-native start --reset-cache`
+   - For Next.js, remove `.next` and restart: `rm -rf .next && next dev`
+   - For React Native: Ensure `babel.config.js` includes `plugins: ['react-native-reanimated/plugin']` as the last plugin
+   - For Next.js with Babel: Add `plugins: ['react-native-reanimated/plugin']` to your Babel config if using Babel (not needed with default SWC)
+   - For iOS CocoaPods issues: First try `cd ios && pod install` or clean the build folder in Xcode. Only use `pod deintegrate` as a last resort if other steps fail.