@payware/mcp-server 1.0.0

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

@@ -0,0 +1,258 @@
+import axios from 'axios';
+import { createJWTToken } from '../../core/auth/jwt-token.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get transaction history from payware API (for completed/expired transactions)
+ * @param {Object} params - Parameters for history request
+ * @returns {Object} Transaction history response
+ */
+export async function getTransactionHistory({ transactionId, partnerId, privateKey, useSandbox = true }) {
+  if (!transactionId) {
+    throw new Error('Transaction ID is required');
+  }
+  
+  if (!partnerId || !privateKey) {
+    throw new Error('Partner ID and private key are required for proper JWT creation');
+  }
+  
+  // Create JWT token without body (GET request - no contentMd5 required)
+  const tokenData = createJWTToken(partnerId, privateKey, null);
+  
+  // Required headers as per payware API documentation
+  const headers = {
+    'Authorization': `Bearer ${tokenData.token}`,
+    'Content-Type': 'application/json',
+    'Api-Version': '1'  // Required: current API version
+  };
+  
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.get(`${baseUrl}/transactions-history/${transactionId}`, { headers });
+    
+    return {
+      success: true,
+      transaction: response.data,
+      requestId: response.headers['x-request-id'],
+      timestamp: new Date().toISOString()
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        message: error.response?.data?.message || error.message,
+        status: error.response?.status,
+        code: error.response?.data?.errorCode,
+        details: error.response?.data,
+        throttled: error.response?.status === 415
+      },
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+/**
+ * Format transaction history for display
+ */
+function formatTransactionHistory(transaction) {
+  const statusEmojis = {
+    'CONFIRMED': '✅',
+    'DECLINED': '❌', 
+    'FAILED': '💥',
+    'CANCELLED': '🚫',
+    'EXPIRED': '⏰'
+  };
+  
+  const typeEmojis = {
+    'DEFAULT': '💳',
+    'SHIPPABLE': '📦',
+    'VOUCHER': '🎫',
+    'CHEQUE': '📝'
+  };
+  
+  const status = transaction.status || 'UNKNOWN';
+  const type = transaction.transactionType || 'DEFAULT';
+  const statusEmoji = statusEmojis[status] || '❓';
+  const typeEmoji = typeEmojis[type] || '💳';
+  
+  return {
+    statusEmoji,
+    typeEmoji,
+    status,
+    type,
+    formattedStatus: `${statusEmoji} ${status}`,
+    formattedType: `${typeEmoji} ${type}`
+  };
+}
+
+/**
+ * Get transaction history tool implementation
+ */
+export const getTransactionHistoryTool = {
+  name: "payware_operations_get_transaction_history", 
+  description: `Get history of completed/finalized transactions with final statuses (throttled endpoint).
+
+**Endpoint:** GET /transactions-history/{transactionId}
+**Use Case:** Retrieve transactions with final statuses: CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED.
+**⚠️ THROTTLED:** This endpoint may return HTTP 415 Too Many Requests - implement retry logic.
+**Note:** For ACTIVE transactions, use 'payware_transactions_get_transaction_status' instead.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      transactionId: {
+        type: "string",
+        description: "Transaction ID to get history for. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
+        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+      },
+      partnerId: {
+        type: "string",
+        description: "Partner ID from payware dashboard. Can use PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key for JWT token creation. Can use PAYWARE_PRIVATE_KEY_PATH env var as default.",
+        default: getPrivateKeySafe()
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment for testing",
+        default: true
+      }
+    },
+    required: ["transactionId"],
+    additionalProperties: false
+  },
+  
+  async handler(args) {
+    const { transactionId, partnerId = getPartnerIdSafe(), privateKey = getPrivateKeySafe(args.useSandbox ?? true), useSandbox = true } = args;
+    
+    if (!transactionId) {
+      throw new Error("Transaction ID is required");
+    }
+    
+    if (!partnerId) {
+      throw new Error("Partner ID is required. Provide via 'partnerId' 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.");
+    }
+    
+    const result = await getTransactionHistory({ transactionId, partnerId, privateKey, useSandbox });
+    
+    if (result.success) {
+      const formatInfo = formatTransactionHistory(result.transaction);
+      
+      // Format dates
+      const created = result.transaction.created ? new Date(result.transaction.created * 1000).toISOString() : 'N/A';
+      const finalized = result.transaction.finalized ? new Date(result.transaction.finalized * 1000).toISOString() : 'N/A';
+      
+      return {
+        content: [{
+          type: "text",
+          text: `📊 **Transaction History Retrieved**
+
+**Transaction:** ${transactionId}
+**Type:** ${formatInfo.formattedType}
+**Status:** ${formatInfo.formattedStatus}
+
+**Transaction Details:**
+- ID: ${result.transaction.transactionId || 'N/A'}
+- Initiated By: ${result.transaction.initiatedBy || 'N/A'}
+- Amount: ${result.transaction.amount ? `${result.transaction.amount} ${result.transaction.currency}` : 'N/A'}
+- Reason: ${result.transaction.reasonL1 || 'N/A'}${result.transaction.reasonL2 ? ` (${result.transaction.reasonL2})` : ''}
+
+**Parties:**
+- Payee: ${result.transaction.payeeFriendlyName || 'N/A'} (${result.transaction.payeeAccount || 'N/A'})
+- Payer: ${result.transaction.payerFriendlyName || 'N/A'} (${result.transaction.payerAccount || 'N/A'})
+- Payee BIC: ${result.transaction.payeeBIC || 'N/A'}
+- Payer BIC: ${result.transaction.payerBIC || 'N/A'}
+
+**Timeline:**
+- Created: ${created}
+- Finalized: ${finalized}
+- Time to Live: ${result.transaction.timeToLive || 'N/A'} seconds
+
+**Status Information:**
+${result.transaction.status ? `- Final Status: ${formatInfo.formattedStatus}` : ''}
+${result.transaction.statusMessage ? `- Status Message: ${result.transaction.statusMessage}` : ''}
+
+${result.transaction.deliveryAddress ? `
+**Delivery Address:**
+- Name: ${result.transaction.deliveryAddress.fullName || 'N/A'}
+- Address: ${result.transaction.deliveryAddress.streetAddressLine1 || 'N/A'}
+${result.transaction.deliveryAddress.streetAddressLine2 ? `  ${result.transaction.deliveryAddress.streetAddressLine2}` : ''}
+- City: ${result.transaction.deliveryAddress.city || 'N/A'}, ${result.transaction.deliveryAddress.zipCode || 'N/A'}
+- Region: ${result.transaction.deliveryAddress.region || 'N/A'}
+- Country: ${result.transaction.deliveryAddress.country || 'N/A'}
+- Phone: ${result.transaction.deliveryAddress.phoneNumber || 'N/A'}
+- Email: ${result.transaction.deliveryAddress.email || 'N/A'}
+` : ''}
+
+**Full Response:**
+\`\`\`json
+${JSON.stringify(result.transaction, null, 2)}
+\`\`\`
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}
+
+**Status Meanings:**
+- ✅ CONFIRMED: Successfully finalized
+- ❌ DECLINED: Declined by the user, processing or finalizing payment institutions
+- 💥 FAILED: Failed due to technical reasons or other
+- 🚫 CANCELLED: Transaction canceled by the originator
+- ⏰ EXPIRED: Time to live of the transaction has passed
+
+**Note:** This endpoint is throttled and only returns transactions with final statuses. ACTIVE transactions cannot be retrieved here.`
+        }]
+      };
+    } else {
+      let errorText = `❌ **Failed to Get Transaction History**
+
+**Transaction ID:** ${transactionId}
+
+**Error Details:**
+- Message: ${result.error.message}
+- Status: ${result.error.status || 'N/A'}
+- Code: ${result.error.code || 'N/A'}`;
+
+      if (result.error.throttled) {
+        errorText += `
+
+**⚠️ THROTTLED REQUEST**
+This endpoint has rate limiting. You've made too many requests recently.
+Please wait before trying again.`;
+      }
+
+      errorText += `
+
+**Full Error Response:**
+\`\`\`json
+${JSON.stringify(result.error.details || result.error, null, 2)}
+\`\`\`
+
+**Timestamp:** ${result.timestamp}
+
+**Common Issues:**
+1. **ERR_MISSING_TRANSACTION**: Transaction ID not found
+2. **Too Many Requests (415)**: API rate limit exceeded
+3. **ERR_METHOD_NOT_ALLOWED**: HTTP method issue
+
+**Troubleshooting:**
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+2. Ensure transaction exists and you have access to it
+3. If getting rate limit errors, wait 60 seconds before retrying
+4. For ACTIVE transactions, use 'payware_transactions_get_transaction_status' instead
+5. This endpoint only returns transactions with final statuses (CONFIRMED, DECLINED, FAILED, EXPIRED, CANCELLED)`;
+
+      return {
+        content: [{
+          type: "text",
+          text: errorText
+        }]
+      };
+    }
+  }
+};

