@getuserfeedback/protocol 0.6.1 → 0.8.0

package/src/host/command-dispatch.ts

@@ -0,0 +1,59 @@
+import { createCommandEnvelope } from "./command-envelope.js";
+import { waitForCommandSettlement } from "./command-settlement.js";
+import type { CommandEnvelope, PublicCommandPayload } from "./sdk-types.js";
+
+/**
+ * A command input: the pure payload with `kind` and command-specific fields.
+ * Distributes over the PublicCommandPayload union so discriminant
+ * narrowing is preserved (e.g. `{ kind: "open", flowId }` type-checks).
+ */
+export type CommandInput = PublicCommandPayload extends infer C
+	? C extends PublicCommandPayload
+		? C
+		: never
+	: never;
+
+type DispatchOptions = {
+	idempotencyKey?: string;
+};
+
+/**
+ * Creates a dispatch function that wraps a command payload in an envelope,
+ * pushes it into the queue, and returns a promise that settles when the
+ * runtime acknowledges it.
+ *
+ * Request IDs are generated automatically.
+ *
+ * @example
+ * ```ts
+ * const dispatch = createCommandDispatch((env) => queue.push(env));
+ * await dispatch({ kind: "open", flowId: "f1", flowHandleId: "h1" });
+ * ```
+ */
+export const createCommandDispatch = (
+	push: (envelope: CommandEnvelope) => void,
+): ((input: CommandInput, options?: DispatchOptions) => Promise<void>) => {
+	return async (
+		input: CommandInput,
+		options?: DispatchOptions,
+	): Promise<void> => {
+		const envelope: CommandEnvelope = createCommandEnvelope({
+			command: input,
+			idempotencyKey:
+				resolveIdempotencyKey(options?.idempotencyKey) ?? undefined,
+		});
+		push(envelope);
+		await waitForCommandSettlement({ requestId: envelope.requestId });
+	};
+};
+
+const resolveIdempotencyKey = (value?: string): string | null => {
+	if (value === undefined) {
+		return null;
+	}
+	const idempotencyKey = value.trim();
+	if (!idempotencyKey) {
+		throw new Error("idempotencyKey must be a non-empty string");
+	}
+	return idempotencyKey;
+};

package/src/host/command-envelope.ts

@@ -0,0 +1,41 @@
+import { createCommandRequestId } from "./request-id.js";
+import type {
+	ClientMeta,
+	CommandEnvelope,
+	PublicCommandPayload,
+} from "./sdk-types.js";
+
+export type CreateCommandEnvelopeInput = {
+	command: PublicCommandPayload;
+	requestId?: string | undefined;
+	idempotencyKey?: string | undefined;
+	instanceId?: string | undefined;
+	clientMeta?: ClientMeta | undefined;
+};
+
+const normalizeOptionalString = (value?: string): string | undefined => {
+	if (value === undefined) {
+		return undefined;
+	}
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : undefined;
+};
+
+export const createCommandEnvelope = (
+	input: CreateCommandEnvelopeInput,
+): CommandEnvelope => {
+	const requestId =
+		normalizeOptionalString(input.requestId) ?? createCommandRequestId();
+	const idempotencyKey =
+		normalizeOptionalString(input.idempotencyKey) ?? requestId;
+	const instanceId = normalizeOptionalString(input.instanceId);
+
+	return {
+		version: "1",
+		command: input.command,
+		requestId,
+		idempotencyKey,
+		...(instanceId !== undefined ? { instanceId } : {}),
+		...(input.clientMeta !== undefined ? { clientMeta: input.clientMeta } : {}),
+	};
+};

package/src/host/command-settlement.ts

