@aranova/tracking-react 0.13.0 → 0.14.1

package/dist/sales-7w7-Ud60.d.mts

@@ -0,0 +1,895 @@
+import { z } from 'zod';
+
+interface ServiceFiring {
+    send_to: string;
+    /** Action's configured default value (cents); the SDK fires it only when a sale has no amount. */
+    value_cents?: number | null;
+    currency?: string | null;
+}
+/** Serializable on-page trigger (owned by tracking-core/src/events/trigger-spec.ts). The shape
+ * varies by `event_type`; only the parameter for that type is set. */
+interface ConfigTriggerSpec {
+    event_type: string;
+    threshold_percent?: number;
+    threshold_seconds?: number;
+    page_threshold?: number;
+    page_name?: string;
+}
+/** One unified conversion goal: a revenue `sale` or an on-page `event`. */
+interface ConversionGoal {
+    key: string;
+    label?: string;
+    kind: "sale" | "event";
+    /** Structured fire-when for event-goals; null for sales. */
+    trigger: ConfigTriggerSpec | null;
+    firing: ServiceFiring | null;
+}
+interface ConversionConfig {
+    schema_version: number;
+    config_version: number;
+    business_id?: string;
+    customer_id?: string | null;
+    environment?: string;
+    gtag_ids: Record<string, string>;
+    meta_pixel_ids: Record<string, string>;
+    /** LEGACY: sale-goals only (for pre-unified-goal readers). */
+    services: Array<{
+        key: string;
+        label?: string;
+        firing: ServiceFiring | null;
+    }>;
+    /** Unified goal list (sales + on-page events). Superset of `services`. */
+    goals: ConversionGoal[];
+}
+interface ConversionConfigStore {
+    /** Firing config for a goal/service key, or null when it doesn't fire on-site. */
+    getFiring(key: string): ServiceFiring | null;
+    /** The full goal for a key, or null when unknown. */
+    getGoal(key: string): ConversionGoal | null;
+    /** Every adopted goal (sales + events). */
+    listGoals(): ConversionGoal[];
+    /** The currently adopted config (baked / cached fallback until the fetch lands). */
+    current(): ConversionConfig | null;
+    /** True once a config is adopted (seeded synchronously from cache/baked, or fetched). */
+    isReady(): boolean;
+    /**
+     * Run `listener` when a config first becomes available — immediately if already
+     * ready, otherwise on the first adopt. Lets auto-fire replay automatic events that
+     * occurred before the async CDN fetch resolved. Returns an unsubscribe fn.
+     */
+    onResolve(listener: () => void): () => void;
+    /** Force a background revalidate against the CDN object. */
+    revalidate(): Promise<void>;
+}
+interface ResolveConversionConfigOptions {
+    /** Full URL of the per-business CDN object. */
+    cdnUrl: string;
+    /** Offline-correct fallback (e.g. the CLI-baked snapshot). */
+    baked?: ConversionConfig | null;
+    /** Injectable for tests / non-global-fetch runtimes. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resolve the config with stale-while-revalidate: seed synchronously from the
+ * sessionStorage cache (or the baked fallback), then conditionally re-fetch the CDN object
+ * with `If-None-Match`. A fetched object is adopted only if its `config_version` is strictly
+ * greater than what's cached, so a reordered edge copy can't downgrade fresher state.
+ * Non-blocking and browser-only; a failed fetch leaves the seed in place.
+ */
+declare function resolveConversionConfig(options: ResolveConversionConfigOptions): ConversionConfigStore;
+
+/**
+ * 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";
+    environment: "production" | "development";
+    occurred_at: string;
+    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;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    service?: string | 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;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    environment?: "production" | "development" | undefined;
+    service?: string | null | undefined;
+    amount_total_cents?: number | null | undefined;
+    external_id?: string | null | undefined;
+    description?: string | null | 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";
+    environment: "production" | "development";
+    occurred_at: string;
+    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;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    service?: string | 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;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    environment?: "production" | "development" | undefined;
+    service?: string | null | undefined;
+    amount_total_cents?: number | null | undefined;
+    external_id?: string | null | undefined;
+    description?: string | null | 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, {
+    currency?: "USD" | "CAD" | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    service?: string | null | undefined;
+    amount_total_cents?: number | undefined;
+    description?: string | null | 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;
+}, {
+    currency?: "USD" | "CAD" | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    service?: string | null | undefined;
+    amount_total_cents?: number | undefined;
+    description?: string | null | 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;
+}>, {
+    currency?: "USD" | "CAD" | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    service?: string | null | undefined;
+    amount_total_cents?: number | undefined;
+    description?: string | null | 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;
+}, {
+    currency?: "USD" | "CAD" | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    service?: string | null | undefined;
+    amount_total_cents?: number | undefined;
+    description?: string | null | 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;
+    /** Populated only when `want_total` was requested (a single indexed COUNT). */
+    total_count?: number;
+    has_more?: boolean;
+}
+/**
+ * Sortable columns on the secret-key (keyset) and admin (offset) list endpoints.
+ * `business_name` only applies to the cross-business admin list — it sorts the
+ * joined `businesses.name` column.
+ */
+type SaleSortField = "occurred_at" | "created_at" | "amount_total_cents" | "customer_name" | "business_name";
+type SaleSortOrder = "asc" | "desc";
+/**
+ * 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;
+    /** E.164 phone — the canonical customer key; filters sales for one customer. */
+    customer_phone?: 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;
+}
+/** 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. */
+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[];
+}
+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 {
+    /** 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;
+}
+/**
+ * Single awaited request used by every sales helper. Unlike the event queue,
+ * this surfaces failures: any non-2xx rejects with an {@link AranovaApiError}.
+ * Returns `undefined` for 204 No Content.
+ */
+declare function salesRequest<T>(config: SalesTransportConfig, method: string, path: string, body?: unknown): Promise<T>;
+
+/** Config for {@link createSalesClient}. */
+interface SalesClientConfig extends SalesTransportConfig {
+    /** Applied when an individual `record()` call omits `currency`. */
+    defaultCurrency?: SupportedCurrency;
+    /**
+     * GAP28: when present, `record()` ALSO fires a real-time on-site conversion
+     * (`gtag('event','conversion')`) for any recorded service that has a `firing` send_to in
+     * the resolved config. Consent-gated + de-duped; no-ops server-side. Wire it from
+     * `resolveConversionConfig(...)`.
+     */
+    firing?: Pick<ConversionConfigStore, "getFiring">;
+}
+/** 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
+ * 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>;
+    /**
+     * Record a revenue sale — the intent-revealing alias of {@link record} in the unified-goal
+     * API. POSTs `/sales` and ALSO fires the on-site conversion when the sale-goal is
+     * WEBPAGE-mapped. Use this for anything with real revenue; use {@link trackConversion} for a
+     * non-revenue on-page event.
+     */
+    recordSale(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>;
+    /**
+     * Fire ONLY the on-site conversion for an event-goal `key` — for MANUAL event-goals
+     * (`form_submit`, `phone_click`, `cta_click`) the consumer triggers explicitly. No `/sales`
+     * write. No-ops when the goal isn't WEBPAGE-mapped (no resolved `send_to`) or the config
+     * isn't wired. Consent-gated + de-duped. (Automatic event-goals fire themselves — no call.)
+     */
+    trackConversion(key: string, options?: {
+        transactionId?: string | null;
+        value?: number | null;
+        currency?: SupportedCurrency;
+    }): void;
+    /** Keyset list with optional server sort + opt-in `total_count`. */
+    list(query?: SaleListQueryV2): Promise<SaleCursorPage>;
+    /**
+     * 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: SaleSummaryQueryV2): Promise<SaleSummaryV2>;
+    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>;
+    /** 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>;
+
+/**
+ * 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;
+    });
+}
+
+/**
+ * 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;
+/**
+ * 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;
+
+/** 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[]>;
+
+export { type SalesCustomersClient as $, AranovaApiError as A, type BusinessConfig as B, type ConversionConfig as C, type DistinctCustomersByCurrency as D, type SaleItemInput as E, type SaleKeysetSortField as F, type Granularity as G, type SaleListPage as H, type SaleListQuery as I, type SaleListQueryV2 as J, type SaleService as K, type SaleServiceInput as L, type SaleSortField as M, NAMED_RANGES as N, type SaleSortOrder as O, type PublicServiceItem as P, type SaleSummary as Q, type SaleSummaryPrevious as R, SUPPORTED_CURRENCIES as S, type SaleSummaryQuery as T, type SaleSummaryQueryV2 as U, type SaleSummaryV2 as V, type SaleUpdateInput as W, type SalesBusinessClient as X, type SalesCategoryBreakdown as Y, type SalesClient as Z, type SalesClientConfig as _, type BusinessConfigFeatures as a, type SalesServiceBreakdown as a0, type SalesTransportConfig as a1, type SalesTrendPoint as a2, type SummaryCurrencyDelta as a3, type SummaryDeltas as a4, type SummaryWindow as a5, type SupportedCurrency as a6, TRACKING_RANGES as a7, type TrackingOverviewRange as a8, createSalesClient as a9, fetchServices as aa, formatDateInTz as ab, formatMoney as ac, fromMinor as ad, resolveConversionConfig as ae, saleCreateSchema as af, saleItemSchema as ag, saleServiceSchema as ah, saleUpdateSchema as ai, salesRequest as aj, toMinor as ak, type BusinessConfigService as b, type CompareTo as c, type ConversionConfigStore as d, type CurrencyRevenue as e, type CustomerCurrencyDelta as f, type CustomerCurrencyTotal as g, type CustomerGetOptions as h, type CustomerGetResult as i, type CustomerKpis as j, type CustomerKpisDeltas as k, type CustomerKpisPrevious as l, type CustomerListPage as m, type CustomerListQuery as n, type CustomerProfile as o, type CustomerSegment as p, type CustomerSegmentCount as q, type CustomerSortField as r, type CustomerSummary as s, type CustomerSummaryQuery as t, type NamedRange as u, type Sale as v, type SaleCursorPage as w, type SaleFilters as x, type SaleInput as y, type SaleItem as z };