Skip to content

armgit / fli

Public Imported from GitHub
0

Google Flights MCP, CLI and Python Library

32.2 KB
Raw Blame
/**
 * Date-based flight search — the cheapest price for each date in a range.
 *
 * Google's `GetCalendarGraph` RPC used to hand back a whole date grid in
 * one call, but it now requires a browser-signed
 * `x-goog-batchexecute-bgr` header (see `tfs.ts`). The public search page
 * has no such grid, so each date costs its own page fetch. Those run
 * concurrently under the shared rate limiter, and the range is capped —
 * see {@link MAX_DATES_PER_SEARCH}.
 *
 * 1:1 port of fli/search/dates.py.
 */

import { formatIsoDate, parseIsoDate } from "../core/dates.ts";
import type { FlightResult, PassengerInfo } from "../models/google-flights/base.ts";
import { TripType } from "../models/google-flights/base.ts";
import type { DateSearchFilters } from "../models/google-flights/dates.ts";
import { type Client, getClient } from "./client.ts";
import { cloneFilters } from "./clone.ts";
import { parallelMap, throwIfAborted } from "./concurrency.ts";
import { parseFlightRow } from "./decoders.ts";
import { SearchClientError, SearchParseError } from "./exceptions.ts";
import { getSearchLogger } from "./logging.ts";
import {
  applyClientSideFilters,
  buildTfs,
  fetchPayload,
  pageUrl,
  unsupportedFilters,
} from "./tfs.ts";

const MAX_DAYS_PER_SEARCH = 61;
const DAY_MS = 24 * 60 * 60 * 1000;

/**
 * Same wording the flight path uses for the same condition, so a caller
 * who sees it on either path gets the same hint about what to check.
 *
 * Exported (mirroring the Python module's `_NO_PAYLOAD`, importable despite
 * the underscore) so tests can build `DateOutcome`s that exercise the
 * no-payload branch of {@link SearchDates._collect} exactly.
 */
export const NO_PAYLOAD =
  "the search page carried no ds:1 payload — Google may have changed the " +
  "page shape, or served a consent/blocked page instead";

/**
 * Same wording `flights.ts` uses for the same condition — see
 * {@link SPARSE_PASSENGER_MIX_WARNING} there for the live JFK-LHR / SFO-NRT
 * row counts behind it. Duplicated rather than imported so this module's
 * empty-result path stays self-contained.
 */
export const SPARSE_PASSENGER_MIX_WARNING =
  "No itineraries were inlined for this passenger mix. Google's search page " +
  "prices parties with children or infants client-side, so it often carries " +
  "few or no rows for them — most of all in premium cabins. This does not " +
  "mean the route has no flights: an adults-only search shows the schedule.";

/**
 * Whether the party includes anyone Google prices client-side.
 *
 * Extra adults ride the request for free; children and infants (lap or
 * seat) are the passenger types that make the search-page transport inline
 * fewer — sometimes zero — rows. See {@link SPARSE_PASSENGER_MIX_WARNING}.
 */
function hasChildrenOrInfants(passengerInfo: PassengerInfo): boolean {
  return passengerInfo.children + passengerInfo.infants_on_lap + passengerInfo.infants_in_seat > 0;
}

/**
 * Most dates a single {@link SearchDates.search} call will price.
 *
 * The public search page carries no calendar grid, so every date in the
 * range costs its own full page fetch (~2 MB). Ninety-three days is a
 * whole quarter — comfortably wider than the 61-day chunk size — and caps
 * one search at roughly 190 MB of transfer rather than letting a
 * "2026-01-01 to 2026-12-31" request quietly issue 365 requests.
 */
export const MAX_DATES_PER_SEARCH = 93;

