@thg-agentic/hyper-personalisation-web 0.0.0-stage → 3.17.1

package/types/consent.d.ts

@@ -0,0 +1,126 @@
+export type ConsentPurpose =
+	| 'analytics'
+	| 'marketing'
+	| 'personalisation'
+	| 'ad_user_data'
+	| 'ad_personalization';
+
+/** schemas/common/consent-state.json: true granted, false refused, null never asked. */
+export type ConsentState = Record<ConsentPurpose, boolean | null>;
+
+/**
+ * context.consent.basis (spec 1.5): who decided whether an event may be collected. `visitor` is the
+ * visitor's own answer, where null is unanswered; `host` is the site's own decision.
+ */
+export type ConsentBasis = 'visitor' | 'host';
+
+export declare const CONSENT_BASIS: Readonly<{
+	visitor: 'visitor';
+	host: 'host';
+}>;
+
+/** context.consent when the SDK has no adapter: `{ basis: 'host' }`. */
+export declare function hostConsent(): { basis: 'host' };
+
+export interface ConsentAdapter {
+	/** Recorded as context.consent.source. */
+	name: string;
+	/**
+	 * Recorded as context.consent.basis. Default `visitor`; `staticConsent` is `host`. Set `host` only
+	 * for an adapter that reports the site's own decision rather than asking the visitor.
+	 */
+	readonly basis?: ConsentBasis;
+	/** Null while the CMP has not answered. */
+	read(): Partial<ConsentState> | null;
+	/** Called on every change the CMP reports; returns an unsubscribe. */
+	subscribe(onChange: (state: Partial<ConsentState>) => void): () => void;
+	/**
+	 * True when `subscribe` reports every change by itself. Otherwise the SDK re-reads the adapter
+	 * every 2s while the page is visible, so a withdrawal nothing announces is still honoured.
+	 */
+	readonly observesChanges?: boolean;
+}
+
+export declare const CONSENT_PURPOSES: readonly ConsentPurpose[];
+/** 'thg_hp_consent': the consent cookie's name unless the host configures another. */
+export declare const DEFAULT_CONSENT_COOKIE: string;
+
+export interface DidomiConsentOptions {
+	/** Didomi purpose ids per spec purpose. An id also matches `<id>-<suffix>`. */
+	purposes?: Partial<Record<ConsentPurpose, string[]>>;
+}
+
+export interface OneTrustConsentOptions {
+	/** OneTrust group id per spec purpose. Defaults: analytics C0002, personalisation C0003, marketing C0004. */
+	groups?: Partial<Record<ConsentPurpose, string>>;
+	/** Accept OneTrust's groups before the banner is closed. Only for notice-only / opt-out regions. */
+	impliedConsent?: boolean;
+}
+
+export interface CookieConsentOptions {
+	/** The cookie your banner writes. Required. */
+	name: string;
+	/** The cookie's category id per spec purpose. `analytics` is required. */
+	categories: Partial<Record<ConsentPurpose, string>> & { analytics: string };
+	/**
+	 * Accepted category ids from the URL-decoded cookie value, or null when it cannot be read.
+	 * Default: comma-separated ids; empty means unknown.
+	 */
+	parse?(raw: string): Set<string> | null;
+	/** A literal cookie value meaning "rejected everything". */
+	refusedValue?: string;
+	/** context.consent.source. Default 'native'. */
+	source?: string;
+	/** Window event the banner dispatches after writing the cookie. Default 'thg_hp_consent_change'. */
+	changeEvent?: string;
+}
+
+export declare function didomiConsent(
+	options?: DidomiConsentOptions,
+): ConsentAdapter;
+export declare function oneTrustConsent(
+	options?: OneTrustConsentOptions,
+): ConsentAdapter;
+export declare function cookieConsent(
+	options: CookieConsentOptions,
+): ConsentAdapter;
+/**
+ * Reads the consent cookie the SDK writes on a page that runs the CMP, for pages on the same
+ * registrable domain that don't (a separate checkout app, a subdomain). No answer in it = not answered.
+ * `name` must match the writer's `storageNames.consent`; both default to 'thg_hp_consent'.
+ */
+export declare function forwardedConsent(options?: {
+	name?: string;
+}): ConsentAdapter;
+export declare function staticConsent(
+	state: Partial<ConsentState>,
+): ConsentAdapter;
+
+export declare function normaliseConsentState(
+	raw: unknown,
+): ConsentState | null;
+export declare function sameConsentState(
+	a: ConsentState | null,
+	b: ConsentState | null,
+): boolean;
+/** The `thg_hp_consent` cookie value, e.g. `a=1&m=0&p=1`. */
+export declare function formatConsentCookie(
+	state: Partial<ConsentState> | null,
+): string;
+export declare function parseConsentCookie(
+	value: string | null | undefined,
+): ConsentState;
+/**
+ * The adapter reporting only the purposes the property asks for (its settings' `consent.purposes`);
+ * the rest read as unanswered. Analytics is always reported. bootstrap and cdpPlugins apply it.
+ */
+export declare function reportingPurposes(
+	adapter: ConsentAdapter,
+	purposes: Partial<Record<ConsentPurpose, boolean>> | null,
+): ConsentAdapter;
+/** 'hp-consent': the header that carries consent to the serving API. */
+export declare const CONSENT_HEADER: 'hp-consent';
+/** `{ 'hp-consent': formatConsentCookie(state) }`, for any request to the serving API. */
+export declare function servingHeaders(state: Partial<ConsentState> | null): {
+	'hp-consent': string;
+};

package/types/datalayer.d.ts

@@ -0,0 +1,76 @@
+import type { CdpProduct } from './events';
+
+export interface DataLayerEvent {
+	event: string;
+	properties?: Record<string, unknown>;
+}
+
+export interface DataLayerHelpers {
+	name: string;
+	entry: Record<string, unknown>;
+	ecommerce: Record<string, unknown>;
+	items: Record<string, unknown>[];
+	/** False when the push had no item list at all (not the same as an empty one). */
+	itemsListed: boolean;
+	products: CdpProduct[];
+	currency: string | null;
+	value: number | null;
+	promotions: Array<{
+		promotion_id: string;
+		name: string | null;
+		creative: string | null;
+		/** GA4 creative_slot, as Segment's `position` (spec 1.2). */
+		position: string | null;
+	}>;
+	toProducts(items: unknown[]): CdpProduct[];
+}
+
+export type DataLayerMapping = (
+	payload: Record<string, unknown>,
+	helpers: DataLayerHelpers,
+) => DataLayerEvent | DataLayerEvent[] | null | undefined;
+
+/** Anything with a Segment-style track: this package's client or an analytics-next instance. */
+export interface TrackingClient {
+	track(
+		event: string,
+		properties?: Record<string, unknown>,
+		options?: { context?: Record<string, unknown> },
+	): unknown;
+	signedOut?(options?: { context?: Record<string, unknown> }): unknown;
+}
+
+/** Resolves a GA4 item's parent product id. Default `item.item_group_id ?? item.item_id`. */
+export type ProductIdResolver = (item: Record<string, unknown>) => unknown;
+
+/** How one commerce platform uses the dataLayer. Spread into the options: `{ ...preset }`. */
+export interface DataLayerPreset {
+	/** The GA4 event name of a push. Default `entry.event`. */
+	eventName?(entry: Record<string, unknown>): string | null | undefined;
+	/** Rewrite a push into the GA4 shape before anything reads it; return null to skip it. */
+	transform?(entry: unknown): unknown;
+	productId?: ProductIdResolver;
+	/** Add or override mappings, keyed by GA4 event name. */
+	map?: Record<string, DataLayerMapping>;
+	/** GA4 event names to skip. purchase and refund are always skipped. */
+	ignore?: string[];
+	/** Checkout step numbers. Defaults: shipping 2, payment 3. */
+	steps?: { shipping?: number; payment?: number };
+}
+
+export interface ConnectDataLayerOptions extends DataLayerPreset {
+	/** Defaults to window.dataLayer, created when absent. */
+	dataLayer?: unknown[];
+	/** Identical pushes within this window are emitted once. Default 1000. */
+	dedupeMs?: number;
+	onError?(error: unknown, entry: unknown): void;
+}
+
+/** Returns disconnect(). */
+export declare function connectDataLayer(
+	analytics: TrackingClient,
+	options?: ConnectDataLayerOptions,
+): () => void;
+
+/** The first usable id among the candidates, as a string, or null. Blank strings are skipped. */
+export declare function firstId(...candidates: unknown[]): string | null;