@bytebrand/export-cars 1.26.27 → 1.26.29

package/test/openai-ads-feed-run.test.ts

@@ -0,0 +1,278 @@
+// Run: npm test (ts-node, no test framework needed)
+// Integration: real files in a temp dir (base export snapshot, output, state), real CSV writer,
+// guard and ledger, real ADV-336 clean-image selection; only HTTP (image check) and UPA are faked.
+import * as assert from 'node:assert/strict';
+import { promises as fs } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+import { FeedGuard, FeedGuardError, FeedGuardOptions } from '../src/services/feed-guard';
+import { DealerStatus, OpenAiAdsFeedRun, SourceCar } from '../src/services/openai-ads-feed-run';
+import { selectOpenAiImageFields } from '../src/transformers/openai-image-fields';
+import { buildImagesService } from './fixtures/images-service.harness';
+import { NOW, car, csvObjects, images, translate } from './fixtures/openai-ads.fixture';
+
+const DAY = 24 * 60 * 60 * 1000;
+const imagesService = buildImagesService();
+
+interface World {
+  root: string;
+  source: string;
+  output: string;
+  state: string;
+  // image URLs answering 404
+  brokenImages: Set<string>;
+  dealers: Record<string, DealerStatus>;
+}
+
+const newWorld = async (): Promise<World> => {
+  const root = await fs.mkdtemp(join(tmpdir(), 'openai-ads-'));
+  return {
+    root,
+    source: join(root, 'cars-export'),
+    output: join(root, 'openai_ads-dryrun', 'api_export_cars_openai_ads.csv'),
+    state: join(root, 'openai_ads-state', 'dryrun'),
+    brokenImages: new Set(),
+    dealers: {},
+  };
+};
+
+// Writes the base export snapshot like base-cars-export: cars.<n>.json chunks of [{car, images}].
+const writeSource = async (world: World, cars: SourceCar[], chunkSize = 2, mtime = NOW) => {
+  await fs.rm(world.source, { recursive: true, force: true });
+  await fs.mkdir(world.source, { recursive: true });
+  for (let i = 0; i * chunkSize < cars.length; i++) {
+    const file = join(world.source, `cars.${i}.json`);
+    await fs.writeFile(file, JSON.stringify(cars.slice(i * chunkSize, (i + 1) * chunkSize)));
+    await fs.utimes(file, mtime, mtime);
+  }
+};
+
+const guardOptions = (world: World, extra: Partial<FeedGuardOptions> = {}): FeedGuardOptions => ({
+  stateDir: world.state,
+  minSourceItems: 1,
+  minPublishedItems: 1,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+  acceptDrop: false,
+  ...extra,
+});
+
+const run = async (world: World, at: Date = NOW, extra: Partial<FeedGuardOptions> = {}) => {
+  const forEachChunk = async (fn: (cars: SourceCar[]) => Promise<void>) => {
+    const names = (await fs.readdir(world.source)).sort((a, b) => Number(a.split('.')[1]) - Number(b.split('.')[1]));
+    for (const name of names) {
+      await fn(JSON.parse(await fs.readFile(join(world.source, name), 'utf8')));
+    }
+  };
+  const feed = new OpenAiAdsFeedRun(
+    {
+      forEachChunk,
+      filterCar: ({ car: c }) => (c?.metaData?.imagesCount ?? 0) > 0,
+      dealerStatus: async ownerId => world.dealers[ownerId] ?? 'active',
+      resolveImages: async ({ car: c, images: list }) => {
+        const clean = imagesService.getCleanImages(c._id, list);
+        return selectOpenAiImageFields(clean, clean.map(i => ({ url: i.url, ok: !world.brokenImages.has(i.url) })));
+      },
+      imageStats: () => ({}),
+      guard: new FeedGuard(guardOptions(world, extra)),
+    },
+    {
+      runId: 'test',
+      dryRun: true,
+      sourceDirectory: world.source,
+      sourceBaseFileName: 'cars',
+      outputFile: world.output,
+      stateDir: world.state,
+      retentionDays: 15,
+      mapping: { domain: 'auto.de', sellerName: 'auto.de', translate },
+      now: () => at,
+    },
+  );
+  // the run prints its report as one JSON line; keep the test output readable
+  const log = console.log;
+  console.log = () => undefined;
+  try {
+    return await feed.run();
+  } finally {
+    console.log = log;
+  }
+};
+
+const published = async (world: World) => csvObjects(await fs.readFile(world.output, 'utf8'));
+const byId = (rows: Record<string, string>[]) => Object.fromEntries(rows.map(r => [r.item_id, r]));
+const src = (id: string, overrides: Record<string, any> = {}): SourceCar => ({ car: car(id, overrides), images: images(id) });
+const fleet = (n: number) => Array.from({ length: n }, (_, i) => src(`car-${i}`));
+
+const cases: Array<[string, () => Promise<void>]> = [
+  ['first run: in_stock rows, hero image first, exclusions counted, report written', async () => {
+    const w = await newWorld();
+    w.dealers['dealer-off'] = 'inactive';
+    await writeSource(w, [
+      ...fleet(3),
+      src('car-1'), // duplicate id (offset paging over a live collection)
+      src('no-photo', { 'metaData.imagesCount': 0 }),
+      src('price-0', { 'price.currentSalesPrice': 0 }),
+      src('off-dealer', { 'metaData.ownerId': 'dealer-off' }),
+      { car: car('interior-only'), images: [{ imageIdentifier: 'i1', imageCodePredicted: 'int_f_ipanel1' }] },
+      src('reserved-new', { 'offer.offerAvailability': 'selector_offerAvailability_reserved' }),
+    ]);
+    const report = await run(w);
+    const rows = await published(w);
+    assert.deepEqual(rows.map(r => r.item_id), ['car-0', 'car-1', 'car-2']);
+    assert.equal(rows[0].image_url, 'https://images.auto.de/carimage/car-0/car-0Right/large-cached.jpeg');
+    assert.equal(rows[0].additional_image_urls.split(',').length, 2);
+    assert.ok(rows.every(r => r.availability === 'in_stock' && r.price === '17990.00 EUR'));
+    assert.deepEqual(report.excluded, { duplicate_id: 1, filtered: 1, invalid_price: 1, dealer_inactive: 1, no_image: 1 });
+    assert.equal(report.reservedNeverSent, 1);
+    assert.equal(report.status, 'published');
+    assert.equal(report.ledger.after, 3);
+    const saved = JSON.parse(await fs.readFile(join(w.state, 'last-run-report.json'), 'utf8'));
+    assert.equal(saved.rows.inStock, 3);
+    await assert.rejects(fs.stat(`${w.output}.tmp`));
+  }],
+  ['sold / deleted car stays as out_of_stock with the same id; reserved car switches off; reinstated car returns', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(5));
+    await run(w);
+    // car-1 sold (offline -> gone from snapshot), car-2 reserved, car-3 loses its price
+    await writeSource(w, [
+      src('car-0'),
+      src('car-2', { 'offer.offerAvailability': 'selector_offerAvailability_reserved', 'price.currentSalesPrice': 18500 }),
+      src('car-3', { 'price.currentSalesPrice': null }),
+      src('car-4'),
+    ], 2, new Date(NOW.getTime() + DAY));
+    const report = await run(w, new Date(NOW.getTime() + DAY), { maxDropPercent: 60 });
+    const rows = byId(await published(w));
+    assert.equal(rows['car-0'].availability, 'in_stock');
+    assert.equal(rows['car-1'].availability, 'out_of_stock');
+    assert.equal(rows['car-1'].is_ads_eligible, 'false');
+    assert.equal(rows['car-1'].price, '17990.00 EUR');
+    assert.equal(rows['car-2'].availability, 'out_of_stock');
+    assert.equal(rows['car-2'].price, '18500.00 EUR', 'reserved row carries the current data');
+    assert.equal(rows['car-3'].availability, 'out_of_stock');
+    assert.deepEqual(report.outOfStock, { not_in_snapshot: 2, reserved: 1 });
+    // car-1 is back online two days later
+    await writeSource(w, fleet(5), 2, new Date(NOW.getTime() + 2 * DAY));
+    await run(w, new Date(NOW.getTime() + 2 * DAY));
+    const back = byId(await published(w));
+    assert.equal(back['car-1'].availability, 'in_stock');
+    assert.equal(Object.keys(back).length, 5);
+  }],
+  ['out_of_stock rows stop after the retention window', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(5));
+    await run(w);
+    const later = new Date(NOW.getTime() + 16 * DAY);
+    await writeSource(w, fleet(4), 2, later);
+    const report = await run(w, later);
+    const rows = await published(w);
+    assert.equal(rows.length, 4);
+    assert.equal(report.ledger.expired, 1);
+  }],
+  ['source outage: empty snapshot is blocked, published file and ledger untouched', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(5));
+    await run(w);
+    const before = await fs.readFile(w.output, 'utf8');
+    const ledgerBefore = await fs.readFile(join(w.state, 'ledger.json'), 'utf8');
+    await writeSource(w, []);
+    await assert.rejects(run(w), (e: FeedGuardError) => e.code === 'source_empty');
+    assert.equal(await fs.readFile(w.output, 'utf8'), before);
+    assert.equal(await fs.readFile(join(w.state, 'ledger.json'), 'utf8'), ledgerBefore);
+    const report = JSON.parse(await fs.readFile(join(w.state, 'last-run-report.json'), 'utf8'));
+    assert.equal(report.status, 'blocked');
+    await assert.rejects(fs.stat(join(w.state, 'run.lock')));
+  }],
+  ['partial snapshot: a missing chunk file is blocked', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(6));
+    await fs.rm(join(w.source, 'cars.1.json'));
+    await assert.rejects(run(w), (e: FeedGuardError) => e.code === 'source_partial');
+    await assert.rejects(fs.stat(w.output));
+  }],
+  ['partial snapshot: base export died after the first pages -> count drop blocked, then accepted on purpose', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(10));
+    await run(w);
+    const before = await fs.readFile(w.output, 'utf8');
+    await writeSource(w, fleet(4));
+    await assert.rejects(run(w), (e: FeedGuardError) => e.code === 'count_drop');
+    assert.equal(await fs.readFile(w.output, 'utf8'), before);
+    assert.ok((await fs.readFile(`${w.output}.rejected`, 'utf8')).length > 0);
+    // legitimate drop confirmed by a human: one run with acceptDrop
+    const report = await run(w, NOW, { acceptDrop: true });
+    assert.equal(report.status, 'published');
+    assert.equal((await published(w)).filter(r => r.availability === 'out_of_stock').length, 6);
+    assert.equal(await fs.readFile(`${w.output}.prev`, 'utf8'), before);
+  }],
+  ['legitimate small stock change passes the guard; recovery after a blocked run', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(10));
+    await run(w);
+    await writeSource(w, []);
+    await assert.rejects(run(w));
+    await writeSource(w, fleet(9));
+    const report = await run(w);
+    assert.equal(report.status, 'published');
+    assert.equal(report.rows.inStock, 9);
+  }],
+  ['stale snapshot: chunk files older than maxSourceAgeHours are blocked', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(3), 2, new Date(NOW.getTime() - 27 * 60 * 60 * 1000));
+    await assert.rejects(run(w), (e: FeedGuardError) => e.code === 'source_stale');
+  }],
+  ['minimums: tiny source is blocked even without a last good run', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(3));
+    await assert.rejects(run(w, NOW, { minSourceItems: 100 }), (e: FeedGuardError) => e.code === 'source_too_small');
+  }],
+  ['lock: a second run while one holds the lock is refused; a stale lock is taken over', async () => {
+    const w = await newWorld();
+    await writeSource(w, fleet(3));
+    await fs.mkdir(w.state, { recursive: true });
+    await fs.writeFile(join(w.state, 'run.lock'), '{}');
+    await fs.utimes(join(w.state, 'run.lock'), NOW, NOW);
+    await assert.rejects(run(w), (e: FeedGuardError) => e.code === 'locked');
+    const old = new Date(NOW.getTime() - 7 * 60 * 60 * 1000);
+    await fs.utimes(join(w.state, 'run.lock'), old, old);
+    assert.equal((await run(w)).status, 'published');
+  }],
+  ['broken hero image: next 3/4 view used; no valid 3/4 view -> car not sent', async () => {
+    const w = await newWorld();
+    const withLeft = { car: car('car-l'), images: [...images('car-l'), { imageIdentifier: 'car-lLeft', imageCodePredicted: 'ext_f_left' }] };
+    await writeSource(w, [withLeft, src('car-x')]);
+    w.brokenImages.add('https://images.auto.de/carimage/car-l/car-lRight/large-cached.jpeg');
+    w.brokenImages.add('https://images.auto.de/carimage/car-x/car-xRight/large-cached.jpeg');
+    const report = await run(w);
+    const rows = await published(w);
+    assert.deepEqual(rows.map(r => r.item_id), ['car-l']);
+    assert.equal(rows[0].image_url, 'https://images.auto.de/carimage/car-l/car-lLeft/large-cached.jpeg');
+    assert.equal(report.excluded.no_image, 1);
+  }],
+  ['CSV file: umlauts as UTF-8 bytes, no BOM, one header', async () => {
+    const w = await newWorld();
+    await writeSource(w, [src('car-u', { 'mainData.make': 'Škoda', 'mainData.subModel': 'Größe, "Edition"\nNeu' })]);
+    await run(w);
+    const bytes = await fs.readFile(w.output);
+    assert.notEqual(bytes[0], 0xef, 'no UTF-8 BOM');
+    assert.ok(bytes.includes(Buffer.from('Größe', 'utf8')));
+    const [row] = await published(w);
+    assert.equal(row.title, 'Škoda Golf Größe, "Edition" Neu');
+  }],
+];
+
+(async () => {
+  let failed = 0;
+  for (const [name, fn] of cases) {
+    try {
+      await fn();
+      console.log(`ok   ${name}`);
+    } catch (e) {
+      failed += 1;
+      console.error(`FAIL ${name}\n     ${e.stack || e.message}`);
+    }
+  }
+  if (failed) process.exit(1);
+})();

