agentshield-live 1.0.0 → 1.1.0

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.
package/README.md CHANGED
@@ -29,6 +29,27 @@ const out = await shield.call("agentshield_invoice", {
29
29
 
30
30
  `choose` is free. `call` pays the live 402 price, and refuses if that price is above `maxUsdc`.
31
31
 
32
+ ## Cost log
33
+
34
+ ```js
35
+ const shield = createAgentShield({
36
+ maxUsdc: 0.05,
37
+ onPay: (p) => console.log(`[agentshield] ${p.route} ${p.price_usdc} USDC ok=${p.ok} tx=${p.transaction}`),
38
+ });
39
+ ```
40
+
41
+ `onPay` runs after each settled payment with `tool`, `route`, `price_usdc`, `status`, `ok`, `failed`, `transaction`, `network` and `payer`. Silent when not set. An error inside it does not break the call.
42
+
43
+ ## Dry run (CI, no key)
44
+
45
+ ```js
46
+ const shield = createAgentShield({ dryRun: true }); // or AGENTSHIELD_DRY_RUN=1
47
+ await shield.call("agentshield_invoice", { net: "100.00", gross: "119.00", country: "DE" });
48
+ // { dryRun: true, status: 402, charged: false, route: "/invoice", price_usdc: 0.03, would_pay: true, ... }
49
+ ```
50
+
51
+ A dry run sends only the unpaid request. It returns the live price from the 402, or the free 404 for missing or unknown input. It never pays and never returns a check result.
52
+
32
53
  OpenClaw: `openclaw skills install @bartelmost/agentshield-verify`
33
54
 
34
55
  Rehearse the payment flow on Base Sepolia: https://agentshield.live/try.md
package/agent-kit.mjs CHANGED
@@ -25,10 +25,22 @@ export const tools = [
25
25
  parameters: q({ task: s("One sentence: what you are about to do or look up") }, ["task"]) },
26
26
  ];
27
27
 
28
- export function createAgentShield({ key = process.env.X402_PAYER_KEY, ref = process.env.X402_REF, maxUsdc = 0.1 } = {}) {
29
- if (!key) throw new Error("Set X402_PAYER_KEY. The key is yours; it never leaves your machine.");
30
- const account = privateKeyToAccount(key.startsWith("0x") ? key : `0x${key}`);
31
- const paidFetch = wrapFetchWithPayment(globalThis.fetch, new x402Client().register("eip155:8453", new ExactEvmScheme(account)));
28
+ // Options:
29
+ // maxUsdc hard per-call cap. A call above it is not made.
30
+ // onPay optional callback after each paid call: { tool, route, price_usdc, status, ok, failed, transaction, network, payer }.
31
+ // Silent when not set. Example: onPay: (p) => console.log(`[agentshield] ${p.route} ${p.price_usdc} USDC ${p.transaction}`)
32
+ // dryRun no payment and no key needed. Each call sends the unpaid request and returns the live price from the 402
33
+ // ({ dryRun: true, would_pay, price_usdc, ... }) or the free 404. It never returns a made-up check result.
34
+ // Also on with env AGENTSHIELD_DRY_RUN=1, for CI. A real check needs a real payment; rehearse on Base Sepolia at /try.md.
35
+ export function createAgentShield({ key = process.env.X402_PAYER_KEY, ref = process.env.X402_REF, maxUsdc = 0.1, onPay = null,
36
+ dryRun = process.env.AGENTSHIELD_DRY_RUN === "1" } = {}) {
37
+ let paidFetch = null;
38
+ if (!dryRun) {
39
+ if (!key) throw new Error("Set X402_PAYER_KEY, or pass dryRun: true. The key is yours; it never leaves your machine.");
40
+ const account = privateKeyToAccount(key.startsWith("0x") ? key : `0x${key}`);
41
+ paidFetch = wrapFetchWithPayment(globalThis.fetch, new x402Client().register("eip155:8453", new ExactEvmScheme(account)));
42
+ }
43
+ const decode = (h) => { try { return h ? JSON.parse(Buffer.from(h, "base64").toString()) : null; } catch { return null; } };
32
44
 
33
45
  async function choose(task) {
34
46
  const r = await fetch(`${BASE}/mcp`, { method: "POST", headers: { "content-type": "application/json" },
@@ -44,18 +56,29 @@ export function createAgentShield({ key = process.env.X402_PAYER_KEY, ref = proc
44
56
  const clean = {};
45
57
  for (const [k, v] of Object.entries(args)) if (v !== undefined && v !== "") clean[k] = String(v);
46
58
  // The five bundles take a JSON body (POST), so IBANs and names never appear in a URL.
47
- const init = { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(clean) };
48
- const probe = await fetch(url, init);
49
- if (probe.status === 402) {
50
- const hdr = probe.headers.get("payment-required");
51
- const price = hdr ? Number(JSON.parse(Buffer.from(hdr, "base64").toString()).accepts[0].amount) / 1e6 : null;
52
- if (price !== null && price > maxUsdc) return { error: `price ${price} USDC exceeds maxUsdc ${maxUsdc}` };
53
- }
54
59
  const headers = { accept: "application/json", "content-type": "application/json" };
55
60
  if (ref) headers["x-agent-ref"] = ref;
56
- const res = await paidFetch(url, { method: "POST", headers, body: init.body });
57
- return { status: res.status, ...(await res.json().catch(() => ({}))) };
61
+ const body = JSON.stringify(clean);
62
+ const probe = await fetch(url, { method: "POST", headers, body });
63
+ // Not 402: a free 404 (unknown input, not charged, do not retry) or an error. Nothing was paid.
64
+ if (probe.status !== 402) return { status: probe.status, charged: false, ...(await probe.json().catch(() => ({}))) };
65
+ const req = decode(probe.headers.get("payment-required"));
66
+ const accept = req?.accepts?.[0];
67
+ const price = accept ? Number(accept.amount) / 1e6 : null;
68
+ if (dryRun) return { dryRun: true, status: 402, charged: false, route: tool.route, price_usdc: price, network: accept?.network ?? null,
69
+ would_pay: price !== null && price <= maxUsdc, note: "Dry run: price from the live 402. No payment, no check result." };
70
+ if (price === null || price > maxUsdc) return { error: `price ${price} USDC exceeds maxUsdc ${maxUsdc}`, charged: false };
71
+ const res = await paidFetch(url, { method: "POST", headers, body });
72
+ const out = { status: res.status, ...(await res.json().catch(() => ({}))) };
73
+ const settle = decode(res.headers.get("payment-response"));
74
+ if (onPay && settle) {
75
+ try {
76
+ await onPay({ tool: name, route: tool.route, price_usdc: price, status: res.status, ok: out.ok ?? null, failed: out.failed ?? [],
77
+ transaction: settle.transaction ?? null, network: settle.network ?? accept.network, payer: settle.payer ?? null });
78
+ } catch { /* a logging hook must not break the call */ }
79
+ }
80
+ return out;
58
81
  }
59
82
 
60
- return { tools, choose, call };
83
+ return { tools, choose, call, dryRun };
61
84
  }
package/package.json CHANGED
@@ -1,21 +1,37 @@
1
1
  {
2
2
  "name": "agentshield-live",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Verify before you act. Tool definitions and a paying caller for agentshield.live checks (x402, USDC on Base).",
5
5
  "type": "module",
6
6
  "main": "./agent-kit.mjs",
7
7
  "exports": {
8
8
  ".": "./agent-kit.mjs"
9
9
  },
10
- "files": ["agent-kit.mjs", "tools.json", "README.md", "LICENSE"],
10
+ "files": [
11
+ "agent-kit.mjs",
12
+ "tools.json",
13
+ "README.md",
14
+ "LICENSE"
15
+ ],
11
16
  "license": "MIT",
12
17
  "homepage": "https://agentshield.live/integrate.md",
13
18
  "repository": {
14
19
  "type": "git",
15
20
  "url": "git+https://github.com/bartelmost/agentshield-agent-kit.git"
16
21
  },
17
- "keywords": ["agentshield", "x402", "ai-agents", "mcp", "invoice", "iban", "usdc", "base"],
18
- "engines": { "node": ">=20" },
22
+ "keywords": [
23
+ "agentshield",
24
+ "x402",
25
+ "ai-agents",
26
+ "mcp",
27
+ "invoice",
28
+ "iban",
29
+ "usdc",
30
+ "base"
31
+ ],
32
+ "engines": {
33
+ "node": ">=20"
34
+ },
19
35
  "dependencies": {
20
36
  "@x402/evm": "^2.28.0",
21
37
  "@x402/fetch": "^2.28.0",
package/tools.json CHANGED
@@ -43,7 +43,7 @@
43
43
  },
44
44
  {
45
45
  "name": "agentshield_invoice",
46
- "description": "Check an invoice before sending or paying: net + VAT = gross, VAT rate, IBAN, VAT id, date, number. Optional registry=1 asks EU VIES. Returns ok and failed fields.",
46
+ "description": "Call before you send or pay an invoice: net + VAT equals gross, VAT matches the stated or standard rate, plus IBAN and VAT-id format. Returns ok and failed fields. Not a receipt photo; that is /lines.",
47
47
  "parameters": {
48
48
  "type": "object",
49
49
  "properties": {
@@ -134,7 +134,7 @@
134
134
  },
135
135
  {
136
136
  "name": "agentshield_holidays",
137
- "description": "All statutory public holidays of a year for a country, optionally one region.",
137
+ "description": "Call for the full statutory holiday calendar of a year and country or region, such as FR 2026 or DE-BY. A single date is /holiday. Adding business days is /deadline.",
138
138
  "parameters": {
139
139
  "type": "object",
140
140
  "properties": {
@@ -161,7 +161,7 @@
161
161
  },
162
162
  {
163
163
  "name": "agentshield_cryptopay",
164
- "description": "Check an EVM stablecoin transfer: recipient checksum, token contract on that chain.",
164
+ "description": "Call before sending USDC or USDT: checksum the recipient, reject the zero address and a token-contract recipient, confirm the native token contract. Not a balance or sanctions screen.",
165
165
  "parameters": {
166
166
  "type": "object",
167
167
  "properties": {