@aranova/tracking-next 0.24.0 → 0.25.0

package/README.md

@@ -103,6 +103,13 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 creates React context — the module that calls it is a Client Component. Your root layout
 stays a Server Component and just renders the client `<TrackingProvider>`.
 
+`<AdPlatformTracking>` needs no wrapper of your own: the package's React surface is built
+as a `"use client"` entry, so importing it from the package root inside a Server Component
+gives you a real client boundary. (Before 0.25.0 it did not — the directive was stripped at
+bundle time and this example failed with `useEffect is not a function`, which is why some
+sites still carry a hand-rolled client wrapper. Those keep working; they are just no longer
+necessary.)
+
 **No consumer `<Suspense>` boundary is required.** The provider reads `useSearchParams()`
 only inside its own internal `<Suspense>` boundary, so it never opts the enclosing route out
 of static prerendering. A fully static page (including one with `export const dynamic = 'error'`)
@@ -172,7 +179,7 @@ export function LeadForm() {
 }
 ```
 
-`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.
+`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; 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
 
@@ -597,6 +604,10 @@ Reads are best-effort: network/parse failures degrade to `null`/empty — a blog
   (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`); calendar
   read surface + headless hooks (`CalendarClientProvider`, `useCalendarBusy`, `useSlots`,
   `useBookingForm`) — booking **writes** are not here, see `/calendar-server`
+- `@aranova/tracking-next/client`: the React surface behind its `"use client"` boundary
+  (components, hooks, `createTracking`, `PhoneField`). The root entry re-exports all of it, so
+  import from the root as shown above — this subpath exists so the directive survives bundling,
+  and is available if you ever want to import the boundary explicitly.
 - `@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.
 - `@aranova/tracking-next/calendar`: **React-free, read-only** — `createCalendarReadClient`, `computeSlots`, timezone helpers, and the booking types. Public key, browser-safe. Deliberately exposes no write verb.
 - `@aranova/tracking-next/calendar-server`: **`server-only`** — `createCalendarWriteClient` and `createCalendarRoutes()` (drop-in booking route handler). Secret key; importing this from a client component fails the build.

package/dist/client.d.mts

@@ -0,0 +1,350 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, InputHTMLAttributes, ChangeEvent, FocusEvent } from 'react';
+import { h as ConsentState, f as ConsentChoiceState, g as ConsentSource, T as TrackingParams, G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, b as TrackingEnvironment, k as PhoneConfig, P as ParsedPhone, l as PhoneDisplayFormat } from './phone-utils-BVzSNBf1.mjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+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;
+
+/**
+ * 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;
+
+/**
+ * Props for the combined Next.js 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;
+}
+/**
+ * Next.js client component that loads the configured ad-platform tags — the
+ * Google tag (`gtag`) and/or the Meta Pixel (`fbq`) — with Consent Mode, via
+ * `next/script`. Render once in the root layout; omit a platform's props to
+ * skip it. Renders no visible UI.
+ */
+declare function AdPlatformTracking({ gtagId, gtagIds, trackingConfig, standalonePageView, metaPixelId, metaPixelIds, }: AdPlatformTrackingProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for the Next.js 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;
+};
+/**
+ * Next.js client component that loads Google Ads gtag with Consent Mode.
+ *
+ * Render in the root layout `<head>` when the client site runs paid Google
+ * Ads. The component injects Next `<Script>` tags and renders no visible UI.
+ */
+declare function GoogleAdsTracking(props: GoogleAdsTrackingProps): react_jsx_runtime.JSX.Element | null;
+
+interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
+    /**
+     * Public tracking API key issued for this business.
+     *
+     * This key is safe to expose via `NEXT_PUBLIC_*` env vars.
+     */
+    apiKey: string;
+    /**
+     * Tracking endpoint base URL, usually ending in `/tracking`.
+     */
+    endpoint: string;
+    /**
+     * Trigger registry that controls automatic events and typed manual events.
+     */
+    triggers: TRegistry;
+    /**
+     * Deployment environment label reported in session context.
+     */
+    environment?: TrackingEnvironment;
+    /**
+     * Labelled map of Google Ads tag IDs. Included in session context and
+     * heartbeat metadata so the dashboard can show what's configured.
+     *
+     * This does NOT load the gtag scripts — use `<GoogleAdsTracking gtagIds={...} />`
+     * in the root layout for that. This option only controls what's reported
+     * in the tracking payload context.
+     */
+    gtagIds?: Record<string, string>;
+    /**
+     * Validate manual event metadata at runtime before queueing.
+     *
+     * Enable in development to catch shape bugs. Leave disabled in production so
+     * analytics can never throw into the host app.
+     */
+    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 whose
+     * trigger threshold a detector crosses. Omit to keep events analytics-only.
+     */
+    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: process.env.NEXT_PUBLIC_ARANOVA_CDN_BASE_URL }`.
+     */
+    trackingConfig?: TrackingConfigReference;
+}
+interface TrackingProviderProps {
+    /**
+     * Application subtree that should have access to the tracking client.
+     */
+    children: ReactNode;
+}
+interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
+    /**
+     * Client component provider for the Next.js App Router integration.
+     */
+    TrackingProvider: (props: TrackingProviderProps) => ReactNode;
+    /**
+     * Hook that returns the registry-typed tracking client.
+     */
+    useTracking: () => TypedTrackingClient<TRegistry>;
+}
+/**
+ * Next.js App Router version of the `createTracking()` factory. Uses
+ * `usePathname` + `useSearchParams` from `next/navigation` for SPA route
+ * detection rather than patching `history.pushState`, because Next's
+ * router does not always go through the History API for transitions.
+ *
+ * Usage is identical to the React factory — call this once at app
+ * startup and export the returned `TrackingProvider` + `useTracking`
+ * from your own module, then import them everywhere else. `GoogleAdsTracking`
+ * is still imported separately and placed in the root layout's `<head>`
+ * when the client runs paid ads.
+ */
+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 };