@aranova/tracking-react 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -1,6 +1,11 @@
-import { ReactNode, CSSProperties } from 'react';
+import * as react from 'react';
+import { ReactNode, CSSProperties, InputHTMLAttributes, ChangeEvent, FocusEvent } from 'react';
+import { C as ConsentState, T as TrackingInstallSurface, a as TrackingEnvironment, b as TrackingClientContext, c as TrackingParams, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, F as FormSubmitConfig, f as FormSubmitMetadata, G as GtagEnvironmentMap, P as PhoneConfig, g as ParsedPhone, h as PhoneDisplayFormat } from './phone-utils-CVX7JmqB.js';
+export { D as DEFAULT_PHONE_COUNTRY, J as JsonValue, i as TrackedField, j as TrackingInitConfig, k as formatPhone, l as formatPhoneAsTyped, p as parsePhone, m as phoneField, t as toE164 } from './phone-utils-CVX7JmqB.js';
 import * as src from 'src';
 import { z } from 'zod';
+import { CountryCode } from 'libphonenumber-js';
+export { CountryCode } from 'libphonenumber-js';
 
 /**
  * Default non-blocking consent banner.
@@ -67,166 +72,6 @@ interface ConsentBannerProps {
 }
 declare function ConsentBanner({ message, title, acceptLabel, declineLabel, policyHref, policyLabel, onAccept, onDecline, position, theme, className, style, }?: ConsentBannerProps): ReactNode;
 
-/**
- * Visitor consent state stored by the SDK.
- *
- * - `pending`: the visitor has not accepted or declined yet.
- * - `granted`: consent was accepted and Google Consent Mode is updated to granted.
- * - `denied`: consent was declined and Google Consent Mode is updated to denied.
- */
-type ConsentState = 'granted' | 'denied' | 'pending';
-/**
- * Attribution parameters captured from the landing URL and persisted in cookies.
- *
- * Missing params are represented as `null` so payloads can be serialized
- * directly without checking for `undefined`.
- */
-interface TrackingParams {
-    /** Google Ads click id. */
-    gclid: string | null;
-    /** Meta/Facebook click id. */
-    fbclid: string | null;
-    /** UTM source, for example `google` or `newsletter`. */
-    utm_source: string | null;
-    /** UTM medium, for example `cpc` or `email`. */
-    utm_medium: string | null;
-    /** UTM campaign name. */
-    utm_campaign: string | null;
-    /** UTM paid-search term. */
-    utm_term: string | null;
-    /** UTM content/ad creative label. */
-    utm_content: string | null;
-}
-/**
- * Runtime surface that installed the tracking SDK.
- *
- * Included in ingest payloads and heartbeat events so the dashboard can tell
- * whether a site uses the Next, React, or script-tag integration.
- */
-type TrackingInstallSurface = 'next' | 'react' | 'script';
-/**
- * Deployment environment label for event tagging.
- *
- * Used to stamp tracking events with the deployment context so the dashboard
- * can distinguish production traffic from dev test traffic. The backend
- * enforces this via a Postgres enum, so values are strictly one of
- * `'production'` or `'development'`.
- */
-type TrackingEnvironment = 'production' | 'development';
-/**
- * Labelled map of Google Ads tag IDs.
- *
- * ALL entries are loaded simultaneously via `gtag('config', ...)` — the keys
- * are human-readable labels (e.g. `production`, `test`) and the values are
- * Google Ads tag IDs (e.g. `AW-123456789`).
- */
-type GtagEnvironmentMap = Record<string, string>;
-/**
- * Runtime context attached to tracking sessions and events.
- */
-interface TrackingClientContext {
-    /** Install surface that created the client. */
-    surface: TrackingInstallSurface;
-    /** Package version, when available. */
-    sdk_version: string | null;
-    /** Package name, for example `@aranova/tracking-react`. */
-    package_name: string | null;
-    /** Browser origin of the tracked site. */
-    site_origin: string | null;
-    /** Current document title at client creation time. */
-    page_title: string | null;
-    /** Browser document referrer at client creation time. */
-    referrer: string | null;
-    /**
-     * Deployment environment label, e.g. `'production'`, `'development'`.
-     *
-     * Always set — defaults to `'production'` when the consumer doesn't
-     * pass `environment` to the factory. Sending `null` would fail the
-     * backend's strict enum validation.
-     */
-    environment: TrackingEnvironment;
-    /** All active gtag IDs loaded on this page, keyed by label. */
-    active_gtag_ids: Record<string, string> | null;
-}
-/**
- * Session payload sent to `POST /tracking/events`.
- *
- * The backend upserts this by `(business_id, session_id)` before inserting
- * individual events.
- */
-interface TrackingSessionUpsertPayload {
-    /** Rolling 30-minute client-side session id. */
-    session_id: string;
-    /** Persistent client-side visitor id. */
-    visitor_id: string | null;
-    gclid: string | null;
-    fbclid: string | null;
-    utm_source: string | null;
-    utm_medium: string | null;
-    utm_campaign: string | null;
-    utm_term: string | null;
-    utm_content: string | null;
-    first_page: string | null;
-    consent_state: Record<string, unknown> | null;
-    context: TrackingClientContext;
-}
-/**
- * Event payload shape before batching into the ingest request.
- */
-interface TrackingEventCreatePayload {
-    /** Session id that logically owns the event. */
-    session_id: string;
-    /** Registered event name, for example `page_view` or `form_submit`. */
-    event_type: string;
-    gclid: string | null;
-    fbclid: string | null;
-    /** Full page URL associated with the event, if known. */
-    page_url: string | null;
-    /** Event-specific metadata. Runtime shape depends on `event_type`. */
-    metadata: Record<string, unknown> | null;
-    context: TrackingClientContext;
-}
-/**
- * Browser-script initialization config passed to `window.AranovaTracking.init()`.
- */
-interface TrackingInitConfig {
-    /** Public tracking API key issued from the Aranova dashboard. */
-    apiKey?: string;
-    /** Tracking endpoint base URL, usually ending in `/tracking`. */
-    endpoint?: string;
-    /** Optional Google Ads tag id, for example `AW-123456789`. */
-    gtagId?: string;
-    /**
-     * Labelled map of Google Ads tag IDs. ALL are loaded simultaneously.
-     * When provided, `gtagId` is ignored.
-     */
-    gtagIds?: GtagEnvironmentMap;
-    /** Deployment environment label reported in session context. */
-    environment?: TrackingEnvironment;
-    /** Whether to capture attribution params from `window.location`. Defaults to true. */
-    autoCaptureTrackingParams?: boolean;
-    /** Whether the browser script should inject the default consent banner. */
-    renderConsentBanner?: boolean;
-    /** Attribution cookie max age in seconds. Defaults to 90 days. */
-    cookieMaxAgeSeconds?: number;
-    /** Override the install surface reported in payload context. */
-    surface?: TrackingInstallSurface;
-}
-declare global {
-    interface Window {
-        gtag?: (...args: unknown[]) => void;
-        dataLayer?: unknown[];
-        AranovaTracking?: {
-            init: (config: TrackingInitConfig) => void;
-            captureTrackingParams: () => TrackingParams;
-            getTrackingParams: () => TrackingParams;
-            getConsentState: () => ConsentState;
-            setConsentState: (state: 'granted' | 'denied') => void;
-            trackEvent: (eventType: string, metadata: Record<string, unknown>) => void;
-        };
-    }
-}
-
 /**
  * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
  */
