@getuserfeedback/protocol 0.6.0 → 0.7.2

package/src/index.ts

@@ -0,0 +1,136 @@
+export {
+	type AppEventCapability,
+	type AppEventFlag,
+	type AppEventJsonValue,
+	type AppEventPayload,
+	type AppEventTrackInput,
+	appEventBaseSchema,
+	appEventCapabilitySchema,
+	appEventContextSchema,
+	appEventCustomerTrackSchema,
+	appEventFlagProviderSchema,
+	appEventFlagSchema,
+	appEventFlowDismissedSchema,
+	appEventIdentitySchema,
+	appEventIdentityTypeSchema,
+	appEventPayloadSchema,
+	appEventSurveyViewedSchema,
+	appEventSystemBaseSchema,
+	appEventSystemTrackSchema,
+	appEventTrackSchema,
+	reservedSystemAppEventNames,
+} from "./app-event.js";
+export {
+	type ClientMeta,
+	clientMetaSchema,
+} from "./client-meta.js";
+export { DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS } from "./defaults.js";
+export type { ErrorEvent, ProtocolErrorCode } from "./errors.js";
+export {
+	ErrorCategory,
+	ErrorCategorySchema,
+	ErrorEventSchema,
+	ProtocolError,
+} from "./errors.js";
+export {
+	type ClaimPendingFlowAssignmentsRequest,
+	type ClaimPendingFlowAssignmentsResponse,
+	claimPendingFlowAssignmentsRequestSchema,
+	claimPendingFlowAssignmentsResponseSchema,
+	type FlowAssignmentRecipientRequest,
+	type FlowAssignmentRecord,
+	type FlowAssignmentStatus,
+	type FlowAssignmentTargetingContext,
+	flowAssignmentRecipientRequestSchema,
+	flowAssignmentRecordSchema,
+	flowAssignmentStatusSchema,
+	flowAssignmentTargetingContextSchema,
+	type ListPendingFlowAssignmentsResponse,
+	listPendingFlowAssignmentsResponseSchema,
+	nullableUpdateFlowAssignmentLifecycleResponseSchema,
+	type ReleaseFlowAssignmentClaimRequest,
+	type ReleaseFlowAssignmentClaimResponse,
+	releaseFlowAssignmentClaimRequestSchema,
+	releaseFlowAssignmentClaimResponseSchema,
+	type UpdateFlowAssignmentLifecycleRequest,
+	type UpdateFlowAssignmentLifecycleResponse,
+	updateFlowAssignmentLifecycleRequestSchema,
+	updateFlowAssignmentLifecycleResponseSchema,
+} from "./flow-assignments.js";
+export {
+	buildIdentityTypeGuidanceMessage,
+	type CustomIdentityTypeValue,
+	getIdentityTypeSuggestion,
+	IDENTITY_TYPE_VALUES,
+	type IdentityTypeValue,
+	isIdentityTypeValue,
+	type StandardIdentityTypeValue,
+} from "./identity-type.js";
+export {
+	isPublicGrantScope,
+	type PublicGrantScope,
+	publicGrantScopeIdSchema,
+} from "./public-grant-scope.js";
+export {
+	type RuntimeEndpoints,
+	resolveApiBaseUrl,
+	resolveCoreUrl,
+	resolveTrpcBaseUrl,
+	runtimeEndpointsSchema,
+} from "./runtime-endpoints.js";
+export {
+	getScopeMeta,
+	isScope,
+	listScopes,
+	SCOPE_IDS,
+	type Scope,
+	scopeIdSchema,
+} from "./scopes.js";
+export {
+	type TrpcSuccessResponse,
+	trpcSuccessResponseSchema,
+} from "./trpc-envelope.js";
+export {
+	type FlowVersionResolution,
+	flowVersionResolutionSchema,
+	type ThemeVersionResolution,
+	themeVersionResolutionSchema,
+} from "./version-resolution.js";
+export {
+	type PublicCommandPayload,
+	parseConfigureOptions,
+	parseInitOptions,
+	parsePublicCommand,
+	publicCommandPayloadSchema,
+	publicWidgetCommandKindSchema,
+} from "./widget-commands.js";
+export {
+	type AuthConfigInput,
+	type AuthJwtConfigInput,
+	authConfigInputSchema,
+	authJwtConfigInputSchema,
+	type ColorSchemeConfigInput,
+	type ConfigureOptions,
+	type ConsentConfigInput,
+	type CoreInstanceConfig,
+	type CoreInstanceConfigInput,
+	colorSchemeConfigInputSchema,
+	configureOptionsSchema,
+	consentConfigInputSchema,
+	coreInstanceConfigSchema,
+	type DebugConfigInput,
+	debugInputSchema,
+	type FlagsConfigInput,
+	flagsConfigInputSchema,
+	type HostCapabilitiesConfigInput,
+	hostCapabilitiesConfigInputSchema,
+	type IdentityConfigInput,
+	INSTANCE_CONFIG_UPDATE_KEYS,
+	type InitOptions,
+	type InstanceUpdateableConfig,
+	identityConfigInputSchema,
+	initOptionsSchema,
+	instanceUpdateableConfigSchema,
+	type TelemetryConfigInput,
+	telemetryConfigInputSchema,
+} from "./widget-config.js";

package/src/protocol-root.test.ts

@@ -0,0 +1,476 @@
+import { describe, expect, it } from "bun:test";
+import type { FlowDismissedPayload, FlowViewedPayload } from "./host";
+import { createCommandEnvelope } from "./host";
+import {
+	appEventCapabilitySchema,
+	appEventFlagSchema,
+	appEventFlowDismissedSchema,
+	appEventIdentityTypeSchema,
+	appEventPayloadSchema,
+	appEventSurveyViewedSchema,
+	appEventTrackSchema,
+	DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS,
+	flowVersionResolutionSchema,
+	getScopeMeta,
+	isPublicGrantScope,
+	isScope,
+	listScopes,
+	parseConfigureOptions,
+	parseInitOptions,
+	parsePublicCommand,
+	publicGrantScopeIdSchema,
+	publicWidgetCommandKindSchema,
+	SCOPE_IDS,
+	themeVersionResolutionSchema,
+} from "./index";
+
+describe("@getuserfeedback/protocol root contract", () => {
+	it("exports the canonical scope ids and metadata helpers", () => {
+		expect(SCOPE_IDS).toContain("functionality.storage");
+		expect(getScopeMeta("analytics.measurement").description).toContain(
+			"analytics events",
+		);
+		expect(listScopes()).toHaveLength(SCOPE_IDS.length);
+		expect(isScope("analytics.measurement")).toBe(true);
+		expect(isScope("not-a-scope")).toBe(false);
+		expect(isPublicGrantScope("analytics.measurement")).toBe(true);
+		expect(isPublicGrantScope("functionality.storage")).toBe(false);
+		expect(
+			publicGrantScopeIdSchema.safeParse("analytics.measurement").success,
+		).toBe(true);
+		expect(
+			publicGrantScopeIdSchema.safeParse("functionality.storage").success,
+		).toBe(false);
+	});
+
+	it("exports the canonical auto-detect color scheme defaults", () => {
+		expect(DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS).toEqual([
+			"class",
+			"data-theme",
+		]);
+	});
+
+	it("parses widget-config flag and capability inputs via canonical app-event schemas", () => {
+		expect(
+			appEventFlagSchema.parse({
+				key: "new_checkout",
+				value: "variant_b",
+				variant: "variant_b",
+			}),
+		).toEqual({
+			key: "new_checkout",
+			value: "variant_b",
+			variant: "variant_b",
+		});
+		expect(
+			appEventCapabilitySchema.parse({
+				key: "checkout.drawer",
+				source: "host-app",
+			}),
+		).toEqual({
+			key: "checkout.drawer",
+			source: "host-app",
+		});
+	});
+
+	it("parses init options from the root contract", () => {
+		const result = parseInitOptions({
+			apiKey: "test-key",
+			colorScheme: {
+				autoDetectColorScheme: ["data-theme"],
+			},
+			defaultConsent: ["analytics.measurement"],
+			capabilities: ["gx.command.open.v1"],
+			flags: [
+				{
+					key: "new_checkout",
+					value: "variant_b",
+					variant: "variant_b",
+					provider: { name: "launchdarkly", environment: "production" },
+				},
+			],
+			hostCapabilities: [{ key: "checkout.drawer", source: "host-app" }],
+		});
+
+		expect(result.apiKey).toBe("test-key");
+		expect(result.defaultConsent).toEqual(["analytics.measurement"]);
+		expect(result.capabilities).toEqual(["gx.command.open.v1"]);
+		expect(result.flags?.[0]).toMatchObject({
+			key: "new_checkout",
+			value: "variant_b",
+		});
+		expect(result.hostCapabilities?.[0]).toEqual({
+			key: "checkout.drawer",
+			source: "host-app",
+		});
+	});
+
+	it("accepts essential scopes in consent array inputs (CMP compatibility)", () => {
+		const result = parseInitOptions({
+			apiKey: "test-key",
+			defaultConsent: ["functionality.storage", "analytics.measurement"],
+		});
+
+		expect(result.defaultConsent).toEqual([
+			"functionality.storage",
+			"analytics.measurement",
+		]);
+	});
+
+	it("parses configure options from the root contract", () => {
+		const result = parseConfigureOptions({
+			auth: {
+				jwt: {
+					token: "jwt-token",
+				},
+			},
+			consent: ["ads.storage"],
+		});
+
+		expect(result.auth?.jwt?.token).toBe("jwt-token");
+		expect(result.consent).toEqual(["ads.storage"]);
+	});
+
+	it("parses public commands from the root contract", () => {
+		const result = parsePublicCommand({
+			kind: "configure",
+			opts: {
+				consent: ["analytics.storage"],
+			},
+		});
+
+		expect(result.kind).toBe("configure");
+		if (result.kind === "configure") {
+			expect(result.opts.consent).toEqual(["analytics.storage"]);
+		}
+	});
+
+	it("parses public customer track commands from the root contract", () => {
+		const result = parsePublicCommand({
+			kind: "track",
+			origin: "customer",
+			event: "Checkout Started",
+			properties: { plan: "starter" },
+		});
+
+		expect(result).toEqual({
+			kind: "track",
+			origin: "customer",
+			event: "Checkout Started",
+			properties: { plan: "starter" },
+		});
+	});
+
+	it("exposes public widget command kind validation aligned with public payloads", () => {
+		expect(publicWidgetCommandKindSchema.safeParse("open").success).toBe(true);
+		expect(publicWidgetCommandKindSchema.safeParse("telemetry").success).toBe(
+			false,
+		);
+	});
+
+	it("strips legacy open.containerRequirement for enum values any and hostOnly", () => {
+		for (const containerRequirement of ["any", "hostOnly"] as const) {
+			const result = parsePublicCommand({
+				kind: "open",
+				flowId: "sur_123",
+				flowHandleId: "handle_open_123",
+				containerRequirement,
+				hideCloseButton: true,
+			});
+
+			expect(result.kind).toBe("open");
+			expect(result).toEqual({
+				kind: "open",
+				flowId: "sur_123",
+				flowHandleId: "handle_open_123",
+				hideCloseButton: true,
+			});
+			expect("containerRequirement" in result).toBe(false);
+		}
+	});
+
+	it("parses public identify commands from the root contract", () => {
+		const withUserId = parsePublicCommand({
+			kind: "identify",
+			userId: "user_123",
+			traits: {
+				email: "user@example.com",
+			},
+		});
+		const withTraitsOnly = parsePublicCommand({
+			kind: "identify",
+			traits: {
+				plan: "pro",
+			},
+		});
+
+		expect(withUserId.kind).toBe("identify");
+		if (withUserId.kind === "identify" && "userId" in withUserId) {
+			expect(withUserId.userId).toBe("user_123");
+			expect(withUserId.traits).toEqual({
+				email: "user@example.com",
+			});
+		}
+
+		expect(withTraitsOnly.kind).toBe("identify");
+		if (withTraitsOnly.kind === "identify" && !("userId" in withTraitsOnly)) {
+			expect(withTraitsOnly.traits).toEqual({
+				plan: "pro",
+			});
+		}
+	});
+
+	it("builds canonical public command envelopes from the host contract", () => {
+		const envelope = createCommandEnvelope({
+			command: {
+				kind: "configure",
+				opts: {
+					consent: ["analytics.storage"],
+				},
+			},
+			instanceId: "instance_123",
+			clientMeta: {
+				loader: "sdk",
+				transport: "snippet",
+			},
+		});
+
+		expect(envelope.version).toBe("1");
+		expect(envelope.command.kind).toBe("configure");
+		expect(envelope.instanceId).toBe("instance_123");
+		expect(envelope.idempotencyKey).toBe(envelope.requestId);
+		expect(envelope.clientMeta).toEqual({
+			loader: "sdk",
+			transport: "snippet",
+		});
+	});
+
+	it("normalizes blank optional envelope identifiers", () => {
+		const envelope = createCommandEnvelope({
+			command: {
+				kind: "configure",
+				opts: {
+					consent: ["analytics.storage"],
+				},
+			},
+			instanceId: "   ",
+			requestId: "  request_123  ",
+			idempotencyKey: "   ",
+		});
+
+		expect(envelope.requestId).toBe("request_123");
+		expect(envelope.idempotencyKey).toBe("request_123");
+		expect("instanceId" in envelope).toBe(false);
+	});
+
+	it("rejects internal navigation context commands from the public contract", () => {
+		expect(() =>
+			parsePublicCommand({
+				kind: "hostContextUpdated",
+				context: {
+					url: "https://example.com/pricing",
+				},
+			}),
+		).toThrow();
+	});
+
+	it("parses public API flow and theme version resolution payloads", () => {
+		expect(
+			flowVersionResolutionSchema.parse({ flowVersionId: "fv_abc" }),
+		).toEqual({ flowVersionId: "fv_abc" });
+		expect(
+			themeVersionResolutionSchema.parse({ themeVersionId: "tv_xyz" }),
+		).toEqual({ themeVersionId: "tv_xyz" });
+		expect(() =>
+			flowVersionResolutionSchema.parse({ flowVersionId: "  " }),
+		).toThrow();
+	});
+
+	it("parses app event track and payload shapes", () => {
+		const track = appEventTrackSchema.parse({
+			event: "Flow Viewed",
+			references: { surveyId: "sur_1" },
+			identities: [{ type: "anonymousId", value: "anon" }],
+			context: {
+				flags: [
+					{
+						key: "new_checkout",
+						value: "variant_b",
+						variant: "variant_b",
+						provider: {
+							name: "launchdarkly",
+							project: "mobile",
+							environment: "production",
+						},
+					},
+				],
+				capabilities: [{ key: "new_checkout" }],
+			},
+		});
+		expect(track.event).toBe("Flow Viewed");
+		expect(track.origin).toBe("system");
+		expect(track.references.surveyId).toBe("sur_1");
+		expect(track.context?.flags?.[0]).toMatchObject({
+			key: "new_checkout",
+			value: "variant_b",
+		});
+		expect(track.context?.capabilities?.[0]).toEqual({
+			key: "new_checkout",
+		});
+
+		const viewed = appEventPayloadSchema.parse({
+			origin: "system",
+			event: "Flow Viewed",
+			references: { surveyId: "sur_2" },
+		});
+		expect(viewed.event).toBe("Flow Viewed");
+
+		const customer = appEventTrackSchema.parse({
+			origin: "customer",
+			event: "Checkout Started",
+			properties: {
+				plan: "starter",
+				step: 1,
+				renewal: null,
+				items: ["seat", { count: 2 }],
+			},
+		});
+		expect(customer).toEqual({
+			origin: "customer",
+			event: "Checkout Started",
+			properties: {
+				plan: "starter",
+				step: 1,
+				renewal: null,
+				items: ["seat", { count: 2 }],
+			},
+		});
+
+		for (const properties of [
+			{ callback: () => undefined },
+			{ amount: Number.NaN },
+			{ amount: Number.POSITIVE_INFINITY },
+			{ orderId: BigInt(1) },
+			{ renewedAt: new globalThis.Date("2026-05-08T00:00:00.000Z") },
+		]) {
+			expect(() =>
+				appEventTrackSchema.parse({
+					origin: "customer",
+					event: "Checkout Started",
+					properties,
+				}),
+			).toThrow();
+		}
+
+		expect(() =>
+			appEventTrackSchema.parse({
+				event: "Unknown",
+				references: { surveyId: "sur_1" },
+			}),
+		).toThrow();
+		expect(() =>
+			appEventTrackSchema.parse({
+				origin: "customer",
+				event: "Flow Viewed",
+			}),
+		).toThrow();
+		expect(() =>
+			appEventTrackSchema.parse({
+				origin: "customer",
+				event: "flow viewed",
+			}),
+		).toThrow();
+	});
+
+	it("keeps flag value validation separate from track properties", () => {
+		expect(
+			appEventFlagSchema.parse({
+				key: "new_checkout",
+				value: {
+					variant: "treatment",
+					enabled: true,
+					rollout: 50,
+				},
+			}),
+		).toEqual({
+			key: "new_checkout",
+			value: {
+				variant: "treatment",
+				enabled: true,
+				rollout: 50,
+			},
+		});
+
+		expect(() =>
+			appEventFlagSchema.parse({
+				key: "new_checkout",
+				value: { callback: () => undefined },
+			}),
+		).toThrow();
+	});
+
+	it("keeps exported system app event schemas compatible with legacy no-origin inputs", () => {
+		const viewed = appEventSurveyViewedSchema.parse({
+			event: "Flow Viewed",
+			references: { surveyId: "sur_1" },
+		});
+		const dismissed = appEventFlowDismissedSchema.parse({
+			event: "Flow Dismissed",
+			references: { surveyId: "sur_2" },
+		});
+
+		expect(viewed.origin).toBe("system");
+		expect(dismissed.origin).toBe("system");
+	});
+
+	it("keeps legacy system app event SDK input types origin-optional", () => {
+		const viewed: FlowViewedPayload = {
+			event: "Flow Viewed",
+			references: { surveyId: "sur_1" },
+		};
+		const dismissed: FlowDismissedPayload = {
+			event: "Flow Dismissed",
+			references: { surveyId: "sur_2" },
+		};
+
+		expect(viewed.origin).toBeUndefined();
+		expect(dismissed.origin).toBeUndefined();
+	});
+
+	it("suggests canonical identity types for app event aliases", () => {
+		expect(() =>
+			appEventTrackSchema.parse({
+				event: "Flow Viewed",
+				references: { surveyId: "sur_1" },
+				identities: [{ type: "email", value: "person@example.com" }],
+			}),
+		).toThrow(/traits\.email/);
+	});
+
+	it("keeps identity type guidance on invalid app event identity values", () => {
+		expect(() => appEventIdentityTypeSchema.safeParse("email")).not.toThrow();
+
+		const result = appEventIdentityTypeSchema.safeParse("email");
+
+		expect(result.success).toBe(false);
+		if (!result.success) {
+			expect(result.error.issues).toEqual([
+				expect.objectContaining({
+					code: "custom",
+					message:
+						'Unsupported identity type "email". Use "traits.email" instead.',
+				}),
+			]);
+		}
+
+		expect(() => appEventIdentityTypeSchema.parse("email")).toThrow(
+			/traits\.email/,
+		);
+	});
+
+	it("accepts first-class custom app event identity types", () => {
+		const result = appEventIdentityTypeSchema.parse("custom.shopifyCustomerId");
+
+		expect(result).toBe("custom.shopifyCustomerId");
+	});
+});

