@payware/mcp-server 1.2.0 → 1.3.0

package/src/shared/logs/logs-api.js

@@ -0,0 +1,242 @@
+import axios from 'axios';
+import { createJWTToken } from '../../core/auth/jwt-token.js';
+import { createJWTForPartner } from '../../core/auth/jwt-factory.js';
+import { getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+import { describeApiError } from '../api-errors.js';
+
+/**
+ * Logs API - Premium Feature
+ * Provides access to application logs for debugging and monitoring.
+ * Requires Premium (PRM) plan subscription.
+ */
+
+/**
+ * Available log levels for filtering
+ */
+export const LOG_LEVELS = {
+  ERROR: 'ERROR',
+  WARN: 'WARN',
+  INFO: 'INFO',
+  DEBUG: 'DEBUG'
+};
+
+/**
+ * Create authentication headers for logs API
+ * @param {string} partnerType - merchant, isv, or payment_institution
+ * @param {Object} authParams - Authentication parameters
+ * @returns {Object} Headers for API request
+ */
+async function createAuthHeaders(partnerType, authParams) {
+  const baseHeaders = {
+    'Content-Type': 'application/json',
+    'Api-Version': '1'
+  };
+
+  let tokenData;
+
+  switch (partnerType) {
+    case 'merchant':
+    case 'payment_institution':
+      // Standard JWT authentication
+      tokenData = createJWTToken(
+        authParams.partnerId,
+        authParams.privateKey,
+        authParams.requestBody
+      );
+      break;
+
+    case 'isv':
+      // ISV JWT with OAuth2
+      tokenData = await createJWTForPartner({
+        partnerId: authParams.isvPartnerId,
+        privateKey: authParams.privateKey,
+        merchantId: authParams.merchantPartnerId,
+        oauth2Token: authParams.oauth2Token,
+        requestBody: authParams.requestBody
+      });
+      break;
+
+    default:
+      throw new Error(`Unknown partner type: ${partnerType}`);
+  }
+
+  return {
+    ...baseHeaders,
+    'Authorization': `Bearer ${tokenData.token}`
+  };
+}
+
+/**
+ * Handle 403 errors with Premium plan messaging
+ */
+function handleLogsError(error, operation) {
+  if (error.response?.status === 403) {
+    throw new Error(
+      `Access denied: Logs API requires Premium (PRM) plan. ` +
+      `Please upgrade your subscription to access application logs. ` +
+      `Original error: ${error.response?.data?.message || 'Forbidden'}`
+    );
+  }
+  throw describeApiError(error, '${operation}');
+}
+
+/**
+ * Query logs with filters
+ * @param {Object} params - Query parameters
+ * @returns {Promise<Object>} Log query response
+ */
+export async function queryLogs({
+  from,
+  to,
+  level,
+  logger,
+  search,
+  limit = 1000,
+  cursor,
+  partnerType,
+  ...authParams
+}) {
+  const headers = await createAuthHeaders(partnerType, authParams);
+
+  // Build query parameters
+  const queryParams = new URLSearchParams();
+  if (from) queryParams.append('from', from);
+  if (to) queryParams.append('to', to);
+  if (level) queryParams.append('level', level);
+  if (logger) queryParams.append('logger', logger);
+  if (search) queryParams.append('search', search);
+  if (limit) queryParams.append('limit', limit.toString());
+  if (cursor) queryParams.append('cursor', cursor);
+
+  const queryString = queryParams.toString();
+  const url = `${getProductionUrl()}/logs${queryString ? '?' + queryString : ''}`;
+
+  try {
+    const response = await axios.get(url, { headers });
+
+    return {
+      success: true,
+      data: response.data,
+      requestInfo: {
+        url,
+        method: 'GET',
+        statusCode: response.status
+      }
+    };
+  } catch (error) {
+    handleLogsError(error, 'query logs');
+  }
+}
+
+/**
+ * Get log status (availability and storage info)
+ * @param {Object} params - Authentication parameters
+ * @returns {Promise<Object>} Log status response
+ */
+export async function getLogStatus({
+  partnerType,
+  ...authParams
+}) {
+  const headers = await createAuthHeaders(partnerType, authParams);
+
+  try {
+    const response = await axios.get(
+      `${getProductionUrl()}/logs/status`,
+      { headers }
+    );
+
+    return {
+      success: true,
+      data: response.data,
+      requestInfo: {
+        url: `${getProductionUrl()}/logs/status`,
+        method: 'GET',
+        statusCode: response.status
+      }
+    };
+  } catch (error) {
+    handleLogsError(error, 'get log status');
+  }
+}
+
+/**
+ * Get download URL for logs archive
+ * @param {Object} params - Query parameters for date range
+ * @returns {Promise<Object>} Download URL information
+ */
+export async function getLogDownloadUrl({
+  from,
+  to,
+  partnerType,
+  ...authParams
+}) {
+  // Build query parameters for the download URL
+  const queryParams = new URLSearchParams();
+  if (from) queryParams.append('from', from);
+  if (to) queryParams.append('to', to);
+
+  const queryString = queryParams.toString();
+  const downloadUrl = `${getProductionUrl()}/logs/download${queryString ? '?' + queryString : ''}`;
+
+  // Note: The actual download requires authentication headers
+  // This returns the URL structure that would be used
+  return {
+    success: true,
+    data: {
+      downloadUrl,
+      note: 'Use this URL with proper JWT authentication headers to download logs as gzipped JSON',
+      parameters: {
+        from: from || 'default (24 hours ago)',
+        to: to || 'default (now)'
+      }
+    },
+    requestInfo: {
+      url: downloadUrl,
+      method: 'GET (with auth headers)'
+    }
+  };
+}
+
+/**
+ * Download logs as compressed archive
+ * @param {Object} params - Query parameters for date range
+ * @returns {Promise<Object>} Downloaded log data
+ */
+export async function downloadLogs({
+  from,
+  to,
+  partnerType,
+  ...authParams
+}) {
+  const headers = await createAuthHeaders(partnerType, authParams);
+
+  // Build query parameters
+  const queryParams = new URLSearchParams();
+  if (from) queryParams.append('from', from);
+  if (to) queryParams.append('to', to);
+
+  const queryString = queryParams.toString();
+  const url = `${getProductionUrl()}/logs/download${queryString ? '?' + queryString : ''}`;
+
+  try {
+    const response = await axios.get(url, {
+      headers,
+      responseType: 'arraybuffer'
+    });
+
+    return {
+      success: true,
+      data: response.data,
+      contentType: response.headers['content-type'],
+      contentDisposition: response.headers['content-disposition'],
+      contentLength: response.headers['content-length'],
+      requestInfo: {
+        url,
+        method: 'GET',
+        statusCode: response.status
+      }
+    };
+  } catch (error) {
+    handleLogsError(error, 'download logs');
+  }
+}

package/src/shared/poi/poi-create-api.js

@@ -0,0 +1,419 @@
+import axios from 'axios';
+import { createAuthHeaders } from '../auth-headers.js';
+import { apiErrorResult } from '../api-errors.js';
+import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
+import { getSandboxUrl, getProductionUrl } from '../../config/env.js';
+
+/**
+ * Creating POIs (Points of Interaction) - the physical payment points a payer scans.
+ *
+ * The existing POI tools could list, read, price and un-price a POI but not create one, so a fleet
+ * had to be built by hand in the portal before any of them were usable. `POST /poi` and
+ * `POST /poi/batch` close that: batch is the one a terminal rollout actually needs, since it creates
+ * up to 50 in a single atomic call.
+ */
+
+/** The server's cap, from POIService.MAX_BATCH_SIZE. Exceeding it is ERR_BATCH_TOO_LARGE. */
+export const MAX_POI_BATCH_SIZE = 50;
+
+/** TTL bounds the server validates on both create paths. */
+export const POI_TTL_MIN_SECONDS = 60;
+export const POI_TTL_MAX_SECONDS = 600;
+
+function validateTtl(ttlSeconds, label = 'ttlSeconds') {
+  if (ttlSeconds === undefined || ttlSeconds === null) return;
+  if (!Number.isInteger(ttlSeconds) || ttlSeconds < POI_TTL_MIN_SECONDS || ttlSeconds > POI_TTL_MAX_SECONDS) {
+    throw new Error(
+      `${label} must be a whole number of seconds between ${POI_TTL_MIN_SECONDS} and ${POI_TTL_MAX_SECONDS}`
+    );
+  }
+}
+
+/**
+ * Create a single POI.
+ *
+ * @param {Object} params
+ * @param {string} params.partnerType  'merchant' | 'isv'
+ * @param {string} params.shopCode     required - the outlet this POI belongs to
+ * @param {string} [params.name]       max 100 chars
+ * @param {number} [params.ttlSeconds] 60-600, server default 300
+ * @param {string} [params.callbackUrl]
+ */
+export async function createPOI({
+  partnerType,
+  shopCode,
+  name,
+  ttlSeconds,
+  callbackUrl,
+  useSandbox = true,
+  ...authParams
+}) {
+  if (!shopCode) {
+    throw new Error('shopCode is required - use payware_shops_list to find a valid one');
+  }
+  if (name !== undefined && String(name).length > 100) {
+    throw new Error('POI name must not exceed 100 characters');
+  }
+  validateTtl(ttlSeconds);
+
+  const requestBody = {
+    shopCode,
+    ...(name && { name }),
+    ...(ttlSeconds !== undefined && ttlSeconds !== null && { ttlSeconds }),
+    ...(callbackUrl && { callbackUrl })
+  };
+
+  const minimizedBody = createMinimizedJSON(requestBody);
+  const headers = await createAuthHeaders(partnerType, { ...authParams, requestBody: minimizedBody });
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.post(`${baseUrl}/poi`, minimizedBody, {
+      headers,
+      transformRequest: [(data) => data]
+    });
+
+    return {
+      success: true,
+      poi: response.data,
+      requestId: response.headers['x-request-id'],
+      timestamp: new Date().toISOString()
+    };
+  } catch (error) {
+    return apiErrorResult(error);
+  }
+}
+
+/**
+ * Create up to 50 POIs in one atomic call.
+ *
+ * `shopCode`, `ttlSeconds` and `callbackUrl` set at the top level are the defaults for every entry;
+ * an entry may override `name`, `ttlSeconds` and `callbackUrl` for itself.
+ */
+export async function createPOIBatch({
+  partnerType,
+  shopCode,
+  pois,
+  ttlSeconds,
+  callbackUrl,
+  useSandbox = true,
+  ...authParams
+}) {
+  if (!shopCode) {
+    throw new Error('shopCode is required - use payware_shops_list to find a valid one');
+  }
+  if (!Array.isArray(pois) || pois.length === 0) {
+    // Matches the server's ERR_BATCH_EMPTY, refused here so the round trip is not wasted.
+    throw new Error('pois must be a non-empty array (server: ERR_BATCH_EMPTY)');
+  }
+  if (pois.length > MAX_POI_BATCH_SIZE) {
+    throw new Error(
+      `pois must contain at most ${MAX_POI_BATCH_SIZE} entries (server: ERR_BATCH_TOO_LARGE). ` +
+      `Received ${pois.length} - split the rollout into batches of ${MAX_POI_BATCH_SIZE}.`
+    );
+  }
+  validateTtl(ttlSeconds);
+  pois.forEach((poi, i) => {
+    if (poi?.name !== undefined && String(poi.name).length > 100) {
+      throw new Error(`pois[${i}].name must not exceed 100 characters`);
+    }
+    validateTtl(poi?.ttlSeconds, `pois[${i}].ttlSeconds`);
+  });
+
+  const requestBody = {
+    shopCode,
+    ...(ttlSeconds !== undefined && ttlSeconds !== null && { ttlSeconds }),
+    ...(callbackUrl && { callbackUrl }),
+    pois: pois.map(poi => ({
+      ...(poi.name && { name: poi.name }),
+      ...(poi.ttlSeconds !== undefined && poi.ttlSeconds !== null && { ttlSeconds: poi.ttlSeconds }),
+      ...(poi.callbackUrl && { callbackUrl: poi.callbackUrl })
+    }))
+  };
+
+  const minimizedBody = createMinimizedJSON(requestBody);
+  const headers = await createAuthHeaders(partnerType, { ...authParams, requestBody: minimizedBody });
+
+  try {
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
+    const response = await axios.post(`${baseUrl}/poi/batch`, minimizedBody, {
+      headers,
+      transformRequest: [(data) => data]
+    });
+
+    return {
+      success: true,
+      created: response.data?.created ?? 0,
+      pois: response.data?.pois ?? [],
+      requestId: response.headers['x-request-id'],
+      timestamp: new Date().toISOString()
+    };
+  } catch (error) {
+    return apiErrorResult(error);
+  }
+}
+
+const SHARED_POI_NOTES = `
+**A POI belongs to a shop, and a shop belongs to a merchant.** \`shopCode\` is required - use
+\`payware_shops_list\` to find one rather than guessing. Banks do not own POIs; a financial-institution
+principal gets 403 on every POI endpoint, not an empty result.
+
+**\`ttlSeconds\` is the price-session TTL, not the POI's lifetime.** It bounds how long a price set on
+this POI stays claimable before the POI returns to IDLE. Range ${POI_TTL_MIN_SECONDS}-${POI_TTL_MAX_SECONDS} seconds; the server
+defaults it to 300.`;
+
+function errorText(title, result) {
+  return `❌ **${title}**
+
+- Message: ${result.error.message}
+- Status: ${result.error.status || 'N/A'}
+- Code: ${result.error.errorCode || 'N/A'}
+${result.error.correlationId ? `- Correlation ID: ${result.error.correlationId}` : ''}
+${result.error.guidance ? `\n${result.error.guidance}` : ''}
+
+**Timestamp:** ${result.timestamp}`;
+}
+
+function isvAuthProperties() {
+  return {
+    merchantPartnerId: {
+      type: 'string',
+      description: 'Partner ID of the target merchant (8 alphanumeric characters)'
+    },
+    oauth2Token: {
+      type: 'string',
+      description: 'OAuth2 access token obtained from the merchant'
+    }
+  };
+}
+
+function merchantAuthProperties() {
+  return {
+    partnerId: {
+      type: 'string',
+      description: 'Partner ID from the payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.'
+    },
+    privateKey: {
+      type: 'string',
+      description: 'RSA private key for JWT signing. Uses the environment-specific key as default.'
+    }
+  };
+}
+
+/** Build the single-POI create tool for a role. */
+export function buildCreatePOITool({ partnerType, resolveAuth }) {
+  const isIsv = partnerType === 'isv';
+
+  return {
+    name: 'payware_poi_create',
+    description: `Create a single POI (Point of Interaction) - a physical payment point a payer scans.
+
+**Endpoint:** POST /poi -> 201 Created
+${SHARED_POI_NOTES}
+
+**Creating many at once?** Use \`payware_poi_create_batch\` instead. It creates up to ${MAX_POI_BATCH_SIZE} in one
+atomic call, which is both faster and safer than a loop over this tool: a loop that fails halfway
+leaves a half-built estate with no record of where it stopped.
+${isIsv ? `
+⚠️ **ISV scope and plan.** The shop must be in the scope this merchant assigned you, or the call is
+**403 \`ERR_SHOP_NOT_IN_SCOPE\`**. The acting merchant's plan governs, not yours.
+` : ''}`,
+
+    inputSchema: {
+      type: 'object',
+      required: isIsv ? ['merchantPartnerId', 'oauth2Token', 'shopCode'] : ['shopCode'],
+      properties: {
+        ...(isIsv ? isvAuthProperties() : merchantAuthProperties()),
+        shopCode: {
+          type: 'string',
+          description: 'Code of the shop this POI belongs to. Required. Find one with payware_shops_list.'
+        },
+        name: {
+          type: 'string',
+          description: 'Human-readable POI name, e.g. "Till 3" or "Gate B". Shown in the portal and in POI listings.',
+          maxLength: 100
+        },
+        ttlSeconds: {
+          type: 'integer',
+          description: `Price-session TTL in seconds - how long a price set on this POI stays claimable before it returns to IDLE. Server default 300.`,
+          minimum: POI_TTL_MIN_SECONDS,
+          maximum: POI_TTL_MAX_SECONDS
+        },
+        callbackUrl: {
+          type: 'string',
+          description: 'HTTPS URL for POI events. Must present a publicly-trusted TLS certificate and resolve to a public address.',
+          format: 'uri'
+        },
+        useSandbox: {
+          type: 'boolean',
+          description: 'Use sandbox environment for testing',
+          default: true
+        }
+      }
+    },
+
+    async handler(args) {
+      const { shopCode, name, ttlSeconds, callbackUrl, useSandbox = true } = args;
+      const result = await createPOI({
+        partnerType,
+        shopCode,
+        name,
+        ttlSeconds,
+        callbackUrl,
+        useSandbox,
+        ...resolveAuth(args)
+      });
+
+      if (!result.success) {
+        return { content: [{ type: 'text', text: errorText('Failed to Create POI', result) }] };
+      }
+
+      const poi = result.poi || {};
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ **POI Created**
+
+- POI ID: \`${poi.poiId}\`
+- Name: ${poi.name || '(unnamed)'}
+- Shop: ${poi.shopName || poi.shopCode || shopCode}
+- Status: ${poi.status || 'IDLE'}
+
+**Next:** set a price with \`payware_poi_set_price\`, or fetch its QR code with
+\`payware_poi_get_qrcode\` to print and mount at the payment point.
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  };
+}
+
+/** Build the batch-create tool for a role. */
+export function buildCreatePOIBatchTool({ partnerType, resolveAuth }) {
+  const isIsv = partnerType === 'isv';
+
+  return {
+    name: 'payware_poi_create_batch',
+    description: `Create up to ${MAX_POI_BATCH_SIZE} POIs in a single **atomic** call - the tool for rolling out a terminal estate.
+
+**Endpoint:** POST /poi/batch -> 201 Created, returning \`{ created, pois: [...] }\`
+
+**Atomic means all or nothing.** Either every entry is created or none is. That is the reason to
+prefer this over a loop of \`payware_poi_create\`: a loop that fails on entry 27 leaves 26 POIs behind
+with nothing recording where it stopped, and re-running it duplicates them.
+${SHARED_POI_NOTES}
+
+**Defaults and overrides.** \`shopCode\`, \`ttlSeconds\` and \`callbackUrl\` at the top level apply to
+every entry. An entry may override \`name\`, \`ttlSeconds\` and \`callbackUrl\` for itself. \`shopCode\` is
+top-level only - one batch builds one shop.
+
+**Limits:** 1 to ${MAX_POI_BATCH_SIZE} entries. An empty list is \`ERR_BATCH_EMPTY\`; more than ${MAX_POI_BATCH_SIZE} is
+\`ERR_BATCH_TOO_LARGE\`. Both are refused locally before the request is sent. For a larger rollout,
+split it into batches of ${MAX_POI_BATCH_SIZE} - each batch is atomic on its own, so record which batches succeeded.
+${isIsv ? `
+⚠️ **ISV scope and plan.** The shop must be in the scope this merchant assigned you, or the whole
+batch is **403 \`ERR_SHOP_NOT_IN_SCOPE\`**. The acting merchant's plan governs, not yours.
+` : ''}`,
+
+    inputSchema: {
+      type: 'object',
+      required: isIsv ? ['merchantPartnerId', 'oauth2Token', 'shopCode', 'pois'] : ['shopCode', 'pois'],
+      properties: {
+        ...(isIsv ? isvAuthProperties() : merchantAuthProperties()),
+        shopCode: {
+          type: 'string',
+          description: 'Code of the shop every POI in this batch belongs to. Required, top-level only. Find one with payware_shops_list.'
+        },
+        pois: {
+          type: 'array',
+          description: `The POIs to create. Each entry may set name, ttlSeconds and callbackUrl; anything omitted falls back to the top-level value. An entry may be an empty object, which creates an unnamed POI with the batch defaults.`,
+          minItems: 1,
+          maxItems: MAX_POI_BATCH_SIZE,
+          items: {
+            type: 'object',
+            properties: {
+              name: {
+                type: 'string',
+                description: 'Human-readable POI name, e.g. "Till 3".',
+                maxLength: 100
+              },
+              ttlSeconds: {
+                type: 'integer',
+                description: 'Overrides the batch ttlSeconds for this POI.',
+                minimum: POI_TTL_MIN_SECONDS,
+                maximum: POI_TTL_MAX_SECONDS
+              },
+              callbackUrl: {
+                type: 'string',
+                description: 'Overrides the batch callbackUrl for this POI.',
+                format: 'uri'
+              }
+            }
+          }
+        },
+        ttlSeconds: {
+          type: 'integer',
+          description: 'Default price-session TTL for every POI in the batch. Server default 300.',
+          minimum: POI_TTL_MIN_SECONDS,
+          maximum: POI_TTL_MAX_SECONDS
+        },
+        callbackUrl: {
+          type: 'string',
+          description: 'Default HTTPS callback URL for every POI in the batch.',
+          format: 'uri'
+        },
+        useSandbox: {
+          type: 'boolean',
+          description: 'Use sandbox environment for testing',
+          default: true
+        }
+      }
+    },
+
+    async handler(args) {
+      const { shopCode, pois, ttlSeconds, callbackUrl, useSandbox = true } = args;
+      const result = await createPOIBatch({
+        partnerType,
+        shopCode,
+        pois,
+        ttlSeconds,
+        callbackUrl,
+        useSandbox,
+        ...resolveAuth(args)
+      });
+
+      if (!result.success) {
+        return {
+          content: [{
+            type: 'text',
+            text: `${errorText('Failed to Create POI Batch', result)}
+
+**Nothing was created.** The call is atomic, so a failure leaves no partial estate behind - fix the
+cause and re-send the same batch.`
+          }]
+        };
+      }
+
+      const created = result.pois.map(poi =>
+        `- \`${poi.poiId}\` ${poi.name || '(unnamed)'} - ${poi.status || 'IDLE'}`
+      ).join('\n');
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ **POI Batch Created** - ${result.created} POI(s) in shop \`${shopCode}\`
+
+${created}
+
+**Next:** fetch each QR code with \`payware_poi_get_qrcode\` to print and mount, then set prices with
+\`payware_poi_set_price\` as sales happen.
+
+**Request ID:** ${result.requestId || 'N/A'}
+**Timestamp:** ${result.timestamp}`
+        }]
+      };
+    }
+  };
+}