x402check 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,465 @@
+//#region src/types/config.d.ts
+/**
+ * Type definitions for all x402 config formats
+ */
+/**
+ * Config format discriminator
+ */
+type ConfigFormat = 'v2' | 'v1' | 'unknown';
+/**
+ * HTTP resource definition
+ */
+interface Resource {
+  url: string;
+  method?: string | undefined;
+  headers?: Record<string, string> | undefined;
+  body?: string | undefined;
+}
+/**
+ * V2 accepts array entry
+ */
+interface AcceptsEntry {
+  scheme: string;
+  network: string;
+  amount: string;
+  asset: string;
+  payTo: string;
+  maxTimeoutSeconds?: number | undefined;
+  extra?: Record<string, unknown> | undefined;
+}
+/**
+ * x402 v2 config shape
+ */
+interface V2Config {
+  x402Version: 2;
+  accepts: AcceptsEntry[];
+  resource: Resource;
+  error?: string | undefined;
+  extensions?: Record<string, unknown> | undefined;
+}
+/**
+ * V1 accepts array entry (different field names from v2)
+ */
+interface V1AcceptsEntry {
+  scheme: string;
+  network: string;
+  maxAmountRequired: string;
+  asset: string;
+  payTo: string;
+  maxTimeoutSeconds?: number | undefined;
+  extra?: Record<string, unknown> | undefined;
+  resource?: Resource | undefined;
+}
+/**
+ * x402 v1 config shape
+ */
+interface V1Config {
+  x402Version: 1;
+  accepts: V1AcceptsEntry[];
+  error?: string | undefined;
+  extensions?: Record<string, unknown> | undefined;
+}
+/**
+ * Normalized config output (canonical v2 shape)
+ */
+interface NormalizedConfig {
+  x402Version: 2;
+  accepts: AcceptsEntry[];
+  resource?: Resource | undefined;
+  error?: string | undefined;
+  extensions?: Record<string, unknown> | undefined;
+}
+//#endregion
+//#region src/types/errors.d.ts
+/**
+ * Error and warning code vocabulary for x402check
+ */
+declare const ErrorCode: {
+  readonly INVALID_JSON: "INVALID_JSON";
+  readonly NOT_OBJECT: "NOT_OBJECT";
+  readonly UNKNOWN_FORMAT: "UNKNOWN_FORMAT";
+  readonly MISSING_VERSION: "MISSING_VERSION";
+  readonly INVALID_VERSION: "INVALID_VERSION";
+  readonly MISSING_ACCEPTS: "MISSING_ACCEPTS";
+  readonly EMPTY_ACCEPTS: "EMPTY_ACCEPTS";
+  readonly INVALID_ACCEPTS: "INVALID_ACCEPTS";
+  readonly MISSING_SCHEME: "MISSING_SCHEME";
+  readonly MISSING_NETWORK: "MISSING_NETWORK";
+  readonly INVALID_NETWORK_FORMAT: "INVALID_NETWORK_FORMAT";
+  readonly MISSING_AMOUNT: "MISSING_AMOUNT";
+  readonly INVALID_AMOUNT: "INVALID_AMOUNT";
+  readonly ZERO_AMOUNT: "ZERO_AMOUNT";
+  readonly MISSING_ASSET: "MISSING_ASSET";
+  readonly MISSING_PAY_TO: "MISSING_PAY_TO";
+  readonly MISSING_RESOURCE: "MISSING_RESOURCE";
+  readonly INVALID_URL: "INVALID_URL";
+  readonly INVALID_TIMEOUT: "INVALID_TIMEOUT";
+  readonly INVALID_EVM_ADDRESS: "INVALID_EVM_ADDRESS";
+  readonly BAD_EVM_CHECKSUM: "BAD_EVM_CHECKSUM";
+  readonly NO_EVM_CHECKSUM: "NO_EVM_CHECKSUM";
+  readonly INVALID_SOLANA_ADDRESS: "INVALID_SOLANA_ADDRESS";
+  readonly ADDRESS_NETWORK_MISMATCH: "ADDRESS_NETWORK_MISMATCH";
+  readonly UNKNOWN_NETWORK: "UNKNOWN_NETWORK";
+  readonly UNKNOWN_ASSET: "UNKNOWN_ASSET";
+  readonly LEGACY_FORMAT: "LEGACY_FORMAT";
+  readonly MISSING_MAX_TIMEOUT: "MISSING_MAX_TIMEOUT";
+};
+type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
+/**
+ * Human-readable error messages for all error codes
+ */
+declare const ErrorMessages: {
+  INVALID_JSON: string;
+  NOT_OBJECT: string;
+  UNKNOWN_FORMAT: string;
+  MISSING_VERSION: string;
+  INVALID_VERSION: string;
+  MISSING_ACCEPTS: string;
+  EMPTY_ACCEPTS: string;
+  INVALID_ACCEPTS: string;
+  MISSING_SCHEME: string;
+  MISSING_NETWORK: string;
+  INVALID_NETWORK_FORMAT: string;
+  MISSING_AMOUNT: string;
+  INVALID_AMOUNT: string;
+  ZERO_AMOUNT: string;
+  MISSING_ASSET: string;
+  MISSING_PAY_TO: string;
+  MISSING_RESOURCE: string;
+  INVALID_URL: string;
+  INVALID_TIMEOUT: string;
+  INVALID_EVM_ADDRESS: string;
+  BAD_EVM_CHECKSUM: string;
+  NO_EVM_CHECKSUM: string;
+  INVALID_SOLANA_ADDRESS: string;
+  ADDRESS_NETWORK_MISMATCH: string;
+  UNKNOWN_NETWORK: string;
+  UNKNOWN_ASSET: string;
+  LEGACY_FORMAT: string;
+  MISSING_MAX_TIMEOUT: string;
+};
+//#endregion
+//#region src/types/validation.d.ts
+/**
+ * Issue severity level
+ */
+type Severity = 'error' | 'warning';
+/**
+ * Validation issue detail
+ */
+interface ValidationIssue {
+  code: ErrorCode;
+  field: string;
+  message: string;
+  severity: Severity;
+  fix?: string | undefined;
+}
+/**
+ * Validation result with errors, warnings, and normalized config
+ */
+interface ValidationResult {
+  valid: boolean;
+  version: ConfigFormat;
+  errors: ValidationIssue[];
+  warnings: ValidationIssue[];
+  normalized: NormalizedConfig | null;
+}
+/**
+ * Parsed input result (for parseInput utility)
+ */
+interface ParsedInput {
+  parsed: unknown;
+  error?: ValidationIssue | undefined;
+}
+//#endregion
+//#region src/types/parse-input.d.ts
+/**
+ * Parse input that may be either a JSON string or an object
+ * API-04: Accept string | object
+ */
+declare function parseInput(input: string | object): ParsedInput;
+//#endregion
+//#region src/registries/networks.d.ts
+type NetworkType = 'evm' | 'solana' | 'stellar' | 'aptos';
+interface NetworkInfo {
+  name: string;
+  type: NetworkType;
+  testnet: boolean;
+}
+declare const CAIP2_REGEX: RegExp;
+declare const KNOWN_NETWORKS: {
+  readonly 'eip155:8453': {
+    readonly name: "Base";
+    readonly type: "evm";
+    readonly testnet: false;
+  };
+  readonly 'eip155:84532': {
+    readonly name: "Base Sepolia";
+    readonly type: "evm";
+    readonly testnet: true;
+  };
+  readonly 'eip155:43114': {
+    readonly name: "Avalanche C-Chain";
+    readonly type: "evm";
+    readonly testnet: false;
+  };
+  readonly 'eip155:43113': {
+    readonly name: "Avalanche Fuji";
+    readonly type: "evm";
+    readonly testnet: true;
+  };
+  readonly 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': {
+    readonly name: "Solana Mainnet";
+    readonly type: "solana";
+    readonly testnet: false;
+  };
+  readonly 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1': {
+    readonly name: "Solana Devnet";
+    readonly type: "solana";
+    readonly testnet: true;
+  };
+  readonly 'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z': {
+    readonly name: "Solana Testnet";
+    readonly type: "solana";
+    readonly testnet: true;
+  };
+  readonly 'stellar:pubnet': {
+    readonly name: "Stellar Mainnet";
+    readonly type: "stellar";
+    readonly testnet: false;
+  };
+  readonly 'stellar:testnet': {
+    readonly name: "Stellar Testnet";
+    readonly type: "stellar";
+    readonly testnet: true;
+  };
+  readonly 'aptos:1': {
+    readonly name: "Aptos Mainnet";
+    readonly type: "aptos";
+    readonly testnet: false;
+  };
+  readonly 'aptos:2': {
+    readonly name: "Aptos Testnet";
+    readonly type: "aptos";
+    readonly testnet: true;
+  };
+};
+declare function isValidCaip2(value: string): boolean;
+declare function isKnownNetwork(caip2: string): boolean;
+declare function getNetworkInfo(caip2: string): NetworkInfo | undefined;
+declare function getNetworkNamespace(caip2: string): string | undefined;
+//#endregion
+//#region src/registries/assets.d.ts
+interface AssetInfo {
+  symbol: string;
+  name: string;
+  decimals: number;
+}
+declare const KNOWN_ASSETS: {
+  readonly 'eip155:8453': {
+    readonly '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': {
+      readonly symbol: "USDC";
+      readonly name: "USD Coin";
+      readonly decimals: 6;
+    };
+  };
+  readonly 'eip155:84532': {
+    readonly '0x036cbd53842c5426634e7929541ec2318f3dcf7e': {
+      readonly symbol: "USDC";
+      readonly name: "USD Coin";
+      readonly decimals: 6;
+    };
+  };
+  readonly 'eip155:43114': {
+    readonly '0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e': {
+      readonly symbol: "USDC";
+      readonly name: "USD Coin";
+      readonly decimals: 6;
+    };
+  };
+  readonly 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': {
+    readonly EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: {
+      readonly symbol: "USDC";
+      readonly name: "USD Coin";
+      readonly decimals: 6;
+    };
+  };
+};
+declare function isKnownAsset(network: string, address: string): boolean;
+declare function getAssetInfo(network: string, address: string): AssetInfo | undefined;
+//#endregion
+//#region src/registries/simple-names.d.ts
+declare const SIMPLE_NAME_TO_CAIP2: {
+  readonly base: "eip155:8453";
+  readonly 'base-sepolia': "eip155:84532";
+  readonly base_sepolia: "eip155:84532";
+  readonly avalanche: "eip155:43114";
+  readonly 'avalanche-fuji': "eip155:43113";
+  readonly solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+  readonly 'solana-devnet': "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+  readonly 'solana-testnet': "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z";
+  readonly stellar: "stellar:pubnet";
+  readonly 'stellar-testnet': "stellar:testnet";
+  readonly aptos: "aptos:1";
+};
+declare function getCanonicalNetwork(name: string): string | undefined;
+//#endregion
+//#region src/detection/detect.d.ts
+/**
+ * Detect the format of an x402 config
+ *
+ * @param input - JSON string or parsed object
+ * @returns ConfigFormat literal: 'v2' | 'v1' | 'unknown'
+ *
+ * Detection requires x402Version field:
+ * 1. v2: accepts array + x402Version: 2
+ * 2. v1: accepts array + x402Version: 1
+ * 3. unknown: anything else (including versionless configs)
+ */
+declare function detect(input: string | object): ConfigFormat;
+//#endregion
+//#region src/detection/normalize.d.ts
+/**
+ * Normalize any x402 config format to canonical v2 shape
+ *
+ * @param input - JSON string or parsed object
+ * @returns NormalizedConfig or null if format is unknown/invalid
+ *
+ * Normalization rules:
+ * - v2: Pass through with new object (FMT-07)
+ * - v1: Map maxAmountRequired → amount, lift per-entry resource (FMT-06)
+ * - unknown: Return null
+ *
+ * All transformations preserve extensions and extra fields (FMT-08)
+ */
+declare function normalize(input: string | object): NormalizedConfig | null;
+//#endregion
+//#region src/crypto/keccak256.d.ts
+/**
+ * Keccak-256 hash function wrapper
+ * Uses @noble/hashes for audited, tree-shakeable implementation
+ */
+/**
+ * Compute Keccak-256 hash (NOT SHA-3)
+ *
+ * @param input - String or Uint8Array to hash
+ * @returns Lowercase hex string (64 chars, no 0x prefix)
+ */
+declare function keccak256(input: string | Uint8Array): string;
+//#endregion
+//#region src/crypto/base58.d.ts
+/**
+ * Base58 decoder wrapper
+ * Uses @scure/base for audited, tree-shakeable implementation
+ */
+/**
+ * Decode a Base58-encoded string to bytes
+ *
+ * Preserves leading zero bytes (represented as leading '1' characters)
+ *
+ * @param input - Base58 string
+ * @returns Decoded bytes
+ * @throws Error if input contains invalid Base58 characters
+ */
+declare function decodeBase58(input: string): Uint8Array;
+//#endregion
+//#region src/crypto/eip55.d.ts
+/**
+ * EIP-55 mixed-case checksum address encoding
+ * Spec: https://eips.ethereum.org/EIPS/eip-55
+ */
+/**
+ * Convert an Ethereum address to EIP-55 checksummed format
+ *
+ * @param address - 42-character hex address (0x-prefixed)
+ * @returns Checksummed address with mixed case
+ */
+declare function toChecksumAddress(address: string): string;
+/**
+ * Check if an address has valid EIP-55 checksum
+ *
+ * Returns false for all-lowercase or all-uppercase addresses
+ * (these are valid formats but do not match their checksummed version)
+ *
+ * @param address - Address to validate
+ * @returns True if checksum is valid
+ */
+declare function isValidChecksum(address: string): boolean;
+//#endregion
+//#region src/validation/evm-address.d.ts
+/**
+ * Validate an EVM address format and checksum
+ *
+ * Returns errors for invalid format, warnings for checksum issues
+ *
+ * @param address - Address to validate
+ * @param field - Field path for error reporting
+ * @returns Array of validation issues (empty if valid)
+ */
+declare function validateEvmAddress(address: string, field: string): ValidationIssue[];
+//#endregion
+//#region src/validation/solana-address.d.ts
+/**
+ * Validate a Solana address (Base58 encoded public key)
+ *
+ * Checks Base58 format and verifies decoded length is exactly 32 bytes
+ *
+ * @param address - Address to validate
+ * @param field - Field path for error reporting
+ * @returns Array of validation issues (empty if valid)
+ */
+declare function validateSolanaAddress(address: string, field: string): ValidationIssue[];
+//#endregion
+//#region src/validation/address.d.ts
+/**
+ * Validate an address for a specific network
+ *
+ * Dispatches to appropriate chain-specific validator based on CAIP-2 namespace:
+ * - eip155:* → EVM address validation
+ * - solana:* → Solana address validation
+ * - stellar:*, aptos:* → Accept any string (deep validation deferred)
+ * - Unknown namespaces → Accept any string (registry warnings handled elsewhere)
+ *
+ * Cross-chain mismatches are caught naturally by dispatch:
+ * - EVM address (0x...) on Solana network → fails Solana Base58 validation
+ * - Solana address on EVM network → fails EVM 0x-prefix validation
+ *
+ * @param address - Address to validate
+ * @param network - CAIP-2 network identifier
+ * @param field - Field path for error reporting
+ * @returns Array of validation issues (empty if valid)
+ */
+declare function validateAddress(address: string, network: string, field: string): ValidationIssue[];
+//#endregion
+//#region src/validation/orchestrator.d.ts
+/**
+ * Options for the validate() orchestrator
+ */
+interface ValidationOptions {
+  /** When true, all warnings are promoted to errors */
+  strict?: boolean | undefined;
+}
+/**
+ * Validate an x402 config through the full pipeline.
+ *
+ * Takes any input (JSON string or object), runs it through:
+ * 1. Structure validation (parse, object check, format detection)
+ * 2. Normalization to canonical v2 shape
+ * 3. Version, accepts, resource validation
+ * 4. Per-entry field, network, asset, amount, timeout, address validation
+ * 5. Legacy format warnings
+ * 6. Strict mode promotion (warnings -> errors)
+ *
+ * NEVER throws -- all invalid inputs produce structured error results.
+ *
+ * @param input - JSON string or parsed object to validate
+ * @param options - Validation options (e.g. strict mode)
+ * @returns Structured validation result
+ */
+declare function validate(input: string | object, options?: ValidationOptions | undefined): ValidationResult;
+//#endregion
+//#region src/index.d.ts
+declare const VERSION: "0.0.1";
+//#endregion
+export { AcceptsEntry, AssetInfo, CAIP2_REGEX, ConfigFormat, ErrorCode, ErrorMessages, KNOWN_ASSETS, KNOWN_NETWORKS, NetworkInfo, NetworkType, NormalizedConfig, ParsedInput, Resource, SIMPLE_NAME_TO_CAIP2, Severity, V1AcceptsEntry, V1Config, V2Config, VERSION, ValidationIssue, type ValidationOptions, ValidationResult, decodeBase58, detect, getAssetInfo, getCanonicalNetwork, getNetworkInfo, getNetworkNamespace, isKnownAsset, isKnownNetwork, isValidCaip2, isValidChecksum, keccak256, normalize, parseInput, toChecksumAddress, validate, validateAddress, validateEvmAddress, validateSolanaAddress };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types/config.ts","../src/types/errors.ts","../src/types/validation.ts","../src/types/parse-input.ts","../src/registries/networks.ts","../src/registries/assets.ts","../src/registries/simple-names.ts","../src/detection/detect.ts","../src/detection/normalize.ts","../src/crypto/keccak256.ts","../src/crypto/base58.ts","../src/crypto/eip55.ts","../src/validation/evm-address.ts","../src/validation/solana-address.ts","../src/validation/address.ts","../src/validation/orchestrator.ts","../src/index.ts"],"mappings":"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"}