@payware/mcp-server 1.1.1 → 1.3.0

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

@@ -1,22 +1,35 @@
 import axios from 'axios';
 import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { describeApiError } from '../../shared/api-errors.js';
 
 /**
- * Get transaction history from payware API as an ISV
+ * Get one completed transaction as an ISV acting on behalf of a merchant.
+ *
+ * **This used to be a list-and-filter tool, and there is nothing on the server to list.**
+ * It built `GET /transactions-history?limit=50&offset=0&status=...&from=...&to=...` and read
+ * `result.transactions` / `result.totalCount` off the response. `TransactionHistoryController` maps
+ * exactly one route - `GET /api/transactions-history/{transactionId}` - so the bare path matched no
+ * handler and the call answered 404 every time, whatever the filters said. The filters, the
+ * pagination and the result shape were all describing an endpoint that has never existed.
+ *
+ * It now does what the merchant tool does and what the API offers: fetch one transaction by id.
  */
 export async function getTransactionHistory({
   merchantPartnerId,
   oauth2Token,
-  partnerId,
   transactionId,
-  limit = 50,
-  offset = 0,
-  status,
-  from,
-  to,
   useSandbox = true
 }) {
+  if (!transactionId) {
+    throw new Error(
+      'transactionId is required. The payware API has no endpoint that lists or filters transaction ' +
+      'history - GET /transactions-history/{transactionId} fetches one transaction by id, and that ' +
+      'is the whole surface. Keep your own record of the ids you created, or read them from the ' +
+      'callbacks you received.'
+    );
+  }
+
   if (!merchantPartnerId) {
     throw new Error('Merchant Partner ID is required for ISV operations');
   }
@@ -28,6 +41,7 @@ export async function getTransactionHistory({
   const isvPartnerId = getPartnerIdSafe();
   const privateKey = getPrivateKeySafe(useSandbox);
 
+  // GET, so no body and no content hash.
   const jwtData = await createJWTForPartner({
     partnerId: isvPartnerId,
     privateKey,
@@ -36,19 +50,9 @@ export async function getTransactionHistory({
     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, {
+    const response = await axios.get(`${baseUrl}/transactions-history/${transactionId}`, {
       headers: {
         'Authorization': `Bearer ${jwtData.token}`,
         'Content-Type': 'application/json',
@@ -58,62 +62,50 @@ export async function getTransactionHistory({
 
     return response.data;
   } catch (error) {
-    if (error.response) {
-      throw new Error(`payware API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
-    }
-    throw error;
+    throw describeApiError(error, 'call the payware API');
   }
 }
 
 export const getTransactionHistoryTool = {
   name: 'payware_operations_get_transaction_history',
-  description: `Get transaction history as an ISV on behalf of a merchant.
+  description: `Get one completed or expired transaction as an ISV on behalf of a merchant.
+
+**Endpoint:** GET /transactions-history/{transactionId}
+
+Returns a transaction in a final state: CONFIRMED, DECLINED, FAILED, EXPIRED or CANCELLED. For a
+transaction still ACTIVE, use \`payware_operations_get_transaction_status\` instead - the two
+endpoints cover disjoint sets of transactions and neither falls back to the other.
+
+⚠️ **There is no way to list or search transaction history.** This endpoint takes an id and returns
+that one transaction. There is no pagination, no date range and no status filter anywhere in the
+payware API - so keep your own record of the transaction ids you created, or read them from the
+callbacks you received. (This tool previously advertised \`limit\`, \`offset\`, \`status\`, \`from\` and
+\`to\` parameters; they described an endpoint that does not exist and every call 404'd.)
+
+📦 **This is the only source of the delivery address.** For a SHIPPABLE transaction,
+\`deliveryAddress\` is returned here and nowhere else - it was removed from the finalized callback on
+2026-08-07, because a callback goes to whatever certificate the merchant's endpoint presents and a
+shopper's home address does not belong on that channel. The callback tells you the shipment is
+ready; this call gives you the address.
 
-Retrieves both active and completed transactions with optional filtering.
-Requires ISV authentication with merchant partner ID and OAuth2 token.`,
+⚠️ **The MERCHANT's plan governs, and this endpoint is now gated.** It was ungated until 2026-08-21
+and now requires Standard or Premium, so acting for a **Basic** merchant answers **403**.`,
 
   inputSchema: {
     type: 'object',
-    required: ['merchantPartnerId', 'oauth2Token'],
+    required: ['transactionId', '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'
+        description: 'The transaction to fetch, e.g. "pw7e4rCToG". Required - there is no list or search endpoint.'
       },
-      status: {
-        type: 'string',
-        enum: ['ACTIVE', 'CONFIRMED', 'DECLINED', 'FAILED', 'EXPIRED', 'CANCELLED'],
-        description: 'Filter by transaction status'
-      },
-      from: {
+      merchantPartnerId: {
         type: 'string',
-        description: 'Start date for filtering (YYYY-MM-DD format)'
+        description: 'Partner ID of the target merchant (8 alphanumeric characters)'
       },
-      to: {
+      oauth2Token: {
         type: 'string',
-        description: 'End date for filtering (YYYY-MM-DD format)'
+        description: 'OAuth2 access token obtained from the merchant'
       },
       useSandbox: {
         type: 'boolean',
@@ -125,46 +117,46 @@ Requires ISV authentication with merchant partner ID and OAuth2 token.`,
 
   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] || '❓';
-        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'}`;
+      const tx = await getTransactionHistory(params);
+
+      const statusEmojis = {
+        CONFIRMED: '✅',
+        DECLINED: '❌',
+        FAILED: '⚠️',
+        EXPIRED: '⏰',
+        CANCELLED: '🚫'
       };
+      const emoji = statusEmojis[tx.status] || '❓';
+
+      const delivery = tx.deliveryAddress ? `
+
+📦 **Delivery Address** (SHIPPABLE)
+- Name: ${tx.deliveryAddress.fullName || 'N/A'}
+- Address: ${tx.deliveryAddress.streetAddressLine1 || 'N/A'}${tx.deliveryAddress.streetAddressLine2 ? `, ${tx.deliveryAddress.streetAddressLine2}` : ''}
+- City: ${tx.deliveryAddress.city || 'N/A'}, ${tx.deliveryAddress.zipCode || 'N/A'}
+- Region: ${tx.deliveryAddress.region || 'N/A'}
+- Country: ${tx.deliveryAddress.country || 'N/A'}
+- Phone: ${tx.deliveryAddress.phoneNumber || 'N/A'}
+- Email: ${tx.deliveryAddress.email || 'N/A'}` : '';
 
       return {
         content: [{
           type: 'text',
-          text: `📈 **Transaction History Retrieved (ISV -> Merchant: ${params.merchantPartnerId})**
+          text: `${emoji} **Transaction ${tx.transactionId || params.transactionId}** - ${tx.status}
 
-**ISV Integration:**
-- ISV Partner: ${getPartnerIdSafe()}
-- Target Merchant: ${params.merchantPartnerId}
-- OAuth2 Token: ${params.oauth2Token.substring(0, 8)}...
+**ISV -> Merchant:** ${getPartnerIdSafe()} -> ${params.merchantPartnerId}
 
-**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` : ''}
+- Amount: ${tx.amount ?? 'N/A'} ${tx.currency ?? ''}
+- Fee: ${tx.fee ?? '(not reported - absence means unknown, not zero)'}
+- Type: ${tx.transactionType ?? 'N/A'}
+- Payment method: ${tx.paymentMethod ?? 'N/A'}
+- Status message: ${tx.statusMessage ?? 'N/A'}
+- Created: ${tx.created ?? 'N/A'}
+- Finalized: ${tx.finalized ?? '(absent - EXPIRED transactions carry no finalization moment)'}${delivery}
 
 **Raw Response:**
 \`\`\`json
-${JSON.stringify(result, null, 2)}
+${JSON.stringify(tx, null, 2)}
 \`\`\``
         }]
       };
@@ -179,9 +171,13 @@ ${JSON.stringify(result, null, 2)}
 **ISV Authentication:**
 - Merchant Partner ID: ${params.merchantPartnerId}
 - OAuth2 Token: ${params.oauth2Token ? 'Provided' : 'Missing'}
-- ISV Partner ID: ${getPartnerIdSafe()}`
+- ISV Partner ID: ${getPartnerIdSafe()}
+
+**Common causes:**
+- 404: the transaction is still ACTIVE (use \`payware_operations_get_transaction_status\`), or the id is wrong.
+- 403: the acting merchant is on the Basic plan, which does not include transaction history.`
         }]
       };
     }
   }
-};
+};

package/src/isv/utils/auth.js

@@ -80,11 +80,11 @@ async function createOAuth2JWT({ isvPartnerId, privateKey, requestBody, audience
     typ: 'JWT'
   };
 
-  // Add contentMd5 to header if request body exists
+  // Add contentSha256 to header if request body exists (SHA-256 is preferred over MD5)
   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');
+    header.contentSha256 = crypto.default.createHash('sha256').update(bodyString, 'utf8').digest('base64');
   }
 
   // JWT Payload for OAuth2 requests

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

@@ -6,7 +6,25 @@ import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
  */
 export const generateReportTool = {
   name: "payware_data_generate_report",
-  description: "Generate an asynchronous data report for merchant data analysis and reporting. Production only - not supported in sandbox.",
+  description: `Generate an asynchronous data report for merchant data analysis and reporting. Production only - not supported in sandbox.
+
+⚠️ **Running a report is entitlement-checked as of 2026-08-22.** Naming a report answers **403
+\`ERR_REPORT_NOT_AVAILABLE\`** when that report is not included in the caller's plan or partner type.
+Until that date only the *menu* was filtered - the door was not - so a caller that hard-coded a
+report id it had never been offered could still run it, and may now start failing.
+
+**Always resolve the id from \`payware_data_list_reports\` rather than hard-coding one.** That call
+and this check share a single rule, so the menu and the door cannot drift apart: if a report is in
+that list, this call will accept it.
+
+Distinguish the two failures:
+- **403 \`ERR_REPORT_NOT_AVAILABLE\`** - the report exists, this caller may not run it. Not retryable;
+  it is a plan boundary, not a transient error.
+- **404 \`ERR_REPORT_UNIT_ID_NOT_FOUND\`** - no report is registered under that id at all. Usually a
+  typo or a stale id.
+
+For an ISV acting on behalf of a merchant, the plan that applies is the **merchant's**, and reports
+are outside the Basic plan entirely.`,
   inputSchema: {
     type: "object",
     properties: {

package/src/merchant/index.js

@@ -20,6 +20,12 @@ import { merchantProductTools } from './products/index.js';
 // Deep links tools
 import { merchantDeepLinksTools } from './deep-links/index.js';
 
+// Logs tools (Premium feature)
+import { merchantLogsTools } from './logs/index.js';
+
+// Shop tools - needed before any call that takes a shop / shopCode
+import { merchantShopTools } from './shops/index.js';
+
 // Shared utility tools
 import { getServerInfoTool } from '../utils/server-info.js';
 
@@ -48,7 +54,13 @@ export const merchantTools = [
   ...merchantProductTools,
 
   // Deep links management
-  ...merchantDeepLinksTools
+  ...merchantDeepLinksTools,
+
+  // Logs management (Premium feature)
+  ...merchantLogsTools,
+
+  // Shop lookup
+  ...merchantShopTools
 ];
 
 /**
@@ -83,6 +95,14 @@ export function getMerchantTools() {
     else if (tool.name.startsWith('payware_deep_links_')) {
       newName = tool.name; // Keep deep_links grouping
     }
+    // Logs tools keep their logs grouping
+    else if (tool.name.startsWith('payware_logs_')) {
+      newName = tool.name; // Keep logs grouping
+    }
+    // Shop tools keep their shops grouping
+    else if (tool.name.startsWith('payware_shops_')) {
+      newName = tool.name; // Keep shops grouping
+    }
 
     return {
       ...tool,