@nevermined-io/payments 1.12.0 → 1.14.0

package/dist/x402/token-request.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-request.js","sourceRoot":"","sources":["../../src/x402/token-request.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,EAAoB,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAGxE,MAAM,UAAU,yBAAyB,CAAC,MAKzC;IACC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,GAAG,MAAM,CAAA;IACjE,MAAM,MAAM,GAAG,YAAY,EAAE,MAAM,IAAI,aAAa,CAAA;IACpD,MAAM,OAAO,GAAG,YAAY,EAAE,OAAO,IAAI,iBAAiB,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAEnF,uFAAuF;IACvF,IAAI,CAAC,YAAY,EAAE,gBAAgB,EAAE,CAAC;QACpC,MAAM,aAAa,CAAC,UAAU,CAC5B,oCAAoC,MAAM,qBAAqB;YAC7D,yEAAyE;YACzE,4DAA4D,CAC/D,CAAA;IACH,CAAC;IAED,0EAA0E;IAC1E,yEAAyE;IACzE,uEAAuE;IACvE,wEAAwE;IACxE,wEAAwE;IACxE,wEAAwE;IACxE,0EAA0E;IAC1E,yEAAyE;IACzE,sCAAsC;IACtC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,YAAY,EAAE,GACvF,YAAY,CAAC,gBAAgB,CAAA;IAC/B,4EAA4E;IAC5E,0EAA0E;IAC1E,8EAA8E;IAC9E,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC7D,MAAM,aAAa,CAAC,UAAU,CAC5B,6DAA6D;YAC3D,iDAAiD,CACpD,CAAA;IACH,CAAC;IACD,MAAM,cAAc,GAClB,CAAC,YAAY;QACb,CAAC,MAAM,KAAK,SAAS;YACnB,uBAAuB,KAAK,SAAS;YACrC,kBAAkB,KAAK,SAAS;YAChC,YAAY,KAAK,SAAS,CAAC,CAAA;IAC/B,IAAI,cAAc,EAAE,CAAC;QACnB,yEAAyE;QACzE,wEAAwE;QACxE,oEAAoE;QACpE,qEAAqE;QACrE,OAAO,CAAC,IAAI,CACV,2EAA2E;YACzE,2EAA2E;YAC3E,2EAA2E;YAC3E,iEAAiE,CACpE,CAAA;IACH,CAAC;IAED,kCAAkC;IAClC,OAAO;QACL,QAAQ,EAAE;YACR,MAAM;YACN,OAAO;YACP,MAAM;YACN,KAAK,EAAE;gBACL,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;aAC5B;SACF;QACD,sEAAsE;QACtE,gFAAgF;QAChF,gBAAgB,EAAE,YAAY,CAAC,gBAAgB;KAChD,CAAA;AACH,CAAC","sourcesContent":["/**\n * The access-token request body, shared by the x402 and MPP mints.\n *\n * Both routes take identical inputs — only the EIP-712 domain the backend signs\n * under differs — so the body is built in one place to keep them from drifting.\n */\n\nimport { PaymentsError } from '../common/payments.error.js'\nimport { X402TokenOptions, getDefaultNetwork } from '../common/types.js'\nimport type { EnvironmentName } from '../environments.js'\n\nexport function buildX402TokenRequestBody(params: {\n  planId: string\n  agentId?: string\n  tokenOptions?: X402TokenOptions\n  environmentName: EnvironmentName\n}): Record<string, any> {\n  const { planId, agentId, tokenOptions, environmentName } = params\n  const scheme = tokenOptions?.scheme ?? 'nvm:erc4337'\n  const network = tokenOptions?.network ?? getDefaultNetwork(scheme, environmentName)\n\n  // Validate delegationConfig is provided — the backend requires it for token generation\n  if (!tokenOptions?.delegationConfig) {\n    throw PaymentsError.validation(\n      `delegationConfig is required for ${scheme} token generation. ` +\n        'Create a delegation first with payments.delegation.createDelegation(), ' +\n        'then request the token with delegationConfig.delegationId.',\n    )\n  }\n\n  // Deprecation: the supported flow is create-first — create the delegation\n  // with createDelegation(), then request the token with { delegationId }.\n  // A delegationConfig that carries an inline-create signal instead of a\n  // delegationId triggers inline create-on-the-fly, which the backend has\n  // deprecated (auto-select and providerPaymentMethodId/cardId creation).\n  // Warn once per call; the { delegationId } (± apiKeyId) path is silent.\n  // Predicate mirrors the Python SDK (payments-py#224): no delegationId AND\n  // at least one creation field present — a bare/invalid config is left to\n  // fail downstream rather than warned.\n  const { delegationId, cardId, providerPaymentMethodId, spendingLimitCents, durationSecs } =\n    tokenOptions.delegationConfig\n  // Reject an explicit empty/blank delegationId early — it is neither a valid\n  // reuse id nor an inline-create signal, and forwarding `delegationId: ''`\n  // would 4xx at the backend. (Symmetric with the Python SDK, payments-py#225.)\n  if (delegationId !== undefined && delegationId.trim() === '') {\n    throw PaymentsError.validation(\n      'delegationConfig.delegationId must not be an empty string. ' +\n        'Pass a valid delegation UUID or omit the field.',\n    )\n  }\n  const isInlineCreate =\n    !delegationId &&\n    (cardId !== undefined ||\n      providerPaymentMethodId !== undefined ||\n      spendingLimitCents !== undefined ||\n      durationSecs !== undefined)\n  if (isInlineCreate) {\n    // Neutral wording: this body builder is shared by getX402AccessToken and\n    // the MPP mint (payments.mpp.fetch / getMppAccessToken), so the message\n    // must not name one caller specifically — an MPP buyer grepping for\n    // \"getX402AccessToken\" after seeing this warning would find nothing.\n    console.warn(\n      '[DEPRECATED] delegationConfig: inline create-on-the-fly delegationConfig ' +\n        '(no delegationId) is deprecated and will be removed in a future release. ' +\n        'Create the delegation first with payments.delegation.createDelegation(), ' +\n        'then request the token with delegationConfig: { delegationId }.',\n    )\n  }\n\n  // Build x402-aligned request body\n  return {\n    accepted: {\n      scheme,\n      network,\n      planId,\n      extra: {\n        ...(agentId && { agentId }),\n      },\n    },\n    // Add delegation config for both erc4337 and card-delegation schemes.\n    // delegationConfig is guaranteed present here (the absence check above throws).\n    delegationConfig: tokenOptions.delegationConfig,\n  }\n}\n"]}
+{"version":3,"file":"token-request.js","sourceRoot":"","sources":["../../src/x402/token-request.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The access-token request body, shared by the x402 and MPP mints.\n *\n * Both routes take identical inputs — only the EIP-712 domain the backend signs\n * under differs — so the body is built in one place to keep them from drifting.\n */\n\nimport { PaymentsError } from '../common/payments.error.js'\nimport { X402TokenOptions, getDefaultNetwork } from '../common/types.js'\nimport type { EnvironmentName } from '../environments.js'\n\nexport function buildX402TokenRequestBody(params: {\n  planId: string\n  agentId?: string\n  tokenOptions?: X402TokenOptions\n  environmentName: EnvironmentName\n  /**\n   * Which mint this body is for. MPP has no token version at all — it is not\n   * \"x402 v2 by another name\": the two protocols stopped sharing a version\n   * ladder (nvm-monorepo#3266), and `MppService.createPermission` refuses ANY\n   * `tokenVersion` with `BCK.MPP.0007`, `2` included. Sending one would 400 the\n   * mint, so this builder refuses it here, where the caller can be told why.\n   */\n  protocol?: 'x402' | 'mpp'\n}): Record<string, any> {\n  const { planId, agentId, tokenOptions, environmentName, protocol = 'x402' } = params\n  const scheme = tokenOptions?.scheme ?? 'nvm:erc4337'\n  const network = tokenOptions?.network ?? getDefaultNetwork(scheme, environmentName)\n\n  // Validate delegationConfig is provided — the backend requires it for token generation\n  if (!tokenOptions?.delegationConfig) {\n    throw PaymentsError.validation(\n      `delegationConfig is required for ${scheme} token generation. ` +\n        'Create a delegation first with payments.delegation.createDelegation(), ' +\n        'then request the token with delegationConfig.delegationId.',\n    )\n  }\n\n  // Deprecation: the supported flow is create-first — create the delegation\n  // with createDelegation(), then request the token with { delegationId }.\n  // A delegationConfig that carries an inline-create signal instead of a\n  // delegationId triggers inline create-on-the-fly, which the backend has\n  // deprecated (auto-select and providerPaymentMethodId/cardId creation).\n  // Warn once per call; the { delegationId } (± apiKeyId) path is silent.\n  // Predicate mirrors the Python SDK (payments-py#224): no delegationId AND\n  // at least one creation field present — a bare/invalid config is left to\n  // fail downstream rather than warned.\n  const { delegationId, cardId, providerPaymentMethodId, spendingLimitCents, durationSecs } =\n    tokenOptions.delegationConfig\n  // Reject an explicit empty/blank delegationId early — it is neither a valid\n  // reuse id nor an inline-create signal, and forwarding `delegationId: ''`\n  // would 4xx at the backend. (Symmetric with the Python SDK, payments-py#225.)\n  if (delegationId !== undefined && delegationId.trim() === '') {\n    throw PaymentsError.validation(\n      'delegationConfig.delegationId must not be an empty string. ' +\n        'Pass a valid delegation UUID or omit the field.',\n    )\n  }\n  const isInlineCreate =\n    !delegationId &&\n    (cardId !== undefined ||\n      providerPaymentMethodId !== undefined ||\n      spendingLimitCents !== undefined ||\n      durationSecs !== undefined)\n  if (isInlineCreate) {\n    // Neutral wording: this body builder is shared by getX402AccessToken and\n    // the MPP mint (payments.mpp.fetch / getMppAccessToken), so the message\n    // must not name one caller specifically — an MPP buyer grepping for\n    // \"getX402AccessToken\" after seeing this warning would find nothing.\n    console.warn(\n      '[DEPRECATED] delegationConfig: inline create-on-the-fly delegationConfig ' +\n        '(no delegationId) is deprecated and will be removed in a future release. ' +\n        'Create the delegation first with payments.delegation.createDelegation(), ' +\n        'then request the token with delegationConfig: { delegationId }.',\n    )\n  }\n\n  // `resource` and `httpVerb` are what a v3 token is bound to: they go inside\n  // the EIP-712 signature next to `agentId` and the one-time nonce, so a v3\n  // token minted for one seller endpoint cannot be presented to another.\n  //\n  // On a v1/v2 token they are outside the signature — but NOT inert. The\n  // backend compares a token's `resource.url` against the seller's\n  // `paymentRequired.resource.url` (origin + path, exact string when it cannot\n  // parse either as a URL) for ANY token that carries one, so a v2 token bound\n  // to a URL the seller does not advertise verbatim fails verification with\n  // `BCK.X402.0013`. Measured against staging, not inferred.\n  //\n  // They are still forwarded when the caller supplies them — this is the\n  // low-level builder, and a caller that names a resource means it (binding a\n  // v2 token to the URL the seller really advertises is valid, and once the\n  // backend default flips to v3 the binding is needed without anyone asking for\n  // a version). What the builder will not do is let that happen silently: see\n  // the warning below.\n  //\n  // Omitted rather than sent empty when the caller did not supply them: a field\n  // absent at mint is signed as the empty string AND must stay absent from the\n  // unsigned envelope, so sending `{ url: '' }` and sending nothing must not\n  // diverge — which is why the guard below tests `resource?.url`, not the\n  // object.\n  const { resource, tokenVersion } = tokenOptions\n  // Normalized here, once, rather than in each consumer: sellers advertise\n  // `req.method`, i.e. upper case, and `httpVerb: 'post'` mints a token that\n  // can never match. Both in-tree consumers already upper-cased it themselves;\n  // a direct SDK caller had no such defence.\n  const httpVerb = tokenOptions.httpVerb?.toUpperCase()\n  const boundUrl = resource?.url\n\n  // A binding on a token that is not v3 is legal but rarely intended, and its\n  // failure mode (verify rejecting with BCK.X402.0013 at the seller) points\n  // nowhere near this call. Say so once, here, where the cause is visible.\n  //\n  // MPP gets the same warning for the same reason: the MPP mint accepts\n  // `resource`/`httpVerb` (its DTO is `OmitType(GenerateX402TokenDto,\n  // ['tokenVersion'])`, so only the version is refused) and forwards them into\n  // the same comparison — but MPP has no v3 to opt into, so a binding there is\n  // never signed and can only narrow what the credential verifies against.\n  if (boundUrl || httpVerb) {\n    // A binding on anything but a v3 mint has no good outcome, so it is refused\n    // rather than warned about — the same answer payments-py gives\n    // (`token_request.py`). The presence of `resource.url` is what arms the\n    // backend's endpoint allowlist (`erc4337-scheme.handler.ts`; without it the\n    // backend logs \"resource.url not provided in token … skipping endpoint\n    // validation\"), while a v2 signature binds nothing — so the caller either\n    // arms a check they did not configure (`BCK.PROTOCOL.0031` for an agent\n    // registered with `endpoints`) or fails verification later with\n    // `BCK.X402.0013`. Neither is worth a log line nobody reads at mint time.\n    //\n    // This covers an OMITTED `tokenVersion` as well as an explicit `2`, because\n    // today they mint the same thing: `core-kit`'s minter is\n    // `(options.tokenVersion ?? 2) === 3`, the handler adds no default, and no\n    // versioning gate fills the field in — verified against a live mint, which\n    // comes back v2. Once nvm-monorepo#3292 makes v3 the default (it is open at\n    // the time of writing), the omitted case becomes the shape the backend is\n    // moving to and this guard should narrow to `tokenVersion === 2`.\n    if (protocol === 'x402' && tokenVersion !== 3) {\n      throw PaymentsError.validation(\n        `resource/httpVerb were supplied with tokenVersion ${tokenVersion ?? '(omitted, defaults to 2)'}. ` +\n          'Only a v3 token signs them, so the binding cannot hold — but the backend still ' +\n          'compares the resource against what the seller advertises, and arms its endpoint ' +\n          'allowlist on it. Pass tokenVersion: 3 to bind the token, or drop resource/httpVerb.',\n      )\n    }\n    if (protocol === 'mpp') {\n      // MPP is warned, not refused: it has no v3 to opt into, so there is no\n      // \"correct\" version to point the caller at, and the binding still narrows\n      // what the credential verifies against rather than arming a signature\n      // that cannot hold.\n      console.warn(\n        '[mpp] resource/httpVerb were supplied on an MPP mint. MPP tokens carry no version and ' +\n          'nothing is signed over them, but the backend still compares the resource against what ' +\n          'the seller advertises — a mismatch fails the credential. Omit them unless the string ' +\n          'matches the seller exactly.',\n      )\n    }\n  }\n\n  // MPP's single-use unit is the CHALLENGE, not the token: one MPP access token\n  // is presented across many challenges by design, so the x402 v3 per-token\n  // nonce would kill every buyer's second challenge. The backend enforces this\n  // by refusing the field outright; refuse it here too rather than let the\n  // caller discover it as a 400 whose cause is a field they set two layers up.\n  if (protocol === 'mpp' && tokenVersion !== undefined) {\n    throw PaymentsError.validation(\n      'tokenVersion is not supported on MPP access tokens: MPP and x402 no longer share a ' +\n        'token version ladder, and the backend refuses any tokenVersion on an MPP mint ' +\n        '(BCK.MPP.0007). Omit the field — an MPP token is reusable across challenges, and the ' +\n        'challenge is what is single-use.',\n    )\n  }\n\n  // Build x402-aligned request body\n  return {\n    ...(boundUrl && { resource }),\n    accepted: {\n      scheme,\n      network,\n      planId,\n      extra: {\n        ...(agentId && { agentId }),\n        ...(httpVerb && { httpVerb }),\n      },\n    },\n    // Add delegation config for both erc4337 and card-delegation schemes.\n    // delegationConfig is guaranteed present here (the absence check above throws).\n    delegationConfig: tokenOptions.delegationConfig,\n    // Opt-in only, and x402-only (the MPP guard above has already thrown).\n    // Left out entirely when unset so a v2 mint stays byte-identical to what it\n    // was before v3 existed. A backend that predates the v3 struct drops this\n    // field silently (ValidationPipe whitelists without forbidNonWhitelisted)\n    // and returns v2 — which is why no caller may infer the version from what\n    // it asked for. See detectAccessTokenVersion().\n    //\n    // `tokenVersion: 3` WITHOUT a resource is deliberately allowed, not an\n    // oversight: the backend signs an absent binding member as the empty\n    // string, so the result is a single-use token bound to nothing. That is a\n    // supported mode — single-use without seller binding — and the only one\n    // available when the caller does not know the seller's advertised URL.\n    ...(tokenVersion !== undefined && { tokenVersion }),\n  }\n}\n"]}

package/dist/x402/token-version.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Detecting the EIP-712 version of a minted x402 access token.
+ *
+ * The version is a property of the token you were handed, never of the one you
+ * asked for. The backend's `ValidationPipe` runs with `whitelist: true` and
+ * without `forbidNonWhitelisted`, so a `tokenVersion: 3` sent to a deployment
+ * that predates the v3 struct is dropped **without an error** and a v2 token
+ * comes back. Branching on the requested version would then silently treat a
+ * reusable v2 token as single-use (harmless) or — far worse, once the default
+ * flips — a single-use v3 token as reusable, replaying a spent nonce on every
+ * call after the first.
+ *
+ * The discriminator is `payload.authorization.nonce`: v3 is the first version
+ * to carry one, and it is exactly what makes the token single-use.
+ */
+import type { X402TokenVersion } from '../common/types.js';
+/**
+ * The EIP-712 version the given access token was actually signed under.
+ *
+ * `3` when `payload.authorization.nonce` is a non-empty string, `2` otherwise.
+ *
+ * A token that cannot be decoded also reads as `2`. That is the conservative
+ * answer for a *version* question — v2 is what every pre-v3 token and every
+ * non-Nevermined blob already is — but note it is the permissive answer for the
+ * *reuse* question a caller asks next: `2` means "safe to cache and replay".
+ * The gap is unreachable today, since an undecodable token is unusable anyway
+ * (the backend rejects it on the first presentation, so there is nothing to
+ * replay), but a future change to the envelope format would turn every v3 token
+ * into a cached one here. Any such change must revisit this function first.
+ *
+ * Note this is deliberately NOT the same as trusting the token: nothing here
+ * is verified. It answers "which settle semantics does this token have", which
+ * only the backend's signature check ultimately enforces.
+ *
+ * @param accessToken - The base64-encoded x402 access token
+ * @returns `3` for a single-use, seller/resource-bound token, else `2`
+ *
+ * @example
+ * ```typescript
+ * const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
+ *   delegationConfig: { delegationId },
+ *   // The string the seller advertises, not the URL you fetch.
+ *   resource: { url: '/api/v1/tasks' },
+ *   httpVerb: 'POST',
+ *   tokenVersion: 3,
+ * })
+ * if (detectAccessTokenVersion(accessToken) === 3) {
+ *   // Single-use: mint a new one for the next paid request.
+ * }
+ * ```
+ */
+export declare function detectAccessTokenVersion(accessToken: string): X402TokenVersion;
+/**
+ * Whether the token is consumed by its first successful settlement.
+ *
+ * True exactly for v3 tokens. A caller that caches an access token must test
+ * this before reusing one: settling a spent v3 token fails with
+ * `BCK.X402.0059` (see {@link isAccessTokenAlreadyUsed}).
+ *
+ * @param accessToken - The base64-encoded x402 access token
+ */
+export declare function isSingleUseAccessToken(accessToken: string): boolean;
+/**
+ * Backend code for "this access token was already used".
+ *
+ * Returned by `POST /x402/settle` when a v3 token is settled a second time.
+ * Deliberately not forgery-gated on the backend: it says plainly that the
+ * token was spent, so a client can tell a **spent** token apart from a
+ * declined one (insufficient credits, wrong plan) and from a **forged** one
+ * (`BCK.X402.0005`, an envelope edited to disagree with the signature).
+ */
+export declare const X402_TOKEN_ALREADY_USED_CODE = "BCK.X402.0059";
+/**
+ * Whether an error is the backend refusing a second settlement of the same
+ * single-use token.
+ *
+ * The one correct response is to **mint a new token** — a retry that replays
+ * the same token fails identically forever. Never treat this as a transient
+ * settlement failure.
+ *
+ * @param error - Any thrown value; typically a `PaymentsError` from
+ *   `payments.facilitator.settlePermissions`
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await payments.facilitator.settlePermissions({ paymentRequired, x402AccessToken })
+ * } catch (error) {
+ *   if (isAccessTokenAlreadyUsed(error)) {
+ *     // Re-mint, do not replay.
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export declare function isAccessTokenAlreadyUsed(error: unknown): boolean;
+//# sourceMappingURL=token-version.d.ts.map

package/dist/x402/token-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-version.d.ts","sourceRoot":"","sources":["../../src/x402/token-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAgB1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAU9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,kBAAkB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGhE"}

package/dist/x402/token-version.js

@@ -0,0 +1,127 @@
+/**
+ * Detecting the EIP-712 version of a minted x402 access token.
+ *
+ * The version is a property of the token you were handed, never of the one you
+ * asked for. The backend's `ValidationPipe` runs with `whitelist: true` and
+ * without `forbidNonWhitelisted`, so a `tokenVersion: 3` sent to a deployment
+ * that predates the v3 struct is dropped **without an error** and a v2 token
+ * comes back. Branching on the requested version would then silently treat a
+ * reusable v2 token as single-use (harmless) or — far worse, once the default
+ * flips — a single-use v3 token as reusable, replaying a spent nonce on every
+ * call after the first.
+ *
+ * The discriminator is `payload.authorization.nonce`: v3 is the first version
+ * to carry one, and it is exactly what makes the token single-use.
+ */
+import { decodeAccessToken } from '../utils.js';
+/**
+ * Read the `authorization` object out of a base64 x402 access token.
+ *
+ * Returns `undefined` for anything that is not a decodable token with that
+ * shape, so callers can treat "not a Nevermined token" and "no nonce" the same
+ * way: as not-v3.
+ */
+function readAuthorization(accessToken) {
+    if (typeof accessToken !== 'string' || accessToken.length === 0)
+        return undefined;
+    const decoded = decodeAccessToken(accessToken);
+    const authorization = decoded?.payload?.authorization;
+    return typeof authorization === 'object' && authorization !== null ? authorization : undefined;
+}
+/**
+ * The EIP-712 version the given access token was actually signed under.
+ *
+ * `3` when `payload.authorization.nonce` is a non-empty string, `2` otherwise.
+ *
+ * A token that cannot be decoded also reads as `2`. That is the conservative
+ * answer for a *version* question — v2 is what every pre-v3 token and every
+ * non-Nevermined blob already is — but note it is the permissive answer for the
+ * *reuse* question a caller asks next: `2` means "safe to cache and replay".
+ * The gap is unreachable today, since an undecodable token is unusable anyway
+ * (the backend rejects it on the first presentation, so there is nothing to
+ * replay), but a future change to the envelope format would turn every v3 token
+ * into a cached one here. Any such change must revisit this function first.
+ *
+ * Note this is deliberately NOT the same as trusting the token: nothing here
+ * is verified. It answers "which settle semantics does this token have", which
+ * only the backend's signature check ultimately enforces.
+ *
+ * @param accessToken - The base64-encoded x402 access token
+ * @returns `3` for a single-use, seller/resource-bound token, else `2`
+ *
+ * @example
+ * ```typescript
+ * const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
+ *   delegationConfig: { delegationId },
+ *   // The string the seller advertises, not the URL you fetch.
+ *   resource: { url: '/api/v1/tasks' },
+ *   httpVerb: 'POST',
+ *   tokenVersion: 3,
+ * })
+ * if (detectAccessTokenVersion(accessToken) === 3) {
+ *   // Single-use: mint a new one for the next paid request.
+ * }
+ * ```
+ */
+export function detectAccessTokenVersion(accessToken) {
+    const nonce = readAuthorization(accessToken)?.nonce;
+    // The string check mirrors the backend's own discriminator verbatim
+    // (`AgentX402AccessToken.ts`: `typeof authorization?.nonce === 'string' &&
+    // authorization.nonce.trim() !== ''`), and `generateTokenNonce()` emits 32
+    // bytes of CSPRNG output hex-encoded — a string on the wire, always.
+    // Accepting a non-string nonce as v3 would make this SDK disagree with the
+    // server about what a v3 token is, which is worse than either error it could
+    // prevent.
+    return typeof nonce === 'string' && nonce.trim() !== '' ? 3 : 2;
+}
+/**
+ * Whether the token is consumed by its first successful settlement.
+ *
+ * True exactly for v3 tokens. A caller that caches an access token must test
+ * this before reusing one: settling a spent v3 token fails with
+ * `BCK.X402.0059` (see {@link isAccessTokenAlreadyUsed}).
+ *
+ * @param accessToken - The base64-encoded x402 access token
+ */
+export function isSingleUseAccessToken(accessToken) {
+    return detectAccessTokenVersion(accessToken) === 3;
+}
+/**
+ * Backend code for "this access token was already used".
+ *
+ * Returned by `POST /x402/settle` when a v3 token is settled a second time.
+ * Deliberately not forgery-gated on the backend: it says plainly that the
+ * token was spent, so a client can tell a **spent** token apart from a
+ * declined one (insufficient credits, wrong plan) and from a **forged** one
+ * (`BCK.X402.0005`, an envelope edited to disagree with the signature).
+ */
+export const X402_TOKEN_ALREADY_USED_CODE = 'BCK.X402.0059';
+/**
+ * Whether an error is the backend refusing a second settlement of the same
+ * single-use token.
+ *
+ * The one correct response is to **mint a new token** — a retry that replays
+ * the same token fails identically forever. Never treat this as a transient
+ * settlement failure.
+ *
+ * @param error - Any thrown value; typically a `PaymentsError` from
+ *   `payments.facilitator.settlePermissions`
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await payments.facilitator.settlePermissions({ paymentRequired, x402AccessToken })
+ * } catch (error) {
+ *   if (isAccessTokenAlreadyUsed(error)) {
+ *     // Re-mint, do not replay.
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export function isAccessTokenAlreadyUsed(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    return error.code === X402_TOKEN_ALREADY_USED_CODE;
+}
+//# sourceMappingURL=token-version.js.map

package/dist/x402/token-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-version.js","sourceRoot":"","sources":["../../src/x402/token-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG/C;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,WAAmB;IAC5C,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACjF,MAAM,OAAO,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAA;IAC9C,MAAM,aAAa,GAAG,OAAO,EAAE,OAAO,EAAE,aAAa,CAAA;IACrD,OAAO,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAA;AAChG,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,MAAM,KAAK,GAAG,iBAAiB,CAAC,WAAW,CAAC,EAAE,KAAK,CAAA;IACnD,oEAAoE;IACpE,2EAA2E;IAC3E,2EAA2E;IAC3E,qEAAqE;IACrE,2EAA2E;IAC3E,6EAA6E;IAC7E,WAAW;IACX,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACjE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,OAAO,wBAAwB,CAAC,WAAW,CAAC,KAAK,CAAC,CAAA;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,eAAe,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAC7D,OAAQ,KAA4B,CAAC,IAAI,KAAK,4BAA4B,CAAA;AAC5E,CAAC","sourcesContent":["/**\n * Detecting the EIP-712 version of a minted x402 access token.\n *\n * The version is a property of the token you were handed, never of the one you\n * asked for. The backend's `ValidationPipe` runs with `whitelist: true` and\n * without `forbidNonWhitelisted`, so a `tokenVersion: 3` sent to a deployment\n * that predates the v3 struct is dropped **without an error** and a v2 token\n * comes back. Branching on the requested version would then silently treat a\n * reusable v2 token as single-use (harmless) or — far worse, once the default\n * flips — a single-use v3 token as reusable, replaying a spent nonce on every\n * call after the first.\n *\n * The discriminator is `payload.authorization.nonce`: v3 is the first version\n * to carry one, and it is exactly what makes the token single-use.\n */\n\nimport { decodeAccessToken } from '../utils.js'\nimport type { X402TokenVersion } from '../common/types.js'\n\n/**\n * Read the `authorization` object out of a base64 x402 access token.\n *\n * Returns `undefined` for anything that is not a decodable token with that\n * shape, so callers can treat \"not a Nevermined token\" and \"no nonce\" the same\n * way: as not-v3.\n */\nfunction readAuthorization(accessToken: string): Record<string, any> | undefined {\n  if (typeof accessToken !== 'string' || accessToken.length === 0) return undefined\n  const decoded = decodeAccessToken(accessToken)\n  const authorization = decoded?.payload?.authorization\n  return typeof authorization === 'object' && authorization !== null ? authorization : undefined\n}\n\n/**\n * The EIP-712 version the given access token was actually signed under.\n *\n * `3` when `payload.authorization.nonce` is a non-empty string, `2` otherwise.\n *\n * A token that cannot be decoded also reads as `2`. That is the conservative\n * answer for a *version* question — v2 is what every pre-v3 token and every\n * non-Nevermined blob already is — but note it is the permissive answer for the\n * *reuse* question a caller asks next: `2` means \"safe to cache and replay\".\n * The gap is unreachable today, since an undecodable token is unusable anyway\n * (the backend rejects it on the first presentation, so there is nothing to\n * replay), but a future change to the envelope format would turn every v3 token\n * into a cached one here. Any such change must revisit this function first.\n *\n * Note this is deliberately NOT the same as trusting the token: nothing here\n * is verified. It answers \"which settle semantics does this token have\", which\n * only the backend's signature check ultimately enforces.\n *\n * @param accessToken - The base64-encoded x402 access token\n * @returns `3` for a single-use, seller/resource-bound token, else `2`\n *\n * @example\n * ```typescript\n * const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {\n *   delegationConfig: { delegationId },\n *   // The string the seller advertises, not the URL you fetch.\n *   resource: { url: '/api/v1/tasks' },\n *   httpVerb: 'POST',\n *   tokenVersion: 3,\n * })\n * if (detectAccessTokenVersion(accessToken) === 3) {\n *   // Single-use: mint a new one for the next paid request.\n * }\n * ```\n */\nexport function detectAccessTokenVersion(accessToken: string): X402TokenVersion {\n  const nonce = readAuthorization(accessToken)?.nonce\n  // The string check mirrors the backend's own discriminator verbatim\n  // (`AgentX402AccessToken.ts`: `typeof authorization?.nonce === 'string' &&\n  // authorization.nonce.trim() !== ''`), and `generateTokenNonce()` emits 32\n  // bytes of CSPRNG output hex-encoded — a string on the wire, always.\n  // Accepting a non-string nonce as v3 would make this SDK disagree with the\n  // server about what a v3 token is, which is worse than either error it could\n  // prevent.\n  return typeof nonce === 'string' && nonce.trim() !== '' ? 3 : 2\n}\n\n/**\n * Whether the token is consumed by its first successful settlement.\n *\n * True exactly for v3 tokens. A caller that caches an access token must test\n * this before reusing one: settling a spent v3 token fails with\n * `BCK.X402.0059` (see {@link isAccessTokenAlreadyUsed}).\n *\n * @param accessToken - The base64-encoded x402 access token\n */\nexport function isSingleUseAccessToken(accessToken: string): boolean {\n  return detectAccessTokenVersion(accessToken) === 3\n}\n\n/**\n * Backend code for \"this access token was already used\".\n *\n * Returned by `POST /x402/settle` when a v3 token is settled a second time.\n * Deliberately not forgery-gated on the backend: it says plainly that the\n * token was spent, so a client can tell a **spent** token apart from a\n * declined one (insufficient credits, wrong plan) and from a **forged** one\n * (`BCK.X402.0005`, an envelope edited to disagree with the signature).\n */\nexport const X402_TOKEN_ALREADY_USED_CODE = 'BCK.X402.0059'\n\n/**\n * Whether an error is the backend refusing a second settlement of the same\n * single-use token.\n *\n * The one correct response is to **mint a new token** — a retry that replays\n * the same token fails identically forever. Never treat this as a transient\n * settlement failure.\n *\n * @param error - Any thrown value; typically a `PaymentsError` from\n *   `payments.facilitator.settlePermissions`\n *\n * @example\n * ```typescript\n * try {\n *   await payments.facilitator.settlePermissions({ paymentRequired, x402AccessToken })\n * } catch (error) {\n *   if (isAccessTokenAlreadyUsed(error)) {\n *     // Re-mint, do not replay.\n *   }\n *   throw error\n * }\n * ```\n */\nexport function isAccessTokenAlreadyUsed(error: unknown): boolean {\n  if (typeof error !== 'object' || error === null) return false\n  return (error as { code?: unknown }).code === X402_TOKEN_ALREADY_USED_CODE\n}\n"]}

package/dist/x402/token.d.ts

@@ -5,7 +5,7 @@
  * Tokens are used to authorize payment verification and settlement.
  */
 import { BasePaymentsAPI } from '../api/base-payments.js';
-import { PaymentOptions, X402TokenOptions } from '../common/types.js';
+import { PaymentOptions, X402TokenOptions, X402TokenVersion } from '../common/types.js';
 /**
  * X402 Token API for generating access tokens.
  *
@@ -32,11 +32,20 @@ export declare class X402TokenAPI extends BasePaymentsAPI {
      * (spending limits / `providerPaymentMethodId` / `cardId`, i.e. no
      * `delegationId`) is **deprecated** and emits a runtime warning.
      *
+     * Pass `resource` / `httpVerb` to bind the token to one seller endpoint, and
+     * `tokenVersion: 3` to ask for the single-use, seller/resource-bound token.
+     * v3 is opt-in and the request may be silently downgraded by a backend that
+     * predates it, so the returned `tokenVersion` is read off the minted token
+     * rather than echoed back from the request — branch on that, never on what
+     * you asked for.
+     *
      * @param planId - The unique identifier of the payment plan
      * @param agentId - The unique identifier of the AI agent (optional)
-     * @param tokenOptions - Options controlling scheme and delegation behavior (optional)
+     * @param tokenOptions - Options controlling scheme, resource binding, token version and delegation behavior (optional)
      * @returns A promise that resolves to an object containing:
      *   - accessToken: The X402 access token string
+     *   - tokenVersion: The EIP-712 version the returned token was actually signed
+     *     under (`3` means single-use — mint a new token per paid request)
      *
      * @throws PaymentsError if the request fails
      *
@@ -53,9 +62,31 @@ export declare class X402TokenAPI extends BasePaymentsAPI {
      *   delegationConfig: { delegationId },
      * })
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Single-use, bound to one seller endpoint. Mint one per paid request.
+     * // `resource.url` must be the string the seller advertises in its 402
+     * // `paymentRequired` — sellers built on this SDK's `paymentMiddleware`
+     * // advertise `req.originalUrl`, i.e. a relative path.
+     * const { accessToken, tokenVersion } = await payments.x402.getX402AccessToken(
+     *   planId,
+     *   agentId,
+     *   {
+     *     delegationConfig: { delegationId },
+     *     resource: { url: '/api/v1/tasks' },
+     *     httpVerb: 'POST',
+     *     tokenVersion: 3,
+     *   },
+     * )
+     * if (tokenVersion === 2) {
+     *   // The backend does not support v3 yet; this token is still reusable.
+     * }
+     * ```
      */
     getX402AccessToken(planId: string, agentId?: string, tokenOptions?: X402TokenOptions): Promise<{
         accessToken: string;
+        tokenVersion: X402TokenVersion;
         [key: string]: any;
     }>;
 }

package/dist/x402/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAGzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAGrE;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY;IAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,gBAAgB,GAC9B,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;CAmCxD"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAGzD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAIvF;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY;IAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,gBAAgB,GAC9B,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,gBAAgB,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,CAAC;CAmDxF"}

package/dist/x402/token.js

@@ -8,6 +8,7 @@ import { BasePaymentsAPI } from '../api/base-payments.js';
 import { API_URL_CREATE_PERMISSION } from '../api/nvm-api.js';
 import { PaymentsError } from '../common/payments.error.js';
 import { buildX402TokenRequestBody } from './token-request.js';
+import { detectAccessTokenVersion } from './token-version.js';
 /**
  * X402 Token API for generating access tokens.
  *
@@ -36,11 +37,20 @@ export class X402TokenAPI extends BasePaymentsAPI {
      * (spending limits / `providerPaymentMethodId` / `cardId`, i.e. no
      * `delegationId`) is **deprecated** and emits a runtime warning.
      *
+     * Pass `resource` / `httpVerb` to bind the token to one seller endpoint, and
+     * `tokenVersion: 3` to ask for the single-use, seller/resource-bound token.
+     * v3 is opt-in and the request may be silently downgraded by a backend that
+     * predates it, so the returned `tokenVersion` is read off the minted token
+     * rather than echoed back from the request — branch on that, never on what
+     * you asked for.
+     *
      * @param planId - The unique identifier of the payment plan
      * @param agentId - The unique identifier of the AI agent (optional)
-     * @param tokenOptions - Options controlling scheme and delegation behavior (optional)
+     * @param tokenOptions - Options controlling scheme, resource binding, token version and delegation behavior (optional)
      * @returns A promise that resolves to an object containing:
      *   - accessToken: The X402 access token string
+     *   - tokenVersion: The EIP-712 version the returned token was actually signed
+     *     under (`3` means single-use — mint a new token per paid request)
      *
      * @throws PaymentsError if the request fails
      *
@@ -57,6 +67,27 @@ export class X402TokenAPI extends BasePaymentsAPI {
      *   delegationConfig: { delegationId },
      * })
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Single-use, bound to one seller endpoint. Mint one per paid request.
+     * // `resource.url` must be the string the seller advertises in its 402
+     * // `paymentRequired` — sellers built on this SDK's `paymentMiddleware`
+     * // advertise `req.originalUrl`, i.e. a relative path.
+     * const { accessToken, tokenVersion } = await payments.x402.getX402AccessToken(
+     *   planId,
+     *   agentId,
+     *   {
+     *     delegationConfig: { delegationId },
+     *     resource: { url: '/api/v1/tasks' },
+     *     httpVerb: 'POST',
+     *     tokenVersion: 3,
+     *   },
+     * )
+     * if (tokenVersion === 2) {
+     *   // The backend does not support v3 yet; this token is still reusable.
+     * }
+     * ```
      */
     async getX402AccessToken(planId, agentId, tokenOptions) {
         const urlPath = API_URL_CREATE_PERMISSION;
@@ -81,7 +112,21 @@ export class X402TokenAPI extends BasePaymentsAPI {
                 }
                 throw PaymentsError.internal(`${errorMessage} (HTTP ${response.status})`);
             }
-            return await response.json();
+            const result = await response.json();
+            // A 2xx with no usable token is a broken response, not a token: without
+            // this guard the caller gets `{ accessToken: undefined }` typed as
+            // `string`, sends `undefined` as the `payment-signature`, and the failure
+            // surfaces at the seller as an unparseable token — three layers from the
+            // cause.
+            if (typeof result?.accessToken !== 'string' || result.accessToken.length === 0) {
+                throw PaymentsError.internal('X402 token request succeeded but the response carried no accessToken');
+            }
+            // Detected, never echoed: `tokenVersion: 3` is dropped without an error by
+            // a backend that predates the v3 struct, so the only trustworthy source of
+            // the version is the token itself. The override after the spread is
+            // deliberate — a `tokenVersion` echoed by the backend is discarded in
+            // favour of the one read off the token.
+            return { ...result, tokenVersion: detectAccessTokenVersion(result.accessToken) };
         }
         catch (error) {
             if (error instanceof PaymentsError) {

package/dist/x402/token.js.map

@@ -1 +1 @@
-{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAuB;QACxC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,KAAK,CAAC,kBAAkB,CACtB,MAAc,EACd,OAAgB,EAChB,YAA+B;QAE/B,MAAM,OAAO,GAAG,yBAAyB,CAAA;QACzC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAEtD,MAAM,IAAI,GAAG,yBAAyB,CAAC;YACrC,MAAM;YACN,OAAO;YACP,YAAY;YACZ,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,CAAC,CAAA;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAExD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC1C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,YAAY,GAAG,wCAAwC,CAAA;gBAC3D,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;oBACvC,YAAY,GAAG,SAAS,CAAC,OAAO,IAAI,YAAY,CAAA;gBAClD,CAAC;gBAAC,MAAM,CAAC;oBACP,4BAA4B;gBAC9B,CAAC;gBACD,MAAM,aAAa,CAAC,QAAQ,CAAC,GAAG,YAAY,UAAU,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAA;YAC3E,CAAC;YACD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,MAAM,KAAK,CAAA;YACb,CAAC;YACD,MAAM,aAAa,CAAC,QAAQ,CAC1B,uDAAuD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAChH,CAAA;QACH,CAAC;IACH,CAAC;CACF","sourcesContent":["/**\n * X402 Token Generation API.\n *\n * Provides X402 access token generation functionality for subscribers.\n * Tokens are used to authorize payment verification and settlement.\n */\n\nimport { BasePaymentsAPI } from '../api/base-payments.js'\nimport { API_URL_CREATE_PERMISSION } from '../api/nvm-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, X402TokenOptions } from '../common/types.js'\nimport { buildX402TokenRequestBody } from './token-request.js'\n\n/**\n * X402 Token API for generating access tokens.\n *\n * Handles X402 access token generation for subscribers to authorize\n * payment operations with AI agents.\n */\nexport class X402TokenAPI extends BasePaymentsAPI {\n  /**\n   * Get a singleton instance of the X402TokenAPI class.\n   *\n   * @param options - The options to initialize the API\n   * @returns The instance of the X402TokenAPI class\n   */\n  static getInstance(options: PaymentOptions): X402TokenAPI {\n    return new X402TokenAPI(options)\n  }\n\n  /**\n   * Get an X402 access token for the given plan, backed by a delegation.\n   *\n   * This token allows the agent to verify and settle delegations on behalf\n   * of the subscriber.\n   *\n   * The supported flow is **create-first**: create the delegation once with\n   * {@link DelegationAPI.createDelegation}, then pass its `delegationId` in\n   * `tokenOptions.delegationConfig`. Passing inline create-on-the-fly fields\n   * (spending limits / `providerPaymentMethodId` / `cardId`, i.e. no\n   * `delegationId`) is **deprecated** and emits a runtime warning.\n   *\n   * @param planId - The unique identifier of the payment plan\n   * @param agentId - The unique identifier of the AI agent (optional)\n   * @param tokenOptions - Options controlling scheme and delegation behavior (optional)\n   * @returns A promise that resolves to an object containing:\n   *   - accessToken: The X402 access token string\n   *\n   * @throws PaymentsError if the request fails\n   *\n   * @example\n   * ```typescript\n   * // Supported: create the delegation first, then request the token by id.\n   * const { delegationId } = await payments.delegation.createDelegation({\n   *   provider: 'erc4337',\n   *   spendingLimitCents: 10000,\n   *   durationSecs: 604800,\n   *   currency: 'usdc',\n   * })\n   * const result = await payments.x402.getX402AccessToken(planId, agentId, {\n   *   delegationConfig: { delegationId },\n   * })\n   * ```\n   */\n  async getX402AccessToken(\n    planId: string,\n    agentId?: string,\n    tokenOptions?: X402TokenOptions,\n  ): Promise<{ accessToken: string; [key: string]: any }> {\n    const urlPath = API_URL_CREATE_PERMISSION\n    const url = new URL(urlPath, this.environment.backend)\n\n    const body = buildX402TokenRequestBody({\n      planId,\n      agentId,\n      tokenOptions,\n      environmentName: this.environmentName,\n    })\n\n    const options = this.getBackendHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Failed to create X402 delegation token'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.internal(`${errorMessage} (HTTP ${response.status})`)\n      }\n      return await response.json()\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.internal(\n        `Network error while creating X402 delegation token: ${error instanceof Error ? error.message : String(error)}`,\n      )\n    }\n  }\n}\n"]}
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/x402/token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,eAAe;IAC/C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,OAAuB;QACxC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAA;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACH,KAAK,CAAC,kBAAkB,CACtB,MAAc,EACd,OAAgB,EAChB,YAA+B;QAE/B,MAAM,OAAO,GAAG,yBAAyB,CAAA;QACzC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;QAEtD,MAAM,IAAI,GAAG,yBAAyB,CAAC;YACrC,MAAM;YACN,OAAO;YACP,YAAY;YACZ,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,CAAC,CAAA;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAExD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC1C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,YAAY,GAAG,wCAAwC,CAAA;gBAC3D,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;oBACvC,YAAY,GAAG,SAAS,CAAC,OAAO,IAAI,YAAY,CAAA;gBAClD,CAAC;gBAAC,MAAM,CAAC;oBACP,4BAA4B;gBAC9B,CAAC;gBACD,MAAM,aAAa,CAAC,QAAQ,CAAC,GAAG,YAAY,UAAU,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAA;YAC3E,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;YACpC,wEAAwE;YACxE,mEAAmE;YACnE,0EAA0E;YAC1E,yEAAyE;YACzE,SAAS;YACT,IAAI,OAAO,MAAM,EAAE,WAAW,KAAK,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC/E,MAAM,aAAa,CAAC,QAAQ,CAC1B,sEAAsE,CACvE,CAAA;YACH,CAAC;YACD,2EAA2E;YAC3E,2EAA2E;YAC3E,oEAAoE;YACpE,sEAAsE;YACtE,wCAAwC;YACxC,OAAO,EAAE,GAAG,MAAM,EAAE,YAAY,EAAE,wBAAwB,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAA;QAClF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,MAAM,KAAK,CAAA;YACb,CAAC;YACD,MAAM,aAAa,CAAC,QAAQ,CAC1B,uDAAuD,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAChH,CAAA;QACH,CAAC;IACH,CAAC;CACF","sourcesContent":["/**\n * X402 Token Generation API.\n *\n * Provides X402 access token generation functionality for subscribers.\n * Tokens are used to authorize payment verification and settlement.\n */\n\nimport { BasePaymentsAPI } from '../api/base-payments.js'\nimport { API_URL_CREATE_PERMISSION } from '../api/nvm-api.js'\nimport { PaymentsError } from '../common/payments.error.js'\nimport { PaymentOptions, X402TokenOptions, X402TokenVersion } from '../common/types.js'\nimport { buildX402TokenRequestBody } from './token-request.js'\nimport { detectAccessTokenVersion } from './token-version.js'\n\n/**\n * X402 Token API for generating access tokens.\n *\n * Handles X402 access token generation for subscribers to authorize\n * payment operations with AI agents.\n */\nexport class X402TokenAPI extends BasePaymentsAPI {\n  /**\n   * Get a singleton instance of the X402TokenAPI class.\n   *\n   * @param options - The options to initialize the API\n   * @returns The instance of the X402TokenAPI class\n   */\n  static getInstance(options: PaymentOptions): X402TokenAPI {\n    return new X402TokenAPI(options)\n  }\n\n  /**\n   * Get an X402 access token for the given plan, backed by a delegation.\n   *\n   * This token allows the agent to verify and settle delegations on behalf\n   * of the subscriber.\n   *\n   * The supported flow is **create-first**: create the delegation once with\n   * {@link DelegationAPI.createDelegation}, then pass its `delegationId` in\n   * `tokenOptions.delegationConfig`. Passing inline create-on-the-fly fields\n   * (spending limits / `providerPaymentMethodId` / `cardId`, i.e. no\n   * `delegationId`) is **deprecated** and emits a runtime warning.\n   *\n   * Pass `resource` / `httpVerb` to bind the token to one seller endpoint, and\n   * `tokenVersion: 3` to ask for the single-use, seller/resource-bound token.\n   * v3 is opt-in and the request may be silently downgraded by a backend that\n   * predates it, so the returned `tokenVersion` is read off the minted token\n   * rather than echoed back from the request — branch on that, never on what\n   * you asked for.\n   *\n   * @param planId - The unique identifier of the payment plan\n   * @param agentId - The unique identifier of the AI agent (optional)\n   * @param tokenOptions - Options controlling scheme, resource binding, token version and delegation behavior (optional)\n   * @returns A promise that resolves to an object containing:\n   *   - accessToken: The X402 access token string\n   *   - tokenVersion: The EIP-712 version the returned token was actually signed\n   *     under (`3` means single-use — mint a new token per paid request)\n   *\n   * @throws PaymentsError if the request fails\n   *\n   * @example\n   * ```typescript\n   * // Supported: create the delegation first, then request the token by id.\n   * const { delegationId } = await payments.delegation.createDelegation({\n   *   provider: 'erc4337',\n   *   spendingLimitCents: 10000,\n   *   durationSecs: 604800,\n   *   currency: 'usdc',\n   * })\n   * const result = await payments.x402.getX402AccessToken(planId, agentId, {\n   *   delegationConfig: { delegationId },\n   * })\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Single-use, bound to one seller endpoint. Mint one per paid request.\n   * // `resource.url` must be the string the seller advertises in its 402\n   * // `paymentRequired` — sellers built on this SDK's `paymentMiddleware`\n   * // advertise `req.originalUrl`, i.e. a relative path.\n   * const { accessToken, tokenVersion } = await payments.x402.getX402AccessToken(\n   *   planId,\n   *   agentId,\n   *   {\n   *     delegationConfig: { delegationId },\n   *     resource: { url: '/api/v1/tasks' },\n   *     httpVerb: 'POST',\n   *     tokenVersion: 3,\n   *   },\n   * )\n   * if (tokenVersion === 2) {\n   *   // The backend does not support v3 yet; this token is still reusable.\n   * }\n   * ```\n   */\n  async getX402AccessToken(\n    planId: string,\n    agentId?: string,\n    tokenOptions?: X402TokenOptions,\n  ): Promise<{ accessToken: string; tokenVersion: X402TokenVersion; [key: string]: any }> {\n    const urlPath = API_URL_CREATE_PERMISSION\n    const url = new URL(urlPath, this.environment.backend)\n\n    const body = buildX402TokenRequestBody({\n      planId,\n      agentId,\n      tokenOptions,\n      environmentName: this.environmentName,\n    })\n\n    const options = this.getBackendHTTPOptions('POST', body)\n\n    try {\n      const response = await fetch(url, options)\n      if (!response.ok) {\n        let errorMessage = 'Failed to create X402 delegation token'\n        try {\n          const errorData = await response.json()\n          errorMessage = errorData.message || errorMessage\n        } catch {\n          // Use default error message\n        }\n        throw PaymentsError.internal(`${errorMessage} (HTTP ${response.status})`)\n      }\n      const result = await response.json()\n      // A 2xx with no usable token is a broken response, not a token: without\n      // this guard the caller gets `{ accessToken: undefined }` typed as\n      // `string`, sends `undefined` as the `payment-signature`, and the failure\n      // surfaces at the seller as an unparseable token — three layers from the\n      // cause.\n      if (typeof result?.accessToken !== 'string' || result.accessToken.length === 0) {\n        throw PaymentsError.internal(\n          'X402 token request succeeded but the response carried no accessToken',\n        )\n      }\n      // Detected, never echoed: `tokenVersion: 3` is dropped without an error by\n      // a backend that predates the v3 struct, so the only trustworthy source of\n      // the version is the token itself. The override after the spread is\n      // deliberate — a `tokenVersion` echoed by the backend is discarded in\n      // favour of the one read off the token.\n      return { ...result, tokenVersion: detectAccessTokenVersion(result.accessToken) }\n    } catch (error) {\n      if (error instanceof PaymentsError) {\n        throw error\n      }\n      throw PaymentsError.internal(\n        `Network error while creating X402 delegation token: ${error instanceof Error ? error.message : String(error)}`,\n      )\n    }\n  }\n}\n"]}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@nevermined-io/payments",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Typescript SDK to interact with the Nevermined Payments Protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nevermined-io/payments"
@@ -44,6 +47,7 @@
   "scripts": {
     "clean": "rm -rf ./dist/ ./doc/ ./.nyc_output",
     "build": "tsc",
+    "typecheck:tests": "tsc --noEmit -p tests/tsconfig.json",
     "build:all": "pnpm build && pnpm cli:build",
     "lint": "eslint ./src",
     "test": "jest --verbose --config ./tests/jest.config.json",
@@ -63,26 +67,25 @@
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.91.1",
     "@aws-sdk/client-bedrock-runtime": "^3.972.0",
-    "@babel/core": "^7.27.4",
+    "@babel/core": "^7.29.6",
     "@babel/preset-env": "^7.27.2",
-    "@google-cloud/aiplatform": "^6.1.0",
+    "@google-cloud/aiplatform": "^7.5.0",
     "@langchain/langgraph": "1.2.0",
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@types/express": "4.17.23",
     "@types/jest": "^29.5.13",
     "@types/node": "^20.11.19",
     "@types/supertest": "^6.0.3",
-    "@types/uuid": "^10.0.0",
     "@types/ws": "^8.0.3",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "babel-jest": "^30.0.2",
-    "cohere-ai": "^7.19.0",
+    "cohere-ai": "^8.1.0",
     "dotenv": "^17.2.3",
     "eslint": "^8.56.0",
     "eslint-config-nevermined": "^0.3.0",
     "eslint-config-next": "^15.1.5",
-    "eslint-config-prettier": "^9.1.0",
+    "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-tsdoc": "^0.5.2",
     "jest": "^29.7.0",
     "langchain": "^0.3.37",
@@ -131,20 +134,26 @@
     "@traceloop/node-server-sdk": "^0.26.0",
     "axios": "^1.13.1",
     "express": "4.21.2",
-    "jose": "^5.2.4",
+    "jose": "^6.2.12",
     "js-file-download": "^0.4.12",
-    "uuid": "^10.0.0",
+    "uuid": "^11.1.1",
     "zod": "^4.0.17",
     "zod-to-json-schema": "^3.25.0"
   },
   "packageManager": "pnpm@10.33.0",
   "pnpm": {
     "overrides": {
-      "qs": ">=6.14.1",
-      "jws": ">=4.0.1",
-      "js-yaml": ">=4.1.1",
-      "@langchain/core": ">=0.3.80",
-      "@smithy/config-resolver": ">=4.4.0"
+      "@opentelemetry/core@2": ">=2.8.0 <3",
+      "@opentelemetry/exporter-prometheus": ">=0.217.0 <1",
+      "@opentelemetry/propagator-jaeger": ">=2.9.0 <3",
+      "@opentelemetry/sdk-node": ">=0.217.0 <1",
+      "body-parser@1": ">=1.20.6 <2",
+      "express@4>path-to-regexp": ">=0.1.13 <0.2.0",
+      "ip-address": ">=10.3.1 <11",
+      "langsmith@<0.6.0": ">=0.6.0 <1",
+      "qs@6": ">=6.16.0 <7",
+      "uuid@10": ">=11.1.1 <12",
+      "uuid@9": ">=11.1.1 <12"
     }
   }
 }