@haven_ai/sdk 0.0.0-dev.202609141609.ad8a780 → 0.0.0-dev.202609141754.2199891

package/dist/index.cjs

@@ -136,8 +136,11 @@ var AgentPaymentNextAction = {
    * first appears. Poll {@link CheckStatusLater}'s tool
    * (`haven_get_payment_status`) once more, roughly two minutes later; if it
    * still shows no evidence, tell the user the goods were delivered but
-   * Haven holds no verified settlement evidence for this payment. There is
-   * no tool that reports a settlement transaction hash for this scheme —
+   * Haven holds no verified settlement evidence for this payment. If the
+   * agent holds the merchant's real settlement transaction hash (from
+   * `PAYMENT-RESPONSE`'s `transaction` field, or a prior settle/complete
+   * result's `settlement_tx_hash`), report it with the hosted
+   * `haven_report_settlement_evidence` tool instead of waiting —
    * `haven_report_x402_outcome` takes no hash and refuses a non-`confirmed`
    * intent.
    */
@@ -241,7 +244,7 @@ var AgentPaymentNextActionDescriptions = {
   [AgentPaymentNextAction.FundSafeOrRaiseAllowance]: "Stop and tell the user that the account needs to be funded or the agent budget raised before the payment can succeed.",
   [AgentPaymentNextAction.RetryWithExplicitContext]: "Retry the same tool call, this time passing merchant_url, tool_name, arguments, and mcp_transport explicitly \u2014 the server had no stored context to rehydrate for this payment id.",
   [AgentPaymentNextAction.SweepStrandedFunds]: "Tell the user that funds may be stranded in the delegate wallet and prompt them to initiate a sweep in Haven to return them to the originating account.",
-  [AgentPaymentNextAction.AwaitingSettlementEvidence]: "The settlement window passed with no verified on-chain evidence yet. Haven's settlement sweep may still attribute it within about two minutes \u2014 poll getPaymentStatus once more, then tell the user the goods were delivered but unverified if it still shows nothing."
+  [AgentPaymentNextAction.AwaitingSettlementEvidence]: "The settlement window passed with no verified on-chain evidence yet. If you hold the merchant's real settlement transaction hash, report it with haven_report_settlement_evidence. Otherwise, Haven's settlement sweep may still attribute it within about two minutes \u2014 poll getPaymentStatus once more, then tell the user the goods were delivered but unverified if it still shows nothing."
 };
 var AgentPaymentFailureCodeDescriptions = {
   [AgentPaymentFailureCode.PriceExceedsMax]: "The merchant-authoritative x402 amount exceeds the caller's max_amount cap. No funding transfer was created; ask the user before retrying with a larger cap.",
@@ -385,6 +388,17 @@ var HavenSigningError = class extends HavenError {
     this.name = "HavenSigningError";
   }
 };
+var HavenZeroSettlementHashError = class extends HavenError {
+  constructor(paymentId) {
+    super(
+      "settlement_tx_hash is the zero hash (0x00\u202600), which is never a real settlement transaction \u2014 refused before any report was sent.",
+      "ZERO_SETTLEMENT_HASH",
+      400,
+      paymentId
+    );
+    this.name = "HavenZeroSettlementHashError";
+  }
+};
 var SignerRefusalCode = {
   /** `SUPPORTED_X402_EXPECTED_VERSIONS` in `@haven_ai/signer` does not include the received version. */
   UnsupportedExpectedContextVersion: "UNSUPPORTED_EXPECTED_CONTEXT_VERSION",
@@ -2957,6 +2971,39 @@ var MerchantCompletion = class {
       }
     }
   }
