zyro-gateway 1.0.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "zyro-gateway",
+  "version": "1.0.0",
+  "description": "Zyro Gateway — real-time phone ↔ desktop sync (Node server + browser client)",
+  "license": "MIT",
+  "author": "orod-codes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orod-codes/zyro-getway.git"
+  },
+  "homepage": "https://github.com/orod-codes/zyro-getway#readme",
+  "bugs": {
+    "url": "https://github.com/orod-codes/zyro-getway/issues"
+  },
+  "main": "dist/zyro.js",
+  "module": "zyro/zyro.js",
+  "browser": "dist/zyro.js",
+  "exports": {
+    ".": {
+      "import": "./zyro/zyro.js",
+      "require": "./dist/zyro.js",
+      "default": "./dist/zyro.js"
+    },
+    "./server": {
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./config.example": "./zyro.config.example.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "zyro",
+    "scripts",
+    "zyro.config.example.js",
+    "server.js",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js",
+    "build": "node scripts/build-zyro.js",
+    "config": "node scripts/init-config.js",
+    "prestart": "npm run build",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "bin": {
+    "zyro-gateway": "bin/zyro-gateway.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "zyro",
+    "zyro-gateway",
+    "socket.io",
+    "real-time",
+    "payment-sync",
+    "telebirr",
+    "ethiopia",
+    "flutter",
+    "sms-monitor"
+  ],
+  "dependencies": {
+    "express": "^4.21.2",
+    "socket.io": "^4.8.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  }
+}

package/scripts/build-zyro.js

@@ -0,0 +1,22 @@
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const entry = path.join(root, 'zyro', 'browser-entry.js');
+const outFile = path.join(root, 'dist', 'zyro.js');
+
+const esbuild = require('esbuild');
+
+fs.mkdirSync(path.dirname(outFile), { recursive: true });
+
+esbuild.buildSync({
+  entryPoints: [entry],
+  bundle: true,
+  format: 'iife',
+  globalName: 'Zyro',
+  outfile: outFile,
+  platform: 'browser',
+  target: ['es2020'],
+});
+
+console.log('Built', outFile);

package/scripts/init-config.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const example = path.join(root, 'zyro.config.example.js');
+const target = path.join(process.cwd(), 'zyro.config.js');
+
+if (fs.existsSync(target)) {
+  console.log('Already exists:', target);
+  process.exit(0);
+}
+
+if (!fs.existsSync(example)) {
+  console.error('Missing', example);
+  process.exit(1);
+}
+
+fs.copyFileSync(example, target);
+console.log('Created', target);
+console.log('Edit ip, port, pairingCode then run: npx zyro-gateway');

package/scripts/load-zyro-config.js

@@ -0,0 +1,4 @@
+'use strict';
+
+/** @deprecated Use require('zyro-gateway/src/config/load-config') or programmatic API */
+module.exports = require('../src/config/load-config');

package/server.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('./src/index').start();

package/src/config/load-config.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createRequire } = require('module');
+
+const DEFAULTS = {
+  ip: '',
+  port: 3000,
+  pairingCode: '',
+  deviceName: '',
+  autoConnect: true,
+  pollIntervalMs: 1500,
+};
+
+function resolveConfigPath(packageDir) {
+  if (process.env.ZYRO_CONFIG) {
+    return path.resolve(process.env.ZYRO_CONFIG);
+  }
+  const cwdFile = path.join(process.cwd(), 'zyro.config.js');
+  if (fs.existsSync(cwdFile)) return cwdFile;
+  const pkgFile = path.join(packageDir, 'zyro.config.js');
+  if (fs.existsSync(pkgFile)) return pkgFile;
+  return cwdFile;
+}
+
+function parseExportDefault(text) {
+  const out = { ...DEFAULTS };
+  const ipMatch = text.match(/ip:\s*['"]([^'"]*)['"]/);
+  const portMatch = text.match(/port:\s*(\d+)/);
+  const pairingMatch = text.match(/pairingCode:\s*['"]([^'"]+)['"]/);
+  const deviceMatch = text.match(/deviceName:\s*['"]([^'"]+)['"]/);
+  const autoMatch = text.match(/autoConnect:\s*(true|false)/);
+  const pollMatch = text.match(/pollIntervalMs:\s*(\d+)/);
+  if (ipMatch) out.ip = ipMatch[1].trim();
+  if (portMatch) out.port = Number(portMatch[1]);
+  if (pairingMatch) out.pairingCode = pairingMatch[1].trim();
+  if (deviceMatch) out.deviceName = deviceMatch[1].trim();
+  if (autoMatch) out.autoConnect = autoMatch[1] === 'true';
+  if (pollMatch) out.pollIntervalMs = Number(pollMatch[1]);
+  return out;
+}
+
+function loadZyroConfig(packageDir) {
+  const configPath = resolveConfigPath(packageDir);
+  if (!fs.existsSync(configPath)) {
+    return { ...DEFAULTS, configPath, loaded: false };
+  }
+
+  const text = fs.readFileSync(configPath, 'utf8');
+  let parsed = { ...DEFAULTS };
+
+  try {
+    if (/module\.exports\s*=/.test(text)) {
+      const req = createRequire(configPath);
+      const mod = req(configPath);
+      parsed = { ...DEFAULTS, ...(mod?.default || mod) };
+    } else {
+      parsed = parseExportDefault(text);
+    }
+  } catch (_) {
+    parsed = parseExportDefault(text);
+  }
+
+  return { ...parsed, configPath, loaded: true };
+}
+
+module.exports = { loadZyroConfig, resolveConfigPath, DEFAULTS };

package/src/config/pairing.js

@@ -0,0 +1,21 @@
+'use strict';
+
+function normalizePairing(raw) {
+  const p = String(raw || '')
+    .trim()
+    .toUpperCase()
+    .replace(/[^A-Z0-9]/g, '');
+  if (p.length < 4 || p.length > 12) return null;
+  return p;
+}
+
+function resolvePairing(req, fallback) {
+  return (
+    normalizePairing(req?.query?.pairing) ||
+    normalizePairing(req?.headers?.['x-pairing']) ||
+    normalizePairing(fallback) ||
+    null
+  );
+}
+
+module.exports = { normalizePairing, resolvePairing };

package/src/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const path = require('path');
+const { createGateway } = require('./server/create-gateway');
+
+function start(options = {}) {
+  const packageRoot = options.packageRoot || path.join(__dirname, '..');
+  const gateway = createGateway({ packageRoot });
+  return gateway.start(options.listen);
+}
+
+if (require.main === module) {
+  start().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+module.exports = { createGateway, start };

package/src/server/broadcast.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { getRoom, buildDashboardPayload } = require('./rooms');
+const { printIncome } = require('./terminal');
+const { touchHttpPhone } = require('./devices');
+
+function createBroadcaster(io) {
+  function broadcastIncome(roomKey, payload) {
+    const room = getRoom(roomKey);
+    const roomName = `pairing:${roomKey}`;
+    const tx = { ...payload, receivedAt: new Date().toISOString() };
+    room.transactions.unshift(tx);
+    if (room.transactions.length > 500) room.transactions.length = 500;
+    printIncome(roomKey, tx);
+    io.to(roomName).emit('income_transaction', tx);
+    io.to(roomName).emit('dashboard_update', buildDashboardPayload(room, roomKey));
+  }
+
+  function broadcastNotification(roomKey, payload) {
+    const room = getRoom(roomKey);
+    const roomName = `pairing:${roomKey}`;
+    const note = {
+      ...payload,
+      receivedAt: new Date().toISOString(),
+    };
+    if (!note.id) {
+      note.id = `n_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    }
+    room.notifications.unshift(note);
+    if (room.notifications.length > 200) room.notifications.length = 200;
+    io.to(roomName).emit('notification_event', note);
+    io.to(roomName).emit('dashboard_update', buildDashboardPayload(room, roomKey));
+  }
+
+  function bumpPhonePresence(roomKey, meta = {}) {
+    touchHttpPhone(io, roomKey, meta);
+  }
+
+  return { broadcastIncome, broadcastNotification, bumpPhonePresence };
+}
+
+module.exports = { createBroadcaster };

package/src/server/create-gateway.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const http = require('http');
+const path = require('path');
+const express = require('express');
+const { Server } = require('socket.io');
+const { loadZyroConfig } = require('../config/load-config');
+const { normalizePairing } = require('../config/pairing');
+const { getLocalIp } = require('../utils/network');
+const { createBroadcaster } = require('./broadcast');
+const { registerRoutes } = require('./routes');
+const { attachSocketHandlers } = require('./socket');
+const { printStartup } = require('./terminal');
+
+/**
+ * Create an Express + Socket.IO gateway instance (does not listen until `.start()`).
+ * @param {{ packageRoot?: string }} [options]
+ */
+function createGateway(options = {}) {
+  const packageRoot =
+    options.packageRoot || path.join(__dirname, '../..');
+  const zyroConfig = loadZyroConfig(packageRoot);
+  const configPath = zyroConfig.configPath;
+  const envPort = process.env.PORT ? Number(process.env.PORT) : null;
+  const port =
+    (Number.isFinite(envPort) && envPort > 0 ? envPort : null) ??
+    zyroConfig.port ??
+    3000;
+  const configPairing = normalizePairing(zyroConfig.pairingCode) || '';
+
+  function publicIp() {
+    return zyroConfig.ip || getLocalIp();
+  }
+
+  const app = express();
+  app.use(express.json({ limit: '256kb' }));
+  app.use((req, res, next) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Pairing');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    if (req.method === 'OPTIONS') return res.sendStatus(204);
+    next();
+  });
+  app.use(
+    '/zyro',
+    express.static(path.join(packageRoot, 'dist'), {
+      setHeaders(res, filePath) {
+        if (filePath.endsWith('.js')) {
+          res.setHeader('Cache-Control', 'no-store');
+        }
+      },
+    }),
+  );
+
+  const server = http.createServer(app);
+  const io = new Server(server, {
+    cors: { origin: '*' },
+    transports: ['polling', 'websocket'],
+    pingTimeout: 120000,
+    pingInterval: 25000,
+    connectTimeout: 60000,
+    allowEIO3: true,
+  });
+
+  const broadcaster = createBroadcaster(io);
+  const ctx = {
+    packageRoot,
+    zyroConfig,
+    configPath,
+    port,
+    configPairing,
+    publicIp,
+    io,
+    broadcaster,
+  };
+
+  registerRoutes(app, ctx);
+  attachSocketHandlers(io, ctx);
+
+  return {
+    app,
+    server,
+    io,
+    config: zyroConfig,
+    port,
+    pairingCode: configPairing,
+    publicIp,
+    /**
+     * @param {{ host?: string }} [listenOptions]
+     * @returns {Promise<{ url: string, port: number, pairingCode: string }>}
+     */
+    start(listenOptions = {}) {
+      const host = listenOptions.host ?? '0.0.0.0';
+      return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => {
+          server.removeListener('error', reject);
+          const ip = publicIp();
+          printStartup({
+            configPath,
+            configLoaded: zyroConfig.loaded,
+            pairing: configPairing,
+            ip,
+            port,
+          });
+          resolve({
+            url: `http://${ip}:${port}`,
+            port,
+            pairingCode: configPairing,
+          });
+        });
+      });
+    },
+    stop() {
+      return new Promise((resolve, reject) => {
+        io.close();
+        server.close((err) => (err ? reject(err) : resolve()));
+      });
+    },
+  };
+}
+
+module.exports = { createGateway };

package/src/server/devices.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { getRoom, listDevices, presencePayload } = require('./rooms');
+const { printConnectedDevices } = require('./terminal');
+
+function defaultDeviceName(role) {
+  if (role === 'desktop') return 'Web Dashboard';
+  return 'Zyro Phone';
+}
+
+function upsertDevice(room, socket, meta = {}) {
+  const device = {
+    id: socket.id,
+    role: socket.data.role || 'phone',
+    deviceName:
+      meta.deviceName || meta.name || defaultDeviceName(socket.data.role),
+    platform: meta.platform || 'unknown',
+    connectedAt: meta.connectedAt || new Date().toISOString(),
+    lastSeen: new Date().toISOString(),
+    online: true,
+  };
+  room.deviceMap.set(socket.id, device);
+  return device;
+}
+
+function touchHttpPhone(io, roomKey, meta = {}) {
+  const room = getRoom(roomKey);
+  const stableId = String(meta.deviceId || 'phone').replace(/[^a-zA-Z0-9_-]/g, '');
+  const id = `http:${roomKey}:${stableId}`;
+  const prev = room.deviceMap.get(id);
+  const device = {
+    id,
+    role: 'phone',
+    deviceName: meta.deviceName || prev?.deviceName || 'Zyro Phone',
+    platform: meta.platform || 'android',
+    connectedAt: prev?.connectedAt || new Date().toISOString(),
+    lastSeen: new Date().toISOString(),
+    online: true,
+    via: 'http',
+  };
+  room.deviceMap.set(id, device);
+  const roomName = `pairing:${roomKey}`;
+  io.to(roomName).emit('presence', presencePayload(room));
+  io.to(roomName).emit('device_joined', device);
+  printConnectedDevices(roomKey, listDevices(room));
+  return device;
+}
+
+module.exports = { defaultDeviceName, upsertDevice, touchHttpPhone };

