@getuserfeedback/protocol 0.6.1 → 0.8.0

package/src/host/sdk-types.ts

@@ -0,0 +1,528 @@
+/**
+ * getuserfeedback widget SDK public API.
+ *
+ * {@link FlowState} lives in `./host-event-contract` (re-exported from the `@getuserfeedback/protocol/host` barrel).
+ */
+
+import type { Scope } from "../scopes.js";
+
+// ── Events and identity ─────────────────────────────────────────────
+
+/**
+ * Identifier types supported by event tracking and identity resolution.
+ *
+ * Business-specific identifiers are sent as Segment-compatible
+ * `context.externalIds` entries on app events or identify options.
+ *
+ * @see https://getuserfeedback.com/docs/guides/identity-resolution
+ */
+export type AppEventIdentityType =
+	| "anonymousId"
+	| "userId"
+	| "traits.email"
+	| "traits.phone"
+	| "context.device.id"
+	| "context.device.advertisingId"
+	| "context.device.token";
+
+/** A single standard identifier, such as a user ID, anonymous ID, email, or device ID. */
+export type AppEventIdentity = {
+	type: AppEventIdentityType;
+	value: string;
+};
+
+/**
+ * Segment-compatible external identifier.
+ *
+ * Only `collection: "users"` participates in person identity resolution today.
+ */
+export type AppEventExternalId = {
+	id: string;
+	type: string;
+	collection: "users";
+	encoding: "none";
+};
+
+/** Page, feature flag, and capability context attached to an event. */
+export type AppEventContext = {
+	page?: {
+		path?: string;
+		referrer?: string;
+		search?: string;
+	};
+	locale?: string;
+	userAgent?: string;
+	externalIds?: AppEventExternalId[] | undefined;
+	flags?: AppEventFlag[] | undefined;
+	capabilities?: AppEventCapability[] | undefined;
+};
+
+/** Supported feature flag value shape. */
+export type AppEventFlagValue =
+	| string
+	| number
+	| boolean
+	| null
+	| AppEventFlagValue[]
+	| { [key: string]: AppEventFlagValue };
+
+/**
+ * Supported event property value shape.
+ *
+ * @see https://getuserfeedback.com/docs/reference/events
+ */
+export type AppEventJsonValue = AppEventFlagValue;
+
+/** Feature flag provider metadata. */
+export type AppEventFlagProvider = {
+	name: string;
+	project?: string | undefined;
+	environment?: string | undefined;
+};
+
+/** Feature flag evaluation context attached to widget initialization or events. */
+export type AppEventFlag = {
+	key: string;
+	target?: string | undefined;
+	value: AppEventFlagValue;
+	variant?: string | undefined;
+	origin?: "runtime_config" | "trigger_context" | "provider_sync" | "api";
+	provider?: AppEventFlagProvider | undefined;
+	status?: string | undefined;
+	reason?: string | undefined;
+	evaluatedAt?: string | undefined;
+};
+
+/** Host capability context attached to widget initialization or events. */
+export type AppEventCapability = {
+	key: string;
+	source?: string | undefined;
+	provider?: AppEventFlagProvider | undefined;
+};
+
+/** Feature flag evaluations accepted by SDK initialization. */
+export type FlagsInput = AppEventFlag[] | Record<string, AppEventFlagValue>;
+
+/** Host capabilities accepted by SDK initialization. */
+export type CapabilitiesInput = Array<string | AppEventCapability>;
+
+/** Optional fields shared by event payloads. */
+export type AppEventBase = {
+	traits?: Record<string, unknown> | undefined;
+	identities?: AppEventIdentity[] | undefined;
+	context?: AppEventContext | undefined;
+	messageId?: string | undefined;
+	timestamp?: number | undefined;
+};
+
+/** Reference to a specific survey or flow. */
+export type AppEventSurveyReference = {
+	surveyId: string;
+};
+
+/** Event payload emitted when a flow is shown. */
+export type FlowViewedPayload = AppEventBase & {
+	origin?: "system" | undefined;
+	event: "Flow Viewed";
+	references: AppEventSurveyReference;
+};
+
+/** Event payload emitted when a user dismisses a flow. */
+export type FlowDismissedPayload = AppEventBase & {
+	origin?: "system" | undefined;
+	event: "Flow Dismissed";
+	references: AppEventSurveyReference;
+};
+
+/**
+ * Event payload sent with `client.track()`.
+ *
+ * @see https://getuserfeedback.com/docs/reference/events
+ */
+export type CustomerTrackPayload = AppEventBase & {
+	origin: "customer";
+	event: string;
+	properties?: Record<string, AppEventJsonValue> | undefined;
+};
+
+/**
+ * Event payload union. Use `origin` as the discriminator when handling the
+ * union directly.
+ */
+export type AppEventPayload =
+	| FlowViewedPayload
+	| FlowDismissedPayload
+	| CustomerTrackPayload;
+
+// ── Client metadata ─────────────────────────────────────────────────
+
+/** How the widget was loaded, such as SDK, GTM, Segment, or a custom loader. */
+export type ClientMetaLoader =
+	| "sdk"
+	| "gtm"
+	| "segment"
+	| "rudderstack"
+	| "tealium"
+	| "custom";
+
+/** Delivery method for the widget script. */
+export type ClientMetaTransport =
+	| "script-tag"
+	| "esm"
+	| "loader"
+	| "tag-manager"
+	| "snippet";
+
+/** Detected or configured front-end framework. */
+export type ClientMetaRuntimeFramework = "next" | "vite" | "webpack" | "plain";
+
+/** Runtime environment (browser or edge). */
+export type ClientMetaRuntimeEnv = "browser" | "edge";
+
+/** Metadata about the client integration, used for diagnostics and support. */
+export type ClientMeta = {
+	loader: ClientMetaLoader;
+	clientName?: string | undefined;
+	clientVersion?: string | undefined;
+	integrator?:
+		| {
+				name?: string | undefined;
+				version?: string | undefined;
+		  }
+		| undefined;
+	transport?: ClientMetaTransport | undefined;
+	runtime?:
+		| {
+				framework?: ClientMetaRuntimeFramework | undefined;
+				runtime?: ClientMetaRuntimeEnv | undefined;
+		  }
+		| undefined;
+	notes?: string | undefined;
+};
+
+export type RuntimeEndpoints = {
+	apiUrl?: string | undefined;
+	coreUrl?: string | undefined;
+};
+
+/** A single response metadata tag value preserved with a submitted response. */
+export type ResponseMetadataTagValue = string | string[];
+
+/** Optional metadata tags the host can attach to a widget flow run. */
+export type ResponseMetadataInput = {
+	tags?: Record<string, ResponseMetadataTagValue> | undefined;
+};
+
+// ── Configuration (color scheme, consent, auth) ─────────────────────────────
+
+/**
+ * Use host attributes to auto-detect the color scheme ("light" by default). The widget observes these attributes on body and html elements,
+ *
+ * class="dark" or data-theme="dark" on html or body elements will set the widget to dark mode.
+ *
+ * class="light" or data-theme="light" will set the widget to light mode.
+ *
+ * class="system" or data-theme="system" will set the widget to follow the user's OS/browser preference (prefers-color-scheme).
+ */
+export type ColorSchemeAutoDetect = {
+	/** List of host attribute names (html or body) to observe for color scheme.
+	 *
+	 * Default: ["class", "data-theme"]
+	 */
+	autoDetectColorScheme: string[];
+};
+
+/**
+ * Color scheme: either auto-detect from host html and body attributes (default) or provide an explicit value.
+ * - { autoDetectColorScheme: ["class", "data-theme"] }
+ * - "light" | "dark" | "system"
+ */
+export type ColorSchemeConfig =
+	| ColorSchemeAutoDetect
+	| "light"
+	| "dark"
+	| "system";
+
+/** Whether telemetry is enabled. */
+export type TelemetryConfig = {
+	enabled?: boolean | undefined;
+};
+
+/** When true, prints debug logs to console. Narrow down with a namespace string/array eg. `["loader", "handshake"]`. Default `false`. */
+export type DebugConfig = boolean | string | string[];
+
+/** Status of a consent decision (pending, granted, denied, revoked). */
+export type ConsentStatus = "pending" | "granted" | "denied" | "revoked";
+
+/**
+ * Supported consent scope identifiers for explicit allow-list grants (full CMP-aligned set).
+ * Alias for {@link Scope}; kept for backward-compatible imports.
+ */
+export type GrantScope = Scope;
+
+/** Consent configuration. Use a single decision for all scopes, or provide an explicit allow-list of granted scopes. */
+export type ConsentConfig = ConsentStatus | Scope[];
+
+/** Auth configuration, such as a JWT for authenticated flows. */
+export type AuthConfig = {
+	jwt?: { token: string } | null | undefined;
+};
+
+/**
+ * Runtime configuration updates accepted by `client.configure()`.
+ *
+ * @see https://getuserfeedback.com/docs/security-and-privacy/compliance-and-consent
+ */
+export type ConfigureOptions = {
+	colorScheme?: ColorSchemeConfig | undefined;
+	consent?: ConsentConfig | undefined;
+	auth?: AuthConfig | undefined;
+};
+
+/** @internal Options when initializing the widget: API key, color scheme, disableTelemetry, enableDebug, defaultConsent, capabilities, and optional host targeting context. */
+export type InitOptions = {
+	apiKey: string;
+	colorScheme?: ColorSchemeConfig | undefined;
+	disableTelemetry?: boolean | undefined;
+	enableDebug?: DebugConfig | undefined;
+	defaultConsent?: ConsentConfig | undefined;
+	clientMeta?: ClientMeta | undefined;
+	capabilities?: string[] | undefined;
+	flags?: AppEventFlag[] | undefined;
+	hostCapabilities?: AppEventCapability[] | undefined;
+	runtimeEndpoints?: RuntimeEndpoints | undefined;
+};
+
+export type ClientOptions = {
+	/** Your project API key. */
+	apiKey: string;
+	/** Color scheme config: host-driven (loader observes attributes) or explicit. */
+	colorScheme?: ColorSchemeConfig | undefined;
+	/**
+	 * Initial consent state.
+	 *
+	 * Default: `granted` (all scopes).
+	 *
+	 * Accepts either a single decision (`granted` | `denied` | `pending` | `revoked`)
+	 * or an explicit allow-list of additional granted scopes (`Scope[]`).
+	 *
+	 * For strict privacy guarantees, use `pending` at init time and later call `client.configure({ consent })` after
+	 * the user makes a consent choice via your CMP or UI.
+	 *
+	 * In array form, listed scopes are granted and all other non-essential scopes are denied.
+	 *
+	 * Essential baseline scopes are always granted for core widget operation and cannot be denied:
+	 * - `functionality.storage`
+	 * - `security.storage`
+	 *
+	 * @see https://getuserfeedback.com/docs/security-and-privacy/compliance-and-consent
+	 */
+	defaultConsent?: ConsentConfig | undefined;
+	/** When true, prints debug logs to console. Narrow down with a namespace string/array eg. ```["loader", "handshake"]```. Default `false`.
+	 */
+	enableDebug?: DebugConfig | undefined;
+	/** When true, the widget does not load automatically; call `client.load()` when ready. Default `false` */
+	disableAutoLoad?: boolean;
+	/** Disable anonymous widget telemetry.
+	 *
+	 * When `true`, telemetry is not sent.
+	 *
+	 * This flag does not disable user targeting and reporting analytics. It's used (by us) for performance monitoring and error tracking.
+	 *
+	 * Included telemetry data when enabled: apiKey, ephemeral one-time session id,
+	 * execution flow, event timestamps, and page origin (domain name).
+	 *
+	 * Excluded by default: user identity and detailed page fields (path/referrer/search).
+	 */
+	disableTelemetry?: boolean | undefined;
+	/** Feature flag evaluations collected with widget initialization. */
+	flags?: FlagsInput | undefined;
+	/** Host capabilities collected with widget initialization. */
+	capabilities?: CapabilitiesInput | undefined;
+	_loaderUrl?: string | undefined;
+	_coreUrl?: string | undefined;
+	_apiUrl?: string | undefined;
+};
+
+// ── Flow and widget actions (used by Client methods) ───────────────────
+
+/** Open a flow with a given instance. Omit flowHandleId for first open; core returns it in settlement. */
+export type OpenCommandPayload = {
+	kind: "open";
+	flowId: string;
+	flowHandleId?: string | undefined;
+	container?: HTMLElement | null | undefined;
+	/** Optional metadata tags to persist with the eventual response submission. */
+	metadata?: ResponseMetadataInput | undefined;
+	/**
+	 * When `true`, the flow view does not show a close button.
+	 * Useful for mobile or embedded contexts where the host handles dismissal (e.g. via a drawer or back gesture).
+	 */
+	hideCloseButton?: boolean | undefined;
+};
+
+/** Prefetch a flow. Omit flowHandleId for first prefetch; core returns it in settlement. */
+export type PrefetchCommandPayload = {
+	kind: "prefetch";
+	flowId: string;
+	flowHandleId?: string | undefined;
+};
+
+/** Prerender a flow. Omit flowHandleId for first prerender; core returns it in settlement. */
+export type PrerenderCommandPayload = {
+	kind: "prerender";
+	flowId: string;
+	flowHandleId?: string | undefined;
+	/**
+	 * When `true`, the prerendered view does not show a close button.
+	 */
+	hideCloseButton?: boolean | undefined;
+};
+
+/** Identify with traits only (`client.identify(traits)`). */
+export type IdentifyTraitsOnlyCommandPayload = {
+	kind: "identify";
+	traits: Record<string, unknown>;
+	options?: IdentifyOptions | undefined;
+};
+
+/** Identify with userId and optional traits (`client.identify(userId, traits?)`). */
+export type IdentifyUserCommandPayload = {
+	kind: "identify";
+	userId: string;
+	traits?: Record<string, unknown> | undefined;
+	options?: IdentifyOptions | undefined;
+};
+
+/** Identify command payload: either traits-only or userId+traits shape. */
+export type IdentifyCommandPayload =
+	| IdentifyTraitsOnlyCommandPayload
+	| IdentifyUserCommandPayload;
+
+export type IdentifyOptions = {
+	externalIds?: AppEventExternalId[] | undefined;
+};
+
+export type TrackOptions = {
+	externalIds?: AppEventExternalId[] | undefined;
+};
+
+/**
+ * Command payload for `client.track()`.
+ *
+ * @see https://getuserfeedback.com/docs/reference/events
+ */
+export type TrackCommandPayload = AppEventBase & {
+	kind: "track";
+	origin: "customer";
+	event: string;
+	properties?: Record<string, AppEventJsonValue> | undefined;
+};
+
+/** Attach or detach a resolved flow handle from a host container. */
+export type SetContainerCommandPayload = {
+	kind: "setContainer";
+	flowHandleId: string;
+	container: HTMLElement | null;
+};
+
+/** Default container behavior for flows in an instance. */
+export type ContainerPolicy =
+	| {
+			kind: "floating";
+	  }
+	| {
+			kind: "hostContainer";
+			host: HTMLElement | null;
+			sharing: "shared" | "perFlowRun";
+	  };
+
+/** Set the instance-level default container policy. */
+export type SetDefaultContainerPolicyCommandPayload = {
+	kind: "setDefaultContainerPolicy";
+	policy: ContainerPolicy;
+};
+
+/** Update color scheme, consent, and auth. */
+export type ConfigureCommandPayload = {
+	kind: "configure";
+	opts: ConfigureOptions;
+};
+
+/** Initialize the widget with options. */
+export type InitCommandPayload = {
+	kind: "init";
+	opts: InitOptions;
+};
+
+/** Close a flow. */
+export type CloseCommandPayload = {
+	kind: "close";
+	flowHandleId?: string | undefined;
+};
+
+/** Reset widget state. */
+export type ResetCommandPayload = {
+	kind: "reset";
+};
+
+/** Union of widget action payloads such as open, prefetch, identify, configure, and track. */
+export type PublicCommandPayload =
+	| OpenCommandPayload
+	| PrefetchCommandPayload
+	| PrerenderCommandPayload
+	| IdentifyCommandPayload
+	| SetContainerCommandPayload
+	| SetDefaultContainerPolicyCommandPayload
+	| ConfigureCommandPayload
+	| InitCommandPayload
+	| CloseCommandPayload
+	| ResetCommandPayload
+	| TrackCommandPayload;
+
+/** Input for a single widget action; same shape as {@link PublicCommandPayload}. */
+export type Command = PublicCommandPayload;
+
+/** Wrapper for a widget action (version, request id, idempotency key, optional client metadata, and the action payload). */
+export type CommandEnvelope = {
+	version: "1";
+	instanceId?: string | undefined;
+	requestId: string;
+	idempotencyKey: string;
+	clientMeta?: ClientMeta | undefined;
+	command: PublicCommandPayload;
+};
+
+// ── Telemetry (use("beforeSend")) ─────────────────────────────────────
+
+/** Identity kind for telemetry events; same as {@link AppEventIdentityType}. */
+export type TelemetryIdentityType = AppEventIdentityType;
+
+/**
+ * Event passed to the `beforeSend` hook in {@link Client.use}.
+ * When `debug` is true, identities and full page context are included; when false, no identities and page is origin-only.
+ *
+ * TODO(migration): Rename this SDK-facing type to WidgetTelemetryEvent in the
+ * same change that updates SDK imports, so the generic TelemetryEvent name can
+ * retire here without colliding with shared telemetry.
+ *   [from=TelemetryEvent-widget-surface] [to=WidgetTelemetryEvent] [scope=slice] [priority=low]
+ */
+export type TelemetryEvent = {
+	type: string;
+	timestamp: number;
+	apiKey: string;
+	/** When true, identities and full page context are present; when false, no identities and page.origin only. */
+	debug: boolean;
+	identities: Array<{ type: TelemetryIdentityType; value: string }>;
+	context: {
+		page: {
+			path?: string | null | undefined;
+			referrer?: string | null | undefined;
+			search?: string | null | undefined;
+			origin?: string | null | undefined;
+		};
+		widgetVersion: string;
+		clientMeta?: ClientMeta | undefined;
+	};
+	properties?: Record<string, unknown> | undefined;
+};

