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

package/dist/cjs/core/json.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonNumber = void 0;
+exports.parseJson = parseJson;
+exports.parseJsonObject = parseJsonObject;
+exports.isLosslessObject = isLosslessObject;
+exports.toPlain = toPlain;
+exports.toPlainObject = toPlainObject;
+exports.setKey = setKey;
+/**
+ * A JSON number kept as the exact text the gateway sent, so `1000.50` stays `1000.50` and large
+ * integers keep every digit. Only used internally while verifying signatures and reading values.
+ *
+ * @internal
+ */
+class JsonNumber {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+}
+exports.JsonNumber = JsonNumber;
+const NUMBER = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+/**
+ * Parses strict JSON (RFC 8259) without passing numbers through a float. Returns `undefined` when
+ * the text is not valid JSON.
+ *
+ * @internal
+ */
+function parseJson(text) {
+    const parser = new Parser(text);
+    try {
+        parser.skipWhitespace();
+        const value = parser.value();
+        parser.skipWhitespace();
+        return parser.done() ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parses JSON and returns it only when it is an object (not an array, string or null).
+ *
+ * @internal
+ */
+function parseJsonObject(text) {
+    const value = parseJson(text);
+    return isLosslessObject(value) ? value : undefined;
+}
+/** @internal */
+function isLosslessObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof JsonNumber));
+}
+/**
+ * Converts a lossless value to plain JavaScript values (numbers become `number`), for the `raw`
+ * fields of results.
+ *
+ * @internal
+ */
+function toPlain(value) {
+    if (value instanceof JsonNumber) {
+        return Number(value.text);
+    }
+    if (Array.isArray(value)) {
+        return value.map(toPlain);
+    }
+    if (value !== null && typeof value === 'object') {
+        return toPlainObject(value);
+    }
+    return value;
+}
+/** @internal */
+function toPlainObject(value) {
+    const result = {};
+    for (const key of Object.keys(value)) {
+        setKey(result, key, toPlain(value[key]));
+    }
+    return result;
+}
+/** Sets a key without letting `__proto__` change the object's prototype. @internal */
+function setKey(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+class Parser {
+    text;
+    index = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    done() {
+        return this.index === this.text.length;
+    }
+    skipWhitespace() {
+        while (this.index < this.text.length) {
+            const char = this.text[this.index];
+            if (char !== ' ' && char !== '\t' && char !== '\n' && char !== '\r') {
+                return;
+            }
+            this.index++;
+        }
+    }
+    value() {
+        const char = this.text[this.index];
+        switch (char) {
+            case '{':
+                return this.object();
+            case '[':
+                return this.array();
+            case '"':
+                return this.string();
+            case 't':
+                return this.literal('true', true);
+            case 'f':
+                return this.literal('false', false);
+            case 'n':
+                return this.literal('null', null);
+            default:
+                return this.number();
+        }
+    }
+    object() {
+        this.index++;
+        const result = {};
+        this.skipWhitespace();
+        if (this.text[this.index] === '}') {
+            this.index++;
+            return result;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            if (this.text[this.index] !== '"') {
+                throw new SyntaxError('Expected a string key');
+            }
+            const key = this.string();
+            this.skipWhitespace();
+            this.expect(':');
+            this.skipWhitespace();
+            setKey(result, key, this.value());
+            this.skipWhitespace();
+            if (this.text[this.index] === ',') {
+                this.index++;
+                continue;
+            }
+            this.expect('}');
+            return result;
+        }
+    }
+    array() {
+        this.index++;
+        const result = [];
+        this.skipWhitespace();
+        if (this.text[this.index] === ']') {
+            this.index++;
+            return result;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            result.push(this.value());
+            this.skipWhitespace();
+            if (this.text[this.index] === ',') {
+                this.index++;
+                continue;
+            }
+            this.expect(']');
+            return result;
+        }
+    }
+    string() {
+        this.index++;
+        let result = '';
+        for (;;) {
+            if (this.index >= this.text.length) {
+                throw new SyntaxError('Unterminated string');
+            }
+            const char = this.text[this.index];
+            if (char === '"') {
+                this.index++;
+                return result;
+            }
+            if (char === '\\') {
+                result += this.escape();
+                continue;
+            }
+            if (char < ' ') {
+                throw new SyntaxError('Control character in string');
+            }
+            result += char;
+            this.index++;
+        }
+    }
+    escape() {
+        const char = this.text[this.index + 1];
+        this.index += 2;
+        switch (char) {
+            case '"':
+                return '"';
+            case '\\':
+                return '\\';
+            case '/':
+                return '/';
+            case 'b':
+                return '\b';
+            case 'f':
+                return '\f';
+            case 'n':
+                return '\n';
+            case 'r':
+                return '\r';
+            case 't':
+                return '\t';
+            case 'u': {
+                const hex = this.text.slice(this.index, this.index + 4);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+                    throw new SyntaxError('Invalid unicode escape');
+                }
+                this.index += 4;
+                return String.fromCharCode(parseInt(hex, 16));
+            }
+            default:
+                throw new SyntaxError('Invalid escape');
+        }
+    }
+    literal(word, value) {
+        if (!this.text.startsWith(word, this.index)) {
+            throw new SyntaxError(`Expected ${word}`);
+        }
+        this.index += word.length;
+        return value;
+    }
+    number() {
+        NUMBER.lastIndex = this.index;
+        const match = NUMBER.exec(this.text);
+        if (match === null) {
+            throw new SyntaxError('Unexpected token');
+        }
+        this.index += match[0].length;
+        return new JsonNumber(match[0]);
+    }
+    expect(char) {
+        if (this.text[this.index] !== char) {
+            throw new SyntaxError(`Expected ${char}`);
+        }
+        this.index++;
+    }
+}

