@bytebrand/export-cars 1.26.28 → 1.26.30

package/src/services/publication-gate.ts

@@ -1,119 +1,119 @@
-import { join } from 'path';
-import { get } from 'lodash';
-import { BigQueryLogger } from '@bytebrand/bigquery-logger';
-import { DataSchemes } from '@bytebrand/car-schema';
-import { PublicationGateConfig } from '../interfaces/params.interface';
-import { GoogleEnvkvAttribute, googleEnvkvSourceFields } from '../transformers/google-feed-envkv';
-
-// EnVKV stage C8 — publication gate for estimated EnVKV values in the Google feed.
-//
-// No car field says whether a value was delivered or estimated; car-basic-data writes every change it
-// makes to the enrichment audit log (BigQuery). At the start of the export the gate reads the latest
-// log row per car and field; a field counts as estimated when that row came from an estimate source
-// and its final value is still the value stored on the car (a later import with a delivered value
-// replaces it without a log row, so the stored value no longer matches).
-//
-//   off      no BigQuery call, the feed as before (default)
-//   audit    the feed as before, the estimated attributes are recorded in the feed items table
-//   enforce  estimated attributes are left out of the item (and recorded)
-
-// finalValueSource values of CBD's enrichment log that are estimates: the CO2 estimator (EEA register /
-// model), the make-model template sheet and the global defaults.
-export const ESTIMATE_SOURCES = ['co2-estimate', 'mmm', 'globalDefault'];
-
-// Every car field a Google EnVKV attribute can be taken from (google-feed-envkv picks).
-export const GATED_FIELDS = [
-  'consumption.wltpWeightedCombined',
-  'consumption.wltpCombined',
-  'consumption.consumptionCombined',
-  'consumption.wltpWeightedPowerCombined',
-  'consumption.wltpPowerCombined',
-  'consumption.consumptionPowerCombined',
-  'environmentEmissions.wltpCo2',
-  'environmentEmissions.co2',
-  'battery.wltpTotalRange',
-  'battery.wltpRange',
-  'battery.batteryRangeElectric',
-];
-
-// '7.10' and 7.1 are the same value; non-numeric values compare as strings.
-const sameValue = (logged: string, stored: unknown): boolean => {
-  if (stored === undefined || stored === null) return false;
-  const a = Number(logged);
-  const b = Number(stored);
-  if (Number.isFinite(a) && Number.isFinite(b)) return Math.abs(a - b) < 1e-9;
-  return logged === String(stored);
-};
-
-export class PublicationGate {
-  // estimates: `${carId}|${field}` -> final value of the latest estimate row
-  constructor(readonly mode: 'off' | 'audit' | 'enforce', private estimates: Map<string, string>) {}
-
-  static off(): PublicationGate {
-    return new PublicationGate('off', new Map());
-  }
-
-  get size(): number {
-    return this.estimates.size;
-  }
-
-  // The attributes of this car whose value comes from an estimated field, in a fixed order.
-  estimatedAttributes(car: DataSchemes.Car): GoogleEnvkvAttribute[] {
-    if (this.mode === 'off') return [];
-    const carId = String(get(car, '_id', ''));
-    const attributes: GoogleEnvkvAttribute[] = [];
-    for (const [attribute, field] of Object.entries(googleEnvkvSourceFields(car))) {
-      const logged = this.estimates.get(`${carId}|${field}`);
-      if (logged !== undefined && sameValue(logged, get(car, field))) attributes.push(attribute as GoogleEnvkvAttribute);
-    }
-    return attributes;
-  }
-
-  // enforce: drops the estimated attributes from the item. Returns the item for chaining.
-  apply<T extends Partial<Record<GoogleEnvkvAttribute, string>>>(item: T, attributes: GoogleEnvkvAttribute[]): T {
-    if (this.mode !== 'enforce') return item;
-    for (const attribute of attributes) delete item[attribute];
-    return item;
-  }
-}
-
-class EnrichmentLogReader extends BigQueryLogger {
-  async latestEstimates(table: string): Promise<Map<string, string>> {
-    const query = `
-      SELECT carId, fieldName, finalValue
-      FROM (
-        SELECT carId, fieldName, finalValue, finalValueSource,
-               ROW_NUMBER() OVER (PARTITION BY carId, fieldName ORDER BY timestamp DESC) AS rn
-        FROM \`${table}\`
-        WHERE fieldName IN UNNEST(@fields)
-      )
-      WHERE rn = 1 AND finalValueSource IN UNNEST(@sources) AND finalValue IS NOT NULL`;
-    const [rows] = await this.client.query({ query, params: { fields: GATED_FIELDS, sources: ESTIMATE_SOURCES } });
-    const estimates = new Map<string, string>();
-    for (const row of rows) estimates.set(`${row.carId}|${row.fieldName}`, String(row.finalValue));
-    return estimates;
-  }
-}
-
-// Reads the estimates once per run. audit: a failure only switches the gate off. enforce: a failure
-// fails the export, so the last published feed stays in place instead of a feed with unchecked estimates.
-export async function loadPublicationGate(config: PublicationGateConfig | undefined): Promise<PublicationGate> {
-  if (!config || config.mode === 'off') return PublicationGate.off();
-  const table = `${config.project}.${config.dataset}.${config.table}`;
-  try {
-    const credentials = require(join(process.cwd(), 'credentials/google-cloud-project-id.json'));
-    const reader = new EnrichmentLogReader(credentials, {
-      BigQueryProject: config.project,
-      BigQueryDataset: config.dataset,
-      BigQueryLogTable: config.table,
-    });
-    const estimates = await reader.latestEstimates(table);
-    console.log(`Publication gate ${config.mode}: ${estimates.size} estimated car fields from ${table}`);
-    return new PublicationGate(config.mode, estimates);
-  } catch (e) {
-    const message = String(e?.message || e).split('\n')[0];
-    if (config.mode === 'enforce') throw new Error(`Publication gate: cannot read ${table}: ${message}`);
-    console.error(`Publication gate disabled for this run: cannot read ${table}: ${message}`);
-    return PublicationGate.off();
-  }
-}
+import { join } from 'path';
+import { get } from 'lodash';
+import { BigQueryLogger } from '@bytebrand/bigquery-logger';
+import { DataSchemes } from '@bytebrand/car-schema';
+import { PublicationGateConfig } from '../interfaces/params.interface';
+import { GoogleEnvkvAttribute, googleEnvkvSourceFields } from '../transformers/google-feed-envkv';
+
+// EnVKV stage C8 — publication gate for estimated EnVKV values in the Google feed.
+//
+// No car field says whether a value was delivered or estimated; car-basic-data writes every change it
+// makes to the enrichment audit log (BigQuery). At the start of the export the gate reads the latest
+// log row per car and field; a field counts as estimated when that row came from an estimate source
+// and its final value is still the value stored on the car (a later import with a delivered value
+// replaces it without a log row, so the stored value no longer matches).
+//
+//   off      no BigQuery call, the feed as before (default)
+//   audit    the feed as before, the estimated attributes are recorded in the feed items table
+//   enforce  estimated attributes are left out of the item (and recorded)
+
+// finalValueSource values of CBD's enrichment log that are estimates: the CO2 estimator (EEA register /
+// model), the make-model template sheet and the global defaults.
+export const ESTIMATE_SOURCES = ['co2-estimate', 'mmm', 'globalDefault'];
+
+// Every car field a Google EnVKV attribute can be taken from (google-feed-envkv picks).
+export const GATED_FIELDS = [
+  'consumption.wltpWeightedCombined',
+  'consumption.wltpCombined',
+  'consumption.consumptionCombined',
+  'consumption.wltpWeightedPowerCombined',
+  'consumption.wltpPowerCombined',
+  'consumption.consumptionPowerCombined',
+  'environmentEmissions.wltpCo2',
+  'environmentEmissions.co2',
+  'battery.wltpTotalRange',
+  'battery.wltpRange',
+  'battery.batteryRangeElectric',
+];
+
+// '7.10' and 7.1 are the same value; non-numeric values compare as strings.
+const sameValue = (logged: string, stored: unknown): boolean => {
+  if (stored === undefined || stored === null) return false;
+  const a = Number(logged);
+  const b = Number(stored);
+  if (Number.isFinite(a) && Number.isFinite(b)) return Math.abs(a - b) < 1e-9;
+  return logged === String(stored);
+};
+
+export class PublicationGate {
+  // estimates: `${carId}|${field}` -> final value of the latest estimate row
+  constructor(readonly mode: 'off' | 'audit' | 'enforce', private estimates: Map<string, string>) {}
+
+  static off(): PublicationGate {
+    return new PublicationGate('off', new Map());
+  }
+
+  get size(): number {
+    return this.estimates.size;
+  }
+
+  // The attributes of this car whose value comes from an estimated field, in a fixed order.
+  estimatedAttributes(car: DataSchemes.Car): GoogleEnvkvAttribute[] {
+    if (this.mode === 'off') return [];
+    const carId = String(get(car, '_id', ''));
+    const attributes: GoogleEnvkvAttribute[] = [];
+    for (const [attribute, field] of Object.entries(googleEnvkvSourceFields(car))) {
+      const logged = this.estimates.get(`${carId}|${field}`);
+      if (logged !== undefined && sameValue(logged, get(car, field))) attributes.push(attribute as GoogleEnvkvAttribute);
+    }
+    return attributes;
+  }
+
+  // enforce: drops the estimated attributes from the item. Returns the item for chaining.
+  apply<T extends Partial<Record<GoogleEnvkvAttribute, string>>>(item: T, attributes: GoogleEnvkvAttribute[]): T {
+    if (this.mode !== 'enforce') return item;
+    for (const attribute of attributes) delete item[attribute];
+    return item;
+  }
+}
+
+class EnrichmentLogReader extends BigQueryLogger {
+  async latestEstimates(table: string): Promise<Map<string, string>> {
+    const query = `
+      SELECT carId, fieldName, finalValue
+      FROM (
+        SELECT carId, fieldName, finalValue, finalValueSource,
+               ROW_NUMBER() OVER (PARTITION BY carId, fieldName ORDER BY timestamp DESC) AS rn
+        FROM \`${table}\`
+        WHERE fieldName IN UNNEST(@fields)
+      )
+      WHERE rn = 1 AND finalValueSource IN UNNEST(@sources) AND finalValue IS NOT NULL`;
+    const [rows] = await this.client.query({ query, params: { fields: GATED_FIELDS, sources: ESTIMATE_SOURCES } });
+    const estimates = new Map<string, string>();
+    for (const row of rows) estimates.set(`${row.carId}|${row.fieldName}`, String(row.finalValue));
+    return estimates;
+  }
+}
+
+// Reads the estimates once per run. audit: a failure only switches the gate off. enforce: a failure
+// fails the export, so the last published feed stays in place instead of a feed with unchecked estimates.
+export async function loadPublicationGate(config: PublicationGateConfig | undefined): Promise<PublicationGate> {
+  if (!config || config.mode === 'off') return PublicationGate.off();
+  const table = `${config.project}.${config.dataset}.${config.table}`;
+  try {
+    const credentials = require(join(process.cwd(), 'credentials/google-cloud-project-id.json'));
+    const reader = new EnrichmentLogReader(credentials, {
+      BigQueryProject: config.project,
+      BigQueryDataset: config.dataset,
+      BigQueryLogTable: config.table,
+    });
+    const estimates = await reader.latestEstimates(table);
+    console.log(`Publication gate ${config.mode}: ${estimates.size} estimated car fields from ${table}`);
+    return new PublicationGate(config.mode, estimates);
+  } catch (e) {
+    const message = String(e?.message || e).split('\n')[0];
+    if (config.mode === 'enforce') throw new Error(`Publication gate: cannot read ${table}: ${message}`);
+    console.error(`Publication gate disabled for this run: cannot read ${table}: ${message}`);
+    return PublicationGate.off();
+  }
+}

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

