@bytebrand/export-cars 1.26.24 → 1.26.26

package/src/services/feed-items-bigquery.writer.ts

@@ -0,0 +1,101 @@
+import { join } from 'path';
+import { BigQueryLogger } from '@bytebrand/bigquery-logger';
+import { FeedItemsBigQueryTarget } from '../interfaces/params.interface';
+import { FeedItemRow } from '../transformers/google-feed-item-row';
+
+const BATCH_SIZE = 500;
+// After this many failed batches the writer gives up for the run (missing table, bad credentials).
+const MAX_FAILED_BATCHES = 3;
+const CLOSE_TIMEOUT_MS = 60000;
+
+class FeedItemsBigQueryLogger extends BigQueryLogger {
+  async insertRows(rows: FeedItemRow[]): Promise<void> {
+    await this.client
+      .dataset(this.options.BigQueryDataset)
+      .table(this.options.BigQueryLogTable)
+      .insert(rows, { skipInvalidRows: true, ignoreUnknownValues: true });
+  }
+}
+
+// Audit trail of the feed items: rows are buffered and inserted in batches of 500 in the background,
+// one batch at a time. Errors are logged and swallowed — the feed export must never fail because of
+// BigQuery.
+export class FeedItemsBigQueryWriter {
+  private logger: FeedItemsBigQueryLogger;
+  private buffer: FeedItemRow[] = [];
+  private queue: Promise<void> = Promise.resolve();
+  private failedBatches = 0;
+  private insertedRows = 0;
+
+  constructor(private target: FeedItemsBigQueryTarget) {
+    try {
+      const credentials = require(join(process.cwd(), 'credentials/google-cloud-project-id.json'));
+      this.logger = new FeedItemsBigQueryLogger(credentials, {
+        BigQueryProject: target.project,
+        BigQueryDataset: target.dataset,
+        BigQueryLogTable: target.table,
+      });
+    } catch (e) {
+      // First line only: a missing credentials file comes with the whole require stack.
+      console.log(`Feed items BigQuery disabled: ${String(e?.message || e).split('\n')[0]}`);
+    }
+  }
+
+  add(row: FeedItemRow): void {
+    if (!this.enabled) return;
+    this.buffer.push(row);
+    if (this.buffer.length >= BATCH_SIZE) this.flush();
+  }
+
+  // Waits for the pending batches, but never longer than CLOSE_TIMEOUT_MS: a hanging BigQuery
+  // must not hold up the feed export (the XML is already written at this point).
+  async close(): Promise<void> {
+    this.flush();
+    let timer: NodeJS.Timeout | undefined;
+    const timeout = new Promise<'timeout'>((resolve) => {
+      timer = setTimeout(() => resolve('timeout'), CLOSE_TIMEOUT_MS);
+    });
+    const outcome = await Promise.race([this.queue.then(() => 'done' as const), timeout]);
+    if (timer) clearTimeout(timer);
+    if (outcome === 'timeout') console.error(`Feed items BigQuery: gave up waiting after ${CLOSE_TIMEOUT_MS} ms`);
+    if (this.logger) {
+      console.log(`Feed items BigQuery: ${this.insertedRows} rows to ${this.tableName}, ${this.failedBatches} failed batches`);
+    }
+  }
+
+  private get enabled(): boolean {
+    return !!this.logger && this.failedBatches < MAX_FAILED_BATCHES;
+  }
+
+  private get tableName(): string {
+    return `${this.target.project}.${this.target.dataset}.${this.target.table}`;
+  }
+
+  private flush(): void {
+    if (!this.buffer.length) return;
+    const rows = this.buffer;
+    this.buffer = [];
+    this.queue = this.queue.then(() => this.insert(rows));
+  }
+
+  private async insert(rows: FeedItemRow[]): Promise<void> {
+    if (!this.enabled) return;
+    try {
+      await this.logger.insertRows(rows);
+      this.insertedRows += rows.length;
+    } catch (e) {
+      // PartialFailureError: the valid rows went in (skipInvalidRows), `errors` lists the rejected
+      // ones; the first is enough to see the cause.
+      const rejected: any[] = e?.name === 'PartialFailureError' && Array.isArray(e.errors) ? e.errors : null;
+      const firstRowError = rejected?.[0]?.errors?.[0];
+      const detail = firstRowError ? ` (${firstRowError.reason}: ${firstRowError.message})` : '';
+      if (rejected) {
+        this.insertedRows += rows.length - rejected.length;
+        console.log(`Feed items BigQuery rejected ${rejected.length} of ${rows.length} rows${detail}`);
+      } else {
+        this.failedBatches++;
+        console.log(`Feed items BigQuery insert of ${rows.length} rows failed: ${e?.message || e}`);
+      }
+    }
+  }
+}

package/src/transformers/google-feed-envkv.ts

@@ -35,57 +35,77 @@ export function googleEngine(car: DataSchemes.Car): string {
 
 // BEV: combined WLTP range (CoC 49.2). Plug-in: the EAER (`wltpTotalRange`, CoC 49.5) when present,
 // else the range the dealer delivered. City ranges are never used; 0 counts as missing.
-export function googleElectricRange(car: DataSchemes.Car): string | undefined {
-  let range: number | undefined;
-  if (isBev(car)) {
-    range = positive(get(car, 'battery.wltpRange')) ?? positive(get(car, 'battery.batteryRangeElectric'));
-  } else if (isPlugIn(car)) {
-    range = positive(get(car, 'battery.wltpTotalRange'))
-      ?? positive(get(car, 'battery.wltpRange'))
-      ?? positive(get(car, 'battery.batteryRangeElectric'));
+const BEV_RANGE_FIELDS = ['battery.wltpRange', 'battery.batteryRangeElectric'];
+const PLUG_IN_RANGE_FIELDS = ['battery.wltpTotalRange', 'battery.wltpRange', 'battery.batteryRangeElectric'];
+
+const pickElectricRange = (car: DataSchemes.Car): { field: string; range: number } | undefined => {
+  const fields = isBev(car) ? BEV_RANGE_FIELDS : isPlugIn(car) ? PLUG_IN_RANGE_FIELDS : [];
+  for (const field of fields) {
+    const range = positive(get(car, field));
+    if (range) return { field, range };
   }
-  return range ? `${range}km` : undefined;
+  return undefined;
+};
+
+export function googleElectricRange(car: DataSchemes.Car): string | undefined {
+  const picked = pickElectricRange(car);
+  return picked ? `${picked.range}km` : undefined;
+}
+
+// The car field googleElectricRange took its value from (feed audit), null when nothing is sent.
+export function googleElectricRangeSource(car: DataSchemes.Car): string | null {
+  return pickElectricRange(car)?.field ?? null;
 }
 
 // Plug-in hybrids: Google and Pkw-EnVKV (CoC 49.4) want the WEIGHTED combined values for fuel,
 // electricity and CO2, and the fuel consumption with a DISCHARGED battery separately. In CBD those
 // are wltpWeightedCombined, wltpWeightedPowerCombined, wltpCo2 (weighted for a plug-in) and
 // wltpCombined (discharged for a plug-in); the legacy consumptionCombined / co2 are only a fallback.
+//
+// engineData.hybridPlugin alone does not prove a plug-in: since ADV-124 every hybrid carries it, and
+// the weighted fields of hybrids without an electric range are enrichment-sheet templates
+// (prod 07.10: 4,178 of 5,576 flagged cars, e.g. 2.3 l + 21.5 kWh + 195 g). Only a hybrid with an
+// electric range counts as a confirmed plug-in; the others keep the values sent before.
+const isConfirmedPlugIn = (car: DataSchemes.Car): boolean => isPlugIn(car) && !!googleElectricRange(car);
 
 // Missing or 0 is omitted instead of sending "0l/100km". BEVs carry no fuel consumption
 // (CBD mirrors kWh into consumptionCombined for them).
 export function googleFuelConsumption(car: DataSchemes.Car): string | undefined {
   if (isBev(car)) return undefined;
-  const value = isPlugIn(car)
+  const value = isConfirmedPlugIn(car)
     ? positive(get(car, 'consumption.wltpWeightedCombined')) ?? positive(get(car, 'consumption.consumptionCombined'))
     : positive(get(car, 'consumption.consumptionCombined'));
   return value ? `${value}l/100km` : undefined;
 }
 
-// Plug-in only. No fallback: the legacy combined value is (close to) the weighted one, sending it
-// here would repeat the weighted figure as the discharged one.
+// Confirmed plug-in: wltpCombined, no fallback (the legacy combined value is close to the weighted
+// one, sending it here would repeat the weighted figure). Unconfirmed plug-in: the stored combined
+// value, as before.
 export function googleFuelConsumptionDischarged(car: DataSchemes.Car): string | undefined {
   if (!isPlugIn(car)) return undefined;
-  const value = positive(get(car, 'consumption.wltpCombined'));
+  const value = isConfirmedPlugIn(car)
+    ? positive(get(car, 'consumption.wltpCombined'))
+    : positive(get(car, 'consumption.consumptionCombined')) ?? positive(get(car, 'consumption.wltpCombined'));
   return value ? `${value}l/100km` : undefined;
 }
 
-// BEV: combined consumption. Plug-in: weighted combined. Nothing for other cars.
+// BEV: combined consumption. Confirmed plug-in: weighted combined. Unconfirmed plug-in: the stored
+// electric value, as before. Nothing for other cars.
 export function googleEnergyConsumption(car: DataSchemes.Car): string | undefined {
   let value: number | undefined;
-  if (isBev(car)) {
-    value = positive(get(car, 'consumption.wltpPowerCombined')) ?? positive(get(car, 'consumption.consumptionPowerCombined'));
-  } else if (isPlugIn(car)) {
+  if (isConfirmedPlugIn(car)) {
     value = positive(get(car, 'consumption.wltpWeightedPowerCombined'));
+  } else if (isBev(car) || isPlugIn(car)) {
+    value = positive(get(car, 'consumption.wltpPowerCombined')) ?? positive(get(car, 'consumption.consumptionPowerCombined'));
   }
   return value ? `${value}kWh/100km` : undefined;
 }
 
-// A BEV emits 0 g/km by definition; a plug-in sends the weighted WLTP CO2; for every other car the
-// stored value. A missing or 0 value is omitted.
+// A BEV emits 0 g/km by definition; a confirmed plug-in sends the weighted WLTP CO2; every other car
+// the stored value. A missing or 0 value is omitted.
 export function googleCo2(car: DataSchemes.Car): string | undefined {
   if (isBev(car)) return '0g/km';
-  const value = isPlugIn(car)
+  const value = isConfirmedPlugIn(car)
     ? positive(get(car, 'environmentEmissions.wltpCo2')) ?? positive(get(car, 'environmentEmissions.co2'))
     : positive(get(car, 'environmentEmissions.co2'));
   return value ? `${value}g/km` : undefined;

package/src/transformers/google-feed-item-row.ts

@@ -0,0 +1,71 @@
+import { get, isBoolean } from 'lodash';
+import { DataSchemes } from '@bytebrand/car-schema';
+import { GoogleXmlItem } from '../interfaces';
+import { googleElectricRangeSource } from './google-feed-envkv';
+
+// One BigQuery row per item the Google feed sent (schema/feed-items.json), so a Merchant Center
+// issue can be traced back to the exact values of a run. The attribute strings are the ones in the
+// XML; null means the attribute was omitted.
+export interface FeedItemRow {
+  partitionDay: string;
+  exportedAt: string;
+  feed: string;
+  runId: string | null;
+  itemId: string;
+  vehicleId: string | null;
+  make: string | null;
+  model: string | null;
+  condition: string | null;
+  fuel: string | null;
+  hybridPlugin: boolean | null;
+  engine: string | null;
+  electricRange: string | null;
+  fuelConsumption: string | null;
+  fuelConsumptionDischarged: string | null;
+  energyConsumption: string | null;
+  co2Emissions: string | null;
+  rangeSourceField: string | null;
+  price: number | null;
+  availability: string | null;
+}
+
+const orNull = (value: unknown): string | null =>
+  value === undefined || value === null || value === '' ? null : String(value);
+
+// "12345.5 EUR" -> 12345.5
+const sentPrice = (price: string | undefined): number | null => {
+  const n = parseFloat(price);
+  return Number.isFinite(n) ? n : null;
+};
+
+// exportedAt is the run's start, shared by all rows of a run; partitionDay is its UTC day.
+export function buildGoogleFeedItemRow(
+  car: DataSchemes.Car,
+  item: GoogleXmlItem,
+  runId: string | null,
+  exportedAt: Date,
+): FeedItemRow {
+  const hybridPlugin = get(car, 'engineData.hybridPlugin');
+  return {
+    partitionDay: exportedAt.toISOString().slice(0, 10),
+    exportedAt: exportedAt.toISOString(),
+    feed: 'google',
+    runId: orNull(runId),
+    itemId: String(item.id),
+    vehicleId: orNull(get(car, 'metaData.vehicleId')),
+    make: orNull(item.brand),
+    model: orNull(item.model),
+    condition: orNull(item.condition),
+    fuel: orNull(get(car, 'consumption.fuel')),
+    hybridPlugin: isBoolean(hybridPlugin) ? hybridPlugin : null,
+    engine: orNull(item.engine),
+    electricRange: orNull(item.electric_range),
+    fuelConsumption: orNull(item.fuel_consumption),
+    fuelConsumptionDischarged: orNull(item.fuel_consumption_discharged_battery),
+    energyConsumption: orNull(item.energy_consumption),
+    co2Emissions: orNull(item.co2_emissions),
+    rangeSourceField: item.electric_range ? googleElectricRangeSource(car) : null,
+    price: sentPrice(item.price),
+    availability: orNull(item.availability),
+  };
+}

package/test/google-feed-envkv.test.ts

@@ -66,6 +66,7 @@ const cases: Array<[string, () => void]> = [
   ['plug-in: weighted fuel, discharged fuel, weighted electricity and weighted CO2', () => {
     const phev = car('selector_fuel_hybridElectricalPetrol', {
       hybridPlugin: true,
+      battery: { wltpTotalRange: 62 },
       consumption: { consumptionCombined: 1.4, wltpCombined: 6.3, wltpWeightedCombined: 1.2, wltpPowerCombined: 19.3, wltpWeightedPowerCombined: 17.3 },
       environmentEmissions: { co2: 121, wltpCo2: 28 },
     });
@@ -77,6 +78,7 @@ const cases: Array<[string, () => void]> = [
   ['plug-in without weighted values falls back to the legacy combined ones, never the pure-electric value', () => {
     const phev = car('selector_fuel_hybridElectricalPetrol', {
       hybridPlugin: true,
+      battery: { wltpRange: 59 },
       consumption: { consumptionCombined: 1.4, wltpPowerCombined: 19.3 },
       environmentEmissions: { co2: 32 },
     });
@@ -95,6 +97,17 @@ const cases: Array<[string, () => void]> = [
     assert.equal(googleEnergyConsumption(hev), undefined);
     assert.equal(googleCo2(hev), '116g/km');
   }],
+  ['a plug-in flag without an electric range keeps the stored values (ADV-124 flags every hybrid)', () => {
+    const flagged = car('selector_fuel_hybridElectricalPetrol', {
+      hybridPlugin: true,
+      consumption: { consumptionCombined: 5.1, wltpCombined: 5.3, wltpWeightedCombined: 2.3, wltpPowerCombined: 21.5, wltpWeightedPowerCombined: 21.5 },
+      environmentEmissions: { co2: 116, wltpCo2: 116, wltpCo2Discharged: 195 },
+    });
+    assert.equal(googleFuelConsumption(flagged), '5.1l/100km');
+    assert.equal(googleFuelConsumptionDischarged(flagged), '5.1l/100km');
+    assert.equal(googleEnergyConsumption(flagged), '21.5kWh/100km');
+    assert.equal(googleCo2(flagged), '116g/km');
+  }],
   ['BEV energy consumption is the combined value', () => {
     assert.equal(googleEnergyConsumption(car('selector_fuel_electrical', { consumption: { wltpPowerCombined: 16.5 } })), '16.5kWh/100km');
     assert.equal(googleEnergyConsumption(car('selector_fuel_electrical', { consumption: { consumptionPowerCombined: 18 } })), '18kWh/100km');

package/test/google-feed-item-row.test.ts

@@ -0,0 +1,121 @@
+// Run: npm test (ts-node, no test framework needed)
+import * as assert from 'node:assert/strict';
+import { buildGoogleFeedItemRow } from '../src/transformers/google-feed-item-row';
+import { googleElectricRange, googleElectricRangeSource } from '../src/transformers/google-feed-envkv';
+
+const exportedAt = new Date('2026-10-08T23:30:00.000Z');
+
+const car = (fuel: string, extra: Record<string, any> = {}): any => ({
+  _id: 'cbd-1',
+  metaData: { vehicleId: 'veh-1' },
+  consumption: { fuel },
+  engineData: 'hybridPlugin' in extra ? { hybridPlugin: extra.hybridPlugin } : {},
+  battery: extra.battery || {},
+});
+
+// Shape of what GoogleTransformer returns after dropping the empty optional attributes.
+const item = (extra: Record<string, any> = {}): any => ({
+  id: 'cbd-1',
+  brand: 'VW',
+  model: 'Golf',
+  condition: 'Used',
+  engine: 'Gasoline',
+  price: '19990.5 EUR',
+  availability: 'in_stock',
+  ...extra,
+});
+
+const cases: Array<[string, () => void]> = [
+  ['combustion car: sent values, omitted attributes are null', () => {
+    const row = buildGoogleFeedItemRow(
+      car('selector_fuel_petrol', { hybridPlugin: false }),
+      item({ fuel_consumption: '5.1l/100km', co2_emissions: '118g/km' }),
+      '12345',
+      exportedAt,
+    );
+    assert.deepEqual(row, {
+      partitionDay: '2026-10-08',
+      exportedAt: '2026-10-08T23:30:00.000Z',
+      feed: 'google',
+      runId: '12345',
+      itemId: 'cbd-1',
+      vehicleId: 'veh-1',
+      make: 'VW',
+      model: 'Golf',
+      condition: 'Used',
+      fuel: 'selector_fuel_petrol',
+      hybridPlugin: false,
+      engine: 'Gasoline',
+      electricRange: null,
+      fuelConsumption: '5.1l/100km',
+      fuelConsumptionDischarged: null,
+      energyConsumption: null,
+      co2Emissions: '118g/km',
+      rangeSourceField: null,
+      price: 19990.5,
+      availability: 'in_stock',
+    });
+  }],
+  ['BEV: range source is the field the range came from', () => {
+    const bev = car('selector_fuel_electrical', { battery: { batteryRangeElectric: 400 } });
+    const row = buildGoogleFeedItemRow(
+      bev,
+      item({ engine: 'Electric', electric_range: googleElectricRange(bev), energy_consumption: '16.5kWh/100km', co2_emissions: '0g/km' }),
+      '12345',
+      exportedAt,
+    );
+    assert.equal(row.electricRange, '400km');
+    assert.equal(row.rangeSourceField, 'battery.batteryRangeElectric');
+    assert.equal(row.hybridPlugin, null);
+    assert.equal(row.energyConsumption, '16.5kWh/100km');
+    assert.equal(row.co2Emissions, '0g/km');
+  }],
+  ['plug-in: EAER first, then WLTP range, then delivered range', () => {
+    const phev = (battery: object) => car('selector_fuel_hybridElectricalPetrol', { hybridPlugin: true, battery });
+    assert.equal(googleElectricRangeSource(phev({ wltpTotalRange: 62, wltpRange: 59 })), 'battery.wltpTotalRange');
+    assert.equal(googleElectricRangeSource(phev({ wltpTotalRange: 0, wltpRange: 59 })), 'battery.wltpRange');
+    assert.equal(googleElectricRangeSource(phev({ batteryRangeElectric: 50 })), 'battery.batteryRangeElectric');
+    assert.equal(googleElectricRangeSource(phev({ wltpTotalRangeCity: 70 })), null);
+  }],
+  ['range source agrees with googleElectricRange', () => {
+    const cars = [
+      car('selector_fuel_electrical', { battery: { wltpRange: 451, batteryRangeElectric: 400 } }),
+      car('selector_fuel_electrical', { battery: { wltpRange: 0 } }),
+      car('selector_fuel_hybridElectricalPetrol', { hybridPlugin: false, battery: { wltpRange: 50 } }),
+      car('selector_fuel_petrol', { battery: { wltpRange: 50 } }),
+    ];
+    for (const c of cars) {
+      assert.equal(googleElectricRangeSource(c) === null, googleElectricRange(c) === undefined);
+    }
+    assert.equal(googleElectricRangeSource(cars[0]), 'battery.wltpRange');
+  }],
+  ['no range source when the item carries no electric_range', () => {
+    const bev = car('selector_fuel_electrical', { battery: { wltpRange: 451 } });
+    assert.equal(buildGoogleFeedItemRow(bev, item(), null, exportedAt).rangeSourceField, null);
+  }],
+  ['missing run id, vehicle id and unparsable price become null', () => {
+    const row = buildGoogleFeedItemRow(
+      { consumption: {} } as any,
+      item({ price: ' EUR', availability: undefined }),
+      undefined,
+      exportedAt,
+    );
+    assert.equal(row.runId, null);
+    assert.equal(row.vehicleId, null);
+    assert.equal(row.fuel, null);
+    assert.equal(row.price, null);
+    assert.equal(row.availability, null);
+  }],
+];
+
+let failed = 0;
+for (const [name, fn] of cases) {
+  try {
+    fn();
+    console.log(`ok   ${name}`);
+  } catch (e) {
+    failed++;
+    console.log(`FAIL ${name}\n     ${(e as Error).message}`);
+  }
+}
+if (failed) process.exit(1);