@aranova/tracking-next 0.7.2 → 0.8.0

package/README.md

@@ -171,9 +171,55 @@ export default function Page() {
 }
 ```
 
+## Recording Sales
+
+Record a sale / conversion (a first-class, mutable resource — not a fire-and-forget
+event). Money is integer minor units (cents); `currency` is a required ISO-4217 enum.
+
+One isomorphic `createSalesClient` (on the root entry) serves both sides — what a
+key may do is enforced by the backend, not by hiding methods. Browser write with
+your **public** key, from a client component:
+
+```tsx
+'use client';
+import { createSalesClient, toMinor } from '@aranova/tracking-next';
+
+const sales = createSalesClient({ apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!, endpoint });
+await sales.record({ currency: 'CAD', amount_total_cents: toMinor(250, 'CAD'), service: 'tires' });
+```
+
+Full CRUD from a route handler / server action with your **secret** key (same
+import — keep the secret key in server env, never in client code):
+
+```ts
+import { createSalesClient } from '@aranova/tracking-next';
+import type { AranovaService } from './aranova-services'; // generated, see below
+
+const sales = createSalesClient<AranovaService>({
+  apiKey: process.env.ARANOVA_TRACKING_SECRET_KEY!,
+  endpoint: process.env.ARANOVA_TRACKING_ENDPOINT!,
+});
+const { items, next_cursor } = await sales.list({ limit: 50 });
+```
+
+A public-key client calling `list`/`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**):
+
+```bash
+npm install --save-dev @aranova/tracking-cli
+npx @aranova/tracking-cli gen          # reads ARANOVA_TRACKING_SECRET_KEY from .env
+```
+
+See the full guide: [sales-tracking.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/sales-tracking.md)
+and the CLI reference: [cli.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/cli.md).
+
 ## Exports
 
-- Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, `ConsentBanner`, hooks, and event types
+- Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, `ConsentBanner`, hooks, event types, and `createSalesClient()` (isomorphic sales client — public key writes, secret key reads/CRUD) + money helpers (`toMinor`/`fromMinor`/`formatMoney`)
 - `@aranova/tracking-next/middleware`: `createTrackingMiddleware()`
 - `@aranova/tracking-next/server`: `getTrackingParamsServer()`
