@payware/mcp-server 1.0.0

package/src/isv/deep-links/get-product-link.js

@@ -0,0 +1,167 @@
+import { getProductDeepLink } from '../../shared/deep-links/api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get deep link for a product (ISV on behalf of merchant)
+ */
+export const getProductLinkTool = {
+  name: "payware_deep_links_get_product_link",
+  description: `Get an active deep link for a product on behalf of a merchant. Returns a clickable URL that redirects to the payware mobile app.
+
+**ISV Authentication:**
+- Requires ISV JWT token with merchant partner ID in 'aud' claim
+- Requires OAuth2 token in 'sub' claim
+
+**Deep Link Format:**
+- Web URL: https://url.payware.eu/{productId}
+- Mobile Redirect: payware://{productId}
+
+**Use Cases:**
+- Mobile-only e-commerce product references
+- Advertisement links to products
+- Product sharing via messaging
+
+**Important Notes:**
+- Deep links are only supported in production environment
+- Link expiration is synchronized with the referenced product
+- Traditional deep links that route to app content when app is installed`,
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      productId: {
+        type: "string",
+        description: "The product identifier (e.g., 'pr7e4rCToG')",
+        pattern: "^[a-zA-Z0-9]+$"
+      },
+      merchantPartnerId: {
+        type: "string",
+        description: "Partner ID of the merchant for whom the product is being retrieved"
+      },
+      oauth2Token: {
+        type: "string",
+        description: "OAuth2 access token for merchant authorization"
+      },
+      isvPartnerId: {
+        type: "string",
+        description: "ISV Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      }
+    },
+    required: ["productId", "merchantPartnerId", "oauth2Token"]
+  },
+
+  async handler(args) {
+    const {
+      productId,
+      merchantPartnerId,
+      oauth2Token,
+      isvPartnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!productId) {
+      throw new Error("productId is required");
+    }
+
+    if (!merchantPartnerId) {
+      throw new Error("merchantPartnerId is required for ISV operations");
+    }
+
+    if (!oauth2Token) {
+      throw new Error("oauth2Token is required for ISV operations");
+    }
+
+    if (!isvPartnerId) {
+      throw new Error("ISV Partner ID is required. Provide via 'isvPartnerId' parameter or set PAYWARE_PARTNER_ID environment variable.");
+    }
+
+    if (!privateKey) {
+      throw new Error("Private key is required. Provide via 'privateKey' parameter or set PAYWARE_PRIVATE_KEY environment variable.");
+    }
+
+    try {
+      const result = await getProductDeepLink({
+        productId,
+        partnerType: 'isv',
+        isvPartnerId,
+        privateKey,
+        merchantPartnerId,
+        oauth2Token
+      });
+
+      // Extract the URL - API returns either string directly or object with link property
+      const linkUrl = typeof result.data === 'string' ? result.data : (result.data.link || result.data)
+
+      return {
+        content: [{
+          type: "text",
+          text: `🔗 **Product Deep Link Retrieved (ISV)**
+
+**Deep Link Details:**
+- Product ID: ${productId}
+- Merchant: ${merchantPartnerId}
+- Web URL: ${linkUrl}
+- Mobile Redirect: payware://${productId}
+
+**ISV Authentication:**
+- ISV Partner ID: ${isvPartnerId}
+- Merchant Partner ID: ${merchantPartnerId}
+- OAuth2 Token: ${oauth2Token.substring(0, 10)}...
+
+**Link Information:**
+- Status: Active
+- Expiration: Synchronized with product
+- Platform: Production only
+
+**API Response:**
+\`\`\`json
+${JSON.stringify(result.data, null, 2)}
+\`\`\`
+
+**API Call Details:**
+- Endpoint: GET ${result.requestInfo.url}
+- Status: ${result.requestInfo.statusCode}
+- Method: ${result.requestInfo.method}
+
+**Usage:**
+1. Share the web URL: \`${linkUrl}\`
+2. On mobile devices, it will redirect to: \`payware://${productId}\`
+3. Link expires when the product expires
+4. Recreate if product is updated`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Get Product Deep Link (ISV)**
+
+**Error Details:**
+- Product ID: ${productId}
+- Merchant: ${merchantPartnerId}
+- Message: ${error.message}
+
+**Common Issues:**
+1. **Product not found**: Check if product exists and is not expired
+2. **Authentication failed**: Verify ISV partner ID, private key, and OAuth2 token
+3. **Authorization failed**: Ensure OAuth2 token authorizes access to merchant
+4. **Sandbox environment**: Deep links are production-only
+5. **Invalid product ID**: Ensure product ID format is correct
+
+**Troubleshooting:**
+1. Verify product exists in merchant's payware dashboard
+2. Check OAuth2 token is valid and not expired
+3. Ensure ISV has permission to access merchant data
+4. Check if running in production environment
+5. Ensure JWT authentication is working`
+        }]
+      };
+    }
+  }
+};

package/src/isv/deep-links/get-transaction-link.js

@@ -0,0 +1,167 @@
+import { getTransactionDeepLink } from '../../shared/deep-links/api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get deep link for a transaction (ISV on behalf of merchant)
+ */
+export const getTransactionLinkTool = {
+  name: "payware_deep_links_get_transaction_link",
+  description: `Get an active deep link for a transaction on behalf of a merchant. Returns a clickable URL that redirects to the payware mobile app.
+
+**ISV Authentication:**
+- Requires ISV JWT token with merchant partner ID in 'aud' claim
+- Requires OAuth2 token in 'sub' claim
+
+**Deep Link Format:**
+- Web URL: https://url.payware.eu/{transactionId}
+- Mobile Redirect: payware://{transactionId}
+
+**Use Cases:**
+- P2P payments via messaging services
+- Mobile-only e-commerce payments
+- Advertisement references
+
+**Important Notes:**
+- Deep links are only supported in production environment
+- Link expiration is synchronized with the referenced transaction
+- Traditional deep links that route to app content when app is installed`,
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      transactionId: {
+        type: "string",
+        description: "The transaction identifier (e.g., 'pw7e4rCToG')",
+        pattern: "^[a-zA-Z0-9]+$"
+      },
+      merchantPartnerId: {
+        type: "string",
+        description: "Partner ID of the merchant for whom the transaction is being retrieved"
+      },
+      oauth2Token: {
+        type: "string",
+        description: "OAuth2 access token for merchant authorization"
+      },
+      isvPartnerId: {
+        type: "string",
+        description: "ISV Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "ISV RSA private key for JWT token creation. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      }
+    },
+    required: ["transactionId", "merchantPartnerId", "oauth2Token"]
+  },
+
+  async handler(args) {
+    const {
+      transactionId,
+      merchantPartnerId,
+      oauth2Token,
+      isvPartnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!transactionId) {
+      throw new Error("transactionId is required");
+    }
+
+    if (!merchantPartnerId) {
+      throw new Error("merchantPartnerId is required for ISV operations");
+    }
+
+    if (!oauth2Token) {
+      throw new Error("oauth2Token is required for ISV operations");
+    }
+
+    if (!isvPartnerId) {
+      throw new Error("ISV Partner ID is required. Provide via 'isvPartnerId' parameter or set PAYWARE_PARTNER_ID environment variable.");
+    }
+
+    if (!privateKey) {
+      throw new Error("Private key is required. Provide via 'privateKey' parameter or set PAYWARE_PRIVATE_KEY environment variable.");
+    }
+
+    try {
+      const result = await getTransactionDeepLink({
+        transactionId,
+        partnerType: 'isv',
+        isvPartnerId,
+        privateKey,
+        merchantPartnerId,
+        oauth2Token
+      });
+
+      // Extract the URL - API returns either string directly or object with link property
+      const linkUrl = typeof result.data === 'string' ? result.data : (result.data.link || result.data)
+
+      return {
+        content: [{
+          type: "text",
+          text: `🔗 **Transaction Deep Link Retrieved (ISV)**
+
+**Deep Link Details:**
+- Transaction ID: ${transactionId}
+- Merchant: ${merchantPartnerId}
+- Web URL: ${linkUrl}
+- Mobile Redirect: payware://${transactionId}
+
+**ISV Authentication:**
+- ISV Partner ID: ${isvPartnerId}
+- Merchant Partner ID: ${merchantPartnerId}
+- OAuth2 Token: ${oauth2Token.substring(0, 10)}...
+
+**Link Information:**
+- Status: Active
+- Expiration: Synchronized with transaction
+- Platform: Production only
+
+**API Response:**
+\`\`\`json
+${JSON.stringify(result.data, null, 2)}
+\`\`\`
+
+**API Call Details:**
+- Endpoint: GET ${result.requestInfo.url}
+- Status: ${result.requestInfo.statusCode}
+- Method: ${result.requestInfo.method}
+
+**Usage:**
+1. Share the web URL: \`${linkUrl}\`
+2. On mobile devices, it will redirect to: \`payware://${transactionId}\`
+3. Link expires when the transaction expires
+4. Recreate if transaction is extended`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Get Transaction Deep Link (ISV)**
+
+**Error Details:**
+- Transaction ID: ${transactionId}
+- Merchant: ${merchantPartnerId}
+- Message: ${error.message}
+
+**Common Issues:**
+1. **Transaction not found**: Check if transaction exists and is not expired
+2. **Authentication failed**: Verify ISV partner ID, private key, and OAuth2 token
+3. **Authorization failed**: Ensure OAuth2 token authorizes access to merchant
+4. **Sandbox environment**: Deep links are production-only
+5. **Invalid transaction ID**: Ensure transaction ID format is correct
+
+**Troubleshooting:**
+1. Verify transaction exists using \`payware_transactions_get_transaction_status\`
+2. Check OAuth2 token is valid and not expired
+3. Ensure ISV has permission to access merchant data
+4. Check if running in production environment
+5. Ensure JWT authentication is working`
+        }]
+      };
+    }
+  }
+};

