@aranova/tracking-react 0.14.2 → 0.15.0

package/dist/{phone-utils-Dyk0F14_.d.mts → phone-utils-DlAQK-gU.d.mts}

@@ -180,11 +180,17 @@ interface TrackedField {
 declare function phoneField(name: string, raw: string, country?: CountryCode): TrackedField;
 
 /**
- * Visitor consent state stored by the SDK.
+ * Visitor consent state as reported by `getConsentState()`.
  *
- * - `pending`: the visitor has not accepted or declined yet.
- * - `granted`: consent was accepted and Google Consent Mode is updated to granted.
- * - `denied`: consent was declined and Google Consent Mode is updated to denied.
+ * Consent v2 is an opt-out model: the effective state is `granted` unless the
+ * visitor stored an explicit, unexpired decline.
+ *
+ * - `granted`: default, or an explicit opt-in.
+ * - `denied`: explicit opt-out, honored for 90 days.
+ * - `pending`: NEVER returned since consent v2 (the opt-in-era "no choice yet"
+ *   value). Retained in the union only so pre-v2 call sites keep compiling;
+ *   any `pending` branch is dead code. Use `getConsentChoice().source ===
+ *   "default"` to detect "no explicit choice".
  */
 type ConsentState = "granted" | "denied" | "pending";
 /**
@@ -296,6 +302,22 @@ interface TrackingSessionUpsertPayload {
     utm_campaign: string | null;
     utm_term: string | null;
     utm_content: string | null;
+    /**
+     * Landing attribution (ADR-016): params present in THIS session's landing
+     * URL, unlike the cookie-backed fields above which carry for 90 days and may
+     * be inherited from an earlier session's click. The backend treats key
+     * PRESENCE as "landing explicitly known" (nulls mean a param-less landing);
+     * when the landing is NOT observable — SSR, or SDKs predating these fields —
+     * the keys are omitted and the backend falls back to parsing first_page.
+     * Build via `buildLandingPayloadFields()`, which enforces this contract.
+     */
+    landing_gclid?: string | null;
+    landing_fbclid?: string | null;
+    landing_utm_source?: string | null;
+    landing_utm_medium?: string | null;
+    landing_utm_campaign?: string | null;
+    landing_utm_term?: string | null;
+    landing_utm_content?: string | null;
     first_page: string | null;
     consent_state: Record<string, unknown> | null;
     context: TrackingClientContext;
@@ -344,7 +366,11 @@ interface TrackingInitConfig {
     environment?: TrackingEnvironment;
     /** Whether to capture attribution params from `window.location`. Defaults to true. */
     autoCaptureTrackingParams?: boolean;
-    /** Whether the browser script should inject the default consent banner. */
+    /**
+     * @deprecated No-op since consent v2 (opt-out model). The packages no longer
+     * ship a consent banner; wire a footer control to
+     * `window.AranovaTracking.optOut()` / `optIn()` instead.
+     */
     renderConsentBanner?: boolean;
     /** Attribution cookie max age in seconds. Defaults to 90 days. */
     cookieMaxAgeSeconds?: number;
@@ -365,9 +391,104 @@ declare global {
             getTrackingParams: () => TrackingParams;
             getConsentState: () => ConsentState;
             setConsentState: (state: "granted" | "denied") => void;
+            getConsentChoice: () => ConsentChoice;
+            optIn: () => void;
+            optOut: (options?: SetConsentOptions) => void;
+            resetConsent: () => void;
             trackEvent: (eventType: string, metadata: Record<string, unknown>) => void;
         };
     }
 }
 
