@chordcommerce/analytics 1.23.1 → 1.25.0-beta.2

package/README.md

@@ -121,8 +121,16 @@ 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.
+sent to analytics providers. Middleware functions are invoked in the order they
+were added during event tracking, and each one's properties are merged into the
+event in that order.
+
+A middleware may be synchronous or asynchronous. Synchronous middleware is never
+awaited, so it adds no delay to event delivery. Asynchronous middleware is
+awaited before the event is sent, capped at one second — a middleware that has
+not resolved by then is abandoned, a warning is logged, and the event is sent
+without its properties. A middleware that throws or rejects is logged and
+skipped. A middleware never prevents an event from being sent.
 
 Parameters
 
@@ -135,6 +143,15 @@ The middleware function can return:
 
 - Partial<EventProperties> - Properties to merge into the event payload
 - void - No additional properties to add
+- A Promise of either of the above - Awaited before the event is sent
+
+The `payload` argument carries `payload.obj` (the event's properties, name and
+page context) plus `payload.userId` and `payload.anonymousId` as the CDP
+currently knows them — either may be undefined.
+
+Note that middleware contributes properties by **returning** them. Mutating the
+`payload` argument has no effect; `next` is accepted for signature
+compatibility and does nothing.
 
 Useage Example
 
@@ -156,6 +173,15 @@ Useage Example
       timestamp: Date.now()
     };
   });
+
+  // Asynchronous middleware: the event waits for the lookup, up to one second.
+  analytics.addSourceMiddleware(async ({ payload }) => {
+    if (payload.obj.event !== 'Order Completed') return;
+
+    const isNewCustomer = await fetchIsNewCustomer();
+
+    return { is_new_customer: isNewCustomer ? 1 : 0 };
+  });
 ```
 
 ## API Reference

package/dist/cjs/client/index.d.ts

@@ -31,34 +31,10 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
      */
     private cdpReadyPromise;
     private consentConfig;
-    private resetCompletePromise;
-    /**
-     * Queue for events waiting for consent to be ready
-     */
-    private consentEventQueue;
-    /**
-     * Whether we're currently waiting for consent and watching for it
-     */
-    private consentWatcherActive;
-    /**
-     * Promise that resolves when consent is ready (shared across all queued events)
-     */
+    private operationQueue;
+    private resetting;
     private consentReadyPromise;
     constructor(options: ChordAnalyticsOptions<T>);
-    /**
-     * Persist the consent event queue to sessionStorage for recovery on instance recreation.
-     * Validates queue size before storing to prevent QuotaExceededError.
-     */
-    private persistQueueToStorage;
-    /**
-     * Restore pending events from sessionStorage (keeps events less than 5 min old).
-     * Called on new instance initialization.
-     */
-    private restoreQueueFromStorage;
-    /**
-     * Clear the persisted queue from sessionStorage after successful flush.
-     */
-    private clearQueueFromStorage;
     /**
      * Initialize CDP snippet and wait for it to be ready.
      * Fires initial consent track event after CDP is fully initialized to avoid circular await.
@@ -71,29 +47,17 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
     setDebugMode: (enabled: boolean) => void;
     cdp: () => AnyAnalytics;
     ccdp: () => AnyAnalytics;
+    private currentUser;
     logger: (message?: any, ...optionalParams: any[]) => void;
     isResetting: () => boolean;
+    private enqueue;
+    private withTimeout;
     private waitForReadyState;
     /**
      * Wait for consent manager to be ready (no timeout - queues indefinitely).
      * Uses a shared promise so multiple events share the same watcher.
      */
     private waitForConsent;
-    /**
-     * Queue an event to be sent when consent is ready.
-     * Persists to sessionStorage for recovery on instance recreation.
-     * Starts a consent watcher if not already active.
-     */
-    private queueEventForConsent;
-    /**
-     * Watch for consent to become ready, then flush the queue.
-     */
-    private watchForConsentAndFlush;
-    /**
-     * Flush all queued events now that consent is ready.
-     * Clears sessionStorage after successful flush.
-     */
-    private flushConsentQueue;
     /**
      * Configure CDP with fresh consent categories before each event.
      * Uses Jitsu's configure() to update privacy.consentCategories.
@@ -152,7 +116,6 @@ export declare class ChordAnalytics<T extends ObjectTypes = ObjectTypes> {
      */
     private sendPageEvent;
     reset: () => Promise<void>;
-    private performReset;
     /**
      * Handler for postMessage events from the Shopify Web Pixel sandbox.
      * Bound to the instance for proper `this` context and cleanup.