@getuserfeedback/protocol 0.6.1 → 0.7.2

package/src/app-event.ts

@@ -0,0 +1,211 @@
+import * as z from "zod/mini";
+import { appEventIdentityTypeSchema } from "./identity-type.js";
+
+export { appEventIdentityTypeSchema } from "./identity-type.js";
+
+export const appEventIdentitySchema = z.object({
+	type: appEventIdentityTypeSchema,
+	value: z.string().check(z.trim(), z.minLength(1)),
+});
+
+type AppEventFlagValue =
+	| string
+	| number
+	| boolean
+	| null
+	| AppEventFlagValue[]
+	| { [key: string]: AppEventFlagValue };
+
+export type AppEventJsonValue =
+	| string
+	| number
+	| boolean
+	| null
+	| AppEventJsonValue[]
+	| { [key: string]: AppEventJsonValue };
+
+const appEventFlagValueSchema: z.ZodMiniType<AppEventFlagValue> = z.lazy(() =>
+	z.union([
+		z.string(),
+		z.number(),
+		z.boolean(),
+		z.null(),
+		z.array(appEventFlagValueSchema),
+		z.record(z.string(), appEventFlagValueSchema),
+	]),
+);
+
+const appEventJsonNumberSchema = z.number().check(
+	z.refine(Number.isFinite, {
+		message: "Expected a finite JSON number.",
+	}),
+);
+
+const appEventJsonValueSchema: z.ZodMiniType<AppEventJsonValue> = z.lazy(() =>
+	z.union([
+		z.string(),
+		appEventJsonNumberSchema,
+		z.boolean(),
+		z.null(),
+		z.array(appEventJsonValueSchema),
+		z.record(z.string(), appEventJsonValueSchema),
+	]),
+);
+
+const appEventJsonObjectSchema = z.record(z.string(), appEventJsonValueSchema);
+
+export const appEventFlagProviderSchema = z.object({
+	name: z.string().check(z.trim(), z.minLength(1)),
+	project: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	environment: z.optional(z.string().check(z.trim(), z.minLength(1))),
+});
+
+export const appEventFlagSchema = z.object({
+	key: z.string().check(z.trim(), z.minLength(1)),
+	target: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	value: appEventFlagValueSchema,
+	variant: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	origin: z.optional(
+		z.enum(["runtime_config", "trigger_context", "provider_sync", "api"]),
+	),
+	provider: z.optional(appEventFlagProviderSchema),
+	status: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	reason: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	evaluatedAt: z.optional(z.string().check(z.trim(), z.minLength(1))),
+});
+
+export const appEventCapabilitySchema = z.object({
+	key: z.string().check(z.trim(), z.minLength(1)),
+	source: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	provider: z.optional(appEventFlagProviderSchema),
+});
+
+const appEventPageSchema = z.object({
+	path: z.optional(z.string()),
+	referrer: z.optional(z.string()),
+	search: z.optional(z.string()),
+});
+
+export const appEventContextSchema = z.object({
+	page: z.optional(appEventPageSchema),
+	locale: z.optional(z.string()),
+	userAgent: z.optional(z.string()),
+	flags: z.optional(z.array(appEventFlagSchema)),
+	capabilities: z.optional(z.array(appEventCapabilitySchema)),
+});
+
+export const appEventBaseSchema = z.object({
+	traits: z.optional(z.record(z.string(), z.unknown())),
+	identities: z.optional(z.array(appEventIdentitySchema)),
+	context: z.optional(appEventContextSchema),
+	messageId: z.optional(z.string()),
+	timestamp: z.optional(z.number()),
+});
+
+const appEventSurveyReferenceSchema = z.object({
+	surveyId: z.string(),
+});
+
+export const reservedSystemAppEventNames = [
+	"Response Submitted",
+	"Flow Viewed",
+	"Flow Dismissed",
+	"Identified",
+] as const;
+const reservedSystemAppEventNameLowercaseSet = new Set<string>(
+	reservedSystemAppEventNames.map((event) => event.toLowerCase()),
+);
+
+const appEventSystemTrackNameSchema = z.enum(["Flow Viewed", "Flow Dismissed"]);
+
+const appEventCustomerNameSchema = z.string().check(
+	z.trim(),
+	z.minLength(1),
+	z.maxLength(255),
+	z.check<string>((ctx) => {
+		if (!reservedSystemAppEventNameLowercaseSet.has(ctx.value.toLowerCase())) {
+			return;
+		}
+		ctx.issues.push({
+			code: "custom",
+			input: ctx.value,
+			message:
+				"Customer app event names cannot use reserved system event names.",
+			continue: false,
+		});
+	}),
+);
+
+export const appEventSystemBaseSchema = z.extend(appEventBaseSchema, {
+	origin: z.literal("system"),
+});
+
+const normalizeSystemAppEventOrigin = <T extends { origin?: "system" }>(
+	input: T,
+): Omit<T, "origin"> & { origin: "system" } => {
+	const { origin: _origin, ...rest } = input;
+	return {
+		...rest,
+		origin: "system" as const,
+	};
+};
+
+export const appEventSurveyViewedSchema = z.pipe(
+	z.extend(appEventBaseSchema, {
+		origin: z.optional(z.literal("system")),
+		event: z.literal("Flow Viewed"),
+		references: appEventSurveyReferenceSchema,
+	}),
+	z.transform(normalizeSystemAppEventOrigin),
+);
+
+export const appEventFlowDismissedSchema = z.pipe(
+	z.extend(appEventBaseSchema, {
+		origin: z.optional(z.literal("system")),
+		event: z.literal("Flow Dismissed"),
+		references: appEventSurveyReferenceSchema,
+	}),
+	z.transform(normalizeSystemAppEventOrigin),
+);
+
+export const appEventSystemTrackSchema = z.extend(appEventSystemBaseSchema, {
+	event: appEventSystemTrackNameSchema,
+	references: appEventSurveyReferenceSchema,
+});
+
+const appEventLegacySystemTrackSchema = z.pipe(
+	z.extend(appEventBaseSchema, {
+		origin: z.optional(z.literal("system")),
+		event: appEventSystemTrackNameSchema,
+		references: appEventSurveyReferenceSchema,
+	}),
+	z.transform(normalizeSystemAppEventOrigin),
+);
+
+export const appEventCustomerTrackSchema = z.extend(appEventBaseSchema, {
+	origin: z.literal("customer"),
+	event: appEventCustomerNameSchema,
+	// TODO(migration): Normalize Date values in event properties to ISO strings.
+	//   [from=manual-date-property-serialization] [to=protocol-date-property-normalization] [scope=slice] [priority=medium] [impact=medium] [risk=low]
+	properties: z.optional(appEventJsonObjectSchema),
+});
+
+export const appEventTrackSchema = z.union([
+	appEventLegacySystemTrackSchema,
+	appEventCustomerTrackSchema,
+]);
+
+const appEventDiscriminatedPayloadSchema = z.discriminatedUnion("origin", [
+	appEventSystemTrackSchema,
+	appEventCustomerTrackSchema,
+]);
+
+export const appEventPayloadSchema = z.union([
+	appEventLegacySystemTrackSchema,
+	appEventDiscriminatedPayloadSchema,
+]);
+
+export type AppEventTrackInput = z.output<typeof appEventTrackSchema>;
+export type AppEventPayload = z.output<typeof appEventPayloadSchema>;
+export type AppEventFlag = z.output<typeof appEventFlagSchema>;
+export type AppEventCapability = z.output<typeof appEventCapabilitySchema>;

