@laranex/myanmar-payments 4.0.0-dev.3 → 4.0.0-dev.4

package/dist/esm/core/callback.d.ts

@@ -42,8 +42,10 @@ export interface WebRequestLike {
  * {@link CallbackRequest.fromNodeRequest} or {@link CallbackRequest.fromWebRequest}.
  */
 export declare class CallbackRequest {
-    /** The raw request body, decoded as UTF-8. */
+    /** The request body as text: a string body as given, bytes decoded as UTF-8. */
     readonly body: string;
+    /** The exact bytes received. A string body is encoded as UTF-8. */
+    readonly rawBody: Uint8Array;
     /** The request headers, with lowercase names. Repeated headers are joined with `, `. */
     readonly headers: Readonly<Record<string, string>>;
     /** The query string parameters (the first value of each). */
@@ -71,7 +73,10 @@ export declare class CallbackRequest {
     static fromWebRequest(request: WebRequestLike): Promise<CallbackRequest>;
     /** The named header, matched case-insensitively, or `undefined`. */
     header(name: string): string | undefined;
-    /** The body decoded as JSON or as a urlencoded form. */
+    /**
+     * The body decoded as JSON or as a urlencoded form. JSON numbers keep their exact text, as strings
+     * (`1000.50` stays `"1000.50"`).
+     */
     parsedBody(): Record<string, unknown>;
     /** The parsed body merged over the query string. */
     input(): Record<string, unknown>;

package/dist/esm/core/callback.js

@@ -5,14 +5,17 @@ import { parseJsonObject, setKey, toPlainObject } from './json.js';
  * {@link CallbackRequest.fromNodeRequest} or {@link CallbackRequest.fromWebRequest}.
  */
 export class CallbackRequest {
-    /** The raw request body, decoded as UTF-8. */
+    /** The request body as text: a string body as given, bytes decoded as UTF-8. */
     body;
+    /** The exact bytes received. A string body is encoded as UTF-8. */
+    rawBody;
     /** The request headers, with lowercase names. Repeated headers are joined with `, `. */
     headers;
     /** The query string parameters (the first value of each). */
     query;
     constructor(init = {}) {
-        this.body = bodyText(init.body);
+        this.rawBody = bodyBytes(init.body);
+        this.body = typeof init.body === 'string' ? init.body : new TextDecoder().decode(this.rawBody);
         this.headers = Object.freeze(normalizeHeaders(init.headers));
         this.query = Object.freeze(normalizeQuery(init.query));
     }
@@ -68,7 +71,10 @@ export class CallbackRequest {
     header(name) {
         return this.headers[name.toLowerCase()];
     }
-    /** The body decoded as JSON or as a urlencoded form. */
+    /**
+     * The body decoded as JSON or as a urlencoded form. JSON numbers keep their exact text, as strings
+     * (`1000.50` stays `"1000.50"`).
+     */
     parsedBody() {
         return toPlainObject(losslessBody(this));
     }
@@ -207,14 +213,15 @@ export class PaymentStatusResult {
         return this.status === 'successful';
     }
 }
-function bodyText(body) {
+function bodyBytes(body) {
     if (body === undefined || body === null) {
-        return '';
+        return new Uint8Array();
     }
     if (typeof body === 'string') {
-        return body;
+        return new TextEncoder().encode(body);
     }
-    return new TextDecoder().decode(body);
+    // A copy, so later changes to the caller's buffer cannot alter what was verified.
+    return body instanceof ArrayBuffer ? new Uint8Array(body.slice(0)) : Uint8Array.from(body);
 }
 function rawBody(value) {
     if (typeof value === 'string' || value instanceof Uint8Array || value instanceof ArrayBuffer) {

package/dist/esm/core/crypto.d.ts

@@ -15,5 +15,10 @@ export declare function randomHex(bytes?: number): string;
  * @internal
  */
 export declare function queryEscape(value: string): string;
-/** Decodes strict standard base64 (with padding), or `undefined`. @internal */
+/**
+ * Decodes standard base64 (`A-Z a-z 0-9 + /`), either correctly padded or without any padding, to
+ * UTF-8 text. Partial padding, other characters and bytes that are not UTF-8 return `undefined`.
+ *
+ * @internal
+ */
 export declare function decodeBase64(value: string): string | undefined;

package/dist/esm/core/crypto.js

@@ -32,10 +32,24 @@ export function queryEscape(value) {
         .replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)
         .replace(/%20/g, '+');
 }
-/** Decodes strict standard base64 (with padding), or `undefined`. @internal */
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
+/**
+ * Decodes standard base64 (`A-Z a-z 0-9 + /`), either correctly padded or without any padding, to
+ * UTF-8 text. Partial padding, other characters and bytes that are not UTF-8 return `undefined`.
+ *
+ * @internal
+ */
 export function decodeBase64(value) {
-    if (value === '' || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value)) {
+        return undefined;
+    }
+    if (value.includes('=') ? value.length % 4 !== 0 : value.length % 4 === 1) {
+        return undefined;
+    }
+    try {
+        return UTF8.decode(Buffer.from(value, 'base64'));
+    }
+    catch {
         return undefined;
     }
-    return Buffer.from(value, 'base64').toString('utf8');
 }

package/dist/esm/core/env.d.ts

@@ -9,6 +9,13 @@ export declare function envFirst(env: EnvSource, ...keys: string[]): string;
  * @internal
  */
 export declare function envSandbox(env: EnvSource, key: string): boolean;
+/**
+ * A `sandbox` setting: booleans as is, text parsed like a `*_SANDBOX` variable (`false`, `0`, `f`,
+ * `no` and `off` in any case select production; anything else means sandbox), unset means sandbox.
+ *
+ * @internal
+ */
+export declare function parseSandbox(value: boolean | string | undefined | null): boolean;
 /** An integer variable, or `undefined` when unset or not an integer. @internal */
 export declare function envInt(env: EnvSource, key: string): number | undefined;
 /** The trimmed value, or throws a {@link ConfigurationError} naming `key`. @internal */

package/dist/esm/core/env.js

@@ -16,8 +16,19 @@ export function envFirst(env, ...keys) {
  * @internal
  */
 export function envSandbox(env, key) {
-    const value = env[key]?.trim().toLowerCase() ?? '';
-    return !['false', '0', 'f', 'no', 'off'].includes(value);
+    return parseSandbox(env[key] ?? '');
+}
+/**
+ * A `sandbox` setting: booleans as is, text parsed like a `*_SANDBOX` variable (`false`, `0`, `f`,
+ * `no` and `off` in any case select production; anything else means sandbox), unset means sandbox.
+ *
+ * @internal
+ */
+export function parseSandbox(value) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    return !['false', '0', 'f', 'no', 'off'].includes((value ?? '').trim().toLowerCase());
 }
 /** An integer variable, or `undefined` when unset or not an integer. @internal */
 export function envInt(env, key) {

package/dist/esm/core/json.d.ts

@@ -32,8 +32,8 @@ export declare function parseJsonObject(text: string): LosslessObject | undefine
 /** @internal */
 export declare function isLosslessObject(value: unknown): value is LosslessObject;
 /**
- * Converts a lossless value to plain JavaScript values (numbers become `number`), for the `raw`
- * fields of results.
+ * Converts a lossless value to plain JavaScript values for the `raw` fields of results. Numbers
+ * become their exact text as a string (`1000.50` stays `"1000.50"`), so no precision is lost.
  *
  * @internal
  */

package/dist/esm/core/json.js

@@ -46,14 +46,14 @@ export function isLosslessObject(value) {
         !(value instanceof JsonNumber));
 }
 /**
- * Converts a lossless value to plain JavaScript values (numbers become `number`), for the `raw`
- * fields of results.
+ * Converts a lossless value to plain JavaScript values for the `raw` fields of results. Numbers
+ * become their exact text as a string (`1000.50` stays `"1000.50"`), so no precision is lost.
  *
  * @internal
  */
 export function toPlain(value) {
     if (value instanceof JsonNumber) {
-        return Number(value.text);
+        return value.text;
     }
     if (Array.isArray(value)) {
         return value.map(toPlain);

package/dist/esm/core/values.d.ts

@@ -14,3 +14,5 @@ export declare function optional(source: Record<string, unknown>, key: string):
 export declare function trimmed(source: Record<string, unknown>, key: string): string;
 /** The value at `key` when it is an object (not an array). @internal */
 export declare function object(source: Record<string, unknown>, key: string): LosslessObject | undefined;
+/** Whether `value` is an object or array, which a gateway never signs. @internal */
+export declare function isNested(value: unknown): boolean;

package/dist/esm/core/values.js

@@ -36,3 +36,7 @@ export function object(source, key) {
     const value = source[key];
     return isLosslessObject(value) ? value : undefined;
 }
+/** Whether `value` is an object or array, which a gateway never signs. @internal */
+export function isNested(value) {
+    return typeof value === 'object' && value !== null && !(value instanceof JsonNumber);
+}

package/dist/esm/cyber-source/cyber-source.d.ts

@@ -10,8 +10,11 @@ export interface CyberSourceConfigOptions {
     accessKey: string;
     /** The profile's secret key, which signs the fields. */
     secretKey: string;
-    /** Use the test environment (default `true`). */
-    sandbox?: boolean | undefined;
+    /**
+     * Use the test environment (default `true`).
+     * Text is read like a `*_SANDBOX` variable: `false`, `0`, `f`, `no` or `off` select production.
+     */
+    sandbox?: boolean | string | undefined;
     /** Overrides the Secure Acceptance base URL. */
     baseUrl?: string | undefined;
 }

package/dist/esm/cyber-source/cyber-source.js

@@ -1,7 +1,7 @@
 import {} from '../core/amount.js';
 import { CallbackRequest, losslessInput, PaymentCallback } from '../core/callback.js';
 import { hmacSha256Base64, randomHex, safeEqual } from '../core/crypto.js';
-import { defaultEnv, envFirst, envSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
+import { defaultEnv, envFirst, envSandbox, parseSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
 import { SignatureVerificationError } from '../core/errors.js';
 import { setKey, toPlainObject } from '../core/json.js';
 import { FormPayment } from '../core/results.js';
@@ -24,7 +24,7 @@ export class CyberSourceConfig {
         this.profileId = requireSetting('cyber_source', 'profile_id', options.profileId);
         this.accessKey = requireSetting('cyber_source', 'access_key', options.accessKey);
         this.secretKey = requireSetting('cyber_source', 'secret_key', options.secretKey);
-        this.sandbox = options.sandbox ?? true;
+        this.sandbox = parseSandbox(options.sandbox);
         this.baseUrl = trimUrl(optionalSetting(options.baseUrl) ??
             (this.sandbox ? CyberSourceConfig.SANDBOX_URL : CyberSourceConfig.PRODUCTION_URL));
     }

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

@@ -12,8 +12,12 @@ export interface KbzPayConfigOptions {
     appKey: string;
     /** The `merch_code` KBZ issued. */
     merchantCode: string;
-    /** Use the UAT endpoints (default `true`). UAT and production issue separate credentials. */
-    sandbox?: boolean | undefined;
+    /**
+     * Use the UAT endpoints (default `true`). UAT and production issue separate
+     * credentials. Text is read like a `*_SANDBOX` variable: `false`, `0`, `f`, `no` or `off`
+     * select production.
+     */
+    sandbox?: boolean | string | undefined;
     /** Overrides the API base URL, e.g. to go through a proxy. */
     apiUrl?: string | undefined;
     /** Overrides the PWA checkout URL. A trailing `#` or `#/` is normalized to `#/`. */

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

@@ -1,7 +1,7 @@
 import {} from '../core/amount.js';
 import { Acknowledgement, CallbackRequest, losslessBody, PaymentCallback, PaymentStatusResult, } from '../core/callback.js';
 import { queryEscape, randomHex } from '../core/crypto.js';
-import { defaultEnv, envFirst, envSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
+import { defaultEnv, envFirst, envSandbox, parseSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
 import { ApiError, SignatureVerificationError } from '../core/errors.js';
 import { httpClientFrom, Transport, } from '../core/http.js';
 import { toPlainObject } from '../core/json.js';
@@ -30,7 +30,7 @@ export class KbzPayConfig {
         this.appId = requireSetting('kbz_pay', 'app_id', options.appId);
         this.appKey = requireSetting('kbz_pay', 'app_key', options.appKey);
         this.merchantCode = requireSetting('kbz_pay', 'merchant_code', options.merchantCode);
-        this.sandbox = options.sandbox ?? true;
+        this.sandbox = parseSandbox(options.sandbox);
         this.apiUrl = trimUrl(optionalSetting(options.apiUrl) ??
             (this.sandbox ? KbzPayConfig.SANDBOX_API_URL : KbzPayConfig.PRODUCTION_API_URL));
         this.pwaUrl = `${trimUrl(optionalSetting(options.pwaUrl) ??

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

@@ -10,6 +10,9 @@ export declare class KbzPaySigner {
     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. */
+    /**
+     * Whether `fields.sign` matches, compared in constant time. Nested values are never signed, so
+     * fields holding an object or array fail rather than being partly trusted.
+     */
     verify(fields: Readonly<Record<string, unknown>>): boolean;
 }

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

@@ -1,5 +1,5 @@
 import { safeEqual, sha256Hex } from '../core/crypto.js';
-import { scalarString } from '../core/values.js';
+import { isNested, 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
@@ -24,9 +24,14 @@ export class KbzPaySigner {
     sign(fields) {
         return sha256Hex(`${this.signString(fields)}&key=${this.appKey}`).toUpperCase();
     }
-    /** Whether `fields.sign` matches, compared in constant time. */
+    /**
+     * Whether `fields.sign` matches, compared in constant time. Nested values are never signed, so
+     * fields holding an object or array fail rather than being partly trusted.
+     */
     verify(fields) {
         const sign = fields.sign;
-        return typeof sign === 'string' && safeEqual(this.sign(fields), sign.toUpperCase());
+        return (typeof sign === 'string' &&
+            !Object.values(fields).some(isNested) &&
+            safeEqual(this.sign(fields), sign.toUpperCase()));
     }
 }

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

@@ -13,8 +13,11 @@ export interface WaveMoneyConfigOptions {
     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;
+    /**
+     * Use the test environment (default `true`).
+     * Text is read like a `*_SANDBOX` variable: `false`, `0`, `f`, `no` or `off` select production.
+     */
+    sandbox?: boolean | string | undefined;
     /** Overrides the API base URL. */
     baseUrl?: string | undefined;
     /** Overrides the host the customer is redirected to. Wave serves it without the API port. */
@@ -104,7 +107,7 @@ export declare 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: CallbackRequest): PaymentCallback;
     private hash;

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

@@ -1,14 +1,14 @@
 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 { defaultEnv, envFirst, envInt, envSandbox, parseSandbox, 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';
+import { get, isNested, optional, scalarString, trimmed } from '../core/values.js';
 /**
  * Wave Money credentials and endpoints. A missing credential throws a `ConfigurationError`.
  */
@@ -37,7 +37,7 @@ export class WaveMoneyConfig {
             ttl !== undefined && Number.isInteger(ttl) && ttl > 0
                 ? ttl
                 : WaveMoneyConfig.DEFAULT_TIME_TO_LIVE_SECONDS;
-        this.sandbox = options.sandbox ?? true;
+        this.sandbox = parseSandbox(options.sandbox);
         this.baseUrl = trimUrl(optionalSetting(options.baseUrl) ??
             (this.sandbox ? WaveMoneyConfig.SANDBOX_URL : WaveMoneyConfig.PRODUCTION_URL));
         this.authenticateUrl = trimUrl(optionalSetting(options.authenticateUrl) ??
@@ -205,13 +205,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');

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

@@ -16,8 +16,11 @@ 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;
+    /**
+     * Use the UAT payment hub (default `true`).
+     * Text is read like a `*_SANDBOX` variable: `false`, `0`, `f`, `no` or `off` select production.
+     */
+    sandbox?: boolean | string | undefined;
     /** Overrides the API base URL. */
     baseUrl?: string | undefined;
     /** The `{version}` segment of the API paths (default `v1rc`). */

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

@@ -2,14 +2,14 @@ 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, envSandbox, parseSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
 import { ApiError, SignatureVerificationError } from '../core/errors.js';
 import { httpClientFrom, Transport, } from '../core/http.js';
 import { toPlainObject } from '../core/json.js';
 import { QrPayment } from '../core/results.js';
 import { resolveStatus } from '../core/status.js';
 import { toAmount, Validator } from '../core/validate.js';
-import { get, optional, trimmed } from '../core/values.js';
+import { get, isNested, optional, trimmed } from '../core/values.js';
 /**
  * Yoma MMQR credentials and endpoints. A missing credential throws a `ConfigurationError`.
  */
@@ -33,7 +33,7 @@ export class YomaMmqrConfig {
         this.clientSecret = requireSetting('yoma_mmqr', 'client_secret', options.clientSecret);
         this.webhookHashKey = requireSetting('yoma_mmqr', 'webhook_hashkey', options.webhookHashKey);
         this.webhookSecret = optionalSetting(options.webhookSecret);
-        this.sandbox = options.sandbox ?? true;
+        this.sandbox = parseSandbox(options.sandbox);
         this.baseUrl = trimUrl(optionalSetting(options.baseUrl) ??
             (this.sandbox ? YomaMmqrConfig.SANDBOX_URL : YomaMmqrConfig.PRODUCTION_URL));
         this.apiVersion = optionalSetting(options.apiVersion) ?? YomaMmqrConfig.DEFAULT_API_VERSION;
@@ -158,7 +158,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 +209,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,6 +1,6 @@
 {
   "name": "@laranex/myanmar-payments",
-  "version": "4.0.0-dev.3",
+  "version": "4.0.0-dev.4",
   "description": "Node.js SDK for Myanmar payment gateways: KBZ Pay, Wave Money, AYA Pay, Yoma MMQR and CyberSource. Typed TypeScript API, ESM and CommonJS, no runtime dependencies.",
   "keywords": [
     "laranex",

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_*` (the same variables as the PHP, Go and Python SDKs). `sandbox` defaults to `true`; set `*_SANDBOX=false` (or `sandbox: false`) in production.
 
 ```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).
+- 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; a string `sandbox` such as `'false'` is read like the variable.
+- Options (second argument): `{ httpClient, fetch, timeoutMs }` (default 30 seconds). Yoma and the facade also take `tokenCache` (any `TokenCache`, default `MemoryTokenCache`; back it with Redis when you run several processes).
 - A missing credential throws `ConfigurationError` (`gateway`, `key`).
 
 ## Use
 
 ### Amounts
 
-Amounts are `Amount.kyat(1000)`, `Amount.parse('1000.50')`, or a whole-number `number`/`bigint`; floats like `10.5` are rejected. Only KBZ Pay (up to 2 decimals) and CyberSource accept decimals; Wave, AYA and Yoma take whole kyat. Invalid data throws `InvalidPaymentDataError` with `errors` per field, before any request is sent.
+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';
 
@@ -56,19 +59,20 @@ 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.
+- `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 })`.
+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.
 
 ### 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,23 +80,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()`.
-- Fastify consumes the body before your handler: keep it as a string with a content-type parser (`parseAs: 'string'`) and build `CallbackRequest.from({ body, headers: request.headers, query: request.query })`.
+- 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`, `Canceled`, `Expired`, `Unknown`; `PaymentStatus.isFinal(status)`.
-- Gateway failures throw `ApiError` (`gatewayCode`, `gatewayMessage`, `httpStatus`, `raw`, `cause` for network errors and aborts). All errors extend `PaymentError`.
+- Gateway failures throw `ApiError` (`gatewayCode`, `gatewayMessage`, `httpStatus`, `raw`; network errors and aborts are the `cause`). All errors extend `PaymentError`.
 
 ## Test your app
 
@@ -105,6 +106,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.