@nevermined-io/payments 1.12.0 → 1.14.0

package/README.md

@@ -286,6 +286,39 @@ const agentHTTPOptions = {
 const response = await fetch(new URL(agentURL), agentHTTPOptions)
 ```
 
+#### Single-Use Access Tokens (v3)
+
+By default an access token is reusable for as long as the plan has credits. Opt
+into a **single-use, seller-bound** token by passing the resource it is for plus
+`tokenVersion: 3`:
+
+```typescript
+// `resource.url` must be the exact string the seller advertises in its 402
+// `paymentRequired`, NOT the URL you fetch — sellers built on this SDK's
+// paymentMiddleware advertise `req.originalUrl`, i.e. a relative path.
+const { accessToken, tokenVersion } = await payments.x402.getX402AccessToken(
+  creditsPlanId,
+  agentId,
+  {
+    delegationConfig: { delegationId },
+    resource: { url: paymentRequired.resource.url }, // e.g. '/ask'
+    httpVerb: 'POST',
+    tokenVersion: 3,
+  },
+)
+```
+
+A v3 token signs `agentId`, `resourceUrl`, `httpVerb` and a one-time `nonce`, so
+it only settles against that one endpoint and is consumed by its first
+settlement — mint a new one per paid request, and never cache it. The
+`resource.url` must be the exact string the seller advertises in its
+`paymentRequired` (origin + path), otherwise verification fails with
+`BCK.X402.0013` — a check that applies to any token carrying a resource, not
+just v3. Settling the token twice fails with `BCK.X402.0059`, which
+`isAccessTokenAlreadyUsed(error)` identifies. Always read the returned `tokenVersion` rather than assuming the
+version you requested: a backend without v3 support silently returns v2. See
+[markdown/x402.md](./markdown/x402.md) for the full contract.
+
 ## MCP (Model Context Protocol)
 
 ### What is MCP?

package/dist/a2a/clientRegistry.d.ts

@@ -15,8 +15,17 @@ export declare class ClientRegistry {
     constructor(payments: Payments);
     /**
      * Gets (or creates) a PaymentsClient for the given agentBaseUrl, agentId, and planId.
-     * The combination of these three is used as a unique key.
+     * That triple plus the requested `tokenVersion` is the cache key.
      * It derives the Agent Card path when needed.
+     *
+     * `tokenVersion` is part of the key rather than ignored on a hit: it decides
+     * whether the client mints a single-use, seller-bound token per paid call or
+     * caches one reusable token for its lifetime. Keying without it would hand a
+     * caller who asked for v3 a client that mints v2 — the security control
+     * dropped silently, with nothing on the returned client to detect it — and,
+     * in the other direction, would put a caller who wanted the cached v2 path on
+     * per-call v3 mints because someone else asked first.
+     *
      * @param options - ClientRegistryOptions with agentBaseUrl, agentId, planId (all required).
      * @returns The PaymentsClient instance
      */

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

@@ -1 +1 @@
-{"version":3,"file":"clientRegistry.d.ts","sourceRoot":"","sources":["../../src/a2a/clientRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAGvD;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,QAAQ,CAAU;IAE1B;;;OAGG;gBACS,QAAQ,EAAE,QAAQ;IAI9B;;;;;;OAMG;IACU,SAAS,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;CAqBhF"}
+{"version":3,"file":"clientRegistry.d.ts","sourceRoot":"","sources":["../../src/a2a/clientRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAGvD;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,QAAQ,CAAU;IAE1B;;;OAGG;gBACS,QAAQ,EAAE,QAAQ;IAI9B;;;;;;;;;;;;;;;OAeG;IACU,SAAS,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;CAuBhF"}

package/dist/a2a/clientRegistry.js

@@ -15,20 +15,29 @@ export class ClientRegistry {
     }
     /**
      * Gets (or creates) a PaymentsClient for the given agentBaseUrl, agentId, and planId.
-     * The combination of these three is used as a unique key.
+     * That triple plus the requested `tokenVersion` is the cache key.
      * It derives the Agent Card path when needed.
+     *
+     * `tokenVersion` is part of the key rather than ignored on a hit: it decides
+     * whether the client mints a single-use, seller-bound token per paid call or
+     * caches one reusable token for its lifetime. Keying without it would hand a
+     * caller who asked for v3 a client that mints v2 — the security control
+     * dropped silently, with nothing on the returned client to detect it — and,
+     * in the other direction, would put a caller who wanted the cached v2 path on
+     * per-call v3 mints because someone else asked first.
+     *
      * @param options - ClientRegistryOptions with agentBaseUrl, agentId, planId (all required).
      * @returns The PaymentsClient instance
      */
     async getClient(options) {
-        const { agentBaseUrl, agentId, planId, agentCardPath, delegationConfig } = options;
+        const { agentBaseUrl, agentId, planId, agentCardPath, delegationConfig, tokenVersion } = options;
         if (!agentBaseUrl || !agentId || !planId) {
             throw PaymentsError.validation('Missing required fields');
         }
-        const key = `${agentBaseUrl}::${agentId}::${planId}`;
+        const key = `${agentBaseUrl}::${agentId}::${planId}::v${tokenVersion ?? 'default'}`;
         let client = this.clients.get(key);
         if (!client) {
-            client = await PaymentsClient.create(agentBaseUrl, this.payments, agentId, planId, agentCardPath, delegationConfig);
+            client = await PaymentsClient.create(agentBaseUrl, this.payments, agentId, planId, agentCardPath, delegationConfig, tokenVersion);
             this.clients.set(key, client);
         }
         return client;

package/dist/a2a/clientRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"clientRegistry.js","sourceRoot":"","sources":["../../src/a2a/clientRegistry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D;;;GAGG;AACH,MAAM,OAAO,cAAc;IAIzB;;;OAGG;IACH,YAAY,QAAkB;QAPtB,YAAO,GAAgC,IAAI,GAAG,EAAE,CAAA;QAQtD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,SAAS,CAAC,OAA8B;QACnD,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAA;QAClF,IAAI,CAAC,YAAY,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;YACzC,MAAM,aAAa,CAAC,UAAU,CAAC,yBAAyB,CAAC,CAAA;QAC3D,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,OAAO,KAAK,MAAM,EAAE,CAAA;QACpD,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,MAAM,cAAc,CAAC,MAAM,CAClC,YAAY,EACZ,IAAI,CAAC,QAAQ,EACb,OAAO,EACP,MAAM,EACN,aAAa,EACb,gBAAgB,CACjB,CAAA;YACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;QAC/B,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;CACF","sourcesContent":["import { Payments } from '../index.js'\nimport { PaymentsClient } from './paymentsClient.js'\nimport type { ClientRegistryOptions } from './types.js'\nimport { PaymentsError } from '../common/payments.error.js'\n\n/**\n * Registry for managing multiple PaymentsClient instances by agentId+planId+baseUrl.\n * If a client does not exist for a given combination, it is created and cached.\n */\nexport class ClientRegistry {\n  private clients: Map<string, PaymentsClient> = new Map()\n  private payments: Payments\n\n  /**\n   * Constructs a ClientRegistry.\n   * @param payments - The Payments instance to use for all clients.\n   */\n  constructor(payments: Payments) {\n    this.payments = payments\n  }\n\n  /**\n   * Gets (or creates) a PaymentsClient for the given agentBaseUrl, agentId, and planId.\n   * The combination of these three is used as a unique key.\n   * It derives the Agent Card path when needed.\n   * @param options - ClientRegistryOptions with agentBaseUrl, agentId, planId (all required).\n   * @returns The PaymentsClient instance\n   */\n  public async getClient(options: ClientRegistryOptions): Promise<PaymentsClient> {\n    const { agentBaseUrl, agentId, planId, agentCardPath, delegationConfig } = options\n    if (!agentBaseUrl || !agentId || !planId) {\n      throw PaymentsError.validation('Missing required fields')\n    }\n\n    const key = `${agentBaseUrl}::${agentId}::${planId}`\n    let client = this.clients.get(key)\n    if (!client) {\n      client = await PaymentsClient.create(\n        agentBaseUrl,\n        this.payments,\n        agentId,\n        planId,\n        agentCardPath,\n        delegationConfig,\n      )\n      this.clients.set(key, client)\n    }\n    return client\n  }\n}\n"]}
+{"version":3,"file":"clientRegistry.js","sourceRoot":"","sources":["../../src/a2a/clientRegistry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D;;;GAGG;AACH,MAAM,OAAO,cAAc;IAIzB;;;OAGG;IACH,YAAY,QAAkB;QAPtB,YAAO,GAAgC,IAAI,GAAG,EAAE,CAAA;QAQtD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACI,KAAK,CAAC,SAAS,CAAC,OAA8B;QACnD,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,GACpF,OAAO,CAAA;QACT,IAAI,CAAC,YAAY,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;YACzC,MAAM,aAAa,CAAC,UAAU,CAAC,yBAAyB,CAAC,CAAA;QAC3D,CAAC;QAED,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,OAAO,KAAK,MAAM,MAAM,YAAY,IAAI,SAAS,EAAE,CAAA;QACnF,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,MAAM,cAAc,CAAC,MAAM,CAClC,YAAY,EACZ,IAAI,CAAC,QAAQ,EACb,OAAO,EACP,MAAM,EACN,aAAa,EACb,gBAAgB,EAChB,YAAY,CACb,CAAA;YACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;QAC/B,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;CACF","sourcesContent":["import { Payments } from '../index.js'\nimport { PaymentsClient } from './paymentsClient.js'\nimport type { ClientRegistryOptions } from './types.js'\nimport { PaymentsError } from '../common/payments.error.js'\n\n/**\n * Registry for managing multiple PaymentsClient instances by agentId+planId+baseUrl.\n * If a client does not exist for a given combination, it is created and cached.\n */\nexport class ClientRegistry {\n  private clients: Map<string, PaymentsClient> = new Map()\n  private payments: Payments\n\n  /**\n   * Constructs a ClientRegistry.\n   * @param payments - The Payments instance to use for all clients.\n   */\n  constructor(payments: Payments) {\n    this.payments = payments\n  }\n\n  /**\n   * Gets (or creates) a PaymentsClient for the given agentBaseUrl, agentId, and planId.\n   * That triple plus the requested `tokenVersion` is the cache key.\n   * It derives the Agent Card path when needed.\n   *\n   * `tokenVersion` is part of the key rather than ignored on a hit: it decides\n   * whether the client mints a single-use, seller-bound token per paid call or\n   * caches one reusable token for its lifetime. Keying without it would hand a\n   * caller who asked for v3 a client that mints v2 — the security control\n   * dropped silently, with nothing on the returned client to detect it — and,\n   * in the other direction, would put a caller who wanted the cached v2 path on\n   * per-call v3 mints because someone else asked first.\n   *\n   * @param options - ClientRegistryOptions with agentBaseUrl, agentId, planId (all required).\n   * @returns The PaymentsClient instance\n   */\n  public async getClient(options: ClientRegistryOptions): Promise<PaymentsClient> {\n    const { agentBaseUrl, agentId, planId, agentCardPath, delegationConfig, tokenVersion } =\n      options\n    if (!agentBaseUrl || !agentId || !planId) {\n      throw PaymentsError.validation('Missing required fields')\n    }\n\n    const key = `${agentBaseUrl}::${agentId}::${planId}::v${tokenVersion ?? 'default'}`\n    let client = this.clients.get(key)\n    if (!client) {\n      client = await PaymentsClient.create(\n        agentBaseUrl,\n        this.payments,\n        agentId,\n        planId,\n        agentCardPath,\n        delegationConfig,\n        tokenVersion,\n      )\n      this.clients.set(key, client)\n    }\n    return client\n  }\n}\n"]}

package/dist/a2a/paymentsClient.d.ts

@@ -1,5 +1,5 @@
 import { Payments } from '../index.js';
-import type { DelegationConfig } from '../common/types.js';
+import type { DelegationConfig, X402TokenVersion } from '../common/types.js';
 import { MessageSendParams, SendMessageResponse, TaskQueryParams, GetTaskResponse, TaskPushNotificationConfig, SetTaskPushNotificationConfigResponse, TaskIdParams, GetTaskPushNotificationConfigResponse, JSONRPCResponse, JSONRPCErrorResponse } from '@a2a-js/sdk';
 import { A2AClient } from '@a2a-js/sdk/client';
 /**
@@ -11,7 +11,10 @@ export declare class PaymentsClient extends A2AClient {
     private readonly agentId;
     private readonly planId;
     private readonly delegationConfig?;
+    private readonly tokenVersion?;
     private accessToken;
+    private lastMintedTokenVersion;
+    private downgradeWarned;
     /**
      * Creates a new PaymentsClient instance.
      * @param agentBaseUrl - The base URL of the agent (e.g. http://localhost:3005/a2a/).
@@ -19,13 +22,14 @@ export declare class PaymentsClient extends A2AClient {
      * @param agentId - The ID of the agent.
      * @param planId - The ID of the plan.
      * @param agentCardPath - Optional path to the agent card relative to base URL (defaults to '.well-known/agent-card.json').
+     * @param tokenVersion - Optional EIP-712 token version to request (`3` = single-use, bound to this agent's endpoint).
      */
     private constructor();
     /**
      * Creates a PaymentsClient by fetching the AgentCard first and then
      * constructing the underlying A2AClient with the AgentCard object.
      */
-    static create(agentBaseUrl: string, payments: Payments, agentId: string, planId: string, agentCardPath?: string, delegationConfig?: DelegationConfig): Promise<PaymentsClient>;
+    static create(agentBaseUrl: string, payments: Payments, agentId: string, planId: string, agentCardPath?: string, delegationConfig?: DelegationConfig, tokenVersion?: X402TokenVersion): Promise<PaymentsClient>;
     /**
      * Fetches a remote agent card, trying the requested (canonical) path first and
      * falling back to the legacy '.well-known/agent.json' so updated clients keep
@@ -34,12 +38,65 @@ export declare class PaymentsClient extends A2AClient {
      */
     private static _fetchAgentCard;
     /**
-     * Gets and caches the access token for this client instance.
+     * The A2A service endpoint this client talks to — the `resource.url` a v3
+     * token is bound to.
+     *
+     * Resolution failures are RAISED, not swallowed. This runs only on the v3
+     * path, where the caller explicitly asked for a seller-bound token: minting
+     * without the resource would hand them a single-use token bound to nothing,
+     * reporting `tokenVersion: 3`, with no signal that half the guarantee was
+     * dropped. Failing here loses a call; failing quietly loses the control.
+     *
+     * The lookup reaches into `_getServiceEndpoint`, which `@a2a-js/sdk` declares
+     * `private` and whose own source says it "can be made synchronous or
+     * deleted" — so a dependency bump can break it. That is exactly why this must
+     * be loud: the alternative is every v3 token silently becoming unbound.
+     */
+    private _resolveResourceUrl;
+    /**
+     * Gets the access token for this client instance, caching it only when the
+     * token is reusable.
+     *
+     * A v2 token is a reusable bearer credential, so it is cached for the client's
+     * lifetime exactly as before. A **v3 token is consumed by its first
+     * settlement**, so caching one would make every paid call after the first
+     * settle against a spent nonce (`BCK.X402.0059`) — a v3 token is therefore
+     * minted per request and never stored.
+     *
+     * The version is read off the minted token, never inferred from what was
+     * requested: a backend that predates the v3 struct silently mints v2, and a
+     * backend whose default has flipped to v3 mints v3 without being asked.
+     *
      * @returns The access token string.
      */
     private _getX402AccessToken;
+    /**
+     * The EIP-712 version of the token this client minted most recently, or
+     * `null` before the first paid call.
+     *
+     * The version a client was constructed with is a *request*; this is what the
+     * backend actually minted. They differ whenever a deployment predates the v3
+     * struct (it drops the field and mints v2) or once its default flips the
+     * other way — so a caller that needs single-use semantics to hold should
+     * check this rather than assume its own argument was honoured.
+     *
+     * Per-client state answering a per-call question: there is no mint lock, so
+     * two concurrent paid calls on a fresh client both mint and the last writer
+     * wins. Today they agree — the backend does not change its answer mid-flight
+     * — but read this before or after a call, not racing one.
+     */
+    getLastMintedTokenVersion(): X402TokenVersion | null;
     /**
      * Clears the cached access token for this client instance.
+     *
+     * A no-op for the token itself when the last one was single-use (v3): those
+     * are never cached. `getLastMintedTokenVersion()` resets to `null` either
+     * way — after a clear there is no token in use, and reporting the version of
+     * one that has been discarded is worse than reporting nothing.
+     *
+     * The downgrade flag is deliberately NOT reset here: it tracks the current
+     * downgrade episode, which a clear does not end. It is cleared when a v3
+     * token is actually minted.
      */
     clearToken(): void;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"paymentsClient.d.ts","sourceRoot":"","sources":["../../src/a2a/paymentsClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAC5E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,0BAA0B,EAC1B,qCAAqC,EACrC,YAAY,EACZ,qCAAqC,EACrC,eAAe,EACf,oBAAoB,EACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAO9C;;;GAGG;AACH,qBAAa,cAAe,SAAQ,SAAS;IACpC,QAAQ,EAAE,QAAQ,CAAA;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAkB;IACpD,OAAO,CAAC,WAAW,CAAe;IAElC;;;;;;;OAOG;IACH,OAAO;IAeP;;;OAGG;WACiB,MAAM,CACxB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,aAAa,SAA6B,EAC1C,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,OAAO,CAAC,cAAc,CAAC;IAK1B;;;;;OAKG;mBACkB,eAAe;IAsCpC;;;OAGG;YACW,mBAAmB;IAyBjC;;OAEG;IACI,UAAU;IAIjB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,2BAA2B;IAQnC;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,QAAQ,IAAI,oBAAoB;IAI5E;;;;OAIG;IACU,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA4BpF;;;;;;;;OAQG;IACW,oBAAoB,CAChC,MAAM,EAAE,iBAAiB,GACxB,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC;IAyDvC;;;;;;;;OAQG;YACY,eAAe;IAoD9B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAuDzB;;;;;;OAMG;IACW,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC;IAsD5F;;;;OAIG;IACU,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAU1E;;;;OAIG;IACU,gCAAgC,CAC3C,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,qCAAqC,CAAC;IASjD;;;;OAIG;IACU,gCAAgC,CAC3C,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,qCAAqC,CAAC;IAUjD;;;;;;OAMG;cACa,0BAA0B,CAAC,OAAO,EAAE,SAAS,EAC3D,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,OAAO,CAAC,SAAS,CAAC;CA2CtB;AAED,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,0BAA0B,EAC1B,qCAAqC,EACrC,YAAY,EACZ,qCAAqC,GACtC,MAAM,aAAa,CAAA"}
+{"version":3,"file":"paymentsClient.d.ts","sourceRoot":"","sources":["../../src/a2a/paymentsClient.ts"],"names":[],"mappings":"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"}

package/dist/a2a/paymentsClient.js

@@ -17,22 +17,26 @@ export class PaymentsClient extends A2AClient {
      * @param agentId - The ID of the agent.
      * @param planId - The ID of the plan.
      * @param agentCardPath - Optional path to the agent card relative to base URL (defaults to '.well-known/agent-card.json').
+     * @param tokenVersion - Optional EIP-712 token version to request (`3` = single-use, bound to this agent's endpoint).
      */
-    constructor(agentCard, payments, agentId, planId, delegationConfig) {
+    constructor(agentCard, payments, agentId, planId, delegationConfig, tokenVersion) {
         super(agentCard);
+        this.lastMintedTokenVersion = null;
+        this.downgradeWarned = false;
         this.payments = payments;
         this.agentId = agentId;
         this.planId = planId;
         this.delegationConfig = delegationConfig;
+        this.tokenVersion = tokenVersion;
         this.accessToken = null;
     }
     /**
      * Creates a PaymentsClient by fetching the AgentCard first and then
      * constructing the underlying A2AClient with the AgentCard object.
      */
-    static async create(agentBaseUrl, payments, agentId, planId, agentCardPath = AGENT_CARD_WELL_KNOWN_PATH, delegationConfig) {
+    static async create(agentBaseUrl, payments, agentId, planId, agentCardPath = AGENT_CARD_WELL_KNOWN_PATH, delegationConfig, tokenVersion) {
         const agentCard = await PaymentsClient._fetchAgentCard(agentBaseUrl, agentCardPath);
-        return new PaymentsClient(agentCard, payments, agentId, planId, delegationConfig);
+        return new PaymentsClient(agentCard, payments, agentId, planId, delegationConfig, tokenVersion);
     }
     /**
      * Fetches a remote agent card, trying the requested (canonical) path first and
@@ -69,7 +73,51 @@ export class PaymentsClient extends A2AClient {
         }
     }
     /**
-     * Gets and caches the access token for this client instance.
+     * The A2A service endpoint this client talks to — the `resource.url` a v3
+     * token is bound to.
+     *
+     * Resolution failures are RAISED, not swallowed. This runs only on the v3
+     * path, where the caller explicitly asked for a seller-bound token: minting
+     * without the resource would hand them a single-use token bound to nothing,
+     * reporting `tokenVersion: 3`, with no signal that half the guarantee was
+     * dropped. Failing here loses a call; failing quietly loses the control.
+     *
+     * The lookup reaches into `_getServiceEndpoint`, which `@a2a-js/sdk` declares
+     * `private` and whose own source says it "can be made synchronous or
+     * deleted" — so a dependency bump can break it. That is exactly why this must
+     * be loud: the alternative is every v3 token silently becoming unbound.
+     */
+    async _resolveResourceUrl() {
+        let endpoint;
+        try {
+            endpoint = await this._getServiceEndpoint();
+        }
+        catch (error) {
+            throw PaymentsError.internal('Could not resolve the A2A service endpoint to bind a tokenVersion 3 access token to: ' +
+                `${error instanceof Error ? error.message : String(error)}. A v3 token is bound to one ` +
+                'resource URL, so it cannot be minted without it. Use tokenVersion 2, or fix the agent ' +
+                'card / service endpoint.');
+        }
+        if (typeof endpoint !== 'string' || endpoint.length === 0) {
+            throw PaymentsError.internal('The A2A service endpoint resolved to an empty value, so a tokenVersion 3 access token ' +
+                'cannot be bound to it. Use tokenVersion 2, or fix the agent card / service endpoint.');
+        }
+        return endpoint;
+    }
+    /**
+     * Gets the access token for this client instance, caching it only when the
+     * token is reusable.
+     *
+     * A v2 token is a reusable bearer credential, so it is cached for the client's
+     * lifetime exactly as before. A **v3 token is consumed by its first
+     * settlement**, so caching one would make every paid call after the first
+     * settle against a spent nonce (`BCK.X402.0059`) — a v3 token is therefore
+     * minted per request and never stored.
+     *
+     * The version is read off the minted token, never inferred from what was
+     * requested: a backend that predates the v3 struct silently mints v2, and a
+     * backend whose default has flipped to v3 mints v3 without being asked.
+     *
      * @returns The access token string.
      */
     async _getX402AccessToken() {
@@ -80,22 +128,95 @@ export class PaymentsClient extends A2AClient {
         if (!this.delegationConfig) {
             throw PaymentsError.internal(`${scheme} scheme requires delegationConfig. Pass it to PaymentsClient.create().`);
         }
+        // The resource binding is attached ONLY when v3 was explicitly requested.
+        // It is not inert on a v2 token: the backend compares the token's
+        // `resource.url` against the seller's `paymentRequired.resource.url`
+        // (origin + path, falling back to an exact string compare for anything it
+        // cannot parse as a URL), so a resource that does not match what the seller
+        // advertises fails verification with `BCK.X402.0013` — a binding nobody
+        // asked for can only cost the caller a failed verify.
+        //
+        // The ABSOLUTE service endpoint is the right string for this client's
+        // counterparty specifically: an A2A seller built on this SDK advertises
+        // `new URL(req.originalUrl, protocol + host)` (`src/a2a/server.ts`), not
+        // the relative `req.originalUrl` that the Express `paymentMiddleware`
+        // advertises for plain HTTP agents. Every A2A call is a POST to the one
+        // JSON-RPC service endpoint, so a single binding covers all of them.
+        let binding = {};
+        if (this.tokenVersion === 3) {
+            binding = {
+                resource: { url: await this._resolveResourceUrl() },
+                httpVerb: 'POST',
+                tokenVersion: 3,
+            };
+        }
         let tokenOptions;
         if (scheme !== 'nvm:erc4337') {
-            tokenOptions = { scheme, delegationConfig: this.delegationConfig };
+            tokenOptions = { scheme, delegationConfig: this.delegationConfig, ...binding };
         }
         else {
-            tokenOptions = { delegationConfig: this.delegationConfig };
+            tokenOptions = { delegationConfig: this.delegationConfig, ...binding };
         }
         const accessParams = await this.payments.x402.getX402AccessToken(this.planId, this.agentId, tokenOptions);
-        this.accessToken = accessParams.accessToken;
-        return this.accessToken;
+        this.lastMintedTokenVersion = accessParams.tokenVersion ?? null;
+        // A caller who asked for v3 and got v2 asked for single-use + seller
+        // binding and received neither. Caching it is still the correct handling of
+        // a genuinely reusable token, but it must not be the only trace: say so
+        // once, and expose the minted version so callers can branch the way
+        // getX402AccessToken's own return value lets them.
+        if (accessParams.tokenVersion === 3) {
+            // The current downgrade episode is over: a later one is new information
+            // and gets its own warning, rather than being swallowed by a flag set
+            // once for the lifetime of the client.
+            this.downgradeWarned = false;
+        }
+        else if (this.tokenVersion === 3 && !this.downgradeWarned) {
+            this.downgradeWarned = true;
+            console.warn(`[x402] tokenVersion 3 was requested but the backend minted v${accessParams.tokenVersion}. ` +
+                'This token is reusable and bound to nothing, and it is cached for the lifetime of this ' +
+                'client. Read PaymentsClient.getLastMintedTokenVersion() to branch on it.');
+        }
+        // Cache unless the token is single-use. Phrased as "not v3" rather than
+        // "is v2" so an unrecognised or missing version keeps today's caching
+        // behaviour instead of silently turning every call into a fresh mint.
+        if (accessParams.tokenVersion !== 3) {
+            this.accessToken = accessParams.accessToken;
+        }
+        return accessParams.accessToken;
+    }
+    /**
+     * The EIP-712 version of the token this client minted most recently, or
+     * `null` before the first paid call.
+     *
+     * The version a client was constructed with is a *request*; this is what the
+     * backend actually minted. They differ whenever a deployment predates the v3
+     * struct (it drops the field and mints v2) or once its default flips the
+     * other way — so a caller that needs single-use semantics to hold should
+     * check this rather than assume its own argument was honoured.
+     *
+     * Per-client state answering a per-call question: there is no mint lock, so
+     * two concurrent paid calls on a fresh client both mint and the last writer
+     * wins. Today they agree — the backend does not change its answer mid-flight
+     * — but read this before or after a call, not racing one.
+     */
+    getLastMintedTokenVersion() {
+        return this.lastMintedTokenVersion;
     }
     /**
      * Clears the cached access token for this client instance.
+     *
+     * A no-op for the token itself when the last one was single-use (v3): those
+     * are never cached. `getLastMintedTokenVersion()` resets to `null` either
+     * way — after a clear there is no token in use, and reporting the version of
+     * one that has been discarded is worse than reporting nothing.
+     *
+     * The downgrade flag is deliberately NOT reset here: it tracks the current
+     * downgrade episode, which a clear does not end. It is cleared when a v3
+     * token is actually minted.
      */
     clearToken() {
         this.accessToken = null;
+        this.lastMintedTokenVersion = null;
     }
     /**
      * Build the in-band x402 message metadata (x402 v2 A2A transport).