@getuserfeedback/protocol 0.6.1 → 0.7.2

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()) ?? ""}/`);
+};

package/src/scopes.ts

@@ -0,0 +1,79 @@
+import * as z from "zod/mini";
+
+export const SCOPE_IDS: readonly [
+	"functionality.storage",
+	"security.storage",
+	"analytics.storage",
+	"analytics.measurement",
+	"personalization.storage",
+	"ads.storage",
+	"ads.user_data",
+	"ads.personalization",
+] = [
+	"functionality.storage",
+	"security.storage",
+	"analytics.storage",
+	"analytics.measurement",
+	"personalization.storage",
+	"ads.storage",
+	"ads.user_data",
+	"ads.personalization",
+];
+
+export const scopeIdSchema = z.enum(SCOPE_IDS);
+
+export type Scope = (typeof SCOPE_IDS)[number];
+
+export function isScope(value: unknown): value is Scope {
+	return scopeIdSchema.safeParse(value).success;
+}
+
+export type ScopeMeta = {
+	description: string;
+};
+
+const scopeMetaById: Record<Scope, ScopeMeta> = {
+	"functionality.storage": {
+		description:
+			"Allow essential storage for core widget behavior (e.g., frequency capping, dismissals, draft answers).",
+	},
+	"security.storage": {
+		description:
+			"Allow storage used for fraud/abuse prevention and integrity checks.",
+	},
+	"analytics.storage": {
+		description:
+			"Allow storage for analytics identifiers enabling consistent cross-session measurement.",
+	},
+	"analytics.measurement": {
+		description:
+			"Allow sending analytics events; can operate without storage when needed.",
+	},
+	"personalization.storage": {
+		description:
+			"Allow storage used to personalize the widget UI/targeting (non-ads).",
+	},
+	"ads.storage": {
+		description:
+			"Allow storage for advertising identifiers and conversion cookies.",
+	},
+	"ads.user_data": {
+		description:
+			"Allow sending user data to ad platforms when legally permitted.",
+	},
+	"ads.personalization": {
+		description:
+			"Allow personalized advertising signals and interest-based targeting.",
+	},
+};
+
+export function getScopeMeta(id: Scope): ScopeMeta {
+	return scopeMetaById[id];
+}
+
+export function listScopes(): ReadonlyArray<{ id: Scope } & ScopeMeta> {
+	return SCOPE_IDS.map((id) => ({
+		id,
+		...getScopeMeta(id),
+	}));
+}

package/src/trpc-envelope.ts

@@ -0,0 +1,9 @@
+import * as z from "zod/mini";
+
+export const trpcSuccessResponseSchema = z.object({
+	result: z.object({
+		data: z.unknown(),
+	}),
+});
+
+export type TrpcSuccessResponse = z.output<typeof trpcSuccessResponseSchema>;

package/src/version-resolution.ts

@@ -0,0 +1,18 @@
+import * as z from "zod/mini";
+
+const versionIdSchema = z.string().check(z.trim(), z.minLength(1));
+
+export const flowVersionResolutionSchema = z.object({
+	flowVersionId: versionIdSchema,
+});
+
+export const themeVersionResolutionSchema = z.object({
+	themeVersionId: versionIdSchema,
+});
+
+export type FlowVersionResolution = z.output<
+	typeof flowVersionResolutionSchema
+>;
+export type ThemeVersionResolution = z.output<
+	typeof themeVersionResolutionSchema
+>;