@bytebrand/export-cars 1.26.27 → 1.26.29

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

@@ -70,51 +70,99 @@ const isConfirmedPlugIn = (car: DataSchemes.Car): boolean => isPlugIn(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;
-  let value: number | undefined;
-  if (isConfirmedPlugIn(car)) {
-    value = positive(get(car, 'consumption.wltpWeightedCombined')) ?? positive(get(car, 'consumption.consumptionCombined'));
-  } else if (isPlugIn(car)) {
-    value = positive(get(car, 'consumption.consumptionCombined')); // unconfirmed plug-in: as before
-  } else {
-    // ICE / HEV: the WLTP combined value the VDP and EnVKV use (EnVKV stage D3), the legacy field as fallback
-    value = positive(get(car, 'consumption.wltpCombined')) ?? positive(get(car, 'consumption.consumptionCombined'));
-  }
-  return value ? `${value}l/100km` : undefined;
+//
+// Each attribute is picked from the first positive field of a list; the pick keeps the field so the
+// publication gate (EnVKV C8) can tell whether the sent value was estimated by CBD.
+interface Picked {
+  field: string;
+  value: number;
 }
 
+const firstPositive = (car: DataSchemes.Car, fields: string[]): Picked | undefined => {
+  for (const field of fields) {
+    const value = positive(get(car, field));
+    if (value) return { field, value };
+  }
+  return undefined;
+};
+
+const pickFuelConsumption = (car: DataSchemes.Car): Picked | undefined => {
+  if (isBev(car)) return undefined;
+  if (isConfirmedPlugIn(car)) return firstPositive(car, ['consumption.wltpWeightedCombined', 'consumption.consumptionCombined']);
+  if (isPlugIn(car)) return firstPositive(car, ['consumption.consumptionCombined']); // unconfirmed plug-in: as before
+  // ICE / HEV: the WLTP combined value the VDP and EnVKV use (EnVKV stage D3), the legacy field as fallback
+  return firstPositive(car, ['consumption.wltpCombined', 'consumption.consumptionCombined']);
+};
+
 // 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 {
+const pickFuelConsumptionDischarged = (car: DataSchemes.Car): Picked | undefined => {
   if (!isPlugIn(car)) return undefined;
-  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;
-}
+  return isConfirmedPlugIn(car)
+    ? firstPositive(car, ['consumption.wltpCombined'])
+    : firstPositive(car, ['consumption.consumptionCombined', 'consumption.wltpCombined']);
+};
 
 // BEV: combined consumption. Confirmed plug-in: weighted combined. Unconfirmed plug-in: the stored
 // electric value, as before. Nothing for other cars.
+const pickEnergyConsumption = (car: DataSchemes.Car): Picked | undefined => {
+  if (isConfirmedPlugIn(car)) return firstPositive(car, ['consumption.wltpWeightedPowerCombined']);
+  if (isBev(car) || isPlugIn(car)) return firstPositive(car, ['consumption.wltpPowerCombined', 'consumption.consumptionPowerCombined']);
+  return undefined;
+};
+
+// A BEV emits 0 g/km by definition (no field behind it); a confirmed plug-in and ICE / HEV send the
+// WLTP value (weighted for the plug-in); an unconfirmed plug-in keeps the stored legacy value, as before.
+const pickCo2 = (car: DataSchemes.Car): Picked | undefined => {
+  if (isBev(car)) return undefined;
+  return isPlugIn(car) && !isConfirmedPlugIn(car)
+    ? firstPositive(car, ['environmentEmissions.co2'])
+    : firstPositive(car, ['environmentEmissions.wltpCo2', 'environmentEmissions.co2']);
+};
+
+export function googleFuelConsumption(car: DataSchemes.Car): string | undefined {
+  const picked = pickFuelConsumption(car);
+  return picked ? `${picked.value}l/100km` : undefined;
+}
+
+export function googleFuelConsumptionDischarged(car: DataSchemes.Car): string | undefined {
+  const picked = pickFuelConsumptionDischarged(car);
+  return picked ? `${picked.value}l/100km` : undefined;
+}
+
 export function googleEnergyConsumption(car: DataSchemes.Car): string | undefined {
-  let value: number | undefined;
-  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;
+  const picked = pickEnergyConsumption(car);
+  return picked ? `${picked.value}kWh/100km` : undefined;
 }
 
