letsfg 2026.5.64 → 2026.5.66

package/README.md

@@ -9,8 +9,8 @@
 
 | | **CLI / SDK** (this package) | **Developer API** |
 |---|---|---|
-| **Search cost** | Free (Twitter/X Bearer token via `letsfg auth`) | Prepaid credits |
-| **Booking** | `POST /api/agent-book` | Direct airline URL |
+| **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) |
 | **Speed** | 60–90 s | 2–5 s (discover) · 60–90 s (full) |
 | **Setup** | `npm install letsfg` then `letsfg auth` | [letsfg.co/developers](https://letsfg.co/developers) |
 
@@ -27,60 +27,60 @@ npm install letsfg
 ```typescript
 import { LetsFG, cheapestOffer, offerSummary } from 'letsfg';
 
-// Register (one-time)
-const creds = await LetsFG.register('my-agent', 'agent@example.com');
-console.log(creds.api_key); // Save this
-
-// Use
-const bt = new LetsFG({ apiKey: 'trav_...' });
+// PFS — free. Get a Bearer token once with `letsfg auth` (zero-amount card
+// setup, nothing charged), then pass it here.
+const bt = new LetsFG({ bearerToken: 'eyJ...' });
 
 // Search — FREE
 const flights = await bt.search('GDN', 'BER', '2026-03-03');
 const best = cheapestOffer(flights);
 console.log(offerSummary(best));
 
-// Unlock
-const unlock = await bt.unlock(best.id);
-
-// Book
-const booking = await bt.book(
+// Book — free, ticket price only, no LetsFG fee. No unlock step.
+const result = await bt.book(
   best.id,
-  [{
-    id: flights.passenger_ids[0],
-    given_name: 'John',
-    family_name: 'Doe',
-    born_on: '1990-01-15',
-    gender: 'm',
-    title: 'mr',
-    email: 'john@example.com',
-  }],
-  'john@example.com'
+  [{ given_name: 'John', family_name: 'Doe', born_on: '1990-01-15', gender: 'm' }],
+  'john@example.com',
+  '',
+  '',
+  flights.search_id,
 );
-console.log(`PNR: ${booking.booking_reference}`);
+if (result.booked) {
+  console.log(`Order: ${result.order_id}`);
+} else {
+  console.log(`Booking link (nothing charged): ${result.booking_url}`);
+}
 ```
 
+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()`.
+
 ## Quick Start (CLI)
 
 ```bash
-export LETSFG_BEARER_TOKEN=<your-bearer-token>
+export LETSFG_BEARER_TOKEN=<your-bearer-token>  # from `letsfg auth`
 
 letsfg search GDN BER 2026-03-03 --sort price
 letsfg search LON BCN 2026-04-01 --json  # Machine-readable
-letsfg unlock off_xxx
-letsfg book off_xxx -p '{"id":"pas_xxx","given_name":"John",...}' -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"}' -e john@example.com
 ```
 
 ## API
 
-### `new LetsFG({ apiKey, baseUrl?, timeout? })`
+### `new LetsFG({ bearerToken?, apiKey?, baseUrl?, timeout? })`
 
 ### `bt.search(origin, destination, dateFrom, options?)`
 ### `bt.resolveLocation(query)`
-### `bt.unlock(offerId)`
-### `bt.book(offerId, passengers, contactEmail, contactPhone?)`
-### `bt.setupPayment(token?)`
+### `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
+Developer API `book` (requires `unlock()` first, supports multiple passengers
+and `idempotencyKey`).
+### `bt.setupPayment(token?)` — Developer API only
 ### `bt.me()`
-### `LetsFG.register(agentName, email, baseUrl?, ownerName?, description?)`
+### `LetsFG.register(agentName, email, baseUrl?, ownerName?, description?)` — Developer API only, most agents don't need this
 
 ### Helpers
 - `offerSummary(offer)` — One-line string summary

package/dist/auth-SYZ5AYZ6.mjs

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

package/dist/{chunk-ZX2EIEN7.mjs → chunk-2SNO3AGS.mjs}

@@ -1629,18 +1629,44 @@ var LetsFG = class {
   }
   /**
    * Unlock a flight offer — confirms live price, reveals direct airline booking URL.
-   * Cost: 1% of ticket price, min $3. Free with Developer API.
+   * Cost: 1% of ticket price, min $3. Developer API only — there is no unlock
+   * endpoint on a PFS Bearer token, so PFS callers use book() directly.
    */
   async unlock(offerId) {
-    this.requireAuth();
-    const path = this.usingPFS ? "/api/unlock" : "/developers/api/v1/bookings/unlock";
-    return this.postWithAuth(path, { offer_id: offerId });
+    this.requireApiKey();
+    return this.post("/developers/api/v1/bookings/unlock", { offer_id: offerId });
   }
   /**
-   * Book a flight via Developer API — charges ticket price via Stripe, creates real PNR.
-   * Always provide idempotencyKey to prevent double-bookings on retry.
+   * Book a flight.
+   *
+   * PFS (Bearer token): POST /api/agent-book. Free — nothing charged beyond
+   * the ticket price. Pass searchId (from search()'s result). Returns either
+   * { ok, booked: true, order_id } or, when the booking genuinely could not
+   * 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.
    */
-  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "") {
+  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "", searchId = "") {
+    this.requireAuth();
+    if (this.usingPFS) {
+      if (!searchId) {
+        throw new LetsFGError(
+          "searchId is required to book via PFS \u2014 pass the search_id from search()'s result.",
+          400
+        );
+      }
+      const passenger = { ...passengers[0] };
+      if (contactPhone && !passenger.phone_number) passenger.phone_number = contactPhone;
+      return this.postWithBearer("/api/agent-book", {
+        search_id: searchId,
+        offer_id: offerId,
+        passenger,
+        contact_email: contactEmail
+      });
+    }
     this.requireApiKey();
     const body = {
       offer_id: offerId,

package/dist/chunk-XNO2W77S.mjs

@@ -0,0 +1,126 @@
+// 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
+};

package/dist/cli.js

@@ -1,5 +1,167 @@
 #!/usr/bin/env node
 "use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+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))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  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 = {
@@ -384,18 +546,44 @@ var LetsFG = class {
   }
   /**
    * Unlock a flight offer — confirms live price, reveals direct airline booking URL.
-   * Cost: 1% of ticket price, min $3. Free with Developer API.
+   * Cost: 1% of ticket price, min $3. Developer API only — there is no unlock
+   * endpoint on a PFS Bearer token, so PFS callers use book() directly.
    */
   async unlock(offerId) {
-    this.requireAuth();
-    const path = this.usingPFS ? "/api/unlock" : "/developers/api/v1/bookings/unlock";
-    return this.postWithAuth(path, { offer_id: offerId });
+    this.requireApiKey();
+    return this.post("/developers/api/v1/bookings/unlock", { offer_id: offerId });
   }
   /**
-   * Book a flight via Developer API — charges ticket price via Stripe, creates real PNR.
-   * Always provide idempotencyKey to prevent double-bookings on retry.
+   * Book a flight.
+   *
+   * PFS (Bearer token): POST /api/agent-book. Free — nothing charged beyond
+   * the ticket price. Pass searchId (from search()'s result). Returns either
+   * { ok, booked: true, order_id } or, when the booking genuinely could not
+   * 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.
    */
-  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "") {
+  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "", searchId = "") {
+    this.requireAuth();
+    if (this.usingPFS) {
+      if (!searchId) {
+        throw new LetsFGError(
+          "searchId is required to book via PFS \u2014 pass the search_id from search()'s result.",
+          400
+        );
+      }
+      const passenger = { ...passengers[0] };
+      if (contactPhone && !passenger.phone_number) passenger.phone_number = contactPhone;
+      return this.postWithBearer("/api/agent-book", {
+        search_id: searchId,
+        offer_id: offerId,
+        passenger,
+        contact_email: contactEmail
+      });
+    }
     this.requireApiKey();
     const body = {
       offer_id: offerId,
@@ -658,6 +846,16 @@ var LetsFG = class {
 };
 
 // src/cli.ts
+init_auth();
+function resolveCredentials(apiKeyFlag) {
+  const apiKey = apiKeyFlag || process.env.LETSFG_API_KEY;
+  if (apiKey) return { apiKey };
+  try {
+    return { bearerToken: getBearerToken() };
+  } catch {
+    return {};
+  }
+}
 function getFlag(args, flag, alias) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag || alias && args[i] === alias) {
@@ -712,7 +910,8 @@ async function cmdSearch(args) {
     console.error("Usage: letsfg search <origin> <destination> <date> [options]");
     process.exit(1);
   }
-  const bt = new LetsFG({ apiKey, baseUrl });
+  const creds = resolveCredentials(apiKey);
+  const bt = new LetsFG({ ...creds, baseUrl });
   const result = await bt.search(origin, destination, date, {
     returnDate,
     adults,
@@ -726,6 +925,7 @@ async function cmdSearch(args) {
   });
   if (jsonOut) {
     console.log(JSON.stringify({
+      search_id: result.search_id,
       passenger_ids: result.passenger_ids,
       total_results: result.total_results,
       offers: result.offers.map((o) => ({
@@ -749,16 +949,25 @@ async function cmdSearch(args) {
   }
   console.log(`
   ${result.total_results} offers  |  ${origin} \u2192 ${destination}  |  ${date}`);
+  if (result.search_id) {
+    console.log(`  search_id: ${result.search_id}  (needed for \`letsfg book\`, offers expire ~15 min after search)`);
+  }
   console.log(`  Passenger IDs: ${JSON.stringify(result.passenger_ids)}
 `);
   result.offers.forEach((o, i) => {
     console.log(`  ${(i + 1).toString().padStart(3)}. ${offerSummary(o)}`);
     console.log(`       ID: ${o.id}`);
   });
-  console.log(`
+  if (creds.bearerToken) {
+    console.log(`
+  To book: letsfg book <offer_id> --search-id ${result.search_id} --passenger '{...}' --email you@example.com
+`);
+  } else {
+    console.log(`
   To unlock: letsfg unlock <offer_id>`);
-  console.log(`  Passenger IDs needed for booking: ${JSON.stringify(result.passenger_ids)}
+    console.log(`  Passenger IDs needed for booking: ${JSON.stringify(result.passenger_ids)}
 `);
+  }
 }
 async function cmdUnlock(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
@@ -792,33 +1001,55 @@ async function cmdBook(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
   const apiKey = getFlag(args, "--api-key", "-k");
   const baseUrl = getFlag(args, "--base-url");
+  const searchId = getFlag(args, "--search-id");
   const email = getFlag(args, "--email", "-e") || "";
   const phone = getFlag(args, "--phone") || "";
   const passengerStrs = getAllFlags(args, "--passenger", "-p");
   const offerId = args[0];
   if (!offerId || !passengerStrs.length || !email) {
-    console.error(`Usage: letsfg book <offer_id> --passenger '{"id":"pas_xxx",...}' --email you@example.com`);
+    console.error(`Usage: letsfg book <offer_id> --search-id <id> --passenger '{"given_name":"John",...}' --email you@example.com`);
     process.exit(1);
   }
   const passengers = passengerStrs.map((s) => JSON.parse(s));
-  const bt = new LetsFG({ apiKey, baseUrl });
-  const result = await bt.book(offerId, passengers, email, phone);
+  const creds = resolveCredentials(apiKey);
+  if (creds.bearerToken && !searchId) {
+    console.error("Error: --search-id is required (from your `letsfg search` results) to book via the free PFS path.");
+    process.exit(1);
+  }
+  const bt = new LetsFG({ ...creds, baseUrl });
+  const result = await bt.book(offerId, passengers, email, phone, "", searchId);
   if (jsonOut) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
-  if (result.status === "confirmed") {
+  if ("booked" in result) {
+    if (result.booked) {
+      console.log(`
+  \u2713 Booking confirmed!`);
+      console.log(`    Order ID: ${result.order_id}`);
+      console.log(`    Charged: ${result.charged ?? 0} ${result.currency ?? ""}
+`);
+    } else {
+      console.log(`
+  Could not complete a confirmed booking. Nothing was charged.`);
+      console.log(`    Booking link: ${result.booking_url ?? "(none)"}
+`);
+    }
+    return;
+  }
+  const br = result;
+  if (br.status === "confirmed") {
     console.log(`
   \u2713 Booking confirmed!`);
-    console.log(`    PNR: ${result.booking_reference}`);
-    console.log(`    Flight: ${result.currency} ${result.flight_price.toFixed(2)}`);
-    console.log(`    Fee: ${result.currency} ${result.service_fee.toFixed(2)} (${result.service_fee_percentage}%)`);
-    console.log(`    Total: ${result.currency} ${result.total_charged.toFixed(2)}`);
-    console.log(`    Order: ${result.order_id}
+    console.log(`    PNR: ${br.booking_reference}`);
+    console.log(`    Flight: ${br.currency} ${br.flight_price.toFixed(2)}`);
+    console.log(`    Fee: ${br.currency} ${br.service_fee.toFixed(2)} (${br.service_fee_percentage}%)`);
+    console.log(`    Total: ${br.currency} ${br.total_charged.toFixed(2)}`);
+    console.log(`    Order: ${br.order_id}
 `);
   } else {
     console.error(`  \u2717 Booking failed`);
-    console.error(JSON.stringify(result.details, null, 2));
+    console.error(JSON.stringify(br.details, null, 2));
     process.exit(1);
   }
 }
@@ -850,6 +1081,19 @@ async function cmdLocations(args) {
     console.log(`  ${iata}  ${name} (${type}) \u2014 ${city}, ${country}`);
   }
 }
+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);
+  }
+  console.log("\n  You're all set. Run: letsfg search WAW BCN 2026-07-15\n");
+}
 async function cmdRegister(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
   const baseUrl = getFlag(args, "--base-url");
@@ -930,11 +1174,11 @@ Authenticate once with letsfg auth \u2014 a zero-amount card setup, nothing is
 charged \u2014 then search and book.
 
 Commands:
-  auth                            Put a card on file -> 90-day token. Nothing charged
-  search <origin> <dest> <date>   Search for flights (free)
-  locations <query>               Resolve city name to IATA codes
-  book <offer_id> --passenger ... Book a flight. No LetsFG fee
-  me                              Show agent profile
+  auth                             Put a card on file -> 90-day token. 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
+  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):
@@ -943,20 +1187,26 @@ they create a billing account. Use auth above instead):
   unlock <offer_id>               [Developer API only] Unlock offer \u2014 1% of ticket (min $3)
 
 Options:
-  --json, -j       Output raw JSON
-  --api-key, -k    API key (or set LETSFG_API_KEY)
-  --base-url       API URL (default: https://letsfg.co/developers)
+  --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
 
 Examples:
   letsfg auth
   letsfg search GDN BER 2026-03-03 --sort price
-  letsfg book off_xxx -p '{"given_name":"Ada",...}' -e ada@example.com
+  letsfg book off_xxx --search-id srch_xxx -p '{"given_name":"Ada","family_name":"Lovelace","born_on":"1990-04-01","gender":"f"}' -e ada@example.com
 `;
 async function main() {
   const args = process.argv.slice(2);
   const command = args.shift();
   try {
     switch (command) {
+      case "auth":
+        await cmdAuth(args);
+        break;
       case "search":
         await cmdSearch(args);
         break;
@@ -990,7 +1240,7 @@ async function main() {
         process.exit(1);
     }
   } catch (e) {
-    if (e instanceof LetsFGError) {
+    if (e instanceof LetsFGError || e instanceof BearerTokenError) {
       console.error(`Error: ${e.message}`);
       process.exit(1);
     }

package/dist/cli.mjs

@@ -3,9 +3,23 @@ import {
   LetsFG,
   LetsFGError,
   offerSummary
-} from "./chunk-ZX2EIEN7.mjs";
+} from "./chunk-2SNO3AGS.mjs";
+import {
+  BearerTokenError,
+  getBearerToken,
+  paymentAuth
+} from "./chunk-XNO2W77S.mjs";
 
 // src/cli.ts
+function resolveCredentials(apiKeyFlag) {
+  const apiKey = apiKeyFlag || process.env.LETSFG_API_KEY;
+  if (apiKey) return { apiKey };
+  try {
+    return { bearerToken: getBearerToken() };
+  } catch {
+    return {};
+  }
+}
 function getFlag(args, flag, alias) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag || alias && args[i] === alias) {
@@ -60,7 +74,8 @@ async function cmdSearch(args) {
     console.error("Usage: letsfg search <origin> <destination> <date> [options]");
     process.exit(1);
   }
-  const bt = new LetsFG({ apiKey, baseUrl });
+  const creds = resolveCredentials(apiKey);
+  const bt = new LetsFG({ ...creds, baseUrl });
   const result = await bt.search(origin, destination, date, {
     returnDate,
     adults,
@@ -74,6 +89,7 @@ async function cmdSearch(args) {
   });
   if (jsonOut) {
     console.log(JSON.stringify({
+      search_id: result.search_id,
       passenger_ids: result.passenger_ids,
       total_results: result.total_results,
       offers: result.offers.map((o) => ({
@@ -97,16 +113,25 @@ async function cmdSearch(args) {
   }
   console.log(`
   ${result.total_results} offers  |  ${origin} \u2192 ${destination}  |  ${date}`);
+  if (result.search_id) {
+    console.log(`  search_id: ${result.search_id}  (needed for \`letsfg book\`, offers expire ~15 min after search)`);
+  }
   console.log(`  Passenger IDs: ${JSON.stringify(result.passenger_ids)}
 `);
   result.offers.forEach((o, i) => {
     console.log(`  ${(i + 1).toString().padStart(3)}. ${offerSummary(o)}`);
     console.log(`       ID: ${o.id}`);
   });
-  console.log(`
+  if (creds.bearerToken) {
+    console.log(`
+  To book: letsfg book <offer_id> --search-id ${result.search_id} --passenger '{...}' --email you@example.com
+`);
+  } else {
+    console.log(`
   To unlock: letsfg unlock <offer_id>`);
-  console.log(`  Passenger IDs needed for booking: ${JSON.stringify(result.passenger_ids)}
+    console.log(`  Passenger IDs needed for booking: ${JSON.stringify(result.passenger_ids)}
 `);
+  }
 }
 async function cmdUnlock(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
@@ -140,33 +165,55 @@ async function cmdBook(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
   const apiKey = getFlag(args, "--api-key", "-k");
   const baseUrl = getFlag(args, "--base-url");
+  const searchId = getFlag(args, "--search-id");
   const email = getFlag(args, "--email", "-e") || "";
   const phone = getFlag(args, "--phone") || "";
   const passengerStrs = getAllFlags(args, "--passenger", "-p");
   const offerId = args[0];
   if (!offerId || !passengerStrs.length || !email) {
-    console.error(`Usage: letsfg book <offer_id> --passenger '{"id":"pas_xxx",...}' --email you@example.com`);
+    console.error(`Usage: letsfg book <offer_id> --search-id <id> --passenger '{"given_name":"John",...}' --email you@example.com`);
     process.exit(1);
   }
   const passengers = passengerStrs.map((s) => JSON.parse(s));
-  const bt = new LetsFG({ apiKey, baseUrl });
-  const result = await bt.book(offerId, passengers, email, phone);
+  const creds = resolveCredentials(apiKey);
+  if (creds.bearerToken && !searchId) {
+    console.error("Error: --search-id is required (from your `letsfg search` results) to book via the free PFS path.");
+    process.exit(1);
+  }
+  const bt = new LetsFG({ ...creds, baseUrl });
+  const result = await bt.book(offerId, passengers, email, phone, "", searchId);
   if (jsonOut) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
-  if (result.status === "confirmed") {
+  if ("booked" in result) {
+    if (result.booked) {
+      console.log(`
+  \u2713 Booking confirmed!`);
+      console.log(`    Order ID: ${result.order_id}`);
+      console.log(`    Charged: ${result.charged ?? 0} ${result.currency ?? ""}
+`);
+    } else {
+      console.log(`
+  Could not complete a confirmed booking. Nothing was charged.`);
+      console.log(`    Booking link: ${result.booking_url ?? "(none)"}
+`);
+    }
+    return;
+  }
+  const br = result;
+  if (br.status === "confirmed") {
     console.log(`
   \u2713 Booking confirmed!`);
-    console.log(`    PNR: ${result.booking_reference}`);
-    console.log(`    Flight: ${result.currency} ${result.flight_price.toFixed(2)}`);
-    console.log(`    Fee: ${result.currency} ${result.service_fee.toFixed(2)} (${result.service_fee_percentage}%)`);
-    console.log(`    Total: ${result.currency} ${result.total_charged.toFixed(2)}`);
-    console.log(`    Order: ${result.order_id}
+    console.log(`    PNR: ${br.booking_reference}`);
+    console.log(`    Flight: ${br.currency} ${br.flight_price.toFixed(2)}`);
+    console.log(`    Fee: ${br.currency} ${br.service_fee.toFixed(2)} (${br.service_fee_percentage}%)`);
+    console.log(`    Total: ${br.currency} ${br.total_charged.toFixed(2)}`);
+    console.log(`    Order: ${br.order_id}
 `);
   } else {
     console.error(`  \u2717 Booking failed`);
-    console.error(JSON.stringify(result.details, null, 2));
+    console.error(JSON.stringify(br.details, null, 2));
     process.exit(1);
   }
 }
@@ -198,6 +245,19 @@ async function cmdLocations(args) {
     console.log(`  ${iata}  ${name} (${type}) \u2014 ${city}, ${country}`);
   }
 }
+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);
+  }
+  console.log("\n  You're all set. Run: letsfg search WAW BCN 2026-07-15\n");
+}
 async function cmdRegister(args) {
   const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
   const baseUrl = getFlag(args, "--base-url");
@@ -278,11 +338,11 @@ Authenticate once with letsfg auth \u2014 a zero-amount card setup, nothing is
 charged \u2014 then search and book.
 
 Commands:
-  auth                            Put a card on file -> 90-day token. Nothing charged
-  search <origin> <dest> <date>   Search for flights (free)
-  locations <query>               Resolve city name to IATA codes
-  book <offer_id> --passenger ... Book a flight. No LetsFG fee
-  me                              Show agent profile
+  auth                             Put a card on file -> 90-day token. 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
+  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):
@@ -291,20 +351,26 @@ they create a billing account. Use auth above instead):
   unlock <offer_id>               [Developer API only] Unlock offer \u2014 1% of ticket (min $3)
 
 Options:
-  --json, -j       Output raw JSON
-  --api-key, -k    API key (or set LETSFG_API_KEY)
-  --base-url       API URL (default: https://letsfg.co/developers)
+  --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
 
 Examples:
   letsfg auth
   letsfg search GDN BER 2026-03-03 --sort price
-  letsfg book off_xxx -p '{"given_name":"Ada",...}' -e ada@example.com
+  letsfg book off_xxx --search-id srch_xxx -p '{"given_name":"Ada","family_name":"Lovelace","born_on":"1990-04-01","gender":"f"}' -e ada@example.com
 `;
 async function main() {
   const args = process.argv.slice(2);
   const command = args.shift();
   try {
     switch (command) {
+      case "auth":
+        await cmdAuth(args);
+        break;
       case "search":
         await cmdSearch(args);
         break;
@@ -338,7 +404,7 @@ async function main() {
         process.exit(1);
     }
   } catch (e) {
-    if (e instanceof LetsFGError) {
+    if (e instanceof LetsFGError || e instanceof BearerTokenError) {
       console.error(`Error: ${e.message}`);
       process.exit(1);
     }

package/dist/index.d.mts

@@ -472,14 +472,24 @@ declare class LetsFG {
     resolveLocation(query: string): Promise<Array<Record<string, unknown>>>;
     /**
      * Unlock a flight offer — confirms live price, reveals direct airline booking URL.
-     * Cost: 1% of ticket price, min $3. Free with Developer API.
+     * Cost: 1% of ticket price, min $3. Developer API only — there is no unlock
+     * endpoint on a PFS Bearer token, so PFS callers use book() directly.
      */
     unlock(offerId: string): Promise<UnlockResult>;
     /**
-     * Book a flight via Developer API — charges ticket price via Stripe, creates real PNR.
-     * Always provide idempotencyKey to prevent double-bookings on retry.
+     * Book a flight.
+     *
+     * PFS (Bearer token): POST /api/agent-book. Free — nothing charged beyond
+     * the ticket price. Pass searchId (from search()'s result). Returns either
+     * { ok, booked: true, order_id } or, when the booking genuinely could not
+     * 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.
      */
-    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string): Promise<BookingResult>;
+    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string, searchId?: string): Promise<BookingResult | Record<string, unknown>>;
     /**
      * Resolve a place name to the city id that searchHotels() needs.
      *

package/dist/index.d.ts

@@ -472,14 +472,24 @@ declare class LetsFG {
     resolveLocation(query: string): Promise<Array<Record<string, unknown>>>;
     /**
      * Unlock a flight offer — confirms live price, reveals direct airline booking URL.
-     * Cost: 1% of ticket price, min $3. Free with Developer API.
+     * Cost: 1% of ticket price, min $3. Developer API only — there is no unlock
+     * endpoint on a PFS Bearer token, so PFS callers use book() directly.
      */
     unlock(offerId: string): Promise<UnlockResult>;
     /**
-     * Book a flight via Developer API — charges ticket price via Stripe, creates real PNR.
-     * Always provide idempotencyKey to prevent double-bookings on retry.
+     * Book a flight.
+     *
+     * PFS (Bearer token): POST /api/agent-book. Free — nothing charged beyond
+     * the ticket price. Pass searchId (from search()'s result). Returns either
+     * { ok, booked: true, order_id } or, when the booking genuinely could not
+     * 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.
      */
-    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string): Promise<BookingResult>;
+    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string, searchId?: string): Promise<BookingResult | Record<string, unknown>>;
     /**
      * Resolve a place name to the city id that searchHotels() needs.
      *

package/dist/index.js

@@ -1677,18 +1677,44 @@ var LetsFG = class {
   }
   /**
    * Unlock a flight offer — confirms live price, reveals direct airline booking URL.
-   * Cost: 1% of ticket price, min $3. Free with Developer API.
+   * Cost: 1% of ticket price, min $3. Developer API only — there is no unlock
+   * endpoint on a PFS Bearer token, so PFS callers use book() directly.
    */
   async unlock(offerId) {
-    this.requireAuth();
-    const path = this.usingPFS ? "/api/unlock" : "/developers/api/v1/bookings/unlock";
-    return this.postWithAuth(path, { offer_id: offerId });
+    this.requireApiKey();
+    return this.post("/developers/api/v1/bookings/unlock", { offer_id: offerId });
   }
   /**
-   * Book a flight via Developer API — charges ticket price via Stripe, creates real PNR.
-   * Always provide idempotencyKey to prevent double-bookings on retry.
+   * Book a flight.
+   *
+   * PFS (Bearer token): POST /api/agent-book. Free — nothing charged beyond
+   * the ticket price. Pass searchId (from search()'s result). Returns either
+   * { ok, booked: true, order_id } or, when the booking genuinely could not
+   * 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.
    */
-  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "") {
+  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "", searchId = "") {
+    this.requireAuth();
+    if (this.usingPFS) {
+      if (!searchId) {
+        throw new LetsFGError(
+          "searchId is required to book via PFS \u2014 pass the search_id from search()'s result.",
+          400
+        );
+      }
+      const passenger = { ...passengers[0] };
+      if (contactPhone && !passenger.phone_number) passenger.phone_number = contactPhone;
+      return this.postWithBearer("/api/agent-book", {
+        search_id: searchId,
+        offer_id: offerId,
+        passenger,
+        contact_email: contactEmail
+      });
+    }
     this.requireApiKey();
     const body = {
       offer_id: offerId,

package/dist/index.mjs

@@ -22,7 +22,7 @@ import {
   offerSummary,
   rankOffers,
   selectDiverseTop
-} from "./chunk-ZX2EIEN7.mjs";
+} from "./chunk-2SNO3AGS.mjs";
 export {
   AuthenticationError,
   BoostedTravel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letsfg",
-  "version": "2026.5.64",
+  "version": "2026.5.66",
   "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",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean",
-    "test": "tsx --test src/index.test.ts",
+    "test": "tsx --test src/index.test.ts src/auth.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [