@apiosk/mcp 1.7.0 → 2.0.0

package/src/external-fetch.mjs

@@ -1,203 +0,0 @@
-// Apiosk external x402 payment (apiosk_fetch_paid).
-//
-// The last step of the agentic flow for endpoints the Apiosk gateway does NOT
-// host: pay an arbitrary external x402 URL from the connected buyer's managed
-// wallet. The MCP holds no signing keys, so this delegates to the gateway's
-// gateway-as-payer proxy (POST /v1/x402/fetch): the gateway enforces the connect
-// token's spend caps, pays the provider from a platform payer wallet, debits the
-// buyer's managed wallet, and returns the provider response.
-//
-// For Apiosk CATALOG listings use apiosk_execute instead — that path is cheaper
-// and fully settled. This tool is only for external (federated / discovered)
-// endpoints. `confirmed_price_usdc` is required and is the in-chat price
-// checkpoint: the gateway refuses if the live price exceeds what the user
-// confirmed via apiosk_inspect_x402.
-
-import { randomUUID } from "node:crypto";
-
-const DEFAULT_GATEWAY_BASE_URL = "https://gateway.apiosk.com";
-
-function content(value) {
-  const result = {
-    content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }],
-  };
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    result.structuredContent = value;
-  }
-  return result;
-}
-
-function trimString(value) {
-  return String(value ?? "").trim();
-}
-
-/**
- * Execute a paid fetch of an external x402 endpoint via the gateway payer proxy.
- *
- * @param {object} args - { url, method?, query?, body?, headers?, confirmed_price_usdc, max_price_usdc?, idempotency_key? }
- * @param {object} ctx  - { connectToken, gatewayBaseUrl, fetchImpl? }
- */
-export async function runFetchPaid(args = {}, ctx = {}) {
-  const url = trimString(args.url);
-  if (!url) {
-    return content({ status: "error", error: "Missing required field: url" });
-  }
-  const confirmedPrice = args.confirmed_price_usdc;
-  if (!Number.isFinite(confirmedPrice) || confirmedPrice < 0) {
-    return content({
-      status: "error",
-      error:
-        "Missing required field: confirmed_price_usdc. Call apiosk_inspect_x402 on the URL first, tell the user the price, then pass the confirmed amount here.",
-    });
-  }
-
-  const connectToken = trimString(ctx.connectToken);
-  if (!connectToken) {
-    return content({
-      status: "error",
-      error:
-        "No connected wallet. apiosk_fetch_paid needs an Apiosk connect token (authorize the Apiosk app / OAuth on the hosted server). For Apiosk catalog listings, use apiosk_execute instead.",
-    });
-  }
-
-  const gatewayBaseUrl = trimString(ctx.gatewayBaseUrl) || DEFAULT_GATEWAY_BASE_URL;
-  const fetchImpl = ctx.fetchImpl || fetch;
-  const idempotencyKey = trimString(args.idempotency_key) || randomUUID();
-  const method = trimString(args.method).toUpperCase() || "GET";
-
-  const requestBody = {
-    url,
-    method,
-    query: args.query && typeof args.query === "object" ? args.query : undefined,
-    body: args.body !== undefined ? args.body : undefined,
-    headers: args.headers && typeof args.headers === "object" ? args.headers : undefined,
-    confirmed_price_usdc: confirmedPrice,
-    max_price_usdc: Number.isFinite(args.max_price_usdc) ? args.max_price_usdc : undefined,
-  };
-
-  let response;
-  try {
-    response = await fetchImpl(`${gatewayBaseUrl.replace(/\/+$/, "")}/v1/x402/fetch`, {
-      method: "POST",
-      cache: "no-store",
-      headers: {
-        "content-type": "application/json",
-        accept: "application/json",
-        "X-Apiosk-Connect-Token": connectToken,
-        "Idempotency-Key": idempotencyKey,
-      },
-      body: JSON.stringify(requestBody),
-    });
-  } catch (error) {
-    return content({
-      status: "error",
-      error: `Could not reach the Apiosk gateway payer: ${trimString(error?.message || error)}`,
-      idempotency_key: idempotencyKey,
-    });
-  }
-
-  const text = await response.text().catch(() => "");
-  let payload = null;
-  try {
-    payload = text ? JSON.parse(text) : null;
-  } catch {
-    payload = text || null;
-  }
-
-  // The gateway emits refusal codes under `error` (json_error_response) or
-  // `code`; normalize so callers below can read either.
-  const gatewayCode = payload?.code || payload?.error || null;
-
-  // Feature not enabled yet: degrade gracefully so the model falls back to a
-  // catalog listing instead of surfacing a raw 403.
-  if (response.status === 403 && gatewayCode === "feature_disabled") {
-    return content({
-      status: "unavailable",
-      code: "feature_disabled",
-      message:
-        "External direct-pay (apiosk_fetch_paid) is not enabled on this gateway yet. Use an Apiosk catalog listing via apiosk_execute instead.",
-      idempotency_key: idempotencyKey,
-    });
-  }
-
-  // Any non-2xx with a structured code is a business outcome (price too high,
-  // host not allowed, wallet over cap) — return it as data, not an MCP error, so
-  // the model can adapt (lower the amount, pick another endpoint, tell the user).
-  if (!response.ok) {
-    return content({
-      status: payload?.status || (response.status === 402 ? "payment_required" : "refused"),
-      code: gatewayCode || `http_${response.status}`,
-      message: payload?.message || payload?.error || `Gateway returned HTTP ${response.status}.`,
-      http_status: response.status,
-      idempotency_key: idempotencyKey,
-    });
-  }
-
-  // Success: surface the provider data + a receipt the model can quote back.
-  return content({
-    status: "success",
-    data: payload?.data ?? payload,
-    receipt: payload?.receipt || null,
-    idempotency_key: idempotencyKey,
-  });
-}
-
-export const FETCH_PAID_TOOL = {
-  name: "apiosk_fetch_paid",
-  description:
-    "Pay an EXTERNAL x402 endpoint (one Apiosk does not host) from the connected wallet and return its data. Use this only for external results from apiosk_discover (executable_via='apiosk_fetch_paid'); for Apiosk catalog listings use apiosk_execute. REQUIRED: call apiosk_inspect_x402 on the url first, tell the user the exact price, and pass that amount as confirmed_price_usdc — the gateway refuses if the live price is higher. The gateway enforces the wallet's per-tx/daily spend limits. Base + USDC only.",
-  annotations: {
-    readOnlyHint: false,
-    destructiveHint: true,
-    idempotentHint: false,
-    openWorldHint: true,
-  },
-  _meta: {
-    "openai/outputTemplate": "ui://apiosk/result-canvas.html",
-    "openai/toolInvocation/invoking": "Paying the provider and fetching data…",
-    "openai/toolInvocation/invoked": "Paid data received",
-    ui: { resourceUri: "ui://apiosk/result-canvas.html" },
-  },
-  inputSchema: {
-    type: "object",
-    required: ["url", "confirmed_price_usdc"],
-    properties: {
-      url: {
-        type: "string",
-        description: "The external x402 resource URL to pay and fetch (from a discovery result's `url`).",
-      },
-      confirmed_price_usdc: {
-        type: "number",
-        description: "The price you read via apiosk_inspect_x402 and confirmed with the user. The gateway refuses if the live price exceeds this.",
-      },
-      method: {
-        type: "string",
-        enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
-        description: "HTTP method for the provider request. Defaults to GET.",
-      },
-      query: {
-        type: "object",
-        additionalProperties: true,
-        description: "Optional query parameters to send to the provider.",
-      },
-      body: {
-        type: "object",
-        additionalProperties: true,
-        description: "Optional JSON request body for POST/PUT/PATCH.",
-      },
-      headers: {
-        type: "object",
-        additionalProperties: true,
-        description: "Optional extra request headers (allowlisted server-side; secrets are never accepted here).",
-      },
-      max_price_usdc: {
-        type: "number",
-        description: "Optional additional per-call ceiling. The gateway also enforces the wallet's per-tx and daily limits.",
-      },
-      idempotency_key: {
-        type: "string",
-        description: "Optional. Reuse the same key to safely retry without paying twice; a fresh one is generated if omitted.",
-      },
-    },
-  },
-};