-// 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.
+// A missing or 0 value is omitted.
 export function googleCo2(car: DataSchemes.Car): string | undefined {
   if (isBev(car)) return '0g/km';
-  // a confirmed plug-in and ICE / HEV send the WLTP value (weighted for the plug-in); an unconfirmed
-  // plug-in keeps the stored legacy value, as before
-  const value = isPlugIn(car) && !isConfirmedPlugIn(car)
-    ? positive(get(car, 'environmentEmissions.co2'))
-    : positive(get(car, 'environmentEmissions.wltpCo2')) ?? positive(get(car, 'environmentEmissions.co2'));
-  return value ? `${value}g/km` : undefined;
+  const picked = pickCo2(car);
+  return picked ? `${picked.value}g/km` : undefined;
+}
+
+// The EnVKV attributes of the Google item (keys of GoogleXmlItem).
+export type GoogleEnvkvAttribute =
+  | 'fuel_consumption'
+  | 'fuel_consumption_discharged_battery'
+  | 'energy_consumption'
+  | 'electric_range'
+  | 'co2_emissions';
+
+// For every EnVKV attribute the item sends: the car field its value came from.
+export function googleEnvkvSourceFields(car: DataSchemes.Car): Partial<Record<GoogleEnvkvAttribute, string>> {
+  const picks: Record<GoogleEnvkvAttribute, { field: string } | undefined> = {
+    fuel_consumption: pickFuelConsumption(car),
+    fuel_consumption_discharged_battery: pickFuelConsumptionDischarged(car),
+    energy_consumption: pickEnergyConsumption(car),
+    electric_range: pickElectricRange(car),
+    co2_emissions: pickCo2(car),
+  };
+  const fields: Partial<Record<GoogleEnvkvAttribute, string>> = {};
+  for (const [attribute, picked] of Object.entries(picks)) {
+    if (picked) fields[attribute as GoogleEnvkvAttribute] = picked.field;
+  }
+  return fields;
 }

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

@@ -1,71 +1,78 @@
-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),
-  };
-}
+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;
+  // EnVKV C8: gate mode of the run and the attributes whose value CBD estimated (comma-separated);
+  // in enforce mode these attributes were left out of the item.
+  publicationGate: string | null;
+  estimatedAttributes: 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,
+  gate: { mode: string; estimatedAttributes: string[] } | null = null,
+): 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),
+    publicationGate: gate ? gate.mode : null,
+    estimatedAttributes: gate && gate.estimatedAttributes.length ? gate.estimatedAttributes.join(',') : null,
+  };
+}

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

