@aranova/tracking-next 0.11.0 → 0.12.1

package/dist/index.d.ts

@@ -1,14 +1,18 @@
-import { C as ConsentState, T as TrackingInstallSurface, a as TrackingEnvironment, b as TrackingClientContext, c as TrackingParams, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, G as GtagEnvironmentMap } from './types-BPJLgMsG.js';
-export { f as TrackingInitConfig } from './types-BPJLgMsG.js';
+import { C as ConsentState, a as TrackingInstallSurface, b as TrackingEnvironment, c as TrackingClientContext, T 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-dd1tW7sb.js';
+export { D as DEFAULT_PHONE_COUNTRY, J as JsonValue, i as TrackedField, j as TrackingInitConfig, k as formSubmitConfigSchema, l as formSubmitMetadataSchema, m as formatPhone, n as formatPhoneAsTyped, o as jsonValueSchema, p as parsePhone, q as phoneField, t as toE164 } from './phone-utils-dd1tW7sb.js';
 import { z } from 'zod';
 import * as src from 'src';
-import { ReactNode, CSSProperties } from 'react';
+export { AranovaApiError, BusinessConfig, BusinessConfigFeatures, BusinessConfigService, CompareTo, CurrencyRevenue, CustomerCurrencyDelta, CustomerCurrencyTotal, CustomerGetOptions, CustomerGetResult, CustomerKpis, CustomerKpisDeltas, CustomerKpisPrevious, CustomerListPage, CustomerListQuery, CustomerProfile, CustomerSegment, CustomerSegmentCount, CustomerSortField, CustomerSummary, CustomerSummaryQuery, DistinctCustomersByCurrency, Granularity, NAMED_RANGES, NamedRange, PublicServiceItem, SUPPORTED_CURRENCIES, Sale, SaleCursorPage, SaleFilters, SaleInput, SaleItem, SaleItemInput, SaleKeysetSortField, SaleListPage, SaleListQuery, SaleListQueryV2, SaleService, SaleServiceInput, SaleSortField, SaleSortOrder, SaleSummary, SaleSummaryPrevious, SaleSummaryQuery, SaleSummaryQueryV2, SaleSummaryV2, SaleUpdateInput, SalesBusinessClient, SalesCategoryBreakdown, SalesClient, SalesClientConfig, SalesCustomersClient, SalesServiceBreakdown, SalesTransportConfig, SalesTrendPoint, SummaryCurrencyDelta, SummaryDeltas, SummaryWindow, SupportedCurrency, TRACKING_RANGES, TrackingOverviewRange, createSalesClient, fetchServices, formatDateInTz, formatMoney, fromMinor, saleCreateSchema, saleItemSchema, saleServiceSchema, saleUpdateSchema, salesRequest, toMinor } from './sales.js';
+import * as react from 'react';
+import { ReactNode, CSSProperties, InputHTMLAttributes, ChangeEvent, FocusEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CountryCode } from 'libphonenumber-js';
+export { CountryCode } from 'libphonenumber-js';
 
 /**
  * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
  */
-type GtagConsentValue = 'granted' | 'denied';
+type GtagConsentValue = "granted" | "denied";
 /**
  * Read the persisted visitor consent state from localStorage.
  *
@@ -125,6 +129,19 @@ type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
 declare const ctaClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
 type CtaClickConfig = z.infer<typeof ctaClickConfigSchema>;
 
+/**
+ * Registered trigger names reported by the SDK heartbeat.
+ */
+declare const sdkHeartbeatTriggersSchema: z.ZodObject<{
+    automatic: z.ZodArray<z.ZodString, "many">;
+    manual: z.ZodArray<z.ZodString, "many">;
+}, "strict", z.ZodTypeAny, {
+    automatic: string[];
+    manual: string[];
+}, {
+    automatic: string[];
+    manual: string[];
+}>;
 /**
  * Metadata for the SDK-internal `sdk_heartbeat` event.
  *
@@ -234,131 +251,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.
  *
@@ -412,14 +304,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>;
@@ -435,9 +327,9 @@ declare const pageViewMetadataSchema: z.ZodObject<{
     }>>>;
 }, "strict", z.ZodTypeAny, {
     page: {
+        path: string;
         search: string;
         title: string | null;
-        path: string;
         hash: string;
     };
     referrer: string | null;
@@ -447,9 +339,9 @@ declare const pageViewMetadataSchema: z.ZodObject<{
     } | null | undefined;
 }, {
     page: {
+        path: string;
         search: string;
         title: string | null;
-        path: string;
         hash: string;
     };
     referrer: string | null;
@@ -552,6 +444,7 @@ type ScrollDepthConfig = z.infer<typeof scrollDepthConfigSchema>;
  */
 declare const SPECIFIC_PAGE_NAMES: readonly ["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"];
 type SpecificPageName = (typeof SPECIFIC_PAGE_NAMES)[number];
+declare const specificPageNameSchema: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
 /**
  * Metadata for the automatic `specific_page_visit` event.
  *
@@ -648,6 +541,7 @@ declare const timeOnSiteConfigSchema: z.ZodObject<{
 }>;
 type TimeOnSiteConfig = z.infer<typeof timeOnSiteConfigSchema>;
 
+type EventKind = "automatic" | "manual";
 declare const EVENT_REGISTRY: {
     readonly page_view: {
         readonly kind: "automatic";
@@ -658,14 +552,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>;
@@ -681,9 +575,9 @@ declare const EVENT_REGISTRY: {
             }>>>;
         }, "strict", z.ZodTypeAny, {
             page: {
+                path: string;
                 search: string;
                 title: string | null;
-                path: string;
                 hash: string;
             };
             referrer: string | null;
@@ -693,9 +587,9 @@ declare const EVENT_REGISTRY: {
             } | null | undefined;
         }, {
             page: {
+                path: string;
                 search: string;
                 title: string | null;
-                path: string;
                 hash: string;
             };
             referrer: string | null;
@@ -939,33 +833,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<{
@@ -980,10 +874,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: {
@@ -994,10 +888,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: {
@@ -1074,13 +968,13 @@ type EventName = keyof typeof EVENT_REGISTRY;
  * Automatic events are not accepted by the typed `trackEvent()` API.
  */
 type AutomaticEventName = {
-    [K in EventName]: (typeof EVENT_REGISTRY)[K]['kind'] extends 'automatic' ? K : never;
+    [K in EventName]: (typeof EVENT_REGISTRY)[K]["kind"] extends "automatic" ? K : never;
 }[EventName];
 /**
  * Event names that consumer code can fire manually after registering them.
  */
 type ManualEventName = {
-    [K in EventName]: (typeof EVENT_REGISTRY)[K]['kind'] extends 'manual' ? K : never;
+    [K in EventName]: (typeof EVENT_REGISTRY)[K]["kind"] extends "manual" ? K : never;
 }[EventName];
 type MetadataByName = {
     page_view: PageViewMetadata;
@@ -1119,6 +1013,14 @@ type EventMetadata<K extends EventName> = MetadataByName[K];
  * Trigger registration config type for a specific tracking event.
  */
 type EventConfig<K extends EventName> = ConfigByName[K];
+/**
+ * Runtime list of automatic event names.
+ */
+declare const ALL_AUTOMATIC_EVENT_NAMES: readonly AutomaticEventName[];
+/**
+ * Runtime list of manual event names.
+ */
+declare const ALL_MANUAL_EVENT_NAMES: readonly ManualEventName[];
 /**
  * Trigger registry passed to `createTracking({ triggers })`.
  *
@@ -1146,18 +1048,18 @@ type EventConfig<K extends EventName> = ConfigByName[K];
  */
 type TriggerRegistryConfig = {
     automatic: {
-        page_view: EventConfig<'page_view'>;
+        page_view: EventConfig<"page_view">;
     } & Partial<{
-        time_on_site: EventConfig<'time_on_site'>;
-        specific_page_visit: EventConfig<'specific_page_visit'>;
-        scroll_depth: EventConfig<'scroll_depth'>;
-        multi_page_session: EventConfig<'multi_page_session'>;
-        form_start: EventConfig<'form_start'>;
+        time_on_site: EventConfig<"time_on_site">;
+        specific_page_visit: EventConfig<"specific_page_visit">;
+        scroll_depth: EventConfig<"scroll_depth">;
+        multi_page_session: EventConfig<"multi_page_session">;
+        form_start: EventConfig<"form_start">;
     }>;
     manual?: Partial<{
-        form_submit: EventConfig<'form_submit'>;
-        phone_click: EventConfig<'phone_click'>;
-        cta_click: EventConfig<'cta_click'>;
+        form_submit: EventConfig<"form_submit">;
+        phone_click: EventConfig<"phone_click">;
+        cta_click: EventConfig<"cta_click">;
     }>;
 };
 /**
@@ -1166,11 +1068,25 @@ type TriggerRegistryConfig = {
  * Used by `TypedTrackingClient` so `trackEvent()` only accepts events the
  * consumer explicitly enabled.
  */
-type RegisteredManualEvents<TRegistry extends TriggerRegistryConfig> = Extract<keyof NonNullable<TRegistry['manual']>, ManualEventName>;
+type RegisteredManualEvents<TRegistry extends TriggerRegistryConfig> = Extract<keyof NonNullable<TRegistry["manual"]>, ManualEventName>;
 /**
  * Automatic event names registered in a concrete trigger registry.
  */
-type RegisteredAutomaticEvents<TRegistry extends TriggerRegistryConfig> = Extract<keyof TRegistry['automatic'], AutomaticEventName>;
+type RegisteredAutomaticEvents<TRegistry extends TriggerRegistryConfig> = Extract<keyof TRegistry["automatic"], AutomaticEventName>;
+/**
+ * Discriminated union of valid manual tracking calls for a registry.
+ */
+type TrackableEvent<TRegistry extends TriggerRegistryConfig> = {
+    [K in RegisteredManualEvents<TRegistry>]: {
+        eventType: K;
+        metadata: EventMetadata<K>;
+    };
+}[RegisteredManualEvents<TRegistry>];
+declare function getEventDefinition(name: EventName): {
+    kind: EventKind;
+    metadataSchema: z.ZodTypeAny;
+    configSchema: z.ZodTypeAny;
+};
 
 /**
  * Input accepted by the low-level stringly-typed client.
@@ -1248,569 +1164,6 @@ interface TypedTrackingClient<TRegistry extends TriggerRegistryConfig> {
     getVisitorId(): string;
 }
 
-/**
- * Sales / Conversions wire schemas — the client-side source of truth.
- *
- * `saleCreateSchema` is mirrored by `SaleCreateSchema` in
- * `apps/api/src/schemas/tracking_sales.py` and enforced by the backend drift
- * test (the `resources` section of `events.schema.json`). Keep them in lockstep.
- *
- * Money is **integer minor units (cents)**; `quantity` is a decimal string;
- * `currency` is the required `SupportedCurrency` enum.
- */
-declare const SUPPORTED_CURRENCIES: readonly ["USD", "CAD"];
-type SupportedCurrency = (typeof SUPPORTED_CURRENCIES)[number];
-declare const TRACKING_ENVIRONMENTS: readonly ["production", "development"];
-declare const saleItemSchema: z.ZodObject<{
-    external_item_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    quantity: z.ZodString;
-    unit_price_cents: z.ZodNumber;
-    unit_cost_cents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-}, "strict", z.ZodTypeAny, {
-    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;
-}, {
-    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;
-}>;
-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.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    occurred_at: z.ZodString;
-    environment: z.ZodDefault<z.ZodEnum<["production", "development"]>>;
-    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
-        external_item_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        quantity: z.ZodString;
-        unit_price_cents: z.ZodNumber;
-        unit_cost_cents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    }, "strict", z.ZodTypeAny, {
-        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;
-    }, {
-        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;
-    }>, "many">>;
-    metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-    customer_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    customer_phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    customer_email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, "strict", z.ZodTypeAny, {
-    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;
-        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;
-        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;
-}>;
-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>;
-    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        external_item_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        quantity: z.ZodString;
-        unit_price_cents: z.ZodNumber;
-        unit_cost_cents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    }, "strict", z.ZodTypeAny, {
-        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;
-    }, {
-        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;
-    }>, "many">>;
-    metadata: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-    customer_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    customer_phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    customer_email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, "strict", z.ZodTypeAny, {
-    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;
-        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;
-}>;
-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 {
-    id: string;
-    external_item_id: string | null;
-    name: string | null;
-    category: string | null;
-    quantity: string;
-    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;
-    business_name?: string | null;
-    external_id: string | null;
-    currency: SupportedCurrency;
-    amount_total_cents: number;
-    description: string | null;
-    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;
-    customer_name: string | null;
-    customer_phone: string | null;
-    customer_email: string | null;
-    created_at: string;
-    updated_at: string;
-    items: SaleItem[];
-}
-interface SaleListPage {
-    items: Sale[];
-    total: number;
-}
-interface SaleCursorPage {
-    items: Sale[];
-    next_cursor: string | null;
-}
-/**
- * Comprehensive filter shape mirrored from the backend's `SaleQueryFilters`.
- *
- * `search` runs case-insensitively across `customer_name`, `customer_phone`,
- * `customer_email`, `description`, and `external_id` — the human-facing
- * columns. `service_id` is the resolved per-business service UUID (different
- * from the create-time `service` *key*).
- */
-interface SaleFilters {
-    business_id?: string;
-    external_id?: string;
-    service_id?: string;
-    currency?: SupportedCurrency;
-    environment?: (typeof TRACKING_ENVIRONMENTS)[number];
-    since?: string;
-    until?: string;
-    min_amount_cents?: number;
-    max_amount_cents?: number;
-    search?: string;
-}
-/**
- * Full query input for `SalesClient.list()` — filters + pagination.
- *
- * Pagination is **keyset (cursor)**: `next_cursor` returned by one page is
- * passed back as `cursor` on the next. `null` / undefined cursor = first page.
- *
- * Ordering on this endpoint is fixed at **`occurred_at DESC, id DESC`** — the
- * cursor encodes a position in that index, so a different sort would
- * invalidate cursors mid-pagination. For ad-hoc sorted reads use the
- * dashboard admin endpoint, which is offset-paginated.
- */
-interface SaleListQuery extends SaleFilters {
-    limit?: number;
-    cursor?: string | null;
-}
-declare const TRACKING_RANGES: readonly ["24h", "7d", "30d"];
-type TrackingOverviewRange = (typeof TRACKING_RANGES)[number];
-/** Query input for `SalesClient.summary()` — filters + range + options. */
-interface SaleSummaryQuery extends SaleFilters {
-    range: TrackingOverviewRange;
-    /** Include the per-category line-item breakdown (extra join; default false). */
-    include_categories?: boolean;
-    /** Surface soft-deleted services individually (flagged "(deleted)") instead of
-     * rolling them into a single "Deleted services" bucket. Default false. */
-    include_deleted_services?: boolean;
-    /** Cap on the by-service / by-category rows (1–50, default 10). */
-    top_n?: number;
-}
-interface CurrencyRevenue {
-    currency: SupportedCurrency;
-    sale_count: number;
-    revenue_cents: number;
-    average_order_value_cents: number;
-}
-interface SalesServiceBreakdown {
-    service_id: string | null;
-    service_key: string | null;
-    /** "Unassigned" when the sale has no service. */
-    service_label: string | null;
-    currency: SupportedCurrency;
-    sale_count: number;
-    revenue_cents: number;
-}
-interface SalesCategoryBreakdown {
-    category: string | null;
-    currency: SupportedCurrency;
-    /** sum(unit_price_cents * quantity) — advisory, not authoritative. */
-    revenue_cents: number;
-    /** Decimal string. */
-    quantity: string;
-}
-interface SalesTrendPoint {
-    bucket_start: string;
-    currency: SupportedCurrency;
-    sale_count: number;
-    revenue_cents: number;
-}
-interface SaleSummary {
-    range: TrackingOverviewRange;
-    business_id: string | null;
-    metrics: {
-        sale_count: number;
-        distinct_customers: number;
-        by_currency: CurrencyRevenue[];
-    };
-    by_service: SalesServiceBreakdown[];
-    by_currency: CurrencyRevenue[];
-    by_category: SalesCategoryBreakdown[];
-    series: SalesTrendPoint[];
-}
-
-/** Shared config for every sales HTTP helper. */
-interface SalesTransportConfig {
-    /** Public (`aranv_pk_…`) or secret (`aranv_sk_…`) API key. */
-    apiKey: string;
-    /**
-     * Base tracking endpoint, e.g. `https://aranovainternal-production.up.railway.app/tracking`.
-     * The `/sales` path is appended by the helpers.
-     */
-    endpoint: string;
-    /** Optional SDK identity headers (mirrors the event ingest client). */
-    sdkVersion?: string;
-    packageName?: string;
-    surface?: string;
-    environment?: string;
-}
-
-/** Config for {@link createSalesClient}. */
-interface SalesClientConfig extends SalesTransportConfig {
-    /** Applied when an individual `record()` call omits `currency`. */
-    defaultCurrency?: SupportedCurrency;
-}
-/**
- * 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
- * backend rejects reads/CRUD from it with a `403`); a **secret** key
- * (`aranv_sk_…`), used **server-side only**, gets full read/list/update/delete.
- * Never ship a secret key in a browser bundle.
- *
- * Generic over the service-key union `TService`: bind the type emitted by
- * `@aranova/tracking-cli gen` for compile-time-checked `service` values.
- */
-interface SalesClient<TService extends string = string> {
-    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>;
-    /**
-     * 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`.
-     */
-    summary(query: SaleSummaryQuery): Promise<SaleSummary>;
-    get(id: string): Promise<Sale>;
-    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>;
-}
-declare function createSalesClient<TService extends string = string>(config: SalesClientConfig): SalesClient<TService>;
-
-/** A business's active service, as returned by `GET /tracking/services`. */
-interface PublicServiceItem {
-    key: string;
-    label: string;
-}
-/**
- * Fetch the caller's business's active service taxonomy. Accepts a public or
- * secret key (the taxonomy is low-sensitivity category names). Powers the
- * `@aranova/tracking-cli gen` codegen.
- */
-declare function fetchServices(config: SalesTransportConfig): Promise<PublicServiceItem[]>;
-
-/**
- * Convert a major amount (dollars `250.5`) to integer minor units (`25050`).
- *
- * Convenience only — the wire is always integer cents. Uses float multiply +
- * `Math.round`, so values that aren't exactly representable in binary float
- * (e.g. `1.005`) can round to the neighbouring cent. If you already hold an
- * exact cents integer, pass it straight through and skip this helper.
- */
-declare function toMinor(amount: number, currency: SupportedCurrency): number;
-/** Convert integer minor units (`25050`) to a major amount (`250.5`). */
-declare function fromMinor(cents: number, currency: SupportedCurrency): number;
-/**
- * Format integer minor units as a localized currency string (e.g. `"$250.50"`).
- * Uses the built-in `Intl.NumberFormat` — no extra dependency.
- */
-declare function formatMoney(cents: number, currency: SupportedCurrency, locale?: string): string;
-
-/**
- * Error thrown by the sales client (`createSalesClient`) on a
- * non-2xx response. Unlike the fire-and-forget event queue (which swallows
- * failures), a sale is a transaction the caller must be able to react to.
- */
-declare class AranovaApiError extends Error {
-    readonly status: number;
-    readonly code: string | undefined;
-    readonly requestId: string | undefined;
-    constructor(message: string, options: {
-        status: number;
-        code?: string;
-        requestId?: string;
-    });
-}
-
 /**
  * Default non-blocking consent banner.
  *
@@ -1864,11 +1217,11 @@ interface ConsentBannerProps {
     onAccept?: () => void;
     onDecline?: () => void;
     /** Where the banner docks. Default: `"bottom"`. */
