@adobe/alloy 2.28.0 → 2.28.1-beta.0

package/libEs6/components/RulesEngine/createEventRegistry.js

@@ -0,0 +1,162 @@
+/*
+Copyright 2023 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { EventData, EventPayload, EventRecord, EventRegistry } from './types.js' */
+
+import { getActivityId, hasExperienceData, getDecisionProvider, createRestoreStorage, createSaveStorage, createEventPruner, generateEventHash } from "./utils/index.js";
+import { EVENT_TYPE_TRUE } from "../../constants/eventType.js";
+import { ADOBE_JOURNEY_OPTIMIZER } from "../../constants/decisionProvider.js";
+import { EVENT_HISTORY_STORAGE_KEY, EVENT_HISTORY_MAX_LENGTH, INSERT_OPERATION, INSERT_IF_NOT_EXISTS_OPERATION } from "./constants/index.js";
+
+/**
+ * Creates an event registry to track and manage events
+ * @param {Object} options - The options object
+ * @param {Object} options.storage - The storage object used to persist events
+ * @param {Object} options.logger - The logger object used for logging
+ * @returns {Object} The event registry interface
+ */
+export default ({
+  storage,
+  logger
+}) => {
+  let currentStorage = storage;
+  let save;
+
+  /** @type {EventRegistry} */
+  let eventRegistry;
+
+  /** @type {number} */
+  let eventRegistrySize;
+
+  /**
+   * Sets a new storage object for the event registry
+   * @param {Object} newStorage
+   */
+  const setStorage = newStorage => {
+    currentStorage = newStorage;
+    const restore = createRestoreStorage(currentStorage, EVENT_HISTORY_STORAGE_KEY);
+    save = createSaveStorage(currentStorage, EVENT_HISTORY_STORAGE_KEY);
+    [eventRegistry, eventRegistrySize] = restore({});
+    if (eventRegistrySize > EVENT_HISTORY_MAX_LENGTH) {
+      const eventPruner = createEventPruner();
+      eventRegistry = eventPruner(eventRegistry);
+      save(eventRegistry);
+    }
+  };
+  setStorage(storage);
+
+  /**
+   * Adds a single event to the event registry
+   * @param {EventData} event
+   * @param {string} operation
+   * @returns {EventRecord|undefined}
+   */
+  const addEvent = (event = {
+    eventType: null,
+    eventId: null
+  }, operation = INSERT_OPERATION) => {
+    const {
+      eventType,
+      eventId
+    } = event;
+    if (!eventType || !eventId) {
+      return undefined;
+    }
+    const eventHash = generateEventHash(event);
+    if (operation === INSERT_IF_NOT_EXISTS_OPERATION && eventRegistry[eventHash]) {
+      return undefined;
+    }
+    if (!eventRegistry[eventHash] || !Array.isArray(eventRegistry[eventHash].timestamps)) {
+      eventRegistry[eventHash] = {
+        timestamps: []
+      };
+    }
+    const timestamp = new Date().getTime();
+    eventRegistry[eventHash].timestamps.push(timestamp);
+    eventRegistry[eventHash].timestamps.sort();
+    logger.info("[Event History] Added event for", event, "with hash", eventHash, "and timestamp", timestamp);
+    save(eventRegistry);
+    return eventRegistry[eventHash];
+  };
+
+  /**
+   * Adds multiple events to the event registry
+   * @param {Array<EventPayload>} eventPayloads
+   * @returns {Array<EventRecord>}
+   */
+  const addEventPayloads = (eventPayloads = []) => eventPayloads.map(({
+    operation,
+    event
+  }) => addEvent(event, operation));
+
+  /**
+   * Processes and adds Experience Edge events to the registry
+   * @param {Object} event - The Experience Edge event object
+   * @returns {void}
+   */
+  const addExperienceEdgeEvent = event => {
+    const {
+      xdm
+    } = event.getContent();
+    if (!hasExperienceData(xdm)) {
+      return;
+    }
+    const {
+      _experience: {
+        decisioning: {
+          propositionEventType = {},
+          propositionAction: {
+            id: action
+          } = {},
+          propositions = []
+        } = {}
+      }
+    } = xdm;
+    Object.keys(propositionEventType).filter(eventType => propositionEventType[eventType] === EVENT_TYPE_TRUE).forEach(eventType => {
+      propositions.forEach(proposition => {
+        if (getDecisionProvider(proposition) !== ADOBE_JOURNEY_OPTIMIZER) {
+          return;
+        }
+        addEvent({
+          eventId: getActivityId(proposition),
+          eventType,
+          action
+        });
+      });
+    });
+  };
+
+  /**
+   * Retrieves an event from the registry based on type and ID
+   * @param {string} eventType - The type of the event to retrieve
+   * @param {string} eventId - The ID of the event to retrieve
+   * @returns {EventRecord|undefined} The event object if found, otherwise undefined
+   */
+  const getEvent = (eventType, eventId) => {
+    const h = generateEventHash({
+      eventType,
+      eventId
+    });
+    if (!eventRegistry[h]) {
+      return undefined;
+    }
+    return eventRegistry[h];
+  };
+  return {
+    addExperienceEdgeEvent,
+    addEvent,
+    addEventPayloads,
+    getEvent,
+    toJSON: () => eventRegistry,
+    setStorage
+  };
+};

