@bacano/sdk 1.1.20 → 1.2.2

package/index.js

@@ -337,7 +337,8 @@ async function getWebsitePublicConfig(options) {
           pixelId: marketing.destinations.meta.pixel_id,
           diagnosticMode: marketing.destinations.meta.diagnostic_mode ?? false
         } : null,
-        clarity: marketing.destinations.clarity ? { projectId: marketing.destinations.clarity.project_id } : null
+        clarity: marketing.destinations.clarity ? { projectId: marketing.destinations.clarity.project_id } : null,
+        ...marketing.destinations.gtm ? { gtm: { containerId: marketing.destinations.gtm.container_id } } : {}
       }
     },
     legal: {
@@ -2900,6 +2901,9 @@ var ALLOWED_MARKETING_PARAMETERS = /* @__PURE__ */ new Set([
 function sanitizeMarketingUrl(input, baseUrl) {
   try {
     const url = new URL(input, baseUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return "";
+    url.username = "";
+    url.password = "";
     const safeParameters = new URLSearchParams();
     for (const [key, value] of url.searchParams.entries()) {
       if (ALLOWED_MARKETING_PARAMETERS.has(key.toLowerCase()) && !SENSITIVE_PARAMETER_PATTERNS.some((pattern) => pattern.test(key))) {
@@ -5675,50 +5679,65 @@ function createContentModule(graphqlUrl, getHeaders, getContext, storageUrl) {
   };
 }
 
-// libs/sdk/src/marketing/clarity.ts
-var initializedDestinations = /* @__PURE__ */ new Set();
-function clarityWindow() {
-  return typeof window === "undefined" ? null : window;
-}
-function prepareClarity(projectId) {
-  const target = clarityWindow();
-  if (!target || initializedDestinations.has(projectId)) return;
-  if (!target.clarity) {
-    const clarity = function() {
-      clarity.q ??= [];
-      clarity.q.push(arguments);
-    };
-    target.clarity = clarity;
+// libs/sdk/src/marketing/interactions.ts
+var WEBSITE_INTERACTION_EVENTS = [
+  "cta_click",
+  "form_open",
+  "form_start",
+  "form_step_complete",
+  "form_submit_attempt",
+  "form_submit_error",
+  "form_submit_success"
+];
+function isInteractionEvent(name) {
+  return WEBSITE_INTERACTION_EVENTS.some((candidate) => candidate === name);
+}
+function isInteractionIdentifier(value) {
+  return typeof value === "string" && /^[a-z][a-z0-9_-]{0,63}$/.test(value);
+}
+function isBrowserMarketingEvent(name) {
+  return isInteractionEvent(name) || [
+    "page_view",
+    "search",
+    "view_item_list",
+    "select_item",
+    "view_item",
+    "add_to_cart",
+    "remove_from_cart",
+    "view_cart",
+    "begin_checkout",
+    "add_shipping_info",
+    "add_payment_info",
+    "contact"
+  ].includes(name);
+}
+function interactionParameters(event) {
+  if (!isInteractionEvent(event.eventName)) return {};
+  if (event.eventName === "cta_click" ? !isInteractionIdentifier(event.ctaId) : !isInteractionIdentifier(event.formKey))
+    return null;
+  if (event.eventName === "form_step_complete" && !isInteractionIdentifier(event.stepKey))
+    return null;
+  if (event.eventName === "form_submit_error" && !["validation", "network", "rejected", "unavailable"].includes(
+    event.errorCategory ?? ""
+  ))
+    return null;
+  const params = {};
+  for (const [key, value] of Object.entries({
+    form_key: event.formKey,
+    cta_id: event.ctaId,
+    placement: event.placement,
+    step_key: event.stepKey
+  })) {
+    if (value === void 0) continue;
+    if (!isInteractionIdentifier(value)) return null;
+    params[key] = value;
   }
-  initializedDestinations.add(projectId);
-}
-function loadClarityScript(projectId) {
-  if (typeof document === "undefined") return;
-  const id = `bacano-clarity-${projectId}`;
-  if (document.getElementById(id)) return;
-  const script = document.createElement("script");
-  script.id = id;
-  script.async = true;
-  script.src = `https://www.clarity.ms/tag/${encodeURIComponent(projectId)}`;
-  script.referrerPolicy = "strict-origin-when-cross-origin";
-  document.head.appendChild(script);
-}
-function sendClarityEvent(eventName) {
-  clarityWindow()?.clarity?.("event", eventName);
+  if (event.eventName === "form_submit_error" && event.errorCategory)
+    params.error_category = event.errorCategory;
+  return params;
 }
-
-// libs/sdk/src/marketing/domain.ts
-function matchesCanonicalMarketingHost(canonicalDomain, currentHostname) {
-  if (canonicalDomain === void 0) return true;
-  if (!canonicalDomain?.trim()) return false;
-  try {
-    const configuredHost = new URL(
-      canonicalDomain.includes("://") ? canonicalDomain : `https://${canonicalDomain}`
-    ).hostname.toLowerCase();
-    return currentHostname.toLowerCase() === configuredHost;
-  } catch {
-    return false;
-  }
+function newMarketingEventId() {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `evt_${Date.now()}_${Math.random().toString(16).slice(2)}`;
 }
 
 // libs/sdk/src/marketing/ga4.ts
@@ -5746,19 +5765,20 @@ var WEBSITE_MARKETING_CONTACT_PLACEMENTS = [
   "contact_page"
 ];
 
-// libs/sdk/src/marketing/runtime.ts
+// libs/sdk/src/marketing/browser-adapters.ts
 var initializedGa4Destinations = /* @__PURE__ */ new Set();
 var initializedMetaDestinations = /* @__PURE__ */ new Set();
 function marketingWindow() {
   return typeof window === "undefined" ? null : window;
 }
-function loadScriptOnce(id, source) {
+function loadScriptOnce(id, source, onError) {
   if (typeof document === "undefined" || document.getElementById(id)) return;
   const script = document.createElement("script");
   script.id = id;
   script.async = true;
   script.src = source;
   script.referrerPolicy = "strict-origin-when-cross-origin";
+  script.onerror = () => onError?.();
   document.head.appendChild(script);
 }
 function prepareGa4(measurementId) {
@@ -5773,10 +5793,11 @@ function prepareGa4(measurementId) {
   target.gtag("config", measurementId, { send_page_view: false });
   initializedGa4Destinations.add(measurementId);
 }
-function loadGa4Script(measurementId) {
+function loadGa4Script(measurementId, onError) {
   loadScriptOnce(
     `bacano-ga4-${measurementId}`,
-    `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(measurementId)}`
+    `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(measurementId)}`,
+    onError
   );
 }
 function captureGa4ClientId(measurementId, websiteId, diagnostic) {
@@ -5824,10 +5845,11 @@ function prepareMeta(pixelId) {
   target.fbq("init", pixelId);
   initializedMetaDestinations.add(pixelId);
 }
-function loadMetaScript() {
+function loadMetaScript(onError) {
   loadScriptOnce(
     "bacano-meta-pixel",
-    "https://connect.facebook.net/en_US/fbevents.js"
+    "https://connect.facebook.net/en_US/fbevents.js",
+    onError
   );
 }
 function scheduleScriptLoad(load, strategy) {
@@ -5891,10 +5913,12 @@ function contactPlacementFor(event) {
   }
   return placement;
 }
-function sendGa4(event, diagnosticMode) {
+function sendGa4(event, diagnosticMode, measurementId) {
   const target = marketingWindow();
   const contactPlacement = contactPlacementFor(event);
   target?.gtag?.("event", event.eventName, {
+    send_to: measurementId,
+    ...interactionParameters(event),
     currency: event.currency,
     value: event.value,
     search_term: event.searchTerm,
@@ -5911,15 +5935,17 @@ function sendGa4(event, diagnosticMode) {
     debug_mode: diagnosticMode ? true : void 0
   });
 }
-function sendMeta(event) {
+function sendMeta(event, pixelId) {
   const target = marketingWindow();
   const eventName = metaEventName(event.eventName);
   const isStandard = eventName !== event.eventName;
   const contactPlacement = contactPlacementFor(event);
   target?.fbq?.(
-    isStandard ? "track" : "trackCustom",
+    isStandard ? "trackSingle" : "trackSingleCustom",
+    pixelId,
     eventName,
     {
+      ...interactionParameters(event),
       currency: event.currency,
       value: event.value,
       search_string: event.searchTerm,
@@ -5936,40 +5962,192 @@ function sendMeta(event) {
     { eventID: event.eventId }
   );
 }
-function newEventId() {
-  return typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `evt_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+
+// libs/sdk/src/marketing/clarity.ts
+var initializedDestinations = /* @__PURE__ */ new Set();
+function clarityWindow() {
+  return typeof window === "undefined" ? null : window;
+}
+function prepareClarity(projectId) {
+  const target = clarityWindow();
+  if (!target || initializedDestinations.has(projectId)) return;
+  if (!target.clarity) {
+    const clarity = function() {
+      clarity.q ??= [];
+      clarity.q.push(arguments);
+    };
+    target.clarity = clarity;
+  }
+  initializedDestinations.add(projectId);
+}
+function loadClarityScript(projectId, onError) {
+  if (typeof document === "undefined") return;
+  const id = `bacano-clarity-${projectId}`;
+  if (document.getElementById(id)) return;
+  const script = document.createElement("script");
+  script.id = id;
+  script.async = true;
+  script.src = `https://www.clarity.ms/tag/${encodeURIComponent(projectId)}`;
+  script.referrerPolicy = "strict-origin-when-cross-origin";
+  script.onerror = () => onError?.();
+  document.head.appendChild(script);
+}
+function sendClarityEvent(eventName) {
+  clarityWindow()?.clarity?.("event", eventName);
+}
+
+// libs/sdk/src/marketing/domain.ts
+function matchesCanonicalMarketingHost(canonicalDomain, currentHostname) {
+  if (canonicalDomain === void 0) return true;
+  if (!canonicalDomain?.trim()) return false;
+  try {
+    const configuredHost = new URL(
+      canonicalDomain.includes("://") ? canonicalDomain : `https://${canonicalDomain}`
+    ).hostname.toLowerCase();
+    return currentHostname.toLowerCase() === configuredHost;
+  } catch {
+    return false;
+  }
+}
+
+// libs/sdk/src/marketing/gtm.ts
+var CONTAINER_ID = /^GTM-[A-Z0-9]{4,32}$/;
+var preparedQueues = /* @__PURE__ */ new WeakMap();
+function prepareGtm(containerId) {
+  const target = marketingWindow();
+  if (!target || !CONTAINER_ID.test(containerId)) return;
+  target.dataLayer ??= [];
+  const containers = preparedQueues.get(target.dataLayer) ?? /* @__PURE__ */ new Set();
+  if (containers.has(containerId)) return;
+  target.dataLayer.push({ "gtm.start": Date.now(), event: "gtm.js" });
+  containers.add(containerId);
+  preparedQueues.set(target.dataLayer, containers);
+}
+function loadGtmScript(containerId, onError) {
+  const target = marketingWindow();
+  if (!target || typeof document === "undefined" || !CONTAINER_ID.test(containerId))
+    return;
+  const id = `bacano-gtm-${containerId}`;
+  if (document.getElementById(id)) return;
+  prepareGtm(containerId);
+  const script = document.createElement("script");
+  script.id = id;
+  script.async = true;
+  script.src = `https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(containerId)}`;
+  script.referrerPolicy = "strict-origin-when-cross-origin";
+  script.onerror = () => onError();
+  document.head.appendChild(script);
+}
+function sendGtm(event) {
+  const target = marketingWindow();
+  if (!target?.dataLayer) return;
+  target.dataLayer.push({ bacano: null });
+  target.dataLayer.push({
+    event: `bacano_${event.eventName}`,
+    bacano: {
+      schema_version: event.schemaVersion,
+      event_name: event.eventName,
+      event_id: event.eventId,
+      ...interactionParameters(event),
+      page_location: event.pageLocation,
+      currency: event.currency,
+      value: event.value,
+      items: mapGa4Items(event.items),
+      item_list_id: event.itemListId,
+      item_list_name: event.itemListName,
+      shipping_tier: event.shippingTier,
+      payment_type: event.paymentType,
+      method: event.contactMethod,
+      contact_placement: event.eventName === "contact" && WEBSITE_MARKETING_CONTACT_PLACEMENTS.some(
+        (value) => value === event.contactPlacement
+      ) ? event.contactPlacement : void 0
+    }
+  });
 }
+
+// libs/sdk/src/marketing/runtime.ts
 function createWebsiteMarketingRuntime(options) {
   let destroyed = false;
+  const dispatched = /* @__PURE__ */ new Set();
+  const observer = options.diagnostic;
+  const diagnostic = (value) => {
+    try {
+      observer?.(value);
+    } catch {
+    }
+  };
+  options = { ...options, diagnostic };
   let cancelScheduledLoad = () => void 0;
   const target = marketingWindow();
-  const enabled = options.config.enabled && Boolean(
+  const enabled = options.config.enabled && options.measurementAllowed !== false && Boolean(
     target && matchesCanonicalMarketingHost(
       options.canonicalDomain,
       target.location.hostname
     )
   ) && Boolean(
-    options.config.destinations.ga4 || options.config.destinations.meta || options.config.destinations.clarity
+    options.config.destinations.ga4 || options.config.destinations.meta || options.config.destinations.clarity || options.config.destinations.gtm
   );
+  if (!enabled)
+    diagnostic({
+      level: "debug",
+      code: !options.config.enabled ? "MARKETING_DISABLED" : options.measurementAllowed === false ? "MEASUREMENT_NOT_ALLOWED" : !target ? "SERVER_RENDER" : !matchesCanonicalMarketingHost(
+        options.canonicalDomain,
+        target.location.hostname
+      ) ? "DOMAIN_NOT_ALLOWED" : "PROVIDER_NOT_CONFIGURED",
+      message: "Measurement is inactive; no events are emitted"
+    });
   if (enabled) {
+    const guard = (provider, action) => {
+      try {
+        action();
+      } catch {
+        diagnostic({
+          level: "warning",
+          code: "RUNTIME_INITIALIZATION_FAILED",
+          message: `${provider}: initialization failed`
+        });
+      }
+    };
+    const scriptError = (provider) => () => diagnostic({
+      level: "warning",
+      code: "SCRIPT_LOAD_FAILED",
+      message: `${provider}: script could not load (network, CSP or blocker); external reception is unverified`
+    });
     try {
       if (options.config.destinations.ga4) {
-        prepareGa4(options.config.destinations.ga4.measurementId);
+        const { measurementId } = options.config.destinations.ga4;
+        guard("GA4", () => prepareGa4(measurementId));
       }
       if (options.config.destinations.meta) {
-        prepareMeta(options.config.destinations.meta.pixelId);
+        const { pixelId } = options.config.destinations.meta;
+        guard("Meta", () => prepareMeta(pixelId));
       }
       if (options.config.destinations.clarity) {
-        prepareClarity(options.config.destinations.clarity.projectId);
+        const { projectId } = options.config.destinations.clarity;
+        guard("Clarity", () => prepareClarity(projectId));
+      }
+      if (options.config.destinations.gtm) {
+        const { containerId } = options.config.destinations.gtm;
+        guard("GTM", () => prepareGtm(containerId));
       }
       cancelScheduledLoad = scheduleScriptLoad(() => {
         if (destroyed) return;
         if (options.config.destinations.ga4) {
-          loadGa4Script(options.config.destinations.ga4.measurementId);
+          const { measurementId } = options.config.destinations.ga4;
+          guard("GA4", () => loadGa4Script(measurementId, scriptError("GA4")));
         }
-        if (options.config.destinations.meta) loadMetaScript();
+        if (options.config.destinations.meta)
+          guard("Meta", () => loadMetaScript(scriptError("Meta")));
         if (options.config.destinations.clarity) {
-          loadClarityScript(options.config.destinations.clarity.projectId);
+          const { projectId } = options.config.destinations.clarity;
+          guard(
+            "Clarity",
+            () => loadClarityScript(projectId, scriptError("Clarity"))
+          );
+        }
+        if (options.config.destinations.gtm) {
+          const { containerId } = options.config.destinations.gtm;
+          guard("GTM", () => loadGtmScript(containerId, scriptError("GTM")));
         }
       }, options.scriptLoadStrategy);
       captureWebsiteMarketingAttribution(
@@ -5991,11 +6169,11 @@ function createWebsiteMarketingRuntime(options) {
       if (options.config.destinations.meta) {
         refreshWebsiteMarketingMetaContext(options.websiteId);
       }
-    } catch (error) {
+    } catch {
       options.diagnostic?.({
         level: "warning",
         code: "RUNTIME_INITIALIZATION_FAILED",
-        message: error instanceof Error ? error.message : "Initialization failed"
+        message: "Marketing initialization failed; external reception is unverified"
       });
     }
   }
@@ -6003,41 +6181,99 @@ function createWebsiteMarketingRuntime(options) {
     enabled,
     track(input) {
       if (!enabled || destroyed) return;
+      if (!isBrowserMarketingEvent(input.eventName)) {
+        diagnostic({
+          level: "warning",
+          code: "INVALID_EVENT",
+          message: "Unknown or server-owned event rejected"
+        });
+        return;
+      }
+      try {
+        captureWebsiteMarketingAttribution(
+          options.websiteId,
+          options.config.attributionWindowDays
+        );
+      } catch {
+      }
       const event = {
         ...input,
         schemaVersion: 1,
-        eventId: input.eventId ?? newEventId(),
+        eventId: input.eventId ?? newMarketingEventId(),
         occurredAt: input.occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
         currency: input.currency ?? options.config.currencyCode,
         pageLocation: sanitizeMarketingUrl(
           input.pageLocation ?? (typeof window === "undefined" ? "" : window.location.href)
         )
       };
-      try {
-        if (options.config.destinations.ga4) {
-          sendGa4(event, options.config.destinations.ga4.diagnosticMode);
+      if (isInteractionEvent(event.eventName)) {
+        if (!interactionParameters(event) || !/^[a-zA-Z0-9_-]{1,100}$/.test(event.eventId)) {
+          diagnostic({
+            level: "warning",
+            code: "INVALID_INTERACTION",
+            message: "Interaction rejected by the public contract",
+            eventName: event.eventName
+          });
+          return;
         }
-        if (options.config.destinations.meta) sendMeta(event);
-        if (options.config.destinations.clarity) {
-          sendClarityEvent(event.eventName);
+        for (const key of [
+          "currency",
+          "value",
+          "searchTerm",
+          "itemListId",
+          "itemListName",
+          "shippingTier",
+          "paymentType",
+          "contactMethod",
+          "contactPlacement",
+          "items",
+          "pageTitle"
+        ])
+          delete event[key];
+      }
+      const identity = `${event.eventName}:${event.eventId}`;
+      if (dispatched.has(identity)) return;
+      dispatched.add(identity);
+      const oldest = dispatched.values().next().value;
+      if (dispatched.size > 1e3 && oldest) dispatched.delete(oldest);
+      const dispatch = (provider, send) => {
+        try {
+          send();
+          diagnostic({
+            level: "debug",
+            code: "EVENT_DISPATCHED",
+            message: `${provider}: passed to adapter; external reception is unverified`,
+            eventName: event.eventName
+          });
+        } catch {
+          diagnostic({
+            level: "warning",
+            code: "EVENT_DISPATCH_FAILED",
+            message: `${provider}: adapter failed`,
+            eventName: event.eventName
+          });
         }
-        options.diagnostic?.({
-          level: "debug",
-          code: "EVENT_DISPATCHED",
-          message: "Marketing event dispatched",
-          eventName: event.eventName
-        });
-      } catch (error) {
-        options.diagnostic?.({
-          level: "warning",
-          code: "EVENT_DISPATCH_FAILED",
-          message: error instanceof Error ? error.message : "Dispatch failed",
-          eventName: event.eventName
-        });
+      };
+      if (options.config.destinations.ga4) {
+        const ga4 = options.config.destinations.ga4;
+        dispatch(
+          "GA4",
+          () => sendGa4(event, ga4.diagnosticMode, ga4.measurementId)
+        );
+      }
+      if (options.config.destinations.meta) {
+        const meta = options.config.destinations.meta;
+        dispatch("Meta", () => sendMeta(event, meta.pixelId));
+      }
+      if (options.config.destinations.clarity) {
+        dispatch("Clarity", () => sendClarityEvent(event.eventName));
+      }
+      if (options.config.destinations.gtm && /^GTM-[A-Z0-9]{4,32}$/.test(options.config.destinations.gtm.containerId)) {
+        dispatch("GTM", () => sendGtm(event));
       }
     },
     captureAttribution() {
-      if (!enabled) return null;
+      if (!enabled || destroyed) return null;
       captureWebsiteMarketingAttribution(
         options.websiteId,
         options.config.attributionWindowDays
@@ -6048,7 +6284,7 @@ function createWebsiteMarketingRuntime(options) {
       return getWebsiteMarketingAttribution(options.websiteId);
     },
     getAttribution() {
-      if (!enabled) return null;
+      if (!enabled || destroyed) return null;
       if (options.config.destinations.meta) {
         refreshWebsiteMarketingMetaContext(options.websiteId);
       }

package/marketing/browser-adapters.d.ts

@@ -0,0 +1,30 @@
+import type { WebsiteMarketingBrowserEvent, WebsiteMarketingRuntimeOptions } from "./types";
+type TrackingFunction = (...args: unknown[]) => void;
+type MetaTrackingFunction = TrackingFunction & {
+    callMethod?: TrackingFunction;
+    push?: TrackingFunction;
+    loaded?: boolean;
+    version?: string;
+    queue?: unknown[];
+};
+type MarketingWindow = Window & {
+    dataLayer?: unknown[];
+    gtag?: TrackingFunction;
+    fbq?: MetaTrackingFunction;
+    _fbq?: MetaTrackingFunction;
+    requestIdleCallback?: (callback: () => void, options?: {
+        timeout: number;
+    }) => number;
+    cancelIdleCallback?: (handle: number) => void;
+};
+export declare function marketingWindow(): MarketingWindow | null;
+export declare function prepareGa4(measurementId: string): void;
+export declare function loadGa4Script(measurementId: string, onError: () => void): void;
+export declare function captureGa4ClientId(measurementId: string, websiteId: string, diagnostic?: WebsiteMarketingRuntimeOptions["diagnostic"]): void;
+export declare function captureGa4SessionId(measurementId: string, websiteId: string, diagnostic?: WebsiteMarketingRuntimeOptions["diagnostic"]): void;
+export declare function prepareMeta(pixelId: string): void;
+export declare function loadMetaScript(onError: () => void): void;
+export declare function scheduleScriptLoad(load: () => void, strategy: WebsiteMarketingRuntimeOptions["scriptLoadStrategy"]): () => void;
+export declare function sendGa4(event: WebsiteMarketingBrowserEvent, diagnosticMode: boolean, measurementId: string): void;
+export declare function sendMeta(event: WebsiteMarketingBrowserEvent, pixelId: string): void;
+export {};

package/marketing/clarity.d.ts

@@ -1,3 +1,3 @@
 export declare function prepareClarity(projectId: string): void;
-export declare function loadClarityScript(projectId: string): void;
+export declare function loadClarityScript(projectId: string, onError?: () => void): void;
 export declare function sendClarityEvent(eventName: string): void;

package/marketing/form-interactions.d.ts

@@ -0,0 +1,12 @@
+import type { WebsiteFormResponseResult } from "../types";
+import { type WebsiteFormErrorCategory } from "./interactions";
+import type { WebsiteMarketingRuntime } from "./types";
+/** One instance per mounted form. No answers, storage or provider listeners. */
+export declare function createFormInteractionTracker(getRuntime: () => WebsiteMarketingRuntime, formKey: string): {
+    setVisible(next: boolean): void;
+    start(): void;
+    stepComplete(stepKey: string): void;
+    beginSubmit(): boolean;
+    fail(errorCategory: WebsiteFormErrorCategory): void;
+    complete(result: WebsiteFormResponseResult | void): void;
+};

package/marketing/gtm.d.ts

@@ -0,0 +1,6 @@
+import type { WebsiteMarketingBrowserEvent } from "./types";
+/** Preserve the shared Google queue, including an existing native gtag.js. */
+export declare function prepareGtm(containerId: string): void;
+export declare function loadGtmScript(containerId: string, onError: () => void): void;
+/** Explicit allowlist: never spread caller input, customer data or attribution. */
+export declare function sendGtm(event: WebsiteMarketingBrowserEvent): void;

package/marketing/index.d.ts

@@ -1,4 +1,6 @@
 export { captureWebsiteMarketingAttribution, getWebsiteMarketingAttribution, serializeWebsiteMarketingAttribution, } from "./attribution";
+export type { WebsiteFormErrorCategory, WebsiteInteractionContext, WebsiteInteractionEventName, } from "./interactions";
+export { WEBSITE_INTERACTION_EVENTS } from "./interactions";
 export { createWebsiteMarketingRuntime } from "./runtime";
 export { getAllowedMarketingParameters, sanitizeMarketingUrl, } from "./sanitize";
 export type { WebsiteAdvertisingConsent, WebsiteMarketingAttribution, WebsiteMarketingBrowserEvent, WebsiteMarketingBrowserEventName, WebsiteMarketingContactPlacement, WebsiteMarketingDiagnostic, WebsiteMarketingItem, WebsiteMarketingRuntime, WebsiteMarketingRuntimeOptions, WebsiteMarketingScriptLoadStrategy, WebsiteMarketingTouchpoint, } from "./types";

package/marketing/interactions.d.ts

@@ -0,0 +1,19 @@
+import type { WebsiteMarketingBrowserEvent } from "./types";
+export declare const WEBSITE_INTERACTION_EVENTS: readonly ["cta_click", "form_open", "form_start", "form_step_complete", "form_submit_attempt", "form_submit_error", "form_submit_success"];
+export type WebsiteInteractionEventName = (typeof WEBSITE_INTERACTION_EVENTS)[number];
+export type WebsiteFormErrorCategory = "validation" | "network" | "rejected" | "unavailable";
+export interface WebsiteInteractionContext {
+    /** Public definition key, never a field value. */
+    formKey?: string;
+    /** Stable technical identifiers (1–64 characters), not button text. */
+    ctaId?: string;
+    placement?: string;
+    stepKey?: string;
+    errorCategory?: WebsiteFormErrorCategory;
+}
+export declare function isInteractionEvent(name: string): name is WebsiteInteractionEventName;
+export declare function isInteractionIdentifier(value: unknown): value is string;
+export declare function isBrowserMarketingEvent(name: string): boolean;
+/** Allowlisted projection: never spread caller fields into analytics payloads. */
+export declare function interactionParameters(event: WebsiteMarketingBrowserEvent): Record<string, string> | null;
+export declare function newMarketingEventId(): string;

package/marketing/types.d.ts

@@ -1,6 +1,7 @@
 import type { WebsiteMarketingPublicConfig } from "../types";
+import type { WebsiteInteractionContext, WebsiteInteractionEventName } from "./interactions";
 export declare const MARKETING_SCHEMA_VERSION: 1;
-export type WebsiteMarketingBrowserEventName = "page_view" | "search" | "view_item_list" | "select_item" | "view_item" | "add_to_cart" | "remove_from_cart" | "view_cart" | "begin_checkout" | "add_shipping_info" | "add_payment_info" | "contact";
+export type WebsiteMarketingBrowserEventName = WebsiteInteractionEventName | "page_view" | "search" | "view_item_list" | "select_item" | "view_item" | "add_to_cart" | "remove_from_cart" | "view_cart" | "begin_checkout" | "add_shipping_info" | "add_payment_info" | "contact";
 export declare const WEBSITE_MARKETING_CONTACT_PLACEMENTS: readonly ["product_detail", "floating", "header", "footer", "contact_page"];
 export type WebsiteMarketingContactPlacement = (typeof WEBSITE_MARKETING_CONTACT_PLACEMENTS)[number];
 export interface WebsiteMarketingItem {
@@ -15,7 +16,7 @@ export interface WebsiteMarketingItem {
     itemVariant?: string | null;
     index?: number;
 }
-export interface WebsiteMarketingBrowserEvent {
+export interface WebsiteMarketingBrowserEvent extends WebsiteInteractionContext {
     schemaVersion: typeof MARKETING_SCHEMA_VERSION;
     eventId: string;
     eventName: WebsiteMarketingBrowserEventName;
@@ -88,6 +89,8 @@ export type WebsiteMarketingDiagnostic = {
 };
 export type WebsiteMarketingScriptLoadStrategy = "immediate" | "idle";
 export interface WebsiteMarketingRuntimeOptions {
+    /** Host consent integration: false prevents scripts, events and attribution. */
+    measurementAllowed?: boolean;
     websiteId: string;
     config: WebsiteMarketingPublicConfig;
     /**