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

package/dist/a2a/server.js

@@ -0,0 +1,189 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentsA2AServer = void 0;
+/**
+ * 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
+ */
+const express_1 = __importDefault(require("express"));
+const http_1 = __importDefault(require("http"));
+const sdk_1 = require("@a2a-js/sdk");
+const paymentsRequestHandler_1 = require("./paymentsRequestHandler");
+/**
+ * Middleware to extract bearer token from HTTP headers and store it in the global context.
+ * This middleware is applied after A2A routes are set up and extracts authentication
+ * information for credit validation.
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Express next function
+ */
+function _bearerTokenMiddleware(handler, req, res, next) {
+    console.log(`[MIDDLEWARE] Processing ${req.method} ${req.url}`);
+    // Only process POST requests (A2A uses POST for all operations)
+    if (req.method !== 'POST') {
+        console.log(`[MIDDLEWARE] Skipping non-POST request`);
+        return next();
+    }
+    // Extract bearer token from Authorization header
+    const authHeader = req.headers.authorization;
+    let bearerToken;
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+        bearerToken = authHeader.substring(7); // Remove 'Bearer ' prefix
+        console.log(`[MIDDLEWARE] Extracted bearer token: ${bearerToken.substring(0, 20)}...`);
+    }
+    else {
+        console.log(`[MIDDLEWARE] No bearer token found in headers`);
+    }
+    // Transform relative URL to absolute URL
+    const absoluteUrl = new URL(req.url, req.protocol + '://' + req.get('host')).toString();
+    const context = {
+        bearerToken,
+        urlRequested: absoluteUrl,
+        httpMethodRequested: req.method,
+    };
+    // Try to associate context with taskId or messageId
+    const taskId = req.body?.taskId || req.body?.id;
+    const messageId = req.body?.params?.message?.messageId;
+    if (taskId) {
+        handler.setHttpRequestContextForTask(taskId, context);
+    }
+    else if (messageId) {
+        handler.setHttpRequestContextForMessage(messageId, context);
+    }
+    next();
+}
+/**
+ * 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`)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+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) {
+        const { agentCard, executor, paymentsService, port, taskStore, basePath = '/', exposeAgentCard = true, exposeDefaultRoutes = true, expressApp, customRequestHandler, hooks, } = options;
+        // Initialize components
+        const store = taskStore || new sdk_1.InMemoryTaskStore();
+        const handler = customRequestHandler ||
+            new paymentsRequestHandler_1.PaymentsRequestHandler(agentCard, store, executor, paymentsService);
+        const appBuilder = new sdk_1.A2AExpressApp(handler);
+        const app = expressApp || (0, express_1.default)();
+        // Apply hooks middleware if provided
+        if (hooks) {
+            app.use((req, res, next) => {
+                if (req.method === 'POST' && req.body?.method) {
+                    const { method, params } = req.body;
+                    // Apply beforeRequest hook
+                    if (hooks.beforeRequest) {
+                        hooks.beforeRequest(method, params, req).catch((err) => {
+                            console.error('[HOOKS] beforeRequest error:', err);
+                        });
+                    }
+                    // Apply afterRequest hook by intercepting res.json
+                    const originalJson = res.json;
+                    res.json = function (data) {
+                        if (hooks.afterRequest) {
+                            hooks.afterRequest(method, data, req).catch((err) => {
+                                console.error('[HOOKS] afterRequest error:', err);
+                            });
+                        }
+                        return originalJson.call(this, data);
+                    };
+                    // Apply onError hook by catching errors
+                    const originalSend = res.send;
+                    res.send = function (data) {
+                        if (data?.error && hooks.onError) {
+                            hooks
+                                .onError(method, new Error(data.error.message || 'Unknown error'), req)
+                                .catch((err) => {
+                                console.error('[HOOKS] onError error:', err);
+                            });
+                        }
+                        return originalSend.call(this, data);
+                    };
+                }
+                next();
+            });
+        }
+        if (exposeDefaultRoutes) {
+            appBuilder.setupRoutes(app, basePath); //, [bearerTokenMiddleware.bind(null, handler)])
+        }
+        if (exposeAgentCard) {
+            app.get(`${basePath}.well-known/agent.json`, (req, res) => {
+                res.json(agentCard);
+            });
+        }
+        const server = http_1.default.createServer(app);
+        server.listen(port, () => {
+            console.log(`[PaymentsA2A] Server started on http://localhost:${port}${basePath}`);
+            if (exposeAgentCard) {
+                console.log(`[PaymentsA2A] Agent Card: http://localhost:${port}${basePath}.well-known/agent.json`);
+            }
+        });
+        return { app, server, handler };
+    }
+}
+exports.PaymentsA2AServer = PaymentsA2AServer;
+//# sourceMappingURL=server.js.map

package/dist/a2a/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/a2a/server.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * PaymentsA2AServer sets up and starts the A2A server for payments agents.\n * Handles A2A protocol endpoints and allows optional custom endpoints.\n *\n * The server provides a complete A2A protocol implementation with:\n * - JSON-RPC endpoint for A2A messages\n * - Agent Card endpoint (.well-known/agent.json)\n * - Bearer token extraction and validation\n * - Credit validation and burning\n * - Task execution and streaming\n * - Customizable routes and handlers\n */\nimport express from 'express'\nimport http from 'http'\nimport { InMemoryTaskStore, A2AExpressApp, AgentExecutor } from '@a2a-js/sdk'\nimport type { AgentCard } from './types'\nimport { PaymentsRequestHandler } from './paymentsRequestHandler'\n\n/**\n * Options for starting the PaymentsA2AServer.\n * Provides comprehensive configuration for A2A server setup.\n */\nexport interface PaymentsA2AServerOptions {\n  /** The agent card defining the agent's capabilities and metadata */\n  agentCard: AgentCard\n  /** User-implemented executor for handling A2A tasks */\n  executor: AgentExecutor\n  /** Payments service instance for credit validation and burning */\n  paymentsService: any\n  /** Port number to bind the server to */\n  port: number\n  /** Custom task store implementation (defaults to InMemoryTaskStore) */\n  taskStore?: any\n  /** Base path for all A2A routes (defaults to '/') */\n  basePath?: string\n  /** Whether to expose the agent card at .well-known/agent.json */\n  exposeAgentCard?: boolean\n  /** Whether to expose default A2A JSON-RPC routes */\n  exposeDefaultRoutes?: boolean\n  /** Custom Express app instance (defaults to new express()) */\n  expressApp?: express.Express\n  /** Custom request handler to override JSON-RPC method handling */\n  customRequestHandler?: any\n  /** Hooks for intercepting requests before/after processing */\n  hooks?: {\n    /** Called before processing any JSON-RPC request */\n    beforeRequest?: (method: string, params: any, req: express.Request) => Promise<void>\n    /** Called after processing any JSON-RPC request */\n    afterRequest?: (method: string, result: any, req: express.Request) => Promise<void>\n    /** Called when a JSON-RPC request fails */\n    onError?: (method: string, error: Error, req: express.Request) => Promise<void>\n  }\n}\n\n/**\n * Result returned by the server start method.\n * Contains the Express app and HTTP server instances for further customization.\n */\nexport interface PaymentsA2AServerResult {\n  /** The configured Express application */\n  app: express.Express\n  /** The HTTP server instance */\n  server: http.Server\n  /** The request handler instance for direct access if needed */\n  handler: PaymentsRequestHandler\n}\n\n/**\n * Middleware to extract bearer token from HTTP headers and store it in the global context.\n * This middleware is applied after A2A routes are set up and extracts authentication\n * information for credit validation.\n *\n * @param req - Express request object\n * @param res - Express response object\n * @param next - Express next function\n */\nfunction _bearerTokenMiddleware(\n  handler: PaymentsRequestHandler,\n  req: express.Request,\n  res: express.Response,\n  next: express.NextFunction,\n) {\n  console.log(`[MIDDLEWARE] Processing ${req.method} ${req.url}`)\n\n  // Only process POST requests (A2A uses POST for all operations)\n  if (req.method !== 'POST') {\n    console.log(`[MIDDLEWARE] Skipping non-POST request`)\n    return next()\n  }\n\n  // Extract bearer token from Authorization header\n  const authHeader = req.headers.authorization\n  let bearerToken: string | undefined\n\n  if (authHeader && authHeader.startsWith('Bearer ')) {\n    bearerToken = authHeader.substring(7) // Remove 'Bearer ' prefix\n    console.log(`[MIDDLEWARE] Extracted bearer token: ${bearerToken.substring(0, 20)}...`)\n  } else {\n    console.log(`[MIDDLEWARE] No bearer token found in headers`)\n  }\n\n  // Transform relative URL to absolute URL\n  const absoluteUrl = new URL(req.url, req.protocol + '://' + req.get('host')).toString()\n  const context = {\n    bearerToken,\n    urlRequested: absoluteUrl,\n    httpMethodRequested: req.method,\n  }\n\n  // Try to associate context with taskId or messageId\n  const taskId = req.body?.taskId || req.body?.id\n  const messageId = req.body?.params?.message?.messageId\n\n  if (taskId) {\n    handler.setHttpRequestContextForTask(taskId, context)\n  } else if (messageId) {\n    handler.setHttpRequestContextForMessage(messageId, context)\n  }\n\n  next()\n}\n\n/**\n * PaymentsA2AServer sets up the A2A endpoints and starts the server.\n *\n * This class provides a complete A2A protocol implementation with payment integration.\n * It handles:\n * - JSON-RPC message routing\n * - Agent card exposure\n * - Bearer token extraction\n * - Credit validation and burning\n * - Task execution and streaming\n * - Customizable routes and handlers\n *\n * @example\n * ```typescript\n * const server = PaymentsA2AServer.start({\n *   agentCard: myAgentCard,\n *   executor: new MyExecutor(),\n *   paymentsService: payments,\n *   port: 41242,\n *   basePath: '/a2a/',\n *   hooks: {\n *     beforeRequest: async (method, params, req) => {\n *       console.log(`Processing ${method} request`)\n *     }\n *   }\n * })\n * ```\n */\nexport class PaymentsA2AServer {\n  /**\n   * Starts the A2A server with the given options.\n   *\n   * This method sets up the complete A2A server infrastructure including:\n   * - Express app configuration\n   * - A2A route setup\n   * - Middleware for bearer token extraction\n   * - Agent card endpoint\n   * - HTTP server creation and binding\n   *\n   * @param options - Server configuration options\n   * @returns Server result containing app, server, adapter, and handler instances\n   *\n   * @example\n   * ```typescript\n   * const result = PaymentsA2AServer.start({\n   *   agentCard: buildPaymentAgentCard(baseCard, paymentMetadata),\n   *   executor: new MyPaymentsExecutor(),\n   *   paymentsService: payments,\n   *   port: 41242,\n   *   basePath: '/a2a/',\n   *   exposeAgentCard: true,\n   *   exposeDefaultRoutes: true\n   * })\n   *\n   * // Access the Express app for additional routes\n   * result.app.get('/health', (req, res) => res.json({ status: 'ok' }))\n   * ```\n   */\n  static start(options: PaymentsA2AServerOptions): PaymentsA2AServerResult {\n    const {\n      agentCard,\n      executor,\n      paymentsService,\n      port,\n      taskStore,\n      basePath = '/',\n      exposeAgentCard = true,\n      exposeDefaultRoutes = true,\n      expressApp,\n      customRequestHandler,\n      hooks,\n    } = options\n\n    // Initialize components\n    const store = taskStore || new InMemoryTaskStore()\n    const handler =\n      customRequestHandler ||\n      new PaymentsRequestHandler(agentCard, store, executor, paymentsService)\n    const appBuilder = new A2AExpressApp(handler)\n\n    const app = expressApp || express()\n\n    // Apply hooks middleware if provided\n    if (hooks) {\n      app.use((req, res, next) => {\n        if (req.method === 'POST' && req.body?.method) {\n          const { method, params } = req.body\n\n          // Apply beforeRequest hook\n          if (hooks.beforeRequest) {\n            hooks.beforeRequest(method, params, req).catch((err) => {\n              console.error('[HOOKS] beforeRequest error:', err)\n            })\n          }\n\n          // Apply afterRequest hook by intercepting res.json\n          const originalJson = res.json\n          res.json = function (data) {\n            if (hooks.afterRequest) {\n              hooks.afterRequest(method, data, req).catch((err) => {\n                console.error('[HOOKS] afterRequest error:', err)\n              })\n            }\n            return originalJson.call(this, data)\n          }\n\n          // Apply onError hook by catching errors\n          const originalSend = res.send\n          res.send = function (data) {\n            if (data?.error && hooks.onError) {\n              hooks\n                .onError(method, new Error(data.error.message || 'Unknown error'), req)\n                .catch((err) => {\n                  console.error('[HOOKS] onError error:', err)\n                })\n            }\n            return originalSend.call(this, data)\n          }\n        }\n        next()\n      })\n    }\n\n    if (exposeDefaultRoutes) {\n      appBuilder.setupRoutes(app, basePath) //, [bearerTokenMiddleware.bind(null, handler)])\n    }\n\n    if (exposeAgentCard) {\n      app.get(`${basePath}.well-known/agent.json`, (req, res) => {\n        res.json(agentCard)\n      })\n    }\n\n    const server = http.createServer(app)\n    server.listen(port, () => {\n      console.log(`[PaymentsA2A] Server started on http://localhost:${port}${basePath}`)\n      if (exposeAgentCard) {\n        console.log(\n          `[PaymentsA2A] Agent Card: http://localhost:${port}${basePath}.well-known/agent.json`,\n        )\n      }\n    })\n\n    return { app, server, handler }\n  }\n}\n"]}

package/dist/a2a/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Types and interfaces for the A2A payments integration.
+ *
+ * This module defines the core types and interfaces used throughout the A2A
+ * payments integration. It provides:
+ * - Task context structures for user executors
+ * - Handler result definitions
+ * - Payment metadata interfaces
+ * - Re-exports of A2A SDK types for convenience
+ *
+ * These types ensure type safety and provide clear contracts between
+ * the user's executor implementation and the payments system.
+ */
+import type { AgentCard, Task, Message, Artifact, TaskState, Part, TaskStatusUpdateEvent, ExecutionEventBus, AgentExecutor, RequestContext, PushNotificationConfig } from '@a2a-js/sdk';
+/**
+ * Context provided to the user's task handler.
+ *
+ * This interface contains all the information available to the user's
+ * executor when handling an A2A task. It includes:
+ * - The original user message
+ * - Any existing task state (for continuation)
+ * - Authentication information
+ * - Request metadata
+ *
+ * The context is created by the PaymentsA2AAdapter and passed to the
+ * user's handleTask method.
+ */
+export interface TaskContext {
+    /** The original message from the user containing the request */
+    userMessage: Message;
+    /** Any existing task state (for task continuation scenarios) */
+    existingTask?: Task;
+    /** Bearer token for authentication and payment validation */
+    bearerToken?: string;
+    /** Additional metadata from the original request */
+    requestMetadata?: Record<string, any>;
+    /**
+     * Emit a streaming event to the client (SSE, WebSocket, etc.) during task execution.
+     * This function allows the executor to send intermediate messages or progress updates.
+     *
+     * @param parts - Array of message parts (text, etc.) to send as a streaming event
+     * @param metadata - Optional metadata to include with the event
+     */
+    emitStreamingEvent?: (parts: Part[], metadata?: Record<string, any>) => void;
+}
+/**
+ * Result returned by the user's task handler.
+ *
+ * This interface defines the structure that user executors must return
+ * from their handleTask method. The result includes:
+ * - Parts that will be converted to A2A Message or Artifact objects
+ * - Optional metadata for payment tracking and other purposes
+ * - Task state information
+ *
+ * The result is processed by the PaymentsA2AAdapter to create the
+ * appropriate A2A protocol objects and handle payment operations.
+ */
+export interface TaskHandlerResult {
+    /** Parts that will be converted to A2A Message or Artifact objects */
+    parts: Part[];
+    /** Optional metadata including payment information and custom data */
+    metadata?: PaymentMetadata & Record<string, any>;
+    /** The final state of the task */
+    state?: TaskState;
+}
+/**
+ * Metadata for payment/credits information to be included in A2A objects.
+ *
+ * This interface defines the payment-related metadata that can be included
+ * in task handler results. This metadata is used for:
+ * - Credit tracking and validation
+ * - Payment processing
+ * - Cost reporting
+ * - Plan management
+ *
+ * The metadata is embedded in A2A Message objects and can be used by
+ * clients to understand the cost of operations.
+ */
+export interface PaymentMetadata {
+    /** Number of credits used for this operation */
+    creditsUsed?: number;
+    /** ID of the payment plan associated with this operation */
+    planId?: string;
+    /** Type of payment model used */
+    paymentType?: 'fixed' | 'dynamic';
+    /** Human-readable description of the cost */
+    costDescription?: string;
+}
+export type { AgentCard, Task, Message, Artifact, TaskState, Part, TaskStatusUpdateEvent, ExecutionEventBus, AgentExecutor, RequestContext, PushNotificationConfig, };
+export type { PaymentsA2AServerOptions } from './server';
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/a2a/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,sBAAsB,EACvB,MAAM,aAAa,CAAA;AAEpB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,WAAW,EAAE,OAAO,CAAA;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,IAAI,CAAA;IACnB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACrC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAA;CAC7E;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,sEAAsE;IACtE,QAAQ,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAChD,kCAAkC;IAClC,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iCAAiC;IACjC,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACjC,6CAA6C;IAC7C,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAGD,YAAY,EACV,SAAS,EACT,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,sBAAsB,GACvB,CAAA;AAGD,YAAY,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAA"}

package/dist/a2a/types.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Types and interfaces for the A2A payments integration.
+ *
+ * This module defines the core types and interfaces used throughout the A2A
+ * payments integration. It provides:
+ * - Task context structures for user executors
+ * - Handler result definitions
+ * - Payment metadata interfaces
+ * - Re-exports of A2A SDK types for convenience
+ *
+ * These types ensure type safety and provide clear contracts between
+ * the user's executor implementation and the payments system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/a2a/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/a2a/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * Types and interfaces for the A2A payments integration.\n *\n * This module defines the core types and interfaces used throughout the A2A\n * payments integration. It provides:\n * - Task context structures for user executors\n * - Handler result definitions\n * - Payment metadata interfaces\n * - Re-exports of A2A SDK types for convenience\n *\n * These types ensure type safety and provide clear contracts between\n * the user's executor implementation and the payments system.\n */\n\nimport type {\n  AgentCard,\n  Task,\n  Message,\n  Artifact,\n  TaskState,\n  Part,\n  TaskStatusUpdateEvent,\n  ExecutionEventBus,\n  AgentExecutor,\n  RequestContext,\n  PushNotificationConfig,\n} from '@a2a-js/sdk'\n\n/**\n * Context provided to the user's task handler.\n *\n * This interface contains all the information available to the user's\n * executor when handling an A2A task. It includes:\n * - The original user message\n * - Any existing task state (for continuation)\n * - Authentication information\n * - Request metadata\n *\n * The context is created by the PaymentsA2AAdapter and passed to the\n * user's handleTask method.\n */\nexport interface TaskContext {\n  /** The original message from the user containing the request */\n  userMessage: Message\n  /** Any existing task state (for task continuation scenarios) */\n  existingTask?: Task\n  /** Bearer token for authentication and payment validation */\n  bearerToken?: string\n  /** Additional metadata from the original request */\n  requestMetadata?: Record<string, any>\n  /**\n   * Emit a streaming event to the client (SSE, WebSocket, etc.) during task execution.\n   * This function allows the executor to send intermediate messages or progress updates.\n   *\n   * @param parts - Array of message parts (text, etc.) to send as a streaming event\n   * @param metadata - Optional metadata to include with the event\n   */\n  emitStreamingEvent?: (parts: Part[], metadata?: Record<string, any>) => void\n}\n\n/**\n * Result returned by the user's task handler.\n *\n * This interface defines the structure that user executors must return\n * from their handleTask method. The result includes:\n * - Parts that will be converted to A2A Message or Artifact objects\n * - Optional metadata for payment tracking and other purposes\n * - Task state information\n *\n * The result is processed by the PaymentsA2AAdapter to create the\n * appropriate A2A protocol objects and handle payment operations.\n */\nexport interface TaskHandlerResult {\n  /** Parts that will be converted to A2A Message or Artifact objects */\n  parts: Part[]\n  /** Optional metadata including payment information and custom data */\n  metadata?: PaymentMetadata & Record<string, any>\n  /** The final state of the task */\n  state?: TaskState\n}\n\n/**\n * Metadata for payment/credits information to be included in A2A objects.\n *\n * This interface defines the payment-related metadata that can be included\n * in task handler results. This metadata is used for:\n * - Credit tracking and validation\n * - Payment processing\n * - Cost reporting\n * - Plan management\n *\n * The metadata is embedded in A2A Message objects and can be used by\n * clients to understand the cost of operations.\n */\nexport interface PaymentMetadata {\n  /** Number of credits used for this operation */\n  creditsUsed?: number\n  /** ID of the payment plan associated with this operation */\n  planId?: string\n  /** Type of payment model used */\n  paymentType?: 'fixed' | 'dynamic'\n  /** Human-readable description of the cost */\n  costDescription?: string\n}\n\n// Re-export A2A SDK types for convenience\nexport type {\n  AgentCard,\n  Task,\n  Message,\n  Artifact,\n  TaskState,\n  Part,\n  TaskStatusUpdateEvent,\n  ExecutionEventBus,\n  AgentExecutor,\n  RequestContext,\n  PushNotificationConfig,\n}\n\n// Re-export server options type for convenience\nexport type { PaymentsA2AServerOptions } from './server'\n"]}

package/dist/api/agents-api.d.ts

@@ -0,0 +1,196 @@
+import { AgentAccessCredentials, AgentAPIAttributes, AgentMetadata, NvmAPIResult, PaginationOptions, PaymentOptions, PlanCreditsConfig, PlanMetadata, PlanPriceConfig } from '../common/types';
+import { BasePaymentsAPI } from './base-payments';
+/**
+ * The AgentsAPI class provides methods to register and interact with AI Agents on Nevermined.
+ */
+export declare class AgentsAPI extends BasePaymentsAPI {
+    /**
+     * This method is used to create a singleton instance of the AgentsAPI class.
+     *
+     * @param options - The options to initialize the payments class.
+     * @returns The instance of the AgentsAPI class.
+     */
+    static getInstance(options: PaymentOptions): AgentsAPI;
+    /**
+     *
+     * It registers a new AI Agent on Nevermined.
+     * The agent must be associated to one or multiple Payment Plans. Users that are subscribers of a payment plan can query the agent.
+     * Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits.
+     * When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.
+     *
+     * @remarks This method is oriented to AI Builders
+     * @remarks To call this method, the NVM API Key must have publication permissions
+     *
+     * @see https://docs.nevermined.app/docs/tutorials/builders/register-agent
+     *
+     * @param agentMetadata - @see {@link AgentMetadata}
+     * @param agentApi - @see {@link AgentAPIAttributes}
+     * @param paymentPlans - the list of payment plans giving access to the agent.
+     *
+     * @example
+     * ```
+     *  const agentMetadata = { name: 'My AI Payments Agent', tags: ['test'] }
+     *  const agentApi = { endpoints: [{ 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' }] }
+     *  const paymentPlans = [planId]
+     *
+     *  const { agentId } = await payments.agents.registerAgent(agentMetadata, agentApi, paymentPlans)
+     * ```
+     *
+     * @returns The unique identifier of the newly created agent (Agent Id).
+     */
+    registerAgent(agentMetadata: AgentMetadata, agentApi: AgentAPIAttributes, paymentPlans: string[]): Promise<{
+        agentId: string;
+    }>;
+    /**
+     *
+     * It registers a new AI Agent and a Payment Plan associated to this new agent.
+     * Depending on the Payment Plan and the configuration of the agent, the usage of the agent/service will consume credits.
+     * When the plan expires (because the time is over or the credits are consumed), the user needs to renew the plan to continue using the agent.
+     *
+     * @remarks This method is oriented to AI Builders
+     * @remarks To call this method, the NVM API Key must have publication permissions
+     *
+     * @see https://docs.nevermined.app/docs/tutorials/builders/register-agent
+     *
+     * @param agentMetadata - @see {@link AgentMetadata}
+     * @param agentApi - @see {@link AgentAPIAttributes}
+     * @param planMetadata - @see {@link PlanMetadata}
+     * @param priceConfig - @see {@link PlanPriceConfig}
+     * @param creditsConfig - @see {@link PlanCreditsConfig}
+     *
+     * @example
+     * ```
+     *  const agentMetadata = { name: 'My AI Payments Agent', tags: ['test'] }
+     *  const agentApi { endpoints: [{ 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' }] }
+     *  const cryptoPriceConfig = getNativeTokenPriceConfig(100n, builderAddress)
+     *  const 1dayDurationPlan = getExpirableDurationConfig(ONE_DAY_DURATION)
+     *  const { agentId, planId } = await payments.agents.registerAgentAndPlan(
+     *    agentMetadata,
+     *    agentApi,
+     *    cryptoPriceConfig,
+     *    1dayDurationPlan
+     *  )
+     * ```
+     *
+     * @returns The unique identifier of the newly created agent (agentId).
+     * @returns The unique identifier of the newly created plan (planId).
+     */
+    registerAgentAndPlan(agentMetadata: AgentMetadata, agentApi: AgentAPIAttributes, planMetadata: PlanMetadata, priceConfig: PlanPriceConfig, creditsConfig: PlanCreditsConfig): Promise<{
+        agentId: string;
+        planId: string;
+        txHash: string;
+    }>;
+    /**
+     * Gets the metadata for a given Agent identifier.
+     *
+     * @param agentId - The unique identifier of the agent.
+     * @returns A promise that resolves to the agent's metadata.
+     * @throws PaymentsError if the agent is not found.
+     *
+     * @example
+     * ```
+     *  const plan = payments.agents.getAgent(agentId)
+     * ```
+     */
+    getAgent(agentId: string): Promise<any>;
+    /**
+     * Gets the list of plans that can be ordered to get access to an agent.
+     *
+     * @param agentId - The unique identifier of the agent.
+     * @param pagination - Optional pagination options to control the number of results returned.p
+     * @returns A promise that resolves to the list of all different plans giving access to the agent.
+     * @throws PaymentsError if the agent is not found.
+     *
+     * @example
+     * ```
+     *  const result = payments.agents.getAgentPlans(planId)
+     *  // {
+     *  //  total: 10,
+     *  //  page: 1,
+     *  //  offset: 5,
+     *  //  plans: [ ..]
+     *  // }
+     * ```
+     */
+    getAgentPlans(agentId: string, pagination?: PaginationOptions): Promise<any>;
+    /**
+     * Adds an existing Payment Plan to an AI Agent.
+     * After this operation, users with access to the Payment Plan will be able to access the AI Agent.
+     *
+     * @remarks
+     * Only the owner of the Payment Plan can call this method.
+     *
+     * @param planId - The unique identifier of the Payment Plan.
+     * @param agentId - The unique identifier of the AI Agent.
+     * @returns  @see {@link NvmAPIResult} A promise that resolves indicating if the operation was successful.
+     * @throws PaymentsError if unable to add the plan to the agent.
+     *
+     * @example
+     * ```
+     * const result = await payments.agents.addPlanToAgent(planId, agentId)
+     * // {
+     * //   txHash: '0x8d29d5769e832a35e53f80cd4e8890d941c50a09c33dbd975533debc894f2535',
+     * //   success: true
+     * // }
+     * ```
+     */
+    addPlanToAgent(planId: string, agentId: string): Promise<NvmAPIResult>;
+    /**
+     * Removes a Payment Plan from an AI Agent.
+     * After this operation, users with access to the Payment Plan will no longer be able to access the AI Agent.
+     *
+     * @remarks
+     * Only the owner of the Payment Plan can call this method.
+     *
+     * @param planId - The unique identifier of the Payment Plan.
+     * @param agentId - The unique identifier of the AI Agent.
+     * @returns  @see {@link NvmAPIResult} A promise that resolves indicating if the operation was successful.
+     * @throws PaymentsError if unable to remove the plan from the agent.
+     *
+     * @example
+     * ```
+     * const result = await payments.agents.removePlanFromAgent(planId, agentId)
+     * // {
+     * //   txHash: '0x8d29d5769e832a35e53f80cd4e8890d941c50a09c33dbd975533debc894f2535',
+     * //   success: true
+     * // }
+     * ```
+     */
+    removePlanFromAgent(planId: string, agentId: string): Promise<NvmAPIResult>;
+    /**
+     * When the user calling this method is a valid subscriber, it generates an access token related to the Payment Plan and the AI Agent.
+     * The access token can be used to query the AI Agent's API endpoints. The access token is unique for the subscriber, payment plan and agent.
+     *
+     * @remarks
+     * Only a valid subscriber of the Payment Plan can generate a valid access token.
+     * @remarks
+     * The access token generated can be send by HTTP Authorization header to query the AI Agent's API endpoints.
+     *
+     * @param planId - The unique identifier of the Payment Plan.
+     * @param agentId - The unique identifier of the AI Agent.
+     * @returns  @see {@link AgentAccessCredentials} The access token and the proxy URL to query the agent.
+     * @throws PaymentsError if unable to remove the plan from the agent.
+     *
+     * @example
+     * ```
+     * const credentials = await payments.agents.getAgentAccessToken(planId, agentId)
+     * // {
+     * //   accessToken: 'eyJhbGciOiJFUzI1NksifQ.eyJpc3MiOiIweD ...',
+     * //   proxies: ['https://proxy.nevermined.network/']
+     * // }
+     *
+     * const agentHTTPOptions = {
+     *   method: 'POST',
+     *   headers: {
+     *   Accept: 'application/json',
+     *   'Content-Type': 'application/json',
+     *   Authorization: `Bearer ${credentials.accessToken}`,
+     *  }
+     * }
+     *
+     * const response = await fetch(new URL(agentEndpoint), agentHTTPOptions)
+     * ```
+     */
+    getAgentAccessToken(planId: string, agentId: string): Promise<AgentAccessCredentials>;
+}
+//# sourceMappingURL=agents-api.d.ts.map

package/dist/api/agents-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-api.d.ts","sourceRoot":"","sources":["../../src/api/agents-api.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EAChB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAWjD;;GAEG;AACH,qBAAa,SAAU,SAAQ,eAAe;IAC5C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS;IAItD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,aAAa,CACxB,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,EAC5B,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAoB/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACU,oBAAoB,CAC/B,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,EAC5B,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,eAAe,EAC5B,aAAa,EAAE,iBAAiB,GAC/B,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;KACf,CAAC;IA8BF;;;;;;;;;;;OAWG;IACU,QAAQ,CAAC,OAAO,EAAE,MAAM;IASrC;;;;;;;;;;;;;;;;;;OAkBG;IACU,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,oBAA0B;IAYhF;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAcnF;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAiBxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACU,mBAAmB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,sBAAsB,CAAC;CAiBnC"}