package/src/isv/deep-links/index.js

@@ -0,0 +1,23 @@
+/**
+ * ISV Deep Links Tools
+ * Deep link management for ISVs acting on behalf of merchants
+ */
+
+import { getTransactionLinkTool } from './get-transaction-link.js';
+import { getProductLinkTool } from './get-product-link.js';
+import { deleteTransactionLinkTool } from './delete-transaction-link.js';
+import { deleteProductLinkTool } from './delete-product-link.js';
+
+export const isvDeepLinksTools = [
+  getTransactionLinkTool,
+  getProductLinkTool,
+  deleteTransactionLinkTool,
+  deleteProductLinkTool
+];
+
+export {
+  getTransactionLinkTool,
+  getProductLinkTool,
+  deleteTransactionLinkTool,
+  deleteProductLinkTool
+};

package/src/isv/index.js

@@ -0,0 +1,103 @@
+/**
+ * ISV (Independent Software Vendor) partner tools registry
+ * Tools available for ISVs serving multiple merchants
+ */
+
+// OAuth2 tools
+import { obtainTokenTool } from './oauth2/obtain-token.js';
+import { getTokenInfoTool } from './oauth2/get-token-info.js';
+import { tokenHelperTool } from './oauth2/token-helper.js';
+
+// Transaction tools
+import { createTransactionTool } from './transactions/create-transaction.js';
+import { getTransactionStatusTool } from './transactions/get-status.js';
+import { cancelTransactionTool } from './transactions/cancel-transaction.js';
+import { getTransactionHistoryTool } from './transactions/transaction-history.js';
+import { processTransactionTool } from './transactions/process-transaction.js';
+import { simulateCallbackTool } from './transactions/simulate-callback.js';
+
+// Data tools
+import { isvDataTools } from './data/index.js';
+
+// Product tools
+import { isvProductTools } from './products/index.js';
+
+// Deep links tools
+import { isvDeepLinksTools } from './deep-links/index.js';
+
+// Import shared tools
+import { sharedTools } from '../shared/index.js';
+
+/**
+ * All ISV-specific tools
+ */
+export const isvTools = [
+  // Shared tools (authentication, utilities, etc.)
+  ...sharedTools,
+
+  // OAuth2 management (ISV-specific)
+  obtainTokenTool,
+  getTokenInfoTool,
+  tokenHelperTool,
+
+  // Transaction management
+  createTransactionTool,
+  getTransactionStatusTool,
+  cancelTransactionTool,
+  getTransactionHistoryTool,
+  processTransactionTool,
+  simulateCallbackTool,
+
+  // Data management
+  ...isvDataTools,
+
+  // Product management
+  ...isvProductTools,
+
+  // Deep links management
+  ...isvDeepLinksTools
+];
+
+/**
+ * Get tools for ISV partner type with proper grouping
+ * @returns {Array} Array of ISV tools with grouped names
+ */
+export function getISVTools() {
+  return isvTools.map(tool => {
+    let newName = tool.name;
+
+    // Authentication tools use authentication grouping (shared tools)
+    if (tool.name.startsWith('payware_authentication_')) {
+      newName = tool.name; // Keep authentication grouping
+    }
+    // Authorization tools use authorization grouping (ISV-specific OAuth2)
+    else if (tool.name.startsWith('payware_authorization_')) {
+      newName = tool.name; // Keep authorization grouping
+    }
+    // Utility tools keep their utils grouping
+    else if (tool.name.startsWith('payware_utils_')) {
+      newName = tool.name; // Keep utils grouping
+    }
+    // Operations tools (previously transactions) keep operations grouping
+    else if (tool.name.startsWith('payware_operations_')) {
+      newName = tool.name; // Keep operations grouping
+    }
+    // Data tools keep their data grouping
+    else if (tool.name.startsWith('payware_data_')) {
+      newName = tool.name; // Keep data grouping
+    }
+    // Product tools keep their products grouping
+    else if (tool.name.startsWith('payware_products_')) {
+      newName = tool.name; // Keep products grouping
+    }
+    // Deep links tools keep their deep_links grouping
+    else if (tool.name.startsWith('payware_deep_links_')) {
+      newName = tool.name; // Keep deep_links grouping
+    }
+
+    return {
+      ...tool,
+      name: newName
+    };
+  });
+}

package/src/isv/oauth2/create-token-simple.js

@@ -0,0 +1,46 @@
+/**
+ * Simple OAuth2 token creation utility for testing
+ * Returns just the token string for easy command-line use
+ */
+
+import { obtainTokenTool } from './obtain-token.js';
+
+/**
+ * Create OAuth2 token and return just the token string
+ * @param {Object} params - Optional parameters (uses env vars if not provided)
+ * @returns {string} The access token
+ */
+export async function createTokenSimple(params = {}) {
+  try {
+    const result = await obtainTokenTool.handler(params);
+
+    // Extract token from the response text
+    const responseText = result.content?.[0]?.text || '';
+    const tokenMatch = responseText.match(/🎯 \*\*NEW ACCESS TOKEN\*\*: ([A-Za-z0-9]+)/);
+    if (tokenMatch) {
+      return tokenMatch[1];
+    }
+
+    // Fallback: look for any token pattern in the response
+    const fallbackMatch = responseText.match(/Access Token\*\*: ([A-Za-z0-9]+)/);
+    if (fallbackMatch) {
+      return fallbackMatch[1];
+    }
+
+    throw new Error('Could not extract token from response');
+  } catch (error) {
+    throw new Error(`Token creation failed: ${error.message}`);
+  }
+}
+
+// For command line testing
+if (import.meta.url === `file://${process.argv[1]}`) {
+  createTokenSimple()
+    .then(token => {
+      console.log('🎯 New OAuth2 Token:');
+      console.log(token);
+    })
+    .catch(error => {
+      console.error('❌ Error:', error.message);
+    });
+}

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

