@payware/mcp-server 1.0.0

package/src/merchant/products/update-product.js

@@ -0,0 +1,282 @@
+import { updateProduct } from '../../shared/products/products-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { PRODUCT_TYPES, OVERLAP_PRIORITY } from '../../shared/products/products-api.js';
+
+/**
+ * Update product tool implementation for merchants
+ */
+export const updateProductTool = {
+  name: "payware_products_update_product",
+  description: `Update an existing product. Only provide the fields you want to change.
+
+**Product Structure:**
+📦 **PRODUCT METADATA**: name, shortDescription, longDescription, sku, upc, shippable, active, shop
+💰 **PRODUCT DATA** (prData object): type, regularPrice, currency, overlapPriority, timeToLive, activeFrom, activeTo, timeZone
+⚙️ **PRODUCT OPTIONS** (prOptions object): imageUrl, termsUrl, termsText`,
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      productId: {
+        type: "string",
+        description: "Product identifier to update (starts with 'pr')",
+        pattern: "^pr[a-zA-Z0-9]+$"
+      },
+      name: {
+        type: "string",
+        description: "Product recognizable name",
+        maxLength: 50
+      },
+      shortDescription: {
+        type: "string",
+        description: "Short product description",
+        maxLength: 150
+      },
+      longDescription: {
+        type: "string",
+        description: "Long product description",
+        maxLength: 1500
+      },
+      sku: {
+        type: "string",
+        description: "Stock Keeping Unit (SKU)",
+        maxLength: 25
+      },
+      upc: {
+        type: "string",
+        description: "Universal Product Code (UPC)",
+        maxLength: 15
+      },
+      shippable: {
+        type: "string",
+        enum: ["TRUE", "FALSE"],
+        description: "Indicates if product requires delivery address"
+      },
+      active: {
+        type: "string",
+        enum: ["TRUE", "FALSE"],
+        description: "Indicates if product can serve as payment source"
+      },
+      shop: {
+        type: "string",
+        description: "Shop code",
+        maxLength: 10
+      },
+      // Product Data Properties
+      productType: {
+        type: "string",
+        enum: Object.values(PRODUCT_TYPES),
+        description: "Type of product"
+      },
+      regularPrice: {
+        type: "string",
+        description: "Product regular price (positive number with max 2 decimals)"
+      },
+      currency: {
+        type: "string",
+        pattern: "^[A-Z]{3}$",
+        description: "Price currency (3-character ISO code)"
+      },
+      overlapPriority: {
+        type: "string",
+        enum: Object.values(OVERLAP_PRIORITY),
+        description: "Priority when overlapping price schedules exist"
+      },
+      timeToLive: {
+        type: "number",
+        description: "Time allowed for product payment in seconds (60-2592000)",
+        minimum: 60,
+        maximum: 2592000
+      },
+      activeFrom: {
+        type: "string",
+        pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+        description: "Product active state starting date (YYYY-MM-DD format)"
+      },
+      activeTo: {
+        type: "string",
+        pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+        description: "Product active state ending date (YYYY-MM-DD format)"
+      },
+      timeZone: {
+        type: "string",
+        description: "Product state scheduling timezone (IANA format, e.g., 'Europe/Sofia')"
+      },
+      // Product Options Properties
+      imageUrl: {
+        type: "string",
+        description: "URL pointing to external product image resource",
+        maxLength: 150,
+        format: "uri"
+      },
+      termsUrl: {
+        type: "string",
+        description: "URL pointing to external terms and conditions resource",
+        maxLength: 150,
+        format: "uri"
+      },
+      termsText: {
+        type: "string",
+        description: "Terms and conditions text",
+        maxLength: 3000
+      },
+      // Authentication
+      partnerId: {
+        type: "string",
+        description: "Merchant partner ID (uses PAYWARE_PARTNER_ID env var as default)",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key for authentication (uses environment-specific private key as default)",
+        default: getPrivateKeySafe()
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment",
+        default: true
+      }
+    },
+    required: ["productId"]
+  },
+
+  async handler(args) {
+    const {
+      productId,
+      name,
+      shortDescription,
+      longDescription,
+      sku,
+      upc,
+      shippable,
+      active,
+      shop,
+      productType,
+      regularPrice,
+      currency,
+      overlapPriority,
+      timeToLive,
+      activeFrom,
+      activeTo,
+      timeZone,
+      imageUrl,
+      termsUrl,
+      termsText,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe(),
+      useSandbox = true
+    } = args;
+
+    if (!productId) {
+      throw new Error("Product 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 environment-specific private key variable.");
+    }
+
+    // Build prData object only with provided fields
+    const prData = {};
+    if (productType !== undefined) prData.type = productType;
+    if (regularPrice !== undefined) prData.regularPrice = regularPrice;
+    if (currency !== undefined) prData.currency = currency;
+    if (overlapPriority !== undefined) prData.overlapPriority = overlapPriority;
+    if (timeToLive !== undefined) prData.timeToLive = timeToLive;
+    if (activeFrom !== undefined) prData.activeFrom = activeFrom;
+    if (activeTo !== undefined) prData.activeTo = activeTo;
+    if (timeZone !== undefined) prData.timeZone = timeZone;
+
+    // Build prOptions object only with provided fields
+    const prOptions = {};
+    if (imageUrl !== undefined) prOptions.imageUrl = imageUrl;
+    if (termsUrl !== undefined) prOptions.termsUrl = termsUrl;
+    if (termsText !== undefined) prOptions.termsText = termsText;
+
+    try {
+      const result = await updateProduct({
+        productId,
+        name,
+        shortDescription,
+        longDescription,
+        sku,
+        upc,
+        shippable,
+        active,
+        shop,
+        prData,
+        prOptions,
+        partnerType: 'merchant',
+        partnerId,
+        privateKey,
+        useSandbox
+      });
+
+      const product = result.data;
+
+      return {
+        content: [{
+          type: "text",
+          text: `✅ **Product Updated Successfully**
+
+**Updated Product Details:**
+- ID: ${product.productId}
+- Name: ${product.name}
+- Type: ${product.type}
+- Price: ${product.regularPrice} ${product.currencyCode}
+- Status: ${product.active ? '✅ Active' : '⏸️ Inactive'}
+- Shop: ${product.shopCode} (${product.shopName})
+${product.shortDescription ? `- Description: ${product.shortDescription}` : ''}
+${product.sku ? `- SKU: ${product.sku}` : ''}
+${product.upc ? `- UPC: ${product.upc}` : ''}
+
+**Product Settings:**
+- Shippable: ${product.shippable ? 'Yes' : 'No'}
+- Time to Live: ${product.timeToLive} seconds
+- Sale Price: ${product.salePrice} ${product.currencyCode}
+- Overlap Priority: ${product.overlapPriority}
+
+**Active Period:**
+- From: ${product.activeFromZoned || product.activeFrom}
+- To: ${product.activeToZoned || product.activeTo}
+- Timezone: ${product.timeZone}
+
+**API Response:**
+\`\`\`json
+${JSON.stringify(product, null, 2)}
+\`\`\`
+
+**API Call Details:**
+- Endpoint: ${result.requestInfo.method} ${result.requestInfo.url}
+- Status: ${result.requestInfo.statusCode}
+
+**Next Steps:**
+- Use \`payware_products_get_product\` to view updated product details
+- Use \`payware_products_create_schedule\` to manage price schedules
+- Use \`payware_products_get_product_image\` to generate QR/barcode`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Product Update Failed**
+
+**Error Details:**
+- Message: ${error.message}
+- Product ID: ${productId}
+
+**Troubleshooting:**
+1. Verify the product ID is correct and exists
+2. Check parameter values (dates, price format, currency)
+3. Ensure JWT token is valid and not expired
+4. Verify partner ID and API access
+5. Check that the product belongs to your account`
+        }]
+      };
+    }
+  }
+};

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

@@ -0,0 +1,241 @@
+import axios from 'axios';
+import { createJWTToken } from '../../core/auth/jwt-token.js';
+import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
+import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Cancel a transaction via payware API
+ * @param {Object} params - Transaction cancellation parameters
+ * @returns {Object} Transaction cancellation response
+ */
+export async function cancelTransaction({
+  transactionId,
+  statusMessage,
+  partnerId,
+  privateKey,
+  useSandbox = true
+}) {
+  if (!transactionId) {
+    throw new Error('Transaction ID is required');
+  }
+  
+  if (!statusMessage) {
+    throw new Error('Status message is required (cancellation reason)');
+  }
+  
+  if (statusMessage.length > 100) {
+    throw new Error('Status message cannot exceed 100 characters');
+  }
+  
+  if (!partnerId || !privateKey) {
+    throw new Error('Partner ID and private key are required for proper JWT creation');
+  }
+  
+  // Build request body according to documentation
+  const requestBody = {
+    status: 'CANCELLED',
+    statusMessage
+  };
+  
+  // Convert to deterministic minimized JSON for MD5 calculation
+  const minimizedBodyString = createMinimizedJSON(requestBody);
+  
+  // Create JWT token with contentMd5 for the request body (PATCH requires contentMd5)
+  const tokenData = createJWTToken(partnerId, privateKey, minimizedBodyString);
+  
+  // 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 {
+    // Send the exact minimized JSON string that was used for MD5 calculation
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.patch(`${baseUrl}/transactions/${transactionId}`, minimizedBodyString, {
+      headers,
+      // Tell axios to send the string as-is, don't serialize it again
+      transformRequest: [(data) => data]
+    });
+    
+    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
+      },
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+/**
+ * Cancel transaction tool implementation
+ */
+export const cancelTransactionTool = {
+  name: "payware_operations_cancel_transaction",
+  description: "Cancel an ACTIVE transaction created by this merchant. Only the merchant who created the transaction can cancel it, and only before it has been processed.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      transactionId: {
+        type: "string",
+        description: "Transaction ID to cancel (must be ACTIVE transaction created by this merchant). Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
+        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+      },
+      statusMessage: {
+        type: "string",
+        description: "Reason for cancellation (required)",
+        maxLength: 100,
+        minLength: 1
+      },
+      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", "statusMessage"]
+  },
+  
+  async handler(args) {
+    const {
+      transactionId,
+      statusMessage,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe(args.useSandbox ?? true),
+      useSandbox = true
+    } = args;
+    
+    if (!transactionId) {
+      throw new Error("Transaction ID is required");
+    }
+    
+    if (!statusMessage) {
+      throw new Error("Status message is required (reason for cancellation)");
+    }
+    
+    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 cancelTransaction({
+      transactionId,
+      statusMessage,
+      partnerId,
+      privateKey,
+      useSandbox
+    });
+    
+    if (result.success) {
+      return {
+        content: [{
+          type: "text",
+          text: `🚫 **Transaction Cancelled Successfully**
+
+**Transaction ID:** ${transactionId}
+**Status:** ${result.transaction.status || 'CANCELLED'}
+
+**Cancellation Details:**
+- Reason: ${statusMessage}
+- Amount: ${result.transaction.amount ? `${result.transaction.amount} ${result.transaction.currency}` : 'N/A'}
+- Cancelled At: ${result.timestamp}
+- Cancelled By: Transaction Creator (Merchant)
+
+**API Response:**
+\`\`\`json
+${JSON.stringify(result.transaction, null, 2)}
+\`\`\`
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}
+
+**Important Notes:**
+- ✅ Transaction successfully cancelled by its creator
+- 🔒 No payment processing will occur
+- 📧 Callbacks may be sent to notify interested parties
+- ⏰ Cancellation is permanent and cannot be undone
+- 👤 Only the merchant who created this transaction can cancel it
+
+**Merchant Cancellation Rules:**
+- ✅ Can cancel: Active transactions you created
+- ❌ Cannot cancel: Transactions created by others
+- ❌ Cannot cancel: Already processed transactions
+- ❌ Cannot cancel: Expired transactions
+
+**Next Steps:**
+1. Wait for callback confirmation (if configured)
+2. Update your internal systems
+3. Notify customers if applicable
+4. Create new transaction if payment still needed`
+        }]
+      };
+    } else {
+      return {
+        content: [{
+          type: "text", 
+          text: `❌ **Transaction Cancellation Failed**
+
+**Transaction ID:** ${transactionId}
+
+**Error Details:**
+- Message: ${result.error.message}
+- Status: ${result.error.status || 'N/A'}
+- Code: ${result.error.code || 'N/A'}
+
+**Full Error Response:**
+\`\`\`json
+${JSON.stringify(result.error.details || result.error, null, 2)}
+\`\`\`
+
+**Timestamp:** ${result.timestamp}
+
+**Common Issues:**
+1. **ERR_MISSING_TRANSACTION**: Transaction not found or expired
+2. **ERR_ALREADY_PROCESSED**: Transaction already processed, cannot cancel
+3. **ERR_UNAUTHORIZED_OPERATION**: Only transaction creator can cancel
+4. **ERR_INVALID_STATUS_MESSAGE**: Status message invalid or too long
+
+**Merchant Cancellation Restrictions:**
+- ⚠️ **Creator Only**: Only the merchant who created the transaction can cancel it
+- ⚠️ **Active Only**: Transaction must be in ACTIVE state (not processed/expired)
+- ⚠️ **Before Processing**: Cannot cancel after merchant/PI has processed it
+- ⚠️ **Before Expiry**: Cannot cancel expired transactions
+
+**Troubleshooting:**
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+2. **Ensure you are the transaction creator** (not just any merchant)
+3. Check transaction hasn't been processed already by anyone
+4. Verify status message is under 100 characters
+5. Ensure transaction is still active (not expired)
+6. Confirm you created this transaction with your merchant account`
+        }]
+      };
+    }
+  }
+};