@tks/wayfinder 0.1.0 → 0.2.0

package/README.md

@@ -1,16 +1,22 @@
-# wayfinder
-
-CLI for one way flight search with SerpApi Google Flights.
+# 🛫 wayfinder — Travel search for your terminal and your AI agents.
 
 ## Install
 
+Requires [Bun](https://bun.sh/) runtime.
+
+```bash
+bun install -g @tks/wayfinder
+```
+
+Or install from source:
+
 ```bash
+git clone https://github.com/tksohishi/wayfinder.git
+cd wayfinder
 bun install
 bun link
 ```
 
-`bun link` makes the `wayfinder` command available in your shell.
-
 ## Setup
 
 Set API key by environment variable (preferred):
@@ -32,17 +38,41 @@ Or store it in `~/.config/wayfinder/config.json`:
 Search one way flights:
 
 ```bash
-wayfinder --from SFO --to JFK --date 2026-04-10
+wayfinder flights --from SFO --to JFK --date 2026-04-10
 ```
 
 Search with filters:
 
 ```bash
-wayfinder --from LAX --to SEA --date 2026-04-10 --airline AS --max-stops 0 --max-price 250 --depart-after 06:00 --depart-before 12:00
+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
+```
+
+Exclude basic economy fares:
+
+```bash
+wayfinder flights --from SFO --to JFK --date 2026-04-10 --exclude-basic
 ```
 
 Structured output for scripting:
 
 ```bash
-wayfinder --from SFO --to JFK --date 2026-04-10 --json | jq '.results[] | {price,airline,stops}'
+wayfinder flights --from SFO --to JFK --date 2026-04-10 --json | jq '.results[] | {price,airline,stops}'
+```
+
+Search hotels:
+
+```bash
+wayfinder hotels --where "New York, NY" --check-in 2026-04-10 --check-out 2026-04-12
+```
+
+Search hotels with filters:
+
+```bash
+wayfinder hotels --where "Tokyo" --check-in 2026-04-10 --check-out 2026-04-13 --adults 2 --max-price 300 --rating 4
+```
+
+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}'
 ```

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "@tks/wayfinder",
-  "version": "0.1.0",
+  "version": "0.2.0",
+  "description": "Travel search for your terminal and your AI agents",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tksohishi/wayfinder.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tksohishi/wayfinder/issues"
+  },
+  "homepage": "https://github.com/tksohishi/wayfinder#readme",
   "license": "MIT",
   "private": false,
   "type": "module",
   "bin": {
-    "wayfinder": "./bin/wayfinder"
+    "wayfinder": "bin/wayfinder"
   },
   "files": [
     "bin",

package/src/cli.ts

@@ -1,8 +1,8 @@
 import { resolveApiKey } from "./config";
 import { CliError } from "./errors";
-import { renderTable } from "./format";
+import { renderFlightTable, renderHotelTable } from "./format";
 import { parseCliArgs } from "./parse";
-import { searchFlights } from "./serpapi";
+import { searchFlights, searchHotels } from "./serpapi";
 import { ExitCode } from "./types";
 
 interface Output {
@@ -17,23 +17,35 @@ interface RunOptions {
   output?: Output;
 }
 
-const HELP_TEXT = `wayfinder v1 flight search
+const HELP_TEXT = `wayfinder v0.2.0 travel search
 
 Usage:
-  wayfinder --from SFO --to JFK --date 2026-03-21 [filters]
+  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 hotels --where "New York, NY" --check-in 2026-03-21 --check-out 2026-03-23 [filters]
 
-Required:
+Flights required:
   --from <IATA>             Origin airport code
   --to <IATA>               Destination airport code
   --date <YYYY-MM-DD>       Departure date
 
-Optional filters:
+Flights optional filters:
   --airline <IATA>          Airline code, example UA
   --max-stops <0|1|2>       Maximum number of stops
   --max-price <USD>         Max price in USD
   --depart-after <HH:MM>    Start of departure window
   --depart-before <HH:MM>   End of departure window
+  --exclude-basic           Exclude basic economy fares
+
+Hotels required:
+  --where <QUERY>           Destination or hotel search query
+  --check-in <YYYY-MM-DD>   Check-in date
+  --check-out <YYYY-MM-DD>  Check-out date
+
+Hotels optional filters:
+  --adults <N>              Number of adults (default 2)
+  --max-price <USD>         Max nightly rate in USD
+  --rating <3.5|4|4.5|5>    Minimum guest rating
 
 Output:
   --json                    Print structured JSON output`;
