@compilacion/colleciones-clientos 1.0.12 → 2.0.1

package/dist/collecionesClientos.iife.js

@@ -2,58 +2,7 @@
     'use strict';
 
     // helper 'private' functions
-    /**
-     * Converts a snake_case string to camelCase.
-     * Removes non-ASCII characters.
-     * @param {string} str
-     * @returns {string}
-     */
-    const underscoreToCamelCase = function (str) {
-        str = str.replace(/[^\x00-\x7F_]/g, '');
-        return str
-            .split('_')
-            .map((word, index) => {
-                if (index === 0) {
-                    return word;
-                }
-                return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-            })
-            .join('');
-    };
 
-    /**
-     * Formats adjectives by converting them to camelCase strings.
-     * Accepts a single string or an array of strings.
-     * @param {string|string[]|undefined} adjectiveParameter
-     * @returns {string[]|undefined}
-     */
-    const formatAdjectives = function (adjectiveParameter) {
-        const 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')) {
-            return adjectiveParameter.map(adjective => underscoreToCamelCase(adjective));
-        }
-        throw errorMsg;
-    };
-
-    /**
-     * Converts an array of adjective strings to a dot-prefixed, dot-separated string.
-     * Removes duplicates and sorts alphabetically.
-     * @param {string[]} adjective
-     * @returns {string|undefined}
-     */
-    const stringifyAdjectives = function (adjective) {
-        if (!Array.isArray(adjective) || adjective.length === 0) {
-            return undefined;
-        }
-        const uniqueSorted = [...new Set(adjective)].sort();
-        return '.' + uniqueSorted.join('.');
-    };
 
     /**
      * Encodes a string to Base64.
@@ -95,171 +44,264 @@
 
     /**
      * 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 CollecionesBaseEvent {
+    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';
             }
         }
 
         /**
-         * Sets the event name.
-         * @param {string} name
+         * Returns the declared event format.
+         * @returns {string} The format name (e.g. 'CollecionesEvent').
          */
