@aranova/tracking-react 0.24.0 → 0.25.0

package/README.md

@@ -115,7 +115,7 @@ export function LeadForm() {
 }
 ```
 
-`fields[].value` can be any JSON value: string, number, boolean, null, array, or object. Values must be JSON-serializable because events are stored as first-party JSONB. Intentionally submitted lead fields may include raw names, emails, phone numbers, addresses, selections, free-text messages, and submitted file data for first-party analytics and lead operations. Build the array explicitly from the submitted form; the SDK never scrapes arbitrary DOM fields. `File`/`Blob` objects must be converted to a JSON representation, and the complete event metadata must fit the 4 KB limit; upload larger files separately and send their storage reference. Never send passwords, authentication tokens, payment-card/bank credentials, or private keys. Apply the client's privacy notice, consent, retention, and regulated-data requirements. Google offline matching uses normalized, server-side SHA-256-hashed identifiers — not raw free-text/file metadata.
+`fields[].value` can be any JSON value: string, number, boolean, null, array, or object. Values must be JSON-serializable because events are stored as first-party JSONB. Intentionally submitted lead fields may include raw names, emails, phone numbers, addresses, selections, free-text messages, and submitted file data for first-party analytics and lead operations. Build the array explicitly from the submitted form; the SDK never scrapes arbitrary DOM fields. `File`/`Blob` objects must be converted to a JSON representation; upload larger files separately and send their storage reference. No byte limit is enforced on event metadata — but a submit fired just before navigation flushes over `keepalive`, which browsers cap near 64 KB and drop silently, so keep inlined payloads small. Never send passwords, authentication tokens, payment-card/bank credentials, or private keys. Apply the client's privacy notice, consent, retention, and regulated-data requirements. Google offline matching uses normalized, server-side SHA-256-hashed identifiers — not raw free-text/file metadata.
 
 ### Phone clicks (`tel:` taps) — manual or auto-capture
 

package/dist/client.d.mts

@@ -0,0 +1,366 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, InputHTMLAttributes, ChangeEvent, FocusEvent } from 'react';
+import { G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, h as ConsentState, f as ConsentChoiceState, g as ConsentSource, T as TrackingParams, b as TrackingEnvironment, k as PhoneConfig, P as ParsedPhone, l as PhoneDisplayFormat } from './phone-utils-BVzSNBf1.mjs';
+import { T as TrackingConfigReference, C as ConversionConfig } from './tracking-config-runtime-BnUlS_Ae.mjs';
+import { N as TriggerRegistryConfig, Q as TypedTrackingClient } from './ingest-typed-BioxtBJD.mjs';
+import { CountryCode } from 'libphonenumber-js';
+import 'zod';
+import 'src';
+
+/**
+ * Legacy opt-in-era consent banner.
+ *
+ * @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. */
+    message?: ReactNode;
+    /** Optional bold title above the body text. */
+    title?: ReactNode;
+    /** Label for the accept button. Default: `"Accept"`. */
+    acceptLabel?: string;
+    /** Label for the decline button. Default: `"Decline"`. */
+    declineLabel?: string;
+    /** Optional link inline with the message (e.g. to a privacy policy). */
+    policyHref?: string;
+    /** Visible text for {@link policyHref}. Default: `"Learn more"`. */
+    policyLabel?: string;
+    /**
+     * Fires after the consent state is persisted + propagated to gtag. Useful
+     * for emitting your own analytics event on the choice.
+     */
+    onAccept?: () => void;
+    onDecline?: () => void;
+    /** Where the banner docks. Default: `"bottom"`. */
+    position?: "top" | "bottom";
+    /**
+     * Visual theme. `"auto"` follows `prefers-color-scheme`. Default: `"light"`.
+     */
+    theme?: "light" | "dark" | "auto";
+    /** Class added to the outer wrapper for additional styling hooks. */
+    className?: string;
+    /** Inline style overrides applied to the outer wrapper after the defaults. */
+    style?: CSSProperties;
+}
+/**
+ * @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 ConsentBanner({ message, title, acceptLabel, declineLabel, policyHref, policyLabel, onAccept, onDecline, position, theme, className, style, }?: ConsentBannerProps): ReactNode;
+
+/**
+ * Props for the combined ad-platform tag loader.
+ *
+ * Every field is optional and independent: pass the Google fields, the Meta
+ * fields, or both. For each platform a labelled `*Ids` map (ALL loaded) takes
+ * precedence over the single `*Id` shortcut.
+ */
+interface AdPlatformTrackingProps {
+    /** Single Google Ads tag id, e.g. `AW-123456789`. */
+    gtagId?: string;
+    /** Labelled Google Ads tag map — ALL loaded; wins over `gtagId`. */
+    gtagIds?: GtagEnvironmentMap;
+    /** R2-authoritative Google tracking config. When set, static gtagId(s) are ignored. */
+    trackingConfig?: TrackingConfigReference;
+    /** Fire a Google page view from this standalone loader. Leave false when using TrackingProvider. */
+    standalonePageView?: boolean;
+    /** Single Meta Pixel id, e.g. `123456789012345`. */
+    metaPixelId?: string;
+    /** Labelled Meta Pixel map — ALL loaded; wins over `metaPixelId`. */
+    metaPixelIds?: MetaPixelEnvironmentMap;
+}
+/**
+ * Client component that loads the configured ad-platform tags — the Google tag
+ * (`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
+ * standalone component when you want the ad tags WITHOUT the event-ingest SDK.
+ */
+declare function AdPlatformTracking({ gtagId, gtagIds, trackingConfig, standalonePageView, metaPixelId, metaPixelIds, }: AdPlatformTrackingProps): null;
+
+/**
+ * Props for the Google Ads tracking component.
+ *
+ * Accepts either a single `gtagId` (legacy) or a labelled `gtagIds` map
+ * where ALL entries are loaded simultaneously via `gtag('config', ...)`.
+ */
+type GoogleAdsTrackingProps = {
+    gtagId: string;
+    gtagIds?: undefined;
+} | {
+    gtagId?: undefined;
+    gtagIds: GtagEnvironmentMap;
+};
+/**
+ * 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.
+ */
+declare function GoogleAdsTracking(props: GoogleAdsTrackingProps): null;
+
+/**
+ * Read the captured Google Ads click id from first-party cookies.
+ *
+ * Returns `null` during SSR and before the client has mounted.
+ */
+declare function useGclid(): string | null;
+/**
+ * Read all captured attribution parameters from first-party cookies.
+ *
+ * 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;
+}
+/**
+ * The headless cookie-preferences surface returned by
+ * {@link useCookiePreferences}.
+ */
+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;
+}
+/**
+ * Headless cookie-preferences hook for the opt-out consent model (consent v2).
+ *
+ * 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
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function useCookiePreferences(options?: UseCookiePreferencesOptions): UseCookiePreferencesResult;
+/**
+ * Read the current visitor consent state.
+ *
+ * @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;
+    isPending: boolean;
+    isGranted: boolean;
+    isDenied: boolean;
+    accept: () => void;
+    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> {
+    /**
+     * Public tracking API key issued for this business.
+     *
+     * This key is safe to expose in browser code. Abuse is bounded by the
+     * server-side origin allowlist and rate limits.
+     */
+    apiKey: string;
+    /**
+     * Tracking endpoint base URL, usually ending in `/tracking`.
+     *
+     * The client posts events to `${endpoint}/events`.
+     */
+    endpoint: string;
+    /**
+     * Trigger registry. Determines which events the SDK fires automatically
+     * and which ones the consumer can fire manually via `trackEvent()`.
+     * `automatic.page_view` is required — every tracking install needs it.
+     */
+    triggers: TRegistry;
+    /**
+     * Deployment environment label reported in session context.
+     *
+     * Does not affect which gtag IDs are loaded — all configured IDs are
+     * loaded simultaneously. This value is purely for event tagging so the
+     * dashboard can filter by environment.
+     */
+    environment?: TrackingEnvironment;
+    /**
+     * When true, the typed client validates every `trackEvent()` metadata
+     * payload through the Zod schema before forwarding. Errors are thrown
+     * loudly. Leave off in prod; turn on in dev to catch shape bugs early.
+     */
+    debug?: boolean;
+    /**
+     * Phone-field display + default-country config, read by `usePhoneField` /
+     * `<PhoneField>`. Display is customizable; the transmitted value is always E.164.
+     */
+    phone?: PhoneConfig;
+    /**
+     * GAP28 / unified-goal: enable real-time on-site conversion firing. When set, the SDK
+     * fetches the per-business config from `cdnUrl` (optional offline `baked` fallback) and
+     * AUTOMATICALLY fires `gtag('event','conversion')` for any automatic event-goal
+     * (scroll/time/page-view/…) whose trigger threshold a detector crosses. Omit to keep events
+     * analytics-only. (Sale + manual-event firing lives in the server/browser sales client.)
+     */
+    conversionConfig?: {
+        cdnUrl: string;
+        baked?: ConversionConfig | null;
+    };
+    /**
+     * R2-authoritative config reference — `ARANOVA_TRACKING_CONFIG` from
+     * `tracking-cli gen`. Wins over `conversionConfig`. The object URL is composed
+     * from `businessId` + `environment` against the production CDN; spread in a
+     * `cdnBaseUrl` to read it from somewhere else, e.g.
+     * `{ ...ARANOVA_TRACKING_CONFIG, cdnBaseUrl: import.meta.env.VITE_ARANOVA_CDN_BASE_URL }`.
+     */
+    trackingConfig?: TrackingConfigReference;
+}
+interface TrackingProviderProps {
+    /**
+     * Optional Google Ads tag id, for example `AW-123456789`.
+     *
+     * If omitted and `gtagIds` is also omitted, no gtag script is loaded.
+     */
+    gtagId?: string;
+    /**
+     * Labelled map of Google Ads tag IDs. ALL are loaded simultaneously.
+     * When provided, `gtagId` is ignored.
+     */
+    gtagIds?: GtagEnvironmentMap;
+    /** Optional Meta Pixel id, for example `123456789012345`. */
+    metaPixelId?: string;
+    /**
+     * Labelled map of Meta Pixel IDs. ALL are loaded simultaneously.
+     * When provided, `metaPixelId` is ignored.
+     */
+    metaPixelIds?: MetaPixelEnvironmentMap;
+    /**
+     * Application tree that should have access to the scoped tracking client.
+     */
+    children: ReactNode;
+}
+interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
+    /**
+     * Provider component that initializes the page-level tracking client.
+     *
+     * Mount this once near the root of the React tree.
+     */
+    TrackingProvider: (props: TrackingProviderProps) => ReactNode;
+    /**
+     * Hook that returns the registry-typed tracking client.
+     *
+     * Import this hook from your local tracking module, not directly from the
+     * package root, so TypeScript preserves your trigger registry.
+     */
+    useTracking: () => TypedTrackingClient<TRegistry>;
+}
+declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
+
+/** Resolve the effective phone config (provider value or built-in defaults). */
+declare function usePhoneConfig(): {
+    defaultCountry: CountryCode;
+    display: PhoneDisplayFormat;
+};
+interface UsePhoneFieldOptions {
+    defaultValue?: string;
+    /** Overrides the provider's `defaultCountry`. */
+    country?: CountryCode;
+    /** Overrides the provider's `display` (applied to the settled value on blur). */
+    display?: PhoneDisplayFormat;
+    /** Notified with the canonical E.164 (or `null`) on every change. */
+    onValueChange?: (e164: string | null) => void;
+}
+interface PhoneInputProps {
+    value: string;
+    onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    onBlur: (event: FocusEvent<HTMLInputElement>) => void;
+    type: "tel";
+    inputMode: "tel";
+    autoComplete: "tel";
+}
+interface PhoneFieldApi {
+    /** Display value for the `<input>` (live `AsYouType` while typing). */
+    value: string;
+    /** Canonical E.164 — what gets transmitted. `null` while invalid/incomplete. */
+    e164: string | null;
+    isValid: boolean;
+    /** Validation message, surfaced only after blur with non-empty invalid input. */
+    error: string | null;
+    parsed: ParsedPhone;
+    /** Spread onto an `<input>`: pre-wires value/onChange/onBlur/type/inputMode/autoComplete. */
+    inputProps: PhoneInputProps;
+}
+/** Headless phone field — the client owns the markup. */
+declare function usePhoneField(opts?: UsePhoneFieldOptions): PhoneFieldApi;
+interface PhoneFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "onChange"> {
+    country?: CountryCode;
+    /** Controlled display value. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    /** Receives the native change event (RHF `register().onChange` or your own); the
+     *  event's `target.value` is already `AsYouType`-formatted. */
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+    /** Receives the canonical E.164 (or `null`) on every change. */
+    onE164Change?: (e164: string | null) => void;
+}
+/**
+ * Batteries-included phone input. Composes identically with react-hook-form
+ * `{...register('phone')}` and with controlled state — the `AsYouType` +
+ * mutate-`e.target.value`-before-`onChange` technique lives inside, so RHF and
+ * controlled parents both receive the formatted value, and the wire value stays
+ * E.164.
+ */
+declare const PhoneField: react.ForwardRefExoticComponent<PhoneFieldProps & react.RefAttributes<HTMLInputElement>>;
+
+export { AdPlatformTracking, type AdPlatformTrackingProps, ConsentBanner, type ConsentBannerProps, type CreateTrackingOptions, type CreateTrackingResult, GoogleAdsTracking, type GoogleAdsTrackingProps, PhoneField, type PhoneFieldApi, type PhoneFieldProps, type PhoneInputProps, type TrackingProviderProps, type UseConsentResult, type UseCookiePreferencesOptions, type UseCookiePreferencesResult, type UsePhoneFieldOptions, createTracking, useConsent, useConsentState, useCookiePreferences, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };