s402 0.1.7 → 0.1.8

package/README.md

@@ -5,6 +5,8 @@
 
 **Sui-native HTTP 402 protocol.** Atomic settlement via Sui's Programmable Transaction Blocks (PTBs). Includes an optional compat layer (`s402/compat`) for normalizing x402 input.
 
+s402 is the Sui-native implementation of HTTP 402 (Payment Required) — an open protocol that lets AI agents pay for API calls in a single HTTP request with no per-call on-chain transaction. Unlike Coinbase's x402 on Ethereum, s402 uses Sui's Programmable Transaction Blocks to reduce 1,000 payments to just 2 on-chain transactions via the Prepaid scheme, cutting per-call effective gas from $0.007 to $0.000014 and making micropayments economically viable for AI agents for the first time.
+
 ```bash
 npm install s402
 pnpm add s402

package/dist/http.d.mts

@@ -74,6 +74,31 @@ declare function validatePrepaidShape(value: unknown): void;
 declare function validateSubObjects(record: Record<string, unknown>): void;
 /** Validate that decoded payment requirements have the required shape. */
 declare function validateRequirementsShape(obj: unknown): void;
+/** Content type for s402 JSON body transport */
+declare const S402_CONTENT_TYPE: "application/s402+json";
+/** Encode payment requirements as JSON string (for response body) */
+declare function encodeRequirementsBody(requirements: s402PaymentRequirements): string;
+/** Decode payment requirements from JSON string (from response body) */
+declare function decodeRequirementsBody(body: string): s402PaymentRequirements;
+/** Encode payment payload as JSON string (for request body) */
+declare function encodePayloadBody(payload: s402PaymentPayload): string;
+/** Decode payment payload from JSON string (from request body) */
+declare function decodePayloadBody(body: string): s402PaymentPayload;
+/** Encode settlement response as JSON string (for response body) */
+declare function encodeSettleBody(response: s402SettleResponse): string;
+/** Decode settlement response from JSON string (from response body) */
+declare function decodeSettleBody(body: string): s402SettleResponse;
+/**
+ * Detect transport mode from an incoming request.
+ *
+ * Checks Content-Type for body transport, then falls back to header detection.
+ * Returns 'body' if Content-Type is application/s402+json.
+ * Returns 'header' if x-payment header is present.
+ * Returns 'unknown' otherwise.
+ */
+declare function detectTransport(request: {
+  headers: Headers;
+}): 'header' | 'body' | 'unknown';
 /**
  * Detect whether a 402 response uses s402 or x402 protocol.
  *
@@ -88,4 +113,4 @@ declare function detectProtocol(headers: Headers): 's402' | 'x402' | 'unknown';
  */
 declare function extractRequirementsFromResponse(response: Response): s402PaymentRequirements | null;
 //#endregion
-export { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };
+export { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };

package/dist/http.mjs

@@ -83,7 +83,9 @@ const S402_SUB_OBJECT_KEYS = {
 		"ratePerCall",
 		"maxCalls",
 		"minDeposit",
-		"withdrawalDelayMs"
+		"withdrawalDelayMs",
+		"providerPubkey",
+		"disputeWindowMs"
 	])
 };
 /** Strip unknown keys from a sub-object, returning a clean copy. */
@@ -318,6 +320,8 @@ function validatePrepaidShape(value) {
 	assertString(obj, "withdrawalDelayMs", "prepaid");
 	if (typeof obj.withdrawalDelayMs === "string" && !isValidAmount(obj.withdrawalDelayMs)) throw new s402Error("INVALID_PAYLOAD", `prepaid.withdrawalDelayMs must be a non-negative integer string (milliseconds), got "${obj.withdrawalDelayMs}"`);
 	assertOptionalString(obj, "maxCalls", "prepaid");
+	assertOptionalString(obj, "providerPubkey", "prepaid");
+	assertOptionalString(obj, "disputeWindowMs", "prepaid");
 }
 /**
 * Validate all optional sub-objects on a requirements record.
@@ -386,6 +390,66 @@ 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)");
 }
+/** Content type for s402 JSON body transport */
+const S402_CONTENT_TYPE = "application/s402+json";
+/** Encode payment requirements as JSON string (for response body) */
+function encodeRequirementsBody(requirements) {
+	return JSON.stringify(requirements);
+}
+/** Decode payment requirements from JSON string (from response body) */
+function decodeRequirementsBody(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (e) {
+		throw new s402Error("INVALID_PAYLOAD", `Failed to parse s402 requirements body: ${e instanceof Error ? e.message : "invalid JSON"}`);
+	}
+	validateRequirementsShape(parsed);
+	return pickRequirementsFields(parsed);
+}
+/** Encode payment payload as JSON string (for request body) */
+function encodePayloadBody(payload) {
+	return JSON.stringify(payload);
+}
+/** Decode payment payload from JSON string (from request body) */
+function decodePayloadBody(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (e) {
+		throw new s402Error("INVALID_PAYLOAD", `Failed to parse s402 payload body: ${e instanceof Error ? e.message : "invalid JSON"}`);
+	}
+	validatePayloadShape(parsed);
+	return pickPayloadFields(parsed);
+}
+/** Encode settlement response as JSON string (for response body) */
+function encodeSettleBody(response) {
+	return JSON.stringify(response);
+}
+/** Decode settlement response from JSON string (from response body) */
+function decodeSettleBody(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body);
+	} catch (e) {
+		throw new s402Error("INVALID_PAYLOAD", `Failed to parse s402 settle body: ${e instanceof Error ? e.message : "invalid JSON"}`);
+	}
+	validateSettleShape(parsed);
+	return pickSettleResponseFields(parsed);
+}
+/**
+* Detect transport mode from an incoming request.
+*
+* Checks Content-Type for body transport, then falls back to header detection.
+* Returns 'body' if Content-Type is application/s402+json.
+* Returns 'header' if x-payment header is present.
+* Returns 'unknown' otherwise.
+*/
+function detectTransport(request) {
+	if (request.headers.get("content-type")?.includes(S402_CONTENT_TYPE)) return "body";
+	if (request.headers.get(S402_HEADERS.PAYMENT)) return "header";
+	return "unknown";
+}
 /**
 * Detect whether a 402 response uses s402 or x402 protocol.
 *
@@ -421,4 +485,4 @@ function extractRequirementsFromResponse(response) {
 }
 
 //#endregion
-export { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };
+export { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, pickPayloadFields, pickRequirementsFields, pickSettleResponseFields, validateEscrowShape, validateMandateShape, validatePrepaidShape, validateRequirementsShape, validateStreamShape, validateSubObjects, validateUnlockShape };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { createS402Error, s402Error, s402ErrorCode, s402ErrorCodeType, s402ErrorInfo } from "./errors.mjs";
 import { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PaymentSession, s402PrepaidExtra, s402PrepaidPayload, s402RegistryQuery, s402Scheme, s402ServiceEntry, s402SettleResponse, s402SettlementMode, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402VerifyResponse } from "./types.mjs";
-import { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
+import { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
 
 //#region src/scheme.d.ts
 /** Implemented by each scheme on the client side */
@@ -192,4 +192,4 @@ declare class s402ResourceServer {
   process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
 }
 //#endregion
-export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, type s402ClientScheme, type s402DirectScheme, type s402Discovery, s402Error, s402ErrorCode, type s402ErrorCodeType, type s402ErrorInfo, type s402EscrowExtra, type s402EscrowPayload, type s402ExactPayload, s402Facilitator, type s402FacilitatorScheme, type s402Mandate, type s402MandateRequirements, type s402PaymentPayload, type s402PaymentPayloadBase, type s402PaymentRequirements, type s402PaymentSession, type s402PrepaidExtra, type s402PrepaidPayload, type s402RegistryQuery, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerScheme, type s402ServiceEntry, type s402SettleResponse, type s402SettlementMode, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402VerifyResponse, validateRequirementsShape };
+export { S402_CONTENT_TYPE, S402_HEADERS, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, type s402ClientScheme, type s402DirectScheme, type s402Discovery, s402Error, s402ErrorCode, type s402ErrorCodeType, type s402ErrorInfo, type s402EscrowExtra, type s402EscrowPayload, type s402ExactPayload, s402Facilitator, type s402FacilitatorScheme, type s402Mandate, type s402MandateRequirements, type s402PaymentPayload, type s402PaymentPayloadBase, type s402PaymentRequirements, type s402PaymentSession, type s402PrepaidExtra, type s402PrepaidPayload, type s402RegistryQuery, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerScheme, type s402ServiceEntry, type s402SettleResponse, type s402SettlementMode, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402VerifyResponse, validateRequirementsShape };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { S402_HEADERS, S402_VERSION } from "./types.mjs";
 import { createS402Error, s402Error, s402ErrorCode } from "./errors.mjs";
-import { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
+import { S402_CONTENT_TYPE, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, validateRequirementsShape } from "./http.mjs";
 
 //#region src/client.ts
 var s402Client = class {
@@ -317,4 +317,4 @@ var s402Facilitator = class {
 };
 
 //#endregion
-export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };
+export { S402_CONTENT_TYPE, S402_HEADERS, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, isValidU64Amount, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s402",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "description": "s402 — Sui-native 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",