@agentbadge/circle-payments 0.1.8 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,33 @@
1
+ import { spawn } from "node:child_process";
2
+ export interface PolicyCaps {
3
+ perTx?: string;
4
+ daily?: string;
5
+ weekly?: string;
6
+ monthly?: string;
7
+ raw?: unknown;
8
+ }
9
+ export interface AgentWalletInfo {
10
+ address: string;
11
+ chain: string;
12
+ raw?: unknown;
13
+ }
14
+ export interface CircleCliStatus {
15
+ loggedIn: boolean;
16
+ email?: string;
17
+ }
18
+ export interface CircleCliClient {
19
+ isAvailable(): Promise<boolean>;
20
+ status(): Promise<CircleCliStatus>;
21
+ listWallets(chain: string): Promise<AgentWalletInfo[]>;
22
+ balance(address: string, chain: string): Promise<string>;
23
+ limits(address: string, chain: string): Promise<PolicyCaps>;
24
+ }
25
+ export declare class CliUnavailableError extends Error {
26
+ constructor(message: string);
27
+ }
28
+ export interface CircleCliOptions {
29
+ cliPath?: string;
30
+ timeoutMs?: number;
31
+ spawnFn?: typeof spawn;
32
+ }
33
+ export declare function createCircleCliClient(opts?: CircleCliOptions): CircleCliClient;
@@ -0,0 +1,186 @@
1
+ import { spawn } from "node:child_process";
2
+ import { isAddress } from "viem";
3
+ export class CliUnavailableError extends Error {
4
+ constructor(message) {
5
+ super(message);
6
+ this.name = "CliUnavailableError";
7
+ }
8
+ }
9
+ const CHAIN_RE = /^[a-z0-9-]+$/i;
10
+ const SIGTERM_GRACE_MS = 500;
11
+ function assertArgvSafe(name, value) {
12
+ if (name === "chain") {
13
+ if (!CHAIN_RE.test(value))
14
+ throw new Error(`invalid chain value rejected from argv: "${value}"`);
15
+ return;
16
+ }
17
+ if (name === "address" && !isAddress(value)) {
18
+ throw new Error(`invalid address rejected from argv: "${value}"`);
19
+ }
20
+ }
21
+ function runCli(cliPath, args, timeoutMs, spawnFn) {
22
+ return new Promise((resolve, reject) => {
23
+ let child;
24
+ try {
25
+ child = spawnFn(cliPath, args, { stdio: ["ignore", "pipe", "pipe"] });
26
+ }
27
+ catch (err) {
28
+ reject(new CliUnavailableError(`spawn failed: ${String(err)}`));
29
+ return;
30
+ }
31
+ let stdout = "";
32
+ let stderr = "";
33
+ let finished = false;
34
+ const kill = setTimeout(() => {
35
+ if (finished)
36
+ return;
37
+ finished = true;
38
+ child.kill("SIGTERM");
39
+ setTimeout(() => {
40
+ try {
41
+ child.kill("SIGKILL");
42
+ }
43
+ catch {
44
+ }
45
+ }, SIGTERM_GRACE_MS).unref();
46
+ reject(new CliUnavailableError(`cli timeout after ${timeoutMs}ms`));
47
+ }, timeoutMs);
48
+ kill.unref();
49
+ child.stdout?.on("data", (d) => {
50
+ stdout += d.toString("utf8");
51
+ });
52
+ child.stderr?.on("data", (d) => {
53
+ stderr += d.toString("utf8");
54
+ });
55
+ child.on("error", (err) => {
56
+ if (finished)
57
+ return;
58
+ finished = true;
59
+ clearTimeout(kill);
60
+ if (err.code === "ENOENT") {
61
+ reject(new CliUnavailableError(`cli not found: ${cliPath}`));
62
+ }
63
+ else {
64
+ reject(new CliUnavailableError(`cli error: ${String(err)}`));
65
+ }
66
+ });
67
+ child.on("close", (code) => {
68
+ if (finished)
69
+ return;
70
+ finished = true;
71
+ clearTimeout(kill);
72
+ resolve({ code: code ?? -1, stdout, stderr });
73
+ });
74
+ });
75
+ }
76
+ function parseJson(stdout, what) {
77
+ try {
78
+ return JSON.parse(stdout);
79
+ }
80
+ catch {
81
+ throw new CliUnavailableError(`cli returned non-JSON for ${what}`);
82
+ }
83
+ }
84
+ export function createCircleCliClient(opts = {}) {
85
+ const cliPath = opts.cliPath ?? "circle";
86
+ const timeoutMs = opts.timeoutMs ?? 15_000;
87
+ const spawnFn = opts.spawnFn ?? spawn;
88
+ let availability = null;
89
+ const isAvailable = async () => {
90
+ if (availability !== null)
91
+ return availability;
92
+ try {
93
+ const r = await runCli(cliPath, ["--version"], Math.min(timeoutMs, 5_000), spawnFn);
94
+ availability = r.code === 0;
95
+ }
96
+ catch {
97
+ availability = false;
98
+ }
99
+ return availability;
100
+ };
101
+ const must = async () => {
102
+ if (!(await isAvailable())) {
103
+ throw new CliUnavailableError("circle cli unavailable");
104
+ }
105
+ };
106
+ const call = async (args) => {
107
+ const r = await runCli(cliPath, [...args, "--output", "json"], timeoutMs, spawnFn);
108
+ if (r.code !== 0) {
109
+ throw new CliUnavailableError(`cli exit ${r.code}: ${r.stderr.trim().slice(0, 200) || "no stderr"}`);
110
+ }
111
+ return r.stdout;
112
+ };
113
+ return {
114
+ isAvailable,
115
+ async status() {
116
+ await must();
117
+ const out = parseJson(await call(["wallet", "status"]), "wallet status");
118
+ return {
119
+ loggedIn: Boolean(out.loggedIn ?? out.logged_in ?? true),
120
+ ...(typeof out.email === "string" ? { email: out.email } : {}),
121
+ };
122
+ },
123
+ async listWallets(chain) {
124
+ assertArgvSafe("chain", chain);
125
+ await must();
126
+ const out = parseJson(await call(["wallet", "list", "--chain", chain]), "wallet list");
127
+ const rows = Array.isArray(out)
128
+ ? out
129
+ : out.wallets ?? [];
130
+ return rows
131
+ .filter((r) => r && typeof r.address === "string")
132
+ .map((r) => ({
133
+ address: r.address,
134
+ chain,
135
+ raw: r,
136
+ }));
137
+ },
138
+ async balance(address, chain) {
139
+ assertArgvSafe("address", address);
140
+ assertArgvSafe("chain", chain);
141
+ if (!(await isAvailable()))
142
+ return "unavailable";
143
+ try {
144
+ const out = parseJson(await call([
145
+ "wallet",
146
+ "balance",
147
+ "--address",
148
+ address,
149
+ "--chain",
150
+ chain,
151
+ ]), "wallet balance");
152
+ const v = out.balance ?? out.usdc ?? out.amount;
153
+ return v === undefined ? "unavailable" : String(v);
154
+ }
155
+ catch (err) {
156
+ if (err instanceof CliUnavailableError)
157
+ return "unavailable";
158
+ throw err;
159
+ }
160
+ },
161
+ async limits(address, chain) {
162
+ assertArgvSafe("address", address);
163
+ assertArgvSafe("chain", chain);
164
+ await must();
165
+ const out = parseJson(await call(["wallet", "limit", "--address", address, "--chain", chain]), "wallet limit");
166
+ const caps = {};
167
+ const pick = (k, keys) => {
168
+ for (const key of keys) {
169
+ const v = out[key];
170
+ if (typeof v === "string" || typeof v === "number") {
171
+ caps[k] = String(v);
172
+ return;
173
+ }
174
+ }
175
+ };
176
+ pick("perTx", ["perTx", "per_tx", "perTransaction"]);
177
+ pick("daily", ["daily"]);
178
+ pick("weekly", ["weekly"]);
179
+ pick("monthly", ["monthly"]);
180
+ if (!caps.perTx && !caps.daily && !caps.weekly && !caps.monthly) {
181
+ caps.raw = out;
182
+ }
183
+ return caps;
184
+ },
185
+ };
186
+ }
@@ -0,0 +1 @@
1
+ export * from "./cli.js";
@@ -0,0 +1 @@
1
+ export * from "./cli.js";
package/dist/index.d.ts CHANGED
@@ -17,3 +17,4 @@ export * from "./escrow/commission.js";
17
17
  export * from "./identity/erc8004.js";