package/src/client-meta.ts

@@ -0,0 +1,25 @@
+import * as z from "zod/mini";
+
+export const clientMetaSchema = z.object({
+	loader: z.enum(["sdk", "gtm", "segment", "rudderstack", "tealium", "custom"]),
+	clientName: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	clientVersion: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	integrator: z.optional(
+		z.object({
+			name: z.optional(z.string().check(z.trim(), z.minLength(1))),
+			version: z.optional(z.string().check(z.trim(), z.minLength(1))),
+		}),
+	),
+	transport: z.optional(
+		z.enum(["script-tag", "esm", "loader", "tag-manager", "snippet"]),
+	),
+	runtime: z.optional(
+		z.object({
+			framework: z.optional(z.enum(["next", "vite", "webpack", "plain"])),
+			runtime: z.optional(z.enum(["browser", "edge"])),
+		}),
+	),
+	notes: z.optional(z.string().check(z.trim(), z.minLength(1))),
+});
+
+export type ClientMeta = z.output<typeof clientMetaSchema>;

package/src/defaults.ts

@@ -0,0 +1,4 @@
+export const DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS: readonly [
+	"class",
+	"data-theme",
+] = ["class", "data-theme"];

package/src/errors.ts

@@ -0,0 +1,58 @@
+import * as z from "zod/mini";
+
+import { clientMetaSchema } from "./client-meta.js";
+
+// ---------------------------------------------------------------------------
+// Error-telemetry definitions shared across widget / host.
+// ---------------------------------------------------------------------------
+
+export const ErrorCategory = {
+	INTERNAL: "INTERNAL",
+	INVALID_USAGE: "INVALID_USAGE",
+	HOST: "HOST",
+} as const;
+
+export type ErrorCategory = (typeof ErrorCategory)[keyof typeof ErrorCategory];
+
+export const ErrorCategorySchema = z.enum([
+	ErrorCategory.INTERNAL,
+	ErrorCategory.INVALID_USAGE,
+	ErrorCategory.HOST,
+]);
+
+export const ErrorEventSchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	message: z.string(),
+	stack: z.optional(z.string()),
+	category: ErrorCategorySchema,
+	timestamp: z.number(),
+	probability: z.optional(z.number()),
+	context: z.object({
+		widgetVersion: z.string(),
+		clientMeta: z.optional(clientMetaSchema),
+		/** When true, telemetry was captured with debug mode on (affects how to interpret context). */
+		debug: z.optional(z.boolean()),
+	}),
+});
+
+export type ErrorEvent = z.output<typeof ErrorEventSchema>;
+
+export type ProtocolErrorCode = "PARSE" | "VERSION" | "UNKNOWN_TYPE";
+
+const MAX_DETAIL_LENGTH = 80;
+
+export class ProtocolError extends Error {
+	code: ProtocolErrorCode;
+	details: string;
+
+	constructor(code: ProtocolErrorCode, details: string) {
+		const short =
+			details.length > MAX_DETAIL_LENGTH
+				? details.slice(0, MAX_DETAIL_LENGTH)
+				: details;
+		super(short);
+		this.code = code;
+		this.details = short;
+	}
+}

