@purseragents/cli 0.0.0-stage → 0.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/LICENSE +21 -0
- package/README.md +12 -2
- package/dist/index.js +233 -0
- package/package.json +17 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Purser
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,13 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @purseragents/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The `purser` command. Run `purser --help` for every command.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
export PURSER_ENGINE_URL=http://localhost:8787 PURSER_API_KEY=prs_...
|
|
7
|
+
purser account
|
|
8
|
+
purser pay 0xPAYEE 2.50 --memo "data report"
|
|
9
|
+
purser check 0xPAYEE 100 --context "text that led to the payment"
|
|
10
|
+
purser receipts
|
|
11
|
+
purser audit export > audit.jsonl && purser audit verify audit.jsonl
|
|
12
|
+
purser testmode --fork # from a Purser checkout: local node + Purser + engine in one command
|
|
13
|
+
```
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* purser: the command line for Purser.
|
|
4
|
+
*
|
|
5
|
+
* purser health
|
|
6
|
+
* purser me (needs PURSER_API_KEY)
|
|
7
|
+
* purser account [safe] balances, today's spending, rules
|
|
8
|
+
* purser accounts [--owner 0x...]
|
|
9
|
+
* purser pay <to> <amount> [--token ETH] [--memo text] [--service id] [--context text]
|
|
10
|
+
* purser check <to> <amount> [--context text]
|
|
11
|
+
* purser receipts [safe] [--limit 20] [--direction in|out]
|
|
12
|
+
* purser verdicts [safe] [--blocked]
|
|
13
|
+
* purser approvals [safe]
|
|
14
|
+
* purser pnl [safe]
|
|
15
|
+
* purser export [safe] > receipts.csv
|
|
16
|
+
* purser templates
|
|
17
|
+
* purser audit export > audit.jsonl
|
|
18
|
+
* purser audit verify <file> [--signer 0x...]
|
|
19
|
+
* purser demo firewall [--pace 1500] (engine in test mode)
|
|
20
|
+
* purser testmode [--fork] [--port 8787] (from a Purser checkout: starts a local node, Purser and the engine)
|
|
21
|
+
*
|
|
22
|
+
* Settings: --engine <url> or PURSER_ENGINE_URL (default http://localhost:8787), --key or PURSER_API_KEY,
|
|
23
|
+
* --owner-token or PURSER_OWNER_TOKEN. Amounts are whole units ("2.50"), not base units.
|
|
24
|
+
*/
|
|
25
|
+
import { spawn } from "node:child_process";
|
|
26
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
27
|
+
import { dirname, resolve } from "node:path";
|
|
28
|
+
import { fileURLToPath } from "node:url";
|
|
29
|
+
import { parseArgs } from "node:util";
|
|
30
|
+
import { Purser, PurserError } from "@purseragents/sdk";
|
|
31
|
+
import { formatUnits, parseUnits } from "viem";
|
|
32
|
+
const { values: flags, positionals } = parseArgs({
|
|
33
|
+
allowPositionals: true,
|
|
34
|
+
options: {
|
|
35
|
+
engine: { type: "string" },
|
|
36
|
+
key: { type: "string" },
|
|
37
|
+
"owner-token": { type: "string" },
|
|
38
|
+
token: { type: "string", default: "USDG" },
|
|
39
|
+
memo: { type: "string" },
|
|
40
|
+
service: { type: "string" },
|
|
41
|
+
context: { type: "string" },
|
|
42
|
+
limit: { type: "string" },
|
|
43
|
+
direction: { type: "string" },
|
|
44
|
+
owner: { type: "string" },
|
|
45
|
+
signer: { type: "string" },
|
|
46
|
+
pace: { type: "string" },
|
|
47
|
+
port: { type: "string" },
|
|
48
|
+
fork: { type: "boolean" },
|
|
49
|
+
blocked: { type: "boolean" },
|
|
50
|
+
json: { type: "boolean" },
|
|
51
|
+
help: { type: "boolean", short: "h" },
|
|
52
|
+
},
|
|
53
|
+
});
|
|
54
|
+
const purser = new Purser({
|
|
55
|
+
baseUrl: flags.engine ?? process.env.PURSER_ENGINE_URL ?? "http://localhost:8787",
|
|
56
|
+
apiKey: flags.key ?? process.env.PURSER_API_KEY,
|
|
57
|
+
ownerToken: flags["owner-token"] ?? process.env.PURSER_OWNER_TOKEN,
|
|
58
|
+
});
|
|
59
|
+
const out = (s) => {
|
|
60
|
+
process.stdout.write(s.endsWith("\n") ? s : `${s}\n`);
|
|
61
|
+
};
|
|
62
|
+
const asJson = (v) => out(JSON.stringify(v, null, 2));
|
|
63
|
+
const date = (t) => new Date(t * 1000).toISOString().replace("T", " ").slice(0, 16);
|
|
64
|
+
async function safeArg(i) {
|
|
65
|
+
return positionals[i] ?? (await purser.me()).safe;
|
|
66
|
+
}
|
|
67
|
+
async function tokenOf(symbol) {
|
|
68
|
+
const cfg = await purser.config();
|
|
69
|
+
const t = cfg.tokens.find((x) => x.symbol.toUpperCase() === symbol.toUpperCase());
|
|
70
|
+
if (!t)
|
|
71
|
+
throw new Error(`unknown token ${symbol}`);
|
|
72
|
+
return t;
|
|
73
|
+
}
|
|
74
|
+
function showVerdict(v) {
|
|
75
|
+
out(v.summary);
|
|
76
|
+
for (const r of v.reasons)
|
|
77
|
+
if (r.severity !== "info")
|
|
78
|
+
out(` ${r.severity === "block" ? "x" : "!"} ${r.title}: ${r.detail}`);
|
|
79
|
+
}
|
|
80
|
+
function showPay(r) {
|
|
81
|
+
out(`${r.intent.status.toUpperCase()} ${r.intent.summary}`);
|
|
82
|
+
if (r.intent.txHash)
|
|
83
|
+
out(` transaction ${r.intent.txHash}`);
|
|
84
|
+
if (r.receipt)
|
|
85
|
+
out(` receipt ${r.receipt.id}${r.receipt.fee ? `, fee ${r.receipt.fee.display}` : ""}`);
|
|
86
|
+
if (r.intent.status !== "executed")
|
|
87
|
+
showVerdict(r.verdict);
|
|
88
|
+
}
|
|
89
|
+
const commands = {
|
|
90
|
+
async health() {
|
|
91
|
+
const h = await purser.health();
|
|
92
|
+
flags.json ? asJson(h) : out(`${h.ok ? "OK" : "DOWN"} chain ${h.chainId}, block ${h.block}, mode ${h.mode}, broadcast ${h.broadcast ? "local node only" : "off"}`);
|
|
93
|
+
},
|
|
94
|
+
async me() {
|
|
95
|
+
const m = await purser.me();
|
|
96
|
+
flags.json ? asJson(m) : out(`account ${m.safe}\nkey ${m.key.prefix}... scopes ${m.key.scopes.join(", ")}\nsession key ${m.sessionAddress ?? "kept by the agent"}`);
|
|
97
|
+
},
|
|
98
|
+
async account() {
|
|
99
|
+
const a = await purser.accounts.get(await safeArg(1));
|
|
100
|
+
if (flags.json)
|
|
101
|
+
return asJson(a);
|
|
102
|
+
out(`${a.name} ${a.safe}${a.frozen ? " FROZEN" : ""}`);
|
|
103
|
+
out(`owners ${a.owners.join(", ")} (threshold ${a.threshold}), agent key ${a.config.agent}`);
|
|
104
|
+
for (const b of a.balances)
|
|
105
|
+
out(`balance ${b.display}`);
|
|
106
|
+
for (const s of a.spentToday)
|
|
107
|
+
out(`spent today ${s.display}${s.remaining !== null ? `, left ${formatUnits(BigInt(s.remaining), s.token.decimals)} ${s.token.symbol}` : ""}`);
|
|
108
|
+
out(`firewall ${a.config.firewall ? "on" : "off"}, watchdog ${a.config.watchdog ? "on" : "off"}, pending approvals ${a.pendingApprovals}`);
|
|
109
|
+
},
|
|
110
|
+
async accounts() {
|
|
111
|
+
const r = await purser.accounts.list(flags.owner);
|
|
112
|
+
if (flags.json)
|
|
113
|
+
return asJson(r);
|
|
114
|
+
for (const a of r.items)
|
|
115
|
+
out(`${a.safe} ${a.name.padEnd(28)} spent today $${a.spentTodayUsd.padStart(8)} earned $${a.earnedTodayUsd.padStart(8)}${a.frozen ? " FROZEN" : ""}`);
|
|
116
|
+
},
|
|
117
|
+
async pay() {
|
|
118
|
+
const [, to, amount] = positionals;
|
|
119
|
+
if (!to || !amount)
|
|
120
|
+
throw new Error("usage: purser pay <to> <amount>");
|
|
121
|
+
const t = await tokenOf(flags.token);
|
|
122
|
+
const r = await purser.pay({ to, amount: parseUnits(amount, t.decimals), token: t.address, memo: flags.memo, service: flags.service, trigger: flags.context });
|
|
123
|
+
flags.json ? asJson(r) : showPay(r);
|
|
124
|
+
if (r.intent.status === "blocked")
|
|
125
|
+
process.exitCode = 3;
|
|
126
|
+
},
|
|
127
|
+
async check() {
|
|
128
|
+
const [, to, amount] = positionals;
|
|
129
|
+
if (!to || !amount)
|
|
130
|
+
throw new Error("usage: purser check <to> <amount>");
|
|
131
|
+
const t = await tokenOf(flags.token);
|
|
132
|
+
const v = await purser.checkPayment({ to, amount: parseUnits(amount, t.decimals), token: t.address, service: flags.service, trigger: flags.context });
|
|
133
|
+
flags.json ? asJson(v) : showVerdict(v);
|
|
134
|
+
if (v.decision === "block")
|
|
135
|
+
process.exitCode = 3;
|
|
136
|
+
},
|
|
137
|
+
async receipts() {
|
|
138
|
+
const r = await purser.accounts.receipts(await safeArg(1), { limit: flags.limit ? Number(flags.limit) : 20, direction: flags.direction });
|
|
139
|
+
if (flags.json)
|
|
140
|
+
return asJson(r);
|
|
141
|
+
for (const x of r.items)
|
|
142
|
+
out(`${date(x.createdAt)} ${x.direction === "in" ? "+" : "-"}${x.money.display.padEnd(16)} ${x.category.padEnd(12)} ${(x.counterpartyName ?? x.counterparty).slice(0, 42).padEnd(42)} ${x.memo ?? ""}`);
|
|
143
|
+
},
|
|
144
|
+
async verdicts() {
|
|
145
|
+
const r = await purser.accounts.verdicts(await safeArg(1), { decision: flags.blocked ? "block" : undefined, limit: flags.limit ? Number(flags.limit) : 20 });
|
|
146
|
+
if (flags.json)
|
|
147
|
+
return asJson(r);
|
|
148
|
+
for (const v of r.items)
|
|
149
|
+
out(`${date(v.createdAt)} ${v.decision.toUpperCase().padEnd(5)} ${v.summary}`);
|
|
150
|
+
},
|
|
151
|
+
async approvals() {
|
|
152
|
+
const r = await purser.accounts.approvals(await safeArg(1));
|
|
153
|
+
if (flags.json)
|
|
154
|
+
return asJson(r);
|
|
155
|
+
if (!r.items.length)
|
|
156
|
+
out("Nothing waits for approval.");
|
|
157
|
+
for (const a of r.items)
|
|
158
|
+
out(`${a.id} ${a.summary} digest ${a.digest}`);
|
|
159
|
+
},
|
|
160
|
+
async pnl() {
|
|
161
|
+
const p = await purser.accounts.pnl(await safeArg(1));
|
|
162
|
+
if (flags.json)
|
|
163
|
+
return asJson(p);
|
|
164
|
+
out(`income $${p.incomeUsd} spend $${p.spendUsd} fees $${p.feesUsd} profit $${p.profitUsd} (last 30 days)`);
|
|
165
|
+
for (const l of p.byModel.slice(0, 5))
|
|
166
|
+
out(` model ${l.label}: $${l.spend}`);
|
|
167
|
+
for (const l of p.byCustomer.slice(0, 5))
|
|
168
|
+
out(` customer ${l.label}: $${l.income}`);
|
|
169
|
+
},
|
|
170
|
+
async export() {
|
|
171
|
+
out(await purser.accounts.exportCsv(await safeArg(1)));
|
|
172
|
+
},
|
|
173
|
+
async templates() {
|
|
174
|
+
const t = await purser.templates();
|
|
175
|
+
if (flags.json)
|
|
176
|
+
return asJson(t);
|
|
177
|
+
for (const x of t.items)
|
|
178
|
+
out(`${x.id.padEnd(10)} ${x.name.padEnd(22)} ${x.highlights.join(", ")}`);
|
|
179
|
+
},
|
|
180
|
+
async audit() {
|
|
181
|
+
const sub = positionals[1];
|
|
182
|
+
if (sub === "export")
|
|
183
|
+
return out(await purser.audit.export());
|
|
184
|
+
if (sub === "verify") {
|
|
185
|
+
const file = positionals[2];
|
|
186
|
+
if (!file)
|
|
187
|
+
throw new Error("usage: purser audit verify <file> [--signer 0x...]");
|
|
188
|
+
const r = await purser.audit.verify(readFileSync(file, "utf8"), flags.signer);
|
|
189
|
+
out(r.ok ? `OK: ${r.entries} entries, hash chain intact, all signed by ${r.signer}.` : `FAILED at entry ${r.brokenAt}: ${r.problem}.`);
|
|
190
|
+
if (!r.ok)
|
|
191
|
+
process.exitCode = 1;
|
|
192
|
+
return;
|
|
193
|
+
}
|
|
194
|
+
const r = await purser.audit.list({ limit: flags.limit ? Number(flags.limit) : 20 });
|
|
195
|
+
for (const e of r.items)
|
|
196
|
+
out(`${e.seq} ${date(e.ts)} ${e.actor.padEnd(28)} ${e.action}`);
|
|
197
|
+
},
|
|
198
|
+
async demo() {
|
|
199
|
+
if (positionals[1] !== "firewall")
|
|
200
|
+
throw new Error("usage: purser demo firewall [--pace ms]");
|
|
201
|
+
const r = await purser.demo.runFirewall(flags.pace ? Number(flags.pace) : 0);
|
|
202
|
+
if (flags.json)
|
|
203
|
+
return asJson(r);
|
|
204
|
+
for (const s of r.steps)
|
|
205
|
+
out(`${s.step}. ${s.title} [${s.status.toUpperCase()}]\n ${s.detail}`);
|
|
206
|
+
},
|
|
207
|
+
async testmode() {
|
|
208
|
+
const here = dirname(fileURLToPath(import.meta.url));
|
|
209
|
+
const engine = [resolve(here, "../../../engine"), resolve(process.cwd(), "engine")].find((p) => existsSync(resolve(p, "scripts/testmode.ts")));
|
|
210
|
+
if (!engine)
|
|
211
|
+
throw new Error("Run this from a Purser checkout (it starts engine/scripts/testmode.ts).");
|
|
212
|
+
const args = ["tsx", "scripts/testmode.ts", ...(flags.fork ? ["--fork"] : []), ...(flags.port ? ["--port", flags.port] : [])];
|
|
213
|
+
const child = spawn("npx", args, { cwd: engine, stdio: "inherit" });
|
|
214
|
+
await new Promise((r) => child.on("exit", r));
|
|
215
|
+
},
|
|
216
|
+
};
|
|
217
|
+
async function main() {
|
|
218
|
+
const cmd = positionals[0];
|
|
219
|
+
if (!cmd || flags.help || !commands[cmd]) {
|
|
220
|
+
out(readFileSync(fileURLToPath(import.meta.url), "utf8").split("*/")[0].replace(/^#!.*\n\/\*\*\n/, "").replace(/^ \* ?/gm, ""));
|
|
221
|
+
if (cmd && !commands[cmd])
|
|
222
|
+
process.exitCode = 2;
|
|
223
|
+
return;
|
|
224
|
+
}
|
|
225
|
+
await commands[cmd]();
|
|
226
|
+
}
|
|
227
|
+
main().catch((e) => {
|
|
228
|
+
if (e instanceof PurserError)
|
|
229
|
+
process.stderr.write(`error ${e.status} ${e.code}: ${e.message}\n`);
|
|
230
|
+
else
|
|
231
|
+
process.stderr.write(`error: ${e.message}\n`);
|
|
232
|
+
process.exitCode = 1;
|
|
233
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,19 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@purseragents/cli",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "The purser command: accounts, payments, receipts, firewall checks, audit export and verify, test mode.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"purser": "dist/index.js"
|
|
9
|
+
},
|
|
10
|
+
"main": "./dist/index.js",
|
|
11
|
+
"files": [
|
|
12
|
+
"dist",
|
|
13
|
+
"README.md"
|
|
14
|
+
],
|
|
15
|
+
"dependencies": {
|
|
16
|
+
"@purseragents/sdk": "^0.1.0",
|
|
17
|
+
"viem": "2.57.18"
|
|
18
|
+
}
|
|
19
|
+
}
|