-export { type ConsentState as C, DEFAULT_PHONE_COUNTRY as D, type FormSubmitConfig as F, type GtagEnvironmentMap as G, type JsonValue as J, type MetaPixelEnvironmentMap as M, type PhoneConfig as P, type TrackingInstallSurface as T, type TrackingEnvironment as a, type TrackingClientContext as b, type TrackingParams as c, type TrackingEventCreatePayload as d, type TrackingSessionUpsertPayload as e, type FormSubmitMetadata as f, type ParsedPhone as g, type PhoneDisplayFormat as h, type TrackedField as i, type TrackingInitConfig as j, formSubmitConfigSchema as k, formSubmitMetadataSchema as l, formatPhone as m, formatPhoneAsTyped as n, jsonValueSchema as o, parsePhone as p, phoneField as q, toE164 as t };
+/**
+ * How long an explicit decline is honored before the visitor reverts to the
+ * default-granted state. Explicit grants never expire.
+ */
+declare const DEFAULT_DECLINE_TTL_DAYS = 90;
+/**
+ * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
+ */
+type GtagConsentValue = "granted" | "denied";
+/** Effective consent state — the opt-out model has no "pending". */
+type ConsentChoiceState = "granted" | "denied";
+/**
+ * Where the effective state came from: `explicit` when the visitor made a
+ * stored, still-valid choice; `default` otherwise (no choice, expired decline,
+ * storage blocked, SSR).
+ */
+type ConsentSource = "default" | "explicit";
+/**
+ * The effective consent decision plus its provenance.
+ */
+interface ConsentChoice {
+    state: ConsentChoiceState;
+    source: ConsentSource;
+    /** ISO timestamp of the explicit choice; null for the default state. */
+    updatedAt: string | null;
+    /** ISO expiry of an unexpired decline; null for grants and the default state. */
+    expiresAt: string | null;
+}
+/** Options for explicit consent writes. */
+interface SetConsentOptions {
+    /** Days an explicit decline is honored. Defaults to {@link DEFAULT_DECLINE_TTL_DAYS}. */
+    declineTtlDays?: number;
+}
+type ConsentChangeListener = (choice: ConsentChoice) => void;
+/**
+ * Subscribe to consent changes (opt-in, opt-out, reset) made in THIS tab.
+ * Cross-tab changes surface via the browser's `storage` event instead.
+ * Returns an unsubscribe function.
+ */
+declare function onConsentChange(listener: ConsentChangeListener): () => void;
+/**
+ * Resolve the visitor's effective consent (opt-out model).
+ *
+ * Default is GRANTED. Only a stored, unexpired explicit decline yields
+ * `denied`. SSR, blocked storage, and expired declines all resolve to the
+ * default. A legacy decline stored by the opt-in-era SDK (no expiry key) stays
+ * denied and gets a fresh 90-day expiry backfilled, keeping this reader
+ * consistent with the inline scripts (which treat a missing expiry as denied).
+ */
+declare function getConsentChoice(): ConsentChoice;
+/**
+ * Read the visitor's effective consent state.
+ *
+ * Opt-out model: returns `granted` unless a stored, unexpired explicit decline
+ * exists. Never returns `pending` — that value survives in {@link ConsentState}
+ * only so pre-v2 call sites keep compiling.
+ */
+declare function getConsentState(): ConsentState;
+/**
+ * Persist an explicit visitor consent choice and push it live to Google
+ * Consent Mode and the Meta Pixel.
+ *
+ * Declines expire after {@link DEFAULT_DECLINE_TTL_DAYS} days (override via
+ * `options.declineTtlDays`); grants never expire.
+ */
+declare function setConsentState(state: GtagConsentValue, options?: SetConsentOptions): void;
+/**
+ * Explicitly opt the visitor in to ad tracking (never expires).
+ */
+declare function optIn(): void;
+/**
+ * Explicitly opt the visitor out of ad tracking for
+ * {@link DEFAULT_DECLINE_TTL_DAYS} days (override via `options.declineTtlDays`).
+ *
+ * This is the primitive a client site's footer "cookie preferences" control
+ * should call — the packages ship no consent UI of their own.
+ */
+declare function optOut(options?: SetConsentOptions): void;
+/**
+ * Clear the stored explicit choice, returning the visitor to the
+ * default-granted state, and push that state live to gtag + Meta.
+ *
+ * Power a "Cookie preferences" reset in a footer:
+ *
+ * ```tsx
+ * const { reset } = useCookiePreferences();
+ * <button onClick={reset}>Reset cookie preferences</button>
+ * ```
+ */
+declare function resetConsent(): void;
+
+export { resetConsent as A, setConsentState as B, type ConsentState as C, DEFAULT_DECLINE_TTL_DAYS as D, toE164 as E, type FormSubmitConfig as F, type GtagEnvironmentMap as G, type JsonValue as J, type MetaPixelEnvironmentMap as M, type PhoneConfig as P, type SetConsentOptions as S, type TrackingParams as T, type TrackingInstallSurface as a, type TrackingEnvironment as b, type TrackingClientContext as c, type TrackingEventCreatePayload as d, type TrackingSessionUpsertPayload as e, type FormSubmitMetadata as f, type ConsentChoiceState as g, type ConsentSource as h, type ParsedPhone as i, type PhoneDisplayFormat as j, type ConsentChoice as k, DEFAULT_PHONE_COUNTRY as l, type TrackedField as m, type TrackingInitConfig as n, formSubmitConfigSchema as o, formSubmitMetadataSchema as p, formatPhone as q, formatPhoneAsTyped as r, getConsentChoice as s, getConsentState as t, jsonValueSchema as u, onConsentChange as v, optIn as w, optOut as x, parsePhone as y, phoneField as z };

package/dist/{phone-utils-Dyk0F14_.d.ts → phone-utils-DlAQK-gU.d.ts}

@@ -180,11 +180,17 @@ interface TrackedField {
 declare function phoneField(name: string, raw: string, country?: CountryCode): TrackedField;
 
 /**
- * Visitor consent state stored by the SDK.
+ * Visitor consent state as reported by `getConsentState()`.
  *
- * - `pending`: the visitor has not accepted or declined yet.
- * - `granted`: consent was accepted and Google Consent Mode is updated to granted.
- * - `denied`: consent was declined and Google Consent Mode is updated to denied.
+ * Consent v2 is an opt-out model: the effective state is `granted` unless the
+ * visitor stored an explicit, unexpired decline.
+ *
+ * - `granted`: default, or an explicit opt-in.
+ * - `denied`: explicit opt-out, honored for 90 days.
+ * - `pending`: NEVER returned since consent v2 (the opt-in-era "no choice yet"
+ *   value). Retained in the union only so pre-v2 call sites keep compiling;
+ *   any `pending` branch is dead code. Use `getConsentChoice().source ===
+ *   "default"` to detect "no explicit choice".
  */
 type ConsentState = "granted" | "denied" | "pending";
 /**
@@ -296,6 +302,22 @@ interface TrackingSessionUpsertPayload {
     utm_campaign: string | null;
     utm_term: string | null;
     utm_content: string | null;
+    /**
+     * Landing attribution (ADR-016): params present in THIS session's landing
+     * URL, unlike the cookie-backed fields above which carry for 90 days and may
+     * be inherited from an earlier session's click. The backend treats key
+     * PRESENCE as "landing explicitly known" (nulls mean a param-less landing);
+     * when the landing is NOT observable — SSR, or SDKs predating these fields —
+     * the keys are omitted and the backend falls back to parsing first_page.
+     * Build via `buildLandingPayloadFields()`, which enforces this contract.
+     */
+    landing_gclid?: string | null;
+    landing_fbclid?: string | null;
+    landing_utm_source?: string | null;
+    landing_utm_medium?: string | null;
+    landing_utm_campaign?: string | null;
+    landing_utm_term?: string | null;
+    landing_utm_content?: string | null;
     first_page: string | null;
     consent_state: Record<string, unknown> | null;
     context: TrackingClientContext;
@@ -344,7 +366,11 @@ interface TrackingInitConfig {
     environment?: TrackingEnvironment;
     /** Whether to capture attribution params from `window.location`. Defaults to true. */
     autoCaptureTrackingParams?: boolean;
-    /** Whether the browser script should inject the default consent banner. */
+    /**
+     * @deprecated No-op since consent v2 (opt-out model). The packages no longer
+     * ship a consent banner; wire a footer control to
+     * `window.AranovaTracking.optOut()` / `optIn()` instead.
+     */
     renderConsentBanner?: boolean;
     /** Attribution cookie max age in seconds. Defaults to 90 days. */
     cookieMaxAgeSeconds?: number;
@@ -365,9 +391,104 @@ declare global {
             getTrackingParams: () => TrackingParams;
             getConsentState: () => ConsentState;
             setConsentState: (state: "granted" | "denied") => void;
+            getConsentChoice: () => ConsentChoice;
+            optIn: () => void;
+            optOut: (options?: SetConsentOptions) => void;
+            resetConsent: () => void;
             trackEvent: (eventType: string, metadata: Record<string, unknown>) => void;
         };
     }
 }
 
