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

package/types/bootstrap.d.ts

@@ -56,6 +56,13 @@ export interface SettingsResponse {
 		queryParamAllowlist?: string[];
 		/** Host for ingest and for the API. */
 		apiHost?: string;
+		/** The share of visitors sent for, decided per anonymous id (since 3.18). Absent: 1. */
+		sampleRate?: number;
+		/**
+		 * Console logging for everyone, or for a session opened with `?hp_debug=<token>` whose SHA-256
+		 * is `tokenSha256` (since 3.18). Absent: off.
+		 */
+		debug?: { enabled: boolean; tokenSha256: string | null };
 		/** Each property's personalisation holdout, keyed by property id. */
 		holdouts?: Record<
 			string,
@@ -132,6 +139,10 @@ export interface BootstrapOptions {
 	dataLayer?: { name?: string; ignore?: string[] };
 	/** Rename what the SDK stores. Defaults are `thg_hp_*`. */
 	storageNames?: StorageNames;
+	/**
+	 * Log every event to the console. Also on when the settings turn it on (`hp.debug`), for everyone
+	 * or for a session opened with `?hp_debug=<token>`, without a release of the page.
+	 */
 	debug?: boolean;
 	/** Development and tests: use this settings response and never fetch or cache one. */
 	settings?: SettingsResponse;

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.8
+// Spec version: 1.10
 
 /** The product shape shared by every commerce event. */
 export interface CdpProduct {
@@ -36,6 +36,7 @@ export interface DecisionMade {
 	propensity: number;
 	arm: string;
 	kind?: 'recommendation' | 'search_rank' | 'banner' | 'offer' | 'layout' | 'copy' | 'price' | 'other' | null;
+	learning_reset_at?: string | null;
 	explored?: boolean | null;
 	context_features?: Record<string, unknown> | null;
 	context_key?: string | null;
@@ -565,8 +566,32 @@ export interface EmailMarkedAsSpam {
 	email_id?: string | null;
 }
 
+/** The app was launched for the first time after being installed. */
+export interface ApplicationInstalled {
+	version: string;
+	build: string;
+}
+
+/** The app was launched, or came back to the foreground. */
+export interface ApplicationOpened {
+	from_background: boolean;
+	version: string;
+	build: string;
+}
+
+/** The app went to the background. */
+export type ApplicationBackgrounded = Record<string, never>;
+
+/** The app was launched for the first time after an update to a different version or build. */
+export interface ApplicationUpdated {
+	previous_version: string;
+	previous_build: string;
+	version: string;
+	build: string;
+}
+
 /** The spec version these models implement. SDKs stamp it on context.spec.version. */
-export const SPEC_VERSION = '1.8';
+export const SPEC_VERSION = '1.10';
 
 /** Every event name the registry accepts. Anything else is rejected at the ingest. */
 export type CdpEventName =
@@ -620,6 +645,10 @@ export type CdpEventName =
 	| 'Order Returned'
 	| 'Email Bounced'
 	| 'Email Marked as Spam'
+	| 'Application Installed'
+	| 'Application Opened'
+	| 'Application Backgrounded'
+	| 'Application Updated'
 ;
 
 /** Event name -> its properties, so a generic emitter stays type-safe. */
@@ -674,6 +703,10 @@ export interface CdpEventProperties {
 	'Order Returned': OrderReturned;
 	'Email Bounced': EmailBounced;
 	'Email Marked as Spam': EmailMarkedAsSpam;
+	'Application Installed': ApplicationInstalled;
+	'Application Opened': ApplicationOpened;
+	'Application Backgrounded': ApplicationBackgrounded;
+	'Application Updated': ApplicationUpdated;
 }
 
 /** Which producers the registry permits for each event. Emitting from another is refused. */

package/types/index.d.ts

@@ -171,6 +171,11 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 
 	/** The property's personalisation holdout, from the settings (`hp.holdouts`). */
 	holdout?: Holdout | null;
+	/**
+	 * The share of visitors to send for, from the settings (`hp.sampleRate`): a visitor whose
+	 * anonymous id falls outside it sends nothing. Default 1. Since 3.18.
+	 */
+	sampleRate?: number;
 
 	/** Keep only these query params (anchored, case-insensitive patterns), plus campaign params. */
 	queryParamAllowlist?: string[];
@@ -184,10 +189,10 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 
 	/**
 	 * Where device ids come from, as the source's settings serve it (`hp.anonymousId`, chosen in the
-	 * console). One place per source, never a fallback between two:
+	 * console):
 	 *
 	 * - `site_cookie`: the site's own first-party cookie, the one named here or, with `cookie: null`,
-	 *   whatever `getAnonymousId` reads. Read only: a visitor without it has no device id.
+	 *   whatever `getAnonymousId` reads. Read only; a visitor without it gets the SDK's own (3.18).
 	 * - `hp_cookie`: Hyper-Personalisation's own first-party cookie (`storageNames.anonymousId`,
 	 *   `thg_hp_anonymous_id`), which the SDK mints and keeps; `getAnonymousId` is ignored.
 	 *
@@ -231,11 +236,11 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 	};
 }
 
-/** The event as queued, or null when the tracking plan disables it. */
+/** The event as queued, or null when the tracking plan disables it or the visitor is outside the sample. */
 type Emit<P> = (properties: P, options?: CallOptions) => CdpEvent | null;
 
 export interface AnalyticsClient {
-	/** Null when the tracking plan disables the event. */
+	/** Null when the tracking plan disables the event or the visitor is outside the sample. */
 	track<E extends CdpEventName>(
 		event: E,
 		properties?: CdpEventProperties[E],
@@ -473,6 +478,8 @@ export interface StorageNames {
 	session?: string;
 	/** Session cookie: the preview token from `?hp_preview=` (3.15). Default 'thg_hp_preview'. */
 	preview?: string;
+	/** sessionStorage: the debug token from `?hp_debug=` (3.18). Default 'thg_hp_debug'. */
+	debug?: string;
 }
 
 /** Where a source's device ids come from: the settings' `hp.anonymousId` (since 3.6). */