@thg-agentic/hyper-personalisation-web 3.24.1 → 3.26.0

package/types/bootstrap.d.ts

@@ -88,6 +88,13 @@ export interface Preset extends DataLayerPreset {
 export interface Identity {
 	userId?: string | number | null;
 	emailSha256?: string | null;
+	/**
+	 * The identity token your server signed for this user on this page view (ADR 0067): a JWT,
+	 * ES256 with `typ: "JWT"` over `{ sub: userId, aud: "hyper-personalisation", exp }`. Without
+	 * it the sign-in is recorded but never joins this device to the user's others, and a promo
+	 * reminder's code is not shown. Since 3.26.
+	 */
+	token?: string | null;
 }
 
 export interface AutocaptureOptions {
@@ -165,8 +172,9 @@ export interface BootstrappedClient extends AnalyticsClient {
 }
 
 /**
- * The client, or null when the key is not enabled, the settings cannot be fetched on a first
- * visit, or the options are invalid. Never rejects. Idempotent per page.
+ * The client, or null when the key is not enabled or the options are invalid. Settings that cannot
+ * be fetched on a first visit start it on built-in, collect-only defaults (3.25). Never rejects.
+ * Idempotent per page.
  */
 export declare function bootstrap(
 	config: HpConfig,

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.18
+// Spec version: 1.20
 
 /** context.source.environment. Environment the producer runs in. */
 export type CdpSourceEnvironment = 'production' | 'staging' | 'development';
@@ -91,6 +91,32 @@ export interface JourneyTriggered {
 	products?: CdpProduct[];
 }
 
+/** The serving log: one ranked rail as the recommender answered it, with the features it ranked on, recorded when it was served rather than recomputed later. */
+export interface RecommendationServed {
+	recommendation_request_id: string;
+	group: 'personalised' | 'holdout' | 'excluded';
+	personalised: boolean;
+	products: Record<string, unknown>[];
+	batch_request_id?: string | null;
+	placement?: string | null;
+	recipe_requested?: string | null;
+	recipe?: string | null;
+	strategy?: string | null;
+	algorithm_version?: string | null;
+	ranked_by?: 'ranker' | 'blend' | 'session' | 'manual' | 'other' | null;
+	fusion?: string | null;
+	fast_weight?: number | null;
+	found?: boolean | null;
+	degraded?: boolean | null;
+	person_id?: string | null;
+	decision_id?: string | null;
+	arm?: string | null;
+	propensity?: number;
+	limit?: number | null;
+	candidate_set_size?: number | null;
+	unserved?: Record<string, unknown>[] | null;
+}
+
 /** 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;
@@ -686,12 +712,13 @@ export interface SignUpRelayed {
 }
 
 /** The spec version these models implement. SDKs stamp it on context.spec.version. */
-export const SPEC_VERSION = '1.18';
+export const SPEC_VERSION = '1.20';
 
 /** Every event name the registry accepts. Anything else is rejected at the ingest. */
 export type CdpEventName =
 	| 'Decision Made'
 	| 'Journey Triggered'
+	| 'Recommendation Served'
 	| 'Slot Engaged'
 	| 'Recommendations Viewed'
 	| 'Promotion Viewed'
@@ -755,6 +782,7 @@ export type CdpEventName =
 export interface CdpEventProperties {
 	'Decision Made': DecisionMade;
 	'Journey Triggered': JourneyTriggered;
+	'Recommendation Served': RecommendationServed;
 	'Slot Engaged': SlotEngaged;
 	'Recommendations Viewed': RecommendationsViewed;
 	'Promotion Viewed': PromotionViewed;

package/types/hp.d.ts

@@ -35,8 +35,9 @@ interface HpTrack {
 /**
  * The page's client, callable from anywhere: calls made before `bootstrap` has started it wait and
  * replay in order, keeping the messageId and time they were made with; on a page that turns out to
- * be off they are dropped. A page that navigates first, or never reaches the API, carries them to the
- * next page, which sends them under its own consent (3.9, 3.9.1). Nothing is returned (but by
+ * be off they are dropped. A page that navigates first carries them to the next page, which sends
+ * them under its own consent (3.9); one that cannot reach the API starts on built-in settings and
+ * sends them itself (3.25). Nothing is returned (but by
  * `assignmentDecisionId` and `recommendationContext`), nothing is awaited, and nothing ever throws
  * into the caller.
  */

package/types/index.d.ts

@@ -119,7 +119,8 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 	apiHost?: string;
 	/** Default 'web'. */
 	writeKey?: string;
-	propertyId: string | number;
+	/** null: none on the wire, and the ingest stamps the key's (a key scoped to one property). */
+	propertyId: string | number | null;
 	channel?: string | null;
 	market?: string | null;
 	environment?: string | null;
@@ -200,7 +201,7 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 	mintAnonymousId?: boolean;
 	/**
 	 * Strict consent: carry events held for an unanswered CMP across a navigation, in sessionStorage
-	 * per property (`thg_hp_held`), so a redirect before the answer (a sign-in) does not lose them.
+	 * per write key (`thg_hp_held`), so a redirect before the answer (a sign-in) does not lose them.
 	 * They leave only on a grant, on whichever page it comes, and are deleted on a refusal or after
 	 * 30 minutes. This writes event data to the device before the visitor has answered: enable it
 	 * only where your consent policy allows that. With bootstrap it also lets `hp` carry calls made
@@ -208,6 +209,12 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 	 */
 	holdAcrossPages?: boolean;
 	getUserId?(): string | null | undefined;
+	/**
+	 * The identity token your server signed for the user `getUserId` names (a JWT, ADR 0067), read
+	 * once: sent on each identify and with each onsite decision until `reset()`, a sign-out or
+	 * another user's `identify`. A later sign-in passes its own on `identify`. Since 3.26.
+	 */
+	identityToken?: string | null;
 	/** Observer for every event that will be sent. Must not throw; failures are swallowed. */
 	onEvent?(event: CdpEvent): void;
 
@@ -466,7 +473,7 @@ export interface StorageNames {
 	decisions?: string;
 	/** localStorage. Default 'thg_hp_settings'. */
 	settings?: string;
-	/** sessionStorage, with holdAcrossPages. Default 'thg_hp_held'. */
+	/** sessionStorage, per write key, with holdAcrossPages. Default 'thg_hp_held'. */
 	held?: string;
 	/** sessionStorage: `hp` calls carried to the next page (3.9). Default 'thg_hp_carried'. */
 	carried?: string;

package/types/onsite.d.ts

@@ -47,6 +47,15 @@ export interface OnsiteForm {
 	pages?: { include?: string[]; exclude?: string[] };
 	/** `mobile` is a coarse pointer or a viewport under 768px. Absent: both. */
 	devices?: Array<'desktop' | 'mobile'>;
+	/**
+	 * Shown only to a visit that arrived from a matching campaign: the landing page's `utm_*` tags,
+	 * kept for the visit. Every rule must hold; any of a rule's values meets it, in any case.
+	 */
+	arrived_from?: Array<{
+		field: 'source' | 'medium' | 'campaign' | 'content' | 'term';
+		match: 'is' | 'contains';
+		values: string[];
+	}>;
 	/** Shown only with personalisation consent, and only to members as the server decides. */
 	audiences?: string[];
 	exclude_subscribed?: boolean;