@odatano/x402 0.1.0 → 0.3.0

package/srv/middleware/cap.js

@@ -4,7 +4,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:
@@ -32,44 +32,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.gateService = gateService;
 const cds_1 = __importDefault(require("@sap/cds"));
 const requirements_1 = require("../core/requirements");
-const verify_1 = require("../facilitator/verify");
+const adapter_1 = require("../facilitator/adapter");
 const errors_1 = require("../core/errors");
+const pricing_1 = require("./pricing");
+const receipts_1 = require("./receipts");
+const grants_1 = require("./grants");
 const log = cds_1.default.log('x402');
+function getAllHeaders(req) {
+    const httpReq = req;
+    return (httpReq.http?.req?.headers ?? httpReq._?.req?.headers ?? {});
+}
+function getHeader(req, name) {
+    const v = getAllHeaders(req)[name];
+    return Array.isArray(v) ? v[0] : v;
+}
 /**
- * Resolve the routePricing key for a CAP request.
+ * Build the `PricingContext` for `resolvePrice` from a CAP request.
  *
- * CAP fires two distinct shapes:
- *   - CRUD on an entity:  req.event === 'READ' | 'CREATE' | 'UPDATE' | 'DELETE'
- *                         req.target.name === '<Service>.<Entity>'
- *   - Action call:        req.event === '<actionName>'
- *                         req.target may be empty or the bound-entity target
+ * CAP fires two distinct event shapes:
+ *   - CRUD on entity:  req.event === 'READ' | 'CREATE' | ...   ; req.target.name === '<Service>.<Entity>'
+ *   - Action call:     req.event === '<actionName>'             ; req.target may be empty or bound entity
  *
- * routePricing keys are meant to be human-readable identifiers (entity
- * names or action names), so we try the entity name first (more specific)
- * and fall back to the event verb. Either match wins; both miss falls
- * through to opts.priceUnits or null.
+ * We surface both `event` (the verb / action name) and `target` (the
+ * fully-qualified entity name when present), giving the resolver enough
+ * to discriminate CRUD-vs-action and per-entity pricing.
  */
-function pickPriceUnits(req, opts) {
-    if (opts.routePricing) {
-        const event = String(req.event ?? '');
-        const targetName = req.target?.name ?? '';
-        const entitySegment = targetName.split('.').pop() ?? '';
-        const price = opts.routePricing[entitySegment] ?? opts.routePricing[event];
-        if (price != null)
-            return String(price);
-        if (opts.priceUnits != null)
-            return String(opts.priceUnits);
-        return null;
-    }
-    return opts.priceUnits != null ? String(opts.priceUnits) : null;
-}
-function getHeader(req, name) {
-    // CAP's req.http?.req exposes the underlying express request. Fall
-    // back to req._.req for older shapes.
-    const httpReq = req;
-    const hdrs = httpReq.http?.req?.headers ?? httpReq._?.req?.headers;
-    const v = hdrs?.[name];
-    return Array.isArray(v) ? v[0] : v;
+function capContext(req) {
+    const event = String(req.event ?? '');
+    const target = req.target?.name;
+    return {
+        event,
+        ...(target ? { target } : {}),
+        headers: getAllHeaders(req),
+    };
 }
 function getResourceUrl(req, opts) {
     if (opts.resourceUrl)
@@ -83,7 +78,7 @@ function getResourceUrl(req, opts) {
  *
  * 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.
  */
 function gateService(srv, opts) {
@@ -96,12 +91,41 @@ function gateService(srv, opts) {
     if (opts.priceUnits == null && !opts.routePricing) {
         throw new Error('gateService: priceUnits or routePricing is required');
     }
+    const facilitator = opts.facilitator ?? (0, adapter_1.localFacilitator)();
+    const receiptsEntity = (0, receipts_1.resolveReceiptsEntity)(opts.receipts);
+    const grantsEntity = (0, grants_1.resolveGrantsEntity)(opts.grants);
+    const grantTtlSeconds = (0, grants_1.resolveGrantTtl)(opts.grants);
     srv.before('*', async function x402CapGate(req) {
-        const priceUnits = pickPriceUnits(req, opts);
-        if (priceUnits == null)
+        let options;
+        try {
+            options = await (0, pricing_1.resolvePrice)(opts, capContext(req));
+        }
+        catch (err) {
+            log.error('x402 CAP gate pricing resolver threw', err);
+            req
+                .reject(500, 'x402 pricing error');
+            return;
+        }
+        if (options == null)
             return; // unmapped → pass through
-        const requirementsBody = (0, requirements_1.buildPaymentRequirements)({
-            amount: priceUnits,
+        // ─── Grant short-circuit ────────────────────────────────────────────
+        // If the buyer presents a valid X-PAYMENT-GRANT for THIS route, skip
+        // the whole 402 + verify+settle pipeline. We run the grant check
+        // AFTER pricing resolution so passes-through paths don't hit the DB,
+        // but BEFORE building the requirements body so we save the wasted
+        // work when a grant is valid.
+        if (grantsEntity) {
+            const grantToken = getHeader(req, 'x-payment-grant');
+            if (grantToken) {
+                const route = getResourceUrl(req, opts);
+                const result = await (0, grants_1.lookupGrant)(grantsEntity, grantToken, route);
+                if (result.kind === 'valid')
+                    return; // bypass gate entirely
+                // expired / not-found → fall through to the payment path
+            }
+        }
+        const requirementsBody = (0, requirements_1.buildPaymentRequirementsMulti)({
+            options,
             asset: opts.asset,
             payTo: opts.payTo,
             network: opts.network,
@@ -125,16 +149,26 @@ function gateService(srv, opts) {
         }
         if (opts.allowNoTtl)
             processArgs.allowNoTtl = true;
-        if (opts.onAccepted) {
-            processArgs.onAccepted = (claim) => opts.onAccepted(claim, req);
+        // Chain receipts INSERT before the user's onAccepted so consumers
+        // can read back the persisted row inside their hook if they want to.
+        // Receipts errors are swallowed inside `persistReceipt`, so the
+        // user's onAccepted still runs.
+        if (receiptsEntity || opts.onAccepted) {
+            processArgs.onAccepted = async (claim) => {
+                if (receiptsEntity) {
+                    await (0, receipts_1.persistReceipt)(receiptsEntity, claim, getResourceUrl(req, opts));
+                }
+                if (opts.onAccepted)
+                    await opts.onAccepted(claim, req);
+            };
         }
         // ─── Run the pipeline. Only the orchestrator's internal errors are
-        //     trapped here — `req.reject` MUST be called outside this catch
+        //     trapped here, `req.reject` MUST be called outside this catch
         //     because it throws synchronously, and re-catching that throw
         //     would translate the 402 into a 500. ─────────────────────────
         let result;
         try {
-            result = await (0, verify_1.process)(processArgs);
+            result = await facilitator.verifyAndSettle(processArgs);
         }
         catch (err) {
             log.error('x402 CAP gate internal error', err);
@@ -144,12 +178,22 @@ function gateService(srv, opts) {
             return;
         }
         // ─── Apply the result. From here on, `req.reject` is called once
-        //     and we let its synchronous throw bubble — CAP's dispatcher
+        //     and we let its synchronous throw bubble, CAP's dispatcher
         //     wraps it into the OData error response.
         if (result.kind === 'accepted') {
             req.payment = result.payment;
             const httpRes = req.http?.res;
             httpRes?.setHeader('X-PAYMENT-RESPONSE', result.paymentResponseB64);
+            // Issue a grant token, the buyer's next request can short-circuit
+            // the 402 + settle path until expiry. Best-effort: a failed
+            // issue just means no header gets set; the response is unaffected.
+            if (grantsEntity) {
+                const grant = await (0, grants_1.issueGrant)(grantsEntity, result.payment, getResourceUrl(req, opts), grantTtlSeconds);
+                if (grant) {
+                    httpRes?.setHeader('X-PAYMENT-GRANT', grant.token);
+                    httpRes?.setHeader('X-PAYMENT-GRANT-EXPIRES', grant.expiresAt);
+                }
+            }
             return;
         }
         // rejected | pending → 402 with the requirements body

package/srv/middleware/express.d.ts

@@ -6,8 +6,8 @@
  * without paying (e.g. OData `$metadata`, `$batch` previews).
  *
  * Two pricing modes:
- *   1. `priceUnits`   — single price for everything under this mount.
- *   2. `routePricing` — { 'EntityOrActionName': 'priceUnits' }, keyed
+ *   1. `priceUnits`  , single price for everything under this mount.
+ *   2. `routePricing`, { 'EntityOrActionName': 'priceUnits' }, keyed
  *                       by the last URL segment (with OData function
  *                       args stripped). Unmapped paths pass through.
  *
@@ -17,7 +17,8 @@
  * can extract the code without breaking wire format.
  */
 import type { Request, RequestHandler } from 'express';
-import type { AssetTransferMethod, PaymentClaim, Network } from '../core/types';
+import { type Facilitator } from '../facilitator/adapter';
+import type { AssetTransferMethod, PaymentClaim, Network, PriceSpec, PriceResolver } from '../core/types';
 declare module 'express-serve-static-core' {
     interface Request {
         payment?: PaymentClaim;
@@ -31,13 +32,18 @@ export interface X402MiddlewareOptions {
     /** v2 asset string: 'lovelace' or '<policy>.<nameHex>'. */
     asset: string;
     /**
-     * Single price for everything under this mount. Mutually exclusive
-     * with `routePricing` (but coexistable: routePricing wins where
-     * defined, falls back to priceUnits otherwise).
+     * Single price for everything under this mount. May be a scalar, a
+     * `RouteOption`, or a `RouteOption[]` (multi-accept).
+     * Coexists with `routePricing`: routePricing wins where defined,
+     * falls back to priceUnits otherwise.
      */
-    priceUnits?: string | number | bigint;
-    /** Per-route prices keyed by the URL's last segment. */
-    routePricing?: Record<string, string | number | bigint>;
+    priceUnits?: PriceSpec;
+    /**
+     * Per-route prices keyed by the URL's last segment, OR a dynamic
+     * `PriceResolver` function. Resolver returning `null` passes through;
+     * otherwise returns scalar / `RouteOption` / `RouteOption[]`.
+     */
+    routePricing?: Record<string, PriceSpec> | PriceResolver;
     /** Regex of paths that bypass payment (default: $metadata, $batch, root, /index). */
     skipPaths?: RegExp;
     /** Shown in `accepts[0].resource.description`. */
@@ -60,6 +66,13 @@ export interface X402MiddlewareOptions {
      * block serving the response.
      */
     onAccepted?: (claim: PaymentClaim, req: Request) => void | Promise<void>;
+    /**
+     * Facilitator implementation handling verify+settle. Default
+     * `localFacilitator()`, runs the pipeline in-process via
+     * `@odatano/core`. Use `httpFacilitator({ url, apiKey })` to delegate
+     * to a hosted service.
+     */
+    facilitator?: Facilitator;
 }
 /** Build the Express middleware. */
 export declare function x402Middleware(opts: X402MiddlewareOptions): RequestHandler;

package/srv/middleware/express.js

@@ -7,8 +7,8 @@
  * without paying (e.g. OData `$metadata`, `$batch` previews).
  *
  * Two pricing modes:
- *   1. `priceUnits`   — single price for everything under this mount.
- *   2. `routePricing` — { 'EntityOrActionName': 'priceUnits' }, keyed
+ *   1. `priceUnits`  , single price for everything under this mount.
+ *   2. `routePricing`, { 'EntityOrActionName': 'priceUnits' }, keyed
  *                       by the last URL segment (with OData function
  *                       args stripped). Unmapped paths pass through.
  *
@@ -24,22 +24,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.x402Middleware = x402Middleware;
 const cds_1 = __importDefault(require("@sap/cds"));
 const requirements_1 = require("../core/requirements");
-const verify_1 = require("../facilitator/verify");
+const adapter_1 = require("../facilitator/adapter");
 const errors_1 = require("../core/errors");
+const pricing_1 = require("./pricing");
 const log = cds_1.default.log('x402');
-function pickPriceUnits(req, opts) {
-    if (opts.routePricing) {
-        // Last URL segment, OData function-args stripped:
-        //   /odata/v4/price/getBestPrice(pair='ADA-USD') → getBestPrice
-        const segment = (req.path.split('/').pop() ?? '').split('(')[0];
-        const price = opts.routePricing[segment];
-        if (price != null)
-            return String(price);
-        if (opts.priceUnits != null)
-            return String(opts.priceUnits);
-        return null; // unmapped under routePricing = pass through
-    }
-    return opts.priceUnits != null ? String(opts.priceUnits) : null;
+function expressContext(req) {
+    // Last URL segment with OData function-args stripped:
+    //   /odata/v4/price/getBestPrice(pair='ADA-USD') → getBestPrice
+    const segment = (req.path.split('/').pop() ?? '').split('(')[0] ?? '';
+    return {
+        event: segment,
+        path: req.path,
+        method: req.method,
+        headers: req.headers,
+        query: req.query,
+    };
 }
 /** Build the Express middleware. */
 function x402Middleware(opts) {
@@ -53,15 +52,16 @@ function x402Middleware(opts) {
         throw new Error('x402Middleware: priceUnits or routePricing is required');
     }
     const skipPaths = opts.skipPaths ?? /(^\/?$|\$metadata|\$batch|^\/?\?|^\/index)/i;
+    const facilitator = opts.facilitator ?? (0, adapter_1.localFacilitator)();
     return async function x402Express(req, res, next) {
         try {
             if (skipPaths.test(req.path))
                 return next();
-            const priceUnits = pickPriceUnits(req, opts);
-            if (priceUnits == null)
+            const options = await (0, pricing_1.resolvePrice)(opts, expressContext(req));
+            if (options == null)
                 return next(); // unmapped path = pass through
-            const requirementsBody = (0, requirements_1.buildPaymentRequirements)({
-                amount: priceUnits,
+            const requirementsBody = (0, requirements_1.buildPaymentRequirementsMulti)({
+                options,
                 asset: opts.asset,
                 payTo: opts.payTo,
                 network: opts.network,
@@ -88,7 +88,7 @@ function x402Middleware(opts) {
             if (opts.onAccepted) {
                 processArgs.onAccepted = (claim) => opts.onAccepted(claim, req);
             }
-            const result = await (0, verify_1.process)(processArgs);
+            const result = await facilitator.verifyAndSettle(processArgs);
             if (result.kind === 'accepted') {
                 res.setHeader('X-PAYMENT-RESPONSE', result.paymentResponseB64);
                 req.payment = result.payment;

package/srv/middleware/grants.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CAP-backed time-limited grants.
+ *
+ * Used by `gateService` when its `grants` option is set. The accepted-
+ * payment hook issues a grant token + expiry, returns the token via
+ * the `X-PAYMENT-GRANT` response header. The before-* hook checks the
+ * inbound `X-PAYMENT-GRANT` header against the table, route-scoped and
+ * time-windowed; a valid grant bypasses the 402 + verify+settle pipeline.
+ *
+ * Trade-offs vs. JWT:
+ *   - Opaque tokens require one DB lookup per request, JWT would be
+ *     self-validating. We prefer opaque so revocation is trivial
+ *     (`DELETE FROM X402Grants WHERE token = …`) and clock skew is a
+ *     non-issue (the DB owns `now`).
+ *   - Lookup adds latency (~ms on SQLite, < ms on HANA). Negligible
+ *     compared to the seconds-long settle path it replaces.
+ *
+ * Failure modes:
+ *   - Issue failure: logged, gate still serves the response (the buyer
+ *     paid, we don't punish them for our DB hiccup). They simply won't
+ *     have a grant for next time.
+ *   - Lookup failure: treated as `not-found`; the gate falls through to
+ *     the normal payment path. Buyers retry their grant; on real DB
+ *     failures, payments still work, just without the subscription
+ *     short-circuit.
+ */
+import type { PaymentClaim } from '../core/types';
+export declare const DEFAULT_GRANTS_ENTITY = "odatano.x402.X402Grants";
+export declare const DEFAULT_GRANT_TTL_SECONDS = 3600;
+/** Resolve entity name from the `grants` option. */
+export declare function resolveGrantsEntity(grants: boolean | {
+    ttlSeconds?: number;
+    entity?: string;
+} | undefined): string | null;
+/** Resolve TTL (seconds) from the `grants` option. */
+export declare function resolveGrantTtl(grants: boolean | {
+    ttlSeconds?: number;
+    entity?: string;
+} | undefined): number;
+export interface IssueGrantResult {
+    token: string;
+    expiresAt: string;
+}
+/**
+ * Issue a new grant for an accepted payment. Returns `null` if the
+ * INSERT failed; the caller continues without setting the
+ * `X-PAYMENT-GRANT` response header (graceful degradation).
+ */
+export declare function issueGrant(entityName: string, claim: PaymentClaim, route: string, ttlSeconds: number): Promise<IssueGrantResult | null>;
+export type GrantLookupResult = {
+    kind: 'valid';
+} | {
+    kind: 'expired';
+} | {
+    kind: 'not-found';
+};
+/**
+ * Look up a grant by token, scoped to a specific route. The route check
+ * is strict equality, a grant for `/Quotes` will not unlock `/getBestPrice`.
+ * Any DB error is logged and surfaces as `not-found`; the gate then runs
+ * its normal payment path, ensuring DB problems never deny paying buyers.
+ */
+export declare function lookupGrant(entityName: string, token: string, route: string): Promise<GrantLookupResult>;
+//# sourceMappingURL=grants.d.ts.map

package/srv/middleware/grants.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * CAP-backed time-limited grants.
+ *
+ * Used by `gateService` when its `grants` option is set. The accepted-
+ * payment hook issues a grant token + expiry, returns the token via
+ * the `X-PAYMENT-GRANT` response header. The before-* hook checks the
+ * inbound `X-PAYMENT-GRANT` header against the table, route-scoped and
+ * time-windowed; a valid grant bypasses the 402 + verify+settle pipeline.
+ *
+ * Trade-offs vs. JWT:
+ *   - Opaque tokens require one DB lookup per request, JWT would be
+ *     self-validating. We prefer opaque so revocation is trivial
+ *     (`DELETE FROM X402Grants WHERE token = …`) and clock skew is a
+ *     non-issue (the DB owns `now`).
+ *   - Lookup adds latency (~ms on SQLite, < ms on HANA). Negligible
+ *     compared to the seconds-long settle path it replaces.
+ *
+ * Failure modes:
+ *   - Issue failure: logged, gate still serves the response (the buyer
+ *     paid, we don't punish them for our DB hiccup). They simply won't
+ *     have a grant for next time.
+ *   - Lookup failure: treated as `not-found`; the gate falls through to
+ *     the normal payment path. Buyers retry their grant; on real DB
+ *     failures, payments still work, just without the subscription
+ *     short-circuit.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GRANT_TTL_SECONDS = exports.DEFAULT_GRANTS_ENTITY = void 0;
+exports.resolveGrantsEntity = resolveGrantsEntity;
+exports.resolveGrantTtl = resolveGrantTtl;
+exports.issueGrant = issueGrant;
+exports.lookupGrant = lookupGrant;
+const cds_1 = __importDefault(require("@sap/cds"));
+const crypto_1 = require("crypto");
+const log = cds_1.default.log('x402');
+exports.DEFAULT_GRANTS_ENTITY = 'odatano.x402.X402Grants';
+exports.DEFAULT_GRANT_TTL_SECONDS = 3600;
+/** Resolve entity name from the `grants` option. */
+function resolveGrantsEntity(grants) {
+    if (!grants)
+        return null;
+    if (grants === true)
+        return exports.DEFAULT_GRANTS_ENTITY;
+    return grants.entity ?? exports.DEFAULT_GRANTS_ENTITY;
+}
+/** Resolve TTL (seconds) from the `grants` option. */
+function resolveGrantTtl(grants) {
+    if (!grants || grants === true)
+        return exports.DEFAULT_GRANT_TTL_SECONDS;
+    return grants.ttlSeconds ?? exports.DEFAULT_GRANT_TTL_SECONDS;
+}
+function generateToken() {
+    // 32 bytes, base64url-encoded (44 chars without padding).
+    return (0, crypto_1.randomBytes)(32).toString('base64url');
+}
+/**
+ * Issue a new grant for an accepted payment. Returns `null` if the
+ * INSERT failed; the caller continues without setting the
+ * `X-PAYMENT-GRANT` response header (graceful degradation).
+ */
+async function issueGrant(entityName, claim, route, ttlSeconds) {
+    const token = generateToken();
+    const now = Date.now();
+    const expiresAt = new Date(now + ttlSeconds * 1000).toISOString();
+    try {
+        await INSERT.into(entityName).entries({
+            ID: cds_1.default.utils.uuid(),
+            token,
+            route,
+            payerAddr: claim.payerAddr ?? null,
+            txHash: claim.txHash,
+            asset: claim.asset,
+            network: claim.network,
+            issuedAt: new Date(now).toISOString(),
+            expiresAt,
+        });
+        return { token, expiresAt };
+    }
+    catch (err) {
+        log.warn(`x402 grant INSERT into ${entityName} failed (non-fatal):`, err?.message ?? err);
+        return null;
+    }
+}
+/**
+ * Look up a grant by token, scoped to a specific route. The route check
+ * is strict equality, a grant for `/Quotes` will not unlock `/getBestPrice`.
+ * Any DB error is logged and surfaces as `not-found`; the gate then runs
+ * its normal payment path, ensuring DB problems never deny paying buyers.
+ */
+async function lookupGrant(entityName, token, route) {
+    if (!token)
+        return { kind: 'not-found' };
+    try {
+        const row = await SELECT.one
+            .from(entityName)
+            .where({ token, route });
+        if (!row)
+            return { kind: 'not-found' };
+        const expiresMs = row.expiresAt ? Date.parse(row.expiresAt) : 0;
+        if (!Number.isFinite(expiresMs) || expiresMs <= Date.now()) {
+            return { kind: 'expired' };
+        }
+        return { kind: 'valid' };
+    }
+    catch (err) {
+        log.warn(`x402 grant SELECT from ${entityName} failed (non-fatal):`, err?.message ?? err);
+        return { kind: 'not-found' };
+    }
+}

package/srv/middleware/pricing.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared pricing resolution for the CAP and Express middlewares.
+ *
+ * The two integrations differ in how they extract the routing key
+ * (`req.event` vs. last URL segment) and how they read headers, but
+ * once they've built a `PricingContext` the resolution logic is identical:
+ *
+ *   1. If `routePricing` is a function, invoke it with the context.
+ *      Sync or async; null return = pass through.
+ *   2. If `routePricing` is a static map, look up `target` then `event`.
+ *      Miss falls back to `priceUnits`. Both miss = pass through.
+ *   3. The matched value can be a scalar (single price in default asset),
+ *      a `RouteOption` (single price with overrides), or `RouteOption[]`
+ *      (multi-accept). Scalars and single RouteOptions are widened to
+ *      length-1 arrays so downstream code only deals with one shape.
+ *
+ * Returns `RouteOption[]` (≥ 1 entry) or `null` for pass-through.
+ *
+ * The middlewares pass the returned array straight to
+ * `buildPaymentRequirementsMulti()`; length-1 still produces a single-
+ * entry 402 body, indistinguishable from the pre-v0.3 output.
+ */
+import type { PriceSpec, PriceResolver, PricingContext, RouteOption } from '../core/types';
+export interface PricingOptions {
+    /** Single price, applies when `routePricing` misses. */
+    priceUnits?: PriceSpec;
+    /**
+     * Per-event prices keyed by route name, OR a dynamic resolver function.
+     * Function returns null to skip the gate entirely.
+     */
+    routePricing?: Record<string, PriceSpec> | PriceResolver;
+}
+/**
+ * Resolve pricing for a request. Returns the option array to gate the
+ * request with, or `null` if the request should pass through ungated.
+ *
+ * Async to support dynamic resolvers that hit a DB / cache. Awaiting a
+ * sync return is a JS-engine no-op, so the sync path stays fast.
+ */
+export declare function resolvePrice(opts: PricingOptions, ctx: PricingContext): Promise<RouteOption[] | null>;
+//# sourceMappingURL=pricing.d.ts.map

package/srv/middleware/pricing.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Shared pricing resolution for the CAP and Express middlewares.
+ *
+ * The two integrations differ in how they extract the routing key
+ * (`req.event` vs. last URL segment) and how they read headers, but
+ * once they've built a `PricingContext` the resolution logic is identical:
+ *
+ *   1. If `routePricing` is a function, invoke it with the context.
+ *      Sync or async; null return = pass through.
+ *   2. If `routePricing` is a static map, look up `target` then `event`.
+ *      Miss falls back to `priceUnits`. Both miss = pass through.
+ *   3. The matched value can be a scalar (single price in default asset),
+ *      a `RouteOption` (single price with overrides), or `RouteOption[]`
+ *      (multi-accept). Scalars and single RouteOptions are widened to
+ *      length-1 arrays so downstream code only deals with one shape.
+ *
+ * Returns `RouteOption[]` (≥ 1 entry) or `null` for pass-through.
+ *
+ * The middlewares pass the returned array straight to
+ * `buildPaymentRequirementsMulti()`; length-1 still produces a single-
+ * entry 402 body, indistinguishable from the pre-v0.3 output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePrice = resolvePrice;
+function widenToOptions(spec) {
+    if (Array.isArray(spec)) {
+        if (spec.length === 0) {
+            throw new Error('resolvePrice: route option array must be non-empty');
+        }
+        return spec;
+    }
+    if (typeof spec === 'object') {
+        // RouteOption shape
+        return [spec];
+    }
+    // scalar (string | number | bigint) , default-asset shorthand
+    return [{ amount: spec }];
+}
+function lookupStatic(map, ctx) {
+    // `target` is more specific (CAP entity name) than `event` (verb), so
+    // try the entity segment first. Express only fills `event`.
+    if (ctx.target) {
+        const entitySegment = ctx.target.split('.').pop() ?? '';
+        if (entitySegment && map[entitySegment] != null)
+            return map[entitySegment];
+    }
+    if (map[ctx.event] != null)
+        return map[ctx.event];
+    return undefined;
+}
+/**
+ * Resolve pricing for a request. Returns the option array to gate the
+ * request with, or `null` if the request should pass through ungated.
+ *
+ * Async to support dynamic resolvers that hit a DB / cache. Awaiting a
+ * sync return is a JS-engine no-op, so the sync path stays fast.
+ */
+async function resolvePrice(opts, ctx) {
+    // ─── 1. Function-form routePricing ─────────────────────────────────
+    if (typeof opts.routePricing === 'function') {
+        const spec = await opts.routePricing(ctx);
+        if (spec == null)
+            return null;
+        return widenToOptions(spec);
+    }
+    // ─── 2. Static-map routePricing ────────────────────────────────────
+    if (opts.routePricing) {
+        const hit = lookupStatic(opts.routePricing, ctx);
+        if (hit != null)
+            return widenToOptions(hit);
+        // Map present but no key matched. Fall through to priceUnits.
+    }
+    // ─── 3. Fallback to flat priceUnits ────────────────────────────────
+    if (opts.priceUnits != null)
+        return widenToOptions(opts.priceUnits);
+    return null;
+}

package/srv/middleware/receipts.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CAP-backed persistence for accepted x402 payments.
+ *
+ * Called from `gateService` when its `receipts` option is set. One INSERT
+ * per accepted payment; runs AFTER settle confirms and BEFORE the 200
+ * response is served to the buyer. Best-effort: any INSERT failure is
+ * logged and SWALLOWED, the canonical record is on chain and we never
+ * want a flaky DB to deny a paying buyer their response.
+ *
+ * Entity shape: see `db/x402-receipts.cds`. The schema is shipped in the
+ * plugin's `db/`; CAP auto-discovers it when `@odatano/x402` is in
+ * node_modules. Consumers wanting a custom shape can pass
+ * `receipts: { entity: 'my.namespace.MyTable' }`, the table needs to
+ * carry the columns we INSERT below.
+ *
+ * Idempotency: txHash carries `@assert.unique`. A duplicate INSERT
+ * (e.g. settle returning twice for the same buyer) hits a unique-key
+ * violation and we log + continue. Buyers' UX is unaffected.
+ */
+import type { PaymentClaim } from '../core/types';
+/** Canonical entity name shipped by the plugin. */
+export declare const DEFAULT_RECEIPTS_ENTITY = "odatano.x402.X402Receipts";
+/**
+ * Insert one receipt for an accepted payment. Returns a promise that
+ * always resolves (never throws), errors are logged.
+ *
+ * The `route` argument is the resource URL the buyer paid for, the same
+ * value embedded in `accepts[0].resource.url`. We pass it explicitly
+ * rather than re-deriving it inside this module so the persisted route
+ * matches what the 402 advertised, even when the consumer set a custom
+ * `resourceUrl` builder.
+ */
+export declare function persistReceipt(entityName: string, claim: PaymentClaim, route: string): Promise<void>;
+/** Resolve the entity name from the `receipts` option. */
+export declare function resolveReceiptsEntity(receipts: boolean | {
+    entity?: string;
+} | undefined): string | null;
+//# sourceMappingURL=receipts.d.ts.map