@t402/a2a 2.4.0

package/dist/cjs/server.d.cts

@@ -0,0 +1,177 @@
+import { PaymentPayload, PaymentRequired, SettleResponse, A2AMessage, A2ATaskStatus, A2ATask } from '@t402/core/types';
+import { FacilitatorClient } from '@t402/core/server';
+
+/**
+ * A2A Payment Server
+ *
+ * Handles server-side payment processing for A2A agent endpoints,
+ * including generating payment requirements and processing payment submissions.
+ */
+
+/**
+ * Result of payment processing
+ */
+interface A2APaymentResult {
+    /** Whether payment was successful */
+    success: boolean;
+    /** Settlement receipts (if settled) */
+    receipts?: SettleResponse[];
+    /** Error message (if failed) */
+    error?: string;
+    /** A2A message to include in response */
+    message: A2AMessage;
+}
+/**
+ * Payment handler function type
+ */
+type A2APaymentHandler = (payload: PaymentPayload, requirements: PaymentRequired) => Promise<A2APaymentResult>;
+/**
+ * Options for A2APaymentServer
+ */
+interface A2APaymentServerOptions {
+    /**
+     * Facilitator client for verification and settlement
+     */
+    facilitator?: FacilitatorClient;
+    /**
+     * Custom payment handler (alternative to facilitator)
+     */
+    paymentHandler?: A2APaymentHandler;
+    /**
+     * Default payment requirements template
+     */
+    defaultRequirements?: Partial<PaymentRequired>;
+    /**
+     * Optional callback when payment is received
+     */
+    onPaymentReceived?: (payload: PaymentPayload) => void;
+    /**
+     * Optional callback when payment is verified
+     */
+    onPaymentVerified?: (payload: PaymentPayload) => void;
+    /**
+     * Optional callback when payment is settled
+     */
+    onPaymentSettled?: (receipts: SettleResponse[]) => void;
+    /**
+     * Optional callback when payment fails
+     */
+    onPaymentFailed?: (error: string, payload?: PaymentPayload) => void;
+}
+/**
+ * A2A Payment Server
+ *
+ * Provides server-side payment handling for A2A agent endpoints.
+ *
+ * @example
+ * ```typescript
+ * const server = new A2APaymentServer({
+ *   facilitator: facilitatorClient,
+ *   defaultRequirements: {
+ *     t402Version: 2,
+ *     resource: 'agent://my-agent/skill',
+ *   },
+ * });
+ *
+ * // Create payment-required response
+ * const requirements = server.createRequirements({
+ *   accepts: [{ scheme: 'exact', network: 'eip155:8453', amount: '1000000', ... }],
+ * });
+ * const task = server.createPaymentRequiredTask(taskId, requirements);
+ *
+ * // Process payment submission
+ * const result = await server.processPayment(message, requirements);
+ * if (result.success) {
+ *   // Continue with task execution
+ * }
+ * ```
+ */
+declare class A2APaymentServer {
+    private options;
+    constructor(options?: A2APaymentServerOptions);
+    /**
+     * Create payment requirements with defaults
+     *
+     * @param requirements - Partial requirements to merge with defaults
+     * @returns Complete payment requirements
+     */
+    createRequirements(requirements: Partial<PaymentRequired>): PaymentRequired;
+    /**
+     * Create a payment-required task status
+     *
+     * @param requirements - Payment requirements
+     * @param text - Optional text message
+     * @returns A2A task status
+     */
+    createPaymentRequiredStatus(requirements: PaymentRequired, text?: string): A2ATaskStatus;
+    /**
+     * Create a payment-required task
+     *
+     * @param taskId - Task identifier
+     * @param requirements - Payment requirements
+     * @param text - Optional text message
+     * @returns A2A task in input-required state
+     */
+    createPaymentRequiredTask(taskId: string, requirements: PaymentRequired, text?: string): A2ATask;
+    /**
+     * Extract payment payload from an A2A message
+     *
+     * @param message - A2A message that may contain payment
+     * @returns Payment payload or undefined
+     */
+    extractPaymentPayload(message: A2AMessage): PaymentPayload | undefined;
+    /**
+     * Check if a message contains a payment submission
+     *
+     * @param message - A2A message to check
+     * @returns Whether the message contains a payment
+     */
+    hasPaymentPayload(message: A2AMessage): boolean;
+    /**
+     * Process a payment submission
+     *
+     * @param message - A2A message containing payment payload
+     * @param requirements - Original payment requirements
+     * @returns Payment processing result
+     */
+    processPayment(message: A2AMessage, requirements: PaymentRequired): Promise<A2APaymentResult>;
+    /**
+     * Create a completed task status with payment receipts
+     *
+     * @param receipts - Settlement receipts
+     * @param text - Optional text message
+     * @returns A2A task status
+     */
+    createPaymentCompletedStatus(receipts: SettleResponse[], text?: string): A2ATaskStatus;
+    /**
+     * Create a failed task status with payment error
+     *
+     * @param error - Error message
+     * @param receipts - Optional settlement receipts
+     * @param errorCode - Optional error code
+     * @returns A2A task status
+     */
+    createPaymentFailedStatus(error: string, receipts?: SettleResponse[], errorCode?: string): A2ATaskStatus;
+    /**
+     * Update a task with payment completion
+     *
+     * @param task - Original task
+     * @param result - Payment processing result
+     * @returns Updated task
+     */
+    updateTaskWithPaymentResult(task: A2ATask, result: A2APaymentResult): A2ATask;
+    /**
+     * Handle a complete payment flow for a task
+     *
+     * This is a convenience method that processes a payment submission
+     * and returns an updated task.
+     *
+     * @param task - The current A2A task
+     * @param message - The message containing payment payload
+     * @param requirements - Payment requirements
+     * @returns Updated task with payment result
+     */
+    handlePayment(task: A2ATask, message: A2AMessage, requirements: PaymentRequired): Promise<A2ATask>;
+}
+
+export { type A2APaymentHandler, type A2APaymentResult, A2APaymentServer, type A2APaymentServerOptions };

package/dist/esm/chunk-6TJQKXTN.mjs

@@ -0,0 +1,219 @@
+// src/server.ts
+import {
+  createPaymentRequiredMessage,
+  createPaymentCompletedMessage,
+  createPaymentFailedMessage
+} from "@t402/core/types";
+var A2APaymentServer = class {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /**
+   * Create payment requirements with defaults
+   *
+   * @param requirements - Partial requirements to merge with defaults
+   * @returns Complete payment requirements
+   */
+  createRequirements(requirements) {
+    return {
+      t402Version: 2,
+      ...this.options.defaultRequirements,
+      ...requirements
+    };
+  }
+  /**
+   * Create a payment-required task status
+   *
+   * @param requirements - Payment requirements
+   * @param text - Optional text message
+   * @returns A2A task status
+   */
+  createPaymentRequiredStatus(requirements, text) {
+    return {
+      state: "input-required",
+      message: createPaymentRequiredMessage(requirements, text),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Create a payment-required task
+   *
+   * @param taskId - Task identifier
+   * @param requirements - Payment requirements
+   * @param text - Optional text message
+   * @returns A2A task in input-required state
+   */
+  createPaymentRequiredTask(taskId, requirements, text) {
+    return {
+      kind: "task",
+      id: taskId,
+      status: this.createPaymentRequiredStatus(requirements, text)
+    };
+  }
+  /**
+   * Extract payment payload from an A2A message
+   *
+   * @param message - A2A message that may contain payment
+   * @returns Payment payload or undefined
+   */
+  extractPaymentPayload(message) {
+    return message.metadata?.["t402.payment.payload"];
+  }
+  /**
+   * Check if a message contains a payment submission
+   *
+   * @param message - A2A message to check
+   * @returns Whether the message contains a payment
+   */
+  hasPaymentPayload(message) {
+    return message.metadata?.["t402.payment.status"] === "payment-submitted" && message.metadata?.["t402.payment.payload"] !== void 0;
+  }
+  /**
+   * Process a payment submission
+   *
+   * @param message - A2A message containing payment payload
+   * @param requirements - Original payment requirements
+   * @returns Payment processing result
+   */
+  async processPayment(message, requirements) {
+    const payload = this.extractPaymentPayload(message);
+    if (!payload) {
+      const error = "No payment payload in message";
+      this.options.onPaymentFailed?.(error);
+      return {
+        success: false,
+        error,
+        message: createPaymentFailedMessage([], "T402-1001", error)
+      };
+    }
+    this.options.onPaymentReceived?.(payload);
+    if (this.options.paymentHandler) {
+      return this.options.paymentHandler(payload, requirements);
+    }
+    if (!this.options.facilitator) {
+      const error = "No facilitator or payment handler configured";
+      this.options.onPaymentFailed?.(error, payload);
+      return {
+        success: false,
+        error,
+        message: createPaymentFailedMessage([], "T402-5001", error)
+      };
+    }
+    try {
+      const paymentRequirements = payload.accepted;
+      const verifyResponse = await this.options.facilitator.verify(
+        payload,
+        paymentRequirements
+      );
+      if (!verifyResponse.isValid) {
+        const error = verifyResponse.invalidReason || "Payment verification failed";
+        this.options.onPaymentFailed?.(error, payload);
+        return {
+          success: false,
+          error,
+          message: createPaymentFailedMessage([], "T402-2001", error)
+        };
+      }
+      this.options.onPaymentVerified?.(payload);
+      const settleResponse = await this.options.facilitator.settle(
+        payload,
+        paymentRequirements
+      );
+      const receipts = [settleResponse];
+      if (!settleResponse.success) {
+        const error = settleResponse.errorReason || "Payment settlement failed";
+        this.options.onPaymentFailed?.(error, payload);
+        return {
+          success: false,
+          receipts,
+          error,
+          message: createPaymentFailedMessage(receipts, "T402-3001", error)
+        };
+      }
+      this.options.onPaymentSettled?.(receipts);
+      return {
+        success: true,
+        receipts,
+        message: createPaymentCompletedMessage(receipts)
+      };
+    } catch (err) {
+      const error = err instanceof Error ? err.message : "Payment processing error";
+      this.options.onPaymentFailed?.(error, payload);
+      return {
+        success: false,
+        error,
+        message: createPaymentFailedMessage([], "T402-5002", error)
+      };
+    }
+  }
+  /**
+   * Create a completed task status with payment receipts
+   *
+   * @param receipts - Settlement receipts
+   * @param text - Optional text message
+   * @returns A2A task status
+   */
+  createPaymentCompletedStatus(receipts, text) {
+    return {
+      state: "completed",
+      message: createPaymentCompletedMessage(receipts, text),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Create a failed task status with payment error
+   *
+   * @param error - Error message
+   * @param receipts - Optional settlement receipts
+   * @param errorCode - Optional error code
+   * @returns A2A task status
+   */
+  createPaymentFailedStatus(error, receipts = [], errorCode = "T402-5000") {
+    return {
+      state: "failed",
+      message: createPaymentFailedMessage(receipts, errorCode, error),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Update a task with payment completion
+   *
+   * @param task - Original task
+   * @param result - Payment processing result
+   * @returns Updated task
+   */
+  updateTaskWithPaymentResult(task, result) {
+    if (result.success) {
+      return {
+        ...task,
+        status: this.createPaymentCompletedStatus(result.receipts || []),
+        history: [...task.history || [], result.message]
+      };
+    }
+    return {
+      ...task,
+      status: this.createPaymentFailedStatus(result.error || "Payment failed", result.receipts),
+      history: [...task.history || [], result.message]
+    };
+  }
+  /**
+   * Handle a complete payment flow for a task
+   *
+   * This is a convenience method that processes a payment submission
+   * and returns an updated task.
+   *
+   * @param task - The current A2A task
+   * @param message - The message containing payment payload
+   * @param requirements - Payment requirements
+   * @returns Updated task with payment result
+   */
+  async handlePayment(task, message, requirements) {
+    const result = await this.processPayment(message, requirements);
+    return this.updateTaskWithPaymentResult(task, result);
+  }
+};
+
+export {
+  A2APaymentServer
+};

package/dist/esm/chunk-IPWV3JOP.mjs

@@ -0,0 +1,127 @@
+// src/client.ts
+import {
+  isPaymentRequired,
+  getPaymentRequired,
+  createPaymentSubmissionMessage
+} from "@t402/core/types";
+var A2APaymentClient = class {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /**
+   * Check if a task requires payment
+   */
+  requiresPayment(task) {
+    const requires = isPaymentRequired(task);
+    if (requires) {
+      const requirements = getPaymentRequired(task);
+      if (requirements && this.options.onPaymentRequired) {
+        this.options.onPaymentRequired(requirements);
+      }
+    }
+    return requires;
+  }
+  /**
+   * Get payment requirements from a task
+   */
+  getRequirements(task) {
+    return getPaymentRequired(task);
+  }
+  /**
+   * Select the best payment option from requirements
+   *
+   * @param requirements - Payment requirements with accepts array
+   * @param preferredNetwork - Preferred network (CAIP-2 format)
+   * @param preferredScheme - Preferred scheme (e.g., 'exact', 'upto')
+   * @returns The best matching payment option or undefined
+   */
+  selectPaymentOption(requirements, preferredNetwork, preferredScheme) {
+    const accepts = requirements.accepts;
+    if (!accepts || accepts.length === 0) {
+      return void 0;
+    }
+    if (preferredNetwork && preferredScheme) {
+      const exact = accepts.find(
+        (a) => a.network === preferredNetwork && a.scheme === preferredScheme
+      );
+      if (exact) return exact;
+    }
+    if (preferredNetwork) {
+      const byNetwork = accepts.find((a) => a.network === preferredNetwork);
+      if (byNetwork) return byNetwork;
+    }
+    if (preferredScheme) {
+      const byScheme = accepts.find((a) => a.scheme === preferredScheme);
+      if (byScheme) return byScheme;
+    }
+    return accepts[0];
+  }
+  /**
+   * Create a payment payload using a mechanism client
+   *
+   * @param mechanism - The scheme/network client to use
+   * @param requirements - Payment requirements to fulfill
+   * @returns Promise resolving to the payment payload
+   */
+  async createPayload(mechanism, requirements) {
+    const selected = this.selectPaymentOption(requirements);
+    if (!selected) {
+      throw new Error("No payment options available");
+    }
+    const basePayload = await mechanism.createPaymentPayload(
+      requirements.t402Version,
+      selected
+    );
+    const payload = {
+      ...basePayload,
+      resource: requirements.resource,
+      accepted: selected
+    };
+    if (this.options.onPaymentSubmitted) {
+      this.options.onPaymentSubmitted(payload);
+    }
+    return payload;
+  }
+  /**
+   * Create a payment submission message
+   *
+   * @param payload - The payment payload to submit
+   * @param text - Optional text message
+   * @returns A2A message with payment metadata
+   */
+  createPaymentMessage(payload, text = "Here is the payment authorization.") {
+    return createPaymentSubmissionMessage(payload, text);
+  }
+  /**
+   * Handle a complete payment flow for a task
+   *
+   * This is a convenience method that checks for payment requirements,
+   * creates a payload, and returns a payment message.
+   *
+   * @param task - The A2A task that may require payment
+   * @param mechanism - The mechanism client to use for signing
+   * @param preferredNetwork - Optional preferred network
+   * @param preferredScheme - Optional preferred scheme
+   * @returns A2A message with payment, or undefined if no payment needed
+   */
+  async handlePayment(task, mechanism, preferredNetwork, preferredScheme) {
+    if (!this.requiresPayment(task)) {
+      return void 0;
+    }
+    const requirements = this.getRequirements(task);
+    if (!requirements) {
+      return void 0;
+    }
+    const selected = this.selectPaymentOption(requirements, preferredNetwork, preferredScheme);
+    if (!selected) {
+      throw new Error("No compatible payment option found");
+    }
+    const payload = await this.createPayload(mechanism, requirements);
+    return this.createPaymentMessage(payload);
+  }
+};
+
+export {
+  A2APaymentClient
+};

package/dist/esm/client.d.ts

@@ -0,0 +1,102 @@
+import { PaymentRequired, PaymentPayload, A2ATask, SchemeNetworkClient, A2AMessage } from '@t402/core/types';
+
+/**
+ * A2A Payment Client
+ *
+ * Handles payment flows for A2A client agents, including detecting
+ * payment-required states and submitting payment payloads.
+ */
+
+/**
+ * Options for A2APaymentClient
+ */
+interface A2APaymentClientOptions {
+    /**
+     * Optional callback when payment is required
+     */
+    onPaymentRequired?: (requirements: PaymentRequired) => void;
+    /**
+     * Optional callback when payment is submitted
+     */
+    onPaymentSubmitted?: (payload: PaymentPayload) => void;
+    /**
+     * Optional callback when payment is completed
+     */
+    onPaymentCompleted?: (task: A2ATask) => void;
+    /**
+     * Optional callback when payment fails
+     */
+    onPaymentFailed?: (error: string, task: A2ATask) => void;
+}
+/**
+ * A2A Payment Client
+ *
+ * Provides methods for handling t402 payments in A2A client agents.
+ *
+ * @example
+ * ```typescript
+ * const client = new A2APaymentClient({
+ *   onPaymentRequired: (req) => console.log('Payment required:', req),
+ * });
+ *
+ * // Check if task requires payment
+ * if (client.requiresPayment(task)) {
+ *   const requirements = client.getRequirements(task);
+ *   const payload = await mechanism.createPaymentPayload(requirements);
+ *   const message = client.createPaymentMessage(payload);
+ *   // Send message via A2A
+ * }
+ * ```
+ */
+declare class A2APaymentClient {
+    private options;
+    constructor(options?: A2APaymentClientOptions);
+    /**
+     * Check if a task requires payment
+     */
+    requiresPayment(task: A2ATask): boolean;
+    /**
+     * Get payment requirements from a task
+     */
+    getRequirements(task: A2ATask): PaymentRequired | undefined;
+    /**
+     * Select the best payment option from requirements
+     *
+     * @param requirements - Payment requirements with accepts array
+     * @param preferredNetwork - Preferred network (CAIP-2 format)
+     * @param preferredScheme - Preferred scheme (e.g., 'exact', 'upto')
+     * @returns The best matching payment option or undefined
+     */
+    selectPaymentOption(requirements: PaymentRequired, preferredNetwork?: string, preferredScheme?: string): PaymentRequired["accepts"][0] | undefined;
+    /**
+     * Create a payment payload using a mechanism client
+     *
+     * @param mechanism - The scheme/network client to use
+     * @param requirements - Payment requirements to fulfill
+     * @returns Promise resolving to the payment payload
+     */
+    createPayload(mechanism: SchemeNetworkClient, requirements: PaymentRequired): Promise<PaymentPayload>;
+    /**
+     * Create a payment submission message
+     *
+     * @param payload - The payment payload to submit
+     * @param text - Optional text message
+     * @returns A2A message with payment metadata
+     */
+    createPaymentMessage(payload: PaymentPayload, text?: string): A2AMessage;
+    /**
+     * Handle a complete payment flow for a task
+     *
+     * This is a convenience method that checks for payment requirements,
+     * creates a payload, and returns a payment message.
+     *
+     * @param task - The A2A task that may require payment
+     * @param mechanism - The mechanism client to use for signing
+     * @param preferredNetwork - Optional preferred network
+     * @param preferredScheme - Optional preferred scheme
+     * @returns A2A message with payment, or undefined if no payment needed
+     */
+    handlePayment(task: A2ATask, mechanism: SchemeNetworkClient, preferredNetwork?: string, preferredScheme?: string): Promise<A2AMessage | undefined>;
+}
+
+export { A2APaymentClient, type A2APaymentClientOptions };

package/dist/esm/client.mjs

@@ -0,0 +1,6 @@
+import {
+  A2APaymentClient
+} from "./chunk-IPWV3JOP.mjs";
+export {
+  A2APaymentClient
+};

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { A2AAgentCard, A2AArtifact, A2ACapabilities, A2ADataPart, A2AError, A2AExtension, A2AFilePart, A2AMessage, A2AMessagePart, A2APaymentMetadata, A2APaymentStatus, A2ARequest, A2AResponse, A2ASkill, A2ATask, A2ATaskState, A2ATaskStatus, A2ATextPart, A2A_EXTENSIONS_HEADER, T402_A2A_EXTENSION_URI, createPaymentCompletedMessage, createPaymentFailedMessage, createPaymentRequiredMessage, createPaymentSubmissionMessage, createT402Extension, getPaymentReceipts, getPaymentRequired, isPaymentCompleted, isPaymentFailed, isPaymentRequired } from '@t402/core/types';
+export { A2APaymentClient, A2APaymentClientOptions } from './client.js';
+export { A2APaymentHandler, A2APaymentResult, A2APaymentServer, A2APaymentServerOptions } from './server.js';
+import '@t402/core/server';

package/dist/esm/index.mjs

@@ -0,0 +1,38 @@
+import {
+  A2APaymentClient
+} from "./chunk-IPWV3JOP.mjs";
+import {
+  A2APaymentServer
+} from "./chunk-6TJQKXTN.mjs";
+
+// src/index.ts
+import {
+  T402_A2A_EXTENSION_URI,
+  A2A_EXTENSIONS_HEADER,
+  isPaymentRequired,
+  isPaymentCompleted,
+  isPaymentFailed,
+  getPaymentRequired,
+  getPaymentReceipts,
+  createPaymentRequiredMessage,
+  createPaymentSubmissionMessage,
+  createPaymentCompletedMessage,
+  createPaymentFailedMessage,
+  createT402Extension
+} from "@t402/core/types";
+export {
+  A2APaymentClient,
+  A2APaymentServer,
+  A2A_EXTENSIONS_HEADER,
+  T402_A2A_EXTENSION_URI,
+  createPaymentCompletedMessage,
+  createPaymentFailedMessage,
+  createPaymentRequiredMessage,
+  createPaymentSubmissionMessage,
+  createT402Extension,
+  getPaymentReceipts,
+  getPaymentRequired,
+  isPaymentCompleted,
+  isPaymentFailed,
+  isPaymentRequired
+};