uvd-x402-sdk 2.102.0 → 2.104.0

package/README.md

@@ -675,6 +675,7 @@ import { buildEscrowPreAuth, EnvKeyAdapter } from 'uvd-x402-sdk';
 // (e.g. Execution Market's GET /api/v1/h2a/payment-config).
 const paymentAuth = await buildEscrowPreAuth(new EnvKeyAdapter(), {
   networkConfig: config.escrow.networks.base,
+  network: 'base',                    // its chain_id must be the chain this SDK registers for it
   payerWallet: '0xPublisher...',
   workerWallet: '0xWorker...',        // escrow receiver — committed by the nonce
   bountyAtomic: '100000',             // $0.10 in 6-decimal USDC
@@ -683,7 +684,7 @@ const paymentAuth = await buildEscrowPreAuth(new EnvKeyAdapter(), {
 // Send as the X-Payment-Auth header (raw JSON, NOT base64).
 ```
 
-Any `SigningWalletAdapter` works as the signer (only `signTypedData` is used); browser wallets can pass a minimal `{ signTypedData }` wrapper. Validation fails loud instead of falling back: incomplete network config, unknown tier, bounty outside the on-chain deposit limit ($100), or a `maxFeeBps` below the operator's 1300 bps all throw before anything is signed. `computeEscrowNonce` is exported to reproduce `AuthCaptureEscrow.getHash` externally.
+Any `SigningWalletAdapter` works as the signer (only `signTypedData` is used); browser wallets can pass a minimal `{ signTypedData }` wrapper. Validation fails loud instead of falling back: incomplete network config, unknown tier, bounty outside the on-chain deposit limit ($100), or a `maxFeeBps` below the operator's 1300 bps all throw before anything is signed. What the config asserts is also checked against the SDK's own tables before signing, as in the Python SDK: the `chain_id` against the `network` you name (a registry name or `eip155:<id>`), the escrow, token collector and USDC against `ESCROW_CONTRACTS`, the operator against `ESCROW_OPERATORS`, and `maxFeeBps` against the chain's ceiling in `ESCROW_MAX_FEE_BPS`. A contradiction throws `INVALID_CONFIG`, and so do a `network` the SDK does not register and a chain without a row in each of the three tables, with or without `network`; name the network you expect to pay on, from your own code, never one read from the config. A server-published tier window must be an integer from 0 to its `ESCROW_TIER_WINDOW_MAX`, and `authorizationExpiry` at most `ESCROW_MAX_AUTHORIZATION_SEC` after now: past either, the SDK refuses, it never clamps. `computeEscrowNonce` is exported to reproduce `AuthCaptureEscrow.getHash` externally.
 
 ## Multi-Stablecoin (EVM)
 
@@ -888,11 +889,74 @@ app.post('/api/premium', async (req, res) => {
 });
 ```
 
-`createPaymentMiddleware()` and `createHonoMiddleware()` verify and settle automatically by default (`before-handler`). Use `settlementStrategy: 'manual'` if you need to control when settlement happens (e.g., settle only after confirming you can fulfill the request).
+`createPaymentMiddleware()`, `createHonoMiddleware()` and `createFetchPaywall()` verify and settle automatically by default (`before-handler`). Use `settlementStrategy: 'manual'` if you need to control when settlement happens (e.g., settle only after confirming you can fulfill the request).
+
+A buyer in a browser on another origin reads the terms of a v2 402, in the `PAYMENT-REQUIRED` header, only if the app's CORS exposes that header: list it in `Access-Control-Expose-Headers` (with `hono/cors`, `exposeHeaders: ['PAYMENT-REQUIRED']`) and send `Access-Control-Allow-Origin`. The 402 of `createHonoMiddleware` and `createFetchPaywall` sets no CORS header of its own; `create402Response` lists the header in its `headers` but sets no `Access-Control-Allow-Origin` (spread `getCorsHeaders(origin)` too).
+
+### Astro, Next.js, Vercel and Cloudflare (`createFetchPaywall`)
+
+A route that takes a `Request` and returns a `Response` gets the same paywall as `createHonoMiddleware`: same options, same answers, same code underneath. `createFetchPaywall(options)` returns a wrapper; the route it wraps runs only for a verified payment (settled first, unless `settlementStrategy: 'manual'`) and receives it as its second argument. Without a payment the route answers `402` with the accepts, and it never runs for a refused, unverifiable or already used one.
+
+**Astro** (`src/pages/api/premium/[id].ts`, on-demand rendering with any adapter, e.g. `@astrojs/vercel`):
+
+```typescript
+import type { APIRoute } from 'astro';
+import { createFetchPaywall } from 'uvd-x402-sdk/backend';
+
+// Run on every request: a prerendered endpoint is called once, at build time, without a payment.
+export const prerender = false;
+
+const paywall = createFetchPaywall({
+  accepts: [{
+    network: 'base',
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
+    amount: '10000', // $0.01 (6 decimals)
+    payTo: process.env.RECEIVING_ADDRESS as string,
+  }],
+});
+
+export const GET: APIRoute = paywall(async (context, x402) => {
+  return Response.json({ id: context.params.id, payer: x402.verifyResult.payer });
+});
+```
+
+**Next.js** (App Router, `app/api/articles/[slug]/route.ts`):
+
+```typescript
+import { createFetchPaywall } from 'uvd-x402-sdk/backend';
+
+const paywall = createFetchPaywall({ accepts: [/* as above */] });
+
+export const GET = paywall(async (request: Request, x402, { params }: { params: Promise<{ slug: string }> }) => {
+  const { slug } = await params;
+  const settled = await x402.settle(); // the settle already made before the handler ran
+  return Response.json({ slug, transaction: settled.transactionHash });
+});
+```
+
+**Vercel Functions and Cloudflare Workers** take the `Request` itself; whatever else the platform passes (`env`, `ctx`) comes after the payment:
+
+```typescript
+import { createFetchPaywall } from 'uvd-x402-sdk/backend';
+
+const paywall = createFetchPaywall({
+  accepts: [{ network: 'base', asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', amount: '10000', payTo: '0xYourWallet' }],
+});
+
+export default {
+  fetch: paywall(async (request: Request, x402, env: Env, ctx: ExecutionContext) => new Response('paid content')),
+};
+```
+
+- The route's first argument is the `Request`, or an object that carries it as `request` (Astro, SvelteKit, React Router). The handler gets that same first argument back, then the payment, then the rest.
+- The advertised `resource` is `request.url`. Behind a proxy that rewrites the host, set `resource` in the accept.
+- A facilitator receipt goes out as `PAYMENT-RESPONSE` on the response the handler returns, added to its own `Access-Control-Expose-Headers` and `Cache-Control` rather than replacing them; a `Response.redirect()` works too. In `'manual'` mode, a `settle()` that ends after the handler returned changes nothing in the response.
+- Once a receipt exists, a handler that throws an `Error` gets a `500` that keeps the receipt headers, as Hono's default error handler answers one, and the error goes to `console.error`: the buyer may have paid, and the receipt is their proof. Such an error does not reach the framework's error reporting (Next.js `onRequestError`, a Sentry wrapper); catch it inside the handler if it must. The framework's own control flow passes through untouched: a thrown `Response` (React Router, Remix) is rethrown with the receipt headers, and SvelteKit's `redirect()` / `error()` and Next.js' `redirect()` / `notFound()` are rethrown as they are, so the receipt does not ride on them; to send it with a redirect, return `Response.redirect()` instead. Without a receipt every error reaches the framework as usual.
+- The paywall answers every request that reaches it, `OPTIONS` included. If browsers on another origin pay, answer the preflight before the paywall (an `OPTIONS` export in Astro or Next.js, a method check in a Worker) and add `Access-Control-Allow-Origin` to what the route returns (`getCorsHeaders(origin)`).
 
 ### Stack key (services run by Ultravioleta DAO)
 
-Services run by Ultravioleta DAO carry a per-service credential, the stack key, so that the facilitator's rate-limit policy does not answer them `429`. Everything in this SDK that calls the facilitator sends it as `X-UVD-Stack-Key`: the clients `FacilitatorClient` (and the two middlewares), `Erc8004Client`, `BazaarClient`, `EscrowClient` and `AdvancedEscrowClient`, and the functions `anchorEvidence`, `availableBackends`, `streamTrafficEvents` and `getFacilitatorReceipt`, which take the same `stackKey` / `stackKeyHosts` options. It changes nothing else about a payment, and a facilitator that does not know the header ignores it.
+Services run by Ultravioleta DAO carry a per-service credential, the stack key, so that the facilitator's rate-limit policy does not answer them `429`. Everything in this SDK that calls the facilitator sends it as `X-UVD-Stack-Key`: the clients `FacilitatorClient` (and the two middlewares and `createFetchPaywall`), `Erc8004Client`, `BazaarClient`, `EscrowClient` and `AdvancedEscrowClient`, and the functions `anchorEvidence`, `availableBackends`, `streamTrafficEvents` and `getFacilitatorReceipt`, which take the same `stackKey` / `stackKeyHosts` options. It changes nothing else about a payment, and a facilitator that does not know the header ignores it.
 
 - **Where it comes from:** the facilitator's operator issues one per service: `uvdsk_` followed by 43-128 base64url characters. The process receives it as `UVD_STACK_KEY` (read by default) or as the `stackKey` option, from a secret store, never from code.
 - **Not for third parties:** if you integrate this SDK in your own product you have no key and need none. Leave both unset and no header is sent.
@@ -1248,7 +1312,7 @@ anti-double-settle guard, adopted here.
 
 ### Middleware
 
-`createPaymentMiddleware` and `createHonoMiddleware` answer **503 with a
+`createPaymentMiddleware`, `createHonoMiddleware` and `createFetchPaywall` answer **503 with a
 `Retry-After` header** — not `402`, not `500` — whenever the facilitator reached
 no verdict, and keep answering `402` for genuine rejections.
 
@@ -1260,7 +1324,7 @@ the buyer's client can reconcile instead of paying again.
 An X-PAYMENT the facilitator already admitted for another request is answered
 **`409`** (`authorization_already_settled`, `receipt_request_conflict`: it was
 used, the handler does not run) or **`503` + `Retry-After`** while it is
-`authorization_in_flight` — never `402` and never `500`. Both middlewares add
+`authorization_in_flight` — never `402` and never `500`. All three add
 `PAYMENT-RESPONSE` to an existing `Access-Control-Expose-Headers` and `no-store`
 to an existing `Cache-Control` instead of replacing them, and in `'manual'` mode
 a `settle()` after the handler already answered no longer touches the sent
@@ -1771,7 +1835,7 @@ bazaarExtension({
 });
 ```
 
-The result is `{ bazaar: { info, schema } }`: `info.input` (`type: "http"`, `method`, then `bodyType` and `body` for a body method, or `queryParams` for a query method, plus optional `headers`), `info.output` (`type`, default `json`, and `example`), and `schema`, the JSON Schema (draft 2020-12) that `info` validates against. `bodyType` is `json` (default), `form-data` or `text` (then `body` is a string). A body method without `body`, a query method with one, or a method the spec does not name (`CONNECT`, `OPTIONS`, ...) throws. `extensions` is a v2 field: `create402Response` throws if the response would be v1 rather than dropping it, and without `extensions` it returns exactly what it returned before.
+The result is `{ bazaar: { info, schema } }`: `info.input` (`type: "http"`, `method`, then `bodyType` and `body` for a body method, or `queryParams` for a query method, plus optional `headers`), `info.output` (`type`, default `json`, and `example`), and `schema`, the JSON Schema (draft 2020-12) that `info` validates against. `bodyType` is `json` (default), `form-data` or `text` (then `body` is a string). A body method without `body`, a query method with one, or a method the spec does not name (`CONNECT`, `OPTIONS`, ...) throws. `extensions` is a v2 field: `create402Response` throws if the response would be v1 rather than dropping it, and without `extensions` the body has no `extensions` key.
 
 ## x402 v2 requests (`buildVerifyRequestV2` / `buildSettleRequestV2`)
 
@@ -2103,8 +2167,8 @@ the authorization and reuse it after uncertainty. Payment confirmation does not
 prove merchant delivery. See [the receipt guide](docs/facilitator-receipts.md).
 
 Every `/verify` and `/settle` carries an `Idempotency-Key`, the same one for both
-calls of a payment and for their retries: `verifyAndSettle` and both middlewares
-create one per payment, and `verify`/`settle` accept `{ idempotencyKey }`
+calls of a payment and for their retries: `verifyAndSettle`, both middlewares and
+`createFetchPaywall` create one per payment, and `verify`/`settle` accept `{ idempotencyKey }`
 (`createIdempotencyKey()`). The facilitator returns an admitted payment's original
 answer (`SettleResponse.replayed`, from `Idempotent-Replayed: true`) only to that
 key or to the buyer's `X-UVD-Purchase`; a resend without them is

package/dist/adapters/index.js

@@ -103,10 +103,12 @@ var SUPPORTED_CHAINS = {
         name: "USD Coin",
         version: "2"
       },
+      // name() on-chain is "Euro Coin" here and "EURC" on Base: pinned to each
+      // contract's DOMAIN_SEPARATOR() by src/eurc-domains.test.ts.
       eurc: {
         address: "0xC891EB4cbdEFf6e073e859e987815Ed1505c2ACD",
         decimals: 6,
-        name: "EURC",
+        name: "Euro Coin",
         version: "2",
         usdPegged: false
       },