ga4-export-fixer 0.9.0-dev.8 → 0.9.0

package/README.md

@@ -44,96 +44,100 @@ The goal of the package is to **speed up development** when building data models
 </td>
 </tr>
 <tr>
+<td valign="top">
+  <b>🧬 Data Enrichments</b><br>
+  Join external lookup data (cohorts, product master, etc.) at row level or ecommerce item level via <code>enrichments</code>
+</td>
 <td valign="top">
   <b>📐 Flexible Schema</b><br>
   Keeps the flexible structure of the original export with key fields promoted to columns for better query performance; partitioning &amp; clustering enabled
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>🤖 AI Agent Ready</b><br>
   Extensive table &amp; column descriptions for AI agents and humans
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>🔑 Session Identity Resolution</b><br>
   <code>user_id</code> resolved per session; <code>merged_user_id</code> coalesces with <code>user_pseudo_id</code>
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>📡 Session Traffic Sources</b><br>
   <code>session_first_traffic_source</code> and <code>session_traffic_source_last_click</code> computed automatically, adjusting for sessions that span midnight
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>📍 Landing Page Detection</b><br>
   Derived per session from the first page where <code>entrances > 0</code>
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>🔗 Page URL Parsing</b><br>
   Parsed <code>hostname</code>, <code>path</code>, <code>query</code>, and <code>query_params</code> from <code>page_location</code>
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>🛒 Ecommerce Data Fixes</b><br>
   Nullifies placeholder <code>transaction_id</code>; corrects <code>purchase_revenue</code> bugs
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>🏷️ Item List Attribution</b><br>
   Attributes <code>item_list_name</code>, <code>item_list_id</code>, and <code>item_list_index</code> from item selection events to downstream ecommerce events
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>⚙️ Event Parameter Handling</b><br>
   Promote event params to columns; include or exclude by name
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>📊 Session Parameters</b><br>
   Promote selected event parameters as <code>session_params</code>
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>⏱️ Custom Timestamp</b><br>
   Use a custom event parameter as primary timestamp with automatic fallback
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>🔒 Schema Lock</b><br>
   Lock table schema to a specific GA4 export date to prevent schema drift
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>✅ Data Freshness Tracking</b><br>
   <code>data_is_final</code> flag and <code>export_type</code> label on every row
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>🔍 Data Quality Assertions</b><br>
   Built-in daily assertion reconciles sessions, events, and revenue between the enhanced table and raw export
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>🔃 Selective Re-processing</b><br>
   Re-process a date range without full table rebuild using <code>incrementalStartOverride</code> and <code>incrementalEndOverride</code>
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>📑 Batch Processing</b><br>
   Process large exports in smaller batches via <code>numberOfDaysToProcess</code>
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>🕐 Timezone-Aware Datetime</b><br>
   <code>event_datetime</code> converted to a configurable IANA timezone
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>🧩 Custom Processing Steps</b><br>
   Append user-defined CTEs via <code>customSteps</code> to derive new columns or join external tables
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>🛡️ Zero Dependencies</b><br>
   No additional external dependencies added to your Dataform repository
@@ -145,7 +149,6 @@ The goal of the package is to **speed up development** when building data models
 
 Features under consideration for future releases:
 
-- Data enrichment (item-level, session-level, event-level)
 - Aggregated tables (ga4_session, ga4_ecommerce...)
 - Web and app specific default configurations
 - Custom channel grouping
