@getuserfeedback/protocol 0.6.1 → 0.8.0

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
+>;

package/src/widget-commands.ts

@@ -0,0 +1,162 @@
+import * as z from "zod/mini";
+import {
+	appEventCustomerTrackSchema,
+	appEventExternalIdSchema,
+} from "./app-event.js";
+import {
+	type ConfigureOptions,
+	configureOptionsSchema,
+	type InitOptions,
+	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));
+
+/** Public command kinds accepted from host / SDK before core dispatch. */
+const publicWidgetCommandKinds = [
+	"open",
+	"prefetch",
+	"prerender",
+	"identify",
+	"setContainer",
+	"setDefaultContainerPolicy",
+	"configure",
+	"init",
+	"close",
+	"reset",
+	"track",
+] as const;
+
+export const publicWidgetCommandKindSchema = z.enum(publicWidgetCommandKinds);
+
+const isHTMLElementLike = (value: unknown): value is HTMLElement => {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+	if (typeof HTMLElement !== "undefined" && value instanceof HTMLElement) {
+		return true;
+	}
+	if (!("nodeType" in value) || !("appendChild" in value)) {
+		return false;
+	}
+	const nodeType = Reflect.get(value, "nodeType");
+	const appendChild = Reflect.get(value, "appendChild");
+	return nodeType === 1 && typeof appendChild === "function";
+};
+
+const htmlElementOrNullSchema = z.custom<HTMLElement | null>(
+	(value: unknown) => value === null || isHTMLElementLike(value),
+	{
+		message: "Container must be null or an HTMLElement with nodeType=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),
+	}),
+]);
+
+// TODO(migration): After telemetry confirms no remaining `open.containerRequirement` in host command queues, remove the optional field and transform so unknown keys fail under `.strict()` again.
+// [from=legacy-open-container-requirement] [to=strict-public-open-only] [scope=slice] [priority=low] [impact=medium] [risk=low]
+const legacyOpenContainerRequirementSchema = z.enum(["any", "hostOnly"]);
+
+export const containerPolicySchema = z.discriminatedUnion("kind", [
+	z.strictObject({
+		kind: z.literal("floating"),
+	}),
+	z.strictObject({
+		kind: z.literal("hostContainer"),
+		host: htmlElementOrNullSchema,
+		sharing: z.enum(["shared", "perFlowRun"]),
+	}),
+]);
+
+const openPublicPayloadSchema = z.pipe(
+	z.strictObject({
+		kind: z.literal("open"),
+		flowId: flowIdSchema,
+		flowHandleId: z.optional(flowHandleIdSchema),
+		container: z.optional(htmlElementOrNullSchema),
+		/** Accepted for legacy browser SDK payloads; stripped before dispatch. */
+		containerRequirement: z.optional(legacyOpenContainerRequirementSchema),
+		hideCloseButton: z.optional(z.boolean()),
+	}),
+	z.transform(({ containerRequirement: _legacy, ...rest }) => rest),
+);
+
+export const publicCommandPayloadSchema = z.union([
+	z.discriminatedUnion("kind", [
+		openPublicPayloadSchema,
+		z.strictObject({
+			kind: z.literal("prefetch"),
+			flowId: flowIdSchema,
+			flowHandleId: z.optional(flowHandleIdSchema),
+		}),
+		z.strictObject({
+			kind: z.literal("prerender"),
+			flowId: flowIdSchema,
+			flowHandleId: z.optional(flowHandleIdSchema),
+			hideCloseButton: z.optional(z.boolean()),
+		}),
+		z.strictObject({
+			kind: z.literal("setContainer"),
+			flowHandleId: flowHandleIdSchema,
+			container: htmlElementOrNullSchema,
+		}),
+		z.strictObject({
+			kind: z.literal("setDefaultContainerPolicy"),
+			policy: containerPolicySchema,
+		}),
+		z.strictObject({
+			kind: z.literal("configure"),
+			opts: configureOptionsSchema,
+		}),
+		z.strictObject({
+			kind: z.literal("init"),
+			opts: initOptionsSchema,
+		}),
+		z.strictObject({
+			kind: z.literal("close"),
+			flowHandleId: z.optional(flowHandleIdSchema),
+		}),
+		z.strictObject({
+			kind: z.literal("reset"),
+		}),
+		z.extend(appEventCustomerTrackSchema, {
+			kind: z.literal("track"),
+		}),
+	]),
+	identifyPayloadSchema,
+]);
+
+export type PublicCommandPayload = z.output<typeof publicCommandPayloadSchema>;
+
+export type ContainerPolicy = z.output<typeof containerPolicySchema>;
+
+export function parseInitOptions(input: unknown): InitOptions {
+	return initOptionsSchema.parse(input);
+}
+
+export function parseConfigureOptions(input: unknown): ConfigureOptions {
+	return configureOptionsSchema.parse(input);
+}
+
+export function parsePublicCommand(input: unknown): PublicCommandPayload {
+	return publicCommandPayloadSchema.parse(input);
+}

