@tiquo/dom-package 1.5.0 → 1.5.2

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
+- **First-Party Website Analytics** - Cookie-free pageview, session, attribution, and known-customer activity tracking
 - **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
@@ -39,6 +40,19 @@ const auth = new TiquoAuth({
 });
 ```
 
+Website analytics starts automatically when you initialize `TiquoAuth` or `TiquoCMS`.
+The same public key is used across all websites in your organization; Tiquo records
+the source domain for each event and rolls `www.example.com` into `example.com`.
+Other subdomains are tracked as separate websites.
+
+```typescript
+// Optional custom analytics events
+await auth.analytics?.track('booking_started', {
+  eventName: 'Booking Started',
+  eventProperties: { serviceId: 'svc_123' }
+});
+```
+
 ### 3. Authenticate Users
 
 ```typescript
@@ -65,6 +79,7 @@ const auth = new TiquoAuth({
   storagePrefix?: string;  // Optional: localStorage key prefix
   debug?: boolean;         // Optional: Enable debug logging
   enableTabSync?: boolean; // Optional: Multi-tab session sync (default: true)
+  analytics?: boolean;     // Optional: Website analytics (default: true)
 });
 ```
 
@@ -137,12 +152,24 @@ const result = await auth.updateProfile({
 console.log(result.customer.firstName); // 'John'
 ```
 
+Profile photos can be passed as a URL, a browser `File`/`Blob`, or a `data:image/...`/`blob:...` URI:
+
+```typescript
+const file = fileInput.files?.[0];
+if (file) {
+  await auth.updateProfile({ profilePhoto: file });
+}
+
+// Or upload just the photo:
+await auth.uploadProfilePhoto(file);
+```
+
 **Available fields:**
 - `firstName` - Customer's first name
 - `lastName` - Customer's last name
 - `displayName` - Display name (nickname)
 - `phone` - Primary phone number (E.164 format recommended: `+[country code][number]`)
-- `profilePhoto` - URL to profile photo
+- `profilePhoto` - URL, File/Blob, or `data:image/...`/`blob:...` URI for 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.

package/dist/index.d.mts

