@getuserfeedback/protocol 0.6.1 → 0.8.0

package/dist/app-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-event.d.ts","sourceRoot":"","sources":["../src/app-event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAG9B,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEhE,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAC;AAEH,KAAK,iBAAiB,GACnB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,iBAAiB,EAAE,GACnB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAaxC,eAAO,MAAM,0BAA0B;;;;iBAIrC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;iBAY7B,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;iBAInC,CAAC;AAQH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMhC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM7B,CAAC;AAMH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGrC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGtC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG9B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAGhC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACrE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"app-event.d.ts","sourceRoot":"","sources":["../src/app-event.ts"],"names":[],"mappings":"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"}

package/dist/app-event.js

@@ -13,6 +13,18 @@ const appEventFlagValueSchema = z.lazy(() => z.union([
     z.array(appEventFlagValueSchema),
     z.record(z.string(), appEventFlagValueSchema),
 ]));
+const appEventJsonNumberSchema = z.number().check(z.refine(Number.isFinite, {
+    message: "Expected a finite JSON number.",
+}));
+const appEventJsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    appEventJsonNumberSchema,
+    z.boolean(),
+    z.null(),
+    z.array(appEventJsonValueSchema),
+    z.record(z.string(), appEventJsonValueSchema),
+]));
+const appEventJsonObjectSchema = z.record(z.string(), appEventJsonValueSchema);
 export const appEventFlagProviderSchema = z.object({
     name: z.string().check(z.trim(), z.minLength(1)),
     project: z.optional(z.string().check(z.trim(), z.minLength(1))),
@@ -39,10 +51,20 @@ const appEventPageSchema = z.object({
     referrer: z.optional(z.string()),
     search: z.optional(z.string()),
 });
+const externalIdTypeSchema = z.string().check(z.trim(), z.minLength(1), z.regex(/^[a-z0-9][a-z0-9_.-]*$/, {
+    message: "External ID type must start with a lowercase letter or number and may contain lowercase letters, numbers, underscores, dots, or hyphens.",
+}));
+export const appEventExternalIdSchema = z.object({
+    id: z.pipe(z.string().check(z.trim(), z.minLength(1)), z.transform((value) => value.trim())),
+    type: externalIdTypeSchema,
+    collection: z.literal("users"),
+    encoding: z.literal("none"),
+});
 export const appEventContextSchema = z.object({
     page: z.optional(appEventPageSchema),
     locale: z.optional(z.string()),
     userAgent: z.optional(z.string()),
+    externalIds: z.optional(z.array(appEventExternalIdSchema).check(z.maxLength(20))),
     flags: z.optional(z.array(appEventFlagSchema)),
     capabilities: z.optional(z.array(appEventCapabilitySchema)),
 });
@@ -56,19 +78,70 @@ export const appEventBaseSchema = z.object({
 const appEventSurveyReferenceSchema = z.object({
     surveyId: z.string(),
 });
-export const appEventSurveyViewedSchema = z.extend(appEventBaseSchema, {
+export const reservedSystemAppEventNames = [
+    "Response Submitted",
+    "Flow Viewed",
+    "Flow Dismissed",
+    "Identified",
+];
+const reservedSystemAppEventNameLowercaseSet = new Set(reservedSystemAppEventNames.map((event) => event.toLowerCase()));
+const appEventSystemTrackNameSchema = z.enum(["Flow Viewed", "Flow Dismissed"]);
+const appEventCustomerNameSchema = z.string().check(z.trim(), z.minLength(1), z.maxLength(255), z.check((ctx) => {
+    if (!reservedSystemAppEventNameLowercaseSet.has(ctx.value.toLowerCase())) {
+        return;
+    }
+    ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        message: "Customer app event names cannot use reserved system event names.",
+        continue: false,
+    });
+}));
+export const appEventSystemBaseSchema = z.extend(appEventBaseSchema, {
+    origin: z.literal("system"),
+});
+const normalizeSystemAppEventOrigin = (input) => {
+    const { origin: _origin, ...rest } = input;
+    return {
+        ...rest,
+        origin: "system",
+    };
+};
+export const appEventSurveyViewedSchema = z.pipe(z.extend(appEventBaseSchema, {
+    origin: z.optional(z.literal("system")),
     event: z.literal("Flow Viewed"),
     references: appEventSurveyReferenceSchema,
-});
-export const appEventFlowDismissedSchema = z.extend(appEventBaseSchema, {
+}), z.transform(normalizeSystemAppEventOrigin));
+export const appEventFlowDismissedSchema = z.pipe(z.extend(appEventBaseSchema, {
+    origin: z.optional(z.literal("system")),
     event: z.literal("Flow Dismissed"),
     references: appEventSurveyReferenceSchema,
+}), z.transform(normalizeSystemAppEventOrigin));
+export const appEventSystemTrackSchema = z.extend(appEventSystemBaseSchema, {
+    event: appEventSystemTrackNameSchema,
+    references: appEventSurveyReferenceSchema,
 });
-export const appEventTrackSchema = z.extend(appEventBaseSchema, {
-    event: z.enum(["Flow Viewed", "Flow Dismissed"]),
+const appEventLegacySystemTrackSchema = z.pipe(z.extend(appEventBaseSchema, {
+    origin: z.optional(z.literal("system")),
+    event: appEventSystemTrackNameSchema,
     references: appEventSurveyReferenceSchema,
+}), z.transform(normalizeSystemAppEventOrigin));
+export const appEventCustomerTrackSchema = z.extend(appEventBaseSchema, {
+    origin: z.literal("customer"),
+    event: appEventCustomerNameSchema,
+    // TODO(migration): Normalize Date values in event properties to ISO strings.
+    //   [from=manual-date-property-serialization] [to=protocol-date-property-normalization] [scope=slice] [priority=medium] [impact=medium] [risk=low]
+    properties: z.optional(appEventJsonObjectSchema),
 });
-export const appEventPayloadSchema = z.discriminatedUnion("event", [
-    appEventSurveyViewedSchema,
-    appEventFlowDismissedSchema,
+export const appEventTrackSchema = z.union([
+    appEventLegacySystemTrackSchema,
+    appEventCustomerTrackSchema,
+]);
+const appEventDiscriminatedPayloadSchema = z.discriminatedUnion("origin", [
+    appEventSystemTrackSchema,
+    appEventCustomerTrackSchema,
+]);
+export const appEventPayloadSchema = z.union([
+    appEventLegacySystemTrackSchema,
+    appEventDiscriminatedPayloadSchema,
 ]);

package/dist/flow-assignments.d.ts

@@ -1,4 +1,7 @@
 import * as z from "zod/mini";
+import type { IdentityTypeValue } from "./identity-type.js";
+export type FlowAssignmentExternalIdIdentityTypeValue = `externalId.${string}`;
+export type FlowAssignmentIdentityTypeValue = IdentityTypeValue | FlowAssignmentExternalIdIdentityTypeValue;
 export declare const flowAssignmentStatusSchema: z.ZodMiniEnum<{
     pending: "pending";
     held: "held";
@@ -91,7 +94,7 @@ export declare const flowAssignmentTargetingContextSchema: z.ZodMiniObject<{
 }, z.core.$strip>;
 export declare const flowAssignmentRecipientRequestSchema: z.ZodMiniObject<{
     identities: z.ZodMiniDefault<z.ZodMiniArray<z.ZodMiniObject<{
-        type: z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<"anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token", string>>;
+        type: z.ZodMiniUnion<readonly [z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<"anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token", string>>, z.ZodMiniType<`externalId.${string}`, `externalId.${string}`, z.core.$ZodTypeInternals<`externalId.${string}`, `externalId.${string}`>>]>;
         value: z.ZodMiniString<string>;
     }, z.core.$strip>>>;
     context: z.ZodMiniOptional<z.ZodMiniObject<{
@@ -236,7 +239,7 @@ export declare const listPendingFlowAssignmentsResponseSchema: z.ZodMiniObject<{
 }, z.core.$strip>;
 export declare const claimPendingFlowAssignmentsRequestSchema: z.ZodMiniObject<{
     identities: z.ZodMiniDefault<z.ZodMiniArray<z.ZodMiniObject<{
-        type: z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<"anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token", string>>;
+        type: z.ZodMiniUnion<readonly [z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<"anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token", string>>, z.ZodMiniType<`externalId.${string}`, `externalId.${string}`, z.core.$ZodTypeInternals<`externalId.${string}`, `externalId.${string}`>>]>;
         value: z.ZodMiniString<string>;
     }, z.core.$strip>>>;
     context: z.ZodMiniOptional<z.ZodMiniObject<{
@@ -355,7 +358,7 @@ export declare const claimPendingFlowAssignmentsResponseSchema: z.ZodMiniObject<
 }, z.core.$strip>;
 export declare const updateFlowAssignmentLifecycleRequestSchema: z.ZodMiniObject<{
     identities: z.ZodMiniDefault<z.ZodMiniArray<z.ZodMiniObject<{
-        type: z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<"anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token", string>>;
+        type: z.ZodMiniUnion<readonly [z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<"anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token", string>>, z.ZodMiniType<`externalId.${string}`, `externalId.${string}`, z.core.$ZodTypeInternals<`externalId.${string}`, `externalId.${string}`>>]>;
         value: z.ZodMiniString<string>;
     }, z.core.$strip>>>;
     context: z.ZodMiniOptional<z.ZodMiniObject<{
@@ -444,7 +447,7 @@ export declare const updateFlowAssignmentLifecycleRequestSchema: z.ZodMiniObject
 }, z.core.$strip>;
 export declare const releaseFlowAssignmentClaimRequestSchema: z.ZodMiniObject<{
     identities: z.ZodMiniDefault<z.ZodMiniArray<z.ZodMiniObject<{
-        type: z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<"anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token", string>>;
+        type: z.ZodMiniUnion<readonly [z.ZodMiniPipe<z.ZodMiniString<string>, z.ZodMiniTransform<"anonymousId" | "userId" | "traits.email" | "traits.phone" | "context.device.id" | "context.device.advertisingId" | "context.device.token", string>>, z.ZodMiniType<`externalId.${string}`, `externalId.${string}`, z.core.$ZodTypeInternals<`externalId.${string}`, `externalId.${string}`>>]>;
         value: z.ZodMiniString<string>;
     }, z.core.$strip>>>;
     holdGroupToken: z.ZodMiniString<string>;

package/dist/flow-assignments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow-assignments.d.ts","sourceRoot":"","sources":["../src/flow-assignments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAQ9B,eAAO,MAAM,0BAA0B;;;;;;;;;;EAUrC,CAAC;AAEH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG/C,CAAC;AAEH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAI/C,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmBrC,CAAC;AAEH,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGnD,CAAC;AAEH,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMnD,CAAC;AAEH,eAAO,MAAM,yCAAyC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGpD,CAAC;AAEH,eAAO,MAAM,0CAA0C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAOrD,CAAC;AAEH,eAAO,MAAM,uCAAuC;;;;;;;;iBAKlD,CAAC;AAEH,eAAO,MAAM,wCAAwC;;iBAEnD,CAAC;AAEH,eAAO,MAAM,2CAA2C;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAC7B,CAAC;AAC5B,eAAO,MAAM,mDAAmD;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAE/D,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC/E,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CACpD,OAAO,oCAAoC,CAC3C,CAAC;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CACpD,OAAO,oCAAoC,CAC3C,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC/E,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CACxD,OAAO,wCAAwC,CAC/C,CAAC;AACF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,MAAM,CACzD,OAAO,yCAAyC,CAChD,CAAC;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CACxD,OAAO,wCAAwC,CAC/C,CAAC;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CACvD,OAAO,uCAAuC,CAC9C,CAAC;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CACxD,OAAO,wCAAwC,CAC/C,CAAC;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAC1D,OAAO,0CAA0C,CACjD,CAAC;AACF,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAC3D,OAAO,2CAA2C,CAClD,CAAC"}
+{"version":3,"file":"flow-assignments.d.ts","sourceRoot":"","sources":["../src/flow-assignments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAO9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,MAAM,MAAM,yCAAyC,GAAG,cAAc,MAAM,EAAE,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GACxC,iBAAiB,GACjB,yCAAyC,CAAC;AAsB7C,eAAO,MAAM,0BAA0B;;;;;;;;;;EAUrC,CAAC;AAEH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG/C,CAAC;AAEH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAI/C,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmBrC,CAAC;AAEH,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGnD,CAAC;AAEH,eAAO,MAAM,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMnD,CAAC;AAEH,eAAO,MAAM,yCAAyC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGpD,CAAC;AAEH,eAAO,MAAM,0CAA0C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAOrD,CAAC;AAEH,eAAO,MAAM,uCAAuC;;;;;;;;iBAKlD,CAAC;AAEH,eAAO,MAAM,wCAAwC;;iBAEnD,CAAC;AAEH,eAAO,MAAM,2CAA2C;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAC7B,CAAC;AAC5B,eAAO,MAAM,mDAAmD;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAE/D,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC/E,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CACpD,OAAO,oCAAoC,CAC3C,CAAC;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CACpD,OAAO,oCAAoC,CAC3C,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC/E,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CACxD,OAAO,wCAAwC,CAC/C,CAAC;AACF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,MAAM,CACzD,OAAO,yCAAyC,CAChD,CAAC;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CACxD,OAAO,wCAAwC,CAC/C,CAAC;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CACvD,OAAO,uCAAuC,CAC9C,CAAC;AACF,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CACxD,OAAO,wCAAwC,CAC/C,CAAC;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAC1D,OAAO,0CAA0C,CACjD,CAAC;AACF,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAC3D,OAAO,2CAA2C,CAClD,CAAC"}

package/dist/flow-assignments.js

@@ -1,5 +1,15 @@
 import * as z from "zod/mini";
-import { appEventCapabilitySchema, appEventFlagSchema, appEventIdentitySchema, } from "./app-event.js";
+import { appEventCapabilitySchema, appEventFlagSchema, appEventIdentityTypeSchema, } from "./app-event.js";
+const flowAssignmentExternalIdIdentityTypeSchema = z.string().check(z.trim(), z.minLength(1), z.regex(/^externalId\.[a-z0-9][a-z0-9_.-]*$/, {
+    message: "External ID identity type must use externalId.<type> with a lowercase Segment external ID type.",
+}));
+const flowAssignmentIdentitySchema = z.object({
+    type: z.union([
+        appEventIdentityTypeSchema,
+        flowAssignmentExternalIdIdentityTypeSchema,
+    ]),
+    value: z.string().check(z.trim(), z.minLength(1)),
+});
 export const flowAssignmentStatusSchema = z.enum([
     "pending",
     "held",
@@ -16,7 +26,7 @@ export const flowAssignmentTargetingContextSchema = z.object({
     capabilities: z.optional(z.array(appEventCapabilitySchema)),
 });
 export const flowAssignmentRecipientRequestSchema = z.object({
-    identities: z._default(z.array(appEventIdentitySchema), []),
+    identities: z._default(z.array(flowAssignmentIdentitySchema), []),
     context: z.optional(flowAssignmentTargetingContextSchema),
     at: z.optional(z.number()),
 });
@@ -43,7 +53,7 @@ export const listPendingFlowAssignmentsResponseSchema = z.object({
     flowAssignments: z.array(flowAssignmentRecordSchema),
 });
 export const claimPendingFlowAssignmentsRequestSchema = z.object({
-    identities: z._default(z.array(appEventIdentitySchema), []),
+    identities: z._default(z.array(flowAssignmentIdentitySchema), []),
     context: z.optional(flowAssignmentTargetingContextSchema),
     holdOwnerKey: z.string().check(z.trim(), z.minLength(1)),
     at: z.optional(z.number()),
@@ -54,7 +64,7 @@ export const claimPendingFlowAssignmentsResponseSchema = z.object({
     flowAssignments: z.array(flowAssignmentRecordSchema),
 });
 export const updateFlowAssignmentLifecycleRequestSchema = z.object({
-    identities: z._default(z.array(appEventIdentitySchema), []),
+    identities: z._default(z.array(flowAssignmentIdentitySchema), []),
     context: z.optional(flowAssignmentTargetingContextSchema),
     flowAssignmentId: z.string().check(z.trim(), z.minLength(1)),
     flowVersionId: z.optional(z.string().check(z.trim(), z.minLength(1))),
@@ -62,7 +72,7 @@ export const updateFlowAssignmentLifecycleRequestSchema = z.object({
     at: z.optional(z.number()),
 });
 export const releaseFlowAssignmentClaimRequestSchema = z.object({
-    identities: z._default(z.array(appEventIdentitySchema), []),
+    identities: z._default(z.array(flowAssignmentIdentitySchema), []),
     holdGroupToken: z.string().check(z.trim(), z.minLength(1)),
     holdOwnerKey: z.optional(z.string().check(z.trim(), z.minLength(1))),
     at: z.optional(z.number()),

package/dist/host/constants.d.ts

@@ -27,9 +27,9 @@ export declare const HOST_EVENT_KEYS: {
  * Stable capability tokens announced by the browser SDK during init.
  * These are versioned and namespaced to support forward-compatible negotiation.
  */
-export declare const SDK_PROTOCOL_CAPABILITIES: readonly ["gx.protocol.public.v1", "gx.command.configure.v1", "gx.command.open.v1", "gx.command.prefetch.v1", "gx.command.prerender.v1", "gx.command.identify.v1", "gx.command.setContainer.v1", "gx.command.close.v1", "gx.command.reset.v1", "gx.command.setDefaultContainerPolicy.v1"];
+export declare const SDK_PROTOCOL_CAPABILITIES: readonly ["gx.protocol.public.v1", "gx.command.configure.v1", "gx.command.open.v1", "gx.command.prefetch.v1", "gx.command.prerender.v1", "gx.command.identify.v1", "gx.command.setContainer.v1", "gx.command.close.v1", "gx.command.reset.v1", "gx.command.setDefaultContainerPolicy.v1", "gx.command.track.v1"];
 export type SdkProtocolCapability = (typeof SDK_PROTOCOL_CAPABILITIES)[number];
 export declare const LOADER_RUNTIME_GLOBAL_KEY: "__getuserfeedback_runtime";
-export declare const LOADER_RUNTIME_PROTOCOL_VERSION: "v1";
+export declare const LOADER_RUNTIME_PROTOCOL_VERSION: "v2";
 export declare const toHostEventName: (key: string) => string;
 //# sourceMappingURL=constants.d.ts.map

package/dist/host/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/host/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAC7B,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,eAAe,EAAG,kBAA2B,CAAC;AAE3D,eAAO,MAAM,mBAAmB,EAAG,kBAA2B,CAAC;AAI/D,eAAO,MAAM,iBAAiB,EAAG,kBAA2B,CAAC;AAE7D,eAAO,MAAM,eAAe;;;;;;;;;;;;;CAalB,CAAC;AAgDX;;;GAGG;AACH,eAAO,MAAM,yBAAyB,2RAG5B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/E,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAC9E,eAAO,MAAM,+BAA+B,EAAG,IAAa,CAAC;AAG7D,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACjB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/host/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAC7B,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,eAAe,EAAG,kBAA2B,CAAC;AAE3D,eAAO,MAAM,mBAAmB,EAAG,kBAA2B,CAAC;AAI/D,eAAO,MAAM,iBAAiB,EAAG,kBAA2B,CAAC;AAE7D,eAAO,MAAM,eAAe;;;;;;;;;;;;;CAalB,CAAC;AAkDX;;;GAGG;AACH,eAAO,MAAM,yBAAyB,kTAG5B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/E,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAC9E,eAAO,MAAM,+BAA+B,EAAG,IAAa,CAAC;AAG7D,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACjB,CAAC"}

package/dist/host/constants.js

@@ -36,6 +36,7 @@ const SDK_COMMAND_CAPABILITY_BY_KIND = {
     close: "gx.command.close.v1",
     reset: "gx.command.reset.v1",
     setDefaultContainerPolicy: "gx.command.setDefaultContainerPolicy.v1",
+    track: "gx.command.track.v1",
 };
 const SDK_COMMAND_CAPABILITIES = [
     SDK_COMMAND_CAPABILITY_BY_KIND.configure,
@@ -47,6 +48,7 @@ const SDK_COMMAND_CAPABILITIES = [
     SDK_COMMAND_CAPABILITY_BY_KIND.close,
     SDK_COMMAND_CAPABILITY_BY_KIND.reset,
     SDK_COMMAND_CAPABILITY_BY_KIND.setDefaultContainerPolicy,
+    SDK_COMMAND_CAPABILITY_BY_KIND.track,
 ];
 /**
  * Stable capability tokens announced by the browser SDK during init.
@@ -57,6 +59,6 @@ export const SDK_PROTOCOL_CAPABILITIES = [
     ...SDK_COMMAND_CAPABILITIES,
 ];
 export const LOADER_RUNTIME_GLOBAL_KEY = "__getuserfeedback_runtime";
-export const LOADER_RUNTIME_PROTOCOL_VERSION = "v1";
+export const LOADER_RUNTIME_PROTOCOL_VERSION = "v2";
 // Helper to construct full event name with prefix
 export const toHostEventName = (key) => `${HOST_EVENT_PREFIX}${key}`;

package/dist/host/external-id-argument-guards.d.ts

@@ -0,0 +1,10 @@
+type ExternalIdArgumentCommandName = "identify" | "track";
+type ExternalIdArgumentValueName = "traits" | "properties";
+export declare const assertNoAmbiguousExternalIdsArgument: ({ argument, options, commandName, valueArgumentName, }: {
+    argument: unknown;
+    options: unknown;
+    commandName: ExternalIdArgumentCommandName;
+    valueArgumentName: ExternalIdArgumentValueName;
+}) => void;
+export {};
+//# sourceMappingURL=external-id-argument-guards.d.ts.map

package/dist/host/external-id-argument-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-id-argument-guards.d.ts","sourceRoot":"","sources":["../../src/host/external-id-argument-guards.ts"],"names":[],"mappings":"AAAA,KAAK,6BAA6B,GAAG,UAAU,GAAG,OAAO,CAAC;AAC1D,KAAK,2BAA2B,GAAG,QAAQ,GAAG,YAAY,CAAC;AAqC3D,eAAO,MAAM,oCAAoC,GAAI,wDAKlD;IACF,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,6BAA6B,CAAC;IAC3C,iBAAiB,EAAE,2BAA2B,CAAC;CAC/C,KAAG,IAQH,CAAC"}

package/dist/host/external-id-argument-guards.js

@@ -0,0 +1,27 @@
+const isAmbiguousExternalIdsArgument = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const entries = Object.entries(value);
+    const externalIds = entries[0]?.[1];
+    return (entries.length === 1 &&
+        entries[0]?.[0] === "externalIds" &&
+        Array.isArray(externalIds) &&
+        externalIds.length > 0 &&
+        externalIds.every(isSegmentExternalIdLike));
+};
+const isSegmentExternalIdLike = (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    return (typeof Reflect.get(value, "id") === "string" &&
+        typeof Reflect.get(value, "type") === "string" &&
+        Reflect.get(value, "collection") === "users" &&
+        Reflect.get(value, "encoding") === "none");
+};
+export const assertNoAmbiguousExternalIdsArgument = ({ argument, options, commandName, valueArgumentName, }) => {
+    if (options !== undefined || !isAmbiguousExternalIdsArgument(argument)) {
+        return;
+    }
+    throw new Error(`${commandName} received externalIds in the ${valueArgumentName} argument. Pass undefined for ${valueArgumentName} and provide externalIds as options instead.`);
+};

package/dist/host/index.d.ts

@@ -5,6 +5,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/dist/host/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/host/index.js

@@ -5,6 +5,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/dist/host/sdk-types.d.ts

@@ -4,14 +4,32 @@
  * {@link FlowState} lives in `./host-event-contract` (re-exported from the `@getuserfeedback/protocol/host` barrel).
  */
 import type { Scope } from "../scopes.js";
-/** Supported identity kinds for analytics and tracking. */
+/**
+ * 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 identity (e.g. userId or anonymousId) and its value. */
+/** A single standard identifier, such as a user ID, anonymous ID, email, or device ID. */
 export type AppEventIdentity = {
     type: AppEventIdentityType;
     value: string;
 };
-/** Page and device context you can attach to tracked events. */
+/**
+ * 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;
@@ -20,17 +38,27 @@ export type AppEventContext = {
     };
     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;
@@ -42,14 +70,17 @@ export type AppEventFlag = {
     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 all flow lifecycle events (traits, identities, context, timing). */
+/** Optional fields shared by event payloads. */
 export type AppEventBase = {
     traits?: Record<string, unknown> | undefined;
     identities?: AppEventIdentity[] | undefined;
@@ -57,34 +88,46 @@ export type AppEventBase = {
     messageId?: string | undefined;
     timestamp?: number | undefined;
 };
-/** Reference to a specific survey/flow. */
+/** Reference to a specific survey or flow. */
 export type AppEventSurveyReference = {
     surveyId: string;
 };
-/** Event payload when a flow is shown (Flow Viewed event). */
+/** Event payload emitted when a flow is shown. */
 export type FlowViewedPayload = AppEventBase & {
+    origin?: "system" | undefined;
     event: "Flow Viewed";
     references: AppEventSurveyReference;
 };
-/** Event payload when a user dismisses a flow. */
+/** Event payload emitted when a user dismisses a flow. */
 export type FlowDismissedPayload = AppEventBase & {
+    origin?: "system" | undefined;
     event: "Flow Dismissed";
     references: AppEventSurveyReference;
 };
 /**
- * Payload for {@link Client.track}. Use this to record when a flow is shown or dismissed.
- * Discriminate on the `event` field (`"Flow Viewed"` or `"Flow Dismissed"`).
+ * 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;
-/** How the widget was loaded (e.g. via SDK, GTM, or a tag manager). */
+export type AppEventPayload = FlowViewedPayload | FlowDismissedPayload | CustomerTrackPayload;
+/** 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 (e.g. ESM, script tag). */
+/** 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 and integration (e.g. loader, framework). Used for analytics and support. */
+/** Metadata about the client integration, used for diagnostics and support. */
 export type ClientMeta = {
     loader: ClientMetaLoader;
     clientName?: string | undefined;
@@ -147,19 +190,23 @@ export type ConsentStatus = "pending" | "granted" | "denied" | "revoked";
 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 (e.g. JWT for authenticated flows). */
+/** Auth configuration, such as a JWT for authenticated flows. */
 export type AuthConfig = {
     jwt?: {
         token: string;
     } | null | undefined;
 };
-/** Options for {@link Client.configure}: color scheme, consent, and auth. */
+/**
+ * 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 customer targeting context. */
+/** @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;
@@ -177,7 +224,8 @@ export type ClientOptions = {
     apiKey: string;
     /** Color scheme config: host-driven (loader observes attributes) or explicit. */
     colorScheme?: ColorSchemeConfig | undefined;
-    /** Consent settings compatible with common privacy frameworks (GDPR, CCPA, LGPD) and CMP flows.
+    /**
+     * Initial consent state.
      *
      * Default: `granted` (all scopes).
      *
@@ -192,6 +240,8 @@ export type ClientOptions = {
      * 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`.
@@ -211,9 +261,9 @@ export type ClientOptions = {
      * Excluded by default: user identity and detailed page fields (path/referrer/search).
      */
     disableTelemetry?: boolean | undefined;
-    /** Customer feature flag evaluations collected with widget initialization. */
+    /** Feature flag evaluations collected with widget initialization. */
     flags?: FlagsInput | undefined;
-    /** Customer host capabilities collected with widget initialization. */
+    /** Host capabilities collected with widget initialization. */
     capabilities?: CapabilitiesInput | undefined;
     _loaderUrl?: string | undefined;
     _coreUrl?: string | undefined;
@@ -253,20 +303,33 @@ export type PrerenderCommandPayload = {
 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;
-/** Track a flow shown or dismissed event. */
+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";
-    event: "Flow Viewed" | "Flow Dismissed";
-    references: AppEventSurveyReference;
+    origin: "customer";
+    event: string;
+    properties?: Record<string, AppEventJsonValue> | undefined;
 };
 /** Attach or detach a resolved flow handle from a host container. */
 export type SetContainerCommandPayload = {
@@ -306,8 +369,8 @@ export type CloseCommandPayload = {
 export type ResetCommandPayload = {
     kind: "reset";
 };
-/** Union of all widget action payloads (open, prefetch, identify, configure, etc.). */
-export type PublicCommandPayload = OpenCommandPayload | PrefetchCommandPayload | PrerenderCommandPayload | IdentifyCommandPayload | SetContainerCommandPayload | SetDefaultContainerPolicyCommandPayload | ConfigureCommandPayload | InitCommandPayload | CloseCommandPayload | ResetCommandPayload;
+/** 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). */
@@ -324,9 +387,11 @@ 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(telemetry-contract-cleanup): Rename this SDK-facing type to
- * WidgetTelemetryEvent in a coordinated SDK-facing change so we can retire the
- * generic TelemetryEvent alias from shared telemetry.
+ *
+ * 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;