/**
 * Payload-less pages, before any success, that abandon a sweep.
 *
 * Retries multiply. The client retries a request three times, and
 * `fetchPayload` fetches a page up to three times, so one date can cost
 * nine HTTP requests before it gives up — and a client that is being
 * blocked (an EU/EEA IP with the consent cookie disabled, say) fails that
 * way on *every* date. Paying it 93 times to learn one fact is the wrong
 * trade.
 *
 * Only the payload-less page counts. That failure is deterministic: a
 * consent or block page is served to every request alike, so the dates
 * not yet tried will fail the same way. A connection error or timeout
 * says nothing about them, so counting those would abandon a healthy
 * sweep over a transient wobble.
 *
 * The breaker also only looks at the start of a sweep: it arms while no
 * date has produced a usable page, and disarms permanently the moment one
 * does. A working sweep therefore keeps the full retry budget for every
 * transient miss in it.
 */
export const SWEEP_FAILURE_THRESHOLD = 5;

/**
 * Tracks whether a sweep is failing the one way that is worth quitting
 * over.
 *
 * One instance per sweep, never module-global: two concurrent sweeps must
 * not be able to trip each other's breaker. JavaScript runs the date
 * workers on one thread, so unlike the Python original this needs no
 * lock — but the counter is still shared by every in-flight promise in
 * the sweep, which is the point.
 */
class SweepHealth {
  private blocked = 0;
  private anySuccess = false;
  private skippedCount = 0;

  constructor(private readonly threshold: number) {}

  /** Note a date whose page arrived; disarms the breaker for good. */
  recordSuccess(): void {
    this.anySuccess = true;
  }

  /**
   * Note a date whose page arrived without a `ds:1` payload.
   *
   * Only this failure mode counts towards the threshold — see
   * {@link SWEEP_FAILURE_THRESHOLD} for why a network error deliberately
   * does not.
   */
  recordBlocked(): void {
    this.blocked++;
  }

  /** Note a date abandoned because the breaker had already tripped. */
  recordSkip(): void {
    this.skippedCount++;
  }

  /** How many dates were abandoned without being requested. */
  get skipped(): number {
    return this.skippedCount;
  }

  /** Has the sweep only ever been blocked, and enough times? */
  shouldStop(): boolean {
    return !this.anySuccess && this.blocked >= this.threshold;
  }
}

export interface DatePrice {
  /** Single date for one-way searches, or `[outbound, return]` for round trip. */
  date: [Date] | [Date, Date];
  price: number;
  currency: string | null;
}

export interface DateSearchOptions {
  currency?: string | null;
  language?: string | null;
  country?: string | null;
  /**
   * Cancels the sweep. A 93-date range is up to 93 page fetches with
   * backoffs between their retries; this reaches every one of them,
   * sleeps included.
   */
  signal?: AbortSignal;
}

/**
 * What pricing one date produced.
 *
 * Richer than a bare `DatePrice | null` so the caller can tell "this date
 * had no flights" apart from "this date never loaded". Exported for
 * {@link SearchDates._collect}, which tests drive directly because the
 * interesting states (a tripped breaker alongside real prices) depend on
 * how the sweep's concurrent fetches happen to interleave.
 */
export interface DateOutcome {
  /** The cheapest itinerary for the date, or null when skipped/failed/empty. */
  price: DatePrice | null;
  /** Human-readable reason the date could not be priced, or null. */
  failure: string | null;
  /** The error behind `failure`, kept for chaining. */
  error: unknown;
  /** False for dates skipped before any request, so they don't count as failures. */
  attempted: boolean;
  /**
   * How many rows the page decoded to *before* `applyClientSideFilters` ran,
   * or `null`/absent when the page never loaded (`failure` is set) or the
   * outcome was built by hand. Zero here means Google itself inlined
   * nothing for the date; a positive count that still left `price` unset
   * means the caller's own airline/price/duration/window filter removed
   * every row — a different cause, so the two must not be conflated when
   * deciding whether to blame a sparse passenger mix. Optional so existing
   * hand-built ``DateOutcome`` literals (test fixtures predating this field)
   * still type-check; an absent value reads the same as `null`.
   */
  rowsBeforeFilters?: number | null;
}

function outcome(over: Partial<DateOutcome> = {}): DateOutcome {
  return {
    price: null,
    failure: null,
    error: null,
    attempted: true,
    rowsBeforeFilters: null,
    ...over,
  };
}

/** Midnight UTC today. */
function todayUtc(): Date {
  const now = new Date();
  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
}

/**
 * The earliest date that is still "today" somewhere on Earth.
 *
 * Real UTC offsets span UTC-12 to UTC+14, so any traveller's local date
 * is within one day of the UTC date. Anchoring to `utcToday - 1` never
 * skips a date that is still today-or-future for the actual traveller;
 * the cost is that a genuinely past date may reach Google, which simply
 * returns no flights. Mirrors `earliest_searchable_date()` in the Python
 * models.
 */
function earliestSearchableDate(): Date {
  return new Date(todayUtc().getTime() - DAY_MS);
}

/**
 * Decode every flight row in a `ds:1` payload.
 *
 * Total by construction: a payload whose `[2]` / `[3]` slots are absent,
 * empty, or not the nested list we expect yields no flights instead of an
 * error that would abort the whole sweep. Individual unparseable rows are
 * skipped the same way the flight search skips them.
 */
function flightsIn(payload: unknown): FlightResult[] {
  const flights: FlightResult[] = [];
  if (!Array.isArray(payload)) return flights;
  for (const index of [2, 3]) {
    const block = index < payload.length ? payload[index] : null;
    if (!Array.isArray(block) || block.length === 0) continue;
    const rows = block[0];
    if (!Array.isArray(rows)) continue;
    for (const row of rows) {
      if (!Array.isArray(row)) continue;
      try {
        flights.push(parseFlightRow(row));
      } catch {
        // One bad row must not cost the whole date.
      }
    }
  }
  return flights;
}

/**
 * Up to 3 distinct failure messages, in the order they were first seen.
 *
 * Shared by every `_collect` branch that raises or warns about failed
 * dates, so the same range always gets the same short list however it is
 * reported.
 */
function reasonsFor(failed: DateOutcome[]): string[] {
  const reasons: string[] = [];
  for (const o of failed) {
    if (o.failure != null && !reasons.includes(o.failure) && reasons.length < 3) {
      reasons.push(o.failure);
    }
  }
  return reasons;
}

export class SearchDates {
  /**
   * @deprecated Kept only so the exported surface does not move. The
   * sweep no longer POSTs here: `GetCalendarGraph` requires a
   * browser-signed `x-goog-batchexecute-bgr` header and answers every
   * other client with error 13. Each date is priced from its own
   * `/travel/flights` page instead.
   */
  static readonly BASE_URL =
    "https://www.google.com/_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetCalendarGraph";

  /** Range size at which the sweep splits into independent chunk filters. */
  static readonly MAX_DAYS_PER_SEARCH = MAX_DAYS_PER_SEARCH;

  /** Most dates one `search` call will price. See {@link MAX_DATES_PER_SEARCH}. */
  static readonly MAX_DATES_PER_SEARCH = MAX_DATES_PER_SEARCH;

  private readonly client: Client;
  private _sparsePassengerMix = false;

  constructor(client?: Client) {
    this.client = client ?? getClient();
  }

  /**
   * Whether the sparse-passenger-mix warning fired on the most recent `search()`.
   *
   * `true` exactly when the empty sweep this instance last returned (or
   * threw out of) was consistent with Google's client-side pricing gap for
   * children/infants rather than the caller's own filters — see
   * {@link SearchDates._warnIfSparsePassengerMix}. Reset to `false` at the
   * start of every `search()` call, including ones that throw, so a stale
   * `true` from an earlier call never leaks into a later one.
   *
   * Reflects only the *last completed* `search()` call on this instance and
   * is not meant for instances shared across concurrent searches. Not
   * currently read by any caller in this package (unlike
   * {@link SearchFlights.sparsePassengerMix}); exposed here for symmetry
   * with the warning this class already logs.
   */
  get sparsePassengerMix(): boolean {
    return this._sparsePassengerMix;
  }

