@zelthr/topup

A thin, dependency-light Node.js client for the zelthrStudio Open API gateway — TrueMoney gift-code redemption and Thai bank-slip verification, served from https://api.zelthr.rest.

The package does no local work: every call is forwarded to the gateway, which talks to the TrueMoney core and runs the full slip OCR pipeline itself. No image scanning, no QR parsing, no native binaries — just two clean API calls.

Endpoints

Both services share the gateway's single unified verification endpoint (POST /); the gateway auto-detects which service to run from the request body.

| Function | Request body | Purpose | | --- | --- | --- | | truemoney(code, phone, options?) | { gift, phone } | Check / redeem a TrueMoney voucher code | | bank(data, options?) | { img } | Verify a Thai bank transfer slip from an image |

Requirements

• Node.js >= 20.9

Installation

npm install @zelthr/topup

No install scripts, no native binaries, no model files — installs on any platform in seconds.

Quick Start

TrueMoney voucher redemption

const { truemoney } = require('@zelthr/topup');

// Redeem a gift code to a 10-digit Thai mobile number
// Automatically normalizes '081-234-5678', '+66812345678', ' 081 234 5678 ', etc.
const res = await truemoney('ABCD1234EFGH', '0812345678');

// Gift URLs work too, and you can verify the redeemed amount
const res2 = await truemoney('https://gift.truemoney.com/campaign/?v=XXXX', '+66812345678', { amount: 100 });
// throws AmountMismatchError if the code redeemed a different amount

Bank slip verification

const { bank } = require('@zelthr/topup');
const fs = require('node:fs');

// Pass a Buffer directly from fs.readFileSync:
const res = await bank(fs.readFileSync('slip.jpg'));
// { success: true, amount: 80, ... } — the verified slip result

// Or pass a base64 string / data URI:
const res2 = await bank('data:image/jpeg;base64,...');

// Optional amount verification:
const res3 = await bank(fs.readFileSync('slip.jpg'), { amount: 80 });
// throws AmountMismatchError if the verified slip amount differs

Bare base64 strings, Buffer, Uint8Array, and ArrayBuffer are handled automatically.

API

truemoney(codeOrLink, phone, options?)

Redeems a TrueMoney voucher via the unified endpoint (POST /).

| arg | type | description | | --- | --- | --- | | codeOrLink | string | Gift code (e.g. ABCD1234EFGH) or full gift URL. | | phone | string | Optional. Thai mobile number (08x..., +668x..., 08x-xxx-xxxx); formatting and whitespace are normalized automatically. If omitted, the server's configured wallet number is used. | | options.amount | number | Optional. If set, the redeemed amount is compared against it and a mismatch throws AmountMismatchError (slug === 'amount-mismatch'). | | options.timeoutMs | number | Optional request deadline in milliseconds (default: 30000). | | options.baseUrl | string | Optional base URL override (default: https://api.zelthr.rest). | | options.headers | object | Optional custom headers. |

Under the hood:

POST https://api.zelthr.rest/
{ "gift": "ABCD1234EFGH", "phone": "0812345678" }

Returns the gateway JSON response (the upstream redeem result as-is). A non-existent voucher is a normal 200 with status.code === 'VOUCHER_NOT_FOUND' — HTTP 4xx/5xx means the request itself was rejected or the upstream failed.

bank(data, options?)

Verifies a Thai bank transfer slip via the unified endpoint (POST /). The gateway decodes the QR, extracts the amount and verifies it upstream.

| arg | type | description | | --- | --- | --- | | data | string \| Buffer \| Uint8Array \| ArrayBuffer | Slip image as a Buffer, Uint8Array, ArrayBuffer, base64 string, or data: URI. | | options.amount | number | Optional expected amount (baht). Throws AmountMismatchError if verified slip amount does not match. | | options.timeoutMs | number | Optional request deadline in milliseconds (default: 30000). | | options.baseUrl | string | Optional base URL override (default: https://api.zelthr.rest). | | options.headers | object | Optional custom headers. |

Under the hood:

POST https://api.zelthr.rest/
{ "img": "data:image/jpeg;base64,/9j/4AAQ..." }

Returns the upstream verified-slip result as-is. Throws ValidationError on empty input or oversized payloads, and HttpError on gateway failures (e.g. 400 invalid-image, 422 qr-not-found, 429 rate-limit-exceeded, 502 upstream-error).

Low-level helpers

• post(url, body?, options?) — shared POST helper used by both clients (JSON body, 30 s deadline, 32 MiB body cap, redirects disabled).
• TMN_BASE / SLIP_BASE — gateway base URL constants (https://api.zelthr.rest), overridable via env vars below.

Error handling

All errors extend a common base and are exported:

| Error | Meaning | | --- | --- | | TopupError | Base class — catch this for broad handling. | | ValidationError | Invalid caller input (empty code, bad phone, invalid image, ...). | | TimeoutError | Request exceeded its deadline (30 s default). | | HttpError | Non-2xx or transport failure, with .status, .slug, .body. | | AmountMismatchError | Extends HttpError; the code redeemed a different amount than expected (slug === 'amount-mismatch'). | | AmountVerificationError | Extends HttpError; amount verification was requested but no amount could be extracted from the response. |

const { truemoney, AmountMismatchError } = require('@zelthr/topup');

try {
  await truemoney(code, phone, { amount: 100 });
} catch (err) {
  if (err instanceof AmountMismatchError) {
    console.error(`redeemed ${err.body ? JSON.stringify(err.body) : '?'} instead of 100 THB`);
  }
}

Rate limits

The gateway enforces per-IP limits — tmn: 200/min, slip: 100/min — and returns 429 with a Retry-After header when exceeded, surfaced as an HttpError with slug === 'rate-limit-exceeded'.

Environment variables

| var | effect | | --- | --- | | TMN_API_URL | Override the gateway base URL for truemoney() (default https://api.zelthr.rest). | | SLIP_API_URL | Override the gateway base URL for bank() (default https://api.zelthr.rest). |

Security

• Gift codes, phone numbers and slip images travel in the JSON body over TLS only — redirects are disabled and ambient proxies (HTTP_PROXY/HTTPS_PROXY) are explicitly ignored, so a 307/308 can never re-POST your data to another host.
• Error messages redact the request URL and cap server-controlled text; oversized error bodies are truncated to a 64 KB preview.

License

MIT