@compilacion/colleciones-clientos 2.0.5 → 2.0.7

package/dist/collecionesClientos.iife.js

@@ -1,924 +1,962 @@
 (function () {
-    'use strict';
-
-    // helper 'private' functions
-
-
-    /**
-     * 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' && 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 {};
-        }
-        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,
-        };
-    };
-
-    /**
-     * CollecionesEvent
-     * -----------------
-     * Base class representing a semantically structured event object.
-     * Each event models a specific interaction with an entity, optionally performed by an actor,
-     * and may reference related entities or include contextual metadata.
-     *
-     * Key features:
-     * - Captures structured semantics: entity, action, actor, context, references
-     * - Supports multiple identifiers for both the main entity and the actor
-     * - Allows origin tagging for cross-context or cross-application references
-     * - Supports referencing collections of entities or grouped data
-     * - Includes timestamps and tracker/app metadata for auditability
-     * - Fully serializable and deserializable via toJSON/fromJSON
-     */
-    class CollecionesEvent {
-
-        /**
-         * Constructs a new CollecionesEvent with default structure and timestamps.
-         * Initializes empty containers for semantic attributes such as:
-         * - entity: the subject of the event
-         * - adjectives: descriptors of the entity
-         * - identifiers: identifiers of the entity
-         * - action: what happened to the entity
-         * - actor: who or what triggered the event (with identifiers in actorIdentifiers)
-         * - context: environmental data related to the event
-         * - references: external entities involved, optionally scoped by origin
-         * - collections: groups of related entities
-         * - meta: tracking metadata and timestamps
-         */
-        constructor() {
-            // initialize event properties
-            this.entity = '';
-            this.adjevtives = [];
-            this.identifiers = {};
-            this.action = '';
-            this.actor = {};
-            this.actorIdentifiers = {};
-            this.context = {};
-            this.references = {};
-            this.collections = {};
-            // set default values
-            this.meta = {
-                eventFormat: 'CollecionesEvent',
-                eventFormatVersion: '1'
-            };
-            this.meta.tracker = '';
-            this.meta.app = '';
-            this.meta.timestamps = {};
-            this.meta.timestamps.clientDatetimeUtc = new Date().toISOString();
-            if (typeof window !== 'undefined' && typeof navigator !== 'undefined' && navigator.language) {
-                this.meta.timestamps.clientDatetimeLocal = new Date(Date.now() - new Date().getTimezoneOffset() * 60000).toISOString();
-                this.meta.timestamps.timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-                this.meta.timestamps.timeZoneOffset = new Date().getTimezoneOffset();
-            } else {
-                this.meta.timestamps.clientDatetimeLocal = new Date().toISOString();
-                this.meta.timestamps.timeZone = 'UTC';
-            }
-        }
-
-        /**
-         * Returns the declared event format.
-         * @returns {string} The format name (e.g. 'CollecionesEvent').
-         */
-        getEventFormat() {
-            let v = this.meta?.eventFormat;
-            return (typeof v !== 'undefined') ? v : '1';
-        }
-
-        /**
-         * Returns the version of the event format.
-         * @returns {string} The format version string.
-         */
-        getEventFormatVersion() {
-            let v = this?.meta?.eventFormatVersion;
-            return (typeof v !== 'undefined') ? v : 'CollecionesEvent';
-        }
-
-        /**
-         * Overrides or supplements the event's timestamp fields with custom values.
-         * @param {object} dateTimeObject - Key-value pairs to merge into the existing timestamp object.
-         */
-        overrideDatetime(dateTimeObject = {}) {
-            for (const [key, value] of Object.entries(dateTimeObject)) {
-                this.meta.timestamps[key] = value;
-            }
-        }
-
-        /**
-         * Sets the name of the tracker responsible for generating this event.
-         * @param {string} name - Tracker name.
-         */
-        setTracker(name) {
-            this.meta.tracker = name;
-        }
-
-        /**
-         * Sets the name of the application that generated the event.
-         * @param {string} name - Application name.
-         */
-        setAppName(name) {
-            this.meta.appName = name;
-        }
-
-        /**
-         * Sets the expected schema name for this event.
-         * @param {string} schema - The name of the schema.
-         */
-        setSchema(schema) {
-            if (typeof schema !== 'string') {
-                throw new Error('Schema must be a string');
-            }
-            this.meta.schema = schema;
-        }
-
-        /**
-         * Sets the entity (subject) of the event.
-         * @param {string} entity - The entity name.
-         */
-        setEntity = function(entity) {
-            this.entity = entity;
-        }
-        
-        /**
-         * Defines the main action of the event (e.g., 'clicked').
-         * @param {string} action - The action string.
-         */
-        setAction = function(action) {
-            this.action = action;
-        }
-
-        /**
-         * Adds an adjective that describes the entity in more detail.
-         * @param {string} adjective - An adjective string.
-         */
-        addAdjective = function(adjective) {
-            if (typeof adjective !== 'string') {
-                throw new Error('Adjective must be a string');
-            }
-            this.adjevtives.push(adjective);
-        }
-
-        /**
-         * Adds or updates an identifier for the primary entity.
-         * Identifiers allow multiple keys to uniquely identify the entity.
-         * @param {string} name - The identifier key.
-         * @param {*} identifier - The identifier value.
-         */
-        setIdentifier = function(name, identifier) {
-            if (typeof name !== 'string') {
-                throw new Error('Identifier name must be a string');
-            }
-            this.identifiers[name] = identifier;
-        }
-
-        /**
-         * Defines the name of the actor (who or what performed the action).
-         * @param {string} name - Actor name (e.g., 'user', 'system').
-         */
-        setActor = function(name) {
-            if (typeof name !== 'string') {
-                throw new Error('Actor name must be a string');
-            }
-            this.actor.name = name;
-        }
-
-        /**
-         * Adds or updates an identifier for the actor.
-         * Supports multiple identifiers to uniquely identify the actor.
-         * @param {string} name - Identifier key.
-         * @param {*} identifier - Identifier value.
-         */
-        setActorIdentifier = function(name, identifier) {
-            if (typeof name !== 'string') {
-                throw new Error('Actor Identifier name must be a string');
-            }
-            this.actorIdentifiers[name] = identifier;
-        }
-
-        /**
-         * Adds contextual information to the event.
-         * Context can include any additional environmental or situational data.
-         * @param {string} context - The key of the context field.
-         * @param {*} value - The value of the context field.
-         */
-        setContext = function(context, value) {
-            if (typeof context !== 'string') {
-                throw new Error('Context must be a string');
-            }
-            this.context[context] = value;
-        }
-
-        /**
-         * Alias for `setReference` for compatibility.
-         * Declares an external entity referenced by this event.
-         * @param {string} entity - The referenced entity name.
-         * @param {string|null} origin - The origin application or context (optional).
-         */
-        setRefence = function(entity, origin=null) {
-            return this.setReference(entity, origin);
-        }
-
-        /**
-         * Declares an entity referenced by this event.
-         * References may include multiple identifiers and an optional origin to scope the reference.
-         * @param {string} entity - The referenced entity name.
-         * @param {string|null} origin - The origin application or context (optional).
-         */
-        setReference = function(entity, origin=null) {
-            if (typeof entity !== 'string') {
-                throw new Error('Referenced entity must be a string');
-            }
-            if(this.references[entity] === undefined) {
-                this.references[entity] = {
-                    identifiers: {},
-                    origin
-                };
-            }
-        }
-
-        /**
-         * Adds or updates an identifier for a referenced entity.
-         * Ensures the reference is declared and sets the identifier under that reference.
-         * @param {string} entity - The referenced entity name.
-         * @param {string} name - The identifier key.
-         * @param {*} identifier - The identifier value.
-         * @param {string|null} origin - Optional origin context.
-         */
-        setRefenceIdentifier = function(entity, name, identifier, origin=null) {
-            return this.setReferenceIdentifier(entity, name, identifier, origin);
-        }
-
-        /**
-         * Adds or updates an identifier for a referenced entity.
-         * @param {string} entity - The referenced entity name.
-         * @param {string} name - The identifier key.
-         * @param {*} identifier - The identifier value.
-         * @param {string|null} origin - Optional origin context.
-         */
-        setReferenceIdentifier = function(entity, name, identifier, origin=null) {
-            if (typeof entity !== 'string') {
-                throw new Error('Referenced entity name must be a string');
-            }
-            if (typeof name !== 'string') {
-                throw new Error('Actor Identifier name must be a string');
-            }
-            this.setRefence(entity, origin);
-            this.references[entity].identifiers[name] = identifier;
-        }
-
-        /**
-         * Declares a collection of related entities for this event.
-         * Collections group multiple related items and may include identifiers and origin metadata.
-         * @param {string} entity - The collection name.
-         * @param {string|null} origin - Optional origin identifier (e.g. system name).
-         */
-        setCollection = function(entity, origin=null) {
-            if(this.collections[entity] == undefined) {
-                this.collections[entity] = {
-                    items: [],
-                    identifiers: {},
-                    origin
-                };
-            }
-        }
-
-        /**
-         * Adds a new item to a collection and returns its index key.
-         * Items represent individual elements within the collection.
-         * @param {string} entity - The name of the collection.
-         * @returns {number} Index of the newly added item in the collection.
-         */
-        setCollectionItem = function(entity) {
-            this.setCollection(entity);
-            this.collections[entity].items.push({});
-            let itemKey = this.collections[entity].items.length - 1;
-            return itemKey;
-        }
-
-        /**
-         * Assigns a reference (identifier) to a specific item in a collection.
-         * Useful for tagging individual collection elements with identifiers.
-         * @param {string} entity - Collection name.
-         * @param {number} itemKey - The index of the item in the collection.
-         * @param {string} name - The identifier key.
-         * @param {*} identifier - The identifier value.
-         * @throws {Error} If the item does not exist at the given index.
-         */
-        setCollectionItemReference = function(entity, itemKey, name, identifier) {
-            this.setCollection(entity);
-            if(typeof this.collections[entity].items[itemKey] !== 'object') {
-                throw new Error('bad bad man, the collection key does not exists');
-            }
-            this.collections[entity].items[itemKey][name] = identifier;
-        }
-        
-        /**
-         * Sets a static identifier that applies to the entire collection.
-         * These identifiers describe the collection as a whole.
-         * @param {string} entity - Collection name.
-         * @param {string} name - Identifier key.
-         * @param {*} identifier - Identifier value.
-         */
-        setCollectionIdentifier = function(entity, name, identifier) {
-            if(this.collections[entity] == undefined) {
-                this.collections[entity] = {};
-            }
-            this.collections[entity].identifiers[name] = identifier;
-        }
-
-        /**
-         * Serializes the event instance to a plain object suitable for transport or storage.
-         * The output includes all semantic fields and metadata.
-         * @returns {object} A plain JavaScript object representing the event.
-         */
-        toJSON() {
-            return {
-                class: 'CollecionesEvent',
-                entity: this.entity,
-                adjectives: this.adjevtives,
-                identifiers: this.identifiers,
-                action: this.action,
-                actor: this.actor,
-                actorIdentifiers: this.actorIdentifiers,
-                actorIds: this.actorIds,
-                context: this.context,
-                references: this.references,
-                meta: this.meta,
-                collections: this.collections
-            };
-        }
-
-        /**
-         * Recreates a CollecionesEvent instance from a plain object.
-         * Used when deserializing events from storage or network transport.
-         * @param {object} obj - The input object containing event data.
-         * @returns {CollecionesEvent} A rehydrated event instance.
-         * @throws {Error} If the class type is not 'CollecionesEvent'.
-         */
-        static fromJSON(obj) { 
-            if (!obj || obj.class !== 'CollecionesEvent') {
-                throw new Error('Invalid or missing event class type'); 
-            }        
-            const instance = new CollecionesEvent();
-            instance.entity = obj.entity;
-            instance.adjevtives = obj.adjectives || [];
-            instance.identifiers = obj.identifiers || {};
-            instance.action = obj.action;
-            instance.actor = obj.actor;
-            instance.actorIdentifiers = obj.actorIdentifiers;
-            instance.actorIds = obj.actorIds;
-            instance.context = obj.context || {};
-            instance.references = obj.references || {};
-            instance.meta = obj.meta || {};
-            instance.collections = obj.collections || {};
-            return instance;
-        }
-        
-    }
-
-    /**
-     * CollecionesEmitter
-     * -------------------
-     * This class collects and sends event objects to a remote endpoint (e.g., an event collector API).
-     * It is used in both client- and server-side tracking scenarios, typically in combination with
-     * CollecionesEvent or subclasses like CollecionesBaseEvent.
-     *
-     * Behavior:
-     * - Events are buffered via `.track()` or `.trackAsync()`.
-     * - If the number of buffered events reaches `flushSize`, the buffer is automatically flushed.
-     * - If `flushInterval` is provided, the buffer is flushed at a fixed interval.
-     * - Flushing serializes each event using `.toJSON()`, encodes it with base64, and posts
-     *   the resulting array to the configured endpoint.
-     *
-     * Example usage:
-     *   const emitter = new CollecionesEmitter('/track', 5, 10000);
-     *   emitter.track(new CollecionesEvent());
-     *
-     * Note:
-     * This class is stateful. To stop periodic flushing, call `.stopTimer()` when the emitter is no longer in use.
-     */
-    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;
-            this.flushSize = flushSize;
-            this.buffer = [];
-            this.timer = null;
-            this.lastPayload = null;
-        }
-
-        /**
-         * Starts the flush timer if a valid interval is set.
-         * @returns {void}
-         */
-        startTimer() {
-            this.stopTimer();
-            if (typeof this.flushInterval == 'number' && this.flushInterval > 0) {
-                this.timer = setInterval(() => this.flush(), this.flushInterval);
-            }
-        }
-
-        /**
-         * Starts the flush timer only if not already running.
-         * @returns {void}
-         */
-        startTimerIfStopped() {
-            if (!this.timer) {
-                this.startTimer();
-            }
-        }
-
-        /**
-         * Stops the active flush timer.
-         * @returns {void}
-         */
-        stopTimer() {
-            if (this.timer) {
-                clearInterval(this.timer);
-            }
-            this.timer = null;
-        }
-
-        /**
-         * Adds an event to the buffer and flushes if threshold is reached.
-         * Validates that the event is an instance of CollecionesEvent to ensure correct event type.
-         * @param {CollecionesEvent} event - Event instance to be tracked.
-         * @throws {Error} Throws if event is not a CollecionesEvent instance.
-         * @returns {void}
-         */
-        track(event) {
-            if (!(event instanceof CollecionesEvent)) {
-                throw new Error('Event must be an instance of CollecionesEvent');
-            }
-            this.trackAsync(event);
-        }
-
-        /**
-         * Asynchronously adds an event and flushes if the buffer size is exceeded.
-         * Validates that the event is an instance of CollecionesEvent to ensure correct event type.
-         * @param {CollecionesEvent} event - Event instance to be tracked asynchronously.
-         * @throws {Error} Throws if event is not a CollecionesEvent instance.
-         * @returns {Promise<void>} Resolves when event is added and flush triggered if needed.
-         */
-        async trackAsync(event) {
-            if (!(event instanceof CollecionesEvent)) {
-                throw new Error('Event must be an instance of CollecionesEvent');
-            }
-            this.startTimerIfStopped();
-            this.buffer.push(event);
-            return (this.buffer.length >= this.flushSize) ? this.flush() : Promise.resolve();
-        }
-
-        /**
-         * Sends all buffered events in a single POST request to the server.
-         * Each event is serialized via `.toJSON()` and encoded as a base64 string.
-         * Response status is checked for HTTP success; errors are logged but not thrown.
-         *
-         * @returns {Promise<boolean|undefined>} Resolves true if flush was triggered, or undefined if buffer was empty.
-         */
-        async flush() {
-            if (this.buffer.length === 0) return;
-            this.stopTimer();
-            const body = this.buildBody();
-            this.lastPayload = body;
-            this.buffer = [];
-            try {
-                const response = await fetch(this.endpoint, {
-                    method: 'POST',
-                    credentials: 'include',
-                    headers: {
-                        'Content-Type': 'application/json'
-                    },
-                    body
-                });
-                if (!response.ok) {
-                    console.log(`Failed to send events: ${response.statusText}`);
-                }
-                return true;
-            } catch (error) {     
-                console.log(`Network error sending events: ${error.message}`);
-            }   
-        }
-
-        /**
-         * Builds a POST-ready payload from the current buffer, without clearing it.
-         * @returns {string} JSON string of base64-encoded serialized events.
-         */
-        buildBody() {
-            return JSON.stringify(this.buffer.map(e => toBase64(JSON.stringify(e.toJSON()))));
-        }
-
-    }
-
-    /**
-     * 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;
-            this.appName = appName;
-        }
-
-        /**
-         * Sends an event to all emitters after enriching it with identifiers and metadata.
-         * @param {CollecionesEvent} collecionesEvent - The event to be sent.
-         * @throws {Error} If the input is not an instance of CollecionesEvent.
-         */
-        track(collecionesEvent) {
-            if (!(collecionesEvent instanceof CollecionesEvent)) {
-                throw new Error('Event must be of type CollecionesEvent');
-            }
-            collecionesEvent.setTracker(this.trackerName);
-            collecionesEvent.setAppName(this.appName); 
-            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 {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);        
-        }
-    }
-
-    /**
-     * Colleciones DSL
-     * ---------------
-     * This module provides a fluent, human-readable DSL (domain-specific language) for constructing
-     * structured tracking events based on CollecionesBaseEvent. Each step in the chain represents
-     * a semantically meaningful piece of the event: the entity, the action, the actor, references, etc.
-     *
-     * Entry Point:
-     *   collecionesDsl.the('dark')
-     *
-     * Chaining:
-     *   - .and('...')                    : add additional adjectives
-     *   - ._('entity')                  : specify the entity being acted on
-     *   - .identified.by('field')      : declare primary identifier for the subject
-     *   - .has.been('action')          : declare what happened
-     *   - .by('actor')                 : describe the actor performing the action
-     *   - .identified.by('id')        : add identifiers for the actor
-     *   - .with('key').set.to('val')  : add contextual data fields
-     *   - .referring.to('entity')     : describe referenced/related entities
-     *   - .identified.by('refId')     : add identifiers for the reference
-     *   - .conform.to('SchemaName')   : attach schema metadata
-     *   - .then.track.with(emitter)   : finalize and emit the event
-     *
-     * Each function in the chain passes forward a scoped version of the CollecionesBaseEvent instance,
-     * and enforces semantic constraints (e.g. `.as()` is required after `.by()`).
-     *
-     * Internal:
-     *   - Uses setRefence / setRefenceIdentifier for references
-     *   - Uses helpers.getEvent() for test access
-     *   - Uses instanceof CollecionesEmitter for validation
-     *
-     * This file is designed for internal use by developers building with the Colleciones tracking model.
-     */
-
-
-    let init = (entity) => {
-        return ((entity)=>{
-            let eventInstance = new CollecionesEvent(); // Core event object
-            eventInstance.setEntity(entity);
-
-            let helpers = {
-                getEvent: () => {
-                    return eventInstance;
-                },
-            };
-
-            // DSL function groups
-            let andEntity = () => {}; // .and(...) chaining after the()
-            let setEntityAfterAnd = () => {}; // ._('entity') after .and
-            let setEntityIdentifiers = () => {}; // .identified.by(...) for main subject
-            let setAction = () => {}; // .has.been(...) for action
-            let setActor = () => {}; // .by('actor')
-            let setActorIdentifier = () => {}; // .identified.by(...) inside .by(...)
-            let addContext = () => {}; // .with(...).set.to(...)
-            let addReference = () => {}; // .referring.to(...)
-            let getAddReference = () => {}; // .identified.by().as() inside .referring
-            let conformingTo = () => {}; // .conform.to('SchemaName')
-            let track = () => {}; // .then.track.with(emitter)
-            let addCollection = () => {};
-
-            // Adjective chaining: .and(...)._('entity')
-            setEntityAfterAnd = (entity) => {
-                eventInstance.addAdjective(eventInstance.entity);
-                eventInstance.setEntity(entity);
-                return {
-                    as: () => {
-                        return { helpers }
-                    },
-                    identified: {
-                        by: setEntityIdentifiers
-                    },
-                    has: { been: setAction },
-                    helpers
-                };
-            };
-
-            // Identifier setup: .identified.by().as()
-            setEntityIdentifiers = (name) => {
-                eventInstance.setIdentifier(name, null);
-                return {
-                    as: (value) => {
-                        eventInstance.setIdentifier(name, value);
-                        return {
-                            helpers,
-                            and: {
-                                by: setEntityIdentifiers
-                            },
-                            has: { been: setAction },
-                        }
-                    },
-                    helpers
-                };
-            };
-
-            // Additional adjectives: .and('...')._()
-            andEntity = (entity) => {
-                eventInstance.addAdjective(eventInstance.entity);
-                eventInstance.setEntity(entity);
-                return {
-                    and: andEntity,
-                    _ : setEntityAfterAnd,
-                    helpers
-                }
-            };
-
-            // Action: .has.been('...')
-            setAction = (action) => {
-                eventInstance.setAction(action);
-                return {
-                    by: setActor,
-                    referring: { to: addReference },
-                    with: addContext,
-                    conform: {to: conformingTo},
-                    then: {track: {with: track}},
-                    including: {
-                        a: addCollection,
-                    },
-                    helpers
-                }
-            };
-
-            // Actor: .by('user')
-            setActor = (name) => {
-                eventInstance.setActor(name);
-                return { 
-                    identified: {
-                        by: setActorIdentifier
-                    },
-                    with: addContext,
-                    including: {
-                        a: addCollection,
-                    },
-                    helpers
-                }
-            };
-
-            // Actor identifier: .identified.by().as()
-            setActorIdentifier = (name) => {
-                return {
-                    as: (value) => {
-                        eventInstance.setActorIdentifier(name, value);
-                        return {
-                            helpers,
-                            and: setActorIdentifier,
-                            with: addContext,
-                            referring: { to: addReference },
-                            including: {
-                                a: addCollection,
-                            },
-                        }
-                    },
-                    helpers
-                }
-            };
-
-            // Contextual field: .with('key').set.to('value')
-            addContext = (context) => {
-                return {
-                    helpers,
-                    set: {
-                        to: (value) => {
-                            eventInstance.setContext(context, value);
-                            return {
-                                helpers,
-                                and: addContext,
-                                referring: { to: addReference },
-                                including: {
-                                    a: addCollection,
-                                },
-                            }
-                        }
-                    }
-                }
-            };
-
-            // Reference: .referring.to('...')
-            addReference = (entity) => {
-                eventInstance.setRefence(entity);
-                return {
-                    identified: {
-                        by: getAddReference(entity)
-                    },
-                    conform: {to: conformingTo},
-                    then: {track: {with: track}},
-                    including: {
-                        a: addCollection,
-                    },
-                    helpers
-                }
-            };
-
-            // Reference identifier setup: .identified.by().as()
-            getAddReference = (entity) => {
-                return (name) => {
-                    return {
-                        as: (value) => {
-                            eventInstance.setRefenceIdentifier(entity, name, value);
-                            return {
-                                helpers,
-                                and: {by: getAddReference(entity) },
-                                conform: {to: conformingTo},
-                                then: {track: {with: track}},
-                                including: {
-                                    a: addCollection,
-                                },
-                            }
-                        },
-                        helpers,
-                    };
-                };
-            };
-
-            // Schema declaration: .conform.to('...')
-            conformingTo = (name) => {
-                eventInstance.setSchema(name);
-                return { 
-                    then: {track: {with: track}},
-                    helpers
-                }
-            };
-
-            addCollection = (entity) => {
-                const collection = () => {
-                    eventInstance.setCollection(entity);
-                    
-                    const addItem = (referenceName) => {
-                        const itemKey = eventInstance.setCollectionItem(entity);
-                        const addIdentifier = (referenceNameNewIdentifier) => {
-                            referenceName = referenceNameNewIdentifier;
-                            return {
-                                as: addItemReferenceValue,
-                            }
-                        };
-                        const addItemReferenceValue = (value) => {
-                            eventInstance.setCollectionItemReference(entity, itemKey, referenceName, value);
-                            return {
-                                and: {
-                                    helpers, 
-                                    by: addIdentifier,
-                                    item: { 
-                                        identified: { 
-                                            by: addItem
-                                        }
-                                    },
-                                    a: addCollection
-                                },
-                                conform: {
-                                    to: conformingTo,
-                                },  
-                                then: {track: {with: track}},
-                                helpers
-                            }
-                        };
-                        return {
-                            as: addItemReferenceValue
-                        }
-
-                    };
-
-                    return {
-                        helpers,
-                        with: {
-                            item: {
-                                identified: {
-                                    by: addItem
-                                }
-                            }
-                        },
-                        and: { a: addCollection }
-                    }
-                };
-                return {
-                    collection
-                }
-            };
-
-            // Final dispatch: .then.track.with(tracker)
-            track = (tracker) => {
-                if(!(tracker instanceof CollecionesTracker)){
-                    throw new Error('can only be a CollecionesTracker')
-                }
-                tracker.track(eventInstance);
-                return {
-                    and: track,
-                    helpers,
-                }
-            };
-
-            return {
-                and: andEntity,
-                _: setEntityAfterAnd,
-                identified: {
-                    by: setEntityIdentifiers
-                },
-                has: { been: setAction},
-                node: '_base',
-                helpers
-            }
-
-        })(entity);
-    };
-
-    let collecionesDsl = {
-        the: init
-    };
-
-    (function(global) {
-      global.CollecionesEmitter = CollecionesEmitter;
-      global.CollecionesTracker = CollecionesTracker;
-      global.CollecionesWebTracker = CollecionesWebTracker;
-      global.CollecionesEvent = CollecionesEvent;
-      global.collecionesDsl = collecionesDsl;
-    })(typeof window !== 'undefined' ? window : globalThis);
+  'use strict';
+
+  // helper 'private' functions
+
+
+  /**
+   * 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' && 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 {};
+      }
+      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, ' ')
+      .trim()
+      .split(/\s+/)
+      .map((word, index) => {
+        if (index === 0) return word;
+        return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+      })
+      .join('');
+  };
+
+  /**
+   * CollecionesEvent
+   * -----------------
+   * Base class representing a semantically structured event object.
+   * Each event models a specific interaction with an entity, optionally performed by an actor,
+   * and may reference related entities or include contextual metadata.
+   *
+   * Key features:
+   * - Captures structured semantics: entity, action, actor, context, references
+   * - Supports multiple identifiers for both the main entity and the actor
+   * - Allows origin tagging for cross-context or cross-application references
+   * - Supports referencing collections of entities or grouped data
+   * - Includes timestamps and tracker/app metadata for auditability
+   * - Fully serializable and deserializable via toJSON/fromJSON
+   */
+
+
+  class CollecionesEvent {
+
+      /**
+       * Constructs a new CollecionesEvent with default structure and timestamps.
+       * Initializes empty containers for semantic attributes such as:
+       * - entity: the subject of the event
+       * - adjectives: descriptors of the entity
+       * - identifiers: identifiers of the entity
+       * - action: what happened to the entity
+       * - actor: who or what triggered the event (with identifiers in actorIdentifiers)
+       * - context: environmental data related to the event
+       * - references: external entities involved, optionally scoped by origin
+       * - collections: groups of related entities
+       * - meta: tracking metadata and timestamps
+       */
+      constructor() {
+          // initialize event properties
+          this.entity = '';
+          this.adjevtives = [];
+          this.identifiers = {};
+          this.action = '';
+          this.actor = {};
+          this.actorIdentifiers = {};
+          this.context = {};
+          this.references = {};
+          this.collections = {};
+          // set default values
+          this.meta = {
+              eventFormat: 'CollecionesEvent',
+              eventFormatVersion: '1'
+          };
+          this.meta.tracker = '';
+          this.meta.app = '';
+          this.meta.timestamps = {};
+          this.meta.timestamps.clientDatetimeUtc = new Date().toISOString();
+          if (typeof window !== 'undefined' && typeof navigator !== 'undefined' && navigator.language) {
+              this.meta.timestamps.clientDatetimeLocal = new Date(Date.now() - new Date().getTimezoneOffset() * 60000).toISOString();
+              this.meta.timestamps.timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+              this.meta.timestamps.timeZoneOffset = new Date().getTimezoneOffset();
+          } else {
+              this.meta.timestamps.clientDatetimeLocal = new Date().toISOString();
+              this.meta.timestamps.timeZone = 'UTC';
+          }
+      }
+
+      /**
+       * Returns the declared event format.
+       * @returns {string} The format name (e.g. 'CollecionesEvent').
+       */
+      getEventFormat() {
+          let v = this.meta?.eventFormat;
+          return (typeof v !== 'undefined') ? v : '1';
+      }
+
+      /**
+       * Returns the version of the event format.
+       * @returns {string} The format version string.
+       */
+      getEventFormatVersion() {
+          let v = this?.meta?.eventFormatVersion;
+          return (typeof v !== 'undefined') ? v : 'CollecionesEvent';
+      }
+
+      /**
+       * Overrides or supplements the event's timestamp fields with custom values.
+       * @param {object} dateTimeObject - Key-value pairs to merge into the existing timestamp object.
+       */
+      overrideDatetime(dateTimeObject = {}) {
+          for (const [key, value] of Object.entries(dateTimeObject)) {
+              this.meta.timestamps[key] = value;
+          }
+      }
+
+      /**
+       * Sets the name of the tracker responsible for generating this event.
+       * @param {string} name - Tracker name.
+       */
+      setTracker(name) {
+          this.meta.tracker = name;
+      }
+
+      /**
+       * Sets the name of the application that generated the event.
+       * @param {string} name - Application name.
+       */
+      setAppName(name) {
+          this.meta.appName = name;
+      }
+
+      /**
+       * Sets the expected schema name for this event.
+       * @param {string} schema - The name of the schema.
+       */
+      setSchema(schema) {
+          if (typeof schema !== 'string') {
+              throw new Error('Schema must be a string');
+          }
+          this.meta.schema = schema;
+      }
+
+      /**
+       * Sets the entity (subject) of the event.
+       * @param {string} entity - The entity name.
+       */
+      setEntity = function(entity) {
+          this.entity = formatToCamelCase(entity);
+      }
+      
+      /**
+       * Defines the main action of the event (e.g., 'clicked').
+       * @param {string} action - The action string.
+       */
+      setAction = function(action) {
+          this.action = formatToCamelCase(action);
+      }
+
+      /**
+       * Adds an adjective that describes the entity in more detail.
+       * @param {string} adjective - An adjective string.
+       */
+      addAdjective = function(adjective) {
+          if (typeof adjective !== 'string') {
+              throw new Error('Adjective must be a string');
+          }
+          this.adjevtives.push(formatToCamelCase(adjective));
+      }
+
+      /**
+       * Adds or updates an identifier for the primary entity.
+       * Identifiers allow multiple keys to uniquely identify the entity.
+       * @param {string} name - The identifier key.
+       * @param {*} identifier - The identifier value.
+       */
+      setIdentifier = function(name, identifier) {
+          if (typeof name !== 'string') {
+              throw new Error('Identifier name must be a string');
+          }
+          this.identifiers[name] = identifier;
+      }
+
+      /**
+       * Defines the name of the actor (who or what performed the action).
+       * @param {string} name - Actor name (e.g., 'user', 'system').
+       */
+      setActor = function(name) {
+          if (typeof name !== 'string') {
+              throw new Error('Actor name must be a string');
+          }
+          this.actor.name = name;
+      }
+
+      /**
+       * Adds or updates an identifier for the actor.
+       * Supports multiple identifiers to uniquely identify the actor.
+       * @param {string} name - Identifier key.
+       * @param {*} identifier - Identifier value.
+       */
+      setActorIdentifier = function(name, identifier) {
+          if (typeof name !== 'string') {
+              throw new Error('Actor Identifier name must be a string');
+          }
+          this.actorIdentifiers[name] = identifier;
+      }
+
+      /**
+       * Adds contextual information to the event.
+       * Context can include any additional environmental or situational data.
+       * @param {string} context - The key of the context field.
+       * @param {*} value - The value of the context field.
+       */
+      setContext = function(context, value) {
+          if (typeof context !== 'string') {
+              throw new Error('Context must be a string');
+          }
+          this.context[context] = value;
+      }
+
+      /**
+       * Alias for `setReference` for compatibility.
+       * Declares an external entity referenced by this event.
+       * @param {string} entity - The referenced entity name.
+       * @param {string|null} origin - The origin application or context (optional).
+       */
+      setRefence = function(entity, origin=null) {
+          return this.setReference(entity, origin);
+      }
+
+      /**
+       * Declares an entity referenced by this event.
+       * References may include multiple identifiers and an optional origin to scope the reference.
+       * @param {string} entity - The referenced entity name.
+       * @param {string|null} origin - The origin application or context (optional).
+       */
+      setReference = function(entity, origin=null) {
+          if (typeof entity !== 'string') {
+              throw new Error('Referenced entity must be a string');
+          }
+          entity = formatToCamelCase(entity);
+          if (origin !== null) {
+              entity = `${origin}.${entity}`;
+          }
+          if(this.references[entity] === undefined) {
+              this.references[entity] = {
+                  identifiers: {},
+                  origin
+              };
+          }
+      }
+
+      /**
+       * Adds or updates an identifier for a referenced entity.
+       * Ensures the reference is declared and sets the identifier under that reference.
+       * @param {string} entity - The referenced entity name.
+       * @param {string} name - The identifier key.
+       * @param {*} identifier - The identifier value.
+       * @param {string|null} origin - Optional origin context.
+       */
+      setRefenceIdentifier = function(entity, name, identifier, origin=null) {
+          return this.setReferenceIdentifier(entity, name, identifier, origin);
+      }
+
+      /**
+       * Adds or updates an identifier for a referenced entity.
+       * @param {string} entity - The referenced entity name.
+       * @param {string} name - The identifier key.
+       * @param {*} identifier - The identifier value.
+       * @param {string|null} origin - Optional origin context.
+       */
+      setReferenceIdentifier = function(entity, name, identifier, origin=null) {
+          if (typeof entity !== 'string') {
+              throw new Error('Referenced entity name must be a string');
+          }
+          if (typeof name !== 'string') {
+              throw new Error('Actor Identifier name must be a string');
+          }
+          this.setRefence(entity, origin);
+          entity = formatToCamelCase(entity);
+          if (origin !== null) {
+              entity = `${origin}.${entity}`;
+          }
+          this.references[entity].identifiers[name] = identifier;
+      }
+
+      /**
+       * Declares a collection of related entities for this event.
+       * Collections group multiple related items and may include identifiers and origin metadata.
+       * @param {string} entity - The collection name.
+       * @param {string|null} origin - Optional origin identifier (e.g. system name).
+       */
+      setCollection = function(entity, origin=null) {
+          entity = formatToCamelCase(entity);
+          if (origin !== null) {
+              entity = `${origin}.${entity}`;
+          }
+          if(this.collections[entity] == undefined) {
+              this.collections[entity] = {
+                  items: [],
+                  identifiers: {},
+                  origin
+              };
+          }
+      }
+
+      /**
+       * Adds a new item to a collection and returns its index key.
+       * Items represent individual elements within the collection.
+       * @param {string} entity - The name of the collection.
+       * @returns {number} Index of the newly added item in the collection.
+       */
+      setCollectionItem = function(entity, origin=null) {
+          entity = formatToCamelCase(entity);
+          if (origin !== null) {
+              entity = `${origin}.${entity}`;
+          }
+          this.setCollection(entity);
+          this.collections[entity].items.push({});
+          let itemKey = this.collections[entity].items.length - 1;
+          return itemKey;
+      }
+
+      /**
+       * Assigns a reference (identifier) to a specific item in a collection.
+       * Useful for tagging individual collection elements with identifiers.
+       * @param {string} entity - Collection name.
+       * @param {number} itemKey - The index of the item in the collection.
+       * @param {string} name - The identifier key.
+       * @param {*} identifier - The identifier value.
+       * @throws {Error} If the item does not exist at the given index.
+       */
+      setCollectionItemReference = function(entity, itemKey, name, identifier, origin=null) {
+          entity = formatToCamelCase(entity);
+          if (origin !== null) {
+              entity = `${origin}.${entity}`;
+          }
+          this.setCollection(entity);
+          if(typeof this.collections[entity].items[itemKey] !== 'object') {
+              throw new Error('bad bad man, the collection key does not exists');
+          }
+          this.collections[entity].items[itemKey][name] = identifier;
+      }
+      
+      /**
+       * Sets a static identifier that applies to the entire collection.
+       * These identifiers describe the collection as a whole.
+       * @param {string} entity - Collection name.
+       * @param {string} name - Identifier key.
+       * @param {*} identifier - Identifier value.
+       */
+      setCollectionIdentifier = function(entity, name, identifier, origin=null) {
+          entity = formatToCamelCase(entity);
+          if (origin !== null) {
+              entity = `${origin}.${entity}`;
+          }
+          if(this.collections[entity] == undefined) {
+              this.collections[entity] = {};
+          }
+          this.collections[entity].identifiers[name] = identifier;
+      }
+
+      /**
+       * Serializes the event instance to a plain object suitable for transport or storage.
+       * The output includes all semantic fields and metadata.
+       * @returns {object} A plain JavaScript object representing the event.
+       */
+      toJSON() {
+          return {
+              class: 'CollecionesEvent',
+              entity: this.entity,
+              adjectives: this.adjevtives,
+              identifiers: this.identifiers,
+              action: this.action,
+              actor: this.actor,
+              actorIdentifiers: this.actorIdentifiers,
+              actorIds: this.actorIds,
+              context: this.context,
+              references: this.references,
+              meta: this.meta,
+              collections: this.collections
+          };
+      }
+
+      /**
+       * Recreates a CollecionesEvent instance from a plain object.
+       * Used when deserializing events from storage or network transport.
+       * @param {object} obj - The input object containing event data.
+       * @returns {CollecionesEvent} A rehydrated event instance.
+       * @throws {Error} If the class type is not 'CollecionesEvent'.
+       */
+      static fromJSON(obj) { 
+          if (!obj || obj.class !== 'CollecionesEvent') {
+              throw new Error('Invalid or missing event class type'); 
+          }        
+          const instance = new CollecionesEvent();
+          instance.entity = obj.entity;
+          instance.adjevtives = obj.adjectives || [];
+          instance.identifiers = obj.identifiers || {};
+          instance.action = obj.action;
+          instance.actor = obj.actor;
+          instance.actorIdentifiers = obj.actorIdentifiers;
+          instance.actorIds = obj.actorIds;
+          instance.context = obj.context || {};
+          instance.references = obj.references || {};
+          instance.meta = obj.meta || {};
+          instance.collections = obj.collections || {};
+          return instance;
+      }
+      
+  }
+
+  /**
+   * CollecionesEmitter
+   * -------------------
+   * This class collects and sends event objects to a remote endpoint (e.g., an event collector API).
+   * It is used in both client- and server-side tracking scenarios, typically in combination with
+   * CollecionesEvent or subclasses like CollecionesBaseEvent.
+   *
+   * Behavior:
+   * - Events are buffered via `.track()` or `.trackAsync()`.
+   * - If the number of buffered events reaches `flushSize`, the buffer is automatically flushed.
+   * - If `flushInterval` is provided, the buffer is flushed at a fixed interval.
+   * - Flushing serializes each event using `.toJSON()`, encodes it with base64, and posts
+   *   the resulting array to the configured endpoint.
+   *
+   * Example usage:
+   *   const emitter = new CollecionesEmitter('/track', 5, 10000);
+   *   emitter.track(new CollecionesEvent());
+   *
+   * Note:
+   * This class is stateful. To stop periodic flushing, call `.stopTimer()` when the emitter is no longer in use.
+   */
+  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;
+          this.flushSize = flushSize;
+          this.buffer = [];
+          this.timer = null;
+          this.lastPayload = null;
+      }
+
+      /**
+       * Starts the flush timer if a valid interval is set.
+       * @returns {void}
+       */
+      startTimer() {
+          this.stopTimer();
+          if (typeof this.flushInterval == 'number' && this.flushInterval > 0) {
+              this.timer = setInterval(() => this.flush(), this.flushInterval);
+          }
+      }
+
+      /**
+       * Starts the flush timer only if not already running.
+       * @returns {void}
+       */
+      startTimerIfStopped() {
+          if (!this.timer) {
+              this.startTimer();
+          }
+      }
+
+      /**
+       * Stops the active flush timer.
+       * @returns {void}
+       */
+      stopTimer() {
+          if (this.timer) {
+              clearInterval(this.timer);
+          }
+          this.timer = null;
+      }
+
+      /**
+       * Adds an event to the buffer and flushes if threshold is reached.
+       * Validates that the event is an instance of CollecionesEvent to ensure correct event type.
+       * @param {CollecionesEvent} event - Event instance to be tracked.
+       * @throws {Error} Throws if event is not a CollecionesEvent instance.
+       * @returns {void}
+       */
+      track(event) {
+          if (!(event instanceof CollecionesEvent)) {
+              throw new Error('Event must be an instance of CollecionesEvent');
+          }
+          this.trackAsync(event);
+      }
+
+      /**
+       * Asynchronously adds an event and flushes if the buffer size is exceeded.
+       * Validates that the event is an instance of CollecionesEvent to ensure correct event type.
+       * @param {CollecionesEvent} event - Event instance to be tracked asynchronously.
+       * @throws {Error} Throws if event is not a CollecionesEvent instance.
+       * @returns {Promise<void>} Resolves when event is added and flush triggered if needed.
+       */
+      async trackAsync(event) {
+          if (!(event instanceof CollecionesEvent)) {
+              throw new Error('Event must be an instance of CollecionesEvent');
+          }
+          this.startTimerIfStopped();
+          this.buffer.push(event);
+          return (this.buffer.length >= this.flushSize) ? this.flush() : Promise.resolve();
+      }
+
+      /**
+       * Sends all buffered events in a single POST request to the server.
+       * Each event is serialized via `.toJSON()` and encoded as a base64 string.
+       * Response status is checked for HTTP success; errors are logged but not thrown.
+       *
+       * @returns {Promise<boolean|undefined>} Resolves true if flush was triggered, or undefined if buffer was empty.
+       */
+      async flush() {
+          if (this.buffer.length === 0) return;
+          this.stopTimer();
+          const body = this.buildBody();
+          this.lastPayload = body;
+          this.buffer = [];
+          try {
+              const response = await fetch(this.endpoint, {
+                  method: 'POST',
+                  credentials: 'include',
+                  headers: {
+                      'Content-Type': 'application/json'
+                  },
+                  body
+              });
+              if (!response.ok) {
+                  console.log(`Failed to send events: ${response.statusText}`);
+              }
+              return true;
+          } catch (error) {     
+              console.log(`Network error sending events: ${error.message}`);
+          }   
+      }
+
+      /**
+       * Builds a POST-ready payload from the current buffer, without clearing it.
+       * @returns {string} JSON string of base64-encoded serialized events.
+       */
+      buildBody() {
+          return JSON.stringify(this.buffer.map(e => toBase64(JSON.stringify(e.toJSON()))));
+      }
+
+  }
+
+  /**
+   * 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;
+          this.appName = appName;
+      }
+
+      /**
+       * Sends an event to all emitters after enriching it with identifiers and metadata.
+       * @param {CollecionesEvent} collecionesEvent - The event to be sent.
+       * @throws {Error} If the input is not an instance of CollecionesEvent.
+       */
+      track(collecionesEvent) {
+          if (!(collecionesEvent instanceof CollecionesEvent)) {
+              throw new Error('Event must be of type CollecionesEvent');
+          }
+          collecionesEvent.setTracker(this.trackerName);
+          collecionesEvent.setAppName(this.appName); 
+          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 {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);        
+      }
+  }
+
+  /**
+   * Colleciones DSL
+   * ---------------
+   * This module provides a fluent, human-readable DSL (domain-specific language) for constructing
+   * structured tracking events based on CollecionesBaseEvent. Each step in the chain represents
+   * a semantically meaningful piece of the event: the entity, the action, the actor, references, etc.
+   *
+   * Entry Point:
+   *   collecionesDsl.the('dark')
+   *
+   * Chaining:
+   *   - .and('...')                    : add additional adjectives
+   *   - ._('entity')                  : specify the entity being acted on
+   *   - .identified.by('field')      : declare primary identifier for the subject
+   *   - .has.been('action')          : declare what happened
+   *   - .by('actor')                 : describe the actor performing the action
+   *   - .identified.by('id')        : add identifiers for the actor
+   *   - .with('key').set.to('val')  : add contextual data fields
+   *   - .referring.to('entity')     : describe referenced/related entities
+   *   - .identified.by('refId')     : add identifiers for the reference
+   *   - .conform.to('SchemaName')   : attach schema metadata
+   *   - .then.track.with(emitter)   : finalize and emit the event
+   *
+   * Each function in the chain passes forward a scoped version of the CollecionesBaseEvent instance,
+   * and enforces semantic constraints (e.g. `.as()` is required after `.by()`).
+   *
+   * Internal:
+   *   - Uses setRefence / setRefenceIdentifier for references
+   *   - Uses helpers.getEvent() for test access
+   *   - Uses instanceof CollecionesEmitter for validation
+   *
+   * This file is designed for internal use by developers building with the Colleciones tracking model.
+   */
+
+
+  let init = (entity) => {
+      return ((entity)=>{
+          let eventInstance = new CollecionesEvent(); // Core event object
+          eventInstance.setEntity(entity);
+
+          let helpers = {
+              getEvent: () => {
+                  return eventInstance;
+              },
+          };
+
+          // DSL function groups
+          let andEntity = () => {}; // .and(...) chaining after the()
+          let setEntityAfterAnd = () => {}; // ._('entity') after .and
+          let setEntityIdentifiers = () => {}; // .identified.by(...) for main subject
+          let setAction = () => {}; // .has.been(...) for action
+          let setActor = () => {}; // .by('actor')
+          let setActorIdentifier = () => {}; // .identified.by(...) inside .by(...)
+          let addContext = () => {}; // .with(...).set.to(...)
+          let addReference = () => {}; // .referring.to(...)
+          let getAddReference = () => {}; // .identified.by().as() inside .referring
+          let conformingTo = () => {}; // .conform.to('SchemaName')
+          let track = () => {}; // .then.track.with(emitter)
+          let addCollection = () => {};
+
+          // Adjective chaining: .and(...)._('entity')
+          setEntityAfterAnd = (entity) => {
+              eventInstance.addAdjective(eventInstance.entity);
+              eventInstance.setEntity(entity);
+              return {
+                  as: () => {
+                      return { helpers }
+                  },
+                  identified: {
+                      by: setEntityIdentifiers
+                  },
+                  has: { been: setAction },
+                  helpers
+              };
+          };
+
+          // Identifier setup: .identified.by().as()
+          setEntityIdentifiers = (name) => {
+              eventInstance.setIdentifier(name, null);
+              return {
+                  as: (value) => {
+                      eventInstance.setIdentifier(name, value);
+                      return {
+                          helpers,
+                          and: {
+                              by: setEntityIdentifiers
+                          },
+                          has: { been: setAction },
+                      }
+                  },
+                  helpers
+              };
+          };
+
+          // Additional adjectives: .and('...')._()
+          andEntity = (entity) => {
+              eventInstance.addAdjective(eventInstance.entity);
+              eventInstance.setEntity(entity);
+              return {
+                  and: andEntity,
+                  _ : setEntityAfterAnd,
+                  helpers
+              }
+          };
+
+          // Action: .has.been('...')
+          setAction = (action) => {
+              eventInstance.setAction(action);
+              return {
+                  by: setActor,
+                  referring: { to: addReference },
+                  with: addContext,
+                  conform: {to: conformingTo},
+                  then: {track: {with: track}},
+                  including: {
+                      a: addCollection,
+                  },
+                  helpers
+              }
+          };
+
+          // Actor: .by('user')
+          setActor = (name) => {
+              eventInstance.setActor(name);
+              return { 
+                  identified: {
+                      by: setActorIdentifier
+                  },
+                  with: addContext,
+                  including: {
+                      a: addCollection,
+                  },
+                  helpers
+              }
+          };
+
+          // Actor identifier: .identified.by().as()
+          setActorIdentifier = (name) => {
+              return {
+                  as: (value) => {
+                      eventInstance.setActorIdentifier(name, value);
+                      return {
+                          helpers,
+                          and: setActorIdentifier,
+                          with: addContext,
+                          referring: { to: addReference },
+                          including: {
+                              a: addCollection,
+                          },
+                      }
+                  },
+                  helpers
+              }
+          };
+
+          // Contextual field: .with('key').set.to('value')
+          addContext = (context) => {
+              return {
+                  helpers,
+                  set: {
+                      to: (value) => {
+                          eventInstance.setContext(context, value);
+                          return {
+                              helpers,
+                              and: addContext,
+                              referring: { to: addReference },
+                              including: {
+                                  a: addCollection,
+                              },
+                          }
+                      }
+                  }
+              }
+          };
+
+          // Reference: .referring.to('...')
+          addReference = (entity) => {
+              eventInstance.setRefence(entity);
+              return {
+                  identified: {
+                      by: getAddReference(entity)
+                  },
+                  conform: {to: conformingTo},
+                  then: {track: {with: track}},
+                  including: {
+                      a: addCollection,
+                  },
+                  helpers
+              }
+          };
+
+          // Reference identifier setup: .identified.by().as()
+          getAddReference = (entity) => {
+              return (name) => {
+                  return {
+                      as: (value) => {
+                          eventInstance.setRefenceIdentifier(entity, name, value);
+                          return {
+                              helpers,
+                              and: {by: getAddReference(entity) },
+                              conform: {to: conformingTo},
+                              then: {track: {with: track}},
+                              including: {
+                                  a: addCollection,
+                              },
+                          }
+                      },
+                      helpers,
+                  };
+              };
+          };
+
+          // Schema declaration: .conform.to('...')
+          conformingTo = (name) => {
+              eventInstance.setSchema(name);
+              return { 
+                  then: {track: {with: track}},
+                  helpers
+              }
+          };
+
+          addCollection = (entity) => {
+              const collection = () => {
+                  eventInstance.setCollection(entity);
+                  
+                  const addItem = (referenceName) => {
+                      const itemKey = eventInstance.setCollectionItem(entity);
+                      const addIdentifier = (referenceNameNewIdentifier) => {
+                          referenceName = referenceNameNewIdentifier;
+                          return {
+                              as: addItemReferenceValue,
+                          }
+                      };
+                      const addItemReferenceValue = (value) => {
+                          eventInstance.setCollectionItemReference(entity, itemKey, referenceName, value);
+                          return {
+                              and: {
+                                  helpers, 
+                                  by: addIdentifier,
+                                  item: { 
+                                      identified: { 
+                                          by: addItem
+                                      }
+                                  },
+                                  a: addCollection
+                              },
+                              conform: {
+                                  to: conformingTo,
+                              },  
+                              then: {track: {with: track}},
+                              helpers
+                          }
+                      };
+                      return {
+                          as: addItemReferenceValue
+                      }
+
+                  };
+
+                  return {
+                      helpers,
+                      with: {
+                          item: {
+                              identified: {
+                                  by: addItem
+                              }
+                          }
+                      },
+                      and: { a: addCollection }
+                  }
+              };
+              return {
+                  collection
+              }
+          };
+
+          // Final dispatch: .then.track.with(tracker)
+          track = (tracker) => {
+              if(!(tracker instanceof CollecionesTracker)){
+                  throw new Error('can only be a CollecionesTracker')
+              }
+              tracker.track(eventInstance);
+              return {
+                  and: track,
+                  helpers,
+              }
+          };
+
+          return {
+              and: andEntity,
+              _: setEntityAfterAnd,
+              identified: {
+                  by: setEntityIdentifiers
+              },
+              has: { been: setAction},
+              node: '_base',
+              helpers
+          }
+
+      })(entity);
+  };
+
+  let collecionesDsl = {
+      the: init
+  };
+
+  (function(global) {
+    global.CollecionesEmitter = CollecionesEmitter;
+    global.CollecionesTracker = CollecionesTracker;
+    global.CollecionesWebTracker = CollecionesWebTracker;
+    global.CollecionesEvent = CollecionesEvent;
+    global.collecionesDsl = collecionesDsl;
+  })(typeof window !== 'undefined' ? window : globalThis);
 
 })();
 //# sourceMappingURL=collecionesClientos.iife.js.map