@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

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

@@ -0,0 +1,362 @@
+/**
+ * Storefront-owned Amplitude HTTP API v2 adapter.
+ *
+ * This module intentionally uses no vendor SDK or browser discovery surface. It
+ * consumes only validated commerce-broker events and sends a closed, anonymous
+ * 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.
+ */
+import type { CommerceEventBroker, CommerceEventSubscription } from "./commerce-broker.js";
+import {
+  APPROVED_MARKETING_ACTION_NAMES,
+  eventDedupeKey,
+  validateCommerceEvent,
+  type CommerceEvent,
+} from "./events.js";
+import { validateBrowserEnvironment, type BrowserEnvironment } from "./environment.js";
+import { resemblesManagedAnalyticsPii } from "./managed-analytics-value-safety.js";
+import type {
+  IntegrationEventSubscribe,
+  IntegrationLifecycleContext,
+  IntegrationLifecycleModule,
+} from "./lifecycle.js";
+import {
+  AMPLITUDE_HTTP_ADAPTER,
+  destinationIdConfigKey,
+  resolveAdapterDestinationId,
+} from "./platform-adapters.js";
+
+export const AMPLITUDE_COLLECTION_ORIGIN = "https://api2.amplitude.com" as const;
+export const AMPLITUDE_COLLECTION_URL = `${AMPLITUDE_COLLECTION_ORIGIN}/2/httpapi` as const;
+export const AMPLITUDE_HTTP_ENTRY_URL = "/platform/amplitude-http/v1/entry.mjs" as const;
+export const AMPLITUDE_HTTP_ADAPTER_VERSION = "1.0.0" as const;
+export const AMPLITUDE_HTTP_RUNTIME_ID = "native-amplitude-http-v1" as const;
+const ANONYMOUS_DEVICE_ID = "storefront-anonymous" as const;
+export const AMPLITUDE_HTTP_EVENT_TYPES = Object.freeze([
+  "storefront.page.viewed.v1",
+  "storefront.page.viewed.v2",
+  "storefront.action.activated.v1",
+] as const);
+
+export interface AmplitudeHttpEvent {
+  event_type: "page_view" | (typeof APPROVED_MARKETING_ACTION_NAMES)[number];
+  device_id: typeof ANONYMOUS_DEVICE_ID;
+  insert_id: string;
+  event_properties: { page_path: string } | Record<string, never>;
+}
+
+export const AMPLITUDE_DEDUPE_CAPACITY = 512 as const;
+const MAX_AMPLITUDE_DEDUPE_CAPACITY = 2_048;
+
+export type AmplitudeDiagnosticCode =
+  | "collection_failed"
+  | "subscription_bind_failed"
+  | "subscription_teardown_failed";
+export interface AmplitudeDiagnostic { code: AmplitudeDiagnosticCode }
+export type AmplitudeFetch = (url: string, init: RequestInit) => Promise<Pick<Response, "ok">>;
+export type AmplitudeDiagnosticObserver = (diagnostic: AmplitudeDiagnostic) => void;
+
+/** FIFO-bounded defense in depth; the commerce broker remains dedupe authority. */
+class BoundedInsertIds {
+  private readonly ids = new Set<string>();
+  readonly capacity: number;
+
+  constructor(capacity: number) {
+    const normalized = Number.isFinite(capacity)
+      ? Math.floor(capacity)
+      : AMPLITUDE_DEDUPE_CAPACITY;
+    this.capacity = Math.max(1, Math.min(MAX_AMPLITUDE_DEDUPE_CAPACITY, normalized));
+  }
+
+  seenOrRemember(id: string): boolean {
+    if (this.ids.has(id)) return true;
+    this.ids.add(id);
+    if (this.ids.size > this.capacity) {
+      const oldest = this.ids.values().next().value as string | undefined;
+      if (oldest !== undefined) this.ids.delete(oldest);
+    }
+    return false;
+  }
+}
+
+function isSafePagePath(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith("/") && !value.startsWith("//") &&
+    !value.includes("\\") && !value.includes("?") && !value.includes("#") &&
+    !resemblesManagedAnalyticsPii(value);
+}
+
+/**
+ * Reduce a broker event to the complete Amplitude allowlist. Returning null is
+ * fail-closed for unknown events, invalid/extra data, consent loss, environment
+ * disagreement, unsafe paths, or unapproved action names.
+ */
+export function mapCommerceEventToAmplitude(
+  input: unknown,
+  environment: BrowserEnvironment,
+  tenantPublicId: string,
+): AmplitudeHttpEvent | null {
+  const eventResult = validateCommerceEvent(input);
+  const environmentResult = validateBrowserEnvironment(environment);
+  if (!eventResult.ok || !environmentResult.ok || typeof tenantPublicId !== "string" || tenantPublicId.length === 0) return null;
+  const event = eventResult.value;
+  if (!(AMPLITUDE_HTTP_EVENT_TYPES as readonly string[]).includes(event.type)) return null;
+  if (event.storefront.emitter !== "browser") return null;
+  if (
+    event.storefront.tenant !== tenantPublicId ||
+    event.storefront.environment !== environmentResult.value.environment ||
+    event.storefront.siteSurface !== environmentResult.value.siteSurface
+  ) return null;
+  if (!event.consent.eligiblePurposes.includes("analytics")) return null;
+
+  const base = {
+    device_id: ANONYMOUS_DEVICE_ID,
+    insert_id: eventDedupeKey(event),
+  };
+  if (event.type === "storefront.action.activated.v1") {
+    const name = event.data["name"];
+    if (!(APPROVED_MARKETING_ACTION_NAMES as readonly unknown[]).includes(name)) return null;
+    return {
+      ...base,
+      event_type: name as (typeof APPROVED_MARKETING_ACTION_NAMES)[number],
+      event_properties: {},
+    };
+  }
+  const path = event.data["path"];
+  if (!isSafePagePath(path)) return null;
+  return { ...base, event_type: "page_view", event_properties: { page_path: path } };
+}
+
+export interface RegisterAmplitudeHttpDestinationInput {
+  broker: CommerceEventBroker;
+  /** Trusted tenant identity paired with the broker's server-stamped context. */
+  tenantPublicId: string;
+  publicConfig: Record<string, unknown>;
+  environment: BrowserEnvironment;
+  fetch: AmplitudeFetch;
+  onDiagnostic?: AmplitudeDiagnosticObserver;
+  /** Test seam; production is clamped to the fixed default. */
+  dedupeCapacity?: number;
+}
+
+export type AmplitudeRegistrationResult =
+  | { ok: true; dispose(): void }
+  | { ok: false; code: "invalid_configuration" };
+
+function report(
+  observer: AmplitudeDiagnosticObserver | undefined,
+  code: AmplitudeDiagnosticCode,
+): void {
+  try { observer?.(Object.freeze({ code })); } catch { /* diagnostics are fail-soft */ }
+}
+
+interface AmplitudeHandlerInput {
+  destinationId: string;
+  tenantPublicId: string;
+  environment: BrowserEnvironment;
+  fetcher: AmplitudeFetch;
+  observer?: AmplitudeDiagnosticObserver;
+  dedupe: BoundedInsertIds;
+  isActive(): boolean;
+}
+
+function createAmplitudeHandler(input: AmplitudeHandlerInput): (event: CommerceEvent) => void {
+  return (event) => {
+    if (!input.isActive()) return;
+    const mapped = mapCommerceEventToAmplitude(event, input.environment, input.tenantPublicId);
+    if (!mapped || input.dedupe.seenOrRemember(mapped.insert_id)) return;
+    const body = JSON.stringify({ api_key: input.destinationId, events: [mapped] });
+    try {
+      void input.fetcher(AMPLITUDE_COLLECTION_URL, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        credentials: "omit",
+        cache: "no-store",
+        mode: "cors",
+        keepalive: true,
+      }).then((response) => {
+        if (!response.ok) report(input.observer, "collection_failed");
+      }).catch(() => report(input.observer, "collection_failed"));
+    } catch {
+      report(input.observer, "collection_failed");
+    }
+  };
+}
+
+/**
+ * Register exactly one stable broker subscription. The broker supplies consent
+ * filtering and first-level logical-event dedupe; this sink keeps its own bounded
+ * insert-id window so recent replacement/re-entry cannot issue a second request. Disposal is
+ * terminal for this registration and removes the subscription synchronously.
+ */
+export function registerAmplitudeHttpDestination(
+  input: RegisterAmplitudeHttpDestinationInput,
+): AmplitudeRegistrationResult {
+  let environment: ReturnType<typeof validateBrowserEnvironment>;
+  let destinationId: string | null;
+  let fetcher: AmplitudeFetch;
+  let observer: RegisterAmplitudeHttpDestinationInput["onDiagnostic"];
+  let broker: CommerceEventBroker;
+  try {
+    environment = validateBrowserEnvironment(input.environment);
+    destinationId = environment.ok
+      ? resolveAdapterDestinationId(input.publicConfig, environment.value.environment)
+      : null;
+    fetcher = input.fetch;
+    observer = input.onDiagnostic;
+    broker = input.broker;
+  } catch {
+    return { ok: false, code: "invalid_configuration" };
+  }
+  if (
+    !environment.ok || !destinationId || !AMPLITUDE_HTTP_ADAPTER.validateId(destinationId) ||
+    typeof input.tenantPublicId !== "string" || input.tenantPublicId.length === 0 ||
+    typeof fetcher !== "function"
+  ) {
+    return { ok: false, code: "invalid_configuration" };
+  }
+
+  let disposed = false;
+  const dedupe = new BoundedInsertIds(input.dedupeCapacity ?? AMPLITUDE_DEDUPE_CAPACITY);
+  const subscription: CommerceEventSubscription = {
+    id: AMPLITUDE_HTTP_ADAPTER.adapterId,
+    consentPurpose: "analytics",
+    types: [...AMPLITUDE_HTTP_EVENT_TYPES],
+    sink: {
+      kind: "callback",
+      handler: createAmplitudeHandler({
+        destinationId,
+        tenantPublicId: input.tenantPublicId,
+        environment: environment.value,
+        fetcher,
+        observer,
+        dedupe,
+        isActive: () => !disposed,
+      }),
+    },
+  };
+  let unsubscribe: () => void;
+  try { unsubscribe = broker.subscribe(subscription); }
+  catch { return { ok: false, code: "invalid_configuration" }; }
+  return {
+    ok: true,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      try { unsubscribe(); } catch { /* disposed remains terminal */ }
+    },
+  };
+}
+
+export interface CreateAmplitudeLifecycleModuleOptions {
+  fetch?: AmplitudeFetch;
+  onDiagnostic?: AmplitudeDiagnosticObserver;
+  /** Narrow test seam; every value is clamped to a finite production ceiling. */
+  dedupeCapacity?: number;
+}
+
+type AmplitudeLifecycleState = "idle" | "initialized" | "disposed";
+
+/**
+ * Build the actual lifecycle entry behind `/platform/amplitude-http/v1/entry.mjs`.
+ * Every update invalidates the prior handler before teardown, then rebinds exactly
+ * once from the new consent/config/environment context. A teardown failure leaves
+ * the old handler inert and is retryable on the next update; dispose is terminal.
+ */
+export function createAmplitudeLifecycleModule(
+  options: CreateAmplitudeLifecycleModuleOptions = {},
+): IntegrationLifecycleModule {
+  const fetcher: AmplitudeFetch = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+  const observer = options.onDiagnostic;
+  const dedupe = new BoundedInsertIds(options.dedupeCapacity ?? AMPLITUDE_DEDUPE_CAPACITY);
+  let state: AmplitudeLifecycleState = "idle";
+  let generation = 0;
+  let unsubscribe: (() => void) | undefined;
+
+  const teardown = (): boolean => {
+    generation += 1; // any retained/stale callback becomes inert before teardown
+    if (!unsubscribe) return true;
+    try {
+      unsubscribe();
+      unsubscribe = undefined;
+      return true;
+    } catch {
+      report(observer, "subscription_teardown_failed");
+      return false;
+    }
+  };
+
+  const bind = (ctx: IntegrationLifecycleContext): void => {
+    let subscribe: IntegrationEventSubscribe | undefined;
+    let environment: ReturnType<typeof validateBrowserEnvironment>;
+    let destinationId: string | null;
+    try {
+      environment = validateBrowserEnvironment(ctx.environment);
+      const eligible = ctx.consent.unknownState === "block" &&
+        ctx.consent.eligiblePurposes.includes("analytics");
+      subscribe = ctx.subscribe;
+      destinationId = environment.ok
+        ? resolveAdapterDestinationId(ctx.config, environment.value.environment)
+        : null;
+      if (
+        ctx.appId !== AMPLITUDE_HTTP_ADAPTER.adapterId || !eligible || !subscribe ||
+        typeof ctx.tenantPublicId !== "string" || ctx.tenantPublicId.length === 0 ||
+        !environment.ok || !destinationId || !AMPLITUDE_HTTP_ADAPTER.validateId(destinationId)
+      ) return;
+    } catch {
+      return;
+    }
+
+    const ownGeneration = ++generation;
+    const handler = createAmplitudeHandler({
+      destinationId,
+      tenantPublicId: ctx.tenantPublicId,
+      environment: environment.value,
+      fetcher,
+      observer,
+      dedupe,
+      isActive: () => state === "initialized" && generation === ownGeneration,
+    });
+    try {
+      const next = subscribe({
+        consentPurpose: "analytics",
+        types: [...AMPLITUDE_HTTP_EVENT_TYPES],
+        sink: { kind: "callback", handler },
+      });
+      if (typeof next !== "function") throw new TypeError("invalid unsubscribe");
+      unsubscribe = next;
+    } catch {
+      generation += 1;
+      report(observer, "subscription_bind_failed");
+    }
+  };
+
+  return {
+    init(ctx) {
+      if (state !== "idle") return;
+      state = "initialized";
+      bind(ctx);
+    },
+    update(_reason, ctx) {
+      if (state !== "initialized") return;
+      if (!teardown()) return;
+      bind(ctx);
+    },
+    dispose() {
+      if (state === "disposed") return;
+      state = "disposed";
+      teardown();
+    },
+  };
+}
+
+/** Default export shape consumed by the exact-entry module loader. */
+export const AMPLITUDE_HTTP_LIFECYCLE_MODULE: IntegrationLifecycleModule =
+  createAmplitudeLifecycleModule();
+export default AMPLITUDE_HTTP_LIFECYCLE_MODULE;
+
+/** Build the flat public config expected by a resolved adapter declaration. */
+export function amplitudePublicConfig(environment: BrowserEnvironment, projectKey: string): Record<string, unknown> {
+  return { [destinationIdConfigKey(environment.environment)]: projectKey };
+}