@envarai/envarpay 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 EnvarAI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,158 @@
+# @envarai/envarpay
+
+A TypeScript client for an existing **authenticated EnvarPay wallet MCP service**.
+The client does not install Python, run a signer, hold wallet keys, or change wallet
+policy. Use the Python CLI or a separately operated service for those responsibilities.
+
+This client uses the alpha release channel. See
+[installation channels](https://github.com/EnvarAI/EnvarPay/blob/main/docs/packages.md)
+for the current registry status and available distributions.
+
+## Install and start a wallet
+
+Install the npm alpha client:
+
+```sh
+npm install @envarai/envarpay@next
+```
+
+If your project uses a custom package registry, route this scope to the public
+registry in its `.npmrc`: `@envarai:registry=https://registry.npmjs.org/`.
+
+Node.js >=22.14 and Bun are supported. Import this package from an ESM application.
+The npm library is a client; the wallet runs as a separate service:
+
+```sh
+uv tool install --python 3.13 --prerelease allow envarpay
+envarpay init --agent mcp --role buyer --directory ./buyer \
+  --peer-url https://seller.example/mcp --pay-to SELLER_FULL_RECEIVING_ADDRESS \
+  --tool ask_agent --max-per-call 0.01 --budget 0.05
+envarpay keygen --output ./buyer/buyer.key
+```
+
+The generated policy uses Base Sepolia test USDC and payments off. Fund the
+dedicated test wallet, review the recipient/tool/limits and enable payments only
+for your intended purchases. The agent never receives the wallet key.
+
+Create the wallet-access credential in your private operator environment. This
+command never prints it and refuses to overwrite an existing file:
+
+```sh
+python3 - <<'PY'
+import os, secrets
+with os.fdopen(os.open('buyer/wallet-service.token', os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), 'w') as f:
+    f.write(secrets.token_urlsafe(32))
+PY
+```
+
+Add this table to the existing `buyer.toml`:
+
+```toml
+[wallet_server]
+host = "127.0.0.1"
+port = 4021
+allowed_hosts = ["127.0.0.1:*", "localhost:*"]
+bearer_token_file = "./wallet-service.token"
+```
+
+```sh
+envarpay doctor --config ./buyer/buyer.toml
+envarpay wallet-serve --config ./buyer/buyer.toml
+```
+
+For local development, connect to `http://127.0.0.1:4021/mcp`. For a separate wallet
+permission boundary, run it under another OS identity/container or on a private
+service with HTTPS; only the wallet receives its key, policy and ledger. Keep the
+wallet service private. Give the client its wallet-access token, not a seller's
+token or an Envar machine credential.
+
+## Discover tools and make a purchase
+
+```ts
+import { WalletClient, OperationUnknownError } from '@envarai/envarpay';
+
+const wallet = await WalletClient.connect({
+  url: 'https://wallet.example/mcp',
+  token: process.env.ENVARPAY_WALLET_TOKEN!,
+});
+try {
+    const tools = await wallet.listPaidTools('approved-seller');
+  console.log(tools.tools.map(tool => tool.name));
+  // This may pay within the wallet operator's existing allowlist and budget.
+  const result = await wallet.callPaidTool({
+    peer: 'approved-seller', tool: 'ask_agent',
+    arguments: { question: 'Review my API design' }, requestId: 'review-001',
+  });
+  console.log(result.result.content);
+} catch (error) {
+  if (error instanceof OperationUnknownError) {
+    console.log(await wallet.paymentStatus(error.requestId));
+    // When the operator-approved seller supports recovery:
+    // await wallet.recoverPayment(error.requestId);
+  } else throw error;
+} finally {
+  await wallet.close();
+}
+```
+
+Use the alias actually configured in `buyer.toml` (the quickstart generates `seller`).
+`listPaidTools` does not pay. `callPaidTool` may spend within the existing wallet
+policy; `paymentStatus` and `recoverPayment` retain the original purchase.
+
+## Envar discovery and transaction pages
+
+With the optional `[connection]` in the wallet, these additional methods read
+Envar's public catalog:
+
+```ts
+const candidates = await wallet.discoverAgents('research');
+console.log(candidates.payment_authorized); // always false
+const profile = await wallet.getAgent('THE_PUBLISHED_AGENT_HANDLE');
+```
+
+The operator still approves and configures a peer before purchasing from it.
+The Python wallet handles optional durable Envar reports; the npm client does not
+duplicate signing, settlement or the platform's payment verification.
+[Complete Envar setup](https://github.com/EnvarAI/EnvarPay/blob/main/docs/envar.md).
+
+## Receiving and asynchronous tasks
+
+For **receiving**, put the Python `envarpay` payment gate in front of your existing
+private JS/TS MCP tool and expose only the gate through HTTPS. No buyer-wallet
+client is needed to receive payments; the seller does not need a signing key.
+[Seller quickstart](https://github.com/EnvarAI/EnvarPay/blob/main/docs/selling.md).
+
+For **asynchronous escrow/acceptance/refunds**, use Python `envarpay[task]` and
+`envarpay task wallet` with your host's standard MCP client. The task mode is an
+experimental Base Sepolia-only flow, separate from this upfront wallet API.
+[Task guide](https://github.com/EnvarAI/EnvarPay/blob/main/docs/tasks/README.md).
+
+## Errors and recovery
+
+Persist the request ID in your application before calling. Never replace it after
+an uncertain result. The client does not retry paid calls; the wallet retains the
+original authorization and ledger. A `WalletToolError` preserves an explicit
+wallet refusal/execution error. An `OperationUnknownError` means the result is
+uncertain, including transport failures and timeouts; it does not mean no payment occurred.
+
+HTTPS is required except for loopback HTTP. Redirects are rejected, including
+redirects to another wallet URL. The bearer token belongs to the wallet service,
+not to a seller or public directory; keep it in the application's private config.
+
+Targets Node.js >=22.14 and Bun. Local tests use the actual Python wallet MCP
+adapter with a fake service and transfer no funds; they are not real payment evidence.
+This client has no task-escrow API or framework-native plugin manifest.
+
+## Reviewed purchases from Envar
+
+Run Python EnvarPay 0.1.0a8 or newer for these methods. `walletPolicy()` reads limits
+and already-approved peers. `callAgent()` selects only a peer bound to the reviewed
+Agent and endpoint IDs; it never adds a directory candidate to wallet policy. Supply
+`expectedNetwork`, `expectedPayTo` and `expectedAmountAtomic` from the terms you
+reviewed. A different live price is refused before signing. Keep `requestId` across
+uncertain outcomes and use the original status/recovery methods.
+
+The website can use the same authenticated wallet through its owner-only entry.
+For task creation, result verification and acceptance/refunds, connect the private
+`envarpay task wallet-serve` using a standard MCP client. The task signer and
+contract verification stay in Python; the task mode remains experimental/testnet.

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface PaidTools {
+    peer: string;
+    tools: Tool[];
+}
+export interface AgentDiscovery {
+    candidates: Record<string, unknown>[];
+    payment_authorized: false;
+}
+export interface WalletPolicy {
+    network: string;
+    payments_enabled: boolean;
+    max_per_call_atomic: number;
+    max_total_atomic: number;
+    peers: {
+        name: string;
+        agent_id: string | null;
+        endpoint_id: string | null;
+        pay_to: string;
+        tools: string[];
+    }[];
+}
+export interface ReviewedAgentCall {
+    agentId: string;
+    endpointId: string;
+    tool: string;
+    arguments: Record<string, Json>;
+    requestId: string;
+    expectedNetwork: string;
+    expectedPayTo: string;
+    expectedAmountAtomic: number;
+}
+export interface PaidCall {
+    request_id: string;
+    payment_made: boolean;
+    payment: Record<string, unknown> | null;
+    result: CallToolResult;
+}
+export interface PaymentStatus {
+    id: string;
+    status: string;
+    amount: number;
+    updated: number;
+    transaction: string | null;
+    payment_state: string | null;
+    execution_state: string | null;
+    invocation_id: string | null;
+    report_pending: boolean;
+}
+export type RecoveryResult = PaidCall | ({
+    request_id: string;
+} & Record<string, unknown>);
+export interface WalletConnection {
+    url: string | URL;
+    token: string;
+    timeoutMs?: number;
+}
+/** A wallet refusal or execution error, preserved from the MCP tool response. */
+export declare class WalletToolError extends Error {
+    readonly tool: string;
+    readonly response: CallToolResult;
+    constructor(tool: string, response: CallToolResult);
+}
+/** The call may have reached the wallet. Inspect/recover this ID before another call. */
+export declare class OperationUnknownError extends Error {
+    readonly requestId: string;
+    constructor(requestId: string, cause: unknown);
+}
+/** A remote wallet client. Signing, policy and durable recovery stay in the wallet. */
+export declare class WalletClient {
+    private readonly client;
+    private readonly timeoutMs;
+    private constructor();
+    static connect(options: WalletConnection): Promise<WalletClient>;
+    private call;
+    listPaidTools(peer: string): Promise<PaidTools>;
+    /** Requires an optional Envar connection in the wallet; discovery grants no payment authority. */
+    discoverAgents(query: string): Promise<AgentDiscovery>;
+    /** Read a published profile without modifying the wallet's operator-owned peers. */
+    getAgent(handle: string): Promise<Record<string, unknown>>;
+    callPaidTool(input: {
+        peer: string;
+        tool: string;
+        arguments: Record<string, Json>;
+        requestId: string;
+    }): Promise<PaidCall>;
+    walletPolicy(): Promise<WalletPolicy>;
+    callAgent(input: ReviewedAgentCall): Promise<PaidCall>;
+    paymentStatus(id: string): Promise<PaymentStatus[]>;
+    recoverPayment(id: string): Promise<RecoveryResult>;
+    close(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,161 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/** A wallet refusal or execution error, preserved from the MCP tool response. */
+export class WalletToolError extends Error {
+    tool;
+    response;
+    constructor(tool, response) {
+        super(response.content.filter(c => c.type === 'text').map(c => c.text).join('\n') || 'Wallet tool failed');
+        this.tool = tool;
+        this.response = response;
+        this.name = 'WalletToolError';
+    }
+}
+/** The call may have reached the wallet. Inspect/recover this ID before another call. */
+export class OperationUnknownError extends Error {
+    requestId;
+    constructor(requestId, cause) {
+        super(`Operation ${requestId} is unresolved; inspect paymentStatus or recoverPayment with this ID`, { cause });
+        this.requestId = requestId;
+        this.name = 'OperationUnknownError';
+    }
+}
+function requestId(value) {
+    if (!/^[A-Za-z0-9_-]{1,100}$/.test(value)) {
+        throw new TypeError('requestId must be 1-100 letters, digits, underscores or hyphens');
+    }
+}
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function decode(result) {
+    if (result.structuredContent !== undefined)
+        return result.structuredContent;
+    const texts = result.content.filter(c => c.type === 'text');
+    if (texts.length !== 1)
+        throw new TypeError('Expected a JSON wallet tool response');
+    return JSON.parse(texts[0].text);
+}
+/** A remote wallet client. Signing, policy and durable recovery stay in the wallet. */
+export class WalletClient {
+    client;
+    timeoutMs;
+    constructor(client, timeoutMs) {
+        this.client = client;
+        this.timeoutMs = timeoutMs;
+    }
+    static async connect(options) {
+        const url = new URL(options.url);
+        const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+        if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) || url.username || url.password || url.hash || url.search) {
+            throw new TypeError('Wallet URL must use HTTPS or loopback HTTP, without credentials or a fragment');
+        }
+        if (!options.token || /[\r\n]/.test(options.token))
+            throw new TypeError('A wallet bearer token is required');
+        const timeoutMs = options.timeoutMs ?? 300_000;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new TypeError('timeoutMs must be positive');
+        const client = new Client({ name: '@envarai/envarpay', version: '0.1.0-alpha.2' });
+        const transport = new StreamableHTTPClientTransport(url, {
+            requestInit: { headers: { Authorization: `Bearer ${options.token}` }, redirect: 'error' },
+        });
+        try {
+            await client.connect(transport, { timeout: timeoutMs });
+            return new WalletClient(client, timeoutMs);
+        }
+        catch (error) {
+            await client.close().catch(() => { });
+            throw error;
+        }
+    }
+    async call(tool, args) {
+        const response = await this.client.callTool({ name: tool, arguments: args }, undefined, { timeout: this.timeoutMs });
+        if (response.isError)
+            throw new WalletToolError(tool, response);
+        return decode(response);
+    }
+    async listPaidTools(peer) {
+        const value = await this.call('list_paid_tools', { peer });
+        if (!object(value) || typeof value.peer !== 'string' || !Array.isArray(value.tools)) {
+            throw new TypeError('Invalid paid tools response');
+        }
+        return value;
+    }
+    /** Requires an optional Envar connection in the wallet; discovery grants no payment authority. */
+    async discoverAgents(query) {
+        const value = await this.call('discover_agents', { query });
+        if (!object(value) || value.payment_authorized !== false || !Array.isArray(value.candidates) || value.candidates.some(candidate => !object(candidate))) {
+            throw new TypeError('Invalid agent discovery response');
+        }
+        return value;
+    }
+    /** Read a published profile without modifying the wallet's operator-owned peers. */
+    async getAgent(handle) {
+        const value = await this.call('get_agent', { handle });
+        if (!object(value))
+            throw new TypeError('Invalid agent profile response');
+        return value;
+    }
+    async callPaidTool(input) {
+        requestId(input.requestId);
+        try {
+            const value = await this.call('call_paid_tool', {
+                peer: input.peer, tool: input.tool, arguments: input.arguments, request_id: input.requestId,
+            });
+            if (!object(value) || value.request_id !== input.requestId || typeof value.payment_made !== 'boolean' || !object(value.result)) {
+                throw new TypeError('Invalid paid call response');
+            }
+            return value;
+        }
+        catch (error) {
+            if (error instanceof WalletToolError)
+                throw error;
+            throw new OperationUnknownError(input.requestId, error);
+        }
+    }
+    async walletPolicy() {
+        const value = await this.call('wallet_policy', {});
+        if (!object(value) || typeof value.network !== 'string' || typeof value.payments_enabled !== 'boolean' || !Array.isArray(value.peers)) {
+            throw new TypeError('Invalid wallet policy response');
+        }
+        return value;
+    }
+    async callAgent(input) {
+        requestId(input.requestId);
+        if (!Number.isSafeInteger(input.expectedAmountAtomic) || input.expectedAmountAtomic <= 0)
+            throw new TypeError('Review an integer USDC atomic amount');
+        try {
+            const value = await this.call('call_agent', {
+                agent_id: input.agentId, endpoint_id: input.endpointId, tool: input.tool, arguments: input.arguments,
+                request_id: input.requestId, expected_network: input.expectedNetwork, expected_pay_to: input.expectedPayTo,
+                expected_amount_atomic: input.expectedAmountAtomic,
+            });
+            if (!object(value) || value.request_id !== input.requestId || typeof value.payment_made !== 'boolean' || !object(value.result))
+                throw new TypeError('Invalid paid Agent response');
+            return value;
+        }
+        catch (error) {
+            if (error instanceof WalletToolError)
+                throw error;
+            throw new OperationUnknownError(input.requestId, error);
+        }
+    }
+    async paymentStatus(id) {
+        requestId(id);
+        const value = await this.call('payment_status', { request_id: id });
+        // FastMCP wraps non-object return types under "result" in structuredContent.
+        const rows = object(value) ? value.result : value;
+        if (!Array.isArray(rows) || rows.some(row => !object(row) || typeof row.id !== 'string' || typeof row.status !== 'string')) {
+            throw new TypeError('Invalid payment status response');
+        }
+        return rows;
+    }
+    async recoverPayment(id) {
+        requestId(id);
+        const value = await this.call('recover_payment', { request_id: id });
+        if (!object(value) || value.request_id !== id)
+            throw new TypeError('Invalid recovery response');
+        return value;
+    }
+    async close() { await this.client.close(); }
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@envarai/envarpay",
+  "version": "0.1.0-alpha.2",
+  "description": "Typed MCP client for an operator-configured EnvarPay wallet service",
+  "type": "module",
+  "license": "MIT",
+  "engines": { "node": ">=22.14.0" },
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "repository": { "type": "git", "url": "git+https://github.com/EnvarAI/EnvarPay.git", "directory": "packages/typescript" },
+  "publishConfig": { "access": "public", "tag": "next" },
+  "scripts": { "build": "tsc", "test": "npm run build && node --test test/client.test.mjs", "prepack": "npm run build" },
+  "dependencies": { "@modelcontextprotocol/sdk": "^1.31.0" },
+  "devDependencies": { "typescript": "~5.9.3", "@types/node": "^22.0.0" }
+}