Skip to content

armgit / fli

Public Imported from GitHub
0

Google Flights MCP, CLI and Python Library

fix(js): restore search in fli-js via the public search page (port of #230) (#247)

Punit Arani787db0e75cce
diff --git a/README.md b/README.md
index eda9a25..216cf6a 100644
--- a/README.md
+++ b/README.md
@@ -531,6 +531,13 @@ const filters = new FlightSearchFilters({
const results = await new SearchFlights().search(filters, { currency: "USD" });
```
+`fli-js` uses the same search-page transport as the Python package (see
+[Search transport](#search-transport) above), with the same consequences:
+`emissions` / `bags` / `exclude_basic_economy` are dropped with a warning,
+multi-city throws `SearchUnsupportedError`, `getBookingOptions` throws
+`SearchRejectedError`, date searches cost one page fetch per date and are
+capped at 93, and `FLI_SOCS_COOKIE` controls the consent cookie.
+
The TypeScript source lives in [`fli-js/`](fli-js); see the
[TypeScript Quick Start](https://punitarani.github.io/fli/typescript/quickstart/)
for the full guide.
diff --git a/docs/typescript/examples.md b/docs/typescript/examples.md
index 6909398..43b5b42 100644
--- a/docs/typescript/examples.md
+++ b/docs/typescript/examples.md
@@ -35,6 +35,14 @@ On Node, run through a TypeScript loader: `npx tsx basic_one_way_search.ts`.
## Multi-city
+!!! warning "Not available through the current transport"
+ Google loads multi-city results client-side through the RPC it gated
+ in 2026-08, so the search page carries no rows to read.
+ `search(...)` throws `SearchUnsupportedError` for
+ `TripType.MULTI_CITY` rather than returning the first leg's one-way
+ board, which would decode cleanly into wrong results. Search each leg
+ separately for now. The example below is kept for when that changes.
+
```ts
import {
Airport,
@@ -78,9 +86,12 @@ for (const legs of itineraries ?? []) {
```ts
import {
+ SearchClientError,
SearchConnectionError,
SearchHTTPError,
+ SearchParseError,
SearchTimeoutError,
+ SearchUnsupportedError,
} from "fli-js";
try {
@@ -92,10 +103,20 @@ try {
// network/proxy problem
} else if (err instanceof SearchHTTPError) {
// non-2xx from Google
+ } else if (err instanceof SearchParseError) {
+ // the page loaded but carried no readable results — a consent or
+ // block page, or a change in Google's page shape
+ } else if (err instanceof SearchUnsupportedError) {
+ // the current transport cannot serve this query (multi-city)
} else {
throw err;
}
}
```
+All of the above extend `SearchClientError`, so `catch (err) { if (err
+instanceof SearchClientError) … }` covers "the search failed" in one
+branch. A search that simply found nothing returns `null` instead of
+throwing.
+
See the [Python examples](../python/examples.md) for the equivalent scripts.
diff --git a/docs/typescript/quickstart.md b/docs/typescript/quickstart.md
index 00f7077..7c4618e 100644
--- a/docs/typescript/quickstart.md
+++ b/docs/typescript/quickstart.md
@@ -131,8 +131,14 @@ for (const { date, price } of dates ?? []) {
```
`DatePrice.date` is a tuple of `Date` objects: `[outbound]` for one-way,
-`[outbound, return]` for round trips. Ranges larger than 61 days are split
-into multiple calls automatically.
+`[outbound, return]` for round trips.
+
+!!! warning "One page fetch per date"
+ Google's search page carries no calendar grid, so every date in the
+ range costs its own full page fetch (~2 MB). A single
+ `SearchDates.search` prices at most **93 dates**
+ (`MAX_DATES_PER_SEARCH`); a wider range throws `RangeError`. See
+ [Search transport](#search-transport).
## Filters, alliances, and locale
@@ -193,8 +199,64 @@ const search = new SearchFlights(client);
```
Typed errors — `SearchTimeoutError`, `SearchConnectionError`,
-`SearchHTTPError`, all extending `SearchClientError` — let you branch on
-failure mode.
+`SearchHTTPError`, `SearchParseError`, `SearchRejectedError` and
+`SearchUnsupportedError`, all extending `SearchClientError` — let you
+branch on failure mode.
+
+## Search transport
+
+Searches are served by Google's public search page rather than the
+`FlightsFrontendService` RPC. Since 2026-08 `GetShoppingResults` and
+`GetCalendarGraph` require an `x-goog-batchexecute-bgr` header that only
+the page's own JavaScript can produce, so a plain HTTP client gets HTTP
+200 with no payload. `fli-js` issues
+`GET https://www.google.com/travel/flights?tfs=<protobuf>` instead and
+reads the results out of the page's inline `AF_initDataCallback` blob
+keyed `ds:1`. This matches the Python library, which moved the same way.
+
+What that means in practice:
+
+* **Three filters are not supported.** `emissions`, `bags` and
+ `exclude_basic_economy` have no `tfs` field and cannot be reconstructed
+ from the decoded rows, so they are dropped with a warning. Stops,
+ cabin, passengers, alliances and layover bounds ride in the request;
+ airline include/exclude, price cap, max duration and departure windows
+ are applied to the results after fetching, and `sort_by` orders them
+ afterwards (`TOP_FLIGHTS` / `BEST` keep Google's own ranking).
+* **Multi-city throws `SearchUnsupportedError`.** Google loads those
+ results client-side through the gated RPC, so the page carries no rows
+ to read. Search each leg separately.
+* **`getBookingOptions` is unavailable.** It calls `GetBookingResults`,
+ which is gated the same way, and currently throws
+ `SearchRejectedError`. `buildFlightBookingUrl` is built offline from
+ the itinerary and still works.
+* **Fewer rows per search.** Expect roughly 20–45 itineraries, fewer than
+ the old RPC returned — and a client-side filter cannot back-fill the
+ list the way Google's server-side one did.
+* **Date searches cost one page fetch per date**, capped at 93 dates. A
+ sweep that never loads a single page stops once five dates have come
+ back payload-less and throws, rather than paying the retry budget on
+ all of them. Ten dates are in flight at once, so around fourteen are
+ attempted first — about 42 page fetches, whether the range is 30, 61 or
+ 93 days. One that was cut short but found prices returns them with a
+ warning.
+* **A page occasionally arrives without results.** Roughly one request in
+ sixty returns HTTP 200 with no `ds:1` blob; the client retries that case
+ up to twice (0.5s then 1.5s) before throwing `SearchParseError`.
+* **`FLI_SOCS_COOKIE`.** EU/EEA IPs are redirected to Google's consent
+ interstitial, which serves no `ds:1` blob. The client sends a
+ pre-accepted `SOCS` consent cookie by default; set `FLI_SOCS_COOKIE` to
+ change the value, or to an empty string to send none.
+
+Warnings (dropped filters, a sweep cut short) go to `console.warn`.
+Redirect or silence them with `setSearchLogger`:
+
+```ts
+import { setSearchLogger } from "fli-js";
+
+setSearchLogger({ warn: (m) => myLogger.warn(m), debug: () => {} });
+setSearchLogger(null); // back to console.warn
+```
## Next steps
diff --git a/examples/python/multi_city_search.py b/examples/python/multi_city_search.py
index 5a3926c..75cfc8d 100644
--- a/examples/python/multi_city_search.py
+++ b/examples/python/multi_city_search.py
@@ -1,6 +1,16 @@
#!/usr/bin/env python3
"""Multi-city flight search example.
+CURRENTLY UNAVAILABLE. Since 2026-08 searches are served by Google's
+public ``/travel/flights`` page rather than the ``GetShoppingResults``
+RPC, which now requires a browser-signed header. Google loads multi-city
+results client-side through that same gated RPC, so the page carries no
+flight rows to read — :meth:`SearchFlights.search` raises
+``SearchUnsupportedError`` rather than returning the first leg's one-way
+board, which would decode cleanly into wrong results. Search each leg
+separately for now. This example is kept for when that changes; see
+github.com/punitarani/fli#223.
+
This example demonstrates how to search a multi-city itinerary (three or
more one-way legs on different dates) in a single request. Multi-city
results come back as tuples of ``FlightResult`` — one entry per leg, in
diff --git a/examples/typescript/multi_city_search.ts b/examples/typescript/multi_city_search.ts
index 0441d56..aa73ec5 100644
--- a/examples/typescript/multi_city_search.ts
+++ b/examples/typescript/multi_city_search.ts
@@ -1,6 +1,16 @@
/**
* Multi-city itinerary search (three legs on different dates).
*
+ * CURRENTLY UNAVAILABLE. Since 2026-08 searches are served by Google's
+ * public `/travel/flights` page rather than the `GetShoppingResults` RPC,
+ * which now requires a browser-signed header. Google loads multi-city
+ * results client-side through that same gated RPC, so the page carries no
+ * flight rows to read — `search()` raises `SearchUnsupportedError` rather
+ * than returning the first leg's one-way board, which would decode
+ * cleanly into wrong results. Search each leg separately for now. This
+ * example is kept for when that changes; see
+ * https://github.com/punitarani/fli#223.
+ *
* Mirrors examples/python/multi_city_search.py. Results come back as an
* array of itineraries, each itinerary an array of FlightResult — one per
* leg, in order. Run with:
diff --git a/fli-js/README.md b/fli-js/README.md
index 70f3c8d..aa0c59f 100644
--- a/fli-js/README.md
+++ b/fli-js/README.md
@@ -4,7 +4,8 @@ A 1:1 TypeScript / JavaScript port of the [Python `fli` library](https://github.
Programmatic access to Google Flights data via direct API interaction (no
scraping). The API surface mirrors the Python package — same models, same
-filter encoding, same wire-format decoders.
+filter encoding, same wire-format decoders — and, since Google gated its
+RPC endpoints, the same [search-page transport](#search-transport).
## Install
@@ -94,12 +95,74 @@ console.log(googleFlightsUrl("JFK", "LHR", "2026-12-25", null, { currency: "USD"
of them (round-trip / multi-city). It never throws — on malformed input it
falls back to the generic Google Flights URL.
+## Search transport
+
+Searches are served by Google's public search page rather than the
+`FlightsFrontendService` RPC. Since 2026-08 `GetShoppingResults` and
+`GetCalendarGraph` require an `x-goog-batchexecute-bgr` header that only the
+page's own JavaScript can produce, so a plain HTTP client gets HTTP 200 with no
+payload. `fli-js` issues `GET https://www.google.com/travel/flights?tfs=<protobuf>`
+instead and reads the results out of the page's inline `AF_initDataCallback`
+blob keyed `ds:1`.
+
+What that means in practice:
+
+- **Three filters are not supported.** `emissions`, `bags` and
+ `exclude_basic_economy` have no `tfs` field and cannot be reconstructed from
+ the decoded rows, so they are dropped with a warning. Stops, cabin,
+ passengers, alliances and layover bounds ride in the request; airline
+ include/exclude, price cap, max duration and departure windows are applied to
+ the results after fetching, and `sort_by` orders them afterwards
+ (`TOP_FLIGHTS` / `BEST` keep Google's own ranking).
+- **Multi-city throws `SearchUnsupportedError`.** Google loads those results
+ client-side through the gated RPC, so the page carries no rows to read.
+ Search each leg separately.
+- **`getBookingOptions` is unavailable.** It calls `GetBookingResults`, which
+ is gated the same way, and currently throws `SearchRejectedError`. The
+ per-flight `tfs` booking deep links (`buildFlightBookingUrl`) are built
+ offline and still work.
+- **Fewer rows per search.** Expect roughly 20–45 itineraries, fewer than the
+ old RPC returned — and a client-side filter cannot back-fill the list the way
+ Google's server-side one did.
+- **Date searches cost one page fetch per date.** The page has no calendar
+ grid, so a range is priced date by date; one `SearchDates.search` covers at
+ most 93 dates (`MAX_DATES_PER_SEARCH`) and a wider range throws `RangeError`.
+ A sweep that never manages to load a single page — the shape a blocked or
+ consent-gated client produces — stops once five dates have come back
+ payload-less rather than paying the retry budget on all of them, and throws.
+ Up to ten dates are in flight at once, so around fourteen are attempted
+ before the rest are abandoned (measured: 42 page fetches, whether the range
+ is 30, 61 or 93 days). Only pages served without results count towards that:
+ a timeout or a dropped connection says nothing about the dates not yet tried,
+ so those never abandon a sweep. A sweep cut short that still found prices
+ returns them with one warning saying so.
+- **A page occasionally arrives without results.** Roughly one request in sixty
+ returns HTTP 200 with no `ds:1` blob; the client retries that case up to twice
+ (0.5s then 1.5s) before throwing `SearchParseError`. A healthy search never
+ pays for it.
+- **`FLI_SOCS_COOKIE`.** EU/EEA IPs are redirected to Google's consent
+ interstitial, which serves no `ds:1` blob. The client sends a pre-accepted
+ `SOCS` consent cookie by default; set `FLI_SOCS_COOKIE` to change the value,
+ or to an empty string to send none.
+
+The client reports dropped filters and partial sweeps through `console.warn`.
+Redirect or silence that with `setSearchLogger`:
+
+```ts
+import { setSearchLogger } from "fli-js";
+
+setSearchLogger({ warn: (m) => myLogger.warn(m), debug: () => {} });
+setSearchLogger(null); // back to console.warn
+```
+
## HTTP / proxy configuration
-The TypeScript port uses native `fetch` (Bun's built-in) and replaces
-`curl_cffi`'s TLS impersonation with:
+The TypeScript port uses native `fetch` (Bun's and Node's built-in) and
+replaces `curl_cffi`'s TLS impersonation with:
-- realistic Chrome `User-Agent` + `Sec-CH-*` headers,
+- realistic Chrome `User-Agent` + `Sec-CH-*` headers — the `User-Agent` is
+ load-bearing, not cosmetic: without one the search page serves a shell with
+ no flight rows in it,
- automatic rate-limiting at 10 req/s,
- 3-attempt exponential backoff on transient errors,
- proxy support via the `HTTPS_PROXY` / `HTTP_PROXY` env vars (or via the
@@ -124,7 +187,9 @@ Set the per-request timeout with `FLI_TIMEOUT=30` (seconds) or via the
currency token decoders, deep-link builder (`googleFlightsUrl`).
- `fli-js/search` — `SearchFlights` (incl. `buildFlightBookingUrl`),
`SearchDates`, `Client`, error classes, protobuf token helpers
- (`buildBookingToken`, `buildTfsToken`, `extractBookingTokenFromTfu`).
+ (`buildBookingToken`, `buildTfsToken`, `extractBookingTokenFromTfu`), and
+ the search-page transport (`buildTfs`, `pageUrl`, `extractPayload`,
+ `fetchPayload`).
## Development
@@ -150,6 +215,14 @@ Python upstream:
booking-page tokens byte-for-byte (see `tests/search/proto.test.ts`); the
resulting `buildFlightBookingUrl(...)` output matches the Python library
character-for-character.
+- `buildTfs(...)` produces the same search-page token as the Python
+ `fli.search._tfs.build_tfs` across trip shapes, cabins, stop limits,
+ passenger mixes, alliances and layover bounds. The expected values in
+ `tests/search/tfs.test.ts` are generated by running the Python encoder —
+ regenerate them from the repository root with
+ `uv run --python 3.13 python fli-js/scripts/dump_tfs_goldens.py`.
+- `extractPayload(...)` is pinned against the same captured search page the
+ Python suite uses (`tests/search/fixtures/search_page_jfk_lhr_nonstop_ds1.html`).
- The wire-format parser handles both the legacy single-chunk JSONP
shape and the multi-chunk format used by `GetBookingResults`.
diff --git a/fli-js/scripts/dump_tfs_goldens.py b/fli-js/scripts/dump_tfs_goldens.py
new file mode 100644
index 0000000..7ab22b0
--- /dev/null
+++ b/fli-js/scripts/dump_tfs_goldens.py
@@ -0,0 +1,252 @@
+"""Dump the golden ``tfs`` values pinned by ``tests/search/tfs.test.ts``.
+
+The TypeScript encoder must produce byte-identical ``tfs`` tokens to the
+Python one — that is the strongest correctness lever the port has, since
+Google accepts a malformed token by quietly answering a different query.
+This script is the single source of those goldens.
+
+Run it from the **repository root** (it imports the Python package, not
+the JS one)::
+
+ uv run --python 3.13 python fli-js/scripts/dump_tfs_goldens.py
+
+and paste the JSON it prints into ``TFS_GOLDENS`` in
+``fli-js/tests/search/tfs.test.ts``.
+
+Travel dates are deliberately far out: ``FlightSegment`` rejects a past
+date, and the JS suite has no clock-pinning fixture, so a golden built on
+a near date would start failing the day it passed. The ``tfs`` bytes
+depend only on the dates in the filters, never on "today".
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+
+from fli.models import (
+ Airline,
+ Airport,
+ Alliance,
+ FlightLeg,
+ FlightResult,
+ FlightSearchFilters,
+ FlightSegment,
+ LayoverRestrictions,
+ MaxStops,
+ PassengerInfo,
+ SeatType,
+ TripType,
+)
+from fli.search._tfs import build_tfs
+
+OUT = "2030-09-15"
+RET = "2030-09-19"
+MULTI = "2030-10-15"
+
+
+def seg(origins, dests, date):
+ return FlightSegment(
+ departure_airport=[[Airport[o], 0] for o in origins],
+ arrival_airport=[[Airport[d], 0] for d in dests],
+ travel_date=date,
+ )
+
+
+def filters(segments, **kw):
+ return FlightSearchFilters(
+ trip_type=kw.pop("trip_type", TripType.ONE_WAY),
+ passenger_info=kw.pop("passenger_info", PassengerInfo(adults=1)),
+ flight_segments=segments,
+ stops=kw.pop("stops", MaxStops.ANY),
+ seat_type=kw.pop("seat_type", SeatType.ECONOMY),
+ **kw,
+ )
+
+
+def selected_flight():
+ return FlightResult(
+ legs=[
+ FlightLeg(
+ airline=Airline.BA,
+ flight_number="178",
+ departure_airport=Airport.JFK,
+ arrival_airport=Airport.LHR,
+ departure_datetime=datetime(2030, 9, 15, 20, 30),
+ arrival_datetime=datetime(2030, 9, 16, 8, 30),
+ duration=420,
+ )
+ ],
+ price=295.0,
+ currency="USD",
+ duration=420,
+ stops=0,
+ )
+
+
+def two_leg_selected_flight():
+ """Connecting outbound, to pin the repeated leg encoding."""
+ return FlightResult(
+ legs=[
+ FlightLeg(
+ airline=Airline.AA,
+ flight_number="100",
+ departure_airport=Airport.JFK,
+ arrival_airport=Airport.ORD,
+ departure_datetime=datetime(2030, 9, 15, 7, 0),
+ arrival_datetime=datetime(2030, 9, 15, 9, 0),
+ duration=150,
+ ),
+ FlightLeg(
+ airline=Airline.AA,
+ flight_number="200",
+ departure_airport=Airport.ORD,
+ arrival_airport=Airport.LHR,
+ departure_datetime=datetime(2030, 9, 15, 17, 0),
+ arrival_datetime=datetime(2030, 9, 16, 7, 0),
+ duration=480,
+ ),
+ ],
+ price=420.0,
+ currency="USD",
+ duration=900,
+ stops=1,
+ )
+
+
+cases: dict[str, str] = {}
+
+
+def add(name, spec, **kw):
+ cases[name] = build_tfs(spec, **kw)
+
+
+# --- trip shapes ---------------------------------------------------------
+add("one_way_jfk_lax", filters([seg(["JFK"], ["LAX"], OUT)]))
+add(
+ "round_trip_jfk_lax",
+ filters(
+ [seg(["JFK"], ["LAX"], OUT), seg(["LAX"], ["JFK"], RET)],
+ trip_type=TripType.ROUND_TRIP,
+ ),
+)
+
+rt_selected = filters(
+ [seg(["JFK"], ["LHR"], OUT), seg(["LHR"], ["JFK"], RET)],
+ trip_type=TripType.ROUND_TRIP,
+)
+rt_selected.flight_segments[0].selected_flight = selected_flight()
+add("round_trip_selected_outbound", rt_selected)
+
+rt_conn = filters(
+ [seg(["JFK"], ["LHR"], OUT), seg(["LHR"], ["JFK"], RET)],
+ trip_type=TripType.ROUND_TRIP,
+)
+rt_conn.flight_segments[0].selected_flight = two_leg_selected_flight()
+add("round_trip_selected_connecting_outbound", rt_conn)
+
+add(
+ "multi_airport",
+ filters([seg(["BOM", "DEL", "AMD"], ["ORD", "DTW"], MULTI)]),
+)
+
+# --- cabins --------------------------------------------------------------
+for name, cabin in [
+ ("economy", SeatType.ECONOMY),
+ ("premium_economy", SeatType.PREMIUM_ECONOMY),
+ ("business", SeatType.BUSINESS),
+ ("first", SeatType.FIRST),
+]:
+ add(f"cabin_{name}", filters([seg(["JFK"], ["LAX"], OUT)], seat_type=cabin))
+
+# --- stops ---------------------------------------------------------------
+for name, stops in [
+ ("any", MaxStops.ANY),
+ ("non_stop", MaxStops.NON_STOP),
+ ("one_stop_or_fewer", MaxStops.ONE_STOP_OR_FEWER),
+ ("two_or_fewer_stops", MaxStops.TWO_OR_FEWER_STOPS),
+]:
+ add(f"stops_{name}", filters([seg(["JFK"], ["LAX"], OUT)], stops=stops))
+
+# --- passenger mixes -----------------------------------------------------
+passenger_mixes = {
+ "pax_single_adult": {"adults": 1},
+ "pax_two_adults": {"adults": 2},
+ "pax_adult_child": {"adults": 1, "children": 1},
+ "pax_adult_lap_infant": {"adults": 1, "infants_on_lap": 1},
+ "pax_adult_seat_infant": {"adults": 1, "infants_in_seat": 1},
+ "pax_family_mix": {"adults": 2, "children": 1, "infants_in_seat": 1, "infants_on_lap": 1},
+ "pax_full_house": {"adults": 4, "children": 2, "infants_in_seat": 2, "infants_on_lap": 1},
+ "pax_two_adults_two_lap_infants": {"adults": 2, "infants_on_lap": 2},
+}
+for name, counts in passenger_mixes.items():
+ add(
+ name,
+ filters([seg(["JFK"], ["LAX"], OUT)], passenger_info=PassengerInfo(**counts)),
+ )
+
+# --- alliances -----------------------------------------------------------
+for name, alliance in [
+ ("oneworld", Alliance.ONEWORLD),
+ ("skyteam", Alliance.SKYTEAM),
+ ("star_alliance", Alliance.STAR_ALLIANCE),
+]:
+ spec = filters([seg(["JFK"], ["LAX"], OUT)])
+ spec.alliances = [alliance]
+ add(f"alliance_include_{name}", spec)
+
+ spec = filters([seg(["JFK"], ["LAX"], OUT)])
+ spec.alliances_exclude = [alliance]
+ add(f"alliance_exclude_{name}", spec)
+
+spec = filters([seg(["JFK"], ["LAX"], OUT)])
+spec.alliances = [Alliance.ONEWORLD, Alliance.STAR_ALLIANCE]
+spec.alliances_exclude = [Alliance.SKYTEAM]
+add("alliance_include_two_exclude_one", spec)
+
+# --- layovers ------------------------------------------------------------
+spec = filters([seg(["JFK"], ["LAX"], OUT)])
+spec.layover_restrictions = LayoverRestrictions(airports=[Airport.ORD], min_duration=120)
+add("layover_airport_and_min", spec)
+
+spec = filters([seg(["JFK"], ["LAX"], OUT)])
+spec.layover_restrictions = LayoverRestrictions(max_duration=300)
+add("layover_max_only", spec)
+
+spec = filters([seg(["JFK"], ["LAX"], OUT)])
+spec.layover_restrictions = LayoverRestrictions(
+ airports=[Airport.ORD, Airport.DFW], min_duration=90, max_duration=600
+)
+add("layover_full", spec)
+
+# --- combined ------------------------------------------------------------
+spec = filters(
+ [seg(["JFK", "EWR"], ["LHR", "LGW"], OUT), seg(["LHR", "LGW"], ["JFK", "EWR"], RET)],
+ trip_type=TripType.ROUND_TRIP,
+ stops=MaxStops.ONE_STOP_OR_FEWER,
+ seat_type=SeatType.BUSINESS,
+ passenger_info=PassengerInfo(adults=2, children=1, infants_on_lap=1),
+)
+spec.alliances = [Alliance.ONEWORLD]
+spec.layover_restrictions = LayoverRestrictions(
+ airports=[Airport.DUB], min_duration=60, max_duration=240
+)
+add("kitchen_sink_round_trip", spec)
+
+# --- travel_dates override (date sweep) ----------------------------------
+add(
+ "sweep_one_way_date_override",
+ filters([seg(["JFK"], ["LAX"], OUT)]),
+ travel_dates=["2030-11-02"],
+)
+rt_sweep = filters(
+ [seg(["JFK"], ["LAX"], OUT), seg(["LAX"], ["JFK"], RET)],
+ trip_type=TripType.ROUND_TRIP,
+)
+add(
+ "sweep_round_trip_date_override",
+ rt_sweep,
+ travel_dates=["2030-11-02", "2030-11-09"],
+)
+
+print(json.dumps(cases, indent=2, sort_keys=True))
diff --git a/fli-js/src/search/client.ts b/fli-js/src/search/client.ts
index 74ed79e..2cb040a 100644
--- a/fli-js/src/search/client.ts
+++ b/fli-js/src/search/client.ts
@@ -12,7 +12,7 @@
* - wraps low-level errors into the typed {@link SearchClientError} family
*/
-import { TokenBucketRateLimiter } from "./concurrency.ts";
+import { sleep, TokenBucketRateLimiter, throwIfAborted } from "./concurrency.ts";
import {
SearchClientError,
SearchConnectionError,
@@ -44,24 +44,90 @@ function resolveProxy(): string | undefined {
return env.HTTPS_PROXY ?? env.https_proxy ?? env.HTTP_PROXY ?? env.http_proxy ?? undefined;
}
-const DEFAULT_HEADERS: Record<string, string> = {
+/**
+ * Headers every request carries.
+ *
+ * The `user-agent` is the load-bearing one, and not cosmetically: the
+ * `/travel/flights` page inlines its `ds:1` flight payload only for a
+ * request that looks like a browser. Probed 2026-09-20 under Bun 1.3 and
+ * Node 24 — with a Chrome UA the page is ~2.5 MB and carries the rows;
+ * with no UA at all it is ~1.2 MB and carries none, on HTTP 200 either
+ * way. The rest of the headers are not required by that probe, and are
+ * sent because a browser sends them.
+ */
+const BASE_HEADERS: Record<string, string> = {
// A realistic recent-Chrome UA. Google's frontend is tolerant of mismatch
// between the UA and the actual TLS fingerprint (which we can't fake from
// a Node/Bun fetch) but a credible UA makes a difference vs the default
// "node-fetch" / "undici" strings.
"user-agent":
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
- accept: "*/*",
"accept-language": "en-US,en;q=0.9",
"sec-ch-ua": '"Chromium";v="131", "Not_A Brand";v="24", "Google Chrome";v="131"',
"sec-ch-ua-mobile": "?0",
"sec-ch-ua-platform": '"macOS"',
+};
+
+/**
+ * Headers for the `f.req` RPC POSTs (`GetBookingResults`).
+ *
+ * Unchanged from before the search-page transport landed, so the one
+ * remaining RPC call goes out exactly as it always did.
+ */
+const DEFAULT_HEADERS: Record<string, string> = {
+ ...BASE_HEADERS,
+ accept: "*/*",
"sec-fetch-dest": "empty",
"sec-fetch-mode": "cors",
"sec-fetch-site": "same-origin",
"content-type": "application/x-www-form-urlencoded;charset=UTF-8",
};
+/**
+ * Headers for the search-page GET.
+ *
+ * A top-level document navigation, which is what this request actually
+ * is — the POST set describes a same-origin XHR, and carries a
+ * form-encoded `content-type` on a request with no body.
+ */
+const DEFAULT_GET_HEADERS: Record<string, string> = {
+ ...BASE_HEADERS,
+ accept:
+ "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
+ "sec-fetch-dest": "document",
+ "sec-fetch-mode": "navigate",
+ "sec-fetch-site": "none",
+ "sec-fetch-user": "?1",
+ "upgrade-insecure-requests": "1",
+};
+
+/**
+ * Pre-accepted consent cookie, sent so EU/EEA IPs are not redirected to
+ * Google's consent interstitial — which serves a page with no `ds:1`
+ * payload, so every search there fails to parse. The legacy `CONSENT`
+ * cookie no longer works, and a truncated `SOCS` value is ignored.
+ *
+ * Override with `FLI_SOCS_COOKIE` if Google rotates the value; set it to
+ * the empty string to send no cookie at all.
+ */
+export const DEFAULT_SOCS_COOKIE =
+ "CAISNQgQEitib3FfaWRlbnRpdHlmcm9udGVuZHVpc2VydmVyXzIwMjQwMzE3LjA5X3AwGgJlbiADGgYIgLC_rwY";
+
+/**
+ * The `SOCS` cookie value in effect: `FLI_SOCS_COOKIE` if set (including
+ * to the empty string, which disables the cookie), else
+ * {@link DEFAULT_SOCS_COOKIE}.
+ *
+ * Read at `Client` construction rather than at module load — Python
+ * reads its process environment once at import, but a JS consumer that
+ * sets `process.env` before building a client would find that surprising,
+ * and it makes the behaviour testable without module cache games.
+ */
+export function resolveSocsCookie(): string {
+ const raw = typeof process !== "undefined" ? process.env?.FLI_SOCS_COOKIE : undefined;
+ return raw ?? DEFAULT_SOCS_COOKIE;
+}
+
export interface ClientOptions {
/** Calls per second budget. Defaults to 10. */
callsPerSecond?: number;
@@ -75,6 +141,11 @@ export interface ClientOptions {
proxy?: string | null;
/** Custom fetch implementation (test seam). */
fetchImpl?: typeof fetch;
+ /**
+ * `SOCS` consent cookie value. Defaults to `FLI_SOCS_COOKIE` if set,
+ * else {@link DEFAULT_SOCS_COOKIE}. An empty string sends no cookie.
+ */
+ socsCookie?: string;
}
export interface RequestOptions {
@@ -91,8 +162,24 @@ export interface ClientResponse {
ok: boolean;
}
-function sleep(ms: number): Promise<void> {
- return new Promise((res) => setTimeout(res, ms));
+/**
+ * Is this URL served by Google?
+ *
+ * The `SOCS` consent cookie must not ride along to whatever other host a
+ * caller points the client at — Python keeps it in a cookie jar scoped to
+ * `.google.com`, and a header has no such scope of its own. `.google.com`
+ * covers `www.google.com` and `consent.google.com`, which are the two
+ * hosts a search actually touches, and deliberately not `google.co.uk`
+ * (Python's jar does not match it either).
+ */
+function isGoogleHost(url: string): boolean {
+ let hostname: string;
+ try {
+ hostname = new URL(url).hostname.toLowerCase();
+ } catch {
+ return false;
+ }
+ return hostname === "google.com" || hostname.endsWith(".google.com");
}
function hostFromUrl(url: string): string {
@@ -138,6 +225,7 @@ export class Client {
private readonly backoffMs: number;
private readonly proxy: string | undefined;
private readonly fetchImpl: typeof fetch;
+ private readonly cookieHeader: Record<string, string>;
constructor(options: ClientOptions = {}) {
this.rateLimiter = new TokenBucketRateLimiter(
@@ -149,6 +237,8 @@ export class Client {
this.backoffMs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
this.proxy = options.proxy === null ? undefined : (options.proxy ?? resolveProxy());
this.fetchImpl = options.fetchImpl ?? fetch;
+ const socs = options.socsCookie ?? resolveSocsCookie();
+ this.cookieHeader = socs ? { cookie: `SOCS=${socs}` } : {};
}
async get(url: string, options: RequestOptions = {}): Promise<ClientResponse> {
@@ -164,6 +254,11 @@ export class Client {
url: string,
options: RequestOptions,
): Promise<ClientResponse> {
+ // Nothing is spent on behalf of a caller who has already cancelled —
+ // not a rate-limiter token, which would delay the next real request,
+ // and not a `fetchImpl` call.
+ throwIfAborted(options.signal);
+
let lastError: unknown = null;
for (let attempt = 0; attempt < this.retries; attempt++) {
await this.rateLimiter.acquire();
@@ -178,10 +273,15 @@ export class Client {
}
}
const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+ let shouldRetry = false;
try {
const init: RequestInit & { proxy?: string } = {
method,
- headers: { ...DEFAULT_HEADERS, ...options.headers },
+ headers: {
+ ...(method === "GET" ? DEFAULT_GET_HEADERS : DEFAULT_HEADERS),
+ ...(isGoogleHost(url) ? this.cookieHeader : {}),
+ ...options.headers,
+ },
signal: controller.signal,
};
if (method === "POST" && options.body != null) {
@@ -220,18 +320,27 @@ export class Client {
// For HTTP errors we still respect the retry budget (matches the
// Python tenacity retry decorator behavior, which retries on any
// exception).
- if (attempt < this.retries - 1) {
- const wait = this.backoffMs * 2 ** attempt;
- await sleep(wait);
- continue;
- }
- break;
+ if (attempt >= this.retries - 1) break;
+ shouldRetry = true;
} finally {
clearTimeout(timer);
if (abortListener && externalSignal) {
externalSignal.removeEventListener("abort", abortListener);
}
}
+
+ // Outside the try/finally on purpose: the per-attempt timeout timer
+ // is cleared first, so a long backoff never sits under an armed
+ // request timeout. The sleep itself is abortable — waiting out a
+ // 4-second backoff after the caller has cancelled, and leaving the
+ // timer running afterwards, is exactly what a cancellation is for.
+ if (shouldRetry) {
+ try {
+ await sleep(this.backoffMs * 2 ** attempt, externalSignal);
+ } catch (abortErr) {
+ throw externalSignal?.reason ?? abortErr;
+ }
+ }
}
throw lastError ?? new SearchClientError("Unknown request failure");
}
diff --git a/fli-js/src/search/clone.ts b/fli-js/src/search/clone.ts
new file mode 100644
index 0000000..ad97bdb
--- /dev/null
+++ b/fli-js/src/search/clone.ts
@@ -0,0 +1,78 @@
+/**
+ * Copying filter objects before a search mutates them.
+ *
+ * Round-trip expansion pins a segment's `selected_flight` and the date
+ * sweep rewrites segment dates per chunk; neither may touch the object
+ * the caller handed in. Python does this with Pydantic's `model_copy`.
+ *
+ * There is exactly one implementation here on purpose. Both call sites
+ * used to keep their own hand-written list of fields to copy, which is
+ * the pattern that silently dropped `airlines_exclude` and the alliance
+ * lists in Python: a filter left off the list is not an error, it is a
+ * search that quietly ignores what the caller asked for. Copying every
+ * own property means a filter added later is carried without anyone
+ * having to remember to add it.
+ */
+
+/** A plain object literal — not a class instance, array or Date. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ if (typeof value !== "object" || value === null) return false;
+ const proto = Object.getPrototypeOf(value);
+ return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Copy one field.
+ *
+ * Deep enough that nothing a search mutates is shared with the caller,
+ * shallow enough to stay cheap: arrays and plain objects are copied one
+ * level (recursively for nested plain values), while class instances —
+ * `FlightSegment`, and `FlightResult` under `selected_flight` — are
+ * handled by the caller or kept by reference. A `FlightResult` is only
+ * ever read, so sharing it is safe and is what the previous
+ * implementations did.
+ */
+function copyValue(value: unknown): unknown {
+ if (Array.isArray(value)) return value.map(copyValue);
+ if (isPlainObject(value)) {
+ const out: Record<string, unknown> = {};
+ for (const [key, inner] of Object.entries(value)) out[key] = copyValue(inner);
+ return out;
+ }
+ return value;
+}
+
+/**
+ * Copy an object, keeping its prototype and every own enumerable field.
+ *
+ * The constructor is bypassed deliberately: re-running it would re-reject
+ * a travel date that has since passed, or re-validate a range the caller
+ * already got past, on a copy that is about to have those fields
+ * rewritten anyway.
+ */
+function copyInstance<T extends object>(source: T): T {
+ const out = Object.create(Object.getPrototypeOf(source)) as Record<string, unknown>;
+ for (const [key, value] of Object.entries(source)) out[key] = copyValue(value);
+ return out as T;
+}
+
+/** Shape shared by both filter classes: the part a search mutates. */
+interface HasSegments {
+ flight_segments: object[];
+}
+
+/**
+ * Copy a `FlightSearchFilters` or `DateSearchFilters`.
+ *
+ * Every own field is carried over. `flight_segments` and the segments
+ * themselves are fresh objects, so pinning a `selected_flight` or
+ * rewriting a `travel_date` on the copy leaves the caller's filters
+ * untouched.
+ */
+export function cloneFilters<T extends HasSegments>(filters: T): T {
+ const out = copyInstance(filters);
+ if (Array.isArray(filters.flight_segments)) {
+ out.flight_segments = filters.flight_segments.map((segment) => copyInstance(segment));
+ }
+ return out;
+}
diff --git a/fli-js/src/search/concurrency.ts b/fli-js/src/search/concurrency.ts
index e5058fb..825f706 100644
--- a/fli-js/src/search/concurrency.ts
+++ b/fli-js/src/search/concurrency.ts
@@ -4,6 +4,56 @@
* threading.Condition — `setTimeout`/`Promise` are the equivalent).
*/
+/**
+ * Throw the caller's abort reason if `signal` has already fired.
+ *
+ * Used at every point where a cancelled call would otherwise spend
+ * something on the caller's behalf — a rate-limiter token (which delays
+ * the next real request), a `fetchImpl` call, a page fetch, a date.
+ * Real `fetch` rejects a pre-aborted signal without touching the network,
+ * but a custom `fetchImpl` is under no such obligation.
+ */
+export function throwIfAborted(signal?: AbortSignal): void {
+ if (signal?.aborted) {
+ throw signal.reason ?? new DOMException("Aborted", "AbortError");
+ }
+}
+
+/**
+ * Sleep for `ms`, giving up promptly if `signal` aborts.
+ *
+ * Both backoffs in this package — the client's retry backoff and the
+ * page-retry backoff — sit between HTTP requests on a path a caller may
+ * cancel. A plain `setTimeout` promise would make the caller wait out a
+ * delay that no longer has any reason to elapse, and would leave the
+ * timer armed after the call had already settled.
+ *
+ * Rejects with the signal's own `reason`, so the caller gets back the
+ * error it aborted with rather than a synthesised one.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+ if (signal == null) {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+ }
+ return new Promise<void>((resolve, reject) => {
+ const abortReason = (): unknown => signal.reason ?? new DOMException("Aborted", "AbortError");
+ if (signal.aborted) {
+ reject(abortReason());
+ return;
+ }
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const onAbort = (): void => {
+ if (timer !== undefined) clearTimeout(timer);
+ reject(abortReason());
+ };
+ timer = setTimeout(() => {
+ signal.removeEventListener("abort", onAbort);
+ resolve();
+ }, ms);
+ signal.addEventListener("abort", onAbort, { once: true });
+ });
+}
+
/**
* Async token-bucket rate limiter.
*
diff --git a/fli-js/src/search/dates.ts b/fli-js/src/search/dates.ts
index c78f525..faced93 100644
--- a/fli-js/src/search/dates.ts
+++ b/fli-js/src/search/dates.ts
@@ -1,22 +1,127 @@
/**
- * Date-based flight search. Finds the cheapest prices across a date range
- * using Google Flights' GetCalendarGraph RPC.
+ * 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 { extractCurrencyFromPriceToken } from "../core/currency.ts";
import { formatIsoDate, parseIsoDate } from "../core/dates.ts";
+import type { FlightResult } from "../models/google-flights/base.ts";
import { TripType } from "../models/google-flights/base.ts";
-import { DateSearchFilters } from "../models/google-flights/dates.ts";
+import type { DateSearchFilters } from "../models/google-flights/dates.ts";
import { type Client, getClient } from "./client.ts";
-import { parallelMap } from "./concurrency.ts";
-import { withLocaleParams } from "./urls.ts";
-import { parseFirstWrbPayload } from "./wire.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 BASE_URL =
- "https://www.google.com/_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetCalendarGraph";
+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.
+ */
+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";
+
+/**
+ * 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. */
@@ -29,79 +134,281 @@ 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;
}
-function cloneSegments(filters: DateSearchFilters) {
- return filters.flight_segments.map((s) => {
- const clone = Object.create(Object.getPrototypeOf(s)) as typeof s;
- Object.assign(clone, {
- departure_airport: s.departure_airport,
- arrival_airport: s.arrival_airport,
- travel_date: s.travel_date,
- time_restrictions: s.time_restrictions,
- selected_flight: s.selected_flight,
- });
- return clone;
- });
+/**
+ * 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;
+}
+
+function outcome(over: Partial<DateOutcome> = {}): DateOutcome {
+ return { price: null, failure: null, error: null, attempted: true, ...over };
}
-function cloneFilters(filters: DateSearchFilters): DateSearchFilters {
- const out = Object.create(DateSearchFilters.prototype) as DateSearchFilters;
- Object.assign(out, {
- trip_type: filters.trip_type,
- passenger_info: { ...filters.passenger_info },
- flight_segments: cloneSegments(filters),
- stops: filters.stops,
- seat_type: filters.seat_type,
- price_limit: filters.price_limit ? { ...filters.price_limit } : null,
- airlines: filters.airlines ? [...filters.airlines] : null,
- airlines_exclude: filters.airlines_exclude ? [...filters.airlines_exclude] : null,
- alliances: filters.alliances ? [...filters.alliances] : null,
- alliances_exclude: filters.alliances_exclude ? [...filters.alliances_exclude] : null,
- max_duration: filters.max_duration,
- layover_restrictions: filters.layover_restrictions ? { ...filters.layover_restrictions } : null,
- emissions: filters.emissions,
- bags: filters.bags ? { ...filters.bags } : null,
- from_date: filters.from_date,
- to_date: filters.to_date,
- duration: filters.duration,
- });
- return out;
+/** 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;
}
export class SearchDates {
- static readonly BASE_URL = BASE_URL;
+ /**
+ * @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;
constructor(client?: Client) {
this.client = client ?? getClient();
}
+ /**
+ * 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.
+ */
async search(
filters: DateSearchFilters,
options: DateSearchOptions = {},
): Promise<DatePrice[] | null> {
+ 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);
- const dayMs = 24 * 60 * 60 * 1000;
- const dateRange = Math.floor((toDate.getTime() - fromDate.getTime()) / dayMs) + 1;
- if (dateRange <= MAX_DAYS_PER_SEARCH) {
- return this._searchChunk(filters, options);
+ // 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]);
}
- const chunkFilters = this._buildChunkFilters(filters, fromDate, toDate);
- const chunkResults = await parallelMap((cf) => this._searchChunk(cf, options), chunkFilters);
+ 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);
+
+ return SearchDates._collect(outcomes, tasks.length, health.skipped);
+ }
+
+ /** 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.
+ *
+ * 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);
+ // 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: string[] = [];
+ for (const o of failed) {
+ if (o.failure != null && !reasons.includes(o.failure) && reasons.length < 3) {
+ reasons.push(o.failure);
+ }
+ }
+ 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);
+ }
- const allResults: DatePrice[] = [];
- for (const r of chunkResults) {
- if (r) allResults.push(...r);
+ 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.",
+ );
}
- return allResults.length > 0 ? allResults : null;
+ 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,
@@ -110,85 +417,157 @@ export class SearchDates {
const chunks: DateSearchFilters[] = [];
let currentFrom = fromDate;
let chunkIndex = 0;
- const dayMs = 24 * 60 * 60 * 1000;
- while (currentFrom <= toDate) {
- const endMs = currentFrom.getTime() + (MAX_DAYS_PER_SEARCH - 1) * dayMs;
+ 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);
- const shiftDays = MAX_DAYS_PER_SEARCH * chunkIndex;
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 * dayMs));
+ 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() + dayMs);
+ currentFrom = new Date(currentTo.getTime() + DAY_MS);
chunkIndex++;
}
return chunks;
}
- private async _searchChunk(
+ /**
+ * 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,
- ): Promise<DatePrice[] | null> {
- const encoded = filters.encode();
- const url = withLocaleParams(
- BASE_URL,
+ 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,
);
- const response = await this.client.post(url, { body: `f.req=${encoded}` });
- const data = parseFirstWrbPayload(response.text);
- if (data == null || !Array.isArray(data)) return null;
-
- const items = data[data.length - 1];
- if (!Array.isArray(items)) return null;
-
- const out: DatePrice[] = [];
- for (const item of items) {
- const price = SearchDates._parsePrice(item);
- if (price == null) continue;
- out.push({
- date: SearchDates._parseDate(item, filters.trip_type),
- price,
- currency: SearchDates._parseCurrency(item),
- });
- }
- return out;
- }
- static _parseDate(item: unknown, tripType: TripType): [Date] | [Date, Date] {
- if (!Array.isArray(item)) throw new Error("date item is not an array");
- if (tripType === TripType.ONE_WAY) {
- return [parseIsoDate(item[0] as string)];
- }
- return [parseIsoDate(item[0] as string), parseIsoDate(item[1] as string)];
- }
+ let flights: 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 });
+ }
- static _parsePrice(item: unknown): number | null {
- if (!Array.isArray(item) || item.length <= 2) return null;
- const middle = item[2];
- if (!Array.isArray(middle) || middle.length === 0) return null;
- const inner = middle[0];
- if (!Array.isArray(inner) || inner.length <= 1) return null;
- const raw = inner[1];
- const n = typeof raw === "number" ? raw : Number.parseFloat(raw as string);
- return Number.isFinite(n) ? n : null;
- }
+ // The page arrived and decoded; from here on the sweep is healthy
+ // and later misses get their full retry budget.
+ health.recordSuccess();
- static _parseCurrency(item: unknown): string | null {
- if (!Array.isArray(item) || item.length <= 2) return null;
- const middle = item[2];
- if (!Array.isArray(middle) || middle.length <= 1) return null;
- try {
- return extractCurrencyFromPriceToken(middle[1] as string);
- } catch {
- return null;
+ // 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.
+ flights = applyClientSideFilters(flightsIn(payload), 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();
+
+ return outcome({
+ 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,
+ },
+ });
}
}
diff --git a/fli-js/src/search/exceptions.ts b/fli-js/src/search/exceptions.ts
index 02f86d1..810ef00 100644
--- a/fli-js/src/search/exceptions.ts
+++ b/fli-js/src/search/exceptions.ts
@@ -1,41 +1,97 @@
/**
* Typed errors raised by the search client.
* Mirrors fli/search/exceptions.py.
+ *
+ * These exist so consumers can react to a network failure with a clear,
+ * user-facing message instead of a raw `fetch` error. They are
+ * intentionally light wrappers — the original error is kept as `cause`
+ * where one exists.
*/
export class SearchClientError extends Error {
- constructor(message: string) {
- super(message);
+ constructor(message: string, options?: { cause?: unknown }) {
+ super(message, options);
this.name = "SearchClientError";
}
}
export class SearchTimeoutError extends SearchClientError {
- constructor(message: string) {
- super(message);
+ constructor(message: string, options?: { cause?: unknown }) {
+ super(message, options);
this.name = "SearchTimeoutError";
}
}
export class SearchConnectionError extends SearchClientError {
- constructor(message: string) {
- super(message);
+ constructor(message: string, options?: { cause?: unknown }) {
+ super(message, options);
this.name = "SearchConnectionError";
}
}
export class SearchHTTPError extends SearchClientError {
status_code: number | null;
- constructor(message: string, statusCode: number | null = null) {
- super(message);
+ constructor(message: string, statusCode: number | null = null, options?: { cause?: unknown }) {
+ super(message, options);
this.name = "SearchHTTPError";
this.status_code = statusCode;
}
}
-export class SearchParseError extends Error {
- constructor(message: string) {
- super(message);
+/**
+ * Google answered HTTP 200 but declined to serve results.
+ *
+ * The response carries a `wrb.fr` row with no payload and an error code
+ * (13 = INTERNAL). Since 2026-08 `GetShoppingResults` /
+ * `GetBookingResults` require an `x-goog-batchexecute-bgr` header signed
+ * by the page's own JavaScript over the exact request bytes, so a plain
+ * HTTP client always lands here. Without this error the caller saw an
+ * empty list and reported "no flights found", which is indistinguishable
+ * from a route with no service.
+ */
+export class SearchRejectedError extends SearchClientError {
+ code: number | null;
+ constructor(code: number | null = null) {
+ const suffix = code == null ? "" : ` (error ${code})`;
+ super(
+ `Google Flights declined the request${suffix} and returned no data. ` +
+ "Its API now requires a browser-signed x-goog-batchexecute-bgr header, " +
+ "which this client cannot produce. See github.com/punitarani/fli#223.",
+ );
+ this.name = "SearchRejectedError";
+ this.code = code;
+ }
+}
+
+/**
+ * The requested search cannot be served by the current transport.
+ *
+ * Distinct from an empty result: the query is well formed and Google
+ * would answer it in a browser, but the public search page carries no
+ * inline payload for it, so this client has nothing to read.
+ */
+export class SearchUnsupportedError extends SearchClientError {
+ constructor(message: string, options?: { cause?: unknown }) {
+ super(message, options);
+ this.name = "SearchUnsupportedError";
+ }
+}
+
+/**
+ * A successful HTTP response could not be parsed into flights.
+ *
+ * Distinct from network / HTTP errors: this says "Google responded but
+ * the shape changed", not "Google didn't respond". In practice it is
+ * either a consent/blocked page (no `ds:1` blob at all) or a change in
+ * the flight rows themselves.
+ *
+ * It belongs to the {@link SearchClientError} family so that callers
+ * already catching search failures classify it as one instead of an
+ * unexpected crash.
+ */
+export class SearchParseError extends SearchClientError {
+ constructor(message: string, options?: { cause?: unknown }) {
+ super(message, options);
this.name = "SearchParseError";
}
}
diff --git a/fli-js/src/search/flights.ts b/fli-js/src/search/flights.ts
index 22c3e79..de6738d 100644
--- a/fli-js/src/search/flights.ts
+++ b/fli-js/src/search/flights.ts
@@ -1,26 +1,80 @@
/**
- * Flight search orchestrator — `GetShoppingResults` + `GetBookingResults`.
+ * Flight search orchestrator.
+ *
+ * Results come from Google's public `/travel/flights` page — see
+ * `tfs.ts` for why, and for the token that addresses it. Booking options
+ * still go through the `GetBookingResults` RPC, which is gated: that call
+ * now fails with {@link SearchRejectedError} rather than returning
+ * anything.
*
* 1:1 port of fli/search/flights.py.
*/
import type { GoogleFlightsUrlOptions } from "../core/links.ts";
import type { BookingOption, FlightResult } from "../models/google-flights/base.ts";
-import { SeatType, TripType } from "../models/google-flights/base.ts";
-import { FlightSearchFilters } from "../models/google-flights/flights.ts";
+import { SeatType, SortBy, TripType } from "../models/google-flights/base.ts";
+import type { FlightSearchFilters } from "../models/google-flights/flights.ts";
import { type Client, getClient } from "./client.ts";
-import { parallelMap } from "./concurrency.ts";
+import { cloneFilters } from "./clone.ts";
+import { parallelMap, throwIfAborted } from "./concurrency.ts";
import { parseBookingChunk, parseFlightRow } from "./decoders.ts";
import { SearchParseError } from "./exceptions.ts";
+import { getSearchLogger } from "./logging.ts";
import { buildBookingToken, buildTfsToken, type LegSpec } from "./proto.ts";
+import {
+ applyClientSideFilters,
+ buildTfs,
+ fetchPayload,
+ pageUrl,
+ unsupportedFilters,
+} from "./tfs.ts";
import { withLocaleParams } from "./urls.ts";
-import { iterWrbChunks, parseFirstWrbPayload } from "./wire.ts";
+import { iterWrbChunks } from "./wire.ts";
+
+/**
+ * Result ordering for `sortBy`.
+ *
+ * The search page serves Google's own default order, so the sort the
+ * caller asked for is applied here instead of in the request.
+ * `TOP_FLIGHTS` / `BEST` are Google's own blended rankings, which we
+ * can't reproduce — those keep the page's order.
+ */
+function sortFlights(flights: FlightResult[], sortBy: SortBy): void {
+ const rank = (f: FlightResult): [number, number] => {
+ switch (sortBy) {
+ case SortBy.CHEAPEST:
+ return [f.price == null ? 1 : 0, f.price ?? 0];
+ case SortBy.DURATION:
+ return [f.duration == null ? 1 : 0, f.duration ?? 0];
+ case SortBy.DEPARTURE_TIME:
+ return [0, f.legs[0]?.departure_datetime.getTime() ?? 0];
+ case SortBy.ARRIVAL_TIME:
+ return [0, f.legs[f.legs.length - 1]?.arrival_datetime.getTime() ?? 0];
+ default:
+ return [0, 0];
+ }
+ };
+ // `Array.prototype.sort` is required to be stable, so rows that tie on
+ // the key keep Google's own ordering — the same guarantee Python's
+ // `list.sort` gives.
+ flights.sort((a, b) => {
+ const ka = rank(a);
+ const kb = rank(b);
+ return ka[0] - kb[0] || ka[1] - kb[1];
+ });
+}
export interface SearchOptions {
topN?: number;
currency?: string | null;
language?: string | null;
country?: string | null;
+ /**
+ * Cancels the search. A round trip is several sequential page fetches
+ * with backoffs between them, so this reaches every one of them —
+ * including the sleeps — and rejects with the reason it was aborted with.
+ */
+ signal?: AbortSignal;
}
export interface BookingOptions {
@@ -29,6 +83,8 @@ export interface BookingOptions {
country?: string | null;
bookingToken?: string | null;
sessionId?: string | null;
+ /** Cancels the booking request. */
+ signal?: AbortSignal;
}
/** Locale knobs plus cabin class for {@link SearchFlights.buildFlightBookingUrl}. */
@@ -38,8 +94,19 @@ export interface BookingUrlOptions extends GoogleFlightsUrlOptions {
}
export class SearchFlights {
+ /**
+ * @deprecated Kept only so the exported surface does not move. Searches
+ * no longer POST here: `GetShoppingResults` requires a browser-signed
+ * `x-goog-batchexecute-bgr` header and answers every other client with
+ * error 13. Results come from `PAGE_URL` in `tfs.ts` instead.
+ */
static readonly BASE_URL =
"https://www.google.com/_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetShoppingResults";
+ /**
+ * The `GetBookingResults` RPC. Still used by {@link SearchFlights.getBookingOptions},
+ * and still gated the same way — that call currently throws
+ * `SearchRejectedError`.
+ */
static readonly BOOKING_URL =
"https://www.google.com/_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetBookingResults";
@@ -50,7 +117,19 @@ export class SearchFlights {
this.client = client ?? getClient();
}
- /** Search for flights using the given filters. */
+ /**
+ * Search for flights using the given filters.
+ *
+ * One page fetch for a one-way trip; for a round trip, one more per
+ * expanded outbound candidate (`topN`, default 5).
+ *
+ * @returns For one-way trips, `FlightResult[]`. For round trips, one
+ * array per itinerary (`[outbound, return]`). `null` when nothing
+ * survived the filters.
+ * @throws {SearchUnsupportedError} Multi-city, which the page cannot serve.
+ * @throws {SearchParseError} The page loaded but carried no readable rows.
+ * @throws {SearchClientError} Network or HTTP failure.
+ */
async search(
filters: FlightSearchFilters,
options: SearchOptions = {},
@@ -61,6 +140,7 @@ export class SearchFlights {
language: options.language ?? null,
country: options.country ?? null,
captureSession: true,
+ signal: options.signal,
});
if (flights == null) return null;
if (filters.trip_type === TripType.ONE_WAY) return flights;
@@ -69,6 +149,7 @@ export class SearchFlights {
currency: options.currency ?? null,
language: options.language ?? null,
country: options.country ?? null,
+ signal: options.signal,
});
}
@@ -79,18 +160,26 @@ export class SearchFlights {
language: string | null;
country: string | null;
captureSession: boolean;
+ signal?: AbortSignal;
},
): Promise<FlightResult[] | null> {
- const encoded = filters.encode();
- const url = withLocaleParams(
- SearchFlights.BASE_URL,
- opts.currency,
- opts.language,
- opts.country,
- );
- const response = await this.client.post(url, { body: `f.req=${encoded}` });
- const inner = parseFirstWrbPayload(response.text);
- if (inner == null) return null;
+ throwIfAborted(opts.signal);
+
+ const dropped = unsupportedFilters(filters);
+ if (dropped.length > 0) {
+ getSearchLogger().warn(
+ `Filters not supported by the search-page transport, ignored: ${dropped.join(", ")}`,
+ );
+ }
+
+ const url = pageUrl(buildTfs(filters), opts.currency, opts.language, opts.country);
+ const inner = await fetchPayload(this.client, url, { signal: opts.signal });
+ if (inner == null) {
+ throw new SearchParseError(
+ "Search page carried no ds:1 payload — Google may have changed " +
+ "the page shape, or served a consent/blocked page instead.",
+ );
+ }
if (opts.captureSession) this._captureSessionId(inner);
@@ -98,27 +187,76 @@ export class SearchFlights {
throw new SearchParseError("Shopping response shape changed — top-level is not an array");
}
+ // Mirrors Python's
+ // [item for i in (2, 3) if isinstance(inner[i], list) for item in inner[i][0]]
+ // wrapped in `except (IndexError, TypeError)`, condition for condition:
+ //
+ // slot missing entirely -> IndexError -> SearchParseError
+ // slot present, not a list -> skipped by the isinstance check
+ // slot is an empty list -> IndexError on [0] -> SearchParseError
+ // [0] is not iterable -> TypeError -> SearchParseError
+ // [0] is a list (even empty) -> those are the rows
+ //
+ // Skipping a missing structure and returning `null` instead would
+ // report the likeliest future Google change — rows moving out of
+ // `[2][0]` — as "no flights on this route", which is exactly the
+ // silent failure this transport exists to avoid. A block that is
+ // present and simply holds no rows stays a legitimate empty answer.
const flightsRaw: unknown[] = [];
- for (const i of [2, 3]) {
- const block = inner[i];
- if (Array.isArray(block) && Array.isArray(block[0])) {
- for (const item of block[0]) flightsRaw.push(item);
+ try {
+ for (const i of [2, 3]) {
+ if (i >= inner.length) {
+ throw new RangeError(`payload has ${inner.length} elements, no inner[${i}]`);
+ }
+ const block = inner[i];
+ if (!Array.isArray(block)) continue;
+ if (block.length === 0) {
+ throw new RangeError(`inner[${i}] is empty, no inner[${i}][0]`);
+ }
+ const rows = block[0];
+ // Python would iterate any iterable here; the only shape Google
+ // has ever served is a list, and anything else reaches
+ // SearchParseError there too (every "row" fails to parse), just
+ // by a longer route and with a less useful message.
+ if (!Array.isArray(rows)) {
+ throw new TypeError(`inner[${i}][0] is ${typeof rows}, not a list of rows`);
+ }
+ for (const item of rows) flightsRaw.push(item);
}
+ } catch (err) {
+ throw new SearchParseError(
+ "Shopping response shape changed — no flights array at inner[2]/[3]: " +
+ `${err instanceof Error ? err.message : String(err)}`,
+ { cause: err },
+ );
}
const flights: FlightResult[] = [];
const failureSamples: string[] = [];
let anyFailure = false;
+ const noteFailure = (reason: string): void => {
+ anyFailure = true;
+ if (!failureSamples.includes(reason) && failureSamples.length < 3) {
+ failureSamples.push(reason);
+ }
+ };
for (const row of flightsRaw) {
- if (!Array.isArray(row)) continue;
+ // A row that is not a list is a *failed* row, not an absent one.
+ // Python hands it to `parse_flight_row` and gets back
+ // `TypeError: 'int' object is not subscriptable`, which counts
+ // towards the "parsed 0 of N" tripwire below. Skipping it quietly
+ // meant a block of scalars came back as "no flights on this route".
+ // One bad row among good ones still costs only that row.
+ if (!Array.isArray(row)) {
+ noteFailure(`TypeError: '${row === null ? "null" : typeof row}' row is not subscriptable`);
+ continue;
+ }
try {
flights.push(parseFlightRow(row));
} catch (err) {
- anyFailure = true;
- const reason = `${err instanceof Error ? err.name : "Error"}: ${err instanceof Error ? err.message : String(err)}`;
- if (!failureSamples.includes(reason) && failureSamples.length < 3) {
- failureSamples.push(reason);
- }
+ noteFailure(
+ `${err instanceof Error ? err.name : "Error"}: ${err instanceof Error ? err.message : String(err)}`,
+ );
}
}
@@ -129,10 +267,24 @@ export class SearchFlights {
);
}
- return flights.length > 0 ? flights : null;
+ const kept = applyClientSideFilters(flights, filters);
+ sortFlights(kept, filters.sort_by);
+ return kept.length > 0 ? kept : null;
}
- /** Fetch bookable fare options for a selected itinerary. */
+ /**
+ * Fetch bookable fare options for a selected itinerary.
+ *
+ * Currently unavailable: this is the one call still made against the
+ * `GetBookingResults` RPC, which since 2026-08 requires an
+ * `x-goog-batchexecute-bgr` header signed by Google's own page
+ * JavaScript. Expect {@link SearchRejectedError}. Per-itinerary booking
+ * links are still available — see
+ * {@link SearchFlights.buildFlightBookingUrl}, which needs no network
+ * call at all.
+ *
+ * @throws {SearchRejectedError} Google declined the RPC (the normal outcome).
+ */
async getBookingOptions(
flight: FlightResult | FlightResult[],
filters: FlightSearchFilters,
@@ -197,7 +349,10 @@ export class SearchFlights {
options.language ?? null,
options.country ?? null,
);
- const response = await this.client.post(url, { body: `f.req=${encoded}` });
+ const response = await this.client.post(url, {
+ body: `f.req=${encoded}`,
+ ...(options.signal ? { signal: options.signal } : {}),
+ });
const chunks = [...iterWrbChunks(response.text)];
if (chunks.length === 0) return [];
@@ -268,13 +423,30 @@ export class SearchFlights {
);
}
+ /**
+ * Cache the shopping session id from `inner[0][4]` of a search payload.
+ *
+ * A shape change here means booking calls fall back to "missing token"
+ * errors, so it warns rather than silently leaving the cache untouched.
+ */
private _captureSessionId(inner: unknown): void {
- if (!Array.isArray(inner)) return;
- const first = inner[0];
- if (!Array.isArray(first)) return;
+ const first = Array.isArray(inner) ? inner[0] : undefined;
+ if (!Array.isArray(first)) {
+ getSearchLogger().warn(
+ "Failed to capture the shopping session id from the search page " +
+ "(payload[0] is not an array); getBookingOptions() calls without an " +
+ "explicit sessionId will fail.",
+ );
+ return;
+ }
const session = first[4];
if (typeof session === "string" && session.length > 0) {
this._lastSessionId = session;
+ } else {
+ getSearchLogger().warn(
+ `Search page payload[0][4] is ${JSON.stringify(session)}, not a non-empty ` +
+ "string; the session cache is unchanged.",
+ );
}
}
@@ -290,6 +462,7 @@ export class SearchFlights {
currency: string | null;
language: string | null;
country: string | null;
+ signal?: AbortSignal;
},
): Promise<Array<FlightResult[]>> {
const numSegments = filters.flight_segments.length;
@@ -311,6 +484,7 @@ export class SearchFlights {
language: opts.language,
country: opts.country,
captureSession: false,
+ signal: opts.signal,
});
if (subFlights == null) return [outbound, null];
if (selectedCount + 1 < numSegments - 1) {
@@ -354,39 +528,3 @@ export class SearchFlights {
return encodeURIComponent(JSON.stringify(wrapped));
}
}
-
-function cloneFilters(filters: FlightSearchFilters): FlightSearchFilters {
- // The constructor's date validator would re-reject past travel dates if
- // we ran it on a clone — bypass by writing fields directly.
- const out = Object.create(FlightSearchFilters.prototype) as FlightSearchFilters;
- Object.assign(out, {
- trip_type: filters.trip_type,
- passenger_info: { ...filters.passenger_info },
- flight_segments: filters.flight_segments.map((s) => {
- const clone = Object.create(Object.getPrototypeOf(s)) as typeof s;
- Object.assign(clone, {
- departure_airport: s.departure_airport,
- arrival_airport: s.arrival_airport,
- travel_date: s.travel_date,
- time_restrictions: s.time_restrictions,
- selected_flight: s.selected_flight,
- });
- return clone;
- }),
- stops: filters.stops,
- seat_type: filters.seat_type,
- price_limit: filters.price_limit ? { ...filters.price_limit } : null,
- airlines: filters.airlines ? [...filters.airlines] : null,
- airlines_exclude: filters.airlines_exclude ? [...filters.airlines_exclude] : null,
- alliances: filters.alliances ? [...filters.alliances] : null,
- alliances_exclude: filters.alliances_exclude ? [...filters.alliances_exclude] : null,
- max_duration: filters.max_duration,
- layover_restrictions: filters.layover_restrictions ? { ...filters.layover_restrictions } : null,
- sort_by: filters.sort_by,
- exclude_basic_economy: filters.exclude_basic_economy,
- emissions: filters.emissions,
- bags: filters.bags ? { ...filters.bags } : null,
- show_all_results: filters.show_all_results,
- });
- return out;
-}
diff --git a/fli-js/src/search/index.ts b/fli-js/src/search/index.ts
index cf557ab..428ec36 100644
--- a/fli-js/src/search/index.ts
+++ b/fli-js/src/search/index.ts
@@ -1,11 +1,27 @@
-export { Client, type ClientOptions, type ClientResponse, getClient } from "./client.ts";
+export {
+ Client,
+ type ClientOptions,
+ type ClientResponse,
+ DEFAULT_SOCS_COOKIE,
+ getClient,
+ resolveSocsCookie,
+} from "./client.ts";
+export { cloneFilters } from "./clone.ts";
export {
configureConcurrency,
getDefaultMaxWorkers,
parallelMap,
+ sleep,
TokenBucketRateLimiter,
} from "./concurrency.ts";
-export { type DatePrice, type DateSearchOptions, SearchDates } from "./dates.ts";
+export {
+ type DateOutcome,
+ type DatePrice,
+ type DateSearchOptions,
+ MAX_DATES_PER_SEARCH,
+ SearchDates,
+ SWEEP_FAILURE_THRESHOLD,
+} from "./dates.ts";
export {
parseBookingChunk,
parseFlightRow,
@@ -15,7 +31,9 @@ export {
SearchConnectionError,
SearchHTTPError,
SearchParseError,
+ SearchRejectedError,
SearchTimeoutError,
+ SearchUnsupportedError,
} from "./exceptions.ts";
export {
type BookingOptions,
@@ -23,14 +41,33 @@ export {
SearchFlights,
type SearchOptions,
} from "./flights.ts";
+export { getSearchLogger, type SearchLogger, setSearchLogger } from "./logging.ts";
export {
type BuildTfsTokenOptions,
buildBookingToken,
buildTfsToken,
decodeBookingToken,
+ type EncodeTfsPayloadOptions,
+ type EncodeTfsSegmentOptions,
+ encodeTfsPayload,
+ encodeTfsSegment,
extractBookingTokenFromTfu,
extractSessionIdFromTfu,
type LegSpec,
} from "./proto.ts";
+export {
+ applyClientSideFilters,
+ type BuildTfsOptions,
+ buildTfs,
+ extractPayload,
+ type FetchPayloadOptions,
+ fetchPayload,
+ PAGE_FETCH_ATTEMPTS,
+ PAGE_RETRY_BACKOFF_MS,
+ PAGE_URL,
+ pageUrl,
+ type TfsFilters,
+ unsupportedFilters,
+} from "./tfs.ts";
export { withLocaleParams } from "./urls.ts";
export { iterWrbChunks, parseFirstWrbPayload } from "./wire.ts";
diff --git a/fli-js/src/search/logging.ts b/fli-js/src/search/logging.ts
new file mode 100644
index 0000000..1c5eb0f
--- /dev/null
+++ b/fli-js/src/search/logging.ts
@@ -0,0 +1,48 @@
+/**
+ * The search client's warning channel.
+ *
+ * The Python library reports partial failures through `logging` — a
+ * dropped filter, a date whose page never arrived, a sweep cut short.
+ * Those messages are the difference between an honest partial answer and
+ * a silent one, so the port keeps them; JavaScript has no stdlib logger,
+ * so they go to `console.warn` by default and can be redirected or
+ * silenced with {@link setSearchLogger}.
+ *
+ * `debug` is a no-op by default, mirroring a Python logger left at its
+ * default level: the detail (stack traces in particular) stays available
+ * to anyone who asks for it and never lands on a user's stderr by
+ * accident.
+ */
+
+export interface SearchLogger {
+ /** One concise line about something the caller needs to know. */
+ warn(message: string): void;
+ /** Detail for diagnosis; silent unless a logger opts in. */
+ debug(message: string, error?: unknown): void;
+}
+
+const DEFAULT_LOGGER: SearchLogger = {
+ warn(message: string): void {
+ console.warn(`[fli] ${message}`);
+ },
+ debug(): void {
+ // Off by default.
+ },
+};
+
+let current: SearchLogger = DEFAULT_LOGGER;
+
+/**
+ * Replace the logger the search client writes to.
+ *
+ * Pass `null` to restore the default (`console.warn`). Pass an object
+ * with no-op methods to silence the client entirely.
+ */
+export function setSearchLogger(logger: SearchLogger | null): void {
+ current = logger ?? DEFAULT_LOGGER;
+}
+
+/** The logger in effect. */
+export function getSearchLogger(): SearchLogger {
+ return current;
+}
diff --git a/fli-js/src/search/proto.ts b/fli-js/src/search/proto.ts
index 3b88efd..0fa8904 100644
--- a/fli-js/src/search/proto.ts
+++ b/fli-js/src/search/proto.ts
@@ -355,6 +355,159 @@ export interface BuildTfsTokenOptions {
seat?: number;
}
+// `tfs` is the itinerary parameter shared by booking deep links and the
+// public search page. Both builders below write the same message, so the
+// field layout lives here once:
+//
+// 1 = 28 (constant) 8 = passenger kind, repeated
+// 2 = 2 (constant) 9 = cabin class
+// 3 = segment, repeated 14 = 1 (constant)
+// 3.2 = departure date 16 = max-uint64 pin (deep links only)
+// 3.4 = selected leg, rep. 19 = 2 one-way / multi-city, 1 round-trip
+// 3.5 = stop ceiling
+// 3.6 = carrier include, repeated (IATA code or alliance name)
+// 3.7 = carrier exclude, repeated (same values as 3.6)
+// 3.13 = origin 3.14 = destination
+// 3.15 = layover airport include, repeated
+// 3.17 = min layover minutes 3.18 = max layover minutes
+//
+// Reverse-engineered from live browser captures; 1:1 with the Python
+// `fli/search/_proto.py`.
+
+const MAX_U64 = (1n << 64n) - 1n;
+
+/** Optional per-segment restrictions Google reads out of the `tfs` segment. */
+export interface EncodeTfsSegmentOptions {
+ /**
+ * Physical flights pinned for this direction, if any. Supplying them
+ * narrows a search to itineraries that include them — that is how a
+ * round-trip search asks for return options against a chosen outbound.
+ */
+ legs?: readonly LegSpec[];
+ /**
+ * Stop ceiling, zero-based (`0` = non-stop, `1` = one stop or fewer).
+ * `null`/`undefined` leaves the search unconstrained; passing `0` for
+ * "any" would pin it to non-stop instead.
+ */
+ maxStops?: number | null;
+ /**
+ * Only itineraries on these carriers. Google takes airline IATA codes
+ * and alliance names (`"STAR_ALLIANCE"`) in the same list.
+ */
+ carriers?: readonly string[];
+ /** The same values, as an exclude list. */
+ carriersExclude?: readonly string[];
+ /** Only these airports may be used as layover stops. */
+ layoverAirports?: readonly string[];
+ /** Minimum layover wait, in minutes. */
+ minLayover?: number | null;
+ /** Maximum layover wait, in minutes. */
+ maxLayover?: number | null;
+}
+
+/**
+ * Encode one travel direction of a `tfs` itinerary.
+ *
+ * @param origin IATA code (or codes) the direction departs from.
+ * @param dest IATA code (or codes) the direction arrives at.
+ * @param date Departure date in `YYYY-MM-DD` format.
+ * @returns The length-delimited field 3 bytes for this segment.
+ */
+export function encodeTfsSegment(
+ origin: string | readonly string[],
+ dest: string | readonly string[],
+ date: string,
+ options: EncodeTfsSegmentOptions = {},
+): Uint8Array {
+ const {
+ legs = [],
+ maxStops = null,
+ carriers = [],
+ carriersExclude = [],
+ layoverAirports = [],
+ minLayover = null,
+ maxLayover = null,
+ } = options;
+
+ let body = lengthDelim(2, utf8.encode(date));
+ if (maxStops != null) body = concatBytes(body, varintField(5, maxStops));
+ for (const code of carriers) body = concatBytes(body, lengthDelim(6, utf8.encode(code)));
+ for (const code of carriersExclude) body = concatBytes(body, lengthDelim(7, utf8.encode(code)));
+ for (const leg of legs) {
+ body = concatBytes(
+ body,
+ lengthDelim(
+ 4,
+ concatBytes(
+ lengthDelim(1, utf8.encode(leg.origin)),
+ lengthDelim(2, utf8.encode(leg.depDate)),
+ lengthDelim(3, utf8.encode(leg.dest)),
+ lengthDelim(5, utf8.encode(leg.airline)),
+ lengthDelim(6, utf8.encode(leg.flightNumber)),
+ ),
+ ),
+ );
+ }
+ for (const code of typeof origin === "string" ? [origin] : origin) {
+ body = concatBytes(
+ body,
+ lengthDelim(13, concatBytes(varintField(1, 1), lengthDelim(2, utf8.encode(code)))),
+ );
+ }
+ for (const code of typeof dest === "string" ? [dest] : dest) {
+ body = concatBytes(
+ body,
+ lengthDelim(14, concatBytes(varintField(1, 1), lengthDelim(2, utf8.encode(code)))),
+ );
+ }
+ for (const code of layoverAirports) body = concatBytes(body, lengthDelim(15, utf8.encode(code)));
+ if (minLayover != null) body = concatBytes(body, varintField(17, minLayover));
+ if (maxLayover != null) body = concatBytes(body, varintField(18, maxLayover));
+ return lengthDelim(3, body);
+}
+
+/** Envelope options for {@link encodeTfsPayload}. */
+export interface EncodeTfsPayloadOptions {
+ /**
+ * `true` for one-way, `false` for round-trip. Controls field 19.
+ * Multi-city is a third value (3) that the search page cannot serve.
+ */
+ isOneWay: boolean;
+ /**
+ * Passenger kind codes, one entry per traveller (1 = adult, 2 = child,
+ * 3 = infant on lap, 4 = infant in own seat). The two infant codes are
+ * the ones to get right: a lap infant prices at ~10% of the adult fare
+ * and an infant in its own seat at ~100%, and transposing them produces
+ * a plausible wrong quote rather than an error.
+ */
+ passengers?: readonly number[];
+ /** Cabin class (1 = economy, 2 = premium, 3 = business, 4 = first). */
+ seat?: number;
+ /**
+ * Emit the field 16 constant that booking deep links carry. The search
+ * page does not need it.
+ */
+ pinMaxU64?: boolean;
+}
+
+/**
+ * Wrap encoded segments in the `tfs` envelope and base64 it.
+ *
+ * @param segments Concatenated output of {@link encodeTfsSegment}.
+ * @returns URL-safe base64 string with padding stripped.
+ */
+export function encodeTfsPayload(segments: Uint8Array, options: EncodeTfsPayloadOptions): string {
+ const { isOneWay, passengers = [1], seat = 1, pinMaxU64 = false } = options;
+ let payload = concatBytes(varintField(1, 28), varintField(2, 2), segments);
+ for (const kind of passengers) payload = concatBytes(payload, varintField(8, kind));
+ payload = concatBytes(payload, varintField(9, seat), varintField(14, 1));
+ if (pinMaxU64) {
+ payload = concatBytes(payload, lengthDelim(16, concatBytes(tag(1, 0), varintBig(MAX_U64))));
+ }
+ payload = concatBytes(payload, varintField(19, isOneWay ? 2 : 1));
+ return toUrlsafeB64(payload);
+}
+
/**
* Build the `tfs` query parameter for a Google Flights deep-link URL.
*
@@ -378,41 +531,13 @@ export function buildTfsToken(segments: LegSpec[][], options: BuildTfsTokenOptio
let segmentProtos: Uint8Array = new Uint8Array(0);
for (const seg of segments) {
- let legsProto: Uint8Array = new Uint8Array(0);
- for (const leg of seg) {
- const legProto = concatBytes(
- lengthDelim(1, utf8.encode(leg.origin)),
- lengthDelim(2, utf8.encode(leg.depDate)),
- lengthDelim(3, utf8.encode(leg.dest)),
- lengthDelim(5, utf8.encode(leg.airline)),
- lengthDelim(6, utf8.encode(leg.flightNumber)),
- );
- legsProto = concatBytes(legsProto, lengthDelim(4, legProto));
- }
-
const first = seg[0] as LegSpec;
const last = seg[seg.length - 1] as LegSpec;
- const segProto = concatBytes(
- lengthDelim(2, utf8.encode(first.depDate)),
- legsProto,
- lengthDelim(13, concatBytes(varintField(1, 1), lengthDelim(2, utf8.encode(first.origin)))),
- lengthDelim(14, concatBytes(varintField(1, 1), lengthDelim(2, utf8.encode(last.dest)))),
+ segmentProtos = concatBytes(
+ segmentProtos,
+ encodeTfsSegment(first.origin, last.dest, first.depDate, { legs: seg }),
);
- segmentProtos = concatBytes(segmentProtos, lengthDelim(3, segProto));
}
- const MAX_U64 = (1n << 64n) - 1n;
- const f19 = isOneWay ? 2 : 1;
-
- const payload = concatBytes(
- varintField(1, 28),
- varintField(2, 2),
- segmentProtos,
- varintField(8, 1),
- varintField(9, seat), // 1=economy 2=premium 3=business 4=first
- varintField(14, 1),
- lengthDelim(16, concatBytes(tag(1, 0), varintBig(MAX_U64))),
- varintField(19, f19),
- );
- return toUrlsafeB64(payload);
+ return encodeTfsPayload(segmentProtos, { isOneWay, seat, pinMaxU64: true });
}
diff --git a/fli-js/src/search/tfs.ts b/fli-js/src/search/tfs.ts
new file mode 100644
index 0000000..5c88ab9
--- /dev/null
+++ b/fli-js/src/search/tfs.ts
@@ -0,0 +1,413 @@
+/**
+ * Search transport built on Google Flights' public `/travel/flights` page.
+ *
+ * Since 2026-08 the `FlightsFrontendService` RPC endpoints
+ * (`GetShoppingResults`, `GetCalendarGraph`) require an
+ * `x-goog-batchexecute-bgr` header that only the page's own JavaScript can
+ * produce. The signature is bound to the exact request bytes, so a captured
+ * token cannot be replayed against a different body — every plain HTTP
+ * client gets HTTP 200 with a payload-less `wrb.fr` row carrying error 13.
+ *
+ * The public search page is not gated that way. It serves the same result
+ * payload inline, in an `AF_initDataCallback` blob keyed `ds:1`, whose
+ * elements `[2]` and `[3]` hold exactly the flight rows the RPC used to
+ * return — so `decoders.ts` keeps working untouched. The page is addressed
+ * by a `tfs` protobuf parameter instead of the `f.req` JSON struct, which
+ * is what this module builds.
+ *
+ * Scope note: `tfs` carries trip type, segments, stop limit, cabin,
+ * passengers, alliances and layover restrictions. Filters with no known
+ * `tfs` field (airline include/exclude, price cap, duration, departure
+ * window) are applied to the decoded results instead — see
+ * {@link applyClientSideFilters}. Anything that can be neither encoded nor
+ * filtered after the fact is reported by {@link unsupportedFilters} so the
+ * caller can warn rather than silently return results that ignore it.
+ *
+ * Multi-city is out of reach here entirely: the page inlines no rows for
+ * it, so {@link buildTfs} refuses those searches rather than returning the
+ * first leg's one-way board.
+ *
+ * 1:1 port of fli/search/_tfs.py.
+ */
+
+import type { Airline } from "../models/airline.ts";
+import type {
+ FlightResult,
+ FlightSegment,
+ TimeRestrictions,
+} 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 { FlightSearchFilters } from "../models/google-flights/flights.ts";
+import type { Client } from "./client.ts";
+import { sleep, throwIfAborted } from "./concurrency.ts";
+import { SearchUnsupportedError } from "./exceptions.ts";
+import { getSearchLogger } from "./logging.ts";
+import { encodeTfsPayload, encodeTfsSegment, type LegSpec } from "./proto.ts";
+
+/** Filter objects this transport can encode — both carry the same core fields. */
+export type TfsFilters = FlightSearchFilters | DateSearchFilters;
+
+export const PAGE_URL = "https://www.google.com/travel/flights";
+
+/**
+ * How many times one page is fetched before giving up on its `ds:1` blob.
+ *
+ * Roughly one page in sixty comes back HTTP 200 with every other
+ * `AF_initDataCallback` block present but no `ds:1` one — a transient
+ * variant, not a block: the identical request succeeds seconds later. A
+ * round trip fetches six pages and a date sweep one per date, so at that
+ * rate an unretried search fails noticeably often.
+ *
+ * Retry only this exact case. HTTP errors and error-13 rejections are
+ * already handled (and retried, where appropriate) by the client, and
+ * re-fetching them here would just multiply a hard failure. Worst case is
+ * 3 fetches per page, so a healthy N-date sweep stays N requests.
+ */
+export const PAGE_FETCH_ATTEMPTS = 3;
+
+/** Backoff in milliseconds between page fetch attempts. */
+export const PAGE_RETRY_BACKOFF_MS = [500, 1500] as const;
+
+type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
+
+let sleepImpl: SleepFn = sleep;
+
+/**
+ * Replace the page-retry backoff (test seam).
+ *
+ * Pass `null` to restore the real `setTimeout` sleep. Mirrors the
+ * `_tfs._sleep` indirection the Python tests patch, so a retry test can
+ * observe the backoff without waiting two seconds for it.
+ */
+export function _setPageRetrySleep(fn: SleepFn | null): void {
+ sleepImpl = fn ?? sleep;
+}
+
+// `AF_initDataCallback({key: 'ds:1', hash: '..', data:[...], sideChannel: {}});`
+const DS_BLOB = /AF_initDataCallback\((\{[\s\S]*?\})\);/g;
+const DS_KEY = /key:\s*'([^']+)'/;
+const DS_DATA = /data:([\s\S]*?), sideChannel/;
+
+/**
+ * Passenger kinds, in the order Google's repeated field 8 numbers them:
+ * 1 = adult, 2 = child, 3 = infant on lap, 4 = infant in own seat.
+ *
+ * The two infant codes are easy to transpose and the mistake is expensive
+ * rather than loud: on an international route a lap infant prices at ~10%
+ * of the adult fare and an infant in its own seat at ~100%, so a swap
+ * quotes a plausible but wrong fare instead of erroring. Pricing one fixed
+ * itinerary (BA178 JFK->LHR, economy) confirms the mapping — $295 for
+ * `[1]`, $324 for `[1, 3]` (+10%, lap), $589 for `[1, 4]` (+100%, own
+ * seat, same as the `[1, 2]` child fare). The legacy RPC struct orders the
+ * same four counts `[adults, children, infants_on_lap, infants_in_seat]`.
+ */
+const PASSENGER_FIELDS = [
+ ["adults", 1],
+ ["children", 2],
+ ["infants_on_lap", 3],
+ ["infants_in_seat", 4],
+] as const;
+
+/**
+ * Filters with no `tfs` encoding and no reliable post-hoc equivalent —
+ * the decoded rows don't carry the data needed to apply them locally.
+ */
+const UNSUPPORTED = ["emissions", "bags", "exclude_basic_economy"] as const;
+
+/** Return the bare IATA code for an Airport/Airline constant. */
+function iata(value: unknown): string {
+ return String(value).replace(/^_/, "");
+}
+
+/** Read a segment's airport list as flat IATA codes. */
+function airportCodes(entries: ReadonlyArray<ReadonlyArray<readonly [string, number]>>): string[] {
+ const out: string[] = [];
+ for (const group of entries) {
+ for (const entry of group) out.push(iata(entry[0]));
+ }
+ return out;
+}
+
+/** Format a `Date` as `YYYY-MM-DD` using its local components. */
+function localDate(d: Date): string {
+ const y = d.getFullYear();
+ const m = String(d.getMonth() + 1).padStart(2, "0");
+ const day = String(d.getDate()).padStart(2, "0");
+ return `${y}-${m}-${day}`;
+}
+
+/** Describe a chosen itinerary as the leg specs `tfs` pins it by. */
+function legsOf(flight: FlightResult): LegSpec[] {
+ return flight.legs.map((leg) => ({
+ origin: iata(leg.departure_airport),
+ depDate: localDate(leg.departure_datetime),
+ dest: iata(leg.arrival_airport),
+ airline: iata(leg.airline),
+ flightNumber: String(leg.flight_number),
+ }));
+}
+
+export interface BuildTfsOptions {
+ /**
+ * Per-segment date overrides, used by the date sweep to reprice one
+ * segment set across a range without cloning the whole filter object
+ * per day.
+ */
+ travelDates?: readonly string[] | null;
+}
+
+/**
+ * Build the `tfs` URL parameter for `filters`.
+ *
+ * @returns The base64url `tfs` value, unpadded, as Google's own URLs carry it.
+ * @throws {SearchUnsupportedError} For multi-city trips, which this
+ * transport cannot serve at all.
+ */
+export function buildTfs(filters: TfsFilters, options: BuildTfsOptions = {}): string {
+ // Field 19 is the trip type. Multi-city is 3, but sending 2 (one-way)
+ // makes Google ignore every segment past the first and serve the first
+ // leg's one-way board, which decodes cleanly into wrong results;
+ // sending 3 renders the right board in a browser but inlines no flight
+ // rows — multi-city is fetched client-side through the RPC gated since
+ // 2026-08.
+ if (filters.trip_type === TripType.MULTI_CITY) {
+ throw new SearchUnsupportedError(
+ "Multi-city search is not available through the search-page transport: " +
+ "Google loads those results client-side through the gated RPC, so the " +
+ "page carries no rows to read. Search each leg separately. " +
+ "See github.com/punitarani/fli#223.",
+ );
+ }
+
+ const travelDates = options.travelDates ?? null;
+ const stops = filters.stops;
+ const passengers: number[] = [];
+ for (const [field, code] of PASSENGER_FIELDS) {
+ const count = filters.passenger_info[field] ?? 0;
+ for (let i = 0; i < count; i++) passengers.push(code);
+ }
+
+ // Google reads alliances out of the same carrier lists as airline codes.
+ const carriers = (filters.alliances ?? []).map((a) => String(a));
+ const carriersExclude = (filters.alliances_exclude ?? []).map((a) => String(a));
+ const layovers = filters.layover_restrictions;
+
+ const parts: Uint8Array[] = [];
+ filters.flight_segments.forEach((segment: FlightSegment, index: number) => {
+ const selected = segment.selected_flight;
+ parts.push(
+ encodeTfsSegment(
+ airportCodes(
+ segment.departure_airport as ReadonlyArray<ReadonlyArray<readonly [string, number]>>,
+ ),
+ airportCodes(
+ segment.arrival_airport as ReadonlyArray<ReadonlyArray<readonly [string, number]>>,
+ ),
+ travelDates ? (travelDates[index] ?? segment.travel_date) : segment.travel_date,
+ {
+ legs: selected != null ? legsOf(selected) : [],
+ // MaxStops.ANY (0) must leave the field out — writing 0 for it
+ // would silently pin every search to non-stop.
+ maxStops: stops ? stops - 1 : null,
+ carriers,
+ carriersExclude,
+ layoverAirports: (layovers?.airports ?? []).map(iata),
+ minLayover: layovers?.min_duration ?? null,
+ maxLayover: layovers?.max_duration ?? null,
+ },
+ ),
+ );
+ });
+
+ let total = 0;
+ for (const part of parts) total += part.length;
+ const segments = new Uint8Array(total);
+ let offset = 0;
+ for (const part of parts) {
+ segments.set(part, offset);
+ offset += part.length;
+ }
+
+ return encodeTfsPayload(segments, {
+ isOneWay: filters.trip_type === TripType.ONE_WAY,
+ passengers: passengers.length > 0 ? passengers : [1],
+ seat: filters.seat_type,
+ });
+}
+
+/** Build the search-page URL for a `tfs` value and locale. */
+export function pageUrl(
+ tfs: string,
+ currency?: string | null,
+ language?: string | null,
+ country?: string | null,
+): string {
+ const params = [`tfs=${tfs}`, `hl=${language || "en"}`, `gl=${country || "US"}`];
+ if (currency) params.push(`curr=${currency}`);
+ return `${PAGE_URL}?${params.join("&")}`;
+}
+
+/**
+ * Pull the `ds:1` payload out of a rendered search page.
+ *
+ * Returns the same structure the RPC used to hand back, so callers can
+ * keep reading `payload[2]` / `payload[3]` for flight rows.
+ */
+export function extractPayload(html: string): unknown {
+ DS_BLOB.lastIndex = 0;
+ let match: RegExpExecArray | null = DS_BLOB.exec(html);
+ while (match !== null) {
+ const blob = match[1] ?? "";
+ const key = DS_KEY.exec(blob);
+ if (key && key[1] === "ds:1") {
+ const data = DS_DATA.exec(blob);
+ if (data?.[1] != null) {
+ try {
+ return JSON.parse(data[1]);
+ } catch (err) {
+ // One concise line. This sits on the per-page path, which the
+ // retry below runs up to three times and a date sweep runs once
+ // per date — a stack trace here would put hundreds of them on a
+ // user's stderr. The detail stays at debug.
+ getSearchLogger().warn(
+ `ds:1 blob is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+ );
+ getSearchLogger().debug("ds:1 blob decode failed", err);
+ return null;
+ }
+ }
+ }
+ match = DS_BLOB.exec(html);
+ }
+ return null;
+}
+
+export interface FetchPayloadOptions {
+ /** Propagated to the client so a caller can cancel the fetch. */
+ signal?: AbortSignal;
+}
+
+/**
+ * Fetch a search page and return its `ds:1` payload, or `null`.
+ *
+ * The single entry point both the flight search and the date sweep use,
+ * so the transient-page retry described at {@link PAGE_FETCH_ATTEMPTS}
+ * applies identically to each. Only a 200 with no `ds:1` blob is retried;
+ * HTTP and network errors propagate on the first attempt exactly as
+ * before.
+ *
+ * @returns The decoded payload, or `null` when every attempt came back
+ * without one — the caller decides whether that is fatal.
+ */
+export async function fetchPayload(
+ client: Client,
+ url: string,
+ options: FetchPayloadOptions = {},
+): Promise<unknown> {
+ for (let attempt = 0; attempt < PAGE_FETCH_ATTEMPTS; attempt++) {
+ throwIfAborted(options.signal);
+ const response = await client.get(url, options.signal ? { signal: options.signal } : {});
+ const payload = extractPayload(response.text);
+ if (payload != null) {
+ if (attempt > 0) {
+ getSearchLogger().debug(`Search page carried ds:1 on attempt ${attempt + 1}`);
+ }
+ return payload;
+ }
+ if (attempt + 1 < PAGE_FETCH_ATTEMPTS) {
+ const delay =
+ PAGE_RETRY_BACKOFF_MS[Math.min(attempt, PAGE_RETRY_BACKOFF_MS.length - 1)] ?? 500;
+ getSearchLogger().debug(
+ `Search page carried no ds:1 payload (attempt ${attempt + 1}/${PAGE_FETCH_ATTEMPTS}); retrying in ${delay}ms`,
+ );
+ await sleepImpl(delay, options.signal);
+ }
+ }
+ return null;
+}
+
+/** Name the set filters this transport can neither encode nor emulate. */
+export function unsupportedFilters(filters: TfsFilters): string[] {
+ const named: string[] = [];
+ for (const attr of UNSUPPORTED) {
+ const value = (filters as unknown as Record<string, unknown>)[attr];
+ if (value == null || value === false) continue;
+ if (Array.isArray(value) && value.length === 0) continue;
+ // `EmissionsFilter.ALL` (0) is "unset" for our purposes.
+ if (attr === "emissions" && value === 0) continue;
+ named.push(attr);
+ }
+ return named;
+}
+
+/**
+ * Apply the filters `tfs` has no field for, to already-decoded rows.
+ *
+ * Google would have applied these server-side and back-filled the result
+ * list, so a filtered search returns fewer options here than the old RPC
+ * did — but every option it does return honours the filter.
+ */
+export function applyClientSideFilters(
+ flights: readonly FlightResult[],
+ filters: TfsFilters,
+): FlightResult[] {
+ const airlines = new Set((filters.airlines ?? []).map((a: Airline) => iata(a)));
+ const excluded = new Set((filters.airlines_exclude ?? []).map((a: Airline) => iata(a)));
+ const maxDuration = filters.max_duration ?? null;
+ const maxPrice = filters.price_limit?.max_price ?? null;
+
+ // These rows describe whichever segment the caller is still choosing,
+ // not necessarily the outbound one. Round-trip expansion pins a segment
+ // by setting its `selected_flight` and re-fetches, so the flights coming
+ // back belong to the first segment that is still unpinned. Filtering a
+ // return leg against the outbound window drops valid evening returns and
+ // keeps invalid ones, silently and in the caller's favour-looking
+ // direction.
+ const segments = filters.flight_segments;
+ let active = segments.findIndex((s: FlightSegment) => s.selected_flight == null);
+ if (active === -1) active = Math.max(0, segments.length - 1);
+ const window = segments.length > 0 ? (segments[active]?.time_restrictions ?? null) : null;
+
+ const out: FlightResult[] = [];
+ for (const flight of flights) {
+ const carriers = new Set(flight.legs.map((l) => iata(l.airline)));
+ if (airlines.size > 0 && ![...carriers].some((c) => airlines.has(c))) continue;
+ if (excluded.size > 0 && [...carriers].some((c) => excluded.has(c))) continue;
+ if (maxDuration != null && flight.duration && flight.duration > maxDuration) continue;
+ if (maxPrice != null && flight.price && flight.price > maxPrice) continue;
+ if (!withinWindow(flight, window)) continue;
+ out.push(flight);
+ }
+ return out;
+}
+
+/**
+ * Check a flight's departure/arrival hours against a segment's window.
+ *
+ * `FlightResult.legs` has no minimum length and `parseFlightRow` happily
+ * returns a row whose `detail[2]` was empty, so an unguarded `legs[0]`
+ * here would throw out of the whole search on one odd row. A flight with
+ * no legs has no departure time to judge, so it cannot satisfy a time
+ * window — drop it rather than crash.
+ */
+function withinWindow(flight: FlightResult, restrictions: TimeRestrictions | null): boolean {
+ if (restrictions == null) return true;
+ const first = flight.legs[0];
+ const last = flight.legs[flight.legs.length - 1];
+ if (first == null || last == null) return false;
+ const departure = first.departure_datetime.getHours();
+ const arrival = last.arrival_datetime.getHours();
+ const checks: Array<[number | null | undefined, number, "min" | "max"]> = [
+ [restrictions.earliest_departure, departure, "min"],
+ [restrictions.latest_departure, departure, "max"],
+ [restrictions.earliest_arrival, arrival, "min"],
+ [restrictions.latest_arrival, arrival, "max"],
+ ];
+ for (const [bound, actual, kind] of checks) {
+ if (bound == null) continue;
+ if (kind === "min" && actual < bound) return false;
+ if (kind === "max" && actual > bound) return false;
+ }
+ return true;
+}
diff --git a/fli-js/src/search/wire.ts b/fli-js/src/search/wire.ts
index b453582..63a65b4 100644
--- a/fli-js/src/search/wire.ts
+++ b/fli-js/src/search/wire.ts
@@ -8,6 +8,8 @@
* so the parser operates on `Uint8Array` rather than the JS string.
*/
+import { SearchRejectedError } from "./exceptions.ts";
+
const PREFIX = ")]}'";
const PREFIX_BYTES = new TextEncoder().encode(PREFIX);
@@ -49,7 +51,17 @@ function* chunksFromOuter(outer: unknown): Generator<unknown> {
if (!Array.isArray(row) || row.length < 3) continue;
if (row[0] !== "wrb.fr") continue;
const inner = row[2];
- if (typeof inner !== "string" || inner.length === 0) continue;
+ if (typeof inner !== "string" || inner.length === 0) {
+ // Payload-less row: Google declined the call and parked an error
+ // code in slot 5. Throw instead of yielding nothing, so callers
+ // don't report a hard block as "no flights on this route".
+ const slot = row.length > 5 ? row[5] : null;
+ const code = Array.isArray(slot) && slot.length > 0 ? slot[0] : null;
+ if (typeof code === "number" && Number.isInteger(code)) {
+ throw new SearchRejectedError(code);
+ }
+ continue;
+ }
try {
yield JSON.parse(inner);
} catch {
@@ -71,12 +83,17 @@ export function* iterWrbChunks(body: string | Uint8Array): Generator<unknown> {
// Fast path: legacy single-chunk responses with no length headers.
const first = raw[0];
if (first === undefined || first < 0x30 || first > 0x39) {
+ let outer: unknown;
try {
- const outer = JSON.parse(decoder.decode(raw));
- yield* chunksFromOuter(outer);
+ outer = JSON.parse(decoder.decode(raw));
} catch {
// Discard malformed body.
+ return;
}
+ // Deliberately outside the `try`: `chunksFromOuter` throws
+ // `SearchRejectedError` on a payload-less row, and swallowing that
+ // would turn a hard rejection back into "no flights found".
+ yield* chunksFromOuter(outer);
return;
}
@@ -95,13 +112,15 @@ export function* iterWrbChunks(body: string | Uint8Array): Generator<unknown> {
const chunkBytes = Math.max(length - 1, 0);
const payload = raw.subarray(cursor, cursor + chunkBytes);
cursor += chunkBytes;
+ let outer: unknown;
try {
- const trimmed = decoder.decode(payload).trim();
- const outer = JSON.parse(trimmed);
- yield* chunksFromOuter(outer);
+ outer = JSON.parse(decoder.decode(payload).trim());
} catch {
// Discard malformed chunks.
+ continue;
}
+ // Outside the `try` — see the note in the single-chunk path above.
+ yield* chunksFromOuter(outer);
}
}
diff --git a/fli-js/tests/integration/public_api.test.ts b/fli-js/tests/integration/public_api.test.ts
index b39adab..83921e2 100644
--- a/fli-js/tests/integration/public_api.test.ts
+++ b/fli-js/tests/integration/public_api.test.ts
@@ -37,6 +37,36 @@ describe("Public API surface", () => {
expect(typeof fli.SearchConnectionError).toBe("function");
expect(typeof fli.SearchHTTPError).toBe("function");
expect(typeof fli.SearchParseError).toBe("function");
+ expect(typeof fli.SearchRejectedError).toBe("function");
+ expect(typeof fli.SearchUnsupportedError).toBe("function");
+ });
+
+ test("every search error is catchable as SearchClientError", () => {
+ // Consumers catch the base class to mean "the search failed"; a
+ // parse failure — which a consent or blocked page produces — has to
+ // land there too.
+ expect(new fli.SearchParseError("x")).toBeInstanceOf(fli.SearchClientError);
+ expect(new fli.SearchRejectedError(13)).toBeInstanceOf(fli.SearchClientError);
+ expect(new fli.SearchUnsupportedError("x")).toBeInstanceOf(fli.SearchClientError);
+ });
+
+ test("exports the search-page transport helpers", () => {
+ expect(typeof fli.buildTfs).toBe("function");
+ expect(typeof fli.pageUrl).toBe("function");
+ expect(typeof fli.extractPayload).toBe("function");
+ expect(typeof fli.fetchPayload).toBe("function");
+ expect(typeof fli.applyClientSideFilters).toBe("function");
+ expect(typeof fli.unsupportedFilters).toBe("function");
+ expect(fli.PAGE_URL).toBe("https://www.google.com/travel/flights");
+ expect(fli.PAGE_FETCH_ATTEMPTS).toBe(3);
+ });
+
+ test("exports the sweep limits and the consent-cookie knob", () => {
+ expect(fli.MAX_DATES_PER_SEARCH).toBe(93);
+ expect(fli.SWEEP_FAILURE_THRESHOLD).toBe(5);
+ expect(typeof fli.DEFAULT_SOCS_COOKIE).toBe("string");
+ expect(typeof fli.resolveSocsCookie).toBe("function");
+ expect(typeof fli.setSearchLogger).toBe("function");
});
test("exports core utilities", () => {
@@ -51,6 +81,9 @@ describe("Public API surface", () => {
expect(typeof fli.buildBookingToken).toBe("function");
expect(typeof fli.decodeBookingToken).toBe("function");
expect(typeof fli.extractBookingTokenFromTfu).toBe("function");
+ expect(typeof fli.buildTfsToken).toBe("function");
+ expect(typeof fli.encodeTfsSegment).toBe("function");
+ expect(typeof fli.encodeTfsPayload).toBe("function");
});
test("exports wire / urls helpers", () => {
diff --git a/fli-js/tests/integration/search_dates_stubbed.test.ts b/fli-js/tests/integration/search_dates_stubbed.test.ts
index e2d15ed..e948276 100644
--- a/fli-js/tests/integration/search_dates_stubbed.test.ts
+++ b/fli-js/tests/integration/search_dates_stubbed.test.ts
@@ -1,13 +1,29 @@
/**
* End-to-end test of SearchDates with a stubbed HTTP client.
+ *
+ * The date sweep used to POST one `GetCalendarGraph` request per 61-day
+ * chunk and read a whole price grid back. That RPC is gated, and the
+ * public search page carries no calendar grid, so every date now costs
+ * its own page fetch. These stubs were rewritten around that rather than
+ * deleted, and the tests that mattered — chunking, empty responses,
+ * price/date parsing — have equivalents below.
*/
import { describe, expect, test } from "bun:test";
+import { Airline } from "../../src/models/airline.ts";
import { Airport } from "../../src/models/airport.ts";
import { FlightSegment, TripType } from "../../src/models/google-flights/base.ts";
import { DateSearchFilters } from "../../src/models/google-flights/dates.ts";
import { Client } from "../../src/search/client.ts";
-import { SearchDates } from "../../src/search/dates.ts";
+import {
+ type DateOutcome,
+ MAX_DATES_PER_SEARCH,
+ SearchDates,
+ SWEEP_FAILURE_THRESHOLD,
+} from "../../src/search/dates.ts";
+import { SearchClientError, SearchParseError } from "../../src/search/exceptions.ts";
+import { setSearchLogger } from "../../src/search/logging.ts";
+import { _setPageRetrySleep } from "../../src/search/tfs.ts";
function futureDate(daysAhead = 30): string {
const d = new Date();
@@ -15,64 +31,137 @@ function futureDate(daysAhead = 30): string {
return d.toISOString().slice(0, 10);
}
-function calendarResponse(dates: Array<[string, number]>): string {
- // The price decoder walks data[-1] for an array of items.
- // item layout (one-way): [date, _, [[null, price], currency_token]]
- const items = dates.map(([date, price]) => [date, null, [[null, price], null]]);
- // Inner JSON is an array where the last element is `items`.
- const inner = [null, null, items];
- const outer = [["wrb.fr", null, JSON.stringify(inner)]];
- return `)]}'\n\n${JSON.stringify(outer)}`;
+/** A flight row `parseFlightRow` accepts, at the given price. */
+function flightRow(price: number, airline = "AA"): unknown {
+ const leg: unknown[] = [
+ airline,
+ null,
+ null,
+ "JFK",
+ null,
+ null,
+ "LAX",
+ null,
+ [12, 30],
+ null,
+ [16, 45],
+ 375,
+ null,
+ null,
+ null,
+ null,
+ null,
+ "Boeing 737",
+ null,
+ false,
+ [2026, 12, 25],
+ [2026, 12, 25],
+ [airline, "100"],
+ ];
+ while (leg.length < 32) leg.push(null);
+ const detail: unknown[] = Array.from({ length: 25 }, () => null);
+ detail[0] = airline;
+ detail[1] = ["American Airlines"];
+ detail[2] = [leg];
+ detail[9] = 375;
+ const row: unknown[] = Array.from({ length: 11 }, () => null);
+ row[0] = detail;
+ row[1] = [[null, price], null];
+ return row;
}
-describe("SearchDates.search (stubbed)", () => {
- test("decodes a synthetic calendar response into DatePrice array", async () => {
- const fakeFetch = async (): Promise<Response> =>
- new Response(
- calendarResponse([
- ["2026-07-15", 199.0],
- ["2026-07-16", 215.5],
- ["2026-07-17", 188.25],
- ]),
- { status: 200 },
- );
- const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
- const search = new SearchDates(client);
+/** Wrap flight rows as a rendered search page. */
+function searchPage(rows: unknown[]): string {
+ const payload: unknown[] = [null, null, [rows], null];
+ return `<script>AF_initDataCallback({key: 'ds:1', hash: '1', data:${JSON.stringify(payload)}, sideChannel: {}});</script>`;
+}
- const fromD = futureDate(10);
- const toD = futureDate(30);
- const filters = new DateSearchFilters({
- passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
- flight_segments: [
- new FlightSegment({
- departure_airport: [[[Airport.JFK, 0]]],
- arrival_airport: [[[Airport.LAX, 0]]],
- travel_date: fromD,
- }),
- ],
- from_date: fromD,
- to_date: toD,
+const BLANK_PAGE = "<html><body>consent wall</body></html>";
+
+/** A `DateOutcome` carrying a price, for driving `_collect` directly. */
+function priced(price: number): DateOutcome {
+ return {
+ price: { date: [new Date(2030, 0, 1)], price, currency: "USD" },
+ failure: null,
+ error: null,
+ attempted: true,
+ };
+}
+
+function oneWayFilters(fromAhead: number, toAhead: number): DateSearchFilters {
+ const fromD = futureDate(fromAhead);
+ return new DateSearchFilters({
+ passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LAX, 0]]],
+ travel_date: fromD,
+ }),
+ ],
+ from_date: fromD,
+ to_date: futureDate(toAhead),
+ });
+}
+
+function clientReturning(
+ handler: (url: string, call: number) => string | { body: string; status: number },
+): { client: Client; urls: string[] } {
+ const urls: string[] = [];
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ // The real 10 req/sec ceiling would make a 93-date sweep take ten
+ // seconds of wall clock for no extra coverage.
+ callsPerSecond: 10_000,
+ fetchImpl: (async (input: string | URL | Request) => {
+ urls.push(String(input));
+ const out = handler(String(input), urls.length);
+ if (typeof out === "string") return new Response(out, { status: 200 });
+ return new Response(out.body, { status: out.status });
+ }) as unknown as typeof fetch,
+ });
+ return { client, urls };
+}
+
+describe("SearchDates.search (stubbed)", () => {
+ test("prices every date in the range with its own page fetch", async () => {
+ const { client, urls } = clientReturning((_u, call) => searchPage([flightRow(100 + call)]));
+ const results = await new SearchDates(client).search(oneWayFilters(10, 14), {
+ currency: "USD",
});
+ // 10..14 inclusive is five dates, five pages.
+ expect(urls).toHaveLength(5);
+ expect(urls.every((u) => u.startsWith("https://www.google.com/travel/flights?"))).toBe(true);
+ expect(results).toHaveLength(5);
+ expect(results?.[0]?.date).toHaveLength(1);
+ expect(results?.[0]?.currency).toBe("USD");
+ });
- const results = await search.search(filters, { currency: "USD" });
- expect(results).not.toBeNull();
- expect(results).toHaveLength(3);
- expect(results?.[0]?.price).toBe(199.0);
- expect(results?.[2]?.price).toBe(188.25);
+ test("each date is priced at the cheapest flight on its page", async () => {
+ const { client } = clientReturning(() =>
+ searchPage([flightRow(400), flightRow(120), flightRow(250)]),
+ );
+ const results = await new SearchDates(client).search(oneWayFilters(10, 11));
+ expect(results?.map((r) => r.price)).toEqual([120, 120]);
});
- test("date range > 61 days splits into chunks", async () => {
- let callCount = 0;
- const fakeFetch = async (): Promise<Response> => {
- callCount++;
- return new Response(calendarResponse([["2026-07-15", 100.0]]), { status: 200 });
- };
- const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
- const search = new SearchDates(client);
+ test("client-side filters apply before the minimum is taken", async () => {
+ // The cheapest row is on an excluded carrier; taking the minimum
+ // before filtering would quote a fare the caller asked not to see.
+ const { client } = clientReturning(() =>
+ searchPage([flightRow(400, "AA"), flightRow(120, "DL")]),
+ );
+ const filters = oneWayFilters(10, 10);
+ filters.airlines_exclude = [Airline.DL];
+ const results = await new SearchDates(client).search(filters);
+ expect(results?.map((r) => r.price)).toEqual([400]);
+ });
+ test("a round trip prices the outbound and its return date", async () => {
const fromD = futureDate(10);
- const toD = futureDate(150); // 140-day range → 3 chunks
const filters = new DateSearchFilters({
+ trip_type: TripType.ROUND_TRIP,
passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
flight_segments: [
new FlightSegment({
@@ -80,63 +169,285 @@ describe("SearchDates.search (stubbed)", () => {
arrival_airport: [[[Airport.LAX, 0]]],
travel_date: fromD,
}),
+ new FlightSegment({
+ departure_airport: [[[Airport.LAX, 0]]],
+ arrival_airport: [[[Airport.JFK, 0]]],
+ travel_date: futureDate(17),
+ }),
],
from_date: fromD,
- to_date: toD,
+ to_date: futureDate(11),
+ duration: 7,
});
- await search.search(filters);
- // 141 days at 61 per chunk → 3 requests.
- expect(callCount).toBe(3);
+ const { client, urls } = clientReturning(() => searchPage([flightRow(300)]));
+ const results = await new SearchDates(client).search(filters);
+ expect(urls).toHaveLength(2);
+ expect(results).toHaveLength(2);
+ const pair = results?.[0]?.date as [Date, Date];
+ expect(pair).toHaveLength(2);
+ const gapDays = Math.round((pair[1].getTime() - pair[0].getTime()) / 86_400_000);
+ expect(gapDays).toBe(7);
});
- test("returns null on empty calendar response", async () => {
- const fakeFetch = async (): Promise<Response> =>
- new Response(calendarResponse([]), { status: 200 });
- const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
- const search = new SearchDates(client);
+ test("a date whose page has no flights is a legitimate empty answer", async () => {
+ const { client } = clientReturning((_u, call) =>
+ call === 1 ? searchPage([]) : searchPage([flightRow(200)]),
+ );
+ const results = await new SearchDates(client).search(oneWayFilters(10, 11));
+ expect(results).toHaveLength(1);
+ expect(results?.[0]?.price).toBe(200);
+ });
- const fromD = futureDate(10);
- const toD = futureDate(30);
+ test("every date having no flights returns null, not an error", async () => {
+ const { client } = clientReturning(() => searchPage([]));
+ expect(await new SearchDates(client).search(oneWayFilters(10, 12))).toBeNull();
+ });
+
+ test("one malformed row does not sink the sweep", async () => {
+ const { client } = clientReturning(() =>
+ searchPage(["not a row", flightRow(175), { nope: true }]),
+ );
+ const results = await new SearchDates(client).search(oneWayFilters(10, 11));
+ expect(results?.map((r) => r.price)).toEqual([175, 175]);
+ });
+
+ test("a reshaped payload yields no flights rather than throwing", async () => {
+ const page = `<script>AF_initDataCallback({key: 'ds:1', hash: '1', data:{"not":"an array"}, sideChannel: {}});</script>`;
+ const { client } = clientReturning(() => page);
+ expect(await new SearchDates(client).search(oneWayFilters(10, 11))).toBeNull();
+ });
+
+ test("dates already in the past are skipped without a request", async () => {
+ const { client, urls } = clientReturning(() => searchPage([flightRow(100)]));
+ // `FlightSegment` refuses a past travel date, so the segment stays on
+ // today and only the sweep's range reaches backwards.
const filters = new DateSearchFilters({
passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
flight_segments: [
new FlightSegment({
departure_airport: [[[Airport.JFK, 0]]],
arrival_airport: [[[Airport.LAX, 0]]],
- travel_date: fromD,
+ travel_date: futureDate(0),
}),
],
- from_date: fromD,
- to_date: toD,
+ from_date: futureDate(-3),
+ to_date: futureDate(2),
});
- const out = await search.search(filters);
- expect(out == null || (out?.length ?? 0) === 0).toBe(true);
+ const results = await new SearchDates(client).search(filters);
+ // Six dates in the range; the two before "today somewhere on Earth"
+ // are not bookable and cost no request at all.
+ expect(urls).toHaveLength(4);
+ expect(results).toHaveLength(4);
});
});
-describe("SearchDates static parsers", () => {
- test("_parsePrice extracts a numeric price", () => {
- expect(SearchDates._parsePrice(["2026-07-15", null, [[null, 199.5]]])).toBe(199.5);
- });
- test("_parsePrice returns null when shape is wrong", () => {
- expect(SearchDates._parsePrice([])).toBeNull();
- expect(SearchDates._parsePrice(["2026", null, [[null]]])).toBeNull();
- });
- test("_parseDate one-way returns single-element tuple", () => {
- const parsed = SearchDates._parseDate(["2026-07-15"], TripType.ONE_WAY);
- expect(parsed).toHaveLength(1);
- expect(parsed[0]).toBeInstanceOf(Date);
- });
- test("_parseDate rejects non-numeric date components", () => {
- // The canonical `parseIsoDate` in `core/dates.ts` checks the YYYY-MM-DD
- // shape with a regex first and rejects format errors with
- // `Expected YYYY-MM-DD`; out-of-range calendar dates produce
- // `Invalid date`. Either error is a valid rejection here.
- expect(() => SearchDates._parseDate(["2026-XX-15"], TripType.ONE_WAY)).toThrow(
- /Expected YYYY-MM-DD|Invalid date/,
- );
- expect(() => SearchDates._parseDate(["bad"], TripType.ONE_WAY)).toThrow(
- /Expected YYYY-MM-DD|Invalid date/,
+describe("SearchDates range cap", () => {
+ test(`a range above ${MAX_DATES_PER_SEARCH} dates is refused before any fetch`, async () => {
+ const { client, urls } = clientReturning(() => searchPage([flightRow(100)]));
+ const filters = oneWayFilters(1, 1 + MAX_DATES_PER_SEARCH);
+ await expect(new SearchDates(client).search(filters)).rejects.toThrow(
+ new RegExp(`${MAX_DATES_PER_SEARCH}-date limit`),
);
+ expect(urls).toHaveLength(0);
+ });
+
+ test(`exactly ${MAX_DATES_PER_SEARCH} dates is allowed`, async () => {
+ const { client, urls } = clientReturning(() => searchPage([flightRow(100)]));
+ // `from` .. `from + 92` inclusive is 93 dates.
+ const filters = oneWayFilters(1, MAX_DATES_PER_SEARCH);
+ const results = await new SearchDates(client).search(filters);
+ expect(urls).toHaveLength(MAX_DATES_PER_SEARCH);
+ expect(results).toHaveLength(MAX_DATES_PER_SEARCH);
+ });
+});
+
+describe("SearchDates failure reporting", () => {
+ const silence = () => setSearchLogger({ warn: () => {}, debug: () => {} });
+
+ test("every date failing raises instead of reporting an empty range", async () => {
+ _setPageRetrySleep(async () => {});
+ silence();
+ try {
+ const { client } = clientReturning(() => BLANK_PAGE);
+ // Three dates, all blocked — under the breaker threshold, so every
+ // one is actually attempted.
+ await expect(new SearchDates(client).search(oneWayFilters(10, 12))).rejects.toThrow(
+ SearchParseError,
+ );
+ } finally {
+ _setPageRetrySleep(null);
+ setSearchLogger(null);
+ }
+ });
+
+ test("a blocked sweep names the FLI_SOCS_COOKIE knob", async () => {
+ _setPageRetrySleep(async () => {});
+ silence();
+ try {
+ const { client } = clientReturning(() => BLANK_PAGE);
+ await expect(new SearchDates(client).search(oneWayFilters(10, 12))).rejects.toThrow(
+ /FLI_SOCS_COOKIE/,
+ );
+ } finally {
+ _setPageRetrySleep(null);
+ setSearchLogger(null);
+ }
+ });
+
+ test("the circuit breaker stops a sweep that has never loaded a page", async () => {
+ _setPageRetrySleep(async () => {});
+ silence();
+ try {
+ const { client, urls } = clientReturning(() => BLANK_PAGE);
+ const filters = oneWayFilters(10, 70); // 61 dates
+ await expect(new SearchDates(client).search(filters)).rejects.toThrow(SearchParseError);
+ // Each attempted date costs up to PAGE_FETCH_ATTEMPTS fetches, and
+ // the breaker trips once SWEEP_FAILURE_THRESHOLD dates have come
+ // back payload-less — far short of 61 dates' worth of requests.
+ expect(urls.length).toBeLessThan(61 * 3);
+ expect(urls.length).toBeGreaterThanOrEqual(SWEEP_FAILURE_THRESHOLD * 3);
+ } finally {
+ _setPageRetrySleep(null);
+ setSearchLogger(null);
+ }
+ });
+
+ test("the tripped breaker says how many dates it abandoned", async () => {
+ _setPageRetrySleep(async () => {});
+ silence();
+ try {
+ const { client } = clientReturning(() => BLANK_PAGE);
+ await expect(new SearchDates(client).search(oneWayFilters(10, 70))).rejects.toThrow(
+ /skipped/,
+ );
+ } finally {
+ _setPageRetrySleep(null);
+ setSearchLogger(null);
+ }
+ });
+
+ test("a network error does not arm the breaker", async () => {
+ silence();
+ try {
+ let calls = 0;
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ fetchImpl: (async () => {
+ calls++;
+ throw new TypeError("fetch failed");
+ }) as unknown as typeof fetch,
+ });
+ // A transient network fault says nothing about the dates not yet
+ // tried, so all 10 are attempted rather than abandoned after 5.
+ await expect(new SearchDates(client).search(oneWayFilters(10, 19))).rejects.toThrow(
+ SearchClientError,
+ );
+ expect(calls).toBe(10);
+ } finally {
+ setSearchLogger(null);
+ }
+ });
+
+ test("one success disarms the breaker for the rest of the sweep", async () => {
+ _setPageRetrySleep(async () => {});
+ silence();
+ try {
+ // The first date loads; everything after it is blocked. The sweep
+ // must still attempt every remaining date.
+ const seen = new Set<string>();
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ callsPerSecond: 10_000,
+ fetchImpl: (async (input: string | URL | Request) => {
+ const url = String(input);
+ const first = seen.size === 0;
+ seen.add(url);
+ return new Response(first ? searchPage([flightRow(150)]) : BLANK_PAGE, { status: 200 });
+ }) as unknown as typeof fetch,
+ });
+ const results = await new SearchDates(client).search(oneWayFilters(10, 30));
+ expect(results).toHaveLength(1);
+ // 21 distinct dates were all requested — none skipped.
+ expect(seen.size).toBe(21);
+ } finally {
+ _setPageRetrySleep(null);
+ setSearchLogger(null);
+ }
+ });
+
+ test("a partial sweep warns rather than returning quietly", () => {
+ // Driven through `_collect` directly: a sweep that trips the breaker
+ // *and* still has prices to show depends on which concurrent fetches
+ // happen to land first, which is not something to race in a test.
+ const warnings: string[] = [];
+ setSearchLogger({ warn: (m) => warnings.push(m), debug: () => {} });
+ let results: ReturnType<typeof SearchDates._collect>;
+ try {
+ results = SearchDates._collect(
+ [
+ priced(180),
+ priced(210),
+ { price: null, failure: "blocked", error: null, attempted: true },
+ ],
+ 30,
+ 24,
+ );
+ } finally {
+ setSearchLogger(null);
+ }
+ expect(results).toHaveLength(2);
+ const partial = warnings.filter((w) => w.includes("real but incomplete"));
+ expect(partial).toHaveLength(1);
+ expect(partial[0]).toContain("2 of 30");
+ expect(partial[0]).toContain("24 were skipped");
+ expect(partial[0]).toContain("FLI_SOCS_COOKIE");
+ });
+
+ test("a complete sweep says nothing about skipping", () => {
+ const warnings: string[] = [];
+ setSearchLogger({ warn: (m) => warnings.push(m), debug: () => {} });
+ try {
+ expect(SearchDates._collect([priced(180), priced(210)], 2, 0)).toHaveLength(2);
+ } finally {
+ setSearchLogger(null);
+ }
+ expect(warnings).toEqual([]);
+ });
+
+ test("a tripped breaker with nothing priced raises and names the count", () => {
+ setSearchLogger({ warn: () => {}, debug: () => {} });
+ try {
+ expect(() =>
+ SearchDates._collect(
+ [{ price: null, failure: "blocked", error: null, attempted: true }],
+ 30,
+ 29,
+ ),
+ ).toThrow(/29 skipped/);
+ } finally {
+ setSearchLogger(null);
+ }
+ });
+
+ test("a sweep where nothing was attempted at all returns null quietly", () => {
+ expect(
+ SearchDates._collect([{ price: null, failure: null, error: null, attempted: false }], 1, 0),
+ ).toBeNull();
+ });
+
+ test("unsupported filters are dropped with a warning", async () => {
+ const warnings: string[] = [];
+ setSearchLogger({ warn: (m) => warnings.push(m), debug: () => {} });
+ try {
+ const { client } = clientReturning(() => searchPage([flightRow(100)]));
+ const filters = oneWayFilters(10, 10);
+ filters.bags = { checked_bags: 2, carry_on: false };
+ await new SearchDates(client).search(filters);
+ } finally {
+ setSearchLogger(null);
+ }
+ expect(warnings.filter((w) => w.includes("bags"))).toHaveLength(1);
});
});
diff --git a/fli-js/tests/integration/search_flights_stubbed.test.ts b/fli-js/tests/integration/search_flights_stubbed.test.ts
index 1f710fa..2a93716 100644
--- a/fli-js/tests/integration/search_flights_stubbed.test.ts
+++ b/fli-js/tests/integration/search_flights_stubbed.test.ts
@@ -1,18 +1,36 @@
/**
* End-to-end test of SearchFlights with a stubbed HTTP client.
*
- * Builds a synthetic GetShoppingResults response, asserts the parser
- * decodes it into a FlightResult correctly, and asserts the request body
- * went out as the URL-encoded f.req payload.
+ * Builds a synthetic search page, asserts the parser decodes it into a
+ * FlightResult, and asserts the request went out as a GET for the
+ * `/travel/flights` page with the expected `tfs` token.
+ *
+ * These stubs used to encode the old `GetShoppingResults` POST shape
+ * (`f.req=` body, `wrb.fr` response). They were updated rather than
+ * deleted when the transport moved to the page, so the same behaviour
+ * stays covered.
*/
import { describe, expect, test } from "bun:test";
import { Airline } from "../../src/models/airline.ts";
import { Airport } from "../../src/models/airport.ts";
-import { FlightSegment, MaxStops, SeatType, SortBy } from "../../src/models/google-flights/base.ts";
+import {
+ FlightSegment,
+ MaxStops,
+ SeatType,
+ SortBy,
+ TripType,
+} from "../../src/models/google-flights/base.ts";
import { FlightSearchFilters } from "../../src/models/google-flights/flights.ts";
import { Client } from "../../src/search/client.ts";
+import {
+ SearchParseError,
+ SearchRejectedError,
+ SearchUnsupportedError,
+} from "../../src/search/exceptions.ts";
import { SearchFlights } from "../../src/search/flights.ts";
+import { setSearchLogger } from "../../src/search/logging.ts";
+import { _setPageRetrySleep, buildTfs } from "../../src/search/tfs.ts";
function futureDate(daysAhead = 30): string {
const d = new Date();
@@ -21,7 +39,9 @@ function futureDate(daysAhead = 30): string {
}
/** Build a minimal synthetic flight row that parseFlightRow accepts. */
-function syntheticFlightRow(): unknown {
+function syntheticFlightRow(
+ options: { airline?: string; price?: number; duration?: number; hour?: number } = {},
+): unknown {
// Position layout reverse-engineered from the Python decoder:
// row[0] = detail
// row[0][0] = primary airline code (string or null)
@@ -31,9 +51,12 @@ function syntheticFlightRow(): unknown {
// row[1] = price block = [[head], currency_token]
// row[1][0] = head; non-empty list with price at the END
// row[8] = booking_token
+ const airline = options.airline ?? "AA";
+ const duration = options.duration ?? 375;
+ const hour = options.hour ?? 12;
const leg = [
- "AA", // [0]
+ airline, // [0]
null, // [1]
null, // [2]
"JFK", // [3] departure
@@ -41,10 +64,10 @@ function syntheticFlightRow(): unknown {
null, // [5]
"LAX", // [6] arrival
null, // [7]
- [12, 30], // [8] departure time [h, m]
+ [hour, 30], // [8] departure time [h, m]
null, // [9]
- [16, 45], // [10] arrival time [h, m]
- 375, // [11] duration min
+ [hour + 4, 45], // [10] arrival time [h, m]
+ duration, // [11] duration min
null, // [12] amenities
null, // [13]
null, // [14] legroom_short
@@ -55,62 +78,73 @@ function syntheticFlightRow(): unknown {
false, // [19] overnight
[2026, 12, 25], // [20] departure date [y, m, d]
[2026, 12, 25], // [21] arrival date
- ["AA", "100"], // [22] [code, flight_no, op_code?]
+ [airline, "100"], // [22] [code, flight_no, op_code?]
];
// Pad leg out so .legroom_long / co2 indices don't blow up.
while (leg.length < 32) leg.push(null);
const detail: unknown[] = Array.from({ length: 25 }, () => null);
- detail[0] = "AA"; // primary_airline
+ detail[0] = airline; // primary_airline
detail[1] = ["American Airlines"]; // primary_airline_name
detail[2] = [leg]; // legs
- detail[9] = 375; // total duration
+ detail[9] = duration; // total duration
const row: unknown[] = Array.from({ length: 11 }, () => null);
row[0] = detail;
// Price block: head ends with the price value.
- row[1] = [[null, 199.99], null];
+ row[1] = [[null, options.price ?? 199.99], null];
row[8] = "tok-row-8";
return row;
}
-function syntheticShoppingResponse(flightRows: unknown[]): string {
- // inner[0][4] = session id
- // inner[2][0] = top flight rows
- const inner: unknown[] = Array.from({ length: 4 }, () => null);
- inner[0] = [null, null, null, null, "test-session-id"];
- inner[2] = [flightRows];
+/** Wrap a payload as the `ds:1` blob of a rendered search page. */
+function asSearchPage(payload: unknown): string {
+ return `<script>AF_initDataCallback({key: 'ds:0', hash: '1', data:["decoy"], sideChannel: {}});</script><script>AF_initDataCallback({key: 'ds:1', hash: '2', data:${JSON.stringify(payload)}, sideChannel: {}});</script>`;
+}
+
+function syntheticSearchPage(flightRows: unknown[]): string {
+ // payload[0][4] = session id
+ // payload[2][0] = "best" flight rows
+ const payload: unknown[] = Array.from({ length: 4 }, () => null);
+ payload[0] = [null, null, null, null, "test-session-id"];
+ payload[2] = [flightRows];
+ return asSearchPage(payload);
+}
- const outer = [["wrb.fr", null, JSON.stringify(inner)]];
- return `)]}'\n\n${JSON.stringify(outer)}`;
+function oneWayFilters(
+ overrides: Partial<ConstructorParameters<typeof FlightSearchFilters>[0]> = {},
+) {
+ return new FlightSearchFilters({
+ passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LAX, 0]]],
+ travel_date: futureDate(),
+ }),
+ ],
+ ...overrides,
+ });
}
describe("SearchFlights.search (stubbed)", () => {
- test("decodes a synthetic shopping response into FlightResult", async () => {
+ test("decodes a synthetic search page into FlightResult", async () => {
let capturedUrl = "";
- let capturedBody = "";
+ let capturedMethod = "";
+ let capturedBody: unknown;
const fakeFetch = async (
input: string | URL | Request,
init?: RequestInit,
): Promise<Response> => {
capturedUrl = String(input);
- capturedBody = String(init?.body ?? "");
- return new Response(syntheticShoppingResponse([syntheticFlightRow()]), {
- status: 200,
- });
+ capturedMethod = String(init?.method ?? "");
+ capturedBody = init?.body;
+ return new Response(syntheticSearchPage([syntheticFlightRow()]), { status: 200 });
};
const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
const search = new SearchFlights(client);
- const filters = new FlightSearchFilters({
- passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
- flight_segments: [
- new FlightSegment({
- departure_airport: [[[Airport.JFK, 0]]],
- arrival_airport: [[[Airport.LAX, 0]]],
- travel_date: futureDate(),
- }),
- ],
+ const filters = oneWayFilters({
stops: MaxStops.NON_STOP,
seat_type: SeatType.ECONOMY,
sort_by: SortBy.CHEAPEST,
@@ -124,71 +158,268 @@ describe("SearchFlights.search (stubbed)", () => {
expect(flight?.price).toBe(199.99);
expect(flight?.legs).toHaveLength(1);
- // URL carries the locale-param suffix.
- expect(capturedUrl).toContain("GetShoppingResults");
+ // A GET for the public search page, not a POST to the gated RPC.
+ expect(capturedMethod).toBe("GET");
+ expect(capturedBody).toBeUndefined();
+ expect(capturedUrl.startsWith("https://www.google.com/travel/flights?")).toBe(true);
+ expect(capturedUrl).toContain(`tfs=${buildTfs(filters)}`);
expect(capturedUrl).toContain("curr=USD");
-
- // Body starts with f.req= and is URL-encoded JSON.
- expect(capturedBody.startsWith("f.req=")).toBe(true);
- expect(decodeURIComponent(capturedBody.slice(6))).toContain("JFK");
- expect(decodeURIComponent(capturedBody.slice(6))).toContain("LAX");
+ expect(capturedUrl).toContain("hl=en");
+ expect(capturedUrl).toContain("gl=US");
});
test("session id captured for later booking calls", async () => {
const fakeFetch = async (): Promise<Response> =>
- new Response(syntheticShoppingResponse([syntheticFlightRow()]), { status: 200 });
+ new Response(syntheticSearchPage([syntheticFlightRow()]), { status: 200 });
const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
const search = new SearchFlights(client);
+ const warnings: string[] = [];
+ setSearchLogger({ warn: (m) => warnings.push(m), debug: () => {} });
+ try {
+ await search.search(oneWayFilters());
+ } finally {
+ setSearchLogger(null);
+ }
+ // The page carried a well-formed session id, so nothing was warned about.
+ expect(warnings).toEqual([]);
+ });
+ test("returns null when the page yields no parseable rows", async () => {
+ const fakeFetch = async (): Promise<Response> =>
+ new Response(syntheticSearchPage([]), { status: 200 });
+ const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
+ const search = new SearchFlights(client);
+ expect(await search.search(oneWayFilters())).toBeNull();
+ });
+
+ test("a page with no ds:1 blob raises instead of reporting no flights", async () => {
+ let calls = 0;
+ const fakeFetch = async (): Promise<Response> => {
+ calls++;
+ return new Response("<html><body>consent wall</body></html>", { status: 200 });
+ };
+ const client = new Client({
+ fetchImpl: fakeFetch as unknown as typeof fetch,
+ retries: 1,
+ backoffMs: 1,
+ });
+ const search = new SearchFlights(client);
+ _setPageRetrySleep(async () => {});
+ try {
+ await expect(search.search(oneWayFilters())).rejects.toThrow(SearchParseError);
+ } finally {
+ _setPageRetrySleep(null);
+ }
+ // Three page attempts, and no more — the client's own retry does not
+ // multiply with this one for a 200 response.
+ expect(calls).toBe(3);
+ });
+
+ describe("a shape-changed payload is a parse error, not 'no flights'", () => {
+ // Python raises SearchParseError when the payload loads but the row
+ // blocks are not where they should be. Returning null instead would
+ // report the likeliest future Google change — rows moving out of
+ // `[2][0]` — to users as "no flights on this route", which is the
+ // failure this transport exists to prevent.
+ async function searchPayload(payload: unknown) {
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ fetchImpl: (async () =>
+ new Response(asSearchPage(payload), { status: 200 })) as unknown as typeof fetch,
+ });
+ // These payloads have no session id either; that warning is correct
+ // but is not what these tests are about.
+ setSearchLogger({ warn: () => {}, debug: () => {} });
+ try {
+ return await new SearchFlights(client).search(oneWayFilters());
+ } finally {
+ setSearchLogger(null);
+ }
+ }
+
+ test("payload too short to hold the row blocks raises", async () => {
+ // `inner[2]` does not exist at all.
+ await expect(searchPayload(["x", [1, 2, 3]])).rejects.toThrow(SearchParseError);
+ await expect(searchPayload(["x", [1, 2, 3]])).rejects.toThrow(
+ /no flights array at inner\[2\]\/\[3\]/,
+ );
+ });
+
+ test("an empty row block raises — there is no [0] to read", async () => {
+ await expect(searchPayload(["x", [1, 2, 3], [], []])).rejects.toThrow(SearchParseError);
+ });
+
+ test("a row block whose [0] is not a list raises", async () => {
+ await expect(searchPayload([null, null, [42], [42]])).rejects.toThrow(SearchParseError);
+ });
+
+ test("present-but-empty row blocks are genuinely no flights", async () => {
+ // `[[]]` is what Google serves for a route with no service: the
+ // block is there, `[0]` is there, and it holds no rows.
+ const payload: unknown[] = Array.from({ length: 4 }, () => null);
+ payload[0] = [null, null, null, null, "sid"];
+ payload[2] = [[]];
+ payload[3] = [[]];
+ expect(await searchPayload(payload)).toBeNull();
+ });
+
+ test("a block of scalar rows raises, rather than reporting no flights", async () => {
+ // Python hands each row to `parse_flight_row`, which raises
+ // `TypeError: 'int' object is not subscriptable`, so all three rows
+ // fail and the "parsed 0 of N" tripwire fires. Skipping them
+ // silently left the TS port returning `null` — "no flights on this
+ // route" — for a payload that is plainly the wrong shape.
+ const payload: unknown[] = Array.from({ length: 4 }, () => null);
+ payload[0] = [null, null, null, null, "sid"];
+ payload[2] = [[1, 2, 3]];
+ payload[3] = [[]];
+ await expect(searchPayload(payload)).rejects.toThrow(SearchParseError);
+ await expect(searchPayload(payload)).rejects.toThrow(/Parsed 0\/3 flight rows/);
+ });
+
+ test("one scalar row among good ones still does not sink the search", async () => {
+ const payload: unknown[] = Array.from({ length: 4 }, () => null);
+ payload[0] = [null, null, null, null, "sid"];
+ payload[2] = [[7, syntheticFlightRow(), null]];
+ payload[3] = [[]];
+ const results = (await searchPayload(payload)) as Array<{ price: number }>;
+ expect(results).toHaveLength(1);
+ expect(results[0]?.price).toBe(199.99);
+ });
+
+ test("a non-list block is skipped, exactly as Python's isinstance check does", async () => {
+ // Google parks other things in these slots; only a list is read.
+ const payload: unknown[] = Array.from({ length: 4 }, () => null);
+ payload[0] = [null, null, null, null, "sid"];
+ payload[2] = [[syntheticFlightRow()]];
+ payload[3] = "not a block";
+ const results = (await searchPayload(payload)) as Array<{ price: number }>;
+ expect(results).toHaveLength(1);
+ });
+ });
+
+ test("multi-city is refused before any request goes out", async () => {
+ let calls = 0;
+ const client = new Client({
+ retries: 1,
+ fetchImpl: (async () => {
+ calls++;
+ return new Response("", { status: 200 });
+ }) as unknown as typeof fetch,
+ });
const filters = new FlightSearchFilters({
+ trip_type: TripType.MULTI_CITY,
passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
flight_segments: [
new FlightSegment({
departure_airport: [[[Airport.JFK, 0]]],
arrival_airport: [[[Airport.LAX, 0]]],
- travel_date: futureDate(),
+ travel_date: futureDate(10),
+ }),
+ new FlightSegment({
+ departure_airport: [[[Airport.LAX, 0]]],
+ arrival_airport: [[[Airport.SEA, 0]]],
+ travel_date: futureDate(14),
}),
],
});
+ await expect(new SearchFlights(client).search(filters)).rejects.toThrow(SearchUnsupportedError);
+ expect(calls).toBe(0);
+ });
+
+ test("client-side filters are applied to the decoded rows", async () => {
+ const fakeFetch = async (): Promise<Response> =>
+ new Response(
+ syntheticSearchPage([
+ syntheticFlightRow({ airline: "AA", price: 500 }),
+ syntheticFlightRow({ airline: "DL", price: 100 }),
+ ]),
+ { status: 200 },
+ );
+ const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
+ const search = new SearchFlights(client);
- await search.search(filters);
- // Internal cache is private; the public proof is that getBookingOptions
- // doesn't throw "Missing booking token" with no explicit override.
- expect(true).toBe(true);
+ const results = (await search.search(oneWayFilters({ airlines: [Airline.AA] }))) as Array<{
+ price: number;
+ }>;
+ expect(results).toHaveLength(1);
+ expect(results[0]?.price).toBe(500);
});
- test("returns null when response yields no parseable rows", async () => {
- const emptyResponse = syntheticShoppingResponse([]);
- const fakeFetch = async (): Promise<Response> => new Response(emptyResponse, { status: 200 });
+ test("sortBy CHEAPEST orders the page's rows by price", async () => {
+ const fakeFetch = async (): Promise<Response> =>
+ new Response(
+ syntheticSearchPage([
+ syntheticFlightRow({ price: 500 }),
+ syntheticFlightRow({ price: 100 }),
+ syntheticFlightRow({ price: 300 }),
+ ]),
+ { status: 200 },
+ );
const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
const search = new SearchFlights(client);
+ const results = (await search.search(oneWayFilters({ sort_by: SortBy.CHEAPEST }))) as Array<{
+ price: number;
+ }>;
+ expect(results.map((f) => f.price)).toEqual([100, 300, 500]);
+ });
+ test("unsupported filters are dropped with a warning, not silently", async () => {
+ const fakeFetch = async (): Promise<Response> =>
+ new Response(syntheticSearchPage([syntheticFlightRow()]), { status: 200 });
+ const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
+ const warnings: string[] = [];
+ setSearchLogger({ warn: (m) => warnings.push(m), debug: () => {} });
+ try {
+ await new SearchFlights(client).search(
+ oneWayFilters({ exclude_basic_economy: true, bags: { checked_bags: 1, carry_on: true } }),
+ );
+ } finally {
+ setSearchLogger(null);
+ }
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0]).toContain("bags");
+ expect(warnings[0]).toContain("exclude_basic_economy");
+ });
+
+ test("a round trip fetches one return page per expanded outbound", async () => {
+ const urls: string[] = [];
+ const fakeFetch = async (input: string | URL | Request): Promise<Response> => {
+ urls.push(String(input));
+ return new Response(syntheticSearchPage([syntheticFlightRow()]), { status: 200 });
+ };
+ const client = new Client({ fetchImpl: fakeFetch as unknown as typeof fetch, retries: 1 });
const filters = new FlightSearchFilters({
+ trip_type: TripType.ROUND_TRIP,
passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
flight_segments: [
new FlightSegment({
departure_airport: [[[Airport.JFK, 0]]],
arrival_airport: [[[Airport.LAX, 0]]],
- travel_date: futureDate(),
+ travel_date: futureDate(20),
+ }),
+ new FlightSegment({
+ departure_airport: [[[Airport.LAX, 0]]],
+ arrival_airport: [[[Airport.JFK, 0]]],
+ travel_date: futureDate(27),
}),
],
});
- expect(await search.search(filters)).toBeNull();
+ const results = await new SearchFlights(client).search(filters, { topN: 2 });
+ // One outbound page; the page returned one row, so one return page.
+ expect(urls).toHaveLength(2);
+ expect(urls.every((u) => u.startsWith("https://www.google.com/travel/flights?"))).toBe(true);
+ // The return request pins the chosen outbound, so its token differs.
+ expect(urls[0]).not.toBe(urls[1]);
+ expect(results).toHaveLength(1);
+ expect((results as unknown[][])[0]).toHaveLength(2);
});
});
describe("SearchFlights._encodeBookingPayload", () => {
test("truncates main struct to 18 elements", () => {
- const filters = new FlightSearchFilters({
- passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
- flight_segments: [
- new FlightSegment({
- departure_airport: [[[Airport.JFK, 0]]],
- arrival_airport: [[[Airport.LAX, 0]]],
- travel_date: futureDate(),
- }),
- ],
- });
+ const filters = oneWayFilters();
const encoded = SearchFlights._encodeBookingPayload("token", filters);
expect(typeof encoded).toBe("string");
// Decoded form should reconstruct: [null, "<json>"] where json starts with [[null,"token"], main, null, 0]
@@ -204,20 +435,46 @@ describe("SearchFlights._encodeBookingPayload", () => {
});
describe("SearchFlights.getBookingOptions error paths", () => {
+ test("Google's payload-less RPC answer surfaces as SearchRejectedError", async () => {
+ // The booking RPC is the one call still made against
+ // FlightsFrontendService, and it is gated: Google answers HTTP 200
+ // with a payload-less `wrb.fr` row carrying error 13. Reporting that
+ // as an empty vendor list would read as "nobody sells this fare".
+ const rejected = `)]}'\n\n${JSON.stringify([["wrb.fr", null, null, null, null, [13]]])}`;
+ const search = new SearchFlights(
+ new Client({
+ retries: 1,
+ fetchImpl: (async () => new Response(rejected, { status: 200 })) as unknown as typeof fetch,
+ }),
+ );
+ const fakeFlight = {
+ legs: [
+ {
+ airline: Airline.AA,
+ flight_number: "100",
+ departure_airport: Airport.JFK,
+ arrival_airport: Airport.LAX,
+ departure_datetime: new Date(2030, 0, 1, 8, 0),
+ arrival_datetime: new Date(2030, 0, 1, 11, 0),
+ duration: 180,
+ },
+ ],
+ price: 199,
+ currency: "USD",
+ duration: 180,
+ stops: 0,
+ booking_token: "tok",
+ } as unknown as Parameters<typeof search.getBookingOptions>[0];
+ await expect(search.getBookingOptions(fakeFlight, oneWayFilters())).rejects.toThrow(
+ SearchRejectedError,
+ );
+ });
+
test("throws when neither session nor token is available", async () => {
const search = new SearchFlights(
new Client({ fetchImpl: (async () => new Response("")) as unknown as typeof fetch }),
);
- const filters = new FlightSearchFilters({
- passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
- flight_segments: [
- new FlightSegment({
- departure_airport: [[[Airport.JFK, 0]]],
- arrival_airport: [[[Airport.LAX, 0]]],
- travel_date: futureDate(),
- }),
- ],
- });
+ const filters = oneWayFilters();
const fakeFlight = {
legs: [{ airline: Airline.AA, flight_number: "100" }],
price: null,
diff --git a/fli-js/tests/search/abort.test.ts b/fli-js/tests/search/abort.test.ts
new file mode 100644
index 0000000..bf2c86d
--- /dev/null
+++ b/fli-js/tests/search/abort.test.ts
@@ -0,0 +1,451 @@
+/**
+ * Cancellation tests.
+ *
+ * A search is now several sequential HTTP requests with sleeps between
+ * them — the client's retry backoff and the page-retry backoff — so a
+ * caller who aborts must not be left waiting for a timer that no longer
+ * has any reason to fire, and that timer must not keep the process alive
+ * after the promise has settled.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { Airport } from "../../src/models/airport.ts";
+import { FlightSegment, TripType } from "../../src/models/google-flights/base.ts";
+import { DateSearchFilters } from "../../src/models/google-flights/dates.ts";
+import { FlightSearchFilters } from "../../src/models/google-flights/flights.ts";
+import { Client } from "../../src/search/client.ts";
+import { SearchDates } from "../../src/search/dates.ts";
+import { SearchFlights } from "../../src/search/flights.ts";
+import { setSearchLogger } from "../../src/search/logging.ts";
+import { fetchPayload } from "../../src/search/tfs.ts";
+
+function futureDate(daysAhead = 30): string {
+ const d = new Date();
+ d.setUTCDate(d.getUTCDate() + daysAhead);
+ return d.toISOString().slice(0, 10);
+}
+
+function asFetch(fn: (input: unknown, init?: RequestInit) => Promise<Response>): typeof fetch {
+ return fn as unknown as typeof fetch;
+}
+
+function oneWayFilters(): FlightSearchFilters {
+ return new FlightSearchFilters({
+ passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LAX, 0]]],
+ travel_date: futureDate(),
+ }),
+ ],
+ });
+}
+
+/** A rendered search page carrying exactly one parseable flight row. */
+function pageWithOneFlight(): string {
+ const leg: unknown[] = [
+ "AA",
+ null,
+ null,
+ "JFK",
+ null,
+ null,
+ "LAX",
+ null,
+ [12, 30],
+ null,
+ [16, 45],
+ 375,
+ null,
+ null,
+ null,
+ null,
+ null,
+ "Boeing 737",
+ null,
+ false,
+ [2026, 12, 25],
+ [2026, 12, 25],
+ ["AA", "100"],
+ ];
+ while (leg.length < 32) leg.push(null);
+ const detail: unknown[] = Array.from({ length: 25 }, () => null);
+ detail[0] = "AA";
+ detail[1] = ["American Airlines"];
+ detail[2] = [leg];
+ detail[9] = 375;
+ const row: unknown[] = Array.from({ length: 11 }, () => null);
+ row[0] = detail;
+ row[1] = [[null, 199.99], null];
+ const payload: unknown[] = [[null, null, null, null, "sid"], null, [[row]], [[]]];
+ return `<script>AF_initDataCallback({key: 'ds:1', hash: '1', data:${JSON.stringify(payload)}, sideChannel: {}});</script>`;
+}
+
+/** Date filters covering `days` dates starting 10 days out. */
+function sweepFilters(days: number): DateSearchFilters {
+ const fromD = futureDate(10);
+ return new DateSearchFilters({
+ passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LAX, 0]]],
+ travel_date: fromD,
+ }),
+ ],
+ from_date: fromD,
+ to_date: futureDate(10 + days - 1),
+ });
+}
+
+describe("client retry backoff is abortable", () => {
+ test("aborting during the backoff rejects promptly with the caller's reason", async () => {
+ let calls = 0;
+ const client = new Client({
+ retries: 3,
+ // Long enough that "the sleep was waited out" is unmistakable, short
+ // enough that a regression fails the assertion instead of the timeout.
+ backoffMs: 400,
+ fetchImpl: asFetch(async () => {
+ calls++;
+ throw new TypeError("fetch failed");
+ }),
+ });
+ const controller = new AbortController();
+ const reason = new Error("caller aborted");
+ setTimeout(() => controller.abort(reason), 20);
+
+ const started = performance.now();
+ await expect(
+ client.get("https://www.google.com/travel/flights", { signal: controller.signal }),
+ ).rejects.toBe(reason);
+ const elapsed = performance.now() - started;
+
+ // One failed fetch, then the abort lands mid-backoff.
+ expect(calls).toBe(1);
+ expect(elapsed).toBeLessThan(300);
+ });
+
+ test("a backoff that is waited out still retries normally", async () => {
+ let calls = 0;
+ const client = new Client({
+ retries: 2,
+ backoffMs: 5,
+ fetchImpl: asFetch(async () => {
+ calls++;
+ if (calls === 1) throw new TypeError("fetch failed");
+ return new Response("ok", { status: 200 });
+ }),
+ });
+ expect((await client.get("https://www.google.com/x")).text).toBe("ok");
+ expect(calls).toBe(2);
+ });
+});
+
+describe("page retry backoff is abortable", () => {
+ test("fetchPayload stops mid-backoff when the caller aborts", async () => {
+ let calls = 0;
+ const client = new Client({
+ retries: 1,
+ fetchImpl: asFetch(async () => {
+ calls++;
+ return new Response("<html>no payload</html>", { status: 200 });
+ }),
+ });
+ const controller = new AbortController();
+ const reason = new Error("caller aborted");
+ setTimeout(() => controller.abort(reason), 20);
+
+ const started = performance.now();
+ await expect(
+ fetchPayload(client, "https://www.google.com/travel/flights", {
+ signal: controller.signal,
+ }),
+ ).rejects.toBe(reason);
+ const elapsed = performance.now() - started;
+
+ // The real backoff is 500ms then 1500ms; aborting at 20ms must not
+ // wait either of them out, and must not start the second fetch.
+ expect(calls).toBe(1);
+ expect(elapsed).toBeLessThan(400);
+ });
+});
+
+describe("signal reaches the transport from the public options", () => {
+ test("SearchFlights.search puts its signal on the wire", async () => {
+ // Aborted once the first fetch is under way, so the signal must have
+ // reached `fetchImpl` for the request to notice at all.
+ let seen: AbortSignal | null | undefined;
+ const controller = new AbortController();
+ const reason = new Error("cancelled mid-flight");
+ const client = new Client({
+ retries: 1,
+ fetchImpl: asFetch(async (_u, init) => {
+ seen = init?.signal;
+ controller.abort(reason);
+ throw new DOMException("Aborted", "AbortError");
+ }),
+ });
+
+ await expect(
+ new SearchFlights(client).search(oneWayFilters(), { signal: controller.signal }),
+ ).rejects.toBe(reason);
+ expect(seen).toBeDefined();
+ expect(seen?.aborted).toBe(true);
+ });
+
+ test("SearchDates.search puts its signal on the wire", async () => {
+ let seen: AbortSignal | null | undefined;
+ const controller = new AbortController();
+ const reason = new Error("cancelled mid-sweep");
+ const client = new Client({
+ retries: 1,
+ callsPerSecond: 10_000,
+ fetchImpl: asFetch(async (_u, init) => {
+ seen = init?.signal;
+ controller.abort(reason);
+ throw new DOMException("Aborted", "AbortError");
+ }),
+ });
+
+ setSearchLogger({ warn: () => {}, debug: () => {} });
+ try {
+ await expect(
+ new SearchDates(client).search(sweepFilters(3), { signal: controller.signal }),
+ ).rejects.toBe(reason);
+ } finally {
+ setSearchLogger(null);
+ }
+ expect(seen).toBeDefined();
+ expect(seen?.aborted).toBe(true);
+ });
+});
+
+describe("a pre-aborted signal costs nothing at all", () => {
+ // Real `fetch` rejects a pre-aborted signal without touching the
+ // network, but a custom `fetchImpl` is under no such obligation — and
+ // taking a rate-limiter token for a request that will never be made
+ // delays the next real one.
+ function countingClient(): { client: Client; calls: () => number } {
+ let calls = 0;
+ const client = new Client({
+ retries: 3,
+ backoffMs: 1,
+ fetchImpl: asFetch(async () => {
+ calls++;
+ return new Response("<html>no payload</html>", { status: 200 });
+ }),
+ });
+ return { client, calls: () => calls };
+ }
+
+ function preAborted(): { signal: AbortSignal; reason: Error } {
+ const controller = new AbortController();
+ const reason = new Error("cancelled before we started");
+ controller.abort(reason);
+ return { signal: controller.signal, reason };
+ }
+
+ test("Client.get makes no call", async () => {
+ const { client, calls } = countingClient();
+ const { signal, reason } = preAborted();
+ await expect(client.get("https://www.google.com/x", { signal })).rejects.toBe(reason);
+ expect(calls()).toBe(0);
+ });
+
+ test("Client.post makes no call", async () => {
+ const { client, calls } = countingClient();
+ const { signal, reason } = preAborted();
+ await expect(client.post("https://www.google.com/x", { body: "", signal })).rejects.toBe(
+ reason,
+ );
+ expect(calls()).toBe(0);
+ });
+
+ test("fetchPayload makes no call", async () => {
+ const { client, calls } = countingClient();
+ const { signal, reason } = preAborted();
+ await expect(
+ fetchPayload(client, "https://www.google.com/travel/flights", { signal }),
+ ).rejects.toBe(reason);
+ expect(calls()).toBe(0);
+ });
+
+ test("SearchFlights.search makes no call", async () => {
+ const { client, calls } = countingClient();
+ const { signal, reason } = preAborted();
+ await expect(new SearchFlights(client).search(oneWayFilters(), { signal })).rejects.toBe(
+ reason,
+ );
+ expect(calls()).toBe(0);
+ });
+
+ test("SearchDates.search makes no call", async () => {
+ const { client, calls } = countingClient();
+ const { signal, reason } = preAborted();
+ await expect(new SearchDates(client).search(sweepFilters(40), { signal })).rejects.toBe(reason);
+ expect(calls()).toBe(0);
+ });
+});
+
+describe("aborting a date sweep stops it and rejects", () => {
+ test("a 93-date sweep aborted early rejects with the caller's reason", async () => {
+ // Measured before this was fixed: all 93 slots ran, the sweep took
+ // 8.3s, and it RESOLVED with 10 partial dates — a silently truncated
+ // answer, which is the failure class this transport exists to remove.
+ let calls = 0;
+ let inFlight = 0;
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ callsPerSecond: 10_000,
+ fetchImpl: asFetch(async () => {
+ calls++;
+ inFlight++;
+ try {
+ await new Promise((r) => setTimeout(r, 30));
+ return new Response(pageWithOneFlight(), { status: 200 });
+ } finally {
+ inFlight--;
+ }
+ }),
+ });
+
+ const controller = new AbortController();
+ const reason = new Error("caller aborted the sweep");
+ setTimeout(() => controller.abort(reason), 20);
+
+ setSearchLogger({ warn: () => {}, debug: () => {} });
+ const started = performance.now();
+ try {
+ await expect(
+ new SearchDates(client).search(sweepFilters(93), { signal: controller.signal }),
+ ).rejects.toBe(reason);
+ } finally {
+ setSearchLogger(null);
+ }
+ const elapsed = performance.now() - started;
+
+ // No further date is started once the signal fires: only the batch
+ // already in flight (≤ 10 workers) ever reached the network.
+ expect(calls).toBeLessThanOrEqual(20);
+ expect(elapsed).toBeLessThan(1_000);
+ expect(inFlight).toBe(0);
+ });
+
+ test("an aborted sweep never returns partial results", async () => {
+ // Let a few dates succeed before aborting: the sweep now has real
+ // prices in hand and must still reject rather than hand back a
+ // truncated answer the caller has no way to recognise as truncated.
+ let calls = 0;
+ const controller = new AbortController();
+ const reason = new Error("aborted after some dates priced");
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ callsPerSecond: 10_000,
+ fetchImpl: asFetch(async () => {
+ calls++;
+ if (calls === 12) controller.abort(reason);
+ return new Response(pageWithOneFlight(), { status: 200 });
+ }),
+ });
+
+ setSearchLogger({ warn: () => {}, debug: () => {} });
+ try {
+ await expect(
+ new SearchDates(client).search(sweepFilters(93), { signal: controller.signal }),
+ ).rejects.toBe(reason);
+ } finally {
+ setSearchLogger(null);
+ }
+ expect(calls).toBeLessThan(93);
+ });
+
+ test("an abort is not reported as a blocked sweep or a failed date", async () => {
+ // The abort must not feed the circuit breaker or the "every date
+ // failed" error — neither message is true, and both would send the
+ // caller looking for a problem that is not there.
+ const warnings: string[] = [];
+ const controller = new AbortController();
+ const reason = new Error("aborted");
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ callsPerSecond: 10_000,
+ fetchImpl: asFetch(async () => {
+ controller.abort(reason);
+ // Model a real fetch noticing the abort mid-flight.
+ throw new DOMException("Aborted", "AbortError");
+ }),
+ });
+
+ setSearchLogger({ warn: (m) => warnings.push(m), debug: () => {} });
+ try {
+ await expect(
+ new SearchDates(client).search(sweepFilters(20), { signal: controller.signal }),
+ ).rejects.toBe(reason);
+ } finally {
+ setSearchLogger(null);
+ }
+ expect(warnings.filter((w) => w.includes("FLI_SOCS_COOKIE"))).toHaveLength(0);
+ expect(warnings.filter((w) => w.includes("real but incomplete"))).toHaveLength(0);
+ });
+
+ test("a sweep with no signal is unaffected", async () => {
+ let calls = 0;
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ callsPerSecond: 10_000,
+ fetchImpl: asFetch(async () => {
+ calls++;
+ return new Response(pageWithOneFlight(), { status: 200 });
+ }),
+ });
+ const results = await new SearchDates(client).search(sweepFilters(5));
+ expect(results).toHaveLength(5);
+ expect(calls).toBe(5);
+ });
+});
+
+describe("aborting a round trip stops the expansion", () => {
+ test("rejects with the caller's reason and stops fetching", async () => {
+ let calls = 0;
+ const controller = new AbortController();
+ const reason = new Error("aborted mid round trip");
+ const client = new Client({
+ retries: 1,
+ backoffMs: 1,
+ callsPerSecond: 10_000,
+ fetchImpl: asFetch(async () => {
+ calls++;
+ // Abort once the outbound board has come back, i.e. just as the
+ // per-outbound return fetches are about to be issued.
+ if (calls === 1) controller.abort(reason);
+ return new Response(pageWithOneFlight(), { status: 200 });
+ }),
+ });
+ const filters = new FlightSearchFilters({
+ trip_type: TripType.ROUND_TRIP,
+ passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LAX, 0]]],
+ travel_date: futureDate(20),
+ }),
+ new FlightSegment({
+ departure_airport: [[[Airport.LAX, 0]]],
+ arrival_airport: [[[Airport.JFK, 0]]],
+ travel_date: futureDate(27),
+ }),
+ ],
+ });
+ await expect(
+ new SearchFlights(client).search(filters, { topN: 5, signal: controller.signal }),
+ ).rejects.toBe(reason);
+ expect(calls).toBe(1);
+ });
+});
diff --git a/fli-js/tests/search/client.test.ts b/fli-js/tests/search/client.test.ts
index ed21278..33842ee 100644
--- a/fli-js/tests/search/client.test.ts
+++ b/fli-js/tests/search/client.test.ts
@@ -165,9 +165,11 @@ describe("Client", () => {
expect(calls).toBe(1);
});
- test("pre-aborted external signal short-circuits before any fetch retry", async () => {
+ test("pre-aborted external signal short-circuits before any fetch at all", async () => {
let calls = 0;
- // Real `fetch` rejects synchronously on a pre-aborted signal — model that.
+ // Real `fetch` rejects synchronously on a pre-aborted signal, but a
+ // custom `fetchImpl` need not — so the client checks first and never
+ // calls it, nor takes a rate-limiter token for a dead request.
const fake = async (_u: unknown, init?: RequestInit): Promise<Response> => {
calls++;
if (init?.signal?.aborted) {
@@ -186,7 +188,7 @@ describe("Client", () => {
expect(e).toBe(reason);
expect(e).not.toBeInstanceOf(SearchTimeoutError);
}
- expect(calls).toBe(1);
+ expect(calls).toBe(0);
});
test("retries on transient network failure then succeeds", async () => {
diff --git a/fli-js/tests/search/client_page_headers.test.ts b/fli-js/tests/search/client_page_headers.test.ts
new file mode 100644
index 0000000..401be9b
--- /dev/null
+++ b/fli-js/tests/search/client_page_headers.test.ts
@@ -0,0 +1,145 @@
+/**
+ * Request-shaping tests for the search-page GET.
+ *
+ * Google's `/travel/flights` page decides whether to inline its `ds:1`
+ * payload from the request headers — with no `user-agent` it serves a
+ * 1.2 MB shell with no flight rows at all, and every search silently
+ * returns nothing. That, plus the EU/EEA consent cookie, is what this
+ * covers.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { Client, DEFAULT_SOCS_COOKIE, resolveSocsCookie } from "../../src/search/client.ts";
+
+function asFetch(fn: (input: unknown, init?: RequestInit) => Promise<Response>): typeof fetch {
+ return fn as unknown as typeof fetch;
+}
+
+async function captureHeaders(
+ method: "get" | "post",
+ options: ConstructorParameters<typeof Client>[0] = {},
+): Promise<Record<string, string>> {
+ let headers: Record<string, string> = {};
+ const client = new Client({
+ ...options,
+ retries: 1,
+ fetchImpl: asFetch(async (_u, init) => {
+ headers = (init?.headers ?? {}) as Record<string, string>;
+ return new Response("ok", { status: 200 });
+ }),
+ });
+ if (method === "get") await client.get("https://www.google.com/travel/flights?tfs=x");
+ else await client.post("https://www.google.com/x", { body: "" });
+ return headers;
+}
+
+const originalSocs = process.env.FLI_SOCS_COOKIE;
+
+afterEach(() => {
+ if (originalSocs === undefined) delete process.env.FLI_SOCS_COOKIE;
+ else process.env.FLI_SOCS_COOKIE = originalSocs;
+});
+
+describe("search-page GET headers", () => {
+ test("a GET carries a Chrome user-agent — without it the page has no ds:1", async () => {
+ const headers = await captureHeaders("get");
+ expect(headers["user-agent"]).toMatch(/Chrome/);
+ });
+
+ test("a GET asks for a document, not an XHR", async () => {
+ const headers = await captureHeaders("get");
+ expect(headers.accept).toContain("text/html");
+ expect(headers["sec-fetch-dest"]).toBe("document");
+ expect(headers["sec-fetch-mode"]).toBe("navigate");
+ // A form-encoded content-type on a body-less GET is nonsense.
+ expect(headers["content-type"]).toBeUndefined();
+ });
+
+ test("the RPC POST keeps the headers it always sent", async () => {
+ const headers = await captureHeaders("post");
+ expect(headers["content-type"]).toBe("application/x-www-form-urlencoded;charset=UTF-8");
+ expect(headers.accept).toBe("*/*");
+ expect(headers["sec-fetch-mode"]).toBe("cors");
+ });
+});
+
+describe("SOCS consent cookie", () => {
+ test("sent by default on both verbs", async () => {
+ expect(DEFAULT_SOCS_COOKIE.length).toBeGreaterThan(40);
+ for (const method of ["get", "post"] as const) {
+ const headers = await captureHeaders(method);
+ expect(headers.cookie).toBe(`SOCS=${DEFAULT_SOCS_COOKIE}`);
+ }
+ });
+
+ test("FLI_SOCS_COOKIE overrides the value", async () => {
+ process.env.FLI_SOCS_COOKIE = "custom-value";
+ const headers = await captureHeaders("get");
+ expect(headers.cookie).toBe("SOCS=custom-value");
+ });
+
+ test("an empty FLI_SOCS_COOKIE disables the cookie entirely", async () => {
+ process.env.FLI_SOCS_COOKIE = "";
+ const headers = await captureHeaders("get");
+ expect(headers.cookie).toBeUndefined();
+ });
+
+ test("resolveSocsCookie reads the env at call time", () => {
+ process.env.FLI_SOCS_COOKIE = "abc";
+ expect(resolveSocsCookie()).toBe("abc");
+ process.env.FLI_SOCS_COOKIE = "";
+ expect(resolveSocsCookie()).toBe("");
+ delete process.env.FLI_SOCS_COOKIE;
+ expect(resolveSocsCookie()).toBe(DEFAULT_SOCS_COOKIE);
+ });
+
+ test("is not sent to a non-Google host", async () => {
+ // A header has no scope of its own; Python keeps this cookie in a jar
+ // scoped to `.google.com`. Leaking a consent cookie to whatever host
+ // a caller points the client at is nobody's idea of a good default.
+ let headers: Record<string, string> = {};
+ const client = new Client({
+ retries: 1,
+ fetchImpl: asFetch(async (_u, init) => {
+ headers = (init?.headers ?? {}) as Record<string, string>;
+ return new Response("ok", { status: 200 });
+ }),
+ });
+ await client.get("https://evil.example.com/collect");
+ expect(headers.cookie).toBeUndefined();
+ await client.post("https://google.com.evil.example/collect", { body: "" });
+ expect(headers.cookie).toBeUndefined();
+ });
+
+ test("is sent to google.com and its subdomains", async () => {
+ for (const url of [
+ "https://google.com/travel/flights",
+ "https://www.google.com/travel/flights",
+ "https://consent.google.com/m",
+ ]) {
+ let headers: Record<string, string> = {};
+ const client = new Client({
+ retries: 1,
+ fetchImpl: asFetch(async (_u, init) => {
+ headers = (init?.headers ?? {}) as Record<string, string>;
+ return new Response("ok", { status: 200 });
+ }),
+ });
+ await client.get(url);
+ expect(headers.cookie).toBe(`SOCS=${DEFAULT_SOCS_COOKIE}`);
+ }
+ });
+
+ test("a caller-supplied cookie header wins", async () => {
+ let headers: Record<string, string> = {};
+ const client = new Client({
+ retries: 1,
+ fetchImpl: asFetch(async (_u, init) => {
+ headers = (init?.headers ?? {}) as Record<string, string>;
+ return new Response("ok", { status: 200 });
+ }),
+ });
+ await client.get("https://www.google.com/x", { headers: { cookie: "SOCS=mine" } });
+ expect(headers.cookie).toBe("SOCS=mine");
+ });
+});
diff --git a/fli-js/tests/search/clone.test.ts b/fli-js/tests/search/clone.test.ts
new file mode 100644
index 0000000..8c491b7
--- /dev/null
+++ b/fli-js/tests/search/clone.test.ts
@@ -0,0 +1,191 @@
+/**
+ * Filter-cloning tests.
+ *
+ * Round-trip expansion and the date sweep both copy the caller's filters
+ * before mutating them. The copies used to be hand-written field lists,
+ * one per file — the exact pattern that silently dropped
+ * `airlines_exclude` and the alliance lists in Python until `model_copy`
+ * replaced it. A dropped field does not raise; it just quietly widens the
+ * search past what the caller asked for.
+ *
+ * So the guard is structural: every own field on the filters object must
+ * survive the copy, whatever it is called.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { Airline } from "../../src/models/airline.ts";
+import { Airport } from "../../src/models/airport.ts";
+import {
+ Alliance,
+ EmissionsFilter,
+ FlightSegment,
+ MaxStops,
+ SeatType,
+ SortBy,
+ TripType,
+} from "../../src/models/google-flights/base.ts";
+import { DateSearchFilters } from "../../src/models/google-flights/dates.ts";
+import { FlightSearchFilters } from "../../src/models/google-flights/flights.ts";
+import { cloneFilters } from "../../src/search/clone.ts";
+
+function futureDate(daysAhead: number): string {
+ const d = new Date();
+ d.setUTCDate(d.getUTCDate() + daysAhead);
+ return d.toISOString().slice(0, 10);
+}
+
+function fullyPopulatedFlightFilters(): FlightSearchFilters {
+ return new FlightSearchFilters({
+ trip_type: TripType.ROUND_TRIP,
+ passenger_info: { adults: 2, children: 1, infants_in_seat: 1, infants_on_lap: 1 },
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [
+ [
+ [Airport.JFK, 0],
+ [Airport.EWR, 0],
+ ],
+ ],
+ arrival_airport: [[[Airport.LHR, 0]]],
+ travel_date: futureDate(30),
+ time_restrictions: { earliest_departure: 6, latest_departure: 12 },
+ }),
+ new FlightSegment({
+ departure_airport: [[[Airport.LHR, 0]]],
+ arrival_airport: [[[Airport.JFK, 0]]],
+ travel_date: futureDate(37),
+ }),
+ ],
+ stops: MaxStops.ONE_STOP_OR_FEWER,
+ seat_type: SeatType.BUSINESS,
+ price_limit: { max_price: 2000, currency: "USD" },
+ airlines: [Airline.BA],
+ airlines_exclude: [Airline.AA],
+ alliances: [Alliance.ONEWORLD],
+ alliances_exclude: [Alliance.SKYTEAM],
+ max_duration: 1200,
+ layover_restrictions: { airports: [Airport.DUB], min_duration: 60, max_duration: 240 },
+ sort_by: SortBy.CHEAPEST,
+ exclude_basic_economy: true,
+ emissions: EmissionsFilter.LESS,
+ bags: { checked_bags: 2, carry_on: true },
+ show_all_results: false,
+ });
+}
+
+function fullyPopulatedDateFilters(): DateSearchFilters {
+ return new DateSearchFilters({
+ passenger_info: { adults: 2, children: 1, infants_in_seat: 0, infants_on_lap: 1 },
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LHR, 0]]],
+ travel_date: futureDate(30),
+ time_restrictions: { earliest_departure: 6, latest_departure: 12 },
+ }),
+ ],
+ stops: MaxStops.NON_STOP,
+ seat_type: SeatType.PREMIUM_ECONOMY,
+ price_limit: { max_price: 900, currency: "EUR" },
+ airlines: [Airline.BA],
+ airlines_exclude: [Airline.AA],
+ alliances: [Alliance.ONEWORLD],
+ alliances_exclude: [Alliance.SKYTEAM],
+ max_duration: 900,
+ layover_restrictions: { airports: [Airport.DUB], min_duration: 45, max_duration: 300 },
+ emissions: EmissionsFilter.LESS,
+ bags: { checked_bags: 1, carry_on: false },
+ from_date: futureDate(30),
+ to_date: futureDate(40),
+ });
+}
+
+describe("cloneFilters carries every field", () => {
+ for (const [label, build] of [
+ ["FlightSearchFilters", fullyPopulatedFlightFilters],
+ ["DateSearchFilters", fullyPopulatedDateFilters],
+ ] as const) {
+ test(`${label}: no own field is dropped`, () => {
+ const original = build();
+ const copy = cloneFilters(original);
+
+ const originalKeys = Object.keys(original).sort();
+ expect(Object.keys(copy as object).sort()).toEqual(originalKeys);
+
+ // Every field must compare equal. `toEqual` is structural, so this
+ // catches a field that was copied as `undefined` or `null`.
+ for (const key of originalKeys) {
+ const from = (original as unknown as Record<string, unknown>)[key];
+ const to = (copy as unknown as Record<string, unknown>)[key];
+ expect(to).toEqual(from as never);
+ }
+ });
+
+ test(`${label}: the copy keeps its class`, () => {
+ const copy = cloneFilters(build());
+ expect(copy).toBeInstanceOf(
+ label === "FlightSearchFilters" ? FlightSearchFilters : DateSearchFilters,
+ );
+ // Prototype getters still resolve.
+ expect(copy.flight_segments[0]?.parsed_travel_date).toBeInstanceOf(Date);
+ });
+
+ test(`${label}: mutating the copy does not touch the original`, () => {
+ const original = build();
+ const copy = cloneFilters(original);
+
+ // The two mutations the search actually performs.
+ const seg = copy.flight_segments[0];
+ if (seg) {
+ seg.travel_date = "2031-01-01";
+ seg.selected_flight = {
+ legs: [],
+ price: 1,
+ currency: "USD",
+ duration: 1,
+ stops: 0,
+ };
+ }
+ copy.flight_segments.push(copy.flight_segments[0] as FlightSegment);
+ (copy.airlines as Airline[]).push(Airline.DL);
+ copy.passenger_info.adults = 9;
+
+ expect(original.flight_segments[0]?.travel_date).not.toBe("2031-01-01");
+ expect(original.flight_segments[0]?.selected_flight).toBeNull();
+ expect(original.flight_segments).toHaveLength(build().flight_segments.length);
+ expect(original.airlines).toEqual([Airline.BA]);
+ expect(original.passenger_info.adults).toBe(2);
+ });
+ }
+
+ test("a field added to the filters later is carried without editing the clone", () => {
+ // The regression guard: the old hand-written copies listed fields by
+ // name, so a new one was silently dropped until someone noticed the
+ // search ignoring it.
+ const original = fullyPopulatedFlightFilters() as FlightSearchFilters & Record<string, unknown>;
+ original.some_future_filter = { nested: ["value"] };
+ const copy = cloneFilters(original) as FlightSearchFilters & Record<string, unknown>;
+ expect(copy.some_future_filter).toEqual({ nested: ["value"] });
+ // …and it is a copy, not the same object.
+ expect(copy.some_future_filter).not.toBe(original.some_future_filter);
+ });
+
+ test("null-valued fields stay null rather than becoming undefined", () => {
+ const original = new FlightSearchFilters({
+ passenger_info: { adults: 1, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LHR, 0]]],
+ travel_date: futureDate(30),
+ }),
+ ],
+ });
+ const copy = cloneFilters(original);
+ expect(copy.airlines).toBeNull();
+ expect(copy.price_limit).toBeNull();
+ expect(copy.layover_restrictions).toBeNull();
+ expect(copy.bags).toBeNull();
+ expect(copy.flight_segments[0]?.time_restrictions).toBeNull();
+ });
+});
diff --git a/fli-js/tests/search/exceptions.test.ts b/fli-js/tests/search/exceptions.test.ts
new file mode 100644
index 0000000..05b479b
--- /dev/null
+++ b/fli-js/tests/search/exceptions.test.ts
@@ -0,0 +1,69 @@
+/**
+ * Typed-error family tests.
+ *
+ * Mirrors fli/search/exceptions.py: every search failure must be a
+ * `SearchClientError` so a caller catching "the search failed" catches
+ * all of them, including the parse failures that a blocked or reshaped
+ * page produces.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+ SearchClientError,
+ SearchConnectionError,
+ SearchHTTPError,
+ SearchParseError,
+ SearchRejectedError,
+ SearchTimeoutError,
+ SearchUnsupportedError,
+} from "../../src/search/exceptions.ts";
+import { iterWrbChunks, parseFirstWrbPayload } from "../../src/search/wire.ts";
+
+describe("error family", () => {
+ test("every search error is a SearchClientError", () => {
+ for (const err of [
+ new SearchTimeoutError("t"),
+ new SearchConnectionError("c"),
+ new SearchHTTPError("h", 500),
+ new SearchParseError("p"),
+ new SearchRejectedError(13),
+ new SearchUnsupportedError("u"),
+ ]) {
+ expect(err).toBeInstanceOf(SearchClientError);
+ expect(err).toBeInstanceOf(Error);
+ expect(err.name).toBe(err.constructor.name);
+ }
+ });
+
+ test("SearchRejectedError names the code and the gated header", () => {
+ const err = new SearchRejectedError(13);
+ expect(err.code).toBe(13);
+ expect(err.message).toContain("error 13");
+ expect(err.message).toContain("x-goog-batchexecute-bgr");
+ });
+
+ test("SearchRejectedError without a code omits the suffix", () => {
+ expect(new SearchRejectedError().message).not.toContain("error");
+ });
+});
+
+describe("wire rejection", () => {
+ /** A payload-less `wrb.fr` row with an error code parked in slot 5. */
+ function rejectedBody(code: unknown): string {
+ return `)]}'\n\n${JSON.stringify([["wrb.fr", null, null, null, null, [code]]])}`;
+ }
+
+ test("payload-less row with an error code raises instead of yielding nothing", () => {
+ expect(() => [...iterWrbChunks(rejectedBody(13))]).toThrow(SearchRejectedError);
+ expect(() => parseFirstWrbPayload(rejectedBody(13))).toThrow(/error 13/);
+ });
+
+ test("payload-less row with no error code is still skipped", () => {
+ const body = `)]}'\n\n${JSON.stringify([["wrb.fr", null, null]])}`;
+ expect(parseFirstWrbPayload(body)).toBeNull();
+ });
+
+ test("a non-numeric slot-5 value is not mistaken for a code", () => {
+ expect(parseFirstWrbPayload(rejectedBody("13"))).toBeNull();
+ });
+});
diff --git a/fli-js/tests/search/search_page_fixture.test.ts b/fli-js/tests/search/search_page_fixture.test.ts
new file mode 100644
index 0000000..957e4ca
--- /dev/null
+++ b/fli-js/tests/search/search_page_fixture.test.ts
@@ -0,0 +1,63 @@
+/**
+ * `extractPayload` against a real captured search page.
+ *
+ * Every other fixture the JS suite reads is an RPC body; this one is the
+ * page HTML the transport actually reads now, so it is the only offline
+ * guard on the regex that finds the `ds:1` blob among the page's other
+ * `AF_initDataCallback` blocks. The file keeps that script block exactly
+ * as Google served it, inside a minimal HTML shell.
+ *
+ * It is the same capture the Python suite pins
+ * (`tests/search/fixtures/search_page_jfk_lhr_nonstop_ds1.html`), read
+ * from its existing path rather than duplicated — the other fixture
+ * tests in this directory already share the Python fixtures that way.
+ *
+ * Same drift policy as the rest: assert structure, never prices or
+ * flight numbers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { parseFlightRow } from "../../src/search/decoders.ts";
+import { extractPayload } from "../../src/search/tfs.ts";
+
+const PAGE = await Bun.file(
+ new URL("../../../tests/search/fixtures/search_page_jfk_lhr_nonstop_ds1.html", import.meta.url),
+).text();
+
+describe("real search page", () => {
+ test("payload is extracted", () => {
+ const payload = extractPayload(PAGE);
+ expect(Array.isArray(payload)).toBe(true);
+ expect((payload as unknown[]).length).toBeGreaterThan(3);
+ });
+
+ test("payload decodes into flights through the existing row decoder", () => {
+ const payload = extractPayload(PAGE) as unknown[];
+ const 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) {
+ try {
+ flights.push(parseFlightRow(row as unknown[]));
+ } catch {
+ // One unparseable row must not sink the page.
+ }
+ }
+ }
+ expect(flights.length).toBeGreaterThan(0);
+ expect(flights.every((f) => f.legs.length > 0)).toBe(true);
+ expect(new Set(flights.map((f) => String(f.legs[0]?.departure_airport)))).toEqual(
+ new Set(["JFK"]),
+ );
+ });
+
+ test("fixture carries nothing account-specific", () => {
+ const lowered = PAGE.toLowerCase();
+ for (const marker of ["set-cookie", "sapisid", "apisid", "hsid", "__secure-", "authuser"]) {
+ expect(lowered).not.toContain(marker);
+ }
+ });
+});
diff --git a/fli-js/tests/search/tfs.test.ts b/fli-js/tests/search/tfs.test.ts
new file mode 100644
index 0000000..4f56fd3
--- /dev/null
+++ b/fli-js/tests/search/tfs.test.ts
@@ -0,0 +1,916 @@
+/**
+ * Tests for the search-page transport (`src/search/tfs.ts`).
+ *
+ * Everything here is offline.
+ *
+ * The `tfs` goldens were produced by running the Python reference
+ * implementation this module ports — see the header on `TFS_GOLDENS`
+ * below for the exact command. A mismatch means the TypeScript encoder
+ * has drifted from the Python one, and therefore from what Google
+ * accepts.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { Airline } from "../../src/models/airline.ts";
+import { Airport } from "../../src/models/airport.ts";
+import {
+ Alliance,
+ type FlightLeg,
+ type FlightResult,
+ FlightSegment,
+ type LayoverRestrictions,
+ MaxStops,
+ type PassengerInfo,
+ type PriceLimit,
+ SeatType,
+ type TimeRestrictions,
+ TripType,
+} from "../../src/models/google-flights/base.ts";
+import { FlightSearchFilters } from "../../src/models/google-flights/flights.ts";
+import { Client } from "../../src/search/client.ts";
+import { SearchUnsupportedError } from "../../src/search/exceptions.ts";
+import { setSearchLogger } from "../../src/search/logging.ts";
+import {
+ _setPageRetrySleep,
+ applyClientSideFilters,
+ buildTfs,
+ extractPayload,
+ fetchPayload,
+ PAGE_FETCH_ATTEMPTS,
+ pageUrl,
+ unsupportedFilters,
+} from "../../src/search/tfs.ts";
+
+// ---------------------------------------------------------------------------
+// Golden `tfs` values
+// ---------------------------------------------------------------------------
+
+/**
+ * Expected `tfs` values, generated by running the Python implementation.
+ *
+ * Regenerate with (from the repository root):
+ *
+ * ```
+ * uv run --python 3.13 python fli-js/scripts/dump_tfs_goldens.py
+ * ```
+ *
+ * The travel dates are deliberately far out (2030): `FlightSegment`
+ * rejects a past date, and unlike the Python suite this one has no
+ * clock-pinning fixture, so a golden built on a near date would start
+ * failing the day it passed. The `tfs` bytes do not depend on "today" —
+ * only on the dates in the filters — so a 2030 date pins the encoder
+ * exactly as a 2026 one would.
+ */
+const TFS_GOLDENS: Record<string, string> = {
+ alliance_exclude_oneworld:
+ "CBwQAhooEgoyMDMwLTA5LTE1OghPTkVXT1JMRGoHCAESA0pGS3IHCAESA0xBWEABSAFwAZgBAg",
+ alliance_exclude_skyteam:
+ "CBwQAhonEgoyMDMwLTA5LTE1OgdTS1lURUFNagcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ alliance_exclude_star_alliance:
+ "CBwQAhotEgoyMDMwLTA5LTE1Og1TVEFSX0FMTElBTkNFagcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ alliance_include_oneworld:
+ "CBwQAhooEgoyMDMwLTA5LTE1MghPTkVXT1JMRGoHCAESA0pGS3IHCAESA0xBWEABSAFwAZgBAg",
+ alliance_include_skyteam:
+ "CBwQAhonEgoyMDMwLTA5LTE1MgdTS1lURUFNagcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ alliance_include_star_alliance:
+ "CBwQAhotEgoyMDMwLTA5LTE1Mg1TVEFSX0FMTElBTkNFagcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ alliance_include_two_exclude_one:
+ "CBwQAhpAEgoyMDMwLTA5LTE1MghPTkVXT1JMRDINU1RBUl9BTExJQU5DRToHU0tZVEVBTWoHCAESA0pGS3IHCAESA0xBWEABSAFwAZgBAg",
+ cabin_business: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFIA3ABmAEC",
+ cabin_economy: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ cabin_first: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFIBHABmAEC",
+ cabin_premium_economy: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFIAnABmAEC",
+ kitchen_sink_round_trip:
+ "CBwQAhpIEgoyMDMwLTA5LTE1KAEyCE9ORVdPUkxEagcIARIDSkZLagcIARIDRVdScgcIARIDTEhScgcIARIDTEdXegNEVUKIATyQAfABGkgSCjIwMzAtMDktMTkoATIIT05FV09STERqBwgBEgNMSFJqBwgBEgNMR1dyBwgBEgNKRktyBwgBEgNFV1J6A0RVQogBPJAB8AFAAUABQAJAA0gDcAGYAQE",
+ layover_airport_and_min:
+ "CBwQAhomEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYegNPUkSIAXhAAUgBcAGYAQI",
+ layover_full:
+ "CBwQAhovEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYegNPUkR6A0RGV4gBWpAB2ARAAUgBcAGYAQI",
+ layover_max_only: "CBwQAhoiEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYkAGsAkABSAFwAZgBAg",
+ multi_airport:
+ "CBwQAho5EgoyMDMwLTEwLTE1agcIARIDQk9NagcIARIDREVMagcIARIDQU1EcgcIARIDT1JEcgcIARIDRFRXQAFIAXABmAEC",
+ one_way_jfk_lax: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ pax_adult_child: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFAAkgBcAGYAQI",
+ pax_adult_lap_infant: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFAA0gBcAGYAQI",
+ pax_adult_seat_infant: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFABEgBcAGYAQI",
+ pax_family_mix: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFAAUACQANABEgBcAGYAQI",
+ pax_full_house:
+ "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFAAUABQAFAAkACQANABEAESAFwAZgBAg",
+ pax_single_adult: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ pax_two_adults: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFAAUgBcAGYAQI",
+ pax_two_adults_two_lap_infants:
+ "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFAAUADQANIAXABmAEC",
+ round_trip_jfk_lax:
+ "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYGh4SCjIwMzAtMDktMTlqBwgBEgNMQVhyBwgBEgNKRktAAUgBcAGYAQE",
+ round_trip_selected_connecting_outbound:
+ "CBwQAhpgEgoyMDMwLTA5LTE1Ih8KA0pGSxIKMjAzMC0wOS0xNRoDT1JEKgJBQTIDMTAwIh8KA09SRBIKMjAzMC0wOS0xNRoDTEhSKgJBQTIDMjAwagcIARIDSkZLcgcIARIDTEhSGh4SCjIwMzAtMDktMTlqBwgBEgNMSFJyBwgBEgNKRktAAUgBcAGYAQE",
+ round_trip_selected_outbound:
+ "CBwQAho_EgoyMDMwLTA5LTE1Ih8KA0pGSxIKMjAzMC0wOS0xNRoDTEhSKgJCQTIDMTc4agcIARIDSkZLcgcIARIDTEhSGh4SCjIwMzAtMDktMTlqBwgBEgNMSFJyBwgBEgNKRktAAUgBcAGYAQE",
+ stops_any: "CBwQAhoeEgoyMDMwLTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ stops_non_stop: "CBwQAhogEgoyMDMwLTA5LTE1KABqBwgBEgNKRktyBwgBEgNMQVhAAUgBcAGYAQI",
+ stops_one_stop_or_fewer: "CBwQAhogEgoyMDMwLTA5LTE1KAFqBwgBEgNKRktyBwgBEgNMQVhAAUgBcAGYAQI",
+ stops_two_or_fewer_stops: "CBwQAhogEgoyMDMwLTA5LTE1KAJqBwgBEgNKRktyBwgBEgNMQVhAAUgBcAGYAQI",
+ sweep_one_way_date_override: "CBwQAhoeEgoyMDMwLTExLTAyagcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC",
+ sweep_round_trip_date_override:
+ "CBwQAhoeEgoyMDMwLTExLTAyagcIARIDSkZLcgcIARIDTEFYGh4SCjIwMzAtMTEtMDlqBwgBEgNMQVhyBwgBEgNKRktAAUgBcAGYAQE",
+};
+
+const OUT = "2030-09-15";
+const RET = "2030-09-19";
+const MULTI = "2030-10-15";
+
+// ---------------------------------------------------------------------------
+// Builders mirroring the Python test helpers
+// ---------------------------------------------------------------------------
+
+interface FilterOverrides {
+ trip_type?: TripType;
+ passenger_info?: Partial<PassengerInfo>;
+ stops?: MaxStops;
+ seat_type?: SeatType;
+ airlines?: Airline[] | null;
+ airlines_exclude?: Airline[] | null;
+ max_duration?: number | null;
+ price_limit?: PriceLimit | null;
+ alliances?: Alliance[] | null;
+ alliances_exclude?: Alliance[] | null;
+ layover_restrictions?: LayoverRestrictions | null;
+ time_restrictions?: TimeRestrictions | null;
+}
+
+function pax(counts: Partial<PassengerInfo> = {}): PassengerInfo {
+ return {
+ adults: counts.adults ?? 1,
+ children: counts.children ?? 0,
+ infants_in_seat: counts.infants_in_seat ?? 0,
+ infants_on_lap: counts.infants_on_lap ?? 0,
+ };
+}
+
+function filters(
+ segments: Array<[string[], string[], string]>,
+ overrides: FilterOverrides = {},
+): FlightSearchFilters {
+ return new FlightSearchFilters({
+ trip_type: overrides.trip_type ?? TripType.ONE_WAY,
+ passenger_info: pax(overrides.passenger_info),
+ flight_segments: segments.map(([o, d, date]) => {
+ const s = new FlightSegment({
+ departure_airport: [o.map((x) => [x as Airport, 0])],
+ arrival_airport: [d.map((x) => [x as Airport, 0])],
+ travel_date: date,
+ time_restrictions: overrides.time_restrictions ?? null,
+ });
+ return s;
+ }),
+ stops: overrides.stops ?? MaxStops.ANY,
+ seat_type: overrides.seat_type ?? SeatType.ECONOMY,
+ airlines: overrides.airlines ?? null,
+ airlines_exclude: overrides.airlines_exclude ?? null,
+ max_duration: overrides.max_duration ?? null,
+ price_limit: overrides.price_limit ?? null,
+ alliances: overrides.alliances ?? null,
+ alliances_exclude: overrides.alliances_exclude ?? null,
+ layover_restrictions: overrides.layover_restrictions ?? null,
+ });
+}
+
+function leg(over: Partial<FlightLeg> = {}): FlightLeg {
+ return {
+ airline: Airline.AA,
+ flight_number: "171",
+ departure_airport: Airport.JFK,
+ arrival_airport: Airport.LAX,
+ departure_datetime: new Date(2030, 8, 15, 9, 0),
+ arrival_datetime: new Date(2030, 8, 15, 12, 0),
+ duration: 180,
+ ...over,
+ };
+}
+
+function flight(
+ over: { airline?: Airline; price?: number | null; duration?: number; hour?: number } = {},
+): FlightResult {
+ const hour = over.hour ?? 9;
+ const duration = over.duration ?? 180;
+ return {
+ legs: [
+ leg({
+ airline: over.airline ?? Airline.AA,
+ departure_datetime: new Date(2030, 8, 15, hour, 0),
+ arrival_datetime: new Date(2030, 8, 15, hour + 3, 0),
+ duration,
+ }),
+ ],
+ price: over.price === undefined ? 300 : over.price,
+ currency: "USD",
+ duration,
+ stops: 0,
+ };
+}
+
+function decode(tfs: string): Uint8Array {
+ const padded = tfs + "=".repeat((4 - (tfs.length % 4)) % 4);
+ return new Uint8Array(Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64"));
+}
+
+/** Read the repeated field 8 (passenger kinds) out of a `tfs` token. */
+function passengerCodes(tfs: string): number[] {
+ const raw = decode(tfs);
+ const codes: number[] = [];
+ let offset = 0;
+ const readVarint = (): number => {
+ let value = 0;
+ let shift = 0;
+ while (true) {
+ const byte = raw[offset] as number;
+ offset++;
+ value += (byte & 0x7f) * 2 ** shift;
+ if ((byte & 0x80) === 0) return value;
+ shift += 7;
+ }
+ };
+ while (offset < raw.length) {
+ const tag = readVarint();
+ const field = tag >> 3;
+ const wire = tag & 0x7;
+ if (wire === 0) {
+ const value = readVarint();
+ if (field === 8) codes.push(value);
+ } else if (wire === 2) {
+ // `offset += readVarint()` would read `offset` before the call
+ // mutates it, and skip from the wrong place.
+ const length = readVarint();
+ offset += length;
+ } else {
+ throw new Error(`unexpected wire type ${wire} at offset ${offset}`);
+ }
+ }
+ return codes;
+}
+
+// ---------------------------------------------------------------------------
+// Token parity with the Python implementation
+// ---------------------------------------------------------------------------
+
+describe("buildTfs golden parity with Python", () => {
+ const cases: Array<[string, () => string]> = [
+ ["one_way_jfk_lax", () => buildTfs(filters([[["JFK"], ["LAX"], OUT]]))],
+ [
+ "round_trip_jfk_lax",
+ () =>
+ buildTfs(
+ filters(
+ [
+ [["JFK"], ["LAX"], OUT],
+ [["LAX"], ["JFK"], RET],
+ ],
+ { trip_type: TripType.ROUND_TRIP },
+ ),
+ ),
+ ],
+ [
+ "round_trip_selected_outbound",
+ () => {
+ const spec = filters(
+ [
+ [["JFK"], ["LHR"], OUT],
+ [["LHR"], ["JFK"], RET],
+ ],
+ { trip_type: TripType.ROUND_TRIP },
+ );
+ (spec.flight_segments[0] as FlightSegment).selected_flight = {
+ legs: [
+ leg({
+ airline: Airline.BA,
+ flight_number: "178",
+ departure_airport: Airport.JFK,
+ arrival_airport: Airport.LHR,
+ departure_datetime: new Date(2030, 8, 15, 20, 30),
+ arrival_datetime: new Date(2030, 8, 16, 8, 30),
+ duration: 420,
+ }),
+ ],
+ price: 295,
+ currency: "USD",
+ duration: 420,
+ stops: 0,
+ };
+ return buildTfs(spec);
+ },
+ ],
+ [
+ "round_trip_selected_connecting_outbound",
+ () => {
+ const spec = filters(
+ [
+ [["JFK"], ["LHR"], OUT],
+ [["LHR"], ["JFK"], RET],
+ ],
+ { trip_type: TripType.ROUND_TRIP },
+ );
+ (spec.flight_segments[0] as FlightSegment).selected_flight = {
+ legs: [
+ leg({
+ airline: Airline.AA,
+ flight_number: "100",
+ departure_airport: Airport.JFK,
+ arrival_airport: Airport.ORD,
+ departure_datetime: new Date(2030, 8, 15, 7, 0),
+ arrival_datetime: new Date(2030, 8, 15, 9, 0),
+ duration: 150,
+ }),
+ leg({
+ airline: Airline.AA,
+ flight_number: "200",
+ departure_airport: Airport.ORD,
+ arrival_airport: Airport.LHR,
+ departure_datetime: new Date(2030, 8, 15, 17, 0),
+ arrival_datetime: new Date(2030, 8, 16, 7, 0),
+ duration: 480,
+ }),
+ ],
+ price: 420,
+ currency: "USD",
+ duration: 900,
+ stops: 1,
+ };
+ return buildTfs(spec);
+ },
+ ],
+ ["multi_airport", () => buildTfs(filters([[["BOM", "DEL", "AMD"], ["ORD", "DTW"], MULTI]]))],
+ ["cabin_economy", () => buildTfs(filters([[["JFK"], ["LAX"], OUT]]))],
+ [
+ "cabin_premium_economy",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { seat_type: SeatType.PREMIUM_ECONOMY })),
+ ],
+ [
+ "cabin_business",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { seat_type: SeatType.BUSINESS })),
+ ],
+ [
+ "cabin_first",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { seat_type: SeatType.FIRST })),
+ ],
+ ["stops_any", () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { stops: MaxStops.ANY }))],
+ [
+ "stops_non_stop",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { stops: MaxStops.NON_STOP })),
+ ],
+ [
+ "stops_one_stop_or_fewer",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { stops: MaxStops.ONE_STOP_OR_FEWER })),
+ ],
+ [
+ "stops_two_or_fewer_stops",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { stops: MaxStops.TWO_OR_FEWER_STOPS })),
+ ],
+ [
+ "pax_single_adult",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { passenger_info: { adults: 1 } })),
+ ],
+ [
+ "pax_two_adults",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { passenger_info: { adults: 2 } })),
+ ],
+ [
+ "pax_adult_child",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], { passenger_info: { adults: 1, children: 1 } }),
+ ),
+ ],
+ [
+ "pax_adult_lap_infant",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], { passenger_info: { adults: 1, infants_on_lap: 1 } }),
+ ),
+ ],
+ [
+ "pax_adult_seat_infant",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], { passenger_info: { adults: 1, infants_in_seat: 1 } }),
+ ),
+ ],
+ [
+ "pax_family_mix",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], {
+ passenger_info: { adults: 2, children: 1, infants_in_seat: 1, infants_on_lap: 1 },
+ }),
+ ),
+ ],
+ [
+ "pax_full_house",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], {
+ passenger_info: { adults: 4, children: 2, infants_in_seat: 2, infants_on_lap: 1 },
+ }),
+ ),
+ ],
+ [
+ "pax_two_adults_two_lap_infants",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], { passenger_info: { adults: 2, infants_on_lap: 2 } }),
+ ),
+ ],
+ [
+ "alliance_include_oneworld",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { alliances: [Alliance.ONEWORLD] })),
+ ],
+ [
+ "alliance_include_skyteam",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { alliances: [Alliance.SKYTEAM] })),
+ ],
+ [
+ "alliance_include_star_alliance",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { alliances: [Alliance.STAR_ALLIANCE] })),
+ ],
+ [
+ "alliance_exclude_oneworld",
+ () =>
+ buildTfs(filters([[["JFK"], ["LAX"], OUT]], { alliances_exclude: [Alliance.ONEWORLD] })),
+ ],
+ [
+ "alliance_exclude_skyteam",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]], { alliances_exclude: [Alliance.SKYTEAM] })),
+ ],
+ [
+ "alliance_exclude_star_alliance",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], { alliances_exclude: [Alliance.STAR_ALLIANCE] }),
+ ),
+ ],
+ [
+ "alliance_include_two_exclude_one",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], {
+ alliances: [Alliance.ONEWORLD, Alliance.STAR_ALLIANCE],
+ alliances_exclude: [Alliance.SKYTEAM],
+ }),
+ ),
+ ],
+ [
+ "layover_airport_and_min",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], {
+ layover_restrictions: { airports: [Airport.ORD], min_duration: 120 },
+ }),
+ ),
+ ],
+ [
+ "layover_max_only",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], { layover_restrictions: { max_duration: 300 } }),
+ ),
+ ],
+ [
+ "layover_full",
+ () =>
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], {
+ layover_restrictions: {
+ airports: [Airport.ORD, Airport.DFW],
+ min_duration: 90,
+ max_duration: 600,
+ },
+ }),
+ ),
+ ],
+ [
+ "kitchen_sink_round_trip",
+ () =>
+ buildTfs(
+ filters(
+ [
+ [["JFK", "EWR"], ["LHR", "LGW"], OUT],
+ [["LHR", "LGW"], ["JFK", "EWR"], RET],
+ ],
+ {
+ trip_type: TripType.ROUND_TRIP,
+ stops: MaxStops.ONE_STOP_OR_FEWER,
+ seat_type: SeatType.BUSINESS,
+ passenger_info: { adults: 2, children: 1, infants_on_lap: 1 },
+ alliances: [Alliance.ONEWORLD],
+ layover_restrictions: {
+ airports: [Airport.DUB],
+ min_duration: 60,
+ max_duration: 240,
+ },
+ },
+ ),
+ ),
+ ],
+ [
+ "sweep_one_way_date_override",
+ () => buildTfs(filters([[["JFK"], ["LAX"], OUT]]), { travelDates: ["2030-11-02"] }),
+ ],
+ [
+ "sweep_round_trip_date_override",
+ () =>
+ buildTfs(
+ filters(
+ [
+ [["JFK"], ["LAX"], OUT],
+ [["LAX"], ["JFK"], RET],
+ ],
+ { trip_type: TripType.ROUND_TRIP },
+ ),
+ { travelDates: ["2030-11-02", "2030-11-09"] },
+ ),
+ ],
+ ];
+
+ for (const [name, build] of cases) {
+ test(`${name} is byte-identical to Python`, () => {
+ const golden = TFS_GOLDENS[name];
+ expect(golden).toBeDefined();
+ expect(build()).toBe(golden as string);
+ });
+ }
+
+ test("every golden is covered by a case", () => {
+ expect(new Set(cases.map(([name]) => name))).toEqual(new Set(Object.keys(TFS_GOLDENS)));
+ });
+});
+
+describe("buildTfs structure", () => {
+ test("MaxStops.ANY omits the ceiling — writing 0 would mean non-stop", () => {
+ expect(buildTfs(filters([[["JFK"], ["LAX"], OUT]]))).not.toBe(TFS_GOLDENS.stops_non_stop);
+ });
+
+ test("every airport in a multi-airport segment reaches the request", () => {
+ const raw = Buffer.from(
+ decode(buildTfs(filters([[["BOM", "DEL", "AMD"], ["ORD", "DTW"], MULTI]]))),
+ );
+ for (const code of ["BOM", "DEL", "AMD", "ORD", "DTW"]) {
+ expect(raw.includes(code)).toBe(true);
+ }
+ });
+
+ test("field 19 says one-way (2) or round trip (1)", () => {
+ const oneWay = decode(buildTfs(filters([[["JFK"], ["LAX"], OUT]])));
+ const roundTrip = decode(
+ buildTfs(
+ filters(
+ [
+ [["JFK"], ["LAX"], OUT],
+ [["LAX"], ["JFK"], RET],
+ ],
+ { trip_type: TripType.ROUND_TRIP },
+ ),
+ ),
+ );
+ expect(Array.from(oneWay.slice(-3))).toEqual([0x98, 0x01, 0x02]);
+ expect(Array.from(roundTrip.slice(-3))).toEqual([0x98, 0x01, 0x01]);
+ });
+
+ test("multi-city is refused with a typed error", () => {
+ const spec = filters(
+ [
+ [["MNL"], ["DXB"], "2030-10-12"],
+ [["DXB"], ["FCO"], "2030-10-16"],
+ [["FCO"], ["MNL"], "2030-10-25"],
+ ],
+ { trip_type: TripType.MULTI_CITY },
+ );
+ expect(() => buildTfs(spec)).toThrow(SearchUnsupportedError);
+ expect(() => buildTfs(spec)).toThrow(/Multi-city/);
+ });
+});
+
+describe("passenger wire codes", () => {
+ // These codes are money: on an international route a lap infant prices
+ // at ~10% of the adult fare while an infant in its own seat prices like
+ // a child, at ~100%. Swapping the two produces a plausible,
+ // non-erroring search that quotes the wrong fare.
+ const kinds: Array<[keyof PassengerInfo, number]> = [
+ ["adults", 1],
+ ["children", 2],
+ ["infants_on_lap", 3],
+ ["infants_in_seat", 4],
+ ];
+
+ for (const [field, code] of kinds) {
+ test(`${field} encodes as ${code}`, () => {
+ const counts: Partial<PassengerInfo> = { adults: 1 };
+ counts[field] = (counts[field] ?? 0) + 1;
+ expect(
+ passengerCodes(
+ buildTfs(
+ filters([[["JFK"], ["LAX"], OUT]], {
+ passenger_info: counts,
+ }),
+ ),
+ ),
+ ).toEqual([1, code]);
+ });
+ }
+
+ test("a lap infant is 3 and a seat infant is 4, not the other way round", () => {
+ const lap = filters([[["JFK"], ["LAX"], OUT]], {
+ passenger_info: { adults: 1, infants_on_lap: 1 },
+ });
+ const seat = filters([[["JFK"], ["LAX"], OUT]], {
+ passenger_info: { adults: 1, infants_in_seat: 1 },
+ });
+ expect(passengerCodes(buildTfs(lap))).toEqual([1, 3]);
+ expect(passengerCodes(buildTfs(seat))).toEqual([1, 4]);
+ });
+
+ test("one field-8 entry per traveller, in field order", () => {
+ const spec = filters([[["JFK"], ["LAX"], OUT]], {
+ passenger_info: { adults: 2, children: 1, infants_in_seat: 1, infants_on_lap: 1 },
+ });
+ expect(passengerCodes(buildTfs(spec))).toEqual([1, 1, 2, 3, 4]);
+ });
+
+ test("an all-zero mix still books one adult", () => {
+ const spec = filters([[["JFK"], ["LAX"], OUT]], {
+ passenger_info: { adults: 0, children: 0, infants_in_seat: 0, infants_on_lap: 0 },
+ });
+ expect(passengerCodes(buildTfs(spec))).toEqual([1]);
+ });
+});
+
+describe("pageUrl", () => {
+ test("includes locale and currency", () => {
+ const url = pageUrl("TFS", "EUR", "de", "DE");
+ expect(url).toContain("tfs=TFS");
+ expect(url).toContain("curr=EUR");
+ expect(url).toContain("hl=de");
+ expect(url).toContain("gl=DE");
+ });
+
+ test("defaults when locale omitted", () => {
+ const url = pageUrl("TFS");
+ expect(url).toContain("hl=en");
+ expect(url).toContain("gl=US");
+ expect(url).not.toContain("curr=");
+ });
+});
+
+describe("extractPayload", () => {
+ test("reads the ds:1 blob past the other AF_initDataCallback blocks", () => {
+ const html =
+ "<script>AF_initDataCallback({key: 'ds:0', hash: '1', " +
+ 'data:["other"], sideChannel: {}});</script>' +
+ "<script>AF_initDataCallback({key: 'ds:1', hash: '2', " +
+ 'data:[1,2,[["row"]]], sideChannel: {}});</script>';
+ expect(extractPayload(html)).toEqual([1, 2, [["row"]]]);
+ });
+
+ test("returns null without a ds:1 block", () => {
+ const html =
+ "<script>AF_initDataCallback({key: 'ds:4', hash: '2', data:[], sideChannel: {}});</script>";
+ expect(extractPayload(html)).toBeNull();
+ });
+
+ test("returns null on an unparseable blob, with one concise warning", () => {
+ const html =
+ "<script>AF_initDataCallback({key: 'ds:1', hash: '2', data:[oops, sideChannel: {}});</script>";
+ const warnings: string[] = [];
+ setSearchLogger({
+ warn: (m) => warnings.push(m),
+ debug: () => {},
+ });
+ try {
+ expect(extractPayload(html)).toBeNull();
+ } finally {
+ setSearchLogger(null);
+ }
+ // Exactly one line, and no stack trace on a per-page code path.
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0]).toContain("ds:1 blob is not valid JSON");
+ expect(warnings[0]).not.toContain(" at ");
+ });
+});
+
+describe("fetchPayload retry", () => {
+ const restoreSleep = () => _setPageRetrySleep(null);
+
+ function pageWith(payload: unknown): string {
+ return `<script>AF_initDataCallback({key: 'ds:1', hash: '1', data:${JSON.stringify(payload)}, sideChannel: {}});</script>`;
+ }
+
+ test("a page missing ds:1 once then present takes exactly 2 fetches", async () => {
+ const slept: number[] = [];
+ _setPageRetrySleep(async (ms) => {
+ slept.push(ms);
+ });
+ try {
+ let calls = 0;
+ const client = new Client({
+ retries: 1,
+ fetchImpl: (async () => {
+ calls++;
+ return new Response(calls === 1 ? "<html>no payload</html>" : pageWith([1, 2]), {
+ status: 200,
+ });
+ }) as unknown as typeof fetch,
+ });
+ expect(await fetchPayload(client, "https://example.com")).toEqual([1, 2]);
+ expect(calls).toBe(2);
+ expect(slept).toEqual([500]);
+ } finally {
+ restoreSleep();
+ }
+ });
+
+ test("a page missing ds:1 every time gives up after exactly 3 fetches", async () => {
+ const slept: number[] = [];
+ _setPageRetrySleep(async (ms) => {
+ slept.push(ms);
+ });
+ try {
+ let calls = 0;
+ const client = new Client({
+ retries: 1,
+ fetchImpl: (async () => {
+ calls++;
+ return new Response("<html>no payload</html>", { status: 200 });
+ }) as unknown as typeof fetch,
+ });
+ expect(await fetchPayload(client, "https://example.com")).toBeNull();
+ expect(calls).toBe(PAGE_FETCH_ATTEMPTS);
+ expect(calls).toBe(3);
+ // Backs off between attempts only, never after the last one.
+ expect(slept).toEqual([500, 1500]);
+ } finally {
+ restoreSleep();
+ }
+ });
+
+ test("a good page on the first try costs exactly one fetch and no sleep", async () => {
+ const slept: number[] = [];
+ _setPageRetrySleep(async (ms) => {
+ slept.push(ms);
+ });
+ try {
+ let calls = 0;
+ const client = new Client({
+ retries: 1,
+ fetchImpl: (async () => {
+ calls++;
+ return new Response(pageWith(["ok"]), { status: 200 });
+ }) as unknown as typeof fetch,
+ });
+ expect(await fetchPayload(client, "https://example.com")).toEqual(["ok"]);
+ expect(calls).toBe(1);
+ expect(slept).toEqual([]);
+ } finally {
+ restoreSleep();
+ }
+ });
+
+ test("an HTTP error propagates on the first attempt — no page-level retry", async () => {
+ let calls = 0;
+ const client = new Client({
+ retries: 1,
+ fetchImpl: (async () => {
+ calls++;
+ return new Response("nope", { status: 503 });
+ }) as unknown as typeof fetch,
+ });
+ await expect(fetchPayload(client, "https://example.com")).rejects.toThrow(/HTTP 503/);
+ expect(calls).toBe(1);
+ });
+});
+
+describe("applyClientSideFilters", () => {
+ test("airline include keeps only matching carriers", () => {
+ const kept = applyClientSideFilters(
+ [flight({ airline: Airline.AA }), flight({ airline: Airline.DL })],
+ filters([[["JFK"], ["LAX"], OUT]], { airlines: [Airline.AA] }),
+ );
+ expect(kept.map((f) => f.legs[0]?.airline)).toEqual([Airline.AA]);
+ });
+
+ test("airline exclude drops matching carriers", () => {
+ const kept = applyClientSideFilters(
+ [flight({ airline: Airline.AA }), flight({ airline: Airline.DL })],
+ filters([[["JFK"], ["LAX"], OUT]], { airlines_exclude: [Airline.AA] }),
+ );
+ expect(kept.map((f) => f.legs[0]?.airline)).toEqual([Airline.DL]);
+ });
+
+ test("price cap drops expensive flights", () => {
+ const kept = applyClientSideFilters(
+ [flight({ price: 100 }), flight({ price: 900 })],
+ filters([[["JFK"], ["LAX"], OUT]], { price_limit: { max_price: 500, currency: null } }),
+ );
+ expect(kept.map((f) => f.price)).toEqual([100]);
+ });
+
+ test("max duration drops long flights", () => {
+ const kept = applyClientSideFilters(
+ [flight({ duration: 120 }), flight({ duration: 600 })],
+ filters([[["JFK"], ["LAX"], OUT]], { max_duration: 300 }),
+ );
+ expect(kept.map((f) => f.duration)).toEqual([120]);
+ });
+
+ test("departure window drops flights outside it", () => {
+ const kept = applyClientSideFilters(
+ [flight({ hour: 6 }), flight({ hour: 20 })],
+ filters([[["JFK"], ["LAX"], OUT]], {
+ time_restrictions: { earliest_departure: 8, latest_departure: 22 },
+ }),
+ );
+ expect(kept.map((f) => f.legs[0]?.departure_datetime.getHours())).toEqual([20]);
+ });
+
+ test("the window follows the segment still being chosen", () => {
+ // During round-trip expansion the outbound is pinned and the rows
+ // coming back are return options. Filtering them against segment
+ // zero's window drops valid returns and keeps invalid ones.
+ const spec = new FlightSearchFilters({
+ trip_type: TripType.ROUND_TRIP,
+ passenger_info: pax(),
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LAX, 0]]],
+ travel_date: OUT,
+ time_restrictions: { earliest_departure: 5, latest_departure: 9 },
+ selected_flight: flight({ hour: 6 }),
+ }),
+ new FlightSegment({
+ departure_airport: [[[Airport.LAX, 0]]],
+ arrival_airport: [[[Airport.JFK, 0]]],
+ travel_date: RET,
+ time_restrictions: { earliest_departure: 18, latest_departure: 23 },
+ }),
+ ],
+ });
+ const kept = applyClientSideFilters([flight({ hour: 6 }), flight({ hour: 20 })], spec);
+ expect(kept.map((f) => f.legs[0]?.departure_datetime.getHours())).toEqual([20]);
+ });
+
+ test("with nothing pinned, segment zero's window applies", () => {
+ const spec = new FlightSearchFilters({
+ trip_type: TripType.ROUND_TRIP,
+ passenger_info: pax(),
+ flight_segments: [
+ new FlightSegment({
+ departure_airport: [[[Airport.JFK, 0]]],
+ arrival_airport: [[[Airport.LAX, 0]]],
+ travel_date: OUT,
+ time_restrictions: { earliest_departure: 5, latest_departure: 9 },
+ }),
+ new FlightSegment({
+ departure_airport: [[[Airport.LAX, 0]]],
+ arrival_airport: [[[Airport.JFK, 0]]],
+ travel_date: RET,
+ time_restrictions: { earliest_departure: 18, latest_departure: 23 },
+ }),
+ ],
+ });
+ const kept = applyClientSideFilters([flight({ hour: 6 }), flight({ hour: 20 })], spec);
+ expect(kept.map((f) => f.legs[0]?.departure_datetime.getHours())).toEqual([6]);
+ });
+
+ test("a legless row cannot satisfy a window, and does not crash the search", () => {
+ const legless = { ...flight(), legs: [] };
+ const spec = filters([[["JFK"], ["LAX"], OUT]], {
+ time_restrictions: { earliest_departure: 0, latest_departure: 23 },
+ });
+ expect(applyClientSideFilters([legless], spec)).toEqual([]);
+ });
+
+ test("no filters keeps everything", () => {
+ const all = [flight({ airline: Airline.AA }), flight({ airline: Airline.DL })];
+ expect(applyClientSideFilters(all, filters([[["JFK"], ["LAX"], OUT]]))).toEqual(all);
+ });
+});
+
+describe("unsupportedFilters", () => {
+ test("reports nothing for a plain search", () => {
+ expect(unsupportedFilters(filters([[["JFK"], ["LAX"], OUT]]))).toEqual([]);
+ });
+
+ test("names the filters the page cannot honour", () => {
+ const spec = filters([[["JFK"], ["LAX"], OUT]]);
+ spec.exclude_basic_economy = true;
+ spec.emissions = 1;
+ spec.bags = { checked_bags: 1, carry_on: true };
+ expect(unsupportedFilters(spec).sort()).toEqual(["bags", "emissions", "exclude_basic_economy"]);
+ });
+
+ test("alliances and layovers ride in the request, so are not unsupported", () => {
+ const spec = filters([[["JFK"], ["LAX"], OUT]], {
+ alliances: [Alliance.SKYTEAM],
+ layover_restrictions: { min_duration: 90 },
+ });
+ expect(unsupportedFilters(spec)).toEqual([]);
+ });
+});
diff --git a/fli-js/tests/search/tfs_encoder.test.ts b/fli-js/tests/search/tfs_encoder.test.ts
new file mode 100644
index 0000000..a1b42e3
--- /dev/null
+++ b/fli-js/tests/search/tfs_encoder.test.ts
@@ -0,0 +1,111 @@
+/**
+ * Low-level `tfs` protobuf encoder tests.
+ *
+ * The tokens below were issued by Google itself for the same queries (the
+ * same captures the Python suite pins in `tests/search/test_tfs.py`), so a
+ * byte mismatch means the encoder has drifted from what Google accepts.
+ *
+ * These exercise `encodeTfsSegment` / `encodeTfsPayload` directly rather
+ * than through `buildTfs`, because the captures carry 2026 travel dates
+ * that `FlightSegment` now rejects as past — see `tfs.test.ts` for the
+ * filter-level goldens, which use dates far enough out to stay valid.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { buildTfsToken, encodeTfsPayload, encodeTfsSegment } from "../../src/search/proto.ts";
+
+// Captured from Google's own search-page URLs (2026-08-26) for
+// JFK -> LAX on 2026-09-15, returning 2026-09-19.
+const TFS_ONE_WAY = "CBwQAhoeEgoyMDI2LTA5LTE1agcIARIDSkZLcgcIARIDTEFYQAFIAXABmAEC";
+const TFS_NON_STOP = "CBwQAhogEgoyMDI2LTA5LTE1KABqBwgBEgNKRktyBwgBEgNMQVhAAUgBcAGYAQI";
+const TFS_ROUND_TRIP =
+ "CBwQAhoeEgoyMDI2LTA5LTE1agcIARIDSkZLcgcIARIDTEFYGh4SCjIwMjYtMDktMTlqBwgBEgNMQVhy" +
+ "BwgBEgNKRktAAUgBcAGYAQE";
+const TFS_MULTI_AIRPORT =
+ "CBwQAho5EgoyMDI2LTEwLTE1agcIARIDQk9NagcIARIDREVMagcIARIDQU1EcgcIARIDT1JEcgcIARIDRFRX" +
+ "QAFIAXABmAEC";
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+ let total = 0;
+ for (const p of parts) total += p.length;
+ const out = new Uint8Array(total);
+ let off = 0;
+ for (const p of parts) {
+ out.set(p, off);
+ off += p.length;
+ }
+ return out;
+}
+
+function decode(tfs: string): Uint8Array {
+ const padded = tfs + "=".repeat((4 - (tfs.length % 4)) % 4);
+ return new Uint8Array(Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64"));
+}
+
+function includesBytes(haystack: Uint8Array, needle: number[]): boolean {
+ outer: for (let i = 0; i + needle.length <= haystack.length; i++) {
+ for (let j = 0; j < needle.length; j++) {
+ if (haystack[i + j] !== needle[j]) continue outer;
+ }
+ return true;
+ }
+ return false;
+}
+
+describe("encodeTfsSegment / encodeTfsPayload", () => {
+ test("one-way matches the tfs Google issued", () => {
+ const seg = encodeTfsSegment("JFK", "LAX", "2026-09-15");
+ expect(encodeTfsPayload(seg, { isOneWay: true })).toBe(TFS_ONE_WAY);
+ });
+
+ test("non-stop matches the tfs Google issued", () => {
+ const seg = encodeTfsSegment("JFK", "LAX", "2026-09-15", { maxStops: 0 });
+ expect(encodeTfsPayload(seg, { isOneWay: true })).toBe(TFS_NON_STOP);
+ });
+
+ test("round trip matches the tfs Google issued", () => {
+ const segs = concat(
+ encodeTfsSegment("JFK", "LAX", "2026-09-15"),
+ encodeTfsSegment("LAX", "JFK", "2026-09-19"),
+ );
+ expect(encodeTfsPayload(segs, { isOneWay: false })).toBe(TFS_ROUND_TRIP);
+ });
+
+ test("multi-airport matches the tfs Google issued", () => {
+ const seg = encodeTfsSegment(["BOM", "DEL", "AMD"], ["ORD", "DTW"], "2026-10-15");
+ expect(encodeTfsPayload(seg, { isOneWay: true })).toBe(TFS_MULTI_AIRPORT);
+ });
+
+ test("maxStops null omits the ceiling entirely", () => {
+ // Writing 0 for "any" would silently pin every search to non-stop.
+ const any = encodeTfsPayload(encodeTfsSegment("JFK", "LAX", "2026-09-15"), { isOneWay: true });
+ expect(any).toBe(TFS_ONE_WAY);
+ expect(any).not.toBe(TFS_NON_STOP);
+ });
+
+ test("stop ceiling is zero-based and sits in field 5", () => {
+ for (const ceiling of [0, 1, 2]) {
+ const raw = decode(
+ encodeTfsPayload(encodeTfsSegment("JFK", "LAX", "2026-09-15", { maxStops: ceiling }), {
+ isOneWay: true,
+ }),
+ );
+ expect(includesBytes(raw, [0x28, ceiling])).toBe(true);
+ }
+ });
+
+ test("buildTfsToken is the same encoder, not a fork", () => {
+ // `buildTfsToken` (booking deep links) and `buildTfs` (search pages)
+ // write the same message; the deep link only adds the field-16 pin.
+ // Byte-for-byte captures for `buildTfsToken` itself live in
+ // `proto.test.ts` — this pins that it composes the shared helpers.
+ const legs = [
+ { origin: "SFO", depDate: "2026-06-15", dest: "PHX", airline: "AA", flightNumber: "2413" },
+ ];
+ const viaHelpers = encodeTfsPayload(encodeTfsSegment("SFO", "PHX", "2026-06-15", { legs }), {
+ isOneWay: true,
+ pinMaxU64: true,
+ });
+ expect(buildTfsToken([legs], { isOneWay: true })).toBe(viaHelpers);
+ });
+});