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

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

@@ -0,0 +1,122 @@
+import { type AmountInput } from '../core/amount.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 { FormPayment } from '../core/results.js';
+/** The settings of {@link AyaPayConfig}. */
+export interface AyaPayConfigOptions {
+    /** The public application key, sent with every request. */
+    appKey: string;
+    /** The secret that signs requests and verifies callbacks. */
+    appSecret: string;
+    /** Use the UAT environment (default `true`). */
+    sandbox?: boolean | undefined;
+    /** Overrides the gateway base URL. */
+    baseUrl?: string | undefined;
+}
+/**
+ * AYA Payment Gateway (APG) credentials and endpoints. A missing credential throws a
+ * `ConfigurationError`.
+ */
+export declare class AyaPayConfig {
+    static readonly SANDBOX_URL = "https://uat-pgw.ayainnovation.com";
+    static readonly PRODUCTION_URL = "https://pgw.ayainnovation.com";
+    readonly appKey: string;
+    readonly appSecret: string;
+    readonly sandbox: boolean;
+    /** The base URL in use. */
+    readonly baseUrl: string;
+    constructor(options: AyaPayConfigOptions);
+    /**
+     * Reads `AYA_PAY_APP_KEY`, `AYA_PAY_APP_SECRET`, `AYA_PAY_SANDBOX` and `AYA_PAY_BASE_URL`, falling
+     * back to the `AYA_PGW_*` names.
+     */
+    static fromEnv(env?: EnvSource): AyaPayConfig;
+}
+/** How the customer pays through the chosen channel. `services()` lists the methods each channel supports. */
+export type AyaPayMethod = 'WEB' | 'QR' | 'NOTI';
+/** The AYA payment methods. */
+export declare const AyaPayMethod: Readonly<{
+    /** Pay on a hosted web page (cards, web checkout). */
+    readonly Web: "WEB";
+    /** Scan a QR with the wallet app. */
+    readonly Qr: "QR";
+    /** Approve a push notification in the wallet app. */
+    readonly Noti: "NOTI";
+}>;
+/**
+ * An AYA Payment Gateway order. AYA only accepts MMK (currency code 104) and documents no decimals,
+ * so amounts are whole kyat.
+ */
+export interface AyaPayPaymentData {
+    /** Your unique order id (`merchOrderId`), 6 to 40 characters. */
+    orderId: string;
+    /** The amount in whole kyat, e.g. `Amount.kyat(1000)` or `1000`. */
+    amount: AmountInput;
+    /** The channel key from `services()`, e.g. `aya_pay`, `kbz_pay`, `visa`. */
+    channel: string;
+    /** How the customer pays through that channel. */
+    method: AyaPayMethod;
+    /** Where AYA sends the customer afterwards. Defaults to the URL registered with AYA. */
+    returnUrl?: string | undefined;
+    /** Shown to the customer. */
+    description?: string | undefined;
+    /** Up to five of your own reference values, echoed back in the callback. */
+    userRefs?: readonly string[] | undefined;
+}
+/** A payment channel enabled for your merchant account. */
+export declare class AyaPayService {
+    /** The display name, e.g. `AYA Pay`. */
+    readonly name: string;
+    /** The `channel` value to send when initiating, e.g. `aya_pay` or `visa`. */
+    readonly key: string;
+    /** The channel's logo. */
+    readonly imageUrl: string | undefined;
+    /** The methods this channel supports. */
+    readonly methods: readonly AyaPayMethod[];
+    /** Methods the gateway listed that this package does not know yet. */
+    readonly unknownMethods: readonly string[];
+    constructor(init: {
+        name: string;
+        key: string;
+        imageUrl?: string | undefined;
+        methods: readonly AyaPayMethod[];
+        unknownMethods?: readonly string[];
+    });
+    /** Whether the channel supports `method`. */
+    supports(method: AyaPayMethod): boolean;
+}
+/**
+ * The AYA Payment Gateway (APG): one hosted checkout for AYA Pay, other wallets and cards, with
+ * channel listing, status enquiry and verified callbacks.
+ */
+export declare class AyaPay {
+    /** The configuration in use. */
+    readonly config: AyaPayConfig;
+    private readonly transport;
+    constructor(config: AyaPayConfig | AyaPayConfigOptions, options?: GatewayOptions);
+    /** A gateway configured from the `AYA_PAY_*` (or `AYA_PGW_*`) environment variables. */
+    static fromEnv(env?: EnvSource, options?: GatewayOptions): AyaPay;
+    /** Checks the order against AYA's documented rules; throws an `InvalidPaymentDataError`. */
+    static validate(data: AyaPayPaymentData): void;
+    /** Lists the payment channels enabled for your merchant account. */
+    services(options?: RequestOptions): Promise<AyaPayService[]>;
+    /**
+     * Signs the order. The customer's browser must POST the returned form to AYA's hosted checkout;
+     * `toHtml()` renders a page that does it. Makes no network call.
+     */
+    initiate(data: AyaPayPaymentData): FormPayment;
+    /** Asks AYA for the current state of an order (enquiry). */
+    status(orderId: string, options?: RequestOptions): Promise<PaymentStatusResult>;
+    /** Verifies AYA's backend callback. */
+    handleCallback(request: CallbackRequest): PaymentCallback;
+    /**
+     * Verifies the signed query string AYA adds when it sends the customer back to your return URL.
+     * Use it to show the right page; fulfill orders from the backend callback.
+     */
+    verifyRedirect(request: CallbackRequest): PaymentCallback;
+    /** Decodes a `payload` + `checkSum` pair and returns the payload if the checksum matches. */
+    private verifiedPayload;
+    private checksum;
+    private post;
+}

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

