@dvmkit/dvm-cli 0.19.0 → 0.19.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.
package/README.md CHANGED
@@ -10,9 +10,17 @@ Requires Node.js 22 or later.
10
10
 
11
11
  ```sh
12
12
  npm install --global @dvmkit/dvm-cli
13
+ ```
14
+
15
+ ## Try it
16
+
17
+ ```sh
13
18
  dvm init
19
+ dvm request -d dvmkit--stakeout/peek --data '{"cameras":["kiruna"]}'
14
20
  ```
15
21
 
22
+ Get a one-time grade of the live Kiruna aurora camera for free, with no wallet or payment; see [Stakeout](https://dvmkit.com/dvmkit/stakeout) for more capabilities.
23
+
16
24
  `dvm init` returns JSON with `status: "created"` on first setup and the message "Local setup is ready. Nothing has been funded yet, so nothing can be spent yet." It also reports the configuration path and wallet setup steps.
17
25
 
18
26
  ## For agents
@@ -26,7 +26,7 @@ import {
26
26
  resolveBtcUsdRate,
27
27
  tryResolveBtcUsdRate,
28
28
  tryX402Payment
29
- } from "./chunk-DJDONOMG.js";
29
+ } from "./chunk-7HJ5ZR3D.js";
30
30
  import {
31
31
  BUDGET_FILE,
32
32
  CONFIG_DIR,
@@ -2744,27 +2744,61 @@ function parseUpfrontRailPayment(value) {
2744
2744
  ...Number.isSafeInteger(raw.usdMicro) && raw.usdMicro >= 0 ? { usdMicro: raw.usdMicro } : {}
2745
2745
  };
2746
2746
  }
2747
- function parseUpfrontPayment(value) {
2748
- if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
2747
+ var UPFRONT_RAILS = {
2748
+ cashu: true,
2749
+ x402: true,
2750
+ tempo: true,
2751
+ lightning: true,
2752
+ stripe: true
2753
+ };
2754
+ function isUpfrontRail(value) {
2755
+ return typeof value === "string" && Object.hasOwn(UPFRONT_RAILS, value);
2756
+ }
2757
+ function checkUpfrontPayment(value) {
2758
+ if (!value || typeof value !== "object" || Array.isArray(value)) return { reason: "upfront_payment is not an object" };
2749
2759
  const raw = value;
2750
- if (!Number.isSafeInteger(raw.amount_msats) || Number(raw.amount_msats) < 0) return void 0;
2760
+ if (!Number.isSafeInteger(raw.amount_msats) || Number(raw.amount_msats) < 0)
2761
+ return { reason: "amount_msats is not a non-negative integer" };
2751
2762
  for (const key of ["amount_micro", "native_amount"]) {
2752
- if (raw[key] !== void 0 && (!Number.isSafeInteger(raw[key]) || Number(raw[key]) < 0)) return void 0;
2753
- }
2754
- if (raw.amount_micro === void 0 !== (raw.currency === void 0) || raw.currency !== void 0 && (typeof raw.currency !== "string" || !/^[a-z]{3}$/.test(raw.currency))) return void 0;
2755
- if (raw.credit_id === void 0 !== (raw.draw_id === void 0)) return void 0;
2763
+ if (raw[key] !== void 0 && (!Number.isSafeInteger(raw[key]) || Number(raw[key]) < 0))
2764
+ return { reason: `${key} is not a non-negative integer` };
2765
+ }
2766
+ if (raw.amount_micro === void 0 !== (raw.currency === void 0))
2767
+ return { reason: "amount_micro and currency must be set together" };
2768
+ if (raw.currency !== void 0 && (typeof raw.currency !== "string" || !/^[a-z]{3}$/.test(raw.currency)))
2769
+ return { reason: "currency is not a lowercase three-letter code" };
2770
+ if (raw.credit_id === void 0 !== (raw.draw_id === void 0))
2771
+ return { reason: "credit_id and draw_id must be set together" };
2756
2772
  for (const key of ["credit_id", "draw_id", "native_asset"]) {
2757
- if (raw[key] !== void 0 && (typeof raw[key] !== "string" || raw[key].trim().length === 0)) return void 0;
2773
+ if (raw[key] !== void 0 && (typeof raw[key] !== "string" || raw[key].trim().length === 0))
2774
+ return { reason: `${key} is not a non-empty string` };
2758
2775
  }
2759
- if (raw.rail !== void 0 && !["cashu", "x402", "tempo", "lightning"].includes(String(raw.rail))) return void 0;
2760
- return {
2776
+ if (raw.rail !== void 0 && !isUpfrontRail(raw.rail))
2777
+ return { reason: `rail ${JSON.stringify(String(raw.rail)).slice(0, 40)} is not a known funding rail` };
2778
+ return { payment: {
2761
2779
  amount_msats: raw.amount_msats,
2762
2780
  ...raw.amount_micro !== void 0 ? { amount_micro: raw.amount_micro, currency: raw.currency } : {},
2763
2781
  ...raw.rail !== void 0 ? { rail: raw.rail } : {},
2764
2782
  ...raw.native_amount !== void 0 ? { native_amount: raw.native_amount } : {},
2765
2783
  ...raw.native_asset !== void 0 ? { native_asset: raw.native_asset } : {},
2766
2784
  ...raw.credit_id !== void 0 ? { credit_id: raw.credit_id, draw_id: raw.draw_id } : {}
2767
- };
2785
+ } };
2786
+ }
2787
+ function parseUpfrontPayment(value) {
2788
+ const checked = checkUpfrontPayment(value);
2789
+ return "payment" in checked ? checked.payment : void 0;
2790
+ }
2791
+ function upfrontPaymentFault(value) {
2792
+ if (value === void 0 || value === null) return void 0;
2793
+ const checked = checkUpfrontPayment(value);
2794
+ return "reason" in checked ? checked.reason : void 0;
2795
+ }
2796
+ function upfrontReceiptFields(value) {
2797
+ const fault = upfrontPaymentFault(value);
2798
+ return { upfrontPayment: parseUpfrontPayment(value), ...fault ? { upfrontPaymentFault: fault } : {} };
2799
+ }
2800
+ function receiptUpfrontFault(receipt) {
2801
+ return receipt.upfrontPaymentFault;
2768
2802
  }
