@blocks-network/mcp-server 0.1.55 → 0.1.64

package/src/agent-status.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent presence/availability helper.
+ *
+ * Calls GET /api/v1/agent-status with the Blocks-Protocol-Version
+ * header. Backend route is optionalAuth so the API key is forwarded
+ * when available but not required.
+ *
+ * Response shape mirrors the service's agent-status types.
+ */
+
+import {
+  PROTOCOL_VERSION_HEADER,
+  CURRENT_PROTOCOL_VERSION,
+} from './protocol-headers.js';
+
+/** MUST stay in sync with the service's agent-status types. */
+export const MAX_AGENT_NAMES = 50;
+export const AGENT_NAME_PATTERN = /^[a-zA-Z0-9_]+$/;
+
+export interface AgentInstanceStatus {
+  instanceId: string;
+  uuid: string;
+  online: true;
+  /**
+   * Reserved — backend currently returns 0 (live activity counters are not
+   * yet populated by the agent-status service). Do not use for routing or
+   * availability decisions.
+   */
+  activeTasks: number;
+  /** Reserved — backend currently returns 0. See `activeTasks`. */
+  concurrentTasksPerInstance: number;
+  /** Reserved — backend currently returns 0. See `activeTasks`. */
+  startedAt: number;
+  sdkVersion: string | null;
+  cliVersion: string | null;
+  preferredProtocolVersion: string | null;
+  protocolVersions: string[];
+}
+
+export interface AgentStatus {
+  agentName: string;
+  instances: AgentInstanceStatus[];
+  onlineCount: number;
+  /** Reserved — backend currently returns 0. See `AgentInstanceStatus.activeTasks`. */
+  totalActiveTasks: number;
+  taskCount: number;
+}
+
+export interface AgentStatusResponse {
+  agents: Record<string, AgentStatus>;
+}
+
+export interface FetchAgentStatusOptions {
+  baseUrl: string;
+  agentNames: string[];
+  apiKey?: string;
+  fetchImpl?: typeof fetch;
+}
+
+export async function fetchAgentStatus(
+  opts: FetchAgentStatusOptions,
+): Promise<AgentStatusResponse> {
+  const names = opts.agentNames.map((n) => n.trim()).filter(Boolean);
+  if (names.length === 0) {
+    throw new Error('agentNames must contain at least one value');
+  }
+  if (names.length > MAX_AGENT_NAMES) {
+    throw new Error(`agentNames must be at most ${MAX_AGENT_NAMES} values`);
+  }
+  for (const n of names) {
+    if (!AGENT_NAME_PATTERN.test(n)) {
+      throw new Error(`Invalid agent name: ${n}`);
+    }
+  }
+
+  const params = new URLSearchParams({ agentNames: names.join(',') });
+  const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/agent-status?${params}`;
+  const headers: Record<string, string> = {
+    [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
+  };
+  if (opts.apiKey) headers['Authorization'] = `Bearer ${opts.apiKey}`;
+
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const response = await fetchFn(url, { headers });
+  if (!response.ok) {
+    throw new Error(`Agent status failed: HTTP ${response.status}`);
+  }
+  return (await response.json()) as AgentStatusResponse;
+}

package/src/billing.ts

@@ -0,0 +1,122 @@
+/**
+ * Billing helpers — direct HTTP to the routes that accept Bearer
+ * API-key auth (`requireAuth` middleware path on the backend).
+ *
+ *   GET  /api/v1/billing/:orgId/consumer/balance
+ *   POST /api/v1/billing/:orgId/consumer/topup
+ *
+ * Other billing routes (ledger, usage-summary, dashboard-summary,
+ * topup-from-earnings) are session-only on the backend and are not
+ * callable from an MCP server holding only an API key.
+ */
+
+import {
+  PROTOCOL_VERSION_HEADER,
+  CURRENT_PROTOCOL_VERSION,
+} from './protocol-headers.js';
+
+/**
+ * Platform minimum top-up amount in USD. MUST stay in sync with
+ * the service's MIN_BILLING_AMOUNT
+ * (decimal-dollar string `'5'`). The backend rejects values below this floor
+ * via `stripeMoneyAtLeast(MIN_BILLING_AMOUNT, ...)`; we mirror it here so MCP
+ * callers get the real contract up front instead of a runtime HTTP 400.
+ */
+export const MIN_TOPUP_AMOUNT_USD = 5;
+
+export interface ConsumerBalance {
+  /** Ledger balance as a decimal-dollar string (e.g. "12.34"). */
+  balance: string;
+  /** Currently reserved (held for in-flight tasks). */
+  reservedBalance: string;
+  /** balance - reservedBalance. */
+  availableBalance: string;
+  /** ISO timestamp of when the balance snapshot was taken. */
+  updatedAt: string;
+}
+
+export interface TopUpSession {
+  /** Stripe Checkout URL the user opens in a browser to complete payment. */
+  checkoutUrl: string;
+  /** Stripe Checkout session id. */
+  sessionId: string;
+}
+
+export interface BillingClientBase {
+  baseUrl: string;
+  orgId: string;
+  apiKey: string;
+  fetchImpl?: typeof fetch;
+}
+
+function buildHeaders(apiKey: string): Record<string, string> {
+  return {
+    [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
+    Authorization: `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+  };
+}
+
+function billingUrl(baseUrl: string, orgId: string, suffix: string): string {
+  return `${baseUrl.replace(/\/+$/, '')}/api/v1/billing/${encodeURIComponent(orgId)}${suffix}`;
+}
+
+export async function getConsumerBalance(
+  opts: BillingClientBase,
+): Promise<ConsumerBalance> {
+  const url = billingUrl(opts.baseUrl, opts.orgId, '/consumer/balance');
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const response = await fetchFn(url, {
+    method: 'GET',
+    headers: buildHeaders(opts.apiKey),
+  });
+  if (!response.ok) {
+    throw new Error(`Balance lookup failed: HTTP ${response.status}`);
+  }
+  return (await response.json()) as ConsumerBalance;
+}
+
+export interface CreateTopUpOptions extends BillingClientBase {
+  /**
+   * Whole-dollar (or whole-cent decimal) USD amount, e.g. 25 or 19.99.
+   * Must be at least `MIN_TOPUP_AMOUNT_USD` ($5) — backend rejects below this.
+   */
+  amountUsd: number;
+}
+
+export async function createConsumerTopUp(
+  opts: CreateTopUpOptions,
+): Promise<TopUpSession> {
+  if (!Number.isFinite(opts.amountUsd) || opts.amountUsd <= 0) {
+    throw new Error('amountUsd must be a positive finite number');
+  }
+  if (Math.round(opts.amountUsd * 100) / 100 !== opts.amountUsd) {
+    throw new Error('amountUsd must be a whole-cent value (no sub-cent fractions)');
+  }
+  if (opts.amountUsd < MIN_TOPUP_AMOUNT_USD) {
+    throw new Error(
+      `amountUsd must be at least $${MIN_TOPUP_AMOUNT_USD}.00 (platform minimum)`,
+    );
+  }
+  const amount = opts.amountUsd.toFixed(2);
+
+  const url = billingUrl(opts.baseUrl, opts.orgId, '/consumer/topup');
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const response = await fetchFn(url, {
+    method: 'POST',
+    headers: buildHeaders(opts.apiKey),
+    body: JSON.stringify({ amount }),
+  });
+  if (!response.ok) {
+    let detail = '';
+    try {
+      detail = await response.text();
+    } catch {
+      // ignore body decode failures
+    }
+    throw new Error(
+      `Top-up failed: HTTP ${response.status}${detail ? ` — ${detail}` : ''}`,
+    );
+  }
+  return (await response.json()) as TopUpSession;
+}