central-auth-js-sdk 1.0.10

package/INTEGRATION_GUIDE.md

@@ -0,0 +1,473 @@
+# Central Auth SDK — Integration Guide
+
+This guide explains how to **pull the SDK** and use **all SDK functionalities** in your application.
+
+---
+
+## 1. Pull / install the SDK
+
+```bash
+npm install central-auth-sdk
+```
+
+Use in your app (with a bundler such as Vite, Webpack, or Parcel):
+
+```javascript
+import { initializeAuth, startSignup, startLogin } from 'central-auth-sdk';
+import 'central-auth-sdk/styles.css';
+```
+
+Or in HTML (if your tool resolves node_modules):
+
+```html
+<link rel="stylesheet" href="./node_modules/central-auth-sdk/styles.css" />
+<script type="module">
+  import { startSignup, startLogin } from 'central-auth-sdk';
+  // ...
+</script>
+```
+
+---
+
+## 2. Minimal setup
+
+You need:
+
+1. A **container** element in the DOM where the SDK will render.
+2. The **SDK CSS** loaded (so the UI looks correct).
+3. A call to **`startSignup`** or **`startLogin`** with at least `container` and **`env`** (which backend to use: `local`, `dev`, `staging`, or `prod`). **`appIdentifier`** is optional; include it only if your backend expects it for OAuth or login APIs.
+
+**Minimal signup example:**
+
+```html
+<div id="auth-container"></div>
+<link rel="stylesheet" href="central-auth-sdk/styles.css" />
+<script type="module">
+  import { startSignup } from 'central-auth-sdk';
+
+  const instance = startSignup({
+    container: '#auth-container',
+    env: 'dev',
+    appIdentifier: 'your-app-id',
+  });
+</script>
+```
+
+**Minimal login example:**
+
+```html
+<div id="auth-container"></div>
+<link rel="stylesheet" href="central-auth-sdk/styles.css" />
+<script type="module">
+  import { startLogin } from 'central-auth-sdk';
+
+  const instance = startLogin({
+    container: '#auth-container',
+    env: 'dev',
+    appIdentifier: 'your-app-id',
+    loginMethods: { emailPassword: true },
+  });
+</script>
+```
+
+---
+
+## 3. All SDK functions
+
+| Function | Purpose |
+|----------|--------|
+| **`initializeAuth(config)`** | (Optional) Set default config once; `startSignup` / `startLogin` can override per call. |
+| **`startSignup(config)`** | Run the sign-up flow in the given container. |
+| **`startLogin(config)`** | Run the login flow in the given container. |
+
+You can use **only** `startSignup` and `startLogin` and pass full config each time. Or call **`initializeAuth`** once and then call **`auth.startSignup({})`** / **`auth.startLogin({})`** so they use the stored defaults.
+
+---
+
+## 4. initializeAuth(config)
+
+Call once (e.g. at app load) to set defaults. Returns `{ startSignup, startLogin, getConfig }`.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `env` | string | `'local'` | Environment: `'local'` \| `'dev'` \| `'staging'` \| `'prod'`. SDK uses the predefined API URL for that env. |
+| `appIdentifier` | string | — | Optional. When provided, sent with OAuth and login-related API requests; omit to not send `app_identifier`. |
+| `defaultContainer` | string \| HTMLElement | — | Default container; can override in `startSignup` / `startLogin` |
+| `loginMethods` | object | — | Default login methods (see Login config) |
+| `frsAsSecondFactor` | boolean | `false` | Default: require face verification after primary auth |
+| `enableFaceRegistration` | boolean | `true` | Whether sign-up includes face registration step |
+
+**Environments:** The SDK uses only `env` to choose the API base URL:
+
+| `env`     | API base URL |
+|-----------|----------------|
+| `local`   | `http://localhost:8080` |
+| `dev`     | `https://central-auth-dev.soham.ai/apis` |
+| `staging` | `https://central-auth-staging.soham.ai/apis` |
+| `prod`    | `https://central-auth.soham.ai/apis` |
+
+**Example:**
+
+```javascript
+import { initializeAuth } from 'central-auth-sdk';
+
+const auth = initializeAuth({
+  env: 'dev',  // uses https://central-auth-dev.soham.ai/apis
+  appIdentifier: 'my-app',
+  defaultContainer: '#auth-container',
+  loginMethods: {
+    emailPassword: true,
+    emailOtp: true,
+    social: { google: true, microsoft: true },
+  },
+  frsAsSecondFactor: true,
+});
+
+// Later:
+auth.startSignup({});
+auth.startLogin({ onSignUp: () => showSignup() });
+```
+
+---
+
+## 5. startSignup(config)
+
+Starts the **sign-up flow** (email + name → verify → mobile → verify → password → face → success). The first screen collects first name, last name, and email.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `container` | string \| HTMLElement | yes* | Where to render (*or set `defaultContainer` in `initializeAuth`) |
+| `env` | string | no | Environment: `'local'` \| `'dev'` \| `'staging'` \| `'prod'` (default from init or `'local'`) |
+| `appIdentifier` | string | no | Optional. When provided, sent with relevant API requests; omit to not send. |
+| `enableFaceRegistration` | boolean | no | Include face registration step (default from init or `true`) |
+| **`onSignupComplete(payload)`** | function | no | Called **once** when signup completes. `payload`: `email`, `mobile`, `userId` + any fields from final API (e.g. `access_token`, `refresh_token`). |
+| **`onContinue()`** | function | no | Called when user clicks **Continue to application** on the success screen. Use to unmount and redirect. |
+| **`onSwitchToLogin()`** | function | no | Called when user clicks **Sign in** (e.g. “Already have an account? Sign in”). Use to unmount signup and start the login flow in the **same container** (e.g. login + FRS). |
+
+**Returns:** `{ unmount, getState, getFlow, getCurrentStep }` or `null` if container is invalid.
+
+**Example with callbacks (including switch to login):**
+
+```javascript
+const instance = startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  appIdentifier: 'my-app',
+  onSignupComplete(payload) {
+    console.log('Signup done', payload);
+    saveToken(payload.access_token);
+    instance.unmount();
+    redirectToDashboard();
+  },
+  onContinue() {
+    instance.unmount();
+    redirectToDashboard();
+  },
+  onSwitchToLogin() {
+    instance.unmount();
+    startLogin({ container: '#auth-container', env: 'dev', appIdentifier: 'my-app', loginMethods: { emailFrs: true }, onContinue: goToApp, onSignUp: showSignup });
+  },
+});
+```
+
+---
+
+## 5.1. Theming (optional)
+
+All SDK functions (`initializeAuth`, `startSignup`, `startLogin`) accept an optional **`theme`** object. If omitted, the SDK renders its built-in warm-orange theme. If provided, only the specified properties are overridden — everything else keeps the default.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `primaryColor` | string (hex) | `#D46B2D` | Buttons, links, active states, progress ring, accent bar |
+| `secondaryColor` | string (hex) | — | Reserved for future accent elements |
+| `backgroundColor` | string (hex) | `#F5F1EC` | Page / layout background |
+| `backgroundImage` | string (URL) | — | Full-bleed background image (an overlay is added automatically) |
+| `cardColor` | string (hex) | `#FFFFFF` | Card panel background |
+| `textColor` | string (hex) | `#1A1714` | Primary text color |
+| `fontFamily` | string | `'Plus Jakarta Sans', system-ui` | CSS font-family |
+| `mode` | `'light'` \| `'dark'` \| `'auto'` | `'auto'` | Color mode. `'auto'` detects from `backgroundColor` luminance. |
+
+The SDK **auto-derives** hover colors, glow/shadow colors, gradient endpoints, and input backgrounds from the values you provide. It also runs a WCAG contrast check and logs a warning if `primaryColor` has low contrast against the card.
+
+**Minimal example (just brand colors):**
+
+```javascript
+startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  theme: {
+    primaryColor: '#2563EB',
+  },
+});
+```
+
+**Full customization:**
+
+```javascript
+startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  theme: {
+    primaryColor: '#6C63FF',
+    secondaryColor: '#2D2B55',
+    backgroundColor: '#1A1A2E',
+    backgroundImage: 'https://myapp.com/auth-bg.webp',
+    cardColor: '#1E1E2E',
+    textColor: '#E0E0E0',
+    fontFamily: '"DM Sans", sans-serif',
+    mode: 'dark',
+  },
+});
+```
+
+**Built-in presets** are available via `THEME_PRESETS`:
+
+```javascript
+import { startSignup, THEME_PRESETS } from 'central-auth-sdk';
+
+startSignup({
+  container: '#auth',
+  env: 'dev',
+  theme: THEME_PRESETS.midnight,  // 'default' | 'dark' | 'ocean' | 'forest' | 'purple' | 'rose' | 'midnight'
+});
+```
+
+You can also spread a preset and override individual properties:
+
+```javascript
+theme: { ...THEME_PRESETS.ocean, fontFamily: '"Poppins", sans-serif' }
+```
+
+Theme can be set once via `initializeAuth` and overridden per flow:
+
+```javascript
+const auth = initializeAuth({
+  env: 'dev',
+  theme: { primaryColor: '#E11D48' },
+});
+
+auth.startSignup({});  // uses rose primary
+auth.startLogin({ theme: { primaryColor: '#2563EB' } });  // overrides to blue for login
+```
+
+---
+
+## 6. startLogin(config)
+
+Starts the **login flow**. If the parent enables **only one** login method, the SDK skips the method picker and goes straight to that flow.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `container` | string \| HTMLElement | yes* | Where to render |
+| `env` | string | no | Environment: `'local'` \| `'dev'` \| `'staging'` \| `'prod'` (default from init or `'local'`) |
+| `appIdentifier` | string | no | Optional. When provided, sent with login/OAuth API requests; omit to not send. |
+| **`loginMethods`** | object | no | Which login methods are enabled (see below) |
+| `frsAsSecondFactor` | boolean | no | Require face verification after password/OTP/social |
+| **`onSignUp()`** | function | no | Called when user clicks **Sign up** on the login screen (e.g. unmount login and start signup in the **same container**). |
+| **`onLoginComplete(payload)`** | function | no | Called **once** when login completes. `payload`: `identifier` + any fields from final API (e.g. `access_token`, `refresh_token`). |
+| **`onContinue()`** | function | no | Called when user clicks **Continue to application** on the success screen. |
+
+**Login methods** (`loginMethods`):
+
+| Key | Description |
+|-----|-------------|
+| `emailPassword` | Email + Password |
+| `mobilePassword` | Mobile + Password |
+| `emailOtp` | Email + OTP |
+| `mobileOtp` | Mobile + OTP |
+| `social.google` | Google sign-in |
+| `social.microsoft` | Microsoft sign-in |
+| `emailFrs` | Email + Face only (no password/OTP) |
+
+**Email + FRS:** On the face capture screen, if the user has no webcam, they can click **“No webcam? Sign in with OTP instead”**. The SDK sends an OTP to the email they entered and switches to the OTP step so they can complete login without face capture. No extra configuration is required.
+
+**Example — single method (no method picker):**
+
+```javascript
+startLogin({
+  container: '#auth-container',
+  env: 'dev',
+  appIdentifier: 'my-app',
+  loginMethods: { emailFrs: true },
+  onLoginComplete(payload) {
+    saveToken(payload.access_token);
+    instance.unmount();
+    redirectToApp();
+  },
+  onContinue() {
+    instance.unmount();
+    redirectToApp();
+  },
+  onSignUp() {
+    instance.unmount();
+    startSignup({ container: '#auth-container', env: 'dev', appIdentifier: '...', onContinue: goToApp, onSwitchToLogin: showLoginFrs });
+  },
+});
+```
+
+**Example — multiple methods (user sees method picker):**
+
+```javascript
+startLogin({
+  container: '#auth-container',
+  env: 'dev',
+  appIdentifier: 'my-app',
+  loginMethods: {
+    emailPassword: true,
+    emailOtp: true,
+    social: { google: true, microsoft: true },
+    emailFrs: true,
+  },
+  frsAsSecondFactor: true,
+  onLoginComplete(payload) { /* ... */ },
+  onContinue() { /* ... */ },
+  onSignUp() { /* ... */ },
+});
+```
+
+---
+
+## 6.1. Switching between signup and login in the same container
+
+To keep the user inside the SDK (same container) when they tap **Sign in** or **Sign up**:
+
+- **From signup:** Pass **`onSwitchToLogin()`**. When the user clicks “Already have an account? Sign in”, call it to unmount signup and start login (e.g. `startLogin({ container, loginMethods: { emailFrs: true }, onContinue, onSignUp: showSignup })`).
+- **From login:** Pass **`onSignUp()`**. When the user clicks “Don’t have an account? Sign up”, call it to unmount login and start signup (e.g. `startSignup({ container, onContinue, onSwitchToLogin: showLoginFrs })`).
+
+Define `showSignup` and `showLoginFrs` (or your equivalents) so each starts the other flow in the same container and passes the other callback for the reverse link.
+
+---
+
+## 7. Instance API (returned by startSignup / startLogin)
+
+Each call to `startSignup` or `startLogin` returns an instance (or `null` if the container is invalid):
+
+| Method | Description |
+|--------|-------------|
+| **`instance.unmount()`** | Removes the SDK UI from the DOM. |
+| **`instance.getState()`** | Returns current flow state (e.g. `email`, `mobile`, `userId`, `signupResult` / `loginResult`). After completion, `signupResult` or `loginResult` holds the raw final API response. |
+| **`instance.getCurrentStep()`** | Current step id (e.g. `'email'`, `'password'`, `'success'`). |
+| **`instance.getFlow()`** | Reference to the internal flow controller (for advanced use). |
+
+**Example:**
+
+```javascript
+const instance = startLogin({ container: '#auth', loginMethods: { emailPassword: true } });
+// Later:
+const state = instance.getState();
+const step = instance.getCurrentStep();
+instance.unmount();
+```
+
+---
+
+## 8. Getting tokens and details back
+
+- **Signup:** Pass **`onSignupComplete(payload)`**. The SDK calls it once when signup finishes. `payload` includes `email`, `mobile`, `userId` and whatever your **final signup API** returns (e.g. `access_token`, `refresh_token`). Your backend should return these in the final signup response (e.g. `POST /signup/fr/enroll`).
+- **Login:** Pass **`onLoginComplete(payload)`**. The SDK calls it once when login finishes. `payload` includes `identifier` and whatever your **final login API** returns (e.g. `access_token`, `refresh_token`). Your backend should return these in the final login response (e.g. `POST /login/custom`, `POST /otp/verify`, etc.).
+
+You can also read **`instance.getState()`** after the flow completes; it includes **`signupResult`** or **`loginResult`** (the raw final API response).
+
+---
+
+## 9. Returning to the parent application
+
+When the user clicks **Continue to application** on the success screen, the SDK calls **`onContinue()`** if you provided it. Use it to unmount the SDK and show your app (e.g. redirect or switch view):
+
+```javascript
+onContinue() {
+  instance.unmount();
+  window.location.href = '/dashboard';
+  // or: showYourAppView();
+}
+```
+
+---
+
+## 10. Full integration example
+
+```javascript
+import { initializeAuth, startSignup, startLogin } from 'central-auth-sdk';
+import 'central-auth-sdk/styles.css';
+
+const auth = initializeAuth({
+  env: 'dev',
+  appIdentifier: 'my-app',
+  defaultContainer: '#auth-container',
+  loginMethods: {
+    emailPassword: true,
+    emailOtp: true,
+    social: { google: true, microsoft: true },
+    emailFrs: true,
+  },
+  frsAsSecondFactor: false,
+});
+
+let currentInstance = null;
+
+function goToApp() {
+  if (currentInstance) currentInstance.unmount();
+  currentInstance = null;
+  document.getElementById('auth-container').style.display = 'none';
+  document.getElementById('app-root').style.display = 'block';
+}
+
+function showSignup() {
+  if (currentInstance) currentInstance.unmount();
+  document.getElementById('auth-container').style.display = 'block';
+  currentInstance = auth.startSignup({
+    onSignupComplete(payload) {
+      saveToken(payload.access_token);
+      goToApp();
+    },
+    onContinue: goToApp,
+    onSwitchToLogin: showLoginFrs,
+  });
+}
+
+function showLoginFrs() {
+  if (currentInstance) currentInstance.unmount();
+  document.getElementById('auth-container').style.display = 'block';
+  currentInstance = auth.startLogin({
+    loginMethods: { emailFrs: true },
+    onLoginComplete(payload) {
+      saveToken(payload.access_token);
+      goToApp();
+    },
+    onContinue: goToApp,
+    onSignUp: showSignup,
+  });
+}
+
+function showLogin(loginMethods = { emailPassword: true }) {
+  if (currentInstance) currentInstance.unmount();
+  document.getElementById('auth-container').style.display = 'block';
+  currentInstance = auth.startLogin({
+    loginMethods,
+    onLoginComplete(payload) {
+      saveToken(payload.access_token);
+      goToApp();
+    },
+    onContinue: goToApp,
+    onSignUp: showSignup,
+  });
+}
+
+function saveToken(token) {
+  if (token) localStorage.setItem('access_token', token);
+}
+
+showLogin();
+```
+
+---
+
+## 11. Backend requirements
+
+- **CORS:** Your API must allow requests from your app’s origin (e.g. `Access-Control-Allow-Origin`).
+- **Signup:** The SDK calls your signup endpoints (e.g. `/signup/start`, `/signup/email/verify`, `/signup/fr/enroll`). The **final** response can include `access_token`, `refresh_token`, etc.; the SDK forwards them in `onSignupComplete(payload)` and `getState().signupResult`.
+- **Login:** The SDK calls your login endpoints (e.g. `/login/custom`, `/otp/verify`, `/login/email/fr`). The **final** response can include tokens; the SDK forwards them in `onLoginComplete(payload)` and `getState().loginResult`.
+- **OAuth:** For Google/Microsoft, configure your backend with the same redirect URI your app uses. The SDK reads `login_token` and `provider` from the URL after redirect and continues the flow.
+- **app_identifier:** When the parent app passes **`appIdentifier`**, the SDK sends it as `app_identifier` on login-related requests (e.g. `/login/custom`, `/login/email/fr`, OAuth start URLs, social mobile/FR). If the parent omits it, the SDK does not send the parameter.
+
+For endpoint details and request/response shapes, see **API_INTEGRATION.md** and your backend docs.