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

package/types/hp.d.ts

@@ -0,0 +1,64 @@
+import type { CdpEventName, CdpEventProperties } from './events';
+import type {
+	AnalyticsClient,
+	CallOptions,
+	RecommendationContext,
+} from './index';
+
+type Methods = {
+	[K in keyof AnalyticsClient as AnalyticsClient[K] extends (
+		...args: never[]
+	) => unknown
+		? K
+		: never]: AnalyticsClient[K];
+};
+
+/**
+ * `track`, with both of the client's forms. A mapped `Parameters<>` keeps only an overloaded
+ * function's last signature, which typed `hp.track` as the extension form alone and refused
+ * `hp.track('Identity Linked', …)`.
+ */
+interface HpTrack {
+	<E extends CdpEventName>(
+		event: E,
+		properties?: CdpEventProperties[E],
+		options?: CallOptions,
+	): void;
+	(
+		event: `${string}.${string}`,
+		properties?: Record<string, unknown>,
+		options?: CallOptions,
+	): void;
+}
+
+/**
+ * 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
+ * `assignmentDecisionId` and `recommendationContext`), nothing is awaited, and nothing ever throws
+ * into the caller.
+ */
+export declare const hp: {
+	[K in Exclude<keyof Methods, 'track' | 'recommendationContext'>]: (
+		...args: Parameters<Methods[K]>
+	) => void;
+} & {
+	track: HpTrack;
+	/**
+	 * The `decision_id` HP logged when it assigned `arm` to `slot` server-side for this visitor's
+	 * session, for the page's `Slot Engaged`. Synchronous: it reads the session cookie (else the
+	 * visitor cookie) bootstrap was given, so it answers once bootstrap has been called, started or
+	 * not. Null before that, or with neither cookie. Since 3.10.
+	 */
+	assignmentDecisionId(assignment: {
+		slot: string;
+		arm: string;
+	}): string | null;
+	/**
+	 * This visit as the recommendations API's session context, now: append
+	 * `new URLSearchParams(hp.recommendationContext())` to the request. Synchronous; `{}` before the
+	 * client has started, and without personalisation consent. Since 3.11.
+	 */
+	recommendationContext(): RecommendationContext;
+};

package/types/index.d.ts

