@compilacion/colleciones-clientos 2.0.24 → 2.0.28

package/dist/browser.domainModel.gtm.js

@@ -611,6 +611,99 @@
 
   }
 
+  /**
+   * CollecionesEventGroup
+   * ----------------------
+   * A client-side grouping interface for events that belong to the same business occurrence.
+   *
+   * Design principles:
+   * - A group is purely a build-time construct; it does not change the wire format.
+   * - Each event in the group remains a standalone CollecionesEvent.
+   * - When getEvents() is called, group metadata is materialised onto each event:
+   *     meta.eventGroup.id              — the shared group id
+   *     meta.eventGroup.groupClientEventIds — clientEventIds of all other events in the group
+   * - Semantic meaning of the relations between events is intentionally left to the domain model.
+   *
+   * Usage:
+   *   const group = new CollecionesEventGroup();
+   *
+   *   const eventA = group.addEvent();
+   *   eventA.setEntity('listing');
+   *   eventA.setAction('viewed');
+   *
+   *   const eventB = group.addEvent();
+   *   eventB.setEntity('session');
+   *   eventB.setAction('active');
+   *
+   *   tracker.trackGroup(group);
+   */
+
+
+  class CollecionesEventGroup {
+
+      /**
+       * Creates a new event group.
+       * The groupId is NOT generated up-front: a group's identity is defined by its composition,
+       * so the id is generated lazily in getEvents() and invalidated by every addEvent() call.
+       * Reading `group.groupId` before the first getEvents() returns null.
+       */
+      constructor() {
+          this.groupId = null;
+          this._events = [];
+      }
+
+      /**
+       * Adds an event to the group.
+       * When called without arguments it acts as an alias for `new CollecionesEvent()`,
+       * keeping the same familiar contract as building events directly.
+       * An existing CollecionesEvent instance may also be passed in.
+       *
+       * Adding an event changes the composition of the group, so the cached groupId is invalidated
+       * — the next getEvents() call will generate a fresh id and re-stamp every event.
+       *
+       * @param {CollecionesEvent|null} [event=null] - An existing event to register, or null to create a fresh one.
+       * @returns {CollecionesEvent} The event that was added.
+       * @throws {Error} If a non-null, non-CollecionesEvent value is passed.
+       */
+      addEvent(event = null) {
+          if (event !== null && !(event instanceof CollecionesEvent)) {
+              throw new Error('Event must be an instance of CollecionesEvent');
+          }
+          const newEvent = event ?? new CollecionesEvent();
+          this._events.push(newEvent);
+          this.groupId = null;
+          return newEvent;
+      }
+
+      /**
+       * Materialises group metadata onto every event and returns the full list.
+       * If no groupId is currently set, a new one is generated here. Each event then receives:
+       *   - meta.eventGroup.id                  — the groupId of this group
+       *   - meta.eventGroup.groupClientEventIds — clientEventIds of the sibling events (not self)
+       *
+       * Safe to call multiple times: idempotent as long as no addEvent() happened in between.
+       * After an addEvent() the cached groupId is null, so a subsequent getEvents() will mint a fresh id
+       * and re-stamp every event accordingly.
+       *
+       * Callers may also assign `group.groupId` directly (e.g. with a semantic name) before calling
+       * getEvents() to override the auto-generated value; do so AFTER all addEvent() calls,
+       * otherwise the next addEvent() will clear the override.
+       *
+       * @returns {CollecionesEvent[]} A shallow copy of the internal events array with group metadata applied.
+       */
+      getEvents() {
+          if (this.groupId === null) {
+              this.groupId = generateId();
+          }
+          const allClientEventIds = this._events.map(e => e.meta.clientEventId);
+          this._events.forEach(event => {
+              const peers = allClientEventIds.filter(id => id !== event.meta.clientEventId);
+              event.setEventGroup(this.groupId, peers);
+          });
+          return [...this._events];
+      }
+  }
+
   /**
    * Tracks events by enriching them with shared identifiers and routing through configured emitters.
    */
@@ -741,7 +834,6 @@
               if (!initialized) return false;
               if (!tracker) return false;
               if (!arg || typeof arg !== 'object') return false;
