maib-mia-sdk 1.0.0

package/src/MaibMiaSdk.js

@@ -0,0 +1,219 @@
+/**
+ * Node.js SDK for maib MIA API
+ * Main Class
+ */
+
+const { name: packageName, version: packageVersion } = require('../package.json');
+
+const crypto = require('crypto');
+const axios = require('axios');
+
+const { SANDBOX_BASE_URL, DEFAULT_BASE_URL, DEFAULT_TIMEOUT } = require('./constants');
+const { MaibMiaApiError, MaibMiaValidationError } = require('./errors');
+
+class MaibMiaSdk {
+    /**
+     * Create a new MaibMiaSdk instance
+     * @param {string} baseUrl - maib MIA API base url
+     * @param {number} timeout - API request timeout in milliseconds
+     */
+    constructor(baseUrl = DEFAULT_BASE_URL, timeout = DEFAULT_TIMEOUT) {
+        this.baseUrl = baseUrl;
+        this.timeout = timeout;
+
+        this.client = axios.create({
+            baseURL: baseUrl,
+            timeout: timeout,
+            headers: {
+                'User-Agent': `${packageName}-node/${packageVersion}`
+            }
+        });
+    }
+
+    setupLogging() {
+        this.client.interceptors.request.use(
+            (config) => {
+                const logData = MaibMiaSdk._getLogData(config, config);
+                console.debug(`${packageName} Request: ${logData.method} ${logData.url}`, logData);
+                return config;
+            },
+            (error) => {
+                console.error(`${packageName} Request: ${error.message}`, error);
+                return Promise.reject(error);
+            }
+        );
+
+        this.client.interceptors.response.use(
+            (response) => {
+                const logData = MaibMiaSdk._getLogData(response, response?.config);
+                console.debug(`${packageName} Response: ${logData.status} ${logData.method} ${logData.url}`, logData);
+                return response;
+            },
+            (error) => {
+                const config = error.response?.config || error.config;
+                const logData = MaibMiaSdk._getLogData(error.response, config);
+                console.error(`${packageName} Error: ${logData.status ?? ''} ${logData.data ?? ''}`, logData, error);
+                return Promise.reject(error);
+            }
+        );
+    }
+
+    static _getLogData(object, config) {
+        const logData = {
+            'method': config?.method?.toUpperCase(),
+            'url': config ? axios.getUri(config) : undefined,
+            'data': object?.data,
+            'params': config?.params,
+            // 'headers': object?.headers?.toJSON?.() || config?.headers?.toJSON?.(),
+            'status': object?.status
+        }
+
+        return logData;
+    }
+
+    /**
+     * Sandbox base URL
+     */
+    static get SANDBOX_BASE_URL() {
+        return SANDBOX_BASE_URL;
+    }
+
+    /**
+     * Production base URL
+     */
+    static get DEFAULT_BASE_URL() {
+        return DEFAULT_BASE_URL;
+    }
+
+    /**
+     * Default API request timeout in milliseconds
+     */
+    static get DEFAULT_TIMEOUT() {
+        return DEFAULT_TIMEOUT;
+    }
+
+    /**
+     * Perform API request
+     * @param {string} method - Request HTTP method
+     * @param {string} url - Request URL
+     * @param {Object} data - Request data
+     * @param {Object} params - Request params
+     * @param {string} token - Access token
+     * @returns {Promise<Object>} API request response
+     */
+    async _sendRequest(method, url, data = null, params = null, token = null) {
+        const requestConfig = {
+            url: url,
+            method: method,
+            data: data,
+            headers: {
+                ...this.client.defaults.headers.common,
+                ...MaibMiaSdk._getAuthHeaders(token)
+            },
+            params: params,
+            // https://github.com/axios/axios/issues/41
+            validateStatus: () => true
+        }
+
+        const response = await this.client.request(requestConfig);
+        return MaibMiaSdk._handleResponse(response, url);
+    }
+
+    /**
+     * Set authorization header
+     * @param {string} token - Access token
+     * @returns {Object} - Headers object
+     */
+    static _getAuthHeaders(token) {
+        if (!token) return null;
+
+        return {
+            'Authorization': `Bearer ${token}`
+        };
+    }
+
+    /**
+     * Handles errors returned by the API
+     * @param {axios.AxiosResponse} response - Response object
+     * @param {string} endpoint - API endpoint
+     * @throws {MaibMiaApiError} - When received a server error from the API
+     */
+    static _handleResponse(response, endpoint) {
+        if (!response.data)
+            throw new MaibMiaApiError(`Invalid response received from server for endpoint ${endpoint}`, response);
+
+        if (response.data.ok) {
+            if (response.data.result)
+                return response.data.result;
+
+            throw new MaibMiaApiError(`Invalid response received from server for endpoint ${endpoint}: missing 'result' field`, response);
+        }
+
+        if (response.data.errors && response.data.errors.length > 0) {
+            const errorMessages = response.data.errors.map(error => `${error.errorMessage} (${error.errorCode})`).join('; ');
+            throw new MaibMiaApiError(`Error sending request to endpoint ${endpoint}: ${errorMessages}`, response);
+        }
+
+        throw new MaibMiaApiError(`Invalid response received from server for endpoint ${endpoint}: missing 'ok' and 'errors' fields`, response);
+    }
+
+    /**
+     * Validate callback data signature
+     * @param {Object} callbackData - The callback data received from the payment gateway
+     * @param {string} signatureKey - The signature key for validation
+     * @returns {boolean} - True if signature is valid, false otherwise
+     * @link https://docs.maibmerchants.md/mia-qr-api/en/notifications-on-callback-url
+     * @link https://docs.maibmerchants.md/mia-qr-api/en/examples/signature-key-verification
+     * @link https://docs.maibmerchants.md/request-to-pay/api-reference/callback-notifications#signature-validation
+     * @link https://docs.maibmerchants.md/request-to-pay/api-reference/examples/signature-key-verification
+     * @throws {MaibMiaValidationError} - If Callback data or Signature Key are invalid
+     */
+    static validateCallbackSignature(callbackData, signatureKey) {
+        if (!signatureKey) {
+            throw new MaibMiaValidationError('Invalid signature key');
+        }
+
+        if (!callbackData?.signature || !callbackData?.result) {
+            throw new MaibMiaValidationError('Missing result or signature in callback data');
+        }
+
+        const computedResultSignature = MaibMiaSdk.computeDataSignature(callbackData.result, signatureKey);
+        return crypto.timingSafeEqual(Buffer.from(computedResultSignature), Buffer.from(callbackData.signature));
+    }
+
+    static computeDataSignature(resultData, signatureKey) {
+        const keys = {};
+
+        // Collect and format values
+        for (const [key, value] of Object.entries(resultData)) {
+            if (value === null || value === undefined) continue;
+
+            let valueStr;
+            if (key === 'amount' || key === 'commission') {
+                valueStr = parseFloat(value).toFixed(2); // Always two decimals
+            } else {
+                valueStr = String(value);
+            }
+
+            if (valueStr.trim() !== '') {
+                keys[key] = valueStr;
+            }
+        }
+
+        // Sort keys case-insensitively
+        const orderedKeys = Object.keys(keys).sort((a, b) =>
+            a.toLowerCase().localeCompare(b.toLowerCase())
+        );
+
+        // Join values with colon
+        const additionalString = orderedKeys.map(k => keys[k]).join(':');
+        const hashInput = `${additionalString}:${signatureKey}`;
+
+        // Hash and base64 encode
+        const hash = crypto.createHash('sha256').update(hashInput, 'utf8').digest('base64');
+
+        return hash;
+    }
+}
+
+module.exports = MaibMiaSdk;

package/src/constants.js

@@ -0,0 +1,61 @@
+/**
+ * Node.js SDK for maib MIA API
+ * Constants
+ */
+
+// maib MIA QR API base urls
+// https://docs.maibmerchants.md/mia-qr-api/en/overview/general-technical-specifications#available-base-urls
+// https://docs.maibmerchants.md/request-to-pay/getting-started/api-fundamentals#available-environments
+const DEFAULT_BASE_URL = 'https://api.maibmerchants.md/v2/';
+const SANDBOX_BASE_URL = 'https://sandbox.maibmerchants.md/v2/';
+
+const DEFAULT_TIMEOUT = 30000; // milliseconds
+
+const API_ENDPOINTS = {
+    AUTH_TOKEN: 'auth/token',
+
+    // maib MIA QR API endpoints
+    // https://docs.maibmerchants.md/mia-qr-api/en/endpoints
+    MIA_QR: 'mia/qr',
+    MIA_QR_HYBRID: 'mia/qr/hybrid',
+    MIA_QR_ID: 'mia/qr/:qrId',
+    MIA_QR_EXTENSION: 'mia/qr/:qrId/extension',
+    MIA_QR_CANCEL: 'mia/qr/:qrId/cancel',
+    MIA_QR_EXTENSION_CANCEL: 'mia/qr/:qrId/extension/cancel',
+    MIA_PAYMENTS: 'mia/payments',
+    MIA_PAYMENTS_ID: 'mia/payments/:payId',
+    MIA_PAYMENTS_REFUND: 'mia/payments/:payId/refund',
+    MIA_TEST_PAY: 'mia/test-pay',
+
+    // maib RTP API endpoints
+    // https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints
+    MIA_RTP: 'rtp',
+    MIA_RTP_ID: 'rtp/:rtpId',
+    MIA_RTP_CANCEL: 'rtp/:rtpId/cancel',
+    MIA_RTP_REFUND: 'rtp/:payId/refund',
+    MIA_RTP_TEST_ACCEPT: 'rtp/:rtpId/test-accept',
+    MIA_RTP_TEST_REJECT: 'rtp/:rtpId/test-reject'
+};
+
+const REQUIRED_PARAMS = {
+    // https://docs.maibmerchants.md/mia-qr-api/en/endpoints/payment-initiation/create-qr-code-static-dynamic#request-parameters-body
+    QR_PARAMS: ['type', 'amountType', 'currency', 'description'],
+    // https://docs.maibmerchants.md/mia-qr-api/en/endpoints/payment-initiation/create-hybrid-qr-code#request-body-parameters
+    QR_HYBRID_PARAMS: ['amountType', 'currency'],
+    // https://docs.maibmerchants.md/mia-qr-api/en/endpoints/payment-initiation/create-hybrid-qr-code/create-extension-for-qr-code-by-id#request-parameters-body
+    QR_EXTENSION_PARAMS: ['expiresAt', 'description'],
+    // https://docs.maibmerchants.md/mia-qr-api/en/payment-simulation-sandbox#request-parameters-body-json
+    TEST_PAY_PARAMS: ['qrId', 'amount', 'iban', 'currency', 'payerName'],
+    // https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints/create-a-new-payment-request-rtp#request-body-parameters
+    RTP_PARAMS: ['alias', 'amount', 'currency', 'expiresAt', 'description'],
+    // https://docs.maibmerchants.md/request-to-pay/api-reference/sandbox-simulation-environment/simulate-acceptance-of-a-payment-request#request-body-parameters
+    TEST_ACCEPT_PARAMS: ['amount', 'currency']
+}
+
+module.exports = {
+    DEFAULT_BASE_URL,
+    SANDBOX_BASE_URL,
+    DEFAULT_TIMEOUT,
+    API_ENDPOINTS,
+    REQUIRED_PARAMS
+};

package/src/errors.js

@@ -0,0 +1,32 @@
+/**
+ * Node.js SDK for maib MIA API
+ * Custom Error Classes
+ */
+
+class MaibMiaError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+class MaibMiaApiError extends MaibMiaError {
+    constructor(message, response = null, error = null) {
+        super(message, { cause: error });
+
+        this.response = response;
+    }
+}
+
+class MaibMiaValidationError extends MaibMiaError {
+    constructor(message, error = null) {
+        super(message, { cause: error });
+    }
+}
+
+module.exports = {
+    MaibMiaError,
+    MaibMiaApiError,
+    MaibMiaValidationError,
+};

package/src/index.js

@@ -0,0 +1,21 @@
+/**
+ * Node.js SDK for maib MIA API
+ * Main Entry Point
+ */
+
+const MaibMiaSdk = require('./MaibMiaSdk');
+const MaibMiaAuthRequest = require('./MaibMiaAuthRequest');
+const MaibMiaApiRequest = require('./MaibMiaApiRequest');
+const { MaibMiaError, MaibMiaApiError, MaibMiaValidationError } = require('./errors');
+
+module.exports = {
+    MaibMiaSdk,
+    MaibMiaAuthRequest,
+    MaibMiaApiRequest,
+    MaibMiaError,
+    MaibMiaApiError,
+    MaibMiaValidationError,
+};
+
+// Default export for ES6 imports
+module.exports.default = MaibMiaSdk;