@bytebrand/export-cars 1.26.31 → 1.26.33

package/src/transformers/openai-ads-finance.ts

@@ -0,0 +1,60 @@
+/**
+ * No finance claims in the OpenAI Ads feed (ADV-335/336 launch gate, 13.10). OpenAI's ads policy
+ * lists "Auto loans and leasing" outside the US as "Restricted to Select Approved Advertisers", so
+ * the feed must not carry rates, interest, leasing or monthly-payment wording at all.
+ *
+ * The only source today is the dealer's variant text (mainData.subModel), e.g. "GLB 200
+ * 4,49%Finz./Progressive" or "Tourneo Custom L1 0% Zins" — the description is generated from
+ * structured fields and repeats the title. Two layers:
+ * - stripFinanceClaims: removes finance tokens (word-bounded) before the title is normalised;
+ * - hasFinanceClaim: a broader substring check on the final title/description; a match keeps the
+ *   car out of the feed (exclusion `finance_claim`), so anything the stripping misses fails closed.
+ */
+
+// A percentage next to these words is a battery/damage figure, not an interest rate:
+// "99% SoH", "Akku 95%", "100% elektrisch", "0% Schaden".
+const NON_FINANCE_PERCENT_CONTEXT = /soh|akku|batter|kapazit|elektr|schaden|unfall|reichweite|ladung/i;
+const PERCENT = /\d{1,3}(?:[.,]\d{1,2})?\s*%-?/g;
+
+const FINANCE_TOKENS: RegExp[] = [
+  // monthly amounts: "ab 199 € mtl.", "199€/Monat", "mtl. 199 €", "pro Monat"
+  /(?:\bab\s+)?\d[\d.,]*\s*(?:€|\beur\b|\beuro\b)?\s*(?:\/\s*|pro\s+|im\s+)?(?:\bmonat\b|\bmtl\b\.?|\bmonatl\b\.?|\bmonatlich\b)/gi,
+  /(?:\bmtl\b\.?|\bmonatl\b\.?|\bmonatlich\w*)\s*(?:ab\s+)?(?:\d[\d.,]*\s*(?:€|\beur\b|\beuro\b)?)?/gi,
+  /(?:€|\beur\b|\beuro\b)?\s*(?:\/\s*|\bpro\s+|\bim\s+)monat\b/gi,
+  // finance words
+  /\beffektiv(?:er|en)?\s+jahreszins\w*/gi,
+  /\b(?:finz\b\.?|finanz\w*|ballonfinanz\w*|zins\w*|sollzins\w*|jahreszins\w*|schlussrate\w*|monatsrate\w*|raten?|leasing\w*|leasen|anzahlung\w*|kredit\w*|darlehen\w*|santander)\b\.?/gi,
+];
+
+// Broader than the stripping patterns (substrings, glued words like "AMGFinanzierung").
+const FINANCE_CLAIM = /finanz|\bfinz\b|zins|leasing|leasen|santander|darlehen|kredit|anzahlung|schlussrate|monatsrate|\bmtl\b|monatl|\braten?\b|\/\s*monat|pro\s+monat|im\s+monat/i;
+
+const CUT = '\u0000';
+const SEPARATORS = '[\\s/,;|+&\\-–]*';
+const CUT_WITH_SEPARATORS = new RegExp(`${SEPARATORS}${CUT}(?:${SEPARATORS}${CUT})*${SEPARATORS}`, 'g');
+
+// Only the word right before the number or right after the "%" counts ("Akku 95%", "99% SoH"), so
+// "Elektromotor V 0,0%" is still a rate.
+const isFinancePercent = (match: string, offset: number, text: string): boolean => {
+  const before = /([^\s/,;|]*)[\s/,;|]*$/.exec(text.slice(0, offset))[1];
+  const after = /^[\s/,;|]*([^\s/,;|]*)/.exec(text.slice(offset + match.length))[1];
+  return !NON_FINANCE_PERCENT_CONTEXT.test(before) && !NON_FINANCE_PERCENT_CONTEXT.test(after);
+};
+
+// Finance tokens out, together with the separators around them ("SB 4,49%/AMG" -> "SB AMG").
+export const stripFinanceClaims = (text: string): string => {
+  let out = text || '';
+  for (const pattern of FINANCE_TOKENS) {
+    out = out.replace(pattern, CUT);
+  }
+  out = out.replace(PERCENT, (match: string, offset: number, whole: string) => (isFinancePercent(match, offset, whole) ? CUT : match));
+  return out.includes(CUT) ? out.replace(CUT_WITH_SEPARATORS, ' ').replace(/\s+/g, ' ').trim() : text || '';
+};
+
+export const hasFinanceClaim = (text: string): boolean => {
+  const value = text || '';
+  if (FINANCE_CLAIM.test(value)) {
+    return true;
+  }
+  return [...value.matchAll(PERCENT)].some(match => isFinancePercent(match[0], match.index, value));
+};

package/src/transformers/openai-ads.transformer.ts

@@ -9,6 +9,7 @@ import {
   OpenAiAdsRow,
 } from '../interfaces/openai-ads.interface';
 import { OpenAiImageFields, encodeCommasInUrl } from './openai-image-fields';
+import { hasFinanceClaim, stripFinanceClaims } from './openai-ads-finance';
 
 // OpenAI product file limits (guidance): title ≤ 150, description ≤ 5,000 characters.
 export const OPENAI_TITLE_MAX_LENGTH = 150;
@@ -51,7 +52,8 @@ export interface OpenAiAdsMappingContext {
 export type OpenAiAdsBaseRow = Omit<OpenAiAdsRow, 'image_url' | 'additional_image_urls'>;
 
 export type OpenAiAdsMapResult =
-  | { ok: true; row: OpenAiAdsBaseRow; outOfStockReason?: OpenAiAdsOutOfStockReason }
+  // financeTermsRemoved: the dealer variant text carried finance wording that was cut from the title
+  | { ok: true; row: OpenAiAdsBaseRow; outOfStockReason?: OpenAiAdsOutOfStockReason; financeTermsRemoved?: boolean }
   | { ok: false; reason: OpenAiAdsExclusion };
 
 /**
@@ -98,8 +100,19 @@ export const mapOpenAiAdsVehicle = (car: DataSchemes.Car, ctx: OpenAiAdsMappingC
     is_ads_eligible: true,
   };
 
+  // fail-closed: whatever finance wording survived the stripping keeps the car out of the feed
+  if (hasFinanceClaim(row.title) || hasFinanceClaim(row.description)) {
+    return { ok: false, reason: OpenAiAdsExclusion.financeClaim };
+  }
+
   const outOfStockReason = OFFER_AVAILABILITY_OUT_OF_STOCK[toString(get(car, 'offer.offerAvailability', ''))];
-  return outOfStockReason ? { ok: true, row, outOfStockReason } : { ok: true, row };
+  const financeTermsRemoved = title !== buildOpenAiTitle(car, { keepFinanceTerms: true });
+  return {
+    ok: true,
+    row,
+    ...(outOfStockReason ? { outOfStockReason } : {}),
+    ...(financeTermsRemoved ? { financeTermsRemoved } : {}),
+  };
 };
 
 export const withOpenAiImages = (row: OpenAiAdsBaseRow, images: OpenAiImageFields): OpenAiAdsRow => ({
@@ -112,11 +125,22 @@ export const withOpenAiImages = (row: OpenAiAdsBaseRow, images: OpenAiImageField
 // The same vehicle, switched off: kept in the file so OpenAI stops delivering it instead of
 // relying on the row disappearing (not documented as a removal).
 export const asOutOfStock = (row: OpenAiAdsRow): OpenAiAdsRow => ({
-  ...row,
+  ...withoutFinanceClaims(row),
   availability: 'out_of_stock',
   is_ads_eligible: false,
 });
 
+// Rows re-sent from the ledger may predate the finance rule: strip again, and if wording is still
+// left, fall back to the brand alone (the row only switches the item off).
+export const withoutFinanceClaims = <T extends { title: string; description: string; brand: string }>(row: T): T => {
+  const title = stripFinanceClaims(row.title);
+  const description = stripFinanceClaims(row.description);
+  if (!hasFinanceClaim(title) && !hasFinanceClaim(description)) {
+    return title === row.title && description === row.description ? row : { ...row, title, description };
+  }
+  return { ...row, title: row.brand, description: row.brand };
+};
+
 // Purchase price (price.currentSalesPrice, EUR gross) in major units with exactly two decimals and
 // no thousands separator: 17990 -> "17990.00 EUR". Never a monthly financing/leasing rate.
 // null = not a valid positive price; the car is not exported.
@@ -140,10 +164,12 @@ export const toOpenAiMinorUnits = (value: unknown): number | null => {
 // "<make> <model> <variant>" as delivered (German market names), dealer junk punctuation removed
 // with the same normalizer as the Meta feed, cut at a word boundary. No HTML escaping: CSV quoting
 // handles every character. A placeholder model (SONSTIGE) is left out ("MG 1.5 Hybrid Luxury");
-// with neither a real model nor a variant there is no title and the car is not sent.
-export const buildOpenAiTitle = (car: DataSchemes.Car): string => {
+// with neither a real model nor a variant there is no title and the car is not sent. Finance wording
+// in the dealer text ("4,49%Finz.", "0% Zins") is cut first (openai-ads-finance.ts).
+export const buildOpenAiTitle = (car: DataSchemes.Car, options: { keepFinanceTerms?: boolean } = {}): string => {
   const [make, model, subModel] = ['mainData.make', 'mainData.model', 'mainData.subModel']
-    .map(path => repairMojibake(trim(toString(get(car, path, '')))));
+    .map(path => repairMojibake(trim(toString(get(car, path, '')))))
+    .map(part => (options.keepFinanceTerms ? part : stripFinanceClaims(part)));
   const realModel = PLACEHOLDER_NAMES.test(model) ? '' : model;
   if (!normalizeFeedText(`${realModel} ${subModel}`)) {
     return '';

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

@@ -0,0 +1,256 @@
+// 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) and UPA (dealer) 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 { AutouncleFeedRun, AutouncleSourceCar } from '../src/services/autouncle-feed-run';
+import { toAutouncleImages } from '../src/transformers/autouncle.transformer';
+import { selectOpenAiImageFields } from '../src/transformers/openai-image-fields';
+import { buildImagesService } from './fixtures/images-service.harness';
+import { NOW, car, images } from './fixtures/meinstadt.fixture';
+
+const HOUR = 60 * 60 * 1000;
+const imagesService = buildImagesService();
+const ADDRESS = { city: 'Sandersdorf-Brehna', addr1: 'Max-Planck-Str. 19', region: 'Brehna', postal_code: '06796' };
+
+interface World {
+  root: string;
+  source: string;
+  json: string;
+  state: string;
+  brokenImages: Set<string>;
+  unknownDealers: Set<string>;
+  dealerLookups: number;
+}
+
+const newWorld = async (): Promise<World> => {
+  const root = await fs.mkdtemp(join(tmpdir(), 'autouncle-'));
+  return {
+    root,
+    source: join(root, 'cars-export'),
+    json: join(root, 'autouncle-dryrun', 'api_export_cars_autouncle.json'),
+    state: join(root, 'autouncle-state', 'dryrun'),
+    brokenImages: new Set(),
+    unknownDealers: new Set(),
+    dealerLookups: 0,
+  };
+};
+
+const source = (id: string, overrides: Record<string, any> = {}): AutouncleSourceCar => ({ car: car(id, overrides), images: images(id) });
+
+const writeSource = async (world: World, cars: AutouncleSourceCar[], 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 = NOW, guard = {} }: { at?: Date; guard?: Partial<FeedGuardOptions> } = {}) => {
+  const forEachChunk = async (fn: (cars: AutouncleSourceCar[]) => 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 AutouncleFeedRun(
+    {
+      forEachChunk,
+      filterCar: ({ car: c }) => (c?.metaData?.imagesCount ?? 0) > 0,
+      dealerAddress: async (ownerId) => {
+        world.dealerLookups += 1;
+        return world.unknownDealers.has(ownerId) ? null : ADDRESS;
+      },
+      resolveImages: async ({ car: c, images: list }) => {
+        const clean = imagesService.getCleanImages(c._id, list);
+        return toAutouncleImages(selectOpenAiImageFields(clean, clean.map(i => ({ url: i.url, ok: !world.brokenImages.has(i.url) }))));
+      },
+      imageStats: () => ({ ok: 1 }),
+      translate: key => key,
+      guard: new FeedGuard(guardOptions(world, guard)),
+    },
+    {
+      runId: 'test',
+      dryRun: true,
+      domain: 'auto.de',
+      sourceDirectory: world.source,
+      sourceBaseFileName: 'cars',
+      jsonFile: world.json,
+      stateDir: world.state,
+      now: () => at,
+    },
+  );
+  return feed.run();
+};
+
+const readAds = async (world: World) => JSON.parse(await fs.readFile(world.json, 'utf8')).ads;
+const ids = (ads: any[]) => ads.map((a: any) => a.back_link.split('/vehicle/')[1].split('?')[0]);
+const exists = (file: string) => fs.stat(file).then(() => true, () => false);
+
+const tests: Array<[string, () => Promise<void>]> = [
+  ['first run: {"ads":[...]} without the duplicated first car, 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');
+    world.unknownDealers.add('dealer-x');
+    await writeSource(world, [
+      source('aaa1', { 'metaData.ownerId': 'dealer-1' }),
+      source('aaa2', { 'metaData.ownerId': 'dealer-1' }),
+      source('aaa3', { 'metaData.ownerId': 'dealer-2', 'mainData.firstRegistration': null }),
+      source('aaa1'),
+      noImages,
+      noHero,
+      source('sold', { 'offer.offerAvailability': 'selector_offerAvailability_sold' }),
+      source('resv', { 'offer.offerAvailability': 'selector_offerAvailability_reserved' }),
+      source('noprice', { 'price.currentSalesPrice': null }),
+      source('nodealer', { 'metaData.ownerId': 'dealer-x' }),
+    ]);
+    const report = await run(world);
+    const ads = await readAds(world);
+    assert.deepEqual(ids(ads), ['aaa1', 'aaa2', 'aaa3']);
+    // two cars of one dealer share seller_id
+    assert.deepEqual(ads.map((a: any) => a.seller_id), ['dealer-1', 'dealer-1', 'dealer-2']);
+    assert.deepEqual(ads.map((a: any) => a.year), ['2025', '2025', '']);
+    for (const ad of ads) {
+      assert.equal(ad.images.length, 4);
+      assert.match(ad.images[0].url, /hero1\/large-cached\.jpeg$/);
+      assert.ok(ad.images.every(({ url }: { url: string }) => !url.includes('/noimage/')));
+      assert.equal(ad.price, 'EUR 15148');
+    }
+    assert.equal(report.status, 'published');
+    assert.equal(report.items, 3);
+    assert.equal(report.dealers, 2);
+    assert.deepEqual(report.excluded, {
+      duplicate_id: 1,
+      filtered: 1,
+      no_valid_image: 1,
+      reserved_or_sold: 2,
+      no_valid_price: 1,
+      no_dealer: 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, single object with ads array', 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.ok(bytes.toString('utf8').startsWith('{"ads":[{'));
+    assert.equal((await readAds(world)).length, 2);
+  }],
+
+  ['broken image URLs are left out; 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/b2/b2hero1/large-cached.jpeg');
+    await writeSource(world, [source('b1'), source('b2')]);
+    const report = await run(world);
+    const ads = await readAds(world);
+    assert.deepEqual(ids(ads), ['b1']);
+    assert.deepEqual(ads[0].images.map((i: any) => i.url), [
+      'https://images.auto.de/carimage/b1/b1hero1/large-cached.jpeg',
+      'https://images.auto.de/carimage/b1/b1side1/large-cached.jpeg',
+      'https://images.auto.de/carimage/b1/b1int01/large-cached.jpeg',
+    ]);
+    assert.equal(report.excluded.no_valid_image, 1);
+  }],
+
+  ['source outage: empty snapshot is blocked, last good JSON untouched', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('g1'), source('g2')]);
+    await run(world);
+    const good = await fs.readFile(world.json, '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'), good);
+    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');
+    assert.equal(await exists(join(world.state, 'run.lock')), false);
+  }],
+
+  ['partial snapshot (missing chunk) and stale snapshot are blocked', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('p1'), source('p2'), source('p3'), source('p4'), source('p5')]);
+    await fs.rm(join(world.source, 'cars.1.json'));
+    await assert.rejects(run(world), (e: any) => e instanceof FeedGuardError && e.code === 'source_partial');
+    assert.equal(await exists(world.json), false);
+
+    await writeSource(world, [source('s1')], 2, new Date(NOW.getTime() - 30 * HOUR));
+    await assert.rejects(run(world), (e: any) => e instanceof FeedGuardError && e.code === 'source_stale');
+    assert.equal(await exists(world.json), false);
+  }],
+
+  ['count drop > 20% is blocked (rejected file kept), acceptDrop publishes once', async () => {
+    const world = await newWorld();
+    const ten = Array.from({ length: 10 }, (_, i) => source(`c${i}`));
+    await writeSource(world, ten);
+    await run(world);
+    const good = await fs.readFile(world.json, 'utf8');
+    await writeSource(world, ten.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 fs.readFile(world.json, 'utf8'), good);
+    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 readAds(world)).length, 4);
+    assert.equal(await fs.readFile(`${world.json}.prev`, 'utf8'), good);
+  }],
+
+  ['nothing publishable -> blocked, never an empty {"ads":[]} file', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('n1', { 'price.currentSalesPrice': 0 }), source('n2', { 'offer.offerAvailability': 'selector_offerAvailability_sold' })]);
+    await assert.rejects(run(world), (e: any) => e instanceof FeedGuardError && e.code === 'published_too_small');
+    assert.equal(await exists(world.json), false);
+  }],
+
+  ['second run with the same snapshot: byte-identical file (stable ids, order, links)', async () => {
+    const world = await newWorld();
+    await writeSource(world, [source('i1'), source('i2'), source('i3')]);
+    await run(world);
+    const first = await fs.readFile(world.json, 'utf8');
+    await run(world, { at: new Date(NOW.getTime() + HOUR) });
+    assert.equal(await fs.readFile(world.json, 'utf8'), first);
+  }],
+];
+
+(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);
+})();

package/test/autouncle-mapping.test.ts

@@ -0,0 +1,225 @@
+// Run: npm test (ts-node, no test framework needed)
+// AutoUncle `ads[]` mapping (ADV-322) and image list (ADV-323) — pure functions, no network.
+import * as assert from 'node:assert/strict';
+
+import { AutouncleConfig } from '../src/configs/autouncle.config';
+import { AutouncleJsonBuilder } from '../src/formats/autouncle-json.builder';
+import { Environment, ExportType, ImageType } from '../src/enums';
+import {
+  AutouncleExclusion,
+  AutouncleTransformer,
+  getAutounclePrice,
+  getAutouncleStatus,
+  getAutouncleYear,
+  mapAutouncleItem,
+  toAutouncleImages,
+} from '../src/transformers/autouncle.transformer';
+import { selectOpenAiImageFields } from '../src/transformers/openai-image-fields';
+import { buildImagesService } from './fixtures/images-service.harness';
+import { car, eightImages, images } from './fixtures/meinstadt.fixture';
+import { promises as fs } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+const imagesService = buildImagesService();
+const ADDRESS = { city: 'Sandersdorf-Brehna', addr1: 'Max-Planck-Str. 19', region: 'Sachsen-Anhalt', postal_code: '06796' };
+const ctx = (extra: Record<string, any> = {}) => ({
+  domain: 'auto.de',
+  address: ADDRESS,
+  images: ['https://images.auto.de/carimage/x/hero/large-cached.jpeg'],
+  translate: (key: string) => ({ selector_exteriorColor_red: 'Rot', other: 'Andere' }[key] ?? key),
+  ...extra,
+});
+const item = (c: any, extra: Record<string, any> = {}) => {
+  const result = mapAutouncleItem(c, ctx(extra));
+  assert.equal(result.ok, true, `expected ok, got ${JSON.stringify(result)}`);
+  return (result as any).item;
+};
+const reason = (c: any, extra: Record<string, any> = {}) => {
+  const result = mapAutouncleItem(c, ctx(extra));
+  assert.equal(result.ok, false);
+  return (result as any).reason;
+};
+const NOW = new Date('2026-10-13T08:00:00Z');
+
+// Historic key set and order (Confluence "2.7.2 Export Plugins" + the exporter since init commit),
+// misspellings included, until AutoUncle confirms a current schema.
+const HISTORIC_KEYS = [
+  'back_link', 'make', 'model_name', 'model_variant', 'fuel', 'body', 'doors', 'price', 'year', 'status',
+  'mileage', 'leasing', 'color', 'engine_size', 'power', 'gear_type', 'has_4wd', 'seller_type', 'seller_region',
+  'seller_city', 'seller_street_address', 'seller_postcode', 'seller_name', 'seller_id', 'description', 'images',
+  'fuel_economy', 'co2_emission', 'co2_effiency_class', 'euro_emission_class', 'enviromental_sticker',
+];
+
+const tests: Array<[string, () => void | Promise<void>]> = [
+  ['keys: historic set, order and spellings unchanged', () => {
+    assert.deepEqual(Object.keys(item(car('k1'))), HISTORIC_KEYS);
+  }],
+
+  ['identity: seller_id = dealer (ownerId) for every car of one dealer; back_link = stable car _id', () => {
+    const a = item(car('car-a', { 'metaData.ownerId': 'dealer-7' }));
+    const b = item(car('car-b', { 'metaData.ownerId': 'dealer-7' }));
+    assert.equal(a.seller_id, 'dealer-7');
+    assert.equal(b.seller_id, 'dealer-7');
+    assert.notEqual(a.back_link, b.back_link);
+    assert.equal(a.back_link, 'https://www.auto.de/search/vehicle/car-a?source=classifieds&medium=cpc&campaign=autouncle');
+    // same car again -> byte-identical back_link (no relisting under a new URL)
+    assert.equal(item(car('car-a', { 'metaData.ownerId': 'dealer-7' })).back_link, a.back_link);
+    // seller_id is never a vehicle id
+    assert.notEqual(a.seller_id, car('car-a').metaData.vehicleId);
+  }],
+
+  ['year: null / 0 / missing / garbage -> "" (never 1970); status follows the same rule', () => {
+    for (const value of [null, 0, undefined, '', 'abc', -5]) {
+      assert.equal(getAutouncleYear(value, NOW), '', `year for ${JSON.stringify(value)}`);
+      assert.equal(getAutouncleStatus(value), 'Neuwagen');
+    }
+    const noField = car('y0');
+    delete noField.mainData.firstRegistration;
+    assert.equal(item(noField).year, '');
+    const nullYear = item(car('y1', { 'mainData.firstRegistration': null }));
+    assert.equal(nullYear.year, '');
+    assert.notEqual(nullYear.year, '1970');
+    assert.equal(nullYear.status, 'Neuwagen');
+    // 2025-06-25 in Unix seconds
+    const used = item(car('y2', { 'mainData.firstRegistration': 1750809600 }));
+    assert.equal(used.year, '2025');
+    assert.equal(used.status, 'Gebrauchtwagen');
+    // milliseconds by mistake -> year 57453 -> unknown, not a fantasy year
+    assert.equal(getAutouncleYear(1750809600000, NOW), '');
+  }],
+
+  ['price: EUR purchase price (currentSalesPrice), never the rate or the dealer cost; invalid -> car not sent', () => {
+    const c = car('p1', { 'price.currentSalesPrice': 15148, 'price.purchasePrice': 11000, 'rate.monthlyRate': 199 });
+    assert.equal(item(c).price, 'EUR 15148');
+    // a price change shows up 1:1
+    assert.equal(item(car('p1', { 'price.currentSalesPrice': 14990 })).price, 'EUR 14990');
+    for (const value of [null, undefined, '', 0, -1, 'abc', true]) {
+      assert.equal(getAutounclePrice(value), null, `price ${JSON.stringify(value)}`);
+      assert.equal(reason(car('p2', { 'price.currentSalesPrice': value })), AutouncleExclusion.noPrice);
+    }
+  }],
+
+  ['availability: reserved / sold cars are not sendable stock', () => {
+    assert.equal(reason(car('r1', { 'offer.offerAvailability': 'selector_offerAvailability_reserved' })), AutouncleExclusion.notAvailable);
+    assert.equal(reason(car('r2', { 'offer.offerAvailability': 'selector_offerAvailability_sold' })), AutouncleExclusion.notAvailable);
+    assert.equal(mapAutouncleItem(car('r3', { 'offer.offerAvailability': 'selector_offerAvailability_available' }), ctx()).ok, true);
+  }],
+
+  ['no id / no dealer -> not sent', () => {
+    assert.equal(reason(car('', {})), AutouncleExclusion.noId);
+    assert.equal(reason(car('d1', { 'metaData.ownerId': '' })), AutouncleExclusion.noDealer);
+  }],
+
+  ['selectors: unknown / null category, fuel, gearbox -> Other/other, the key is never dropped', () => {
+    const odd = item(car('o1', { 'mainData.category': 'selector_category_pickup', 'consumption.fuel': null, 'driveSuspension.gearbox': undefined }));
+    assert.equal(odd.body, 'Other');
+    assert.equal(odd.fuel, 'Other');
+    assert.equal(odd.gear_type, 'other');
+    assert.deepEqual(Object.keys(JSON.parse(JSON.stringify(odd))), HISTORIC_KEYS);
+    const known = item(car('o2', { 'mainData.category': 'selector_category_suv', 'consumption.fuel': 'selector_fuel_hybridElectricalPetrol', 'driveSuspension.gearbox': 'selector_gearbox_semiAutomatic' }));
+    assert.deepEqual([known.body, known.fuel, known.gear_type], ['Suv', 'Hybrid', 'automatic']);
+  }],
+
+  ['units: no "ccm" without a value; km and kW as before', () => {
+    assert.equal(item(car('u1')).engine_size, '');
+    assert.equal(item(car('u2', { 'engineData.cubicCapacity': 1497 })).engine_size, '1497ccm');
+    assert.equal(item(car('u3')).mileage, '13000km');
+    assert.equal(item(car('u4', { 'mainData.mileage': 0 })).mileage, '1km');
+    assert.equal(item(car('u5')).power, '85');
+  }],
+
+  ['seller address: the dealer\'s own address, region from the postal code table', () => {
+    const a = item(car('s1'));
+    assert.equal(a.seller_city, 'Sandersdorf-Brehna');
+    assert.equal(a.seller_postcode, '06796');
+    assert.equal(a.seller_street_address, 'Max-Planck-Str. 19');
+    assert.equal(a.seller_region, 'Sachsen-Anhalt');
+    assert.equal(a.seller_name, 'auto.de');
+    assert.equal(a.seller_type, 'Dealer');
+  }],
+
+  ['getAddress: place unknown to the postal code table keeps street/city/zip (were blanked), region Deutschland', async () => {
+    const transformer = new AutouncleTransformer();
+    const unknown = await transformer.getAddress({ mainAddress: { city: 'Nirgendwo', zip: '00000', street: 'Teststr. 1', country: { name: 'Deutschland' } } });
+    assert.deepEqual(unknown, { city: 'Nirgendwo', addr1: 'Teststr. 1', region: 'Deutschland', postal_code: '00000' });
+    const known = await transformer.getAddress({ businessAddress: { city: 'Sandersdorf-Brehna', zip: '06796', street: 'Max-Planck-Str. 19', country: { name: 'Deutschland' } } });
+    assert.equal(known.city, 'Sandersdorf-Brehna');
+    assert.equal(known.postal_code, '06796');
+    assert.ok(known.region && known.region !== 'Deutschland', `region from table, got ${known.region}`);
+    assert.deepEqual(await transformer.getAddress(null), { city: '', addr1: '', region: 'Deutschland', postal_code: '' });
+  }],
+
+  ['images: [{url}] objects, clean profile order, explicit JPEG, never a placeholder', () => {
+    const clean = imagesService.getCleanImages('car-i', images('i'));
+    const urls = toAutouncleImages(selectOpenAiImageFields(clean, clean.map(i => ({ url: i.url, ok: true }))));
+    const out = item(car('car-i'), { images: urls }).images;
+    assert.deepEqual(out, [
+      { url: 'https://images.auto.de/carimage/car-i/ihero1/large-cached.jpeg' },
+      { url: 'https://images.auto.de/carimage/car-i/iside1/large-cached.jpeg' },
+      { url: 'https://images.auto.de/carimage/car-i/iback1/large-cached.jpeg' },
+      { url: 'https://images.auto.de/carimage/car-i/iint01/large-cached.jpeg' },
+    ]);
+    assert.ok(out.every(({ url }: { url: string }) => !url.includes('/noimage/')));
+  }],
+
+  ['images: no valid 3/4 hero -> [] -> car not sent; duplicates once; maxImages cuts only the list', () => {
+    const clean = imagesService.getCleanImages('car-h', images('h'));
+    const heroBroken = selectOpenAiImageFields(clean, clean.map(i => ({ url: i.url, ok: !i.heroCandidate })));
+    assert.deepEqual(toAutouncleImages(heroBroken), []);
+    assert.equal(reason(car('car-h'), { images: [] }), AutouncleExclusion.noImage);
+    // no hero shot at all
+    assert.deepEqual(imagesService.getCleanImages('car-n', images('n').filter(i => i.imageCodePredicted !== 'ext_f_right')), []);
+    // the same Imbo image twice -> once
+    const dup = [...eightImages('d'), ...eightImages('d')];
+    const dupClean = imagesService.getCleanImages('car-d', dup);
+    assert.equal(dupClean.length, 8);
+    const allOk = selectOpenAiImageFields(dupClean, dupClean.map(i => ({ url: i.url, ok: true })));
+    assert.equal(toAutouncleImages(allOk).length, 8);
+    assert.equal(toAutouncleImages(allOk, 3).length, 3);
+    assert.equal(allOk.fields.additional_image_urls.length, 7);
+  }],
+
+  ['builder: first item written once, {"ads":[...]} parses', async () => {
+    const file = join(await fs.mkdtemp(join(tmpdir(), 'autouncle-b-')), 'out.json');
+    const builder = new AutouncleJsonBuilder(file);
+    await builder.buildStart();
+    await builder.addItem(item(car('b1')), true);
+    await builder.addItem(item(car('b2')), false);
+    await builder.buildEnd();
+    const parsed = JSON.parse(await fs.readFile(file, 'utf8'));
+    assert.deepEqual(parsed.ads.map((a: any) => a.back_link.split('/vehicle/')[1].split('?')[0]), ['b1', 'b2']);
+  }],
+
+  ['config: dry-run by default (path no Cronicle step reads), live only with autouncleDryRun=false; clean images', () => {
+    const base = { environment: Environment.DEVELOP, exportType: ExportType.AUTOUNCLE };
+    const dry = new AutouncleConfig({ ...base } as any);
+    assert.equal(dry.dryRun, true);
+    assert.equal(dry.outputFiles[0], 'resources/autouncle-dryrun/api_export_cars_autouncle.json');
+    assert.equal(dry.stateDir, 'resources/autouncle-state/dryrun');
+    assert.equal(dry.imageType, ImageType.clean);
+    assert.equal(dry.maxImages, 0);
+    assert.equal(dry.feedGuard.minPublishedItems, 1);
+    assert.equal(new AutouncleConfig({ ...base, autouncleDryRun: 'no' } as any).dryRun, true);
+    const live = new AutouncleConfig({ ...base, autouncleDryRun: 'false', autouncleMaxImages: '12', feedGuardMinPublishedItems: '50' } as any);
+    assert.equal(live.dryRun, false);
+    assert.equal(live.outputFiles[0], 'resources/autouncle-export/api_export_cars_autouncle.json');
+    assert.equal(live.stateDir, 'resources/autouncle-state/export');
+    assert.equal(live.maxImages, 12);
+    assert.equal(live.feedGuard.minPublishedItems, 50);
+  }],
+];
+
+(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);
+})();