@bytebrand/export-cars 1.26.30 → 1.26.32

package/docs/autouncle/AUDIT.md

@@ -0,0 +1,97 @@
+# AutoUncle inventory feed — audit (ADV-322 / ADV-323)
+
+Status 13.10.2026, base `origin/deploy_develop` 3a025095, `@bytebrand/export-cars` 1.26.31.
+Historical documents (Confluence "autouncle [paused]", "2.7.2 Export Plugins", ACF-3604/3650/3717/3725/6172/6190)
+are evidence only. No current AutoUncle inventory schema is available; the public AutoUncle B2B
+"automotive API" is a dealer/DMS **valuation** API and is not used as a schema here.
+
+## 1. Is the export live? — No
+
+| Where | Event | State | Last run | Output |
+|---|---|---|---|---|
+| PROD Cronicle (`auto-de-prod-cronicle-01`, export-cars 1.26.18) | `3.0 Export to autouncle - part 1` `ek61rkico08` | **disabled**, no timing, nothing chains into it | one manual run 07.07.2026, aborted by user | `resources/autouncle-export/api_export_cars_autouncle.json` = 8 bytes (`{"ads":[`) |
+| | `3.1 Export to autouncle - part 2` `ek61ro0yv09` | **disabled**; shell `cp` of the JSON to `htdocs/autouncle/export_cars_autouncle.json` | never ran | `htdocs/autouncle/` does not exist |
+| DEV Cronicle (`auto-de-dev-cronicle-01`, 1.26.31) | `3.0 Export to Autouncle part1` `ek60tym7m0b` | enabled, no timing; chained from `2.1 Export facebook - part 2` | 10.09.2026, code 0 | 467 KB JSON of 10.09 (298 ads) |
+| | `3.1 Export to Autouncle part2` `ek60u1gsd0c` | enabled, chains to `ek87441xa04` | 10.09.2026, **code 1** every run (`cp: … htdocs/autouncle/… No such file or directory`) | — the rest of the DEV chain (criteo, meinestadt, ooyyo, …) stops here |
+
+PROD 3.0 params: `environment=production`, `String` = allow-list of 19 dealer `metaData.ownerId`s, `Number` =
+`metaData.imagesCount:2`. DEV 3.0: no rules. Both events were last modified 2023 (DEV) / 01.04.2026 (PROD,
+migration). Events, keys and scripts were read with `storage-cli list_get`, secrets redacted.
+
+Hosting: `https://scheduler.auto.de/autouncle/export_cars_autouncle.json` (historic) — no answer (timeout);
+`https://cronicle.auto.de/autouncle/…` and `http://cronicle.autode-dev.de/autouncle/…` — 404. Nothing is
+hosted for AutoUncle today, on any environment.
+
+## 2. Code path
+
+`ExportType.AUTOUNCLE = 'autouncle'` → `AutouncleConfig` + `AutouncleExporter` (`export.schema.ts`).
+
+Before (unchanged since the monorepo import 3046a15d, CO2 class ADV-187 b46e7e83):
+`emptyDir(resources/autouncle-export)` → for every car of the base export snapshot: shared `filterCar`
+(imagesCount > 0 + Cronicle rules) → UPA dealer profile (skip if none) → `AutouncleTransformer` →
+`AutouncleJsonBuilder` appends `{"ads":[…]}` directly to the published file.
+
+After (this branch): `AutouncleFeedRun` (`services/autouncle-feed-run.ts`) — lock → source snapshot check
+(shared ADV-335 `FeedGuard`) → per car: duplicate id, `filterCar`, car-level exclusions, dealer address (UPA,
+cached per dealer), clean images (ADV-336 `getCleanImages` + `ImageUrlValidator` + `selectOpenAiImageFields`)
+→ pure `mapAutouncleItem` → temp file → count check → atomic rename (`.prev` kept) → report.
+Dry-run is the default and writes `resources/autouncle-dryrun/`, which no Cronicle step reads.
+
+## 3. Field mapping (`ads[]`, keys/order/spellings unchanged)
+
+| Key | Source | Before | Now | Open |
+|---|---|---|---|---|
+| back_link | CBD `_id` | `https://www.<domain>/search/vehicle/<_id>?source=classifieds&medium=cpc&campaign=autouncle` | same; stable across runs | UTM pattern = Confluence 2.7.2; others existed (ACF-3650/6172) → Q8 |
+| make / model_name / model_variant | mainData.make / model / subModel | raw | same | `SONSTIGE` placeholder models are exported (data) → Q9 |
+| fuel / body / gear_type | consumption.fuel / mainData.category / driveSuspension.gearbox | fixed maps; an unmapped or null selector made the key **disappear** from JSON | unmapped/null → `Other` / `other` | enum values → Q6 |
+| doors | mainData.doors | string | same | |
+| price | price.currentSalesPrice | `EUR <value>`; missing price → `"EUR "` and the car was still sent | same format; no valid positive price → car not sent (`no_valid_price`). Never a rate, never purchasePrice | currency format → Q6 |
+| year | mainData.firstRegistration (Unix s) | null → `moment(0)` → **1970** (143 of 1044 DEV cars) | missing/0/null/invalid → `""`; outside 1900..next year → `""` | null vs "" → Q6 |
+| status | same | `Neuwagen` only when firstRegistration === 0 | `Neuwagen` when no valid firstRegistration (same rule, null included) | 3 of 143 DEV cars are `condition=used` without registration → Q7 |
+| mileage | mainData.mileage | `<n>km`, 0 → `1km` | same | |
+| leasing / has_4wd | — | always `""` | same | → Q10 |
+| color | exterior.exteriorColor, German label | same | same | |
+| engine_size | engineData.cubicCapacity | `ccm` with no number when missing (189/1044) | `""` when missing | |
+| power | engineData.powerKW | kW, no unit | same | unit → Q6 |
+| seller_type / seller_name | — | `Dealer` / `auto.de` | same | marketplace vs dealer identity → Q3 |
+| seller_id | metaData.ownerId | **dealer** id already (not a vehicle id) | same; contract test with two cars of one dealer | |
+| seller_region / city / street_address / postcode | UPA businessAddress, else mainAddress; region from the postal code table | if the table did not know the place, street/city/zip were **blanked** (664/1044 DEV cars) | dealer's own values kept, region `Deutschland` | |
+| description | offer.offerDescription | raw | same; 192/1002 empty on DEV, some contain literal `\\` line breaks (dealer data) | → Q10 |
+| images | Imbo images | default profile: `/large` (format negotiated, can be WebP), padded with **3 noimage placeholders** below 17 photos (2820 placeholder URLs on DEV) | `[{url}]`, ADV-336 clean profile, explicit `large-cached.jpeg`, every URL checked (200 + image/jpeg|png); no valid 3/4 hero → car not sent | limits → ADV-323 gate |
+| fuel_economy / co2_emission | consumption.consumptionCombined / environmentEmissions.co2 | raw | same | |
+| co2_effiency_class / euro_emission_class / enviromental_sticker | environmentEmissions.* | raw selector keys (`selector_energyEfficiencyClass_d`) | same (no schema to translate to) | → Q6 |
+
+Car-level exclusions (new, counted in the report): `duplicate_id`, `filtered`, `no_id`, `no_dealer`,
+`reserved_or_sold` (offer.offerAvailability reserved/sold), `no_valid_price`, `no_valid_image`.
+
+## 4. Fixes on this branch
+
+1. Builder wrote the first car twice (`{"ads":[A,A,B…`) — fixed, test.
+2. Year 1970 for a null first registration (ACF-3717/3725 class of bug) — fixed, tests.
+3. Price must be a valid positive end-customer price, otherwise the car is not sent.
+4. Reserved / sold cars are not sent (absence = removal; partner semantics unknown → Q5).
+5. Dealer address no longer blanked when the postal code table misses the place.
+6. `engine_size` without a value is `""`, not `ccm`; unmapped selectors never drop a key.
+7. Images: clean profile + validator, no placeholders, no WebP risk, hero first (ADV-323).
+8. Fail-closed: no `emptyDir`; empty / partial / stale snapshot, empty result or a drop > 20 % against the
+   last good run → run blocked (exit 1, `3.1` copy does not run), last good file stays. Lock per state dir.
+9. Dry-run default; live only with `autouncleDryRun=false`.
+
+## 5. Evidence
+
+- `npm test`: 138 ok (116 existing + 14 mapping + 8 run).
+- Other feeds byte-identical: `origin/deploy_develop` and this branch compiled with the same `node_modules`;
+  every emitted `.js` outside the AutoUncle files is identical (only `params.interface.d.ts` gains three
+  optional fields). Covers Google, FB/Meta, Criteo, meinestadt, OOYYO, OpenAI and the rest.
+- DEV dry-run 13.10.2026 (local, DEV snapshot 12.10 15:00 CEST, DEV `3.0` params): 2234 source cars →
+  1002 ads, 370 dealers, excluded `filtered` 1190 / `no_valid_image` 42, images 7259/7259 ok, 0 placeholders,
+  0 × 1970, 0 duplicate links. Old exporter on the same snapshot: 1045 ads (first duplicated), 143 × 1970,
+  2820 placeholder URLs. 20-car sample in `autouncle-sample/` (worktree, not committed).
+
+## 6. Not done / not decided
+
+- No partner schema, no test import, no activation, no Cronicle change, no version bump / publish.
+- `minPublishedItems` default is 1 (PROD exports an allow-list of 19 dealers; real size unknown) — set per job
+  before activation.
+- `3.1` copy target `htdocs/autouncle/` does not exist on either Cronicle; hosting/transport is a partner question (Q4).
+- Portrait / small images: the validator checks status + MIME only, no pixel size — waits for partner limits.

