Google Flights

bowmark.providers.google_flights.search(query: GoogleFlightQuery): Promise<GoogleFlight[]>
bowmark.providers.google_flights.getBookingOptions(query: GoogleFlightQuery, flightId: string): Promise<GoogleBookingOption[]>
bowmark.providers.google_flights.getPriceGraph(query: GoogleFlightQuery): Promise<GooglePriceGraph>

interface GoogleFlightQuery {
  from: string;            // IATA or city, e.g. "SFO"
  to: string;
  depart: string;          // YYYY-MM-DD
  return?: string;         // omit for one-way
  cabin?: "economy" | "premium" | "business" | "first";
  stops?: "any" | "nonstop" | "1";
  passengers?: number;
}

// Google Flights' OWN shapes — not the `flights` capability contract.
interface GoogleFlight {
  id: string;
  price: number | null;
  currency: string;
  tripType: "round trip" | "one way";
  airlines: string[];
  stops: number;
  depart: string;
  arrive: string;
  durationMinutes: number | null;
  url?: string;
}

interface GoogleBookingOption {
  provider: string;        // the OTA or airline selling it
  fareType: string;
  price: number | null;
  currency: string;
  deepLink: string | null; // null for JS-driven rows — see the caveat below
}

// One column of the price graph.
interface GooglePricePoint {
  date: string;             // departure date, "2026-08-22"
  returnDate: string | null;// the return date priced WITH it; null for one-way.
                            // Google slides a fixed-length trip, so a round-trip
                            // column is a whole trip, not just a departure date.
  price: number | null;     // cheapest total for that date
  currency: string;
}

interface GooglePriceGraph {
  from: string;
  to: string;
  tripType: "round trip" | "one way";
  stayNights: number | null;  // nights held constant across the window; null for
                              // one-way, or if the columns disagree
  rangeStart: string;         // the window GOOGLE chose (≈ depart-7 … depart+52).
  rangeEnd: string;           // It is not selectable — see the note below.
  points: GooglePricePoint[]; // ascending by departure date
  cheapest: GooglePricePoint | null;  // ties resolve to the earliest date
  url: string;
  checkedAt: string;
}

const rows = await bowmark.providers.google_flights.search({ from: "SFO", to: "JFK", depart: "2026-09-01" });
const cheapest = rows.sort((a, b) => (a.price ?? 1e9) - (b.price ?? 1e9))[0];
return await bowmark.providers.google_flights.getBookingOptions(
  { from: "SFO", to: "JFK", depart: "2026-09-01" },
  cheapest.id,
);