@bytebrand/export-cars 1.26.28 → 1.26.30

package/docs/openai-ads/AUDIT.md

@@ -0,0 +1,235 @@
+# ADV-335 — OpenAI Ads vehicle product feed: codebase audit + field mapping
+
+Status: audit 2026-10-09; first implementation 2026-10-12 on branch `feat/adv-335-openai-ads-feed` (stacked on
+`feat/adv-336-openai-images`), see §7. Nothing uploaded, no Cronicle/Cloudflare/server change, not published.
+Owner of this pass: Volodymyr. Review: Viktoriia. Sibling tickets: ADV-336 (image_url), ADV-337 (tracking `contents[].id`).
+
+Paths are repo-relative. `export-cars` = `cronicle/cronicle-plugins/packages/export-cars`.
+
+---
+
+## 0. Base branch — read this first
+
+| Branch | export-cars version | Has |
+|---|---|---|
+| `origin/deploy_prod` (a189de13, 06.10) | 1.26.19 | no test runner |
+| `origin/deploy_develop` (4221698b, 09.10) | **1.26.28** | `npm test` (ts-node), `publication-gate.ts`, `feed-items-bigquery.writer.ts`, EnVKV helpers |
+| `origin/autobahn` (ec9f115d, 17.09) | 1.26.21 | stale |
+
+npm has one version stream. The OpenAI exporter must be built on `deploy_develop` (next version 1.26.29), otherwise a publish
+silently reverts the EnVKV/Google work (same failure mode as the 1.26.10 AIA-image incident). Line numbers below refer to
+`deploy_develop` unless stated.
+
+---
+
+## 1. Official OpenAI specs (read 2026-10-09)
+
+Sources: developers.openai.com/commerce/specs/file-upload/products, developers.openai.com/ads/product-feeds,
+help.openai.com/en/articles/20001268. The products page shows **no Stable/Draft label** on 09.10; it has two profiles:
+"OpenAI format" and "Google-compatible" (the latter only after OpenAI confirms it for the registered feed).
+
+Facts that drive the design:
+
+- Required per row (OpenAI format): `item_id, title (≤150), description (≤5000, plain text), url, brand, seller_name, image_url, availability, price`.
+- `availability` ∈ `in_stock | out_of_stock | pre_order | backorder | unknown`; empty/unknown value **rejects the row**.
+- `price` = `"<amount> <ISO4217>"`, major units, decimal point, no thousands separator → `17990.00 EUR`.
+- `condition` ∈ `new | refurbished | used`; **omitted may be treated as `new`** → must always be sent for used cars.
+- `is_ads_eligible`: Ads Manager feeds are ads-eligible by default unless a row says `false`.
+- `additional_image_urls`: CSV = one quoted comma-separated cell, commas inside URLs as `%2C`.
+- `ads_metadata`: object of strings, keys must match the Ads integration setup ("don't invent them"); JSON-serialised in a CSV cell.
+- `gtin` / `mpn`: optional, never invent. No VIN column exists.
+- CSV: UTF-8, header row, quote cells with comma/quote/newline, double embedded quotes. Placeholder strings (`null`, `n/a`) forbidden.
+- **Markets: "Standard uploads use `["US"]` regardless"; `target_countries` shared format currently `US, CA, MX`; `store_country` = `US`.**
+  Campaign geo targeting is country-level. → **DE/EUR is not supported by the documented standard path. Gate = BLOCKED until OpenAI confirms in writing.**
+- Import: Ads Manager "Upload CSV or TXT" / "Hosted URL" (stable HTTPS) / "SFTP". **Items expire after 2 weeks.**
+- SFTP (developer guide): files in SFTP **root** only (`invalid_sftp_directory_layout` otherwise); password or `ssh_key`;
+  transfer success ≠ processed; one product once across all files. Atomic-upload behaviour not documented.
+- Sold/removed: send `availability=out_of_stock` (full upload or delta). Docs do **not** say that omitting a row removes it.
+- Delta: `PATCH https://api.ads.openai.com/v1/feeds/{feed_id}/products`, Advertiser API key (Bearer, account-scoped),
+  price as `{"amount": 1799000, "currency": "EUR"}` (minor units), availability `{"status": "out_of_stock"}`.
+- Monitoring API: `GET /v1/feeds/uploads` (`status`, `rows_accepted`, `rows_rejected`, `rows_ads_eligible`, `diagnostics[]`),
+  `GET /v1/feeds?include[]=product_count`. Needs API access — otherwise Upload History in the UI only.
+- Crawlers: OAI-AdsBot must reach the landing page (VDP), OAI-SearchBot must reach catalog images.
+
+---
+
+## 2. Current code paths (what runs today)
+
+### 2.1 Chain
+
+```
+Cronicle "1.0 Base export"  (base-cars-export)                 daily, prod ~16:00
+  └─ src/index.ts:20      emptyDir(resources/cars-export)        <- wiped BEFORE fetch
+  └─ CarBasicDataCarsLoader (libs/packages/chunkable/src/chunkable/loader/CarBasicDataCarsLoader.ts:47-73)
+       GET car-basic-data /api/v1/car?limit&offset  (5 retries) -> CBD CarService.getCars: query {'state.isOnline': true}
+       per car: image-imbo getCleanedCarImages (only images with image_code_predicted; error -> [] silently)
+       writes resources/cars-export/cars.{n}.json = [{car, images}]   (page 400)
+  └─ chained exports (export-cars, one Cronicle event per exportType)
+       src/export.command.ts:43-46   exportSchema[params.exportType] -> config + exporter
+       LoaderService -> FsCarsLoader (reads cars.*.json; empty dir = 0 cars, NOT an error)
+       Exporter: ensureDir + emptyDir(output dir) -> filterCar -> transformer -> builder
+  └─ "part 2" upload / nginx `feeds` site on ftp.auto.de (server-side, not in repo)
+       https://ftp.auto.de/feeds/api_export_cars_{fb,facebookshop}.xml  (nginx alias to /opt/cronicle/resources/*-export)
+```
+
+### 2.2 Source of truth per concept
+
+| Concept | Where | Notes |
+|---|---|---|
+| Inventory included | CBD `state.isOnline === true` (`services/car-basic-data/src/services/car/CarService.ts:110-113`) | only filter of the base export |
+| Forced offline | `CarService.calculateIsOnline` (`:1271-1297`): blacklisted dealer, mileage > 80k, price < min, damaged, EZ > 5 y | skipped when validation disabled |
+| Sold (CRM) | odoo-sync `updateCarOnWon` → `isOnline:false`, `offer.offerSource=selector_offerSource_won`; lost → online again | `services/odoo-sync/src/leads/car.service.ts:73-134` |
+| Reserved / sold flag on an online car | `offer.offerAvailability` ∈ `_reserved, _sold, _arrived, _inPreparation, _new, unknown` | display-only today, no filter anywhere |
+| Deleted | `CarService.deleteCar` hard-deletes from `cars`, copies to car archive | disappears from base export |
+| Dealer permission | none at export time; CBD offlines blacklisted dealers' cars; UPA profile has `active`, `blacklist` (`libs/packages/autode-request/src/interfaces/DealerProfileInterface.ts:27-28`) | `CarService.getOwner` exists (cached, retried) |
+| Price | `price.currentSalesPrice` (EUR gross, number) | Google/Meta cap 80k via `maxCurrentSalesPrice` (`car.service.ts` filterCar) |
+| Monthly rate | `rate.*`, `leasing.*`, fe-financing | **must never reach `price`** |
+| Canonical ID | `car._id` (UUID, VDP id). ADV-200 made fb/facebookshop use it; GA4 `item_id = car._id` (`services/fe-main/source/services/GoogleTagManager.ts:195-221`) | short `metaData.vehicleId` is a different id |
+| VDP URL | fe-main route `/search/vehicle/:vehicleID` (`services/fe-main/source/AppRouter.tsx:54`); public CBD GET returns 404 for offline cars | builders inconsistent: `www.` in google/fb, none in facebook-shop/`TransformerService.link` |
+| Photos | `ImagesService.generateImageLinks` → `https://images.auto.de/carimage/{_id}/{imageIdentifier}/{large|small}` (`images.service.ts:172-175`), no HEAD check | Google uses `small`; sort order `IMAGES_SORT_ORDER` |
+| Marketing images | Meta AIA `https://images.auto.de/generated_images/{a}/{b}/{c}/{_id}/meta-aia-financing-{imageId}.jpg`, HEAD-checked (`images.service.ts:220-259`) | **carries a financing overlay → not usable for OpenAI without approval** |
+
+### 2.3 Existing exporters used as reference
+
+| | Google (`google.transformer.ts`) | Meta AMA (`facebook-shop.transformer.ts`) | Meta AIA (`fb.transformer.ts`) |
+|---|---|---|---|
+| id | `car._id` | `car._id` (ADV-200) | `car._id` (ADV-200) |
+| title | brand(+Mercedes→"Mercedes", VW→"VW") model year subModel, `lodash.escape`, 100 chars | finance offer text ("… finanzieren – z. B. ab … €/Monat") | year make model subModel, `normalizeFeedText` |
+| price | `` `${round(p,2)} EUR` `` → `17990 EUR` (no `.00`) | same | `` `${p} EUR` `` |
+| availability | hardcoded `in_stock` | `state.isOnline` → always AVAILABLE (only online cars in source) | same |
+| condition | new/used, unknown→Used | — | unknown→Used |
+| VIN | `metaData.vin` else **`marketing.fakeVIN`** | — | same |
+| description | dealer summary template via `car-description` (HTML `<p>`) | offer text | structured blocks |
+| image | real photos (`small`) | Meta AIA overlay | Meta AIA overlay |
+| price cap | 80k | 80k | 80k |
+
+### 2.4 CSV builders (asked to be reused) — do not reuse
+
+- `formats/awin-csv.builder.ts:7-9` joins values with `","` **without escaping** embedded `"` or newlines.
+- `formats/santander-csv.builder.ts:7-17` uses `;`, quotes only when a comma occurs, escapes quotes only then.
+- `utils/converter.utils.ts` `convertToCSV` uses `;`.
+Neither is RFC 4180. OpenAI needs a new, small, tested writer (always quote, double `"`, keep `\n` inside quotes, UTF-8 without BOM — BOM to be confirmed).
+
+### 2.5 Guards that do NOT exist (all exporters)
+
+- base export empties `resources/cars-export` first; on CBD outage the dir is empty/partial and downstream exports
+  write an empty feed (24.09 incident: 169-byte Google feed fetched by Google at 14:00).
+- `FsCarsLoader`: empty dir = success with 0 cars.
+- `CarBasicDataCarsLoader`: malformed page (`pagination` missing) ends the run as success.
+- every exporter `emptyDir`s its output dir before writing (non-atomic), no count threshold, no last-good, no lock,
+  no freshness metadata. No SFTP client anywhere (`basic-ftp` only, no temp-name/rename).
+
+---
+
+## 3. Field mapping: source → OpenAI (OpenAI format, CSV)
+
+Null policy "EXCLUDE" = row not written + counted in the run report under the reason code.
+
+| OpenAI field | Req. | Source path | Transform / format | Null / invalid policy | Test case |
+|---|---|---|---|---|---|
+| `item_id` | R | `car._id` | string as-is (UUID) | missing → EXCLUDE `no_id`; duplicate in run → keep first, count `duplicate_id` | dup id; id equals GA4 `item_id` |
+| `title` | R | `mainData.make`, `mainData.model`, `mainData.subModel` | `normalizeFeedText(make model subModel)`, German as delivered, ≤150 at word boundary, no HTML escape; placeholder model `SONSTIGE` left out; UTF-8-read-as-Latin-1/cp1252 (`ü`) repaired (1.26.30) | neither a real model nor a variant → EXCLUDE `no_title` | umlauts, `*AHK*Leder*`, `&`, 200-char subModel |
+| `description` | R | structured fields only — NOT the dealer summary templates of the Google feed (free text, finance claims unverifiable, Q6) | `Gebrauchtwagen: <title>. Erstzulassung: 03/2021 · Kilometerstand: 45.000 km · Kraftstoff: Benzin · Getriebe: Manuell · Leistung: 110 kW (150 PS) · Karosserie · Außenfarbe`, ≤5000, real mileage (no 901/1001 floors) | facts without a German label are left out | sparse car, no `selector_*` leaks |
+| `url` | R | `car._id` | `https://www.{domain}/search/vehicle/{_id}` (same as Google/fb; no UTM — tracking via ADV-337) | always set | url host per env |
+| `brand` | R | `mainData.make` | raw manufacturer name (NOT Google's "Mercedes"/"VW" rewrite) | empty → EXCLUDE | Mercedes-Benz stays Mercedes-Benz |
+| `seller_name` | R | config (Q3) | default `auto.de` (or legal `auto.de Handels GmbH`); option dealer name from UPA | never empty | — |
+| `image_url` | R | ADV-336 clean profile: `https://images.auto.de/carimage/{_id}/{imageIdentifier}/large-cached.jpeg` (explicit JPEG; bare `/large` may negotiate WebP) | 3/4 hero (`ext_f_right`, else `ext_f_left`), every URL HEAD-checked (200 + jpeg/png) | no valid 3/4 hero → EXCLUDE `no_image` (no placeholders) | broken hero, interior-only car |
+| `availability` | R | `state.isOnline` (= in source), `offer.offerAvailability`, ledger of previously sent ids | in source + not reserved/sold → `in_stock`; in source + `_reserved`/`_sold` → `out_of_stock`; sent before but missing now → `out_of_stock` for the retention window (≥14 days) | never `unknown`, never empty | sold, reserved, deleted, reinstated |
+| `price` | R | `price.currentSalesPrice` | `toFixed(2) + ' EUR'` → `17990.00 EUR`; never `rate.*`/`leasing.*` | not finite or ≤0 → EXCLUDE `invalid_price` (out_of_stock rows reuse the last sent price) | 0, null, "17990", 17990.5 |
+| `condition` | O (send always) | `mainData.condition` | `selector_condition_new`→`new`, `_used`→`used`; unknown → `used` only with a past first registration | else EXCLUDE `condition_unknown` (Q5 still open) | unknown condition |
+| `is_ads_eligible` | C | computed | `true` for `in_stock`, `false` for `out_of_stock` | — | — |
+| `additional_image_urls` | O | ADV-336: all other valid ext + int photos, no count limit | comma-joined in one cell, `,`→`%2C` inside URL | empty cell when none | 0/1/15 photos |
+| `ads_metadata` | O | only keys configured in Ads Manager (Q7), e.g. `make`, `model`, `body_type`, `price_band` | JSON object of strings in one cell | off by default (job param) | JSON quoting in CSV |
+| `product_category` | O | constant | e.g. `Fahrzeuge > Pkw > Gebrauchtwagen` (Q8, may be omitted) | — | — |
+| `color` | O | `exterior.exteriorColor` | not a column in v1 (colour is in the description) | — | — |
+| `gtin`, `mpn`, VIN, `sale_price`, shipping, returns, reviews, `group_id`, `target_countries`, `store_country` | — | — | **not sent** (no `fakeVIN`, no invented ids; markets via account setup) | — | header contains none of them |
+
+Delta (deferred, only with API access): `products[].id = item_id`, price `{"amount": round(currentSalesPrice*100), "currency":"EUR"}`.
+
+Filters before mapping (all reasons counted in the run report):
+`imagesCount > 0` (existing `filterCar`), price valid, optional price cap (Q9), dealer `active && !blacklist` via `CarService.getOwner` (cached per dealer, failure → EXCLUDE `dealer_unknown`), title/brand/image present.
+
+---
+
+## 4. Gaps vs. ticket requirements
+
+| Requirement | Today | Needed |
+|---|---|---|
+| explicit `out_of_stock` for sold/removed | source only has online cars; sold/deleted cars vanish | ledger of sent `item_id`s (+ last row) kept in the job's state dir; missing ids re-emitted as `out_of_stock` for N days, reinstated id → `in_stock` with same id |
+| reserved | `offer.offerAvailability` ignored everywhere | map `_reserved`/`_sold` → `out_of_stock` (decision Q4) |
+| fail-closed | none | shared guard: source freshness (max age of `cars.*.json`), source count vs last-good (max drop %), absolute minimum, write to temp + rename, keep last-good, run report JSON |
+| CSV correctness | Awin/Santander writers not RFC 4180 | new writer + tests |
+| transport | nginx `feeds` site (server, not in repo) serves 2 Meta XMLs; no SFTP | hosted: add one `location =` for the CSV (server change, approval) or SFTP: new dep `ssh2-sftp-client`, root upload, key from secret store |
+| monitoring | stdout counters only | run report (counts per availability/exclusion reason, duplicates, max price, freshness) + optional BQ rows via existing writer pattern; upload status only with API access |
+| dry-run | n/a | `openAiAdsDryRun` (default `true`): file written, nothing published |
+
+---
+
+## 5. Blockers / open questions (owner)
+
+| # | Question | Owner | Blocks |
+|---|---|---|---|
+| Q1 | **DE market + EUR**: docs say standard uploads are US-only (`target_countries` US/CA/MX). Written confirmation that the auto.de account can run DE/EUR feed campaigns. | Marketing → OpenAI | go-live (BLOCKED) |
+| Q2 | Used-car / automotive inventory allowed in the account (docs mention retail only)? | Marketing → OpenAI | go-live (BLOCKED) |
+| Q3 | `seller_name`: `auto.de`, `auto.de Handels GmbH` or the dealer? Who is the contractual seller in checkout? | Marketing/Legal | first test file |
+| Q4 | `reserved` (and `sold` flag on still-online cars) → `out_of_stock`? | PM | availability logic |
+| Q5 | `condition` unknown: send `used` (as Google/Meta do) or exclude? | PM | mapping |
+| Q6 | Description: reuse dealer summary templates (same as Google) — do they contain finance claims? Or plain generated German text only? | PM/Legal | description |
+| Q7 | `ads_metadata` keys configured in Ads Manager (if any) | Marketing | optional |
+| Q8 | `product_category` wanted? | Marketing | optional |
+| Q9 | Apply the 80k price cap of Google/Meta? | Marketing | filter |
+| Q10 | Import method available in the account: hosted URL (needs fetch IP/auth info) or SFTP (credentials into secret store); API access (delta, upload status)? | Marketing | transport |
+| Q11 | OAI-AdsBot / OAI-SearchBot reachability of `www.auto.de` VDP and `images.auto.de` behind Cloudflare (js_challenge rules from ADV-193). Test only, no CF change without approval. | Eng + approval | go-live |
+| Q12 | Image: ADV-336 clean profile is used (no overlay). Approval of plain photos + `ext_lr_main` question open in ADV-336 | ADV-336 | image_url |
+| Q13 | Is a "Stable" vs "Draft" schema selector visible in your docs/account? The public page shows none on 09.10. | Marketing | — |
+
+---
+
+## 6. Proposed implementation (after OK on this audit)
+
+Branch `feat/adv-335-openai-ads-feed` from `origin/deploy_develop`, export-cars 1.26.29. All new files, existing exporters untouched
+except one enum value + one `export.schema.ts` entry.
+
+- `src/enums/export-type.enum.ts`: `OPENAI_ADS = 'openai_ads'`
+- `src/configs/openai-ads.config.ts`: output `resources/openai_ads-export/api_export_cars_openai_ads.csv`, state dir, guard thresholds, dry-run flag
+- `src/transformers/openai-ads.transformer.ts`: pure mapping functions (testable without Nest)
+- `src/formats/openai-ads-csv.builder.ts`: RFC 4180 writer, fixed header
+- `src/services/feed-guard.ts` (shared, opt-in): freshness, min count, max drop vs last-good, temp+rename, last-good copy, run report
+- `src/services/openai-ads-ledger.ts`: sent-id ledger, out_of_stock retention, reinstatement
+- `src/exporters/openai-ads.exporter.ts`
+- `test/openai-ads-*.test.ts`: escaping/umlauts, price format, condition, availability (sold/reserved/deleted/reinstated), duplicate id, missing image, guard (outage, partial source, legit drop, recovery)
+- `docs/openai-ads/RUNBOOK.md`
+- Transport (SFTP or hosted) in a separate step after Q10. Delta PATCH deferred.
+
+Remaining human steps (not engineering): Q1–Q13 answers, Cronicle event creation (dev first, dry-run), nginx/SFTP setup on prod Cronicle,
+first manual test upload of 20 cars in Ads Manager, Upload History reconciliation.
+
+---
+
+## 7. Implementation state (2026-10-12)
+
+Branch `feat/adv-335-openai-ads-feed`, stacked on `feat/adv-336-openai-images` (ADV-336 library fdc1d5aa, itself
+based on `deploy_develop`). Local only: not pushed, not published. The export-cars version bump and the publish
+belong to ADV-335 only (one bump for both tickets).
+
+Done: `ExportType.OPENAI_ADS`, `OpenAiAdsConfig` (dry-run by default), mapping (§3), RFC 4180 writer, shared
+`FeedGuard` (source empty/partial/stale, minimums, max drop vs last good, temp + rename, `.prev`, lock), ledger
+for out_of_stock (items sent before that are sold/offline/deleted/now excluded, or online but reserved/sold-flag;
+retention 15 days; reinstatement keeps the id), run report, `RUNBOOK.md`, 23 tests (`npm test`).
+
+Open questions decided in code for now (each reversible by a param or a one-line change):
+Q3 `seller_name` = `auto.de` (param); Q4 reserved/sold flag → out_of_stock, and never advertised when not sent before;
+Q5 unknown condition → `used` only with a past first registration; Q6 description from structured data only;
+Q9 no price cap unless `maxCurrentSalesPrice` is set; Q7/Q8 `ads_metadata` / `product_category` not sent.
+
+Found while running the compiled job (`node dist/main.js` with a stdin job): **export-cars reports every failed
+run as success.** nest-commander's default `serviceErrorHandler` only prints the error, and `main.ts` then
+writes `{"complete":1,"code":0}`. This applies to all export types, Google and Meta included. The OpenAI exporter
+fails the job itself (`exitError` + exit 1). The global fix is a separate task.
+
+Not done (next steps / human):
+- transport: hosted URL or SFTP, after Q10;
+- Cronicle event: DEV dry-run first;
+- a real DEV/PROD dry-run plus the 20-car reconciliation;
+- delta PATCH: deferred, needs API access;
+- crawler access, per ADV-336: robots.txt has `Disallow: /search/` for OAI-AdsBot, plus the Cloudflare rules and the SPA shell without SSR on `/search*`.

package/docs/openai-ads/RUNBOOK.md

@@ -0,0 +1,94 @@
+# OpenAI Ads vehicle feed (`exportType=openai_ads`) — runbook
+
+ADV-335. Contract version: **openai-ads-csv v1** (columns in `src/interfaces/openai-ads.interface.ts`).
+Go-live is BLOCKED until the account gate (DE market, EUR, used-car inventory, import method) is confirmed in
+writing — see `AUDIT.md` §5.
+
+## What the job does
+
+1. Reads the base export snapshot `resources/cars-export/cars.<n>.json` (written by "1.0 Base export";
+   only `state.isOnline` cars).
+2. **Source guard** (before anything is written): chunk files exist, no gap in `0..n-1`, newest chunk not older
+   than `feedGuardMaxSourceAgeHours`.
+3. Maps every car (`transformers/openai-ads.transformer.ts`), checks the dealer (UPA `active`/`blacklist`),
+   picks clean images (ADV-336: `large-cached.jpeg`, 3/4 hero first, every URL HEAD-checked).
+4. Writes `<output>.tmp`: in_stock rows, then out_of_stock rows for items sent before (ledger).
+5. **Count guard**: source and in_stock counts ≥ minimums and not more than `feedGuardMaxDropPercent` below the
+   last good run.
+6. Publishes by rename (`<output>.prev` = previous file), saves the ledger and `last-good.json`.
+7. Writes `last-run-report.json` and prints it as one `OpenAI ads feed report: {…}` log line.
+
+A blocked or failed run exits with code 1 (`{"complete":1,"code":1,"description":…}`); the last good file
+stays in place and `<output>.rejected` holds the file that was not published.
+
+## Files
+
+| Mode | Output (what a transport may publish) | State |
+|---|---|---|
+| dry-run (default) | `resources/openai_ads-dryrun/api_export_cars_openai_ads.csv` | `resources/openai_ads-state/dryrun/` |
+| live (`openAiAdsDryRun=false`) | `resources/openai_ads-export/api_export_cars_openai_ads.csv` | `resources/openai_ads-state/export/` |
+
+State dir: `ledger.json` (items sent in_stock, for out_of_stock), `last-good.json`, `last-run-report.json`,
+`run.lock`. Dry-run and live never share state.
+
+No transport is implemented yet. Nothing leaves the server until a hosted-URL location or an SFTP upload is set
+up for the **live** output only (separate, approved step).
+
+## Cronicle event (to be created by an admin — not done)
+
+- Plugin "Export cars", chained after "1.0 Base export" (same as the Google/Meta exports), daily.
+  Items expire at OpenAI after 2 weeks without refresh — never rely on manual uploads.
+- Concurrency 1 (the job also takes `run.lock`).
+- Params (all text; unset = default):
+
+| Param | Default | Meaning |
+|---|---|---|
+| `exportType` | — | `openai_ads` |
+| `openAiAdsDryRun` | dry-run | `false` = write the live output |
+| `openAiAdsSellerName` | `auto.de` | `seller_name` (open question Q3) |
+| `openAiAdsRetentionDays` | 15 | days an item stays as out_of_stock after it was last in stock |
+| `openAiAdsImageConcurrency` | 16 | parallel image HEAD checks against images.auto.de |
+| `maxCurrentSalesPrice` | none | optional price cap (no 80k default here, Q9) |
+| `feedGuardMinSourceItems` | 1000 | DEV: set ~50 |
+| `feedGuardMinPublishedItems` | 500 | DEV: set ~20 |
+| `feedGuardMaxDropPercent` | 20 | vs the last good run |
+| `feedGuardMaxSourceAgeHours` | 26 | base export runs daily |
+| `feedGuardMaxStaleHours` | 48 | report flags `stale` after this |
+| `feedGuardAcceptDrop` | false | `true` for ONE run after a confirmed real drop; remove afterwards |
+| `String`, `Number`, `Date` | — | the usual rule params of the plugin (empty is fine) |
+
+## Monitoring
+
+- Cronicle job failure = feed not published (guard code in the description). Alert on failed job.
+- `last-run-report.json`: `rows.inStock/outOfStock`, `excluded{reason:count}`, `outOfStock{reason:count}`,
+  `images{ok|http_status|…}`, `price.min/max`, `source.newestChunkAt`, `lastGood`, `stale`.
+  Watch for: `excluded.no_image` or `dealer_unknown` spikes, `price.max` jumps, `stale: true`.
+- OpenAI side (manual until API access): Ads Manager → Tools → Feeds → Upload History (accepted / rejected /
+  diagnostics) and the ad-group product count. **Transfer success ≠ processed ≠ ads-eligible.**
+  The "Products" reporting tab is not an inventory view.
+
+## Guard codes
+
+| Code | Meaning | Action |
+|---|---|---|
+| `source_empty` / `source_partial` | base export failed or still running | check "1.0 Base export", re-run it, then this job |
+| `source_stale` | base export did not run | same |
+| `source_too_small` / `published_too_small` | below the absolute minimum | check CBD / UPA / images.auto.de; never lower the minimum to "make it pass" |
+| `count_drop` | > N % fewer cars than the last good run | confirm the drop is real (CBD online count, dealer offboarding), then ONE run with `feedGuardAcceptDrop=true` |
+| `locked` | another run holds `run.lock` (< 6 h) | wait; a lock older than 6 h is taken over automatically |
+
+## Rollback
+
+- Bad content published: `cp <output>.prev <output>` (the previous good file), then disable the Cronicle event.
+  Note: the ledger already contains the bad run's in_stock items — they will be sent as out_of_stock later,
+  which is the safe direction.
+- Stop advertising everything: disable the transport (hosted location / SFTP). Items expire at OpenAI after
+  2 weeks; to stop sooner, pause the campaigns in Ads Manager (Marketing).
+- Code: the exporter is isolated (`ExportType.OPENAI_ADS` only); reverting the export-cars version does not touch
+  Google/Meta outputs.
+
+## Tests
+
+`npm test` in the package: `test/openai-ads-mapping.test.ts` (price, identity, title, condition, German
+description, CSV quoting) and `test/openai-ads-feed-run.test.ts` (real files: first run, sold/reserved/reinstated,
+retention, empty/partial/stale source, count drop + acceptDrop, recovery, lock, broken hero image, UTF-8).

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "@bytebrand/export-cars",
-  "version": "1.26.28",
-  "description": "",
-  "author": "bytebrand",
-  "license": "UNLICENSED",
-  "scripts": {
-    "prebuild": "rimraf dist",
-    "build": "nest build",
-    "prepublishOnly": "npm run build",
-    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
-    "lint": "eslint -c .eslintrc.js --ext .ts src/",
-    "start:dev": "nest start --watch",
-    "test": "ts-node --transpile-only test/google-feed-envkv.test.ts && ts-node --transpile-only test/google-feed-item-row.test.ts && ts-node --transpile-only test/publication-gate.test.ts"
-  },
-  "dependencies": {
-    "@bytebrand/autode-request": "^1.19.2",
-    "@bytebrand/bigquery-logger": "^2.1.2",
-    "@bytebrand/car-basic-data-scope": "^9.11.24",
-    "@bytebrand/car-description": "^1.17.20",
-    "@bytebrand/car-schema": "^3.14.15",
-    "@bytebrand/chunkable": "^5.19.8",
-    "@bytebrand/cronicle-helper": "^1.21.8",
-    "@bytebrand/fe-financing": "^5.14.19",
-    "@bytebrand/i18n-dictionaries": "^1.5.0",
-    "@bytebrand/import-helper": "^0.45.0",
-    "@bytebrand/schema-tools": "^3.18.8",
-    "@bytebrand/zipper": "^2.2.0",
-    "@nestjs/cache-manager": "^2.1.0",
-    "@nestjs/common": "^10.2.7",
-    "@nestjs/core": "^10.2.7",
-    "axios": "^1.5.1",
-    "bottleneck": "^2.19.5",
-    "cache-manager": "^5.2.4",
-    "csv-write-stream": "^2.0.0",
-    "google-spreadsheet": "^3.3.0",
-    "lodash": "^4.17.21",
-    "moment": "^2.29.4",
-    "nest-commander": "~3.15.0",
-    "reflect-metadata": "^0.1.13",
-    "vin-generator": "^1.0.1"
-  },
-  "devDependencies": {
-    "@nestjs/cli": "^10.1.18",
-    "@types/google-spreadsheet": "^3.3.0",
-    "@types/inquirer": "^8.2.4",
-    "@types/lodash": "^4.14.186",
-    "@types/node": "^16.18.58",
-    "@typescript-eslint/eslint-plugin": "^6.8.0",
-    "@typescript-eslint/parser": "^6.8.0",
-    "eslint": "^8.0.1",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "gts": "^3.1.1",
-    "prettier": "^2.3.2",
-    "ts-node": "^10.0.0",
-    "tsconfig-paths": "4.1.0",
-    "typescript": "^5.2.2"
-  },
-  "engines": {
-    "node": ">=14.0.0"
-  },
-  "gitHead": "e827f35865032821bf3a081f03a026d3d3f8a540"
-}
+{
+  "name": "@bytebrand/export-cars",
+  "version": "1.26.30",
+  "description": "",
+  "author": "bytebrand",
+  "license": "UNLICENSED",
+  "scripts": {
+    "prebuild": "rimraf dist",
+    "build": "nest build",
+    "prepublishOnly": "npm run build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint": "eslint -c .eslintrc.js --ext .ts src/",
+    "start:dev": "nest start --watch",
+    "test": "ts-node --transpile-only test/google-feed-envkv.test.ts && ts-node --transpile-only test/google-feed-item-row.test.ts && ts-node --transpile-only test/publication-gate.test.ts && ts-node --transpile-only test/images-regression.test.ts && ts-node --transpile-only test/clean-images.test.ts && ts-node --transpile-only test/image-url-validator.test.ts && ts-node --transpile-only test/openai-image-fields.test.ts && ts-node --transpile-only test/openai-ads-mapping.test.ts && ts-node --transpile-only test/openai-ads-feed-run.test.ts"
+  },
+  "dependencies": {
+    "@bytebrand/autode-request": "^1.19.2",
+    "@bytebrand/bigquery-logger": "^2.1.2",
+    "@bytebrand/car-basic-data-scope": "^9.11.24",
+    "@bytebrand/car-description": "^1.17.20",
+    "@bytebrand/car-schema": "^3.14.15",
+    "@bytebrand/chunkable": "^5.19.8",
+    "@bytebrand/cronicle-helper": "^1.21.8",
+    "@bytebrand/fe-financing": "^5.14.19",
+    "@bytebrand/i18n-dictionaries": "^1.5.0",
+    "@bytebrand/import-helper": "^0.45.0",
+    "@bytebrand/schema-tools": "^3.18.8",
+    "@bytebrand/zipper": "^2.2.0",
+    "@nestjs/cache-manager": "^2.1.0",
+    "@nestjs/common": "^10.2.7",
+    "@nestjs/core": "^10.2.7",
+    "axios": "^1.5.1",
+    "bottleneck": "^2.19.5",
+    "cache-manager": "^5.2.4",
+    "csv-write-stream": "^2.0.0",
+    "google-spreadsheet": "^3.3.0",
+    "lodash": "^4.17.21",
+    "moment": "^2.29.4",
+    "nest-commander": "~3.15.0",
+    "reflect-metadata": "^0.1.13",
+    "vin-generator": "^1.0.1"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.1.18",
+    "@types/google-spreadsheet": "^3.3.0",
+    "@types/inquirer": "^8.2.4",
+    "@types/lodash": "^4.14.186",
+    "@types/node": "^16.18.58",
+    "@typescript-eslint/eslint-plugin": "^6.8.0",
+    "@typescript-eslint/parser": "^6.8.0",
+    "eslint": "^8.0.1",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "gts": "^3.1.1",
+    "prettier": "^2.3.2",
+    "ts-node": "^10.0.0",
+    "tsconfig-paths": "4.1.0",
+    "typescript": "^5.2.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "gitHead": "e827f35865032821bf3a081f03a026d3d3f8a540"
+}