s402 0.2.1 → 0.2.3

package/README.md

@@ -36,6 +36,18 @@ HTTP 402 ("Payment Required") has been reserved since 1999 — waiting for a pay
 
 **s402 is Sui-native by design.** These advantages come from Sui's object model, PTBs, and sub-second finality. They can't be replicated on EVM — and they don't need to be. x402 already handles EVM well. s402 handles Sui better.
 
+## Which Scheme Should I Use?
+
+| Your situation | Scheme | Gas per 1K calls | Latency |
+|---|---|---|---|
+| One-time API call, simplest path | **Exact** | $7.00 | ~400ms |
+| High-frequency API (10+ calls) | **Prepaid** | $0.014 | ~0ms per call |
+| Buyer needs dispute protection | **Escrow** | $7.00 | ~400ms |
+| Selling encrypted content | **Unlock** | $7.00 | ~400ms |
+| Real-time billing (per-second) | **Stream** | variable | ~400ms setup |
+
+**Quick decision:** Use **Prepaid** for AI agents making repeated API calls. Use **Exact** for everything else (it's the x402-compatible default). See the [full guide](https://s402-protocol.org/guide/which-scheme) for details.
+
 ## Architecture
 
 ```

package/dist/compat.d.mts

@@ -108,6 +108,20 @@ declare function fromX402Envelope(envelope: x402PaymentRequiredEnvelope): s402Pa
  * Validates required fields to catch malformed/malicious payloads at the trust boundary.
  *
  * Returns a clean object with only known s402 fields — unknown top-level keys are stripped.
+ *
+ * @param obj - Raw decoded JSON (could be s402, x402 V1, or x402 V2 envelope)
+ * @returns Validated s402PaymentRequirements
+ * @throws {s402Error} `INVALID_PAYLOAD` if the format is unrecognized or malformed
+ *
+ * @example
+ * ```ts
+ * import { normalizeRequirements } from 's402/compat';
+ *
+ * // Works with any format — auto-detects s402 vs x402
+ * const rawJson = JSON.parse(atob(header));
+ * const requirements = normalizeRequirements(rawJson);
+ * // Always returns s402PaymentRequirements regardless of input format
+ * ```
  */
 declare function normalizeRequirements(obj: Record<string, unknown>): s402PaymentRequirements;
 //#endregion

package/dist/compat.mjs

@@ -127,8 +127,23 @@ function fromX402Envelope(envelope) {
 * Validates required fields to catch malformed/malicious payloads at the trust boundary.
 *
 * Returns a clean object with only known s402 fields — unknown top-level keys are stripped.
+*
+* @param obj - Raw decoded JSON (could be s402, x402 V1, or x402 V2 envelope)
+* @returns Validated s402PaymentRequirements
+* @throws {s402Error} `INVALID_PAYLOAD` if the format is unrecognized or malformed
+*
+* @example
+* ```ts
+* import { normalizeRequirements } from 's402/compat';
+*
+* // Works with any format — auto-detects s402 vs x402
+* const rawJson = JSON.parse(atob(header));
+* const requirements = normalizeRequirements(rawJson);
+* // Always returns s402PaymentRequirements regardless of input format
+* ```
 */
 function normalizeRequirements(obj) {
+	if (obj == null || typeof obj !== "object" || Array.isArray(obj)) throw new s402Error("INVALID_PAYLOAD", `Payment requirements must be a plain object, got ${obj === null ? "null" : Array.isArray(obj) ? "array" : typeof obj}`);
 	if (isS402(obj)) {
 		validateRequirementsShape(obj);
 		return pickRequirementsFields(obj);

package/dist/errors.d.mts

@@ -33,10 +33,36 @@ interface s402ErrorInfo {
 }
 /**
  * Create a typed s402 error with recovery hints.
+ *
+ * @param code - One of the 15 s402 error codes (e.g. 'SETTLEMENT_FAILED')
+ * @param message - Optional human-readable message (defaults to the code)
+ * @returns Error info object with code, message, retryable flag, and suggestedAction
+ *
+ * @example
+ * ```ts
+ * const info = createS402Error('INSUFFICIENT_BALANCE');
+ * // { code: 'INSUFFICIENT_BALANCE', message: 'INSUFFICIENT_BALANCE',
+ * //   retryable: false, suggestedAction: 'Top up wallet balance...' }
+ * ```
  */
 declare function createS402Error(code: s402ErrorCodeType, message?: string): s402ErrorInfo;
 /**
  * s402 error class for throwing in code.
+ * Every instance includes a machine-readable `code`, `retryable` flag, and `suggestedAction`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await facilitator.process(payload, requirements);
+ * } catch (e) {
+ *   if (e instanceof s402Error) {
+ *     console.log(e.code);            // 'SETTLEMENT_FAILED'
+ *     console.log(e.retryable);       // true
+ *     console.log(e.suggestedAction); // 'Transient RPC failure...'
+ *     if (e.retryable) { } // retry with exponential backoff
+ *   }
+ * }
+ * ```
  */
 declare class s402Error extends Error {
   readonly code: s402ErrorCodeType;

package/dist/errors.mjs

@@ -89,6 +89,17 @@ const ERROR_HINTS = {
 };
 /**
 * Create a typed s402 error with recovery hints.
+*
+* @param code - One of the 15 s402 error codes (e.g. 'SETTLEMENT_FAILED')
+* @param message - Optional human-readable message (defaults to the code)
+* @returns Error info object with code, message, retryable flag, and suggestedAction
+*
+* @example
+* ```ts
+* const info = createS402Error('INSUFFICIENT_BALANCE');
+* // { code: 'INSUFFICIENT_BALANCE', message: 'INSUFFICIENT_BALANCE',
+* //   retryable: false, suggestedAction: 'Top up wallet balance...' }
+* ```
 */
 function createS402Error(code, message) {
 	const hints = ERROR_HINTS[code];
@@ -101,6 +112,21 @@ function createS402Error(code, message) {
 }
 /**
 * s402 error class for throwing in code.
+* Every instance includes a machine-readable `code`, `retryable` flag, and `suggestedAction`.
+*
+* @example
+* ```ts
+* try {
+*   await facilitator.process(payload, requirements);
+* } catch (e) {
+*   if (e instanceof s402Error) {
+*     console.log(e.code);            // 'SETTLEMENT_FAILED'
+*     console.log(e.retryable);       // true
+*     console.log(e.suggestedAction); // 'Transient RPC failure...'
+*     if (e.retryable) { } // retry with exponential backoff
+*   }
+* }
+* ```
 */
 var s402Error = class extends Error {
 	code;

package/dist/http.d.mts

@@ -1,19 +1,85 @@
 import { s402PaymentPayload, s402PaymentRequirements, s402SettleResponse } from "./types.mjs";
 
 //#region src/http.d.ts
-/** Encode payment requirements for the `payment-required` header */
+/**
+ * Encode payment requirements for the `payment-required` header.
+ *
+ * @param requirements - Typed s402 payment requirements
+ * @returns Base64-encoded JSON string for the HTTP header
+ *
+ * @example
+ * ```ts
+ * import { encodePaymentRequired } from 's402/http';
+ *
+ * const header = encodePaymentRequired({
+ *   s402Version: '1',
+ *   accepts: ['exact'],
+ *   network: 'sui:mainnet',
+ *   asset: '0x2::sui::SUI',
+ *   amount: '1000000',
+ *   payTo: '0xYOUR_ADDRESS',
+ * });
+ * response.headers.set('payment-required', header);
+ * ```
+ */
 declare function encodePaymentRequired(requirements: s402PaymentRequirements): string;
-/** Encode payment payload for the `x-payment` header */
+/**
+ * Encode payment payload for the `x-payment` header.
+ *
+ * @param payload - Typed s402 payment payload (any scheme)
+ * @returns Base64-encoded JSON string for the HTTP header
+ *
+ * @example
+ * ```ts
+ * import { encodePaymentPayload, S402_HEADERS } from 's402/http';
+ *
+ * const header = encodePaymentPayload(payload);
+ * fetch(url, { headers: { [S402_HEADERS.PAYMENT]: header } });
+ * ```
+ */
 declare function encodePaymentPayload(payload: s402PaymentPayload): string;
 /** Encode settlement response for the `payment-response` header */
 declare function encodeSettleResponse(response: s402SettleResponse): string;
 /** Return a clean object with only known s402 requirement fields. */
 declare function pickRequirementsFields(obj: Record<string, unknown>): s402PaymentRequirements;
-/** Decode payment requirements from the `payment-required` header */
+/**
+ * Decode payment requirements from the `payment-required` header.
+ * Validates shape, strips unknown keys, enforces size limit (64KB).
+ *
+ * @param header - Base64-encoded JSON string from the HTTP header
+ * @returns Validated s402 payment requirements
+ * @throws {s402Error} `INVALID_PAYLOAD` on oversized header, invalid base64/JSON, or malformed shape
+ *
+ * @example
+ * ```ts
+ * import { decodePaymentRequired } from 's402/http';
+ *
+ * const header = response.headers.get('payment-required')!;
+ * const requirements = decodePaymentRequired(header);
+ * console.log(requirements.accepts); // ['exact', 'prepaid']
+ * console.log(requirements.amount);  // '1000000'
+ * ```
+ */
 declare function decodePaymentRequired(header: string): s402PaymentRequirements;
 /** Return a clean payload object with only known s402 payload fields. */
 declare function pickPayloadFields(obj: Record<string, unknown>): s402PaymentPayload;
-/** Decode payment payload from the `x-payment` header */
+/**
+ * Decode payment payload from the `x-payment` header.
+ * Validates shape, strips unknown keys, enforces size limit (64KB).
+ *
+ * @param header - Base64-encoded JSON string from the HTTP header
+ * @returns Validated s402 payment payload
+ * @throws {s402Error} `INVALID_PAYLOAD` on oversized header, invalid base64/JSON, or malformed shape
+ *
+ * @example
+ * ```ts
+ * import { decodePaymentPayload, S402_HEADERS } from 's402/http';
+ *
+ * const header = request.headers.get(S402_HEADERS.PAYMENT)!;
+ * const payload = decodePaymentPayload(header);
+ * console.log(payload.scheme); // 'exact'
+ * ```
+ */
 declare function decodePaymentPayload(header: string): s402PaymentPayload;
 /** Return a clean settle response with only known s402 fields. */
 declare function pickSettleResponseFields(obj: Record<string, unknown>): s402SettleResponse;
@@ -110,6 +176,22 @@ declare function detectProtocol(headers: Headers): 's402' | 'x402' | 'unknown';
  * Extract s402 payment requirements from a 402 Response.
  * Returns null if the header is missing, malformed, or not s402 format.
  * For x402 responses, decode the header manually and use normalizeRequirements().
+ *
+ * @param response - Fetch API Response object (status should be 402)
+ * @returns Parsed requirements, or null if not an s402 response
+ *
+ * @example
+ * ```ts
+ * import { extractRequirementsFromResponse } from 's402/http';
+ *
+ * const res = await fetch(url);
+ * if (res.status === 402) {
+ *   const requirements = extractRequirementsFromResponse(res);
+ *   if (requirements) {
+ *     // Build and send payment
+ *   }
+ * }
+ * ```
  */
 declare function extractRequirementsFromResponse(response: Response): s402PaymentRequirements | null;
 //#endregion

package/dist/http.mjs

@@ -13,11 +13,44 @@ function fromBase64(b64) {
 	const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
 	return new TextDecoder().decode(bytes);
 }
-/** Encode payment requirements for the `payment-required` header */
+/**
+* Encode payment requirements for the `payment-required` header.
+*
+* @param requirements - Typed s402 payment requirements
+* @returns Base64-encoded JSON string for the HTTP header
+*
+* @example
+* ```ts
+* import { encodePaymentRequired } from 's402/http';
+*
+* const header = encodePaymentRequired({
+*   s402Version: '1',
+*   accepts: ['exact'],
+*   network: 'sui:mainnet',
+*   asset: '0x2::sui::SUI',
+*   amount: '1000000',
+*   payTo: '0xYOUR_ADDRESS',
+* });
+* response.headers.set('payment-required', header);
+* ```
+*/
 function encodePaymentRequired(requirements) {
 	return toBase64(JSON.stringify(requirements));
 }
-/** Encode payment payload for the `x-payment` header */
+/**
+* Encode payment payload for the `x-payment` header.
+*
+* @param payload - Typed s402 payment payload (any scheme)
+* @returns Base64-encoded JSON string for the HTTP header
+*
+* @example
+* ```ts
+* import { encodePaymentPayload, S402_HEADERS } from 's402/http';
+*
+* const header = encodePaymentPayload(payload);
+* fetch(url, { headers: { [S402_HEADERS.PAYMENT]: header } });
+* ```
+*/
 function encodePaymentPayload(payload) {
 	return toBase64(JSON.stringify(payload));
 }
@@ -104,8 +137,26 @@ function pickRequirementsFields(obj) {
 	else result[key] = obj[key];
 	return result;
 }
-/** Decode payment requirements from the `payment-required` header */
+/**
+* Decode payment requirements from the `payment-required` header.
+* Validates shape, strips unknown keys, enforces size limit (64KB).
+*
+* @param header - Base64-encoded JSON string from the HTTP header
+* @returns Validated s402 payment requirements
+* @throws {s402Error} `INVALID_PAYLOAD` on oversized header, invalid base64/JSON, or malformed shape
+*
+* @example
+* ```ts
+* import { decodePaymentRequired } from 's402/http';
+*
+* const header = response.headers.get('payment-required')!;
+* const requirements = decodePaymentRequired(header);
+* console.log(requirements.accepts); // ['exact', 'prepaid']
+* console.log(requirements.amount);  // '1000000'
+* ```
+*/
 function decodePaymentRequired(header) {
+	if (typeof header !== "string") throw new s402Error("INVALID_PAYLOAD", `payment-required header must be a string, got ${typeof header}`);
 	if (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `payment-required header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
 	let parsed;
 	try {
@@ -160,8 +211,25 @@ function pickPayloadFields(obj) {
 	}
 	return result;
 }
-/** Decode payment payload from the `x-payment` header */
+/**
+* Decode payment payload from the `x-payment` header.
+* Validates shape, strips unknown keys, enforces size limit (64KB).
+*
+* @param header - Base64-encoded JSON string from the HTTP header
+* @returns Validated s402 payment payload
+* @throws {s402Error} `INVALID_PAYLOAD` on oversized header, invalid base64/JSON, or malformed shape
+*
+* @example
+* ```ts
+* import { decodePaymentPayload, S402_HEADERS } from 's402/http';
+*
+* const header = request.headers.get(S402_HEADERS.PAYMENT)!;
+* const payload = decodePaymentPayload(header);
+* console.log(payload.scheme); // 'exact'
+* ```
+*/
 function decodePaymentPayload(header) {
+	if (typeof header !== "string") throw new s402Error("INVALID_PAYLOAD", `x-payment header must be a string, got ${typeof header}`);
 	if (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `x-payment header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
 	let parsed;
 	try {
@@ -195,6 +263,7 @@ function pickSettleResponseFields(obj) {
 }
 /** Decode settlement response from the `payment-response` header */
 function decodeSettleResponse(header) {
+	if (typeof header !== "string") throw new s402Error("INVALID_PAYLOAD", `payment-response header must be a string, got ${typeof header}`);
 	if (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `payment-response header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
 	let parsed;
 	try {
@@ -374,6 +443,19 @@ function validateRequirementsShape(obj) {
 	if (record.facilitatorUrl !== void 0) {
 		if (typeof record.facilitatorUrl !== "string") throw new s402Error("INVALID_PAYLOAD", `facilitatorUrl must be a string, got ${typeof record.facilitatorUrl}`);
 		if (/[\x00-\x1f\x7f]/.test(record.facilitatorUrl)) throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl contains control characters (potential header injection)");
+		try {
+			const url = new URL(record.facilitatorUrl);
+			if (url.protocol !== "https:" && url.protocol !== "http:") throw new s402Error("INVALID_PAYLOAD", `facilitatorUrl must use https:// or http://, got "${url.protocol}"`);
+		} catch (e) {
+			if (e instanceof s402Error) throw e;
+			throw new s402Error("INVALID_PAYLOAD", "facilitatorUrl is not a valid URL");
+		}
+	}
+	if (record.settlementMode !== void 0) {
+		if (record.settlementMode !== "facilitator" && record.settlementMode !== "direct") throw new s402Error("INVALID_PAYLOAD", `settlementMode must be "facilitator" or "direct", got ${JSON.stringify(record.settlementMode)}`);
+	}
+	if (record.receiptRequired !== void 0) {
+		if (typeof record.receiptRequired !== "boolean") throw new s402Error("INVALID_PAYLOAD", `receiptRequired must be a boolean, got ${typeof record.receiptRequired}`);
 	}
 	validateSubObjects(record);
 }
@@ -392,11 +474,21 @@ function validatePayloadShape(obj) {
 	if (typeof inner.signature !== "string") throw new s402Error("INVALID_PAYLOAD", `payload.signature must be a string, got ${typeof inner.signature}`);
 	if (record.scheme === "unlock" && typeof inner.encryptionId !== "string") throw new s402Error("INVALID_PAYLOAD", `unlock payload requires encryptionId (string), got ${typeof inner.encryptionId}`);
 	if (record.scheme === "prepaid" && typeof inner.ratePerCall !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload requires ratePerCall (string), got ${typeof inner.ratePerCall}`);
+	if (record.scheme === "prepaid" && inner.maxCalls !== void 0 && typeof inner.maxCalls !== "string") throw new s402Error("INVALID_PAYLOAD", `prepaid payload maxCalls must be a string if provided, got ${typeof inner.maxCalls}`);
 }
 /** Validate that a decoded settle response has the required shape. */
 function validateSettleShape(obj) {
 	if (obj == null || typeof obj !== "object") throw new s402Error("INVALID_PAYLOAD", "Settle response is not an object");
-	if (typeof obj.success !== "boolean") throw new s402Error("INVALID_PAYLOAD", "Malformed settle response: missing or invalid \"success\" (boolean)");
+	const record = obj;
+	if (typeof record.success !== "boolean") throw new s402Error("INVALID_PAYLOAD", "Malformed settle response: missing or invalid \"success\" (boolean)");
+	if (record.txDigest !== void 0 && typeof record.txDigest !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: txDigest must be a string, got ${typeof record.txDigest}`);
+	if (record.receiptId !== void 0 && typeof record.receiptId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: receiptId must be a string, got ${typeof record.receiptId}`);
+	if (record.finalityMs !== void 0 && (typeof record.finalityMs !== "number" || !Number.isFinite(record.finalityMs))) throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: finalityMs must be a finite number, got ${typeof record.finalityMs}`);
+	if (record.streamId !== void 0 && typeof record.streamId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: streamId must be a string, got ${typeof record.streamId}`);
+	if (record.escrowId !== void 0 && typeof record.escrowId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: escrowId must be a string, got ${typeof record.escrowId}`);
+	if (record.balanceId !== void 0 && typeof record.balanceId !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: balanceId must be a string, got ${typeof record.balanceId}`);
+	if (record.error !== void 0 && typeof record.error !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: error must be a string, got ${typeof record.error}`);
+	if (record.errorCode !== void 0 && typeof record.errorCode !== "string") throw new s402Error("INVALID_PAYLOAD", `Malformed settle response: errorCode must be a string, got ${typeof record.errorCode}`);
 }
 /** Content type for s402 JSON body transport */
 const S402_CONTENT_TYPE = "application/s402+json";
@@ -406,6 +498,7 @@ function encodeRequirementsBody(requirements) {
 }
 /** Decode payment requirements from JSON string (from response body) */
 function decodeRequirementsBody(body) {
+	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 requirements body must be a string, got ${typeof body}`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -421,6 +514,7 @@ function encodePayloadBody(payload) {
 }
 /** Decode payment payload from JSON string (from request body) */
 function decodePayloadBody(body) {
+	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 payload body must be a string, got ${typeof body}`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -436,6 +530,7 @@ function encodeSettleBody(response) {
 }
 /** Decode settlement response from JSON string (from response body) */
 function decodeSettleBody(body) {
+	if (typeof body !== "string") throw new s402Error("INVALID_PAYLOAD", `s402 settle body must be a string, got ${typeof body}`);
 	let parsed;
 	try {
 		parsed = JSON.parse(body);
@@ -481,6 +576,22 @@ function detectProtocol(headers) {
 * Extract s402 payment requirements from a 402 Response.
 * Returns null if the header is missing, malformed, or not s402 format.
 * For x402 responses, decode the header manually and use normalizeRequirements().
+*
+* @param response - Fetch API Response object (status should be 402)
+* @returns Parsed requirements, or null if not an s402 response
+*
+* @example
+* ```ts
+* import { extractRequirementsFromResponse } from 's402/http';
+*
+* const res = await fetch(url);
+* if (res.status === 402) {
+*   const requirements = extractRequirementsFromResponse(res);
+*   if (requirements) {
+*     // Build and send payment
+*   }
+* }
+* ```
 */
 function extractRequirementsFromResponse(response) {
 	const header = response.headers.get(S402_HEADERS.PAYMENT_REQUIRED);

package/dist/index.d.mts

@@ -102,8 +102,19 @@ declare class s402Client {
   /**
    * Register a scheme implementation for a network.
    *
-   * @param network - Sui network (e.g., "sui:testnet")
-   * @param scheme - Scheme implementation
+   * @param network - Network identifier (e.g., "sui:testnet", "sui:mainnet")
+   * @param scheme - Scheme implementation (from @sweefi/sui or your own)
+   * @returns `this` for chaining
+   *
+   * @example
+   * ```ts
+   * import { s402Client } from 's402';
+   *
+   * const client = new s402Client();
+   * client
+   *   .register('sui:mainnet', exactScheme)
+   *   .register('sui:mainnet', prepaidScheme);
+   * ```
    */
   register(network: string, scheme: s402ClientScheme): this;
   /**
@@ -114,6 +125,23 @@ declare class s402Client {
    *
    * Accepts typed s402PaymentRequirements only. For x402 input, normalize
    * first via `normalizeRequirements()` from 's402/compat'.
+   *
+   * @param requirements - Server's payment requirements (from a 402 response)
+   * @returns Payment payload ready to send in the `x-payment` header
+   * @throws {s402Error} `NETWORK_MISMATCH` if no schemes registered for the network
+   * @throws {s402Error} `SCHEME_NOT_SUPPORTED` if no registered scheme matches server's accepts
+   *
+   * @example
+   * ```ts
+   * import { s402Client, decodePaymentRequired, encodePaymentPayload, S402_HEADERS } from 's402';
+   *
+   * const client = new s402Client();
+   * client.register('sui:mainnet', exactScheme);
+   *
+   * const requirements = decodePaymentRequired(res.headers.get('payment-required')!);
+   * const payload = await client.createPayment(requirements);
+   * fetch(url, { headers: { [S402_HEADERS.PAYMENT]: encodePaymentPayload(payload) } });
+   * ```
    */
   createPayment(requirements: s402PaymentRequirements): Promise<s402PaymentPayload>;
   /**
@@ -141,12 +169,33 @@ declare class s402Facilitator {
    */
   settle(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
   /**
-   * Expiration-guarded verify + settle in one call.
+   * Expiration-guarded verify + settle in one call. **This is the recommended path.**
    * Rejects expired requirements, verifies the payload, then settles.
+   * Includes deduplication (prevents concurrent identical requests) and timeouts
+   * (5s verify, 15s settle).
    *
    * Note: True atomicity comes from Sui's PTBs in the scheme implementation,
    * not from this method. This method provides the expiration guard and
-   * sequential verify→settle orchestration.
+   * sequential verify-then-settle orchestration.
+   *
+   * @param payload - Client's payment payload
+   * @param requirements - Server's payment requirements
+   * @returns Settlement result (check `result.success` and `result.errorCode`)
+   *
+   * @example
+   * ```ts
+   * import { s402Facilitator } from 's402';
+   *
+   * const facilitator = new s402Facilitator();
+   * facilitator.register('sui:mainnet', exactFacilitatorScheme);
+   *
+   * const result = await facilitator.process(payload, requirements);
+   * if (result.success) {
+   *   console.log(result.txDigest); // Sui transaction digest
+   * } else {
+   *   console.log(result.errorCode); // e.g. 'VERIFICATION_FAILED'
+   * }
+   * ```
    */
   process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
   /**
@@ -176,6 +225,25 @@ declare class s402ResourceServer {
    * Build payment requirements for a route.
    * Uses the first scheme in the config's schemes array.
    * Always includes "exact" in accepts for x402 compat.
+   *
+   * @param config - Per-route payment configuration (schemes, price, network, payTo, asset)
+   * @returns Payment requirements ready to encode for the 402 response
+   * @throws {s402Error} `INVALID_PAYLOAD` if price is not a valid non-negative integer string
+   *
+   * @example
+   * ```ts
+   * import { s402ResourceServer, encodePaymentRequired } from 's402';
+   *
+   * const server = new s402ResourceServer();
+   * const requirements = server.buildRequirements({
+   *   schemes: ['exact'],
+   *   price: '1000000',
+   *   network: 'sui:mainnet',
+   *   payTo: '0xYOUR_ADDRESS',
+   *   asset: '0x2::sui::SUI',
+   * });
+   * res.status(402).setHeader('payment-required', encodePaymentRequired(requirements));
+   * ```
    */
   buildRequirements(config: s402RouteConfig): s402PaymentRequirements;
   /**
@@ -191,6 +259,20 @@ declare class s402ResourceServer {
    * Expiration-guarded verify + settle. This is the recommended path.
    * Rejects expired requirements, verifies the payload, then settles.
    * True atomicity comes from Sui PTBs in the scheme implementation.
+   *
+   * @param payload - Client's payment payload (from the `x-payment` header)
+   * @param requirements - The requirements this server originally sent
+   * @returns Settlement result with txDigest on success
+   * @throws {s402Error} `FACILITATOR_UNAVAILABLE` if no facilitator is configured
+   *
+   * @example
+   * ```ts
+   * const result = await server.process(payload, requirements);
+   * if (result.success) {
+   *   // Serve the protected resource
+   *   res.status(200).json({ data: 'paid content' });
+   * }
+   * ```
    */
   process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
 }

package/dist/index.mjs

@@ -9,8 +9,19 @@ var s402Client = class {
 	/**
 	* Register a scheme implementation for a network.
 	*
-	* @param network - Sui network (e.g., "sui:testnet")
-	* @param scheme - Scheme implementation
+	* @param network - Network identifier (e.g., "sui:testnet", "sui:mainnet")
+	* @param scheme - Scheme implementation (from @sweefi/sui or your own)
+	* @returns `this` for chaining
+	*
+	* @example
+	* ```ts
+	* import { s402Client } from 's402';
+	*
+	* const client = new s402Client();
+	* client
+	*   .register('sui:mainnet', exactScheme)
+	*   .register('sui:mainnet', prepaidScheme);
+	* ```
 	*/
 	register(network, scheme) {
 		if (!this.schemes.has(network)) this.schemes.set(network, /* @__PURE__ */ new Map());
@@ -25,6 +36,23 @@ var s402Client = class {
 	*
 	* Accepts typed s402PaymentRequirements only. For x402 input, normalize
 	* first via `normalizeRequirements()` from 's402/compat'.
+	*
+	* @param requirements - Server's payment requirements (from a 402 response)
+	* @returns Payment payload ready to send in the `x-payment` header
+	* @throws {s402Error} `NETWORK_MISMATCH` if no schemes registered for the network
+	* @throws {s402Error} `SCHEME_NOT_SUPPORTED` if no registered scheme matches server's accepts
+	*
+	* @example
+	* ```ts
+	* import { s402Client, decodePaymentRequired, encodePaymentPayload, S402_HEADERS } from 's402';
+	*
+	* const client = new s402Client();
+	* client.register('sui:mainnet', exactScheme);
+	*
+	* const requirements = decodePaymentRequired(res.headers.get('payment-required')!);
+	* const payload = await client.createPayment(requirements);
+	* fetch(url, { headers: { [S402_HEADERS.PAYMENT]: encodePaymentPayload(payload) } });
+	* ```
 	*/
 	async createPayment(requirements) {
 		const networkSchemes = this.schemes.get(requirements.network);
@@ -67,6 +95,25 @@ var s402ResourceServer = class {
 	* Build payment requirements for a route.
 	* Uses the first scheme in the config's schemes array.
 	* Always includes "exact" in accepts for x402 compat.
+	*
+	* @param config - Per-route payment configuration (schemes, price, network, payTo, asset)
+	* @returns Payment requirements ready to encode for the 402 response
+	* @throws {s402Error} `INVALID_PAYLOAD` if price is not a valid non-negative integer string
+	*
+	* @example
+	* ```ts
+	* import { s402ResourceServer, encodePaymentRequired } from 's402';
+	*
+	* const server = new s402ResourceServer();
+	* const requirements = server.buildRequirements({
+	*   schemes: ['exact'],
+	*   price: '1000000',
+	*   network: 'sui:mainnet',
+	*   payTo: '0xYOUR_ADDRESS',
+	*   asset: '0x2::sui::SUI',
+	* });
+	* res.status(402).setHeader('payment-required', encodePaymentRequired(requirements));
+	* ```
 	*/
 	buildRequirements(config) {
 		if (!isValidAmount(config.price)) throw new s402Error("INVALID_PAYLOAD", `Invalid price "${config.price}": must be a non-negative integer string`);
@@ -118,6 +165,20 @@ var s402ResourceServer = class {
 	* Expiration-guarded verify + settle. This is the recommended path.
 	* Rejects expired requirements, verifies the payload, then settles.
 	* True atomicity comes from Sui PTBs in the scheme implementation.
+	*
+	* @param payload - Client's payment payload (from the `x-payment` header)
+	* @param requirements - The requirements this server originally sent
+	* @returns Settlement result with txDigest on success
+	* @throws {s402Error} `FACILITATOR_UNAVAILABLE` if no facilitator is configured
+	*
+	* @example
+	* ```ts
+	* const result = await server.process(payload, requirements);
+	* if (result.success) {
+	*   // Serve the protected resource
+	*   res.status(200).json({ data: 'paid content' });
+	* }
+	* ```
 	*/
 	async process(payload, requirements) {
 		if (!this.facilitator) throw new s402Error("FACILITATOR_UNAVAILABLE", "No facilitator configured on this server");
@@ -212,12 +273,33 @@ var s402Facilitator = class {
 		}
 	}
 	/**
-	* Expiration-guarded verify + settle in one call.
+	* Expiration-guarded verify + settle in one call. **This is the recommended path.**
 	* Rejects expired requirements, verifies the payload, then settles.
+	* Includes deduplication (prevents concurrent identical requests) and timeouts
+	* (5s verify, 15s settle).
 	*
 	* Note: True atomicity comes from Sui's PTBs in the scheme implementation,
 	* not from this method. This method provides the expiration guard and
-	* sequential verify→settle orchestration.
+	* sequential verify-then-settle orchestration.
+	*
+	* @param payload - Client's payment payload
+	* @param requirements - Server's payment requirements
+	* @returns Settlement result (check `result.success` and `result.errorCode`)
+	*
+	* @example
+	* ```ts
+	* import { s402Facilitator } from 's402';
+	*
+	* const facilitator = new s402Facilitator();
+	* facilitator.register('sui:mainnet', exactFacilitatorScheme);
+	*
+	* const result = await facilitator.process(payload, requirements);
+	* if (result.success) {
+	*   console.log(result.txDigest); // Sui transaction digest
+	* } else {
+	*   console.log(result.errorCode); // e.g. 'VERIFICATION_FAILED'
+	* }
+	* ```
 	*/
 	async process(payload, requirements) {
 		if (requirements.expiresAt != null) {
@@ -264,7 +346,10 @@ var s402Facilitator = class {
 		try {
 			let verifyResult;
 			try {
-				verifyResult = await Promise.race([scheme.verify(payload, requirements), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("Verification timed out after 5s")), 5e3))]);
+				let verifyTimer;
+				verifyResult = await Promise.race([scheme.verify(payload, requirements), new Promise((_, reject) => {
+					verifyTimer = setTimeout(() => reject(/* @__PURE__ */ new Error("Verification timed out after 5s")), 5e3);
+				})]).finally(() => clearTimeout(verifyTimer));
 			} catch (e) {
 				return {
 					success: false,
@@ -283,7 +368,10 @@ var s402Facilitator = class {
 				errorCode: "REQUIREMENTS_EXPIRED"
 			};
 			try {
-				return await Promise.race([scheme.settle(payload, requirements), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("Settlement timed out after 15s")), 15e3))]);
+				let settleTimer;
+				return await Promise.race([scheme.settle(payload, requirements), new Promise((_, reject) => {
+					settleTimer = setTimeout(() => reject(/* @__PURE__ */ new Error("Settlement timed out after 15s")), 15e3);
+				})]).finally(() => clearTimeout(settleTimer));
 			} catch (e) {
 				return {
 					success: false,

package/dist/receipts.mjs

@@ -1,4 +1,23 @@
+import { s402Error } from "./errors.mjs";
+
 //#region src/receipts.ts
+/**
+* s402 Receipt HTTP Helpers — chain-agnostic receipt header format/parse.
+*
+* Providers sign each API response with Ed25519. The signature, call number,
+* timestamp, and response hash are transported as a single HTTP header:
+*
+*   X-S402-Receipt: v2:base64(signature):callNumber:timestampMs:base64(responseHash)
+*
+* This module handles the header wire format ONLY. It does not:
+* - Construct BCS messages (chain-specific — see @sweefi/sui receipts.ts)
+* - Generate Ed25519 keys (implementations provide their own)
+* - Accumulate receipts (client-side concern — see @sweefi/sui ReceiptAccumulator)
+*
+* Zero runtime dependencies. Uses built-in btoa/atob.
+*
+* @see docs/schemes/prepaid.md — v0.2 spec
+*/
 /** HTTP header name for s402 signed usage receipts. */
 const S402_RECEIPT_HEADER = "X-S402-Receipt";
 const HEADER_VERSION = "v2";
@@ -8,9 +27,14 @@ function uint8ToBase64(bytes) {
 	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
 	return btoa(binary);
 }
-/** Decode a base64 string to Uint8Array using built-in atob. */
+/** Decode a base64 string to Uint8Array using built-in atob. Throws Error on invalid base64. */
 function base64ToUint8(b64) {
-	const binary = atob(b64);
+	let binary;
+	try {
+		binary = atob(b64);
+	} catch {
+		throw new s402Error("INVALID_PAYLOAD", `Invalid base64: "${b64.slice(0, 20)}${b64.length > 20 ? "..." : ""}"`);
+	}
 	const bytes = new Uint8Array(binary.length);
 	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
 	return bytes;
@@ -40,21 +64,35 @@ function formatReceiptHeader(receipt) {
 * @throws On empty string, wrong number of parts, or unknown version
 */
 function parseReceiptHeader(header) {
-	if (!header) throw new Error("Empty receipt header");
+	if (!header) throw new s402Error("INVALID_PAYLOAD", "Empty receipt header");
 	const parts = header.split(":");
-	if (parts.length !== 5) throw new Error(`Malformed receipt header: expected 5 colon-separated parts, got ${parts.length}`);
+	if (parts.length !== 5) throw new s402Error("INVALID_PAYLOAD", `Malformed receipt header: expected 5 colon-separated parts, got ${parts.length}`);
 	const [version, sigB64, callNumberStr, timestampMsStr, hashB64] = parts;
-	if (version !== HEADER_VERSION) throw new Error(`Unknown receipt header version: "${version}" (expected "${HEADER_VERSION}")`);
-	const callNumber = BigInt(callNumberStr);
-	const timestampMs = BigInt(timestampMsStr);
-	if (callNumber <= 0n) throw new Error(`Invalid receipt callNumber: must be positive, got ${callNumber}`);
-	if (timestampMs <= 0n) throw new Error(`Invalid receipt timestampMs: must be positive, got ${timestampMs}`);
+	if (version !== HEADER_VERSION) throw new s402Error("INVALID_PAYLOAD", `Unknown receipt header version: "${version}" (expected "${HEADER_VERSION}")`);
+	let callNumber;
+	let timestampMs;
+	try {
+		callNumber = BigInt(callNumberStr);
+	} catch {
+		throw new s402Error("INVALID_PAYLOAD", `Invalid receipt callNumber: not a valid integer "${callNumberStr}"`);
+	}
+	try {
+		timestampMs = BigInt(timestampMsStr);
+	} catch {
+		throw new s402Error("INVALID_PAYLOAD", `Invalid receipt timestampMs: not a valid integer "${timestampMsStr}"`);
+	}
+	if (callNumber <= 0n) throw new s402Error("INVALID_PAYLOAD", `Invalid receipt callNumber: must be positive, got ${callNumber}`);
+	if (timestampMs <= 0n) throw new s402Error("INVALID_PAYLOAD", `Invalid receipt timestampMs: must be positive, got ${timestampMs}`);
+	const signature = base64ToUint8(sigB64);
+	if (signature.length !== 64) throw new s402Error("INVALID_PAYLOAD", `Receipt signature must be 64 bytes (Ed25519), got ${signature.length}`);
+	const responseHash = base64ToUint8(hashB64);
+	if (responseHash.length !== 32) throw new s402Error("INVALID_PAYLOAD", `Receipt responseHash must be 32 bytes (SHA-256), got ${responseHash.length}`);
 	return {
 		version: "v2",
-		signature: base64ToUint8(sigB64),
+		signature,
 		callNumber,
 		timestampMs,
-		responseHash: base64ToUint8(hashB64)
+		responseHash
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s402",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "s402 — Chain-agnostic HTTP 402 wire format. Types, HTTP encoding, and scheme registry for five payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
   "license": "Apache-2.0",
@@ -25,7 +25,11 @@
     "streaming",
     "escrow",
     "web3",
-    "protocol"
+    "protocol",
+    "ai-agent",
+    "machine-to-machine",
+    "m2m",
+    "agent-payments"
   ],
   "engines": {
     "node": ">=18"
@@ -86,22 +90,21 @@
       "default": "./dist/receipts.mjs"
     }
   },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "fast-check": "^4.5.3",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.7.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^3.0.5"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build && npm run typecheck && npm run test",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
-  },
-  "devDependencies": {
-    "@vitest/coverage-v8": "^3.2.4",
-    "fast-check": "^4.5.3",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.7.0",
-    "vitepress": "^1.6.4",
-    "vitest": "^3.0.5"
   }
-}
+}

package/test/conformance/README.md

@@ -1,172 +0,0 @@
-# s402 Conformance Test Vectors
-
-Machine-readable test vectors that define s402-compliant behavior. Use these to verify any s402 implementation — TypeScript, Go, Python, Rust, etc.
-
-## Getting the Vectors
-
-The vectors ship with the `s402` npm package:
-
-```bash
-npm pack s402
-tar xzf s402-*.tgz
-ls package/test/conformance/vectors/
-```
-
-Or clone the repo directly:
-
-```bash
-git clone https://github.com/s402-protocol/core.git
-ls core/test/conformance/vectors/
-```
-
-## Vector Format
-
-Each JSON file contains an array of test cases:
-
-```json
-[
-  {
-    "description": "Human-readable test name",
-    "input": { ... },
-    "expected": { ... },
-    "shouldReject": false
-  }
-]
-```
-
-### Accept vectors (`shouldReject: false`)
-
-The implementation MUST produce `expected` when given `input`.
-
-### Reject vectors (`shouldReject: true`)
-
-The implementation MUST reject the input with an error. The `expectedErrorCode` field indicates which error:
-
-```json
-{
-  "description": "Rejects negative amount",
-  "input": { "header": "base64-encoded-malformed-json" },
-  "shouldReject": true,
-  "expectedErrorCode": "INVALID_PAYLOAD"
-}
-```
-
-## Vector Files
-
-| File | Tests | Description |
-|------|-------|-------------|
-| `requirements-encode.json` | Encode | `s402PaymentRequirements` object → base64 header string |
-| `requirements-decode.json` | Decode | base64 header string → `s402PaymentRequirements` object |
-| `payload-encode.json` | Encode | `s402PaymentPayload` object → base64 header string |
-| `payload-decode.json` | Decode | base64 header string → `s402PaymentPayload` object |
-| `settle-encode.json` | Encode | `s402SettleResponse` object → base64 header string |
-| `settle-decode.json` | Decode | base64 header string → `s402SettleResponse` object |
-| `body-transport.json` | Both | Requirements/payload/settle via JSON body (no base64) |
-| `compat-normalize.json` | Normalize | x402 V1/V2 input → normalized s402 output |
-| `receipt-format.json` | Format | Receipt fields → `X-S402-Receipt` header string |
-| `receipt-parse.json` | Parse | `X-S402-Receipt` header string → parsed receipt fields |
-| `validation-reject.json` | Reject | Malformed inputs that MUST be rejected |
-| `roundtrip.json` | Roundtrip | encode → decode → re-encode = identical output |
-
-## Encoding Scheme
-
-s402 uses **Unicode-safe base64** for HTTP header transport:
-
-1. JSON-serialize the object: `JSON.stringify(obj)`
-2. UTF-8 encode the string: `TextEncoder.encode(json)`
-3. Base64 encode the bytes: `btoa(bytes.map(b => String.fromCharCode(b)).join(''))`
-
-For ASCII-only content (the common case), this produces the same output as plain `btoa(json)`.
-
-Body transport uses raw JSON (no base64).
-
-## Receipt Header Format
-
-The `X-S402-Receipt` header uses colon-separated fields:
-
-```
-v2:base64(signature):callNumber:timestampMs:base64(responseHash)
-```
-
-- `v2` — version prefix (always "v2" for signed receipts)
-- `signature` — 64-byte Ed25519 signature, base64-encoded
-- `callNumber` — sequential call number (1-indexed, bigint string)
-- `timestampMs` — Unix timestamp in milliseconds (bigint string)
-- `responseHash` — response body hash (typically SHA-256, 32 bytes), base64-encoded
-
-In the vector JSON files, `signature` and `responseHash` are represented as arrays of byte values (0-255) since JSON has no binary type.
-
-## Implementing in Another Language
-
-1. Load the JSON vector files
-2. For each vector where `shouldReject` is `false`:
-   - Feed `input` to your encode/decode function
-   - Compare the result to `expected`
-3. For each vector where `shouldReject` is `true`:
-   - Feed `input` to your decode function
-   - Verify it throws/returns an error with the matching error code
-4. For roundtrip vectors:
-   - Verify `expected.identical` is `true`
-   - Verify `expected.firstEncode === expected.reEncode`
-
-### Key stripping on decode
-
-All three decode functions (`decodePaymentRequired`, `decodePaymentPayload`, `decodeSettleResponse`) MUST strip unknown top-level keys. Only known fields should survive the decode. This is a defense-in-depth measure at the HTTP trust boundary.
-
-**Requirements known top-level keys:** `s402Version`, `accepts`, `network`, `asset`, `amount`, `payTo`, `facilitatorUrl`, `mandate`, `protocolFeeBps`, `protocolFeeAddress`, `receiptRequired`, `settlementMode`, `expiresAt`, `stream`, `escrow`, `unlock`, `prepaid`, `extensions`.
-
-**Requirements sub-object known keys** (also stripped of unknowns):
-- `mandate`: `required`, `minPerTx`, `coinType`
-- `stream`: `ratePerSecond`, `budgetCap`, `minDeposit`, `streamSetupUrl`
-- `escrow`: `seller`, `arbiter`, `deadlineMs`
-- `unlock`: `encryptionId`, `walrusBlobId`, `encryptionPackageId`
-- `prepaid`: `ratePerCall`, `maxCalls`, `minDeposit`, `withdrawalDelayMs`, `providerPubkey`, `disputeWindowMs`
-
-**Payload known top-level keys:** `s402Version`, `scheme`, `payload`.
-
-**Payload inner keys** (per scheme):
-- `exact`, `stream`, `escrow`: `transaction`, `signature`
-- `unlock`: `transaction`, `signature`, `encryptionId`
-- `prepaid`: `transaction`, `signature`, `ratePerCall`, `maxCalls`
-
-**Settle response known keys:** `success`, `txDigest`, `receiptId`, `finalityMs`, `streamId`, `escrowId`, `balanceId`, `error`, `errorCode`.
-
-### JSON key ordering
-
-s402 vectors use JavaScript's `JSON.stringify()` key ordering (insertion order). Cross-language implementations MUST serialize keys in the same order as the vector files to produce identical base64 output. If your language's JSON serializer uses alphabetical ordering by default, you'll need ordered serialization (e.g., Go's `json.Marshal` on a struct with ordered fields, Python's `json.dumps` with `sort_keys=False`).
-
-Note: **decode also reorders keys**. The decode functions iterate their allowlist in the order listed above, not the input order. If the input JSON has keys in a different order, the decoded output follows the allowlist order. This affects roundtrip tests — the re-encoded output uses the allowlist order, which may differ from the original input order.
-
-### Header size limits
-
-Implementations SHOULD enforce a maximum header size of **64 KiB** (`MAX_HEADER_BYTES = 65536`). Headers exceeding this limit indicate abuse or misconfiguration and SHOULD be rejected before base64 decoding.
-
-### Rejection vector dispatch
-
-Rejection vectors are dispatched in this precedence order:
-
-1. If `expectedErrorCode` is `"RECEIPT_PARSE_ERROR"` → test `parseReceiptHeader`. Note: receipts throw a plain `Error`, not an `s402Error`, since receipts are a separate subsystem.
-2. If `input.decodeAs` is `"payload"` → test `decodePaymentPayload`
-3. If `input.decodeAs` is `"compat"` → test `normalizeRequirements` with the raw JSON (not base64)
-4. Otherwise → test `decodePaymentRequired` (the default)
-
-### Error codes
-
-Rejection vectors use `expectedErrorCode` values from the s402 error code enum:
-
-- `INVALID_PAYLOAD` — malformed or invalid input
-- `RECEIPT_PARSE_ERROR` — malformed receipt header (vector convention for receipt-specific parsing errors)
-
-## Regenerating Vectors
-
-If you modify the s402 encoding logic, regenerate vectors:
-
-```bash
-npx tsx test/conformance/generate-vectors.ts
-```
-
-Then run the conformance tests to verify:
-
-```bash
-pnpm run test
-```