@repobit/dex-data-layer 0.2.1 → 1.1.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.1.0](https://github.com/bitdefender/dex-core/compare/@repobit/dex-data-layer@0.2.1...@repobit/dex-data-layer@1.1.0) (2025-04-02)
+
+
+### Features
+
+* **DEX-22225:** added documentation ([12d2a0a](https://github.com/bitdefender/dex-core/commit/12d2a0aa1a5abad6119e93b897f729a1605cfbea))
+
+
+
 ## [0.2.1](https://github.com/bitdefender/dex-core/compare/@repobit/dex-data-layer@0.2.0...@repobit/dex-data-layer@0.2.1) (2025-03-26)
 
 

package/README.md

@@ -1,11 +1,182 @@
-# `@bitdefender/dex-target`
+# `@repobit/dex-data-layer`
 
-> TODO: description
+# BD Adobe Data Layer Utilities
 
-## Usage
+BD Adobe Data Layer Utilities is an npm package that provides a robust and flexible toolkit for managing and pushing events to Adobe’s Data Layer. It offers a collection of event classes (such as button clicks, form submissions, page load events, product events, etc.) along with a centralized service to handle event merging and dispatching to the global Adobe data layer. This ensures that events are recorded consistently for analytics and tracking.
 
+---
+
+## Overview
+
+This package standardizes the way web applications interact with Adobe’s Data Layer by:
+
+- Defining a set of event classes that encapsulate common interactions (e.g., page events, product events, user actions).
+- Providing a central service (`AdobeDataLayerService`) that manages the merging and pushing of these events into the global data layer (`window.adobeDataLayer`).
+- Implementing a custom merge strategy for product-related events to prevent duplication and ensure data consistency.
+
+---
+
+## Key Features
+
+- **Event Abstraction:**  
+  A comprehensive set of event classes, each with well-defined constructors and return types, to capture various user interactions and system events.
+
+- **Centralized Data Layer Management:**  
+  The `AdobeDataLayerService` class centralizes event management by merging events (especially product events) before dispatching them to the global data layer.
+
+- **Custom Merge Strategy:**  
+  Uses a tailored merge function to consolidate multiple `ProductLoadedEvent` entries, ensuring that only unique product details are retained.
+
+- **Seamless Global Integration:**  
+  Automatically integrates with the global `window.adobeDataLayer` array, making the pushed events readily available for Adobe Tag Management and analytics tools.
+
+- **Extensive Use Cases:**  
+  Comprehensive unit tests demonstrate real-world scenarios, including page load tracking, user detection, button clicks, and purchase events.
+
+---
+
+## Installation
+
+This package relies on external dependencies:
+- @repobit/dex-utils
+- @repobit/dex-store
+
+Install the package via npm or yarn:
+
+```bash
+npm install @repobit/dex-data-layer
+```
+# Classes and Their Constructors / Return Types
+
+## AdobeDataLayerService
+### Static class (not instantiated)
+
+### Key Methods:
+
+- ## push(event: DataLayerEvent): void
+  - ### Input: An instance of a DataLayerEvent (e.g., ButtonClickEvent, CdpEvent, etc.).
+  - ### Behavior:
+    - For `ProductLoadedEvent`, the event is merged into a local data structure (using the `deepmerge` library with a custom array merge function) keyed by the event name (e.g., `product loaded`). This allows multiple product events to be consolidated, reducing redundancy.
+    - For all other situations, the event is directly pushed to the global `window.adobeDataLayer`, making it immediately available for consumption by Adobe’s tag management tools.
+- ## pushEventsToDataLayer(): void
+  - ### Behavior:
+    - Iterates through the locally stored events (like merged product events) and pushes them into the global data layer.
+
+### Use case:
+When a user action or system event occurs (for example, a button click or product load), create the corresponding event instance and call AdobeDataLayerService.push(event). For product events, later call AdobeDataLayerService.pushEventsToDataLayer() to flush the merged data.
+
+## ButtonClickEvent
+### Constructor: constructor(clickEvent: 'trial downloaded' | 'product downloaded' | string, productId: string)
+### Return Type:
+Returns an instance of `ButtonClickEvent` with:
+- `event`: A string indicating the type of button click event.
+- `product`: An object containing product details. For example, if the event is 'trial downloaded', the product object will have a trial key with an array of product IDs.
+
+## CdpEvent
+### Constructor: constructor(cdpData: CdpEventParameters)
+### Return Type:
+Returns an instance of `CdpEvent` with:
+- `event`: Constant string `cdp data`.
+- `parameters`: An object containing CDP parameters
+
+## FormEvent
+### Constructor: constructor(event: string, userObject: FormEventUserObject)
+### Return Type:
+Returns an instance of `FormEvent` with:
+- `event`: A string representing the form event (e.g., `form completed`).
+- `user`: An object containing form-specific data (such as form ID and form name).
+
+## OneClickPurchaseEvent
+### Constructor: constructor(event: string, cart: OneClickPurchaseEventCartObject, transaction: OneClickPurchaseEventTransactionObject)
+### Return Type:
+Returns an instance of `OneClickPurchaseEvent` with:
+- `event`:  A string representing the purchase event (e.g., `purchase`).
+- `cart`: An object detailing the cart (if provided).
+- `transaction`: An object detailing the transaction (if provided).
+
+## PageErrorEvent
+### Constructor: constructor()
+### Return Type:
+Returns an instance of `PageErrorEvent` with:
+- `event`:  Constant string `page error`.
+
+## PageLoadStartedEvent
+### Constructor: constructor(page: Page, pageData: PageLoadStartedDataObject)
+### Return Type:
+Returns an instance of `PageLoadStartedEvent` with:
+- `event`: Constant string `page load started`.
+- `pageInstanceID`: A value derived from the page’s environment (e.g., 'dev', 'stage', or 'prod').
+- `page`: A complex object that contains detailed page information (sections, query parameters, server details, etc.) constructed from the provided Page instance and pageData. This object is easily constructed using the `Page class` from the `@repobit/dex-utils` package.
+
+## PageLoadedEvent
+### Constructor: constructor()
+### Return Type:
+Returns an instance of `PageLoadedEvent` with:
+- `event`:  Constant string `page loaded`.
+
+## ProductLoadedEvent
+### Constructor: constructor(option: ProductOption | { ID: string }, type: 'all' | 'info' | 'comparison' | string)
+### Return Type:
+Returns an instance of `ProductLoadedEvent` with:
+- `event`: Constant string `product loaded`.
+- `product`: An object where keys are the product type (e.g., all, info) and the values are arrays of product details (either raw product IDs or detailed option information).
+
+## PromotionIdEvent
+### Constructor: constructor(pageObject: PromotionIdEventPageObject)
+### Return Type:
+Returns an instance of `PromotionIdEvent` with:
+- `event`: Constant string `promotion id event`.
+- `page`: An object containing page attributes related to the promotion ID.
+
+## UserDetectedEvent
+### Constructor: constructor(page: Page, userData: UserDataObject)
+### Return Type:
+Returns an instance of `UserDetectedEvent` with:
+- `event`: Constant string `user detected`.
+- `user`: An object that includes user detection details (e.g., login status, unique identifiers).
+
+---
+
+# Usage Examples
+
+## Page Load Started Event:
+
+```typescript
+const testPage = new Page('en-us', 'consumer', 'dev');
+AdobeDataLayerService.push(new PageLoadStartedEvent(testPage, {
+  name: 'en-us:consumer:solutions',
+  geoRegion: 'en-us'
+}));
+const insertedEvent = window.adobeDataLayer[0] as PageLoadStartedEvent;
+console.log(insertedEvent.event); // "page load started"
+```
+
+## User Detected Event:
+
+```typescript
+AdobeDataLayerService.push(new UserDetectedEvent(testPage, {
+  ID: '9999',
+  productFinding: 'consumer-page'
+}));
+const insertedEvent = window.adobeDataLayer[0] as UserDetectedEvent;
+console.log(insertedEvent.event); // "user detected"
 ```
-import Target from '@bitdefender/dex-target';
 
-// TODO: DEMONSTRATE API
+## Button Click Event:
+
+```typescript
+AdobeDataLayerService.push(new ButtonClickEvent('trial downloaded', '9999'));
+const insertedEvent = window.adobeDataLayer[0] as ButtonClickEvent;
+console.log(insertedEvent.event); // "trial downloaded"
 ```
+
+## Product Loaded Event:
+The code below is just for example purposes. Product Option is generated by the `Store` and should only be used in the context of a `Store Resolver`.
+
+```typescript
+const option = new ProductOption({ /* product details */ });
+AdobeDataLayerService.push(new ProductLoadedEvent(option, 'all'));
+AdobeDataLayerService.pushEventsToDataLayer();
+const insertedEvent = window.adobeDataLayer[0] as ProductLoadedEvent;
+console.log(insertedEvent.event); // "product loaded"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobit/dex-data-layer",
-  "version": "0.2.1",
+  "version": "1.1.0",
   "description": "Client for Adobe Data Layer",
   "author": "Constantin Ioan Mihai <iconstantin@bitdefender.com>",
   "homepage": "https://github.com/bitdefender/dex-core#readme",
@@ -37,5 +37,5 @@
   "volta": {
     "node": "22.14.0"
   },
-  "gitHead": "64dd7dca1e451796a1fafe016b7a8d361523754f"
+  "gitHead": "63cefae5c57ca4f1e886b623d1979bb369b3e777"
 }