@@ -0,0 +1,243 @@
+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 make/model values from import mapping (SONSTIGE = "other"). As `brand` the value would
+// be invented (car excluded); as model it is left out of title and description.
+const PLACEHOLDER_NAMES = /^(sonstige|sonstiges|andere|other|unknown|unbekannt)$/i;
+
+// UTF-8 text that was decoded as Latin-1 / Windows-1252 somewhere upstream ("Navi über" for
+// "Navi über", "ß" for "ß", "„" for "„"). Continuation bytes 0x80–0xBF show up as the Latin-1
+// character of the same code, or — for 0x80–0x9F — as the Windows-1252 character below.
+const CP1252_HIGH: Record<string, number> = {
+  '€': 0x80, '‚': 0x82, 'ƒ': 0x83, '„': 0x84, '…': 0x85, '†': 0x86,
+  '‡': 0x87, 'ˆ': 0x88, '‰': 0x89, 'Š': 0x8a, '‹': 0x8b, 'Œ': 0x8c,
+  'Ž': 0x8e, '‘': 0x91, '’': 0x92, '“': 0x93, '”': 0x94, '•': 0x95,
+  '–': 0x96, '—': 0x97, '˜': 0x98, '™': 0x99, 'š': 0x9a, '›': 0x9b,
+  'œ': 0x9c, 'ž': 0x9e, 'Ÿ': 0x9f,
+};
+const CONTINUATION = `[\\u0080-\\u00BF${Object.keys(CP1252_HIGH).join('')}]`;
+// a C2–C5 lead + one continuation (Latin-1 Supplement / Latin Extended-A), or E2 + two
+// (general punctuation, €)
+const MOJIBAKE_SEQUENCE = new RegExp(`[\\u00C2-\\u00C5]${CONTINUATION}|\\u00E2${CONTINUATION}{2}`, 'g');
+
+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 = repairMojibake(trim(toString(get(car, 'mainData.make', ''))));
+  if (!brand || PLACEHOLDER_NAMES.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. 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 => {
+  const [make, model, subModel] = ['mainData.make', 'mainData.model', 'mainData.subModel']
+    .map(path => repairMojibake(trim(toString(get(car, path, '')))));
+  const realModel = PLACEHOLDER_NAMES.test(model) ? '' : model;
+  if (!normalizeFeedText(`${realModel} ${subModel}`)) {
+    return '';
+  }
+  const title = normalizeFeedText([make, realModel, subModel].join(' '));
+  return truncate(title, { length: OPENAI_TITLE_MAX_LENGTH, separator: ' ', omission: '' }).trim();
+};
+
+// Repairs only sequences that decode to one character of the expected ranges (Latin-1 Supplement,
+// Latin Extended-A, general punctuation, €), so regular German text ("ä°", "ß") is never touched.
+export const repairMojibake = (text: string): string =>
+  (text || '').replace(MOJIBAKE_SEQUENCE, (sequence) => {
+    const bytes = [...sequence].map(char => CP1252_HIGH[char] ?? char.charCodeAt(0));
+    const decoded = Buffer.from(bytes).toString('utf8');
+    const code = decoded.length === 1 ? decoded.charCodeAt(0) : -1;
+    const expected = (code >= 0x00a0 && code <= 0x017f) || (code >= 0x2010 && code <= 0x20ac);
+    return expected ? decoded : sequence;
+  });
+
+// 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);
+})();

