@nevermined-io/payments 1.6.0 → 1.8.0

package/dist/a2a/types.d.ts

@@ -133,12 +133,42 @@ export interface AgentOptions {
 }
 /**
  * HTTP context associated with a task or message (for internal request tracking).
+ *
+ * INVARIANT — exactly one of two mutually-exclusive states:
+ * - **payment-required**: a payment-gated request arrived with NO token, so only
+ *   `paymentRequired` is set (`bearerToken`/`validation` are absent). The handler
+ *   short-circuits to an `input-required` task instead of executing the agent.
+ * - **authorized**: a token was supplied (in band via `x402.payment.payload` when
+ *   `inBand` is true, else the deprecated `payment-signature` header), so
+ *   `bearerToken` + `validation` are set (`paymentRequired` is absent).
+ *
+ * A `mode`-discriminated union would enforce this at the type level (tracked as a
+ * follow-up); for now consumers guard the field they need — e.g. the settlement
+ * path asserts `bearerToken` + `validation` are present.
  */
 export type HttpRequestContext = {
+    /** Set only in the authorized state. */
     bearerToken?: string;
     urlRequested?: string;
     httpMethodRequested?: string;
-    validation: StartAgentRequest;
+    /** The validated request — set only in the authorized state. */
+    validation?: StartAgentRequest;
+    /**
+     * x402 v2 A2A in-band transport: set by the server middleware when a
+     * payment-gated request arrives with NO token (neither in-band
+     * `x402.payment.payload` nor the deprecated `payment-signature` header). The
+     * handler short-circuits and returns an `input-required` task carrying this
+     * X402PaymentRequired object under `x402.payment.required`, instead of
+     * executing the agent. Set only in the payment-required state.
+     */
+    paymentRequired?: import('../x402/facilitator-api.js').X402PaymentRequired;
+    /**
+     * Whether the bearer token was supplied in band (via `x402.payment.payload`
+     * message metadata) rather than the deprecated `payment-signature` header.
+     * When true, settlement receipts are stamped into the task metadata under the
+     * spec-defined `x402.payment.*` keys.
+     */
+    inBand?: boolean;
 };
 /**
  * Authentication result for A2A requests (equivalent to MCP AuthResult)

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/a2a/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/a2a/types.ts"],"names":[],"mappings":"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"}

package/dist/a2a/types.js.map

@@ -1 +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  TaskArtifactUpdateEvent,\n  PushNotificationConfig,\n  MessageSendParams,\n  SendMessageResponse,\n  TaskQueryParams,\n  GetTaskResponse,\n  TaskPushNotificationConfig,\n  SetTaskPushNotificationConfigResponse,\n  TaskIdParams,\n  GetTaskPushNotificationConfigResponse,\n} from '@a2a-js/sdk'\n\nimport type { ExecutionEventBus, AgentExecutor } from '@a2a-js/sdk/server'\nimport type { StartAgentRequest } from '../common/types.ts'\nimport type { Payments } from '../payments.ts'\n\n/**\n * Union type for A2A streaming events\n *\n * This type represents all possible events that can be yielded by A2A streaming methods.\n * It includes messages, tasks, status updates, and artifact updates.\n */\nexport type A2AStreamEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent\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 * Configuration for credit redemption behavior\n *\n * This interface defines how credits should be redeemed for a specific agent.\n * The configuration is set at the server level and cannot be manipulated by clients.\n */\nexport interface PaymentRedemptionConfig {\n  /** Whether to use batch processing for redemptions */\n  useBatch?: boolean\n  /** Whether to use margin-based redemptions (if false, uses fixed credits) */\n  useMargin?: boolean\n  /** Margin percentage (0-100) when using margin-based redemptions */\n  marginPercent?: number\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  /** Agent ID for payment tracking */\n  agentId?: string\n  /** Configuration for credit redemption behavior */\n  redemptionConfig?: PaymentRedemptionConfig\n}\n\n/**\n * Options required to register or retrieve a client in the registry.\n */\nexport interface ClientRegistryOptions {\n  agentBaseUrl: string\n  agentId: string\n  planId: string\n  agentCardPath?: string\n  delegationConfig?: import('../common/types.js').DelegationConfig\n}\n\n/**\n * Options for agent interaction methods (used by PaymentsClient).\n */\nexport interface AgentOptions {\n  agentId: string\n  planId?: string\n}\n\n/**\n * HTTP context associated with a task or message (for internal request tracking).\n */\nexport type HttpRequestContext = {\n  bearerToken?: string\n  urlRequested?: string\n  httpMethodRequested?: string\n  validation: StartAgentRequest\n}\n\n/**\n * Authentication result for A2A requests (equivalent to MCP AuthResult)\n */\nexport interface A2AAuthResult {\n  /** The agent request ID for tracking */\n  requestId: string\n  /** The bearer token for authentication */\n  token: string\n  /** The agent ID */\n  agentId: string\n  /** The agent request data */\n  agentRequest: StartAgentRequest\n}\n\n/**\n * Agent request context provided to A2A AgentExecutors\n *\n * This context contains all the payment-related data that an AgentExecutor needs\n * to process requests with payment integration. The agent is responsible for\n * calculating and specifying credits in its final response.\n */\nexport interface AgentRequestContext {\n  /** Authentication result with request metadata */\n  authResult: A2AAuthResult\n  /** The HTTP context with request details */\n  httpContext: HttpRequestContext\n  /** The payments service instance for observability and other operations */\n  paymentsService: Payments\n}\n\n/**\n * Base RequestContext interface (local definition based on actual usage)\n *\n * This defines the structure that the A2A SDK RequestContext actually has\n * based on how it's used in PaymentsRequestHandler.\n */\nexport interface RequestContext {\n  /** The original message from the user containing the request */\n  userMessage: Message\n  /** Unique identifier for the task */\n  taskId: string\n  /** Unique identifier for the context/conversation */\n  contextId: string\n  /** Any existing task state (for task continuation scenarios) */\n  task?: Task\n  /** Reference tasks for multi-turn conversations */\n  referenceTasks?: Task[]\n  /** Additional metadata from the original request */\n  requestMetadata?: Record<string, any>\n  /** Any existing task state (for task continuation scenarios) */\n  existingTask?: Task\n}\n\n/**\n * Extended RequestContext with agent request data injection\n *\n * This extends the standard A2A RequestContext to include agent request context\n * while maintaining compatibility with the A2A protocol.\n */\nexport interface PaymentsRequestContext extends RequestContext {\n  /** Agent request context injection (following MCP pattern) */\n  payments?: AgentRequestContext\n}\n\n/**\n * Payments-specific AgentExecutor that uses PaymentsRequestContext\n */\nexport interface PaymentsAgentExecutor {\n  execute(requestContext: PaymentsRequestContext, eventBus: ExecutionEventBus): Promise<void>\n  cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>\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  PushNotificationConfig,\n  MessageSendParams,\n  SendMessageResponse,\n  TaskQueryParams,\n  GetTaskResponse,\n  TaskPushNotificationConfig,\n  SetTaskPushNotificationConfigResponse,\n  TaskIdParams,\n  GetTaskPushNotificationConfigResponse,\n  ExecutionEventBus,\n  AgentExecutor,\n}\n\n// Re-export server options type for convenience\nexport type { PaymentsA2AServerOptions } from './server.ts'\n"]}
+{"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  TaskArtifactUpdateEvent,\n  PushNotificationConfig,\n  MessageSendParams,\n  SendMessageResponse,\n  TaskQueryParams,\n  GetTaskResponse,\n  TaskPushNotificationConfig,\n  SetTaskPushNotificationConfigResponse,\n  TaskIdParams,\n  GetTaskPushNotificationConfigResponse,\n} from '@a2a-js/sdk'\n\nimport type { ExecutionEventBus, AgentExecutor } from '@a2a-js/sdk/server'\nimport type { StartAgentRequest } from '../common/types.ts'\nimport type { Payments } from '../payments.ts'\n\n/**\n * Union type for A2A streaming events\n *\n * This type represents all possible events that can be yielded by A2A streaming methods.\n * It includes messages, tasks, status updates, and artifact updates.\n */\nexport type A2AStreamEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent\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 * Configuration for credit redemption behavior\n *\n * This interface defines how credits should be redeemed for a specific agent.\n * The configuration is set at the server level and cannot be manipulated by clients.\n */\nexport interface PaymentRedemptionConfig {\n  /** Whether to use batch processing for redemptions */\n  useBatch?: boolean\n  /** Whether to use margin-based redemptions (if false, uses fixed credits) */\n  useMargin?: boolean\n  /** Margin percentage (0-100) when using margin-based redemptions */\n  marginPercent?: number\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  /** Agent ID for payment tracking */\n  agentId?: string\n  /** Configuration for credit redemption behavior */\n  redemptionConfig?: PaymentRedemptionConfig\n}\n\n/**\n * Options required to register or retrieve a client in the registry.\n */\nexport interface ClientRegistryOptions {\n  agentBaseUrl: string\n  agentId: string\n  planId: string\n  agentCardPath?: string\n  delegationConfig?: import('../common/types.js').DelegationConfig\n}\n\n/**\n * Options for agent interaction methods (used by PaymentsClient).\n */\nexport interface AgentOptions {\n  agentId: string\n  planId?: string\n}\n\n/**\n * HTTP context associated with a task or message (for internal request tracking).\n *\n * INVARIANT — exactly one of two mutually-exclusive states:\n * - **payment-required**: a payment-gated request arrived with NO token, so only\n *   `paymentRequired` is set (`bearerToken`/`validation` are absent). The handler\n *   short-circuits to an `input-required` task instead of executing the agent.\n * - **authorized**: a token was supplied (in band via `x402.payment.payload` when\n *   `inBand` is true, else the deprecated `payment-signature` header), so\n *   `bearerToken` + `validation` are set (`paymentRequired` is absent).\n *\n * A `mode`-discriminated union would enforce this at the type level (tracked as a\n * follow-up); for now consumers guard the field they need — e.g. the settlement\n * path asserts `bearerToken` + `validation` are present.\n */\nexport type HttpRequestContext = {\n  /** Set only in the authorized state. */\n  bearerToken?: string\n  urlRequested?: string\n  httpMethodRequested?: string\n  /** The validated request — set only in the authorized state. */\n  validation?: StartAgentRequest\n  /**\n   * x402 v2 A2A in-band transport: set by the server middleware when a\n   * payment-gated request arrives with NO token (neither in-band\n   * `x402.payment.payload` nor the deprecated `payment-signature` header). The\n   * handler short-circuits and returns an `input-required` task carrying this\n   * X402PaymentRequired object under `x402.payment.required`, instead of\n   * executing the agent. Set only in the payment-required state.\n   */\n  paymentRequired?: import('../x402/facilitator-api.js').X402PaymentRequired\n  /**\n   * Whether the bearer token was supplied in band (via `x402.payment.payload`\n   * message metadata) rather than the deprecated `payment-signature` header.\n   * When true, settlement receipts are stamped into the task metadata under the\n   * spec-defined `x402.payment.*` keys.\n   */\n  inBand?: boolean\n}\n\n/**\n * Authentication result for A2A requests (equivalent to MCP AuthResult)\n */\nexport interface A2AAuthResult {\n  /** The agent request ID for tracking */\n  requestId: string\n  /** The bearer token for authentication */\n  token: string\n  /** The agent ID */\n  agentId: string\n  /** The agent request data */\n  agentRequest: StartAgentRequest\n}\n\n/**\n * Agent request context provided to A2A AgentExecutors\n *\n * This context contains all the payment-related data that an AgentExecutor needs\n * to process requests with payment integration. The agent is responsible for\n * calculating and specifying credits in its final response.\n */\nexport interface AgentRequestContext {\n  /** Authentication result with request metadata */\n  authResult: A2AAuthResult\n  /** The HTTP context with request details */\n  httpContext: HttpRequestContext\n  /** The payments service instance for observability and other operations */\n  paymentsService: Payments\n}\n\n/**\n * Base RequestContext interface (local definition based on actual usage)\n *\n * This defines the structure that the A2A SDK RequestContext actually has\n * based on how it's used in PaymentsRequestHandler.\n */\nexport interface RequestContext {\n  /** The original message from the user containing the request */\n  userMessage: Message\n  /** Unique identifier for the task */\n  taskId: string\n  /** Unique identifier for the context/conversation */\n  contextId: string\n  /** Any existing task state (for task continuation scenarios) */\n  task?: Task\n  /** Reference tasks for multi-turn conversations */\n  referenceTasks?: Task[]\n  /** Additional metadata from the original request */\n  requestMetadata?: Record<string, any>\n  /** Any existing task state (for task continuation scenarios) */\n  existingTask?: Task\n}\n\n/**\n * Extended RequestContext with agent request data injection\n *\n * This extends the standard A2A RequestContext to include agent request context\n * while maintaining compatibility with the A2A protocol.\n */\nexport interface PaymentsRequestContext extends RequestContext {\n  /** Agent request context injection (following MCP pattern) */\n  payments?: AgentRequestContext\n}\n\n/**\n * Payments-specific AgentExecutor that uses PaymentsRequestContext\n */\nexport interface PaymentsAgentExecutor {\n  execute(requestContext: PaymentsRequestContext, eventBus: ExecutionEventBus): Promise<void>\n  cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>\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  PushNotificationConfig,\n  MessageSendParams,\n  SendMessageResponse,\n  TaskQueryParams,\n  GetTaskResponse,\n  TaskPushNotificationConfig,\n  SetTaskPushNotificationConfigResponse,\n  TaskIdParams,\n  GetTaskPushNotificationConfigResponse,\n  ExecutionEventBus,\n  AgentExecutor,\n}\n\n// Re-export server options type for convenience\nexport type { PaymentsA2AServerOptions } from './server.ts'\n"]}

