@aranova/tracking-react 0.9.1 → 0.10.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

@@ -1725,6 +1725,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 {
@@ -1764,6 +1819,12 @@ interface SalesClient<TService extends string = string> {
         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'> & {
         service?: TService | null;
@@ -1963,4 +2024,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 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 };

package/dist/index.d.ts

@@ -1725,6 +1725,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 {
@@ -1764,6 +1819,12 @@ interface SalesClient<TService extends string = string> {
         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'> & {
         service?: TService | null;
@@ -1963,4 +2024,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 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 };

package/dist/index.js

@@ -1386,6 +1386,16 @@ function createSalesClient(config) {
         ...cursor !== void 0 ? { cursor } : {}
       });
     },
+    async summary(query) {
+      const { range, include_categories, include_deleted_services, top_n, ...filters } = query;
+      return salesRequest(config, "POST", "/sales/summary", {
+        filters,
+        range,
+        ...include_categories !== void 0 ? { include_categories } : {},
+        ...include_deleted_services !== void 0 ? { include_deleted_services } : {},
+        ...top_n !== void 0 ? { top_n } : {}
+      });
+    },
     async get(id) {
       return salesRequest(config, "GET", `/sales/${id}`);
     },
@@ -1681,7 +1691,7 @@ function GoogleAdsTracking(props) {
 var import_react4 = require("react");
 
 // package.json
-var version = "0.9.1";
+var version = "0.10.0";
 
 // src/factory.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");