@tks/wayfinder 0.4.0 → 0.6.0

package/README.md

@@ -70,6 +70,12 @@ Search with filters:
 wayfinder flights --from LAX --to SEA --date 2026-04-10 --airline AS --max-stops 0 --max-price 250 --depart-after 06:00 --depart-before 12:00
 ```
 
+Search by cabin:
+
+```bash
+wayfinder flights --from JFK --to HND --date 2026-06-15 --cabin premium-economy
+```
+
 Exclude basic economy fares:
 
 ```bash
@@ -94,10 +100,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.4.0",
+  "version": "0.6.0",
   "description": "Travel search for your terminal and your AI agents",
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -22,7 +22,7 @@ interface RunOptions {
   promptImpl?: (prompt: string) => Promise<string>;
 }
 
-const HELP_TEXT = `wayfinder v0.4.0 travel search
+const HELP_TEXT = `wayfinder travel search
 
 Usage:
   wayfinder setup [--reset]
@@ -43,6 +43,7 @@ Flights required:
 
 Flights optional filters:
   --airline <IATA>          Airline code, example UA
+  --cabin <CABIN>           Cabin: economy, premium-economy, preeco, business, first
   --max-stops <0|1|2>       Maximum number of stops
   --max-price <USD>         Max price in USD
   --depart-after <HH:MM>    Start of departure window
@@ -63,7 +64,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:

package/src/format.ts

@@ -14,6 +14,7 @@ export function renderFlightTable(options: FlightOption[]): string {
     arrive: option.arrivalTime,
     duration: formatDuration(option.durationMinutes),
     stops: String(option.stops),
+    cabin: option.cabin ?? "n/a",
   }));
 
   const headers = {
@@ -23,6 +24,7 @@ export function renderFlightTable(options: FlightOption[]): string {
     arrive: "ARRIVE",
     duration: "DURATION",
     stops: "STOPS",
+    cabin: "CABIN",
   };
 
   const widths = {
@@ -32,6 +34,7 @@ export function renderFlightTable(options: FlightOption[]): string {
     arrive: maxWidth(rows, "arrive", headers.arrive),
     duration: maxWidth(rows, "duration", headers.duration),
     stops: maxWidth(rows, "stops", headers.stops),
+    cabin: maxWidth(rows, "cabin", headers.cabin),
   };
 
   const lines: string[] = [];
@@ -44,6 +47,7 @@ export function renderFlightTable(options: FlightOption[]): string {
       headers.arrive.padEnd(widths.arrive),
       headers.duration.padEnd(widths.duration),
       headers.stops.padEnd(widths.stops),
+      headers.cabin.padEnd(widths.cabin),
     ].join("  "),
   );
 
@@ -55,6 +59,7 @@ export function renderFlightTable(options: FlightOption[]): string {
       "-".repeat(widths.arrive),
       "-".repeat(widths.duration),
       "-".repeat(widths.stops),
+      "-".repeat(widths.cabin),
     ].join("  "),
   );
 
@@ -67,6 +72,7 @@ export function renderFlightTable(options: FlightOption[]): string {
         row.arrive.padEnd(widths.arrive),
         row.duration.padEnd(widths.duration),
         row.stops.padEnd(widths.stops),
+        row.cabin.padEnd(widths.cabin),
       ].join("  "),
     );
   }

package/src/parse.ts