package/dist/a2a/x402-a2a.d.ts

@@ -0,0 +1,142 @@
+/**
+ * x402 + A2A in-band integration utilities (x402 v2 A2A transport).
+ *
+ * Port of the Python SDK's `payments_py/x402/a2a.py` `X402A2AUtils`. These
+ * helpers bridge the x402 payment protocol with the A2A (Agent-to-Agent)
+ * protocol, signalling payment state *in band* through A2A Task / Message
+ * metadata instead of HTTP status codes and headers.
+ *
+ * The A2A transport equivalent of the MCP transport's `_meta["x402/payment"]`
+ * keys is the A2A **task / message metadata** under the spec-defined
+ * `x402.payment.*` keys (see {@link X402A2AMetadata}). The wire shapes are
+ * defined by:
+ *   - Coinbase x402 v2 A2A transport: specs/transports-v2/a2a.md
+ *   - A2A x402 extension: https://github.com/google-agentic-commerce/a2a-x402
+ *
+ * These constants/keys are part of the specification and MUST NOT be changed.
+ */
+import type { Message, Task } from '@a2a-js/sdk';
+import type { SettlePermissionsResult, X402PaymentRequired } from '../x402/facilitator-api.js';
+/**
+ * Protocol-defined payment states for the A2A x402 flow.
+ *
+ * Tracked in the `x402.payment.status` metadata field. Values are part of the
+ * A2A x402 specification (Section 6: State Management) and must not be changed.
+ */
+export declare enum PaymentStatus {
+    /** Payment requirements sent to client (task state `input-required`). */
+    PAYMENT_REQUIRED = "payment-required",
+    /** Payment payload received by server. */
+    PAYMENT_SUBMITTED = "payment-submitted",
+    /** Payment payload verified by the facilitator. */
+    PAYMENT_VERIFIED = "payment-verified",
+    /** Payment requirements rejected by the client. */
+    PAYMENT_REJECTED = "payment-rejected",
+    /** Payment settled on-chain successfully (task state `completed`). */
+    PAYMENT_COMPLETED = "payment-completed",
+    /** Payment verification or settlement failed (task state `failed`). */
+    PAYMENT_FAILED = "payment-failed"
+}
+/**
+ * Spec-defined A2A task / message metadata keys for the x402 protocol.
+ *
+ * As defined in the A2A x402 specification (Section 6: State Management). These
+ * keys are part of the specification and must not be changed. Note these are
+ * NOT the MCP `_meta["x402/payment"]` keys — A2A signals payment state through
+ * Task / Message `metadata` instead.
+ */
+export declare const X402A2AMetadata: {
+    /** Current payment flow stage. */
+    readonly STATUS_KEY: "x402.payment.status";
+    /** X402PaymentRequired object. */
+    readonly REQUIRED_KEY: "x402.payment.required";
+    /** PaymentPayload object (client → server). */
+    readonly PAYLOAD_KEY: "x402.payment.payload";
+    /** Array of SettleResponse receipts (server → client). */
+    readonly RECEIPTS_KEY: "x402.payment.receipts";
+    /** Error code on failure. */
+    readonly ERROR_KEY: "x402.payment.error";
+};
+/**
+ * Nevermined-specific (non-core-spec) marker set alongside `payment-verified`
+ * when on-chain settlement is **deferred** to a batch process this handler does
+ * not confirm. Lets a client distinguish "verified, will be charged out-of-band"
+ * from a plain verify; spec-only clients ignore the unknown key. Value: `'deferred'`.
+ */
+export declare const X402_SETTLEMENT_DEFERRED_KEY = "x402.payment.settlement";
+/**
+ * Utilities for managing x402 payment state in A2A messages and tasks.
+ *
+ * Provides methods to extract payment status / requirements / payload from
+ * incoming A2A messages and tasks, and to stamp payment-required, verified,
+ * completed and failed state onto outgoing tasks — all via the spec-defined
+ * `x402.payment.*` metadata keys.
+ */
+export declare class X402A2AUtils {
+    static readonly STATUS_KEY: "x402.payment.status";
+    static readonly REQUIRED_KEY: "x402.payment.required";
+    static readonly PAYLOAD_KEY: "x402.payment.payload";
+    static readonly RECEIPTS_KEY: "x402.payment.receipts";
+    static readonly ERROR_KEY: "x402.payment.error";
+    /** Extract the payment status from a Message's metadata, or `undefined`. */
+    getPaymentStatusFromMessage(message?: Message | null): string | undefined;
+    /** Extract the payment status from a Task's status message metadata, or `undefined`. */
+    getPaymentStatus(task?: Task | null): string | undefined;
+    /**
+     * Extract the X402PaymentRequired object from a Message's metadata.
+     *
+     * Returns the raw object (already spec-shaped JSON). Returns `undefined` when
+     * absent or not a plain object.
+     */
+    getPaymentRequirementsFromMessage(message?: Message | null): X402PaymentRequired | undefined;
+    /** Extract the X402PaymentRequired object from a Task's status message metadata. */
+    getPaymentRequirements(task?: Task | null): X402PaymentRequired | undefined;
+    /**
+     * Extract the in-band PaymentPayload object from a Message's metadata.
+     *
+     * The payload is untrusted client input that the server re-encodes into an
+     * access token, so this rejects null, arrays and oversized payloads
+     * (defense-in-depth, parity with the MCP `readPaymentPayload`).
+     *
+     * @returns The PaymentPayload object, or `undefined` when absent/invalid.
+     */
+    getPaymentPayloadFromMessage(message?: Message | null): Record<string, any> | undefined;
+    /** Extract the in-band PaymentPayload object from a Task's status message metadata. */
+    getPaymentPayload(task?: Task | null): Record<string, any> | undefined;
+    /**
+     * Set a Task to the payment-required state (`input-required`) with the
+     * X402PaymentRequired object in `x402.payment.required` metadata.
+     *
+     * Mutates and returns `task` (in place), per the x402 v2 A2A transport.
+     */
+    createPaymentRequiredTask(task: Task, paymentRequired: X402PaymentRequired): Task;
+    /**
+     * Record payment verification on a Task: sets the `x402.payment.status`
+     * metadata to `payment-verified`. Task state is left to the caller (the spec
+     * keeps it `working`).
+     */
+    recordPaymentVerified(task: Task): Task;
+    /**
+     * Record a deferred (batch) settlement on a Task: the payload was verified but
+     * on-chain settlement is deferred out-of-band (the handler never confirms it).
+     * Sets `payment-verified` PLUS the Nevermined `x402.payment.settlement: 'deferred'`
+     * marker, so a client can tell it will be charged out-of-band — distinct from a
+     * plain verify where nothing is owed.
+     */
+    recordPaymentDeferred(task: Task): Task;
+    /**
+     * Record a successful settlement on a Task: sets the `x402.payment.status`
+     * metadata to `payment-completed` and stores the SettleResponse receipt under
+     * `x402.payment.receipts` (an array, per the spec).
+     */
+    recordPaymentSuccess(task: Task, settleResponse?: SettlePermissionsResult): Task;
+    /**
+     * Record a payment failure on a Task: `x402.payment.status = payment-failed`,
+     * the error code under `x402.payment.error`, and (when available) the failed
+     * SettleResponse under `x402.payment.receipts`.
+     */
+    recordPaymentFailure(task: Task, errorCode: string, errorResponse?: SettlePermissionsResult): Task;
+}
+/** Shared singleton, matching the Python `X402A2AUtils()` usage pattern. */
+export declare const x402A2AUtils: X402A2AUtils;
+//# sourceMappingURL=x402-a2a.d.ts.map