package/test/fixtures/images-service.harness.ts

@@ -0,0 +1,32 @@
+import { ImagesService } from '../../src/services/images.service';
+import { ImageType } from '../../src/enums';
+import { IMBO_FIXTURES, MARKETING_CONFIG_FIXTURE, cloneImages } from './imbo-images.fixture';
+
+export const buildImagesService = (): ImagesService => {
+  const configService: any = {
+    config: {
+      baseImageUrl: 'https://images.auto.de',
+      marketingImageUrl: 'https://images.auto.de/generated_images',
+      marketingImageConfigId: 3,
+    },
+  };
+  const userService: any = { getMarketingImageConfig: async () => MARKETING_CONFIG_FIXTURE };
+  return new ImagesService(configService, userService);
+};
+
+// Every image output the existing partner exporters consume, per fixture car. The regression test
+// compares this against images.golden.json, recorded from the pre-ADV-336 ImagesService.
+export const snapshotExistingImageOutputs = async (): Promise<Record<string, unknown>> => {
+  const service = buildImagesService();
+  const out: Record<string, unknown> = {};
+  for (const [name, { carId, images }] of Object.entries(IMBO_FIXTURES)) {
+    const car: any = { _id: carId };
+    out[name] = {
+      defaultWithPlaceholders: await service.getImages(car, cloneImages(images), ImageType.default, false),
+      defaultIgnorePlaceholders: await service.getImages(car, cloneImages(images), ImageType.default, true),
+      marketing: images.length ? await service.getImages(car, cloneImages(images), ImageType.marketing, false) : null,
+      googleExtInt: await service.getExtIntDefaultImages(car, cloneImages(images), ImageType.default, false),
+    };
+  }
+  return out;
+};