@agentwonderland/mcp 0.1.23 → 0.1.25

package/src/core/__tests__/card-setup.test.ts

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockApiGet = vi.fn();
+const mockApiPost = vi.fn();
+
+class MockApiError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+let pendingToken: string | null = null;
+const savedCards: unknown[] = [];
+
+vi.mock("../api-client.js", () => ({
+  ApiError: MockApiError,
+  apiGet: (...args: unknown[]) => mockApiGet(...args),
+  apiPost: (...args: unknown[]) => mockApiPost(...args),
+}));
+
+vi.mock("../config.js", () => ({
+  getApiUrl: () => "http://api.test",
+  getPendingCardSetupToken: () => pendingToken,
+  setCardConfig: (card: unknown) => {
+    savedCards.push(card);
+  },
+  setPendingCardSetupToken: (token: string | null) => {
+    pendingToken = token;
+  },
+}));
+
+describe("card setup helpers", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    pendingToken = null;
+    savedCards.length = 0;
+  });
+
+  it("reuses the existing pending setup token", async () => {
+    pendingToken = "tok_existing";
+    const { getOrCreatePendingCardSetup } = await import("../card-setup.js");
+
+    const result = await getOrCreatePendingCardSetup();
+
+    expect(mockApiPost).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      token: "tok_existing",
+      url: "http://api.test/card/handoff/tok_existing",
+      isNew: false,
+    });
+  });
+
+  it("stores a newly created setup token for later resume", async () => {
+    mockApiPost.mockResolvedValueOnce({ token: "tok_new" });
+    const { getOrCreatePendingCardSetup } = await import("../card-setup.js");
+
+    const result = await getOrCreatePendingCardSetup();
+
+    expect(mockApiPost).toHaveBeenCalledWith("/card/setup", {});
+    expect(pendingToken).toBe("tok_new");
+    expect(result).toMatchObject({
+      token: "tok_new",
+      url: "http://api.test/card/handoff/tok_new",
+      isNew: true,
+    });
+  });
+
+  it("persists the card and clears pending setup on successful completion", async () => {
+    pendingToken = "tok_ready";
+    mockApiGet.mockResolvedValueOnce({
+      status: "complete",
+      card_last4: "4242",
+      card_brand: "visa",
+      consumer_token: "consumer_123",
+      payment_method_id: "pm_123",
+    });
+    const { pollCardSetup } = await import("../card-setup.js");
+
+    const result = await pollCardSetup("tok_ready", 50);
+
+    expect(result).toEqual({
+      last4: "4242",
+      brand: "visa",
+      consumerToken: "consumer_123",
+    });
+    expect(savedCards).toEqual([{
+      consumerToken: "consumer_123",
+      paymentMethodId: "pm_123",
+      last4: "4242",
+      brand: "visa",
+    }]);
+    expect(pendingToken).toBeNull();
+  });
+
+  it("clears expired pending setup tokens", async () => {
+    pendingToken = "tok_expired";
+    mockApiGet.mockRejectedValueOnce(new MockApiError(404, "Setup not found"));
+    const { pollCardSetup } = await import("../card-setup.js");
+
+    const result = await pollCardSetup("tok_expired", 50);
+
+    expect(result).toBeNull();
+    expect(pendingToken).toBeNull();
+  });
+
+  it("formats card setup as a single visible message with the setup page URL", async () => {
+    const { formatCardSetupBlocks } = await import("../card-setup.js");
+
+    const blocks = formatCardSetupBlocks("http://api.test/card/handoff/tok");
+
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0]).toContain("Open this setup page to connect your card:");
+    expect(blocks[0]).toContain("http://api.test/card/handoff/tok");
+    expect(blocks[0]).toContain("securely save the card");
+    expect(blocks[0]).not.toContain("QR code above");
+  });
+});

