@compilacion/colleciones-clientos 1.0.11 → 2.0.0

package/dist/index.cjs

@@ -1,56 +1,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 {};
@@ -70,108 +41,275 @@ const getBrowserContext = function() {
     };
 };
 
-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;
@@ -180,6 +318,10 @@ class CollecionesEmitter {
         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) {
@@ -187,12 +329,20 @@ class CollecionesEmitter {
         }
     }
 
+    /**
+     * 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);
@@ -200,29 +350,50 @@ class CollecionesEmitter {
         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 {
@@ -244,8 +415,17 @@ class CollecionesEmitter {
     }
 }
 
+/**
+ * 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;
@@ -253,12 +433,13 @@ class CollecionesTracker {
         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)) {
@@ -269,172 +450,273 @@ class CollecionesTracker {
         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
+};
 
 exports.CollecionesEmitter = CollecionesEmitter;
 exports.CollecionesEvent = CollecionesEvent;
-exports.CollecionesSemanticCollectionEvent = CollecionesSemanticCollectionEvent;
-exports.CollecionesSemanticEvent = CollecionesSemanticEvent;
 exports.CollecionesTracker = CollecionesTracker;
 exports.CollecionesWebTracker = CollecionesWebTracker;
+exports.collecionesDsl = collecionesDsl;
 //# sourceMappingURL=index.cjs.map