letsfg 2026.5.62 → 2026.5.64

package/README.md

@@ -1,104 +1,197 @@
-# LetsFG — Your AI agent just learned to book flights. (Node.js)
-
-**Server-side search engine. Real prices. One function call.** Search hundreds of airlines at raw airline prices — **$20–$50 cheaper** than Booking.com, Kayak, and other OTAs. Zero dependencies. Built for AI agents.
-
-[![GitHub stars](https://img.shields.io/github/stars/LetsFG/LetsFG?style=social)](https://github.com/LetsFG/LetsFG)
-[![npm](https://img.shields.io/npm/v/letsfg)](https://www.npmjs.com/package/letsfg)
-
-## Two ways to use LetsFG
-
-| | **CLI / SDK** (this package) | **Developer API** |
-|---|---|---|
-| **Search cost** | Free (Twitter/X Bearer token via `letsfg auth`) | Prepaid credits |
-| **Booking** | `POST /api/agent-book` | Direct airline URL |
-| **Speed** | 60–90 s | 2–5 s (discover) · 60–90 s (full) |
-| **Setup** | `npm install letsfg` then `letsfg auth` | [letsfg.co/developers](https://letsfg.co/developers) |
-
-> **Want direct airline URLs without any per-booking fee?** Use the [Developer API](https://letsfg.co/developers) — prepaid credits, results in seconds, no checkout step.
-
-## Install
-
-```bash
-npm install letsfg
-```
-
-## Quick Start (SDK)
-
-```typescript
-import { LetsFG, cheapestOffer, offerSummary } from 'letsfg';
-
-// Register (one-time)
-const creds = await LetsFG.register('my-agent', 'agent@example.com');
-console.log(creds.api_key); // Save this
-
-// Use
-const bt = new LetsFG({ apiKey: 'trav_...' });
-
-// Search — FREE
-const flights = await bt.search('GDN', 'BER', '2026-03-03');
-const best = cheapestOffer(flights);
-console.log(offerSummary(best));
-
-// Unlock
-const unlock = await bt.unlock(best.id);
-
-// Book
-const booking = await bt.book(
-  best.id,
-  [{
-    id: flights.passenger_ids[0],
-    given_name: 'John',
-    family_name: 'Doe',
-    born_on: '1990-01-15',
-    gender: 'm',
-    title: 'mr',
-    email: 'john@example.com',
-  }],
-  'john@example.com'
-);
-console.log(`PNR: ${booking.booking_reference}`);
-```
-
-## Quick Start (CLI)
-
-```bash
-export LETSFG_BEARER_TOKEN=<your-bearer-token>
-
-letsfg search GDN BER 2026-03-03 --sort price
-letsfg search LON BCN 2026-04-01 --json  # Machine-readable
-letsfg unlock off_xxx
-letsfg book off_xxx -p '{"id":"pas_xxx","given_name":"John",...}' -e john@example.com
-```
-
-## API
-
-### `new LetsFG({ apiKey, baseUrl?, timeout? })`
-
-### `bt.search(origin, destination, dateFrom, options?)`
-### `bt.resolveLocation(query)`
-### `bt.unlock(offerId)`
-### `bt.book(offerId, passengers, contactEmail, contactPhone?)`
-### `bt.setupPayment(token?)`
-### `bt.me()`
-### `LetsFG.register(agentName, email, baseUrl?, ownerName?, description?)`
-
-### Helpers
-- `offerSummary(offer)` — One-line string summary
-- `cheapestOffer(result)` — Get cheapest offer from search
-
-## Zero Dependencies
-
-Uses native `fetch` (Node 18+). No `axios`, no `node-fetch`, nothing. Safe for sandboxed environments.
-
-## Also Available As
-
-- **MCP Server**: `npx letsfg-mcp` — [npm](https://www.npmjs.com/package/letsfg-mcp)
-- **Python SDK + CLI**: `pip install letsfg` — [PyPI](https://pypi.org/project/letsfg/)
-- **Try without installing**: [letsfg.co](https://letsfg.co) — search instantly in your browser
-- **GitHub**: [LetsFG/LetsFG](https://github.com/LetsFG/LetsFG)
-
-> ⭐ **[Star the repo](https://github.com/LetsFG/LetsFG)** — we appreciate the support.
-
-## License
-
-MIT
+# LetsFG — Your AI agent just learned to book flights. (Node.js)
+
+**Server-side search engine. Real prices. One function call.** Search hundreds of airlines at raw airline prices — **$20–$50 cheaper** than Booking.com, Kayak, and other OTAs. Zero dependencies. Built for AI agents.
+
+[![GitHub stars](https://img.shields.io/github/stars/LetsFG/LetsFG?style=social)](https://github.com/LetsFG/LetsFG)
+[![npm](https://img.shields.io/npm/v/letsfg)](https://www.npmjs.com/package/letsfg)
+
+## Two ways to use LetsFG
+
+| | **CLI / SDK** (this package) | **Developer API** |
+|---|---|---|
+| **Search cost** | Free (Twitter/X Bearer token via `letsfg auth`) | Prepaid credits |
+| **Booking** | `POST /api/agent-book` | Direct airline URL |
+| **Speed** | 60–90 s | 2–5 s (discover) · 60–90 s (full) |
+| **Setup** | `npm install letsfg` then `letsfg auth` | [letsfg.co/developers](https://letsfg.co/developers) |
+
+> **Want direct airline URLs without any per-booking fee?** Use the [Developer API](https://letsfg.co/developers) — prepaid credits, results in seconds, no checkout step.
+
+## Install
+
+```bash
+npm install letsfg
+```
+
+## Quick Start (SDK)
+
+```typescript
+import { LetsFG, cheapestOffer, offerSummary } from 'letsfg';
+
+// Register (one-time)
+const creds = await LetsFG.register('my-agent', 'agent@example.com');
+console.log(creds.api_key); // Save this
+
+// Use
+const bt = new LetsFG({ apiKey: 'trav_...' });
+
+// Search — FREE
+const flights = await bt.search('GDN', 'BER', '2026-03-03');
+const best = cheapestOffer(flights);
+console.log(offerSummary(best));
+
+// Unlock
+const unlock = await bt.unlock(best.id);
+
+// Book
+const booking = await bt.book(
+  best.id,
+  [{
+    id: flights.passenger_ids[0],
+    given_name: 'John',
+    family_name: 'Doe',
+    born_on: '1990-01-15',
+    gender: 'm',
+    title: 'mr',
+    email: 'john@example.com',
+  }],
+  'john@example.com'
+);
+console.log(`PNR: ${booking.booking_reference}`);
+```
+
+## Quick Start (CLI)
+
+```bash
+export LETSFG_BEARER_TOKEN=<your-bearer-token>
+
+letsfg search GDN BER 2026-03-03 --sort price
+letsfg search LON BCN 2026-04-01 --json  # Machine-readable
+letsfg unlock off_xxx
+letsfg book off_xxx -p '{"id":"pas_xxx","given_name":"John",...}' -e john@example.com
+```
+
+## API
+
+### `new LetsFG({ apiKey, baseUrl?, timeout? })`
+
+### `bt.search(origin, destination, dateFrom, options?)`
+### `bt.resolveLocation(query)`
+### `bt.unlock(offerId)`
+### `bt.book(offerId, passengers, contactEmail, contactPhone?)`
+### `bt.setupPayment(token?)`
+### `bt.me()`
+### `LetsFG.register(agentName, email, baseUrl?, ownerName?, description?)`
+
+### Helpers
+- `offerSummary(offer)` — One-line string summary
+- `cheapestOffer(result)` — Get cheapest offer from search
+
+## Zero Dependencies
+
+Uses native `fetch` (Node 18+). No `axios`, no `node-fetch`, nothing. Safe for sandboxed environments.
+
+## Also Available As
+
+- **MCP Server**: `npx letsfg-mcp` — [npm](https://www.npmjs.com/package/letsfg-mcp)
+- **Python SDK + CLI**: `pip install letsfg` — [PyPI](https://pypi.org/project/letsfg/)
+- **Try without installing**: [letsfg.co](https://letsfg.co) — search instantly in your browser
+- **GitHub**: [LetsFG/LetsFG](https://github.com/LetsFG/LetsFG)
+
+> ⭐ **[Star the repo](https://github.com/LetsFG/LetsFG)** — we appreciate the support.
+
+## License
+
+MIT
+
+## 🏨 Hotels — new, and live
+
+Your agent can now book hotels, not just flights. Same API key, same card on file.
+
+```python
+from letsfg import LetsFG
+lfg = LetsFG()
+
+city = lfg.hotel_destinations("Warsaw")[0]
+stays = lfg.search_hotels(
+    city_id=city["Id"], city_name=city["Name"],
+    check_in="2026-11-10", check_out="2026-11-12", adults=2,
+)
+
+hotel = stays["hotels"][0]
+offer = hotel["offers"][0]
+print(hotel["name"], offer["price"], stays["currency"])
+# Hotel Gromada Warszawa Centrum 669.86 PLN
+
+booking = lfg.book_hotel_and_wait(
+    session_id=stays["session_id"],
+    hotel_code=hotel["hotel_code"],
+    combination_id_v2=offer["combination_id_v2"],
+    expected_price=offer["price"],
+    expected_balance=offer["balance_to_supplier"],
+    city_id=city["Id"], city_name=city["Name"],
+    check_in="2026-11-10", check_out="2026-11-12",
+    guests=[{"title": "Mr", "first_name": "Jan", "last_name": "Kowalski"}],
+    email="guest@example.com", phone="512345678",
+)
+print(booking["confirmation"], booking["pay_link"])
+```
+
+### How you pay
+
+**10% now, the rest to the hotel later.** At booking we charge 10% of the price
+to your card as a reservation fee. The remaining balance is paid **directly to
+the supplier** through a `pay_link` we return — we never hold it.
+
+`balance_due_by` is the supplier's own auto-cancellation date, not a date we
+invent. Miss it and the room is released.
+
+The 10% is **non-refundable**. Cancelling before `balance_due_by` costs nothing
+else; after it, the hotel's own cancellation ladder applies and can reach 100%.
+That ladder ships in the booking's `terms`, so you can always see the cost before
+you cancel.
+
+### Things worth knowing before you build
+
+- **A card on file is required for every hotel call, including search.** That is
+  unusual and it is deliberate: a hotel search opens a real session at the
+  supplier, and booking blocks a real rate. We would rather refuse up front than
+  let you reach the point of commitment and discover you cannot pay. The same
+  card that authorises flight booking authorises hotels — there is no separate
+  hotel signup.
+- **Only free-cancellation, pay-later rates are sold.** Those are the rates where
+  the balance can safely be settled with the supplier after booking, which is
+  what makes 10%-now/rest-later work at all. You will see fewer results than a
+  metasearch shows you. Every one of them can actually be booked.
+- **Booking is asynchronous.** `book_hotel` returns a `booking_job_id`, not a
+  booking — the real thing takes minutes. Poll `hotel_booking(job_id)` until
+  `status` is `succeeded` or `failed`, or call `book_hotel_and_wait` and let the
+  SDK do it. This is not ceremony: it is what makes it impossible to charge a
+  card and then lose the confirmation to a timeout.
+- **The fee is charged before the room is committed.** A declined card therefore
+  costs nothing to unwind — no reservation exists and nothing is charged.
+- **Do not retry a booking blindly.** Calling `book_hotel` twice for the same
+  rate books the room twice and charges two reservation fees.
+- `price` is what the guest pays. There is no wholesale figure in the response to
+  quote by mistake.
+
+### JavaScript
+
+```javascript
+import { LetsFG } from 'letsfg';
+const lfg = new LetsFG({ apiKey: process.env.LETSFG_API_KEY });
+
+const [city] = await lfg.hotelDestinations('Warsaw');
+const stays = await lfg.searchHotels({
+  cityId: city.Id, cityName: city.Name,
+  checkIn: '2026-11-10', checkOut: '2026-11-12', adults: 2,
+});
+
+const booking = await lfg.bookHotelAndWait({ /* ...offer + guest details... */ });
+console.log(booking.confirmation, booking.pay_link);
+```
+
+### MCP
+
+Five new tools, in the order you call them: `resolve_hotel_city` →
+`search_hotels` → `book_hotel` → `get_hotel_booking` → `cancel_hotel_booking`.
+

package/dist/{chunk-AYF7QMP4.mjs → chunk-ZX2EIEN7.mjs}

@@ -1652,6 +1652,161 @@ var LetsFG = class {
     if (idempotencyKey) body.idempotency_key = idempotencyKey;
     return this.post("/developers/api/v1/bookings/book", body);
   }
+  // ── Hotels ──────────────────────────────────────────────────────────
+  //
+  // A card on file is required for EVERY hotel call, search included. That is
+  // deliberate: a hotel search opens a real session at the supplier and booking
+  // blocks a real rate, so a caller is never allowed to reach the point of
+  // commitment only to discover it cannot pay. The same card that authorises
+  // flight booking authorises hotels — there is no separate hotel enrolment.
+  //
+  // Only free-cancellation, pay-later rates are sold. Those are the rates where
+  // the guest's balance can safely be settled with the supplier after booking,
+  // which is what makes 10%-now/rest-later work. The result set is smaller than
+  // a metasearch's, and every row in it can actually be booked.
+  /**
+   * Resolve a place name to the city id that searchHotels() needs.
+   *
+   * Use `Id` from the first result as `cityId` and `Name` as `cityName`.
+   */
+  async hotelDestinations(text) {
+    this.requireApiKey();
+    const data = await this.post(
+      "/developers/api/v1/hotels/destinations",
+      { text },
+      6e4
+    );
+    return data.results ?? [];
+  }
+  /**
+   * Search real, bookable hotel inventory.
+   *
+   * Slow by nature — the supplier streams a whole city and every rate is priced
+   * — so this gets its own generous timeout rather than the client default.
+   *
+   * Each offer carries `price` (what the guest pays), `reservation_fee_now`
+   * (the 10% taken at booking), `balance_to_supplier`, `balance_due_by` and
+   * `free_cancellation_until`. There is no wholesale figure to quote by mistake.
+   *
+   * Keep `session_id` and the chosen offer's `combination_id_v2`: together they
+   * identify the exact rate, and booking needs both.
+   */
+  async searchHotels(params) {
+    this.requireApiKey();
+    const body = {
+      city_id: params.cityId,
+      city_name: params.cityName,
+      check_in: params.checkIn,
+      check_out: params.checkOut,
+      adults: params.adults ?? 2,
+      children: params.children ?? 0,
+      nationality: params.nationality ?? "PL",
+      limit: params.limit ?? 40,
+      with_images: params.withImages ?? true
+    };
+    if (params.childAges?.length) body.child_ages = params.childAges;
+    return this.post("/developers/api/v1/hotels/search", body, 24e4);
+  }
+  /**
+   * Start a booking. Returns a job immediately — it does NOT book inline.
+   *
+   * A booking takes minutes: the rate is re-blocked at the supplier, every
+   * price and date rail is checked, the 10% reservation fee is charged to your
+   * card, and only then is the room committed. No proxy holds a connection that
+   * long, so this returns at once and you poll hotelBooking() for the outcome.
+   * Use bookHotelAndWait() if you would rather block.
+   *
+   * Because the fee is taken BEFORE the commit, a declined card costs nothing
+   * to unwind: no reservation exists and nothing is charged.
+   *
+   * Send `expectedPrice` and `expectedBalance` back exactly as search returned
+   * them — the booking is refused if the supplier has moved beyond tolerance,
+   * so a guest is never charged a price they did not agree to.
+   *
+   * Do NOT call this again for the same rate while a job is running: that books
+   * the room twice and charges two reservation fees.
+   */
+  async bookHotel(params) {
+    this.requireApiKey();
+    const body = {
+      session_id: params.sessionId,
+      hotel_code: params.hotelCode,
+      combination_id_v2: params.combinationIdV2,
+      expected_price: params.expectedPrice,
+      expected_balance: params.expectedBalance,
+      city_id: params.cityId,
+      city_name: params.cityName,
+      check_in: params.checkIn,
+      check_out: params.checkOut,
+      adults: params.adults ?? 2,
+      guests: params.guests,
+      email: params.email,
+      phone: params.phone,
+      phone_country_code: params.phoneCountryCode ?? "48",
+      special_requests: params.specialRequests ?? []
+    };
+    if (params.combinationId != null) body.combination_id = params.combinationId;
+    if (params.hotelName) body.hotel_name = params.hotelName;
+    return this.post("/developers/api/v1/hotels/book", body, 9e4);
+  }
+  /**
+   * Collect the result of a booking started with bookHotel().
+   *
+   * `status` is 'in_progress', 'succeeded' or 'failed'. On success you get
+   * `confirmation`, `reservation_fee_charged`, `pay_link`, `balance_due`,
+   * `balance_due_by` and `terms` (including the full cancellation ladder).
+   */
+  async hotelBooking(bookingJobId) {
+    this.requireApiKey();
+    return this.get(
+      `/developers/api/v1/hotels/booking/${encodeURIComponent(bookingJobId)}`,
+      6e4
+    );
+  }
+  /**
+   * bookHotel(), then poll until the booking settles. Convenience only.
+   *
+   * Giving up after `maxWaitMs` does NOT cancel anything — the booking may
+   * still complete. The returned object carries `booking_job_id` so you can
+   * keep polling, and the confirmation is emailed to the guest regardless.
+   */
+  async bookHotelAndWait(params) {
+    const pollIntervalMs = params.pollIntervalMs ?? 2e4;
+    const maxWaitMs = params.maxWaitMs ?? 6e5;
+    const job = await this.bookHotel(params);
+    const jobId = job.booking_job_id;
+    if (!jobId) return job;
+    let waited = 0;
+    let result = job;
+    while (waited < maxWaitMs) {
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+      waited += pollIntervalMs;
+      result = await this.hotelBooking(jobId);
+      const st = result.status;
+      if (st === "succeeded" || st === "failed") return result;
+    }
+    if (result.booking_job_id == null) result.booking_job_id = jobId;
+    return result;
+  }
+  /**
+   * Release a reservation at the supplier.
+   *
+   * Free until `balance_due_by`; after that the hotel's own cancellation ladder
+   * applies and can reach 100%. The ladder ships in the booking's `terms`, so
+   * you can see the cost before calling this. The 10% reservation fee is NOT
+   * refunded.
+   *
+   * This drives a browser at the supplier and takes over a minute. If it times
+   * out, do not assume it failed — re-check before retrying.
+   */
+  async cancelHotel(confirmation) {
+    this.requireApiKey();
+    return this.post(
+      "/developers/api/v1/hotels/cancel",
+      { confirmation },
+      3e5
+    );
+  }
   /**
    * [Developer API only] Attach a card to a PAID prepaid Developer API account.
    *
@@ -1709,15 +1864,15 @@ var LetsFG = class {
     const headers = this.usingPFS ? { "Authorization": `Bearer ${this.bearerToken}` } : { "X-API-Key": this.apiKey };
     return this.requestWithHeaders(path, "POST", headers, body);
   }
-  async post(path, body) {
-    return this.requestWithHeaders(path, "POST", { "X-API-Key": this.apiKey }, body);
+  async post(path, body, timeoutMs) {
+    return this.requestWithHeaders(path, "POST", { "X-API-Key": this.apiKey }, body, timeoutMs);
   }
-  async get(path) {
-    return this.requestWithHeaders(path, "GET", { "X-API-Key": this.apiKey });
+  async get(path, timeoutMs) {
+    return this.requestWithHeaders(path, "GET", { "X-API-Key": this.apiKey }, void 0, timeoutMs);
   }
-  async requestWithHeaders(path, method, extraHeaders, body) {
+  async requestWithHeaders(path, method, extraHeaders, body, timeoutMs) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeout);
+    const timer = setTimeout(() => controller.abort(), timeoutMs ?? this.timeout);
     try {
       const resp = await fetch(`${this.baseUrl}${path}`, {
         method,

package/dist/cli.js

@@ -407,6 +407,161 @@ var LetsFG = class {
     if (idempotencyKey) body.idempotency_key = idempotencyKey;
     return this.post("/developers/api/v1/bookings/book", body);
   }
+  // ── Hotels ──────────────────────────────────────────────────────────
+  //
+  // A card on file is required for EVERY hotel call, search included. That is
+  // deliberate: a hotel search opens a real session at the supplier and booking
+  // blocks a real rate, so a caller is never allowed to reach the point of
+  // commitment only to discover it cannot pay. The same card that authorises
+  // flight booking authorises hotels — there is no separate hotel enrolment.
+  //
+  // Only free-cancellation, pay-later rates are sold. Those are the rates where
+  // the guest's balance can safely be settled with the supplier after booking,
+  // which is what makes 10%-now/rest-later work. The result set is smaller than
+  // a metasearch's, and every row in it can actually be booked.
+  /**
+   * Resolve a place name to the city id that searchHotels() needs.
+   *
+   * Use `Id` from the first result as `cityId` and `Name` as `cityName`.
+   */
+  async hotelDestinations(text) {
+    this.requireApiKey();
+    const data = await this.post(
+      "/developers/api/v1/hotels/destinations",
+      { text },
+      6e4
+    );
+    return data.results ?? [];
+  }
+  /**
+   * Search real, bookable hotel inventory.
+   *
+   * Slow by nature — the supplier streams a whole city and every rate is priced
+   * — so this gets its own generous timeout rather than the client default.
+   *
+   * Each offer carries `price` (what the guest pays), `reservation_fee_now`
+   * (the 10% taken at booking), `balance_to_supplier`, `balance_due_by` and
+   * `free_cancellation_until`. There is no wholesale figure to quote by mistake.
+   *
+   * Keep `session_id` and the chosen offer's `combination_id_v2`: together they
+   * identify the exact rate, and booking needs both.
+   */
+  async searchHotels(params) {
+    this.requireApiKey();
+    const body = {
+      city_id: params.cityId,
+      city_name: params.cityName,
+      check_in: params.checkIn,
+      check_out: params.checkOut,
+      adults: params.adults ?? 2,
+      children: params.children ?? 0,
+      nationality: params.nationality ?? "PL",
+      limit: params.limit ?? 40,
+      with_images: params.withImages ?? true
+    };
+    if (params.childAges?.length) body.child_ages = params.childAges;
+    return this.post("/developers/api/v1/hotels/search", body, 24e4);
+  }
+  /**
+   * Start a booking. Returns a job immediately — it does NOT book inline.
+   *
+   * A booking takes minutes: the rate is re-blocked at the supplier, every
+   * price and date rail is checked, the 10% reservation fee is charged to your
+   * card, and only then is the room committed. No proxy holds a connection that
+   * long, so this returns at once and you poll hotelBooking() for the outcome.
+   * Use bookHotelAndWait() if you would rather block.
+   *
+   * Because the fee is taken BEFORE the commit, a declined card costs nothing
+   * to unwind: no reservation exists and nothing is charged.
+   *
+   * Send `expectedPrice` and `expectedBalance` back exactly as search returned
+   * them — the booking is refused if the supplier has moved beyond tolerance,
+   * so a guest is never charged a price they did not agree to.
+   *
+   * Do NOT call this again for the same rate while a job is running: that books
+   * the room twice and charges two reservation fees.
+   */
+  async bookHotel(params) {
+    this.requireApiKey();
+    const body = {
+      session_id: params.sessionId,
+      hotel_code: params.hotelCode,
+      combination_id_v2: params.combinationIdV2,
+      expected_price: params.expectedPrice,
+      expected_balance: params.expectedBalance,
+      city_id: params.cityId,
+      city_name: params.cityName,
+      check_in: params.checkIn,
+      check_out: params.checkOut,
+      adults: params.adults ?? 2,
+      guests: params.guests,
+      email: params.email,
+      phone: params.phone,
+      phone_country_code: params.phoneCountryCode ?? "48",
+      special_requests: params.specialRequests ?? []
+    };
+    if (params.combinationId != null) body.combination_id = params.combinationId;
+    if (params.hotelName) body.hotel_name = params.hotelName;
+    return this.post("/developers/api/v1/hotels/book", body, 9e4);
+  }
+  /**
+   * Collect the result of a booking started with bookHotel().
+   *
+   * `status` is 'in_progress', 'succeeded' or 'failed'. On success you get
+   * `confirmation`, `reservation_fee_charged`, `pay_link`, `balance_due`,
+   * `balance_due_by` and `terms` (including the full cancellation ladder).
+   */
+  async hotelBooking(bookingJobId) {
+    this.requireApiKey();
+    return this.get(
+      `/developers/api/v1/hotels/booking/${encodeURIComponent(bookingJobId)}`,
+      6e4
+    );
+  }
+  /**
+   * bookHotel(), then poll until the booking settles. Convenience only.
+   *
+   * Giving up after `maxWaitMs` does NOT cancel anything — the booking may
+   * still complete. The returned object carries `booking_job_id` so you can
+   * keep polling, and the confirmation is emailed to the guest regardless.
+   */
+  async bookHotelAndWait(params) {
+    const pollIntervalMs = params.pollIntervalMs ?? 2e4;
+    const maxWaitMs = params.maxWaitMs ?? 6e5;
+    const job = await this.bookHotel(params);
+    const jobId = job.booking_job_id;
+    if (!jobId) return job;
+    let waited = 0;
+    let result = job;
+    while (waited < maxWaitMs) {
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+      waited += pollIntervalMs;
+      result = await this.hotelBooking(jobId);
+      const st = result.status;
+      if (st === "succeeded" || st === "failed") return result;
+    }
+    if (result.booking_job_id == null) result.booking_job_id = jobId;
+    return result;
+  }
+  /**
+   * Release a reservation at the supplier.
+   *
+   * Free until `balance_due_by`; after that the hotel's own cancellation ladder
+   * applies and can reach 100%. The ladder ships in the booking's `terms`, so
+   * you can see the cost before calling this. The 10% reservation fee is NOT
+   * refunded.
+   *
+   * This drives a browser at the supplier and takes over a minute. If it times
+   * out, do not assume it failed — re-check before retrying.
+   */
+  async cancelHotel(confirmation) {
+    this.requireApiKey();
+    return this.post(
+      "/developers/api/v1/hotels/cancel",
+      { confirmation },
+      3e5
+    );
+  }
   /**
    * [Developer API only] Attach a card to a PAID prepaid Developer API account.
    *
@@ -464,15 +619,15 @@ var LetsFG = class {
     const headers = this.usingPFS ? { "Authorization": `Bearer ${this.bearerToken}` } : { "X-API-Key": this.apiKey };
     return this.requestWithHeaders(path, "POST", headers, body);
   }
-  async post(path, body) {
-    return this.requestWithHeaders(path, "POST", { "X-API-Key": this.apiKey }, body);
+  async post(path, body, timeoutMs) {
+    return this.requestWithHeaders(path, "POST", { "X-API-Key": this.apiKey }, body, timeoutMs);
   }
-  async get(path) {
-    return this.requestWithHeaders(path, "GET", { "X-API-Key": this.apiKey });
+  async get(path, timeoutMs) {
+    return this.requestWithHeaders(path, "GET", { "X-API-Key": this.apiKey }, void 0, timeoutMs);
   }
-  async requestWithHeaders(path, method, extraHeaders, body) {
+  async requestWithHeaders(path, method, extraHeaders, body, timeoutMs) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeout);
+    const timer = setTimeout(() => controller.abort(), timeoutMs ?? this.timeout);
     try {
       const resp = await fetch(`${this.baseUrl}${path}`, {
         method,

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   LetsFG,
   LetsFGError,
   offerSummary
-} from "./chunk-AYF7QMP4.mjs";
+} from "./chunk-ZX2EIEN7.mjs";
 
 // src/cli.ts
 function getFlag(args, flag, alias) {

package/dist/index.d.mts

@@ -480,6 +480,112 @@ declare class LetsFG {
      * Always provide idempotencyKey to prevent double-bookings on retry.
      */
     book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string): Promise<BookingResult>;
+    /**
+     * Resolve a place name to the city id that searchHotels() needs.
+     *
+     * Use `Id` from the first result as `cityId` and `Name` as `cityName`.
+     */
+    hotelDestinations(text: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Search real, bookable hotel inventory.
+     *
+     * Slow by nature — the supplier streams a whole city and every rate is priced
+     * — so this gets its own generous timeout rather than the client default.
+     *
+     * Each offer carries `price` (what the guest pays), `reservation_fee_now`
+     * (the 10% taken at booking), `balance_to_supplier`, `balance_due_by` and
+     * `free_cancellation_until`. There is no wholesale figure to quote by mistake.
+     *
+     * Keep `session_id` and the chosen offer's `combination_id_v2`: together they
+     * identify the exact rate, and booking needs both.
+     */
+    searchHotels(params: {
+        cityId: number;
+        cityName: string;
+        checkIn: string;
+        checkOut: string;
+        adults?: number;
+        children?: number;
+        childAges?: number[];
+        /** Two-letter code. Rates and taxes genuinely differ by nationality. */
+        nationality?: string;
+        limit?: number;
+        withImages?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Start a booking. Returns a job immediately — it does NOT book inline.
+     *
+     * A booking takes minutes: the rate is re-blocked at the supplier, every
+     * price and date rail is checked, the 10% reservation fee is charged to your
+     * card, and only then is the room committed. No proxy holds a connection that
+     * long, so this returns at once and you poll hotelBooking() for the outcome.
+     * Use bookHotelAndWait() if you would rather block.
+     *
+     * Because the fee is taken BEFORE the commit, a declined card costs nothing
+     * to unwind: no reservation exists and nothing is charged.
+     *
+     * Send `expectedPrice` and `expectedBalance` back exactly as search returned
+     * them — the booking is refused if the supplier has moved beyond tolerance,
+     * so a guest is never charged a price they did not agree to.
+     *
+     * Do NOT call this again for the same rate while a job is running: that books
+     * the room twice and charges two reservation fees.
+     */
+    bookHotel(params: {
+        sessionId: string;
+        hotelCode: number;
+        combinationIdV2: string;
+        expectedPrice: number;
+        expectedBalance: number;
+        cityId: number;
+        cityName: string;
+        checkIn: string;
+        checkOut: string;
+        guests: Array<{
+            title: string;
+            first_name: string;
+            last_name: string;
+        }>;
+        /** The voucher and the pay link go here. A typo loses the booking. */
+        email: string;
+        phone: string;
+        adults?: number;
+        combinationId?: number;
+        hotelName?: string;
+        phoneCountryCode?: string;
+        specialRequests?: string[];
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Collect the result of a booking started with bookHotel().
+     *
+     * `status` is 'in_progress', 'succeeded' or 'failed'. On success you get
+     * `confirmation`, `reservation_fee_charged`, `pay_link`, `balance_due`,
+     * `balance_due_by` and `terms` (including the full cancellation ladder).
+     */
+    hotelBooking(bookingJobId: string): Promise<Record<string, unknown>>;
+    /**
+     * bookHotel(), then poll until the booking settles. Convenience only.
+     *
+     * Giving up after `maxWaitMs` does NOT cancel anything — the booking may
+     * still complete. The returned object carries `booking_job_id` so you can
+     * keep polling, and the confirmation is emailed to the guest regardless.
+     */
+    bookHotelAndWait(params: Parameters<LetsFG['bookHotel']>[0] & {
+        pollIntervalMs?: number;
+        maxWaitMs?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Release a reservation at the supplier.
+     *
+     * Free until `balance_due_by`; after that the hotel's own cancellation ladder
+     * applies and can reach 100%. The ladder ships in the booking's `terms`, so
+     * you can see the cost before calling this. The 10% reservation fee is NOT
+     * refunded.
+     *
+     * This drives a browser at the supplier and takes over a minute. If it times
+     * out, do not assume it failed — re-check before retrying.
+     */
+    cancelHotel(confirmation: string): Promise<Record<string, unknown>>;
     /**
      * [Developer API only] Attach a card to a PAID prepaid Developer API account.
      *

package/dist/index.d.ts

@@ -480,6 +480,112 @@ declare class LetsFG {
      * Always provide idempotencyKey to prevent double-bookings on retry.
      */
     book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string): Promise<BookingResult>;
+    /**
+     * Resolve a place name to the city id that searchHotels() needs.
+     *
+     * Use `Id` from the first result as `cityId` and `Name` as `cityName`.
+     */
+    hotelDestinations(text: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Search real, bookable hotel inventory.
+     *
+     * Slow by nature — the supplier streams a whole city and every rate is priced
+     * — so this gets its own generous timeout rather than the client default.
+     *
+     * Each offer carries `price` (what the guest pays), `reservation_fee_now`
+     * (the 10% taken at booking), `balance_to_supplier`, `balance_due_by` and
+     * `free_cancellation_until`. There is no wholesale figure to quote by mistake.
+     *
+     * Keep `session_id` and the chosen offer's `combination_id_v2`: together they
+     * identify the exact rate, and booking needs both.
+     */
+    searchHotels(params: {
+        cityId: number;
+        cityName: string;
+        checkIn: string;
+        checkOut: string;
+        adults?: number;
+        children?: number;
+        childAges?: number[];
+        /** Two-letter code. Rates and taxes genuinely differ by nationality. */
+        nationality?: string;
+        limit?: number;
+        withImages?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Start a booking. Returns a job immediately — it does NOT book inline.
+     *
+     * A booking takes minutes: the rate is re-blocked at the supplier, every
+     * price and date rail is checked, the 10% reservation fee is charged to your
+     * card, and only then is the room committed. No proxy holds a connection that
+     * long, so this returns at once and you poll hotelBooking() for the outcome.
+     * Use bookHotelAndWait() if you would rather block.
+     *
+     * Because the fee is taken BEFORE the commit, a declined card costs nothing
+     * to unwind: no reservation exists and nothing is charged.
+     *
+     * Send `expectedPrice` and `expectedBalance` back exactly as search returned
+     * them — the booking is refused if the supplier has moved beyond tolerance,
+     * so a guest is never charged a price they did not agree to.
+     *
+     * Do NOT call this again for the same rate while a job is running: that books
+     * the room twice and charges two reservation fees.
+     */
+    bookHotel(params: {
+        sessionId: string;
+        hotelCode: number;
+        combinationIdV2: string;
+        expectedPrice: number;
+        expectedBalance: number;
+        cityId: number;
+        cityName: string;
+        checkIn: string;
+        checkOut: string;
+        guests: Array<{
+            title: string;
+            first_name: string;
+            last_name: string;
+        }>;
+        /** The voucher and the pay link go here. A typo loses the booking. */
+        email: string;
+        phone: string;
+        adults?: number;
+        combinationId?: number;
+        hotelName?: string;
+        phoneCountryCode?: string;
+        specialRequests?: string[];
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Collect the result of a booking started with bookHotel().
+     *
+     * `status` is 'in_progress', 'succeeded' or 'failed'. On success you get
+     * `confirmation`, `reservation_fee_charged`, `pay_link`, `balance_due`,
+     * `balance_due_by` and `terms` (including the full cancellation ladder).
+     */
+    hotelBooking(bookingJobId: string): Promise<Record<string, unknown>>;
+    /**
+     * bookHotel(), then poll until the booking settles. Convenience only.
+     *
+     * Giving up after `maxWaitMs` does NOT cancel anything — the booking may
+     * still complete. The returned object carries `booking_job_id` so you can
+     * keep polling, and the confirmation is emailed to the guest regardless.
+     */
+    bookHotelAndWait(params: Parameters<LetsFG['bookHotel']>[0] & {
+        pollIntervalMs?: number;
+        maxWaitMs?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Release a reservation at the supplier.
+     *
+     * Free until `balance_due_by`; after that the hotel's own cancellation ladder
+     * applies and can reach 100%. The ladder ships in the booking's `terms`, so
+     * you can see the cost before calling this. The 10% reservation fee is NOT
+     * refunded.
+     *
+     * This drives a browser at the supplier and takes over a minute. If it times
+     * out, do not assume it failed — re-check before retrying.
+     */
+    cancelHotel(confirmation: string): Promise<Record<string, unknown>>;
     /**
      * [Developer API only] Attach a card to a PAID prepaid Developer API account.
      *

package/dist/index.js

@@ -1700,6 +1700,161 @@ var LetsFG = class {
     if (idempotencyKey) body.idempotency_key = idempotencyKey;
     return this.post("/developers/api/v1/bookings/book", body);
   }
+  // ── Hotels ──────────────────────────────────────────────────────────
+  //
+  // A card on file is required for EVERY hotel call, search included. That is
+  // deliberate: a hotel search opens a real session at the supplier and booking
+  // blocks a real rate, so a caller is never allowed to reach the point of
+  // commitment only to discover it cannot pay. The same card that authorises
+  // flight booking authorises hotels — there is no separate hotel enrolment.
+  //
+  // Only free-cancellation, pay-later rates are sold. Those are the rates where
+  // the guest's balance can safely be settled with the supplier after booking,
+  // which is what makes 10%-now/rest-later work. The result set is smaller than
+  // a metasearch's, and every row in it can actually be booked.
+  /**
+   * Resolve a place name to the city id that searchHotels() needs.
+   *
+   * Use `Id` from the first result as `cityId` and `Name` as `cityName`.
+   */
+  async hotelDestinations(text) {
+    this.requireApiKey();
+    const data = await this.post(
+      "/developers/api/v1/hotels/destinations",
+      { text },
+      6e4
+    );
+    return data.results ?? [];
+  }
+  /**
+   * Search real, bookable hotel inventory.
+   *
+   * Slow by nature — the supplier streams a whole city and every rate is priced
+   * — so this gets its own generous timeout rather than the client default.
+   *
+   * Each offer carries `price` (what the guest pays), `reservation_fee_now`
+   * (the 10% taken at booking), `balance_to_supplier`, `balance_due_by` and
+   * `free_cancellation_until`. There is no wholesale figure to quote by mistake.
+   *
+   * Keep `session_id` and the chosen offer's `combination_id_v2`: together they
+   * identify the exact rate, and booking needs both.
+   */
+  async searchHotels(params) {
+    this.requireApiKey();
+    const body = {
+      city_id: params.cityId,
+      city_name: params.cityName,
+      check_in: params.checkIn,
+      check_out: params.checkOut,
+      adults: params.adults ?? 2,
+      children: params.children ?? 0,
+      nationality: params.nationality ?? "PL",
+      limit: params.limit ?? 40,
+      with_images: params.withImages ?? true
+    };
+    if (params.childAges?.length) body.child_ages = params.childAges;
+    return this.post("/developers/api/v1/hotels/search", body, 24e4);
+  }
+  /**
+   * Start a booking. Returns a job immediately — it does NOT book inline.
+   *
+   * A booking takes minutes: the rate is re-blocked at the supplier, every
+   * price and date rail is checked, the 10% reservation fee is charged to your
+   * card, and only then is the room committed. No proxy holds a connection that
+   * long, so this returns at once and you poll hotelBooking() for the outcome.
+   * Use bookHotelAndWait() if you would rather block.
+   *
+   * Because the fee is taken BEFORE the commit, a declined card costs nothing
+   * to unwind: no reservation exists and nothing is charged.
+   *
+   * Send `expectedPrice` and `expectedBalance` back exactly as search returned
+   * them — the booking is refused if the supplier has moved beyond tolerance,
+   * so a guest is never charged a price they did not agree to.
+   *
+   * Do NOT call this again for the same rate while a job is running: that books
+   * the room twice and charges two reservation fees.
+   */
+  async bookHotel(params) {
+    this.requireApiKey();
+    const body = {
+      session_id: params.sessionId,
+      hotel_code: params.hotelCode,
+      combination_id_v2: params.combinationIdV2,
+      expected_price: params.expectedPrice,
+      expected_balance: params.expectedBalance,
+      city_id: params.cityId,
+      city_name: params.cityName,
+      check_in: params.checkIn,
+      check_out: params.checkOut,
+      adults: params.adults ?? 2,
+      guests: params.guests,
+      email: params.email,
+      phone: params.phone,
+      phone_country_code: params.phoneCountryCode ?? "48",
+      special_requests: params.specialRequests ?? []
+    };
+    if (params.combinationId != null) body.combination_id = params.combinationId;
+    if (params.hotelName) body.hotel_name = params.hotelName;
+    return this.post("/developers/api/v1/hotels/book", body, 9e4);
+  }
+  /**
+   * Collect the result of a booking started with bookHotel().
+   *
+   * `status` is 'in_progress', 'succeeded' or 'failed'. On success you get
+   * `confirmation`, `reservation_fee_charged`, `pay_link`, `balance_due`,
+   * `balance_due_by` and `terms` (including the full cancellation ladder).
+   */
+  async hotelBooking(bookingJobId) {
+    this.requireApiKey();
+    return this.get(
+      `/developers/api/v1/hotels/booking/${encodeURIComponent(bookingJobId)}`,
+      6e4
+    );
+  }
+  /**
+   * bookHotel(), then poll until the booking settles. Convenience only.
+   *
+   * Giving up after `maxWaitMs` does NOT cancel anything — the booking may
+   * still complete. The returned object carries `booking_job_id` so you can
+   * keep polling, and the confirmation is emailed to the guest regardless.
+   */
+  async bookHotelAndWait(params) {
+    const pollIntervalMs = params.pollIntervalMs ?? 2e4;
+    const maxWaitMs = params.maxWaitMs ?? 6e5;
+    const job = await this.bookHotel(params);
+    const jobId = job.booking_job_id;
+    if (!jobId) return job;
+    let waited = 0;
+    let result = job;
+    while (waited < maxWaitMs) {
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+      waited += pollIntervalMs;
+      result = await this.hotelBooking(jobId);
+      const st = result.status;
+      if (st === "succeeded" || st === "failed") return result;
+    }
+    if (result.booking_job_id == null) result.booking_job_id = jobId;
+    return result;
+  }
+  /**
+   * Release a reservation at the supplier.
+   *
+   * Free until `balance_due_by`; after that the hotel's own cancellation ladder
+   * applies and can reach 100%. The ladder ships in the booking's `terms`, so
+   * you can see the cost before calling this. The 10% reservation fee is NOT
+   * refunded.
+   *
+   * This drives a browser at the supplier and takes over a minute. If it times
+   * out, do not assume it failed — re-check before retrying.
+   */
+  async cancelHotel(confirmation) {
+    this.requireApiKey();
+    return this.post(
+      "/developers/api/v1/hotels/cancel",
+      { confirmation },
+      3e5
+    );
+  }
   /**
    * [Developer API only] Attach a card to a PAID prepaid Developer API account.
    *
@@ -1757,15 +1912,15 @@ var LetsFG = class {
     const headers = this.usingPFS ? { "Authorization": `Bearer ${this.bearerToken}` } : { "X-API-Key": this.apiKey };
     return this.requestWithHeaders(path, "POST", headers, body);
   }
-  async post(path, body) {
-    return this.requestWithHeaders(path, "POST", { "X-API-Key": this.apiKey }, body);
+  async post(path, body, timeoutMs) {
+    return this.requestWithHeaders(path, "POST", { "X-API-Key": this.apiKey }, body, timeoutMs);
   }
-  async get(path) {
-    return this.requestWithHeaders(path, "GET", { "X-API-Key": this.apiKey });
+  async get(path, timeoutMs) {
+    return this.requestWithHeaders(path, "GET", { "X-API-Key": this.apiKey }, void 0, timeoutMs);
   }
-  async requestWithHeaders(path, method, extraHeaders, body) {
+  async requestWithHeaders(path, method, extraHeaders, body, timeoutMs) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeout);
+    const timer = setTimeout(() => controller.abort(), timeoutMs ?? this.timeout);
     try {
       const resp = await fetch(`${this.baseUrl}${path}`, {
         method,

package/dist/index.mjs

@@ -22,7 +22,7 @@ import {
   offerSummary,
   rankOffers,
   selectDiverseTop
-} from "./chunk-AYF7QMP4.mjs";
+} from "./chunk-ZX2EIEN7.mjs";
 export {
   AuthenticationError,
   BoostedTravel,

package/package.json

@@ -1,52 +1,56 @@
-{
-  "name": "letsfg",
-  "version": "2026.5.62",
-  "description": "Flight search & booking for AI agents. Server-side engine covers hundreds of airlines. Free search via Bearer token or prepaid Developer API. Includes open-source ranking engine.",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "letsfg": "dist/cli.js"
-  },
-  "files": [
-    "dist/",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean",
-    "test": "tsx --test src/index.test.ts",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "flights",
-    "travel",
-    "booking",
-    "agent",
-    "ai",
-    "cli",
-    "autonomous",
-    "mcp",
-    "openai",
-    "airline",
-    "ndc",
-    "search",
-    "ndc"
-  ],
-  "author": "LetsFG",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/LetsFG/LetsFG.git"
-  },
-  "homepage": "https://letsfg.co",
-  "devDependencies": {
-    "@types/node": "^25.3.3",
-    "tsup": "^8.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.3.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "letsfg",
+  "version": "2026.5.64",
+  "description": "Flights and hotels for AI agents. Server-side engine covers hundreds of airlines; hotels are real bookable inventory with free cancellation and pay-later terms. Includes open-source ranking engine.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "letsfg": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean",
+    "test": "tsx --test src/index.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "flights",
+    "travel",
+    "booking",
+    "agent",
+    "ai",
+    "cli",
+    "autonomous",
+    "mcp",
+    "openai",
+    "airline",
+    "ndc",
+    "search",
+    "ndc",
+    "hotels",
+    "hotel-booking",
+    "hotel-search",
+    "accommodation"
+  ],
+  "author": "LetsFG",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LetsFG/LetsFG.git"
+  },
+  "homepage": "https://letsfg.co",
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}