package/libEs6/components/RulesEngine/createOnResponseHandler.js

@@ -0,0 +1,46 @@
+/*
+Copyright 2023 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { PERSONALIZATION_DECISIONS_HANDLE } from "../../constants/decisionProvider.js";
+import flattenObject from "../../utils/flattenObject.js";
+export default ({
+  renderDecisions,
+  decisionProvider,
+  applyResponse,
+  event,
+  personalization,
+  decisionContext
+}) => {
+  const context = {
+    ...flattenObject(event.getContent()),
+    ...decisionContext
+  };
+  return ({
+    response
+  }) => {
+    decisionProvider.addPayloads(response.getPayloadsByType(PERSONALIZATION_DECISIONS_HANDLE));
+
+    // only evaluate events that include a personalization query
+    if (!event.hasQuery()) {
+      return {
+        propositions: []
+      };
+    }
+    const propositions = decisionProvider.evaluate(context);
+    return applyResponse({
+      renderDecisions,
+      propositions,
+      event,
+      personalization
+    });
+  };
+};

package/libEs6/components/RulesEngine/createSubscribeRulesetItems.js

@@ -0,0 +1,129 @@
+/*
+Copyright 2023 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+import { arrayOf, callback as callbackType, objectOf, string } from "../../utils/validation/index.js";
+import createSubscription from "../../utils/createSubscription.js";
+import { getEventType, PropositionEventType } from "../../constants/propositionEventType.js";
+const validateOptions = ({
+  options
+}) => {
+  const validator = objectOf({
+    surfaces: arrayOf(string()).uniqueItems(),
+    schemas: arrayOf(string()).uniqueItems(),
+    callback: callbackType().required()
+  }).noUnknownFields();
+  return validator(options);
+};
+const getAnalyticsDetail = proposition => {
+  const {
+    id,
+    scope,
+    scopeDetails
+  } = proposition;
+  return {
+    id,
+    scope,
+    scopeDetails
+  };
+};
+export default ({
+  collect
+}) => {
+  let emitPropositions = () => undefined;
+  const collectedEventsThisSession = new Set();
+  const shouldAlwaysCollect = propositionEventType => [PropositionEventType.INTERACT, PropositionEventType.DISMISS].includes(propositionEventType);
+  const shouldCollect = (propositionEventType, analyticsMetaId, collectedEventsThisRequest) => {
+    const eventId = [propositionEventType, analyticsMetaId].join("-");
+    const result = !collectedEventsThisRequest.has(eventId) && (shouldAlwaysCollect(propositionEventType) || !collectedEventsThisSession.has(eventId));
+    collectedEventsThisRequest.add(eventId);
+    collectedEventsThisSession.add(eventId);
+    return result;
+  };
+  const collectEvent = (propositionEventType, propositions = []) => {
+    if (!(propositions instanceof Array)) {
+      return Promise.resolve();
+    }
+    if (!Object.values(PropositionEventType).includes(propositionEventType)) {
+      return Promise.resolve();
+    }
+    const decisionsMeta = [];
+    const collectedEventsThisRequest = new Set();
+    propositions.forEach(proposition => {
+      const analyticsMeta = getAnalyticsDetail(proposition);
+      if (!shouldCollect(propositionEventType, analyticsMeta.id, collectedEventsThisRequest)) {
+        return;
+      }
+      decisionsMeta.push(analyticsMeta);
+    });
+    return decisionsMeta.length > 0 ? collect({
+      decisionsMeta,
+      eventType: getEventType(propositionEventType),
+      documentMayUnload: true
+    }) : Promise.resolve();
+  };
+  const subscriptions = createSubscription();
+  const emissionPreprocessor = (params, propositions) => {
+    const {
+      surfacesFilter,
+      schemasFilter
+    } = params;
+    const result = {
+      propositions: propositions.filter(payload => surfacesFilter ? surfacesFilter.includes(payload.scope) : true).map(payload => {
+        const {
+          items = []
+        } = payload;
+        return {
+          ...payload,
+          items: items.filter(item => schemasFilter ? schemasFilter.includes(item.schema) : true)
+        };
+      }).filter(payload => payload.items.length > 0)
+    };
+    return [result, collectEvent];
+  };
+  subscriptions.setEmissionPreprocessor(emissionPreprocessor);
+  const run = ({
+    surfaces,
+    schemas,
+    callback
+  }) => {
+    const {
+      id,
+      unsubscribe
+    } = subscriptions.add(callback, {
+      surfacesFilter: surfaces instanceof Array ? surfaces : undefined,
+      schemasFilter: schemas instanceof Array ? schemas : undefined
+    });
+    emitPropositions(id);
+    return Promise.resolve({
+      unsubscribe
+    });
+  };
+  const optionsValidator = options => validateOptions({
+    options
+  });
+  const refresh = propositions => {
+    emitPropositions = subscriptionId => {
+      if (subscriptionId) {
+        subscriptions.emitOne(subscriptionId, propositions);
+        return;
+      }
+      subscriptions.emit(propositions);
+    };
+    emitPropositions();
+  };
+  return {
+    refresh,
+    command: {
+      optionsValidator,
+      run
+    }
+  };
+};

package/libEs6/components/RulesEngine/index.js

@@ -0,0 +1,151 @@
+/*
+Copyright 2023 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+import { noop, sanitizeOrgIdForCookieName } from "../../utils/index.js";
+import createOnResponseHandler from "./createOnResponseHandler.js";
+import createDecisionProvider from "./createDecisionProvider.js";
+import createApplyResponse from "./createApplyResponse.js";
+import createEventRegistry from "./createEventRegistry.js";
+import createContextProvider from "./createContextProvider.js";
+import createSubscribeRulesetItems from "./createSubscribeRulesetItems.js";
+import { CONTEXT_KEY, CONTEXT_EVENT_SOURCE, CONTEXT_EVENT_TYPE } from "./constants/index.js";
+import createEvaluateRulesetsCommand from "./createEvaluateRulesetsCommand.js";
+import { clearLocalStorage, createInMemoryStorage } from "./utils/storage.js";
+import { objectOf, boolean } from "../../utils/validation/index.js";
+import createCollect from "../../utils/createCollect.js";
+import { mergeDecisionsMeta } from "../../utils/event.js";
+const createRulesEngine = ({
+  config,
+  eventManager,
+  createNamespacedStorage,
+  consent,
+  getBrowser,
+  logger
+}) => {
+  const {
+    orgId,
+    personalizationStorageEnabled
+  } = config;
+  const collect = createCollect({
+    eventManager,
+    mergeDecisionsMeta
+  });
+  const storage = createNamespacedStorage(`${sanitizeOrgIdForCookieName(orgId)}.decisioning.`);
+  if (!personalizationStorageEnabled) {
+    clearLocalStorage(storage.persistent);
+  }
+  const eventRegistry = createEventRegistry({
+    storage: createInMemoryStorage(),
+    logger
+  });
+  const decisionProvider = createDecisionProvider({
+    eventRegistry
+  });
+  const contextProvider = createContextProvider({
+    eventRegistry,
+    window,
+    getBrowser
+  });
+  const evaluateRulesetsCommand = createEvaluateRulesetsCommand({
+    contextProvider,
+    decisionProvider
+  });
+  const subscribeRulesetItems = createSubscribeRulesetItems({
+    collect
+  });
+  let applyResponse;
+  return {
+    lifecycle: {
+      onDecision({
+        propositions
+      }) {
+        subscribeRulesetItems.refresh(propositions);
+      },
+      onComponentsRegistered(tools) {
+        applyResponse = createApplyResponse({
+          lifecycle: tools.lifecycle,
+          eventRegistry
+        });
+        if (personalizationStorageEnabled) {
+          consent.awaitConsent().then(() => {
+            eventRegistry.setStorage(storage.persistent);
+          }).catch(() => {
+            if (storage) {
+              clearLocalStorage(storage.persistent);
+            }
+          });
+        }
+      },
+      onBeforeEvent({
+        event,
+        renderDecisions,
+        personalization = {},
+        onResponse = noop
+      }) {
+        const {
+          decisionContext = {}
+        } = personalization;
+        onResponse(createOnResponseHandler({
+          renderDecisions,
+          decisionProvider,
+          applyResponse,
+          event,
+          personalization,
+          decisionContext: contextProvider.getContext({
+            [CONTEXT_KEY.TYPE]: CONTEXT_EVENT_TYPE.EDGE,
+            [CONTEXT_KEY.SOURCE]: CONTEXT_EVENT_SOURCE.REQUEST,
+            ...decisionContext
+          })
+        }));
+      },
+      onBeforeRequest({
+        request
+      }) {
+        const payload = request.getPayload().toJSON();
+        const {
+          events = []
+        } = payload;
+        if (events.length === 0) {
+          return;
+        }
+        events.forEach(event => eventRegistry.addExperienceEdgeEvent(event));
+      }
+    },
+    commands: {
+      evaluateRulesets: {
+        run: ({
+          renderDecisions,
+          personalization = {}
+        }) => {
+          const {
+            decisionContext = {}
+          } = personalization;
+          return evaluateRulesetsCommand.run({
+            renderDecisions,
+            decisionContext: {
+              [CONTEXT_KEY.TYPE]: CONTEXT_EVENT_TYPE.RULES_ENGINE,
+              [CONTEXT_KEY.SOURCE]: CONTEXT_EVENT_SOURCE.REQUEST,
+              ...decisionContext
+            },
+            applyResponse
+          });
+        },
+        optionsValidator: evaluateRulesetsCommand.optionsValidator
+      },
+      subscribeRulesetItems: subscribeRulesetItems.command
+    }
+  };
+};
+createRulesEngine.namespace = "RulesEngine";
+createRulesEngine.configValidators = objectOf({
+  personalizationStorageEnabled: boolean().default(false)
+});
+export default createRulesEngine;

package/libEs6/components/RulesEngine/types.js

@@ -0,0 +1,76 @@
+/**
+ * @typedef {Record<string, EventRecord>} EventRegistry
+ */
+
+/**
+ * @typedef {object} EventPayload
+ * @property {string} operation
+ * @property {EventData} event
+ */
+
+/**
+ * @typedef {Record<string, string>} EventData
+ * @property {string} eventType
+ * @property {string} eventId
+ * @property {string} [action]
+ */
+
+/**
+ * @typedef {object} EventRecord
+ * @property {Array<number>} timestamps
+ */
+
+/**
+ * @typedef {Array<Proposition>} PropositionList
+ */
+
+/**
+ * @typedef {Object} Proposition
+ * @property {string} id
+ * @property {string} scope
+ * @property {ScopeDetails} scopeDetails
+ * @property {Array<PropositionItem>} items
+ */
+
+/**
+ * @typedef {Object} ScopeDetails
+ * @property {string} decisionProvider
+ * @property {string} correlationID
+ * @property {Characteristics} characteristics
+ * @property {number} rank
+ * @property {Activity} activity
+ */
+
+/**
+ * @typedef {Object} Characteristics
+ * @property {string} eventToken
+ */
+
+/**
+ * @typedef {Object} Activity
+ * @property {string} id
+ * @property {number} priority
+ * @property {Array<string>} matchedSurfaces
+ */
+
+/**
+ * @typedef {Object} PropositionItem
+ * @property {string} schema
+ * @property {EventHistoryOperationData|Object} data
+ * @property {string} id
+ */
+
+/**
+ * @typedef {Object} EventHistoryOperationData
+ * @property {string} operation
+ * @property {RulesEventPayload} content
+ * @property {number} qualifiedDate
+ */
+
+/**
+ * @typedef {Record<string, string>} RulesEventPayload
+ * @property {string} iam.eventType
+ * @property {string} iam.id
+ */
+
+export const Types = {};

