@bytebrand/export-cars 1.26.39 → 1.26.40

package/docs/criteo/RUNBOOK.md

@@ -0,0 +1,86 @@
+# Criteo catalog feed — runbook (ADV-319)
+
+Status 06.11.2026, `@bytebrand/export-cars` 1.26.40. DEV only; PROD events `4.0` / `4.1` are disabled
+and no Criteo account, contract or importer test exists yet. Nothing here allows a live upload.
+
+## What the job does
+
+`4.0 export criteo - part 1` (`exportType=criteo`) reads the base export snapshot
+(`resources/cars-export/cars.<n>.json`) and writes the legacy Criteo RSS/XML file
+`resources/criteo-export/api_export_cars_criteo.xml`. The chained `4.1 Export criteo - part 2` uploads that
+file. Format, enums and field order are the legacy ones (decision 20.10.2026: restore as before).
+
+Per car, in this order (first match wins, counted in `excluded`):
+
+| Reason | Rule |
+|---|---|
+| `no_id` | empty `_id` |
+| `duplicate_id` | `_id` already seen in this run (first one is kept) |
+| `filtered` | shared partner filter: `metaData.imagesCount > 0` and the Cronicle rule params |
+| `reserved_or_sold` | `offer.offerAvailability` is reserved or sold (Criteo 16.10: only marketable stock) |
+| `no_valid_price` | `price.currentSalesPrice` missing, not a number or ≤ 0 |
+| `no_marketing_image` | no generated `criteo-<id>.jpg`; no noimage placeholder is ever sent |
+
+A car that went offline is not in the snapshot, so it is missing from the next full file; Criteo's next
+full import removes it. `published-ids.json` keeps the ids of the last published file, and the report
+lists `ids.added` / `ids.removed` / `ids.kept` (+ up to 20 removed ids) for each run.
+
+Item fields: `installment` and `custom_label_0` only when the car has a real rate (months and amount > 0);
+`energy_efficiency_class` only for a known WLTP class.
+
+## Fail-closed guard
+
+Shared `FeedGuard` (same as meinestadt / AutoUncle / OpenAI). The new XML is written to
+`api_export_cars_criteo.xml.tmp` and renamed over the published file only after all checks passed; the
+previous file is kept as `.prev`. A blocked run keeps the published file, moves the temp file to
+`.rejected`, and **fails the job** (Cronicle code 1), so `4.1` does not upload anything.
+
+| Code | Meaning | Action |
+|---|---|---|
+| `source_empty` | no snapshot chunk files (base export failed / wiped) | fix the base export, re-run |
+| `source_partial` | chunk files with gaps | re-run the base export |
+| `source_stale` | newest chunk older than `feedGuardMaxSourceAgeHours` (26) | base export did not run |
+| `source_too_small` | snapshot below `feedGuardMinSourceItems` (1000) | check the base export |
+| `published_too_small` | fewer items than `feedGuardMinPublishedItems` (500), e.g. all reserved/sold | check stock / images |
+| `count_drop` | source or items dropped by more than `feedGuardMaxDropPercent` (20 %) vs last good | if the stock really dropped: re-run once with `feedGuardAcceptDrop=true` |
+| `locked` | another run holds `resources/criteo-state/run.lock` (stale after 6 h) | wait / check the other job |
+
+Stale fallback: each report carries `lastGoodAgeHours`; after `feedGuardMaxStaleHours` (48) without a
+successful run, `stale: true` and the log line `criteo feed STALE`. The job itself already failed on every
+blocked run, which is the alert. Whether Criteo should then get an empty file (to stop advertising
+old stock) is an open partner question, not built.
+
+All thresholds are Cronicle params of the `4.0` event (`feedGuardMinSourceItems`,
+`feedGuardMinPublishedItems`, `feedGuardMaxDropPercent`, `feedGuardMaxSourceAgeHours`,
+`feedGuardMaxStaleHours`, `feedGuardAcceptDrop`).
+
+## Files
+
+| Path (relative to `/opt/cronicle`) | Content |
+|---|---|
+| `resources/criteo-export/api_export_cars_criteo.xml` | published file (what `4.1` uploads) |
+| `resources/criteo-export/api_export_cars_criteo.xml.prev` | file before the last publish |
+| `resources/criteo-export/api_export_cars_criteo.xml.rejected` | output of the last blocked run |
+| `resources/criteo-state/last-good.json` | counts + time of the last publish |
+| `resources/criteo-state/last-run-report.json` | report of the last run (also printed as `criteo feed report: {...}`) |
+| `resources/criteo-state/published-ids.json` | ids of the published file |
+
+Report metrics: source chunk age (`source.ageHours`), run time (`durationMs`), source cars, items,
+exclusions by reason, items with a rate, items without energy class, id changes, last good age.
+Criteo's accepted / rejected records come from the Criteo importer, not from this job.
+
+## Rollback
+
+1. Code: `sudo npm --prefix /opt/cronicle install @bytebrand/export-cars@<previous> --prefer-online`
+   (DEV before this release: 1.26.39). Only the export-cars package changes; back up
+   `/opt/cronicle/package.json` and `package-lock.json` first.
+2. File: `cp resources/criteo-export/api_export_cars_criteo.xml.prev resources/criteo-export/api_export_cars_criteo.xml`.
+3. State: `resources/criteo-state/` can be deleted; the next run then has no last good counts (no drop check
+   once) and reports all ids as added.
+
+## Tests
+
+`test/criteo-mapping.test.ts` (item mapping) and `test/criteo-feed-run.test.ts`: 20 anonymized DEV cars
+(`test/fixtures/criteo-20-cases.json`, synthetic ids, mapping fields only) plus sold, reserved, offline,
+no image, price change, invalid price, duplicate id, missing id, source outage, partial / stale snapshot,
+count drop + acceptDrop, empty stock, lock, stale last good, atomic publish. Run: `npm test`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebrand/export-cars",
-  "version": "1.26.39",
+  "version": "1.26.40",
   "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/criteo-images.test.ts && ts-node --transpile-only test/criteo-mapping.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/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",

package/src/configs/criteo.config.ts

@@ -1,17 +1,54 @@
-import { ExportType, FileType, ImageType } from 'src/enums';
-import { Params } from '../interfaces/params.interface';
-import { Config } from './config';
-
-export class CriteoConfig extends Config {
-  constructor(params: Params) {
-    super(params);
-    this.campaign = ExportType.CRITEO;
-    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.CRITEO}-export`;
-    this.imageType = ImageType.marketing;
-    this.marketingImageConfigId = this.environmentConfig[params.environment].criteoMarketingImagesConfigId;
-    this.outputFiles = [
-      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.CRITEO}.${FileType.XML}`,
-    ];
-    this.isCriteo = true;
-  }
-}
+import { toNumber } from 'lodash';
+
+import { ExportType, FileType, ImageType } from 'src/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;
+};
+
+// Same guard defaults as the meinestadt / OpenAI feeds; a job can override them via the
+// feedGuard* Cronicle params.
+export const CRITEO_DEFAULTS = {
+  minSourceItems: 1000,
+  minPublishedItems: 500,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+};
+
+/**
+ * Criteo catalog (ADV-319): legacy RSS/XML file at the same path as before, which the chained
+ * `4.1 Export criteo - part 2` step uploads. Guard state lives in resources/criteo-state.
+ */
+export class CriteoConfig extends Config {
+  stateDir: string;
+  feedGuard: FeedGuardOptions;
+
+  constructor(params: Params) {
+    super(params);
+    this.campaign = ExportType.CRITEO;
+    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.CRITEO}-export`;
+    this.stateDir = `resources/${ExportType.CRITEO}-state`;
+    this.imageType = ImageType.marketing;
+    this.marketingImageConfigId = this.environmentConfig[params.environment].criteoMarketingImagesConfigId;
+    this.feedGuard = {
+      stateDir: this.stateDir,
+      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, CRITEO_DEFAULTS.minSourceItems),
+      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, CRITEO_DEFAULTS.minPublishedItems),
+      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, CRITEO_DEFAULTS.maxDropPercent),
+      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, CRITEO_DEFAULTS.maxSourceAgeHours),
+      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, CRITEO_DEFAULTS.maxStaleHours),
+      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
+    };
+    this.outputFiles = [
+      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.CRITEO}.${FileType.XML}`,
+    ];
+    this.isCriteo = true;
+  }
+}

package/src/exporters/criteo.exporter.ts

@@ -1,51 +1,63 @@
-import { Injectable } from '@nestjs/common';
-import { ModuleRef } from '@nestjs/core';
-
-import { CronicleUtils } from '@bytebrand/cronicle-helper';
-import { FsChunkInterface } from '@bytebrand/chunkable';
-
-import { CarService, ConfigService, LoaderService, RulesService } from '../services';
-import { GoogleXmlBuilder } from '../formats/google-xml.builder';
-import { Exporter } from '../interfaces/exporter.interface';
-import { CriteoTransformer } from 'src/transformers/criteo.transformer';
-
-@Injectable()
-export class CriteoExporter implements Exporter {
-	constructor(
-		private carService: CarService,
-		private configService: ConfigService,
-		private rulesService: RulesService,
-		private loaderService: LoaderService,
-		private moduleRef: ModuleRef,
-	) { }
-
-	async export(): Promise<void> {
-		const [fileName] = this.configService.config.outputFiles;
-		await CronicleUtils.ensureDir(this.configService.config.pathesConfig.localConvertedDirectory);
-		await CronicleUtils.emptyDir(this.configService.config.pathesConfig.localConvertedDirectory);
-
-		const googleXmlBuilder = new GoogleXmlBuilder(fileName);
-		await googleXmlBuilder.buildStart(this.configService.config.domain);
-
-		const criteoTransformer = await this.moduleRef.create(CriteoTransformer);
-		let withoutImage = 0;
-
-		await this.loaderService.process(async (chunk: FsChunkInterface) => {
-			chunk.data = chunk.data.filter(car => this.carService.filterCar(car, this.rulesService.rules));
-
-			for (const data of chunk.data) {
-				const car = await criteoTransformer.transform(data);
-				if (car) {
-					await googleXmlBuilder.addItem(car);
-				} else {
-					withoutImage += 1;
-				}
-				this.carService.counter.countCar(data.images);
-			}
-		});
-
-		await googleXmlBuilder.buildEnd();
-		console.log(this.carService.counter.getCountedCars());
-		console.log(`criteo: ${withoutImage} cars skipped without a marketing image`);
-	}
-}
+import { Injectable } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+
+import { FsChunkInterface } from '@bytebrand/chunkable';
+import { LoggerService } from '@bytebrand/cronicle-helper';
+
+import { CarService, ConfigService, LoaderService, RulesService } from '../services';
+import { FeedGuard } from '../services/feed-guard';
+import { CriteoFeedRun, CriteoSourceCar } from '../services/criteo-feed-run';
+import { Exporter } from '../interfaces/exporter.interface';
+import { CriteoConfig } from '../configs/criteo.config';
+import { CriteoTransformer } from 'src/transformers/criteo.transformer';
+
+/**
+ * ExportType.CRITEO (ADV-319). Wires the Cronicle/Nest services into CriteoFeedRun, which holds the
+ * logic. The output directory is no longer emptied: the new XML replaces the old one only after the
+ * fail-closed guard passed.
+ */
+@Injectable()
+export class CriteoExporter implements Exporter {
+	constructor(
+		private carService: CarService,
+		private configService: ConfigService,
+		private rulesService: RulesService,
+		private loaderService: LoaderService,
+		private moduleRef: ModuleRef,
+	) { }
+
+	async export(): Promise<void> {
+		const config = this.configService.config as CriteoConfig;
+		const [xmlFile] = config.outputFiles;
+		const transformer = await this.moduleRef.create(CriteoTransformer);
+
+		const run = new CriteoFeedRun(
+			{
+				forEachChunk: fn => this.loaderService.process((chunk: FsChunkInterface) => fn(chunk.data as CriteoSourceCar[])),
+				filterCar: source => this.carService.filterCar(source, this.rulesService.rules),
+				transform: source => transformer.transform(source),
+				guard: new FeedGuard(config.feedGuard),
+			},
+			{
+				runId: config.runId,
+				domain: config.domain,
+				sourceDirectory: config.pathesConfig.localDirectory,
+				sourceBaseFileName: config.pathesConfig.baseFileName,
+				xmlFile,
+				stateDir: config.stateDir,
+			},
+		);
+
+		try {
+			const report = await run.run();
+			if (report.stale) {
+				console.log(`criteo feed STALE: last good file ${report.lastGoodAgeHours?.toFixed(1)} h old`);
+			}
+		} catch (error) {
+			// main.ts would report a rejected run as {"complete":1,"code":0}; fail the job so the chained
+			// upload step does not run (report + lock already handled by the run).
+			LoggerService.exitError(`criteo feed not published: ${error?.message ?? error}`);
+			process.exit(1);
+		}
+	}
+}

package/src/services/criteo-feed-run.ts

@@ -0,0 +1,253 @@
+import { promises as fs } from 'fs';
+import { dirname, join } from 'path';
+import { get, toNumber, toString } from 'lodash';
+import { ImboImageResponseInterface } from '@bytebrand/chunkable';
+import { DataSchemes } from '@bytebrand/car-schema';
+
+import { GoogleXmlBuilder } from '../formats/google-xml.builder';
+import { CriteoXmlItem } from '../interfaces';
+import { FeedGuard, FeedGuardError, LastGood, inspectSourceSnapshot } from './feed-guard';
+
+export interface CriteoSourceCar {
+  car: DataSchemes.Car;
+  images: ImboImageResponseInterface[];
+}
+
+export enum CriteoExclusion {
+  noId = 'no_id',
+  duplicateId = 'duplicate_id',
+  filtered = 'filtered',
+  notAvailable = 'reserved_or_sold',
+  noPrice = 'no_valid_price',
+  noImage = 'no_marketing_image',
+}
+
+// Online cars flagged like this are not sellable stock (same rule as the AutoUncle feed). Criteo
+// (16.10.2026): only currently marketable stock goes into the full file; a car that leaves it is
+// removed by the next full import.
+const NOT_AVAILABLE = ['selector_offerAvailability_reserved', 'selector_offerAvailability_sold'];
+
+// Everything the run needs from the outside world — the Nest exporter wires the real services,
+// tests pass fakes.
+export interface CriteoRunDeps {
+  // iterates the base export snapshot chunk by chunk (LoaderService.process)
+  forEachChunk: (fn: (cars: CriteoSourceCar[]) => Promise<void>) => Promise<unknown>;
+  // existing shared partner filter (images count, Cronicle rules)
+  filterCar: (source: CriteoSourceCar) => boolean;
+  // CriteoTransformer.transform: null = no real marketing image
+  transform: (source: CriteoSourceCar) => Promise<CriteoXmlItem | null>;
+  guard: FeedGuard;
+}
+
+export interface CriteoRunOptions {
+  runId?: string;
+  domain: string;
+  sourceDirectory: string;
+  sourceBaseFileName: string;
+  xmlFile: string;
+  stateDir: string;
+  now?: () => Date;
+}
+
+export interface CriteoRunReport {
+  runId?: string;
+  startedAt: string;
+  finishedAt?: string;
+  durationMs?: number;
+  status: 'published' | 'blocked' | 'failed';
+  guard?: { code: string; message: string };
+  error?: string;
+  xmlFile: string;
+  source: { files: number; newestChunkAt: string | null; ageHours: number | null; cars: number };
+  items: number;
+  excluded: Record<string, number>;
+  withRate: number;
+  withoutEnergyClass: number;
+  // against the ids of the last published file; removed ids are dropped by Criteo's next full import
+  ids: { added: number; removed: number; kept: number; removedSample: string[] } | null;
+  lastGood: LastGood | null;
+  lastGoodAgeHours: number | null;
+  stale: boolean;
+}
+
+const HOUR_MS = 60 * 60 * 1000;
+const PRICE = /^\d+(\.\d+)? EUR$/;
+
+const increment = (counter: Record<string, number>, key: string) => {
+  counter[key] = (counter[key] ?? 0) + 1;
+};
+
+/**
+ * One Criteo catalog run (ADV-319): source check -> map -> temp XML -> count check -> atomic
+ * publish -> report. Nothing outside the output directory and `stateDir` is written. A blocked run
+ * leaves the last good XML in place and fails the job, so the chained upload step does not run.
+ * The XML format, enums and field order stay the legacy Criteo ones.
+ */
+export class CriteoFeedRun {
+  constructor(private readonly deps: CriteoRunDeps, private readonly options: CriteoRunOptions) { }
+
+  private now(): Date {
+    return this.options.now ? this.options.now() : new Date();
+  }
+
+  private get idsFile(): string {
+    return join(this.options.stateDir, 'published-ids.json');
+  }
+
+  async run(): Promise<CriteoRunReport> {
+    const { guard } = this.deps;
+    const { xmlFile, runId } = this.options;
+    const startedAt = this.now();
+    const lastGood = await guard.readLastGood();
+    const report: CriteoRunReport = {
+      runId,
+      startedAt: startedAt.toISOString(),
+      status: 'failed',
+      xmlFile,
+      source: { files: 0, newestChunkAt: null, ageHours: null, cars: 0 },
+      items: 0,
+      excluded: {},
+      withRate: 0,
+      withoutEnergyClass: 0,
+      ids: null,
+      lastGood,
+      lastGoodAgeHours: guard.staleHours(lastGood, startedAt),
+      stale: guard.isStale(lastGood, startedAt),
+    };
+
+    await guard.acquireLock(runId ?? 'local', startedAt);
+    const tmpFile = `${xmlFile}.tmp`;
+    try {
+      const snapshot = await inspectSourceSnapshot(this.options.sourceDirectory, this.options.sourceBaseFileName);
+      report.source.files = snapshot.files;
+      report.source.newestChunkAt = snapshot.newestMtime?.toISOString() ?? null;
+      report.source.ageHours = snapshot.newestMtime
+        ? Number(((startedAt.getTime() - snapshot.newestMtime.getTime()) / HOUR_MS).toFixed(2))
+        : null;
+      guard.checkSource(snapshot, startedAt);
+
+      await fs.mkdir(dirname(xmlFile), { recursive: true });
+      // the builder appends — never onto a leftover temp file
+      await fs.rm(tmpFile, { force: true });
+      const builder = new GoogleXmlBuilder(tmpFile);
+      await builder.buildStart(this.options.domain);
+
+      const seen = new Set<string>();
+      const published: string[] = [];
+      await this.deps.forEachChunk(async (cars) => {
+        for (const source of cars) {
+          report.source.cars += 1;
+          const reason = this.exclusion(source, seen);
+          if (reason) {
+            increment(report.excluded, reason);
+            continue;
+          }
+          const item = await this.deps.transform(source);
+          if (!item) {
+            increment(report.excluded, CriteoExclusion.noImage);
+            continue;
+          }
+          // the transformer formats the price; a value it could not format is not sent
+          if (!PRICE.test(item.price) || !PRICE.test(item.sale_price)) {
+            increment(report.excluded, CriteoExclusion.noPrice);
+            continue;
+          }
+          await builder.addItem(item);
+          published.push(item.id);
+          report.items += 1;
+          if (item.installment) {
+            report.withRate += 1;
+          }
+          if (!item.energy_efficiency_class) {
+            report.withoutEnergyClass += 1;
+          }
+        }
+      });
+      await builder.buildEnd();
+
+      const counts = { sourceItems: report.source.cars, publishedItems: report.items };
+      guard.checkCounts(counts, lastGood);
+
+      const previousIds = await this.readPublishedIds();
+      report.lastGood = await guard.publish(tmpFile, xmlFile, counts, this.now(), runId);
+      await this.writePublishedIds(published);
+      report.ids = this.diffIds(previousIds, published);
+      report.status = 'published';
+      report.lastGoodAgeHours = 0;
+      report.stale = false;
+      return report;
+    } catch (error) {
+      if (error instanceof FeedGuardError) {
+        report.status = 'blocked';
+        report.guard = { code: error.code, message: error.message };
+      } else {
+        report.error = error?.message ?? String(error);
+      }
+      // keep the rejected file for inspection; the published file stays untouched
+      await fs.rename(tmpFile, `${xmlFile}.rejected`).catch(() => undefined);
+      throw error;
+    } finally {
+      await this.writeReport(report, startedAt);
+      await guard.releaseLock();
+    }
+  }
+
+  private exclusion(source: CriteoSourceCar, seen: Set<string>): CriteoExclusion | null {
+    const id = toString(get(source, 'car._id', ''));
+    if (!id) {
+      return CriteoExclusion.noId;
+    }
+    if (seen.has(id)) {
+      return CriteoExclusion.duplicateId;
+    }
+    seen.add(id);
+    if (!this.deps.filterCar(source)) {
+      return CriteoExclusion.filtered;
+    }
+    if (NOT_AVAILABLE.includes(toString(get(source.car, 'offer.offerAvailability', '')))) {
+      return CriteoExclusion.notAvailable;
+    }
+    const price = toNumber(get(source.car, 'price.currentSalesPrice', null));
+    if (!Number.isFinite(price) || price <= 0) {
+      return CriteoExclusion.noPrice;
+    }
+    return null;
+  }
+
+  private async readPublishedIds(): Promise<string[] | null> {
+    try {
+      return JSON.parse(await fs.readFile(this.idsFile, 'utf8')) as string[];
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  private async writePublishedIds(ids: string[]): Promise<void> {
+    await fs.mkdir(this.options.stateDir, { recursive: true });
+    await fs.writeFile(`${this.idsFile}.tmp`, JSON.stringify(ids), 'utf8');
+    await fs.rename(`${this.idsFile}.tmp`, this.idsFile);
+  }
+
+  private diffIds(previous: string[] | null, current: string[]): CriteoRunReport['ids'] {
+    if (!previous) {
+      return { added: current.length, removed: 0, kept: 0, removedSample: [] };
+    }
+    const before = new Set(previous);
+    const now = new Set(current);
+    const removed = previous.filter(id => !now.has(id));
+    const kept = current.filter(id => before.has(id)).length;
+    return { added: current.length - kept, removed: removed.length, kept, removedSample: removed.slice(0, 20) };
+  }
+
+  private async writeReport(report: CriteoRunReport, startedAt: Date): Promise<void> {
+    const finishedAt = this.now();
+    report.finishedAt = finishedAt.toISOString();
+    report.durationMs = finishedAt.getTime() - startedAt.getTime();
+    await fs.mkdir(this.options.stateDir, { recursive: true });
+    await fs.writeFile(join(this.options.stateDir, 'last-run-report.json'), JSON.stringify(report, null, 2), 'utf8');
+    console.log(`criteo feed report: ${JSON.stringify(report)}`);
+  }
+}