elpaypg 0.0.0-stage → 2.0.0

package/src/vendor/db/__tests__/db.test.js

@@ -0,0 +1,265 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  Database,
+  runMigrations,
+  MerchantRepository,
+  ReceivingAccountRepository,
+  CustomerRepository,
+  PaymentSessionRepository,
+  ObservationRepository,
+  SupportTicketRepository,
+  AuditLogRepository
+} from '../index.js';
+import { PaymentStatus, ObserverSource, SenderType, TicketStatus } from '../../common/index.js';
+
+describe('../../db/index.js Unit & Integration Tests', () => {
+  let db;
+  let merchantRepo;
+  let accountRepo;
+  let customerRepo;
+  let sessionRepo;
+  let obsRepo;
+  let ticketRepo;
+  let auditRepo;
+  let testMerchant;
+  let testAccount;
+
+  beforeEach(() => {
+    db = new Database({ inMemory: true });
+    const { defaultMerchant } = runMigrations(db);
+    testMerchant = defaultMerchant;
+
+    merchantRepo = new MerchantRepository(db);
+    accountRepo = new ReceivingAccountRepository(db);
+    customerRepo = new CustomerRepository(db);
+    sessionRepo = new PaymentSessionRepository(db);
+    obsRepo = new ObservationRepository(db);
+    ticketRepo = new SupportTicketRepository(db);
+    auditRepo = new AuditLogRepository(db);
+
+    testAccount = accountRepo.findActiveForMerchant(testMerchant.id);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  test('migrations seed default merchant and active UPI receiving account', () => {
+    assert.ok(testMerchant);
+    assert.equal(testMerchant.slug, 'demo-store');
+    assert.ok(testAccount);
+    assert.equal(testAccount.upiId, 'merchant@upi');
+    assert.equal(testAccount.isActive, true);
+    assert.equal(testAccount.isSlotBusy, false);
+  });
+
+  test('customer registration and password verification', () => {
+    const customer = customerRepo.create({
+      merchantId: testMerchant.id,
+      phoneNumber: '9876543210',
+      fullName: 'Gaurav Sharma',
+      password: 'SecurePassword123!'
+    });
+
+    assert.ok(customer.id);
+    assert.equal(customer.phoneNumber, '9876543210');
+    assert.equal(customer.fullName, 'Gaurav Sharma');
+
+    const verified = customerRepo.verifyCredentials(
+      testMerchant.id,
+      '9876543210',
+      'SecurePassword123!'
+    );
+    assert.ok(verified);
+    assert.equal(verified.id, customer.id);
+
+    const failed = customerRepo.verifyCredentials(
+      testMerchant.id,
+      '9876543210',
+      'WrongPassword'
+    );
+    assert.equal(failed, null);
+  });
+
+  describe('Queue Engine & Concurrency Slot Invariants', () => {
+    test('enforces ONE active slot at one time and queues subsequent sessions', () => {
+      // Create session A
+      const sessionA = sessionRepo.create({
+        merchantId: testMerchant.id,
+        receivingAccountId: testAccount.id,
+        orderId: 'ORDER-A',
+        amountPaise: 20000n
+      });
+
+      // Create session B (same amount, same account)
+      const sessionB = sessionRepo.create({
+        merchantId: testMerchant.id,
+        receivingAccountId: testAccount.id,
+        orderId: 'ORDER-B',
+        amountPaise: 20000n
+      });
+
+      // Create session C (same amount, same account)
+      const sessionC = sessionRepo.create({
+        merchantId: testMerchant.id,
+        receivingAccountId: testAccount.id,
+        orderId: 'ORDER-C',
+        amountPaise: 20000n
+      });
+
+      // 1. Session A attempts to acquire slot
+      const resA = sessionRepo.acquireSlotAtomic(sessionA.id, testAccount.id, 300000);
+      assert.equal(resA.status, PaymentStatus.ACTIVE);
+      assert.equal(resA.queuePosition, 0);
+      assert.ok(resA.expiresAt instanceof Date);
+
+      // Verify receiving account is marked busy
+      const acctAfterA = accountRepo.findById(testAccount.id);
+      assert.equal(acctAfterA.isSlotBusy, true);
+      assert.equal(acctAfterA.currentActiveSessionId, sessionA.id);
+
+      // 2. Session B attempts to acquire slot -> MUST BE QUEUED at position 1
+      const resB = sessionRepo.acquireSlotAtomic(sessionB.id, testAccount.id, 300000);
+      assert.equal(resB.status, PaymentStatus.QUEUED);
+      assert.equal(resB.queuePosition, 1);
+      assert.equal(resB.expiresAt, null);
+
+      // 3. Session C attempts to acquire slot -> MUST BE QUEUED at position 2
+      const resC = sessionRepo.acquireSlotAtomic(sessionC.id, testAccount.id, 300000);
+      assert.equal(resC.status, PaymentStatus.QUEUED);
+      assert.equal(resC.queuePosition, 2);
+
+      // 4. Session A transitions to PROCESSING when customer clicks "Payment Done"
+      const procA = sessionRepo.transitionToProcessing(sessionA.id, 30000);
+      assert.equal(procA.status, PaymentStatus.PROCESSING);
+      assert.ok(procA.processingStartedAt instanceof Date);
+      assert.ok(procA.processingExpiresAt instanceof Date);
+
+      // Slot MUST STILL BE BUSY during PROCESSING! Session B cannot steal it
+      const acctDuringProc = accountRepo.findById(testAccount.id);
+      assert.equal(acctDuringProc.isSlotBusy, true);
+      assert.equal(acctDuringProc.currentActiveSessionId, sessionA.id);
+
+      // 5. Session A finishes with SUCCESS
+      const successA = sessionRepo.transitionToTerminal(sessionA.id, PaymentStatus.SUCCESS);
+      assert.equal(successA.status, PaymentStatus.SUCCESS);
+      assert.ok(successA.completedAt instanceof Date);
+
+      // Slot is now released!
+      const acctAfterSuccess = accountRepo.findById(testAccount.id);
+      assert.equal(acctAfterSuccess.isSlotBusy, false);
+      assert.equal(acctAfterSuccess.currentActiveSessionId, null);
+
+      // 6. Promote next queued session (B)
+      const nextQueued = sessionRepo.getNextQueuedSession(testAccount.id);
+      assert.equal(nextQueued.id, sessionB.id);
+
+      const resBAfterPromo = sessionRepo.acquireSlotAtomic(sessionB.id, testAccount.id, 300000);
+      assert.equal(resBAfterPromo.status, PaymentStatus.ACTIVE);
+      assert.equal(resBAfterPromo.queuePosition, 0);
+
+      // Re-index remaining queue
+      sessionRepo.reindexQueue(testAccount.id);
+      const updatedC = sessionRepo.findById(sessionC.id);
+      assert.equal(updatedC.queuePosition, 1); // C promoted from #2 to #1 in waiting line
+    });
+
+    test('transitions to CANCELLED and immediately releases slot', () => {
+      const session = sessionRepo.create({
+        merchantId: testMerchant.id,
+        receivingAccountId: testAccount.id,
+        orderId: 'ORDER-CANCEL',
+        amountPaise: 50000n
+      });
+
+      sessionRepo.acquireSlotAtomic(session.id, testAccount.id, 300000);
+      let acct = accountRepo.findById(testAccount.id);
+      assert.equal(acct.isSlotBusy, true);
+
+      sessionRepo.transitionToTerminal(session.id, PaymentStatus.CANCELLED);
+      acct = accountRepo.findById(testAccount.id);
+      assert.equal(acct.isSlotBusy, false);
+      assert.equal(acct.currentActiveSessionId, null);
+    });
+  });
+
+  describe('Observation Deduplication & Storage', () => {
+    test('records observations and retrieves by fingerprint for deduplication', () => {
+      const now = new Date();
+      const obs = obsRepo.create({
+        receivingAccountId: testAccount.id,
+        source: ObserverSource.GOOGLE_MESSAGES,
+        amountPaise: 20000n,
+        observedAt: now,
+        bankReferenceNumber: 'UTR998877',
+        fingerprintHash: 'hash_abc_123',
+        rawPayload: { text: 'Received Rs 200 via UPI' }
+      });
+
+      assert.ok(obs.id);
+      assert.equal(obs.bankReferenceNumber, 'UTR998877');
+
+      const found = obsRepo.findByFingerprint('hash_abc_123');
+      assert.ok(found);
+      assert.equal(found.id, obs.id);
+    });
+  });
+
+  describe('Support Tickets & Live Messages', () => {
+    test('creates tickets, links payments, and records bidirectional chat', () => {
+      const customer = customerRepo.create({
+        merchantId: testMerchant.id,
+        phoneNumber: '9123456780',
+        fullName: 'Anita Roy',
+        password: 'PassWord123!'
+      });
+
+      const ticket = ticketRepo.createTicket({
+        merchantId: testMerchant.id,
+        customerId: customer.id,
+        subject: 'Payment failed but money deducted',
+        initialMessage: {
+          senderType: SenderType.CUSTOMER,
+          senderId: customer.id,
+          message: 'I paid 200 rupees but the screen said failed.'
+        }
+      });
+
+      assert.ok(ticket.id);
+      assert.equal(ticket.status, TicketStatus.OPEN);
+
+      // Admin replies
+      const adminMsg = ticketRepo.addMessage({
+        ticketId: ticket.id,
+        senderType: SenderType.ADMIN,
+        senderId: testMerchant.id,
+        message: 'Hello Anita, we found your transaction and have credited your order.'
+      });
+
+      assert.ok(adminMsg.id);
+
+      const messages = ticketRepo.findMessagesByTicket(ticket.id);
+      assert.equal(messages.length, 2);
+      assert.equal(messages[0].senderType, SenderType.CUSTOMER);
+      assert.equal(messages[1].senderType, SenderType.ADMIN);
+    });
+  });
+
+  describe('Audit Logging', () => {
+    test('records and queries audit trail', () => {
+      auditRepo.log({
+        merchantId: testMerchant.id,
+        entityType: 'PAYMENT_SESSION',
+        entityId: 'pay_123',
+        action: 'SLOT_ACQUIRED',
+        details: { queuePosition: 0 }
+      });
+
+      const logs = auditRepo.findByEntity('PAYMENT_SESSION', 'pay_123');
+      assert.equal(logs.length, 1);
+      assert.equal(logs[0].action, 'SLOT_ACQUIRED');
+      assert.equal(logs[0].details.queuePosition, 0);
+    });
+  });
+});

package/src/vendor/db/__tests__/schema-parity.test.js

@@ -0,0 +1,137 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Database } from '../database.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+describe('Database Schema Parity & Integrity (Postgres vs SQLite) (#13)', () => {
+  const pgSchemaPath = path.join(__dirname, '..', 'schema.sql');
+  const sqliteSchemaPath = path.join(__dirname, '..', 'sqlite-schema.sql');
+
+  const pgSchema = fs.readFileSync(pgSchemaPath, 'utf8');
+  const sqliteSchema = fs.readFileSync(sqliteSchemaPath, 'utf8');
+
+  function extractTableNames(sql) {
+    const regex = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([a-zA-Z0-9_]+)/gi;
+    const tables = [];
+    let match;
+    while ((match = regex.exec(sql)) !== null) {
+      tables.push(match[1].toLowerCase());
+    }
+    return tables;
+  }
+
+  function extractIndexNames(sql) {
+    const regex = /CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?([a-zA-Z0-9_]+)/gi;
+    const indexes = [];
+    let match;
+    while ((match = regex.exec(sql)) !== null) {
+      indexes.push(match[1].toLowerCase());
+    }
+    return indexes;
+  }
+
+  test('PostgreSQL and SQLite schemas define identical set of tables', () => {
+    const pgTables = extractTableNames(pgSchema);
+    const sqliteTables = extractTableNames(sqliteSchema);
+
+    assert.deepEqual(pgTables.sort(), sqliteTables.sort(), 'Tables in schema.sql and sqlite-schema.sql must match 1:1');
+    assert.ok(pgTables.length >= 10, 'Must have at least 10 core tables defined');
+  });
+
+  test('devices table is defined before payment_sessions in both schemas to prevent foreign key errors', () => {
+    const pgTables = extractTableNames(pgSchema);
+    const sqliteTables = extractTableNames(sqliteSchema);
+
+    const pgDevicesIdx = pgTables.indexOf('devices');
+    const pgSessionsIdx = pgTables.indexOf('payment_sessions');
+    assert.ok(pgDevicesIdx !== -1, 'devices table must exist in schema.sql');
+    assert.ok(pgSessionsIdx !== -1, 'payment_sessions table must exist in schema.sql');
+    assert.ok(pgDevicesIdx < pgSessionsIdx, 'devices must be declared before payment_sessions in schema.sql');
+
+    const sqliteDevicesIdx = sqliteTables.indexOf('devices');
+    const sqliteSessionsIdx = sqliteTables.indexOf('payment_sessions');
+    assert.ok(sqliteDevicesIdx < sqliteSessionsIdx, 'devices must be declared before payment_sessions in sqlite-schema.sql');
+  });
+
+  test('PostgreSQL and SQLite schemas define identical core indexes', () => {
+    const pgIndexes = extractIndexNames(pgSchema);
+    const sqliteIndexes = extractIndexNames(sqliteSchema);
+
+    const requiredIndexes = [
+      'idx_single_active_vpa_per_merchant',
+      'idx_customers_email',
+      'idx_customers_mobile',
+      'idx_customer_sessions_token',
+      'idx_customer_sessions_customer',
+      'idx_devices_customer',
+      'idx_devices_fingerprint',
+      'idx_devices_token',
+      'idx_payment_sessions_active',
+      'idx_payment_sessions_order',
+      'idx_payment_sessions_device',
+      'idx_single_active_session_per_order',
+      'idx_one_slot_per_receiving_account',
+      'idx_payment_sessions_attributed_obs',
+      'idx_observations_match',
+      'idx_observations_bank_ref',
+      'idx_observations_unique_attributed_bank_ref',
+      'idx_observations_fingerprint',
+      'idx_observations_attributed_payment',
+      'idx_webhook_deliveries_retry',
+      'idx_support_tickets_merchant',
+      'idx_support_tickets_customer',
+      'idx_ticket_messages_ticket',
+      'idx_audit_logs_merchant',
+      'idx_audit_logs_entity',
+      'idx_security_events_customer',
+      'idx_security_events_session',
+      'idx_security_events_type'
+    ];
+
+    for (const idx of requiredIndexes) {
+      assert.ok(pgIndexes.includes(idx), `schema.sql missing index: ${idx}`);
+      assert.ok(sqliteIndexes.includes(idx), `sqlite-schema.sql missing index: ${idx}`);
+    }
+  });
+
+  test('customers table has required security and fraud tracking columns in both schemas', () => {
+    const requiredCustomerCols = [
+      'otp_attempts',
+      'ban_reason',
+      'banned_at',
+      'unbanned_at',
+      'last_device'
+    ];
+
+    for (const col of requiredCustomerCols) {
+      assert.ok(pgSchema.includes(col), `schema.sql customers table missing column: ${col}`);
+      assert.ok(sqliteSchema.includes(col), `sqlite-schema.sql customers table missing column: ${col}`);
+    }
+  });
+
+  test('sqlite-schema.sql executes cleanly and creates complete schema on fresh database', () => {
+    const db = new Database({ inMemory: true, autoMigrate: false });
+    try {
+      db.exec(sqliteSchema);
+      const tables = db.query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'");
+      const tableNames = tables.map(t => t.name);
+      assert.ok(tableNames.includes('merchants'));
+      assert.ok(tableNames.includes('payment_receiving_accounts'));
+      assert.ok(tableNames.includes('customers'));
+      assert.ok(tableNames.includes('devices'));
+      assert.ok(tableNames.includes('payment_sessions'));
+      assert.ok(tableNames.includes('payment_observations'));
+      assert.ok(tableNames.includes('webhook_deliveries'));
+      assert.ok(tableNames.includes('support_tickets'));
+      assert.ok(tableNames.includes('audit_logs'));
+      assert.ok(tableNames.includes('security_events'));
+    } finally {
+      db.close();
+    }
+  });
+});

