@bytebrand/export-cars 1.26.46 → 1.26.48

package/docs/marktde/AUDIT.md

@@ -13,7 +13,7 @@ letters are code evidence, not a contract.
 | Row format | `MobileTransformer` + Google sheet `147qz9sT…` tab `mobile_yescar` (165 rules, ACF-4370 reused the YesCar / mobile.de CSV). `;` separated, every cell quoted, no header row, UTF-8, 517–528 columns per row |
 | Files | `api_export_cars_marktde.csv` + `.zip` (was `resources/marktde-export/`) |
 | DEV Cronicle | `9c.0 Export markt.de - part 1` `ekpy4pqg21u` (rule `metaData.ownerId:xo1ag9JooQebXhnfSclw3NhZyG63`) → `9c.1 … part 2` `ekyvib2rm06` (plain `ftp -pinv 185.15.211.90`, uploads `develop_marktde.zip/.csv`, credentials in the script) → `9d.0 facebook shop`. Triggered by the chain after `9b.1 Export Focus`. No run in the job history |
-| DEV runtime defects found | (a) the Google Sheets API key in `9c.0` is **expired** — the mapping sheet cannot load, every row-building run fails; (b) the filtered dealer has 0 cars in the DEV snapshot; (c) the host has no `zip` binary — the legacy run wrote the CSV, failed the ZIP and still reported `code 0`; (d) `9c.1` uploads names the exporter never writes; (e) 185.15.211.90 is the legacy Jelastic FTP (port 21 closed, see ADV-319 4.1) |
+| DEV runtime defects found | (a) the Google Sheets API key in `9c.0` is **expired** — the mapping sheet could not load (fixed in 1.26.47: public CSV, no key); (b) the filtered dealer has 0 cars in the DEV snapshot; (c) the host has no `zip` binary — the legacy run wrote the CSV, failed the ZIP and still reported `code 0`; (d) `9c.1` uploads names the exporter never writes; (e) 185.15.211.90 is the legacy Jelastic FTP (port 21 closed, see ADV-319 4.1) |
 | PROD | not checked (DEV-only task). Old contract / account belong to the former auto.de Media GmbH — not transferable (Daniel, 16.10) |
 
 ## 2. Source → target matrix (columns the feed relies on)

package/docs/marktde/RUNBOOK.md

@@ -4,7 +4,7 @@
 
 | Param | Default | Meaning |
 |---|---|---|
-| `apikey` | — | Google Sheets API key for the mapping sheet `mobile_yescar`. **DEV 9c.0: expired (12.11.2026)** |
+| `apikey` | — | no longer used for the mapping (since 1.26.47 the tab `mobile_yescar` is read from the sheet's public CSV, no key); the sheet must stay readable by everyone with the link. The DEV 9c.0 key is expired (12.11.2026) |
 | `String` / `Number` / `Date` | — | Cronicle filter rules (DEV 9c.0: one dealer, 0 cars today) |
 | `marktdeDryRun` | dry-run | only the exact text `false` makes a live run |
 | `marktdeMaxImages` | no cut | cut the image list (no markt.de limit known) |
@@ -42,7 +42,7 @@ the API with `chain: ""` (see below) or from the UI with the chain removed for t
 D=/home/deploy/export-cars-<ver>-dryrun/<name>   # job.json (chmod 600) + credentials + resources/cars-export symlinks
 NODE_PATH=<pkg>/dist:/opt/cronicle/node_modules node <pkg>/dist/main.js < job.json > run.log
 ```
-While the event's Sheets key is expired: `node harness.js <pkg> < job.json` — the harness runs the same
+Before 1.26.47 (Sheets API key expired): `node harness.js <pkg> < job.json` — the harness runs the same
 `main.js` but loads the mapping rules from the public CSV of the same sheet tab (gviz) with the same
 post-processing as `MappingService`.
 
@@ -50,7 +50,7 @@ post-processing as `MappingService`.
 
 1. Signed contract / account for auto.de GmbH, current markt.de feed spec + test importer
    (`PARTNER-QUESTIONS.md`); written acceptance of a test import of the 20-row sample.
-2. New Sheets API key in the 9c.0 params (or move the mapping out of Google Sheets).
+2. Keep the mapping sheet shared with everyone who has the link (1.26.47 reads its public CSV; a private sheet fails the run).
 3. Dealer scope (the rule in 9c.0) and `feedGuardMinPublishedItems` from a PROD dry-run.
 4. Replace `9c.1`: transport and file names from the spec, credentials out of the script; never the
    legacy Jelastic host. Only then `marktdeDryRun=false`.

package/docs/marktde/TRACKING.md

@@ -3,6 +3,8 @@
 Status 12.11.2026: DEV only. Implemented: the clickout link (export-cars 1.26.45) and the reporting
 channel `CLASSIFIEDS_MARKTDE` (web-funnel-tracking-health 1.5.6). Not implemented, by design, until
 markt.de confirms a path in writing: partner click ids, hosted-enquiry ingestion, cost import.
+13.11.2026: DEV end-to-end lead test (link → VDP → enquiry → Odoo REQ → session / lead views), see QA.
+Customer-SQL proposal (not applied): `release-runbooks/adv-328/ADV-330-customer-sql-proposal.sql`.
 
 ## Evidence
 
@@ -23,7 +25,8 @@ markt.de listing ──(structured field OM)──► https://www.auto.de/search
     ?source=marktde&medium=listing&campaign=listing&utm_source=marktde&utm_medium=listing&utm_campaign=listing
   → fe-main marketing cookie (ADV-260)        → visitor session, landing_url keeps the raw query
   → views: reporting_channel CLASSIFIEDS_MARKTDE, family Classifieds, detail markt.de, publisher MARKTDE
-  → form → REQ → Odoo crm_source "marktde" (lower-case source, no SQL change needed)
+  → form → REQ → Odoo crm_source "marktde" (lower-case source, no SQL change needed; VDP enquiries
+    need the user-actions-contact ADV-327 cookie fallback — DEV since 13.11, not on PROD)
   → rpt_episode_touchpoint → canonical 90-day episode (original episode_start_date) → sale / CM
 ```
 
@@ -63,7 +66,10 @@ stay unchanged (live report layout changes need approval).
 | `utm_source=markt.de`, other medium (`cpc`) | CLASSIFIEDS_MARKTDE, not PAID_OTHER | unit test ✓ |
 | Google click id + markt.de utm | click id wins (PAID_SEARCH_GOOGLE) | rule order test ✓ |
 | no consent / revoked | no marketing cookie → lead without source (unchanged behaviour) | not run (needs browser) |
-| lead → REQ → episode → sale | crm_source marktde, episode keeps original start | not run (no markt.de traffic) |
+| VDP enquiry → REQ → Odoo source (cookie only, no body marketing) | utm source from the marketing cookie | ✅ 13.11 DEV: REQ584786 `marktde / listing / listing`, REQ584785 `classifieds / listing / marktde` (raw, legacy link) |
+| same visits in the views | session CLASSIFIEDS_MARKTDE / Classifieds / markt.de / MARKTDE, VISITOR, lead_persisted; lead view REQ joined, crm_status CONFIRMED | ✅ 13.11 DEV (`testmk3-new-1794562402`, `testmk3-legacy-1794562402`) |
+| producer label in the lead view (`resolved_channel`) | not the reporting channel (message-schemes knows no partner classifieds; REFERRAL with the markt.de referrer) — report by the session's `reporting_channel` | documented, unchanged (same for meinestadt / AutoUncle) |
+| episode → sale / CM | crm_source marktde → `source_resolved_v1 = marktde`; legacy link needs the proposed D-rule; episode keeps original start | not run: prod customer SQL; DEV `crm_source_resolved_v1` empty (DEV CRM export stale since 29.10) |
 | partner id, hosted leads, invoice import, credits, double import | — | blocked on partner spec |
 
 Launch blockers: contract (auto.de GmbH), clickout permission, spec, legal / data QA, feed + image tests.

package/docs/meinestadt/PARTNER-QUESTIONS.md

@@ -52,3 +52,20 @@ only — we need the CURRENT automotive specification in writing.
 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?
+
+## Measurement and reporting (ADV-327)
+
+22. Daily click report: please send the latest original `meinestadt-daily_reporting_AUTODE_<date>.csv` and its
+    field definitions — separator, encoding, decimal format, timezone of the report date, currency, net/gross.
+23. Which clicks are billable vs non-billable (bots, duplicates, invalid clicks)? How are corrections, credit
+    notes and late revisions delivered (new file for the same day, separate file, invoice only)?
+24. Report delivery: e-mail attachment, SFTP, URL or API? Recipient / account? What happens on a day without
+    clicks (empty file or no file)?
+25. Is there a budget cap per day / month, and does the report show when it was reached?
+26. Do you append your own click or listing identifier to the `listingUrl` (name and format)? If not, we
+    reconcile in aggregate per day only.
+27. Do you offer or require a conversion pixel, postback or server-to-server event? We send nothing back today
+    and would only add a partner-confirmed event with a consent basis and a DPA.
+28. Do you redirect through your own tracking host before our page, and does the redirect keep all query
+    parameters?
+29. Data retention and consent requirements on your side for the click data in the report.

package/docs/meinestadt/TRACKING.md

@@ -0,0 +1,107 @@
+# meinestadt.de — measurement design (ADV-327)
+
+Status 13.11.2026: DEV only. Implemented: the listing link (export-cars 1.26.44), the reporting channel
+`CLASSIFIEDS_MEINESTADT` (web-funnel-tracking-health 1.5.5) and the lead source for the VDP enquiry
+(user-actions-contact, ADV-327 fix). Not implemented, by design, until meinestadt confirms a path in
+writing: partner click ids, postbacks / pixels, the daily report import. No production switch.
+
+## 1. Evidence
+
+| Source | Link parameters | Note |
+|---|---|---|
+| Original 32-field workbook (tab `meinestadt`) | `source=meineStadt&medium=cpc&campaign=listing` | historic |
+| export-cars ≤ 1.26.43 / Confluence | `source=classifieds&medium=listing&campaign=meinestadt` | partner only in `campaign` |
+| export-cars ≥ 1.26.44 (current DEV) | `source=meinestadt&medium=listing&campaign=listing` + identical `utm_source/utm_medium/utm_campaign` | partner in `source`; no paid medium |
+
+- ADV-260: fe-main stores `source / medium / campaign / utm_*` + click ids in the `marketing` cookie
+  (`CommonUtils.ts` `MARKETING_PARAM_REGISTRY`, merge per key, 24 h) and the first landing URL / external
+  referrer in `landing_context` (first wins). car-basic-data (VDP), car-search-endpoint (SRL),
+  user-actions-contact (forms, checkout) read both cookies server-side into the BigQuery event rows.
+- Before 1.5.5 every variant fell into generic rules: the workbook variant (`medium=cpc`) as `PAID_OTHER`,
+  the legacy variant as `UNRESOLVED` (`medium=listing` is unmapped). Partner identity was lost.
+- Before the ADV-327 fix the VDP enquiry "Frage zum Fahrzeug" (`VehicleDetailedNextPage.onEnquirySubmit`)
+  sent no `marketing` object, and user-actions-contact built the Odoo message only from the body, so
+  those REQs reached Odoo without utm source / medium / campaign. DEV 09.11.2026, same visit with a
+  Criteo cookie: enquiry → source "(nicht bekannt)", offer request → `criteo / cpc / retargeting`.
+  This affected every channel, not only meinestadt.
+- No meinestadt click id, postback, pixel or reporting API is known. Daily e-mails from
+  auto@meinestadt.de with `meinestadt-daily_reporting_AUTODE_<date>.csv` existed historically; no file was
+  available for this ticket, so its schema is not verified.
+
+## 2. Path
+
+```
+meinestadt listing ──listingUrl──► https://www.auto.de/search/vehicle/<car _id>?source=meinestadt&medium=listing&campaign=listing&utm_*=…
+  → fe-main: marketing cookie + landing_context (ADV-260)        raw values unchanged in every event row
+  → views: reporting_channel CLASSIFIEDS_MEINESTADT, family Classifieds, detail meinestadt.de, publisher MEINESTADT
+  → form (VDP enquiry / offer request / checkout) → REQ → Odoo utm source "meinestadt"   (body marketing, or the cookie)
+  → fact_lead.crm_source → source_resolved_v1 = 'meinestadt' (customer SQL, no change needed for the new link)
+  → rpt_episode_touchpoint → canonical 90-day intent episode (original episode_start_date) → fact_sale / CM
+```
+
+- Grain: VISITOR session (traffic_class VISITOR; KNOWN_CRAWLER / BOT_SUSPECT rules run before attribution).
+- Raw vs normalized: `source / medium / campaign / utm_*` stay as received in the event rows and in Odoo;
+  the channel is derived in the views. Historical rows are not rewritten — the views classify at query
+  time, the producer label (`resolved_channel`, message-schemes) is untouched.
+- Rule (web-funnel-tracking-health `MEINESTADT_UTM`): `source` (legacy or utm, lower-cased) in
+  `meinestadt` / `meinstadt`, or `source = classifieds` and `campaign` in `meinestadt` / `meinstadt`; any
+  medium; after the click-id rules (a Google click id wins), before the paid UTM rules; not `PAID_*`, so
+  the paid click-id health rates are unaffected (paid / free is a contract attribute).
+- Listing-level join without a partner id: feed `listingUrl` car `_id` = VDP id = lead car id.
+- Click reconciliation: platform `meinestadt` in `buildClickReconciliationView`, aggregate only (no click
+  id). Used only once `fact_marketing_media` holds meinestadt rows. No artificial 1:1 mapping.
+- Off-site leads (phone, partner-hosted forms) never create a website session.
+- Consent: the cookie capture is first-party and not consent-gated today (open compliance question noted
+  in fe-main `CookieUtils.getConsentState`); every event row carries `marketingConsent` /
+  `analyticsConsent` from the request headers. Nothing is sent to meinestadt (no pixel / postback).
+  Finance / bank data never leaves auto.de.
+
+## 3. Episodes and sales (customer SQL, prod-only, not applied)
+
+- New link: `crm_source = meinestadt` → `source_resolved_v1/v2 = 'meinestadt'` with the existing rules.
+- Legacy link (`classifieds` + campaign `meinestadt`): resolves to `classifieds` today; proposal D-rule
+  `source_resolved_v2 = 'meinestadt'`, method `PARTNER_PARAM_EXACT` (raw values kept). File:
+  `release-runbooks/adv-327/ADV-327-customer-sql-proposal.sql`.
+- Same person within a fixed 90-day episode → no new acquisition (`rpt_customer_intent_episode`).
+  Sales: distinct `fact_sale` ids per episode, cohort = `episode_start_date`, `sales_reported_at` separate.
+
+## 4. Costs (blocked on the real report and a contract)
+
+- Target: the existing `fact_marketing_media` / `fact_marketing_cost` (no new table, no data mart).
+  `source_system = meinestadt_daily_report`, `channel = meinestadt`, report date (partner timezone →
+  Europe/Berlin), billable / non-billable clicks, spend, currency, credits as negative rows, invoice
+  number, contract version, file name + SHA-256 for idempotent upsert and correction replay, status
+  `actual` / `estimated` / `missing` per day.
+- The feed field `cpc` is a bid / configuration value, never actual cost; no cost from the historic 0.08.
+- `rpt_lead_cost_live.paid_channel_v3` gets `meinestadt` only while a CPC contract is effective.
+- The parser is written against a real CSV only (separator, encoding, decimal comma, timezone, columns).
+
+## 5. QA (DEV)
+
+| Case | Expected | Status |
+|---|---|---|
+| new link, legacy link, workbook link (`meineStadt` + `cpc`) | CLASSIFIEDS_MEINESTADT event + session | ✅ 12.11 real DEV requests + unit tests |
+| other classifieds campaign | not meinestadt | ✅ control → UNRESOLVED |
+| Google click id + meinestadt utm | click id wins | ✅ rule order test |
+| raw values kept | event rows hold `meineStadt` / `classifieds` as sent | ✅ BQ |
+| fe-main capture of the link | cookie = link parameters, no parameterConflict | ✅ fe-main function run on the URLs |
+| health metrics | Classifieds in `channel_family_share`, 0 WARN | ✅ day run 12.11 |
+| VDP enquiry → REQ → Odoo source (no body marketing, cookie only) | utm source from the cookie | ✅ 13.11 DEV: REQ584784 `meinestadt / listing / listing`, REQ584783 `classifieds / listing / meinestadt` (raw); sessions CLASSIFIEDS_MEINESTADT, `develop_web_journey_lead_v1` CONFIRMED |
+| offer request with body marketing | unchanged (body wins) | ✅ unit test |
+| no consent | capture unchanged, consent flag on rows | documented, not changed |
+| bot | KNOWN_CRAWLER / BOT_SUSPECT, not counted | existing rules |
+| new / repeat episode, 2 sales, CSV replay / credit / no-report day, DST | — | prod customer SQL / blocked on CSV |
+
+Note: Odoo `cookieid` is filled only for signed-in senders (user-actions-contact, unchanged); the website
+session ↔ REQ link is `lead_funnel_event` (session id + Pub/Sub messageId → REQ), as for every form.
+
+## 6. Launch blockers
+
+Contract with auto.de GmbH, partner spec and approval of the link parameters, real daily CSV + field
+definitions, legal / privacy sign-off, customer-SQL owner OK, feed and image acceptance (ADV-325/326).
+
+## 7. Rollback
+
+- Link: export-cars ≤ 1.26.43 (dry-run feed only, nothing published).
+- Channel: web-funnel-tracking-health 1.5.4 + view rebuild (event `emubc2hjemu`).
+- Lead source fallback: revert the user-actions-contact commit and rebuild the service.

package/docs/ooyyo/AUDIT.md

@@ -0,0 +1,81 @@
+# OOYYO feed — audit and contract (ADV-331)
+
+Status 13.11.2026: DEV only, dry-run by default. Nothing is hosted, sent or submitted; OOYYO's
+crawler is not enabled. Export type `ooyyo`, export-cars ≥ 1.26.48.
+
+## Sources
+
+| What | Where |
+|---|---|
+| Official XSD / XML template | `test/fixtures/ooyyo/OoyyoFormat.{xsd,xml}` — downloaded 13.11.2026 from the links on ooyyo.com/c=CDA31D7114F5854F111BFE6F9D671453 (d10y2oj5s0rxih.cloudfront.net/ooyyo_format/), 4,883 / 5,595 bytes = the attachments of Aleksandar Ciric's mail of 16.10.2026. sha256 xsd `58947bf2…ac07c3`, xml `08b3e74a…adefd` |
+| Importer rules (binding) | Aleksandar Ciric (OOYYO), 16.10. and 19.10.2026, quoted in ADV-331 / ADV-333 |
+| Legacy exporter | `OoyyoExporter` / `OoyyoTransformer` / `OoyyoXmlBuilder` before 1.26.48; DEV Cronicle `6.0 Export Ooyyo - part 1` (ejtpmrpb002) → `6.1 … part 2` (ejtpmsrmw03, shell `ftp put` of `autode-ooyyo.tar.gz` to the legacy Jelastic FTP) |
+
+## What the XSD does and does not enforce
+
+`<ooyyo>` = `xsd:choice minOccurs=0 maxOccurs=unbounded` of `<ad>`; `<ad>` = choice of 25 optional
+elements; all values `xsd:string`; `price`, `engine_size`, `mileage`, `power` need a `unit` attribute
+(any string). So the XSD accepts an empty file, an ad without price / photo / year, and `unit="euro"`.
+The partner's real acceptance rules are therefore implemented separately (`validateOoyyoItem`) and
+applied twice: to every item before it is written and to the finished file when it is read back
+(`verifyOoyyoXml`). The test suite re-derives the element names and required-unit list from the XSD
+file, so a schema change fails the build.
+
+## Partner acceptance rules (19.10.2026) → implementation
+
+| Rule | Implementation |
+|---|---|
+| `<price unit="EUR">` exactly; missing / other unit = rejected | builder writes `unit="EUR"`; verifier allows only `EUR` |
+| price = integer vehicle purchase price | `price.currentSalesPrice` only, whole euros; never `rate.*` (leasing) or `price.purchasePrice` (dealer cost) |
+| rejected without photo | ≥ 1 validated clean photo (ADV-336 selection: 3/4 hero first, URL check), else `no_valid_image` |
+| rejected without year | first-registration year, else stored construction year; nothing defaulted, else `no_valid_year` |
+| rejected when make / model not recognisable | empty / `SONSTIGE` / `Andere` / `selector_unknown` … → `no_make` / `no_recognisable_model` |
+| vehicle URL and picture URLs ≤ 1,500 chars, HTTPS | `url_too_long` / `no_valid_image`; all URLs `https://` |
+| partly valid file REPLACES the whole OOYYO inventory | FeedGuard (complete + fresh snapshot, min / drop vs last good, lock) + read-back verify of every ad + count equality; temp → atomic rename; blocked run keeps the last good `.xml` / `.xml.gz` and exits 1 |
+| download failure / 0 readable ads: OOYYO keeps old inventory | not relied upon — an empty file is never published (`published_too_small`) |
+| one XML at a fixed HTTPS URL, plain or gzip ending `.gz`, FTP discouraged | outputs `ooyyo.xml` + `ooyyo.xml.gz` (real gzip of the XML, round-trip checked); the legacy `autode-ooyyo.tar.gz` (tar, FTP) is no longer produced. Hosting is NOT set up |
+
+## Field mapping (source → XML)
+
+| Element | Source | Rule |
+|---|---|---|
+| `url` | `_id` | `https://www.<domain>/search/vehicle/<id>?source=ooyyo&medium=listing&campaign=listing&utm_source=ooyyo&utm_medium=listing&utm_campaign=listing` (ADV-333) |
+| `title` | `mainData.make model subModel` | German, missing parts left out (legacy prefixed `constructionYear`, also for used cars) |
+| `content` | `offer.offerDescription` | plain text: mobile.de `\\` → line break, `**` dropped; nothing added; empty → left out |
+| `price unit="EUR"` | `price.currentSalesPrice` | integer > 0 |
+| `make` / `model` / `trim` | `mainData.make` / `model` / `subModel` | as stored |
+| `engine_size unit="cc"` | `engineData.cubicCapacity` | > 0 else left out (BEV) |
+| `body_type` / `color` / `fuel_type` / `transmission` | selectors | German labels (`de` dictionary), `Außenfarbe ` prefix removed, unknown → left out |
+| `year` | `mainData.firstRegistration` / `constructionYear` | see rules |
+| `mileage unit="km"` | `mainData.mileage` | ≥ 0 (0 for new cars is real) |
+| `euronorm` | `environmentEmissions.emissionClass` | `1`…`6`, `6b`, `6c`, `6d`, `6d-TEMP` (legacy values); unknown left out (legacy wrote `default`) |
+| `power unit="kw"` | `engineData.powerKW` | > 0 |
+| `doors` / `seats` / `gears` | `mainData.doors` / `seats`, `driveSuspension.gears` | > 0 |
+| `location/city` | `location.city` | as stored |
+| `location/postcode` | `location.zipCode` | STRING; DE 4-digit → leading zero restored (`4103` → `04103`); invalid → left out |
+| `location/region` | postal code table (`DePostalCodesService`) | Bundesland of the postcode (legacy wrote the country code `DE`) |
+| `pictures/picture` | Imbo images | validated clean list, hero first, no cap (20 is a ranking recommendation), never `noimage` |
+| `vin` | `metaData.vin` | only a valid ISO 3779 VIN |
+| `is_new` | `mainData.condition` | `1` new, `0` used |
+| `date` / `time` | `metaData.creationDate` | `DD/MM/YYYY` / `HH:MM` 24 h, Europe/Berlin (legacy `hh:mm:ss`, 12 h, host TZ) |
+
+Empty optional elements are left out entirely (all are optional in the XSD); the legacy builder wrote
+`<engine_size/>` / `<power/>` without the required `unit`, which made the file schema-invalid.
+Values are CDATA-wrapped as in the template; `]]>` is split, XML-invalid control characters removed.
+
+Excluded cars (counted in `last-run-report.json.excluded`): `duplicate_id`, `filtered` (Cronicle
+rules, no images), `reserved_or_sold`, `no_valid_price`, `no_make`, `no_recognisable_model`,
+`no_valid_year`, `no_valid_image`, `url_too_long`.
+
+## Legacy DEV output (last run 09.11.2026 09:01, 1,771 ads) — defects found
+
+- `price unit="euro"` on every ad (rejected by the current importer).
+- 5,001 `…/carimage/noimage/…` placeholder pictures (the template forbids "No image available" images).
+- `region` = `DE` (country code, not a region); 415 of 3,094 DEV cars have a 4-digit postcode
+  (leading zero lost because CBD stores a number).
+- `euronorm` = `default` on 65 ads; empty `<engine_size/>` / `<power/>` without `unit` → XSD-invalid.
+- `time` as `hh:mm:ss` (12-hour clock); year invented for new cars without a year (`now - 2 months`).
+- Output directory emptied before the run (an outage published an empty / partial file); tar.gz built
+  with the external `zip` tooling.
+
+DEV dry-run results with 1.26.48: see `RUNBOOK.md` → "DEV runs".

package/docs/ooyyo/PARTNER-QUESTIONS.md

@@ -0,0 +1,32 @@
+# OOYYO — open partner questions (ADV-331 / ADV-333)
+
+Contact: Aleksandar Ciric (OOYYO). `submission@ooyyo.net` is dead. Draft only — nothing is sent from
+engineering; Marketing sends after review.
+
+Already answered (16.10. / 19.10.2026): OOYYO XML only; fixed HTTPS URL, plain or `.gz`; daily pull
+shortly after midnight; full replacement (partly valid file replaces everything, failed download / 0
+readable ads keeps the old inventory); `unit="EUR"` mandatory; photo / year / price / recognisable
+make + model mandatory; URLs ≤ 1,500 chars; UTMs allowed and kept, direct link without redirect; free
+listing has no click reporting and no click id; Featured Vehicles is a separate paid product.
+
+Open:
+
+1. Time zone of the daily pull ("shortly after midnight") — asked by Marketing on 19.10., no answer yet.
+   We need it to schedule our export so the file is fresh but never mid-write (we publish atomically).
+2. How should the 20-car test sample reach the importer for the non-live test: file attachment or a
+   temporary URL? If a URL: may it carry a secret token in the path / query (the partner mentioned an
+   optional token), and does the importer accept a self-signed / basic-auth protected URL?
+3. Retry behaviour when the URL answers 5xx / times out at the pull time: one retry later the same
+   night, or next day only? Any alerting on their side we can subscribe to?
+4. Grace period for deletions: a car missing in one file — removed immediately at that import?
+5. Make / model recognition: is there a reference list (or a report of unmatched values after the
+   test import) so we can map our values (e.g. "Mercedes-Benz", "Škoda", sub-brands) up front?
+6. Accepted values for `fuel_type`, `transmission`, `body_type`, `color`: German labels OK (we send
+   e.g. `Benzin`, `Elektro`, `Automatik`, `SUV/Geländewagen`), or English keywords preferred?
+7. `euronorm`: are our values `6`, `6d`, `6d-TEMP` OK, or `Euro 6` style?
+8. `date` / `time`: listing creation date in Europe/Berlin — correct meaning ("date of the ad")?
+9. Electric cars: is an ad without `engine_size` fine (we leave it out rather than send 0)?
+10. Crawler: User-Agent and source IPs of the feed fetcher and of any page crawler, so we can classify
+    them as automation in our traffic reporting (ADV-333) and allow-list them at Cloudflare.
+11. Does OOYYO ever request our vehicle pages itself (link checking / crawling) after the import?
+12. Rejection report after each production import (counts + reasons) — available beyond the test?

package/docs/ooyyo/RUNBOOK.md

@@ -0,0 +1,67 @@
+# OOYYO feed — runbook (ADV-331)
+
+## Parameters (Cronicle event, export-cars plugin, `exportType=ooyyo`)
+
+| Param | Default | Meaning |
+|---|---|---|
+| `String` / `Number` / `Date` | — | Cronicle filter rules (DEV 6.0: none) |
+| `ooyyoDryRun` | dry-run | only the exact text `false` makes a live run |
+| `ooyyoMaxImages` | no cut | cut the picture list (OOYYO accepts all; 20 is a ranking recommendation) |
+| `ooyyoImageConcurrency` | 16 | parallel image URL checks |
+| `feedGuardMinSourceItems` | 1000 | DEV snapshot ~3,100 cars |
+| `feedGuardMinPublishedItems` | 1 | set a real minimum from a PROD dry-run before going live |
+| `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, approved stock reduction |
+
+No new parameter is needed for a run: the defaults give a safe dry-run.
+
+## Files
+
+| Mode | Output | State |
+|---|---|---|
+| dry-run | `resources/ooyyo-dryrun/ooyyo.xml` + `ooyyo.xml.gz` | `resources/ooyyo-state/dryrun/` |
+| live | `resources/ooyyo-export/ooyyo.xml` + `ooyyo.xml.gz` | `resources/ooyyo-state/export/` |
+
+State dir: `last-good.json`, `last-run-report.json` (guard code, exclusions, verify issues, missing
+optional fields, padded postcodes, bytes + sha256, image stats), `run.lock`. A blocked run leaves
+`ooyyo.xml.rejected`; the published files and their `.prev` copies stay.
+
+## Run order inside one run
+
+source snapshot check → map + partner rules + image check per car → temp XML → read back + verify
+every ad and the count → count guard vs last good → gzip + round-trip check → rename `.xml.gz`, then
+`.xml` (both atomic) → report. Any failure: exit 1, nothing replaced.
+
+## Exit codes and the chain
+
+Blocked or failed runs exit 1, so the chained `6.1 … part 2` does not run. A dry-run exits 0 and DEV
+`6.1` then uploads `resources/ooyyo-export/autode-ooyyo.tar.gz` — the LEGACY file from 09.11.2026,
+which 1.26.48 no longer writes — to the legacy Jelastic FTP (as `autode-ooyyo-develop.tar.gz`). `6.1`
+is not changed (same decision as meinestadt `5.1`). To run 6.0 alone use the API with `chain: ""`:
+
+```
+# on the DEV Cronicle host; the key never leaves the host
+K=$(sudo -n node bin/storage-cli.js get global/api_keys/0 | node -e '…print .key…')
+curl -s -X POST 127.0.0.1:<WebServer.http_port>/api/app/run_event/v1 \
+  -d '{"api_key":"'$K'","id":"ejtpmrpb002","chain":""}'
+```
+
+## Before anything goes live (not done; each step needs explicit OK)
+
+1. Marketing approval; 20-car sample (from a PROD dry-run, not DEV data) to Aleksandar for the
+   NON-LIVE importer test; accepted / rejected counts and reasons reconciled (target: 0 rejected).
+2. Answers to `PARTNER-QUESTIONS.md` (pull time zone, retry, sample transport, value lists).
+3. Hosting: a fixed HTTPS URL serving `resources/ooyyo-export/ooyyo.xml(.gz)` read-only, optional
+   secret token kept out of logs; replace / disable `6.1` (legacy FTP, credentials in the script).
+4. Schedule the export so it finishes well before the partner's midnight pull; monitoring on
+   `last-run-report.json` (status, stale) and on the served file's age.
+5. `feedGuardMinPublishedItems` from a PROD dry-run; only then `ooyyoDryRun=false`.
+6. Stop-poll / rollback: serve the `.prev` file or an HTTP 5xx (OOYYO keeps the old inventory on a
+   failed download) — never an empty or partial file.
+7. Tracking: `web-funnel-tracking-health` ≥ 1.5.7 (CLASSIFIEDS_OOYYO) on the target Cronicle.
+
+## DEV runs
+
+(filled in after the DEV run, see below)

package/docs/ooyyo/TRACKING.md

@@ -0,0 +1,54 @@
+# OOYYO — measurement (ADV-333)
+
+Status 13.11.2026: DEV only. Implemented: the feed `<url>` scheme (export-cars 1.26.48) and the
+reporting channel `CLASSIFIEDS_OOYYO` (web-funnel-tracking-health 1.5.7). No partner click id, cost,
+postback or pixel exists for the free listing, so none is modelled.
+
+## Evidence
+
+- Partner, 19.10.2026: OOYYO links DIRECTLY to the `<url>` of the XML, no redirect, query parameters
+  (our UTMs) unchanged; URL ≤ 1,500 chars; free listing = no click reporting, no click id.
+- Historic ACF-6139 link: `?source=classifieds&medium=listing&campaign=ooyyo` (Confluence tag
+  "ooyyo [organic]"). Before 1.5.7 that resolved to generic classifieds / UTM rules — the partner
+  identity was lost, same finding as AutoUncle (ADV-324).
+- ADV-260: fe-main keeps `source/medium/campaign/utm_*` in the marketing cookie (first external
+  context wins, internal navigation does not overwrite it) and sends it with every lead.
+
+## Path
+
+```
+OOYYO result ──(direct link, no redirect)──► https://www.auto.de/search/vehicle/<car _id>
+    ?source=ooyyo&medium=listing&campaign=listing&utm_source=ooyyo&utm_medium=listing&utm_campaign=listing
+  → fe-main marketing cookie (ADV-260)        → visitor session, landing_url keeps the raw query
+  → views: reporting_channel CLASSIFIEDS_OOYYO, family Classifieds, detail OOYYO, publisher OOYYO
+    (historic source=classifieds&campaign=ooyyo resolves to the same channel)
+  → form → REQ → Odoo crm_source "ooyyo" (VDP enquiries need the user-actions-contact ADV-327 cookie
+    fallback — DEV since 13.11, not on PROD)
+  → rpt_episode_touchpoint → canonical 90-day episode (original episode_start_date) → sale / CM
+```
+
+- Legacy and utm pairs carry identical values, so fe-main's `getUtmQueryParameter` sees no
+  parameter conflict; GA4 sees `ooyyo / listing`.
+- Not PAID_*: the listing is free; it stays out of the paid click-id health rates and gets no cost.
+  Spend for OOYYO is "verified no fee" only for the free XML listing; any Featured Vehicles test needs
+  its own cost import first.
+- Reconciliation view: platform `ooyyo`, but there are no media rows → sessions only, no exact join.
+
+## Crawler / bot filtering
+
+Sessions are VISITOR / KNOWN_CRAWLER / INTERNAL by published crawler IP ranges and proven automation
+signatures (ADV-371). OOYYO publishes no ranges; its feed fetch reads the XML file only and creates
+no tracking event. No OOYYO rule is guessed — partner question 10 asks for UA / IPs; once known, add
+them as verified automation with evidence.
+
+## Not done (by design)
+
+- No `ooyyo_clickid` or similar parameter, no postback, no conversion upload.
+- No retroactive rewrite of historic `crm_source` values.
+- Customer SQL (`source_resolved_v1 = LOWER(crm_source)`) already yields `ooyyo` for the new link; the
+  historic `classifieds` + campaign `ooyyo` rows stay `classifieds` until the data owner applies the
+  classifieds-campaign rule proposed for ADV-324 / ADV-327 / ADV-330.
+
+## QA
+
+See `RUNBOOK.md` → "DEV runs" for the DEV test (link → VDP → enquiry → Odoo REQ → views).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebrand/export-cars",
-  "version": "1.26.46",
+  "version": "1.26.48",
   "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 && ts-node --transpile-only test/openai-ads-finance.test.ts && ts-node --transpile-only test/openai-ads-price-cap.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 && ts-node --transpile-only test/marktde-mapping.test.ts && ts-node --transpile-only test/marktde-feed-run.test.ts && ts-node --transpile-only test/criteo-images.test.ts && ts-node --transpile-only test/criteo-mapping.test.ts && ts-node --transpile-only test/criteo-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/openai-ads-finance.test.ts && ts-node --transpile-only test/openai-ads-price-cap.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 && ts-node --transpile-only test/mapping-csv.test.ts && ts-node --transpile-only test/marktde-mapping.test.ts && ts-node --transpile-only test/marktde-feed-run.test.ts && ts-node --transpile-only test/ooyyo-mapping.test.ts && ts-node --transpile-only test/ooyyo-feed-run.test.ts && ts-node --transpile-only test/criteo-images.test.ts && ts-node --transpile-only test/criteo-mapping.test.ts && ts-node --transpile-only test/criteo-feed-run.test.ts"
   },
   "dependencies": {
     "@bytebrand/autode-request": "^1.19.2",
@@ -34,6 +34,7 @@
     "bottleneck": "^2.19.5",
     "cache-manager": "^5.2.4",
     "csv-write-stream": "^2.0.0",
+    "fast-xml-parser": "4.2.5",
     "google-spreadsheet": "^3.3.0",
     "lodash": "^4.17.21",
     "moment": "^2.29.4",

package/src/configs/ooyyo.config.ts

@@ -1,15 +1,65 @@
-import { Params } from '../interfaces/params.interface';
-import { Config } from './config';
-import { ExportType, FileType, ImageType } from '../enums';
-
-export class OoyyoConfig extends Config {
-  constructor(params: Params) {
-    super(params);
-    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.OOYYO}-export`;
-    this.imageType = ImageType.default;
-    this.outputFiles = [
-      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.OOYYO}.${FileType.XML}`,
-      `${this.pathesConfig.localConvertedDirectory}/autode-${ExportType.OOYYO}.${FileType.TAR_GZ}`,
-    ];
-  }
-}
+import { toNumber } from 'lodash';
+
+import { ExportType, 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 (same as AutoUncle / meinestadt / markt.de). minPublishedItems only forbids an
+// empty file; before a live run set it from a PROD dry-run (see docs/ooyyo/RUNBOOK.md).
+export const OOYYO_DEFAULTS = {
+  imageConcurrency: 16,
+  minSourceItems: 1000,
+  minPublishedItems: 1,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+};
+
+/**
+ * OOYYO vehicle XML (ADV-331): one full-inventory XML + the same file gzipped (`.xml.gz`), the two
+ * forms OOYYO accepts from a fixed HTTPS URL (partner, 16.10.2026; FTP not recommended).
+ * Dry-run is the default: the files go to resources/ooyyo-dryrun, which no Cronicle step reads and
+ * nothing serves. Only ooyyoDryRun=false writes resources/ooyyo-export. The legacy
+ * autode-ooyyo.tar.gz (FTP package) is no longer produced. Each mode has its own guard state.
+ */
+export class OoyyoConfig extends Config {
+  dryRun: boolean;
+  imageConcurrency: number;
+  // 0 = no limit (OOYYO accepts all pictures; 20 is only a ranking recommendation)
+  maxImages: number;
+  stateDir: string;
+  feedGuard: FeedGuardOptions;
+
+  constructor(params: Params) {
+    super(params);
+    this.campaign = ExportType.OOYYO;
+    this.dryRun = text(params.ooyyoDryRun).toLowerCase() !== 'false';
+    const mode = this.dryRun ? 'dryrun' : 'export';
+    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.OOYYO}-${mode}`;
+    this.stateDir = `resources/${ExportType.OOYYO}-state/${mode}`;
+    this.imageType = ImageType.clean;
+    this.imageConcurrency = positiveNumber(params.ooyyoImageConcurrency, OOYYO_DEFAULTS.imageConcurrency);
+    this.maxImages = Math.floor(positiveNumber(params.ooyyoMaxImages, 0));
+    this.feedGuard = {
+      stateDir: this.stateDir,
+      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, OOYYO_DEFAULTS.minSourceItems),
+      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, OOYYO_DEFAULTS.minPublishedItems),
+      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, OOYYO_DEFAULTS.maxDropPercent),
+      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, OOYYO_DEFAULTS.maxSourceAgeHours),
+      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, OOYYO_DEFAULTS.maxStaleHours),
+      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
+    };
+    this.outputFiles = [
+      `${this.pathesConfig.localConvertedDirectory}/${ExportType.OOYYO}.xml`,
+      `${this.pathesConfig.localConvertedDirectory}/${ExportType.OOYYO}.xml.gz`,
+    ];
+  }
+}

package/src/constants/fb.constants.ts

@@ -1,34 +1,34 @@
-export const FB_MAX_TRIM_LENGTH = 50;
-export const FB_MAX_IMAGE_COUNT_FOR_DEAFULT = 47;
-export const FB_MIN_MILEAGES = 900;
-export const DEFAULT_ZIP = '06796';
-export const DEFAULT_CITY = 'Sandersdorf-Brehna';
-export const DEFAULT_ADDR1 = 'Max-Planck-Str. 19';
-export const TIMESTAMP_FIRST_YEAR = 1970;
-export const META_PUSH_PRIORITY_STANDARD = 'standard';
-export const META_PUSH_PRIORITY_ALLOWED_VALUES = ['dealer_priority_1', 'dealer_priority_2'];
-
-// MarketingImageExportConfig channel code for the Meta AIA overlay images (image-generator's
-// MetaAiaImagesService.CHANNEL_CODE) — distinct from this feed's now-disabled legacy "fb" config.
-export const META_AIA_CHANNEL_CODE = 'meta_aia';
-// Only the financing variant exists so far; leasing/other modes will be added once image-generator
-// renders them too (see MetaAiaImagesService's MetaAiaMode).
-export const META_AIA_MODE_FINANCING = 'financing';
-
-// Values must match Meta's Automotive Model Ads offer_type enum exactly (lease/finance/cash) —
-// the old 'financing'/'leasing'/'buy' values are not recognized by the AMA Vehicle Offers Feed.
-export enum OfferType {
-  financing = 'finance',
-  leasing = 'lease',
-  buy = 'cash',
-}
-
-export const AMOUNT_QUALIFIER_APR = 'APR';
-export const TERM_QUALIFIER_MONTHS = 'months';
-
-export const OFFER_DISCLAIMER = 'Für Ihre Finanzierungswünsche stellen wir eine Bonitätsanfrage. Bonität ' +
-  'vorausgesetzt, ist dies ein repräsentatives Berechnungsbeispiel gem. der Angaben, welches 2/3 aller Kunden, ' +
-  'im Sinne des § 17a Abs. 4 PAngV, erhalten. Dieses freibleibende Angebot der Openbank Deutschland AG, ' +
-  'Santander-Platz 1, 41061 Mönchengladbach wird vermittelt durch die auto.de GmbH, Max-Planck-Str. 19, 06796 ' +
-  'Sandersdorf-Brehna, die als ungebundener Vermittler nicht beratend tätig ist. Irrtümer vorbehalten. Preise ' +
-  'ggf. inkl. MwSt.';
+export const FB_MAX_TRIM_LENGTH = 50;
+export const FB_MAX_IMAGE_COUNT_FOR_DEAFULT = 47;
+export const FB_MIN_MILEAGES = 900;
+export const DEFAULT_ZIP = '06796';
+export const DEFAULT_CITY = 'Sandersdorf-Brehna';
+export const DEFAULT_ADDR1 = 'Max-Planck-Str. 19';
+export const TIMESTAMP_FIRST_YEAR = 1970;
+export const META_PUSH_PRIORITY_STANDARD = 'standard';
+export const META_PUSH_PRIORITY_ALLOWED_VALUES = ['dealer_priority_1', 'dealer_priority_2'];
+
+// MarketingImageExportConfig channel code for the Meta AIA overlay images (image-generator's
+// MetaAiaImagesService.CHANNEL_CODE) — distinct from this feed's now-disabled legacy "fb" config.
+export const META_AIA_CHANNEL_CODE = 'meta_aia';
+// Only the financing variant exists so far; leasing/other modes will be added once image-generator
+// renders them too (see MetaAiaImagesService's MetaAiaMode).
+export const META_AIA_MODE_FINANCING = 'financing';
+
+// Values must match Meta's Automotive Model Ads offer_type enum exactly (lease/finance/cash) —
+// the old 'financing'/'leasing'/'buy' values are not recognized by the AMA Vehicle Offers Feed.
+export enum OfferType {
+  financing = 'finance',
+  leasing = 'lease',
+  buy = 'cash',
+}
+
+export const AMOUNT_QUALIFIER_APR = 'APR';
+export const TERM_QUALIFIER_MONTHS = 'months';
+
+export const OFFER_DISCLAIMER = 'Für Ihre Finanzierungswünsche stellen wir eine Bonitätsanfrage. Bonität ' +
+  'vorausgesetzt, ist dies ein repräsentatives Berechnungsbeispiel gem. der Angaben, welches 2/3 aller Kunden, ' +
+  'im Sinne des § 17a Abs. 4 PAngV, erhalten. Dieses freibleibende Angebot der Openbank Deutschland AG, ' +
+  'Santander-Platz 1, 41061 Mönchengladbach wird vermittelt durch die auto.de GmbH, Max-Planck-Str. 19, 06796 ' +
+  'Sandersdorf-Brehna, die als ungebundener Vermittler nicht beratend tätig ist. Irrtümer vorbehalten. Preise ' +
+  'ggf. inkl. MwSt.';