uvd-x402-sdk 2.42.0 → 2.43.1

package/README.md

@@ -19,6 +19,7 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 - **Commerce Scheme**: `'commerce'` scheme alias for marketplace integrations (identical to `'escrow'` on-chain)
 - **`/accepts` Negotiation**: Discover facilitator capabilities before constructing payments
 - **Bazaar Discovery**: Register and discover paid resources across the x402 network
+- **Live Traffic Stream**: Subscribe to `GET /events` (SSE) for settlements as they happen — lossy live hint, not a ledger
 - **Facilitator Info**: Query version, supported networks, blacklist, and health
 
 ## Installation
@@ -1066,6 +1067,63 @@ console.log(stats.total, stats.visible, stats.byHealth.alive);
 
 Timestamps (`firstSeen`, `lastSeen`, `lastUpdated`, `health.lastChecked`) are Unix epoch **seconds**. Use `epochToDate()` to get a `Date`.
 
+## Live Traffic Stream (`GET /events`)
+
+The facilitator emits one Server-Sent Event per operation it handles, so you can
+render or react to live traffic without polling. Works in Node 18+ and browsers —
+it uses `fetch` and the response body stream rather than `EventSource`, so custom
+headers work too.
+
+```typescript
+import { streamTrafficEvents } from 'uvd-x402-sdk';
+
+for await (const event of streamTrafficEvents()) {
+  console.log(event.kind, event.network, event.ok, event.tx);
+}
+
+// Only settlements on the chains you care about. The facilitator has NO
+// server-side filter by network, so this runs client-side.
+const controller = new AbortController();
+const stream = streamTrafficEvents({
+  networks: ['base', 'polygon'],
+  kinds: ['settle'],
+  signal: controller.signal,
+});
+for await (const event of stream) console.log(event.tx, new Date(event.ts));
+```
+
+Three properties decide how you should use this:
+
+**It is lossy by design.** The facilitator will never slow down or fail a payment
+to keep an observer in sync, so an event you were not connected for is gone.
+Treat it as a live hint and use the chain as the source of truth — and note that
+*absence of events is not evidence that nothing happened*. On a quiet rail the
+only thing on the wire for minutes is a keepalive.
+
+**Failed operations are not published.** Only operations that resolved emit an
+event, so `ok: false` means "resolved and came back negative", never "blew up". A
+stream that looks healthy is not proof that the rail is.
+
+**Admission is bounded.** `/events` is public and unauthenticated, so it sheds
+with HTTP 503 + `Retry-After` at subscriber capacity, and returns 404 when the
+operator disabled it. Both throw `TrafficStreamError`, which carries `status` and
+`retryAfter`. Iteration does **not** reconnect on its own: reconnect policy
+belongs to you, because only you know whether a gap matters.
+
+> **Match the canonical network slug.** `network` is the name `/supported` uses,
+> which is not always the alias you may *send*. `skale` is accepted inbound, but
+> events always say `skale-base`. Keying on the alias silently drops every event
+> for that chain.
+
+| Field | Notes |
+|-------|-------|
+| `ts` | Unix epoch **milliseconds** (not seconds) |
+| `kind` | `'verify'` or `'settle'` |
+| `network` | Canonical slug, same as `/supported` |
+| `ok` | Resolved successfully? |
+| `payer` / `amount` / `asset` | Omitted in `minimal` detail mode |
+| `tx` | Present on `settle`, absent on `verify` — nothing settled yet |
+
 ## Facilitator Info
 
 Query the facilitator for version, supported networks, and compliance data.

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-import { O as X402Version, k as PaymentResult } from '../index-DBCFd6mO.mjs';
+import { X as X402Version, b as PaymentResult } from '../index-NDRI_c7e.mjs';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-CYIVd4xO.mjs';
 import '../wallet-0cX9Pw2F.mjs';
 

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { O as X402Version, k as PaymentResult } from '../index-DBCFd6mO.js';
+import { X as X402Version, b as PaymentResult } from '../index-NDRI_c7e.js';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-DTDixPzO.js';
 import '../wallet-0cX9Pw2F.js';
 

package/dist/backend/index.d.mts

@@ -1,5 +1,5 @@
 import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.mjs';
-import { w as X402Header, O as X402Version } from '../index-DBCFd6mO.mjs';
+import { e as X402Header, X as X402Version } from '../index-NDRI_c7e.mjs';
 
 /**
  * Payment requirements sent to the facilitator
@@ -93,6 +93,15 @@ interface PaymentAcceptance {
     network: string;
     asset: string;
     amount: string;
+    /**
+     * Payment scheme. REQUIRED by the facilitator's v2 `PaymentRequirementsV2`.
+     *
+     * Optional here only so existing callers keep compiling — when it is absent,
+     * `buildRequirementFromAcceptance` defaults it to `'exact'`. Do not treat its
+     * optionality as "the facilitator does not need it": an accepts[] entry that
+     * reaches a v2 client without a scheme is unpayable.
+     */
+    scheme?: string;
     payTo?: string;
     facilitator?: string;
     resource?: string;

package/dist/backend/index.d.ts

@@ -1,5 +1,5 @@
 import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.js';
-import { w as X402Header, O as X402Version } from '../index-DBCFd6mO.js';
+import { e as X402Header, X as X402Version } from '../index-NDRI_c7e.js';
 
 /**
  * Payment requirements sent to the facilitator
@@ -93,6 +93,15 @@ interface PaymentAcceptance {
     network: string;
     asset: string;
     amount: string;
+    /**
+     * Payment scheme. REQUIRED by the facilitator's v2 `PaymentRequirementsV2`.
+     *
+     * Optional here only so existing callers keep compiling — when it is absent,
+     * `buildRequirementFromAcceptance` defaults it to `'exact'`. Do not treat its
+     * optionality as "the facilitator does not need it": an accepts[] entry that
+     * reaches a v2 client without a scheme is unpayable.
+     */
+    scheme?: string;
     payTo?: string;
     facilitator?: string;
     resource?: string;

package/dist/backend/index.js

@@ -1425,7 +1425,9 @@ function buildRequirementFromAcceptance(accept, resource, version, defaults) {
     throw new Error("Payment accepts entries must include payTo");
   }
   return normalizeRequirementForVersion({
-    scheme: "exact",
+    // Honour a caller-supplied scheme; 'exact' is the default, not an override.
+    // Hardcoding it silently discarded 'escrow' / 'commerce' accepts.
+    scheme: accept.scheme ?? "exact",
     network: accept.network,
     maxAmountRequired: accept.amount,
     resource: accept.resource ?? defaults?.resource ?? resource,
@@ -1443,6 +1445,11 @@ function toPaymentAcceptance(requirements, facilitator) {
     network: requirements.network,
     asset: requirements.asset,
     amount: requirements.maxAmountRequired,
+    // scheme is REQUIRED by the facilitator's v2 PaymentRequirementsV2. Dropping it
+    // here produced an accepts[] entry that no v2 client could pay: the spec makes
+    // the client echo the accept verbatim, so the omission travelled downstream and
+    // died in deserialization with an error naming no field.
+    scheme: requirements.scheme,
     payTo: requirements.payTo,
     resource: requirements.resource,
     description: requirements.description,