package/src/vendor/db/__tests__/sqlite_verify.test.js

@@ -0,0 +1,15 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+
+test('native node:sqlite operates in memory', () => {
+  const db = new DatabaseSync(':memory:');
+  db.exec('CREATE TABLE test (id TEXT PRIMARY KEY, val INT);');
+  const insert = db.prepare('INSERT INTO test (id, val) VALUES (?, ?)');
+  insert.run('1', 42);
+
+  const select = db.prepare('SELECT * FROM test WHERE id = ?');
+  const row = select.get('1');
+  assert.equal(row.val, 42);
+  db.close();
+});

package/src/vendor/db/database.js

@@ -0,0 +1,181 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DatabaseSync } from 'node:sqlite';
+import { runMigrations } from './migrate.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, '../../..');
+
+/**
+ * Checks if core tables exist and executes migrations if not yet initialized.
+ * @param {Database} db
+ */
+export function ensureDatabaseInitialized(db) {
+  try {
+    const row = db.queryOne("SELECT count(*) as count FROM sqlite_master WHERE type='table' AND name='merchants'");
+    if (!row || Number(row.count) === 0) {
+      return runMigrations(db);
+    }
+  } catch {
+    return runMigrations(db);
+  }
+}
+
+/**
+ * Universal Database Client for ELPAY PG.
+ * Uses native node:sqlite for high-performance, embedded zero-dependency local operation
+ * with full transactional ACID guarantees.
+ */
+export class Database {
+  /**
+   * @param {{ dbPath?: string, inMemory?: boolean, autoMigrate?: boolean }} [options={}]
+   */
+  constructor(options = {}) {
+    if (options.inMemory) {
+      this.db = new DatabaseSync(':memory:');
+    } else {
+      let dbPath;
+      if (options.dbPath) {
+        dbPath = path.isAbsolute(options.dbPath)
+          ? options.dbPath
+          : path.resolve(process.cwd(), options.dbPath);
+      } else if (process.env.SQLITE_DB_PATH) {
+        dbPath = path.isAbsolute(process.env.SQLITE_DB_PATH)
+          ? process.env.SQLITE_DB_PATH
+          : path.resolve(repoRoot, process.env.SQLITE_DB_PATH);
+      } else {
+        dbPath = path.resolve(repoRoot, 'data/elpay_pg.sqlite');
+      }
+      const dir = path.dirname(dbPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      }
+      this.db = new DatabaseSync(dbPath);
+      // The file holds webhook secrets, session-token indexes, OTPs and customer PII.
+      // Default file creation honours umask, which on many hosts leaves it group/world
+      // readable, so restrict it explicitly.
+      try { fs.chmodSync(dbPath, 0o600); } catch {}
+      try { fs.chmodSync(dir, 0o700); } catch {}
+    }
+
+    // Enable foreign keys, busy timeout, and WAL mode for maximum concurrency and integrity
+    this.db.exec('PRAGMA foreign_keys = ON;');
+    this.db.exec('PRAGMA busy_timeout = 5000;');
+    try {
+      this.db.exec('PRAGMA journal_mode = WAL;');
+    } catch {}
+
+    // Auto-initialize SQLite on first boot if core tables do not exist
+    if (!options.inMemory && options.autoMigrate !== false) {
+      ensureDatabaseInitialized(this);
+    }
+  }
+
+  /**
+   * Normalizes parameter markers from PostgreSQL style ($1, $2) to SQLite style (?, ?).
+   * @param {string} sql
+   * @returns {string}
+   */
+  normalizeSql(sql) {
+    return sql.replace(/\$\d+/g, '?');
+  }
+
+  /**
+   * Executes a statement (INSERT, UPDATE, DELETE, DDL).
+   * @param {string} sql
+   * @param {any[]} [params=[]]
+   * @returns {{ changes: number, lastInsertRowid: number | bigint }}
+   */
+  execute(sql, params = []) {
+    const normalized = this.normalizeSql(sql);
+    const stmt = this.db.prepare(normalized);
+    return stmt.run(...params);
+  }
+
+  run(sql, params = []) {
+    return this.execute(sql, params);
+  }
+
+  /**
+   * Queries multiple rows.
+   * @param {string} sql
+   * @param {any[]} [params=[]]
+   * @returns {any[]}
+   */
+  query(sql, params = []) {
+    const normalized = this.normalizeSql(sql);
+    const stmt = this.db.prepare(normalized);
+    return stmt.all(...params);
+  }
+
+  /**
+   * Queries a single row.
+   * @param {string} sql
+   * @param {any[]} [params=[]]
+   * @returns {any | null}
+   */
+  queryOne(sql, params = []) {
+    const normalized = this.normalizeSql(sql);
+    const stmt = this.db.prepare(normalized);
+    const res = stmt.get(...params);
+    return res !== undefined ? res : null;
+  }
+
+  /**
+   * Executes a batch of DDL or SQL statements.
+   * @param {string} sql
+   */
+  exec(sql) {
+    this.db.exec(sql);
+  }
+
+  /**
+   * Executes a callback within an ACID database transaction.
+   * Automatically rolls back on exception.
+   * @template T
+   * @param {() => T} callback
+   * @returns {T}
+   */
+  transaction(callback) {
+    // IMMEDIATE (not DEFERRED) so the write lock is taken up front. A deferred transaction
+    // starts as a read transaction and only upgrades on first write, which lets two
+    // concurrent slot-acquisition callers both observe a free slot before either writes.
+    this.db.exec('BEGIN IMMEDIATE;');
+    try {
+      const result = callback();
+      this.db.exec('COMMIT;');
+      return result;
+    } catch (err) {
+      try {
+        this.db.exec('ROLLBACK;');
+      } catch {
+        // Ignore rollback error if already rolled back
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Closes the database connection.
+   */
+  close() {
+    this.db.close();
+  }
+}
+
+let defaultDbInstance = null;
+
+/**
+ * Returns the singleton database instance.
+ * @param {{ dbPath?: string, inMemory?: boolean }} [options={}]
+ * @returns {Database}
+ */
+export function getDatabase(options = {}) {
+  if (!defaultDbInstance) {
+    defaultDbInstance = new Database(options);
+    ensureDatabaseInitialized(defaultDbInstance);
+  }
+  return defaultDbInstance;
+}

package/src/vendor/db/index.js

@@ -0,0 +1,12 @@
+export * from './database.js';
+export * from './migrate.js';
+export * from './repositories/merchant.repository.js';
+export * from './repositories/receiving-account.repository.js';
+export * from './repositories/customer.repository.js';
+export * from './repositories/customer-session.repository.js';
+export * from './repositories/payment-session.repository.js';
+export * from './repositories/observation.repository.js';
+export * from './repositories/support-ticket.repository.js';
+export * from './repositories/audit-log.repository.js';
+export * from './repositories/device.repository.js';
+