package/dist/a2a/x402-a2a.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-a2a.d.ts","sourceRoot":"","sources":["../../src/a2a/x402-a2a.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAc,MAAM,aAAa,CAAA;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAE9F;;;;;GAKG;AACH,oBAAY,aAAa;IACvB,yEAAyE;IACzE,gBAAgB,qBAAqB;IACrC,0CAA0C;IAC1C,iBAAiB,sBAAsB;IACvC,mDAAmD;IACnD,gBAAgB,qBAAqB;IACrC,mDAAmD;IACnD,gBAAgB,qBAAqB;IACrC,sEAAsE;IACtE,iBAAiB,sBAAsB;IACvC,uEAAuE;IACvE,cAAc,mBAAmB;CAClC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;IAC1B,kCAAkC;;IAElC,kCAAkC;;IAElC,+CAA+C;;IAE/C,0DAA0D;;IAE1D,6BAA6B;;CAErB,CAAA;AAEV;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,4BAA4B,CAAA;AAiDrE;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,QAAQ,CAAC,UAAU,wBAA6B;IACvD,MAAM,CAAC,QAAQ,CAAC,YAAY,0BAA+B;IAC3D,MAAM,CAAC,QAAQ,CAAC,WAAW,yBAA8B;IACzD,MAAM,CAAC,QAAQ,CAAC,YAAY,0BAA+B;IAC3D,MAAM,CAAC,QAAQ,CAAC,SAAS,uBAA4B;IAIrD,4EAA4E;IAC5E,2BAA2B,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS;IAMzE,wFAAwF;IACxF,gBAAgB,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS;IAIxD;;;;;OAKG;IACH,iCAAiC,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,mBAAmB,GAAG,SAAS;IAiB5F,oFAAoF;IACpF,sBAAsB,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,mBAAmB,GAAG,SAAS;IAI3E;;;;;;;;OAQG;IACH,4BAA4B,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAYvF,uFAAuF;IACvF,iBAAiB,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAMtE;;;;;OAKG;IACH,yBAAyB,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,mBAAmB,GAAG,IAAI;IAYjF;;;;OAIG;IACH,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAMvC;;;;;;OAMG;IACH,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAOvC;;;;OAIG;IACH,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,uBAAuB,GAAG,IAAI;IAShF;;;;OAIG;IACH,oBAAoB,CAClB,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,uBAAuB,GACtC,IAAI;CASR;AAED,4EAA4E;AAC5E,eAAO,MAAM,YAAY,cAAqB,CAAA"}

