ga4-export-fixer 0.9.0-dev.15 → 0.9.0-dev.17

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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ga4-export-fixer",
-  "version": "0.9.0-dev.15",
+  "version": "0.9.0-dev.17",
   "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

@@ -164,10 +164,10 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
     const itemListAttribution = mergedConfig.itemListAttribution;
 
     // Build enrichment-source CTEs and gather per-level join/column data. The utility routes
-    // event-level and item-level entries through separate output channels. Done up here so the
+    // 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, event: eventEnrichments, item: itemEnrichments }
+    const { steps: enrichmentSteps, row: rowEnrichments, item: itemEnrichments }
         = utils.buildEnrichments(mergedConfig.enrichments);
     const itemEnrichmentsActive = itemEnrichments.joins.length > 0;
     const itemsScaffoldActive = !!itemListAttribution || itemEnrichmentsActive;
@@ -279,7 +279,7 @@ ${excludedEventsSQL}`,
     // items_unnested and need no extension.
     const itemJoinKeysFromEventData = new Set();
     for (const [i, e] of (mergedConfig.enrichments ?? []).entries()) {
-        const level = e.level ?? 'event';
+        const level = e.level ?? 'row';
         if (level !== 'item') continue;
         const joinKeys = Array.isArray(e.joinKey) ? e.joinKey : [e.joinKey];
         for (const c of joinKeys) {
@@ -424,13 +424,13 @@ ${excludedEventsSQL}`,
     } : {};
     const itemListExcludedColumns = itemListSteps ? ['_item_row_id'] : [];
 
-    // Wrap overlapping event-level enrichment columns in coalesce(enrich_<name>.<col>, <original>)
+    // 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 wrappedEventEnrichmentColumns = {};
-    for (const [col, enrichExpr] of Object.entries(eventEnrichments.columns)) {
+    const wrappedRowEnrichmentColumns = {};
+    for (const [col, enrichExpr] of Object.entries(rowEnrichments.columns)) {
         let originalExpr;
         if (col in itemListOverrides) {
             originalExpr = itemListOverrides[col];
@@ -439,7 +439,7 @@ ${excludedEventsSQL}`,
         } else if (col in eventDataStep.select.columns && eventDataStep.select.columns[col] !== undefined) {
             originalExpr = `event_data.${col}`;
         }
-        wrappedEventEnrichmentColumns[col] = originalExpr
+        wrappedRowEnrichmentColumns[col] = originalExpr
             ? `coalesce(${enrichExpr}, ${originalExpr})`
             : enrichExpr;
     }
@@ -449,7 +449,7 @@ ${excludedEventsSQL}`,
     const alreadyMapped = [
         ...Object.keys(finalColumnOrder),
         ...Object.keys(itemListOverrides),
-        ...eventEnrichments.columnNames,
+        ...rowEnrichments.columnNames,
         'entrances',
         mergedConfig.sessionParams.length > 0 ? 'session_params_prep' : undefined,
         'data_is_final',
@@ -466,8 +466,8 @@ ${excludedEventsSQL}`,
                 // get the most important columns in the correct order
                 ...finalColumnOrder,
                 ...itemListOverrides,
-                // event-level enrichment columns: coalesce with the original when overlapping; otherwise add.
-                ...wrappedEventEnrichmentColumns,
+                // 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),
@@ -489,8 +489,8 @@ ${excludedEventsSQL}`,
                 table: 'session_data',
                 on: 'using(session_id)'
             },
-            // The left joins for the event-level enrichment ctes
-            ...eventEnrichments.joins,
+            // The left joins for the row-level enrichment ctes
+            ...rowEnrichments.joins,
         ],
         where: helpers.incrementalDateFilter(mergedConfig)
     };

package/tables/ga4EventsEnhanced/validation.js

@@ -234,7 +234,7 @@ const validateEnhancedEventsConfig = (config, options = {}) => {
         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,25 +515,27 @@ const buildPassThroughs = (explicitColumns, sourceColumns) => {
 
 /**
  * Builds the per-enrichment CTE definitions, JOIN clauses, and column-name mappings for the
- * declarative `enrichments` feature. Routes event-level and item-level entries through
+ * 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 one generation-time throw:
- *   - Same-level enrichment-vs-enrichment column collisions (two event-level enrichments or
+ *   - 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 (`enhanced_events.<col>` vs
+ *     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? }. `level` is 'event' (default) or 'item'.
+ *   { 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).
- *   - `event` — { joins, columns, columnNames } for event-level enrichments. Caller attaches
- *     `joins` to the event-grained downstream CTE (e.g. `enhanced_events`) and spreads `columns`
+ *   - `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`
@@ -545,20 +547,20 @@ const buildPassThroughs = (explicitColumns, sourceColumns) => {
  *   enrichment names and the conflicting column in the error message).
  *
  * @example
- *   const { steps, event, item } = buildEnrichments(config.enrichments);
- *   // event.joins → attach to enhanced_events; event.columns → spread into enhanced_events
+ *   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 channels = {
-        event: { joins: [], columns: {}, columnNames: new Set() },
+        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';
+        const level = e.level ?? 'row';
         const channel = channels[level];
         const joinKeys = Array.isArray(e.joinKey) ? e.joinKey : [e.joinKey];
         const cteName = `enrich_${e.name}`;
@@ -598,7 +600,7 @@ const buildEnrichments = (enrichments) => {
         }
     }
 
-    return { steps, event: channels.event, item: channels.item, columnOwner };
+    return { steps, row: channels.row, item: channels.item, columnOwner };
 };