package/src/funding-options.mjs

@@ -1,255 +0,0 @@
-import { createHmac } from "node:crypto";
-
-import QRCode from "qrcode";
-
-const TRANSAK_API_URL = "https://api-gateway.transak.com";
-const ONRAMPER_WIDGET_URL = "https://buy.onramper.com";
-const BASE_EXPLORER_URL = "https://basescan.org";
-
-function trimString(value) {
-  return String(value || "").trim();
-}
-
-function boolFromEnv(value, defaultValue = true) {
-  const normalized = trimString(value).toLowerCase();
-  if (!normalized) return defaultValue;
-  if (["0", "false", "no", "off"].includes(normalized)) return false;
-  if (["1", "true", "yes", "on"].includes(normalized)) return true;
-  return defaultValue;
-}
-
-function qrImageUrl(value) {
-  return `https://api.qrserver.com/v1/create-qr-code/?size=280x280&data=${encodeURIComponent(value)}`;
-}
-
-function getOnramperConfig(env = process.env) {
-  return {
-    apiKey: trimString(env.ONRAMPER_API_KEY),
-    widgetSecret: trimString(env.ONRAMPER_WIDGET_SECRET),
-  };
-}
-
-function getTransakConfig(env = process.env) {
-  return {
-    apiKey: trimString(env.TRANSAK_API_KEY),
-    secret: trimString(env.TRANSAK_SECRET),
-    referrerDomain: trimString(env.APIOSK_TRANSAK_REFERRER_DOMAIN || "dashboard.apiosk.com"),
-  };
-}
-
-function buildOnramperWidgetUrl(address, env = process.env) {
-  const { apiKey, widgetSecret } = getOnramperConfig(env);
-  const normalizedAddress = trimString(address).toLowerCase();
-  const searchParams = new URLSearchParams({
-    apiKey,
-    mode: "buy",
-    defaultCrypto: "USDC",
-    defaultNetwork: "base",
-    onlyCryptoNetworks: "base",
-    networkWallets: `base:${normalizedAddress}`,
-  });
-
-  const signContent = `networkWallets=base:${normalizedAddress}`;
-  const signature = createHmac("sha256", widgetSecret)
-    .update(signContent)
-    .digest("hex");
-
-  searchParams.set("signature", signature);
-
-  return `${ONRAMPER_WIDGET_URL}/?${searchParams.toString()}`;
-}
-
-async function getTransakAccessToken(env = process.env, fetchImpl = globalThis.fetch) {
-  const { apiKey, secret } = getTransakConfig(env);
-  const response = await fetchImpl(`${TRANSAK_API_URL}/api/v2/auth/token`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      apiKey,
-      secretKey: secret,
-    }),
-  });
-
-  if (!response.ok) {
-    throw new Error("Failed to get Transak access token.");
-  }
-
-  const data = await response.json();
-  return String(data.accessToken || "");
-}
-
-async function createTransakFundingSession(address, env = process.env, fetchImpl = globalThis.fetch) {
-  const { apiKey, referrerDomain } = getTransakConfig(env);
-  const accessToken = await getTransakAccessToken(env, fetchImpl);
-
-  const sessionResponse = await fetchImpl(`${TRANSAK_API_URL}/api/v2/auth/session`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "access-token": accessToken,
-    },
-    body: JSON.stringify({
-      widgetParams: {
-        apiKey,
-        referrerDomain,
-        walletAddress: address,
-        cryptoCurrencyCode: "USDC",
-        network: "base",
-        defaultCryptoCurrency: "USDC",
-        defaultNetwork: "base",
-        disableWalletAddressForm: true,
-        themeColor: "0052FF",
-        hideMenu: true,
-      },
-    }),
-  });
-
-  if (!sessionResponse.ok) {
-    throw new Error("Failed to create Transak funding session.");
-  }
-
-  const sessionData = await sessionResponse.json();
-  return {
-    widget_url: sessionData.widgetUrl || null,
-    session_id: sessionData.sessionId || null,
-  };
-}
-
-async function buildQrBundle(address, options = {}) {
-  const env = options.env || process.env;
-  const includeDataUrl =
-    options.includeQrDataUrl === true || boolFromEnv(env.APIOSK_INCLUDE_QR_DATA_URL, false);
-  const qrEnabled = boolFromEnv(env.APIOSK_ENABLE_QR, true);
-  const transferUri = `ethereum:${address}@8453`;
-  const payload = address;
-  const bundle = {
-    qr_payload: payload,
-    transfer_uri: transferUri,
-    qr_image_url: qrImageUrl(payload),
-  };
-
-  if (!qrEnabled) {
-    return bundle;
-  }
-
-  try {
-    bundle.qr_code_terminal = await QRCode.toString(payload, {
-      type: "terminal",
-      small: true,
-    });
-    bundle.qr_code_terminal_format = "ansi";
-  } catch {
-    // Leave terminal QR unset if rendering fails.
-  }
-
-  if (includeDataUrl) {
-    try {
-      bundle.qr_code_data_url = await QRCode.toDataURL(payload, {
-        margin: 1,
-        width: 280,
-      });
-    } catch {
-      // Leave data URL unset if rendering fails.
-    }
-  }
-
-  return bundle;
-}
-
-function buildFundingProviders(address, env = process.env) {
-  const { apiKey: transakApiKey, secret: transakSecret } = getTransakConfig(env);
-  const { apiKey: onramperApiKey, widgetSecret: onramperWidgetSecret } = getOnramperConfig(env);
-
-  return [
-    {
-      id: "manual",
-      label: "Receive on Base",
-      description: "Send ETH or USDC on Base directly to this wallet address.",
-      available: true,
-      kind: "direct",
-      address,
-      explorer_url: `${BASE_EXPLORER_URL}/address/${address}`,
-    },
-    {
-      id: "transak",
-      label: "Transak",
-      description: "Direct card or bank checkout for Base USDC.",
-      available: Boolean(transakApiKey && transakSecret),
-      kind: "direct",
-      action_hint: "Call apiosk_configure with section='funding' and funding_provider='transak' to request a checkout URL.",
-    },
-    {
-      id: "onramper",
-      label: "Onramper",
-      description: "Multi-provider onramp with outsourced KYC.",
-      available: Boolean(onramperApiKey && onramperWidgetSecret),
-      kind: "aggregator",
-      action_hint: "Call apiosk_configure with section='funding' and funding_provider='onramper' to request a checkout URL.",
-    },
-  ];
-}
-
-export async function buildFundingOptions({
-  wallet,
-  env = process.env,
-  fetchImpl = globalThis.fetch,
-  fundingProvider = null,
-  includeQrDataUrl = false,
-} = {}) {
-  if (!wallet?.address) {
-    return null;
-  }
-
-  const address = trimString(wallet.address).toLowerCase();
-  const receiveOnBase = {
-    title: "Receive on Base",
-    description: "This address accepts both ETH and USDC on Base.",
-    address,
-    network: "Base",
-    accepted_assets: ["ETH", "USDC"],
-    explorer_url: `${BASE_EXPLORER_URL}/address/${address}`,
-    ...await buildQrBundle(address, { env, includeQrDataUrl }),
-  };
-
-  const providers = buildFundingProviders(address, env);
-  let selectedProvider = null;
-  const requestedProvider = trimString(fundingProvider).toLowerCase();
-
-  if (requestedProvider && requestedProvider !== "manual") {
-    const provider = providers.find((entry) => entry.id === requestedProvider);
-    if (provider) {
-      if (!provider.available) {
-        selectedProvider = {
-          ...provider,
-          error: `${provider.label} is not configured in this environment.`,
-        };
-      } else if (provider.id === "onramper") {
-        selectedProvider = {
-          ...provider,
-          widget_url: buildOnramperWidgetUrl(address, env),
-          opens_in: "browser",
-        };
-      } else if (provider.id === "transak") {
-        const session = await createTransakFundingSession(address, env, fetchImpl);
-        selectedProvider = {
-          ...provider,
-          ...session,
-          opens_in: "browser",
-        };
-      }
-    }
-  } else if (requestedProvider === "manual") {
-    selectedProvider = providers.find((entry) => entry.id === "manual") || null;
-  }
-
-  return {
-    receive_on_base: receiveOnBase,
-    providers,
-    selected_provider: selectedProvider,
-    notes: [
-      "Base mainnet only.",
-      "Manual funding works even when embedded onramp providers are unavailable.",
-      "Use the wallet address or QR code from this section to top up the wallet.",
-    ],
-  };
-}

