@odatano/x402 0.2.0 → 0.3.1

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

package/srv/middleware/receipts.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RECEIPTS_ENTITY = void 0;
+exports.persistReceipt = persistReceipt;
+exports.resolveReceiptsEntity = resolveReceiptsEntity;
+const cds_1 = __importDefault(require("@sap/cds"));
+const log = cds_1.default.log('x402');
+/** Canonical entity name shipped by the plugin. */
+exports.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.
+ */
+async function persistReceipt(entityName, claim, route) {
+    try {
+        await INSERT.into(entityName).entries({
+            ID: cds_1.default.utils.uuid(),
+            txHash: claim.txHash,
+            payerAddr: claim.payerAddr ?? null,
+            payTo: claim.payTo,
+            asset: claim.asset,
+            amount: claim.amountUnits,
+            network: claim.network,
+            route,
+            nonceRef: claim.nonceRef,
+            at: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        log.warn(`x402 receipts INSERT into ${entityName} failed (non-fatal):`, err?.message ?? err);
+    }
+}
+/** Resolve the entity name from the `receipts` option. */
+function resolveReceiptsEntity(receipts) {
+    if (!receipts)
+        return null;
+    if (receipts === true)
+        return exports.DEFAULT_RECEIPTS_ENTITY;
+    return receipts.entity ?? exports.DEFAULT_RECEIPTS_ENTITY;
+}

package/srv/plugin.d.ts

@@ -2,13 +2,13 @@
  * CAP plugin registration for `@odatano/x402`.
  *
  * Unlike `@odatano/core`, this plugin doesn't auto-serve any CDS
- * entities — x402 is a library, not a service. We use the
+ * entities, x402 is a library, not a service. We use the
  * `cds.on('served')` hook only to initialise the bridge (warm up the
  * @odatano/core connection) and the `cds.on('shutdown')` hook to clean
  * up. Consumers wire middleware / gateService themselves inside their
  * own service init().
  *
- * NEVER throws on init failure — the plugin must not crash the host
+ * NEVER throws on init failure, the plugin must not crash the host
  * CAP application. Errors are logged; calls into the bridge later
  * will fail with `BRIDGE_UNAVAILABLE`.
  */

package/srv/plugin.js

@@ -3,13 +3,13 @@
  * CAP plugin registration for `@odatano/x402`.
  *
  * Unlike `@odatano/core`, this plugin doesn't auto-serve any CDS
- * entities — x402 is a library, not a service. We use the
+ * entities, x402 is a library, not a service. We use the
  * `cds.on('served')` hook only to initialise the bridge (warm up the
  * @odatano/core connection) and the `cds.on('shutdown')` hook to clean
  * up. Consumers wire middleware / gateService themselves inside their
  * own service init().
  *
- * NEVER throws on init failure — the plugin must not crash the host
+ * NEVER throws on init failure, the plugin must not crash the host
  * CAP application. Errors are logged; calls into the bridge later
  * will fail with `BRIDGE_UNAVAILABLE`.
  */