package/src/flow-assignments.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import {
+	claimPendingFlowAssignmentsRequestSchema,
+	flowAssignmentRecipientRequestSchema,
+	updateFlowAssignmentLifecycleRequestSchema,
+} from "./flow-assignments";
+
+describe("flow assignment request contracts", () => {
+	it("accepts runtime targeting context for listPending", () => {
+		const result = flowAssignmentRecipientRequestSchema.parse({
+			identities: [{ type: "userId", value: "user_1" }],
+			context: {
+				flags: [{ key: "new_checkout", value: true }],
+				capabilities: [{ key: "checkout.drawer", source: "host-app" }],
+			},
+		});
+
+		expect(result.context?.flags?.[0]).toEqual({
+			key: "new_checkout",
+			value: true,
+		});
+		expect(result.context?.capabilities?.[0]).toEqual({
+			key: "checkout.drawer",
+			source: "host-app",
+		});
+	});
+
+	it("accepts runtime targeting context for claimPending", () => {
+		const result = claimPendingFlowAssignmentsRequestSchema.parse({
+			holdOwnerKey: "inst_1",
+			context: {
+				flags: [{ key: "pricing_test", value: "variant_a" }],
+				capabilities: [{ key: "billing.portal" }],
+			},
+		});
+
+		expect(result.identities).toEqual([]);
+		expect(result.context?.flags?.[0]?.key).toBe("pricing_test");
+		expect(result.context?.capabilities?.[0]?.key).toBe("billing.portal");
+	});
+
+	it("accepts runtime targeting context for lifecycle updates", () => {
+		const result = updateFlowAssignmentLifecycleRequestSchema.parse({
+			identities: [{ type: "userId", value: "user_1" }],
+			flowAssignmentId: "flasn_1",
+			flowVersionId: "flv_1",
+			holdGroupToken: "fahold_1",
+			context: {
+				flags: [{ key: "new_checkout", value: true }],
+				capabilities: [{ key: "checkout.drawer", source: "host-app" }],
+			},
+		});
+
+		expect(result.context?.flags?.[0]).toEqual({
+			key: "new_checkout",
+			value: true,
+		});
+		expect(result.context?.capabilities?.[0]).toEqual({
+			key: "checkout.drawer",
+			source: "host-app",
+		});
+	});
+});

package/src/flow-assignments.ts

@@ -0,0 +1,125 @@
+import * as z from "zod/mini";
+
+import {
+	appEventCapabilitySchema,
+	appEventFlagSchema,
+	appEventIdentitySchema,
+} from "./app-event.js";
+
+export const flowAssignmentStatusSchema = z.enum([
+	"pending",
+	"held",
+	"presented",
+	"completed",
+	"expired",
+	"superseded",
+	"withdrawn_pending",
+	"withdrawn_presented",
+	"withdrawn_final",
+]);
+
+export const flowAssignmentTargetingContextSchema = z.object({
+	flags: z.optional(z.array(appEventFlagSchema)),
+	capabilities: z.optional(z.array(appEventCapabilitySchema)),
+});
+
+export const flowAssignmentRecipientRequestSchema = z.object({
+	identities: z._default(z.array(appEventIdentitySchema), []),
+	context: z.optional(flowAssignmentTargetingContextSchema),
+	at: z.optional(z.number()),
+});
+
+export const flowAssignmentRecordSchema = z.object({
+	flowAssignmentId: z.string().check(z.trim(), z.minLength(1)),
+	flowId: z.string().check(z.trim(), z.minLength(1)),
+	holdGroupToken: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	presentedFlowVersionId: z.optional(
+		z.string().check(z.trim(), z.minLength(1)),
+	),
+	latestFlowVersionId: z.string().check(z.trim(), z.minLength(1)),
+	status: flowAssignmentStatusSchema,
+	assignedAt: z.string(),
+	expiresAt: z.optional(z.string()),
+	heldAt: z.optional(z.string()),
+	holdExpiresAt: z.optional(z.string()),
+	presentedAt: z.optional(z.string()),
+	completedAt: z.optional(z.string()),
+	expiredAt: z.optional(z.string()),
+	supersededAt: z.optional(z.string()),
+	withdrawnAt: z.optional(z.string()),
+	withdrawnFinalAt: z.optional(z.string()),
+});
+
+export const listPendingFlowAssignmentsResponseSchema = z.object({
+	fetchedAt: z.string(),
+	flowAssignments: z.array(flowAssignmentRecordSchema),
+});
+
+export const claimPendingFlowAssignmentsRequestSchema = z.object({
+	identities: z._default(z.array(appEventIdentitySchema), []),
+	context: z.optional(flowAssignmentTargetingContextSchema),
+	holdOwnerKey: z.string().check(z.trim(), z.minLength(1)),
+	at: z.optional(z.number()),
+	limit: z.optional(z.number()),
+});
+
+export const claimPendingFlowAssignmentsResponseSchema = z.object({
+	fetchedAt: z.string(),
+	flowAssignments: z.array(flowAssignmentRecordSchema),
+});
+
+export const updateFlowAssignmentLifecycleRequestSchema = z.object({
+	identities: z._default(z.array(appEventIdentitySchema), []),
+	context: z.optional(flowAssignmentTargetingContextSchema),
+	flowAssignmentId: z.string().check(z.trim(), z.minLength(1)),
+	flowVersionId: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	holdGroupToken: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	at: z.optional(z.number()),
+});
+
+export const releaseFlowAssignmentClaimRequestSchema = z.object({
+	identities: z._default(z.array(appEventIdentitySchema), []),
+	holdGroupToken: z.string().check(z.trim(), z.minLength(1)),
+	holdOwnerKey: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	at: z.optional(z.number()),
+});
+
+export const releaseFlowAssignmentClaimResponseSchema = z.object({
+	releasedCount: z.number(),
+});
+
+export const updateFlowAssignmentLifecycleResponseSchema =
+	flowAssignmentRecordSchema;
+export const nullableUpdateFlowAssignmentLifecycleResponseSchema = z.nullable(
+	updateFlowAssignmentLifecycleResponseSchema,
+);
+
+export type FlowAssignmentStatus = z.output<typeof flowAssignmentStatusSchema>;
+export type FlowAssignmentRecipientRequest = z.output<
+	typeof flowAssignmentRecipientRequestSchema
+>;
+export type FlowAssignmentTargetingContext = z.output<
+	typeof flowAssignmentTargetingContextSchema
+>;
+export type FlowAssignmentRecord = z.output<typeof flowAssignmentRecordSchema>;
+export type ClaimPendingFlowAssignmentsRequest = z.output<
+	typeof claimPendingFlowAssignmentsRequestSchema
+>;
+export type ClaimPendingFlowAssignmentsResponse = z.output<
+	typeof claimPendingFlowAssignmentsResponseSchema
+>;
+export type ListPendingFlowAssignmentsResponse = z.output<
+	typeof listPendingFlowAssignmentsResponseSchema
+>;
+export type ReleaseFlowAssignmentClaimRequest = z.output<
+	typeof releaseFlowAssignmentClaimRequestSchema
+>;
+export type ReleaseFlowAssignmentClaimResponse = z.output<
+	typeof releaseFlowAssignmentClaimResponseSchema
+>;
+export type UpdateFlowAssignmentLifecycleRequest = z.output<
+	typeof updateFlowAssignmentLifecycleRequestSchema
+>;
+export type UpdateFlowAssignmentLifecycleResponse = z.output<
+	typeof updateFlowAssignmentLifecycleResponseSchema
+>;

