@laranex/myanmar-payments 4.0.0-dev.1 → 4.0.0-dev.10

package/dist/esm/core/callback.js

@@ -5,14 +5,17 @@ import { parseJsonObject, setKey, toPlainObject } from './json.js';
  * {@link CallbackRequest.fromNodeRequest} or {@link CallbackRequest.fromWebRequest}.
  */
 export class CallbackRequest {
-    /** The raw request body, decoded as UTF-8. */
+    /** The request body as text: a string body as given, bytes decoded as UTF-8. */
     body;
+    /** The exact bytes received. A string body is encoded as UTF-8. */
+    rawBody;
     /** The request headers, with lowercase names. Repeated headers are joined with `, `. */
     headers;
     /** The query string parameters (the first value of each). */
     query;
     constructor(init = {}) {
-        this.body = bodyText(init.body);
+        this.rawBody = bodyBytes(init.body);
+        this.body = typeof init.body === 'string' ? init.body : new TextDecoder().decode(this.rawBody);
         this.headers = Object.freeze(normalizeHeaders(init.headers));
         this.query = Object.freeze(normalizeQuery(init.query));
     }
@@ -31,10 +34,11 @@ export class CallbackRequest {
         });
     }
     /**
-     * Reads a Node `http.IncomingMessage` (also Express `req`, Fastify `request.raw`, Koa `ctx.req`).
-     * Reads the raw body from the stream, or from `rawBody`/`body` when middleware captured it as
-     * text or bytes. When a body parser already consumed the stream, the parsed `body` is encoded
-     * again as JSON or a form.
+     * Reads a Node `http.IncomingMessage` (also Express `req`, or Koa `ctx.req` without a body
+     * parser). Reads the raw body from the stream, or from `rawBody`/`body` when middleware captured
+     * it as text or bytes. When a body parser already consumed the stream, the parsed `body` is
+     * encoded again as JSON or a form. Fastify parses the body before your handler runs: use
+     * {@link CallbackRequest.from} with the raw body there.
      */
     static async fromNodeRequest(request) {
         const headers = normalizeHeaders(request.headers);
@@ -67,7 +71,10 @@ export class CallbackRequest {
     header(name) {
         return this.headers[name.toLowerCase()];
     }
-    /** The body decoded as JSON or as a urlencoded form. */
+    /**
+     * The body decoded as JSON or as a urlencoded form. JSON numbers keep their exact text, as strings
+     * (`1000.50` stays `"1000.50"`).
+     */
     parsedBody() {
         return toPlainObject(losslessBody(this));
     }
@@ -206,14 +213,15 @@ export class PaymentStatusResult {
         return this.status === 'successful';
     }
 }
-function bodyText(body) {
+function bodyBytes(body) {
     if (body === undefined || body === null) {
-        return '';
+        return new Uint8Array();
     }
     if (typeof body === 'string') {
-        return body;
+        return new TextEncoder().encode(body);
     }
-    return new TextDecoder().decode(body);
+    // A copy, so later changes to the caller's buffer cannot alter what was verified.
+    return body instanceof ArrayBuffer ? new Uint8Array(body.slice(0)) : Uint8Array.from(body);
 }
 function rawBody(value) {
     if (typeof value === 'string' || value instanceof Uint8Array || value instanceof ArrayBuffer) {

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

@@ -15,5 +15,10 @@ export declare function randomHex(bytes?: number): string;
  * @internal
  */
 export declare function queryEscape(value: string): string;
-/** Decodes strict standard base64 (with padding), or `undefined`. @internal */
+/**
+ * Decodes standard base64 (`A-Z a-z 0-9 + /`), either correctly padded or without any padding, to
+ * UTF-8 text. Partial padding, other characters and bytes that are not UTF-8 return `undefined`.
+ *
+ * @internal
+ */
 export declare function decodeBase64(value: string): string | undefined;

package/dist/esm/core/crypto.js

@@ -32,10 +32,24 @@ export function queryEscape(value) {
         .replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)
         .replace(/%20/g, '+');
 }
-/** Decodes strict standard base64 (with padding), or `undefined`. @internal */
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
+/**
+ * Decodes standard base64 (`A-Z a-z 0-9 + /`), either correctly padded or without any padding, to
+ * UTF-8 text. Partial padding, other characters and bytes that are not UTF-8 return `undefined`.
+ *
+ * @internal
+ */
 export function decodeBase64(value) {
-    if (value === '' || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value)) {
+        return undefined;
+    }
+    if (value.includes('=') ? value.length % 4 !== 0 : value.length % 4 === 1) {
+        return undefined;
+    }
+    try {
+        return UTF8.decode(Buffer.from(value, 'base64'));
+    }
+    catch {
         return undefined;
     }
-    return Buffer.from(value, 'base64').toString('utf8');
 }

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

@@ -3,14 +3,23 @@ export type EnvSource = Readonly<Record<string, string | undefined>>;
 /** The first non-empty value among `keys`, trimmed, or `''`. @internal */
 export declare function envFirst(env: EnvSource, ...keys: string[]): string;
 /**
- * Reads a `*_SANDBOX` variable. Only `false`, `0`, `f`, `no` and `off` (any case) select
- * production; unset or unrecognized values mean sandbox.
+ * A required whole number of seconds: an integer greater than 0, or text such as `'300'`. Unset
+ * or blank throws the missing {@link ConfigurationError}; anything else throws the invalid one.
  *
  * @internal
  */
-export declare function envSandbox(env: EnvSource, key: string): boolean;
-/** An integer variable, or `undefined` when unset or not an integer. @internal */
-export declare function envInt(env: EnvSource, key: string): number | undefined;
+export declare function requireSeconds(gateway: string, key: string, value: unknown): number;
+/** The variable holding the HTTP timeout of every gateway that calls an API. @internal */
+export declare const HTTP_TIMEOUT_VARIABLE = "MYANMAR_PAYMENTS_HTTP_TIMEOUT";
+/** Seconds before the default HTTP client gives up on a request when no timeout is configured. */
+export declare const DEFAULT_TIMEOUT_SECONDS = 30;
+/**
+ * The HTTP timeout in seconds: {@link DEFAULT_TIMEOUT_SECONDS} when unset or blank, otherwise a
+ * whole number greater than 0 (or its text), or the invalid {@link ConfigurationError}.
+ *
+ * @internal
+ */
+export declare function resolveTimeout(gateway: string, value: unknown): number;
 /** The trimmed value, or throws a {@link ConfigurationError} naming `key`. @internal */
 export declare function requireSetting(gateway: string, key: string, value: unknown): string;
 /** A trimmed optional string, `undefined` when blank. @internal */

package/dist/esm/core/env.js

@@ -10,19 +10,42 @@ export function envFirst(env, ...keys) {
     return '';
 }
 /**
- * Reads a `*_SANDBOX` variable. Only `false`, `0`, `f`, `no` and `off` (any case) select
- * production; unset or unrecognized values mean sandbox.
+ * A required whole number of seconds: an integer greater than 0, or text such as `'300'`. Unset
+ * or blank throws the missing {@link ConfigurationError}; anything else throws the invalid one.
  *
  * @internal
  */
-export function envSandbox(env, key) {
-    const value = env[key]?.trim().toLowerCase() ?? '';
-    return !['false', '0', 'f', 'no', 'off'].includes(value);
+export function requireSeconds(gateway, key, value) {
+    if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) {
+        throw new ConfigurationError(gateway, key);
+    }
+    let seconds;
+    if (typeof value === 'number' && Number.isSafeInteger(value)) {
+        seconds = value;
+    }
+    else if (typeof value === 'string' && /^[+-]?\d+$/.test(value.trim())) {
+        seconds = Number.parseInt(value.trim(), 10);
+    }
+    if (seconds === undefined || !Number.isSafeInteger(seconds) || seconds <= 0) {
+        throw new ConfigurationError(gateway, key, true);
+    }
+    return seconds;
 }
-/** An integer variable, or `undefined` when unset or not an integer. @internal */
-export function envInt(env, key) {
-    const value = env[key]?.trim() ?? '';
-    return /^[+-]?\d+$/.test(value) ? Number.parseInt(value, 10) : undefined;
+/** The variable holding the HTTP timeout of every gateway that calls an API. @internal */
+export const HTTP_TIMEOUT_VARIABLE = 'MYANMAR_PAYMENTS_HTTP_TIMEOUT';
+/** Seconds before the default HTTP client gives up on a request when no timeout is configured. */
+export const DEFAULT_TIMEOUT_SECONDS = 30;
+/**
+ * The HTTP timeout in seconds: {@link DEFAULT_TIMEOUT_SECONDS} when unset or blank, otherwise a
+ * whole number greater than 0 (or its text), or the invalid {@link ConfigurationError}.
+ *
+ * @internal
+ */
+export function resolveTimeout(gateway, value) {
+    if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) {
+        return DEFAULT_TIMEOUT_SECONDS;
+    }
+    return requireSeconds(gateway, 'timeout_in_seconds', value);
 }
 /** The trimmed value, or throws a {@link ConfigurationError} naming `key`. @internal */
 export function requireSetting(gateway, key, value) {

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

@@ -45,12 +45,18 @@ export declare class SignatureVerificationError extends PaymentError {
     constructor(message: string, raw?: Record<string, unknown>);
 }
 /**
- * Thrown when a gateway is missing a credential or setting it needs.
+ * Thrown when a gateway is missing a credential or setting it needs, or a whole-number setting
+ * is not a whole number greater than 0.
  */
 export declare class ConfigurationError extends PaymentError {
     /** The gateway, e.g. `kbz_pay`. */
     readonly gateway: string;
-    /** The missing setting, e.g. `app_key`. */
+    /** The missing or invalid setting, e.g. `app_key`. */
     readonly key: string;
-    constructor(gateway: string, key: string);
+    /**
+     * @param invalid `true` when the setting is set but out of range; `false` (the default) when it
+     *   is missing.
+     * @param requirement What a valid value is, used in the message when `invalid`.
+     */
+    constructor(gateway: string, key: string, invalid?: boolean, requirement?: string);
 }

package/dist/esm/core/errors.js

@@ -55,15 +55,23 @@ export class SignatureVerificationError extends PaymentError {
     }
 }
 /**
- * Thrown when a gateway is missing a credential or setting it needs.
+ * Thrown when a gateway is missing a credential or setting it needs, or a whole-number setting
+ * is not a whole number greater than 0.
  */
 export class ConfigurationError extends PaymentError {
     /** The gateway, e.g. `kbz_pay`. */
     gateway;
-    /** The missing setting, e.g. `app_key`. */
+    /** The missing or invalid setting, e.g. `app_key`. */
     key;
-    constructor(gateway, key) {
-        super(`The ${gateway} configuration is missing [${key}].`);
+    /**
+     * @param invalid `true` when the setting is set but out of range; `false` (the default) when it
+     *   is missing.
+     * @param requirement What a valid value is, used in the message when `invalid`.
+     */
+    constructor(gateway, key, invalid = false, requirement = 'a whole number greater than 0') {
+        super(invalid
+            ? `The ${gateway} configuration [${key}] must be ${requirement}.`
+            : `The ${gateway} configuration is missing [${key}].`);
         this.gateway = gateway;
         this.key = key;
     }

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

@@ -27,29 +27,28 @@ export type FetchFunction = (input: string, init: RequestInit) => Promise<Respon
 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;
+    /** Milliseconds before a request is aborted. `0` disables the timeout. */
+    timeoutMs: number;
 }
-/** 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.
+ * The default {@link HttpClient}: the global `fetch` (or the one you pass) with the timeout you
+ * give it. Gateways build one with their `timeoutSeconds` setting when you pass no client.
  */
 export declare class FetchHttpClient implements HttpClient {
     private readonly fetchFunction;
     private readonly timeoutMs;
-    constructor(options?: FetchHttpClientOptions);
+    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`. */
+    /**
+     * Sends the requests, with its own timeout. Takes precedence over `fetch`. Without one, the
+     * gateway uses a {@link FetchHttpClient} with the config's `timeoutSeconds`.
+     */
     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 {
@@ -57,7 +56,7 @@ export interface RequestOptions {
     signal?: AbortSignal | undefined;
 }
 /** @internal */
-export declare function httpClientFrom(options?: GatewayOptions): HttpClient;
+export declare function httpClientFrom(options: GatewayOptions, timeoutSeconds: number): HttpClient;
 /** A decoded gateway response. @internal */
 export declare class GatewayResponse {
     readonly status: number;

package/dist/esm/core/http.js

@@ -1,17 +1,15 @@
 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.
+ * The default {@link HttpClient}: the global `fetch` (or the one you pass) with the timeout you
+ * give it. Gateways build one with their `timeoutSeconds` setting when you pass no client.
  */
 export class FetchHttpClient {
     fetchFunction;
     timeoutMs;
-    constructor(options = {}) {
+    constructor(options) {
         this.fetchFunction = options.fetch;
-        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.timeoutMs = options.timeoutMs;
     }
     async send(request) {
         const fetchFunction = this.fetchFunction ?? globalThis.fetch;
@@ -38,9 +36,9 @@ export class FetchHttpClient {
     }
 }
 /** @internal */
-export function httpClientFrom(options = {}) {
+export function httpClientFrom(options, timeoutSeconds) {
     return (options.httpClient ??
-        new FetchHttpClient({ fetch: options.fetch, timeoutMs: options.timeoutMs }));
+        new FetchHttpClient({ fetch: options.fetch, timeoutMs: timeoutSeconds * 1000 }));
 }
 /** A decoded gateway response. @internal */
 export class GatewayResponse {

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

@@ -1,8 +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 { DEFAULT_TIMEOUT_SECONDS, 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 { 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

@@ -1,7 +1,8 @@
 export { Amount } from './amount.js';
 export { MemoryTokenCache } from './cache.js';
 export { Acknowledgement, CallbackRequest, PaymentCallback, PaymentStatusResult, } from './callback.js';
+export { DEFAULT_TIMEOUT_SECONDS } from './env.js';
 export { ApiError, ConfigurationError, InvalidPaymentDataError, PaymentError, SignatureVerificationError, } from './errors.js';
-export { DEFAULT_TIMEOUT_MS, FetchHttpClient, } from './http.js';
+export { 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

@@ -32,8 +32,8 @@ export declare function parseJsonObject(text: string): LosslessObject | undefine
 /** @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.
+ * Converts a lossless value to plain JavaScript values for the `raw` fields of results. Numbers
+ * become their exact text as a string (`1000.50` stays `"1000.50"`), so no precision is lost.
  *
  * @internal
  */

package/dist/esm/core/json.js

@@ -46,14 +46,14 @@ export function isLosslessObject(value) {
         !(value instanceof JsonNumber));
 }
 /**
- * Converts a lossless value to plain JavaScript values (numbers become `number`), for the `raw`
- * fields of results.
+ * Converts a lossless value to plain JavaScript values for the `raw` fields of results. Numbers
+ * become their exact text as a string (`1000.50` stays `"1000.50"`), so no precision is lost.
  *
  * @internal
  */
 export function toPlain(value) {
     if (value instanceof JsonNumber) {
-        return Number(value.text);
+        return value.text;
     }
     if (Array.isArray(value)) {
         return value.map(toPlain);

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

@@ -1,7 +1,7 @@
 /**
  * A gateway-independent payment status. Every gateway's own status values are mapped onto these.
  */
-export type PaymentStatus = 'successful' | 'pending' | 'failed' | 'cancelled' | 'expired' | 'unknown';
+export type PaymentStatus = 'successful' | 'pending' | 'failed' | 'canceled' | 'expired' | 'unknown';
 /**
  * The payment statuses, plus helpers.
  *
@@ -18,13 +18,13 @@ export declare const PaymentStatus: Readonly<{
     /** The payment was attempted and failed or was rejected. */
     Failed: "failed";
     /** The payment or order was canceled or closed before completing. */
-    Cancelled: "cancelled";
+    Canceled: "canceled";
     /** 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"];
+    values: readonly ["successful", "pending", "failed", "canceled", "expired", "unknown"];
     /** Whether the status will not change any more: `false` for `pending` and `unknown`. */
     isFinal(status: PaymentStatus): boolean;
 }>;

package/dist/esm/core/status.js

@@ -14,7 +14,7 @@ export const PaymentStatus = Object.freeze({
     /** The payment was attempted and failed or was rejected. */
     Failed: 'failed',
     /** The payment or order was canceled or closed before completing. */
-    Cancelled: 'cancelled',
+    Canceled: 'canceled',
     /** The payment window ran out before the customer paid. */
     Expired: 'expired',
     /** The gateway sent a status this package does not recognize. Inspect `gatewayStatus`. */
@@ -24,7 +24,7 @@ export const PaymentStatus = Object.freeze({
         'successful',
         'pending',
         'failed',
-        'cancelled',
+        'canceled',
         'expired',
         'unknown',
     ]),

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

@@ -14,3 +14,5 @@ export declare function optional(source: Record<string, unknown>, key: string):
 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;
+/** Whether `value` is an object or array, which a gateway never signs. @internal */
+export declare function isNested(value: unknown): boolean;

package/dist/esm/core/values.js

@@ -36,3 +36,7 @@ export function object(source, key) {
     const value = source[key];
     return isLosslessObject(value) ? value : undefined;
 }
+/** Whether `value` is an object or array, which a gateway never signs. @internal */
+export function isNested(value) {
+    return typeof value === 'object' && value !== null && !(value instanceof JsonNumber);
+}

package/dist/esm/cyber-source/cyber-source.d.ts

@@ -10,27 +10,24 @@ export interface CyberSourceConfigOptions {
     accessKey: string;
     /** The profile's secret key, which signs the fields. */
     secretKey: string;
-    /** Use the test environment (default `true`). */
-    sandbox?: boolean | undefined;
-    /** Overrides the Secure Acceptance base URL. */
+    /** Overrides the Secure Acceptance base URL, e.g. to point at the test environment. */
     baseUrl?: string | undefined;
 }
 /**
- * A CyberSource Secure Acceptance profile. A missing credential throws a `ConfigurationError`.
+ * A CyberSource Secure Acceptance profile. A missing credential throws a `ConfigurationError`. The
+ * URL defaults to production.
  */
 export declare class CyberSourceConfig {
-    static readonly SANDBOX_URL = "https://testsecureacceptance.cybersource.com";
     static readonly PRODUCTION_URL = "https://secureacceptance.cybersource.com";
     readonly profileId: string;
     readonly accessKey: string;
     readonly secretKey: string;
-    readonly sandbox: boolean;
     /** The base URL in use. */
     readonly baseUrl: string;
     constructor(options: CyberSourceConfigOptions);
     /**
      * Reads `CYBER_SOURCE_PROFILE_ID`, `CYBER_SOURCE_ACCESS_KEY`, `CYBER_SOURCE_SECRET_KEY`,
-     * `CYBER_SOURCE_SANDBOX` and `CYBER_SOURCE_BASE_URL`.
+     * and `CYBER_SOURCE_BASE_URL`.
      */
     static fromEnv(env?: EnvSource): CyberSourceConfig;
 }
@@ -61,12 +58,12 @@ export interface CyberSourcePaymentData {
     returnUrl?: string | undefined;
     /** The page shown on cancel (`override_custom_cancel_page`), at most 255 characters. */
     cancelUrl?: string | undefined;
-    /** An ISO 4217 code (default `MMK`). */
-    currency?: string | undefined;
-    /** What to do with the card (default `sale`). */
-    transactionType?: CyberSourceTransactionType | undefined;
-    /** The hosted page language, e.g. `en-us` (the default). */
-    locale?: string | undefined;
+    /** An ISO 4217 code, e.g. `MMK`. */
+    currency: string;
+    /** What to do with the card, e.g. `sale`. */
+    transactionType: CyberSourceTransactionType;
+    /** The hosted page language, e.g. `en-us`. */
+    locale: string;
 }
 /**
  * CyberSource Secure Acceptance hosted checkout for card payments: signs the form and verifies the
@@ -87,7 +84,8 @@ export declare class CyberSource {
     initiate(data: CyberSourcePaymentData): FormPayment;
     /**
      * Verifies CyberSource's result post. The same check works for the browser post to your receipt
-     * page.
+     * page. Only the fields listed in `signed_field_names` are trusted: `decision` and
+     * `req_reference_number` must be signed, and unsigned fields are left out of the result.
      */
     handleCallback(request: CallbackRequest): PaymentCallback;
     /** Signs the fields listed in `signed_field_names`; `undefined` when a listed field is missing. */