x402check 0.0.1 → 0.1.1

package/README.md

@@ -0,0 +1,135 @@
+# x402check
+
+Validate [x402](https://www.x402.org/) payment configurations. Works in Node, browsers, and edge runtimes — zero dependencies.
+
+**[x402check.com](https://www.x402check.com)** — try it in the browser
+
+## Install
+
+```
+npm i x402check
+```
+
+## Quick start
+
+```js
+import { validate } from 'x402check'
+
+const result = validate({
+  x402Version: 2,
+  accepts: [{
+    scheme: 'exact',
+    network: 'base',
+    payTo: '0x1234567890abcdef1234567890abcdef12345678',
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    amount: '10000',
+    maxTimeoutSeconds: 300
+  }]
+})
+
+result.valid      // true | false
+result.errors     // ValidationIssue[]
+result.warnings   // ValidationIssue[]
+result.normalized // canonical v2 config
+```
+
+## API
+
+### `validate(input, options?)`
+
+Validates a config object or JSON string. Returns errors, warnings, and a normalized v2 config.
+
+```js
+validate(configOrJson)
+validate(configOrJson, { strict: true }) // promotes warnings to errors
+```
+
+**Returns:** `ValidationResult`
+
+```ts
+{
+  valid: boolean
+  version: 'v2' | 'v1' | 'unknown'
+  errors: ValidationIssue[]
+  warnings: ValidationIssue[]
+  normalized: NormalizedConfig | null
+}
+```
+
+Each issue includes a machine-readable `code`, a `field` path, a human-readable `message`, and an optional `fix` suggestion.
+
+### `extractConfig(response)`
+
+Extracts an x402 config from an HTTP 402 response. Checks the JSON body first, then falls back to the `PAYMENT-REQUIRED` header (base64 or raw JSON).
+
+```js
+const res = await fetch(url)
+const { config, source, error } = extractConfig({
+  body: await res.json(),
+  headers: res.headers
+})
+// source: 'body' | 'header' | null
+```
+
+### `detect(input)`
+
+Returns the config format: `'v2'`, `'v1'`, or `'unknown'`.
+
+```js
+detect({ x402Version: 2, accepts: [...] }) // 'v2'
+```
+
+### `normalize(input)`
+
+Converts any supported config to canonical v2 shape. Returns `null` if the format is unrecognized.
+
+```js
+const v2Config = normalize(v1Config)
+```
+
+### Address validation
+
+```js
+import { validateAddress, validateEvmAddress, validateSolanaAddress } from 'x402check'
+
+validateAddress(addr, 'eip155:8453', 'payTo')   // dispatches by network
+validateEvmAddress(addr, 'payTo')                // EIP-55 checksum verification
+validateSolanaAddress(addr, 'payTo')             // base58, 32-byte decode check
+```
+
+### Network & asset registry
+
+```js
+import {
+  isKnownNetwork, getNetworkInfo, getCanonicalNetwork,
+  isKnownAsset, getAssetInfo, isValidCaip2
+} from 'x402check'
+
+isValidCaip2('eip155:8453')           // true
+getCanonicalNetwork('base')           // 'eip155:8453'
+getNetworkInfo('eip155:8453')         // { name: 'Base', type: 'evm', testnet: false }
+isKnownAsset('eip155:8453', '0x833…') // true
+getAssetInfo('eip155:8453', '0x833…') // { symbol: 'USDC', name: 'USD Coin', decimals: 6 }
+```
+
+## Supported formats
+
+| Format | `x402Version` | Status |
+|--------|---------------|--------|
+| v2     | `2`           | Recommended |
+| v1     | `1`           | Supported, auto-normalized to v2 |
+
+## Validation checks
+
+- Required fields (`scheme`, `network`, `amount`, `asset`, `payTo`)
+- Amount is a numeric string > 0
+- Network is valid [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md)
+- EVM addresses: `0x`-prefixed, 40 hex chars, EIP-55 checksum
+- Solana addresses: base58, decodes to 32 bytes
+- Known network and asset registry warnings
+- `maxTimeoutSeconds` is a positive integer (if present)
+- Resource URL format (if present)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -1824,9 +1824,101 @@ function runPipeline(input, options) {
 	};
 }
 
+//#endregion
+//#region src/extraction/extract.ts
+/**
+* Get a header value, case-insensitive.
+* Supports both Headers objects and plain Record<string, string>.
+*/
+function getHeader(headers, name) {
+	if (!headers) return null;
+	if (typeof headers.get === "function") return headers.get(name);
+	const lower = name.toLowerCase();
+	for (const key of Object.keys(headers)) if (key.toLowerCase() === lower) return headers[key];
+	return null;
+}
+/**
+* Decode base64 string to UTF-8 text.
+* Works in both browser (atob) and Node (Buffer).
+*/
+function decodeBase64(encoded) {
+	if (typeof atob === "function") return atob(encoded);
+	return Buffer.from(encoded, "base64").toString("utf-8");
+}
+/**
+* Check if a parsed object looks like it contains x402 config fields.
+*/
+function hasX402Fields(obj) {
+	if (!obj || typeof obj !== "object") return false;
+	const rec = obj;
+	return !!(rec.accepts || rec.payTo || rec.x402Version);
+}
+/**
+* Try to parse the PAYMENT-REQUIRED header value as a base64-encoded JSON config.
+*/
+function tryHeaderExtraction(headers) {
+	const headerValue = getHeader(headers, "payment-required");
+	if (!headerValue) return null;
+	try {
+		const decoded = decodeBase64(headerValue);
+		const parsed = JSON.parse(decoded);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return {
+			config: parsed,
+			source: "header"
+		};
+	} catch {}
+	try {
+		const parsed = JSON.parse(headerValue);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return {
+			config: parsed,
+			source: "header"
+		};
+	} catch {}
+	return null;
+}
+/**
+* Extract an x402 config from an HTTP 402 response.
+*
+* Extraction priority:
+* 1. JSON body — if it parses and has x402 fields (accepts, payTo, x402Version)
+* 2. PAYMENT-REQUIRED header — base64-decoded JSON fallback
+*
+* Never throws. Returns structured result with error message on failure.
+*
+* @param response - Response-like object with body and/or headers
+* @returns Extraction result with config, source, and error
+*/
+function extractConfig(response) {
+	const body = response.body;
+	if (body && typeof body === "object" && !Array.isArray(body) && hasX402Fields(body)) return {
+		config: body,
+		source: "body",
+		error: null
+	};
+	if (typeof body === "string" && body.trim()) try {
+		const parsed = JSON.parse(body);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && hasX402Fields(parsed)) return {
+			config: parsed,
+			source: "body",
+			error: null
+		};
+	} catch {}
+	const headerResult = tryHeaderExtraction(response.headers);
+	if (headerResult) return {
+		config: headerResult.config,
+		source: headerResult.source,
+		error: null
+	};
+	return {
+		config: null,
+		source: null,
+		error: "No x402 config found in response body or PAYMENT-REQUIRED header"
+	};
+}
+
 //#endregion
 //#region src/index.ts
-const VERSION = "0.0.1";
+const VERSION = "0.1.0";
 
 //#endregion
 exports.CAIP2_REGEX = CAIP2_REGEX;
@@ -1838,6 +1930,7 @@ exports.SIMPLE_NAME_TO_CAIP2 = SIMPLE_NAME_TO_CAIP2;
 exports.VERSION = VERSION;
 exports.decodeBase58 = decodeBase58;
 exports.detect = detect;
+exports.extractConfig = extractConfig;
 exports.getAssetInfo = getAssetInfo;
 exports.getCanonicalNetwork = getCanonicalNetwork;
 exports.getNetworkInfo = getNetworkInfo;