@getuserfeedback/protocol 0.6.1 → 0.7.2

package/src/host/lazy-handle-client.ts

@@ -0,0 +1,207 @@
+type Subscriber<THandleId extends string> = (handleId: THandleId) => void;
+type StageSubscriber<TStage extends string> = (stage: TStage) => void;
+
+type LifecycleStage = "uninitialized" | "ready" | "invalidated";
+type StageMap<TStage extends string> = {
+	uninitialized: TStage;
+	ready: TStage;
+	invalidated: TStage;
+};
+
+const DEFAULT_LIFECYCLE_STAGES: StageMap<LifecycleStage> = {
+	uninitialized: "uninitialized",
+	ready: "ready",
+	invalidated: "invalidated",
+};
+
+export type LazyHandleClient<
+	THandleId extends string,
+	TSettlement,
+	TStage extends string = LifecycleStage,
+> = {
+	runCommand<TPayload>(
+		buildPayload: (handleId: THandleId | undefined) => TPayload,
+		dispatchAndWait: (payload: TPayload) => Promise<TSettlement>,
+	): Promise<TSettlement>;
+	getHandleId(): THandleId | undefined;
+	subscribeHandle(subscriber: Subscriber<THandleId>): () => void;
+	getStage(): TStage;
+	setStage(stage: TStage): void;
+	subscribeStage(subscriber: StageSubscriber<TStage>): () => void;
+	reset(): void;
+	invalidate(): void;
+};
+
+export type CreateLazyHandleClientOptions<
+	THandleId extends string,
+	TSettlement,
+	TStage extends string = LifecycleStage,
+> = {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	stages?: StageMap<TStage>;
+	initialStage?: TStage;
+};
+
+type CreateLazyHandleClientDefaultOptions<
+	THandleId extends string,
+	TSettlement,
+> = {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	initialStage?: LifecycleStage;
+	stages?: undefined;
+};
+
+type CreateLazyHandleClientCustomOptions<
+	THandleId extends string,
+	TSettlement,
+	TStage extends string,
+> = {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	stages: StageMap<TStage>;
+	initialStage?: TStage;
+};
+
+/**
+ * Serializes commands for a lazily initialized handle.
+ * Each command payload is built only when its turn runs, so it always sees
+ * the latest settled handle id from prior commands.
+ */
+const createLazyHandleClientWithStages = <
+	THandleId extends string,
+	TSettlement,
+	TStage extends string,
+>(input: {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	stages: StageMap<TStage>;
+	initialStage?: TStage;
+}): LazyHandleClient<THandleId, TSettlement, TStage> => {
+	let handleId: THandleId | undefined;
+	let tail = Promise.resolve();
+	let isIdle = true;
+	let epoch = 0;
+	const { stages } = input;
+	let stage = input.initialStage ?? stages.uninitialized;
+	const subscribers = new Set<Subscriber<THandleId>>();
+	const stageSubscribers = new Set<StageSubscriber<TStage>>();
+
+	const setStage = (nextStage: TStage): void => {
+		if (stage === nextStage) {
+			return;
+		}
+		if (stage === stages.invalidated && nextStage !== stages.invalidated) {
+			return;
+		}
+		stage = nextStage;
+		stageSubscribers.forEach((subscriber) => {
+			subscriber(nextStage);
+		});
+	};
+
+	const publishHandle = (nextHandleId: THandleId): void => {
+		if (stage === stages.invalidated) {
+			return;
+		}
+		handleId = nextHandleId;
+		setStage(stages.ready);
+		subscribers.forEach((subscriber) => {
+			subscriber(nextHandleId);
+		});
+	};
+
+	const runCommand: LazyHandleClient<
+		THandleId,
+		TSettlement,
+		TStage
+	>["runCommand"] = (buildPayload, dispatchAndWait) => {
+		const execute = async (): Promise<TSettlement> => {
+			if (stage === stages.invalidated) {
+				throw new Error("Handle client is invalidated");
+			}
+			const commandEpoch = epoch;
+			const payload = buildPayload(handleId);
+			const settlement = await dispatchAndWait(payload);
+			const settledHandleId = input.getHandleIdFromSettlement(settlement);
+			if (settledHandleId && commandEpoch === epoch) {
+				publishHandle(settledHandleId);
+			}
+			return settlement;
+		};
+
+		const run = isIdle ? execute() : tail.then(execute, execute);
+		isIdle = false;
+		tail = run.then(
+			() => {
+				isIdle = true;
+			},
+			() => {
+				isIdle = true;
+			},
+		);
+		return run;
+	};
+
+	return {
+		runCommand,
+		getHandleId: () => handleId,
+		subscribeHandle: (subscriber) => {
+			subscribers.add(subscriber);
+			if (handleId) {
+				subscriber(handleId);
+			}
+			return () => {
+				subscribers.delete(subscriber);
+			};
+		},
+		getStage: () => stage,
+		setStage,
+		subscribeStage: (subscriber) => {
+			stageSubscribers.add(subscriber);
+			subscriber(stage);
+			return () => {
+				stageSubscribers.delete(subscriber);
+			};
+		},
+		reset: () => {
+			epoch += 1;
+			handleId = undefined;
+			stage = stages.uninitialized;
+			stageSubscribers.forEach((subscriber) => {
+				subscriber(stage);
+			});
+		},
+		invalidate: () => {
+			epoch += 1;
+			handleId = undefined;
+			setStage(stages.invalidated);
+		},
+	};
+};
+
+export function createLazyHandleClient<THandleId extends string, TSettlement>(
+	options: CreateLazyHandleClientDefaultOptions<THandleId, TSettlement>,
+): LazyHandleClient<THandleId, TSettlement, LifecycleStage>;
+export function createLazyHandleClient<
+	THandleId extends string,
+	TSettlement,
+	TStage extends string,
+>(
+	options: CreateLazyHandleClientCustomOptions<THandleId, TSettlement, TStage>,
+): LazyHandleClient<THandleId, TSettlement, TStage>;
+export function createLazyHandleClient<THandleId extends string, TSettlement>(
+	options:
+		| CreateLazyHandleClientDefaultOptions<THandleId, TSettlement>
+		| CreateLazyHandleClientCustomOptions<THandleId, TSettlement, string>,
+): LazyHandleClient<THandleId, TSettlement, string> {
+	if ("stages" in options && options.stages) {
+		return createLazyHandleClientWithStages({
+			getHandleIdFromSettlement: options.getHandleIdFromSettlement,
+			stages: options.stages,
+			initialStage: options.initialStage,
+		});
+	}
+	return createLazyHandleClientWithStages({
+		getHandleIdFromSettlement: options.getHandleIdFromSettlement,
+		stages: DEFAULT_LIFECYCLE_STAGES,
+		initialStage: options.initialStage,
+	});
+}

