s402 0.4.0 → 0.5.0

package/dist/index.mjs

@@ -140,10 +140,11 @@ var s402ResourceServer = class {
 			protocolFeeBps: config.protocolFeeBps,
 			receiptRequired: config.receiptRequired,
 			settlementMode: config.settlementMode,
+			upto: config.upto,
+			prepaid: config.prepaid,
 			stream: config.stream,
 			escrow: config.escrow,
-			unlock: config.unlock,
-			prepaid: config.prepaid
+			unlock: config.unlock
 		};
 	}
 	/**
@@ -186,11 +187,129 @@ var s402ResourceServer = class {
 	}
 };
 
+//#endregion
+//#region src/extensions.ts
+/**
+* Type-safe extension data retrieval.
+*
+* The wire format is `Record<string, unknown>` for interop, but this helper
+* provides typed access for TypeScript consumers.
+*
+* @example
+* ```ts
+* interface DiscoveryData { services: string[] }
+* const data = getExtensionData<DiscoveryData>(requirements.extensions, 'org.s402.discovery');
+* if (data) console.log(data.services);
+* ```
+*/
+function getExtensionData(extensions, key) {
+	return extensions?.[key];
+}
+/**
+* Set extension data on an extensions record (creates if needed).
+* Returns a new extensions object (does not mutate the input).
+*/
+function setExtensionData(extensions, key, data) {
+	return {
+		...extensions,
+		[key]: data
+	};
+}
+/**
+* Registry for extensions with dependency-ordered execution.
+*
+* Extensions are stored by key and sorted topologically based on `dependsOn`.
+* Within the same dependency level, registration order is preserved.
+*
+* @example
+* ```ts
+* const registry = new s402ExtensionRegistry<s402FacilitatorExtension>();
+* registry.register(rateLimitExtension);
+* registry.register(analyticsExtension);
+* const sorted = registry.sorted(); // dependency-ordered list
+* ```
+*/
+var s402ExtensionRegistry = class {
+	extensions = /* @__PURE__ */ new Map();
+	sortedCache = null;
+	/**
+	* Register an extension. Throws on duplicate key or dependency cycle.
+	*/
+	register(ext) {
+		if (this.extensions.has(ext.key)) throw new s402Error("EXTENSION_FAILED", `Extension "${ext.key}" is already registered`);
+		this.extensions.set(ext.key, ext);
+		this.sortedCache = null;
+	}
+	/** Get a registered extension by key. */
+	get(key) {
+		return this.extensions.get(key);
+	}
+	/** Number of registered extensions. */
+	get size() {
+		return this.extensions.size;
+	}
+	/**
+	* Return extensions in topological (dependency) order.
+	* Cached until a new extension is registered.
+	*/
+	sorted() {
+		if (this.sortedCache) return this.sortedCache;
+		this.sortedCache = topologicalSort(this.extensions);
+		return this.sortedCache;
+	}
+};
+/**
+* Topological sort of extensions based on `dependsOn` declarations.
+* Uses Kahn's algorithm. Throws on cycles.
+*/
+function topologicalSort(extensions) {
+	if (extensions.size === 0) return [];
+	const inDegree = /* @__PURE__ */ new Map();
+	const dependents = /* @__PURE__ */ new Map();
+	for (const [key] of extensions) {
+		inDegree.set(key, 0);
+		dependents.set(key, []);
+	}
+	for (const [key, ext] of extensions) if (ext.dependsOn) for (const dep of ext.dependsOn) {
+		if (!extensions.has(dep)) throw new s402Error("EXTENSION_FAILED", `Extension "${key}" depends on "${dep}" which is not registered`);
+		dependents.get(dep).push(key);
+		inDegree.set(key, (inDegree.get(key) ?? 0) + 1);
+	}
+	const queue = [];
+	for (const [key, degree] of inDegree) if (degree === 0) queue.push(key);
+	const sorted = [];
+	while (queue.length > 0) {
+		const key = queue.shift();
+		sorted.push(extensions.get(key));
+		for (const dependent of dependents.get(key)) {
+			const newDegree = inDegree.get(dependent) - 1;
+			inDegree.set(dependent, newDegree);
+			if (newDegree === 0) queue.push(dependent);
+		}
+	}
+	if (sorted.length !== extensions.size) throw new s402Error("EXTENSION_FAILED", `Extension dependency cycle detected involving: ${[...extensions.keys()].filter((k) => !sorted.some((e) => e.key === k)).join(", ")}`);
+	return sorted;
+}
+/**
+* Run an async hook on all extensions in order.
+* Critical extensions throw on failure; advisory extensions call the error handler.
+*/
+async function runExtensionHooks(extensions, hookName, runner, onError) {
+	for (const ext of extensions) try {
+		await runner(ext);
+	} catch (e) {
+		if (ext.critical) throw new s402Error("EXTENSION_FAILED", `Critical extension "${ext.key}" failed in ${hookName}: ${e instanceof Error ? e.message : String(e)}`);
+		onError?.(ext, e);
+	}
+}
+
 //#endregion
 //#region src/facilitator.ts
 var s402Facilitator = class {
 	schemes = /* @__PURE__ */ new Map();
 	inFlight = /* @__PURE__ */ new Set();
+	extensionRegistry = new s402ExtensionRegistry();
+	extensionErrorHandler;
 	/**
 	* Register a scheme-specific facilitator for a network.
 	*/
@@ -200,6 +319,25 @@ var s402Facilitator = class {
 		return this;
 	}
 	/**
+	* Register a facilitator extension. Extensions fire in dependency order
+	* at four points in the process() pipeline: beforeVerify, afterVerify,
+	* beforeSettle, afterSettle.
+	*
+	* @throws {s402Error} `EXTENSION_FAILED` on duplicate key or dependency cycle
+	*/
+	registerExtension(ext) {
+		this.extensionRegistry.register(ext);
+		return this;
+	}
+	/**
+	* Set the handler for advisory (non-critical) extension failures.
+	* Critical extensions always throw; advisory extensions call this handler.
+	*/
+	onExtensionError(handler) {
+		this.extensionErrorHandler = handler;
+		return this;
+	}
+	/**
 	* Verify a payment payload by dispatching to the correct scheme.
 	* Includes expiration guard and scheme-mismatch check.
 	*/
@@ -284,6 +422,7 @@ var s402Facilitator = class {
 	*
 	* @param payload - Client's payment payload
 	* @param requirements - Server's payment requirements
+	* @param options - Optional process configuration (e.g., `{ skipVerify: true }` for zero-cost-failure chains)
 	* @returns Settlement result (check `result.success` and `result.errorCode`)
 	*
 	* @example
@@ -301,7 +440,7 @@ var s402Facilitator = class {
 	* }
 	* ```
 	*/
-	async process(payload, requirements) {
+	async process(payload, requirements, options) {
 		if (requirements.expiresAt != null) {
 			if (typeof requirements.expiresAt !== "number" || !Number.isFinite(requirements.expiresAt)) return {
 				success: false,
@@ -343,33 +482,79 @@ var s402Facilitator = class {
 			errorCode: "INVALID_PAYLOAD"
 		};
 		this.inFlight.add(dedupeKey);
+		const extensions = this.extensionRegistry.size > 0 ? this.extensionRegistry.sorted() : null;
 		try {
-			let verifyResult;
-			try {
-				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));
+			if (!options?.skipVerify) {
+				if (extensions) try {
+					await runExtensionHooks(extensions, "beforeVerify", (ext) => ext.beforeVerify ? ext.beforeVerify(payload, requirements) : Promise.resolve(), this.extensionErrorHandler);
+				} catch (e) {
+					if (e instanceof s402Error) return {
+						success: false,
+						error: e.message,
+						errorCode: e.code
+					};
+					return {
+						success: false,
+						error: "Extension beforeVerify failed",
+						errorCode: "EXTENSION_FAILED"
+					};
+				}
+				let verifyResult;
+				try {
+					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,
+						error: e instanceof Error ? e.message : "Verification threw an unexpected error",
+						errorCode: "VERIFICATION_FAILED"
+					};
+				}
+				if (!verifyResult.valid) return {
+					success: false,
+					error: verifyResult.invalidReason ?? "Payment verification failed",
+					errorCode: "VERIFICATION_FAILED"
+				};
+				if (extensions) try {
+					await runExtensionHooks(extensions, "afterVerify", (ext) => ext.afterVerify ? ext.afterVerify(payload, verifyResult) : Promise.resolve(), this.extensionErrorHandler);
+				} catch (e) {
+					if (e instanceof s402Error) return {
+						success: false,
+						error: e.message,
+						errorCode: e.code
+					};
+					return {
+						success: false,
+						error: "Extension afterVerify failed",
+						errorCode: "EXTENSION_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"
+				};
+			}
+			if (extensions) try {
+				await runExtensionHooks(extensions, "beforeSettle", (ext) => ext.beforeSettle ? ext.beforeSettle(payload, requirements) : Promise.resolve(), this.extensionErrorHandler);
 			} catch (e) {
+				if (e instanceof s402Error) return {
+					success: false,
+					error: e.message,
+					errorCode: e.code
+				};
 				return {
 					success: false,
-					error: e instanceof Error ? e.message : "Verification threw an unexpected error",
-					errorCode: "VERIFICATION_FAILED"
+					error: "Extension beforeSettle failed",
+					errorCode: "EXTENSION_FAILED"
 				};
 			}
-			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"
-			};
+			let settleResult;
 			try {
 				let settleTimer;
-				return await Promise.race([scheme.settle(payload, requirements), new Promise((_, reject) => {
+				settleResult = 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) {
@@ -379,6 +564,16 @@ var s402Facilitator = class {
 					errorCode: "SETTLEMENT_FAILED"
 				};
 			}
+			if (extensions && settleResult.success) try {
+				await runExtensionHooks(extensions, "afterSettle", (ext) => ext.afterSettle ? ext.afterSettle(payload, settleResult) : Promise.resolve(), this.extensionErrorHandler);
+			} catch (e) {
+				this.extensionErrorHandler?.({
+					key: "afterSettle",
+					version: "0",
+					critical: true
+				}, e);
+			}
+			return settleResult;
 		} finally {
 			this.inFlight.delete(dedupeKey);
 		}
@@ -406,4 +601,4 @@ var s402Facilitator = class {
 };
 
 //#endregion
-export { S402_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatReceiptHeader, isValidAmount, isValidU64Amount, parseReceiptHeader, s402Client, s402Error, s402ErrorCode, s402Facilitator, s402ResourceServer, validateRequirementsShape };
+export { S402_CONTENT_TYPE, S402_HEADERS, S402_RECEIPT_HEADER, S402_VERSION, createS402Error, decodePayloadBody, decodePaymentPayload, decodePaymentRequired, decodeRequirementsBody, decodeSettleBody, decodeSettleResponse, detectProtocol, detectTransport, encodePayloadBody, encodePaymentPayload, encodePaymentRequired, encodeRequirementsBody, encodeSettleBody, encodeSettleResponse, extractRequirementsFromResponse, formatReceiptHeader, getExtensionData, isValidAmount, isValidU64Amount, parseReceiptHeader, runExtensionHooks, s402Client, s402Error, s402ErrorCode, s402ExtensionRegistry, s402Facilitator, s402ResourceServer, setExtensionData, validateRequirementsShape };

package/dist/{scheme-tVj4sOr-.d.mts → scheme-m-uk4zyH.d.mts}

@@ -60,6 +60,8 @@ interface s402ServerScheme {
  *
  * Critical: each scheme has its OWN verify logic.
  * - Exact: signature recovery + dry-run simulation + balance check
+ * - Upto: deposit PTB validation + maxAmount match + deadline check
+ * - Prepaid: deposit PTB validation + rate/cap match
  * - Stream: stream creation PTB validation + deposit check
  * - Escrow: escrow creation PTB validation + arbiter/deadline check
  * - Unlock: escrow validation (key release is separate PTB)
@@ -109,6 +111,20 @@ interface s402RouteConfig {
   protocolFeeBps?: number;
   /** Require on-chain receipt */
   receiptRequired?: boolean;
+  upto?: {
+    maxAmount: string;
+    settlementDeadlineMs: string;
+    usageReportUrl?: string;
+    estimatedAmount?: string;
+  };
+  prepaid?: {
+    ratePerCall: string;
+    maxCalls?: string;
+    minDeposit: string;
+    withdrawalDelayMs: string; /** Provider Ed25519 pubkey (hex). Enables v0.2 signed receipt mode. @since v0.2 */
+    providerPubkey?: string; /** Dispute window in ms. Required when providerPubkey is set. @since v0.2 */
+    disputeWindowMs?: string;
+  };
   stream?: {
     ratePerSecond: string;
     budgetCap: string;
@@ -124,14 +140,6 @@ interface s402RouteConfig {
     encryptedContentId: string;
     encryptionServiceId: string;
   };
-  prepaid?: {
-    ratePerCall: string;
-    maxCalls?: string;
-    minDeposit: string;
-    withdrawalDelayMs: string; /** Provider Ed25519 pubkey (hex). Enables v0.2 signed receipt mode. @since v0.2 */
-    providerPubkey?: string; /** Dispute window in ms. Required when providerPubkey is set. @since v0.2 */
-    disputeWindowMs?: string;
-  };
 }
 //#endregion
 export { s402ServerScheme as a, s402RouteConfig as i, s402DirectScheme as n, s402SettlementVerification as o, s402FacilitatorScheme as r, s402ClientScheme as t };

package/dist/test-utils.d.mts

@@ -1,5 +1,5 @@
 import { s402PaymentPayload, s402PaymentRequirements, s402SettleResponse, s402VerifyResponse } from "./types.mjs";
-import { a as s402ServerScheme, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-tVj4sOr-.mjs";
+import { a as s402ServerScheme, r as s402FacilitatorScheme, t as s402ClientScheme } from "./scheme-m-uk4zyH.mjs";
 
 //#region src/test-utils.d.ts
 /**

package/dist/types.d.mts

@@ -3,8 +3,14 @@ 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';
+/**
+ * The six s402 payment schemes, ordered by complexity:
+ *
+ * TIER 1 — Single Payment:  exact (fixed amount), upto (variable amount)
+ * TIER 2 — Persistent Balance: prepaid (multi-claim), stream (time-based)
+ * TIER 3 — Conditional Release: escrow (arbiter), unlock (encryption)
+ */
+type s402Scheme = 'exact' | 'upto' | 'prepaid' | 'stream' | 'escrow' | 'unlock';
 /** Settlement mode: facilitator-mediated or direct on-chain */
 type s402SettlementMode = 'facilitator' | 'direct';
 /**
@@ -64,14 +70,18 @@ interface s402PaymentRequirements {
   settlementMode?: s402SettlementMode;
   /** When these requirements expire (Unix timestamp ms). Facilitator MUST reject after this. */
   expiresAt?: number;
+  /** Extra fields for upto scheme (usage-based, variable settlement) */
+  upto?: s402UptoExtra;
+  /** Extra fields for prepaid scheme */
+  prepaid?: s402PrepaidExtra;
   /** 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;
+  /** Settlement overrides (used by upto scheme — server provides actual amount at settle-time) */
+  settlementOverrides?: s402SettlementOverrides;
   /**
    * Arbitrary extension data (forward-compatible extensibility).
    *
@@ -83,34 +93,57 @@ interface s402PaymentRequirements {
    */
   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;
+/**
+ * Upto-specific requirements (usage-based, variable settlement).
+ *
+ * The client authorizes up to `maxAmount`; the facilitator settles the actual
+ * amount (provided by the server via `settlementOverrides`) at settlement time.
+ * Remainder is returned to the payer on-chain.
+ *
+ * TRUST MODEL: The client can bound its exposure via `settlementCeiling` in the
+ * payment payload — an on-chain-enforced cap tighter than `maxAmount`. The server
+ * advertises `estimatedAmount` so the client can set a tight ceiling (e.g., 1.2x
+ * the estimate). Without `settlementCeiling`, the facilitator can settle up to
+ * `maxAmount`. See ADR-003 §Decision 3 and §Decision 8.
+ *
+ * SEMANTIC CLARITY: `amount` on the parent `s402PaymentRequirements` is the
+ * EXACT price for the `exact` scheme. For `upto`, `maxAmount` here is the
+ * ceiling — the two are intentionally separate fields to avoid the semantic
+ * overloading that x402 suffers from.
+ */
+interface s402UptoExtra {
+  /** Maximum authorized amount in base units. Client deposits this; actual may be less. */
+  maxAmount: string;
+  /**
+   * Deadline for settlement in milliseconds since epoch.
+   * After this time, the payer can reclaim the full deposit via `expire()`.
+   * Must be in the future at verify-time. Facilitator MUST reject expired deposits.
+   */
+  settlementDeadlineMs: string;
+  /** Optional URL where the client can query usage/metering data (informational) */
+  usageReportUrl?: string;
+  /**
+   * Server's estimated cost in base units (advisory, optional).
+   * Helps the client set a tight `settlementCeiling` in the payload.
+   * Must be ≤ maxAmount when present. Not enforced on-chain — purely informational.
+   */
+  estimatedAmount?: string;
 }
-/** Unlock-specific requirements (pay-to-decrypt encrypted content) */
-interface s402UnlockExtra {
-  /** Encryption ID for key servers */
-  encryptionId: string;
-  /** Content identifier for the encrypted blob (e.g., Walrus blob ID, IPFS CID) */
-  encryptedContentId: string;
-  /** Identifier for the encryption service or module (e.g., Sui package ID, EVM contract address) */
-  encryptionServiceId: string;
+/**
+ * Settlement overrides — server provides the actual amount to the facilitator.
+ *
+ * Used by the `upto` scheme: the resource server tells the facilitator how much
+ * of the authorized maximum to actually charge, based on observed usage.
+ * Threaded via `requirements.settlementOverrides` so the facilitator's `process()`
+ * signature (payload, requirements) doesn't need to change.
+ *
+ * TRUST MODEL: The server is trusted to report honest usage. The facilitator
+ * enforces `actualAmount <= maxAmount` but cannot verify usage independently.
+ * On-chain events provide an audit trail for dispute resolution.
+ */
+interface s402SettlementOverrides {
+  /** Actual amount to settle in base units. Must be ≤ maxAmount from UptoExtra. */
+  actualAmount: string;
 }
 /**
  * Prepaid-specific requirements.
@@ -152,6 +185,35 @@ interface s402PrepaidExtra {
    */
   disputeWindowMs?: string;
 }
+/** 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;
+  /** Content identifier for the encrypted blob (e.g., Walrus blob ID, IPFS CID) */
+  encryptedContentId: string;
+  /** Identifier for the encryption service or module (e.g., Sui package ID, EVM contract address) */
+  encryptionServiceId: 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) */
@@ -193,6 +255,46 @@ interface s402ExactPayload extends s402PaymentPayloadBase {
     signature: string;
   };
 }
+/**
+ * Upto payment: signed deposit transaction for variable-amount settlement.
+ *
+ * The client deposits `maxAmount` into an on-chain UptoDeposit proxy.
+ * The facilitator later calls `settle(actual_amount)` where
+ * `actual ≤ min(maxAmount, settlementCeiling)`, returning the remainder
+ * to the payer. If settlement doesn't happen before the deadline, the
+ * payer can reclaim via `expire()`.
+ */
+interface s402UptoPayload extends s402PaymentPayloadBase {
+  scheme: 'upto';
+  payload: {
+    /** Base64-encoded signed deposit transaction (creates UptoDeposit on-chain) */transaction: string; /** Base64-encoded signature */
+    signature: string; /** Maximum authorized amount (must match requirements.upto.maxAmount) */
+    maxAmount: string;
+    /**
+     * Client-chosen settlement ceiling (optional, on-chain enforced).
+     * The Move contract rejects settlements where `actualAmount > settlementCeiling`.
+     * Must satisfy: `1 <= settlementCeiling <= maxAmount`.
+     * Omit to allow settlement up to `maxAmount` (backwards compatible).
+     *
+     * Servers SHOULD check this before serving expensive resources — if
+     * `settlementCeiling < estimatedCost`, respond with an updated 402.
+     */
+    settlementCeiling?: 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;
+  };
+}
 /** Stream payment: signed stream creation transaction */
 interface s402StreamPayload extends s402PaymentPayloadBase {
   scheme: 'stream';
@@ -226,21 +328,8 @@ interface s402UnlockPayload extends s402PaymentPayloadBase {
     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;
+type s402PaymentPayload = s402ExactPayload | s402UptoPayload | s402PrepaidPayload | s402StreamPayload | s402EscrowPayload | s402UnlockPayload;
 interface s402SettleResponse {
   /** Whether settlement was successful */
   success: boolean;
@@ -250,12 +339,16 @@ interface s402SettleResponse {
   receiptId?: string;
   /** Time to finality in milliseconds */
   finalityMs?: number;
+  /** Actual amount settled in base units (for upto scheme — fixes x402's opacity) */
+  actualAmount?: string;
+  /** UptoDeposit object ID (for upto scheme) */
+  depositId?: string;
+  /** PrepaidBalance object ID (for prepaid scheme) */
+  balanceId?: string;
   /** 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 */
@@ -356,4 +449,4 @@ declare const S402_HEADERS: {
   readonly STREAM_ID: "x-stream-id";
 };
 //#endregion
-export { 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 };
+export { S402_HEADERS, S402_VERSION, s402Discovery, s402EscrowExtra, s402EscrowPayload, s402ExactPayload, s402Mandate, s402MandateRequirements, s402PaymentPayload, s402PaymentPayloadBase, s402PaymentRequirements, s402PaymentSession, s402PrepaidExtra, s402PrepaidPayload, s402RegistryQuery, s402Scheme, s402ServiceEntry, s402SettleResponse, s402SettlementMode, s402SettlementOverrides, s402StreamExtra, s402StreamPayload, s402UnlockExtra, s402UnlockPayload, s402UptoExtra, s402UptoPayload, s402VerifyResponse };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "s402",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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.",
+  "description": "s402 — Chain-agnostic HTTP 402 wire format. Types, HTTP encoding, and scheme registry for six payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
   "license": "Apache-2.0",
   "author": "SweeInc <daniel@sweeinc.com> (https://s402-protocol.org)",
   "repository": {
@@ -89,6 +89,13 @@
       },
       "default": "./dist/receipts.mjs"
     },
+    "./extensions": {
+      "import": {
+        "types": "./dist/extensions.d.mts",
+        "default": "./dist/extensions.mjs"
+      },
+      "default": "./dist/extensions.mjs"
+    },
     "./test-utils": {
       "import": {
         "types": "./dist/test-utils.d.mts",