ga4-export-fixer 0.5.1 → 0.5.2-dev.1

package/README.md

@@ -294,7 +294,8 @@ All fields are optional except `sourceTable`. Default values are applied automat
 | `schemaLock`           | string                  | `undefined`                        | Lock the table schema to a specific GA4 export table suffix. Accepts `"YYYYMMDD"` (daily), `"intraday_YYYYMMDD"`, or `"fresh_YYYYMMDD"`. Date must be >= `"20241009"`                                                                                                                                                        |
 | `timezone`             | string                  | `'Etc/UTC'`                        | IANA timezone for event datetime (e.g. `'Europe/Helsinki'`)                                                                                                                                                                                                                                                                  |
 | `customTimestampParam` | string                  | `undefined`                        | Name of a custom event parameter containing a JS timestamp in milliseconds (e.g. collected via `Date.now()`)                                                                                                                                                                                                                 |
-| `bufferDays`           | integer                 | `1`                                | Extra days to include for sessions that span midnight                                                                                                                                                                                                                                                                        |
+| `bufferDays`           | integer                 | `1`                                | Extra days to include for sessions that span midnight. Auto-adjusted when `itemListAttribution.lookbackType` is `'TIME'` and the lookback exceeds `bufferDays`                                                                                                                                                               |
+| `itemListAttribution`  | object                  | `undefined`                        | Enable item list attribution. See [Item List Attribution](#item-list-attribution)                                                                                                                                                                                                                                            |
 | `test`                 | boolean                 | `false`                            | Enable test mode (uses `testConfig` date range instead of pre-operations)                                                                                                                                                                                                                                                    |
 | `excludedEventParams`  | string[]                | `[]`                               | Event parameter names to exclude from the `event_params` array                                                                                                                                                                                                                                                               |
 | `excludedEvents`       | string[]                | `['session_start', 'first_visit']` | Event names to exclude from the table. These events are excluded by default because they have no use for analysis purposes. Override this to include them if needed                                                                                                                                                          |
@@ -412,6 +413,25 @@ The boundary between fresh and intraday is timestamp-based because the fresh exp
 | `columnName` | string | No       | Column name in the output. Defaults to the parameter `name`                                                                           |
 
 
+<a id="item-list-attribution"></a>
+
+**`itemListAttribution`** — when set to an object, enables attribution of `item_list_name`, `item_list_id`, and `item_list_index` from `select_item`/`select_promotion` events to downstream ecommerce events (e.g. `add_to_cart`, `purchase`). Disabled by default.
+
+| Field            | Type    | Required                    | Description                                                           |
+| ---------------- | ------- | --------------------------- | --------------------------------------------------------------------- |
+| `lookbackType`   | string  | Yes                         | `'SESSION'` (partition by session) or `'TIME'` (time-based window)    |
+| `lookbackTimeMs` | integer | When `lookbackType: 'TIME'` | Lookback window in milliseconds (e.g. `86400000` for 24h)            |
+
+```javascript
+// Session-based: attribute within the same session
+itemListAttribution: { lookbackType: 'SESSION' }
+
+// Time-based: attribute within a 24-hour window across sessions
+itemListAttribution: { lookbackType: 'TIME', lookbackTimeMs: 86400000 }
+```
+
+> **Note:** This feature adds a compute-heavy CTE with a window function over unnested items. Only enable it if you need item list attribution for ecommerce analysis.
+
 Date fields (`dateRangeStart`, `dateRangeEnd`, etc.) accept string dates in `YYYYMMDD` or `YYYY-MM-DD` format, or BigQuery SQL expressions (e.g. `'current_date()'`, `'date(2026, 1, 1)'`).
 
 ### Creating Incremental Downstream Tables from ga4_events_enhanced

package/helpers/ga4Transforms.js

@@ -157,10 +157,71 @@ const getGa4ExportType = (tableSuffix) => {
     end`;
 };
 
+/**
+ * Generates a SQL LAST_VALUE window function that attributes item list fields
+ * (item_list_name, item_list_id, item_list_index) from select_item/select_promotion
+ * events to downstream ecommerce events using a lookback window.
+ *
+ * Returns a struct containing all three attributed fields via a single window sort.
+ *
+ * @param {'SESSION'|'TIME'} lookbackType - Window scope: session-based or time-based
+ * @param {string} timestampColumn - Column to order by ('event_timestamp' or 'event_custom_timestamp')
+ * @param {number} [lookbackTimeMs] - Lookback window in milliseconds (required when lookbackType is 'TIME')
+ * @returns {string} SQL expression that evaluates to a struct with item_list_name, item_list_id, item_list_index
+ */
+const itemListAttributionExpr = (lookbackType, timestampColumn, lookbackTimeMs) => {
+  const selectEvents = `event_name in ('select_item', 'select_promotion')`;
+  const structExpr = `struct(item.item_list_name, item.item_list_id, item.item_list_index)`;
+
+  let partitionBy;
+  let frameBounds;
+
+  if (lookbackType === 'SESSION') {
+    partitionBy = 'session_id, item.item_id';
+    frameBounds = 'rows between unbounded preceding and current row';
+  } else {
+    // TIME-based: range window in microseconds
+    const lookbackMicros = lookbackTimeMs * 1000;
+    partitionBy = 'user_pseudo_id, item.item_id';
+    frameBounds = `range between ${lookbackMicros} preceding and current row`;
+  }
+
+  return `last_value(
+      if(${selectEvents}, ${structExpr}, null) ignore nulls
+    ) over(
+      partition by ${partitionBy}
+      order by ${timestampColumn} asc
+      ${frameBounds}
+    )`;
+};
+
+/**
+ * Official GA4 ecommerce events that carry item data.
+ * Based on: https://developers.google.com/analytics/devguides/collection/ga4/ecommerce
+ */
+const ga4EcommerceEvents = [
+  'view_item_list',
+  'select_item',
+  'view_promotion',
+  'select_promotion',
+  'view_item',
+  'add_to_wishlist',
+  'add_to_cart',
+  'remove_from_cart',
+  'view_cart',
+  'begin_checkout',
+  'add_shipping_info',
+  'add_payment_info',
+  'purchase',
+  'refund',
+];
+
 module.exports = {
   sessionId,
   fixEcommerceStruct,
   isFinalData,
   isGa4ExportColumn,
-  getGa4ExportType
+  getGa4ExportType,
+  itemListAttributionExpr,
+  ga4EcommerceEvents
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ga4-export-fixer",
-  "version": "0.5.1",
+  "version": "0.5.2-dev.1",
   "description": "",
   "main": "index.js",
   "files": [
@@ -26,6 +26,7 @@
     "test:validation": "node tests/inputValidation.test.js",
     "test:createTable": "node tests/createTable.test.js",
     "test:integration": "node tests/integration/integration.test.js",
+    "release:dev": "./scripts/release-dev.sh",
     "readme": "node scripts/updateReadme.js",
     "prepublishOnly": "node scripts/updateReadme.js"
   },

package/tables/ga4EventsEnhanced/config.js

@@ -36,6 +36,8 @@ const ga4EventsEnhancedConfig = {
         // according to GA4 documentation, the data up to 72 hours old is subject to possible changes
         // in reality, there have been cases where the data has changed even after 72 hours (4 day window would have covered these)
     },
+    // optional item list attribution - disabled by default (compute-heavy, only useful for ecommerce sites)
+    itemListAttribution: undefined,
     // number of additional days to take in for taking into account sessions that overlap days
     bufferDays: 1,
     // these parameters are excluded by default because they've been made available in other columns

package/tables/ga4EventsEnhanced/index.js

@@ -159,6 +159,17 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
     // the most accurate available timestamp column
     const timestampColumn = mergedConfig.customTimestampParam ? 'event_custom_timestamp' : 'event_timestamp';
 
+    // item list attribution config
+    const itemListAttribution = mergedConfig.itemListAttribution;
+
+    // auto-adjust bufferDays for time-based item list attribution lookback
+    const effectiveBufferDays = (itemListAttribution && itemListAttribution.lookbackType === 'TIME')
+        ? Math.max(mergedConfig.bufferDays, Math.ceil(itemListAttribution.lookbackTimeMs / (24 * 60 * 60 * 1000)))
+        : mergedConfig.bufferDays;
+    const dateFilterConfig = effectiveBufferDays !== mergedConfig.bufferDays
+        ? { ...mergedConfig, bufferDays: effectiveBufferDays }
+        : mergedConfig;
+
     // exlude these events from the table
     const excludedEvents = mergedConfig.excludedEvents;
     const excludedEventsSQL = excludedEvents.length > 0 ? `and event_name not in (${excludedEvents.map(event => `'${event}'`).join(',')})` : '';
@@ -214,6 +225,8 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
             // ecommerce
             ecommerce: helpers.fixEcommerceStruct('ecommerce'),
             items: 'items',
+            // unique row id for item list attribution join
+            _event_row_id: itemListAttribution ? 'row_number() over()' : undefined,
             // flag if the data is "final" and is not expected to change anymore
             data_is_final: helpers.isFinalData(mergedConfig.dataIsFinal.detectionMethod, mergedConfig.dataIsFinal.dayThreshold),
             export_type: helpers.getGa4ExportType('_table_suffix'),
@@ -227,7 +240,7 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
             },
         },
         from: mergedConfig.sourceTable,
-        where: `${helpers.ga4ExportDateFilters(mergedConfig)}
+        where: `${helpers.ga4ExportDateFilters(dateFilterConfig)}
 ${excludedEventsSQL}`,
     };
 
@@ -248,28 +261,64 @@ ${excludedEventsSQL}`,
         groupBy: ['session_id']
     };
 
+    // item list attribution CTE: unnest items, attribute via window function, re-aggregate
+    const itemListDataStep = itemListAttribution ? (() => {
+        const attrExpr = helpers.itemListAttributionExpr(
+            itemListAttribution.lookbackType,
+            timestampColumn,
+            itemListAttribution.lookbackTimeMs
+        );
+        const passthroughEvents = `event_name in ('view_item_list', 'select_item', 'view_promotion', 'select_promotion')`;
+        const ecommerceFilter = helpers.ga4EcommerceEvents.filter(e => e !== 'refund').map(e => `'${e}'`).join(', ');
+
+        return {
+            name: 'item_list_data',
+            columns: {
+                '_event_row_id': '_event_row_id',
+                'items': `array_agg(
+      (select as struct item.* replace(
+        coalesce(if(${passthroughEvents}, item.item_list_name, _item_list_attr.item_list_name), '(not set)') as item_list_name,
+        coalesce(if(${passthroughEvents}, item.item_list_id, _item_list_attr.item_list_id), '(not set)') as item_list_id,
+        coalesce(if(${passthroughEvents}, item.item_list_index, _item_list_attr.item_list_index)) as item_list_index
+      ))
+    )`,
+            },
+            from: `(select _event_row_id, event_name, item, ${attrExpr} as _item_list_attr from event_data, unnest(items) as item where event_name in (${ecommerceFilter}))`,
+            groupBy: ['_event_row_id'],
+        };
+    })() : null;
+
     const finalColumnOrder = getFinalColumnOrder(eventDataStep, sessionDataStep);
 
+    // When item list attribution is enabled, override the items column and exclude _event_row_id
+    // COALESCE handles events without items (not in ecommerce filter) where the LEFT JOIN returns NULL
+    const itemListOverrides = itemListDataStep ? {
+        items: 'coalesce(item_list_data.items, event_data.items)',
+    } : {};
+    const itemListExcludedColumns = itemListDataStep ? ['_event_row_id'] : [];
+
     // Join event_data and session_data, include additional logic
     const finalStep = {
         name: 'final',
         columns: {
             // get the most important columns in the correct order
             ...finalColumnOrder,
+            ...itemListOverrides,
             // get the rest of the event_data columns
             '[sql]event_data': utils.selectOtherColumns(
-                eventDataStep, 
+                eventDataStep,
                 Object.keys(finalColumnOrder),
                 [
                     'entrances',
                     mergedConfig.sessionParams.length > 0 ? 'session_params_prep' : undefined,
                     'data_is_final',
                     'export_type',
+                    ...itemListExcludedColumns,
                 ]
             ),
-            // get the rest of the session_data columns 
+            // get the rest of the session_data columns
             '[sql]session_data': utils.selectOtherColumns(
-                sessionDataStep, 
+                sessionDataStep,
                 Object.keys(finalColumnOrder),
                 []
             ),
@@ -280,6 +329,10 @@ ${excludedEventsSQL}`,
         },
         from: 'event_data',
         leftJoin: [
+            ...(itemListDataStep ? [{
+                table: 'item_list_data',
+                condition: 'using(_event_row_id)'
+            }] : []),
             {
                 table: 'session_data',
                 condition: 'using(session_id)'
@@ -290,6 +343,7 @@ ${excludedEventsSQL}`,
 
     const steps = [
         eventDataStep,
+        ...(itemListDataStep ? [itemListDataStep] : []),
         sessionDataStep,
         finalStep,
     ];

package/tables/ga4EventsEnhanced/validation.js

@@ -129,6 +129,29 @@ const validateEnhancedEventsConfig = (config, options = {}) => {
         throw new Error(`config.dataIsFinal.detectionMethod must be 'DAY_THRESHOLD' when daily export is not enabled (config.includedExportTypes.daily is false). A dayThreshold of 1 is recommended for intraday only setups. With fresh export, the GA4 data is subject to possible changes for up to 72 hours. Received: ${JSON.stringify(config.dataIsFinal.detectionMethod)}`);
     }
 
+    // itemListAttribution - optional; must be undefined or a valid config object
+    if (typeof config.itemListAttribution !== 'undefined') {
+        if (!config.itemListAttribution || typeof config.itemListAttribution !== 'object' || Array.isArray(config.itemListAttribution)) {
+            throw new Error(`config.itemListAttribution must be an object when provided. Received: ${JSON.stringify(config.itemListAttribution)}`);
+        }
+        if (typeof config.itemListAttribution.lookbackType === 'undefined') {
+            throw new Error("config.itemListAttribution.lookbackType is required. Must be 'SESSION' or 'TIME'.");
+        }
+        if (config.itemListAttribution.lookbackType !== 'SESSION' && config.itemListAttribution.lookbackType !== 'TIME') {
+            throw new Error(`config.itemListAttribution.lookbackType must be 'SESSION' or 'TIME'. Received: ${JSON.stringify(config.itemListAttribution.lookbackType)}`);
+        }
+        if (config.itemListAttribution.lookbackType === 'TIME') {
+            if (typeof config.itemListAttribution.lookbackTimeMs === 'undefined') {
+                throw new Error("config.itemListAttribution.lookbackTimeMs is required when lookbackType is 'TIME'.");
+            }
+        }
+        if (typeof config.itemListAttribution.lookbackTimeMs !== 'undefined') {
+            if (typeof config.itemListAttribution.lookbackTimeMs !== 'number' || !Number.isInteger(config.itemListAttribution.lookbackTimeMs) || config.itemListAttribution.lookbackTimeMs <= 0) {
+                throw new Error(`config.itemListAttribution.lookbackTimeMs must be a positive integer. Received: ${JSON.stringify(config.itemListAttribution.lookbackTimeMs)}`);
+            }
+        }
+    }
+
     // bufferDays - required
     if (typeof config.bufferDays !== 'number' || !Number.isInteger(config.bufferDays) || config.bufferDays < 0) {
         throw new Error(`config.bufferDays must be a non-negative integer. Received: ${JSON.stringify(config.bufferDays)}`);