@agentbadge/circle-payments 0.1.8 → 0.1.12

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";
@@ -0,0 +1,15 @@
1
+ export interface GatewayProbeOptions {
2
+ apiUrl: string;
3
+ probePath?: string;
4
+ intervalMs?: number;
5
+ downMs?: number;
6
+ fetchImpl?: typeof fetch;
7
+ onChange?: (up: boolean, reason: string) => void;
8
+ }
9
+ export interface GatewayProbe {
10
+ isUp(): boolean;
11
+ markFailure(): void;
12
+ start(): void;
13
+ stop(): void;
14
+ }
15
+ export declare function createGatewayProbe(opts: GatewayProbeOptions): GatewayProbe;
@@ -0,0 +1,62 @@
1
+ export function createGatewayProbe(opts) {
2
+ const intervalMs = opts.intervalMs ?? 30_000;
3
+ const downMs = opts.downMs ?? 30_000;
4
+ const probePath = opts.probePath ?? "/x402/transfers?pageSize=1";
5
+ const fetchImpl = opts.fetchImpl ?? fetch;
6
+ let downUntil = 0;
7
+ let downNotified = false;
8
+ let timer;
9
+ const url = `${opts.apiUrl.replace(/\/+$/, "")}${probePath}`;
10
+ function setDown(reason) {
11
+ downUntil = Date.now() + downMs;
12
+ if (!downNotified) {
13
+ downNotified = true;
14
+ opts.onChange?.(false, reason);
15
+ }
16
+ }
17
+ function setUp(reason) {
18
+ downUntil = 0;
19
+ if (downNotified) {
20
+ downNotified = false;
21
+ opts.onChange?.(true, reason);
22
+ }
23
+ }
24
+ async function probe() {
25
+ try {
26
+ const res = await fetchImpl(url);
27
+ if (res.ok) {
28
+ setUp("probe ok");
29
+ }
30
+ else {
31
+ setDown(`probe HTTP ${res.status}`);
32
+ }
33
+ }
34
+ catch (err) {
35
+ setDown(`probe ${err instanceof Error ? err.message : String(err)}`);
36
+ }
37
+ }
38
+ return {
39
+ isUp() {
40
+ if (downUntil === 0)
41
+ return true;
42
+ return Date.now() >= downUntil;
43
+ },
44
+ markFailure() {
45
+ setDown("handle failure");
46
+ },
47
+ start() {
48
+ if (timer)
49
+ return;
50
+ timer = setInterval(() => {
51
+ void probe();
52
+ }, intervalMs);
53
+ timer.unref?.();
54
+ },
55
+ stop() {
56
+ if (timer) {
57
+ clearInterval(timer);
58
+ timer = undefined;
59
+ }
60
+ },
61
+ };
62
+ }
package/dist/index.d.ts CHANGED
@@ -5,6 +5,7 @@ export * from "./schemes/exact.js";
5
5
  export * from "./schemes/arc-self-settle.js";
6
6
  export * from "./router.js";
7
7
  export * from "./middleware.js";
8
+ export * from "./gateway-probe.js";
8
9
  export * from "./identity.js";
9
10
  export * from "./ledger.js";
10
11
  export * from "./pricing.js";
@@ -17,3 +18,4 @@ export * from "./escrow/commission.js";
17
18
  export * from "./identity/erc8004.js";
18
19
  export * from "./identity/verify-passport.js";
19
20
  export * from "./memo/memo.js";
21
+ export * from "./agent-wallet/index.js";
package/dist/index.js CHANGED
@@ -5,6 +5,7 @@ export * from "./schemes/exact.js";
5
5
  export * from "./schemes/arc-self-settle.js";
6
6
  export * from "./router.js";
7
7
  export * from "./middleware.js";
8
+ export * from "./gateway-probe.js";
8
9
  export * from "./identity.js";
9
10
  export * from "./ledger.js";
10
11
  export * from "./pricing.js";
@@ -17,3 +18,4 @@ export * from "./escrow/commission.js";
17
18
  export * from "./identity/erc8004.js";
18
19
  export * from "./identity/verify-passport.js";
19
20
  export * from "./memo/memo.js";
21
+ 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";
@@ -6,9 +6,25 @@ export interface RequirePaymentOptions extends PaymentRouterConfig {
6
6
  router?: PaymentRouter;
7
7
  description?: string;
8
8
  mimeType?: string;
9
+ methods?: string[];
10
+ onBeforeChallenge?: (c: Context) => Promise<true | Response | void> | true | Response | void;
11
+ unpaidBody?: (c: Context) => Promise<unknown> | unknown;
12
+ resourceUrl?: (c: Context) => string;
9
13
  extensions?: Record<string, unknown> | (() => Promise<Record<string, unknown> | undefined>);
10
14
  failureStore?: FailureStore;
11
15
  onFailure?: FailureAlert;
16
+ onBeforeSettle?: (args: {
17
+ c: Context;
18
+ paymentPayload: PaymentPayload;
19
+ requirements: PaymentRequirements;
20
+ payer?: string;
21
+ }) => Promise<Response | void>;
22
+ onSettleResult?: (args: {
23
+ c: Context;
24
+ ok: boolean;
25
+ payment?: PaymentInfo;
26
+ error?: string;
27
+ }) => Promise<void> | void;
12
28
  }
13
29
  export interface PaymentInfo {
14
30
  payer?: string;
@@ -23,4 +39,5 @@ export interface PaymentPayload {
23
39
  accepted?: PaymentRequirements;
24
40
  payload?: Record<string, unknown>;
25
41
  }
26
- export declare function requirePayment(price: string, opts: RequirePaymentOptions): MiddlewareHandler;
42
+ export type PriceResolver = string | ((c: Context) => string | Promise<string>);
43
+ export declare function requirePayment(price: PriceResolver, opts: RequirePaymentOptions): MiddlewareHandler;
@@ -36,19 +36,42 @@ async function paymentRequired(c, accepts, opts, error) {
36
36
  x402Version: 2,
37
37
  ...(error ? { error } : {}),
38
38
  resource: {
39
- url: c.req.url,
39
+ url: opts.resourceUrl?.(c) ?? c.req.url,
40
40
  description: opts.description ?? "Paid resource",
41
41
  mimeType: opts.mimeType ?? "application/json",
42
42
  },
43
43
  accepts,
44
44
  ...(extensions ? { extensions } : {}),
45
45
  };
46
- return c.json({ error: error ?? "Payment required" }, 402, { "PAYMENT-REQUIRED": b64encode(body) });
46
+ const responseBody = opts.unpaidBody
47
+ ? await opts.unpaidBody(c)
48
+ : { error: error ?? "Payment required" };
49
+ return c.json(responseBody, 402, { "PAYMENT-REQUIRED": b64encode(body) });
47
50
  }
