google-flights-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wooldox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,543 @@
+# ✈️ google-flights-ts
+
+A fast, strongly-typed Google Flights scraper for Node.js.
+
+TypeScript port of [AWeirdDev/flights](https://github.com/AWeirdDev/flights). Encodes search parameters into Google's protobuf-based `tfs` query parameter, fetches the results page, and parses flight data from the HTML or embedded JS response.
+
+> **Zero binary dependencies** — the protobuf encoding is hand-rolled, no native modules needed.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [`getFlights`](#getflightsoptions)
+  - [`getFlightsFromFilter`](#getflightsfromfilterfilter-options)
+  - [`FetchFn`](#fetchfn)
+  - [`createFilter`](#createfilteroptions)
+  - [`FlightData`](#new-flightdataoptions)
+  - [`Passengers`](#new-passengersoptions)
+  - [`searchAirport`](#searchairportquery)
+  - [`Cookies`](#cookies)
+- [Fetch Modes](#fetch-modes)
+- [Data Sources](#data-sources)
+- [Examples](#examples)
+- [How It Works](#how-it-works)
+- [Scripts](#scripts)
+- [License](#license)
+
+## Install
+
+```bash
+npm install google-flights-ts
+```
+
+### Optional: Local Playwright
+
+If you want to use the `local` fetch mode (headless browser):
+
+```bash
+npm install playwright
+npx playwright install chromium
+```
+
+## Quick Start
+
+```ts
+import { FlightData, Passengers, getFlights } from "google-flights-ts";
+
+const result = await getFlights({
+  flight_data: [
+    new FlightData({
+      date: "2026-07-01",
+      from_airport: "JFK",
+      to_airport: "LAX",
+    }),
+  ],
+  trip: "one-way",
+  seat: "economy",
+  adults: 1,
+});
+
+if (result && "flights" in result) {
+  console.log("Price trend:", result.current_price); // "low" | "typical" | "high"
+  for (const flight of result.flights) {
+    console.log(`${flight.name} ${flight.departure}-${flight.arrival} $${flight.price}`);
+  }
+}
+```
+
+## API Reference
+
+### `getFlights(options)`
+
+High-level function that builds a filter and fetches results in one call.
+
+```ts
+const result = await getFlights({
+  // Required
+  flight_data: FlightData[],
+  trip: "one-way" | "round-trip" | "multi-city",
+
+  // Passengers (either pass a Passengers object or use convenience counters)
+  passengers?: Passengers,
+  adults?: number,        // default: 1
+  children?: number,      // default: 0
+  infants_in_seat?: number, // default: 0
+  infants_on_lap?: number,  // default: 0
+
+  // Optional
+  seat?: "economy" | "premium-economy" | "business" | "first", // default: "economy"
+  fetch_mode?: FetchMode,       // default: "common"
+  max_stops?: number,           // undefined = any
+  data_source?: "html" | "js",  // default: "html"
+  cookies?: Record<string, string>,
+  request_options?: RequestOptions,
+  cookie_consent?: boolean,     // default: true
+  fetchFn?: FetchFn,            // custom fetch implementation (e.g. for proxies)
+});
+```
+
+**Returns:** `Promise<Result | DecodedResult | null>`
+
+- `Result` when `data_source` is `"html"` (default)
+- `DecodedResult` when `data_source` is `"js"`
+- `null` if no data found
+
+---
+
+### `getFlightsFromFilter(filter, options?)`
+
+Lower-level function that takes a pre-built `TFSData` filter.
+
+```ts
+import { createFilter, getFlightsFromFilter, FlightData, Passengers } from "google-flights-ts";
+
+const filter = createFilter({
+  flight_data: [
+    new FlightData({ date: "2026-07-01", from_airport: "LHR", to_airport: "SLC" }),
+    new FlightData({ date: "2026-07-15", from_airport: "SLC", to_airport: "LHR" }),
+  ],
+  trip: "round-trip",
+  passengers: new Passengers({ adults: 2, children: 1 }),
+  seat: "economy",
+  max_stops: 1,
+});
+
+const result = await getFlightsFromFilter(filter, {
+  currency: "USD",
+  mode: "common",
+  data_source: "html",
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `currency` | `string` | `""` | Currency code (e.g. `"USD"`, `"EUR"`) |
+| `mode` | `FetchMode` | `"common"` | How to fetch the page (see [Fetch Modes](#fetch-modes)) |
+| `data_source` | `"html" \| "js"` | `"html"` | Which parser to use (see [Data Sources](#data-sources)) |
+| `cookies` | `Record<string, string>` | - | Custom cookies to send |
+| `request_options` | `RequestOptions` | - | Custom headers/cookies for the request |
+| `cookie_consent` | `boolean` | `true` | Auto-include default consent cookies |
+| `fetchFn` | `FetchFn` | `fetch` | Custom fetch function (e.g. for proxy support) |
+
+---
+
+### `FetchFn`
+
+Type alias for a custom fetch implementation. Useful when you need to route requests through a proxy or add custom transport logic.
+
+```ts
+type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+```
+
+Both `getFlights` and `getFlightsFromFilter` accept an optional `fetchFn` parameter. When provided, it replaces the global `fetch` for the HTTP request to Google Flights.
+
+```ts
+import { FlightData, getFlights, type FetchFn } from "google-flights-ts";
+
+// Example: route through a SOCKS proxy using node:https + socks-proxy-agent
+import { SocksProxyAgent } from "socks-proxy-agent";
+import https from "node:https";
+
+const agent = new SocksProxyAgent("socks5://127.0.0.1:1080");
+
+const proxyFetch: FetchFn = (url, init) =>
+  new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const req = https.request(
+      {
+        hostname: parsed.hostname,
+        path: parsed.pathname + parsed.search,
+        method: init?.method ?? "GET",
+        headers: init?.headers as Record<string, string>,
+        agent,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (c: Buffer) => chunks.push(c));
+        res.on("end", () =>
+          resolve(
+            new Response(Buffer.concat(chunks), {
+              status: res.statusCode ?? 200,
+              headers: new Headers(res.headers as Record<string, string>),
+            }),
+          ),
+        );
+      },
+    );
+    req.on("error", reject);
+    req.end();
+  });
+
+const result = await getFlights({
+  flight_data: [
+    new FlightData({ date: "2026-07-01", from_airport: "JFK", to_airport: "LAX" }),
+  ],
+  trip: "one-way",
+  adults: 1,
+  fetchFn: proxyFetch,
+});
+```
+
+---
+
+### `createFilter(options)`
+
+Builds a `TFSData` filter object without fetching. Useful when you want to inspect the encoded URL or reuse the filter.
+
+```ts
+const filter = createFilter({
+  flight_data: [new FlightData({ date: "2026-07-01", from_airport: "JFK", to_airport: "LAX" })],
+  trip: "one-way",
+  passengers: new Passengers({ adults: 1 }),
+  seat: "economy",
+});
+
+// Get the Google Flights URL
+const url = `https://www.google.com/travel/flights?tfs=${filter.toBase64()}`;
+console.log(url);
+```
+
+---
+
+### `new FlightData(options)`
+
+Represents one leg of a journey.
+
+```ts
+new FlightData({
+  date: string,           // "YYYY-MM-DD"
+  from_airport: string,   // 3-letter IATA code or AIRPORTS key
+  to_airport: string,     // 3-letter IATA code or AIRPORTS key
+  max_stops?: number,     // 0 = nonstop, 1, 2, etc.
+  airlines?: string[],    // 2-letter codes or alliance names
+})
+```
+
+**Airport codes** can be either raw IATA codes (`"JFK"`, `"LAX"`) or the full name from the `AIRPORTS` object (`"ZURICH_AIRPORT"` resolves to `"ZRH"`).
+
+**Airlines** accepts 2-letter IATA airline codes (`"UA"`, `"AA"`) or alliance names: `"STAR_ALLIANCE"`, `"ONEWORLD"`, `"SKYTEAM"`.
+
+---
+
+### `new Passengers(options?)`
+
+```ts
+new Passengers({
+  adults?: number,          // default: 0
+  children?: number,        // default: 0
+  infants_in_seat?: number, // default: 0
+  infants_on_lap?: number,  // default: 0
+})
+```
+
+**Constraints:**
+- Total passengers must be <= 9
+- `infants_on_lap` must be <= `adults`
+
+---
+
+### `searchAirport(query)`
+
+Case-insensitive search across all 3,311 airports.
+
+```ts
+import { searchAirport } from "google-flights-ts";
+
+const results = searchAirport("zurich");
+// [{ name: "ZURICH_AIRPORT", code: "ZRH" }]
+
+const results2 = searchAirport("NEW_YORK");
+// [{ name: "NEW_YORK_JOHN_F_KENNEDY_INTERNATIONAL_AIRPORT", code: "JFK" }, ...]
+```
+
+---
+
+### `Cookies`
+
+Generate Google consent cookies for requests.
+
+```ts
+import { Cookies } from "google-flights-ts";
+
+const cookies = Cookies.create({ locale: "en" });
+cookies.toDict();    // { CONSENT: "PENDING+987", SOCS: "<base64>" }
+cookies.toBase64();  // base64-encoded SOCS protobuf
+```
+
+The library embeds default consent cookies automatically (controlled by the `cookie_consent` option). You only need `Cookies` if you want to generate fresh ones or customize the locale.
+
+---
+
+## Fetch Modes
+
+| Mode | Description |
+|------|-------------|
+| `"common"` | Direct HTTP request with Chrome-like headers. Fastest option. **(default)** |
+| `"fallback"` | Tries `common` first, falls back to serverless Playwright if it fails. Recommended for reliability. |
+| `"force-fallback"` | Always uses serverless Playwright via `try.playwright.tech`. |
+| `"local"` | Uses a local Playwright browser. Requires the `playwright` package. Best for privacy. |
+| `"bright-data"` | Uses Bright Data proxy API. Requires `BRIGHT_DATA_API_KEY` env var. |
+
+### Bright Data Configuration
+
+Set these environment variables:
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `BRIGHT_DATA_API_KEY` | Yes | - |
+| `BRIGHT_DATA_API_URL` | No | `https://api.brightdata.com/request` |
+| `BRIGHT_DATA_SERP_ZONE` | No | `serp_api1` |
+
+---
+
+## Data Sources
+
+### HTML mode (`data_source: "html"`) -- default
+
+Parses the rendered HTML using CSS selectors. Returns a `Result`:
+
+```ts
+interface Result {
+  current_price: "low" | "typical" | "high" | string;
+  flights: Flight[];
+}
+
+interface Flight {
+  is_best: boolean;
+  name: string;           // Airline name
+  departure: string;      // e.g. "2:30 PM"
+  arrival: string;        // e.g. "11:45 PM"
+  arrival_time_ahead: string; // e.g. "+1 day"
+  duration: string;       // e.g. "18h 15m"
+  stops: number | string; // 0 for nonstop, or "Unknown"
+  delay: string | null;
+  price: string;          // e.g. "523" (no currency symbol)
+}
+```
+
+### JS mode (`data_source: "js"`)
+
+Extracts structured data from the embedded JavaScript. Returns a `DecodedResult` with richer detail:
+
+```ts
+interface DecodedResult {
+  raw: unknown[];
+  best: Itinerary[];
+  other: Itinerary[];
+}
+
+interface Itinerary {
+  airline_code: string;
+  airline_names: string[];
+  flights: DecodedFlight[];
+  layovers: Layover[];
+  travel_time: number;          // minutes
+  departure_airport: string;
+  arrival_airport: string;
+  departure_date: [number, number, number]; // [year, month, day]
+  arrival_date: [number, number, number];
+  departure_time: [number, number];         // [hour, minute]
+  arrival_time: [number, number];
+  itinerary_summary: ItinerarySummary;
+}
+
+interface DecodedFlight {
+  airline: string;
+  airline_name: string;
+  flight_number: string;
+  operator: string;
+  codeshares: Codeshare[];
+  aircraft: string;
+  departure_airport: string;
+  departure_airport_name: string;
+  arrival_airport: string;
+  arrival_airport_name: string;
+  departure_date: [number, number, number];
+  arrival_date: [number, number, number];
+  departure_time: [number, number];
+  arrival_time: [number, number];
+  travel_time: number;
+  seat_pitch_short: string;
+}
+
+interface Layover {
+  minutes: number;
+  departure_airport: string;
+  departure_airport_name: string;
+  departure_airport_city: string;
+  arrival_airport: string;
+  arrival_airport_name: string;
+  arrival_airport_city: string;
+}
+
+interface Codeshare {
+  airline_code: string;
+  flight_number: number;
+  airline_name: string;
+}
+
+interface ItinerarySummary {
+  flights: string;
+  price: number;   // dollars (e.g. 150.00)
+  currency: string; // e.g. "USD"
+}
+```
+
+---
+
+## Examples
+
+### One-way flight
+
+```ts
+import { FlightData, getFlights } from "google-flights-ts";
+
+const result = await getFlights({
+  flight_data: [
+    new FlightData({ date: "2026-07-01", from_airport: "SFO", to_airport: "NRT" }),
+  ],
+  trip: "one-way",
+  adults: 1,
+  seat: "business",
+  max_stops: 1,
+});
+```
+
+### Round trip
+
+```ts
+import { FlightData, Passengers, getFlights } from "google-flights-ts";
+
+const result = await getFlights({
+  flight_data: [
+    new FlightData({ date: "2026-12-20", from_airport: "LHR", to_airport: "JFK" }),
+    new FlightData({ date: "2027-01-03", from_airport: "JFK", to_airport: "LHR" }),
+  ],
+  trip: "round-trip",
+  passengers: new Passengers({ adults: 2, children: 1, infants_on_lap: 1 }),
+  seat: "premium-economy",
+  fetch_mode: "fallback",
+});
+```
+
+### JS data source (detailed itinerary info)
+
+```ts
+import { FlightData, getFlights, type DecodedResult } from "google-flights-ts";
+
+const result = await getFlights({
+  flight_data: [
+    new FlightData({ date: "2026-10-04", from_airport: "SJC", to_airport: "LAS" }),
+  ],
+  trip: "one-way",
+  adults: 1,
+  data_source: "js",
+}) as DecodedResult | null;
+
+if (result) {
+  for (const itinerary of result.best) {
+    console.log(`${itinerary.airline_names.join(", ")} - ${itinerary.travel_time} min`);
+    console.log(`  $${itinerary.itinerary_summary.price} ${itinerary.itinerary_summary.currency}`);
+    for (const flight of itinerary.flights) {
+      console.log(`  ${flight.flight_number} ${flight.departure_airport}->${flight.arrival_airport} (${flight.aircraft})`);
+    }
+    for (const layover of itinerary.layovers) {
+      console.log(`  Layover: ${layover.minutes} min at ${layover.departure_airport_name}`);
+    }
+  }
+}
+```
+
+### Filter-only (generate URL without fetching)
+
+```ts
+import { FlightData, Passengers, createFilter } from "google-flights-ts";
+
+const filter = createFilter({
+  flight_data: [
+    new FlightData({ date: "2026-07-01", from_airport: "EWR", to_airport: "CDG" }),
+  ],
+  trip: "one-way",
+  passengers: new Passengers({ adults: 1 }),
+  seat: "economy",
+});
+
+console.log(`https://www.google.com/travel/flights?tfs=${filter.toBase64()}`);
+```
+
+### Custom cookies and headers
+
+```ts
+import { FlightData, Cookies, getFlights } from "google-flights-ts";
+
+const cookies = Cookies.create({ locale: "de" });
+
+const result = await getFlights({
+  flight_data: [
+    new FlightData({ date: "2026-08-15", from_airport: "FRA", to_airport: "BKK" }),
+  ],
+  trip: "one-way",
+  adults: 1,
+  cookies: cookies.toDict(),
+  request_options: {
+    headers: { "Accept-Language": "de-DE,de;q=0.9" },
+  },
+  cookie_consent: false, // disable default cookies since we're providing our own
+});
+```
+
+---
+
+## How It Works
+
+1. **Protobuf encoding** -- Flight search parameters (airports, dates, passengers, seat class, trip type) are serialized into a Protocol Buffer binary message, then base64-encoded. This becomes the `tfs` query parameter that Google Flights uses internally.
+
+2. **HTTP request** -- The encoded `tfs` parameter is sent to `https://www.google.com/travel/flights` using one of five fetch strategies (direct HTTP, serverless Playwright, local Playwright, or Bright Data proxy).
+
+3. **Response parsing** -- The HTML response is parsed with [cheerio](https://cheerio.js.org/) to extract flight cards (HTML mode), or the embedded JavaScript data blob is decoded from nested JSON arrays (JS mode).
+
+The protobuf encoding is hand-rolled (no runtime protobuf library needed) since the schema is small and fixed. The `.proto` definitions are in `src/proto/` for reference.
+
+---
+
+## Scripts
+
+```bash
+npm run build       # Compile TypeScript to dist/
+npm test            # Run tests (vitest)
+npm run test:watch  # Run tests in watch mode
+```
+
+---
+
+## Disclaimer
+
+This project is not affiliated with, endorsed by, or associated with Google. "Google Flights" is a trademark of Google LLC. This library is provided as-is for personal and educational use. Use responsibly and in accordance with Google's Terms of Service.
+
+## License
+
+MIT