package/libEs6/components/RulesEngine/utils/createEventPruner.js

@@ -0,0 +1,54 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+import { EVENT_HISTORY_MAX_RECORDS, EVENT_HISTORY_RETENTION_PERIOD } from "../constants/index.js";
+import getExpirationDate from "./getExpirationDate.js";
+
+/**
+ * Creates an event pruner function that filters events based on retention period and maximum count
+ *
+ * @param {number} [retentionPeriod=EVENT_HISTORY_RETENTION_PERIOD] - The retention period in days
+ * @param {number} [limit=EVENT_HISTORY_MAX_RECORDS] - Maximum number of events to keep
+ * @returns {Function} A function that takes an events object and returns a pruned version of it
+ * @param {Object} events - Object containing events with timestamps
+ * @returns {Object} Pruned events object with events filtered by retention period and limited to max count
+ */
+export default (retentionPeriod = EVENT_HISTORY_RETENTION_PERIOD, limit = EVENT_HISTORY_MAX_RECORDS) => events => {
+  let eventsWithHash = Object.entries(events).reduce((accumulator, [key, {
+    timestamps = []
+  }]) => {
+    timestamps.forEach(timestamp => {
+      accumulator.push({
+        key,
+        timestamp
+      });
+    });
+    return accumulator;
+  }, []);
+  const expirationDate = getExpirationDate(retentionPeriod);
+  eventsWithHash = eventsWithHash.filter(({
+    timestamp
+  }) => timestamp >= expirationDate);
+  eventsWithHash.sort((a, b) => a.timestamp - b.timestamp);
+  eventsWithHash = eventsWithHash.slice(-limit);
+  return eventsWithHash.reduce((accumulator, {
+    key,
+    timestamp
+  }) => {
+    if (!accumulator[key]) {
+      accumulator[key] = {
+        timestamps: []
+      };
+    }
+    accumulator[key].timestamps.push(timestamp);
+    return accumulator;
+  }, {});
+};