@@ -0,0 +1,121 @@
+import { HOST_EVENT_KEYS, toHostEventName } from "./constants.js";
+import {
+	type CommandSettledDetail,
+	isCommandSettledDetail,
+} from "./host-event-contract.js";
+
+type WaitForCommandSettlementInput = {
+	requestId: string;
+	windowRef?: Window;
+	timeoutMs?: number;
+};
+
+const DEFAULT_SETTLEMENT_TIMEOUT_MS = 30_000;
+export const COMMAND_SETTLEMENT_TIMEOUT_CODE =
+	"COMMAND_SETTLEMENT_TIMEOUT" as const;
+
+export class CommandSettlementError extends Error {
+	readonly code?: string;
+	readonly requestId: string;
+	readonly kind: string;
+	readonly instanceId: string | null;
+
+	constructor(input: {
+		requestId: string;
+		kind: string;
+		instanceId: string | null;
+		message: string;
+		code?: string;
+	}) {
+		super(input.message);
+		this.name = "CommandSettlementError";
+		this.requestId = input.requestId;
+		this.kind = input.kind;
+		this.instanceId = input.instanceId;
+		if (input.code) {
+			this.code = input.code;
+		}
+	}
+}
+
+type CommandSettledFailureDetail = Extract<CommandSettledDetail, { ok: false }>;
+
+export const toCommandSettlementError = (
+	detail: CommandSettledFailureDetail,
+): CommandSettlementError => {
+	return new CommandSettlementError({
+		requestId: detail.requestId,
+		kind: detail.kind,
+		instanceId: detail.instanceId,
+		message:
+			detail.error.message ??
+			`Command ${detail.kind} failed without an error payload`,
+		code: detail.error.code,
+	});
+};
+
+export class CommandSettlementTimeoutError extends Error {
+	readonly code = COMMAND_SETTLEMENT_TIMEOUT_CODE;
+	readonly requestId: string;
+
+	constructor(requestId: string) {
+		super(`Timed out waiting for command settlement: ${requestId}`);
+		this.name = "CommandSettlementTimeoutError";
+		this.requestId = requestId;
+	}
+}
+
+const eventHasDetail = (event: Event): event is Event & { detail: unknown } =>
+	typeof event === "object" && event !== null && "detail" in event;
+
+export const waitForCommandSettlement = (
+	input: WaitForCommandSettlementInput,
+): Promise<CommandSettledDetail> => {
+	const requestId = input.requestId;
+	if (!requestId) {
+		return Promise.reject(new Error("requestId must be a non-empty string"));
+	}
+	const targetWindow =
+		input.windowRef ?? (typeof window === "undefined" ? undefined : window);
+	if (!targetWindow) {
+		return Promise.reject(
+			new Error("Cannot await command settlement without window"),
+		);
+	}
+	const eventName = toHostEventName(HOST_EVENT_KEYS.INSTANCE_COMMAND_SETTLED);
+	const timeoutMs = Math.max(
+		0,
+		input.timeoutMs ?? DEFAULT_SETTLEMENT_TIMEOUT_MS,
+	);
+	return new Promise<CommandSettledDetail>((resolve, reject) => {
+		const cleanup = (): void => {
+			if (typeof targetWindow.removeEventListener === "function") {
+				targetWindow.removeEventListener(eventName, handleEvent);
+			}
+		};
+
+		const timeoutId = setTimeout(() => {
+			cleanup();
+			reject(new CommandSettlementTimeoutError(requestId));
+		}, timeoutMs);
+
+		const handleEvent = (event: Event): void => {
+			if (!eventHasDetail(event)) {
+				return;
+			}
+			const raw = event.detail;
+			if (!isCommandSettledDetail(raw) || raw.requestId !== requestId) {
+				return;
+			}
+			const detail = raw;
+			cleanup();
+			clearTimeout(timeoutId);
+			if (detail.ok) {
+				resolve(detail);
+				return;
+			}
+			reject(toCommandSettlementError(detail));
+		};
+		targetWindow.addEventListener(eventName, handleEvent);
+	});
+};

package/src/host/constants.ts

@@ -0,0 +1,103 @@
+import type { PublicCommandPayload } from "./sdk-types.js";
+
+export const TELEMETRY_EVENTS = {
+	INSTANCE_READY: "instance_ready",
+	VIEW_DISPLAYED: "view_displayed",
+	VIEW_CLOSED: "view_closed",
+	FLOW_DISPLAYED: "flow_displayed",
+	FLOW_CLOSED: "flow_closed",
+} as const;
+
+export type TelemetryEventName =
+	(typeof TELEMETRY_EVENTS)[keyof typeof TELEMETRY_EVENTS];
+
+// Data attribute used to anchor widget styles & root element. Shared so build
+// scripts, runtime code and tests stay in sync.
+export const WIDGET_SELECTOR = "[data-gx-widget]" as const;
+
+export const PARENT_ORIGIN_PARAM = "gx_parent_origin" as const;
+
+// Host event names (DOM events emitted by widget for external consumption)
+// Uses prefix "getuserfeedback:" for namespacing
+export const HOST_EVENT_PREFIX = "getuserfeedback:" as const;
+
+export const HOST_EVENT_KEYS = {
+	INSTANCE_FLOW_STATE_CHANGED: "instance:flow:state-changed",
+	INSTANCE_FLOW_STATE_CHANGED_INSTANCE: "instance:flow:state-changed:instance",
+	INSTANCE_COMMAND_SETTLED: "instance:command:settled",
+	INSTANCE_HANDLE_INVALIDATED: "instance:handle:invalidated",
+	INSTANCE_OPEN_REQUESTED: "instance:open:requested",
+	INSTANCE_COMMAND_UNSUPPORTED: "instance:command:unsupported",
+	INSTANCE_READY: "instance:ready",
+	INSTANCE_BRIDGE_MOUNTED: "instance:bridge:mounted",
+	INSTANCE_BRIDGE_UNMOUNTED: "instance:bridge:unmounted",
+	INSTANCE_IFRAME_READY: "instance:iframe:ready",
+	INSTANCE_ERROR: "instance:error",
+	INSTANCE_APP_EVENT: "instance:app-event",
+} as const;
+
+type SdkCapabilityCommandKind = Exclude<PublicCommandPayload["kind"], "init">;
+
+const SDK_COMMAND_CAPABILITY_BY_KIND = {
+	configure: "gx.command.configure.v1",
+	open: "gx.command.open.v1",
+	prefetch: "gx.command.prefetch.v1",
+	prerender: "gx.command.prerender.v1",
+	identify: "gx.command.identify.v1",
+	setContainer: "gx.command.setContainer.v1",
+	close: "gx.command.close.v1",
+	reset: "gx.command.reset.v1",
+	setDefaultContainerPolicy: "gx.command.setDefaultContainerPolicy.v1",
+	track: "gx.command.track.v1",
+} as const satisfies Record<
+	SdkCapabilityCommandKind,
+	`gx.command.${string}.v${number}`
+>;
+
+const SDK_COMMAND_CAPABILITIES = [
+	SDK_COMMAND_CAPABILITY_BY_KIND.configure,
+	SDK_COMMAND_CAPABILITY_BY_KIND.open,
+	SDK_COMMAND_CAPABILITY_BY_KIND.prefetch,
+	SDK_COMMAND_CAPABILITY_BY_KIND.prerender,
+	SDK_COMMAND_CAPABILITY_BY_KIND.identify,
+	SDK_COMMAND_CAPABILITY_BY_KIND.setContainer,
+	SDK_COMMAND_CAPABILITY_BY_KIND.close,
+	SDK_COMMAND_CAPABILITY_BY_KIND.reset,
+	SDK_COMMAND_CAPABILITY_BY_KIND.setDefaultContainerPolicy,
+	SDK_COMMAND_CAPABILITY_BY_KIND.track,
+] as const;
+
+type SdkCommandCapability =
+	(typeof SDK_COMMAND_CAPABILITY_BY_KIND)[keyof typeof SDK_COMMAND_CAPABILITY_BY_KIND];
+type _AssertAllCommandCapabilitiesAreAnnounced =
+	Exclude<
+		SdkCommandCapability,
+		(typeof SDK_COMMAND_CAPABILITIES)[number]
+	> extends never
+		? true
+		: never;
+type _AssertNoUnknownCommandCapabilities =
+	Exclude<
+		(typeof SDK_COMMAND_CAPABILITIES)[number],
+		SdkCommandCapability
+	> extends never
+		? true
+		: never;
+
+/**
+ * Stable capability tokens announced by the browser SDK during init.
+ * These are versioned and namespaced to support forward-compatible negotiation.
+ */
+export const SDK_PROTOCOL_CAPABILITIES = [
+	"gx.protocol.public.v1",
+	...SDK_COMMAND_CAPABILITIES,
+] as const;
+
+export type SdkProtocolCapability = (typeof SDK_PROTOCOL_CAPABILITIES)[number];
+
+export const LOADER_RUNTIME_GLOBAL_KEY = "__getuserfeedback_runtime" as const;
+export const LOADER_RUNTIME_PROTOCOL_VERSION = "v2" as const;
+
+// Helper to construct full event name with prefix
+export const toHostEventName = (key: string): string =>
+	`${HOST_EVENT_PREFIX}${key}`;

package/src/host/external-id-argument-guards.ts

@@ -0,0 +1,57 @@
+type ExternalIdArgumentCommandName = "identify" | "track";
+type ExternalIdArgumentValueName = "traits" | "properties";
+
+const isAmbiguousExternalIdsArgument = (value: unknown): boolean => {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		return false;
+	}
+
+	const entries = Object.entries(value);
+	const externalIds = entries[0]?.[1];
+	return (
+		entries.length === 1 &&
+		entries[0]?.[0] === "externalIds" &&
+		Array.isArray(externalIds) &&
+		externalIds.length > 0 &&
+		externalIds.every(isSegmentExternalIdLike)
+	);
+};
+
+const isSegmentExternalIdLike = (
+	value: unknown,
+): value is {
+	id: string;
+	type: string;
+	collection: "users";
+	encoding: "none";
+} => {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		return false;
+	}
+	return (
+		typeof Reflect.get(value, "id") === "string" &&
+		typeof Reflect.get(value, "type") === "string" &&
+		Reflect.get(value, "collection") === "users" &&
+		Reflect.get(value, "encoding") === "none"
+	);
+};
+
+export const assertNoAmbiguousExternalIdsArgument = ({
+	argument,
+	options,
+	commandName,
+	valueArgumentName,
+}: {
+	argument: unknown;
+	options: unknown;
+	commandName: ExternalIdArgumentCommandName;
+	valueArgumentName: ExternalIdArgumentValueName;
+}): void => {
+	if (options !== undefined || !isAmbiguousExternalIdsArgument(argument)) {
+		return;
+	}
+
+	throw new Error(
+		`${commandName} received externalIds in the ${valueArgumentName} argument. Pass undefined for ${valueArgumentName} and provide externalIds as options instead.`,
+	);
+};

package/src/host/host-event-contract.ts

@@ -0,0 +1,277 @@
+/**
+ * Types and type guards for flow state and lifecycle events.
+ */
+
+/** Current state of the flow: whether it is open, opening, and its dimensions (if known). */
+export interface FlowState {
+	/** True when the flow is visible. */
+	isOpen: boolean;
+	/**
+	 * True after an open request while the flow is not visible yet. Background
+	 * prefetching or prerendering without open intent must not set this.
+	 */
+	isLoading: boolean;
+	/** Flow width in pixels when known. */
+	width?: number;
+	/** Flow height in pixels when known. */
+	height?: number;
+}
+
+export interface FlowStateChangedDetail extends FlowState {
+	instanceId: string;
+	flowHandleId: string;
+}
+
+export interface InstanceFlowStateChangedDetail extends FlowState {
+	instanceId: string;
+}
+
+export interface OpenRequestedDetail {
+	instanceId: string;
+	source: "command" | "targeting";
+	flowId: string;
+	flowHandleId?: string;
+	hideCloseButton?: boolean;
+}
+
+export const HANDLE_INVALIDATED_REASON_CODES: readonly [
+	"RESET",
+	"CLOSED",
+	"STALE_HANDLE",
+	"OWNERSHIP_CONFLICT",
+	"OWNER_DISPOSED",
+	"UPSTREAM_INVALIDATED",
+	"INTERNAL",
+] = [
+	"RESET",
+	"CLOSED",
+	"STALE_HANDLE",
+	"OWNERSHIP_CONFLICT",
+	"OWNER_DISPOSED",
+	"UPSTREAM_INVALIDATED",
+	"INTERNAL",
+];
+
+export type HandleInvalidatedReasonCode =
+	(typeof HANDLE_INVALIDATED_REASON_CODES)[number];
+
+export const HANDLE_INVALIDATED_SOURCES: readonly ["loader", "core"] = [
+	"loader",
+	"core",
+];
+
+export type HandleInvalidatedSource =
+	(typeof HANDLE_INVALIDATED_SOURCES)[number];
+
+/** Generic handle lifecycle event emitted when a previously issued handle is invalidated upstream. */
+export interface HandleInvalidatedDetail {
+	instanceId: string;
+	handleKind: string;
+	handleId: string;
+	reasonCode: HandleInvalidatedReasonCode;
+	reasonMessage?: string;
+	relatedRequestId?: string;
+	source: HandleInvalidatedSource;
+	at: number;
+}
+
+const isNonEmptyString = (v: unknown): v is string =>
+	typeof v === "string" && v.trim().length > 0;
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+	typeof v === "object" && v !== null;
+
+const HANDLE_INVALIDATED_REASON_CODE_SET: ReadonlySet<string> = new Set(
+	HANDLE_INVALIDATED_REASON_CODES,
+);
+
+const isHandleInvalidatedReasonCode = (
+	v: unknown,
+): v is HandleInvalidatedReasonCode =>
+	typeof v === "string" && HANDLE_INVALIDATED_REASON_CODE_SET.has(v);
+
+const HANDLE_INVALIDATED_SOURCE_SET: ReadonlySet<string> = new Set(
+	HANDLE_INVALIDATED_SOURCES,
+);
+
+const isHandleInvalidatedSource = (v: unknown): v is HandleInvalidatedSource =>
+	typeof v === "string" && HANDLE_INVALIDATED_SOURCE_SET.has(v);
+
+export function isFlowStateChangedDetail(
+	detail: unknown,
+): detail is FlowStateChangedDetail {
+	if (!isRecord(detail)) return false;
+	const { instanceId, isOpen, isLoading, width, height, flowHandleId } = detail;
+	return (
+		isNonEmptyString(instanceId) &&
+		typeof isOpen === "boolean" &&
+		typeof isLoading === "boolean" &&
+		(typeof width === "undefined" || typeof width === "number") &&
+		(typeof height === "undefined" || typeof height === "number") &&
+		isNonEmptyString(flowHandleId)
+	);
+}
+
+export function isInstanceFlowStateChangedDetail(
+	detail: unknown,
+): detail is InstanceFlowStateChangedDetail {
+	if (!isRecord(detail)) return false;
+	const { instanceId, isOpen, isLoading, width, height } = detail;
+	return (
+		isNonEmptyString(instanceId) &&
+		typeof isOpen === "boolean" &&
+		typeof isLoading === "boolean" &&
+		(typeof width === "undefined" || typeof width === "number") &&
+		(typeof height === "undefined" || typeof height === "number")
+	);
+}
+
+export function isOpenRequestedDetail(
+	detail: unknown,
+): detail is OpenRequestedDetail {
+	if (!isRecord(detail)) return false;
+	const { instanceId, source, flowId, flowHandleId, hideCloseButton } = detail;
+	return (
+		isNonEmptyString(instanceId) &&
+		(source === "command" || source === "targeting") &&
+		isNonEmptyString(flowId) &&
+		(typeof flowHandleId === "undefined" || isNonEmptyString(flowHandleId)) &&
+		(typeof hideCloseButton === "undefined" ||
+			typeof hideCloseButton === "boolean")
+	);
+}
+
+export function isHandleInvalidatedDetail(
+	detail: unknown,
+): detail is HandleInvalidatedDetail {
+	if (!isRecord(detail)) return false;
+	const {
+		instanceId,
+		handleKind,
+		handleId,
+		reasonCode,
+		reasonMessage,
+		relatedRequestId,
+		source,
+		at,
+	} = detail;
+	return (
+		isNonEmptyString(instanceId) &&
+		isNonEmptyString(handleKind) &&
+		isNonEmptyString(handleId) &&
+		isHandleInvalidatedReasonCode(reasonCode) &&
+		(typeof reasonMessage === "undefined" ||
+			typeof reasonMessage === "string") &&
+		(typeof relatedRequestId === "undefined" ||
+			isNonEmptyString(relatedRequestId)) &&
+		isHandleInvalidatedSource(source) &&
+		typeof at === "number" &&
+		Number.isFinite(at)
+	);
+}
+
+export interface CommandSettledSuccessDetail {
+	requestId: string;
+	instanceId: string | null;
+	kind: string;
+	ok: true;
+	result?: unknown;
+}
+
+export interface CommandSettledFailureDetail {
+	requestId: string;
+	instanceId: string | null;
+	kind: string;
+	ok: false;
+	error: { message: string; code?: string };
+}
+
+export type CommandSettledDetail =
+	| CommandSettledSuccessDetail
+	| CommandSettledFailureDetail;
+
+export function isCommandSettledDetail(
+	detail: unknown,
+): detail is CommandSettledDetail {
+	if (!isRecord(detail)) return false;
+	const { requestId, instanceId, kind, ok, error } = detail;
+	if (
+		!isNonEmptyString(requestId) ||
+		(typeof instanceId !== "string" && instanceId !== null) ||
+		typeof kind !== "string" ||
+		typeof ok !== "boolean"
+	) {
+		return false;
+	}
+	if (ok === true) {
+		return true;
+	}
+	if (ok === false && isRecord(error)) {
+		return typeof error.message === "string";
+	}
+	return false;
+}
+
+/** Result of extracting a flow handle from a successful open/prerender/prefetch settlement. */
+export type FlowHandleFromSettlement = {
+	flowHandleId: string;
+	flowRunId?: string;
+};
+
+/**
+ * Host-facing handle result: same shape as FlowHandleFromSettlement.
+ * Used when projecting instance:command:settled so the SDK receives flowHandleId (and flowRunId when present).
+ */
+export type HostHandleSettlementResult = FlowHandleFromSettlement;
+
+/**
+ * Return the host-facing handle result for a command settlement, or null.
+ * Use in the loader when projecting instance:command:settled; keeps the host contract in one place (no zod).
+ */
+export function getHostHandleResultFromSettlement(detail: {
+	ok: boolean;
+	kind: string;
+	result?: unknown;
+}): HostHandleSettlementResult | null {
+	return getFlowHandleFromSettlementDetail(detail);
+}
+
+const HANDLE_RETURNING_KINDS: readonly ["open", "prerender", "prefetch"] = [
+	"open",
+	"prerender",
+	"prefetch",
+];
+type HandleReturningKind = (typeof HANDLE_RETURNING_KINDS)[number];
+const HANDLE_RETURNING_KIND_SET: ReadonlySet<string> = new Set(
+	HANDLE_RETURNING_KINDS,
+);
+const isHandleReturningKind = (kind: string): kind is HandleReturningKind =>
+	HANDLE_RETURNING_KIND_SET.has(kind);
+
+/**
+ * Extract flow handle from a successful command settlement when the command
+ * is one that can return a handle (open, prerender, prefetch). Uses plain
+ * checks only (no Zod). Returns null if detail is not ok, kind is not one of
+ * those, or result does not contain a non-empty flowHandleId.
+ */
+export function getFlowHandleFromSettlementDetail(detail: {
+	ok: boolean;
+	kind: string;
+	result?: unknown;
+}): FlowHandleFromSettlement | null {
+	if (!detail.ok || !isHandleReturningKind(detail.kind)) {
+		return null;
+	}
+	const result = detail.result;
+	if (!isRecord(result)) {
+		return null;
+	}
+	const { flowHandleId, flowRunId } = result;
+	if (!isNonEmptyString(flowHandleId)) {
+		return null;
+	}
+	return {
+		flowHandleId,
+		...(isNonEmptyString(flowRunId) && { flowRunId }),
+	};
+}

package/src/host/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Host-page / npm SDK protocol surface (Zod-free).
+ */
+
+export * from "./command-dispatch.js";
+export * from "./command-envelope.js";
+export * from "./command-settlement.js";
+export * from "./constants.js";
+export * from "./external-id-argument-guards.js";
+export * from "./host-event-contract.js";
+export * from "./lazy-handle-client.js";
+export { createCommandRequestId } from "./request-id.js";
+export * from "./sdk-types.js";
+export { createUniqueId } from "./unique-id.js";