@payware/mcp-server 1.0.0 → 1.1.0

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

@@ -0,0 +1,176 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get POI status via ISV authentication
+ * @param {Object} params - Parameters for status request
+ * @returns {Object} POI status response
+ */
+export async function getPOIStatus({ poiId, 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');
+  }
+
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody: null,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  const headers = {
+    'Authorization': `Bearer ${jwtData.token}`,
+    'Content-Type': 'application/json',
+    'Api-Version': '1'
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.get(`${baseUrl}/poi/${poiId}/status`, { headers });
+
+    return {
+      success: true,
+      status: 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?.code,
+        details: error.response?.data
+      },
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+/**
+ * Get POI status tool implementation for ISV
+ */
+export const getPOIStatusTool = {
+  name: "payware_poi_get_status",
+  description: `Get current status of a POI including any pending payment.
+
+**ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
+**Endpoint:** GET /poi/{poiId}/status
+**Use Case:** Check if a POI is idle, has a pending price, or is busy with a payment.
+
+**POI States:**
+- IDLE: Ready for new payment
+- READY: Price set, waiting for customer scan
+- BUSY: Payment in progress
+- DISABLED: Not accepting payments
+
+**Required:** POI ID, Merchant Partner ID, and OAuth2 token.`,
+
+  inputSchema: {
+    type: "object",
+    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"
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment for testing",
+        default: true
+      }
+    }
+  },
+
+  async handler(args) {
+    const { poiId, merchantPartnerId, oauth2Token, useSandbox = true } = args;
+
+    if (!poiId) {
+      throw new Error("POI ID is required");
+    }
+
+    if (!merchantPartnerId) {
+      throw new Error("Merchant Partner ID is required");
+    }
+
+    if (!oauth2Token) {
+      throw new Error("OAuth2 token is required");
+    }
+
+    const result = await getPOIStatus({ poiId, merchantPartnerId, oauth2Token, useSandbox });
+
+    if (result.success) {
+      const status = result.status;
+      const statusEmoji = {
+        'IDLE': '🟢',
+        'READY': '🟡',
+        'BUSY': '🔴',
+        'DISABLED': '⚫'
+      }[status.status] || '⚪';
+
+      let pendingInfo = '';
+      if (status.status === 'READY' || status.status === 'BUSY') {
+        pendingInfo = `
+**Pending Payment:**
+- Amount: ${status.pendingAmount} ${status.pendingCurrency}
+- Expires: ${status.sessionExpiresAt || 'N/A'}${status.transactionId ? `\n- Transaction: ${status.transactionId}` : ''}`;
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `${statusEmoji} **POI Status: ${status.status}**
+
+**POI ID:** ${status.poiId}
+**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
+${pendingInfo}
+
+**Status Meaning:**
+${status.status === 'IDLE' ? '✅ POI is ready to accept a new price' : ''}${status.status === 'READY' ? '⏳ Price set, waiting for customer to scan' : ''}${status.status === 'BUSY' ? '🔄 Customer scanned, payment in progress' : ''}${status.status === 'DISABLED' ? '🚫 POI is disabled and cannot accept payments' : ''}
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Get POI Status**
+
+**POI ID:** ${poiId}
+**Error:** ${result.error.message}
+**Status:** ${result.error.status || 'N/A'}
+
+**Common Issues:**
+- INVALID_POI_ID (400): POI ID format invalid (must be pi + 8 alphanumeric chars)
+- POI_NOT_FOUND (404): POI doesn't exist
+
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  }
+};

package/src/isv/poi/index.js

@@ -0,0 +1,32 @@
+/**
+ * POI (Point of Interaction) tools for ISV partners
+ * Enables management of physical payment points with dynamic pricing
+ */
+
+import { listPOIsTool } from './list-pois.js';
+import { getPOITool } from './get-poi.js';
+import { getPOIStatusTool } from './get-status.js';
+import { setPOIPriceTool } from './set-price.js';
+import { cancelPOIPriceTool } from './cancel-price.js';
+import { getPOIQRCodeTool } from './get-qrcode.js';
+
+/**
+ * All POI tools for ISV
+ */
+export const isvPOITools = [
+  listPOIsTool,
+  getPOITool,
+  getPOIStatusTool,
+  setPOIPriceTool,
+  cancelPOIPriceTool,
+  getPOIQRCodeTool
+];
+
+export {
+  listPOIsTool,
+  getPOITool,
+  getPOIStatusTool,
+  setPOIPriceTool,
+  cancelPOIPriceTool,
+  getPOIQRCodeTool
+};

package/src/isv/poi/list-pois.js

@@ -0,0 +1,168 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * List all POIs for a merchant via ISV authentication
+ * @param {Object} params - Parameters for list request
+ * @returns {Object} List of POIs response
+ */
+export async function listPOIs({ merchantPartnerId, oauth2Token, 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');
+  }
+
+  // Get ISV credentials
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  // Create ISV JWT token (GET request - no body)
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody: null,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  // Required headers as per payware API documentation
+  const headers = {
+    'Authorization': `Bearer ${jwtData.token}`,
+    'Content-Type': 'application/json',
+    'Api-Version': '1'
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.get(`${baseUrl}/poi`, { headers });
+
+    return {
+      success: true,
+      pois: response.data,
+      count: Array.isArray(response.data) ? response.data.length : 0,
+      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?.code,
+        details: error.response?.data
+      },
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+/**
+ * List POIs tool implementation for ISV
+ */
+export const listPOIsTool = {
+  name: "payware_poi_list",
+  description: `List all POIs (Points of Interaction) for a merchant.
+
+**ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
+**Endpoint:** GET /poi
+**Use Case:** Retrieve all physical payment points configured for a merchant.
+
+POI states: IDLE (ready), READY (price set), BUSY (payment in progress), DISABLED.
+
+**Required:** Merchant Partner ID and OAuth2 token for ISV authentication.`,
+
+  inputSchema: {
+    type: "object",
+    required: ["merchantPartnerId", "oauth2Token"],
+    properties: {
+      merchantPartnerId: {
+        type: "string",
+        description: "Partner ID of the target merchant (8 alphanumeric characters)"
+      },
+      oauth2Token: {
+        type: "string",
+        description: "OAuth2 access token obtained from the merchant"
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment for testing",
+        default: true
+      }
+    }
+  },
+
+  async handler(args) {
+    const { merchantPartnerId, oauth2Token, useSandbox = true } = args;
+
+    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 result = await listPOIs({ merchantPartnerId, oauth2Token, useSandbox });
+
+    if (result.success) {
+      const poisList = result.pois.map(poi => {
+        const statusEmoji = {
+          'IDLE': '🟢',
+          'READY': '🟡',
+          'BUSY': '🔴',
+          'DISABLED': '⚫'
+        }[poi.status] || '⚪';
+
+        return `${statusEmoji} **${poi.name}** (${poi.poiId})
+   Shop: ${poi.shopName || poi.shopCode}
+   Status: ${poi.status}${poi.pendingAmount && poi.pendingAmount !== '0.00' ? ` | Pending: ${poi.pendingAmount} ${poi.pendingCurrency}` : ''}`;
+      }).join('\n\n');
+
+      return {
+        content: [{
+          type: "text",
+          text: `📍 **POIs Retrieved (ISV -> Merchant: ${merchantPartnerId})**
+
+**Total POIs:** ${result.count}
+
+${poisList || 'No POIs found for this merchant.'}
+
+**Status Legend:**
+🟢 IDLE - Ready for new payment
+🟡 READY - Price set, waiting for customer
+🔴 BUSY - Payment in progress
+⚫ DISABLED - Not accepting payments
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to List POIs**
+
+**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
+
+**Error Details:**
+- Message: ${result.error.message}
+- Status: ${result.error.status || 'N/A'}
+- Code: ${result.error.code || 'N/A'}
+
+**Troubleshooting:**
+1. Verify OAuth2 token is valid
+2. Ensure merchant has POI feature enabled
+3. Check ISV authorization for merchant
+
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  }
+};

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

@@ -0,0 +1,225 @@
+import axios from 'axios';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Set price on a POI via ISV authentication
+ * @param {Object} params - Parameters for set price request
+ * @returns {Object} Set price response
+ */
+export async function setPOIPrice({ poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams, merchantPartnerId, oauth2Token, useSandbox = true }) {
+  if (!poiId) {
+    throw new Error('POI ID is required');
+  }
+
+  if (!amount) {
+    throw new Error('Amount is required');
+  }
+
+  if (!currency) {
+    throw new Error('Currency is required');
+  }
+
+  if (!reasonL1) {
+    throw new Error('Reason (reasonL1) 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');
+  }
+
+  const isvPartnerId = getPartnerIdSafe();
+  const privateKey = getPrivateKeySafe(useSandbox);
+
+  // Build request body
+  const requestBody = {
+    amount: String(amount),
+    currency: currency.toUpperCase(),
+    reasonL1
+  };
+
+  if (reasonL2) requestBody.reasonL2 = reasonL2;
+  if (timeToLive) requestBody.timeToLive = timeToLive;
+  if (callbackUrl) requestBody.callbackUrl = callbackUrl;
+  if (passbackParams) requestBody.passbackParams = passbackParams;
+
+  const jwtData = await createJWTForPartner({
+    partnerId: isvPartnerId,
+    privateKey,
+    requestBody,
+    merchantId: merchantPartnerId,
+    oauth2Token
+  });
+
+  const headers = {
+    'Authorization': `Bearer ${jwtData.token}`,
+    'Content-Type': 'application/json',
+    'Api-Version': '1'
+  };
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.put(`${baseUrl}/poi/${poiId}/price`, requestBody, { headers });
+
+    return {
+      success: true,
+      result: 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?.code,
+        details: error.response?.data
+      },
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+/**
+ * Set POI price tool implementation for ISV
+ */
+export const setPOIPriceTool = {
+  name: "payware_poi_set_price",
+  description: `Set a pending price on a POI for customer payment.
+
+**ISV Authentication:** Uses ISV JWT with merchant partner ID and OAuth2 token.
+**Endpoint:** PUT /poi/{poiId}/price
+**Use Case:** Set the amount a customer should pay when they scan the POI.
+
+The POI will transition to READY state and wait for a customer scan until the TTL expires.
+
+**Required:** POI ID, amount, currency, reason, Merchant Partner ID, and OAuth2 token.`,
+
+  inputSchema: {
+    type: "object",
+    required: ["poiId", "amount", "currency", "reasonL1", "merchantPartnerId", "oauth2Token"],
+    properties: {
+      poiId: {
+        type: "string",
+        description: "The POI identifier (format: pi + 8 alphanumeric chars, e.g., piABC12345)"
+      },
+      amount: {
+        type: "string",
+        description: "Payment amount (e.g., '25.50')"
+      },
+      currency: {
+        type: "string",
+        description: "ISO 4217 currency code (e.g., 'EUR', 'USD', 'BGN')"
+      },
+      reasonL1: {
+        type: "string",
+        description: "Payment description (e.g., 'Table 5', 'Order #123')"
+      },
+      reasonL2: {
+        type: "string",
+        description: "Additional description (optional)"
+      },
+      timeToLive: {
+        type: "integer",
+        description: "Seconds until price expires (60-600, default: 120)"
+      },
+      callbackUrl: {
+        type: "string",
+        description: "Override callback URL for this payment (optional)"
+      },
+      passbackParams: {
+        type: "string",
+        description: "Data to pass back in callback (optional, max 200 chars)"
+      },
+      merchantPartnerId: {
+        type: "string",
+        description: "Partner ID of the target merchant (8 alphanumeric characters)"
+      },
+      oauth2Token: {
+        type: "string",
+        description: "OAuth2 access token obtained from the merchant"
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment for testing",
+        default: true
+      }
+    }
+  },
+
+  async handler(args) {
+    const { poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams, merchantPartnerId, oauth2Token, useSandbox = true } = args;
+
+    if (!poiId) throw new Error("POI ID is required");
+    if (!amount) throw new Error("Amount is required");
+    if (!currency) throw new Error("Currency is required");
+    if (!reasonL1) throw new Error("Reason (reasonL1) is required");
+    if (!merchantPartnerId) throw new Error("Merchant Partner ID is required");
+    if (!oauth2Token) throw new Error("OAuth2 token is required");
+
+    const result = await setPOIPrice({
+      poiId, amount, currency, reasonL1, reasonL2, timeToLive, callbackUrl, passbackParams,
+      merchantPartnerId, oauth2Token, useSandbox
+    });
+
+    if (result.success) {
+      const data = result.result;
+
+      return {
+        content: [{
+          type: "text",
+          text: `✅ **Price Set Successfully**
+
+**POI ID:** ${data.poiId || poiId}
+**Status:** 🟡 ${data.status || 'READY'}
+
+**Payment Details:**
+- Amount: **${data.amount || amount} ${data.currency || currency}**
+- Reason: ${reasonL1}${reasonL2 ? ` - ${reasonL2}` : ''}
+
+**Session:**
+- Token: ${data.sessionToken || 'N/A'}
+- Expires: ${data.sessionExpiresAt || 'N/A'}
+
+**Next Steps:**
+1. Customer scans the POI (QR code, NFC tag, or barcode)
+2. Customer sees the amount and confirms payment
+3. You receive a callback when payment completes
+
+**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${merchantPartnerId}
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Failed to Set Price**
+
+**POI ID:** ${poiId}
+**Attempted:** ${amount} ${currency}
+
+**Error:** ${result.error.message}
+**Code:** ${result.error.code || 'N/A'}
+**Status:** ${result.error.status || 'N/A'}
+
+**Common Issues:**
+- INVALID_POI_ID (400): POI ID format invalid (must be pi + 8 alphanumeric chars)
+- POI_NOT_FOUND (404): POI doesn't exist or doesn't belong to merchant
+- POI_DISABLED (409): POI is disabled
+- POI_NOT_IDLE (409): POI already has a pending price (cancel it first)
+- INVALID_AMOUNT (400): Check amount format (e.g., '25.50')
+- UNKNOWN_CURRENCY (400): Invalid currency code
+
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  }
+};

package/src/isv/transactions/get-status.js

@@ -159,7 +159,7 @@ export const getTransactionStatusTool = {
 - ID: ${result.transaction.id || 'N/A'}
 - Type: ${result.transaction.type || 'N/A'}
 - Amount: ${result.transaction.trData ? `${result.transaction.trData.amount} ${result.transaction.trData.currency}` : 'N/A'}
-- Description: ${result.transaction.description || 'N/A'}
+${result.transaction.paymentMethod ? `- Payment Method: ${result.transaction.paymentMethod}\n` : ''}- Description: ${result.transaction.description || 'N/A'}
 - Created: ${result.transaction.createdAt || 'N/A'}
 - Updated: ${result.transaction.updatedAt || 'N/A'}
 

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

@@ -140,7 +140,8 @@ Requires ISV authentication with merchant partner ID and OAuth2 token.`,
           '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'}`;
+        const paymentInfo = tx.paymentMethod ? ` [${tx.paymentMethod}]` : '';
+        return `  ${emoji} **${tx.id}** - ${tx.trData?.amount || '0.00'} ${tx.trData?.currency || 'EUR'}${paymentInfo} - ${tx.status} - ${tx.createdAt || 'N/A'}`;
       };
 
       return {

package/src/mcp-proxy.js

@@ -111,13 +111,13 @@ class PaywareMCPBridge {
     };
 
     process.on('SIGINT', async () => {
-      console.log('\nShutting down MCP Bridge...');
+      console.error('\nShutting down MCP Bridge...');
       await this.server.close();
       process.exit(0);
     });
 
     process.on('SIGTERM', async () => {
-      console.log('\nShutting down MCP Bridge...');
+      console.error('\nShutting down MCP Bridge...');
       await this.server.close();
       process.exit(0);
     });

package/src/merchant/data/export-report.js

@@ -27,8 +27,7 @@ export const exportReportTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication. Uses production private key as default (Data API is production-only)."
       }
     },
     required: ["requestId"]
@@ -39,11 +38,11 @@ export const exportReportTool = {
       requestId,
       outputFormat = EXPORT_FORMATS.PDF,
       partnerId = getPartnerIdSafe(),
-      privateKey = getPrivateKeySafe()
+      privateKey = getPrivateKeySafe(false)  // false = production (Data API is production-only)
     } = args;
 
     if (!partnerId || !privateKey) {
-      throw new Error("Partner ID and private key are required. Set PAYWARE_PARTNER_ID and environment-specific private key variables or provide them as parameters.");
+      throw new Error("Partner ID and private key are required. Set PAYWARE_PARTNER_ID and PAYWARE_PRODUCTION_PRIVATE_KEY_PATH environment variables or provide them as parameters.");
     }
 
     try {

package/src/merchant/data/generate-report.js

@@ -49,8 +49,7 @@ export const generateReportTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for authentication. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for authentication. Uses production private key as default (Data API is production-only)."
       }
     },
     required: ["reportUnitId"]
@@ -65,11 +64,11 @@ export const generateReportTool = {
       locale = LOCALES.ENGLISH_US,
       timeZone = 'GMT',
       partnerId = getPartnerIdSafe(),
-      privateKey = getPrivateKeySafe()
+      privateKey = getPrivateKeySafe(false)  // false = production (Data API is production-only)
     } = args;
 
     if (!partnerId || !privateKey) {
-      throw new Error("Partner ID and private key are required. Set PAYWARE_PARTNER_ID and environment-specific private key variables or provide them as parameters.");
+      throw new Error("Partner ID and private key are required. Set PAYWARE_PARTNER_ID and PAYWARE_PRODUCTION_PRIVATE_KEY_PATH environment variables or provide them as parameters.");
     }
 
     // Check for required date range on premium reports