@getuserfeedback/protocol 0.6.0 → 0.7.2

package/src/flow-assignments.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import {
+	claimPendingFlowAssignmentsRequestSchema,
+	flowAssignmentRecipientRequestSchema,
+	updateFlowAssignmentLifecycleRequestSchema,
+} from "./flow-assignments";
+
+describe("flow assignment request contracts", () => {
+	it("accepts runtime targeting context for listPending", () => {
+		const result = flowAssignmentRecipientRequestSchema.parse({
+			identities: [{ type: "userId", value: "user_1" }],
+			context: {
+				flags: [{ key: "new_checkout", value: true }],
+				capabilities: [{ key: "checkout.drawer", source: "host-app" }],
+			},
+		});
+
+		expect(result.context?.flags?.[0]).toEqual({
+			key: "new_checkout",
+			value: true,
+		});
+		expect(result.context?.capabilities?.[0]).toEqual({
+			key: "checkout.drawer",
+			source: "host-app",
+		});
+	});
+
+	it("accepts runtime targeting context for claimPending", () => {
+		const result = claimPendingFlowAssignmentsRequestSchema.parse({
+			holdOwnerKey: "inst_1",
+			context: {
+				flags: [{ key: "pricing_test", value: "variant_a" }],
+				capabilities: [{ key: "billing.portal" }],
+			},
+		});
+
+		expect(result.identities).toEqual([]);
+		expect(result.context?.flags?.[0]?.key).toBe("pricing_test");
+		expect(result.context?.capabilities?.[0]?.key).toBe("billing.portal");
+	});
+
+	it("accepts runtime targeting context for lifecycle updates", () => {
+		const result = updateFlowAssignmentLifecycleRequestSchema.parse({
+			identities: [{ type: "userId", value: "user_1" }],
+			flowAssignmentId: "flasn_1",
+			flowVersionId: "flv_1",
+			holdGroupToken: "fahold_1",
+			context: {
+				flags: [{ key: "new_checkout", value: true }],
+				capabilities: [{ key: "checkout.drawer", source: "host-app" }],
+			},
+		});
+
+		expect(result.context?.flags?.[0]).toEqual({
+			key: "new_checkout",
+			value: true,
+		});
+		expect(result.context?.capabilities?.[0]).toEqual({
+			key: "checkout.drawer",
+			source: "host-app",
+		});
+	});
+});

package/src/flow-assignments.ts

@@ -0,0 +1,125 @@
+import * as z from "zod/mini";
+
+import {
+	appEventCapabilitySchema,
+	appEventFlagSchema,
+	appEventIdentitySchema,
+} from "./app-event.js";
+
+export const flowAssignmentStatusSchema = z.enum([
+	"pending",
+	"held",
+	"presented",
+	"completed",
+	"expired",
+	"superseded",
+	"withdrawn_pending",
+	"withdrawn_presented",
+	"withdrawn_final",
+]);
+
+export const flowAssignmentTargetingContextSchema = z.object({
+	flags: z.optional(z.array(appEventFlagSchema)),
+	capabilities: z.optional(z.array(appEventCapabilitySchema)),
+});
+
+export const flowAssignmentRecipientRequestSchema = z.object({
+	identities: z._default(z.array(appEventIdentitySchema), []),
+	context: z.optional(flowAssignmentTargetingContextSchema),
+	at: z.optional(z.number()),
+});
+
+export const flowAssignmentRecordSchema = z.object({
+	flowAssignmentId: z.string().check(z.trim(), z.minLength(1)),
+	flowId: z.string().check(z.trim(), z.minLength(1)),
+	holdGroupToken: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	presentedFlowVersionId: z.optional(
+		z.string().check(z.trim(), z.minLength(1)),
+	),
+	latestFlowVersionId: z.string().check(z.trim(), z.minLength(1)),
+	status: flowAssignmentStatusSchema,
+	assignedAt: z.string(),
+	expiresAt: z.optional(z.string()),
+	heldAt: z.optional(z.string()),
+	holdExpiresAt: z.optional(z.string()),
+	presentedAt: z.optional(z.string()),
+	completedAt: z.optional(z.string()),
+	expiredAt: z.optional(z.string()),
+	supersededAt: z.optional(z.string()),
+	withdrawnAt: z.optional(z.string()),
+	withdrawnFinalAt: z.optional(z.string()),
+});
+
+export const listPendingFlowAssignmentsResponseSchema = z.object({
+	fetchedAt: z.string(),
+	flowAssignments: z.array(flowAssignmentRecordSchema),
+});
+
+export const claimPendingFlowAssignmentsRequestSchema = z.object({
+	identities: z._default(z.array(appEventIdentitySchema), []),
+	context: z.optional(flowAssignmentTargetingContextSchema),
+	holdOwnerKey: z.string().check(z.trim(), z.minLength(1)),
+	at: z.optional(z.number()),
+	limit: z.optional(z.number()),
+});
+
+export const claimPendingFlowAssignmentsResponseSchema = z.object({
+	fetchedAt: z.string(),
+	flowAssignments: z.array(flowAssignmentRecordSchema),
+});
+
+export const updateFlowAssignmentLifecycleRequestSchema = z.object({
+	identities: z._default(z.array(appEventIdentitySchema), []),
+	context: z.optional(flowAssignmentTargetingContextSchema),
+	flowAssignmentId: z.string().check(z.trim(), z.minLength(1)),
+	flowVersionId: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	holdGroupToken: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	at: z.optional(z.number()),
+});
+
+export const releaseFlowAssignmentClaimRequestSchema = z.object({
+	identities: z._default(z.array(appEventIdentitySchema), []),
+	holdGroupToken: z.string().check(z.trim(), z.minLength(1)),
+	holdOwnerKey: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	at: z.optional(z.number()),
+});
+
+export const releaseFlowAssignmentClaimResponseSchema = z.object({
+	releasedCount: z.number(),
+});
+
+export const updateFlowAssignmentLifecycleResponseSchema =
+	flowAssignmentRecordSchema;
+export const nullableUpdateFlowAssignmentLifecycleResponseSchema = z.nullable(
+	updateFlowAssignmentLifecycleResponseSchema,
+);
+
+export type FlowAssignmentStatus = z.output<typeof flowAssignmentStatusSchema>;
+export type FlowAssignmentRecipientRequest = z.output<
+	typeof flowAssignmentRecipientRequestSchema
+>;
+export type FlowAssignmentTargetingContext = z.output<
+	typeof flowAssignmentTargetingContextSchema
+>;
+export type FlowAssignmentRecord = z.output<typeof flowAssignmentRecordSchema>;
+export type ClaimPendingFlowAssignmentsRequest = z.output<
+	typeof claimPendingFlowAssignmentsRequestSchema
+>;
+export type ClaimPendingFlowAssignmentsResponse = z.output<
+	typeof claimPendingFlowAssignmentsResponseSchema
+>;
+export type ListPendingFlowAssignmentsResponse = z.output<
+	typeof listPendingFlowAssignmentsResponseSchema
+>;
+export type ReleaseFlowAssignmentClaimRequest = z.output<
+	typeof releaseFlowAssignmentClaimRequestSchema
+>;
+export type ReleaseFlowAssignmentClaimResponse = z.output<
+	typeof releaseFlowAssignmentClaimResponseSchema
+>;
+export type UpdateFlowAssignmentLifecycleRequest = z.output<
+	typeof updateFlowAssignmentLifecycleRequestSchema
+>;
+export type UpdateFlowAssignmentLifecycleResponse = z.output<
+	typeof updateFlowAssignmentLifecycleResponseSchema
+>;

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}`;