-    position?: 'top' | 'bottom';
+    position?: "top" | "bottom";
     /**
      * Visual theme. `"auto"` follows `prefers-color-scheme`. Default: `"light"`.
      */
-    theme?: 'light' | 'dark' | 'auto';
+    theme?: "light" | "dark" | "auto";
     /** Class added to the outer wrapper for additional styling hooks. */
     className?: string;
     /** Inline style overrides applied to the outer wrapper after the defaults. */
@@ -1988,6 +1341,11 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
      * analytics can never throw into the host app.
      */
     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 {
     /**
@@ -2019,4 +1377,61 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
  */
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, 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 SaleService, type SaleServiceInput, 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, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, type TrackingOverviewRange, TrackingParams, type TrackingProviderProps, 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 };
+/** 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 { ALL_AUTOMATIC_EVENT_NAMES, ALL_MANUAL_EVENT_NAMES, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, EVENT_REGISTRY, type EventConfig, type EventKind, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, FormSubmitConfig, FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, ParsedPhone, type PhoneClickConfig, type PhoneClickMetadata, PhoneConfig, PhoneDisplayFormat, PhoneField, type PhoneFieldApi, type PhoneFieldProps, type PhoneInputProps, type RegisteredAutomaticEvents, type RegisteredManualEvents, SPECIFIC_PAGE_NAMES, type ScrollDepthConfig, type ScrollDepthMetadata, type SdkHeartbeatConfig, type SdkHeartbeatMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackableEvent, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, type UsePhoneFieldOptions, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, ctaClickConfigSchema, ctaClickMetadataSchema, formStartConfigSchema, formStartMetadataSchema, getConsentState, getEventDefinition, multiPageSessionConfigSchema, multiPageSessionMetadataSchema, pageViewConfigSchema, pageViewMetadataSchema, phoneClickConfigSchema, phoneClickMetadataSchema, resetConsent, scrollDepthConfigSchema, scrollDepthMetadataSchema, sdkHeartbeatConfigSchema, sdkHeartbeatMetadataSchema, sdkHeartbeatTriggersSchema, setConsentState, specificPageNameSchema, specificPageVisitConfigSchema, specificPageVisitMetadataSchema, timeOnSiteConfigSchema, timeOnSiteMetadataSchema, useConsent, useConsentState, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };