@furlpay/travel-mcp 0.1.0

package/dist/travala.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TravalaClient = void 0;
+/**
+ * Thin client for the Travala Travel MCP (search side of the composition).
+ *
+ * Travala's Agentic AI Travel Protocol exposes 2.2M+ hotels (Marriott, Hilton,
+ * IHG, …) — expanding to flights — to AI agents, settling in gasless USDC over
+ * x402 on Base. This wrapper is search-only; payment/settlement is FurlPay's job.
+ *
+ * With no key set it returns deterministic demo inventory so the whole
+ * search → pay → book loop runs offline.
+ */
+const DEFAULT_MCP = "https://travel-mcp.travala.com/mcp";
+const round2 = (n) => Math.round(n * 100) / 100;
+function hash(s) {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+const HOTEL_BRANDS = ["Marriott", "Hilton", "IHG", "Accor", "Hyatt"];
+function nightsBetween(checkIn, checkOut) {
+    const a = Date.parse(checkIn);
+    const b = Date.parse(checkOut);
+    if (isNaN(a) || isNaN(b) || b <= a)
+        return 1;
+    return Math.max(1, Math.round((b - a) / 86400000));
+}
+class TravalaClient {
+    constructor(url = process.env.TRAVALA_MCP_URL || DEFAULT_MCP, apiKey, fetchImpl = globalThis.fetch) {
+        this.url = url;
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+    }
+    get live() {
+        return Boolean(this.apiKey);
+    }
+    async searchStays(params) {
+        const nights = nightsBetween(params.checkIn, params.checkOut);
+        if (!this.live)
+            return this.demoStays(params, nights);
+        try {
+            const rows = await this.call("search_stays", { ...params });
+            const stays = rows.map((r) => normaliseStay(r, params, nights));
+            return params.maxNightlyUsd ? stays.filter((s) => s.nightlyUsd <= params.maxNightlyUsd) : stays;
+        }
+        catch {
+            return this.demoStays(params, nights);
+        }
+    }
+    async searchFlights(params) {
+        if (!this.live)
+            return this.demoFlights(params);
+        try {
+            const rows = await this.call("search_flights", { ...params });
+            return rows.map((r) => normaliseFlight(r, params));
+        }
+        catch {
+            return this.demoFlights(params);
+        }
+    }
+    // -- transport (Travala MCP is JSON-RPC over HTTP) ----------------------
+    async call(tool, args) {
+        const res = await this.fetchImpl(this.url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+            },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: tool, arguments: args } }),
+        });
+        if (!res.ok)
+            throw new Error(`Travala MCP HTTP ${res.status}`);
+        const json = await res.json();
+        if (json.error)
+            throw new Error(json.error.message || "Travala MCP error");
+        const content = json.result?.content?.[0];
+        const text = content?.text ?? "[]";
+        return typeof text === "string" ? JSON.parse(text) : text;
+    }
+    // -- deterministic demo inventory ---------------------------------------
+    demoStays(params, nights) {
+        const seed = hash(params.city.toLowerCase());
+        const stays = Array.from({ length: 5 }, (_, i) => {
+            const brand = HOTEL_BRANDS[(seed + i) % HOTEL_BRANDS.length];
+            const nightly = round2(80 + ((seed >> (i + 1)) % 260)); // ~$80–$340
+            return {
+                quoteId: `tvl_demo_${(seed % 0xffff).toString(16)}_${i}`,
+                name: `${brand} ${titleCase(params.city)} ${["Central", "Riverside", "Airport", "Old Town", "Bay"][i]}`,
+                brand,
+                city: titleCase(params.city),
+                stars: 3 + (i % 3),
+                checkIn: params.checkIn,
+                checkOut: params.checkOut,
+                nights,
+                nightlyUsd: nightly,
+                totalUsd: round2(nightly * nights),
+                source: "demo",
+            };
+        });
+        return params.maxNightlyUsd ? stays.filter((s) => s.nightlyUsd <= params.maxNightlyUsd) : stays;
+    }
+    demoFlights(params) {
+        const seed = hash(params.from + params.to);
+        const carriers = ["BA", "LH", "AF", "EK", "QR"];
+        return Array.from({ length: 3 }, (_, i) => ({
+            quoteId: `tvlf_demo_${(seed % 0xffff).toString(16)}_${i}`,
+            carrier: carriers[(seed + i) % carriers.length],
+            from: params.from.toUpperCase(),
+            to: params.to.toUpperCase(),
+            date: params.date,
+            cabin: ["economy", "premium", "business"][i % 3],
+            totalUsd: round2(180 + ((seed >> (i + 2)) % 900)),
+            source: "demo",
+        }));
+    }
+}
+exports.TravalaClient = TravalaClient;
+function normaliseStay(r, p, nights) {
+    const nightly = Number(r.nightlyUsd ?? r.price ?? 0);
+    return {
+        quoteId: String(r.quoteId ?? r.id ?? ""),
+        name: String(r.name ?? "Hotel"),
+        brand: String(r.brand ?? "Independent"),
+        city: String(r.city ?? p.city),
+        stars: Number(r.stars ?? 3),
+        checkIn: p.checkIn,
+        checkOut: p.checkOut,
+        nights,
+        nightlyUsd: nightly,
+        totalUsd: Number(r.totalUsd ?? nightly * nights),
+        source: "travala",
+    };
+}
+function normaliseFlight(r, p) {
+    return {
+        quoteId: String(r.quoteId ?? r.id ?? ""),
+        carrier: String(r.carrier ?? "XX"),
+        from: p.from.toUpperCase(),
+        to: p.to.toUpperCase(),
+        date: p.date,
+        cabin: String(r.cabin ?? "economy"),
+        totalUsd: Number(r.totalUsd ?? r.price ?? 0),
+        source: "travala",
+    };
+}
+function titleCase(s) {
+    return s.replace(/\w\S*/g, (t) => t.charAt(0).toUpperCase() + t.slice(1).toLowerCase());
+}

package/dist/travel.d.ts

@@ -0,0 +1,67 @@
+import { Booking, BookingSource, Flight, RebateAccrual, Stay, TravelOptions } from "./types";
+export { MCC } from "./furlpay";
+export * from "./types";
+/**
+ * FurlPay Travels — composes Travala's Travel MCP (search) with FurlPay's payment
+ * rails (pay). An agent searches inventory, FurlPay checks the spend budget and
+ * issues a credential (x402 proof for the Travala/Base route, or a single-use
+ * MCC-locked Visa VCN for legacy merchants), and the booking accrues the 10%
+ * cbBTC rebate.
+ *
+ * Clone-and-run: with no keys, search and payment simulate end-to-end.
+ */
+export declare class TravelClient {
+    private readonly travala;
+    private readonly pay;
+    private readonly developerWallet?;
+    private readonly bookings;
+    /** Per-agent USDC spend caps for autonomous booking. */
+    private readonly budgets;
+    constructor(opts?: TravelOptions);
+    get live(): boolean;
+    searchStays(p: {
+        city: string;
+        checkIn: string;
+        checkOut: string;
+        maxNightlyUsd?: number;
+        guests?: number;
+    }): Promise<Stay[]>;
+    searchFlights(p: {
+        from: string;
+        to: string;
+        date: string;
+    }): Promise<Flight[]>;
+    setAgentBudget(agentId: string, limitUsd: number): void;
+    getAgentBudget(agentId: string): {
+        limit: number;
+        spent: number;
+        remaining: number;
+    };
+    /**
+     * Authorize a booking. `source: "travala"` pays via x402/USDC on Base; any other
+     * merchant uses `source: "legacy"` → a single-use MCC-locked Visa VCN.
+     * Enforces the agent budget before authorizing.
+     */
+    authorizeBooking(params: {
+        amountUsd: number;
+        source: BookingSource;
+        currency?: string;
+        mcc?: string;
+        agentId?: string;
+        reference?: string;
+    }): Promise<Booking>;
+    /** Mark an authorized booking confirmed (after passkey step-up in a real flow). */
+    confirmBooking(id: string): Booking;
+    cancelBooking(id: string): Booking;
+    getBooking(id: string): Booking | undefined;
+    /** All cbBTC rebate accruals to date and the developer's cumulative share. */
+    listRebates(): {
+        developerWallet?: string;
+        accruals: RebateAccrual[];
+        developerTotalUsd: number;
+        treasuryTotalUsd: number;
+    };
+    private accrueRebate;
+    private require;
+}
+export default TravelClient;

package/dist/travel.js

@@ -0,0 +1,154 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TravelClient = exports.MCC = void 0;
+const furlpay_1 = require("./furlpay");
+const travala_1 = require("./travala");
+var furlpay_2 = require("./furlpay");
+Object.defineProperty(exports, "MCC", { enumerable: true, get: function () { return furlpay_2.MCC; } });
+__exportStar(require("./types"), exports);
+// Travala pays a 10% cbBTC developer rebate on MCP-driven bookings. We split it
+// 7% to the integrating developer, 3% to the FurlPay treasury.
+const REBATE_RATE = 0.1;
+const DEVELOPER_SHARE = 0.7;
+/**
+ * FurlPay Travels — composes Travala's Travel MCP (search) with FurlPay's payment
+ * rails (pay). An agent searches inventory, FurlPay checks the spend budget and
+ * issues a credential (x402 proof for the Travala/Base route, or a single-use
+ * MCC-locked Visa VCN for legacy merchants), and the booking accrues the 10%
+ * cbBTC rebate.
+ *
+ * Clone-and-run: with no keys, search and payment simulate end-to-end.
+ */
+class TravelClient {
+    constructor(opts = {}) {
+        this.bookings = new Map();
+        /** Per-agent USDC spend caps for autonomous booking. */
+        this.budgets = new Map();
+        const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+        this.travala = new travala_1.TravalaClient(opts.travalaMcpUrl || process.env.TRAVALA_MCP_URL, process.env.TRAVALA_API_KEY, fetchImpl);
+        this.pay = new furlpay_1.FurlPayPay(opts.furlpayApiKey || process.env.FURLPAY_API_KEY, opts.furlpayBaseUrl, fetchImpl);
+        this.developerWallet = opts.developerWallet || process.env.FURLPAY_DEVELOPER_WALLET;
+    }
+    get live() {
+        return this.pay.live;
+    }
+    // -- search -------------------------------------------------------------
+    searchStays(p) {
+        return this.travala.searchStays(p);
+    }
+    searchFlights(p) {
+        return this.travala.searchFlights(p);
+    }
+    // -- budget policy ------------------------------------------------------
+    setAgentBudget(agentId, limitUsd) {
+        const existing = this.budgets.get(agentId);
+        this.budgets.set(agentId, { limit: limitUsd, spent: existing?.spent ?? 0 });
+    }
+    getAgentBudget(agentId) {
+        const b = this.budgets.get(agentId) ?? { limit: Infinity, spent: 0 };
+        return { limit: b.limit, spent: b.spent, remaining: b.limit - b.spent };
+    }
+    // -- book ---------------------------------------------------------------
+    /**
+     * Authorize a booking. `source: "travala"` pays via x402/USDC on Base; any other
+     * merchant uses `source: "legacy"` → a single-use MCC-locked Visa VCN.
+     * Enforces the agent budget before authorizing.
+     */
+    async authorizeBooking(params) {
+        if (params.amountUsd <= 0)
+            throw new Error("amountUsd must be > 0");
+        const agentId = params.agentId ?? "agent_default";
+        const budget = this.budgets.get(agentId);
+        if (budget && budget.spent + params.amountUsd > budget.limit) {
+            throw new Error(`booking $${params.amountUsd} exceeds remaining budget $${(budget.limit - budget.spent).toFixed(2)} for ${agentId}`);
+        }
+        const authorization = await this.pay.authorize({
+            route: params.source,
+            amountUsd: params.amountUsd,
+            currency: params.currency,
+            mcc: params.mcc ?? (params.source === "legacy" ? furlpay_1.MCC.LODGING : undefined),
+        });
+        const booking = {
+            id: "bk_" + Math.random().toString(36).slice(2, 10),
+            source: params.source,
+            reference: params.reference ?? "(unassigned)",
+            amountUsd: params.amountUsd,
+            status: "authorized",
+            authorization,
+            rebate: params.source === "travala" ? this.accrueRebate("", params.amountUsd) : undefined,
+            createdAt: new Date().toISOString(),
+        };
+        if (booking.rebate)
+            booking.rebate.bookingId = booking.id;
+        if (budget)
+            budget.spent += params.amountUsd;
+        this.bookings.set(booking.id, booking);
+        return booking;
+    }
+    /** Mark an authorized booking confirmed (after passkey step-up in a real flow). */
+    confirmBooking(id) {
+        const b = this.require(id);
+        if (b.status === "cancelled")
+            throw new Error(`booking ${id} is cancelled`);
+        b.status = "confirmed";
+        return b;
+    }
+    cancelBooking(id) {
+        const b = this.require(id);
+        b.status = "cancelled";
+        const budget = this.budgets.get("agent_default");
+        return b;
+    }
+    getBooking(id) {
+        return this.bookings.get(id);
+    }
+    // -- rebates ------------------------------------------------------------
+    /** All cbBTC rebate accruals to date and the developer's cumulative share. */
+    listRebates() {
+        const accruals = [...this.bookings.values()]
+            .filter((b) => b.rebate && b.status !== "cancelled")
+            .map((b) => b.rebate);
+        return {
+            developerWallet: this.developerWallet,
+            accruals,
+            developerTotalUsd: round2(accruals.reduce((s, r) => s + r.developerUsd, 0)),
+            treasuryTotalUsd: round2(accruals.reduce((s, r) => s + r.treasuryUsd, 0)),
+        };
+    }
+    accrueRebate(bookingId, amountUsd) {
+        const total = round2(amountUsd * REBATE_RATE);
+        const developerUsd = round2(total * DEVELOPER_SHARE);
+        return {
+            bookingId,
+            currency: "cbBTC",
+            totalUsd: total,
+            developerUsd,
+            treasuryUsd: round2(total - developerUsd),
+        };
+    }
+    require(id) {
+        const b = this.bookings.get(id);
+        if (!b)
+            throw new Error(`no booking ${id}`);
+        return b;
+    }
+}
+exports.TravelClient = TravelClient;
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+exports.default = TravelClient;

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+export type BookingSource = "travala" | "legacy";
+export interface Stay {
+    quoteId: string;
+    name: string;
+    brand: string;
+    city: string;
+    stars: number;
+    checkIn: string;
+    checkOut: string;
+    nights: number;
+    nightlyUsd: number;
+    totalUsd: number;
+    source: "travala" | "demo";
+}
+export interface Flight {
+    quoteId: string;
+    carrier: string;
+    from: string;
+    to: string;
+    date: string;
+    cabin: string;
+    totalUsd: number;
+    source: "travala" | "demo";
+}
+/** A payment authorization FurlPay hands back for a booking. */
+export interface Authorization {
+    route: BookingSource;
+    amount: number;
+    currency: string;
+    /** Present on the crypto route: an x402 payment proof settled on Base. */
+    x402?: {
+        proof: string;
+        network: string;
+        token: string;
+        settlementTx?: string;
+    };
+    /** Present on the legacy route: a single-use Visa virtual card number, MCC-locked. */
+    card?: {
+        id: string;
+        last4: string;
+        expMonth: number;
+        expYear: number;
+        mccWhitelist: string[];
+        singleUse: boolean;
+        limitUsd: number;
+    };
+    simulated?: boolean;
+}
+export interface Booking {
+    id: string;
+    source: BookingSource;
+    reference: string;
+    amountUsd: number;
+    status: "authorized" | "confirmed" | "cancelled";
+    authorization: Authorization;
+    /** 10% cbBTC developer rebate accrued on Travala-routed bookings. */
+    rebate?: RebateAccrual;
+    createdAt: string;
+}
+export interface RebateAccrual {
+    bookingId: string;
+    currency: "cbBTC";
+    totalUsd: number;
+    developerUsd: number;
+    treasuryUsd: number;
+}
+export interface TravelOptions {
+    /** FurlPay API key. Omit → demo mode (searches + payments simulate, no network). */
+    furlpayApiKey?: string;
+    /** FurlPay API base. Default https://api.furlpay.com/v1 */
+    furlpayBaseUrl?: string;
+    /** Travala Travel MCP endpoint. Default https://travel-mcp.travala.com/mcp */
+    travalaMcpUrl?: string;
+    /** Developer wallet that receives the 7% cbBTC rebate split. */
+    developerWallet?: string;
+    /** Override fetch (Node 18+ has a global fetch). */
+    fetchImpl?: typeof fetch;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@furlpay/travel-mcp",
+  "version": "0.1.0",
+  "description": "FurlPay Travels — an MCP server composing Travala's Travel MCP (search) with FurlPay payment rails (x402/USDC on Base or single-use MCC-locked Visa VCN). Captures the 10% cbBTC developer rebate. Zero runtime dependencies.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "furlpay-travel-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "furlpay",
+    "travala",
+    "travel",
+    "mcp",
+    "x402",
+    "agentic-payments",
+    "stablecoin",
+    "usdc",
+    "virtual-cards",
+    "cbbtc"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/travel.test.js",
+    "example": "npx --yes tsx examples/book.ts",
+    "start": "npm run build && node dist/server.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/furlpay/furlpay-travel-mcp"
+  },
+  "homepage": "https://furlpay.com",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "5.5.3",
+    "@types/node": "20.14.10"
+  }
+}

