@peac/rails-x402 0.9.18

package/README.md

@@ -0,0 +1,23 @@
+# @peac/rails-x402
+
+x402 payment rail adapter for PEAC protocol
+
+## Installation
+
+```bash
+pnpm add @peac/rails-x402
+```
+
+## Documentation
+
+See [peacprotocol.org](https://peacprotocol.org) for full documentation.
+
+## License
+
+Apache-2.0
+
+---
+
+PEAC Protocol is an open source project stewarded by Originary and community contributors.
+
+[Originary](https://www.originary.xyz) | [Docs](https://peacprotocol.org) | [GitHub](https://github.com/peacprotocol/peac)

package/dist/constants.d.ts

@@ -0,0 +1,46 @@
+/**
+ * x402 protocol constants and types
+ *
+ * Supports both x402 v1 (legacy X-PAYMENT-* headers) and v2 (Payment-* headers).
+ * Default behavior is auto-detection with v1 fallback.
+ */
+/**
+ * x402 protocol dialect
+ *
+ * - 'v1': Legacy X-PAYMENT-* headers (pre-Dec 2025)
+ * - 'v2': New Payment-* headers (Dec 2025+)
+ * - 'auto': Auto-detect from response headers (default)
+ */
+export type X402Dialect = 'v1' | 'v2' | 'auto';
+/**
+ * x402 v1 header names (legacy, pre-Dec 2025)
+ */
+export declare const X402_HEADERS_V1: {
+    readonly paymentRequired: "X-PAYMENT";
+    readonly paymentResponse: "X-PAYMENT-RESPONSE";
+};
+/**
+ * x402 v2 header names (Dec 2025+)
+ */
+export declare const X402_HEADERS_V2: {
+    readonly paymentRequired: "Payment-Required";
+    readonly paymentSignature: "Payment-Signature";
+    readonly paymentResponse: "Payment-Response";
+};
+/**
+ * CAIP-2 network registry
+ *
+ * Maps canonical CAIP-2 identifiers to human-readable labels and environment.
+ * Used for validation/logging only - network IDs are passed through unchanged.
+ *
+ * Reference: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
+ */
+export declare const CAIP2_REGISTRY: Record<string, {
+    label: string;
+    env: 'mainnet' | 'testnet';
+}>;
+/**
+ * Default network for v1 x402 (Lightning)
+ */
+export declare const X402_V1_DEFAULT_NETWORK = "lightning";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,CAWxF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,cAAc,CAAC"}

package/dist/constants.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * x402 protocol constants and types
+ *
+ * Supports both x402 v1 (legacy X-PAYMENT-* headers) and v2 (Payment-* headers).
+ * Default behavior is auto-detection with v1 fallback.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402_V1_DEFAULT_NETWORK = exports.CAIP2_REGISTRY = exports.X402_HEADERS_V2 = exports.X402_HEADERS_V1 = void 0;
+/**
+ * x402 v1 header names (legacy, pre-Dec 2025)
+ */
+exports.X402_HEADERS_V1 = {
+    paymentRequired: 'X-PAYMENT',
+    paymentResponse: 'X-PAYMENT-RESPONSE',
+};
+/**
+ * x402 v2 header names (Dec 2025+)
+ */
+exports.X402_HEADERS_V2 = {
+    paymentRequired: 'Payment-Required',
+    paymentSignature: 'Payment-Signature',
+    paymentResponse: 'Payment-Response',
+};
+/**
+ * CAIP-2 network registry
+ *
+ * Maps canonical CAIP-2 identifiers to human-readable labels and environment.
+ * Used for validation/logging only - network IDs are passed through unchanged.
+ *
+ * Reference: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md
+ */
+exports.CAIP2_REGISTRY = {
+    // EVM chains
+    'eip155:8453': { label: 'Base', env: 'mainnet' },
+    'eip155:84532': { label: 'Base Sepolia', env: 'testnet' },
+    'eip155:43114': { label: 'Avalanche', env: 'mainnet' },
+    'eip155:43113': { label: 'Avalanche Fuji', env: 'testnet' },
+    // Solana
+    'solana:mainnet': { label: 'Solana', env: 'mainnet' },
+    'solana:devnet': { label: 'Solana Devnet', env: 'testnet' },
+    // Lightning (v1 default)
+    lightning: { label: 'Lightning', env: 'mainnet' },
+};
+/**
+ * Default network for v1 x402 (Lightning)
+ */
+exports.X402_V1_DEFAULT_NETWORK = 'lightning';
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAWH;;GAEG;AACU,QAAA,eAAe,GAAG;IAC7B,eAAe,EAAE,WAAW;IAC5B,eAAe,EAAE,oBAAoB;CAC7B,CAAC;AAEX;;GAEG;AACU,QAAA,eAAe,GAAG;IAC7B,eAAe,EAAE,kBAAkB;IACnC,gBAAgB,EAAE,mBAAmB;IACrC,eAAe,EAAE,kBAAkB;CAC3B,CAAC;AAEX;;;;;;;GAOG;AACU,QAAA,cAAc,GAAkE;IAC3F,aAAa;IACb,aAAa,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE;IAChD,cAAc,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,SAAS,EAAE;IACzD,cAAc,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE;IACtD,cAAc,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,SAAS,EAAE;IAC3D,SAAS;IACT,gBAAgB,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE;IACrD,eAAe,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,SAAS,EAAE;IAC3D,yBAAyB;IACzB,SAAS,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE;CAClD,CAAC;AAEF;;GAEG;AACU,QAAA,uBAAuB,GAAG,WAAW,CAAC"}

package/dist/helpers.d.ts

@@ -0,0 +1,81 @@
+/**
+ * x402 helper functions
+ *
+ * Detection, normalization, and logging utilities for x402 v1/v2 support.
+ */
+import { type X402Dialect, X402_HEADERS_V1, X402_HEADERS_V2 } from './constants';
+import type { X402Invoice } from './types';
+/**
+ * Log warning for unknown CAIP-2 network (once per network per process)
+ *
+ * Message is calm and informative. Does not throw.
+ */
+export declare function logUnknownNetworkWarning(networkId: string): void;
+/**
+ * Detect x402 dialect from HTTP response headers
+ *
+ * Priority: v2 headers first (case-insensitive), then v1 fallback.
+ *
+ * Detection rules:
+ * 1. If any v2 header present (Payment-Required, Payment-Signature, Payment-Response) -> v2
+ * 2. If only v1 headers present (X-PAYMENT-*) -> v1
+ * 3. If no headers provided -> v1 (safe default)
+ *
+ * @param headers - HTTP response headers (optional)
+ * @returns Detected dialect ('v1' or 'v2')
+ */
+export declare function detectDialect(headers?: Record<string, string>): 'v1' | 'v2';
+/**
+ * Resolve dialect for invoice processing (no headers available)
+ *
+ * Heuristics:
+ * 1. If explicit dialect is specified (not 'auto') -> use it
+ * 2. If invoice.network is a CAIP-2 string (contains ':') -> v2
+ * 3. If invoice.payTo is present -> v2
+ * 4. Otherwise -> v1
+ *
+ * @param invoice - x402 invoice
+ * @param explicitDialect - Explicit dialect from config
+ * @returns Resolved dialect ('v1' or 'v2')
+ */
+export declare function resolveDialectFromInvoice(invoice: X402Invoice, explicitDialect: X402Dialect): 'v1' | 'v2';
+/**
+ * Normalize network ID (returns canonical ID, not label)
+ *
+ * Behavior:
+ * - Missing input -> "lightning" (v1 default)
+ * - Known CAIP-2 -> return as-is
+ * - Unknown -> log warning, return as-is (no throw)
+ *
+ * Key rule: NO lossy mapping. The canonical ID is always preserved.
+ *
+ * @param caip2 - CAIP-2 network identifier (optional)
+ * @returns Canonical network ID
+ */
+export declare function normalizeNetworkId(caip2: string | undefined): string;
+/**
+ * Get human-readable label for network (for evidence.network_label)
+ *
+ * @param caip2 - CAIP-2 network identifier
+ * @returns Human-readable label, or undefined for unknown networks
+ */
+export declare function getNetworkLabel(caip2: string): string | undefined;
+/**
+ * Get header names for a specific dialect
+ *
+ * @param dialect - 'v1' or 'v2'
+ * @returns Header name mapping
+ */
+export declare function getHeaders(dialect: 'v1' | 'v2'): typeof X402_HEADERS_V1 | typeof X402_HEADERS_V2;
+/**
+ * Check if a network ID indicates testnet environment
+ *
+ * @param networkId - CAIP-2 network identifier
+ * @returns true if testnet, false otherwise
+ */
+export declare function isTestnet(networkId: string): boolean;
+/**
+ * Clear warned networks set (for testing)
+ */
+export declare function _resetWarnedNetworks(): void;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,EAGhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAO3C;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAiB3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,WAAW,EACpB,eAAe,EAAE,WAAW,GAC3B,IAAI,GAAG,IAAI,CAUb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQpE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,eAAe,GAAG,OAAO,eAAe,CAEhG;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/helpers.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * x402 helper functions
+ *
+ * Detection, normalization, and logging utilities for x402 v1/v2 support.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logUnknownNetworkWarning = logUnknownNetworkWarning;
+exports.detectDialect = detectDialect;
+exports.resolveDialectFromInvoice = resolveDialectFromInvoice;
+exports.normalizeNetworkId = normalizeNetworkId;
+exports.getNetworkLabel = getNetworkLabel;
+exports.getHeaders = getHeaders;
+exports.isTestnet = isTestnet;
+exports._resetWarnedNetworks = _resetWarnedNetworks;
+const constants_1 = require("./constants");
+/**
+ * Track warned networks to avoid log spam (one warning per network per process)
+ */
+const warnedNetworks = new Set();
+/**
+ * Log warning for unknown CAIP-2 network (once per network per process)
+ *
+ * Message is calm and informative. Does not throw.
+ */
+function logUnknownNetworkWarning(networkId) {
+    if (warnedNetworks.has(networkId))
+        return;
+    warnedNetworks.add(networkId);
+    console.warn(`[peac:x402] Unknown CAIP-2 network "${networkId}", passing through as-is.`);
+}
+/**
+ * Detect x402 dialect from HTTP response headers
+ *
+ * Priority: v2 headers first (case-insensitive), then v1 fallback.
+ *
+ * Detection rules:
+ * 1. If any v2 header present (Payment-Required, Payment-Signature, Payment-Response) -> v2
+ * 2. If only v1 headers present (X-PAYMENT-*) -> v1
+ * 3. If no headers provided -> v1 (safe default)
+ *
+ * @param headers - HTTP response headers (optional)
+ * @returns Detected dialect ('v1' or 'v2')
+ */
+function detectDialect(headers) {
+    if (!headers)
+        return 'v1';
+    const lowerHeaders = Object.keys(headers).map((k) => k.toLowerCase());
+    // Check for v2 headers first
+    const v2Headers = [
+        constants_1.X402_HEADERS_V2.paymentRequired.toLowerCase(),
+        constants_1.X402_HEADERS_V2.paymentSignature.toLowerCase(),
+        constants_1.X402_HEADERS_V2.paymentResponse.toLowerCase(),
+    ];
+    if (v2Headers.some((h) => lowerHeaders.includes(h))) {
+        return 'v2';
+    }
+    return 'v1';
+}
+/**
+ * Resolve dialect for invoice processing (no headers available)
+ *
+ * Heuristics:
+ * 1. If explicit dialect is specified (not 'auto') -> use it
+ * 2. If invoice.network is a CAIP-2 string (contains ':') -> v2
+ * 3. If invoice.payTo is present -> v2
+ * 4. Otherwise -> v1
+ *
+ * @param invoice - x402 invoice
+ * @param explicitDialect - Explicit dialect from config
+ * @returns Resolved dialect ('v1' or 'v2')
+ */
+function resolveDialectFromInvoice(invoice, explicitDialect) {
+    if (explicitDialect !== 'auto') {
+        return explicitDialect;
+    }
+    // v2 indicators
+    if (invoice.network && invoice.network.includes(':'))
+        return 'v2';
+    if (invoice.payTo)
+        return 'v2';
+    return 'v1';
+}
+/**
+ * Normalize network ID (returns canonical ID, not label)
+ *
+ * Behavior:
+ * - Missing input -> "lightning" (v1 default)
+ * - Known CAIP-2 -> return as-is
+ * - Unknown -> log warning, return as-is (no throw)
+ *
+ * Key rule: NO lossy mapping. The canonical ID is always preserved.
+ *
+ * @param caip2 - CAIP-2 network identifier (optional)
+ * @returns Canonical network ID
+ */
+function normalizeNetworkId(caip2) {
+    if (!caip2)
+        return constants_1.X402_V1_DEFAULT_NETWORK;
+    if (!(caip2 in constants_1.CAIP2_REGISTRY)) {
+        logUnknownNetworkWarning(caip2);
+    }
+    return caip2; // Always return the canonical ID unchanged
+}
+/**
+ * Get human-readable label for network (for evidence.network_label)
+ *
+ * @param caip2 - CAIP-2 network identifier
+ * @returns Human-readable label, or undefined for unknown networks
+ */
+function getNetworkLabel(caip2) {
+    return constants_1.CAIP2_REGISTRY[caip2]?.label;
+}
+/**
+ * Get header names for a specific dialect
+ *
+ * @param dialect - 'v1' or 'v2'
+ * @returns Header name mapping
+ */
+function getHeaders(dialect) {
+    return dialect === 'v2' ? constants_1.X402_HEADERS_V2 : constants_1.X402_HEADERS_V1;
+}
+/**
+ * Check if a network ID indicates testnet environment
+ *
+ * @param networkId - CAIP-2 network identifier
+ * @returns true if testnet, false otherwise
+ */
+function isTestnet(networkId) {
+    return constants_1.CAIP2_REGISTRY[networkId]?.env === 'testnet';
+}
+/**
+ * Clear warned networks set (for testing)
+ */
+function _resetWarnedNetworks() {
+    warnedNetworks.clear();
+}
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAqBH,4DAKC;AAeD,sCAiBC;AAeD,8DAaC;AAeD,gDAQC;AAQD,0CAEC;AAQD,gCAEC;AAQD,8BAEC;AAKD,oDAEC;AAhJD,2CAMqB;AAGrB;;GAEG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;AAEzC;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,SAAiB;IACxD,IAAI,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC;QAAE,OAAO;IAC1C,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAE9B,OAAO,CAAC,IAAI,CAAC,uCAAuC,SAAS,2BAA2B,CAAC,CAAC;AAC5F,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,aAAa,CAAC,OAAgC;IAC5D,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAEtE,6BAA6B;IAC7B,MAAM,SAAS,GAAG;QAChB,2BAAe,CAAC,eAAe,CAAC,WAAW,EAAE;QAC7C,2BAAe,CAAC,gBAAgB,CAAC,WAAW,EAAE;QAC9C,2BAAe,CAAC,eAAe,CAAC,WAAW,EAAE;KAC9C,CAAC;IAEF,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,yBAAyB,CACvC,OAAoB,EACpB,eAA4B;IAE5B,IAAI,eAAe,KAAK,MAAM,EAAE,CAAC;QAC/B,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,gBAAgB;IAChB,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,IAAI,OAAO,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAE/B,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,kBAAkB,CAAC,KAAyB;IAC1D,IAAI,CAAC,KAAK;QAAE,OAAO,mCAAuB,CAAC;IAE3C,IAAI,CAAC,CAAC,KAAK,IAAI,0BAAc,CAAC,EAAE,CAAC;QAC/B,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,KAAK,CAAC,CAAC,2CAA2C;AAC3D,CAAC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,KAAa;IAC3C,OAAO,0BAAc,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,UAAU,CAAC,OAAoB;IAC7C,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,2BAAe,CAAC,CAAC,CAAC,2BAAe,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,SAAgB,SAAS,CAAC,SAAiB;IACzC,OAAO,0BAAc,CAAC,SAAS,CAAC,EAAE,GAAG,KAAK,SAAS,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,SAAgB,oBAAoB;IAClC,cAAc,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * x402 payment rail adapter
+ *
+ * Normalizes x402 invoices/settlements to PEAC PaymentEvidence.
+ * Supports both v1 (legacy X-PAYMENT-* headers) and v2 (Payment-* headers).
+ *
+ * Default behavior is auto-detection with v1 fallback for backwards compatibility.
+ */
+import type { PaymentEvidence } from '@peac/schema';
+export * from './constants';
+export * from './types';
+export * from './helpers';
+import type { X402Dialect } from './constants';
+import type { X402Invoice, X402Settlement, X402WebhookEvent } from './types';
+/**
+ * Normalize x402 invoice to PEAC PaymentEvidence
+ *
+ * Supports both v1 and v2 x402 formats. Default is auto-detection.
+ *
+ * @param invoice - x402 invoice object
+ * @param env - Environment ('live' or 'test')
+ * @param dialect - x402 dialect ('v1', 'v2', or 'auto')
+ * @returns Normalized PaymentEvidence
+ */
+export declare function fromInvoice(invoice: X402Invoice, env?: 'live' | 'test', dialect?: X402Dialect): PaymentEvidence;
+/**
+ * Normalize x402 settlement to PEAC PaymentEvidence
+ *
+ * @param settlement - x402 settlement object
+ * @param env - Environment ('live' or 'test')
+ * @param dialect - x402 dialect ('v1', 'v2', or 'auto')
+ * @returns Normalized PaymentEvidence
+ */
+export declare function fromSettlement(settlement: X402Settlement, env?: 'live' | 'test', dialect?: X402Dialect): PaymentEvidence;
+/**
+ * Normalize x402 webhook event to PEAC PaymentEvidence
+ *
+ * Supports:
+ * - invoice.paid
+ * - settlement.completed
+ *
+ * Dialect is auto-detected from headers if provided.
+ *
+ * @param event - x402 webhook event
+ * @param env - Environment ('live' or 'test')
+ * @param headers - HTTP response headers (optional, for dialect detection)
+ * @returns Normalized PaymentEvidence
+ */
+export declare function fromWebhookEvent(event: X402WebhookEvent, env?: 'live' | 'test', headers?: Record<string, string>): PaymentEvidence;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,cAAc,CAAC;AAGlE,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAE1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAgB,MAAM,SAAS,CAAC;AA2F3F;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,GAAG,GAAE,MAAM,GAAG,MAAe,EAC7B,OAAO,GAAE,WAAoB,GAC5B,eAAe,CA+EjB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,cAAc,EAC1B,GAAG,GAAE,MAAM,GAAG,MAAe,EAC7B,OAAO,GAAE,WAAoB,GAC5B,eAAe,CAqDjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,gBAAgB,EACvB,GAAG,GAAE,MAAM,GAAG,MAAe,EAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,eAAe,CAgBjB"}

package/dist/index.js

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * x402 payment rail adapter
+ *
+ * Normalizes x402 invoices/settlements to PEAC PaymentEvidence.
+ * Supports both v1 (legacy X-PAYMENT-* headers) and v2 (Payment-* headers).
+ *
+ * Default behavior is auto-detection with v1 fallback for backwards compatibility.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromInvoice = fromInvoice;
+exports.fromSettlement = fromSettlement;
+exports.fromWebhookEvent = fromWebhookEvent;
+// Re-export types and constants for consumers
+__exportStar(require("./constants"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./helpers"), exports);
+const helpers_1 = require("./helpers");
+/**
+ * Build aggregator and splits from x402 invoice metadata
+ *
+ * Mapping rules:
+ * - aggregator: Set when invoice has platform/aggregator in metadata
+ *   - Pattern: "x402:{serviceName}" (e.g., "x402:load", "x402:tollbit")
+ * - splits: Mapped from explicit split data, or single merchant split if aggregator known
+ *   - If no split data and no aggregator -> undefined
+ *
+ * @param invoice - x402 invoice
+ * @param resolvedDialect - Resolved dialect
+ * @returns Object with optional aggregator and splits
+ */
+function buildAggregatorAndSplits(invoice, resolvedDialect) {
+    // Only attempt aggregator/splits for v2 (v1 has no such concept)
+    if (resolvedDialect === 'v1') {
+        return {};
+    }
+    let aggregator;
+    let splits;
+    // Detect aggregator from invoice metadata or known patterns
+    const meta = invoice.metadata;
+    if (meta?.aggregator && typeof meta.aggregator === 'string') {
+        aggregator = `x402:${meta.aggregator}`;
+    }
+    else if (meta?.platform && typeof meta.platform === 'string') {
+        aggregator = `x402:${meta.platform}`;
+    }
+    // Build splits if we have explicit split data
+    if (meta?.splits && Array.isArray(meta.splits)) {
+        const rawSplits = meta.splits;
+        splits = rawSplits
+            .map((s) => {
+            const party = s.party;
+            const amount = s.amount;
+            const share = s.share;
+            // Validate: party required, at least one of amount/share
+            if (!party || (amount === undefined && share === undefined)) {
+                return null;
+            }
+            const split = { party };
+            if (amount !== undefined)
+                split.amount = amount;
+            if (share !== undefined)
+                split.share = share;
+            if (s.currency)
+                split.currency = s.currency;
+            if (s.rail)
+                split.rail = s.rail;
+            if (s.account_ref)
+                split.account_ref = s.account_ref;
+            return split;
+        })
+            .filter((s) => s !== null);
+        // If no valid splits after filtering, set to undefined
+        if (splits.length === 0) {
+            splits = undefined;
+        }
+    }
+    else if (aggregator) {
+        // Single split for merchant when aggregator is known but no explicit splits
+        splits = [{ party: 'merchant', share: 1.0 }];
+    }
+    return { aggregator, splits };
+}
+/**
+ * Map x402 payTo.mode to PaymentEvidence.routing
+ *
+ * @param payToMode - x402 payTo mode value
+ * @returns Valid routing value or undefined
+ */
+function mapRouting(payToMode) {
+    if (payToMode === 'direct' || payToMode === 'callback' || payToMode === 'role') {
+        return payToMode;
+    }
+    return undefined;
+}
+/**
+ * Normalize x402 invoice to PEAC PaymentEvidence
+ *
+ * Supports both v1 and v2 x402 formats. Default is auto-detection.
+ *
+ * @param invoice - x402 invoice object
+ * @param env - Environment ('live' or 'test')
+ * @param dialect - x402 dialect ('v1', 'v2', or 'auto')
+ * @returns Normalized PaymentEvidence
+ */
+function fromInvoice(invoice, env = 'live', dialect = 'auto') {
+    // Validate required fields
+    if (!invoice.id) {
+        throw new Error('x402 invoice missing id');
+    }
+    if (typeof invoice.amount !== 'number' || invoice.amount < 0) {
+        throw new Error('x402 invoice invalid amount');
+    }
+    if (!invoice.currency || !/^[A-Z]{3}$/.test(invoice.currency)) {
+        throw new Error('x402 invoice invalid currency (must be uppercase ISO 4217)');
+    }
+    // Resolve dialect
+    const resolvedDialect = (0, helpers_1.resolveDialectFromInvoice)(invoice, dialect);
+    // Normalize network (canonical ID, not label)
+    const network = (0, helpers_1.normalizeNetworkId)(invoice.network);
+    // Build x402-specific evidence (namespaced, not top-level)
+    const evidence = {
+        invoice_id: invoice.id,
+        dialect: resolvedDialect,
+    };
+    // Add network label for human readability
+    const networkLabel = (0, helpers_1.getNetworkLabel)(network);
+    if (networkLabel) {
+        evidence.network_label = networkLabel;
+    }
+    // Add optional fields
+    if (invoice.session_id) {
+        evidence.session_id = invoice.session_id;
+    }
+    if (invoice.invoice_url) {
+        evidence.invoice_url = invoice.invoice_url;
+    }
+    if (invoice.memo) {
+        evidence.memo = invoice.memo;
+    }
+    if (invoice.metadata) {
+        evidence.metadata = invoice.metadata;
+    }
+    // v2: Add payTo if present
+    if (invoice.payTo) {
+        evidence.pay_to = invoice.payTo;
+    }
+    // Build aggregator and splits (v2 only)
+    const { aggregator, splits } = buildAggregatorAndSplits(invoice, resolvedDialect);
+    // Map routing from payTo.mode
+    const routing = mapRouting(invoice.payTo?.mode);
+    // Build PaymentEvidence
+    const result = {
+        rail: 'x402',
+        reference: invoice.id,
+        amount: invoice.amount,
+        currency: invoice.currency,
+        asset: invoice.currency,
+        env,
+        network,
+        evidence,
+    };
+    // Add optional top-level fields
+    if (aggregator) {
+        result.aggregator = aggregator;
+    }
+    if (splits) {
+        result.splits = splits;
+    }
+    if (routing) {
+        result.routing = routing;
+    }
+    return result;
+}
+/**
+ * Normalize x402 settlement to PEAC PaymentEvidence
+ *
+ * @param settlement - x402 settlement object
+ * @param env - Environment ('live' or 'test')
+ * @param dialect - x402 dialect ('v1', 'v2', or 'auto')
+ * @returns Normalized PaymentEvidence
+ */
+function fromSettlement(settlement, env = 'live', dialect = 'auto') {
+    // Validate required fields
+    if (!settlement.id) {
+        throw new Error('x402 settlement missing id');
+    }
+    if (!settlement.invoice_id) {
+        throw new Error('x402 settlement missing invoice_id');
+    }
+    if (typeof settlement.amount !== 'number' || settlement.amount < 0) {
+        throw new Error('x402 settlement invalid amount');
+    }
+    if (!settlement.currency || !/^[A-Z]{3}$/.test(settlement.currency)) {
+        throw new Error('x402 settlement invalid currency (must be uppercase ISO 4217)');
+    }
+    // Resolve dialect (simplified for settlements - check network field)
+    const resolvedDialect = dialect !== 'auto' ? dialect : settlement.network?.includes(':') ? 'v2' : 'v1';
+    // Normalize network
+    const network = (0, helpers_1.normalizeNetworkId)(settlement.network);
+    // Build x402-specific evidence
+    const evidence = {
+        invoice_id: settlement.invoice_id,
+        settlement_id: settlement.id,
+        dialect: resolvedDialect,
+    };
+    // Add network label
+    const networkLabel = (0, helpers_1.getNetworkLabel)(network);
+    if (networkLabel) {
+        evidence.network_label = networkLabel;
+    }
+    // Add optional fields
+    if (settlement.settled_at) {
+        evidence.settled_at = settlement.settled_at;
+    }
+    if (settlement.metadata) {
+        evidence.metadata = settlement.metadata;
+    }
+    return {
+        rail: 'x402',
+        reference: settlement.invoice_id,
+        amount: settlement.amount,
+        currency: settlement.currency,
+        asset: settlement.currency,
+        env,
+        network,
+        evidence,
+    };
+}
+/**
+ * Normalize x402 webhook event to PEAC PaymentEvidence
+ *
+ * Supports:
+ * - invoice.paid
+ * - settlement.completed
+ *
+ * Dialect is auto-detected from headers if provided.
+ *
+ * @param event - x402 webhook event
+ * @param env - Environment ('live' or 'test')
+ * @param headers - HTTP response headers (optional, for dialect detection)
+ * @returns Normalized PaymentEvidence
+ */
+function fromWebhookEvent(event, env = 'live', headers) {
+    const obj = event.data.object;
+    // Detect dialect from headers if provided
+    const dialect = headers ? (0, helpers_1.detectDialect)(headers) : 'auto';
+    // Determine object type by presence of fields
+    if ('invoice_id' in obj && ('settled_at' in obj || 'settlement_id' in obj)) {
+        // Settlement
+        return fromSettlement(obj, env, dialect);
+    }
+    else if ('amount' in obj && 'id' in obj) {
+        // Invoice
+        return fromInvoice(obj, env, dialect);
+    }
+    throw new Error(`Unsupported x402 webhook event type: ${event.type}`);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * x402 type definitions
+ *
+ * Supports both v1 and v2 x402 protocol formats.
+ */
+/**
+ * x402 payTo metadata (v2 only)
+ *
+ * Describes routing information for the payment.
+ */
+export interface X402PayTo {
+    /** Routing mode: direct, callback, or role-based */
+    mode?: 'direct' | 'callback' | 'role';
+    /** Callback URL for payment completion (if mode === 'callback') */
+    callback_url?: string;
+    /** Role identifier (if mode === 'role') */
+    role?: string;
+}
+/**
+ * x402 Invoice (v1 + v2 compatible)
+ *
+ * v2 additions: network (CAIP-2), payTo
+ */
+export interface X402Invoice {
+    /** Invoice identifier */
+    id: string;
+    /** Amount in smallest currency unit */
+    amount: number;
+    /** ISO 4217 currency code (uppercase) */
+    currency: string;
+    /** Session identifier (optional) */
+    session_id?: string;
+    /** Invoice URL for payment (optional) */
+    invoice_url?: string;
+    /** Memo/description (optional) */
+    memo?: string;
+    /** Additional metadata (optional) */
+    metadata?: Record<string, unknown>;
+    /** Network identifier: CAIP-2 for v2, "lightning" for v1 (optional) */
+    network?: string;
+    /** Payment routing metadata - v2 only (optional) */
+    payTo?: X402PayTo;
+}
+/**
+ * x402 Settlement (v1 + v2 compatible)
+ */
+export interface X402Settlement {
+    /** Settlement identifier */
+    id: string;
+    /** Associated invoice ID */
+    invoice_id: string;
+    /** Amount in smallest currency unit */
+    amount: number;
+    /** ISO 4217 currency code (uppercase) */
+    currency: string;
+    /** Settlement timestamp (ISO 8601) */
+    settled_at?: string;
+    /** Additional metadata (optional) */
+    metadata?: Record<string, unknown>;
+    /** Network identifier: CAIP-2 for v2, "lightning" for v1 (optional) */
+    network?: string;
+}
+/**
+ * x402 Webhook event payload
+ */
+export interface X402WebhookEvent {
+    /** Event type (e.g., "invoice.paid", "settlement.completed") */
+    type: string;
+    /** Event data */
+    data: {
+        object: X402Invoice | X402Settlement;
+    };
+}
+/**
+ * x402-specific evidence structure (inside PaymentEvidence.evidence)
+ *
+ * This is namespaced inside the opaque evidence field, not at the top level.
+ */
+export interface X402Evidence {
+    /** Invoice ID */
+    invoice_id: string;
+    /** Which x402 dialect was used */
+    dialect: 'v1' | 'v2';
+    /** Human-readable network label (e.g., "Base", "Solana") */
+    network_label?: string;
+    /** x402 v2 payTo object (preserved as-is from invoice) */
+    pay_to?: X402PayTo;
+    /** Session ID (optional) */
+    session_id?: string;
+    /** Invoice URL (optional) */
+    invoice_url?: string;
+    /** Memo (optional) */
+    memo?: string;
+    /** Settlement ID (for settlements) */
+    settlement_id?: string;
+    /** Settled at timestamp (for settlements) */
+    settled_at?: string;
+    /** User-provided metadata */
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAGnC,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAGnC,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,IAAI,EAAE;QACJ,MAAM,EAAE,WAAW,GAAG,cAAc,CAAC;KACtC,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC"}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * x402 type definitions
+ *
+ * Supports both v1 and v2 x402 protocol formats.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@peac/rails-x402",
+  "version": "0.9.18",
+  "description": "x402 payment rail adapter for PEAC protocol",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/peacprotocol/peac.git",
+    "directory": "packages/rails/x402"
+  },
+  "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/peacprotocol/peac/issues"
+  },
+  "homepage": "https://github.com/peacprotocol/peac#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@peac/schema": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  }
+}