@weftlabs/sdk 0.30.0 → 0.31.0

package/dist/index.mjs

@@ -1889,6 +1889,9 @@ var FetchErrorResponseErrorEnum = {
   UnknownParameter: "UNKNOWN_PARAMETER",
   InvalidUrl: "INVALID_URL",
   InvalidMaxCostUsd: "INVALID_MAX_COST_USD",
+  InvalidAllowTempoRefill: "INVALID_ALLOW_TEMPO_REFILL",
+  InvalidMaxTotalCostUsd: "INVALID_MAX_TOTAL_COST_USD",
+  IncompatibleFetchControls: "INCOMPATIBLE_FETCH_CONTROLS",
   UnsupportedMethod: "UNSUPPORTED_METHOD",
   InvalidBody: "INVALID_BODY",
   InvalidHeaders: "INVALID_HEADERS",
@@ -1896,6 +1899,7 @@ var FetchErrorResponseErrorEnum = {
   IdempotencyConflict: "IDEMPOTENCY_CONFLICT",
   AccountClosing: "ACCOUNT_CLOSING",
   ExceededMaxCost: "EXCEEDED_MAX_COST",
+  TotalCostUnverifiable: "TOTAL_COST_UNVERIFIABLE",
   FundingPending: "FUNDING_PENDING",
   InsufficientBalance: "INSUFFICIENT_BALANCE",
   PaymentAuthorizationRequired: "PAYMENT_AUTHORIZATION_REQUIRED",
@@ -2080,6 +2084,8 @@ function FetchRequestFromJSONTyped(json, ignoreDiscriminator) {
   return {
     "url": json["url"],
     "maxCostUsd": json["max_cost_usd"] == null ? void 0 : json["max_cost_usd"],
+    "allowTempoRefill": json["allow_tempo_refill"] == null ? void 0 : json["allow_tempo_refill"],
+    "maxTotalCostUsd": json["max_total_cost_usd"] == null ? void 0 : json["max_total_cost_usd"],
     "method": json["method"] == null ? void 0 : json["method"],
     "body": json["body"] == null ? void 0 : FetchRequestBodyFromJSON(json["body"]),
     "headers": json["headers"] == null ? void 0 : json["headers"],
@@ -2098,6 +2104,8 @@ function FetchRequestToJSONTyped(value, ignoreDiscriminator = false) {
   return {
     "url": value["url"],
     "max_cost_usd": value["maxCostUsd"],
+    "allow_tempo_refill": value["allowTempoRefill"],
+    "max_total_cost_usd": value["maxTotalCostUsd"],
     "method": value["method"],
     "body": FetchRequestBodyToJSON(value["body"]),
     "headers": value["headers"],
@@ -4602,7 +4610,7 @@ var DocumentationApi = class extends BaseAPI {
 // src/generated/apis/FetchApi.ts
 var FetchApi = class extends BaseAPI {
   /**
-   * 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.
+   * Universal x402/MPP fetch proxy. The caller provides a target `url`, a merchant-principal `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 refill is allowed and 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`.  **Opt-in safety controls:** `allow_tempo_refill: false` prevents this request from creating, adopting, or enqueueing a Base-to-Tempo bridge. A Tempo shortfall returns `402 INSUFFICIENT_BALANCE`; unrelated bridges and their jobs remain unchanged. `access_method_id` is advisory and does not enforce a payment rail.  `max_total_cost_usd` is an all-in ceiling covering merchant principal, network gas, provider fees, and prerequisite buyer-paid operations. It disables refill; explicitly combining it with `allow_tempo_refill: true` returns `422 INCOMPATIBLE_FETCH_CONTROLS`. Current wallet integrations provide no supported binding all-in fee guarantee. Therefore all-in requests return `402 TOTAL_COST_UNVERIFIABLE` before payment preparation, approval, reservation, or refill. This also refuses recovery of older payments and SIWX wallet signing; it admits no positive paid route. Increasing the ceiling does not resolve missing fee authority.  Omitted controls preserve existing behavior. Ordinary non-402 merchant responses retain `MERCHANT_RETURNED_NON_402`. Stored-result replay is historical payment information, not a new bounded authorization.  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.
    * Pay-and-fetch any URL (x402/MPP proxy)
    */
   async fetchRaw(requestParameters, initOverrides) {
@@ -4636,7 +4644,7 @@ var FetchApi = class extends BaseAPI {
     return new JSONApiResponse(response, (jsonValue) => FetchResponseFromJSON(jsonValue));
   }
   /**
-   * 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.
+   * Universal x402/MPP fetch proxy. The caller provides a target `url`, a merchant-principal `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 refill is allowed and 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`.  **Opt-in safety controls:** `allow_tempo_refill: false` prevents this request from creating, adopting, or enqueueing a Base-to-Tempo bridge. A Tempo shortfall returns `402 INSUFFICIENT_BALANCE`; unrelated bridges and their jobs remain unchanged. `access_method_id` is advisory and does not enforce a payment rail.  `max_total_cost_usd` is an all-in ceiling covering merchant principal, network gas, provider fees, and prerequisite buyer-paid operations. It disables refill; explicitly combining it with `allow_tempo_refill: true` returns `422 INCOMPATIBLE_FETCH_CONTROLS`. Current wallet integrations provide no supported binding all-in fee guarantee. Therefore all-in requests return `402 TOTAL_COST_UNVERIFIABLE` before payment preparation, approval, reservation, or refill. This also refuses recovery of older payments and SIWX wallet signing; it admits no positive paid route. Increasing the ceiling does not resolve missing fee authority.  Omitted controls preserve existing behavior. Ordinary non-402 merchant responses retain `MERCHANT_RETURNED_NON_402`. Stored-result replay is historical payment information, not a new bounded authorization.  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.
    * Pay-and-fetch any URL (x402/MPP proxy)
    */
   async fetch(requestParameters, initOverrides) {
@@ -4877,6 +4885,26 @@ var SearchApi = class extends BaseAPI {
 };
 
 // src/error.ts
+var PRE_SIGN_FETCH_CODES = /* @__PURE__ */ new Set([
+  "EXCEEDED_MAX_COST",
+  "MERCHANT_RETURNED_NON_402",
+  "INSUFFICIENT_BALANCE",
+  "DENYLISTED_RECIPIENT",
+  "WALLET_ENVIRONMENT_MISMATCH",
+  "UNSUPPORTED_ASSET",
+  "INVALID_REQUEST",
+  "UNKNOWN_PARAMETER",
+  "INVALID_URL",
+  "INVALID_MAX_COST_USD",
+  "UNSUPPORTED_METHOD",
+  "INVALID_BODY",
+  "INVALID_HEADERS",
+  "INVALID_IDEMPOTENCY_KEY"
+]);
+function fetchCharge(status, code) {
+  const preSign = PRE_SIGN_FETCH_CODES.has(code) || code.startsWith("POLICY_VIOLATION_");
+  return status >= 400 && status < 500 && preSign ? "none" : "possible";
+}
 var WeftError = class extends Error {
   constructor(options) {
     super(options.message);
@@ -4886,19 +4914,32 @@ var WeftError = class extends Error {
     this.requestId = options.requestId;
     this.retryable = options.retryable;
     this.details = options.details;
+    this.charge = options.charge ?? "possible";
   }
 };
-async function normalizeWeftError(error) {
+async function normalizeWeftError(error, paid = false) {
   if (error instanceof FetchError) {
     return new WeftError({
       status: 0,
       code: "NETWORK_ERROR",
       message: `Network failure before a Weft API response: ${error.cause?.message ?? error.message}`,
       retryable: true,
-      details: error.cause
+      details: error.cause,
+      charge: paid ? "possible" : "none"
+    });
+  }
+  if (!(error instanceof ResponseError)) {
+    if (!paid || error instanceof WeftError) return error;
+    return new WeftError({
+      status: 0,
+      code: "RESPONSE_DECODE_ERROR",
+      message: "Weft API returned a fetch response that could not be decoded",
+      // A replay returns the same body; reconcile instead of retrying.
+      retryable: false,
+      details: error,
+      charge: "possible"
     });
   }
-  if (!(error instanceof ResponseError)) return error;
   let details;
   try {
     details = await error.response.json();
@@ -4908,13 +4949,15 @@ async function normalizeWeftError(error) {
   const body = details;
   const nested = typeof body?.error === "object" ? body.error : void 0;
   const status = error.response.status;
+  const code = nested?.code ?? body?.code ?? (typeof body?.error === "string" ? body.error : `HTTP_${status}`);
   return new WeftError({
     status,
-    code: nested?.code ?? body?.code ?? (typeof body?.error === "string" ? body.error : `HTTP_${status}`),
+    code,
     message: nested?.message ?? body?.message ?? `Weft API returned HTTP ${status}`,
     requestId: nested?.request_id ?? body?.request_id ?? error.response.headers.get("x-request-id") ?? void 0,
     retryable: status === 429 || status >= 500,
-    details
+    details,
+    charge: paid ? fetchCharge(status, String(code)) : "none"
   });
 }
 
@@ -4952,11 +4995,11 @@ var WeftClient = class {
     this.fetches = new FetchApi(configuration);
     this.purchaseHistory = new PurchasesApi(configuration);
   }
-  async call(operation) {
+  async call(operation, paid = false) {
     try {
       return await operation();
     } catch (error) {
-      throw await normalizeWeftError(error);
+      throw await normalizeWeftError(error, paid);
     }
   }
   me() {
@@ -4975,12 +5018,27 @@ var WeftClient = class {
     if (!options.idempotencyKey.trim()) {
       throw new Error("idempotencyKey is required");
     }
+    if (!/^[!-~]{1,255}$/.test(options.idempotencyKey)) {
+      throw new Error(
+        "idempotencyKey must be 1-255 visible ASCII characters without spaces"
+      );
+    }
+    const fetchRequest = request.body != null && typeof request.body === "object" ? { ...request, body: JSON.stringify(request.body) } : request;
     return this.call(
       () => this.fetches.fetch({
-        fetchRequest: request,
+        fetchRequest,
         idempotencyKey: options.idempotencyKey
-      })
-    );
+      }),
+      true
+    ).then(async (response) => {
+      if (typeof response?.status !== "number") {
+        throw await normalizeWeftError(
+          new Error("unreadable fetch response"),
+          true
+        );
+      }
+      return response;
+    });
   }
   purchases(options = {}) {
     return this.call(() => this.purchaseHistory.listPurchases(options));