@tokenoftrust/storefront-runner 2.2.17 → 2.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.17",
+  "version": "2.2.19",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/integration/native-amplitude.ts

@@ -6,6 +6,15 @@
  * payload to one exact collection endpoint. The fixed device value groups events
  * as non-identifying storefront traffic; it is never derived from a browser,
  * person, account, persisted client value, network address, or device signal.
+ *
+ * Channel ATTRIBUTION (UTM tokens + the referrer's origin) is allowed through as
+ * plain `event_properties`: it is a minimized, campaign-scoped label already
+ * validated upstream (`events.ts` `validatePageAttribution`), not a visitor or
+ * device signal, and this adapter re-screens each value for PII before sending
+ * it regardless. A persistent/session identity is a different thing entirely —
+ * it stays out, on purpose: `device_id` remains the fixed, non-identifying value
+ * below and there is still no `session_id`, `user_id`, or any persisted client
+ * value anywhere in this file.
  */
 import type { CommerceEventBroker, CommerceEventSubscription } from "./commerce-broker.js";
 import {
@@ -47,13 +56,23 @@ export const AMPLITUDE_HTTP_EVENT_TYPES = Object.freeze([
   "storefront.action.activated.v1",
 ] as const);
 
+/** The flat channel-attribution keys this adapter will forward, mirroring `events.ts` UTM_FIELDS. */
+export type AmplitudeAttributionProperties = Partial<{
+  utm_source: string;
+  utm_medium: string;
+  utm_campaign: string;
+  utm_term: string;
+  utm_content: string;
+  referrer_origin: string;
+}>;
+
 export interface AmplitudeHttpEvent {
   event_type: "page_view" | (typeof APPROVED_MARKETING_ACTION_NAMES)[number];
   device_id: typeof ANONYMOUS_DEVICE_ID;
   insert_id: string;
   /** Occurrence time, epoch milliseconds. */
   time: number;
-  event_properties: GovernedEventProperties & { page_path?: string };
+  event_properties: GovernedEventProperties & { page_path?: string } & AmplitudeAttributionProperties;
 }
 
 export const AMPLITUDE_DEDUPE_CAPACITY = 512 as const;
@@ -104,6 +123,44 @@ class BoundedInsertIds {
   }
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Flatten the already-validated `data.attribution` object (`events.ts`
+ * `validatePageAttribution` — a minimized referrer origin plus up to five UTM
+ * tokens) into Amplitude's flat `event_properties`. Re-screened for PII here
+ * rather than trusted from upstream validation alone, matching `isSafePagePath`'s
+ * own double-check: a field that resembles PII is dropped individually rather
+ * than failing the whole page-view event.
+ */
+function extractAttributionProperties(data: Record<string, unknown>): AmplitudeAttributionProperties {
+  const attribution = data["attribution"];
+  if (!isPlainObject(attribution)) return {};
+  const out: AmplitudeAttributionProperties = {};
+
+  const utm = attribution["utm"];
+  if (isPlainObject(utm)) {
+    for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
+      const value = utm[key];
+      if (typeof value === "string" && value.length > 0 && !resemblesManagedAnalyticsPii(value)) {
+        out[`utm_${key}`] = value;
+      }
+    }
+  }
+
+  const referrer = attribution["referrer"];
+  if (isPlainObject(referrer)) {
+    const origin = referrer["origin"];
+    if (typeof origin === "string" && origin.length > 0 && !resemblesManagedAnalyticsPii(origin)) {
+      out.referrer_origin = origin;
+    }
+  }
+
+  return out;
+}
+
 function isSafePagePath(value: unknown): value is string {
   return typeof value === "string" && value.startsWith("/") && !value.startsWith("//") &&
     !value.includes("\\") && !value.includes("?") && !value.includes("#") &&
@@ -166,7 +223,12 @@ export function mapCommerceEventToAmplitude(
   }
   const path = event.data["path"];
   if (!isSafePagePath(path)) return null;
-  return { ...base, event_type: "page_view", event_properties: { ...governed, page_path: path } };
+  const attribution = extractAttributionProperties(event.data);
+  return {
+    ...base,
+    event_type: "page_view",
+    event_properties: { ...governed, page_path: path, ...attribution },
+  };
 }
 
 export interface RegisterAmplitudeHttpDestinationInput {