@bytebrand/export-cars 1.26.31 → 1.26.32

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

@@ -0,0 +1,240 @@
+import { promises as fs } from 'fs';
+import { dirname, join } from 'path';
+import { ImboImageResponseInterface } from '@bytebrand/chunkable';
+import { DataSchemes } from '@bytebrand/car-schema';
+
+import { MeinstadtJsonBuilder } from '../formats/meinstadt-json.builder';
+import { MeinstadtJsonItem } from '../interfaces';
+import { mapMeinstadtItem } from '../transformers/meinstadt.transformer';
+import { FeedGuard, FeedGuardError, LastGood, inspectSourceSnapshot } from './feed-guard';
+
+export interface MeinstadtSourceCar {
+  car: DataSchemes.Car;
+  images: ImboImageResponseInterface[];
+}
+
+export enum MeinstadtExclusion {
+  duplicateId = 'duplicate_id',
+  filtered = 'filtered',
+  noVehicleId = 'no_vehicle_id',
+  noImage = 'no_valid_image',
+}
+
+export class MeinstadtConfigError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(`[meinstadt:${code}] ${message}`);
+  }
+}
+
+// Everything the run needs from the outside world — the Nest exporter wires the real services,
+// tests pass fakes.
+export interface MeinstadtRunDeps {
+  // iterates the base export snapshot chunk by chunk (LoaderService.process)
+  forEachChunk: (fn: (cars: MeinstadtSourceCar[]) => Promise<void>) => Promise<unknown>;
+  // existing shared partner filter (images count, Cronicle rules)
+  filterCar: (source: MeinstadtSourceCar) => boolean;
+  // final validated image URLs for the car, hero first; [] = no usable image
+  resolveImages: (source: MeinstadtSourceCar) => Promise<string[]>;
+  imageStats: () => Record<string, number>;
+  equipment: (car: DataSchemes.Car) => Promise<string>;
+  // packs jsonFile into zipFile (entry name = basename of jsonFile)
+  zip: (jsonFile: string, zipFile: string) => Promise<void>;
+  guard: FeedGuard;
+}
+
+export interface MeinstadtRunOptions {
+  runId?: string;
+  dryRun: boolean;
+  cpc: string | null;
+  domain: string;
+  sourceDirectory: string;
+  sourceBaseFileName: string;
+  jsonFile: string;
+  zipFile: string;
+  stateDir: string;
+  translate?: (key: string) => string | undefined;
+  now?: () => Date;
+}
+
+export interface MeinstadtRunReport {
+  runId?: string;
+  mode: 'dry-run' | 'live';
+  startedAt: string;
+  finishedAt?: string;
+  status: 'published' | 'blocked' | 'failed';
+  guard?: { code: string; message: string };
+  error?: string;
+  cpc: string | null;
+  jsonFile: string;
+  zipFile: string;
+  source: { files: number; newestChunkAt: string | null; cars: number };
+  items: number;
+  excluded: Record<string, number>;
+  accidentFree: Record<string, number>;
+  imagesPerItem: { min: number | null; max: number | null; total: number };
+  images: Record<string, number>;
+  lastGood: LastGood | null;
+  lastGoodAgeHours: number | null;
+  stale: boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const AdmZip = require('adm-zip');
+
+/**
+ * Packs one file into a new ZIP, entry name = the file's basename. In-process (adm-zip, the same
+ * library @bytebrand/zipper uses for unzipping): Zipper.zip shells out to the `zip` binary, which
+ * the DEV Cronicle host does not have (13.10.2026: only unzip).
+ */
+export const zipSingleFile = async (file: string, zipFile: string): Promise<void> => {
+  const archive = new AdmZip();
+  archive.addLocalFile(file);
+  archive.writeZip(zipFile);
+};
+
+const increment = (counter: Record<string, number>, key: string) => {
+  counter[key] = (counter[key] ?? 0) + 1;
+};
+
+/**
+ * One meinestadt feed run (ADV-325/326): config check -> source check -> map + validated images ->
+ * temp JSON -> count check -> atomic publish of the JSON -> ZIP of the published JSON -> report.
+ * Nothing outside the output directory and `stateDir` is written; a blocked run leaves the last
+ * good JSON/ZIP in place. The Cronicle upload step only ever reads the published files.
+ */
+export class MeinstadtFeedRun {
+  constructor(private readonly deps: MeinstadtRunDeps, private readonly options: MeinstadtRunOptions) { }
+
+  private now(): Date {
+    return this.options.now ? this.options.now() : new Date();
+  }
+
+  async run(): Promise<MeinstadtRunReport> {
+    const { guard } = this.deps;
+    const { jsonFile, zipFile, stateDir, runId, dryRun, cpc } = this.options;
+    const startedAt = this.now();
+    const lastGood = await guard.readLastGood();
+    const report: MeinstadtRunReport = {
+      runId,
+      mode: dryRun ? 'dry-run' : 'live',
+      startedAt: startedAt.toISOString(),
+      status: 'failed',
+      cpc,
+      jsonFile,
+      zipFile,
+      source: { files: 0, newestChunkAt: null, cars: 0 },
+      items: 0,
+      excluded: {},
+      accidentFree: {},
+      imagesPerItem: { min: null, max: null, total: 0 },
+      images: {},
+      lastGood,
+      lastGoodAgeHours: guard.staleHours(lastGood, startedAt),
+      stale: guard.isStale(lastGood, startedAt),
+    };
+
+    // A live feed without a tariff is a configuration error, not a 0 / historical 0.08 bid.
+    if (!dryRun && !cpc) {
+      report.error = 'cpc_missing';
+      await this.writeReport(report);
+      throw new MeinstadtConfigError('cpc_missing', 'live meinestadt feed needs a configured cpc (positive decimal, e.g. "0.99")');
+    }
+
+    await guard.acquireLock(runId ?? 'local', startedAt);
+    const tmpFile = `${jsonFile}.tmp`;
+    try {
+      const snapshot = await inspectSourceSnapshot(this.options.sourceDirectory, this.options.sourceBaseFileName);
+      report.source.files = snapshot.files;
+      report.source.newestChunkAt = snapshot.newestMtime?.toISOString() ?? null;
+      guard.checkSource(snapshot, startedAt);
+
+      await fs.mkdir(dirname(jsonFile), { recursive: true });
+      // the builder appends — never onto a leftover temp file
+      await fs.rm(tmpFile, { force: true });
+      const builder = new MeinstadtJsonBuilder(tmpFile);
+      await builder.buildStart();
+
+      const seen = new Set<string>();
+      let first = true;
+      await this.deps.forEachChunk(async (cars) => {
+        for (const source of cars) {
+          report.source.cars += 1;
+          const id = String(source?.car?._id ?? '');
+          if (id && seen.has(id)) {
+            increment(report.excluded, MeinstadtExclusion.duplicateId);
+            continue;
+          }
+          seen.add(id);
+          if (!this.deps.filterCar(source)) {
+            increment(report.excluded, MeinstadtExclusion.filtered);
+            continue;
+          }
+          if (!source.car?.metaData?.vehicleId) {
+            increment(report.excluded, MeinstadtExclusion.noVehicleId);
+            continue;
+          }
+          const images = await this.deps.resolveImages(source);
+          if (!images.length) {
+            increment(report.excluded, MeinstadtExclusion.noImage);
+            continue;
+          }
+          const item = mapMeinstadtItem(source.car, {
+            domain: this.options.domain,
+            cpc,
+            equipment: await this.deps.equipment(source.car),
+            images,
+            translate: this.options.translate,
+          });
+          await builder.addItem(item, first);
+          first = false;
+          this.count(report, item);
+        }
+      });
+      await builder.buildEnd();
+      report.images = this.deps.imageStats();
+
+      const counts = { sourceItems: report.source.cars, publishedItems: report.items };
+      guard.checkCounts(counts, lastGood);
+
+      report.lastGood = await guard.publish(tmpFile, jsonFile, counts, this.now(), runId);
+      const zipTmp = zipFile.replace(/\.zip$/, '.tmp.zip');
+      await fs.rm(zipTmp, { force: true });
+      await this.deps.zip(jsonFile, zipTmp);
+      await fs.rename(zipTmp, zipFile);
+      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 files stay untouched
+      await fs.rename(tmpFile, `${jsonFile}.rejected`).catch(() => undefined);
+      throw error;
+    } finally {
+      await this.writeReport(report);
+      await guard.releaseLock();
+    }
+  }
+
+  private count(report: MeinstadtRunReport, item: MeinstadtJsonItem): void {
+    report.items += 1;
+    increment(report.accidentFree, String(item.accidentFree));
+    const n = item.images.length;
+    const stats = report.imagesPerItem;
+    stats.min = stats.min === null ? n : Math.min(stats.min, n);
+    stats.max = stats.max === null ? n : Math.max(stats.max, n);
+    stats.total += n;
+  }
+
+  private async writeReport(report: MeinstadtRunReport): Promise<void> {
+    report.finishedAt = this.now().toISOString();
+    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(`meinestadt feed report: ${JSON.stringify(report)}`);
+  }
+}