-        setEventName(name) {
-            this.eventName = name;
+        getEventFormat() {
+            let v = this.meta?.eventFormat;
+            return (typeof v !== 'undefined') ? v : '1';
         }
 
         /**
-         * Returns the event name.
-         * @returns {string}
+         * Returns the version of the event format.
+         * @returns {string} The format version string.
          */
-        getEventName() {
-            return this.eventName;
+        getEventFormatVersion() {
+            let v = this?.meta?.eventFormatVersion;
+            return (typeof v !== 'undefined') ? v : 'CollecionesEvent';
         }
 
         /**
-         * Gets the format of the event.
-         * @returns {string}
+         * Overrides or supplements the event's timestamp fields with custom values.
+         * @param {object} dateTimeObject - Key-value pairs to merge into the existing timestamp object.
          */
-        getEventFormat() {
-            let v = this.data?.meta?.eventFormat;
-            return (typeof v !== 'undefined') ? v : '1';
+        overrideDatetime(dateTimeObject = {}) {
+            for (const [key, value] of Object.entries(dateTimeObject)) {
+                this.meta.timestamps[key] = value;
+            }
         }
 
         /**
-         * Gets the version of the event format.
-         * @returns {string}
+         * Sets the name of the tracker responsible for generating this event.
+         * @param {string} name - Tracker name.
          */
-        getEventFormatVersion() {
-            let v = this.data?.meta?.eventFormatVersion;
-            return (typeof v !== 'undefined') ? v : 'CollecionesBaseEvent';
+        setTracker(name) {
+            this.meta.tracker = name;
         }
 
         /**
-         * Replaces the entire data object.
-         * @param {object} data
+         * Sets the name of the application that generated the event.
+         * @param {string} name - Application name.
          */
-        setData(data) {
-            this.data = data;
+        setAppName(name) {
+            this.meta.appName = name;
         }
 
         /**
-         * Adds a field to the event's custom fields section.
-         * @param {string} name
-         * @param {*} value
+         * Sets the expected schema name for this event.
+         * @param {string} schema - The name of the schema.
          */
-        addAttribute(name, value) {
-            return this.addField(name, value);
+        setSchema(schema) {
+            if (typeof schema !== 'string') {
+                throw new Error('Schema must be a string');
+            }
+            this.meta.schema = schema;
         }
 
         /**
-         * Adds a key-value pair to the custom fields.
-         * @param {string} name
-         * @param {*} value
+         * Sets the entity (subject) of the event.
+         * @param {string} entity - The entity name.
          */
-        addField(name, value) {
-            if (typeof this.data.fields !== 'object' || this.data.fields === null) {
-                this.data.fields = {};
+        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);
         }
 
         /**
-         * Sets the name of the tracker used to generate the event.
-         * @param {string} name
+         * Adds or updates an identifier for the primary entity.
+         * @param {string} name - The identifier key.
+         * @param {*} identifier - The identifier value.
          */
-        setTracker(name) {
-            this.data.tracker = name;
+        setIdentifier = function(name, identifier) {
+            if (typeof name !== 'string') {
+                throw new Error('Identifier name must be a string');
+            }
+            this.identifiers[name] = identifier;
         }
 
         /**
-         * Sets the name of the application that created the event.
-         * @param {string} name
+         * Defines the name of the actor (who or what performed the action).
+         * @param {string} name - Actor name (e.g., 'user').
          */
-        setAppName(name) {
-            this.data.appName = name;
+        setActor = function(name) {
+            if (typeof name !== 'string') {
+                throw new Error('Actor name must be a string');
+            }
+            this.actor.name = name;
         }
 
         /**
-         * Adds multiple identifiers from an object.
-         * @param {object} param
+         * Adds or updates an identifier for the actor.
+         * @param {string} name - Identifier name.
+         * @param {*} identifier - Identifier value.
          */
-        convertParamIdentifiers(param) {
-            if (typeof param === 'object' && param !== null && !Array.isArray(param)) {
-                for (const [key, value] of Object.entries(param)) {
-                    this.addIdentifier(key, value);
-                }
+        setActorIdentifier = function(name, identifier) {
+            if (typeof name !== 'string') {
+                throw new Error('Actor Identifier name must be a string');
             }
+            this.actor.identifiers[name] = identifier;
         }
 
         /**
-         * Adds a single identifier to the event.
-         * @param {string} name
-         * @param {*} value
+         * Adds contextual information to the event.
+         * @param {string} context - The key of the context field.
+         * @param {*} value - The value of the context field.
          */
-        addIdentifier(name, value) {
-            if (typeof this.data.identifiers !== 'object' || this.data.identifiers === null) {
-                this.data.identifiers = {};
+        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;
         }
 
         /**
-         * Constructs the postable event object with metadata and encoded payload.
-         * @returns {object}
+         * Declares an entity referenced by this event.
+         * @param {string} entity - The referenced entity name.
          */
-        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())
-            };
+        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: {}};
+            }
         }
 
         /**
-         * Overrides or extends the timestamp fields of the event.
-         * @param {object} dateTimeObject
+         * 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.
          */
-        overrideDatetime(dateTimeObject = {}) {
-            for (const [key, value] of Object.entries(dateTimeObject)) {
-                this.data.timestamps[key] = 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;
         }
 
         /**
-         * Serializes the event data to a JSON string.
-         * @returns {string}
+         * Serializes the event to a plain object suitable for JSON.stringify().
+         * @returns {object}
          */
-        getPayload() {
-            return JSON.stringify(this.data);
+        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;
+        }
+        
     }
 
     /**
-     * Emitter class responsible for batching and sending events to a configured endpoint.
+     * 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 {
 
@@ -279,6 +321,7 @@
 
         /**
          * Starts the flush timer if a valid interval is set.
+         * @returns {void}
          */
         startTimer() {
             this.stopTimer();
@@ -289,6 +332,7 @@
 
         /**
          * Starts the flush timer only if not already running.
+         * @returns {void}
          */
         startTimerIfStopped() {
             if (!this.timer) {
@@ -298,6 +342,7 @@
 
         /**
          * Stops the active flush timer.
+         * @returns {void}
          */
         stopTimer() {
             if (this.timer) {
@@ -308,23 +353,28 @@
 
         /**
          * Adds an event to the buffer and flushes if threshold is reached.
-         * @param {CollecionesBaseEvent} event
+         * 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.
-         * @param {CollecionesBaseEvent} event
-         * @returns {Promise<void>}
+         * 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);
@@ -332,18 +382,16 @@
         }
 
         /**
-         * Sends the buffered events to the server and clears the buffer.
-         * @returns {Promise<boolean|undefined>}
+         * 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() );
-            });
             this.stopTimer();
+            let body = this.getBody();
             try {
                 const response = await fetch(this.endpoint, {
                     method: 'POST',
@@ -351,7 +399,7 @@
                     headers: {
                         'Content-Type': 'application/json'
                     },
-                    body: JSON.stringify(postPayload)
+                    body
                 });
                 if (!response.ok) {
                     console.log(`Failed to send events: ${response.statusText}`);
@@ -361,6 +409,16 @@
                 console.log(`Network error sending events: ${error.message}`);
             }   
         }
+
+        getBody() {
+            const eventsToSend = [...this.buffer];
+            this.buffer = [];
+            let postPayload = [];
+            eventsToSend.forEach((e) => {
+                postPayload.push( toBase64( JSON.stringify(e.toJSON())) );
+            });
+            return JSON.stringify(postPayload);
+        }
     }
 
     /**
@@ -381,22 +439,13 @@
             this.identifiers = {};
         }
 
-        /**
-         * Adds a global identifier to be included with every event.
-         * @param {string} name - Identifier key.
-         * @param {*} value - Identifier value.
-         */
-        addIdentifier(name, value) {
-            this.identifiers[name] = value;
-        }
-
         /**
          * Sends an event to all emitters after enriching it with identifiers and metadata.
-         * @param {CollecionesBaseEvent} collecionesEvent - The event to be sent.
-         * @throws {Error} If the input is not an instance of CollecionesBaseEvent.
+         * @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)) {
@@ -427,217 +476,256 @@
 
         /**
          * Tracks an event, enriching it with browser context information.
-         * @param {CollecionesBaseEvent} collecionesEvent - The event object to track.
-         * @throws {Error} If the event is not an instance of CollecionesBaseEvent.
+         * @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);        
         }
     }
 
     /**
-     * Represents a semantic event with a name, data payload, and identifiers.
-     * Extends CollecionesBaseEvent.
+     * 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.
      */
-    class CollecionesEvent extends CollecionesBaseEvent {
 
-        /**
-         * Constructs a new CollecionesEvent instance.
-         * @param {string} name - The name of the event.
-         * @param {object} data - The main data payload of the event.
-         * @param {object} identifiers - A set of identifiers to associate with the event.
-         */
-        constructor(name, data, identifiers) {
-            super();
-            this.setEventName(name);
-            Object.assign(this.data, data);
-            this.convertParamIdentifiers(identifiers);
-        }
 
-    }
+    let init = (entity) => {
+        return ((entity)=>{
+            let eventInstance = new CollecionesEvent(); // Core event object
+            eventInstance.setEntity(entity);
 
-    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();
-    }
+            let helpers = {
+                getEvent: () => {
+                    return eventInstance;
+                },
+            };
 
-    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);
-    }
+            // 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 randomUUID = typeof crypto !== 'undefined' && crypto.randomUUID && crypto.randomUUID.bind(crypto);
-    var native = { randomUUID };
+            // 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
+                };
+            };
 
-    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);
-    }
+            // Additional adjectives: .and('...')._()
+            andEntity = (entity) => {
+                eventInstance.addAdjective(eventInstance.entity);
+                eventInstance.setEntity(entity);
+                return {
+                    and: andEntity,
+                    _ : setEntityAfterAnd,
+                    helpers
+                }
+            };
 
-    /**
-     * Represents a structured semantic event with entity, action, and optional adjective.
-     * Includes automatic naming and identifier mapping.
-     * Extends CollecionesBaseEvent.
-     */
-    class CollecionesSemanticEvent extends CollecionesBaseEvent {
+            // Action: .has.been('...')
+            setAction = (action) => {
+                eventInstance.setAction(action);
+                return {
+                    by: setActor,
+                    referring: { to: addReference },
+                    with: addContext,
+                    conform: {to: conformingTo},
+                    then: {track: {with: track}},
+                    helpers
+                }
+            };
 
-        /**
-         * Constructs a new semantic event.
-         * @param {string} entity - The entity involved in the event.
-         * @param {string} action - The action performed on the entity.
-         * @param {string|string[]|undefined} adjective - Optional adjective(s) modifying the event.
-         * @param {object} identifiers - Key-value pairs to be added as identifiers.
-         */
-        constructor(entity, action, adjective, identifiers) {
-            super();
-            this.entity = underscoreToCamelCase(entity);
-            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: .by('user')
+            setActor = (name) => {
+                eventInstance.setActor(name);
+                return { 
+                    identified: {
+                        by: setActorIdentifier
+                    },
+                    with: addContext,
+                    helpers
+                }
             };
-        }
 
-        /**
-         * This method is deprecated in semantic events and will throw if called.
-         * @throws {Error}
-         */
-        setData() {
-            throw new Error('setData deprecated in semantic events');
-        }
+            // Actor identifier: .identified.by().as()
+            setActorIdentifier = (name) => {
+                return {
+                    as: (value) => {
+                        eventInstance.setActorIdentifier(name, value);
+                        return {
+                            helpers,
+                            and: setActorIdentifier,
+                            with: addContext,
+                            referring: { to: addReference },
+                        }
+                    },
+                    helpers
+                }
+            };
 
-        /**
-         * Adds a key-value pair as an identifier for the semantic entity.
-         * @param {string} key - The identifier name.
-         * @param {string|number} value - The identifier value.
-         * @throws Will throw if key is not a string or value is not a string or number.
-         */
-        addEntityIdentifier(key, value) {
-            if (typeof key !== 'string') {
-                throw new Error('Entity identifier key must be a string');
-            }
-            if (typeof value !== 'string' && typeof value !== 'number') {
-                throw new Error('Entity identifier value must be a string or number');
-            }
-            this.data.entityIdentifiers[key] = value;
-        }
+            // 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 },
+                            }
+                        }
+                    }
+                }
+            };
 
-    }
+            // Reference: .referring.to('...')
+            addReference = (entity) => {
+                eventInstance.setRefence(entity);
+                return {
+                    identified: {
+                        by: getAddReference(entity)
+                    },
+                    conform: {to: conformingTo},
+                    then: {track: {with: track}},
+                    helpers
+                }
+            };
 
-    /**
-     * Represents a semantic event related to a collection of entities.
-     * Extends CollecionesSemanticEvent and adds item-level detail and identifiers.
-     */
-    class CollecionesSemanticCollectionEvent extends CollecionesSemanticEvent {
+            // 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,
+                    };
+                };
+            };
 
