@payware/mcp-server 1.3.2 → 1.4.0

package/src/isv/invitations/index.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { CHANGES, CREATES, READS } from '../../shared/tool-annotations.js';
 
 /**
  * Merchant invitations - how an ISV onboards a merchant onto payware.
@@ -181,6 +182,7 @@ ${result.error.guidance ? `\n${result.error.guidance}` : ''}
 
 export const createInvitationTool = {
   name: 'payware_isv_create_invitation',
+  annotations: CREATES,
   description: `Invite a merchant to join payware through this ISV. **This is the start of the ISV onboarding flow.**
 
 **Endpoint:** POST /isv/invitations -> 201 Created
@@ -300,6 +302,7 @@ to start acting on their behalf.
 
 export const listInvitationsTool = {
   name: 'payware_isv_list_invitations',
+  annotations: READS,
   description: `List the merchant invitations this ISV has created, newest first.
 
 **Endpoint:** GET /isv/invitations - paginated
@@ -362,6 +365,7 @@ to was deleted.
 
 export const getInvitationTool = {
   name: 'payware_isv_get_invitation',
+  annotations: READS,
   description: `Get full details of one invitation, including its link and the merchant data it pre-fills.
 
 **Endpoint:** GET /isv/invitations/{invitationId}
@@ -416,6 +420,7 @@ ${inv.invitationLink}
 
 export const cancelInvitationTool = {
   name: 'payware_isv_cancel_invitation',
+  annotations: CHANGES,
   description: `Cancel a PENDING invitation. **The link stops working immediately.**
 
 **Endpoint:** DELETE /isv/invitations/{invitationId} -> 204 No Content

package/src/isv/oauth2/get-token-info.js

@@ -5,8 +5,11 @@
  * Use this to check token status and present information in POS software UI.
  */
 
