ga4-export-fixer 0.8.0-dev.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ga4-export-fixer",
-  "version": "0.8.0-dev.1",
+  "version": "0.8.0",
   "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",
+    "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:summary": "node tests/testRunner.js",
     "test:docs": "node tests/documentation.test.js",
     "test:preops": "node tests/preOperations.test.js",
@@ -27,6 +27,7 @@
     "test:assertions": "node tests/assertions.test.js",
     "test:createTable": "node tests/createTable.test.js",
     "test:queryBuilder": "node tests/queryBuilder.test.js",
+    "test:customSteps": "node tests/customSteps.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

@@ -1,70 +1,73 @@
-const { baseConfig } = require('../../defaultConfig.js');
-
-/*
-The default configuration for the GA4 Events Enhanced table.
-*/
-const ga4EventsEnhancedConfig = {
-    ...baseConfig,
-    sourceTable: undefined,
-    sourceTableType: 'GA4_EXPORT', // used with pre operations to detect if ga4 export specific pre operations are needed
-    // optional but recommended
-    schemaLock: undefined,
-    // only used with js tables
-    dataformTableConfig: {
-        type: 'incremental',
-        bigquery: {
-            partitionBy: 'event_date',
-            clusterBy: ['event_name', 'session_id', 'page_location', 'data_is_final'],
-            labels: {
-                'ga4_export_fixer': 'true'
-            }
-        },
-        onSchemaChange: 'EXTEND',
-        tags: ['ga4_export_fixer'],
-    },
-    // optional
-    includedExportTypes: {
-        daily: true,
-        fresh: false,
-        intraday: true,
-    },
-    timezone: 'Etc/UTC',
-    customTimestampParam: undefined,
-    dataIsFinal: {
-        detectionMethod: 'DAY_THRESHOLD', // 'EXPORT_TYPE' or 'DAY_THRESHOLD'
-        dayThreshold: 3 // only used if detectionMethod is 'DAY_THRESHOLD'
-        // 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
-    defaultExcludedEventParams: [
-        'page_location',
-        'ga_session_id',
-        //'custom_event_timestamp', // removed if customTimestampParam is used
-    ],
-    excludedEventParams: [],
-    eventParamsToColumns: [
-        //{name: 'page_location', type: 'string', columnName: 'page_location2'},
-    ],
-    sessionParams: [],
-    defaultExcludedEvents: [],
-    // session_start and first_visit are excluded via the excludedEvents array
-    // this allows the user to include them if needed
-    excludedEvents: [
-        'session_start',
-        'first_visit'
-    ],
-    defaultExcludedColumns: [
-        'event_dimensions', // legacy column, not needed
-        'traffic_source', // renamed to user_traffic_source
-        'session_id'
-    ],
-    // exclude these columns when extracting raw data from the export tables
-    excludedColumns: [],
-};
-
-module.exports = { ga4EventsEnhancedConfig };
+const { baseConfig } = require('../../defaultConfig.js');
+
+/*
+The default configuration for the GA4 Events Enhanced table.
+*/
+const ga4EventsEnhancedConfig = {
+    ...baseConfig,
+    sourceTable: undefined,
+    sourceTableType: 'GA4_EXPORT', // used with pre operations to detect if ga4 export specific pre operations are needed
+    // optional but recommended
+    schemaLock: undefined,
+    // only used with js tables
+    dataformTableConfig: {
+        type: 'incremental',
+        bigquery: {
+            partitionBy: 'event_date',
+            clusterBy: ['event_name', 'session_id', 'page_location', 'data_is_final'],
+            labels: {
+                'ga4_export_fixer': 'true'
+            }
+        },
+        onSchemaChange: 'EXTEND',
+        tags: ['ga4_export_fixer'],
+    },
+    // optional
+    includedExportTypes: {
+        daily: true,
+        fresh: false,
+        intraday: true,
+    },
+    timezone: 'Etc/UTC',
+    customTimestampParam: undefined,
+    dataIsFinal: {
+        detectionMethod: 'DAY_THRESHOLD', // 'EXPORT_TYPE' or 'DAY_THRESHOLD'
+        dayThreshold: 3 // only used if detectionMethod is 'DAY_THRESHOLD'
+        // 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
+    defaultExcludedEventParams: [
+        'page_location',
+        'ga_session_id',
+        //'custom_event_timestamp', // removed if customTimestampParam is used
+    ],
+    excludedEventParams: [],
+    eventParamsToColumns: [
+        //{name: 'page_location', type: 'string', columnName: 'page_location2'},
+    ],
+    sessionParams: [],
+    defaultExcludedEvents: [],
+    // session_start and first_visit are excluded via the excludedEvents array
+    // this allows the user to include them if needed
+    excludedEvents: [
+        'session_start',
+        'first_visit'
+    ],
+    defaultExcludedColumns: [
+        'event_dimensions', // legacy column, not needed
+        'traffic_source', // renamed to user_traffic_source
+        'session_id'
+    ],
+    // exclude these columns when extracting raw data from the export tables
+    excludedColumns: [],
+    // 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: [],
+};
+
+module.exports = { ga4EventsEnhancedConfig };

package/tables/ga4EventsEnhanced/index.js

@@ -324,8 +324,9 @@ ${excludedEventsSQL}`,
     const itemListExcludedColumns = itemListSteps ? ['_item_list_attribution_row_id'] : [];
 
     // Join event_data and session_data, include additional logic
-    const finalStep = {
-        name: 'final',
+    // Named 'enhanced_events' so user-supplied customSteps can reference it as a stable handle.
+    const enhancedEventsStep = {
+        name: 'enhanced_events',
         select: {
             columns: {
                 // get the most important columns in the correct order
@@ -371,13 +372,31 @@ ${excludedEventsSQL}`,
         where: helpers.incrementalDateFilter(mergedConfig)
     };
 
-    const steps = [
+    const packageSteps = [
         eventDataStep,
         ...(itemListSteps ?? []),
         sessionDataStep,
-        finalStep,
+        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).
+    const customSteps = mergedConfig.customSteps ?? [];
+    if (customSteps.length > 0) {
+        const reservedNames = new Set(packageSteps.map(s => s.name));
+        for (const [i, step] of customSteps.entries()) {
+            if (reservedNames.has(step.name)) {
+                throw new Error(
+                    `config.customSteps[${i}].name '${step.name}' collides with a reserved package CTE name. ` +
+                    `Reserved names (active for this config): ${[...reservedNames].join(', ')}. Choose a different name.`
+                );
+            }
+        }
+    }
+
+    const steps = [...packageSteps, ...customSteps];
+
     return utils.queryBuilder(steps);
 };