@getuserfeedback/protocol 0.7.2 → 0.9.0

package/src/host/index.ts

@@ -6,6 +6,7 @@ export * from "./command-dispatch.js";
 export * from "./command-envelope.js";
 export * from "./command-settlement.js";
 export * from "./constants.js";
+export * from "./external-id-argument-guards.js";
 export * from "./host-event-contract.js";
 export * from "./lazy-handle-client.js";
 export { createCommandRequestId } from "./request-id.js";

package/src/host/sdk-types.ts

@@ -11,8 +11,8 @@ import type { Scope } from "../scopes.js";
 /**
  * Identifier types supported by event tracking and identity resolution.
  *
- * Use `custom.<name>` for business-specific identifiers such as
- * `custom.shopifyCustomerId` or `custom.salesforceContactId`.
+ * 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
  */
@@ -23,15 +23,29 @@ export type AppEventIdentityType =
 	| "traits.phone"
 	| "context.device.id"
 	| "context.device.advertisingId"
-	| "context.device.token"
-	| `custom.${string}`;
+	| "context.device.token";
 
-/** A single identifier, such as a user ID, anonymous ID, email, or custom external ID. */
+/** 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.
+ * External IDs help match profiles, but they are not traits by themselves.
+ *
+ * @see https://getuserfeedback.com/docs/guides/identity-resolution
+ */
+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?: {
@@ -41,6 +55,7 @@ export type AppEventContext = {
 	};
 	locale?: string;
 	userAgent?: string;
+	externalIds?: AppEventExternalId[] | undefined;
 	flags?: AppEventFlag[] | undefined;
 	capabilities?: AppEventCapability[] | undefined;
 };
@@ -367,17 +382,19 @@ export type PrerenderCommandPayload = {
 	hideCloseButton?: boolean | undefined;
 };
 
-/** Identify with traits only (`client.identify(traits)`). */
+/** Identify with traits only (`client.identify(traits)` or `client.identify(traits, options)`). */
 export type IdentifyTraitsOnlyCommandPayload = {
 	kind: "identify";
 	traits: Record<string, unknown>;
+	options?: IdentifyOptions | undefined;
 };
 
-/** Identify with userId and optional traits (`client.identify(userId, traits?)`). */
+/** Identify with userId, optional traits, and optional external IDs (`client.identify(userId, traits?, options?)`). */
 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. */
@@ -385,6 +402,33 @@ export type IdentifyCommandPayload =
 	| IdentifyTraitsOnlyCommandPayload
 	| IdentifyUserCommandPayload;
 