package/src/core/__tests__/formatters.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { formatRunResult } from "../formatters.js";
+
+describe("formatRunResult", () => {
+  it("does not show a paid line for credit-pack-backed runs with zero cost", () => {
+    const output = formatRunResult({
+      agent_name: "Credit Pack Agent",
+      status: "success",
+      cost: 0,
+      consumption_mode: "credit_pack",
+      credit_pack_id: "pack-123",
+    }, { paymentMethod: "card" });
+
+    expect(output).toContain("Covered by credit pack (pack-123)");
+    expect(output).not.toContain("Paid:");
+  });
+});

package/src/core/__tests__/passes.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatCreditPack,
+  formatCreditPackOffer,
+  getActiveCreditPack,
+  getCreditPackProgram,
+} from "../passes.js";
+import type { AgentRecord } from "../types.js";
+
+const baseAgent: AgentRecord = {
+  id: "agent-1",
+  name: "Test Agent",
+  payment: {
+    credit_packs: {
+      unit_type: "run",
+      packs: [
+        { key: "starter", name: "Starter Pack", included_units: 5, price_usd: "1.00" },
+        { key: "growth", name: "Growth Pack", included_units: 20, price_usd: "3.00" },
+      ],
+    },
+  },
+};
+
+describe("getCreditPackProgram", () => {
+  it("returns the configured credit-pack program from agent metadata", () => {
+    expect(getCreditPackProgram(baseAgent)).toEqual({
+      unit_type: "run",
+      packs: [
+        { key: "starter", name: "Starter Pack", included_units: 5, price_usd: "1.00" },
+        { key: "growth", name: "Growth Pack", included_units: 20, price_usd: "3.00" },
+      ],
+    });
+  });
+});
+
+describe("formatCreditPackOffer", () => {
+  it("shows units and per-unit price", () => {
+    expect(formatCreditPackOffer({
+      pack_id: "starter",
+      label: "Starter Pack",
+      included_units: 5,
+      price_usd: "1.00",
+      effective_price_per_unit_usd: "0.200000",
+    })).toContain("Starter Pack");
+  });
+});
+
+describe("formatCreditPack", () => {
+  it("includes the pack status when it is no longer active", () => {
+    expect(formatCreditPack({
+      id: "pack-1",
+      status: "depleted",
+      unit_type: "run",
+      included_units: 5,
+      remaining_units: 0,
+      price_usd: "1.00",
+      purchased_at: "2026-05-04T15:08:28.700Z",
+      pack: { key: "starter", name: "Starter Pack" },
+    })).toContain("depleted");
+  });
+});
+
+describe("getActiveCreditPack", () => {
+  it("returns the oldest active balance with remaining units", () => {
+    const pack = getActiveCreditPack({
+      consumer_principal: "did:pkh:eip155:8453:0x1111111111111111111111111111111111111111",
+      offers: [],
+      balances: [
+        {
+          id: "newer",
+          status: "active",
+          unit_type: "run",
+          included_units: 20,
+          remaining_units: 20,
+          price_usd: "3.00",
+          purchased_at: "2026-04-10T00:00:00Z",
+          pack: { key: "growth", name: "Growth Pack" },
+        },
+        {
+          id: "older",
+          status: "active",
+          unit_type: "run",
+          included_units: 5,
+          remaining_units: 2,
+          price_usd: "1.00",
+          purchased_at: "2026-04-01T00:00:00Z",
+          pack: { key: "starter", name: "Starter Pack" },
+        },
+      ],
+    });
+
+    expect(pack?.id).toBe("older");
+  });
+});

package/src/core/__tests__/payments.test.ts

