@nevermined-io/payments 1.0.0-rc0 → 1.0.0-rc2

package/dist/a2a/paymentsRequestHandler.js

@@ -0,0 +1,333 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentsRequestHandler = void 0;
+const uuid_1 = require("uuid");
+const sdk_1 = require("@a2a-js/sdk");
+const payments_error_1 = require("../common/payments.error");
+const terminalStates = ['completed', 'failed', 'canceled', 'rejected'];
+/**
+ * PaymentsRequestHandler extends DefaultRequestHandler to add payments validation and burning.
+ * It validates credits before executing a task and burns credits after successful execution.
+ * It also sends push notifications when a task reaches a terminal state.
+ */
+class PaymentsRequestHandler extends sdk_1.DefaultRequestHandler {
+    /**
+     * Store HTTP context temporarily by messageId (used in middleware when taskId is not yet available).
+     * @param messageId - The messageId from the incoming message
+     * @param ctx - The HTTP context (bearerToken, url, method)
+     */
+    setHttpRequestContextForMessage(messageId, ctx) {
+        this.httpContextByMessageId.set(messageId, ctx);
+    }
+    /**
+     * Store HTTP context by taskId (used in middleware when taskId is available).
+     * @param taskId - The taskId of the task
+     * @param ctx - The HTTP context (bearerToken, url, method)
+     */
+    setHttpRequestContextForTask(taskId, ctx) {
+        this.httpContextByTaskId.set(taskId, ctx);
+    }
+    /**
+     * @param agentCard - The agent card
+     * @param taskStore - The task store
+     * @param agentExecutor - The business logic executor
+     * @param paymentsService - The payments service for validation and burning
+     * @param eventBusManager - The event bus manager (optional)
+     */
+    constructor(agentCard, taskStore, agentExecutor, paymentsService, eventBusManager) {
+        super(agentCard, taskStore, agentExecutor, eventBusManager);
+        /**
+         * Map to store HTTP context by taskId.
+         */
+        this.httpContextByTaskId = new Map();
+        /**
+         * Map to store temporary HTTP context by messageId (before taskId is known).
+         */
+        this.httpContextByMessageId = new Map();
+        /**
+         * Set to track which tasks already have a finalization listener attached.
+         */
+        this.finalizedTasksWithListener = new Set();
+        this.paymentsService = paymentsService;
+    }
+    /**
+     * Retrieve the HTTP context for a given taskId.
+     * @param taskId - The taskId of the task
+     * @returns The HTTP context (bearerToken, url, method) or undefined
+     */
+    getHttpRequestContextForTask(taskId) {
+        return this.httpContextByTaskId.get(taskId);
+    }
+    /**
+     * Retrieve the HTTP context for a given messageId.
+     * @param messageId - The messageId of the message
+     * @returns The HTTP context (bearerToken, url, method) or undefined
+     */
+    getHttpRequestContextForMessage(messageId) {
+        return this.httpContextByMessageId.get(messageId);
+    }
+    /**
+     * Sends a message, validating credits before execution and burning credits after.
+     * Also sends a push notification if the task reaches a terminal state.
+     * @param params - Message send parameters
+     * @returns The resulting message or task
+     */
+    async sendMessage(params) {
+        const incomingMessage = params.message;
+        // 1. Get HTTP context for the task or message
+        const taskId = incomingMessage.taskId;
+        let httpContext;
+        if (taskId) {
+            httpContext = this.getHttpRequestContextForTask(taskId);
+        }
+        else {
+            const messageId = incomingMessage.messageId;
+            if (messageId) {
+                httpContext = this.getHttpRequestContextForMessage(messageId);
+            }
+        }
+        if (!httpContext) {
+            throw payments_error_1.PaymentsError.internal('HTTP context not found for task or message.');
+        }
+        // 2. Extract bearer token
+        const { bearerToken, urlRequested, httpMethodRequested } = httpContext;
+        if (!bearerToken || !urlRequested || !httpMethodRequested) {
+            throw payments_error_1.PaymentsError.unauthorized('Missing bearer token for payment validation.');
+        }
+        // 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;
+        if (!agentId) {
+            throw payments_error_1.PaymentsError.internal('Agent ID not found in payment extension.');
+        }
+        try {
+            const validation = await this.paymentsService.isValidRequest(agentId, bearerToken, urlRequested, httpMethodRequested);
+            if (!validation?.balance?.isSubscriber) {
+                throw payments_error_1.PaymentsError.paymentRequired('Insufficient credits or invalid request.');
+            }
+        }
+        catch (err) {
+            throw payments_error_1.PaymentsError.paymentRequired('Payment validation failed: ' + (err instanceof Error ? err.message : String(err)));
+        }
+        // 4. Call the base logic
+        const result = await super.sendMessage(params);
+        // 5. Only handle if result is a Task (not a Message)
+        if (result && result.kind === 'task') {
+            if (incomingMessage.messageId) {
+                this.migrateHttpRequestContextFromMessageToTask(incomingMessage.messageId, result.id);
+            }
+            const eventBus = this.getEventBusManager().createOrGetByTaskId(result.id);
+            if (!this.finalizedTasksWithListener.has(result.id)) {
+                this.finalizedTasksWithListener.add(result.id);
+                eventBus.on('event', (event) => {
+                    if (event.kind === 'status-update' && terminalStates.includes(event.status?.state)) {
+                        this.handleTaskFinalization(event, bearerToken);
+                    }
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Handles credits burning and push notification when a task reaches a terminal state.
+     * This is called asynchronously from the eventBus listener.
+     * @param event - The status-update event with final state
+     * @param bearerToken - The bearer token for payment validation
+     */
+    async handleTaskFinalization(event, bearerToken) {
+        const creditsToBurn = event.metadata?.creditsUsed;
+        if (creditsToBurn !== undefined &&
+            creditsToBurn !== null &&
+            bearerToken &&
+            (typeof creditsToBurn === 'string' ||
+                typeof creditsToBurn === 'number' ||
+                typeof creditsToBurn === 'bigint')) {
+            try {
+                await this.paymentsService.redeemCreditsFromRequest(bearerToken, BigInt(creditsToBurn));
+            }
+            catch (err) {
+                console.error('[Payments] Failed to redeem credits.', err);
+            }
+        }
+        try {
+            const taskPushNotificationConfig = await this.getTaskPushNotificationConfig({
+                id: event.taskId,
+            });
+            if (taskPushNotificationConfig) {
+                await this.sendPushNotification(event.taskId, event.status.state, taskPushNotificationConfig.pushNotificationConfig, { contextId: event.contextId });
+            }
+        }
+        catch (err) {
+            console.error('[PushNotification] Failed to send push notification.', err);
+        }
+    }
+    /**
+     * Streams messages and events for a task, with payments validation.
+     * Also sends a push notification if a terminal status-update event is emitted.
+     * @param params - Message send parameters
+     * @returns Async generator of events
+     */
+    async *sendMessageStream(params) {
+        // 0. Get HTTP context for the task or message
+        const taskId = params.message.taskId;
+        let httpContext;
+        if (taskId) {
+            httpContext = this.getHttpRequestContextForTask(taskId);
+        }
+        else {
+            const messageId = params.message.messageId;
+            if (messageId) {
+                httpContext = this.getHttpRequestContextForMessage(messageId);
+            }
+        }
+        if (!httpContext) {
+            throw payments_error_1.PaymentsError.internal('HTTP context not found for task or message.');
+        }
+        const { bearerToken, urlRequested, httpMethodRequested } = httpContext;
+        if (!bearerToken) {
+            throw payments_error_1.PaymentsError.unauthorized('Missing bearer token for payment validation.');
+        }
+        const agentCard = await this.getAgentCard();
+        const agentId = agentCard.capabilities?.extensions?.find((ext) => ext.uri === 'urn:nevermined:payment')?.params?.agentId;
+        if (!agentId) {
+            throw payments_error_1.PaymentsError.internal('Agent ID not found in payment extension.');
+        }
+        try {
+            const validation = await this.paymentsService.isValidRequest(agentId, bearerToken, urlRequested, httpMethodRequested);
+            if (!validation?.balance?.isSubscriber) {
+                throw payments_error_1.PaymentsError.paymentRequired('Insufficient credits or invalid request.');
+            }
+        }
+        catch (err) {
+            throw payments_error_1.PaymentsError.paymentRequired('Payment validation failed: ' + (err instanceof Error ? err.message : String(err)));
+        }
+        // 4. Create the task if it does not exist yet
+        // If params.message.taskId is not present, create and store a new Task
+        if (!params.message.taskId) {
+            const newTaskId = (0, uuid_1.v4)();
+            const newContextId = params.message.contextId || (0, uuid_1.v4)();
+            const newTask = {
+                kind: 'task',
+                id: newTaskId,
+                contextId: newContextId,
+                status: {
+                    state: 'submitted',
+                    timestamp: new Date().toISOString(),
+                },
+                history: [params.message],
+                metadata: params.message.metadata,
+                artifacts: [],
+            };
+            // Store the new task in the taskStore
+            await this.getTaskStore().save(newTask);
+            // Update the params.message with the new taskId and contextId
+            params.message.taskId = newTaskId;
+            params.message.contextId = newContextId;
+        }
+        // Call the base stream logic
+        const stream = super.sendMessageStream(params);
+        for await (const event of stream) {
+            // 1. Handle credits burning
+            if (event.kind === 'status-update' &&
+                event.final &&
+                event?.metadata?.creditsUsed !== undefined &&
+                event?.metadata?.creditsUsed !== null &&
+                bearerToken &&
+                (typeof event.metadata.creditsUsed === 'string' ||
+                    typeof event.metadata.creditsUsed === 'number' ||
+                    typeof event.metadata.creditsUsed === 'bigint')) {
+                try {
+                    await this.paymentsService.redeemCreditsFromRequest(bearerToken, BigInt(event.metadata.creditsUsed));
+                }
+                catch (err) {
+                    console.error('[Payments] Failed to redeem credits.', err);
+                }
+            }
+            // 2. Handle push notification
+            if (event.kind === 'status-update' &&
+                event.final &&
+                event.status?.state &&
+                terminalStates.includes(event.status.state)) {
+                try {
+                    const taskPushNotificationConfig = await this.getTaskPushNotificationConfig({
+                        id: event.taskId,
+                    });
+                    if (taskPushNotificationConfig) {
+                        await this.sendPushNotification(event.taskId, event.status.state, taskPushNotificationConfig.pushNotificationConfig, {
+                            contextId: event.contextId,
+                        });
+                    }
+                }
+                catch (err) {
+                    console.error('[PushNotification] Failed to send push notification.', err);
+                }
+            }
+            yield event;
+        }
+    }
+    async sendPushNotification(taskId, state, pushNotificationConfig, payload = {}) {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (pushNotificationConfig.authentication) {
+            if (pushNotificationConfig.authentication.schemes.includes('basic')) {
+                const basic = Buffer.from(`${pushNotificationConfig.authentication.credentials}`).toString('base64');
+                headers['Authorization'] = `Basic ${basic}`;
+            }
+            else if (pushNotificationConfig.authentication.schemes.includes('bearer')) {
+                headers['Authorization'] = `Bearer ${pushNotificationConfig.authentication.credentials}`;
+            }
+            else if (pushNotificationConfig.authentication.schemes.includes('custom')) {
+                Object.assign(headers, pushNotificationConfig.authentication.credentials);
+            }
+        }
+        const body = JSON.stringify({
+            taskId,
+            state,
+            payload,
+        });
+        const response = await fetch(pushNotificationConfig.url, {
+            method: 'POST',
+            headers,
+            body,
+        });
+        if (!response.ok) {
+            throw payments_error_1.PaymentsError.internal('Failed to send push notification.');
+        }
+    }
+    /**
+     * Migrates the HTTP context from a messageId to a taskId and deletes the temporary messageId context.
+     * @param messageId - The messageId to migrate from
+     * @param taskId - The taskId to migrate to
+     */
+    migrateHttpRequestContextFromMessageToTask(messageId, taskId) {
+        const ctx = this.getHttpRequestContextForMessage(messageId);
+        if (ctx) {
+            this.setHttpRequestContextForTask(taskId, ctx);
+            this.deleteHttpRequestContextForMessage(messageId);
+        }
+    }
+    /**
+     * Deletes the HTTP context associated with a messageId.
+     * @param messageId - The messageId to delete context for
+     */
+    deleteHttpRequestContextForMessage(messageId) {
+        this.httpContextByMessageId.delete(messageId);
+    }
+    /**
+     * Protected getter to access the private taskStore property from the parent class.
+     * This is a workaround due to SDK limitations.
+     */
+    getTaskStore() {
+        return this.taskStore;
+    }
+    /**
+     * Protected getter to access the private eventBusManager property from the parent class.
+     * This is a workaround due to SDK limitations.
+     */
+    getEventBusManager() {
+        return this.eventBusManager;
+    }
+}
+exports.PaymentsRequestHandler = PaymentsRequestHandler;
+//# sourceMappingURL=paymentsRequestHandler.js.map

package/dist/a2a/paymentsRequestHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paymentsRequestHandler.js","sourceRoot":"","sources":["../../src/a2a/paymentsRequestHandler.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  AgentCard,\n  MessageSendParams,\n  TaskState,\n  ExecutionEventBusManager,\n  TaskStore,\n  PushNotificationConfig,\n  TaskStatusUpdateEvent,\n  Task,\n} from '@a2a-js/sdk'\nimport { v4 as uuidv4 } from 'uuid'\nimport { AgentExecutor, DefaultRequestHandler } from '@a2a-js/sdk'\nimport { PaymentsError } from '../common/payments.error'\nimport { AgentExecutionEvent } from '@a2a-js/sdk/build/src/server/events/execution_event_bus'\n\nconst terminalStates: TaskState[] = ['completed', 'failed', 'canceled', 'rejected']\n\n/**\n * HTTP context associated with a task or message.\n */\ntype HttpRequestContext = {\n  bearerToken?: string\n  urlRequested?: string\n  httpMethodRequested?: string\n}\n\n/**\n * PaymentsRequestHandler extends DefaultRequestHandler to add payments validation and burning.\n * It validates credits before executing a task and burns credits after successful execution.\n * It also sends push notifications when a task reaches a terminal state.\n */\nexport class PaymentsRequestHandler extends DefaultRequestHandler {\n  private paymentsService: any\n\n  /**\n   * Map to store HTTP context by taskId.\n   */\n  private httpContextByTaskId: Map<string, HttpRequestContext> = new Map()\n\n  /**\n   * Map to store temporary HTTP context by messageId (before taskId is known).\n   */\n  private httpContextByMessageId: Map<string, HttpRequestContext> = new Map()\n\n  /**\n   * Set to track which tasks already have a finalization listener attached.\n   */\n  private finalizedTasksWithListener: Set<string> = new Set()\n\n  /**\n   * Store HTTP context temporarily by messageId (used in middleware when taskId is not yet available).\n   * @param messageId - The messageId from the incoming message\n   * @param ctx - The HTTP context (bearerToken, url, method)\n   */\n  public setHttpRequestContextForMessage(messageId: string, ctx: HttpRequestContext) {\n    this.httpContextByMessageId.set(messageId, ctx)\n  }\n\n  /**\n   * Store HTTP context by taskId (used in middleware when taskId is available).\n   * @param taskId - The taskId of the task\n   * @param ctx - The HTTP context (bearerToken, url, method)\n   */\n  public setHttpRequestContextForTask(taskId: string, ctx: HttpRequestContext) {\n    this.httpContextByTaskId.set(taskId, ctx)\n  }\n\n  /**\n   * @param agentCard - The agent card\n   * @param taskStore - The task store\n   * @param agentExecutor - The business logic executor\n   * @param paymentsService - The payments service for validation and burning\n   * @param eventBusManager - The event bus manager (optional)\n   */\n  constructor(\n    agentCard: AgentCard,\n    taskStore: TaskStore,\n    agentExecutor: AgentExecutor,\n    paymentsService: any,\n    eventBusManager?: ExecutionEventBusManager,\n  ) {\n    super(agentCard, taskStore, agentExecutor, eventBusManager)\n    this.paymentsService = paymentsService\n  }\n\n  /**\n   * Retrieve the HTTP context for a given taskId.\n   * @param taskId - The taskId of the task\n   * @returns The HTTP context (bearerToken, url, method) or undefined\n   */\n  private getHttpRequestContextForTask(taskId: string): HttpRequestContext | undefined {\n    return this.httpContextByTaskId.get(taskId)\n  }\n\n  /**\n   * Retrieve the HTTP context for a given messageId.\n   * @param messageId - The messageId of the message\n   * @returns The HTTP context (bearerToken, url, method) or undefined\n   */\n  private getHttpRequestContextForMessage(messageId: string): HttpRequestContext | undefined {\n    return this.httpContextByMessageId.get(messageId)\n  }\n\n  /**\n   * Sends a message, validating credits before execution and burning credits after.\n   * Also sends a push notification if the task reaches a terminal state.\n   * @param params - Message send parameters\n   * @returns The resulting message or task\n   */\n  async sendMessage(params: MessageSendParams) {\n    const incomingMessage = params.message\n\n    // 1. Get HTTP context for the task or message\n    const taskId = incomingMessage.taskId\n    let httpContext: HttpRequestContext | undefined\n    if (taskId) {\n      httpContext = this.getHttpRequestContextForTask(taskId)\n    } else {\n      const messageId = incomingMessage.messageId\n      if (messageId) {\n        httpContext = this.getHttpRequestContextForMessage(messageId)\n      }\n    }\n\n    if (!httpContext) {\n      throw PaymentsError.internal('HTTP context not found for task or message.')\n    }\n\n    // 2. Extract bearer token\n    const { bearerToken, urlRequested, httpMethodRequested } = httpContext\n    if (!bearerToken || !urlRequested || !httpMethodRequested) {\n      throw PaymentsError.unauthorized('Missing bearer token for payment validation.')\n    }\n    // 3. Validate credits before executing the task\n    const agentCard = await this.getAgentCard()\n    const agentId = agentCard.capabilities?.extensions?.find(\n      (ext) => ext.uri === 'urn:nevermined:payment',\n    )?.params?.agentId\n    if (!agentId) {\n      throw PaymentsError.internal('Agent ID not found in payment extension.')\n    }\n    try {\n      const validation = await this.paymentsService.isValidRequest(\n        agentId,\n        bearerToken,\n        urlRequested,\n        httpMethodRequested,\n      )\n      if (!validation?.balance?.isSubscriber) {\n        throw PaymentsError.paymentRequired('Insufficient credits or invalid request.')\n      }\n    } catch (err) {\n      throw PaymentsError.paymentRequired(\n        'Payment validation failed: ' + (err instanceof Error ? err.message : String(err)),\n      )\n    }\n\n    // 4. Call the base logic\n    const result = await super.sendMessage(params)\n\n    // 5. Only handle if result is a Task (not a Message)\n    if (result && result.kind === 'task') {\n      if (incomingMessage.messageId) {\n        this.migrateHttpRequestContextFromMessageToTask(incomingMessage.messageId, result.id)\n      }\n      const eventBus = this.getEventBusManager().createOrGetByTaskId(result.id)\n      if (!this.finalizedTasksWithListener.has(result.id)) {\n        this.finalizedTasksWithListener.add(result.id)\n        eventBus.on('event', (event: AgentExecutionEvent) => {\n          if (event.kind === 'status-update' && terminalStates.includes(event.status?.state)) {\n            this.handleTaskFinalization(event, bearerToken)\n          }\n        })\n      }\n    }\n    return result\n  }\n\n  /**\n   * Handles credits burning and push notification when a task reaches a terminal state.\n   * This is called asynchronously from the eventBus listener.\n   * @param event - The status-update event with final state\n   * @param bearerToken - The bearer token for payment validation\n   */\n  private async handleTaskFinalization(event: TaskStatusUpdateEvent, bearerToken: string) {\n    const creditsToBurn = event.metadata?.creditsUsed\n    if (\n      creditsToBurn !== undefined &&\n      creditsToBurn !== null &&\n      bearerToken &&\n      (typeof creditsToBurn === 'string' ||\n        typeof creditsToBurn === 'number' ||\n        typeof creditsToBurn === 'bigint')\n    ) {\n      try {\n        await this.paymentsService.redeemCreditsFromRequest(bearerToken, BigInt(creditsToBurn))\n      } catch (err) {\n        console.error('[Payments] Failed to redeem credits.', err)\n      }\n    }\n    try {\n      const taskPushNotificationConfig = await this.getTaskPushNotificationConfig({\n        id: event.taskId,\n      })\n      if (taskPushNotificationConfig) {\n        await this.sendPushNotification(\n          event.taskId,\n          event.status.state,\n          taskPushNotificationConfig.pushNotificationConfig,\n          { contextId: event.contextId },\n        )\n      }\n    } catch (err) {\n      console.error('[PushNotification] Failed to send push notification.', err)\n    }\n  }\n\n  /**\n   * Streams messages and events for a task, with payments validation.\n   * Also sends a push notification if a terminal status-update event is emitted.\n   * @param params - Message send parameters\n   * @returns Async generator of events\n   */\n  async *sendMessageStream(params: MessageSendParams) {\n    // 0. Get HTTP context for the task or message\n    const taskId = params.message.taskId\n    let httpContext: HttpRequestContext | undefined\n    if (taskId) {\n      httpContext = this.getHttpRequestContextForTask(taskId)\n    } else {\n      const messageId = params.message.messageId\n      if (messageId) {\n        httpContext = this.getHttpRequestContextForMessage(messageId)\n      }\n    }\n\n    if (!httpContext) {\n      throw PaymentsError.internal('HTTP context not found for task or message.')\n    }\n    const { bearerToken, urlRequested, httpMethodRequested } = httpContext\n    if (!bearerToken) {\n      throw PaymentsError.unauthorized('Missing bearer token for payment validation.')\n    }\n    const agentCard = await this.getAgentCard()\n    const agentId = agentCard.capabilities?.extensions?.find(\n      (ext) => ext.uri === 'urn:nevermined:payment',\n    )?.params?.agentId\n    if (!agentId) {\n      throw PaymentsError.internal('Agent ID not found in payment extension.')\n    }\n\n    try {\n      const validation = await this.paymentsService.isValidRequest(\n        agentId,\n        bearerToken,\n        urlRequested,\n        httpMethodRequested,\n      )\n      if (!validation?.balance?.isSubscriber) {\n        throw PaymentsError.paymentRequired('Insufficient credits or invalid request.')\n      }\n    } catch (err) {\n      throw PaymentsError.paymentRequired(\n        'Payment validation failed: ' + (err instanceof Error ? err.message : String(err)),\n      )\n    }\n\n    // 4. Create the task if it does not exist yet\n    // If params.message.taskId is not present, create and store a new Task\n    if (!params.message.taskId) {\n      const newTaskId = uuidv4()\n      const newContextId = params.message.contextId || uuidv4()\n      const newTask: Task = {\n        kind: 'task',\n        id: newTaskId,\n        contextId: newContextId,\n        status: {\n          state: 'submitted',\n          timestamp: new Date().toISOString(),\n        },\n        history: [params.message],\n        metadata: params.message.metadata,\n        artifacts: [],\n      }\n      // Store the new task in the taskStore\n      await this.getTaskStore().save(newTask)\n      // Update the params.message with the new taskId and contextId\n      params.message.taskId = newTaskId\n      params.message.contextId = newContextId\n    }\n\n    // Call the base stream logic\n    const stream = super.sendMessageStream(params)\n    for await (const event of stream) {\n      // 1. Handle credits burning\n      if (\n        event.kind === 'status-update' &&\n        event.final &&\n        event?.metadata?.creditsUsed !== undefined &&\n        event?.metadata?.creditsUsed !== null &&\n        bearerToken &&\n        (typeof event.metadata.creditsUsed === 'string' ||\n          typeof event.metadata.creditsUsed === 'number' ||\n          typeof event.metadata.creditsUsed === 'bigint')\n      ) {\n        try {\n          await this.paymentsService.redeemCreditsFromRequest(\n            bearerToken,\n            BigInt(event.metadata.creditsUsed),\n          )\n        } catch (err) {\n          console.error('[Payments] Failed to redeem credits.', err)\n        }\n      }\n      // 2. Handle push notification\n      if (\n        event.kind === 'status-update' &&\n        event.final &&\n        event.status?.state &&\n        terminalStates.includes(event.status.state)\n      ) {\n        try {\n          const taskPushNotificationConfig = await this.getTaskPushNotificationConfig({\n            id: event.taskId,\n          })\n          if (taskPushNotificationConfig) {\n            await this.sendPushNotification(\n              event.taskId,\n              event.status.state,\n              taskPushNotificationConfig.pushNotificationConfig,\n              {\n                contextId: event.contextId,\n              },\n            )\n          }\n        } catch (err) {\n          console.error('[PushNotification] Failed to send push notification.', err)\n        }\n      }\n      yield event\n    }\n  }\n\n  private async sendPushNotification(\n    taskId: string,\n    state: TaskState,\n    pushNotificationConfig: PushNotificationConfig,\n    payload: Record<string, any> = {},\n  ) {\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n    }\n    if (pushNotificationConfig.authentication) {\n      if (pushNotificationConfig.authentication.schemes.includes('basic')) {\n        const basic = Buffer.from(`${pushNotificationConfig.authentication.credentials}`).toString(\n          'base64',\n        )\n        headers['Authorization'] = `Basic ${basic}`\n      } else if (pushNotificationConfig.authentication.schemes.includes('bearer')) {\n        headers['Authorization'] = `Bearer ${pushNotificationConfig.authentication.credentials}`\n      } else if (pushNotificationConfig.authentication.schemes.includes('custom')) {\n        Object.assign(headers, pushNotificationConfig.authentication.credentials)\n      }\n    }\n    const body = JSON.stringify({\n      taskId,\n      state,\n      payload,\n    })\n    const response = await fetch(pushNotificationConfig.url, {\n      method: 'POST',\n      headers,\n      body,\n    })\n    if (!response.ok) {\n      throw PaymentsError.internal('Failed to send push notification.')\n    }\n  }\n\n  /**\n   * Migrates the HTTP context from a messageId to a taskId and deletes the temporary messageId context.\n   * @param messageId - The messageId to migrate from\n   * @param taskId - The taskId to migrate to\n   */\n  public migrateHttpRequestContextFromMessageToTask(messageId: string, taskId: string): void {\n    const ctx = this.getHttpRequestContextForMessage(messageId)\n    if (ctx) {\n      this.setHttpRequestContextForTask(taskId, ctx)\n      this.deleteHttpRequestContextForMessage(messageId)\n    }\n  }\n\n  /**\n   * Deletes the HTTP context associated with a messageId.\n   * @param messageId - The messageId to delete context for\n   */\n  public deleteHttpRequestContextForMessage(messageId: string): void {\n    this.httpContextByMessageId.delete(messageId)\n  }\n\n  /**\n   * Protected getter to access the private taskStore property from the parent class.\n   * This is a workaround due to SDK limitations.\n   */\n  protected getTaskStore(): TaskStore {\n    return (this as any).taskStore as TaskStore\n  }\n\n  /**\n   * Protected getter to access the private eventBusManager property from the parent class.\n   * This is a workaround due to SDK limitations.\n   */\n  protected getEventBusManager(): ExecutionEventBusManager {\n    return (this as any).eventBusManager as ExecutionEventBusManager\n  }\n}\n"]}

package/dist/a2a/server.d.ts

@@ -0,0 +1,126 @@
+/// <reference types="node" />
+/**
+ * PaymentsA2AServer sets up and starts the A2A server for payments agents.
+ * Handles A2A protocol endpoints and allows optional custom endpoints.
+ *
+ * The server provides a complete A2A protocol implementation with:
+ * - JSON-RPC endpoint for A2A messages
+ * - Agent Card endpoint (.well-known/agent.json)
+ * - Bearer token extraction and validation
+ * - Credit validation and burning
+ * - Task execution and streaming
+ * - Customizable routes and handlers
+ */
+import express from 'express';
+import http from 'http';
+import { AgentExecutor } from '@a2a-js/sdk';
+import type { AgentCard } from './types';
+import { PaymentsRequestHandler } from './paymentsRequestHandler';
+/**
+ * Options for starting the PaymentsA2AServer.
+ * Provides comprehensive configuration for A2A server setup.
+ */
+export interface PaymentsA2AServerOptions {
+    /** The agent card defining the agent's capabilities and metadata */
+    agentCard: AgentCard;
+    /** User-implemented executor for handling A2A tasks */
+    executor: AgentExecutor;
+    /** Payments service instance for credit validation and burning */
+    paymentsService: any;
+    /** Port number to bind the server to */
+    port: number;
+    /** Custom task store implementation (defaults to InMemoryTaskStore) */
+    taskStore?: any;
+    /** Base path for all A2A routes (defaults to '/') */
+    basePath?: string;
+    /** Whether to expose the agent card at .well-known/agent.json */
+    exposeAgentCard?: boolean;
+    /** Whether to expose default A2A JSON-RPC routes */
+    exposeDefaultRoutes?: boolean;
+    /** Custom Express app instance (defaults to new express()) */
+    expressApp?: express.Express;
+    /** Custom request handler to override JSON-RPC method handling */
+    customRequestHandler?: any;
+    /** Hooks for intercepting requests before/after processing */
+    hooks?: {
+        /** Called before processing any JSON-RPC request */
+        beforeRequest?: (method: string, params: any, req: express.Request) => Promise<void>;
+        /** Called after processing any JSON-RPC request */
+        afterRequest?: (method: string, result: any, req: express.Request) => Promise<void>;
+        /** Called when a JSON-RPC request fails */
+        onError?: (method: string, error: Error, req: express.Request) => Promise<void>;
+    };
+}
+/**
+ * Result returned by the server start method.
+ * Contains the Express app and HTTP server instances for further customization.
+ */
+export interface PaymentsA2AServerResult {
+    /** The configured Express application */
+    app: express.Express;
+    /** The HTTP server instance */
+    server: http.Server;
+    /** The request handler instance for direct access if needed */
+    handler: PaymentsRequestHandler;
+}
+/**
+ * PaymentsA2AServer sets up the A2A endpoints and starts the server.
+ *
+ * This class provides a complete A2A protocol implementation with payment integration.
+ * It handles:
+ * - JSON-RPC message routing
+ * - Agent card exposure
+ * - Bearer token extraction
+ * - Credit validation and burning
+ * - Task execution and streaming
+ * - Customizable routes and handlers
+ *
+ * @example
+ * ```typescript
+ * const server = PaymentsA2AServer.start({
+ *   agentCard: myAgentCard,
+ *   executor: new MyExecutor(),
+ *   paymentsService: payments,
+ *   port: 41242,
+ *   basePath: '/a2a/',
+ *   hooks: {
+ *     beforeRequest: async (method, params, req) => {
+ *       console.log(`Processing ${method} request`)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare class PaymentsA2AServer {
+    /**
+     * Starts the A2A server with the given options.
+     *
+     * This method sets up the complete A2A server infrastructure including:
+     * - Express app configuration
+     * - A2A route setup
+     * - Middleware for bearer token extraction
+     * - Agent card endpoint
+     * - HTTP server creation and binding
+     *
+     * @param options - Server configuration options
+     * @returns Server result containing app, server, adapter, and handler instances
+     *
+     * @example
+     * ```typescript
+     * const result = PaymentsA2AServer.start({
+     *   agentCard: buildPaymentAgentCard(baseCard, paymentMetadata),
+     *   executor: new MyPaymentsExecutor(),
+     *   paymentsService: payments,
+     *   port: 41242,
+     *   basePath: '/a2a/',
+     *   exposeAgentCard: true,
+     *   exposeDefaultRoutes: true
+     * })
+     *
+     * // Access the Express app for additional routes
+     * result.app.get('/health', (req, res) => res.json({ status: 'ok' }))
+     * ```
+     */
+    static start(options: PaymentsA2AServerOptions): PaymentsA2AServerResult;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/a2a/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/a2a/server.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;AACH,OAAO,OAAO,MAAM,SAAS,CAAA;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,EAAoC,aAAa,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AAEjE;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,SAAS,EAAE,SAAS,CAAA;IACpB,uDAAuD;IACvD,QAAQ,EAAE,aAAa,CAAA;IACvB,kEAAkE;IAClE,eAAe,EAAE,GAAG,CAAA;IACpB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,SAAS,CAAC,EAAE,GAAG,CAAA;IACf,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,oDAAoD;IACpD,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC,OAAO,CAAA;IAC5B,kEAAkE;IAClE,oBAAoB,CAAC,EAAE,GAAG,CAAA;IAC1B,8DAA8D;IAC9D,KAAK,CAAC,EAAE;QACN,oDAAoD;QACpD,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QACpF,mDAAmD;QACnD,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;QACnF,2CAA2C;QAC3C,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KAChF,CAAA;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAA;IACpB,+BAA+B;IAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAA;IACnB,+DAA+D;IAC/D,OAAO,EAAE,sBAAsB,CAAA;CAChC;AAyDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,wBAAwB,GAAG,uBAAuB;CAuFzE"}