@haven_ai/sdk 0.1.6 → 0.1.8
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 +6 -13
- package/dist/index.cjs +51 -18
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +25 -5
- package/dist/index.d.ts +25 -5
- package/dist/index.js +51 -18
- package/dist/index.js.map +1 -1
- package/examples/x402_openapi_python.py +2 -2
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -447,6 +447,14 @@ declare const AgentPaymentPhase: {
|
|
|
447
447
|
readonly Expired: "expired";
|
|
448
448
|
/** Haven could not complete the payment; the agent should stop and surface the failure. */
|
|
449
449
|
readonly Failed: "failed";
|
|
450
|
+
/**
|
|
451
|
+
* Pre-flight check determined the delegate's existing balance plus the
|
|
452
|
+
* remaining on-chain allowance cannot cover the requested amount, so no
|
|
453
|
+
* payment intent was created. Distinct from `UserApprovalRequired`: there
|
|
454
|
+
* is no approval that would fix this — the originating Safe needs more
|
|
455
|
+
* funds or the agent's per-token allowance needs to be raised first.
|
|
456
|
+
*/
|
|
457
|
+
readonly InsufficientFunds: "insufficient_funds";
|
|
450
458
|
};
|
|
451
459
|
type AgentPaymentPhase = (typeof AgentPaymentPhase)[keyof typeof AgentPaymentPhase];
|
|
452
460
|
declare const AgentPaymentNextAction: {
|
|
@@ -466,6 +474,12 @@ declare const AgentPaymentNextAction: {
|
|
|
466
474
|
readonly StopAndTellUser: "stop_and_tell_user";
|
|
467
475
|
/** Ask again only if the user still wants the payment after expiry. */
|
|
468
476
|
readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
|
|
477
|
+
/**
|
|
478
|
+
* Stop and tell the user that the originating Safe needs to be funded or
|
|
479
|
+
* the agent's per-token allowance needs to be raised before the payment
|
|
480
|
+
* can succeed. A user approval will not fix this state on its own.
|
|
481
|
+
*/
|
|
482
|
+
readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
|
|
469
483
|
};
|
|
470
484
|
type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
|
|
471
485
|
/**
|
|
@@ -505,8 +519,8 @@ declare const AgentPaymentRail: {
|
|
|
505
519
|
type AgentPaymentRail = (typeof AgentPaymentRail)[keyof typeof AgentPaymentRail];
|
|
506
520
|
type PaymentPhase = AgentPaymentPhase;
|
|
507
521
|
type PaymentNextAction = AgentPaymentNextAction;
|
|
508
|
-
declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent")[];
|
|
509
|
-
declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it")[];
|
|
522
|
+
declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent" | "insufficient_funds")[];
|
|
523
|
+
declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it" | "fund_safe_or_raise_allowance")[];
|
|
510
524
|
declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
|
|
511
525
|
declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
|
|
512
526
|
declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
|
|
@@ -929,13 +943,19 @@ declare const toolDescriptions: {
|
|
|
929
943
|
readonly quoteX402: {
|
|
930
944
|
readonly summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.";
|
|
931
945
|
readonly behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior — Haven is not contacted.";
|
|
932
|
-
readonly nextActionGuidance: "";
|
|
946
|
+
readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_x402_quote. Do not call the merchant again — Haven re-uses the captured request when paying.";
|
|
933
947
|
};
|
|
934
948
|
readonly payX402: {
|
|
935
949
|
readonly summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
|
|
936
950
|
readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
|
|
937
951
|
readonly behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.";
|
|
938
|
-
readonly nextActionGuidance:
|
|
952
|
+
readonly nextActionGuidance: string;
|
|
953
|
+
};
|
|
954
|
+
readonly payX402OneShot: {
|
|
955
|
+
readonly summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.";
|
|
956
|
+
readonly selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
|
|
957
|
+
readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns an MPP machine-payment challenge instead of standard x402, the MPP payment path is used automatically. If the resource returns a non-402 status, returns it unchanged without contacting Haven.";
|
|
958
|
+
readonly nextActionGuidance: string;
|
|
939
959
|
};
|
|
940
960
|
readonly resumeX402: {
|
|
941
961
|
readonly summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.";
|
|
@@ -945,7 +965,7 @@ declare const toolDescriptions: {
|
|
|
945
965
|
readonly quoteMpp: {
|
|
946
966
|
readonly summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.";
|
|
947
967
|
readonly behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only — Haven is not contacted.";
|
|
948
|
-
readonly nextActionGuidance: "";
|
|
968
|
+
readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_mpp_challenge. Do not call the merchant again — Haven re-uses the captured request when paying.";
|
|
949
969
|
};
|
|
950
970
|
readonly payMpp: {
|
|
951
971
|
readonly summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
|
package/dist/index.d.ts
CHANGED
|
@@ -447,6 +447,14 @@ declare const AgentPaymentPhase: {
|
|
|
447
447
|
readonly Expired: "expired";
|
|
448
448
|
/** Haven could not complete the payment; the agent should stop and surface the failure. */
|
|
449
449
|
readonly Failed: "failed";
|
|
450
|
+
/**
|
|
451
|
+
* Pre-flight check determined the delegate's existing balance plus the
|
|
452
|
+
* remaining on-chain allowance cannot cover the requested amount, so no
|
|
453
|
+
* payment intent was created. Distinct from `UserApprovalRequired`: there
|
|
454
|
+
* is no approval that would fix this — the originating Safe needs more
|
|
455
|
+
* funds or the agent's per-token allowance needs to be raised first.
|
|
456
|
+
*/
|
|
457
|
+
readonly InsufficientFunds: "insufficient_funds";
|
|
450
458
|
};
|
|
451
459
|
type AgentPaymentPhase = (typeof AgentPaymentPhase)[keyof typeof AgentPaymentPhase];
|
|
452
460
|
declare const AgentPaymentNextAction: {
|
|
@@ -466,6 +474,12 @@ declare const AgentPaymentNextAction: {
|
|
|
466
474
|
readonly StopAndTellUser: "stop_and_tell_user";
|
|
467
475
|
/** Ask again only if the user still wants the payment after expiry. */
|
|
468
476
|
readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
|
|
477
|
+
/**
|
|
478
|
+
* Stop and tell the user that the originating Safe needs to be funded or
|
|
479
|
+
* the agent's per-token allowance needs to be raised before the payment
|
|
480
|
+
* can succeed. A user approval will not fix this state on its own.
|
|
481
|
+
*/
|
|
482
|
+
readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
|
|
469
483
|
};
|
|
470
484
|
type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
|
|
471
485
|
/**
|
|
@@ -505,8 +519,8 @@ declare const AgentPaymentRail: {
|
|
|
505
519
|
type AgentPaymentRail = (typeof AgentPaymentRail)[keyof typeof AgentPaymentRail];
|
|
506
520
|
type PaymentPhase = AgentPaymentPhase;
|
|
507
521
|
type PaymentNextAction = AgentPaymentNextAction;
|
|
508
|
-
declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent")[];
|
|
509
|
-
declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it")[];
|
|
522
|
+
declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent" | "insufficient_funds")[];
|
|
523
|
+
declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it" | "fund_safe_or_raise_allowance")[];
|
|
510
524
|
declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
|
|
511
525
|
declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
|
|
512
526
|
declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
|
|
@@ -929,13 +943,19 @@ declare const toolDescriptions: {
|
|
|
929
943
|
readonly quoteX402: {
|
|
930
944
|
readonly summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.";
|
|
931
945
|
readonly behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior — Haven is not contacted.";
|
|
932
|
-
readonly nextActionGuidance: "";
|
|
946
|
+
readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_x402_quote. Do not call the merchant again — Haven re-uses the captured request when paying.";
|
|
933
947
|
};
|
|
934
948
|
readonly payX402: {
|
|
935
949
|
readonly summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
|
|
936
950
|
readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
|
|
937
951
|
readonly behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.";
|
|
938
|
-
readonly nextActionGuidance:
|
|
952
|
+
readonly nextActionGuidance: string;
|
|
953
|
+
};
|
|
954
|
+
readonly payX402OneShot: {
|
|
955
|
+
readonly summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.";
|
|
956
|
+
readonly selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
|
|
957
|
+
readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns an MPP machine-payment challenge instead of standard x402, the MPP payment path is used automatically. If the resource returns a non-402 status, returns it unchanged without contacting Haven.";
|
|
958
|
+
readonly nextActionGuidance: string;
|
|
939
959
|
};
|
|
940
960
|
readonly resumeX402: {
|
|
941
961
|
readonly summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.";
|
|
@@ -945,7 +965,7 @@ declare const toolDescriptions: {
|
|
|
945
965
|
readonly quoteMpp: {
|
|
946
966
|
readonly summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.";
|
|
947
967
|
readonly behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only — Haven is not contacted.";
|
|
948
|
-
readonly nextActionGuidance: "";
|
|
968
|
+
readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_mpp_challenge. Do not call the merchant again — Haven re-uses the captured request when paying.";
|
|
949
969
|
};
|
|
950
970
|
readonly payMpp: {
|
|
951
971
|
readonly summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
|
package/dist/index.js
CHANGED
|
@@ -27,7 +27,15 @@ var AgentPaymentPhase = {
|
|
|
27
27
|
/** The payment or approval request expired before completion. */
|
|
28
28
|
Expired: "expired",
|
|
29
29
|
/** Haven could not complete the payment; the agent should stop and surface the failure. */
|
|
30
|
-
Failed: "failed"
|
|
30
|
+
Failed: "failed",
|
|
31
|
+
/**
|
|
32
|
+
* Pre-flight check determined the delegate's existing balance plus the
|
|
33
|
+
* remaining on-chain allowance cannot cover the requested amount, so no
|
|
34
|
+
* payment intent was created. Distinct from `UserApprovalRequired`: there
|
|
35
|
+
* is no approval that would fix this — the originating Safe needs more
|
|
36
|
+
* funds or the agent's per-token allowance needs to be raised first.
|
|
37
|
+
*/
|
|
38
|
+
InsufficientFunds: "insufficient_funds"
|
|
31
39
|
};
|
|
32
40
|
var AgentPaymentNextAction = {
|
|
33
41
|
/** Sign with the delegate key and submit the payment to Haven. */
|
|
@@ -45,7 +53,13 @@ var AgentPaymentNextAction = {
|
|
|
45
53
|
/** Stop retrying this payment and tell the user what happened. */
|
|
46
54
|
StopAndTellUser: "stop_and_tell_user",
|
|
47
55
|
/** Ask again only if the user still wants the payment after expiry. */
|
|
48
|
-
RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it"
|
|
56
|
+
RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it",
|
|
57
|
+
/**
|
|
58
|
+
* Stop and tell the user that the originating Safe needs to be funded or
|
|
59
|
+
* the agent's per-token allowance needs to be raised before the payment
|
|
60
|
+
* can succeed. A user approval will not fix this state on its own.
|
|
61
|
+
*/
|
|
62
|
+
FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance"
|
|
49
63
|
};
|
|
50
64
|
var AgentPaymentRail = {
|
|
51
65
|
/** Standard Haven payment from the user's Safe through an approved delegate allowance. */
|
|
@@ -76,7 +90,8 @@ var AgentPaymentPhaseDescriptions = {
|
|
|
76
90
|
[AgentPaymentPhase.FundingSent]: "The Haven funding leg was sent; the agent can continue the merchant/protocol leg.",
|
|
77
91
|
[AgentPaymentPhase.Rejected]: "The wallet owner rejected the request; the agent should stop and tell the user.",
|
|
78
92
|
[AgentPaymentPhase.Expired]: "The payment or approval request expired before completion.",
|
|
79
|
-
[AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure."
|
|
93
|
+
[AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure.",
|
|
94
|
+
[AgentPaymentPhase.InsufficientFunds]: "Pre-flight check determined the delegate balance plus the remaining on-chain allowance cannot cover the requested amount, so no payment was created. The originating Safe must be funded or the agent allowance raised before retrying."
|
|
80
95
|
};
|
|
81
96
|
var AgentPaymentNextActionDescriptions = {
|
|
82
97
|
[AgentPaymentNextAction.SignAndSubmitPayment]: "Sign with the delegate key and submit the payment to Haven.",
|
|
@@ -86,7 +101,8 @@ var AgentPaymentNextActionDescriptions = {
|
|
|
86
101
|
[AgentPaymentNextAction.WaitForUserToCompletePayment]: "Wait for the wallet owner to finish sending the approved funding payment.",
|
|
87
102
|
[AgentPaymentNextAction.RetryOriginalX402Request]: "Resume this payment id and retry the original x402 request with the merchant payment header.",
|
|
88
103
|
[AgentPaymentNextAction.StopAndTellUser]: "Stop retrying this payment and tell the user what happened.",
|
|
89
|
-
[AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry."
|
|
104
|
+
[AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry.",
|
|
105
|
+
[AgentPaymentNextAction.FundSafeOrRaiseAllowance]: "Stop and tell the user that the originating Safe needs to be funded or the agent allowance raised before the payment can succeed."
|
|
90
106
|
};
|
|
91
107
|
var AgentPaymentRailDescriptions = {
|
|
92
108
|
[AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
|
|
@@ -202,6 +218,7 @@ function verifySignature(hash, signature, expectedAddress) {
|
|
|
202
218
|
}
|
|
203
219
|
var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
|
|
204
220
|
var X402_IDEMPOTENCY_BUCKET_MS = 3e5;
|
|
221
|
+
var DECIMAL_ATOMIC_AMOUNT_RE = /^[0-9]+$/;
|
|
205
222
|
function decodeBase64Json(value, label) {
|
|
206
223
|
try {
|
|
207
224
|
return JSON.parse(atob(value));
|
|
@@ -209,6 +226,12 @@ function decodeBase64Json(value, label) {
|
|
|
209
226
|
throw new Error(`Failed to decode ${label}`);
|
|
210
227
|
}
|
|
211
228
|
}
|
|
229
|
+
function isPositiveDecimalAtomicAmount(value) {
|
|
230
|
+
return DECIMAL_ATOMIC_AMOUNT_RE.test(value) && BigInt(value) > 0n;
|
|
231
|
+
}
|
|
232
|
+
function optionAuthorizationAmount(option) {
|
|
233
|
+
return option.maxAmountRequired ?? option.amount;
|
|
234
|
+
}
|
|
212
235
|
function normalizePaymentOption(value) {
|
|
213
236
|
const candidate = value;
|
|
214
237
|
if (!candidate || typeof candidate !== "object" || typeof candidate.scheme !== "string" || typeof candidate.network !== "string" || typeof candidate.asset !== "string" || typeof candidate.payTo !== "string") {
|
|
@@ -216,6 +239,10 @@ function normalizePaymentOption(value) {
|
|
|
216
239
|
}
|
|
217
240
|
const amount = typeof candidate.amount === "string" ? candidate.amount : typeof candidate.maxAmountRequired === "string" ? candidate.maxAmountRequired : null;
|
|
218
241
|
if (!amount) return null;
|
|
242
|
+
if (!isPositiveDecimalAtomicAmount(amount)) return null;
|
|
243
|
+
if (candidate.maxAmountRequired !== void 0 && (typeof candidate.maxAmountRequired !== "string" || !isPositiveDecimalAtomicAmount(candidate.maxAmountRequired))) {
|
|
244
|
+
return null;
|
|
245
|
+
}
|
|
219
246
|
return {
|
|
220
247
|
scheme: candidate.scheme,
|
|
221
248
|
network: candidate.network,
|
|
@@ -316,11 +343,13 @@ function selectPaymentOption(accepts) {
|
|
|
316
343
|
for (const opt of accepts) {
|
|
317
344
|
if (opt.network in SUPPORTED_X402_NETWORKS) {
|
|
318
345
|
const networkTokens = NETWORK_TOKENS[opt.network];
|
|
319
|
-
if (networkTokens?.[opt.asset.toLowerCase()]
|
|
346
|
+
if (networkTokens?.[opt.asset.toLowerCase()] && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
|
|
347
|
+
return opt;
|
|
348
|
+
}
|
|
320
349
|
}
|
|
321
350
|
}
|
|
322
351
|
for (const opt of accepts) {
|
|
323
|
-
if (opt.network in SUPPORTED_X402_NETWORKS) {
|
|
352
|
+
if (opt.network in SUPPORTED_X402_NETWORKS && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
|
|
324
353
|
return opt;
|
|
325
354
|
}
|
|
326
355
|
}
|
|
@@ -329,14 +358,18 @@ function selectPaymentOption(accepts) {
|
|
|
329
358
|
function selectStandardPaymentOption(accepts) {
|
|
330
359
|
if (!accepts || accepts.length === 0) return null;
|
|
331
360
|
for (const opt of accepts) {
|
|
332
|
-
if (opt.scheme === "exact" && opt.network in STANDARD_X402_NETWORKS && opt.asset.toLowerCase() === BASE_USDC_ADDRESS) {
|
|
361
|
+
if (opt.scheme === "exact" && opt.network in STANDARD_X402_NETWORKS && opt.asset.toLowerCase() === BASE_USDC_ADDRESS && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
|
|
333
362
|
return opt;
|
|
334
363
|
}
|
|
335
364
|
}
|
|
336
365
|
return null;
|
|
337
366
|
}
|
|
338
367
|
function x402AuthorizationAmount(option) {
|
|
339
|
-
|
|
368
|
+
const amount = optionAuthorizationAmount(option);
|
|
369
|
+
if (!isPositiveDecimalAtomicAmount(amount)) {
|
|
370
|
+
throw new Error("Invalid x402 amount: must be a positive decimal atomic amount");
|
|
371
|
+
}
|
|
372
|
+
return amount;
|
|
340
373
|
}
|
|
341
374
|
function buildX402ExpectedMessage(context) {
|
|
342
375
|
return `Haven x402 expected context v1
|
|
@@ -1583,13 +1616,7 @@ var HavenClient = class {
|
|
|
1583
1616
|
paymentRequired.x402Version,
|
|
1584
1617
|
requirements
|
|
1585
1618
|
);
|
|
1586
|
-
|
|
1587
|
-
const payment = decodeBase64Json3(header);
|
|
1588
|
-
return btoa(JSON.stringify({
|
|
1589
|
-
x402Version: paymentRequired.x402Version,
|
|
1590
|
-
accepted: option,
|
|
1591
|
-
payload: payment.payload
|
|
1592
|
-
}));
|
|
1619
|
+
return header;
|
|
1593
1620
|
}
|
|
1594
1621
|
cacheX402Receipt(idempotencyKey, paymentHeader, receipt) {
|
|
1595
1622
|
const expiresAt = getPaymentHeaderValidBefore(paymentHeader);
|
|
@@ -2307,13 +2334,19 @@ var toolDescriptions = {
|
|
|
2307
2334
|
quoteX402: {
|
|
2308
2335
|
summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.",
|
|
2309
2336
|
behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior \u2014 Haven is not contacted.",
|
|
2310
|
-
nextActionGuidance: ""
|
|
2337
|
+
nextActionGuidance: "On success the returned quote is the input to haven_pay_x402_quote. Do not call the merchant again \u2014 Haven re-uses the captured request when paying."
|
|
2311
2338
|
},
|
|
2312
2339
|
payX402: {
|
|
2313
2340
|
summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
|
|
2314
2341
|
selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
|
|
2315
2342
|
behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.",
|
|
2316
|
-
nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming."
|
|
2343
|
+
nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the originating Safe is funded or the agent allowance raised \u2014 stop and tell the user the shortfall reported on the response."
|
|
2344
|
+
},
|
|
2345
|
+
payX402OneShot: {
|
|
2346
|
+
summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.",
|
|
2347
|
+
selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
|
|
2348
|
+
behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns an MPP machine-payment challenge instead of standard x402, the MPP payment path is used automatically. If the resource returns a non-402 status, returns it unchanged without contacting Haven.",
|
|
2349
|
+
nextActionGuidance: "If approval is needed, preserve the returned resume_state or paymentId and call the resume tool once nextAction=retry_original_x402_request. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the originating Safe is funded or the agent allowance raised \u2014 stop and tell the user the shortfall reported on the response."
|
|
2317
2350
|
},
|
|
2318
2351
|
resumeX402: {
|
|
2319
2352
|
summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.",
|
|
@@ -2323,7 +2356,7 @@ var toolDescriptions = {
|
|
|
2323
2356
|
quoteMpp: {
|
|
2324
2357
|
summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.",
|
|
2325
2358
|
behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only \u2014 Haven is not contacted.",
|
|
2326
|
-
nextActionGuidance: ""
|
|
2359
|
+
nextActionGuidance: "On success the returned quote is the input to haven_pay_mpp_challenge. Do not call the merchant again \u2014 Haven re-uses the captured request when paying."
|
|
2327
2360
|
},
|
|
2328
2361
|
payMpp: {
|
|
2329
2362
|
summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
|