package/src/host/sdk.ts

@@ -0,0 +1,43 @@
+/**
+ * SDK-facing protocol surface: types (from sdk-types) and values only.
+ * Does not re-export schema modules so SDK dist stays zod-free.
+ */
+
+export { createCommandDispatch } from "./command-dispatch.js";
+export {
+	COMMAND_SETTLEMENT_TIMEOUT_CODE,
+	CommandSettlementError,
+	CommandSettlementTimeoutError,
+	toCommandSettlementError,
+	waitForCommandSettlement,
+} from "./command-settlement.js";
+export type {
+	FlowHandleFromSettlement,
+	FlowState,
+} from "./host-event-contract.js";
+export {
+	getFlowHandleFromSettlementDetail,
+	isFlowStateChangedDetail,
+	isHandleInvalidatedDetail,
+	isInstanceFlowStateChangedDetail,
+} from "./host-event-contract.js";
+export type {
+	AppEventCapability,
+	AppEventFlag,
+	AppEventFlagProvider,
+	AppEventFlagValue,
+	AppEventPayload,
+	CapabilitiesInput,
+	ClientMeta,
+	ClientOptions,
+	Command,
+	CommandEnvelope,
+	ConfigureOptions,
+	ContainerPolicy,
+	FlagsInput,
+	InitOptions,
+	PublicCommandPayload,
+	ResponseMetadataInput,
+	// Re-export name stays TelemetryEvent until the migration on TelemetryEvent in sdk-types completes.
+	TelemetryEvent,
+} from "./sdk-types.js";