@@ -169,7 +172,7 @@ Include the package in the package.json file in your Dataform repository.
 {
   "dependencies": {
     "@dataform/core": "3.0.42",
-    "ga4-export-fixer": "0.8.0"
+    "ga4-export-fixer": "0.9.0"
   }
 }
 ```
@@ -198,7 +201,8 @@ Create a new **ga4_events_enhanced** table using a **.js** file in your reposito
 const { ga4EventsEnhanced } = require('ga4-export-fixer');
 
 const config = {
-  sourceTable: constants.GA4_TABLES.MY_GA4_EXPORT
+  // using hard-coded GA4 export path
+  sourceTable: '`project.analytics_12345.events_*`'
 };
 
 ga4EventsEnhanced.createTable(publish, config);
@@ -212,6 +216,7 @@ ga4EventsEnhanced.createTable(publish, config);
 const { ga4EventsEnhanced } = require('ga4-export-fixer');
 
 const config = {
+  // GA4 export path declared, using the table reference object
   sourceTable: constants.GA4_TABLES.MY_GA4_EXPORT,
   // use dataformTableConfig to make changes to the default Dataform table configuration
   dataformTableConfig: {
@@ -290,7 +295,8 @@ js {
   const { ga4EventsEnhanced } = require('ga4-export-fixer');
 
   const config = {
-    sourceTable: ref(constants.GA4_TABLES.MY_GA4_EXPORT),
+    // using hard-coded GA4 export path
+    sourceTable: '`project.analytics_12345.events_*`',
     self: self(),
     incremental: incremental()
   };
@@ -534,13 +540,13 @@ For typical use cases this is the right tool; reach for `customSteps` only when
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `name` | string | Yes | Used in the generated `enrich_<name>` CTE name. Unique within `enrichments`. |
-| `level` | `'event'` | No, defaults to `'event'` | Join grain. Currently only `'event'` is supported (item-level enrichments will arrive in a later release). |
+| `level` | `'row'` / `'item'` | No, defaults to `'row'` | Join grain. `'row'` joins external dim data onto each row of `enhanced_events` (any column on `enhanced_events` as the key). `'item'` joins external dim data onto each item inside the `items` array (any field on the items struct or any event_data column as the key). |
 | `source` | Dataform ref / object / string | Yes | Source dim table. Inside an SQLX `js { }` block use `ref(...)`. From a `.js` definition file use a `{ schema, name }` ref object (resolved later via `ctx.ref()`) or a backtick-quoted ``` `project.dataset.table` ``` string for an external table. |
-| `joinKey` | string / string[] | Yes | Column name(s) on `enhanced_events` to join on. Composite keys (array) compile to `USING(col1, col2, ...)`. |
-| `columns` | string[] | Yes | Source columns to add to the output (excluding `joinKey`). Names matching existing columns REPLACE them. |
+| `joinKey` | string / string[] | Yes | For `level: 'row'`: column name(s) on `enhanced_events`. For `level: 'item'`: field name(s) on the items struct (e.g. `'item_id'`) or column name(s) on `event_data` (e.g. `'user_pseudo_id'`). Composite keys (array) compile to `USING(col1, col2, ...)`. |
+| `columns` | string[] | Yes | Source columns to add to the output (excluding `joinKey`). Names matching existing columns are coalesced with the original (`coalesce(enrich.col, original)`) so missed JOINs fall back to the existing value. |
 | `dedupe` | boolean | No, defaults to `false` | When `true`, wraps the source CTE in `qualify row_number() over (partition by <joinKey>) = 1` for non-unique-key dim sources. Non-deterministic which row wins; for strict needs, pre-aggregate in source SQL. |
 
-**Replace-or-add semantics.** If an enrichment column name matches an existing column on `enhanced_events` (a column promoted via `eventParamsToColumns`, a package-generated column, or a default GA4 column from the export), the enrichment value REPLACES it. If there is no overlap, the column is added.
+**Coalesce-or-add semantics.** If an enrichment column name matches an existing column on `enhanced_events` (a column promoted via `eventParamsToColumns`, a package-generated column, or a default GA4 column from the export), the enrichment value is coalesced with the original: `coalesce(enrich_<name>.<col>, <original>) as <col>`. Rows where the JOIN matches get the enrichment value; rows where it misses fall back to the existing value rather than going NULL. If there is no overlap, the column is added as a plain `enrich_<name>.<col>`.
 
 **Example** — attach user cohort labels by `user_pseudo_id` (Dataform-declared table referenced by `{ schema, name }`):
 
@@ -548,7 +554,7 @@ For typical use cases this is the right tool; reach for `customSteps` only when
 enrichments: [
     {
         name: 'cohorts',
-        level: 'event',
+        // level omitted → defaults to 'row'
         source: { schema: 'analytics', name: 'user_cohorts' },
         joinKey: 'user_pseudo_id',
         columns: ['cohort_label', 'lifecycle_stage'],
@@ -562,7 +568,7 @@ enrichments: [
 enrichments: [
     {
         name: 'segments',
-        level: 'event',
+        level: 'row',
         source: '`my-project.analytics.daily_user_segments`',
         joinKey: ['event_date', 'user_pseudo_id'],
         columns: ['segment'],
@@ -571,7 +577,7 @@ enrichments: [
 ],
 ```
 