package/docs/autouncle/PARTNER-QUESTIONS.md

@@ -0,0 +1,53 @@
+# Open questions for AutoUncle (Mario Kunz-Pfauch, mario.pfauch@autouncle.com)
+
+Draft for Marketing / Commercial. **Not sent.** Erik Lusuardi and Katarina Tökölyova were involved in the
+January 2025 CPS proposal; their current ownership is not established. Historical documents (Confluence
+"autouncle [paused]" 08.06.2023, "2.7.2 Export Plugins") are evidence only — we need the CURRENT inventory feed
+specification in writing. The public AutoUncle B2B automotive API (dealer/DMS valuation) is not the inventory
+ingestion contract and is not used as one.
+
+## Commercial / account
+
+1. **CPS vs CPC.** Is the January 2025 cost-per-sale proposal still valid, or is the model now cost-per-click
+   (or another)? Please confirm price, sale definition and eligibility, attribution/conversion window,
+   cancellations/returns, fees, credits, caps, term, billing and reporting.
+2. Who owns the account on your side today (business and technical contact)? Is the historic auto.de account
+   (dealer 1764) still active, or is a new contract / reactivation needed?
+3. **Seller identity.** We list as a marketplace: `seller_name` = "auto.de", `seller_id` = the individual
+   dealer's id, address = the dealer's address. Is that the model you expect, or must each dealer be a seller of
+   its own (name, imprint, contact)? Do you need dealer onboarding on your side?
+
+## Feed contract
+
+4. **Schema and transport.** Please send the current machine-readable inventory schema (field names, types,
+   mandatory/optional, enums, units). Is our historic `{"ads":[…]}` JSON with 31 keys still accepted —
+   including the spellings `co2_effiency_class` and `enviromental_sticker`? Do you pull a hosted URL (which
+   authentication, how often, from which IPs/user agent) or do we push (SFTP/API)?
+5. **Full vs delta, removals.** Is every file a full snapshot where a missing ad means "remove", or do you
+   need explicit delete/sold/reserved records? How fast do you process removals and price changes?
+6. **Formats.** Price as `EUR 15148` or a number + currency field? Unknown year: empty string, null, or omit
+   the key? Power in kW or PS? Mileage/engine size with or without the `km` / `ccm` suffix? Expected enum values
+   for fuel, body, gear type, CO₂ class (we can send A–G letters instead of internal keys), euro emission class
+   and environmental sticker?
+7. **New vs used.** How do you classify new cars, day registrations and demo cars? Is a car without a first
+   registration date "new"?
+8. **Unique key and links.** Which field is the unique ad key on your side — `back_link`, or should we add a
+   stable vehicle id? Which UTM parameters do you want on `back_link` (historic:
+   `source=classifieds&medium=cpc&campaign=autouncle`)? Do you need a click id passed through?
+9. How do you treat ads whose model is unknown (our placeholder "SONSTIGE")? Exclude or send?
+10. Optional fields: do you use `leasing`, `has_4wd`, `description` (German text), and do you support
+    structured financing offers (rate, duration, deposit, balloon, mileage, APR with legal disclosures) instead
+    of text?
+11. Feedback: do you provide an import report (accepted/rejected ads with reasons), and by which channel?
+12. **Test import.** Can you run a test import of our 20-ad sample (DEV data) before any production feed?
+
+## Images (ADV-323)
+
+13. Minimum / maximum number of images per ad, and is the order (main exterior 3/4 view first) kept?
+14. Accepted formats (JPEG / PNG / WebP), maximum file size, minimum/maximum pixel size, aspect ratios; do you
+    crop, resize or re-host?
+15. URL rules: maximum length, encoding, redirects allowed? How often do you re-fetch images, and how do you
+    handle a changed image under the same URL?
+16. Image rights, watermarks, dealer logos, marketing graphics or text overlays (e.g. rate badges): allowed or
+    not? (Our default is clean real photos only; overlays stay off without written approval.)
+17. Faces / licence plates: do you require blurring?

package/docs/autouncle/RUNBOOK.md

@@ -0,0 +1,64 @@
+# AutoUncle feed — runbook (ADV-322 / ADV-323)
+
+Not activated. Nothing below has been done on any Cronicle host.
+
+## Params (Cronicle text params of `3.0 Export to autouncle - part 1`)
+
+| Param | Default | Meaning |
+|---|---|---|
+| `autouncleDryRun` | dry-run | only the exact text `false` makes a live run |
+| `autouncleMaxImages` | no cut | cut the exported `images` list once AutoUncle gives a limit |
+| `autouncleImageConcurrency` | 16 | parallel image URL checks |
+| `feedGuardMinSourceItems` | 1000 | base snapshot size (shared by all feeds; DEV ~2,200) |
+| `feedGuardMinPublishedItems` | 1 | only forbids an empty file — PROD exports a dealer allow-list, set a real minimum |
+| `feedGuardMaxDropPercent` | 20 | max drop of source / ads against the last good run |
+| `feedGuardMaxSourceAgeHours` | 26 | newest base export chunk must be younger |
+| `feedGuardMaxStaleHours` | 48 | last good file reported STALE after this |
+| `feedGuardAcceptDrop` | off | `true` for ONE run after a real stock drop |
+
+`String` / `Number` rules stay as they are (PROD: dealer allow-list + `metaData.imagesCount:2`).
+
+## Files
+
+| Mode | Output | State |
+|---|---|---|
+| dry-run | `resources/autouncle-dryrun/api_export_cars_autouncle.json` | `resources/autouncle-state/dryrun/` |
+| live | `resources/autouncle-export/api_export_cars_autouncle.json` | `resources/autouncle-state/export/` |
+
+State dir: `last-good.json`, `last-run-report.json` (every run, also blocked ones: guard code, exclusions,
+dealer count, image stats), `run.lock`. A blocked run leaves `<json>.rejected`; the published JSON and
+`<json>.prev` stay.
+
+## Exit codes and the Cronicle chain
+
+Blocked or failed runs exit 1, so `3.1 … part 2` (copy to `htdocs/autouncle/`) does not run. DEV: `3.0` has no
+`chain_error`, so a blocked run also stops the rest of the DEV chain — which today already stops at `3.1`
+(copy target missing; all 18 runs in the DEV history failed there, latest 10.09.2026).
+
+## Before any activation (needs explicit OK)
+
+1. AutoUncle written schema + test import (PARTNER-QUESTIONS.md); adapt the mapping only inside
+   `transformers/autouncle.transformer.ts`.
+2. Decide hosting/transport: `htdocs/autouncle/` does not exist on DEV or PROD; the historic
+   `scheduler.auto.de` host does not answer.
+3. In dry-run mode `3.1` would copy whatever old file is in `autouncle-export/` (PROD: an 8-byte broken file) →
+   delete it or keep `3.1` disabled.
+4. Set `feedGuardMinPublishedItems` from a PROD dry-run.
+5. Version bump / publish / install on Cronicle — in turn with the meinestadt release.
+
+## Manual dry-run (as done 13.10.2026, locally)
+
+DEV base snapshot `/opt/cronicle/resources/cars-export/cars.*.json` copied with mtimes (`scp -p`) to
+`<run dir>/resources/cars-export/`; job input = DEV event `ek60tym7m0b` params (+ `feedGuardMaxSourceAgeHours`,
+`feedGuardMinPublishedItems`), compiled branch code:
+
+```
+node <compiled>/main.js < input.json      # cwd = <run dir>; NODE_PATH must resolve `src/…` imports
+```
+
+The job log echoes the input including the apikey — keep it local.
+
+## Rollback
+
+Install the previous export-cars version on the Cronicle host. Dry-run output and state are separate from the
+live path, so a dry-run never changes what `3.1` copies.

package/docs/meinestadt/AUDIT.md

@@ -0,0 +1,146 @@
+# meinestadt.de vehicle feed — audit (ADV-325 / ADV-326)
+
+Status 13.10.2026, base `origin/deploy_develop` aa787932, `@bytebrand/export-cars` 1.26.31.
+Historical documents are evidence only; nothing here is a confirmed current partner specification.
+
+## 1. Code and file contract (as built today)
+
+| Item | Current code | Historical sources | Note |
+|---|---|---|---|
+| Export type | `ExportType.MEINSTADT = 'meinstadt'` | Confluence `Meinstadt` exporter | spelling without "e" everywhere in code |
+| Files | `src/{exporters,transformers,formats,configs}/meinstadt.*.ts` | — | untouched since monorepo import (3046a15d, 12.06.2026) |
+| Output dir | `resources/meinstadt-export/` | — | emptied at the start of every run |
+| JSON file | `api_export_cars_meinstadt.json` | ACF-3985: `api_export_cars_meinestadt.json` | spellings differ; not normalized |
+| ZIP file | `api_export_cars_meinstadt.zip` (entry = the JSON) | Confluence: `api_export_cars_meinstadt.zip` | the ZIP is built but the Cronicle upload step sends the **JSON**, not the ZIP |
+| Envelope | bare JSON array `[ {...}, ... ]` | ACF-3985: `listings` array, "potentially optional" | no `{ "listings": [...] }` wrapper today |
+| Sorting | base-export chunk order | — | not explicitly sorted |
+| Fail-closed guard | none — a run with an empty source writes `[]` and the next step uploads it | — | see §4 |
+| Live / dry-run | no notion of dry-run | — | every run writes the file the upload step reads |
+
+## 2. Cronicle (DEV, read-only check 13.10)
+
+`auto-de-dev-cronicle-01`, export-cars 1.26.31 installed.
+
+- `5.0 Export to Meintadt part1` (`ekiout5fl62`): plugin export-cars, `exportType=meinstadt`, `cpc=0.99`,
+  target `auto-de-dev-cronicle-01`, no timing, chained from `4.1 Export criteo - part 2`, chains to `5.1`.
+- `5.1 Export menstadt part 2` (`ekipu4pcr01`): shell `ftp put` of
+  `/opt/cronicle/resources/meinstadt-export/api_export_cars_meinstadt.json` to an external FTP host
+  (185.15.211.90, user/password in plain text in the script), chains to `6.0 Export Ooyyo`.
+  Both events last modified 23.02.2023.
+- No job history for either event, and `resources/meinstadt-export/` does not exist on this server:
+  the chain `2.0 fb → 2.1 → 3.0 autouncle → 3.1 → 4.0 criteo → …` stops at `3.1 Export to Autouncle part2`,
+  which fails every time (`cp: cannot create … /opt/cronicle/htdocs/autouncle/…`, last 10.09.2026).
+  So meinestadt has **never run** on the current DEV Cronicle.
+- Risk: if the chain is repaired, DEV will push a DEV feed to the external FTP host without any guard.
+- PROD state (schedule, last success, upload target) not checked yet — needs a separate read-only OK.
+
+## 3. Field matrix — 32 historical keys vs current code
+
+Source: workbook `147qz9sT…`, tab `meinestadt` (gid 286164229), read 13.10.2026 via gviz.
+DEV data: base-export snapshot 12.10.2026 15:00, 2,234 cars, 1,044 with `metaData.imagesCount > 0` (the
+only ones any partner export sends).
+
+| # | Key (as emitted) | Sheet type | Sheet source / note | Current code | DEV data | Finding |
+|---|---|---|---|---|---|---|
+| 1 | `id` | String | `metaData.vehicleId` | same | 1044/1044 string (6-char) | OK |
+| 2 | `make` | String | `mainData.make` | same | OK | OK |
+| 3 | `model` | String | `mainData.model` | same | placeholder `SONSTIGE` exists | sent as-is |
+| 4 | `cpc` | Float | literal `0,08` | `config.cpc` param, default **`'0.08'`** (string) | DEV event `cpc=0.99` | **BUG (ADV-325)**: hidden historical default; emitted as string |
+| 5 | `listingUrl` | String | `…/search/vehicle/<id>/?source=meineStadt&medium=cpc&campaign=listing` | `…/search/vehicle/<id>?source=classifieds&medium=listing&campaign=meinestadt` | — | UTM differs from sheet → ADV-327 (tracking, paused); unchanged |
+| 6 | `title` | String | make & model & subModel | `${make} ${model} ${subModel}` | — | `SONSTIGE` / `undefined` possible; not changed now |
+| 7 | `accidentFree` | Boolean | `mainData.accidentDamaged` | `accidentDamaged` **without inversion** | 697 `false`, 347 `null`, 0 `true` | **BUG (ADV-325)**: every known accident-free car is sent as `accidentFree:false` |
+| 8 | `city` | String | "do not include this field" | not emitted | — | OK (comply) |
+| 9 | `zip` | String | "do not include this field" | not emitted | — | OK |
+| 10 | `latitude` | Float | "do not include this field" | not emitted | — | OK |
+| 11 | `longitude` | Float | "do not include this field" | not emitted | — | OK |
+| 12 | `mileage` | Number | `mainData.mileage` (km) | same | 3 null | OK |
+| 13 | `initialRegistration` | **String** | `mainData.firstRegistration` (number) | raw value = **Unix seconds as number** | 888 number (2021-11 … 2026-09), 156 null (151 new cars) | type differs from sheet; a reader expecting ms sees 1970 → partner must confirm format |
+| 14 | `offerCreationDate` | **String** | `metaData.creationDate` (number) | raw Unix seconds | 1044 number (2026-04-10 … 2026-10-09) | value is the CBD record creation date, the exporter never resets it; format as #13 |
+| 15 | `numberOfDoors` | Number | `mainData.doors` | same | 12 null | OK |
+| 16 | `numberOfSeats` | Number | `mainData.seats` | same | 5 null | OK |
+| 17 | `numberOfPreviousOwners` | Number | `mainData.numberOfPreviousOwners` | same | 111 null | OK |
+| 18 | `price` | Number | `price.currentSalesPrice` | same | 1044 number | OK — end-customer purchase price (EUR), not a rate, not `price.purchasePrice` (dealer cost) |
+| 19 | `power` | Number | `engineData.powerPS`, "PS only" | `engineData.powerPS` | 1044; 6 cars where PS ≠ kW×1.36 (source data) | OK — PS, not kW |
+| 20 | `co2Emissions` | Number | `environmentEmissions.co2` | same | OK | OK |
+| 21 | `fuelConsumptionCombined` | Float | `consumption.consumptionCombined` | same | OK | OK |
+| 22 | `images` | **String Array** | "put image url of main image … not the image id" | `carImages[0]` → a **single string** | — | **BUG (ADV-326)**: not an array; first entry of a placeholder-padded list |
+| 23 | `equipment` | String Array / comma string (`"ABS, Klimaanlage, DAB"`) | `offer.offerDescription` | mobile.de description (markdown `**`, `\\`, dealer header/footer) | — | differs from sheet; partner question, not changed now |
+| 24 | `color` | String (DE) | `exterior.exteriorColor` | `de[...]` | e.g. `Rot` | OK |
+| 25 | `bodyType` | String (DE) | `mainData.category` | `de[...]` | 118 `selector_unknown` → **"Unbekannt"** | unknown sent as a value |
+| 26 | `customerType/sellerType` | String | literal `Händler` | literal key `customerType/sellerType` = `Händler` | — | key name with slash is a mapping alternative in the sheet; code emits it literally → partner question |
+| 27 | `emissionClass` | String (DE) | `environmentEmissions.emissionClass` | `de[...]` | 25 `selector_unknown` → "Unbekannt" | as #25 |
+| 28 | `emissionSticker` | String (DE) | `environmentEmissions.emissionSticker` | `de[...]` | `Feinstaubplakette grün (4)` | OK |
+| 29 | `fuelType` | String (DE) | `consumption.fuel` | `de[...]` | OK | OK |
+| 30 | `transmissionType/transmission` | String (DE) | `driveSuspension.gearbox` | literal slash key | 1 unknown → "Unbekannt" | as #26 / #25 |
+| 31 | `usageState` | String (DE) | Neu / Gebraucht | `de[condition]`, unknown condition → mileage ≥ 100 km = used | `Gebraucht` 654 / `Neu` 390 | OK |
+| 32 | `imagesCount` | number | number of images | `carImages.length` | — | **BUG (ADV-326)**: counts the whole list incl. placeholders (see below) |
+
+`MeinstadtJsonItem` also declares `powerPS`, `powerKS`, `transmissionType`, `sellerType` — never emitted.
+
+### Images today (DEV data, 1,044 cars)
+
+`imageType = default`, `getImages(…, ignoreDefImages=false)`: the car's photos in shared sort order, padded
+with the three `carimage/noimage/…` placeholders (404) whenever the car has fewer than 17 photos.
+
+- 939 / 1,044 cars carry placeholders in the list; average list length 12.0.
+- `images` = first entry only (a string), `imagesCount` = full list length → count ≠ 1 for all 1,044 cars.
+- Clean profile (ADV-336 `getCleanImages`): average 7.0 real photos per car; 42 cars have no 3/4 exterior
+  hero and would be skipped (same 42 the OpenAI dry-run skips).
+
+- Additional finding: the DEV Cronicle host has no `zip` binary (only `unzip`). `Zipper.zip` shells out to it,
+  so the legacy exporter would have failed at the ZIP step there (OOYYO/mobile/AS24/rubrikk use it too).
+
+## 4. Decisions in this branch (user OK 13.10.2026: "do everything, DEV only for now")
+
+1. `images` = array of all valid clean URLs (ADV-336 clean profile + `ImageUrlValidator`, same selection
+   rules as the OpenAI feed: valid 3/4 hero first, then the other valid views), `imagesCount` = its length.
+   Cars without a valid hero are skipped and counted. The Imbo gallery itself is not changed.
+   `meinstadtMaxImages` cuts the exported list only (default: no cut) — for a partner one-image rule.
+   The image list is produced behind one function (`resolveImages` dep → `toMeinstadtImages`): the planned
+   meinestadt marketing image designs will plug in there; `imagesCount` follows whatever list is exported.
+2. `accidentFree`: `accidentDamaged === false → true`, `true → false`, anything else → `null` (unknown).
+3. `cpc`: no default. Live mode (`meinstadtDryRun=false`) refuses to start without a positive decimal `cpc`.
+   Dry-run without one sends `cpc: null`.
+4. Dry-run is the default: `resources/meinstadt-dryrun/` + `resources/meinstadt-state/dryrun/`. Live keeps
+   the historical `resources/meinstadt-export/` that the Cronicle upload step reads.
+5. Shared `FeedGuard` (ADV-335): empty / partial / stale source, minimum counts and drops > 20 % against the
+   last good run block the run; temp file + atomic rename; last good JSON/ZIP stay in place; one run per
+   state dir (lock). A blocked/failed run exits 1 so the chained upload step does not run.
+6. ZIP built in-process (adm-zip 0.5.5, already in the tree via @bytebrand/zipper) from the published JSON,
+   one entry `api_export_cars_meinstadt.json`.
+7. Dates stay Unix seconds (historical output); 0 / negative / unparsable / missing → `null`, never 1970.
+   `offerCreationDate` is the CBD record creation date, passed through unchanged.
+8. `selector_unknown` and unmapped selectors → `null` instead of "Unbekannt".
+9. Not changed (partner questions): file names, envelope, slash keys, date format, `equipment`, `listingUrl`
+   (UTM → ADV-327), `title`.
+
+## 5. Results
+
+Tests: `npm test` 96 → 116 checks green (`test/meinstadt-mapping.test.ts`, `test/meinstadt-feed-run.test.ts`).
+
+Other feeds: `tsc` of `aa787932` vs the branch — of 138 compiled `.js` files only `meinstadt.config.js`,
+`meinstadt.exporter.js`, `meinstadt.transformer.js` differ and `services/meinstadt-feed-run.js` is new; the other
+135 (all other exporters/transformers/builders, `images.service`, `feed-guard`, `car.service`, …) are
+byte-identical, so Google, Meta (fb / facebookshop), Criteo, AutoUncle, OOYYO, Awin, Trovit, … output cannot change.
+`images-regression.test.ts` (golden image URLs of all existing partner feeds) still passes.
+
+Dry-run on the DEV snapshot (12.10.2026 15:00), real image checks against images.autode-dev.de, real UPA:
+
+| | before (legacy code, computed) | after |
+|---|---|---|
+| source cars | 2,234 | 2,234 |
+| items | 1,044 | 1,002 (42 without a valid 3/4 hero skipped) |
+| `images` | 1 string, placeholders possible | array, 1–28 URLs, 7,259 / 7,259 URLs valid, 0 placeholders |
+| `imagesCount` ≠ exported URLs | 1,044 | 0 |
+| `accidentFree` | `false` 697, `null` 347 | `true` 676, `null` 326 |
+| "Unbekannt" values | yes | none |
+| runtime | — | ~5 min (image checks, concurrency 16) |
+
+20-car sample (ZIP, JSON, report, checklist, gallery preview): `meinestadt-sample/` in the worktree, not committed.
+
+Not fixed, seen in the data: placeholder model `SONSTIGE` in `model`/`title`; `equipment` carries the auto.de
+marketing header/footer of the mobile.de description ("über 180.000 Autos …") and mobile.de markup.
+
+## 6. Open partner questions
+
+See `PARTNER-QUESTIONS.md`.

package/docs/meinestadt/PARTNER-QUESTIONS.md

@@ -0,0 +1,54 @@
+# Open questions for meinestadt.de (Oliver Blank, oliver.blank@meinestadt.de)
+
+Draft for Marketing / Commercial. Not sent. Historical documents (ACF-3985 workbook, Confluence) are evidence
+only — we need the CURRENT automotive specification in writing.
+
+## Account, contract, billing
+
+1. Who is the current owner of the automotive (vehicle listings) feed on your side — business and technical
+   contact?
+2. Is the partner account `AUTODE` still active, or does the feed need a new contract / reactivation?
+3. What is the current CPC tariff (amount, currency, net/gross, caps/budgets, cancellation terms)? Should the
+   feed carry the CPC per listing at all, and if yes, must it equal the contracted tariff?
+4. How are clicks reported and billed today (report format, frequency, recipient)? (Accounting will reconcile
+   the 2025 invoice correspondence separately.)
+
+## Feed format
+
+5. Please send the current automotive feed specification (JSON schema or field list with types, mandatory
+   fields and accepted enum values). Is our historical 32-field format still accepted?
+6. File and container: JSON inside a ZIP, plain JSON, or another format? Required file name
+   (`api_export_cars_meinestadt.json` vs `api_export_cars_meinstadt.json`)? Top-level array or
+   `{ "listings": [...] }`?
+7. Field names: are `transmissionType/transmission` and `customerType/sellerType` literal keys, or should we
+   send `transmissionType` / `customerType` (or `transmission` / `sellerType`)?
+8. Date format for `initialRegistration` and `offerCreationDate`: we send Unix seconds (number). Do you
+   expect seconds, milliseconds, ISO 8601 (`2025-06-25`) or `MM/YYYY`? What should a new car without first
+   registration contain (omit, null, empty)?
+9. `accidentFree`: we send `true` (no accident damage), `false` (accident damage) or `null` (unknown). Is `null`
+   accepted, or should the field be omitted when unknown?
+10. `equipment`: a list of features (`"ABS, Klimaanlage, DAB"` or an array) or free text? Maximum length?
+11. Enumerations: which German values do you accept for `color`, `bodyType`, `fuelType`,
+    `transmissionType`, `emissionClass`, `emissionSticker`, `usageState`, `customerType`?
+12. `power`: confirm PS (not kW). `price`: confirm gross EUR purchase price.
+13. Location: our historical mapping says not to send `city`, `zip`, `latitude`, `longitude`. Still correct?
+14. `listingUrl`: required tracking parameters (historical: `source=meineStadt&medium=cpc&campaign=listing`)?
+
+## Images
+
+15. Do you accept several images per listing (`images` array) or only one main image? Maximum count? Is the
+    order significant (first = main image)?
+16. Image requirements: formats (JPEG/PNG/WebP), minimum/maximum pixel size, aspect ratio, maximum file
+    size, maximum URL length?
+17. Do you download/cache images or hot-link them? Crawler user agent and IP ranges (for our CDN/WAF), retry
+    behaviour, how often images are re-fetched, and how removed/changed images are invalidated?
+18. Are text, logos, watermarks, price or financing-rate overlays allowed on images? Any image rights /
+    copyright statements required?
+
+## Delivery and operations
+
+19. Delivery path: FTP/SFTP upload (host, directory, credentials, IP allow-list), or should you pull from a
+    URL we host? The historical target was FTP host 185.15.211.90 — is it still valid?
+20. Update frequency and timing; full file each time or deltas? How do you remove listings that are no longer
+    in the file (sold / withdrawn), and how fast?
+21. Can we run a test import first and get the parsed item count and rejection report?

package/docs/meinestadt/RUNBOOK.md

@@ -0,0 +1,64 @@
+# meinestadt.de feed — runbook (ADV-325 / ADV-326)
+
+## Parameters (Cronicle event, export-cars plugin, `exportType=meinstadt`)
+
+| Param | Default | Meaning |
+|---|---|---|
+| `meinstadtDryRun` | dry-run | only the exact text `false` makes a live run |
+| `cpc` | none | tariff as a positive decimal with a dot (`0.99`). Required for live; no 0.08 / 0 fallback |
+| `meinstadtMaxImages` | no cut | cut the exported `images` list (e.g. `1` if the partner accepts one main image) |
+| `meinstadtImageConcurrency` | 16 | parallel image URL checks |
+| `feedGuardMinSourceItems` | 1000 | DEV: ~2,200 source cars → keep or lower |
+| `feedGuardMinPublishedItems` | 500 | DEV: ~1,000 items → keep or lower |
+| `feedGuardMaxDropPercent` | 20 | max drop of source / items against the last good run |
+| `feedGuardMaxSourceAgeHours` | 26 | newest base export chunk must be younger |
+| `feedGuardMaxStaleHours` | 48 | last good file reported STALE after this |
+| `feedGuardAcceptDrop` | off | `true` for ONE run after a real stock drop |
+
+## Files
+
+| Mode | Output | State |
+|---|---|---|
+| dry-run | `resources/meinstadt-dryrun/api_export_cars_meinstadt.{json,zip}` | `resources/meinstadt-state/dryrun/` |
+| live | `resources/meinstadt-export/api_export_cars_meinstadt.{json,zip}` | `resources/meinstadt-state/export/` |
+
+State dir: `last-good.json` (counts of the last published run), `last-run-report.json` (every run, also
+blocked ones: guard code, exclusions, accidentFree split, image stats), `run.lock`.
+A blocked run leaves `<json>.rejected` for inspection; the published JSON/ZIP and `<json>.prev` stay.
+
+## Exit codes and the Cronicle chain
+
+Blocked (guard) or failed runs and a live run without `cpc` exit 1, so the chained `5.1 … part 2` upload
+does not run. Side effect in the DEV chain (`4.1 criteo → 5.0 meinstadt → 5.1 → 6.0 ooyyo → …`): the rest of
+the chain stops too (no `chain_error` on 5.0). Today the DEV chain already stops earlier at
+`3.1 Export to Autouncle part2` (fails since at least 25.08).
+
+## Before anything goes live (not done, needs explicit OK each)
+
+1. Partner answers (`PARTNER-QUESTIONS.md`), written acceptance of a test import; Commercial/Accounting OK.
+2. Cronicle `5.1 Export menstadt part 2` uploads the **JSON** from `resources/meinstadt-export/` by plain FTP to
+   185.15.211.90 with credentials in the script. Before deploying this version where 5.1 is active:
+   - in dry-run mode 5.1 would upload whatever old file is still in `meinstadt-export/` → disable 5.1 or
+     remove the old file first;
+   - target host / protocol / JSON vs ZIP to be confirmed with the partner; credentials into a Cronicle secret.
+3. PROD Cronicle state (events, last success, existing files) not checked yet.
+
+## Manual DEV dry-run (as done 13.10.2026, locally)
+
+Base export snapshot copied from the DEV Cronicle (`/opt/cronicle/resources/cars-export/cars.*.json`) to
+`<run dir>/resources/cars-export/`, compiled branch code, job input = DEV event `ekiout5fl62` params:
+
+```
+node <compiled>/main.js < input.json      # cwd = <run dir>; NODE_PATH must resolve `src/…` imports
+```
+
+## Rollback
+
+Install the previous export-cars version on the Cronicle host. Dry-run output and state dirs are separate
+from the live path, so a dry-run never changes what the upload step reads.
+
+## Later: marketing images
+
+The exported list comes from `resolveImages` in `MeinstadtExporter` (clean profile + validation →
+`toMeinstadtImages`). A meinestadt marketing image profile replaces that function; `imagesCount` always
+follows the exported list. Overlays/rate artwork only after written partner, Marketing and Legal OK (ADV-326).

package/docs/openai-ads/AUDIT.md

@@ -182,6 +182,7 @@ Filters before mapping (all reasons counted in the run report):
 | 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 | — |
+| Q14 | Make mapping at import (out of feed scope): DEV car titled "Jeep SWM G01a" — model SONSTIGE, variant names SWM (a different manufacturer), so the feed sends `brand=Jeep` for a non-Jeep car. Fix belongs to the import make/model mapping (sheet / CBD), not to the exporter. | Import owner | brand correctness |
 
 ---
 

package/docs/openai-ads/RUNBOOK.md

@@ -77,6 +77,25 @@ up for the **live** output only (separate, approved step).
 | `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 |
 
+## Known risk: other export-cars jobs report failures as success (accepted, 12.10)
+
+Every export-cars run except `openai_ads` ends with `{"complete":1,"code":0}`, even when the exporter threw:
+nest-commander's default `serviceErrorHandler` only prints the error and `main.ts` then reports success. Cronicle
+therefore treats a failed part 1 as successful and starts the chained part 2, which can upload an empty or
+partial file (Google feed incident 24.09: a 169-byte feed was uploaded and fetched by Google). Decision
+(user, 12.10): keep it — no global fix, no `chain_error` handlers, no Cronicle config change; the chains keep
+running after a failure as before.
+
+Only `openai_ads` is protected: the feed guard keeps the last good file, and the job exits with code 1
+(`exitError` + exit 1 in `openai-ads.exporter.ts`). It has no chain, so this stops nothing else.
+
+## Known source-data issues (not fixed by the feed)
+
+- Wrong make from the import mapping: e.g. DEV "Jeep SWM G01a" (model SONSTIGE, the variant names another
+  manufacturer). The feed sends the stored make as `brand`; correct it in the import make/model mapping (AUDIT Q14).
+- Handled in the feed since 1.26.30: placeholder model `SONSTIGE` is left out of title/description; UTF-8 read as
+  Latin-1/cp1252 upstream (`ü` → `ü`) is repaired.
+
 ## Rollback
 
 - Bad content published: `cp <output>.prev <output>` (the previous good file), then disable the Cronicle event.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebrand/export-cars",
-  "version": "1.26.30",
+  "version": "1.26.32",
   "description": "",
   "author": "bytebrand",
   "license": "UNLICENSED",
@@ -11,7 +11,7 @@
     "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"
+    "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 && ts-node --transpile-only test/meinstadt-mapping.test.ts && ts-node --transpile-only test/meinstadt-feed-run.test.ts && ts-node --transpile-only test/autouncle-mapping.test.ts && ts-node --transpile-only test/autouncle-feed-run.test.ts"
   },
   "dependencies": {
     "@bytebrand/autode-request": "^1.19.2",
@@ -29,6 +29,7 @@
     "@nestjs/cache-manager": "^2.1.0",
     "@nestjs/common": "^10.2.7",
     "@nestjs/core": "^10.2.7",
+    "adm-zip": "0.5.5",
     "axios": "^1.5.1",
     "bottleneck": "^2.19.5",
     "cache-manager": "^5.2.4",

package/src/configs/autouncle.config.ts

@@ -1,12 +1,60 @@
-import { ExportType, FileType, ImageType } from 'src/enums';
+import { toNumber } from 'lodash';
+
+import { ExportType, FileType, ImageType } from '../enums';
 import { Params } from '../interfaces/params.interface';
+import { FeedGuardOptions } from '../services/feed-guard';
 import { Config } from './config';
 
+const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '');
+
+const positiveNumber = (value: unknown, fallback: number): number => {
+  const parsed = toNumber(text(value));
+  return text(value) && Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+// Guard defaults. The PROD job only exports a dealer allow-list, so the published count is far below
+// the base snapshot: minPublishedItems only forbids an empty file — set a real minimum per job.
+export const AUTOUNCLE_DEFAULTS = {
+  imageConcurrency: 16,
+  minSourceItems: 1000,
+  minPublishedItems: 1,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+};
+
+/**
+ * AutoUncle JSON feed (ADV-322/323): `{"ads":[...]}` with clean ADV-336 images.
+ * Dry-run is the default: the file goes to resources/autouncle-dryrun, which no Cronicle step reads.
+ * Only autouncleDryRun=false writes resources/autouncle-export (the path `3.1 … part 2` copies from).
+ * Each mode has its own guard state.
+ */
 export class AutouncleConfig extends Config {
+  dryRun: boolean;
+  imageConcurrency: number;
+  // 0 = no limit (no partner limit known)
+  maxImages: number;
+  stateDir: string;
+  feedGuard: FeedGuardOptions;
+
   constructor(params: Params) {
     super(params);
-    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.AUTOUNCLE}-export`;
-    this.imageType = ImageType.default;
+    this.dryRun = text(params.autouncleDryRun).toLowerCase() !== 'false';
+    const mode = this.dryRun ? 'dryrun' : 'export';
+    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.AUTOUNCLE}-${mode}`;
+    this.stateDir = `resources/${ExportType.AUTOUNCLE}-state/${mode}`;
+    this.imageType = ImageType.clean;
+    this.imageConcurrency = positiveNumber(params.autouncleImageConcurrency, AUTOUNCLE_DEFAULTS.imageConcurrency);
+    this.maxImages = Math.floor(positiveNumber(params.autouncleMaxImages, 0));
+    this.feedGuard = {
+      stateDir: this.stateDir,
+      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, AUTOUNCLE_DEFAULTS.minSourceItems),
+      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, AUTOUNCLE_DEFAULTS.minPublishedItems),
+      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, AUTOUNCLE_DEFAULTS.maxDropPercent),
+      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, AUTOUNCLE_DEFAULTS.maxSourceAgeHours),
+      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, AUTOUNCLE_DEFAULTS.maxStaleHours),
+      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
+    };
     this.outputFiles = [
       `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.AUTOUNCLE}.${FileType.JSON}`,
     ];