@tks/wayfinder 0.2.1 → 0.3.0

package/README.md

@@ -2,13 +2,19 @@
 
 ## Install
 
-Requires [Bun](https://bun.sh/) runtime.
+Primary install method:
+
+```bash
+brew install tksohishi/tap/wayfinder
+```
+
+Secondary fallback method (requires [Bun](https://bun.sh/) runtime):
 
 ```bash
 bun install -g @tks/wayfinder
 ```
 
-Or install from source:
+Install from source:
 
 ```bash
 git clone https://github.com/tksohishi/wayfinder.git
@@ -19,7 +25,18 @@ bun link
 
 ## Setup
 
-Set API key by environment variable (preferred):
+First run:
+
+```bash
+wayfinder setup
+```
+
+This interactive command explains why the key is needed, where to get it, and saves it to your local config.
+SerpApi is the API provider wayfinder uses to fetch Google Flights and Google Hotels results.
+
+Advanced alternatives:
+
+Set API key by environment variable:
 
 ```bash
 export SERPAPI_API_KEY="your_key"
@@ -82,3 +99,27 @@ 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
+```
+
+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.1",
+  "version": "0.3.0",
   "description": "Travel search for your terminal and your AI agents",
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -1,9 +1,12 @@
-import { resolveApiKey } from "./config";
+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";
+import { existsSync, unlinkSync } from "node:fs";
 
 interface Output {
   stdout: (message: string) => void;
@@ -15,15 +18,23 @@ interface RunOptions {
   homeDir?: string;
   fetchImpl?: typeof fetch;
   output?: Output;
+  isInteractive?: boolean;
+  promptImpl?: (prompt: string) => Promise<string>;
 }
 
-const HELP_TEXT = `wayfinder v0.2.0 travel search
+const HELP_TEXT = `wayfinder v0.3.0 travel search
 
 Usage:
+  wayfinder setup [--reset]
   wayfinder flights --from SFO --to JFK --date 2026-03-21 [filters]
   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]
+
+Setup:
+  Runs interactive key setup and stores your SerpApi key in local config.
+  --reset                   Remove existing local config and reconfigure
 
 Flights required:
   --from <IATA>             Origin airport code
@@ -55,6 +66,14 @@ 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)
+  --limit <N>               Maximum number of results (default 10)
+
 Output:
   --json                    Print structured JSON output`;
 
@@ -62,12 +81,40 @@ export async function runWayfinder(
   argv: string[] = process.argv.slice(2),
   options: RunOptions = {},
 ): Promise<number> {
+  const env = options.env ?? process.env;
+  const homeDir = options.homeDir;
+  const isInteractive = options.isInteractive ?? Boolean(defaultStdin.isTTY && defaultStdout.isTTY);
   const output = options.output ?? {
     stdout: (message: string) => console.log(message),
     stderr: (message: string) => console.error(message),
   };
 
   try {
+    if (argv.length === 0) {
+      try {
+        resolveApiKey(env, homeDir);
+        output.stdout(HELP_TEXT);
+        return ExitCode.Success;
+      } catch (error) {
+        if (error instanceof CliError && error.exitCode === ExitCode.MissingApiKey) {
+          if (!isInteractive) {
+            output.stderr(error.message);
+            return error.exitCode;
+          }
+
+          return await runSetupFlow(output, homeDir, options.promptImpl, isInteractive, false);
+        }
+
+        if (error instanceof CliError) {
+          output.stderr(error.message);
+          return error.exitCode;
+        }
+
+        output.stderr("Unexpected internal error");
+        return ExitCode.InternalError;
+      }
+    }
+
     const parsed = parseCliArgs(argv);
 
     if (parsed.help) {
@@ -75,7 +122,17 @@ export async function runWayfinder(
       return ExitCode.Success;
     }
 
-    const apiKey = resolveApiKey(options.env ?? process.env, options.homeDir);
+    if (parsed.mode === "setup") {
+      return await runSetupFlow(
+        output,
+        homeDir,
+        options.promptImpl,
+        isInteractive,
+        parsed.reset,
+      );
+    }
+
+    const apiKey = resolveApiKey(env, homeDir);
     if (parsed.mode === "flights") {
       const flights = await searchFlights(parsed.query, apiKey, options.fetchImpl ?? fetch);
 
@@ -133,7 +190,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) {
@@ -154,6 +211,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;
@@ -186,3 +264,78 @@ function renderFlightBookingText(
 
   return lines.join("\n").trimEnd();
 }
+
+async function runSetupFlow(
+  output: Output,
+  homeDir: string | undefined,
+  promptImpl: ((prompt: string) => Promise<string>) | undefined,
+  isInteractive: boolean,
+  forceReset: boolean,
+): Promise<number> {
+  if (!isInteractive) {
+    throw new CliError(
+      "wayfinder setup requires an interactive terminal. Use SERPAPI_API_KEY or write ~/.config/wayfinder/config.json manually.",
+      ExitCode.InvalidInput,
+    );
+  }
+
+  output.stdout("Wayfinder needs a SerpApi API key to fetch live flight and hotel data.");
+  output.stdout("SerpApi is the API provider that returns Google Flights and Google Hotels search results.");
+  output.stdout("Get your key at: https://serpapi.com/manage-api-key");
+  output.stdout("");
+
+  const configPath = getConfigPath(homeDir);
+  if (forceReset) {
+    if (existsSync(configPath)) {
+      unlinkSync(configPath);
+      output.stdout("Existing config removed due to --reset.");
+    } else {
+      output.stdout("No existing config found. Starting fresh setup.");
+    }
+  }
+
+  const existingKey = readConfigApiKey(homeDir);
+  if (existingKey && !forceReset) {
+    const overwrite = await promptWithFallback(promptImpl, "A key already exists. Overwrite? [y/N]: ");
+    if (!/^(y|yes)$/i.test(overwrite.trim())) {
+      output.stdout("Setup cancelled. Existing key kept.");
+      return ExitCode.Success;
+    }
+  }
+
+  let apiKey = "";
+  while (apiKey.length === 0) {
+    apiKey = (await promptWithFallback(promptImpl, "Enter your SerpApi API key: ")).trim();
+    if (apiKey.length === 0) {
+      output.stdout("API key cannot be empty.");
+    }
+  }
+
+  writeConfigApiKey(apiKey, homeDir);
+  output.stdout("");
+  output.stdout(`Setup complete. Saved key to ${configPath}.`);
+  output.stdout("Next step: wayfinder --help");
+  output.stdout("Quick start: wayfinder flights --from SFO --to JFK --date 2026-04-10");
+
+  return ExitCode.Success;
+}
+
+async function promptWithFallback(
+  promptImpl: ((prompt: string) => Promise<string>) | undefined,
+  message: string,
+): Promise<string> {
+  if (promptImpl) {
+    return promptImpl(message);
+  }
+
+  const rl = createInterface({
+    input: defaultStdin,
+    output: defaultStdout,
+  });
+
+  try {
+    return await rl.question(message);
+  } finally {
+    rl.close();
+  }
+}

package/src/config.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { CliError } from "./errors";
@@ -14,10 +14,18 @@ export function resolveApiKey(env: NodeJS.ProcessEnv = process.env, homeDir = os
     return envKey;
   }
 
-  const configPath = path.join(homeDir, ".config", "wayfinder", "config.json");
+  const configKey = readConfigApiKey(homeDir);
+  if (!configKey) {
+    throw missingKeyError();
+  }
+
+  return configKey;
+}
 
+export function readConfigApiKey(homeDir = os.homedir()): string | undefined {
+  const configPath = getConfigPath(homeDir);
   if (!existsSync(configPath)) {
-    throw missingKeyError();
+    return undefined;
   }
 
   let parsed: ConfigFile;
@@ -26,21 +34,49 @@ export function resolveApiKey(env: NodeJS.ProcessEnv = process.env, homeDir = os
     parsed = JSON.parse(raw) as ConfigFile;
   } catch {
     throw new CliError(
-      "Could not read ~/.config/wayfinder/config.json. Ensure it is valid JSON.",
+      "Could not read ~/.config/wayfinder/config.json. Ensure it is valid JSON or rerun `wayfinder setup`.",
       ExitCode.MissingApiKey,
     );
   }
 
-  if (typeof parsed.serpApiKey !== "string" || parsed.serpApiKey.trim() === "") {
-    throw missingKeyError();
+  if (typeof parsed.serpApiKey !== "string") {
+    return undefined;
   }
 
-  return parsed.serpApiKey.trim();
+  const key = parsed.serpApiKey.trim();
+  return key.length > 0 ? key : undefined;
+}
+
+export function writeConfigApiKey(apiKey: string, homeDir = os.homedir()): void {
+  const configPath = getConfigPath(homeDir);
+  const configDir = path.dirname(configPath);
+  mkdirSync(configDir, { recursive: true });
+  writeFileSync(
+    configPath,
+    `${JSON.stringify(
+      {
+        serpApiKey: apiKey,
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+}
+
+export function getConfigPath(homeDir = os.homedir()): string {
+  return path.join(homeDir, ".config", "wayfinder", "config.json");
 }
 
 function missingKeyError(): CliError {
   return new CliError(
-    "Missing SerpApi key. Set SERPAPI_API_KEY or add ~/.config/wayfinder/config.json with {\"serpApiKey\":\"...\"}.",
+    [
+      "Missing SerpApi API key.",
+      "Wayfinder needs a SerpApi key to fetch live flight and hotel results.",
+      "SerpApi is the API provider used for Google Flights and Google Hotels data.",
+      "Get a key at: https://serpapi.com/manage-api-key",
+      "Then run: wayfinder setup",
+    ].join("\n"),
     ExitCode.MissingApiKey,
   );
 }

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,13 @@
 import { CliError } from "./errors";
-import { ExitCode, FlightBookingQuery, FlightQuery, HotelQuery, ParsedArgs } from "./types";
+import {
+  ExitCode,
+  FlightBookingQuery,
+  FlightQuery,
+  HotelQuery,
+  ParsedArgs,
+  PlaceQuery,
+  PlaceType,
+} from "./types";
 
 interface FlightRawOptions {
   from?: string;
@@ -35,7 +43,15 @@ interface FlightBookingRawOptions {
   help: boolean;
 }
 
-type SearchMode = "flights" | "hotels" | "flight-booking";
+interface PlaceRawOptions {
+  near?: string;
+  type?: string;
+  limit?: string;
+  outputJson: boolean;
+  help: boolean;
+}
+
+type SearchMode = "flights" | "hotels" | "places" | "flight-booking" | "setup";
 
 const HELP_FLAGS = new Set(["-h", "--help"]);
 
@@ -57,6 +73,14 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     return parseFlightBookingArgs(args);
   }
 
+  if (mode === "places") {
+    return parsePlacesArgs(args);
+  }
+
+  if (mode === "setup") {
+    return parseSetupArgs(args);
+  }
+
   return parseFlightsArgs(args);
 }
 
@@ -277,6 +301,82 @@ 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;
+      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");
+  const unsupported = args.filter((token) => token !== "--json" && token !== "--reset");
+  if (unsupported.length > 0) {
+    throw new CliError(`Unknown argument for setup: ${unsupported[0]}`, ExitCode.InvalidInput);
+  }
+
+  return {
+    help: false,
+    mode: "setup",
+    outputJson,
+    reset,
+  };
+}
+
 function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
   if (!raw.from || !raw.to || !raw.date) {
     throw new CliError("Missing required flags: --from, --to, --date", ExitCode.InvalidInput);
@@ -389,6 +489,22 @@ 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;
+
+  return {
+    near,
+    type,
+    limit,
+  };
+}
+
 function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] } {
   const args = [...argv];
   if (args[0] === "hotels") {
@@ -410,8 +526,18 @@ function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] }
     return { mode: "flights", args };
   }
 
+  if (args[0] === "setup") {
+    args.shift();
+    return { mode: "setup", args };
+  }
+
+  if (args[0] === "places") {
+    args.shift();
+    return { mode: "places", args };
+  }
+
   throw new CliError(
-    "Missing subcommand: use `flights` or `hotels`",
+    "Missing subcommand: use `setup`, `flights`, `hotels`, or `places`",
     ExitCode.InvalidInput,
   );
 }
@@ -496,6 +622,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) {
@@ -514,6 +649,15 @@ 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 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,17 @@ 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";
+
+  url.searchParams.set("engine", "google_maps");
+  url.searchParams.set("type", "search");
+  url.searchParams.set("q", `${searchTerm} near ${query.near}`);
+  url.searchParams.set("api_key", apiKey);
+  return url.toString();
+}
+
 function buildFlightBookingOptionsRequestUrl(
   query: FlightBookingQuery,
   token: string,
@@ -383,6 +442,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,14 @@ export interface HotelQuery {
   minRating?: 3.5 | 4 | 4.5 | 5;
 }
 
+export type PlaceType = "restaurant" | "coffee";
+
+export interface PlaceQuery {
+  near: string;
+  type: PlaceType;
+  limit: number;
+}
+
 export interface ParsedArgsHelp {
   help: true;
   outputJson: boolean;
@@ -63,11 +71,27 @@ export interface ParsedArgsFlightBooking {
   query: FlightBookingQuery;
 }
 
+export interface ParsedArgsSetup {
+  help: false;
+  mode: "setup";
+  outputJson: boolean;
+  reset: boolean;
+}
+
+export interface ParsedArgsPlaces {
+  help: false;
+  mode: "places";
+  outputJson: boolean;
+  query: PlaceQuery;
+}
+
 export type ParsedArgs =
   | ParsedArgsHelp
   | ParsedArgsFlights
   | ParsedArgsHotels
-  | ParsedArgsFlightBooking;
+  | ParsedArgsPlaces
+  | ParsedArgsFlightBooking
+  | ParsedArgsSetup;
 
 export interface FlightOption {
   price: number;
@@ -89,6 +113,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;