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

package/dist/esm/kbz-pay/signer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * KBZ Pay's signature: every non-empty scalar field except `sign` and `sign_type`, sorted by key,
+ * joined as raw `key=value` pairs (not URL-encoded), with `&key=<app key>` appended, hashed with
+ * SHA-256 and uppercased.
+ */
+export declare class KbzPaySigner {
+    private readonly appKey;
+    constructor(appKey: string);
+    /** The sorted `key=value` string, without the app key. */
+    signString(fields: Readonly<Record<string, unknown>>): string;
+    /** The uppercase SHA-256 signature of `fields`. */
+    sign(fields: Readonly<Record<string, unknown>>): string;
+    /** Whether `fields.sign` matches, compared in constant time. */
+    verify(fields: Readonly<Record<string, unknown>>): boolean;
+}

package/dist/esm/kbz-pay/signer.js

@@ -0,0 +1,32 @@
+import { safeEqual, sha256Hex } from '../core/crypto.js';
+import { scalarString } from '../core/values.js';
+/**
+ * KBZ Pay's signature: every non-empty scalar field except `sign` and `sign_type`, sorted by key,
+ * joined as raw `key=value` pairs (not URL-encoded), with `&key=<app key>` appended, hashed with
+ * SHA-256 and uppercased.
+ */
+export class KbzPaySigner {
+    appKey;
+    constructor(appKey) {
+        this.appKey = appKey;
+    }
+    /** The sorted `key=value` string, without the app key. */
+    signString(fields) {
+        return Object.keys(fields)
+            .filter((key) => key !== 'sign' && key !== 'sign_type')
+            .map((key) => [key, scalarString(fields[key])])
+            .filter((pair) => pair[1] !== undefined && pair[1] !== '')
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([key, value]) => `${key}=${value}`)
+            .join('&');
+    }
+    /** The uppercase SHA-256 signature of `fields`. */
+    sign(fields) {
+        return sha256Hex(`${this.signString(fields)}&key=${this.appKey}`).toUpperCase();
+    }
+    /** Whether `fields.sign` matches, compared in constant time. */
+    verify(fields) {
+        const sign = fields.sign;
+        return typeof sign === 'string' && safeEqual(this.sign(fields), sign.toUpperCase());
+    }
+}

package/dist/esm/myanmar-payments.d.ts

