@compilacion/colleciones-clientos 1.0.10 → 1.0.12

package/dist/collecionesClientos.iife.js

@@ -2,6 +2,12 @@
     'use strict';
 
     // helper 'private' functions
+    /**
+     * Converts a snake_case string to camelCase.
+     * Removes non-ASCII characters.
+     * @param {string} str
+     * @returns {string}
+     */
     const underscoreToCamelCase = function (str) {
         str = str.replace(/[^\x00-\x7F_]/g, '');
         return str
@@ -15,8 +21,14 @@
             .join('');
     };
 
+    /**
+     * Formats adjectives by converting them to camelCase strings.
+     * Accepts a single string or an array of strings.
+     * @param {string|string[]|undefined} adjectiveParameter
+     * @returns {string[]|undefined}
+     */
     const formatAdjectives = function (adjectiveParameter) {
-        let errorMsg = new Error('Adjective must be a string, an array of strings, or undefined');
+        const errorMsg = new Error('Adjective must be a string, an array of strings, or undefined');
         if (typeof adjectiveParameter === 'undefined') {
             return undefined;
         }
@@ -24,18 +36,17 @@
             return [underscoreToCamelCase(adjectiveParameter)];
         }
         if (Array.isArray(adjectiveParameter) && adjectiveParameter.every(item => typeof item === 'string')) {
-            let returnValue = [];
-            adjectiveParameter.forEach((adjectiveParameter) => {
-                if (!typeof item === 'string') {
-                    throw errorMsg;
-                }
-                returnValue.push(underscoreToCamelCase(adjectiveParameter));
-            });
-            return returnValue;
+            return adjectiveParameter.map(adjective => underscoreToCamelCase(adjective));
         }
         throw errorMsg;
     };
 