package/src/server/rooms.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/** @type {Map<string, object>} */
+const rooms = new Map();
+
+function getRoom(pairing) {
+  const key = pairing.toUpperCase();
+  if (!rooms.has(key)) {
+    rooms.set(key, {
+      phones: 0,
+      desktops: 0,
+      transactions: [],
+      notifications: [],
+      deviceMap: new Map(),
+    });
+  }
+  return rooms.get(key);
+}
+
+function listDevices(room) {
+  return Array.from(room.deviceMap.values()).sort(
+    (a, b) => new Date(b.connectedAt) - new Date(a.connectedAt),
+  );
+}
+
+function presencePayload(room) {
+  const devices = listDevices(room);
+  return {
+    phones: devices.filter((d) => d.role === 'phone').length,
+    desktops: devices.filter((d) => d.role === 'desktop').length,
+    devices,
+  };
+}
+
+function buildDashboardPayload(room, roomKey) {
+  const start = new Date();
+  start.setHours(0, 0, 0, 0);
+  const todayTx = room.transactions.filter((tx) => {
+    const t = new Date(tx.timestamp || tx.receivedAt);
+    return t >= start;
+  });
+  const todayTotal = todayTx.reduce(
+    (sum, tx) => sum + (Number(tx.amount) || 0),
+    0,
+  );
+  const matchedNotes = room.notifications.filter((n) => n.matched).length;
+  const devices = listDevices(room);
+
+  return {
+    serverTime: new Date().toISOString(),
+    pairingCode: roomKey,
+    stats: {
+      todayTotal,
+      transactionCount: room.transactions.length,
+      todayTransactionCount: todayTx.length,
+      notificationCount: room.notifications.length,
+      matchedNotificationCount: matchedNotes,
+      phones: devices.filter((d) => d.role === 'phone').length,
+      desktops: devices.filter((d) => d.role === 'desktop').length,
+    },
+    recentTransactions: room.transactions.slice(0, 8),
+    recentNotifications: room.notifications.slice(0, 8),
+  };
+}
+
+module.exports = {
+  getRoom,
+  listDevices,
+  presencePayload,
+  buildDashboardPayload,
+};