-**Example** — fix a promoted event parameter via enrichment (replacement case):
+**Example** — fix a promoted event parameter via enrichment (coalesce case: enrichment value wins where the JOIN matches, original kept where it doesn't):
 
 ```javascript
 {
@@ -579,18 +585,34 @@ enrichments: [
     enrichments: [
         {
             name: 'titles',
-            level: 'event',
+            level: 'row',
             source: { schema: 'analytics', name: 'page_title_overrides' },
             joinKey: 'page_location',
-            columns: ['page_title'],   // overlaps the promoted column → replaces it
+            columns: ['page_title'],   // overlaps the promoted column → coalesce(enrich.page_title, event_data.page_title)
         },
     ],
 }
 ```
 
+**Example** — item-level enrichment: attach product master data to each item via `item_id`. The enrichment flows into the `items` array struct; `margin_bucket` is added as a new item-struct field, and `item_category` overlap-coalesces against the original. Item-level enrichment columns do NOT appear at the row grain — they live inside `items[].<col>`:
+
+```javascript
+enrichments: [
+    {
+        name: 'products',
+        level: 'item',
+        source: { schema: 'analytics', name: 'product_master' },
+        joinKey: 'item_id',                                  // joins on item.item_id
+        columns: ['margin_bucket', 'item_category'],         // margin_bucket is additive; item_category overlap-coalesces
+    },
+],
+```
+
+For `level: 'item'`, valid `joinKey` values are any field on the GA4 items struct (`item_id`, `item_category`, etc.) or any column on `event_data` (`user_pseudo_id`, `event_date`, etc.). A row-level and an item-level enrichment may share the same column name (e.g. both writing `cohort`) — the two columns target structurally distinct slots (`enhanced_events.cohort` at row grain vs `items[].cohort` inside the items array) and are not in collision.
+
 > **Note:** Each enrichment generates a CTE named `enrich_<name>` at the top of the pipeline. The `enrich_*` namespace is part of the reserved-names contract — `customSteps` cannot use these names. The active reserved set includes only the names of enrichments actually configured.
 
-> **Note:** Enrichment columns get auto-generated descriptions (`Added by enrichment '<name>' (joined on <joinKey> from <source>).` for new columns; `Replaced by enrichment '<name>' (...). Original: <description>` for replacements). User-supplied `dataformTableConfig.columns` overrides win — the auto-generated description is the default.
+> **Note:** Row-level enrichment columns get auto-generated descriptions (`Added by enrichment '<name>' (joined on <joinKey> from <source>).` for new columns; `Coalesced by enrichment '<name>' (...; falls back to original on missed JOIN). Original: <description>` for overlapping columns). User-supplied `dataformTableConfig.columns` overrides win — the auto-generated description is the default. Item-level enrichment columns do not receive auto-generated descriptions (BigQuery does not surface per-field descriptions on STRUCT-array fields cleanly through Dataform's column-description mechanism).
 
 > **Note:** `joinKey` and `columns` entries must be plain SQL identifiers — inline aliases like `'id as user_id'` are rejected at validation time. If your dim source uses a different column name, alias it in an upstream Dataform view and point `source` at that view.
 

package/documentation.js

@@ -173,8 +173,8 @@ const getColumnDescriptions = (config, columnMetadata) => {
     // Item-level enrichments are not yet supported and throw at SQL gen time — skip here.
     if (config && Array.isArray(config.enrichments) && config.enrichments.length > 0) {
         config.enrichments.forEach(e => {
-            const level = e.level ?? 'event';
-            if (level !== 'event') return;
+            const level = e.level ?? 'row';
+            if (level !== 'row') return;
             const joinKeys = Array.isArray(e.joinKey) ? e.joinKey : [e.joinKey];
             const joinKeyText = joinKeys.join(', ');
             const sourceText = renderEnrichmentSource(e.source);
@@ -186,7 +186,7 @@ const getColumnDescriptions = (config, columnMetadata) => {
                         ? existing.description
                         : null;
                 const newDesc = existingText
-                    ? `Replaced by enrichment '${e.name}' (joined on ${joinKeyText} from ${sourceText}). Original: ${existingText}`
+                    ? `Coalesced by enrichment '${e.name}' (joined on ${joinKeyText} from ${sourceText}; falls back to original on missed JOIN). Original: ${existingText}`
                     : `Added by enrichment '${e.name}' (joined on ${joinKeyText} from ${sourceText}).`;
                 // If the original was a struct-shaped entry, preserve the structure but replace the description.
                 // Otherwise, set as a plain string.

package/helpers/ga4Transforms.js

@@ -140,6 +140,55 @@ const ga4ExportColumns = [
  */
 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.
  *
@@ -186,13 +235,17 @@ const itemListAttributionExpr = (lookbackType, timestampColumn, lookbackTimeMs)
     frameBounds = `range between ${lookbackMicros} preceding and current row`;
   }
 
-  return `last_value(
+  // Suppress attribution for:
+  //   - refund events (outside the selection-driven journey window)
+  //   - unconsented events (user_pseudo_id is NULL) — attribution requires a visitor
+  //     identity to stitch select_* events to later receivers within the same visitor.
+  return `if(event_name = 'refund' or user_pseudo_id is null, null, last_value(
       if(${selectEvents}, ${structExpr}, null) ignore nulls
     ) over(
       partition by ${partitionBy}
       order by ${timestampColumn} asc
       ${frameBounds}
-    )`;
+    ))`;
 };
 
 /**
@@ -209,6 +262,10 @@ const itemListAttributionExpr = (lookbackType, timestampColumn, lookbackTimeMs)
  * the rows are interchangeable, so arbitrary row number assignment between them
  * produces the same result.
  *
+ * Unconsented events (user_pseudo_id is NULL) use an empty-string sentinel inside
+ * concat — without it, CONCAT NULL-propagates and the row_id becomes NULL, which
+ * would prevent enrichments from applying to such events.
+ *
  * @param {string} ecommerceEventsFilter - Comma-separated, quoted list of event names
  *        (e.g., "'purchase', 'add_to_cart'").
  * @returns {string} SQL expression that evaluates to the row id or NULL.
@@ -217,7 +274,7 @@ const itemRowId = (ecommerceEventsFilter) => {
   return `if(
       event_name in (${ecommerceEventsFilter}),
       farm_fingerprint(concat(
-        user_pseudo_id,
+        ifnull(user_pseudo_id, ''),
         cast(event_timestamp as string),
         event_name,
         to_json_string(items),
@@ -257,6 +314,8 @@ module.exports = {
   isFinalData,
   ga4ExportColumns,
   isGa4ExportColumn,
+  ga4ItemStructFields,
+  isGa4ItemStructField,
   getGa4ExportType,
   itemListAttributionExpr,
   itemRowId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ga4-export-fixer",
-  "version": "0.9.0-dev.8",
+  "version": "0.9.0",
   "description": "",
   "main": "index.js",
   "files": [

package/tables/ga4EventsEnhanced/config.js

@@ -69,8 +69,9 @@ const ga4EventsEnhancedConfig = {
     // 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
+    // each entry: { name, source, joinKey, columns, level?, dedupe? }
+    // `level` is optional — defaults to 'row' (one row of the enclosing table per join match).
+    // 'item' targets the items[] array (GA4-specific, ecommerce events only).
     enrichments: [],
 };
 

package/tables/ga4EventsEnhanced/index.js

@@ -162,8 +162,18 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
 
     // item list attribution config
     const itemListAttribution = mergedConfig.itemListAttribution;
-    const ecommerceEventsFilter = itemListAttribution
-        ? helpers.ga4EcommerceEvents.filter(e => e !== 'refund').map(e => `'${e}'`).join(', ')
+
+    // Build enrichment-source CTEs and gather per-level join/column data. The utility routes
+    // row-level and item-level entries through separate output channels. Done up here so the
+    // items-scaffold activation state is known before building event_data (which needs
+    // _item_row_id when the scaffold is active for any reason).
+    const { steps: enrichmentSteps, row: rowEnrichments, item: itemEnrichments }
+        = utils.buildEnrichments(mergedConfig.enrichments);
+    const itemEnrichmentsActive = itemEnrichments.joins.length > 0;
+    const itemsScaffoldActive = !!itemListAttribution || itemEnrichmentsActive;
+
+    const ecommerceEventsFilter = itemsScaffoldActive
+        ? helpers.ga4EcommerceEvents.map(e => `'${e}'`).join(', ')
         : null;
 
     // auto-adjust bufferDays for time-based item list attribution lookback
@@ -220,7 +230,7 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
         // 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,
+        _item_row_id: itemsScaffoldActive ? 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'),
@@ -263,74 +273,183 @@ ${excludedEventsSQL}`,
         'group by': 'session_id',
     };
 
+    // 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 ?? 'row';
+        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, 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
-        );
+    // 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 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
+        const baseColumnNames = new Set(['_item_row_id', 'event_name', ...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',
+            ...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.
+        // References are qualified with `items_unnested.` so that overlapping item-level
+        // enrichments (which JOIN against enrich_<name> CTEs that may share column names)
+        // do not produce ambiguous bare-column references.
+        const preItemExpressions = {};
+        for (const f of helpers.ga4ItemStructFields) {
+            preItemExpressions[f] = `items_unnested.${f}`;
+        }
+        if (itemListAttribution) {
+            preItemExpressions.item_list_name = `coalesce(if(${passthroughEvents}, items_unnested.item_list_name, _item_list_attr.item_list_name), '(not set)')`;
+            preItemExpressions.item_list_id = `coalesce(if(${passthroughEvents}, items_unnested.item_list_id, _item_list_attr.item_list_id), '(not set)')`;
+            preItemExpressions.item_list_index = `coalesce(if(${passthroughEvents}, items_unnested.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
-    // COALESCE handles events without items (not in ecommerce filter) where the LEFT JOIN returns NULL
+    // When the items scaffold is active, override the items column and exclude _item_row_id.
+    // ifnull(..., []) preserves the empty-array shape for events that have no items_rebuilt
+    // match (non-ecommerce events, or ecommerce events with empty items arrays). The empty
+    // array literal is type-inferred from items_rebuilt.items, which includes any item-level
+    // enrichment columns — so additive enrichments don't cause a struct-schema mismatch.
     const itemListOverrides = itemListSteps ? {
-        items: 'coalesce(items_rebuilt.items, event_data.items)',
+        items: 'ifnull(items_rebuilt.items, [])',
     } : {};
     const itemListExcludedColumns = itemListSteps ? ['_item_row_id'] : [];
 
-    // Build enrichment-source CTEs and gather event-level join/column data. Item-level
-    // enrichments throw "not yet supported" inside the utility — they will arrive in a later release.
-    const { steps: enrichmentSteps, joins: enrichmentJoins, columns: enrichmentColumns,
-            columnNames: enrichmentColumnNames } = utils.buildEnrichments(mergedConfig.enrichments);
+    // Wrap overlapping row-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 wrappedRowEnrichmentColumns = {};
+    for (const [col, enrichExpr] of Object.entries(rowEnrichments.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}`;
+        }
+        wrappedRowEnrichmentColumns[col] = originalExpr
+            ? `coalesce(${enrichExpr}, ${originalExpr})`
+            : enrichExpr;
+    }
 
-    // Build the set of columns the outer SELECT already maps explicitly (so wildcards skip them)
-    // plus internal-only columns that should never reach enhanced_events.
+    // 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),
-        ...enrichmentColumnNames,
+        ...rowEnrichments.columnNames,
         'entrances',
         mergedConfig.sessionParams.length > 0 ? 'session_params_prep' : undefined,
         'data_is_final',
@@ -347,8 +466,8 @@ ${excludedEventsSQL}`,
                 // get the most important columns in the correct order
                 ...finalColumnOrder,
                 ...itemListOverrides,
-                // event-level enrichment columns: override matching explicit columns; new columns added.
-                ...enrichmentColumns,
+                // row-level enrichment columns: coalesce with the original when overlapping; otherwise add.
+                ...wrappedRowEnrichmentColumns,
                 // explicit pass-throughs for the rest of event_data and session_data
                 ...utils.buildQualifiedPassThroughs(eventDataStep, alreadyMapped),
                 ...utils.buildQualifiedPassThroughs(sessionDataStep, alreadyMapped),
@@ -370,8 +489,8 @@ ${excludedEventsSQL}`,
                 table: 'session_data',
                 on: 'using(session_id)'
             },
-            // Event-level enrichment joins go last so they apply on top of the package's own joins.
-            ...enrichmentJoins,
+            // The left joins for the row-level enrichment ctes
+            ...rowEnrichments.joins,
         ],
         where: helpers.incrementalDateFilter(mergedConfig)
     };
@@ -384,10 +503,7 @@ ${excludedEventsSQL}`,
         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,
-    // and enrich_* names exist only when enrichments are configured).
+    // 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));
@@ -401,6 +517,7 @@ ${excludedEventsSQL}`,
         }
     }
 
+    // Include custom steps last in the list
     const steps = [...packageSteps, ...customSteps];
 
     return utils.queryBuilder(steps);

package/tables/ga4EventsEnhanced/validation.js

@@ -201,11 +201,11 @@ const validateEnhancedEventsConfig = (config, options = {}) => {
         }
     }
 
-    // customSteps - optional array of queryBuilder step objects appended to the pipeline
-    // Layer 1 (config shape): array, objects with non-empty name, no duplicates within customSteps.
+    // customSteps - optional array of queryBuilder step objects appended to the pipeline.
+    // Config-shape checks only: array, objects with non-empty name, no duplicates within customSteps.
     // Step-shape validation (clause keys, etc.) deferred to queryBuilder.
-    // Collision-with-package-names check deferred to _generateEnhancedEventsSQL (Layer 2),
-    // since the reserved set is config-dependent (e.g. item_list_* only exist when itemListAttribution is on).
+    // Collision-with-package-names check deferred to _generateEnhancedEventsSQL, since the
+    // reserved set is config-dependent (e.g. item_list_* only exist when itemListAttribution is on).
     if (config.customSteps !== undefined) {
         if (!Array.isArray(config.customSteps)) {
             throw new Error(`config.customSteps must be an array. Received: ${JSON.stringify(config.customSteps)}`);
@@ -227,14 +227,14 @@ const validateEnhancedEventsConfig = (config, options = {}) => {
     }
 
     // enrichments - optional array of declarative external-data enrichment specs.
-    // This block performs Layer 1 (config-shape) checks. Layer 2 checks (reserved-name collision
-    // + item-level deferral throw) live in _generateEnhancedEventsSQL — the reserved set is
-    // config-dependent and the item-level deferral throws there once the SQL is built.
+    // Config-shape checks only. Reserved-name collision and item-level joinKey resolution
+    // happen in _generateEnhancedEventsSQL, where the reserved set and item-level join targets
+    // are derived from the resolved config.
     if (config.enrichments !== undefined) {
         if (!Array.isArray(config.enrichments)) {
             throw new Error(`config.enrichments must be an array. Received: ${JSON.stringify(config.enrichments)}`);
         }
-        const validLevels = ['event', 'item'];
+        const validLevels = ['row', 'item'];
         const seenNames = new Set();
         for (let i = 0; i < config.enrichments.length; i++) {
             const entry = config.enrichments[i];

package/utils.js

@@ -515,48 +515,53 @@ const buildPassThroughs = (explicitColumns, sourceColumns) => {
 
 /**
  * Builds the per-enrichment CTE definitions, JOIN clauses, and column-name mappings for the
- * declarative `enrichments` feature.
+ * declarative `enrichments` feature. Routes row-level and item-level entries through
+ * separate output channels so the caller can attach them to different downstream CTEs.
  *
  * Pure config-to-data mapping. No knowledge of downstream CTEs or specific table modules —
  * intended to be called by any table module that exposes an `enrichments` config field.
  *
- * Encapsulates two generation-time throws:
- *   - level: 'item' (not yet supported; deferred per design_docs/planned/data-enrichments.md Q15).
- *   - Enrichment-vs-enrichment column collisions (two enrichments targeting the same column).
+ * Encapsulates one generation-time throw:
+ *   - Same-level enrichment-vs-enrichment column collisions (two row-level enrichments or
+ *     two item-level enrichments targeting the same column). Cross-level same-name is allowed —
+ *     the two columns target structurally distinct slots (e.g. `enhanced_events.<col>` vs
+ *     `items[].<col>`).
  *
  * @param {Array<Object>} enrichments - Validated enrichment entries. Each entry has fields:
- *   { name, level, source, joinKey, columns, dedupe? } per data-enrichments.md Q8.
- * @returns {Object} A struct with five fields:
- *   - `steps` — array of queryBuilder source-CTE step definitions (one `enrich_<name>` per entry).
- *   - `joins` — array of LEFT JOIN clauses to attach downstream (one per entry).
- *   - `columns` — map of `{ <enrichmentColumn>: 'enrich_<name>.<col>' }` for spreading into a
- *     downstream SELECT's `select.columns`.
- *   - `columnNames` — Set of all enrichment column names (used by callers for overlap detection
- *     against downstream CTEs).
- *   - `columnOwner` — map of `{ <column>: { i, name } }` recording which enrichment owns each
- *     column; preserved for diagnostics.
+ *   { name, source, joinKey, columns, level?, dedupe? }. `level` is 'row' (default) or 'item'.
+ *   'row' means one row of the enclosing table per join match; 'item' targets a nested array
+ *   (currently only the GA4 items[] array).
+ * @returns {Object} A struct with four fields:
+ *   - `steps` — array of queryBuilder source-CTE step definitions (one `enrich_<name>` per
+ *     entry, regardless of level — all source CTEs go to the top of the pipeline).
+ *   - `row` — { joins, columns, columnNames } for row-level enrichments. Caller attaches
+ *     `joins` to the row-grained downstream CTE (e.g. `enhanced_events`) and spreads `columns`
+ *     into that CTE's `select.columns`.
+ *   - `item` — { joins, columns, columnNames } for item-level enrichments. Caller attaches
+ *     `joins` to the item-grained downstream CTE (e.g. `items_rebuilt`) and folds `columns`
+ *     into that CTE's struct construction.
+ *   - `columnOwner` — map of `{ <column>: { i, name, level } }` recording which enrichment
+ *     owns each column. The `level` field distinguishes cross-level same-name entries.
  *
- * @throws {Error} If any entry has `level: 'item'` (with a pointer to data-enrichments.md).
- * @throws {Error} If two enrichments target the same column name (with both enrichment names).
+ * @throws {Error} If two same-level enrichments target the same column name (with both
+ *   enrichment names and the conflicting column in the error message).
  *
  * @example
- *   const { steps, joins, columns, columnNames } = buildEnrichments(config.enrichments);
+ *   const { steps, row, item } = buildEnrichments(config.enrichments);
+ *   // row.joins → attach to enhanced_events; row.columns → spread into enhanced_events
+ *   // item.joins → attach to items_rebuilt; item.columns → fold into items struct
  */
 const buildEnrichments = (enrichments) => {
     const steps = [];
-    const joins = [];
-    const columns = {};
-    const columnNames = new Set();
+    const channels = {
+        row: { joins: [], columns: {}, columnNames: new Set() },
+        item: { joins: [], columns: {}, columnNames: new Set() },
+    };
     const columnOwner = {};
 
     for (const [i, e] of (enrichments ?? []).entries()) {
-        const level = e.level ?? 'event';
-        if (level === 'item') {
-            throw new Error(
-                `config.enrichments[${i}] uses level: 'item', which is not yet supported in this version. ` +
-                `Item-level enrichments will ship in a future release; see design_docs/planned/data-enrichments.md.`
-            );
-        }
+        const level = e.level ?? 'row';
+        const channel = channels[level];
         const joinKeys = Array.isArray(e.joinKey) ? e.joinKey : [e.joinKey];
         const cteName = `enrich_${e.name}`;
 
@@ -573,24 +578,29 @@ const buildEnrichments = (enrichments) => {
         }
         steps.push(sourceStep);
 
-        joins.push({ type: 'left', table: cteName, on: `using(${joinKeys.join(', ')})` });
+        channel.joins.push({ type: 'left', table: cteName, on: `using(${joinKeys.join(', ')})` });
 
         for (const c of e.columns) {
-            if (columnNames.has(c)) {
+            // Same-level collision throw. Cross-level same-name is allowed because the two
+            // columns target structurally distinct output slots (event_data vs items[]).
+            if (channel.columnNames.has(c)) {
                 const owner = columnOwner[c];
                 throw new Error(
                     `config.enrichments[${i}] (name: '${e.name}') and config.enrichments[${owner.i}] ` +
-                    `(name: '${owner.name}') both target column '${c}'. ` +
-                    `Two enrichments cannot write the same column; rename one in source SQL or pick a different name.`
+                    `(name: '${owner.name}') both target column '${c}' at level '${level}'. ` +
+                    `Two enrichments cannot write the same column at the same level; rename one in source SQL or pick a different name.`
                 );
             }
-            columns[c] = `${cteName}.${c}`;
-            columnNames.add(c);
-            columnOwner[c] = { i, name: e.name };
+            channel.columns[c] = `${cteName}.${c}`;
+            channel.columnNames.add(c);
+            // columnOwner is keyed by column name; if the same name appears at different
+            // levels, the second-writer entry wins, but we record level so diagnostics
+            // distinguish them. Same-level collisions throw above before reaching here.
+            columnOwner[c] = { i, name: e.name, level };
         }
     }
 
-    return { steps, joins, columns, columnNames, columnOwner };
+    return { steps, row: channels.row, item: channels.item, columnOwner };
 };