@tks/wayfinder 0.4.0 → 0.5.0

package/README.md

@@ -94,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 --max-price 300 --rating 4
+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 --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.5.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]
@@ -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:

package/src/parse.ts

@@ -3,6 +3,7 @@ import {
   ExitCode,
   FlightBookingQuery,
   FlightsQuery,
+  HotelClass,
   HotelQuery,
   ParsedArgs,
   PlaceQuery,
@@ -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;
@@ -170,6 +176,7 @@ function parseFlightsArgs(args: string[]): ParsedArgs {
 
 function parseHotelsArgs(args: string[]): ParsedArgs {
   const raw: HotelRawOptions = {
+    freeCancellation: false,
     outputJson: false,
     help: false,
   };
@@ -187,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);
     }
@@ -209,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;
@@ -405,7 +429,7 @@ function buildFlightQuery(raw: FlightRawOptions): FlightsQuery {
 
   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";
@@ -468,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);
@@ -478,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,
   };
@@ -640,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;
 }
 
@@ -666,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

@@ -405,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));
   }

package/src/types.ts

@@ -35,11 +35,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;
 }