@aranova/tracking-react 0.24.0 → 0.25.0

package/dist/tracking-config-runtime-BnUlS_Ae.d.ts

@@ -0,0 +1,190 @@
+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;
+    google_tracking_state: "active" | "disabled";
+    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;
+
+/**
+ * Where a business's published tracking config lives.
+ *
+ * `businessId` + `environment` are the stable identity; the ORIGIN it is fetched
+ * from is deployment-specific (production CDN vs. a local object store), which is
+ * why `cdnBaseUrl` exists. Codegen bakes only the identity, so one committed
+ * generated file works in every environment and only an env var changes.
+ *
+ * `cdnUrl` remains supported and WINS when present — every client repo generated
+ * before `cdnBaseUrl` passes one, and those must keep working untouched.
+ */
+interface TrackingConfigReference {
+    /**
+     * Fully-resolved object URL. Optional: omit it and pass `cdnBaseUrl` (or rely
+     * on the production default) to have it composed from the identity below.
+     */
+    cdnUrl?: string;
+    /**
+     * Origin (optionally with a path prefix) the config object is served from, e.g.
+     * `https://demos.aranova.io` in production or
+     * `http://localhost:9100/aranova-demos` against a local MinIO. Ignored when
+     * `cdnUrl` is set; blank or omitted falls back to {@link DEFAULT_CDN_BASE_URL}.
+     * `tracking-cli gen` wires this to an env var so retargeting is config, not code.
+     */
+    cdnBaseUrl?: string;
+    businessId: string;
+    environment: "production" | "test";
+}
+/**
+ * The URL a reference resolves to. An explicit `cdnUrl` wins (back-compat);
+ * otherwise compose from `cdnBaseUrl` (or the production default).
+ *
+ * A blank/whitespace `cdnBaseUrl` is treated as UNSET rather than composed: the
+ * generated module reads it from an env var, and a var that is present-but-empty
+ * (a stray `NEXT_PUBLIC_ARANOVA_CDN_BASE_URL=` line) would otherwise produce
+ * `/tracking-config/...` — a same-origin request to the client's own site.
+ */
+declare function resolveTrackingConfigUrl(ref: TrackingConfigReference): string;
+type RuntimeState = "unconfirmed" | "active" | "tombstone";
+interface QueuedConversion {
+    key: string;
+    value?: number | null;
+    currency?: string | null;
+    transactionId?: string | null;
+}
+type TrackingConfigConversionOptions = Omit<QueuedConversion, "key">;
+interface QueuedPageView {
+    href: string;
+    title: string | null;
+    referrer: string | null;
+}
+declare class TrackingConfigRuntime {
+    readonly ref: TrackingConfigReference;
+    private readonly fetchImpl;
+    /** Resolved config URL — see the constructor for why it is computed once. */
+    private readonly url;
+    private current;
+    private etag;
+    private stateValue;
+    private confirmedAt;
+    private authorityGeneration;
+    private inFlight;
+    private flushInFlight;
+    private flushRequested;
+    private retryTimer;
+    private started;
+    /** Consecutive failed authority attempts — drives the revalidate backoff. */
+    private authorityFailures;
+    /** Epoch ms before which `ensureAuthority` must not issue another request. */
+    private nextAuthorityAttemptAt;
+    private readonly conversionQueue;
+    private readonly automaticQueue;
+    private readonly pageQueue;
+    private readonly listeners;
+    constructor(ref: TrackingConfigReference, fetchImpl?: typeof fetch);
+    /** The URL this runtime actually fetches (composed or explicit). */
+    configUrl(): string;
+    /**
+     * Explicitly start authority resolution and Google-tag bootstrap.
+     *
+     * Idempotent so framework effects can call it after hydration without
+     * depending on constructor timing.
+     */
+    start(): void;
+    state(): RuntimeState;
+    config(): ConversionConfig | null;
+    __unsafeExpireAuthorityForTests(): void;
+    /** Queue depths — asserted by tests to pin the bound. */
+    __queueDepthsForTests(): {
+        conversions: number;
+        automatic: number;
+        pages: number;
+    };
+    subscribe(listener: () => void): () => void;
+    ensureAuthority(): Promise<boolean>;
+    revalidate(): Promise<void>;
+    private revalidateAuthority;
+    queuePageView(snapshot?: QueuedPageView | null): void;
+    fireConversion(key: string, options?: TrackingConfigConversionOptions): void;
+    queueAutomaticEvent(eventType: string, metadata: Record<string, unknown>, transactionPath: string, transactionScope: string): void;
+    listGoals(): ConversionGoal[];
+    private revalidateNow;
+    private expireAuthority;
+    private confirm;
+    private flush;
+    private scheduleRetry;
+    private flushNow;
+}
+declare function getTrackingConfigRuntime(ref: TrackingConfigReference, fetchImpl?: typeof fetch): TrackingConfigRuntime;
+
+export { type ConversionConfig as C, type TrackingConfigReference as T, type ConversionConfigStore as a, resolveTrackingConfigUrl as b, TrackingConfigRuntime as c, getTrackingConfigRuntime as g, resolveConversionConfig as r };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aranova/tracking-react",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "private": false,
   "type": "commonjs",
   "description": "React tracking and consent utilities for Aranova client sites",
@@ -11,6 +11,13 @@
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "client": [
+        "./dist/client.d.ts"
+      ]
+    }
+  },
   "sideEffects": false,
   "repository": {
     "type": "git",
@@ -29,6 +36,16 @@
         "default": "./dist/index.js"
       }
     },
+    "./client": {
+      "import": {
+        "types": "./dist/client.d.mts",
+        "default": "./dist/client.mjs"
+      },
+      "require": {
+        "types": "./dist/client.d.ts",
+        "default": "./dist/client.js"
+      }
+    },
     "./sales": {
       "import": {
         "types": "./dist/sales.d.mts",