+/**
+ * Optional identity context accepted by `client.identify()`.
+ *
+ * Use `externalIds` for Segment-compatible identifiers from another system,
+ * such as Shopify customer IDs or Salesforce contact IDs. Without a user ID,
+ * pass options as `client.identify(traits, options)`, or use
+ * `client.identify(traits, undefined, options)` when your call site needs the
+ * explicit three-argument form.
+ *
+ * @see https://getuserfeedback.com/docs/guides/identity-resolution
+ */
+export type IdentifyOptions = {
+	externalIds?: AppEventExternalId[] | undefined;
+};
+
+/**
+ * Optional context accepted by `client.track()`.
+ *
+ * Use `externalIds` when the event carries a Segment-compatible identifier
+ * from another system.
+ *
+ * @see https://getuserfeedback.com/docs/reference/events
+ */
+export type TrackOptions = {
+	externalIds?: AppEventExternalId[] | undefined;
+};
+
 /**
  * Command payload for `client.track()`.
  *

package/src/identity-type.ts

@@ -11,12 +11,7 @@ export const IDENTITY_TYPE_VALUES = [
 ] 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_.-]*$/;
+export type IdentityTypeValue = StandardIdentityTypeValue;
 
 const IDENTITY_TYPE_ALIAS_SUGGESTIONS: Record<
 	string,
@@ -44,8 +39,7 @@ const normalizeIdentityTypeAliasKey = (value: string): string =>
 export const isIdentityTypeValue = (
 	value: string,
 ): value is IdentityTypeValue =>
-	IDENTITY_TYPE_VALUES.some((candidate) => candidate === value) ||
-	CUSTOM_IDENTITY_TYPE_PATTERN.test(value);
+	IDENTITY_TYPE_VALUES.some((candidate) => candidate === value);
 
 const parseIdentityTypeValue = (value: string): IdentityTypeValue | null =>
 	isIdentityTypeValue(value) ? value : null;
@@ -69,7 +63,7 @@ export const buildIdentityTypeGuidanceMessage = (value: string): string => {
 		([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}.`;
+	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(

package/src/index.ts

@@ -1,5 +1,6 @@
 export {
 	type AppEventCapability,
+	type AppEventExternalId,
 	type AppEventFlag,
 	type AppEventJsonValue,
 	type AppEventPayload,
@@ -8,6 +9,7 @@ export {
 	appEventCapabilitySchema,
 	appEventContextSchema,
 	appEventCustomerTrackSchema,
+	appEventExternalIdSchema,
 	appEventFlagProviderSchema,
 	appEventFlagSchema,
 	appEventFlowDismissedSchema,
@@ -37,6 +39,8 @@ export {
 	type ClaimPendingFlowAssignmentsResponse,
 	claimPendingFlowAssignmentsRequestSchema,
 	claimPendingFlowAssignmentsResponseSchema,
+	type FlowAssignmentExternalIdIdentityTypeValue,
+	type FlowAssignmentIdentityTypeValue,
 	type FlowAssignmentRecipientRequest,
 	type FlowAssignmentRecord,
 	type FlowAssignmentStatus,
@@ -59,7 +63,6 @@ export {
 } from "./flow-assignments.js";
 export {
 	buildIdentityTypeGuidanceMessage,
-	type CustomIdentityTypeValue,
 	getIdentityTypeSuggestion,
 	IDENTITY_TYPE_VALUES,
 	type IdentityTypeValue,

package/src/protocol-root.test.ts

@@ -161,6 +161,18 @@ describe("@getuserfeedback/protocol root contract", () => {
 		});
 	});
 
+	it("parses theme resolution payloads with optional runtime artifacts", () => {
+		expect(
+			themeVersionResolutionSchema.parse({
+				themeRuntimeArtifactId: "thra_xyz",
+				themeVersionId: "tv_xyz",
+			}),
+		).toEqual({
+			themeRuntimeArtifactId: "thra_xyz",
+			themeVersionId: "tv_xyz",
+		});
+	});
+
 	it("exposes public widget command kind validation aligned with public payloads", () => {
 		expect(publicWidgetCommandKindSchema.safeParse("open").success).toBe(true);
 		expect(publicWidgetCommandKindSchema.safeParse("telemetry").success).toBe(
@@ -196,6 +208,16 @@ describe("@getuserfeedback/protocol root contract", () => {
 			traits: {
 				email: "user@example.com",
 			},
+			options: {
+				externalIds: [
+					{
+						id: "gid://shopify/Customer/123",
+						type: "shopify_customer_id",
+						collection: "users",
+						encoding: "none",
+					},
+				],
+			},
 		});
 		const withTraitsOnly = parsePublicCommand({
 			kind: "identify",
@@ -210,6 +232,14 @@ describe("@getuserfeedback/protocol root contract", () => {
 			expect(withUserId.traits).toEqual({
 				email: "user@example.com",
 			});
+			expect(withUserId.options?.externalIds).toEqual([
+				{
+					id: "gid://shopify/Customer/123",
+					type: "shopify_customer_id",
+					collection: "users",
+					encoding: "none",
+				},
+			]);
 		}
 
 		expect(withTraitsOnly.kind).toBe("identify");
@@ -468,9 +498,97 @@ describe("@getuserfeedback/protocol root contract", () => {
 		);
 	});
 
-	it("accepts first-class custom app event identity types", () => {
-		const result = appEventIdentityTypeSchema.parse("custom.shopifyCustomerId");
+	it("rejects legacy custom app event identity types", () => {
+		expect(() =>
+			appEventIdentityTypeSchema.parse("custom.shopifyCustomerId"),
+		).toThrow(/context\.externalIds/);
+	});
 
-		expect(result).toBe("custom.shopifyCustomerId");
+	it("accepts Segment-compatible external IDs in app event context", () => {
+		const result = appEventTrackSchema.parse({
+			event: "Checkout Started",
+			origin: "customer",
+			context: {
+				externalIds: [
+					{
+						id: "gid://shopify/123",
+						type: "shopify_customer_id",
+						collection: "users",
+						encoding: "none",
+					},
+				],
+			},
+		});
+
+		expect(result.context?.externalIds).toEqual([
+			{
+				id: "gid://shopify/123",
+				type: "shopify_customer_id",
+				collection: "users",
+				encoding: "none",
+			},
+		]);
+	});
+
+	it("normalizes external ID values before app event context output", () => {
+		const result = appEventTrackSchema.parse({
+			event: "Checkout Started",
+			origin: "customer",
+			context: {
+				externalIds: [
+					{
+						id: " gid://shopify/123 ",
+						type: "shopify_customer_id",
+						collection: "users",
+						encoding: "none",
+					},
+				],
+			},
+		});
+
+		expect(result.context?.externalIds).toEqual([
+			{
+				id: "gid://shopify/123",
+				type: "shopify_customer_id",
+				collection: "users",
+				encoding: "none",
+			},
+		]);
+	});
+
+	it("caps app event context external IDs to identity cardinality limits", () => {
+		expect(() =>
+			appEventTrackSchema.parse({
+				event: "Checkout Started",
+				origin: "customer",
+				context: {
+					externalIds: Array.from({ length: 21 }, (_, index) => ({
+						id: `customer_${index}`,
+						type: "shopify_customer_id",
+						collection: "users",
+						encoding: "none",
+					})),
+				},
+			}),
+		).toThrow();
+	});
+
+	it("rejects uppercase external ID types", () => {
+		expect(() =>
+			appEventTrackSchema.parse({
+				event: "Checkout Started",
+				origin: "customer",
+				context: {
+					externalIds: [
+						{
+							id: "gid://shopify/123",
+							type: "Shopify_Customer_Id",
+							collection: "users",
+							encoding: "none",
+						},
+					],
+				},
+			}),
+		).toThrow(/lowercase/);
 	});
 });

package/src/version-resolution.ts

@@ -7,6 +7,7 @@ export const flowVersionResolutionSchema = z.object({
 });
 
 export const themeVersionResolutionSchema = z.object({
+	themeRuntimeArtifactId: z.optional(versionIdSchema),
 	themeVersionId: versionIdSchema,
 });
 

package/src/widget-commands.ts

@@ -1,5 +1,8 @@
 import * as z from "zod/mini";
-import { appEventCustomerTrackSchema } from "./app-event.js";
+import {
+	appEventCustomerTrackSchema,
+	appEventExternalIdSchema,
+} from "./app-event.js";
 import {
 	type ConfigureOptions,
 	configureOptionsSchema,
@@ -50,15 +53,22 @@ const htmlElementOrNullSchema = z.custom<HTMLElement | null>(
 );
 
 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),
 	}),
 ]);
 

package/src/widget-config.ts

@@ -1,5 +1,9 @@
 import * as z from "zod/mini";
-import { appEventCapabilitySchema, appEventFlagSchema } from "./app-event.js";
+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";
@@ -59,6 +63,9 @@ 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>;