@compilacion/colleciones-clientos 1.0.11 → 2.0.0

package/dist/collecionesClientos.iife.js

@@ -2,56 +2,27 @@
     'use strict';
 
     // helper 'private' functions
-    const underscoreToCamelCase = function (str) {
-        str = str.replace(/[^\x00-\x7F_]/g, '');
-        return str
-            .split('_')
-            .map((word, index) => {
-                if (index === 0) {
-                    return word;
-                }
-                return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-            })
-            .join('');
-    };
-
-    const formatAdjectives = function (adjectiveParameter) {
-        let errorMsg = new Error('Adjective must be a string, an array of strings, or undefined');
-        if (typeof adjectiveParameter === 'undefined') {
-            return undefined;
-        }
-        if (typeof adjectiveParameter === 'string') {
-            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;
-        }
-        throw errorMsg;
-    };
 
-    const stringifyAdjectives = function (adjective) {
-        if (!Array.isArray(adjective) || adjective.length === 0) {
-            return undefined;
-        }
-        const uniqueSorted = [...new Set(adjective)].sort();
-        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,108 +42,275 @@
         };
     };
 
-    class CollecionesBaseEvent {
+    /**
+     * Base class representing a structured event with timestamp, identifiers, and data fields.
+     * This class is used to model events in a semantic and structured format for tracking purposes.
+     */
+    class CollecionesEvent {
 
+        /**
+         * Constructs a new event with default metadata and timestamps.
+         */
         constructor() {
-            this.eventName = '';
-            this.data = {};
-            this.data.meta = {
-                eventFormat: 'CollecionesBaseEvent',
+            // initialize event properties
+            this.entity = '';
+            this.adjevtives = [];
+            this.identifiers = {};
+            this.action = '';
+            this.actor = {
+                name:'', 
+                identifiers: []
+            };
+            this.context = {};
+            this.references = {};
+            // set default values
+            this.meta = {
+                eventFormat: 'CollecionesEvent',
                 eventFormatVersion: '1'
             };
-            this.data.timestamps = {};
-            this.data.timestamps.clientDatetimeUtc = new Date().toISOString();
+            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.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();
+                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.data.timestamps.clientDatetimeLocal = new Date().toISOString();
-                this.data.timestamps.timeZone = 'UTC';
+                this.meta.timestamps.clientDatetimeLocal = new Date().toISOString();
+                this.meta.timestamps.timeZone = 'UTC';
             }
         }
 
-        setEventName(name) {
-            this.eventName = name;
+        /**
+         * 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';
         }
 
-        getEventName() {
-            return this.eventName;
+        /**
+         * 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';
         }
 
-        getEventFormat() {
-            let v = this.data?.meta?.eventFormat;
-            return (typeof v !== 'undefined') ? v : '1';
+        /**
+         * 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;
+            }
         }
 
-        getEventFormatVersion() {
-            let v = this.data?.meta?.eventFormatVersion;
-            return (typeof v !== 'undefined') ? v : 'CollecionesBaseEvent';
+        /**
+         * Sets the name of the tracker responsible for generating this event.
+         * @param {string} name - Tracker name.
+         */
+        setTracker(name) {
+            this.meta.tracker = name;
         }
 
-        setData(data) {
-            this.data = data;
+        /**
+         * Sets the name of the application that generated the event.
+         * @param {string} name - Application name.
+         */
+        setAppName(name) {
+            this.meta.appName = name;
         }
 
-        addAttribute(name, value) {
-            return this.addField(name, value);
+        /**
+         * 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;
         }
 
-        addField(name, value) {
-            if (typeof this.data.fields !== 'object' || this.data.fields === null) {
-                this.data.fields = {};
+        /**
+         * 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.data.fields[name] = value;
+            this.adjevtives.push(adjective);
         }
 
-        setTracker(name) {
-            this.data.tracker = name;
+        /**
+         * Adds or updates an identifier for the primary 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;
         }
 
-        setAppName(name) {
-            this.data.appName = name;
+        /**
+         * Defines the name of the actor (who or what performed the action).
+         * @param {string} name - Actor name (e.g., 'user').
+         */
+        setActor = function(name) {
+            if (typeof name !== 'string') {
+                throw new Error('Actor name must be a string');
+            }
+            this.actor.name = name;
         }
 
-        convertParamIdentifiers(param) {
-            if (typeof param === 'object' && param !== null && !Array.isArray(param)) {
-                for (const [key, value] of Object.entries(param)) {
-                    this.addIdentifier(key, value);
-                }
+        /**
+         * Adds or updates an identifier for the actor.
+         * @param {string} name - Identifier name.
+         * @param {*} identifier - Identifier value.
+         */
+        setActorIdentifier = function(name, identifier) {
+            if (typeof name !== 'string') {
+                throw new Error('Actor Identifier name must be a string');
             }
+            this.actor.identifiers[name] = identifier;
         }
 
-        addIdentifier(name, value) {
-            if (typeof this.data.identifiers !== 'object' || this.data.identifiers === null) {
-                this.data.identifiers = {};
+        /**
+         * Adds contextual information to the event.
+         * @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.data.identifiers[name] = value;
+            this.context[context] = value;
         }
 
-        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())
-            };
+        /**
+         * Declares an entity referenced by this event.
+         * @param {string} entity - The referenced entity name.
+         */
+        setRefence = function(entity) {
+            if (typeof entity !== 'string') {
+                throw new Error('Referenced entity must be a string');
+            }
+            if(this.references[entity] === undefined) {
+                this.references[entity] = {identifiers: {}};
+            }
         }
 
-        overrideDatetime(dateTimeObject = {}) {
-            for (const [key, value] of Object.entries(dateTimeObject)) {
-                this.data.timestamps[key] = value;
+        /**
+         * 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.
+         */
+        setRefenceIdentifier = function(entity, name, identifier) {
+            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);
+            this.references[entity].identifiers[name] = identifier;
         }
 
-        getPayload() {
-            return JSON.stringify(this.data);
+        /**
+         * Serializes the event to a plain object suitable for JSON.stringify().
+         * @returns {object}
+         */
+        toJSON() {
+            return {
+                class: 'CollecionesEvent',
+                entity: this.entity,
+                adjectives: this.adjevtives,
+                identifiers: this.identifiers,
+                action: this.action,
+                actor: this.actor,
+                context: this.context,
+                references: this.references,
+                meta: this.meta
+            };
         }
 
+        /**
+         * Recreates an instance of CollecionesEvent from a plain object.
+         * @param {object} obj
+         * @returns {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 || { name: '', identifiers: {} };
+            instance.context = obj.context || {};
+            instance.references = obj.references || {};
+            instance.meta = obj.meta || {};
+            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;
@@ -181,6 +319,10 @@
             this.timer = null;
         }
 
+        /**
+         * Starts the flush timer if a valid interval is set.
+         * @returns {void}
+         */
         startTimer() {
             this.stopTimer();
             if (typeof this.flushInterval == 'number' && this.flushInterval > 0) {
@@ -188,12 +330,20 @@
             }
         }
 
+        /**
+         * 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);
@@ -201,29 +351,50 @@
             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 CollecionesBaseEvent)) {
-                throw new Error('Event must be an instance of CollecionesBaseEvent');
+            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 CollecionesBaseEvent)) {
-                throw new Error('Event must be an instance of CollecionesBaseEvent');
+            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;
             const eventsToSend = [...this.buffer];
             this.buffer = [];
             let postPayload = [];
             eventsToSend.forEach((e) => {
-                postPayload.push( e.getPostObject() );
+                postPayload.push( toBase64( JSON.stringify(e.toJSON())) );
             });
             this.stopTimer();
             try {
@@ -245,8 +416,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;
@@ -254,12 +434,13 @@
             this.identifiers = {};
         }
 
-        addIdentifier(name, value) {
-            this.identifiers[name] = value;
-        }
-
+        /**
+         * 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 CollecionesBaseEvent)) {
+            if (!(collecionesEvent instanceof CollecionesEvent)) {
                 throw new Error('Event must be of type CollecionesEvent');
             }
             for (const [key, value] of Object.entries(this.identifiers)) {
@@ -270,175 +451,276 @@
             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 CollecionesBaseEvent)) {
+            if (!(collecionesEvent instanceof CollecionesEvent)) {
                 throw new Error('Event must be of type CollecionesEvent');
             }
-            collecionesEvent.addField('browserContext', getBrowserContext());
+            collecionesEvent.setContext('browserContext', getBrowserContext());
             super.track(collecionesEvent);        
         }
     }
 
-    class CollecionesEvent extends CollecionesBaseEvent {
-
-        constructor(name, data, identifiers) {
-            super();
-            this.setEventName(name);
-            Object.assign(this.data, data);
-            this.convertParamIdentifiers(identifiers);
-        }
+    /**
+     * 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 addReferenceIdentifier = () => {}; // .and(...) after reference
+            let conformingTo = () => {}; // .conform.to('SchemaName')
+            let track = () => {}; // .then.track.with(emitter)
+
+            // Adjective chaining: .and(...)._('entity')
+            setEntityAfterAnd = (entity) => {
+                eventInstance.addAdjective(eventInstance.entity);
+                eventInstance.setEntity(entity);
+                return {
+                    as: () => {
+                        return { helpers }
+                    },
+                    identified: {
+                        by: setEntityIdentifiers
+                    },
+                    has: { been: setAction },
+                    helpers
+                };
+            };
 
-    const byteToHex = [];
-    for (let i = 0; i < 256; ++i) {
-        byteToHex.push((i + 0x100).toString(16).slice(1));
-    }
-    function unsafeStringify(arr, offset = 0) {
-        return (byteToHex[arr[offset + 0]] +
-            byteToHex[arr[offset + 1]] +
-            byteToHex[arr[offset + 2]] +
-            byteToHex[arr[offset + 3]] +
-            '-' +
-            byteToHex[arr[offset + 4]] +
-            byteToHex[arr[offset + 5]] +
-            '-' +
-            byteToHex[arr[offset + 6]] +
-            byteToHex[arr[offset + 7]] +
-            '-' +
-            byteToHex[arr[offset + 8]] +
-            byteToHex[arr[offset + 9]] +
-            '-' +
-            byteToHex[arr[offset + 10]] +
-            byteToHex[arr[offset + 11]] +
-            byteToHex[arr[offset + 12]] +
-            byteToHex[arr[offset + 13]] +
-            byteToHex[arr[offset + 14]] +
-            byteToHex[arr[offset + 15]]).toLowerCase();
-    }
+            // 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
+                };
+            };
 
-    let getRandomValues;
-    const rnds8 = new Uint8Array(16);
-    function rng() {
-        if (!getRandomValues) {
-            if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
-                throw new Error('crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported');
-            }
-            getRandomValues = crypto.getRandomValues.bind(crypto);
-        }
-        return getRandomValues(rnds8);
-    }
+            // Additional adjectives: .and('...')._()
+            andEntity = (entity) => {
+                eventInstance.addAdjective(eventInstance.entity);
+                eventInstance.setEntity(entity);
+                return {
+                    and: andEntity,
+                    _ : setEntityAfterAnd,
+                    helpers
+                }
+            };
 
-    const randomUUID = typeof crypto !== 'undefined' && crypto.randomUUID && crypto.randomUUID.bind(crypto);
-    var native = { randomUUID };
+            // Action: .has.been('...')
+            setAction = (action) => {
+                eventInstance.setAction(action);
+                return {
+                    by: setActor,
+                    referring: { to: addReference },
+                    with: addContext,
+                    conform: {to: conformingTo},
+                    then: {track: {with: track}},
+                    helpers
+                }
+            };
 
-    function v4(options, buf, offset) {
-        if (native.randomUUID && true && !options) {
-            return native.randomUUID();
-        }
-        options = options || {};
-        const rnds = options.random ?? options.rng?.() ?? rng();
-        if (rnds.length < 16) {
-            throw new Error('Random bytes length must be >= 16');
-        }
-        rnds[6] = (rnds[6] & 0x0f) | 0x40;
-        rnds[8] = (rnds[8] & 0x3f) | 0x80;
-        return unsafeStringify(rnds);
-    }
+            // Actor: .by('user')
+            setActor = (name) => {
+                eventInstance.setActor(name);
+                return { 
+                    identified: {
+                        by: setActorIdentifier
+                    },
+                    with: addContext,
+                    helpers
+                }
+            };
 
-    class CollecionesSemanticEvent extends CollecionesBaseEvent {
-
-        constructor(entity, action, adjective, identifiers) {
-            super();
-            this.entity = underscoreToCamelCase(entity);
-            this.action = underscoreToCamelCase(action);
-            this.adjective = formatAdjectives(adjective);
-            let adjectiveString = stringifyAdjectives(this.adjective);
-            this.eventName = `${this.entity}${(adjectiveString !== undefined) ? adjectiveString : ''}__${this.action}`;
-            this.convertParamIdentifiers(identifiers);
-            this.data.entityIdentifiers = {};
-            this.data.attributes = {};
-            this.data.clientEventId = v4();
-            this.data.meta = {
-                eventFormat: 'CollecionesSemanticEvent',
-                eventFormatVersion: '1'
+            // Actor identifier: .identified.by().as()
+            setActorIdentifier = (name) => {
+                return {
+                    as: (value) => {
+                        eventInstance.setActorIdentifier(name, value);
+                        return {
+                            helpers,
+                            and: setActorIdentifier,
+                            with: addContext,
+                            referring: { to: addReference },
+                        }
+                    },
+                    helpers
+                }
             };
-        }
 
-        setData() {
-            throw new Error('setData deprecated in semantic events');
-        }
+            // 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 },
+                            }
+                        }
+                    }
+                }
+            };
 
-        addEntityIdentifier(key, value) {
-            if (typeof key !== 'string') {
-                throw new Error('Entity identifier key must be a string');
-            }
-            if (typeof value !== 'string' && typeof value !== 'number') {
-                throw new Error('Entity identifier value must be a string or number');
-            }
-            this.data.entityIdentifiers[key] = value;
-        }
+            // Reference: .referring.to('...')
+            addReference = (entity) => {
+                eventInstance.setRefence(entity);
+                return {
+                    identified: {
+                        by: getAddReference(entity)
+                    },
+                    conform: {to: conformingTo},
+                    then: {track: {with: track}},
+                    helpers
+                }
+            };
 
-    }
+            // Reference identifier setup: .identified.by().as()
+            getAddReference = (entity) => {
+                return (name) => {
+                    return {
+                        as: (value) => {
+                            eventInstance.setRefenceIdentifier(entity, name, value);
+                            return {
+                                helpers,
+                                and: addReferenceIdentifier,
+                                conform: {to: conformingTo},
+                                then: {track: {with: track}},
+                            }
+                        },
+                        helpers,
+                    };
+                };
+            };
 
-    class CollecionesSemanticCollectionEvent extends CollecionesSemanticEvent {
+            // Schema declaration: .conform.to('...')
+            conformingTo = (name) => {
+                eventInstance.setSchema(name);
+                return { 
+                    then: {track: {with: track}},
+                    helpers
+                }
+            };
 
-        constructor(itemEntity, action, adjective, identifiers, collectionEntity) {
-            if(typeof collectionEntity == 'undefined') {
-                collectionEntity = `${itemEntity}Collection`;
-            }
-            super(collectionEntity, action, undefined, identifiers);
-            this.data.meta = {
-                eventFormat: 'CollecionesSemanticCollectionEvent',
-                eventFormatVersion: '1'
+            // Final dispatch: .then.track.with(emitter)
+            track = (emitter) => {
+                if(emitter instanceof CollecionesEmitter){
+                    emitter.track(eventInstance);
+                }
+                return {
+                    and: track,
+                    helpers,
+                }
             };
-            this.adjective = formatAdjectives(adjective);
-            let adjectiveString = stringifyAdjectives(this.adjective);
-            itemEntity = underscoreToCamelCase(itemEntity);
-            this.data.itemEntity = itemEntity;
-            this.data.itemEventName = `${itemEntity}${(adjectiveString !== undefined) ? adjectiveString : ''}__${this.action}`;
-            this.data.entityItemIdentifiers = {};
-        }
 
-        addEntityItemIdentifier(key, value) {
-            if (typeof key !== 'string') {
-                throw new Error('Entity identifier key must be a string');
-            }
-            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') {
-                this.data.entityItemIdentifiers[key] = [];
-            }
-            if(Array.isArray(value)) {
-                value.forEach((v)=> {
-                    this.data.entityItemIdentifiers[key].push(v);
-                });
-            } else {
-                this.data.entityItemIdentifiers[key].push(value);
+            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.CollecionesSemanticEvent = CollecionesSemanticEvent;
-      global.CollecionesSemanticCollectionEvent = CollecionesSemanticCollectionEvent;
+      global.collecionesDsl = collecionesDsl;
     })(typeof window !== 'undefined' ? window : globalThis);
 
 })();