letsfg 2026.5.73 → 2026.5.75

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   BoostedTravelError: () => BoostedTravelError,
   ErrorCategory: () => ErrorCategory,
   ErrorCode: () => ErrorCode,
+  HOTEL_BOOKING_FINAL_STATUSES: () => HOTEL_BOOKING_FINAL_STATUSES,
   LetsFG: () => LetsFG,
   LetsFGError: () => LetsFGError,
   OfferExpiredError: () => OfferExpiredError,
@@ -1612,6 +1613,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;
@@ -1665,15 +1667,23 @@ var LetsFG = class {
       currency: options.currency ?? "EUR",
       limit: options.limit ?? 50
     };
-    if (options.returnDate) body.return_date = options.returnDate;
-    if (options.cabinClass) body.cabin_class = options.cabinClass;
-    if (options.maxStopovers != null) body.max_stopovers = options.maxStopovers;
-    if (options.sort) body.sort = options.sort;
     if (options.departureTimeFrom) body.departure_time_from = options.departureTimeFrom;
     if (options.departureTimeTo) body.departure_time_to = options.departureTimeTo;
     if (this.usingPFS) {
-      return this.searchPFS(body);
+      if (options.returnDate) body.return_date = options.returnDate;
+      if (options.cabinClass) body.cabin = options.cabinClass;
+      if (options.maxStopovers != null) body.max_stops = options.maxStopovers;
+      if (options.sort) body.sort_by = options.sort;
+      const result = await this.searchPFS(body);
+      if (options.limit != null && Array.isArray(result.offers)) {
+        result.offers = result.offers.slice(0, Math.max(0, options.limit));
+      }
+      return result;
     }
+    if (options.returnDate) body.return_from = options.returnDate;
+    if (options.cabinClass) body.cabin_class = options.cabinClass;
+    if (options.maxStopovers != null) body.max_stopovers = options.maxStopovers;
+    if (options.sort) body.sort = options.sort;
     return this.post("/developers/api/v1/flights/search", body);
   }
   /** PFS path: POST /api/search -> poll /api/results/<id> */
@@ -1863,16 +1873,18 @@ var LetsFG = class {
   }
   // ── 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.
    *
@@ -1893,12 +1905,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();
@@ -1911,7 +1928,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);
@@ -1919,30 +1937,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,
@@ -1954,16 +1984,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();
@@ -1975,13 +2019,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;
@@ -1991,19 +2037,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.
@@ -2142,6 +2188,7 @@ var BoostedTravelError = LetsFGError;
   BoostedTravelError,
   ErrorCategory,
   ErrorCode,
+  HOTEL_BOOKING_FINAL_STATUSES,
   LetsFG,
   LetsFGError,
   OfferExpiredError,

package/dist/index.mjs

@@ -4,6 +4,7 @@ import {
   BoostedTravelError,
   ErrorCategory,
   ErrorCode,
+  HOTEL_BOOKING_FINAL_STATUSES,
   LetsFG,
   LetsFGError,
   OfferExpiredError,
@@ -22,13 +23,14 @@ import {
   offerSummary,
   rankOffers,
   selectDiverseTop
-} from "./chunk-F5BBI6XX.mjs";
+} from "./chunk-6IWYHW62.mjs";
 export {
   AuthenticationError,
   BoostedTravel,
   BoostedTravelError,
   ErrorCategory,
   ErrorCode,
+  HOTEL_BOOKING_FINAL_STATUSES,
   LetsFG,
   LetsFGError,
   OfferExpiredError,

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "letsfg",
-  "version": "2026.5.73",
-  "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 src/auth.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"
-  }
-}
+{
+  "name": "letsfg",
+  "version": "2026.5.75",
+  "description": "Flights and hotels for AI agents. Server-side engine covers hundreds of airlines; hotels are real bookable inventory with pay-later terms, and every rate says whether it is refundable. 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 src/auth.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"
+  }
+}