-        /**
-         * Constructs a new CollecionesSemanticCollectionEvent.
-         * @param {string} itemEntity - The name of the item entity being acted on.
-         * @param {string} action - The action performed.
-         * @param {string|string[]|undefined} adjective - Optional adjective(s) describing the action.
-         * @param {object} identifiers - Identifiers associated with the event.
-         * @param {string} [collectionEntity] - Optional collection name, defaults to `${itemEntity}Collection`.
-         */
-        constructor(itemEntity, action, adjective, identifiers, collectionEntity) {
-            if (typeof collectionEntity == 'undefined') {
-                collectionEntity = `${itemEntity}Collection`;
-            }
-            super(collectionEntity, action, undefined, identifiers);
-            this.data.meta = {
-                eventFormat: 'CollecionesSemanticCollectionEvent',
-                eventFormatVersion: '1'
+            // Schema declaration: .conform.to('...')
+            conformingTo = (name) => {
+                eventInstance.setSchema(name);
+                return { 
+                    then: {track: {with: 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 = {};
-        }
 
-        /**
-         * Adds an identifier value (or values) for a specific entity item key.
-         * @param {string} key - The identifier name.
-         * @param {string|number|Array<string|number>} value - The identifier value(s).
-         * @throws Will throw if key is not a string or value is of invalid type.
-         */
-        addEntityItemIdentifier(key, value) {
-            if (typeof key !== 'string') {
-                throw new Error('Entity identifier key must be a string');
-            }
-            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);
+            // Final dispatch: .then.track.with(emitter)
+            track = (emitter) => {
+                if(emitter instanceof CollecionesEmitter){
+                    emitter.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.CollecionesSemanticEvent = CollecionesSemanticEvent;
-      global.CollecionesSemanticCollectionEvent = CollecionesSemanticCollectionEvent;
+      global.collecionesDsl = collecionesDsl;
     })(typeof window !== 'undefined' ? window : globalThis);
 
 })();