@@ -2,7 +2,9 @@ import { CliError } from "./errors";
 import {
   ExitCode,
   FlightBookingQuery,
+  CabinClass,
   FlightsQuery,
+  HotelClass,
   HotelQuery,
   ParsedArgs,
   PlaceQuery,
@@ -15,6 +17,7 @@ interface FlightRawOptions {
   to?: string;
   dates: string[];
   airline?: string;
+  cabin?: string;
   maxStops?: string;
   maxPrice?: string;
   departAfter?: string;
@@ -29,6 +32,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;
@@ -134,6 +142,9 @@ function parseFlightsArgs(args: string[]): ParsedArgs {
       case "--airline":
         raw.airline = value;
         break;
+      case "--cabin":
+        raw.cabin = value;
+        break;
       case "--max-stops":
         raw.maxStops = value;
         break;
@@ -170,6 +181,7 @@ function parseFlightsArgs(args: string[]): ParsedArgs {
 
 function parseHotelsArgs(args: string[]): ParsedArgs {
   const raw: HotelRawOptions = {
+    freeCancellation: false,
     outputJson: false,
     help: false,
   };
@@ -187,6 +199,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);
     }
@@ -209,6 +226,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;
@@ -404,8 +433,13 @@ function buildFlightQuery(raw: FlightRawOptions): FlightsQuery {
   }
 
   const airlineCode = raw.airline ? normalizeAirlineCode(raw.airline) : undefined;
+  const cabin = raw.cabin ? normalizeCabin(raw.cabin) : 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;
+
+  if (raw.excludeBasic && cabin && cabin !== "economy") {
+    throw new CliError("--exclude-basic can only be used with --cabin economy", ExitCode.InvalidInput);
+  }
 
   const hasDepartAfter = typeof raw.departAfter === "string";
   const hasDepartBefore = typeof raw.departBefore === "string";
@@ -436,6 +470,7 @@ function buildFlightQuery(raw: FlightRawOptions): FlightsQuery {
     origin,
     destination,
     airlineCode,
+    cabin,
     maxStops,
     maxPrice,
     departureAfterMinutes,
@@ -468,7 +503,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);
@@ -478,11 +518,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,
   };
@@ -590,6 +650,27 @@ function normalizeAirlineCode(value: string): string {
   return upper;
 }
 
+function normalizeCabin(value: string): CabinClass {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "preeco") {
+    return "premium-economy";
+  }
+
+  if (
+    normalized === "economy" ||
+    normalized === "premium-economy" ||
+    normalized === "business" ||
+    normalized === "first"
+  ) {
+    return normalized;
+  }
+
+  throw new CliError(
+    "--cabin must be one of: economy, premium-economy, preeco, business, first",
+    ExitCode.InvalidInput,
+  );
+}
+
 function normalizeLocation(value: string): string {
   const trimmed = value.trim();
   if (trimmed.length === 0) {
@@ -640,11 +721,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;
 }
 
@@ -666,6 +753,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,5 +1,6 @@
 import { CliError } from "./errors";
 import {
+  CabinClass,
   ExitCode,
   FlightDateResult,
   FlightBookingQuery,
@@ -22,6 +23,7 @@ interface SerpApiAirport {
 
 interface SerpApiSegment {
   airline?: string;
+  travel_class?: string;
   duration?: number;
   departure_airport?: SerpApiAirport;
   arrival_airport?: SerpApiAirport;
@@ -148,6 +150,7 @@ export async function searchFlightsMultiDate(
       destination: query.destination,
       departureDate: date,
       airlineCode: query.airlineCode,
+      cabin: query.cabin,
       maxStops: query.maxStops,
       maxPrice: query.maxPrice,
       departureAfterMinutes: query.departureAfterMinutes,
@@ -291,6 +294,9 @@ function shapeItinerary(itinerary: SerpApiItinerary): FlightOption | null {
   }
 
   const uniqueAirlines = [...new Set(segments.map((segment) => segment.airline).filter(Boolean))];
+  const cabinClasses = [
+    ...new Set(segments.map((segment) => segment.travel_class).filter(isNonEmptyString)),
+  ];
 
   const option: FlightOption = {
     price: itinerary.price as number,
@@ -301,6 +307,10 @@ function shapeItinerary(itinerary: SerpApiItinerary): FlightOption | null {
     stops: Math.max(0, segments.length - 1),
   };
 
+  if (cabinClasses.length > 0) {
+    option.cabin = cabinClasses.join(", ");
+  }
+
   if (typeof itinerary.booking_token === "string" && itinerary.booking_token.trim() !== "") {
     option.bookingToken = itinerary.booking_token.trim();
   }
@@ -351,6 +361,10 @@ function inferDurationMinutes(itinerary: SerpApiItinerary, segments: SerpApiSegm
   return segmentDuration;
 }
 
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
 function buildFlightRequestUrl(query: FlightQuery, apiKey: string): string {
   const url = new URL("https://serpapi.com/search.json");
 
@@ -367,6 +381,10 @@ function buildFlightRequestUrl(query: FlightQuery, apiKey: string): string {
     url.searchParams.set("include_airlines", query.airlineCode);
   }
 
+  if (query.cabin) {
+    url.searchParams.set("travel_class", toSerpApiTravelClass(query.cabin));
+  }
+
   if (typeof query.maxStops === "number") {
     url.searchParams.set("stops", toSerpApiStopsFilter(query.maxStops));
   }
@@ -390,7 +408,7 @@ function buildFlightRequestUrl(query: FlightQuery, apiKey: string): string {
 
   if (query.excludeBasic) {
     url.searchParams.set("exclude_basic", "true");
-    url.searchParams.set("travel_class", "1");
+    url.searchParams.set("travel_class", toSerpApiTravelClass("economy"));
     url.searchParams.set("gl", "us");
   }
 
@@ -405,9 +423,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));
   }
@@ -462,6 +497,22 @@ function toSerpApiStopsFilter(maxStops: number): string {
   return "3";
 }
 
+function toSerpApiTravelClass(cabin: CabinClass): string {
+  if (cabin === "economy") {
+    return "1";
+  }
+
+  if (cabin === "premium-economy") {
+    return "2";
+  }
+
+  if (cabin === "business") {
+    return "3";
+  }
+
+  return "4";
+}
+
 function toSerpApiRating(rating: 3.5 | 4 | 4.5 | 5): string {
   if (rating === 3.5) {
     return "7";

package/src/types.ts

@@ -9,11 +9,14 @@ export const ExitCode = {
 
 export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
 
+export type CabinClass = "economy" | "premium-economy" | "business" | "first";
+
 export interface FlightQuery {
   origin: string;
   destination: string;
   departureDate: string;
   airlineCode?: string;
+  cabin?: CabinClass;
   maxStops?: number;
   maxPrice?: number;
   departureAfterMinutes?: number;
@@ -26,6 +29,7 @@ export interface FlightMultiDateQuery {
   destination: string;
   departureDates: string[];
   airlineCode?: string;
+  cabin?: CabinClass;
   maxStops?: number;
   maxPrice?: number;
   departureAfterMinutes?: number;
@@ -35,11 +39,18 @@ export interface FlightMultiDateQuery {
 
 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;
 }
@@ -116,6 +127,7 @@ export interface FlightOption {
   arrivalTime: string;
   durationMinutes: number;
   stops: number;
+  cabin?: string;
   bookingToken?: string;
 }