@nevermined-io/payments 1.6.0 → 1.8.0

package/dist/a2a/paymentsRequestHandler.js

@@ -3,7 +3,8 @@ import { v4 as uuidv4 } from 'uuid';
 import { PaymentsError } from '../common/payments.error.js';
 import { isValidScheme } from '../common/types.js';
 import { decodeAccessToken } from '../utils.js';
-import { buildPaymentRequired } from '../x402/facilitator-api.js';
+import { buildPaymentRequired, } from '../x402/facilitator-api.js';
+import { x402A2AUtils } from './x402-a2a.js';
 const terminalStates = ['completed', 'failed', 'canceled', 'rejected'];
 /**
  * PaymentsRequestHandler extends DefaultRequestHandler to add payments validation and burning.
@@ -109,7 +110,9 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
             throw PaymentsError.unauthorized('Cannot determine subscriberAddress from token (expected payload.authorization.from)');
         }
         const agentId = paymentExtension?.params?.agentId;
-        const scheme = isValidScheme(decodedAccessToken.accepted?.scheme) ? decodedAccessToken.accepted.scheme : 'nvm:erc4337';
+        const scheme = isValidScheme(decodedAccessToken.accepted?.scheme)
+            ? decodedAccessToken.accepted.scheme
+            : 'nvm:erc4337';
         const paymentRequired = buildPaymentRequired(planId, {
             endpoint: endpoint || '',
             agentId,
@@ -172,7 +175,9 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
         if (!planId) {
             throw PaymentsError.unauthorized('Plan ID not found in agent card.');
         }
-        const scheme = isValidScheme(decodedAccessToken.accepted?.scheme) ? decodedAccessToken.accepted.scheme : 'nvm:erc4337';
+        const scheme = isValidScheme(decodedAccessToken.accepted?.scheme)
+            ? decodedAccessToken.accepted.scheme
+            : 'nvm:erc4337';
         // Build paymentRequired using the helper
         const paymentRequired = buildPaymentRequired(planId, {
             endpoint: httpContext?.urlRequested,
@@ -217,11 +222,17 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
         if (!httpContext) {
             throw A2AError.internalError('HTTP context not found for task or message.');
         }
-        // 2. Extract bearer token and validate presence of required fields
+        // 2. Extract bearer token and validate presence of required fields.
+        // This path only runs for an *authorized* context (a token was supplied), so
+        // both bearerToken and validation must be present — assert the invariant
+        // explicitly instead of carrying an `undefined as any`.
         const { bearerToken, validation } = httpContext;
         if (!bearerToken) {
             throw PaymentsError.unauthorized('Missing bearer token for payment validation.');
         }
+        if (!validation) {
+            throw PaymentsError.unauthorized('Missing validation context for payment.');
+        }
         // 3. Validate credits before executing the task
         const agentCard = await this.getAgentCard();
         const agentId = agentCard.capabilities?.extensions?.find((ext) => ext.uri === 'urn:nevermined:payment')?.params?.agentId;
@@ -271,6 +282,85 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
             resultManager,
         };
     }
+    /**
+     * x402 v2 A2A transport: if the request is payment-gated and arrived with no
+     * token (the middleware stored a `paymentRequired` on the HTTP context), build
+     * and return the spec-shaped `input-required` task carrying the
+     * X402PaymentRequired object under `x402.payment.required` — WITHOUT executing
+     * the agent. Returns `undefined` when a token was present (normal flow).
+     *
+     * @param params - The incoming message send parameters
+     * @returns The `input-required` Task to return to the client, or `undefined`
+     */
+    async buildPaymentRequiredTaskIfNeeded(params) {
+        const message = params.message;
+        if (!message) {
+            return undefined;
+        }
+        const incomingTaskId = message.taskId;
+        const httpContext = incomingTaskId
+            ? this.getHttpRequestContextForTask(incomingTaskId)
+            : this.getHttpRequestContextForMessage(message.messageId);
+        if (!httpContext?.paymentRequired) {
+            return undefined;
+        }
+        // Correlate the input-required task with the incoming taskId when present so
+        // the client's follow-up payment payload (same taskId) maps back to it.
+        const taskId = incomingTaskId || uuidv4();
+        const contextId = message.contextId || uuidv4();
+        const task = {
+            kind: 'task',
+            id: taskId,
+            contextId,
+            status: { state: 'submitted', timestamp: new Date().toISOString() },
+            history: [message],
+        };
+        const paymentRequiredTask = x402A2AUtils.createPaymentRequiredTask(task, httpContext.paymentRequired);
+        // Persist the input-required task so the client's follow-up (same taskId)
+        // can correlate to it (otherwise the SDK's _createRequestContext raises
+        // "Task not found"). The follow-up carries the in-band payload, so the
+        // middleware overwrites this taskId's HTTP context with the authorized one.
+        await this.getTaskStore().save(paymentRequiredTask);
+        if (!incomingTaskId) {
+            this.deleteHttpRequestContextForMessage(message.messageId);
+        }
+        return paymentRequiredTask;
+    }
+    /**
+     * Stamp x402 settlement state onto the final task's metadata, in band, per the
+     * x402 v2 A2A transport. Only applied when the token arrived in band (so the
+     * legacy `payment-signature` header path is unchanged). On success the task
+     * carries `x402.payment.status: payment-completed` + `x402.payment.receipts`;
+     * on failure `payment-failed` + `x402.payment.error` + receipts.
+     *
+     * @param task - The current task (mutated in place)
+     * @param httpContext - The request's HTTP context
+     * @param settlement - The settlement result, or undefined when none ran
+     */
+    recordInBandSettlement(task, httpContext, settlement, settlementDeferred = false) {
+        if (!task || !httpContext?.inBand) {
+            return;
+        }
+        if (settlement && settlement.success === false) {
+            x402A2AUtils.recordPaymentFailure(task, settlement.errorReason || 'SETTLEMENT_FAILED', settlement);
+        }
+        else if (settlement) {
+            x402A2AUtils.recordPaymentSuccess(task, settlement);
+        }
+        else if (settlementDeferred) {
+            // No in-band settlement result because redemption is BATCHED: the payload was
+            // verified but on-chain settlement is deferred out-of-band (this handler never
+            // confirms it). Mark payment-verified + the deferred marker, NOT
+            // payment-completed — so the client knows it will be charged out-of-band
+            // rather than reading a completed task as "nothing owed".
+            x402A2AUtils.recordPaymentDeferred(task);
+        }
+        else {
+            // Defensive default: verified, but no settlement result AND not batch-deferred
+            // (e.g. a settle that returned nothing). Record a bare verify.
+            x402A2AUtils.recordPaymentVerified(task);
+        }
+    }
     /**
      * Processes streaming events with finalization (credits burning and push notifications).
      * Similar to processEventsWithFinalization but yields events for streaming.
@@ -281,7 +371,7 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
      * @param validation - The validation result
      * @returns Async generator yielding processed events
      */
-    async *processStreamingEventsWithFinalization(taskId, resultManager, eventQueue, bearerToken) {
+    async *processStreamingEventsWithFinalization(taskId, resultManager, eventQueue, bearerToken, requestHttpContext) {
         try {
             for await (const event of eventQueue.events()) {
                 await resultManager.processEvent(event);
@@ -298,21 +388,75 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
                         // Get redemption configuration from server (not from client metadata)
                         const redemptionConfig = await this.getRedemptionConfig();
                         if (!redemptionConfig.useBatch) {
-                            // Get HTTP context if available
-                            const httpContext = this.getHttpRequestContextForTask(event.taskId);
+                            // Prefer the per-request context (authoritative in-band flag); fall
+                            // back to a per-taskId lookup for executors that mint their own task id.
+                            const httpContext = requestHttpContext ?? this.getHttpRequestContextForTask(event.taskId);
                             // Execute redemption with server configuration for non-batch requests
                             const response = await this.executeRedemption(bearerToken, BigInt(event.metadata.creditsUsed), httpContext);
                             // Update event metadata with response data
                             if (response && event.metadata) {
-                                event.metadata.txHash = response.txHash;
+                                event.metadata.txHash = response.txHash ?? response.transaction;
                                 event.metadata.creditsCharged = response.amountOfCredits
                                     ? Number(response.amountOfCredits)
                                     : event.metadata.creditsUsed;
                             }
+                            // x402 v2 A2A transport: stamp the settlement receipt onto the
+                            // persisted task in band. NOTE: a stream cannot retract the event
+                            // it already yielded above, so an in-band settlement is reflected
+                            // on the saved task (visible via tasks/get + resubscribe) — it
+                            // cannot withhold content the way a non-streaming result does.
+                            if (httpContext?.inBand) {
+                                const task = resultManager.getCurrentTask();
+                                if (task) {
+                                    this.recordInBandSettlement(task, httpContext, response);
+                                    await resultManager.processEvent(task);
+                                }
+                            }
+                        }
+                        else {
+                            // Batch redemption: on-chain settlement is deferred out-of-band. The
+                            // stream already yielded the content (can't retract), but stamp the
+                            // PERSISTED task with payment-verified + the deferred marker so a
+                            // streaming client (via tasks/get + resubscribe) isn't left reading a
+                            // completed task as "nothing owed" — matching the non-streaming path.
+                            const httpContext = requestHttpContext ?? this.getHttpRequestContextForTask(event.taskId);
+                            if (httpContext?.inBand) {
+                                const task = resultManager.getCurrentTask();
+                                if (task) {
+                                    this.recordInBandSettlement(task, httpContext, undefined, true);
+                                    await resultManager.processEvent(task);
+                                }
+                            }
                         }
                     }
                     catch (err) {
-                        // Do nothing
+                        // x402 v2 A2A: settlement failed AFTER the paid event was already
+                        // streamed to the client (a stream cannot retract it). Do NOT swallow
+                        // it — log, and stamp payment-failed on the persisted task so
+                        // tasks/get + resubscribe reflect the failure (mirrors non-streaming).
+                        console.error('[PaymentsA2A] streaming settlement failed after execution:', err);
+                        const httpContext = requestHttpContext ?? this.getHttpRequestContextForTask(event.taskId);
+                        if (httpContext?.inBand) {
+                            try {
+                                const task = resultManager.getCurrentTask();
+                                if (task) {
+                                    const errorReason = err instanceof Error ? err.message : String(err);
+                                    if (task.status)
+                                        task.status.state = 'failed';
+                                    task.artifacts = undefined;
+                                    this.recordInBandSettlement(task, httpContext, {
+                                        success: false,
+                                        errorReason,
+                                        transaction: '',
+                                        network: '',
+                                    });
+                                    await resultManager.processEvent(task);
+                                }
+                            }
+                            catch (stampErr) {
+                                console.error('[PaymentsA2A] failed to stamp streaming payment-failed:', stampErr);
+                            }
+                        }
                     }
                 }
                 // Handle push notification
@@ -345,7 +489,7 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
      * Processes all events, calling handleTaskFinalization when a terminal status-update event is received.
      * In async mode, it can be launched in background.
      */
-    async processEventsWithFinalization(taskId, resultManager, eventQueue, bearerToken, validation, options) {
+    async processEventsWithFinalization(taskId, resultManager, eventQueue, bearerToken, validation, options, requestHttpContext) {
         let firstResultSent = false;
         try {
             for await (const event of eventQueue.events()) {
@@ -353,8 +497,11 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
                 if (event.kind === 'status-update' &&
                     event.final &&
                     terminalStates.includes(event.status?.state)) {
-                    // Get HTTP context if available
-                    const httpContext = this.getHttpRequestContextForTask(event.taskId);
+                    // Prefer the per-request HTTP context (authoritative for this request,
+                    // carries the in-band flag). Fall back to a per-taskId lookup for
+                    // executors that mint their own task id (the event's taskId may then
+                    // differ from the request's generated one).
+                    const httpContext = requestHttpContext ?? this.getHttpRequestContextForTask(event.taskId);
                     await this.handleTaskFinalization(resultManager, event, bearerToken, httpContext);
                 }
                 await resultManager.processEvent(event);
@@ -387,8 +534,14 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
      * @returns The resulting message or task
      */
     async sendMessage(params) {
+        // x402 v2 A2A transport: a payment-gated request with no token returns an
+        // `input-required` task (in band) instead of executing the agent.
+        const paymentRequiredTask = await this.buildPaymentRequiredTaskIfNeeded(params);
+        if (paymentRequiredTask) {
+            return paymentRequiredTask;
+        }
         // Create PaymentsRequestContext and related data
-        const { paymentsRequestContext, taskId, bearerToken, validation, requestContext, finalMessageForAgent, eventBus, eventQueue, resultManager, } = await this.createPaymentsRequestContext(params, false);
+        const { paymentsRequestContext, taskId, httpContext, bearerToken, validation, requestContext, finalMessageForAgent, eventBus, eventQueue, resultManager, } = await this.createPaymentsRequestContext(params, false);
         this.agentExecutor
             .execute(paymentsRequestContext, eventBus)
             .catch((err) => {
@@ -429,7 +582,7 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
         // The blocking parameter comes from params.configuration.blocking
         const isBlocking = params.configuration?.blocking !== false; // Default to blocking if not specified
         if (isBlocking) {
-            await this.processEventsWithFinalization(taskId, resultManager, eventQueue, bearerToken, validation);
+            await this.processEventsWithFinalization(taskId, resultManager, eventQueue, bearerToken, validation, undefined, httpContext);
             const finalResult = resultManager.getFinalResult();
             if (!finalResult) {
                 throw A2AError.internalError('Agent execution finished without a result, and no task context found.');
@@ -446,7 +599,7 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
                 this.processEventsWithFinalization(validTaskId, resultManager, eventQueue, bearerToken, validation, {
                     firstResultResolver: resolve,
                     firstResultRejector: reject,
-                });
+                }, httpContext);
             });
         }
     }
@@ -467,37 +620,97 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
             (typeof creditsToBurn === 'string' ||
                 typeof creditsToBurn === 'number' ||
                 typeof creditsToBurn === 'bigint')) {
+            let settlement;
+            let settlementError;
+            let settlementDeferred = false;
             try {
                 // Get redemption configuration from server (not from client metadata)
                 const redemptionConfig = await this.getRedemptionConfig();
+                // Batch redemption defers on-chain settlement out-of-band (no receipt here).
+                settlementDeferred = redemptionConfig.useBatch ?? false;
                 if (!redemptionConfig.useBatch) {
                     // Execute redemption with server configuration for non-batch requests
                     const response = await this.executeRedemption(bearerToken, BigInt(creditsToBurn), httpContext);
+                    settlement = response;
                     // Update event metadata with redemption results
                     event.metadata = {
                         ...event.metadata,
-                        txHash: response.txHash,
+                        txHash: response.txHash ?? response.transaction,
                         // Store the actual credits charged (especially important for margin-based)
                         creditsCharged: response.amountOfCredits
                             ? Number(response.amountOfCredits)
                             : creditsToBurn,
                     };
                 }
+            }
+            catch (err) {
+                // Settlement failed AFTER the agent executed. Always log it (the legacy
+                // header path has no other surface for it). For the in-band x402 v2 A2A
+                // path it is additionally surfaced below as payment-failed + suppressed
+                // content; the legacy header path still delivers the result (no retract).
+                console.error('[PaymentsA2A] settlement failed after execution:', err);
+                settlementError = err;
+            }
+            // Stamp the in-band x402 state onto the FINAL event so it survives when the
+            // caller processes this event into the task's status (mutating the task
+            // here would be overwritten by the final event). The event carries a Task
+            // shape under `event.status`; the helpers mutate `event.status.message`.
+            if (httpContext?.inBand && settlementError) {
+                // x402 v2 A2A transport: a settlement failure after execution must NOT
+                // deliver paid content — replace the agent's status message with a
+                // failed one carrying payment-failed metadata + an error receipt.
+                const errorReason = settlementError instanceof Error ? settlementError.message : String(settlementError);
+                event.status = {
+                    state: 'failed',
+                    message: {
+                        kind: 'message',
+                        messageId: uuidv4(),
+                        role: 'agent',
+                        parts: [{ kind: 'text', text: `Payment settlement failed: ${errorReason}` }],
+                        taskId: event.taskId,
+                        contextId: event.contextId,
+                        metadata: {},
+                    },
+                    timestamp: new Date().toISOString(),
+                };
+                this.recordInBandSettlement({ status: event.status }, httpContext, {
+                    success: false,
+                    errorReason,
+                    transaction: '',
+                    network: settlement?.network || '',
+                });
+            }
+            else if (httpContext?.inBand) {
+                // Stamp in-band settlement state onto the final event's status message.
+                this.recordInBandSettlement({ status: event.status }, httpContext, settlement, settlementDeferred);
+            }
+            try {
                 // Always update task metadata and process the task
                 const task = resultManager.getCurrentTask();
                 if (task) {
-                    // Update task metadata with current event metadata (from executor or redemption)
+                    // Update task metadata with current event metadata (executor / redemption).
                     task.metadata = {
                         ...task.metadata,
                         ...event.metadata,
                     };
+                    if (httpContext?.inBand && settlementError) {
+                        // x402 v2 A2A transport: a settlement failure must never deliver paid
+                        // content. The agent's status message was already replaced above; also
+                        // drop any artifacts it emitted so the paid result cannot surface there
+                        // (mirrors the Python SDK's _apply_inband_settlement). History is rebuilt
+                        // by processEvent below from the replaced (failed) status, so it carries
+                        // no paid content.
+                        task.artifacts = undefined;
+                    }
                     await resultManager.processEvent(task);
                     // Delete http context associated with the task
                     this.deleteHttpRequestContextForTask(event.taskId);
                 }
             }
             catch (err) {
-                // Do nothing
+                // This block persists the payment-failed/suppressed task; if it throws the
+                // suppression itself failed, so log loudly rather than swallow.
+                console.error('[PaymentsA2A] failed to persist finalized task:', err);
             }
         }
         try {
@@ -519,8 +732,15 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
      * @returns Async generator of events
      */
     async *sendMessageStream(params) {
+        // x402 v2 A2A transport: a payment-gated request with no token yields a
+        // single `input-required` task (in band) instead of executing the agent.
+        const paymentRequiredTask = await this.buildPaymentRequiredTaskIfNeeded(params);
+        if (paymentRequiredTask) {
+            yield paymentRequiredTask;
+            return;
+        }
         // Create PaymentsRequestContext and related data
-        const { paymentsRequestContext, taskId, bearerToken, requestContext, finalMessageForAgent, eventBus, eventQueue, resultManager, } = await this.createPaymentsRequestContext(params, true);
+        const { paymentsRequestContext, taskId, httpContext, bearerToken, requestContext, finalMessageForAgent, eventBus, eventQueue, resultManager, } = await this.createPaymentsRequestContext(params, true);
         this.agentExecutor
             .execute(paymentsRequestContext, eventBus)
             .catch((err) => {
@@ -547,7 +767,7 @@ export class PaymentsRequestHandler extends DefaultRequestHandler {
             eventBus.publish(errorTaskStatus);
         });
         // Process streaming events with finalization
-        yield* this.processStreamingEventsWithFinalization(taskId, resultManager, eventQueue, bearerToken);
+        yield* this.processStreamingEventsWithFinalization(taskId, resultManager, eventQueue, bearerToken, httpContext);
     }
     /**
      * Sends a push notification when a task reaches a terminal state.