package/test/openai-ads-mapping.test.ts

@@ -0,0 +1,136 @@
+// Run: npm test (ts-node, no test framework needed)
+import * as assert from 'node:assert/strict';
+import { OPENAI_ADS_COLUMNS, OpenAiAdsExclusion as X, OpenAiAdsOutOfStockReason as O } from '../src/interfaces/openai-ads.interface';
+import { openAiAdsCsvHeader, openAiAdsCsvRow, toCsvCell } from '../src/formats/openai-ads-csv.builder';
+import {
+  asOutOfStock,
+  formatOpenAiPrice,
+  mapOpenAiAdsVehicle,
+  toOpenAiMinorUnits,
+  withOpenAiImages,
+} from '../src/transformers/openai-ads.transformer';
+import { NOW, car, csvObjects, translate } from './fixtures/openai-ads.fixture';
+
+const ctx = { domain: 'auto.de', sellerName: 'auto.de', translate, now: NOW };
+const map = (c: any) => mapOpenAiAdsVehicle(c, ctx);
+const okRow = (c: any) => {
+  const result = map(c);
+  assert.equal(result.ok, true, `expected ok, got ${JSON.stringify(result)}`);
+  return (result as any).row;
+};
+const reason = (c: any) => {
+  const result = map(c);
+  assert.equal(result.ok, false);
+  return (result as any).reason;
+};
+const imageFields = {
+  image_url: 'https://images.auto.de/carimage/id/right/large-cached.jpeg',
+  additional_image_urls: ['https://images.auto.de/carimage/id/back/large-cached.jpeg', 'https://x.test/a,b.jpeg'],
+};
+
+const cases: Array<[string, () => void]> = [
+  ['price: purchase price in major units with two decimals, never the rate', () => {
+    assert.equal(formatOpenAiPrice(17990), '17990.00 EUR');
+    assert.equal(formatOpenAiPrice(17990.5), '17990.50 EUR');
+    assert.equal(formatOpenAiPrice('24999'), '24999.00 EUR');
+    assert.equal(formatOpenAiPrice(123456.789), '123456.79 EUR');
+    for (const bad of [0, -1, null, undefined, '', 'abc', NaN, Infinity, true]) {
+      assert.equal(formatOpenAiPrice(bad), null, String(bad));
+    }
+    assert.equal(okRow(car('a')).price, '17990.00 EUR');
+    assert.equal(okRow(car('a', { 'rate.monthlyInstallment': 99 })).price, '17990.00 EUR');
+  }],
+  ['price: zero / missing / text price excludes the car', () => {
+    assert.equal(reason(car('a', { 'price.currentSalesPrice': 0 })), X.invalidPrice);
+    assert.equal(reason(car('a', { 'price.currentSalesPrice': undefined })), X.invalidPrice);
+    assert.equal(reason(car('a', { 'price.currentSalesPrice': 'auf Anfrage' })), X.invalidPrice);
+  }],
+  ['delta price: integer minor units', () => {
+    assert.equal(toOpenAiMinorUnits(17990), 1799000);
+    assert.equal(toOpenAiMinorUnits(17990.5), 1799050);
+    assert.equal(toOpenAiMinorUnits(0), null);
+  }],
+  ['identity: item_id = car._id, url = VDP of the same id, brand = real make', () => {
+    const row = okRow(car('2ce1d71f-851f-4123-ae16-187ddd7923c5', { 'mainData.make': 'Mercedes-Benz' }));
+    assert.equal(row.item_id, '2ce1d71f-851f-4123-ae16-187ddd7923c5');
+    assert.equal(row.url, 'https://www.auto.de/search/vehicle/2ce1d71f-851f-4123-ae16-187ddd7923c5');
+    assert.equal(row.brand, 'Mercedes-Benz');
+    assert.equal(row.seller_name, 'auto.de');
+    assert.equal(reason(car('')), X.noId);
+  }],
+  ['brand: placeholder make SONSTIGE / empty is excluded', () => {
+    assert.equal(reason(car('a', { 'mainData.make': 'SONSTIGE' })), X.noBrand);
+    assert.equal(reason(car('a', { 'mainData.make': '' })), X.noBrand);
+  }],
+  ['title: make model variant, junk punctuation removed, umlauts kept, max 150', () => {
+    assert.equal(okRow(car('a')).title, 'Volkswagen Golf 1.5 TSI Life');
+    const row = okRow(car('a', { 'mainData.make': 'Škoda', 'mainData.model': 'Octavia', 'mainData.subModel': '*AHK*Größe "L"* &Navi#' }));
+    assert.equal(row.title, 'Škoda Octavia AHK Größe "L" Navi');
+    const long = okRow(car('a', { 'mainData.subModel': 'Ausstattung '.repeat(30) })).title;
+    assert.ok(long.length <= 150 && !long.endsWith(' '), long);
+  }],
+  ['condition: new/used; unknown only used with a past first registration', () => {
+    assert.equal(okRow(car('a', { 'mainData.condition': 'selector_condition_new' })).condition, 'new');
+    assert.equal(okRow(car('a')).condition, 'used');
+    assert.equal(okRow(car('a', { 'mainData.condition': 'selector_unknown' })).condition, 'used');
+    assert.equal(reason(car('a', { 'mainData.condition': 'selector_unknown', 'mainData.firstRegistration': undefined })), X.conditionUnknown);
+    assert.equal(reason(car('a', { 'mainData.condition': undefined, 'mainData.firstRegistration': NOW.getTime() / 1000 + 86400 })), X.conditionUnknown);
+  }],
+  ['description: plain German facts, no rate, no price, real mileage', () => {
+    const { description } = okRow(car('a', { 'mainData.mileage': 56 }));
+    assert.equal(
+      description,
+      'Gebrauchtwagen: Volkswagen Golf 1.5 TSI Life. Erstzulassung: 03/2021 · Kilometerstand: 56 km · Kraftstoff: Benzin · ' +
+      'Getriebe: Manuell · Leistung: 110 kW (150 PS) · Karosserie: Limousine · Außenfarbe: Schwarz',
+    );
+    assert.ok(!/€|EUR|Rate|monat/i.test(description));
+    const sparse = okRow(car('a', {
+      'mainData.condition': 'selector_condition_new', 'mainData.firstRegistration': undefined, 'mainData.mileage': 0,
+      'consumption.fuel': 'selector_fuel_unmapped', 'exterior.exteriorColor': 'selector_unknown',
+    })).description;
+    assert.ok(sparse.startsWith('Neuwagen: Volkswagen Golf 1.5 TSI Life.'), sparse);
+    assert.ok(!/selector_|Unbekannt|Erstzulassung|Kilometerstand|Außenfarbe/.test(sparse), sparse);
+  }],
+  ['reserved / sold flag on an online car -> out_of_stock signal, row still mapped', () => {
+    assert.equal((map(car('a', { 'offer.offerAvailability': 'selector_offerAvailability_reserved' })) as any).outOfStockReason, O.reserved);
+    assert.equal((map(car('a', { 'offer.offerAvailability': 'selector_offerAvailability_sold' })) as any).outOfStockReason, O.soldFlag);
+    assert.equal((map(car('a', { 'offer.offerAvailability': 'selector_offerAvailability_arrived' })) as any).outOfStockReason, undefined);
+  }],
+  ['CSV cells: RFC 4180 quoting, booleans lowercase, umlauts untouched', () => {
+    assert.equal(toCsvCell('plain'), 'plain');
+    assert.equal(toCsvCell('a,b'), '"a,b"');
+    assert.equal(toCsvCell('Zoll 18"'), '"Zoll 18"""');
+    assert.equal(toCsvCell('line1\nline2'), '"line1\nline2"');
+    assert.equal(toCsvCell('Größe Ä'), 'Größe Ä');
+    assert.equal(toCsvCell(true), 'true');
+    assert.equal(toCsvCell(false), 'false');
+    assert.equal(toCsvCell(undefined), '');
+  }],
+  ['CSV row: fixed header, round-trips through a CSV parser, out_of_stock row', () => {
+    assert.equal(openAiAdsCsvHeader(), `${OPENAI_ADS_COLUMNS.join(',')}\n`);
+    assert.ok(!/gtin|mpn|vin|target_countries|store_country|image_link/.test(openAiAdsCsvHeader()));
+    const row = withOpenAiImages(okRow(car('a', { 'mainData.subModel': 'Life, "Edition" Größe' })), imageFields);
+    const text = openAiAdsCsvHeader() + openAiAdsCsvRow(row) + openAiAdsCsvRow(asOutOfStock(row));
+    const [inStock, outOfStock] = csvObjects(text);
+    assert.equal(inStock.title, 'Volkswagen Golf Life, "Edition" Größe');
+    assert.equal(inStock.additional_image_urls, 'https://images.auto.de/carimage/id/back/large-cached.jpeg,https://x.test/a%2Cb.jpeg');
+    assert.equal(inStock.availability, 'in_stock');
+    assert.equal(inStock.is_ads_eligible, 'true');
+    assert.equal(outOfStock.availability, 'out_of_stock');
+    assert.equal(outOfStock.is_ads_eligible, 'false');
+    assert.equal(outOfStock.item_id, inStock.item_id);
+    assert.equal(Object.keys(inStock).length, OPENAI_ADS_COLUMNS.length);
+  }],
+];
+
+let failed = 0;
+for (const [name, fn] of cases) {
+  try {
+    fn();
+    console.log(`ok   ${name}`);
+  } catch (e) {
+    failed += 1;
+    console.error(`FAIL ${name}\n     ${e.message}`);
+  }
+}
+if (failed) process.exit(1);

