nets-service-sdk

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, 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

npm install nets-service-sdk

Usage

Importing the SDK

const netsSdk = require('nets-service-sdk');
// OR destructure specific modules
const { communication, manageConfig, logger } = require('nets-service-sdk');

Configuration Management

Manage your application configuration using manageConfig. It reads/writes to a config.json file in your project root.

const { manageConfig } = require('nets-service-sdk');

// Get entire configuration
const config = manageConfig.getConfig();

// Get specific config value
const port = manageConfig.getConfigByKey('com');

// Update configuration
manageConfig.updateConfig({ com: '/dev/ttyUSB0' });

Serial Communication (Payment Terminal)

Handle communication with the NETS terminal.

const { communication } = require('nets-service-sdk');

// Initialize WITHOUT socket (messages logged only)
communication.initialize();

// OR Initialize WITH socket (messages emitted via socket)
const io = require('socket.io-client');
const socket = io('http://localhost:3000');
communication.initialize(socket);

// Send a request to the terminal
// Types: 'STATUS_CHECK', 'LOGON', 'PAYMENT', 'CREDIT_PAYMENT'
communication.sentToTerminal('STATUS_CHECK', {});

// For Payment
communication.sentToTerminal('PAYMENT', {
    amount: 1000, // Amount in cents
    reference: 'ORDER123',
    ecn: '040126003000'
});

Socket.IO Integration (Optional)

The SDK supports optional Socket.IO integration for real-time event broadcasting.

const io = require('socket.io-client');
const sdk = require('nets-service-sdk');

// Connect to Socket.IO server
const socket = io('http://localhost:3000');

// Initialize with socket connection
sdk.communication.initialize(socket);

// Listen for events on client side
socket.on('PAYMENT_MESSAGE', (data) => {
  console.log('Payment event:', data);
});

socket.on('LOGON_MESSAGE', (data) => {
  console.log('Logon event:', data);
});

Socket Events Emitted:

• STATUS_MESSAGE - Terminal status updates
• LOGON_MESSAGE - Terminal logon results
• PAYMENT_MESSAGE - Payment transaction updates

Note: Socket connection is optional. Without it, events are logged only.

See Socket Integration Guide for detailed usage.

Transaction Storage (New in v1.1.0)

All terminal requests and responses are automatically stored in a SQLite database.

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.

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.

const { padWithLeadingZeros, xorCalculation, generateServiceKey } = require('nets-service-sdk');

// Pad numbers
console.log(padWithLeadingZeros(5, 3)); // Output: "005"

// XOR Calculation for checksums
const checksum = xorCalculation("02313030");

// Generate Service Key
const key = generateServiceKey({ some: "payload" });

Logging

Use the built-in Winston logger.

const { logger } = require('nets-service-sdk');
const myLogger = logger(module);

myLogger.info('This is an info message');
myLogger.error('This is an error message');

Modules

• communication: Handles serial port communication with the terminal.
• manageConfig: Reads and writes configuration to config.json.
• utilsHelper: General utility functions (padding, XOR, hex conversion, etc.).
• logger: Winston logger configuration.
• queue: Queue management (if applicable).
• 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

ISC