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

package/dist/esm/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/esm/core/results.js

@@ -0,0 +1,139 @@
+/**
+ * Send the customer's browser to `url` to complete the payment.
+ */
+export 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 ?? {};
+    }
+}
+/**
+ * POST `fields` to `action` from the customer's browser. {@link FormPayment.toHtml} renders a page
+ * that does this automatically.
+ */
+export 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>');
+    }
+}
+/**
+ * Show a QR code for the customer to scan. Gateways return either a payload to encode
+ * (`qrString`) or a ready-made image (`qrImage`).
+ */
+export 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}`;
+    }
+}
+/**
+ * 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 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,
+        };
+    }
+}
+const HTML_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&#34;',
+    "'": '&#39;',
+};
+/** Escapes text for HTML content and attribute values. @internal */
+export function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char]);
+}

package/dist/esm/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/esm/core/status.js

@@ -0,0 +1,56 @@
+/**
+ * The payment statuses, plus helpers.
+ *
+ * ```ts
+ * if (callback.status === PaymentStatus.Successful) { ... }
+ * PaymentStatus.isFinal(result.status)
+ * ```
+ */
+export const 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`.
+ */
+export function resolveStatus(statuses, gatewayStatus) {
+    const key = (gatewayStatus ?? '').trim();
+    return Object.prototype.hasOwnProperty.call(statuses, key)
+        ? statuses[key]
+        : 'unknown';
+}
+/** The payment flows. */
+export const 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/esm/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;
+}

package/dist/esm/core/validate.js

@@ -0,0 +1,142 @@
+import { Amount } from './amount.js';
+import { InvalidPaymentDataError } from './errors.js';
+/**
+ * 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 function toAmount(value) {
+    if (value instanceof Amount) {
+        return value;
+    }
+    if ((typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) ||
+        (typeof value === 'bigint' && value >= 0n)) {
+        return Amount.kyat(value);
+    }
+    return undefined;
+}
+/** UTF-8 byte length, matching the byte limits in the gateway documentation. @internal */
+export function byteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+/**
+ * Collects one error per field (the first one wins) and throws them together.
+ *
+ * @internal
+ */
+export class Validator {
+    errors = {};
+    required(field, value) {
+        if (typeof value !== 'string' || value.trim() === '') {
+            this.fail(field, `The ${field} field is required.`);
+        }
+        return this;
+    }
+    /** Fails when the value is set but not a string. */
+    string(field, value) {
+        if (value !== undefined && value !== null && typeof value !== 'string') {
+            this.fail(field, `The ${field} field must be a string.`);
+        }
+        return this;
+    }
+    length(field, value, min, max) {
+        if (typeof value === 'string' && value !== '') {
+            const size = byteLength(value);
+            if (size < min || size > max) {
+                this.fail(field, `The ${field} field must be between ${min} and ${max} characters.`);
+            }
+        }
+        return this;
+    }
+    max(field, value, max) {
+        if (typeof value === 'string' && byteLength(value) > max) {
+            this.fail(field, `The ${field} field must not be greater than ${max} characters.`);
+        }
+        return this;
+    }
+    pattern(field, value, pattern, description) {
+        if (typeof value === 'string' && value !== '' && !pattern.test(value)) {
+            this.fail(field, `The ${field} field may only contain ${description}.`);
+        }
+        return this;
+    }
+    /** Fails when a set value is not an integer within [min, max]. */
+    between(field, value, min, max) {
+        if (value !== undefined &&
+            value !== null &&
+            (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max)) {
+            this.fail(field, `The ${field} field must be between ${min} and ${max}.`);
+        }
+        return this;
+    }
+    amount(field, value, rule) {
+        if (value === undefined || value === null) {
+            return this.fail(field, `The ${field} field is required.`);
+        }
+        if (typeof value === 'number' && Number.isFinite(value) && !Number.isInteger(value)) {
+            return this.fail(field, `The ${field} field must be a whole number of kyat or an Amount; use Amount.parse('10.50') for decimal amounts.`);
+        }
+        if (!(value instanceof Amount) && typeof value !== 'number' && typeof value !== 'bigint') {
+            return this.fail(field, `The ${field} field must be an Amount, e.g. Amount.kyat(1000) or Amount.parse('1000.50').`);
+        }
+        const amount = toAmount(value);
+        if (amount === undefined) {
+            return this.fail(field, `The ${field} field must be a non-negative number such as 1000 or 1000.50.`);
+        }
+        const places = amount.decimalPlaces();
+        if (rule.maxDecimals === 0 && places > 0) {
+            return this.fail(field, `${rule.gateway} does not accept decimal amounts; the ${field} field must be a whole number.`);
+        }
+        if (rule.maxDecimals !== null && rule.maxDecimals > 0 && places > rule.maxDecimals) {
+            return this.fail(field, `${rule.gateway} accepts at most ${rule.maxDecimals} decimal places; the ${field} field has ${places}.`);
+        }
+        if (rule.allowZero !== true && amount.isZero()) {
+            return this.fail(field, `The ${field} field must be greater than 0.`);
+        }
+        if (rule.maxLength !== undefined && amount.toString().length > rule.maxLength) {
+            return this.fail(field, `The ${field} field must not be greater than ${rule.maxLength} characters.`);
+        }
+        return this;
+    }
+    /** Fails when a set value is not an absolute http or https URL. */
+    url(field, value) {
+        if (typeof value !== 'string' || value === '') {
+            return this;
+        }
+        let valid;
+        try {
+            const parsed = new URL(value);
+            valid = (parsed.protocol === 'http:' || parsed.protocol === 'https:') && parsed.host !== '';
+        }
+        catch {
+            valid = false;
+        }
+        if (!valid) {
+            this.fail(field, `The ${field} field must be a valid http or https URL.`);
+        }
+        return this;
+    }
+    when(condition, field, message) {
+        if (condition) {
+            this.fail(field, message);
+        }
+        return this;
+    }
+    /** Whether any check failed so far. */
+    failed() {
+        return Object.keys(this.errors).length > 0;
+    }
+    /** Throws an {@link InvalidPaymentDataError} when any check failed. */
+    validate() {
+        if (this.failed()) {
+            throw new InvalidPaymentDataError(this.errors);
+        }
+    }
+    fail(field, message) {
+        if (!Object.prototype.hasOwnProperty.call(this.errors, field)) {
+            this.errors[field] = message;
+        }
+        return this;
+    }
+}

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

