@bytebrand/export-cars 1.26.28 → 1.26.30

package/src/exporters/openai-ads.exporter.ts

@@ -0,0 +1,93 @@
+import { Injectable } from '@nestjs/common';
+import { FsChunkInterface } from '@bytebrand/chunkable';
+import { LoggerService } from '@bytebrand/cronicle-helper';
+import { TranslatorExtended } from '@bytebrand/schema-tools';
+import { de, deVehicleDetailsPage, deVehicleProps } from '@bytebrand/i18n-dictionaries';
+
+import { CarService, ConfigService, ImagesService, LoaderService, RulesService } from '../services';
+import { ImageUrlValidator } from '../services/image-url-validator.service';
+import { FeedGuard } from '../services/feed-guard';
+import { DealerStatus, OpenAiAdsFeedRun, SourceCar } from '../services/openai-ads-feed-run';
+import { resolveOpenAiImageFields } from '../transformers/openai-image-fields';
+import { OpenAiAdsConfig } from '../configs/openai-ads.config';
+import { Exporter } from '../interfaces/exporter.interface';
+
+/**
+ * ExportType.OPENAI_ADS (ADV-335). Wires the Cronicle/Nest services into OpenAiAdsFeedRun, which
+ * holds the logic. Unlike the other exporters it never empties its output directory: the new file
+ * replaces the old one only after the fail-closed guard passed.
+ */
+@Injectable()
+export class OpenAiAdsExporter implements Exporter {
+  constructor(
+    private carService: CarService,
+    private configService: ConfigService,
+    private rulesService: RulesService,
+    private loaderService: LoaderService,
+    private imagesService: ImagesService,
+  ) { }
+
+  async export(): Promise<void> {
+    const config = this.configService.config as OpenAiAdsConfig;
+    const translator = new TranslatorExtended({ ...de, ...deVehicleProps, ...deVehicleDetailsPage });
+    const validator = new ImageUrlValidator({ concurrency: config.imageConcurrency });
+
+    const run = new OpenAiAdsFeedRun(
+      {
+        forEachChunk: fn => this.loaderService.process((chunk: FsChunkInterface) => fn(chunk.data as SourceCar[])),
+        filterCar: source => this.carService.filterCar(source, this.rulesService.rules),
+        dealerStatus: ownerId => this.dealerStatus(ownerId),
+        resolveImages: ({ car, images }) =>
+          resolveOpenAiImageFields(this.imagesService.getCleanImages(car._id, images), validator),
+        imageStats: () => validator.stats,
+        guard: new FeedGuard(config.feedGuard),
+      },
+      {
+        runId: config.runId,
+        dryRun: config.dryRun,
+        sourceDirectory: config.pathesConfig.localDirectory,
+        sourceBaseFileName: config.pathesConfig.baseFileName,
+        outputFile: config.outputFiles[0],
+        stateDir: config.stateDir,
+        retentionDays: config.retentionDays,
+        mapping: {
+          domain: config.domain,
+          sellerName: config.sellerName,
+          translate: key => translator.translateVal(key),
+        },
+      },
+    );
+
+    try {
+      const report = await run.run();
+      if (report.stale) {
+        console.log(`OpenAI ads feed STALE: last good file ${report.lastGoodAgeHours?.toFixed(1)} h old`);
+      }
+    } catch (error) {
+      // nest-commander's default serviceErrorHandler only prints a rejected run, and main.ts then
+      // reports {"complete":1,"code":0} — a blocked feed would look green in Cronicle. Fail the job
+      // here (report + lock already handled by the run).
+      LoggerService.exitError(`OpenAI ads feed not published: ${error?.message ?? error}`);
+      process.exit(1);
+    }
+  }
+
+  // One UPA lookup per dealer and run. CarService.getOwner retries 4× and does not remember
+  // failures, so without this map every car of an unknown dealer would wait for the retries again.
+  private readonly dealerStatuses = new Map<string, Promise<DealerStatus>>();
+
+  // CBD already takes blacklisted dealers' cars offline, but a deactivated dealer's cars stay
+  // online — not advertised here. A missing `active` field counts as active (only explicit false).
+  private dealerStatus(ownerId: string): Promise<DealerStatus> {
+    if (!ownerId) {
+      return Promise.resolve('unknown');
+    }
+    if (!this.dealerStatuses.has(ownerId)) {
+      this.dealerStatuses.set(ownerId, this.carService.getOwner(ownerId).then(
+        owner => (!owner ? 'unknown' : owner.active === false || owner.blacklist === true ? 'inactive' : 'active'),
+        () => 'unknown' as DealerStatus,
+      ));
+    }
+    return this.dealerStatuses.get(ownerId);
+  }
+}

package/src/formats/openai-ads-csv.builder.ts

@@ -0,0 +1,55 @@
+import { createWriteStream, WriteStream } from 'fs';
+import { once } from 'events';
+
+import { OPENAI_ADS_COLUMNS, OpenAiAdsRow } from '../interfaces/openai-ads.interface';
+
+// RFC 4180 cell: quoted only when it contains a comma, a quote, CR or LF (the OpenAI product file
+// rule); embedded quotes are doubled. Values are written as they are — callers keep free text on
+// one line, but a stray newline still stays inside its quoted cell instead of breaking the row.
+export const toCsvCell = (value: string | boolean | undefined | null): string => {
+  if (value === undefined || value === null) {
+    return '';
+  }
+  const text = typeof value === 'boolean' ? (value ? 'true' : 'false') : value;
+  return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+};
+
+export const toCsvLine = (cells: Array<string | boolean | undefined | null>): string => `${cells.map(toCsvCell).join(',')}\n`;
+
+export const openAiAdsCsvHeader = (): string => toCsvLine([...OPENAI_ADS_COLUMNS]);
+
+export const openAiAdsCsvRow = (row: OpenAiAdsRow): string => toCsvLine(OPENAI_ADS_COLUMNS.map(column => row[column]));
+
+/**
+ * OpenAI product file (OpenAI format, not the Google-compatible profile): UTF-8 without BOM, one
+ * header row, one vehicle per row, fixed column order (OPENAI_ADS_COLUMNS). Not built on
+ * XMLBuilderBase and not shared with the Awin/Santander writers, which do not escape quotes.
+ */
+export class OpenAiAdsCsvBuilder {
+  private stream: WriteStream;
+  private rows = 0;
+
+  constructor(private readonly fileName: string) { }
+
+  async buildStart(): Promise<void> {
+    this.stream = createWriteStream(this.fileName, { encoding: 'utf8' });
+    await this.write(openAiAdsCsvHeader());
+  }
+
+  async addItem(row: OpenAiAdsRow): Promise<void> {
+    await this.write(openAiAdsCsvRow(row));
+    this.rows += 1;
+  }
+
+  async buildEnd(): Promise<number> {
+    this.stream.end();
+    await once(this.stream, 'finish');
+    return this.rows;
+  }
+
+  private async write(chunk: string): Promise<void> {
+    if (!this.stream.write(chunk)) {
+      await once(this.stream, 'drain');
+    }
+  }
+}

package/src/interfaces/openai-ads.interface.ts

@@ -0,0 +1,64 @@
+// OpenAI product file, OpenAI format (developers.openai.com/commerce/specs/file-upload/products,
+// read 2026-10-09). Only the columns below are sent: no gtin/mpn/VIN (never invented), no
+// target_countries/store_country (market comes from the account setup), no Google-compatible names.
+export const OPENAI_ADS_COLUMNS = [
+  'item_id',
+  'title',
+  'description',
+  'url',
+  'brand',
+  'seller_name',
+  'image_url',
+  'additional_image_urls',
+  'availability',
+  'price',
+  'condition',
+  'is_ads_eligible',
+] as const;
+
+export type OpenAiAdsColumn = typeof OPENAI_ADS_COLUMNS[number];
+
+export type OpenAiAdsAvailability = 'in_stock' | 'out_of_stock';
+
+export type OpenAiAdsCondition = 'new' | 'used';
+
+export interface OpenAiAdsRow {
+  // canonical auto.de vehicle id (car._id, the VDP id) — same value as GA4 item_id and the
+  // Pixel/CAPI contents[].id of ADV-337
+  item_id: string;
+  title: string;
+  description: string;
+  url: string;
+  brand: string;
+  seller_name: string;
+  image_url: string;
+  // one CSV cell, comma-separated, commas inside URLs as %2C; '' = none
+  additional_image_urls: string;
+  availability: OpenAiAdsAvailability;
+  // "17990.00 EUR": purchase price in major units — never a monthly rate
+  price: string;
+  condition: OpenAiAdsCondition;
+  is_ads_eligible: boolean;
+}
+
+// Why a car of the source snapshot is not in the file as in_stock. Counted in the run report.
+export enum OpenAiAdsExclusion {
+  noId = 'no_id',
+  duplicateId = 'duplicate_id',
+  filtered = 'filtered',
+  invalidPrice = 'invalid_price',
+  noTitle = 'no_title',
+  noBrand = 'no_brand',
+  conditionUnknown = 'condition_unknown',
+  dealerInactive = 'dealer_inactive',
+  dealerUnknown = 'dealer_unknown',
+  noImage = 'no_image',
+}
+
+// Why an item is sent as out_of_stock.
+export enum OpenAiAdsOutOfStockReason {
+  reserved = 'reserved',
+  soldFlag = 'sold_flag',
+  // sent before, not in_stock in this run (sold/offline/deleted/now excluded)
+  notInSnapshot = 'not_in_snapshot',
+}

package/src/interfaces/params.interface.ts

@@ -25,6 +25,19 @@ export interface Params {
   publicationGateBqProject?: string;
   publicationGateBqDataset?: string;
   publicationGateBqTable?: string;
+  // OpenAI Ads feed only (ADV-335). Cronicle text params, so all arrive as strings; see
+  // configs/openai-ads.config.ts for defaults. Live output needs openAiAdsDryRun=false explicitly.
+  openAiAdsDryRun?: string;
+  openAiAdsSellerName?: string;
+  openAiAdsRetentionDays?: string;
+  openAiAdsImageConcurrency?: string;
+  feedGuardMinSourceItems?: string;
+  feedGuardMinPublishedItems?: string;
+  feedGuardMaxDropPercent?: string;
+  feedGuardMaxSourceAgeHours?: string;
+  feedGuardMaxStaleHours?: string;
+  // "true" for ONE run after a real stock drop the guard blocked
+  feedGuardAcceptDrop?: string;
 }
 
 // Parsed from feedItemsBq* by GoogleConfig.

package/src/services/feed-guard.ts

@@ -0,0 +1,219 @@
+import { promises as fs } from 'fs';
+import { basename, dirname, join } from 'path';
+
+/**
+ * Shared fail-closed guard for partner feed exporters (ADV-335). Opt-in per exporter; today only
+ * the OpenAI exporter uses it. Built for the 24.09 failure: base export wiped resources/cars-export,
+ * failed on the CBD outage, and every downstream feed was published empty.
+ *
+ * - checkSource: before any output is touched — the base export snapshot must exist, be complete
+ *   (chunk files cars.0..n-1 without gaps) and be fresh enough.
+ * - checkCounts: after the new file was written to a temp path — source and published counts must
+ *   not be below an absolute minimum or drop by more than maxDropPercent against the last good run.
+ *   A real stock drop is accepted by re-running once with acceptDrop.
+ * - publish: temp file -> final path by rename (same directory, atomic), previous file kept as
+ *   `<name>.prev`, last good counts written to the state dir. A blocked run leaves the last good
+ *   file in place, so the partner keeps reading it; how long that is acceptable is maxStaleHours.
+ * - lock: one run per state dir.
+ */
+export interface FeedGuardOptions {
+  // state dir of this feed (last-good.json, lock); one per export type and mode
+  stateDir: string;
+  // fail when the source snapshot has fewer cars than this
+  minSourceItems: number;
+  // fail when the published in_stock count is below this
+  minPublishedItems: number;
+  // fail when source or published count is more than this % below the last good run
+  maxDropPercent: number;
+  // fail when the newest base export chunk is older than this
+  maxSourceAgeHours: number;
+  // the last good file is reported STALE after this many hours without a successful run
+  maxStaleHours: number;
+  // one-off override for a real stock drop (Cronicle param); does not override the minimums
+  acceptDrop: boolean;
+  // a lock file older than this is treated as left over by a crashed run
+  lockStaleHours?: number;
+}
+
+export interface SourceSnapshot {
+  files: number;
+  missingChunks: number[];
+  newestMtime: Date | null;
+  oldestMtime: Date | null;
+}
+
+export interface FeedCounts {
+  sourceItems: number;
+  publishedItems: number;
+}
+
+export interface LastGood extends FeedCounts {
+  publishedAt: string;
+  file: string;
+  runId?: string;
+}
+
+export class FeedGuardError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(`[feed-guard:${code}] ${message}`);
+  }
+}
+
+const HOUR_MS = 60 * 60 * 1000;
+
+// Reads the base export snapshot: `<baseFileName>.<n>.json` chunk files (FsCarsLoader order).
+export const inspectSourceSnapshot = async (directory: string, baseFileName: string): Promise<SourceSnapshot> => {
+  let names: string[];
+  try {
+    names = await fs.readdir(directory);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return { files: 0, missingChunks: [], newestMtime: null, oldestMtime: null };
+    }
+    throw error;
+  }
+  const pattern = new RegExp(`^${baseFileName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.(\\d+)\\.json$`);
+  const chunks = names.map(name => ({ name, match: pattern.exec(name) })).filter(entry => entry.match);
+  const ids = new Set(chunks.map(entry => Number(entry.match[1])));
+  const maxId = ids.size ? Math.max(...ids) : -1;
+  const missingChunks: number[] = [];
+  for (let id = 0; id <= maxId; id += 1) {
+    if (!ids.has(id)) {
+      missingChunks.push(id);
+    }
+  }
+  let newest: number = null;
+  let oldest: number = null;
+  for (const { name } of chunks) {
+    const { mtimeMs } = await fs.stat(join(directory, name));
+    newest = newest === null ? mtimeMs : Math.max(newest, mtimeMs);
+    oldest = oldest === null ? mtimeMs : Math.min(oldest, mtimeMs);
+  }
+  return {
+    files: chunks.length,
+    missingChunks,
+    newestMtime: newest === null ? null : new Date(newest),
+    oldestMtime: oldest === null ? null : new Date(oldest),
+  };
+};
+
+const dropPercent = (current: number, previous: number): number =>
+  previous > 0 ? ((previous - current) / previous) * 100 : 0;
+
+export class FeedGuard {
+  private lockFile: string;
+
+  constructor(private readonly options: FeedGuardOptions) { }
+
+  private get lastGoodFile(): string {
+    return join(this.options.stateDir, 'last-good.json');
+  }
+
+  async readLastGood(): Promise<LastGood | null> {
+    try {
+      return JSON.parse(await fs.readFile(this.lastGoodFile, 'utf8')) as LastGood;
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async acquireLock(runId: string, now: Date): Promise<void> {
+    await fs.mkdir(this.options.stateDir, { recursive: true });
+    const lockFile = join(this.options.stateDir, 'run.lock');
+    const staleMs = (this.options.lockStaleHours ?? 6) * HOUR_MS;
+    try {
+      await fs.writeFile(lockFile, JSON.stringify({ runId, startedAt: now.toISOString() }), { flag: 'wx' });
+    } catch (error) {
+      if (error?.code !== 'EEXIST') {
+        throw error;
+      }
+      const { mtimeMs } = await fs.stat(lockFile);
+      if (now.getTime() - mtimeMs < staleMs) {
+        throw new FeedGuardError('locked', `another run holds ${lockFile} (since ${new Date(mtimeMs).toISOString()})`);
+      }
+      console.log(`feed-guard: removing stale lock ${lockFile} (${new Date(mtimeMs).toISOString()})`);
+      await fs.writeFile(lockFile, JSON.stringify({ runId, startedAt: now.toISOString() }));
+    }
+    this.lockFile = lockFile;
+  }
+
+  async releaseLock(): Promise<void> {
+    if (this.lockFile) {
+      await fs.rm(this.lockFile, { force: true });
+      this.lockFile = null;
+    }
+  }
+
+  checkSource(snapshot: SourceSnapshot, now: Date): void {
+    if (!snapshot.files) {
+      throw new FeedGuardError('source_empty', 'base export snapshot has no chunk files');
+    }
+    if (snapshot.missingChunks.length) {
+      throw new FeedGuardError('source_partial', `base export snapshot misses chunk(s) ${snapshot.missingChunks.slice(0, 10).join(', ')}`);
+    }
+    const ageHours = (now.getTime() - snapshot.newestMtime.getTime()) / HOUR_MS;
+    if (ageHours > this.options.maxSourceAgeHours) {
+      throw new FeedGuardError(
+        'source_stale',
+        `newest base export chunk is ${ageHours.toFixed(1)} h old (max ${this.options.maxSourceAgeHours} h)`,
+      );
+    }
+  }
+
+  checkCounts(counts: FeedCounts, lastGood: LastGood | null): void {
+    if (counts.sourceItems < this.options.minSourceItems) {
+      throw new FeedGuardError('source_too_small', `${counts.sourceItems} source cars < minimum ${this.options.minSourceItems}`);
+    }
+    if (counts.publishedItems < this.options.minPublishedItems) {
+      throw new FeedGuardError(
+        'published_too_small',
+        `${counts.publishedItems} in_stock items < minimum ${this.options.minPublishedItems}`,
+      );
+    }
+    if (!lastGood || this.options.acceptDrop) {
+      return;
+    }
+    const sourceDrop = dropPercent(counts.sourceItems, lastGood.sourceItems);
+    const publishedDrop = dropPercent(counts.publishedItems, lastGood.publishedItems);
+    if (sourceDrop > this.options.maxDropPercent || publishedDrop > this.options.maxDropPercent) {
+      throw new FeedGuardError(
+        'count_drop',
+        `source ${lastGood.sourceItems} -> ${counts.sourceItems} (-${sourceDrop.toFixed(1)}%), ` +
+        `in_stock ${lastGood.publishedItems} -> ${counts.publishedItems} (-${publishedDrop.toFixed(1)}%), ` +
+        `max ${this.options.maxDropPercent}% — re-run with acceptDrop if the stock really dropped`,
+      );
+    }
+  }
+
+  staleHours(lastGood: LastGood | null, now: Date): number | null {
+    return lastGood ? (now.getTime() - Date.parse(lastGood.publishedAt)) / HOUR_MS : null;
+  }
+
+  isStale(lastGood: LastGood | null, now: Date): boolean {
+    const hours = this.staleHours(lastGood, now);
+    return hours !== null && hours > this.options.maxStaleHours;
+  }
+
+  // tmpFile must sit next to finalFile so the rename stays on one filesystem (atomic).
+  async publish(tmpFile: string, finalFile: string, counts: FeedCounts, now: Date, runId?: string): Promise<LastGood> {
+    if (dirname(tmpFile) !== dirname(finalFile)) {
+      throw new Error(`feed-guard: ${basename(tmpFile)} must be in the directory of ${finalFile}`);
+    }
+    try {
+      await fs.copyFile(finalFile, `${finalFile}.prev`);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+    await fs.rename(tmpFile, finalFile);
+    const lastGood: LastGood = { ...counts, publishedAt: now.toISOString(), file: finalFile, runId };
+    await fs.mkdir(this.options.stateDir, { recursive: true });
+    await fs.writeFile(`${this.lastGoodFile}.tmp`, JSON.stringify(lastGood, null, 2), 'utf8');
+    await fs.rename(`${this.lastGoodFile}.tmp`, this.lastGoodFile);
+    return lastGood;
+  }
+}

package/src/services/image-url-validator.service.ts

@@ -0,0 +1,181 @@
+import axios, { AxiosResponse } from 'axios';
+import Bottleneck from 'bottleneck';
+
+export enum ImageUrlRejectReason {
+  invalidUrl = 'invalid_url',
+  notHttps = 'not_https',
+  credentials = 'credentials_in_url',
+  placeholder = 'placeholder',
+  httpStatus = 'http_status',
+  wrongMime = 'wrong_mime',
+  tooManyRedirects = 'too_many_redirects',
+  timeout = 'timeout',
+  networkError = 'network_error',
+  budgetExhausted = 'budget_exhausted',
+}
+
+export interface ImageUrlCheck {
+  url: string;
+  ok: boolean;
+  reason?: ImageUrlRejectReason;
+  status?: number;
+  contentType?: string;
+  finalUrl?: string;
+}
+
+export interface ImageUrlValidatorOptions {
+  // MIME types a partner is known to accept. OpenAI documents JPEG/PNG only as examples, so WebP
+  // (which our CDN negotiates for browsers) is rejected unless a partner explicitly allows it.
+  allowedMimeTypes?: string[];
+  requireHttps?: boolean;
+  timeoutMs?: number;
+  maxRedirects?: number;
+  concurrency?: number;
+  // Upper bound of HTTP probes per validator instance (one export run). Unlimited by default.
+  maxProbes?: number;
+  // e.g. the partner crawler's UA, to see what the crawler would get
+  userAgent?: string;
+}
+
+// auto.de "no image" assets (ImagesService.DEFAULT_IMAGES) — never a valid vehicle photo, and
+// images.auto.de answers them with 404 + an image/jpeg body anyway.
+const PLACEHOLDER_PATTERN = /\/carimage\/noimage\//i;
+
+/**
+ * Budgeted, cached HTTP check of image URLs before they go into a partner feed (ADV-336).
+ * HEAD first, GET (body discarded) when HEAD is not supported. A URL is valid only with a final
+ * 200 and an allowed image MIME type — images.auto.de answers unknown images with 404 AND an
+ * image/jpeg placeholder body, so the Content-Type alone proves nothing. One instance = one run:
+ * each URL is probed at most once, results and per-reason counters are kept for the run log.
+ */
+export class ImageUrlValidator {
+  private readonly options: Required<ImageUrlValidatorOptions>;
+  private readonly limiter: Bottleneck;
+  private readonly cache = new Map<string, Promise<ImageUrlCheck>>();
+  private readonly counters: Record<string, number> = {};
+  private probes = 0;
+
+  constructor(options: ImageUrlValidatorOptions = {}) {
+    this.options = {
+      allowedMimeTypes: ['image/jpeg', 'image/png'],
+      requireHttps: true,
+      timeoutMs: 5000,
+      maxRedirects: 3,
+      concurrency: 8,
+      maxProbes: Infinity,
+      userAgent: undefined,
+      ...options,
+    };
+    this.limiter = new Bottleneck({ maxConcurrent: this.options.concurrency });
+  }
+
+  validate(url: string): Promise<ImageUrlCheck> {
+    if (!this.cache.has(url)) {
+      this.cache.set(url, this.check(url).then((result) => {
+        const key = result.ok ? 'ok' : result.reason;
+        this.counters[key] = (this.counters[key] ?? 0) + 1;
+        return result;
+      }));
+    }
+    return this.cache.get(url);
+  }
+
+  validateAll(urls: string[]): Promise<ImageUrlCheck[]> {
+    return Promise.all(urls.map(url => this.validate(url)));
+  }
+
+  // Per-reason counts of the distinct URLs checked so far (cache hits are not counted twice).
+  get stats(): Record<string, number> {
+    return { ...this.counters };
+  }
+
+  private async check(url: string): Promise<ImageUrlCheck> {
+    const rejected = this.checkStatically(url);
+    if (rejected) {
+      return rejected;
+    }
+    if (this.probes >= this.options.maxProbes) {
+      return { url, ok: false, reason: ImageUrlRejectReason.budgetExhausted };
+    }
+    this.probes++;
+
+    try {
+      let response = await this.limiter.schedule(() => this.request('HEAD', url));
+      if (response.status === 405 || response.status === 501) {
+        response = await this.limiter.schedule(() => this.request('GET', url));
+      }
+      return this.checkResponse(url, response);
+    } catch (error) {
+      return { url, ok: false, reason: this.mapError(error) };
+    }
+  }
+
+  private checkStatically(url: string): ImageUrlCheck | null {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return { url, ok: false, reason: ImageUrlRejectReason.invalidUrl };
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+      return { url, ok: false, reason: ImageUrlRejectReason.invalidUrl };
+    }
+    if (this.options.requireHttps && parsed.protocol !== 'https:') {
+      return { url, ok: false, reason: ImageUrlRejectReason.notHttps };
+    }
+    if (parsed.username || parsed.password) {
+      return { url, ok: false, reason: ImageUrlRejectReason.credentials };
+    }
+    if (PLACEHOLDER_PATTERN.test(parsed.pathname)) {
+      return { url, ok: false, reason: ImageUrlRejectReason.placeholder };
+    }
+    return null;
+  }
+
+  private request(method: 'HEAD' | 'GET', url: string): Promise<AxiosResponse> {
+    return axios.request({
+      method,
+      url,
+      timeout: this.options.timeoutMs,
+      maxRedirects: this.options.maxRedirects,
+      // body is never needed — the stream is destroyed right after the headers arrive
+      responseType: 'stream',
+      headers: this.options.userAgent ? { 'User-Agent': this.options.userAgent } : undefined,
+      validateStatus: () => true,
+    }).then((response) => {
+      response.data?.destroy?.();
+      return response;
+    });
+  }
+
+  private checkResponse(url: string, response: AxiosResponse): ImageUrlCheck {
+    const status = response.status;
+    const contentType = String(response.headers?.['content-type'] ?? '').split(';')[0].trim().toLowerCase();
+    const finalUrl: string = response.request?.res?.responseUrl ?? url;
+    const result = { url, status, contentType, finalUrl };
+
+    if (status !== 200) {
+      return { ...result, ok: false, reason: ImageUrlRejectReason.httpStatus };
+    }
+    if (this.options.requireHttps && !finalUrl.startsWith('https:')) {
+      return { ...result, ok: false, reason: ImageUrlRejectReason.notHttps };
+    }
+    if (PLACEHOLDER_PATTERN.test(finalUrl)) {
+      return { ...result, ok: false, reason: ImageUrlRejectReason.placeholder };
+    }
+    if (!this.options.allowedMimeTypes.includes(contentType)) {
+      return { ...result, ok: false, reason: ImageUrlRejectReason.wrongMime };
+    }
+    return { ...result, ok: true };
+  }
+
+  private mapError(error: any): ImageUrlRejectReason {
+    if (error?.code === 'ERR_FR_TOO_MANY_REDIRECTS') {
+      return ImageUrlRejectReason.tooManyRedirects;
+    }
+    if (error?.code === 'ECONNABORTED' || error?.code === 'ETIMEDOUT' || /timeout/i.test(error?.message ?? '')) {
+      return ImageUrlRejectReason.timeout;
+    }
+    return ImageUrlRejectReason.networkError;
+  }
+}