+import { READS } from '../../shared/tool-annotations.js';
+
 export const getTokenInfoTool = {
   name: 'payware_authorization_oauth2_get_token_info',
+  annotations: READS,
   description: `Get information about an OAuth2 access token.
 
 This endpoint exposes information about access tokens, including their status.
@@ -76,18 +79,20 @@ Auth: Requires ISV JWT token`,
           text: `📋 **OAuth2 Token Information**
 
 🔑 **Token Details:**
-- **Access Token**: ${result.access_token}
-- **Token Type**: ${result.token_type}
+- **Access Token**: ${result.accessToken}
+- **Token Type**: ${result.tokenType}
 - **Status**: ${statusEmoji[result.status]} ${result.status}
 - **Description**: ${statusDescription[result.status]}
 - **Scope**: ${result.scope}
-- **Expires**: ${result.expires_in || 'Never (client_credentials tokens do not expire)'}
+- **Expires**: ${result.expiresIn == null ? 'No expiration date' : result.expiresIn === 0 ? 'Expired - rotate with POST /oauth2/tokens/{token}/rotate' : `${result.expiresIn} seconds (~${Math.floor(result.expiresIn / 86400)} days)`}
 
-${result.status === 'GRANTED' ?
+${result.status === 'GRANTED' && result.expiresIn === 0 ?
+  '⌛ **Token has expired - rotate it with POST /oauth2/tokens/{token}/rotate (no merchant consent needed)**' :
+  result.status === 'GRANTED' ?
   '✅ **Token is ready for use in API requests**' :
   result.status === 'PENDING' ?
     '⏳ **Token is pending - wait for merchant approval**' :
-    '❌ **Token is revoked - obtain a new token**'
+    '❌ **Token is revoked, and revocation is final.** Requesting a token again returns this same revoked token; the merchant must consent again through an AUTHORIZATION_ONLY invitation (payware_isv_create_invitation)'
 }
 
 📋 **Usage Notes:**

package/src/isv/oauth2/obtain-token.js

@@ -5,14 +5,20 @@
  * This is the first step in the ISV authorization flow.
  */
 
+import { CREATES } from '../../shared/tool-annotations.js';
+
 export const obtainTokenTool = {
   name: 'payware_authorization_oauth2_obtain_token',
+  annotations: CREATES,
   description: `Obtain an OAuth2 access token for a merchant.
 
 ISVs must be authorized by payware registered merchants to make requests on their behalf.
 This endpoint allows ISVs to request a token using the merchant's credentials.
 
-IMPORTANT: Access tokens do not expire and only one token is allowed per merchant.
+IMPORTANT: A token requested this way expires 180 days after the merchant grants authorization.
+expiresIn in the response gives the seconds remaining (null = no expiration date). Rotate it with
+POST /oauth2/tokens/{token}/rotate, before or after expiry - no merchant consent is needed.
+Requesting again for the same merchant returns the existing token rather than a second one.
 Store tokens securely using strong encryption.
 
 Endpoint: POST /oauth2/tokens
@@ -99,7 +105,7 @@ Auth: Requires ISV JWT token with aud: "https://payware.eu"`,
 - **Token Type**: ${result.tokenType}
 - **Status**: ${result.status}
 - **Scope**: ${result.scope}
-- **Expires**: ${result.expiresIn || 'Never (client_credentials tokens do not expire)'}
+- **Expires**: ${result.expiresIn == null ? 'No expiration date' : result.expiresIn === 0 ? 'Expired - rotate with POST /oauth2/tokens/{token}/rotate' : `${result.expiresIn} seconds (~${Math.floor(result.expiresIn / 86400)} days)`}
 
 📋 **Copy this token for next operations:**
 \`${result.accessToken}\`
@@ -110,7 +116,7 @@ Auth: Requires ISV JWT token with aud: "https://payware.eu"`,
 - Use this token in the "sub" claim of future JWT requests
 
 📋 **Next Steps:**
-1. Check token status: Use token \`${result.accessToken}\` with payware_oauth2_get_token_info
+1. Check token status: Use token \`${result.accessToken}\` with payware_authorization_oauth2_get_token_info
 2. Wait for merchant approval (status will change from PENDING to GRANTED)
 3. Use this token in JWT "sub" claim for API requests to merchant data
 4. Set JWT "aud" claim to the merchant's partnerId (${finalClientId}) for API calls`
@@ -191,7 +197,6 @@ ${JSON.stringify(errorDetails, null, 2)}
 - Verify merchant partnerId (clientId) is correct
 - Ensure merchant secret is properly base64 encoded
 - Check if merchant account is active
-- Confirm no existing token for this merchant
 - Verify ISV JWT token is properly signed for OAuth2 requests`
         }]
       };

package/src/isv/oauth2/token-helper.js

@@ -5,12 +5,14 @@
 
 import { obtainTokenTool } from './obtain-token.js';
 import { getTokenInfoTool } from './get-token-info.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Helper tool to create or find OAuth2 tokens with clear output
  */
 export const tokenHelperTool = {
   name: 'payware_authorization_oauth2_token_helper',
+  annotations: CREATES,
   description: `OAuth2 Token Helper - Create or manage tokens with clear output.
 
 This tool helps you:
@@ -54,24 +56,30 @@ Use this when you need a token but aren't sure if one exists or what it is.`,
           text: `📋 **OAuth2 Token Management Help**
 
 🔑 **About OAuth2 Tokens:**
-- Only ONE token allowed per merchant
-- Tokens don't expire (client_credentials flow)
-- Token status: PENDING → GRANTED (after merchant approval)
+- Requesting a token again for the same merchant returns the existing one, not a second one
+- Tokens requested this way expire 180 days after the merchant grants authorization
+- Rotate with POST /oauth2/tokens/{token}/rotate - works on expired tokens too, no merchant consent needed
+- Token status: PENDING → GRANTED (after merchant approval); REVOKED is final
 
 🎯 **To get your token:**
 
-**Option 1: Try creating a token**
-Use: \`payware_oauth2_obtain_token\`
-- If successful: New token will be clearly displayed
+**Option 1: Request a token**
+Use: \`payware_authorization_oauth2_obtain_token\`
+- Returns a new PENDING token, or the existing token if this merchant already has one
 - On failure the server names the reason (e.g. client not found, client disabled)
 
 **Option 2: Check a known token**
-Use: \`payware_oauth2_get_token_info\` with your saved token
-- Shows current status (PENDING/GRANTED/REVOKED)
+Use: \`payware_authorization_oauth2_get_token_info\` with your saved token
+- Shows current status (PENDING/GRANTED/REVOKED) and expiry
 
-**Option 3: Create new token (if current is lost)**
-1. Contact merchant to revoke existing token
-2. Then use \`payware_oauth2_obtain_token\` to create new one
+**Option 3: If you lost the token**
+Nothing needs revoking - the token can be retrieved:
+- Request it again with Option 1, which returns the existing token, or
+- Call GET /oauth2/tokens, which lists every token issued to your ISV with its value and status
+
+⚠️ **Never ask the merchant to revoke a token to get a new one.** Revocation is final: requesting
+again afterwards returns the same REVOKED token, and the only way back is a fresh consent through an
+AUTHORIZATION_ONLY invitation (\`payware_isv_create_invitation\`). To replace a token value, rotate it.
 
 🔐 **Security:**
 - Always store tokens securely
@@ -94,25 +102,19 @@ Use: \`payware_oauth2_get_token_info\` with your saved token
           type: 'text',
           text: `⚠️ **Token Already Exists for This Merchant**
 
-🔍 **Your existing token is stored somewhere secure** (as per OAuth2 best practices, the server doesn't return existing tokens).
+🔍 **A token already exists for this merchant, and it can be retrieved.**
 
 📋 **To find your token:**
 
-**Option 1: Check your secure storage**
-- Look where you saved tokens before
-- Environment variables file
-- Secure configuration management
-- Password manager
+**Option 1: List your tokens**
+Call GET /oauth2/tokens - it lists every token issued to your ISV with its value and status.
 
 **Option 2: If you have the token value**
-Use: \`payware_oauth2_get_token_info\` with your token to check its status
-
-**Option 3: Create new token**
-1. Contact the merchant (Partner ID: ${process.env.PAYWARE_OAUTH_CLIENT_ID || 'not configured'})
-2. Ask them to revoke the existing token
-3. Then use \`payware_oauth2_obtain_token\` to create a new one
+Use: \`payware_authorization_oauth2_get_token_info\` with your token to check its status
 
-💡 **Tip:** Always keep a secure backup of your OAuth2 tokens!
+**Option 3: Need a different value?**
+Rotate it with POST /oauth2/tokens/{token}/rotate. Do not ask the merchant to revoke it - revocation
+is final, and requesting again afterwards returns the same REVOKED token.
 
 📋 **For immediate help:**
 Run this tool with action='help' for more detailed guidance.`
@@ -138,8 +140,8 @@ ${token}
 \`\`\`
 
 🔄 **Next Steps:**
-1. **SAVE THIS TOKEN** securely (you won't be able to retrieve it later)
-2. Check status: \`payware_oauth2_get_token_info\` with token: \`${token}\`
+1. **SAVE THIS TOKEN** securely (if you lose it, GET /oauth2/tokens lists it again)
+2. Check status: \`payware_authorization_oauth2_get_token_info\` with token: \`${token}\`
 3. Wait for merchant approval (status will change to GRANTED)
 4. Use token in API requests once GRANTED`
         }]

package/src/isv/poi/cancel-price.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { CHANGES } from '../../shared/tool-annotations.js';
 
 /**
  * Cancel pending price on a POI via ISV authentication
@@ -57,13 +58,19 @@ export async function cancelPOIPrice({ poiId, merchantPartnerId, oauth2Token, us
  */
 export const cancelPOIPriceTool = {
   name: "payware_poi_cancel_price",
+  annotations: CHANGES,
   description: `Cancel a pending price on a POI, resetting it to IDLE state.
 
 **ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
 **Endpoint:** DELETE /poi/{poiId}/price
-**Use Case:** Cancel a price that was set but customer didn't pay (e.g., order cancelled).
+**Use Case:** Cancel a price that was set but not yet scanned (e.g., order cancelled).
 
-The POI will return to IDLE state and be ready for a new price.
+The POI returns to IDLE and is ready for a new price.
+
+**Only before the scan.** The scan is the customer's bank processing the payment, so from then on a POI
+sale cannot be cancelled by the merchant or an ISV, on any plan: this answers 409
+ERR_POI_NO_PENDING_PAYMENT, and cancelling the transaction itself answers 409 ERR_ALREADY_PROCESSED. The
+sale completes or expires; the POI accepts the next price meanwhile.
 
 **Required:** POI ID, Merchant Partner ID, and OAuth2 token.`,
 

package/src/isv/poi/get-poi.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get POI details via ISV authentication
@@ -61,6 +62,7 @@ export async function getPOI({ poiId, merchantPartnerId, oauth2Token, useSandbox
  */
 export const getPOITool = {
   name: "payware_poi_get",
+  annotations: READS,
   description: `Get details of a specific POI (Point of Interaction).
 
 **ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
@@ -115,8 +117,7 @@ export const getPOITool = {
       const statusEmoji = {
         'IDLE': '🟢',
         'READY': '🟡',
-        'BUSY': '🔴',
-        'DISABLED': '⚫'
+        'BUSY': '🔴'
       }[poi.status] || '⚪';
 
       return {
@@ -137,7 +138,7 @@ export const getPOITool = {
 - Linked vPOS: ${poi.linkedVposCount || 0} terminals
 
 **Current Session:**
-${poi.status !== 'IDLE' && poi.pendingAmount ? `- Amount: ${poi.pendingAmount} ${poi.pendingCurrency}
+${poi.status === 'READY' && poi.pendingAmount ? `- Amount: ${poi.pendingAmount} ${poi.pendingCurrency}
 - Expires: ${poi.sessionExpiresAt || 'N/A'}
 - Token: ${poi.sessionToken || 'N/A'}` : '- No active session'}
 

package/src/isv/poi/get-qrcode.js

@@ -1,19 +1,41 @@
 import axios from 'axios';
-import { getSandboxUrl, getProductionUrl } from '../../config/env.js';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
- * Get POI QR code image
- * Note: This endpoint is public and doesn't require authentication
+ * Get POI QR code image via ISV authentication
+ *
+ * Not a public endpoint: the server resolves the merchant from the token and only answers for that
+ * merchant's own POIs (ApiPOIController.getQRCode, V-05), so an unauthenticated request was refused.
  * @param {Object} params - Parameters for QR code request
  * @returns {Object} QR code response
  */
-export async function getPOIQRCode({ poiId, format = 'PNG', useSandbox = true }) {
+export async function getPOIQRCode({ poiId, format = 'PNG', merchantPartnerId, oauth2Token, useSandbox = true }) {
   if (!poiId) {
     throw new Error('POI ID is required');
   }
 
+  if (!merchantPartnerId) {
+    throw new Error('Merchant Partner ID is required for ISV operations');
+  }
+
+  if (!oauth2Token) {
+    throw new Error('OAuth2 token is required for ISV operations');
+  }
+
+  // Create ISV JWT token (GET request - no body)
+  const jwtData = await createJWTForPartner({
+    partnerId: getPartnerIdSafe(),
+    privateKey: getPrivateKeySafe(useSandbox),
+    requestBody: null,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
   const headers = {
+    'Authorization': `Bearer ${jwtData.token}`,
     'Api-Version': '1'
   };
 
@@ -49,26 +71,35 @@ export async function getPOIQRCode({ poiId, format = 'PNG', useSandbox = true })
  */
 export const getPOIQRCodeTool = {
   name: "payware_poi_get_qrcode",
+  annotations: READS,
   description: `Generate a QR code image for a POI that customers can scan.
 
 **Endpoint:** GET /poi/{poiId}/image
-**Authentication:** Public endpoint (no auth required)
+**Authentication:** On behalf of the merchant that owns the POI
 **Use Case:** Generate QR codes for printing or displaying on screens.
 
 **Formats:** PNG (default), SVG, JPG
 
 Returns base64-encoded image data that can be saved or displayed.
 
-**Required:** POI ID only.`,
+**Required:** POI ID, and the merchant partner ID and OAuth2 token to act on its behalf.`,
 
   inputSchema: {
     type: "object",
-    required: ["poiId"],
+    required: ["poiId", "merchantPartnerId", "oauth2Token"],
     properties: {
       poiId: {
         type: "string",
         description: "The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)"
       },
+      merchantPartnerId: {
+        type: "string",
+        description: "Partner ID of the target merchant (8 alphanumeric characters)"
+      },
+      oauth2Token: {
+        type: "string",
+        description: "OAuth2 access token obtained from the merchant"
+      },
       format: {
         type: "string",
         enum: ["PNG", "SVG", "JPG"],
@@ -84,11 +115,11 @@ Returns base64-encoded image data that can be saved or displayed.
   },
 
   async handler(args) {
-    const { poiId, format = 'PNG', useSandbox = true } = args;
+    const { poiId, format = 'PNG', merchantPartnerId, oauth2Token, useSandbox = true } = args;
 
     if (!poiId) throw new Error("POI ID is required");
 
-    const result = await getPOIQRCode({ poiId, format, useSandbox });
+    const result = await getPOIQRCode({ poiId, format, merchantPartnerId, oauth2Token, useSandbox });
 
     if (result.success) {
       const img = result.image;