-export { type ConsentState as C, DEFAULT_PHONE_COUNTRY as D, type FormSubmitConfig as F, type GtagEnvironmentMap as G, type JsonValue as J, type MetaPixelEnvironmentMap as M, type PhoneConfig as P, type TrackingInstallSurface as T, type TrackingEnvironment as a, type TrackingClientContext as b, type TrackingParams as c, type TrackingEventCreatePayload as d, type TrackingSessionUpsertPayload as e, type FormSubmitMetadata as f, type ParsedPhone as g, type PhoneDisplayFormat as h, type TrackedField as i, type TrackingInitConfig as j, formSubmitConfigSchema as k, formSubmitMetadataSchema as l, formatPhone as m, formatPhoneAsTyped as n, jsonValueSchema as o, parsePhone as p, phoneField as q, toE164 as t };
+/**
+ * How long an explicit decline is honored before the visitor reverts to the
+ * default-granted state. Explicit grants never expire.
+ */
+declare const DEFAULT_DECLINE_TTL_DAYS = 90;
+/**
+ * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
+ */
+type GtagConsentValue = "granted" | "denied";
+/** Effective consent state — the opt-out model has no "pending". */
+type ConsentChoiceState = "granted" | "denied";
+/**
+ * Where the effective state came from: `explicit` when the visitor made a
+ * stored, still-valid choice; `default` otherwise (no choice, expired decline,
+ * storage blocked, SSR).
+ */
+type ConsentSource = "default" | "explicit";
+/**
+ * The effective consent decision plus its provenance.
+ */
+interface ConsentChoice {
+    state: ConsentChoiceState;
+    source: ConsentSource;
+    /** ISO timestamp of the explicit choice; null for the default state. */
+    updatedAt: string | null;
+    /** ISO expiry of an unexpired decline; null for grants and the default state. */
+    expiresAt: string | null;
+}
+/** Options for explicit consent writes. */
+interface SetConsentOptions {
+    /** Days an explicit decline is honored. Defaults to {@link DEFAULT_DECLINE_TTL_DAYS}. */
+    declineTtlDays?: number;
+}
+type ConsentChangeListener = (choice: ConsentChoice) => void;
+/**
+ * Subscribe to consent changes (opt-in, opt-out, reset) made in THIS tab.
+ * Cross-tab changes surface via the browser's `storage` event instead.
+ * Returns an unsubscribe function.
+ */
+declare function onConsentChange(listener: ConsentChangeListener): () => void;
+/**
+ * Resolve the visitor's effective consent (opt-out model).
+ *
+ * Default is GRANTED. Only a stored, unexpired explicit decline yields
+ * `denied`. SSR, blocked storage, and expired declines all resolve to the
+ * default. A legacy decline stored by the opt-in-era SDK (no expiry key) stays
+ * denied and gets a fresh 90-day expiry backfilled, keeping this reader
+ * consistent with the inline scripts (which treat a missing expiry as denied).
+ */
+declare function getConsentChoice(): ConsentChoice;
+/**
+ * Read the visitor's effective consent state.
+ *
+ * Opt-out model: returns `granted` unless a stored, unexpired explicit decline
+ * exists. Never returns `pending` — that value survives in {@link ConsentState}
+ * only so pre-v2 call sites keep compiling.
+ */
+declare function getConsentState(): ConsentState;
+/**
+ * Persist an explicit visitor consent choice and push it live to Google
+ * Consent Mode and the Meta Pixel.
+ *
+ * Declines expire after {@link DEFAULT_DECLINE_TTL_DAYS} days (override via
+ * `options.declineTtlDays`); grants never expire.
+ */
+declare function setConsentState(state: GtagConsentValue, options?: SetConsentOptions): void;
+/**
+ * Explicitly opt the visitor in to ad tracking (never expires).
+ */
+declare function optIn(): void;
+/**
+ * Explicitly opt the visitor out of ad tracking for
+ * {@link DEFAULT_DECLINE_TTL_DAYS} days (override via `options.declineTtlDays`).
+ *
+ * This is the primitive a client site's footer "cookie preferences" control
+ * should call — the packages ship no consent UI of their own.
+ */
+declare function optOut(options?: SetConsentOptions): void;
+/**
+ * Clear the stored explicit choice, returning the visitor to the
+ * default-granted state, and push that state live to gtag + Meta.
+ *
+ * Power a "Cookie preferences" reset in a footer:
+ *
+ * ```tsx
+ * const { reset } = useCookiePreferences();
+ * <button onClick={reset}>Reset cookie preferences</button>
+ * ```
+ */
+declare function resetConsent(): void;
+
+export { resetConsent as A, setConsentState as B, type ConsentState as C, DEFAULT_DECLINE_TTL_DAYS as D, toE164 as E, type FormSubmitConfig as F, type GtagEnvironmentMap as G, type JsonValue as J, type MetaPixelEnvironmentMap as M, type PhoneConfig as P, type SetConsentOptions as S, type TrackingParams as T, type TrackingInstallSurface as a, type TrackingEnvironment as b, type TrackingClientContext as c, type TrackingEventCreatePayload as d, type TrackingSessionUpsertPayload as e, type FormSubmitMetadata as f, type ConsentChoiceState as g, type ConsentSource as h, type ParsedPhone as i, type PhoneDisplayFormat as j, type ConsentChoice as k, DEFAULT_PHONE_COUNTRY as l, type TrackedField as m, type TrackingInitConfig as n, formSubmitConfigSchema as o, formSubmitMetadataSchema as p, formatPhone as q, formatPhoneAsTyped as r, getConsentChoice as s, getConsentState as t, jsonValueSchema as u, onConsentChange as v, optIn as w, optOut as x, parsePhone as y, phoneField as z };