package/src/payment-institution/data/index.js

@@ -0,0 +1,280 @@
+/**
+ * Payment Institution Data Tools - Complete Data API Implementation
+ * Production-only tools for data retrieval, reporting, and export functionality for Payment Institutions
+ */
+
+import {
+  generateReport,
+  getReportStatus,
+  exportReport,
+  getExportStatus,
+  downloadExport,
+  cancelReport,
+  cancelExport,
+  REPORT_TYPES,
+  EXPORT_FORMATS,
+  LOCALES
+} from '../../shared/data/data-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+// Create a payment institution tool factory
+const createPIDataTool = (toolName, apiFunction, description, additionalParams = {}) => ({
+  name: `payware_data_${toolName}`,
+  description: `${description} (Payment Institution data access)`,
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      partnerId: {
+        type: "string",
+        description: "Payment Institution Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "Payment Institution RSA private key for authentication. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      },
+      ...additionalParams
+    },
+    required: Object.keys(additionalParams)
+  },
+
+  async handler(args) {
+    const {
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!partnerId || !privateKey) {
+      throw new Error("Payment Institution Partner ID and private key are required. Set PAYWARE_PARTNER_ID and environment-specific private key variables or provide them as parameters.");
+    }
+
+    try {
+      const result = await apiFunction({
+        ...args,
+        partnerType: 'payment_institution',
+        partnerId,
+        privateKey
+      });
+
+      return {
+        content: [{
+          type: "text",
+          text: `🏦 **Payment Institution ${description}**\n\n${JSON.stringify(result.data, null, 2)}\n\n**Payment Institution Context:**\n- Partner ID: ${partnerId}\n- Role: Payment Institution (P2P transactions)`
+        }]
+      };
+    } catch (error) {
+      throw new Error(`Payment Institution failed to ${toolName.replace('_', ' ')}: ${error.message}`);
+    }
+  }
+});
+
+/**
+ * Generate report tool for Payment Institutions
+ */
+export const generateReportTool = {
+  name: "payware_data_generate_report",
+  description: "Generate an asynchronous data report for Payment Institution analysis. Focuses on P2P transaction flows and cross-institution payments. Production only.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      reportUnitId: {
+        type: "string",
+        description: "The ID of the report to generate",
+        enum: Object.values(REPORT_TYPES),
+        default: REPORT_TYPES.PROCESSED_TRANSACTIONS
+      },
+      dateFrom: {
+        type: "string",
+        description: "Start date for the reporting period (YYYY-MM-DD format). Required for premium reports.",
+        pattern: "^\\d{4}-\\d{2}-\\d{2}$"
+      },
+      dateTo: {
+        type: "string",
+        description: "End date for the reporting period (YYYY-MM-DD format). Required for premium reports.",
+        pattern: "^\\d{4}-\\d{2}-\\d{2}$"
+      },
+      ignorePagination: {
+        type: "boolean",
+        description: "If true, return report as single continuous document. If false, paginate results.",
+        default: false
+      },
+      locale: {
+        type: "string",
+        description: "Locale for the report",
+        enum: Object.values(LOCALES),
+        default: LOCALES.ENGLISH_US
+      },
+      timeZone: {
+        type: "string",
+        description: "Timezone for date calculations (e.g., 'Europe/Sofia', 'America/New_York')",
+        default: "GMT"
+      },
+      partnerId: {
+        type: "string",
+        description: "Payment Institution Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "Payment Institution RSA private key for authentication. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      }
+    },
+    required: ["reportUnitId"]
+  },
+
+  async handler(args) {
+    const {
+      reportUnitId,
+      dateFrom,
+      dateTo,
+      ignorePagination = false,
+      locale = LOCALES.ENGLISH_US,
+      timeZone = 'GMT',
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!partnerId || !privateKey) {
+      throw new Error("Payment Institution Partner ID and private key are required. Set PAYWARE_PARTNER_ID and environment-specific private key variables or provide them as parameters.");
+    }
+
+    // Check for required date range on premium reports
+    const premiumReports = [
+      REPORT_TYPES.PROCESSED_TRANSACTIONS,
+      REPORT_TYPES.SCHEDULES_LIST,
+      REPORT_TYPES.TRANSACTIONS_PER_PRODUCT,
+      REPORT_TYPES.SALES_PER_PRODUCT,
+      REPORT_TYPES.TRANSACTIONS_PER_WEBPOS
+    ];
+
+    if (premiumReports.includes(reportUnitId) && (!dateFrom || !dateTo)) {
+      throw new Error(`Report "${reportUnitId}" requires dateFrom and dateTo parameters (YYYY-MM-DD format)`);
+    }
+
+    try {
+      const result = await generateReport({
+        reportUnitId,
+        dateFrom,
+        dateTo,
+        ignorePagination,
+        locale,
+        timeZone,
+        partnerType: 'payment_institution',
+        partnerId,
+        privateKey
+      });
+
+      const reportType = Object.keys(REPORT_TYPES).find(key => REPORT_TYPES[key] === reportUnitId) || reportUnitId;
+
+      return {
+        content: [{
+          type: "text",
+          text: `🏦 **Payment Institution Data Report Generation Started**
+
+**Report Details:**
+- Type: ${reportType}
+- Report Unit ID: ${reportUnitId}
+- Request ID: ${result.data.requestId}
+- Status: ${result.data.status}
+- Generated: ${result.data.generatedAt}
+
+**Payment Institution Context:**
+- Partner ID: ${partnerId}
+- Role: Payment Institution (handles P2P transactions)
+- Access: Cross-institution payment flows
+
+**Report Parameters:**
+- Date Range: ${dateFrom || 'Default'} to ${dateTo || 'Default'}
+- Timezone: ${timeZone}
+- Locale: ${locale}
+- Pagination: ${ignorePagination ? 'Disabled (single document)' : 'Enabled'}
+
+**Next Steps:**
+1. Save the Request ID: \`${result.data.requestId}\`
+2. Use "Get Report Status" tool to monitor progress
+3. When status is "READY", use "Export Report" tool to get the data
+
+**Payment Institution Reports Include:**
+- P2P transaction flows (SRC/DST roles)
+- Cross-institution payment data
+- Settlement and reconciliation data
+- Transaction fees and commissions
+- Partner network activity
+
+**⚠️ Production Only:**
+This feature is only available in the production environment, not in sandbox.
+
+**Note:** Payment Institution reports may include additional data specific to P2P transactions and cross-institution flows that are not available to regular merchants.`
+        }]
+      };
+    } catch (error) {
+      throw new Error(`Failed to generate Payment Institution report: ${error.message}`);
+    }
+  }
+};
+
+// Create all other PI data tools
+export const getReportStatusTool = createPIDataTool('get_report_status', getReportStatus, 'Get Report Status', {
+  requestId: {
+    type: "string",
+    description: "The request ID returned from the report generation request (UUID format)"
+  }
+});
+
+export const exportReportTool = createPIDataTool('export_report', exportReport, 'Export Report', {
+  requestId: {
+    type: "string",
+    description: "The request ID from the report generation (UUID format)"
+  },
+  outputFormat: {
+    type: "string",
+    description: "Export format",
+    enum: Object.values(EXPORT_FORMATS),
+    default: EXPORT_FORMATS.PDF
+  }
+});
+
+export const getExportStatusTool = createPIDataTool('get_export_status', getExportStatus, 'Get Export Status', {
+  exportId: {
+    type: "string",
+    description: "The export ID returned from the export request (UUID format)"
+  }
+});
+
+export const downloadExportTool = createPIDataTool('download_export', downloadExport, 'Download Export', {
+  exportId: {
+    type: "string",
+    description: "The export ID from the export request (UUID format)"
+  }
+});
+
+export const cancelReportTool = createPIDataTool('cancel_report', cancelReport, 'Cancel Report', {
+  requestId: {
+    type: "string",
+    description: "The request ID of the report to cancel (UUID format)"
+  }
+});
+
+export const cancelExportTool = createPIDataTool('cancel_export', cancelExport, 'Cancel Export', {
+  exportId: {
+    type: "string",
+    description: "The export ID of the export to cancel (UUID format)"
+  }
+});
+
+/**
+ * All Payment Institution data tools
+ */
+export const paymentInstitutionDataTools = [
+  generateReportTool,
+  getReportStatusTool,
+  exportReportTool,
+  getExportStatusTool,
+  downloadExportTool,
+  cancelReportTool,
+  cancelExportTool
+];

