@tks/wayfinder 0.2.0 → 0.2.3

package/README.md

@@ -2,13 +2,19 @@
 
 ## Install
 
-Requires [Bun](https://bun.sh/) runtime.
+Primary install method:
+
+```bash
+brew install tksohishi/tap/wayfinder
+```
+
+Secondary fallback method (requires [Bun](https://bun.sh/) runtime):
 
 ```bash
 bun install -g @tks/wayfinder
 ```
 
-Or install from source:
+Install from source:
 
 ```bash
 git clone https://github.com/tksohishi/wayfinder.git
@@ -19,7 +25,18 @@ bun link
 
 ## Setup
 
-Set API key by environment variable (preferred):
+First run:
+
+```bash
+wayfinder setup
+```
+
+This interactive command explains why the key is needed, where to get it, and saves it to your local config.
+SerpApi is the API provider wayfinder uses to fetch Google Flights and Google Hotels results.
+
+Advanced alternatives:
+
+Set API key by environment variable:
 
 ```bash
 export SERPAPI_API_KEY="your_key"
@@ -59,6 +76,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.3",
   "description": "Travel search for your terminal and your AI agents",
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -1,9 +1,12 @@
-import { resolveApiKey } from "./config";
+import { getConfigPath, readConfigApiKey, resolveApiKey, writeConfigApiKey } 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";
+import { createInterface } from "node:readline/promises";
+import { stdin as defaultStdin, stdout as defaultStdout } from "node:process";
+import { existsSync, unlinkSync } from "node:fs";
 
 interface Output {
   stdout: (message: string) => void;
@@ -15,15 +18,23 @@ interface RunOptions {
   homeDir?: string;
   fetchImpl?: typeof fetch;
   output?: Output;
+  isInteractive?: boolean;
+  promptImpl?: (prompt: string) => Promise<string>;
 }
 
-const HELP_TEXT = `wayfinder v0.2.0 travel search
+const HELP_TEXT = `wayfinder v0.2.1 travel search
 
 Usage:
+  wayfinder setup [--reset]
   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]
 
+Setup:
+  Runs interactive key setup and stores your SerpApi key in local config.
+  --reset                   Remove existing local config and reconfigure
+
 Flights required:
   --from <IATA>             Origin airport code
   --to <IATA>               Destination airport code
@@ -37,6 +48,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
@@ -54,12 +72,40 @@ export async function runWayfinder(
   argv: string[] = process.argv.slice(2),
   options: RunOptions = {},
 ): Promise<number> {
+  const env = options.env ?? process.env;
+  const homeDir = options.homeDir;
+  const isInteractive = options.isInteractive ?? Boolean(defaultStdin.isTTY && defaultStdout.isTTY);
   const output = options.output ?? {
     stdout: (message: string) => console.log(message),
     stderr: (message: string) => console.error(message),
   };
 
   try {
+    if (argv.length === 0) {
+      try {
+        resolveApiKey(env, homeDir);
+        output.stdout(HELP_TEXT);
+        return ExitCode.Success;
+      } catch (error) {
+        if (error instanceof CliError && error.exitCode === ExitCode.MissingApiKey) {
+          if (!isInteractive) {
+            output.stderr(error.message);
+            return error.exitCode;
+          }
+
+          return await runSetupFlow(output, homeDir, options.promptImpl, isInteractive, false);
+        }
+
+        if (error instanceof CliError) {
+          output.stderr(error.message);
+          return error.exitCode;
+        }
+
+        output.stderr("Unexpected internal error");
+        return ExitCode.InternalError;
+      }
+    }
+
     const parsed = parseCliArgs(argv);
 
     if (parsed.help) {
@@ -67,11 +113,21 @@ export async function runWayfinder(
       return ExitCode.Success;
     }
 
-    const apiKey = resolveApiKey(options.env ?? process.env, options.homeDir);
+    if (parsed.mode === "setup") {
+      return await runSetupFlow(
+        output,
+        homeDir,
+        options.promptImpl,
+        isInteractive,
+        parsed.reset,
+      );
+    }
+
+    const apiKey = resolveApiKey(env, homeDir);
     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 +136,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 +220,92 @@ 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();
+}
+
+async function runSetupFlow(
+  output: Output,
+  homeDir: string | undefined,
+  promptImpl: ((prompt: string) => Promise<string>) | undefined,
+  isInteractive: boolean,
+  forceReset: boolean,
+): Promise<number> {
+  if (!isInteractive) {
+    throw new CliError(
+      "wayfinder setup requires an interactive terminal. Use SERPAPI_API_KEY or write ~/.config/wayfinder/config.json manually.",
+      ExitCode.InvalidInput,
+    );
+  }
+
+  output.stdout("Wayfinder needs a SerpApi API key to fetch live flight and hotel data.");
+  output.stdout("SerpApi is the API provider that returns Google Flights and Google Hotels search results.");
+  output.stdout("Get your key at: https://serpapi.com/manage-api-key");
+  output.stdout("");
+
+  const configPath = getConfigPath(homeDir);
+  if (forceReset) {
+    if (existsSync(configPath)) {
+      unlinkSync(configPath);
+      output.stdout("Existing config removed due to --reset.");
+    } else {
+      output.stdout("No existing config found. Starting fresh setup.");
+    }
+  }
+
+  const existingKey = readConfigApiKey(homeDir);
+  if (existingKey && !forceReset) {
+    const overwrite = await promptWithFallback(promptImpl, "A key already exists. Overwrite? [y/N]: ");
+    if (!/^(y|yes)$/i.test(overwrite.trim())) {
+      output.stdout("Setup cancelled. Existing key kept.");
+      return ExitCode.Success;
+    }
+  }
+
+  let apiKey = "";
+  while (apiKey.length === 0) {
+    apiKey = (await promptWithFallback(promptImpl, "Enter your SerpApi API key: ")).trim();
+    if (apiKey.length === 0) {
+      output.stdout("API key cannot be empty.");
+    }
+  }
+
+  writeConfigApiKey(apiKey, homeDir);
+  output.stdout("");
+  output.stdout(`Setup complete. Saved key to ${configPath}.`);
+  output.stdout("Next step: wayfinder --help");
+  output.stdout("Quick start: wayfinder flights --from SFO --to JFK --date 2026-04-10");
+
+  return ExitCode.Success;
+}
+
+async function promptWithFallback(
+  promptImpl: ((prompt: string) => Promise<string>) | undefined,
+  message: string,
+): Promise<string> {
+  if (promptImpl) {
+    return promptImpl(message);
+  }
+
+  const rl = createInterface({
+    input: defaultStdin,
+    output: defaultStdout,
+  });
+
+  try {
+    return await rl.question(message);
+  } finally {
+    rl.close();
+  }
+}

package/src/config.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { CliError } from "./errors";
@@ -14,10 +14,18 @@ export function resolveApiKey(env: NodeJS.ProcessEnv = process.env, homeDir = os
     return envKey;
   }
 
-  const configPath = path.join(homeDir, ".config", "wayfinder", "config.json");
+  const configKey = readConfigApiKey(homeDir);
+  if (!configKey) {
+    throw missingKeyError();
+  }
+
+  return configKey;
+}
 
+export function readConfigApiKey(homeDir = os.homedir()): string | undefined {
+  const configPath = getConfigPath(homeDir);
   if (!existsSync(configPath)) {
-    throw missingKeyError();
+    return undefined;
   }
 
   let parsed: ConfigFile;
@@ -26,21 +34,49 @@ export function resolveApiKey(env: NodeJS.ProcessEnv = process.env, homeDir = os
     parsed = JSON.parse(raw) as ConfigFile;
   } catch {
     throw new CliError(
-      "Could not read ~/.config/wayfinder/config.json. Ensure it is valid JSON.",
+      "Could not read ~/.config/wayfinder/config.json. Ensure it is valid JSON or rerun `wayfinder setup`.",
       ExitCode.MissingApiKey,
     );
   }
 
-  if (typeof parsed.serpApiKey !== "string" || parsed.serpApiKey.trim() === "") {
-    throw missingKeyError();
+  if (typeof parsed.serpApiKey !== "string") {
+    return undefined;
   }
 
-  return parsed.serpApiKey.trim();
+  const key = parsed.serpApiKey.trim();
+  return key.length > 0 ? key : undefined;
+}
+
+export function writeConfigApiKey(apiKey: string, homeDir = os.homedir()): void {
+  const configPath = getConfigPath(homeDir);
+  const configDir = path.dirname(configPath);
+  mkdirSync(configDir, { recursive: true });
+  writeFileSync(
+    configPath,
+    `${JSON.stringify(
+      {
+        serpApiKey: apiKey,
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+}
+
+export function getConfigPath(homeDir = os.homedir()): string {
+  return path.join(homeDir, ".config", "wayfinder", "config.json");
 }
 
 function missingKeyError(): CliError {
   return new CliError(
-    "Missing SerpApi key. Set SERPAPI_API_KEY or add ~/.config/wayfinder/config.json with {\"serpApiKey\":\"...\"}.",
+    [
+      "Missing SerpApi API key.",
+      "Wayfinder needs a SerpApi key to fetch live flight and hotel results.",
+      "SerpApi is the API provider used for Google Flights and Google Hotels data.",
+      "Get a key at: https://serpapi.com/manage-api-key",
+      "Then run: wayfinder setup",
+    ].join("\n"),
     ExitCode.MissingApiKey,
   );
 }

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" | "setup";
 
 const HELP_FLAGS = new Set(["-h", "--help"]);
 
@@ -44,6 +53,14 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     return parseHotelsArgs(args);
   }
 
+  if (mode === "flight-booking") {
+    return parseFlightBookingArgs(args);
+  }
+
+  if (mode === "setup") {
+    return parseSetupArgs(args);
+  }
+
   return parseFlightsArgs(args);
 }
 
@@ -197,6 +214,89 @@ 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 parseSetupArgs(args: string[]): ParsedArgs {
+  const outputJson = args.includes("--json");
+  const reset = args.includes("--reset");
+  const unsupported = args.filter((token) => token !== "--json" && token !== "--reset");
+  if (unsupported.length > 0) {
+    throw new CliError(`Unknown argument for setup: ${unsupported[0]}`, ExitCode.InvalidInput);
+  }
+
+  return {
+    help: false,
+    mode: "setup",
+    outputJson,
+    reset,
+  };
+}
+
 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 +384,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 +418,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();
     }
@@ -300,8 +430,13 @@ function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] }
     return { mode: "flights", args };
   }
 
+  if (args[0] === "setup") {
+    args.shift();
+    return { mode: "setup", args };
+  }
+
   throw new CliError(
-    "Missing subcommand: use `flights` or `hotels`",
+    "Missing subcommand: use `setup`, `flights`, or `hotels`",
     ExitCode.InvalidInput,
   );
 }

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,33 @@ 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 interface ParsedArgsSetup {
+  help: false;
+  mode: "setup";
+  outputJson: boolean;
+  reset: boolean;
+}
+
+export type ParsedArgs =
+  | ParsedArgsHelp
+  | ParsedArgsFlights
+  | ParsedArgsHotels
+  | ParsedArgsFlightBooking
+  | ParsedArgsSetup;
 
 export interface FlightOption {
   price: number;
@@ -58,6 +84,7 @@ export interface FlightOption {
   arrivalTime: string;
   durationMinutes: number;
   stops: number;
+  bookingToken?: string;
 }
 
 export interface HotelOption {
@@ -69,3 +96,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[];
+}