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

package/types/onsite.d.ts

@@ -0,0 +1,195 @@
+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. */
+	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 }>;
+	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 };
+}
+
+/** `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;
+	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;