@haven_ai/sdk 0.1.24-alpha.0 → 0.1.26-alpha.0

package/README.md

@@ -122,6 +122,66 @@ if (apiResponse.status === 402) {
 }
 ```
 
+### Idempotency: what the key guarantees, and what it costs
+
+**Omit `idempotencyKey` and the SDK synthesises one** from the merchant's
+resource URL and description, the payee, asset, amount, network, and a
+**5-minute time bucket**. Every one of those inputs except the bucket
+describes *the product*, so the guarantee is:
+
+> Repeated calls for the same product, at the same price, within the same
+> 5-minute bucket are **one payment**.
+
+That is what makes a retried HTTP request safe by default — a dropped
+connection or a re-run tool call cannot pay twice.
+
+**The cost is the flip side of the same rule.** The SDK cannot tell a retry
+from a *deliberate* second purchase of the same item: both re-fetch the 402
+and produce identical key material. So a genuine second purchase inside the
+window collapses onto the first payment. When that happens the SDK does not
+hand you a fresh authorization — the funds are already spent, and any
+authorization it minted would be unfundable. It throws
+`X402AlreadySettledError`, carrying the original receipt:
+
+```typescript
+import { X402AlreadySettledError } from '@haven_ai/sdk'
+
+try {
+  await haven.fetch('https://paid-api.example.com/data')
+} catch (err) {
+  if (err instanceof X402AlreadySettledError) {
+    // The FIRST payment's receipt — real, settled funds.
+    console.log(err.receipt.paymentId, err.receipt.txHash)
+    // 'settled'      — the delegate was checked on-chain and cannot fund again.
+    // 'unverifiable' — no chainRpcs entry for the chain, so it was not checked.
+    console.log(err.basis)
+  }
+}
+```
+
+**To buy the same item twice, pass distinct keys** — that is the supported
+way to say "this is a new purchase, not a retry":
+
+```typescript
+await haven.fetch(url, init, { idempotencyKey: `vpn-renewal:${orderId}` })
+```
+
+Configure `chainRpcs` for your chain. Without it the SDK cannot check the
+delegate's balance, so an accidental key collision refuses on the weaker
+`unverifiable` basis rather than risk issuing an authorization it cannot vouch
+for.
+
+**Resuming is not affected by that.** When you are following the documented
+approval flow — re-calling after a queued payment is approved, or calling
+`resumeAuthorizedX402({ paymentId })` — you named the payment, so an
+unverifiable balance lets the resume proceed as before. Only a balance
+verified *absent* refuses there. The stricter default applies solely to the
+case where two purchases collided on a key you did not choose.
+
+This applies to the **EIP-3009 funding-leg** scheme, which routes money
+through the delegate EOA. **erc7710 direct settlement is unaffected**: it has
+no funding leg and no delegate balance to exhaust.
+
 For agents that need to inspect the price before paying, use the quote-first
 path. `quoteX402()` probes the merchant and parses the HTTP 402 response, but it
 does not create a Haven payment, approval request, signature, or on-chain
@@ -445,6 +505,12 @@ try {
 }
 ```
 
+`X402AlreadySettledError` extends `HavenApiError` (status 409) and is the one
+error above that is **not** a failure to pay — it reports that the payment it
+describes *succeeded*, earlier. Handle it before the generic `HavenApiError`
+branch, and treat `err.receipt` as proof of purchase rather than retrying. See
+[Idempotency](#idempotency-what-the-key-guarantees-and-what-it-costs).
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -277,6 +277,17 @@ var X402UnexpectedStatusError = class extends HavenApiError {
     this.name = "X402UnexpectedStatusError";
   }
 };