package/libEs6/components/RulesEngine/utils/extractPayloadsFromEventHistoryOperations.js

@@ -0,0 +1,48 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { PropositionList,  EventPayload } from '../types.js' */
+import { EVENT_HISTORY_OPERATION } from "../../../constants/schema.js";
+
+/**
+ * Extracts event history operations from a proposition list and filters them out.
+ *
+ * This function processes the provided proposition list by:
+ * 1. Identifying items with the EVENT_HISTORY_OPERATION schema
+ * 2. Converting these items into event payloads and tie them with the operation
+ * 3. Removing these items from the original propositions
+ * 4. Returning an array of the extracted event payloads
+ *
+ * @param {PropositionList} propositionList - The list of propositions to process
+ * @returns {Array<EventPayload>} Array of extracted event payloads with operation
+ */
+export default propositionList => {
+  const result = [];
+  propositionList.forEach(proposition => {
+    const filteredItems = [];
+    proposition.items.forEach(item => {
+      if (item.schema === EVENT_HISTORY_OPERATION) {
+        result.push({
+          operation: item.data.operation,
+          event: {
+            eventId: item.data.content["iam.id"],
+            eventType: item.data.content["iam.eventType"]
+          }
+        });
+      } else {
+        filteredItems.push(item);
+      }
+    });
+    proposition.items = filteredItems;
+  });
+  return result;
+};

package/libEs6/components/RulesEngine/utils/generateEventHash.js

@@ -0,0 +1,33 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+import fnv1a32Hex from "../../../utils/fnv1a32Hex.js";
+
+/**
+ * Generates an event history hash from an object by removing keys with empty values, sorting the keys,
+ * converting the object to a string, and hashing the string.
+ * @param {Object} o - The object to process.
+ * @returns {string} - The hash of the processed object.
+ */
+export default o => {
+  const obj = structuredClone(o);
+  const objectString = Object.keys(obj).sort().reduce((result, key) => {
+    const value = obj[key];
+
+    // eslint-disable-next-line eqeqeq
+    if (value == undefined || value === "") {
+      return result;
+    }
+    result += `${key}:${value}`;
+    return result;
+  }, "");
+  return fnv1a32Hex(objectString);
+};