@getuserfeedback/protocol 2.2.0 → 3.0.3

package/dist/index.js

@@ -1,5 +1,7 @@
 export { appEventBaseSchema, appEventCapabilitySchema, appEventContextSchema, appEventCustomerTrackSchema, appEventExternalIdSchema, appEventFlagProviderSchema, appEventFlagSchema, appEventFlowDismissedSchema, appEventIdentitySchema, appEventIdentityTypeSchema, appEventPayloadSchema, appEventSurveyViewedSchema, appEventSystemBaseSchema, appEventSystemTrackSchema, appEventTrackSchema, reservedSystemAppEventNames, } from "./app-event.js";
 export { clientMetaSchema, } from "./client-meta.js";
+export { coreCommandEnvelopeSchema, } from "./core-command-envelope.js";
+export { coreCommandPayloadSchema, } from "./core-commands.js";
 export { DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS } from "./defaults.js";
 export { ErrorCategory, ErrorCategorySchema, ErrorEventSchema, ProtocolError, } from "./errors.js";
 export { claimPendingFlowAssignmentsRequestSchema, claimPendingFlowAssignmentsResponseSchema, flowAssignmentRecipientRequestSchema, flowAssignmentRecordSchema, flowAssignmentStatusSchema, flowAssignmentTargetingContextSchema, listPendingFlowAssignmentsResponseSchema, nullableUpdateFlowAssignmentLifecycleResponseSchema, releaseFlowAssignmentClaimRequestSchema, releaseFlowAssignmentClaimResponseSchema, updateFlowAssignmentLifecycleRequestSchema, updateFlowAssignmentLifecycleResponseSchema, } from "./flow-assignments.js";

package/dist/scopes.d.ts

@@ -10,14 +10,14 @@ export declare const SCOPE_IDS: readonly [
     "ads.personalization"
 ];
 export declare const scopeIdSchema: 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 Scope = (typeof SCOPE_IDS)[number];
 export declare function isScope(value: unknown): value is Scope;

package/dist/webview-transport.d.ts