@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const TEST_KEY = "1111111111111111111111111111111111111111111111111111111111111111";
+
+let currentCard = {
+  consumerToken: "consumer_one",
+  paymentMethodId: "pm_one",
+  last4: "1111",
+  brand: "visa",
+};
+
+let currentDefaultWallet: any;
+let currentWallets: any[] = [];
+let currentResolvedMethod: { wallet: any; chain: string } | null = null;
+
+const createdFetches = [vi.fn(), vi.fn(), vi.fn(), vi.fn()];
+const mockMppxCreate = vi.fn();
+const mockStripe = vi.fn((opts: unknown) => opts);
+const mockTempo = vi.fn((..._args: unknown[]) => "tempo_method");
+const mockBaseChargeClient = vi.fn((..._args: unknown[]) => "base_method");
+
+vi.mock("../config.js", () => ({
+  getApiUrl: () => "http://api.test",
+  getCardConfig: () => currentCard,
+  getConfig: () => ({ defaultPaymentMethod: "card" }),
+  getDefaultWallet: () => currentDefaultWallet,
+  getWallets: () => currentWallets,
+  resolveWalletAndChain: () => currentResolvedMethod,
+}));
+
+vi.mock("mppx/client", () => ({
+  Mppx: {
+    create: (config: unknown) => mockMppxCreate(config),
+  },
+  stripe: (config: unknown) => mockStripe(config),
+  tempo: (config: unknown) => mockTempo(config),
+}));
+
+vi.mock("../base-charge.js", () => ({
+  baseChargeClient: (config: unknown) => mockBaseChargeClient(config),
+}));
+
+describe("payment method initialization", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+    currentCard = {
+      consumerToken: "consumer_one",
+      paymentMethodId: "pm_one",
+      last4: "1111",
+      brand: "visa",
+    };
+    currentDefaultWallet = undefined;
+    currentWallets = [];
+    currentResolvedMethod = null;
+    mockMppxCreate
+      .mockReturnValueOnce({ fetch: createdFetches[0] })
+      .mockReturnValueOnce({ fetch: createdFetches[1] })
+      .mockReturnValueOnce({ fetch: createdFetches[2] })
+      .mockReturnValueOnce({ fetch: createdFetches[3] });
+  });
+
+  it("rebuilds the cached card fetch when the card config changes", async () => {
+    const { getPaymentFetch } = await import("../payments.js");
+
+    const firstFetch = await getPaymentFetch("card");
+    currentCard = {
+      consumerToken: "consumer_two",
+      paymentMethodId: "pm_two",
+      last4: "2222",
+      brand: "mastercard",
+    };
+    const secondFetch = await getPaymentFetch("card");
+
+    expect(firstFetch).not.toBe(secondFetch);
+    expect(mockMppxCreate).toHaveBeenCalledTimes(2);
+  });
+
+  it("initializes only the Base method when base is requested", async () => {
+    const wallet = {
+      id: "aw-main",
+      keyType: "raw",
+      key: TEST_KEY,
+      chains: ["tempo", "base"],
+      defaultChain: "base",
+    };
+    currentDefaultWallet = wallet;
+    currentWallets = [wallet];
+    currentResolvedMethod = { wallet, chain: "base" };
+
+    const { getPaymentFetch } = await import("../payments.js");
+    await getPaymentFetch("base");
+
+    expect(mockBaseChargeClient).toHaveBeenCalledTimes(1);
+    expect(mockTempo).not.toHaveBeenCalled();
+    expect(mockMppxCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ methods: ["base_method"] }),
+    );
+  });
+
+  it("initializes only the Tempo method when tempo is requested", async () => {
+    const wallet = {
+      id: "aw-main",
+      keyType: "raw",
+      key: TEST_KEY,
+      chains: ["tempo", "base"],
+      defaultChain: "tempo",
+    };
+    currentDefaultWallet = wallet;
+    currentWallets = [wallet];
+    currentResolvedMethod = { wallet, chain: "tempo" };
+
+    const { getPaymentFetch } = await import("../payments.js");
+    await getPaymentFetch("tempo");
+
+    expect(mockTempo).toHaveBeenCalledTimes(1);
+    expect(mockBaseChargeClient).not.toHaveBeenCalled();
+    expect(mockMppxCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ methods: ["tempo_method"] }),
+    );
+  });
+});

package/src/core/__tests__/principal.test.ts

