letsfg 1.0.0

package/dist/index.d.ts

@@ -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 };