package/src/gateway-management.mjs

@@ -1,107 +0,0 @@
-import { randomBytes } from "node:crypto";
-
-import { privateKeyToAccount } from "viem/accounts";
-
-function parseBody(text) {
-  if (!text) return null;
-
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}
-
-function pickMessage(payload, fallback) {
-  if (payload && typeof payload === "object") {
-    if (typeof payload.message === "string" && payload.message.trim()) {
-      return payload.message.trim();
-    }
-    if (typeof payload.error === "string" && payload.error.trim()) {
-      return payload.error.trim();
-    }
-  }
-
-  if (typeof payload === "string" && payload.trim()) {
-    return payload.trim();
-  }
-
-  return fallback;
-}
-
-export function buildWalletAuthMessage(action, resource, walletAddress, timestamp, nonce) {
-  return [
-    "Apiosk auth",
-    `action:${action}`,
-    `wallet:${String(walletAddress || "").toLowerCase()}`,
-    `resource:${resource}`,
-    `timestamp:${timestamp}`,
-    `nonce:${nonce}`,
-  ].join("\n");
-}
-
-async function signedRequest({
-  baseUrl,
-  path,
-  method = "GET",
-  body,
-  action,
-  resource,
-  wallet,
-  fetchImpl = globalThis.fetch,
-}) {
-  if (!fetchImpl) {
-    throw new Error("A fetch implementation is required.");
-  }
-
-  const account = privateKeyToAccount(wallet.private_key);
-  const timestamp = String(Math.floor(Date.now() / 1000));
-  const nonce = randomBytes(16).toString("hex");
-  const message = buildWalletAuthMessage(action, resource, wallet.address, timestamp, nonce);
-  const signature = await account.signMessage({ message });
-  const headers = new Headers({
-    accept: "application/json",
-    "x-wallet-address": wallet.address,
-    "x-wallet-signature": signature,
-    "x-wallet-timestamp": timestamp,
-    "x-wallet-nonce": nonce,
-  });
-
-  const init = {
-    method,
-    headers,
-  };
-
-  if (body !== undefined) {
-    headers.set("content-type", "application/json");
-    init.body = JSON.stringify(body);
-  }
-
-  const response = await fetchImpl(`${String(baseUrl).replace(/\/+$/, "")}${path}`, init);
-  const text = await response.text();
-  const payload = parseBody(text);
-
-  return { payload, response };
-}
-
-export async function requestGatewayManagement(options) {
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    const { response, payload } = await signedRequest(options);
-    if (response.ok) {
-      return payload;
-    }
-
-    if ((response.status === 401 || response.status === 403) && attempt === 0) {
-      continue;
-    }
-
-    throw new Error(
-      pickMessage(
-        payload,
-        `Gateway management request failed with HTTP ${response.status}`
-      )
-    );
-  }
-
-  throw new Error("Gateway management request failed.");
-}