@aranova/tracking-next 0.17.3 → 0.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/README.md +50 -24
  2. package/dist/index.d.mts +171 -14
  3. package/dist/index.d.ts +171 -14
  4. package/dist/index.js +479 -28
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +457 -9
  7. package/dist/index.mjs.map +1 -1
  8. package/dist/middleware.js +82 -0
  9. package/dist/middleware.js.map +1 -1
  10. package/dist/middleware.mjs +82 -0
  11. package/dist/middleware.mjs.map +1 -1
  12. package/dist/{phone-utils-DlAQK-gU.d.mts → phone-utils-CVCzW04Z.d.mts} +7 -4
  13. package/dist/{phone-utils-DlAQK-gU.d.ts → phone-utils-CVCzW04Z.d.ts} +7 -4
  14. package/dist/phone.d.mts +1 -1
  15. package/dist/phone.d.ts +1 -1
  16. package/dist/phone.js +82 -0
  17. package/dist/phone.js.map +1 -1
  18. package/dist/phone.mjs +82 -0
  19. package/dist/phone.mjs.map +1 -1
  20. package/dist/{sales-C3jFBx08.d.mts → sales-QqKh6_iy.d.mts} +55 -2
  21. package/dist/{sales-C3jFBx08.d.ts → sales-QqKh6_iy.d.ts} +55 -2
  22. package/dist/sales.d.mts +1 -1
  23. package/dist/sales.d.ts +1 -1
  24. package/dist/sales.js +16 -0
  25. package/dist/sales.js.map +1 -1
  26. package/dist/sales.mjs +16 -0
  27. package/dist/sales.mjs.map +1 -1
  28. package/dist/server.d.mts +1 -1
  29. package/dist/server.d.ts +1 -1
  30. package/dist/server.js +82 -0
  31. package/dist/server.js.map +1 -1
  32. package/dist/server.mjs +82 -0
  33. package/dist/server.mjs.map +1 -1
  34. package/package.json +1 -1
package/README.md CHANGED
@@ -50,10 +50,12 @@ Create one shared tracking module and use its scoped exports throughout your app
50
50
  "use client";
51
51
 
52
52
  import { createTracking } from "@aranova/tracking-next";
53
+ import { ARANOVA_TRACKING_CONFIG } from "@/aranova-services";
53
54
 