package/dist/cjs/core/results.d.ts

@@ -0,0 +1,122 @@
+type Raw = Readonly<Record<string, unknown>>;
+/** Returned when a payment is initiated. Each flow has its own class; switch on `flow`. */
+export type PaymentResult = RedirectPayment | FormPayment | QrPayment | AppPayment;
+/**
+ * Send the customer's browser to `url` to complete the payment.
+ */
+export declare class RedirectPayment {
+    /** Always `redirect`. */
+    readonly flow: 'redirect';
+    /** Your order id, as sent to the gateway. */
+    readonly orderId: string;
+    /** The gateway page to redirect the customer to. */
+    readonly url: string;
+    /** The gateway's id for this attempt (KBZ `prepay_id`, Wave `transaction_id`). */
+    readonly gatewayReference: string | undefined;
+    /** The gateway's response, for logging. */
+    readonly raw: Raw;
+    constructor(init: {
+        orderId: string;
+        url: string;
+        gatewayReference?: string | undefined;
+        raw?: Raw;
+    });
+}
+/** One signed hidden field of a {@link FormPayment}. */
+export interface FormField {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * POST `fields` to `action` from the customer's browser. {@link FormPayment.toHtml} renders a page
+ * that does this automatically.
+ */
+export declare class FormPayment {
+    /** Always `form`. */
+    readonly flow: 'form';
+    /** Your order id, as sent to the gateway. */
+    readonly orderId: string;
+    /** The gateway URL the form posts to. */
+    readonly action: string;
+    /** The signed hidden fields, in signing order. Post them unchanged. */
+    readonly fields: readonly FormField[];
+    /** The encoding the gateway expects for the form. */
+    readonly enctype: string;
+    constructor(init: {
+        orderId: string;
+        action: string;
+        fields: readonly FormField[];
+        enctype?: string | undefined;
+    });
+    /** The value of the named field, or `undefined`. */
+    field(name: string): string | undefined;
+    /** The fields as an object, e.g. to render the form with your own template. */
+    values(): Record<string, string>;
+    /** A complete HTML page that posts the form as soon as it loads. Every value is escaped. */
+    toHtml(): string;
+}
+/**
+ * Show a QR code for the customer to scan. Gateways return either a payload to encode
+ * (`qrString`) or a ready-made image (`qrImage`).
+ */
+export declare class QrPayment {
+    /** Always `qr`. */
+    readonly flow: 'qr';
+    /** Your order id, as sent to the gateway. */
+    readonly orderId: string;
+    /** A QR payload to encode into an image yourself (KBZ Pay). */
+    readonly qrString: string | undefined;
+    /** A base64 encoded image to display as is (Yoma MMQR). */
+    readonly qrImage: string | undefined;
+    /** When the QR stops being payable, when the gateway limits it. */
+    readonly expiresAt: Date | undefined;
+    /** The gateway's id for this QR, used to check its status (Yoma `refLabel`, KBZ `prepay_id`). */
+    readonly reference: string | undefined;
+    /** The gateway's response, for logging. */
+    readonly raw: Raw;
+    constructor(init: {
+        orderId: string;
+        qrString?: string | undefined;
+        qrImage?: string | undefined;
+        expiresAt?: Date | undefined;
+        reference?: string | undefined;
+        raw?: Raw;
+    });
+    /** The image as a data URI for an `<img src>`, or `undefined` when there is no image. */
+    qrImageDataUri(mimeType?: string): string | undefined;
+}
+/**
+ * Pass these values to your mobile app, which hands them to the wallet's SDK.
+ * `JSON.stringify(payment)` writes `orderId`, `orderInfo`, `sign` and `signType`.
+ */
+export declare class AppPayment {
+    /** Always `app`. */
+    readonly flow: 'app';
+    /** Your order id, as sent to the gateway. */
+    readonly orderId: string;
+    /** The signed order string the SDK expects. */
+    readonly orderInfo: string;
+    /** The signature of `orderInfo`. */
+    readonly sign: string;
+    /** The signature algorithm, e.g. `SHA256`. */
+    readonly signType: string;
+    /** The gateway's response, for logging. Left out of `toJSON()`. */
+    readonly raw: Raw;
+    constructor(init: {
+        orderId: string;
+        orderInfo: string;
+        sign: string;
+        signType: string;
+        raw?: Raw;
+    });
+    /** The values your app needs: `orderId`, `orderInfo`, `sign` and `signType`. */
+    toJSON(): {
+        orderId: string;
+        orderInfo: string;
+        sign: string;
+        signType: string;
+    };
+}
+/** Escapes text for HTML content and attribute values. @internal */
+export declare function escapeHtml(value: string): string;
+export {};

package/dist/cjs/core/results.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppPayment = exports.QrPayment = exports.FormPayment = exports.RedirectPayment = void 0;
+exports.escapeHtml = escapeHtml;
+/**
+ * Send the customer's browser to `url` to complete the payment.
+ */
+class RedirectPayment {
+    /** Always `redirect`. */
+    flow = 'redirect';
+    /** Your order id, as sent to the gateway. */
+    orderId;
+    /** The gateway page to redirect the customer to. */
+    url;
+    /** The gateway's id for this attempt (KBZ `prepay_id`, Wave `transaction_id`). */
+    gatewayReference;
+    /** The gateway's response, for logging. */
+    raw;
+    constructor(init) {
+        this.orderId = init.orderId;
+        this.url = init.url;
+        this.gatewayReference = init.gatewayReference;
+        this.raw = init.raw ?? {};
+    }
+}
+exports.RedirectPayment = RedirectPayment;
+/**
+ * POST `fields` to `action` from the customer's browser. {@link FormPayment.toHtml} renders a page
+ * that does this automatically.
+ */
+class FormPayment {
+    /** Always `form`. */
+    flow = 'form';
+    /** Your order id, as sent to the gateway. */
+    orderId;
+    /** The gateway URL the form posts to. */
+    action;
+    /** The signed hidden fields, in signing order. Post them unchanged. */
+    fields;
+    /** The encoding the gateway expects for the form. */
+    enctype;
+    constructor(init) {
+        this.orderId = init.orderId;
+        this.action = init.action;
+        this.fields = Object.freeze(init.fields.map((field) => Object.freeze({ ...field })));
+        this.enctype = init.enctype ?? 'application/x-www-form-urlencoded';
+    }
+    /** The value of the named field, or `undefined`. */
+    field(name) {
+        return this.fields.find((field) => field.name === name)?.value;
+    }
+    /** The fields as an object, e.g. to render the form with your own template. */
+    values() {
+        return Object.fromEntries(this.fields.map((field) => [field.name, field.value]));
+    }
+    /** A complete HTML page that posts the form as soon as it loads. Every value is escaped. */
+    toHtml() {
+        const inputs = this.fields
+            .map((field) => `<input type="hidden" name="${escapeHtml(field.name)}" value="${escapeHtml(field.value)}">`)
+            .join('');
+        return ('<!DOCTYPE html><html><head><meta charset="utf-8"><title>Redirecting to payment</title></head><body>' +
+            `<form id="payment-form" method="POST" action="${escapeHtml(this.action)}" enctype="${escapeHtml(this.enctype)}">` +
+            inputs +
+            '<noscript><button type="submit">Continue to payment</button></noscript></form>' +
+            '<script>document.getElementById("payment-form").submit();</script></body></html>');
+    }
+}
+exports.FormPayment = FormPayment;
+/**
+ * Show a QR code for the customer to scan. Gateways return either a payload to encode
+ * (`qrString`) or a ready-made image (`qrImage`).
+ */
+class QrPayment {
+    /** Always `qr`. */
+    flow = 'qr';
+    /** Your order id, as sent to the gateway. */
+    orderId;
+    /** A QR payload to encode into an image yourself (KBZ Pay). */
+    qrString;
+    /** A base64 encoded image to display as is (Yoma MMQR). */
+    qrImage;
+    /** When the QR stops being payable, when the gateway limits it. */
+    expiresAt;
+    /** The gateway's id for this QR, used to check its status (Yoma `refLabel`, KBZ `prepay_id`). */
+    reference;
+    /** The gateway's response, for logging. */
+    raw;
+    constructor(init) {
+        this.orderId = init.orderId;
+        this.qrString = init.qrString;
+        this.qrImage = init.qrImage;
+        this.expiresAt = init.expiresAt;
+        this.reference = init.reference;
+        this.raw = init.raw ?? {};
+    }
+    /** The image as a data URI for an `<img src>`, or `undefined` when there is no image. */
+    qrImageDataUri(mimeType = 'image/png') {
+        return this.qrImage === undefined ? undefined : `data:${mimeType};base64,${this.qrImage}`;
+    }
+}
+exports.QrPayment = QrPayment;
+/**
+ * Pass these values to your mobile app, which hands them to the wallet's SDK.
+ * `JSON.stringify(payment)` writes `orderId`, `orderInfo`, `sign` and `signType`.
+ */
+class AppPayment {
+    /** Always `app`. */
+    flow = 'app';
+    /** Your order id, as sent to the gateway. */
+    orderId;
+    /** The signed order string the SDK expects. */
+    orderInfo;
+    /** The signature of `orderInfo`. */
+    sign;
+    /** The signature algorithm, e.g. `SHA256`. */
+    signType;
+    /** The gateway's response, for logging. Left out of `toJSON()`. */
+    raw;
+    constructor(init) {
+        this.orderId = init.orderId;
+        this.orderInfo = init.orderInfo;
+        this.sign = init.sign;
+        this.signType = init.signType;
+        this.raw = init.raw ?? {};
+    }
+    /** The values your app needs: `orderId`, `orderInfo`, `sign` and `signType`. */
+    toJSON() {
+        return {
+            orderId: this.orderId,
+            orderInfo: this.orderInfo,
+            sign: this.sign,
+            signType: this.signType,
+        };
+    }
+}
+exports.AppPayment = AppPayment;
+const HTML_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&#34;',
+    "'": '&#39;',
+};
+/** Escapes text for HTML content and attribute values. @internal */
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char]);
+}

