@tiquo/dom-package 1.1.2 → 1.3.0

package/dist/index.d.ts

@@ -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 };