@paynodelabs/paynode-402-cli 2.5.0

package/marketplace/client.ts

@@ -0,0 +1,189 @@
+import { jsonEnvelope, reportError, withRetry, EXIT_CODES, GLOBAL_CONFIG } from '../utils.ts';
+import type { CatalogApiItem, CatalogListResponse, InvokePreparation } from './types.ts';
+
+export interface MarketplaceClientOptions {
+  baseUrl?: string;
+  json?: boolean;
+}
+
+export class MarketplaceError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly code: string = 'unknown_error'
+  ) {
+    super(message);
+    this.name = 'MarketplaceError';
+  }
+}
+
+export interface ListCatalogOptions {
+  network?: string;
+  limit?: number;
+  tag?: string[];
+  seller?: string;
+}
+
+export interface PrepareInvokeOptions {
+  network?: string;
+  payload?: any;
+}
+
+function joinUrl(baseUrl: string, path: string): string {
+  const normalizedBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${normalizedBase}${normalizedPath}`;
+}
+
+export interface RawCatalogApiItem {
+  id?: string;
+  api_id?: string;
+  name?: string;
+  title?: string;
+  api_name?: string;
+  description?: string;
+  tags?: string[];
+  price_per_call?: string | number;
+  price?: string | number;
+  amount?: string | number;
+  currency?: string;
+  network?: string;
+  seller?: any;
+  seller_name?: string;
+  wallet_address?: string;
+  method?: string;
+  http_method?: string;
+  payable_url?: string;
+  payment_url?: string;
+  invoke_url?: string;
+  input_schema?: any;
+  sample_response?: any;
+  headers_template?: any;
+}
+
+function normalizeCatalogItem(raw: RawCatalogApiItem): CatalogApiItem {
+  return {
+    id: raw.id || raw.api_id || '',
+    name: raw.name || raw.title || raw.api_name || raw.api_id || 'unnamed',
+    description: raw.description,
+    tags: Array.isArray(raw.tags) ? raw.tags : [],
+    price_per_call: String(raw.price_per_call || raw.price || raw.amount || '0'),
+    currency: raw.currency || 'USDC',
+    network: raw.network,
+    seller: (raw.seller && typeof raw.seller === 'object' && Object.keys(raw.seller).length > 0) ? {
+      name: raw.seller.name || raw.seller.seller_name,
+      wallet_address: raw.seller.wallet_address || raw.seller.address
+    } : {
+      name: raw.seller_name,
+      wallet_address: raw.wallet_address
+    },
+    method: raw.method || raw.http_method,
+    payable_url: raw.payable_url || raw.payment_url,
+    invoke_url: raw.invoke_url,
+    input_schema: raw.input_schema,
+    sample_response: raw.sample_response,
+    headers_template: raw.headers_template
+  };
+}
+
+export class MarketplaceClient {
+  private readonly baseUrl: string;
+  private readonly isJson: boolean;
+
+  constructor(options: MarketplaceClientOptions = {}) {
+    this.baseUrl = options.baseUrl || GLOBAL_CONFIG.MARKETPLACE_URL;
+    this.isJson = !!options.json;
+  }
+
+  private async request<T>(path: string, init?: RequestInit): Promise<T> {
+    const url = joinUrl(this.baseUrl, path);
+    const response = await withRetry(
+      () => fetch(url, init),
+      `marketplace:${path}`
+    );
+
+    if (!response.ok) {
+      const text = await response.text();
+      let errorMessage = `Marketplace request failed (${response.status}) at ${path}: ${text || 'empty response'}`;
+      let errorCode = 'unknown_error';
+      try {
+        const json = JSON.parse(text);
+        if (json.message) errorMessage = json.message;
+        errorCode = json.code || json.error || errorCode;
+      } catch { /* use defaults if parse fails */ }
+
+      throw new MarketplaceError(errorMessage, response.status, errorCode);
+    }
+
+    return await response.json() as T;
+  }
+
+  async listCatalog(options: ListCatalogOptions = {}): Promise<CatalogListResponse> {
+    const params = new URLSearchParams();
+    if (options.network) params.set('network', options.network);
+    if (options.limit) params.set('limit', String(options.limit));
+    if (options.seller) params.set('seller', options.seller);
+    for (const tag of options.tag || []) {
+      params.append('tag', tag);
+    }
+
+    const query = params.toString();
+    const path = `/api/v1/paid-apis${query ? `?${query}` : ''}`;
+    const raw = await this.request<any>(path);
+    const items = Array.isArray(raw.items)
+      ? raw.items.map(normalizeCatalogItem)
+      : Array.isArray(raw)
+        ? raw.map(normalizeCatalogItem)
+        : [];
+
+    return {
+      items,
+      total: raw.total || items.length
+    };
+  }
+
+  async getApiDetail(apiId: string, network?: string): Promise<CatalogApiItem> {
+    const params = new URLSearchParams();
+    if (network) params.set('network', network);
+    const query = params.toString();
+    const path = `/api/v1/paid-apis/${encodeURIComponent(apiId)}${query ? `?${query}` : ''}`;
+    const raw = await this.request<any>(path);
+    return normalizeCatalogItem(raw);
+  }
+
+  async prepareInvoke(apiId: string, options: PrepareInvokeOptions = {}): Promise<InvokePreparation> {
+    try {
+      const preparation = await this.request<InvokePreparation>(`/api/v1/paid-apis/${encodeURIComponent(apiId)}/invoke`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          network: options.network,
+          payload: options.payload ?? {}
+        })
+      });
+
+      if (!preparation.invoke_url) {
+        throw new Error('Preparation response missing invoke_url');
+      }
+
+      return preparation;
+    } catch (err: any) {
+      console.warn(`[Marketplace] /invoke preparation failed for ${apiId}, falling back to direct proxy. Error: ${err.message}`);
+      const detail = await this.getApiDetail(apiId, options.network);
+      const invokeUrl = detail.payable_url || detail.invoke_url;
+      if (!invokeUrl) {
+        throw new Error(`API '${apiId}' is missing payable_url/invoke_url and marketplace did not provide an invoke preparation.`);
+      }
+
+      return {
+        api_id: detail.id,
+        invoke_url: invokeUrl,
+        method: detail.method || 'POST',
+        headers: detail.headers_template || {},
+        body: options.payload ?? {}
+      };
+    }
+  }
+}

package/marketplace/types.ts

@@ -0,0 +1,37 @@
+export interface SellerInfo {
+  name?: string;
+  wallet_address?: string;
+}
+
+export interface CatalogApiItem {
+  id: string;
+  name: string;
+  description?: string;
+  tags?: string[];
+  price_per_call?: string;
+  currency?: string;
+  network?: string;
+  seller?: SellerInfo;
+  method?: string;
+  payable_url?: string;
+  invoke_url?: string;
+  input_schema?: Record<string, any>;
+  sample_response?: any;
+  headers_template?: Record<string, string>;
+  [key: string]: any;
+}
+
+export interface CatalogListResponse {
+  items: CatalogApiItem[];
+  total?: number;
+}
+
+export interface InvokePreparation {
+  api_id: string;
+  invoke_url: string;
+  method?: string;
+  headers?: Record<string, string>;
+  body?: any;
+  network?: string;
+  [key: string]: any;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@paynodelabs/paynode-402-cli",
+  "version": "2.5.0",
+  "description": "The official command-line interface for the PayNode protocol. Designed for AI Agents to execute stateless micro-payments via HTTP 402.",
+  "type": "module",
+  "main": "./index.ts",
+  "bin": {
+    "paynode-402": "./index.ts"
+  },
+  "keywords": [
+    "paynode",
+    "x402",
+    "payment-required",
+    "web3",
+    "bun",
+    "cli",
+    "agent"
+  ],
+  "author": "PayNode Labs",
+  "license": "MIT",
+  "scripts": {
+    "test": "bun test",
+    "build": "echo 'No build required for Bun' && exit 0"
+  },
+  "dependencies": {
+    "@paynodelabs/sdk-js": "^2.4.0",
+    "cac": "7.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PayNodeLabs/paynode-402-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PayNodeLabs/paynode-402-cli/issues"
+  },
+  "homepage": "https://github.com/PayNodeLabs/paynode-402-cli#readme"
+}

package/tests/commands.test.ts

@@ -0,0 +1,88 @@
+import { mock, describe, expect, test, beforeEach, afterEach, spyOn } from "bun:test";
+
+/**
+ * 🛡️ [TEST SAFETY]
+ * Prevent process.exit from killing the test runner.
+ */
+const exitSpy = spyOn(process, "exit").mockImplementation((code) => {
+    throw new Error(`PROCESS_EXIT_${code}`);
+});
+
+/**
+ * 🧬 [ENVIRONMENT SETUP]
+ * Pre-set environment variables before any module evaluation.
+ */
+process.env.CLIENT_PRIVATE_KEY = "0x" + "1".repeat(64);
+
+/**
+ * 🔒 [MOCK CORE]
+ */
+const mockEthers = {
+    parseEther: (v: string) => 1000000000000000n,
+    formatEther: (v: bigint) => "0.001",
+    formatUnits: (v: bigint, u: number) => (Number(v) / Math.pow(10, u)).toString(),
+    Wallet: class {
+        address = "0xMockAddress";
+        //@ts-ignore
+        connect = () => this;
+        constructor(pk: string, provider: any) {}
+    },
+    Contract: class {
+        constructor() {
+            //@ts-ignore
+            this.balanceOf = async () => 1000000n;
+        }
+    },
+    JsonRpcProvider: class {
+        constructor(url: string) {}
+        //@ts-ignore
+        getNetwork = async () => ({ chainId: 84532n });
+        //@ts-ignore
+        getBalance = async () => 1000000000000000n;
+    }
+};
+
+mock.module("ethers", () => mockEthers);
+mock.module("@paynodelabs/sdk-js", () => ({
+    ethers: mockEthers,
+    BASE_RPC_URLS: ["http://mock-rpc"],
+    BASE_RPC_URLS_SANDBOX: ["http://mock-rpc-sandbox"],
+    BASE_USDC_ADDRESS: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    BASE_USDC_ADDRESS_SANDBOX: "0x65c088EfBDB0E03185Dbe8e258Ad0cf4Ab7946b0",
+    PAYNODE_ROUTER_ADDRESS: "0x4A73696ccF76E7381b044cB95127B3784369Ed63",
+    PAYNODE_ROUTER_ADDRESS_SANDBOX: "0x24cD8b68aaC209217ff5a6ef1Bf55a59f2c8Ca6F"
+}));
+
+/**
+ * 🚀 [DEFERRED LOADING]
+ */
+const { checkAction } = await import("../commands/check.ts");
+
+describe("checkAction() CLI command tests", () => {
+    let logSpy: any;
+
+    beforeEach(() => {
+        logSpy = spyOn(console, "log").mockImplementation(() => {});
+        exitSpy.mockClear();
+    });
+
+    afterEach(() => {
+        logSpy.mockRestore();
+    });
+
+    test("✅ Should output JSON status when --json is provided", async () => {
+        await checkAction({ json: true });
+        
+        expect(logSpy).toHaveBeenCalled();
+        const lastCall = logSpy.mock.calls[logSpy.mock.calls.length - 1][0];
+        const output = JSON.parse(lastCall);
+        expect(output.status).toBe("success");
+        expect(output.address).toBe("0xMockAddress");
+    });
+
+    test("✅ Should output human-readable status by default", async () => {
+        await checkAction({ json: false });
+        expect(logSpy).toHaveBeenCalled();
+        expect(logSpy.mock.calls[0][0]).toContain("PayNode Wallet Status");
+    });
+});

package/tests/network.test.ts

@@ -0,0 +1,53 @@
+import { mock, describe, expect, test } from "bun:test";
+
+/**
+ * ⚠️ [CRITICAL] 
+ * This mock must reside at the very top of the file to intercept
+ * dynamic imports within resolveNetwork() before they evaluate.
+ */
+mock.module("@paynodelabs/sdk-js", () => {
+    const mockProvider = {
+        getNetwork: async () => ({ chainId: 84532n }), // Force testnet for all
+        getBalance: async () => 1000000000001n
+    };
+    return {
+        ethers: {
+            JsonRpcProvider: class {
+                constructor(public url: string) {}
+                getNetwork = async () => mockProvider.getNetwork();
+            }
+        },
+        BASE_RPC_URLS: ["http://mock-rpc"],
+        BASE_RPC_URLS_SANDBOX: ["http://mock-rpc-sandbox"],
+        BASE_USDC_ADDRESS: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        BASE_USDC_ADDRESS_SANDBOX: "0x65c088EfBDB0E03185Dbe8e258Ad0cf4Ab7946b0",
+        PAYNODE_ROUTER_ADDRESS: "0x4A73696ccF76E7381b044cB95127B3784369Ed63",
+        PAYNODE_ROUTER_ADDRESS_SANDBOX: "0x24cD8b68aaC209217ff5a6ef1Bf55a59f2c8Ca6F"
+    };
+});
+
+import { resolveNetwork } from "../utils.ts";
+
+describe("resolveNetwork() unit tests with direct mock", () => {
+    
+    test("✅ Should resolve testnet (Sepolia) by alias", async () => {
+        const config = await resolveNetwork(undefined, "testnet");
+        expect(config.chainId).toBe(84532);
+        expect(config.isSandbox).toBe(true);
+        expect(config.usdcAddress).toBe("0x65c088EfBDB0E03185Dbe8e258Ad0cf4Ab7946b0");
+        expect(config.routerAddress).toBe("0x24cD8b68aaC209217ff5a6ef1Bf55a59f2c8Ca6F");
+    });
+
+    test("✅ Should resolve mainnet (aliased to Sandbox in this mock)", async () => {
+        const config = await resolveNetwork(undefined, "mainnet");
+        // Due to our mock forcing 84532n, it will be treated as Sandbox.
+        expect(config.chainId).toBe(84532);
+        expect(config.networkName).toContain("84532");
+    });
+
+    test("✅ Should use provided custom RPC URL without timing out", async () => {
+        const customRpc = "http://my-mock-rpc-node.com";
+        const config = await resolveNetwork(customRpc);
+        expect(config.rpcUrl).toBe(customRpc);
+    });
+});

package/tests/utils.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test, mock, beforeAll, afterAll } from "bun:test";
+import { 
+    generateTaskId, 
+    maskAddress, 
+    jsonEnvelope, 
+    EXIT_CODES, 
+    SKILL_VERSION,
+    SDK_VERSION
+} from "../utils.ts";
+import fs from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+describe("PayNode CLI Utilities", () => {
+    
+    test("generateTaskId() should return unique alphanumeric strings", () => {
+        const id1 = generateTaskId();
+        const id2 = generateTaskId();
+        expect(id1).not.toBe(id2);
+        expect(id1).toMatch(/^[a-z0-9]+-[a-z0-9]+$/);
+    });
+
+    test("maskAddress() should mask long addresses", () => {
+        const addr = "0x1234567890abcdef1234567890abcdef12345678";
+        const masked = maskAddress(addr);
+        expect(masked).toBe("0x1234...5678");
+    });
+
+    test("maskAddress() should return short strings as-is", () => {
+        expect(maskAddress("abc")).toBe("abc");
+    });
+
+    test("jsonEnvelope() should include correct version metadata", () => {
+        const data = { foo: "bar" };
+        const envelope = JSON.parse(jsonEnvelope(data));
+        
+        expect(envelope.foo).toBe("bar");
+        expect(envelope.version).toBe(SKILL_VERSION);
+        expect(envelope.skill_version).toBe(SKILL_VERSION);
+        expect(envelope.sdk_version).toBe(SDK_VERSION);
+    });
+
+    test("EXIT_CODES should be consistent with protocol spec", () => {
+        expect(EXIT_CODES.SUCCESS).toBe(0);
+        expect(EXIT_CODES.GENERIC_ERROR).toBe(1);
+        expect(EXIT_CODES.AUTH_FAILURE).toBe(3);
+        expect(EXIT_CODES.INSUFFICIENT_FUNDS).toBe(7);
+        expect(EXIT_CODES.DUST_LIMIT).toBe(8);
+    });
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "ignoreDeprecations": "5.0",
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "paths": {
+      "*": ["./node_modules/*"]
+    },
+    "types": ["bun-types"]
+  },
+  "include": ["**/*.ts"]
+}