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

package/dist/cjs/wave-money/wave-money.js

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaveMoney = exports.WaveMoneyConfig = void 0;
+const amount_js_1 = require("../core/amount.js");
+const callback_js_1 = require("../core/callback.js");
+const crypto_js_1 = require("../core/crypto.js");
+const env_js_1 = require("../core/env.js");
+const errors_js_1 = require("../core/errors.js");
+const http_js_1 = require("../core/http.js");
+const json_js_1 = require("../core/json.js");
+const results_js_1 = require("../core/results.js");
+const status_js_1 = require("../core/status.js");
+const validate_js_1 = require("../core/validate.js");
+const values_js_1 = require("../core/values.js");
+/**
+ * Wave Money credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ */
+class WaveMoneyConfig {
+    static SANDBOX_URL = 'https://preprodpayments.wavemoney.io:8107';
+    static PRODUCTION_URL = 'https://payments.wavemoney.io';
+    static SANDBOX_AUTHENTICATE_URL = 'https://preprodpayments.wavemoney.io';
+    static PRODUCTION_AUTHENTICATE_URL = 'https://payments.wavemoney.io';
+    static DEFAULT_TIME_TO_LIVE_SECONDS = 300;
+    merchantId;
+    secretKey;
+    merchantName;
+    /** Seconds the customer has to pay. */
+    timeToLiveSeconds;
+    sandbox;
+    /** The API base URL in use. */
+    baseUrl;
+    /** The host the customer is redirected to. */
+    authenticateUrl;
+    constructor(options) {
+        this.merchantId = (0, env_js_1.requireSetting)('wave_money', 'merchant_id', options.merchantId);
+        this.secretKey = (0, env_js_1.requireSetting)('wave_money', 'secret_key', options.secretKey);
+        this.merchantName = (0, env_js_1.requireSetting)('wave_money', 'merchant_name', options.merchantName);
+        const ttl = options.timeToLiveSeconds;
+        this.timeToLiveSeconds =
+            ttl !== undefined && Number.isInteger(ttl) && ttl > 0
+                ? ttl
+                : WaveMoneyConfig.DEFAULT_TIME_TO_LIVE_SECONDS;
+        this.sandbox = options.sandbox ?? true;
+        this.baseUrl = (0, env_js_1.trimUrl)((0, env_js_1.optionalSetting)(options.baseUrl) ??
+            (this.sandbox ? WaveMoneyConfig.SANDBOX_URL : WaveMoneyConfig.PRODUCTION_URL));
+        this.authenticateUrl = (0, env_js_1.trimUrl)((0, env_js_1.optionalSetting)(options.authenticateUrl) ??
+            (this.sandbox
+                ? WaveMoneyConfig.SANDBOX_AUTHENTICATE_URL
+                : WaveMoneyConfig.PRODUCTION_AUTHENTICATE_URL));
+    }
+    /**
+     * Reads `WAVE_MONEY_MERCHANT_ID`, `WAVE_MONEY_SECRET_KEY`, `WAVE_MONEY_MERCHANT_NAME` (falling back
+     * to `APP_NAME`), `WAVE_MONEY_TIME_TO_LIVE_IN_SECONDS`, `WAVE_MONEY_SANDBOX`, `WAVE_MONEY_BASE_URL`
+     * and `WAVE_MONEY_AUTHENTICATE_URL`.
+     */
+    static fromEnv(env = (0, env_js_1.defaultEnv)()) {
+        return new WaveMoneyConfig({
+            merchantId: (0, env_js_1.envFirst)(env, 'WAVE_MONEY_MERCHANT_ID'),
+            secretKey: (0, env_js_1.envFirst)(env, 'WAVE_MONEY_SECRET_KEY'),
+            merchantName: (0, env_js_1.envFirst)(env, 'WAVE_MONEY_MERCHANT_NAME', 'APP_NAME'),
+            timeToLiveSeconds: (0, env_js_1.envInt)(env, 'WAVE_MONEY_TIME_TO_LIVE_IN_SECONDS'),
+            sandbox: (0, env_js_1.envSandbox)(env, 'WAVE_MONEY_SANDBOX'),
+            baseUrl: (0, env_js_1.envFirst)(env, 'WAVE_MONEY_BASE_URL'),
+            authenticateUrl: (0, env_js_1.envFirst)(env, 'WAVE_MONEY_AUTHENTICATE_URL'),
+        });
+    }
+}
+exports.WaveMoneyConfig = WaveMoneyConfig;
+const STATUSES = {
+    PAYMENT_CONFIRMED: 'successful',
+    INSUFFICIENT_BALANCE: 'pending',
+    ACCOUNT_LOCKED: 'failed',
+    BILL_COLLECTION_FAILED: 'failed',
+    PAYMENT_REQUEST_CANCELLED: 'cancelled',
+    TRANSACTION_TIMED_OUT: 'expired',
+    SCHEDULER_TRANSACTION_TIMED_OUT: 'expired',
+};
+const CALLBACK_FIELDS = [
+    'status',
+    'timeToLiveSeconds',
+    'merchantId',
+    'orderId',
+    'amount',
+    'backendResultUrl',
+    'merchantReferenceId',
+    'initiatorMsisdn',
+    'transactionId',
+    'paymentRequestId',
+    'requestTime',
+];
+/**
+ * Wave Money (WavePay payment gateway): redirect payments and callbacks. Wave has no status API,
+ * so the callback is the only result.
+ */
+class WaveMoney {
+    /** The configuration in use. */
+    config;
+    transport;
+    constructor(config, options = {}) {
+        this.config = config instanceof WaveMoneyConfig ? config : new WaveMoneyConfig(config);
+        this.transport = new http_js_1.Transport((0, http_js_1.httpClientFrom)(options));
+    }
+    /** A gateway configured from the `WAVE_MONEY_*` environment variables. */
+    static fromEnv(env = (0, env_js_1.defaultEnv)(), options = {}) {
+        return new WaveMoney(WaveMoneyConfig.fromEnv(env), options);
+    }
+    /**
+     * The total that will be charged: `amount`, or the exact sum of the items when it is unset.
+     * `undefined` when an item amount is missing, malformed or has decimals.
+     */
+    static resolvedAmount(data) {
+        if (data.amount !== undefined) {
+            return (0, validate_js_1.toAmount)(data.amount);
+        }
+        if (!Array.isArray(data.items) || data.items.length === 0) {
+            return undefined;
+        }
+        let total = 0n;
+        for (const item of data.items) {
+            const amount = (0, validate_js_1.toAmount)(item?.amount);
+            if (amount === undefined || amount.decimalPlaces() > 0) {
+                return undefined;
+            }
+            total += BigInt(amount.toString());
+        }
+        return amount_js_1.Amount.kyat(total);
+    }
+    /** Checks the request against Wave's documented rules; throws an `InvalidPaymentDataError`. */
+    static validate(data) {
+        const items = Array.isArray(data.items) ? data.items : [];
+        const validator = new validate_js_1.Validator()
+            .required('orderId', data.orderId)
+            .required('callbackUrl', data.callbackUrl)
+            .url('callbackUrl', data.callbackUrl)
+            .required('returnUrl', data.returnUrl)
+            .url('returnUrl', data.returnUrl)
+            .required('description', data.description)
+            .when(items.length === 0, 'items', 'The items field must have at least one item.')
+            .string('merchantReferenceId', data.merchantReferenceId);
+        items.forEach((item, index) => {
+            validator
+                .required(`items.${index}.name`, item?.name)
+                .amount(`items.${index}.amount`, item?.amount, { gateway: 'Wave Money', maxDecimals: 0 });
+        });
+        const resolved = WaveMoney.resolvedAmount(data);
+        if (!(items.length > 0 && data.amount === undefined && resolved === undefined)) {
+            validator.amount('amount', data.amount ?? resolved, {
+                gateway: 'Wave Money',
+                maxDecimals: 0,
+            });
+        }
+        validator.validate();
+    }
+    /**
+     * Creates a payment request and returns Wave's page to redirect the customer to. Once `data`
+     * passes validation it fills `data.merchantReferenceId` with a random id when empty, so store it
+     * afterwards. Invalid data is left untouched.
+     */
+    async initiate(data, options = {}) {
+        WaveMoney.validate(data);
+        if (!data.merchantReferenceId) {
+            data.merchantReferenceId = (0, crypto_js_1.randomHex)();
+        }
+        const amount = WaveMoney.resolvedAmount(data).toString();
+        const ttl = String(this.config.timeToLiveSeconds);
+        // Wave documents items as [{"name": "...", "amount": 1000}] with a numeric amount; the amount
+        // text is written as a JSON number without passing through a float.
+        const items = `[${data.items
+            .map((item) => `{"name":${JSON.stringify(item.name)},"amount":${String((0, validate_js_1.toAmount)(item.amount))}}`)
+            .join(',')}]`;
+        const response = await this.transport.postForm(`${this.config.baseUrl}/payment`, {
+            time_to_live_in_seconds: ttl,
+            merchant_id: this.config.merchantId,
+            order_id: data.orderId,
+            merchant_reference_id: data.merchantReferenceId,
+            frontend_result_url: data.returnUrl,
+            backend_result_url: data.callbackUrl,
+            amount,
+            payment_description: data.description,
+            merchant_name: this.config.merchantName,
+            items,
+            hash: this.hash([
+                ttl,
+                this.config.merchantId,
+                data.orderId,
+                amount,
+                data.callbackUrl,
+                data.merchantReferenceId,
+            ]),
+        }, {}, options.signal);
+        const body = response.json();
+        const transactionId = (0, values_js_1.get)(body, 'transaction_id');
+        if (!response.successful() || (0, values_js_1.get)(body, 'message') !== 'success' || transactionId === '') {
+            const message = errorMessage(body);
+            throw new errors_js_1.ApiError(`Wave Money payment request failed with HTTP ${response.status}: ${message}`, {
+                gatewayCode: 'errors' in body ? 'VALIDATION_ERROR' : (0, values_js_1.optional)(body, 'message'),
+                gatewayMessage: message,
+                httpStatus: response.status,
+                raw: (0, json_js_1.toPlainObject)(body),
+            });
+        }
+        return new results_js_1.RedirectPayment({
+            orderId: data.orderId,
+            url: `${this.config.authenticateUrl}/authenticate?transaction_id=${(0, crypto_js_1.queryEscape)(transactionId)}`,
+            gatewayReference: transactionId,
+            raw: (0, json_js_1.toPlainObject)(body),
+        });
+    }
+    /**
+     * Verifies Wave's callback. Only `PAYMENT_CONFIRMED` means the customer paid. `orderId` falls
+     * back to `merchantReferenceId` when it is missing, null or empty, because Wave marks `orderId` as
+     * optional.
+     */
+    handleCallback(request) {
+        const payload = (0, callback_js_1.losslessBody)(request);
+        const expected = this.hash(CALLBACK_FIELDS.map((field) => (0, values_js_1.scalarString)(payload[field]) ?? 'null'));
+        const hashValue = payload.hashValue;
+        if (typeof hashValue !== 'string' || !(0, crypto_js_1.safeEqual)(expected, hashValue.toLowerCase())) {
+            throw new errors_js_1.SignatureVerificationError('Wave Money callback hash verification failed.', (0, json_js_1.toPlainObject)(payload));
+        }
+        const gatewayStatus = (0, values_js_1.trimmed)(payload, 'status');
+        return new callback_js_1.PaymentCallback({
+            orderId: (0, values_js_1.get)(payload, 'orderId') || (0, values_js_1.get)(payload, 'merchantReferenceId'),
+            status: (0, status_js_1.resolveStatus)(STATUSES, gatewayStatus),
+            gatewayStatus,
+            gatewayReference: (0, values_js_1.optional)(payload, 'transactionId'),
+            amount: (0, values_js_1.optional)(payload, 'amount'),
+            raw: (0, json_js_1.toPlainObject)(payload),
+        });
+    }
+    hash(parts) {
+        return (0, crypto_js_1.hmacSha256Hex)(this.config.secretKey, parts.join(''));
+    }
+}
+exports.WaveMoney = WaveMoney;
+function errorMessage(body) {
+    const errors = body.errors;
+    if ((0, json_js_1.isLosslessObject)(errors)) {
+        return Object.keys(errors)
+            .sort()
+            .map((field) => {
+            const list = errors[field];
+            const texts = (Array.isArray(list) ? list : [list])
+                .map((item) => (0, values_js_1.scalarString)(item))
+                .filter((text) => text !== undefined);
+            return `${field}: ${texts.join(' ')}`;
+        })
+            .join('; ');
+    }
+    return (0, values_js_1.get)(body, 'message') || 'unexpected response';
+}