package/dist/a2a/x402-a2a.js

@@ -0,0 +1,254 @@
+/**
+ * x402 + A2A in-band integration utilities (x402 v2 A2A transport).
+ *
+ * Port of the Python SDK's `payments_py/x402/a2a.py` `X402A2AUtils`. These
+ * helpers bridge the x402 payment protocol with the A2A (Agent-to-Agent)
+ * protocol, signalling payment state *in band* through A2A Task / Message
+ * metadata instead of HTTP status codes and headers.
+ *
+ * The A2A transport equivalent of the MCP transport's `_meta["x402/payment"]`
+ * keys is the A2A **task / message metadata** under the spec-defined
+ * `x402.payment.*` keys (see {@link X402A2AMetadata}). The wire shapes are
+ * defined by:
+ *   - Coinbase x402 v2 A2A transport: specs/transports-v2/a2a.md
+ *   - A2A x402 extension: https://github.com/google-agentic-commerce/a2a-x402
+ *
+ * These constants/keys are part of the specification and MUST NOT be changed.
+ */
+/**
+ * Protocol-defined payment states for the A2A x402 flow.
+ *
+ * Tracked in the `x402.payment.status` metadata field. Values are part of the
+ * A2A x402 specification (Section 6: State Management) and must not be changed.
+ */
+export var PaymentStatus;
+(function (PaymentStatus) {
+    /** Payment requirements sent to client (task state `input-required`). */
+    PaymentStatus["PAYMENT_REQUIRED"] = "payment-required";
+    /** Payment payload received by server. */
+    PaymentStatus["PAYMENT_SUBMITTED"] = "payment-submitted";
+    /** Payment payload verified by the facilitator. */
+    PaymentStatus["PAYMENT_VERIFIED"] = "payment-verified";
+    /** Payment requirements rejected by the client. */
+    PaymentStatus["PAYMENT_REJECTED"] = "payment-rejected";
+    /** Payment settled on-chain successfully (task state `completed`). */
+    PaymentStatus["PAYMENT_COMPLETED"] = "payment-completed";
+    /** Payment verification or settlement failed (task state `failed`). */
+    PaymentStatus["PAYMENT_FAILED"] = "payment-failed";
+})(PaymentStatus || (PaymentStatus = {}));
+/**
+ * Spec-defined A2A task / message metadata keys for the x402 protocol.
+ *
+ * As defined in the A2A x402 specification (Section 6: State Management). These
+ * keys are part of the specification and must not be changed. Note these are
+ * NOT the MCP `_meta["x402/payment"]` keys — A2A signals payment state through
+ * Task / Message `metadata` instead.
+ */
+export const X402A2AMetadata = {
+    /** Current payment flow stage. */
+    STATUS_KEY: 'x402.payment.status',
+    /** X402PaymentRequired object. */
+    REQUIRED_KEY: 'x402.payment.required',
+    /** PaymentPayload object (client → server). */
+    PAYLOAD_KEY: 'x402.payment.payload',
+    /** Array of SettleResponse receipts (server → client). */
+    RECEIPTS_KEY: 'x402.payment.receipts',
+    /** Error code on failure. */
+    ERROR_KEY: 'x402.payment.error',
+};
+/**
+ * Nevermined-specific (non-core-spec) marker set alongside `payment-verified`
+ * when on-chain settlement is **deferred** to a batch process this handler does
+ * not confirm. Lets a client distinguish "verified, will be charged out-of-band"
+ * from a plain verify; spec-only clients ignore the unknown key. Value: `'deferred'`.
+ */
+export const X402_SETTLEMENT_DEFERRED_KEY = 'x402.payment.settlement';
+/**
+ * Upper bound on the serialized size of an in-band payment payload. The payload
+ * is untrusted client input that gets re-encoded into a token, so cap it as
+ * defense-in-depth (parity with the MCP `readPaymentPayload` and the Python
+ * sibling's `len(json.dumps(value))` guard).
+ */
+const MAX_INBAND_PAYMENT_PAYLOAD_LEN = 64 * 1024;
+/** Type guard: a plain (non-null, non-array) object, mirroring `isinstance(value, dict)`. */
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Read x402 payment metadata from a Message's `metadata`, ignoring non-object values.
+ */
+function metaOf(message) {
+    const metadata = message?.metadata;
+    return isPlainObject(metadata) ? metadata : undefined;
+}
+/**
+ * Ensure a Task has a status with a status message carrying a `metadata` object,
+ * returning that metadata object for mutation by the record* helpers.
+ *
+ * The task is mutated in place (the A2A SDK's ResultManager / event flow operate
+ * on task objects by reference), mirroring the Python `X402A2AUtils` behavior.
+ */
+function ensureStatusMetadata(task, defaultText) {
+    if (!task.status) {
+        task.status = { state: 'working' };
+    }
+    if (!task.status.message) {
+        task.status.message = {
+            kind: 'message',
+            messageId: `${task.id}-status`,
+            role: 'agent',
+            parts: [{ kind: 'text', text: defaultText }],
+            metadata: {},
+        };
+    }
+    if (!isPlainObject(task.status.message.metadata)) {
+        task.status.message.metadata = {};
+    }
+    return task.status.message.metadata;
+}
+/**
+ * Utilities for managing x402 payment state in A2A messages and tasks.
+ *
+ * Provides methods to extract payment status / requirements / payload from
+ * incoming A2A messages and tasks, and to stamp payment-required, verified,
+ * completed and failed state onto outgoing tasks — all via the spec-defined
+ * `x402.payment.*` metadata keys.
+ */
+export class X402A2AUtils {
+    // ---- Extraction (client/server reads) ------------------------------------
+    /** Extract the payment status from a Message's metadata, or `undefined`. */
+    getPaymentStatusFromMessage(message) {
+        const meta = metaOf(message);
+        const value = meta?.[X402A2AUtils.STATUS_KEY];
+        return typeof value === 'string' ? value : undefined;
+    }
+    /** Extract the payment status from a Task's status message metadata, or `undefined`. */
+    getPaymentStatus(task) {
+        return this.getPaymentStatusFromMessage(task?.status?.message);
+    }
+    /**
+     * Extract the X402PaymentRequired object from a Message's metadata.
+     *
+     * Returns the raw object (already spec-shaped JSON). Returns `undefined` when
+     * absent or not a plain object.
+     */
+    getPaymentRequirementsFromMessage(message) {
+        const meta = metaOf(message);
+        const value = meta?.[X402A2AUtils.REQUIRED_KEY];
+        // Structural guard before asserting the typed shape: a valid
+        // X402PaymentRequired is a plain object carrying a numeric `x402Version` and
+        // an `accepts` array. Anything else is treated as absent (never assert the
+        // rich interface over arbitrary, unvalidated metadata).
+        if (!isPlainObject(value) ||
+            typeof value.x402Version !== 'number' ||
+            !Array.isArray(value.accepts)) {
+            return undefined;
+        }
+        return value;
+    }
+    /** Extract the X402PaymentRequired object from a Task's status message metadata. */
+    getPaymentRequirements(task) {
+        return this.getPaymentRequirementsFromMessage(task?.status?.message);
+    }
+    /**
+     * Extract the in-band PaymentPayload object from a Message's metadata.
+     *
+     * The payload is untrusted client input that the server re-encodes into an
+     * access token, so this rejects null, arrays and oversized payloads
+     * (defense-in-depth, parity with the MCP `readPaymentPayload`).
+     *
+     * @returns The PaymentPayload object, or `undefined` when absent/invalid.
+     */
+    getPaymentPayloadFromMessage(message) {
+        const meta = metaOf(message);
+        const value = meta?.[X402A2AUtils.PAYLOAD_KEY];
+        if (!isPlainObject(value)) {
+            return undefined;
+        }
+        if (JSON.stringify(value).length > MAX_INBAND_PAYMENT_PAYLOAD_LEN) {
+            return undefined;
+        }
+        return value;
+    }
+    /** Extract the in-band PaymentPayload object from a Task's status message metadata. */
+    getPaymentPayload(task) {
+        return this.getPaymentPayloadFromMessage(task?.status?.message);
+    }
+    // ---- Stamping (server writes) --------------------------------------------
+    /**
+     * Set a Task to the payment-required state (`input-required`) with the
+     * X402PaymentRequired object in `x402.payment.required` metadata.
+     *
+     * Mutates and returns `task` (in place), per the x402 v2 A2A transport.
+     */
+    createPaymentRequiredTask(task, paymentRequired) {
+        if (!task.status) {
+            task.status = { state: 'input-required' };
+        }
+        else {
+            task.status.state = 'input-required';
+        }
+        const meta = ensureStatusMetadata(task, 'Payment is required for this service.');
+        meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_REQUIRED;
+        meta[X402A2AUtils.REQUIRED_KEY] = paymentRequired;
+        return task;
+    }
+    /**
+     * Record payment verification on a Task: sets the `x402.payment.status`
+     * metadata to `payment-verified`. Task state is left to the caller (the spec
+     * keeps it `working`).
+     */
+    recordPaymentVerified(task) {
+        const meta = ensureStatusMetadata(task, 'Payment verification recorded.');
+        meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_VERIFIED;
+        return task;
+    }
+    /**
+     * Record a deferred (batch) settlement on a Task: the payload was verified but
+     * on-chain settlement is deferred out-of-band (the handler never confirms it).
+     * Sets `payment-verified` PLUS the Nevermined `x402.payment.settlement: 'deferred'`
+     * marker, so a client can tell it will be charged out-of-band — distinct from a
+     * plain verify where nothing is owed.
+     */
+    recordPaymentDeferred(task) {
+        const meta = ensureStatusMetadata(task, 'Payment verified; settlement deferred.');
+        meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_VERIFIED;
+        meta[X402_SETTLEMENT_DEFERRED_KEY] = 'deferred';
+        return task;
+    }
+    /**
+     * Record a successful settlement on a Task: sets the `x402.payment.status`
+     * metadata to `payment-completed` and stores the SettleResponse receipt under
+     * `x402.payment.receipts` (an array, per the spec).
+     */
+    recordPaymentSuccess(task, settleResponse) {
+        const meta = ensureStatusMetadata(task, 'Payment completed successfully.');
+        meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_COMPLETED;
+        if (settleResponse) {
+            meta[X402A2AUtils.RECEIPTS_KEY] = [settleResponse];
+        }
+        return task;
+    }
+    /**
+     * Record a payment failure on a Task: `x402.payment.status = payment-failed`,
+     * the error code under `x402.payment.error`, and (when available) the failed
+     * SettleResponse under `x402.payment.receipts`.
+     */
+    recordPaymentFailure(task, errorCode, errorResponse) {
+        const meta = ensureStatusMetadata(task, 'Payment failed.');
+        meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_FAILED;
+        meta[X402A2AUtils.ERROR_KEY] = errorCode;
+        if (errorResponse) {
+            meta[X402A2AUtils.RECEIPTS_KEY] = [errorResponse];
+        }
+        return task;
+    }
+}
+X402A2AUtils.STATUS_KEY = X402A2AMetadata.STATUS_KEY;
+X402A2AUtils.REQUIRED_KEY = X402A2AMetadata.REQUIRED_KEY;
+X402A2AUtils.PAYLOAD_KEY = X402A2AMetadata.PAYLOAD_KEY;
+X402A2AUtils.RECEIPTS_KEY = X402A2AMetadata.RECEIPTS_KEY;
+X402A2AUtils.ERROR_KEY = X402A2AMetadata.ERROR_KEY;
+/** Shared singleton, matching the Python `X402A2AUtils()` usage pattern. */
+export const x402A2AUtils = new X402A2AUtils();
+//# sourceMappingURL=x402-a2a.js.map

package/dist/a2a/x402-a2a.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-a2a.js","sourceRoot":"","sources":["../../src/a2a/x402-a2a.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * x402 + A2A in-band integration utilities (x402 v2 A2A transport).\n *\n * Port of the Python SDK's `payments_py/x402/a2a.py` `X402A2AUtils`. These\n * helpers bridge the x402 payment protocol with the A2A (Agent-to-Agent)\n * protocol, signalling payment state *in band* through A2A Task / Message\n * metadata instead of HTTP status codes and headers.\n *\n * The A2A transport equivalent of the MCP transport's `_meta[\"x402/payment\"]`\n * keys is the A2A **task / message metadata** under the spec-defined\n * `x402.payment.*` keys (see {@link X402A2AMetadata}). The wire shapes are\n * defined by:\n *   - Coinbase x402 v2 A2A transport: specs/transports-v2/a2a.md\n *   - A2A x402 extension: https://github.com/google-agentic-commerce/a2a-x402\n *\n * These constants/keys are part of the specification and MUST NOT be changed.\n */\n\nimport type { Message, Task, TaskStatus } from '@a2a-js/sdk'\nimport type { SettlePermissionsResult, X402PaymentRequired } from '../x402/facilitator-api.js'\n\n/**\n * Protocol-defined payment states for the A2A x402 flow.\n *\n * Tracked in the `x402.payment.status` metadata field. Values are part of the\n * A2A x402 specification (Section 6: State Management) and must not be changed.\n */\nexport enum PaymentStatus {\n  /** Payment requirements sent to client (task state `input-required`). */\n  PAYMENT_REQUIRED = 'payment-required',\n  /** Payment payload received by server. */\n  PAYMENT_SUBMITTED = 'payment-submitted',\n  /** Payment payload verified by the facilitator. */\n  PAYMENT_VERIFIED = 'payment-verified',\n  /** Payment requirements rejected by the client. */\n  PAYMENT_REJECTED = 'payment-rejected',\n  /** Payment settled on-chain successfully (task state `completed`). */\n  PAYMENT_COMPLETED = 'payment-completed',\n  /** Payment verification or settlement failed (task state `failed`). */\n  PAYMENT_FAILED = 'payment-failed',\n}\n\n/**\n * Spec-defined A2A task / message metadata keys for the x402 protocol.\n *\n * As defined in the A2A x402 specification (Section 6: State Management). These\n * keys are part of the specification and must not be changed. Note these are\n * NOT the MCP `_meta[\"x402/payment\"]` keys — A2A signals payment state through\n * Task / Message `metadata` instead.\n */\nexport const X402A2AMetadata = {\n  /** Current payment flow stage. */\n  STATUS_KEY: 'x402.payment.status',\n  /** X402PaymentRequired object. */\n  REQUIRED_KEY: 'x402.payment.required',\n  /** PaymentPayload object (client → server). */\n  PAYLOAD_KEY: 'x402.payment.payload',\n  /** Array of SettleResponse receipts (server → client). */\n  RECEIPTS_KEY: 'x402.payment.receipts',\n  /** Error code on failure. */\n  ERROR_KEY: 'x402.payment.error',\n} as const\n\n/**\n * Nevermined-specific (non-core-spec) marker set alongside `payment-verified`\n * when on-chain settlement is **deferred** to a batch process this handler does\n * not confirm. Lets a client distinguish \"verified, will be charged out-of-band\"\n * from a plain verify; spec-only clients ignore the unknown key. Value: `'deferred'`.\n */\nexport const X402_SETTLEMENT_DEFERRED_KEY = 'x402.payment.settlement'\n\n/**\n * Upper bound on the serialized size of an in-band payment payload. The payload\n * is untrusted client input that gets re-encoded into a token, so cap it as\n * defense-in-depth (parity with the MCP `readPaymentPayload` and the Python\n * sibling's `len(json.dumps(value))` guard).\n */\nconst MAX_INBAND_PAYMENT_PAYLOAD_LEN = 64 * 1024\n\n/** Type guard: a plain (non-null, non-array) object, mirroring `isinstance(value, dict)`. */\nfunction isPlainObject(value: unknown): value is Record<string, any> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value)\n}\n\n/**\n * Read x402 payment metadata from a Message's `metadata`, ignoring non-object values.\n */\nfunction metaOf(message?: Message | null): Record<string, any> | undefined {\n  const metadata = message?.metadata\n  return isPlainObject(metadata) ? metadata : undefined\n}\n\n/**\n * Ensure a Task has a status with a status message carrying a `metadata` object,\n * returning that metadata object for mutation by the record* helpers.\n *\n * The task is mutated in place (the A2A SDK's ResultManager / event flow operate\n * on task objects by reference), mirroring the Python `X402A2AUtils` behavior.\n */\nfunction ensureStatusMetadata(task: Task, defaultText: string): Record<string, any> {\n  if (!task.status) {\n    task.status = { state: 'working' } as TaskStatus\n  }\n  if (!task.status.message) {\n    task.status.message = {\n      kind: 'message',\n      messageId: `${task.id}-status`,\n      role: 'agent',\n      parts: [{ kind: 'text', text: defaultText }],\n      metadata: {},\n    }\n  }\n  if (!isPlainObject(task.status.message.metadata)) {\n    task.status.message.metadata = {}\n  }\n  return task.status.message.metadata as Record<string, any>\n}\n\n/**\n * Utilities for managing x402 payment state in A2A messages and tasks.\n *\n * Provides methods to extract payment status / requirements / payload from\n * incoming A2A messages and tasks, and to stamp payment-required, verified,\n * completed and failed state onto outgoing tasks — all via the spec-defined\n * `x402.payment.*` metadata keys.\n */\nexport class X402A2AUtils {\n  static readonly STATUS_KEY = X402A2AMetadata.STATUS_KEY\n  static readonly REQUIRED_KEY = X402A2AMetadata.REQUIRED_KEY\n  static readonly PAYLOAD_KEY = X402A2AMetadata.PAYLOAD_KEY\n  static readonly RECEIPTS_KEY = X402A2AMetadata.RECEIPTS_KEY\n  static readonly ERROR_KEY = X402A2AMetadata.ERROR_KEY\n\n  // ---- Extraction (client/server reads) ------------------------------------\n\n  /** Extract the payment status from a Message's metadata, or `undefined`. */\n  getPaymentStatusFromMessage(message?: Message | null): string | undefined {\n    const meta = metaOf(message)\n    const value = meta?.[X402A2AUtils.STATUS_KEY]\n    return typeof value === 'string' ? value : undefined\n  }\n\n  /** Extract the payment status from a Task's status message metadata, or `undefined`. */\n  getPaymentStatus(task?: Task | null): string | undefined {\n    return this.getPaymentStatusFromMessage(task?.status?.message)\n  }\n\n  /**\n   * Extract the X402PaymentRequired object from a Message's metadata.\n   *\n   * Returns the raw object (already spec-shaped JSON). Returns `undefined` when\n   * absent or not a plain object.\n   */\n  getPaymentRequirementsFromMessage(message?: Message | null): X402PaymentRequired | undefined {\n    const meta = metaOf(message)\n    const value = meta?.[X402A2AUtils.REQUIRED_KEY]\n    // Structural guard before asserting the typed shape: a valid\n    // X402PaymentRequired is a plain object carrying a numeric `x402Version` and\n    // an `accepts` array. Anything else is treated as absent (never assert the\n    // rich interface over arbitrary, unvalidated metadata).\n    if (\n      !isPlainObject(value) ||\n      typeof (value as Record<string, unknown>).x402Version !== 'number' ||\n      !Array.isArray((value as Record<string, unknown>).accepts)\n    ) {\n      return undefined\n    }\n    return value as unknown as X402PaymentRequired\n  }\n\n  /** Extract the X402PaymentRequired object from a Task's status message metadata. */\n  getPaymentRequirements(task?: Task | null): X402PaymentRequired | undefined {\n    return this.getPaymentRequirementsFromMessage(task?.status?.message)\n  }\n\n  /**\n   * Extract the in-band PaymentPayload object from a Message's metadata.\n   *\n   * The payload is untrusted client input that the server re-encodes into an\n   * access token, so this rejects null, arrays and oversized payloads\n   * (defense-in-depth, parity with the MCP `readPaymentPayload`).\n   *\n   * @returns The PaymentPayload object, or `undefined` when absent/invalid.\n   */\n  getPaymentPayloadFromMessage(message?: Message | null): Record<string, any> | undefined {\n    const meta = metaOf(message)\n    const value = meta?.[X402A2AUtils.PAYLOAD_KEY]\n    if (!isPlainObject(value)) {\n      return undefined\n    }\n    if (JSON.stringify(value).length > MAX_INBAND_PAYMENT_PAYLOAD_LEN) {\n      return undefined\n    }\n    return value\n  }\n\n  /** Extract the in-band PaymentPayload object from a Task's status message metadata. */\n  getPaymentPayload(task?: Task | null): Record<string, any> | undefined {\n    return this.getPaymentPayloadFromMessage(task?.status?.message)\n  }\n\n  // ---- Stamping (server writes) --------------------------------------------\n\n  /**\n   * Set a Task to the payment-required state (`input-required`) with the\n   * X402PaymentRequired object in `x402.payment.required` metadata.\n   *\n   * Mutates and returns `task` (in place), per the x402 v2 A2A transport.\n   */\n  createPaymentRequiredTask(task: Task, paymentRequired: X402PaymentRequired): Task {\n    if (!task.status) {\n      task.status = { state: 'input-required' } as TaskStatus\n    } else {\n      task.status.state = 'input-required'\n    }\n    const meta = ensureStatusMetadata(task, 'Payment is required for this service.')\n    meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_REQUIRED\n    meta[X402A2AUtils.REQUIRED_KEY] = paymentRequired\n    return task\n  }\n\n  /**\n   * Record payment verification on a Task: sets the `x402.payment.status`\n   * metadata to `payment-verified`. Task state is left to the caller (the spec\n   * keeps it `working`).\n   */\n  recordPaymentVerified(task: Task): Task {\n    const meta = ensureStatusMetadata(task, 'Payment verification recorded.')\n    meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_VERIFIED\n    return task\n  }\n\n  /**\n   * Record a deferred (batch) settlement on a Task: the payload was verified but\n   * on-chain settlement is deferred out-of-band (the handler never confirms it).\n   * Sets `payment-verified` PLUS the Nevermined `x402.payment.settlement: 'deferred'`\n   * marker, so a client can tell it will be charged out-of-band — distinct from a\n   * plain verify where nothing is owed.\n   */\n  recordPaymentDeferred(task: Task): Task {\n    const meta = ensureStatusMetadata(task, 'Payment verified; settlement deferred.')\n    meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_VERIFIED\n    meta[X402_SETTLEMENT_DEFERRED_KEY] = 'deferred'\n    return task\n  }\n\n  /**\n   * Record a successful settlement on a Task: sets the `x402.payment.status`\n   * metadata to `payment-completed` and stores the SettleResponse receipt under\n   * `x402.payment.receipts` (an array, per the spec).\n   */\n  recordPaymentSuccess(task: Task, settleResponse?: SettlePermissionsResult): Task {\n    const meta = ensureStatusMetadata(task, 'Payment completed successfully.')\n    meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_COMPLETED\n    if (settleResponse) {\n      meta[X402A2AUtils.RECEIPTS_KEY] = [settleResponse]\n    }\n    return task\n  }\n\n  /**\n   * Record a payment failure on a Task: `x402.payment.status = payment-failed`,\n   * the error code under `x402.payment.error`, and (when available) the failed\n   * SettleResponse under `x402.payment.receipts`.\n   */\n  recordPaymentFailure(\n    task: Task,\n    errorCode: string,\n    errorResponse?: SettlePermissionsResult,\n  ): Task {\n    const meta = ensureStatusMetadata(task, 'Payment failed.')\n    meta[X402A2AUtils.STATUS_KEY] = PaymentStatus.PAYMENT_FAILED\n    meta[X402A2AUtils.ERROR_KEY] = errorCode\n    if (errorResponse) {\n      meta[X402A2AUtils.RECEIPTS_KEY] = [errorResponse]\n    }\n    return task\n  }\n}\n\n/** Shared singleton, matching the Python `X402A2AUtils()` usage pattern. */\nexport const x402A2AUtils = new X402A2AUtils()\n"]}

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

@@ -132,6 +132,25 @@ export declare class AgentsAPI extends BasePaymentsAPI {
      * ```
      */
     getAgentPlans(agentId: string, pagination?: PaginationOptions): Promise<any>;
+    /**
+     * Lists the AI agents **you** published (the authenticated caller's own
+     * agents). This is account management, not a marketplace search — it never
+     * returns other users' agents.
+     *
+     * @param page - The page number to retrieve.
+     * @param offset - The number of items per page.
+     * @param sortBy - The field to sort the results by.
+     * @param sortOrder - The order in which to sort the results.
+     * @param orgId - Optional organization id. When set, returns every agent in
+     *   that organization (requires active membership) instead of the caller's.
+     * @returns A promise that resolves to the paginated list of your agents.
+     */
+    getAgents(page?: number, offset?: number, sortBy?: string, sortOrder?: 'asc' | 'desc', orgId?: string): Promise<{
+        total: number;
+        page: number;
+        offset: number;
+        agents: 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.

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

@@ -1 +1 @@
-{"version":3,"file":"agents-api.d.ts","sourceRoot":"","sources":["../../src/api/agents-api.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EAChB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAA6B,MAAM,oBAAoB,CAAA;AAWnG,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D;;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,EACtB,kBAAkB,CAAC,EAAE,kBAAkB,GACtC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAsB/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,EAChC,WAAW,CAAC,EAAE,SAAS,GAAG,MAAM,EAChC,kBAAkB,CAAC,EAAE,kBAAkB,GACtC,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;KACf,CAAC;IAyCF;;;;;;;;;;;OAWG;IACU,QAAQ,CAAC,OAAO,EAAE,MAAM;IASrC;;;;;;;;;;;;;;;;OAgBG;IACU,mBAAmB,CAC9B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAcxB;;;;;;;;;;;;;;;;;;OAkBG;IACU,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,oBAA0B;IAWhF;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAYnF;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAczF"}
+{"version":3,"file":"agents-api.d.ts","sourceRoot":"","sources":["../../src/api/agents-api.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EAChB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAA6B,MAAM,oBAAoB,CAAA;AAYnG,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D;;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,EACtB,kBAAkB,CAAC,EAAE,kBAAkB,GACtC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAsB/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,EAChC,WAAW,CAAC,EAAE,SAAS,GAAG,MAAM,EAChC,kBAAkB,CAAC,EAAE,kBAAkB,GACtC,OAAO,CAAC;QACT,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;KACf,CAAC;IA4CF;;;;;;;;;;;OAWG;IACU,QAAQ,CAAC,OAAO,EAAE,MAAM;IASrC;;;;;;;;;;;;;;;;OAgBG;IACU,mBAAmB,CAC9B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAcxB;;;;;;;;;;;;;;;;;;OAkBG;IACU,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,oBAA0B;IAWhF;;;;;;;;;;;;OAYG;IACU,SAAS,CACpB,IAAI,SAAI,EACR,MAAM,SAAM,EACZ,MAAM,SAAY,EAClB,SAAS,GAAE,KAAK,GAAG,MAAe,EAClC,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC;IAc1E;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAYnF;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAiBzF"}