@getuserfeedback/protocol 2.2.0 → 3.0.3

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

@@ -0,0 +1,135 @@
+/**
+ * Zod schemas that validate the host event detail contract.
+ * Paired with host-event-contract.ts, which defines the types and lightweight guards.
+ */
+import * as z from "zod/mini";
+import { allCommandKindSchema } from "../command-kinds.js";
+import {
+	HANDLE_INVALIDATED_REASON_CODES,
+	HANDLE_INVALIDATED_SOURCES,
+} from "./host-event-contract.js";
+
+const nonEmptyStringSchema = z.string().check(z.trim(), z.minLength(1));
+
+const commandErrorSchema = z.strictObject({
+	message: nonEmptyStringSchema,
+	code: z.optional(nonEmptyStringSchema),
+});
+
+const commandSettledDetailBase = {
+	requestId: nonEmptyStringSchema,
+	instanceId: z.nullable(nonEmptyStringSchema),
+	kind: allCommandKindSchema,
+};
+
+/**
+ * Canonical shape when a command (open, prerender, prefetch) settles and core
+ * has allocated a flow handle. flowRunId is present for open/prerender, absent for prefetch.
+ */
+export const flowHandleSettlementResultSchema = z.strictObject({
+	flowHandleId: nonEmptyStringSchema,
+	flowRunId: z.optional(nonEmptyStringSchema),
+});
+
+export type FlowHandleSettlementResult = z.output<
+	typeof flowHandleSettlementResultSchema
+>;
+
+const commandSettledSuccessDetailSchema = z.strictObject({
+	...commandSettledDetailBase,
+	ok: z.literal(true),
+	result: z.optional(z.unknown()),
+});
+
+const commandSettledFailureDetailSchema = z.strictObject({
+	...commandSettledDetailBase,
+	ok: z.literal(false),
+	error: commandErrorSchema,
+});
+
+export const commandSettledDetailSchema = z.discriminatedUnion("ok", [
+	commandSettledSuccessDetailSchema,
+	commandSettledFailureDetailSchema,
+]);
+
+export type { CommandSettledDetail } from "./host-event-contract.js";
+
+const flowStateChangedBase = {
+	instanceId: nonEmptyStringSchema,
+	isOpen: z.boolean(),
+	isLoading: z.boolean(),
+	width: z.optional(z.number()),
+	height: z.optional(z.number()),
+} as const;
+
+export const flowStateChangedDetailSchema = z.strictObject({
+	...flowStateChangedBase,
+	flowHandleId: nonEmptyStringSchema,
+});
+
+export type { FlowStateChangedDetail } from "./host-event-contract.js";
+
+export const instanceFlowStateChangedDetailSchema = z.strictObject({
+	...flowStateChangedBase,
+	flowHandleId: z.optional(nonEmptyStringSchema),
+});
+
+export type { InstanceFlowStateChangedDetail } from "./host-event-contract.js";
+
+export const openRequestedDetailSchema = z.strictObject({
+	instanceId: nonEmptyStringSchema,
+	source: z.enum(["command", "targeting"]),
+	flowId: nonEmptyStringSchema,
+	flowHandleId: z.optional(nonEmptyStringSchema),
+	hideCloseButton: z.optional(z.boolean()),
+});
+
+export type { OpenRequestedDetail } from "./host-event-contract.js";
+
+export const handleInvalidatedDetailSchema = z.strictObject({
+	instanceId: nonEmptyStringSchema,
+	handleKind: nonEmptyStringSchema,
+	handleId: nonEmptyStringSchema,
+	reasonCode: z.enum(HANDLE_INVALIDATED_REASON_CODES),
+	reasonMessage: z.optional(nonEmptyStringSchema),
+	relatedRequestId: z.optional(nonEmptyStringSchema),
+	source: z.enum(HANDLE_INVALIDATED_SOURCES),
+	at: z.number(),
+});
+
+export type { HandleInvalidatedDetail } from "./host-event-contract.js";
+
+/**
+ * Parse unknown result into FlowHandleSettlementResult. Returns null if invalid.
+ */
+export function parseFlowHandleSettlementResult(
+	result: unknown,
+): FlowHandleSettlementResult | null {
+	const parsed = flowHandleSettlementResultSchema.safeParse(result);
+	return parsed.success ? parsed.data : null;
+}
+
+/**
+ * Extract flow handle from a successful command settlement when the command
+ * is one that can return a handle (open, prerender, prefetch). Returns null
+ * if detail is not ok, kind is not one of those, or result does not match
+ * flowHandleSettlementResultSchema.
+ */
+export function getFlowHandleFromSettlementDetail(detail: {
+	ok: boolean;
+	kind: string;
+	result?: unknown;
+}): FlowHandleSettlementResult | null {
+	if (
+		!detail.ok ||
+		(detail.kind !== "open" &&
+			detail.kind !== "prerender" &&
+			detail.kind !== "prefetch")
+	) {
+		return null;
+	}
+	return parseFlowHandleSettlementResult(detail.result);
+}
+
+export type { FlowHandleAllocationFromSettlement } from "./host-event-contract.js";
+export { getFlowHandleAllocationFromSettlement } from "./host-event-contract.js";

package/src/index.ts

@@ -26,6 +26,15 @@ export {
 	type ClientMeta,
 	clientMetaSchema,
 } from "./client-meta.js";
+export {
+	type CommandContext,
+	type CoreCommandEnvelope,
+	coreCommandEnvelopeSchema,
+} from "./core-command-envelope.js";
+export {
+	type CoreCommandPayload,
+	coreCommandPayloadSchema,
+} from "./core-commands.js";
 export { DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS } from "./defaults.js";
 export type { ErrorEvent, ProtocolErrorCode } from "./errors.js";
 export {