@odatano/x402 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@odatano/x402` are documented here. The format follows [
 
 **Pre-1.0 caveat:** minor versions may include breaking changes until `1.0.0`.
 
+## [0.3.1] - 2026-05-15
+
+### Fixed
+- **`gateService` now emits the canonical x402 v2 body on the wire** instead of CAP's OData-wrapped shape. The gate writes `httpRes.status(402).json(body)` directly when an Express response is reachable, then calls `req.reject(402, ...)` as the chain-terminator: the synchronous throw stops CAP's handler pipeline so the gated `on` handler never runs, and CAP's render attempt no-ops on `headersSent`. Non-HTTP transports (event invocations, `$batch` reuse) fall back to plain `req.reject`. Validated against `@sap/cds ^9`. Third-party x402 clients now interop with CAP-gated services without any unwrap shim. Closes the "Known issues" item from 0.3.0.
+
+### Removed (breaking)
+- **`unwrapCapEnvelope`** helper and its calls from `x402Fetch` / `x402Axios`. With the server fix above, the v2 body lands at the top level on the wire and the defensive unwrap is dead code. The export is gone; consumers who pulled it in (e.g. for wrapping the wrappers) should remove the import. **Pair the upgrade**: if you upgrade the `@odatano/x402` client to 0.3.1, upgrade the server in the same step, since 0.3.1 clients no longer unwrap a 0.3.0-style wrapped body.
+
+### Changed
+- `srv/middleware/cap.ts` , new `send402` helper and `getHttpRes` accessor; the one 402 emit site routes through `send402`. The two 500 `req.reject` paths (pricing-resolver throw, facilitator throw) are unchanged.
+- Test suite: 232 tests across 21 suites. CAP middleware tests gained 3 cases (canonical-wire-shape regression, `headersSent` defensive fallback, no-`http.res` transport fallback). Client tests dropped 7 cases tied to `unwrapCapEnvelope`.
+
 ## [0.3.0] - 2026-05-15
 
 ### Added
@@ -16,7 +28,7 @@ All notable changes to `@odatano/x402` are documented here. The format follows [
 - **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.
+- **`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.
 
 ### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odatano/x402",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "x402 Cardano-v2 payment library for SAP CAP applications",
   "license": "Apache-2.0",
   "main": "srv/index.js",

package/srv/client/axios.js

@@ -54,9 +54,7 @@ function x402Axios(instance, opts) {
         }
         const cfg = error.config;
         const retries = Number(cfg[RETRY_KEY] ?? 0);
-        // CAP-style servers wrap the v2 body inside an OData error envelope.
-        // Defensively unwrap before validating shape.
-        const body = (0, errors_1.unwrapCapEnvelope)(error.response.data);
+        const body = error.response.data;
         const status = error.response.status;
         if (retries >= maxRetries) {
             if (opts.errorOnFailure) {

package/srv/client/errors.d.ts

@@ -60,27 +60,6 @@ export declare class X402PaymentError extends Error {
     readonly cause?: unknown;
     constructor(init: X402PaymentErrorInit);
 }
-/**
- * Defensively unwrap a CAP / OData error envelope around a v2 body.
- *
- * Background: `gateService` in this package historically (≤ v0.2)
- * reaches a 402 via `req.reject(402, JSON.stringify(body))`, which
- * CAP wraps into its standard OData error shape, putting the canonical
- * v2 body inside `error.message` as a JSON string:
- *
- *   { "error": { "message": "{\"x402Version\":2, ... }", "code": "402", ... } }
- *
- * The Express middleware emits the v2 body at the top level directly.
- * This helper detects the CAP wrap and returns the unwrapped candidate
- * so client wrappers can validate v2 shape uniformly. Non-CAP bodies
- * pass through untouched.
- *
- * Symmetric server-side fix (emit canonical body even through CAP) is
- * a separate concern, deferred until we can validate the CAP-version
- * specific behaviour. The unwrap below keeps `x402Fetch` /
- * `x402Axios` working against both shapes.
- */
-export declare function unwrapCapEnvelope(parsed: unknown): unknown;
 /**
  * Parse the (server, canonical) error string from a `PaymentRequirementsBody`.
  *

package/srv/client/errors.js

@@ -31,7 +31,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.X402PaymentError = void 0;
-exports.unwrapCapEnvelope = unwrapCapEnvelope;
 exports.parseErrorCode = parseErrorCode;
 exports.paymentErrorFromBody = paymentErrorFromBody;
 /**
@@ -71,42 +70,6 @@ class X402PaymentError extends Error {
     }
 }
 exports.X402PaymentError = X402PaymentError;
-/**
- * Defensively unwrap a CAP / OData error envelope around a v2 body.
- *
- * Background: `gateService` in this package historically (≤ v0.2)
- * reaches a 402 via `req.reject(402, JSON.stringify(body))`, which
- * CAP wraps into its standard OData error shape, putting the canonical
- * v2 body inside `error.message` as a JSON string:
- *
- *   { "error": { "message": "{\"x402Version\":2, ... }", "code": "402", ... } }
- *
- * The Express middleware emits the v2 body at the top level directly.
- * This helper detects the CAP wrap and returns the unwrapped candidate
- * so client wrappers can validate v2 shape uniformly. Non-CAP bodies
- * pass through untouched.
- *
- * Symmetric server-side fix (emit canonical body even through CAP) is
- * a separate concern, deferred until we can validate the CAP-version
- * specific behaviour. The unwrap below keeps `x402Fetch` /
- * `x402Axios` working against both shapes.
- */
-function unwrapCapEnvelope(parsed) {
-    if (!parsed || typeof parsed !== 'object')
-        return parsed;
-    const maybeError = parsed.error;
-    if (!maybeError || typeof maybeError !== 'object')
-        return parsed;
-    const msg = maybeError.message;
-    if (typeof msg !== 'string')
-        return parsed;
-    try {
-        return JSON.parse(msg);
-    }
-    catch {
-        return parsed;
-    }
-}
 /**
  * Parse the (server, canonical) error string from a `PaymentRequirementsBody`.
  *

package/srv/client/fetch.js

@@ -57,8 +57,7 @@ function x402Fetch(opts) {
                     let body = lastBody;
                     if (!body) {
                         try {
-                            const raw = await res.clone().json();
-                            body = (0, errors_1.unwrapCapEnvelope)(raw);
+                            body = await res.clone().json();
                         }
                         catch { /* fall through */ }
                     }
@@ -75,13 +74,9 @@ function x402Fetch(opts) {
             }
             // Parse 402 body. If it's not a v2 PaymentRequirementsBody we
             // bail with the original response (or throw under errorOnFailure).
-            // Some servers (CAP-gated ones using req.reject) wrap the v2 body
-            // inside an OData error envelope, unwrap defensively before the
-            // x402Version check.
             let body;
             try {
-                const raw = await res.clone().json();
-                body = (0, errors_1.unwrapCapEnvelope)(raw);
+                body = await res.clone().json();
             }
             catch {
                 if (opts.errorOnFailure) {

package/srv/middleware/cap.js

@@ -72,6 +72,32 @@ function getResourceUrl(req, opts) {
     const httpReq = req;
     return httpReq.http?.req?.originalUrl ?? httpReq.http?.req?.url ?? `cap://${req.event}`;
 }
+function getHttpRes(req) {
+    return req.http?.res;
+}
+/**
+ * Emit a 402 with the canonical x402 v2 body on the wire.
+ *
+ * When an Express response is reachable we write the body ourselves so
+ * third-party x402 clients see `{ x402Version: 2, accepts: [...] }` at
+ * the top level rather than CAP's OData-wrapped `{ error: { message:
+ * "<v2-json-string>", ... } }`. The `req.reject` call is always made:
+ * its synchronous throw is what terminates CAP's handler pipeline (so
+ * the gated `on` handler never runs); CAP's own render attempt no-ops
+ * because `headersSent` is already true. Validated against `@sap/cds ^9`.
+ *
+ * For non-HTTP transports (event invocations, `$batch` reuse, tests
+ * without `http.res`) we skip the direct write and let `req.reject` do
+ * the whole job — the wrap is irrelevant when there's no HTTP buyer.
+ */
+function send402(req, body) {
+    const httpRes = getHttpRes(req);
+    if (httpRes && !httpRes.headersSent) {
+        httpRes.status(402).json(body);
+    }
+    req
+        .reject(402, JSON.stringify(body));
+}
 /**
  * Attach the x402 gate to a CAP ApplicationService. Returns the service
  * (chainable) so callers can fluently wire multiple middlewares.
@@ -207,8 +233,7 @@ function gateService(srv, opts) {
             if (result.txHash)
                 body.transaction = result.txHash;
         }
-        req
-            .reject(402, JSON.stringify(body));
+        send402(req, body);
     });
     return srv;
 }