central-auth-js-sdk 1.2.6 → 1.2.7

package/INTEGRATION_GUIDE.md

@@ -111,6 +111,9 @@ When **`autoResumeOAuth`** is `true` (default) and **`defaultContainer`** is set
 | `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 |
+| `collectOrgDetails` | boolean \| object | `true` | Whether to show/collect organization fields (Team, Sub-team, Designation) during registration (`true` \| `false`, or `{ team, subTeam, designation }`). |
+| `mobileVerification` | string | `'india_only'` | Mobile verification mode: `'india_only'` \| `'none'` \| `'all'`. Default `'india_only'` verifies +91 via OTP and auto-skips OTP for international numbers. |
+| `skipMobileOtp` | boolean | `false` | Explicitly skip mobile OTP verification for all numbers when `true`. |
 | `onContinue` | function | — | Default callback when user clicks Continue on success (see [§ 9](#9-returning-to-the-parent-application)) |
 | `onBack` | function | — | Default callback when user clicks ← Back on the first screen of signup/login (see [§ 9](#9-returning-to-the-parent-application)) |
 | `onLoginComplete` | function | — | Default login-complete callback |
@@ -135,6 +138,8 @@ const auth = initializeAuth({
   appIdentifier: 'my-app',
   defaultContainer: '#auth-container',
   autoResumeOAuth: true,
+  mobileVerification: 'india_only', // default: verify +91 with OTP, skip for international
+  collectOrgDetails: true, // set false to hide Team, Sub-team, Designation
   loginMethods: {
     emailPassword: true,
     emailOtp: true,
@@ -162,6 +167,10 @@ Starts the **sign-up flow** (email + name → verify → mobile → verify → p
 | `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`) |
+| `collectOrgDetails` | boolean \| object | no | Show/collect Team, Sub-team, Designation during registration (default: `true`, set `false` to hide all, or pass `{ team, subTeam, designation }` for granular control). See [§ 5.3](#53-organization-details-team-sub-team--designation). |
+| `showOrgDetails` | boolean | no | Alias for `collectOrgDetails`. |
+| `mobileVerification` | string | no | Mobile OTP verification policy: `'india_only'` (default) \| `'none'` \| `'all'`. See [§ 5.2](#52-mobile-verification--international-numbers-skip-otp). |
+| `skipMobileOtp` | boolean | no | Skip mobile OTP verification directly (`true` / `false`). |
 | **`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. |
 | **`onBack()`** | function | no | Called when user clicks **← Back** on the **first screen** of signup. Use to unmount the SDK and return to your app. See [§ 9](#9-returning-to-the-parent-application). |
@@ -279,6 +288,122 @@ auth.startLogin({ theme: { primaryColor: '#2563EB' } });  // overrides to blue f
 
 ---
 
+## 5.2. Mobile verification & international numbers (Skip OTP)
+
+By default, the SDK uses **`mobileVerification: 'india_only'`**. This provides frictionless onboarding for international users while preserving carrier-grade SMS/WhatsApp OTP verification for domestic Indian numbers.
+
+### Verification modes
+
+| Mode | Behavior | Button Label | WhatsApp OTP Option |
+|------|----------|--------------|---------------------|
+| `'india_only'` *(Default)* | **+91 (India):** Sends OTP via SMS or WhatsApp and requires 6-digit verification.<br>**International (+1, +44, +971, +65, etc.):** Collects phone number, skips OTP verification, and transitions directly to Password Setup. | "Send Code" (+91)<br>"Continue" (International) | Shown for +91, Hidden for International |
+| `'none'` | Skips OTP for **all** phone numbers. Collects mobile number and transitions immediately to Password Setup. | "Continue" | Hidden |
+| `'all'` | Enforces OTP verification for **all** phone numbers regardless of country code. | "Send Code" | Shown |
+
+> **Shortcut:** You can also pass `skipMobileOtp: true` in `startSignup` or `initializeAuth` to bypass mobile OTP verification completely.
+
+### How it works under the hood
+
+1. **Dynamic UI:** When an international country code is selected (or when OTP is skipped), the SDK dynamically switches the CTA button from *"Send Code"* to *"Continue"*, hides the *"Send WhatsApp OTP instead"* button, and updates the prompt text to *"Enter your mobile number to continue"*.
+2. **Flexible length validation:** Indian numbers (`+91`) require $\ge 10$ digits; international numbers accept between 7 and 15 digits (E.164 standard) to support numbers across different countries (e.g. Singapore `+65` with 8 digits, UAE `+971` with 9 digits).
+3. **Backend integration:**
+   - **Standard flow (with OTP):** Calls `POST /signup/mobile/send_otp` $\rightarrow$ user enters OTP $\rightarrow$ calls `POST /signup/mobile/verify`.
+   - **Skip OTP flow:** Calls `POST /signup/mobile/save` with `{ email, mobile }` to persist the mobile number, advances user signup status to `MOBILE_VERIFIED`, and transitions directly to `STEPS.PASSWORD`.
+
+### Example configurations
+
+#### 1. Default (India OTP only, international numbers skip OTP)
+
+No extra configuration needed! This is the out-of-the-box default:
+
+```javascript
+const instance = startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  // mobileVerification: 'india_only' is active by default
+  onSignupComplete(payload) {
+    console.log('User signed up:', payload);
+  },
+});
+```
+
+#### 2. Skip mobile OTP for all countries
+
+```javascript
+const instance = startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  mobileVerification: 'none', // or pass: skipMobileOtp: true
+  onSignupComplete(payload) {
+    console.log('Signed up without mobile OTP:', payload);
+  },
+});
+```
+
+#### 3. Require OTP for all numbers (Global OTP verification)
+
+```javascript
+const instance = startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  mobileVerification: 'all',
+});
+```
+
+---
+
+## 5.3. Organization details (Team, Sub-team & Designation)
+
+During the email verification step, the SDK by default renders fields to collect **Team**, **Sub-team**, and **Designation** alongside First and Last Name.
+
+If your application does not need to collect organization details, or if you only want to collect a subset of them, use **`collectOrgDetails`** (or its alias **`showOrgDetails`**).
+
+### Configuration options
+
+| Value | Behavior |
+|-------|----------|
+| `true` *(Default)* | Shows all 3 fields (**Team**, **Sub-team**, **Designation**). |
+| `false` | Completely hides **Team**, **Sub-team**, and **Designation** inputs from the registration screen. The user only enters OTP, First Name, and Last Name. |
+| Object `{ team, subTeam, designation }` | Granular control to show only specific fields (e.g. `{ team: true, subTeam: false, designation: true }`). |
+
+### Examples
+
+#### 1. Hide all organization fields during signup
+
+```javascript
+const instance = startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  collectOrgDetails: false, // or showOrgDetails: false
+});
+```
+
+#### 2. Granular control (e.g. collect Team and Designation, hide Sub-team)
+
+```javascript
+const instance = startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  collectOrgDetails: {
+    team: true,
+    subTeam: false,
+    designation: true,
+  },
+});
+```
+
+#### 3. Set globally via `initializeAuth`
+
+```javascript
+const auth = initializeAuth({
+  env: 'dev',
+  defaultContainer: '#auth-container',
+  collectOrgDetails: false, // will apply to all startSignup calls by default
+});
+```
+
+---
+
 ## 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.

package/auth.js

@@ -122,6 +122,9 @@ export function initializeAuth(config = {}) {
     loginMethods: null,
     frsAsSecondFactor: false,
     enableFaceRegistration: true,
+    collectOrgDetails: true,
+    mobileVerification: 'india_only',
+    skipMobileOtp: false,
     theme: null,
     ...config,
   };
@@ -156,6 +159,10 @@ export function initializeAuth(config = {}) {
  * @param {string} [config.env] - Environment: 'local' | 'dev' | 'staging' | 'prod' (default from init or 'local')
  * @param {string} [config.appIdentifier] - Override app identifier
  * @param {boolean} [config.enableFaceRegistration] - Include face registration step (default from init or true)
+ * @param {boolean|Object} [config.collectOrgDetails=true] - Whether to show/collect Team, Sub-team, and Designation during registration (or pass object for granular control: { team, subTeam, designation })
+ * @param {boolean} [config.showOrgDetails] - Alias for collectOrgDetails
+ * @param {string} [config.mobileVerification] - Mobile verification mode: 'india_only' | 'none' | 'all' (default: 'india_only')
+ * @param {boolean} [config.skipMobileOtp] - Explicitly skip mobile OTP verification (default: false)
  * @param {Function} [config.onSignupComplete] - Called when signup completes with (payload). Payload: email, mobile, userId, plus any token/fields from the final API response (e.g. access_token, refresh_token).
  * @param {Function} [config.onContinue] - Called when user clicks Continue on the success screen (e.g. unmount and redirect).
  * @param {Function} [config.onSwitchToLogin] - Called when user clicks "Sign in" (e.g. unmount signup and start login, e.g. login + FRS).
@@ -176,6 +183,10 @@ export function startSignup(config = {}) {
     apiBaseUrl: resolveApiBaseUrl(merged),
     appIdentifier: merged.appIdentifier,
     enableFaceRegistration: merged.enableFaceRegistration,
+    collectOrgDetails: config.collectOrgDetails ?? config.showOrgDetails ?? merged.collectOrgDetails,
+    showOrgDetails: config.showOrgDetails ?? merged.showOrgDetails,
+    mobileVerification: config.mobileVerification ?? merged.mobileVerification,
+    skipMobileOtp: config.skipMobileOtp ?? merged.skipMobileOtp,
     theme: merged.theme || undefined,
     onSignupComplete: config.onSignupComplete ?? merged.onSignupComplete,
     onContinue: config.onContinue ?? merged.onContinue,

package/core/api.js

@@ -77,6 +77,11 @@ export function createApi(baseUrl = DEFAULT_BASE, options = {}) {
       return request('POST', '/signup/mobile/verify', { email, mobile, otp });
     },
 
+    /** POST /signup/mobile/save — Save mobile without OTP verification (e.g. international numbers) */
+    async signupMobileSave(email, mobile) {
+      return request('POST', '/signup/mobile/save', { email, mobile });
+    },
+
     /** POST /signup/password/set — Password step */
     async signupPasswordSet(email, password) {
       return request('POST', '/signup/password/set', { email, password });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "central-auth-js-sdk",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Vanilla JS sign-up and login flow SDK — embeddable auth UI with configurable methods",
   "type": "module",
   "main": "index.js",

package/signup.js

@@ -70,10 +70,20 @@ export function mount(container, options = {}) {
     onContinue = null,
     onSwitchToLogin = null,
     onBack = null,
+    skipMobileOtp = false,
+    mobileVerification = 'india_only',
+    collectOrgDetails = true,
+    showOrgDetails,
   } = options;
 
   const flow = new FlowController();
   const state = new StateManager();
+  state.set('skipMobileOtp', skipMobileOtp);
+  state.set('mobileVerification', mobileVerification);
+  state.set('collectOrgDetails', collectOrgDetails);
+  if (showOrgDetails !== undefined) {
+    state.set('showOrgDetails', showOrgDetails);
+  }
   const api = createApi(apiBaseUrl);
 
   const layout = createLayout(el, () => {});
@@ -172,11 +182,24 @@ export function mount(container, options = {}) {
     }
   }
 
-  async function handleMobileSubmit(mobile, channel = 'sms') {
+  async function handleMobileSubmit(mobile, channel = 'sms', opts = {}) {
     state.clearError();
     state.set('mobile', mobile);
     state.set('mobileChannel', channel);
     try {
+      const shouldSkipOtp = opts?.skipOtp ?? (
+        state.get('skipMobileOtp') === true ||
+        state.get('mobileVerification') === 'none' ||
+        (state.get('mobileVerification') !== 'all' && !mobile.startsWith('+91'))
+      );
+
+      if (shouldSkipOtp) {
+        // Skip OTP verification, save mobile directly and advance to password step
+        await api.signupMobileSave(state.get('email'), mobile);
+        flow.setStep(STEPS.PASSWORD);
+        return;
+      }
+
       let res;
       if (isSocial()) {
         const token = state.get('loginToken');
@@ -189,7 +212,7 @@ export function mount(container, options = {}) {
       if (res?.channel) state.set('mobileChannel', res.channel);
       flow.goNext();
     } catch (err) {
-      const msg = err?.data?.error || err?.message || 'Failed to send code';
+      const msg = err?.data?.error || err?.message || 'Failed to submit mobile number';
       state.set('error', msg);
       showError(msg);
     }

package/ui/screens/email-verify.js

@@ -7,10 +7,54 @@ const MAIL_CHECK = 'M3 8l7.89 5.26a2 2 0 002.22 0L21 8M5 19h14a2 2 0 002-2V7a2 2
 const ARROW_LEFT = 'M19 12H5m7 7l-7-7 7-7';
 const ARROW_RIGHT = 'M5 12h14m-7-7l7 7-7 7';
 
-export function createEmailVerifyScreen(email, onNext, onBack, prefill = {}) {
+export function createEmailVerifyScreen(email, onNext, onBack, prefill = {}, options = {}) {
   const wrap = document.createElement('div');
   wrap.className = 'wf-screen';
 
+  const orgOpt = options.collectOrgDetails !== undefined ? options.collectOrgDetails : options.showOrgDetails;
+  const showTeam = typeof orgOpt === 'object' && orgOpt !== null ? Boolean(orgOpt.team) : orgOpt !== false;
+  const showSubTeam = typeof orgOpt === 'object' && orgOpt !== null ? Boolean(orgOpt.subTeam) : orgOpt !== false;
+  const showDesignation = typeof orgOpt === 'object' && orgOpt !== null ? Boolean(orgOpt.designation) : orgOpt !== false;
+
+  let orgFieldsHtml = '';
+  if (showTeam && showSubTeam) {
+    orgFieldsHtml += `
+      <div class="wf-row-2">
+        <div class="wf-field">
+          <label class="wf-label" for="wf-team">Team</label>
+          <input type="text" id="wf-team" placeholder="Engineering" class="wf-input" autocomplete="organization" />
+        </div>
+        <div class="wf-field">
+          <label class="wf-label" for="wf-sub-team">Sub-team</label>
+          <input type="text" id="wf-sub-team" placeholder="Backend" class="wf-input" />
+        </div>
+      </div>
+    `;
+  } else if (showTeam) {
+    orgFieldsHtml += `
+      <div class="wf-field">
+        <label class="wf-label" for="wf-team">Team</label>
+        <input type="text" id="wf-team" placeholder="Engineering" class="wf-input" autocomplete="organization" />
+      </div>
+    `;
+  } else if (showSubTeam) {
+    orgFieldsHtml += `
+      <div class="wf-field">
+        <label class="wf-label" for="wf-sub-team">Sub-team</label>
+        <input type="text" id="wf-sub-team" placeholder="Backend" class="wf-input" />
+      </div>
+    `;
+  }
+
+  if (showDesignation) {
+    orgFieldsHtml += `
+      <div class="wf-field">
+        <label class="wf-label" for="wf-designation">Designation</label>
+        <input type="text" id="wf-designation" placeholder="Software Engineer" class="wf-input" autocomplete="organization-title" />
+      </div>
+    `;
+  }
+
   const otpInputs = Array(6).fill(0).map((_, i) => `
     <input type="text" inputmode="numeric" maxlength="1" class="wf-otp-input" id="wf-email-otp-${i}" data-idx="${i}" autocomplete="one-time-code" />
   `).join('');
@@ -38,20 +82,7 @@ export function createEmailVerifyScreen(email, onNext, onBack, prefill = {}) {
           <input type="text" id="wf-last-name" placeholder="Doe" class="wf-input" required autocomplete="family-name" />
         </div>
       </div>
-      <div class="wf-row-2">
-        <div class="wf-field">
-          <label class="wf-label" for="wf-team">Team</label>
-          <input type="text" id="wf-team" placeholder="Engineering" class="wf-input" autocomplete="organization" />
-        </div>
-        <div class="wf-field">
-          <label class="wf-label" for="wf-sub-team">Sub-team</label>
-          <input type="text" id="wf-sub-team" placeholder="Backend" class="wf-input" />
-        </div>
-      </div>
-      <div class="wf-field">
-        <label class="wf-label" for="wf-designation">Designation</label>
-        <input type="text" id="wf-designation" placeholder="Software Engineer" class="wf-input" autocomplete="organization-title" />
-      </div>
+      ${orgFieldsHtml}
       <div class="wf-btn-row">
         <button type="button" class="wf-btn wf-btn-outline wf-btn-lg" data-action="back" aria-label="Go back">
           <svg class="wf-icon-sm" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${ARROW_LEFT}"/></svg>

package/ui/screens/index.js

@@ -44,11 +44,18 @@ export function createScreen(step, state, flow, callbacks) {
           team: state.get('team') || '',
           subTeam: state.get('subTeam') || '',
           designation: state.get('designation') || '',
+        },
+        {
+          collectOrgDetails: state.get('collectOrgDetails'),
+          showOrgDetails: state.get('showOrgDetails'),
         }
       );
 
     case STEPS.MOBILE:
-      return createMobileEntryScreen(onMobileSubmit, onBack);
+      return createMobileEntryScreen(onMobileSubmit, onBack, {
+        skipMobileOtp: state.get('skipMobileOtp'),
+        mobileVerification: state.get('mobileVerification'),
+      });
 
     case STEPS.MOBILE_VERIFY:
       return createMobileVerifyScreen(

package/ui/screens/mobile-entry.js

@@ -23,7 +23,7 @@ const COUNTRY_CODES = [
   { code: "52", label: "+52" },
 ];
 
-export function createMobileEntryScreen(onNext, onBack) {
+export function createMobileEntryScreen(onNext, onBack, options = {}) {
   const wrap = document.createElement("div");
   wrap.className = "wf-screen";
 
@@ -37,7 +37,7 @@ export function createMobileEntryScreen(onNext, onBack) {
         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${PHONE_ICON}"/></svg>
       </div>
       <h2 class="wf-screen-title">Add your mobile number</h2>
-      <p class="wf-screen-desc">We will send a verification code to confirm this number</p>
+      <p class="wf-screen-desc" id="wf-mobile-desc">We will send a verification code to confirm this number</p>
     </div>
     <form class="wf-form" id="wf-mobile-form">
       <div class="wf-field">
@@ -54,11 +54,11 @@ export function createMobileEntryScreen(onNext, onBack) {
           <svg class="wf-icon-sm" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${ARROW_LEFT}"/></svg>
         </button>
         <button type="submit" class="wf-btn wf-btn-primary wf-btn-lg wf-btn-flex" id="wf-btn-send-sms">
-          Send Code
+          <span id="wf-mobile-btn-text">Send Code</span>
           <svg class="wf-icon-sm" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${ARROW_RIGHT}"/></svg>
         </button>
       </div>
-      <div class="wf-channel-alt">
+      <div class="wf-channel-alt" id="wf-mobile-channel-alt">
         <div class="wf-divider-text"><span>or</span></div>
         <button type="button" class="wf-btn wf-btn-outline wf-btn-whatsapp-outline wf-btn-lg wf-btn-full" id="wf-btn-send-wa">
           <svg class="wf-icon-sm" viewBox="0 0 24 24" fill="currentColor"><path d="${WHATSAPP_ICON}"/></svg>
@@ -71,14 +71,55 @@ export function createMobileEntryScreen(onNext, onBack) {
   const form = wrap.querySelector("#wf-mobile-form");
   const countrySelect = wrap.querySelector("#wf-mobile-country");
   const input = wrap.querySelector("#wf-mobile");
+  const descEl = wrap.querySelector("#wf-mobile-desc");
+  const btnTextEl = wrap.querySelector("#wf-mobile-btn-text");
+  const channelAlt = wrap.querySelector("#wf-mobile-channel-alt");
   const waBtn = wrap.querySelector("#wf-btn-send-wa");
 
+  function isSkipOtp() {
+    if (options.skipMobileOtp === true || options.mobileVerification === "none") {
+      return true;
+    }
+    if (options.mobileVerification === "all") {
+      return false;
+    }
+    // Default: india_only -> skip OTP for non-+91 numbers
+    return countrySelect.value !== "91";
+  }
+
+  function updateUiState() {
+    const skip = isSkipOtp();
+    if (skip) {
+      if (descEl) descEl.textContent = "Enter your mobile number to continue";
+      if (btnTextEl) btnTextEl.textContent = "Continue";
+      if (channelAlt) channelAlt.style.display = "none";
+    } else {
+      if (descEl) descEl.textContent = "We will send a verification code to confirm this number";
+      if (btnTextEl) btnTextEl.textContent = "Send Code";
+      if (channelAlt) channelAlt.style.display = "";
+    }
+  }
+
+  countrySelect.addEventListener("change", updateUiState);
+  updateUiState();
+
+  input.addEventListener("input", () => {
+    input.setCustomValidity("");
+  });
+
   function submitMobile(channel = "sms") {
     const digits = input.value.trim().replace(/\D/g, "");
-    if (digits.length >= 10) {
+    const minLen = countrySelect.value === "91" ? 10 : 7;
+    if (digits.length >= minLen && digits.length <= 15) {
       const full = "+" + countrySelect.value + digits;
-      onNext(full, channel);
+      const skipOtp = isSkipOtp();
+      onNext(full, channel, { skipOtp });
     } else {
+      input.setCustomValidity(
+        digits.length < minLen
+          ? `Please enter a valid phone number (at least ${minLen} digits)`
+          : "Phone number cannot exceed 15 digits"
+      );
       input.focus();
       if (typeof input.reportValidity === "function") {
         input.reportValidity();