@@ -124,19 +124,19 @@ export declare const webViewCommandEnvelopeSchema: 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<{
@@ -167,19 +167,19 @@ export declare const webViewCommandEnvelopeSchema: 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<{
@@ -563,19 +563,19 @@ export declare const webViewTransportNativeMessageSchema: z.ZodMiniDiscriminated
                     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<{
@@ -606,19 +606,19 @@ export declare const webViewTransportNativeMessageSchema: z.ZodMiniDiscriminated
                 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<{
@@ -933,8 +933,8 @@ export declare const webViewTransportHostEventSchema: z.ZodMiniDiscriminatedUnio
         handleId: z.ZodMiniString<string>;
         reasonCode: z.ZodMiniEnum<{
             INTERNAL: "INTERNAL";
-            RESET: "RESET";
             CLOSED: "CLOSED";
+            RESET: "RESET";
             STALE_HANDLE: "STALE_HANDLE";
             OWNERSHIP_CONFLICT: "OWNERSHIP_CONFLICT";
             OWNER_DISPOSED: "OWNER_DISPOSED";
@@ -1518,8 +1518,8 @@ export declare const webViewTransportWebMessageSchema: z.ZodMiniDiscriminatedUni
             handleId: z.ZodMiniString<string>;
             reasonCode: z.ZodMiniEnum<{
                 INTERNAL: "INTERNAL";
-                RESET: "RESET";
                 CLOSED: "CLOSED";
+                RESET: "RESET";
                 STALE_HANDLE: "STALE_HANDLE";
                 OWNERSHIP_CONFLICT: "OWNERSHIP_CONFLICT";
                 OWNER_DISPOSED: "OWNER_DISPOSED";

package/dist/widget-commands.d.ts

@@ -2,18 +2,18 @@ import * as z from "zod/mini";
 import { type ConfigureOptions, type InitOptions } from "./widget-config.js";
 export declare const publicWidgetCommandKindSchema: z.ZodMiniEnum<{
     open: "open";
-    prerender: "prerender";
     prefetch: "prefetch";
+    prerender: "prerender";
     identify: "identify";
-    updateHostContext: "updateHostContext";
-    emitHostSignal: "emitHostSignal";
-    setContainer: "setContainer";
-    setDefaultContainerPolicy: "setDefaultContainerPolicy";
+    track: "track";
     configure: "configure";
     init: "init";
     close: "close";
     reset: "reset";
-    track: "track";
+    updateHostContext: "updateHostContext";
+    emitHostSignal: "emitHostSignal";
+    setContainer: "setContainer";
+    setDefaultContainerPolicy: "setDefaultContainerPolicy";
 }>;
 export declare const containerPolicySchema: z.ZodMiniDiscriminatedUnion<[z.ZodMiniObject<{
     kind: z.ZodMiniLiteral<"floating">;
@@ -109,19 +109,19 @@ export declare const publicCommandPayloadSchema: z.ZodMiniUnion<readonly [z.ZodM
             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<{
@@ -152,19 +152,19 @@ export declare const publicCommandPayloadSchema: z.ZodMiniUnion<readonly [z.ZodM
         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<{

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": "2.2.0",
+	"version": "3.0.3",
 	"description": "getuserfeedback widget protocol — host surface and (later) wire protocol",
 	"keywords": [
 		"getuserfeedback",
@@ -46,6 +46,12 @@
 			"import": "./dist/host/host-event-contract.js",
 			"default": "./dist/host/host-event-contract.js"
 		},
+		"./host/host-event-schemas": {
+			"types": "./dist/host/host-event-schemas.d.ts",
+			"bun": "./src/host/host-event-schemas.ts",
+			"import": "./dist/host/host-event-schemas.js",
+			"default": "./dist/host/host-event-schemas.js"
+		},
 		"./host/constants": {
 			"types": "./dist/host/constants.d.ts",
 			"bun": "./src/host/constants.ts",
@@ -140,7 +146,6 @@
 		"zod": "^4.2.1"
 	},
 	"devDependencies": {
-		"rimraf": "^6.0.0",
 		"typescript": "^5.8.3"
 	}
 }

package/src/app-event.ts

@@ -132,6 +132,7 @@ const appEventSurveyReferenceSchema = z.object({
 
 export const reservedSystemAppEventNames = [
 	"Response Submitted",
+	"Flow Completed",
 	"Flow Viewed",
 	"Flow Dismissed",
 	"Identified",

package/src/command-kinds.ts

@@ -0,0 +1,42 @@
+import * as z from "zod/mini";
+
+const coreCommandKinds = [
+	"open",
+	"prefetch",
+	"prerender",
+	"hostContextUpdated",
+	"hostSignal",
+	"setTargetingPlan",
+	"telemetry",
+	"identify",
+	"track",
+	"configure",
+	"init",
+	"close",
+	"reset",
+	"error",
+] as const;
+
+const publicCommandKinds = [
+	"open",
+	"prefetch",
+	"prerender",
+	"identify",
+	"updateHostContext",
+	"emitHostSignal",
+	"setContainer",
+	"setDefaultContainerPolicy",
+	"configure",
+	"init",
+	"close",
+	"reset",
+	"track",
+] as const;
+
+export const coreCommandKindSchema = z.enum(coreCommandKinds);
+export const publicCommandKindSchema = z.enum(publicCommandKinds);
+
+/** All command kinds that may appear in settlement events (core receives loader + SDK commands). */
+const allCommandKinds = [...coreCommandKinds, ...publicCommandKinds] as const;
+
+export const allCommandKindSchema = z.enum(allCommandKinds);

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-assignments.ts

@@ -40,9 +40,6 @@ export const flowAssignmentStatusSchema = z.enum([
 	"completed",
 	"expired",
 	"superseded",
-	"withdrawn_pending",
-	"withdrawn_presented",
-	"withdrawn_final",
 ]);
 
 export const flowAssignmentTargetingContextSchema = z.object({

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

@@ -278,3 +278,34 @@ export function getFlowHandleFromSettlementDetail(detail: {
 		...(isNonEmptyString(flowRunId) && { flowRunId }),
 	};
 }
+
+/** Normalized allocation from a handle-returning settlement: handle + instanceId for state. */
+export type FlowHandleAllocationFromSettlement = {
+	flowHandleId: string;
+	flowRunId: string | null;
+	instanceId: string | null;
+};
+
+const nonEmptyOrNull = (value: string | null | undefined): string | null =>
+	typeof value === "string" && value.length > 0 ? value : null;
+
+/**
+ * Parse a command settlement into a single allocation object when the command
+ * returned a flow handle (open/prerender/prefetch). Returns null otherwise.
+ */
+export function getFlowHandleAllocationFromSettlement(detail: {
+	ok: boolean;
+	kind: string;
+	result?: unknown;
+	instanceId?: string | null;
+}): FlowHandleAllocationFromSettlement | null {
+	const handle = getFlowHandleFromSettlementDetail(detail);
+	if (!handle) {
+		return null;
+	}
+	return {
+		flowHandleId: handle.flowHandleId,
+		flowRunId: handle.flowRunId ?? null,
+		instanceId: nonEmptyOrNull(detail.instanceId ?? null),
+	};
+}