nets-service-sdk 1.0.2 → 1.1.0

package/README.md

@@ -1,6 +1,14 @@
 # NETS Service SDK
 
-A utility library for integrating with NETS payment terminals and handling related operations. This SDK provides tools for serial communication, message parsing, configuration management, and common utility functions.
+A utility library for integrating with NETS payment terminals and handling related operations. This SDK provides tools for serial communication, message parsing, configuration management, transaction storage, and common utility functions.
+
+## Features
+
+- 🔌 Serial communication with NETS payment terminals
+- 💾 SQLite-based transaction storage with automatic purging
+- 📝 Comprehensive logging with Winston
+- 🔧 Configuration management
+- 🛠️ Utility functions for payment processing
 
 ## Installation
 
@@ -53,10 +61,67 @@ communication.sentToTerminal('STATUS_CHECK', {});
 // For Payment
 communication.sentToTerminal('PAYMENT', {
     amount: 1000, // Amount in cents
-    reference: 'ORDER123'
+    reference: 'ORDER123',
+    ecn: '040126003000'
 });
 ```
 
+### Transaction Storage (New in v1.1.0)
+
+All terminal requests and responses are automatically stored in a SQLite database.
+
+```javascript
+const sdk = require('nets-service-sdk');
+
+// Query specific transaction by ECN
+const transaction = sdk.getTransactionByEcn('040126003000');
+console.log(transaction);
+// {
+//   ecn: '040126003000',
+//   request_type: 'PAYMENT',
+//   request_payload: { amount: 10.50, reference: 'ORDER123' },
+//   response_data: { status: 'APPROVED', ... },
+//   status: 'APPROVED',
+//   ...
+// }
+
+// Get recent transactions
+const recent = sdk.getRecentTransactions(50);
+
+// Query by status
+const approved = sdk.getTransactionsByStatus('APPROVED', 100);
+const pending = sdk.getTransactionsByStatus('PENDING', 100);
+
+// Manual cleanup (delete old transactions)
+const deleted = sdk.cleanupOldTransactions(90); // Keep last 90 days
+```
+
+### Automatic Data Purging (New in v1.1.0)
+
+The SDK automatically purges old transaction data weekly.
+
+```javascript
+const sdk = require('nets-service-sdk');
+
+// Auto-purge is enabled by default
+// Default: Every Sunday at 2 AM, keeps last 7 days
+
+// Start with custom settings
+sdk.startAutoPurge(14, '0 3 * * *'); // Keep 14 days, run daily at 3 AM
+
+// Stop auto-purge
+sdk.stopAutoPurge();
+
+// Check if auto-purge is running
+const isRunning = sdk.isAutoPurgeRunning();
+```
+
+**Cron Schedule Examples:**
+- `'0 2 * * 0'` - Every Sunday at 2 AM (default)
+- `'0 3 * * *'` - Every day at 3 AM
+- `'0 */6 * * *'` - Every 6 hours
+- `'0 0 1 * *'` - First day of every month
+
 ### Utility Functions
 
 The SDK exports various utility functions directly.
@@ -96,6 +161,17 @@ myLogger.error('This is an error message');
 -   **sendMessage**: Helper for sending messages (e.g., to socket rooms).
 -   **hexRequest**: Generates HEX requests for the terminal.
 -   **parser**: Parses responses from the terminal.
+-   **Transaction Storage**: SQLite-based storage for request/response tracking.
+-   **Auto-Purge**: Automatic cleanup of old transaction data.
+
+## Database
+
+The SDK creates a `transactions.db` SQLite database in your project root to store all terminal transactions. This provides:
+
+- Complete audit trail of all requests and responses
+- Debugging capabilities with full hex data
+- Transaction reconciliation
+- Automatic weekly cleanup (configurable)
 
 ## License
 

package/dist/index.js

@@ -631,6 +631,303 @@ var require_parser = __commonJS({
   }
 });
 
+// src/db/autoPurge.js
+var require_autoPurge = __commonJS({
+  "src/db/autoPurge.js"(exports2, module2) {
+    var cron = require("node-cron");
+    var logger = require_winston()(module2);
+    var { cleanupOldTransactions } = require_transactionStore();
+    var scheduledTask = null;
+    function startAutoPurge(daysToKeep = 7, cronSchedule = "0 2 * * 0") {
+      if (scheduledTask) {
+        logger.log({
+          level: "warn",
+          message: "Auto-purge already running. Stopping existing task first."
+        });
+        stopAutoPurge();
+      }
+      scheduledTask = cron.schedule(cronSchedule, () => {
+        logger.log({
+          level: "info",
+          message: `Running scheduled transaction cleanup (keeping last ${daysToKeep} days)`
+        });
+        try {
+          const deletedCount = cleanupOldTransactions(daysToKeep);
+          logger.log({
+            level: "info",
+            message: `Auto-purge completed: Deleted ${deletedCount} old transactions`
+          });
+        } catch (error) {
+          logger.log({
+            level: "error",
+            message: `Auto-purge failed: ${error.message}`
+          });
+        }
+      });
+      logger.log({
+        level: "info",
+        message: `Auto-purge scheduled: ${cronSchedule} (keeping last ${daysToKeep} days)`
+      });
+      return scheduledTask;
+    }
+    function stopAutoPurge() {
+      if (scheduledTask) {
+        scheduledTask.stop();
+        scheduledTask = null;
+        logger.log({
+          level: "info",
+          message: "Auto-purge stopped"
+        });
+      }
+    }
+    function isAutoPurgeRunning() {
+      return scheduledTask !== null;
+    }
+    module2.exports = {
+      startAutoPurge,
+      stopAutoPurge,
+      isAutoPurgeRunning
+    };
+  }
+});
+
+// src/db/transactionStore.js
+var require_transactionStore = __commonJS({
+  "src/db/transactionStore.js"(exports2, module2) {
+    var Database = require("better-sqlite3");
+    var path = require("path");
+    var fs = require("fs");
+    var logger = require_winston()(module2);
+    var db = null;
+    function initDatabase(dbPath, autoPurgeConfig = {}) {
+      try {
+        const defaultPath = path.join(__dirname, "../../transactions.db");
+        const finalPath = dbPath || defaultPath;
+        const dir = path.dirname(finalPath);
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
+        }
+        db = new Database(finalPath);
+        db.pragma("journal_mode = WAL");
+        const createTableSQL = `
+      CREATE TABLE IF NOT EXISTS transactions (
+        ecn TEXT PRIMARY KEY,
+        request_type TEXT NOT NULL,
+        request_payload TEXT,
+        request_hex TEXT,
+        request_timestamp INTEGER NOT NULL,
+        response_hex TEXT,
+        response_data TEXT,
+        response_timestamp INTEGER,
+        status TEXT DEFAULT 'PENDING',
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      )
+    `;
+        db.exec(createTableSQL);
+        db.exec("CREATE INDEX IF NOT EXISTS idx_request_timestamp ON transactions(request_timestamp DESC)");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_status ON transactions(status)");
+        logger.log({
+          level: "info",
+          message: `Transaction database initialized at ${finalPath}`
+        });
+        const { enabled = true, daysToKeep = 7, schedule = "0 2 * * 0" } = autoPurgeConfig;
+        if (enabled) {
+          const autoPurge = require_autoPurge();
+          autoPurge.startAutoPurge(daysToKeep, schedule);
+        }
+        return db;
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to initialize database: ${error.message}`
+        });
+        throw error;
+      }
+    }
+    function getDatabase() {
+      if (!db) {
+        initDatabase();
+      }
+      return db;
+    }
+    function createTransaction(data) {
+      try {
+        const database = getDatabase();
+        const now = Date.now();
+        const stmt = database.prepare(`
+      INSERT INTO transactions (
+        ecn, request_type, request_payload, request_hex, 
+        request_timestamp, status, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const result = stmt.run(
+          data.ecn,
+          data.requestType,
+          JSON.stringify(data.requestPayload || {}),
+          data.requestHex,
+          now,
+          "PENDING",
+          now,
+          now
+        );
+        logger.log({
+          level: "info",
+          message: `Transaction created: ECN=${data.ecn}, Type=${data.requestType}`
+        });
+        return result;
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to create transaction: ${error.message}`
+        });
+        throw error;
+      }
+    }
+    function updateTransactionResponse(ecn, data) {
+      try {
+        const database = getDatabase();
+        const now = Date.now();
+        const stmt = database.prepare(`
+      UPDATE transactions 
+      SET response_hex = ?, 
+          response_data = ?, 
+          response_timestamp = ?,
+          status = ?,
+          updated_at = ?
+      WHERE ecn = ?
+    `);
+        const result = stmt.run(
+          data.responseHex,
+          JSON.stringify(data.responseData || {}),
+          now,
+          data.status || "COMPLETED",
+          now,
+          ecn
+        );
+        logger.log({
+          level: "info",
+          message: `Transaction updated: ECN=${ecn}, Status=${data.status || "COMPLETED"}`
+        });
+        return result;
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to update transaction: ${error.message}`
+        });
+        throw error;
+      }
+    }
+    function getTransactionByEcn(ecn) {
+      try {
+        const database = getDatabase();
+        const stmt = database.prepare("SELECT * FROM transactions WHERE ecn = ?");
+        const row = stmt.get(ecn);
+        if (row) {
+          row.request_payload = JSON.parse(row.request_payload || "{}");
+          row.response_data = JSON.parse(row.response_data || "{}");
+        }
+        return row;
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to get transaction: ${error.message}`
+        });
+        return null;
+      }
+    }
+    function getRecentTransactions(limit = 100) {
+      try {
+        const database = getDatabase();
+        const stmt = database.prepare(`
+      SELECT * FROM transactions 
+      ORDER BY request_timestamp DESC 
+      LIMIT ?
+    `);
+        const rows = stmt.all(limit);
+        return rows.map((row) => ({
+          ...row,
+          request_payload: JSON.parse(row.request_payload || "{}"),
+          response_data: JSON.parse(row.response_data || "{}")
+        }));
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to get recent transactions: ${error.message}`
+        });
+        return [];
+      }
+    }
+    function getTransactionsByStatus(status, limit = 100) {
+      try {
+        const database = getDatabase();
+        const stmt = database.prepare(`
+      SELECT * FROM transactions 
+      WHERE status = ?
+      ORDER BY request_timestamp DESC 
+      LIMIT ?
+    `);
+        const rows = stmt.all(status, limit);
+        return rows.map((row) => ({
+          ...row,
+          request_payload: JSON.parse(row.request_payload || "{}"),
+          response_data: JSON.parse(row.response_data || "{}")
+        }));
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to get transactions by status: ${error.message}`
+        });
+        return [];
+      }
+    }
+    function cleanupOldTransactions(daysToKeep = 90) {
+      try {
+        const database = getDatabase();
+        const cutoffTime = Date.now() - daysToKeep * 24 * 60 * 60 * 1e3;
+        const stmt = database.prepare("DELETE FROM transactions WHERE request_timestamp < ?");
+        const result = stmt.run(cutoffTime);
+        logger.log({
+          level: "info",
+          message: `Cleaned up ${result.changes} old transactions (older than ${daysToKeep} days)`
+        });
+        return result.changes;
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to cleanup old transactions: ${error.message}`
+        });
+        return 0;
+      }
+    }
+    function closeDatabase() {
+      if (db) {
+        db.close();
+        db = null;
+        logger.log({
+          level: "info",
+          message: "Database connection closed"
+        });
+      }
+    }
+    module2.exports = {
+      initDatabase,
+      getDatabase,
+      createTransaction,
+      updateTransactionResponse,
+      getTransactionByEcn,
+      getRecentTransactions,
+      getTransactionsByStatus,
+      cleanupOldTransactions,
+      closeDatabase,
+      // Auto-purge control functions
+      startAutoPurge: require_autoPurge().startAutoPurge,
+      stopAutoPurge: require_autoPurge().stopAutoPurge,
+      isAutoPurgeRunning: require_autoPurge().isAutoPurgeRunning
+    };
+  }
+});
+
 // src/payment/responseHandler.js
 var require_responseHandler = __commonJS({
   "src/payment/responseHandler.js"(exports2, module2) {
@@ -648,6 +945,7 @@ var require_responseHandler = __commonJS({
     } = require_parser();
     var fw = require_manageConfig();
     var { xorCalculation } = require_utils_helper();
+    var { updateTransactionResponse } = require_transactionStore();
     var queue2 = new Queue();
     module2.exports.terminalStatus = (ecn) => {
       const length = queue2.size();
@@ -662,6 +960,18 @@ var require_responseHandler = __commonJS({
         level: "info",
         message: status
       });
+      try {
+        updateTransactionResponse(ecn, {
+          responseHex: fullHex,
+          responseData: { status },
+          status: status ? "COMPLETED" : "FAILED"
+        });
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to update transaction: ${error.message}`
+        });
+      }
       if (status) {
         fw.updateConfig({ terminal_status: true });
         sendMessage2("clientRoom", "STATUS_MESSAGE", {
@@ -687,6 +997,18 @@ var require_responseHandler = __commonJS({
       }
       console.log(fullHex);
       const response = logonParser(fullHex, ecn);
+      try {
+        updateTransactionResponse(ecn, {
+          responseHex: fullHex,
+          responseData: response,
+          status: response.status ? "COMPLETED" : "FAILED"
+        });
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to update transaction: ${error.message}`
+        });
+      }
       if (response.status) {
         fw.updateConfig({ last_logon: /* @__PURE__ */ new Date() });
         sendMessage2("clientRoom", "LOGON_MESSAGE", {
@@ -714,6 +1036,18 @@ var require_responseHandler = __commonJS({
     module2.exports.terminalPayment = (hexValue, ecn) => {
       const parsedValue = netsPaymentParser(hexValue, ecn);
       const response = jsonProcessor(parsedValue);
+      try {
+        updateTransactionResponse(ecn, {
+          responseHex: hexValue,
+          responseData: response,
+          status: response.translated?.status || "UNKNOWN"
+        });
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to update transaction: ${error.message}`
+        });
+      }
       if (response.translated) {
         if (response.translated.status == "APPROVED") {
           sendMessage2("clientRoom", "PAYMENT_MESSAGE", {
@@ -741,6 +1075,18 @@ var require_responseHandler = __commonJS({
     module2.exports.terminalCreditPayment = (hexValue, ecn) => {
       const parsedValue = creditPaymentParser(hexValue, ecn);
       const response = jsonProcessor(parsedValue);
+      try {
+        updateTransactionResponse(ecn, {
+          responseHex: hexValue,
+          responseData: response,
+          status: response.translated?.status || "UNKNOWN"
+        });
+      } catch (error) {
+        logger.log({
+          level: "error",
+          message: `Failed to update transaction: ${error.message}`
+        });
+      }
       if (response.translated) {
         if (response.translated.status == "APPROVED") {
           sendMessage2("clientRoom", "PAYMENT_MESSAGE", {
@@ -817,6 +1163,7 @@ var require_communication = __commonJS({
     } = require_responseHandler();
     var { sendMessage: sendMessage2 } = require_sendMessage();
     var fw = require_manageConfig();
+    var { createTransaction } = require_transactionStore();
     var { initialiseRequest } = require_httpRequest();
     var requestType;
     var calculated;
@@ -968,16 +1315,55 @@ var require_communication = __commonJS({
       requestPayload = body;
       if (requestType == "STATUS_CHECK") {
         calculated = generateStatusReq();
+        try {
+          createTransaction({
+            ecn: calculated.ecn,
+            requestType,
+            requestPayload: null,
+            requestHex: calculated.buffer.toString("hex")
+          });
+        } catch (error) {
+          logger.log({
+            level: "error",
+            message: `Failed to store transaction: ${error.message}`
+          });
+        }
         global.port.write(calculated.buffer);
       }
       if (requestType == "LOGON") {
         calculated = generateLogonRequest();
+        try {
+          createTransaction({
+            ecn: calculated.ecn,
+            requestType,
+            requestPayload: null,
+            requestHex: calculated.buffer.toString("hex")
+          });
+        } catch (error) {
+          logger.log({
+            level: "error",
+            message: `Failed to store transaction: ${error.message}`
+          });
+        }
         global.port.write(calculated.buffer);
       }
       if (requestType == "PAYMENT" || requestType == "CREDIT_PAYMENT") {
         exports2.reset();
         calculated = generatePaymentRequest(body);
         console.log(calculated);
+        try {
+          createTransaction({
+            ecn: calculated.ecn,
+            requestType,
+            requestPayload: body,
+            requestHex: calculated.hexString
+          });
+        } catch (error) {
+          logger.log({
+            level: "error",
+            message: `Failed to store transaction: ${error.message}`
+          });
+        }
         global.port.write(calculated.buffer);
         exports2.checkACKorNACK();
       }
@@ -996,6 +1382,7 @@ var hexRequest = require_hexRequest();
 var httpRequest = require_httpRequest();
 var parser = require_parser();
 var responseHandler = require_responseHandler();
+var transactionStore = require_transactionStore();
 module.exports = {
   ...utilsHelper,
   logger: winston,
@@ -1006,5 +1393,14 @@ module.exports = {
   hexRequest,
   httpRequest,
   parser,
-  responseHandler
+  responseHandler,
+  // Transaction store utilities
+  getTransactionByEcn: transactionStore.getTransactionByEcn,
+  getRecentTransactions: transactionStore.getRecentTransactions,
+  getTransactionsByStatus: transactionStore.getTransactionsByStatus,
+  cleanupOldTransactions: transactionStore.cleanupOldTransactions,
+  // Auto-purge control
+  startAutoPurge: transactionStore.startAutoPurge,
+  stopAutoPurge: transactionStore.stopAutoPurge,
+  isAutoPurgeRunning: transactionStore.isAutoPurgeRunning
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nets-service-sdk",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Utility functions for Nets Service",
   "source": "src/index.js",
   "main": "dist/index.js",
@@ -11,16 +11,18 @@
     "watch": "microbundle watch",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": [],
+  "keywords": ["nets", "payment", "terminal", "pos", "sqlite", "transaction", "serial", "payment-gateway"],
   "author": "dineshhv",
   "license": "ISC",
   "files": [
     "dist"
   ],
   "dependencies": {
+    "better-sqlite3": "^12.5.0",
     "dollars-to-cents": "^1.0.3",
     "lodash": "^4.17.21",
     "moment": "^2.29.4",
+    "node-cron": "^4.2.1",
     "request": "^2.88.2",
     "serialport": "^10.5.0",
     "socket.io-client": "^4.7.2",