@@ -0,0 +1,16 @@
+import { type LosslessObject } from './json.js';
+/**
+ * Returns a scalar as the text a gateway signs: strings as is, numbers exactly as sent, booleans as
+ * `true`/`false`. Objects, arrays, `null` and `undefined` return `undefined`.
+ *
+ * @internal
+ */
+export declare function scalarString(value: unknown): string | undefined;
+/** The value at `key` as a string, or `''` when it is missing or not a scalar. @internal */
+export declare function get(source: Record<string, unknown>, key: string): string;
+/** The value at `key` as a string, or `undefined` when it is missing, `null` or not a scalar. @internal */
+export declare function optional(source: Record<string, unknown>, key: string): string | undefined;
+/** The value at `key` with surrounding whitespace removed. @internal */
+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;

package/dist/esm/core/values.js

@@ -0,0 +1,38 @@
+import { isLosslessObject, JsonNumber } from './json.js';
+/**
+ * Returns a scalar as the text a gateway signs: strings as is, numbers exactly as sent, booleans as
+ * `true`/`false`. Objects, arrays, `null` and `undefined` return `undefined`.
+ *
+ * @internal
+ */
+export function scalarString(value) {
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            return Number.isFinite(value) ? String(value) : undefined;
+        case 'bigint':
+            return value.toString();
+        default:
+            return value instanceof JsonNumber ? value.text : undefined;
+    }
+}
+/** The value at `key` as a string, or `''` when it is missing or not a scalar. @internal */
+export function get(source, key) {
+    return scalarString(source[key]) ?? '';
+}
+/** The value at `key` as a string, or `undefined` when it is missing, `null` or not a scalar. @internal */
+export function optional(source, key) {
+    return scalarString(source[key]);
+}
+/** The value at `key` with surrounding whitespace removed. @internal */
+export function trimmed(source, key) {
+    return get(source, key).trim();
+}
+/** The value at `key` when it is an object (not an array). @internal */
+export function object(source, key) {
+    const value = source[key];
+    return isLosslessObject(value) ? value : undefined;
+}