@adobe/alloy 2.29.0-beta.1 → 2.29.0-beta.13

package/libEs6/core/injectCreateResponse.js

@@ -9,12 +9,21 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 OF ANY KIND, either express or implied. See the License for the specific language
 governing permissions and limitations under the License.
 */
+
+/** @import { ResponseCreator } from './types.js' */
+
 import { ADOBE_EDGE } from "../constants/httpHeaderNames.js";
 
 /**
  * Creates a representation of a gateway response with the addition of
  * helper methods.
- * @returns Response
+ *
+ * @function
+ *
+ * @param {object} options
+ * @param {function(string): Object} options.extractEdgeInfo
+ *
+ * @returns {ResponseCreator}
  */
 export default ({
   extractEdgeInfo
@@ -27,15 +36,10 @@ export default ({
     errors = [],
     warnings = []
   } = content;
-
-  /**
-   * Response object.
-   * @typedef {Object} Response
-   */
   return {
     /**
      * Returns matching fragments of the response by type.
-     * @param {String} type A string with the current format: <namespace:action>
+     * @param {string} type A string with the current format: <namespace:action>
      *
      * @example
      * getPayloadsByType("identity:persist")

package/libEs6/core/types.js

@@ -1,16 +1,106 @@
 /**
  * @typedef {object} AlloyMonitor
- * @property {function(data): void} [onBeforeLog]
- * @property {function(data): void} [onInstanceCreated]
- * @property {function(data): void} [onInstanceConfigured]
- * @property {function(data): void} [onBeforeCommand]
- * @property {function(data): void} [onCommandResolved]
- * @property {function(data): void} [onCommandRejected]
- * @property {function(data): void} [onBeforeNetworkRequest]
- * @property {function(data): void} [onNetworkResponse]
- * @property {function(data): void} [onNetworkError]
- * @property {function(data): void} [onContentHiding]
- * @property {function(data): void} [onContentRendering]
+ * @property {function(any): void} [onBeforeLog]
+ * @property {function(any): void} [onInstanceCreated]
+ * @property {function(any): void} [onInstanceConfigured]
+ * @property {function(any): void} [onBeforeCommand]
+ * @property {function(any): void} [onCommandResolved]
+ * @property {function(any): void} [onCommandRejected]
+ * @property {function(any): void} [onBeforeNetworkRequest]
+ * @property {function(any): void} [onNetworkResponse]
+ * @property {function(any): void} [onNetworkError]
+ * @property {function(any): void} [onContentHiding]
+ * @property {function(any): void} [onContentRendering]
+ */
+
+/**
+ * @typedef {object} Logger
+ * @property {boolean} enabled
+ * @property {function(any): void} logOnInstanceCreated
+ * @property {function(any): void} logOnInstanceConfigured
+ * @property {function(any): void} logOnBeforeCommand
+ * @property {function(any): void} logOnCommandResolved
+ * @property {function(any): void} logOnCommandRejected
+ * @property {function(any): void} logOnBeforeNetworkRequest
+ * @property {function(any): void} logOnNetworkResponse
+ * @property {function(any): void} logOnNetworkError
+ * @property {function(any): void} logOnContentHiding
+ * @property {function(any): void} logOnContentRendering
+ * @property {function(...any): void} info
+ * @property {function(...any): void} warn
+ * @property {function(...any): void} error
+ */
+
+/**
+ * @typedef {object} Event
+ * @property {function(): boolean} hasQuery
+ * @property {function(): object} getContent
+ * @property {function(object): void} setUserXdm
+ * @property {function(object): void} setUserData
+ * @property {function(object): void} mergeXdm
+ * @property {function(object): void} mergeData
+ * @property {function(object): void} mergeMeta
+ * @property {function(object): void} mergeQuery
+ * @property {function(): void} documentMayUnload
+ * @property {function(function=): void} finalize
+ * @property {function(): boolean} getDocumentMayUnload
+ * @property {function(): boolean} isEmpty
+ * @property {function(): boolean} shouldSend
+ * @property {function(): string|undefined} getViewName
+ * @property {function(): object} toJSON
+ */
+
+/**
+ * @typedef {object} SendEventOptions
+ * @property {object} [edgeConfigOverrides]
+configuration
+ * @property {boolean} [renderDecisions]
+ * @property {string[]} [decisionScopes]
+ * @property {object} [decisionContext]
+ * @property {object} [personalization]
+ * @property {object} [mediaOptions]
+ */
+
+/**
+ * @typedef {object} ApplyResponseOptions
+ * @property {boolean} [renderDecisions=false]
+ * @property {object} [decisionContext={}]
+ * @property {object} [responseHeaders={}]
+ * @property {object} [responseBody={handle:[]}]
+ * @property {object} [personalization]
+ */
+
+/**
+ * @typedef {object} EventManager
+ * @property {function(): Event} createEvent
+ * @property {function(Event, SendEventOptions=): Promise<any>} sendEvent
+ * @property {function(Event, ApplyResponseOptions=): Promise<any>} applyResponse
+ */
+
+/**
+ * @typedef {Object} ResponseContent
+ * @property {Array<{type: string, payload: Array<Object>}>} [handle] - Array of response fragments with type and payload
+ * @property {Array<object>} [errors] - Array of error objects
+ * @property {Array<object>} [warnings] - Array of warning objects
+ */
+
+/**
+ * @typedef {Object} ResponseFragment
+ * @property {string} type - Fragment type in format "<namespace:action>"
+ * @property {any} payload - Fragment payload data
+ */
+
+/**
+ * @typedef {Object} Response
+ * @property {function(string): Array<any>} getPayloadsByType - Returns matching fragments by type (e.g., "identity:persist")
+ * @property {function(): Array<object>} getErrors - Returns all error objects from the response
+ * @property {function(): Array<object>} getWarnings - Returns all warning objects from the response
+ * @property {function(): object} getEdge - Returns object containing regionId from x-adobe-edge header
+ * @property {function(): ResponseContent} toJSON
+ */
+
+/**
+ * @typedef {function({content?: ResponseContent, getHeader: function(string): string|undefined}): Response} ResponseCreator
  */
 
 export const Types = {};

package/libEs6/utils/bytes.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.
+*/
+
+/**
+ * Takes a base64 string of bytes and returns a Uint8Array.
+ * @param {string} base64String
+ * @returns {Uint8Array}
+ */
+export const base64ToBytes = base64String => {
+  // Add padding if needed
+  const padding = "=".repeat((4 - base64String.length % 4) % 4);
+
+  // Convert URL-safe base64 to regular base64
+  const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const binString = atob(base64);
+  return Uint8Array.from(binString, m => m.codePointAt(0));
+};
+
+/**
+ * Takes a Uint8Array and returns a base64 string.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export const bytesToBase64 = bytes => btoa(String.fromCharCode(...bytes));

package/libEs6/{components/Identity → utils}/createDecodeKndctrCookie.js

@@ -10,7 +10,8 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 /* eslint-disable no-bitwise */
-import { getNamespacedCookieName } from "../../utils/index.js";
+import { getNamespacedCookieName } from "./index.js";
+import { base64ToBytes } from "./bytes.js";
 
 // #region decode protobuf
 
@@ -26,39 +27,39 @@ import { getNamespacedCookieName } from "../../utils/index.js";
  * and https://git.corp.adobe.com/experience-edge/konductor/blob/master/feature-identity/src/main/kotlin/com/adobe/edge/features/identity/data/StoredIdentity.kt#L16
 
  * syntax = "proto3";
- * 
+ *
  * // Device-level identity for Experience Edge
  * message Identity {
  *   // The Experience Cloud ID value
  *   string ecid = 1;
- * 
+ *
  *   IdentityMetadata metadata = 10;
- * 
+ *
  *   // Used only in the 3rd party domain context.
  *   // It stores the UNIX timestamp and some metadata about the last identity sync triggered by Experience Edge.
  *   int64 last_sync = 20;
  *   int64 sync_hash = 21;
  *   int32 id_sync_container_id = 22;
- * 
+ *
  *   // UNIX timestamp when the Identity was last returned in a `state:store` instruction.
  *   // The Identity is written at most once every 24h with a large TTL, to ensure it does not expire.
  *   int64 write_time = 30;
  * }
- * 
+ *
  * message IdentityMetadata {
  *   // UNIX timestamp when this identity was minted.
  *   int64 created_at = 1;
- * 
+ *
  *   // Whether or not the identity is random (new) or based on an existing seed.
  *   bool is_new = 2;
- * 
+ *
  *   // Type of device for which the identity was generated.
  *   // 0 = UNKNOWN, 1 = BROWSER, 2 = MOBILE
  *   int32 device_type = 3;
- * 
+ *
  *   // The Experience Edge region in which the identity was minted.
  *   string region = 5;
- * 
+ *
  *   // More details on the source of the ECID identity.
  *   // Invariant: when `is_new` = true, the source must be set to `RANDOM`.
  *   // 0 = RANDOM, 1 = THIRD_PARTY_ID, 2 = FIRST_PARTY_ID, 3 = RECEIVED_IN_REQUEST
@@ -220,15 +221,6 @@ const decodeKndctrProtobuf = buffer => {
   throw new Error("No ECID found in cookie.");
 };
 
-/**
- * takes a base64 string of bytes and returns a Uint8Array
- * @param {string} base64
- * @returns {Uint8Array}
- */
-const base64ToBytes = base64 => {
-  const binString = atob(base64);
-  return Uint8Array.from(binString, m => m.codePointAt(0));
-};
 // #endregion
 
 // #region decode cookie

package/libEs6/utils/createLoggingCookieJar.js

@@ -10,6 +10,20 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
+/** @import { Logger } from '../core/types.js' */
+/** @import { CookieJar } from './types.js' */
+
+/**
+ * Creates a logging wrapper around a cookie jar that logs cookie operations.
+ *
+ * @function
+ *
+ * @param {object} options
+ * @param {Logger} options.logger
+ * @param {CookieJar} options.cookieJar
+ *
+ * @returns {CookieJar}
+ */
 export default ({
   logger,
   cookieJar
@@ -22,7 +36,7 @@ export default ({
         value,
         ...options
       });
-      cookieJar.set(key, value, options);
+      return cookieJar.set(key, value, options);
     }
   };
 };

package/libEs6/utils/createMerger.js

@@ -15,10 +15,11 @@ import deepAssign from "./deepAssign.js";
 /**
  * Creates a function that, when passed an object of updates, will merge
  * the updates onto the current value of a payload property.
- * @param {Object} content The base object to modify
- * @param {String } key The property to merge updates into. This
- * can be a dot-notation property path.
- * @returns {Function}
+ *
+ * @param {object} content The base object to modify
+ * @param {string} key The property to merge updates into. This can be a dot-notation property path.
+ *
+ * @returns {function(object): void}
  */
 export default (content, key) => updates => {
   const propertyPath = key.split(".");

package/libEs6/utils/index.js

@@ -12,6 +12,7 @@ governing permissions and limitations under the License.
 
 // Please keep in alphabetical order.
 export { default as assignConcatArrayValues } from "./assignConcatArrayValues.js";
+export { base64ToBytes, bytesToBase64 } from "./bytes.js";
 export { default as clone } from "./clone.js";
 export { default as cookieJar } from "./cookieJar.js";
 export { default as createMerger } from "./createMerger.js";

package/libEs6/utils/injectStorage.js

@@ -10,7 +10,18 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
+/** @import { Storage, StorageCreator } from './types.js' */
+
 import baseNamespace from "../constants/namespace.js";
+
+/**
+ * Creates a storage interface for a specific storage type with namespaced keys.
+ *
+ * @param {Object} context - The context object (typically window) that provides storage APIs.
+ * @param {string} storageType - The type of storage to use ('localStorage' or 'sessionStorage').
+ * @param {string} namespace - The namespace prefix to prepend to all storage keys.
+ * @returns {Storage}
+ */
 const getStorageByType = (context, storageType, namespace) => {
   // When storage is disabled on Safari, the mere act of referencing
   // window.localStorage or window.sessionStorage throws an error.
@@ -59,6 +70,15 @@ const getStorageByType = (context, storageType, namespace) => {
     }
   };
 };
+
+/**
+ * Creates a storage factory function that provides access to both session and persistent storage
+ * with namespaced keys. This is a higher-order function that returns a function which can be
+ * used to create storage instances with additional namespace suffixes.
+ *
+ * @param {Object} context - The context object (typically window) that provides storage APIs.
+ * @returns {StorageCreator}
+ */
 export default context => additionalNamespace => {
   const finalNamespace = baseNamespace + additionalNamespace;
   return {

package/libEs6/utils/request/createDataCollectionRequestPayload.js

@@ -9,22 +9,33 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 OF ANY KIND, either express or implied. See the License for the specific language
 governing permissions and limitations under the License.
 */
+
+/** @import { DataCollectionRequestPayload } from './types.js' */
+
 import createRequestPayload from "./createRequestPayload.js";
 import createAddIdentity from "./createAddIdentity.js";
 import createHasIdentity from "./createHasIdentity.js";
+
+/**
+ * @function
+ *
+ * @returns {DataCollectionRequestPayload}
+ */
 export default () => {
   const content = {};
-  const payload = createRequestPayload({
+  const requestPayload = createRequestPayload({
     content,
     addIdentity: createAddIdentity(content),
     hasIdentity: createHasIdentity(content)
   });
-  payload.addEvent = event => {
-    content.events = content.events || [];
-    content.events.push(event);
-  };
-  payload.getDocumentMayUnload = () => {
-    return (content.events || []).some(event => event.getDocumentMayUnload());
+  return {
+    ...requestPayload,
+    addEvent: event => {
+      content.events = content.events || [];
+      content.events.push(event);
+    },
+    getDocumentMayUnload: () => {
+      return (content.events || []).some(event => event.getDocumentMayUnload());
+    }
   };
-  return payload;
 };

package/libEs6/utils/request/createRequest.js

@@ -10,9 +10,37 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
+/** @import { Request, RequestPayload } from './types.js' */
+
 import { uuid } from "../index.js";
 
-// This provides the base functionality that all types of requests share.
+/**
+ * Creates a request object with methods to access and modify request properties.
+ *
+ * @function
+ *
+ * @param {Object} options
+ * @param {RequestPayload} options.payload
+ * @param {function({isIdentityEstablished: boolean}): string} options.getAction
+ * @param {function({isIdentityEstablished: boolean}): boolean} options.getUseSendBeacon
+ * @param {string} [options.datastreamIdOverride]
+ * @param {string} [options.edgeSubPath]
+ *
+ * @returns {Request}
+ *
+ * @example
+ * const request = createRequest({
+ *   payload: { event: 'pageView' },
+ *   getAction: ({ isIdentityEstablished }) => isIdentityEstablished ? 'send' : 'queue',
+ *   getUseSendBeacon: ({ isIdentityEstablished }) => isIdentityEstablished,
+ *   datastreamIdOverride: 'custom-datastream-id',
+ *   edgeSubPath: 'custom/path'
+ * });
+ *
+ * console.log(request.getId()); // Returns unique UUID
+ * request.setIsIdentityEstablished();
+ * console.log(request.getAction()); // Returns action based on identity status
+ */
 export default options => {
   const {
     payload,

package/libEs6/utils/request/createRequestPayload.js

@@ -10,22 +10,85 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
+/** @import { RequestPayload, Identity } from './types.js' */
+
 import { createMerger, prepareConfigOverridesForEdge } from "../index.js";
 
-// This provides the base functionality that all types of
-// request payloads share.
+/**
+ * createMerger creates a function that does a deep merge. Example:
+ * ```js
+ * payload.mergeConfigOverride({
+ *   com_adobe_analytics: {
+ *     reportSuites: ["reportSuite1"],
+ *   },
+ * });
+ *
+ * payload.mergeConfigOverride({
+ *   com_adobe_analytics: {
+ *     enabled: false,
+ *   },
+ * });
+ *
+ *
+ * // payload.meta.configOverrides is now:
+ * // {
+ * //   com_adobe_analytics: {
+ * //     enabled: false,
+ * //     reportSuites: ["reportSuite1"],
+ * //   },
+ * // }
+ * ```
+ * however, we need the result to be:
+ * ```js
+ * // {
+ * //   com_adobe_analytics: {
+ * //     enabled: false,
+ * //   },
+ * // }
+ * ```
+ * aka a shallow merge, where the second object overwrites the first.
+ * This is because order matters and we don't want to send reportSuites when something is
+ * disabled.
+ * This function does that.
+ *
+ * @param {Object} content
+ * @param {string} key
+ * @returns {(updates: Object) => void}
+ */
+const createMergeConfigOverride = (content, key) => updates => {
+  const propertyPath = key.split(".");
+  const hostObjectForUpdates = propertyPath.reduce((obj, propertyName) => {
+    obj[propertyName] = obj[propertyName] || {};
+    return obj[propertyName];
+  }, content);
+  Object.assign(hostObjectForUpdates, updates);
+};
+
+/**
+ * Creates a request payload object with methods for merging different types of data.
+ * This provides the base functionality that all types of request payloads share.
+ *
+ * @function
+ *
+ * @param {Object} options
+ * @param {Object} options.content
+ * @param {function(string, Identity): void} options.addIdentity
+ * @param {function(string):  boolean} options.hasIdentity
+ *
+ * @returns {RequestPayload}
+ */
 export default options => {
   const {
     content,
     addIdentity,
     hasIdentity
   } = options;
-  const mergeConfigOverride = createMerger(content, "meta.configOverrides");
+  const mergeConfigOverrides = createMergeConfigOverride(content, "meta.configOverrides");
   return {
     mergeMeta: createMerger(content, "meta"),
     mergeState: createMerger(content, "meta.state"),
     mergeQuery: createMerger(content, "query"),
-    mergeConfigOverride: updates => mergeConfigOverride(prepareConfigOverridesForEdge(updates)),
+    mergeConfigOverride: updates => mergeConfigOverrides(prepareConfigOverridesForEdge(updates)),
     addIdentity,
     hasIdentity,
     toJSON() {

package/libEs6/utils/request/types.js

@@ -0,0 +1,49 @@
+/**
+ * Request object with methods to access and modify request properties.
+ *
+ * @typedef {Object} Request
+ * @property {function(): string} getId
+ * @property {function(): RequestPayload} getPayload
+ * @property {function({isIdentityEstablished: boolean}): string}  getAction
+ * @property {function(): string|undefined} getDatastreamIdOverride
+ * @property {Function} getUseSendBeacon
+ * @property {function(): string|undefined} getEdgeSubPath
+ * @property {Function} getUseIdThirdPartyDomain
+ * @property {Function} setUseIdThirdPartyDomain
+ * @property {Function} setIsIdentityEstablished
+ */
+
+/**
+ * Request payload object with methods for merging different types of data.
+ *
+ * @typedef {Object} RequestPayload
+ * @property {function(object): void} mergeMeta
+ * @property {function(object): void} mergeState
+ * @property {function(object): void} mergeQuery
+ * @property {function(object): void} mergeConfigOverride
+ * @property {function(string, Identity): void} options.addIdentity
+ * @property {function(string): boolean} options.hasIdentity
+ * @property {function(): object} toJSON
+ */
+
+/**
+ * Request payload object with methods for merging different types of data.
+ *
+ * @typedef {Object} DataCollectionRequestPayload
+ * @property {function(object): void} mergeMeta
+ * @property {function(object): void} mergeState
+ * @property {function(object): void} mergeQuery
+ * @property {function(object): void} mergeConfigOverride
+ * @property {function(string, Identity): void} options.addIdentity
+ * @property {function(string): boolean} options.hasIdentity
+ * @property {function(object): void} addEvent
+ * @property {function(): boolean} getDocumentMayUnload
+ * @property {function(): object} toJSON
+ */
+
+/**
+ * @typedef {Object} Identity
+ * @property {string} id
+ */
+
+export const Types = {};

package/libEs6/utils/types.js

@@ -0,0 +1,36 @@
+/**
+ * @typedef {Object} Storage
+ * @property {function(string): string|null} getItem
+ * @property {function(string, string): void} setItem
+ * @property {function(): void} clear
+ */
+
+/**
+ * @typedef {Object} CookieAttributes
+ * @property {number|Date} [expires] - Cookie expiration (number of days or Date object)
+ * @property {string} [path] - Cookie path (default: "/")
+ * @property {string} [domain] - Cookie domain
+ * @property {boolean} [secure] - Requires HTTPS transmission
+ * @property {"strict"|"lax"|"none"} [sameSite] - SameSite attribute
+ */
+
+/**
+ * @typedef {Object} CookieConverter
+ * @property {function(string, string): string} [read] - Custom decoder function
+ * @property {function(string, string): string} [write] - Custom encoder function
+ */
+
+/**
+ * @typedef {Object} CookieJar
+ * @property {function(string): string|undefined} get - Get cookie value by name, or get all cookies as object if no name provided
+ * @property {function(): Object<string, string>} get - Get all cookies as key-value object when called with no arguments
+ * @property {function(string, string, CookieAttributes=): string|undefined} set - Set cookie with optional attributes
+ * @property {function(string, CookieAttributes=): void} remove - Remove cookie with optional attributes (must match set attributes)
+ * @property {function(CookieConverter): CookieJar} withConverter - Create new instance with custom encoding/decoding
+ */
+
+/**
+ * @typedef {function(string): { session: Storage, persistent: Storage }} StorageCreator
+ */
+
+export const Types = {};