@peac/rails-x402 0.12.5 → 0.12.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +104 -3
  2. package/package.json +17 -5
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @peac/rails-x402
2
2
 
3
- x402 payment rail adapter for PEAC protocol
3
+ x402 payment rail adapter for PEAC protocol: normalizes x402 invoices, settlements, and webhook events to signed evidence receipts with v1/v2 dialect auto-detection.
4
4
 
5
5
  ## Installation
6
6
 
@@ -8,9 +8,110 @@ x402 payment rail adapter for PEAC protocol
8
8
  pnpm add @peac/rails-x402
9
9
  ```
10
10
 
11
- ## Documentation
11
+ ## What It Does
12
12
 
13
- See [peacprotocol.org](https://www.peacprotocol.org) for full documentation.
13
+ `@peac/rails-x402` maps x402 payment protocol objects to PEAC `PaymentEvidence` for inclusion in signed interaction receipts. It supports both v1 (legacy `X-PAYMENT-*` headers) and v2 (`Payment-*` headers) dialects with automatic detection. Network identifiers use CAIP-2 format, and the adapter includes header detection utilities for HTTP payment flows.
14
+
15
+ ## How Do I Use It?
16
+
17
+ ### Normalize an x402 invoice
18
+
19
+ ```typescript
20
+ import { fromInvoice } from '@peac/rails-x402';
21
+
22
+ const evidence = fromInvoice({
23
+ id: 'inv_abc123',
24
+ amount: 1000000,
25
+ currency: 'USD',
26
+ network: 'eip155:8453',
27
+ payTo: { mode: 'direct' },
28
+ });
29
+ // evidence.rail === 'x402'
30
+ // evidence.network === 'eip155:8453'
31
+ // evidence.routing === 'direct'
32
+ ```
33
+
34
+ ### Normalize a settlement
35
+
36
+ ```typescript
37
+ import { fromSettlement } from '@peac/rails-x402';
38
+
39
+ const evidence = fromSettlement({
40
+ id: 'stl_xyz',
41
+ invoice_id: 'inv_abc123',
42
+ amount: 1000000,
43
+ currency: 'USD',
44
+ network: 'eip155:8453',
45
+ settled_at: '2026-03-15T12:00:00Z',
46
+ });
47
+ // evidence.reference === 'inv_abc123'
48
+ ```
49
+
50
+ ### Detect x402 payment headers
51
+
52
+ ```typescript
53
+ import { detectPaymentRequired, extractPaymentReference } from '@peac/rails-x402';
54
+
55
+ // Works with native Headers, Express req.headers, or plain objects
56
+ const headers = { 'payment-required': 'base64-encoded-invoice' };
57
+
58
+ if (detectPaymentRequired(headers)) {
59
+ const reference = extractPaymentReference(headers);
60
+ // reference === 'base64-encoded-invoice'
61
+ }
62
+ ```
63
+
64
+ ### Detect dialect from response headers
65
+
66
+ ```typescript
67
+ import { detectDialect, getHeaders } from '@peac/rails-x402';
68
+
69
+ const dialect = detectDialect({ 'payment-required': '...' });
70
+ // dialect === 'v2'
71
+
72
+ const headerNames = getHeaders(dialect);
73
+ // headerNames.paymentRequired === 'Payment-Required'
74
+ ```
75
+
76
+ ### Handle webhook events
77
+
78
+ ```typescript
79
+ import { fromWebhookEvent } from '@peac/rails-x402';
80
+
81
+ const evidence = fromWebhookEvent(
82
+ {
83
+ type: 'invoice.paid',
84
+ data: {
85
+ object: {
86
+ id: 'inv_abc',
87
+ amount: 500000,
88
+ currency: 'USD',
89
+ network: 'eip155:8453',
90
+ },
91
+ },
92
+ },
93
+ 'live',
94
+ { 'payment-required': '...' }
95
+ );
96
+ ```
97
+
98
+ ## Integrates With
99
+
100
+ - `@peac/kernel` (Layer 0): Types and constants
101
+ - `@peac/schema` (Layer 1): `PaymentEvidence` and `PaymentSplit` schema validation
102
+ - `@peac/protocol` (Layer 3): Receipt issuance using normalized evidence
103
+ - `@peac/adapter-x402` (Layer 4): Higher-level x402 receipt verification and extraction
104
+ - `@peac/rails-stripe` (Layer 4): Stripe crypto payment intents settled via x402
105
+
106
+ ## For Agent Developers
107
+
108
+ If you are building an AI agent that handles x402 machine-to-machine payments:
109
+
110
+ - Use `fromInvoice` and `fromSettlement` to capture x402 payment evidence
111
+ - Use `detectPaymentRequired` to check HTTP responses for x402 payment challenges
112
+ - The adapter auto-detects v1/v2 dialect; pass `'v1'` or `'v2'` explicitly to override
113
+ - Network identifiers use CAIP-2 format (e.g., `eip155:8453` for Base)
114
+ - See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise overview
14
115
 
15
116
  ## License
16
117
 
package/package.json CHANGED
@@ -1,15 +1,15 @@
1
1
  {
2
2
  "name": "@peac/rails-x402",
3
- "version": "0.12.5",
3
+ "version": "0.12.6",
4
4
  "description": "x402 payment rail adapter for PEAC protocol",
5
5
  "main": "dist/index.cjs",
6
6
  "types": "dist/index.d.ts",
7
7
  "repository": {
8
8
  "type": "git",
9
- "url": "https://github.com/peacprotocol/peac.git",
9
+ "url": "git+https://github.com/peacprotocol/peac.git",
10
10
  "directory": "packages/rails/x402"
11
11
  },
12
- "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
12
+ "author": "PEAC Protocol Contributors",
13
13
  "license": "Apache-2.0",
14
14
  "bugs": {
15
15
  "url": "https://github.com/peacprotocol/peac/issues"
@@ -23,8 +23,8 @@
23
23
  "access": "public"
24
24
  },
25
25
  "dependencies": {
26
- "@peac/schema": "0.12.5",
27
- "@peac/kernel": "0.12.5"
26
+ "@peac/kernel": "0.12.6",
27
+ "@peac/schema": "0.12.6"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@types/node": "^22.19.11",
@@ -41,6 +41,18 @@
41
41
  },
42
42
  "./package.json": "./package.json"
43
43
  },
44
+ "keywords": [
45
+ "peac",
46
+ "peacprotocol",
47
+ "interaction-records",
48
+ "signed-records",
49
+ "receipts",
50
+ "originary",
51
+ "x402",
52
+ "http-402",
53
+ "payment",
54
+ "machine-payments"
55
+ ],
44
56
  "scripts": {
45
57
  "prebuild": "rm -rf dist",
46
58
  "build": "pnpm run build:js && pnpm run build:types",