@thg-agentic/hyper-personalisation-web 3.22.2 → 3.24.0

package/types/events.d.ts

@@ -1,7 +1,7 @@
 // Generated from spec/registry.json by scripts/generate-sdk-models.mjs.
 // DO NOT EDIT. Change the schema and regenerate — the schema is the contract,
 // and a hand-edit here is an SDK that disagrees with the ingest.
-// Spec version: 1.16
+// Spec version: 1.18
 
 /** context.source.environment. Environment the producer runs in. */
 export type CdpSourceEnvironment = 'production' | 'staging' | 'development';
@@ -76,12 +76,28 @@ export interface DecisionMade {
 	latency_ms?: number | null;
 }
 
-/** A visitor acted on a personalised surface: clicked it (for example opened a product from a rail) or dismissed it. */
+/** A triggered journey fired for one shopper: an entry event happened, the journey's delay passed, its exit event did not happen, and the shopper passed its gates (marketing consent, suppression, frequency cap, quiet hours). */
+export interface JourneyTriggered {
+	trigger_id: string;
+	journey: string;
+	entry_event: string;
+	entry_message_id: string;
+	entry_at: string;
+	delay_seconds: number;
+	holdout: boolean;
+	holdout_share?: number | null;
+	cart_id?: string | null;
+	currency?: string | null;
+	products?: CdpProduct[];
+}
+
+/** A visitor acted on a personalised surface: clicked it (for example opened a product from a rail), dismissed it, or submitted a step of an onsite form. */
 export interface SlotEngaged {
 	decision_id: string;
 	slot: string;
-	engagement: 'view' | 'click' | 'dismiss';
+	engagement: 'view' | 'click' | 'dismiss' | 'submit';
 	arm?: string | null;
+	step?: string | null;
 	position?: number | null;
 	products?: CdpProduct[] | null;
 }