package/dist/cjs/core/status.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A gateway-independent payment status. Every gateway's own status values are mapped onto these.
+ */
+export type PaymentStatus = 'successful' | 'pending' | 'failed' | 'cancelled' | 'expired' | 'unknown';
+/**
+ * The payment statuses, plus helpers.
+ *
+ * ```ts
+ * if (callback.status === PaymentStatus.Successful) { ... }
+ * PaymentStatus.isFinal(result.status)
+ * ```
+ */
+export declare const PaymentStatus: Readonly<{
+    /** The customer paid. The only status that means money was collected. */
+    Successful: "successful";
+    /** The payment is still in progress or waiting on the customer. */
+    Pending: "pending";
+    /** The payment was attempted and failed or was rejected. */
+    Failed: "failed";
+    /** The payment or order was canceled or closed before completing. */
+    Cancelled: "cancelled";
+    /** The payment window ran out before the customer paid. */
+    Expired: "expired";
+    /** The gateway sent a status this package does not recognize. Inspect `gatewayStatus`. */
+    Unknown: "unknown";
+    /** Every status, in the order above. */
+    values: readonly ["successful", "pending", "failed", "cancelled", "expired", "unknown"];
+    /** Whether the status will not change any more: `false` for `pending` and `unknown`. */
+    isFinal(status: PaymentStatus): boolean;
+}>;
+/**
+ * Maps a gateway status onto a {@link PaymentStatus}, trimming whitespace. Statuses missing from
+ * the map resolve to `unknown`.
+ */
+export declare function resolveStatus(statuses: Readonly<Record<string, PaymentStatus>>, gatewayStatus: string | null | undefined): PaymentStatus;
+/**
+ * How the customer completes a payment after it has been initiated.
+ */
+export type PaymentFlow = 'redirect' | 'form' | 'qr' | 'app';
+/** The payment flows. */
+export declare const PaymentFlow: Readonly<{
+    /** Send the customer's browser to a gateway-hosted URL. */
+    readonly Redirect: "redirect";
+    /** POST a signed form from the customer's browser to the gateway. */
+    readonly Form: "form";
+    /** Show a QR code the customer scans with their wallet app. */
+    readonly Qr: "qr";
+    /** Hand a signed payload to your mobile app, which opens the wallet SDK. */
+    readonly App: "app";
+}>;

