@t402/a2a 2.4.0

package/README.md

@@ -0,0 +1,182 @@
+# @t402/a2a
+
+A2A (Agent-to-Agent) transport implementation for the t402 payment protocol. Enables AI agents to monetize their services through on-chain cryptocurrency payments using the A2A protocol.
+
+## Installation
+
+```bash
+npm install @t402/a2a
+# or
+pnpm add @t402/a2a
+```
+
+## Overview
+
+This package provides tools for implementing t402 payments over the A2A (Agent-to-Agent) protocol:
+
+- **A2APaymentClient**: Client-side payment handling for AI agents requesting services
+- **A2APaymentServer**: Server-side payment processing for AI agents providing services
+- **Type definitions**: Complete TypeScript types for A2A payment flows
+- **Helper functions**: Utilities for creating and parsing payment messages
+
+## Usage
+
+### Client-Side (Requesting Services)
+
+```typescript
+import { A2APaymentClient } from "@t402/a2a";
+import { ExactEVMClient } from "@t402/evm/exact/client";
+
+// Create a payment client
+const paymentClient = new A2APaymentClient({
+  onPaymentRequired: (requirements) =>
+    console.log("Payment required:", requirements),
+  onPaymentSubmitted: (payload) =>
+    console.log("Payment submitted:", payload),
+});
+
+// Create your mechanism client (e.g., EVM)
+const mechanism = new ExactEVMClient({ signer: yourSigner });
+
+// Handle payment flow
+async function handleTask(task: A2ATask) {
+  // Check if payment is required
+  if (paymentClient.requiresPayment(task)) {
+    // Get requirements and create payment
+    const requirements = paymentClient.getRequirements(task);
+    const payload = await paymentClient.createPayload(mechanism, requirements!);
+
+    // Create message with payment
+    const message = paymentClient.createPaymentMessage(payload);
+
+    // Send message via A2A protocol
+    return message;
+  }
+}
+
+// Or use the convenience method
+const paymentMessage = await paymentClient.handlePayment(task, mechanism);
+```
+
+### Server-Side (Providing Services)
+
+```typescript
+import { A2APaymentServer } from "@t402/a2a";
+import { HTTPFacilitatorClient } from "@t402/core/server";
+
+// Create a payment server
+const paymentServer = new A2APaymentServer({
+  facilitator: new HTTPFacilitatorClient(),
+  defaultRequirements: {
+    resource: { url: "agent://my-agent/skill" },
+  },
+  onPaymentReceived: (payload) => console.log("Payment received:", payload),
+  onPaymentSettled: (receipts) => console.log("Payment settled:", receipts),
+});
+
+// Create payment-required task for a new request
+function createPaymentTask(taskId: string): A2ATask {
+  const requirements = paymentServer.createRequirements({
+    accepts: [
+      {
+        scheme: "exact",
+        network: "eip155:8453",
+        amount: "1000000", // 1 USDC
+        asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        payTo: "0xYourAddress",
+        maxTimeoutSeconds: 3600,
+        extra: {},
+      },
+    ],
+  });
+
+  return paymentServer.createPaymentRequiredTask(taskId, requirements);
+}
+
+// Process payment when received
+async function processPayment(
+  task: A2ATask,
+  message: A2AMessage,
+  requirements: PaymentRequired,
+): Promise<A2ATask> {
+  const result = await paymentServer.processPayment(message, requirements);
+
+  if (result.success) {
+    // Payment successful, continue with task execution
+    return {
+      ...task,
+      status: {
+        state: "working",
+        message: { kind: "message", role: "agent", parts: [{ kind: "text", text: "Processing..." }] },
+      },
+    };
+  }
+
+  // Payment failed
+  return paymentServer.updateTaskWithPaymentResult(task, result);
+}
+```
+
+## API Reference
+
+### A2APaymentClient
+
+Client for handling payments in A2A client agents.
+
+| Method | Description |
+|--------|-------------|
+| `requiresPayment(task)` | Check if a task requires payment |
+| `getRequirements(task)` | Extract payment requirements from a task |
+| `selectPaymentOption(requirements, network?, scheme?)` | Select the best payment option |
+| `createPayload(mechanism, requirements)` | Create a signed payment payload |
+| `createPaymentMessage(payload, text?)` | Create an A2A message with payment |
+| `handlePayment(task, mechanism, network?, scheme?)` | Handle complete payment flow |
+
+### A2APaymentServer
+
+Server for processing payments in A2A server agents.
+
+| Method | Description |
+|--------|-------------|
+| `createRequirements(requirements)` | Create requirements with defaults |
+| `createPaymentRequiredTask(taskId, requirements, text?)` | Create a payment-required task |
+| `extractPaymentPayload(message)` | Extract payment from a message |
+| `hasPaymentPayload(message)` | Check if message contains payment |
+| `processPayment(message, requirements)` | Process a payment submission |
+| `handlePayment(task, message, requirements)` | Handle payment and update task |
+| `updateTaskWithPaymentResult(task, result)` | Update task with payment result |
+
+### Re-exported Types
+
+All A2A types from `@t402/core/types` are re-exported:
+
+- `A2ATask`, `A2AMessage`, `A2ATaskStatus`
+- `A2APaymentStatus`, `A2APaymentMetadata`
+- `A2AAgentCard`, `A2ASkill`, `A2ACapabilities`
+- `isPaymentRequired()`, `isPaymentCompleted()`, `isPaymentFailed()`
+- `createPaymentRequiredMessage()`, `createPaymentSubmissionMessage()`
+- `createPaymentCompletedMessage()`, `createPaymentFailedMessage()`
+- `T402_A2A_EXTENSION_URI`, `A2A_EXTENSIONS_HEADER`
+
+## A2A Extension
+
+When advertising t402 payment support in your agent card:
+
+```typescript
+import { createT402Extension } from "@t402/a2a";
+
+const agentCard: A2AAgentCard = {
+  name: "My AI Agent",
+  url: "https://my-agent.example.com",
+  capabilities: {
+    extensions: [
+      createT402Extension(true), // required = true
+    ],
+  },
+  // ...
+};
+```
+
+## License
+
+Apache-2.0

package/dist/cjs/client.cjs

@@ -0,0 +1,147 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  A2APaymentClient: () => A2APaymentClient
+});
+module.exports = __toCommonJS(client_exports);
+var import_types = require("@t402/core/types");
+var A2APaymentClient = class {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /**
+   * Check if a task requires payment
+   */
+  requiresPayment(task) {
+    const requires = (0, import_types.isPaymentRequired)(task);
+    if (requires) {
+      const requirements = (0, import_types.getPaymentRequired)(task);
+      if (requirements && this.options.onPaymentRequired) {
+        this.options.onPaymentRequired(requirements);
+      }
+    }
+    return requires;
+  }
+  /**
+   * Get payment requirements from a task
+   */
+  getRequirements(task) {
+    return (0, import_types.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 (0, import_types.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);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A2APaymentClient
+});

package/dist/cjs/client.d.cts

@@ -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 };