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

package/dist/cjs/core/env.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envFirst = envFirst;
+exports.envSandbox = envSandbox;
+exports.envInt = envInt;
+exports.requireSetting = requireSetting;
+exports.optionalSetting = optionalSetting;
+exports.trimUrl = trimUrl;
+exports.defaultEnv = defaultEnv;
+const errors_js_1 = require("./errors.js");
+/** The first non-empty value among `keys`, trimmed, or `''`. @internal */
+function envFirst(env, ...keys) {
+    for (const key of keys) {
+        const value = env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return '';
+}
+/**
+ * Reads a `*_SANDBOX` variable. Only `false`, `0`, `f`, `no` and `off` (any case) select
+ * production; unset or unrecognized values mean sandbox.
+ *
+ * @internal
+ */
+function envSandbox(env, key) {
+    const value = env[key]?.trim().toLowerCase() ?? '';
+    return !['false', '0', 'f', 'no', 'off'].includes(value);
+}
+/** An integer variable, or `undefined` when unset or not an integer. @internal */
+function envInt(env, key) {
+    const value = env[key]?.trim() ?? '';
+    return /^[+-]?\d+$/.test(value) ? Number.parseInt(value, 10) : undefined;
+}
+/** The trimmed value, or throws a {@link ConfigurationError} naming `key`. @internal */
+function requireSetting(gateway, key, value) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new errors_js_1.ConfigurationError(gateway, key);
+    }
+    return value;
+}
+/** A trimmed optional string, `undefined` when blank. @internal */
+function optionalSetting(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/** Removes trailing slashes. @internal */
+function trimUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+/** The default environment: `process.env`. @internal */
+function defaultEnv() {
+    return process.env;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Base class of every error thrown by this package.
+ */
+export declare class PaymentError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when payment data has values the gateway would reject. Thrown before any request is sent.
+ */
+export declare class InvalidPaymentDataError extends PaymentError {
+    /** Field name to error message, e.g. `{ amount: 'The amount field is required.' }`. */
+    readonly errors: Readonly<Record<string, string>>;
+    constructor(errors: Record<string, string>);
+}
+/**
+ * Thrown when a gateway rejects a request or answers with an error, including errors sent with
+ * HTTP 200, or when it cannot be reached (the network error is the `cause`).
+ */
+export declare class ApiError extends PaymentError {
+    /** The gateway's own error code, e.g. `ORDER_ID_USED` or `09`. */
+    readonly gatewayCode: string | undefined;
+    /** The gateway's own error message. */
+    readonly gatewayMessage: string | undefined;
+    /** The HTTP status of the response, or `0` when no response was received. */
+    readonly httpStatus: number;
+    /** The decoded response body. */
+    readonly raw: Readonly<Record<string, unknown>>;
+    constructor(message: string, details?: {
+        gatewayCode?: string | undefined;
+        gatewayMessage?: string | undefined;
+        httpStatus?: number;
+        raw?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a callback, return redirect or gateway response fails signature verification.
+ * Never act on its payload.
+ */
+export declare class SignatureVerificationError extends PaymentError {
+    /** The unverified payload, for logging only. */
+    readonly raw: Readonly<Record<string, unknown>>;
+    constructor(message: string, raw?: Record<string, unknown>);
+}
+/**
+ * Thrown when a gateway is missing a credential or setting it needs.
+ */
+export declare class ConfigurationError extends PaymentError {
+    /** The gateway, e.g. `kbz_pay`. */
+    readonly gateway: string;
+    /** The missing setting, e.g. `app_key`. */
+    readonly key: string;
+    constructor(gateway: string, key: string);
+}

package/dist/cjs/core/errors.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationError = exports.SignatureVerificationError = exports.ApiError = exports.InvalidPaymentDataError = exports.PaymentError = void 0;
+/**
+ * Base class of every error thrown by this package.
+ */
+class PaymentError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+exports.PaymentError = PaymentError;
+/**
+ * Thrown when payment data has values the gateway would reject. Thrown before any request is sent.
+ */
+class InvalidPaymentDataError extends PaymentError {
+    /** Field name to error message, e.g. `{ amount: 'The amount field is required.' }`. */
+    errors;
+    constructor(errors) {
+        const messages = Object.keys(errors)
+            .sort()
+            .map((field) => errors[field]);
+        super(`Invalid payment data: ${messages.join(' ')}`);
+        this.errors = Object.freeze({ ...errors });
+    }
+}
+exports.InvalidPaymentDataError = InvalidPaymentDataError;
+/**
+ * Thrown when a gateway rejects a request or answers with an error, including errors sent with
+ * HTTP 200, or when it cannot be reached (the network error is the `cause`).
+ */
+class ApiError extends PaymentError {
+    /** The gateway's own error code, e.g. `ORDER_ID_USED` or `09`. */
+    gatewayCode;
+    /** The gateway's own error message. */
+    gatewayMessage;
+    /** The HTTP status of the response, or `0` when no response was received. */
+    httpStatus;
+    /** The decoded response body. */
+    raw;
+    constructor(message, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.gatewayCode = details.gatewayCode;
+        this.gatewayMessage = details.gatewayMessage;
+        this.httpStatus = details.httpStatus ?? 0;
+        this.raw = details.raw ?? {};
+    }
+}
+exports.ApiError = ApiError;
+/**
+ * Thrown when a callback, return redirect or gateway response fails signature verification.
+ * Never act on its payload.
+ */
+class SignatureVerificationError extends PaymentError {
+    /** The unverified payload, for logging only. */
+    raw;
+    constructor(message, raw = {}) {
+        super(message);
+        this.raw = raw;
+    }
+}
+exports.SignatureVerificationError = SignatureVerificationError;
+/**
+ * Thrown when a gateway is missing a credential or setting it needs.
+ */
+class ConfigurationError extends PaymentError {
+    /** The gateway, e.g. `kbz_pay`. */
+    gateway;
+    /** The missing setting, e.g. `app_key`. */
+    key;
+    constructor(gateway, key) {
+        super(`The ${gateway} configuration is missing [${key}].`);
+        this.gateway = gateway;
+        this.key = key;
+    }
+}
+exports.ConfigurationError = ConfigurationError;

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

@@ -0,0 +1,81 @@
+import { type LosslessObject } from './json.js';
+/** A request a gateway sends. Gateways only send `POST`s. */
+export interface HttpRequest {
+    method: 'POST';
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+    /** Aborts the request, e.g. when the caller's own request is canceled. */
+    signal?: AbortSignal | undefined;
+}
+/** A gateway's response: its status and raw body text. */
+export interface HttpResponse {
+    status: number;
+    body: string;
+}
+/**
+ * Sends the gateway's HTTP requests. Implement it to add proxies, tracing, retries or a test
+ * double; the default is {@link FetchHttpClient}. Throw on network failures; any non-2xx status
+ * is a normal response.
+ */
+export interface HttpClient {
+    send(request: HttpRequest): Promise<HttpResponse>;
+}
+/** The `fetch` function {@link FetchHttpClient} uses, e.g. `globalThis.fetch` or `undici.fetch`. */
+export type FetchFunction = (input: string, init: RequestInit) => Promise<Response>;
+/** Options of {@link FetchHttpClient}. */
+export interface FetchHttpClientOptions {
+    /** The `fetch` to call; defaults to the global `fetch`. */
+    fetch?: FetchFunction | undefined;
+    /** Milliseconds before a request is aborted; defaults to 30000. `0` disables the timeout. */
+    timeoutMs?: number | undefined;
+}
+/** The default request timeout: 30 seconds. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * The default {@link HttpClient}: the global `fetch` (or the one you pass) with a 30 second
+ * timeout.
+ */
+export declare class FetchHttpClient implements HttpClient {
+    private readonly fetchFunction;
+    private readonly timeoutMs;
+    constructor(options?: FetchHttpClientOptions);
+    send(request: HttpRequest): Promise<HttpResponse>;
+}
+/** Options every gateway that calls an API accepts. */
+export interface GatewayOptions {
+    /** Sends the requests. Takes precedence over `fetch` and `timeoutMs`. */
+    httpClient?: HttpClient | undefined;
+    /** The `fetch` the default client calls, e.g. a mocked one in tests. */
+    fetch?: FetchFunction | undefined;
+    /** Milliseconds before the default client aborts a request; defaults to 30000. */
+    timeoutMs?: number | undefined;
+}
+/** Per-call options of every network method. */
+export interface RequestOptions {
+    /** Aborts the gateway call, e.g. with `AbortSignal.timeout(5000)` or the incoming request's signal. */
+    signal?: AbortSignal | undefined;
+}
+/** @internal */
+export declare function httpClientFrom(options?: GatewayOptions): HttpClient;
+/** A decoded gateway response. @internal */
+export declare class GatewayResponse {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+    successful(): boolean;
+    /** The body as a JSON object with exact numbers, or `{}` when it is not one. */
+    json(): LosslessObject;
+}
+/**
+ * Posts the JSON and form requests the gateways use.
+ *
+ * @internal
+ */
+export declare class Transport {
+    private readonly client;
+    constructor(client: HttpClient);
+    postJson(url: string, data: unknown, headers?: Record<string, string>, signal?: AbortSignal): Promise<GatewayResponse>;
+    postForm(url: string, data: Record<string, string>, headers?: Record<string, string>, signal?: AbortSignal): Promise<GatewayResponse>;
+    private post;
+}

package/dist/cjs/core/http.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = exports.GatewayResponse = exports.FetchHttpClient = exports.DEFAULT_TIMEOUT_MS = void 0;
+exports.httpClientFrom = httpClientFrom;
+const errors_js_1 = require("./errors.js");
+const json_js_1 = require("./json.js");
+/** The default request timeout: 30 seconds. */
+exports.DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * The default {@link HttpClient}: the global `fetch` (or the one you pass) with a 30 second
+ * timeout.
+ */
+class FetchHttpClient {
+    fetchFunction;
+    timeoutMs;
+    constructor(options = {}) {
+        this.fetchFunction = options.fetch;
+        this.timeoutMs = options.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+    }
+    async send(request) {
+        const fetchFunction = this.fetchFunction ?? globalThis.fetch;
+        if (typeof fetchFunction !== 'function') {
+            throw new TypeError('No fetch implementation is available; pass one with the fetch option.');
+        }
+        const response = await fetchFunction(request.url, {
+            method: request.method,
+            headers: request.headers,
+            body: request.body,
+            signal: combineSignals(request.signal, this.timeoutMs) ?? null,
+        });
+        let body;
+        try {
+            body = await response.text();
+        }
+        catch (error) {
+            throw new errors_js_1.ApiError(`Could not read response from ${request.url}: ${describe(error)}`, {
+                httpStatus: response.status,
+                cause: error,
+            });
+        }
+        return { status: response.status, body };
+    }
+}
+exports.FetchHttpClient = FetchHttpClient;
+/** @internal */
+function httpClientFrom(options = {}) {
+    return (options.httpClient ??
+        new FetchHttpClient({ fetch: options.fetch, timeoutMs: options.timeoutMs }));
+}
+/** A decoded gateway response. @internal */
+class GatewayResponse {
+    status;
+    body;
+    constructor(status, body) {
+        this.status = status;
+        this.body = body;
+    }
+    successful() {
+        return this.status >= 200 && this.status < 300;
+    }
+    /** The body as a JSON object with exact numbers, or `{}` when it is not one. */
+    json() {
+        return (0, json_js_1.parseJsonObject)(this.body) ?? {};
+    }
+}
+exports.GatewayResponse = GatewayResponse;
+/**
+ * Posts the JSON and form requests the gateways use.
+ *
+ * @internal
+ */
+class Transport {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    postJson(url, data, headers = {}, signal) {
+        return this.post(url, JSON.stringify(data), { 'Content-Type': 'application/json', Accept: 'application/json', ...headers }, signal);
+    }
+    postForm(url, data, headers = {}, signal) {
+        return this.post(url, new URLSearchParams(data).toString(), {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json',
+            ...headers,
+        }, signal);
+    }
+    async post(url, body, headers, signal) {
+        let response;
+        try {
+            response = await this.client.send({ method: 'POST', url, headers, body, signal });
+        }
+        catch (error) {
+            if (error instanceof errors_js_1.PaymentError) {
+                throw error;
+            }
+            throw new errors_js_1.ApiError(`Could not reach ${url}: ${describe(error)}`, { cause: error });
+        }
+        return new GatewayResponse(response.status, response.body);
+    }
+}
+exports.Transport = Transport;
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function combineSignals(signal, timeoutMs) {
+    const signals = [];
+    if (signal !== undefined) {
+        signals.push(signal);
+    }
+    if (timeoutMs > 0) {
+        signals.push(AbortSignal.timeout(timeoutMs));
+    }
+    if (signals.length <= 1) {
+        return signals[0];
+    }
+    // AbortSignal.any() needs Node 20.3; this works on every supported version.
+    const controller = new AbortController();
+    for (const source of signals) {
+        if (source.aborted) {
+            controller.abort(source.reason);
+            break;
+        }
+        source.addEventListener('abort', () => {
+            controller.abort(source.reason);
+        }, { once: true });
+    }
+    return controller.signal;
+}

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

@@ -0,0 +1,8 @@
+export { Amount, type AmountInput } from './amount.js';
+export { MemoryTokenCache, type TokenCache } from './cache.js';
+export { Acknowledgement, CallbackRequest, PaymentCallback, PaymentStatusResult, type AcknowledgementInit, type BodyInput, type CallbackRequestInit, type HeadersInput, type NodeRequestLike, type PaymentCallbackInit, type PaymentStatusResultInit, type QueryInput, type ServerResponseLike, type WebRequestLike, } from './callback.js';
+export type { EnvSource } from './env.js';
+export { ApiError, ConfigurationError, InvalidPaymentDataError, PaymentError, SignatureVerificationError, } from './errors.js';
+export { DEFAULT_TIMEOUT_MS, FetchHttpClient, type FetchFunction, type FetchHttpClientOptions, type GatewayOptions, type HttpClient, type HttpRequest, type HttpResponse, type RequestOptions, } from './http.js';
+export { AppPayment, FormPayment, QrPayment, RedirectPayment, type FormField, type PaymentResult, } from './results.js';
+export { PaymentFlow, PaymentStatus, resolveStatus } from './status.js';

package/dist/cjs/core/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStatus = exports.PaymentStatus = exports.PaymentFlow = exports.RedirectPayment = exports.QrPayment = exports.FormPayment = exports.AppPayment = exports.FetchHttpClient = exports.DEFAULT_TIMEOUT_MS = exports.SignatureVerificationError = exports.PaymentError = exports.InvalidPaymentDataError = exports.ConfigurationError = exports.ApiError = exports.PaymentStatusResult = exports.PaymentCallback = exports.CallbackRequest = exports.Acknowledgement = exports.MemoryTokenCache = exports.Amount = void 0;
+var amount_js_1 = require("./amount.js");
+Object.defineProperty(exports, "Amount", { enumerable: true, get: function () { return amount_js_1.Amount; } });
+var cache_js_1 = require("./cache.js");
+Object.defineProperty(exports, "MemoryTokenCache", { enumerable: true, get: function () { return cache_js_1.MemoryTokenCache; } });
+var callback_js_1 = require("./callback.js");
+Object.defineProperty(exports, "Acknowledgement", { enumerable: true, get: function () { return callback_js_1.Acknowledgement; } });
+Object.defineProperty(exports, "CallbackRequest", { enumerable: true, get: function () { return callback_js_1.CallbackRequest; } });
+Object.defineProperty(exports, "PaymentCallback", { enumerable: true, get: function () { return callback_js_1.PaymentCallback; } });
+Object.defineProperty(exports, "PaymentStatusResult", { enumerable: true, get: function () { return callback_js_1.PaymentStatusResult; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return errors_js_1.ApiError; } });
+Object.defineProperty(exports, "ConfigurationError", { enumerable: true, get: function () { return errors_js_1.ConfigurationError; } });
+Object.defineProperty(exports, "InvalidPaymentDataError", { enumerable: true, get: function () { return errors_js_1.InvalidPaymentDataError; } });
+Object.defineProperty(exports, "PaymentError", { enumerable: true, get: function () { return errors_js_1.PaymentError; } });
+Object.defineProperty(exports, "SignatureVerificationError", { enumerable: true, get: function () { return errors_js_1.SignatureVerificationError; } });
+var http_js_1 = require("./http.js");
+Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: function () { return http_js_1.DEFAULT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "FetchHttpClient", { enumerable: true, get: function () { return http_js_1.FetchHttpClient; } });
+var results_js_1 = require("./results.js");
+Object.defineProperty(exports, "AppPayment", { enumerable: true, get: function () { return results_js_1.AppPayment; } });
+Object.defineProperty(exports, "FormPayment", { enumerable: true, get: function () { return results_js_1.FormPayment; } });
+Object.defineProperty(exports, "QrPayment", { enumerable: true, get: function () { return results_js_1.QrPayment; } });
+Object.defineProperty(exports, "RedirectPayment", { enumerable: true, get: function () { return results_js_1.RedirectPayment; } });
+var status_js_1 = require("./status.js");
+Object.defineProperty(exports, "PaymentFlow", { enumerable: true, get: function () { return status_js_1.PaymentFlow; } });
+Object.defineProperty(exports, "PaymentStatus", { enumerable: true, get: function () { return status_js_1.PaymentStatus; } });
+Object.defineProperty(exports, "resolveStatus", { enumerable: true, get: function () { return status_js_1.resolveStatus; } });

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

@@ -0,0 +1,44 @@
+/**
+ * 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
+ */
+export declare class JsonNumber {
+    readonly text: string;
+    constructor(text: string);
+}
+/** A value decoded by {@link parseJson}: numbers are {@link JsonNumber}s. @internal */
+export type LosslessValue = string | boolean | null | JsonNumber | LosslessValue[] | {
+    [key: string]: LosslessValue;
+};
+/** A decoded JSON object whose numbers are {@link JsonNumber}s. @internal */
+export type LosslessObject = {
+    [key: string]: LosslessValue;
+};
+/**
+ * Parses strict JSON (RFC 8259) without passing numbers through a float. Returns `undefined` when
+ * the text is not valid JSON.
+ *
+ * @internal
+ */
+export declare function parseJson(text: string): LosslessValue | undefined;
+/**
+ * Parses JSON and returns it only when it is an object (not an array, string or null).
+ *
+ * @internal
+ */
+export declare function parseJsonObject(text: string): LosslessObject | undefined;
+/** @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.
+ *
+ * @internal
+ */
+export declare function toPlain(value: LosslessValue): unknown;
+/** @internal */
+export declare function toPlainObject(value: LosslessObject): Record<string, unknown>;
+/** Sets a key without letting `__proto__` change the object's prototype. @internal */
+export declare function setKey(target: Record<string, unknown>, key: string, value: unknown): void;