@@ -56,25 +68,48 @@ export async function runWayfinder(
     }
 
     const apiKey = resolveApiKey(options.env ?? process.env, options.homeDir);
-    const flights = await searchFlights(parsed.query!, apiKey, options.fetchImpl ?? fetch);
-
-    if (flights.length === 0) {
-      throw new CliError("No flights found for the selected query", ExitCode.NoResults);
-    }
-
-    if (parsed.outputJson) {
-      output.stdout(
-        JSON.stringify(
-          {
-            query: parsed.query,
-            results: flights,
-          },
-          null,
-          2,
-        ),
-      );
+    if (parsed.mode === "flights") {
+      const flights = await searchFlights(parsed.query, apiKey, options.fetchImpl ?? fetch);
+
+      if (flights.length === 0) {
+        throw new CliError("No flights found for the selected query", ExitCode.NoResults);
+      }
+
+      if (parsed.outputJson) {
+        output.stdout(
+          JSON.stringify(
+            {
+              query: parsed.query,
+              results: flights,
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        output.stdout(renderFlightTable(flights));
+      }
     } else {
-      output.stdout(renderTable(flights));
+      const hotels = await searchHotels(parsed.query, apiKey, options.fetchImpl ?? fetch);
+
+      if (hotels.length === 0) {
+        throw new CliError("No hotels found for the selected query", ExitCode.NoResults);
+      }
+
+      if (parsed.outputJson) {
+        output.stdout(
+          JSON.stringify(
+            {
+              query: parsed.query,
+              results: hotels,
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        output.stdout(renderHotelTable(hotels));
+      }
     }
 
     return ExitCode.Success;

package/src/format.ts

@@ -1,4 +1,4 @@
-import { FlightOption } from "./types";
+import { FlightOption, HotelOption } from "./types";
 
 const currencyFormatter = new Intl.NumberFormat("en-US", {
   style: "currency",
@@ -6,7 +6,7 @@ const currencyFormatter = new Intl.NumberFormat("en-US", {
   maximumFractionDigits: 0,
 });
 
-export function renderTable(options: FlightOption[]): string {
+export function renderFlightTable(options: FlightOption[]): string {
   const rows = options.map((option) => ({
     price: currencyFormatter.format(option.price),
     airline: option.airline,
@@ -74,11 +74,75 @@ export function renderTable(options: FlightOption[]): string {
   return lines.join("\n");
 }
 
-function maxWidth(
-  rows: Array<Record<string, string>>,
-  key: string,
-  header: string,
-): number {
+export function renderHotelTable(options: HotelOption[]): string {
+  const rows = options.map((option) => ({
+    nightly: currencyFormatter.format(option.nightlyPrice),
+    total: typeof option.totalPrice === "number" ? currencyFormatter.format(option.totalPrice) : "n/a",
+    name: option.name,
+    rating: typeof option.rating === "number" ? option.rating.toFixed(1) : "n/a",
+    reviews: typeof option.reviews === "number" ? String(option.reviews) : "n/a",
+    location: option.location,
+  }));
+
+  const headers = {
+    nightly: "PRICE/NIGHT",
+    total: "TOTAL",
+    name: "NAME",
+    rating: "RATING",
+    reviews: "REVIEWS",
+    location: "LOCATION",
+  };
+
+  const widths = {
+    nightly: maxWidth(rows, "nightly", headers.nightly),
+    total: maxWidth(rows, "total", headers.total),
+    name: maxWidth(rows, "name", headers.name),
+    rating: maxWidth(rows, "rating", headers.rating),
+    reviews: maxWidth(rows, "reviews", headers.reviews),
+    location: maxWidth(rows, "location", headers.location),
+  };
+
+  const lines: string[] = [];
+
+  lines.push(
+    [
+      headers.nightly.padEnd(widths.nightly),
+      headers.total.padEnd(widths.total),
+      headers.name.padEnd(widths.name),
+      headers.rating.padEnd(widths.rating),
+      headers.reviews.padEnd(widths.reviews),
+      headers.location.padEnd(widths.location),
+    ].join("  "),
+  );
+
+  lines.push(
+    [
+      "-".repeat(widths.nightly),
+      "-".repeat(widths.total),
+      "-".repeat(widths.name),
+      "-".repeat(widths.rating),
+      "-".repeat(widths.reviews),
+      "-".repeat(widths.location),
+    ].join("  "),
+  );
+
+  for (const row of rows) {
+    lines.push(
+      [
+        row.nightly.padEnd(widths.nightly),
+        row.total.padEnd(widths.total),
+        row.name.padEnd(widths.name),
+        row.rating.padEnd(widths.rating),
+        row.reviews.padEnd(widths.reviews),
+        row.location.padEnd(widths.location),
+      ].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);
 }
 

package/src/parse.ts

@@ -1,7 +1,7 @@
 import { CliError } from "./errors";
-import { ExitCode, ParsedArgs } from "./types";
+import { ExitCode, FlightQuery, HotelQuery, ParsedArgs } from "./types";
 
-interface RawOptions {
+interface FlightRawOptions {
   from?: string;
   to?: string;
   date?: string;
@@ -10,15 +10,46 @@ interface RawOptions {
   maxPrice?: string;
   departAfter?: string;
   departBefore?: string;
+  excludeBasic: boolean;
   outputJson: boolean;
   help: boolean;
 }
 
+interface HotelRawOptions {
+  where?: string;
+  checkIn?: string;
+  checkOut?: string;
+  adults?: string;
+  maxPrice?: string;
+  rating?: string;
+  outputJson: boolean;
+  help: boolean;
+}
+
+type SearchMode = "flights" | "hotels";
+
 const HELP_FLAGS = new Set(["-h", "--help"]);
 
 export function parseCliArgs(argv: string[]): ParsedArgs {
-  const args = stripSubcommands(argv);
-  const raw: RawOptions = {
+  if (argv.some((token) => HELP_FLAGS.has(token))) {
+    return {
+      help: true,
+      outputJson: argv.includes("--json"),
+    };
+  }
+
+  const { mode, args } = stripSubcommands(argv);
+
+  if (mode === "hotels") {
+    return parseHotelsArgs(args);
+  }
+
+  return parseFlightsArgs(args);
+}
+
+function parseFlightsArgs(args: string[]): ParsedArgs {
+  const raw: FlightRawOptions = {
+    excludeBasic: false,
     outputJson: false,
     help: false,
   };
@@ -36,6 +67,11 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
       continue;
     }
 
+    if (token === "--exclude-basic") {
+      raw.excludeBasic = true;
+      continue;
+    }
+
     if (!token.startsWith("--")) {
       throw new CliError(`Unexpected argument: ${token}`, ExitCode.InvalidInput);
     }
@@ -84,6 +120,84 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     };
   }
 
+  return {
+    help: false,
+    mode: "flights",
+    outputJson: raw.outputJson,
+    query: buildFlightQuery(raw),
+  };
+}
+
+function parseHotelsArgs(args: string[]): ParsedArgs {
+  const raw: HotelRawOptions = {
+    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 "--where":
+        raw.where = value;
+        break;
+      case "--check-in":
+        raw.checkIn = value;
+        break;
+      case "--check-out":
+        raw.checkOut = value;
+        break;
+      case "--adults":
+        raw.adults = value;
+        break;
+      case "--max-price":
+        raw.maxPrice = value;
+        break;
+      case "--rating":
+        raw.rating = 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: "hotels",
+    outputJson: raw.outputJson,
+    query: buildHotelQuery(raw),
+  };
+}
+
+function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
   if (!raw.from || !raw.to || !raw.date) {
     throw new CliError("Missing required flags: --from, --to, --date", ExitCode.InvalidInput);
   }
@@ -95,7 +209,7 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     throw new CliError("Origin and destination must be different airports", ExitCode.InvalidInput);
   }
 
-  const departureDate = normalizeDate(raw.date);
+  const departureDate = normalizeDate(raw.date, "departure");
   const airlineCode = raw.airline ? normalizeAirlineCode(raw.airline) : undefined;
   const maxStops = raw.maxStops ? normalizeMaxStops(raw.maxStops) : undefined;
   const maxPrice = raw.maxPrice ? normalizeMaxPrice(raw.maxPrice) : undefined;
@@ -126,32 +240,70 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
   }
 
   return {
-    help: false,
-    outputJson: raw.outputJson,
-    query: {
-      origin,
-      destination,
-      departureDate,
-      airlineCode,
-      maxStops,
-      maxPrice,
-      departureAfterMinutes,
-      departureBeforeMinutes,
-    },
+    origin,
+    destination,
+    departureDate,
+    airlineCode,
+    maxStops,
+    maxPrice,
+    departureAfterMinutes,
+    departureBeforeMinutes,
+    excludeBasic: raw.excludeBasic || undefined,
   };
 }
 
-function stripSubcommands(argv: string[]): string[] {
+function buildHotelQuery(raw: HotelRawOptions): HotelQuery {
+  if (!raw.where || !raw.checkIn || !raw.checkOut) {
+    throw new CliError(
+      "Missing required flags: --where, --check-in, --check-out",
+      ExitCode.InvalidInput,
+    );
+  }
+
+  const location = normalizeLocation(raw.where);
+  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 minRating = raw.rating ? normalizeMinRating(raw.rating) : undefined;
+
+  const checkIn = parseDateOnly(checkInDate);
+  const checkOut = parseDateOnly(checkOutDate);
+
+  if (checkOut <= checkIn) {
+    throw new CliError("Check-out date must be after check-in date", ExitCode.InvalidInput);
+  }
+
+  return {
+    location,
+    checkInDate,
+    checkOutDate,
+    adults,
+    maxPrice,
+    minRating,
+  };
+}
+
+function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] } {
   const args = [...argv];
+  if (args[0] === "hotels") {
+    args.shift();
+    return { mode: "hotels", args };
+  }
 
   if (args[0] === "flights") {
     args.shift();
     if (args[0] === "one-way") {
       args.shift();
     }
+
+    return { mode: "flights", args };
   }
 
-  return args;
+  throw new CliError(
+    "Missing subcommand: use `flights` or `hotels`",
+    ExitCode.InvalidInput,
+  );
 }
 
 function normalizeAirport(value: string, fieldName: "origin" | "destination"): string {
@@ -176,27 +328,43 @@ function normalizeAirlineCode(value: string): string {
   return upper;
 }
 
-function normalizeDate(value: string): string {
+function normalizeLocation(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new CliError("Location cannot be empty", ExitCode.InvalidInput);
+  }
+
+  return trimmed;
+}
+
+function normalizeDate(value: string, fieldName: "departure" | "check-in" | "check-out"): string {
   const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
   if (!match) {
     throw new CliError("Invalid date. Expected YYYY-MM-DD", ExitCode.InvalidInput);
   }
 
+  const date = parseDateOnly(value);
   const year = Number(match[1]);
   const month = Number(match[2]);
   const day = Number(match[3]);
 
-  const date = new Date(year, month - 1, day);
   if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) {
-    throw new CliError("Invalid departure date", ExitCode.InvalidInput);
+    if (fieldName === "departure") {
+      throw new CliError("Invalid departure date", ExitCode.InvalidInput);
+    }
+
+    throw new CliError(`Invalid ${fieldName} date`, ExitCode.InvalidInput);
   }
 
-  const today = new Date();
-  today.setHours(0, 0, 0, 0);
-  date.setHours(0, 0, 0, 0);
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
 
   if (date < today) {
-    throw new CliError("Departure date cannot be in the past", ExitCode.InvalidInput);
+    if (fieldName === "departure") {
+      throw new CliError("Departure date cannot be in the past", ExitCode.InvalidInput);
+    }
+
+    throw new CliError(`${capitalize(fieldName)} date cannot be in the past`, ExitCode.InvalidInput);
   }
 
   return value;
@@ -218,6 +386,24 @@ function normalizeMaxPrice(value: string): number {
   return numeric;
 }
 
+function normalizeAdults(value: string): number {
+  const numeric = Number.parseInt(value, 10);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    throw new CliError("--adults must be a positive integer", ExitCode.InvalidInput);
+  }
+
+  return numeric;
+}
+
+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) {
+    throw new CliError("--rating must be one of: 3.5, 4, 4.5, 5", ExitCode.InvalidInput);
+  }
+
+  return numeric;
+}
+
 function normalizeTime(value: string, flagName: string): number {
   const match = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(value);
   if (!match) {
@@ -226,3 +412,12 @@ function normalizeTime(value: string, flagName: string): number {
 
   return Number(match[1]) * 60 + Number(match[2]);
 }
+
+function parseDateOnly(value: string): Date {
+  const [year, month, day] = value.split("-").map((part) => Number(part));
+  return new Date(year, month - 1, day);
+}
+
+function capitalize(value: string): string {
+  return value.slice(0, 1).toUpperCase() + value.slice(1);
+}

package/src/serpapi.ts

@@ -1,5 +1,5 @@
 import { CliError } from "./errors";
-import { ExitCode, FlightOption, FlightQuery } from "./types";
+import { ExitCode, FlightOption, FlightQuery, HotelOption, HotelQuery } from "./types";
 
 interface SerpApiAirport {
   time?: string;
@@ -18,42 +18,44 @@ interface SerpApiItinerary {
   flights?: SerpApiSegment[];
 }
 
-interface SerpApiResponse {
+interface SerpApiFlightsResponse {
   error?: string;
   best_flights?: SerpApiItinerary[];
   other_flights?: SerpApiItinerary[];
 }
 
+interface SerpApiPrice {
+  lowest?: number;
+  extracted_lowest?: number;
+}
+
+interface SerpApiHotelProperty {
+  name?: string;
+  rate_per_night?: SerpApiPrice;
+  total_rate?: SerpApiPrice;
+  overall_rating?: number;
+  reviews?: number;
+  description?: string;
+  type?: string;
+  link?: string;
+  serpapi_property_details_link?: string;
+  google_property_details_link?: string;
+}
+
+interface SerpApiHotelsResponse {
+  error?: string;
+  properties?: SerpApiHotelProperty[];
+}
+
 export async function searchFlights(
   query: FlightQuery,
   apiKey: string,
   fetchImpl: typeof fetch = fetch,
 ): Promise<FlightOption[]> {
-  const requestUrl = buildRequestUrl(query, apiKey);
-
-  let response: Response;
-  try {
-    response = await fetchImpl(requestUrl, {
-      signal: AbortSignal.timeout(15_000),
-    });
-  } catch (error) {
-    if (error instanceof Error && error.name === "TimeoutError") {
-      throw new CliError("SerpApi request timed out", ExitCode.ApiFailure);
-    }
-
-    throw new CliError("Failed to reach SerpApi", ExitCode.ApiFailure);
-  }
-
-  if (!response.ok) {
-    throw new CliError(`SerpApi request failed with status ${response.status}`, ExitCode.ApiFailure);
-  }
-
-  let payload: SerpApiResponse;
-  try {
-    payload = (await response.json()) as SerpApiResponse;
-  } catch {
-    throw new CliError("SerpApi returned invalid JSON", ExitCode.ApiFailure);
-  }
+  const payload = await fetchSerpApiJson<SerpApiFlightsResponse>(
+    buildFlightRequestUrl(query, apiKey),
+    fetchImpl,
+  );
 
   if (typeof payload.error === "string" && payload.error.trim() !== "") {
     throw new CliError(`SerpApi error: ${payload.error}`, ExitCode.ApiFailure);
@@ -76,7 +78,26 @@ export async function searchFlights(
   return flights;
 }
 
-export function shapeSerpApiResponse(payload: SerpApiResponse): FlightOption[] {
+export async function searchHotels(
+  query: HotelQuery,
+  apiKey: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<HotelOption[]> {
+  const payload = await fetchSerpApiJson<SerpApiHotelsResponse>(
+    buildHotelRequestUrl(query, apiKey),
+    fetchImpl,
+  );
+
+  if (typeof payload.error === "string" && payload.error.trim() !== "") {
+    throw new CliError(`SerpApi error: ${payload.error}`, ExitCode.ApiFailure);
+  }
+
+  const hotels = shapeHotelSerpApiResponse(payload);
+  hotels.sort((a, b) => a.nightlyPrice - b.nightlyPrice);
+  return hotels;
+}
+
+export function shapeSerpApiResponse(payload: SerpApiFlightsResponse): FlightOption[] {
   const merged = [...(payload.best_flights ?? []), ...(payload.other_flights ?? [])];
 
   return merged
@@ -84,6 +105,12 @@ export function shapeSerpApiResponse(payload: SerpApiResponse): FlightOption[] {
     .filter((option): option is FlightOption => option !== null);
 }
 
+export function shapeHotelSerpApiResponse(payload: SerpApiHotelsResponse): HotelOption[] {
+  return (payload.properties ?? [])
+    .map((property) => shapeHotelProperty(property))
+    .filter((option): option is HotelOption => option !== null);
+}
+
 export function filterByDepartureWindow(
   options: FlightOption[],
   minMinutes: number,
@@ -131,6 +158,34 @@ function shapeItinerary(itinerary: SerpApiItinerary): FlightOption | null {
   };
 }
 
+function shapeHotelProperty(property: SerpApiHotelProperty): HotelOption | null {
+  if (typeof property.name !== "string" || property.name.trim() === "") {
+    return null;
+  }
+
+  const nightlyPrice = extractLowestPrice(property.rate_per_night);
+  if (typeof nightlyPrice !== "number") {
+    return null;
+  }
+
+  const totalPrice = extractLowestPrice(property.total_rate);
+  const rating = Number.isFinite(property.overall_rating) ? property.overall_rating : undefined;
+  const reviews = Number.isFinite(property.reviews) ? property.reviews : undefined;
+  const location = property.description?.trim() || property.type?.trim() || "n/a";
+  const link =
+    property.link || property.serpapi_property_details_link || property.google_property_details_link;
+
+  return {
+    name: property.name.trim(),
+    nightlyPrice,
+    totalPrice,
+    rating,
+    reviews,
+    location,
+    link,
+  };
+}
+
 function inferDurationMinutes(itinerary: SerpApiItinerary, segments: SerpApiSegment[]): number {
   if (Number.isFinite(itinerary.total_duration)) {
     return itinerary.total_duration as number;
@@ -146,7 +201,7 @@ function inferDurationMinutes(itinerary: SerpApiItinerary, segments: SerpApiSegm
   return segmentDuration;
 }
 
-function buildRequestUrl(query: FlightQuery, apiKey: string): string {
+function buildFlightRequestUrl(query: FlightQuery, apiKey: string): string {
   const url = new URL("https://serpapi.com/search.json");
 
   url.searchParams.set("engine", "google_flights");
@@ -183,6 +238,34 @@ function buildRequestUrl(query: FlightQuery, apiKey: string): string {
     url.searchParams.set("outbound_times", `${minHour},${maxHour}`);
   }
 
+  if (query.excludeBasic) {
+    url.searchParams.set("exclude_basic", "true");
+    url.searchParams.set("travel_class", "1");
+    url.searchParams.set("gl", "us");
+  }
+
+  return url.toString();
+}
+
+function buildHotelRequestUrl(query: HotelQuery, apiKey: string): string {
+  const url = new URL("https://serpapi.com/search.json");
+
+  url.searchParams.set("engine", "google_hotels");
+  url.searchParams.set("q", query.location);
+  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("currency", "USD");
+  url.searchParams.set("api_key", apiKey);
+
+  if (typeof query.maxPrice === "number") {
+    url.searchParams.set("max_price", String(query.maxPrice));
+  }
+
+  if (typeof query.minRating === "number") {
+    url.searchParams.set("rating", toSerpApiRating(query.minRating));
+  }
+
   return url.toString();
 }
 
@@ -198,6 +281,62 @@ function toSerpApiStopsFilter(maxStops: number): string {
   return "3";
 }
 
+function toSerpApiRating(rating: 3.5 | 4 | 4.5 | 5): string {
+  if (rating === 3.5) {
+    return "7";
+  }
+
+  if (rating === 4) {
+    return "8";
+  }
+
+  if (rating === 4.5) {
+    return "9";
+  }
+
+  return "10";
+}
+
+async function fetchSerpApiJson<T>(
+  requestUrl: string,
+  fetchImpl: typeof fetch,
+): Promise<T> {
+  let response: Response;
+  try {
+    response = await fetchImpl(requestUrl, {
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+      throw new CliError("SerpApi request timed out", ExitCode.ApiFailure);
+    }
+
+    throw new CliError("Failed to reach SerpApi", ExitCode.ApiFailure);
+  }
+
+  if (!response.ok) {
+    throw new CliError(`SerpApi request failed with status ${response.status}`, ExitCode.ApiFailure);
+  }
+
+  try {
+    return (await response.json()) as T;
+  } catch {
+    throw new CliError("SerpApi returned invalid JSON", ExitCode.ApiFailure);
+  }
+}
+
+function extractLowestPrice(value?: SerpApiPrice): number | undefined {
+  if (Number.isFinite(value?.lowest)) {
+    return value?.lowest;
+  }
+
+  if (Number.isFinite(value?.extracted_lowest)) {
+    return value?.extracted_lowest;
+  }
+
+  return undefined;
+}
+
 function extractMinutes(value: string): number | null {
   const match = /\b([01]?\d|2[0-3]):([0-5]\d)\b/.exec(value);
   if (!match) {

package/src/types.ts

@@ -18,14 +18,39 @@ export interface FlightQuery {
   maxPrice?: number;
   departureAfterMinutes?: number;
   departureBeforeMinutes?: number;
+  excludeBasic?: boolean;
 }
 
-export interface ParsedArgs {
-  query?: FlightQuery;
+export interface HotelQuery {
+  location: string;
+  checkInDate: string;
+  checkOutDate: string;
+  adults: number;
+  maxPrice?: number;
+  minRating?: 3.5 | 4 | 4.5 | 5;
+}
+
+export interface ParsedArgsHelp {
+  help: true;
+  outputJson: boolean;
+}
+
+export interface ParsedArgsFlights {
+  help: false;
+  mode: "flights";
   outputJson: boolean;
-  help: boolean;
+  query: FlightQuery;
 }
 
+export interface ParsedArgsHotels {
+  help: false;
+  mode: "hotels";
+  outputJson: boolean;
+  query: HotelQuery;
+}
+
+export type ParsedArgs = ParsedArgsHelp | ParsedArgsFlights | ParsedArgsHotels;
+
 export interface FlightOption {
   price: number;
   airline: string;
@@ -34,3 +59,13 @@ export interface FlightOption {
   durationMinutes: number;
   stops: number;
 }
+
+export interface HotelOption {
+  name: string;
+  nightlyPrice: number;
+  totalPrice?: number;
+  rating?: number;
+  reviews?: number;
+  location: string;
+  link?: string;
+}