@apiosk/mcp 1.3.0 → 1.7.0

package/src/observability.mjs

@@ -0,0 +1,194 @@
+// MCP observability side-car — the MCP server historically logged NOTHING about
+// its own activity (tool calls, SSE sessions, OAuth/installs). This module writes
+// append-only rows to the mcp_tool_calls / mcp_sessions / mcp_oauth_events tables
+// (gateway migration 057) so the admin portal can see MCP traffic.
+//
+// Design: fire-and-forget, NEVER throws into the hot path (every write is wrapped
+// in try/catch and returns a swallowed promise). Uses the service-role key exactly
+// like publisher.mjs (rest/v1/<table>). PRIVACY: raw connect tokens are sha256-hashed
+// (never stored raw), and only argument KEY NAMES are stored — never values, headers,
+// or bodies.
+
+import { createHash } from "node:crypto";
+
+const DEFAULT_SUPABASE_URL = "https://jgjoiyqdyypouskftzeq.supabase.co";
+
+function resolveConfig(env = {}) {
+  const raw =
+    env.APIOSK_SUPABASE_URL || env.SUPABASE_URL || DEFAULT_SUPABASE_URL;
+  const url = String(raw).replace(/\/+$/, "");
+  const key =
+    env.APIOSK_SUPABASE_SERVICE_ROLE_KEY || env.SUPABASE_SERVICE_ROLE_KEY || "";
+  return { url, key };
+}
+
+function sha256(value) {
+  if (!value || typeof value !== "string") return null;
+  try {
+    return createHash("sha256").update(value).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+function trimStr(v, max = 400) {
+  if (v == null) return null;
+  const s = String(v);
+  return s.length > max ? s.slice(0, max) : s;
+}
+
+// Low-level fire-and-forget REST write. Resolves regardless of outcome; a failure
+// is logged to stderr but never propagates — observability must not break a tool call.
+async function restWrite(env, path, body, { method = "POST", extraHeaders = {} } = {}) {
+  const { url, key } = resolveConfig(env);
+  if (!key) return; // not configured on this deployment — skip silently
+  const fetchImpl = globalThis.fetch;
+  if (typeof fetchImpl !== "function") return;
+  try {
+    await fetchImpl(`${url}/rest/v1/${path}`, {
+      method,
+      headers: {
+        apikey: key,
+        authorization: `Bearer ${key}`,
+        "content-type": "application/json",
+        prefer: "return=minimal",
+        ...extraHeaders,
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  } catch (error) {
+    try {
+      console.warn(
+        "[observability] write failed:",
+        error && error.message ? error.message : String(error),
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/** Extract caller identity from the MCP authInfo (never returns a raw token). */
+export function callerFrom(authInfo) {
+  const x = (authInfo && (authInfo.extra || authInfo)) || {};
+  const rawToken = x.apiosk_connect_token || x.connectToken || null;
+  const hasToken = Boolean(rawToken || x.apiosk_connect_token_id);
+  return {
+    auth_method: hasToken ? "connect_token" : x.userId ? "oauth" : "anonymous",
+    user_id: x.userId || x.user_id || null,
+    connect_token_id: x.apiosk_connect_token_id || x.connect_token_id || null,
+    connect_token_hash: sha256(rawToken),
+    wallet_address:
+      x.walletAddress || x.apiosk_connect_wallet_address || x.wallet_address || null,
+    provider_id: x.providerId || x.provider_id || null,
+    client_name: (authInfo && (authInfo.clientName || authInfo.client_name)) || null,
+    client_kind: (authInfo && (authInfo.clientKind || authInfo.client_kind)) || null,
+  };
+}
+
+/** Log one tools/call dispatch. Fire-and-forget. */
+export function logToolCall(
+  env,
+  {
+    toolName,
+    outcome = "ok",
+    errorCode = null,
+    latencyMs = null,
+    authInfo = null,
+    argKeys = [],
+    sessionId = null,
+    gatewayRequestId = null,
+    ip = null,
+    userAgent = null,
+  } = {},
+) {
+  const caller = callerFrom(authInfo);
+  return restWrite(env, "mcp_tool_calls", {
+    tool_name: String(toolName || "unknown"),
+    outcome,
+    error_code: errorCode ? trimStr(errorCode, 120) : null,
+    latency_ms: typeof latencyMs === "number" ? Math.round(latencyMs) : null,
+    ...caller,
+    session_id: sessionId,
+    gateway_request_id: gatewayRequestId,
+    arg_keys: Array.isArray(argKeys) ? argKeys.slice(0, 64).map(String) : [],
+    ip_address: ip,
+    user_agent: trimStr(userAgent),
+  });
+}
+
+/** Record an SSE session on connect (upsert on session_id). Fire-and-forget. */
+export function openSession(
+  env,
+  { sessionId, transport = "sse", ip = null, userAgent = null, clientName = null, clientKind = null, protocolVersion = null } = {},
+) {
+  if (!sessionId) return;
+  return restWrite(
+    env,
+    "mcp_sessions",
+    {
+      session_id: String(sessionId),
+      transport,
+      ip_address: ip,
+      user_agent: trimStr(userAgent),
+      client_name: clientName,
+      client_kind: clientKind,
+      protocol_version: protocolVersion,
+      status: "online",
+    },
+    // Upsert: a reconnect with the same id refreshes it instead of 409-ing.
+    { extraHeaders: { prefer: "resolution=merge-duplicates,return=minimal" } },
+  );
+}
+
+/** Mark an SSE session closed on disconnect. Fire-and-forget. */
+export function closeSession(env, sessionId) {
+  if (!sessionId) return;
+  const now = new Date().toISOString();
+  return restWrite(
+    env,
+    `mcp_sessions?session_id=eq.${encodeURIComponent(String(sessionId))}`,
+    { status: "closed", disconnected_at: now, last_activity_at: now },
+    { method: "PATCH" },
+  );
+}
+
+/** Log an OAuth / install event (authorize, consent, token_issued, wallet_created…). */
+export function logOAuthEvent(
+  env,
+  {
+    eventType,
+    userId = null,
+    clientId = null,
+    clientName = null,
+    redirectUri = null,
+    scopes = [],
+    connectTokenId = null,
+    connectTokenHash = null,
+    connectTokenRaw = null,
+    walletAddress = null,
+    walletCreated = false,
+    outcome = "ok",
+    errorCode = null,
+    ip = null,
+    userAgent = null,
+  } = {},
+) {
+  if (!eventType) return;
+  return restWrite(env, "mcp_oauth_events", {
+    event_type: eventType,
+    user_id: userId,
+    client_id: clientId ? trimStr(clientId, 200) : null,
+    client_name: clientName,
+    redirect_uri: redirectUri ? trimStr(redirectUri, 500) : null,
+    scopes: Array.isArray(scopes) ? scopes.map(String) : [],
+    connect_token_id: connectTokenId,
+    connect_token_hash: connectTokenHash || sha256(connectTokenRaw),
+    wallet_address: walletAddress,
+    wallet_created: Boolean(walletCreated),
+    outcome,
+    error_code: errorCode ? trimStr(errorCode, 120) : null,
+    ip_address: ip,
+    user_agent: trimStr(userAgent),
+  });
+}

package/src/payment-guidance.mjs

@@ -3,7 +3,7 @@
 // This module turns the Apiosk settlement model into agent-readable guidance
 // that is surfaced at discovery time (search/explore/get_api) and through the
 // dedicated apiosk_payment_guide tool. It covers BOTH sides of the gateway:
-//   - buyers: how an agent pays for a paid API call (USDC x402 or prepaid credits),
+//   - buyers: how an agent pays for a paid API call (USDC over x402),
 //     tailored to what auth the runtime currently has.
 //   - providers (sellers): how to publish an API so other agents can pay for it.
 //
@@ -23,21 +23,12 @@ export const SETTLEMENT_RAILS = [
     best_for: "Autonomous agents that hold a funded Base USDC wallet.",
     setup: "Fund a wallet with Base mainnet USDC, then settlement happens automatically per call.",
   },
-  {
-    id: "credits",
-    label: "Prepaid credits",
-    summary:
-      "A human tops up a credits balance once and the agent spends it down per call.",
-    best_for: "Letting a human fund usage once and then handing the agent autonomy.",
-    setup: "Top up credits via the Apiosk buyer portal; the agent spends them down automatically.",
-  },
 ];
 
 // The order the gateway tries to cover a paid call. A 402 is only returned
 // when none of the buyer's enabled rails can settle.
 export const RAIL_FALLBACK_ORDER = [
   "1. USDC / x402 wallet when the agent can produce a payment proof.",
-  "2. Prepaid credits balance.",
 ];
 
 function resolvePrice(api) {
@@ -83,7 +74,7 @@ function describeReadiness(capability = {}, { localWalletsEnabled = false, mode
         status: "ready_to_pay",
         active_method: "Apiosk connect token",
         detail:
-          "A managed connect token is active. The gateway settles each call over the buyer's enabled rails (USDC managed wallet or credits) server-side — no signing needed here.",
+          "A managed connect token is active. The gateway settles each call from the authorized USDC managed wallet server-side, no signing needed here.",
       };
     case "wallet_address":
       return {
@@ -91,7 +82,7 @@ function describeReadiness(capability = {}, { localWalletsEnabled = false, mode
         status: "setup_required",
         active_method: "wallet address only",
         detail:
-          "A wallet address is known but no signing key or connect token is configured, so this surface cannot settle x402 calls itself. The gateway may still settle over credits if a balance exists for this buyer.",
+          "A wallet address is known but no signing key or connect token is configured, so this surface cannot settle x402 calls itself.",
       };
     default:
       return {
@@ -117,24 +108,24 @@ function buildHowToPaySteps({ readiness, localWalletsEnabled, mode, slug }) {
   if (readiness.ready) {
     return [
       execHint,
-      "Settlement is automatic — the gateway charges the active method and returns the result.",
-      "If a call still returns payment_required, fund the wallet (apiosk_show_wallet_funding) or enable another rail, then retry.",
+      "Settlement is automatic, the gateway charges the active method and returns the result.",
+      "If a call still returns payment_required, fund the wallet with USDC on Base and retry.",
     ];
   }
 
   if (localWalletsEnabled) {
     return [
       "Run apiosk_get_started to create or select a local wallet (or import a dashboard connect string).",
-      "Fund the wallet with Base mainnet USDC using apiosk_show_wallet_funding, or top up credits for managed settlement.",
+      "Fund the wallet with Base mainnet USDC using apiosk_show_wallet_funding.",
       execHint,
     ];
   }
 
   if (mode === "hosted") {
     return [
-      "Authorize the Apiosk app when your MCP client prompts, so calls settle against your managed wallet/rails.",
+      "Authorize the Apiosk app when your MCP client prompts, so calls settle against your managed wallet.",
       execHint,
-      "If a call returns payment_required, top up credits via the buyer portal or fund your managed wallet, then retry.",
+      "If a call returns payment_required, fund your managed wallet with USDC on Base, then retry.",
     ];
   }
 
@@ -163,7 +154,7 @@ export function buildPaymentGuidance({
   if (isFree) {
     return {
       role: "buyer",
-      summary: `This listing is free (cost_per_call ${price}). Call it directly — no payment required.`,
+      summary: `This listing is free (cost_per_call ${price}). Call it directly, no payment required.`,
       cost_per_call_usd: price,
       free: true,
       status: "ready_to_pay",
@@ -192,7 +183,7 @@ export function buildPaymentGuidance({
     settlement_rails: SETTLEMENT_RAILS,
     rail_fallback_order: RAIL_FALLBACK_ORDER,
     on_payment_required:
-      "A paid call can return a structured payment_required error when no enabled rail can cover it. Fund the wallet or top up credits, then retry the same call.",
+      "A paid call can return a structured payment_required error when the wallet cannot cover it. Fund the wallet with USDC on Base, then retry the same call.",
     base_chain: { chain_id: BASE_CHAIN_ID, usdc_contract: BASE_USDC_CONTRACT, network: "base" },
     learn_more: "Call apiosk_help with topic='rails' for the full settlement model.",
   };
@@ -227,7 +218,7 @@ export function buildProviderGuidance({ mode = "remote", localWalletsEnabled = f
       "Host your MCP over HTTPS and support initialize, tools/list, and tools/call.",
       "Protect the upstream MCP with bearer auth or another server-side secret; Apiosk injects that credential after payment.",
       "Import the MCP in the provider portal. Apiosk scans tools/list and creates one paid action per selected tool.",
-      "Buyers should use https://mcp.apiosk.com/mcp, GET https://gateway.apiosk.com/<slug>/metadata, or POST https://gateway.apiosk.com/<slug>/execute — not your raw MCP URL.",
+      "Buyers should use https://mcp.apiosk.com/mcp, GET https://gateway.apiosk.com/<slug>/metadata, or POST https://gateway.apiosk.com/<slug>/execute, not your raw MCP URL.",
       "Your MCP should not return 402 or inspect X-Payment. Apiosk handles payment challenges, settlement, and revenue splits before calling your MCP.",
     ],
     requirements: [
@@ -266,17 +257,17 @@ export function buildPaymentGuide({
   const payload = {
     role: normalizedRole,
     overview:
-      "Apiosk is one gateway, any rail: a single buyer identity can pay for any API over USDC (x402 on Base) or prepaid credits — the gateway picks the rail per call. Providers list APIs once and get paid per call.",
+      "Apiosk is one gateway, any rail: a single buyer identity can pay for any API over USDC (x402 on Base) or prepaid credits, the gateway picks the rail per call. Providers list APIs once and get paid per call.",
     quickstart: {
       buyer: [
         "Discover: apiosk_search or apiosk_explore.",
         "Inspect: apiosk_get_api for price, schema, and a per-listing payment block.",
-        "Pay & run: call the dynamic tool or apiosk_execute — settlement is automatic once a rail is configured.",
+        "Pay & run: call the dynamic tool or apiosk_execute, settlement is automatic once a rail is configured.",
       ],
       provider: [
         "Get a signing wallet (apiosk_wallet_create or APIOSK_PRIVATE_KEY).",
         "Publish: apiosk_publish_api with name, slug, https endpoint_url, price_usd, description.",
-        "Confirm: apiosk_list_my_apis — your listing is now discoverable and payable.",
+        "Confirm: apiosk_list_my_apis, your listing is now discoverable and payable.",
       ],
     },
   };
@@ -299,7 +290,7 @@ export function buildDiscoveryPaymentHint({ capability = {}, mode = "remote", lo
     payment_ready: readiness.ready,
     active_method: readiness.active_method,
     how_to_pay: readiness.ready
-      ? "Paid calls settle automatically — just call the tool or apiosk_execute."
+      ? "Paid calls settle automatically, just call the tool or apiosk_execute."
       : readiness.detail,
     settlement_rails: SETTLEMENT_RAILS.map((rail) => rail.id),
     learn_more: "Call apiosk_payment_guide for full buyer + provider instructions.",