@getuserfeedback/protocol 0.6.0 → 0.7.2

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,13 @@
+/**
+ * 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 "./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";

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");