@weftlabs/sdk 0.25.0 → 0.26.1

package/docs/FetchApi.md

@@ -14,7 +14,7 @@ All URIs are relative to *https://weft.network*
 
 Pay-and-fetch any URL (x402/MPP proxy)
 
-Universal x402/MPP fetch proxy. The caller provides a target `url`, a hard `max_cost_usd` ceiling, and optional `method` / `body` / `headers`. Weft:    1. Issues the request.   2. On `402 Payment Required`, selects a supported x402 or MPP challenge.   3. Compares the asking price to `max_cost_usd` and the      buyer\'s policy (`max_tx_usd`, daily/weekly limits).   4. Authorizes payment from the buyer\'s wallet on the selected rail.   5. Replays the request with the protocol-specific payment credential.   6. Streams the upstream artifact back, base64-encoded under       `body_base64`, with `paid_usd`, `held_usd`, `payment_status`,       `tx_hash`, and `protocol`. `paid_usd`      is \"0.00\" until the charge is CONFIRMED settled — a signed-but-      unsettled hold (the common case for x402, which settles      asynchronously) reports its amount in `held_usd` instead, never      in `paid_usd`.  Errors are structured with a stable `error` code, and each error response carries the buyer\'s `policy`, `balance`, and a `dashboard_url` so a CLI can render an actionable message without a second round-trip.  Account-scoped: the bearer must be a buyer-scoped API key, an OAuth access token carrying `fetch`, or a claimed `wbt_*` bearer.  **Forwarded headers:** the caller\'s `headers` are passed through to the upstream, except a denylist of hop-by-hop and Weft-internal headers (`host`, `authorization`, `cookie`, `proxy-authorization`, `x-forwarded-*`, `x-real-ip`, `x-payment`, `connection`, `upgrade`). Up to 32 headers, 4 KB of combined value bytes.
+Universal x402/MPP fetch proxy. The caller provides a target `url`, a hard `max_cost_usd` ceiling, and optional `method` / `body` / `headers`. Weft:    1. Issues the request.   2. On `402 Payment Required`, selects a supported x402 or MPP challenge.   3. Compares the asking price to `max_cost_usd` and the      buyer\'s policy (`max_tx_usd`, daily/weekly limits).   4. If an eligible mainnet MPP challenge finds its Tempo token short,      creates or adopts a buyer-owned Base-to-Tempo refill and returns      `409 FUNDING_PENDING` with `details.reason=funding_active`. If an      overlapping payment invalidates the balance observation before a      bridge is created, the same retryable response carries      `details.reason=balance_changed`. The caller retries the identical      fetch after `details.retry_after_seconds`; that later request      obtains a fresh challenge and reruns rail selection and all payment      controls.   5. Authorizes payment from the buyer\'s wallet on the selected rail.   6. Replays the request with the protocol-specific payment credential.   7. Streams the upstream artifact back, base64-encoded under       `body_base64`, with `paid_usd`, `held_usd`, `payment_status`,       `tx_hash`, and `protocol`. `paid_usd`      is \"0.00\" until the charge is CONFIRMED settled — a signed-but-      unsettled hold (the common case for x402, which settles      asynchronously) reports its amount in `held_usd` instead, never      in `paid_usd`.  Errors are structured with a stable `error` code, and each error response carries the buyer\'s `policy`, `balance`, and a `dashboard_url` so a CLI can render an actionable message without a second round-trip.  Account-scoped: the bearer must be a buyer-scoped API key, an OAuth access token carrying `fetch`, or a claimed `wbt_*` bearer.  **Forwarded headers:** the caller\'s `headers` are passed through to the upstream, except a denylist of hop-by-hop and Weft-internal headers (`host`, `authorization`, `cookie`, `proxy-authorization`, `x-forwarded-*`, `x-real-ip`, `x-payment`, `connection`, `upgrade`). Up to 32 headers, 4 KB of combined value bytes.
 
 ### Example
 
@@ -81,11 +81,11 @@ example().catch(console.error);
 | **401** | Unauthorized — missing or non-buyer-scoped API key |  -  |
 | **402** | Payment refused. `EXCEEDED_MAX_COST` (over the caller cap) or `INSUFFICIENT_BALANCE` (the buyer is genuinely short — `details.asset`, when present, names the exact token the failed check read). Both use `FetchErrorResponse`.  |  -  |
 | **403** | Policy violation, missing Crossmint payment permission (`PAYMENT_AUTHORIZATION_REQUIRED` — `details` carries the wallet-page URL where the authenticated user can enable payments), denylisted recipient, or a merchant challenge on a chain outside the wallet\'s own environment — a testnet wallet may not pay a mainnet challenge, nor the reverse (`WALLET_ENVIRONMENT_MISMATCH`; terminal, not retryable). All four use `FetchErrorResponse`. Alternatively an OAuth access token lacking the `fetch` scope (`InsufficientScopeResponse`, RFC 6750 `insufficient_scope`, with a `WWW-Authenticate` challenge). The two envelopes are disjoint; branch on the `error` value.  |  -  |
