@tks/wayfinder 0.2.3 → 0.3.1

package/README.md

@@ -99,3 +99,33 @@ Structured hotel output for scripting:
 ```bash
 wayfinder hotels --where "Paris" --check-in 2026-04-10 --check-out 2026-04-12 --json | jq '.results[] | {name,nightlyPrice,rating}'
 ```
+
+Search nearby restaurants from a location:
+
+```bash
+wayfinder places --near "Shinjuku, Tokyo"
+```
+
+Use a specific location name for better relevance:
+
+```bash
+wayfinder places --near "Domino Park, Brooklyn, NY"
+```
+
+Search nearby coffee spots:
+
+```bash
+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
+wayfinder places --near "Shinjuku, Tokyo" --type coffee --json | jq '.results[] | {name,rating,reviews,googleMapsUrl}'
+```

package/package.json

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

package/src/cli.ts

@@ -1,8 +1,8 @@
 import { getConfigPath, readConfigApiKey, resolveApiKey, writeConfigApiKey } from "./config";
 import { CliError } from "./errors";
-import { renderFlightTable, renderHotelTable } from "./format";
+import { renderFlightTable, renderHotelTable, renderPlaceTable } from "./format";
 import { parseCliArgs } from "./parse";
-import { searchFlightBookingOptions, searchFlights, searchHotels } from "./serpapi";
+import { searchFlightBookingOptions, searchFlights, searchHotels, searchPlaces } from "./serpapi";
 import { ExitCode } from "./types";
 import { createInterface } from "node:readline/promises";
 import { stdin as defaultStdin, stdout as defaultStdout } from "node:process";
@@ -22,7 +22,7 @@ interface RunOptions {
   promptImpl?: (prompt: string) => Promise<string>;
 }
 
-const HELP_TEXT = `wayfinder v0.2.1 travel search
+const HELP_TEXT = `wayfinder v0.3.1 travel search
 
 Usage:
   wayfinder setup [--reset]
@@ -30,6 +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] [--range walk] [--limit N] [--json]
 
 Setup:
   Runs interactive key setup and stores your SerpApi key in local config.
@@ -65,6 +66,15 @@ Hotels optional filters:
   --max-price <USD>         Max nightly rate in USD
   --rating <3.5|4|4.5|5>    Minimum guest rating
 