@@ -0,0 +1,296 @@
+import {} from '../core/amount.js';
+import { CallbackRequest, losslessInput, losslessQueryInput, PaymentCallback, PaymentStatusResult, } from '../core/callback.js';
+import { decodeBase64, hmacSha256Hex, safeEqual } from '../core/crypto.js';
+import { defaultEnv, envFirst, envSandbox, optionalSetting, requireSetting, trimUrl, } from '../core/env.js';
+import { ApiError, SignatureVerificationError } from '../core/errors.js';
+import { httpClientFrom, Transport, } from '../core/http.js';
+import { isLosslessObject, parseJsonObject, toPlainObject, } from '../core/json.js';
+import { FormPayment } from '../core/results.js';
+import { resolveStatus } from '../core/status.js';
+import { toAmount, Validator } from '../core/validate.js';
+import { get, object, optional, scalarString, trimmed } from '../core/values.js';
+/**
+ * AYA Payment Gateway (APG) credentials and endpoints. A missing credential throws a
+ * `ConfigurationError`.
+ */
+export class AyaPayConfig {
+    static SANDBOX_URL = 'https://uat-pgw.ayainnovation.com';
+    static PRODUCTION_URL = 'https://pgw.ayainnovation.com';
+    appKey;
+    appSecret;
+    sandbox;
+    /** The base URL in use. */
+    baseUrl;
+    constructor(options) {
+        this.appKey = requireSetting('aya_pay', 'app_key', options.appKey);
+        this.appSecret = requireSetting('aya_pay', 'app_secret', options.appSecret);
+        this.sandbox = options.sandbox ?? true;
+        this.baseUrl = trimUrl(optionalSetting(options.baseUrl) ??
+            (this.sandbox ? AyaPayConfig.SANDBOX_URL : AyaPayConfig.PRODUCTION_URL));
+    }
+    /**
+     * Reads `AYA_PAY_APP_KEY`, `AYA_PAY_APP_SECRET`, `AYA_PAY_SANDBOX` and `AYA_PAY_BASE_URL`, falling
+     * back to the `AYA_PGW_*` names.
+     */
+    static fromEnv(env = defaultEnv()) {
+        return new AyaPayConfig({
+            appKey: envFirst(env, 'AYA_PAY_APP_KEY', 'AYA_PGW_APP_KEY'),
+            appSecret: envFirst(env, 'AYA_PAY_APP_SECRET', 'AYA_PGW_APP_SECRET'),
+            sandbox: envSandbox(env, 'AYA_PAY_SANDBOX'),
+            baseUrl: envFirst(env, 'AYA_PAY_BASE_URL', 'AYA_PGW_BASE_URL'),
+        });
+    }
+}
+/** The AYA payment methods. */
+export const AyaPayMethod = Object.freeze({
+    /** Pay on a hosted web page (cards, web checkout). */
+    Web: 'WEB',
+    /** Scan a QR with the wallet app. */
+    Qr: 'QR',
+    /** Approve a push notification in the wallet app. */
+    Noti: 'NOTI',
+});
+const METHODS = ['WEB', 'QR', 'NOTI'];
+/** A payment channel enabled for your merchant account. */
+export class AyaPayService {
+    /** The display name, e.g. `AYA Pay`. */
+    name;
+    /** The `channel` value to send when initiating, e.g. `aya_pay` or `visa`. */
+    key;
+    /** The channel's logo. */
+    imageUrl;
+    /** The methods this channel supports. */
+    methods;
+    /** Methods the gateway listed that this package does not know yet. */
+    unknownMethods;
+    constructor(init) {
+        this.name = init.name;
+        this.key = init.key;
+        this.imageUrl = init.imageUrl;
+        this.methods = Object.freeze([...init.methods]);
+        this.unknownMethods = Object.freeze([...(init.unknownMethods ?? [])]);
+    }
+    /** Whether the channel supports `method`. */
+    supports(method) {
+        return this.methods.includes(method);
+    }
+}
+const CURRENCY_MMK = '104';
+const STATUSES = {
+    '00': 'successful',
+    '01': 'pending',
+    '02': 'failed',
+    '03': 'failed',
+    '04': 'expired',
+};
+/**
+ * The documented field order of the decoded callback / enquiry payload. AYA leaves out fields that
+ * do not apply (e.g. card fields for wallet payments) and signs only the ones present. The payload
+ * spells `currencyCode` as `currenyCode`.
+ */
+const PAYLOAD_FIELDS = [
+    'merchOrderId',
+    'tranId',
+    'amount',
+    'currencyCode',
+    'statusCode',
+    'paymentCardNumber',
+    'paymentMobileNumber',
+    'cardTypeName',
+    'cardExpiryDate',
+    'nameOnCard',
+    'approvalCode',
+    'tranRef',
+    'userRef1',
+    'userRef2',
+    'userRef3',
+    'userRef4',
+    'userRef5',
+    'description',
+    'dateTime',
+];
+/**
+ * The AYA Payment Gateway (APG): one hosted checkout for AYA Pay, other wallets and cards, with
+ * channel listing, status enquiry and verified callbacks.
+ */
+export class AyaPay {
+    /** The configuration in use. */
+    config;
+    transport;
+    constructor(config, options = {}) {
+        this.config = config instanceof AyaPayConfig ? config : new AyaPayConfig(config);
+        this.transport = new Transport(httpClientFrom(options));
+    }
+    /** A gateway configured from the `AYA_PAY_*` (or `AYA_PGW_*`) environment variables. */
+    static fromEnv(env = defaultEnv(), options = {}) {
+        return new AyaPay(AyaPayConfig.fromEnv(env), options);
+    }
+    /** Checks the order against AYA's documented rules; throws an `InvalidPaymentDataError`. */
+    static validate(data) {
+        const userRefs = data.userRefs;
+        new Validator()
+            .required('orderId', data.orderId)
+            .length('orderId', data.orderId, 6, 40)
+            .amount('amount', data.amount, { gateway: 'AYA Payment Gateway', maxDecimals: 0 })
+            .required('channel', data.channel)
+            .when(!METHODS.includes(data.method), 'method', 'The method field must be one of WEB, QR or NOTI.')
+            .string('returnUrl', data.returnUrl)
+            .url('returnUrl', data.returnUrl)
+            .string('description', data.description)
+            .when(userRefs !== undefined &&
+            (!Array.isArray(userRefs) || userRefs.some((ref) => typeof ref !== 'string')), 'userRefs', 'The userRefs field must be a list of strings.')
+            .when(Array.isArray(userRefs) && userRefs.length > 5, 'userRefs', 'The userRefs field must not have more than 5 items.')
+            .validate();
+    }
+    /** Lists the payment channels enabled for your merchant account. */
+    async services(options = {}) {
+        const timestamp = unixTime();
+        const body = await this.post('services', {
+            appKey: this.config.appKey,
+            timestamp,
+            checkSum: this.checksum([this.config.appKey, this.config.appSecret, String(timestamp)]),
+        }, options.signal);
+        const list = Array.isArray(body.data) ? body.data : [];
+        const services = [];
+        for (const entry of list) {
+            if (!isLosslessObject(entry) || get(entry, 'key') === '') {
+                continue;
+            }
+            const methods = [];
+            const unknownMethods = [];
+            for (const method of Array.isArray(entry.methods) ? entry.methods : []) {
+                const name = scalarString(method) ?? '';
+                if (METHODS.includes(name)) {
+                    methods.push(name);
+                }
+                else {
+                    unknownMethods.push(name);
+                }
+            }
+            services.push(new AyaPayService({
+                name: get(entry, 'name') || get(entry, 'key'),
+                key: get(entry, 'key'),
+                imageUrl: optional(entry, 'image_url'),
+                methods,
+                unknownMethods,
+            }));
+        }
+        return services;
+    }
+    /**
+     * Signs the order. The customer's browser must POST the returned form to AYA's hosted checkout;
+     * `toHtml()` renders a page that does it. Makes no network call.
+     */
+    initiate(data) {
+        AyaPay.validate(data);
+        const refs = [...(data.userRefs ?? []), '', '', '', '', ''].slice(0, 5);
+        const fields = [
+            { name: 'merchOrderId', value: data.orderId },
+            { name: 'amount', value: String(toAmount(data.amount)) },
+            { name: 'appKey', value: this.config.appKey },
+            { name: 'timestamp', value: String(unixTime()) },
+            { name: 'userRef1', value: refs[0] },
+            { name: 'userRef2', value: refs[1] },
+            { name: 'userRef3', value: refs[2] },
+            { name: 'userRef4', value: refs[3] },
+            { name: 'userRef5', value: refs[4] },
+            { name: 'description', value: data.description ?? '' },
+            { name: 'currencyCode', value: CURRENCY_MMK },
+            { name: 'channel', value: data.channel },
+            { name: 'method', value: data.method },
+            { name: 'overrideFrontendRedirectUrl', value: data.returnUrl ?? '' },
+        ];
+        fields.push({ name: 'checkSum', value: this.checksum(fields.map((field) => field.value)) });
+        return new FormPayment({
+            orderId: data.orderId,
+            action: `${this.config.baseUrl}/v1/payment/request`,
+            fields,
+            enctype: 'multipart/form-data',
+        });
+    }
+    /** Asks AYA for the current state of an order (enquiry). */
+    async status(orderId, options = {}) {
+        const timestamp = unixTime();
+        const body = await this.post('enquiry', {
+            merchOrderId: orderId,
+            appKey: this.config.appKey,
+            timestamp,
+            checkSum: this.checksum([orderId, String(timestamp), this.config.appKey]),
+        }, options.signal);
+        const payload = this.verifiedPayload(object(body, 'data') ?? {}, 'enquiry response');
+        const statusCode = trimmed(payload, 'statusCode');
+        return new PaymentStatusResult({
+            orderId: optional(payload, 'merchOrderId') || orderId,
+            status: resolveStatus(STATUSES, statusCode),
+            gatewayStatus: statusCode,
+            gatewayReference: optional(payload, 'tranId'),
+            amount: optional(payload, 'amount'),
+            raw: toPlainObject(payload),
+        });
+    }
+    /** Verifies AYA's backend callback. */
+    handleCallback(request) {
+        return toCallback(this.verifiedPayload(losslessInput(request), 'callback'));
+    }
+    /**
+     * Verifies the signed query string AYA adds when it sends the customer back to your return URL.
+     * Use it to show the right page; fulfill orders from the backend callback.
+     */
+    verifyRedirect(request) {
+        return toCallback(this.verifiedPayload(losslessQueryInput(request), 'redirect'));
+    }
+    /** Decodes a `payload` + `checkSum` pair and returns the payload if the checksum matches. */
+    verifiedPayload(input, context) {
+        const fail = () => new SignatureVerificationError(`AYA Pay ${context} checksum verification failed.`, toPlainObject(input));
+        const json = decodeBase64(get(input, 'payload'));
+        const payload = json === undefined ? undefined : parseJsonObject(json);
+        if (payload === undefined) {
+            throw fail();
+        }
+        const parts = [];
+        for (const field of PAYLOAD_FIELDS) {
+            const key = field === 'currencyCode' && 'currenyCode' in payload ? 'currenyCode' : field;
+            if (Object.prototype.hasOwnProperty.call(payload, key)) {
+                parts.push(scalarString(payload[key]) ?? '');
+            }
+        }
+        if (!safeEqual(this.checksum(parts), get(input, 'checkSum').toLowerCase())) {
+            throw fail();
+        }
+        return payload;
+    }
+    checksum(parts) {
+        return hmacSha256Hex(this.config.appSecret, parts.join(':'));
+    }
+    async post(endpoint, data, signal) {
+        const response = await this.transport.postJson(`${this.config.baseUrl}/v1/payment/${endpoint}`, data, {}, signal);
+        const body = response.json();
+        const status = get(body, 'status');
+        if (!response.successful() || status !== '00') {
+            const message = optional(body, 'message');
+            throw new ApiError(status
+                ? `AYA Pay ${endpoint} failed: [${status}] ${message ?? ''}`.trimEnd()
+                : `AYA Pay ${endpoint} failed with HTTP ${response.status}.`, {
+                gatewayCode: status || undefined,
+                gatewayMessage: message,
+                httpStatus: response.status,
+                raw: toPlainObject(body),
+            });
+        }
+        return body;
+    }
+}
+function toCallback(payload) {
+    const statusCode = trimmed(payload, 'statusCode');
+    return new PaymentCallback({
+        orderId: get(payload, 'merchOrderId'),
+        status: resolveStatus(STATUSES, statusCode),
+        gatewayStatus: statusCode,
+        gatewayReference: optional(payload, 'tranId'),
+        amount: optional(payload, 'amount'),
+        raw: toPlainObject(payload),
+    });
+}
+function unixTime() {
+    return Math.floor(Date.now() / 1000);
+}

package/dist/esm/aya-pay/index.d.ts

@@ -0,0 +1 @@
+export { AyaPay, AyaPayConfig, AyaPayMethod, AyaPayService, type AyaPayConfigOptions, type AyaPayPaymentData, } from './aya-pay.js';

package/dist/esm/aya-pay/index.js

@@ -0,0 +1 @@
+export { AyaPay, AyaPayConfig, AyaPayMethod, AyaPayService, } from './aya-pay.js';

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

@@ -0,0 +1,57 @@
+/**
+ * An exact, non-negative money amount, kept as decimal text so it is never rounded through a
+ * floating-point number. Build one with {@link Amount.kyat} for whole amounts or
+ * {@link Amount.parse} for decimal ones; each gateway then checks it against that gateway's
+ * documented rules (Wave Money, AYA and Yoma MMQR only accept whole kyat, KBZ Pay up to 2 decimal
+ * places, CyberSource any).
+ *
+ * Amounts are immutable. `JSON.stringify` writes them as strings, e.g. `"1000.50"`.
+ */
+export declare class Amount {
+    private readonly value;
+    private constructor();
+    /**
+     * A whole amount, e.g. `Amount.kyat(1000)` for 1000 MMK. Works for whole units of any currency.
+     *
+     * Takes a safe integer `number` or a `bigint`. Fractions, negative values, `NaN` and integers
+     * beyond `Number.MAX_SAFE_INTEGER` (pass a `bigint` instead) throw an
+     * {@link InvalidPaymentDataError} for the `amount` field.
+     */
+    static kyat(amount: number | bigint): Amount;
+    /**
+     * A decimal amount written as plain digits, e.g. `Amount.parse('1000.50')`. Signs, exponents,
+     * spaces and thousands separators are rejected with an {@link InvalidPaymentDataError}. Leading
+     * zeros of the whole part are removed; the fractional digits are kept exactly as given.
+     */
+    static parse(amount: string): Amount;
+    /**
+     * Returns `amount` when it is already an `Amount`, or {@link Amount.kyat} of a whole number.
+     */
+    static from(amount: Amount | number | bigint): Amount;
+    /** Whether `value` is an `Amount`. */
+    static isAmount(value: unknown): value is Amount;
+    /** The amount exactly as it is sent to the gateway, e.g. `"1000.50"`. */
+    toString(): string;
+    /** The amount as a JSON string, e.g. `"1000.50"`, so no consumer parses it as a float. */
+    toJSON(): string;
+    /** The number of fractional digits, e.g. `2` for `1000.50`. */
+    decimalPlaces(): number;
+    /** The digits before the decimal point, e.g. `"1000"` for `1000.50`. */
+    wholePart(): string;
+    /** Whether the amount equals zero, e.g. `0` or `0.00`. */
+    isZero(): boolean;
+    /** Whether the amount is greater than zero. */
+    isPositive(): boolean;
+    /**
+     * Whether both amounts have the same value, ignoring trailing fractional zeros
+     * (`1000`, `1000.0` and `1000.00` are equal). `undefined` is never equal, so a gateway amount
+     * that was not sent never matches.
+     */
+    equals(other: Amount | string | null | undefined): boolean;
+}
+/**
+ * What payment data accepts as an amount: an {@link Amount} or a whole number of kyat
+ * (a safe integer `number` or a `bigint`). Decimal amounts must be an `Amount`, e.g.
+ * `Amount.parse('1000.50')`.
+ */
+export type AmountInput = Amount | number | bigint;