@@ -456,131 +301,6 @@ declare const formStartConfigSchema: z.ZodObject<{
 }>;
 type FormStartConfig = z.infer<typeof formStartConfigSchema>;
 
-/**
- * JSON-serializable value accepted by `form_submit.fields[].value`.
- *
- * This intentionally excludes `undefined`, functions, symbols, `Date`
- * instances, and non-finite numbers. Values are stored in PostgreSQL JSONB, so
- * consumers should send only data that has a stable JSON representation.
- */
-type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-/**
- * Metadata for a manually fired `form_submit` event.
- *
- * Register the event with `manual: { form_submit: {} }`, then call
- * `trackEvent('form_submit', metadata)` from the host site's submit handler.
- *
- * `fields` is optional. If present, each field value must be JSON-serializable
- * and should be explicitly allowlisted by the integration. Do not send names,
- * emails, visitor phone numbers, addresses, payment data, medical details,
- * passwords, file contents, or free-text messages.
- *
- * @example
- * ```ts
- * tracking.trackEvent('form_submit', {
- *   form: {
- *     id: 'lead-form',
- *     action: '/api/lead',
- *     fields: [
- *       {
- *         name: 'service_interest',
- *         type: 'select',
- *         label: 'Service interest',
- *         value: 'teeth_whitening',
- *       },
- *     ],
- *   },
- *   page: { path: window.location.pathname },
- * });
- * ```
- */
-declare const formSubmitMetadataSchema: z.ZodObject<{
-    form: z.ZodObject<{
-        id: z.ZodString;
-        action: z.ZodNullable<z.ZodString>;
-        fields: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            type: z.ZodString;
-            label: z.ZodNullable<z.ZodString>;
-            value: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
-        }, "strict", z.ZodTypeAny, {
-            label: string | null;
-            value: JsonValue;
-            type: string;
-            name: string;
-        }, {
-            label: string | null;
-            value: JsonValue;
-            type: string;
-            name: string;
-        }>, "many">>;
-    }, "strict", z.ZodTypeAny, {
-        id: string;
-        action: string | null;
-        fields?: {
-            label: string | null;
-            value: JsonValue;
-            type: string;
-            name: string;
-        }[] | undefined;
-    }, {
-        id: string;
-        action: string | null;
-        fields?: {
-            label: string | null;
-            value: JsonValue;
-            type: string;
-            name: string;
-        }[] | undefined;
-    }>;
-    page: z.ZodObject<{
-        path: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        path: string;
-    }, {
-        path: string;
-    }>;
-}, "strict", z.ZodTypeAny, {
-    form: {
-        id: string;
-        action: string | null;
-        fields?: {
-            label: string | null;
-            value: JsonValue;
-            type: string;
-            name: string;
-        }[] | undefined;
-    };
-    page: {
-        path: string;
-    };
-}, {
-    form: {
-        id: string;
-        action: string | null;
-        fields?: {
-            label: string | null;
-            value: JsonValue;
-            type: string;
-            name: string;
-        }[] | undefined;
-    };
-    page: {
-        path: string;
-    };
-}>;
-type FormSubmitMetadata = z.infer<typeof formSubmitMetadataSchema>;
-/**
- * Registration config for `form_submit`.
- *
- * This event is manual-only and currently has no registration options. The
- * empty object enables typed `trackEvent('form_submit', ...)` calls.
- */
-declare const formSubmitConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
-type FormSubmitConfig = z.infer<typeof formSubmitConfigSchema>;
-
 /**
  * Metadata for the automatic `multi_page_session` event.
  *
@@ -634,14 +354,14 @@ declare const pageViewMetadataSchema: z.ZodObject<{
         search: z.ZodString;
         hash: z.ZodString;
     }, "strict", z.ZodTypeAny, {
+        path: string;
         search: string;
         title: string | null;
-        path: string;
         hash: string;
     }, {
+        path: string;
         search: string;
         title: string | null;
-        path: string;
         hash: string;
     }>;
     referrer: z.ZodNullable<z.ZodString>;
@@ -657,9 +377,9 @@ declare const pageViewMetadataSchema: z.ZodObject<{
     }>>>;
 }, "strict", z.ZodTypeAny, {
     page: {
+        path: string;
         search: string;
         title: string | null;
-        path: string;
         hash: string;
     };
     referrer: string | null;
@@ -669,9 +389,9 @@ declare const pageViewMetadataSchema: z.ZodObject<{
     } | null | undefined;
 }, {
     page: {
+        path: string;
         search: string;
         title: string | null;
-        path: string;
         hash: string;
     };
     referrer: string | null;
@@ -880,14 +600,14 @@ declare const EVENT_REGISTRY: {
                 search: z.ZodString;
                 hash: z.ZodString;
             }, "strict", z.ZodTypeAny, {
+                path: string;
                 search: string;
                 title: string | null;
-                path: string;
                 hash: string;
             }, {
+                path: string;
                 search: string;
                 title: string | null;
-                path: string;
                 hash: string;
             }>;
             referrer: z.ZodNullable<z.ZodString>;
@@ -903,9 +623,9 @@ declare const EVENT_REGISTRY: {
             }>>>;
         }, "strict", z.ZodTypeAny, {
             page: {
+                path: string;
                 search: string;
                 title: string | null;
-                path: string;
                 hash: string;
             };
             referrer: string | null;
@@ -915,9 +635,9 @@ declare const EVENT_REGISTRY: {
             } | null | undefined;
         }, {
             page: {
+                path: string;
                 search: string;
                 title: string | null;
-                path: string;
                 hash: string;
             };
             referrer: string | null;
@@ -1161,33 +881,33 @@ declare const EVENT_REGISTRY: {
                     label: z.ZodNullable<z.ZodString>;
                     value: z.ZodType<src.JsonValue, z.ZodTypeDef, src.JsonValue>;
                 }, "strict", z.ZodTypeAny, {
-                    label: string | null;
                     value: src.JsonValue;
                     type: string;
                     name: string;
-                }, {
                     label: string | null;
+                }, {
                     value: src.JsonValue;
                     type: string;
                     name: string;
+                    label: string | null;
                 }>, "many">>;
             }, "strict", z.ZodTypeAny, {
                 id: string;
                 action: string | null;
                 fields?: {
-                    label: string | null;
                     value: src.JsonValue;
                     type: string;
                     name: string;
+                    label: string | null;
                 }[] | undefined;
             }, {
                 id: string;
                 action: string | null;
                 fields?: {
-                    label: string | null;
                     value: src.JsonValue;
                     type: string;
                     name: string;
+                    label: string | null;
                 }[] | undefined;
             }>;
             page: z.ZodObject<{
@@ -1202,10 +922,10 @@ declare const EVENT_REGISTRY: {
                 id: string;
                 action: string | null;
                 fields?: {
-                    label: string | null;
                     value: src.JsonValue;
                     type: string;
                     name: string;
+                    label: string | null;
                 }[] | undefined;
             };
             page: {
@@ -1216,10 +936,10 @@ declare const EVENT_REGISTRY: {
                 id: string;
                 action: string | null;
                 fields?: {
-                    label: string | null;
                     value: src.JsonValue;
                     type: string;
                     name: string;
+                    label: string | null;
                 }[] | undefined;
             };
             page: {
@@ -1505,12 +1225,32 @@ declare const saleItemSchema: z.ZodObject<{
     category?: string | null | undefined;
     unit_cost_cents?: number | null | undefined;
 }>;
-declare const saleCreateSchema: z.ZodObject<{
+declare const saleServiceSchema: z.ZodObject<{
+    service: z.ZodString;
+    amount_cents: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    service: string;
+    amount_cents: number;
+}, {
+    service: string;
+    amount_cents: number;
+}>;
+declare const saleCreateSchema: z.ZodEffects<z.ZodObject<{
     external_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     service: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    services: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        service: z.ZodString;
+        amount_cents: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        service: string;
+        amount_cents: number;
+    }, {
+        service: string;
+        amount_cents: number;
+    }>, "many">>>;
     currency: z.ZodEnum<["USD", "CAD"]>;
-    amount_total_cents: z.ZodNumber;
+    amount_total_cents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     occurred_at: z.ZodString;
     environment: z.ZodDefault<z.ZodEnum<["production", "development"]>>;
     items: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1541,7 +1281,6 @@ declare const saleCreateSchema: z.ZodObject<{
     customer_email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
     currency: "USD" | "CAD";
-    amount_total_cents: number;
     occurred_at: string;
     environment: "production" | "development";
     items: {
@@ -1553,20 +1292,77 @@ declare const saleCreateSchema: z.ZodObject<{
         unit_cost_cents?: number | null | undefined;
     }[];
     metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | null | undefined;
     external_id?: string | null | undefined;
     description?: string | null | undefined;
-    service?: string | null | undefined;
     customer_name?: string | null | undefined;
     customer_phone?: string | null | undefined;
     customer_email?: string | null | undefined;
 }, {
     currency: "USD" | "CAD";
-    amount_total_cents: number;
     occurred_at: string;
     metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | null | undefined;
+    external_id?: string | null | undefined;
+    description?: string | null | undefined;
+    environment?: "production" | "development" | undefined;
+    items?: {
+        quantity: string;
+        unit_price_cents: number;
+        name?: string | null | undefined;
+        external_item_id?: string | null | undefined;
+        category?: string | null | undefined;
+        unit_cost_cents?: number | null | undefined;
+    }[] | undefined;
+    customer_name?: string | null | undefined;
+    customer_phone?: string | null | undefined;
+    customer_email?: string | null | undefined;
+}>, {
+    currency: "USD" | "CAD";
+    occurred_at: string;
+    environment: "production" | "development";
+    items: {
+        quantity: string;
+        unit_price_cents: number;
+        name?: string | null | undefined;
+        external_item_id?: string | null | undefined;
+        category?: string | null | undefined;
+        unit_cost_cents?: number | null | undefined;
+    }[];
+    metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | null | undefined;
     external_id?: string | null | undefined;
     description?: string | null | undefined;
+    customer_name?: string | null | undefined;
+    customer_phone?: string | null | undefined;
+    customer_email?: string | null | undefined;
+}, {
+    currency: "USD" | "CAD";
+    occurred_at: string;
+    metadata?: Record<string, unknown> | null | undefined;
     service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | null | undefined;
+    external_id?: string | null | undefined;
+    description?: string | null | undefined;
     environment?: "production" | "development" | undefined;
     items?: {
         quantity: string;
@@ -1580,9 +1376,19 @@ declare const saleCreateSchema: z.ZodObject<{
     customer_phone?: string | null | undefined;
     customer_email?: string | null | undefined;
 }>;
-declare const saleUpdateSchema: z.ZodObject<{
+declare const saleUpdateSchema: z.ZodEffects<z.ZodObject<{
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     service: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    services: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        service: z.ZodString;
+        amount_cents: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        service: string;
+        amount_cents: number;
+    }, {
+        service: string;
+        amount_cents: number;
+    }>, "many">>>;
     currency: z.ZodOptional<z.ZodEnum<["USD", "CAD"]>>;
     amount_total_cents: z.ZodOptional<z.ZodNumber>;
     occurred_at: z.ZodOptional<z.ZodString>;
@@ -1614,10 +1420,14 @@ declare const saleUpdateSchema: z.ZodObject<{
     customer_email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
     metadata?: Record<string, unknown> | null | undefined;
-    description?: string | null | undefined;
     service?: string | null | undefined;
-    currency?: "USD" | "CAD" | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
     amount_total_cents?: number | undefined;
+    description?: string | null | undefined;
+    currency?: "USD" | "CAD" | undefined;
     occurred_at?: string | undefined;
     items?: {
         quantity: string;
@@ -1632,10 +1442,58 @@ declare const saleUpdateSchema: z.ZodObject<{
     customer_email?: string | null | undefined;
 }, {
     metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | undefined;
     description?: string | null | undefined;
+    currency?: "USD" | "CAD" | undefined;
+    occurred_at?: string | undefined;
+    items?: {
+        quantity: string;
+        unit_price_cents: number;
+        name?: string | null | undefined;
+        external_item_id?: string | null | undefined;
+        category?: string | null | undefined;
+        unit_cost_cents?: number | null | undefined;
+    }[] | undefined;
+    customer_name?: string | null | undefined;
+    customer_phone?: string | null | undefined;
+    customer_email?: string | null | undefined;
+}>, {
+    metadata?: Record<string, unknown> | null | undefined;
     service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | undefined;
+    description?: string | null | undefined;
     currency?: "USD" | "CAD" | undefined;
+    occurred_at?: string | undefined;
+    items?: {
+        quantity: string;
+        unit_price_cents: number;
+        name?: string | null | undefined;
+        external_item_id?: string | null | undefined;
+        category?: string | null | undefined;
+        unit_cost_cents?: number | null | undefined;
+    }[] | undefined;
+    customer_name?: string | null | undefined;
+    customer_phone?: string | null | undefined;
+    customer_email?: string | null | undefined;
+}, {
+    metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
     amount_total_cents?: number | undefined;
+    description?: string | null | undefined;
+    currency?: "USD" | "CAD" | undefined;
     occurred_at?: string | undefined;
     items?: {
         quantity: string;
@@ -1650,6 +1508,7 @@ declare const saleUpdateSchema: z.ZodObject<{
     customer_email?: string | null | undefined;
 }>;
 type SaleItemInput = z.input<typeof saleItemSchema>;
+type SaleServiceInput = z.input<typeof saleServiceSchema>;
 type SaleInput = z.input<typeof saleCreateSchema>;
 type SaleUpdateInput = z.input<typeof saleUpdateSchema>;
 interface SaleItem {
@@ -1661,6 +1520,13 @@ interface SaleItem {
     unit_price_cents: number;
     unit_cost_cents: number | null;
 }
+interface SaleService {
+    id: string;
+    service_id: string;
+    service_key: string;
+    service_label: string;
+    amount_cents: number;
+}
 interface Sale {
     id: string;
     business_id: string;
@@ -1672,6 +1538,7 @@ interface Sale {
     service_id: string | null;
     service_key?: string | null;
     service_label?: string | null;
+    services: SaleService[];
     occurred_at: string;
     environment: (typeof TRACKING_ENVIRONMENTS)[number];
     metadata: Record<string, unknown> | null;
@@ -1689,7 +1556,11 @@ interface SaleListPage {
 interface SaleCursorPage {
     items: Sale[];
     next_cursor: string | null;
+    /** Populated only when `want_total` was requested (a single indexed COUNT). */
+    total_count?: number;
+    has_more?: boolean;
 }