@@ -0,0 +1,211 @@
+import { get, toNumber, toString, trim, truncate } from 'lodash';
+import { DataSchemes } from '@bytebrand/car-schema';
+
+import { normalizeFeedText } from '../utils';
+import {
+  OpenAiAdsCondition,
+  OpenAiAdsExclusion,
+  OpenAiAdsOutOfStockReason,
+  OpenAiAdsRow,
+} from '../interfaces/openai-ads.interface';
+import { OpenAiImageFields, encodeCommasInUrl } from './openai-image-fields';
+
+// OpenAI product file limits (guidance): title ≤ 150, description ≤ 5,000 characters.
+export const OPENAI_TITLE_MAX_LENGTH = 150;
+export const OPENAI_DESCRIPTION_MAX_LENGTH = 5000;
+
+// Placeholder makes from import mapping (SONSTIGE = "other") — not a real manufacturer, so the
+// required `brand` would be invented.
+const PLACEHOLDER_MAKES = /^(sonstige|sonstiges|andere|other|unknown|unbekannt)$/i;
+
+const OFFER_AVAILABILITY_OUT_OF_STOCK: Record<string, OpenAiAdsOutOfStockReason> = {
+  selector_offerAvailability_reserved: OpenAiAdsOutOfStockReason.reserved,
+  selector_offerAvailability_sold: OpenAiAdsOutOfStockReason.soldFlag,
+};
+
+export interface OpenAiAdsMappingContext {
+  domain: string;
+  sellerName: string;
+  // German label of a schema selector (TranslatorExtended.translateVal); returns the key itself
+  // when it has no label
+  translate: (key: string) => string;
+  now: Date;
+}
+
+// Row without the media columns: mapped first so cheap exclusions happen before any image probe.
+export type OpenAiAdsBaseRow = Omit<OpenAiAdsRow, 'image_url' | 'additional_image_urls'>;
+
+export type OpenAiAdsMapResult =
+  | { ok: true; row: OpenAiAdsBaseRow; outOfStockReason?: OpenAiAdsOutOfStockReason }
+  | { ok: false; reason: OpenAiAdsExclusion };
+
+/**
+ * Maps one CBD car (an online car of the base export snapshot) to the OpenAI columns.
+ * The row comes out in_stock; `outOfStockReason` is set when the car is online but flagged
+ * reserved/sold — the exporter then sends it as out_of_stock (only if it was advertised before).
+ */
+export const mapOpenAiAdsVehicle = (car: DataSchemes.Car, ctx: OpenAiAdsMappingContext): OpenAiAdsMapResult => {
+  const itemId = toString(get(car, '_id', '')).trim();
+  if (!itemId) {
+    return { ok: false, reason: OpenAiAdsExclusion.noId };
+  }
+
+  const price = formatOpenAiPrice(get(car, 'price.currentSalesPrice', null));
+  if (!price) {
+    return { ok: false, reason: OpenAiAdsExclusion.invalidPrice };
+  }
+
+  const brand = trim(toString(get(car, 'mainData.make', '')));
+  if (!brand || PLACEHOLDER_MAKES.test(brand)) {
+    return { ok: false, reason: OpenAiAdsExclusion.noBrand };
+  }
+
+  const title = buildOpenAiTitle(car);
+  if (!title) {
+    return { ok: false, reason: OpenAiAdsExclusion.noTitle };
+  }
+
+  const condition = resolveOpenAiCondition(car, ctx.now);
+  if (!condition) {
+    return { ok: false, reason: OpenAiAdsExclusion.conditionUnknown };
+  }
+
+  const row: OpenAiAdsBaseRow = {
+    item_id: itemId,
+    title,
+    description: buildOpenAiDescription(car, title, condition, ctx),
+    url: `https://www.${ctx.domain}/search/vehicle/${itemId}`,
+    brand,
+    seller_name: ctx.sellerName,
+    availability: 'in_stock',
+    price,
+    condition,
+    is_ads_eligible: true,
+  };
+
+  const outOfStockReason = OFFER_AVAILABILITY_OUT_OF_STOCK[toString(get(car, 'offer.offerAvailability', ''))];
+  return outOfStockReason ? { ok: true, row, outOfStockReason } : { ok: true, row };
+};
+
+export const withOpenAiImages = (row: OpenAiAdsBaseRow, images: OpenAiImageFields): OpenAiAdsRow => ({
+  ...row,
+  image_url: images.image_url,
+  // the CSV writer quotes the cell; commas inside a URL are %2C so the list stays parseable
+  additional_image_urls: images.additional_image_urls.map(encodeCommasInUrl).join(','),
+});
+
+// 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,
+  availability: 'out_of_stock',
+  is_ads_eligible: false,
+});
+
+// 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.
+export const formatOpenAiPrice = (value: unknown): string | null => {
+  if (value === null || value === undefined || value === '' || typeof value === 'boolean') {
+    return null;
+  }
+  const amount = toNumber(value);
+  if (!Number.isFinite(amount) || amount <= 0) {
+    return null;
+  }
+  return `${amount.toFixed(2)} EUR`;
+};
+
+// Integer minor units (cents) for the deferred delta API: 17990.5 -> 1799050.
+export const toOpenAiMinorUnits = (value: unknown): number | null => {
+  const formatted = formatOpenAiPrice(value);
+  return formatted ? Math.round(toNumber(formatted.split(' ')[0]) * 100) : 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.
+export const buildOpenAiTitle = (car: DataSchemes.Car): string => {
+  const parts = ['mainData.make', 'mainData.model', 'mainData.subModel'].map(path => toString(get(car, path, '')));
+  const title = normalizeFeedText(parts.join(' '));
+  return truncate(title, { length: OPENAI_TITLE_MAX_LENGTH, separator: ' ', omission: '' }).trim();
+};
+
+// new/used from mainData.condition. selector_unknown is only "used" when the car has a first
+// registration in the past (a registered car is used for advertising purposes); otherwise
+// the car is excluded rather than defaulted — OpenAI treats an omitted condition as "new".
+export const resolveOpenAiCondition = (car: DataSchemes.Car, now: Date): OpenAiAdsCondition | null => {
+  const condition = toString(get(car, 'mainData.condition', ''));
+  if (condition === 'selector_condition_new') {
+    return 'new';
+  }
+  if (condition === 'selector_condition_used') {
+    return 'used';
+  }
+  const firstRegistration = toNumber(get(car, 'mainData.firstRegistration', 0));
+  return firstRegistration > 0 && firstRegistration * 1000 <= now.getTime() ? 'used' : null;
+};
+
+/**
+ * Plain German text from structured vehicle data only. Dealer summary templates (Google feed) are
+ * not used: their content is free text we cannot check for finance claims. No rates, no prices,
+ * no marketing promises.
+ * e.g. "Gebrauchtwagen: VW Golf 1.5 TSI Life. Erstzulassung: 03/2021 · Kilometerstand: 45.000 km · …"
+ */
+export const buildOpenAiDescription = (
+  car: DataSchemes.Car,
+  title: string,
+  condition: OpenAiAdsCondition,
+  ctx: OpenAiAdsMappingContext,
+): string => {
+  const label = (path: string): string | null => {
+    const key = toString(get(car, path, ''));
+    if (!key || key === 'selector_unknown') {
+      return null;
+    }
+    const value = trim(ctx.translate(key));
+    return value && !value.startsWith('selector_') && value !== 'Unbekannt' ? value : null;
+  };
+
+  const facts: Array<[string, string | null]> = [
+    ['Erstzulassung', formatFirstRegistration(get(car, 'mainData.firstRegistration'))],
+    ['Kilometerstand', formatMileage(get(car, 'mainData.mileage'))],
+    ['Kraftstoff', label('consumption.fuel')],
+    ['Getriebe', label('driveSuspension.gearbox')],
+    ['Leistung', formatPower(get(car, 'engineData.powerKW'), get(car, 'engineData.powerPS'))],
+    ['Karosserie', label('mainData.category')],
+    ['Außenfarbe', label('exterior.exteriorColor')],
+  ];
+
+  const intro = `${condition === 'new' ? 'Neuwagen' : 'Gebrauchtwagen'}: ${title}.`;
+  const details = facts.filter(([, value]) => value).map(([name, value]) => `${name}: ${value}`).join(' · ');
+  const text = (details ? `${intro} ${details}` : intro).replace(/\s+/g, ' ').trim();
+  return truncate(text, { length: OPENAI_DESCRIPTION_MAX_LENGTH, separator: ' ', omission: '' }).trim();
+};
+
+const DE_NUMBER = new Intl.NumberFormat('de-DE', { maximumFractionDigits: 0 });
+
+const formatFirstRegistration = (value: unknown): string | null => {
+  const seconds = toNumber(value);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    return null;
+  }
+  const date = new Date(seconds * 1000);
+  return `${String(date.getUTCMonth() + 1).padStart(2, '0')}/${date.getUTCFullYear()}`;
+};
+
+// Real odometer value — no 901/1001 km floors as in the Meta/Google feeds.
+const formatMileage = (value: unknown): string | null => {
+  const km = toNumber(value);
+  return Number.isFinite(km) && km > 0 ? `${DE_NUMBER.format(km)} km` : null;
+};
+
+const formatPower = (kw: unknown, ps: unknown): string | null => {
+  const powerKw = toNumber(kw);
+  if (!Number.isFinite(powerKw) || powerKw <= 0) {
+    return null;
+  }
+  const powerPs = toNumber(ps);
+  const psPart = Number.isFinite(powerPs) && powerPs > 0 ? ` (${DE_NUMBER.format(powerPs)} PS)` : '';
+  return `${DE_NUMBER.format(powerKw)} kW${psPart}`;
+};

