EVS Meter Tools

EVS Meter Tools

A Telegram bot and web app for supported EVS electricity meters. Supported NUS and SUTD meters can be topped up by credit card, and supported lookup flows show balance, usage, and top-up history where available.

Supported systems

The legacy NUS CP2 fallback (cp2.evs.com.sg) is hidden from the web app and bot. Its backend routes and services are kept but are not linked from any UI; see CP2 — legacy NUS fallback (hidden).

Features

• Check meter balance, 7-day usage history, and recent top-ups from within Telegram
• Top up supported NUS electricity meters via credit card (SGD $6-$50)
• Top up supported SUTD electricity meters via credit card (SGD $10-$50)
• RSA-encrypted card entry — card details never leave the browser in plaintext
• Works as a Telegram Mini App and as a standalone website
• Cross-system guard: cp2nus bootstrap rejects meters that belong to the legacy cp2 system before initiating payment
• SUTD balance, top-up history, and top-up support
• Analytics tracking and error capture throughout the flow
• Opt-in low-balance alerts on Telegram, with a button to start a top-up
• Read-only MCP server, so people can connect their own Claude and set their own instructions

Architecture

Telegram Bot (telegraf)          Website (React, /app/)

│ │ ├── /topup └── HomePage ├── /balance └── system selection ├── /usage + meter ID + amount └── /topups │ webhook in production/Railway, │ │ polling in development │ ▼ ▼ Express (server.js) ←──────────────────────────── │ ├── POST /telegram/webhook/* — Telegram webhook receivers ├── GET /webapp — legacy CP2 (hidden from UI): fetches meter summary, redirects to React ├── GET /webapp/bootstrap — runs full payment init, returns token ├── GET /webapp/session — returns session data as JSON for React ├── GET /webapp/pay — redirects to React card entry page ├── POST /webapp/enets_pay — proxies encrypted card data to eNETS ├── POST /webapp/notify — fallback Telegram payment notification └── GET /webapp/result — redirects to React result page

React Frontend (/app/) ├── / — HomePage (system + meter ID + amount) ├── /balance — HomePage opened in balance-check mode ├── /cp2nus — HomePage preselected for primary NUS CP2NUS flow ├── /cp2nus/loading — cp2nus variant ├── /cp2nus/pay — cp2nus variant ├── /cp2nus/result — cp2nus variant ├── /sutd/loading — SUTD variant ├── /sutd/pay — SUTD variant └── /sutd/result — SUTD variant

Payment flows

CP2 — legacy NUS fallback (hidden)

Hidden. This flow is no longer offered in the web app or bot. The /app/cp2, /app/loading, /app/pay, and /app/result React routes are commented out in frontend/src/App.jsx, /app/cp2 is excluded from the sitemap and robots.txt, and the bot no longer shows a hostel picker. The backend routes and services below are kept for reference and possible reinstatement.

Scrapes the legacy EVS WebPOS portal to create a transaction, then proxies through eNETS. It was used only for NUS meters that had not migrated to CP2NUS.

1. `/webapp` — fetches meter address and balance from ORE, redirects to React loading page with address/balance in query params
2. Bootstrap (/webapp/bootstrap) — runs runPurchaseFlow and getMeterSummary in parallel:

• GET /EVSWebPOS/ → login → POST /loginServlet (meter validation)
• POST /selectOfferServlet (amount selection)
• GET /paymentServlet → extract merchant_txn_ref
• POST creditpayment.jsp → extract eNETS message
• POST /enets2/PaymentListener.do → extract RSA public key (n, e), netsMid, netsTxnRef
• Creates a payment session (10-min TTL), redirects to React card page

1. Card page (/app/pay) — React component; fetches session via /webapp/session; encrypts cardNo + cvv with eNETS RSA scripts client-side
2. Payment proxy (/webapp/enets_pay):

• POST https://www.enets.sg/GW2/uCredit/pay
• Preferred path: extracts EVS callback form → POST /EVSWebPOS/transSumServlet → parseEvsTransactionSummary
• Fallback: parseEnetsResult scrapes the eNETS receipt HTML directly
• Writes outcome (status, merchantTxnRef, reason) back to the server-side session

1. Result page (/app/result) — React component; reads outcome from server session via /webapp/session

CP2NUS — primary NUS hostel flow

Uses the EVS JSON API and the eNETS Payment Page (enetspp) host directly. This is the primary NUS hostel flow for migrated meters.

1. `/webapp` — same as cp2; fetches meter info, redirects to /app/cp2nus/loading
2. Bootstrap (/cp2nus/webapp/bootstrap) — runBootstrap runs sequentially:

• Meter system check — isCp2Meter() guard: rejects cp2 meters with a WRONG_SYSTEM error; on network failure the check is skipped and flow proceeds
• `init_pay` — POST /enets/init_pay → { txn_identifier, req, sign }
• `meter_info` — getMeterSummary → buildPayDisplayAddress
• `enetspp_pay` — buildEnetsPayUrl → GET enetspp/pay?p=… → extract txnReq, keyId, hmac
• `TxnReqListener` — POST /GW2/TxnReqListener → RSA key, netsTxnRef, netsMid, paymtNetsMid, txnRand, keyId, hmac

1. Card page (/app/cp2nus/pay) — same RSA encryption; paymtNetsMid (acquiring MID) used in panSubmitForm, not top-level netsMid
2. Payment proxy (/cp2nus/webapp/enets_pay):

• GET /GW2/pluginpages/env.jsp → seed JSESSIONID
• POST /GW2/credit/init;jsessionid=…
• POST /GW2/credit/panSubmitForm
• Preferred path: netsTxnStatus in response → preParsed result (no b2s call)
• Fallback: POST /enets/b2s → 303 redirect → parsePayResult base64-decodes params

1. Result page (/app/cp2nus/result) — reads outcome from server session

SUTD

Uses the SUTD EVS WebPOS pages and the SUTD credit payment bridge.

1. `/sutd/webapp` — fetches SUTD meter credit, redirects to /app/sutd/loading
2. Bootstrap (/sutd/webapp/bootstrap) — runs the SUTD WebPOS flow:

• POST /EVSSUTDWebPOS/loginServlet with the meter ID
• POST /EVSSUTDWebPOS/selectOfferServlet with the selected amount
• GET /EVSSUTDWebPOS/paymentServlet → extract merchant_txn_ref
• POST http://120.50.44.233/payment_sutd_credit/creditpayment.jsp
• POST /enets2/PaymentListener.do → extract RSA public key, netsMid, netsTxnRef

1. Card page (/app/sutd/pay) — same RSA-encrypted card entry as NUS flows
2. Payment proxy (/sutd/webapp/enets_pay) — posts encrypted card data to eNETS, then posts the callback to /EVSSUTDWebPOS/transSumServlet
3. Result page (/app/sutd/result) — reads outcome from server session

Setup

Prerequisites

• Node.js 20.19+ (22.12+ on Node 22)
• A Telegram bot token (from @BotFather)
• A publicly accessible HTTPS server (required for Telegram WebApp buttons)

Installation

# Install backend dependencies

npm install

Install and build the frontend

npm run build:frontend

Environment variables

Create a .env file:

TELEGRAM_BOT_TOKEN=your_bot_token_here      # legacy single-bot token

NUS_TELEGRAM_BOT_TOKEN=your_nus_bot_token # optional, for concurrent nusairconbot SUTD_TELEGRAM_BOT_TOKEN=your_sutd_bot_token # optional, for concurrent sutdairconbot PAYMENT_SESSION_SECRET=replace_with_openssl_rand_hex_32 # stable secret for signed payment/result tokens SERVER_URL=https://your-public-server.example.com OWNER_CHAT_ID=your_telegram_chat_id # receives feedback notifications MAINTENANCE_MODE=false # set to "true" to put the app and bot in global maintenance mode MAINTENANCE_MESSAGE= # optional custom global maintenance message OWNER_STATUS_TIMEOUT_MS=4000 # optional timeout for owner /status EVS/eNETS checks TOPUP_DISABLED=false # set to "true" to show maintenance message DB_DIR=. # local SQLite dir; use /data on Railway with a mounted volume TELEGRAM_BOT_MODE= # production/Railway defaults to webhook; dev defaults to polling TELEGRAM_BOT_AUDIENCE=nus # legacy single-bot mode: "nus" or "sutd" LOW_BALANCE_CRON_SECRET= # optional, enables the low-balance check endpoint MCP_ALLOWED_ORIGINS= # optional, comma-separated extra browser origins allowed to call /mcp GOOGLE_SITE_VERIFICATION_FILE= # optional Search Console HTML file name, e.g. googleabc123.html GOOGLE_SITE_VERIFICATION_CONTENT= # optional exact file body if Google provides non-default content

SERVER_URL must be HTTPS for the Telegram WebApp payment button to work. If it is HTTP, the bot falls back to a plain browser link instead. On Railway, set it to https://${{RAILWAY_PUBLIC_DOMAIN}} or leave it unset and the app will derive it from RAILWAY_PUBLIC_DOMAIN.

PAYMENT_SESSION_SECRET should be a stable random value, for example from openssl rand -hex 32. If it is omitted, the app falls back to the configured bot token, which still survives Railway sleeps as long as the bot token does not change.

For Google Search Console URL-prefix verification, use the HTML file method and set GOOGLE_SITE_VERIFICATION_FILE to the downloaded file name. The default response body is google-site-verification: . If Google's downloaded file contains different text, set GOOGLE_SITE_VERIFICATION_CONTENT to the exact file body.

In production, or when RAILWAY_PUBLIC_DOMAIN is present, each configured bot uses a Telegram webhook by default so Railway Serverless can sleep and wake from inbound Telegram requests. Set TELEGRAM_BOT_MODE=polling only for an always-on deployment. Optional webhook variables are TELEGRAM_WEBHOOK_PATH, TELEGRAM_WEBHOOK_SECRET, and TELEGRAM_DROP_PENDING_UPDATES for single-bot mode. For concurrent bots, use NUS_TELEGRAM_WEBHOOK_PATH, NUS_TELEGRAM_WEBHOOK_SECRET, SUTD_TELEGRAM_WEBHOOK_PATH, and SUTD_TELEGRAM_WEBHOOK_SECRET only if you need custom paths; otherwise unique paths are generated automatically.

For concurrent Telegram bots in one deployment, set both NUS_TELEGRAM_BOT_TOKEN and SUTD_TELEGRAM_BOT_TOKEN. The same service starts both nusairconbot and sutdairconbot, with separate command menus, webhook paths, in-memory sessions, and payment notifications. Single-bot deployments can still use TELEGRAM_BOT_TOKEN plus TELEGRAM_BOT_AUDIENCE.

Running

# Development (two terminals)

npm run dev # Express backend on :3000 npm run dev:frontend # Vite dev server on :5173

Production

npm run build:frontend npm start

The frontend is served at /app/ by Express in production. In development, Vite proxies /webapp, /cp2nus, and /sutd to the backend.

For local development, keep DB_DIR=. or omit it. On Railway, set DB_DIR=/data only after attachi