package/src/host/unique-id.ts

@@ -0,0 +1,17 @@
+/**
+ * Generates a unique string ID. Uses crypto.randomUUID when available,
+ * otherwise falls back to a timestamp + random string.
+ *
+ * @param prefix - Optional prefix for the fallback format (e.g. "req", "err").
+ *                 Only affects fallback; UUIDs have no prefix.
+ */
+export function createUniqueId(prefix?: string): string {
+	if (
+		typeof globalThis.crypto !== "undefined" &&
+		typeof globalThis.crypto.randomUUID === "function"
+	) {
+		return globalThis.crypto.randomUUID();
+	}
+	const fallback = `${Date.now()}_${Math.random().toString(36).slice(2)}`;
+	return prefix ? `${prefix}_${fallback}` : fallback;
+}

package/src/identity-type.ts

@@ -0,0 +1,96 @@
+import * as z from "zod/mini";
+
+export const IDENTITY_TYPE_VALUES = [
+	"anonymousId",
+	"userId",
+	"traits.email",
+	"traits.phone",
+	"context.device.id",
+	"context.device.advertisingId",
+	"context.device.token",
+] as const;
+
+export type StandardIdentityTypeValue = (typeof IDENTITY_TYPE_VALUES)[number];
+export type IdentityTypeValue = StandardIdentityTypeValue;
+
+const IDENTITY_TYPE_ALIAS_SUGGESTIONS: Record<
+	string,
+	StandardIdentityTypeValue
+> = {
+	advertising_id: "context.device.advertisingId",
+	anonymous_id: "anonymousId",
+	device_id: "context.device.id",
+	device_token: "context.device.token",
+	email: "traits.email",
+	phone: "traits.phone",
+	phone_number: "traits.phone",
+	user_id: "userId",
+};
+
+const COMMON_IDENTITY_TYPE_MAPPINGS = [
+	["email", "traits.email"],
+	["phone", "traits.phone"],
+	["user_id", "userId"],
+] as const;
+
+const normalizeIdentityTypeAliasKey = (value: string): string =>
+	value.trim().toLowerCase().replace(/-/g, "_");
+
+export const isIdentityTypeValue = (
+	value: string,
+): value is IdentityTypeValue =>
+	IDENTITY_TYPE_VALUES.some((candidate) => candidate === value);
+
+const parseIdentityTypeValue = (value: string): IdentityTypeValue | null =>
+	isIdentityTypeValue(value) ? value : null;
+
+export const getIdentityTypeSuggestion = (
+	value: string,
+): IdentityTypeValue | null =>
+	IDENTITY_TYPE_ALIAS_SUGGESTIONS[normalizeIdentityTypeAliasKey(value)] ?? null;
+
+export const buildIdentityTypeGuidanceMessage = (value: string): string => {
+	const normalizedValue = value.trim();
+	const displayValue =
+		normalizedValue.length > 0 ? `"${normalizedValue}"` : "that value";
+	const suggestion = getIdentityTypeSuggestion(value);
+
+	if (suggestion) {
+		return `Unsupported identity type ${displayValue}. Use "${suggestion}" instead.`;
+	}
+
+	const mappingExamples = COMMON_IDENTITY_TYPE_MAPPINGS.map(
+		([from, to]) => `${from} -> ${to}`,
+	).join(", ");
+
+	return `Unsupported identity type ${displayValue}. Use one of: ${IDENTITY_TYPE_VALUES.join(", ")}. For external IDs, send Segment-compatible context.externalIds entries instead. Common mappings: ${mappingExamples}.`;
+};
+
+const identityTypeInputSchema = z.string().check(
+	z.trim(),
+	z.minLength(1, { error: "Identity type is required." }),
+	z.check<string>((ctx) => {
+		if (isIdentityTypeValue(ctx.value)) {
+			return;
+		}
+		ctx.issues.push({
+			code: "custom",
+			input: ctx.value,
+			message: buildIdentityTypeGuidanceMessage(ctx.value),
+			continue: false,
+		});
+	}),
+);
+
+export const appEventIdentityTypeSchema = z.pipe(
+	identityTypeInputSchema,
+	z.transform((value): IdentityTypeValue => {
+		const parsed = parseIdentityTypeValue(value);
+		if (parsed === null) {
+			throw new Error(
+				`Identity type should have been validated before transform: ${value}`,
+			);
+		}
+		return parsed;
+	}),
+);