@compilacion/colleciones-clientos 2.0.30 → 2.0.33

package/dist/browser.gtm.js

@@ -18,30 +18,6 @@
       }
   };
 
-  /**
-   * Collects browser-related context values like screen size, language, etc.
-   * Returns an empty object if not in browser environment.
-   * @returns {Object}
-   */
-  const getBrowserContext = function() {
-      if (typeof window === 'undefined' || typeof navigator === 'undefined') {
-          return {};
-      }
-      return {
-          hasFocus: document.hasFocus(),
-          language: navigator.language,
-          platform: navigator.platform,
-          referrer: document.referrer,
-          screenHeight: window.screen.height,
-          screenWidth: window.screen.width,
-          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-          url: window.location.href,
-          userAgent: navigator.userAgent,
-          viewportHeight: window.innerHeight,
-          viewportWidth: window.innerWidth,
-      };
-  };
-
   const formatToCamelCase = function(input) {
     return input
       .replace(/[^a-zA-Z0-9]+/g, ' ')
@@ -259,6 +235,27 @@
           this.context[context] = value;
       }
 
+      /**
+       * Records a namespaced enrichment under `meta.enrichments`. A producer or
+       * processor the event passes through claims its own `name` ("I am X") and may
+       * declare what subject the data is `about` ("this tells something about Y"), so a
+       * model-aware consumer (e.g. the server) can map it onto entity state. Kept OUT
+       * of `context` on purpose: enrichments are transport/environment metadata, not
+       * part of the domain-validated event payload.
+       * @param {string} name - The enrichment namespace (the source identity).
+       * @param {string|string[]} about - The subject(s) the data describes (recommended).
+       * @param {*} data - The contributed payload.
+       */
+      setEnrichment = function(name, about, data) {
+          if (typeof name !== 'string') {
+              throw new Error('Enrichment name must be a string');
+          }
+          if (!this.meta.enrichments) {
+              this.meta.enrichments = {};
+          }
+          this.meta.enrichments[name] = { about, data };
+      }
+
       /**
        * Alias for `setReference` for compatibility.
        * Declares an external entity referenced by this event.
@@ -626,6 +623,44 @@
           this.emitters = emitters;
           this.trackerName = trackerName;
           this.appName = appName;
+          this.handlers = [];
+      }
+
+      /**
+       * Register an enrichment handler. A handler self-identifies (`name` — "I am X")
+       * and may declare what it is `about` (the subject(s) — "this tells about Y"); on
+       * track it contributes `collect(event)` into `meta.enrichments[name]`. An optional
+       * `appliesTo(event)` lets a handler contribute only for relevant events, and
+       * `collect` may return `null`/`undefined` to contribute nothing for this event.
+       * Handlers stay model-agnostic — `about` is a plain subject string (or array); a
+       * model-aware consumer (the server) does the actual mapping.
+       * @param {{name: string, about?: string|string[], collect: function, appliesTo?: function}} handler
+       * @returns {CollecionesTracker} this (chainable).
+       */
+      use(handler) {
+          if (!handler || typeof handler.name !== 'string' || typeof handler.collect !== 'function') {
+              throw new Error('Handler must have a string `name` and a `collect(event)` function');
+          }
+          this.handlers.push(handler);
+          return this;
+      }
+
+      /** Run every registered handler against the event, writing namespaced enrichments. */
+      runHandlers(collecionesEvent) {
+          this.handlers.forEach((handler) => {
+              try {
+                  if (typeof handler.appliesTo === 'function' && !handler.appliesTo(collecionesEvent)) {
+                      return;
+                  }
+                  const data = handler.collect(collecionesEvent);
+                  if (data === undefined || data === null) {
+                      return; // handler declined to contribute for this event
+                  }
+                  collecionesEvent.setEnrichment(handler.name, handler.about, data);
+              } catch (error) {
+                  // A failing handler must never drop the event; skip its enrichment.
+              }
+          });
       }
 
       /**
@@ -638,7 +673,8 @@
               throw new Error('Event must be of type CollecionesEvent');
           }
           collecionesEvent.setTracker(this.trackerName);
-          collecionesEvent.setAppName(this.appName); 
+          collecionesEvent.setAppName(this.appName);
+          this.runHandlers(collecionesEvent);
           this.emitters.forEach(element => {
               element.track(collecionesEvent, this.trackerName, this.appName);
           });
@@ -660,31 +696,236 @@
   }
 
   /**
-   * Web-specific tracker that enriches events with browser context before sending them.
-   * Extends the base CollecionesTracker.
+   * Default browser-context enrichment handler. Contributes the page/browser
+   * environment under `meta.enrichments.browserContext`.
+   *
+   * This is transport/environment metadata — deliberately NOT part of the
+   * domain-validated `context`. A model-aware consumer (the server) routes each field
+   * onto the matching attribute of one of the declared subjects. Returns an empty
+   * payload outside a browser.
+   */
+  const browserContextHandler = {
+      name: 'browserContext',
+      about: ['session', 'webpage'],
+      collect() {
+          if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+              return {};
+          }
+          return {
+              hasFocus: document.hasFocus(),
+              language: navigator.language,
+              platform: navigator.platform,
+              referrer: document.referrer,
+              screenHeight: window.screen.height,
+              screenWidth: window.screen.width,
+              timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+              url: window.location.href,
+              userAgent: navigator.userAgent,
+              viewportHeight: window.innerHeight,
+              viewportWidth: window.innerWidth,
+          };
+      },
+  };
+
+  /**
+   * Marketing / attribution handler. Parses the page URL's query string for the
+   * standard UTM parameters and the common ad-network click identifiers, so the
+   * model-aware consumer (the server) can attribute the session/visitor.
+   *
+   * Declares `about: ['session', 'visitor']` — attribution describes entity state,
+   * not event payload. Returns `null` when the URL carries no marketing parameters,
+   * so the handler adds nothing on the (many) events that have none.
+   *
+   * Field names are the conventional analytics names the domain model also uses
+   * (`utmSource`, `marketingNetwork`, ...) — not domain-model coupling, just the
+   * shared vocabulary of web attribution.
+   */
+
+  // UTM query parameter -> conventional camelCase field name.
+  const UTM_FIELDS = [
+      ['utm_source', 'utmSource'],
+      ['utm_medium', 'utmMedium'],
+      ['utm_campaign', 'utmCampaign'],
+      ['utm_term', 'utmTerm'],
+      ['utm_content', 'utmContent'],
+  ];
+
+  // Known ad-network click identifiers, in resolution priority, mapped to their network.
+  const CLICK_ID_NETWORKS = [
+      ['gclid', 'google'],
+      ['wbraid', 'google'],
+      ['gbraid', 'google'],
+      ['dclid', 'google'],
+      ['msclkid', 'microsoft'],
+      ['fbclid', 'meta'],
+      ['igshid', 'meta'],
+      ['ttclid', 'tiktok'],
+      ['li_fat_id', 'linkedin'],
+      ['twclid', 'twitter'],
+      ['yclid', 'yandex'],
+      ['epik', 'pinterest'],
+      ['scid', 'snapchat'],
+  ];
+
+  const marketingHandler = {
+      name: 'marketing',
+      about: ['session', 'webpage'],
+      collect() {
+          if (typeof window === 'undefined' || !window.location) {
+              return null;
+          }
+          const params = new URLSearchParams(window.location.search || '');
+          const data = {};
+
+          UTM_FIELDS.forEach(([param, field]) => {
+              const value = params.get(param);
+              if (value) {
+                  data[field] = value;
+              }
+          });
+
+          for (const [param, network] of CLICK_ID_NETWORKS) {
+              const value = params.get(param);
+              if (value) {
+                  data.marketingNetwork = network;
+                  data.marketingNetworkClickId = value;
+                  break;
+              }
+          }
+
+          return Object.keys(data).length > 0 ? data : null;
+      },
+  };
+
+  /**
+   * UA Client Hints handler. Surfaces the low-entropy values from
+   * `navigator.userAgentData` (Chromium) — `mobile`, `platform`, `brands` — a more
+   * reliable device/browser signal than parsing the user-agent string server-side.
+   *
+   * Declares `about: ['visitor', 'session']`. Returns `null` where UA-CH is
+   * unavailable (Firefox/Safari) — the server then falls back to the user-agent
+   * string carried by `browserContext`. Only the synchronous low-entropy values are
+   * read; the async `getHighEntropyValues()` is intentionally not awaited.
+   */
+  const userAgentDataHandler = {
+      name: 'userAgentData',
+      about: ['session', 'webpage'],
+      collect() {
+          if (typeof navigator === 'undefined' || !navigator.userAgentData) {
+              return null;
+          }
+          const uaData = navigator.userAgentData;
+          const data = {
+              mobile: Boolean(uaData.mobile),
+          };
+          if (uaData.platform) {
+              data.platform = uaData.platform;
+          }
+          if (Array.isArray(uaData.brands) && uaData.brands.length > 0) {
+              data.brands = uaData.brands.map((b) => ({ brand: b.brand, version: b.version }));
+          }
+          return data;
+      },
+  };
+
+  /**
+   * Consent handler. Surfaces the synchronously-available consent signals: the IAB
+   * TCF consent string (from the `euconsent-v2` cookie), the detected CMP provider,
+   * and the Global Privacy Control signal. The model-aware consumer (the server)
+   * decodes the TCF string into granted categories.
+   *
+   * Declares `about: ['consent', 'session']`. Returns `null` when no consent signal
+   * is present. NOTE: only synchronous sources are read — the async `__tcfapi`
+   * in-memory state is intentionally not awaited; the persisted cookie is the
+   * source of truth.
+   */
+
+  // Known CMP globals -> provider name.
+  const CMP_PROVIDERS = [
+      ['Cookiebot', 'cookiebot'],
+      ['OneTrust', 'onetrust'],
+      ['Optanon', 'onetrust'],
+      ['Didomi', 'didomi'],
+      ['UC_UI', 'usercentrics'],
+  ];
+
+  function readCookie(name) {
+      if (typeof document === 'undefined' || typeof document.cookie !== 'string') {
+          return undefined;
+      }
+      const match = document.cookie.match(new RegExp('(?:^|; )' + name + '=([^;]*)'));
+      return match ? decodeURIComponent(match[1]) : undefined;
+  }
+
+  function detectProvider() {
+      if (typeof window === 'undefined') {
+          return undefined;
+      }
+      for (const [global, name] of CMP_PROVIDERS) {
+          if (window[global]) {
+              return name;
+          }
+      }
+      if (typeof window.__tcfapi === 'function') {
+          return 'iab-tcf';
+      }
+      return undefined;
+  }
+
+  const consentHandler = {
+      name: 'consent',
+      about: ['consent', 'session', 'visitor'],
+      collect() {
+          if (typeof window === 'undefined') {
+              return null;
+          }
+          const data = {};
+
+          const tcfConsentString = readCookie('euconsent-v2');
+          if (tcfConsentString) {
+              data.tcfConsentString = tcfConsentString;
+          }
+
+          const provider = detectProvider();
+          if (provider) {
+              data.consentProvider = provider;
+          }
+
+          if (typeof navigator !== 'undefined' && typeof navigator.globalPrivacyControl === 'boolean') {
+              data.globalPrivacyControl = navigator.globalPrivacyControl;
+          }
+
+          return Object.keys(data).length > 0 ? data : null;
+      },
+  };
+
+  /**
+   * The default enrichment handlers registered on every web tracker. Each handler is
+   * model-agnostic: it self-identifies (`name`), declares what it is `about` (subject
+   * strings) and `collect`s its data; a model-aware consumer maps it onto entity state.
+   */
+  const defaultWebHandlers = [
+      browserContextHandler,
+      marketingHandler,
+      userAgentDataHandler,
+      consentHandler,
+  ];
+
+  /**
+   * Web-specific tracker: the base tracker plus the default web enrichment handlers
+   * (browser context, marketing/attribution, UA client hints, consent), so every web
+   * event carries the client environment and attribution signals in
+   * `meta.enrichments` — never in the domain-validated `context`.
    */
   class CollecionesWebTracker extends CollecionesTracker {
       /**
-       * Creates a new instance of CollecionesWebTracker.
-       * @param {Array} emitters - A list of emitter instances used to send the event.
-       * @param {string} trackerName - The name of the tracker.
-       * @param {string} appName - The name of the application generating events.
+       * @param {Array} emitters - Emitter instances used to send events.
+       * @param {string} trackerName - The tracker name.
+       * @param {string} appName - The application generating events.
        */
       constructor(emitters, trackerName, appName) {
           super(emitters, trackerName, appName);
-      }
-
-      /**
-       * Tracks an event, enriching it with browser context information.
-       * @param {CollecionesEvent} collecionesEvent - The event object to track.
-       * @throws {Error} If the event is not an instance of CollecionesEvent.
-       */
-      track(collecionesEvent) {
-          if (!(collecionesEvent instanceof CollecionesEvent)) {
-              throw new Error('Event must be of type CollecionesEvent');
-          }
-          collecionesEvent.setContext('browserContext', getBrowserContext());
-          super.track(collecionesEvent);        
+          defaultWebHandlers.forEach((handler) => this.use(handler));
       }
   }