+type SaleSortOrder = 'asc' | 'desc';
 /**
  * Comprehensive filter shape mirrored from the backend's `SaleQueryFilters`.
  *
@@ -1702,6 +1573,8 @@ interface SaleFilters {
     business_id?: string;
     external_id?: string;
     service_id?: string;
+    /** E.164 phone — the canonical customer key; filters sales for one customer. */
+    customer_phone?: string;
     currency?: SupportedCurrency;
     environment?: (typeof TRACKING_ENVIRONMENTS)[number];
     since?: string;
@@ -1725,6 +1598,15 @@ interface SaleListQuery extends SaleFilters {
     limit?: number;
     cursor?: string | null;
 }
+/** Keyset-safe sort columns (NOT-NULL, indexed). */
+type SaleKeysetSortField = 'occurred_at' | 'created_at' | 'amount_total_cents';
+/** v2 list query — adds server sort + opt-in total. */
+interface SaleListQueryV2 extends SaleListQuery {
+    sort?: SaleKeysetSortField;
+    order?: SaleSortOrder;
+    /** Opt-in: a single indexed COUNT over the filtered set. */
+    want_total?: boolean;
+}
 declare const TRACKING_RANGES: readonly ["24h", "7d", "30d"];
 type TrackingOverviewRange = (typeof TRACKING_RANGES)[number];
 /** Query input for `SalesClient.summary()` — filters + range + options. */
