@conto_finance/create-conto-agent 0.3.0 → 0.4.2

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.
@@ -8,16 +8,17 @@ import {
8
8
  printWarning
9
9
  } from "./chunk-K4LBO234.js";
10
10
  import {
11
+ ensureEnvLocalGitignored,
11
12
  saveGlobalConfig,
12
13
  writeContoConfig,
13
14
  writeEnvLocal
14
- } from "./chunk-OS5PZNRM.js";
15
+ } from "./chunk-2U2MPMMD.js";
15
16
 
16
17
  // package.json
17
18
  var package_default = {
18
19
  name: "@conto_finance/create-conto-agent",
19
- version: "0.3.0",
20
- description: "CLI quickstart for Conto \u2014 Agentic Payments Control Center",
20
+ version: "0.4.2",
21
+ description: "Set up an AI agent with Conto spending controls",
21
22
  bin: {
22
23
  "create-conto-agent": "bin/create-conto-agent.js",
23
24
  conto: "bin/conto.js"
@@ -26,16 +27,24 @@ var package_default = {
26
27
  type: "module",
27
28
  files: [
28
29
  "dist",
29
- "bin"
30
+ "bin",
31
+ "README.md",
32
+ "CHANGELOG.md"
30
33
  ],
34
+ publishConfig: {
35
+ access: "public"
36
+ },
31
37
  scripts: {
32
- build: "tsup src/index.ts src/cli.ts --format esm --dts --clean",
33
- dev: "tsup src/index.ts src/cli.ts --format esm --dts --watch",
38
+ build: "tsup src/index.ts src/cli.ts src/lib/rule-values.ts --format esm --dts --clean",
39
+ dev: "tsup src/index.ts src/cli.ts src/lib/rule-values.ts --format esm --dts --watch",
34
40
  lint: "tsc --noEmit",
35
- test: "npm run build && node --test test/*.test.mjs"
41
+ test: "npm run lint && npm run test:contract",
42
+ "test:contract": "npm run build && node --test test/*.test.mjs",
43
+ "verify:release": "node scripts/verify-release.mjs",
44
+ prepublishOnly: "npm run verify:release && npm test"
36
45
  },
37
46
  engines: {
38
- node: ">=18"
47
+ node: ">=20.19.0"
39
48
  },
40
49
  keywords: [
41
50
  "conto",
@@ -51,12 +60,12 @@ var package_default = {
51
60
  license: "MIT",
52
61
  repository: {
53
62
  type: "git",
54
- url: "https://github.com/kwattana/conto.git",
63
+ url: "https://github.com/conto-finance/conto.git",
55
64
  directory: "packages/cli"
56
65
  },
57
- homepage: "https://conto.finance",
66
+ homepage: "https://conto.finance/docs/cli/quickstart",
58
67
  bugs: {
59
- url: "https://github.com/kwattana/conto/issues"
68
+ email: "support@conto.finance"
60
69
  },
61
70
  dependencies: {
62
71
  "@clack/prompts": "^0.9.1",
@@ -69,7 +78,7 @@ var package_default = {
69
78
  esbuild: "0.28.1"
70
79
  },
71
80
  devDependencies: {
72
- "@types/node": "^22.19.18",
81
+ "@types/node": "22.19.18",
73
82
  tsup: "^8.5.1",
74
83
  typescript: "^5.9.3"
75
84
  }
@@ -96,7 +105,6 @@ var FALLBACK_CHAINS = {
96
105
  explorerName: "Tempo Explorer",
97
106
  currency: "USDC.e",
98
107
  chainType: "EVM",
99
- spongeChainId: "tempo-mainnet",
100
108
  testnet: false,
101
109
  isDefault: false,
102
110
  faucetAvailable: false,
@@ -118,7 +126,6 @@ var FALLBACK_CHAINS = {
118
126
  explorerName: "Tempo Explorer",
119
127
  currency: "pathUSD",
120
128
  chainType: "EVM",
121
- spongeChainId: "tempo",
122
129
  testnet: true,
123
130
  isDefault: true,
124
131
  faucetAvailable: true,
@@ -132,9 +139,17 @@ var FALLBACK_CHAINS = {
132
139
  ]
133
140
  }
134
141
  };
135
- var DEFAULT_FALLBACK_CHAIN_ID = "4217";
142
+ var DEFAULT_EVALUATION_CHAIN_ID = "42431";
143
+ var DEFAULT_FALLBACK_CHAIN_ID = DEFAULT_EVALUATION_CHAIN_ID;
136
144
  var cachedChains = null;
137
145
  var cachedDefaultChainId = null;
146
+ function getEvaluationDefaultChainId(chains, serverDefaultChainId) {
147
+ if (chains[DEFAULT_EVALUATION_CHAIN_ID]?.testnet) return DEFAULT_EVALUATION_CHAIN_ID;
148
+ if (serverDefaultChainId && chains[serverDefaultChainId]?.testnet) return serverDefaultChainId;
149
+ const firstTestnet = Object.values(chains).find((chain) => chain.testnet);
150
+ if (firstTestnet) return firstTestnet.chainId;
151
+ return serverDefaultChainId && chains[serverDefaultChainId] ? serverDefaultChainId : Object.keys(chains)[0];
152
+ }
138
153
  async function fetchChains(baseUrl) {
139
154
  if (cachedChains) {
140
155
  return { chains: cachedChains, defaultChainId: cachedDefaultChainId };
@@ -156,7 +171,6 @@ async function fetchChains(baseUrl) {
156
171
  explorerName: c.explorerName,
157
172
  currency: c.currency,
158
173
  chainType: c.type,
159
- spongeChainId: c.spongeChainId,
160
174
  testnet: c.isTestnet,
161
175
  isDefault: c.isDefault,
162
176
  faucetAvailable: c.faucetAvailable,
@@ -165,8 +179,8 @@ async function fetchChains(baseUrl) {
165
179
  };
166
180
  }
167
181
  cachedChains = chains;
168
- cachedDefaultChainId = data.defaultChainId;
169
- return { chains, defaultChainId: data.defaultChainId };
182
+ cachedDefaultChainId = getEvaluationDefaultChainId(chains, data.defaultChainId);
183
+ return { chains, defaultChainId: cachedDefaultChainId };
170
184
  } catch {
171
185
  cachedChains = FALLBACK_CHAINS;
172
186
  cachedDefaultChainId = DEFAULT_FALLBACK_CHAIN_ID;
@@ -179,33 +193,44 @@ function getChain(chainId) {
179
193
  function getChainChoices(chains) {
180
194
  const entries = Object.entries(chains);
181
195
  entries.sort(([, a], [, b]) => {
182
- if (a.chainId === "4217") return -1;
183
- if (b.chainId === "4217") return 1;
184
- if (!a.testnet && b.testnet) return -1;
185
- if (a.testnet && !b.testnet) return 1;
186
- if (a.chainId === "42431") return -1;
187
- if (b.chainId === "42431") return 1;
196
+ if (a.chainId === DEFAULT_EVALUATION_CHAIN_ID) return -1;
197
+ if (b.chainId === DEFAULT_EVALUATION_CHAIN_ID) return 1;
198
+ if (a.testnet && !b.testnet) return -1;
199
+ if (!a.testnet && b.testnet) return 1;
188
200
  return a.name.localeCompare(b.name);
189
201
  });
190
- return entries.map(([id, chain], i) => ({
202
+ return entries.map(([id, chain]) => ({
191
203
  value: id,
192
- label: i === 0 ? `${chain.name} (recommended)` : chain.name,
204
+ label: chain.chainId === DEFAULT_EVALUATION_CHAIN_ID ? `${chain.name} (recommended for evaluation)` : chain.name,
193
205
  hint: chainHint(chain)
194
206
  }));
195
207
  }
196
208
  function chainHint(chain) {
197
- if (chain.chainId === "4217") return "Stablecoin-native, fast, low fees";
198
209
  if (chain.testnet) return `Testnet \u2014 free ${chain.currency}, no real funds`;
210
+ if (chain.chainId === "4217") return "Mainnet \u2014 real USDC.e and real settlement";
199
211
  return `${chain.chainType} \u2014 ${chain.currency}`;
200
212
  }
201
213
 
202
214
  // src/lib/api-client.ts
215
+ var REQUEST_TIMEOUT_MS = 3e4;
216
+ function assertSecureBaseUrl(baseUrl) {
217
+ let parsed;
218
+ try {
219
+ parsed = new URL(baseUrl);
220
+ } catch {
221
+ throw new Error(`Invalid base URL: ${baseUrl}`);
222
+ }
223
+ if (parsed.protocol !== "https:" && parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1") {
224
+ throw new Error("baseUrl must use https (except for localhost)");
225
+ }
226
+ }
203
227
  var ApiClient = class {
204
228
  baseUrl;
205
229
  apiKey;
206
230
  orgApiKey;
207
231
  constructor(options) {
208
232
  this.baseUrl = options.baseUrl.replace(/\/$/, "");
233
+ assertSecureBaseUrl(this.baseUrl);
209
234
  this.apiKey = options.apiKey;
210
235
  this.orgApiKey = options.orgApiKey;
211
236
  }
@@ -220,28 +245,45 @@ var ApiClient = class {
220
245
  if (token) {
221
246
  headers["Authorization"] = `Bearer ${token}`;
222
247
  }
223
- const response = await fetch(url, {
224
- method,
225
- headers,
226
- body: options?.body ? JSON.stringify(options.body) : void 0
227
- });
228
- const contentType = response.headers.get("content-type") || "";
229
- if (!contentType.includes("application/json")) {
230
- const error = new Error(
231
- response.status === 404 ? `API endpoint not found: ${path2}` : `API returned non-JSON response (${response.status})`
232
- );
233
- error.code = response.status === 404 ? "NOT_FOUND" : "INVALID_RESPONSE";
234
- error.status = response.status;
235
- throw error;
236
- }
237
- const data = await response.json();
238
- if (!response.ok) {
239
- const error = new Error(data.error || `API request failed: ${response.status}`);
240
- error.code = data.code || "API_ERROR";
241
- error.status = response.status;
242
- throw error;
248
+ const controller = new AbortController();
249
+ const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
250
+ try {
251
+ const response = await fetch(url, {
252
+ method,
253
+ headers,
254
+ body: options?.body ? JSON.stringify(options.body) : void 0,
255
+ signal: controller.signal
256
+ });
257
+ const contentType = response.headers.get("content-type") || "";
258
+ if (!contentType.includes("application/json")) {
259
+ const error = new Error(
260
+ response.status === 404 ? `API endpoint not found: ${path2}` : `API returned non-JSON response (${response.status})`
261
+ );
262
+ error.code = response.status === 404 ? "NOT_FOUND" : "INVALID_RESPONSE";
263
+ error.status = response.status;
264
+ throw error;
265
+ }
266
+ const data = await response.json();
267
+ if (!response.ok) {
268
+ const error = new Error(data.error || `API request failed: ${response.status}`);
269
+ error.code = data.code || "API_ERROR";
270
+ error.status = response.status;
271
+ throw error;
272
+ }
273
+ return data;
274
+ } catch (err) {
275
+ if (err instanceof Error && err.name === "AbortError") {
276
+ const error = new Error(
277
+ `Request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s`
278
+ );
279
+ error.code = "TIMEOUT";
280
+ error.status = 0;
281
+ throw error;
282
+ }
283
+ throw err;
284
+ } finally {
285
+ clearTimeout(timeoutId);
243
286
  }
244
- return data;
245
287
  }
246
288
  // ── Org-level Admin APIs (used during init) ──
247
289
  async createWallet(params) {
@@ -251,7 +293,7 @@ var ApiClient = class {
251
293
  return this.request("POST", "/api/agents", { body: params, auth: "org" });
252
294
  }
253
295
  async linkWalletToAgent(agentId, params) {
254
- return this.request("POST", `/api/agents/${agentId}/wallets`, {
296
+ return this.request("POST", `/api/agents/${encodeURIComponent(agentId)}/wallets`, {
255
297
  body: params,
256
298
  auth: "org"
257
299
  });
@@ -260,15 +302,15 @@ var ApiClient = class {
260
302
  return this.request("POST", "/api/policies", { body: params, auth: "org" });
261
303
  }
262
304
  async updatePolicy(policyId, params) {
263
- return this.request("PATCH", `/api/policies/${policyId}`, { body: params, auth: "org" });
305
+ return this.request("PATCH", `/api/policies/${encodeURIComponent(policyId)}`, { body: params, auth: "org" });
264
306
  }
265
307
  async deletePolicy(policyId) {
266
- return this.request("DELETE", `/api/policies/${policyId}`, { auth: "org" });
308
+ return this.request("DELETE", `/api/policies/${encodeURIComponent(policyId)}`, { auth: "org" });
267
309
  }
268
310
  async addPolicyRule(policyId, rule) {
269
311
  return this.request(
270
312
  "POST",
271
- `/api/policies/${policyId}/rules`,
313
+ `/api/policies/${encodeURIComponent(policyId)}/rules`,
272
314
  {
273
315
  body: rule,
274
316
  auth: "org"
@@ -276,36 +318,40 @@ var ApiClient = class {
276
318
  );
277
319
  }
278
320
  async deletePolicyRule(policyId, ruleId) {
279
- return this.request("DELETE", `/api/policies/${policyId}/rules/${ruleId}`, { auth: "org" });
321
+ return this.request(
322
+ "DELETE",
323
+ `/api/policies/${encodeURIComponent(policyId)}/rules/${encodeURIComponent(ruleId)}`,
324
+ { auth: "org" }
325
+ );
280
326
  }
281
327
  async listOrgPolicies() {
282
328
  return this.request("GET", "/api/policies", { auth: "org" });
283
329
  }
284
330
  async assignPolicyToAgent(agentId, policyId) {
285
- return this.request("POST", `/api/agents/${agentId}/policies`, {
331
+ return this.request("POST", `/api/agents/${encodeURIComponent(agentId)}/policies`, {
286
332
  body: { policyId },
287
333
  auth: "org"
288
334
  });
289
335
  }
290
336
  async unassignPolicyFromAgent(agentId, policyId) {
291
- return this.request("DELETE", `/api/agents/${agentId}/policies?policyId=${policyId}`, {
292
- auth: "org"
293
- });
337
+ return this.request(
338
+ "DELETE",
339
+ `/api/agents/${encodeURIComponent(agentId)}/policies?policyId=${encodeURIComponent(policyId)}`,
340
+ {
341
+ auth: "org"
342
+ }
343
+ );
294
344
  }
295
345
  async createSdkKey(agentId, params) {
296
- return this.request("POST", `/api/agents/${agentId}/sdk-keys`, {
346
+ return this.request("POST", `/api/agents/${encodeURIComponent(agentId)}/sdk-keys`, {
297
347
  body: params,
298
348
  auth: "org"
299
349
  });
300
350
  }
301
351
  async fundWallet(walletId) {
302
- return this.request("POST", `/api/wallets/${walletId}/faucet`, { auth: "org" });
303
- }
304
- async provisionWallet(walletId) {
305
- return this.request("POST", `/api/wallets/${walletId}/provision`, { auth: "org" });
352
+ return this.request("POST", `/api/wallets/${encodeURIComponent(walletId)}/faucet`, { auth: "org" });
306
353
  }
307
354
  // ── SDK Agent APIs (used by CLI commands) ──
308
- /** GET /api/sdk/setup: full diagnostic snapshot for the authenticated key. */
309
355
  async getSetup() {
310
356
  return this.request("GET", "/api/sdk/setup");
311
357
  }
@@ -356,10 +402,10 @@ var ApiClient = class {
356
402
  return this.request("POST", "/api/sdk/payments/request", { body: params });
357
403
  }
358
404
  async executePayment(requestId) {
359
- return this.request("POST", `/api/sdk/payments/${requestId}/execute`, { body: {} });
405
+ return this.request("POST", `/api/sdk/payments/${encodeURIComponent(requestId)}/execute`, { body: {} });
360
406
  }
361
407
  async getPaymentStatus(requestId) {
362
- return this.request("GET", `/api/sdk/payments/${requestId}`);
408
+ return this.request("GET", `/api/sdk/payments/${encodeURIComponent(requestId)}`);
363
409
  }
364
410
  async getTransactions(params) {
365
411
  const query = new URLSearchParams();
@@ -369,7 +415,7 @@ var ApiClient = class {
369
415
  return this.request("GET", `/api/sdk/transactions${qs}`);
370
416
  }
371
417
  async getTransaction(id) {
372
- return this.request("GET", `/api/sdk/transactions/${id}`);
418
+ return this.request("GET", `/api/sdk/transactions/${encodeURIComponent(id)}`);
373
419
  }
374
420
  async getPolicies() {
375
421
  return this.request("GET", "/api/sdk/policies");
@@ -414,14 +460,18 @@ async function readRequestBody(req) {
414
460
  async function parseCallbackPayload(req) {
415
461
  const url = new URL(req.url || "/", "http://127.0.0.1");
416
462
  let params = url.searchParams;
417
- if (req.method === "POST") {
463
+ const isPost = req.method === "POST";
464
+ if (isPost) {
418
465
  const rawBody = await readRequestBody(req);
419
466
  params = new URLSearchParams(rawBody);
420
467
  }
421
468
  return {
422
- orgApiKey: params.get("token"),
469
+ // The org API key is a secret. Accept it only from the POST body so it
470
+ // never transits a GET query string (query strings leak into browser
471
+ // history, proxy logs, and Referer headers). Ignore any ?token= on GET.
472
+ orgApiKey: isPost ? params.get("token") : null,
423
473
  organizationName: params.get("org") || "",
424
- userId: params.get("userId") || "",
474
+ expiresAt: params.get("expiresAt") || "",
425
475
  error: params.get("error"),
426
476
  returnedState: params.get("state")
427
477
  };
@@ -449,7 +499,7 @@ async function browserAuth(baseUrl) {
449
499
  res.end(getErrorHtml("Unsupported callback method"));
450
500
  return;
451
501
  }
452
- const { orgApiKey, organizationName, userId, error, returnedState } = await parseCallbackPayload(req);
502
+ const { orgApiKey, organizationName, expiresAt, error, returnedState } = await parseCallbackPayload(req);
453
503
  if (returnedState !== state) {
454
504
  res.writeHead(400, { "Content-Type": "text/html" });
455
505
  res.end(getErrorHtml("Invalid authentication state"));
@@ -475,7 +525,7 @@ async function browserAuth(baseUrl) {
475
525
  res.end(getSuccessHtml());
476
526
  clearTimeout(timeout);
477
527
  server.close();
478
- resolve({ orgApiKey, organizationName, userId });
528
+ resolve({ orgApiKey, organizationName, expiresAt });
479
529
  })().catch((error) => {
480
530
  res.writeHead(500, { "Content-Type": "text/html" });
481
531
  res.end(getErrorHtml("Authentication callback failed"));
@@ -536,26 +586,44 @@ function getErrorHtml(error) {
536
586
  var HEADLESS_DEFAULT_NAME = "conto-agent";
537
587
  var HEADLESS_DEFAULT_TYPE = "CUSTOM";
538
588
  var HEADLESS_DEFAULT_LIMIT = 500;
589
+ function failInit(message, details = {}) {
590
+ if (isJsonMode()) {
591
+ printJson({ ok: false, error: message, ...details });
592
+ } else {
593
+ printError(message);
594
+ }
595
+ process.exit(1);
596
+ }
597
+ function initSpinner() {
598
+ if (!isJsonMode()) return p.spinner();
599
+ return {
600
+ start() {
601
+ },
602
+ stop() {
603
+ },
604
+ message() {
605
+ }
606
+ };
607
+ }
539
608
  async function runInit(options = {}) {
540
609
  if (options.sandbox) {
541
610
  await runSandboxInit(options);
542
611
  return;
543
612
  }
544
613
  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
545
- if (!interactive && !options.apiKey) {
546
- console.error("create-conto-agent needs an interactive terminal for the setup wizard.");
547
- console.error("Headless options:");
548
- console.error(
549
- " --sandbox create an anonymous test-mode sandbox (no account, expires in 7 days)"
550
- );
551
- console.error(
552
- " --api-key <org-api-key> use an existing Conto organization API key (skips browser auth)"
614
+ const providedOrgApiKey = options.apiKey || process.env.CONTO_ORG_API_KEY;
615
+ if (!interactive && !providedOrgApiKey) {
616
+ failInit(
617
+ [
618
+ "create-conto-agent needs an interactive terminal for the setup wizard.",
619
+ "Headless options: --sandbox, or --api-key <org-api-key>.",
620
+ "Add --json for machine-readable output."
621
+ ].join(" "),
622
+ { headlessOptions: ["--sandbox", "--api-key <org-api-key>"] }
553
623
  );
554
- console.error("Add --json for machine-readable output.");
555
- process.exit(1);
556
624
  }
557
625
  printBanner();
558
- const baseUrl = options.baseUrl || "https://conto.finance";
626
+ const baseUrl = options.baseUrl || process.env.CONTO_BASE_URL || "https://conto.finance";
559
627
  const agentName = options.name || (interactive ? await p.text({
560
628
  message: "Agent name",
561
629
  placeholder: "my-procurement-bot",
@@ -570,7 +638,6 @@ async function runInit(options = {}) {
570
638
  options: [
571
639
  { value: "ANTHROPIC_CLAUDE", label: "Claude" },
572
640
  { value: "OPENAI_ASSISTANT", label: "OpenAI" },
573
- { value: "LANGCHAIN", label: "LangChain" },
574
641
  { value: "AUTOGPT", label: "AutoGPT" },
575
642
  { value: "CUSTOM", label: "Custom" }
576
643
  ]
@@ -593,85 +660,79 @@ async function runInit(options = {}) {
593
660
  p.cancel("Setup cancelled.");
594
661
  process.exit(0);
595
662
  }
596
- const s0 = p.spinner();
663
+ const s0 = initSpinner();
597
664
  s0.start("Fetching supported networks...");
598
665
  const { chains: availableChains, defaultChainId } = await fetchChains(baseUrl);
599
666
  s0.stop(`Found ${Object.keys(availableChains).length} networks`);
600
667
  const chainChoices = getChainChoices(availableChains);
601
- const selectedChain = options.chain || (interactive ? await p.select({
668
+ const selectedChain = options.chain || process.env.CONTO_CHAIN_ID || (interactive ? await p.select({
602
669
  message: "Network",
603
- options: chainChoices
670
+ options: chainChoices,
671
+ initialValue: defaultChainId
604
672
  }) : defaultChainId);
605
673
  if (p.isCancel(selectedChain)) {
606
674
  p.cancel("Setup cancelled.");
607
675
  process.exit(0);
608
676
  }
609
- const chain = availableChains[selectedChain] || availableChains[defaultChainId];
677
+ const selectedChainId = String(selectedChain);
678
+ const chain = availableChains[selectedChainId];
679
+ if (!chain) {
680
+ failInit(`Unknown chain "${selectedChainId}". Choose a chain ID returned by /api/chains.`, {
681
+ availableChainIds: Object.keys(availableChains)
682
+ });
683
+ }
684
+ if (!chain.testnet && !options.confirmMainnet) {
685
+ if (!interactive) {
686
+ failInit(
687
+ `Chain ${chain.chainId} (${chain.name}) is a mainnet and can move real funds. Re-run with --confirm-mainnet after reviewing the network and limits.`,
688
+ { chainId: chain.chainId, requiresConfirmation: "--confirm-mainnet" }
689
+ );
690
+ }
691
+ const confirmed = await p.confirm({
692
+ message: `${chain.name} is a real-money network. Continue with mainnet provisioning?`,
693
+ initialValue: false
694
+ });
695
+ if (p.isCancel(confirmed) || !confirmed) {
696
+ p.cancel("Setup cancelled before any mainnet resources were created.");
697
+ process.exit(0);
698
+ }
699
+ }
610
700
  const limit = typeof dailyLimit === "string" ? Number(dailyLimit) : dailyLimit;
611
- const s = p.spinner();
701
+ const s = initSpinner();
612
702
  let orgApiKey;
613
- if (options.apiKey) {
614
- orgApiKey = options.apiKey;
703
+ let orgApiKeyExpiresAt;
704
+ if (providedOrgApiKey) {
705
+ orgApiKey = providedOrgApiKey;
615
706
  printSuccess("Using provided organization API key");
616
707
  } else {
617
708
  s.start("Opening browser to authenticate...");
618
709
  try {
619
710
  const authResult = await browserAuth(baseUrl);
620
711
  orgApiKey = authResult.orgApiKey;
712
+ orgApiKeyExpiresAt = authResult.expiresAt || void 0;
621
713
  s.stop("Authenticated");
622
714
  printSuccess("Account connected");
623
715
  } catch (err) {
624
716
  s.stop("Authentication failed");
625
- printError(err instanceof Error ? err.message : "Authentication failed");
626
- process.exit(1);
717
+ failInit(err instanceof Error ? err.message : "Authentication failed");
627
718
  }
628
719
  }
629
720
  const api = new ApiClient({ baseUrl, orgApiKey });
630
- s.start(`Provisioning wallet on ${chain.name}...`);
721
+ s.start(`Creating wallet on ${chain.name}...`);
631
722
  let wallet;
632
723
  try {
633
724
  wallet = await api.createWallet({
634
725
  name: `${agentName} Wallet`,
635
726
  chainType: chain.chainType,
636
- chainId: chain.chainId
727
+ chainId: chain.chainId,
728
+ custodyMode: "MANAGED"
637
729
  });
638
730
  } catch (err) {
639
- const status = err.status;
640
- if (status === 503) {
641
- try {
642
- wallet = await api.createWallet({
643
- name: `${agentName} Wallet`,
644
- chainType: chain.chainType,
645
- chainId: chain.chainId,
646
- custodyType: "SPONGE"
647
- });
648
- } catch (retryErr) {
649
- s.stop("Wallet creation failed");
650
- printError(retryErr instanceof Error ? retryErr.message : "Failed to create wallet");
651
- process.exit(1);
652
- }
653
- } else {
654
- s.stop("Wallet creation failed");
655
- printError(err instanceof Error ? err.message : "Failed to create wallet");
656
- process.exit(1);
657
- }
658
- }
659
- s.stop(`Wallet provisioned on ${chain.name}`);
660
- printSuccess(`Wallet: ${wallet.address} (${wallet.custodyType} custody)`);
661
- if (wallet.custodyType === "SPONGE") {
662
- s.start("Linking wallet to custody provider...");
663
- try {
664
- const provisioned = await api.provisionWallet(wallet.id);
665
- if (provisioned.wallet?.address) {
666
- wallet.address = provisioned.wallet.address;
667
- }
668
- s.stop("Custody provider linked");
669
- } catch (err) {
670
- s.stop("Custody provisioning incomplete");
671
- printWarning(err instanceof Error ? err.message : "Custody provider not configured");
672
- printInfo('Payments may run in simulated mode. Run "conto doctor" after setup for details.');
673
- }
731
+ s.stop("Wallet creation failed");
732
+ failInit(err instanceof Error ? err.message : "Failed to create wallet");
674
733
  }
734
+ s.stop(`Wallet created on ${chain.name}`);
735
+ printSuccess(`Wallet: ${wallet.address} (${wallet.custodyMode} custody)`);
675
736
  if (chain.faucetAvailable) {
676
737
  s.start("Requesting testnet funds from faucet...");
677
738
  try {
@@ -699,8 +760,7 @@ async function runInit(options = {}) {
699
760
  printSuccess(`Agent "${agent.name}" created`);
700
761
  } catch (err) {
701
762
  s.stop("Agent creation failed");
702
- printError(err instanceof Error ? err.message : "Failed to create agent");
703
- process.exit(1);
763
+ failInit(err instanceof Error ? err.message : "Failed to create agent");
704
764
  }
705
765
  s.start("Linking wallet to agent...");
706
766
  try {
@@ -714,8 +774,7 @@ async function runInit(options = {}) {
714
774
  printSuccess(`Wallet linked ($${limit}/day limit)`);
715
775
  } catch (err) {
716
776
  s.stop("Wallet linking failed");
717
- printError(err instanceof Error ? err.message : "Failed to link wallet");
718
- process.exit(1);
777
+ failInit(err instanceof Error ? err.message : "Failed to link wallet");
719
778
  }
720
779
  s.start("Creating default spending policy...");
721
780
  try {
@@ -727,7 +786,10 @@ async function runInit(options = {}) {
727
786
  rules: [
728
787
  {
729
788
  ruleType: "DAILY_LIMIT",
730
- operator: "LESS_THAN_OR_EQUAL",
789
+ // Canonical operator accepted by the strict enum at POST /api/policies
790
+ // (src/lib/schemas/common.ts ruleOperatorSchema). The `LESS_THAN_OR_EQUAL`
791
+ // alias is rejected there (400), which the catch below would silently swallow.
792
+ operator: "LTE",
731
793
  value: String(limit),
732
794
  action: "ALLOW"
733
795
  }
@@ -757,13 +819,13 @@ async function runInit(options = {}) {
757
819
  }
758
820
  } catch (err) {
759
821
  s.stop("SDK key generation failed");
760
- printError(err instanceof Error ? err.message : "Failed to create SDK key");
761
- process.exit(1);
822
+ failInit(err instanceof Error ? err.message : "Failed to create SDK key");
762
823
  }
763
824
  const cwd = process.cwd();
825
+ ensureEnvLocalGitignored(cwd);
764
826
  writeEnvLocal(cwd, [
765
827
  "# Conto Agent Configuration",
766
- "# Generated by: npx create-conto-agent",
828
+ "# Generated by: npx @conto_finance/create-conto-agent",
767
829
  "",
768
830
  "# SDK Authentication",
769
831
  ["CONTO_API_KEY", sdkKey.key],
@@ -791,7 +853,7 @@ async function runInit(options = {}) {
791
853
  type: agentType
792
854
  },
793
855
  network: {
794
- chain: selectedChain,
856
+ chain: selectedChainId,
795
857
  chainId: chain.chainId,
796
858
  rpcUrl: chain.rpcUrl,
797
859
  explorerUrl: chain.explorerUrl,
@@ -801,7 +863,7 @@ async function runInit(options = {}) {
801
863
  wallet: {
802
864
  id: wallet.id,
803
865
  address: wallet.address,
804
- custodyType: wallet.custodyType
866
+ custodyMode: wallet.custodyMode
805
867
  },
806
868
  server: {
807
869
  baseUrl
@@ -811,15 +873,15 @@ async function runInit(options = {}) {
811
873
  saveGlobalConfig({
812
874
  agent: { id: agent.id, name: agent.name, type: agentType },
813
875
  network: {
814
- chain: selectedChain,
876
+ chain: selectedChainId,
815
877
  chainId: chain.chainId,
816
878
  rpcUrl: chain.rpcUrl,
817
879
  explorerUrl: chain.explorerUrl,
818
880
  currency: chain.currency,
819
881
  testnet: chain.testnet
820
882
  },
821
- wallet: { id: wallet.id, address: wallet.address, custodyType: wallet.custodyType },
822
- server: { baseUrl, apiKey: sdkKey.key, orgApiKey }
883
+ wallet: { id: wallet.id, address: wallet.address, custodyMode: wallet.custodyMode },
884
+ server: { baseUrl, apiKey: sdkKey.key, orgApiKey, orgApiKeyExpiresAt }
823
885
  });
824
886
  let cliResolves = false;
825
887
  if (hasLocalCliBin(cwd)) {
@@ -839,19 +901,47 @@ async function runInit(options = {}) {
839
901
  s.stop("CLI install failed (continuing)");
840
902
  }
841
903
  }
904
+ const cli = cliResolves ? "npx conto" : "npx @conto_finance/create-conto-agent";
905
+ const nextSteps = [
906
+ `${cli} doctor`,
907
+ "node example.mjs",
908
+ `${cli} pay <address> <amount>`,
909
+ `${cli} mcp`
910
+ ];
911
+ if (isJsonMode()) {
912
+ printJson({
913
+ ok: true,
914
+ mode: "organization",
915
+ baseUrl,
916
+ agent,
917
+ wallet,
918
+ network: {
919
+ chainId: chain.chainId,
920
+ name: chain.name,
921
+ currency: chain.currency,
922
+ testnet: chain.testnet
923
+ },
924
+ credentials: {
925
+ storedIn: ".env.local",
926
+ sdkKeyEnv: "CONTO_API_KEY"
927
+ },
928
+ files: [".env.local", ".gitignore", "conto.config.json", "example.mjs"],
929
+ nextSteps
930
+ });
931
+ return;
932
+ }
842
933
  console.log("");
843
934
  console.log(chalk.green.bold(" Your agent is ready!") + " Files written:\n");
844
935
  console.log(` ${chalk.bold(".env.local")} - SDK key + config`);
845
936
  console.log(` ${chalk.bold("conto.config.json")} - Agent metadata`);
846
- console.log(` ${chalk.bold("example.ts")} - Runnable payment example`);
937
+ console.log(` ${chalk.bold("example.mjs")} - Runnable payment example`);
847
938
  console.log("");
848
939
  console.log(
849
- ` ${chalk.dim("Wallet:")} ${wallet.address} (${chain.name}${chain.testnet ? " testnet" : ""}, ${wallet.custodyType} custody)`
940
+ ` ${chalk.dim("Wallet:")} ${wallet.address} (${chain.name}${chain.testnet ? " testnet" : ""}, ${wallet.custodyMode} custody)`
850
941
  );
851
942
  console.log(` ${chalk.dim("Currency:")} ${chain.currency}`);
852
943
  console.log(` ${chalk.dim("Explorer:")} ${chain.explorerUrl}`);
853
944
  console.log("");
854
- const cli = cliResolves ? "npx conto" : "npx @conto_finance/create-conto-agent";
855
945
  console.log(chalk.bold(" Next steps:"));
856
946
  let step = 1;
857
947
  console.log(` ${step++}. Verify setup: ${chalk.cyan(`${cli} doctor`)}`);
@@ -860,7 +950,7 @@ async function runInit(options = {}) {
860
950
  ` ${step++}. Fund your wallet with ${chain.currency} ${chalk.dim("\u2192")} ${wallet.address}`
861
951
  );
862
952
  }
863
- console.log(` ${step++}. Run the example: ${chalk.cyan("npx tsx example.ts")}`);
953
+ console.log(` ${step++}. Run the example: ${chalk.cyan("node example.mjs")}`);
864
954
  console.log(` ${step++}. Make a payment: ${chalk.cyan(`${cli} pay <address> <amount>`)}`);
865
955
  console.log(` ${step++}. Connect Claude: ${chalk.cyan(`${cli} mcp`)}`);
866
956
  if (!cliResolves) {
@@ -920,9 +1010,10 @@ async function runSandboxInit(options) {
920
1010
  chain = void 0;
921
1011
  }
922
1012
  const cwd = process.cwd();
1013
+ ensureEnvLocalGitignored(cwd);
923
1014
  writeEnvLocal(cwd, [
924
1015
  "# Conto Agent Configuration (anonymous test-mode sandbox)",
925
- "# Generated by: npx create-conto-agent --sandbox",
1016
+ "# Generated by: npx @conto_finance/create-conto-agent --sandbox",
926
1017
  "",
927
1018
  "# SDK Authentication",
928
1019
  ["CONTO_API_KEY", sandbox.credentials.sdkKey],
@@ -966,15 +1057,14 @@ async function runSandboxInit(options) {
966
1057
  wallet: {
967
1058
  id: sandbox.wallet.id,
968
1059
  address: sandbox.wallet.address,
969
- custodyType: sandbox.wallet.custodyType
1060
+ custodyMode: sandbox.wallet.custodyMode
970
1061
  },
971
1062
  server: {
972
1063
  baseUrl
973
1064
  },
974
1065
  sandbox: {
975
1066
  mode: "test",
976
- expiresAt: sandbox.expiresAt,
977
- execution: "simulated"
1067
+ expiresAt: sandbox.expiresAt
978
1068
  }
979
1069
  });
980
1070
  writeExampleFile(cwd);
@@ -995,12 +1085,16 @@ async function runSandboxInit(options) {
995
1085
  wallet: {
996
1086
  id: sandbox.wallet.id,
997
1087
  address: sandbox.wallet.address,
998
- custodyType: sandbox.wallet.custodyType
1088
+ custodyMode: sandbox.wallet.custodyMode
999
1089
  },
1000
1090
  server: {
1001
1091
  baseUrl,
1002
1092
  apiKey: sandbox.credentials.sdkKey,
1003
1093
  orgApiKey: sandbox.credentials.apiKey
1094
+ },
1095
+ sandbox: {
1096
+ mode: "test",
1097
+ expiresAt: sandbox.expiresAt
1004
1098
  }
1005
1099
  });
1006
1100
  let cliResolves = hasLocalCliBin(cwd);
@@ -1014,16 +1108,23 @@ async function runSandboxInit(options) {
1014
1108
  mode: "sandbox",
1015
1109
  baseUrl,
1016
1110
  expiresAt: sandbox.expiresAt,
1017
- execution: "simulated",
1018
1111
  organization: sandbox.organization,
1019
1112
  agent: sandbox.agent,
1020
1113
  wallet: sandbox.wallet,
1021
- credentials: { ...sandbox.credentials, shownOnce: true },
1022
- files: [".env.local", "conto.config.json", "example.ts"],
1023
- claim: sandbox.claim ?? null,
1114
+ credentials: {
1115
+ storedIn: ".env.local",
1116
+ sdkKeyEnv: "CONTO_API_KEY",
1117
+ sandboxApiKeyEnv: "CONTO_SANDBOX_API_KEY"
1118
+ },
1119
+ files: [".env.local", ".gitignore", "conto.config.json", "example.mjs"],
1120
+ claim: sandbox.claim ? {
1121
+ method: sandbox.claim.method,
1122
+ endpoint: sandbox.claim.endpoint,
1123
+ credentialEnv: "CONTO_SANDBOX_API_KEY"
1124
+ } : null,
1024
1125
  nextSteps: [
1025
- "npx tsx example.ts",
1026
- "npx tsx example.ts --execute",
1126
+ "node example.mjs",
1127
+ "node example.mjs --execute",
1027
1128
  `${cli} doctor`,
1028
1129
  `${cli} pay 0x742d35Cc6634C0532925a3b844Bc454e4438f44e 1 --purpose test`
1029
1130
  ]
@@ -1034,13 +1135,13 @@ async function runSandboxInit(options) {
1034
1135
  console.log(chalk.green.bold(" Sandbox agent ready!") + " Files written:\n");
1035
1136
  console.log(` ${chalk.bold(".env.local")} - SDK key + config (shown once)`);
1036
1137
  console.log(` ${chalk.bold("conto.config.json")} - Agent metadata`);
1037
- console.log(` ${chalk.bold("example.ts")} - Runnable payment example`);
1138
+ console.log(` ${chalk.bold("example.mjs")} - Runnable payment example`);
1038
1139
  console.log("");
1039
1140
  console.log(
1040
1141
  ` ${chalk.dim("Wallet:")} ${sandbox.wallet.address} (${chain?.name || sandbox.wallet.chainId}, test mode)`
1041
1142
  );
1042
1143
  console.log(
1043
- ` ${chalk.dim("Balance:")} ${sandbox.wallet.balance} ${sandbox.wallet.currency} (simulated)`
1144
+ ` ${chalk.dim("Balance:")} ${sandbox.wallet.balance} ${sandbox.wallet.currency} (test balance)`
1044
1145
  );
1045
1146
  console.log(
1046
1147
  ` ${chalk.dim("Limits:")} $${sandbox.wallet.limits.perTransaction}/tx, $${sandbox.wallet.limits.daily}/day`
@@ -1048,12 +1149,12 @@ async function runSandboxInit(options) {
1048
1149
  console.log(` ${chalk.dim("Expires:")} ${sandbox.expiresAt}`);
1049
1150
  console.log("");
1050
1151
  console.log(chalk.bold(" Next steps:"));
1051
- console.log(` 1. Run the example: ${chalk.cyan("npx tsx example.ts")}`);
1052
- console.log(` 2. Execute it: ${chalk.cyan("npx tsx example.ts --execute")}`);
1152
+ console.log(` 1. Run the example: ${chalk.cyan("node example.mjs")}`);
1153
+ console.log(` 2. Execute it: ${chalk.cyan("node example.mjs --execute")}`);
1053
1154
  console.log(` 3. Verify setup: ${chalk.cyan(`${cli} doctor`)}`);
1054
1155
  console.log("");
1055
1156
  printInfo(
1056
- "Sandbox payments execute in simulated mode: policy checks, receipts, and spend tracking are real; no onchain transfer happens."
1157
+ "Sandbox test payments exercise policy checks, receipts, and spend tracking without an onchain transfer."
1057
1158
  );
1058
1159
  printInfo("To keep this sandbox, sign in at conto.finance and claim it before it expires.");
1059
1160
  console.log("");
@@ -1106,13 +1207,15 @@ function writeExampleFile(dir) {
1106
1207
  const content = `// Conto quickstart example, generated by create-conto-agent.
1107
1208
  //
1108
1209
  // Usage:
1109
- // npx tsx example.ts Check setup and request a test payment (no funds move)
1110
- // npx tsx example.ts --execute Also execute the payment if it is approved
1210
+ // node example.mjs Check setup and request a test payment (no funds move)
1211
+ // node example.mjs --execute Also execute the payment if it is approved
1111
1212
  //
1112
1213
  // Reads CONTO_API_KEY and CONTO_BASE_URL from .env.local in this directory.
1113
1214
  // Docs: https://conto.finance/docs
1114
1215
 
1115
1216
  import { readFileSync } from 'fs';
1217
+ import { randomUUID } from 'node:crypto';
1218
+ let lastRequestId;
1116
1219
  try {
1117
1220
  for (const line of readFileSync('.env.local', 'utf-8').split('\\n')) {
1118
1221
  const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
@@ -1122,20 +1225,23 @@ try {
1122
1225
 
1123
1226
  const BASE_URL = process.env.CONTO_BASE_URL || 'https://conto.finance';
1124
1227
  const API_KEY = process.env.CONTO_API_KEY;
1228
+ const IS_SANDBOX = Boolean(process.env.CONTO_SANDBOX_EXPIRES_AT);
1125
1229
  const EXECUTE = process.argv.includes('--execute');
1126
1230
 
1127
1231
  if (!API_KEY) {
1128
- console.error('Missing CONTO_API_KEY in .env.local. Run: npx create-conto-agent');
1232
+ console.error('Missing CONTO_API_KEY in .env.local. Run: npx @conto_finance/create-conto-agent');
1129
1233
  process.exit(1);
1130
1234
  }
1131
1235
 
1132
- async function api(method: string, path: string, body?: unknown) {
1236
+ async function api(method, path, body) {
1133
1237
  const res = await fetch(\`\${BASE_URL}\${path}\`, {
1134
1238
  method,
1135
1239
  headers: { Authorization: \`Bearer \${API_KEY}\`, 'Content-Type': 'application/json' },
1136
1240
  body: body ? JSON.stringify(body) : undefined,
1137
1241
  });
1138
1242
  const data = await res.json();
1243
+ if (data.requestId) lastRequestId = data.requestId;
1244
+ if (!res.ok && data.actionUrl) console.error('Complete action:', data.actionUrl);
1139
1245
  if (!res.ok) throw new Error(data.error || \`\${method} \${path} failed (\${res.status})\`);
1140
1246
  return data;
1141
1247
  }
@@ -1148,20 +1254,33 @@ async function main() {
1148
1254
  for (const w of setup.wallets || []) {
1149
1255
  console.log(\`Wallet: \${w.address}\`);
1150
1256
  console.log(\` Chain: \${w.chainName} (\${w.chainId})\${w.isTestnet ? ' testnet' : ''}\`);
1151
- console.log(\` Custody: \${w.custodyType}\${w.executionMode ? \` ( execution)\` : ''}\`);
1257
+ const executionLabel =
1258
+ IS_SANDBOX
1259
+ ? 'sandbox test mode'
1260
+ : w.custodyMode === 'MANAGED'
1261
+ ? 'managed execution'
1262
+ : 'external execution';
1263
+ console.log(\` Custody: \${w.custodyMode}\${executionLabel ? \` (\${executionLabel})\` : ''}\`);
1152
1264
  console.log(\` Balance: \${w.balance} \${w.currency}\`);
1153
1265
  console.log(\` Daily: \${w.spent?.today ?? 0} / \${w.limits?.daily ?? 'unlimited'}\\n\`);
1154
1266
  }
1155
1267
 
1268
+ const wallet = (setup.wallets || []).find((w) => String(w.chainId) === '42431');
1269
+ if (!wallet) throw new Error('This example requires a Tempo Testnet wallet (42431).');
1270
+
1156
1271
  // 2. Request a payment. The policy engine evaluates it and returns
1157
1272
  // APPROVED, DENIED, or REQUIRES_APPROVAL. No funds move on request.
1158
1273
  console.log('Requesting a $0.01 test payment...');
1159
1274
  const request = await api('POST', '/api/sdk/payments/request', {
1160
1275
  amount: 0.01,
1276
+ walletId: wallet.id,
1277
+ idempotencyKey: randomUUID(),
1161
1278
  recipientAddress: '0x0000000000000000000000000000000000000001',
1162
1279
  purpose: 'Test payment from CLI quickstart',
1163
1280
  category: 'TESTING',
1164
1281
  });
1282
+ lastRequestId = request.requestId;
1283
+ console.log('Request ID:', lastRequestId);
1165
1284
  console.log(\`Policy decision: \${request.status}\`);
1166
1285
  if (request.reasons?.length) console.log(\`Reasons: \${request.reasons.join(', ')}\`);
1167
1286
 
@@ -1182,21 +1301,25 @@ async function main() {
1182
1301
  // quickstart includes the payments:execute scope.
1183
1302
  if (!EXECUTE) {
1184
1303
  console.log(\`\\nApproved (request \${request.requestId}). No funds moved.\`);
1185
- console.log('Re-run with --execute to send it, or use: npx conto pay <address> <amount>');
1304
+ console.log('Re-run with --execute to send it, or use: npx @conto_finance/create-conto-agent pay <address> <amount>');
1186
1305
  return;
1187
1306
  }
1188
1307
  const result = await api('POST', \`/api/sdk/payments/\${request.requestId}/execute\`);
1189
- console.log(\`\\nPayment sent\${result.simulated ? ' (simulated, no onchain transfer)' : ''}.\`);
1190
- console.log(\`TX hash: \${result.txHash}\`);
1191
- console.log(\`Explorer: \${result.explorerUrl}\`);
1308
+ console.log(IS_SANDBOX ? '\\nPayment recorded in sandbox test mode.' : '\\nPayment sent.');
1309
+ console.log('Status:', result.status);
1310
+ console.log('Settlement mode:', result.receipt?.settlementMode);
1311
+ if (result.receipt?.txHash) console.log('TX hash:', result.receipt.txHash);
1312
+ if (result.receipt?.explorerUrl) console.log('Explorer:', result.receipt.explorerUrl);
1313
+ console.log('Check settlement with GET /api/sdk/payments/' + lastRequestId);
1192
1314
  }
1193
1315
 
1194
1316
  main().catch((err) => {
1195
1317
  console.error(err instanceof Error ? err.message : err);
1318
+ if (lastRequestId) console.error('Do not repeat execution. Check GET /api/sdk/payments/' + lastRequestId);
1196
1319
  process.exit(1);
1197
1320
  });
1198
1321
  `;
1199
- fs.writeFileSync(path.join(dir, "example.ts"), content);
1322
+ fs.writeFileSync(path.join(dir, "example.mjs"), content);
1200
1323
  }
1201
1324
 
1202
1325
  export {