package/src/public-grant-scope.ts

@@ -0,0 +1,25 @@
+import * as z from "zod/mini";
+
+const publicGrantScopeIds: readonly [
+	"analytics.storage",
+	"analytics.measurement",
+	"personalization.storage",
+	"ads.storage",
+	"ads.user_data",
+	"ads.personalization",
+] = [
+	"analytics.storage",
+	"analytics.measurement",
+	"personalization.storage",
+	"ads.storage",
+	"ads.user_data",
+	"ads.personalization",
+];
+
+export const publicGrantScopeIdSchema = z.enum(publicGrantScopeIds);
+
+export type PublicGrantScope = z.output<typeof publicGrantScopeIdSchema>;
+
+export function isPublicGrantScope(value: unknown): value is PublicGrantScope {
+	return publicGrantScopeIdSchema.safeParse(value).success;
+}

package/src/runtime-endpoints.ts

@@ -0,0 +1,69 @@
+import * as z from "zod/mini";
+
+const absoluteUrlSchema = z.string().check(z.trim(), z.url());
+
+export const runtimeEndpointsSchema = z.strictObject({
+	apiUrl: z.optional(absoluteUrlSchema),
+	coreUrl: z.optional(absoluteUrlSchema),
+});
+
+export type RuntimeEndpoints = z.output<typeof runtimeEndpointsSchema>;
+
+const parseAbsoluteUrl = (value: string | undefined): URL | null => {
+	if (!value) {
+		return null;
+	}
+	try {
+		return new URL(value);
+	} catch {
+		return null;
+	}
+};
+
+const normalizeOrigin = (value: string | undefined): string | null => {
+	const parsed = parseAbsoluteUrl(value);
+	if (!parsed) {
+		return null;
+	}
+	return parsed.origin;
+};
+
+export const resolveCoreUrl = (
+	runtimeEndpoints: RuntimeEndpoints | undefined,
+): URL | null => {
+	return parseAbsoluteUrl(runtimeEndpoints?.coreUrl);
+};
+
+export const resolveApiBaseUrl = (
+	runtimeEndpoints: RuntimeEndpoints | undefined,
+): URL | null => {
+	const apiUrl = runtimeEndpoints?.apiUrl;
+	const parsed = parseAbsoluteUrl(apiUrl);
+	if (!parsed) {
+		return null;
+	}
+	if (!parsed.pathname || parsed.pathname === "/") {
+		return null;
+	}
+	if (!parsed.pathname.endsWith("/")) {
+		parsed.pathname = `${parsed.pathname}/`;
+	}
+	return parsed;
+};
+
+export const resolveTrpcBaseUrl = (
+	runtimeEndpoints: RuntimeEndpoints | undefined,
+): URL | null => {
+	const apiBaseUrl = resolveApiBaseUrl(runtimeEndpoints);
+	if (!apiBaseUrl) {
+		return null;
+	}
+	const normalizedApiPath = apiBaseUrl.pathname.endsWith("/")
+		? apiBaseUrl.pathname.slice(0, -1)
+		: apiBaseUrl.pathname;
+	if (!normalizedApiPath.endsWith("/v1")) {
+		return null;
+	}
+	const trpcPath = normalizedApiPath.slice(0, -"/v1".length) || "/";
+	return new URL(trpcPath, `${normalizeOrigin(apiBaseUrl.toString()) ?? ""}/`);
+};