s402 0.2.1 → 0.2.2

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,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>;
 }

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.2",
   "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"