@laranex/myanmar-payments 4.0.0-dev.1 → 4.0.0-dev.11

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

@@ -11,38 +11,45 @@ export interface WaveMoneyConfigOptions {
     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. */
+    /**
+     * How long the customer has to pay, in seconds: a whole number greater than 0 (or its text). A
+     * payment's own `timeToLiveSeconds` overrides it. Unset or blank is allowed, but then every
+     * payment must set its own.
+     */
+    timeToLiveSeconds?: number | string | null | undefined;
+    /**
+     * Seconds before the default HTTP client gives up on a request, a whole number greater than 0
+     * (or its text). Defaults to 30 (`DEFAULT_TIMEOUT_SECONDS`) when unset or blank. A
+     * client you pass keeps its own timeout.
+     */
+    timeoutSeconds?: number | string | null | undefined;
+    /** Overrides the API base URL, e.g. to point at UAT. */
     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`.
+ * Wave Money credentials and endpoints. A missing setting throws a `ConfigurationError`. The URLs
+ * default to production.
  */
 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;
+    /** Seconds the customer has to pay unless the payment sets its own; `undefined` when unset. */
+    readonly timeToLiveSeconds: number | undefined;
+    /** Seconds before the default HTTP client gives up on a request. */
+    readonly timeoutSeconds: number;
     /** 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`
+     * Reads `WAVE_MONEY_MERCHANT_ID`, `WAVE_MONEY_SECRET_KEY`, `WAVE_MONEY_MERCHANT_NAME`,
+     * `WAVE_MONEY_TIME_TO_LIVE_IN_SECONDS`, `MYANMAR_PAYMENTS_HTTP_TIMEOUT`, `WAVE_MONEY_BASE_URL`
      * and `WAVE_MONEY_AUTHENTICATE_URL`.
      */
     static fromEnv(env?: EnvSource): WaveMoneyConfig;
@@ -76,6 +83,16 @@ export interface WaveMoneyPaymentData {
      * this.
      */
     merchantReferenceId?: string | undefined;
+    /**
+     * The business name shown on Wave's page for this payment. Defaults to the configured
+     * `merchantName` when unset.
+     */
+    merchantName?: string | null | undefined;
+    /**
+     * How long the customer has to pay this payment, in seconds: a whole number greater than 0.
+     * Defaults to the configured `timeToLiveSeconds` when unset; one of the two is required.
+     */
+    timeToLiveSeconds?: number | null | undefined;
 }
 /**
  * Wave Money (WavePay payment gateway): redirect payments and callbacks. Wave has no status API,
@@ -98,13 +115,14 @@ export declare class WaveMoney {
     /**
      * 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.
+     * afterwards. Invalid data is left untouched. Throws `InvalidPaymentDataError` before any request
+     * when neither the payment nor the config sets a time to live.
      */
     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.
+     * optional. A hashed field holding an object or array fails verification.
      */
     handleCallback(request: CallbackRequest): PaymentCallback;
     private hash;

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

@@ -1,29 +1,28 @@
 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 { defaultEnv, envFirst, HTTP_TIMEOUT_VARIABLE, optionalSetting, optionalSeconds, requireSetting, resolveTimeout, trimUrl, } from '../core/env.js';
+import { ApiError, InvalidPaymentDataError, 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';
+import { get, isNested, optional, scalarString, trimmed } from '../core/values.js';
 /**
- * Wave Money credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ * Wave Money credentials and endpoints. A missing setting throws a `ConfigurationError`. The URLs
+ * default to production.
  */
 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. */
+    /** Seconds the customer has to pay unless the payment sets its own; `undefined` when unset. */
     timeToLiveSeconds;
-    sandbox;
+    /** Seconds before the default HTTP client gives up on a request. */
+    timeoutSeconds;
     /** The API base URL in use. */
     baseUrl;
     /** The host the customer is redirected to. */
@@ -32,31 +31,23 @@ export class WaveMoneyConfig {
         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));
+        this.timeToLiveSeconds = optionalSeconds('wave_money', 'time_to_live_in_seconds', options.timeToLiveSeconds);
+        this.timeoutSeconds = resolveTimeout('wave_money', options.timeoutSeconds);
+        this.baseUrl = trimUrl(optionalSetting(options.baseUrl) ?? WaveMoneyConfig.PRODUCTION_URL);
+        this.authenticateUrl = trimUrl(optionalSetting(options.authenticateUrl) ?? 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`
+     * Reads `WAVE_MONEY_MERCHANT_ID`, `WAVE_MONEY_SECRET_KEY`, `WAVE_MONEY_MERCHANT_NAME`,
+     * `WAVE_MONEY_TIME_TO_LIVE_IN_SECONDS`, `MYANMAR_PAYMENTS_HTTP_TIMEOUT`, `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'),
+            merchantName: envFirst(env, 'WAVE_MONEY_MERCHANT_NAME'),
+            timeToLiveSeconds: envFirst(env, 'WAVE_MONEY_TIME_TO_LIVE_IN_SECONDS'),
+            timeoutSeconds: envFirst(env, HTTP_TIMEOUT_VARIABLE),
             baseUrl: envFirst(env, 'WAVE_MONEY_BASE_URL'),
             authenticateUrl: envFirst(env, 'WAVE_MONEY_AUTHENTICATE_URL'),
         });
