@aranova/tracking-next 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -1,9 +1,12 @@
-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-DZ0Ger64.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-DZ0Ger64.js';
 import { z } from 'zod';
 import * as src from 'src';
-import { ReactNode, CSSProperties } from 'react';
+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', ...)`.
@@ -234,131 +237,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 +290,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 +313,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 +325,9 @@ declare const pageViewMetadataSchema: z.ZodObject<{
     } | null | undefined;
 }, {
     page: {
+        path: string;
         search: string;
         title: string | null;
-        path: string;
         hash: string;
     };
     referrer: string | null;
@@ -658,14 +536,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 +559,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 +571,9 @@ declare const EVENT_REGISTRY: {
             } | null | undefined;
         }, {
             page: {
+                path: string;
                 search: string;
                 title: string | null;
-                path: string;
                 hash: string;
             };
             referrer: string | null;
@@ -939,33 +817,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 +858,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 +872,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: {
@@ -1283,12 +1161,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<{
@@ -1319,7 +1217,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: {
@@ -1331,20 +1228,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;
@@ -1358,9 +1312,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>;
@@ -1392,10 +1356,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;
@@ -1410,10 +1378,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;
@@ -1428,6 +1444,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 {
@@ -1439,6 +1456,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;
@@ -1450,6 +1474,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;
@@ -1467,7 +1492,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`.
  *
@@ -1480,6 +1509,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;
@@ -1503,6 +1534,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. */
@@ -1558,6 +1598,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 {
@@ -1580,6 +1789,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
@@ -1591,23 +1811,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>;
 
@@ -1639,6 +1872,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
@@ -1833,6 +2072,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 {
     /**
@@ -1864,4 +2108,71 @@ 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 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 };
+/** 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 };