@@ -0,0 +1,157 @@
+/**
+ * ISV OAuth2 Token Management - Get Token Information
+ *
+ * Retrieves information about an existing OAuth2 access token.
+ * Use this to check token status and present information in POS software UI.
+ */
+
+export const getTokenInfoTool = {
+  name: 'payware_authorization_oauth2_get_token_info',
+  description: `Get information about an OAuth2 access token.
+
+This endpoint exposes information about access tokens, including their status.
+Only information about tokens requested by the ISV is returned.
+
+Use this to check token status and present information to users in POS software.
+
+Endpoint: GET /oauth2/tokens/{token}
+Auth: Requires ISV JWT token`,
+
+  inputSchema: {
+    type: 'object',
+    required: ['token'],
+    properties: {
+      token: {
+        type: 'string',
+        description: 'The OAuth2 access token to get information about'
+      },
+      useSandbox: {
+        type: 'boolean',
+        description: 'Use sandbox environment for testing',
+        default: true
+      }
+    }
+  },
+
+  async handler({ token, useSandbox = true }) {
+    const axios = (await import('axios')).default;
+    const { createISVJWT } = await import('../utils/auth.js');
+    const { getSandboxUrl, getProductionUrl } = await import('../../config/env.js');
+
+    try {
+      // Create JWT for token info request
+      const jwt = await createISVJWT({
+        isGetRequest: true,
+        isOAuth2Request: true,
+        audience: 'https://payware.eu'
+      });
+
+      const { createISVAuthHeaders } = await import('../utils/auth.js');
+
+      const apiUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+      const baseUrl = apiUrl.replace('/api', ''); // OAuth2 endpoints don't use /api
+      const headers = createISVAuthHeaders(jwt, true); // true = isOAuth2Request (no Api-Version header)
+
+      const response = await axios.get(`${baseUrl}/oauth2/tokens/${token}`, {
+        headers
+      });
+
+      const result = response.data;
+
+      const statusEmoji = {
+        'PENDING': '⏳',
+        'GRANTED': '✅',
+        'REVOKED': '❌'
+      };
+
+      const statusDescription = {
+        'PENDING': 'Token is pending approval',
+        'GRANTED': 'Token is active and valid for API requests',
+        'REVOKED': 'Token has been revoked and is no longer valid'
+      };
+
+      return {
+        content: [{
+          type: "text",
+          text: `📋 **OAuth2 Token Information**
+
+🔑 **Token Details:**
+- **Access Token**: ${result.access_token}
+- **Token Type**: ${result.token_type}
+- **Status**: ${statusEmoji[result.status]} ${result.status}
+- **Description**: ${statusDescription[result.status]}
+- **Scope**: ${result.scope}
+- **Expires**: ${result.expires_in || 'Never (client_credentials tokens do not expire)'}
+
+${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**'
+}
+
+📋 **Usage Notes:**
+- Only GRANTED tokens can be used for API requests
+- Include this token in the "sub" claim of JWT for API calls
+- Set "aud" claim to merchant partnerId when making API requests`
+        }]
+      };
+
+    } catch (error) {
+      let errorMessage = 'Failed to retrieve token information';
+      let errorDetails = {};
+
+      if (error.response) {
+        errorDetails.httpStatus = error.response.status;
+        errorDetails.responseData = error.response.data;
+
+        if (error.response.data?.errorCode) {
+          const errorCode = error.response.data.errorCode;
+          if (errorCode === 'ERR_TOKEN_NOT_FOUND') {
+            errorMessage = 'Token not found or you do not have permission to view this token';
+          } else {
+            errorMessage = `Error: ${errorCode} - ${error.response.data.message || ''}`;
+          }
+        } else {
+          errorMessage = `HTTP ${error.response.status}: ${error.response.statusText}`;
+        }
+      } else if (error.request) {
+        errorMessage = 'Network error - no response received';
+        errorDetails.requestInfo = {
+          url: error.config?.url,
+          method: error.config?.method,
+          headers: error.config?.headers
+        };
+      } else {
+        errorMessage = error.message;
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `❌ Token Information Request Failed
+
+**Error**: ${errorMessage}
+
+**Request Details:**
+- ISV Partner ID: ${process.env.PAYWARE_PARTNER_ID}
+- Token: ${token}
+- Target URL: ${getSandboxUrl().replace('/api', '')}/oauth2/tokens/${token}
+
+${Object.keys(errorDetails).length > 0 ? `
+**Error Details:**
+\`\`\`json
+${JSON.stringify(errorDetails, null, 2)}
+\`\`\`
+` : ''}
+
+📋 **Troubleshooting:**
+- Verify the token value is correct
+- Ensure you have permission to view this token
+- Check if the token was created by your ISV account
+- Verify your ISV JWT token is properly signed`
+        }]
+      };
+    }
+  }
+};