@@ -67,7 +58,7 @@ const STATUSES = {
     INSUFFICIENT_BALANCE: 'pending',
     ACCOUNT_LOCKED: 'failed',
     BILL_COLLECTION_FAILED: 'failed',
-    PAYMENT_REQUEST_CANCELLED: 'cancelled',
+    PAYMENT_REQUEST_CANCELLED: 'canceled',
     TRANSACTION_TIMED_OUT: 'expired',
     SCHEDULER_TRANSACTION_TIMED_OUT: 'expired',
 };
@@ -94,7 +85,7 @@ export class WaveMoney {
     transport;
     constructor(config, options = {}) {
         this.config = config instanceof WaveMoneyConfig ? config : new WaveMoneyConfig(config);
-        this.transport = new Transport(httpClientFrom(options));
+        this.transport = new Transport(httpClientFrom(options, this.config.timeoutSeconds));
     }
     /** A gateway configured from the `WAVE_MONEY_*` environment variables. */
     static fromEnv(env = defaultEnv(), options = {}) {
@@ -132,7 +123,11 @@ export class WaveMoney {
             .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);
+            .string('merchantReferenceId', data.merchantReferenceId)
+            .string('merchantName', data.merchantName)
+            .when(typeof data.merchantName === 'string' && data.merchantName.trim() === '', 'merchantName', 'The merchantName field is required.')
+            .when(isSet(data.timeToLiveSeconds) && !Number.isInteger(data.timeToLiveSeconds), 'timeToLiveSeconds', 'The timeToLiveSeconds field must be an integer.')
+            .when(isSet(data.timeToLiveSeconds) && data.timeToLiveSeconds < 1, 'timeToLiveSeconds', 'The timeToLiveSeconds field must be greater than 0.');
         items.forEach((item, index) => {
             validator
                 .required(`items.${index}.name`, item?.name)
@@ -150,15 +145,22 @@ export class WaveMoney {
     /**
      * 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.
+     * afterwards. Invalid data is left untouched. Throws `InvalidPaymentDataError` before any request
+     * when neither the payment nor the config sets a time to live.
      */
     async initiate(data, options = {}) {
         WaveMoney.validate(data);
+        const timeToLiveSeconds = data.timeToLiveSeconds ?? this.config.timeToLiveSeconds;
+        if (timeToLiveSeconds === undefined) {
+            throw new InvalidPaymentDataError({
+                timeToLiveSeconds: 'The timeToLiveSeconds field is required when the wave_money configuration has no [time_to_live_in_seconds].',
+            });
+        }
         if (!data.merchantReferenceId) {
             data.merchantReferenceId = randomHex();
         }
         const amount = WaveMoney.resolvedAmount(data).toString();
-        const ttl = String(this.config.timeToLiveSeconds);
+        const ttl = String(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
@@ -173,7 +175,7 @@ export class WaveMoney {
             backend_result_url: data.callbackUrl,
             amount,
             payment_description: data.description,
-            merchant_name: this.config.merchantName,
+            merchant_name: data.merchantName ?? this.config.merchantName,
             items,
             hash: this.hash([
                 ttl,
@@ -205,13 +207,15 @@ export class WaveMoney {
     /**
      * 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.
+     * optional. A hashed field holding an object or array fails verification.
      */
     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())) {
+        if (typeof hashValue !== 'string' ||
+            CALLBACK_FIELDS.some((field) => isNested(payload[field])) ||
+            !safeEqual(expected, hashValue.toLowerCase())) {
             throw new SignatureVerificationError('Wave Money callback hash verification failed.', toPlainObject(payload));
         }
         const gatewayStatus = trimmed(payload, 'status');
@@ -228,6 +232,9 @@ export class WaveMoney {
         return hmacSha256Hex(this.config.secretKey, parts.join(''));
     }
 }
+function isSet(value) {
+    return value !== undefined && value !== null;
+}
 function errorMessage(body) {
     const errors = body.errors;
     if (isLosslessObject(errors)) {

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

@@ -16,35 +16,39 @@ export interface YomaMmqrConfigOptions {
     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. */
+    /** The `{version}` segment of the API paths, e.g. `v1rc`. */
+    apiVersion: string;
+    /**
+     * Seconds before the default HTTP client gives up on a request, a whole number greater than 0
+     * (or its text). Defaults to 30 (`DEFAULT_TIMEOUT_SECONDS`) when unset or blank. A
+     * client you pass keeps its own timeout.
+     */
+    timeoutSeconds?: number | string | null | undefined;
+    /** Overrides the API base URL, e.g. to point at UAT. */
     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`.
+ * Yoma MMQR credentials and endpoints. A missing setting throws a `ConfigurationError`. The URL
+ * defaults to production.
  */
 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 `{version}` segment of the API paths. */
+    readonly apiVersion: string;
+    /** Seconds before the default HTTP client gives up on a request. */
+    readonly timeoutSeconds: number;
     /** 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`.
+     * `YOMA_MMQR_WEBHOOK_HASHKEY`, `YOMA_MMQR_API_VERSION`, `MYANMAR_PAYMENTS_HTTP_TIMEOUT`,
+     * `YOMA_MMQR_WEBHOOK_SECRET` and `YOMA_MMQR_BASE_URL`.
      */
     static fromEnv(env?: EnvSource): YomaMmqrConfig;
 }

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

@@ -2,46 +2,45 @@ 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 { defaultEnv, envFirst, HTTP_TIMEOUT_VARIABLE, optionalSetting, requireSetting, resolveTimeout, 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';
+import { get, isNested, optional, trimmed } from '../core/values.js';
 /**
- * Yoma MMQR credentials and endpoints. A missing credential throws a `ConfigurationError`.
+ * Yoma MMQR credentials and endpoints. A missing setting throws a `ConfigurationError`. The URL
+ * defaults to production.
  */
 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 `{version}` segment of the API paths. */
+    apiVersion;
+    /** Seconds before the default HTTP client gives up on a request. */
+    timeoutSeconds;
     /** 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.apiVersion = requireSetting('yoma_mmqr', 'api_version', options.apiVersion);
+        this.timeoutSeconds = resolveTimeout('yoma_mmqr', options.timeoutSeconds);
         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;
+        this.baseUrl = trimUrl(optionalSetting(options.baseUrl) ?? YomaMmqrConfig.PRODUCTION_URL);
     }
     /**
      * 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`.
+     * `YOMA_MMQR_WEBHOOK_HASHKEY`, `YOMA_MMQR_API_VERSION`, `MYANMAR_PAYMENTS_HTTP_TIMEOUT`,
+     * `YOMA_MMQR_WEBHOOK_SECRET` and `YOMA_MMQR_BASE_URL`.
      */
     static fromEnv(env = defaultEnv()) {
         return new YomaMmqrConfig({
@@ -49,10 +48,10 @@ export class YomaMmqrConfig {
             clientId: envFirst(env, 'YOMA_MMQR_CLIENT_ID'),
             clientSecret: envFirst(env, 'YOMA_MMQR_CLIENT_SECRET'),
             webhookHashKey: envFirst(env, 'YOMA_MMQR_WEBHOOK_HASHKEY'),
+            apiVersion: envFirst(env, 'YOMA_MMQR_API_VERSION'),
+            timeoutSeconds: envFirst(env, HTTP_TIMEOUT_VARIABLE),
             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'),
         });
     }
 }
@@ -76,7 +75,7 @@ export class YomaMmqr {
     pendingToken;
     constructor(config, options = {}) {
         this.config = config instanceof YomaMmqrConfig ? config : new YomaMmqrConfig(config);
-        this.transport = new Transport(httpClientFrom(options));
+        this.transport = new Transport(httpClientFrom(options, this.config.timeoutSeconds));
         this.cache = options.tokenCache ?? new MemoryTokenCache();
     }
     /** A gateway configured from the `YOMA_MMQR_*` environment variables. */
@@ -158,7 +157,9 @@ export class YomaMmqr {
         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())) {
+        if (orderNumber === '' ||
+            isNested(payload.status) ||
+            !safeEqual(expected, get(payload, 'hashValue').toLowerCase())) {
             throw new SignatureVerificationError('Yoma MMQR callback hash verification failed.', toPlainObject(payload));
         }
         return new PaymentCallback({
@@ -207,13 +208,14 @@ export class YomaMmqr {
         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);
+        // The leading digits of `expires_in`; missing, non-numeric or 0 means an hour.
+        const expiresIn = Number(/^\d+/.exec(get(body, 'expires_in'))?.[0] ?? 0);
+        const ttl = Math.max(60, (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}`)}`;
+        return `myanmar-payments.yoma-mmqr.token.${sha256Hex(`${this.config.baseUrl}|${this.config.clientId}`)}`;
     }
 }
 function apiError(endpoint, status, body, errorCode) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@laranex/myanmar-payments",
-  "version": "4.0.0-dev.1",
-  "description": "Node.js and TypeScript SDK for Myanmar payment gateways: KBZ Pay, Wave Money, AYA Payment Gateway, Yoma MMQR and CyberSource.",
+  "version": "4.0.0-dev.11",
+  "description": "Node.js SDK for Myanmar payment gateways: KBZ Pay, Wave Money, AYA Pay, Yoma MMQR and CyberSource. Typed requests and results, exact amounts, no runtime dependencies.",
   "keywords": [
     "laranex",
     "node-myanmar-payments",

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

@@ -11,7 +11,7 @@ metadata:
 
 ## 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.
+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. In NestJS, use `@laranex/nestjs-myanmar-payments` instead; it wraps this package.
 
 ## Install
 
@@ -19,11 +19,11 @@ Use this skill when a Node.js or TypeScript app takes payments through KBZ Pay,
 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`.
+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` and `/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.
+`MyanmarPayments.fromEnv(process.env)` reads `KBZ_PAY_*`, `WAVE_MONEY_*`, `AYA_PAY_*` (or `AYA_PGW_*`), `YOMA_MMQR_*` and `CYBER_SOURCE_*` plus `MYANMAR_PAYMENTS_HTTP_TIMEOUT` (the same variables as the PHP, Go and Python SDKs). Every gateway defaults to its production URLs; to test against UAT, set the URL overrides (`KBZ_PAY_BASE_URL`, `KBZ_PAY_PWA_BASE_REDIRECT_URL`, `WAVE_MONEY_BASE_URL`, `WAVE_MONEY_AUTHENTICATE_URL`, `AYA_PAY_BASE_URL`, `YOMA_MMQR_BASE_URL`, `CYBER_SOURCE_BASE_URL`) to the gateway's UAT URLs. The HTTP timeout `timeoutSeconds` / `MYANMAR_PAYMENTS_HTTP_TIMEOUT` (seconds, for every gateway except CyberSource) is optional and defaults to 30 (`DEFAULT_TIMEOUT_SECONDS`); an explicit value must be a whole number greater than 0. Time to live: `KBZ_PAY_TIME_TO_LIVE_IN_MINUTES` (KBZ's `timeToLiveMinutes`, 1 to 120) and `WAVE_MONEY_TIME_TO_LIVE_IN_SECONDS` (Wave's `timeToLiveSeconds`, greater than 0) are optional defaults; a payment's `timeToLiveMinutes` / `timeToLiveSeconds` overrides them, and a payment with neither throws `InvalidPaymentDataError` before any request. Every other setting is required, with no defaults: credentials, Wave's `merchantName`, and Yoma's `apiVersion` (e.g. `v1rc`).
 
 ```ts
 import { MyanmarPayments } from '@laranex/myanmar-payments';
@@ -32,18 +32,21 @@ const payments = MyanmarPayments.fromEnv(process.env); // create once, share acr
 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`).
+- Or build one gateway: `new KbzPay(new KbzPayConfig({ appId, appKey, merchantCode }))`, `KbzPay.fromEnv()` or `new KbzPay(KbzPayConfig.fromEnv(process.env))`.
+- Or pass the settings directly: gateways and `new MyanmarPayments({ kbzPay: { appId, appKey, merchantCode } })` take config objects or plain option objects; whole-number settings also take text such as `'30'`.
+- Options (second argument): `{ httpClient, fetch }`. Without `httpClient`, the gateway uses `fetch` with the config's `timeoutSeconds`; a client you pass keeps its own timeout. Yoma and the facade also take `tokenCache` (any `TokenCache`, default `MemoryTokenCache`; back it with Redis when you run several processes).
+- A missing setting throws `ConfigurationError` (`gateway`, `key`); a time setting that is not a whole number greater than 0 throws it too.
 
 ## 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.
+Amounts are `Amount.kyat(1000)`, `Amount.parse('1000.50')` or a whole `number`/`bigint`; never a float such as `10.5`. 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. Compare a gateway's amount by value with `amount.equals(callback.amount)`.
 
 ### Start a payment
 
+Each gateway takes a data object (`KbzPayPaymentData`, `WaveMoneyPaymentData` with `WaveMoneyItem`s, `AyaPayPaymentData` with an `AyaPayMethod`, `YomaMmqrPaymentData`, `CyberSourcePaymentData` with a `CyberSourceTransactionType`) and returns a typed result:
+
 ```ts
 import { Amount } from '@laranex/myanmar-payments';
 
@@ -55,20 +58,23 @@ const payment = await kbz.pwa({
 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.
+- `RedirectPayment` (`url`) from `kbz.pwa(data)` and `wave.initiate(data)`. Wave fills `data.merchantReferenceId` when empty; store it. Pass `merchantName` or `timeToLiveSeconds` in Wave's payment data to override the configured `WAVE_MONEY_MERCHANT_NAME` or `WAVE_MONEY_TIME_TO_LIVE_IN_SECONDS` for that one payment (the merchant name setting stays required).
+- `FormPayment` from `aya.initiate(data)` and `cyberSource.initiate(data)` (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.
+- `AppPayment` from `kbz.app(data)`: `res.json(payment)` sends `orderId`, `orderInfo`, `sign` and `signType` to your mobile app.
+
+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 })`. 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 })`.
+CyberSource has no payment defaults: pass `currency` (e.g. `'MMK'`), `transactionType` (e.g. `CyberSourceTransactionType.Sale`) and `locale` (e.g. `'en-us'`) on every `cyberSource.initiate(data)`.
 
 ### Handle the callback
 
+Build a `CallbackRequest` from the raw request, verify it, then reply:
+
 ```ts
 import { CallbackRequest, SignatureVerificationError } from '@laranex/myanmar-payments';
 
-const request = await CallbackRequest.fromNodeRequest(req); // or fromWebRequest(request) for Fetch servers
+const request = await CallbackRequest.fromNodeRequest(req); // or fromWebRequest(request)
 try {
   const callback = kbz.handleCallback(request);
   if (callback.isSuccessful()) {
@@ -76,22 +82,20 @@ try {
   }
   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;
+  if (!(error instanceof SignatureVerificationError)) throw error;
+  res.writeHead(400).end('invalid signature');
 }
 ```
 
-- Give the callback route the raw body: in Express use `express.raw({ type: '*/*' })` or mount it before `express.json()`.
+- Give the package the raw body: in Express use `express.raw({ type: '*/*' })` on the callback route; in Fastify keep the body as a string (`parseAs: 'string'`) and build `CallbackRequest.from({ body, headers, query })`.
 - Check AYA's browser return with `aya.verifyRedirect(request)`.
-- For production, store the verified call, acknowledge immediately, then process it once in the background.
+- For production, store the verified callback, 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`.
+- Statuses: `PaymentStatus.Successful`, `Pending`, `Failed`, `Canceled`, `Expired`, `Unknown`; `PaymentStatus.isFinal(status)`.
+- Gateway failures throw `ApiError` (`gatewayCode`, `gatewayMessage`, `httpStatus`, `raw`; network errors and aborts are the `cause`). All errors extend `PaymentError`.
 
 ## Test your app
 
@@ -104,6 +108,6 @@ try {
 - 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.
+- Building the `CallbackRequest` from `req.body` parsed by `express.json()` instead of 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.