2769
2803
 
2770
2804
  // src/lib/job-budget.ts
@@ -2832,28 +2866,51 @@ function saveSubmittedJob(job) {
2832
2866
  throw new Error("Submitted job conflicts with an existing local job.");
2833
2867
  }, true, job);
2834
2868
  }
2835
- function recordUpfrontCreditPayment(jobId, value, paidOnRail = false) {
2869
+ function markUpfrontCreditConflict(job, reason, recoverable = false) {
2870
+ const wasRecoverable = job.upfrontCreditConflictRecoverable === true;
2871
+ if (job.upfrontCreditConflict && !(wasRecoverable && !recoverable)) {
2872
+ job.upfrontCreditConflictReason ??= reason;
2873
+ return;
2874
+ }
2875
+ job.upfrontCreditConflict = true;
2876
+ job.upfrontCreditConflictReason = reason;
2877
+ if (recoverable) job.upfrontCreditConflictRecoverable = true;
2878
+ else delete job.upfrontCreditConflictRecoverable;
2879
+ }
2880
+ function recordUpfrontCreditPayment(jobId, value, paidOnRail = false, fault) {
2836
2881
  const payment = parseUpfrontPayment(value);
2882
+ const unusable = fault ?? upfrontPaymentFault(value);
2837
2883
  mutateJobs((jobs) => {
2838
2884
  const job = jobs.find((entry) => entry.id === jobId);
2839
- if (!job || !payment) return;
2885
+ if (!job) return;
2886
+ if (!payment) {
2887
+ if (unusable && !paidOnRail && job.paymentMethod === "credit" && !job.upfrontCreditBooked) {
2888
+ markUpfrontCreditConflict(job, `the provider's upfront_payment was unusable: ${unusable}`, true);
2889
+ }
2890
+ return;
2891
+ }
2840
2892
  if (paidOnRail || job.paymentMethod && job.paymentMethod !== "credit") {
2841
2893
  job.upfrontPayment ??= payment;
2842
2894
  return;
2843
2895
  }
2844
2896
  if (!payment.credit_id || !payment.draw_id) {
2845
- if (job.paymentMethod === "credit") job.upfrontCreditConflict = true;
2897
+ if (job.paymentMethod === "credit") markUpfrontCreditConflict(job, "the accepted debit names no credit draw");
2846
2898
  return;
2847
2899
  }
2848
2900
  const binding = job.creditBinding;
2849
2901
  if (!binding || "unbound" in binding || binding.creditId !== payment.credit_id || binding.drawId !== payment.draw_id) {
2850
- job.upfrontCreditConflict = true;
2902
+ markUpfrontCreditConflict(job, "the accepted debit does not match this job's credit draw");
2851
2903
  return;
2852
2904
  }
2853
2905
  if (job.upfrontPayment && JSON.stringify(job.upfrontPayment) !== JSON.stringify(payment)) {
2854
- job.upfrontCreditConflict = true;
2906
+ markUpfrontCreditConflict(job, "the provider reported a different accepted debit than the one recorded");
2855
2907
  return;
2856
2908
  }
2909
+ if (job.upfrontCreditConflictRecoverable) {
2910
+ delete job.upfrontCreditConflict;
2911
+ delete job.upfrontCreditConflictReason;
2912
+ delete job.upfrontCreditConflictRecoverable;
2913
+ }
2857
2914
  job.upfrontPayment = payment;
2858
2915
  job.paymentMethod = "credit";
2859
2916
  if (job.upfrontCreditBooked) return;
@@ -9205,6 +9262,9 @@ function fundTimeoutMs() {
9205
9262
  if (!Number.isFinite(n) || n <= 0) return DEFAULT_TIMEOUT_SEC * 1e3;
9206
9263
  return Math.floor(n) * 1e3;
9207
9264
  }
9265
+ function withoutPendingMint(wallet, quoteId) {
9266
+ return { ...wallet, pending_mints: wallet.pending_mints.filter((p) => p.quote_id !== quoteId) };
9267
+ }
9208
9268
  function upsertPending(wallet, entry) {
9209
9269
  const others = wallet.pending_mints.filter((p) => p.quote_id !== entry.quote_id);
9210
9270
  return { ...wallet, pending_mints: [...others, entry] };
@@ -9366,18 +9426,19 @@ async function findFundableAlternatives(configured, skip, sats) {
9366
9426
 
9367
9427
  // src/lib/wallet-agent/recovery.ts
9368
9428
  var DEFAULT_SWEEP_QUOTE_RETRY_TIMEOUT_MS = 1e4;
9429
+ var MINT_QUOTE_EXPIRY_GRACE_MS = 24 * 60 * 60 * 1e3;
9369
9430
  async function sweepPendingMints(opts = {}) {
9370
9431
  const wallet = loadAgentWallet();
9371
9432
  if (!wallet || wallet.pending_mints.length === 0) {
9372
- return { outcomes: [], recovered_proofs: [], still_pending: [], errors: [] };
9433
+ return { outcomes: [], recovered_proofs: [], still_pending: [], refused: [], errors: [] };
9373
9434
  }
9374
9435
  const now = opts.now ?? (() => Date.now());
9375
- const expirationMs = opts.expirationMs ?? fundTimeoutMs();
9436
+ const expiryGraceMs = opts.expiryGraceMs ?? MINT_QUOTE_EXPIRY_GRACE_MS;
9376
9437
  const getWalletForMint = opts.getWalletForMint ?? getWallet;
9377
9438
  const quoteRetryTimeoutMs = opts.quoteRetryTimeoutMs ?? DEFAULT_SWEEP_QUOTE_RETRY_TIMEOUT_MS;
9378
9439
  const outcomes = [];
9379
9440
  for (const entry of wallet.pending_mints) {
9380
- const outcome = await processEntry(wallet, entry, now(), expirationMs, getWalletForMint, {
9441
+ const outcome = await processEntry(wallet, entry, now(), expiryGraceMs, getWalletForMint, {
9381
9442
  now,
9382
9443
  sleep: opts.sleep,
9383
9444
  timeoutMs: quoteRetryTimeoutMs
@@ -9401,10 +9462,11 @@ async function sweepPendingMints(opts = {}) {
9401
9462
  still_pending: outcomes.filter(
9402
9463
  (o) => o.kind === "still_pending"
9403
9464
  ).map((o) => o.entry),
9465
+ refused: outcomes.filter((o) => o.kind === "paid_refused").map((o) => o.entry),
9404
9466
  errors: outcomes.filter((o) => o.kind === "error").map((o) => ({ quote_id: o.entry.quote_id, error: o.error }))
9405
9467
  };
9406
9468
  }
9407
- async function processEntry(wallet, entry, nowMs, expirationMs, getWalletForMint, retry) {
9469
+ async function processEntry(wallet, entry, nowMs, expiryGraceMs, getWalletForMint, retry) {
9408
9470
  let cashuWallet;
9409
9471
  let quoteResponse;
9410
9472
  try {
@@ -9422,6 +9484,15 @@ async function processEntry(wallet, entry, nowMs, expirationMs, getWalletForMint
9422
9484
  }
9423
9485
  ));
9424
9486
  } catch (err) {
9487
+ const refusal = mintQuoteRefusal(err);
9488
+ if (refusal !== void 0) {
9489
+ return finalAnswer(
9490
+ wallet,
9491
+ entry,
9492
+ refusal === "unknown" ? "mint_unknown" : "mint_expired",
9493
+ () => getWalletForMint(entry.mint)
9494
+ );
9495
+ }
9425
9496
  return { kind: "error", entry, error: errorMessage(err) };
9426
9497
  }
9427
9498
  const state = quoteResponse.state;
@@ -9475,29 +9546,72 @@ async function processEntry(wallet, entry, nowMs, expirationMs, getWalletForMint
9475
9546
  const agentProofs = proofs.map((p) => toAgentProof(p, entry.mint, wallet.lock_pubkey));
9476
9547
  return { kind: "minted", entry, proofs: agentProofs };
9477
9548
  } catch (err) {
9549
+ if (mintQuoteRefusal(err) === "expired") {
9550
+ return { kind: "paid_refused", entry, reason: "quote_expired" };
9551
+ }
9478
9552
  return { kind: "error", entry, error: errorMessage(err) };
9479
9553
  }
9480
9554
  }
9555
+ if (state === "EXPIRED") {
9556
+ return finalAnswer(wallet, entry, "mint_expired", async () => cashuWallet);
9557
+ }
9481
9558
  const quoteExpiry = entry.expires_at;
9482
- if (quoteExpiry !== void 0 && Number.isFinite(quoteExpiry)) {
9483
- if (nowMs > quoteExpiry * 1e3) {
9484
- return { kind: "expired", entry };
9485
- }
9559
+ if (quoteExpiry === void 0 || !Number.isFinite(quoteExpiry)) {
9560
+ return { kind: "still_pending", entry };
9561
+ }
9562
+ const expiredAtMs = quoteExpiry * 1e3;
9563
+ if (nowMs <= expiredAtMs) {
9486
9564
  return { kind: "still_pending", entry };
9487
9565
  }
9488
- const requestedAtMs = Date.parse(entry.requested_at);
9489
- const ageMs = Number.isFinite(requestedAtMs) ? nowMs - requestedAtMs : Infinity;
9490
- if (ageMs > expirationMs) {
9491
- return { kind: "expired", entry };
9566
+ const dropAfterMs = expiredAtMs + expiryGraceMs;
9567
+ if (nowMs > dropAfterMs) {
9568
+ return finalAnswer(wallet, entry, "grace_elapsed", async () => cashuWallet);
9569
+ }
9570
+ return {
9571
+ kind: "still_pending",
9572
+ entry,
9573
+ past_expiry: { expired_at_ms: expiredAtMs, drop_after_ms: dropAfterMs }
9574
+ };
9575
+ }
9576
+ async function finalAnswer(wallet, entry, reason, getCashuWallet) {
9577
+ if (!entry.minting) return { kind: "expired", entry, reason };
9578
+ try {
9579
+ const restored = await restoreFromMintingState(
9580
+ await getCashuWallet(),
9581
+ entry.minting,
9582
+ wallet.lock_pubkey,
9583
+ entry.mint
9584
+ );
9585
+ if (restored.length > 0) return { kind: "restored", entry, proofs: restored };
9586
+ } catch (err) {
9587
+ return { kind: "error", entry, error: errorMessage(err) };
9492
9588
  }
9493
- return { kind: "still_pending", entry };
9589
+ if (reason === "mint_expired") return { kind: "paid_refused", entry, reason: "quote_expired" };
9590
+ return {
9591
+ kind: "error",
9592
+ entry,
9593
+ error: reason === "mint_unknown" ? "The mint reported this quote paid earlier and no longer knows it; nothing could be restored, so the quote is kept." : "The mint reported this quote paid earlier and now reports it unpaid; nothing could be restored, so the quote is kept."
9594
+ };
9595
+ }
9596
+ var MINT_QUOTE_EXPIRED_CODE = 20007;
9597
+ var QUOTE_UNKNOWN_TEXT = /\bquote\b[^.]*\b(not found|unknown|does not exist)\b|\b(unknown|no such) quote\b/i;
9598
+ var QUOTE_EXPIRED_TEXT = /\bquote\b[^.]*\bexpired\b|\bexpired quote\b/i;
9599
+ function mintQuoteRefusal(err) {
9600
+ if (typeof err !== "object" || err === null) return void 0;
9601
+ const { name, status, code, message } = err;
9602
+ const answered = name === "MintOperationError" && status === 400 && typeof code === "number";
9603
+ if (!answered) return void 0;
9604
+ const text = typeof message === "string" ? message : "";
9605
+ if (code === MINT_QUOTE_EXPIRED_CODE || QUOTE_EXPIRED_TEXT.test(text)) return "expired";
9606
+ if (QUOTE_UNKNOWN_TEXT.test(text)) return "unknown";
9607
+ return void 0;
9494
9608
  }
9495
9609
  async function restoreFromMintingState(cashuWallet, minting, lockPubkey, mintUrl) {
9496
9610
  const proofs = await restoreProofsFromOutputs(cashuWallet, minting.keyset_id, minting.outputs);
9497
9611
  return proofs.map((proof) => toAgentProof(proof, mintUrl, lockPubkey));
9498
9612
  }
9499
9613
  function applyOutcome(wallet, outcome) {
9500
- if (outcome.kind === "still_pending" || outcome.kind === "error") {
9614
+ if (outcome.kind === "still_pending" || outcome.kind === "paid_refused" || outcome.kind === "error") {
9501
9615
  return wallet;
9502
9616
  }
9503
9617
  const next = {
@@ -9542,6 +9656,8 @@ export {
9542
9656
  upfrontRailPayment,
9543
9657
  parseUpfrontRailPayment,
9544
9658
  parseUpfrontPayment,
9659
+ upfrontReceiptFields,
9660
+ receiptUpfrontFault,
9545
9661
  budgetVerdict,
9546
9662
  dollarBoundUsdMicro,
9547
9663
  askUsdMicro,
@@ -9719,8 +9835,11 @@ export {
9719
9835
  createPendingMintQuote,
9720
9836
  fundAgentWallet,
9721
9837
  fundTimeoutMs,
9838
+ withoutPendingMint,
9722
9839
  pollUntilPaidOrTimeout,
9723
9840
  resolveFundMint,
9724
9841
  describeMintBounds,
9725
- sweepPendingMints
9842
+ MINT_QUOTE_EXPIRY_GRACE_MS,
9843
+ sweepPendingMints,
9844
+ mintQuoteRefusal
9726
9845
  };
@@ -52,15 +52,19 @@ function withJobPersistence(run, warn) {
52
52
 
53
53
  // src/lib/output.ts
54
54
  var warnings = new AsyncLocalStorage2();
55
+ function withOutputWarningContext(run) {
56
+ return warnings.run([], run);
57
+ }
55
58
  function withOutputWarnings(run, human) {
56
- return warnings.run([], () => withJobPersistence(run, ({ accessPreserved, accessUnpreserved }) => {
59
+ const collect = () => withJobPersistence(run, ({ accessPreserved, accessUnpreserved }) => {
57
60
  const hint = accessUnpreserved ? "Job access was not preserved. Supply --endpoint <url> and --job-token <hex>, or DVM_JOB_ENDPOINT and DVM_JOB_TOKEN, to read this job; do not submit or pay again." : "Refresh the job with dvm status <job_id> --messages before paying or submitting a replacement.";
58
61
  addOutputWarnings([{
59
62
  code: "local_job_state_unsaved",
60
63
  display: "The provider's outcome is unchanged, but local job state could not be saved and may lag. Automatic payments are paused for this command." + (accessUnpreserved ? ` ${hint}` : accessPreserved ? ` Job access is preserved privately. ${hint}` : ""),
61
64
  hint
62
65
  }], human);
63
- }));
66
+ });
67
+ return warnings.getStore() ? collect() : withOutputWarningContext(collect);
64
68
  }
65
69
  function sameWarning(prior, entry) {
66
70
  if (prior.code === "local_job_state_unsaved" && entry.code === "local_job_state_unsaved") return true;
@@ -452,6 +456,7 @@ async function priceableRate(btcRate) {
452
456
  export {
453
457
  jobPersistence,
454
458
  hasUnsavedJobState,
459
+ withOutputWarningContext,
455
460
  withOutputWarnings,
456
461
  addOutputWarnings,
457
462
  setOutputTraceId,
@@ -3,7 +3,7 @@ import { createRequire as __dvmCreateRequire } from "node:module";
3
3
  const require = __dvmCreateRequire(import.meta.url);
4
4
  import {
5
5
  tryX402Payment
6
- } from "./chunk-DJDONOMG.js";
6
+ } from "./chunk-7HJ5ZR3D.js";
7
7
  import "./chunk-X6BETQ7V.js";
8
8
  import "./chunk-JBU7RKQ3.js";
9
9
  import "./chunk-KDNFUDOG.js";