@tiquo/dom-package 1.1.2 → 1.3.0

package/README.md

@@ -9,6 +9,7 @@ Tiquo SDK for third-party websites. Integrate authentication, customer profiles,
 - **Multi-Tab Sync** - Auth state automatically syncs across all browser tabs
 - **Native App Integration** - WebView token injection for iOS/Android hybrid apps
 - **Customer Flow Integration** - Embed authenticated customer flows with one line of code
+- **Phone Number Utilities** - Validation, formatting, and country code support for 200+ countries
 - **Framework Agnostic** - Works with React, Vue, Svelte, or vanilla JavaScript
 - **TypeScript Support** - Full type definitions included
 
@@ -123,12 +124,14 @@ if (auth.isAuthenticated()) {
 
 Update the authenticated customer's profile. Only allows updating the logged-in customer's own data.
 
+Phone numbers are **automatically normalized** to E.164 format before being sent to the API. You can pass common formats and they'll be cleaned up, but for best results include the country code.
+
 ```typescript
 const result = await auth.updateProfile({
   firstName: 'John',
   lastName: 'Doe',
   displayName: 'Johnny',
-  phone: '+1234567890',
+  phone: '+1 (555) 456-7890', // Auto-normalized to +15554567890
 });
 
 console.log(result.customer.firstName); // 'John'
@@ -138,8 +141,11 @@ console.log(result.customer.firstName); // 'John'
 - `firstName` - Customer's first name
 - `lastName` - Customer's last name
 - `displayName` - Display name (nickname)
-- `phone` - Primary phone number
+- `phone` - Primary phone number (E.164 format recommended: `+[country code][number]`)
 - `profilePhoto` - URL to profile photo
+- `phones` - Full phone list (array of `{ number, isPrimary, order }`)
+
+> **Important:** Phone numbers should include a country code (e.g., `+1` for US, `+44` for UK). Use `TiquoPhone.buildPhone()` to construct properly formatted numbers from a country selector + national number input. See [Phone Number Utilities](#phone-number-utilities) below.
 
 #### `logout(): Promise<void>`
 
@@ -427,6 +433,164 @@ async function logout() {
 </template>
 ```
 
+## Phone Number Utilities
+
+The SDK includes `TiquoPhone`, a static utility class for working with international phone numbers. It supports **200+ countries** and handles validation, normalization, formatting, and country detection — everything you need to build a phone input with a country selector.
+
+### Import
+
+```typescript
+import { TiquoPhone } from '@tiquo/dom-package';
+```
+
+### Get Countries (for building a dropdown)
+
+```typescript
+const countries = TiquoPhone.getCountries();
+// Returns alphabetically sorted array:
+// [
+//   { code: "AF", name: "Afghanistan", dialCode: "+93", format: "XX XXX XXXX", flag: "🇦🇫" },
+//   ...
+//   { code: "GB", name: "United Kingdom", dialCode: "+44", format: "XXXX XXXXXX", flag: "🇬🇧" },
+//   { code: "US", name: "United States", dialCode: "+1", format: "(XXX) XXX-XXXX", flag: "🇺🇸" },
+//   ...
+// ]
+```
+
+### Build a Phone Number (country selector + input)
+
+```typescript
+// Combine a country selector value with a local number input
+TiquoPhone.buildPhone("GB", "07911 123456"); // → "+447911123456"
+TiquoPhone.buildPhone("US", "(555) 456-7890"); // → "+15554567890"
+TiquoPhone.buildPhone("FR", "06 65 08 50 44"); // → "+33665085044"
+```
+
+### Validate a Phone Number
+
+```typescript
+TiquoPhone.validate("+44 7911 123456");
+// → { valid: true, normalized: "+447911123456", countryCode: "GB" }
+
+TiquoPhone.validate("555-1234");
+// → { valid: false, reason: "Phone number must include a country code..." }
+
+TiquoPhone.validate("+999 123");
+// → { valid: false, reason: "Phone number is too short..." }
+```
+
+### Normalize to E.164
+
+```typescript
+TiquoPhone.normalize("+1 (555) 456-7890");    // → "+15554567890"
+TiquoPhone.normalize("+44 (0)20 3227 4972");   // → "+442032274972"
+TiquoPhone.normalize("0033 6 65 08 50 44");    // → "+33665085044"
+TiquoPhone.normalize("+49 0151 12345678");     // → "+4915112345678"
+```
+
+### Format for Display
+
+```typescript
+TiquoPhone.format("+15554567890");  // → "+1 (555) 456-7890"
+TiquoPhone.format("+447911123456"); // → "+44 7911 123456"
+TiquoPhone.format("+33665085044");  // → "+33 6 65 08 50 44"
+```
+
+### Detect Country
+
+```typescript
+TiquoPhone.detectCountry("+15554567890");  // → "US"
+TiquoPhone.detectCountry("+447911123456"); // → "GB"
+TiquoPhone.detectCountry("+33665085044");  // → "FR"
+```
+
+### Get Dial Code
+
+```typescript
+TiquoPhone.getDialCode("US"); // → "+1"
+TiquoPhone.getDialCode("GB"); // → "+44"
+TiquoPhone.getDialCode("FR"); // → "+33"
+```
+
+### Example: Phone Input with Country Selector (React)
+
+```tsx
+import { TiquoPhone } from '@tiquo/dom-package';
+import { useState } from 'react';
+
+function PhoneInput({ onChange }) {
+  const countries = TiquoPhone.getCountries();
+  const [country, setCountry] = useState('US');
+  const [number, setNumber] = useState('');
+  const [error, setError] = useState('');
+
+  const handleChange = (newCountry, newNumber) => {
+    setCountry(newCountry);
+    setNumber(newNumber);
+
+    if (!newNumber.trim()) {
+      setError('');
+      onChange('');
+      return;
+    }
+
+    const phone = TiquoPhone.buildPhone(newCountry, newNumber);
+    if (!phone) {
+      setError('Invalid phone number');
+      onChange('');
+      return;
+    }
+
+    const result = TiquoPhone.validate(phone);
+    if (result.valid) {
+      setError('');
+      onChange(result.normalized);
+    } else {
+      setError(result.reason);
+      onChange('');
+    }
+  };
+
+  return (
+    <div>
+      <select
+        value={country}
+        onChange={(e) => handleChange(e.target.value, number)}
+      >
+        {countries.map((c) => (
+          <option key={c.code} value={c.code}>
+            {c.flag} {c.name} ({c.dialCode})
+          </option>
+        ))}
+      </select>
+      <input
+        type="tel"
+        value={number}
+        onChange={(e) => handleChange(country, e.target.value)}
+        placeholder={countries.find(c => c.code === country)?.format}
+      />
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+    </div>
+  );
+}
+
+// Usage with updateProfile:
+function ProfilePage() {
+  const [phone, setPhone] = useState('');
+
+  const handleSave = async () => {
+    await auth.updateProfile({ phone }); // Already in E.164 format
+  };
+
+  return (
+    <div>
+      <PhoneInput onChange={setPhone} />
+      <button onClick={handleSave} disabled={!phone}>Save</button>
+    </div>
+  );
+}
+```
+
 ## Multi-Tab Session Sync
 
 The SDK automatically synchronizes authentication state across all browser tabs using the [BroadcastChannel API](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel). This means:

package/dist/index.d.mts

@@ -4,13 +4,13 @@
  * This module handles setting a cross-subdomain cookie that stores customer user IDs.
  * The cookie is shared across all *.tiquo.app subdomains and persists for 1 year.
  *
- * The cookie is NOT set if the user is logged in with Clerk (dashboard staff).
+ * The cookie is NOT set if the user is a dashboard staff member.
  */
 /**
- * Check if the current user is authenticated via Clerk (dashboard staff).
- * If they are, we should NOT set the customer cookie.
+ * Check if the current user has an active dashboard staff session.
+ * If they do, we should NOT set the customer cookie.
  */
-declare function isClerkAuthenticated(): boolean;
+declare function isDashboardSession(): boolean;
 /**
  * Get the list of customer user IDs from the cookie.
  */
@@ -18,7 +18,7 @@ declare function getCustomerUserIds(): string[];
 /**
  * Add a customer user ID to the cookie.
  * Does nothing if:
- * - The user is authenticated via Clerk (dashboard staff)
+ * - The user has an active dashboard staff session
  * - The user ID is already in the cookie
  * - Running in a non-browser environment
  *
@@ -30,7 +30,7 @@ declare function addCustomerUserId(userId: string): void;
  * This fetches the user's email associated with the cookie user IDs.
  * Results are cached for 5 minutes to avoid repeated API calls.
  *
- * @param organizationId - The Clerk organization ID
+ * @param organizationId - The organization ID
  * @returns Promise with email and optional name fields, or null if not found
  */
 declare function getPrefilledEmailFromCookie(organizationId: string): Promise<{
@@ -47,7 +47,7 @@ declare function clearCachedEmail(): void;
  * Track customer presence when the cookie is detected.
  * This updates the customer's online status and logs activity.
  *
- * @param organizationId - The Clerk organization ID
+ * @param organizationId - The organization ID
  * @returns Promise with tracking results
  */
 declare function trackCustomerPresence(organizationId: string): Promise<{
@@ -61,6 +61,109 @@ declare function trackCustomerPresence(organizationId: string): Promise<{
     error?: string;
 }>;
 
+/**
+ * @tiquo/dom-package - Phone Utilities
+ *
+ * Comprehensive phone number validation, normalization, and formatting
+ * with worldwide country code support. Designed for use in websites
+ * that integrate the Tiquo DOM package.
+ */
+interface CountryPhoneInfo {
+    /** ISO 3166-1 alpha-2 code (e.g. "US", "GB") */
+    code: string;
+    /** Country name */
+    name: string;
+    /** Dial code with + prefix (e.g. "+1", "+44") */
+    dialCode: string;
+    /** Example format (e.g. "(XXX) XXX-XXXX") */
+    format: string;
+    /** Flag emoji */
+    flag: string;
+}
+interface PhoneValidationResult {
+    /** Whether the phone number is valid for submission */
+    valid: boolean;
+    /** Normalized E.164 format if valid (e.g. "+15551234567") */
+    normalized?: string;
+    /** Detected country code if identifiable */
+    countryCode?: string;
+    /** Reason for invalid result */
+    reason?: string;
+}
+/**
+ * Normalize a phone number to E.164 format (+digits).
+ * Handles all worldwide formats: international prefixes, domestic leading zeros,
+ * formatting characters, (0) patterns, 00-prefix, Unicode artifacts.
+ *
+ * @example
+ * normalizePhone("+1 (555) 456-7890")  // → "+15554567890"
+ * normalizePhone("+44 (0)20 3227 4972") // → "+442032274972"
+ * normalizePhone("0033 6 65 08 50 44")  // → "+33665085044"
+ * normalizePhone("+49 0151 12345678")   // → "+4915112345678"
+ */
+declare function normalizePhone(phone: string): string;
+/**
+ * Validate a phone number and return detailed results.
+ * Checks format, length, and country code presence.
+ *
+ * @example
+ * validatePhone("+15554567890")    // → { valid: true, normalized: "+15554567890", countryCode: "US" }
+ * validatePhone("555-1234")        // → { valid: false, reason: "Phone number must include a country code..." }
+ * validatePhone("+44 7911 123456") // → { valid: true, normalized: "+447911123456", countryCode: "GB" }
+ */
+declare function validatePhone(phone: string): PhoneValidationResult;
+/**
+ * Detect the country from a phone number's calling code.
+ * Returns the ISO 3166-1 alpha-2 country code, or null if unrecognized.
+ *
+ * @example
+ * detectCountry("+15554567890")  // → "US"
+ * detectCountry("+447911123456") // → "GB"
+ * detectCountry("+33665085044")  // → "FR"
+ */
+declare function detectCountry(phone: string): string | null;
+/**
+ * Format a phone number for display using country-specific patterns.
+ *
+ * @example
+ * formatPhone("+15554567890")  // → "+1 (555) 456-7890"
+ * formatPhone("+447911123456") // → "+44 7911 123456"
+ * formatPhone("+33665085044")  // → "+33 6 65 08 50 44"
+ */
+declare function formatPhone(phone: string): string;
+/**
+ * Get the full list of countries with phone info for building UI selectors.
+ * Returns countries sorted alphabetically by name.
+ *
+ * @example
+ * const countries = getCountries();
+ * // Build a <select> dropdown:
+ * countries.forEach(c => {
+ *   // c.code = "GB", c.name = "United Kingdom", c.dialCode = "+44",
+ *   // c.format = "XXXX XXXXXX", c.flag = "🇬🇧"
+ * });
+ */
+declare function getCountries(): CountryPhoneInfo[];
+/**
+ * Get the dial code for a specific country.
+ *
+ * @example
+ * getDialCode("US") // → "+1"
+ * getDialCode("GB") // → "+44"
+ * getDialCode("FR") // → "+33"
+ */
+declare function getDialCode(countryCode: string): string | null;
+/**
+ * Build a full E.164 phone number from a country code and national number.
+ * Strips the domestic leading zero if present.
+ *
+ * @example
+ * buildPhone("GB", "07911 123456") // → "+447911123456"
+ * buildPhone("US", "(555) 456-7890") // → "+15554567890"
+ * buildPhone("FR", "06 65 08 50 44") // → "+33665085044"
+ */
+declare function buildPhone(countryCode: string, nationalNumber: string): string | null;
+
 /**
  * @tiquo/dom-package
  *
@@ -190,9 +293,21 @@ interface ProfileUpdateData {
     firstName?: string;
     lastName?: string;
     displayName?: string;
+    /**
+     * Primary phone number in E.164 format: +[country code][number]
+     * Examples: "+15551234567" (US), "+447911123456" (UK), "+33665085044" (FR)
+     *
+     * The SDK auto-normalizes common formats (strips spaces, dashes, parentheses,
+     * handles +/00 prefixes). Use TiquoPhone.buildPhone("GB", "07911 123456")
+     * for country+national input, or TiquoPhone.validate() to pre-check.
+     */
     phone?: string;
     profilePhoto?: string;
     emails?: TiquoCustomerEmail[];
+    /**
+     * Full phone list. Each number should be in E.164 format: +[country code][number].
+     * The SDK auto-normalizes all numbers before sending to the API.
+     */
     phones?: TiquoCustomerPhone[];
 }
 interface ProfileUpdateResult {
@@ -324,7 +439,12 @@ declare class TiquoAuth {
     isAuthenticated(): boolean;
     /**
      * Update the authenticated customer's profile
-     * Only allows updating the logged-in customer's own data
+     * Only allows updating the logged-in customer's own data.
+     *
+     * Phone numbers are automatically normalized to E.164 format (+digits).
+     * For best results, include a country code: "+1 (555) 456-7890" or "+44 7911 123456".
+     * Use TiquoPhone.validate() to check before submitting, or TiquoPhone.buildPhone()
+     * to construct from a country selector and national number.
      */
     updateProfile(updates: ProfileUpdateData): Promise<ProfileUpdateResult>;
     /**
@@ -438,5 +558,57 @@ declare function useTiquoAuth(auth: TiquoAuth): {
     }) => Promise<HTMLIFrameElement>;
     onAuthStateChange: (cb: AuthStateChangeCallback) => () => void;
 };
+/**
+ * Phone number utilities for building phone inputs and validating numbers.
+ * All methods are static — no instantiation needed.
+ *
+ * @example
+ * ```typescript
+ * import { TiquoPhone } from '@tiquo/dom-package';
+ *
+ * // Get countries for a selector dropdown
+ * const countries = TiquoPhone.getCountries();
+ *
+ * // Build a phone number from country + national number
+ * const phone = TiquoPhone.buildPhone("GB", "07911 123456");
+ * // → "+447911123456"
+ *
+ * // Validate before submitting
+ * const result = TiquoPhone.validate("+44 7911 123456");
+ * // → { valid: true, normalized: "+447911123456", countryCode: "GB" }
+ *
+ * // Normalize for submission
+ * const e164 = TiquoPhone.normalize("+1 (555) 456-7890");
+ * // → "+15554567890"
+ *
+ * // Format for display
+ * const display = TiquoPhone.format("+15554567890");
+ * // → "+1 (555) 456-7890"
+ *
+ * // Detect country from a phone number
+ * const country = TiquoPhone.detectCountry("+33665085044");
+ * // → "FR"
+ *
+ * // Get dial code for a country
+ * const dialCode = TiquoPhone.getDialCode("US");
+ * // → "+1"
+ * ```
+ */
+declare class TiquoPhone {
+    /** Normalize a phone number to E.164 format (+digits). */
+    static normalize: typeof normalizePhone;
+    /** Validate a phone number with detailed result. */
+    static validate: typeof validatePhone;
+    /** Detect the country from a phone number's calling code. */
+    static detectCountry: typeof detectCountry;
+    /** Format a phone number for display using country-specific patterns. */
+    static format: typeof formatPhone;
+    /** Get the full list of countries with phone info for building UI selectors. */
+    static getCountries: typeof getCountries;
+    /** Get the dial code for a specific country (e.g. "US" → "+1"). */
+    static getDialCode: typeof getDialCode;
+    /** Build an E.164 phone number from a country code and national number. */
+    static buildPhone: typeof buildPhone;
+}
 
-export { type AuthStateChangeCallback, type GetBookingsOptions, type GetBookingsResult, type GetEnquiriesOptions, type GetEnquiriesResult, type GetOrdersOptions, type GetOrdersResult, type IframeTokenResult, type ProfileUpdateData, type ProfileUpdateResult, type SendOTPResult, TiquoAuth, type TiquoAuthConfig, TiquoAuthError, type TiquoBooking, type TiquoCustomer, type TiquoCustomerEmail, type TiquoCustomerPhone, type TiquoEnquiry, type TiquoOrder, type TiquoOrderItem, type TiquoSession, type TiquoUser, type VerifyOTPResult, addCustomerUserId, clearCachedEmail, TiquoAuth as default, getCustomerUserIds, getPrefilledEmailFromCookie, isClerkAuthenticated, trackCustomerPresence, useTiquoAuth };
+export { type AuthStateChangeCallback, type CountryPhoneInfo, type GetBookingsOptions, type GetBookingsResult, type GetEnquiriesOptions, type GetEnquiriesResult, type GetOrdersOptions, type GetOrdersResult, type IframeTokenResult, type PhoneValidationResult, type ProfileUpdateData, type ProfileUpdateResult, type SendOTPResult, TiquoAuth, type TiquoAuthConfig, TiquoAuthError, type TiquoBooking, type TiquoCustomer, type TiquoCustomerEmail, type TiquoCustomerPhone, type TiquoEnquiry, type TiquoOrder, type TiquoOrderItem, TiquoPhone, type TiquoSession, type TiquoUser, type VerifyOTPResult, addCustomerUserId, clearCachedEmail, TiquoAuth as default, getCustomerUserIds, getPrefilledEmailFromCookie, isDashboardSession, trackCustomerPresence, useTiquoAuth };