uvd-x402-sdk 2.41.0 → 2.43.0

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
@@ -1014,34 +1015,115 @@ The facilitator's `/supported` endpoint advertises both `'escrow'` and `'commerc
 
 Register and discover paid x402 resources across the network.
 
+The Bazaar is served by the facilitator itself under `/discovery/*`. No API key, no separate host.
+
 ```typescript
-import { BazaarClient } from 'uvd-x402-sdk/backend';
+import { BazaarClient, isAlive } from 'uvd-x402-sdk/backend';
 
-const bazaar = new BazaarClient({ apiKey: 'your-api-key' });
+const bazaar = new BazaarClient();
 
-// Discover resources
-const results = await bazaar.discover({
-  category: 'ai',
-  network: 'base',
-  maxPrice: '0.10',
+// List resources. Every filter is applied server-side over the whole catalog,
+// so `pagination.total` is the real number of matches -- filtering one page
+// locally is not the same thing and will under-report.
+const page = await bazaar.listResources({
+  network: 'eip155:8453',
+  health: 'alive',   // only endpoints a probe actually reached
+  tier: 'vip',       // first_party | vip | verified | listed
+  limit: 20,
 });
 
-for (const resource of results.resources) {
-  console.log(`${resource.name}: ${resource.url}`);
+for (const r of page.items) {
+  console.log(r.url, r.health?.status, `${r.health?.latencyMs}ms`, r.curation?.label);
+}
+console.log(`${page.items.length} of ${page.pagination.total}`);
+
+// Free-text search. The parameter is `q`; anything else is rejected with a 400.
+const hits = await bazaar.listResources({ q: 'logs' });
+
+// Walk the whole filtered catalog, one page at a time
+for await (const r of bazaar.iterateResources({ health: 'alive' })) {
+  if (isAlive(r)) console.log(r.url);
 }
 
-// Register a resource
-const resource = await bazaar.register({
+// Register a resource. Registration is open and rate limited.
+await bazaar.registerResource({
   url: 'https://api.example.com/v1/generate',
-  name: 'Image Generator API',
   description: 'Generate images with AI',
-  category: 'ai',
-  networks: ['base', 'ethereum'],
-  price: '0.05',
-  payTo: '0x1234...',
+  accepts: [{
+    scheme: 'exact',
+    network: 'eip155:8453',
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    amount: '50000',
+    payTo: '0x1234...',
+    maxTimeoutSeconds: 60,
+  }],
+  metadata: { category: 'ai', tags: ['image'] },
 });
+
+// Aggregate catalog metrics
+const stats = await bazaar.getStats();
+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';