54
55
  export const { TrackingProvider, useTracking } = createTracking({
55
56
  apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!,
56
57
  endpoint: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_ENDPOINT!,
58
+ trackingConfig: ARANOVA_TRACKING_CONFIG,
57
59
  triggers: {
58
60
  automatic: {
59
61
  page_view: {},
@@ -76,16 +78,15 @@ Wrap the root layout.
76
78
 
77
79
  ```tsx
78
80
  // app/layout.tsx
79
- import { GoogleAdsTracking } from "@aranova/tracking-next";
81
+ import { AdPlatformTracking } from "@aranova/tracking-next";
82
+ import { ARANOVA_TRACKING_CONFIG } from "@/aranova-services";
80
83
  import { TrackingProvider } from "@/lib/tracking";
81
84
 
82
85
  export default function RootLayout({ children }: { children: React.ReactNode }) {
83
86
  return (
84
87
  <html lang="en">
85
88
  <head>
86
- {process.env.NEXT_PUBLIC_GTAG_ID && (
87
- <GoogleAdsTracking gtagId={process.env.NEXT_PUBLIC_GTAG_ID} />
88
- )}
89
+ <AdPlatformTracking trackingConfig={ARANOVA_TRACKING_CONFIG} />
89
90
  </head>
90
91
  <body>
91
92
  <TrackingProvider>{children}</TrackingProvider>
@@ -108,11 +109,12 @@ Tracking is on by default (consent v2, opt-out model) — no banner. Add a foote
108
109
  "cookie preferences" control built on `useCookiePreferences()` (see **Consent** below)
109
110
  and disclose the tracking + opt-out in the site's privacy policy.
110
111
 
111
- ### Multiple gtag IDs
112
+ ### Legacy static gtag IDs
112
113
 
113
- Pass `gtagIds` (instead of `gtagId`) to install several Google Ads tags at once — e.g. a real
114
- account plus a test MCC. Each entry fires `gtag('config', …)` on every page; the labels surface in
115
- the dashboard's SDK table. Pass `environment` to the factory to tag events for dashboard filtering.
114
+ `gtagId`, `gtagIds`, `GoogleAdsTracking`, and generated `ARANOVA_GTAG_IDS` remain
115
+ compatibility APIs. Do not use them for new installs: static IDs cannot consume dashboard
116
+ tag changes or tombstones without a redeploy. If maintaining a legacy install, `gtagIds`
117
+ loads every entry and takes precedence over `gtagId`.
116
118
 
117
119
  ```tsx
118
120
  <GoogleAdsTracking gtagIds={{ production: "AW-111111111", test: "AW-222222222" }} />
@@ -167,7 +169,7 @@ export function LeadForm() {
167
169
  }
168
170
  ```
169
171
 
170
- `fields[].value` can be any JSON value: string, number, boolean, null, array, or object. 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.
172
+ `fields[].value` can be any JSON value: string, number, boolean, null, array, or object and is 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 successful submission; 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.
171
173
 
172
174
  ### Phone clicks (`tel:` taps) — manual or auto-capture
173
175
 
@@ -338,30 +340,38 @@ and the CLI reference: [cli.md](https://github.com/AranovaIO/aranova_internal/bl
338
340
 
339
341
  ## On-site conversion firing
340
342
 
341
- 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**.
343
+ Run `tracking-cli gen` once to emit `ARANOVA_TRACKING_CONFIG`, then use that
344
+ reference everywhere Google tracking is initialized. R2 is authoritative: the SDK confirms
345
+ the current object before emitting Google tag, page-view, or conversion commands. Dashboard
346
+ tag changes, goal remaps, and disabled-state tombstones propagate under
347
+ `public, max-age=60, must-revalidate` with no CLI run or site redeploy.
342
348
 
343
349
  ```ts
344
- import { createTracking } from "@aranova/tracking-next";
345
- import { ARANOVA_CONFIG_URL } from "./aranova-services"; // emitted by `tracking-cli gen`
350
+ import {
351
+ createSalesClient,
352
+ createTracking,
353
+ getTrackingConfigRuntime,
354
+ toMinor,
355
+ } from "@aranova/tracking-next";
356
+ import {
357
+ ARANOVA_TRACKING_CONFIG,
358
+ type AranovaConversion,
359
+ type AranovaService,
360
+ } from "./aranova-services";
361
+
362
+ const googleTracking = getTrackingConfigRuntime(ARANOVA_TRACKING_CONFIG);
346
363
 
347
364
  export const { TrackingProvider, useTracking } = createTracking({
348
365
  apiKey,
349
366
  endpoint,
350
367
  triggers,
351
- conversionConfig: { cdnUrl: ARANOVA_CONFIG_URL },
368
+ trackingConfig: ARANOVA_TRACKING_CONFIG,
352
369
  });
353
- ```
354
370
 
355
- - **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.
356
- - **Sales + manual events** fire through the sales client (use a **public** key in the browser; a secret-key server-side client no-ops firing since there's no `gtag`):
357
-
358
- ```ts
359
- import { createSalesClient, resolveConversionConfig, toMinor } from "@aranova/tracking-next";
360
-
361
- const sales = createSalesClient({
371
+ const sales = createSalesClient<AranovaService, AranovaConversion>({
362
372
  apiKey,
363
373
  endpoint,
364
- firing: resolveConversionConfig({ cdnUrl: ARANOVA_CONFIG_URL }),
374
+ firing: googleTracking,
365
375
  });
366
376
 
367
377
  await sales.recordSale({
@@ -372,7 +382,16 @@ await sales.recordSale({
372
382
  sales.trackConversion("phone_click"); // fires a manual event-goal only (no sale recorded)
373
383
  ```
374
384
 
375
- 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).
385
+ - **Automatic event-goals** fire when their registered detector crosses the published threshold.
386
+ - **Sales + manual goals** use the shared runtime above. Firing is consent-gated,
387
+ transaction-deduped, and browser-only.
388
+ - A remap of an existing key needs no codegen. A **new manual goal key** still requires
389
+ `tracking-cli gen` to refresh `AranovaConversion`, plus site handler wiring that calls
390
+ `trackConversion(key)`.
391
+
392
+ `ARANOVA_CONFIG_URL` and `conversionConfig: { cdnUrl }` remain legacy compatibility
393
+ APIs; do not use them for new installs. See
394
+ [conversion-config-schema.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/conversion-config-schema.md).
376
395
 
377
396
  ## Consent (v2 — opt-out model)
378
397
 
@@ -405,7 +424,14 @@ The hook returns the effective `state` (`"granted" | "denied"`), its `source` (`
405
424
 
406
425
  ## Exports
407
426
 
408
- - Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, consent v2 (`useCookiePreferences`, `optIn`, `optOut`, `resetConsent`, `getConsentChoice`, `onConsentChange`) + deprecated shims (`ConsentBanner`, `useConsent`, `useConsentState`), attribution hooks, event types; `createSalesClient()` (isomorphic — public key writes; secret key reads/CRUD, `summary`, `customers.*`, `business.config`) + `toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`; phone (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`)
427
+ - Root package: `createTracking`, `TrackingProvider`, `useTracking`, `AdPlatformTracking`,
428
+ `getTrackingConfigRuntime`, legacy `GoogleAdsTracking`, consent v2
429
+ (`useCookiePreferences`, `optIn`, `optOut`, `resetConsent`, `getConsentChoice`,
430
+ `onConsentChange`) + deprecated shims (`ConsentBanner`, `useConsent`, `useConsentState`),
431
+ attribution hooks, event types; `createSalesClient()` (isomorphic — public key writes;
432
+ secret key reads/CRUD, `summary`, `customers.*`, `business.config`) +
433
+ `toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`; phone
434
+ (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`)
409
435
  - `@aranova/tracking-next/sales`: **React-free** server-safe SDK — `createSalesClient`, money/date helpers, and all sale/customer/config types. Use this in Server Components, route handlers, and Node servers; the root entry re-exports the same symbols for back-compat.
410
436
  - `@aranova/tracking-next/middleware`: `createTrackingMiddleware()`
411
437
  - `@aranova/tracking-next/server`: `getTrackingParamsServer()`
package/dist/index.d.mts CHANGED
@@ -1,7 +1,7 @@
1
- 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, C as ConsentState, g as ConsentChoiceState, h as ConsentSource, G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, P as PhoneConfig, i as ParsedPhone, j as PhoneDisplayFormat } from './phone-utils-DlAQK-gU.mjs';
2
- 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';
3
- import { C as ConversionConfig } from './sales-C3jFBx08.mjs';
4
- 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';
1
+ 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, C as ConsentState, g as ConsentChoiceState, h as ConsentSource, G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, P as PhoneConfig, i as ParsedPhone, j as PhoneDisplayFormat } from './phone-utils-CVCzW04Z.mjs';
2
+ 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';
3
+ import { T as TrackingConfigReference, C as ConversionConfig } from './sales-QqKh6_iy.mjs';
4
+ 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';
5
5
  import { z } from 'zod';
6
6
  import * as src from 'src';
7
7
  import * as react from 'react';
@@ -88,8 +88,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
88
88
  };
89
89
  cta_name: string;
90
90
  section?: string | null | undefined;
91
- destination_url?: string | null | undefined;
92
91
  href?: string | null | undefined;
92
+ destination_url?: string | null | undefined;
93
93
  element?: string | null | undefined;
94
94
  }, {
95
95
  page: {
@@ -97,8 +97,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
97
97
  };
98
98
  cta_name: string;
99
99
  section?: string | null | undefined;
100
- destination_url?: string | null | undefined;
101
100
  href?: string | null | undefined;
101
+ destination_url?: string | null | undefined;
102
102
  element?: string | null | undefined;
103
103
  }>;
104
104
  type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
@@ -605,10 +605,101 @@ declare const timeOnSiteConfigSchema: z.ZodObject<{
605
605
  }>;
606
606
  type TimeOnSiteConfig = z.infer<typeof timeOnSiteConfigSchema>;
607
607
 
608
+ type EventOutcomeRole = "lead" | "engagement" | "navigation" | "diagnostic";
609
+ type EventCategory = "page" | "engagement" | "lead" | "commerce" | "system";
610
+ type EventClientVisibility = "simple" | "detailed" | "hidden";
611
+ interface EventSemantics {
612
+ label: string;
613
+ category: EventCategory;
614
+ outcomeRole: EventOutcomeRole;
615
+ clientVisibility: EventClientVisibility;
616
+ }
617
+ /**
618
+ * Lightweight runtime event metadata. This module intentionally imports no
619
+ * Zod schemas so dashboards and framework adapters can consume it without
620
+ * pulling the validation registry into their bundles.
621
+ */
622
+ declare const EVENT_SEMANTICS: {
623
+ readonly page_view: {
624
+ readonly label: "Page view";
625
+ readonly category: "page";
626
+ readonly outcomeRole: "navigation";
627
+ readonly clientVisibility: "simple";
628
+ };
629
+ readonly time_on_site: {
630
+ readonly label: "Time on site";
631
+ readonly category: "engagement";
632
+ readonly outcomeRole: "engagement";
633
+ readonly clientVisibility: "detailed";
634
+ };
635
+ readonly specific_page_visit: {
636
+ readonly label: "Key page visit";
637
+ readonly category: "engagement";
638
+ readonly outcomeRole: "engagement";
639
+ readonly clientVisibility: "detailed";
640
+ };
641
+ readonly scroll_depth: {
642
+ readonly label: "Scroll depth";
643
+ readonly category: "engagement";
644
+ readonly outcomeRole: "engagement";
645
+ readonly clientVisibility: "detailed";
646
+ };
647
+ readonly multi_page_session: {
648
+ readonly label: "Multi-page session";
649
+ readonly category: "engagement";
650
+ readonly outcomeRole: "engagement";
651
+ readonly clientVisibility: "detailed";
652
+ };
653
+ readonly form_start: {
654
+ readonly label: "Form started";
655
+ readonly category: "engagement";
656
+ readonly outcomeRole: "engagement";
657
+ readonly clientVisibility: "simple";
658
+ };
659
+ readonly sdk_heartbeat: {
660
+ readonly label: "SDK heartbeat";
661
+ readonly category: "system";
662
+ readonly outcomeRole: "diagnostic";
663
+ readonly clientVisibility: "hidden";
664
+ };
665
+ readonly page_exit: {
666
+ readonly label: "Page exit";
667
+ readonly category: "engagement";
668
+ readonly outcomeRole: "diagnostic";
669
+ readonly clientVisibility: "detailed";
670
+ };
671
+ readonly form_submit: {
672
+ readonly label: "Form submitted";
673
+ readonly category: "lead";
674
+ readonly outcomeRole: "lead";
675
+ readonly clientVisibility: "simple";
676
+ };
677
+ readonly phone_click: {
678
+ readonly label: "Phone click";
679
+ readonly category: "lead";
680
+ readonly outcomeRole: "lead";
681
+ readonly clientVisibility: "simple";
682
+ };
683
+ readonly cta_click: {
684
+ readonly label: "CTA click";
685
+ readonly category: "engagement";
686
+ readonly outcomeRole: "engagement";
687
+ readonly clientVisibility: "simple";
688
+ };
689
+ };
690
+ type EventName = keyof typeof EVENT_SEMANTICS;
691
+ declare function getEventSemantics(eventName: string): EventSemantics | null;
692
+
608
693
  type EventKind = "automatic" | "manual";
609
694
  declare const EVENT_REGISTRY: {
610
695
  readonly page_view: {
611
696
  readonly kind: "automatic";
697
+ readonly semantics: {
698
+ readonly label: "Page view";
699
+ readonly category: "page";
700
+ readonly outcomeRole: "navigation";
701
+ readonly clientVisibility: "simple";
702
+ };
612
703
  readonly metadataSchema: z.ZodObject<{
613
704
  page: z.ZodObject<{
614
705
  title: z.ZodNullable<z.ZodString>;
@@ -666,6 +757,12 @@ declare const EVENT_REGISTRY: {
666
757
  };
667
758
  readonly time_on_site: {
668
759
  readonly kind: "automatic";
760
+ readonly semantics: {
761
+ readonly label: "Time on site";
762
+ readonly category: "engagement";
763
+ readonly outcomeRole: "engagement";
764
+ readonly clientVisibility: "detailed";
765
+ };
669
766
  readonly metadataSchema: z.ZodObject<{
670
767
  duration_ms: z.ZodNumber;
671
768
  page: z.ZodObject<{
@@ -696,6 +793,12 @@ declare const EVENT_REGISTRY: {
696
793
  };
697
794
  readonly specific_page_visit: {
698
795
  readonly kind: "automatic";
796
+ readonly semantics: {
797
+ readonly label: "Key page visit";
798
+ readonly category: "engagement";
799
+ readonly outcomeRole: "engagement";
800
+ readonly clientVisibility: "detailed";
801
+ };
699
802
  readonly metadataSchema: z.ZodObject<{
700
803
  page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
701
804
  page: z.ZodObject<{
@@ -741,6 +844,12 @@ declare const EVENT_REGISTRY: {
741
844
  };
742
845
  readonly scroll_depth: {
743
846
  readonly kind: "automatic";
847
+ readonly semantics: {
848
+ readonly label: "Scroll depth";
849
+ readonly category: "engagement";
850
+ readonly outcomeRole: "engagement";
851
+ readonly clientVisibility: "detailed";
852
+ };
744
853
  readonly metadataSchema: z.ZodObject<{
745
854
  depth_percent: z.ZodNumber;
746
855
  page: z.ZodObject<{
@@ -771,6 +880,12 @@ declare const EVENT_REGISTRY: {
771
880
  };
772
881
  readonly multi_page_session: {
773
882
  readonly kind: "automatic";
883
+ readonly semantics: {
884
+ readonly label: "Multi-page session";
885
+ readonly category: "engagement";
886
+ readonly outcomeRole: "engagement";
887
+ readonly clientVisibility: "detailed";
888
+ };
774
889
  readonly metadataSchema: z.ZodObject<{
775
890
  page_count: z.ZodNumber;
776
891
  page: z.ZodObject<{
@@ -801,6 +916,12 @@ declare const EVENT_REGISTRY: {
801
916
  };
802
917
  readonly form_start: {
803
918
  readonly kind: "automatic";
919
+ readonly semantics: {
920
+ readonly label: "Form started";
921
+ readonly category: "engagement";
922
+ readonly outcomeRole: "engagement";
923
+ readonly clientVisibility: "simple";
924
+ };
804
925
  readonly metadataSchema: z.ZodObject<{
805
926
  form: z.ZodObject<{
806
927
  id: z.ZodString;
@@ -846,6 +967,12 @@ declare const EVENT_REGISTRY: {
846
967
  };
847
968
  readonly sdk_heartbeat: {
848
969
  readonly kind: "automatic";
970
+ readonly semantics: {
971
+ readonly label: "SDK heartbeat";
972
+ readonly category: "system";
973
+ readonly outcomeRole: "diagnostic";
974
+ readonly clientVisibility: "hidden";
975
+ };
849
976
  readonly metadataSchema: z.ZodObject<{
850
977
  sdk_version: z.ZodString;
851
978
  package_name: z.ZodNullable<z.ZodString>;
@@ -887,6 +1014,12 @@ declare const EVENT_REGISTRY: {
887
1014
  };
888
1015
  readonly page_exit: {
889
1016
  readonly kind: "automatic";
1017
+ readonly semantics: {
1018
+ readonly label: "Page exit";
1019
+ readonly category: "engagement";
1020
+ readonly outcomeRole: "diagnostic";
1021
+ readonly clientVisibility: "detailed";
1022
+ };
890
1023
  readonly metadataSchema: z.ZodObject<{
891
1024
  dwell_ms: z.ZodNumber;
892
1025
  max_scroll_percent: z.ZodNullable<z.ZodNumber>;
@@ -917,6 +1050,12 @@ declare const EVENT_REGISTRY: {
917
1050
  };
918
1051
  readonly form_submit: {
919
1052
  readonly kind: "manual";
1053
+ readonly semantics: {
1054
+ readonly label: "Form submitted";
1055
+ readonly category: "lead";
1056
+ readonly outcomeRole: "lead";
1057
+ readonly clientVisibility: "simple";
1058
+ };
920
1059
  readonly metadataSchema: z.ZodObject<{
921
1060
  form: z.ZodObject<{
922
1061
  id: z.ZodString;
@@ -996,6 +1135,12 @@ declare const EVENT_REGISTRY: {
996
1135
  };
997
1136
  readonly phone_click: {
998
1137
  readonly kind: "manual";
1138
+ readonly semantics: {
1139
+ readonly label: "Phone click";
1140
+ readonly category: "lead";
1141
+ readonly outcomeRole: "lead";
1142
+ readonly clientVisibility: "simple";
1143
+ };
999
1144
  readonly metadataSchema: z.ZodObject<{
1000
1145
  phone_number: z.ZodString;
1001
1146
  page: z.ZodObject<{
@@ -1039,6 +1184,12 @@ declare const EVENT_REGISTRY: {
1039
1184
  };
1040
1185
  readonly cta_click: {
1041
1186
  readonly kind: "manual";
1187
+ readonly semantics: {
1188
+ readonly label: "CTA click";
1189
+ readonly category: "engagement";
1190
+ readonly outcomeRole: "engagement";
1191
+ readonly clientVisibility: "simple";
1192
+ };
1042
1193
  readonly metadataSchema: z.ZodObject<{
1043
1194
  cta_name: z.ZodString;
1044
1195
  page: z.ZodObject<{
@@ -1058,8 +1209,8 @@ declare const EVENT_REGISTRY: {
1058
1209
  };
1059
1210
  cta_name: string;
1060
1211
  section?: string | null | undefined;
1061
- destination_url?: string | null | undefined;
1062
1212
  href?: string | null | undefined;
1213
+ destination_url?: string | null | undefined;
1063
1214
  element?: string | null | undefined;
1064
1215
  }, {
1065
1216
  page: {
@@ -1067,8 +1218,8 @@ declare const EVENT_REGISTRY: {
1067
1218
  };
1068
1219
  cta_name: string;
1069
1220
  section?: string | null | undefined;
1070
- destination_url?: string | null | undefined;
1071
1221
  href?: string | null | undefined;
1222
+ destination_url?: string | null | undefined;
1072
1223
  element?: string | null | undefined;
1073
1224
  }>;
1074
1225
  readonly configSchema: z.ZodObject<{
@@ -1090,10 +1241,6 @@ declare const EVENT_REGISTRY: {
1090
1241
  }>;
1091
1242
  };
1092
1243
  };
1093
- /**
1094
- * Name of any event known to the tracking SDK.
1095
- */
1096
- type EventName = keyof typeof EVENT_REGISTRY;
1097
1244
  /**
1098
1245
  * Event names that are fired by the SDK when their configured signal occurs.
1099
1246
  *
@@ -1155,6 +1302,10 @@ declare const ALL_AUTOMATIC_EVENT_NAMES: readonly AutomaticEventName[];
1155
1302
  * Runtime list of manual event names.
1156
1303
  */
1157
1304
  declare const ALL_MANUAL_EVENT_NAMES: readonly ManualEventName[];
1305
+ /**
1306
+ * Events that represent a lead/outcome in first-party tracking projections.
1307
+ */
1308
+ declare const ALL_LEAD_EVENT_NAMES: readonly EventName[];
1158
1309
  /**
1159
1310
  * Trigger registry passed to `createTracking({ triggers })`.
1160
1311
  *
@@ -1218,6 +1369,7 @@ type TrackableEvent<TRegistry extends TriggerRegistryConfig> = {
1218
1369
  }[RegisteredManualEvents<TRegistry>];
1219
1370
  declare function getEventDefinition(name: EventName): {
1220
1371
  kind: EventKind;
1372
+ semantics: EventSemantics;
1221
1373
  metadataSchema: z.ZodTypeAny;
1222
1374
  configSchema: z.ZodTypeAny;
1223
1375
  };
@@ -1459,6 +1611,10 @@ interface AdPlatformTrackingProps {
1459
1611
  gtagId?: string;
1460
1612
  /** Labelled Google Ads tag map — ALL loaded; wins over `gtagId`. */
1461
1613
  gtagIds?: GtagEnvironmentMap;
1614
+ /** R2-authoritative Google tracking config. When set, static gtagId(s) are ignored. */
1615
+ trackingConfig?: TrackingConfigReference;
1616
+ /** Fire a Google page view from this standalone loader. Leave false when using TrackingProvider. */
1617
+ standalonePageView?: boolean;
1462
1618
  /** Single Meta Pixel id, e.g. `123456789012345`. */
1463
1619
  metaPixelId?: string;
1464
1620
  /** Labelled Meta Pixel map — ALL loaded; wins over `metaPixelId`. */
@@ -1470,7 +1626,7 @@ interface AdPlatformTrackingProps {
1470
1626
  * `next/script`. Render once in the root layout; omit a platform's props to
1471
1627
  * skip it. Renders no visible UI.
1472
1628
  */
1473
- declare function AdPlatformTracking({ gtagId, gtagIds, metaPixelId, metaPixelIds, }: AdPlatformTrackingProps): react_jsx_runtime.JSX.Element;
1629
+ declare function AdPlatformTracking({ gtagId, gtagIds, trackingConfig, standalonePageView, metaPixelId, metaPixelIds, }: AdPlatformTrackingProps): react_jsx_runtime.JSX.Element;
1474
1630
 
1475
1631
  /**
1476
1632
  * Props for the Next.js Google Ads tracking component.
@@ -1543,6 +1699,7 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
1543
1699
  cdnUrl: string;
1544
1700
  baked?: ConversionConfig | null;
1545
1701
  };
1702
+ trackingConfig?: TrackingConfigReference;
1546
1703
  }
1547
1704
  interface TrackingProviderProps {
1548
1705
  /**
@@ -1631,4 +1788,4 @@ interface PhoneFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "t
1631
1788
  */
1632
1789
  declare const PhoneField: react.ForwardRefExoticComponent<PhoneFieldProps & react.RefAttributes<HTMLInputElement>>;
1633
1790
 
1634
- 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 };
1791
+ 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 };