48
51
  export function requirePayment(price, opts) {
49
- const amount = priceToAmount(price);
52
+ const staticAmount = typeof price === "string" ? priceToAmount(price) : undefined;
50
53
  const router = opts.router ?? createPaymentRouter(opts);
54
+ const methods = opts.methods?.map((m) => m.toUpperCase());
51
55
  return async (c, next) => {
56
+ if (methods && !methods.includes(c.req.method.toUpperCase())) {
57
+ return next();
58
+ }
59
+ if (opts.onBeforeChallenge) {
60
+ const bypass = await opts.onBeforeChallenge(c);
61
+ if (bypass === true)
62
+ return next();
63
+ if (bypass instanceof Response)
64
+ return bypass;
65
+ }
66
+ let amount = staticAmount;
67
+ if (amount === undefined) {
68
+ try {
69
+ amount = priceToAmount(await price(c));
70
+ }
71
+ catch {
72
+ return c.json({ error: "Invalid price" }, 402);
73
+ }
74
+ }
52
75
  const accepts = router.acceptsFor(amount);
53
76
  const signatureHeader = c.req.header("payment-signature");
54
77
  if (!signatureHeader) {
@@ -67,12 +90,35 @@ export function requirePayment(price, opts) {
67
90
  if (!requirements) {
68
91
  return paymentRequired(c, accepts, opts, "Unsupported payment option");
69
92
  }
93
+ const maxHeader = c.req.header("x-max-amount");
94
+ if (maxHeader !== undefined) {
95
+ const maxUsd = Number.parseFloat(maxHeader);
96
+ const priceUsd = Number(requirements.amount) / 1_000_000;
97
+ if (!Number.isFinite(maxUsd) || maxUsd < 0 || priceUsd > maxUsd) {
98
+ return paymentRequired(c, accepts, opts, `Price $${priceUsd} exceeds declared X-Max-Amount "${maxHeader}"`);
99
+ }
100
+ }
70
101
  const verifyResult = await router.verify(paymentPayload, requirements);
71
102
  if (!verifyResult.isValid) {
72
103
  return paymentRequired(c, accepts, opts, verifyResult.invalidReason ?? "Payment verification failed");
73
104
  }
105
+ if (opts.onBeforeSettle) {
106
+ const deny = await opts.onBeforeSettle({
107
+ c,
108
+ paymentPayload,
109
+ requirements,
110
+ payer: verifyResult.payer,
111
+ });
112
+ if (deny instanceof Response)
113
+ return deny;
114
+ }
74
115
  const settleResult = await router.settle(paymentPayload, requirements);
75
116
  if (!settleResult.success) {
117
+ await opts.onSettleResult?.({
118
+ c,
119
+ ok: false,
120
+ error: settleResult.errorReason ?? "Payment settlement failed",
121
+ });
76
122
  return paymentRequired(c, accepts, opts, settleResult.errorReason ?? "Payment settlement failed");
77
123
  }
78
124
  const payment = {
@@ -83,6 +129,7 @@ export function requirePayment(price, opts) {
83
129
  amount: requirements.amount,
84
130
  };
85
131
  c.set("payment", payment);
132
+ await opts.onSettleResult?.({ c, ok: true, payment });
86
133
  await next();
87
134
  if (c.error && opts.failureStore) {
88
135
  await recordFailure(opts.failureStore, {
package/dist/router.d.ts CHANGED
@@ -3,10 +3,11 @@ export interface SchemeHandle {
3
3
  verify(payload: unknown, requirements: PaymentRequirements): Promise<VerifyResult>;
4
4
  settle(payload: unknown, requirements: PaymentRequirements): Promise<SettleResult>;
5
5
  }
6
+ export type DynamicFlag = boolean | (() => boolean);
6
7
  export interface RouterFlags {
7
- gateway?: boolean;
8
- exact?: boolean;
9
- arc?: boolean;
8
+ gateway?: DynamicFlag;
9
+ exact?: DynamicFlag;
10
+ arc?: DynamicFlag;
10
11
  }
11
12
  export interface RouterConfig extends RouterFlags {
12
13
  sellerAddress: string;
package/dist/router.js CHANGED
@@ -2,11 +2,16 @@ import { ARC_TESTNET, BASE_SEPOLIA, } from "./chains.js";
2
2
  import { buildGatewayRequirements } from "./schemes/gateway.js";
3
3
  import { buildExactRequirements } from "./schemes/exact.js";
4
4
  import { ARC_SELF_SETTLE_SCHEME, buildArcSelfSettleRequirements, } from "./schemes/arc-self-settle.js";
5
+ function flagOn(flag) {
6
+ if (flag === undefined)
7
+ return true;
8
+ return typeof flag === "function" ? flag() !== false : flag !== false;
9
+ }
5
10
  export function buildAccepts(amount, config) {
6
11
  const accepts = [];
7
- const gatewayOn = config.gateway !== false;
8
- const exactOn = config.exact !== false;
9
- const arcOn = config.arc !== false;
12
+ const gatewayOn = flagOn(config.gateway);
13
+ const exactOn = flagOn(config.exact);
14
+ const arcOn = flagOn(config.arc);
10
15
  if (gatewayOn) {
11
16
  const chains = config.gatewayChains ?? [BASE_SEPOLIA, ARC_TESTNET];
12
17
  for (const chain of chains) {
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.12",
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",