@odatano/x402 0.2.0 → 0.3.1

package/srv/facilitator/server.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Reference HTTP facilitator, the server side of `httpFacilitator()`.
+ *
+ * `httpFacilitator()` (in `./http.ts`) is the client wrapper that resource
+ * servers wire into their middleware via the `facilitator` option. This
+ * module is the matching server: a thin Express `Router` exposing the
+ * three endpoints documented in `docs/facilitator-protocol.md`:
+ *
+ *   POST /verify-settle , runs the full pipeline through a `Facilitator`
+ *   GET  /supported     , discovery
+ *   GET  /healthz       , orchestrator health check
+ *
+ * The router is composable, consumers mount it under whatever path /
+ * port / TLS / CORS / rate-limiter they prefer, no opinions baked in.
+ * Auth is a single `auth(req)` hook, callers can implement bearer-token,
+ * mTLS, signed-request, OAuth, etc. There is NO default auth, an
+ * unconfigured router is open; document this loudly in deployment.
+ *
+ * The `onAccepted` callback CANNOT cross the HTTP boundary, the matching
+ * client (`httpFacilitator()`) invokes it locally after the remote returns
+ * `accepted`. To cover the facilitator-side audit need, this router
+ * exposes `onRejected` and `onPending` hooks, fired exactly once per
+ * non-accepted outcome, with the request available for context.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFacilitatorRouter = createFacilitatorRouter;
+const express_1 = __importDefault(require("express"));
+const cds_1 = __importDefault(require("@sap/cds"));
+const defaultLog = cds_1.default.log('x402');
+async function runAudit(result, req, cb, log, label) {
+    if (!cb)
+        return;
+    try {
+        await cb(result, req);
+    }
+    catch (err) {
+        log.warn(`facilitator-server: ${label} hook failed (non-fatal):`, err);
+    }
+}
+/**
+ * Build the facilitator HTTP router. Mount on whatever path you like:
+ *
+ *   const app = express();
+ *   app.use('/v1', createFacilitatorRouter({ auth: bearer(token) }));
+ *   app.listen(4040);
+ *
+ * The router parses its own JSON body, do not mount `express.json()`
+ * upstream with a smaller limit, the inner parser will see an already-
+ * parsed body and skip.
+ */
+function resolveDefaultFacilitator() {
+    // Lazy require so the @odatano/core dependency is pulled in only when
+    // a consumer actually uses the default. Tests and consumers that pass
+    // a custom facilitator (e.g. a chained or mock one) never load core.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { localFacilitator } = require('./adapter');
+    return localFacilitator();
+}
+function createFacilitatorRouter(opts = {}) {
+    const facilitator = opts.facilitator ?? resolveDefaultFacilitator();
+    const log = opts.logger ?? defaultLog;
+    const jsonLimit = opts.jsonLimit ?? '256kb';
+    const router = express_1.default.Router();
+    // Body parser scoped to this router. We DO NOT install a global JSON
+    // parser, callers may already have one with a different limit they
+    // don't want overridden for the rest of their app.
+    const json = express_1.default.json({ limit: jsonLimit });
+    // Auth runs BEFORE body parsing so we don't waste CPU parsing
+    // payloads for unauthenticated callers.
+    router.use(async (req, res, next) => {
+        if (!opts.auth)
+            return next();
+        try {
+            const ok = await opts.auth(req);
+            if (!ok) {
+                res.status(401).json({ error: 'unauthorized' });
+                return;
+            }
+            next();
+        }
+        catch (err) {
+            log.error('facilitator-server: auth hook threw', err);
+            res.status(500).json({ error: 'auth check failed' });
+        }
+    });
+    // ─── POST /verify-settle ─────────────────────────────────────────────
+    router.post('/verify-settle', json, async (req, res) => {
+        const body = req.body;
+        if (!body || typeof body !== 'object') {
+            res.status(400).json({ error: 'request body must be a JSON object' });
+            return;
+        }
+        if (!body.paymentHeader) {
+            // Don't 400 here, the facilitator returns a structured `rejected`
+            // with `missing_payment_header` so clients get a uniform shape.
+        }
+        if (!body.requirementsBody || typeof body.requirementsBody !== 'object') {
+            res.status(400).json({ error: 'requirementsBody is required' });
+            return;
+        }
+        // Strip onAccepted defensively, the wire schema doesn't carry it
+        // and we'd refuse to invoke a foreign callback anyway.
+        const args = {
+            paymentHeader: body.paymentHeader,
+            requirementsBody: body.requirementsBody,
+            ...(body.settlePollBudgetMs !== undefined ? { settlePollBudgetMs: body.settlePollBudgetMs } : {}),
+            ...(body.allowNoTtl ? { allowNoTtl: true } : {}),
+        };
+        let result;
+        try {
+            result = await facilitator.verifyAndSettle(args);
+        }
+        catch (err) {
+            log.error('facilitator-server: verifyAndSettle threw', err);
+            res.status(500).json({ error: err?.message ?? 'internal error' });
+            return;
+        }
+        res.json(result);
+        // Audit hooks fire AFTER the response so a slow audit DB never
+        // delays the buyer's settle round-trip.
+        if (result.kind === 'rejected') {
+            void runAudit(result, req, opts.onRejected, log, 'onRejected');
+        }
+        else if (result.kind === 'pending') {
+            void runAudit(result, req, opts.onPending, log, 'onPending');
+        }
+    });
+    // ─── GET /supported ──────────────────────────────────────────────────
+    router.get('/supported', async (_req, res) => {
+        if (!facilitator.supported) {
+            // Spec allows minimal facilitators to omit /supported. We surface
+            // 501 so the caller can distinguish "endpoint missing" from
+            // "facilitator unavailable".
+            res.status(501).json({ error: 'facilitator does not implement supported()' });
+            return;
+        }
+        try {
+            const s = await facilitator.supported();
+            res.json(s);
+        }
+        catch (err) {
+            log.error('facilitator-server: supported() threw', err);
+            res.status(500).json({ error: err?.message ?? 'internal error' });
+        }
+    });
+    // ─── GET /healthz ────────────────────────────────────────────────────
+    // Orchestrator-friendly liveness probe. NOT auth-gated, on purpose:
+    // k8s / Cloud Run probes don't carry bearer tokens. If the auth hook
+    // ran first and rejected the request, this route would be unreachable
+    // to probes. We register healthz on a side-router that bypasses auth.
+    // Implementation note: Express runs middlewares in registration order
+    // for a router, so we install healthz on a SEPARATE router and mount
+    // it before the auth middleware on the returned router. The cleanest
+    // way: build healthz on a sub-router and mount FIRST.
+    //
+    // (Restructure: rebuild the router with healthz prepended.)
+    const outer = express_1.default.Router();
+    outer.get('/healthz', (_req, res) => {
+        res.json({ ok: true });
+    });
+    outer.use(router);
+    return outer;
+}

package/srv/facilitator/settle.d.ts

@@ -2,7 +2,7 @@
  * Submit a signed payment tx to Cardano and confirm settlement.
  *
  * Confirmation policy (v2 spec): accept after first chain sighting.
- * `mempool` status is explicitly discouraged in v2 — Cardano's
+ * `mempool` status is explicitly discouraged in v2, Cardano's
  * Ouroboros Praos has probabilistic finality, so "in mempool" gives
  * no economic guarantee. We poll for first-chain-sighting via
  * `getTransactionByHash` (resolves to non-null when Blockfrost / Koios
@@ -10,7 +10,7 @@
  *
  * Confirmation budget: middleware paths use ~60s (covers preprod's
  * worst-case block time of ~20s plus indexer lag). On timeout we
- * return `{ confirmed: false, pending: true }` — the spec contract is
+ * return `{ confirmed: false, pending: true }`, the spec contract is
  * that the buyer retries with the same `PAYMENT-SIGNATURE`. Replay
  * defense (on-chain via UTxO nonce) ensures only one retry actually
  * gets served.

package/srv/facilitator/settle.js

@@ -3,7 +3,7 @@
  * Submit a signed payment tx to Cardano and confirm settlement.
  *
  * Confirmation policy (v2 spec): accept after first chain sighting.
- * `mempool` status is explicitly discouraged in v2 — Cardano's
+ * `mempool` status is explicitly discouraged in v2, Cardano's
  * Ouroboros Praos has probabilistic finality, so "in mempool" gives
  * no economic guarantee. We poll for first-chain-sighting via
  * `getTransactionByHash` (resolves to non-null when Blockfrost / Koios
@@ -11,7 +11,7 @@
  *
  * Confirmation budget: middleware paths use ~60s (covers preprod's
  * worst-case block time of ~20s plus indexer lag). On timeout we
- * return `{ confirmed: false, pending: true }` — the spec contract is
+ * return `{ confirmed: false, pending: true }`, the spec contract is
  * that the buyer retries with the same `PAYMENT-SIGNATURE`. Replay
  * defense (on-chain via UTxO nonce) ensures only one retry actually
  * gets served.
@@ -55,7 +55,7 @@ const bridge = __importStar(require("../bridge"));
 const errors_1 = require("../core/errors");
 /**
  * Patterns surfaced by the submit step that mean "the tx is already
- * known to the network" — either in mempool or already mined. In
+ * known to the network", either in mempool or already mined. In
  * both cases we should NOT treat as failure; we should fall through
  * to polling.
  *
@@ -101,7 +101,7 @@ async function settle({ signedTxCborHex, expectedTxHash, pollBudgetMs = 60_000,
         }
     }
     // Cross-check: backend's hash must match our locally-computed one.
-    // If it doesn't, something is structurally off — bail loudly.
+    // If it doesn't, something is structurally off, bail loudly.
     if (submittedHash && submittedHash.toLowerCase() !== expectedTxHash.toLowerCase()) {
         return {
             confirmed: false,

package/srv/facilitator/verify.d.ts

@@ -5,7 +5,7 @@
  * Pipeline (v2):
  *   1. decode               (PAYMENT-SIGNATURE → DecodedPayment)
  *   2. validate             (6 mandatory checks, pure)
- *   3. checkNonceUnspent    (chain — UTxO still spendable)
+ *   3. checkNonceUnspent    (chain, UTxO still spendable)
  *   4. settle               (submit + poll-until-confirmed)
  *   5. onAccepted callback  (consumer-side audit, best-effort)
  *
@@ -17,7 +17,7 @@
  *     CBOR whose nonce was already spent will fail at the network
  *     level anyway, and we want to return a precise REPLAY code
  *     instead of a generic SUBMIT_FAILED.
- *   - `onAccepted` runs ONLY after settle confirms — we never call it
+ *   - `onAccepted` runs ONLY after settle confirms, we never call it
  *     for pending/rejected outcomes.
  */
 import { type X402Code } from '../core/errors';
@@ -26,19 +26,19 @@ export type ProcessKind = 'accepted' | 'rejected' | 'pending';
 export interface ProcessArgs {
     /** Raw header value (undefined if missing). */
     paymentHeader: string | string[] | undefined;
-    /** Full 402 body — the validator inspects `accepts[0]`. */
+    /** Full 402 body, the validator inspects `accepts[0]`. */
     requirementsBody: PaymentRequirementsBody;
     /** Optional override of the settle poll budget (ms). Default 60_000. */
     settlePollBudgetMs?: number;
     /**
      * Optional: callback invoked on successful payment. Use for consumer-
      * side audit (e.g. CHAINFEED writing to FeedReads, ODATAPAY writing to
-     * Receipts). Throws here are swallowed and logged — the canonical
+     * Receipts). Throws here are swallowed and logged, the canonical
      * record is on chain.
      */
     onAccepted?: (claim: PaymentClaim) => void | Promise<void>;
     /**
-     * Optional: TTL check tolerance. Default false — txs without a
+     * Optional: TTL check tolerance. Default false, txs without a
      * validity-range upper bound are rejected.
      */
     allowNoTtl?: boolean;

package/srv/facilitator/verify.js

@@ -6,7 +6,7 @@
  * Pipeline (v2):
  *   1. decode               (PAYMENT-SIGNATURE → DecodedPayment)
  *   2. validate             (6 mandatory checks, pure)
- *   3. checkNonceUnspent    (chain — UTxO still spendable)
+ *   3. checkNonceUnspent    (chain, UTxO still spendable)
  *   4. settle               (submit + poll-until-confirmed)
  *   5. onAccepted callback  (consumer-side audit, best-effort)
  *
@@ -18,7 +18,7 @@
  *     CBOR whose nonce was already spent will fail at the network
  *     level anyway, and we want to return a precise REPLAY code
  *     instead of a generic SUBMIT_FAILED.
- *   - `onAccepted` runs ONLY after settle confirms — we never call it
+ *   - `onAccepted` runs ONLY after settle confirms, we never call it
  *     for pending/rejected outcomes.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -62,7 +62,6 @@ exports.process = process;
 const cds_1 = __importDefault(require("@sap/cds"));
 const decode_1 = require("../core/decode");
 const validate_1 = require("../core/validate");
-const requirements_1 = require("../core/requirements");
 const errors_1 = require("../core/errors");
 const nonce_1 = require("./nonce");
 const settle_1 = require("./settle");
@@ -95,8 +94,10 @@ async function process(args) {
             requirementsBody: args.requirementsBody,
         };
     }
-    const requirements = (0, requirements_1.flatRequirements)(args.requirementsBody);
     // ─── 1. Decode ──────────────────────────────────────────────────────
+    // Decode happens BEFORE we pick a requirements entry, the picker needs
+    // to know which (payTo, asset) the tx actually credits to choose
+    // among multi-accept options.
     let decoded;
     try {
         decoded = (0, decode_1.decode)(headerStr);
@@ -112,6 +113,19 @@ async function process(args) {
         }
         throw err;
     }
+    // Pick the accepts[] entry the buyer paid against. For single-entry
+    // bodies this is the same as the old `flatRequirements`; for
+    // multi-accept it routes the tx to the matching seller option.
+    const picked = (0, validate_1.pickRequirement)(decoded, args.requirementsBody);
+    if (!picked.ok) {
+        return {
+            kind: 'rejected',
+            code: picked.code,
+            reason: picked.reason,
+            requirementsBody: args.requirementsBody,
+        };
+    }
+    const requirements = picked.entry;
     // ─── 2. Validate (6 checks, pure) ───────────────────────────────────
     let currentSlot;
     try {
@@ -137,7 +151,7 @@ async function process(args) {
             requirementsBody: args.requirementsBody,
         };
     }
-    // ─── 3. Nonce — UTxO still unspent (chain) ──────────────────────────
+    // ─── 3. Nonce, UTxO still unspent (chain) ──────────────────────────
     const nonceResult = await (0, nonce_1.checkNonceUnspent)({
         txHash: decoded.nonce.txHash,
         outputIndex: decoded.nonce.index,

package/srv/helpers/build-unsigned-tx.d.ts

@@ -9,9 +9,9 @@
  * `payload.transaction` in the PAYMENT-SIGNATURE envelope.
  *
  * Diff vs v1 of CHAINFEED's same-named helper:
- *   - Asset-agnostic — parses requirements.asset as a v2 string
+ *   - Asset-agnostic, parses requirements.asset as a v2 string
  *     (`'lovelace'` or `'<policy>.<nameHex>'`).
- *   - Returns `nonceRef` alongside the unsigned CBOR — the server
+ *   - Returns `nonceRef` alongside the unsigned CBOR, the server
  *     picks one of the buyer's chosen inputs as the v2 nonce UTxO,
  *     so the browser doesn't have to reason about it.
  *
@@ -26,7 +26,7 @@ import type { PaymentRequirementEntry } from '../core/types';
 export interface BuildUnsignedTxArgs {
     /** Buyer's bech32 address (must be Base or Enterprise with VKey-hash payment cred). */
     buyerBech32: string;
-    /** A single accepts[] entry — call `flatRequirements(body)` to extract. */
+    /** A single accepts[] entry, call `flatRequirements(body)` to extract. */
     requirements: PaymentRequirementEntry;
     /**
      * Optional TTL in slots from "now" (= current chain tip slot).
@@ -37,9 +37,9 @@ export interface BuildUnsignedTxArgs {
 export interface UnsignedTxResult {
     /** CBOR hex of the unsigned tx (empty witness set). Ready for CIP-30 signTx. */
     unsignedTxCborHex: string;
-    /** Hex tx hash — what the buyer's wallet will display. */
+    /** Hex tx hash, what the buyer's wallet will display. */
     txHashHex: string;
-    /** Buyer's payment-cred VKey hash — wallet must sign for this. */
+    /** Buyer's payment-cred VKey hash, wallet must sign for this. */
     requiredSignerHex: string;
     /** v2 nonce reference `<txHash>#<index>`, picked from the buyer's chosen inputs. */
     nonceRef: string;

package/srv/helpers/build-unsigned-tx.js

@@ -10,9 +10,9 @@
  * `payload.transaction` in the PAYMENT-SIGNATURE envelope.
  *
  * Diff vs v1 of CHAINFEED's same-named helper:
- *   - Asset-agnostic — parses requirements.asset as a v2 string
+ *   - Asset-agnostic, parses requirements.asset as a v2 string
  *     (`'lovelace'` or `'<policy>.<nameHex>'`).
- *   - Returns `nonceRef` alongside the unsigned CBOR — the server
+ *   - Returns `nonceRef` alongside the unsigned CBOR, the server
  *     picks one of the buyer's chosen inputs as the v2 nonce UTxO,
  *     so the browser doesn't have to reason about it.
  *
@@ -189,7 +189,7 @@ async function buildUnsignedPaymentTx(args) {
     const unsigned = CSL.Transaction.new(txBody, emptyWits);
     // Pick the first input as the v2 nonce UTxO.
     // It MUST appear in tx.inputs (which it does by construction) and be
-    // unspent (which it is — we just queried it from the buyer's UTxO set).
+    // unspent (which it is, we just queried it from the buyer's UTxO set).
     const nonceInput = inputs[0];
     const nonceRef = `${nonceInput.txHash}#${nonceInput.outputIndex}`;
     return {

package/srv/helpers/verify-confirmed.d.ts

@@ -7,7 +7,7 @@
  * the right asset to the right address on the right network.
  *
  * Differences from the middleware path (`facilitator/verify.ts`):
- *   - No envelope, no PAYMENT-SIGNATURE header — just a tx hash.
+ *   - No envelope, no PAYMENT-SIGNATURE header, just a tx hash.
  *   - The tx is presumed already on-chain (the network already accepted
  *     witnesses), so we skip the witness-presence check.
  *   - No on-chain nonce check: replay defense for confirmed-payment

package/srv/helpers/verify-confirmed.js

@@ -8,7 +8,7 @@
  * the right asset to the right address on the right network.
  *
  * Differences from the middleware path (`facilitator/verify.ts`):
- *   - No envelope, no PAYMENT-SIGNATURE header — just a tx hash.
+ *   - No envelope, no PAYMENT-SIGNATURE header, just a tx hash.
  *   - The tx is presumed already on-chain (the network already accepted
  *     witnesses), so we skip the witness-presence check.
  *   - No on-chain nonce check: replay defense for confirmed-payment

package/srv/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @odatano/x402 — public API barrel.
+ * @odatano/x402, public API barrel.
  *
  * Cardano-x402-v2 payment library for SAP CAP applications.
  *
@@ -27,7 +27,7 @@
  *     }
  *   }
  *
- *   // 3. Programmatic — verify a confirmed payment by tx hash
+ *   // 3. Programmatic, verify a confirmed payment by tx hash
  *   import { verifyConfirmedPayment } from '@odatano/x402';
  *   const r = await verifyConfirmedPayment({
  *     txHash, requiredAmount, asset, payTo, network,
@@ -45,6 +45,7 @@ export { settle, type SettleArgs, type SettleResult } from './facilitator/settle
 export { checkNonceUnspent, type NonceCheckArgs, type NonceResult } from './facilitator/nonce';
 export { localFacilitator, type Facilitator, type FacilitatorVerifyAndSettleArgs, type FacilitatorResult, type FacilitatorSupportedResult, } from './facilitator/adapter';
 export { httpFacilitator, type HttpFacilitatorConfig, } from './facilitator/http';
+export { createFacilitatorRouter, type CreateFacilitatorRouterOptions, type FacilitatorServerLogger, } from './facilitator/server';
 export { verifyConfirmedPayment, type VerifyConfirmedArgs, type VerifyConfirmedResult, } from './helpers/verify-confirmed';
 export { buildUnsignedPaymentTx, type BuildUnsignedTxArgs, type UnsignedTxResult, } from './helpers/build-unsigned-tx';
 export { x402Middleware, type X402MiddlewareOptions } from './middleware/express';
@@ -54,5 +55,6 @@ export { x402Axios } from './client/axios';
 export { encodePaymentEnvelope, type EncodeEnvelopeArgs, } from './client/envelope';
 export { createBridgePayHandler, type BridgePayHandlerOptions, } from './client/pay-handlers';
 export type { PayHandler, PayHandlerResult, AcceptsSelector, X402ClientOptions, } from './client/types';
+export { X402PaymentError, parseErrorCode, paymentErrorFromBody, type X402PaymentErrorKind, type X402PaymentErrorInit, } from './client/errors';
 export * as bridge from './bridge';
 //# sourceMappingURL=index.d.ts.map

package/srv/index.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * @odatano/x402 — public API barrel.
+ * @odatano/x402, public API barrel.
  *
  * Cardano-x402-v2 payment library for SAP CAP applications.
  *
@@ -28,7 +28,7 @@
  *     }
  *   }
  *
- *   // 3. Programmatic — verify a confirmed payment by tx hash
+ *   // 3. Programmatic, verify a confirmed payment by tx hash
  *   import { verifyConfirmedPayment } from '@odatano/x402';
  *   const r = await verifyConfirmedPayment({
  *     txHash, requiredAmount, asset, payTo, network,
@@ -68,7 +68,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bridge = exports.createBridgePayHandler = exports.encodePaymentEnvelope = exports.x402Axios = exports.x402Fetch = exports.gateService = exports.x402Middleware = exports.buildUnsignedPaymentTx = exports.verifyConfirmedPayment = exports.httpFacilitator = exports.localFacilitator = exports.checkNonceUnspent = exports.settle = exports.verifyPayment = exports.Codes = exports.X402Error = exports.networksMatch = exports.isNetwork = exports.parseNetwork = exports.buildAssetString = exports.parseAsset = exports.validatePayment = exports.decode = exports.flatRequirements = exports.buildEntry = exports.buildPaymentRequirements = void 0;
+exports.bridge = exports.paymentErrorFromBody = exports.parseErrorCode = exports.X402PaymentError = exports.createBridgePayHandler = exports.encodePaymentEnvelope = exports.x402Axios = exports.x402Fetch = exports.gateService = exports.x402Middleware = exports.buildUnsignedPaymentTx = exports.verifyConfirmedPayment = exports.createFacilitatorRouter = exports.httpFacilitator = exports.localFacilitator = exports.checkNonceUnspent = exports.settle = exports.verifyPayment = exports.Codes = exports.X402Error = exports.networksMatch = exports.isNetwork = exports.parseNetwork = exports.buildAssetString = exports.parseAsset = exports.validatePayment = exports.decode = exports.flatRequirements = exports.buildEntry = exports.buildPaymentRequirements = void 0;
 // ─── Core builders / validators (pure) ────────────────────────────────
 var requirements_1 = require("./core/requirements");
 Object.defineProperty(exports, "buildPaymentRequirements", { enumerable: true, get: function () { return requirements_1.buildPaymentRequirements; } });
@@ -102,6 +102,8 @@ var adapter_1 = require("./facilitator/adapter");
 Object.defineProperty(exports, "localFacilitator", { enumerable: true, get: function () { return adapter_1.localFacilitator; } });
 var http_1 = require("./facilitator/http");
 Object.defineProperty(exports, "httpFacilitator", { enumerable: true, get: function () { return http_1.httpFacilitator; } });
+var server_1 = require("./facilitator/server");
+Object.defineProperty(exports, "createFacilitatorRouter", { enumerable: true, get: function () { return server_1.createFacilitatorRouter; } });
 // ─── Helpers ──────────────────────────────────────────────────────────
 var verify_confirmed_1 = require("./helpers/verify-confirmed");
 Object.defineProperty(exports, "verifyConfirmedPayment", { enumerable: true, get: function () { return verify_confirmed_1.verifyConfirmedPayment; } });
@@ -121,5 +123,9 @@ var envelope_1 = require("./client/envelope");
 Object.defineProperty(exports, "encodePaymentEnvelope", { enumerable: true, get: function () { return envelope_1.encodePaymentEnvelope; } });
 var pay_handlers_1 = require("./client/pay-handlers");
 Object.defineProperty(exports, "createBridgePayHandler", { enumerable: true, get: function () { return pay_handlers_1.createBridgePayHandler; } });
+var errors_2 = require("./client/errors");
+Object.defineProperty(exports, "X402PaymentError", { enumerable: true, get: function () { return errors_2.X402PaymentError; } });
+Object.defineProperty(exports, "parseErrorCode", { enumerable: true, get: function () { return errors_2.parseErrorCode; } });
+Object.defineProperty(exports, "paymentErrorFromBody", { enumerable: true, get: function () { return errors_2.paymentErrorFromBody; } });
 // ─── Bridge (lower-level: exposed for advanced consumers) ─────────────
 exports.bridge = __importStar(require("./bridge"));

package/srv/middleware/cap.d.ts

@@ -3,7 +3,7 @@
  *
  * CAP services receive requests through `srv.before(...)` / `srv.on(...)`
  * handlers, not Express middleware. For OData-served entities, the 402
- * needs to come from `req.reject(402, body)` — the response is built by
+ * needs to come from `req.reject(402, body)`, the response is built by
  * CAP, not by `res.status(...)`.
  *
  * Usage:
@@ -26,18 +26,23 @@
  */
 import cds from '@sap/cds';
 import { type Facilitator } from '../facilitator/adapter';
-import type { AssetTransferMethod, Network, PaymentClaim } from '../core/types';
+import type { AssetTransferMethod, Network, PaymentClaim, PriceSpec, PriceResolver } from '../core/types';
 export interface X402CapOptions {
     payTo: string;
     network: Network | string;
     asset: string;
-    /** Single price (applies to all gated events). */
-    priceUnits?: string | number | bigint;
     /**
-     * Per-event prices. Keys are CAP event names (entity name for CRUD,
-     * action name for actions). Events absent here pass through.
+     * Single price (applies to all gated events). May be a scalar, a
+     * `RouteOption`, or a `RouteOption[]` (multi-accept).
      */
-    routePricing?: Record<string, string | number | bigint>;
+    priceUnits?: PriceSpec;
+    /**
+     * Per-event prices. Either a static map (keys are CAP entity or
+     * action names; events absent here pass through) or a `PriceResolver`
+     * function for dynamic pricing. Resolver returning `null` skips the
+     * gate; otherwise returns a scalar / `RouteOption` / `RouteOption[]`.
+     */
+    routePricing?: Record<string, PriceSpec> | PriceResolver;
     description?: string;
     mimeType?: string;
     assetTransferMethod?: AssetTransferMethod;
@@ -52,9 +57,42 @@ export interface X402CapOptions {
      * builder to embed pair / entity id in the resource string.
      */
     resourceUrl?: (req: cds.Request) => string;
+    /**
+     * Persist accepted payments to a CDS entity. Set to `true` to use the
+     * default entity `odatano.x402.X402Receipts` (shipped in the plugin's
+     * `db/x402-receipts.cds`), or pass `{ entity: 'my.namespace.MyTable' }`
+     * to write to a consumer-defined table with the same shape.
+     *
+     * INSERT runs AFTER settle confirms, BEFORE the 200 response. INSERT
+     * failures are logged and never block the response, the canonical
+     * record is on chain. Pair with `onAccepted` if you need side-effects
+     * beyond persistence.
+     */
+    receipts?: boolean | {
+        entity?: string;
+    };
+    /**
+     * Time-limited grants: pay once, get `ttlSeconds` of free access to
+     * the same route. On accepted payment, the gate issues an opaque
+     * token and returns it via the `X-PAYMENT-GRANT` response header.
+     * The buyer presents that token via the `X-PAYMENT-GRANT` request
+     * header on subsequent calls; while it's valid the gate bypasses the
+     * 402 + verify+settle pipeline.
+     *
+     * Default `ttlSeconds`: 3600. Default entity:
+     * `odatano.x402.X402Grants` (shipped in `db/x402-grants.cds`).
+     *
+     * Grant errors (issue or lookup) are SWALLOWED. A failing DB never
+     * denies a paying buyer their response; it just means no
+     * subscription short-circuit until the DB recovers.
+     */
+    grants?: boolean | {
+        ttlSeconds?: number;
+        entity?: string;
+    };
     /**
      * Facilitator implementation handling verify+settle. Default
-     * `localFacilitator()` — in-process via `@odatano/core`. Use
+     * `localFacilitator()`, in-process via `@odatano/core`. Use
      * `httpFacilitator({ url, apiKey })` to delegate to a hosted service.
      */
     facilitator?: Facilitator;
@@ -65,7 +103,7 @@ export interface X402CapOptions {
  *
  * The gate registers as `srv.before('*', ...)` which fires for every
  * event on the service. We filter inside the handler based on
- * `routePricing` — registering per-entity would lose actions, and
+ * `routePricing`, registering per-entity would lose actions, and
  * per-event arrays don't support the `'*'` fallback we want.
  */
 export declare function gateService<S extends cds.Service>(srv: S, opts: X402CapOptions): S;