package/dist/phone.d.mts

@@ -1,3 +1,3 @@
-export { D as DEFAULT_PHONE_COUNTRY, g as ParsedPhone, P as PhoneConfig, h as PhoneDisplayFormat, i as TrackedField, m as formatPhone, n as formatPhoneAsTyped, p as parsePhone, q as phoneField, t as toE164 } from './phone-utils-Dyk0F14_.mjs';
+export { l as DEFAULT_PHONE_COUNTRY, i as ParsedPhone, P as PhoneConfig, j as PhoneDisplayFormat, m as TrackedField, q as formatPhone, r as formatPhoneAsTyped, y as parsePhone, z as phoneField, E as toE164 } from './phone-utils-DlAQK-gU.mjs';
 export { CountryCode } from 'libphonenumber-js';
 import 'zod';

package/dist/phone.d.ts

@@ -1,3 +1,3 @@
-export { D as DEFAULT_PHONE_COUNTRY, g as ParsedPhone, P as PhoneConfig, h as PhoneDisplayFormat, i as TrackedField, m as formatPhone, n as formatPhoneAsTyped, p as parsePhone, q as phoneField, t as toE164 } from './phone-utils-Dyk0F14_.js';
+export { l as DEFAULT_PHONE_COUNTRY, i as ParsedPhone, P as PhoneConfig, j as PhoneDisplayFormat, m as TrackedField, q as formatPhone, r as formatPhoneAsTyped, y as parsePhone, z as phoneField, E as toE164 } from './phone-utils-DlAQK-gU.js';
 export { CountryCode } from 'libphonenumber-js';
 import 'zod';

package/dist/phone.js

@@ -29,79 +29,6 @@ __export(phone_utils_exports, {
 });
 module.exports = __toCommonJS(phone_utils_exports);
 
-// ../tracking-core/src/consent.ts
-var CONSENT_STATE_KEY = "consent_state";
-var grantedListeners = /* @__PURE__ */ new Set();
-function onConsentGranted(listener) {
-  grantedListeners.add(listener);
-  return () => {
-    grantedListeners.delete(listener);
-  };
-}
-function getConsentState() {
-  if (typeof window === "undefined") return "pending";
-  try {
-    const storedState = window.localStorage.getItem(CONSENT_STATE_KEY);
-    if (storedState === "granted" || storedState === "denied") return storedState;
-  } catch {
-  }
-  return "pending";
-}
-
-// ../tracking-core/src/gtag.ts
-var SEND_TO_RE = /^AW-[A-Za-z0-9]+\/[A-Za-z0-9_-]+$/;
-function isValidSendTo(sendTo) {
-  return SEND_TO_RE.test(sendTo);
-}
-function fireGtagConversion(input) {
-  if (typeof window === "undefined" || typeof window.gtag !== "function") return false;
-  if (!isValidSendTo(input.sendTo)) return false;
-  const params = { send_to: input.sendTo };
-  if (input.value != null) params.value = input.value;
-  if (input.currency) params.currency = input.currency;
-  if (input.transactionId) params.transaction_id = input.transactionId;
-  try {
-    window.gtag("event", "conversion", params);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// ../tracking-core/src/resources/conversion-firing.ts
-var DEDUP_PREFIX = "_aranova_conv_";
-var pendingQueue = [];
-function dedupKey(input) {
-  return `${DEDUP_PREFIX}${input.transactionId ?? ""}:${input.sendTo}`;
-}
-function alreadyFired(input) {
-  if (!input.transactionId || typeof window === "undefined") return false;
-  try {
-    return window.sessionStorage.getItem(dedupKey(input)) !== null;
-  } catch {
-    return false;
-  }
-}
-function markFired(input) {
-  if (!input.transactionId || typeof window === "undefined") return;
-  try {
-    window.sessionStorage.setItem(dedupKey(input), "1");
-  } catch {
-  }
-}
-function fireOnce(input) {
-  if (alreadyFired(input)) return;
-  if (fireGtagConversion(input)) markFired(input);
-}
-function flushPendingConversions() {
-  if (getConsentState() !== "granted") return;
-  while (pendingQueue.length > 0) {
-    const input = pendingQueue.shift();
-    if (input) fireOnce(input);
-  }
-}
-if (typeof window !== "undefined") onConsentGranted(flushPendingConversions);
-
 // ../tracking-core/src/session.ts
 var SESSION_IDLE_MS = 30 * 60 * 1e3;