package/dist/cjs/core/status.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentFlow = exports.PaymentStatus = void 0;
+exports.resolveStatus = resolveStatus;
+/**
+ * The payment statuses, plus helpers.
+ *
+ * ```ts
+ * if (callback.status === PaymentStatus.Successful) { ... }
+ * PaymentStatus.isFinal(result.status)
+ * ```
+ */
+exports.PaymentStatus = Object.freeze({
+    /** The customer paid. The only status that means money was collected. */
+    Successful: 'successful',
+    /** The payment is still in progress or waiting on the customer. */
+    Pending: 'pending',
+    /** The payment was attempted and failed or was rejected. */
+    Failed: 'failed',
+    /** The payment or order was canceled or closed before completing. */
+    Cancelled: 'cancelled',
+    /** The payment window ran out before the customer paid. */
+    Expired: 'expired',
+    /** The gateway sent a status this package does not recognize. Inspect `gatewayStatus`. */
+    Unknown: 'unknown',
+    /** Every status, in the order above. */
+    values: Object.freeze([
+        'successful',
+        'pending',
+        'failed',
+        'cancelled',
+        'expired',
+        'unknown',
+    ]),
+    /** Whether the status will not change any more: `false` for `pending` and `unknown`. */
+    isFinal(status) {
+        return status !== 'pending' && status !== 'unknown';
+    },
+});
+/**
+ * Maps a gateway status onto a {@link PaymentStatus}, trimming whitespace. Statuses missing from
+ * the map resolve to `unknown`.
+ */
+function resolveStatus(statuses, gatewayStatus) {
+    const key = (gatewayStatus ?? '').trim();
+    return Object.prototype.hasOwnProperty.call(statuses, key)
+        ? statuses[key]
+        : 'unknown';
+}
+/** The payment flows. */
+exports.PaymentFlow = Object.freeze({
+    /** Send the customer's browser to a gateway-hosted URL. */
+    Redirect: 'redirect',
+    /** POST a signed form from the customer's browser to the gateway. */
+    Form: 'form',
+    /** Show a QR code the customer scans with their wallet app. */
+    Qr: 'qr',
+    /** Hand a signed payload to your mobile app, which opens the wallet SDK. */
+    App: 'app',
+});