package/src/transformers/openai-image-fields.ts

@@ -0,0 +1,60 @@
+import { CleanImage } from '../services/images.service';
+import { ImageUrlCheck, ImageUrlValidator } from '../services/image-url-validator.service';
+
+// OpenAI product file (Stable schema) media fields. Not the Google-compatible image_link /
+// additional_image_link pair — the two feed formats must not be mixed.
+export interface OpenAiImageFields {
+  image_url: string;
+  additional_image_urls: string[];
+}
+
+export interface OpenAiImageSelection {
+  fields: OpenAiImageFields | null;
+  // every clean image that failed validation, for the run log / reject tracking
+  rejected: ImageUrlCheck[];
+}
+
+/**
+ * image_url = first valid 3/4 exterior hero candidate; additional_image_urls = every other valid
+ * image in clean-profile order (exterior before interior), without an artificial count limit —
+ * OpenAI states none. Invalid optional URLs are dropped. No valid hero => fields null: the car must
+ * be skipped and counted, never sent with a placeholder or a non-hero view as its main image.
+ */
+export const selectOpenAiImageFields = (images: CleanImage[], checks: ImageUrlCheck[]): OpenAiImageSelection => {
+  const byUrl = new Map(checks.map(check => [check.url, check]));
+  const isValid = (image: CleanImage) => byUrl.get(image.url)?.ok === true;
+  const rejected = images.map(image => byUrl.get(image.url)).filter(check => check && !check.ok);
+
+  const hero = images.find(image => image.heroCandidate && isValid(image));
+  if (!hero) {
+    return { fields: null, rejected };
+  }
+
+  return {
+    fields: {
+      image_url: hero.url,
+      additional_image_urls: images.filter(image => image !== hero && isValid(image)).map(image => image.url),
+    },
+    rejected,
+  };
+};
+
+export const resolveOpenAiImageFields = async (
+  images: CleanImage[],
+  validator: ImageUrlValidator,
+): Promise<OpenAiImageSelection> => {
+  const checks = await validator.validateAll(images.map(image => image.url));
+  return selectOpenAiImageFields(images, checks);
+};
+
+// Percent-encode commas inside a URL (spec: "Percent-encode commas inside a URL as %2C").
+export const encodeCommasInUrl = (url: string): string => url.replace(/,/g, '%2C');
+
+// additional_image_urls as ONE CSV cell: comma-separated (no spaces, no semicolons), commas inside
+// URLs encoded, quoted for the CSV writer. JSONL keeps the plain array instead.
+export const serializeAdditionalImageUrlsForCsv = (urls: string[]): string =>
+  quoteCsvCell(urls.map(encodeCommasInUrl).join(','));
+
+export const serializeAdditionalImageUrlsForJsonl = (urls: string[]): string[] => urls.map(encodeCommasInUrl);
+
+export const quoteCsvCell = (value: string): string => `"${value.replace(/"/g, '""')}"`;

