uvd-x402-sdk 2.45.0 → 2.46.0

package/dist/index.d.mts

@@ -189,6 +189,20 @@ interface TrafficEvent {
     description?: string;
     /** Payment scheme: `exact`, `escrow`, `commerce`, `upto`. */
     scheme?: string;
+    /**
+     * Why the operation failed, as a BOUNDED CATEGORY — never the error text.
+     *
+     * Present only on operations that errored, and only where the operator set
+     * `X402_EVENTS_PUBLISH_FAILURES=true`. A closed set (`contract_revert`,
+     * `invalid_signature`, `insufficient_funds`, `invalid_timing`,
+     * `blocked_address`, …, `other`) precisely so it can never carry an address
+     * or an RPC URL.
+     *
+     * Note the distinction it makes visible: `ok: false` with no `error` means the
+     * operation RESOLVED and came back negative; `error` set means it blew up.
+     * Before this existed the second case produced no event at all.
+     */
+    error?: string;
 }
 /** Raised when the stream cannot be opened. Carries the HTTP status. */
 declare class TrafficStreamError extends Error {

package/dist/index.d.ts

@@ -189,6 +189,20 @@ interface TrafficEvent {
     description?: string;
     /** Payment scheme: `exact`, `escrow`, `commerce`, `upto`. */
     scheme?: string;
+    /**
+     * Why the operation failed, as a BOUNDED CATEGORY — never the error text.
+     *
+     * Present only on operations that errored, and only where the operator set
+     * `X402_EVENTS_PUBLISH_FAILURES=true`. A closed set (`contract_revert`,
+     * `invalid_signature`, `insufficient_funds`, `invalid_timing`,
+     * `blocked_address`, …, `other`) precisely so it can never carry an address
+     * or an RPC URL.
+     *
+     * Note the distinction it makes visible: `ok: false` with no `error` means the
+     * operation RESOLVED and came back negative; `error` set means it blew up.
+     * Before this existed the second case produced no event at all.
+     */
+    error?: string;
 }
 /** Raised when the stream cannot be opened. Carries the HTTP status. */
 declare class TrafficStreamError extends Error {

package/dist/index.js

@@ -2489,6 +2489,7 @@ function parseTrafficEvent(frame) {
   if (typeof raw.payTo === "string") event.payTo = raw.payTo;
   if (typeof raw.description === "string") event.description = raw.description;
   if (typeof raw.scheme === "string") event.scheme = raw.scheme;
+  if (typeof raw.error === "string") event.error = raw.error;
   return event;
 }
 function matchesFilters(event, options) {
@@ -2833,6 +2834,57 @@ var FacilitatorClient = class {
     }
     return await response.json();
   }
+  /**
+   * Aggregated totals per network and asset (`GET /api/stats`).
+   *
+   * **An index, not a ledger.** Records are written best-effort AFTER
+   * settlement, so an outage loses rows while payments proceed — verify
+   * anything that matters against the transaction hash. Counting starts when
+   * the operator enabled the store, so earlier operations are UNKNOWN, not
+   * zero. And unless `X402_EVENTS_PUBLISH_FAILURES=true`, operations that ERROR
+   * are not recorded at all: a 100% success rate means "no failures were
+   * recorded".
+   *
+   * `volumeAtomic` is a STRING (u256-shaped; a JS number loses precision above
+   * 2^53) and each row carries its own `decimals`. **Use that, never a
+   * constant** — USDC is 6 decimals nearly everywhere and 18 on BSC, so scaling
+   * by 6 there overstates volume by 10^12. `decimals` is null when the asset is
+   * unrecognised; render the atomic value rather than guessing a scale.
+   */
+  async getStats() {
+    const response = await fetch(`${this.baseUrl}/api/stats`, { method: "GET" });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`GET /api/stats failed: ${response.status} - ${errorText}`);
+    }
+    return await response.json();
+  }
+  /**
+   * Recent recorded operations, newest first (`GET /transactions`).
+   *
+   * There is **no pagination and no cursor**: this returns the newest N,
+   * walking back at most 30 days. With 10,000 rows you get the newest 200, not
+   * page one of fifty. `limit` is clamped to 200 by the facilitator.
+   *
+   * `network` matches the canonical slug `/supported` uses, which is not always
+   * the alias you may send — `skale` is accepted inbound but records say
+   * `skale-base`.
+   */
+  async getTransactions(options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    if (options.network) params.set("network", options.network);
+    const query = params.toString();
+    const response = await fetch(
+      `${this.baseUrl}/transactions${query ? `?${query}` : ""}`,
+      { method: "GET" }
+    );
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`GET /transactions failed: ${response.status} - ${errorText}`);
+    }
+    return await response.json();
+  }
   /**
    * Get the facilitator's blocked/sanctioned addresses
    *