package/test/openai-image-fields.test.ts

@@ -0,0 +1,99 @@
+// Run: npm test (ts-node, no test framework needed)
+import * as assert from 'node:assert/strict';
+import { CleanImage } from '../src/services/images.service';
+import { ImageUrlCheck, ImageUrlRejectReason as R } from '../src/services/image-url-validator.service';
+import {
+  encodeCommasInUrl,
+  selectOpenAiImageFields,
+  serializeAdditionalImageUrlsForCsv,
+  serializeAdditionalImageUrlsForJsonl,
+} from '../src/transformers/openai-image-fields';
+
+const image = (id: string, imageCode: string, heroCandidate = false): CleanImage => ({
+  url: `https://images.auto.de/carimage/car/${id}/large-cached.jpeg`,
+  imageIdentifier: id,
+  imageCode,
+  heroCandidate,
+});
+const ok = (i: CleanImage): ImageUrlCheck => ({ url: i.url, ok: true, status: 200 });
+const bad = (i: CleanImage, reason = R.httpStatus): ImageUrlCheck => ({ url: i.url, ok: false, reason, status: 404 });
+
+const right = image('right', 'ext_f_right', true);
+const left = image('left', 'ext_f_left', true);
+const back = image('back', 'ext_b_main');
+const dash = image('dash', 'int_f_ipanel1');
+
+// Minimal RFC 4180 reader, enough to prove a real CSV parser sees ONE cell.
+const parseCsvLine = (line: string): string[] => {
+  const cells: string[] = [];
+  let cell = '';
+  let quoted = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quoted) {
+      if (c === '"' && line[i + 1] === '"') { cell += '"'; i++; } else if (c === '"') { quoted = false; } else { cell += c; }
+    } else if (c === '"') { quoted = true; } else if (c === ',') { cells.push(cell); cell = ''; } else { cell += c; }
+  }
+  cells.push(cell);
+  return cells;
+};
+
+const cases: Array<[string, () => void]> = [
+  ['image_url = hero, additional_image_urls = all other valid images in order, no count limit', () => {
+    const many = Array.from({ length: 40 }, (_, n) => image(`int${n}`, 'int_f_ipanel1'));
+    const images = [right, left, back, dash, ...many];
+    const { fields, rejected } = selectOpenAiImageFields(images, images.map(ok));
+    assert.equal(fields.image_url, right.url);
+    assert.deepEqual(fields.additional_image_urls, [left, back, dash, ...many].map(i => i.url));
+    assert.deepEqual(rejected, []);
+  }],
+  ['invalid optional images are dropped and reported', () => {
+    const { fields, rejected } = selectOpenAiImageFields([right, back, dash], [ok(right), bad(back), ok(dash)]);
+    assert.deepEqual(fields.additional_image_urls, [dash.url]);
+    assert.deepEqual(rejected.map(r => r.url), [back.url]);
+  }],
+  ['invalid hero: next valid 3/4 candidate becomes image_url', () => {
+    const { fields } = selectOpenAiImageFields([right, left, back], [bad(right, R.httpStatus), ok(left), ok(back)]);
+    assert.equal(fields.image_url, left.url);
+    assert.deepEqual(fields.additional_image_urls, [back.url]);
+  }],
+  ['no valid hero: no fields (car skipped), a non-hero view is never promoted', () => {
+    const selection = selectOpenAiImageFields([right, back, dash], [bad(right), ok(back), ok(dash)]);
+    assert.equal(selection.fields, null);
+    assert.equal(selection.rejected.length, 1);
+    assert.equal(selectOpenAiImageFields([], []).fields, null);
+  }],
+  ['unchecked images count as invalid', () => {
+    assert.equal(selectOpenAiImageFields([right], []).fields, null);
+  }],
+  ['CSV: one quoted cell, comma-separated, commas inside URLs as %2C', () => {
+    const withComma = 'https://images.auto.de/carimage/car/a,b/large-cached.jpeg';
+    const cell = serializeAdditionalImageUrlsForCsv([back.url, withComma]);
+    assert.equal(cell, `"${back.url},https://images.auto.de/carimage/car/a%2Cb/large-cached.jpeg"`);
+    assert.ok(!cell.includes(';') && !cell.includes(' '));
+
+    const row = parseCsvLine(`car-1,${right.url},${cell},49990.00 EUR`);
+    assert.equal(row.length, 4);
+    assert.deepEqual(row[2].split(','), [back.url, 'https://images.auto.de/carimage/car/a%2Cb/large-cached.jpeg']);
+  }],
+  ['CSV: quotes inside a value are doubled; empty list is an empty cell', () => {
+    assert.equal(serializeAdditionalImageUrlsForCsv(['https://x.de/a"b.jpg']), '"https://x.de/a""b.jpg"');
+    assert.equal(serializeAdditionalImageUrlsForCsv([]), '""');
+  }],
+  ['JSONL keeps an array (commas still encoded)', () => {
+    assert.deepEqual(serializeAdditionalImageUrlsForJsonl([back.url, 'https://x.de/a,b.jpg']), [back.url, 'https://x.de/a%2Cb.jpg']);
+    assert.equal(encodeCommasInUrl(right.url), right.url);
+  }],
+];
+
+let failed = 0;
+for (const [name, fn] of cases) {
+  try {
+    fn();
+    console.log(`ok   ${name}`);
+  } catch (e) {
+    failed += 1;
+    console.error(`FAIL ${name}\n     ${e.message}`);
+  }
+}
+if (failed) process.exit(1);

