@aranova/tracking-react 0.9.1 → 0.11.0

package/README.md

@@ -162,8 +162,12 @@ export default async function handler(_req, res) {
 }
 ```
 
-A public-key client calling `list`/`get`/`update`/`delete` gets a `403` telling it
-to use a secret key server-side.
+`sales.summary({ range: '30d' })` returns currency-grouped aggregations (revenue and
+average order value per currency, distinct customers, by-service / by-currency /
+by-category breakdowns, and a revenue/count trend) — also a secret-key read.
+
+A public-key client calling `list`/`summary`/`get`/`update`/`delete` gets a `403`
+telling it to use a secret key server-side.
 
 Generate the typed `AranovaService` union from your dashboard services with the CLI
 (install it as a **devDependency**):

package/dist/index.d.mts

@@ -1505,12 +1505,32 @@ declare const saleItemSchema: z.ZodObject<{
     category?: string | null | undefined;
     unit_cost_cents?: number | null | undefined;
 }>;
-declare const saleCreateSchema: z.ZodObject<{
+declare const saleServiceSchema: z.ZodObject<{
+    service: z.ZodString;
+    amount_cents: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    service: string;
+    amount_cents: number;
+}, {
+    service: string;
+    amount_cents: number;
+}>;
+declare const saleCreateSchema: z.ZodEffects<z.ZodObject<{
     external_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     service: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    services: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        service: z.ZodString;
+        amount_cents: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        service: string;
+        amount_cents: number;
+    }, {
+        service: string;
+        amount_cents: number;
+    }>, "many">>>;
     currency: z.ZodEnum<["USD", "CAD"]>;
-    amount_total_cents: z.ZodNumber;
+    amount_total_cents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     occurred_at: z.ZodString;
     environment: z.ZodDefault<z.ZodEnum<["production", "development"]>>;
     items: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1541,7 +1561,6 @@ declare const saleCreateSchema: z.ZodObject<{
     customer_email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
     currency: "USD" | "CAD";
-    amount_total_cents: number;
     occurred_at: string;
     environment: "production" | "development";
     items: {
@@ -1553,20 +1572,77 @@ declare const saleCreateSchema: z.ZodObject<{
         unit_cost_cents?: number | null | undefined;
     }[];
     metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | null | undefined;
     external_id?: string | null | undefined;
     description?: string | null | undefined;
-    service?: string | null | undefined;
     customer_name?: string | null | undefined;
     customer_phone?: string | null | undefined;
     customer_email?: string | null | undefined;
 }, {
     currency: "USD" | "CAD";
-    amount_total_cents: number;
     occurred_at: string;
     metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | null | undefined;
+    external_id?: string | null | undefined;
+    description?: string | null | undefined;
+    environment?: "production" | "development" | undefined;
+    items?: {
+        quantity: string;
+        unit_price_cents: number;
+        name?: string | null | undefined;
+        external_item_id?: string | null | undefined;
+        category?: string | null | undefined;
+        unit_cost_cents?: number | null | undefined;
+    }[] | undefined;
+    customer_name?: string | null | undefined;
+    customer_phone?: string | null | undefined;
+    customer_email?: string | null | undefined;
+}>, {
+    currency: "USD" | "CAD";
+    occurred_at: string;
+    environment: "production" | "development";
+    items: {
+        quantity: string;
+        unit_price_cents: number;
+        name?: string | null | undefined;
+        external_item_id?: string | null | undefined;
+        category?: string | null | undefined;
+        unit_cost_cents?: number | null | undefined;
+    }[];
+    metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | null | undefined;
     external_id?: string | null | undefined;
     description?: string | null | undefined;
+    customer_name?: string | null | undefined;
+    customer_phone?: string | null | undefined;
+    customer_email?: string | null | undefined;
+}, {
+    currency: "USD" | "CAD";
+    occurred_at: string;
+    metadata?: Record<string, unknown> | null | undefined;
     service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | null | undefined;
+    external_id?: string | null | undefined;
+    description?: string | null | undefined;
     environment?: "production" | "development" | undefined;
     items?: {
         quantity: string;
@@ -1580,9 +1656,19 @@ declare const saleCreateSchema: z.ZodObject<{
     customer_phone?: string | null | undefined;
     customer_email?: string | null | undefined;
 }>;
-declare const saleUpdateSchema: z.ZodObject<{
+declare const saleUpdateSchema: z.ZodEffects<z.ZodObject<{
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     service: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    services: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        service: z.ZodString;
+        amount_cents: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        service: string;
+        amount_cents: number;
+    }, {
+        service: string;
+        amount_cents: number;
+    }>, "many">>>;
     currency: z.ZodOptional<z.ZodEnum<["USD", "CAD"]>>;
     amount_total_cents: z.ZodOptional<z.ZodNumber>;
     occurred_at: z.ZodOptional<z.ZodString>;
@@ -1614,10 +1700,14 @@ declare const saleUpdateSchema: z.ZodObject<{
     customer_email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
     metadata?: Record<string, unknown> | null | undefined;
-    description?: string | null | undefined;
     service?: string | null | undefined;
-    currency?: "USD" | "CAD" | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
     amount_total_cents?: number | undefined;
+    description?: string | null | undefined;
+    currency?: "USD" | "CAD" | undefined;
     occurred_at?: string | undefined;
     items?: {
         quantity: string;
@@ -1632,10 +1722,58 @@ declare const saleUpdateSchema: z.ZodObject<{
     customer_email?: string | null | undefined;
 }, {
     metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | undefined;
     description?: string | null | undefined;
+    currency?: "USD" | "CAD" | undefined;
+    occurred_at?: string | undefined;
+    items?: {
+        quantity: string;
+        unit_price_cents: number;
+        name?: string | null | undefined;
+        external_item_id?: string | null | undefined;
+        category?: string | null | undefined;
+        unit_cost_cents?: number | null | undefined;
+    }[] | undefined;
+    customer_name?: string | null | undefined;
+    customer_phone?: string | null | undefined;
+    customer_email?: string | null | undefined;
+}>, {
+    metadata?: Record<string, unknown> | null | undefined;
     service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
+    amount_total_cents?: number | undefined;
+    description?: string | null | undefined;
     currency?: "USD" | "CAD" | undefined;
+    occurred_at?: string | undefined;
+    items?: {
+        quantity: string;
+        unit_price_cents: number;
+        name?: string | null | undefined;
+        external_item_id?: string | null | undefined;
+        category?: string | null | undefined;
+        unit_cost_cents?: number | null | undefined;
+    }[] | undefined;
+    customer_name?: string | null | undefined;
+    customer_phone?: string | null | undefined;
+    customer_email?: string | null | undefined;
+}, {
+    metadata?: Record<string, unknown> | null | undefined;
+    service?: string | null | undefined;
+    services?: {
+        service: string;
+        amount_cents: number;
+    }[] | null | undefined;
     amount_total_cents?: number | undefined;
+    description?: string | null | undefined;
+    currency?: "USD" | "CAD" | undefined;
     occurred_at?: string | undefined;
     items?: {
         quantity: string;
@@ -1650,6 +1788,7 @@ declare const saleUpdateSchema: z.ZodObject<{
     customer_email?: string | null | undefined;
 }>;
 type SaleItemInput = z.input<typeof saleItemSchema>;
+type SaleServiceInput = z.input<typeof saleServiceSchema>;
 type SaleInput = z.input<typeof saleCreateSchema>;
 type SaleUpdateInput = z.input<typeof saleUpdateSchema>;
 interface SaleItem {
@@ -1661,6 +1800,13 @@ interface SaleItem {
     unit_price_cents: number;
     unit_cost_cents: number | null;
 }
+interface SaleService {
+    id: string;
+    service_id: string;
+    service_key: string;
+    service_label: string;
+    amount_cents: number;
+}
 interface Sale {
     id: string;
     business_id: string;
@@ -1672,6 +1818,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;
@@ -1725,6 +1872,61 @@ 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 {
@@ -1758,15 +1960,29 @@ 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>;
+    /**
+     * 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'> & {
+    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>;
 }
@@ -1963,4 +2179,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
 }
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type 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 SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, resetConsent, setConsentState, toMinor, useConsent, useConsentState, useGclid, useTrackingParams };
+export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, type ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type CurrencyRevenue, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type 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, type TrackingClientContext, type TrackingEventCreatePayload, type TrackingInitConfig, type TrackingInstallSurface, type TrackingOverviewRange, type TrackingParams, type TrackingProviderProps, type TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, resetConsent, setConsentState, toMinor, useConsent, useConsentState, useGclid, useTrackingParams };