@payware/mcp-server 1.0.0

package/src/isv/transactions/process-transaction.js

@@ -0,0 +1,145 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Process (finalize) a transaction via payware API as an ISV
+ */
+export async function processTransaction({ transactionId, merchantPartnerId, oauth2Token, action = 'CONFIRMED', useSandbox = true }) {
+  if (!transactionId) {
+    throw new Error('Transaction 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');
+  }
+
+  if (!['CONFIRMED', 'DECLINED'].includes(action)) {
+    throw new Error('Action must be either CONFIRMED or DECLINED');
+  }
+
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  const requestBody = { action };
+
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  // Use the same JSON serialization method as the JWT factory for MD5 calculation
+  const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
+  const minimizedBodyString = createMinimizedJSON(requestBody);
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    // Send the exact minimized JSON string that was used for MD5 calculation
+    const response = await axios.patch(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
+      headers: {
+        'Authorization': `Bearer ${jwtData.token}`,
+        'Content-Type': 'application/json',
+        'Api-Version': '1'
+      },
+      // Tell axios to send the string as-is, don't serialize it again
+      transformRequest: [(data) => data]
+    });
+
+    return response.data;
+  } catch (error) {
+    if (error.response) {
+      throw new Error(`payware API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+    }
+    throw error;
+  }
+}
+
+export const processTransactionTool = {
+  name: 'payware_operations_process_transaction',
+  description: `Process (finalize) a transaction as an ISV on behalf of a merchant.
+
+Allows confirming or declining a transaction. Only ACTIVE transactions can be processed.
+Requires ISV authentication with merchant partner ID and OAuth2 token.`,
+
+  inputSchema: {
+    type: 'object',
+    required: ['transactionId', 'merchantPartnerId', 'oauth2Token'],
+    properties: {
+      transactionId: {
+        type: 'string',
+        description: 'Transaction ID to process'
+      },
+      merchantPartnerId: {
+        type: 'string',
+        description: 'Partner ID of the target merchant'
+      },
+      oauth2Token: {
+        type: 'string',
+        description: 'OAuth2 access token obtained from the merchant'
+      },
+      action: {
+        type: 'string',
+        enum: ['CONFIRMED', 'DECLINED'],
+        default: 'CONFIRMED',
+        description: 'Action to perform on the transaction'
+      },
+      useSandbox: {
+        type: 'boolean',
+        description: 'Use sandbox environment for testing',
+        default: true
+      }
+    }
+  },
+
+  async handler(params) {
+    try {
+      const result = await processTransaction(params);
+
+      const actionEmoji = params.action === 'CONFIRMED' ? '✅' : '❌';
+
+      return {
+        content: [{
+          type: 'text',
+          text: `${actionEmoji} Transaction ${params.action} Successfully (ISV -> Merchant: ${params.merchantPartnerId})
+
+📋 **Processing Details:**
+- **Transaction ID**: ${params.transactionId}
+- **Action**: ${params.action}
+- **New Status**: ${result.status || params.action}
+- **ISV Partner**: ${getPartnerIdSafe()}
+- **Target Merchant**: ${params.merchantPartnerId}
+
+**Raw Response:**
+\`\`\`json
+${JSON.stringify(result, null, 2)}
+\`\`\``
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: 'text',
+          text: `❌ Transaction Processing Failed
+
+**Error**: ${error.message}
+
+**Processing Attempt:**
+- Transaction ID: ${params.transactionId}
+- Action: ${params.action}
+- Merchant: ${params.merchantPartnerId}
+
+**ISV Authentication:**
+- OAuth2 Token: ${params.oauth2Token ? 'Provided' : 'Missing'}
+- ISV Partner ID: ${getPartnerIdSafe()}`
+        }]
+      };
+    }
+  }
+};

package/src/isv/transactions/simulate-callback.js

@@ -0,0 +1,146 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Simulate a transaction callback via payware API as an ISV
+ */
+export async function simulateCallback({ transactionId, merchantPartnerId, oauth2Token, action = 'CONFIRMED', useSandbox = true }) {
+  if (!transactionId) {
+    throw new Error('Transaction 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');
+  }
+
+  if (!['CONFIRMED', 'DECLINED'].includes(action)) {
+    throw new Error('Action must be either CONFIRMED or DECLINED');
+  }
+
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  const requestBody = { action };
+
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  // Use the same JSON serialization method as the JWT factory for MD5 calculation
+  const { createMinimizedJSON } = await import('../../core/utils/json-serializer.js');
+  const minimizedBodyString = createMinimizedJSON(requestBody);
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    // Send the exact minimized JSON string that was used for MD5 calculation
+    const response = await axios.post(`${baseUrl}/transactions/${transactionId}/simulate-callback`, minimizedBodyString, {
+      headers: {
+        'Authorization': `Bearer ${jwtData.token}`,
+        'Content-Type': 'application/json',
+        'Api-Version': '1'
+      },
+      // Tell axios to send the string as-is, don't serialize it again
+      transformRequest: [(data) => data]
+    });
+
+    return response.data;
+  } catch (error) {
+    if (error.response) {
+      throw new Error(`payware API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+    }
+    throw error;
+  }
+}
+
+export const simulateCallbackTool = {
+  name: 'payware_operations_simulate_callback',
+  description: `Simulate a transaction callback as an ISV on behalf of a merchant.
+
+Triggers a callback to test webhook integration in sandbox environment.
+Requires ISV authentication with merchant partner ID and OAuth2 token.`,
+
+  inputSchema: {
+    type: 'object',
+    required: ['transactionId', 'merchantPartnerId', 'oauth2Token'],
+    properties: {
+      transactionId: {
+        type: 'string',
+        description: 'Transaction ID to simulate callback for'
+      },
+      merchantPartnerId: {
+        type: 'string',
+        description: 'Partner ID of the target merchant'
+      },
+      oauth2Token: {
+        type: 'string',
+        description: 'OAuth2 access token obtained from the merchant'
+      },
+      action: {
+        type: 'string',
+        enum: ['CONFIRMED', 'DECLINED'],
+        default: 'CONFIRMED',
+        description: 'Action to simulate in the callback'
+      },
+      useSandbox: {
+        type: 'boolean',
+        description: 'Use sandbox environment for testing',
+        default: true
+      }
+    }
+  },
+
+  async handler(params) {
+    try {
+      const result = await simulateCallback(params);
+
+      const actionEmoji = params.action === 'CONFIRMED' ? '✅' : '❌';
+
+      return {
+        content: [{
+          type: 'text',
+          text: `🔔 Callback Simulated Successfully (ISV -> Merchant: ${params.merchantPartnerId})
+
+**Callback Details:**
+- **Transaction ID**: ${params.transactionId}
+- **Simulated Action**: ${actionEmoji} ${params.action}
+- **ISV Partner**: ${getPartnerIdSafe()}
+- **Target Merchant**: ${params.merchantPartnerId}
+
+**Use Case**: Testing webhook integration in sandbox environment
+
+**Raw Response:**
+\`\`\`json
+${JSON.stringify(result, null, 2)}
+\`\`\``
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: 'text',
+          text: `❌ Callback Simulation Failed
+
+**Error**: ${error.message}
+
+**Simulation Attempt:**
+- Transaction ID: ${params.transactionId}
+- Action: ${params.action}
+- Merchant: ${params.merchantPartnerId}
+
+**ISV Authentication:**
+- OAuth2 Token: ${params.oauth2Token ? 'Provided' : 'Missing'}
+- ISV Partner ID: ${getPartnerIdSafe()}`
+        }]
+      };
+    }
+  }
+};

package/src/isv/transactions/transaction-history.js

