letsfg 2026.5.72 → 2026.5.74

package/README.md

@@ -14,7 +14,7 @@
 | **Speed** | 8–10 s to first results; longer on a split | 2–5 s (discover) · 8–10 s to first results (full) |
 | **Setup** | `npm install letsfg`, then connect at [letsfg.co/developers/api/mcp](https://letsfg.co/developers/api/mcp) | [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.
+> **Building a product, or need hotels?** Use the [Developer API](https://letsfg.co/developers) — look-to-book search (200 free after every booking, then $0.01), booking through `POST /flights/book`, no booking fee and no transaction fee.
 
 ## Install
 
@@ -54,7 +54,7 @@ const flights = await bt.search('GDN', 'BER', '2026-03-03');
 const best = cheapestOffer(flights);
 console.log(offerSummary(best));
 
-// Book — ticket price only, no LetsFG fee, no unlock step. Starts the booking:
+// Book — no booking fee, no transaction fee — our margin is already in the price you saw; no unlock step. Starts the booking:
 // the fare is HELD on your card and a LetsFG agent buys the ticket (4-11 min).
 const result = await bt.book(
   best.id,
@@ -111,8 +111,9 @@ address (passport optional). A missing detail returns `missing_details` with
 same trip while one is in progress — that would place a second hold.
 
 Prefer the paid Developer API instead? Pass `apiKey` instead of `bearerToken` —
-`search()`/`book()` dispatch automatically. That path requires `unlock()`
-(1% fee, min $3) before `book()`.
+`search()`/`book()` dispatch automatically. That path needs a `searchId` (an offer
+is bookable only inside the search that produced it) and has no unlock step:
+`unlock()` was retired 2026-09-08, the route answers `410 Gone`, and there is no fee.
 
 ## Quick Start (CLI)
 
@@ -131,14 +132,15 @@ letsfg book off_xxx --search-id srch_xxx -p '{"given_name":"John","family_name":
 
 ### `bt.search(origin, destination, dateFrom, options?)`
 ### `bt.resolveLocation(query)`
-### `bt.unlock(offerId)` — Developer API only
 ### `bt.book(offerId, passengers, contactEmail, contactPhone?, idempotencyKey?, searchId?)`
 Dispatches on which credential is set: `bearerToken` → PFS booking via
 `POST /api/agent-book` (pass `searchId`, one passenger with full details;
 returns `booking_ref` — poll `POST /api/agent-book/status`). `apiKey` → paid
-Developer API `book` (requires `unlock()` first, supports multiple passengers
-and `idempotencyKey`).
-### `bt.setupPayment(token?)` — Developer API only
+Developer API `book` (requires `searchId`, no unlock step, supports multiple
+passengers and `idempotencyKey`; returns a `booking_id` to poll).
+### `bt.getBooking(bookingId)` / `bt.answerBooking(...)` / `bt.bookAndWait(...)` — Developer API only
+### `bt.connectPayment()` — Developer API only. Returns `connect_url`; nothing is charged
+### `bt.setupPayment()` / `bt.unlock()` — **retired 2026-09-08, both throw locally**
 ### `bt.me()`
 ### `LetsFG.register(agentName, email, baseUrl?, ownerName?, description?)` — Developer API only, most agents don't need this
 
@@ -178,7 +180,7 @@ MIT
 
 ## 🏨 Hotels — new, and live
 
-Your agent can book hotels as well as flights. Same card-backed token or API key, same card on file.
+Your agent can book hotels as well as flights. Same card-backed token or API key, same connected payment method.
 
 ```python
 from letsfg import LetsFG
@@ -192,36 +194,52 @@ stays = lfg.search_hotels(
 
 hotel = stays["hotels"][0]
 offer = hotel["offers"][0]
-print(hotel["name"], offer["price"], stays["currency"])
-# Hotel Gromada Warszawa Centrum 669.86 PLN
+print(hotel["name"], offer["price"], offer["currency"], offer["refundable"])
+# prices are in stays["currency"]: USD unless you pass currency=
 
 booking = lfg.book_hotel_and_wait(
-    session_id=stays["session_id"],
+    session_id=offer["session_id"],
     hotel_code=hotel["hotel_code"],
     combination_id_v2=offer["combination_id_v2"],
-    expected_price=offer["price"],
-    expected_balance=offer["balance_to_supplier"],
+    expected_price=offer["price"],          # copy these four from the offer, verbatim
+    expected_cost=offer["expected_cost"],
+    currency=offer["currency"],
+    fx_rate=offer["fx_rate"],
     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",
+    # ONE entry per guest in the room, children included: adults first, then children in child_ages order
+    guests=[{"title": "Mr", "first_name": "Jan", "last_name": "Kowalski"},
+            {"title": "Mrs", "first_name": "Anna", "last_name": "Kowalska"}],
+    email="GUEST_EMAIL", phone="512345678",   # the guest's real e-mail and phone
 )
-print(booking["confirmation"], booking["pay_link"])
+if booking["status"] == "succeeded":
+    print(booking["confirmation"], booking["total_price"], booking["currency"])
+elif booking["status"] == "failed":
+    print("Not booked, nothing charged:", booking["error"])
+else:  # "attention": a person is checking it with the supplier, the hold is kept. Do not book again.
+    print(booking["status"], booking.get("error"))
 ```
 
 ### How you pay
 
-**5% now, the rest to the hotel later.** At booking we charge 5% 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.
+**The full price is held, and taken only once the hotel confirms.** Booking holds the offer's
+`price` on the Revolut payment method connected to your account — authorised, not charged.
+LetsFG then books the room with the supplier and pays the supplier itself. The hold is captured
+only after the supplier has confirmed the booking; if the booking fails for any reason (the rate
+is gone, the price moved, the supplier declined, a guest detail was rejected), the hold is
+released and nothing is charged.
 
-`balance_due_by` is the supplier's own auto-cancellation date, not a date we
-invent. Miss it and the room is released.
+There is **no reservation fee, no deposit and no pay link**, and the guest owes the hotel nothing
+further. (Those belonged to the process retired on 2026-09-11.)
 
-The 5% 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.
+`price` is the supplier's cost plus 6.4% (our margin and payment processing) for Revolut Pay or a
+card issued in the EEA, or 8.3% for a card issued outside the EEA — the search response's
+`markup_rate` says which. Nothing is added at booking. Prices are in the currency you search in:
+USD unless you ask for another.
+
+Cancelling a refundable rate before its `free_cancellation_until` costs nothing and refunds the
+charge in full. A cancellation that would cost money is refused (409); the hotel's own ladder is in
+the booking's `terms`.
 
 ### What search costs
 
@@ -236,27 +254,36 @@ is not metered, only the search call itself.
 
 ### 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 5%-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.
+- **A connected payment method is required for every hotel call, including search.** A hotel
+  search opens a real session at the supplier and booking blocks a real rate, so we refuse up
+  front rather than let you reach the point of commitment and discover you cannot pay. The same
+  method authorises flights and hotels — there is no separate hotel signup.
+- **Every rate type is sold**, refundable and non-refundable. Each offer's `refundable` and
+  `free_cancellation_until` say which one you are buying.
+- **Booking is asynchronous.** `book_hotel` returns a `booking_job_id`, not a booking — the real
+  thing takes minutes. Poll `hotel_booking(job_id)` every ~20 s until `status` is `succeeded`,
+  `failed` or `attention`, or call `book_hotel_and_wait` and let the SDK do it. All three are final:
+  - `succeeded` — `confirmation`, `total_price` + `currency` (what the guest is charged),
+    `supplier_paid` + `supplier_currency`, `refundable`, `free_cancellation_until`,
+    `cancellation_ladder` and `terms`.
+  - `failed` — `error`, written for the guest. The hold has been released; nothing was charged.
+  - `attention` — the outcome could not be settled automatically. The hold is kept (nothing is
+    charged) while a person checks with the supplier. Do not book again.
+- **Copy the offer verbatim.** Send `expected_price` (the offer's `price`), `expected_cost`,
+  `currency` and `fx_rate` exactly as search returned them. A mis-copied price, or a USD offer sent
+  without its `currency`, is refused with `400 price_mismatch` before anything is held.
+- **Guest details are checked before anything is held**: Latin-script names, a phone number valid
+  for its country code, and an e-mail. A problem returns `400 invalid_details` naming the fields.
+- **One name per guest in the room, children included.** For a family, search with `children` and
+  `child_ages`; the party travels with the offer's session. `guests` then lists every guest — adults
+  first, then children in `child_ages` order. The hotel requires a name for every guest: fewer names
+  than guests is refused before anything is submitted, and the hold is released.
+- **The guest is e-mailed however it ends**: a confirmation with the code and the cancellation
+  term, a note that it did not go through and nothing was charged, or a note that it is being
+  confirmed with the supplier.
+- **A retry never books twice.** A second `book_hotel` for the same rate and guest returns the job
+  already under way (`duplicate: true`); pass `idempotency_key` to make that explicit. Still, never
+  re-post a booking whose job is running — poll it.
 
 ### JavaScript
 
@@ -270,8 +297,21 @@ const stays = await lfg.searchHotels({
   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);
+const hotel = stays.hotels[0];
+const offer = hotel.offers[0];
+const booking = await lfg.bookHotelAndWait({
+  sessionId: offer.session_id, hotelCode: hotel.hotel_code,
+  combinationIdV2: offer.combination_id_v2,
+  expectedPrice: offer.price, expectedCost: offer.expected_cost,
+  currency: offer.currency, fxRate: offer.fx_rate,
+  cityId: city.Id, cityName: city.Name,
+  checkIn: '2026-11-10', checkOut: '2026-11-12',
+  // ONE entry per guest in the room, children included: adults first, then children in childAges order
+  guests: [{ title: 'Mr', first_name: 'Jan', last_name: 'Kowalski' },
+    { title: 'Mrs', first_name: 'Anna', last_name: 'Kowalska' }],
+  email: 'GUEST_EMAIL', phone: '512345678',
+});
+console.log(booking.status, booking.confirmation, booking.total_price, booking.currency);
 ```
 
 ### MCP

package/dist/{chunk-GO3FXQXC.mjs → chunk-GVKYPTY3.mjs}

@@ -1564,6 +1564,7 @@ var LATE_MERGE_POLL_MS = 3e3;
 var LATE_MERGE_GRACE_MS = 9e4;
 var WAIT_FOR_SPLIT = (process.env.LETSFG_WAIT_FOR_SPLIT || "").trim() !== "0";
 var NON_TERMINAL = ["pending", "searching"];
+var HOTEL_BOOKING_FINAL_STATUSES = ["succeeded", "failed", "attention"];
 var LetsFG = class {
   bearerToken;
   apiKey;
@@ -1671,13 +1672,23 @@ var LetsFG = class {
     return Array.isArray(data) ? data : data.locations || [];
   }
   /**
-   * Unlock a flight offer — confirms live price, reveals direct airline booking URL.
-   * Developer API only, legacy — there is no unlock endpoint on a PFS Bearer
-   * token, so PFS callers use book() directly.
+   * RETIRED 2026-09-08. Throws instead of calling the server.
+   *
+   * There is no unlock step on any lane. Unlock existed to confirm a live price
+   * before charging; booking now HOLDS the fare on the connected payment method
+   * and captures only once a real airline PNR exists, so a fare that moved
+   * cannot become a charge for a ticket you did not get. If it moves at
+   * checkout you get a `price_change` question to accept or decline instead.
+   *
+   * Kept as a method, and throwing locally rather than making the request, so an
+   * older caller gets one clear sentence at the line that is actually wrong —
+   * not a 410 body to decode, and not a TypeError somewhere else.
    */
-  async unlock(offerId) {
-    this.requireApiKey();
-    return this.post("/developers/api/v1/bookings/unlock", { offer_id: offerId });
+  async unlock(_offerId) {
+    throw new LetsFGError(
+      "unlock() was retired on 2026-09-08 and the endpoint answers 410 Gone. There is no unlock step: call book() directly. The fare is held on the connected payment method and captured only against a real airline PNR. See https://letsfg.co/developers/api/docs",
+      410
+    );
   }
   /**
    * Book a flight.
@@ -1688,9 +1699,14 @@ var LetsFG = class {
    * complete, { ok, booked: false, booking_url } — hand the link to the user,
    * nothing was charged.
    *
-   * Developer API (X-API-Key): charges ticket price + service fee via Stripe,
-   * creates a real PNR. Requires unlock() first. Always provide
-   * idempotencyKey to prevent double-bookings on retry.
+   * Developer API (X-API-Key): POST /flights/book. NO unlock step. searchId is
+   * REQUIRED — an offer is bookable only inside the search that produced it.
+   * The connected Revolut method is HELD, not charged; a LetsFG booking agent
+   * buys the ticket and the hold is captured only against a real airline PNR.
+   * Returns the 202 { ok, booking_id, state, held, charged: 0, poll_url } —
+   * poll getBooking(bookingId) until `terminal`, or use bookAndWait().
+   * Always provide idempotencyKey: a retry with the same key returns the
+   * existing booking instead of opening a second hold on the card.
    */
   async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "", searchId = "") {
     this.requireAuth();
@@ -1711,28 +1727,107 @@ var LetsFG = class {
       });
     }
     this.requireApiKey();
+    if (!searchId) {
+      throw new LetsFGError(
+        "searchId is required to book on the Developer API \u2014 pass the search_id from search()'s result. An offer can only be booked inside the search that produced it. (Before 2026-09-08 this argument was ignored on this path.)",
+        400
+      );
+    }
+    const pax = passengers.map((p) => ({ ...p }));
+    if (contactPhone && pax.length && !pax[0].phone_number) pax[0].phone_number = contactPhone;
     const body = {
+      search_id: searchId,
       offer_id: offerId,
-      booking_type: "flight",
-      passengers,
-      contact_email: contactEmail,
-      contact_phone: contactPhone
+      passengers: pax,
+      contact_email: contactEmail
     };
     if (idempotencyKey) body.idempotency_key = idempotencyKey;
-    return this.post("/developers/api/v1/bookings/book", body);
+    return this.post("/developers/api/v1/flights/book", body);
+  }
+  /**
+   * Poll a Developer API flight booking.
+   *
+   * Poll every few seconds until `terminal` is true. The poll is ALSO how LetsFG
+   * knows you are still there, which is what keeps a booking paused on a
+   * question alive — so do not back off to minutes.
+   *
+   * States: authorised, card_issued, booking_in_progress, awaiting_settlement,
+   * then completed (with `pnr` and `charged_amount`), failed (hold released,
+   * nothing charged) or needs_attention (a human at LetsFG is on it — do not
+   * book again).
+   */
+  async getBooking(bookingId) {
+    this.requireApiKey();
+    return this.getWithAuth(
+      `/developers/api/v1/flights/bookings/${encodeURIComponent(bookingId)}`
+    );
+  }
+  /**
+   * Answer the open `question` on a booking.
+   *
+   * Echo the question's `round`. A stale round is refused with 409 rather than
+   * guessed at, so an answer to an old question can never be applied to a new
+   * one. Seat: { seats: [...] } or { skip: true }. Price change or paid extra:
+   * { confirm: true } or { skip: true } — declining an extra still completes
+   * the booking, without it.
+   */
+  async answerBooking(bookingId, round, answer = {}) {
+    this.requireApiKey();
+    return this.post(
+      `/developers/api/v1/flights/bookings/${encodeURIComponent(bookingId)}/answer`,
+      { round, ...answer }
+    );
+  }
+  /**
+   * Book and poll to a terminal state. Mirrors bookHotelAndWait().
+   *
+   * Blocks for as long as the booking takes (4–11 minutes typically), so use
+   * book() + getBooking() instead if your caller has a request timeout.
+   *
+   * `onQuestion` returns the answer for answerBooking(). Without it, a fare
+   * increase is ACCEPTED and a paid extra is DECLINED — the conservative
+   * reading of "the traveller asked for this flight".
+   */
+  async bookAndWait(offerId, passengers, contactEmail, searchId, opts = {}) {
+    const { contactPhone = "", idempotencyKey = "", pollMs = 5e3, timeoutMs = 9e5, onQuestion } = opts;
+    const started = await this.book(
+      offerId,
+      passengers,
+      contactEmail,
+      contactPhone,
+      idempotencyKey,
+      searchId
+    );
+    if (!started || started.ok !== true) return started;
+    const bookingId = String(started.booking_id);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, pollMs));
+      const state = await this.getBooking(bookingId);
+      const question = state.question;
+      if (question) {
+        const answer = onQuestion ? onQuestion(question) : question.kind === "extra" ? { skip: true } : { confirm: true };
+        await this.answerBooking(bookingId, Number(question.round), answer);
+        continue;
+      }
+      if (state.terminal) return state;
+    }
+    return this.getBooking(bookingId);
   }
   // ── 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.
+  // A connected payment method 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
+  // method that authorises flight booking authorises hotels.
   //
-  // 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 5%-now/rest-later work. The result set is smaller than
-  // a metasearch's, and every row in it can actually be booked.
+  // How a hotel is paid (since 2026-09-11): the full `price` is HELD on the
+  // connected Revolut method, LetsFG books and pays the supplier itself, and the
+  // hold is captured only once the supplier has confirmed. A booking that fails
+  // releases the hold. There is no reservation fee, no deposit and no pay link —
+  // those belonged to the process retired on 2026-09-11. Every rate type is
+  // sold, refundable and non-refundable.
   /**
    * Resolve a place name to the city id that searchHotels() needs.
    *
@@ -1753,12 +1848,17 @@ var LetsFG = class {
    * 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 5% taken at booking), `balance_to_supplier`, `balance_due_by` and
-   * `free_cancellation_until`. There is no wholesale figure to quote by mistake.
+   * The response carries `session_id`, `currency`, `supplier_currency`,
+   * `markup_rate`, `fx_rate`, `fx_as_of`, `count`, `hotels`, `terms` and
+   * `caveats`. Each offer carries `price` (what the guest pays, in `currency`),
+   * `currency`, `fx_rate`, `expected_cost` (the supplier's cost, in PLN),
+   * `refundable`, `free_cancellation_until` (refundable rates only),
+   * `cancellation_policy` and its own `session_id`.
    *
-   * Keep `session_id` and the chosen offer's `combination_id_v2`: together they
-   * identify the exact rate, and booking needs both.
+   * `price` is the supplier's cost plus `markup_rate` (6.4% for Revolut Pay or an
+   * EEA-issued card, 8.3% for a card issued outside the EEA); nothing is added at
+   * booking. Keep the chosen offer whole: bookHotel() needs its `session_id`,
+   * `combination_id_v2`, `price`, `expected_cost`, `currency` and `fx_rate`.
    */
   async searchHotels(params) {
     this.requireApiKey();
@@ -1771,7 +1871,8 @@ var LetsFG = class {
       children: params.children ?? 0,
       nationality: params.nationality ?? "PL",
       limit: params.limit ?? 40,
-      with_images: params.withImages ?? true
+      with_images: params.withImages ?? true,
+      currency: params.currency ?? "USD"
     };
     if (params.childAges?.length) body.child_ages = params.childAges;
     return this.post("/developers/api/v1/hotels/search", body, 24e4);
@@ -1779,30 +1880,42 @@ var LetsFG = class {
   /**
    * 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 5% 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.
+   * What happens, in order: the offer's full `price` is HELD on the Revolut
+   * payment method connected to this account (authorised, not taken); LetsFG
+   * books the room with the supplier and pays the supplier itself; the hold is
+   * captured only once the supplier has confirmed. If the booking fails for any
+   * reason, the hold is released and nothing is charged. There is no
+   * reservation fee, no deposit and no pay link.
    *
-   * Because the fee is taken BEFORE the commit, a declined card costs nothing
-   * to unwind: no reservation exists and nothing is charged.
+   * A booking takes minutes and 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.
    *
-   * 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.
+   * Send `expectedPrice` (the offer's `price`), `expectedCost`, `currency` and
+   * `fxRate` exactly as search returned them. The booking is refused if the
+   * supplier's live cost is above `expectedCost`, and a USD offer sent without
+   * its `currency` is refused with 400 price_mismatch (the API assumes PLN).
+   * Guest names, phone and e-mail are checked before anything is held; a problem
+   * returns 400 invalid_details naming the fields.
    *
-   * Do NOT call this again for the same rate while a job is running: that books
-   * the room twice and charges two reservation fees.
+   * Do NOT call this again for a booking whose job is still running: poll it.
+   * A retry of the same booking returns the job already under way
+   * (`duplicate: true`) rather than holding the money twice.
    */
   async bookHotel(params) {
     this.requireApiKey();
+    if (typeof params.expectedCost !== "number") {
+      throw new LetsFGError(
+        "bookHotel() needs expectedCost: copy the offer's expected_cost, currency and fx_rate. " + ("expectedBalance" in params ? "expectedBalance belonged to the reservation-fee process retired on 2026-09-11 and is not sent. " : "") + "See https://letsfg.co/developers/api/docs",
+        400
+      );
+    }
     const body = {
       session_id: params.sessionId,
       hotel_code: params.hotelCode,
       combination_id_v2: params.combinationIdV2,
       expected_price: params.expectedPrice,
-      expected_balance: params.expectedBalance,
+      expected_cost: params.expectedCost,
       city_id: params.cityId,
       city_name: params.cityName,
       check_in: params.checkIn,
@@ -1814,16 +1927,30 @@ var LetsFG = class {
       phone_country_code: params.phoneCountryCode ?? "48",
       special_requests: params.specialRequests ?? []
     };
+    if (params.currency) body.currency = params.currency;
+    if (params.fxRate != null) body.fx_rate = params.fxRate;
     if (params.combinationId != null) body.combination_id = params.combinationId;
     if (params.hotelName) body.hotel_name = params.hotelName;
+    if (params.idempotencyKey) body.idempotency_key = params.idempotencyKey;
     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).
+   * `status` is 'in_progress', 'succeeded', 'failed' or 'attention'; the last
+   * three are final (HOTEL_BOOKING_FINAL_STATUSES).
+   *
+   * - succeeded: `confirmation`, `booking_id`, `hotel`, `room`, `total_price` +
+   *   `currency` (what the guest is charged), `supplier_paid` +
+   *   `supplier_currency` (what the supplier was paid), `payment_status`,
+   *   `refundable`, `free_cancellation_until`, `cancellation_ladder`, `terms`.
+   * - failed: `error`, written for the guest. The hold has been released and
+   *   nothing was charged.
+   * - attention: `error` (and `confirmation` when known). The outcome could not
+   *   be settled automatically; the hold is kept — nothing is charged — while a
+   *   person checks with the supplier. Do not book again.
+   *
+   * The guest is e-mailed in every case.
    */
   async hotelBooking(bookingJobId) {
     this.requireApiKey();
@@ -1835,13 +1962,15 @@ var LetsFG = class {
   /**
    * 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.
+   * Stops at 'succeeded', 'failed' or 'attention' and never re-books. Giving up
+   * after `maxWaitMs` (default 30 minutes: a booking usually takes 5-10, and
+   * hotel bookings run one at a time) does NOT cancel anything — the booking may
+   * still complete. The returned object carries `booking_job_id` so you can keep
+   * polling, and the guest is e-mailed the outcome regardless.
    */
   async bookHotelAndWait(params) {
     const pollIntervalMs = params.pollIntervalMs ?? 2e4;
-    const maxWaitMs = params.maxWaitMs ?? 6e5;
+    const maxWaitMs = params.maxWaitMs ?? 18e5;
     const job = await this.bookHotel(params);
     const jobId = job.booking_job_id;
     if (!jobId) return job;
@@ -1851,19 +1980,19 @@ var LetsFG = class {
       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 (HOTEL_BOOKING_FINAL_STATUSES.includes(result.status)) return result;
     }
     if (result.booking_job_id == null) result.booking_job_id = jobId;
     return result;
   }
   /**
-   * Release a reservation at the supplier.
+   * Release a reservation at the supplier and refund the guest.
    *
-   * 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 5% reservation fee is NOT
-   * refunded.
+   * Only this account's own bookings can be cancelled (anything else is 404). A
+   * zero-charge cancellation — a refundable rate before its
+   * `free_cancellation_until` — refunds the charge in full, or releases a hold
+   * not yet captured. A cancellation that would cost money is refused with 409;
+   * the hotel's own ladder is in the booking's `terms`.
    *
    * 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.
@@ -1877,15 +2006,37 @@ var LetsFG = class {
     );
   }
   /**
-   * [Developer API only] Attach a card to a PAID prepaid Developer API account.
+   * [Developer API] Mint a one-time link for connecting a Revolut payment method.
+   *
+   * This replaced setupPayment() on 2026-09-08. Nothing is charged to connect, and
+   * card details never touch LetsFG: the returned `connect_url` opens a hosted page
+   * where the developer saves a card, Revolut Pay or Google Pay. A PERSON must open
+   * it in a browser — there is no endpoint that takes card details, so do not ask a
+   * user for a card number and do not try to automate this step.
    *
-   * Most agents should NOT call this. It is unrelated to authenticating for
-   * search and booking — for that, run `letsfg auth`, which puts a card on file
-   * through a zero-amount setup and creates no billing account.
+   * Most agents should NOT need a Developer API account at all. To authenticate for
+   * search and booking, run `letsfg auth`, which creates no billing account.
    */
-  async setupPayment(token = "tok_visa") {
+  async connectPayment() {
     this.requireApiKey();
-    return this.post("/developers/api/v1/agents/setup-payment", { token });
+    return this.post("/developers/api/v1/agents/connect-payment", {});
+  }
+  /**
+   * RETIRED 2026-09-08 with Stripe. Throws instead of calling the server.
+   *
+   * `/agents/setup-payment` answers 410 Gone. Payment enrolment moved onto the same
+   * Revolut rail as the rest of the product: call connectPayment() and open the
+   * `connect_url` it returns.
+   *
+   * Kept as a method, and throwing locally rather than making the request, for the
+   * same reason as unlock() — an older caller gets one clear sentence at the line that
+   * is actually wrong, not a 410 body to decode and not a TypeError somewhere else.
+   */
+  async setupPayment(_token) {
+    throw new LetsFGError(
+      "setupPayment() was retired on 2026-09-08 with Stripe and the endpoint answers 410 Gone. Call connectPayment() instead and open the connect_url it returns; nothing is charged to connect. See https://letsfg.co/developers/api/docs",
+      410
+    );
   }
   /**
    * Get current agent profile and usage stats.
@@ -1994,6 +2145,7 @@ export {
   ValidationError,
   offerSummary,
   cheapestOffer,
+  HOTEL_BOOKING_FINAL_STATUSES,
   LetsFG,
   index_default,
   BoostedTravel,