letsfg 2026.5.72 → 2026.5.73

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

@@ -1671,13 +1671,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 +1698,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,15 +1726,92 @@ 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 ──────────────────────────────────────────────────────────
   //
@@ -1877,15 +1969,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.

package/dist/cli.js

@@ -427,13 +427,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.
@@ -444,9 +454,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();
@@ -467,15 +482,92 @@ 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 ──────────────────────────────────────────────────────────
   //
@@ -633,15 +725,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.
@@ -1051,38 +1165,15 @@ async function cmdSearch(args) {
 `);
   } else {
     console.log(`
-  To unlock: letsfg unlock <offer_id>`);
-    console.log(`  Passenger IDs needed for booking: ${JSON.stringify(result.passenger_ids)}
+  To book: letsfg book <offer_id> --search-id ${result.search_id} --passenger '{...}' --email you@example.com
 `);
   }
 }
-async function cmdUnlock(args) {
-  const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
-  const apiKey = getFlag(args, "--api-key", "-k");
-  const baseUrl = getFlag(args, "--base-url");
-  const offerId = args[0];
-  if (!offerId) {
-    console.error("Usage: letsfg unlock <offer_id>");
-    process.exit(1);
-  }
-  const bt = new LetsFG({ apiKey, baseUrl });
-  const result = await bt.unlock(offerId);
-  if (jsonOut) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  if (result.unlock_status === "unlocked") {
-    console.log(`
-  \u2713 Offer unlocked!`);
-    console.log(`    Confirmed price: ${result.confirmed_currency} ${result.confirmed_price?.toFixed(2)}`);
-    console.log(`    Expires at: ${result.offer_expires_at}`);
-    console.log(`
-    Next: letsfg book ${offerId} --passenger '{...}' --email you@example.com
-`);
-  } else {
-    console.error(`  \u2717 Unlock failed: ${result.message}`);
-    process.exit(1);
-  }
+async function cmdUnlock(_args) {
+  console.error(
+    "\n  letsfg unlock was retired on 2026-09-08 and the endpoint answers 410 Gone.\n\n  There is no unlock step any more. Book directly:\n    letsfg book <offer_id> --search-id <search_id> --passenger '{...}' --email you@example.com\n\n  The fare is HELD on your connected payment method and captured only once a real\n  airline PNR exists, which is what unlock existed to protect against. If the fare moves\n  at checkout you are asked to accept or decline it.\n"
+  );
+  process.exit(1);
 }
 async function cmdBook(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
@@ -1214,19 +1305,26 @@ async function cmdSetupPayment(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
   const apiKey = getFlag(args, "--api-key", "-k");
   const baseUrl = getFlag(args, "--base-url");
-  const token = getFlag(args, "--token", "-t") || "tok_visa";
+  if (getFlag(args, "--token", "-t")) {
+    console.log("\n  Note: --token was part of the Stripe enrolment, retired 2026-09-08. Ignoring it.");
+  }
   const bt = new LetsFG({ apiKey, baseUrl });
-  const result = await bt.setupPayment(token);
+  const result = await bt.connectPayment();
   if (jsonOut) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
-  if (result.status === "ready") {
+  const url = result.connect_url;
+  if (url) {
     console.log(`
-  \u2713 Payment ready! You can now unlock offers and book flights.
+  Open this in a browser to connect a payment method:
+`);
+    console.log(`    ${url}
+`);
+    console.log(`    Nothing is charged. Run \`letsfg me\` afterwards to confirm it landed.
 `);
   } else {
-    console.error(`  \u2717 Payment setup failed: ${result.message || result.status}`);
+    console.error(`  \u2717 Could not mint a connect link: ${result.message || result.status}`);
     process.exit(1);
   }
 }
@@ -1247,10 +1345,9 @@ async function cmdMe(args) {
   console.log(`  Email: ${p.email}`);
   console.log(`  Tier:  ${p.tier}`);
   const access = p.access_granted || false;
-  console.log(`  Access:  ${access ? "\u2713 Granted (search, unlock, book)" : "\u2717 Not granted"}`);
+  console.log(`  Access:  ${access ? "\u2713 Granted (search, book)" : "\u2717 Not granted"}`);
   console.log(`  Payment: ${p.payment_ready ? "\u2713 Ready" : "\u2014"}`);
   console.log(`  Searches: ${u.total_searches || 0}`);
-  console.log(`  Unlocks:  ${u.total_unlocks || 0}`);
   console.log(`  Bookings: ${u.total_bookings || 0}`);
   console.log(`  Total spent: $${((u.total_spent_cents || 0) / 100).toFixed(2)}
 `);
@@ -1267,14 +1364,15 @@ Commands:
   auth                             Connect a card at letsfg.co/connect. Nothing charged
   search <origin> <dest> <date>    Search for flights (free), prints search_id
   locations <query>                Resolve city name to IATA codes
-  book <offer_id> --search-id ...  Book a flight. No LetsFG fee, no unlock step
+  book <offer_id> --search-id ...  Book a flight. No booking or transaction fee, no unlock step
   me                               Show agent profile
 
 Developer API only (a SEPARATE paid product \u2014 most agents should not use these;
 they create a billing account. Use auth above instead):
   register --name ... --email ... Create a paid Developer API account
-  setup-payment                   Attach a card to that paid account
-  unlock <offer_id>               [Developer API only] Unlock offer (legacy)
+  connect-payment                 Print a link to connect a card to that paid account
+  setup-payment                   Alias of connect-payment (the Stripe lane retired 2026-09-08)
+  unlock <offer_id>               RETIRED 2026-09-08 \u2014 no unlock step, book directly
 
 Options:
   --json, -j          Output raw JSON
@@ -1310,6 +1408,7 @@ async function main() {
       case "register":
         await cmdRegister(args);
         break;
+      case "connect-payment":
       case "setup-payment":
         await cmdSetupPayment(args);
         break;

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   LetsFG,
   LetsFGError,
   offerSummary
-} from "./chunk-GO3FXQXC.mjs";
+} from "./chunk-F5BBI6XX.mjs";
 
 // src/auth.ts
 import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from "fs";
@@ -329,38 +329,15 @@ async function cmdSearch(args) {
 `);
   } else {
     console.log(`
-  To unlock: letsfg unlock <offer_id>`);
-    console.log(`  Passenger IDs needed for booking: ${JSON.stringify(result.passenger_ids)}
+  To book: letsfg book <offer_id> --search-id ${result.search_id} --passenger '{...}' --email you@example.com
 `);
   }
 }
-async function cmdUnlock(args) {
-  const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
-  const apiKey = getFlag(args, "--api-key", "-k");
-  const baseUrl = getFlag(args, "--base-url");
-  const offerId = args[0];
-  if (!offerId) {
-    console.error("Usage: letsfg unlock <offer_id>");
-    process.exit(1);
-  }
-  const bt = new LetsFG({ apiKey, baseUrl });
-  const result = await bt.unlock(offerId);
-  if (jsonOut) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  if (result.unlock_status === "unlocked") {
-    console.log(`
-  \u2713 Offer unlocked!`);
-    console.log(`    Confirmed price: ${result.confirmed_currency} ${result.confirmed_price?.toFixed(2)}`);
-    console.log(`    Expires at: ${result.offer_expires_at}`);
-    console.log(`
-    Next: letsfg book ${offerId} --passenger '{...}' --email you@example.com
-`);
-  } else {
-    console.error(`  \u2717 Unlock failed: ${result.message}`);
-    process.exit(1);
-  }
+async function cmdUnlock(_args) {
+  console.error(
+    "\n  letsfg unlock was retired on 2026-09-08 and the endpoint answers 410 Gone.\n\n  There is no unlock step any more. Book directly:\n    letsfg book <offer_id> --search-id <search_id> --passenger '{...}' --email you@example.com\n\n  The fare is HELD on your connected payment method and captured only once a real\n  airline PNR exists, which is what unlock existed to protect against. If the fare moves\n  at checkout you are asked to accept or decline it.\n"
+  );
+  process.exit(1);
 }
 async function cmdBook(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
@@ -492,19 +469,26 @@ async function cmdSetupPayment(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
   const apiKey = getFlag(args, "--api-key", "-k");
   const baseUrl = getFlag(args, "--base-url");
-  const token = getFlag(args, "--token", "-t") || "tok_visa";
+  if (getFlag(args, "--token", "-t")) {
+    console.log("\n  Note: --token was part of the Stripe enrolment, retired 2026-09-08. Ignoring it.");
+  }
   const bt = new LetsFG({ apiKey, baseUrl });
-  const result = await bt.setupPayment(token);
+  const result = await bt.connectPayment();
   if (jsonOut) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
-  if (result.status === "ready") {
+  const url = result.connect_url;
+  if (url) {
     console.log(`
-  \u2713 Payment ready! You can now unlock offers and book flights.
+  Open this in a browser to connect a payment method:
+`);
+    console.log(`    ${url}
+`);
+    console.log(`    Nothing is charged. Run \`letsfg me\` afterwards to confirm it landed.
 `);
   } else {
-    console.error(`  \u2717 Payment setup failed: ${result.message || result.status}`);
+    console.error(`  \u2717 Could not mint a connect link: ${result.message || result.status}`);
     process.exit(1);
   }
 }
@@ -525,10 +509,9 @@ async function cmdMe(args) {
   console.log(`  Email: ${p.email}`);
   console.log(`  Tier:  ${p.tier}`);
   const access = p.access_granted || false;
-  console.log(`  Access:  ${access ? "\u2713 Granted (search, unlock, book)" : "\u2717 Not granted"}`);
+  console.log(`  Access:  ${access ? "\u2713 Granted (search, book)" : "\u2717 Not granted"}`);
   console.log(`  Payment: ${p.payment_ready ? "\u2713 Ready" : "\u2014"}`);
   console.log(`  Searches: ${u.total_searches || 0}`);
-  console.log(`  Unlocks:  ${u.total_unlocks || 0}`);
   console.log(`  Bookings: ${u.total_bookings || 0}`);
   console.log(`  Total spent: $${((u.total_spent_cents || 0) / 100).toFixed(2)}
 `);
@@ -545,14 +528,15 @@ Commands:
   auth                             Connect a card at letsfg.co/connect. Nothing charged
   search <origin> <dest> <date>    Search for flights (free), prints search_id
   locations <query>                Resolve city name to IATA codes
-  book <offer_id> --search-id ...  Book a flight. No LetsFG fee, no unlock step
+  book <offer_id> --search-id ...  Book a flight. No booking or transaction fee, no unlock step
   me                               Show agent profile
 
 Developer API only (a SEPARATE paid product \u2014 most agents should not use these;
 they create a billing account. Use auth above instead):
   register --name ... --email ... Create a paid Developer API account
-  setup-payment                   Attach a card to that paid account
-  unlock <offer_id>               [Developer API only] Unlock offer (legacy)
+  connect-payment                 Print a link to connect a card to that paid account
+  setup-payment                   Alias of connect-payment (the Stripe lane retired 2026-09-08)
+  unlock <offer_id>               RETIRED 2026-09-08 \u2014 no unlock step, book directly
 
 Options:
   --json, -j          Output raw JSON
@@ -588,6 +572,7 @@ async function main() {
       case "register":
         await cmdRegister(args);
         break;
+      case "connect-payment":
       case "setup-payment":
         await cmdSetupPayment(args);
         break;