@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const state = vi.hoisted(() => ({
+  wallets: [] as Array<{
+    id: string;
+    keyType: "evm" | "ows";
+    key?: string;
+    owsWalletId?: string;
+    chains: string[];
+    defaultChain?: string;
+    label?: string;
+  }>,
+  addresses: {} as Record<string, string | null>,
+  addedWallets: [] as Array<Record<string, unknown>>,
+  owsAvailable: false,
+  owsWallets: [] as Array<{ id: string; name: string; address: string }>,
+}));
+
+vi.mock("../config.js", () => ({
+  addWallet: (wallet: Record<string, unknown>) => {
+    state.addedWallets.push(wallet);
+    state.wallets.push(wallet as any);
+  },
+  getDefaultWallet: () => state.wallets[0],
+  getWallets: () => state.wallets,
+}));
+
+vi.mock("../payments.js", () => ({
+  getWalletAddress: async (walletId: string) => {
+    if (walletId in state.addresses) {
+      return state.addresses[walletId] ?? null;
+    }
+
+    const wallet = state.wallets.find((entry) => entry.id === walletId);
+    if (wallet?.key) {
+      const { privateKeyToAccount } = await import("viem/accounts");
+      return privateKeyToAccount(wallet.key as `0x${string}`).address;
+    }
+
+    return null;
+  },
+}));
+
+vi.mock("../ows-adapter.js", () => ({
+  createOwsWallet: async (name: string) => ({
+    walletId: `ows-${name}`,
+    address: "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  }),
+  isOwsAvailable: async () => state.owsAvailable,
+  listOwsWallets: async () => state.owsWallets,
+}));
+
+describe("consumer principal helpers", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    state.wallets = [];
+    state.addresses = {};
+    state.addedWallets = [];
+    state.owsAvailable = false;
+    state.owsWallets = [];
+  });
+
+  it("prefers an EVM-backed principal when both EVM and Solana wallets exist", async () => {
+    state.wallets = [
+      { id: "sol-wallet", keyType: "ows", owsWalletId: "ows-sol", chains: ["solana"], defaultChain: "solana" },
+      { id: "evm-wallet", keyType: "evm", key: "0x1234", chains: ["tempo", "base"], defaultChain: "base" },
+    ];
+    state.addresses = {
+      "sol-wallet": "So1ana11111111111111111111111111111111111111",
+      "evm-wallet": "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+    };
+
+    const { getConsumerPrincipal } = await import("../principal.js");
+    const principal = await getConsumerPrincipal();
+
+    expect(principal).toBe("did:pkh:eip155:8453:0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
+  });
+
+  it("creates a fallback EVM identity wallet when none exists", async () => {
+    const { ensureConsumerPrincipal } = await import("../principal.js");
+    const principal = await ensureConsumerPrincipal();
+
+    expect(principal).toMatch(/^did:pkh:eip155:8453:0x[a-f0-9]{40}$/);
+    expect(state.addedWallets).toHaveLength(1);
+    expect(state.addedWallets[0]?.chains).toEqual(["tempo", "base"]);
+  });
+});

package/src/core/__tests__/spend-policy.test.ts

@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const state = {
+  policies: {} as Record<string, {
+    maxPerTxUsd?: number;
+    maxPerDayUsd?: number;
+    requireConfirmationAboveUsd?: number;
+  }>,
+  ledger: [] as Array<{ method: string; amountUsd: number; day: string; timestamp: string }>,
+};
+
+vi.mock("../config.js", () => ({
+  getSpendPolicy: (method: string) => state.policies[method] ?? null,
+  getSpendLedger: () => state.ledger,
+  saveSpendLedger: (entries: Array<{ method: string; amountUsd: number; day: string; timestamp: string }>) => {
+    state.ledger = entries;
+  },
+}));
+
+import {
+  canSpend,
+  getDailySpend,
+  recordSpend,
+  requiresPolicyConfirmation,
+} from "../spend-policy.js";
+
+describe("spend-policy", () => {
+  beforeEach(() => {
+    state.policies = {};
+    state.ledger = [];
+  });
+
+  it("allows spend when no policy is set", () => {
+    expect(canSpend({ method: "wallet-1", amountUsd: 5 })).toEqual({ ok: true });
+  });
+
+  it("blocks spends above max_per_tx", () => {
+    state.policies["wallet-1"] = { maxPerTxUsd: 2 };
+    const result = canSpend({ method: "wallet-1", amountUsd: 3 });
+    expect(result.ok).toBe(false);
+  });
+
+  it("tracks daily spend totals per method", () => {
+    const now = new Date("2026-04-08T12:00:00.000Z");
+    recordSpend("wallet-1", 1.25, now);
+    recordSpend("wallet-1", 0.75, now);
+    recordSpend("wallet-2", 10, now);
+
+    expect(getDailySpend("wallet-1", now)).toBeCloseTo(2);
+    expect(getDailySpend("wallet-2", now)).toBeCloseTo(10);
+  });
+
+  it("requires explicit confirmation above configured threshold", () => {
+    state.policies["wallet-1"] = { requireConfirmationAboveUsd: 2 };
+    expect(requiresPolicyConfirmation("wallet-1", 1.99)).toBe(false);
+    expect(requiresPolicyConfirmation("wallet-1", 2)).toBe(true);
+  });
+});

package/src/core/amount-utils.ts

@@ -0,0 +1,5 @@
+import { parseUnits } from "viem";
+
+export function toAtomicAmount(amount: string, decimals = 6): bigint {
+  return parseUnits(amount, decimals);
+}

package/src/core/api-client.ts

@@ -1,5 +1,6 @@
 import { getApiUrl, getApiKey } from "./config.js";
 import { getPaymentFetch } from "./payments.js";
+import { ensureConsumerPrincipal, getConsumerPrincipal } from "./principal.js";
 
 // ── Error class ────────────────────────────────────────────────────
 
@@ -16,7 +17,12 @@ export class ApiError extends Error {
 
 // ── Internal helpers ───────────────────────────────────────────────
 
-function buildHeaders(): Record<string, string> {
+interface RequestOptions {
+  ensureConsumerPrincipal?: boolean;
+  extraHeaders?: Record<string, string>;
+}
+
+async function buildHeaders(options?: RequestOptions): Promise<Record<string, string>> {
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
     Accept: "application/json",
@@ -27,6 +33,17 @@ function buildHeaders(): Record<string, string> {
     headers["Authorization"] = `Bearer ${apiKey}`;
   }
 
+  const principal = options?.ensureConsumerPrincipal
+    ? await ensureConsumerPrincipal()
+    : await getConsumerPrincipal();
+  if (principal) {
+    headers["X-AW-Consumer-Principal"] = principal;
+  }
+
+  if (options?.extraHeaders) {
+    Object.assign(headers, options.extraHeaders);
+  }
+
   return headers;
 }
 
@@ -55,25 +72,56 @@ async function handleResponse<T>(response: Response): Promise<T> {
   return body as T;
 }
 
+function attachResponseMetadata<T>(result: T, response: Response): T {
+  if (!result || typeof result !== "object") {
+    return result;
+  }
+
+  const record = result as Record<string, unknown>;
+  const headerToken = response.headers.get("x-feedback-token");
+  if (headerToken && !("feedback_token" in record)) {
+    record.feedback_token = headerToken;
+  }
+
+  const consumptionMode = response.headers.get("x-aw-consumption-mode");
+  if (consumptionMode) {
+    record.consumption_mode = consumptionMode;
+  }
+
+  const creditPackId = response.headers.get("x-aw-credit-pack-id");
+  if (creditPackId) {
+    record.credit_pack_id = creditPackId;
+  }
+
+  const principal = response.headers.get("x-aw-consumer-principal");
+  if (principal) {
+    record.consumer_principal = principal;
+  }
+
+  return result;
+}
+
 // ── Public API ─────────────────────────────────────────────────────
 
-export async function apiGet<T>(path: string): Promise<T> {
+export async function apiGet<T>(path: string, options?: RequestOptions): Promise<T> {
   const url = `${getApiUrl()}${path}`;
   const response = await fetch(url, {
     method: "GET",
-    headers: buildHeaders(),
+    headers: await buildHeaders(options),
   });
-  return handleResponse<T>(response);
+  const result = await handleResponse<T>(response);
+  return attachResponseMetadata(result, response);
 }
 
-export async function apiPost<T>(path: string, body: unknown): Promise<T> {
+export async function apiPost<T>(path: string, body: unknown, options?: RequestOptions): Promise<T> {
   const url = `${getApiUrl()}${path}`;
   const response = await fetch(url, {
     method: "POST",
-    headers: buildHeaders(),
+    headers: await buildHeaders(options),
     body: JSON.stringify(body),
   });
-  return handleResponse<T>(response);
+  const result = await handleResponse<T>(response);
+  return attachResponseMetadata(result, response);
 }
 
 /**
@@ -81,34 +129,33 @@ export async function apiPost<T>(path: string, body: unknown): Promise<T> {
  * auto-handle 402 → sign → retry for paid endpoints.
  * Pass `payWith` to specify a method, or omit for auto-detection.
  */
-export async function apiPostWithPayment<T>(path: string, body: unknown, payWith?: string): Promise<T> {
+export async function apiPostWithPayment<T>(
+  path: string,
+  body: unknown,
+  payWith?: string,
+  options?: RequestOptions,
+): Promise<T> {
   const url = `${getApiUrl()}${path}`;
   const paymentFetch = await getPaymentFetch(payWith);
   const response = await paymentFetch(url, {
     method: "POST",
-    headers: buildHeaders(),
+    headers: await buildHeaders({
+      ensureConsumerPrincipal: true,
+      ...options,
+    }),
     body: JSON.stringify(body),
   });
   const result = await handleResponse<T>(response);
-
-  // mppx may strip extra fields from the response body during receipt processing.
-  // The gateway also sends feedback_token as a header to survive this.
-  if (result && typeof result === "object" && !("feedback_token" in result)) {
-    const headerToken = response.headers.get("x-feedback-token");
-    if (headerToken) {
-      (result as Record<string, unknown>).feedback_token = headerToken;
-    }
-  }
-
-  return result;
+  return attachResponseMetadata(result, response);
 }
 
-export async function apiPut<T>(path: string, body: unknown): Promise<T> {
+export async function apiPut<T>(path: string, body: unknown, options?: RequestOptions): Promise<T> {
   const url = `${getApiUrl()}${path}`;
   const response = await fetch(url, {
     method: "PUT",
-    headers: buildHeaders(),
+    headers: await buildHeaders(options),
     body: JSON.stringify(body),
   });
-  return handleResponse<T>(response);
+  const result = await handleResponse<T>(response);
+  return attachResponseMetadata(result, response);
 }

package/src/core/base-charge.ts

@@ -6,6 +6,7 @@
  */
 import { Method, Credential, z } from "mppx";
 import type { LocalAccount } from "viem/accounts";
+import { toAtomicAmount } from "./amount-utils.js";
 
 // Base USDC (Circle native)
 const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as const;
@@ -63,12 +64,12 @@ export function baseChargeClient(config: BaseChargeClientConfig) {
   return Method.toClient(baseChargeMethod as any, {
     async createCredential({ challenge }: any) {
       const { request } = challenge;
-      const amount = BigInt(request.amount);
+      const amount = toAtomicAmount(request.amount, request.decimals ?? 6);
       const recipient = request.recipient as `0x${string}`;
       const currency = (request.currency ?? BASE_USDC) as `0x${string}`;
 
       // Dynamic imports to keep the module lightweight
-      const { createWalletClient, createPublicClient, http, encodeFunctionData } = await import("viem");
+      const { createWalletClient, createPublicClient, http } = await import("viem");
       const { base } = await import("viem/chains");
 
       const rpcUrl = config.rpcUrl ?? "https://mainnet.base.org";