@@ -432,13 +448,18 @@ export interface SignedUp {
 /** The shopper signed out. */
 export type SignedOut = Record<string, never>;
 
-/** The shopper opted in to marketing messages on the site or in the app, for example through a footer form, a modal, or a checkbox at checkout or in their account. */
+/** The shopper opted in to marketing messages on the site or in the app, for example through a footer form, an onsite sign-up form, or a checkbox at checkout or in their account. */
 export interface NewsletterSubscribed {
 	email_sha256: string;
 	requires_verification?: boolean | null;
 	placement?: string | null;
 	channel?: 'email' | 'sms' | 'post' | 'push' | null;
 	phone_sha256?: string | null;
+	slot?: string | null;
+	arm?: string | null;
+	decision_id?: string | null;
+	receipt_id?: string | null;
+	consent_text?: string | null;
 }
 
 /** A shopper submitted a review of a product. */
@@ -630,12 +651,47 @@ export interface ApplicationUpdated {
 	build: string;
 }
 
+/** The shopper answered a preference question, for example what they are shopping for or which categories they want to hear about. */
+export interface PreferencesStated {
+	question: string;
+	values: string[];
+	source: 'onsite' | 'account' | 'quiz';
+	slot?: string | null;
+	arm?: string | null;
+	decision_id?: string | null;
+	step?: string | null;
+}
+
+/** A shopper who signed up through an onsite form claimed its offer, for example the prize of a spin-to-win or a welcome discount. */
+export interface OfferClaimed {
+	slot: string;
+	prize: string;
+	email_sha256: string;
+	fallback: boolean;
+	arm?: string | null;
+	decision_id?: string | null;
+	pool?: string | null;
+	code_sha256?: string | null;
+}
+
+/** Hyper-Personalisation delivered a sign-up from an onsite form to one of the brand's systems of record, such as its account service or its email platform, or gave up trying. */
+export interface SignUpRelayed {
+	receipt_id: string;
+	destination: string;
+	kind: 'thg' | 'listrak' | 'klaviyo' | 'webhook';
+	outcome: 'delivered' | 'duplicate' | 'verify' | 'failed';
+	attempts: number;
+	email_sha256?: string | null;
+	phone_sha256?: string | null;
+}
+
 /** The spec version these models implement. SDKs stamp it on context.spec.version. */
-export const SPEC_VERSION = '1.16';
+export const SPEC_VERSION = '1.18';
 
 /** Every event name the registry accepts. Anything else is rejected at the ingest. */
 export type CdpEventName =
 	| 'Decision Made'
+	| 'Journey Triggered'
 	| 'Slot Engaged'
 	| 'Recommendations Viewed'
 	| 'Promotion Viewed'
@@ -690,11 +746,15 @@ export type CdpEventName =
 	| 'Application Opened'
 	| 'Application Backgrounded'
 	| 'Application Updated'
+	| 'Preferences Stated'
+	| 'Offer Claimed'
+	| 'Sign-up Relayed'
 ;
 
 /** Event name -> its properties, so a generic emitter stays type-safe. */
 export interface CdpEventProperties {
 	'Decision Made': DecisionMade;
+	'Journey Triggered': JourneyTriggered;
 	'Slot Engaged': SlotEngaged;
 	'Recommendations Viewed': RecommendationsViewed;
 	'Promotion Viewed': PromotionViewed;
@@ -749,6 +809,9 @@ export interface CdpEventProperties {
 	'Application Opened': ApplicationOpened;
 	'Application Backgrounded': ApplicationBackgrounded;
 	'Application Updated': ApplicationUpdated;
+	'Preferences Stated': PreferencesStated;
+	'Offer Claimed': OfferClaimed;
+	'Sign-up Relayed': SignUpRelayed;
 }
 
 /** Which producers the registry permits for each event. Emitting from another is refused. */

package/types/hp.d.ts

@@ -4,6 +4,7 @@ import type {
 	CallOptions,
 	RecommendationContext,
 } from './index';
+import type { OnsiteFacade } from './onsite';
 
 type Methods = {
 	[K in keyof AnalyticsClient as AnalyticsClient[K] extends (
@@ -40,7 +41,7 @@ interface HpTrack {
  * into the caller.
  */
 export declare const hp: {
-	[K in Exclude<keyof Methods, 'track' | 'recommendationContext'>]: (
+	[K in Exclude<keyof Methods, 'track' | 'recommendationContext' | 'onsite'>]: (
 		...args: Parameters<Methods[K]>
 	) => void;
 } & {
@@ -61,4 +62,6 @@ export declare const hp: {
 	 * client has started, and without personalisation consent. Since 3.11.
 	 */
 	recommendationContext(): RecommendationContext;
+	/** Onsite forms: `hp.onsite.open(slot)` opens a form by hand; `debug()` says why each did or did not show. */
+	onsite: OnsiteFacade;
 };

package/types/index.d.ts

@@ -22,6 +22,7 @@ import type {
 	NewsletterUnsubscribed,
 	PaymentInfoEntered,
 	PersonalisationExposed,
+	PreferencesStated,
 	ProductAdded,
 	ProductAddedToWishlist,
 	ProductClicked,
@@ -335,6 +336,11 @@ export interface AnalyticsClient {
 	newsletterSubscribed: Emit<NewsletterSubscribed>;
 	/** An on-site opt-out. The ESP reports its own as Email Unsubscribed. */
 	newsletterUnsubscribed: Emit<NewsletterUnsubscribed>;
+	/**
+	 * Answers to an approved preference question (spec 1.18). Answers sent with an onsite sign-up are
+	 * the gateway's to report, so never send those.
+	 */
+	preferencesStated: Emit<PreferencesStated>;
 	/** An alert request for one product: back in stock, a price drop or a launch. */
 	backInStockSubscribed: Emit<BackInStockSubscribed>;
 	productReviewed: Emit<ProductReviewed>;
@@ -436,6 +442,10 @@ export interface ServingBody {
 		 * computes it from the settings. `default` is no decision and is not put in force. Since 3.16.
 		 */
 		variant?: 'bandit' | 'default';
+		/** The A/B test the arm was assigned in, when the slot runs one. Since 3.23. */
+		experiment?: string;
+		/** The test's split token, sent back with the pin. Since 3.23. */
+		split?: string;
 	}>;
 	recommendation_request_id?: string;
 }

package/types/onsite-preview.d.ts

@@ -0,0 +1,58 @@
+/** A question the form's settings publish, as the preview renders it. */
+export interface PreviewQuestion {
+	key: string;
+	type?: 'one' | 'many' | 'date' | 'number';
+	label?: string;
+	/** A choice's options. */
+	options?: Array<{ value: string; label?: string }>;
+	/** A date's or a number's format, as the settings publish it. */
+	format?: {
+		kind?: 'birthday' | 'date';
+		year?: 'none' | 'optional' | 'required';
+		min?: number;
+		max?: number;
+		decimals?: boolean;
+		unit?: string;
+	};
+}
+
+export interface PreviewOptions {
+	/** The step to show; the first when left out or unknown. */
+	step?: string;
+	/** The small-screen layout (`mobile`) or the large one, whatever the host's own width. */
+	device?: 'desktop' | 'mobile';
+	/** The form's consent text; a sample sentence when left out. */
+	consentText?: string;
+	/** The consent text a step taking a phone number shows; a sample sentence when left out. */
+	smsConsentText?: string;
+	/**
+	 * The form's language (the settings' `locale`, e.g. `en-GB`): a birthday's field order and month
+	 * names, and a phone field's first country. The page's `<html lang>` when left out.
+	 */
+	locale?: string;
+	questions?: PreviewQuestion[];
+	prizes?: Array<{ key: string; label: string }>;
+	/** The basket a progress block is drawn against; 32 when left out. */
+	basketValue?: number;
+}
+
+export interface OnsitePreview {
+	/** Re-render, on the step shown unless `options.step` names another. */
+	update(creative: unknown, options?: PreviewOptions): void;
+	destroy(): void;
+	/** The step on screen, or null when the creative could not be read. */
+	step(): string | null;
+}
+
+/**
+ * Render a creative with the shoppers' renderer inside `host`, for the console: no request, no
+ * event, no counter; its buttons only move between steps.
+ */
+export declare function mountPreview(
+	host: HTMLElement,
+	creative: unknown,
+	options?: PreviewOptions,
+): OnsitePreview;
+
+/** The countries a phone field's country code picker offers, by ISO code, with their calling codes. */
+export declare const CALLING_CODES: Readonly<Record<string, string>>;

package/types/onsite-wheel.d.ts

@@ -0,0 +1,11 @@
+export interface OnsiteWheel {
+	/** Turn to the prize at `index`, the one the server drew. Instant under reduced motion. */
+	spinTo(index: number): Promise<void>;
+	remove(): void;
+}
+
+/** Draw the prize wheel into `container`. Null for fewer than two prizes. */
+export declare function mountWheel(
+	container: Element,
+	prizes: Array<{ key: string; label: string }>,
+): OnsiteWheel | null;

package/types/onsite.d.ts

@@ -0,0 +1,203 @@
+import type { AnalyticsClient } from './index';
+
+/** RichText: plain text, bold, italic and https links. No markup: anything else is dropped. */
+export type RichText =
+	| string
+	| Array<
+			string | { b: RichText } | { i: RichText } | { a: RichText; href: string }
+	  >;
+
+export type OnsiteFormat =
+	| 'popup'
+	| 'sheet'
+	| 'bar'
+	| 'teaser'
+	| 'inline'
+	| 'fullscreen';
+
+export type OnsiteTriggerType =
+	| 'entry'
+	| 'exit'
+	| 'scroll'
+	| 'time'
+	| 'idle'
+	| 'inline'
+	| 'manual';
+
+/** One live form, as the settings' `hp.onsite.forms[]` index carries it (ADR 0064). */
+export interface OnsiteForm {
+	slot: string;
+	format: OnsiteFormat;
+	/** One overlay per page view: of the forms that fire together, the highest shows. */
+	priority?: number;
+	trigger: {
+		type: OnsiteTriggerType;
+		/** entry: the delay; exit: how long until exit intent arms (5000). */
+		delay_ms?: number;
+		/** scroll: the share of the page scrolled, 0–1 (0.5). */
+		depth?: number;
+		/** time and idle: seconds (30). */
+		seconds?: number;
+		/** inline: the element the form renders into. */
+		selector?: string;
+	};
+	/** Path globs, `*` matching anything. No `include` is every page; an exclusion wins. */
+	/** Other names `show()` opens this form by (`footer_signup` for the site's sign-up button). */
+	aliases?: string[];
+	pages?: { include?: string[]; exclude?: string[] };
+	/** `mobile` is a coarse pointer or a viewport under 768px. Absent: both. */
+	devices?: Array<'desktop' | 'mobile'>;
+	/** Shown only with personalisation consent, and only to members as the server decides. */
+	audiences?: string[];
+	exclude_subscribed?: boolean;
+	caps?: { per_session?: number; lifetime?: number; after_close_days?: number };
+	window?: { starts_at?: string; ends_at?: string };
+	/**
+	 * The form's language, BCP 47 (`en-IE`): its phone field starts on this region's country code,
+	 * and a birthday's day and month follow its order and month names. Absent: the page's `lang`.
+	 */
+	locale?: string;
+	/** The words an email step asks agreement to; absent on a form that collects only `sms`. */
+	consent_text?: { id: string; version: number; text: string };
+	/** The words an SMS step asks agreement to; present when `channels` has `sms`. */
+	sms_consent_text?: { id: string; version: number; text: string };
+	/**
+	 * A choice (`one`, `many`) has `options`; a `date` or `number` question has `format`. A date is
+	 * answered as `YYYY-MM-DD`, or `--MM-DD` for a birthday without its year.
+	 */
+	questions?: Array<{
+		key: string;
+		type: 'one' | 'many' | 'date' | 'number';
+		label: string;
+		options?: Array<{ value: string; label: string }>;
+		format?: OnsiteQuestionFormat;
+	}>;
+	/** The wheel's labels only: odds and codes are the server's. */
+	prizes?: Array<{ key: string; label: string }>;
+	/** A destination is handed the shopper's code, so the brand's email can carry it. */
+	code_relayed?: true;
+	channels?: Array<'email' | 'sms'>;
+}
+
+/**
+ * A date question's (`kind`: a `birthday`, its `year` not asked, optional or required, or any
+ * full `date`) or a number question's (`min`, `max`, `decimals`, `unit`).
+ */
+export interface OnsiteQuestionFormat {
+	kind?: 'birthday' | 'date';
+	year?: 'none' | 'optional' | 'required';
+	min?: number;
+	max?: number;
+	decimals?: boolean;
+	unit?: string;
+}
+
+/** `hp.onsite` in the SDK settings. */
+export interface OnsiteSettings {
+	forms: OnsiteForm[];
+	/**
+	 * Minutes a session waits after a popup, sheet or full-screen form (not a bar or teaser) before another may
+	 * show. Absent: no limit; 1440: once per session.
+	 */
+	overlay_gap_minutes?: number;
+	capture?: { challenge?: string } | null;
+}
+
+export interface OnsiteOptions {
+	/** Development and tests: these forms instead of the settings'. */
+	settings?: OnsiteSettings;
+	/** The public API for decisions and offer claims. Default: the host the SDK was pointed at. */
+	servingHost?: string;
+	/** The ingest gateway for capture. Default: where the SDK sends events. */
+	gatewayHost?: string;
+	/** The visitor's session audiences, when the page evaluates them: a form outside them is skipped. */
+	audiences?(): string[] | null | undefined;
+	/** Whether the page knows this visitor is already subscribed (a signed-in subscriber). */
+	subscribed?(): boolean;
+	/** Log why each form did or did not show. Also on with `?hp_debug=onsite` or the SDK's debug. */
+	debug?: boolean;
+	fetch?: typeof fetch;
+}
+
+/** One form's state on this page, and why. */
+export interface OnsiteTrace {
+	slot: string;
+	format?: OnsiteFormat;
+	trigger?: OnsiteTriggerType;
+	priority?: number;
+	state:
+		| 'armed'
+		| 'waiting for hp.onsite.open'
+		| 'asking for a decision'
+		| 'shown'
+		| 'closed'
+		| 'held out'
+		| 'no decision'
+		| 'not eligible'
+		| 'not shown'
+		| 'invalid';
+	reasons: string[];
+}
+
+export interface OnsiteController {
+	/** Show the form on `slot` now, whatever its trigger, if its rules allow it. */
+	open(slot: string): Promise<boolean>;
+	/** Each form's state on this page, and why. */
+	debug(): OnsiteTrace[];
+	/** Stop watching every trigger. A form on screen stays until it is closed. */
+	stop(): void;
+	/** Take every form off the screen, quietly (`hp.onsite.suppress` calls it). */
+	suppress(): void;
+}
+
+/** What every `hp.onsite.on` listener is told. */
+export interface OnsiteEventDetail {
+	slot: string;
+	arm: string | null;
+	format: string;
+}
+
+/** A code a form handed out: the claimed prize, or a reminder's unused code. */
+export interface OnsiteCoupon {
+	code: string | null;
+	prize?: string;
+}
+
+export interface OnsiteEvents {
+	shown: OnsiteEventDetail;
+	/** After the sign-up; for a form that spins, once the prize is claimed. */
+	submitted: OnsiteEventDetail & { coupon: OnsiteCoupon | null };
+	/** A reminder's apply button: put the code on the basket. */
+	apply: OnsiteEventDetail & { coupon: OnsiteCoupon | null };
+	closed: OnsiteEventDetail & { reason: string };
+	/** A held-out visitor's trigger fired (not a form the site opened, whose `open` resolves false): show what the site shows without HP. */
+	held: OnsiteEventDetail;
+}
+
+/** `hp.onsite`, callable before the runtime has loaded. */
+export interface OnsiteFacade {
+	open(slot: string): Promise<boolean>;
+	/** The same as `open`. */
+	show(slot: string): Promise<boolean>;
+	/** Listen to the forms; returns a function that stops listening. */
+	on<K extends keyof OnsiteEvents>(
+		name: K,
+		listener: (detail: OnsiteEvents[K]) => void,
+	): () => void;
+	/** Keep the screen clear for `reason` (default `page`): a form showing goes, and none shows until lifted. */
+	suppress(reason?: string): void;
+	/** Lift `reason`, or every reason. */
+	unsuppress(reason?: string): void;
+	/** Each form's state once the page knows whether onsite forms run on it; `[]` when none will. */
+	ready(): Promise<OnsiteTrace[]>;
+	debug(): OnsiteTrace[];
+}
+
+/**
+ * Start onsite forms for the client, once per page. Null without a browser, or for a client this
+ * SDK did not make.
+ */
+export declare function startOnsite(
+	client: AnalyticsClient,
+	options?: OnsiteOptions,
+): OnsiteController | null;