elpaypg 0.0.0-stage → 2.0.1

package/src/vendor/common/money.ts

@@ -0,0 +1,56 @@
+/**
+ * Financial utilities enforcing integer minor units (paise).
+ * Floating-point representation is forbidden in financial calculations.
+ * 1 INR = 100 paise.
+ */
+
+/**
+ * Converts a rupee amount (string or number) into integer paise (bigint).
+ * Throws an error if invalid, negative, zero, or exceeds 2 decimal places.
+ */
+export function toPaise(rupees: string | number): bigint {
+  if (typeof rupees === 'number') {
+    if (!Number.isFinite(rupees) || isNaN(rupees)) {
+      throw new Error(`Invalid monetary amount: ${rupees}`);
+    }
+    rupees = rupees.toString();
+  }
+
+  const clean = rupees.trim();
+  if (!/^\d+(\.\d{1,2})?$/.test(clean)) {
+    throw new Error(`Invalid INR rupee format: "${rupees}". Must be non-negative with max 2 decimals.`);
+  }
+
+  const parts = clean.split('.');
+  const whole = BigInt(parts[0] || '0');
+  const fractionStr = parts[1] || '';
+  const fraction = BigInt(fractionStr.padEnd(2, '0'));
+
+  const totalPaise = whole * 100n + fraction;
+  if (totalPaise <= 0n) {
+    throw new Error(`Monetary amount must be strictly greater than 0: ${rupees}`);
+  }
+
+  return totalPaise;
+}
+
+/**
+ * Formats integer paise into a standard decimal string ("200.00").
+ */
+export function toRupeesString(paise: bigint | number): string {
+  const p = typeof paise === 'number' ? BigInt(Math.floor(paise)) : paise;
+  if (p < 0n) {
+    throw new Error(`Negative paise value not permitted: ${p}`);
+  }
+
+  const whole = p / 100n;
+  const fraction = p % 100n;
+  return `${whole}.${fraction.toString().padStart(2, '0')}`;
+}
+
+/**
+ * Formats integer paise into a localized INR display string ("₹200.00").
+ */
+export function formatINR(paise: bigint | number): string {
+  return `₹${toRupeesString(paise)}`;
+}

package/src/vendor/common/observation.js

@@ -0,0 +1,27 @@
+import crypto from 'node:crypto';
+
+/**
+ * Calculates a deterministic fingerprint for an observation to prevent duplicate processing.
+ * If bankReferenceNumber exists, it hashes receivingAccount + amount + referenceNumber.
+ * Otherwise, it hashes receivingAccount + amount + 60-second time bucket.
+ * @param {{
+ *   receivingAccountId: string,
+ *   amountPaise: bigint,
+ *   bankReferenceNumber?: string,
+ *   observedAt: Date
+ * }} input
+ * @returns {string}
+ */
+export function calculateObservationFingerprint(input) {
+  let entropy;
+  if (input.bankReferenceNumber && input.bankReferenceNumber.trim().length > 0) {
+    entropy = `REF:${input.bankReferenceNumber.trim().toUpperCase()}`;
+  } else {
+    // 60-second temporal cluster bucket partitioned by channel source
+    const bucket = Math.floor(input.observedAt.getTime() / 60000);
+    entropy = `TIME_BUCKET:${bucket}:${input.source || ''}`;
+  }
+
+  const raw = `${input.receivingAccountId}:${input.amountPaise.toString()}:${entropy}`;
+  return crypto.createHash('sha256').update(raw, 'utf8').digest('hex');
+}

package/src/vendor/common/observation.ts