package/dist/esm/core/amount.js

@@ -0,0 +1,103 @@
+import { InvalidPaymentDataError } from './errors.js';
+const PATTERN = /^\d+(\.\d+)?$/;
+/**
+ * An exact, non-negative money amount, kept as decimal text so it is never rounded through a
+ * floating-point number. Build one with {@link Amount.kyat} for whole amounts or
+ * {@link Amount.parse} for decimal ones; each gateway then checks it against that gateway's
+ * documented rules (Wave Money, AYA and Yoma MMQR only accept whole kyat, KBZ Pay up to 2 decimal
+ * places, CyberSource any).
+ *
+ * Amounts are immutable. `JSON.stringify` writes them as strings, e.g. `"1000.50"`.
+ */
+export class Amount {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    /**
+     * A whole amount, e.g. `Amount.kyat(1000)` for 1000 MMK. Works for whole units of any currency.
+     *
+     * Takes a safe integer `number` or a `bigint`. Fractions, negative values, `NaN` and integers
+     * beyond `Number.MAX_SAFE_INTEGER` (pass a `bigint` instead) throw an
+     * {@link InvalidPaymentDataError} for the `amount` field.
+     */
+    static kyat(amount) {
+        if (typeof amount === 'bigint') {
+            if (amount < 0n) {
+                throw invalid('The amount field must not be negative.');
+            }
+            return new Amount(amount.toString());
+        }
+        if (typeof amount !== 'number' || !Number.isSafeInteger(amount)) {
+            throw invalid(`The amount field must be a whole number of kyat; use Amount.parse('10.50') for decimal amounts, got ${String(amount)}.`);
+        }
+        if (amount < 0) {
+            throw invalid('The amount field must not be negative.');
+        }
+        return new Amount(String(amount));
+    }
+    /**
+     * A decimal amount written as plain digits, e.g. `Amount.parse('1000.50')`. Signs, exponents,
+     * spaces and thousands separators are rejected with an {@link InvalidPaymentDataError}. Leading
+     * zeros of the whole part are removed; the fractional digits are kept exactly as given.
+     */
+    static parse(amount) {
+        if (typeof amount !== 'string' || !PATTERN.test(amount)) {
+            throw invalid(`The amount field must be a number such as 1000 or 1000.50, got ${JSON.stringify(amount)}.`);
+        }
+        const [whole = '', fraction] = amount.split('.');
+        const trimmedWhole = whole.replace(/^0+/, '') || '0';
+        return new Amount(fraction === undefined ? trimmedWhole : `${trimmedWhole}.${fraction}`);
+    }
+    /**
+     * Returns `amount` when it is already an `Amount`, or {@link Amount.kyat} of a whole number.
+     */
+    static from(amount) {
+        return amount instanceof Amount ? amount : Amount.kyat(amount);
+    }
+    /** Whether `value` is an `Amount`. */
+    static isAmount(value) {
+        return value instanceof Amount;
+    }
+    /** The amount exactly as it is sent to the gateway, e.g. `"1000.50"`. */
+    toString() {
+        return this.value;
+    }
+    /** The amount as a JSON string, e.g. `"1000.50"`, so no consumer parses it as a float. */
+    toJSON() {
+        return this.value;
+    }
+    /** The number of fractional digits, e.g. `2` for `1000.50`. */
+    decimalPlaces() {
+        const dot = this.value.indexOf('.');
+        return dot === -1 ? 0 : this.value.length - dot - 1;
+    }
+    /** The digits before the decimal point, e.g. `"1000"` for `1000.50`. */
+    wholePart() {
+        return this.value.split('.')[0];
+    }
+    /** Whether the amount equals zero, e.g. `0` or `0.00`. */
+    isZero() {
+        return /^[0.]+$/.test(this.value);
+    }
+    /** Whether the amount is greater than zero. */
+    isPositive() {
+        return !this.isZero();
+    }
+    /**
+     * Whether both amounts have the same value, ignoring trailing fractional zeros
+     * (`1000`, `1000.0` and `1000.00` are equal). `undefined` is never equal, so a gateway amount
+     * that was not sent never matches.
+     */
+    equals(other) {
+        if (other === undefined || other === null) {
+            return false;
+        }
+        const normalize = (value) => value.includes('.') ? value.replace(/0+$/, '').replace(/\.$/, '') : value;
+        const text = other instanceof Amount ? other.value : other;
+        return normalize(this.value) === normalize(text);
+    }
+}
+function invalid(message) {
+    return new InvalidPaymentDataError({ amount: message });
+}

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

