letsfg 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# BoostedTravel — Agent-Native Flight Search & Booking (Node.js)
+
+Search 400+ airlines at raw airline prices — **$20-50 cheaper** than Booking.com, Kayak, and other OTAs. Zero dependencies. Built for autonomous AI agents — works with OpenClaw, Perplexity Computer, Claude, Cursor, Windsurf, and any MCP-compatible client.
+
+> 🎥 **[Watch the demo](https://github.com/Boosted-Chat/LetsFG#demo-boostedtravel-vs-default-agent-search)** — side-by-side comparison of default agent search vs BoostedTravel CLI.
+
+## Install
+
+```bash
+npm install boostedtravel
+```
+
+## Quick Start (SDK)
+
+```typescript
+import { BoostedTravel, cheapestOffer, offerSummary } from 'boostedtravel';
+
+// Register (one-time)
+const creds = await BoostedTravel.register('my-agent', 'agent@example.com');
+console.log(creds.api_key); // Save this
+
+// Use
+const bt = new BoostedTravel({ apiKey: 'trav_...' });
+
+// Search — FREE
+const flights = await bt.search('GDN', 'BER', '2026-03-03');
+const best = cheapestOffer(flights);
+console.log(offerSummary(best));
+
+// Unlock — $1
+const unlock = await bt.unlock(best.id);
+
+// Book — FREE after unlock
+const booking = 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'
+);
+console.log(`PNR: ${booking.booking_reference}`);
+```
+
+## Quick Start (CLI)
+
+```bash
+export BOOSTEDTRAVEL_API_KEY=trav_...
+
+boostedtravel search GDN BER 2026-03-03 --sort price
+boostedtravel search LON BCN 2026-04-01 --json  # Machine-readable
+boostedtravel unlock off_xxx
+boostedtravel book off_xxx -p '{"id":"pas_xxx","given_name":"John",...}' -e john@example.com
+```
+
+## API
+
+### `new BoostedTravel({ 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.me()`
+### `BoostedTravel.register(agentName, email, baseUrl?, ownerName?, description?)`
+
+### Helpers
+- `offerSummary(offer)` — One-line string summary
+- `cheapestOffer(result)` — Get cheapest offer from search
+
+### `searchLocal(origin, destination, dateFrom, options?)`
+
+Search 75 airline connectors locally (no API key needed). Requires Python + `boostedtravel` installed.
+
+```typescript
+import { searchLocal } from 'boostedtravel';
+
+const result = await searchLocal('GDN', 'BCN', '2026-06-15');
+console.log(result.total_results);
+
+// Limit browser concurrency for constrained environments
+const result2 = await searchLocal('GDN', 'BCN', '2026-06-15', { maxBrowsers: 4 });
+```
+
+### `systemInfo()`
+
+Get system resource profile and recommended concurrency settings.
+
+```typescript
+import { systemInfo } from 'boostedtravel';
+
+const info = await systemInfo();
+console.log(info);
+// { platform: 'win32', cpu_cores: 16, ram_total_gb: 31.2, ram_available_gb: 14.7,
+//   tier: 'standard', recommended_max_browsers: 8, current_max_browsers: 8 }
+```
+
+## Zero Dependencies
+
+Uses native `fetch` (Node 18+). No `axios`, no `node-fetch`, nothing. Safe for sandboxed environments.
+
+## Performance Tuning
+
+Local search auto-scales browser concurrency based on available RAM. Override with `maxBrowsers`:
+
+```typescript
+// Limit to 4 concurrent browsers
+await searchLocal('LHR', 'BCN', '2026-04-15', { maxBrowsers: 4 });
+```
+
+Or set the `BOOSTEDTRAVEL_MAX_BROWSERS` environment variable globally.
+
+## License
+
+MIT

package/dist/chunk-LKAF7U4R.mjs

@@ -0,0 +1,460 @@
+// 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 }
+  });
+  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://api.letsfg.co";
+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.
+   *
+   * @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 = {}) {
+    this.requireApiKey();
+    const body = {
+      origin: origin.toUpperCase(),
+      destination: destination.toUpperCase(),
+      date_from: dateFrom,
+      adults: options.adults ?? 1,
+      children: options.children ?? 0,
+      infants: options.infants ?? 0,
+      max_stopovers: options.maxStopovers ?? 2,
+      currency: options.currency ?? "EUR",
+      limit: options.limit ?? 20,
+      sort: options.sort ?? "price"
+    };
+    if (options.returnDate) body.return_from = options.returnDate;
+    if (options.cabinClass) body.cabin_class = options.cabinClass;
+    return this.post("/api/v1/flights/search", body);
+  }
+  /**
+   * Resolve a city/airport name to IATA codes.
+   */
+  async resolveLocation(query) {
+    this.requireApiKey();
+    const data = await this.get(`/api/v1/flights/locations/${encodeURIComponent(query)}`);
+    if (Array.isArray(data)) return data;
+    if (data && Array.isArray(data.locations)) return data.locations;
+    return data ? [data] : [];
+  }
+  /**
+   * Unlock a flight offer — $1 fee.
+   * Confirms price, reserves for 30 minutes.
+   */
+  async unlock(offerId) {
+    this.requireApiKey();
+    return this.post("/api/v1/bookings/unlock", { offer_id: offerId });
+  }
+  /**
+   * Book a flight — FREE after unlock.
+   * 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 (payment token).
+   */
+  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 ($1 fee). 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();
+    });
+  }
+  /**
+   * 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",
+          ...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
+};

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node