Add transport context to enrichSettleResponse

typescript/.changeset/tired-days-behave.md

@@ -0,0 +1,5 @@
+---
+'@x402/core': patch
+---
+
+Added transport context to enrichSettleResponse and enrichPaymentRequiredResponse hooks

typescript/packages/core/src/http/index.ts

@@ -82,6 +82,7 @@ export {
   x402HTTPResourceServer,
   HTTPAdapter,
   HTTPRequestContext,
+  HTTPTransportContext,
   HTTPResponseInstructions,
   HTTPProcessResult,
   PaywallConfig,

typescript/packages/core/src/http/x402HTTPResourceServer.ts

@@ -188,6 +188,16 @@ export interface HTTPRequestContext {
   paymentHeader?: string;
 }
 
+/**
+ * HTTP transport context contains both request context and optional response data.
+ */
+export interface HTTPTransportContext {
+  /** The HTTP request context */
+  request: HTTPRequestContext;
+  /** The response body buffer */
+  responseBody?: Buffer;
+}
+
 /**
  * HTTP response instructions for the framework middleware
  */
@@ -435,11 +445,13 @@ export class x402HTTPResourceServer {
     }
 
     // createPaymentRequiredResponse already handles extension enrichment in the core layer
+    const transportContext: HTTPTransportContext = { request: context };
     const paymentRequired = await this.ResourceServer.createPaymentRequiredResponse(
       requirements,
       resourceInfo,
       !paymentPayload ? "Payment required" : undefined,
       extensions,
+      transportContext,
     );
 
     // If no payment provided
@@ -474,6 +486,7 @@ export class x402HTTPResourceServer {
           resourceInfo,
           "No matching payment requirements",
           routeConfig.extensions,
+          transportContext,
         );
         return {
           type: "payment-error",
@@ -492,6 +505,7 @@ export class x402HTTPResourceServer {
           resourceInfo,
           verifyResult.invalidReason,
           routeConfig.extensions,
+          transportContext,
         );
         return {
           type: "payment-error",
@@ -512,6 +526,7 @@ export class x402HTTPResourceServer {
         resourceInfo,
         error instanceof Error ? error.message : "Payment verification failed",
         routeConfig.extensions,
+        transportContext,
       );
       return {
         type: "payment-error",
@@ -526,18 +541,21 @@ export class x402HTTPResourceServer {
    * @param paymentPayload - The verified payment payload
    * @param requirements - The matching payment requirements
    * @param declaredExtensions - Optional declared extensions (for per-key enrichment)
+   * @param transportContext - Optional HTTP transport context
    * @returns ProcessSettleResultResponse - SettleResponse with headers if success or errorReason if failure
    */
   async processSettlement(
     paymentPayload: PaymentPayload,
     requirements: PaymentRequirements,
     declaredExtensions?: Record<string, unknown>,
+    transportContext?: HTTPTransportContext,
   ): Promise<ProcessSettleResultResponse> {
     try {
       const settleResponse = await this.ResourceServer.settlePayment(
         paymentPayload,
         requirements,
         declaredExtensions,
+        transportContext,
       );
 
       if (!settleResponse.success) {

typescript/packages/core/src/server/index.ts

@@ -7,6 +7,7 @@ export type { FacilitatorClient, FacilitatorConfig } from "../http/httpFacilitat
 export { x402HTTPResourceServer, RouteConfigurationError } from "../http/x402HTTPResourceServer";
 export type {
   HTTPRequestContext,
+  HTTPTransportContext,
   HTTPResponseInstructions,
   HTTPProcessResult,
   PaywallConfig,

typescript/packages/core/src/server/x402ResourceServer.ts

@@ -43,6 +43,7 @@ export interface PaymentRequiredContext {
   resourceInfo: ResourceInfo;
   error?: string;
   paymentRequiredResponse: PaymentRequired;
+  transportContext?: unknown;
 }
 
 export interface VerifyContext {
@@ -65,6 +66,7 @@ export interface SettleContext {
 
 export interface SettleResultContext extends SettleContext {
   result: SettleResponse;
+  transportContext?: unknown;
 }
 
 export interface SettleFailureContext extends SettleContext {
@@ -523,13 +525,15 @@ export class x402ResourceServer {
    * @param resourceInfo - Resource information
    * @param error - Error message
    * @param extensions - Optional declared extensions (for per-key enrichment)
+   * @param transportContext - Optional transport-specific context (e.g., HTTP request, MCP tool context)
    * @returns Payment required response object
    */
   async createPaymentRequiredResponse(
     requirements: PaymentRequirements[],
     resourceInfo: ResourceInfo,
     error?: string,
     extensions?: Record<string, unknown>,
+    transportContext?: unknown,
   ): Promise<PaymentRequired> {
     // V2 response with resource at top level
     let response: PaymentRequired = {
@@ -555,6 +559,7 @@ export class x402ResourceServer {
               resourceInfo,
               error,
               paymentRequiredResponse: response,
+              transportContext,
             };
             const extensionData = await extension.enrichPaymentRequiredResponse(
               declaration,
@@ -686,12 +691,14 @@ export class x402ResourceServer {
    * @param paymentPayload - The payment payload to settle
    * @param requirements - The payment requirements
    * @param declaredExtensions - Optional declared extensions (for per-key enrichment)
+   * @param transportContext - Optional transport-specific context (e.g., HTTP request/response, MCP tool context)
    * @returns Settlement response
    */
   async settlePayment(
     paymentPayload: PaymentPayload,
     requirements: PaymentRequirements,
     declaredExtensions?: Record<string, unknown>,
+    transportContext?: unknown,
   ): Promise<SettleResponse> {
     const context: SettleContext = {
       paymentPayload,
@@ -762,6 +769,7 @@ export class x402ResourceServer {
       const resultContext: SettleResultContext = {
         ...context,
         result: settleResult,
+        transportContext,
       };
 
       for (const hook of this.afterSettleHooks) {

typescript/packages/core/src/types/extensions.ts

@@ -18,7 +18,7 @@ export interface ResourceServerExtension {
    * Return extension data to add to extensions[key], or undefined to skip.
    *
    * @param declaration - Extension declaration from route config
-   * @param context - PaymentRequired context containing response and requirements
+   * @param context - PaymentRequired context containing response, requirements, and optional transportContext
    * @returns Extension data to add to response.extensions[key]
    */
   enrichPaymentRequiredResponse?: (
@@ -30,7 +30,7 @@ export interface ResourceServerExtension {
    * Return extension data to add to response.extensions[key], or undefined to skip.
    *
    * @param declaration - Extension declaration from route config
-   * @param context - Settlement result context containing payment payload, requirements, and result
+   * @param context - Settlement result context containing payment payload, requirements, result and optional transportContext
    * @returns Extension data to add to response.extensions[key]
    */
   enrichSettlementResponse?: (