@laranex/myanmar-payments 0.0.0-stage → 4.0.0-dev.0

package/dist/esm/yoma-mmqr/yoma-mmqr.js

@@ -0,0 +1,229 @@
+import {} from '../core/amount.js';
+import { MemoryTokenCache } from '../core/cache.js';
+import { CallbackRequest, losslessBody, PaymentCallback, PaymentStatusResult, } from '../core/callback.js';
+import { hmacSha256Hex, safeEqual, sha256Hex } from '../core/crypto.js';
+import { defaultEnv, envFirst, envSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
+import { ApiError, SignatureVerificationError } from '../core/errors.js';
+import { httpClientFrom, Transport, } from '../core/http.js';
+import { toPlainObject } from '../core/json.js';
+import { QrPayment } from '../core/results.js';
+import { resolveStatus } from '../core/status.js';
+import { toAmount, Validator } from '../core/validate.js';
+import { get, optional, trimmed } from '../core/values.js';
+/**
+ * Yoma MMQR credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ */
+export class YomaMmqrConfig {
+    static SANDBOX_URL = 'https://devapi.yomabank.net';
+    static PRODUCTION_URL = 'https://paymenthubapi.yomabank.com';
+    static DEFAULT_API_VERSION = 'v1rc';
+    merchantId;
+    clientId;
+    clientSecret;
+    webhookHashKey;
+    webhookSecret;
+    sandbox;
+    /** The base URL in use. */
+    baseUrl;
+    /** The API version in use. */
+    apiVersion;
+    constructor(options) {
+        this.merchantId = requireSetting('yoma_mmqr', 'merchant_id', options.merchantId);
+        this.clientId = requireSetting('yoma_mmqr', 'client_id', options.clientId);
+        this.clientSecret = requireSetting('yoma_mmqr', 'client_secret', options.clientSecret);
+        this.webhookHashKey = requireSetting('yoma_mmqr', 'webhook_hashkey', options.webhookHashKey);
+        this.webhookSecret = optionalSetting(options.webhookSecret);
+        this.sandbox = options.sandbox ?? true;
+        this.baseUrl = trimUrl(optionalSetting(options.baseUrl) ??
+            (this.sandbox ? YomaMmqrConfig.SANDBOX_URL : YomaMmqrConfig.PRODUCTION_URL));
+        this.apiVersion = optionalSetting(options.apiVersion) ?? YomaMmqrConfig.DEFAULT_API_VERSION;
+    }
+    /**
+     * Reads `YOMA_MMQR_MERCHANT_ID`, `YOMA_MMQR_CLIENT_ID`, `YOMA_MMQR_CLIENT_SECRET`,
+     * `YOMA_MMQR_WEBHOOK_HASHKEY`, `YOMA_MMQR_WEBHOOK_SECRET`, `YOMA_MMQR_SANDBOX`,
+     * `YOMA_MMQR_BASE_URL` and `YOMA_MMQR_API_VERSION`.
+     */
+    static fromEnv(env = defaultEnv()) {
+        return new YomaMmqrConfig({
+            merchantId: envFirst(env, 'YOMA_MMQR_MERCHANT_ID'),
+            clientId: envFirst(env, 'YOMA_MMQR_CLIENT_ID'),
+            clientSecret: envFirst(env, 'YOMA_MMQR_CLIENT_SECRET'),
+            webhookHashKey: envFirst(env, 'YOMA_MMQR_WEBHOOK_HASHKEY'),
+            webhookSecret: envFirst(env, 'YOMA_MMQR_WEBHOOK_SECRET'),
+            sandbox: envSandbox(env, 'YOMA_MMQR_SANDBOX'),
+            baseUrl: envFirst(env, 'YOMA_MMQR_BASE_URL'),
+            apiVersion: envFirst(env, 'YOMA_MMQR_API_VERSION'),
+        });
+    }
+}
+const STATUSES = {
+    SUCCESS: 'successful',
+    PENDING: 'pending',
+    FAILED: 'failed',
+    FAIL: 'failed',
+};
+/**
+ * Yoma Bank MMQR: QR payments, status checks and callbacks. Access tokens are cached in a
+ * {@link TokenCache}; share the gateway (or pass a shared cache) so they survive between calls.
+ */
+export class YomaMmqr {
+    /** How long a generated QR stays payable, in seconds. */
+    static QR_LIFETIME_SECONDS = 120;
+    /** The configuration in use. */
+    config;
+    transport;
+    cache;
+    pendingToken;
+    constructor(config, options = {}) {
+        this.config = config instanceof YomaMmqrConfig ? config : new YomaMmqrConfig(config);
+        this.transport = new Transport(httpClientFrom(options));
+        this.cache = options.tokenCache ?? new MemoryTokenCache();
+    }
+    /** A gateway configured from the `YOMA_MMQR_*` environment variables. */
+    static fromEnv(env = defaultEnv(), options = {}) {
+        return new YomaMmqr(YomaMmqrConfig.fromEnv(env), options);
+    }
+    /** Checks the order against Yoma's documented limits; throws an `InvalidPaymentDataError`. */
+    static validate(data) {
+        new Validator()
+            .required('orderId', data.orderId)
+            .max('orderId', data.orderId, 20)
+            .amount('amount', data.amount, { gateway: 'Yoma MMQR', maxDecimals: 0 })
+            .required('description', data.description)
+            .max('description', data.description, 50)
+            .validate();
+    }
+    /** Checks the order out with Yoma and generates its first QR. Call it once per order. */
+    async initiate(data, options = {}) {
+        YomaMmqr.validate(data);
+        const body = await this.call('payment/checkout', {
+            merchantId: this.config.merchantId,
+            orderNumber: data.orderId,
+            amount: String(toAmount(data.amount)),
+            description: data.description,
+        }, [], options.signal);
+        if (body.checkOutStatus !== true) {
+            throw new ApiError('Yoma MMQR did not confirm the checkout.', { raw: toPlainObject(body) });
+        }
+        return this.renewQr(data.orderId, options);
+    }
+    /**
+     * Generates a new QR for an order that is already checked out, e.g. after the previous one
+     * expired. The previous QR's reference stops working.
+     */
+    async renewQr(orderId, options = {}) {
+        const body = await this.call('qr/generate', { merchantId: this.config.merchantId, orderNumber: orderId }, [], options.signal);
+        const qrString = get(body, 'qrString');
+        const reference = get(body, 'refLabel');
+        if (qrString === '' || reference === '') {
+            throw new ApiError('Yoma MMQR did not return a QR.', { raw: toPlainObject(body) });
+        }
+        return new QrPayment({
+            orderId,
+            qrImage: qrString,
+            expiresAt: new Date(Date.now() + YomaMmqr.QR_LIFETIME_SECONDS * 1000),
+            reference,
+            raw: toPlainObject(body),
+        });
+    }
+    /** Checks a QR's payment status by its reference (`QrPayment.reference`). An expired QR reports `expired`. */
+    async status(reference, options = {}) {
+        const body = await this.call('payment/check-status', { merchantId: this.config.merchantId, refLabel: reference }, ['QR EXPIRED'], options.signal);
+        if (get(body, 'errorCode') === 'QR EXPIRED') {
+            return new PaymentStatusResult({
+                status: 'expired',
+                gatewayStatus: 'QR EXPIRED',
+                gatewayReference: reference,
+                raw: toPlainObject(body),
+            });
+        }
+        const paymentStatus = trimmed(body, 'paymentStatus');
+        return new PaymentStatusResult({
+            status: resolveStatus(STATUSES, paymentStatus.toUpperCase()),
+            gatewayStatus: paymentStatus,
+            gatewayReference: get(body, 'refLabel') || reference,
+            raw: toPlainObject(body),
+        });
+    }
+    /**
+     * Verifies Yoma's payment callback: HMAC-SHA256 of `orderNumber=..&status=..` keyed with the
+     * order number followed by the webhook hash key.
+     */
+    handleCallback(request) {
+        const payload = losslessBody(request);
+        if (this.config.webhookSecret !== undefined &&
+            !safeEqual(this.config.webhookSecret, request.header('X-Webhook-Secret') ?? '')) {
+            throw new SignatureVerificationError('Yoma MMQR callback has a missing or wrong X-Webhook-Secret header.', toPlainObject(payload));
+        }
+        const orderNumber = get(payload, 'orderNumber');
+        const status = trimmed(payload, 'status');
+        const expected = hmacSha256Hex(orderNumber + this.config.webhookHashKey, `orderNumber=${orderNumber}&status=${status}`);
+        if (orderNumber === '' || !safeEqual(expected, get(payload, 'hashValue').toLowerCase())) {
+            throw new SignatureVerificationError('Yoma MMQR callback hash verification failed.', toPlainObject(payload));
+        }
+        return new PaymentCallback({
+            orderId: orderNumber,
+            status: resolveStatus(STATUSES, status.toUpperCase()),
+            gatewayStatus: status,
+            raw: toPlainObject(payload),
+        });
+    }
+    /** Drops the cached access token, e.g. after rotating the client secret. */
+    async forgetToken() {
+        await this.cache.delete(this.tokenCacheKey());
+    }
+    async call(path, data, allowedErrors, signal) {
+        const url = `${this.config.baseUrl}/payment-gateway/${this.config.apiVersion}/api/${path}`;
+        const send = async () => this.transport.postJson(url, data, { Authorization: `Bearer ${await this.token()}` }, signal);
+        let response = await send();
+        if (response.status === 401) {
+            await this.forgetToken();
+            response = await send();
+        }
+        const body = response.json();
+        const errorCode = get(body, 'errorCode');
+        if (!response.successful() || (errorCode !== '' && !allowedErrors.includes(errorCode))) {
+            throw apiError(path, response.status, body, errorCode);
+        }
+        return body;
+    }
+    async token() {
+        const cached = await this.cache.get(this.tokenCacheKey());
+        if (typeof cached === 'string' && cached !== '') {
+            return cached;
+        }
+        // Concurrent calls share one token request; it ignores any one caller's signal so aborting
+        // that caller does not fail the others (the client timeout still applies).
+        this.pendingToken ??= this.fetchToken().finally(() => {
+            this.pendingToken = undefined;
+        });
+        return this.pendingToken;
+    }
+    async fetchToken() {
+        const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
+        const response = await this.transport.postForm(`${this.config.baseUrl}/token`, { grant_type: 'client_credentials' }, { Authorization: `Basic ${credentials}` });
+        const body = response.json();
+        const token = get(body, 'access_token');
+        if (!response.successful() || token === '') {
+            throw apiError('token', response.status, body, get(body, 'error'));
+        }
+        const expiresIn = Number.parseInt(get(body, 'expires_in'), 10);
+        const ttl = Math.max(60, (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 3600) - 60);
+        await this.cache.set(this.tokenCacheKey(), token, ttl);
+        return token;
+    }
+    tokenCacheKey() {
+        return `node-myanmar-payments.yoma-mmqr.token.${sha256Hex(`${this.config.baseUrl}|${this.config.clientId}`)}`;
+    }
+}
+function apiError(endpoint, status, body, errorCode) {
+    const message = optional(body, 'errorDescription') || optional(body, 'error_description');
+    return new ApiError(errorCode
+        ? `Yoma MMQR ${endpoint} failed: [${errorCode}] ${message ?? ''}`.trimEnd()
+        : `Yoma MMQR ${endpoint} failed with HTTP ${status}.`, {
+        gatewayCode: errorCode || undefined,
+        gatewayMessage: message || undefined,
+        httpStatus: status,
+        raw: toPlainObject(body),
+    });
+}

package/package.json

@@ -1,6 +1,153 @@
 {
   "name": "@laranex/myanmar-payments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0-dev.0",
+  "description": "Node.js and TypeScript SDK for Myanmar payment gateways: KBZ Pay, Wave Money, AYA Payment Gateway, Yoma MMQR and CyberSource.",
+  "keywords": [
+    "laranex",
+    "node-myanmar-payments",
+    "myanmar",
+    "payments",
+    "payment-gateway",
+    "kbzpay",
+    "wave-money",
+    "wavepay",
+    "aya-pay",
+    "yoma",
+    "mmqr",
+    "cybersource"
+  ],
+  "homepage": "https://laranex.vercel.app/node-myanmar-payments",
+  "bugs": {
+    "url": "https://github.com/laranex/node-myanmar-payments/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laranex/node-myanmar-payments.git"
+  },
+  "license": "MIT",
+  "author": "Nay Thu Khant <naythukhant644@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./kbz-pay": {
+      "import": {
+        "types": "./dist/esm/kbz-pay/index.d.ts",
+        "default": "./dist/esm/kbz-pay/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/kbz-pay/index.d.ts",
+        "default": "./dist/cjs/kbz-pay/index.js"
+      }
+    },
+    "./wave-money": {
+      "import": {
+        "types": "./dist/esm/wave-money/index.d.ts",
+        "default": "./dist/esm/wave-money/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/wave-money/index.d.ts",
+        "default": "./dist/cjs/wave-money/index.js"
+      }
+    },
+    "./aya-pay": {
+      "import": {
+        "types": "./dist/esm/aya-pay/index.d.ts",
+        "default": "./dist/esm/aya-pay/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/aya-pay/index.d.ts",
+        "default": "./dist/cjs/aya-pay/index.js"
+      }
+    },
+    "./yoma-mmqr": {
+      "import": {
+        "types": "./dist/esm/yoma-mmqr/index.d.ts",
+        "default": "./dist/esm/yoma-mmqr/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/yoma-mmqr/index.d.ts",
+        "default": "./dist/cjs/yoma-mmqr/index.js"
+      }
+    },
+    "./cyber-source": {
+      "import": {
+        "types": "./dist/esm/cyber-source/index.d.ts",
+        "default": "./dist/esm/cyber-source/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/cyber-source/index.d.ts",
+        "default": "./dist/cjs/cyber-source/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "kbz-pay": [
+        "./dist/cjs/kbz-pay/index.d.ts"
+      ],
+      "wave-money": [
+        "./dist/cjs/wave-money/index.d.ts"
+      ],
+      "aya-pay": [
+        "./dist/cjs/aya-pay/index.d.ts"
+      ],
+      "yoma-mmqr": [
+        "./dist/cjs/yoma-mmqr/index.d.ts"
+      ],
+      "cyber-source": [
+        "./dist/cjs/cyber-source/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "CHANGELOG.md",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "check:package": "publint --strict && attw --pack .",
+    "prepack": "npm run build",
+    "test:dist": "node scripts/smoke.mjs && node scripts/smoke.cjs"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^20.19.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.12.0",
+    "prettier": "^3.9.9",
+    "publint": "^0.3.25",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/node-myanmar-payments/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: node-myanmar-payments
+description: >
+  Integrate Myanmar payment gateways (KBZ Pay, Wave Money, AYA Pay, Yoma MMQR, CyberSource) in a Node.js or TypeScript app with @laranex/myanmar-payments.
+license: MIT
+metadata:
+  author: Nay Thu Khant
+---
+
+# Node Myanmar Payments
+
+## When to use
+
+Use this skill when a Node.js or TypeScript app takes payments through KBZ Pay, Wave Money, AYA Payment Gateway, Yoma MMQR or CyberSource. Start payments and verify callbacks with the package's typed API; never build gateway signatures by hand.
+
+## Install
+
+```bash
+npm install @laranex/myanmar-payments
+```
+
+Requires Node.js 20+ and has no runtime dependencies (global `fetch`, `node:crypto`). It ships ESM and CommonJS with types. Import shared types from the root and each gateway from the root or its subpath: `@laranex/myanmar-payments/kbz-pay`, `/wave-money`, `/aya-pay`, `/yoma-mmqr`, `/cyber-source`.
+
+## Configure
+
+Every gateway has a config class with `fromEnv(process.env)`, reading `KBZ_PAY_*`, `WAVE_MONEY_*`, `AYA_PAY_*` (or `AYA_PGW_*`), `YOMA_MMQR_*` and `CYBER_SOURCE_*` (the same variables as the PHP, Laravel and Go packages). `sandbox` defaults to `true`; set `*_SANDBOX=false` (or `sandbox: false`) in production.
+
+```ts
+import { MyanmarPayments } from '@laranex/myanmar-payments';
+
+const payments = MyanmarPayments.fromEnv(process.env); // create once, share across requests
+const kbz = payments.kbzPay(); // also waveMoney(), ayaPay(), yomaMmqr(), cyberSource()
+```
+
+- Or build one gateway: `new KbzPay({ appId, appKey, merchantCode })`, `KbzPay.fromEnv()`, `new KbzPay(KbzPayConfig.fromEnv(process.env))`.
+- Options (second argument): `{ fetch, httpClient, timeoutMs }`; Yoma and the facade also take `tokenCache` (any `TokenCache`, default `MemoryTokenCache`; back it with Redis when you run several processes).
+- A missing credential throws `ConfigurationError` (`gateway`, `key`).
+
+## Use
+
+### Amounts
+
+Amounts are `Amount.kyat(1000)`, `Amount.parse('1000.50')`, or a whole-number `number`/`bigint`; floats like `10.5` are rejected. Only KBZ Pay (up to 2 decimals) and CyberSource accept decimals; Wave, AYA and Yoma take whole kyat. Invalid data throws `InvalidPaymentDataError` with `errors` per field, before any request is sent.
+
+### Start a payment
+
+```ts
+import { Amount } from '@laranex/myanmar-payments';
+
+const payment = await kbz.pwa({
+  orderId: 'ORDER_1',
+  amount: Amount.kyat(1000),
+  callbackUrl: 'https://shop.test/payments/kbz/callback',
+});
+res.writeHead(302, { Location: payment.url }).end();
+```
+
+- `RedirectPayment` (`url`) from `kbz.pwa(data)` and `wave.initiate(data)`. Wave fills `data.merchantReferenceId` when empty; store it.
+- `FormPayment` from `aya.initiate(data)` and `cyberSource.initiate(data)` (synchronous, no network call): send `payment.toHtml()` as an auto-submitting page, or render `action`, `fields` and `enctype` yourself.
+- `QrPayment` from `kbz.qr(data)` (encode `qrString`) and `yoma.initiate(data)` (`qrImageDataUri()`, `expiresAt`, `reference`). A Yoma QR lives `YomaMmqr.QR_LIFETIME_SECONDS` (120); renew it with `yoma.renewQr(orderId)`.
+- `AppPayment` from `kbz.app(data)`: `res.json(payment)` sends `orderId`, `orderInfo`, `sign`, `signType`.
+- Every network method takes `{ signal }` as its last argument.
+
+AYA needs a channel: `await aya.services()` lists `AyaPayService` entries (`key`, `supports(method)`), then `aya.initiate({ orderId: 'ORDER123', amount: 1000, channel: 'kbz_pay', method: AyaPayMethod.Qr })`.
+
+### Handle the callback
+
+```ts
+import { CallbackRequest, SignatureVerificationError } from '@laranex/myanmar-payments';
+
+const request = await CallbackRequest.fromNodeRequest(req); // or fromWebRequest(request) for Fetch servers
+try {
+  const callback = kbz.handleCallback(request);
+  if (callback.isSuccessful()) {
+    // compare callback.amount with the order, then fulfill callback.orderId once
+  }
+  callback.acknowledgement.send(res); // or return callback.acknowledgement.toResponse()
+} catch (error) {
+  if (error instanceof SignatureVerificationError) {
+    res.statusCode = 400;
+    res.end('invalid signature');
+  } else throw error;
+}
+```
+
+- Give the callback route the raw body: in Express use `express.raw({ type: '*/*' })` or mount it before `express.json()`.
+- Check AYA's browser return with `aya.verifyRedirect(request)`.
+- For production, store the verified call, acknowledge immediately, then process it once in the background.
+
+### Check status and handle errors
+
+- `kbz.status(orderId)`, `aya.status(orderId)` and `yoma.status(reference)` return `PaymentStatusResult` with `status` and `isSuccessful()`. Wave Money and CyberSource have no status API.
+- Statuses: `PaymentStatus.Successful`, `Pending`, `Failed`, `Cancelled`, `Expired`, `Unknown`; `PaymentStatus.isFinal(status)`.
+- Gateway failures throw `ApiError` (`gatewayCode`, `gatewayMessage`, `httpStatus`, `raw`, `cause` for network errors and aborts). All errors extend `PaymentError`.
+
+## Test your app
+
+- Pass a fake `fetch` in the options: `new KbzPay(config, { fetch: async () => new Response('{"Response":{...}}') })`.
+- Replay a stored callback with `CallbackRequest.fromJson(payload, headers)` or `CallbackRequest.from({ body, headers, query })`; it is still signature-checked.
+- To test your own fulfillment code, build `new PaymentCallback({ orderId: 'ORDER_1', status: 'successful', gatewayStatus: 'PAY_SUCCESS' })` yourself.
+
+## Avoid
+
+- Fulfilling orders from return pages or query strings; fulfill only from a verified callback or a status check.
+- Treating `pending` or `unknown` as paid.
+- Passing floats or `Number(price)` as amounts; use `Amount.parse()`.
+- Parsing the callback body with `express.json()` before the package sees it when you can pass the raw body.
+- Reusing a Wave `merchantReferenceId`, or calling Yoma `initiate()` twice for one order (use `renewQr()`).
+- Opening a KBZ Pay PWA link outside a phone with the KBZ Pay app.