package/src/widget-config.ts

@@ -0,0 +1,164 @@
+import * as z from "zod/mini";
+import {
+	appEventCapabilitySchema,
+	appEventExternalIdSchema,
+	appEventFlagSchema,
+} from "./app-event.js";
+import { clientMetaSchema } from "./client-meta.js";
+import { DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS } from "./defaults.js";
+import { runtimeEndpointsSchema } from "./runtime-endpoints.js";
+import { scopeIdSchema } from "./scopes.js";
+
+const colorSchemeValueSchema = z.enum(["light", "dark", "system"]);
+
+const autoDetectColorSchemeArraySchema = z
+	.array(z.string().check(z.trim(), z.minLength(1)))
+	.check(z.minLength(1));
+
+export const colorSchemeConfigInputSchema = z.union([
+	z.strictObject({
+		autoDetectColorScheme: autoDetectColorSchemeArraySchema,
+	}),
+	colorSchemeValueSchema,
+]);
+
+export type ColorSchemeConfigInput = z.output<
+	typeof colorSchemeConfigInputSchema
+>;
+
+export const telemetryConfigInputSchema = z.object({
+	enabled: z.optional(z.boolean()),
+});
+
+export type TelemetryConfigInput = z.output<typeof telemetryConfigInputSchema>;
+
+export const consentConfigInputSchema = z.union([
+	z.enum(["granted", "denied", "pending", "revoked"]),
+	z.array(scopeIdSchema),
+]);
+
+export type ConsentConfigInput = z.output<typeof consentConfigInputSchema>;
+
+export const debugInputSchema = z.union([
+	z.boolean(),
+	z.string(),
+	z.array(z.string()),
+]);
+
+export type DebugConfigInput = z.output<typeof debugInputSchema>;
+
+export const authJwtConfigInputSchema = z.object({
+	token: z.string().check(z.trim(), z.minLength(1)),
+});
+
+export type AuthJwtConfigInput = z.output<typeof authJwtConfigInputSchema>;
+
+export const authConfigInputSchema = z.object({
+	jwt: z.optional(z.union([authJwtConfigInputSchema, z.null()])),
+});
+
+export type AuthConfigInput = z.output<typeof authConfigInputSchema>;
+
+export const identityConfigInputSchema = z.object({
+	anonymousId: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	userId: z.optional(z.string().check(z.trim(), z.minLength(1))),
+	traits: z.optional(z.record(z.string(), z.unknown())),
+	externalIds: z.optional(
+		z.array(appEventExternalIdSchema).check(z.maxLength(20)),
+	),
+});
+
+export type IdentityConfigInput = z.output<typeof identityConfigInputSchema>;
+
+export const flagsConfigInputSchema = z.array(appEventFlagSchema);
+
+export type FlagsConfigInput = z.output<typeof flagsConfigInputSchema>;
+
+export const hostCapabilitiesConfigInputSchema = z.array(
+	appEventCapabilitySchema,
+);
+
+export type HostCapabilitiesConfigInput = z.output<
+	typeof hostCapabilitiesConfigInputSchema
+>;
+
+export const configureOptionsSchema = z.strictObject({
+	colorScheme: z.optional(colorSchemeConfigInputSchema),
+	consent: z.optional(consentConfigInputSchema),
+	auth: z.optional(authConfigInputSchema),
+});
+
+export type ConfigureOptions = z.output<typeof configureOptionsSchema>;
+
+export const initOptionsSchema = z.strictObject({
+	apiKey: z.string().check(z.trim(), z.minLength(1)),
+	colorScheme: z.optional(colorSchemeConfigInputSchema),
+	disableTelemetry: z.optional(z.boolean()),
+	enableDebug: z.optional(debugInputSchema),
+	defaultConsent: z.optional(consentConfigInputSchema),
+	clientMeta: z.optional(clientMetaSchema),
+	capabilities: z.optional(z.array(z.string())),
+	flags: z.optional(flagsConfigInputSchema),
+	hostCapabilities: z.optional(hostCapabilitiesConfigInputSchema),
+	runtimeEndpoints: z.optional(runtimeEndpointsSchema),
+});
+
+export type InitOptions = z.output<typeof initOptionsSchema>;
+
+export const DEFAULT_COLOR_SCHEME_CONFIG: ColorSchemeConfigInput = {
+	autoDetectColorScheme: [...DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS],
+};
+
+/**
+ * Schema for the subset of instance config that can be updated via merge (any source).
+ * Telemetry, enableDebug, clientMeta, SDK protocol capabilities, customer
+ * flags, and customer host capabilities are set at registration only.
+ */
+export const instanceUpdateableConfigSchema = z.strictObject({
+	colorScheme: z.optional(colorSchemeConfigInputSchema),
+	consent: z.optional(consentConfigInputSchema),
+	auth: z.optional(authConfigInputSchema),
+	identity: z.optional(identityConfigInputSchema),
+});
+
+export type InstanceUpdateableConfig = z.output<
+	typeof instanceUpdateableConfigSchema
+>;
+
+/** Keys that may be merged into instance config (updatable subset). */
+export const INSTANCE_CONFIG_UPDATE_KEYS: (keyof InstanceUpdateableConfig)[] = [
+	"colorScheme",
+	"consent",
+	"auth",
+	"identity",
+];
+
+/**
+ * Schema for resolved instance config state. Used when producing or validating
+ * stored config (e.g. after register or merge). Defaults are applied here so
+ * state always has a full shape; parse partial input with this schema to get
+ * resolved state. For update shape use InstanceUpdateableConfig. Configure
+ * command opts are in widget-commands (widgetConfigUpdateSchema).
+ */
+export const coreInstanceConfigSchema = z.strictObject({
+	colorScheme: z._default(z.optional(colorSchemeConfigInputSchema), {
+		autoDetectColorScheme: [...DEFAULT_AUTO_DETECT_COLOR_SCHEME_ATTRS],
+	}),
+	disableTelemetry: z._default(z.optional(z.boolean()), false),
+	enableDebug: z._default(z.optional(debugInputSchema), false),
+	consent: z.optional(consentConfigInputSchema),
+	auth: z.optional(authConfigInputSchema),
+	identity: z.optional(identityConfigInputSchema),
+	apiKey: z.string().check(z.trim(), z.minLength(1)),
+	clientMeta: z.optional(clientMetaSchema),
+	capabilities: z.optional(z.array(z.string())),
+	flags: z.optional(flagsConfigInputSchema),
+	hostCapabilities: z.optional(hostCapabilitiesConfigInputSchema),
+	runtimeEndpoints: z.optional(runtimeEndpointsSchema),
+});
+
+/** Input shape for instance config (partial; used for register/merge). */
+export type CoreInstanceConfigInput = z.input<typeof coreInstanceConfigSchema>;
+
+/** Resolved instance config state (defaults applied). */
+export type CoreInstanceConfig = z.output<typeof coreInstanceConfigSchema>;