@@ -0,0 +1,52 @@
+import crypto from 'node:crypto';
+import { ObserverSource, ObservationAttributionStatus } from './enums.js';
+
+export interface CanonicalObservation {
+  id: string;
+  receivingAccountId: string;
+  source: ObserverSource;
+  amountPaise: bigint;
+  observedAt: Date;
+  ingestedAt: Date;
+  senderVpa?: string;
+  bankReferenceNumber?: string;
+  fingerprintHash: string;
+  attributionStatus: ObservationAttributionStatus;
+  attributedPaymentId?: string;
+  rawPayload: Record<string, unknown>;
+}
+
+export interface IngestObservationInput {
+  receivingAccountId: string;
+  source: ObserverSource;
+  amountPaise: bigint;
+  observedAt: Date;
+  senderVpa?: string;
+  bankReferenceNumber?: string;
+  rawPayload?: Record<string, unknown>;
+}
+
+/**
+ * Calculates a deterministic fingerprint for an observation to prevent duplicate processing.
+ * If bankReferenceNumber exists, it hashes receivingAccount + amount + referenceNumber.
+ * Otherwise, it hashes receivingAccount + amount + 60-second time bucket.
+ */
+export function calculateObservationFingerprint(input: {
+  receivingAccountId: string;
+  amountPaise: bigint;
+  source?: string;
+  bankReferenceNumber?: string;
+  observedAt: Date;
+}): string {
+  let entropy: string;
+  if (input.bankReferenceNumber && input.bankReferenceNumber.trim().length > 0) {
+    entropy = `REF:${input.bankReferenceNumber.trim().toUpperCase()}`;
+  } else {
+    // 60-second temporal cluster bucket partitioned by channel source
+    const bucket = Math.floor(input.observedAt.getTime() / 60000);
+    entropy = `TIME_BUCKET:${bucket}:${input.source || ''}`;
+  }
+
+  const raw = `${input.receivingAccountId}:${input.amountPaise.toString()}:${entropy}`;
+  return crypto.createHash('sha256').update(raw, 'utf8').digest('hex');
+}

package/src/vendor/common/runtime-config.js