-              if (!arg.entity || !arg.action) return false;
 
               const normalizeIdentifiers = (identifiers) => {
                   if (Array.isArray(identifiers)) {
@@ -784,7 +876,7 @@
               };
 
               // Collection items are stored as `{ identifierField: value }` on the event.
-              const addCollectionItem = (collectionName, identifierName, identifierValue) => {
+              const addCollectionItem = (event, collectionName, identifierName, identifierValue) => {
                   if (!collectionName || !identifierName || identifierValue === undefined || identifierValue === null) {
                       return;
                   }
@@ -795,24 +887,24 @@
               // ARRAY collections are the simplest form:
               // they are arrays of primitive values that should be copied into the event
               // using the configured identifier field.
-              const applyArrayCollection = (collectionName, collectionConfig) => {
+              const applyArrayCollection = (event, collectionName, collectionConfig) => {
                   if (!Array.isArray(collectionConfig.array)) {
                       return false;
                   }
                   const identifierName = collectionConfig.identifierField;
                   collectionConfig.array.forEach((value) => {
                       if (Array.isArray(value)) {
-                          value.forEach((nestedValue) => addCollectionItem(collectionName, identifierName, nestedValue));
+                          value.forEach((nestedValue) => addCollectionItem(event, collectionName, identifierName, nestedValue));
                           return;
                       }
-                      addCollectionItem(collectionName, identifierName, value);
+                      addCollectionItem(event, collectionName, identifierName, value);
                   });
                   return true;
               };
 
               // EVALUATED collections derive their identifier value from a path on each item.
               // An optional filter object narrows the source array before mapping.
-              const applyEvaluatedCollection = (collectionName, collectionConfig) => {
+              const applyEvaluatedCollection = (event, collectionName, collectionConfig) => {
                   if (!Array.isArray(collectionConfig.itemsField)) {
                       return false;
                   }
@@ -834,14 +926,14 @@
                   const identifierName = collectionConfig.identifierField;
                   items.forEach((item) => {
                       const identifierValue = getByPath(item, collectionConfig.path) ?? item?.[identifierName] ?? item?.id;
-                      addCollectionItem(collectionName, identifierName, identifierValue);
+                      addCollectionItem(event, collectionName, identifierName, identifierValue);
                   });
                   return true;
               };
 
               // PARAMTABLE rows use dynamic field names that are prefixed by the collection name:
               // e.g. `listingParamTableItemsField` and `listingIdentifierValueParamTable`.
-              const applyParamTableCollection = (collectionName, collectionConfig) => {
+              const applyParamTableCollection = (event, collectionName, collectionConfig) => {
                   if (!Array.isArray(collectionConfig.table)) {
                       return false;
                   }
@@ -854,73 +946,100 @@
                       }
                       const identifierName = row[identifierNameKey];
                       const identifierValue = row[identifierValueKey];
-                      addCollectionItem(collectionName, identifierName, identifierValue);
+                      addCollectionItem(event, collectionName, identifierName, identifierValue);
                   });
                   return true;
               };
 
-              const applyCollectionConfig = (collectionName, collectionConfig) => {
+              const applyCollectionConfig = (event, collectionName, collectionConfig) => {
                   if (!collectionConfig || typeof collectionConfig !== 'object') {
                       return;
                   }
 
                   if (collectionConfig.type === 'ARRAY') {
-                      applyArrayCollection(collectionName, collectionConfig);
+                      applyArrayCollection(event, collectionName, collectionConfig);
                       return;
                   }
                   if (collectionConfig.type === 'EVALUATED') {
-                      applyEvaluatedCollection(collectionName, collectionConfig);
+                      applyEvaluatedCollection(event, collectionName, collectionConfig);
                       return;
                   }
                   if (collectionConfig.type === 'PARAMTABLE') {
-                      applyParamTableCollection(collectionName, collectionConfig);
+                      applyParamTableCollection(event, collectionName, collectionConfig);
                   }
               };
 
-              const event = new CollecionesEvent();
-              event.setEntity(arg.entity);
-              event.setAction(arg.action);
-
-              normalizeIdentifiers(arg.identifiers).forEach(identifier => {
-                  if (typeof identifier !== 'object' || identifier === null) return;
-                  if (!identifier.name || !identifier.value) return;
-                  event.setIdentifier(identifier.name, identifier.value);
-              });
+              const populateEvent = (eventArg, event) => {
+                  event.setEntity(eventArg.entity);
+                  event.setAction(eventArg.action);
 
-              if (arg.actor?.entity) {
-                  event.setActor(arg.actor.entity);
-                  let identifiers = arg.actor?.identifiers;
-                  if (!Array.isArray(identifiers)) {
-                      identifiers = identifiers?.[arg.actor.entity] ?? identifiers;
-                  }
-                  normalizeIdentifiers(identifiers).forEach(identifier => {
+                  normalizeIdentifiers(eventArg.identifiers).forEach(identifier => {
                       if (typeof identifier !== 'object' || identifier === null) return;
                       if (!identifier.name || !identifier.value) return;
-                      event.setActorIdentifier(identifier.name, identifier.value);
+                      event.setIdentifier(identifier.name, identifier.value);
                   });
-              }
 
-              const relations = arg?.relations ?? arg?.rerelations;
-              if (relations && typeof relations === 'object') {
-                  Object.keys(relations).forEach(relationName => {
-                      event.setReference(relationName);
-                      Object.keys(relations[relationName]).forEach(identifierName => {
-                          event.setReferenceIdentifier(relationName, identifierName, relations[relationName][identifierName]);
+                  if (eventArg.actor?.entity) {
+                      event.setActor(eventArg.actor.entity);
+                      let identifiers = eventArg.actor?.identifiers;
+                      if (!Array.isArray(identifiers)) {
+                          identifiers = identifiers?.[eventArg.actor.entity] ?? identifiers;
+                      }
+                      normalizeIdentifiers(identifiers).forEach(identifier => {
+                          if (typeof identifier !== 'object' || identifier === null) return;
+                          if (!identifier.name || !identifier.value) return;
+                          event.setActorIdentifier(identifier.name, identifier.value);
                       });
-                  });
-              }
-              if (arg?.adjectives && typeof arg.adjectives === 'object') {
-                  Object.keys(arg.adjectives).forEach(adjectiveName => {
-                      event.addAdjective(adjectiveName, arg.adjectives[adjectiveName]);
-                  });
-              }
+                  }
+
+                  const relations = eventArg?.relations ?? eventArg?.rerelations;
+                  if (relations && typeof relations === 'object') {
+                      Object.keys(relations).forEach(relationName => {
+                          event.setReference(relationName);
+                          Object.keys(relations[relationName]).forEach(identifierName => {
+                              event.setReferenceIdentifier(relationName, identifierName, relations[relationName][identifierName]);
+                          });
+                      });
+                  }
+                  if (eventArg?.adjectives && typeof eventArg.adjectives === 'object') {
+                      Object.keys(eventArg.adjectives).forEach(adjectiveName => {
+                          event.addAdjective(adjectiveName, eventArg.adjectives[adjectiveName]);
+                      });
+                  }
+
+                  if (eventArg?.collections && typeof eventArg.collections === 'object') {
+                      Object.keys(eventArg.collections).forEach(collectionName => {
+                          applyCollectionConfig(event, collectionName, eventArg.collections[collectionName]);
+                      });
+                  }
+              };
 
-              if (arg?.collections && typeof arg.collections === 'object') {
-                  Object.keys(arg.collections).forEach(collectionName => {
-                      applyCollectionConfig(collectionName, arg.collections[collectionName]);
+              // Group form: payload carries an `events` array (and optionally a semantic `eventGroup` name).
+              // Each item is a standalone event spec; they are bundled into a CollecionesEventGroup so that
+              // shared group metadata (id + sibling clientEventIds) is materialised onto every event.
+              if (Array.isArray(arg.events)) {
+                  const group = new CollecionesEventGroup();
+                  let added = 0;
+                  arg.events.forEach(eventArg => {
+                      if (!eventArg || typeof eventArg !== 'object') return;
+                      if (!eventArg.entity || !eventArg.action) return;
+                      const event = group.addEvent();
+                      populateEvent(eventArg, event);
+                      added++;
                   });
+                  if (added === 0) return false;
+                  // Apply the semantic group name AFTER addEvent calls: each addEvent invalidates
+                  // group.groupId, so an override set earlier would be cleared by the loop above.
+                  if (typeof arg.eventGroup === 'string' && arg.eventGroup.length > 0) {
+                      group.groupId = arg.eventGroup;
+                  }
+                  tracker.trackGroup(group);
+                  return true;
               }
 
+              if (!arg.entity || !arg.action) return false;
+              const event = new CollecionesEvent();
+              populateEvent(arg, event);
               tracker.track(event);
               return true;
           };