s402 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-03-02
+
+### Added
+
+- **Conformance test vectors ship in npm package** — 133 machine-readable JSON test vectors across 12 files now included via `test/conformance/vectors`. Cross-language implementors (Go, Python, Rust) can `npm pack s402` to get the vectors without cloning the repo.
+- **API stability declaration** — `API-STABILITY.md` classifies all 83 exports as stable, experimental, or internal.
+
+### Fixed
+
+- Barrel export JSDoc updated to chain-agnostic wording (was "Sui-native").
+
 ## [0.2.0] - 2026-03-01
 
 ### Added
@@ -27,7 +38,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **BREAKING**: `s402RouteConfig.asset` is now required (was optional).
 - JSDoc on `s402PaymentRequirements` updated to chain-agnostic wording (network, asset, amount fields).
-- 258 tests across 11 suites (was 207 at v0.1.0).
+- **Conformance test suite** — 133 machine-readable JSON test vectors across 12 files for cross-language implementation verification. Covers encode/decode, body transport, compat normalization, receipt format/parse, validation rejection, key-stripping, and roundtrip identity. Vectors ship in the npm package.
+- **API stability declaration** — `API-STABILITY.md` classifies all 83 exports as stable/experimental/internal.
+- 405 tests across 12 suites (was 207 at v0.1.0).
 
 ## [0.1.8] - 2026-02-27
 
@@ -116,6 +129,7 @@ _Version bump for npm publish after license change._
 - Property-based fuzz testing via fast-check
 - 207 tests, zero runtime dependencies
 
+[0.2.1]: https://github.com/s402-protocol/core/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/s402-protocol/core/compare/v0.1.8...v0.2.0
 [0.1.8]: https://github.com/s402-protocol/core/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/s402-protocol/core/compare/v0.1.6...v0.1.7

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
 
 ```
@@ -325,6 +337,20 @@ const requirements: s402PaymentRequirements = {
 
 5. **Errors tell you what to do.** Every error code includes `retryable` (can the client try again?) and `suggestedAction` (what should it do?). Agents can self-recover.
 
+## Conformance Testing
+
+s402 ships 133 machine-readable JSON test vectors for cross-language conformance. If you're implementing s402 in Go, Python, Rust, or any other language, use these vectors to verify your implementation matches the spec.
+
+```bash
+# Vectors are in the npm package
+ls node_modules/s402/test/conformance/vectors/
+
+# Or clone the repo
+ls test/conformance/vectors/
+```
+
+See [`test/conformance/README.md`](./test/conformance/README.md) for the vector format, encoding scheme, and implementation guide.
+
 ## Related
 
 - **[SweeFi](https://github.com/sweeinc/sweefi)** — Open-source payment SDK built on s402. 10 packages including PTB builders, MCP tools, CLI, and UI components.

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,7 +137,24 @@ 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 (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `payment-required header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
 	let parsed;
@@ -160,7 +210,23 @@ 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 (header.length > MAX_HEADER_BYTES) throw new s402Error("INVALID_PAYLOAD", `x-payment header exceeds maximum size (${header.length} > ${MAX_HEADER_BYTES})`);
 	let parsed;
@@ -374,6 +440,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 +471,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";
@@ -481,6 +570,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>;
 }