s402 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,192 @@
+import { createS402Error, s402Error, s402ErrorCode, s402ErrorCodeType, s402ErrorInfo } from "./errors.mjs";
+import { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PrepaidExtra, s402PrepaidPayload, s402Scheme, s402SettleResponse, s402SettlementMode, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402VerifyResponse } from "./types.mjs";
+import { decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, validateRequirementsShape } from "./http.mjs";
+
+//#region src/scheme.d.ts
+/** Implemented by each scheme on the client side */
+interface s402ClientScheme {
+  /** Which scheme this implements */
+  readonly scheme: s402Scheme;
+  /** Create a signed payment payload from server requirements */
+  createPayment(requirements: s402PaymentRequirements): Promise<s402PaymentPayload>;
+}
+/** Implemented by each scheme on the server side */
+interface s402ServerScheme {
+  readonly scheme: s402Scheme;
+  /** Build payment requirements from route config */
+  buildRequirements(config: s402RouteConfig): s402PaymentRequirements;
+}
+/**
+ * Implemented by each scheme in the facilitator.
+ *
+ * Critical: each scheme has its OWN verify logic.
+ * - Exact: signature recovery + dry-run simulation + balance check
+ * - Stream: stream creation PTB validation + deposit check
+ * - Escrow: escrow creation PTB validation + arbiter/deadline check
+ * - Unlock: escrow validation (key release is separate PTB)
+ */
+interface s402FacilitatorScheme {
+  readonly scheme: s402Scheme;
+  /** Verify a payment payload without broadcasting */
+  verify(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402VerifyResponse>;
+  /** Verify and broadcast the transaction */
+  settle(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+}
+/**
+ * For self-sovereign agents that hold their own keys.
+ * Builds, signs, and broadcasts in one step — no facilitator needed.
+ *
+ * MUST call waitForTransaction() before returning success.
+ * Without finality confirmation, server could grant access for a
+ * transaction that gets reverted.
+ */
+interface s402DirectScheme {
+  readonly scheme: s402Scheme;
+  /** Build, sign, broadcast, and wait for finality */
+  settleDirectly(requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+}
+/** Per-route payment configuration for the server middleware */
+interface s402RouteConfig {
+  /** Which payment scheme(s) to accept. Always includes "exact" for x402 compat. */
+  schemes: s402Scheme[];
+  /** Amount in base units, same as wire format (e.g., "1000000" for 0.001 SUI in MIST) */
+  price: string;
+  /** Sui network */
+  network: string;
+  /** Recipient address */
+  payTo: string;
+  /** Move coin type */
+  asset?: string;
+  /** Facilitator URL (optional for direct settlement) */
+  facilitatorUrl?: string;
+  /** Settlement mode preference */
+  settlementMode?: s402SettlementMode;
+  /** AP2 mandate requirements */
+  mandate?: {
+    required: boolean;
+    minPerTx?: string;
+  };
+  /** Protocol fee in basis points */
+  protocolFeeBps?: number;
+  /** Require on-chain receipt */
+  receiptRequired?: boolean;
+  stream?: {
+    ratePerSecond: string;
+    budgetCap: string;
+    minDeposit: string;
+  };
+  escrow?: {
+    seller: string;
+    arbiter?: string;
+    deadlineMs: string;
+  };
+  unlock?: {
+    encryptionId: string;
+    walrusBlobId: string;
+    encryptionPackageId: string;
+  };
+  prepaid?: {
+    ratePerCall: string;
+    maxCalls?: string;
+    minDeposit: string;
+    withdrawalDelayMs: string;
+  };
+}
+//#endregion
+//#region src/client.d.ts
+declare class s402Client {
+  private schemes;
+  /**
+   * Register a scheme implementation for a network.
+   *
+   * @param network - Sui network (e.g., "sui:testnet")
+   * @param scheme - Scheme implementation
+   */
+  register(network: string, scheme: s402ClientScheme): this;
+  /**
+   * Create a payment payload for the given requirements.
+   *
+   * Auto-selects the best scheme: prefers the first scheme in the server's
+   * `accepts` array that we have a registered implementation for.
+   *
+   * Accepts typed s402PaymentRequirements only. For x402 input, normalize
+   * first via `normalizeRequirements()` from 's402/compat'.
+   */
+  createPayment(requirements: s402PaymentRequirements): Promise<s402PaymentPayload>;
+  /**
+   * Check if we can handle requirements for a given network.
+   */
+  supports(network: string, scheme: s402Scheme): boolean;
+}
+//#endregion
+//#region src/facilitator.d.ts
+declare class s402Facilitator {
+  private schemes;
+  /**
+   * Register a scheme-specific facilitator for a network.
+   */
+  register(network: string, scheme: s402FacilitatorScheme): this;
+  /**
+   * Verify a payment payload by dispatching to the correct scheme.
+   */
+  verify(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402VerifyResponse>;
+  /**
+   * Settle a payment by dispatching to the correct scheme.
+   */
+  settle(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+  /**
+   * Expiration-guarded verify + settle in one call.
+   * Rejects expired requirements, verifies the payload, then settles.
+   *
+   * 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.
+   */
+  process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+  /**
+   * Check if a scheme is supported for a network.
+   */
+  supports(network: string, scheme: s402Scheme): boolean;
+  /**
+   * List supported schemes for a network.
+   */
+  supportedSchemes(network: string): s402Scheme[];
+  private resolveScheme;
+}
+//#endregion
+//#region src/server.d.ts
+declare class s402ResourceServer {
+  private schemes;
+  private facilitator;
+  /**
+   * Register a server-side scheme for building requirements.
+   */
+  register(network: string, scheme: s402ServerScheme): this;
+  /**
+   * Set the facilitator for verify + settle.
+   */
+  setFacilitator(facilitator: s402Facilitator): this;
+  /**
+   * Build payment requirements for a route.
+   * Uses the first scheme in the config's schemes array.
+   * Always includes "exact" in accepts for x402 compat.
+   */
+  buildRequirements(config: s402RouteConfig): s402PaymentRequirements;
+  /**
+   * Verify a payment payload.
+   */
+  verify(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402VerifyResponse>;
+  /**
+   * Settle a pre-verified payment payload (no verify, no expiration check).
+   * Prefer `process()` for the full guarded path.
+   */
+  settle(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+  /**
+   * 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.
+   */
+  process(payload: s402PaymentPayload, requirements: s402PaymentRequirements): Promise<s402SettleResponse>;
+}
+//#endregion
+export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, 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 s402PrepaidExtra, type s402PrepaidPayload, s402ResourceServer, type s402RouteConfig, type s402Scheme, type s402ServerScheme, type s402SettleResponse, type s402SettlementMode, type s402StreamExtra, type s402StreamPayload, type s402UnlockExtra, type s402UnlockPayload, type s402VerifyResponse, validateRequirementsShape };

package/dist/index.mjs

@@ -0,0 +1,209 @@
+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, validateRequirementsShape } from "./http.mjs";
+
+//#region src/client.ts
+var s402Client = class {
+	schemes = /* @__PURE__ */ new Map();
+	/**
+	* Register a scheme implementation for a network.
+	*
+	* @param network - Sui network (e.g., "sui:testnet")
+	* @param scheme - Scheme implementation
+	*/
+	register(network, scheme) {
+		if (!this.schemes.has(network)) this.schemes.set(network, /* @__PURE__ */ new Map());
+		this.schemes.get(network).set(scheme.scheme, scheme);
+		return this;
+	}
+	/**
+	* Create a payment payload for the given requirements.
+	*
+	* Auto-selects the best scheme: prefers the first scheme in the server's
+	* `accepts` array that we have a registered implementation for.
+	*
+	* Accepts typed s402PaymentRequirements only. For x402 input, normalize
+	* first via `normalizeRequirements()` from 's402/compat'.
+	*/
+	async createPayment(requirements) {
+		const networkSchemes = this.schemes.get(requirements.network);
+		if (!networkSchemes) throw new s402Error("NETWORK_MISMATCH", `No schemes registered for network "${requirements.network}"`);
+		for (const accepted of requirements.accepts) {
+			const scheme = networkSchemes.get(accepted);
+			if (scheme) return scheme.createPayment(requirements);
+		}
+		throw new s402Error("SCHEME_NOT_SUPPORTED", `No registered scheme matches server's accepts: [${requirements.accepts.join(", ")}]`);
+	}
+	/**
+	* Check if we can handle requirements for a given network.
+	*/
+	supports(network, scheme) {
+		return this.schemes.get(network)?.has(scheme) ?? false;
+	}
+};
+
+//#endregion
+//#region src/server.ts
+var s402ResourceServer = class {
+	schemes = /* @__PURE__ */ new Map();
+	facilitator = null;
+	/**
+	* Register a server-side scheme for building requirements.
+	*/
+	register(network, scheme) {
+		if (!this.schemes.has(network)) this.schemes.set(network, /* @__PURE__ */ new Map());
+		this.schemes.get(network).set(scheme.scheme, scheme);
+		return this;
+	}
+	/**
+	* Set the facilitator for verify + settle.
+	*/
+	setFacilitator(facilitator) {
+		this.facilitator = facilitator;
+		return this;
+	}
+	/**
+	* Build payment requirements for a route.
+	* Uses the first scheme in the config's schemes array.
+	* Always includes "exact" in accepts for x402 compat.
+	*/
+	buildRequirements(config) {
+		if (!isValidAmount(config.price)) throw new s402Error("INVALID_PAYLOAD", `Invalid price "${config.price}": must be a non-negative integer string`);
+		const networkSchemes = this.schemes.get(config.network);
+		const primaryScheme = config.schemes[0] ?? "exact";
+		const schemeImpl = networkSchemes?.get(primaryScheme);
+		if (schemeImpl) {
+			const requirements = schemeImpl.buildRequirements(config);
+			if (!requirements.accepts.includes("exact")) requirements.accepts = [...requirements.accepts, "exact"];
+			return requirements;
+		}
+		return {
+			s402Version: S402_VERSION,
+			accepts: [...new Set([...config.schemes, "exact"])],
+			network: config.network,
+			asset: config.asset ?? "0x2::sui::SUI",
+			amount: config.price,
+			payTo: config.payTo,
+			facilitatorUrl: config.facilitatorUrl,
+			mandate: config.mandate ? {
+				required: config.mandate.required,
+				minPerTx: config.mandate.minPerTx
+			} : void 0,
+			protocolFeeBps: config.protocolFeeBps,
+			receiptRequired: config.receiptRequired,
+			settlementMode: config.settlementMode,
+			stream: config.stream,
+			escrow: config.escrow,
+			unlock: config.unlock,
+			prepaid: config.prepaid
+		};
+	}
+	/**
+	* Verify a payment payload.
+	*/
+	async verify(payload, requirements) {
+		if (!this.facilitator) throw new s402Error("FACILITATOR_UNAVAILABLE", "No facilitator configured on this server");
+		return this.facilitator.verify(payload, requirements);
+	}
+	/**
+	* Settle a pre-verified payment payload (no verify, no expiration check).
+	* Prefer `process()` for the full guarded path.
+	*/
+	async settle(payload, requirements) {
+		if (!this.facilitator) throw new s402Error("FACILITATOR_UNAVAILABLE", "No facilitator configured on this server");
+		return this.facilitator.settle(payload, requirements);
+	}
+	/**
+	* 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.
+	*/
+	async process(payload, requirements) {
+		if (!this.facilitator) throw new s402Error("FACILITATOR_UNAVAILABLE", "No facilitator configured on this server");
+		return this.facilitator.process(payload, requirements);
+	}
+};
+
+//#endregion
+//#region src/facilitator.ts
+var s402Facilitator = class {
+	schemes = /* @__PURE__ */ new Map();
+	/**
+	* Register a scheme-specific facilitator for a network.
+	*/
+	register(network, scheme) {
+		if (!this.schemes.has(network)) this.schemes.set(network, /* @__PURE__ */ new Map());
+		this.schemes.get(network).set(scheme.scheme, scheme);
+		return this;
+	}
+	/**
+	* Verify a payment payload by dispatching to the correct scheme.
+	*/
+	async verify(payload, requirements) {
+		return this.resolveScheme(payload.scheme, requirements.network).verify(payload, requirements);
+	}
+	/**
+	* Settle a payment by dispatching to the correct scheme.
+	*/
+	async settle(payload, requirements) {
+		return this.resolveScheme(payload.scheme, requirements.network).settle(payload, requirements);
+	}
+	/**
+	* Expiration-guarded verify + settle in one call.
+	* Rejects expired requirements, verifies the payload, then settles.
+	*
+	* 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.
+	*/
+	async process(payload, requirements) {
+		if (requirements.expiresAt != null) {
+			if (typeof requirements.expiresAt !== "number" || !Number.isFinite(requirements.expiresAt)) return {
+				success: false,
+				error: `Invalid expiresAt value: expected finite number, got ${typeof requirements.expiresAt}`,
+				errorCode: "INVALID_PAYLOAD"
+			};
+			if (Date.now() > requirements.expiresAt) return {
+				success: false,
+				error: `Payment requirements expired at ${new Date(requirements.expiresAt).toISOString()}`,
+				errorCode: "REQUIREMENTS_EXPIRED"
+			};
+		}
+		const scheme = this.resolveScheme(payload.scheme, requirements.network);
+		const verifyResult = await scheme.verify(payload, requirements);
+		if (!verifyResult.valid) return {
+			success: false,
+			error: verifyResult.invalidReason ?? "Payment verification failed",
+			errorCode: "VERIFICATION_FAILED"
+		};
+		if (typeof requirements.expiresAt === "number" && Date.now() > requirements.expiresAt) return {
+			success: false,
+			error: `Payment requirements expired during verification at ${new Date(requirements.expiresAt).toISOString()}`,
+			errorCode: "REQUIREMENTS_EXPIRED"
+		};
+		return scheme.settle(payload, requirements);
+	}
+	/**
+	* Check if a scheme is supported for a network.
+	*/
+	supports(network, scheme) {
+		return this.schemes.get(network)?.has(scheme) ?? false;
+	}
+	/**
+	* List supported schemes for a network.
+	*/
+	supportedSchemes(network) {
+		const networkSchemes = this.schemes.get(network);
+		return networkSchemes ? [...networkSchemes.keys()] : [];
+	}
+	resolveScheme(scheme, network) {
+		const networkSchemes = this.schemes.get(network);
+		if (!networkSchemes) throw new s402Error("NETWORK_MISMATCH", `No facilitator schemes registered for network "${network}"`);
+		const impl = networkSchemes.get(scheme);
+		if (!impl) throw new s402Error("SCHEME_NOT_SUPPORTED", `Scheme "${scheme}" is not supported on network "${network}". Supported: [${[...networkSchemes.keys()].join(", ")}]`);
+		return impl;
+	}
+};
+
+//#endregion
+export { S402_HEADERS, S402_VERSION, createS402Error, decodePaymentPayload, decodePaymentRequired, decodeSettleResponse, detectProtocol, encodePaymentPayload, encodePaymentRequired, encodeSettleResponse, extractRequirementsFromResponse, isValidAmount, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };

package/dist/types.d.mts

@@ -0,0 +1,252 @@
+import { s402ErrorCodeType } from "./errors.mjs";
+
+//#region src/types.d.ts
+/** Current protocol version. Always lowercase s. */
+declare const S402_VERSION: "1";
+/** The five s402 payment schemes */
+type s402Scheme = 'exact' | 'stream' | 'escrow' | 'unlock' | 'prepaid';
+/** Settlement mode: facilitator-mediated or direct on-chain */
+type s402SettlementMode = 'facilitator' | 'direct';
+/**
+ * Base payment requirements — included in every 402 response.
+ * Wire-compatible with x402 PaymentRequirements where fields overlap.
+ */
+interface s402PaymentRequirements {
+  /** Protocol version (always "1") */
+  s402Version: typeof S402_VERSION;
+  /** Which payment schemes the server accepts. Always includes "exact" for x402 compat. */
+  accepts: s402Scheme[];
+  /** Sui network (e.g., "sui:testnet", "sui:mainnet") */
+  network: string;
+  /** Move coin type (e.g., "0x2::sui::SUI") */
+  asset: string;
+  /** Amount in base units (MIST for SUI, 6-decimal for USDC) */
+  amount: string;
+  /** Recipient address */
+  payTo: string;
+  /** Facilitator URL (optional for direct settlement) */
+  facilitatorUrl?: string;
+  /** AP2 mandate requirements (if agent spending authorization is needed) */
+  mandate?: s402MandateRequirements;
+  /** Protocol fee in basis points (0-10000). 0 = no fee. */
+  protocolFeeBps?: number;
+  /** Address that receives the protocol fee. Defaults to payTo if omitted. */
+  protocolFeeAddress?: string;
+  /** Whether the server requires an on-chain receipt NFT */
+  receiptRequired?: boolean;
+  /** Settlement mode preference */
+  settlementMode?: s402SettlementMode;
+  /** When these requirements expire (Unix timestamp ms). Facilitator MUST reject after this. */
+  expiresAt?: number;
+  /** Extra fields for stream scheme */
+  stream?: s402StreamExtra;
+  /** Extra fields for escrow scheme */
+  escrow?: s402EscrowExtra;
+  /** Extra fields for unlock scheme (pay-to-decrypt encrypted content) */
+  unlock?: s402UnlockExtra;
+  /** Extra fields for prepaid scheme */
+  prepaid?: s402PrepaidExtra;
+  /** Arbitrary extension data (forward-compatible extensibility) */
+  extensions?: Record<string, unknown>;
+}
+/** Stream-specific requirements */
+interface s402StreamExtra {
+  /** Rate in base units per second */
+  ratePerSecond: string;
+  /** Maximum budget cap in base units */
+  budgetCap: string;
+  /** Minimum initial deposit in base units */
+  minDeposit: string;
+  /** URL for stream status checks (phase 2) */
+  streamSetupUrl?: string;
+}
+/** Escrow-specific requirements */
+interface s402EscrowExtra {
+  /** Seller/payee address */
+  seller: string;
+  /** Arbiter address for dispute resolution */
+  arbiter?: string;
+  /** Escrow deadline in milliseconds since epoch */
+  deadlineMs: string;
+}
+/** Unlock-specific requirements (pay-to-decrypt encrypted content) */
+interface s402UnlockExtra {
+  /** Encryption ID for key servers */
+  encryptionId: string;
+  /** Walrus blob ID containing the encrypted content */
+  walrusBlobId: string;
+  /** Encryption package ID on Sui */
+  encryptionPackageId: string;
+}
+/**
+ * Prepaid-specific requirements.
+ *
+ * NOTE: Prepaid inverts the normal s402 flow — the PROVIDER signs claims,
+ * not the CLIENT. The deposit phase uses the standard client→facilitator flow,
+ * but claims are provider-initiated. Full HTTP flow integration is Phase 2+.
+ *
+ * TRUST MODEL: Trust-bounded, not trustless. The provider submits call_count —
+ * Move cannot verify calls actually happened. Agent's protection: rate cap,
+ * max_calls, deposit ceiling, small deposits + short refill cycles, reputation.
+ * v0.2 adds signed usage receipts for cryptographic fraud proofs. See ADR-007.
+ */
+interface s402PrepaidExtra {
+  /** Maximum base units per API call (rate cap) */
+  ratePerCall: string;
+  /** Max calls cap. Omit for unlimited (u64::MAX on-chain). */
+  maxCalls?: string;
+  /** Minimum deposit amount in base units */
+  minDeposit: string;
+  /** Withdrawal delay in ms. Agent must wait this long after last claim. Min 60s, max 7d. */
+  withdrawalDelayMs: string;
+}
+/** Mandate requirements in a 402 response — tells client what mandate is needed */
+interface s402MandateRequirements {
+  /** Whether a mandate is required (true) or optional (false = speeds up if present) */
+  required: boolean;
+  /** Minimum per-transaction limit needed */
+  minPerTx?: string;
+  /** Mandate coin type (must match payment asset) */
+  coinType?: string;
+}
+/** On-chain mandate reference — included in payment payload when agent has authorization */
+interface s402Mandate {
+  /** Mandate object ID on Sui */
+  mandateId: string;
+  /** Delegator (human) address */
+  delegator: string;
+  /** Delegate (agent) address */
+  delegate: string;
+  /** Per-transaction spending limit */
+  maxPerTx: string;
+  /** Lifetime spending cap */
+  maxTotal: string;
+  /** Amount already spent */
+  totalSpent: string;
+  /** Expiry timestamp (ms since epoch) */
+  expiresAtMs: string;
+}
+/** Base payload — all schemes include these fields */
+interface s402PaymentPayloadBase {
+  /** Protocol version */
+  s402Version: typeof S402_VERSION;
+  /** Which scheme is being used */
+  scheme: s402Scheme;
+}
+/** Exact payment: signed transaction bytes */
+interface s402ExactPayload extends s402PaymentPayloadBase {
+  scheme: 'exact';
+  payload: {
+    /** Base64-encoded signed transaction bytes */transaction: string; /** Base64-encoded signature */
+    signature: string;
+  };
+}
+/** Stream payment: signed stream creation transaction */
+interface s402StreamPayload extends s402PaymentPayloadBase {
+  scheme: 'stream';
+  payload: {
+    transaction: string;
+    signature: string;
+  };
+}
+/** Escrow payment: signed escrow creation transaction */
+interface s402EscrowPayload extends s402PaymentPayloadBase {
+  scheme: 'escrow';
+  payload: {
+    transaction: string;
+    signature: string;
+  };
+}
+/**
+ * Unlock payment: escrow creation + encryption-gated decryption.
+ *
+ * Implementation note: The encryption key release function requires all arguments
+ * to be `Argument::Input` (not results of prior commands), so the unlock flow is
+ * two-stage: TX1 creates the escrow receipt, TX2 passes that receipt as
+ * input to the key release for decryption. The `transaction` field here is
+ * TX1 (escrow creation). TX2 is built by the facilitator after TX1 settles.
+ */
+interface s402UnlockPayload extends s402PaymentPayloadBase {
+  scheme: 'unlock';
+  payload: {
+    /** Escrow creation transaction (TX1 of two-stage unlock flow) */transaction: string;
+    signature: string; /** Encryption ID for key servers */
+    encryptionId: string;
+  };
+}
+/**
+ * Prepaid payment: agent deposits into a PrepaidBalance shared object.
+ * This is the deposit phase only — claims are provider-initiated (not via HTTP 402).
+ */
+interface s402PrepaidPayload extends s402PaymentPayloadBase {
+  scheme: 'prepaid';
+  payload: {
+    /** Base64-encoded deposit PTB */transaction: string; /** Agent's signature */
+    signature: string; /** Committed rate per call (must match requirements) */
+    ratePerCall: string; /** Committed max calls cap (must match requirements) */
+    maxCalls?: string;
+  };
+}
+/** Discriminated union of all payment payloads */
+type s402PaymentPayload = s402ExactPayload | s402StreamPayload | s402EscrowPayload | s402UnlockPayload | s402PrepaidPayload;
+interface s402SettleResponse {
+  /** Whether settlement was successful */
+  success: boolean;
+  /** Transaction digest on Sui */
+  txDigest?: string;
+  /** On-chain receipt object ID (if receipt was minted) */
+  receiptId?: string;
+  /** Time to finality in milliseconds */
+  finalityMs?: number;
+  /** Stream object ID (for stream scheme) */
+  streamId?: string;
+  /** Escrow object ID (for escrow scheme) */
+  escrowId?: string;
+  /** PrepaidBalance object ID (for prepaid scheme) */
+  balanceId?: string;
+  /** Error message if settlement failed */
+  error?: string;
+  /** Typed error code for programmatic failure handling */
+  errorCode?: s402ErrorCodeType;
+}
+interface s402VerifyResponse {
+  /** Whether the payment payload is valid */
+  valid: boolean;
+  /** Reason for rejection */
+  invalidReason?: string;
+  /** Payer address (recovered from signature) */
+  payerAddress?: string;
+}
+interface s402Discovery {
+  /** Protocol version */
+  s402Version: typeof S402_VERSION;
+  /** Supported schemes */
+  schemes: s402Scheme[];
+  /** Supported Sui networks */
+  networks: string[];
+  /** Supported coin types */
+  assets: string[];
+  /** Facilitator URL */
+  facilitatorUrl?: string;
+  /** Whether direct settlement is supported */
+  directSettlement: boolean;
+  /** Whether mandates are supported */
+  mandateSupport: boolean;
+  /** Protocol fee in basis points */
+  protocolFeeBps: number;
+  /** Address that receives the protocol fee */
+  protocolFeeAddress?: string;
+}
+/**
+ * HTTP headers used by s402 (same names as x402 for compatibility).
+ * All lowercase per HTTP/2 spec (RFC 9113 §8.2.1). The Headers API
+ * normalizes casing for HTTP/1.1, so lowercase works everywhere.
+ */
+declare const S402_HEADERS: {
+  /** Server → client: payment requirements (base64 JSON in 402 response) */readonly PAYMENT_REQUIRED: "payment-required"; /** Client → server: payment payload (base64 JSON) */
+  readonly PAYMENT: "x-payment"; /** Server → client: settlement result (base64 JSON) */
+  readonly PAYMENT_RESPONSE: "payment-response"; /** Client → server: active stream ID (phase 2 of stream protocol) */
+  readonly STREAM_ID: "x-stream-id";
+};
+//#endregion
+export { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PrepaidExtra, s402PrepaidPayload, s402Scheme, s402SettleResponse, s402SettlementMode, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402VerifyResponse };

package/dist/types.mjs

@@ -0,0 +1,17 @@
+//#region src/types.ts
+/** Current protocol version. Always lowercase s. */
+const S402_VERSION = "1";
+/**
+* HTTP headers used by s402 (same names as x402 for compatibility).
+* All lowercase per HTTP/2 spec (RFC 9113 §8.2.1). The Headers API
+* normalizes casing for HTTP/1.1, so lowercase works everywhere.
+*/
+const S402_HEADERS = {
+	PAYMENT_REQUIRED: "payment-required",
+	PAYMENT: "x-payment",
+	PAYMENT_RESPONSE: "payment-response",
+	STREAM_ID: "x-stream-id"
+};
+
+//#endregion
+export { S402_HEADERS, S402_VERSION };