+var X402AlreadySettledError = class extends HavenApiError {
+  constructor(message, receipt, basis) {
+    super(message, 409, void 0, receipt.paymentId);
+    this.receipt = receipt;
+    this.basis = basis;
+    this.name = "X402AlreadySettledError";
+  }
+  receipt;
+  basis;
+  x402ErrorCode = "already_settled";
+};
 var HavenPaymentStateError = class extends HavenApiError {
   constructor(message, statusCode, state, body) {
     super(message, statusCode, body, state.paymentId);
@@ -953,8 +964,8 @@ function createJsonRpcProvider(url) {
 function createWallet(privateKey, provider) {
   return new ethers.ethers.Wallet(privateKey, provider);
 }
-function createErc20Contract(address, abi, signer) {
-  return new ethers.ethers.Contract(address, abi, signer);
+function createErc20Contract(address, abi, runner) {
+  return new ethers.ethers.Contract(address, abi, runner);
 }
 
 // src/client.ts
@@ -1934,7 +1945,6 @@ var HavenClient = class {
     }
   }
   async authorizeStandardX402(paymentRequired, option, idempotencyKey) {
-    const paymentHeader = await this.createStandardX402Header(paymentRequired, option);
     const raw = await this.post("/x402", {
       url: paymentRequired.resource.url,
       payTo: this.delegateAddress,
@@ -1949,12 +1959,30 @@ var HavenClient = class {
       // declaration keeps both writers of the 3009 shape loud-by-default.
       settlementScheme: "eip3009"
     });
+    const state = this.paymentStateFromRaw("x402 payment", raw);
+    const executedReplay = raw.success && raw.tx_hash ? "idempotency-collision" : state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request ? "approval-resume" : null;
+    if (executedReplay) {
+      const canFund = await this.delegateCanFund(
+        raw.chain_id ?? state?.chainId ?? chainIdFromNetwork(option.network),
+        option.asset,
+        x402AuthorizationAmount(option)
+      );
+      const refuse = executedReplay === "idempotency-collision" ? canFund !== true : canFund === false;
+      if (refuse) {
+        const settledReceipt = state && executedReplay === "approval-resume" ? this.mapX402ReceiptFromStatus(paymentRequired, option, void 0, state) : this.mapX402ReceiptFromAuthorization(paymentRequired, option, void 0, raw);
+        throw new X402AlreadySettledError(
+          canFund === false ? "This x402 payment already settled \u2014 the delegate no longer holds the funds to authorize it again. To buy the same item a second time, pass a distinct `idempotencyKey`; the synthesised key intentionally collapses repeat calls for the same product within a 5-minute window so a retried request cannot pay twice." : "This x402 payment already settled, and whether the delegate can still fund a new authorization could not be verified (no `chainRpcs` entry for this chain). Refusing rather than issue an authorization that may be unfundable. To buy the same item a second time, pass a distinct `idempotencyKey`; to finish an interrupted payment, resume it by `paymentId`.",
+          settledReceipt,
+          canFund === false ? "settled" : "unverifiable"
+        );
+      }
+    }
+    const paymentHeader = await this.createStandardX402Header(paymentRequired, option);
     if (raw.success && raw.tx_hash) {
       const receipt2 = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw);
       this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
       return receipt2;
     }
-    const state = this.paymentStateFromRaw("x402 payment", raw);
     if (state?.nextAction === AgentPaymentNextAction.RetryOriginalX402Request) {
       const receipt2 = this.mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, state);
       this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
@@ -2135,6 +2163,18 @@ var HavenClient = class {
     if (cached && cached.expiresAt > Date.now()) return cached.receipt;
     const status = await this.getPaymentStatus(input.paymentId);
     this.assertCanResumeX402(status, input.paymentRequired, option);
+    const canFund = await this.delegateCanFund(
+      status.chainId ?? chainIdFromNetwork(option.network),
+      option.asset,
+      x402AuthorizationAmount(option)
+    );
+    if (canFund === false) {
+      throw new X402AlreadySettledError(
+        `x402 payment ${status.paymentId} has already settled \u2014 the delegate no longer holds the funds to authorize it again, so there is nothing left to resume.`,
+        this.mapX402ReceiptFromStatus(input.paymentRequired, option, void 0, status),
+        "settled"
+      );
+    }
     const paymentHeader = await this.createStandardX402Header(input.paymentRequired, option);
     const receipt = this.mapX402ReceiptFromStatus(input.paymentRequired, option, paymentHeader, status);
     this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
@@ -2465,8 +2505,18 @@ var HavenClient = class {
    * balance — otherwise it rejects with "Payment verification failed". The
    * SDK's local path already does this (see authorizeStandardX402); the hosted
    * split flow regressed when the 5→3 collapse removed the incidental
-   * inter-call latency that used to mask it. No-op when the funding tx hash or
-   * a chain RPC (chainRpcs[chainId]) is unavailable.
+   * inter-call latency that used to mask it.
+   *
+   * **NOT a no-op when the funding tx hash is absent** (#1508). The WAIT is
+   * skipped without a hash or a chain RPC, but the `GET /payments/:id` read
+   * below runs UNCONDITIONALLY — it is how the fallback hash and the chainId
+   * are obtained. That distinction is load-bearing: this method must never be
+   * called on a scheme with no funding leg, because the read itself fails once
+   * the intent reaches a status the backend maps to a non-2xx (`submitted` is a
+   * 409), turning a settled payment into a reported error. The previous wording
+   * here said "No-op when the funding tx hash ... is unavailable", and the
+   * hosted erc7710 path was written against that promise — see
+   * `deliverMerchantPayment`'s `noFundingLeg` option.
    */
   async ensureFundingConfirmed(paymentId, fundingTxHash) {
     const status = await this.getPaymentStatus(paymentId);
@@ -2475,8 +2525,10 @@ var HavenClient = class {
   async completeX402MerchantCall(input) {
     const evidenceContext = await this.resolveX402MerchantCompletionContext({
       paymentId: input.paymentId,
-      url: input.url
+      url: input.url,
+      noFundingLeg: input.noFundingLeg === true
     });
+    const fundingTxHash = evidenceContext.txHash;
     const shouldHandshakeMcp = isMcpUrl(input.url) || input.mcpTransport?.handshakeRequired === true;
     const x402Wallet = shouldHandshakeMcp ? await this.resolveX402WalletForMerchantCall() : this.x402PayerAddress();
     let mcpSessionId;
@@ -2500,33 +2552,37 @@ var HavenClient = class {
       body = text;
     }
     if (!surfaced.ok) {
-      await this.recordMerchantRetryRejected({
-        rail: "x402",
-        paymentId: evidenceContext.paymentId,
-        txHash: evidenceContext.txHash,
-        resourceUrl: evidenceContext.resourceUrl,
-        merchant: {
-          merchant_status: surfaced.status,
-          merchant_status_text: surfaced.statusText,
-          merchant_headers: Object.fromEntries(surfaced.headers.entries()),
-          merchant_body: text
-        },
-        details: {
-          merchant_to: evidenceContext.merchantAddress
-        }
-      });
+      if (!input.noFundingLeg && fundingTxHash) {
+        await this.recordMerchantRetryRejected({
+          rail: "x402",
+          paymentId: evidenceContext.paymentId,
+          txHash: fundingTxHash,
+          resourceUrl: evidenceContext.resourceUrl,
+          merchant: {
+            merchant_status: surfaced.status,
+            merchant_status_text: surfaced.statusText,
+            merchant_headers: Object.fromEntries(surfaced.headers.entries()),
+            merchant_body: text
+          },
+          details: {
+            merchant_to: evidenceContext.merchantAddress
+          }
+        });
+      }
     } else {
-      await this.reportMachinePaymentEvidence({
-        paymentId: evidenceContext.paymentId,
-        rail: "x402",
-        txHash: evidenceContext.txHash,
-        resourceUrl: evidenceContext.resourceUrl,
-        merchantStatus: surfaced.status,
-        paymentProofHeaderName: "X-PAYMENT",
-        paymentProofHeader: input.paymentHeader,
-        protocolReceiptHeaderName: protocolReceiptHeader ? "PAYMENT-RESPONSE" : void 0,
-        protocolReceiptHeader
-      });
+      if (!input.noFundingLeg && fundingTxHash) {
+        await this.reportMachinePaymentEvidence({
+          paymentId: evidenceContext.paymentId,
+          rail: "x402",
+          txHash: fundingTxHash,
+          resourceUrl: evidenceContext.resourceUrl,
+          merchantStatus: surfaced.status,
+          paymentProofHeaderName: "X-PAYMENT",
+          paymentProofHeader: input.paymentHeader,
+          protocolReceiptHeaderName: protocolReceiptHeader ? "PAYMENT-RESPONSE" : void 0,
+          protocolReceiptHeader
+        });
+      }
       await this.reportMerchantReceipt(evidenceContext.paymentId, surfaced);
     }
     return {
@@ -2572,11 +2628,11 @@ var HavenClient = class {
         status
       );
     }
-    const readyForMerchantCompletion = status.nextAction === AgentPaymentNextAction.RetryOriginalX402Request || status.kind === "payment_intent" && status.status === "confirmed" && status.phase === AgentPaymentPhase.PaymentConfirmed && status.nextAction === AgentPaymentNextAction.None;
+    const readyForMerchantCompletion = input.noFundingLeg ? status.kind === "payment_intent" && status.status === "submitted" : status.nextAction === AgentPaymentNextAction.RetryOriginalX402Request || status.kind === "payment_intent" && status.status === "confirmed" && status.phase === AgentPaymentPhase.PaymentConfirmed && status.nextAction === AgentPaymentNextAction.None;
     if (!readyForMerchantCompletion) {
       throw new HavenPaymentStateError(status.message, PAYMENT_STATE_STATUS_CODES[status.status] ?? 409, status);
     }
-    if (!status.txHash) {
+    if (!input.noFundingLeg && !status.txHash) {
       throw new HavenApiError(
         `x402 payment ${status.paymentId} is ready for merchant completion but has no Haven transaction hash.`,
         502,
@@ -2846,6 +2902,45 @@ var HavenClient = class {
       );
     }
   }
+  /**
+   * Can the delegate EOA still fund an authorization for `amountAtomic`?
+   *
+   * #1521: the only question that separates a legitimate resume (funding
+   * confirmed, merchant never paid — the delegate still holds the money) from
+   * a replayed settled payment (funding confirmed, merchant paid, delegate
+   * spent). The intent's own `status: 'confirmed'` is identical in both.
+   *
+   * The balance is asked of the CHAIN rather than of Haven's bookkeeping on
+   * purpose: the merchant-settlement evidence record is written by this SDK
+   * *after* the merchant call, so a client that dies between the two leaves
+   * the backend believing the merchant was never paid — the exact case the
+   * discriminator has to get right. The chain cannot be behind in that way.
+   *
+   * Returns `null` — never a guess — when `chainRpcs` has no entry for the
+   * chain or the read fails. Callers must treat that as "unverifiable", not
+   * as "funded".
+   */
+  async delegateCanFund(chainId, tokenAddress, amountAtomic, timeoutMs = 1e4) {
+    if (!chainId || !this.delegateAddress) return null;
+    const rpcUrl = this.chainRpcs[chainId];
+    if (!rpcUrl) return null;
+    try {
+      const provider = createJsonRpcProvider(rpcUrl);
+      const token = createErc20Contract(
+        tokenAddress,
+        ["function balanceOf(address) view returns (uint256)"],
+        provider
+      );
+      const balance = await Promise.race([
+        token.balanceOf(this.delegateAddress),
+        new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs).unref?.())
+      ]);
+      if (balance === null) return null;
+      return balance >= BigInt(amountAtomic);
+    } catch {
+      return null;
+    }
+  }
   throwIfNonSignableAuthorizationState(label, raw) {
     if (raw.status === "pending_signature") return;
     this.throwPaymentStateError(label, raw);
@@ -4066,6 +4161,7 @@ exports.SWEEP_BASE_SEPOLIA_USDC_ADDRESS = SWEEP_BASE_SEPOLIA_USDC_ADDRESS;
 exports.SWEEP_BASE_USDC_ADDRESS = SWEEP_BASE_USDC_ADDRESS;
 exports.SignerRefusalCode = SignerRefusalCode;
 exports.TRANSFER_WITH_AUTHORIZATION_TYPES = TRANSFER_WITH_AUTHORIZATION_TYPES;
+exports.X402AlreadySettledError = X402AlreadySettledError;
 exports.X402PaymentHeaderValidationError = X402PaymentHeaderValidationError;
 exports.X402UnexpectedStatusError = X402UnexpectedStatusError;
 exports.X402_MAX_AUTHORIZATION_WINDOW_SECONDS = X402_MAX_AUTHORIZATION_WINDOW_SECONDS;