@@ -0,0 +1,246 @@
+/**
+ * Canonical Cloudflare Tunnel and Runtime URL Resolution Engine.
+ * Single source of truth for runtime mode, derived hostnames, and service mappings.
+ */
+
+export const SERVICE_PORTS = Object.freeze({
+  CHECKOUT: 7000,
+  API: 6100,
+  ADMIN: 6001,
+  GMAIL: 6003,
+  STORE: 5000
+});
+
+/**
+ * Derives public hostnames and Cloudflare published application mappings.
+ * @param {{ domain?: string, prefix?: string }} config
+ * @returns {Array<{
+ *   role: string,
+ *   name: string,
+ *   publicHostname: string,
+ *   publicUrl: string,
+ *   serviceUrl: string,
+ *   port: number,
+ *   purpose: string,
+ *   optional: boolean
+ * }>}
+ */
+export function deriveCloudflareRoutes(config = {}) {
+  const rawDomain = (config.domain || config.domainTld || '').trim().toLowerCase().replace(/^https?:\/\//, '').replace(/\/+$/, '');
+  const rawPrefix = (config.prefix || config.domainPrefix || 'pay').trim().toLowerCase().replace(/[^a-z0-9-_]/g, '') || 'pay';
+
+  if (!rawDomain) {
+    return [];
+  }
+
+  return [
+    {
+      role: 'checkout',
+      name: 'Checkout',
+      publicHostname: `${rawPrefix}.${rawDomain}`,
+      publicUrl: `https://${rawPrefix}.${rawDomain}`,
+      serviceUrl: `http://localhost:${SERVICE_PORTS.CHECKOUT}`,
+      port: SERVICE_PORTS.CHECKOUT,
+      purpose: 'Customer checkout / checkout portal',
+      optional: false
+    },
+    {
+      role: 'api',
+      name: 'Payment API',
+      publicHostname: `${rawPrefix}-api.${rawDomain}`,
+      publicUrl: `https://${rawPrefix}-api.${rawDomain}`,
+      serviceUrl: `http://localhost:${SERVICE_PORTS.API}`,
+      port: SERVICE_PORTS.API,
+      purpose: 'Payment API / merchant API / SSE / observer ingestion',
+      optional: false
+    },
+    {
+      role: 'admin',
+      name: 'Merchant Admin',
+      publicHostname: `${rawPrefix}-admin.${rawDomain}`,
+      publicUrl: `https://${rawPrefix}-admin.${rawDomain}`,
+      serviceUrl: `http://localhost:${SERVICE_PORTS.ADMIN}`,
+      port: SERVICE_PORTS.ADMIN,
+      purpose: 'Merchant/Admin panel',
+      optional: false
+    },
+    {
+      role: 'gmail',
+      name: 'Gmail OAuth / Gmail Observer',
+      publicHostname: `${rawPrefix}-gmail.${rawDomain}`,
+      publicUrl: `https://${rawPrefix}-gmail.${rawDomain}`,
+      serviceUrl: `http://localhost:${SERVICE_PORTS.GMAIL}`,
+      port: SERVICE_PORTS.GMAIL,
+      purpose: 'Gmail OAuth callback and Gmail observation service',
+      optional: false
+    },
+    {
+      role: 'store',
+      name: 'Demo Store',
+      publicHostname: `${rawPrefix}-store.${rawDomain}`,
+      publicUrl: `https://${rawPrefix}-store.${rawDomain}`,
+      serviceUrl: `http://localhost:${SERVICE_PORTS.STORE}`,
+      port: SERVICE_PORTS.STORE,
+      purpose: 'Reference/demo store',
+      optional: true
+    }
+  ];
+}
+
+/**
+ * Resolves authoritative runtime URLs for all system components.
+ * @param {{
+ *   envMode?: string,
+ *   domain?: string,
+ *   domainTld?: string,
+ *   prefix?: string,
+ *   domainPrefix?: string
+ * }} options
+ */
+export function resolveRuntimeUrls(options = {}) {
+  let mode = options.envMode;
+  if (!mode) {
+    if (process.env.ELPAY_MODE) {
+      mode = process.env.ELPAY_MODE;
+    } else if (process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test') {
+      mode = 'localhost';
+    } else if (process.env.CLOUDFLARE_DOMAIN) {
+      mode = 'production';
+    } else {
+      mode = 'localhost';
+    }
+  }
+  mode = String(mode).toLowerCase();
+  const domain = (options.domain || options.domainTld || process.env.CLOUDFLARE_DOMAIN || '').trim().toLowerCase().replace(/^https?:\/\//, '').replace(/\/+$/, '');
+  const prefix = (options.prefix || options.domainPrefix || process.env.DEPLOYMENT_PREFIX || 'pay').trim().toLowerCase().replace(/[^a-z0-9-_]/g, '') || 'pay';
+
+  if (mode === 'production') {
+    if (!domain) {
+      if ((process.env.NODE_ENV === 'test' || process.env.ELPAY_MODE === 'localhost') && options.envMode !== 'production') {
+        mode = 'localhost';
+      } else {
+        throw new Error('Production Configuration Incomplete: Cloudflare Domain is required when running in PRODUCTION mode.');
+      }
+    }
+  }
+
+  if (mode === 'production') {
+
+    const routes = deriveCloudflareRoutes({ domain, prefix });
+    const getRoute = (role) => routes.find(r => r.role === role);
+
+    return {
+      mode: 'production',
+      isProduction: true,
+      domain,
+      prefix,
+      routes,
+      checkoutUrl: getRoute('checkout')?.publicUrl || `https://${prefix}.${domain}`,
+      checkoutHostname: getRoute('checkout')?.publicHostname || `${prefix}.${domain}`,
+      apiUrl: getRoute('api')?.publicUrl || `https://${prefix}-api.${domain}`,
+      apiHostname: getRoute('api')?.publicHostname || `${prefix}-api.${domain}`,
+      adminUrl: getRoute('admin')?.publicUrl || `https://${prefix}-admin.${domain}`,
+      adminHostname: getRoute('admin')?.publicHostname || `${prefix}-admin.${domain}`,
+      gmailUrl: getRoute('gmail')?.publicUrl || `https://${prefix}-gmail.${domain}`,
+      gmailHostname: getRoute('gmail')?.publicHostname || `${prefix}-gmail.${domain}`,
+      storeUrl: getRoute('store')?.publicUrl || `https://${prefix}-store.${domain}`,
+      storeHostname: getRoute('store')?.publicHostname || `${prefix}-store.${domain}`
+    };
+  }
+
+  // Localhost / Development Mode
+  return {
+    mode: 'localhost',
+    isProduction: false,
+    domain: domain || 'localhost',
+    prefix: prefix || 'pay',
+    routes: [
+      { role: 'checkout', name: 'Checkout', publicHostname: 'localhost:7000', publicUrl: 'http://localhost:7000', serviceUrl: 'http://localhost:7000', port: 7000, purpose: 'Customer checkout / checkout portal', optional: false },
+      { role: 'api', name: 'Payment API', publicHostname: 'localhost:6100', publicUrl: 'http://localhost:6100', serviceUrl: 'http://localhost:6100', port: 6100, purpose: 'Payment API / merchant API / SSE / observer ingestion', optional: false },
+      { role: 'admin', name: 'Merchant Admin', publicHostname: 'localhost:6001', publicUrl: 'http://localhost:6001', serviceUrl: 'http://localhost:6001', port: 6001, purpose: 'Merchant/Admin panel', optional: false },
+      { role: 'gmail', name: 'Gmail OAuth / Gmail Observer', publicHostname: 'localhost:6003', publicUrl: 'http://localhost:6003', serviceUrl: 'http://localhost:6003', port: 6003, purpose: 'Gmail OAuth callback and Gmail observation service', optional: false },
+      { role: 'store', name: 'Demo Store', publicHostname: 'localhost:5000', publicUrl: 'http://localhost:5000', serviceUrl: 'http://localhost:5000', port: 5000, purpose: 'Reference/demo store', optional: true }
+    ],
+    checkoutUrl: 'http://localhost:7000',
+    checkoutHostname: 'localhost:7000',
+    apiUrl: 'http://localhost:6100',
+    apiHostname: 'localhost:6100',
+    adminUrl: 'http://localhost:6001',
+    adminHostname: 'localhost:6001',
+    gmailUrl: 'http://localhost:6003',
+    gmailHostname: 'localhost:6003',
+    storeUrl: 'http://localhost:5000',
+    storeHostname: 'localhost:5000'
+  };
+}
+
+/**
+ * Generates structured SMS Gateway QR pairing payload according to Part C1 & C2.
+ */
+export function createPairingPayload(options = {}) {
+  const {
+    serverUrl,
+    sessionId = `pair_sess_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`,
+    token = `tok_${Math.random().toString(36).substring(2, 12)}`,
+    merchantId = '00000000-0000-0000-0000-000000000001',
+    ttlMs = 10 * 60 * 1000 // 10 minutes default
+  } = options;
+
+  return {
+    version: 'v1',
+    type: 'ELPAY_SMS_GATEWAY_PAIR',
+    serverUrl: serverUrl || 'http://localhost:6100',
+    sessionId,
+    token,
+    merchantId,
+    expiresAt: Date.now() + ttlMs,
+    issuedAt: Date.now()
+  };
+}
+
+/**
+ * Validates pairing payload according to Part C5.
+ */
+export function validatePairingPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return { valid: false, error: 'INVALID ELPAY PAIRING QR' };
+  }
+  if (payload.type !== 'ELPAY_SMS_GATEWAY_PAIR') {
+    return { valid: false, error: 'INVALID ELPAY PAIRING QR' };
+  }
+  if (payload.version !== 'v1') {
+    return { valid: false, error: 'INVALID ELPAY PAIRING QR VERSION' };
+  }
+  if (!payload.serverUrl || !payload.token || !payload.sessionId) {
+    return { valid: false, error: 'MALFORMED ELPAY PAIRING QR: Missing required fields' };
+  }
+  if (!payload.serverUrl.startsWith('http://') && !payload.serverUrl.startsWith('https://')) {
+    return { valid: false, error: 'INVALID SERVER URL PROTOCOL' };
+  }
+  if (payload.expiresAt && Date.now() > payload.expiresAt) {
+    return { valid: false, error: 'PAIRING QR EXPIRED' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Resolves active runtime pairing API URL.
+ */
+export function resolvePairingUrl(options = {}) {
+  const urls = resolveRuntimeUrls(options);
+  return urls.apiUrl || 'http://localhost:6100';
+}
+
+/**
+ * OAuth redirect URI for the Gmail observer. `GMAIL_REDIRECT_URI` wins; otherwise it is derived
+ * from the configured domain, falling back to the local observer port.
+ * @param {object} [branding]
+ */
+export function resolveGmailRedirectUri(branding = {}) {
+  if (process.env.GMAIL_REDIRECT_URI) return process.env.GMAIL_REDIRECT_URI;
+  try {
+    return `${resolveRuntimeUrls(branding || {}).gmailUrl}/oauth/callback`;
+  } catch {
+    return `http://localhost:${process.env.GMAIL_OBSERVER_PORT || 6003}/oauth/callback`;
+  }
+}