@@ -0,0 +1,50 @@
+import { AyaPay, AyaPayConfig, type AyaPayConfigOptions } from './aya-pay/aya-pay.js';
+import type { TokenCache } from './core/cache.js';
+import { type EnvSource } from './core/env.js';
+import type { GatewayOptions } from './core/http.js';
+import { CyberSource, CyberSourceConfig, type CyberSourceConfigOptions } from './cyber-source/cyber-source.js';
+import { KbzPay, KbzPayConfig, type KbzPayConfigOptions } from './kbz-pay/kbz-pay.js';
+import { WaveMoney, WaveMoneyConfig, type WaveMoneyConfigOptions } from './wave-money/wave-money.js';
+import { YomaMmqr, YomaMmqrConfig, type YomaMmqrConfigOptions } from './yoma-mmqr/yoma-mmqr.js';
+/** The configuration of every gateway; configure only the ones you use. */
+export interface MyanmarPaymentsConfig {
+    kbzPay?: KbzPayConfig | KbzPayConfigOptions | undefined;
+    waveMoney?: WaveMoneyConfig | WaveMoneyConfigOptions | undefined;
+    ayaPay?: AyaPayConfig | AyaPayConfigOptions | undefined;
+    yomaMmqr?: YomaMmqrConfig | YomaMmqrConfigOptions | undefined;
+    cyberSource?: CyberSourceConfig | CyberSourceConfigOptions | undefined;
+}
+/** Options shared by every gateway the facade builds. */
+export interface MyanmarPaymentsOptions extends GatewayOptions {
+    /** Keeps Yoma MMQR's access token; defaults to a {@link MemoryTokenCache}. */
+    tokenCache?: TokenCache | undefined;
+}
+/**
+ * Builds each gateway from one configuration object (or the environment). Gateways are created
+ * on first use and reused, so only the gateways you call need to be configured.
+ */
+export declare class MyanmarPayments {
+    private kbzPayGateway;
+    private waveMoneyGateway;
+    private ayaPayGateway;
+    private yomaMmqrGateway;
+    private cyberSourceGateway;
+    private readonly options;
+    private readonly sources;
+    constructor(config?: MyanmarPaymentsConfig, options?: MyanmarPaymentsOptions);
+    /**
+     * Reads every gateway's configuration from environment variables (`KBZ_PAY_*`, `WAVE_MONEY_*`,
+     * `AYA_PAY_*`, `YOMA_MMQR_*`, `CYBER_SOURCE_*`) when the gateway is first used.
+     */
+    static fromEnv(env?: EnvSource, options?: MyanmarPaymentsOptions): MyanmarPayments;
+    /** The KBZ Pay gateway. Throws a `ConfigurationError` when it is not configured. */
+    kbzPay(): KbzPay;
+    /** The Wave Money gateway. Throws a `ConfigurationError` when it is not configured. */
+    waveMoney(): WaveMoney;
+    /** The AYA Payment Gateway. Throws a `ConfigurationError` when it is not configured. */
+    ayaPay(): AyaPay;
+    /** The Yoma MMQR gateway. Throws a `ConfigurationError` when it is not configured. */
+    yomaMmqr(): YomaMmqr;
+    /** The CyberSource gateway. Throws a `ConfigurationError` when it is not configured. */
+    cyberSource(): CyberSource;
+}

package/dist/esm/myanmar-payments.js

@@ -0,0 +1,69 @@
+import { AyaPay, AyaPayConfig } from './aya-pay/aya-pay.js';
+import { MemoryTokenCache } from './core/cache.js';
+import { defaultEnv } from './core/env.js';
+import { ConfigurationError } from './core/errors.js';
+import { CyberSource, CyberSourceConfig, } from './cyber-source/cyber-source.js';
+import { KbzPay, KbzPayConfig } from './kbz-pay/kbz-pay.js';
+import { WaveMoney, WaveMoneyConfig, } from './wave-money/wave-money.js';
+import { YomaMmqr, YomaMmqrConfig } from './yoma-mmqr/yoma-mmqr.js';
+/**
+ * Builds each gateway from one configuration object (or the environment). Gateways are created
+ * on first use and reused, so only the gateways you call need to be configured.
+ */
+export class MyanmarPayments {
+    kbzPayGateway;
+    waveMoneyGateway;
+    ayaPayGateway;
+    yomaMmqrGateway;
+    cyberSourceGateway;
+    options;
+    sources;
+    constructor(config = {}, options = {}) {
+        this.options = { ...options, tokenCache: options.tokenCache ?? new MemoryTokenCache() };
+        this.sources = { ...config };
+    }
+    /**
+     * Reads every gateway's configuration from environment variables (`KBZ_PAY_*`, `WAVE_MONEY_*`,
+     * `AYA_PAY_*`, `YOMA_MMQR_*`, `CYBER_SOURCE_*`) when the gateway is first used.
+     */
+    static fromEnv(env = defaultEnv(), options = {}) {
+        const payments = new MyanmarPayments({}, options);
+        Object.assign(payments.sources, {
+            kbzPay: () => KbzPayConfig.fromEnv(env),
+            waveMoney: () => WaveMoneyConfig.fromEnv(env),
+            ayaPay: () => AyaPayConfig.fromEnv(env),
+            yomaMmqr: () => YomaMmqrConfig.fromEnv(env),
+            cyberSource: () => CyberSourceConfig.fromEnv(env),
+        });
+        return payments;
+    }
+    /** The KBZ Pay gateway. Throws a `ConfigurationError` when it is not configured. */
+    kbzPay() {
+        return (this.kbzPayGateway ??= new KbzPay(resolve(this.sources.kbzPay, KbzPayConfig, 'kbz_pay', 'app_id'), this.options));
+    }
+    /** The Wave Money gateway. Throws a `ConfigurationError` when it is not configured. */
+    waveMoney() {
+        return (this.waveMoneyGateway ??= new WaveMoney(resolve(this.sources.waveMoney, WaveMoneyConfig, 'wave_money', 'merchant_id'), this.options));
+    }
+    /** The AYA Payment Gateway. Throws a `ConfigurationError` when it is not configured. */
+    ayaPay() {
+        return (this.ayaPayGateway ??= new AyaPay(resolve(this.sources.ayaPay, AyaPayConfig, 'aya_pay', 'app_key'), this.options));
+    }
+    /** The Yoma MMQR gateway. Throws a `ConfigurationError` when it is not configured. */
+    yomaMmqr() {
+        return (this.yomaMmqrGateway ??= new YomaMmqr(resolve(this.sources.yomaMmqr, YomaMmqrConfig, 'yoma_mmqr', 'merchant_id'), this.options));
+    }
+    /** The CyberSource gateway. Throws a `ConfigurationError` when it is not configured. */
+    cyberSource() {
+        return (this.cyberSourceGateway ??= new CyberSource(resolve(this.sources.cyberSource, CyberSourceConfig, 'cyber_source', 'profile_id')));
+    }
+}
+function resolve(source, type, gateway, firstKey) {
+    if (source === undefined || source === null) {
+        throw new ConfigurationError(gateway, firstKey);
+    }
+    if (typeof source === 'function') {
+        return source();
+    }
+    return source instanceof type ? source : new type(source);
+}

package/dist/esm/wave-money/index.d.ts

@@ -0,0 +1 @@
+export { WaveMoney, WaveMoneyConfig, type WaveMoneyConfigOptions, type WaveMoneyItem, type WaveMoneyPaymentData, } from './wave-money.js';

package/dist/esm/wave-money/index.js

@@ -0,0 +1 @@
+export { WaveMoney, WaveMoneyConfig, } from './wave-money.js';

package/dist/esm/wave-money/wave-money.d.ts

@@ -0,0 +1,111 @@
+import { Amount, type AmountInput } from '../core/amount.js';
+import { CallbackRequest, PaymentCallback } from '../core/callback.js';
+import { type EnvSource } from '../core/env.js';
+import { type GatewayOptions, type RequestOptions } from '../core/http.js';
+import { RedirectPayment } from '../core/results.js';
+/** The settings of {@link WaveMoneyConfig}. */
+export interface WaveMoneyConfigOptions {
+    /** The merchant id Wave issued. */
+    merchantId: string;
+    /** The hash secret key Wave issued. */
+    secretKey: string;
+    /** Your business name, shown on Wave's payment page. */
+    merchantName: string;
+    /** How long the customer has to pay, in seconds (default 300). */
+    timeToLiveSeconds?: number | undefined;
+    /** Use the test environment (default `true`). */
+    sandbox?: boolean | undefined;
+    /** Overrides the API base URL. */
+    baseUrl?: string | undefined;
+    /** Overrides the host the customer is redirected to. Wave serves it without the API port. */
+    authenticateUrl?: string | undefined;
+}
+/**
+ * Wave Money credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ */
+export declare class WaveMoneyConfig {
+    static readonly SANDBOX_URL = "https://preprodpayments.wavemoney.io:8107";
+    static readonly PRODUCTION_URL = "https://payments.wavemoney.io";
+    static readonly SANDBOX_AUTHENTICATE_URL = "https://preprodpayments.wavemoney.io";
+    static readonly PRODUCTION_AUTHENTICATE_URL = "https://payments.wavemoney.io";
+    static readonly DEFAULT_TIME_TO_LIVE_SECONDS = 300;
+    readonly merchantId: string;
+    readonly secretKey: string;
+    readonly merchantName: string;
+    /** Seconds the customer has to pay. */
+    readonly timeToLiveSeconds: number;
+    readonly sandbox: boolean;
+    /** The API base URL in use. */
+    readonly baseUrl: string;
+    /** The host the customer is redirected to. */
+    readonly authenticateUrl: string;
+    constructor(options: WaveMoneyConfigOptions);
+    /**
+     * 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?: EnvSource): WaveMoneyConfig;
+}
+/** A line item shown on Wave's payment page. */
+export interface WaveMoneyItem {
+    /** The item name. */
+    name: string;
+    /** The item amount in whole kyat, e.g. `Amount.kyat(1000)` or `1000`. */
+    amount: AmountInput;
+}
+/**
+ * A Wave Money payment request. Wave only accepts whole kyat (MMK).
+ */
+export interface WaveMoneyPaymentData {
+    /** Your order id. One order can have several payment attempts. */
+    orderId: string;
+    /** The URL Wave posts the result to (`backend_result_url`). */
+    callbackUrl: string;
+    /** Where Wave sends the customer back (`frontend_result_url`). Not proof of payment. */
+    returnUrl: string;
+    /** Shown to the customer. */
+    description: string;
+    /** The line items shown on Wave's page; at least one. */
+    items: readonly WaveMoneyItem[];
+    /** The total in whole kyat. Leave it unset to charge the sum of the items. */
+    amount?: AmountInput | undefined;
+    /**
+     * The unique id of this attempt; Wave rejects a reused one. `initiate()` fills it with a random
+     * id when empty, so store it afterwards: Wave's callback may omit `orderId` but always carries
+     * this.
+     */
+    merchantReferenceId?: string | undefined;
+}
+/**
+ * Wave Money (WavePay payment gateway): redirect payments and callbacks. Wave has no status API,
+ * so the callback is the only result.
+ */
+export declare class WaveMoney {
+    /** The configuration in use. */
+    readonly config: WaveMoneyConfig;
+    private readonly transport;
+    constructor(config: WaveMoneyConfig | WaveMoneyConfigOptions, options?: GatewayOptions);
+    /** A gateway configured from the `WAVE_MONEY_*` environment variables. */
+    static fromEnv(env?: EnvSource, options?: GatewayOptions): WaveMoney;
+    /**
+     * 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: Pick<WaveMoneyPaymentData, 'amount' | 'items'>): Amount | undefined;
+    /** Checks the request against Wave's documented rules; throws an `InvalidPaymentDataError`. */
+    static validate(data: WaveMoneyPaymentData): void;
+    /**
+     * 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.
+     */
+    initiate(data: WaveMoneyPaymentData, options?: RequestOptions): Promise<RedirectPayment>;
+    /**
+     * 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: CallbackRequest): PaymentCallback;
+    private hash;
+}

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

@@ -0,0 +1,246 @@
+import { Amount } from '../core/amount.js';
+import { CallbackRequest, losslessBody, PaymentCallback } from '../core/callback.js';
+import { hmacSha256Hex, queryEscape, randomHex, safeEqual } from '../core/crypto.js';
+import { defaultEnv, envFirst, envInt, envSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
+import { ApiError, SignatureVerificationError } from '../core/errors.js';
+import { httpClientFrom, Transport, } from '../core/http.js';
+import { isLosslessObject, toPlainObject } from '../core/json.js';
+import { RedirectPayment } from '../core/results.js';
+import { resolveStatus } from '../core/status.js';
+import { toAmount, Validator } from '../core/validate.js';
+import { get, optional, scalarString, trimmed } from '../core/values.js';
+/**
+ * Wave Money credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ */
+export 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 = requireSetting('wave_money', 'merchant_id', options.merchantId);
+        this.secretKey = requireSetting('wave_money', 'secret_key', options.secretKey);
+        this.merchantName = 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 = trimUrl(optionalSetting(options.baseUrl) ??
+            (this.sandbox ? WaveMoneyConfig.SANDBOX_URL : WaveMoneyConfig.PRODUCTION_URL));
+        this.authenticateUrl = trimUrl(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 = defaultEnv()) {
+        return new WaveMoneyConfig({
+            merchantId: envFirst(env, 'WAVE_MONEY_MERCHANT_ID'),
+            secretKey: envFirst(env, 'WAVE_MONEY_SECRET_KEY'),
+            merchantName: envFirst(env, 'WAVE_MONEY_MERCHANT_NAME', 'APP_NAME'),
+            timeToLiveSeconds: envInt(env, 'WAVE_MONEY_TIME_TO_LIVE_IN_SECONDS'),
+            sandbox: envSandbox(env, 'WAVE_MONEY_SANDBOX'),
+            baseUrl: envFirst(env, 'WAVE_MONEY_BASE_URL'),
+            authenticateUrl: envFirst(env, 'WAVE_MONEY_AUTHENTICATE_URL'),
+        });
+    }
+}
+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.
+ */
+export class WaveMoney {
+    /** The configuration in use. */
+    config;
+    transport;
+    constructor(config, options = {}) {
+        this.config = config instanceof WaveMoneyConfig ? config : new WaveMoneyConfig(config);
+        this.transport = new Transport(httpClientFrom(options));
+    }
+    /** A gateway configured from the `WAVE_MONEY_*` environment variables. */
+    static fromEnv(env = 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 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 = toAmount(item?.amount);
+            if (amount === undefined || amount.decimalPlaces() > 0) {
+                return undefined;
+            }
+            total += BigInt(amount.toString());
+        }
+        return 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 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 = 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(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 = get(body, 'transaction_id');
+        if (!response.successful() || get(body, 'message') !== 'success' || transactionId === '') {
+            const message = errorMessage(body);
+            throw new ApiError(`Wave Money payment request failed with HTTP ${response.status}: ${message}`, {
+                gatewayCode: 'errors' in body ? 'VALIDATION_ERROR' : optional(body, 'message'),
+                gatewayMessage: message,
+                httpStatus: response.status,
+                raw: toPlainObject(body),
+            });
+        }
+        return new RedirectPayment({
+            orderId: data.orderId,
+            url: `${this.config.authenticateUrl}/authenticate?transaction_id=${queryEscape(transactionId)}`,
+            gatewayReference: transactionId,
+            raw: 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 = losslessBody(request);
+        const expected = this.hash(CALLBACK_FIELDS.map((field) => scalarString(payload[field]) ?? 'null'));
+        const hashValue = payload.hashValue;
+        if (typeof hashValue !== 'string' || !safeEqual(expected, hashValue.toLowerCase())) {
+            throw new SignatureVerificationError('Wave Money callback hash verification failed.', toPlainObject(payload));
+        }
+        const gatewayStatus = trimmed(payload, 'status');
+        return new PaymentCallback({
+            orderId: get(payload, 'orderId') || get(payload, 'merchantReferenceId'),
+            status: resolveStatus(STATUSES, gatewayStatus),
+            gatewayStatus,
+            gatewayReference: optional(payload, 'transactionId'),
+            amount: optional(payload, 'amount'),
+            raw: toPlainObject(payload),
+        });
+    }
+    hash(parts) {
+        return hmacSha256Hex(this.config.secretKey, parts.join(''));
+    }
+}
+function errorMessage(body) {
+    const errors = body.errors;
+    if (isLosslessObject(errors)) {
+        return Object.keys(errors)
+            .sort()
+            .map((field) => {
+            const list = errors[field];
+            const texts = (Array.isArray(list) ? list : [list])
+                .map((item) => scalarString(item))
+                .filter((text) => text !== undefined);
+            return `${field}: ${texts.join(' ')}`;
+        })
+            .join('; ');
+    }
+    return get(body, 'message') || 'unexpected response';
+}

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

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

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

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

package/dist/esm/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;
+}