@@ -0,0 +1,186 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get transaction history from payware API as an ISV
+ */
+export async function getTransactionHistory({
+  merchantPartnerId,
+  oauth2Token,
+  partnerId,
+  transactionId,
+  limit = 50,
+  offset = 0,
+  status,
+  from,
+  to,
+  useSandbox = true
+}) {
+  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');
+  }
+
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody: null,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  const params = new URLSearchParams();
+  if (partnerId) params.append('partnerId', partnerId);
+  if (transactionId) params.append('transactionId', transactionId);
+  if (limit) params.append('limit', limit.toString());
+  if (offset) params.append('offset', offset.toString());
+  if (status) params.append('status', status);
+  if (from) params.append('from', from);
+  if (to) params.append('to', to);
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const url = `${baseUrl}/transactions-history?${params.toString()}`;
+    const response = await axios.get(url, {
+      headers: {
+        'Authorization': `Bearer ${jwtData.token}`,
+        'Content-Type': 'application/json',
+        'Api-Version': '1'
+      }
+    });
+
+    return response.data;
+  } catch (error) {
+    if (error.response) {
+      throw new Error(`payware API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
+    }
+    throw error;
+  }
+}
+
+export const getTransactionHistoryTool = {
+  name: 'payware_operations_get_transaction_history',
+  description: `Get transaction history as an ISV on behalf of a merchant.
+
+Retrieves both active and completed transactions with optional filtering.
+Requires ISV authentication with merchant partner ID and OAuth2 token.`,
+
+  inputSchema: {
+    type: 'object',
+    required: ['merchantPartnerId', 'oauth2Token'],
+    properties: {
+      merchantPartnerId: {
+        type: 'string',
+        description: 'Partner ID of the target merchant'
+      },
+      oauth2Token: {
+        type: 'string',
+        description: 'OAuth2 access token obtained from the merchant'
+      },
+      partnerId: {
+        type: 'string',
+        description: 'Filter by partner ID (optional)'
+      },
+      transactionId: {
+        type: 'string',
+        description: 'Filter by specific transaction ID (optional)'
+      },
+      limit: {
+        type: 'number',
+        default: 50,
+        description: 'Maximum number of results to return'
+      },
+      offset: {
+        type: 'number',
+        default: 0,
+        description: 'Number of results to skip for pagination'
+      },
+      status: {
+        type: 'string',
+        enum: ['ACTIVE', 'CONFIRMED', 'DECLINED', 'FAILED', 'EXPIRED', 'CANCELLED'],
+        description: 'Filter by transaction status'
+      },
+      from: {
+        type: 'string',
+        description: 'Start date for filtering (YYYY-MM-DD format)'
+      },
+      to: {
+        type: 'string',
+        description: 'End date for filtering (YYYY-MM-DD format)'
+      },
+      useSandbox: {
+        type: 'boolean',
+        description: 'Use sandbox environment for testing',
+        default: true
+      }
+    }
+  },
+
+  async handler(params) {
+    try {
+      const result = await getTransactionHistory(params);
+
+      const transactions = result.transactions || [];
+      const totalCount = result.totalCount || transactions.length;
+
+      const formatTransaction = (tx) => {
+        const statusEmojis = {
+          'ACTIVE': '⏳',
+          'CONFIRMED': '✅',
+          'DECLINED': '❌',
+          'FAILED': '⚠️',
+          'EXPIRED': '⏰',
+          'CANCELLED': '🚫'
+        };
+        const emoji = statusEmojis[tx.status] || '❓';
+        return `  ${emoji} **${tx.id}** - ${tx.trData?.amount || '0.00'} ${tx.trData?.currency || 'EUR'} - ${tx.status} - ${tx.createdAt || 'N/A'}`;
+      };
+
+      return {
+        content: [{
+          type: 'text',
+          text: `📈 **Transaction History Retrieved (ISV -> Merchant: ${params.merchantPartnerId})**
+
+**ISV Integration:**
+- ISV Partner: ${getPartnerIdSafe()}
+- Target Merchant: ${params.merchantPartnerId}
+- OAuth2 Token: ${params.oauth2Token.substring(0, 8)}...
+
+**Results:** ${transactions.length} of ${totalCount} transactions
+
+**Transactions:**
+${transactions.length > 0 ? transactions.map(formatTransaction).join('\n') : '  No transactions found'}
+
+**Applied Filters:**
+${params.status ? `- Status: ${params.status}\n` : ''}${params.from ? `- From: ${params.from}\n` : ''}${params.to ? `- To: ${params.to}\n` : ''}${params.limit ? `- Limit: ${params.limit}\n` : ''}${params.offset ? `- Offset: ${params.offset}\n` : ''}
+
+**Raw Response:**
+\`\`\`json
+${JSON.stringify(result, null, 2)}
+\`\`\``
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: 'text',
+          text: `❌ Transaction History Request Failed
+
+**Error**: ${error.message}
+
+**ISV Authentication:**
+- Merchant Partner ID: ${params.merchantPartnerId}
+- OAuth2 Token: ${params.oauth2Token ? 'Provided' : 'Missing'}
+- ISV Partner ID: ${getPartnerIdSafe()}`
+        }]
+      };
+    }
+  }
+};

package/src/isv/utils/auth.js

@@ -0,0 +1,159 @@
+/**
+ * ISV-specific authentication utilities
+ * Handles OAuth2 and JWT token creation for ISV partners
+ */
+
+import { createJWTForPartner, getAuthHeaders } from '../../core/auth/jwt-factory.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Create ISV JWT token for API requests
+ * @param {Object} options - JWT creation options
+ * @param {string} options.merchantPartnerId - Target merchant partner ID (required for API calls)
+ * @param {string} options.oauth2Token - OAuth2 token (required for API calls)
+ * @param {Object} options.requestBody - Request body for POST/PUT/PATCH requests
+ * @param {string} options.audience - JWT audience (defaults to merchant partner ID, or https://payware.eu for OAuth2 requests)
+ * @param {boolean} options.isOAuth2Request - Set to true for OAuth2 endpoint requests
+ * @param {boolean} options.isGetRequest - Set to true for GET requests (no body)
+ * @returns {string} JWT token string
+ */
+export async function createISVJWT(options = {}) {
+  const {
+    merchantPartnerId,
+    oauth2Token,
+    requestBody = null,
+    audience = null,
+    isOAuth2Request = false,
+    isGetRequest = false
+  } = options;
+
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe();
+
+  // For OAuth2 requests, we need special handling
+  if (isOAuth2Request) {
+    return await createOAuth2JWT({
+      isvPartnerId,
+      privateKey,
+      requestBody,
+      audience: audience || 'https://payware.eu'
+    });
+  }
+
+  // For regular API requests, we need merchant partner ID and OAuth2 token
+  if (!merchantPartnerId) {
+    throw new Error('Merchant Partner ID is required for ISV API requests');
+  }
+
+  if (!oauth2Token) {
+    throw new Error('OAuth2 token is required for ISV API requests');
+  }
+
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody: isGetRequest ? null : requestBody,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  return jwtData.token;
+}
+
+/**
+ * Create JWT specifically for OAuth2 endpoint requests
+ * @param {Object} options - OAuth2 JWT options
+ * @returns {string} JWT token string
+ */
+async function createOAuth2JWT({ isvPartnerId, privateKey, requestBody, audience }) {
+  // Dynamic imports to avoid circular dependencies
+  const jwt = await import('jsonwebtoken');
+  const crypto = await import('crypto');
+  const { normalizePrivateKey } = await import('../../core/utils/key-utils.js');
+
+  const normalizedKey = normalizePrivateKey(privateKey);
+  const now = Math.floor(Date.now() / 1000);
+
+  // JWT Header
+  const header = {
+    alg: 'RS256',
+    typ: 'JWT'
+  };
+
+  // Add contentMd5 to header if request body exists
+  if (requestBody) {
+    // Use standard JSON.stringify to match axios serialization (preserves property order)
+    const bodyString = JSON.stringify(requestBody);
+    header.contentMd5 = crypto.default.createHash('md5').update(bodyString, 'utf8').digest('base64');
+  }
+
+  // JWT Payload for OAuth2 requests
+  const payload = {
+    iss: isvPartnerId,           // ISV's partner ID
+    aud: audience,               // https://payware.eu for OAuth2 requests
+    iat: now
+  };
+
+  const token = jwt.default.sign(payload, normalizedKey, {
+    algorithm: 'RS256',
+    header: header
+  });
+
+  return token;
+}
+
+/**
+ * Create authentication headers for ISV requests
+ * @param {string} jwt - JWT token
+ * @param {boolean} isOAuth2Request - Whether this is for OAuth2 endpoints (no Api-Version header)
+ * @returns {Object} Headers object with Authorization and Content-Type
+ */
+export function createISVAuthHeaders(jwt, isOAuth2Request = false) {
+  if (isOAuth2Request) {
+    // OAuth2 endpoints don't need Api-Version header
+    return {
+      'Authorization': `Bearer ${jwt}`,
+      'Content-Type': 'application/json'
+    };
+  }
+
+  // Regular API endpoints need Api-Version header
+  return getAuthHeaders(jwt);
+}
+
+/**
+ * Validate ISV request parameters
+ * @param {Object} params - Parameters to validate
+ * @param {boolean} params.requireMerchant - Whether merchant partner ID is required
+ * @param {boolean} params.requireToken - Whether OAuth2 token is required
+ * @throws {Error} If validation fails
+ */
+export function validateISVParams({ merchantPartnerId, oauth2Token, requireMerchant = true, requireToken = true }) {
+  if (requireMerchant && !merchantPartnerId) {
+    throw new Error('Merchant Partner ID is required for ISV operations');
+  }
+
+  if (requireToken && !oauth2Token) {
+    throw new Error('OAuth2 token is required for ISV API operations');
+  }
+
+  // Validate partner ID format (basic validation)
+  if (merchantPartnerId && !/^[A-Z0-9]{8}$/.test(merchantPartnerId)) {
+    console.warn('Merchant Partner ID should be 8 alphanumeric characters (e.g., "PZAYNMVE")');
+  }
+}
+
+/**
+ * Extract partner information from ISV context
+ * @returns {Object} Partner information
+ */
+export function getISVPartnerInfo() {
+  const partnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe();
+
+  return {
+    isvPartnerId: partnerId,
+    hasPrivateKey: !!privateKey,
+    partnerType: 'isv'
+  };
+}