@aranova/tracking-next 0.9.0 → 0.9.1

package/README.md

@@ -216,9 +216,65 @@ npx @aranova/tracking-cli gen          # reads ARANOVA_TRACKING_SECRET_KEY from
 See the full guide: [sales-tracking.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/sales-tracking.md)
 and the CLI reference: [cli.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/cli.md).
 
+## Consent UI
+
+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.
+
+```tsx
+import { ConsentBanner } from '@aranova/tracking-next';
+
+// Drop-in (already wired in the root layout example above)
+<ConsentBanner />
+```
+
+All props are optional:
+
+```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
+/>
+```
+
+### Fully custom UI — `useConsent()`
+
+For a bespoke banner, skip the component and drive your own UI with the headless hook:
+
+```tsx
+'use client';
+import { useConsent } from '@aranova/tracking-next';
+
+function CookieBar() {
+  const { state, accept, decline, reset, isPending } = useConsent();
+
+  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>
+  );
+}
+```
+
+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 (server actions that revalidate after an account change, etc.).
+
 ## Exports
 
-- Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, `ConsentBanner`, hooks, event types, and `createSalesClient()` (isomorphic sales client — public key writes, secret key reads/CRUD) + money helpers (`toMinor`/`fromMinor`/`formatMoney`)
+- Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, `ConsentBanner` (+ `ConsentBannerProps`), `useConsent` (+ `UseConsentResult`), `useConsentState`, `useGclid`, `useTrackingParams`, standalone consent helpers (`getConsentState`, `setConsentState`, `resetConsent`), event types, and `createSalesClient()` (isomorphic sales client — public key writes, secret key reads/CRUD) + money helpers (`toMinor`/`fromMinor`/`formatMoney`)
 - `@aranova/tracking-next/middleware`: `createTrackingMiddleware()`
 - `@aranova/tracking-next/server`: `getTrackingParamsServer()`
 - Codegen: [`@aranova/tracking-cli`](https://www.npmjs.com/package/@aranova/tracking-cli) — `gen` typed service unions (devDependency)

package/dist/index.d.mts

@@ -2,8 +2,8 @@ import { C as ConsentState, T as TrackingInstallSurface, a as TrackingEnvironmen
 export { f as TrackingInitConfig } from './types-BPJLgMsG.mjs';
 import { z } from 'zod';
 import * as src from 'src';
+import { ReactNode, CSSProperties } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
 
 /**
  * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
@@ -21,6 +21,22 @@ declare function getConsentState(): ConsentState;
  * loaded.
  */
 declare function setConsentState(state: GtagConsentValue): void;
+/**
+ * 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>
+ * ```
+ *
+ * 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.
+ */
+declare function resetConsent(): void;
 
 interface TrackingContextInput {
     packageName?: string | null;
@@ -1580,12 +1596,69 @@ declare class AranovaApiError extends Error {
 }
 
 /**
- * Default non-blocking consent banner for Next.js installs.
+ * Default non-blocking consent banner.
+ *
+ * Renders only while consent is `pending`; collapses to `null` once the
+ * visitor has chosen.
  *
- * Renders only while consent is `pending`. Accept/decline choices are stored
- * in localStorage and propagated to Google Consent Mode when gtag is loaded.
+ * **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-next/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')}
+ * />
  */
-declare function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
+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;
+}
+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.
@@ -1602,8 +1675,46 @@ declare function useTrackingParams(): TrackingParams;
 /**
  * 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.
  */
 declare function useConsentState(): ConsentState;
+/**
+ * The headless consent surface — state + actions in one hook.
+ *
+ * Build a fully-custom banner without losing the gtag-sync, localStorage
+ * persistence, or cross-tab propagation:
+ *
+ * ```tsx
+ * const { state, accept, decline, reset, isPending } = useConsent();
+ *
+ * if (!isPending) {
+ *   return <button onClick={reset}>Cookie preferences</button>;
+ * }
+ * return (
+ *   <MyBannerStyling>
+ *     <button onClick={decline}>No thanks</button>
+ *     <button onClick={accept}>Sure</button>
+ *   </MyBannerStyling>
+ * );
+ * ```
+ *
+ * The boolean helpers (`isPending` / `isGranted` / `isDenied`) are equivalent
+ * to comparing `state` directly — they're there for readability at call sites.
+ */
+interface UseConsentResult {
+    state: ConsentState;
+    isPending: boolean;
+    isGranted: boolean;
+    isDenied: boolean;
+    accept: () => void;
+    decline: () => void;
+    reset: () => void;
+}
+declare function useConsent(): UseConsentResult;
 
 /**
  * Props for the Next.js Google Ads tracking component.
@@ -1692,4 +1803,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
  */
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { AranovaApiError, type AutomaticEventName, ConsentBanner, ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, setConsentState, toMinor, useConsentState, useGclid, useTrackingParams };
+export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, resetConsent, setConsentState, toMinor, useConsent, useConsentState, useGclid, useTrackingParams };

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import { C as ConsentState, T as TrackingInstallSurface, a as TrackingEnvironmen
 export { f as TrackingInitConfig } from './types-BPJLgMsG.js';
 import { z } from 'zod';
 import * as src from 'src';
+import { ReactNode, CSSProperties } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
 
 /**
  * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
@@ -21,6 +21,22 @@ declare function getConsentState(): ConsentState;
  * loaded.
  */
 declare function setConsentState(state: GtagConsentValue): void;
+/**
+ * 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>
+ * ```
+ *
+ * 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.
+ */
+declare function resetConsent(): void;
 
 interface TrackingContextInput {
     packageName?: string | null;
@@ -1580,12 +1596,69 @@ declare class AranovaApiError extends Error {
 }
 
 /**
- * Default non-blocking consent banner for Next.js installs.
+ * Default non-blocking consent banner.
+ *
+ * Renders only while consent is `pending`; collapses to `null` once the
+ * visitor has chosen.
  *
- * Renders only while consent is `pending`. Accept/decline choices are stored
- * in localStorage and propagated to Google Consent Mode when gtag is loaded.
+ * **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-next/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')}
+ * />
  */
-declare function ConsentBanner(): react_jsx_runtime.JSX.Element | null;
+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;
+}
+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.
@@ -1602,8 +1675,46 @@ declare function useTrackingParams(): TrackingParams;
 /**
  * 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.
  */
 declare function useConsentState(): ConsentState;
+/**
+ * The headless consent surface — state + actions in one hook.
+ *
+ * Build a fully-custom banner without losing the gtag-sync, localStorage
+ * persistence, or cross-tab propagation:
+ *
+ * ```tsx
+ * const { state, accept, decline, reset, isPending } = useConsent();
+ *
+ * if (!isPending) {
+ *   return <button onClick={reset}>Cookie preferences</button>;
+ * }
+ * return (
+ *   <MyBannerStyling>
+ *     <button onClick={decline}>No thanks</button>
+ *     <button onClick={accept}>Sure</button>
+ *   </MyBannerStyling>
+ * );
+ * ```
+ *
+ * The boolean helpers (`isPending` / `isGranted` / `isDenied`) are equivalent
+ * to comparing `state` directly — they're there for readability at call sites.
+ */
+interface UseConsentResult {
+    state: ConsentState;
+    isPending: boolean;
+    isGranted: boolean;
+    isDenied: boolean;
+    accept: () => void;
+    decline: () => void;
+    reset: () => void;
+}
+declare function useConsent(): UseConsentResult;
 
 /**
  * Props for the Next.js Google Ads tracking component.
@@ -1692,4 +1803,4 @@ interface CreateTrackingResult<TRegistry extends TriggerRegistryConfig> {
  */
 declare function createTracking<TRegistry extends TriggerRegistryConfig>(options: CreateTrackingOptions<TRegistry>): CreateTrackingResult<TRegistry>;
 
-export { AranovaApiError, type AutomaticEventName, ConsentBanner, ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, setConsentState, toMinor, useConsentState, useGclid, useTrackingParams };
+export { AranovaApiError, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, ConsentState, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, type EventConfig, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, type FormSubmitConfig, type FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, type JsonValue, type ManualEventName, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, type PhoneClickConfig, type PhoneClickMetadata, type PublicServiceItem, type RegisteredAutomaticEvents, type RegisteredManualEvents, type Sale, type SaleCursorPage, type SaleInput, type SaleItem, type SaleItemInput, type SaleListPage, type SaleListQuery, type SaleUpdateInput, type SalesClient, type SalesClientConfig, type SalesTransportConfig, type ScrollDepthConfig, type ScrollDepthMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, type SupportedCurrency, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, captureTrackingParamsFromLocation, createSalesClient, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, fetchServices, formatMoney, fromMinor, getConsentState, resetConsent, setConsentState, toMinor, useConsent, useConsentState, useGclid, useTrackingParams };