  /**
   * Price every date in the filters' range.
   *
   * Every date costs its own search-page fetch — the page serves no
   * calendar grid — so the range is capped at
   * {@link MAX_DATES_PER_SEARCH} dates. Internally it is still split into
   * {@link MAX_DAYS_PER_SEARCH}-day chunk filters, but all dates are
   * priced by a single flat parallel map.
   *
   * @returns One entry per date that could be priced, or `null` when no
   *   date in the range had flights.
   * @throws {RangeError} The range covers more than
   *   {@link MAX_DATES_PER_SEARCH} dates.
   * @throws {SearchParseError} Every date came back without a payload —
   *   a consent or block page, not an empty route.
   * @throws {SearchClientError} Every date failed for some other reason,
   *   or nothing priced because at least half the attempted dates never
   *   loaded — see {@link SearchDates._collect}.
   */
  async search(
    filters: DateSearchFilters,
    options: DateSearchOptions = {},
  ): Promise<DatePrice[] | null> {
    // Reset before anything below can throw, so a search that throws never
    // leaves a stale true from an earlier call on this instance.
    this._sparsePassengerMix = false;

    throwIfAborted(options.signal);

    const dropped = unsupportedFilters(filters);
    if (dropped.length > 0) {
      getSearchLogger().warn(
        `Filters not supported by the search-page transport, ignored: ${dropped.join(", ")}`,
      );
    }

    const fromDate = parseIsoDate(filters.from_date);
    const toDate = parseIsoDate(filters.to_date);

    // Build every chunk descriptor up front so the per-date requests
    // share no mutable state.
    const tasks: Array<[DateSearchFilters, Date]> = [];
    for (const chunk of this._buildChunkFilters(filters, fromDate, toDate)) {
      for (const day of SearchDates._daysIn(chunk)) tasks.push([chunk, day]);
    }

    if (tasks.length > MAX_DATES_PER_SEARCH) {
      throw new RangeError(
        `This date search covers ${tasks.length} dates, above the ` +
          `${MAX_DATES_PER_SEARCH}-date limit. Google's search page serves no ` +
          "calendar grid, so every date costs its own full page fetch. " +
          "Narrow the range (or run several smaller searches).",
      );
    }

    // One flat map over every date. `health` is the sweep's circuit
    // breaker: a client that is being blocked fails identically on every
    // date, and each failed date costs up to nine HTTP requests once the
    // client's retries and the page retry multiply. Queued dates check it
    // before spending anything.
    const health = new SweepHealth(SWEEP_FAILURE_THRESHOLD);
    const outcomes = await parallelMap(
      ([chunk, day]: [DateSearchFilters, Date]) => this._priceOneDate(chunk, day, options, health),
      tasks,
    );

    // A cancelled sweep rejects; it never hands back the dates it happened
    // to finish first. A truncated list of prices is indistinguishable
    // from a complete one at the call site, so returning it would turn a
    // cancellation into a wrong answer — and `_collect` would otherwise
    // describe the cancelled dates as a blocked or failed sweep, which is
    // not what happened.
    throwIfAborted(options.signal);

    const result = SearchDates._collect(outcomes, tasks.length, health.skipped);
    this._sparsePassengerMix = SearchDates._warnIfSparsePassengerMix(
      outcomes,
      result,
      filters.passenger_info,
    );
    return result;
  }

  /**
   * Warn once when an empty sweep may be Google's pricing gap, not a dead range.
   *
   * `_collect` already turns "every attempted date failed" or a tripped
   * breaker into a throw, and a minority of load failures into its own
   * summary warning (see its docstring) — so this only has something to add
   * when nothing priced *and* not one attempted date failed to load.
   *
   * That alone is not enough, though: a date whose page loaded and decoded
   * rows that the caller's own airline/price/duration/window filter then
   * removed looks identical to one Google itself served nothing for, unless
   * the pre-filter row count is checked too. Only when at least one loaded
   * date's page decoded to *zero* rows before filtering is the emptiness
   * actually Google's doing — see {@link DateOutcome.rowsBeforeFilters}. For
   * a party with children or infants that is the shape Google's
   * client-side pricing produces, not evidence the route has no service.
   *
   * Internal — underscore-prefixed rather than private, mirroring
   * {@link SearchDates._collect}, so tests can drive it with a fixed set of
   * outcomes instead of racing a real sweep's per-date failure logging into
   * the state they want to assert.
   *
   * @returns Whether the warning fired — the caller mirrors this onto
   *   {@link SearchDates.sparsePassengerMix}.
   */
  static _warnIfSparsePassengerMix(
    outcomes: DateOutcome[],
    result: DatePrice[] | null,
    passengerInfo: PassengerInfo,
  ): boolean {
    if (result != null) return false;
    if (outcomes.some((o) => o.attempted && o.failure != null)) return false;
    if (!outcomes.some((o) => o.attempted && o.failure == null && o.rowsBeforeFilters === 0)) {
      return false;
    }
    if (!hasChildrenOrInfants(passengerInfo)) return false;
    getSearchLogger().warn(SPARSE_PASSENGER_MIX_WARNING);
    return true;
  }

  /** List every date in one chunk's `from_date`..`to_date` range. */
  private static _daysIn(filters: DateSearchFilters): Date[] {
    const from = filters.parsed_from_date;
    const to = filters.parsed_to_date;
    const days: Date[] = [];
    for (let t = from.getTime(); t <= to.getTime(); t += DAY_MS) days.push(new Date(t));
    return days;
  }

  /**
   * Assemble priced dates, raising when nothing could be fetched at all.
   *
   * A date with no flights is a legitimate answer; a date whose page
   * never arrived is not. When *every* attempted date failed, returning
   * an empty list would report a dead transport as "this route has no
   * flights" — exactly the silent failure this client exists to avoid.
   *
   * A sweep that tripped the circuit breaker must never end quietly
   * either. With prices to show, the answer is real but incomplete, so it
   * comes with one warning naming the count.
   *
   * The breaker is not the only way a sweep can go quietly wrong, though:
   * it disarms for good the instant any page loads, empty or not, so "1
   * loaded, 29 timeouts" sails straight past it — one date out of thirty
   * is not enough evidence that a route has no flights. When nothing
   * priced and at least half the attempted dates never loaded (`failed
   * >= loaded`), that is raised too. A page did load in that case, which
   * rules out an EU/EEA consent wall — those block every request alike —
   * so this path never adds the `FLI_SOCS_COOKIE` hint the branch above
   * does.
   *
   * Short of either throw, a sweep that lost some dates but not enough to
   * doubt the rest still owes the caller exactly one line saying so,
   * whether or not it ends up with anything to return.
   *
   * Internal — underscore-prefixed rather than `private` so tests can
   * drive it with a fixed set of outcomes instead of racing the sweep's
   * concurrent fetches into the state they want to assert.
   *
   * @param outcomes One entry per date in the range, in date order.
   * @param total Dates the sweep set out to price.
   * @param skipped Dates the breaker abandoned without requesting them.
   *   Non-zero exactly when the breaker tripped.
   */
  static _collect(outcomes: DateOutcome[], total: number, skipped: number): DatePrice[] | null {
    const results = outcomes.flatMap((o) => (o.price != null ? [o.price] : []));
    const attempted = outcomes.filter((o) => o.attempted);
    const failed = attempted.filter((o) => o.failure != null);
    // "loaded" counts every attempted date whose page actually arrived,
    // priced or not — it does not distinguish the two, because when
    // `results` is empty (the only time this number matters below) every
    // loaded date is by definition one with no flights.
    const loaded = attempted.length - failed.length;
    // The breaker only ever trips on payload-less pages, so a non-zero
    // skip count *is* the blocked-page diagnosis, whatever else failed
    // alongside.
    const tripped = skipped > 0;
    const everythingFailed = attempted.length > 0 && failed.length === attempted.length;

    if (results.length === 0 && (everythingFailed || tripped)) {
      const reasons = reasonsFor(failed);
      const cause = failed.find((o) => o.error != null)?.error;
      const blocked =
        tripped || (failed.length > 0 && failed.every((o) => o.failure === NO_PAYLOAD));

      let message: string;
      if (everythingFailed) {
        message =
          `Priced 0 of ${total} dates — every date in the range failed. ` +
          `Reasons: ${reasons.join("; ")}`;
      } else {
        // Some attempted date loaded and simply had no flights, which is
        // not a failure on its own — but with nothing priced anywhere and
        // the breaker tripped, the sweep still has no usable answer.
        message =
          `Priced 0 of ${total} dates — no date in the range could be priced. ` +
          `Reasons: ${reasons.join("; ") || "no flights on the dates that loaded"}`;
      }
      if (tripped) {
        message +=
          `. Gave up after ${attempted.length} of ${total} dates (${skipped} skipped): ` +
          "a sweep that has not loaded a single page is failing for the same " +
          "reason on every date, and each one costs several requests";
      }
      if (blocked) {
        message +=
          ". If you are on an EU/EEA IP, Google's consent interstitial serves no " +
          "results — the client sends a pre-accepted SOCS cookie by default, so " +
          "check FLI_SOCS_COOKIE has not been set to an empty value";
      }
      const ErrorType = blocked ? SearchParseError : SearchClientError;
      throw new ErrorType(message, cause != null ? { cause } : undefined);
    }

    if (results.length === 0 && failed.length > 0 && failed.length >= loaded) {
      // The breaker never saw this coming: one loaded page (even an empty
      // one) disarms it for good, so a sweep that is mostly timeouts
      // around a single lucky date never trips it. Half the attempted
      // dates never loading is its own signal that "no flights" cannot be
      // concluded from the handful that did.
      const reasons = reasonsFor(failed);
      const cause = failed.find((o) => o.error != null)?.error;
      const blocked = failed.length > 0 && failed.every((o) => o.failure === NO_PAYLOAD);
      const ErrorType = blocked ? SearchParseError : SearchClientError;
      const message =
        `Priced 0 of ${total} dates — ${failed.length} of the ${attempted.length} dates ` +
        `tried failed to load, so "no flights" cannot be concluded from the ${loaded} ` +
        `that did. Reasons: ${reasons.join("; ")}`;
      // Unlike the branch above, a page did load here — that rules out a
      // consent wall, which blocks every request identically. Adding the
      // FLI_SOCS_COOKIE hint would point at a diagnosis this sweep just
      // disproved, so it is deliberately left off.
      throw new ErrorType(message, cause != null ? { cause } : undefined);
    }

    if (tripped) {
      // Exactly one line, whatever the sweep's size: the caller is about
      // to act on a partial answer and has no other way to know it.
      getSearchLogger().warn(
        `Date sweep returned ${results.length} of ${total} dates: ${skipped} were skipped ` +
          `after ${SWEEP_FAILURE_THRESHOLD} pages came back without a ds:1 payload and none ` +
          "had loaded yet. The prices below are real but incomplete — retry, or check " +
          "FLI_SOCS_COOKIE if you are in the EU/EEA.",
      );
    } else if (failed.length > 0 && results.length > 0) {
      // Neither throw fired — most dates loaded fine — but the caller
      // still can't tell a complete sweep from this one just by looking
      // at the list, so it gets the same "exactly one line" treatment.
      getSearchLogger().warn(
        `Date sweep priced ${results.length} of ${total} dates: ${failed.length} failed ` +
          "to load. The prices below are real but incomplete.",
      );
    } else if (failed.length > 0) {
      // No results, but too few dates failed to throw: most of the sweep
      // loaded fine and simply found nothing. Still worth a line —
      // otherwise a caller sees only `null`, indistinguishable from a
      // sweep where every date loaded and truly had no flights.
      const reasons = reasonsFor(failed);
      getSearchLogger().warn(
        `Date sweep found no flights on the ${loaded} dates that loaded; ${failed.length} ` +
          `of ${attempted.length} dates failed to load, so treat this as provisional ` +
          `rather than a confirmed empty range. Reasons: ${reasons.join("; ")}`,
      );
    }
    return results.length > 0 ? results : null;
  }

  /**
   * Split the filters' date range into independent per-chunk copies.
   *
   * The flight segments are cloned per chunk and their `travel_date`
   * advanced by the chunk offset so each chunk represents a distinct,
   * self-contained search — which keeps the outbound/return gap a
   * round-trip sweep reads its duration from.
   */
  private _buildChunkFilters(
    filters: DateSearchFilters,
    fromDate: Date,
    toDate: Date,
  ): DateSearchFilters[] {
    const chunks: DateSearchFilters[] = [];
    let currentFrom = fromDate;
    let chunkIndex = 0;
    while (currentFrom.getTime() <= toDate.getTime()) {
      const endMs = currentFrom.getTime() + (MAX_DAYS_PER_SEARCH - 1) * DAY_MS;
      const currentTo = new Date(Math.min(endMs, toDate.getTime()));
      const cloned = cloneFilters(filters);
      if (chunkIndex > 0) {
        const shiftDays = MAX_DAYS_PER_SEARCH * chunkIndex;
        for (const segment of cloned.flight_segments) {
          const segDate = parseIsoDate(segment.travel_date);
          segment.travel_date = formatIsoDate(new Date(segDate.getTime() + shiftDays * DAY_MS));
        }
      }
      cloned.from_date = formatIsoDate(currentFrom);
      cloned.to_date = formatIsoDate(currentTo);
      chunks.push(cloned);
      currentFrom = new Date(currentTo.getTime() + DAY_MS);
      chunkIndex++;
    }
    return chunks;
  }

  /**
   * Price one departure date through its own search-page fetch.
   *
   * Total by construction — one bad date must never sink the sweep, so
   * every failure comes back as a `DateOutcome` rather than a rejection.
   *
   * `health` is the sweep's circuit breaker. It is consulted before any
   * request, so a date still queued when the sweep is already known to be
   * failing deterministically costs nothing at all.
   */
  private async _priceOneDate(
    filters: DateSearchFilters,
    day: Date,
    options: DateSearchOptions,
    health: SweepHealth,
  ): Promise<DateOutcome> {
    const dates: Date[] = [day];
    if (filters.trip_type === TripType.ROUND_TRIP) {
      // `duration` is optional, so fall back to the gap between the two
      // segments — which the filter model keeps consistent with it.
      let tripDays = filters.duration;
      if (tripDays == null) {
        const segments = filters.flight_segments;
        const a = segments[0]?.parsed_travel_date.getTime() ?? 0;
        const b = segments[1]?.parsed_travel_date.getTime() ?? 0;
        tripDays = Math.round((b - a) / DAY_MS);
      }
      dates.push(new Date(day.getTime() + tripDays * DAY_MS));
    }
    const travelDates = dates.map(formatIsoDate);

    // The caller has cancelled: start no further date. `attempted: false`
    // keeps it out of every tally — `search` rejects with the abort reason
    // before `_collect` ever runs, and a cancelled date is not evidence of
    // a blocked client.
    if (options.signal?.aborted) {
      return outcome({ attempted: false });
    }

    // A date sweep can straddle today, and past dates are simply not
    // bookable — skip them rather than spend a request on them.
    if (day.getTime() < earliestSearchableDate().getTime()) {
      return outcome({ attempted: false });
    }

    // Nothing in this sweep has loaded and enough dates have failed, so
    // this one will fail too. Skip it rather than spend its retry budget;
    // `attempted: false` keeps it out of the "everything failed" tally,
    // which the already-failed dates satisfy on their own.
    if (health.shouldStop()) {
      health.recordSkip();
      return outcome({ attempted: false });
    }

    const url = pageUrl(
      buildTfs(filters, { travelDates }),
      options.currency ?? null,
      options.language ?? null,
      options.country ?? null,
    );

    let flights: FlightResult[];
    let rawFlights: FlightResult[];
    try {
      const payload = await fetchPayload(this.client, url, { signal: options.signal });
      if (payload == null) {
        // Logged here rather than thrown: one bad date is a warning, and
        // `_collect` decides whether *every* date failing is fatal.
        getSearchLogger().warn(
          `Pricing ${travelDates[0]} failed: the search page carried no ds:1 payload`,
        );
        health.recordBlocked();
        return outcome({ failure: NO_PAYLOAD });
      }

      // The page arrived and decoded; from here on the sweep is healthy
      // and later misses get their full retry budget.
      health.recordSuccess();

      // The filters Google has no `tfs` field for (airlines, price cap,
      // duration, departure window) are applied to the decoded rows,
      // exactly as the flight search applies them — otherwise the
      // cheapest price for a date is taken over itineraries the caller
      // asked to exclude.
      //
      // Decoding and filtering sit inside the `try` on purpose: they walk
      // attacker-shaped data from the wire, and letting one odd row throw
      // out of here would sink the whole sweep.
      //
      // `rawFlights.length` is captured ahead of the filter call
      // deliberately: it is what tells a genuinely empty Google page (0
      // rows decoded) apart from a page Google filled that the caller's
      // own airline/price/duration/window filter then emptied — see
      // `DateOutcome.rowsBeforeFilters` and `_warnIfSparsePassengerMix`.
      rawFlights = flightsIn(payload);
      flights = applyClientSideFilters(rawFlights, filters);
    } catch (err) {
      // An in-flight date that was cancelled is not a failed date. Warning
      // about it, counting it towards "every date failed", or feeding it
      // to the circuit breaker would all report a problem that is not
      // there — the caller knows perfectly well why the sweep stopped.
      if (options.signal?.aborted) {
        return outcome({ attempted: false });
      }
      // One concise line per bad date; the stack trace stays at debug.
      const name = err instanceof Error ? err.name : "Error";
      const detail = err instanceof Error ? err.message : String(err);
      getSearchLogger().warn(`Pricing ${travelDates[0]} failed: ${name}: ${detail}`);
      getSearchLogger().debug(`Pricing ${travelDates[0]} failed`, err);
      // Deliberately not fed to the breaker: an error here (a timeout, a
      // reset connection) tells us nothing about the dates that have not
      // been tried, unlike a page served without its payload.
      return outcome({ failure: `${name}: ${detail}`, error: err });
    }

    // `!flight.price` and not `== null`: a zero price is Google's way of
    // saying it has no fare for the row, the same reading the Python sweep
    // takes with `if flight.price`.
    let cheapest: FlightResult | null = null;
    let cheapestPrice = Number.POSITIVE_INFINITY;
    for (const flight of flights) {
      if (!flight.price) continue;
      if (flight.price < cheapestPrice) {
        cheapest = flight;
        cheapestPrice = flight.price;
      }
    }
    if (cheapest == null) return outcome({ rowsBeforeFilters: rawFlights.length });

    return outcome({
      rowsBeforeFilters: rawFlights.length,
      price: {
        date: dates as [Date] | [Date, Date],
        price: cheapestPrice,
        // Python reports the requested currency here and nothing when
        // none was asked for; the row's own currency is a strictly better
        // fallback than null, and matches what this field meant before
        // the transport moved.
        currency: options.currency ?? cheapest.currency ?? null,
      },
    });
  }
}