@@ -0,0 +1,610 @@
+import type { ConsentAdapter, ConsentState } from './consent';
+import type {
+	BackInStockSubscribed,
+	CartShared,
+	CartUpdated,
+	CartViewed,
+	CdpEventName,
+	CdpEventProperties,
+	CdpProduct,
+	CheckoutFailed,
+	CheckoutStarted,
+	CheckoutStepCompleted,
+	CheckoutStepViewed,
+	ConsentUpdated,
+	CouponApplied,
+	CouponDenied,
+	CouponEntered,
+	CouponRemoved,
+	IdentityLinked,
+	NewsletterSubscribed,
+	NewsletterUnsubscribed,
+	PaymentInfoEntered,
+	PersonalisationExposed,
+	ProductAdded,
+	ProductAddedToWishlist,
+	ProductClicked,
+	ProductListFiltered,
+	ProductListViewed,
+	ProductRemoved,
+	ProductRemovedFromWishlist,
+	ProductReviewed,
+	ProductShared,
+	ProductsSearched,
+	ProductVariantSelected,
+	ProductViewed,
+	PromotionClicked,
+	PromotionViewed,
+	RecommendationsViewed,
+	SignedIn,
+	SignedUp,
+	SlotEngaged,
+	WishlistProductAddedToCart,
+} from './events';
+
+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';
+
+export interface PageProperties {
+	/** Stored as context.page.type and inherited by later events on the page. */
+	type?: PageType;
+	name?: string | null;
+	navigation_trigger?:
+		| 'navigate'
+		| 'reload'
+		| 'back_forward'
+		| 'prerender'
+		| 'soft_navigate'
+		| null;
+	category?: string | null;
+}
+
+export interface IdentifyTraits {
+	/** Becomes the envelope userId for this and every later event, until reset() or signedOut(). */
+	userId?: string | number | null;
+	/** Use hashEmail(). Raw email is never sent. */
+	email_sha256?: string | null;
+	/** Use hashPhone(). Raw phone numbers are never sent. */
+	phone_sha256?: string | null;
+	accepts_marketing?: boolean | null;
+	gender?: string | null;
+	created_at?: string | null;
+}
+
+/** Per-call context overrides, deep-merged into the event's context. */
+export type ContextOverrides = Record<string, unknown>;
+/** Either the overrides themselves, or analytics-next style `{ context: overrides }`. */
+export type CallOptions = ContextOverrides | { context: ContextOverrides };
+
+export interface CdpEvent {
+	type: 'track' | 'page' | 'identify';
+	event?: string;
+	messageId: string;
+	timestamp: string;
+	anonymousId: string | null;
+	userId: string | null;
+	properties?: Record<string, unknown>;
+	traits?: Record<string, unknown>;
+	context: Record<string, unknown>;
+}
+
+export interface ValidationResult {
+	valid: boolean;
+	errors: string[];
+}
+
+/** The per-event sources shared with cdpPlugins(). */
+export interface AnalyticsContextSources {
+	/**
+	 * The host's session id. Omitted, the SDK keeps its own (3.15): a first-party cookie
+	 * (`storageNames.session`) ended by 30 minutes without an event, written only under a grant.
+	 * 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;
+	getRecommendations?(): Record<string, unknown>[] | null | undefined;
+	getExtensions?(): Record<string, unknown> | null | undefined;
+}
+
+export interface AnalyticsOptions extends AnalyticsContextSources {
+	/** Ingest base URL, only for a first-party proxy; events are POSTed to `${apiHost}/v1/batch`. */
+	apiHost?: string;
+	/** Default 'web'. */
+	writeKey?: string;
+	propertyId: string | number;
+	channel?: string | null;
+	market?: string | null;
+	environment?: string | null;
+	/** ISO-4217 currency, when the site trades in one. `getCurrency` wins when it answers. */
+	currency?: string | null;
+	/** The site's locale (which storefront was served), not the browser's. `getLocale` wins. */
+	locale?: string | null;
+	country?: string | null;
+	/** ISO-3166 alpha-2 destination. `getShipToCountry` wins. */
+	shipToCountry?: string | null;
+	/** Read per event: the currency this request is priced in. Invalid values are dropped. */
+	getCurrency?(): string | null | undefined;
+	/** Read per event: where this visitor's order would ship. */
+	getShipToCountry?(): string | null | undefined;
+	/** Read per event: the storefront locale served, e.g. `en-GB` (kept as given). */
+	getLocale?(): string | null | undefined;
+	/** Initial context.page.type, before the first page() call. */
+	pageType?: PageType | null;
+	/** Used when there is no window (SSR). */
+	pageUrl?: string | null;
+	pagePath?: string | null;
+
+	/**
+	 * Strict consent: nothing is sent or stored until analytics is granted, and a CMP that never
+	 * answers is never a grant. Without an adapter the host has decided the basis itself, and events
+	 * carry `context.consent: { basis: 'host' }` (3.7.0, spec 1.5).
+	 */
+	consent?: ConsentAdapter;
+	/** How long to hold events for the CMP before dropping them. Default 5000. */
+	consentTimeoutMs?: number;
+	/** Domain for the consent cookie, e.g. '.example.com' to share it with checkout. */
+	consentCookieDomain?: string;
+	/** Called with the gate's status: pending, granted, denied or unknown (timed out). */
+	onConsentStatus?(status: 'pending' | 'granted' | 'denied' | 'unknown'): void;
+	/** Rename what the SDK stores. Defaults are `thg_hp_*`; one SDK per page. */
+	storageNames?: StorageNames;
+	/** Segment-style tracking plan: `track[event].enabled === false` drops it, `__default` covers the rest. */
+	plan?: { track?: Record<string, { enabled?: boolean }> } | null;
+
+	/** The property's personalisation holdout, from the settings (`hp.holdouts`). */
+	holdout?: Holdout | null;
+
+	/** Keep only these query params (anchored, case-insensitive patterns), plus campaign params. */
+	queryParamAllowlist?: string[];
+	/** Strip these query params. Ignored when an allowlist is given. */
+	queryParamBlocklist?: string[];
+	/**
+	 * Param names (anchored, case-insensitive patterns) exempt from the built-in sensitive-name rules.
+	 * A value that is an email address or a card-length number is dropped regardless.
+	 */
+	sensitiveParamAllowlist?: string[];
+
+	/**
+	 * 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:
+	 *
+	 * - `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.
+	 * - `hp_cookie`: Hyper-Personalisation's own first-party cookie (`storageNames.anonymousId`,
+	 *   `thg_hp_anonymous_id`), which the SDK mints and keeps; `getAnonymousId` is ignored.
+	 *
+	 * Absent, as in settings from before 3.6: `getAnonymousId`. `bootstrap` passes it from the
+	 * settings. Since 3.6.
+	 */
+	anonymousIdSource?: AnonymousIdSource | null;
+	/** The site's own device id, under `site_cookie` with no cookie named, or with no setting. */
+	getAnonymousId?(): string | null | undefined;
+	/**
+	 * @deprecated Ignored since 3.6. Where device ids come from is set per source in the console
+	 * (`anonymousIdSource`): the site's own cookie, or Hyper-Personalisation's, which the SDK mints.
+	 * With `debug`, the SDK says so once.
+	 */
+	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.
+	 * 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
+	 * before the start across an unanswered navigation (3.9). Default false. Since 3.5.
+	 */
+	holdAcrossPages?: boolean;
+	getUserId?(): string | null | undefined;
+	/** Observer for every event that will be sent. Must not throw; failures are swallowed. */
+	onEvent?(event: CdpEvent): void;
+
+	debug?: boolean;
+	/** Inject @thg-agentic/hyper-personalisation-spec's validateEvent in development. */
+	validate?(event: CdpEvent, options: { producer: 'web' }): ValidationResult;
+	throwOnInvalid?: boolean;
+	/** Replace delivery, e.g. in tests. */
+	transport?: {
+		enqueue(event: CdpEvent): void;
+		flush(options?: { beacon?: boolean }): Promise<void>;
+		/** Strict consent: analytics was granted, so batches persisted earlier may be replayed. */
+		replayPersisted?(): unknown;
+		/** Strict consent: analytics was refused, so batches persisted earlier must be forgotten. */
+		clearPersisted?(): void;
+	};
+}
+
+/** The event as queued, or null when the tracking plan disables it. */
+type Emit<P> = (properties: P, options?: CallOptions) => CdpEvent | null;
+
+export interface AnalyticsClient {
+	/** Null when the tracking plan disables the event. */
+	track<E extends CdpEventName>(
+		event: E,
+		properties?: CdpEventProperties[E],
+		options?: CallOptions,
+	): CdpEvent | null;
+	/** A custom event under a registered extension namespace, e.g. 'acme.Size Guide Opened'. */
+	track(
+		event: `${string}.${string}`,
+		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. */
+	reset(): void;
+
+	productViewed: Emit<ProductViewed>;
+	productListViewed: Emit<ProductListViewed>;
+	recommendationsViewed: Emit<RecommendationsViewed>;
+	/** Prefer `recordExposure`, which reads the serving response's `exposure` block. */
+	personalisationExposed: Emit<PersonalisationExposed>;
+	/**
+	 * Log the exposure a serving response carries (membership, decisions or recommendations), once
+	 * per token. Null when the response personalised nothing or its token was already recorded.
+	 * A decisions response's logged decisions are then in force: every later event this session
+	 * carries them as `context.decisions`, unless `getDecisions` is passed.
+	 */
+	recordExposure(body: ServingBody, options?: CallOptions): CdpEvent | null;
+	/**
+	 * A surface rendered server-side from a serving answer the page never sees (a product rail
+	 * the site's server fetched from HP) came into view: record the property holdout's exposure for it, for
+	 * both groups, with the group serving decided. Null, and nothing recorded, for a visitor outside
+	 * the experiment: no holdout in the settings, outside the ramp, no visitor or session id, or a
+	 * rail or audience without personalisation consent. One per session per surface.
+	 */
+	surfaceViewed(
+		surface: { surface: ServingExposure['surface'] },
+		options?: CallOptions,
+	): CdpEvent | null;
+	/**
+	 * Whether this shopper must see the default: held out, or outside the property's ramp (excluded),
+	 * as the edge and the public API decide it. True: skip anything the page personalises itself.
+	 * `personalisationGroup()` gives the exact group.
+	 */
+	inHoldout(): boolean;
+	/**
+	 * This shopper's group, as the edge and the public API decide it. Personalise in the page only for
+	 * `personalised`: `holdout` and `excluded` get the default everywhere.
+	 */
+	personalisationGroup(): PersonalisationGroup;
+	productClicked: Emit<ProductClicked>;
+	productListFiltered: Emit<ProductListFiltered>;
+	productsSearched: Emit<ProductsSearched>;
+	productAdded: Emit<ProductAdded>;
+	productRemoved: Emit<ProductRemoved>;
+	/**
+	 * The basket as the platform confirmed it after a change, every line with its total quantity.
+	 * Send alongside productAdded and productRemoved, never instead. `item_count` is summed from the
+	 * lines when omitted.
+	 */
+	cartUpdated: Emit<ConfirmedBasket>;
+	/** An identity edge an identify cannot imply. Send the event-named trigger. */
+	identityLinked: Emit<IdentityLinked>;
+	/** A visitor saw, clicked or dismissed a decisioned slot. */
+	slotEngaged: Emit<SlotEngaged>;
+	/** A size, colour or flavour the shopper picked: product_id the master, sku the new variant. */
+	productVariantSelected: Emit<ProductVariantSelected>;
+	cartViewed: Emit<CartViewed>;
+	productAddedToWishlist: Emit<ProductAddedToWishlist>;
+	productRemovedFromWishlist: Emit<ProductRemovedFromWishlist>;
+	/** A wishlist conversion. Send productAdded for the cart add as well. */
+	wishlistProductAddedToCart: Emit<WishlistProductAddedToCart>;
+	productShared: Emit<ProductShared>;
+	cartShared: Emit<CartShared>;
+	/** Report each coupon fact from one producer per property, browser or server. */
+	couponEntered: Emit<CouponEntered>;
+	couponApplied: Emit<CouponApplied>;
+	couponDenied: Emit<CouponDenied>;
+	couponRemoved: Emit<CouponRemoved>;
+	checkoutStarted: Emit<CheckoutStarted>;
+	promotionViewed: Emit<PromotionViewed>;
+	promotionClicked: Emit<PromotionClicked>;
+	checkoutStepViewed: Emit<CheckoutStepViewed>;
+	checkoutStepCompleted: Emit<CheckoutStepCompleted>;
+	/** Send instead of checkoutStepCompleted for the payment step, never as well. */
+	paymentInfoEntered: Emit<PaymentInfoEntered>;
+	/** Where checkout failed and why. The kind of payment instrument only, never card data. */
+	checkoutFailed: Emit<CheckoutFailed>;
+	signedIn: Emit<SignedIn>;
+	signedUp: Emit<SignedUp>;
+	/** Sent under the signed-in identity, which is then cleared. */
+	signedOut(options?: CallOptions): CdpEvent | null;
+	newsletterSubscribed: Emit<NewsletterSubscribed>;
+	/** An on-site opt-out. The ESP reports its own as Email Unsubscribed. */
+	newsletterUnsubscribed: Emit<NewsletterUnsubscribed>;
+	/** An alert request for one product: back in stock, a price drop or a launch. */
+	backInStockSubscribed: Emit<BackInStockSubscribed>;
+	productReviewed: Emit<ProductReviewed>;
+	consentUpdated: Emit<ConsentUpdated>;
+
+	flush(options?: { beacon?: boolean }): Promise<void>;
+	readonly lastPageMessageId: string | null;
+	/** The device id events carry: the site's cookie's, or under `hp_cookie` the SDK's own. */
+	readonly anonymousId: string | null;
+	/** The consent state in force (strict mode), or null while the CMP has not answered. */
+	readonly consent: ConsentState | null;
+	/** Spread into every serving request (recommendations, decisions, audiences): `hp-consent`. */
+	servingHeaders(): { 'hp-consent': string };
+	/**
+	 * This visit as the recommendations API's session context, in its wire form: append
+	 * `new URLSearchParams(context)` to the request. `{}` without personalisation consent. Since 3.11.
+	 */
+	recommendationContext(): RecommendationContext;
+}
+
+/**
+ * The visit's products and searches, newest first, as `GET /v1/recommendations` takes them. Each
+ * key is present only when it has something in it. Since 3.11.
+ */
+export interface RecommendationContext {
+	/** Products engaged with (viewed, clicked, added), comma-separated. */
+	viewed?: string;
+	/** Products in the basket, comma-separated. */
+	basket?: string;
+	/** Searches, comma-separated. */
+	q?: string;
+	/** `id:count` pairs: products shown and not engaged with, most shown first. */
+	impressed?: string;
+}
+
+/** A line's subscription, as products[].subscription carries it (spec 1.4). */
+export interface CdpProductSubscription {
+	is_subscription?: boolean | null;
+	frequency_days?: number | null;
+	plan_id?: string | null;
+}
+
+/** One `discounts[]` entry on a basket event. */
+export interface CdpBasketDiscount {
+	coupon_name: string;
+	coupon_id?: string | null;
+	discount?: number | null;
+	type?: string | null;
+}
+
+/** The platform's confirmed basket, as cartUpdated takes it: Cart Updated, item_count optional. */
+export interface ConfirmedBasket
+	extends Omit<CartUpdated, 'products' | 'discounts'> {
+	products: Array<
+		CdpProduct & { subscription?: CdpProductSubscription | null }
+	>;
+	discounts?: CdpBasketDiscount[] | null;
+}
+
+/** Cart Updated's properties from a confirmed basket, with item_count summed when absent. */
+export declare function cartSnapshot(basket: ConfirmedBasket): CartUpdated;
+
+/** A property's personalisation holdout: its share of shoppers and the salt they are hashed with. */
+export interface Holdout {
+	share: number;
+	/** The share of all shoppers personalised (the ramp); null or absent personalises everyone else. */
+	ramp?: number | null;
+	salt: string;
+	/** Readout slots: each splits personalised visitors 50/50 between the bandit and its default. Since 3.16. */
+	readoutSlots?: string[];
+}
+
+/** A shopper's group: `holdout` and `excluded` (outside the ramp) both get the default. */
+export type PersonalisationGroup = 'holdout' | 'personalised' | 'excluded';
+
+/** The `exposure` block a serving response carries when it personalised, or would have. */
+export interface ServingExposure {
+	token: string;
+	surface: 'audiences' | 'decisions' | 'recommendations';
+	holdout: boolean;
+	/** Absent: the property's, from the settings (a cached server-rendered page has no response). */
+	holdout_share?: number | null;
+	/** The share of all shoppers personalised when this was served (the ramp). Absent: as above. */
+	personalised_share?: number | null;
+}
+
+/** The parts of a membership, decisions or recommendations response `recordExposure` reads. */
+export interface ServingBody {
+	exposure?: ServingExposure | null;
+	audiences?: string[];
+	decisions?: Array<{
+		slot: string;
+		decision_id?: string | null;
+		arm?: string | null;
+		/** Held out: the slot showed its default, and is not put in force. */
+		holdout?: boolean;
+		/**
+		 * A readout slot's side of its bandit-vs-default split, as serving answered it. Absent: the SDK
+		 * computes it from the settings. `default` is no decision and is not put in force. Since 3.16.
+		 */
+		variant?: 'bandit' | 'default';
+	}>;
+	recommendation_request_id?: string;
+}
+
+/** Where the SDK stores what it stores, by kind. Every default carries the `thg_hp_` prefix. */
+export interface StorageNames {
+	/** Cookie. Default 'thg_hp_consent'. */
+	consent?: string;
+	/** localStorage. Default 'thg_hp_retry'. */
+	retry?: string;
+	/** localStorage / sessionStorage. Default 'thg_hp_session_signals'. */
+	sessionSignals?: string;
+	/** sessionStorage. Default 'thg_hp_identified'. */
+	identified?: string;
+	/** sessionStorage. Default 'thg_hp_prev_page'. */
+	previousPage?: string;
+	/** sessionStorage. Default 'thg_hp_decisions'. */
+	decisions?: string;
+	/** localStorage. Default 'thg_hp_settings'. */
+	settings?: string;
+	/** sessionStorage, with holdAcrossPages. Default 'thg_hp_held'. */
+	held?: string;
+	/** sessionStorage: `hp` calls carried to the next page (3.9). Default 'thg_hp_carried'. */
+	carried?: string;
+	/**
+	 * localStorage: the visit for `hp.recommendationContext()` before the SDK starts on the next page
+	 * (3.11). Default 'thg_hp_recommendation_context'.
+	 */
+	recommendationContext?: string;
+	/**
+	 * Cookie, one per browser, for a source set to `hp_cookie`: Hyper-Personalisation's device id.
+	 * Default 'thg_hp_anonymous_id'.
+	 */
+	anonymousId?: string;
+	/**
+	 * Cookie: the session id the SDK keeps when the host names none, 30 minutes from the last event
+	 * (3.15). Default 'thg_hp_session'.
+	 */
+	session?: string;
+	/** Session cookie: the preview token from `?hp_preview=` (3.15). Default 'thg_hp_preview'. */
+	preview?: string;
+}
+
+/** Where a source's device ids come from: the settings' `hp.anonymousId` (since 3.6). */
+export type AnonymousIdSource =
+	| { source: 'site_cookie'; cookie: string | null }
+	| { source: 'hp_cookie' };
+
+export declare const VERSION: string;
+/** The HP API, where the SDK goes when no `apiHost` is given. */
+export declare const DEFAULT_API_HOST: string;
+/** An `apiHost` as an origin: DEFAULT_API_HOST when none is given, null when the one given is invalid. */
+export declare function resolveApiHost(host?: string | null): string | null;
+export declare const PAGE_TYPES: ReadonlySet<PageType>;
+
+export declare function createAnalytics(
+	options: AnalyticsOptions,
+): AnalyticsClient;
+
+/** Default parent-id resolver: `item.item_group_id ?? item.item_id`. */
+export declare function defaultProductId(
+	item: Record<string, unknown>,
+): unknown;
+/** GA4 item -> spec product. product_id comes from `productId` (default above), sku from item_id. */
+export declare function fromGa4Item(
+	item: Record<string, unknown> | null | undefined,
+	productId?: (item: Record<string, unknown>) => unknown,
+): CdpProduct | null;
+/** GA4 items -> spec products, dropping any with no identity. */
+export declare function toProducts(
+	items: unknown[] | null | undefined,
+	productId?: (item: Record<string, unknown>) => unknown,
+): CdpProduct[];
+export declare function pruneProperties<
+	T extends Record<string, unknown> | null | undefined,
+>(properties: T): T;
+
+/** SHA-256 as lowercase hex. */
+export declare function sha256(value: string): Promise<string>;
+/**
+ * `email_sha256` for an address, synchronously: trim, lowercase, SHA-256. Null when the input is not
+ * an email. Hash in the same call that reports it, so nothing is awaited. Since 3.9.
+ */
+export declare function emailSha256(
+	email: string | null | undefined,
+): string | null;
+/** As emailSha256, as a promise. */
+export declare function hashEmail(
+	email: string | null | undefined,
+): Promise<string | null>;
+/** `phone_sha256` for identify: E.164, SHA-256. Null when the input is not an E.164 number. */
+export declare function hashPhone(
+	phone: string | null | undefined,
+): Promise<string | null>;
+/**
+ * A SHA-256 digest (hex, base64 or base64url) as lowercase hex, for `email_sha256`. Re-encodes, never
+ * re-hashes; null for anything that is not a 32-byte digest.
+ */
+export declare function normaliseSha256(
+	value: string | null | undefined,
+): string | null;
+
+export declare function getCookie(name: string): string | null;
+
+/** HP's fixed UUID namespace for the `decision_id` of a server-side assignment. Since 3.10. */
+export declare const ASSIGNMENT_DECISION_NAMESPACE: string;
+/**
+ * The `decision_id` HP logged for a server-side assignment (`POST /v1/assignments`):
+ * `UUIDv5(ASSIGNMENT_DECISION_NAMESPACE, "<session_id>:<slot>:<arm>")`, where `session_id` is the
+ * session HP assigned under (the renderer's session id, else the visitor id). Null when any part is
+ * missing. In a page, `hp.assignmentDecisionId({ slot, arm })` reads the session for you. Since 3.10.
+ */
+export declare function assignmentDecisionId(assignment: {
+	sessionId: string | null | undefined;
+	slot: string;
+	arm: string;
+}): string | null;
+
+export interface VariantAssignment {
+	experiment: string;
+	variant: string;
+	holdout: boolean;
+	assignment_bucket: number;
+	assignment_unit_kind: string;
+}
+export declare function assignRecommendationVariant(options: {
+	unit: string | null | undefined;
+	experiment: string;
+	variants: Array<{ name: string; share: number }>;
+	holdoutShare?: number;
+	holdoutName?: string;
+	salt?: string;
+	buckets?: number;
+	unitKind?: 'anonymous_id' | 'customer_id' | 'session_id' | 'other';
+}): VariantAssignment | null;
+export declare function candidateSetFingerprint(
+	productIds: Array<string | number> | null | undefined,
+): string | null;
+export declare function hashBucket(
+	unit: string,
+	salt: string,
+	buckets?: number,
+): number;
+export declare function hash32(input: string): number;
+/**
+ * A visitor's side of a readout slot's bandit-vs-default 50/50, as the public API splits it;
+ * spec/assignment/bandit-split.json holds the vectors. Null without a slot or a unit. Since 3.16.
+ */
+export declare function banditSplit(
+	slot: string,
+	unit: string | null | undefined,
+): 'bandit' | 'default' | null;
+/** The same answer the edge and the public API give; spec/assignment/holdout.json holds the vectors. */
+export declare function holdoutAssignment(
+	holdout: Holdout | null | undefined,
+	unit: string | null | undefined,
+): { holdout: boolean; bucket: number | null; group: PersonalisationGroup };
+
+export declare function createSocialProof(options: {
+	/** As for bootstrap(): optional, only for a first-party proxy. */
+	apiHost?: string;
+	/** The page's publishable key; it names the properties it may read. */
+	writeKey: string;
+	/** Only for a key scoped to several properties. */
+	propertyId?: string;
+	ttlMs?: number;
+	fetchImpl?: typeof fetch;
+	/** Sent as `hp-consent`. Default: read back from the consent cookie. */
+	getConsent?(): Partial<ConsentState> | null;
+}): {
+	forProducts(
+		productIds: string[],
+		options?: { keyType?: string },
+	): Promise<Map<string, unknown>>;
+	trending(limit?: number, options?: { keyType?: string }): Promise<unknown[]>;
+};