18
18
  export * from "./identity/verify-passport.js";
19
19
  export * from "./memo/memo.js";
20
+ export * from "./agent-wallet/index.js";
package/dist/index.js CHANGED
@@ -17,3 +17,4 @@ export * from "./escrow/commission.js";
17
17
  export * from "./identity/erc8004.js";
18
18
  export * from "./identity/verify-passport.js";
19
19
  export * from "./memo/memo.js";
20
+ export * from "./agent-wallet/index.js";
@@ -1,4 +1,4 @@
1
- import type { MiddlewareHandler } from "hono";
1
+ import type { Context, MiddlewareHandler } from "hono";
2
2
  import type { PaymentRequirements } from "./chains.js";
3
3
  import { type FailureAlert, type FailureStore } from "./ledger.js";
4
4
  import { type PaymentRouter, type PaymentRouterConfig } from "./router.js";
@@ -9,6 +9,18 @@ export interface RequirePaymentOptions extends PaymentRouterConfig {
9
9
  extensions?: Record<string, unknown> | (() => Promise<Record<string, unknown> | undefined>);
10
10
  failureStore?: FailureStore;
11
11
  onFailure?: FailureAlert;
12
+ onBeforeSettle?: (args: {
13
+ c: Context;
14
+ paymentPayload: PaymentPayload;
15
+ requirements: PaymentRequirements;
16
+ payer?: string;
17
+ }) => Promise<Response | void>;
18
+ onSettleResult?: (args: {
19
+ c: Context;
20
+ ok: boolean;
21
+ payment?: PaymentInfo;
22
+ error?: string;
23
+ }) => Promise<void> | void;
12
24
  }
13
25
  export interface PaymentInfo {
14
26
  payer?: string;
@@ -67,12 +67,35 @@ export function requirePayment(price, opts) {
67
67
  if (!requirements) {
68
68
  return paymentRequired(c, accepts, opts, "Unsupported payment option");
69
69
  }
70
+ const maxHeader = c.req.header("x-max-amount");
71
+ if (maxHeader !== undefined) {
72
+ const maxUsd = Number.parseFloat(maxHeader);
73
+ const priceUsd = Number(requirements.amount) / 1_000_000;
74
+ if (!Number.isFinite(maxUsd) || maxUsd < 0 || priceUsd > maxUsd) {
75
+ return paymentRequired(c, accepts, opts, `Price $${priceUsd} exceeds declared X-Max-Amount "${maxHeader}"`);
76
+ }
77
+ }
70
78
  const verifyResult = await router.verify(paymentPayload, requirements);
71
79
  if (!verifyResult.isValid) {
72
80
  return paymentRequired(c, accepts, opts, verifyResult.invalidReason ?? "Payment verification failed");
73
81
  }
82
+ if (opts.onBeforeSettle) {
83
+ const deny = await opts.onBeforeSettle({
84
+ c,
85
+ paymentPayload,
86
+ requirements,
87
+ payer: verifyResult.payer,
88
+ });
89
+ if (deny instanceof Response)
90
+ return deny;
91
+ }
74
92
  const settleResult = await router.settle(paymentPayload, requirements);
75
93
  if (!settleResult.success) {
94
+ await opts.onSettleResult?.({
95
+ c,
96
+ ok: false,
97
+ error: settleResult.errorReason ?? "Payment settlement failed",
98
+ });
76
99
  return paymentRequired(c, accepts, opts, settleResult.errorReason ?? "Payment settlement failed");
77
100
  }
78
101
  const payment = {
@@ -83,6 +106,7 @@ export function requirePayment(price, opts) {
83
106
  amount: requirements.amount,
84
107
  };
85
108
  c.set("payment", payment);
109
+ await opts.onSettleResult?.({ c, ok: true, payment });
86
110
  await next();
87
111
  if (c.error && opts.failureStore) {
88
112
  await recordFailure(opts.failureStore, {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentbadge/circle-payments",
3
- "version": "0.1.8",
3
+ "version": "0.1.11",
4
4
  "description": "Circle Gateway nanopayments + x402 payment rails (Base Sepolia, Arc) for AgentBadge — trusted agent payments",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",