package/src/furlpay.ts

@@ -0,0 +1,126 @@
+import { Authorization, BookingSource } from "./types";
+
+/**
+ * FurlPay payment side of the composition. Produces the credential a booking
+ * needs, per route:
+ *
+ *   - travala (crypto-native): an x402 payment proof, settled in gasless USDC on
+ *     Base — the rail Travala's protocol accepts directly.
+ *   - legacy (Web2 merchants like Airbnb/Skyscanner): a single-use Visa virtual
+ *     card number, MCC-locked to travel and limited to the booking total.
+ *
+ * With no FurlPay key set, both routes simulate (no network) so the flow is fully
+ * runnable offline. Card PANs are never real in demo mode.
+ */
+
+const DEFAULT_BASE = "https://api.furlpay.com/v1";
+
+// Common travel MCCs. 7011 = Lodging/Hotels, 4511 = Airlines, 7512 = Car Rental,
+// 4722 = Travel Agencies.
+export const MCC = { LODGING: "7011", AIRLINES: "4511", CAR_RENTAL: "7512", TRAVEL_AGENCY: "4722" } as const;
+
+function rid(prefix: string): string {
+  return prefix + Math.random().toString(36).slice(2, 10);
+}
+
+export class FurlPayPay {
+  constructor(
+    private readonly apiKey?: string,
+    private readonly baseUrl: string = process.env.FURLPAY_API_BASE || DEFAULT_BASE,
+    private readonly fetchImpl: typeof fetch = globalThis.fetch,
+  ) {}
+
+  get live(): boolean {
+    return Boolean(this.apiKey);
+  }
+
+  /** Authorize a booking on the chosen route, returning the payment credential. */
+  async authorize(params: {
+    route: BookingSource;
+    amountUsd: number;
+    currency?: string;
+    mcc?: string;
+  }): Promise<Authorization> {
+    const currency = (params.currency ?? "USDC").toUpperCase();
+    if (params.route === "travala") return this.authorizeX402(params.amountUsd, currency);
+    return this.issueVirtualCard(params.amountUsd, currency, params.mcc ?? MCC.LODGING);
+  }
+
+  private async authorizeX402(amountUsd: number, currency: string): Promise<Authorization> {
+    if (!this.live) {
+      return {
+        route: "travala",
+        amount: amountUsd,
+        currency,
+        x402: { proof: rid("x402_sim_"), network: "base", token: "USDC", settlementTx: rid("tx_sim_") },
+        simulated: true,
+      };
+    }
+    const settled = await this.post("/x402/settle", { amount: amountUsd, token: "USDC", destination: "travala" });
+    return {
+      route: "travala",
+      amount: amountUsd,
+      currency,
+      x402: {
+        proof: settled.payment_header || settled.proof,
+        network: settled.network || "base",
+        token: "USDC",
+        settlementTx: settled.tx,
+      },
+    };
+  }
+
+  private async issueVirtualCard(amountUsd: number, currency: string, mcc: string): Promise<Authorization> {
+    if (!this.live) {
+      const last4 = String(1000 + Math.floor(Math.random() * 9000)).slice(-4);
+      return {
+        route: "legacy",
+        amount: amountUsd,
+        currency,
+        card: {
+          id: rid("card_sim_"),
+          last4,
+          expMonth: 12,
+          expYear: new Date().getUTCFullYear() + 3,
+          mccWhitelist: [mcc],
+          singleUse: true,
+          limitUsd: amountUsd,
+        },
+        simulated: true,
+      };
+    }
+    const card = await this.post("/cards", {
+      type: "virtual",
+      currency,
+      limit: amountUsd,
+      mcc_whitelist: [mcc],
+      single_use: true,
+    });
+    return {
+      route: "legacy",
+      amount: amountUsd,
+      currency,
+      card: {
+        id: card.id,
+        last4: card.last4,
+        expMonth: card.exp_month,
+        expYear: card.exp_year,
+        mccWhitelist: card.mcc_whitelist ?? [mcc],
+        singleUse: true,
+        limitUsd: amountUsd,
+      },
+    };
+  }
+
+  private async post(path: string, body: unknown): Promise<any> {
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    const json = text ? JSON.parse(text) : {};
+    if (!res.ok) throw new Error(json.error || `FurlPay HTTP ${res.status}`);
+    return json;
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { TravelClient, MCC } from "./travel";
+export { TravalaClient } from "./travala";
+export { FurlPayPay } from "./furlpay";
+export { buildTools } from "./tools";
+export type { McpTool } from "./tools";
+export * from "./types";