@tks/wayfinder 0.2.0 → 0.2.1

package/README.md

@@ -59,6 +59,12 @@ Structured output for scripting:
 wayfinder flights --from SFO --to JFK --date 2026-04-10 --json | jq '.results[] | {price,airline,stops}'
 ```
 
+Get booking links from selected flight tokens:
+
+```bash
+wayfinder flights booking --from LAS --to JFK --date 2026-05-29 --token "<TOKEN_1>" --token "<TOKEN_2>" --json
+```
+
 Search hotels:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tks/wayfinder",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Travel search for your terminal and your AI agents",
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -2,7 +2,7 @@ import { resolveApiKey } from "./config";
 import { CliError } from "./errors";
 import { renderFlightTable, renderHotelTable } from "./format";
 import { parseCliArgs } from "./parse";
-import { searchFlights, searchHotels } from "./serpapi";
+import { searchFlightBookingOptions, searchFlights, searchHotels } from "./serpapi";
 import { ExitCode } from "./types";
 
 interface Output {
@@ -22,6 +22,7 @@ const HELP_TEXT = `wayfinder v0.2.0 travel search
 Usage:
   wayfinder flights --from SFO --to JFK --date 2026-03-21 [filters]
   wayfinder flights one-way --from SFO --to JFK --date 2026-03-21 [filters]
+  wayfinder flights booking --from SFO --to JFK --date 2026-03-21 --token <BOOKING_TOKEN> [--token <BOOKING_TOKEN>] [--json]
   wayfinder hotels --where "New York, NY" --check-in 2026-03-21 --check-out 2026-03-23 [filters]
 
 Flights required:
@@ -37,6 +38,13 @@ Flights optional filters:
   --depart-before <HH:MM>   End of departure window
   --exclude-basic           Exclude basic economy fares
 
+Flights booking required:
+  --from <IATA>             Origin airport code
+  --to <IATA>               Destination airport code
+  --date <YYYY-MM-DD>       Departure date
+  --token <BOOKING_TOKEN>   Booking token from a flights search result
+  (repeat --token to request multiple options)
+
 Hotels required:
   --where <QUERY>           Destination or hotel search query
   --check-in <YYYY-MM-DD>   Check-in date
@@ -71,7 +79,7 @@ export async function runWayfinder(
     if (parsed.mode === "flights") {
       const flights = await searchFlights(parsed.query, apiKey, options.fetchImpl ?? fetch);
 
-      if (flights.length === 0) {
+      if (flights.options.length === 0) {
         throw new CliError("No flights found for the selected query", ExitCode.NoResults);
       }
 
@@ -80,14 +88,50 @@ export async function runWayfinder(
           JSON.stringify(
             {
               query: parsed.query,
-              results: flights,
+              googleFlightsUrl: flights.googleFlightsUrl,
+              results: flights.options,
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        output.stdout(renderFlightTable(flights.options));
+      }
+    } else if (parsed.mode === "flight-booking") {
+      const bookingResults = await searchFlightBookingOptions(
+        parsed.query,
+        apiKey,
+        options.fetchImpl ?? fetch,
+      );
+
+      const flightLinks = bookingResults
+        .filter((result) => typeof result.googleFlightsUrl === "string")
+        .map((result) => ({
+          token: result.token,
+          googleFlightsUrl: result.googleFlightsUrl as string,
+        }));
+
+      if (flightLinks.length === 0) {
+        throw new CliError(
+          "No Google Flights links found for the provided token(s)",
+          ExitCode.NoResults,
+        );
+      }
+
+      if (parsed.outputJson) {
+        output.stdout(
+          JSON.stringify(
+            {
+              query: parsed.query,
+              results: flightLinks,
             },
             null,
             2,
           ),
         );
       } else {
-        output.stdout(renderFlightTable(flights));
+        output.stdout(renderFlightBookingText(flightLinks));
       }
     } else {
       const hotels = await searchHotels(parsed.query, apiKey, options.fetchImpl ?? fetch);
@@ -128,3 +172,17 @@ if (import.meta.main) {
   const code = await runWayfinder(process.argv.slice(2));
   process.exitCode = code;
 }
+
+function renderFlightBookingText(
+  results: Array<{ token: string; googleFlightsUrl: string }>,
+): string {
+  const lines: string[] = [];
+
+  for (const result of results) {
+    lines.push(`TOKEN: ${result.token}`);
+    lines.push(`GOOGLE FLIGHTS: ${result.googleFlightsUrl}`);
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}

package/src/parse.ts

@@ -1,5 +1,5 @@
 import { CliError } from "./errors";
-import { ExitCode, FlightQuery, HotelQuery, ParsedArgs } from "./types";
+import { ExitCode, FlightBookingQuery, FlightQuery, HotelQuery, ParsedArgs } from "./types";
 
 interface FlightRawOptions {
   from?: string;
@@ -26,7 +26,16 @@ interface HotelRawOptions {
   help: boolean;
 }
 
-type SearchMode = "flights" | "hotels";
+interface FlightBookingRawOptions {
+  from?: string;
+  to?: string;
+  date?: string;
+  tokens: string[];
+  outputJson: boolean;
+  help: boolean;
+}
+
+type SearchMode = "flights" | "hotels" | "flight-booking";
 
 const HELP_FLAGS = new Set(["-h", "--help"]);
 
@@ -44,6 +53,10 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     return parseHotelsArgs(args);
   }
 
+  if (mode === "flight-booking") {
+    return parseFlightBookingArgs(args);
+  }
+
   return parseFlightsArgs(args);
 }
 
@@ -197,6 +210,73 @@ function parseHotelsArgs(args: string[]): ParsedArgs {
   };
 }
 
+function parseFlightBookingArgs(args: string[]): ParsedArgs {
+  const raw: FlightBookingRawOptions = {
+    tokens: [],
+    outputJson: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+
+    if (HELP_FLAGS.has(token)) {
+      raw.help = true;
+      continue;
+    }
+
+    if (token === "--json") {
+      raw.outputJson = true;
+      continue;
+    }
+
+    if (token === "--token") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new CliError("Missing value for --token", ExitCode.InvalidInput);
+      }
+      raw.tokens.push(value.trim());
+      i += 1;
+      continue;
+    }
+
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) {
+      throw new CliError(`Missing value for ${token}`, ExitCode.InvalidInput);
+    }
+
+    switch (token) {
+      case "--from":
+        raw.from = value;
+        break;
+      case "--to":
+        raw.to = value;
+        break;
+      case "--date":
+        raw.date = value;
+        break;
+      default:
+        throw new CliError(`Unknown flag: ${token}`, ExitCode.InvalidInput);
+    }
+
+    i += 1;
+  }
+
+  if (raw.help) {
+    return {
+      help: true,
+      outputJson: raw.outputJson,
+    };
+  }
+
+  return {
+    help: false,
+    mode: "flight-booking",
+    outputJson: raw.outputJson,
+    query: buildFlightBookingQuery(raw),
+  };
+}
+
 function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
   if (!raw.from || !raw.to || !raw.date) {
     throw new CliError("Missing required flags: --from, --to, --date", ExitCode.InvalidInput);
@@ -284,6 +364,31 @@ function buildHotelQuery(raw: HotelRawOptions): HotelQuery {
   };
 }
 
+function buildFlightBookingQuery(raw: FlightBookingRawOptions): FlightBookingQuery {
+  if (!raw.from || !raw.to || !raw.date) {
+    throw new CliError("Missing required flags: --from, --to, --date", ExitCode.InvalidInput);
+  }
+
+  const origin = normalizeAirport(raw.from, "origin");
+  const destination = normalizeAirport(raw.to, "destination");
+  if (origin === destination) {
+    throw new CliError("Origin and destination must be different airports", ExitCode.InvalidInput);
+  }
+
+  const departureDate = normalizeDate(raw.date, "departure");
+  const tokens = raw.tokens.filter((token) => token.length > 0);
+  if (tokens.length === 0) {
+    throw new CliError("Missing required flag: --token", ExitCode.InvalidInput);
+  }
+
+  return {
+    origin,
+    destination,
+    departureDate,
+    tokens,
+  };
+}
+
 function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] } {
   const args = [...argv];
   if (args[0] === "hotels") {
@@ -293,6 +398,11 @@ function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] }
 
   if (args[0] === "flights") {
     args.shift();
+    if (args[0] === "booking") {
+      args.shift();
+      return { mode: "flight-booking", args };
+    }
+
     if (args[0] === "one-way") {
       args.shift();
     }

package/src/serpapi.ts

@@ -1,5 +1,14 @@
 import { CliError } from "./errors";
-import { ExitCode, FlightOption, FlightQuery, HotelOption, HotelQuery } from "./types";
+import {
+  ExitCode,
+  FlightBookingQuery,
+  FlightBookingResult,
+  FlightOption,
+  FlightQuery,
+  FlightSearchResult,
+  HotelOption,
+  HotelQuery,
+} from "./types";
 
 interface SerpApiAirport {
   time?: string;
@@ -16,14 +25,38 @@ interface SerpApiItinerary {
   price?: number;
   total_duration?: number;
   flights?: SerpApiSegment[];
+  booking_token?: string;
 }
 
 interface SerpApiFlightsResponse {
   error?: string;
+  search_metadata?: {
+    google_flights_url?: string;
+  };
   best_flights?: SerpApiItinerary[];
   other_flights?: SerpApiItinerary[];
 }
 
+interface SerpApiBookingRequest {
+  url?: string;
+  post_data?: string;
+}
+
+interface SerpApiBookingNode {
+  source?: string;
+  price?: number;
+  booking_request?: SerpApiBookingRequest;
+  [key: string]: unknown;
+}
+
+interface SerpApiBookingOptionsResponse {
+  error?: string;
+  search_metadata?: {
+    google_flights_url?: string;
+  };
+  [key: string]: unknown;
+}
+
 interface SerpApiPrice {
   lowest?: number;
   extracted_lowest?: number;
@@ -51,7 +84,7 @@ export async function searchFlights(
   query: FlightQuery,
   apiKey: string,
   fetchImpl: typeof fetch = fetch,
-): Promise<FlightOption[]> {
+): Promise<FlightSearchResult> {
   const payload = await fetchSerpApiJson<SerpApiFlightsResponse>(
     buildFlightRequestUrl(query, apiKey),
     fetchImpl,
@@ -74,8 +107,36 @@ export async function searchFlights(
     );
   }
 
-  flights.sort((a, b) => a.price - b.price);
-  return flights;
+  flights.sort(compareByDepartureTime);
+  return {
+    options: flights,
+    googleFlightsUrl: payload.search_metadata?.google_flights_url,
+  };
+}
+
+export async function searchFlightBookingOptions(
+  query: FlightBookingQuery,
+  apiKey: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<FlightBookingResult[]> {
+  const requests = query.tokens.map(async (token) => {
+    const payload = await fetchSerpApiJson<SerpApiBookingOptionsResponse>(
+      buildFlightBookingOptionsRequestUrl(query, token, apiKey),
+      fetchImpl,
+    );
+
+    if (typeof payload.error === "string" && payload.error.trim() !== "") {
+      throw new CliError(`SerpApi error: ${payload.error}`, ExitCode.ApiFailure);
+    }
+
+    return {
+      token,
+      googleFlightsUrl: payload.search_metadata?.google_flights_url,
+      links: extractBookingLinks(payload),
+    };
+  });
+
+  return Promise.all(requests);
 }
 
 export async function searchHotels(
@@ -148,7 +209,7 @@ function shapeItinerary(itinerary: SerpApiItinerary): FlightOption | null {
 
   const uniqueAirlines = [...new Set(segments.map((segment) => segment.airline).filter(Boolean))];
 
-  return {
+  const option: FlightOption = {
     price: itinerary.price as number,
     airline: uniqueAirlines.length > 0 ? uniqueAirlines.join(", ") : "Unknown",
     departureTime,
@@ -156,6 +217,12 @@ function shapeItinerary(itinerary: SerpApiItinerary): FlightOption | null {
     durationMinutes: inferDurationMinutes(itinerary, segments),
     stops: Math.max(0, segments.length - 1),
   };
+
+  if (typeof itinerary.booking_token === "string" && itinerary.booking_token.trim() !== "") {
+    option.bookingToken = itinerary.booking_token.trim();
+  }
+
+  return option;
 }
 
 function shapeHotelProperty(property: SerpApiHotelProperty): HotelOption | null {
@@ -269,6 +336,25 @@ function buildHotelRequestUrl(query: HotelQuery, apiKey: string): string {
   return url.toString();
 }
 
+function buildFlightBookingOptionsRequestUrl(
+  query: FlightBookingQuery,
+  token: string,
+  apiKey: string,
+): string {
+  const url = new URL("https://serpapi.com/search.json");
+
+  url.searchParams.set("engine", "google_flights");
+  url.searchParams.set("type", "2");
+  url.searchParams.set("departure_id", query.origin);
+  url.searchParams.set("arrival_id", query.destination);
+  url.searchParams.set("outbound_date", query.departureDate);
+  url.searchParams.set("booking_token", token);
+  url.searchParams.set("currency", "USD");
+  url.searchParams.set("api_key", apiKey);
+
+  return url.toString();
+}
+
 function toSerpApiStopsFilter(maxStops: number): string {
   if (maxStops === 0) {
     return "1";
@@ -315,7 +401,20 @@ async function fetchSerpApiJson<T>(
   }
 
   if (!response.ok) {
-    throw new CliError(`SerpApi request failed with status ${response.status}`, ExitCode.ApiFailure);
+    let details = "";
+    try {
+      const raw = await response.text();
+      if (raw.trim().length > 0) {
+        details = `: ${raw.trim()}`;
+      }
+    } catch {
+      details = "";
+    }
+
+    throw new CliError(
+      `SerpApi request failed with status ${response.status}${details}`,
+      ExitCode.ApiFailure,
+    );
   }
 
   try {
@@ -345,3 +444,89 @@ function extractMinutes(value: string): number | null {
 
   return Number(match[1]) * 60 + Number(match[2]);
 }
+
+function compareByDepartureTime(a: FlightOption, b: FlightOption): number {
+  const aKey = departureSortKey(a.departureTime);
+  const bKey = departureSortKey(b.departureTime);
+
+  if (aKey !== bKey) {
+    return aKey - bKey;
+  }
+
+  return a.price - b.price;
+}
+
+function departureSortKey(value: string): number {
+  const match = /^(\d{4})-(\d{2})-(\d{2})\s+([01]\d|2[0-3]):([0-5]\d)$/.exec(value.trim());
+  if (!match) {
+    return Number.MAX_SAFE_INTEGER;
+  }
+
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const hour = Number(match[4]);
+  const minute = Number(match[5]);
+
+  return (
+    year * 100000000 +
+    month * 1000000 +
+    day * 10000 +
+    hour * 100 +
+    minute
+  );
+}
+
+function extractBookingLinks(payload: SerpApiBookingOptionsResponse): Array<{
+  url: string;
+  source?: string;
+  price?: number;
+}> {
+  const links: Array<{ url: string; source?: string; price?: number }> = [];
+  collectBookingLinks(payload as SerpApiBookingNode, links);
+
+  const deduped = new Map<string, { url: string; source?: string; price?: number }>();
+  for (const link of links) {
+    if (!deduped.has(link.url)) {
+      deduped.set(link.url, link);
+    }
+  }
+
+  return [...deduped.values()];
+}
+
+function collectBookingLinks(
+  node: unknown,
+  links: Array<{ url: string; source?: string; price?: number }>,
+): void {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectBookingLinks(item, links);
+    }
+    return;
+  }
+
+  if (!node || typeof node !== "object") {
+    return;
+  }
+
+  const value = node as SerpApiBookingNode;
+  const bookingUrl = value.booking_request?.url;
+  const bookingPostData = value.booking_request?.post_data;
+  if (typeof bookingUrl === "string" && bookingUrl.trim() !== "") {
+    const finalUrl =
+      typeof bookingPostData === "string" && bookingPostData.trim() !== ""
+        ? `${bookingUrl}${bookingUrl.includes("?") ? "&" : "?"}${bookingPostData}`
+        : bookingUrl;
+
+    links.push({
+      url: finalUrl,
+      source: typeof value.source === "string" ? value.source : undefined,
+      price: Number.isFinite(value.price) ? value.price : undefined,
+    });
+  }
+
+  for (const child of Object.values(value)) {
+    collectBookingLinks(child, links);
+  }
+}

package/src/types.ts

@@ -49,7 +49,25 @@ export interface ParsedArgsHotels {
   query: HotelQuery;
 }
 
-export type ParsedArgs = ParsedArgsHelp | ParsedArgsFlights | ParsedArgsHotels;
+export interface FlightBookingQuery {
+  origin: string;
+  destination: string;
+  departureDate: string;
+  tokens: string[];
+}
+
+export interface ParsedArgsFlightBooking {
+  help: false;
+  mode: "flight-booking";
+  outputJson: boolean;
+  query: FlightBookingQuery;
+}
+
+export type ParsedArgs =
+  | ParsedArgsHelp
+  | ParsedArgsFlights
+  | ParsedArgsHotels
+  | ParsedArgsFlightBooking;
 
 export interface FlightOption {
   price: number;
@@ -58,6 +76,7 @@ export interface FlightOption {
   arrivalTime: string;
   durationMinutes: number;
   stops: number;
+  bookingToken?: string;
 }
 
 export interface HotelOption {
@@ -69,3 +88,20 @@ export interface HotelOption {
   location: string;
   link?: string;
 }
+
+export interface FlightSearchResult {
+  options: FlightOption[];
+  googleFlightsUrl?: string;
+}
+
+export interface FlightBookingLink {
+  url: string;
+  source?: string;
+  price?: number;
+}
+
+export interface FlightBookingResult {
+  token: string;
+  googleFlightsUrl?: string;
+  links: FlightBookingLink[];
+}