letsfg 2026.5.72 → 2026.5.74

package/dist/index.d.ts

@@ -282,8 +282,8 @@ declare function getOfferDetailPromptNotes(offer: OfferDetailLike): string[];
  * const bt = new LetsFG({ bearerToken: process.env.LETSFG_BEARER_TOKEN });
  * const flights = await bt.search('GDN', 'BER', '2026-03-03');
  *
- * // Developer API (prepaid credits)
- * const bt2 = new LetsFG({ apiKey: 'letsfg_...' });
+ * // Developer API (look-to-book search: 200 free after every booking)
+ * const bt2 = new LetsFG({ apiKey: process.env.LETSFG_API_KEY });
  * const flights2 = await bt2.search('LHR', 'JFK', '2026-04-15');
  * ```
  */
@@ -402,7 +402,7 @@ interface SearchOptions {
 interface LetsFGConfig {
     /** PFS Bearer token from `letsfg auth`. Enables free search via POST /api/search polling. */
     bearerToken?: string;
-    /** Developer API key (prepaid credits, no per-booking fee). */
+    /** Developer API key. Look-to-book search; no booking fee, no transaction fee. */
     apiKey?: string;
     baseUrl?: string;
     timeout?: number;
@@ -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;
@@ -495,11 +501,19 @@ declare class LetsFG {
      */
     resolveLocation(query: string): Promise<Array<Record<string, unknown>>>;
     /**
-     * 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.
      */
-    unlock(offerId: string): Promise<UnlockResult>;
+    unlock(_offerId: string): Promise<UnlockResult>;
     /**
      * Book a flight.
      *
@@ -509,11 +523,64 @@ declare class LetsFG {
      * 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.
      */
     book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string, searchId?: string): Promise<BookingResult | Record<string, unknown>>;
+    /**
+     * 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).
+     */
+    getBooking(bookingId: string): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    answerBooking(bookingId: string, round: number, answer?: {
+        seats?: Array<Record<string, unknown>>;
+        confirm?: boolean;
+        skip?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * 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".
+     */
+    bookAndWait(offerId: string, passengers: Passenger[], contactEmail: string, searchId: string, opts?: {
+        contactPhone?: string;
+        idempotencyKey?: string;
+        pollMs?: number;
+        timeoutMs?: number;
+        onQuestion?: (q: Record<string, unknown>) => {
+            seats?: Array<Record<string, unknown>>;
+            confirm?: boolean;
+            skip?: boolean;
+        };
+    }): Promise<Record<string, unknown>>;
     /**
      * Resolve a place name to the city id that searchHotels() needs.
      *
@@ -526,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;
@@ -545,89 +617,143 @@ 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.
      */
     cancelHotel(confirmation: string): Promise<Record<string, unknown>>;
     /**
-     * [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 need a Developer API account at all. To authenticate for
+     * search and booking, run `letsfg auth`, which creates no billing account.
+     */
+    connectPayment(): Promise<Record<string, unknown>>;
+    /**
+     * 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.
      *
-     * 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.
+     * 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.
      */
-    setupPayment(token?: string): Promise<Record<string, unknown>>;
+    setupPayment(_token?: string): Promise<Record<string, unknown>>;
     /**
      * Get current agent profile and usage stats.
      */
@@ -652,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 };