+Places required:
+  --near <QUERY>            Specific location query, example "Domino Park, Brooklyn, NY"
+                            Broad names can return mixed-city results
+
+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:
   --json                    Print structured JSON output`;
 
@@ -181,7 +191,7 @@ export async function runWayfinder(
       } else {
         output.stdout(renderFlightBookingText(flightLinks));
       }
-    } else {
+    } else if (parsed.mode === "hotels") {
       const hotels = await searchHotels(parsed.query, apiKey, options.fetchImpl ?? fetch);
 
       if (hotels.length === 0) {
@@ -202,6 +212,27 @@ export async function runWayfinder(
       } else {
         output.stdout(renderHotelTable(hotels));
       }
+    } else {
+      const places = await searchPlaces(parsed.query, apiKey, options.fetchImpl ?? fetch);
+
+      if (places.length === 0) {
+        throw new CliError("No places found for the selected query", ExitCode.NoResults);
+      }
+
+      if (parsed.outputJson) {
+        output.stdout(
+          JSON.stringify(
+            {
+              query: parsed.query,
+              results: places,
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        output.stdout(renderPlaceTable(places));
+      }
     }
 
     return ExitCode.Success;

package/src/format.ts

@@ -1,4 +1,4 @@
-import { FlightOption, HotelOption } from "./types";
+import { FlightOption, HotelOption, PlaceOption } from "./types";
 
 const currencyFormatter = new Intl.NumberFormat("en-US", {
   style: "currency",
@@ -142,6 +142,74 @@ export function renderHotelTable(options: HotelOption[]): string {
   return lines.join("\n");
 }
 
+export function renderPlaceTable(options: PlaceOption[]): string {
+  const rows = options.map((option) => ({
+    name: option.name,
+    type: option.category,
+    rating: typeof option.rating === "number" ? option.rating.toFixed(1) : "n/a",
+    reviews: typeof option.reviews === "number" ? String(option.reviews) : "n/a",
+    distance: formatDistance(option.distanceMeters),
+    address: option.address ?? "n/a",
+  }));
+
+  const headers = {
+    name: "NAME",
+    type: "TYPE",
+    rating: "RATING",
+    reviews: "REVIEWS",
+    distance: "DISTANCE",
+    address: "ADDRESS",
+  };
+
+  const widths = {
+    name: maxWidth(rows, "name", headers.name),
+    type: maxWidth(rows, "type", headers.type),
+    rating: maxWidth(rows, "rating", headers.rating),
+    reviews: maxWidth(rows, "reviews", headers.reviews),
+    distance: maxWidth(rows, "distance", headers.distance),
+    address: maxWidth(rows, "address", headers.address),
+  };
+
+  const lines: string[] = [];
+
+  lines.push(
+    [
+      headers.name.padEnd(widths.name),
+      headers.type.padEnd(widths.type),
+      headers.rating.padEnd(widths.rating),
+      headers.reviews.padEnd(widths.reviews),
+      headers.distance.padEnd(widths.distance),
+      headers.address.padEnd(widths.address),
+    ].join("  "),
+  );
+
+  lines.push(
+    [
+      "-".repeat(widths.name),
+      "-".repeat(widths.type),
+      "-".repeat(widths.rating),
+      "-".repeat(widths.reviews),
+      "-".repeat(widths.distance),
+      "-".repeat(widths.address),
+    ].join("  "),
+  );
+
+  for (const row of rows) {
+    lines.push(
+      [
+        row.name.padEnd(widths.name),
+        row.type.padEnd(widths.type),
+        row.rating.padEnd(widths.rating),
+        row.reviews.padEnd(widths.reviews),
+        row.distance.padEnd(widths.distance),
+        row.address.padEnd(widths.address),
+      ].join("  "),
+    );
+  }
+
+  return lines.join("\n");
+}
+
 function maxWidth(rows: Array<Record<string, string>>, key: string, header: string): number {
   return rows.reduce((width, row) => Math.max(width, row[key].length), header.length);
 }
@@ -164,3 +232,16 @@ function formatDuration(totalMinutes: number): string {
 
   return `${hours}h ${minutes}m`;
 }
+
+function formatDistance(distanceMeters?: number): string {
+  if (!Number.isFinite(distanceMeters)) {
+    return "n/a";
+  }
+
+  if ((distanceMeters as number) < 1000) {
+    return `${Math.round(distanceMeters as number)}m`;
+  }
+
+  const km = (distanceMeters as number) / 1000;
+  return `${km.toFixed(1)}km`;
+}

package/src/parse.ts

@@ -1,5 +1,14 @@
 import { CliError } from "./errors";
-import { ExitCode, FlightBookingQuery, FlightQuery, HotelQuery, ParsedArgs } from "./types";
+import {
+  ExitCode,
+  FlightBookingQuery,
+  FlightQuery,
+  HotelQuery,
+  ParsedArgs,
+  PlaceQuery,
+  PlaceRange,
+  PlaceType,
+} from "./types";
 
 interface FlightRawOptions {
   from?: string;
@@ -35,7 +44,16 @@ interface FlightBookingRawOptions {
   help: boolean;
 }
 
-type SearchMode = "flights" | "hotels" | "flight-booking" | "setup";
+interface PlaceRawOptions {
+  near?: string;
+  type?: string;
+  limit?: string;
+  range?: string;
+  outputJson: boolean;
+  help: boolean;
+}
+
+type SearchMode = "flights" | "hotels" | "places" | "flight-booking" | "setup";
 
 const HELP_FLAGS = new Set(["-h", "--help"]);
 
@@ -57,6 +75,10 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     return parseFlightBookingArgs(args);
   }
 
+  if (mode === "places") {
+    return parsePlacesArgs(args);
+  }
+
   if (mode === "setup") {
     return parseSetupArgs(args);
   }
@@ -281,6 +303,69 @@ function parseFlightBookingArgs(args: string[]): ParsedArgs {
   };
 }
 
+function parsePlacesArgs(args: string[]): ParsedArgs {
+  const raw: PlaceRawOptions = {
+    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.startsWith("--")) {
+      throw new CliError(`Unexpected argument: ${token}`, ExitCode.InvalidInput);
+    }
+
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) {
+      throw new CliError(`Missing value for ${token}`, ExitCode.InvalidInput);
+    }
+
+    switch (token) {
+      case "--near":
+        raw.near = value;
+        break;
+      case "--type":
+        raw.type = value;
+        break;
+      case "--limit":
+        raw.limit = value;
+        break;
+      case "--range":
+        raw.range = 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: "places",
+    outputJson: raw.outputJson,
+    query: buildPlaceQuery(raw),
+  };
+}
+
 function parseSetupArgs(args: string[]): ParsedArgs {
   const outputJson = args.includes("--json");
   const reset = args.includes("--reset");
@@ -409,6 +494,24 @@ function buildFlightBookingQuery(raw: FlightBookingRawOptions): FlightBookingQue
   };
 }
 
+function buildPlaceQuery(raw: PlaceRawOptions): PlaceQuery {
+  if (!raw.near) {
+    throw new CliError("Missing required flag: --near", ExitCode.InvalidInput);
+  }
+
+  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,
+  };
+}
+
 function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] } {
   const args = [...argv];
   if (args[0] === "hotels") {
@@ -435,8 +538,13 @@ function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] }
     return { mode: "setup", args };
   }
 
+  if (args[0] === "places") {
+    args.shift();
+    return { mode: "places", args };
+  }
+
   throw new CliError(
-    "Missing subcommand: use `setup`, `flights`, or `hotels`",
+    "Missing subcommand: use `setup`, `flights`, `hotels`, or `places`",
     ExitCode.InvalidInput,
   );
 }
@@ -521,6 +629,15 @@ function normalizeMaxPrice(value: string): number {
   return numeric;
 }
 
+function normalizeLimit(value: string, flagName: string): number {
+  const numeric = Number.parseInt(value, 10);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    throw new CliError(`${flagName} must be a positive integer`, ExitCode.InvalidInput);
+  }
+
+  return numeric;
+}
+
 function normalizeAdults(value: string): number {
   const numeric = Number.parseInt(value, 10);
   if (!Number.isInteger(numeric) || numeric <= 0) {
@@ -539,6 +656,24 @@ function normalizeMinRating(value: string): 3.5 | 4 | 4.5 | 5 {
   return numeric;
 }
 
+function normalizePlaceType(value: string): PlaceType {
+  const normalized = value.trim().toLowerCase();
+  if (normalized !== "restaurant" && normalized !== "coffee") {
+    throw new CliError("--type must be one of: restaurant, coffee", ExitCode.InvalidInput);
+  }
+
+  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

@@ -8,6 +8,9 @@ import {
   FlightSearchResult,
   HotelOption,
   HotelQuery,
+  PlaceOption,
+  PlaceQuery,
+  PlaceType,
 } from "./types";
 
 interface SerpApiAirport {
@@ -80,6 +83,23 @@ interface SerpApiHotelsResponse {
   properties?: SerpApiHotelProperty[];
 }
 
+interface SerpApiLocalResult {
+  title?: string;
+  rating?: number;
+  reviews?: number;
+  address?: string;
+  distance?: string;
+  open_state?: string;
+  type?: string;
+  place_id_search?: string;
+  data_id?: string;
+}
+
+interface SerpApiPlacesResponse {
+  error?: string;
+  local_results?: SerpApiLocalResult[];
+}
+
 export async function searchFlights(
   query: FlightQuery,
   apiKey: string,
@@ -158,6 +178,25 @@ export async function searchHotels(
   return hotels;
 }
 
+export async function searchPlaces(
+  query: PlaceQuery,
+  apiKey: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<PlaceOption[]> {
+  const payload = await fetchSerpApiJson<SerpApiPlacesResponse>(
+    buildPlaceRequestUrl(query, apiKey),
+    fetchImpl,
+  );
+
+  if (typeof payload.error === "string" && payload.error.trim() !== "") {
+    throw new CliError(`SerpApi error: ${payload.error}`, ExitCode.ApiFailure);
+  }
+
+  const places = shapePlaceSerpApiResponse(payload, query.type);
+  places.sort((a, b) => b.score - a.score);
+  return places.slice(0, query.limit);
+}
+
 export function shapeSerpApiResponse(payload: SerpApiFlightsResponse): FlightOption[] {
   const merged = [...(payload.best_flights ?? []), ...(payload.other_flights ?? [])];
 
@@ -172,6 +211,15 @@ export function shapeHotelSerpApiResponse(payload: SerpApiHotelsResponse): Hotel
     .filter((option): option is HotelOption => option !== null);
 }
 
+export function shapePlaceSerpApiResponse(
+  payload: SerpApiPlacesResponse,
+  category: PlaceType,
+): PlaceOption[] {
+  return (payload.local_results ?? [])
+    .map((result) => shapeLocalResult(result, category))
+    .filter((option): option is PlaceOption => option !== null);
+}
+
 export function filterByDepartureWindow(
   options: FlightOption[],
   minMinutes: number,
@@ -336,6 +384,18 @@ function buildHotelRequestUrl(query: HotelQuery, apiKey: string): string {
   return url.toString();
 }
 
+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", `${rangePrefix}${searchTerm} near ${query.near}`);
+  url.searchParams.set("api_key", apiKey);
+  return url.toString();
+}
+
 function buildFlightBookingOptionsRequestUrl(
   query: FlightBookingQuery,
   token: string,
@@ -383,6 +443,101 @@ function toSerpApiRating(rating: 3.5 | 4 | 4.5 | 5): string {
   return "10";
 }
 
+function shapeLocalResult(result: SerpApiLocalResult, category: PlaceType): PlaceOption | null {
+  if (typeof result.title !== "string" || result.title.trim() === "") {
+    return null;
+  }
+
+  const rating = Number.isFinite(result.rating) ? (result.rating as number) : undefined;
+  const reviews = Number.isFinite(result.reviews) ? (result.reviews as number) : undefined;
+  const distanceMeters = parseDistanceMeters(result.distance);
+  const link = buildGoogleMapsPlaceLink(result);
+  const googleMapsUrl = buildDirectGoogleMapsUrl(result);
+
+  return {
+    name: result.title.trim(),
+    category,
+    rating,
+    reviews,
+    address: typeof result.address === "string" ? result.address : undefined,
+    distanceMeters,
+    openState: typeof result.open_state === "string" ? result.open_state : undefined,
+    link,
+    googleMapsUrl,
+    score: computePlaceScore(rating, reviews, distanceMeters),
+  };
+}
+
+function computePlaceScore(
+  rating: number | undefined,
+  reviews: number | undefined,
+  distanceMeters: number | undefined,
+): number {
+  const ratingComponent = typeof rating === "number" ? rating / 5 : 0;
+  const reviewComponent =
+    typeof reviews === "number" && reviews > 0 ? Math.log10(reviews + 1) / 4 : 0;
+  const distanceComponent =
+    typeof distanceMeters === "number" && distanceMeters >= 0
+      ? Math.max(0, 1 - distanceMeters / 10_000)
+      : 0;
+
+  return ratingComponent * 0.6 + reviewComponent * 0.25 + distanceComponent * 0.15;
+}
+
+function parseDistanceMeters(value?: string): number | undefined {
+  if (typeof value !== "string" || value.trim() === "") {
+    return undefined;
+  }
+
+  const normalized = value.trim().toLowerCase().replace(/,/g, "");
+  const match = /^(\d+(?:\.\d+)?)\s*(m|meter|meters|km|mi)$/.exec(normalized);
+  if (!match) {
+    return undefined;
+  }
+
+  const amount = Number(match[1]);
+  const unit = match[2];
+  if (!Number.isFinite(amount)) {
+    return undefined;
+  }
+
+  if (unit === "m" || unit === "meter" || unit === "meters") {
+    return amount;
+  }
+
+  if (unit === "km") {
+    return amount * 1000;
+  }
+
+  return amount * 1609.34;
+}
+
+function buildGoogleMapsPlaceLink(result: SerpApiLocalResult): string | undefined {
+  if (typeof result.place_id_search === "string" && result.place_id_search.trim() !== "") {
+    return result.place_id_search;
+  }
+
+  return undefined;
+}
+
+function buildDirectGoogleMapsUrl(result: SerpApiLocalResult): string | undefined {
+  if (typeof result.place_id_search !== "string" || result.place_id_search.trim() === "") {
+    return undefined;
+  }
+
+  try {
+    const parsed = new URL(result.place_id_search);
+    const placeId = parsed.searchParams.get("place_id");
+    if (!placeId || placeId.trim() === "") {
+      return undefined;
+    }
+
+    return `https://www.google.com/maps/place/?q=place_id:${encodeURIComponent(placeId)}`;
+  } catch {
+    return undefined;
+  }
+}
+
 async function fetchSerpApiJson<T>(
   requestUrl: string,
   fetchImpl: typeof fetch,

package/src/types.ts

@@ -30,6 +30,16 @@ export interface HotelQuery {
   minRating?: 3.5 | 4 | 4.5 | 5;
 }
 
+export type PlaceType = "restaurant" | "coffee";
+export type PlaceRange = "walk";
+
+export interface PlaceQuery {
+  near: string;
+  type: PlaceType;
+  limit: number;
+  range?: PlaceRange;
+}
+
 export interface ParsedArgsHelp {
   help: true;
   outputJson: boolean;
@@ -70,10 +80,18 @@ export interface ParsedArgsSetup {
   reset: boolean;
 }
 
+export interface ParsedArgsPlaces {
+  help: false;
+  mode: "places";
+  outputJson: boolean;
+  query: PlaceQuery;
+}
+
 export type ParsedArgs =
   | ParsedArgsHelp
   | ParsedArgsFlights
   | ParsedArgsHotels
+  | ParsedArgsPlaces
   | ParsedArgsFlightBooking
   | ParsedArgsSetup;
 
@@ -97,6 +115,19 @@ export interface HotelOption {
   link?: string;
 }
 
+export interface PlaceOption {
+  name: string;
+  category: PlaceType;
+  rating?: number;
+  reviews?: number;
+  address?: string;
+  distanceMeters?: number;
+  openState?: string;
+  link?: string;
+  googleMapsUrl?: string;
+  score: number;
+}
+
 export interface FlightSearchResult {
   options: FlightOption[];
   googleFlightsUrl?: string;