+    /**
+     * Converts an array of adjective strings to a dot-prefixed, dot-separated string.
+     * Removes duplicates and sorts alphabetically.
+     * @param {string[]} adjective
+     * @returns {string|undefined}
+     */
     const stringifyAdjectives = function (adjective) {
         if (!Array.isArray(adjective) || adjective.length === 0) {
             return undefined;
@@ -44,14 +55,25 @@
         return '.' + uniqueSorted.join('.');
     };
 
+    /**
+     * Encodes a string to Base64.
+     * Uses browser or Node.js method depending on environment.
+     * @param {string} str
+     * @returns {string}
+     */
     const toBase64 = function (str) {
-        if (typeof window !== 'undefined' && window.btoa) {
+        if (typeof window !== 'undefined' && typeof window.btoa === 'function') {
             return window.btoa(unescape(encodeURIComponent(str)));
         } else {
             return Buffer.from(str, 'utf-8').toString('base64');
         }
     };
 
+    /**
+     * 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 {};
@@ -71,8 +93,14 @@
         };
     };
 
+    /**
+     * Base class representing a structured event with timestamp, identifiers, and data fields.
+     */
     class CollecionesBaseEvent {
 
+        /**
+         * Constructs a new event with default metadata and timestamps.
+         */
         constructor() {
             this.eventName = '';
             this.data = {};
@@ -80,59 +108,74 @@
                 eventFormat: 'CollecionesBaseEvent',
                 eventFormatVersion: '1'
             };
-            const now = new Date();
             this.data.timestamps = {};
-            this.data.timestamps.clientDatetimeUtc = now.toISOString();
+            this.data.timestamps.clientDatetimeUtc = new Date().toISOString();
             if (typeof window !== 'undefined' && typeof navigator !== 'undefined' && navigator.language) {
-                this.data.timestamps.clientDatetimeLocal = new Date(now.getTime() - now.getTimezoneOffset() * 60000).toISOString();
+                this.data.timestamps.clientDatetimeLocal = new Date(Date.now() - new Date().getTimezoneOffset() * 60000).toISOString();
                 this.data.timestamps.timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+                this.data.timestamps.timeZoneOffset = new Date().getTimezoneOffset();
             } else {
-                this.data.timestamps.clientDatetimeLocal = now.toISOString();
+                this.data.timestamps.clientDatetimeLocal = new Date().toISOString();
                 this.data.timestamps.timeZone = 'UTC';
             }
         }
 
+        /**
+         * Sets the event name.
+         * @param {string} name
+         */
         setEventName(name) {
             this.eventName = name;
         }
 
+        /**
+         * Returns the event name.
+         * @returns {string}
+         */
         getEventName() {
             return this.eventName;
         }
 
+        /**
+         * Gets the format of the event.
+         * @returns {string}
+         */
         getEventFormat() {
             let v = this.data?.meta?.eventFormat;
             return (typeof v !== 'undefined') ? v : '1';
         }
 
+        /**
+         * Gets the version of the event format.
+         * @returns {string}
+         */
         getEventFormatVersion() {
             let v = this.data?.meta?.eventFormatVersion;
             return (typeof v !== 'undefined') ? v : 'CollecionesBaseEvent';
         }
 
-        getPostObject() {
-            const now = new Date();
-            if (typeof navigator !== 'undefined' && navigator.language) {
-                this.data.timestamps.sentDatetime = now.toLocaleString(navigator.language);
-            } else {
-                this.data.timestamps.sentDatetime = now.toISOString();
-            }
-            return {
-                eventname: this.getEventName(),
-                eventFormat: this.getEventFormat(),
-                eventFormatVersion: this.getEventFormatVersion(),
-                payload: toBase64(this.getPayload())
-            };
-        }
-
+        /**
+         * Replaces the entire data object.
+         * @param {object} data
+         */
         setData(data) {
             this.data = data;
         }
 
+        /**
+         * Adds a field to the event's custom fields section.
+         * @param {string} name
+         * @param {*} value
+         */
         addAttribute(name, value) {
             return this.addField(name, value);
         }
 
+        /**
+         * Adds a key-value pair to the custom fields.
+         * @param {string} name
+         * @param {*} value
+         */
         addField(name, value) {
             if (typeof this.data.fields !== 'object' || this.data.fields === null) {
                 this.data.fields = {};
@@ -140,14 +183,26 @@
             this.data.fields[name] = value;
         }
 
+        /**
+         * Sets the name of the tracker used to generate the event.
+         * @param {string} name
+         */
         setTracker(name) {
             this.data.tracker = name;
         }
 
+        /**
+         * Sets the name of the application that created the event.
+         * @param {string} name
+         */
         setAppName(name) {
             this.data.appName = name;
         }
 
+        /**
+         * Adds multiple identifiers from an object.
+         * @param {object} param
+         */
         convertParamIdentifiers(param) {
             if (typeof param === 'object' && param !== null && !Array.isArray(param)) {
                 for (const [key, value] of Object.entries(param)) {
@@ -156,6 +211,11 @@
             }
         }
 
+        /**
+         * Adds a single identifier to the event.
+         * @param {string} name
+         * @param {*} value
+         */
         addIdentifier(name, value) {
             if (typeof this.data.identifiers !== 'object' || this.data.identifiers === null) {
                 this.data.identifiers = {};
@@ -163,14 +223,52 @@
             this.data.identifiers[name] = value;
         }
 
+        /**
+         * Constructs the postable event object with metadata and encoded payload.
+         * @returns {object}
+         */
+        getPostObject() {
+            this.data.timestamps.sendDatetimeUtc = new Date().toISOString();
+            this.data.timestamps.sendDatetimeLocal = new Date(Date.now() - new Date().getTimezoneOffset() * 60000).toISOString();
+            return {
+                eventname: this.getEventName(),
+                eventFormat: this.getEventFormat(),
+                eventFormatVersion: this.getEventFormatVersion(),
+                payload: toBase64(this.getPayload())
+            };
+        }
+
+        /**
+         * Overrides or extends the timestamp fields of the event.
+         * @param {object} dateTimeObject
+         */
+        overrideDatetime(dateTimeObject = {}) {
+            for (const [key, value] of Object.entries(dateTimeObject)) {
+                this.data.timestamps[key] = value;
+            }
+        }
+
+        /**
+         * Serializes the event data to a JSON string.
+         * @returns {string}
+         */
         getPayload() {
             return JSON.stringify(this.data);
         }
 
     }
 
+    /**
+     * Emitter class responsible for batching and sending events to a configured endpoint.
+     */
     class CollecionesEmitter {
 
+        /**
+         * Initializes the emitter with buffering settings.
+         * @param {string} [endpoint='/collect'] - The URL to send events to.
+         * @param {number} [flushSize=10] - Number of events to buffer before flushing.
+         * @param {number|boolean} [flushInterval=false] - Time in ms to flush events periodically.
+         */
         constructor(endpoint = '/collect', flushSize = 10, flushInterval = false) {
             this.endpoint = endpoint;
             this.flushInterval = flushInterval;
@@ -179,6 +277,9 @@
             this.timer = null;
         }
 
+        /**
+         * Starts the flush timer if a valid interval is set.
+         */
         startTimer() {
             this.stopTimer();
             if (typeof this.flushInterval == 'number' && this.flushInterval > 0) {
@@ -186,12 +287,18 @@
             }
         }
 
+        /**
+         * Starts the flush timer only if not already running.
+         */
         startTimerIfStopped() {
             if (!this.timer) {
                 this.startTimer();
             }
         }
 
+        /**
+         * Stops the active flush timer.
+         */
         stopTimer() {
             if (this.timer) {
                 clearInterval(this.timer);
@@ -199,6 +306,10 @@
             this.timer = null;
         }
 
+        /**
+         * Adds an event to the buffer and flushes if threshold is reached.
+         * @param {CollecionesBaseEvent} event
+         */
         track(event) {
             if (!(event instanceof CollecionesBaseEvent)) {
                 throw new Error('Event must be an instance of CollecionesBaseEvent');
@@ -206,6 +317,11 @@
             this.trackAsync(event);
         }
 
+        /**
+         * Asynchronously adds an event and flushes if the buffer size is exceeded.
+         * @param {CollecionesBaseEvent} event
+         * @returns {Promise<void>}
+         */
         async trackAsync(event) {
             if (!(event instanceof CollecionesBaseEvent)) {
                 throw new Error('Event must be an instance of CollecionesBaseEvent');
@@ -215,6 +331,10 @@
             return (this.buffer.length >= this.flushSize) ? this.flush() : Promise.resolve();
         }
 
+        /**
+         * Sends the buffered events to the server and clears the buffer.
+         * @returns {Promise<boolean|undefined>}
+         */
         async flush() {
             if (this.buffer.length === 0) return;
             const eventsToSend = [...this.buffer];
@@ -243,8 +363,17 @@
         }
     }
 
+    /**
+     * Tracks events by enriching them with shared identifiers and routing through configured emitters.
+     */
     class CollecionesTracker {
-        
+
+        /**
+         * Constructs a new tracker instance.
+         * @param {Array} emitters - Array of emitter instances responsible for sending events.
+         * @param {string} trackerName - Name identifying this tracker.
+         * @param {string} appName - Name of the application generating events.
+         */
         constructor(emitters, trackerName, appName) {
             this.emitters = emitters;
             this.trackerName = trackerName;
@@ -252,10 +381,20 @@
             this.identifiers = {};
         }
 
+        /**
+         * Adds a global identifier to be included with every event.
+         * @param {string} name - Identifier key.
+         * @param {*} value - Identifier value.
+         */
         addIdentifier(name, value) {
             this.identifiers[name] = value;
         }
 
+        /**
+         * Sends an event to all emitters after enriching it with identifiers and metadata.
+         * @param {CollecionesBaseEvent} collecionesEvent - The event to be sent.
+         * @throws {Error} If the input is not an instance of CollecionesBaseEvent.
+         */
         track(collecionesEvent) {
             if (!(collecionesEvent instanceof CollecionesBaseEvent)) {
                 throw new Error('Event must be of type CollecionesEvent');
@@ -268,16 +407,29 @@
             this.emitters.forEach(element => {
                 element.track(collecionesEvent, this.trackerName, this.appName);
             });
-            
         }
     }
 
+    /**
+     * Web-specific tracker that enriches events with browser context before sending them.
+     * Extends the base CollecionesTracker.
+     */
     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.
+         */
         constructor(emitters, trackerName, appName) {
             super(emitters, trackerName, appName);
         }
 
+        /**
+         * Tracks an event, enriching it with browser context information.
+         * @param {CollecionesBaseEvent} collecionesEvent - The event object to track.
+         * @throws {Error} If the event is not an instance of CollecionesBaseEvent.
+         */
         track(collecionesEvent) {
             if (!(collecionesEvent instanceof CollecionesBaseEvent)) {
                 throw new Error('Event must be of type CollecionesEvent');
@@ -287,8 +439,18 @@
         }
     }
 
+    /**
+     * Represents a semantic event with a name, data payload, and identifiers.
+     * Extends CollecionesBaseEvent.
+     */
     class CollecionesEvent extends CollecionesBaseEvent {
 
+        /**
+         * Constructs a new CollecionesEvent instance.
+         * @param {string} name - The name of the event.
+         * @param {object} data - The main data payload of the event.
+         * @param {object} identifiers - A set of identifiers to associate with the event.
+         */
         constructor(name, data, identifiers) {
             super();
             this.setEventName(name);
@@ -354,8 +516,20 @@
         return unsafeStringify(rnds);
     }
 
+    /**
+     * Represents a structured semantic event with entity, action, and optional adjective.
+     * Includes automatic naming and identifier mapping.
+     * Extends CollecionesBaseEvent.
+     */
     class CollecionesSemanticEvent extends CollecionesBaseEvent {
 
+        /**
+         * Constructs a new semantic event.
+         * @param {string} entity - The entity involved in the event.
+         * @param {string} action - The action performed on the entity.
+         * @param {string|string[]|undefined} adjective - Optional adjective(s) modifying the event.
+         * @param {object} identifiers - Key-value pairs to be added as identifiers.
+         */
         constructor(entity, action, adjective, identifiers) {
             super();
             this.entity = underscoreToCamelCase(entity);
@@ -373,10 +547,20 @@
             };
         }
 
+        /**
+         * This method is deprecated in semantic events and will throw if called.
+         * @throws {Error}
+         */
         setData() {
             throw new Error('setData deprecated in semantic events');
         }
 
+        /**
+         * Adds a key-value pair as an identifier for the semantic entity.
+         * @param {string} key - The identifier name.
+         * @param {string|number} value - The identifier value.
+         * @throws Will throw if key is not a string or value is not a string or number.
+         */
         addEntityIdentifier(key, value) {
             if (typeof key !== 'string') {
                 throw new Error('Entity identifier key must be a string');
@@ -389,10 +573,22 @@
 
     }
 
+    /**
+     * Represents a semantic event related to a collection of entities.
+     * Extends CollecionesSemanticEvent and adds item-level detail and identifiers.
+     */
     class CollecionesSemanticCollectionEvent extends CollecionesSemanticEvent {
 
+        /**
+         * Constructs a new CollecionesSemanticCollectionEvent.
+         * @param {string} itemEntity - The name of the item entity being acted on.
+         * @param {string} action - The action performed.
+         * @param {string|string[]|undefined} adjective - Optional adjective(s) describing the action.
+         * @param {object} identifiers - Identifiers associated with the event.
+         * @param {string} [collectionEntity] - Optional collection name, defaults to `${itemEntity}Collection`.
+         */
         constructor(itemEntity, action, adjective, identifiers, collectionEntity) {
-            if(typeof collectionEntity == 'undefined') {
+            if (typeof collectionEntity == 'undefined') {
                 collectionEntity = `${itemEntity}Collection`;
             }
             super(collectionEntity, action, undefined, identifiers);
@@ -408,6 +604,12 @@
             this.data.entityItemIdentifiers = {};
         }
 
+        /**
+         * Adds an identifier value (or values) for a specific entity item key.
+         * @param {string} key - The identifier name.
+         * @param {string|number|Array<string|number>} value - The identifier value(s).
+         * @throws Will throw if key is not a string or value is of invalid type.
+         */
         addEntityItemIdentifier(key, value) {
             if (typeof key !== 'string') {
                 throw new Error('Entity identifier key must be a string');
@@ -415,11 +617,11 @@
             if (typeof value !== 'string' && typeof value !== 'number' && !Array.isArray(value)) {
                 throw new Error('Entity identifier value must be a string or number');
             }
-            if(typeof this.data.entityItemIdentifiers[key] == 'undefined') {
+            if (typeof this.data.entityItemIdentifiers[key] == 'undefined') {
                 this.data.entityItemIdentifiers[key] = [];
             }
-            if(Array.isArray(value)) {
-                value.forEach((v)=> {
+            if (Array.isArray(value)) {
+                value.forEach((v) => {
                     this.data.entityItemIdentifiers[key].push(v);
                 });
             } else {
@@ -427,7 +629,6 @@
             }
         }
 
-        
     }
 
     (function(global) {