@bytebrand/export-cars 1.26.31 → 1.26.32

package/test/meinstadt-feed-run.test.ts

@@ -0,0 +1,288 @@
+// Run: npm test (ts-node, no test framework needed)
+// Integration: real files in a temp dir (base export snapshot, output, state), real JSON writer,
+// guard and ADV-336 clean-image selection; only HTTP (image check), UPA (equipment) and the zip
+// binary 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 { MeinstadtConfigError, MeinstadtFeedRun, MeinstadtSourceCar, zipSingleFile } from '../src/services/meinstadt-feed-run';
+import { toMeinstadtImages } from '../src/transformers/meinstadt.transformer';
+import { selectOpenAiImageFields } from '../src/transformers/openai-image-fields';
+import { buildImagesService } from './fixtures/images-service.harness';
+import { NOW, car, images, translate } from './fixtures/meinstadt.fixture';
+
+const HOUR = 60 * 60 * 1000;
+const imagesService = buildImagesService();
+
+interface World {
+  root: string;
+  source: string;
+  json: string;
+  zip: string;
+  state: string;
+  brokenImages: Set<string>;
+  zipCalls: number;
+}
+
+const newWorld = async (): Promise<World> => {
+  const root = await fs.mkdtemp(join(tmpdir(), 'meinstadt-'));
+  const out = join(root, 'meinstadt-dryrun');
+  return {
+    root,
+    source: join(root, 'cars-export'),
+    json: join(out, 'api_export_cars_meinstadt.json'),
+    zip: join(out, 'api_export_cars_meinstadt.zip'),
+    state: join(root, 'meinstadt-state', 'dryrun'),
+    brokenImages: new Set(),
+    zipCalls: 0,
+  };
+};
+
+const source = (id: string, overrides: Record<string, any> = {}): MeinstadtSourceCar => ({ car: car(id, overrides), images: images(id) });
+
+const writeSource = async (world: World, cars: MeinstadtSourceCar[], 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,
+});
+
+interface RunOptions {
+  at?: Date;
+  dryRun?: boolean;
+  cpc?: string | null;
+  guard?: Partial<FeedGuardOptions>;
+}
+
+const run = async (world: World, { at = NOW, dryRun = true, cpc = '0.99', guard = {} }: RunOptions = {}) => {
+  const forEachChunk = async (fn: (cars: MeinstadtSourceCar[]) => 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 MeinstadtFeedRun(
+    {
+      forEachChunk,
+      filterCar: ({ car: c }) => (c?.metaData?.imagesCount ?? 0) > 0,
+      resolveImages: async ({ car: c, images: list }) => {
+        const clean = imagesService.getCleanImages(c._id, list);
+        return toMeinstadtImages(selectOpenAiImageFields(clean, clean.map(i => ({ url: i.url, ok: !world.brokenImages.has(i.url) }))));
+      },
+      imageStats: () => ({ ok: 1 }),
+      equipment: async c => `Ausstattung ${c._id}`,
+      // fake zip: the test only needs to see which JSON was packed
+      zip: async (json, zip) => {
+        world.zipCalls += 1;
+        await fs.writeFile(zip, `ZIP:${await fs.readFile(json, 'utf8')}`);
+      },
+      guard: new FeedGuard(guardOptions(world, guard)),
+    },
+    {
+      runId: 'test',
+      dryRun,
+      cpc,
+      domain: 'auto.de',
+      sourceDirectory: world.source,
+      sourceBaseFileName: 'cars',
+      jsonFile: world.json,
+      zipFile: world.zip,
+      stateDir: world.state,
+      translate,
+      now: () => at,
+    },
+  );
+  return feed.run();
+};
+
+const readItems = async (world: World) => JSON.parse(await fs.readFile(world.json, 'utf8'));
+const exists = (file: string) => fs.stat(file).then(() => true, () => false);
+
+const tests: Array<[string, () => Promise<void>]> = [
+  ['first run: JSON array + ZIP of the published JSON, exclusions counted, report written', async () => {
+    const world = await newWorld();
+    const noImages = source('nopic');
+    noImages.car.metaData.imagesCount = 0;
+    const noHero = source('nohero');
+    noHero.images = noHero.images.filter(i => i.imageCodePredicted !== 'ext_f_right');
+    await writeSource(world, [
+      source('aaa1', { 'mainData.accidentDamaged': false }),
+      source('aaa2', { 'mainData.accidentDamaged': true }),
+      source('aaa3', { 'mainData.accidentDamaged': null }),
+      source('aaa1'),
+      noImages,
+      noHero,
+    ]);
+    const report = await run(world);
+    const items = await readItems(world);
+    assert.ok(Array.isArray(items));
+    assert.deepEqual(items.map((i: any) => i.listingUrl.split('/vehicle/')[1].split('?')[0]), ['aaa1', 'aaa2', 'aaa3']);
+    assert.deepEqual(items.map((i: any) => i.accidentFree), [true, false, null]);
+    for (const item of items) {
+      assert.ok(Array.isArray(item.images));
+      assert.equal(item.imagesCount, item.images.length);
+      assert.equal(item.images.length, 4);
+      assert.equal(item.cpc, '0.99');
+      assert.match(item.images[0], /hero1\/large-cached\.jpeg$/);
+    }
+    assert.equal(await fs.readFile(world.zip, 'utf8'), `ZIP:${await fs.readFile(world.json, 'utf8')}`);
+    assert.equal(report.status, 'published');
+    assert.equal(report.items, 3);
+    assert.deepEqual(report.excluded, { duplicate_id: 1, filtered: 1, no_valid_image: 1 });
+    assert.deepEqual(report.accidentFree, { true: 1, false: 1, null: 1 });
+    assert.deepEqual(report.imagesPerItem, { min: 4, max: 4, total: 12 });
+    const saved = JSON.parse(await fs.readFile(join(world.state, 'last-run-report.json'), 'utf8'));
+    assert.equal(saved.status, 'published');
+    assert.equal(await exists(`${world.json}.tmp`), false);
+    assert.equal(await exists(join(world.state, 'run.lock')), false);
+  }],
+
+  ['JSON file: UTF-8 umlauts, no BOM, parseable, items separated correctly', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('u1', { 'mainData.subModel': 'Größe Ü' }), source('u2')]);
+    await run(world);
+    const bytes = await fs.readFile(world.json);
+    assert.notEqual(bytes[0], 0xef);
+    assert.ok(bytes.includes(Buffer.from('Größe Ü', 'utf8')));
+    assert.equal((await readItems(world)).length, 2);
+  }],
+
+  ['broken image URLs are left out and imagesCount follows; broken hero -> car not sent', async () => {
+    const world = await newWorld();
+    world.brokenImages.add('https://images.auto.de/carimage/b1/b1back1/large-cached.jpeg');
+    world.brokenImages.add('https://images.auto.de/carimage/b1/b1int01/large-cached.jpeg');
+    world.brokenImages.add('https://images.auto.de/carimage/b2/b2hero1/large-cached.jpeg');
+    await writeSource(world, [source('b1'), source('b2')]);
+    const report = await run(world);
+    const items = await readItems(world);
+    assert.equal(items.length, 1);
+    assert.equal(items[0].imagesCount, 2);
+    assert.deepEqual(items[0].images, [
+      'https://images.auto.de/carimage/b1/b1hero1/large-cached.jpeg',
+      'https://images.auto.de/carimage/b1/b1side1/large-cached.jpeg',
+    ]);
+    assert.equal(report.excluded.no_valid_image, 1);
+  }],
+
+  ['live without cpc: config error before anything is read or written; dry-run without cpc sends null', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('c1')]);
+    await assert.rejects(run(world, { dryRun: false, cpc: null }), (e: any) => e instanceof MeinstadtConfigError && e.code === 'cpc_missing');
+    assert.equal(await exists(world.json), false);
+    assert.equal(await exists(world.zip), false);
+    assert.equal(JSON.parse(await fs.readFile(join(world.state, 'last-run-report.json'), 'utf8')).error, 'cpc_missing');
+    assert.equal(await exists(join(world.state, 'run.lock')), false);
+
+    const report = await run(world, { dryRun: true, cpc: null });
+    assert.equal(report.status, 'published');
+    assert.equal((await readItems(world))[0].cpc, null);
+    const live = await run(world, { dryRun: false, cpc: '0.99' });
+    assert.equal(live.mode, 'live');
+  }],
+
+  ['source outage: empty snapshot is blocked, last good JSON + ZIP untouched', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('s1'), source('s2')]);
+    await run(world);
+    const jsonBefore = await fs.readFile(world.json, 'utf8');
+    const zipBefore = await fs.readFile(world.zip, 'utf8');
+    await writeSource(world, []);
+    await assert.rejects(run(world, { at: new Date(NOW.getTime() + HOUR) }), (e: any) => e instanceof FeedGuardError && e.code === 'source_empty');
+    assert.equal(await fs.readFile(world.json, 'utf8'), jsonBefore);
+    assert.equal(await fs.readFile(world.zip, 'utf8'), zipBefore);
+    const saved = JSON.parse(await fs.readFile(join(world.state, 'last-run-report.json'), 'utf8'));
+    assert.equal(saved.status, 'blocked');
+    assert.equal(saved.guard.code, 'source_empty');
+  }],
+
+  ['partial source: base export died after the first pages -> count drop blocked, accepted on purpose', async () => {
+    const world = await newWorld();
+    const cars = Array.from({ length: 10 }, (_, i) => source(`p${i}`));
+    await writeSource(world, cars);
+    await run(world);
+    await writeSource(world, cars.slice(0, 4));
+    const later = new Date(NOW.getTime() + HOUR);
+    await assert.rejects(run(world, { at: later }), (e: any) => e instanceof FeedGuardError && e.code === 'count_drop');
+    assert.equal((await readItems(world)).length, 10);
+    assert.equal(await exists(`${world.json}.rejected`), true);
+    const accepted = await run(world, { at: later, guard: { acceptDrop: true } });
+    assert.equal(accepted.status, 'published');
+    assert.equal((await readItems(world)).length, 4);
+  }],
+
+  ['image outage: every hero broken -> published count below minimum, blocked', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('i1'), source('i2')]);
+    world.brokenImages.add('https://images.auto.de/carimage/i1/i1hero1/large-cached.jpeg');
+    world.brokenImages.add('https://images.auto.de/carimage/i2/i2hero1/large-cached.jpeg');
+    await assert.rejects(run(world), (e: any) => e instanceof FeedGuardError && e.code === 'published_too_small');
+    assert.equal(await exists(world.json), false);
+    assert.equal(world.zipCalls, 0);
+  }],
+
+  ['stale snapshot is blocked; a leftover temp file is never appended to', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('t1')], 2, new Date(NOW.getTime() - 30 * HOUR));
+    await assert.rejects(run(world), (e: any) => e instanceof FeedGuardError && e.code === 'source_stale');
+    await writeSource(world, [source('t1')]);
+    await fs.mkdir(join(world.root, 'meinstadt-dryrun'), { recursive: true });
+    await fs.writeFile(`${world.json}.tmp`, '[{"junk":true}');
+    await run(world);
+    assert.equal((await readItems(world)).length, 1);
+  }],
+
+  ['real ZIP: one entry api_export_cars_meinstadt.json, byte-identical to the published JSON', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('z1', { 'mainData.subModel': 'Größe' }), source('z2')]);
+    await run(world);
+    const zipFile = join(world.root, 'real.zip');
+    await zipSingleFile(world.json, zipFile);
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const AdmZip = require('adm-zip');
+    const entries = new AdmZip(zipFile).getEntries();
+    assert.deepEqual(entries.map((e: any) => e.entryName), ['api_export_cars_meinstadt.json']);
+    assert.ok(entries[0].getData().equals(await fs.readFile(world.json)));
+    // overwrites a leftover archive instead of appending to it
+    await zipSingleFile(world.json, zipFile);
+    assert.equal(new AdmZip(zipFile).getEntries().length, 1);
+  }],
+
+  ['lock: a second run while one holds the lock is refused', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('l1')]);
+    await fs.mkdir(world.state, { recursive: true });
+    await fs.writeFile(join(world.state, 'run.lock'), '{}');
+    await assert.rejects(run(world), (e: any) => e instanceof FeedGuardError && e.code === 'locked');
+  }],
+];
+
+(async () => {
+  let failed = 0;
+  for (const [name, fn] of tests) {
+    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/meinstadt-mapping.test.ts

@@ -0,0 +1,215 @@
+// Run: npm test (ts-node, no test framework needed)
+// meinestadt field mapping (ADV-325) and image list (ADV-326) — pure functions, no I/O.
+import * as assert from 'node:assert/strict';
+import { de } from '@bytebrand/i18n-dictionaries';
+
+import { MeinstadtConfig, parseMeinstadtCpc } from '../src/configs/meinstadt.config';
+import { Environment, ExportType, ImageType } from '../src/enums';
+import {
+  mapMeinstadtItem,
+  toAccidentFree,
+  toMeinstadtImages,
+  toUnixSeconds,
+  translateSelector,
+} from '../src/transformers/meinstadt.transformer';
+import { selectOpenAiImageFields } from '../src/transformers/openai-image-fields';
+import { buildImagesService } from './fixtures/images-service.harness';
+import { car, eightImages, images, translate } from './fixtures/meinstadt.fixture';
+
+const imagesService = buildImagesService();
+const ctx = (extra: Record<string, any> = {}) => ({ domain: 'auto.de', cpc: '0.99', equipment: 'ABS', images: ['https://x/1.jpeg'], translate, ...extra });
+
+const tests: Array<[string, () => void | Promise<void>]> = [
+  ['accidentFree: damaged=false -> true, damaged=true -> false, unknown -> null (never accident-free)', () => {
+    assert.equal(toAccidentFree(false), true);
+    assert.equal(toAccidentFree(true), false);
+    assert.equal(toAccidentFree(null), null);
+    assert.equal(toAccidentFree(undefined), null);
+    assert.equal(toAccidentFree('false'), null);
+    assert.equal(mapMeinstadtItem(car('a1', { 'mainData.accidentDamaged': false }), ctx()).accidentFree, true);
+    assert.equal(mapMeinstadtItem(car('a2', { 'mainData.accidentDamaged': true }), ctx()).accidentFree, false);
+    assert.equal(mapMeinstadtItem(car('a3', { 'mainData.accidentDamaged': null }), ctx()).accidentFree, null);
+    const noField = car('a4');
+    delete noField.mainData.accidentDamaged;
+    assert.equal(mapMeinstadtItem(noField, ctx()).accidentFree, null);
+  }],
+
+  ['cpc: only a positive decimal counts as configured, no hidden 0.08 / 0 default', () => {
+    assert.equal(parseMeinstadtCpc('0.99'), '0.99');
+    assert.equal(parseMeinstadtCpc(' 0.5 '), '0.5');
+    assert.equal(parseMeinstadtCpc('1'), '1');
+    for (const value of [undefined, null, '', '   ', '0', '0.00', '0,08', '-0.1', 'abc', 0.08]) {
+      assert.equal(parseMeinstadtCpc(value), null, `cpc ${JSON.stringify(value)}`);
+    }
+    const params = { environment: Environment.DEVELOP, exportType: ExportType.MEINSTADT };
+    assert.equal(new MeinstadtConfig(params).cpc, null);
+    assert.equal(mapMeinstadtItem(car('c1'), ctx({ cpc: null })).cpc, null);
+    assert.equal(new MeinstadtConfig({ ...params, cpc: '0.99' }).cpc, '0.99');
+  }],
+
+  ['config: dry-run by default (own dir + state), live only with meinstadtDryRun=false; clean images', () => {
+    const params = { environment: Environment.DEVELOP, exportType: ExportType.MEINSTADT };
+    const dry = new MeinstadtConfig(params);
+    assert.equal(dry.dryRun, true);
+    assert.equal(dry.imageType, ImageType.clean);
+    assert.deepEqual(dry.outputFiles, [
+      'resources/meinstadt-dryrun/api_export_cars_meinstadt.json',
+      'resources/meinstadt-dryrun/api_export_cars_meinstadt.zip',
+    ]);
+    assert.equal(dry.stateDir, 'resources/meinstadt-state/dryrun');
+    assert.equal(new MeinstadtConfig({ ...params, meinstadtDryRun: 'TRUE' }).dryRun, true);
+    assert.equal(new MeinstadtConfig({ ...params, meinstadtDryRun: 'no' }).dryRun, true);
+    const live = new MeinstadtConfig({ ...params, meinstadtDryRun: 'false' });
+    assert.equal(live.dryRun, false);
+    // live keeps the historical path the Cronicle upload step reads
+    assert.deepEqual(live.outputFiles, [
+      'resources/meinstadt-export/api_export_cars_meinstadt.json',
+      'resources/meinstadt-export/api_export_cars_meinstadt.zip',
+    ]);
+    assert.equal(live.stateDir, 'resources/meinstadt-state/export');
+    assert.equal(dry.maxImages, 0);
+    assert.equal(new MeinstadtConfig({ ...params, meinstadtMaxImages: '1' }).maxImages, 1);
+    assert.equal(new MeinstadtConfig({ ...params, feedGuardMinSourceItems: '5' }).feedGuard.minSourceItems, 5);
+  }],
+
+  ['dates: Unix seconds kept, missing / 0 / negative / garbage -> null (no 1970), Date and ISO converted', () => {
+    assert.equal(toUnixSeconds(1750809600), 1750809600);
+    assert.equal(toUnixSeconds(0), null);
+    assert.equal(toUnixSeconds(-86400), null);
+    assert.equal(toUnixSeconds(null), null);
+    assert.equal(toUnixSeconds(undefined), null);
+    assert.equal(toUnixSeconds(''), null);
+    assert.equal(toUnixSeconds('garbage'), null);
+    assert.equal(toUnixSeconds(NaN), null);
+    assert.equal(toUnixSeconds(new Date('2025-06-25T00:00:00Z')), 1750809600);
+    assert.equal(toUnixSeconds('2025-06-25T00:00:00Z'), 1750809600);
+    assert.equal(toUnixSeconds(new Date(0)), null);
+    const item = mapMeinstadtItem(car('d1', { 'mainData.firstRegistration': 0, 'metaData.creationDate': 1783408438 }), ctx());
+    assert.equal(item.initialRegistration, null);
+    // the CBD creation date is passed through, never replaced by the export time
+    assert.equal(item.offerCreationDate, 1783408438);
+    assert.equal(mapMeinstadtItem(car('d2', { 'mainData.firstRegistration': null }), ctx()).initialRegistration, null);
+  }],
+
+  ['power = PS (not kW), price = currentSalesPrice (not dealer purchasePrice, not the rate)', () => {
+    const item = mapMeinstadtItem(car('p1'), ctx());
+    assert.equal(item.power, 116);
+    assert.equal(item.price, 15148);
+    assert.equal(item.mileage, 13000);
+  }],
+
+  ['German labels; selector_unknown / unmapped selectors -> null, not "Unbekannt"', () => {
+    assert.equal(translateSelector('selector_unknown', translate), null);
+    assert.equal(translateSelector('selector_category_combi', translate), 'Kombi');
+    assert.equal(translateSelector('selector_does_not_exist', translate), null);
+    assert.equal(translateSelector(null, translate), null);
+    // default translator = i18n-dictionaries `de`, which maps selector_unknown to "Unbekannt"
+    assert.equal(de.selector_unknown, 'Unbekannt');
+    assert.equal(translateSelector('selector_unknown'), null);
+    assert.equal(translateSelector('selector_fuel_petrol'), de.selector_fuel_petrol);
+    const item = mapMeinstadtItem(car('l1', {
+      'mainData.category': 'selector_unknown',
+      'environmentEmissions.emissionClass': 'selector_unknown',
+      'driveSuspension.gearbox': 'selector_unknown',
+    }), ctx());
+    assert.equal(item.bodyType, null);
+    assert.equal(item.emissionClass, null);
+    assert.equal(item['transmissionType/transmission'], null);
+    assert.equal(item.usageState, 'Gebraucht');
+    assert.equal(mapMeinstadtItem(car('l2', { 'mainData.condition': 'selector_unknown', 'mainData.mileage': 5 }), ctx()).usageState, 'Neu');
+  }],
+
+  ['item: historical keys and order, slash keys kept literally, no city/zip/lat/long', () => {
+    const item = mapMeinstadtItem(car('k1'), ctx({ images: ['https://x/1.jpeg', 'https://x/2.jpeg'] }));
+    assert.deepEqual(Object.keys(item), [
+      'id', 'make', 'model', 'cpc', 'listingUrl', 'title', 'accidentFree', 'mileage', 'initialRegistration',
+      'offerCreationDate', 'numberOfDoors', 'numberOfSeats', 'numberOfPreviousOwners', 'price', 'power',
+      'co2Emissions', 'fuelConsumptionCombined', 'equipment', 'color', 'bodyType', 'emissionClass',
+      'emissionSticker', 'fuelType', 'transmissionType/transmission', 'imagesCount', 'customerType/sellerType',
+      'usageState', 'images',
+    ]);
+    assert.deepEqual(item, {
+      id: 'VK1',
+      make: 'Opel',
+      model: 'Astra',
+      cpc: '0.99',
+      listingUrl: 'https://www.auto.de/search/vehicle/k1?source=classifieds&medium=listing&campaign=meinestadt',
+      title: 'Opel Astra 1.2 Turbo Edition',
+      accidentFree: true,
+      mileage: 13000,
+      initialRegistration: 1750809600,
+      offerCreationDate: 1783408438,
+      numberOfDoors: 5,
+      numberOfSeats: 5,
+      numberOfPreviousOwners: 1,
+      price: 15148,
+      power: 116,
+      co2Emissions: 137,
+      fuelConsumptionCombined: 6.1,
+      equipment: 'ABS',
+      color: 'Rot',
+      bodyType: 'Kombi',
+      emissionClass: 'Euro 6',
+      emissionSticker: 'Feinstaubplakette grün (4)',
+      fuelType: 'Benzin',
+      'transmissionType/transmission': 'Manuell',
+      imagesCount: 2,
+      'customerType/sellerType': 'Händler',
+      usageState: 'Gebraucht',
+      images: ['https://x/1.jpeg', 'https://x/2.jpeg'],
+    });
+  }],
+
+  ['images: 8 raw images, only 1 valid -> exactly 1 URL and imagesCount 1', () => {
+    const clean = imagesService.getCleanImages('car-8', eightImages('e'));
+    assert.equal(clean.length, 8);
+    const valid = clean[0].url;
+    const selection = selectOpenAiImageFields(clean, clean.map(i => ({ url: i.url, ok: i.url === valid })));
+    const list = toMeinstadtImages(selection);
+    assert.deepEqual(list, [valid]);
+    const item = mapMeinstadtItem(car('car-8'), ctx({ images: list }));
+    assert.deepEqual(item.images, [valid]);
+    assert.equal(item.imagesCount, 1);
+  }],
+
+  ['images: URL array (not ids, not a string), hero first, all valid in clean order, count = length', () => {
+    const clean = imagesService.getCleanImages('car-g', images('g'));
+    const list = toMeinstadtImages(selectOpenAiImageFields(clean, clean.map(i => ({ url: i.url, ok: true }))));
+    assert.deepEqual(list, [
+      'https://images.auto.de/carimage/car-g/ghero1/large-cached.jpeg',
+      'https://images.auto.de/carimage/car-g/gside1/large-cached.jpeg',
+      'https://images.auto.de/carimage/car-g/gback1/large-cached.jpeg',
+      'https://images.auto.de/carimage/car-g/gint01/large-cached.jpeg',
+    ]);
+    const item = mapMeinstadtItem(car('car-g'), ctx({ images: list }));
+    assert.ok(Array.isArray(item.images));
+    assert.equal(item.imagesCount, item.images.length);
+    assert.ok(item.images.every(url => url.startsWith('https://') && !url.includes('/noimage/')));
+  }],
+
+  ['images: no valid 3/4 hero -> [] (car skipped); maxImages cuts the list only', () => {
+    const clean = imagesService.getCleanImages('car-h', images('h'));
+    const heroBroken = clean.map(i => ({ url: i.url, ok: !i.heroCandidate }));
+    assert.deepEqual(toMeinstadtImages(selectOpenAiImageFields(clean, heroBroken)), []);
+    assert.deepEqual(toMeinstadtImages({ fields: null, rejected: [] }), []);
+    const allOk = selectOpenAiImageFields(clean, clean.map(i => ({ url: i.url, ok: true })));
+    assert.deepEqual(toMeinstadtImages(allOk, 1), [clean[0].url]);
+    assert.equal(toMeinstadtImages(allOk, 0).length, 4);
+    // the selection itself is not modified by the cut
+    assert.equal(allOk.fields.additional_image_urls.length, 3);
+  }],
+];
+
+(async () => {
+  let failed = 0;
+  for (const [name, fn] of tests) {
+    try {
+      await fn();
+      console.log(`ok   ${name}`);
+    } catch (e) {
+      failed += 1;
+      console.error(`FAIL ${name}\n     ${e.message}`);
+    }
+  }
+  if (failed) process.exit(1);
+})();