@tks/wayfinder 0.3.0 → 0.4.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
@@ -118,6 +124,12 @@ Search nearby coffee spots:
 wayfinder places --near "Shinjuku, Tokyo" --type coffee --limit 5
 ```
 
+Narrow results to walking-distance intent:
+
+```bash
+wayfinder places --near "Domino Park, Brooklyn, NY" --range walk
+```
+
 Structured places output for scripting:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tks/wayfinder",
-  "version": "0.3.0",
+  "version": "0.4.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.0 travel search
+const HELP_TEXT = `wayfinder v0.4.0 travel search
 
 Usage:
   wayfinder setup [--reset]
@@ -30,7 +30,7 @@ Usage:
   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]
-  wayfinder places --near "Shinjuku, Tokyo" [--type restaurant|coffee] [--limit N] [--json]
+  wayfinder places --near "Shinjuku, Tokyo" [--type restaurant|coffee] [--range walk] [--limit N] [--json]
 
 Setup:
   Runs interactive key setup and stores your SerpApi key in local config.
@@ -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
@@ -72,6 +72,7 @@ Places required:
 
 Places optional filters:
   --type <restaurant|coffee> Place type (default restaurant)
+  --range <walk>            Heuristic nearby scope; "walk" narrows to walking-distance intent
   --limit <N>               Maximum number of results (default 10)
 
 Output:
@@ -134,26 +135,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(
@@ -339,3 +364,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,17 +2,18 @@ import { CliError } from "./errors";
 import {
   ExitCode,
   FlightBookingQuery,
-  FlightQuery,
+  FlightsQuery,
   HotelQuery,
   ParsedArgs,
   PlaceQuery,
+  PlaceRange,
   PlaceType,
 } from "./types";
 
 interface FlightRawOptions {
   from?: string;
   to?: string;
-  date?: string;
+  dates: string[];
   airline?: string;
   maxStops?: string;
   maxPrice?: string;
@@ -47,6 +48,7 @@ interface PlaceRawOptions {
   near?: string;
   type?: string;
   limit?: string;
+  range?: string;
   outputJson: boolean;
   help: boolean;
 }
@@ -86,6 +88,7 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
 
 function parseFlightsArgs(args: string[]): ParsedArgs {
   const raw: FlightRawOptions = {
+    dates: [],
     excludeBasic: false,
     outputJson: false,
     help: false,
@@ -126,7 +129,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;
@@ -339,6 +342,9 @@ function parsePlacesArgs(args: string[]): ParsedArgs {
       case "--limit":
         raw.limit = value;
         break;
+      case "--range":
+        raw.range = value;
+        break;
       default:
         throw new CliError(`Unknown flag: ${token}`, ExitCode.InvalidInput);
     }
@@ -377,8 +383,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);
   }
 
@@ -389,7 +395,14 @@ 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;
@@ -419,10 +432,9 @@ function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
     }
   }
 
-  return {
+  const shared = {
     origin,
     destination,
-    departureDate,
     airlineCode,
     maxStops,
     maxPrice,
@@ -430,6 +442,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 {
@@ -497,11 +521,13 @@ function buildPlaceQuery(raw: PlaceRawOptions): PlaceQuery {
   const near = normalizeLocation(raw.near);
   const type = raw.type ? normalizePlaceType(raw.type) : "restaurant";
   const limit = raw.limit ? normalizeLimit(raw.limit, "--limit") : 10;
+  const range = raw.range ? normalizePlaceRange(raw.range) : undefined;
 
   return {
     near,
     type,
     limit,
+    range,
   };
 }
 
@@ -658,6 +684,15 @@ function normalizePlaceType(value: string): PlaceType {
   return normalized;
 }
 
+function normalizePlaceRange(value: string): PlaceRange {
+  const normalized = value.trim().toLowerCase();
+  if (normalized !== "walk") {
+    throw new CliError("--range must be: walk", ExitCode.InvalidInput);
+  }
+
+  return normalized;
+}
+
 function normalizeTime(value: string, flagName: string): number {
   const match = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(value);
   if (!match) {

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,
@@ -387,10 +422,11 @@ function buildHotelRequestUrl(query: HotelQuery, apiKey: string): string {
 function buildPlaceRequestUrl(query: PlaceQuery, apiKey: string): string {
   const url = new URL("https://serpapi.com/search.json");
   const searchTerm = query.type === "coffee" ? "coffee" : "restaurants";
+  const rangePrefix = query.range === "walk" ? "within walking distance " : "";
 
   url.searchParams.set("engine", "google_maps");
   url.searchParams.set("type", "search");
-  url.searchParams.set("q", `${searchTerm} near ${query.near}`);
+  url.searchParams.set("q", `${rangePrefix}${searchTerm} near ${query.near}`);
   url.searchParams.set("api_key", apiKey);
   return url.toString();
 }
@@ -684,3 +720,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,6 +21,20 @@ 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 interface HotelQuery {
   location: string;
   checkInDate: string;
@@ -31,11 +45,13 @@ export interface HotelQuery {
 }
 
 export type PlaceType = "restaurant" | "coffee";
+export type PlaceRange = "walk";
 
 export interface PlaceQuery {
   near: string;
   type: PlaceType;
   limit: number;
+  range?: PlaceRange;
 }
 
 export interface ParsedArgsHelp {
@@ -47,7 +63,7 @@ export interface ParsedArgsFlights {
   help: false;
   mode: "flights";
   outputJson: boolean;
-  query: FlightQuery;
+  query: FlightsQuery;
 }
 
 export interface ParsedArgsHotels {
@@ -131,6 +147,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;