@aranova/tracking-react 0.14.2 → 0.16.0

package/README.md

@@ -119,6 +119,49 @@ tracking.trackEvent("phone_click", {
 });
 ```
 
+### CTA clicks — manual or auto-capture
+
+Fire `cta_click` yourself for full control over the name:
+
+```tsx
+tracking.trackEvent("cta_click", {
+  cta_name: "Book appointment",
+  section: "hero",
+  destination_url: "/booking",
+  page: { path: window.location.pathname },
+});
+```
+
+Or opt into **auto-capture** and skip per-button code. Add `autoCapture` to the
+`cta_click` registration — this attaches a single delegated click listener:
+
+```tsx
+manual: {
+  cta_click: { autoCapture: {} }, // default selector: [data-aranova-cta]
+  // or target existing classes: { autoCapture: { selector: "a.cta, .btn-primary" } }
+},
+```
+
+Then tag your CTAs in markup — no imports, no handlers:
+
+```tsx
+<a href="/booking" data-aranova-cta="Book now" data-aranova-section="hero">Book now</a>
+<button data-aranova-cta="Get a quote">Get a quote</button>
+```
+
+`cta_name` resolves to the `data-aranova-cta` value, else the element's trimmed text
+(capped 120 chars), else `tag#id`. `section` comes from an optional `data-aranova-section`;
+`href`/`destination_url` and a short `element` descriptor are captured automatically. Point
+the selector at real CTAs (an explicit attribute is the safe default) — every matching click
+is counted, including ones that later `stopPropagation`.
+
+### Automatic dwell + exit (`page_exit`)
+
+`page_exit` is captured automatically — no registration. On SPA navigation, tab hide, and
+page unload it records the **active** (visible) time spent on the page plus the max scroll
+depth reached, delivered via a keepalive beacon so the final page still counts. This powers
+per-page dwell and drop-off in the dashboard Analytics tab; there is nothing to configure.
+
 ## Phone Fields
 
 Bundled `libphonenumber-js`: parse/format utils + a React input. Display is configurable; the
