@odatano/x402 0.1.0 → 0.3.0

package/.github/workflows/test.yaml

@@ -0,0 +1,49 @@
+name: tests
+
+# Run on every push to main and every pull request. Manual dispatch
+# lets us re-run the workflow from the Actions tab without a commit.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Node ${{ matrix.node }} on ubuntu-latest
+    runs-on: ubuntu-latest
+
+    strategy:
+      # One Node failing should not cancel the other matrix legs;
+      # often a regression hits one version only.
+      fail-fast: false
+      matrix:
+        # Matches ODATANO core's support range.
+        node: ['20.x', '22.x']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        # `npm ci` enforces the lockfile and refuses to mutate it.
+        # Faster and more deterministic than `npm install` for CI.
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type-check + build
+        # tsc -p tsconfig.build.json emits .js/.d.ts next to .ts.
+        # We don't ship those emits from CI; the step just verifies
+        # the build passes against the declared types.
+        run: npm run build
+
+      - name: Run tests
+        run: npm test

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `@odatano/x402` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/) and the project adheres to [Semantic Versioning](https://semver.org/).
+
+**Pre-1.0 caveat:** minor versions may include breaking changes until `1.0.0`.
+
+## [0.3.0] - 2026-05-15
+
+### Added
+- **`createFacilitatorRouter()`** , reference HTTP facilitator. Returns an Express `Router` exposing `POST /verify-settle`, `GET /supported`, and an open `GET /healthz` liveness probe. Composable with any auth scheme via the `auth(req)` hook; defaults to `localFacilitator()`. Facilitator-side audit hooks (`onRejected`, `onPending`) fill the gap left by `onAccepted` (which is invoked client-side by `httpFacilitator()`). See [`examples/facilitator-server/`](examples/facilitator-server/) and [`docs/facilitator-protocol.md`](docs/facilitator-protocol.md#reference-implementation).
+- **Multi-accept payment options** , `routePricing` (and `priceUnits`) now accept `RouteOption[]` so a single route can offer e.g. "0.5 ADA *or* 0.1 USDM". The buyer picks one implicitly by which `(payTo, asset)` the payment tx credits; new `pickRequirement()` selector in `srv/core/validate.ts` routes the tx to the matching entry before the six strict checks run. Single-entry behaviour is bit-identical to v0.2. New builder: `buildPaymentRequirementsMulti()`.
+- **Dynamic `PriceResolver`** , `routePricing` can be a function `(PricingContext) => PriceSpec | null | Promise<...>`. Returning `null` passes the request through ungated, enabling free-tier, role-based, or per-payload pricing. `PricingContext` exposes `event`, `target` (CAP), `path`/`method`/`query` (Express), and `headers`. See [`docs/usage.md`](docs/usage.md#pricespec-and-priceresolver).
+- **Receipts persistence (CAP)** , new `receipts?: boolean | { entity?: string }` option on `gateService`. When set, one INSERT per accepted payment, post-settle, pre-response. Default entity `odatano.x402.X402Receipts` ships in `db/x402-receipts.cds` and is auto-discovered by CAP. INSERT failures are logged and never block the response. See [`docs/usage.md`](docs/usage.md#receipts-persistence-receipts).
+- **Subscription / time-limited grants (CAP)** , new `grants?: boolean | { ttlSeconds?: number; entity?: string }` option on `gateService`. On accepted payment the gate issues an opaque token and returns it via `X-PAYMENT-GRANT` / `X-PAYMENT-GRANT-EXPIRES` response headers; subsequent requests presenting the token on `X-PAYMENT-GRANT` bypass the 402 + verify+settle pipeline until expiry. Default TTL 3600s. Grants are single-route (strict URL equality). Default entity `odatano.x402.X402Grants` ships in `db/x402-grants.cds`. DB failures during issue or lookup are swallowed: failing DB never denies a paying buyer their response. See [`docs/usage.md`](docs/usage.md#subscription--time-limited-grants-grants).
+- **Typed client errors** , new `X402PaymentError` class (with `kind`, `code`, `accepts`, `httpStatus`, `serverError`, `cause` fields). Thrown by `x402Fetch` and `x402Axios` to surface payment failures. Pay-handler errors are ALWAYS wrapped (with the original on `.cause`); add `errorOnFailure: true` to opt into typed throws on unrecovered 402s instead of the previous return-the-response / re-throw-AxiosError behaviour. Helpers `parseErrorCode` and `paymentErrorFromBody` are exported for consumers wrapping the wrappers. See [`docs/usage.md`](docs/usage.md#client-side-errors-x402paymenterror).
+- **Browser-buyer example** , `examples/browser-buyer/` Vite scaffold showing CIP-30 wallet + `x402Fetch` wiring. Documents the typical "unsigned-from-server, signed-by-wallet" architecture (server exposes `POST /pay/intent` via `buildUnsignedPaymentTx`; browser signs via CIP-30). Includes CORS notes for cross-origin deployments.
+
+### Fixed
+- **`x402Fetch` / `x402Axios` now interop with `gateService`** out of the box. CAP's `req.reject(402, body)` wraps the canonical v2 body inside its standard OData error envelope (`{ error: { message: "<json>", code: "402", ... } }`), so previous client wrappers saw `body.x402Version === undefined` and bailed without retrying. Both clients now defensively unwrap the OData envelope before validating shape. Reported by the CHAINFEED team; matches the workaround they were shipping in `scripts/buyer-pay-and-fetch.ts`. New helper `unwrapCapEnvelope` is exported for consumers wrapping the wrappers.
+
+### Known issues
+- The CAP `gateService` still emits 402 responses wrapped in CAP's OData error envelope on the wire (because `req.reject` is the only documented abort path). Third-party x402 clients hitting a CAP-gated server will see the wrapped shape; only `@odatano/x402`'s own clients unwrap it. Direct-write-to-`req.http.res` is the planned symmetric fix but needs validation against `@sap/cds` ^9 internals; tracked for v0.3.1.
+- `PaymentClaim.payTo` , verified recipient address now populated on the claim (was previously only on the requirements entry). Useful for `onAccepted` audit and receipts.
+
+### Changed
+- Test count: 177 → 230 (HTTP-server round-trips, multi-accept + dynamic-pricing across `requirements`/`validate`/`verify`/`cap`/`express`, 4 receipts cases, 5 grants cases, 13 client-error cases).
+- `srv/middleware/{cap,express}.ts` now emit `accepts[]` via `buildPaymentRequirementsMulti()`; single-entry callers are unaffected (one-entry array produces a body byte-identical to v0.2).
+- `srv/facilitator/verify.ts` decodes the envelope BEFORE selecting a requirements entry; multi-accept depends on knowing which `(payTo, asset)` the tx actually credited.
+
+## [0.2.0] - 2026-05-15
+
+### Added
+- **Client helpers**: `x402Fetch`, `x402Axios`, `createBridgePayHandler`, `encodePaymentEnvelope` for symmetric server + client usage. See [`docs/usage.md`](docs/usage.md#5-client-side-auto-handle-402-x402fetch--x402axios).
+- **Facilitator adapter pattern**: `Facilitator` interface, `localFacilitator()` (default, in-process via `@odatano/core`), `httpFacilitator()` for delegating verify+settle to a hosted service. HTTP wire format documented in [`docs/facilitator-protocol.md`](docs/facilitator-protocol.md).
+- **`facilitator` option** on `gateService` and `x402Middleware` for swapping in the local default, an HTTP delegate, or a mock for tests.
+- **GitHub Actions CI** (`.github/workflows/test.yaml`): runs lint + build + tests on Node 20.x and 22.x for every push to `main` and every pull request.
+
+### Changed
+- Test count: 144 → 177 (added 4 client suites and 2 facilitator-adapter suites).
+
+### Notes
+- `0.1.0` consumers upgrade without code changes. The new `facilitator` option defaults to the previous in-process behaviour, so existing call sites are untouched.
+
+## [0.1.0] - 2026-05-13
+
+### Added
+- Initial release. Cardano-x402-v2 payment gating for SAP CAP and Express.
+- `gateService(srv, opts)` for CAP `before('*')` integration.
+- `x402Middleware(opts)` for plain Express routes.
+- Facilitator pipeline: decode, validate (six mandatory checks), `checkNonceUnspent`, `settle` (submit + poll-until-confirmed), `onAccepted` audit callback.
+- Helpers: `verifyConfirmedPayment` (post-paid flow), `buildUnsignedPaymentTx` (browser-buyer flow).
+- CAP plugin auto-discovery via `cds-plugin.js`.
+- 144 unit tests across 13 suites.
+
+### Spec compatibility
+- Implements Cardano-x402-**v2** only. v1 envelopes are rejected with `unsupported_version`; v1-style network strings (`cardano-preprod` with hyphen) are rejected with `invalid_network_format`.
+- v1 and v2 facilitators cannot share a route: they use different header names (`X-PAYMENT` vs `PAYMENT-SIGNATURE`) and incompatible 402 bodies. To migrate from v1, replace the middleware in one commit; clients must upgrade simultaneously.

package/README.md

@@ -1,32 +1,25 @@
 # @odatano/x402
 
+[![npm](https://img.shields.io/npm/v/@odatano/x402?color=cb3837&logo=npm)](https://www.npmjs.com/package/@odatano/x402)
+[![tests](https://github.com/ODATANO/x402/actions/workflows/test.yaml/badge.svg)](https://github.com/ODATANO/x402/actions/workflows/test.yaml)
+[![@odatano/core](https://img.shields.io/github/package-json/dependency-version/ODATANO/x402/peer/@odatano/core?label=%40odatano%2Fcore&color=0e7c66)](https://www.npmjs.com/package/@odatano/core)
+[![spec](https://img.shields.io/badge/Cardano--x402-v2-blueviolet)](https://github.com/masumi-network/x402-cardano)
+
 x402 payment gating for SAP CAP applications, backed by Cardano.
 
-Wire a single `before('*')` hook into your CAP service and every gated request returns **HTTP 402 Payment Required** until the caller proves on-chain settlement. Asset-agnostic — pay in ADA, USDM, or any native asset.
+Wire a single `before('*')` hook into your CAP service. Every gated request returns **HTTP 402 Payment Required** until the caller proves on-chain settlement. Asset-agnostic: pay in ADA, USDM, or any native asset.
 
 Implements the **Cardano-x402-v2** spec on top of [`@odatano/core`](https://www.npmjs.com/package/@odatano/core).
 
----
-
-## What is x402?
-
-[x402](https://www.x402.org/) is the dormant HTTP `402 Payment Required` status code, revived. Servers respond `402` with a machine-readable body describing the price, asset, and recipient. Clients build, sign, and submit a payment, then retry the request with a `PAYMENT-SIGNATURE` header. Settlement happens on-chain.
-
-The original x402 spec is Coinbase / EVM-flavoured. The **Cardano-x402-v2** spec (in progress at [masumi-network/x402-cardano](https://github.com/masumi-network/x402-cardano)) adapts it to Cardano's UTxO model. This library is a from-scratch v2 implementation in TypeScript.
-
----
-
 ## Install
 
 ```bash
 npm install @odatano/x402 @odatano/core
 ```
 
-`@odatano/core` (the Cardano bridge) is a peer dependency — install whichever version meets `>=1.7.8`.
+`@odatano/core` (the Cardano bridge) is a peer dependency. Install whichever version meets `>=1.7.8`.
 
----
-
-## Quick Start — CAP service gate
+## Quick Start
 
 ```typescript
 // srv/prices-service.ts
@@ -38,16 +31,10 @@ export class PricesService extends cds.ApplicationService {
     gateService(this, {
       payTo:   'addr_test1...your-preprod-address...',
       network: 'cardano:preprod',
-      asset:   'lovelace',                  // or '<policy>.<nameHex>' for native tokens
+      asset:   'lovelace',                // or '<policy>.<nameHex>' for native tokens
       routePricing: {
-        Quotes:        '500000',            // 0.5 ADA per Quotes read
-        getBestPrice:  '1000000',           // 1 ADA per getBestPrice action call
-      },
-      description: 'Synthetic price feed',
-      onAccepted: async (claim, req) => {
-        // Optional audit — runs once per accepted payment, after settlement.
-        // Errors here are logged but don't block the response.
-        console.log(`paid ${claim.amountUnits} ${claim.asset} (tx=${claim.txHash})`);
+        Quotes:       '500000',           // 0.5 ADA per Quotes read
+        getBestPrice: '1000000',          // 1 ADA per getBestPrice action call
       },
     });
     return super.init();
@@ -71,280 +58,41 @@ Configure the Cardano backend in `package.json`:
 }
 ```
 
-That's it — `cds watch` and every request to a gated route gets:
-
-```http
-HTTP/1.1 402 Payment Required
-Content-Type: application/json
-```
-```json
-{
-  "x402Version": 2,
-  "error": "PAYMENT-SIGNATURE header is required",
-  "accepts": [{
-    "scheme": "exact",
-    "network": "cardano:preprod",
-    "asset": "lovelace",
-    "amount": "500000",
-    "payTo": "addr_test1...",
-    "resource": {
-      "url": "/odata/v4/prices/Quotes",
-      "description": "Synthetic price feed",
-      "mimeType": "application/json"
-    },
-    "assetTransferMethod": "default",
-    "maxTimeoutSeconds": 600
-  }]
-}
-```
-
-A working version of this is in [`examples/cap-app/`](examples/cap-app/).
-
----
-
-## Usage patterns
-
-### 1. CAP service gate (`gateService`)
-
-For OData-served entities and bound/unbound actions. Pricing keys can be entity names (for CRUD) or action names — the gate tries both.
-
-```typescript
-gateService(this, {
-  payTo, network, asset,
-  routePricing: { Quotes: '500000', getBestPrice: '1000000' },
-});
-```
-
-When a payment is accepted, the verified `PaymentClaim` is stashed on `req.payment` for downstream handlers, and an `X-PAYMENT-RESPONSE` header is set on the response.
-
-### 2. Express middleware (`x402Middleware`)
-
-For plain Express routes (e.g. mounted alongside CAP via `cds.on('bootstrap', app => …)`):
-
-```typescript
-import { x402Middleware } from '@odatano/x402';
-
-app.use('/api/premium', x402Middleware({
-  payTo, network, asset,
-  priceUnits: '1000000',
-  skipPaths: /(\$metadata|^\/?$)/i,
-  onAccepted: async (claim, req) => { /* audit */ },
-}));
-```
-
-### 3. Programmatic — verify a post-paid tx
-
-For subscription / pre-paid flows where the buyer hands you a tx hash:
-
-```typescript
-import { verifyConfirmedPayment } from '@odatano/x402';
-
-const result = await verifyConfirmedPayment({
-  txHash:         'ab8f…',
-  requiredAmount: '1000000',
-  asset:          'lovelace',
-  payTo:          'addr_test1...',
-  network:        'cardano:preprod',
-});
-
-if (result.ok) {
-  // result.amountUnits is what was actually paid (may exceed requiredAmount)
-} else {
-  // result.code: 'pending' | 'wrong_asset' | 'insufficient_amount' | ...
-}
-```
-
-### 4. Programmatic — server-side unsigned-tx builder for browser buyers
-
-When the buyer's CIP-30 wallet can sign but not coin-select:
-
-```typescript
-import { buildUnsignedPaymentTx, buildPaymentRequirements, flatRequirements } from '@odatano/x402';
-
-const body = buildPaymentRequirements({ amount: '1000000', asset: 'lovelace', payTo, network: 'cardano:preprod', resource: '/r' });
-const requirements = flatRequirements(body);
-
-const { unsignedTxCborHex, txHashHex, nonceRef } = await buildUnsignedPaymentTx({
-  buyerBech32: 'addr_test1...buyer...',
-  requirements,
-});
-
-// Browser signs unsignedTxCborHex via CIP-30, then assembles the
-// PAYMENT-SIGNATURE envelope with `nonceRef` as payload.nonce.
-```
-
----
-
-## Configuration reference
-
-### `gateService(srv, options)` / `x402Middleware(options)`
-
-| Option | Type | Required | Default | Notes |
-|---|---|---|---|---|
-| `payTo` | `string` (bech32) | yes | — | Recipient address |
-| `network` | `'cardano:mainnet' \| 'cardano:preprod' \| 'cardano:preview'` | yes | — | **v2 uses colon separator** (v1 hyphen rejected) |
-| `asset` | `string` | yes | — | `'lovelace'` for ADA, or `'<policyIdHex>.<assetNameHex>'` for native tokens |
-| `priceUnits` | `string \| number \| bigint` | one of priceUnits / routePricing | — | Single price for everything under the mount |
-| `routePricing` | `Record<string, string \| number \| bigint>` | one of priceUnits / routePricing | — | Per-entity / per-action prices. Unmapped keys pass through unless `priceUnits` is also set |
-| `skipPaths` | `RegExp` | no | matches `$metadata`, `$batch`, root, `/index` | Express only — paths to bypass |
-| `description` | `string` | no | `''` | Embedded in `accepts[0].resource.description` |
-| `mimeType` | `string` | no | `'application/json'` | Embedded in `accepts[0].resource.mimeType` |
-| `assetTransferMethod` | `'default' \| 'masumi' \| 'script'` | no | `'default'` | v2 field; MVP supports only `default` |
-| `maxTimeoutSeconds` | `number` | no | `600` | Buyer-side TTL hint |
-| `extra` | `Record<string, unknown>` | no | — | Free-form extras (decimals, fingerprint, UI hints) |
-| `settlePollBudgetMs` | `number` | no | `60_000` | How long to poll for chain confirmation before returning `402 pending` |
-| `allowNoTtl` | `boolean` | no | `false` | If `true`, accept txs with no validity-range upper bound |
-| `onAccepted` | `(claim, req) => void \| Promise<void>` | no | — | Audit callback. Errors logged, never block response |
-| `resourceUrl` | `(req) => string` | no (CAP only) | derives from `req.http.req.originalUrl` | Override the resource URL emitted in the 402 body |
-
----
-
-## The buyer flow
-
-```
-        Server                              Buyer (browser / CLI)
-          │                                       │
-          │  ◄── GET /odata/v4/prices/Quotes ─────│
-          │                                       │
-          │ ──── 402 + accepts[0] (price, payTo) ►│
-          │                                       │
-          │                              ┌────────┴────────┐
-          │                              │ build tx        │
-          │                              │ sign via CIP-30 │
-          │                              │ base64-encode   │
-          │                              └────────┬────────┘
-          │                                       │
-          │  ◄── GET /odata/v4/prices/Quotes ─────│
-          │        PAYMENT-SIGNATURE: <base64>    │
-          │                                       │
-   ┌──────┴──────┐                                │
-   │ 6 checks    │                                │
-   │ + submit    │                                │
-   │ + poll      │                                │
-   │ + onAccepted│                                │
-   └──────┬──────┘                                │
-          │                                       │
-          │ ─────── 200 OK + data ───────────────►│
-          │   X-PAYMENT-RESPONSE: <base64>        │
-```
-
-`PAYMENT-SIGNATURE` envelope shape:
-
-```json
-{
-  "x402Version": 2,
-  "scheme": "exact",
-  "network": "cardano:preprod",
-  "payload": {
-    "transaction": "<base64-CBOR of signed tx>",
-    "nonce":       "<txHash>#<outputIndex>"
-  }
-}
-```
-
-The `nonce` references a UTxO that **must also appear as an input of the payment tx**. Once the tx settles, that UTxO is consumed — replay defense is on-chain, no DB table needed.
-
----
-
-## Six mandatory facilitator checks
+`cds watch`, then probe a gated route: it returns `402` with a v2-shape body. A working example lives in [`examples/cap-app/`](examples/cap-app/).
 
-Every accepted payment passes all six (in order):
+## What's in the box
 
-| # | Check | Code on failure |
-|---|---|---|
-| 1 | Network matches requirements | `network_mismatch` |
-| 2 | At least one output to `payTo` | `wrong_recipient` |
-| 3 | Sum of payTo outputs for asset ≥ required | `insufficient_amount` |
-| 4 | Exact policy + asset-name match | `wrong_asset` |
-| 5 | Nonce UTxO referenced as tx input **and** unspent on chain | `nonce_not_referenced` / `replay_detected` |
-| 6 | Validity-range upper bound still in future | `expired_ttl` |
+- **`gateService(srv, opts)`** for CAP services and **`x402Middleware(opts)`** for plain Express routes.
+- **`x402Fetch` / `x402Axios`** wrappers that auto-handle 402 on the client side.
+- **`Facilitator` adapter:** `localFacilitator()` (default, in-process via `@odatano/core`) or `httpFacilitator()` to delegate verify+settle to a hosted service.
+- **Helpers:** `buildUnsignedPaymentTx` (browser-buyer flow), `verifyConfirmedPayment` (post-paid / subscription).
 
-Plus a sanity guard: tx has at least one vkey witness → `unsigned_transaction`.
+## Documentation
 
-Rejected requests get `402` with an `error` field of the form `"<base> (<code>): <reason>"` so clients can parse the code without breaking wire format.
-
----
-
-## Architecture
-
-```
-            ┌──────────────────┐
-  consumer  │ CAP application  │
-            │                  │
-            │ gateService(this,│
-            │   { … })         │
-            └────────┬─────────┘
-                     │
-                     ▼
-            ┌──────────────────┐    bridge.ts
-            │  @odatano/x402   │ ──────────────┐
-            │                  │               │
-            │ core/      ──────┤ pure logic    │
-            │ facilitator/ ────┤ chain-touching│
-            │ middleware/  ────┤ Express + CAP │
-            │ helpers/     ────┤ tx-build,     │
-            │                  │ verify-post-paid
-            └──────────────────┘               │
-                                               ▼
-                                  ┌────────────────────────┐
-                                  │   @odatano/core 1.7.8  │
-                                  │  ┌──────┬──────┬─────┐ │
-                                  │  │ Blkf │Koios │Ogms │ │
-                                  │  └──────┴──────┴─────┘ │
-                                  └────────────────────────┘
-                                            │
-                                            ▼
-                                       Cardano network
-```
-
-Pure modules (`core/*`) are decoupled from the bridge and can be unit-tested without any chain backend. The facilitator orchestrates `decode → validate → checkNonceUnspent → settle → onAccepted`.
-
----
+| Doc | Covers |
+|---|---|
+| [`docs/usage.md`](docs/usage.md) | All five usage patterns + full configuration reference |
+| [`docs/protocol.md`](docs/protocol.md) | Buyer-flow diagram, `PAYMENT-SIGNATURE` envelope, the six mandatory facilitator checks |
+| [`docs/architecture.md`](docs/architecture.md) | Module layout, pure-vs-chain split, plugin auto-discovery |
+| [`docs/facilitator-protocol.md`](docs/facilitator-protocol.md) | HTTP wire format for the hosted-facilitator pattern (`httpFacilitator()`) |
+| [`CHANGELOG.md`](CHANGELOG.md) | Versioned changes, latest first |
 
 ## Requirements
 
 - Node.js 22+
 - `@sap/cds >= 9` (peer)
 - `@odatano/core >= 1.7.8` (peer)
-- `express ^4` (peer) — only required if you use `x402Middleware`
+- `express ^4` (peer), only if you use `x402Middleware`
 - A Cardano backend reachable via `@odatano/core` (Blockfrost / Koios / Ogmios)
 
----
-
 ## Development
 
 ```bash
-npm install                # Workspace install — covers root + examples/*
-npm run build              # tsc — emits .js/.d.ts next to .ts (outDir: .)
-npm test                   # 144 tests, ~12s
-npm run test:coverage      # Coverage report
-npm run watch              # cds watch — for the root project itself
-```
-
-The example app:
-
-```bash
-cd examples/cap-app
-npm start                  # cds-serve with in-memory SQLite
-```
-
-Then probe:
-
-```bash
-curl -s http://localhost:4004/odata/v4/prices/Quotes | jq .
-# → 402 with v2 body
+npm install                # Workspace install: covers root + examples/*
+npm run build              # tsc, emits .js/.d.ts next to .ts (outDir: .)
+npm test                   # 177 tests, ~13s
 ```
 
----
-
-## Versioning + spec compatibility
-
-- **Library:** `0.1.0` (pre-1.0; expect minor breakages between minors until 1.0)
-- **Spec:** Cardano-x402-**v2** only. v1 envelopes are rejected with `unsupported_version`. v1-style network strings (`cardano-preprod`) are rejected with `invalid_network_format`.
-- **Coexistence:** A v1 facilitator and a v2 facilitator can't share the same route — they use different header names (`X-PAYMENT` vs `PAYMENT-SIGNATURE`) and incompatible 402 bodies. To migrate from v1, replace the middleware in one commit; clients must upgrade simultaneously.
-
----
-
 ## License
 
 Apache-2.0.

package/cds-plugin.js

@@ -7,4 +7,6 @@
  * (outDir: ".") so this require path resolves both in dev (tsx) and
  * after `npm run build`.
  */
+// CAP loads this file as a CommonJS entrypoint, so `require()` is required here.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 module.exports = require('./srv/plugin');

package/db/x402-grants.cds

@@ -0,0 +1,49 @@
+/**
+ * Time-limited access grants issued after an accepted x402 payment.
+ *
+ * Pattern: pay once, get N seconds of free access to the same route.
+ * The server issues an opaque random token on `accepted`, returns it via
+ * the `X-PAYMENT-GRANT` response header, and the buyer presents it on
+ * subsequent requests via `X-PAYMENT-GRANT` request header. Until the
+ * grant expires, the gate skips the 402 + verify+settle pipeline.
+ *
+ * Replay defense: each grant is single-route + time-bound. A grant
+ * issued for `/Quotes` cannot be used against `/getBestPrice` (cheap
+ * route boundary, the picker enforces equality). Stolen tokens are
+ * useful only until expiry.
+ *
+ * Cleanup: expired rows accumulate. The `lookupGrant` helper checks
+ * `expiresAt < now` and reports `expired`; consumers may run their own
+ * cleanup (`DELETE … WHERE expiresAt < now()`) on whatever schedule
+ * fits. The library does NOT auto-prune.
+ */
+
+namespace odatano.x402;
+
+entity X402Grants {
+    key id         : UUID;
+
+    @description: 'Opaque random token, base64url 32 bytes.'
+        token      : String(64) @assert.unique;
+
+    @description: 'Resource URL this grant unlocks (exact match).'
+        route      : String(500);
+
+    @description: 'Sender address from the original payment (if resolved).'
+        payerAddr  : String(120);
+
+    @description: 'Tx hash of the payment that bought this grant.'
+        txHash     : String(64);
+
+    @description: 'Asset of the underlying payment, audit only.'
+        asset      : String(120);
+
+    @description: 'cardano:mainnet | cardano:preprod | cardano:preview.'
+        network    : String(20);
+
+    @description: 'Server-side timestamp at issue.'
+        issuedAt   : Timestamp;
+
+    @description: 'Server-side timestamp when the grant becomes invalid.'
+        expiresAt  : Timestamp;
+}

package/db/x402-receipts.cds

@@ -0,0 +1,44 @@
+/**
+ * Optional persistence for accepted x402 payments.
+ *
+ * Enabled per-service by setting `receipts: true` on `gateService(opts)`.
+ * The gate writes one row per accepted payment, after settle confirms,
+ * BEFORE the response is served. Insert failures are logged and never
+ * block the response, the canonical record is on chain regardless.
+ *
+ * Namespace and entity name are stable, consumers can SELECT against
+ * `odatano.x402.X402Receipts` directly or extend it in their own model.
+ */
+
+namespace odatano.x402;
+
+entity X402Receipts {
+    key id         : UUID;
+
+    @description: 'Lowercase 64-char hex of the buyer''s settled payment tx.'
+        txHash     : String(64) @assert.unique;
+
+    @description: 'Sender address (first input bech32) if the facilitator resolved it.'
+        payerAddr  : String(120);
+
+    @description: 'Recipient bech32 the route required.'
+        payTo      : String(120);
+
+    @description: 'v2 asset string, ''lovelace'' or ''<policy>.<nameHex>''.'
+        asset      : String(120);
+
+    @description: 'Amount paid in raw units, BigInt-safe string.'
+        amount     : String(32);
+
+    @description: 'cardano:mainnet | cardano:preprod | cardano:preview.'
+        network    : String(20);
+
+    @description: 'Resource URL the buyer paid for (request originalUrl or cap://<event>).'
+        route      : String(500);
+
+    @description: '<txHash>#<index> of the UTxO that was the replay nonce.'
+        nonceRef   : String(80);
+
+    @description: 'Server-side timestamp when the receipt was written (post-settle).'
+        at         : Timestamp;
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@odatano/x402",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "x402 Cardano-v2 payment library for SAP CAP applications",
   "license": "Apache-2.0",
   "main": "srv/index.js",
-  "types": "srv/index.d.ts",
+  "types": "srv/cds-augment.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -26,13 +26,19 @@
     "@emurgo/cardano-serialization-lib-nodejs": "^15.0.3"
   },
   "peerDependencies": {
+    "@cap-js/cds-types": ">=0.15",
     "@odatano/core": ">=1.7.8",
     "@sap/cds": ">=9",
     "express": "^4"
   },
+  "peerDependenciesMeta": {
+    "@cap-js/cds-types": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@cap-js/cds-types": "^0.15.0",
     "@cap-js/cds-typer": "^0.38.0",
+    "@cap-js/cds-types": "^0.15.0",
     "@cap-js/sqlite": "^2",
     "@odatano/core": "^1.7.8",
     "@odatano/x402": ".",
@@ -47,6 +53,7 @@
     "jest": "^29",
     "ts-jest": "^29",
     "tsx": "^4",
-    "typescript": "^5"
+    "typescript": "^5",
+    "typescript-eslint": "^8.59.3"
   }
 }

package/srv/bridge.d.ts

@@ -3,18 +3,15 @@
  *
  * The x402 modules (facilitator, helpers, middleware) all import from
  * here so the underlying ODATANO surface is the only thing they couple
- * to — and so renames in core (`getTransaction` → `getTransactionByHash`)
+ * to, and so renames in core (`getTransaction` → `getTransactionByHash`)
  * stay isolated to this file.
  *
- * Two methods needed by Cardano-x402-v2 are NOT (yet) first-class on
- * `@odatano/core@1.7.7`:
- *   - `isUtxoUnspent(txHash, outputIndex)` — for replay-defense check 5b
- *   - `getCurrentSlot()`                   — for TTL check 6
+ * Two methods specific to Cardano-x402-v2 are first-class on
+ * `@odatano/core` since `1.7.8` (our minimum peer):
+ *   - `isUtxoUnspent(txHash, outputIndex)` for replay-defense check 5b
+ *   - `getCurrentSlot()`                   for TTL check 6
  *
- * Both are implemented here as **shims** on top of existing core
- * methods, so x402 works against an unmodified 1.7.7. When ODATANO
- * exposes either method natively (planned ≥1.7.8), we can swap the
- * shim for a direct call without touching downstream code.
+ * Both are called through directly here; no shim layer remains.
  */
 export interface BridgeAsset {
     unit: string;
@@ -49,18 +46,18 @@ export declare function getProtocolParameters(): Promise<unknown>;
 export declare function submitTransaction(signedCborHex: string): Promise<string>;
 /**
  * Current chain tip slot. First-class method on `CardanoClient` since
- * `@odatano/core@1.7.8` — wraps `getLatestBlock().slot` with a
+ * `@odatano/core@1.7.8`, wraps `getLatestBlock().slot` with a
  * `ProviderUnavailableError` translation so consumers don't deal with
  * `null` slots.
  */
 export declare function getCurrentSlot(): Promise<number>;
 /**
  * Check whether a UTxO is still unspent. First-class method since
- * `@odatano/core@1.7.8` — backed by `consumed_by` (Blockfrost) /
+ * `@odatano/core@1.7.8`, backed by `consumed_by` (Blockfrost) /
  * `is_spent` (Koios) / `queryLedgerState/utxo` (Ogmios).
  *
  * Returns `false` for txs that don't exist on chain or for
- * out-of-range output indices — both are "not spendable" from the
+ * out-of-range output indices, both are "not spendable" from the
  * caller's perspective.
  */
 export declare function isUtxoUnspent(txHash: string, outputIndex: number): Promise<boolean>;