@@ -0,0 +1,26 @@
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Stores access tokens between calls (used by Yoma MMQR). Implement it on top of Redis or similar
+ * to share tokens between processes; every method may return a promise.
+ */
+export interface TokenCache {
+    /** The cached value, or `undefined` when it is missing or expired. */
+    get(key: string): MaybePromise<string | undefined | null>;
+    /** Stores `value` for `ttlSeconds`; `0` or less never expires. */
+    set(key: string, value: string, ttlSeconds: number): MaybePromise<unknown>;
+    /** Removes `key`. */
+    delete(key: string): MaybePromise<unknown>;
+}
+/**
+ * The default {@link TokenCache}: a `Map` that lives as long as the process. Share one gateway (or
+ * one cache) across requests so the token is reused.
+ */
+export declare class MemoryTokenCache implements TokenCache {
+    private readonly items;
+    get(key: string): string | undefined;
+    set(key: string, value: string, ttlSeconds: number): void;
+    delete(key: string): void;
+    /** Removes every entry. */
+    clear(): void;
+}
+export {};

package/dist/esm/core/cache.js

@@ -0,0 +1,31 @@
+/**
+ * The default {@link TokenCache}: a `Map` that lives as long as the process. Share one gateway (or
+ * one cache) across requests so the token is reused.
+ */
+export class MemoryTokenCache {
+    items = new Map();
+    get(key) {
+        const item = this.items.get(key);
+        if (item === undefined) {
+            return undefined;
+        }
+        if (item.expiresAt !== undefined && Date.now() >= item.expiresAt) {
+            this.items.delete(key);
+            return undefined;
+        }
+        return item.value;
+    }
+    set(key, value, ttlSeconds) {
+        this.items.set(key, {
+            value,
+            expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : undefined,
+        });
+    }
+    delete(key) {
+        this.items.delete(key);
+    }
+    /** Removes every entry. */
+    clear() {
+        this.items.clear();
+    }
+}