@compilacion/colleciones-clientos 2.0.29 → 2.0.32

package/dist/index.cjs

@@ -17,30 +17,6 @@ const toBase64 = function (str) {
     }
 };
 
-/**
- * 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, ' ')
@@ -258,6 +234,27 @@ class CollecionesEvent {
         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.
@@ -625,6 +622,44 @@ class CollecionesTracker {
         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.
+            }
+        });
     }
 
     /**
@@ -637,7 +672,8 @@ class CollecionesTracker {
             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);
         });
@@ -659,31 +695,236 @@ class CollecionesTracker {
 }
 
 /**
- * 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', 'visitor'],
+    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', 'visitor'],
+    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: ['visitor', 'session'],
+    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'],
+    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));
     }
 }