package/src/host/command-dispatch.ts

@@ -0,0 +1,59 @@
+import { createCommandEnvelope } from "./command-envelope.js";
+import { waitForCommandSettlement } from "./command-settlement.js";
+import type { CommandEnvelope, PublicCommandPayload } from "./sdk-types.js";
+
+/**
+ * A command input: the pure payload with `kind` and command-specific fields.
+ * Distributes over the PublicCommandPayload union so discriminant
+ * narrowing is preserved (e.g. `{ kind: "open", flowId }` type-checks).
+ */
+export type CommandInput = PublicCommandPayload extends infer C
+	? C extends PublicCommandPayload
+		? C
+		: never
+	: never;
+
+type DispatchOptions = {
+	idempotencyKey?: string;
+};
+
+/**
+ * Creates a dispatch function that wraps a command payload in an envelope,
+ * pushes it into the queue, and returns a promise that settles when the
+ * runtime acknowledges it.
+ *
+ * Request IDs are generated automatically.
+ *
+ * @example
+ * ```ts
+ * const dispatch = createCommandDispatch((env) => queue.push(env));
+ * await dispatch({ kind: "open", flowId: "f1", flowHandleId: "h1" });
+ * ```
+ */
+export const createCommandDispatch = (
+	push: (envelope: CommandEnvelope) => void,
+): ((input: CommandInput, options?: DispatchOptions) => Promise<void>) => {
+	return async (
+		input: CommandInput,
+		options?: DispatchOptions,
+	): Promise<void> => {
+		const envelope: CommandEnvelope = createCommandEnvelope({
+			command: input,
+			idempotencyKey:
+				resolveIdempotencyKey(options?.idempotencyKey) ?? undefined,
+		});
+		push(envelope);
+		await waitForCommandSettlement({ requestId: envelope.requestId });
+	};
+};
+
+const resolveIdempotencyKey = (value?: string): string | null => {
+	if (value === undefined) {
+		return null;
+	}
+	const idempotencyKey = value.trim();
+	if (!idempotencyKey) {
+		throw new Error("idempotencyKey must be a non-empty string");
+	}
+	return idempotencyKey;
+};

package/src/host/command-envelope.ts

@@ -0,0 +1,41 @@
+import { createCommandRequestId } from "./request-id.js";
+import type {
+	ClientMeta,
+	CommandEnvelope,
+	PublicCommandPayload,
+} from "./sdk-types.js";
+
+export type CreateCommandEnvelopeInput = {
+	command: PublicCommandPayload;
+	requestId?: string | undefined;
+	idempotencyKey?: string | undefined;
+	instanceId?: string | undefined;
+	clientMeta?: ClientMeta | undefined;
+};
+
+const normalizeOptionalString = (value?: string): string | undefined => {
+	if (value === undefined) {
+		return undefined;
+	}
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : undefined;
+};
+
+export const createCommandEnvelope = (
+	input: CreateCommandEnvelopeInput,
+): CommandEnvelope => {
+	const requestId =
+		normalizeOptionalString(input.requestId) ?? createCommandRequestId();
+	const idempotencyKey =
+		normalizeOptionalString(input.idempotencyKey) ?? requestId;
+	const instanceId = normalizeOptionalString(input.instanceId);
+
+	return {
+		version: "1",
+		command: input.command,
+		requestId,
+		idempotencyKey,
+		...(instanceId !== undefined ? { instanceId } : {}),
+		...(input.clientMeta !== undefined ? { clientMeta: input.clientMeta } : {}),
+	};
+};