letsfg 2026.5.71 → 2026.5.73

package/dist/cli.mjs

@@ -3,12 +3,213 @@ import {
   LetsFG,
   LetsFGError,
   offerSummary
-} from "./chunk-GO3FXQXC.mjs";
-import {
-  BearerTokenError,
-  getBearerToken,
-  paymentAuth
-} from "./chunk-XNO2W77S.mjs";
+} from "./chunk-F5BBI6XX.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) {
@@ -128,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");
@@ -246,17 +424,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");
@@ -289,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);
   }
 }
@@ -322,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)}
 `);
@@ -334,29 +520,29 @@ 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
+  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
   --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
@@ -386,6 +572,7 @@ async function main() {
       case "register":
         await cmdRegister(args);
         break;
+      case "connect-payment":
       case "setup-payment":
         await cmdSetupPayment(args);
         break;

package/dist/index.d.mts

@@ -282,7 +282,7 @@ 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)
+ * // Developer API (look-to-book search: 200 free after every booking)
  * const bt2 = new LetsFG({ apiKey: 'letsfg_...' });
  * 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;
@@ -495,11 +495,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 +517,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.
      *
@@ -621,13 +682,30 @@ declare class LetsFG {
      */
     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.
      */