@getuserfeedback/protocol 3.0.2 → 3.0.4

package/dist/widget-config.d.ts

@@ -12,19 +12,19 @@ export declare const telemetryConfigInputSchema: z.ZodMiniObject<{
 }, z.core.$strip>;
 export type TelemetryConfigInput = z.output<typeof telemetryConfigInputSchema>;
 export declare const consentConfigInputSchema: z.ZodMiniUnion<readonly [z.ZodMiniEnum<{
-    pending: "pending";
     granted: "granted";
     denied: "denied";
+    pending: "pending";
     revoked: "revoked";
 }>, z.ZodMiniArray<z.ZodMiniEnum<{
+    "functionality.storage": "functionality.storage";
+    "security.storage": "security.storage";
     "analytics.storage": "analytics.storage";
     "analytics.measurement": "analytics.measurement";
     "personalization.storage": "personalization.storage";
     "ads.storage": "ads.storage";
     "ads.user_data": "ads.user_data";
     "ads.personalization": "ads.personalization";
-    "functionality.storage": "functionality.storage";
-    "security.storage": "security.storage";
 }>>]>;
 export type ConsentConfigInput = z.output<typeof consentConfigInputSchema>;
 export declare const debugInputSchema: z.ZodMiniUnion<readonly [z.ZodMiniBoolean<boolean>, z.ZodMiniString<string>, z.ZodMiniArray<z.ZodMiniString<string>>]>;
