@chordcommerce/analytics 1.16.1 → 1.17.1

package/README.md

@@ -110,6 +110,46 @@ export const cartFormatter: CartFormatter<StorefrontCart> = (props) => {
 }
 ```
 
+addSourceMiddleware(func: AnalyticsMiddleware)
+
+Registers a middleware function to modify event properties before they are
+sent to analytics providers. Middleware functions are executed
+synchronously in the order they were added during event tracking.
+
+Parameters
+
+- func (AnalyticsMiddleware) - A middleware function that receives event
+  data and can return additional properties to merge into the event payload.
+
+Return Value
+
+The middleware function can return:
+
+- Partial<EventProperties> - Properties to merge into the event payload
+- void - No additional properties to add
+
+Useage Example
+
+```
+  analytics.addSourceMiddleware(({ payload }) => {
+    const { searchParams } = payload.obj.context.page;
+
+    return {
+      utm_source: searchParams.utm_source,
+      utm_medium: searchParams.utm_medium,
+      utm_campaign: searchParams.utm_campaign
+    };
+  });
+
+  analytics.addSourceMiddleware(({ payload }) => {
+    return {
+      session_id: getSessionId(),
+      user_agent: navigator.userAgent,
+      timestamp: Date.now()
+    };
+  });
+```
+
 ## API Reference
 
 See [Chord’s documentation](https://docs.chord.co/api-reference) for a full API reference.

package/dist/client/index.d.ts

@@ -1,4 +1,5 @@
 import type { AnyAnalytics, EventProperties, Options, ValidateResult, ChordAnalyticsOptions, AnyOptions, CartViewedInput, IdentifyTraits, CheckoutStartedInput, CheckoutStepCompletedInput, CheckoutStepViewedInput, EmailCapturedInput, ProductListViewedInput, ProductListFilteredInput, ProductAddedInput, ProductClickedInput, VariantClickedInput, ProductRemovedInput, ProductViewedInput, ProductsSearchedInput, CouponAppliedInput, CouponDeniedInput, CouponEnteredInput, CouponRemovedInput, SignedInInput, SignedOutInput, SignedUpInput, LoginStartedInput, ObjectTypes, SubscriptionCancelledInput, NavigationClickedInput, PaymentInfoEnteredInput } from '../types/index.js';
+import { AnalyticsMiddleware } from '../types/client.js';
 export interface ChordAnalyticsSnippet {
     _loadOptions: ChordAnalyticsOptions<ObjectTypes>;
     invoked: boolean;
@@ -21,6 +22,10 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
      * Options for ChordAnalytics.
      */
     options: ChordAnalyticsOptions<T>;
+    /**
+     * Middleware to be applied to the event properties
+     */
+    middleware: any[];
     /**
      * Promise that resolves when CDP is ready
      */
@@ -60,6 +65,7 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
         platform: import("../types/client.js").platformMetadata;
         store: import("../types/client.js").storeMetadata;
     };
+    addSourceMiddleware: (func: AnalyticsMiddleware) => void;
     /**
      * Send a `track` event to the CDP with any event name and properties.
      */

package/dist/client/index.js

@@ -22,6 +22,10 @@ export class ChordAnalytics {
          * Allows snippet.js to detect whether the snippet has started running yet.
          */
         this.invoked = true;
+        /**
+         * Middleware to be applied to the event properties
+         */
+        this.middleware = [];
         /**
          * Promise that resolves when CDP is ready
          */
@@ -93,6 +97,10 @@ export class ChordAnalytics {
                     patch: 0,
                 } });
         };
+        // eslint-disable-next-line class-methods-use-this
+        this.addSourceMiddleware = (func) => {
+            this.middleware.push(func);
+        };
         /**
          * Send a `track` event to the CDP with any event name and properties.
          */
@@ -104,7 +112,39 @@ export class ChordAnalytics {
                 yield this.cdpReadyPromise;
             }
             const formattedProps = this.options.stripNull && props ? pruneNullValues(props) : props;
-            const finalEventProps = Object.assign(Object.assign({}, formattedProps), { meta: this.meta() });
+            let middlewareProps = {};
+            if (this.middleware.length > 0) {
+                const searchParams = typeof window !== 'undefined' ? window.location.search : '';
+                const urlSearchParams = new URLSearchParams(searchParams);
+                const searchData = Object.fromEntries(urlSearchParams.entries());
+                // process middleware synchronously
+                this.middleware.forEach((func) => {
+                    try {
+                        const result = func({
+                            payload: {
+                                obj: {
+                                    properties: props,
+                                    event,
+                                    context: {
+                                        page: {
+                                            search: searchParams,
+                                            searchParams: searchData,
+                                        },
+                                    },
+                                },
+                            },
+                            next: (_) => _,
+                        });
+                        if (result && typeof result === 'object') {
+                            middlewareProps = Object.assign(Object.assign({}, middlewareProps), result);
+                        }
+                    }
+                    catch (error) {
+                        console.warn('Middleware error:', error);
+                    }
+                });
+            }
+            const finalEventProps = Object.assign(Object.assign(Object.assign({}, formattedProps), middlewareProps), { meta: this.meta() });
             if (this.options.debug) {
                 this.validate(event, finalEventProps).forEach((valid) => {
                     if (!valid.success) {

package/dist/setupTests.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/setupTests.js

@@ -0,0 +1,4 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { jest } from '@jest/globals';
+// Make jest available globally
+globalThis.jest = jest;

package/dist/types/client.d.ts

@@ -1,4 +1,4 @@
-import type { AnalyticsSnippet, Analytics, AnalyticsBrowser, Options } from '@segment/analytics-next';
+import type { EventProperties, AnalyticsSnippet, Analytics, AnalyticsBrowser, Options } from '@segment/analytics-next';
 import { ChordAnalyticsFormatters } from './formatters.js';
 export interface ValidateResult {
     success: boolean;
@@ -39,6 +39,7 @@ export interface ChordAnalyticsOptions<T extends ObjectTypes = ObjectTypes> {
     stripNull?: boolean;
     metadata: EventMetadata;
     awaitConsentTimeout?: number;
+    middleware?: Array<() => void>;
 }
 export interface EventMetadata {
     i18n: i18nMetadata;
@@ -74,3 +75,22 @@ export type ChordAnalyticsQueue = {
     page: (...args: any[]) => void;
     reset: (...args: any[]) => void;
 };
+type PageContext = {
+    search: string;
+    searchParams: Record<string, string>;
+};
+type MiddlewarePayload = {
+    obj: {
+        properties?: EventProperties;
+        event: string;
+        context: {
+            page: PageContext;
+        };
+    };
+};
+type MiddlewareArgs = {
+    payload: MiddlewarePayload;
+    next: <T>(arg: T) => T;
+};
+export type AnalyticsMiddleware = (args: MiddlewareArgs) => Partial<EventProperties> | void;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chordcommerce/analytics",
   "description": "Chord Commerce event tracking",
-  "version": "1.16.1",
+  "version": "1.17.1",
   "author": "Chord Commerce <help@chord.co> (https://www.chord.co)",
   "type": "module",
   "main": "dist/index.js",
@@ -18,6 +18,7 @@
     "clean": "rimraf dist",
     "test": "jest",
     "test:watch": "jest --watch",
+    "test:file": "NODE_OPTIONS=--experimental-vm-modules jest",
     "test:ci": "yarn test --ci --runInBand --reporters=default --passWithNoTests",
     "zod": "yarn ts-to-zod src/types/typewriter.ts src/validators/tracking-plan.ts && yarn ts-to-zod src/types/objects.ts src/validators/objects.ts"
   },