@@ -1780,6 +1662,175 @@ interface SaleSummary {
     by_category: SalesCategoryBreakdown[];
     series: SalesTrendPoint[];
 }
+declare const NAMED_RANGES: readonly ["today", "yesterday", "wtd", "mtd", "qtd", "ytd", "24h", "7d", "30d", "90d", "custom"];
+/** Superset of `TrackingOverviewRange` (`24h`/`7d`/`30d` stay valid). */
+type NamedRange = (typeof NAMED_RANGES)[number];
+type Granularity = 'hour' | 'day' | 'week' | 'month' | 'auto';
+type CompareTo = 'previous_period' | 'previous_year' | 'none';
+interface DistinctCustomersByCurrency {
+    currency: SupportedCurrency;
+    distinct_customers: number;
+}
+interface SummaryWindow {
+    since: string;
+    until: string;
+}
+interface SummaryCurrencyDelta {
+    currency: SupportedCurrency;
+    revenue_cents_delta: number;
+    /** Ratio (0.12 = +12%); null when previous revenue was 0. */
+    revenue_pct_delta: number | null;
+    sale_count_delta: number;
+}
+interface SummaryDeltas {
+    by_currency: SummaryCurrencyDelta[];
+    sale_count_delta: number;
+    distinct_customers_delta: number;
+}
+interface SaleSummaryPrevious {
+    window: SummaryWindow;
+    metrics: SaleSummaryV2['metrics'];
+    by_currency: CurrencyRevenue[];
+    series: SalesTrendPoint[];
+}
+/** Query input for `SalesClient.summary()` v2 — widened range + tz/compare options. */
+interface SaleSummaryQueryV2 extends SaleFilters {
+    range?: NamedRange;
+    /** Required when `range === 'custom'`. */
+    since?: string;
+    until?: string;
+    /** IANA tz, e.g. `America/Toronto`. Default = business tz. */
+    timezone?: string;
+    granularity?: Granularity;
+    compare_to?: CompareTo;
+    include_categories?: boolean;
+    include_deleted_services?: boolean;
+    top_n?: number;
+}
+/** Superset of `SaleSummary` (assignable to it). */
+interface SaleSummaryV2 extends Omit<SaleSummary, 'range' | 'metrics'> {
+    range: NamedRange;
+    metrics: SaleSummary['metrics'] & {
+        distinct_customers_by_currency: DistinctCustomersByCurrency[];
+    };
+    timezone: string | null;
+    window: SummaryWindow | null;
+    granularity: string | null;
+    previous: SaleSummaryPrevious | null;
+    deltas: SummaryDeltas | null;
+}
+type CustomerSegment = 'new' | 'returning' | 'repeat' | 'lapsed';
+type CustomerSortField = 'total_spent' | 'last_purchase' | 'purchases' | 'first_purchase';
+interface CustomerCurrencyTotal {
+    currency: SupportedCurrency;
+    revenue_cents: number;
+    sale_count: number;
+    average_order_value_cents: number;
+}
+interface CustomerSummary {
+    /** The E.164 phone — the canonical customer id. */
+    customer_id: string;
+    display_name: string | null;
+    email: string | null;
+    phone: string;
+    first_purchase_at: string;
+    last_purchase_at: string;
+    purchase_count: number;
+    segment: CustomerSegment;
+    totals: CustomerCurrencyTotal[];
+}
+type CustomerProfile = CustomerSummary;
+interface CustomerListQuery extends Omit<SaleFilters, 'external_id'> {
+    segment?: CustomerSegment;
+    sort?: CustomerSortField;
+    order?: SaleSortOrder;
+    cursor?: string | null;
+    limit?: number;
+    want_total?: boolean;
+}
+interface CustomerListPage {
+    items: CustomerSummary[];
+    next_cursor: string | null;
+    total_count: number | null;
+}
+interface CustomerGetOptions {
+    include_sales?: boolean;
+    limit?: number;
+    cursor?: string | null;
+}
+interface CustomerGetResult {
+    customer: CustomerProfile;
+    /** Present only when `include_sales: true` (and a business-scoped key). */
+    sales?: SaleCursorPage | null;
+}
+interface CustomerSummaryQuery extends SaleFilters {
+    range?: NamedRange;
+    since?: string;
+    until?: string;
+    timezone?: string;
+    compare_to?: CompareTo;
+}
+interface CustomerSegmentCount {
+    segment: CustomerSegment;
+    count: number;
+}
+interface CustomerCurrencyDelta {
+    currency: SupportedCurrency;
+    revenue_cents_delta: number;
+    /** Ratio (0.12 = +12%); null when previous revenue was 0. */
+    revenue_pct_delta: number | null;
+}
+interface CustomerKpisDeltas {
+    total_customers_delta: number;
+    new_customers_delta: number;
+    returning_customers_delta: number;
+    repeat_rate_delta: number;
+    ltv_by_currency: CustomerCurrencyDelta[];
+}
+interface CustomerKpisPrevious {
+    window_since: string;
+    window_until: string;
+    total_customers: number;
+    new_customers: number;
+    returning_customers: number;
+    repeat_rate: number;
+    ltv_by_currency: CustomerCurrencyTotal[];
+}
+interface CustomerKpis {
+    range: NamedRange;
+    timezone: string;
+    window_since: string;
+    window_until: string;
+    total_customers: number;
+    new_customers: number;
+    returning_customers: number;
+    repeat_rate: number;
+    by_segment: CustomerSegmentCount[];
+    ltv_by_currency: CustomerCurrencyTotal[];
+    /** Present only when `compare_to` is set. */
+    previous?: CustomerKpisPrevious | null;
+    deltas?: CustomerKpisDeltas | null;
+}
+interface BusinessConfigService {
+    key: string;
+    label: string;
+    archived: boolean;
+}
+interface BusinessConfigFeatures {
+    customers: boolean;
+    comparisons: boolean;
+    retention: boolean;
+}
+interface BusinessConfig {
+    business_id: string;
+    display_name: string;
+    timezone: string;
+    primary_currency: SupportedCurrency;
+    currencies: SupportedCurrency[];
+    default_phone_country: string | null;
+    services: BusinessConfigService[];
+    features: BusinessConfigFeatures;
+}
 
 /** Shared config for every sales HTTP helper. */
 interface SalesTransportConfig {
@@ -1802,6 +1853,17 @@ interface SalesClientConfig extends SalesTransportConfig {
     /** Applied when an individual `record()` call omits `currency`. */
     defaultCurrency?: SupportedCurrency;
 }
+/** Phone-keyed customer rollups (sk-only; a public key gets a `403`). */
+interface SalesCustomersClient {
+    list(query?: CustomerListQuery): Promise<CustomerListPage>;
+    /** `id` is the customer's E.164 phone. */
+    get(id: string, options?: CustomerGetOptions): Promise<CustomerGetResult>;
+    summary(query?: CustomerSummaryQuery): Promise<CustomerKpis>;
+}
+/** Business config (low-sensitivity — accepts a public or secret key). */
+interface SalesBusinessClient {
+    config(): Promise<BusinessConfig>;
+}
 /**
  * One isomorphic sales client — what a key may *do* is enforced by the backend,
  * not by hiding methods. A **public** key (`aranv_pk_…`) may `record` (the
@@ -1813,23 +1875,36 @@ interface SalesClientConfig extends SalesTransportConfig {
  * `@aranova/tracking-cli gen` for compile-time-checked `service` values.
  */
 interface SalesClient<TService extends string = string> {
-    record(input: Omit<SaleInput, 'currency' | 'occurred_at' | 'service'> & {
+    record(input: Omit<SaleInput, 'currency' | 'occurred_at' | 'service' | 'services'> & {
         service?: TService | null;
+        services?: Array<{
+            service: TService;
+            amount_cents: number;
+        }>;
         currency?: SupportedCurrency;
         occurred_at?: string;
     }): Promise<Sale>;
-    list(query?: SaleListQuery): Promise<SaleCursorPage>;
+    /** Keyset list with optional server sort + opt-in `total_count`. */
+    list(query?: SaleListQueryV2): Promise<SaleCursorPage>;
     /**
-     * Currency-grouped aggregations for the key's business (revenue per currency,
-     * AOV, distinct customers, by-service / by-currency / by-category breakdowns,
-     * and a revenue/count trend). Secret key only — a public key gets a `403`.
+     * Currency-grouped aggregations for the key's business. Additive v2 options:
+     * calendar/custom ranges, IANA `timezone`, `granularity`, and `compare_to`.
+     * Legacy `24h/7d/30d` keep their exact prior numbers. Secret key only.
      */
-    summary(query: SaleSummaryQuery): Promise<SaleSummary>;
+    summary(query: SaleSummaryQueryV2): Promise<SaleSummaryV2>;
     get(id: string): Promise<Sale>;
-    update(id: string, patch: Omit<SaleUpdateInput, 'service'> & {
+    update(id: string, patch: Omit<SaleUpdateInput, 'service' | 'services'> & {
         service?: TService | null;
+        services?: Array<{
+            service: TService;
+            amount_cents: number;
+        }>;
     }): Promise<Sale>;
     delete(id: string): Promise<void>;
+    /** Phone-keyed customer rollups (sk-only). */
+    customers: SalesCustomersClient;
+    /** Business config (pk or sk). */
+    business: SalesBusinessClient;
 }
 declare function createSalesClient<TService extends string = string>(config: SalesClientConfig): SalesClient<TService>;
 
@@ -1861,6 +1936,12 @@ declare function fromMinor(cents: number, currency: SupportedCurrency): number;
  * Uses the built-in `Intl.NumberFormat` — no extra dependency.
  */
 declare function formatMoney(cents: number, currency: SupportedCurrency, locale?: string): string;
+/**
+ * Format an ISO timestamp in a specific IANA time zone (e.g. `America/Toronto`),
+ * so dashboards stop hand-rolling `Intl`. Defaults to a short date-time; pass
+ * `opts` to override fields. The `timeZone` is always forced to the argument.
+ */
+declare function formatDateInTz(iso: string, timeZone: string, opts?: Intl.DateTimeFormatOptions, locale?: string): string;
 
 /**
  * Error thrown by the sales client (`createSalesClient`) on a
@@ -1989,6 +2070,11 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
      * loudly. Leave off in prod; turn on in dev to catch shape bugs early.
      */
     debug?: boolean;
+    /**
+     * Phone-field display + default-country config, read by `usePhoneField` /
+     * `<PhoneField>`. Display is customizable; the transmitted value is always E.164.
+     */
+    phone?: PhoneConfig;
 }
 interface TrackingProviderProps {
     /**
@@ -2024,4 +2110,71 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
 }
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type CurrencyRevenue, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleSummary, type SaleSummaryQuery, type SaleUpdateInput, type SalesCategoryBreakdown, type SalesClient, type SalesClientConfig, type SalesServiceBreakdown, type SalesTransportConfig, type SalesTrendPoint, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingOverviewRange, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, resetConsent, setConsentState, toMinor, useConsent, useConsentState, useGclid, useTrackingParams };
+/** Carries `createTracking({ phone })` config to `usePhoneField`. Separate from the
+ *  tracking client context so `useTracking()`'s type is untouched.
+ *
+ *  Caveat: this module is bundled into BOTH `@aranova/tracking-react` and
+ *  `@aranova/tracking-next`, so each package has its own context instance at
+ *  runtime. Within one installed package the provider + hook share it (correct);
+ *  mixing `createTracking` from one package with `usePhoneField` from the other
+ *  won't share config (the hook falls back to the `CA`/`national` defaults). Use a
+ *  single tracking package per app. */
+declare const PhoneConfigContext: react.Context<PhoneConfig | null>;
+/** Resolve the effective phone config (provider value or built-in defaults). */
+declare function usePhoneConfig(): {
+    defaultCountry: CountryCode;
+    display: PhoneDisplayFormat;
+};
+interface UsePhoneFieldOptions {
+    defaultValue?: string;
+    /** Overrides the provider's `defaultCountry`. */
+    country?: CountryCode;
+    /** Overrides the provider's `display` (applied to the settled value on blur). */
+    display?: PhoneDisplayFormat;
+    /** Notified with the canonical E.164 (or `null`) on every change. */
+    onValueChange?: (e164: string | null) => void;
+}
+interface PhoneInputProps {
+    value: string;
+    onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    onBlur: (event: FocusEvent<HTMLInputElement>) => void;
+    type: 'tel';
+    inputMode: 'tel';
+    autoComplete: 'tel';
+}
+interface PhoneFieldApi {
+    /** Display value for the `<input>` (live `AsYouType` while typing). */
+    value: string;
+    /** Canonical E.164 — what gets transmitted. `null` while invalid/incomplete. */
+    e164: string | null;
+    isValid: boolean;
+    /** Validation message, surfaced only after blur with non-empty invalid input. */
+    error: string | null;
+    parsed: ParsedPhone;
+    /** Spread onto an `<input>`: pre-wires value/onChange/onBlur/type/inputMode/autoComplete. */
+    inputProps: PhoneInputProps;
+}
+/** Headless phone field — the client owns the markup. */
+declare function usePhoneField(opts?: UsePhoneFieldOptions): PhoneFieldApi;
+interface PhoneFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'value' | 'onChange'> {
+    country?: CountryCode;
+    /** Controlled display value. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    /** Receives the native change event (RHF `register().onChange` or your own); the
+     *  event's `target.value` is already `AsYouType`-formatted. */
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+    /** Receives the canonical E.164 (or `null`) on every change. */
+    onE164Change?: (e164: string | null) => void;
+}
+/**
+ * Batteries-included phone input. Composes identically with react-hook-form
+ * `{...register('phone')}` and with controlled state — the `AsYouType` +
+ * mutate-`e.target.value`-before-`onChange` technique lives inside, so RHF and
+ * controlled parents both receive the formatted value, and the wire value stays
+ * E.164.
+ */
+declare const PhoneField: react.ForwardRefExoticComponent<PhoneFieldProps & react.RefAttributes<HTMLInputElement>>;
+
+export { AranovaApiError, type AutomaticEventName, type BusinessConfig, type BusinessConfigFeatures, type BusinessConfigService, type CompareTo, ConsentBanner, type ConsentBannerProps, ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type CurrencyRevenue, type CustomerCurrencyDelta, type CustomerCurrencyTotal, type CustomerGetOptions, type CustomerGetResult, type CustomerKpis, type CustomerKpisDeltas, type CustomerKpisPrevious, type CustomerListPage, type CustomerListQuery, type CustomerProfile, type CustomerSegment, type CustomerSegmentCount, type CustomerSortField, type CustomerSummary, type CustomerSummaryQuery, type DistinctCustomersByCurrency, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, FormSubmitConfig, FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type Granularity, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type NamedRange, type PageViewConfig, type PageViewMetadata, ParsedPhone, type PhoneClickConfig, type PhoneClickMetadata, PhoneConfig, PhoneConfigContext, PhoneDisplayFormat, PhoneField, type PhoneFieldApi, type PhoneFieldProps, type PhoneInputProps, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleKeysetSortField, type SaleListPage, type SaleListQuery, type SaleListQueryV2, type SaleService, type SaleServiceInput, type SaleSortOrder, type SaleSummary, type SaleSummaryPrevious, type SaleSummaryQuery, type SaleSummaryQueryV2, type SaleSummaryV2, type SaleUpdateInput, type SalesBusinessClient, type SalesCategoryBreakdown, type SalesClient, type SalesClientConfig, type SalesCustomersClient, type SalesServiceBreakdown, type SalesTransportConfig, type SalesTrendPoint, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SummaryCurrencyDelta, type SummaryDeltas, type SummaryWindow, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, type TrackingOverviewRange, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, type UsePhoneFieldOptions, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatDateInTz, formatMoney, fromMinor, getConsentState, resetConsent, setConsentState, toMinor, useConsent, useConsentState, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };