letsfg 2026.5.71 → 2026.5.72

package/README.md

@@ -9,10 +9,10 @@
 
 | | **CLI / SDK** (this package) | **Developer API** |
 |---|---|---|
-| **Search cost** | Free (Bearer token via `letsfg auth` — zero-amount card setup) | Prepaid credits |
-| **Booking** | `POST /api/agent-book` — confirmed order or a booking link, no LetsFG fee | Direct airline URL (unlock required first) |
+| **Search cost** | Free (card-backed token from [letsfg.co/connect](https://letsfg.co/connect), nothing charged) | Prepaid credits |
+| **Booking** | `POST /api/agent-book` — fare held on your card, a LetsFG agent buys the ticket, captured only on a real PNR. Every offer. | Direct airline URL (unlock required first) |
 | **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 `letsfg auth` | [letsfg.co/developers](https://letsfg.co/developers) |
+| **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.
 
@@ -22,13 +22,31 @@
 npm install letsfg
 ```
 
+## Getting a token
+
+Connect LetsFG as an MCP server at `https://letsfg.co/developers/api/mcp` and
+approve the connection — in Claude, ChatGPT, Cursor, Windsurf, or Claude Code
+(`claude mcp add --transport http letsfg https://letsfg.co/developers/api/mcp`).
+The consent step opens [letsfg.co/connect](https://letsfg.co/connect), where you
+add a card (any card, or Revolut Pay / Google Pay) in a 0.00 Revolut setup.
+Nothing is charged, no Revolut account is needed, and the card details go to
+Revolut, never to LetsFG. The token you get back is card-backed: it searches
+and it books. One card = one account; quotas are per card (10 searches per
+10 min, 30 per hour, 100 per day — polling never counts).
+
+Pass it as `bearerToken`, or set `LETSFG_BEARER_TOKEN` for the CLI.
+
+> `letsfg auth` still runs the Stripe card setup that was retired on
+> 2026-09-02 and cannot get a token today; every token issued that way was
+> revoked (401 `TOKEN_REVOKED`). A connect-flow login for the CLI and SDKs is
+> coming — until then, connect through the MCP.
+
 ## Quick Start (SDK)
 
 ```typescript
 import { LetsFG, cheapestOffer, offerSummary } from 'letsfg';
 
-// PFS — free. Get a Bearer token once with `letsfg auth` (zero-amount card
-// setup, nothing charged), then pass it here.
+// PFS — free. The card-backed token from the connect flow (see above).
 const bt = new LetsFG({ bearerToken: 'eyJ...' });
 
 // Search — FREE
@@ -36,22 +54,62 @@ const flights = await bt.search('GDN', 'BER', '2026-03-03');
 const best = cheapestOffer(flights);
 console.log(offerSummary(best));
 
-// Book — free, ticket price only, no LetsFG fee. No unlock step.
+// Book — ticket price only, no LetsFG fee, 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,
-  [{ given_name: 'John', family_name: 'Doe', born_on: '1990-01-15', gender: 'm' }],
+  [{
+    given_name: 'John', family_name: 'Doe', born_on: '1990-01-15', gender: 'm',
+    nationality: 'GB', phone_number: '+447700900123', phone_country: 'GB',
+    address_line1: '1 Analytical Way', address_city: 'London',
+    address_postal: 'N1 9GU', address_country: 'GB',
+  }],
   'john@example.com',
   '',
   '',
   flights.search_id,
 );
-if (result.booked) {
-  console.log(`Order: ${result.order_id}`);
-} else {
-  console.log(`Booking link (nothing charged): ${result.booking_url}`);
-}
+const bookingRef = result.booking_ref as string;
+
+// Poll until it lands (every 20-30 s): completed | failed | needs_attention
+let status: Record<string, unknown>;
+do {
+  await new Promise(r => setTimeout(r, 25_000));
+  status = await (await fetch('https://letsfg.co/api/agent-book/status', {
+    method: 'POST',
+    headers: { Authorization: 'Bearer eyJ...', 'Content-Type': 'application/json' },
+    body: JSON.stringify({ booking_ref: bookingRef }),
+  })).json();
+} while (status.state === 'booking_in_progress');
+console.log(status); // { state: 'completed', pnr: 'ABC123', charged_amount: 93, currency: 'EUR' }
 ```
 
+### How booking works
+
+`bt.book()` posts to `POST /api/agent-book` and does exactly what the website
+checkout does: the fare plus LetsFG's markup is **held** on the connected card
+(not taken), a LetsFG booking agent buys the ticket from the seller, and the
+hold is captured only once a real airline PNR exists. If the booking fails the
+hold is released and nothing is charged. Every offer can be booked this way —
+no unlock step, no booking-link fallback, no separate LetsFG fee.
+
+The call returns within seconds with a `booking_ref`; the booking itself takes
+4–11 minutes. Poll `POST /api/agent-book/status` with `{"booking_ref": ...}`
+every 20–30 s (the SDK has no helper for this yet):
+
+| `state` | Meaning |
+|---|---|
+| `booking_in_progress` | the agent is at the seller's checkout — keep waiting |
+| `completed` | booked — `pnr`, `charged_amount`, `currency` are in the answer |
+| `failed` | not booked — the hold was released, nothing charged; see `failure_reason` |
+| `needs_attention` | a human at LetsFG is checking it — do **not** book again |
+
+One traveller per call, with the details an airline checkout asks for: name,
+date of birth, gender, nationality, email, phone with its country, residence
+address (passport optional). A missing detail returns `missing_details` with
+`missing_fields` and charges nothing. Never start a second booking for the
+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()`.
@@ -59,11 +117,12 @@ Prefer the paid Developer API instead? Pass `apiKey` instead of `bearerToken`
 ## Quick Start (CLI)
 
 ```bash
-export LETSFG_BEARER_TOKEN=<your-bearer-token>  # from `letsfg auth`
+export LETSFG_BEARER_TOKEN=<your-bearer-token>  # card-backed, from the connect flow
 
 letsfg search GDN BER 2026-03-03 --sort price
 letsfg search LON BCN 2026-04-01 --json  # Machine-readable
-letsfg book off_xxx --search-id srch_xxx -p '{"given_name":"John","family_name":"Doe","born_on":"1990-01-15","gender":"m"}' -e john@example.com
+letsfg book off_xxx --search-id srch_xxx -p '{"given_name":"John","family_name":"Doe","born_on":"1990-01-15","gender":"m","nationality":"GB","phone_number":"+447700900123","phone_country":"GB","address_line1":"1 Analytical Way","address_city":"London","address_postal":"N1 9GU","address_country":"GB"}' -e john@example.com
+# prints the booking_ref — poll POST /api/agent-book/status until completed
 ```
 
 ## API
@@ -74,8 +133,9 @@ letsfg book off_xxx --search-id srch_xxx -p '{"given_name":"John","family_name":
 ### `bt.resolveLocation(query)`
 ### `bt.unlock(offerId)` — Developer API only
 ### `bt.book(offerId, passengers, contactEmail, contactPhone?, idempotencyKey?, searchId?)`
-Dispatches on which credential is set: `bearerToken` → free PFS booking via
-`POST /api/agent-book` (pass `searchId`, one passenger). `apiKey` → paid
+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
@@ -118,7 +178,7 @@ MIT
 
 ## 🏨 Hotels — new, and live
 
-Your agent can now book hotels, not just flights. Same API key, same card on file.
+Your agent can book hotels as well as flights. Same card-backed token or API key, same card on file.
 
 ```python
 from letsfg import LetsFG

package/dist/cli.js

@@ -6,13 +6,6 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -30,139 +23,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// src/auth.ts
-var auth_exports = {};
-__export(auth_exports, {
-  BearerTokenError: () => BearerTokenError,
-  getBearerToken: () => getBearerToken,
-  paymentAuth: () => paymentAuth,
-  requestEnrolment: () => requestEnrolment,
-  saveToken: () => saveToken,
-  verifyPaymentMethod: () => verifyPaymentMethod
-});
-function configPath() {
-  const base = (0, import_node_os.platform)() === "win32" ? process.env.APPDATA || (0, import_node_os.homedir)() : (0, import_node_os.homedir)();
-  return (0, import_node_path.join)(base, ".letsfg", "config.json");
-}
-function loadConfig() {
-  const p = configPath();
-  if (!(0, import_node_fs.existsSync)(p)) return {};
-  try {
-    return JSON.parse((0, import_node_fs.readFileSync)(p, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-function saveConfig(cfg) {
-  const p = configPath();
-  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(p), { recursive: true });
-  (0, import_node_fs.writeFileSync)(p, JSON.stringify(cfg, null, 2));
-  try {
-    (0, import_node_fs.chmodSync)(p, 384);
-  } catch {
-  }
-}
-function getBearerToken() {
-  const env = process.env.LETSFG_BEARER_TOKEN;
-  if (env) return env;
-  const auth = loadConfig().pfs_auth;
-  if (auth?.token && Date.now() < auth.expires_at - 36e5) {
-    return auth.token;
-  }
-  throw new BearerTokenError(
-    "No valid LetsFG Bearer token.\n  Run:  letsfg auth        (adds a payment method \u2014 nothing is charged)\n  Or:   export LETSFG_BEARER_TOKEN=<token>"
-  );
-}
-function saveToken(token, expiresAt) {
-  const cfg = loadConfig();
-  cfg.pfs_auth = { token, expires_at: expiresAt ?? Date.now() + TOKEN_TTL_MS };
-  saveConfig(cfg);
-}
-async function postJson(path, payload) {
-  const resp = await fetch(`${BASE_URL}${path}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", "User-Agent": "LetsFG-js/0.1.0", "X-Client-Type": "js-sdk" },
-    body: JSON.stringify(payload)
-  });
-  const data = await resp.json().catch(() => ({}));
-  return { status: resp.status, data };
-}
-function parseExpiry(raw) {
-  if (typeof raw === "number") return raw * 1e3;
-  if (typeof raw === "string") {
-    const ms = Date.parse(raw);
-    if (!Number.isNaN(ms)) return ms;
-  }
-  return Date.now() + TOKEN_TTL_MS;
-}
-async function requestEnrolment() {
-  const { status, data } = await postJson("/api/agent-access/request", {});
-  if (status !== 200 && status !== 402) {
-    throw new BearerTokenError(`Could not start authentication (HTTP ${status}): ${data.error || ""}`);
-  }
-  return data;
-}
-async function verifyPaymentMethod(opts) {
-  const payload = {};
-  if (opts.setupSessionId) payload.setup_session_id = opts.setupSessionId;
-  else if (opts.paymentMethodId) payload.payment_method_id = opts.paymentMethodId;
-  else if (opts.cardToken) payload.card_token = opts.cardToken;
-  else throw new BearerTokenError("Provide one of setupSessionId, paymentMethodId, or cardToken.");
-  const { status, data } = await postJson("/api/agent-access/verify", payload);
-  if (status !== 200 || !data.token) {
-    throw new BearerTokenError(`Verification failed (HTTP ${status}). ${data.hint || data.error || ""}`.trim());
-  }
-  const token = data.token;
-  saveToken(token, parseExpiry(data.expires_at));
-  return token;
-}
-function openBrowser(url) {
-  import("child_process").then(({ exec }) => {
-    const cmd = (0, import_node_os.platform)() === "win32" ? `start "" "${url}"` : (0, import_node_os.platform)() === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
-    exec(cmd, () => {
-    });
-  }).catch(() => {
-  });
-}
-async function paymentAuth(openBrowserFlag = true) {
-  console.log("\n  Connecting to LetsFG...");
-  const data = await requestEnrolment();
-  const setupUrl = data.setup_url;
-  const sessionId = data.setup_session_id;
-  if (!setupUrl || !sessionId) {
-    throw new BearerTokenError("Server did not return a setup URL. Check https://letsfg.co/for-agents");
-  }
-  console.log("\n  LetsFG needs a payment method on file before it can search or book.");
-  console.log("  Nothing is charged now \u2014 this is a zero-amount card setup.\n");
-  console.log("  Step 1 \u2014 add a card here:\n");
-  console.log(`     ${setupUrl}
-`);
-  if (openBrowserFlag) openBrowser(setupUrl);
-  console.log("  Step 2 \u2014 press Enter once you've finished.");
-  const readline = await import("readline/promises");
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  await rl.question("");
-  rl.close();
-  process.stdout.write("  Verifying... ");
-  const token = await verifyPaymentMethod({ setupSessionId: sessionId });
-  const expiresAt = loadConfig().pfs_auth?.expires_at ?? Date.now() + TOKEN_TTL_MS;
-  console.log(`done. Token valid until ${new Date(expiresAt).toISOString().slice(0, 10)}.`);
-  return token;
-}
-var import_node_fs, import_node_os, import_node_path, BASE_URL, TOKEN_TTL_MS, BearerTokenError;
-var init_auth = __esm({
-  "src/auth.ts"() {
-    "use strict";
-    import_node_fs = require("fs");
-    import_node_os = require("os");
-    import_node_path = require("path");
-    BASE_URL = process.env.LETSFG_BASE_URL || "https://letsfg.co";
-    TOKEN_TTL_MS = 90 * 24 * 3600 * 1e3;
-    BearerTokenError = class extends Error {
-    };
-  }
-});
-
 // src/ranking.ts
 var W = {
   // Generic solo / default — price-driven
@@ -867,8 +727,213 @@ var LetsFG = class {
   }
 };
 
+// src/auth.ts
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var import_node_crypto = require("crypto");
+var import_node_http = require("http");
+var BASE_URL = process.env.LETSFG_BASE_URL || "https://letsfg.co";
+var DEV_ROOT = `${BASE_URL}/developers/api`;
+var FALLBACK_TTL_MS = 55 * 60 * 1e3;
+var REFRESH_SKEW_MS = 5 * 60 * 1e3;
+var BearerTokenError = class extends Error {
+};
+function configPath() {
+  const base = (0, import_node_os.platform)() === "win32" ? process.env.APPDATA || (0, import_node_os.homedir)() : (0, import_node_os.homedir)();
+  return (0, import_node_path.join)(base, ".letsfg", "config.json");
+}
+function loadConfig() {
+  const p = configPath();
+  if (!(0, import_node_fs.existsSync)(p)) return {};
+  try {
+    return JSON.parse((0, import_node_fs.readFileSync)(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function saveConfig(cfg) {
+  const p = configPath();
+  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(p), { recursive: true });
+  (0, import_node_fs.writeFileSync)(p, JSON.stringify(cfg, null, 2));
+  try {
+    (0, import_node_fs.chmodSync)(p, 384);
+  } catch {
+  }
+}
+function saveToken(token, expiresAt, extra) {
+  const cfg = loadConfig();
+  cfg.pfs_auth = {
+    ...cfg.pfs_auth ?? {},
+    ...extra ?? {},
+    token,
+    expires_at: expiresAt ?? Date.now() + FALLBACK_TTL_MS
+  };
+  saveConfig(cfg);
+}
+function getBearerToken() {
+  const env = process.env.LETSFG_BEARER_TOKEN;
+  if (env) return env;
+  const auth = loadConfig().pfs_auth;
+  if (auth?.token && Date.now() < auth.expires_at - REFRESH_SKEW_MS) {
+    return auth.token;
+  }
+  if (auth?.refresh_token) {
+    throw new BearerTokenError(
+      "LetsFG token expired. Call ensureBearerToken() to refresh it, or run:  letsfg auth"
+    );
+  }
+  throw new BearerTokenError(
+    "No valid LetsFG Bearer token.\n  Run:  letsfg auth        (connects a card at letsfg.co/connect - nothing is charged)\n  Or:   export LETSFG_BEARER_TOKEN=<token>"
+  );
+}
+async function discover() {
+  const fallback = {
+    authorization_endpoint: `${BASE_URL}/connect`,
+    token_endpoint: `${DEV_ROOT}/oauth/token`,
+    registration_endpoint: `${DEV_ROOT}/oauth/register`
+  };
+  try {
+    const resp = await fetch(`${DEV_ROOT}/.well-known/oauth-authorization-server`);
+    if (!resp.ok) return fallback;
+    const d = await resp.json();
+    return {
+      authorization_endpoint: d.authorization_endpoint || fallback.authorization_endpoint,
+      token_endpoint: d.token_endpoint || fallback.token_endpoint,
+      registration_endpoint: d.registration_endpoint || fallback.registration_endpoint
+    };
+  } catch {
+    return fallback;
+  }
+}
+function pkce() {
+  const verifier = (0, import_node_crypto.randomBytes)(32).toString("base64url");
+  const challenge = (0, import_node_crypto.createHash)("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+async function postForm(url, form) {
+  const resp = await fetch(url, {
+    method: "POST",
+    // RFC 6749 4.1.3 - the token endpoint takes form encoding. The server also
+    // accepts JSON, but sending the spec encoding keeps this honest.
+    headers: { "Content-Type": "application/x-www-form-urlencoded", "X-Client-Type": "js-sdk" },
+    body: new URLSearchParams(form).toString()
+  });
+  const data = await resp.json().catch(() => ({}));
+  return { status: resp.status, data };
+}
+function openBrowser(url) {
+  import("child_process").then(({ exec }) => {
+    const cmd = (0, import_node_os.platform)() === "win32" ? `start "" "${url}"` : (0, import_node_os.platform)() === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
+    exec(cmd, () => {
+    });
+  }).catch(() => {
+  });
+}
+function startCallbackServer(expectedState) {
+  return new Promise((resolve, reject) => {
+    let settle = null;
+    let fail = null;
+    const codePromise = new Promise((res, rej) => {
+      settle = res;
+      fail = rej;
+    });
+    const server = (0, import_node_http.createServer)((req, res) => {
+      const url = new URL(req.url || "/", "http://127.0.0.1");
+      if (!url.pathname.startsWith("/callback")) {
+        res.writeHead(404).end();
+        return;
+      }
+      const err = url.searchParams.get("error");
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      if (err || !code) {
+        res.end("<h1>LetsFG</h1><p>That did not complete. Nothing was charged - run <code>letsfg auth</code> again.</p>");
+        fail?.(new BearerTokenError(`Authorisation failed: ${err || "no code returned"}`));
+        return;
+      }
+      if (state !== expectedState) {
+        res.end("<h1>LetsFG</h1><p>State mismatch - nothing was charged. Run <code>letsfg auth</code> again.</p>");
+        fail?.(new BearerTokenError("State mismatch on the OAuth callback - aborted."));
+        return;
+      }
+      res.end("<h1>LetsFG</h1><p>Connected. You can close this tab and go back to your terminal.</p>");
+      settle?.(code);
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      if (!port) {
+        reject(new BearerTokenError("Could not open a local callback port."));
+        return;
+      }
+      resolve({ port, waitForCode: () => codePromise, close: () => server.close() });
+    });
+  });
+}
+async function connectAuth(openBrowserFlag = true) {
+  const meta = await discover();
+  const { verifier, challenge } = pkce();
+  const state = (0, import_node_crypto.randomBytes)(16).toString("base64url");
+  const { port, waitForCode, close } = await startCallbackServer(state);
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  try {
+    const reg = await fetch(meta.registration_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_name: "letsfg-cli",
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none"
+      })
+    });
+    const regData = await reg.json().catch(() => ({}));
+    const clientId = typeof regData.client_id === "string" ? regData.client_id : "";
+    if (!reg.ok || !clientId) {
+      throw new BearerTokenError(
+        `Could not register with LetsFG (HTTP ${reg.status}). See ${BASE_URL}/for-agents`
+      );
+    }
+    const authUrl = `${meta.authorization_endpoint}?response_type=code&client_id=${encodeURIComponent(clientId)}&redirect_uri=${encodeURIComponent(redirectUri)}&code_challenge=${challenge}&code_challenge_method=S256&state=${encodeURIComponent(state)}&scope=flights`;
+    console.log("\n  LetsFG needs a card connected before it can search or book.");
+    console.log("  Nothing is charged now - you pay the fare only when you book,");
+    console.log("  and it is held, not taken, until the airline confirms.\n");
+    console.log("  Open this and add a card (or pay 0.00 with Revolut Pay):\n");
+    console.log(`     ${authUrl}
+`);
+    if (openBrowserFlag) openBrowser(authUrl);
+    process.stdout.write("  Waiting for you to finish... ");
+    const code = await waitForCode();
+    const { status, data } = await postForm(meta.token_endpoint, {
+      grant_type: "authorization_code",
+      code,
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      code_verifier: verifier
+    });
+    if (status !== 200 || !data.access_token) {
+      throw new BearerTokenError(
+        `Could not complete authentication (HTTP ${status}). ${String(data.error_description || data.error || "")}`.trim()
+      );
+    }
+    const expiresIn = typeof data.expires_in === "number" ? data.expires_in * 1e3 : FALLBACK_TTL_MS;
+    saveToken(String(data.access_token), Date.now() + expiresIn, {
+      refresh_token: typeof data.refresh_token === "string" ? data.refresh_token : void 0,
+      client_id: clientId
+    });
+    console.log("done. Card connected - the token refreshes itself from now on.");
+    return String(data.access_token);
+  } finally {
+    close();
+  }
+}
+var paymentAuth = connectAuth;
+
 // src/cli.ts
-init_auth();
 function resolveCredentials(apiKeyFlag) {
   const apiKey = apiKeyFlag || process.env.LETSFG_API_KEY;
   if (apiKey) return { apiKey };
@@ -1104,17 +1169,19 @@ async function cmdLocations(args) {
   }
 }
 async function cmdAuth(args) {
-  const cardToken = getFlag(args, "--card-token");
-  const paymentMethodId = getFlag(args, "--payment-method");
-  const noBrowser = hasFlag(args, "--no-browser");
-  if (cardToken || paymentMethodId) {
-    const { verifyPaymentMethod: verifyPaymentMethod2 } = await Promise.resolve().then(() => (init_auth(), auth_exports));
-    await verifyPaymentMethod2({ cardToken: cardToken || void 0, paymentMethodId: paymentMethodId || void 0 });
-    console.log("\n  \u2713 Authenticated. Nothing was charged.");
-  } else {
-    await paymentAuth(!noBrowser);
+  for (const dead of ["--card-token", "--payment-method"]) {
+    if (getFlag(args, dead)) {
+      console.error(
+        `
+  ${dead} was part of the Stripe enrolment, retired 2026-09-02.
+  Run plain \`letsfg auth\` instead - it opens letsfg.co/connect to add a card.
+`
+      );
+      process.exit(1);
+    }
   }
-  console.log("\n  You're all set. Run: letsfg search WAW BCN 2026-07-15\n");
+  await paymentAuth(!hasFlag(args, "--no-browser"));
+  console.log("\n  You are all set. Run: letsfg search WAW BCN 2026-07-15\n");
 }
 async function cmdRegister(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
@@ -1192,11 +1259,12 @@ var HELP = `
 LetsFG \u2014 Agent-native flight search & booking.
 
 Search hundreds of airlines via the LetsFG cloud engine.
-Authenticate once with letsfg auth \u2014 a zero-amount card setup, nothing is
-charged \u2014 then search and book.
+Authenticate once with letsfg auth \u2014 it opens letsfg.co/connect so you can add
+a card. Nothing is charged; you pay the fare only when you book, and it is held,
+not taken, until the airline confirms.
 
 Commands:
-  auth                             Put a card on file -> 90-day token. Nothing charged
+  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
@@ -1212,9 +1280,7 @@ Options:
   --json, -j          Output raw JSON
   --api-key, -k       Developer API key (or set LETSFG_API_KEY) \u2014 switches book/search to the paid path
   --base-url          API URL (default: https://letsfg.co)
-  --card-token        (auth only) Stripe tok_... you already hold, for a headless auth
-  --payment-method    (auth only) Stripe pm_... you already hold, for a headless auth
-  --no-browser        (auth only) Don't try to auto-open the card setup page
+  --no-browser        (auth only) Print the connect URL instead of opening a browser
 
 Examples:
   letsfg auth

package/dist/cli.mjs

@@ -4,11 +4,212 @@ import {
   LetsFGError,
   offerSummary
 } from "./chunk-GO3FXQXC.mjs";
-import {
-  BearerTokenError,
-  getBearerToken,
-  paymentAuth
-} from "./chunk-XNO2W77S.mjs";
+
+// src/auth.ts
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from "fs";
+import { homedir, platform } from "os";
+import { join, dirname } from "path";
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+var BASE_URL = process.env.LETSFG_BASE_URL || "https://letsfg.co";
+var DEV_ROOT = `${BASE_URL}/developers/api`;
+var FALLBACK_TTL_MS = 55 * 60 * 1e3;
+var REFRESH_SKEW_MS = 5 * 60 * 1e3;
+var BearerTokenError = class extends Error {
+};
+function configPath() {
+  const base = platform() === "win32" ? process.env.APPDATA || homedir() : homedir();
+  return join(base, ".letsfg", "config.json");
+}
+function loadConfig() {
+  const p = configPath();
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function saveConfig(cfg) {
+  const p = configPath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(cfg, null, 2));
+  try {
+    chmodSync(p, 384);
+  } catch {
+  }
+}
+function saveToken(token, expiresAt, extra) {
+  const cfg = loadConfig();
+  cfg.pfs_auth = {
+    ...cfg.pfs_auth ?? {},
+    ...extra ?? {},
+    token,
+    expires_at: expiresAt ?? Date.now() + FALLBACK_TTL_MS
+  };
+  saveConfig(cfg);
+}
+function getBearerToken() {
+  const env = process.env.LETSFG_BEARER_TOKEN;
+  if (env) return env;
+  const auth = loadConfig().pfs_auth;
+  if (auth?.token && Date.now() < auth.expires_at - REFRESH_SKEW_MS) {
+    return auth.token;
+  }
+  if (auth?.refresh_token) {
+    throw new BearerTokenError(
+      "LetsFG token expired. Call ensureBearerToken() to refresh it, or run:  letsfg auth"
+    );
+  }
+  throw new BearerTokenError(
+    "No valid LetsFG Bearer token.\n  Run:  letsfg auth        (connects a card at letsfg.co/connect - nothing is charged)\n  Or:   export LETSFG_BEARER_TOKEN=<token>"
+  );
+}
+async function discover() {
+  const fallback = {
+    authorization_endpoint: `${BASE_URL}/connect`,
+    token_endpoint: `${DEV_ROOT}/oauth/token`,
+    registration_endpoint: `${DEV_ROOT}/oauth/register`
+  };
+  try {
+    const resp = await fetch(`${DEV_ROOT}/.well-known/oauth-authorization-server`);
+    if (!resp.ok) return fallback;
+    const d = await resp.json();
+    return {
+      authorization_endpoint: d.authorization_endpoint || fallback.authorization_endpoint,
+      token_endpoint: d.token_endpoint || fallback.token_endpoint,
+      registration_endpoint: d.registration_endpoint || fallback.registration_endpoint
+    };
+  } catch {
+    return fallback;
+  }
+}
+function pkce() {
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+async function postForm(url, form) {
+  const resp = await fetch(url, {
+    method: "POST",
+    // RFC 6749 4.1.3 - the token endpoint takes form encoding. The server also
+    // accepts JSON, but sending the spec encoding keeps this honest.
+    headers: { "Content-Type": "application/x-www-form-urlencoded", "X-Client-Type": "js-sdk" },
+    body: new URLSearchParams(form).toString()
+  });
+  const data = await resp.json().catch(() => ({}));
+  return { status: resp.status, data };
+}
+function openBrowser(url) {
+  import("child_process").then(({ exec }) => {
+    const cmd = platform() === "win32" ? `start "" "${url}"` : platform() === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
+    exec(cmd, () => {
+    });
+  }).catch(() => {
+  });
+}
+function startCallbackServer(expectedState) {
+  return new Promise((resolve, reject) => {
+    let settle = null;
+    let fail = null;
+    const codePromise = new Promise((res, rej) => {
+      settle = res;
+      fail = rej;
+    });
+    const server = createServer((req, res) => {
+      const url = new URL(req.url || "/", "http://127.0.0.1");
+      if (!url.pathname.startsWith("/callback")) {
+        res.writeHead(404).end();
+        return;
+      }
+      const err = url.searchParams.get("error");
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      if (err || !code) {
+        res.end("<h1>LetsFG</h1><p>That did not complete. Nothing was charged - run <code>letsfg auth</code> again.</p>");
+        fail?.(new BearerTokenError(`Authorisation failed: ${err || "no code returned"}`));
+        return;
+      }
+      if (state !== expectedState) {
+        res.end("<h1>LetsFG</h1><p>State mismatch - nothing was charged. Run <code>letsfg auth</code> again.</p>");
+        fail?.(new BearerTokenError("State mismatch on the OAuth callback - aborted."));
+        return;
+      }
+      res.end("<h1>LetsFG</h1><p>Connected. You can close this tab and go back to your terminal.</p>");
+      settle?.(code);
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      if (!port) {
+        reject(new BearerTokenError("Could not open a local callback port."));
+        return;
+      }
+      resolve({ port, waitForCode: () => codePromise, close: () => server.close() });
+    });
+  });
+}
+async function connectAuth(openBrowserFlag = true) {
+  const meta = await discover();
+  const { verifier, challenge } = pkce();
+  const state = randomBytes(16).toString("base64url");
+  const { port, waitForCode, close } = await startCallbackServer(state);
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  try {
+    const reg = await fetch(meta.registration_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_name: "letsfg-cli",
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none"
+      })
+    });
+    const regData = await reg.json().catch(() => ({}));
+    const clientId = typeof regData.client_id === "string" ? regData.client_id : "";
+    if (!reg.ok || !clientId) {
+      throw new BearerTokenError(
+        `Could not register with LetsFG (HTTP ${reg.status}). See ${BASE_URL}/for-agents`
+      );
+    }
+    const authUrl = `${meta.authorization_endpoint}?response_type=code&client_id=${encodeURIComponent(clientId)}&redirect_uri=${encodeURIComponent(redirectUri)}&code_challenge=${challenge}&code_challenge_method=S256&state=${encodeURIComponent(state)}&scope=flights`;
+    console.log("\n  LetsFG needs a card connected before it can search or book.");
+    console.log("  Nothing is charged now - you pay the fare only when you book,");
+    console.log("  and it is held, not taken, until the airline confirms.\n");
+    console.log("  Open this and add a card (or pay 0.00 with Revolut Pay):\n");
+    console.log(`     ${authUrl}
+`);
+    if (openBrowserFlag) openBrowser(authUrl);
+    process.stdout.write("  Waiting for you to finish... ");
+    const code = await waitForCode();
+    const { status, data } = await postForm(meta.token_endpoint, {
+      grant_type: "authorization_code",
+      code,
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      code_verifier: verifier
+    });
+    if (status !== 200 || !data.access_token) {
+      throw new BearerTokenError(
+        `Could not complete authentication (HTTP ${status}). ${String(data.error_description || data.error || "")}`.trim()
+      );
+    }
+    const expiresIn = typeof data.expires_in === "number" ? data.expires_in * 1e3 : FALLBACK_TTL_MS;
+    saveToken(String(data.access_token), Date.now() + expiresIn, {
+      refresh_token: typeof data.refresh_token === "string" ? data.refresh_token : void 0,
+      client_id: clientId
+    });
+    console.log("done. Card connected - the token refreshes itself from now on.");
+    return String(data.access_token);
+  } finally {
+    close();
+  }
+}
+var paymentAuth = connectAuth;
 
 // src/cli.ts
 function resolveCredentials(apiKeyFlag) {
@@ -246,17 +447,19 @@ async function cmdLocations(args) {
   }
 }
 async function cmdAuth(args) {
-  const cardToken = getFlag(args, "--card-token");
-  const paymentMethodId = getFlag(args, "--payment-method");
-  const noBrowser = hasFlag(args, "--no-browser");
-  if (cardToken || paymentMethodId) {
-    const { verifyPaymentMethod } = await import("./auth-SYZ5AYZ6.mjs");
-    await verifyPaymentMethod({ cardToken: cardToken || void 0, paymentMethodId: paymentMethodId || void 0 });
-    console.log("\n  \u2713 Authenticated. Nothing was charged.");
-  } else {
-    await paymentAuth(!noBrowser);
+  for (const dead of ["--card-token", "--payment-method"]) {
+    if (getFlag(args, dead)) {
+      console.error(
+        `
+  ${dead} was part of the Stripe enrolment, retired 2026-09-02.
+  Run plain \`letsfg auth\` instead - it opens letsfg.co/connect to add a card.
+`
+      );
+      process.exit(1);
+    }
   }
-  console.log("\n  You're all set. Run: letsfg search WAW BCN 2026-07-15\n");
+  await paymentAuth(!hasFlag(args, "--no-browser"));
+  console.log("\n  You are all set. Run: letsfg search WAW BCN 2026-07-15\n");
 }
 async function cmdRegister(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
@@ -334,11 +537,12 @@ var HELP = `
 LetsFG \u2014 Agent-native flight search & booking.
 
 Search hundreds of airlines via the LetsFG cloud engine.
-Authenticate once with letsfg auth \u2014 a zero-amount card setup, nothing is
-charged \u2014 then search and book.
+Authenticate once with letsfg auth \u2014 it opens letsfg.co/connect so you can add
+a card. Nothing is charged; you pay the fare only when you book, and it is held,
+not taken, until the airline confirms.
 
 Commands:
-  auth                             Put a card on file -> 90-day token. Nothing charged
+  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
@@ -354,9 +558,7 @@ Options:
   --json, -j          Output raw JSON
   --api-key, -k       Developer API key (or set LETSFG_API_KEY) \u2014 switches book/search to the paid path
   --base-url          API URL (default: https://letsfg.co)
-  --card-token        (auth only) Stripe tok_... you already hold, for a headless auth
-  --payment-method    (auth only) Stripe pm_... you already hold, for a headless auth
-  --no-browser        (auth only) Don't try to auto-open the card setup page
+  --no-browser        (auth only) Print the connect URL instead of opening a browser
 
 Examples:
   letsfg auth

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "letsfg",
-  "version": "2026.5.71",
-  "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.72",
+  "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"
+  }
+}

package/dist/auth-SYZ5AYZ6.mjs

@@ -1,16 +0,0 @@
-import {
-  BearerTokenError,
-  getBearerToken,
-  paymentAuth,
-  requestEnrolment,
-  saveToken,
-  verifyPaymentMethod
-} from "./chunk-XNO2W77S.mjs";
-export {
-  BearerTokenError,
-  getBearerToken,
-  paymentAuth,
-  requestEnrolment,
-  saveToken,
-  verifyPaymentMethod
-};

package/dist/chunk-XNO2W77S.mjs

@@ -1,126 +0,0 @@
-// src/auth.ts
-import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from "fs";
-import { homedir, platform } from "os";
-import { join, dirname } from "path";
-var BASE_URL = process.env.LETSFG_BASE_URL || "https://letsfg.co";
-var TOKEN_TTL_MS = 90 * 24 * 3600 * 1e3;
-var BearerTokenError = class extends Error {
-};
-function configPath() {
-  const base = platform() === "win32" ? process.env.APPDATA || homedir() : homedir();
-  return join(base, ".letsfg", "config.json");
-}
-function loadConfig() {
-  const p = configPath();
-  if (!existsSync(p)) return {};
-  try {
-    return JSON.parse(readFileSync(p, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-function saveConfig(cfg) {
-  const p = configPath();
-  mkdirSync(dirname(p), { recursive: true });
-  writeFileSync(p, JSON.stringify(cfg, null, 2));
-  try {
-    chmodSync(p, 384);
-  } catch {
-  }
-}
-function getBearerToken() {
-  const env = process.env.LETSFG_BEARER_TOKEN;
-  if (env) return env;
-  const auth = loadConfig().pfs_auth;
-  if (auth?.token && Date.now() < auth.expires_at - 36e5) {
-    return auth.token;
-  }
-  throw new BearerTokenError(
-    "No valid LetsFG Bearer token.\n  Run:  letsfg auth        (adds a payment method \u2014 nothing is charged)\n  Or:   export LETSFG_BEARER_TOKEN=<token>"
-  );
-}
-function saveToken(token, expiresAt) {
-  const cfg = loadConfig();
-  cfg.pfs_auth = { token, expires_at: expiresAt ?? Date.now() + TOKEN_TTL_MS };
-  saveConfig(cfg);
-}
-async function postJson(path, payload) {
-  const resp = await fetch(`${BASE_URL}${path}`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", "User-Agent": "LetsFG-js/0.1.0", "X-Client-Type": "js-sdk" },
-    body: JSON.stringify(payload)
-  });
-  const data = await resp.json().catch(() => ({}));
-  return { status: resp.status, data };
-}
-function parseExpiry(raw) {
-  if (typeof raw === "number") return raw * 1e3;
-  if (typeof raw === "string") {
-    const ms = Date.parse(raw);
-    if (!Number.isNaN(ms)) return ms;
-  }
-  return Date.now() + TOKEN_TTL_MS;
-}
-async function requestEnrolment() {
-  const { status, data } = await postJson("/api/agent-access/request", {});
-  if (status !== 200 && status !== 402) {
-    throw new BearerTokenError(`Could not start authentication (HTTP ${status}): ${data.error || ""}`);
-  }
-  return data;
-}
-async function verifyPaymentMethod(opts) {
-  const payload = {};
-  if (opts.setupSessionId) payload.setup_session_id = opts.setupSessionId;
-  else if (opts.paymentMethodId) payload.payment_method_id = opts.paymentMethodId;
-  else if (opts.cardToken) payload.card_token = opts.cardToken;
-  else throw new BearerTokenError("Provide one of setupSessionId, paymentMethodId, or cardToken.");
-  const { status, data } = await postJson("/api/agent-access/verify", payload);
-  if (status !== 200 || !data.token) {
-    throw new BearerTokenError(`Verification failed (HTTP ${status}). ${data.hint || data.error || ""}`.trim());
-  }
-  const token = data.token;
-  saveToken(token, parseExpiry(data.expires_at));
-  return token;
-}
-function openBrowser(url) {
-  import("child_process").then(({ exec }) => {
-    const cmd = platform() === "win32" ? `start "" "${url}"` : platform() === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
-    exec(cmd, () => {
-    });
-  }).catch(() => {
-  });
-}
-async function paymentAuth(openBrowserFlag = true) {
-  console.log("\n  Connecting to LetsFG...");
-  const data = await requestEnrolment();
-  const setupUrl = data.setup_url;
-  const sessionId = data.setup_session_id;
-  if (!setupUrl || !sessionId) {
-    throw new BearerTokenError("Server did not return a setup URL. Check https://letsfg.co/for-agents");
-  }
-  console.log("\n  LetsFG needs a payment method on file before it can search or book.");
-  console.log("  Nothing is charged now \u2014 this is a zero-amount card setup.\n");
-  console.log("  Step 1 \u2014 add a card here:\n");
-  console.log(`     ${setupUrl}
-`);
-  if (openBrowserFlag) openBrowser(setupUrl);
-  console.log("  Step 2 \u2014 press Enter once you've finished.");
-  const readline = await import("readline/promises");
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  await rl.question("");
-  rl.close();
-  process.stdout.write("  Verifying... ");
-  const token = await verifyPaymentMethod({ setupSessionId: sessionId });
-  const expiresAt = loadConfig().pfs_auth?.expires_at ?? Date.now() + TOKEN_TTL_MS;
-  console.log(`done. Token valid until ${new Date(expiresAt).toISOString().slice(0, 10)}.`);
-  return token;
-}
-
-export {
-  BearerTokenError,
-  getBearerToken,
-  saveToken,
-  requestEnrolment,
-  verifyPaymentMethod,
-  paymentAuth
-};