letsfg 2026.5.73 → 2026.5.75

package/dist/index.d.mts

@@ -283,7 +283,7 @@ declare function getOfferDetailPromptNotes(offer: OfferDetailLike): string[];
  * const flights = await bt.search('GDN', 'BER', '2026-03-03');
  *
  * // Developer API (look-to-book search: 200 free after every booking)
- * const bt2 = new LetsFG({ apiKey: 'letsfg_...' });
+ * const bt2 = new LetsFG({ apiKey: process.env.LETSFG_API_KEY });
  * const flights2 = await bt2.search('LHR', 'JFK', '2026-04-15');
  * ```
  */
@@ -458,6 +458,12 @@ declare class ValidationError extends LetsFGError {
 declare function offerSummary(offer: FlightOffer): string;
 /** Get cheapest offer from search results */
 declare function cheapestOffer(result: FlightSearchResult): FlightOffer | null;
+/**
+ * Every hotel booking job status after which polling is pointless. `attention` is
+ * final for the caller too: a person settles it, and booking again would book twice.
+ */
+declare const HOTEL_BOOKING_FINAL_STATUSES: readonly ["succeeded", "failed", "attention"];
+type HotelBookingStatus = 'in_progress' | (typeof HOTEL_BOOKING_FINAL_STATUSES)[number];
 declare class LetsFG {
     private bearerToken;
     private apiKey;
@@ -587,12 +593,17 @@ declare class LetsFG {
      * 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`.
      */
     searchHotels(params: {
         cityId: number;
@@ -606,76 +617,113 @@ declare class LetsFG {
         nationality?: string;
         limit?: number;
         withImages?: boolean;
+        /** ISO code every `price` is quoted in. Default USD; PLN is the supplier's own. */
+        currency?: string;
     }): 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 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.
      */
     bookHotel(params: {
         sessionId: string;
         hotelCode: number;
         combinationIdV2: string;
+        /** The offer's `price`, verbatim. */
         expectedPrice: number;
-        expectedBalance: number;
+        /** The offer's `expected_cost` (the supplier's cost, PLN), verbatim. */
+        expectedCost: number;
+        /** The offer's `currency`. Copy it — omitted means PLN. */
+        currency?: string;
+        /** The offer's `fx_rate` (null for a PLN offer). */
+        fxRate?: number | null;
         cityId: number;
         cityName: string;
         checkIn: string;
         checkOut: string;
+        /**
+         * ONE entry per guest in the room, children included: adults first, then children in the
+         * `childAges` order used to search (the party travels with the offer's session). The hotel
+         * requires a name for every guest; fewer names than guests is refused before anything is
+         * submitted, and the hold is released.
+         */
         guests: Array<{
             title: string;
             first_name: string;
             last_name: string;
         }>;
-        /** The voucher and the pay link go here. A typo loses the booking. */
+        /** The guest's e-mail: the confirmation, or a note that it did not go through, goes here. */
         email: string;
         phone: string;
+        /** Adults in the room, as searched. */
         adults?: number;
         combinationId?: number;
         hotelName?: string;
         phoneCountryCode?: string;
         specialRequests?: string[];
+        /** Optional. A retry with the same key returns the booking already under way. */
+        idempotencyKey?: 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).
+     * `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.
      */
     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.
+     * 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.
      */
     bookHotelAndWait(params: Parameters<LetsFG['bookHotel']>[0] & {
         pollIntervalMs?: number;
         maxWaitMs?: number;
     }): Promise<Record<string, unknown>>;
     /**
-     * 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.
@@ -730,4 +778,4 @@ declare const BoostedTravel: typeof LetsFG;
 declare const BoostedTravelError: typeof LetsFGError;
 type BoostedTravelConfig = LetsFGConfig;
 
-export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, ErrorCategory, type ErrorCategoryType, ErrorCode, type ErrorCodeType, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, LetsFG, type LetsFGConfig, LetsFGError, type OfferDetailSignals, OfferExpiredError, type Passenger, PaymentRequiredError, type RankOffer, type RankedOffer, type RankingContext, type ScoreBreakdown, type SearchOptions, type StarlinkOfferVerdict, type StarlinkSegmentVerdict, TRIP_PURPOSES, type TripPurpose, type TripPurposeOptions, type UnlockResult, ValidationError, cheapestOffer, deduplicateOffers, LetsFG as default, extractOfferDetailSignals, getOfferDetailBadges, getOfferDetailPromptNotes, getPrimaryTripPurpose, getProfileLabel, normalizeTripPurposes, offerSummary, rankOffers, selectDiverseTop };
+export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, ErrorCategory, type ErrorCategoryType, ErrorCode, type ErrorCodeType, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, HOTEL_BOOKING_FINAL_STATUSES, type HotelBookingStatus, LetsFG, type LetsFGConfig, LetsFGError, type OfferDetailSignals, OfferExpiredError, type Passenger, PaymentRequiredError, type RankOffer, type RankedOffer, type RankingContext, type ScoreBreakdown, type SearchOptions, type StarlinkOfferVerdict, type StarlinkSegmentVerdict, TRIP_PURPOSES, type TripPurpose, type TripPurposeOptions, type UnlockResult, ValidationError, cheapestOffer, deduplicateOffers, LetsFG as default, extractOfferDetailSignals, getOfferDetailBadges, getOfferDetailPromptNotes, getPrimaryTripPurpose, getProfileLabel, normalizeTripPurposes, offerSummary, rankOffers, selectDiverseTop };

package/dist/index.d.ts

@@ -283,7 +283,7 @@ declare function getOfferDetailPromptNotes(offer: OfferDetailLike): string[];
  * const flights = await bt.search('GDN', 'BER', '2026-03-03');
  *
  * // Developer API (look-to-book search: 200 free after every booking)
- * const bt2 = new LetsFG({ apiKey: 'letsfg_...' });
+ * const bt2 = new LetsFG({ apiKey: process.env.LETSFG_API_KEY });
  * const flights2 = await bt2.search('LHR', 'JFK', '2026-04-15');
  * ```
  */
@@ -458,6 +458,12 @@ declare class ValidationError extends LetsFGError {
 declare function offerSummary(offer: FlightOffer): string;
 /** Get cheapest offer from search results */
 declare function cheapestOffer(result: FlightSearchResult): FlightOffer | null;
+/**
+ * Every hotel booking job status after which polling is pointless. `attention` is
+ * final for the caller too: a person settles it, and booking again would book twice.
+ */
+declare const HOTEL_BOOKING_FINAL_STATUSES: readonly ["succeeded", "failed", "attention"];
+type HotelBookingStatus = 'in_progress' | (typeof HOTEL_BOOKING_FINAL_STATUSES)[number];
 declare class LetsFG {
     private bearerToken;
     private apiKey;
@@ -587,12 +593,17 @@ declare class LetsFG {
      * 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`.
      */
     searchHotels(params: {
         cityId: number;
@@ -606,76 +617,113 @@ declare class LetsFG {
         nationality?: string;
         limit?: number;
         withImages?: boolean;
+        /** ISO code every `price` is quoted in. Default USD; PLN is the supplier's own. */
+        currency?: string;
     }): 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 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.
      */
     bookHotel(params: {
         sessionId: string;
         hotelCode: number;
         combinationIdV2: string;
+        /** The offer's `price`, verbatim. */
         expectedPrice: number;
-        expectedBalance: number;
+        /** The offer's `expected_cost` (the supplier's cost, PLN), verbatim. */
+        expectedCost: number;
+        /** The offer's `currency`. Copy it — omitted means PLN. */
+        currency?: string;
+        /** The offer's `fx_rate` (null for a PLN offer). */
+        fxRate?: number | null;
         cityId: number;
         cityName: string;
         checkIn: string;
         checkOut: string;
+        /**
+         * ONE entry per guest in the room, children included: adults first, then children in the
+         * `childAges` order used to search (the party travels with the offer's session). The hotel
+         * requires a name for every guest; fewer names than guests is refused before anything is
+         * submitted, and the hold is released.
+         */
         guests: Array<{
             title: string;
             first_name: string;
             last_name: string;
         }>;
-        /** The voucher and the pay link go here. A typo loses the booking. */
+        /** The guest's e-mail: the confirmation, or a note that it did not go through, goes here. */
         email: string;
         phone: string;
+        /** Adults in the room, as searched. */
         adults?: number;
         combinationId?: number;
         hotelName?: string;
         phoneCountryCode?: string;
         specialRequests?: string[];
+        /** Optional. A retry with the same key returns the booking already under way. */
+        idempotencyKey?: 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).
+     * `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.
      */
     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.
+     * 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.
      */
     bookHotelAndWait(params: Parameters<LetsFG['bookHotel']>[0] & {
         pollIntervalMs?: number;
         maxWaitMs?: number;
     }): Promise<Record<string, unknown>>;
     /**
-     * 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.
@@ -730,4 +778,4 @@ declare const BoostedTravel: typeof LetsFG;
 declare const BoostedTravelError: typeof LetsFGError;
 type BoostedTravelConfig = LetsFGConfig;
 
-export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, ErrorCategory, type ErrorCategoryType, ErrorCode, type ErrorCodeType, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, LetsFG, type LetsFGConfig, LetsFGError, type OfferDetailSignals, OfferExpiredError, type Passenger, PaymentRequiredError, type RankOffer, type RankedOffer, type RankingContext, type ScoreBreakdown, type SearchOptions, type StarlinkOfferVerdict, type StarlinkSegmentVerdict, TRIP_PURPOSES, type TripPurpose, type TripPurposeOptions, type UnlockResult, ValidationError, cheapestOffer, deduplicateOffers, LetsFG as default, extractOfferDetailSignals, getOfferDetailBadges, getOfferDetailPromptNotes, getPrimaryTripPurpose, getProfileLabel, normalizeTripPurposes, offerSummary, rankOffers, selectDiverseTop };
+export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, ErrorCategory, type ErrorCategoryType, ErrorCode, type ErrorCodeType, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, HOTEL_BOOKING_FINAL_STATUSES, type HotelBookingStatus, LetsFG, type LetsFGConfig, LetsFGError, type OfferDetailSignals, OfferExpiredError, type Passenger, PaymentRequiredError, type RankOffer, type RankedOffer, type RankingContext, type ScoreBreakdown, type SearchOptions, type StarlinkOfferVerdict, type StarlinkSegmentVerdict, TRIP_PURPOSES, type TripPurpose, type TripPurposeOptions, type UnlockResult, ValidationError, cheapestOffer, deduplicateOffers, LetsFG as default, extractOfferDetailSignals, getOfferDetailBadges, getOfferDetailPromptNotes, getPrimaryTripPurpose, getProfileLabel, normalizeTripPurposes, offerSummary, rankOffers, selectDiverseTop };