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

package/dist/esm/core/errors.js

@@ -0,0 +1,70 @@
+/**
+ * Base class of every error thrown by this package.
+ */
+export class PaymentError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/**
+ * Thrown when payment data has values the gateway would reject. Thrown before any request is sent.
+ */
+export 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 });
+    }
+}
+/**
+ * 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 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 ?? {};
+    }
+}
+/**
+ * Thrown when a callback, return redirect or gateway response fails signature verification.
+ * Never act on its payload.
+ */
+export class SignatureVerificationError extends PaymentError {
+    /** The unverified payload, for logging only. */
+    raw;
+    constructor(message, raw = {}) {
+        super(message);
+        this.raw = raw;
+    }
+}
+/**
+ * Thrown when a gateway is missing a credential or setting it needs.
+ */
+export 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;
+    }
+}

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

@@ -0,0 +1,121 @@
+import { ApiError, PaymentError } from './errors.js';
+import { parseJsonObject } from './json.js';
+/** The default request timeout: 30 seconds. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * The default {@link HttpClient}: the global `fetch` (or the one you pass) with a 30 second
+ * timeout.
+ */
+export class FetchHttpClient {
+    fetchFunction;
+    timeoutMs;
+    constructor(options = {}) {
+        this.fetchFunction = options.fetch;
+        this.timeoutMs = options.timeoutMs ?? 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 ApiError(`Could not read response from ${request.url}: ${describe(error)}`, {
+                httpStatus: response.status,
+                cause: error,
+            });
+        }
+        return { status: response.status, body };
+    }
+}
+/** @internal */
+export function httpClientFrom(options = {}) {
+    return (options.httpClient ??
+        new FetchHttpClient({ fetch: options.fetch, timeoutMs: options.timeoutMs }));
+}
+/** A decoded gateway response. @internal */
+export 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 parseJsonObject(this.body) ?? {};
+    }
+}
+/**
+ * Posts the JSON and form requests the gateways use.
+ *
+ * @internal
+ */
+export 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 PaymentError) {
+                throw error;
+            }
+            throw new ApiError(`Could not reach ${url}: ${describe(error)}`, { cause: error });
+        }
+        return new GatewayResponse(response.status, response.body);
+    }
+}
+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/esm/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/esm/core/index.js

@@ -0,0 +1,7 @@
+export { Amount } from './amount.js';
+export { MemoryTokenCache } from './cache.js';
+export { Acknowledgement, CallbackRequest, PaymentCallback, PaymentStatusResult, } from './callback.js';
+export { ApiError, ConfigurationError, InvalidPaymentDataError, PaymentError, SignatureVerificationError, } from './errors.js';
+export { DEFAULT_TIMEOUT_MS, FetchHttpClient, } from './http.js';
+export { AppPayment, FormPayment, QrPayment, RedirectPayment, } from './results.js';
+export { PaymentFlow, PaymentStatus, resolveStatus } from './status.js';

package/dist/esm/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;

package/dist/esm/core/json.js

@@ -0,0 +1,244 @@
+/**
+ * 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 class JsonNumber {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+}
+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
+ */
+export 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
+ */
+export function parseJsonObject(text) {
+    const value = parseJson(text);
+    return isLosslessObject(value) ? value : undefined;
+}
+/** @internal */
+export 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
+ */
+export 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 */
+export 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 */
+export 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++;
+    }
+}