@payware/mcp-server 1.0.0

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

@@ -0,0 +1,288 @@
+import { createProduct } from '../../shared/products/products-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { PRODUCT_TYPES, OVERLAP_PRIORITY } from '../../shared/products/products-api.js';
+
+/**
+ * Create product tool implementation for merchants
+ */
+export const createProductTool = {
+  name: "payware_products_create_product",
+  description: `Create a new product for inventory management and payment processing.
+
+**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
+
+**Required:** name
+**Optional:** All other parameters have sensible defaults`,
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: {
+        type: "string",
+        description: "Product recognizable name (required)",
+        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",
+        default: "FALSE"
+      },
+      active: {
+        type: "string",
+        enum: ["TRUE", "FALSE"],
+        description: "Indicates if product can serve as payment source",
+        default: "FALSE"
+      },
+      shop: {
+        type: "string",
+        description: "Shop code (if not supplied, default shop is used)",
+        maxLength: 10
+      },
+      // Product Data Properties
+      productType: {
+        type: "string",
+        enum: Object.values(PRODUCT_TYPES),
+        description: "Type of product",
+        default: PRODUCT_TYPES.ITEM
+      },
+      regularPrice: {
+        type: "string",
+        description: "Product regular price (positive number with max 2 decimals)",
+        default: "0.00"
+      },
+      currency: {
+        type: "string",
+        pattern: "^[A-Z]{3}$",
+        description: "Price currency (3-character ISO code)",
+        default: "EUR"
+      },
+      overlapPriority: {
+        type: "string",
+        enum: Object.values(OVERLAP_PRIORITY),
+        description: "Priority when overlapping price schedules exist",
+        default: OVERLAP_PRIORITY.LOWEST
+      },
+      timeToLive: {
+        type: "number",
+        description: "Time allowed for product payment in seconds (60-2592000)",
+        minimum: 60,
+        maximum: 2592000,
+        default: 86400
+      },
+      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')",
+        default: "GMT"
+      },
+      // 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(true)
+      },
+      useSandbox: {
+        type: "boolean",
+        description: "Use sandbox environment",
+        default: true
+      }
+    },
+    required: ["name"]
+  },
+
+  async handler(args) {
+    const {
+      name,
+      shortDescription,
+      longDescription,
+      sku,
+      upc,
+      shippable = "FALSE",
+      active = "FALSE",
+      shop,
+      productType = PRODUCT_TYPES.ITEM,
+      regularPrice = "0.00",
+      currency = "EUR",
+      overlapPriority = OVERLAP_PRIORITY.LOWEST,
+      timeToLive = 86400,
+      activeFrom,
+      activeTo,
+      timeZone = "GMT",
+      imageUrl,
+      termsUrl,
+      termsText,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe(args.useSandbox ?? true),
+      useSandbox = true
+    } = args;
+
+    if (!name) {
+      throw new Error("Product name 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
+    const prData = {
+      type: productType,
+      regularPrice,
+      currency,
+      overlapPriority,
+      timeToLive,
+      timeZone
+    };
+
+    if (activeFrom) prData.activeFrom = activeFrom;
+    if (activeTo) prData.activeTo = activeTo;
+
+    // Build prOptions object
+    const prOptions = {};
+    if (imageUrl) prOptions.imageUrl = imageUrl;
+    if (termsUrl) prOptions.termsUrl = termsUrl;
+    if (termsText) prOptions.termsText = termsText;
+
+    try {
+      const result = await createProduct({
+        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 Created Successfully**
+
+**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:**
+1. Save the product ID: \`${product.productId}\`
+2. Use \`payware_products_get_product\` to view product details
+3. Use \`payware_products_create_schedule\` to add price schedules
+4. Use \`payware_products_register_audio\` to add soundbites`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Product Creation Failed**
+
+**Error Details:**
+- Message: ${error.message}
+
+**Troubleshooting:**
+1. Verify JWT token is valid and not expired
+2. Check product parameters (name, price format, dates)
+3. Ensure private key matches public key registered with payware
+4. Verify partner ID and API access
+5. Check sandbox API status`
+        }]
+      };
+    }
+  }
+};

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

@@ -0,0 +1,111 @@
+import { deleteProduct } from '../../shared/products/products-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Delete product tool implementation for merchants
+ */
+export const deleteProductTool = {
+  name: "payware_products_delete_product",
+  description: "Delete a product from the merchant account. This action cannot be undone.",
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      productId: {
+        type: "string",
+        description: "Product identifier to delete (starts with 'pr')",
+        pattern: "^pr[a-zA-Z0-9]+$"
+      },
+      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,
+      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.");
+    }
+
+    try {
+      const result = await deleteProduct({
+        productId,
+        partnerType: 'merchant',
+        partnerId,
+        privateKey,
+        useSandbox
+      });
+
+      return {
+        content: [{
+          type: "text",
+          text: `🗑️ **Product Deleted Successfully**
+
+**Deleted Product:**
+- ID: ${productId}
+- Status: Successfully removed from account
+
+**API Call Details:**
+- Endpoint: ${result.requestInfo.method} ${result.requestInfo.url}
+- Status: ${result.requestInfo.statusCode}
+
+**Important Notes:**
+⚠️ This action cannot be undone
+⚠️ Any associated price schedules and audios have also been deleted
+⚠️ Active transactions using this product may be affected
+
+**Next Steps:**
+- Use \`payware_products_list_products\` to view remaining products
+- Create new products with \`payware_products_create_product\`
+- Check active transactions that may have used this product`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Product Deletion Failed**
+
+**Error Details:**
+- Message: ${error.message}
+- Product ID: ${productId}
+
+**Troubleshooting:**
+1. Verify the product ID is correct and exists
+2. Ensure the product belongs to your account
+3. Check if the product is currently in use by active transactions
+4. Verify JWT token is valid and not expired
+5. Ensure proper API access permissions`
+        }]
+      };
+    }
+  }
+};

package/src/merchant/products/get-product-image.js

@@ -0,0 +1,252 @@
+import { getProductImage } from '../../shared/products/products-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { IMAGE_TYPES, IMAGE_FORMATS, QR_ERROR_CORRECTION, BARCODE_LOCATIONS } from '../../shared/products/products-api.js';
+
+/**
+ * Get product image tool implementation for merchants
+ */
+export const getProductImageTool = {
+  name: "payware_products_get_product_image",
+  description: `Generate a QR code or barcode image for a product.
+
+**QR Code Options:** Format, border, error correction, scale, version
+**Barcode Options:** Format, module width, bar height, font size, text location`,
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      productId: {
+        type: "string",
+        description: "Product identifier (starts with 'pr')",
+        pattern: "^pr[a-zA-Z0-9]+$"
+      },
+      type: {
+        type: "string",
+        enum: Object.values(IMAGE_TYPES),
+        description: "Type of image to generate",
+        default: IMAGE_TYPES.QR
+      },
+      // QR Code Options
+      qrFormat: {
+        type: "string",
+        enum: Object.values(IMAGE_FORMATS),
+        description: "QR code image format (applies when type=QR)",
+        default: IMAGE_FORMATS.SVG
+      },
+      qrBorder: {
+        type: "number",
+        minimum: 1,
+        maximum: 10,
+        description: "QR code border size in modules (applies when type=QR)",
+        default: 4
+      },
+      qrErrorCorrection: {
+        type: "string",
+        enum: Object.values(QR_ERROR_CORRECTION),
+        description: "QR code error correction level (applies when type=QR)",
+        default: QR_ERROR_CORRECTION.QUARTILE
+      },
+      qrScale: {
+        type: "number",
+        minimum: 1,
+        maximum: 100,
+        description: "QR code module size in pixels, irrelevant for SVG (applies when type=QR)",
+        default: 16
+      },
+      qrVersion: {
+        type: "number",
+        minimum: 1,
+        maximum: 40,
+        description: "QR code version, higher versions store more data (applies when type=QR)",
+        default: 10
+      },
+      // Barcode Options
+      barFormat: {
+        type: "string",
+        enum: Object.values(IMAGE_FORMATS),
+        description: "Barcode image format (applies when type=BARCODE)",
+        default: IMAGE_FORMATS.SVG
+      },
+      barModuleWidth: {
+        type: "number",
+        minimum: 1,
+        maximum: 10,
+        description: "Barcode module width in pixels (applies when type=BARCODE)",
+        default: 2
+      },
+      barBarHeight: {
+        type: "number",
+        minimum: 15,
+        maximum: 1000,
+        description: "Barcode height in pixels (applies when type=BARCODE)",
+        default: 100
+      },
+      barFontSize: {
+        type: "number",
+        minimum: 0,
+        maximum: 24,
+        description: "Barcode font size in pixels (applies when type=BARCODE)",
+        default: 12
+      },
+      barHumanReadableLocation: {
+        type: "string",
+        enum: Object.values(BARCODE_LOCATIONS),
+        description: "Barcode text position (applies when type=BARCODE)",
+        default: BARCODE_LOCATIONS.NONE
+      },
+      // 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,
+      type = IMAGE_TYPES.QR,
+      qrFormat = IMAGE_FORMATS.SVG,
+      qrBorder = 4,
+      qrErrorCorrection = QR_ERROR_CORRECTION.QUARTILE,
+      qrScale = 16,
+      qrVersion = 10,
+      barFormat = IMAGE_FORMATS.SVG,
+      barModuleWidth = 2,
+      barBarHeight = 100,
+      barFontSize = 12,
+      barHumanReadableLocation = BARCODE_LOCATIONS.NONE,
+      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 options based on type
+    const qrOptions = type === IMAGE_TYPES.QR ? {
+      qrFormat,
+      qrBorder,
+      qrErrorCorrection,
+      qrScale,
+      qrVersion
+    } : {};
+
+    const barOptions = type === IMAGE_TYPES.BARCODE ? {
+      barFormat,
+      barModuleWidth,
+      barBarHeight,
+      barFontSize,
+      barHumanReadableLocation
+    } : {};
+
+    try {
+      const result = await getProductImage({
+        productId,
+        type,
+        qrOptions,
+        barOptions,
+        partnerType: 'merchant',
+        partnerId,
+        privateKey,
+        useSandbox
+      });
+
+      const imageData = result.data;
+      const format = imageData.format;
+      const imageType = imageData.type;
+
+      // Truncate image data for display (show first 100 chars + length info)
+      const truncatedData = imageData.imageData.length > 100
+        ? `${imageData.imageData.substring(0, 100)}... (${imageData.imageData.length} total characters)`
+        : imageData.imageData;
+
+      return {
+        content: [{
+          type: "text",
+          text: `🖼️ **Product Image Generated Successfully**
+
+**Image Details:**
+- Product ID: ${imageData.id}
+- Type: ${imageType}
+- Format: ${format}
+- Data Length: ${imageData.imageData.length} characters
+
+**Configuration Used:**
+${type === IMAGE_TYPES.QR ? `**QR Code Settings:**
+- Format: ${qrFormat}
+- Border: ${qrBorder} modules
+- Error Correction: ${qrErrorCorrection}
+- Scale: ${qrScale}px per module
+- Version: ${qrVersion}` : ''}
+${type === IMAGE_TYPES.BARCODE ? `**Barcode Settings:**
+- Format: ${barFormat}
+- Module Width: ${barModuleWidth}px
+- Height: ${barBarHeight}px
+- Font Size: ${barFontSize}px
+- Text Location: ${barHumanReadableLocation}` : ''}
+
+**Image Data (Base64):**
+\`\`\`
+${truncatedData}
+\`\`\`
+
+**API Response:**
+\`\`\`json
+${JSON.stringify(imageData, null, 2)}
+\`\`\`
+
+**API Call Details:**
+- Endpoint: ${result.requestInfo.method} ${result.requestInfo.url}
+- Status: ${result.requestInfo.statusCode}
+
+**Usage Notes:**
+- For ${format === 'SVG' ? 'SVG' : 'raster'} images, decode the base64 data and save as .${format.toLowerCase()} file
+- QR codes can be scanned by payment apps to initiate transactions
+- Barcodes can be used for inventory and payment processing systems`
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: "text",
+          text: `❌ **Image Generation Failed**
+
+**Error Details:**
+- Message: ${error.message}
+- Product ID: ${productId}
+- Image Type: ${type}
+
+**Troubleshooting:**
+1. Verify the product ID is correct and exists
+2. Check image generation parameters (format, dimensions)
+3. Ensure the product belongs to your account
+4. Verify JWT token is valid and not expired
+5. Try different image settings if generation fails`
+        }]
+      };
+    }
+  }
+};