package/test/clean-images.test.ts

@@ -0,0 +1,86 @@
+// Run: npm test (ts-node, no test framework needed)
+import * as assert from 'node:assert/strict';
+import { ImageType } from '../src/enums';
+import { buildImagesService } from './fixtures/images-service.harness';
+import { IMBO_FIXTURES, cloneImages } from './fixtures/imbo-images.fixture';
+
+const service = buildImagesService();
+const clean = (name: string) => {
+  const { carId, images } = IMBO_FIXTURES[name];
+  return service.getCleanImages(carId, cloneImages(images));
+};
+const ids = (name: string) => clean(name).map(i => i.imageIdentifier);
+
+const cases: Array<[string, () => void | Promise<void>]> = [
+  ['3/4 exterior hero first, then exterior, then interior; feat/conext/unknown dropped', () => {
+    assert.deepEqual(ids('full'), [
+      'extRight0001', // ext_f_right (hero)
+      'extCowl00001', 'extLeft00001', 'extSide00001', 'extBack00001', 'extOpened001',
+      'intDash00001', 'intSeats0001', 'intTrunk0001',
+    ]);
+  }],
+  ['explicit JPEG variant on the images host, never a placeholder', () => {
+    const urls = clean('full').map(i => i.url);
+    assert.equal(urls[0], 'https://images.auto.de/carimage/2ce1d71f-851f-4123-ae16-187ddd7923c5/extRight0001/large-cached.jpeg');
+    assert.ok(urls.every(u => u.endsWith('/large-cached.jpeg')));
+    assert.ok(urls.every(u => !u.includes('/noimage/')));
+  }],
+  ['hero candidates are only the 3/4 front views', () => {
+    assert.deepEqual(clean('full').filter(i => i.heroCandidate).map(i => i.imageCode), ['ext_f_right', 'ext_f_left']);
+  }],
+  ['no ext_f_right: ext_f_left becomes the hero', () => {
+    assert.deepEqual(ids('leftOnly'), ['extLeft00002', 'extBack00002', 'intDash00002']);
+  }],
+  ['ext_f_left is lifted above ext_f_cowl when it is the hero', () => {
+    const images = [
+      { imageIdentifier: 'cowl', imageCodePredicted: 'ext_f_cowl' },
+      { imageIdentifier: 'left', imageCodePredicted: 'ext_f_left' },
+    ];
+    assert.deepEqual(service.getCleanImages('car', images).map(i => i.imageIdentifier), ['left', 'cowl']);
+  }],
+  ['no 3/4 exterior shot: no images at all (car is skipped, no fallback hero)', () => {
+    assert.deepEqual(clean('noHero'), []);
+    assert.deepEqual(clean('onlyUnknown'), []);
+    assert.deepEqual(clean('empty'), []);
+    assert.deepEqual(service.getCleanImages('car', undefined), []);
+  }],
+  ['repeated imageIdentifier appears once; distinct shots with the same code keep Imbo order', () => {
+    assert.deepEqual(ids('duplicates'), ['extRight0004', 'extRight0005', 'intDash00004']);
+  }],
+  ['images without imageCodePredicted or imageIdentifier are ignored', () => {
+    const images: any[] = [
+      { imageIdentifier: 'noCode' },
+      { imageCodePredicted: 'ext_f_right' },
+      { imageIdentifier: 'right', imageCodePredicted: 'ext_f_right' },
+    ];
+    assert.deepEqual(service.getCleanImages('car', images).map(i => i.imageIdentifier), ['right']);
+  }],
+  ['deterministic and does not reorder the caller\'s image list', () => {
+    const images = cloneImages(IMBO_FIXTURES.full.images);
+    const before = images.map(i => i.imageIdentifier);
+    const first = service.getCleanImages('car', images);
+    assert.deepEqual(images.map(i => i.imageIdentifier), before);
+    assert.deepEqual(service.getCleanImages('car', images), first);
+  }],
+  ['ImageType.clean via getImages: same URLs, no placeholders even with ignoreDefImages=false', async () => {
+    const { carId, images } = IMBO_FIXTURES.leftOnly;
+    const urls = await service.getImages({ _id: carId } as any, cloneImages(images), ImageType.clean, false);
+    assert.deepEqual(urls, service.getCleanImageUrls(carId, cloneImages(images)));
+    assert.equal(urls.length, 3);
+    assert.deepEqual(await service.getImages({ _id: 'x' } as any, [], ImageType.clean, false), []);
+  }],
+];
+
+(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.message}`);
+    }
+  }
+  if (failed) process.exit(1);
+})();