package/src/host/request-id.ts

@@ -0,0 +1,3 @@
+import { createUniqueId } from "./unique-id.js";
+
+export const createCommandRequestId = (): string => createUniqueId("req");

package/src/host/sdk-types.ts

@@ -0,0 +1,506 @@
+/**
+ * getuserfeedback widget SDK public API.
+ *
+ * {@link FlowState} lives in `./host-event-contract` (re-exported from the `@getuserfeedback/protocol/host` barrel).
+ */
+
+import type { Scope } from "../scopes.js";
+
+// ── Events and identity ─────────────────────────────────────────────
+
+/**
+ * Identifier types supported by event tracking and identity resolution.
+ *
+ * Use `custom.<name>` for business-specific identifiers such as
+ * `custom.shopifyCustomerId` or `custom.salesforceContactId`.
+ *
+ * @see https://getuserfeedback.com/docs/guides/identity-resolution
+ */
+export type AppEventIdentityType =
+	| "anonymousId"
+	| "userId"
+	| "traits.email"
+	| "traits.phone"
+	| "context.device.id"
+	| "context.device.advertisingId"
+	| "context.device.token"
+	| `custom.${string}`;
+
+/** A single identifier, such as a user ID, anonymous ID, email, or custom external ID. */
+export type AppEventIdentity = {
+	type: AppEventIdentityType;
+	value: string;
+};
+
+/** Page, feature flag, and capability context attached to an event. */
+export type AppEventContext = {
+	page?: {
+		path?: string;
+		referrer?: string;
+		search?: string;
+	};
+	locale?: string;
+	userAgent?: string;
+	flags?: AppEventFlag[] | undefined;
+	capabilities?: AppEventCapability[] | undefined;
+};
+
+/** Supported feature flag value shape. */
+export type AppEventFlagValue =
+	| string
+	| number
+	| boolean
+	| null
+	| AppEventFlagValue[]
+	| { [key: string]: AppEventFlagValue };
+
+/**
+ * Supported event property value shape.
+ *
+ * @see https://getuserfeedback.com/docs/reference/events
+ */
+export type AppEventJsonValue = AppEventFlagValue;
+
+/** Feature flag provider metadata. */
+export type AppEventFlagProvider = {
+	name: string;
+	project?: string | undefined;
+	environment?: string | undefined;
+};
+
+/** Feature flag evaluation context attached to widget initialization or events. */
+export type AppEventFlag = {
+	key: string;
+	target?: string | undefined;
+	value: AppEventFlagValue;
+	variant?: string | undefined;
+	origin?: "runtime_config" | "trigger_context" | "provider_sync" | "api";
+	provider?: AppEventFlagProvider | undefined;
+	status?: string | undefined;
+	reason?: string | undefined;
+	evaluatedAt?: string | undefined;
+};
+
+/** Host capability context attached to widget initialization or events. */
+export type AppEventCapability = {
+	key: string;
+	source?: string | undefined;
+	provider?: AppEventFlagProvider | undefined;
+};
+
+/** Feature flag evaluations accepted by SDK initialization. */
+export type FlagsInput = AppEventFlag[] | Record<string, AppEventFlagValue>;
+
+/** Host capabilities accepted by SDK initialization. */
+export type CapabilitiesInput = Array<string | AppEventCapability>;
+
+/** Optional fields shared by event payloads. */
+export type AppEventBase = {
+	traits?: Record<string, unknown> | undefined;
+	identities?: AppEventIdentity[] | undefined;
+	context?: AppEventContext | undefined;
+	messageId?: string | undefined;
+	timestamp?: number | undefined;
+};
+
+/** Reference to a specific survey or flow. */
+export type AppEventSurveyReference = {
+	surveyId: string;
+};
+
+/** Event payload emitted when a flow is shown. */
+export type FlowViewedPayload = AppEventBase & {
+	origin?: "system" | undefined;
+	event: "Flow Viewed";
+	references: AppEventSurveyReference;
+};
+
+/** Event payload emitted when a user dismisses a flow. */
+export type FlowDismissedPayload = AppEventBase & {
+	origin?: "system" | undefined;
+	event: "Flow Dismissed";
+	references: AppEventSurveyReference;
+};
+
+/**
+ * Event payload sent with `client.track()`.
+ *
+ * @see https://getuserfeedback.com/docs/reference/events
+ */
+export type CustomerTrackPayload = AppEventBase & {
+	origin: "customer";
+	event: string;
+	properties?: Record<string, AppEventJsonValue> | undefined;
+};
+
+/**
+ * Event payload union. Use `origin` as the discriminator when handling the
+ * union directly.
+ */
+export type AppEventPayload =
+	| FlowViewedPayload
+	| FlowDismissedPayload
+	| CustomerTrackPayload;
+
+// ── Client metadata ─────────────────────────────────────────────────
+
+/** How the widget was loaded, such as SDK, GTM, Segment, or a custom loader. */
+export type ClientMetaLoader =
+	| "sdk"
+	| "gtm"
+	| "segment"
+	| "rudderstack"
+	| "tealium"
+	| "custom";
+
+/** Delivery method for the widget script. */
+export type ClientMetaTransport =
+	| "script-tag"
+	| "esm"
+	| "loader"
+	| "tag-manager"
+	| "snippet";
+
+/** Detected or configured front-end framework. */
+export type ClientMetaRuntimeFramework = "next" | "vite" | "webpack" | "plain";
+
+/** Runtime environment (browser or edge). */
+export type ClientMetaRuntimeEnv = "browser" | "edge";
+
+/** Metadata about the client integration, used for diagnostics and support. */
+export type ClientMeta = {
+	loader: ClientMetaLoader;
+	clientName?: string | undefined;
+	clientVersion?: string | undefined;
+	integrator?:
+		| {
+				name?: string | undefined;
+				version?: string | undefined;
+		  }
+		| undefined;
+	transport?: ClientMetaTransport | undefined;
+	runtime?:
+		| {
+				framework?: ClientMetaRuntimeFramework | undefined;
+				runtime?: ClientMetaRuntimeEnv | undefined;
+		  }
+		| undefined;
+	notes?: string | undefined;
+};
+
+export type RuntimeEndpoints = {
+	apiUrl?: string | undefined;
+	coreUrl?: string | undefined;
+};
+
+/** A single response metadata tag value preserved with a submitted response. */
+export type ResponseMetadataTagValue = string | string[];
+
+/** Optional metadata tags the host can attach to a widget flow run. */
+export type ResponseMetadataInput = {
+	tags?: Record<string, ResponseMetadataTagValue> | undefined;
+};
+
+// ── Configuration (color scheme, consent, auth) ─────────────────────────────
+
+/**
+ * Use host attributes to auto-detect the color scheme ("light" by default). The widget observes these attributes on body and html elements,
+ *
+ * class="dark" or data-theme="dark" on html or body elements will set the widget to dark mode.
+ *
+ * class="light" or data-theme="light" will set the widget to light mode.
+ *
+ * class="system" or data-theme="system" will set the widget to follow the user's OS/browser preference (prefers-color-scheme).
+ */
+export type ColorSchemeAutoDetect = {
+	/** List of host attribute names (html or body) to observe for color scheme.
+	 *
+	 * Default: ["class", "data-theme"]
+	 */
+	autoDetectColorScheme: string[];
+};
+
+/**
+ * Color scheme: either auto-detect from host html and body attributes (default) or provide an explicit value.
+ * - { autoDetectColorScheme: ["class", "data-theme"] }
+ * - "light" | "dark" | "system"
+ */
+export type ColorSchemeConfig =
+	| ColorSchemeAutoDetect
+	| "light"
+	| "dark"
+	| "system";
+
+/** Whether telemetry is enabled. */
+export type TelemetryConfig = {
+	enabled?: boolean | undefined;
+};
+
+/** When true, prints debug logs to console. Narrow down with a namespace string/array eg. `["loader", "handshake"]`. Default `false`. */
+export type DebugConfig = boolean | string | string[];
+
+/** Status of a consent decision (pending, granted, denied, revoked). */
+export type ConsentStatus = "pending" | "granted" | "denied" | "revoked";
+
+/**
+ * Supported consent scope identifiers for explicit allow-list grants (full CMP-aligned set).
+ * Alias for {@link Scope}; kept for backward-compatible imports.
+ */
+export type GrantScope = Scope;
+
+/** Consent configuration. Use a single decision for all scopes, or provide an explicit allow-list of granted scopes. */
+export type ConsentConfig = ConsentStatus | Scope[];
+
+/** Auth configuration, such as a JWT for authenticated flows. */
+export type AuthConfig = {
+	jwt?: { token: string } | null | undefined;
+};
+
+/**
+ * Runtime configuration updates accepted by `client.configure()`.
+ *
+ * @see https://getuserfeedback.com/docs/security-and-privacy/compliance-and-consent
+ */
+export type ConfigureOptions = {
+	colorScheme?: ColorSchemeConfig | undefined;
+	consent?: ConsentConfig | undefined;
+	auth?: AuthConfig | undefined;
+};
+
+/** @internal Options when initializing the widget: API key, color scheme, disableTelemetry, enableDebug, defaultConsent, capabilities, and optional host targeting context. */
+export type InitOptions = {
+	apiKey: string;
+	colorScheme?: ColorSchemeConfig | undefined;
+	disableTelemetry?: boolean | undefined;
+	enableDebug?: DebugConfig | undefined;
+	defaultConsent?: ConsentConfig | undefined;
+	clientMeta?: ClientMeta | undefined;
+	capabilities?: string[] | undefined;
+	flags?: AppEventFlag[] | undefined;
+	hostCapabilities?: AppEventCapability[] | undefined;
+	runtimeEndpoints?: RuntimeEndpoints | undefined;
+};
+
+export type ClientOptions = {
+	/** Your project API key. */
+	apiKey: string;
+	/** Color scheme config: host-driven (loader observes attributes) or explicit. */
+	colorScheme?: ColorSchemeConfig | undefined;
+	/**
+	 * Initial consent state.
+	 *
+	 * Default: `granted` (all scopes).
+	 *
+	 * Accepts either a single decision (`granted` | `denied` | `pending` | `revoked`)
+	 * or an explicit allow-list of additional granted scopes (`Scope[]`).
+	 *
+	 * For strict privacy guarantees, use `pending` at init time and later call `client.configure({ consent })` after
+	 * the user makes a consent choice via your CMP or UI.
+	 *
+	 * In array form, listed scopes are granted and all other non-essential scopes are denied.
+	 *
+	 * Essential baseline scopes are always granted for core widget operation and cannot be denied:
+	 * - `functionality.storage`
+	 * - `security.storage`
+	 *
+	 * @see https://getuserfeedback.com/docs/security-and-privacy/compliance-and-consent
+	 */
+	defaultConsent?: ConsentConfig | undefined;
+	/** When true, prints debug logs to console. Narrow down with a namespace string/array eg. ```["loader", "handshake"]```. Default `false`.
+	 */
+	enableDebug?: DebugConfig | undefined;
+	/** When true, the widget does not load automatically; call `client.load()` when ready. Default `false` */
+	disableAutoLoad?: boolean;
+	/** Disable anonymous widget telemetry.
+	 *
+	 * When `true`, telemetry is not sent.
+	 *
+	 * This flag does not disable user targeting and reporting analytics. It's used (by us) for performance monitoring and error tracking.
+	 *
+	 * Included telemetry data when enabled: apiKey, ephemeral one-time session id,
+	 * execution flow, event timestamps, and page origin (domain name).
+	 *
+	 * Excluded by default: user identity and detailed page fields (path/referrer/search).
+	 */
+	disableTelemetry?: boolean | undefined;
+	/** Feature flag evaluations collected with widget initialization. */
+	flags?: FlagsInput | undefined;
+	/** Host capabilities collected with widget initialization. */
+	capabilities?: CapabilitiesInput | undefined;
+	_loaderUrl?: string | undefined;
+	_coreUrl?: string | undefined;
+	_apiUrl?: string | undefined;
+};
+
+// ── Flow and widget actions (used by Client methods) ───────────────────
+
+/** Open a flow with a given instance. Omit flowHandleId for first open; core returns it in settlement. */
+export type OpenCommandPayload = {
+	kind: "open";
+	flowId: string;
+	flowHandleId?: string | undefined;
+	container?: HTMLElement | null | undefined;
+	/** Optional metadata tags to persist with the eventual response submission. */
+	metadata?: ResponseMetadataInput | undefined;
+	/**
+	 * When `true`, the flow view does not show a close button.
+	 * Useful for mobile or embedded contexts where the host handles dismissal (e.g. via a drawer or back gesture).
+	 */
+	hideCloseButton?: boolean | undefined;
+};
+
+/** Prefetch a flow. Omit flowHandleId for first prefetch; core returns it in settlement. */
+export type PrefetchCommandPayload = {
+	kind: "prefetch";
+	flowId: string;
+	flowHandleId?: string | undefined;
+};
+
+/** Prerender a flow. Omit flowHandleId for first prerender; core returns it in settlement. */
+export type PrerenderCommandPayload = {
+	kind: "prerender";
+	flowId: string;
+	flowHandleId?: string | undefined;
+	/**
+	 * When `true`, the prerendered view does not show a close button.
+	 */
+	hideCloseButton?: boolean | undefined;
+};
+
+/** Identify with traits only (`client.identify(traits)`). */
+export type IdentifyTraitsOnlyCommandPayload = {
+	kind: "identify";
+	traits: Record<string, unknown>;
+};
+
+/** Identify with userId and optional traits (`client.identify(userId, traits?)`). */
+export type IdentifyUserCommandPayload = {
+	kind: "identify";
+	userId: string;
+	traits?: Record<string, unknown> | undefined;
+};
+
+/** Identify command payload: either traits-only or userId+traits shape. */
+export type IdentifyCommandPayload =
+	| IdentifyTraitsOnlyCommandPayload
+	| IdentifyUserCommandPayload;
+
+/**
+ * Command payload for `client.track()`.
+ *
+ * @see https://getuserfeedback.com/docs/reference/events
+ */
+export type TrackCommandPayload = AppEventBase & {
+	kind: "track";
+	origin: "customer";
+	event: string;
+	properties?: Record<string, AppEventJsonValue> | undefined;
+};
+
+/** Attach or detach a resolved flow handle from a host container. */
+export type SetContainerCommandPayload = {
+	kind: "setContainer";
+	flowHandleId: string;
+	container: HTMLElement | null;
+};
+
+/** Default container behavior for flows in an instance. */
+export type ContainerPolicy =
+	| {
+			kind: "floating";
+	  }
+	| {
+			kind: "hostContainer";
+			host: HTMLElement | null;
+			sharing: "shared" | "perFlowRun";
+	  };
+
+/** Set the instance-level default container policy. */
+export type SetDefaultContainerPolicyCommandPayload = {
+	kind: "setDefaultContainerPolicy";
+	policy: ContainerPolicy;
+};
+
+/** Update color scheme, consent, and auth. */
+export type ConfigureCommandPayload = {
+	kind: "configure";
+	opts: ConfigureOptions;
+};
+
+/** Initialize the widget with options. */
+export type InitCommandPayload = {
+	kind: "init";
+	opts: InitOptions;
+};
+
+/** Close a flow. */
+export type CloseCommandPayload = {
+	kind: "close";
+	flowHandleId?: string | undefined;
+};
+
+/** Reset widget state. */
+export type ResetCommandPayload = {
+	kind: "reset";
+};
+
+/** Union of widget action payloads such as open, prefetch, identify, configure, and track. */
+export type PublicCommandPayload =
+	| OpenCommandPayload
+	| PrefetchCommandPayload
+	| PrerenderCommandPayload
+	| IdentifyCommandPayload
+	| SetContainerCommandPayload
+	| SetDefaultContainerPolicyCommandPayload
+	| ConfigureCommandPayload
+	| InitCommandPayload
+	| CloseCommandPayload
+	| ResetCommandPayload
+	| TrackCommandPayload;
+
+/** Input for a single widget action; same shape as {@link PublicCommandPayload}. */
+export type Command = PublicCommandPayload;
+
+/** Wrapper for a widget action (version, request id, idempotency key, optional client metadata, and the action payload). */
+export type CommandEnvelope = {
+	version: "1";
+	instanceId?: string | undefined;
+	requestId: string;
+	idempotencyKey: string;
+	clientMeta?: ClientMeta | undefined;
+	command: PublicCommandPayload;
+};
+
+// ── Telemetry (use("beforeSend")) ─────────────────────────────────────
+
+/** Identity kind for telemetry events; same as {@link AppEventIdentityType}. */
+export type TelemetryIdentityType = AppEventIdentityType;
+
+/**
+ * Event passed to the `beforeSend` hook in {@link Client.use}.
+ * When `debug` is true, identities and full page context are included; when false, no identities and page is origin-only.
+ *
+ * TODO(migration): Rename this SDK-facing type to WidgetTelemetryEvent in the
+ * same change that updates SDK imports, so the generic TelemetryEvent name can
+ * retire here without colliding with shared telemetry.
+ *   [from=TelemetryEvent-widget-surface] [to=WidgetTelemetryEvent] [scope=slice] [priority=low]
+ */
+export type TelemetryEvent = {
+	type: string;
+	timestamp: number;
+	apiKey: string;
+	/** When true, identities and full page context are present; when false, no identities and page.origin only. */
+	debug: boolean;
+	identities: Array<{ type: TelemetryIdentityType; value: string }>;
+	context: {
+		page: {
+			path?: string | null | undefined;
+			referrer?: string | null | undefined;
+			search?: string | null | undefined;
+			origin?: string | null | undefined;
+		};
+		widgetVersion: string;
+		clientMeta?: ClientMeta | undefined;
+	};
+	properties?: Record<string, unknown> | undefined;
+};