@@ -149,19 +149,19 @@ export declare const configureOptionsSchema: z.ZodMiniObject<{
         dark: "dark";
     }>]>>;
     consent: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniEnum<{
-        pending: "pending";
         granted: "granted";
         denied: "denied";
+        pending: "pending";
         revoked: "revoked";
     }>, z.ZodMiniArray<z.ZodMiniEnum<{
+        "functionality.storage": "functionality.storage";
+        "security.storage": "security.storage";
         "analytics.storage": "analytics.storage";
         "analytics.measurement": "analytics.measurement";
         "personalization.storage": "personalization.storage";
         "ads.storage": "ads.storage";
         "ads.user_data": "ads.user_data";
         "ads.personalization": "ads.personalization";
-        "functionality.storage": "functionality.storage";
-        "security.storage": "security.storage";
     }>>]>>;
     auth: z.ZodMiniOptional<z.ZodMiniObject<{
         jwt: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniObject<{
@@ -191,19 +191,19 @@ export declare const initOptionsSchema: z.ZodMiniObject<{
     disableTelemetry: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
     enableDebug: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniBoolean<boolean>, z.ZodMiniString<string>, z.ZodMiniArray<z.ZodMiniString<string>>]>>;
     defaultConsent: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniEnum<{
-        pending: "pending";
         granted: "granted";
         denied: "denied";
+        pending: "pending";
         revoked: "revoked";
     }>, z.ZodMiniArray<z.ZodMiniEnum<{
+        "functionality.storage": "functionality.storage";
+        "security.storage": "security.storage";
         "analytics.storage": "analytics.storage";
         "analytics.measurement": "analytics.measurement";
         "personalization.storage": "personalization.storage";
         "ads.storage": "ads.storage";
         "ads.user_data": "ads.user_data";
         "ads.personalization": "ads.personalization";
-        "functionality.storage": "functionality.storage";
-        "security.storage": "security.storage";
     }>>]>>;
     clientMeta: z.ZodMiniOptional<z.ZodMiniObject<{
         loader: z.ZodMiniEnum<{
@@ -341,19 +341,19 @@ export declare const instanceUpdateableConfigSchema: z.ZodMiniObject<{
         dark: "dark";
     }>]>>;
     consent: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniEnum<{
-        pending: "pending";
         granted: "granted";
         denied: "denied";
+        pending: "pending";
         revoked: "revoked";
     }>, z.ZodMiniArray<z.ZodMiniEnum<{
+        "functionality.storage": "functionality.storage";
+        "security.storage": "security.storage";
         "analytics.storage": "analytics.storage";
         "analytics.measurement": "analytics.measurement";
         "personalization.storage": "personalization.storage";
         "ads.storage": "ads.storage";
         "ads.user_data": "ads.user_data";
         "ads.personalization": "ads.personalization";
-        "functionality.storage": "functionality.storage";
-        "security.storage": "security.storage";
     }>>]>>;
     auth: z.ZodMiniOptional<z.ZodMiniObject<{
         jwt: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniObject<{
@@ -402,19 +402,19 @@ export declare const coreInstanceConfigSchema: z.ZodMiniObject<{
     disableTelemetry: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>>;
     enableDebug: z.ZodMiniDefault<z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniBoolean<boolean>, z.ZodMiniString<string>, z.ZodMiniArray<z.ZodMiniString<string>>]>>>;
     consent: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniEnum<{
-        pending: "pending";
         granted: "granted";
         denied: "denied";
+        pending: "pending";
         revoked: "revoked";
     }>, z.ZodMiniArray<z.ZodMiniEnum<{
+        "functionality.storage": "functionality.storage";
+        "security.storage": "security.storage";
         "analytics.storage": "analytics.storage";
         "analytics.measurement": "analytics.measurement";
         "personalization.storage": "personalization.storage";
         "ads.storage": "ads.storage";
         "ads.user_data": "ads.user_data";
         "ads.personalization": "ads.personalization";
-        "functionality.storage": "functionality.storage";
-        "security.storage": "security.storage";
     }>>]>>;
     auth: z.ZodMiniOptional<z.ZodMiniObject<{
         jwt: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniObject<{

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@getuserfeedback/protocol",
-	"version": "3.0.2",
+	"version": "3.0.4",
 	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
 	"keywords": [
 		"getuserfeedback",

package/src/core-command-envelope.ts

@@ -0,0 +1,27 @@
+import * as z from "zod/mini";
+import { type ClientMeta, clientMetaSchema } from "./client-meta.js";
+import { coreCommandPayloadSchema } from "./core-commands.js";
+
+const requestIdSchema = z.string().check(z.trim(), z.minLength(1));
+const idempotencyKeySchema = z.string().check(z.trim(), z.minLength(1));
+const versionSchema = z.literal("1");
+
+/** Loader -> core iframe command envelope (MessagePort transport). */
+export const coreCommandEnvelopeSchema = z.object({
+	version: versionSchema,
+	instanceId: z.string().check(z.trim(), z.minLength(1)),
+	requestId: requestIdSchema,
+	idempotencyKey: idempotencyKeySchema,
+	clientMeta: z.optional(clientMetaSchema),
+	command: coreCommandPayloadSchema,
+});
+
+export type CoreCommandEnvelope = z.output<typeof coreCommandEnvelopeSchema>;
+
+/** Context passed to core plugin handlers after envelope validation. */
+export type CommandContext = {
+	instanceId: string;
+	requestId: string;
+	idempotencyKey: string;
+	clientMeta?: ClientMeta;
+};

package/src/core-commands.ts

@@ -0,0 +1,164 @@
+import * as z from "zod/mini";
+import {
+	appEventCustomerTrackSchema,
+	appEventExternalIdSchema,
+	appEventSystemTrackSchema,
+} from "./app-event.js";
+import { ErrorEventSchema } from "./errors.js";
+import { responseMetadataInputSchema } from "./response-metadata.js";
+import { configureOptionsSchema, initOptionsSchema } from "./widget-config.js";
+
+const flowHandleIdSchema = z.string().check(z.trim(), z.minLength(1));
+const flowIdSchema = z.string().check(z.trim(), z.minLength(1));
+
+const identifyTraitsSchema = z.record(z.string(), z.unknown());
+const identifyOptionsSchema = z.strictObject({
+	externalIds: z.optional(
+		z.array(appEventExternalIdSchema).check(z.maxLength(20)),
+	),
+});
+
+const identifyPayloadSchema = z.union([
+	z.strictObject({
+		kind: z.literal("identify"),
+		traits: identifyTraitsSchema,
+		options: z.optional(identifyOptionsSchema),
+	}),
+	z.strictObject({
+		kind: z.literal("identify"),
+		userId: z.string().check(z.trim(), z.minLength(1)),
+		traits: z.optional(identifyTraitsSchema),
+		options: z.optional(identifyOptionsSchema),
+	}),
+]);
+
+const legacySystemTrackPayloadSchema = z.pipe(
+	z.extend(appEventSystemTrackSchema, {
+		kind: z.literal("track"),
+		origin: z.optional(z.literal("system")),
+	}),
+	z.transform(({ origin: _origin, ...rest }) => ({
+		...rest,
+		origin: "system" as const,
+	})),
+);
+
+const customerTrackPayloadSchema = z.extend(appEventCustomerTrackSchema, {
+	kind: z.literal("track"),
+});
+
+const trackPayloadSchema = z.union([
+	legacySystemTrackPayloadSchema,
+	customerTrackPayloadSchema,
+]);
+
+const prefetchPayloadSchema = z.strictObject({
+	kind: z.literal("prefetch"),
+	flowId: flowIdSchema,
+	flowHandleId: z.optional(flowHandleIdSchema),
+});
+
+const openCorePayloadSchema = z.strictObject({
+	kind: z.literal("open"),
+	flowId: flowIdSchema,
+	flowHandleId: z.optional(flowHandleIdSchema),
+	metadata: z.optional(responseMetadataInputSchema),
+	hideCloseButton: z.optional(z.boolean()),
+});
+
+const prerenderCorePayloadSchema = z.strictObject({
+	kind: z.literal("prerender"),
+	flowId: flowIdSchema,
+	flowHandleId: z.optional(flowHandleIdSchema),
+	hideCloseButton: z.optional(z.boolean()),
+});
+
+const closeCorePayloadSchema = z.object({
+	kind: z.literal("close"),
+	flowHandleId: z.optional(flowHandleIdSchema),
+	reasonCode: z.optional(z.enum(["CLOSED", "RESET"])),
+});
+
+const hostContextUpdatedPayloadSchema = z.object({
+	kind: z.literal("hostContextUpdated"),
+	context: z.object({
+		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.object({
+				path: z.optional(z.string()),
+				referrer: z.optional(z.string()),
+				search: z.optional(z.string()),
+			}),
+		),
+	}),
+});
+
+const hostSignalPayloadSchema = z.object({
+	kind: z.literal("hostSignal"),
+	name: z.string(),
+	data: z.optional(z.unknown()),
+});
+
+const setTargetingPlanPayloadSchema = z.object({
+	kind: z.literal("setTargetingPlan"),
+	plan: z.object({
+		strategy: z.optional(z.enum(["firstMatch"])),
+		candidates: z.array(
+			z.object({
+				action: z.enum(["open", "prefetch"]),
+				flowId: flowIdSchema,
+				rules: z.array(z.unknown()),
+			}),
+		),
+	}),
+});
+
+const telemetryPayloadSchema = z.object({
+	kind: z.literal("telemetry"),
+	name: z.string(),
+	props: z.optional(z.record(z.string(), z.unknown())),
+});
+
+const errorPayloadSchema = z.object({
+	kind: z.literal("error"),
+	event: ErrorEventSchema,
+});
+
+const configureCorePayloadSchema = z.object({
+	kind: z.literal("configure"),
+	opts: configureOptionsSchema,
+});
+
+const initCorePayloadSchema = z.strictObject({
+	kind: z.literal("init"),
+	opts: initOptionsSchema,
+});
+
+const resetPayloadSchema = z.object({
+	kind: z.literal("reset"),
+});
+
+const coreCommandPayloadWithoutIdentifySchema = z.discriminatedUnion("kind", [
+	openCorePayloadSchema,
+	prefetchPayloadSchema,
+	prerenderCorePayloadSchema,
+	hostContextUpdatedPayloadSchema,
+	hostSignalPayloadSchema,
+	setTargetingPlanPayloadSchema,
+	telemetryPayloadSchema,
+	configureCorePayloadSchema,
+	initCorePayloadSchema,
+	closeCorePayloadSchema,
+	resetPayloadSchema,
+	errorPayloadSchema,
+]);
+
+export const coreCommandPayloadSchema = z.union([
+	coreCommandPayloadWithoutIdentifySchema,
+	identifyPayloadSchema,
+	trackPayloadSchema,
+]);
+
+export type CoreCommandPayload = z.output<typeof coreCommandPayloadSchema>;

package/src/flow-display.test.ts

@@ -103,6 +103,82 @@ describe("flow display sync contracts", () => {
 		});
 	});
 
+	it("accepts runtime broadcast attention policy metadata", () => {
+		const result = flowDisplaySyncResponseSchema.parse({
+			fetchedAt: "2026-06-18T00:00:00.000Z",
+			assignments: {
+				claimed: [],
+			},
+			broadcasts: {
+				version: "broadcasts_1",
+				opportunities: [
+					{
+						opportunityId: "rtb_daver_1",
+						flowId: "sur_1",
+						flowVersionId: "flv_1",
+						source: {
+							kind: "runtime_broadcast",
+						},
+						runtimeEligibility: {
+							requiredCapabilities: [],
+						},
+						attentionPolicy: {
+							priority: "high",
+							attentionMode: "concurrent",
+							cooldown: {
+								key: "automation:dauto_1",
+								afterDisplayMs: 60_000,
+							},
+						},
+					},
+				],
+			},
+		});
+
+		expect(result.broadcasts.opportunities[0]?.attentionPolicy).toEqual({
+			priority: "high",
+			attentionMode: "concurrent",
+			cooldown: {
+				key: "automation:dauto_1",
+				afterDisplayMs: 60_000,
+			},
+		});
+	});
+
+	it("rejects invalid runtime broadcast attention policy metadata", () => {
+		expect(() =>
+			flowDisplaySyncResponseSchema.parse({
+				fetchedAt: "2026-06-18T00:00:00.000Z",
+				assignments: {
+					claimed: [],
+				},
+				broadcasts: {
+					version: "broadcasts_1",
+					opportunities: [
+						{
+							opportunityId: "rtb_daver_1",
+							flowId: "sur_1",
+							flowVersionId: "flv_1",
+							source: {
+								kind: "runtime_broadcast",
+							},
+							runtimeEligibility: {
+								requiredCapabilities: [],
+							},
+							attentionPolicy: {
+								priority: "urgent",
+								cooldown: {
+									key: "automation:dauto_1",
+									afterDisplayMs: -1,
+								},
+							},
+						},
+					],
+				},
+			}),
+		).toThrow();
+	});
+
 	it("defaults legacy runtime broadcast opportunities to an immediate runtime trigger", () => {
 		const result = flowDisplaySyncResponseSchema.parse({
 			fetchedAt: "2026-06-18T00:00:00.000Z",

package/src/flow-display.ts

@@ -33,6 +33,20 @@ const immediateRuntimeDisplayTrigger: z.output<
 	kind: "immediate",
 };
 
+export const runtimeDisplayAttentionPolicySchema = z.object({
+	priority: z.optional(z.enum(["critical", "high", "normal", "low"])),
+	attentionMode: z.optional(z.enum(["exclusive", "concurrent"])),
+	cooldown: z.optional(
+		z.union([
+			z.object({
+				key: z.string().check(z.trim(), z.minLength(1)),
+				afterDisplayMs: z.number().check(z.positive()),
+			}),
+			z.null(),
+		]),
+	),
+});
+
 export const runtimeDisplayBroadcastOpportunitySchema = z.object({
 	opportunityId: z.string().check(z.trim(), z.minLength(1)),
 	flowId: z.string().check(z.trim(), z.minLength(1)),
@@ -47,6 +61,7 @@ export const runtimeDisplayBroadcastOpportunitySchema = z.object({
 		runtimeDisplayTriggerSchema,
 		immediateRuntimeDisplayTrigger,
 	),
+	attentionPolicy: z.optional(runtimeDisplayAttentionPolicySchema),
 });
 
 export const runtimeDisplayBroadcastsSchema = z.object({
@@ -79,6 +94,9 @@ export type RuntimeDisplayBroadcasts = z.output<
 export type RuntimeDisplayBroadcastOpportunity = z.output<
 	typeof runtimeDisplayBroadcastOpportunitySchema
 >;
+export type RuntimeDisplayAttentionPolicy = z.output<
+	typeof runtimeDisplayAttentionPolicySchema
+>;
 export type RuntimeDisplayEligibility = z.output<
 	typeof runtimeDisplayEligibilitySchema
 >;

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 {
@@ -66,10 +75,12 @@ export {
 	type FlowDisplaySyncResponse,
 	flowDisplaySyncRequestSchema,
 	flowDisplaySyncResponseSchema,
+	type RuntimeDisplayAttentionPolicy,
 	type RuntimeDisplayBroadcastOpportunity,
 	type RuntimeDisplayBroadcasts,
 	type RuntimeDisplayEligibility,
 	type RuntimeDisplayTrigger,
+	runtimeDisplayAttentionPolicySchema,
 	runtimeDisplayBroadcastOpportunitySchema,
 	runtimeDisplayBroadcastsSchema,
 	runtimeDisplayEligibilitySchema,