+- Codegen: [`@aranova/tracking-cli`](https://www.npmjs.com/package/@aranova/tracking-cli) — `gen` typed service unions (devDependency)
 

package/dist/index.d.mts

@@ -1232,6 +1232,307 @@ interface TypedTrackingClient<TRegistry extends TriggerRegistryConfig> {
     getVisitorId(): string;
 }
 
+/**
+ * Sales / Conversions wire schemas — the client-side source of truth.
+ *
+ * `saleCreateSchema` is mirrored by `SaleCreateSchema` in
+ * `apps/api/src/schemas/tracking_sales.py` and enforced by the backend drift
+ * test (the `resources` section of `events.schema.json`). Keep them in lockstep.
+ *
+ * Money is **integer minor units (cents)**; `quantity` is a decimal string;
+ * `currency` is the required `SupportedCurrency` enum.
+ */
+declare const SUPPORTED_CURRENCIES: readonly ["USD", "CAD"];
+type SupportedCurrency = (typeof SUPPORTED_CURRENCIES)[number];
+declare const TRACKING_ENVIRONMENTS: readonly ["production", "development"];
+declare const saleItemSchema: z.ZodObject<{
+    external_item_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    quantity: z.ZodString;
+    unit_price_cents: z.ZodNumber;
+    unit_cost_cents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, "strict", z.ZodTypeAny, {
+    quantity: string;
+    unit_price_cents: number;
+    name?: string | null | undefined;
+    external_item_id?: string | null | undefined;
+    category?: string | null | undefined;
+    unit_cost_cents?: number | null | undefined;
+}, {
+    quantity: string;
+    unit_price_cents: number;
+    name?: string | null | undefined;
+    external_item_id?: string | null | undefined;
+    category?: string | null | undefined;
+    unit_cost_cents?: number | null | undefined;
+}>;
+declare const saleCreateSchema: z.ZodObject<{
+    external_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    service: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    currency: z.ZodEnum<["USD", "CAD"]>;
+    amount_total_cents: 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>>>;
+}, "strict", z.ZodTypeAny, {
+    currency: "USD" | "CAD";
+    amount_total_cents: number;
+    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;
+    external_id?: string | null | undefined;
+    description?: string | null | undefined;
+    service?: string | null | undefined;
+}, {
+    currency: "USD" | "CAD";
+    amount_total_cents: number;
+    occurred_at: string;
+    metadata?: Record<string, unknown> | null | undefined;
+    external_id?: string | null | undefined;
+    description?: string | null | undefined;
+    service?: 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;
+}>;
+declare const saleUpdateSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    service: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    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>>>;
+}, "strict", z.ZodTypeAny, {
+    metadata?: Record<string, unknown> | null | undefined;
+    description?: string | null | undefined;
+    service?: string | null | undefined;
+    currency?: "USD" | "CAD" | undefined;
+    amount_total_cents?: number | 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;
+}, {
+    metadata?: Record<string, unknown> | null | undefined;
+    description?: string | null | undefined;
+    service?: string | null | undefined;
+    currency?: "USD" | "CAD" | undefined;
+    amount_total_cents?: number | 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;
+}>;
+type SaleItemInput = z.input<typeof saleItemSchema>;
+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 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;
+    occurred_at: string;
+    environment: (typeof TRACKING_ENVIRONMENTS)[number];
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+    items: SaleItem[];
+}
+interface SaleListPage {
+    items: Sale[];
+    total: number;
+}
+interface SaleCursorPage {
+    items: Sale[];
+    next_cursor: string | null;
+}
+interface SaleListQuery {
+    business_id?: string;
+    external_id?: string;
+    currency?: SupportedCurrency;
+    environment?: (typeof TRACKING_ENVIRONMENTS)[number];
+    since?: string;
+    until?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+
+/** Shared config for every sales HTTP helper. */
+interface SalesTransportConfig {
+    /** Public (`aranv_pk_…`) or secret (`aranv_sk_…`) API key. */
+    apiKey: string;
+    /**
+     * Base tracking endpoint, e.g. `https://aranovainternal-production.up.railway.app/tracking`.
+     * The `/sales` path is appended by the helpers.
+     */
+    endpoint: string;
+    /** Optional SDK identity headers (mirrors the event ingest client). */
+    sdkVersion?: string;
+    packageName?: string;
+    surface?: string;
+    environment?: string;
+}
+
+/** Config for {@link createSalesClient}. */
+interface SalesClientConfig extends SalesTransportConfig {
+    /** Applied when an individual `record()` call omits `currency`. */
+    defaultCurrency?: SupportedCurrency;
+}
+/**
+ * One isomorphic sales client — what a key may *do* is enforced by the backend,
+ * not by hiding methods. A **public** key (`aranv_pk_…`) may `record` (the
+ * backend rejects reads/CRUD from it with a `403`); a **secret** key
+ * (`aranv_sk_…`), used **server-side only**, gets full read/list/update/delete.
+ * Never ship a secret key in a browser bundle.
+ *
+ * Generic over the service-key union `TService`: bind the type emitted by
+ * `@aranova/tracking-cli gen` for compile-time-checked `service` values.
+ */
+interface SalesClient<TService extends string = string> {
+    record(input: Omit<SaleInput, 'currency' | 'occurred_at' | 'service'> & {
+        service?: TService | null;
+        currency?: SupportedCurrency;
+        occurred_at?: string;
+    }): Promise<Sale>;
+    list(query?: SaleListQuery): Promise<SaleCursorPage>;
+    get(id: string): Promise<Sale>;
+    update(id: string, patch: Omit<SaleUpdateInput, 'service'> & {
+        service?: TService | null;
+    }): Promise<Sale>;
+    delete(id: string): Promise<void>;
+}
+declare function createSalesClient<TService extends string = string>(config: SalesClientConfig): SalesClient<TService>;
+
+/** A business's active service, as returned by `GET /tracking/services`. */
+interface PublicServiceItem {
+    key: string;
+    label: string;
+}
+/**
+ * Fetch the caller's business's active service taxonomy. Accepts a public or
+ * secret key (the taxonomy is low-sensitivity category names). Powers the
+ * `@aranova/tracking-cli gen` codegen.
+ */
+declare function fetchServices(config: SalesTransportConfig): Promise<PublicServiceItem[]>;
+
+/**
+ * Convert a major amount (dollars `250.5`) to integer minor units (`25050`).
+ *
+ * Convenience only — the wire is always integer cents. Uses float multiply +
+ * `Math.round`, so values that aren't exactly representable in binary float
+ * (e.g. `1.005`) can round to the neighbouring cent. If you already hold an
+ * exact cents integer, pass it straight through and skip this helper.
+ */
+declare function toMinor(amount: number, currency: SupportedCurrency): number;
+/** Convert integer minor units (`25050`) to a major amount (`250.5`). */
+declare function fromMinor(cents: number, currency: SupportedCurrency): number;
+/**
+ * Format integer minor units as a localized currency string (e.g. `"$250.50"`).
+ * Uses the built-in `Intl.NumberFormat` — no extra dependency.
+ */
+declare function formatMoney(cents: number, currency: SupportedCurrency, locale?: string): string;
+
+/**
+ * Error thrown by the sales client (`createSalesClient`) on a
+ * non-2xx response. Unlike the fire-and-forget event queue (which swallows
+ * failures), a sale is a transaction the caller must be able to react to.
+ */
+declare class AranovaApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly requestId: string | undefined;
+    constructor(message: string, options: {
+        status: number;
+        code?: string;
+        requestId?: string;
+    });
+}
+
 /**
  * Default non-blocking consent banner for Next.js installs.
  *
@@ -1345,4 +1646,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
  */
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { type AutomaticEventName, ConsentBanner, 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 RegisteredAutomaticEvents, type RegisteredManualEvents, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, getConsentState, setConsentState, useConsentState, useGclid, useTrackingParams };
+export { AranovaApiError, type AutomaticEventName, ConsentBanner, 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, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, setConsentState, toMinor, useConsentState, useGclid, useTrackingParams };