@@ -255,69 +298,43 @@ Each call fires **only** the WEBPAGE conversion for that goal (no `/sales` write
 
 > **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`.
 
-## Consent UI
+## Consent (v2 — opt-out model)
 
-The bundled `<ConsentBanner />` renders a non-blocking bottom-docked banner while consent is `pending`, persists the visitor's choice to `localStorage`, and propagates it to Google Consent Mode v2 when gtag is loaded. **Inline-styled** — no Tailwind or CSS imports required at the consumer.
+Tracking is **on by default**: gtag, the Meta Pixel, and on-site conversion firing all run from first paint unless the visitor has stored an explicit, unexpired decline. A decline is honored for **90 days** (then the visitor reverts to default-granted); an explicit grant never expires. There is no `pending` state and the packages ship **no consent UI** — each site provides its own footer "cookie preferences" control and discloses tracking in its privacy policy (that notice is what makes the opt-out model defensible).
 
-```tsx
-import { ConsentBanner } from "@aranova/tracking-react";
+### Footer control — `useCookiePreferences()`
 
-// Drop-in, defaults work everywhere
-<ConsentBanner />;
-```
+```tsx
+import { useCookiePreferences } from "@aranova/tracking-react";
 
-All props are optional:
+function CookiePreferences() {
+  const { isDenied, isDefault, optOut, optIn } = useCookiePreferences();
 
-```tsx
-<ConsentBanner
-  title="Cookies"
-  message="We use cookies to track ad performance."
-  acceptLabel="Sure"
-  declineLabel="No thanks"
-  policyHref="/privacy"
-  policyLabel="Privacy policy" // default: "Learn more"
-  onAccept={() => track("consent_accepted")}
-  onDecline={() => track("consent_declined")}
-  position="bottom" // or "top"
-  theme="light" // "light" | "dark" | "auto"
-  className="my-extra-classes"
-  style={{ background: "#fafafa" }} // wins over the theme defaults
-/>
+  return isDenied ? (
+    <button onClick={optIn}>Enable ad measurement</button>
+  ) : (
+    <button onClick={optOut}>Opt out of ad measurement</button>
+  );
+}
 ```
 
-### Fully custom UI — `useConsent()`
+The hook returns the effective `state` (`"granted" | "denied"`), its `source` (`"default"` = no explicit choice, `"explicit"`), boolean helpers (`isDefault` / `isGranted` / `isDenied`), the choice's `updatedAt` / `expiresAt`, and the `optOut()` / `optIn()` / `reset()` actions. It stays in sync with other components in the same tab (via `onConsentChange`) and other tabs (via `storage` events). `optOut` accepts a custom TTL via the hook's `{ declineTtlDays }` option.
 
-For a bespoke banner, skip the component and drive your own UI with the headless hook:
+For non-component contexts the same primitives are exported as plain functions: `optOut()`, `optIn()`, `resetConsent()`, `getConsentChoice()`, and `onConsentChange()`.
 
-```tsx
-import { useConsent } from "@aranova/tracking-react";
-
-function CookieBar() {
-  const { state, accept, decline, reset, isPending } = useConsent();
+### Deprecated opt-in flow
 
-  if (!isPending) {
-    // Footer link: re-open the banner if they change their mind.
-    return <button onClick={reset}>Cookie preferences</button>;
-  }
-  return (
-    <MyBespokeBanner>
-      <button onClick={decline}>No thanks</button>
-      <button onClick={accept}>Sure</button>
-    </MyBespokeBanner>
-  );
-}
-```
+`<ConsentBanner />`, `useConsent()`, and `useConsentState()` are `@deprecated` and scheduled for removal. The banner is **permanently inert** — it rendered only while consent was `pending`, which no longer occurs — so leaving it mounted is harmless but pointless. `useConsent()` still works as a shim (`isPending` is always `false`; `accept`/`decline` map to `optIn`/`optOut`).
 
-The hook handles localStorage persistence, gtag sync, and cross-tab propagation — same machinery the default banner uses. `resetConsent()` is also exported as a standalone for non-component contexts.
+**Migrating from the banner flow:** delete `<ConsentBanner />`, add a footer control built on `useCookiePreferences`, and mention the tracking + opt-out in your privacy policy. Existing visitors' stored grants stay granted; stored declines stay denied for 90 days from their first visit after the upgrade.
 
 ## Exports
 
 - `createTracking()`
 - `TrackingProvider` and scoped `useTracking`
 - `GoogleAdsTracking`
-- `ConsentBanner` + `ConsentBannerProps`
-- Consent hooks: `useConsent()` + `UseConsentResult` (headless); `useConsentState()` (read-only alias)
-- Standalone consent helpers: `getConsentState()`, `setConsentState()`, `resetConsent()`
+- Consent (v2): `useCookiePreferences()` + `UseCookiePreferencesResult`; standalone `optIn()`, `optOut()`, `resetConsent()`, `getConsentChoice()`, `onConsentChange()`, `getConsentState()`, `setConsentState()`
+- Deprecated consent shims: `ConsentBanner` + `ConsentBannerProps`, `useConsent()` + `UseConsentResult`, `useConsentState()`
 - Attribution hooks: `useTrackingParams()`, `useGclid()`
 - `createSalesClient()` (isomorphic — public key writes; secret key reads/CRUD, `summary`, `customers.*`, `business.config`) + money/date helpers (`toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`). Also available React-free at **`@aranova/tracking-react/sales`** (with all sale/customer/config types) — the recommended import for server/serverless code.
 - Phone: `parsePhone`/`toE164`/`formatPhone`/`formatPhoneAsTyped`/`phoneField`, `usePhoneField`, `PhoneField` (utils also at `/phone`)

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, InputHTMLAttributes, ChangeEvent, FocusEvent } from 'react';
-import { C as ConsentState, T as TrackingInstallSurface, a as TrackingEnvironment, b as TrackingClientContext, c as TrackingParams, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, F as FormSubmitConfig, f as FormSubmitMetadata, G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, P as PhoneConfig, g as ParsedPhone, h as PhoneDisplayFormat } from './phone-utils-Dyk0F14_.mjs';
-export { D as DEFAULT_PHONE_COUNTRY, J as JsonValue, i as TrackedField, j as TrackingInitConfig, k as formSubmitConfigSchema, l as formSubmitMetadataSchema, m as formatPhone, n as formatPhoneAsTyped, o as jsonValueSchema, p as parsePhone, q as phoneField, t as toE164 } from './phone-utils-Dyk0F14_.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-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-Bq7H-Vym.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-Bq7H-Vym.mjs';
 import * as src from 'src';
@@ -10,37 +10,14 @@ import { CountryCode } from 'libphonenumber-js';
 export { CountryCode } from 'libphonenumber-js';
 
 /**
- * Default non-blocking consent banner.
+ * Legacy opt-in-era consent banner.
  *
- * Renders only while consent is `pending`; collapses to `null` once the
- * visitor has chosen.
- *
- * **Styling is intentionally self-contained** — inline styles, zero CSS
- * dependencies, no Tailwind required at the consumer. The Tailwind-based
- * banner shipped before 0.9.1 rendered as transparent in any consumer that
- * didn't configure their content array to scan
- * `node_modules/@aranova/tracking-react/dist/**`; this version sidesteps that
- * class of bug entirely.
- *
- * For a fully bespoke banner, skip this component and use {@link useConsent}
- * directly to drive your own UI.
- *
- * @example
- * // Drop-in default
- * <ConsentBanner />
- *
- * @example
- * // Customized
- * <ConsentBanner
- *   message="We use cookies to learn which ads drive bookings."
- *   acceptLabel="Sounds good"
- *   declineLabel="No thanks"
- *   policyHref="/privacy"
- *   policyLabel="Privacy policy"
- *   theme="dark"
- *   onAccept={() => track('consent_accepted')}
- *   onDecline={() => track('consent_declined')}
- * />
+ * @deprecated PERMANENTLY INERT since consent v2 (opt-out model): it renders
+ * only while consent is `pending`, and the effective state is never `pending`
+ * anymore, so this component always returns `null`. Tracking is on by default;
+ * replace the banner with a footer "cookie preferences" control built on
+ * {@link useCookiePreferences} (see the package README). Kept exported so
+ * existing integrations keep compiling; scheduled for removal.
  */
 interface ConsentBannerProps {
     /** Body text. Defaults to the standard cookies-for-ad-performance message. */
@@ -72,40 +49,26 @@ interface ConsentBannerProps {
     /** Inline style overrides applied to the outer wrapper after the defaults. */
     style?: CSSProperties;
 }
-declare function ConsentBanner({ message, title, acceptLabel, declineLabel, policyHref, policyLabel, onAccept, onDecline, position, theme, className, style, }?: ConsentBannerProps): ReactNode;
-
-/**
- * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
- */
-type GtagConsentValue = "granted" | "denied";
 /**
- * Read the persisted visitor consent state from localStorage.
- *
- * Returns `pending` when called during SSR or before the visitor has made a
- * choice.
+ * @deprecated Permanently inert since consent v2 — always renders `null`
+ * because the effective consent state is never `pending`. Use a footer
+ * control built on {@link useCookiePreferences} instead. See
+ * {@link ConsentBannerProps} for details.
  */
-declare function getConsentState(): ConsentState;
+declare function ConsentBanner({ message, title, acceptLabel, declineLabel, policyHref, policyLabel, onAccept, onDecline, position, theme, className, style, }?: ConsentBannerProps): ReactNode;
+
 /**
- * Persist a visitor consent choice and update Google Consent Mode when gtag is
- * loaded.
+ * Attribution query/cookie keys captured by the SDK.
  */
-declare function setConsentState(state: GtagConsentValue): void;
+declare const TRACKING_PARAM_KEYS: readonly ["gclid", "fbclid", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
+type TrackingParamKey = (typeof TRACKING_PARAM_KEYS)[number];
 /**
- * Clear the stored consent choice so the banner re-appears on next render.
- *
- * Power a "Cookie preferences" link in a footer so visitors can change their
- * mind without losing access to your site:
- *
- * ```tsx
- * const { reset } = useConsent();
- * <button onClick={reset}>Cookie preferences</button>
- * ```
+ * Capture tracking params from a URL, persist them to first-party cookies, and
+ * return the current cookie-backed attribution state.
  *
- * Does NOT push an `update` to gtag — there's nothing to update because the
- * visitor hasn't chosen anything yet. The next `setConsentState()` call will
- * sync gtag once they re-choose.
+ * Defaults to `window.location.href` in the browser.
  */
-declare function resetConsent(): void;
+declare function captureTrackingParamsFromLocation(url?: string, maxAgeSeconds?: number): TrackingParams;
 
 interface TrackingContextInput {
     packageName?: string | null;
@@ -127,6 +90,12 @@ interface TrackingSessionInput {
     firstPage?: string | null;
     sessionId: string;
     visitorId?: string | null;
+    /**
+     * Landing attribution override (ADR-016). When omitted, the session's
+     * persisted landing record is used (captured from the current URL if the
+     * session has none yet).
+     */
+    landingParams?: Partial<Record<TrackingParamKey, string>>;
 }
 /**
  * Build runtime context attached to tracking sessions and events.
@@ -158,6 +127,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     }>;
     section: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     destination_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    href: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    element: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
     page: {
         path: string;
@@ -165,6 +136,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     cta_name: string;
     section?: string | null | undefined;
     destination_url?: string | null | undefined;
+    href?: string | null | undefined;
+    element?: string | null | undefined;
 }, {
     page: {
         path: string;
@@ -172,14 +145,34 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     cta_name: string;
     section?: string | null | undefined;
     destination_url?: string | null | undefined;
+    href?: string | null | undefined;
+    element?: string | null | undefined;
 }>;
 type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
 /**
  * Registration config for `cta_click`.
  *
- * This event is manual-only and currently has no registration options.
+ * The event stays manually fireable; `autoCapture` additionally attaches a
+ * delegated click listener that fires it for any element matching `selector`
+ * (default `[data-aranova-cta]`) — tag your CTAs, get analytics for free.
  */
-declare const ctaClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+declare const ctaClickConfigSchema: z.ZodObject<{
+    autoCapture: z.ZodOptional<z.ZodObject<{
+        selector: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector?: string | undefined;
+    }, {
+        selector?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}>;
 type CtaClickConfig = z.infer<typeof ctaClickConfigSchema>;
 
 /**
@@ -343,6 +336,49 @@ declare const multiPageSessionConfigSchema: z.ZodObject<{
 }>;
 type MultiPageSessionConfig = z.infer<typeof multiPageSessionConfigSchema>;
 
+/**
+ * Metadata for the automatic `page_exit` event.
+ *
+ * Fired when the user leaves a page (SPA navigation away, tab hidden, or
+ * pagehide). `dwell_ms` is the ACTIVE (visible) time spent on the page segment
+ * being closed — hidden time never counts, matching `time_on_site` semantics.
+ * A page revisited after being hidden emits another `page_exit` for the next
+ * visible segment, so summing `dwell_ms` per page/session yields total active
+ * dwell without double counting.
+ */
+declare const pageExitMetadataSchema: z.ZodObject<{
+    dwell_ms: z.ZodNumber;
+    max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+    page: z.ZodObject<{
+        path: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    page: {
+        path: string;
+    };
+    dwell_ms: number;
+    max_scroll_percent: number | null;
+}, {
+    page: {
+        path: string;
+    };
+    dwell_ms: number;
+    max_scroll_percent: number | null;
+}>;
+type PageExitMetadata = z.infer<typeof pageExitMetadataSchema>;
+/**
+ * Registration config for automatic `page_exit`.
+ *
+ * SDK-internal: attached unconditionally (like `sdk_heartbeat`), so there are
+ * no registration options.
+ */
+declare const pageExitConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+type PageExitConfig = z.infer<typeof pageExitConfigSchema>;
+
 /**
  * Metadata for the automatic `page_view` event.
  *
@@ -874,6 +910,33 @@ declare const EVENT_REGISTRY: {
         }>;
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
+    readonly page_exit: {
+        readonly kind: "automatic";
+        readonly metadataSchema: z.ZodObject<{
+            dwell_ms: z.ZodNumber;
+            max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+            page: z.ZodObject<{
+                path: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                path: string;
+            }, {
+                path: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            page: {
+                path: string;
+            };
+            dwell_ms: number;
+            max_scroll_percent: number | null;
+        }, {
+            page: {
+                path: string;
+            };
+            dwell_ms: number;
+            max_scroll_percent: number | null;
+        }>;
+        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
     readonly form_submit: {
         readonly kind: "manual";
         readonly metadataSchema: z.ZodObject<{
@@ -993,6 +1056,8 @@ declare const EVENT_REGISTRY: {
             }>;
             section: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             destination_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            href: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            element: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, "strict", z.ZodTypeAny, {
             page: {
                 path: string;
@@ -1000,6 +1065,8 @@ declare const EVENT_REGISTRY: {
             cta_name: string;
             section?: string | null | undefined;
             destination_url?: string | null | undefined;
+            href?: string | null | undefined;
+            element?: string | null | undefined;
         }, {
             page: {
                 path: string;
@@ -1007,8 +1074,26 @@ declare const EVENT_REGISTRY: {
             cta_name: string;
             section?: string | null | undefined;
             destination_url?: string | null | undefined;
+            href?: string | null | undefined;
+            element?: string | null | undefined;
+        }>;
+        readonly configSchema: z.ZodObject<{
+            autoCapture: z.ZodOptional<z.ZodObject<{
+                selector: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                selector?: string | undefined;
+            }, {
+                selector?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
+        }, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
         }>;
-        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
 };
 /**
@@ -1037,6 +1122,7 @@ type MetadataByName = {
     multi_page_session: MultiPageSessionMetadata;
     form_start: FormStartMetadata;
     sdk_heartbeat: SdkHeartbeatMetadata;
+    page_exit: PageExitMetadata;
     form_submit: FormSubmitMetadata;
     phone_click: PhoneClickMetadata;
     cta_click: CtaClickMetadata;
@@ -1049,6 +1135,7 @@ type ConfigByName = {
     multi_page_session: MultiPageSessionConfig;
     form_start: FormStartConfig;
     sdk_heartbeat: SdkHeartbeatConfig;
+    page_exit: PageExitConfig;
     form_submit: FormSubmitConfig;
     phone_click: PhoneClickConfig;
     cta_click: CtaClickConfig;
@@ -1163,8 +1250,14 @@ interface TrackEventInput {
 interface TrackingClient {
     /** Enqueue an event for batched delivery. */
     trackEvent: (input: TrackEventInput) => void;
-    /** Flush queued events immediately. */
+    /** Flush queued events immediately (fetch, non-keepalive). */
     flush: () => Promise<void>;
+    /**
+     * Flush queued events through the keepalive transport so the request
+     * survives document unload. Use from `pagehide`/`visibilitychange:hidden`
+     * handlers — a plain `flush()` there is aborted by the browser on unload.
+     */
+    flushBeacon: () => void;
     /** Return the current rolling session id. */
     getSessionId: () => string;
     /** Return the persistent visitor id. */
@@ -1173,18 +1266,6 @@ interface TrackingClient {
     destroy: () => void;
 }
 
-/**
- * Attribution query/cookie keys captured by the SDK.
- */
-declare const TRACKING_PARAM_KEYS: readonly ["gclid", "fbclid", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
-/**
- * Capture tracking params from a URL, persist them to first-party cookies, and
- * return the current cookie-backed attribution state.
- *
- * Defaults to `window.location.href` in the browser.
- */
-declare function captureTrackingParamsFromLocation(url?: string, maxAgeSeconds?: number): TrackingParams;
-
 interface TypedTrackEventOptions {
     /**
      * Override the page URL associated with this event.
@@ -1248,9 +1329,9 @@ interface AdPlatformTrackingProps {
 }
 /**
  * Client component that loads the configured ad-platform tags — the Google tag
- * (`gtag`) and/or the Meta Pixel (`fbq`) — each with Consent Mode, and restores
- * stored consent. One mount handles both platforms; omit a platform's props to
- * skip it. Renders nothing.
+ * (`gtag`) and/or the Meta Pixel (`fbq`) — each with the visitor's effective
+ * consent applied as the default (opt-out model). One mount handles both
+ * platforms; omit a platform's props to skip it. Renders nothing.
  *
  * On React you usually don't need this at all — `<TrackingProvider>` already
  * accepts the same `gtagId/gtagIds` + `metaPixelId/metaPixelIds` props. Use this
@@ -1272,7 +1353,9 @@ type GoogleAdsTrackingProps = {
     gtagIds: GtagEnvironmentMap;
 };
 /**
- * Client component that loads Google Ads gtag and restores stored consent.
+ * Client component that loads Google Ads gtag with the visitor's effective
+ * consent applied as the Consent Mode default (opt-out model — granted unless
+ * an unexpired stored decline exists).
  *
  * Render once near the application root when the client site runs paid Google
  * Ads. The component renders nothing.
@@ -1291,38 +1374,69 @@ declare function useGclid(): string | null;
  * Values are loaded after mount, so the initial render returns all `null`s.
  */
 declare function useTrackingParams(): TrackingParams;
+/** Options for {@link useCookiePreferences}. */
+interface UseCookiePreferencesOptions {
+    /** Days an explicit decline is honored. Defaults to 90. */
+    declineTtlDays?: number;
+}
 /**
- * Read the current visitor consent state and update when another tab changes
- * the stored value.
- *
- * Prefer {@link useConsent} for new code — it returns the same state plus
- * the `accept` / `decline` / `reset` actions a custom consent UI needs.
- * `useConsentState` is kept as a convenience for callers that only need to
- * read.
+ * The headless cookie-preferences surface returned by
+ * {@link useCookiePreferences}.
  */
-declare function useConsentState(): ConsentState;
+interface UseCookiePreferencesResult {
+    /** Effective consent — `granted` unless an unexpired explicit decline exists. */
+    state: ConsentChoiceState;
+    /** `default` = no valid explicit choice stored; `explicit` = visitor chose. */
+    source: ConsentSource;
+    /** True when the visitor has made no (valid, unexpired) explicit choice. */
+    isDefault: boolean;
+    isGranted: boolean;
+    isDenied: boolean;
+    /** ISO timestamp of the explicit choice; null for the default state. */
+    updatedAt: string | null;
+    /** ISO expiry of an unexpired decline; null otherwise. */
+    expiresAt: string | null;
+    /** Explicitly opt out of ad tracking (honored for 90 days by default). */
+    optOut: () => void;
+    /** Explicitly opt in (never expires). */
+    optIn: () => void;
+    /** Clear the explicit choice — back to default-granted. */
+    reset: () => void;
+}
 /**
- * The headless consent surface — state + actions in one hook.
+ * Headless cookie-preferences hook for the opt-out consent model (consent v2).
  *
- * Build a fully-custom banner without losing the gtag-sync, localStorage
- * persistence, or cross-tab propagation:
+ * Tracking is ON by default; this hook is how each client site wires its own
+ * footer "Cookie preferences" control (button, dialog, toggle — the packages
+ * ship no consent UI). State stays in sync with actions from other components
+ * in the same tab (via `onConsentChange`) and other tabs (via `storage`
+ * events).
  *
  * ```tsx
- * const { state, accept, decline, reset, isPending } = useConsent();
- *
- * if (!isPending) {
- *   return <button onClick={reset}>Cookie preferences</button>;
+ * function CookiePreferences() {
+ *   const { isDenied, optOut, optIn } = useCookiePreferences();
+ *   return isDenied ? (
+ *     <button onClick={optIn}>Enable ad measurement</button>
+ *   ) : (
+ *     <button onClick={optOut}>Opt out of ad measurement</button>
+ *   );
  * }
- * return (
- *   <MyBannerStyling>
- *     <button onClick={decline}>No thanks</button>
- *     <button onClick={accept}>Sure</button>
- *   </MyBannerStyling>
- * );
  * ```
+ */
+declare function useCookiePreferences(options?: UseCookiePreferencesOptions): UseCookiePreferencesResult;
+/**
+ * Read the current visitor consent state.
  *
- * The boolean helpers (`isPending` / `isGranted` / `isDenied`) are equivalent
- * to comparing `state` directly — they're there for readability at call sites.
+ * @deprecated Since consent v2 (opt-out model) the state is never `pending`.
+ * Use {@link useCookiePreferences} — it exposes the effective state plus
+ * `source` so you can tell a default grant from an explicit one.
+ */
+declare function useConsentState(): ConsentState;
+/**
+ * Result shape of the deprecated {@link useConsent} hook.
+ *
+ * @deprecated Use {@link UseCookiePreferencesResult} via
+ * {@link useCookiePreferences}. `isPending` is always `false` since consent v2.
  */
 interface UseConsentResult {
     state: ConsentState;
@@ -1333,6 +1447,14 @@ interface UseConsentResult {
     decline: () => void;
     reset: () => void;
 }
+/**
+ * Legacy opt-in-era consent hook.
+ *
+ * @deprecated Since consent v2 tracking defaults ON (opt-out model): the state
+ * is never `pending`, so banner UIs gated on `isPending` never render. Use
+ * {@link useCookiePreferences} for footer "cookie preferences" controls.
+ * `accept` / `decline` still work and map to `optIn` / `optOut`.
+ */
 declare function useConsent(): UseConsentResult;
 
 interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
@@ -1484,4 +1606,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, 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 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 UsePhoneFieldOptions, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, ctaClickConfigSchema, ctaClickMetadataSchema, formStartConfigSchema, formStartMetadataSchema, getConsentState, getEventDefinition, multiPageSessionConfigSchema, multiPageSessionMetadataSchema, pageViewConfigSchema, pageViewMetadataSchema, phoneClickConfigSchema, phoneClickMetadataSchema, resetConsent, scrollDepthConfigSchema, scrollDepthMetadataSchema, sdkHeartbeatConfigSchema, sdkHeartbeatMetadataSchema, sdkHeartbeatTriggersSchema, setConsentState, specificPageNameSchema, specificPageVisitConfigSchema, specificPageVisitMetadataSchema, timeOnSiteConfigSchema, timeOnSiteMetadataSchema, useConsent, useConsentState, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };
+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 };