package/src/payment-institution/deep-links/delete-transaction-link.js

@@ -0,0 +1,128 @@
+import { deleteTransactionDeepLink } from '../../shared/deep-links/api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Delete deep link for a payment institution transaction
+ */
+export const deleteTransactionLinkTool = {
+  name: "payware_deep_links_delete_transaction_link",
+  description: `Delete an active deep link for a transaction where the payment institution acts as source (SRC) or destination (DST). Once deleted, the deep link URL will no longer redirect to the payware mobile app.
+
+**Use Cases:**
+- Remove expired transaction links
+- Clean up after transaction completion
+- Security cleanup for sensitive P2P transactions
+
+**Important Notes:**
+- Deep links are only supported in production environment
+- Once deleted, the link cannot be recovered - you'll need to create a new one
+- Payment institutions only manage transaction links (no product links)
+- This operation is irreversible`,
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      transactionId: {
+        type: "string",
+        description: "The transaction identifier (e.g., 'pw7e4rCToG')",
+        pattern: "^[a-zA-Z0-9]+$"
+      },
+      partnerId: {
+        type: "string",
+        description: "Payment Institution Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      }
+    },
+    required: ["transactionId"]
+  },
+
+  async handler(args) {
+    const {
+      transactionId,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!transactionId) {
+      throw new Error("transactionId is required");
+    }
+
+    if (!partnerId) {
+      throw new Error("Partner ID is required. Provide via 'partnerId' 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 deleteTransactionDeepLink({
+        transactionId,
+        partnerType: 'payment_institution',
+        partnerId,
+        privateKey
+      });
+
+      return {
+        content: [{
+          type: "text",
+          text: `✅ **Transaction Deep Link Deleted (Payment Institution)**
+
+**Deletion Details:**
+- Transaction ID: ${transactionId}
+- Status: Successfully deleted
+- Link URL: https://url.payware.eu/${transactionId} (now inactive)
+
+**Payment Institution Info:**
+- Partner ID: ${partnerId}
+- Role: SRC/DST for P2P transactions
+
+**API Call Details:**
+- Endpoint: DELETE ${result.requestInfo.url}
+- Status: ${result.requestInfo.statusCode}
+- Method: ${result.requestInfo.method}
+
+**Result:**
+- The deep link is no longer active
+- Mobile redirects will no longer work
+- URL will return an error if accessed
+
+**Important Notes:**
+⚠️ This operation is irreversible
+⚠️ Create a new link if needed using \`payware_deep_links_get_transaction_link\`
+⚠️ Any existing shared links will stop working immediately`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Delete Transaction Deep Link (Payment Institution)**
+
+**Error Details:**
+- Transaction ID: ${transactionId}
+- Message: ${error.message}
+
+**Common Issues:**
+1. **Link not found**: Deep link may already be deleted or never existed
+2. **Authentication failed**: Verify partner ID and private key
+3. **Authorization failed**: Ensure PI is SRC or DST for this transaction
+4. **Sandbox environment**: Deep links are production-only
+5. **Invalid transaction ID**: Ensure transaction ID format is correct
+
+**Troubleshooting:**
+1. Check if deep link exists using \`payware_deep_links_get_transaction_link\`
+2. Verify running in production environment
+3. Ensure JWT authentication is working
+4. Confirm payment institution role in transaction
+5. Ensure transaction ID is correct`
+        }]
+      };
+    }
+  }
+};