ga4-export-fixer 0.9.0-dev.1 → 0.9.0-dev.10

package/helpers/ga4Transforms.js

@@ -95,50 +95,99 @@ const isFinalData = (detectionMethod, dayThreshold) => {
 };
 
 /**
- * Checks whether a given column name is part of the standard/expected GA4 BigQuery export columns.
+ * The standard GA4 BigQuery export top-level column names, based on the official schema.
  *
- * The list of recognized GA4 export columns is based on the official schema as of 2026-02-18.
- * This function can be used to filter or validate column names when processing GA4 data exports.
+ * list updated 2026-02-18
+ */
+const ga4ExportColumns = [
+  "event_date",
+  "event_timestamp",
+  "event_name",
+  "event_params",
+  "event_previous_timestamp",
+  "event_value_in_usd",
+  "event_bundle_sequence_id",
+  "event_server_timestamp_offset",
+  "user_id",
+  "user_pseudo_id",
+  "privacy_info",
+  "user_properties",
+  "user_first_touch_timestamp",
+  "user_ltv",
+  "device",
+  "geo",
+  "app_info",
+  "traffic_source",
+  "stream_id",
+  "platform",
+  "event_dimensions",
+  "ecommerce",
+  "items",
+  "collected_traffic_source",
+  "is_active_user",
+  "batch_event_index",
+  "batch_page_id",
+  "batch_ordering_id",
+  "session_traffic_source_last_click",
+  "publisher"
+];
+
+/**
+ * Checks whether a given column name is part of the standard GA4 BigQuery export columns.
  *
  * @param {string} columnName - The name of the column to check.
  * @returns {boolean} True if the column name is a GA4 export column, otherwise false.
  */
-const isGa4ExportColumn = (columnName) => {
-  // list updated 2026-02-18
-  const ga4ExportColumns = [
-    "event_date",
-    "event_timestamp",
-    "event_name",
-    "event_params",
-    "event_previous_timestamp",
-    "event_value_in_usd",
-    "event_bundle_sequence_id",
-    "event_server_timestamp_offset",
-    "user_id",
-    "user_pseudo_id",
-    "privacy_info",
-    "user_properties",
-    "user_first_touch_timestamp",
-    "user_ltv",
-    "device",
-    "geo",
-    "app_info",
-    "traffic_source",
-    "stream_id",
-    "platform",
-    "event_dimensions",
-    "ecommerce",
-    "items",
-    "collected_traffic_source",
-    "is_active_user",
-    "batch_event_index",
-    "batch_page_id",
-    "batch_ordering_id",
-    "session_traffic_source_last_click",
-    "publisher"
-  ];
-  return ga4ExportColumns.includes(columnName);
-};
+const isGa4ExportColumn = (columnName) => ga4ExportColumns.includes(columnName);
+
+/**
+ * The standard GA4 BigQuery export items-struct field names, based on the official schema.
+ * Listed in GA4's source order — `items_rebuilt`'s explicit struct construction emits fields
+ * in this order, and consumers may reasonably depend on the items-struct schema field order
+ * matching GA4's own.
+ *
+ * `item_params` is a nested REPEATED RECORD and projects through as a single struct entry
+ * (no per-key handling).
+ *
+ * list updated 2026-05-12
+ */
+const ga4ItemStructFields = [
+  "item_id",
+  "item_name",
+  "item_brand",
+  "item_variant",
+  "item_category",
+  "item_category2",
+  "item_category3",
+  "item_category4",
+  "item_category5",
+  "price_in_usd",
+  "price",
+  "quantity",
+  "item_revenue_in_usd",
+  "item_revenue",
+  "item_refund_in_usd",
+  "item_refund",
+  "coupon",
+  "affiliation",
+  "location_id",
+  "item_list_id",
+  "item_list_name",
+  "item_list_index",
+  "promotion_id",
+  "promotion_name",
+  "creative_name",
+  "creative_slot",
+  "item_params"
+];
+
+/**
+ * Checks whether a given field name is part of the standard GA4 BigQuery export items struct.
+ *
+ * @param {string} fieldName - The name of the field to check.
+ * @returns {boolean} True if the field name is a standard items-struct field, otherwise false.
+ */
+const isGa4ItemStructField = (fieldName) => ga4ItemStructFields.includes(fieldName);
 
 /**
  * Generates a SQL CASE expression that determines the GA4 export type from a table suffix.
@@ -255,7 +304,10 @@ module.exports = {
   sessionId,
   fixEcommerceStruct,
   isFinalData,
+  ga4ExportColumns,
   isGa4ExportColumn,
+  ga4ItemStructFields,
+  isGa4ItemStructField,
   getGa4ExportType,
   itemListAttributionExpr,
   itemRowId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ga4-export-fixer",
-  "version": "0.9.0-dev.1",
+  "version": "0.9.0-dev.10",
   "description": "",
   "main": "index.js",
   "files": [
@@ -17,7 +17,7 @@
     "createTable.js"
   ],
   "scripts": {
-    "test": "node tests/ga4EventsEnhanced.test.js && node tests/assertions.test.js && node tests/mergeSQLConfigurations.test.js && node tests/preOperations.test.js && node tests/documentation.test.js && node tests/inputValidation.test.js && node tests/createTable.test.js && node tests/queryBuilder.test.js && node tests/customSteps.test.js",
+    "test": "node tests/ga4EventsEnhanced.test.js && node tests/assertions.test.js && node tests/mergeSQLConfigurations.test.js && node tests/preOperations.test.js && node tests/documentation.test.js && node tests/inputValidation.test.js && node tests/createTable.test.js && node tests/queryBuilder.test.js && node tests/customSteps.test.js && node tests/enrichments.test.js && node tests/eventDataColumns.test.js && node tests/utils.test.js",
     "test:summary": "node tests/testRunner.js",
     "test:docs": "node tests/documentation.test.js",
     "test:preops": "node tests/preOperations.test.js",
@@ -28,6 +28,9 @@
     "test:createTable": "node tests/createTable.test.js",
     "test:queryBuilder": "node tests/queryBuilder.test.js",
     "test:customSteps": "node tests/customSteps.test.js",
+    "test:enrichments": "node tests/enrichments.test.js",
+    "test:eventDataColumns": "node tests/eventDataColumns.test.js",
+    "test:utils": "node tests/utils.test.js",
     "test:integration": "node tests/integration/integration.test.js",
     "release:dev": "./scripts/release-dev.sh",
     "readme": "node scripts/updateReadme.js",

package/tables/ga4EventsEnhanced/config.js

@@ -68,6 +68,10 @@ const ga4EventsEnhancedConfig = {
     // user-defined CTEs appended to the pipeline after enhanced_events
     // each entry is a queryBuilder step (raw {name, query} or structured {name, select, from, ...})
     customSteps: [],
+    // declarative external-data enrichments joined into the pipeline
+    // each entry: { name, level: 'event' | 'item', source, joinKey, columns, dedupe? }
+    // 'item' level is accepted at config time but throws at SQL gen — not yet implemented
+    enrichments: [],
 };
 
 module.exports = { ga4EventsEnhancedConfig };

package/tables/ga4EventsEnhanced/index.js

@@ -197,51 +197,46 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
         return excludedColumns;
     };
 
-    // initial step: extract data from the export tables
+    // initial step: extract data from the export tables.
+    // Explicit columns first (transforms + package-promoted + user-excluded sentinels);
+    // then pass-through entries for every GA4 export column not already accounted for.
+    // After this, Object.keys(eventDataStep.select.columns) is the complete column set of event_data.
+    const eventDataExplicitColumns = {
+        // exclude default export columns that are not needed
+        // do this first so that the columns defined later are not excluded
+        ...getExcludedColumns(),
+        event_date: helpers.eventDate,
+        event_datetime: `extract(datetime from timestamp_micros(${helpers.getEventTimestampMicros(mergedConfig.customTimestampParam)}) at time zone '${mergedConfig.timezone}')`,
+        event_custom_timestamp: mergedConfig.customTimestampParam ? helpers.getEventTimestampMicros(mergedConfig.customTimestampParam) : undefined,
+        session_id: helpers.sessionId,
+        // page details
+        page_location: helpers.unnestEventParam('page_location', 'string'),
+        page: helpers.extractPageDetails(),
+        // promote event params to columns
+        ...promotedEventParameters(),
+        event_params: helpers.filterEventParams(mergedConfig.excludedEventParams, 'exclude'),
+        // rename traffic_source for clarity
+        user_traffic_source: 'traffic_source',
+        // ecommerce
+        ecommerce: helpers.fixEcommerceStruct('ecommerce'),
+        // assign a unique row id, used for handling item-level attribution and enrichment
+        _item_row_id: itemListAttribution ? helpers.itemRowId(ecommerceEventsFilter) : 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'),
+        // prep columns for later steps
+        entrances: helpers.unnestEventParam('entrances', 'int'),
+        session_params_prep: mergedConfig.sessionParams.length > 0 ? helpers.filterEventParams(mergedConfig.sessionParams, 'include') : undefined,
+    };
+    // Pass through every GA4 export column not already covered by an explicit transform,
+    // promotion, exclusion sentinel, or value-side rename in eventDataExplicitColumns.
+    const eventDataPassThroughs = utils.buildPassThroughs(eventDataExplicitColumns, helpers.ga4ExportColumns);
     const eventDataStep = {
         name: 'event_data',
         select: {
             columns: {
-                // exclude default export columns that are not needed
-                // do this first so that the columns defined later are not excluded
-                ...getExcludedColumns(),
-                // date and time
-                event_date: helpers.eventDate,
-                event_datetime: `extract(datetime from timestamp_micros(${helpers.getEventTimestampMicros(mergedConfig.customTimestampParam)}) at time zone '${mergedConfig.timezone}')`,
-                event_timestamp: 'event_timestamp',
-                event_custom_timestamp: mergedConfig.customTimestampParam ? helpers.getEventTimestampMicros(mergedConfig.customTimestampParam) : undefined,
-                // event name
-                event_name: 'event_name',
-                // identifiers
-                session_id: helpers.sessionId,
-                user_pseudo_id: 'user_pseudo_id',
-                user_id: 'user_id',
-                // page
-                page_location: helpers.unnestEventParam('page_location', 'string'),
-                page: helpers.extractPageDetails(),
-                // event parameters and user properties
-                ...promotedEventParameters(),
-                event_params: helpers.filterEventParams(mergedConfig.excludedEventParams, 'exclude'),
-                user_properties: 'user_properties',
-                // traffic source
-                collected_traffic_source: 'collected_traffic_source',
-                session_traffic_source_last_click: 'session_traffic_source_last_click',
-                user_traffic_source: 'traffic_source',
-                // ecommerce
-                ecommerce: helpers.fixEcommerceStruct('ecommerce'),
-                items: 'items',
-                _item_row_id: itemListAttribution ? helpers.itemRowId(ecommerceEventsFilter) : 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'),
-                // prep columns for later steps
-                entrances: helpers.unnestEventParam('entrances', 'int'),
-                session_params_prep: mergedConfig.sessionParams.length > 0 ? helpers.filterEventParams(mergedConfig.sessionParams, 'include') : undefined,
-                // include all other columns from the export data
-                get '[sql]other_columns'() {
-                    const definedColumns = Object.keys(this);
-                    return `* except (${definedColumns.filter(column => helpers.isGa4ExportColumn(column)).join(', ')})`;
-                },
+                ...eventDataExplicitColumns,
+                ...eventDataPassThroughs,
             },
         },
         from: mergedConfig.sourceTable,
@@ -268,64 +263,193 @@ ${excludedEventsSQL}`,
         'group by': 'session_id',
     };
 
-    // Shared item-array CTEs (currently used by item-list attribution; will also be used by
-    // item-level data enrichments — see design_docs/planned/data-enrichments.md, Q16):
-    // 1. items_unnested: unnest items from ecommerce events, compute attribution via window function
-    // 2. items_rebuilt: re-aggregate items with attributed list fields
-    const itemListSteps = itemListAttribution ? (() => {
-        const attrExpr = helpers.itemListAttributionExpr(
-            itemListAttribution.lookbackType,
-            timestampColumn,
-            itemListAttribution.lookbackTimeMs
-        );
+    // Build enrichment-source CTEs and gather per-level join/column data. The utility routes
+    // event-level and item-level entries through separate output channels.
+    const { steps: enrichmentSteps, event: eventEnrichments, item: itemEnrichments }
+        = utils.buildEnrichments(mergedConfig.enrichments);
+
+    // Validate item-level joinKey columns and collect any event_data columns that need to
+    // be carried up to items_unnested as top-level columns (so the LEFT JOIN inside
+    // items_rebuilt can USING(...) on them). Item-struct fields are already top-level on
+    // items_unnested and need no extension.
+    const itemJoinKeysFromEventData = new Set();
+    for (const [i, e] of (mergedConfig.enrichments ?? []).entries()) {
+        const level = e.level ?? 'event';
+        if (level !== 'item') continue;
+        const joinKeys = Array.isArray(e.joinKey) ? e.joinKey : [e.joinKey];
+        for (const c of joinKeys) {
+            if (helpers.ga4ItemStructFields.includes(c)) {
+                // Already a top-level column on items_unnested.
+            } else if (c in eventDataStep.select.columns && eventDataStep.select.columns[c] !== undefined) {
+                itemJoinKeysFromEventData.add(c);
+            } else {
+                throw new Error(
+                    `config.enrichments[${i}] (name: '${e.name}') uses item-level joinKey '${c}', ` +
+                    `which is neither a field on the GA4 items struct (helpers.ga4ItemStructFields) ` +
+                    `nor a column on event_data. Valid item-level joinKeys are item-struct fields ` +
+                    `(e.g. item_id, item_category) or any event_data column (e.g. user_pseudo_id, event_date).`
+                );
+            }
+        }
+    }
+
+    // Shared item-array CTEs:
+    // 1. items_unnested: unnest items from ecommerce events; LAST_VALUE attribution window
+    //    is emitted only when itemListAttribution is configured.
+    // 2. items_rebuilt: re-aggregate items via explicit struct(...) construction;
+    //    LEFT JOIN enrich_<name> for each item-level enrichment.
+    // Activation: emitted when EITHER itemListAttribution is configured OR at least one
+    // item-level enrichment is present.
+    const itemEnrichmentsActive = itemEnrichments.joins.length > 0;
+    const itemsScaffoldActive = !!itemListAttribution || itemEnrichmentsActive;
+    const itemListSteps = itemsScaffoldActive ? (() => {
         const passthroughEvents = `event_name in ('view_item_list', 'select_item', 'view_promotion', 'select_promotion')`;
 
+        // Flatten the item struct: every standard items-struct field is selected as a
+        // top-level column of items_unnested. This makes downstream joins simpler
+        // (LEFT JOIN ... USING(item_id) works without aliasing tricks) and lets items_rebuilt
+        // reference fields as bare column names instead of `item.<col>`.
+        const itemFieldColumns = {};
+        for (const f of helpers.ga4ItemStructFields) {
+            itemFieldColumns[f] = `item.${f}`;
+        }
+
+        // Carry up any event_data joinKey columns used by item-level enrichments so the
+        // USING(...) clause in items_rebuilt can bind against top-level identifiers.
+        // Skip ones already in the base columns above (e.g. event_date is always carried).
+        const baseColumnNames = new Set(['_item_row_id', 'event_name', 'event_date', ...Object.keys(itemFieldColumns)]);
+        const extraJoinKeyColumns = {};
+        for (const c of itemJoinKeysFromEventData) {
+            if (!baseColumnNames.has(c)) {
+                extraJoinKeyColumns[c] = c;
+            }
+        }
+
+        // items_unnested base columns. The _item_list_attr struct (LAST_VALUE window) is
+        // added only when itemListAttribution is configured — when only item enrichments
+        // are active, the window function is omitted entirely for cleaner SQL.
+        const unnestedSelectColumns = {
+            '_item_row_id': '_item_row_id',
+            'event_name': 'event_name',
+            // event_date is carried forward for ability to use it in data enrichment joins
+            'event_date': 'event_date',
+            ...itemFieldColumns,
+            ...extraJoinKeyColumns,
+        };
+        if (itemListAttribution) {
+            unnestedSelectColumns._item_list_attr = helpers.itemListAttributionExpr(
+                itemListAttribution.lookbackType,
+                timestampColumn,
+                itemListAttribution.lookbackTimeMs
+            );
+        }
+
         const unnestedStep = {
             name: 'items_unnested',
-            select: {
-                columns: {
-                    '_item_row_id': '_item_row_id',
-                    'event_name': 'event_name',
-                    // event_date is carried forward for ability to use it in data enrichment joins
-                    'event_date': 'event_date',
-                    'item': 'item',
-                    '_item_list_attr': attrExpr,
-                },
-            },
+            select: { columns: unnestedSelectColumns },
             from: 'event_data, unnest(items) as item',
             where: `event_name in (${ecommerceEventsFilter})`,
         };
 
+        // Build the per-field expression map for the items struct. Seed with the canonical
+        // GA4 items-struct fields — each references the matching top-level column on
+        // items_unnested. When itemListAttribution is configured, override the three
+        // attribution entries with their package-generated coalesce-with-passthrough
+        // expressions. Item-level enrichment columns layer on top via the spread below.
+        const preItemExpressions = {};
+        for (const f of helpers.ga4ItemStructFields) {
+            preItemExpressions[f] = f;
+        }
+        if (itemListAttribution) {
+            preItemExpressions.item_list_name = `coalesce(if(${passthroughEvents}, item_list_name, _item_list_attr.item_list_name), '(not set)')`;
+            preItemExpressions.item_list_id = `coalesce(if(${passthroughEvents}, item_list_id, _item_list_attr.item_list_id), '(not set)')`;
+            preItemExpressions.item_list_index = `coalesce(if(${passthroughEvents}, item_list_index, _item_list_attr.item_list_index))`;
+        }
+
+        // Wrap overlapping item-level enrichment columns in coalesce(<enrichExpr>, <originalExpr>)
+        // so a missed JOIN falls back to the existing item field value. Purely additive
+        // columns (no overlap) pass through unchanged.
+        const wrappedItemEnrichmentColumns = {};
+        for (const [col, enrichExpr] of Object.entries(itemEnrichments.columns)) {
+            const originalExpr = preItemExpressions[col];
+            wrappedItemEnrichmentColumns[col] = originalExpr
+                ? `coalesce(${enrichExpr}, ${originalExpr})`
+                : enrichExpr;
+        }
+
+        // Final struct: standard fields first, then enrichment overrides spread on top
+        // (overlapping keys replace preItemExpressions entries; additive keys are appended).
+        const finalItemStructFields = { ...preItemExpressions, ...wrappedItemEnrichmentColumns };
+
+        const itemStructClauses = Object.entries(finalItemStructFields)
+            .map(([col, expr]) => `${expr} as ${col}`)
+            .join(',\n        ');
+
         const rebuiltStep = {
             name: 'items_rebuilt',
             select: {
                 columns: {
                     '_item_row_id': '_item_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
-      ))
-    )`,
+                    'items': `array_agg(struct(
+        ${itemStructClauses}
+      ))`,
                 },
             },
             from: 'items_unnested',
             'group by': '_item_row_id',
         };
+        // Item-level enrichment joins (only attach when present). Each enrichment's LEFT JOIN
+        // binds against top-level columns on items_unnested (item-struct fields, or event_data
+        // joinKey columns carried up via extraJoinKeyColumns above).
+        if (itemEnrichmentsActive) {
+            rebuiltStep.joins = itemEnrichments.joins;
+        }
 
         return [unnestedStep, rebuiltStep];
     })() : null;
 
     const finalColumnOrder = getFinalColumnOrder(eventDataStep, sessionDataStep);
 
-    // When item list attribution is enabled, override the items column and exclude _item_row_id
+    // When the items scaffold is active, override the items column and exclude _item_row_id
     // COALESCE handles events without items (not in ecommerce filter) where the LEFT JOIN returns NULL
     const itemListOverrides = itemListSteps ? {
         items: 'coalesce(items_rebuilt.items, event_data.items)',
     } : {};
     const itemListExcludedColumns = itemListSteps ? ['_item_row_id'] : [];
 
+    // Wrap overlapping event-level enrichment columns in coalesce(enrich_<name>.<col>, <original>)
+    // so a missed JOIN falls back to the existing value. Purely additive columns (no overlap)
+    // pass through unchanged. Source-of-original precedence matches the final SELECT's spread
+    // order: itemListOverrides first (overrides finalColumnOrder for `items`), then
+    // session_data (wins over event_data in getFinalColumnOrder when both have the column).
+    const wrappedEventEnrichmentColumns = {};
+    for (const [col, enrichExpr] of Object.entries(eventEnrichments.columns)) {
+        let originalExpr;
+        if (col in itemListOverrides) {
+            originalExpr = itemListOverrides[col];
+        } else if (col in sessionDataStep.select.columns) {
+            originalExpr = `session_data.${col}`;
+        } else if (col in eventDataStep.select.columns && eventDataStep.select.columns[col] !== undefined) {
+            originalExpr = `event_data.${col}`;
+        }
+        wrappedEventEnrichmentColumns[col] = originalExpr
+            ? `coalesce(${enrichExpr}, ${originalExpr})`
+            : enrichExpr;
+    }
+
+    // List all column names that have already been defined or should be left out
+    // Used for the final pass-through: include the rest of the coulumns that haven't been explicitly listed yet
+    const alreadyMapped = [
+        ...Object.keys(finalColumnOrder),
+        ...Object.keys(itemListOverrides),
+        ...eventEnrichments.columnNames,
+        'entrances',
+        mergedConfig.sessionParams.length > 0 ? 'session_params_prep' : undefined,
+        'data_is_final',
+        'export_type',
+        ...itemListExcludedColumns,
+    ];
+
     // Join event_data and session_data, include additional logic
     // Named 'enhanced_events' so user-supplied customSteps can reference it as a stable handle.
     const enhancedEventsStep = {
@@ -335,24 +459,11 @@ ${excludedEventsSQL}`,
                 // 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,
-                    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
-                '[sql]session_data': utils.selectOtherColumns(
-                    sessionDataStep,
-                    Object.keys(finalColumnOrder),
-                    []
-                ),
+                // event-level enrichment columns: coalesce with the original when overlapping; otherwise add.
+                ...wrappedEventEnrichmentColumns,
+                // explicit pass-throughs for the rest of event_data and session_data
+                ...utils.buildQualifiedPassThroughs(eventDataStep, alreadyMapped),
+                ...utils.buildQualifiedPassThroughs(sessionDataStep, alreadyMapped),
                 // include additional columns
                 row_inserted_timestamp: 'current_timestamp()',
                 data_is_final: 'data_is_final',
@@ -370,21 +481,22 @@ ${excludedEventsSQL}`,
                 type: 'left',
                 table: 'session_data',
                 on: 'using(session_id)'
-            }
+            },
+            // The left joins for the event-level enrichment ctes
+            ...eventEnrichments.joins,
         ],
         where: helpers.incrementalDateFilter(mergedConfig)
     };
 
     const packageSteps = [
+        ...enrichmentSteps,
         eventDataStep,
         ...(itemListSteps ?? []),
         sessionDataStep,
         enhancedEventsStep,
     ];
 
-    // Layer 2 validation: customSteps name must not collide with package step names.
-    // Reserved set is derived from packageSteps at runtime (single source of truth) — what
-    // is reserved depends on config (e.g. item_list_* exist only when itemListAttribution is on).
+    // Ensure that the custom step names don't collide with the default or data enrichment step names
     const customSteps = mergedConfig.customSteps ?? [];
     if (customSteps.length > 0) {
         const reservedNames = new Set(packageSteps.map(s => s.name));
@@ -398,6 +510,7 @@ ${excludedEventsSQL}`,
         }
     }
 
+    // Include custom steps last in the list
     const steps = [...packageSteps, ...customSteps];
 
     return utils.queryBuilder(steps);