@t402/a2a 2.4.0

package/dist/cjs/index.cjs

@@ -0,0 +1,388 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  A2APaymentClient: () => A2APaymentClient,
+  A2APaymentServer: () => A2APaymentServer,
+  A2A_EXTENSIONS_HEADER: () => import_types3.A2A_EXTENSIONS_HEADER,
+  T402_A2A_EXTENSION_URI: () => import_types3.T402_A2A_EXTENSION_URI,
+  createPaymentCompletedMessage: () => import_types3.createPaymentCompletedMessage,
+  createPaymentFailedMessage: () => import_types3.createPaymentFailedMessage,
+  createPaymentRequiredMessage: () => import_types3.createPaymentRequiredMessage,
+  createPaymentSubmissionMessage: () => import_types3.createPaymentSubmissionMessage,
+  createT402Extension: () => import_types3.createT402Extension,
+  getPaymentReceipts: () => import_types3.getPaymentReceipts,
+  getPaymentRequired: () => import_types3.getPaymentRequired,
+  isPaymentCompleted: () => import_types3.isPaymentCompleted,
+  isPaymentFailed: () => import_types3.isPaymentFailed,
+  isPaymentRequired: () => import_types3.isPaymentRequired
+});
+module.exports = __toCommonJS(index_exports);
+var import_types3 = require("@t402/core/types");
+
+// src/client.ts
+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);
+  }
+};
+
+// src/server.ts
+var import_types2 = require("@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: (0, import_types2.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: (0, import_types2.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: (0, import_types2.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: (0, import_types2.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: (0, import_types2.createPaymentFailedMessage)(receipts, "T402-3001", error)
+        };
+      }
+      this.options.onPaymentSettled?.(receipts);
+      return {
+        success: true,
+        receipts,
+        message: (0, import_types2.createPaymentCompletedMessage)(receipts)
+      };
+    } catch (err) {
+      const error = err instanceof Error ? err.message : "Payment processing error";
+      this.options.onPaymentFailed?.(error, payload);
+      return {
+        success: false,
+        error,
+        message: (0, import_types2.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: (0, import_types2.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: (0, import_types2.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);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A2APaymentClient,
+  A2APaymentServer,
+  A2A_EXTENSIONS_HEADER,
+  T402_A2A_EXTENSION_URI,
+  createPaymentCompletedMessage,
+  createPaymentFailedMessage,
+  createPaymentRequiredMessage,
+  createPaymentSubmissionMessage,
+  createT402Extension,
+  getPaymentReceipts,
+  getPaymentRequired,
+  isPaymentCompleted,
+  isPaymentFailed,
+  isPaymentRequired
+});

package/dist/cjs/index.d.cts

@@ -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.cjs';
+export { A2APaymentHandler, A2APaymentResult, A2APaymentServer, A2APaymentServerOptions } from './server.cjs';
+import '@t402/core/server';

package/dist/cjs/server.cjs

@@ -0,0 +1,239 @@
+"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/server.ts
+var server_exports = {};
+__export(server_exports, {
+  A2APaymentServer: () => A2APaymentServer
+});
+module.exports = __toCommonJS(server_exports);
+var import_types = require("@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: (0, import_types.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: (0, import_types.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: (0, import_types.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: (0, import_types.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: (0, import_types.createPaymentFailedMessage)(receipts, "T402-3001", error)
+        };
+      }
+      this.options.onPaymentSettled?.(receipts);
+      return {
+        success: true,
+        receipts,
+        message: (0, import_types.createPaymentCompletedMessage)(receipts)
+      };
+    } catch (err) {
+      const error = err instanceof Error ? err.message : "Payment processing error";
+      this.options.onPaymentFailed?.(error, payload);
+      return {
+        success: false,
+        error,
+        message: (0, import_types.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: (0, import_types.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: (0, import_types.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);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  A2APaymentServer
+});