package/test/publication-gate.test.ts

@@ -0,0 +1,86 @@
+// Run: npm test (ts-node, no test framework needed)
+import * as assert from 'node:assert/strict';
+import { PublicationGate } from '../src/services/publication-gate';
+
+const icev = (extra: Record<string, unknown> = {}): any => ({
+  _id: 'car-1',
+  consumption: { fuel: 'selector_fuel_petrol', wltpCombined: 6.1, consumptionCombined: 6.4, ...(extra.consumption as object) },
+  engineData: {},
+  battery: {},
+  environmentEmissions: { wltpCo2: 139, co2: 145, ...(extra.environmentEmissions as object) },
+});
+
+const plugIn = (): any => ({
+  _id: 'car-2',
+  consumption: { fuel: 'selector_fuel_hybridElectricalPetrol', wltpWeightedCombined: 0.8, wltpCombined: 6.6, wltpWeightedPowerCombined: 15.6 },
+  engineData: { hybridPlugin: true },
+  battery: { wltpRange: 101 },
+  environmentEmissions: { wltpCo2: 18 },
+});
+
+const gate = (mode: 'audit' | 'enforce', entries: [string, string][]) => new PublicationGate(mode, new Map(entries));
+
+const cases: Array<[string, () => void]> = [
+  ['off: never estimated, never touches the item', () => {
+    const off = PublicationGate.off();
+    assert.deepEqual(off.estimatedAttributes(icev()), []);
+    const item = { fuel_consumption: '6.1l/100km' };
+    assert.deepEqual(off.apply(item, ['fuel_consumption']), { fuel_consumption: '6.1l/100km' });
+  }],
+  ['the estimate counts only for the field the attribute was taken from', () => {
+    // wltpCombined is sent; an estimate on the legacy fallback does not matter
+    assert.deepEqual(gate('audit', [['car-1|consumption.consumptionCombined', '6.4']]).estimatedAttributes(icev()), []);
+    assert.deepEqual(gate('audit', [['car-1|consumption.wltpCombined', '6.1']]).estimatedAttributes(icev()), ['fuel_consumption']);
+  }],
+  ['a later delivered value (stored value differs from the logged estimate) is not an estimate', () => {
+    assert.deepEqual(gate('audit', [['car-1|environmentEmissions.wltpCo2', '150']]).estimatedAttributes(icev()), []);
+    assert.deepEqual(gate('audit', [['car-1|environmentEmissions.wltpCo2', '139.0']]).estimatedAttributes(icev()), ['co2_emissions']);
+  }],
+  ['fallback field: wltpCombined missing, consumptionCombined sent and estimated', () => {
+    const car = icev({ consumption: { wltpCombined: null } });
+    assert.deepEqual(gate('audit', [['car-1|consumption.consumptionCombined', '6.4']]).estimatedAttributes(car), ['fuel_consumption']);
+  }],
+  ['other cars are not affected', () => {
+    assert.deepEqual(gate('audit', [['car-9|consumption.wltpCombined', '6.1']]).estimatedAttributes(icev()), []);
+  }],
+  ['confirmed plug-in: weighted values estimated, delivered range and CO2 kept', () => {
+    const g = gate('enforce', [
+      ['car-2|consumption.wltpWeightedCombined', '0.8'],
+      ['car-2|consumption.wltpWeightedPowerCombined', '15.6'],
+    ]);
+    const attributes = g.estimatedAttributes(plugIn());
+    assert.deepEqual(attributes, ['fuel_consumption', 'energy_consumption']);
+    const item = {
+      fuel_consumption: '0.8l/100km',
+      fuel_consumption_discharged_battery: '6.6l/100km',
+      energy_consumption: '15.6kWh/100km',
+      electric_range: '101km',
+      co2_emissions: '18g/km',
+    };
+    assert.deepEqual(g.apply(item, attributes), {
+      fuel_consumption_discharged_battery: '6.6l/100km',
+      electric_range: '101km',
+      co2_emissions: '18g/km',
+    });
+  }],
+  ['audit records but does not remove', () => {
+    const item = { fuel_consumption: '6.1l/100km' };
+    assert.deepEqual(gate('audit', []).apply(item, ['fuel_consumption']), { fuel_consumption: '6.1l/100km' });
+  }],
+  ['BEV CO2 0 g/km has no field behind it and is never gated', () => {
+    const bev: any = { _id: 'car-3', consumption: { fuel: 'selector_fuel_electrical', wltpPowerCombined: 16.8 }, engineData: {}, battery: {}, environmentEmissions: { wltpCo2: 0 } };
+    assert.deepEqual(gate('audit', [['car-3|environmentEmissions.wltpCo2', '0'], ['car-3|consumption.wltpPowerCombined', '16.8']]).estimatedAttributes(bev), ['energy_consumption']);
+  }],
+];
+
+let failed = 0;
+for (const [name, fn] of cases) {
+  try {
+    fn();
+    console.log(`ok   ${name}`);
+  } catch (e) {
+    failed += 1;
+    console.error(`FAIL ${name}\n     ${e.message}`);
+  }
+}
+if (failed) process.exit(1);