letsfg 2026.5.53 → 2026.5.55

package/dist/index.mjs

@@ -8,13 +8,21 @@ import {
   LetsFGError,
   OfferExpiredError,
   PaymentRequiredError,
+  TRIP_PURPOSES,
   ValidationError,
   cheapestOffer,
+  deduplicateOffers,
+  extractOfferDetailSignals,
+  getOfferDetailBadges,
+  getOfferDetailPromptNotes,
+  getPrimaryTripPurpose,
+  getProfileLabel,
   index_default,
+  normalizeTripPurposes,
   offerSummary,
-  searchLocal,
-  systemInfo
-} from "./chunk-LBHJ4GE4.mjs";
+  rankOffers,
+  selectDiverseTop
+} from "./chunk-7C3EKQ37.mjs";
 export {
   AuthenticationError,
   BoostedTravel,
@@ -25,12 +33,18 @@ export {
   LetsFGError,
   OfferExpiredError,
   PaymentRequiredError,
+  TRIP_PURPOSES,
   ValidationError,
   cheapestOffer,
+  deduplicateOffers,
   index_default as default,
-  systemInfo as getSystemInfo,
-  searchLocal as localSearch,
+  extractOfferDetailSignals,
+  getOfferDetailBadges,
+  getOfferDetailPromptNotes,
+  getPrimaryTripPurpose,
+  getProfileLabel,
+  normalizeTripPurposes,
   offerSummary,
-  searchLocal,
-  systemInfo
+  rankOffers,
+  selectDiverseTop
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "letsfg",
-  "version": "2026.5.53",
-  "description": "Flight search & booking for AI agents. 200+ airline connectors run locally. Free search — get direct booking URLs via letsfg.co or the Developer API.",
+  "version": "2026.5.55",
+  "description": "Flight search & booking for AI agents. Server-side engine covers hundreds of airlines. Free search via Bearer token or prepaid Developer API. Includes open-source ranking engine.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -15,6 +15,7 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean",
+    "test": "tsx --test src/index.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -42,6 +43,7 @@
   "devDependencies": {
     "@types/node": "^25.3.3",
     "tsup": "^8.0.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.3.0"
   },
   "engines": {

package/dist/chunk-LBHJ4GE4.mjs

@@ -1,487 +0,0 @@
-// src/index.ts
-var ErrorCode = {
-  // Transient (safe to retry after short delay)
-  SUPPLIER_TIMEOUT: "SUPPLIER_TIMEOUT",
-  RATE_LIMITED: "RATE_LIMITED",
-  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
-  NETWORK_ERROR: "NETWORK_ERROR",
-  // Validation (fix input, then retry)
-  INVALID_IATA: "INVALID_IATA",
-  INVALID_DATE: "INVALID_DATE",
-  INVALID_PASSENGERS: "INVALID_PASSENGERS",
-  UNSUPPORTED_ROUTE: "UNSUPPORTED_ROUTE",
-  MISSING_PARAMETER: "MISSING_PARAMETER",
-  INVALID_PARAMETER: "INVALID_PARAMETER",
-  // Business (requires human decision)
-  AUTH_INVALID: "AUTH_INVALID",
-  PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
-  PAYMENT_DECLINED: "PAYMENT_DECLINED",
-  OFFER_EXPIRED: "OFFER_EXPIRED",
-  OFFER_NOT_UNLOCKED: "OFFER_NOT_UNLOCKED",
-  FARE_CHANGED: "FARE_CHANGED",
-  ALREADY_BOOKED: "ALREADY_BOOKED",
-  BOOKING_FAILED: "BOOKING_FAILED"
-};
-var ErrorCategory = {
-  TRANSIENT: "transient",
-  VALIDATION: "validation",
-  BUSINESS: "business"
-};
-var CODE_TO_CATEGORY = {
-  [ErrorCode.SUPPLIER_TIMEOUT]: ErrorCategory.TRANSIENT,
-  [ErrorCode.RATE_LIMITED]: ErrorCategory.TRANSIENT,
-  [ErrorCode.SERVICE_UNAVAILABLE]: ErrorCategory.TRANSIENT,
-  [ErrorCode.NETWORK_ERROR]: ErrorCategory.TRANSIENT,
-  [ErrorCode.INVALID_IATA]: ErrorCategory.VALIDATION,
-  [ErrorCode.INVALID_DATE]: ErrorCategory.VALIDATION,
-  [ErrorCode.INVALID_PASSENGERS]: ErrorCategory.VALIDATION,
-  [ErrorCode.UNSUPPORTED_ROUTE]: ErrorCategory.VALIDATION,
-  [ErrorCode.MISSING_PARAMETER]: ErrorCategory.VALIDATION,
-  [ErrorCode.INVALID_PARAMETER]: ErrorCategory.VALIDATION,
-  [ErrorCode.AUTH_INVALID]: ErrorCategory.BUSINESS,
-  [ErrorCode.PAYMENT_REQUIRED]: ErrorCategory.BUSINESS,
-  [ErrorCode.PAYMENT_DECLINED]: ErrorCategory.BUSINESS,
-  [ErrorCode.OFFER_EXPIRED]: ErrorCategory.BUSINESS,
-  [ErrorCode.OFFER_NOT_UNLOCKED]: ErrorCategory.BUSINESS,
-  [ErrorCode.FARE_CHANGED]: ErrorCategory.BUSINESS,
-  [ErrorCode.ALREADY_BOOKED]: ErrorCategory.BUSINESS,
-  [ErrorCode.BOOKING_FAILED]: ErrorCategory.BUSINESS
-};
-function inferErrorCode(statusCode, detail) {
-  const d = detail.toLowerCase();
-  if (statusCode === 401) return ErrorCode.AUTH_INVALID;
-  if (statusCode === 402) return d.includes("declined") ? ErrorCode.PAYMENT_DECLINED : ErrorCode.PAYMENT_REQUIRED;
-  if (statusCode === 410) return ErrorCode.OFFER_EXPIRED;
-  if (statusCode === 422) {
-    if (d.includes("iata") || d.includes("airport")) return ErrorCode.INVALID_IATA;
-    if (d.includes("date")) return ErrorCode.INVALID_DATE;
-    if (d.includes("passenger")) return ErrorCode.INVALID_PASSENGERS;
-    if (d.includes("route")) return ErrorCode.UNSUPPORTED_ROUTE;
-    return ErrorCode.INVALID_PARAMETER;
-  }
-  if (statusCode === 429) return ErrorCode.RATE_LIMITED;
-  if (statusCode === 503) return ErrorCode.SERVICE_UNAVAILABLE;
-  if (statusCode === 504) return ErrorCode.SUPPLIER_TIMEOUT;
-  if (statusCode === 409) return ErrorCode.ALREADY_BOOKED;
-  return statusCode >= 500 ? ErrorCode.BOOKING_FAILED : ErrorCode.INVALID_PARAMETER;
-}
-var LetsFGError = class extends Error {
-  statusCode;
-  response;
-  errorCode;
-  errorCategory;
-  isRetryable;
-  constructor(message, statusCode = 0, response = {}, errorCode = "") {
-    super(message);
-    this.name = "LetsFGError";
-    this.statusCode = statusCode;
-    this.response = response;
-    this.errorCode = errorCode || response.error_code || "";
-    this.errorCategory = CODE_TO_CATEGORY[this.errorCode] || ErrorCategory.BUSINESS;
-    this.isRetryable = this.errorCategory === ErrorCategory.TRANSIENT;
-  }
-};
-var AuthenticationError = class extends LetsFGError {
-  constructor(message, response = {}) {
-    super(message, 401, response, ErrorCode.AUTH_INVALID);
-    this.name = "AuthenticationError";
-  }
-};
-var PaymentRequiredError = class extends LetsFGError {
-  constructor(message, response = {}) {
-    const code = message.toLowerCase().includes("declined") ? ErrorCode.PAYMENT_DECLINED : ErrorCode.PAYMENT_REQUIRED;
-    super(message, 402, response, code);
-    this.name = "PaymentRequiredError";
-  }
-};
-var OfferExpiredError = class extends LetsFGError {
-  constructor(message, response = {}) {
-    super(message, 410, response, ErrorCode.OFFER_EXPIRED);
-    this.name = "OfferExpiredError";
-  }
-};
-var ValidationError = class extends LetsFGError {
-  constructor(message, statusCode = 422, response = {}, errorCode = "") {
-    super(message, statusCode, response, errorCode || ErrorCode.INVALID_PARAMETER);
-    this.name = "ValidationError";
-  }
-};
-function routeStr(route) {
-  if (!route.segments.length) return "";
-  const codes = [route.segments[0].origin, ...route.segments.map((s) => s.destination)];
-  return codes.join(" \u2192 ");
-}
-function durationHuman(seconds) {
-  const h = Math.floor(seconds / 3600);
-  const m = Math.floor(seconds % 3600 / 60);
-  return `${h}h${m.toString().padStart(2, "0")}m`;
-}
-function offerSummary(offer) {
-  const route = routeStr(offer.outbound);
-  const dur = durationHuman(offer.outbound.total_duration_seconds);
-  const airline = offer.owner_airline || offer.airlines[0] || "?";
-  return `${offer.currency} ${offer.price.toFixed(2)} | ${airline} | ${route} | ${dur} | ${offer.outbound.stopovers} stop(s)`;
-}
-function cheapestOffer(result) {
-  if (!result.offers.length) return null;
-  return result.offers.reduce((min, o) => o.price < min.price ? o : min, result.offers[0]);
-}
-async function searchLocal(origin, destination, dateFrom, options = {}) {
-  const { spawn } = await import("child_process");
-  const params = JSON.stringify({
-    origin: origin.toUpperCase(),
-    destination: destination.toUpperCase(),
-    date_from: dateFrom,
-    adults: options.adults ?? 1,
-    children: options.children ?? 0,
-    currency: options.currency ?? "EUR",
-    limit: options.limit ?? 50,
-    return_date: options.returnDate,
-    cabin_class: options.cabinClass,
-    ...options.maxBrowsers != null && { max_browsers: options.maxBrowsers },
-    ...options.mode != null && { mode: options.mode }
-  });
-  return new Promise((resolve, reject) => {
-    const pythonCmd = process.platform === "win32" ? "python" : "python3";
-    const child = spawn(pythonCmd, ["-m", "letsfg.local"], {
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => {
-      stdout += d.toString();
-    });
-    child.stderr.on("data", (d) => {
-      stderr += d.toString();
-    });
-    child.on("close", (code) => {
-      try {
-        const data = JSON.parse(stdout);
-        if (data.error) reject(new LetsFGError(data.error));
-        else resolve(data);
-      } catch {
-        reject(new LetsFGError(
-          `Python search failed (code ${code}): ${stdout || stderr}
-Make sure LetsFG is installed: pip install letsfg && playwright install chromium`
-        ));
-      }
-    });
-    child.on("error", (err) => {
-      reject(new LetsFGError(
-        `Cannot start Python: ${err.message}
-Install: pip install letsfg && playwright install chromium`
-      ));
-    });
-    child.stdin.write(params);
-    child.stdin.end();
-  });
-}
-var DEFAULT_BASE_URL = "https://letsfg.co/developers";
-var LetsFG = class {
-  apiKey;
-  baseUrl;
-  timeout;
-  constructor(config = {}) {
-    this.apiKey = config.apiKey || process.env.LETSFG_API_KEY || "";
-    this.baseUrl = (config.baseUrl || process.env.LETSFG_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
-    this.timeout = config.timeout || 3e4;
-  }
-  requireApiKey() {
-    if (!this.apiKey) {
-      throw new AuthenticationError(
-        "API key required for this operation. Set apiKey in config or LETSFG_API_KEY env var.\nNote: searchLocal() works without an API key."
-      );
-    }
-  }
-  // ── Core methods ─────────────────────────────────────────────────────
-  /**
-   * Search for flights — FREE, unlimited, runs locally on your machine.
-   *
-   * Uses 200 airline connectors via Python subprocess. No backend call.
-   * Requires: pip install letsfg && playwright install chromium
-   *
-   * @param origin - IATA code (e.g., "GDN", "LON")
-   * @param destination - IATA code (e.g., "BER", "BCN")
-   * @param dateFrom - Departure date "YYYY-MM-DD"
-   * @param options - Optional search parameters
-   */
-  async search(origin, destination, dateFrom, options = {}) {
-    return searchLocal(origin, destination, dateFrom, options);
-  }
-  /**
-   * Resolve a city/airport name to IATA codes — runs locally, no backend call.
-   */
-  async resolveLocation(query) {
-    const { spawn } = await import("child_process");
-    const params = JSON.stringify({ __resolve_location: true, query });
-    return new Promise((resolve, reject) => {
-      const pythonCmd = process.platform === "win32" ? "python" : "python3";
-      const child = spawn(pythonCmd, ["-m", "letsfg.local"], {
-        stdio: ["pipe", "pipe", "pipe"]
-      });
-      let stdout = "";
-      let stderr = "";
-      child.stdout.on("data", (d) => {
-        stdout += d.toString();
-      });
-      child.stderr.on("data", (d) => {
-        stderr += d.toString();
-      });
-      child.on("close", (code) => {
-        try {
-          const data = JSON.parse(stdout);
-          if (data.error) reject(new LetsFGError(data.error));
-          else resolve(Array.isArray(data) ? data : data.locations || [data]);
-        } catch {
-          reject(new LetsFGError(
-            `Location resolution failed (code ${code}): ${stdout || stderr}`
-          ));
-        }
-      });
-      child.on("error", (err) => {
-        reject(new LetsFGError(`Cannot start Python: ${err.message}`));
-      });
-      child.stdin.write(params);
-      child.stdin.end();
-    });
-  }
-  /**
-   * Unlock a flight offer — FREE with GitHub star.
-   * Confirms price, reserves for 30 minutes.
-   */
-  async unlock(offerId) {
-    this.requireApiKey();
-    return this.post("/api/v1/bookings/unlock", { offer_id: offerId });
-  }
-  /**
-   * Book a flight — charges ticket price via Stripe.
-   * Creates a real airline reservation with PNR.
-   *
-   * Always provide idempotencyKey to prevent double-bookings on retry.
-   */
-  async book(offerId, passengers, contactEmail, contactPhone = "", idempotencyKey = "") {
-    this.requireApiKey();
-    const body = {
-      offer_id: offerId,
-      booking_type: "flight",
-      passengers,
-      contact_email: contactEmail,
-      contact_phone: contactPhone
-    };
-    if (idempotencyKey) body.idempotency_key = idempotencyKey;
-    return this.post("/api/v1/bookings/book", body);
-  }
-  /**
-   * Set up payment method (required before booking).
-   */
-  async setupPayment(token = "tok_visa") {
-    this.requireApiKey();
-    return this.post("/api/v1/agents/setup-payment", { token });
-  }
-  /**
-   * Start automated checkout — drives to payment page, NEVER submits payment.
-   *
-   * Requires unlock first. Returns progress with screenshot and
-   * booking URL for manual completion.
-   *
-   * @param offerId - Offer ID from search results
-   * @param passengers - Passenger details (use test data for safety)
-   * @param checkoutToken - Token from unlock() response
-   */
-  async startCheckout(offerId, passengers, checkoutToken) {
-    this.requireApiKey();
-    return this.post("/api/v1/bookings/start-checkout", {
-      offer_id: offerId,
-      passengers,
-      checkout_token: checkoutToken
-    });
-  }
-  /**
-   * Start checkout locally via Python (runs on your machine).
-   * Requires: pip install letsfg && playwright install chromium
-   *
-   * @param offer - Full FlightOffer object from search results
-   * @param passengers - Passenger details
-   * @param checkoutToken - Token from unlock()
-   */
-  async startCheckoutLocal(offer, passengers, checkoutToken) {
-    const { spawn } = await import("child_process");
-    const input = JSON.stringify({
-      __checkout: true,
-      offer,
-      passengers,
-      checkout_token: checkoutToken,
-      api_key: this.apiKey,
-      base_url: this.baseUrl
-    });
-    return new Promise((resolve, reject) => {
-      const pythonCmd = process.platform === "win32" ? "python" : "python3";
-      const child = spawn(pythonCmd, ["-m", "letsfg.local"], {
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: 18e4
-      });
-      let stdout = "";
-      let stderr = "";
-      child.stdout.on("data", (d) => {
-        stdout += d.toString();
-      });
-      child.stderr.on("data", (d) => {
-        stderr += d.toString();
-      });
-      child.on("close", (code) => {
-        try {
-          const data = JSON.parse(stdout);
-          if (data.error) reject(new LetsFGError(data.error));
-          else resolve(data);
-        } catch {
-          reject(new LetsFGError(`Checkout failed (code ${code}): ${stdout || stderr}`));
-        }
-      });
-      child.on("error", (err) => {
-        reject(new LetsFGError(`Cannot start Python: ${err.message}`));
-      });
-      child.stdin.write(input);
-      child.stdin.end();
-    });
-  }
-  /**
-   * Link GitHub account for FREE unlimited access.
-   *
-   * Star https://github.com/LetsFG/LetsFG, then call this with your username.
-   * Once verified, access is permanent.
-   */
-  async linkGithub(githubUsername) {
-    this.requireApiKey();
-    return this.post("/api/v1/agents/link-github", { github_username: githubUsername });
-  }
-  /**
-   * Get current agent profile and usage stats.
-   */
-  async me() {
-    this.requireApiKey();
-    return this.get("/api/v1/agents/me");
-  }
-  // ── Static methods ───────────────────────────────────────────────────
-  /**
-   * Register a new agent — no API key needed.
-   */
-  static async register(agentName, email, baseUrl, ownerName = "", description = "") {
-    const url = (baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
-    const resp = await fetch(`${url}/api/v1/agents/register`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        agent_name: agentName,
-        email,
-        owner_name: ownerName,
-        description
-      })
-    });
-    const data = await resp.json();
-    if (!resp.ok) {
-      throw new LetsFGError(
-        data.detail || `Registration failed (${resp.status})`,
-        resp.status,
-        data
-      );
-    }
-    return data;
-  }
-  // ── Internal ────────────────────────────────────────────────────────
-  async post(path, body) {
-    return this.request(path, {
-      method: "POST",
-      body: JSON.stringify(body)
-    });
-  }
-  async get(path) {
-    return this.request(path, { method: "GET" });
-  }
-  async request(path, init) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const resp = await fetch(`${this.baseUrl}${path}`, {
-        ...init,
-        headers: {
-          "Content-Type": "application/json",
-          "X-API-Key": this.apiKey,
-          "User-Agent": "LetsFG-js/0.1.0",
-          "X-Client-Type": "js-sdk",
-          ...init.headers || {}
-        },
-        signal: controller.signal
-      });
-      const data = await resp.json();
-      if (!resp.ok) {
-        const detail = data.detail || `API error (${resp.status})`;
-        const code = data.error_code || inferErrorCode(resp.status, detail);
-        if (resp.status === 401) throw new AuthenticationError(detail, data);
-        if (resp.status === 402) throw new PaymentRequiredError(detail, data);
-        if (resp.status === 410) throw new OfferExpiredError(detail, data);
-        if (resp.status === 422) throw new ValidationError(detail, resp.status, data, code);
-        throw new LetsFGError(detail, resp.status, data, code);
-      }
-      return data;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-};
-async function systemInfo() {
-  const { spawn } = await import("child_process");
-  return new Promise((resolve, reject) => {
-    const pythonCmd = process.platform === "win32" ? "python" : "python3";
-    const child = spawn(pythonCmd, ["-m", "letsfg.local"], {
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => {
-      stdout += d.toString();
-    });
-    child.stderr.on("data", (d) => {
-      stderr += d.toString();
-    });
-    child.on("close", (code) => {
-      try {
-        const data = JSON.parse(stdout);
-        if (data.error) reject(new LetsFGError(data.error));
-        else resolve(data);
-      } catch {
-        reject(new LetsFGError(
-          `Python system-info failed (code ${code}): ${stdout || stderr}`
-        ));
-      }
-    });
-    child.on("error", (err) => {
-      reject(new LetsFGError(
-        `Cannot start Python: ${err.message}
-Install: pip install letsfg`
-      ));
-    });
-    child.stdin.write(JSON.stringify({ __system_info: true }));
-    child.stdin.end();
-  });
-}
-var index_default = LetsFG;
-var BoostedTravel = LetsFG;
-var BoostedTravelError = LetsFGError;
-
-export {
-  ErrorCode,
-  ErrorCategory,
-  LetsFGError,
-  AuthenticationError,
-  PaymentRequiredError,
-  OfferExpiredError,
-  ValidationError,
-  offerSummary,
-  cheapestOffer,
-  searchLocal,
-  LetsFG,
-  systemInfo,
-  index_default,
-  BoostedTravel,
-  BoostedTravelError
-};