@payments-ai/mcp 2.6.0 → 2.7.0

package/dist/main.http.js

@@ -274,7 +274,11 @@ function isExplicitGrantScope(scope) {
 }
 var DEFAULT_OAUTH_SCOPES = OAUTH_CONSENT_READ_SCOPES.filter((scope) => !isExplicitGrantScope(scope));
 var OAUTH_RESPONSE_TYPES_SUPPORTED = ["code"];
-var OAUTH_GRANT_TYPES_SUPPORTED = ["authorization_code"];
+var OAUTH_DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+var OAUTH_GRANT_TYPES_SUPPORTED = [
+  "authorization_code",
+  OAUTH_DEVICE_CODE_GRANT_TYPE
+];
 var OAUTH_CODE_CHALLENGE_METHODS_SUPPORTED = ["S256"];
 function buildOAuthAuthorizationServerMetadata(issuerUrl, options2) {
   return {
@@ -283,6 +287,7 @@ function buildOAuthAuthorizationServerMetadata(issuerUrl, options2) {
     token_endpoint: `${issuerUrl}/api/v1/oauth/token`,
     revocation_endpoint: `${issuerUrl}/api/v1/oauth/revoke`,
     registration_endpoint: `${issuerUrl}/api/v1/oauth/register`,
+    device_authorization_endpoint: `${issuerUrl}/api/v1/oauth/device_authorization`,
     scopes_supported: SUPPORTED_OAUTH_SCOPES,
     response_types_supported: OAUTH_RESPONSE_TYPES_SUPPORTED,
     grant_types_supported: OAUTH_GRANT_TYPES_SUPPORTED,
@@ -296,12 +301,67 @@ function buildOAuthAuthorizationServerMetadata(issuerUrl, options2) {
 var MCP_OAUTH_AUTHORIZATION_WINDOW_MINUTES = 30;
 var MCP_OAUTH_AUTHORIZATION_WINDOW_MS = MCP_OAUTH_AUTHORIZATION_WINDOW_MINUTES * 60 * 1e3;
 
+// ../../packages/mcp-contracts/dist/device-user-code.js
+var DEVICE_USER_CODE_ALPHABET = "BCDFGHJKLMNPQRSTVWXZ";
+var DEVICE_USER_CODE_LENGTH = 8;
+var DEVICE_USER_CODE_PATTERN = new RegExp(`^[${DEVICE_USER_CODE_ALPHABET}]{${DEVICE_USER_CODE_LENGTH}}$`);
+
 // ../../packages/mcp-contracts/dist/order-limits.js
 var import_currency2 = __toESM(require_currency(), 1);
 
 // ../../packages/mcp-contracts/dist/currency-precision.js
 var import_currency = __toESM(require_currency(), 1);
 
+// ../../packages/mcp-contracts/dist/precision-messages.js
+function formatAmountPrecisionMessage(currency5, fractionDigits) {
+  const code = currency5.trim().toUpperCase();
+  if (fractionDigits === 0) {
+    return `Amount must be a whole number of ${code}, which has no minor unit. Recovery: round the amount to whole ${code}, e.g. 500 rather than 500.5.`;
+  }
+  return `Amount must have at most ${fractionDigits} decimal places in ${code}. Recovery: round the amount to ${fractionDigits} decimal places.`;
+}
+
+// ../../packages/mcp-contracts/dist/currency-precision.js
+function currencyFractionDigits(currencyCode3) {
+  const code = currencyCode3.trim().toUpperCase();
+  let digits;
+  try {
+    digits = new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: code
+    }).resolvedOptions().maximumFractionDigits;
+  } catch {
+    throw new Error(`Unsupported currency "${currencyCode3}"`);
+  }
+  if (typeof digits !== "number") {
+    throw new Error(`Unsupported currency "${currencyCode3}"`);
+  }
+  return digits;
+}
+var MINOR_UNIT_RELATIVE_TOLERANCE = Number.EPSILON * 16;
+function amountExceedsCurrencyPrecision(amount, currencyCode3) {
+  const minorUnits = amount * 10 ** currencyFractionDigits(currencyCode3);
+  const drift = Math.abs(minorUnits - Math.round(minorUnits));
+  return drift > Math.abs(minorUnits) * MINOR_UNIT_RELATIVE_TOLERANCE;
+}
+function describeAmountPrecisionViolation(amount, currencyCode3) {
+  const fractionDigits = resolveFractionDigits(currencyCode3);
+  if (fractionDigits === void 0 || !amountExceedsCurrencyPrecision(amount, currencyCode3)) {
+    return void 0;
+  }
+  return formatAmountPrecisionMessage(currencyCode3, fractionDigits);
+}
+function describeRequestAmountPrecisionViolation(amount, currencyCode3) {
+  return describeAmountPrecisionViolation((0, import_currency.default)(amount).value, currencyCode3);
+}
+function resolveFractionDigits(currencyCode3) {
+  try {
+    return currencyFractionDigits(currencyCode3);
+  } catch {
+    return void 0;
+  }
+}
+
 // ../../packages/mcp-contracts/dist/plan-amount-limits.js
 var DEFAULT_MIN_PAID_PLAN_AMOUNT = 1;
 var MIN_PAID_PLAN_AMOUNT_BY_CURRENCY = {
@@ -334,13 +394,6 @@ function formatMinPaidPlanAmountMessage(currency5, minAmount) {
   const code = currency5.trim().toUpperCase() || "USD";
   return `Amount must be at least ${minAmount} ${code} for paid plans`;
 }
-function formatAmountPrecisionMessage(currency5, fractionDigits) {
-  const code = currency5.trim().toUpperCase();
-  if (fractionDigits === 0) {
-    return `Amount must be a whole number of ${code}, which has no minor unit. Recovery: round the amount to whole ${code}, e.g. 500 rather than 500.5.`;
-  }
-  return `Amount must have at most ${fractionDigits} decimal places in ${code}. Recovery: round the amount to ${fractionDigits} decimal places.`;
-}
 var LOWEST_MIN_PAID_PLAN_AMOUNT = Math.min(...Object.values(MIN_PAID_PLAN_AMOUNT_BY_CURRENCY));
 var PAID_PLAN_NOT_FREE_BY_ZERO_AMOUNT = "A paid plan cannot be made free by setting its amount to 0; create a free-access plan instead.";
 function formatAmountBelowLowestFloorMessage() {
@@ -391,47 +444,6 @@ function formatPeriodLengthRecovery(maxLength) {
 }
 var MAX_FREE_TRIAL_DAYS = 730;
 
-// ../../packages/mcp-contracts/dist/currency-precision.js
-function currencyFractionDigits(currencyCode3) {
-  const code = currencyCode3.trim().toUpperCase();
-  let digits;
-  try {
-    digits = new Intl.NumberFormat("en-US", {
-      style: "currency",
-      currency: code
-    }).resolvedOptions().maximumFractionDigits;
-  } catch {
-    throw new Error(`Unsupported currency "${currencyCode3}"`);
-  }
-  if (typeof digits !== "number") {
-    throw new Error(`Unsupported currency "${currencyCode3}"`);
-  }
-  return digits;
-}
-var MINOR_UNIT_RELATIVE_TOLERANCE = Number.EPSILON * 16;
-function amountExceedsCurrencyPrecision(amount, currencyCode3) {
-  const minorUnits = amount * 10 ** currencyFractionDigits(currencyCode3);
-  const drift = Math.abs(minorUnits - Math.round(minorUnits));
-  return drift > Math.abs(minorUnits) * MINOR_UNIT_RELATIVE_TOLERANCE;
-}
-function describeAmountPrecisionViolation(amount, currencyCode3) {
-  const fractionDigits = resolveFractionDigits(currencyCode3);
-  if (fractionDigits === void 0 || !amountExceedsCurrencyPrecision(amount, currencyCode3)) {
-    return void 0;
-  }
-  return formatAmountPrecisionMessage(currencyCode3, fractionDigits);
-}
-function describeRequestAmountPrecisionViolation(amount, currencyCode3) {
-  return describeAmountPrecisionViolation((0, import_currency.default)(amount).value, currencyCode3);
-}
-function resolveFractionDigits(currencyCode3) {
-  try {
-    return currencyFractionDigits(currencyCode3);
-  } catch {
-    return void 0;
-  }
-}
-
 // ../../packages/mcp-contracts/dist/order-limits.js
 function getMaxOrderAmount(currency5) {
   return getMaxPlanAmount(currency5);
@@ -20725,11 +20737,15 @@ var credentialExpiryWarningSchema = external_exports.object({
 
 // ../../packages/mcp-contracts/dist/whoami.js
 var mcpConnectionHostSchema = external_exports.enum(["sandbox", "live"]);
+var EMBEDDED_EMAIL_ADDRESS_PATTERN = /[^\s@]+@[^\s@]+\.[^\s@]+/;
+var MCP_ACCOUNT_NAME_MAX_LENGTH = 255;
+var mcpAccountNameSchema = external_exports.string().min(1).max(MCP_ACCOUNT_NAME_MAX_LENGTH).refine((value) => value.length <= MCP_ACCOUNT_NAME_MAX_LENGTH && !EMBEDDED_EMAIL_ADDRESS_PATTERN.test(value), { message: "An account name must not contain an email address" });
 var mcpConnectionProofSchema = external_exports.object({
   userId: external_exports.uuid(),
   scopes: external_exports.array(external_exports.string()).nullable(),
   host: mcpConnectionHostSchema.describe(`The class of MCP URL this client is connected to: "live" for the main MCP URL, "sandbox" for the sandbox-only MCP URL. Not the environment (dev, stage or prod) and not a merchant's deployment.`),
   endpoint: external_exports.url(),
+  accountName: mcpAccountNameSchema.nullable().describe("The business name of the account you are connected to, never an email address. Quote it with host (live or sandbox) and ask the developer to confirm it is their business; null when the account has no business yet."),
   merchantIds: external_exports.array(external_exports.uuid()).describe("Ids of the merchants this credential is a member of, as returned when the credential was validated. Call get_my_merchant for names and per-deployment state; on the main MCP URL a merchant that exists on sandbox only is listed there, not here."),
   credentialExpiresAt: external_exports.iso.datetime().nullable().describe("When this MCP credential stops working (ISO 8601, UTC); null when unknown."),
   credentialExpiresInSeconds: external_exports.number().int().nonnegative().nullable().describe("Seconds of validity left on this MCP credential; null when the expiry is unknown."),
@@ -25502,7 +25518,7 @@ var TRANSACTION_SCOPE_RULE = 'Requires the "transaction:read" scope, which exist
 var LIST_TRANSACTIONS_SUMMARY = `List a merchant's transactions, newest first, narrowed by the optional filters in the input schema. For the full lookup guide, call search_payments_ai_docs with "transaction lookup".`;
 var GET_TRANSACTION_DETAIL = "Get one transaction by transactionId from list_transactions: the same fields plus the refunded amount and the order's line items. items is empty for a single-plan purchase, where plan names what was bought.";
 var TOOL_DESCRIPTIONS = {
-  [MCP_TOOL_NAMES.WHOAMI]: `Prove which account and which MCP server this connection reaches. Takes no arguments. Returns { userId, scopes, host, endpoint, merchantIds, credentialExpiresAt, credentialExpiresInSeconds, credentialExpiryWarning? }, read from the validated token and the server that answered. "scopes" null means the token holds every scope except "transaction:read", which must be granted by name. "host" is the class of MCP URL this client is connected to: "live" for the main MCP URL, which serves every merchant at its own deployment, or "sandbox" for the sandbox-only MCP URL. It is not the environment (dev, stage or prod) and not a merchant's deployment: on a "live" host a merchant that has not gone live still reports deployment "sandbox" in get_my_merchant, which is expected. To prove the connection, quote userId, host and endpoint from this result rather than the client's connected label. "merchantIds" are the merchants this credential is a member of; credentialExpiresAt and credentialExpiresInSeconds say when it stops working (null when unknown). credentialExpiryWarning is present only when the credential expires within ` + CREDENTIAL_EXPIRY_WARNING_WINDOW_DAYS + " days: tell the user and share its reapproveUrl, and expect the same warning appended to every other tool result until they re-approve. Needs no scope: any valid token can call it. Call get_my_merchant next to find the merchants this connection owns.",
+  [MCP_TOOL_NAMES.WHOAMI]: `Prove which account and which MCP server this connection reaches. Takes no arguments. Returns { userId, scopes, host, endpoint, accountName, merchantIds, credentialExpiresAt, credentialExpiresInSeconds, credentialExpiryWarning? }, read from the validated token and the server that answered. "scopes" null means the token holds every scope except "transaction:read", which must be granted by name. "host" is the class of MCP URL this client is connected to: "live" for the main MCP URL, which serves every merchant at its own deployment, or "sandbox" for the sandbox-only MCP URL. It is not the environment (dev, stage or prod) and not a merchant's deployment: on a "live" host a merchant that has not gone live still reports deployment "sandbox" in get_my_merchant, which is expected. To prove the connection, quote userId, host and endpoint from this result rather than the client's connected label. "accountName" is the business name of the account you are connected to, never an email address: quote it with host (live or sandbox) and ask the developer to confirm it is their business; when it is null, the account has no business yet, so say so and quote userId. "merchantIds" are the merchants this credential is a member of; credentialExpiresAt and credentialExpiresInSeconds say when it stops working (null when unknown). credentialExpiryWarning is present only when the credential expires within ` + CREDENTIAL_EXPIRY_WARNING_WINDOW_DAYS + " days: tell the user and share its reapproveUrl, and expect the same warning appended to every other tool result until they re-approve. Needs no scope: any valid token can call it. Call get_my_merchant next to find the merchants this connection owns.",
   [MCP_TOOL_NAMES.GET_MY_MERCHANT]: 'List the merchant accounts this connection already owns. Call this BEFORE create_merchant_account: a new agent session cannot remember a merchant created in an earlier one, and creating again produces a second merchant with its own products and its own checkout links. Takes no arguments \u2014 the merchants come from the authorization on the connection itself. Returns { merchants: [{ merchantId, name, deployment }] }. "deployment" is "sandbox" before go_live and "live" after it has succeeded, and it matches where create_product and list_products will route for that merchant right now. An empty merchants array is a normal result, not an error: this connection owns no merchant yet, so call create_merchant_account. When more than one merchant comes back, ask which one to use \u2014 do not pick for the user. Requires the "merchant:read" scope.',
   [MCP_TOOL_NAMES.CREATE_MERCHANT_ACCOUNT]: "Create a merchant account on PAI Managed. Call get_my_merchant first: if it returns a merchant, reuse that merchantId instead of creating another, because a duplicate merchant gets its own products and checkout links. " + CREATE_MERCHANT_CONTACT_GUIDANCE + " The business name is a display label and is not globally unique \u2014 every downstream tool (create_product, list_products, checkout) keys on merchantId, so if two merchants happen to share a name, disambiguate them by merchantId (do not pick a distinct name here to work around it). No identity verification (KYC/KYB) is needed to use sandbox \u2014 products, checkout links and test transactions all work without it; verification is required on live. " + IDENTITY_VERIFICATION_RULE + " Dual-provisions live and sandbox with a shared merchantId. On partial dual-provision failure (one backend created it, the other did not), retry without a merchantId to finish it. When both backends fail, the returned error names the appropriate recovery \u2014 follow it as-is rather than repeating the same call in a loop, and treat repeated identical failures as needing escalation to support. Returns that merchant ID. Without a merchantId, a merchant this account already owns is returned with existing: true instead of a new one being created, and whichever of live or sandbox is missing it gets a copy with the details the existing copy holds; a merchantId this account already owns is finished the same way, and the copy that exists is never changed. Next: create_product (and checkout tools) on sandbox, then go_live when ready.",
   [MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS]: 'Get the production activation status of a merchant account on PAI Managed. Returns { status, identityVerification }. status "pending": the merchant has not been promoted to live yet; this is the only status where go_live is the next step, once the user confirms the merchant is ready, and polling this tool will not change it on its own. status "verification_pending": the merchant is promoted to live and identity verification (KYC) is not complete yet; do not call go_live again. status "active": live and identity verified. status "not_provisioned": no live merchant record exists (dual provision never finished on live); recovery: re-run create_merchant_account without a merchantId, which finds this merchant and creates the missing live copy with the details the sandbox copy holds \u2014 go_live cannot fix this and fails while the live twin is missing. ' + IDENTITY_VERIFICATION_RULE + ' identityVerification is the KYC state: "not_started", "pending", "in_review", "verified" or "rejected".',
@@ -25614,11 +25630,13 @@ var QUICKSTART_SKILL_SECTIONS = [
   "",
   'Do not trust the client\'s "Connected" label. Call `whoami` and report what it returns. `whoami` takes no arguments and needs no scope: every valid token can call it.',
   "",
-  "| Result         | Meaning                                                   | Tell the developer                                                                                                                                                              |",
-  "| -------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |",
-  "| Success        | Connected.                                                | Quote `userId`, `host` (`sandbox` or `live`: the MCP URL connected to, not the merchant deployment) and `endpoint`. `scopes: null` means every scope except `transaction:read`. |",
-  "| HTTP 401       | Not connected.                                            | Quote the 401 `message` verbatim (for `code: token_expired` it says where to generate a new token), then show the MCP config above.                                             |",
-  "| Any tool error | Connected, but the server could not prove the connection. | Quote the error. Do not say disconnected and do not paste the connect config.                                                                                                   |",
+  "| Result         | Meaning                                                   | Tell the developer                                                                                                                                                                                                                                                                                                                                                                                                                                |",
+  "| -------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |",
+  "| Success        | Connected.                                                | Quote `accountName` (the business name of the account you are connected to, never an email) and ask the developer to confirm it, together with `host` (live or sandbox), is their own business account. Then quote `userId`, `host` (`sandbox` or `live`: the MCP URL connected to, not the merchant deployment) and `endpoint`. `accountName: null` means no label is known: say so. `scopes: null` means every scope except `transaction:read`. |",
+  "| HTTP 401       | Not connected.                                            | Quote the 401 `message` verbatim (for `code: token_expired` it says how to reconnect: re-approve in the client for OAuth, run the device grant again and replace the `Authorization` header if connected that way, or generate a new token if connected with a token), then show the MCP config above.                                                                                                                                            |",
+  "| Any tool error | Connected, but the server could not prove the connection. | Quote the error. Do not say disconnected and do not paste the connect config.                                                                                                                                                                                                                                                                                                                                                                     |",
+  "",
+  'If `whoami` returns a `credentialExpiryWarning`, or a tool result carries one under `_meta["ai.payments/credentialExpiryWarning"]` with a closing text block (OAuth connections only, within 14 days of expiry), tell the user and share its re-approve link, which opens the connect page. If you connected with the device grant, run it again and replace the `Authorization` header instead (see "Connect without a terminal"). `credentialExpiresAt` and `credentialExpiresInSeconds` say when the credential stops working; `null` means unknown.',
   "",
   "## Before you mutate anything",
   "",
@@ -25680,26 +25698,26 @@ var QUICKSTART_SKILL_SECTIONS = [
   "",
   "## Tools",
   "",
-  "| Tool                             | Use                                                                          |",
-  "| -------------------------------- | ---------------------------------------------------------------------------- |",
-  "| `whoami`                         | `userId`, `scopes`, `host`, `endpoint`; any valid token                      |",
-  "| `search_payments_ai_docs`        | Search developer docs                                                        |",
-  "| `get_my_merchant`                | Owned merchants                                                              |",
-  "| `create_merchant_account`        | Dual-provision live + sandbox merchant                                       |",
-  "| `get_merchant_activation_status` | Activation status (see below)                                                |",
-  "| `go_live`                        | Promote to live; a repeat returns current status                             |",
-  "| `create_product`                 | Product + plans (sandbox until go-live)                                      |",
-  "| `create_order`                   | Multi-item or caller-priced checkout                                         |",
-  "| `update_product`                 | Merge-update a product's name, description or status                         |",
-  "| `update_plan`                    | Merge-update a plan's name, description, price, billing period or free trial |",
-  "| `list_products`                  | List products, plans, checkout URLs                                          |",
-  "| `list_transactions`              | Look up transactions (needs `transaction:read`)                              |",
-  "| `get_transaction`                | One transaction's details and line items                                     |",
-  "| `get_product_image_upload_url`   | Presigned POST for product image                                             |",
-  "| `confirm_product_image`          | Attach uploaded product image                                                |",
-  "| `get_checkout_customization`     | Read hosted checkout branding                                                |",
-  "| `update_checkout_customization`  | Merge-update branding                                                        |",
-  "| `set_checkout_logo`              | Mint \u2192 PUT \u2192 confirm checkout logo                                           |",
+  "| Tool                             | Use                                                                                                                                                                   |",
+  "| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |",
+  "| `whoami`                         | `accountName`, `userId`, `scopes`, `host`, `endpoint`, `merchantIds`, `credentialExpiresAt`, `credentialExpiresInSeconds`, `credentialExpiryWarning`; any valid token |",
+  "| `search_payments_ai_docs`        | Search developer docs                                                                                                                                                 |",
+  "| `get_my_merchant`                | Owned merchants                                                                                                                                                       |",
+  "| `create_merchant_account`        | Dual-provision live + sandbox merchant                                                                                                                                |",
+  "| `get_merchant_activation_status` | Activation status (see below)                                                                                                                                         |",
+  "| `go_live`                        | Promote to live; a repeat returns current status                                                                                                                      |",
+  "| `create_product`                 | Product + plans (sandbox until go-live)                                                                                                                               |",
+  "| `create_order`                   | Multi-item or caller-priced checkout                                                                                                                                  |",
+  "| `update_product`                 | Merge-update a product's name, description or status                                                                                                                  |",
+  "| `update_plan`                    | Merge-update a plan's name, description, price, billing period or free trial                                                                                          |",
+  "| `list_products`                  | List products, plans, checkout URLs                                                                                                                                   |",
+  "| `list_transactions`              | Look up transactions (needs `transaction:read`)                                                                                                                       |",
+  "| `get_transaction`                | One transaction's details and line items                                                                                                                              |",
+  "| `get_product_image_upload_url`   | Presigned POST for product image                                                                                                                                      |",
+  "| `confirm_product_image`          | Attach uploaded product image                                                                                                                                         |",
+  "| `get_checkout_customization`     | Read hosted checkout branding                                                                                                                                         |",
+  "| `update_checkout_customization`  | Merge-update branding                                                                                                                                                 |",
+  "| `set_checkout_logo`              | Mint \u2192 PUT \u2192 confirm checkout logo                                                                                                                                    |",
   "",
   "### Activation status",
   "",
@@ -26831,6 +26849,7 @@ function buildConnectionProof(input2) {
     scopes: payload.scopes,
     host: host2,
     endpoint,
+    accountName: payload.accountName ?? null,
     merchantIds: payload.merchantIds,
     credentialExpiresAt: credentialExpiry.credentialExpiresAt,
     credentialExpiresInSeconds: credentialExpiry.credentialExpiresInSeconds,
@@ -28247,18 +28266,20 @@ function parseMcpTokenPayload(parsed) {
   if (typeof parsed !== "object" || parsed === null) {
     return void 0;
   }
-  const { userId, cognitoSub, merchantIds, scopes, expiresAt, oauthIssued } = parsed;
+  const { userId, cognitoSub, merchantIds, scopes, expiresAt, oauthIssued, accountName } = parsed;
   if (typeof userId !== "string" || typeof cognitoSub !== "string" || !isStringArray(merchantIds)) {
     return void 0;
   }
   const expiry = parseExpiresAt(expiresAt);
+  const label = mcpAccountNameSchema.safeParse(accountName);
   return {
     userId,
     cognitoSub,
     merchantIds,
     scopes: Array.isArray(scopes) ? scopes : null,
     oauthIssued: oauthIssued === true,
-    ...expiry === void 0 ? {} : { expiresAt: expiry }
+    ...expiry === void 0 ? {} : { expiresAt: expiry },
+    ...label.success ? { accountName: label.data } : {}
   };
 }
 function parseExpiresAt(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payments-ai/mcp",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "private": false,
   "description": "MCP for Payments AI",
   "repository": {