ga4-export-fixer 0.6.1 → 0.6.2-dev.1

package/README.md

@@ -20,6 +20,7 @@ The goal of the package is to **speed up development** when building data models
 - [Usage](#usage)
   - [Create GA4 Events Enhanced Table](#create-ga4-events-enhanced-table)
   - [Configuration Object](#configuration-object)
+  - [Assertions](#assertions)
   - [Creating Incremental Downstream Tables from ga4_events_enhanced](#creating-incremental-downstream-tables-from-ga4_events_enhanced)
   - [Helpers](#helpers)
 - [License](#license)
@@ -411,6 +412,7 @@ The boundary between fresh and intraday is timestamp-based because the fresh exp
 | `preOperations.incrementalEndOverride`     | string (SQL date) | `undefined`          | Override the incremental end date to re-process a specific range                                                                                                                                    |
 | `preOperations.numberOfDaysToProcess`      | integer           | `undefined`          | Limit each run to N days of data. When set, the end date becomes `start + N - 1` (capped at `current_date()`). When `undefined`, `dateRangeEnd` is used as-is. `incrementalEndOverride` takes priority  |
 
+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)'`).
 
 <a id="eventParamsToColumns"></a>
 
@@ -443,7 +445,64 @@ 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)'`).
+### Assertions
+
+The package includes built-in data quality assertions that can be automatically created alongside the enhanced events table. Pass Dataform's `assert` function as the third argument to `createTable`:
+
+```javascript
+ga4EventsEnhanced.createTable(publish, config, { assert });
+```
+
+This creates the table along with the default-enabled assertions, using the same configuration:
+
+| Assertion | Name | Enabled by default | Description |
+| --------- | ---- | ------------------ | ----------- |
+| `dailyQuality` | `{tableName}_daily_quality` | Yes | Compares session count, event count, and item revenue per day between the enhanced table and raw export. Detects missing days, count mismatches, and non-final data inflation |
+| `itemRevenue` | `{tableName}_item_revenue` | No (opt-in) | Reconciles item_revenue at the (event_date, item_id) grain between the enhanced table and raw export |
+
+Assertions inherit the table's schema and tags from `dataformTableConfig`. Each assertion queries the last 5 days of data.
+
+#### Selective Assertions
+
+Enable opt-in assertions by setting them to `true`, or disable default-enabled ones by setting them to `false`:
+
+```javascript
+ga4EventsEnhanced.createTable(publish, config, {
+    assert,
+    assertions: { dailyQuality: true, itemRevenue: true },
+});
+```
+
+#### Assertion Config Overrides
+
+Override the assertion's Dataform configuration (name, schema, tags):
+
+```javascript
+ga4EventsEnhanced.createTable(publish, config, {
+    assert,
+    assertions: {
+        dailyQuality: { tags: ['data_quality', 'ga4_export_fixer'] },
+    },
+});
+```
+
+#### Standalone Assertions (SQLX Deployment)
+
+For SQLX deployments or when you need full control, assertions can also be used as standalone SQL generators:
+
+```javascript
+const { ga4EventsEnhanced } = require('ga4-export-fixer');
+
+assert('daily_quality_check', {
+    schema: 'analytics_123456789',
+    tags: ['ga4_export_fixer'],
+}).query(ctx => {
+    return ga4EventsEnhanced.assertions.dailyQuality(
+        ctx.ref('ga4_events_enhanced_123456789'),
+        { ...config, sourceTable: ctx.ref(config.sourceTable) }
+    );
+});
+```
 
 ### Creating Incremental Downstream Tables from ga4_events_enhanced
 

package/createTable.js

@@ -17,9 +17,15 @@ const preOperations = require('./preOperations.js');
  *   @param {Function} tableModule.generateSql - (mergedConfig) => string.
  *   @param {Function} tableModule.getColumnDescriptions - (mergedConfig) => Dataform columns object.
  *   @param {Function} tableModule.getTableDescription - (mergedConfig) => string.
+ *   @param {Object}   [tableModule.assertions] - Optional assertion definitions keyed by name.
+ *     Each value: { generate: (tableRef, mergedConfig) => string, defaultName: string }.
+ * @param {Object} [options] - Optional Dataform runtime options.
+ *   @param {Function} [options.assert] - Dataform assert() function. When provided, creates assertions for the table.
+ *   @param {Object}   [options.assertions] - Per-assertion overrides. Set a key to false to disable,
+ *     or to an object to override assertion Dataform config (name, schema, tags).
  * @returns {Object} The Dataform publish() object for the table.
  */
-const createTable = (dataformPublish, userConfig, tableModule) => {
+const createTable = (dataformPublish, userConfig, tableModule, options) => {
     const mergedConfig = utils.mergeSQLConfigurations(tableModule.defaultConfig, userConfig);
     tableModule.validate(mergedConfig, { skipDataformContextFields: true });
 
@@ -48,11 +54,39 @@ const createTable = (dataformPublish, userConfig, tableModule) => {
     }
 
     // Create the table using Dataform publish()
-    return dataformPublish(dataformTableConfig.name, dataformTableConfig).preOps(ctx => {
+    const tableResult = dataformPublish(dataformTableConfig.name, dataformTableConfig).preOps(ctx => {
         return preOperations.setPreOperations(utils.setDataformContext(ctx, mergedConfig));
     }).query(ctx => {
         return tableModule.generateSql(utils.setDataformContext(ctx, mergedConfig));
     });
+
+    // Create assertions when options.assert is provided and the table module defines assertions
+    if (options?.assert && tableModule.assertions) {
+        const tableName = dataformTableConfig.name;
+
+        for (const [key, assertionDef] of Object.entries(tableModule.assertions)) {
+            const assertionOption = options.assertions?.[key];
+            if (assertionOption === false) continue;
+            if (assertionOption === undefined && assertionDef.enabledByDefault === false) continue;
+
+            const assertionName = `${tableName}_${assertionDef.defaultName}`;
+            const assertionDataformConfig = {
+                schema: dataformTableConfig.schema,
+                tags: dataformTableConfig.tags || [],
+                ...(typeof assertionOption === 'object' ? assertionOption : {}),
+            };
+
+            options.assert(assertionDataformConfig.name || assertionName, assertionDataformConfig).query(ctx => {
+                const resolvedConfig = { ...mergedConfig };
+                if (utils.isDataformTableReferenceObject(resolvedConfig.sourceTable)) {
+                    resolvedConfig.sourceTable = ctx.ref(resolvedConfig.sourceTable);
+                }
+                return assertionDef.generate(ctx.ref(tableName), resolvedConfig);
+            });
+        }
+    }
+
+    return tableResult;
 };
 
 module.exports = { createTable };

package/package.json

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

package/tables/ga4EventsEnhanced/assertions/dailyQuality.js

@@ -160,4 +160,4 @@ const generateDailyQualityAssertionSql = (tableRef, config) => {
     return _generateDailyQualityAssertionSql(tableRef, mergedConfig);
 };
 
-module.exports = { generateDailyQualityAssertionSql };
+module.exports = { generateDailyQualityAssertionSql, _generateDailyQualityAssertionSql };

package/tables/ga4EventsEnhanced/assertions/index.js

@@ -1,7 +1,11 @@
-const { generateItemRevenueAssertionSql } = require('./itemRevenue.js');
-const { generateDailyQualityAssertionSql } = require('./dailyQuality.js');
+const { generateItemRevenueAssertionSql, _generateItemRevenueAssertionSql } = require('./itemRevenue.js');
+const { generateDailyQualityAssertionSql, _generateDailyQualityAssertionSql } = require('./dailyQuality.js');
 
 module.exports = {
     itemRevenue: generateItemRevenueAssertionSql,
     dailyQuality: generateDailyQualityAssertionSql,
+    _internal: {
+        dailyQuality: { generate: _generateDailyQualityAssertionSql, defaultName: 'daily_quality' },
+        itemRevenue: { generate: _generateItemRevenueAssertionSql, defaultName: 'item_revenue', enabledByDefault: false },
+    },
 };

package/tables/ga4EventsEnhanced/assertions/itemRevenue.js

@@ -146,4 +146,4 @@ const generateItemRevenueAssertionSql = (tableRef, config) => {
     return _generateItemRevenueAssertionSql(tableRef, mergedConfig);
 };
 
-module.exports = { generateItemRevenueAssertionSql };
+module.exports = { generateItemRevenueAssertionSql, _generateItemRevenueAssertionSql };

package/tables/ga4EventsEnhanced/index.js

@@ -410,10 +410,11 @@ const tableModule = {
     generateSql: _generateEnhancedEventsSQL,
     getColumnDescriptions: (config) => documentation.getColumnDescriptions(config, columnMetadata),
     getTableDescription: (config) => documentation.buildTableDescription(config, getTableDescriptionSections(config)),
+    assertions: assertions._internal,
 };
 
-const createEnhancedEventsTable = (dataformPublish, config) => {
-    return createTable(dataformPublish, config, tableModule);
+const createEnhancedEventsTable = (dataformPublish, config, options) => {
+    return createTable(dataformPublish, config, tableModule, options);
 };
 
 // Exported wrapper: merge config, validate, then delegate to preOperations module