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

``bash
npm install nets-service-sdk
`

Usage

$3

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

$3

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

`javascript
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' });
`

$3

Handle communication with the NETS terminal.

`javascript
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'
});
`

$3

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

`javascript
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.

$3

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
`

$3

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

$3

The SDK exports various utility functions directly.

`javascript
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" });
`

$3

Use the built-in Winston logger.

`javascript
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