@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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +12 -2
  3. package/dist/index.js +233 -0
  4. 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
- # Temporary Holding Version
1
+ # @purseragents/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }