@truworth/twc-auth 1.0.0

package/README.md

@@ -0,0 +1,343 @@
+# TWC Auth Package
+
+A React authentication package for The Wellness Corner that provides a simple email/password login component with callback-based API integration.
+
+## Features
+
+- ✅ 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
+
+```bash
+npm install @truworth/twc-package-auth
+# or
+yarn add @truworth/twc-package-auth
+```
+
+## 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"
+    />
+  );
+}
+```
+
+### API Integration
+
+The package expects two API endpoints:
+
+#### 1. Email Exists Check (`/api/email-exists`)
+
+```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
+```
+
+### 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;
+}
+```
+
+## Development
+
+### Building the Package
+
+```bash
+npm run build
+```
+
+### Linking for Local Development
+
+```bash
+# In the auth package directory
+npm link
+
+# In your host application
+npm link @truworth/twc-package-auth
+```
+
+### Project Structure
+
+```
+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
+
+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;
+}
+
+// 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
+}
+```
+
+## Integration Pattern
+
+The host app handles all API calls and passes results back to the auth package via callbacks:
+
+```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([])
+  });
+};
+```
+
+## Build Commands
+
+```bash
+# Development
+npm run dev          # Start dev server
+npm run build        # Build package
+
+# Integration Testing
+cd ../twc-web-package-host
+npm run dev          # Test complete integration
+```