package/dist/cjs/core/validate.d.ts

@@ -0,0 +1,46 @@
+import { Amount } from './amount.js';
+/** What a gateway's documentation allows for an amount. @internal */
+export interface AmountRule {
+    /** The gateway's display name, used in error messages. */
+    gateway: string;
+    /** The most fractional digits allowed: 0 means whole amounts only, `null` means no limit. */
+    maxDecimals: number | null;
+    /** Limits the amount's text length. */
+    maxLength?: number;
+    /** Accepts an amount of 0. */
+    allowZero?: boolean;
+}
+/**
+ * Converts an amount input to an {@link Amount}, or `undefined` when it is missing or not a valid
+ * non-negative amount. Validation reports why.
+ *
+ * @internal
+ */
+export declare function toAmount(value: unknown): Amount | undefined;
+/** UTF-8 byte length, matching the byte limits in the gateway documentation. @internal */
+export declare function byteLength(value: string): number;
+/**
+ * Collects one error per field (the first one wins) and throws them together.
+ *
+ * @internal
+ */
+export declare class Validator {
+    private readonly errors;
+    required(field: string, value: unknown): this;
+    /** Fails when the value is set but not a string. */
+    string(field: string, value: unknown): this;
+    length(field: string, value: string | undefined, min: number, max: number): this;
+    max(field: string, value: string | undefined, max: number): this;
+    pattern(field: string, value: string | undefined, pattern: RegExp, description: string): this;
+    /** Fails when a set value is not an integer within [min, max]. */
+    between(field: string, value: unknown, min: number, max: number): this;
+    amount(field: string, value: unknown, rule: AmountRule): this;
+    /** Fails when a set value is not an absolute http or https URL. */
+    url(field: string, value: string | undefined): this;
+    when(condition: boolean, field: string, message: string): this;
+    /** Whether any check failed so far. */
+    failed(): boolean;
+    /** Throws an {@link InvalidPaymentDataError} when any check failed. */
+    validate(): void;
+    private fail;
+}