@aranova/tracking-react 0.17.3 → 0.18.1

package/README.md

@@ -15,10 +15,12 @@ Create one shared tracking module and import the scoped `TrackingProvider` / `us
 ```ts
 // src/lib/tracking.ts
 import { createTracking } from "@aranova/tracking-react";
+import { ARANOVA_TRACKING_CONFIG } from "./aranova-services";
 
 export const { TrackingProvider, useTracking } = createTracking({
   apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY,
   endpoint: import.meta.env.VITE_ARANOVA_TRACKING_ENDPOINT,
+  trackingConfig: ARANOVA_TRACKING_CONFIG,
   triggers: {
     automatic: {
       page_view: {},
@@ -46,17 +48,18 @@ import { App } from "./App";
 import { TrackingProvider } from "./lib/tracking";
 
 createRoot(document.getElementById("root")!).render(
-  <TrackingProvider gtagId={import.meta.env.VITE_GTAG_ID}>
+  <TrackingProvider>
     <App />
   </TrackingProvider>,
 );
 ```
 
-### Multiple gtag IDs
+### Legacy static gtag IDs
 
-Pass `gtagIds` (instead of `gtagId`) to install several Google Ads tags at once — e.g. a real
-account plus a test MCC. Each entry fires `gtag('config', …)` on every page; the labels surface in
-the dashboard's SDK table. Stamp events with `environment` to filter out test traffic.
+`gtagId`, `gtagIds`, `GoogleAdsTracking`, and generated `ARANOVA_GTAG_IDS` remain
+compatibility APIs. Do not use them for new installs: static IDs cannot consume dashboard
+tag changes or tombstones without a redeploy. If maintaining a legacy install, `gtagIds`
+loads every entry and takes precedence over `gtagId`.
 
 ```tsx
 <TrackingProvider gtagIds={{ production: "AW-111111111", test: "AW-222222222" }}>
@@ -109,7 +112,7 @@ export function LeadForm() {
 }
 ```
 
-`fields[].value` can be any JSON value: string, number, boolean, null, array, or object. Values must be JSON-serializable because events are stored as JSONB. Only send reviewed, allowlisted, non-sensitive values; do not send names, emails, phone numbers entered by the visitor, addresses, payment data, medical details, passwords, file contents, or free-text messages.
+`fields[].value` can be any JSON value: string, number, boolean, null, array, or object. Values must be JSON-serializable because events are stored as first-party JSONB. Intentionally submitted lead fields may include raw names, emails, phone numbers, addresses, selections, free-text messages, and submitted file data for first-party analytics and lead operations. Build the array explicitly from the submitted form; the SDK never scrapes arbitrary DOM fields. `File`/`Blob` objects must be converted to a JSON representation, and the complete event metadata must fit the 4 KB limit; upload larger files separately and send their storage reference. Never send passwords, authentication tokens, payment-card/bank credentials, or private keys. Apply the client's privacy notice, consent, retention, and regulated-data requirements. Google offline matching uses normalized, server-side SHA-256-hashed identifiers — not raw free-text/file metadata.
 
 ### Phone clicks (`tel:` taps) — manual or auto-capture
 
@@ -274,32 +277,39 @@ and the CLI reference: [cli.md](https://github.com/AranovaIO/aranova_internal/bl
 
 ## On-site conversion firing
 
-Map conversion actions in the Aranova dashboard, run `tracking-cli gen` to bake `ARANOVA_CONFIG_URL`, then pass it to `createTracking`. The SDK fires `gtag('event','conversion', …)` on-page and reads the per-business config from the CDN with stale-while-revalidate — so **changing the mapping needs no client redeploy**.
+Run `tracking-cli gen` once to emit `ARANOVA_TRACKING_CONFIG`, then use that
+reference everywhere Google tracking is initialized. R2 is authoritative: the SDK confirms
+the current object before emitting Google tag, page-view, or conversion commands. Dashboard
+tag changes, goal remaps, and disabled-state tombstones propagate under
+`public, max-age=60, must-revalidate` with no CLI run or site redeploy.
 
 ```ts
-import { createTracking } from "@aranova/tracking-react";
-import { ARANOVA_CONFIG_URL } from "./aranova-services"; // emitted by `tracking-cli gen`
+import {
+  createSalesClient,
+  createTracking,
+  getTrackingConfigRuntime,
+  toMinor,
+} from "@aranova/tracking-react";
+import {
+  ARANOVA_TRACKING_CONFIG,
+  type AranovaConversion,
+  type AranovaService,
+} from "./aranova-services";
+
+const googleTracking = getTrackingConfigRuntime(ARANOVA_TRACKING_CONFIG);
 
 export const { TrackingProvider, useTracking } = createTracking({
   apiKey,
   endpoint,
   triggers,
-  conversionConfig: { cdnUrl: ARANOVA_CONFIG_URL },
+  trackingConfig: ARANOVA_TRACKING_CONFIG,
 });
-```
-
-- **Automatic event-goals** (scroll depth, time-on-site, page views, multi-page, form-start) fire **themselves** when their detector crosses the published threshold — zero extra code.
-- **Sales + manual events** fire through the sales client. Give it the same config:
-
-```ts
-import { createSalesClient, resolveConversionConfig, toMinor } from "@aranova/tracking-react";
-import type { AranovaService, AranovaConversion } from "./aranova-services"; // generated by `gen`
 
 // Bind the generated unions so `service` and `trackConversion` keys are type-checked.
 const sales = createSalesClient<AranovaService, AranovaConversion>({
   apiKey,
   endpoint,
-  firing: resolveConversionConfig({ cdnUrl: ARANOVA_CONFIG_URL }),
+  firing: googleTracking,
 });
 
 await sales.recordSale({
@@ -309,6 +319,10 @@ await sales.recordSale({
 }); // records + fires
 ```
 
+- **Automatic event-goals** fire when their registered detector crosses the published threshold.
+- **Sales + manual goals** use the shared runtime above. Firing is consent-gated,
+  transaction-deduped, and browser-only.
+
 **Manual conversions (multiple forms):** register the trigger once, then call `trackConversion(key)` in each form's submit handler. Keys come from the dashboard Goals tab (event-goals with a `form_submit`/`phone_click`/`cta_click` trigger mapped to a WEBPAGE action) and are emitted as the `AranovaConversion` union by `gen` — so they autocomplete and reject typos:
 
 ```ts
@@ -321,7 +335,12 @@ sales.trackConversion("demo_request");
 sales.trackConversion("typo"); // ❌ compile error — not a known goal key
 ```
 
-Each call fires **only** the WEBPAGE conversion for that goal (no `/sales` write); the SDK no-ops if the goal isn't mapped. Firing is consent-gated, de-duped by `transaction_id`, and no-ops server-side. The config bucket needs an R2 CORS policy — see [conversion-config-schema.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/conversion-config-schema.md).
+Each call fires **only** the WEBPAGE conversion for that goal (no `/sales` write); the SDK
+no-ops if the goal isn't mapped. Remapping an existing key needs no codegen. A **new manual
+goal key** still requires `tracking-cli gen` to refresh `AranovaConversion`, plus site handler
+wiring. `ARANOVA_CONFIG_URL` and `conversionConfig: { cdnUrl }` remain legacy compatibility
+APIs; do not use them for new installs. See
+[conversion-config-schema.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/conversion-config-schema.md).
 
 > **Before any manual goal exists,** `gen` emits an empty `ARANOVA_CONVERSIONS`, so `AranovaConversion` resolves to `never` — binding it (`createSalesClient<AranovaService, AranovaConversion>`) then makes **every** `trackConversion` call a compile error. Until you've mapped at least one manual goal and re-run `gen`, bind only the service generic (`createSalesClient<AranovaService>(…)`); the conversion key defaults back to `string`.
 
@@ -359,7 +378,7 @@ For non-component contexts the same primitives are exported as plain functions:
 
 - `createTracking()`
 - `TrackingProvider` and scoped `useTracking`
-- `GoogleAdsTracking`
+- `AdPlatformTracking` and `getTrackingConfigRuntime`; legacy `GoogleAdsTracking`
 - Consent (v2): `useCookiePreferences()` + `UseCookiePreferencesResult`; standalone `optIn()`, `optOut()`, `resetConsent()`, `getConsentChoice()`, `onConsentChange()`, `getConsentState()`, `setConsentState()`
 - Deprecated consent shims: `ConsentBanner` + `ConsentBannerProps`, `useConsent()` + `UseConsentResult`, `useConsentState()`
 - Attribution hooks: `useTrackingParams()`, `useGclid()`

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, InputHTMLAttributes, ChangeEvent, FocusEvent } from 'react';
-import { T as TrackingParams, a as TrackingInstallSurface, b as TrackingEnvironment, c as TrackingClientContext, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, F as FormSubmitConfig, f as FormSubmitMetadata, G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, C as ConsentState, g as ConsentChoiceState, h as ConsentSource, P as PhoneConfig, i as ParsedPhone, j as PhoneDisplayFormat } from './phone-utils-DlAQK-gU.mjs';
-export { k as ConsentChoice, D as DEFAULT_DECLINE_TTL_DAYS, l as DEFAULT_PHONE_COUNTRY, J as JsonValue, S as SetConsentOptions, m as TrackedField, n as TrackingInitConfig, o as formSubmitConfigSchema, p as formSubmitMetadataSchema, q as formatPhone, r as formatPhoneAsTyped, s as getConsentChoice, t as getConsentState, u as jsonValueSchema, v as onConsentChange, w as optIn, x as optOut, y as parsePhone, z as phoneField, A as resetConsent, B as setConsentState, E as toE164 } from './phone-utils-DlAQK-gU.mjs';
-import { C as ConversionConfig } from './sales-C3jFBx08.mjs';
-export { A as AranovaApiError, B as BusinessConfig, a as BusinessConfigFeatures, b as BusinessConfigService, c as CompareTo, d as ConversionConfigStore, e as CurrencyRevenue, f as CustomerCurrencyDelta, g as CustomerCurrencyTotal, h as CustomerGetOptions, i as CustomerGetResult, j as CustomerKpis, k as CustomerKpisDeltas, l as CustomerKpisPrevious, m as CustomerListPage, n as CustomerListQuery, o as CustomerProfile, p as CustomerSegment, q as CustomerSegmentCount, r as CustomerSortField, s as CustomerSummary, t as CustomerSummaryQuery, D as DistinctCustomersByCurrency, G as Granularity, N as NAMED_RANGES, u as NamedRange, P as PublicServiceItem, S as SUPPORTED_CURRENCIES, v as Sale, w as SaleCursorPage, x as SaleFilters, y as SaleInput, z as SaleItem, E as SaleItemInput, F as SaleKeysetSortField, H as SaleListPage, I as SaleListQuery, J as SaleListQueryV2, K as SaleService, L as SaleServiceInput, M as SaleSortField, O as SaleSortOrder, Q as SaleSummary, R as SaleSummaryPrevious, T as SaleSummaryQuery, U as SaleSummaryQueryV2, V as SaleSummaryV2, W as SaleUpdateInput, X as SalesBusinessClient, Y as SalesCategoryBreakdown, Z as SalesClient, _ as SalesClientConfig, $ as SalesCustomersClient, a0 as SalesServiceBreakdown, a1 as SalesTransportConfig, a2 as SalesTrendPoint, a3 as SummaryCurrencyDelta, a4 as SummaryDeltas, a5 as SummaryWindow, a6 as SupportedCurrency, a7 as TRACKING_RANGES, a8 as TrackingOverviewRange, a9 as createSalesClient, aa as fetchServices, ab as formatDateInTz, ac as formatMoney, ad as fromMinor, ae as resolveConversionConfig, af as saleCreateSchema, ag as saleItemSchema, ah as saleServiceSchema, ai as saleUpdateSchema, aj as salesRequest, ak as toMinor } from './sales-C3jFBx08.mjs';
+import { T as TrackingParams, a as TrackingInstallSurface, b as TrackingEnvironment, c as TrackingClientContext, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, F as FormSubmitConfig, f as FormSubmitMetadata, G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, C as ConsentState, g as ConsentChoiceState, h as ConsentSource, P as PhoneConfig, i as ParsedPhone, j as PhoneDisplayFormat } from './phone-utils-CVCzW04Z.mjs';
+export { k as ConsentChoice, D as DEFAULT_DECLINE_TTL_DAYS, l as DEFAULT_PHONE_COUNTRY, J as JsonValue, S as SetConsentOptions, m as TrackedField, n as TrackingInitConfig, o as formSubmitConfigSchema, p as formSubmitMetadataSchema, q as formatPhone, r as formatPhoneAsTyped, s as getConsentChoice, t as getConsentState, u as jsonValueSchema, v as onConsentChange, w as optIn, x as optOut, y as parsePhone, z as phoneField, A as resetConsent, B as setConsentState, E as toE164 } from './phone-utils-CVCzW04Z.mjs';
+import { T as TrackingConfigReference, C as ConversionConfig } from './sales-QqKh6_iy.mjs';
+export { A as AranovaApiError, B as BusinessConfig, a as BusinessConfigFeatures, b as BusinessConfigService, c as CompareTo, d as ConversionConfigStore, e as CurrencyRevenue, f as CustomerCurrencyDelta, g as CustomerCurrencyTotal, h as CustomerGetOptions, i as CustomerGetResult, j as CustomerKpis, k as CustomerKpisDeltas, l as CustomerKpisPrevious, m as CustomerListPage, n as CustomerListQuery, o as CustomerProfile, p as CustomerSegment, q as CustomerSegmentCount, r as CustomerSortField, s as CustomerSummary, t as CustomerSummaryQuery, D as DistinctCustomersByCurrency, G as Granularity, N as NAMED_RANGES, u as NamedRange, P as PublicServiceItem, S as SUPPORTED_CURRENCIES, v as Sale, w as SaleCursorPage, x as SaleFilters, y as SaleInput, z as SaleItem, E as SaleItemInput, F as SaleKeysetSortField, H as SaleListPage, I as SaleListQuery, J as SaleListQueryV2, K as SaleService, L as SaleServiceInput, M as SaleSortField, O as SaleSortOrder, Q as SaleSummary, R as SaleSummaryPrevious, U as SaleSummaryQuery, V as SaleSummaryQueryV2, W as SaleSummaryV2, X as SaleUpdateInput, Y as SalesBusinessClient, Z as SalesCategoryBreakdown, _ as SalesClient, $ as SalesClientConfig, a0 as SalesCustomersClient, a1 as SalesServiceBreakdown, a2 as SalesTransportConfig, a3 as SalesTrendPoint, a4 as SummaryCurrencyDelta, a5 as SummaryDeltas, a6 as SummaryWindow, a7 as SupportedCurrency, a8 as TRACKING_RANGES, a9 as TrackingOverviewRange, aa as createSalesClient, ab as fetchServices, ac as formatDateInTz, ad as formatMoney, ae as fromMinor, af as getTrackingConfigRuntime, ag as resolveConversionConfig, ah as saleCreateSchema, ai as saleItemSchema, aj as saleServiceSchema, ak as saleUpdateSchema, al as salesRequest, am as toMinor } from './sales-QqKh6_iy.mjs';
 import * as src from 'src';
 import { z } from 'zod';
 import { CountryCode } from 'libphonenumber-js';
@@ -135,8 +135,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     };
     cta_name: string;
     section?: string | null | undefined;
-    destination_url?: string | null | undefined;
     href?: string | null | undefined;
+    destination_url?: string | null | undefined;
     element?: string | null | undefined;
 }, {
     page: {
@@ -144,8 +144,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     };
     cta_name: string;
     section?: string | null | undefined;
-    destination_url?: string | null | undefined;
     href?: string | null | undefined;
+    destination_url?: string | null | undefined;
     element?: string | null | undefined;
 }>;
 type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
@@ -652,10 +652,101 @@ declare const timeOnSiteConfigSchema: z.ZodObject<{
 }>;
 type TimeOnSiteConfig = z.infer<typeof timeOnSiteConfigSchema>;
 
+type EventOutcomeRole = "lead" | "engagement" | "navigation" | "diagnostic";
+type EventCategory = "page" | "engagement" | "lead" | "commerce" | "system";
+type EventClientVisibility = "simple" | "detailed" | "hidden";
+interface EventSemantics {
+    label: string;
+    category: EventCategory;
+    outcomeRole: EventOutcomeRole;
+    clientVisibility: EventClientVisibility;
+}
+/**
+ * Lightweight runtime event metadata. This module intentionally imports no
+ * Zod schemas so dashboards and framework adapters can consume it without
+ * pulling the validation registry into their bundles.
+ */
+declare const EVENT_SEMANTICS: {
+    readonly page_view: {
+        readonly label: "Page view";
+        readonly category: "page";
+        readonly outcomeRole: "navigation";
+        readonly clientVisibility: "simple";
+    };
+    readonly time_on_site: {
+        readonly label: "Time on site";
+        readonly category: "engagement";
+        readonly outcomeRole: "engagement";
+        readonly clientVisibility: "detailed";
+    };
+    readonly specific_page_visit: {
+        readonly label: "Key page visit";
+        readonly category: "engagement";
+        readonly outcomeRole: "engagement";
+        readonly clientVisibility: "detailed";
+    };
+    readonly scroll_depth: {
+        readonly label: "Scroll depth";
+        readonly category: "engagement";
+        readonly outcomeRole: "engagement";
+        readonly clientVisibility: "detailed";
+    };
+    readonly multi_page_session: {
+        readonly label: "Multi-page session";
+        readonly category: "engagement";
+        readonly outcomeRole: "engagement";
+        readonly clientVisibility: "detailed";
+    };
+    readonly form_start: {
+        readonly label: "Form started";
+        readonly category: "engagement";
+        readonly outcomeRole: "engagement";
+        readonly clientVisibility: "simple";
+    };
+    readonly sdk_heartbeat: {
+        readonly label: "SDK heartbeat";
+        readonly category: "system";
+        readonly outcomeRole: "diagnostic";
+        readonly clientVisibility: "hidden";
+    };
+    readonly page_exit: {
+        readonly label: "Page exit";
+        readonly category: "engagement";
+        readonly outcomeRole: "diagnostic";
+        readonly clientVisibility: "detailed";
+    };
+    readonly form_submit: {
+        readonly label: "Form submitted";
+        readonly category: "lead";
+        readonly outcomeRole: "lead";
+        readonly clientVisibility: "simple";
+    };
+    readonly phone_click: {
+        readonly label: "Phone click";
+        readonly category: "lead";
+        readonly outcomeRole: "lead";
+        readonly clientVisibility: "simple";
+    };
+    readonly cta_click: {
+        readonly label: "CTA click";
+        readonly category: "engagement";
+        readonly outcomeRole: "engagement";
+        readonly clientVisibility: "simple";
+    };
+};
+type EventName = keyof typeof EVENT_SEMANTICS;
+declare function getEventSemantics(eventName: string): EventSemantics | null;
+
 type EventKind = "automatic" | "manual";
 declare const EVENT_REGISTRY: {
     readonly page_view: {
         readonly kind: "automatic";
+        readonly semantics: {
+            readonly label: "Page view";
+            readonly category: "page";
+            readonly outcomeRole: "navigation";
+            readonly clientVisibility: "simple";
+        };
         readonly metadataSchema: z.ZodObject<{
             page: z.ZodObject<{
                 title: z.ZodNullable<z.ZodString>;
@@ -713,6 +804,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly time_on_site: {
         readonly kind: "automatic";
+        readonly semantics: {
+            readonly label: "Time on site";
+            readonly category: "engagement";
+            readonly outcomeRole: "engagement";
+            readonly clientVisibility: "detailed";
+        };
         readonly metadataSchema: z.ZodObject<{
             duration_ms: z.ZodNumber;
             page: z.ZodObject<{
@@ -743,6 +840,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly specific_page_visit: {
         readonly kind: "automatic";
+        readonly semantics: {
+            readonly label: "Key page visit";
+            readonly category: "engagement";
+            readonly outcomeRole: "engagement";
+            readonly clientVisibility: "detailed";
+        };
         readonly metadataSchema: z.ZodObject<{
             page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
             page: z.ZodObject<{
@@ -788,6 +891,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly scroll_depth: {
         readonly kind: "automatic";
+        readonly semantics: {
+            readonly label: "Scroll depth";
+            readonly category: "engagement";
+            readonly outcomeRole: "engagement";
+            readonly clientVisibility: "detailed";
+        };
         readonly metadataSchema: z.ZodObject<{
             depth_percent: z.ZodNumber;
             page: z.ZodObject<{
@@ -818,6 +927,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly multi_page_session: {
         readonly kind: "automatic";
+        readonly semantics: {
+            readonly label: "Multi-page session";
+            readonly category: "engagement";
+            readonly outcomeRole: "engagement";
+            readonly clientVisibility: "detailed";
+        };
         readonly metadataSchema: z.ZodObject<{
             page_count: z.ZodNumber;
             page: z.ZodObject<{
@@ -848,6 +963,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly form_start: {
         readonly kind: "automatic";
+        readonly semantics: {
+            readonly label: "Form started";
+            readonly category: "engagement";
+            readonly outcomeRole: "engagement";
+            readonly clientVisibility: "simple";
+        };
         readonly metadataSchema: z.ZodObject<{
             form: z.ZodObject<{
                 id: z.ZodString;
@@ -893,6 +1014,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly sdk_heartbeat: {
         readonly kind: "automatic";
+        readonly semantics: {
+            readonly label: "SDK heartbeat";
+            readonly category: "system";
+            readonly outcomeRole: "diagnostic";
+            readonly clientVisibility: "hidden";
+        };
         readonly metadataSchema: z.ZodObject<{
             sdk_version: z.ZodString;
             package_name: z.ZodNullable<z.ZodString>;
@@ -934,6 +1061,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly page_exit: {
         readonly kind: "automatic";
+        readonly semantics: {
+            readonly label: "Page exit";
+            readonly category: "engagement";
+            readonly outcomeRole: "diagnostic";
+            readonly clientVisibility: "detailed";
+        };
         readonly metadataSchema: z.ZodObject<{
             dwell_ms: z.ZodNumber;
             max_scroll_percent: z.ZodNullable<z.ZodNumber>;
@@ -964,6 +1097,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly form_submit: {
         readonly kind: "manual";
+        readonly semantics: {
+            readonly label: "Form submitted";
+            readonly category: "lead";
+            readonly outcomeRole: "lead";
+            readonly clientVisibility: "simple";
+        };
         readonly metadataSchema: z.ZodObject<{
             form: z.ZodObject<{
                 id: z.ZodString;
@@ -1043,6 +1182,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly phone_click: {
         readonly kind: "manual";
+        readonly semantics: {
+            readonly label: "Phone click";
+            readonly category: "lead";
+            readonly outcomeRole: "lead";
+            readonly clientVisibility: "simple";
+        };
         readonly metadataSchema: z.ZodObject<{
             phone_number: z.ZodString;
             page: z.ZodObject<{
@@ -1086,6 +1231,12 @@ declare const EVENT_REGISTRY: {
     };
     readonly cta_click: {
         readonly kind: "manual";
+        readonly semantics: {
+            readonly label: "CTA click";
+            readonly category: "engagement";
+            readonly outcomeRole: "engagement";
+            readonly clientVisibility: "simple";
+        };
         readonly metadataSchema: z.ZodObject<{
             cta_name: z.ZodString;
             page: z.ZodObject<{
@@ -1105,8 +1256,8 @@ declare const EVENT_REGISTRY: {
             };
             cta_name: string;
             section?: string | null | undefined;
-            destination_url?: string | null | undefined;
             href?: string | null | undefined;
+            destination_url?: string | null | undefined;
             element?: string | null | undefined;
         }, {
             page: {
@@ -1114,8 +1265,8 @@ declare const EVENT_REGISTRY: {
             };
             cta_name: string;
             section?: string | null | undefined;
-            destination_url?: string | null | undefined;
             href?: string | null | undefined;
+            destination_url?: string | null | undefined;
             element?: string | null | undefined;
         }>;
         readonly configSchema: z.ZodObject<{
@@ -1137,10 +1288,6 @@ declare const EVENT_REGISTRY: {
         }>;
     };
 };
-/**
- * Name of any event known to the tracking SDK.
- */
-type EventName = keyof typeof EVENT_REGISTRY;
 /**
  * Event names that are fired by the SDK when their configured signal occurs.
  *
@@ -1202,6 +1349,10 @@ declare const ALL_AUTOMATIC_EVENT_NAMES: readonly AutomaticEventName[];
  * Runtime list of manual event names.
  */
 declare const ALL_MANUAL_EVENT_NAMES: readonly ManualEventName[];
+/**
+ * Events that represent a lead/outcome in first-party tracking projections.
+ */
+declare const ALL_LEAD_EVENT_NAMES: readonly EventName[];
 /**
  * Trigger registry passed to `createTracking({ triggers })`.
  *
@@ -1265,6 +1416,7 @@ type TrackableEvent<TRegistry extends TriggerRegistryConfig> = {
 }[RegisteredManualEvents<TRegistry>];
 declare function getEventDefinition(name: EventName): {
     kind: EventKind;
+    semantics: EventSemantics;
     metadataSchema: z.ZodTypeAny;
     configSchema: z.ZodTypeAny;
 };
@@ -1363,6 +1515,10 @@ interface AdPlatformTrackingProps {
     gtagId?: string;
     /** Labelled Google Ads tag map — ALL loaded; wins over `gtagId`. */
     gtagIds?: GtagEnvironmentMap;
+    /** R2-authoritative Google tracking config. When set, static gtagId(s) are ignored. */
+    trackingConfig?: TrackingConfigReference;
+    /** Fire a Google page view from this standalone loader. Leave false when using TrackingProvider. */
+    standalonePageView?: boolean;
     /** Single Meta Pixel id, e.g. `123456789012345`. */
     metaPixelId?: string;
     /** Labelled Meta Pixel map — ALL loaded; wins over `metaPixelId`. */
@@ -1378,7 +1534,7 @@ interface AdPlatformTrackingProps {
  * accepts the same `gtagId/gtagIds` + `metaPixelId/metaPixelIds` props. Use this
  * standalone component when you want the ad tags WITHOUT the event-ingest SDK.
  */
-declare function AdPlatformTracking({ gtagId, gtagIds, metaPixelId, metaPixelIds, }: AdPlatformTrackingProps): null;
+declare function AdPlatformTracking({ gtagId, gtagIds, trackingConfig, standalonePageView, metaPixelId, metaPixelIds, }: AdPlatformTrackingProps): null;
 
 /**
  * Props for the Google Ads tracking component.
@@ -1548,6 +1704,7 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
         cdnUrl: string;
         baked?: ConversionConfig | null;
     };
+    trackingConfig?: TrackingConfigReference;
 }
 interface TrackingProviderProps {
     /**
@@ -1647,4 +1804,4 @@ interface PhoneFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "t
  */
 declare const PhoneField: react.ForwardRefExoticComponent<PhoneFieldProps & react.RefAttributes<HTMLInputElement>>;
 
-export { ALL_AUTOMATIC_EVENT_NAMES, ALL_MANUAL_EVENT_NAMES, AdPlatformTracking, type AdPlatformTrackingProps, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, ConsentChoiceState, ConsentSource, ConsentState, ConversionConfig, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, EVENT_REGISTRY, type EventConfig, type EventKind, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, FormSubmitConfig, FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, GtagEnvironmentMap, type ManualEventName, MetaPixelEnvironmentMap, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageExitConfig, type PageExitMetadata, type PageViewConfig, type PageViewMetadata, ParsedPhone, type PhoneClickConfig, type PhoneClickMetadata, PhoneConfig, PhoneDisplayFormat, PhoneField, type PhoneFieldApi, type PhoneFieldProps, type PhoneInputProps, type RegisteredAutomaticEvents, type RegisteredManualEvents, SPECIFIC_PAGE_NAMES, type ScrollDepthConfig, type ScrollDepthMetadata, type SdkHeartbeatConfig, type SdkHeartbeatMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackableEvent, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, type UseCookiePreferencesOptions, type UseCookiePreferencesResult, type UsePhoneFieldOptions, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, ctaClickConfigSchema, ctaClickMetadataSchema, formStartConfigSchema, formStartMetadataSchema, getEventDefinition, multiPageSessionConfigSchema, multiPageSessionMetadataSchema, pageExitConfigSchema, pageExitMetadataSchema, pageViewConfigSchema, pageViewMetadataSchema, phoneClickConfigSchema, phoneClickMetadataSchema, scrollDepthConfigSchema, scrollDepthMetadataSchema, sdkHeartbeatConfigSchema, sdkHeartbeatMetadataSchema, sdkHeartbeatTriggersSchema, specificPageNameSchema, specificPageVisitConfigSchema, specificPageVisitMetadataSchema, timeOnSiteConfigSchema, timeOnSiteMetadataSchema, useConsent, useConsentState, useCookiePreferences, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };
+export { ALL_AUTOMATIC_EVENT_NAMES, ALL_LEAD_EVENT_NAMES, ALL_MANUAL_EVENT_NAMES, AdPlatformTracking, type AdPlatformTrackingProps, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, ConsentChoiceState, ConsentSource, ConsentState, ConversionConfig, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, EVENT_REGISTRY, EVENT_SEMANTICS, type EventCategory, type EventClientVisibility, type EventConfig, type EventKind, type EventMetadata, type EventName, type EventOutcomeRole, type EventSemantics, type FormStartConfig, type FormStartMetadata, FormSubmitConfig, FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, GtagEnvironmentMap, type ManualEventName, MetaPixelEnvironmentMap, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageExitConfig, type PageExitMetadata, type PageViewConfig, type PageViewMetadata, ParsedPhone, type PhoneClickConfig, type PhoneClickMetadata, PhoneConfig, PhoneDisplayFormat, PhoneField, type PhoneFieldApi, type PhoneFieldProps, type PhoneInputProps, type RegisteredAutomaticEvents, type RegisteredManualEvents, SPECIFIC_PAGE_NAMES, type ScrollDepthConfig, type ScrollDepthMetadata, type SdkHeartbeatConfig, type SdkHeartbeatMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackableEvent, type TrackingClient, TrackingClientContext, TrackingConfigReference, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, type UseCookiePreferencesOptions, type UseCookiePreferencesResult, type UsePhoneFieldOptions, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, ctaClickConfigSchema, ctaClickMetadataSchema, formStartConfigSchema, formStartMetadataSchema, getEventDefinition, getEventSemantics, multiPageSessionConfigSchema, multiPageSessionMetadataSchema, pageExitConfigSchema, pageExitMetadataSchema, pageViewConfigSchema, pageViewMetadataSchema, phoneClickConfigSchema, phoneClickMetadataSchema, scrollDepthConfigSchema, scrollDepthMetadataSchema, sdkHeartbeatConfigSchema, sdkHeartbeatMetadataSchema, sdkHeartbeatTriggersSchema, specificPageNameSchema, specificPageVisitConfigSchema, specificPageVisitMetadataSchema, timeOnSiteConfigSchema, timeOnSiteMetadataSchema, useConsent, useConsentState, useCookiePreferences, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };