@tks/wayfinder 0.3.1 → 0.5.0

package/README.md

@@ -58,6 +58,12 @@ Search one way flights:
 wayfinder flights --from SFO --to JFK --date 2026-04-10
 ```
 
+Search up to 3 departure dates in one command:
+
+```bash
+wayfinder flights --from SFO --to JFK --date 2026-04-10 --date 2026-04-11 --date 2026-04-13
+```
+
 Search with filters:
 
 ```bash
@@ -88,10 +94,16 @@ Search hotels:
 wayfinder hotels --where "New York, NY" --check-in 2026-04-10 --check-out 2026-04-12
 ```
 
-Search hotels with filters:
+Search hotels with price and rating filters:
+
+```bash
+wayfinder hotels --where "Tokyo" --check-in 2026-04-10 --check-out 2026-04-13 --adults 2 --min-price 120 --max-price 300 --rating 4
+```
+
+Search family-friendly hotels with cancellation and class filters:
 
 ```bash
-wayfinder hotels --where "Tokyo" --check-in 2026-04-10 --check-out 2026-04-13 --adults 2 --max-price 300 --rating 4
+wayfinder hotels --where "Tokyo" --check-in 2026-04-10 --check-out 2026-04-13 --adults 2 --children 2 --children-ages 4,7 --free-cancellation --hotel-class 4,5
 ```
 
 Structured hotel output for scripting:

package/package.json

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

package/src/cli.ts

@@ -1,9 +1,9 @@
 import { getConfigPath, readConfigApiKey, resolveApiKey, writeConfigApiKey } from "./config";
 import { CliError } from "./errors";
-import { renderFlightTable, renderHotelTable, renderPlaceTable } from "./format";
+import { renderFlightTable, renderFlightTablesByDate, renderHotelTable, renderPlaceTable } from "./format";
 import { parseCliArgs } from "./parse";
-import { searchFlightBookingOptions, searchFlights, searchHotels, searchPlaces } from "./serpapi";
-import { ExitCode } from "./types";
+import { searchFlightBookingOptions, searchFlights, searchFlightsMultiDate, searchHotels, searchPlaces } from "./serpapi";
+import { ExitCode, FlightMultiDateQuery, FlightsQuery } from "./types";
 import { createInterface } from "node:readline/promises";
 import { stdin as defaultStdin, stdout as defaultStdout } from "node:process";
 import { existsSync, unlinkSync } from "node:fs";
@@ -22,7 +22,7 @@ interface RunOptions {
   promptImpl?: (prompt: string) => Promise<string>;
 }
 
-const HELP_TEXT = `wayfinder v0.3.1 travel search
+const HELP_TEXT = `wayfinder travel search
 
 Usage:
   wayfinder setup [--reset]
@@ -39,7 +39,7 @@ Setup:
 Flights required:
   --from <IATA>             Origin airport code
   --to <IATA>               Destination airport code
-  --date <YYYY-MM-DD>       Departure date
+  --date <YYYY-MM-DD>       Departure date (repeat up to 3 unique dates)
 
 Flights optional filters:
   --airline <IATA>          Airline code, example UA
@@ -63,7 +63,12 @@ Hotels required:
 
 Hotels optional filters:
   --adults <N>              Number of adults (default 2)
-  --max-price <USD>         Max nightly rate in USD
+  --children <N>            Number of children
+  --children-ages <A,B>     Child ages, comma-separated, example 4,7
+  --free-cancellation       Only show hotels with free cancellation
+  --hotel-class <A,B>       Hotel star class, comma-separated: 2,3,4,5
+  --min-price <USD>         Lower price bound in USD
+  --max-price <USD>         Upper price bound in USD
   --rating <3.5|4|4.5|5>    Minimum guest rating
 
 Places required:
@@ -135,26 +140,50 @@ export async function runWayfinder(
 
     const apiKey = resolveApiKey(env, homeDir);
     if (parsed.mode === "flights") {
-      const flights = await searchFlights(parsed.query, apiKey, options.fetchImpl ?? fetch);
+      if (isMultiDateFlightQuery(parsed.query)) {
+        const multiDateFlights = await searchFlightsMultiDate(parsed.query, apiKey, options.fetchImpl ?? fetch);
+        const nonEmptyDateResults = multiDateFlights.resultsByDate.filter((entry) => entry.results.length > 0);
 
-      if (flights.options.length === 0) {
-        throw new CliError("No flights found for the selected query", ExitCode.NoResults);
-      }
+        if (nonEmptyDateResults.length === 0) {
+          throw new CliError("No flights found for the selected query", ExitCode.NoResults);
+        }
 
-      if (parsed.outputJson) {
-        output.stdout(
-          JSON.stringify(
-            {
-              query: parsed.query,
-              googleFlightsUrl: flights.googleFlightsUrl,
-              results: flights.options,
-            },
-            null,
-            2,
-          ),
-        );
+        if (parsed.outputJson) {
+          output.stdout(
+            JSON.stringify(
+              {
+                query: parsed.query,
+                resultsByDate: nonEmptyDateResults,
+              },
+              null,
+              2,
+            ),
+          );
+        } else {
+          output.stdout(renderFlightTablesByDate(nonEmptyDateResults));
+        }
       } else {
-        output.stdout(renderFlightTable(flights.options));
+        const flights = await searchFlights(parsed.query, apiKey, options.fetchImpl ?? fetch);
+
+        if (flights.options.length === 0) {
+          throw new CliError("No flights found for the selected query", ExitCode.NoResults);
+        }
+
+        if (parsed.outputJson) {
+          output.stdout(
+            JSON.stringify(
+              {
+                query: parsed.query,
+                googleFlightsUrl: flights.googleFlightsUrl,
+                results: flights.options,
+              },
+              null,
+              2,
+            ),
+          );
+        } else {
+          output.stdout(renderFlightTable(flights.options));
+        }
       }
     } else if (parsed.mode === "flight-booking") {
       const bookingResults = await searchFlightBookingOptions(
@@ -340,3 +369,7 @@ async function promptWithFallback(
     rl.close();
   }
 }
+
+function isMultiDateFlightQuery(query: FlightsQuery): query is FlightMultiDateQuery {
+  return "departureDates" in query;
+}

package/src/format.ts

@@ -1,4 +1,4 @@
-import { FlightOption, HotelOption, PlaceOption } from "./types";
+import { FlightDateResult, FlightOption, HotelOption, PlaceOption } from "./types";
 
 const currencyFormatter = new Intl.NumberFormat("en-US", {
   style: "currency",
@@ -74,6 +74,19 @@ export function renderFlightTable(options: FlightOption[]): string {
   return lines.join("\n");
 }
 
+export function renderFlightTablesByDate(resultsByDate: FlightDateResult[]): string {
+  const sections = resultsByDate.map((result) => {
+    const lines = [`DATE: ${result.date}`];
+    if (typeof result.googleFlightsUrl === "string") {
+      lines.push(`GOOGLE FLIGHTS: ${result.googleFlightsUrl}`);
+    }
+    lines.push(renderFlightTable(result.results));
+    return lines.join("\n");
+  });
+
+  return sections.join("\n\n");
+}
+
 export function renderHotelTable(options: HotelOption[]): string {
   const rows = options.map((option) => ({
     nightly: currencyFormatter.format(option.nightlyPrice),

package/src/parse.ts

@@ -2,7 +2,8 @@ import { CliError } from "./errors";
 import {
   ExitCode,
   FlightBookingQuery,
-  FlightQuery,
+  FlightsQuery,
+  HotelClass,
   HotelQuery,
   ParsedArgs,
   PlaceQuery,
@@ -13,7 +14,7 @@ import {
 interface FlightRawOptions {
   from?: string;
   to?: string;
-  date?: string;
+  dates: string[];
   airline?: string;
   maxStops?: string;
   maxPrice?: string;
@@ -29,6 +30,11 @@ interface HotelRawOptions {
   checkIn?: string;
   checkOut?: string;
   adults?: string;
+  children?: string;
+  childrenAges?: string;
+  freeCancellation: boolean;
+  hotelClass?: string;
+  minPrice?: string;
   maxPrice?: string;
   rating?: string;
   outputJson: boolean;
@@ -88,6 +94,7 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
 
 function parseFlightsArgs(args: string[]): ParsedArgs {
   const raw: FlightRawOptions = {
+    dates: [],
     excludeBasic: false,
     outputJson: false,
     help: false,
@@ -128,7 +135,7 @@ function parseFlightsArgs(args: string[]): ParsedArgs {
         raw.to = value;
         break;
       case "--date":
-        raw.date = value;
+        raw.dates.push(value);
         break;
       case "--airline":
         raw.airline = value;
@@ -169,6 +176,7 @@ function parseFlightsArgs(args: string[]): ParsedArgs {
 
 function parseHotelsArgs(args: string[]): ParsedArgs {
   const raw: HotelRawOptions = {
+    freeCancellation: false,
     outputJson: false,
     help: false,
   };
@@ -186,6 +194,11 @@ function parseHotelsArgs(args: string[]): ParsedArgs {
       continue;
     }
 
+    if (token === "--free-cancellation") {
+      raw.freeCancellation = true;
+      continue;
+    }
+
     if (!token.startsWith("--")) {
       throw new CliError(`Unexpected argument: ${token}`, ExitCode.InvalidInput);
     }
@@ -208,6 +221,18 @@ function parseHotelsArgs(args: string[]): ParsedArgs {
       case "--adults":
         raw.adults = value;
         break;
+      case "--children":
+        raw.children = value;
+        break;
+      case "--children-ages":
+        raw.childrenAges = value;
+        break;
+      case "--hotel-class":
+        raw.hotelClass = value;
+        break;
+      case "--min-price":
+        raw.minPrice = value;
+        break;
       case "--max-price":
         raw.maxPrice = value;
         break;
@@ -382,8 +407,8 @@ function parseSetupArgs(args: string[]): ParsedArgs {
   };
 }
 
-function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
-  if (!raw.from || !raw.to || !raw.date) {
+function buildFlightQuery(raw: FlightRawOptions): FlightsQuery {
+  if (!raw.from || !raw.to || raw.dates.length === 0) {
     throw new CliError("Missing required flags: --from, --to, --date", ExitCode.InvalidInput);
   }
 
@@ -394,10 +419,17 @@ function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
     throw new CliError("Origin and destination must be different airports", ExitCode.InvalidInput);
   }
 
-  const departureDate = normalizeDate(raw.date, "departure");
+  const departureDates = [...new Set(raw.dates.map((date) => normalizeDate(date, "departure")))];
+  if (departureDates.length > 3) {
+    throw new CliError(
+      "Too many dates: maximum 3 unique --date values per search",
+      ExitCode.InvalidInput,
+    );
+  }
+
   const airlineCode = raw.airline ? normalizeAirlineCode(raw.airline) : undefined;
   const maxStops = raw.maxStops ? normalizeMaxStops(raw.maxStops) : undefined;
-  const maxPrice = raw.maxPrice ? normalizeMaxPrice(raw.maxPrice) : undefined;
+  const maxPrice = raw.maxPrice ? normalizePrice(raw.maxPrice, "--max-price") : undefined;
 
   const hasDepartAfter = typeof raw.departAfter === "string";
   const hasDepartBefore = typeof raw.departBefore === "string";
@@ -424,10 +456,9 @@ function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
     }
   }
 
-  return {
+  const shared = {
     origin,
     destination,
-    departureDate,
     airlineCode,
     maxStops,
     maxPrice,
@@ -435,6 +466,18 @@ function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
     departureBeforeMinutes,
     excludeBasic: raw.excludeBasic || undefined,
   };
+
+  if (departureDates.length === 1) {
+    return {
+      ...shared,
+      departureDate: departureDates[0] as string,
+    };
+  }
+
+  return {
+    ...shared,
+    departureDates,
+  };
 }
 
 function buildHotelQuery(raw: HotelRawOptions): HotelQuery {
@@ -449,7 +492,12 @@ function buildHotelQuery(raw: HotelRawOptions): HotelQuery {
   const checkInDate = normalizeDate(raw.checkIn, "check-in");
   const checkOutDate = normalizeDate(raw.checkOut, "check-out");
   const adults = raw.adults ? normalizeAdults(raw.adults) : 2;
-  const maxPrice = raw.maxPrice ? normalizeMaxPrice(raw.maxPrice) : undefined;
+  const children = raw.children ? normalizeChildren(raw.children) : 0;
+  const childrenAges = raw.childrenAges ? normalizeChildrenAges(raw.childrenAges) : undefined;
+  const freeCancellation = raw.freeCancellation || undefined;
+  const hotelClasses = raw.hotelClass ? normalizeHotelClasses(raw.hotelClass) : undefined;
+  const minPrice = raw.minPrice ? normalizePrice(raw.minPrice, "--min-price") : undefined;
+  const maxPrice = raw.maxPrice ? normalizePrice(raw.maxPrice, "--max-price") : undefined;
   const minRating = raw.rating ? normalizeMinRating(raw.rating) : undefined;
 
   const checkIn = parseDateOnly(checkInDate);
@@ -459,11 +507,31 @@ function buildHotelQuery(raw: HotelRawOptions): HotelQuery {
     throw new CliError("Check-out date must be after check-in date", ExitCode.InvalidInput);
   }
 
+  if (childrenAges && children === 0) {
+    throw new CliError("--children-ages requires --children", ExitCode.InvalidInput);
+  }
+
+  if (childrenAges && childrenAges.length !== children) {
+    throw new CliError(
+      "--children-ages count must match --children",
+      ExitCode.InvalidInput,
+    );
+  }
+
+  if (typeof minPrice === "number" && typeof maxPrice === "number" && minPrice > maxPrice) {
+    throw new CliError("--min-price cannot be greater than --max-price", ExitCode.InvalidInput);
+  }
+
   return {
     location,
     checkInDate,
     checkOutDate,
     adults,
+    children,
+    childrenAges,
+    freeCancellation,
+    hotelClasses,
+    minPrice,
     maxPrice,
     minRating,
   };
@@ -621,11 +689,17 @@ function normalizeMaxStops(value: string): number {
   return numeric;
 }
 
-function normalizeMaxPrice(value: string): number {
-  const numeric = Number.parseInt(value, 10);
+function normalizePrice(value: string, flagName: "--min-price" | "--max-price"): number {
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new CliError(`${flagName} must be a positive integer`, ExitCode.InvalidInput);
+  }
+
+  const numeric = Number.parseInt(trimmed, 10);
   if (!Number.isInteger(numeric) || numeric <= 0) {
-    throw new CliError("--max-price must be a positive integer", ExitCode.InvalidInput);
+    throw new CliError(`${flagName} must be a positive integer`, ExitCode.InvalidInput);
   }
+
   return numeric;
 }
 
@@ -647,6 +721,62 @@ function normalizeAdults(value: string): number {
   return numeric;
 }
 
+function normalizeChildren(value: string): number {
+  if (!/^\d+$/.test(value.trim())) {
+    throw new CliError("--children must be a positive integer", ExitCode.InvalidInput);
+  }
+
+  const numeric = Number.parseInt(value, 10);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    throw new CliError("--children must be a positive integer", ExitCode.InvalidInput);
+  }
+
+  return numeric;
+}
+
+function normalizeChildrenAges(value: string): number[] {
+  const parts = value.split(",");
+  if (parts.length === 0) {
+    throw new CliError(
+      "--children-ages must be a comma-separated list of ages 1 through 17",
+      ExitCode.InvalidInput,
+    );
+  }
+
+  return parts.map((part) => {
+    const trimmed = part.trim();
+    if (!/^\d+$/.test(trimmed)) {
+      throw new CliError(
+        "--children-ages must be a comma-separated list of ages 1 through 17",
+        ExitCode.InvalidInput,
+      );
+    }
+
+    const age = Number.parseInt(trimmed, 10);
+    if (age < 1 || age > 17) {
+      throw new CliError("--children-ages ages must be between 1 and 17", ExitCode.InvalidInput);
+    }
+
+    return age;
+  });
+}
+
+function normalizeHotelClasses(value: string): HotelClass[] {
+  const hotelClasses = value.split(",").map((part) => {
+    const trimmed = part.trim();
+    if (trimmed !== "2" && trimmed !== "3" && trimmed !== "4" && trimmed !== "5") {
+      throw new CliError(
+        "--hotel-class must be a comma-separated list of: 2, 3, 4, 5",
+        ExitCode.InvalidInput,
+      );
+    }
+
+    return Number.parseInt(trimmed, 10) as HotelClass;
+  });
+
+  return [...new Set(hotelClasses)].sort((a, b) => a - b);
+}
+
 function normalizeMinRating(value: string): 3.5 | 4 | 4.5 | 5 {
   const numeric = Number.parseFloat(value);
   if (numeric !== 3.5 && numeric !== 4 && numeric !== 4.5 && numeric !== 5) {

package/src/serpapi.ts

@@ -1,8 +1,11 @@
 import { CliError } from "./errors";
 import {
   ExitCode,
+  FlightDateResult,
   FlightBookingQuery,
   FlightBookingResult,
+  FlightMultiDateQuery,
+  FlightMultiDateSearchResult,
   FlightOption,
   FlightQuery,
   FlightSearchResult,
@@ -134,6 +137,38 @@ export async function searchFlights(
   };
 }
 
+export async function searchFlightsMultiDate(
+  query: FlightMultiDateQuery,
+  apiKey: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<FlightMultiDateSearchResult> {
+  const resultsByDate = await mapWithConcurrency(query.departureDates, 2, async (date) => {
+    const singleDateQuery: FlightQuery = {
+      origin: query.origin,
+      destination: query.destination,
+      departureDate: date,
+      airlineCode: query.airlineCode,
+      maxStops: query.maxStops,
+      maxPrice: query.maxPrice,
+      departureAfterMinutes: query.departureAfterMinutes,
+      departureBeforeMinutes: query.departureBeforeMinutes,
+      excludeBasic: query.excludeBasic,
+    };
+
+    const result = await searchFlights(singleDateQuery, apiKey, fetchImpl);
+    const grouped: FlightDateResult = {
+      date,
+      results: result.options,
+      googleFlightsUrl: result.googleFlightsUrl,
+    };
+    return grouped;
+  });
+
+  return {
+    resultsByDate,
+  };
+}
+
 export async function searchFlightBookingOptions(
   query: FlightBookingQuery,
   apiKey: string,
@@ -370,9 +405,26 @@ function buildHotelRequestUrl(query: HotelQuery, apiKey: string): string {
   url.searchParams.set("check_in_date", query.checkInDate);
   url.searchParams.set("check_out_date", query.checkOutDate);
   url.searchParams.set("adults", String(query.adults));
+  url.searchParams.set("children", String(query.children));
   url.searchParams.set("currency", "USD");
   url.searchParams.set("api_key", apiKey);
 
+  if (query.childrenAges && query.childrenAges.length > 0) {
+    url.searchParams.set("children_ages", query.childrenAges.join(","));
+  }
+
+  if (query.freeCancellation) {
+    url.searchParams.set("free_cancellation", "true");
+  }
+
+  if (query.hotelClasses && query.hotelClasses.length > 0) {
+    url.searchParams.set("hotel_class", query.hotelClasses.join(","));
+  }
+
+  if (typeof query.minPrice === "number") {
+    url.searchParams.set("min_price", String(query.minPrice));
+  }
+
   if (typeof query.maxPrice === "number") {
     url.searchParams.set("max_price", String(query.maxPrice));
   }
@@ -685,3 +737,33 @@ function collectBookingLinks(
     collectBookingLinks(child, links);
   }
 }
+
+async function mapWithConcurrency<TInput, TOutput>(
+  items: TInput[],
+  concurrency: number,
+  worker: (item: TInput, index: number) => Promise<TOutput>,
+): Promise<TOutput[]> {
+  const output: TOutput[] = new Array(items.length);
+  let cursor = 0;
+
+  async function runWorker(): Promise<void> {
+    while (true) {
+      const index = cursor;
+      cursor += 1;
+
+      if (index >= items.length) {
+        return;
+      }
+
+      output[index] = await worker(items[index] as TInput, index);
+    }
+  }
+
+  const workers = Array.from(
+    { length: Math.min(Math.max(concurrency, 1), items.length) },
+    () => runWorker(),
+  );
+
+  await Promise.all(workers);
+  return output;
+}

package/src/types.ts

@@ -21,11 +21,32 @@ export interface FlightQuery {
   excludeBasic?: boolean;
 }
 
+export interface FlightMultiDateQuery {
+  origin: string;
+  destination: string;
+  departureDates: string[];
+  airlineCode?: string;
+  maxStops?: number;
+  maxPrice?: number;
+  departureAfterMinutes?: number;
+  departureBeforeMinutes?: number;
+  excludeBasic?: boolean;
+}
+
+export type FlightsQuery = FlightQuery | FlightMultiDateQuery;
+
+export type HotelClass = 2 | 3 | 4 | 5;
+
 export interface HotelQuery {
   location: string;
   checkInDate: string;
   checkOutDate: string;
   adults: number;
+  children: number;
+  childrenAges?: number[];
+  freeCancellation?: boolean;
+  hotelClasses?: HotelClass[];
+  minPrice?: number;
   maxPrice?: number;
   minRating?: 3.5 | 4 | 4.5 | 5;
 }
@@ -49,7 +70,7 @@ export interface ParsedArgsFlights {
   help: false;
   mode: "flights";
   outputJson: boolean;
-  query: FlightQuery;
+  query: FlightsQuery;
 }
 
 export interface ParsedArgsHotels {
@@ -133,6 +154,16 @@ export interface FlightSearchResult {
   googleFlightsUrl?: string;
 }
 
+export interface FlightDateResult {
+  date: string;
+  results: FlightOption[];
+  googleFlightsUrl?: string;
+}
+
+export interface FlightMultiDateSearchResult {
+  resultsByDate: FlightDateResult[];
+}
+
 export interface FlightBookingLink {
   url: string;
   source?: string;