@payware/mcp-server 1.0.0

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

@@ -0,0 +1,141 @@
+import { getTransactionDeepLink } from '../../shared/deep-links/api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get deep link for a payment institution transaction
+ */
+export const getTransactionLinkTool = {
+  name: "payware_deep_links_get_transaction_link",
+  description: `Get an active deep link for a transaction where the payment institution acts as source (SRC) or destination (DST). Returns a clickable URL that redirects to the payware mobile app.
+
+**Deep Link Format:**
+- Web URL: https://url.payware.eu/{transactionId}
+- Mobile Redirect: payware://{transactionId}
+
+**Use Cases:**
+- P2P payments initiated via messaging services
+- Transaction notifications with direct links
+- Transaction status sharing
+
+**Important Notes:**
+- Deep links are only supported in production environment
+- Link expiration is synchronized with the referenced transaction
+- Payment institutions only manage transaction links (no product links)
+- 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]+$"
+      },
+      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 getTransactionDeepLink({
+        transactionId,
+        partnerType: 'payment_institution',
+        partnerId,
+        privateKey
+      });
+
+      // 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 (Payment Institution)**
+
+**Deep Link Details:**
+- Transaction ID: ${transactionId}
+- Web URL: ${linkUrl}
+- Mobile Redirect: payware://${transactionId}
+
+**Payment Institution Info:**
+- Partner ID: ${partnerId}
+- Role: SRC/DST for P2P transactions
+
+**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. Use for P2P transaction notifications and sharing`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Get Transaction Deep Link (Payment Institution)**
+
+**Error Details:**
+- Transaction ID: ${transactionId}
+- Message: ${error.message}
+
+**Common Issues:**
+1. **Transaction not found**: Check if transaction exists and is not expired
+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. Verify transaction exists using \`payware_transactions_get_transaction_status\`
+2. Check if running in production environment
+3. Ensure JWT authentication is working
+4. Confirm payment institution role in transaction
+5. Verify transaction is not expired`
+        }]
+      };
+    }
+  }
+};

package/src/payment-institution/deep-links/index.js

@@ -0,0 +1,17 @@
+/**
+ * Payment Institution Deep Links Tools
+ * Deep link management for payment institutions (transaction links only)
+ */
+
+import { getTransactionLinkTool } from './get-transaction-link.js';
+import { deleteTransactionLinkTool } from './delete-transaction-link.js';
+
+export const paymentInstitutionDeepLinksTools = [
+  getTransactionLinkTool,
+  deleteTransactionLinkTool
+];
+
+export {
+  getTransactionLinkTool,
+  deleteTransactionLinkTool
+};

package/src/payment-institution/index.js

@@ -0,0 +1,92 @@
+/**
+ * Payment Institution partner tools registry
+ * Tools available for banks, e-wallets, and financial institutions
+ *
+ * Features specific to Payment Institutions:
+ * - Role-based transactions (SRC/DST)
+ * - Account and friendlyName requirements
+ * - Transaction processing and finalization
+ * - P2P cross-institution payments
+ * - Extended TTL ranges (up to 30 days)
+ * - Soundbite transaction support
+ * - Transaction history access
+ * - Callback handling (TRANSACTION_PROCESSED, TRANSACTION_FINALIZED)
+ */
+
+// Import payment institution specific transaction tools
+import { createPITransactionTool } from './transactions/create-pi-transaction.js';
+import { processPITransactionTool } from './transactions/process-pi-transaction.js';
+import { finalizeTransactionTool } from './transactions/finalize-transaction.js';
+import { getPITransactionStatusTool } from './transactions/get-transaction-status.js';
+import { getPITransactionHistoryTool } from './transactions/get-transaction-history.js';
+import { soundbiteTransactionTool } from './transactions/soundbite-transaction.js';
+import { simulatePICallbackTool } from './transactions/simulate-pi-callback.js';
+
+// Data tools
+import { paymentInstitutionDataTools } from './data/index.js';
+
+// Deep links tools
+import { paymentInstitutionDeepLinksTools } from './deep-links/index.js';
+
+// Import shared tools
+import { sharedTools } from '../shared/index.js';
+
+/**
+ * Payment Institution specific tools
+ * Includes role-based transactions, P2P flows, and PI-specific operations
+ */
+export const paymentInstitutionTools = [
+  // Shared tools (authentication, utilities, etc.)
+  ...sharedTools,
+
+  // PI-specific transaction tools
+  createPITransactionTool,
+  processPITransactionTool,
+  finalizeTransactionTool,
+  getPITransactionStatusTool,
+  getPITransactionHistoryTool,
+  soundbiteTransactionTool,
+  simulatePICallbackTool,
+
+  // Data management
+  ...paymentInstitutionDataTools,
+
+  // Deep links management
+  ...paymentInstitutionDeepLinksTools
+];
+
+/**
+ * Get tools for Payment Institution partner type with proper grouping
+ * @returns {Array} Array of Payment Institution tools with grouped names
+ */
+export function getPaymentInstitutionTools() {
+  return paymentInstitutionTools.map(tool => {
+    let newName = tool.name;
+
+    // Authentication tools use authentication grouping
+    if (tool.name.startsWith('payware_authentication_')) {
+      newName = tool.name; // Keep authentication grouping
+    }
+    // Utility tools keep their utils grouping
+    else if (tool.name.startsWith('payware_utils_')) {
+      newName = tool.name; // Keep utils grouping
+    }
+    // Operations tools (PI-specific transaction operations) 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
+    }
+    // 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
+    };
+  });
+}