@adobe/alloy 2.29.0-beta.5 → 2.29.0

package/libEs6/core/consent/createConsentStateMachine.js

@@ -10,18 +10,54 @@ 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 { ConsentStateMachineUtils, ConsentStateMachine } from './types.js' */
+
 import { defer } from "../../utils/index.js";
 export const DECLINED_CONSENT = "The user declined consent.";
 export const DECLINED_CONSENT_ERROR_CODE = "declinedConsent";
 export const CONSENT_SOURCE_DEFAULT = "default";
 export const CONSENT_SOURCE_INITIAL = "initial";
 export const CONSENT_SOURCE_NEW = "new";
+
+/**
+ * @private
+ * @param {string} errorMessage
+ * @returns {Error}
+ */
 const createDeclinedConsentError = errorMessage => {
   const error = new Error(errorMessage);
   error.code = DECLINED_CONSENT_ERROR_CODE;
   error.message = errorMessage;
   return error;
 };
+
+/**
+ * Creates a consent state machine that manages user consent preferences and
+ * coordinates deferred operations that require consent.
+ *
+ * The state machine supports the following states:
+ * - "in": User has provided consent (with default or explicit consent)
+ * - "out": User has declined consent (with default or explicit decline)
+ * - "pending": Consent decision is awaiting user input
+ *
+ * @param {object} options
+ * @param {Logger} options.logger
+ *
+ * @returns {ConsentStateMachine}
+ *
+ * @example
+ * const consentStateMachine = createConsentStateMachine({ logger });
+ *
+ * // Set consent state
+ * consentStateMachine.in('new');
+ *
+ * // Wait for consent
+ * await consentStateMachine.awaitConsent();
+ *
+ * // Check current state
+ * const { state, wasSet } = consentStateMachine.current();
+ */
 export default ({
   logger
 }) => {

package/libEs6/core/consent/types.js

@@ -0,0 +1,21 @@
+/**
+ * @typedef {Object} ConsentStateMachine
+ * @property {function(string): void} in
+ * @property {function(string): void} out
+ * @property {function(string): void} pending
+ * @property {function(boolean=): Promise<void>} awaitConsent
+ * @property {function(): Promise<void>} withConsent
+ * @property {function(): {state: string, wasSet: boolean}} current
+ */
+
+/**
+ * @typedef {Object} ConsentManager
+ * @property {function(Object, Object): void} initializeConsent
+ * @property {function(Object): void} setConsent
+ * @property {function(): void} suspend
+ * @property {function(): Promise<void>} awaitConsent
+ * @property {function(): Promise<void>} withConsent
+ * @property {function(): {state: string, wasSet: boolean}} current
+ */
+
+export const Types = {};

package/libEs6/core/edgeNetwork/injectSendEdgeNetworkRequest.js

@@ -10,6 +10,9 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
+/** @import { EdgeRequestExecutor } from './types.js' */
+/** @import { ResponseCreator } from '../types.js' */
+
 import { ID_THIRD_PARTY as ID_THIRD_PARTY_DOMAIN } from "../../constants/domain.js";
 import apiVersion from "../../constants/apiVersion.js";
 import { createCallbackAggregator, noop } from "../../utils/index.js";
@@ -19,6 +22,23 @@ import handleRequestFailure from "./handleRequestFailure.js";
 const isDemdexBlockedError = (error, request) => {
   return request.getUseIdThirdPartyDomain() && isNetworkError(error);
 };
+
+/**
+ * @function
+ *
+ * @param {object} options
+ * @param {{edgeDomain: string, edgeBasePath: string, datastreamId: string}} options.config
+ * @param {object} options.lifecycle
+ * @param {object} options.cookieTransfer
+ * @param {function(object): Promise<Object>} options.sendNetworkRequest
+ * @param {ResponseCreator} options.createResponse
+ * @param {function(object): void} options.processWarningsAndErrors
+ * @param {function(): string|undefined} options.getLocationHint
+ * @param {function(): string} options.getAssuranceValidationTokenParams
+
+ *
+ * @returns {EdgeRequestExecutor} A function that sends edge network requests with lifecycle management
+ */
 export default ({
   config,
   lifecycle,

package/libEs6/core/edgeNetwork/types.js

@@ -0,0 +1,7 @@
+/** @import { Request } from '../../utils/request/types.js' */
+
+/**
+ * @typedef {function({request: Request, runOnResponseCallbacks?: function(): void, runOnRequestFailureCallbacks?: function(): void}): Promise<Object>} EdgeRequestExecutor
+ */
+
+export const Types = {};

package/libEs6/core/identity/createIdentity.js

@@ -10,7 +10,45 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
+/** @import { IdentityManager } from './types.js' */
+/** @import { Logger } from '../types.js' */
+/** @import { CookieJar } from '../../utils/types.js' */
+
 import createDecodeKndctrCookie from "../../utils/createDecodeKndctrCookie.js";
+
+/**
+ * Creates an identity management service for handling ECID (Experience Cloud ID) resolution and tracking.
+ *
+ * This factory function creates an identity manager service that manages the state of identity resolution,
+ * provides methods to check for existing identity cookies, and handles the asynchronous nature
+ * of identity acquisition in Adobe Experience Platform Web SDK.
+ *
+ * @function
+ *
+ * @param {Object} options
+ * @param {Logger} options.logger
+ * @param {CookieJar} options.loggingCookieJar
+ * @param {{orgId: string}} options.config
+ *
+ * @returns {IdentityManager}
+ *
+ * @example
+ * // Create an identity service
+ * const identityManager = createIdentity({
+ *   logger: myLogger,
+ *   loggingCookieJar: myCookieJar,
+ *   config: { orgId: 'myOrgId@AdobeOrg' }
+ * });
+ *
+ * // Initialize and check for existing identity
+ * identityManager.initialize();
+ *
+ * // Wait for identity to be available
+ * await identityManager.awaitIdentity();
+ *
+ * // Get ECID from cookie
+ * const ecid = identityManager.getEcidFromCookie();
+ */
 export default ({
   logger,
   loggingCookieJar,

package/libEs6/core/identity/types.js

@@ -0,0 +1,12 @@
+/** @import { Logger } from '../../core/types.js' */
+/** @import { CookieJar } from '../../utils/types.js' */
+
+/**
+ * @typedef {Object} IdentityManager
+ * @property {Function} initialize
+ * @property {Function} setIdentityAcquired - Marks identity as acquired and resolves any pending identity promises
+ * @property {Function} awaitIdentity - Returns a promise that resolves when identity is acquired
+ * @property {Function} getEcidFromCookie
+ */
+
+export const Types = {};

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

@@ -28,6 +28,17 @@ export const base64ToBytes = base64String => {
 /**
  * Takes a Uint8Array and returns a base64 string.
  * @param {Uint8Array} bytes
+ * @param {Object} [options={}] - Options for encoding
+ * @param {boolean} [options.urlSafe=false] - Whether to return URL-safe base64 (no padding, + becomes -, / becomes _)
  * @returns {string}
  */
-export const bytesToBase64 = bytes => btoa(String.fromCharCode(...bytes));
+export const bytesToBase64 = (bytes, options = {}) => {
+  const {
+    urlSafe = false
+  } = options || {};
+  const base64 = btoa(String.fromCharCode(...bytes));
+  if (urlSafe) {
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  }
+  return base64;
+};

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/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,6 +10,8 @@ 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";
 
 /**
@@ -62,8 +64,19 @@ const createMergeConfigOverride = (content, key) => updates => {
   Object.assign(hostObjectForUpdates, updates);
 };
 
-// This provides the base functionality that all types of
-// request payloads share.
+/**
+ * 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,

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 = {};