@getuserfeedback/protocol 0.6.1 → 0.7.2

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,102 @@
+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 CustomIdentityTypeValue = `custom.${string}`;
+export type IdentityTypeValue =
+	| StandardIdentityTypeValue
+	| CustomIdentityTypeValue;
+
+const CUSTOM_IDENTITY_TYPE_PATTERN = /^custom\.[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+
+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) ||
+	CUSTOM_IDENTITY_TYPE_PATTERN.test(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(", ")}, or a custom identity type like "custom.shopifyCustomerId". 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;
+	}),
+);

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