@getuserfeedback/protocol 0.10.1 → 1.0.0

package/src/webview-transport.ts

@@ -0,0 +1,196 @@
+import * as z from "zod/mini";
+import { appEventPayloadSchema } from "./app-event.js";
+import { clientMetaSchema } from "./client-meta.js";
+import {
+	HANDLE_INVALIDATED_REASON_CODES,
+	HANDLE_INVALIDATED_SOURCES,
+} from "./host/host-event-contract.js";
+import { publicCommandPayloadSchema } from "./widget-commands.js";
+
+const nonEmptyStringSchema = z.string().check(z.trim(), z.minLength(1));
+const transportMessageIdSchema = nonEmptyStringSchema;
+const commandErrorSchema = z.strictObject({
+	message: nonEmptyStringSchema,
+	code: z.optional(nonEmptyStringSchema),
+});
+
+export const webViewCommandEnvelopeSchema = z.object({
+	version: z.literal("1"),
+	instanceId: nonEmptyStringSchema,
+	requestId: nonEmptyStringSchema,
+	idempotencyKey: nonEmptyStringSchema,
+	clientMeta: z.optional(clientMetaSchema),
+	command: publicCommandPayloadSchema,
+});
+
+const commandSettledDetailBase = {
+	requestId: nonEmptyStringSchema,
+	instanceId: z.nullable(nonEmptyStringSchema),
+	kind: nonEmptyStringSchema,
+} as const;
+
+const commandSettledDetailSchema = z.discriminatedUnion("ok", [
+	z.strictObject({
+		...commandSettledDetailBase,
+		ok: z.literal(true),
+		result: z.optional(z.unknown()),
+	}),
+	z.strictObject({
+		...commandSettledDetailBase,
+		ok: z.literal(false),
+		error: commandErrorSchema,
+	}),
+]);
+
+const flowStateBase = {
+	instanceId: nonEmptyStringSchema,
+	isOpen: z.boolean(),
+	isLoading: z.boolean(),
+	width: z.optional(z.number()),
+	height: z.optional(z.number()),
+} as const;
+
+const flowStateChangedDetailSchema = z.strictObject({
+	...flowStateBase,
+	flowHandleId: nonEmptyStringSchema,
+});
+
+const instanceFlowStateChangedDetailSchema = z.strictObject(flowStateBase);
+
+const openRequestedDetailSchema = z.strictObject({
+	instanceId: nonEmptyStringSchema,
+	source: z.enum(["command", "targeting"]),
+	flowId: nonEmptyStringSchema,
+	flowHandleId: z.optional(nonEmptyStringSchema),
+	hideCloseButton: z.optional(z.boolean()),
+});
+
+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(),
+});
+
+const unsupportedCommandDetailSchema = z.strictObject({
+	requestId: nonEmptyStringSchema,
+	instanceId: z.nullable(nonEmptyStringSchema),
+	kind: nonEmptyStringSchema,
+	code: z.literal("UNSUPPORTED_COMMAND"),
+	message: nonEmptyStringSchema,
+	issues: z.optional(z.array(z.string())),
+});
+
+const instanceErrorDetailSchema = z.strictObject({
+	instanceId: nonEmptyStringSchema,
+	code: nonEmptyStringSchema,
+	details: z.optional(z.unknown()),
+	recovery: z.optional(z.unknown()),
+	at: z.number(),
+});
+
+const loaderErrorDetailSchema = z.strictObject({
+	code: nonEmptyStringSchema,
+	details: z.optional(z.unknown()),
+	recovery: z.optional(z.unknown()),
+	at: z.number(),
+});
+
+const appEventDetailSchema = z.strictObject({
+	instanceId: nonEmptyStringSchema,
+	payload: appEventPayloadSchema,
+});
+
+export const webViewTransportNativeMessageSchema = z.discriminatedUnion(
+	"kind",
+	[
+		z.strictObject({
+			kind: z.literal("enqueueCommand"),
+			id: transportMessageIdSchema,
+			envelope: webViewCommandEnvelopeSchema,
+		}),
+	],
+);
+
+export const webViewTransportHostEventSchema = z.discriminatedUnion("name", [
+	z.strictObject({
+		name: z.literal("instance:command:settled"),
+		detail: commandSettledDetailSchema,
+	}),
+	z.strictObject({
+		name: z.literal("instance:flow:state-changed"),
+		detail: flowStateChangedDetailSchema,
+	}),
+	z.strictObject({
+		name: z.literal("instance:flow:state-changed:instance"),
+		detail: instanceFlowStateChangedDetailSchema,
+	}),
+	z.strictObject({
+		name: z.literal("instance:open:requested"),
+		detail: openRequestedDetailSchema,
+	}),
+	z.strictObject({
+		name: z.literal("instance:handle:invalidated"),
+		detail: handleInvalidatedDetailSchema,
+	}),
+	z.strictObject({
+		name: z.literal("instance:command:unsupported"),
+		detail: unsupportedCommandDetailSchema,
+	}),
+	z.strictObject({
+		name: z.literal("instance:error"),
+		detail: instanceErrorDetailSchema,
+	}),
+	z.strictObject({
+		name: z.literal("instance:app-event"),
+		detail: appEventDetailSchema,
+	}),
+	z.strictObject({
+		name: z.literal("loader:error"),
+		detail: loaderErrorDetailSchema,
+	}),
+]);
+
+export const webViewTransportWebMessageSchema = z.discriminatedUnion("kind", [
+	z.strictObject({
+		kind: z.literal("ready"),
+		instanceId: z.optional(nonEmptyStringSchema),
+	}),
+	z.strictObject({
+		kind: z.literal("hostEvent"),
+		event: webViewTransportHostEventSchema,
+	}),
+	z.strictObject({
+		kind: z.literal("error"),
+		error: commandErrorSchema,
+	}),
+]);
+
+export type WebViewCommandEnvelope = z.output<
+	typeof webViewCommandEnvelopeSchema
+>;
+export type WebViewTransportNativeMessage = z.output<
+	typeof webViewTransportNativeMessageSchema
+>;
+export type WebViewTransportHostEvent = z.output<
+	typeof webViewTransportHostEventSchema
+>;
+export type WebViewTransportWebMessage = z.output<
+	typeof webViewTransportWebMessageSchema
+>;
+
+export function parseWebViewTransportNativeMessage(
+	input: unknown,
+): WebViewTransportNativeMessage {
+	return webViewTransportNativeMessageSchema.parse(input);
+}
+
+export function parseWebViewTransportWebMessage(
+	input: unknown,
+): WebViewTransportWebMessage {
+	return webViewTransportWebMessageSchema.parse(input);
+}

package/src/widget-commands.ts

@@ -19,6 +19,8 @@ const publicWidgetCommandKinds = [
 	"prefetch",
 	"prerender",
 	"identify",
+	"updateHostContext",
+	"emitHostSignal",
 	"setContainer",
 	"setDefaultContainerPolicy",
 	"configure",
@@ -72,6 +74,19 @@ const identifyPayloadSchema = z.union([
 	}),
 ]);
 
+const hostContextSchema = z.strictObject({
+	url: z.string().check(z.url()),
+	env: z.optional(z.record(z.string(), z.string())),
+	storage: z.optional(z.record(z.string(), z.string())),
+	page: z.optional(
+		z.strictObject({
+			path: z.optional(z.string()),
+			referrer: z.optional(z.string()),
+			search: z.optional(z.string()),
+		}),
+	),
+});
+
 // TODO(migration): After telemetry confirms no remaining `open.containerRequirement` in host command queues, remove the optional field and transform so unknown keys fail under `.strict()` again.
 // [from=legacy-open-container-requirement] [to=strict-public-open-only] [scope=slice] [priority=low] [impact=medium] [risk=low]
 const legacyOpenContainerRequirementSchema = z.enum(["any", "hostOnly"]);
@@ -114,6 +129,15 @@ export const publicCommandPayloadSchema = z.union([
 			flowHandleId: z.optional(flowHandleIdSchema),
 			hideCloseButton: z.optional(z.boolean()),
 		}),
+		z.strictObject({
+			kind: z.literal("updateHostContext"),
+			context: hostContextSchema,
+		}),
+		z.strictObject({
+			kind: z.literal("emitHostSignal"),
+			name: z.string().check(z.trim(), z.minLength(1)),
+			data: z.optional(z.unknown()),
+		}),
 		z.strictObject({
 			kind: z.literal("setContainer"),
 			flowHandleId: flowHandleIdSchema,