package/dist/cjs/yoma-mmqr/index.d.ts

@@ -0,0 +1 @@
+export { YomaMmqr, YomaMmqrConfig, type YomaMmqrConfigOptions, type YomaMmqrOptions, type YomaMmqrPaymentData, } from './yoma-mmqr.js';

package/dist/cjs/yoma-mmqr/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YomaMmqrConfig = exports.YomaMmqr = void 0;
+var yoma_mmqr_js_1 = require("./yoma-mmqr.js");
+Object.defineProperty(exports, "YomaMmqr", { enumerable: true, get: function () { return yoma_mmqr_js_1.YomaMmqr; } });
+Object.defineProperty(exports, "YomaMmqrConfig", { enumerable: true, get: function () { return yoma_mmqr_js_1.YomaMmqrConfig; } });

package/dist/cjs/yoma-mmqr/yoma-mmqr.d.ts

@@ -0,0 +1,105 @@
+import { type AmountInput } from '../core/amount.js';
+import { type TokenCache } from '../core/cache.js';
+import { CallbackRequest, PaymentCallback, PaymentStatusResult } from '../core/callback.js';
+import { type EnvSource } from '../core/env.js';
+import { type GatewayOptions, type RequestOptions } from '../core/http.js';
+import { QrPayment } from '../core/results.js';
+/** The settings of {@link YomaMmqrConfig}. */
+export interface YomaMmqrConfigOptions {
+    /** The merchant id Yoma issued. */
+    merchantId: string;
+    /** The OAuth client id. */
+    clientId: string;
+    /** The OAuth client secret. */
+    clientSecret: string;
+    /** The hash key Yoma issued for verifying callbacks. */
+    webhookHashKey: string;
+    /** The secret you shared with Yoma; when set, callbacks must carry it in `X-Webhook-Secret`. */
+    webhookSecret?: string | undefined;
+    /** Use the UAT payment hub (default `true`). */
+    sandbox?: boolean | undefined;
+    /** Overrides the API base URL. */
+    baseUrl?: string | undefined;
+    /** The `{version}` segment of the API paths (default `v1rc`). */
+    apiVersion?: string | undefined;
+}
+/**
+ * Yoma MMQR credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ */
+export declare class YomaMmqrConfig {
+    static readonly SANDBOX_URL = "https://devapi.yomabank.net";
+    static readonly PRODUCTION_URL = "https://paymenthubapi.yomabank.com";
+    static readonly DEFAULT_API_VERSION = "v1rc";
+    readonly merchantId: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly webhookHashKey: string;
+    readonly webhookSecret: string | undefined;
+    readonly sandbox: boolean;
+    /** The base URL in use. */
+    readonly baseUrl: string;
+    /** The API version in use. */
+    readonly apiVersion: string;
+    constructor(options: YomaMmqrConfigOptions);
+    /**
+     * 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?: EnvSource): YomaMmqrConfig;
+}
+/**
+ * A Yoma MMQR order. Yoma accepts each order number once; renew an expired QR with `renewQr()`.
+ * Yoma documents no decimals, so amounts are whole kyat.
+ */
+export interface YomaMmqrPaymentData {
+    /** Your unique order number, at most 20 characters. */
+    orderId: string;
+    /** The amount in whole kyat, e.g. `Amount.kyat(1000)` or `1000`. */
+    amount: AmountInput;
+    /** Shown on the payment slip, at most 50 characters. */
+    description: string;
+}
+/** Options of {@link YomaMmqr}: the HTTP options plus the access token cache. */
+export interface YomaMmqrOptions extends GatewayOptions {
+    /** Keeps the access token between calls; defaults to a {@link MemoryTokenCache}. */
+    tokenCache?: TokenCache | undefined;
+}
+/**
+ * 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 declare class YomaMmqr {
+    /** How long a generated QR stays payable, in seconds. */
+    static readonly QR_LIFETIME_SECONDS = 120;
+    /** The configuration in use. */
+    readonly config: YomaMmqrConfig;
+    private readonly transport;
+    private readonly cache;
+    private pendingToken;
+    constructor(config: YomaMmqrConfig | YomaMmqrConfigOptions, options?: YomaMmqrOptions);
+    /** A gateway configured from the `YOMA_MMQR_*` environment variables. */
+    static fromEnv(env?: EnvSource, options?: YomaMmqrOptions): YomaMmqr;
+    /** Checks the order against Yoma's documented limits; throws an `InvalidPaymentDataError`. */
+    static validate(data: YomaMmqrPaymentData): void;
+    /** Checks the order out with Yoma and generates its first QR. Call it once per order. */
+    initiate(data: YomaMmqrPaymentData, options?: RequestOptions): Promise<QrPayment>;
+    /**
+     * 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.
+     */
+    renewQr(orderId: string, options?: RequestOptions): Promise<QrPayment>;
+    /** Checks a QR's payment status by its reference (`QrPayment.reference`). An expired QR reports `expired`. */
+    status(reference: string, options?: RequestOptions): Promise<PaymentStatusResult>;
+    /**
+     * Verifies Yoma's payment callback: HMAC-SHA256 of `orderNumber=..&status=..` keyed with the
+     * order number followed by the webhook hash key.
+     */
+    handleCallback(request: CallbackRequest): PaymentCallback;
+    /** Drops the cached access token, e.g. after rotating the client secret. */
+    forgetToken(): Promise<void>;
+    private call;
+    private token;
+    private fetchToken;
+    private tokenCacheKey;
+}

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

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YomaMmqr = exports.YomaMmqrConfig = void 0;
+const cache_js_1 = require("../core/cache.js");
+const callback_js_1 = require("../core/callback.js");
+const crypto_js_1 = require("../core/crypto.js");
+const env_js_1 = require("../core/env.js");
+const errors_js_1 = require("../core/errors.js");
+const http_js_1 = require("../core/http.js");
+const json_js_1 = require("../core/json.js");
+const results_js_1 = require("../core/results.js");
+const status_js_1 = require("../core/status.js");
+const validate_js_1 = require("../core/validate.js");
+const values_js_1 = require("../core/values.js");
+/**
+ * Yoma MMQR credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ */
+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 = (0, env_js_1.requireSetting)('yoma_mmqr', 'merchant_id', options.merchantId);
+        this.clientId = (0, env_js_1.requireSetting)('yoma_mmqr', 'client_id', options.clientId);
+        this.clientSecret = (0, env_js_1.requireSetting)('yoma_mmqr', 'client_secret', options.clientSecret);
+        this.webhookHashKey = (0, env_js_1.requireSetting)('yoma_mmqr', 'webhook_hashkey', options.webhookHashKey);
+        this.webhookSecret = (0, env_js_1.optionalSetting)(options.webhookSecret);
+        this.sandbox = options.sandbox ?? true;
+        this.baseUrl = (0, env_js_1.trimUrl)((0, env_js_1.optionalSetting)(options.baseUrl) ??
+            (this.sandbox ? YomaMmqrConfig.SANDBOX_URL : YomaMmqrConfig.PRODUCTION_URL));
+        this.apiVersion = (0, env_js_1.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 = (0, env_js_1.defaultEnv)()) {
+        return new YomaMmqrConfig({
+            merchantId: (0, env_js_1.envFirst)(env, 'YOMA_MMQR_MERCHANT_ID'),
+            clientId: (0, env_js_1.envFirst)(env, 'YOMA_MMQR_CLIENT_ID'),
+            clientSecret: (0, env_js_1.envFirst)(env, 'YOMA_MMQR_CLIENT_SECRET'),
+            webhookHashKey: (0, env_js_1.envFirst)(env, 'YOMA_MMQR_WEBHOOK_HASHKEY'),
+            webhookSecret: (0, env_js_1.envFirst)(env, 'YOMA_MMQR_WEBHOOK_SECRET'),
+            sandbox: (0, env_js_1.envSandbox)(env, 'YOMA_MMQR_SANDBOX'),
+            baseUrl: (0, env_js_1.envFirst)(env, 'YOMA_MMQR_BASE_URL'),
+            apiVersion: (0, env_js_1.envFirst)(env, 'YOMA_MMQR_API_VERSION'),
+        });
+    }
+}
+exports.YomaMmqrConfig = YomaMmqrConfig;
+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.
+ */
+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 http_js_1.Transport((0, http_js_1.httpClientFrom)(options));
+        this.cache = options.tokenCache ?? new cache_js_1.MemoryTokenCache();
+    }
+    /** A gateway configured from the `YOMA_MMQR_*` environment variables. */
+    static fromEnv(env = (0, env_js_1.defaultEnv)(), options = {}) {
+        return new YomaMmqr(YomaMmqrConfig.fromEnv(env), options);
+    }
+    /** Checks the order against Yoma's documented limits; throws an `InvalidPaymentDataError`. */
+    static validate(data) {
+        new validate_js_1.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((0, validate_js_1.toAmount)(data.amount)),
+            description: data.description,
+        }, [], options.signal);
+        if (body.checkOutStatus !== true) {
+            throw new errors_js_1.ApiError('Yoma MMQR did not confirm the checkout.', { raw: (0, json_js_1.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 = (0, values_js_1.get)(body, 'qrString');
+        const reference = (0, values_js_1.get)(body, 'refLabel');
+        if (qrString === '' || reference === '') {
+            throw new errors_js_1.ApiError('Yoma MMQR did not return a QR.', { raw: (0, json_js_1.toPlainObject)(body) });
+        }
+        return new results_js_1.QrPayment({
+            orderId,
+            qrImage: qrString,
+            expiresAt: new Date(Date.now() + YomaMmqr.QR_LIFETIME_SECONDS * 1000),
+            reference,
+            raw: (0, json_js_1.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 ((0, values_js_1.get)(body, 'errorCode') === 'QR EXPIRED') {
+            return new callback_js_1.PaymentStatusResult({
+                status: 'expired',
+                gatewayStatus: 'QR EXPIRED',
+                gatewayReference: reference,
+                raw: (0, json_js_1.toPlainObject)(body),
+            });
+        }
+        const paymentStatus = (0, values_js_1.trimmed)(body, 'paymentStatus');
+        return new callback_js_1.PaymentStatusResult({
+            status: (0, status_js_1.resolveStatus)(STATUSES, paymentStatus.toUpperCase()),
+            gatewayStatus: paymentStatus,
+            gatewayReference: (0, values_js_1.get)(body, 'refLabel') || reference,
+            raw: (0, json_js_1.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 = (0, callback_js_1.losslessBody)(request);
+        if (this.config.webhookSecret !== undefined &&
+            !(0, crypto_js_1.safeEqual)(this.config.webhookSecret, request.header('X-Webhook-Secret') ?? '')) {
+            throw new errors_js_1.SignatureVerificationError('Yoma MMQR callback has a missing or wrong X-Webhook-Secret header.', (0, json_js_1.toPlainObject)(payload));
+        }
+        const orderNumber = (0, values_js_1.get)(payload, 'orderNumber');
+        const status = (0, values_js_1.trimmed)(payload, 'status');
+        const expected = (0, crypto_js_1.hmacSha256Hex)(orderNumber + this.config.webhookHashKey, `orderNumber=${orderNumber}&status=${status}`);
+        if (orderNumber === '' || !(0, crypto_js_1.safeEqual)(expected, (0, values_js_1.get)(payload, 'hashValue').toLowerCase())) {
+            throw new errors_js_1.SignatureVerificationError('Yoma MMQR callback hash verification failed.', (0, json_js_1.toPlainObject)(payload));
+        }
+        return new callback_js_1.PaymentCallback({
+            orderId: orderNumber,
+            status: (0, status_js_1.resolveStatus)(STATUSES, status.toUpperCase()),
+            gatewayStatus: status,
+            raw: (0, json_js_1.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 = (0, values_js_1.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 = (0, values_js_1.get)(body, 'access_token');
+        if (!response.successful() || token === '') {
+            throw apiError('token', response.status, body, (0, values_js_1.get)(body, 'error'));
+        }
+        const expiresIn = Number.parseInt((0, values_js_1.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.${(0, crypto_js_1.sha256Hex)(`${this.config.baseUrl}|${this.config.clientId}`)}`;
+    }
+}
+exports.YomaMmqr = YomaMmqr;
+function apiError(endpoint, status, body, errorCode) {
+    const message = (0, values_js_1.optional)(body, 'errorDescription') || (0, values_js_1.optional)(body, 'error_description');
+    return new errors_js_1.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: (0, json_js_1.toPlainObject)(body),
+    });
+}