+  /**
+   * #2972: report the merchant's REAL settlement transaction hash for an
+   * erc7710 x402 payment out of band — the remedy #2970's guidance could not
+   * name, because no hosted tool accepted a hash. An agent reaches this after
+   * `haven_settle_mcp_tool` / `haven_complete_mcp_tool` answered
+   * `DELIVERED_UNSETTLED` or `SETTLEMENT_PENDING`, or after
+   * `haven_get_payment_status` reports `awaiting_settlement_evidence` — in
+   * every one of those cases the agent may be holding the merchant's own
+   * `PAYMENT-RESPONSE.transaction` while Haven has nothing.
+   *
+   * Reuses `reportEvidence` — same backend seam
+   * (`POST /machine-payments/evidence` → `observeErc7710Settlement`,
+   * fail-closed — see `settlement-observed.ts`), same three-outcome contract.
+   * `resourceUrl` and `merchantStatus` are omitted: this call has no fresh
+   * merchant HTTP exchange to read either from, and both are optional at the
+   * backend (see the parameter doc on `reportEvidence`).
+   *
+   * The zero hash is refused HERE, client-side, before any network call —
+   * never posted. `isZeroSettlementTxHash` is the same recognizer the #2970
+   * gate uses, so a caller cannot "fix" a missing hash by reporting the demo
+   * merchant's own marker and getting a different verdict than the settle
+   * path already gave it.
+   */
+  async reportSettlementEvidence(paymentId, settlementTxHash) {
+    if (isZeroSettlementTxHash(settlementTxHash)) {
+      throw new HavenZeroSettlementHashError(paymentId);
+    }
+    return this.reportEvidence({
+      paymentId,
+      rail: "x402",
+      txHash: settlementTxHash
+    });
+  }
 };
 function isZeroSettlementTxHash(hash) {
   return typeof hash === "string" && /^0x0+$/i.test(hash);
@@ -3947,6 +3994,19 @@ var HavenClient = class {
   async reportX402MerchantOutcome(input) {
     return await this.merchantCompletion.reportMerchantOutcome(input);
   }
+  /**
+   * #2972: report the merchant's real settlement transaction hash for an
+   * erc7710 x402 payment — the remedy for `DELIVERED_UNSETTLED` /
+   * `SETTLEMENT_PENDING` / `awaiting_settlement_evidence` when the agent
+   * holds the hash (`PAYMENT-RESPONSE.transaction`, or a prior settle/
+   * complete result's `settlement_tx_hash`) and Haven does not. See
+   * `MerchantCompletion.reportSettlementEvidence` for the fail-closed
+   * verification this posts into (`observeErc7710Settlement`) and the
+   * client-side zero-hash refusal.
+   */
+  async reportSettlementEvidence(paymentId, settlementTxHash) {
+    return await this.merchantCompletion.reportSettlementEvidence(paymentId, settlementTxHash);
+  }
   /**
    * GET /x402/:id/merchant-call-context — the settle-leg twin of #1263's
    * sign-context fetch (#1307). Re-serves the stored merchant MCP-tool call
@@ -4183,6 +4243,11 @@ var toolDescriptions = {
     selectionGuidance: "Use this for plain transfers \u2014 refunding a user, paying a freelancer, topping up a co-agent's wallet, or moving funds between addresses. Do NOT use for x402 paid endpoints \u2014 use haven_pay_x402 instead. Do NOT use for read-only allowance, budget, or what-can-I-spend questions \u2014 use haven_get_allowances.",
     behavior: "Sends the requested amount by redeeming the agent's on-chain budget delegation, account to recipient with no funding leg. Budget, recipient and expiry are enforced on-chain while the transfer is prepared, so a request outside them is declined before any money moves and before the agent is asked to sign \u2014 it is never queued for a human to approve later. The agent's signing key signs the account's typed data; Haven never receives the key.",
     nextActionGuidance: "On a decline, report the reason to the user and ask them to grant or raise the budget in Haven \u2014 there is nothing to poll and no approval will arrive. After a successful send, poll haven_get_payment_status until nextAction=none."
+  },
+  reportSettlementEvidence: {
+    summary: "Report an erc7710 payment's real settlement transaction hash so Haven can verify it on-chain and confirm the payment.",
+    behavior: "Pass payment_id and settlement_tx_hash (0x + 64 hex chars) \u2014 from PAYMENT-RESPONSE or a prior settlement_tx_hash. Haven verifies on-chain before confirming; a zero, mismatched, or reverted hash is refused. Your own payments only.",
+    nextActionGuidance: "code DELIVERED_UNSETTLED: did not verify, do not retry \u2014 poll haven_get_payment_status. code SETTLEMENT_PENDING (retryable:true): not mined or RPC unreachable \u2014 report the same hash again shortly."
   }
 };
 
@@ -4944,6 +5009,7 @@ exports.HavenPaymentStateError = HavenPaymentStateError;
 exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
 exports.HavenUnsupportedSignerVersionError = HavenUnsupportedSignerVersionError;
+exports.HavenZeroSettlementHashError = HavenZeroSettlementHashError;
 exports.MERCHANT_DISCOVERY_PATHS = MERCHANT_DISCOVERY_PATHS;
 exports.MerchantTimeoutError = MerchantTimeoutError;
 exports.RECEIPT_VERSION = RECEIPT_VERSION;