letsfg 1.0.0

package/dist/cli.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+import {
+  LetsFG,
+  LetsFGError,
+  offerSummary
+} from "./chunk-LKAF7U4R.mjs";
+
+// src/cli.ts
+function getFlag(args, flag, alias) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === flag || alias && args[i] === alias) {
+      const val = args[i + 1];
+      args.splice(i, 2);
+      return val;
+    }
+    if (args[i].startsWith(`${flag}=`)) {
+      const val = args[i].split("=").slice(1).join("=");
+      args.splice(i, 1);
+      return val;
+    }
+  }
+  return void 0;
+}
+function hasFlag(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx >= 0) {
+    args.splice(idx, 1);
+    return true;
+  }
+  return false;
+}
+function getAllFlags(args, flag, alias) {
+  const results = [];
+  let i = 0;
+  while (i < args.length) {
+    if (args[i] === flag || alias && args[i] === alias) {
+      results.push(args[i + 1]);
+      args.splice(i, 2);
+    } else {
+      i++;
+    }
+  }
+  return results;
+}
+async function cmdSearch(args) {
+  const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
+  const apiKey = getFlag(args, "--api-key", "-k");
+  const baseUrl = getFlag(args, "--base-url");
+  const returnDate = getFlag(args, "--return", "-r");
+  const adults = parseInt(getFlag(args, "--adults", "-a") || "1");
+  const cabin = getFlag(args, "--cabin", "-c");
+  const stops = parseInt(getFlag(args, "--max-stops", "-s") || "2");
+  const currency = getFlag(args, "--currency") || "EUR";
+  const limit = parseInt(getFlag(args, "--limit", "-l") || "20");
+  const sort = getFlag(args, "--sort") || "price";
+  const [origin, destination, date] = args;
+  if (!origin || !destination || !date) {
+    console.error("Usage: letsfg search <origin> <destination> <date> [options]");
+    process.exit(1);
+  }
+  const bt = new LetsFG({ apiKey, baseUrl });
+  const result = await bt.search(origin, destination, date, {
+    returnDate,
+    adults,
+    cabinClass: cabin,
+    maxStopovers: stops,
+    currency,
+    limit,
+    sort
+  });
+  if (jsonOut) {
+    console.log(JSON.stringify({
+      passenger_ids: result.passenger_ids,
+      total_results: result.total_results,
+      offers: result.offers.map((o) => ({
+        id: o.id,
+        price: o.price,
+        currency: o.currency,
+        airlines: o.airlines,
+        owner_airline: o.owner_airline,
+        route: [o.outbound.segments[0]?.origin, ...o.outbound.segments.map((s) => s.destination)].join(" \u2192 "),
+        duration_seconds: o.outbound.total_duration_seconds,
+        stopovers: o.outbound.stopovers,
+        conditions: o.conditions,
+        is_locked: o.is_locked
+      }))
+    }, null, 2));
+    return;
+  }
+  if (!result.offers.length) {
+    console.log(`No flights found for ${origin} \u2192 ${destination} on ${date}`);
+    return;
+  }
+  console.log(`
+  ${result.total_results} offers  |  ${origin} \u2192 ${destination}  |  ${date}`);
+  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(`
+  To unlock: letsfg unlock <offer_id>`);
+  console.log(`  Passenger IDs needed for booking: ${JSON.stringify(result.passenger_ids)}
+`);
+}
+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(`    $1 unlock fee charged`);
+    console.log(`
+    Next: letsfg book ${offerId} --passenger '{...}' --email you@example.com
+`);
+  } else {
+    console.error(`  \u2717 Unlock failed: ${result.message}`);
+    process.exit(1);
+  }
+}
+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 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`);
+    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);
+  if (jsonOut) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.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}
+`);
+  } else {
+    console.error(`  \u2717 Booking failed`);
+    console.error(JSON.stringify(result.details, null, 2));
+    process.exit(1);
+  }
+}
+async function cmdLocations(args) {
+  const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
+  const apiKey = getFlag(args, "--api-key", "-k");
+  const baseUrl = getFlag(args, "--base-url");
+  const query = args[0];
+  if (!query) {
+    console.error("Usage: letsfg locations <city-or-airport-name>");
+    process.exit(1);
+  }
+  const bt = new LetsFG({ apiKey, baseUrl });
+  const result = await bt.resolveLocation(query);
+  if (jsonOut) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (!result.length) {
+    console.log(`No locations found for '${query}'`);
+    return;
+  }
+  for (const loc of result) {
+    const iata = (loc.iata_code || "???").padEnd(5);
+    const name = loc.name || "";
+    const type = loc.type || "";
+    const city = loc.city_name || "";
+    const country = loc.country || "";
+    console.log(`  ${iata}  ${name} (${type}) \u2014 ${city}, ${country}`);
+  }
+}
+async function cmdRegister(args) {
+  const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
+  const baseUrl = getFlag(args, "--base-url");
+  const name = getFlag(args, "--name", "-n");
+  const email = getFlag(args, "--email", "-e");
+  const owner = getFlag(args, "--owner") || "";
+  const desc = getFlag(args, "--desc") || "";
+  if (!name || !email) {
+    console.error("Usage: letsfg register --name my-agent --email agent@example.com");
+    process.exit(1);
+  }
+  const result = await LetsFG.register(name, email, baseUrl, owner, desc);
+  if (jsonOut) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`
+  \u2713 Agent registered!`);
+  console.log(`    Agent ID: ${result.agent_id}`);
+  console.log(`    API Key:  ${result.api_key}`);
+  console.log(`
+    Save your API key:`);
+  console.log(`    export LETSFG_API_KEY=${result.api_key}`);
+  console.log(`
+    Next: LetsFG setup-payment --token tok_visa
+`);
+}
+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";
+  const bt = new LetsFG({ apiKey, baseUrl });
+  const result = await bt.setupPayment(token);
+  if (jsonOut) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.status === "ready") {
+    console.log(`
+  \u2713 Payment ready! You can now unlock offers and book flights.
+`);
+  } else {
+    console.error(`  \u2717 Payment setup failed: ${result.message || result.status}`);
+    process.exit(1);
+  }
+}
+async function cmdMe(args) {
+  const jsonOut = hasFlag(args, "--json") || hasFlag(args, "-j");
+  const apiKey = getFlag(args, "--api-key", "-k");
+  const baseUrl = getFlag(args, "--base-url");
+  const bt = new LetsFG({ apiKey, baseUrl });
+  const profile = await bt.me();
+  if (jsonOut) {
+    console.log(JSON.stringify(profile, null, 2));
+    return;
+  }
+  const p = profile;
+  const u = p.usage || {};
+  console.log(`
+  Agent: ${p.agent_name} (${p.agent_id})`);
+  console.log(`  Email: ${p.email}`);
+  console.log(`  Tier:  ${p.tier}`);
+  console.log(`  Payment: ${p.payment_ready ? "\u2713 Ready" : "\u2717 Not set up"}`);
+  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)}
+`);
+}
+var HELP = `
+LetsFG \u2014 Agent-native flight search & booking.
+
+Search 400+ airlines at raw airline prices \u2014 $20-50 cheaper than OTAs.
+Search is FREE. Unlock: $1. Book: FREE after unlock.
+
+Commands:
+  search <origin> <dest> <date>   Search for flights (FREE)
+  locations <query>               Resolve city name to IATA codes
+  unlock <offer_id>               Unlock offer ($1)
+  book <offer_id> --passenger ... Book flight (FREE after unlock)
+  register --name ... --email ... Register new agent
+  setup-payment                   Set up payment card
+  me                              Show agent profile
+
+Options:
+  --json, -j       Output raw JSON
+  --api-key, -k    API key (or set LETSFG_API_KEY)
+  --base-url       API URL (default: https://api.letsfg.co)
+
+Examples:
+  letsfg search GDN BER 2026-03-03 --sort price
+  letsfg search LON BCN 2026-04-01 --return 2026-04-08 --json
+  letsfg unlock off_xxx
+  letsfg book off_xxx -p '{"id":"pas_xxx","given_name":"John","family_name":"Doe","born_on":"1990-01-15"}' -e john@ex.com
+`;
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args.shift();
+  try {
+    switch (command) {
+      case "search":
+        await cmdSearch(args);
+        break;
+      case "unlock":
+        await cmdUnlock(args);
+        break;
+      case "book":
+        await cmdBook(args);
+        break;
+      case "locations":
+        await cmdLocations(args);
+        break;
+      case "register":
+        await cmdRegister(args);
+        break;
+      case "setup-payment":
+        await cmdSetupPayment(args);
+        break;
+      case "me":
+        await cmdMe(args);
+        break;
+      case "--help":
+      case "-h":
+      case "help":
+      case void 0:
+        console.log(HELP);
+        break;
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.log(HELP);
+        process.exit(1);
+    }
+  } catch (e) {
+    if (e instanceof LetsFGError) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+    throw e;
+  }
+}
+main();

package/dist/index.d.mts

@@ -0,0 +1,278 @@
+/**
+ * LetsFG — Agent-native flight search & booking SDK for Node.js/TypeScript.
+ *
+ * 75 airline connectors run locally via Python + backend API for enterprise GDS/NDC sources.
+ * Zero external JS dependencies. Uses native fetch (Node 18+).
+ *
+ * @example
+ * ```ts
+ * import { LetsFG, searchLocal } from 'letsfg';
+ *
+ * // Local search — FREE, no API key
+ * const local = await searchLocal('SHA', 'CTU', '2026-03-20');
+ *
+ * // Full API — search + unlock + book
+ * const bt = new LetsFG({ apiKey: 'trav_...' });
+ * const flights = await bt.search('GDN', 'BER', '2026-03-03');
+ * ```
+ */
+interface FlightSegment {
+    airline: string;
+    airline_name: string;
+    flight_no: string;
+    origin: string;
+    destination: string;
+    origin_city: string;
+    destination_city: string;
+    departure: string;
+    arrival: string;
+    duration_seconds: number;
+    cabin_class: string;
+    aircraft: string;
+}
+interface FlightRoute {
+    segments: FlightSegment[];
+    total_duration_seconds: number;
+    stopovers: number;
+}
+interface FlightOffer {
+    id: string;
+    price: number;
+    currency: string;
+    price_formatted: string;
+    outbound: FlightRoute;
+    inbound: FlightRoute | null;
+    airlines: string[];
+    owner_airline: string;
+    bags_price: Record<string, number>;
+    availability_seats: number | null;
+    conditions: Record<string, string>;
+    is_locked: boolean;
+    fetched_at: string;
+    booking_url: string;
+}
+interface FlightSearchResult {
+    search_id: string;
+    offer_request_id: string;
+    passenger_ids: string[];
+    origin: string;
+    destination: string;
+    currency: string;
+    offers: FlightOffer[];
+    total_results: number;
+    search_params: Record<string, unknown>;
+    pricing_note: string;
+}
+interface UnlockResult {
+    offer_id: string;
+    unlock_status: string;
+    payment_charged: boolean;
+    payment_amount_cents: number;
+    payment_currency: string;
+    payment_intent_id: string;
+    confirmed_price: number | null;
+    confirmed_currency: string;
+    offer_expires_at: string;
+    message: string;
+}
+interface Passenger {
+    id: string;
+    given_name: string;
+    family_name: string;
+    born_on: string;
+    gender?: string;
+    title?: string;
+    email?: string;
+    phone_number?: string;
+}
+interface BookingResult {
+    booking_id: string;
+    status: string;
+    booking_type: string;
+    offer_id: string;
+    flight_price: number;
+    service_fee: number;
+    service_fee_percentage: number;
+    total_charged: number;
+    currency: string;
+    order_id: string;
+    booking_reference: string;
+    unlock_payment_id: string;
+    fee_payment_id: string;
+    created_at: string;
+    details: Record<string, unknown>;
+}
+interface SearchOptions {
+    returnDate?: string;
+    adults?: number;
+    children?: number;
+    infants?: number;
+    cabinClass?: 'M' | 'W' | 'C' | 'F';
+    maxStopovers?: number;
+    currency?: string;
+    limit?: number;
+    sort?: 'price' | 'duration';
+    /** Max concurrent browser instances (1-32). Omit for auto-detect based on system RAM. */
+    maxBrowsers?: number;
+}
+interface CheckoutProgress {
+    status: string;
+    step: string;
+    step_index: number;
+    airline: string;
+    source: string;
+    offer_id: string;
+    total_price: number;
+    currency: string;
+    booking_url: string;
+    screenshot_b64: string;
+    message: string;
+    can_complete_manually: boolean;
+    elapsed_seconds: number;
+    details: Record<string, unknown>;
+}
+interface LetsFGConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+declare const ErrorCode: {
+    readonly SUPPLIER_TIMEOUT: "SUPPLIER_TIMEOUT";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly INVALID_IATA: "INVALID_IATA";
+    readonly INVALID_DATE: "INVALID_DATE";
+    readonly INVALID_PASSENGERS: "INVALID_PASSENGERS";
+    readonly UNSUPPORTED_ROUTE: "UNSUPPORTED_ROUTE";
+    readonly MISSING_PARAMETER: "MISSING_PARAMETER";
+    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
+    readonly AUTH_INVALID: "AUTH_INVALID";
+    readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
+    readonly PAYMENT_DECLINED: "PAYMENT_DECLINED";
+    readonly OFFER_EXPIRED: "OFFER_EXPIRED";
+    readonly OFFER_NOT_UNLOCKED: "OFFER_NOT_UNLOCKED";
+    readonly FARE_CHANGED: "FARE_CHANGED";
+    readonly ALREADY_BOOKED: "ALREADY_BOOKED";
+    readonly BOOKING_FAILED: "BOOKING_FAILED";
+};
+type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare const ErrorCategory: {
+    readonly TRANSIENT: "transient";
+    readonly VALIDATION: "validation";
+    readonly BUSINESS: "business";
+};
+type ErrorCategoryType = (typeof ErrorCategory)[keyof typeof ErrorCategory];
+declare class LetsFGError extends Error {
+    statusCode: number;
+    response: Record<string, unknown>;
+    errorCode: string;
+    errorCategory: ErrorCategoryType;
+    isRetryable: boolean;
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>, errorCode?: string);
+}
+declare class AuthenticationError extends LetsFGError {
+    constructor(message: string, response?: Record<string, unknown>);
+}
+declare class PaymentRequiredError extends LetsFGError {
+    constructor(message: string, response?: Record<string, unknown>);
+}
+declare class OfferExpiredError extends LetsFGError {
+    constructor(message: string, response?: Record<string, unknown>);
+}
+declare class ValidationError extends LetsFGError {
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>, errorCode?: string);
+}
+/** One-line offer summary */
+declare function offerSummary(offer: FlightOffer): string;
+/** Get cheapest offer from search results */
+declare function cheapestOffer(result: FlightSearchResult): FlightOffer | null;
+/**
+ * Search flights using 73 local airline connectors — FREE, no API key needed.
+ *
+ * Requires: pip install letsfg && playwright install chromium
+ *
+ * @param origin - IATA code (e.g., "SHA")
+ * @param destination - IATA code (e.g., "CTU")
+ * @param dateFrom - Departure date "YYYY-MM-DD"
+ * @param options - Optional: currency, adults, limit, etc.
+ */
+declare function searchLocal(origin: string, destination: string, dateFrom: string, options?: Partial<SearchOptions>): Promise<FlightSearchResult>;
+declare class LetsFG {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(config?: LetsFGConfig);
+    private requireApiKey;
+    /**
+     * 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
+     */
+    search(origin: string, destination: string, dateFrom: string, options?: SearchOptions): Promise<FlightSearchResult>;
+    /**
+     * Resolve a city/airport name to IATA codes.
+     */
+    resolveLocation(query: string): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Unlock a flight offer — $1 fee.
+     * Confirms price, reserves for 30 minutes.
+     */
+    unlock(offerId: string): Promise<UnlockResult>;
+    /**
+     * Book a flight — FREE after unlock.
+     * Creates a real airline reservation with PNR.
+     *
+     * Always provide idempotencyKey to prevent double-bookings on retry.
+     */
+    book(offerId: string, passengers: Passenger[], contactEmail: string, contactPhone?: string, idempotencyKey?: string): Promise<BookingResult>;
+    /**
+     * Set up payment method (payment token).
+     */
+    setupPayment(token?: string): Promise<Record<string, unknown>>;
+    /**
+     * 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
+     */
+    startCheckout(offerId: string, passengers: Passenger[], checkoutToken: string): Promise<CheckoutProgress>;
+    /**
+     * 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()
+     */
+    startCheckoutLocal(offer: FlightOffer, passengers: Passenger[], checkoutToken: string): Promise<CheckoutProgress>;
+    /**
+     * Get current agent profile and usage stats.
+     */
+    me(): Promise<Record<string, unknown>>;
+    /**
+     * Register a new agent — no API key needed.
+     */
+    static register(agentName: string, email: string, baseUrl?: string, ownerName?: string, description?: string): Promise<Record<string, unknown>>;
+    private post;
+    private get;
+    private request;
+}
+/**
+ * Get system resource profile and recommended concurrency settings.
+ * Calls the Python backend's system-info detection.
+ */
+declare function systemInfo(): Promise<Record<string, unknown>>;
+
+declare const BoostedTravel: typeof LetsFG;
+declare const BoostedTravelError: typeof LetsFGError;
+type BoostedTravelConfig = LetsFGConfig;
+
+export { AuthenticationError, type BookingResult, BoostedTravel, type BoostedTravelConfig, BoostedTravelError, type CheckoutProgress, ErrorCategory, type ErrorCategoryType, ErrorCode, type ErrorCodeType, type FlightOffer, type FlightRoute, type FlightSearchResult, type FlightSegment, LetsFG, type LetsFGConfig, LetsFGError, OfferExpiredError, type Passenger, PaymentRequiredError, type SearchOptions, type UnlockResult, ValidationError, cheapestOffer, LetsFG as default, systemInfo as getSystemInfo, searchLocal as localSearch, offerSummary, searchLocal, systemInfo };