@getuserfeedback/protocol 1.5.0 → 1.6.1

package/src/protocol-root.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import type { FlowDismissedPayload, FlowViewedPayload } from "./host";
 import { createCommandEnvelope } from "./host";
+import { commandEnvelopeWithInstanceIdSchema } from "./host/command-envelope-schema.js";
 import type { WebViewTransportWebMessage } from "./index";
 import {
 	appEventCapabilitySchema,
@@ -225,6 +226,30 @@ describe("@getuserfeedback/protocol root contract", () => {
 		);
 	});
 
+	it("parses public open commands with response metadata from the root contract", () => {
+		const result = parsePublicCommand({
+			kind: "open",
+			flowId: "sur_123",
+			metadata: {
+				tags: {
+					campaign: "spring-sale",
+					segments: ["beta", "enterprise"],
+				},
+			},
+		});
+
+		expect(result).toEqual({
+			kind: "open",
+			flowId: "sur_123",
+			metadata: {
+				tags: {
+					campaign: "spring-sale",
+					segments: ["beta", "enterprise"],
+				},
+			},
+		});
+	});
+
 	it("strips legacy open.containerRequirement for enum values any and hostOnly", () => {
 		for (const containerRequirement of ["any", "hostOnly"] as const) {
 			const result = parsePublicCommand({
@@ -338,6 +363,44 @@ describe("@getuserfeedback/protocol root contract", () => {
 		expect("instanceId" in envelope).toBe(false);
 	});
 
+	it("parses public command envelopes with required instance ids", () => {
+		const result = commandEnvelopeWithInstanceIdSchema.safeParse({
+			version: "1",
+			instanceId: "instance_123",
+			requestId: "request_123",
+			idempotencyKey: "request_123",
+			command: {
+				kind: "init",
+				opts: {
+					apiKey: "key_test",
+					runtimeEndpoints: {
+						coreUrl: "https://cdn.example.com/core.html",
+						apiUrl: "https://api.example.com/v1",
+					},
+				},
+			},
+		});
+
+		expect(result.success).toBe(true);
+		if (result.success) {
+			expect(result.data.instanceId).toBe("instance_123");
+			expect(result.data.command.kind).toBe("init");
+		}
+	});
+
+	it("rejects public command envelopes without instance ids", () => {
+		const result = commandEnvelopeWithInstanceIdSchema.safeParse({
+			version: "1",
+			requestId: "request_123",
+			idempotencyKey: "request_123",
+			command: {
+				kind: "reset",
+			},
+		});
+
+		expect(result.success).toBe(false);
+	});
+
 	it("rejects internal navigation context commands from the public contract", () => {
 		expect(() =>
 			parsePublicCommand({

package/src/response-metadata.ts

@@ -0,0 +1,10 @@
+import * as z from "zod/mini";
+
+const responseMetadataTagValueSchema = z.union([
+	z.string(),
+	z.array(z.string()),
+]);
+
+export const responseMetadataInputSchema = z.strictObject({
+	tags: z.optional(z.record(z.string(), responseMetadataTagValueSchema)),
+});

package/src/widget-commands.ts

@@ -3,6 +3,7 @@ import {
 	appEventCustomerTrackSchema,
 	appEventExternalIdSchema,
 } from "./app-event.js";
+import { responseMetadataInputSchema } from "./response-metadata.js";
 import {
 	type ConfigureOptions,
 	configureOptionsSchema,
@@ -108,6 +109,7 @@ const openPublicPayloadSchema = z.pipe(
 		flowId: flowIdSchema,
 		flowHandleId: z.optional(flowHandleIdSchema),
 		container: z.optional(htmlElementOrNullSchema),
+		metadata: z.optional(responseMetadataInputSchema),
 		/** Accepted for legacy browser SDK payloads; stripped before dispatch. */
 		containerRequirement: z.optional(legacyOpenContainerRequirementSchema),
 		hideCloseButton: z.optional(z.boolean()),