@thg-agentic/hyper-personalisation-web 3.18.0 → 3.22.0

package/types/events.d.ts

@@ -1,7 +1,39 @@
 // 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.10
+// Spec version: 1.15
+
+/** context.source.environment. Environment the producer runs in. */
+export type CdpSourceEnvironment = 'production' | 'staging' | 'development';
+export declare const CDP_SOURCE_ENVIRONMENT_VALUES: readonly CdpSourceEnvironment[];
+
+/** context.identity_trust. Whether `anonymousId` on this event identifies a single real visitor. */
+export type CdpIdentityTrust = 'device' | 'shared_render' | 'none';
+export declare const CDP_IDENTITY_TRUST_VALUES: readonly CdpIdentityTrust[];
+
+/** context.page.type. The page's type, from a closed taxonomy every consumer groups by. */
+export type CdpPageType = 'home' | 'list' | 'product' | 'search' | 'basket' | 'checkout' | 'order_confirmation' | 'login' | 'register' | 'account' | 'info' | 'blog' | 'other';
+export declare const CDP_PAGE_TYPE_VALUES: readonly CdpPageType[];
+
+/** context.device.type. The kind of device, derived by the ingest from the user agent. */
+export type CdpDeviceType = 'desktop' | 'mobile' | 'tablet' | 'bot' | 'app';
+export declare const CDP_DEVICE_TYPE_VALUES: readonly CdpDeviceType[];
+
+/** context.device.network. How the device was connected when the event happened, as a native app reports it. */
+export type CdpDeviceNetwork = 'wifi' | 'cellular' | 'wired' | 'offline' | 'other';
+export declare const CDP_DEVICE_NETWORK_VALUES: readonly CdpDeviceNetwork[];
+
+/** context.consent.basis. Who decided whether this event may be collected. */
+export type CdpConsentBasis = 'visitor' | 'host';
+export declare const CDP_CONSENT_BASIS_VALUES: readonly CdpConsentBasis[];
+
+/** context.decisions[].kind. The kind of decision, as `Decision Made.kind` (recommendation, banner, offer, layout, price, …), copied so a reward can be rolled up by kind without joining the decision log. */
+export type CdpDecisionKind = 'recommendation' | 'search_rank' | 'banner' | 'offer' | 'layout' | 'copy' | 'price' | 'other';
+export declare const CDP_DECISION_KIND_VALUES: readonly CdpDecisionKind[];
+
+/** context.consent. The purposes a visitor answers for: context.consent and Consent Updated `state`. */
+export type CdpConsentPurpose = 'analytics' | 'marketing' | 'personalisation' | 'ad_user_data' | 'ad_personalization';
+export declare const CDP_CONSENT_PURPOSE_VALUES: readonly CdpConsentPurpose[];
 
 /** The product shape shared by every commerce event. */
 export interface CdpProduct {
@@ -26,7 +58,7 @@ export interface CdpProduct {
 	subscription?: Record<string, unknown> | null;
 }
 
-/** SERVER-SIDE ONLY. */
+/** A personalisation decision was taken: the decision service chose `arm` for `slot` from `candidates`, with probability `propensity`, under policy `policy_id` at `policy_version`, given `context_features`. */
 export interface DecisionMade {
 	decision_id: string;
 	slot: string;
@@ -44,7 +76,7 @@ export interface DecisionMade {
 	latency_ms?: number | null;
 }
 
-/** A visitor interacted with a personalised surface — clicked the hero, opened a recommended product from a rail, dismissed an offer. */
+/** A visitor interacted with a personalised surface: viewed it, clicked it (for example opened a product from a rail), or dismissed it. */
 export interface SlotEngaged {
 	decision_id: string;
 	slot: string;
@@ -74,7 +106,7 @@ export interface RecommendationsViewed {
 	viewable?: Record<string, unknown>[] | null;
 }
 
-/** A merchandising slot — a hero banner, a strip banner, an editorial block — was actually on screen. */
+/** A promotion was viewable on screen. */
 export interface PromotionViewed {
 	promotion_id: string;
 	name?: string | null;
@@ -83,7 +115,7 @@ export interface PromotionViewed {
 	creative_slot?: string | null;
 }
 
-/** A visitor clicked a merchandising slot. */
+/** A shopper clicked a promotion. */
 export interface PromotionClicked {
 	promotion_id: string;
 	name?: string | null;
@@ -93,14 +125,14 @@ export interface PromotionClicked {
 	href?: string | null;
 }
 
-/** A product detail page was viewed. */
+/** A shopper saw one product's details, on its product page or in a quick-view overlay. */
 export interface ProductViewed {
 	products: CdpProduct[];
 	currency?: string | null;
 	value?: number | null;
 }
 
-/** A listing/category page rendered a set of products. */
+/** A shopper viewed a list of products: a category or listing page, a collection, or a page of search results. */
 export interface ProductListViewed {
 	products: CdpProduct[];
 	list_id?: string | null;
@@ -110,7 +142,7 @@ export interface ProductListViewed {
 	sorts?: Record<string, unknown>[] | null;
 }
 
-/** A product tile in a list was clicked. */
+/** A shopper clicked a product in a list, search results, search suggestions or a recommendation rail. */
 export interface ProductClicked {
 	products: CdpProduct[];
 	list_id?: string | null;
@@ -119,7 +151,7 @@ export interface ProductClicked {
 	search_request_id?: string | null;
 }
 
-/** Facet or sort selection changed on a listing. */
+/** A shopper changed the facets or sort order of a list and a new result set loaded. */
 export interface ProductListFiltered {
 	list_id?: string | null;
 	category?: string | null;
@@ -129,7 +161,7 @@ export interface ProductListFiltered {
 	products?: CdpProduct[] | null;
 }
 
-/** A search was executed and its results were shown. */
+/** A search was submitted and its results page was shown. */
 export interface ProductsSearched {
 	query: string;
 	is_suggested?: boolean | null;
@@ -138,6 +170,13 @@ export interface ProductsSearched {
 	search_request_id?: string | null;
 }
 
+/** A search box suggested products for a partly typed query, and they were seen: instant search, typeahead or autocomplete. */
+export interface SearchSuggestionsViewed {
+	query: string;
+	products: CdpProduct[];
+	search_request_id?: string | null;
+}
+
 /** A product was added to the basket. */
 export interface ProductAdded {
 	products: CdpProduct[];
@@ -162,7 +201,7 @@ export interface ProductRemoved {
 	initiator?: 'shopper' | 'system' | null;
 }
 
-/** The basket page was viewed. */
+/** The shopper viewed the basket page. */
 export interface CartViewed {
 	cart_id?: string | null;
 	value?: number | null;
@@ -174,7 +213,7 @@ export interface CartViewed {
 	coupon?: string | null;
 }
 
-/** Checkout was entered. */
+/** The shopper entered checkout. */
 export interface CheckoutStarted {
 	products: CdpProduct[];
 	cart_id?: string | null;
@@ -195,7 +234,7 @@ export interface CheckoutStarted {
 	discounts?: Record<string, unknown>[] | null;
 }
 
-/** A checkout step was shown. */
+/** A checkout step was shown to the shopper. */
 export interface CheckoutStepViewed {
 	step: number;
 	step_name: string | null;
@@ -205,7 +244,7 @@ export interface CheckoutStepViewed {
 	payment_method?: string | null;
 }
 
-/** A checkout step was completed and the customer moved on. */
+/** The shopper completed a checkout step and moved on. */
 export interface CheckoutStepCompleted {
 	step: number;
 	step_name: string | null;
@@ -215,7 +254,7 @@ export interface CheckoutStepCompleted {
 	payment_method?: string | null;
 }
 
-/** Payment details were supplied. */
+/** The shopper supplied payment details in checkout. */
 export interface PaymentInfoEntered {
 	step: number;
 	step_name: string | null;
@@ -249,7 +288,7 @@ export interface OrderCompleted {
 	is_guest?: boolean | null;
 }
 
-/** An order changed after it was placed — a line removed, an address corrected, a substitution made. */
+/** An order changed after it was placed, e.g. a line removed, an address corrected or a substitution made. */
 export interface OrderUpdated {
 	order_id: string;
 	currency: string;
@@ -261,13 +300,14 @@ export interface OrderUpdated {
 	taxes_included?: boolean | null;
 	discount?: number | null;
 	coupon?: string | null;
+	payment_method?: string | null;
 	products?: CdpProduct[] | null;
 	reason?: 'line_added' | 'line_removed' | 'quantity_changed' | 'address_changed' | 'delivery_changed' | 'payment_changed' | 'price_adjusted' | 'partial_cancellation' | 'other' | 'status_changed' | null;
 	status?: 'processing' | 'despatched' | 'partially_despatched' | 'delivered' | 'collected' | 'held' | 'payment_problem' | null;
 	reason_detail?: string | null;
 }
 
-/** Money went back to the customer, in whole or in part. */
+/** Money went back to the customer for an order, in whole or in part. */
 export interface OrderRefunded {
 	order_id: string;
 	total: number;
@@ -299,7 +339,7 @@ export interface OrderCancelled {
 	reason_detail?: string | null;
 }
 
-/** A shopper submitted a discount code on a basket or an order, BEFORE anything decided whether it applies. */
+/** The shopper submitted a discount code on a basket or order, before anything decided whether it applies. */
 export interface CouponEntered {
 	order_id?: string | null;
 	cart_id?: string | null;
@@ -307,7 +347,7 @@ export interface CouponEntered {
 	coupon_name?: string;
 }
 
-/** A discount code was accepted. */
+/** A discount code was accepted on a basket or order. */
 export interface CouponApplied {
 	coupon_name: string;
 	cart_id?: string | null;
@@ -318,7 +358,7 @@ export interface CouponApplied {
 	source?: 'manual' | 'auto_applied' | 'url' | null;
 }
 
-/** A discount code was rejected. */
+/** A discount code was rejected on a basket or order. */
 export interface CouponDenied {
 	coupon_name: string;
 	cart_id?: string | null;
@@ -328,7 +368,7 @@ export interface CouponDenied {
 	source?: 'manual' | 'auto_applied' | 'url' | null;
 }
 
-/** A discount code that was applied was taken off a basket or an order. */
+/** A discount code that had been applied was taken off a basket or order. */
 export interface CouponRemoved {
 	order_id?: string | null;
 	cart_id?: string | null;
@@ -338,7 +378,7 @@ export interface CouponRemoved {
 	currency?: string | null;
 }
 
-/** Also covers the logged-out attempt, which is a strong signup-intent signal worth keeping rather than discarding. */
+/** A shopper added a product to a wishlist. */
 export interface ProductAddedToWishlist {
 	products: CdpProduct[];
 	wishlist_id?: string | null;
@@ -346,14 +386,14 @@ export interface ProductAddedToWishlist {
 	was_blocked_by_auth?: boolean | null;
 }
 
-/** Product Removed from Wishlist */
+/** A shopper removed a product from a wishlist. */
 export interface ProductRemovedFromWishlist {
 	products: CdpProduct[];
 	wishlist_id?: string | null;
 	wishlist_name?: string | null;
 }
 
-/** A shopper moved a product from a wishlist into their basket. */
+/** A shopper moved a product from a wishlist into the basket. */
 export interface WishlistProductAddedToCart {
 	products: CdpProduct[];
 	wishlist_id?: string | null;
@@ -361,7 +401,7 @@ export interface WishlistProductAddedToCart {
 	cart_id?: string | null;
 }
 
-/** A shopper shared a product with one or more people — mailed it, copied its link, sent it to an app. */
+/** A shopper shared a product with one or more people: by email, a copied link, or another app. */
 export interface ProductShared {
 	products: CdpProduct[];
 	share_via?: string | null;
@@ -369,7 +409,7 @@ export interface ProductShared {
 	recipient?: string | null;
 }
 
-/** A shopper shared their basket with one or more people — a gift list, a team order, a basket sent to whoever holds the card. */
+/** A shopper shared their basket with one or more people, e.g. a gift list or a basket sent to someone else to pay. */
 export interface CartShared {
 	products: CdpProduct[];
 	share_via?: string | null;
@@ -392,7 +432,7 @@ export interface SignedUp {
 /** The shopper signed out. */
 export type SignedOut = Record<string, never>;
 
-/** A marketing opt-in was captured on the site or in the app — a footer form, a modal, a checkbox at checkout or in the account. */
+/** 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. */
 export interface NewsletterSubscribed {
 	email_sha256: string;
 	requires_verification?: boolean | null;
@@ -401,7 +441,7 @@ export interface NewsletterSubscribed {
 	phone_sha256?: string | null;
 }
 
-/** A review was submitted. */
+/** A shopper submitted a review of a product. */
 export interface ProductReviewed {
 	products: CdpProduct[];
 	review_id?: string | null;
@@ -410,20 +450,20 @@ export interface ProductReviewed {
 	has_body?: boolean | null;
 }
 
-/** The visitor changed their consent state. */
+/** The visitor changed their consent: the record of what they allowed and when. */
 export interface ConsentUpdated {
 	state: Record<string, unknown> | null;
 	action?: 'accept_all' | 'reject_all' | 'custom' | 'withdrawn' | null;
 }
 
-/** An explicit assertion that two identifiers belong to the same person. */
+/** An explicit assertion that several identifiers belong to the same person, for links an `identify` cannot imply: a guest checkout, an email click, a newsletter signup, a cross-device link. */
 export interface IdentityLinked {
 	trigger: 'guest_checkout' | 'signed_up' | 'signed_in' | 'account_update' | 'email_link_clicked' | 'newsletter_subscribed' | 'account_creation' | 'user_login' | 'email_click' | 'newsletter_signup';
 	identifiers: Record<string, unknown>[];
 	confidence: number;
 }
 
-/** An ESP accepted and delivered a message. */
+/** The ESP delivered a message to the recipient's mailbox provider. */
 export interface EmailDelivered {
 	email_sha256: string;
 	campaign_id?: string | null;
@@ -432,7 +472,7 @@ export interface EmailDelivered {
 	email_id?: string | null;
 }
 
-/** A tracking pixel fired. */
+/** The recipient opened a message, as detected by the ESP's tracking pixel. */
 export interface EmailOpened {
 	email_sha256: string;
 	campaign_id?: string | null;
@@ -441,7 +481,7 @@ export interface EmailOpened {
 	email_id?: string | null;
 }
 
-/** A link in a message was followed. */
+/** The recipient clicked a link in a message. */
 export interface EmailLinkClicked {
 	email_sha256: string;
 	campaign_id?: string | null;
@@ -453,7 +493,7 @@ export interface EmailLinkClicked {
 	link_id?: string | null;
 }
 
-/** The recipient opted out. */
+/** The recipient opted out of email from a message, for example through the ESP's unsubscribe link or a List-Unsubscribe header. */
 export interface EmailUnsubscribed {
 	email_sha256: string;
 	campaign_id?: string | null;
@@ -476,7 +516,7 @@ export interface PersonalisationExposed {
 	recommendation_request_id?: string | null;
 }
 
-/** The basket AS IT NOW STANDS, sent after any change the platform has confirmed — a line added, removed or re-quantified, a code applied or removed, a basket merged at sign-in, a line the system dropped or repriced, a saved basket restored. */
+/** The basket as it now stands, sent after any change the platform has confirmed: a line added, removed or re-quantified, a code applied or removed, a basket merged at sign-in, a line the system removed or repriced, a saved basket restored. */
 export interface CartUpdated {
 	products: CdpProduct[];
 	cart_id?: string | null;
@@ -492,7 +532,7 @@ export interface CartUpdated {
 	merged_from_cart_id?: string | null;
 }
 
-/** The shopper picked a variant — a size, a colour, a flavour — on a product page or a quick view, and the page now shows that variant. */
+/** The shopper picked a variant (a size, a colour, a flavour) on a product page or a quick view, and the page now shows it. */
 export interface ProductVariantSelected {
 	products: CdpProduct[];
 	changed_attributes?: Record<string, unknown>[] | null;
@@ -511,7 +551,7 @@ export interface BackInStockSubscribed {
 	currency?: string | null;
 }
 
-/** The shopper opted out of marketing ON THE SITE OR IN THE APP — a preference centre, an account settings toggle, an unsubscribe page the storefront hosts. */
+/** The shopper opted out of marketing messages on the site or in the app, for example in a preference centre, an account setting or an unsubscribe page the storefront hosts. */
 export interface NewsletterUnsubscribed {
 	channel?: 'email' | 'sms' | 'post' | 'push' | null;
 	mailing_list_id?: string | null;
@@ -522,7 +562,7 @@ export interface NewsletterUnsubscribed {
 	reason_detail?: string | null;
 }
 
-/** A checkout attempt was stopped by an error the shopper saw: a payment declined, a 3-D Secure challenge failed, an address that would not validate, an item that went out of stock or changed price under them, a session that expired. */
+/** A checkout attempt was stopped by an error the shopper saw: a payment declined, a 3-D Secure challenge failed, an address that would not validate, an item that went out of stock or changed price, or a session that expired. */
 export interface CheckoutFailed {
 	stage: 'address' | 'shipping' | 'payment' | 'review' | 'place_order';
 	reason_kind: 'payment_declined' | 'payment_error' | 'three_ds_failed' | 'validation' | 'stock' | 'price_changed' | 'session_expired' | 'other';
@@ -536,7 +576,7 @@ export interface CheckoutFailed {
 	taxes_included?: boolean | null;
 }
 
-/** A return moved through its lifecycle: the customer asked to return goods (`requested`), the warehouse received them (`received`), or the merchant refused the return (`rejected`). */
+/** A return moved through its lifecycle: the customer asked to return goods (`requested`), the merchant received them (`received`), or the merchant refused the return (`rejected`). */
 export interface OrderReturned {
 	order_id: string;
 	return_id: string;
@@ -547,7 +587,7 @@ export interface OrderReturned {
 	refund_expected?: boolean | null;
 }
 
-/** An ESP's message could not be delivered to the address. */
+/** The ESP could not deliver a message to the address. */
 export interface EmailBounced {
 	email_sha256: string;
 	bounce_type: 'hard' | 'soft';
@@ -557,7 +597,7 @@ export interface EmailBounced {
 	email_id?: string | null;
 }
 
-/** The recipient reported a message as spam — a feedback-loop complaint the ESP received from the mailbox provider. */
+/** The recipient reported a message as spam, as received by the ESP through the mailbox provider's feedback loop. */
 export interface EmailMarkedAsSpam {
 	email_sha256: string;
 	campaign_id?: string | null;
@@ -591,7 +631,7 @@ export interface ApplicationUpdated {
 }
 
 /** The spec version these models implement. SDKs stamp it on context.spec.version. */
-export const SPEC_VERSION = '1.10';
+export const SPEC_VERSION = '1.15';
 
 /** Every event name the registry accepts. Anything else is rejected at the ingest. */
 export type CdpEventName =
@@ -605,6 +645,7 @@ export type CdpEventName =
 	| 'Product Clicked'
 	| 'Product List Filtered'
 	| 'Products Searched'
+	| 'Search Suggestions Viewed'
 	| 'Product Added'
 	| 'Product Removed'
 	| 'Cart Viewed'
@@ -663,6 +704,7 @@ export interface CdpEventProperties {
 	'Product Clicked': ProductClicked;
 	'Product List Filtered': ProductListFiltered;
 	'Products Searched': ProductsSearched;
+	'Search Suggestions Viewed': SearchSuggestionsViewed;
 	'Product Added': ProductAdded;
 	'Product Removed': ProductRemoved;
 	'Cart Viewed': CartViewed;

package/types/index.d.ts

@@ -6,6 +6,7 @@ import type {
 	CartViewed,
 	CdpEventName,
 	CdpEventProperties,
+	CdpPageType,
 	CdpProduct,
 	CheckoutFailed,
 	CheckoutStarted,
@@ -36,6 +37,7 @@ import type {
 	PromotionClicked,
 	PromotionViewed,
 	RecommendationsViewed,
+	SearchSuggestionsViewed,
 	SignedIn,
 	SignedUp,
 	SlotEngaged,
@@ -45,20 +47,8 @@ import type {
 export type { ConsentAdapter, ConsentBasis, ConsentState } from './consent';
 export type * from './events';
 
-export type PageType =
-	| 'home'
-	| 'list'
-	| 'product'
-	| 'search'
-	| 'basket'
-	| 'checkout'
-	| 'order_confirmation'
-	| 'login'
-	| 'register'
-	| 'account'
-	| 'info'
-	| 'blog'
-	| 'other';
+/** context.page.type: the spec's page taxonomy, generated. */
+export type PageType = CdpPageType;
 
 export interface PageProperties {
 	/** Stored as context.page.type and inherited by later events on the page. */
@@ -116,7 +106,6 @@ export interface AnalyticsContextSources {
 	 * Given, it is the only source, even when it returns nothing.
 	 */
 	getSessionId?(): string | null | undefined;
-	getRenderId?(): string | null | undefined;
 	getExperiments?(): Record<string, unknown>[] | null | undefined;
 	getAudiences?(): Record<string, unknown>[] | null | undefined;
 	getDecisions?(): Record<string, unknown>[] | null | undefined;
@@ -252,9 +241,13 @@ export interface AnalyticsClient {
 		properties?: Record<string, unknown>,
 		options?: CallOptions,
 	): CdpEvent | null;
-	page(properties?: PageProperties, options?: CallOptions): CdpEvent;
-	identify(traits?: IdentifyTraits, options?: CallOptions): CdpEvent;
-	/** Clear identity and the page chain. */
+	/** Null when the event is not sent: outside the sample, dropped by `beforeSend`, or failed. */
+	page(properties?: PageProperties, options?: CallOptions): CdpEvent | null;
+	identify(traits?: IdentifyTraits, options?: CallOptions): CdpEvent | null;
+	/**
+	 * Sign-out on a shared device: forget the user, the page chain, the SDK's session, the decisions
+	 * in force and the recommendation context. The device id stays.
+	 */
 	reset(): void;
 
 	productViewed: Emit<ProductViewed>;
@@ -293,7 +286,13 @@ export interface AnalyticsClient {
 	personalisationGroup(): PersonalisationGroup;
 	productClicked: Emit<ProductClicked>;
 	productListFiltered: Emit<ProductListFiltered>;
+	/** A submitted search and the results page it produced. */
 	productsSearched: Emit<ProductsSearched>;
+	/**
+	 * The search box's suggested products for a partly typed query, once seen. Never productsSearched,
+	 * which is a submitted search's results page.
+	 */
+	searchSuggestionsViewed: Emit<SearchSuggestionsViewed>;
 	productAdded: Emit<ProductAdded>;
 	productRemoved: Emit<ProductRemoved>;
 	/**