@@ -209,6 +209,37 @@ declare function buildPhone(countryCode: string, nationalNumber: string): string
  * ```
  */
 
+declare class TiquoAnalytics {
+    private static activeInstances;
+    private config;
+    private clientSessionId;
+    private pageStartedAt;
+    private lastPath;
+    private started;
+    constructor(config: TiquoAnalyticsConfig);
+    start(): void;
+    trackPageview(options?: TiquoAnalyticsEventOptions): Promise<void>;
+    track(eventType: string, options?: TiquoAnalyticsEventOptions): Promise<void>;
+    identify(options?: TiquoAnalyticsEventOptions): Promise<void>;
+    private trackEngagement;
+    private send;
+    private getClientSessionId;
+    private log;
+    private adoptConfig;
+}
+declare class TiquoCMS {
+    private config;
+    analytics: TiquoAnalytics | null;
+    constructor(config: TiquoCMSConfig);
+    /**
+     * Fetch a published CMS page for the website attached to this public key.
+     *
+     * This intentionally goes through the Tiquo edge API rather than exposing
+     * Convex connection details to the consuming website.
+     */
+    getPage(request: TiquoCMSPageRequest): Promise<TiquoCMSPage | null>;
+    private log;
+}
 interface TiquoAuthConfig {
     /** Public key from your Tiquo Auth DOM settings */
     publicKey: string;
@@ -224,6 +255,84 @@ interface TiquoAuthConfig {
     accessToken?: string;
     /** Pre-authenticated refresh token (for WebView injection from native apps) */
     refreshToken?: string;
+    /** Enable first-party website analytics (default: true) */
+    analytics?: boolean;
+}
+interface TiquoCMSConfig {
+    /** Public key from your Tiquo Auth DOM settings */
+    publicKey: string;
+    /** API endpoint (defaults to production) */
+    apiEndpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Enable first-party website analytics (default: true) */
+    analytics?: boolean;
+}
+interface TiquoAnalyticsConfig {
+    /** Public key from your Tiquo Auth DOM settings */
+    publicKey: string;
+    /** API endpoint (defaults to production) */
+    apiEndpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Optional CMS website slug */
+    siteSlug?: string;
+    /** Enable automatic pageview tracking (default: true) */
+    autoTrackPageviews?: boolean;
+    /** Optional access-token getter used to associate events with known customers */
+    getAccessToken?: () => string | null | undefined;
+}
+interface TiquoAnalyticsEventOptions {
+    eventName?: string;
+    eventProperties?: Record<string, unknown>;
+    siteSlug?: string;
+    pageSlug?: string;
+    path?: string;
+    url?: string;
+    title?: string;
+    referrer?: string;
+    durationMs?: number;
+    scrollDepth?: number;
+    identityLinkType?: "auth_dom_login" | "email_capture" | "booking" | "enquiry" | "order" | "customer_portal" | "manual";
+}
+interface TiquoCMSPageRequest {
+    /** CMS website slug */
+    siteSlug: string;
+    /** CMS page slug, defaults to "home" */
+    pageSlug?: string;
+    /** Optional template contract guard */
+    templateId?: string;
+}
+interface TiquoCMSBlock {
+    id: string;
+    type: string;
+    props: Record<string, unknown>;
+    locked?: boolean;
+    lockedBy?: string;
+    required?: boolean;
+}
+interface TiquoCMSPage {
+    id: string;
+    site: {
+        id: string;
+        name: string;
+        slug?: string;
+        templateId?: string;
+        templateVersion?: number;
+        globalConfig?: unknown;
+    };
+    page: {
+        id: string;
+        title: string;
+        slug: string;
+        path: string;
+        blocks: TiquoCMSBlock[];
+        settings?: unknown;
+        metaTitle?: string;
+        metaDescription?: string;
+        publishedAt?: number;
+        updatedAt: number;
+    };
 }
 declare global {
     interface Window {
@@ -305,7 +414,13 @@ interface ProfileUpdateData {
      * for country+national input, or TiquoPhone.validate() to pre-check.
      */
     phone?: string;
-    profilePhoto?: string;
+    /**
+     * URL to a profile photo, a data/blob URI, or a browser File/Blob.
+     *
+     * File/Blob and data/blob URI values are uploaded to Tiquo storage before the
+     * profile is updated. Remote URLs are stored as-is.
+     */
+    profilePhoto?: string | Blob;
     emails?: TiquoCustomerEmail[];
     /**
      * Full phone list. Each number should be in E.164 format: +[country code][number].
@@ -317,13 +432,17 @@ interface ProfileUpdateResult {
     success: boolean;
     customer: TiquoCustomer;
 }
+interface ProfilePhotoUploadResult extends ProfileUpdateResult {
+    profilePhoto: string;
+    storageId: string;
+}
 interface TiquoOrderItem {
     id: string;
     name: string;
     quantity: number;
     unitPrice: number;
     total: number;
-    type: 'product' | 'booking' | 'custom';
+    type: "product" | "booking" | "custom";
 }
 /**
  * An order belonging to the authenticated customer.
@@ -335,8 +454,8 @@ interface TiquoOrderItem {
 interface TiquoOrder {
     id: string;
     orderNumber: string;
-    status: 'draft' | 'processing' | 'completed' | 'cancelled' | 'refunded' | 'open_tab';
-    paymentStatus: 'pending' | 'paid' | 'partial' | 'refunded' | 'partially_refunded' | 'failed' | 'cancelled';
+    status: "draft" | "processing" | "completed" | "cancelled" | "refunded" | "open_tab";
+    paymentStatus: "pending" | "paid" | "partial" | "refunded" | "partially_refunded" | "failed" | "cancelled";
     total: number;
     subtotal: number;
     taxTotal: number;
@@ -344,12 +463,12 @@ interface TiquoOrder {
     items: TiquoOrderItem[];
     createdAt: number;
     completedAt?: number;
-    customerRole: 'primary' | 'attendee' | 'billing' | 'referrer' | 'other';
+    customerRole: "primary" | "attendee" | "billing" | "referrer" | "other";
 }
 interface GetOrdersOptions {
     limit?: number;
     cursor?: string;
-    status?: TiquoOrder['status'];
+    status?: TiquoOrder["status"];
 }
 interface GetOrdersResult {
     orders: TiquoOrder[];
@@ -365,7 +484,7 @@ interface TiquoReceiptItem {
     tax: number;
     discount: number;
     total: number;
-    type: 'product' | 'booking' | 'custom' | 'membership';
+    type: "product" | "booking" | "custom" | "membership";
     specialInstructions?: string;
 }
 interface TiquoReceiptBusiness {
@@ -392,8 +511,8 @@ interface TiquoReceiptCustomer {
 interface TiquoReceiptOrder {
     id: string;
     orderNumber: string;
-    status: TiquoOrder['status'];
-    paymentStatus: TiquoOrder['paymentStatus'];
+    status: TiquoOrder["status"];
+    paymentStatus: TiquoOrder["paymentStatus"];
     currency: string;
     subtotal: number;
     taxTotal: number;
@@ -433,7 +552,7 @@ interface TiquoReceipt {
 interface TiquoBooking {
     id: string;
     bookingNumber: string;
-    status: 'scheduled' | 'confirmed' | 'reminder_sent' | 'waiting_room' | 'waiting_list' | 'checked_in' | 'active' | 'in_progress' | 'completed' | 'cancelled' | 'no_show' | 'rescheduled';
+    status: "scheduled" | "confirmed" | "reminder_sent" | "waiting_room" | "waiting_list" | "checked_in" | "active" | "in_progress" | "completed" | "cancelled" | "no_show" | "rescheduled";
     date: number;
     startTime: string;
     endTime: string;
@@ -457,7 +576,7 @@ interface TiquoBooking {
 interface GetBookingsOptions {
     limit?: number;
     cursor?: string;
-    status?: TiquoBooking['status'];
+    status?: TiquoBooking["status"];
     upcoming?: boolean;
 }
 interface GetBookingsResult {
@@ -472,27 +591,27 @@ interface TiquoEnquiry {
     subject: string;
     message: string;
     category: string;
-    status: 'new' | 'in_progress' | 'waiting_customer' | 'waiting_internal' | 'won' | 'lost' | 'closed' | 'resolved' | 'archived';
-    priority: 'low' | 'medium' | 'high' | 'urgent';
-    source: 'online' | 'website' | 'phone' | 'email' | 'walk_in' | 'social' | 'referral' | 'pos' | 'admin';
+    status: "new" | "in_progress" | "waiting_customer" | "waiting_internal" | "won" | "lost" | "closed" | "resolved" | "archived";
+    priority: "low" | "medium" | "high" | "urgent";
+    source: "online" | "website" | "phone" | "email" | "walk_in" | "social" | "referral" | "pos" | "admin";
     responseCount: number;
     createdAt: string;
     updatedAt: string;
     firstResponseAt?: string;
     resolvedAt?: string;
-    customerRole: 'primary' | 'attendee' | 'billing' | 'referrer' | 'other';
+    customerRole: "primary" | "attendee" | "billing" | "referrer" | "other";
 }
 interface GetEnquiriesOptions {
     limit?: number;
     cursor?: string;
-    status?: TiquoEnquiry['status'];
+    status?: TiquoEnquiry["status"];
 }
 interface GetEnquiriesResult {
     enquiries: TiquoEnquiry[];
     hasMore: boolean;
     nextCursor?: string;
 }
-type TiquoCompanyRelationship = 'employee' | 'contractor' | 'manager' | 'executive' | 'owner' | 'contact' | 'other';
+type TiquoCompanyRelationship = "employee" | "contractor" | "manager" | "executive" | "owner" | "contact" | "other";
 /**
  * The authenticated customer's membership in a company. Each company the
  * customer belongs to has its own membership record — a customer can be
@@ -530,9 +649,9 @@ interface TiquoCompany {
     postalCode?: string;
     country?: string;
     industry?: string;
-    companySize?: '1-10' | '11-50' | '51-200' | '201-500' | '501-1000' | '1000+';
-    status: 'active' | 'inactive' | 'archived';
-    type?: 'client' | 'prospect' | 'vendor' | 'partner' | 'other';
+    companySize?: "1-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1000+";
+    status: "active" | "inactive" | "archived";
+    type?: "client" | "prospect" | "vendor" | "partner" | "other";
     membership: TiquoCompanyMembership;
 }
 interface GetCompaniesResult {
@@ -583,6 +702,7 @@ declare class TiquoAuth {
     private visibilityHandler;
     private iframeObserver;
     private injectedIframes;
+    analytics: TiquoAnalytics | null;
     private broadcastChannel;
     private tabId;
     private isProcessingTabSync;
@@ -615,6 +735,14 @@ declare class TiquoAuth {
      * to construct from a country selector and national number.
      */
     updateProfile(updates: ProfileUpdateData): Promise<ProfileUpdateResult>;
+    /**
+     * Upload and save the authenticated customer's profile photo.
+     *
+     * Accepts a browser File/Blob, `data:image/...` URI, or `blob:...` URI. The
+     * image is uploaded to Tiquo storage first, and the customer profile is
+     * updated with the URL.
+     */
+    uploadProfilePhoto(photo: Blob | string): Promise<ProfilePhotoUploadResult>;
     /**
      * Log out the current user
      */
@@ -654,7 +782,7 @@ declare class TiquoAuth {
      * future, since they're effectively history. Use `getBookings()` without
      * `upcoming: true` if you need those.
      */
-    getUpcomingBookings(options?: Omit<GetBookingsOptions, 'upcoming'>): Promise<GetBookingsResult>;
+    getUpcomingBookings(options?: Omit<GetBookingsOptions, "upcoming">): Promise<GetBookingsResult>;
     /**
      * Get a printable receipt for a single order owned by the authenticated
      * customer. Only resolves for orders that are paid (full or partial),
@@ -747,6 +875,9 @@ declare class TiquoAuth {
      * Check for tokens injected by native apps (WebView integration)
      */
     private checkForInjectedTokens;
+    private extractUploadableProfilePhoto;
+    private isProfilePhotoBlobUrl;
+    private profilePhotoToBlob;
     private request;
     /**
      * Ensure we have a valid access token, refreshing if necessary
@@ -791,6 +922,7 @@ declare function useTiquoAuth(auth: TiquoAuth): {
     verifyOTP: (email: string, otp: string) => Promise<VerifyOTPResult>;
     logout: () => Promise<void>;
     updateProfile: (updates: ProfileUpdateData) => Promise<ProfileUpdateResult>;
+    uploadProfilePhoto: (photo: Blob | string) => Promise<ProfilePhotoUploadResult>;
     getOrders: (options?: GetOrdersOptions) => Promise<GetOrdersResult>;
     getBookings: (options?: GetBookingsOptions) => Promise<GetBookingsResult>;
     getUpcomingBookings: (options?: Omit<GetBookingsOptions, "upcoming">) => Promise<GetBookingsResult>;
@@ -860,4 +992,4 @@ declare class TiquoPhone {
     static buildPhone: typeof buildPhone;
 }
 
-export { type AuthStateChangeCallback, type CountryPhoneInfo, type GetBookingsOptions, type GetBookingsResult, type GetCompaniesResult, type GetCompanyColleaguesResult, 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 TiquoCompany, type TiquoCompanyColleague, type TiquoCompanyMembership, type TiquoCompanyRelationship, type TiquoCustomer, type TiquoCustomerEmail, type TiquoCustomerPhone, type TiquoEnquiry, type TiquoOrder, type TiquoOrderItem, TiquoPhone, type TiquoReceipt, type TiquoReceiptBusiness, type TiquoReceiptCustomer, type TiquoReceiptItem, type TiquoReceiptOrder, type TiquoSession, type TiquoUser, type VerifyOTPResult, addCustomerUserId, clearCachedEmail, TiquoAuth as default, getCustomerUserIds, getPrefilledEmailFromCookie, isDashboardSession, trackCustomerPresence, useTiquoAuth };
+export { type AuthStateChangeCallback, type CountryPhoneInfo, type GetBookingsOptions, type GetBookingsResult, type GetCompaniesResult, type GetCompanyColleaguesResult, type GetEnquiriesOptions, type GetEnquiriesResult, type GetOrdersOptions, type GetOrdersResult, type IframeTokenResult, type PhoneValidationResult, type ProfilePhotoUploadResult, type ProfileUpdateData, type ProfileUpdateResult, type SendOTPResult, TiquoAnalytics, type TiquoAnalyticsConfig, type TiquoAnalyticsEventOptions, TiquoAuth, type TiquoAuthConfig, TiquoAuthError, type TiquoBooking, TiquoCMS, type TiquoCMSBlock, type TiquoCMSConfig, type TiquoCMSPage, type TiquoCMSPageRequest, type TiquoCompany, type TiquoCompanyColleague, type TiquoCompanyMembership, type TiquoCompanyRelationship, type TiquoCustomer, type TiquoCustomerEmail, type TiquoCustomerPhone, type TiquoEnquiry, type TiquoOrder, type TiquoOrderItem, TiquoPhone, type TiquoReceipt, type TiquoReceiptBusiness, type TiquoReceiptCustomer, type TiquoReceiptItem, type TiquoReceiptOrder, type TiquoSession, type TiquoUser, type VerifyOTPResult, addCustomerUserId, clearCachedEmail, TiquoAuth as default, getCustomerUserIds, getPrefilledEmailFromCookie, isDashboardSession, trackCustomerPresence, useTiquoAuth };