-| **409** | `IDEMPOTENCY_CONFLICT` — this buyer already used the supplied `Idempotency-Key` for a different fetch request. Generate a new key for the new operation; retry the original operation unchanged.  Or `WALLET_SETUP_INCOMPLETE` — the buyer\'s wallet has not been created yet, so there is nothing to pay from. `details.wallet_url` carries the page where the authenticated user finishes setup. No retry succeeds until they do.  Or `ACCOUNT_CLOSING` — account closure has started, so the wallet cannot reserve a new payment.  Or `DELIVERY_REPLAY_UNAVAILABLE` — the merchant already returned a successful response for this settled MPP payment, but Weft could not persist its bytes for replay. The merchant is not called again; `details.tx_hash` identifies the settled payment. All four use `FetchErrorResponse`.  |  -  |
+| **409** | `IDEMPOTENCY_CONFLICT` — this buyer already used the supplied `Idempotency-Key` for a different fetch request. Generate a new key for the new operation; retry the original operation unchanged.  Or `WALLET_SETUP_INCOMPLETE` — the buyer\'s wallet has not been created yet, so there is nothing to pay from. `details.wallet_url` carries the page where the authenticated user finishes setup. No retry succeeds until they do.  Or `ACCOUNT_CLOSING` — account closure has started, so the wallet cannot reserve a new payment.  Or `FUNDING_PENDING` — retry after `details.retry_after_seconds`. `details.reason` is `funding_active` when a buyer-owned Base-to-Tempo refill exists, or `balance_changed` when an overlapping payment invalidated the balance observation before funding could start.  Or `DELIVERY_REPLAY_UNAVAILABLE` — the merchant already returned a successful response for this settled MPP payment, but Weft could not persist its bytes for replay. The merchant is not called again; `details.tx_hash` identifies the settled payment. All five use `FetchErrorResponse`.  |  -  |
 | **413** | Upstream artifact exceeded the proxy\'s size cap. |  -  |
 | **422** | Invalid request fields, method, cost, body, headers, idempotency key, or URL. `UNSUPPORTED_ASSET` means the merchant requested an asset this wallet cannot settle. `UNSUPPORTED_PAYMENT_METHOD` means the MPP challenge requested a method Weft cannot execute.  |  -  |
 | **424** | `MERCHANT_RETURNED_NON_402` — the upstream merchant is at fault: it did not return a 402, or its 402 challenge was invalid. A 4xx (not 5xx) because Weft behaved correctly and the caller should act on `details.reason` (e.g. pick another merchant); it also keeps the error envelope intact through CDNs that replace 5xx bodies.  `PAID_DELIVERY_FAILED` — the MPP payment settled, but the merchant did not deliver a successful response. `details.tx_hash` identifies the settled payment; `details.merchant_status` is present when the merchant returned an HTTP response.  |  -  |
-| **502** | Settlement signing failed on Weft\'s side (`SETTLEMENT_FAILED`). `details.reason` carries the wallet-provider sentence and `details.protocol` names the rail it failed on (`x402` or `mpp`) — a 402 may announce both, and Weft picks one, so the rail is not derivable from the merchant or the URL. Absent only when the failure happened while building the credential, which already identifies its own rail.  |  -  |
+| **502** | Merchant connection failure (`MERCHANT_CONNECTION_FAILED`) or settlement signing failed on Weft\'s side (`SETTLEMENT_FAILED`). For merchant failures, `details.phase` identifies challenge or paid; paid requests may have moved funds. Reuse the same idempotency key. `details.reason` carries a stable payment sentence. `details.protocol` names a direct payment rail when that is safe and useful. It is absent for automatic-funding failures so provider, bridge, and retry details stay internal.  |  -  |
 | **504** | `MERCHANT_TIMEOUT` — the upstream merchant did not complete the challenge or paid request inside Weft\'s transport budget. `details.phase` names the request. When it is `paid`, `details.payment_may_have_moved` is true because the credential was already sent. Retry the identical operation with the same `Idempotency-Key`.  `SETTLEMENT_PENDING` — the payment was submitted and the wallet provider had not reached a terminal state before Weft\'s polling budget ran out. NOTHING is known to have failed: the charge may already have settled, so this is not `SETTLEMENT_FAILED` and the amount is not lost. `details.retry_with_same_idempotency_key` is `true`.  Retry the identical request shortly. Sending the same `Idempotency-Key` resumes the same provider operation; a caller that sends no key is also safe, because Weft resumes its own in-flight operation for the same merchant, amount and network rather than opening a second one. Either way the retry resolves the original payment instead of charging twice.  |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weftlabs/sdk",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Unified Weft SDK for the Weft API and x402 Facilitator",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",