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

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

@@ -0,0 +1,26 @@
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Stores access tokens between calls (used by Yoma MMQR). Implement it on top of Redis or similar
+ * to share tokens between processes; every method may return a promise.
+ */
+export interface TokenCache {
+    /** The cached value, or `undefined` when it is missing or expired. */
+    get(key: string): MaybePromise<string | undefined | null>;
+    /** Stores `value` for `ttlSeconds`; `0` or less never expires. */
+    set(key: string, value: string, ttlSeconds: number): MaybePromise<unknown>;
+    /** Removes `key`. */
+    delete(key: string): MaybePromise<unknown>;
+}
+/**
+ * The default {@link TokenCache}: a `Map` that lives as long as the process. Share one gateway (or
+ * one cache) across requests so the token is reused.
+ */
+export declare class MemoryTokenCache implements TokenCache {
+    private readonly items;
+    get(key: string): string | undefined;
+    set(key: string, value: string, ttlSeconds: number): void;
+    delete(key: string): void;
+    /** Removes every entry. */
+    clear(): void;
+}
+export {};

package/dist/cjs/core/cache.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryTokenCache = void 0;
+/**
+ * The default {@link TokenCache}: a `Map` that lives as long as the process. Share one gateway (or
+ * one cache) across requests so the token is reused.
+ */
+class MemoryTokenCache {
+    items = new Map();
+    get(key) {
+        const item = this.items.get(key);
+        if (item === undefined) {
+            return undefined;
+        }
+        if (item.expiresAt !== undefined && Date.now() >= item.expiresAt) {
+            this.items.delete(key);
+            return undefined;
+        }
+        return item.value;
+    }
+    set(key, value, ttlSeconds) {
+        this.items.set(key, {
+            value,
+            expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1000 : undefined,
+        });
+    }
+    delete(key) {
+        this.items.delete(key);
+    }
+    /** Removes every entry. */
+    clear() {
+        this.items.clear();
+    }
+}
+exports.MemoryTokenCache = MemoryTokenCache;

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

@@ -0,0 +1,180 @@
+import { type LosslessObject } from './json.js';
+import type { PaymentStatus } from './status.js';
+/** Headers as a Fetch `Headers`, a Node-style object or `[name, value]` pairs. */
+export type HeadersInput = Headers | Readonly<Record<string, string | readonly string[] | undefined>> | Iterable<readonly [string, string]>;
+/** A query string, `URLSearchParams` or an object of values. */
+export type QueryInput = string | URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+/** A request body: text or raw bytes (a `Buffer` works). */
+export type BodyInput = string | Uint8Array | ArrayBuffer;
+/** The parts of a gateway request. */
+export interface CallbackRequestInit {
+    /** The raw request body exactly as received. */
+    body?: BodyInput | null | undefined;
+    /** The request headers. */
+    headers?: HeadersInput | null | undefined;
+    /** The query string parameters. */
+    query?: QueryInput | null | undefined;
+}
+/**
+ * The parts of a Node `http.IncomingMessage` this package reads, so Express, Fastify (`request.raw`)
+ * and Koa (`ctx.req`) requests work too.
+ */
+export interface NodeRequestLike extends AsyncIterable<unknown> {
+    headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    url?: string | undefined;
+    /** A raw body captured by middleware, e.g. `express.raw()` or a `verify` hook. */
+    rawBody?: unknown;
+    /** A body parsed by middleware. Used only when the stream was already consumed. */
+    body?: unknown;
+}
+/** The parts of a Fetch API `Request` this package reads. */
+export interface WebRequestLike {
+    readonly url: string;
+    readonly headers: Headers;
+    readonly bodyUsed: boolean;
+    clone(): {
+        text(): Promise<string>;
+    };
+}
+/**
+ * An incoming request from a gateway (a server callback or a browser return). Signatures are
+ * verified against what the gateway actually sent, so build it from the real request with
+ * {@link CallbackRequest.fromNodeRequest} or {@link CallbackRequest.fromWebRequest}.
+ */
+export declare class CallbackRequest {
+    /** The raw request body, decoded as UTF-8. */
+    readonly body: string;
+    /** The request headers, with lowercase names. Repeated headers are joined with `, `. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The query string parameters (the first value of each). */
+    readonly query: Readonly<Record<string, string>>;
+    constructor(init?: CallbackRequestInit);
+    /** Builds a request from its parts, e.g. to replay a stored callback. */
+    static from(init: CallbackRequestInit): CallbackRequest;
+    /**
+     * Builds a request from a decoded payload, encoded as a JSON body, e.g. to replay a callback
+     * stored as JSON.
+     */
+    static fromJson(payload: unknown, headers?: HeadersInput | null): 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.
+     */
+    static fromNodeRequest(request: NodeRequestLike): Promise<CallbackRequest>;
+    /**
+     * Reads a Fetch API `Request` (Next.js route handlers, Hono, Bun, Deno, Cloudflare Workers). The
+     * body is read from a clone, so the request stays readable.
+     */
+    static fromWebRequest(request: WebRequestLike): Promise<CallbackRequest>;
+    /** The named header, matched case-insensitively, or `undefined`. */
+    header(name: string): string | undefined;
+    /** The body decoded as JSON or as a urlencoded form. */
+    parsedBody(): Record<string, unknown>;
+    /** The parsed body merged over the query string. */
+    input(): Record<string, unknown>;
+    /** The query string merged over the parsed body. */
+    queryInput(): Record<string, unknown>;
+}
+/** The body as JSON (numbers kept exact) or a form, or `{}`. @internal */
+export declare function losslessBody(request: CallbackRequest): LosslessObject;
+/** @internal */
+export declare function losslessInput(request: CallbackRequest): LosslessObject;
+/** @internal */
+export declare function losslessQueryInput(request: CallbackRequest): LosslessObject;
+/** The headers, a status and a body a gateway expects after it delivers a callback. */
+export interface AcknowledgementInit {
+    status?: number | undefined;
+    body?: string | undefined;
+    headers?: Readonly<Record<string, string>> | undefined;
+}
+/** The parts of a Node `http.ServerResponse` (or Express `res`) {@link Acknowledgement.send} uses. */
+export interface ServerResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+}
+/**
+ * The HTTP response a gateway expects after it delivers a callback. Gateways retry until they
+ * receive it.
+ */
+export declare class Acknowledgement {
+    /** The HTTP status, 200 unless a gateway documents another. */
+    readonly status: number;
+    /** The response body, e.g. KBZ Pay's plain `success`. */
+    readonly body: string;
+    /** The response headers. */
+    readonly headers: Readonly<Record<string, string>>;
+    constructor(init?: AcknowledgementInit);
+    /** An empty `200 text/plain` response, which most gateways expect. */
+    static default(): Acknowledgement;
+    /** Writes the acknowledgement to a Node `http.ServerResponse` (or Express `res`) and ends it. */
+    send(response: ServerResponseLike): void;
+    /** The acknowledgement as a Fetch API `Response`, for Next.js, Hono, Bun and other Fetch servers. */
+    toResponse(): Response;
+}
+/** The fields of a {@link PaymentCallback}. */
+export interface PaymentCallbackInit {
+    orderId: string;
+    status: PaymentStatus;
+    gatewayStatus: string;
+    gatewayReference?: string | undefined;
+    amount?: string | undefined;
+    raw?: Readonly<Record<string, unknown>> | undefined;
+    acknowledgement?: Acknowledgement | undefined;
+}
+/**
+ * A gateway notification whose signature has been verified.
+ *
+ * Always compare `amount` with your order before fulfilling it, and handle duplicates: gateways
+ * retry.
+ */
+export declare class PaymentCallback {
+    /** Your order id. */
+    readonly orderId: string;
+    /** The status mapped onto this package's statuses. */
+    readonly status: PaymentStatus;
+    /** The gateway's own status value, unmapped. */
+    readonly gatewayStatus: string;
+    /** The gateway's id for the payment, when it sends one. */
+    readonly gatewayReference: string | undefined;
+    /** The amount the gateway reports, exactly as it sent it, when it sends one. */
+    readonly amount: string | undefined;
+    /** The verified payload. */
+    readonly raw: Readonly<Record<string, unknown>>;
+    /** The response to send so the gateway stops retrying. */
+    readonly acknowledgement: Acknowledgement;
+    constructor(init: PaymentCallbackInit);
+    /** Whether the customer paid. */
+    isSuccessful(): boolean;
+}
+/** The fields of a {@link PaymentStatusResult}. */
+export interface PaymentStatusResultInit {
+    orderId?: string | undefined;
+    status: PaymentStatus;
+    gatewayStatus: string;
+    gatewayReference?: string | undefined;
+    amount?: string | undefined;
+    raw?: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * The state of a payment as reported by a gateway's status API.
+ */
+export declare class PaymentStatusResult {
+    /** Your order id, when the gateway returns it. */
+    readonly orderId: string | undefined;
+    /** The status mapped onto this package's statuses. */
+    readonly status: PaymentStatus;
+    /** The gateway's own status value, unmapped. */
+    readonly gatewayStatus: string;
+    /** The gateway's id for the payment, when it sends one. */
+    readonly gatewayReference: string | undefined;
+    /** The amount the gateway reports, exactly as it sent it, when it sends one. */
+    readonly amount: string | undefined;
+    /** The gateway's response, for logging. */
+    readonly raw: Readonly<Record<string, unknown>>;
+    constructor(init: PaymentStatusResultInit);
+    /** Whether the customer paid. */
+    isSuccessful(): boolean;
+}

package/dist/cjs/core/callback.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentStatusResult = exports.PaymentCallback = exports.Acknowledgement = exports.CallbackRequest = void 0;
+exports.losslessBody = losslessBody;
+exports.losslessInput = losslessInput;
+exports.losslessQueryInput = losslessQueryInput;
+const json_js_1 = require("./json.js");
+/**
+ * An incoming request from a gateway (a server callback or a browser return). Signatures are
+ * verified against what the gateway actually sent, so build it from the real request with
+ * {@link CallbackRequest.fromNodeRequest} or {@link CallbackRequest.fromWebRequest}.
+ */
+class CallbackRequest {
+    /** The raw request body, decoded as UTF-8. */
+    body;
+    /** 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.headers = Object.freeze(normalizeHeaders(init.headers));
+        this.query = Object.freeze(normalizeQuery(init.query));
+    }
+    /** Builds a request from its parts, e.g. to replay a stored callback. */
+    static from(init) {
+        return new CallbackRequest(init);
+    }
+    /**
+     * Builds a request from a decoded payload, encoded as a JSON body, e.g. to replay a callback
+     * stored as JSON.
+     */
+    static fromJson(payload, headers) {
+        return new CallbackRequest({
+            body: JSON.stringify(payload),
+            headers: { ...normalizeHeaders(headers), 'content-type': 'application/json' },
+        });
+    }
+    /**
+     * 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.
+     */
+    static async fromNodeRequest(request) {
+        const headers = normalizeHeaders(request.headers);
+        const query = new URL(request.url ?? '/', 'http://localhost').searchParams;
+        let body = rawBody(request.rawBody) ?? rawBody(request.body);
+        if (body === undefined) {
+            const chunks = [];
+            for await (const chunk of request) {
+                chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+            }
+            body = Buffer.concat(chunks);
+            if (body.length === 0 && isPlainObject(request.body)) {
+                body = encodeParsedBody(request.body, headers['content-type'] ?? '');
+            }
+        }
+        return new CallbackRequest({ body, headers, query });
+    }
+    /**
+     * Reads a Fetch API `Request` (Next.js route handlers, Hono, Bun, Deno, Cloudflare Workers). The
+     * body is read from a clone, so the request stays readable.
+     */
+    static async fromWebRequest(request) {
+        return new CallbackRequest({
+            body: request.bodyUsed ? '' : await request.clone().text(),
+            headers: request.headers,
+            query: new URL(request.url).searchParams,
+        });
+    }
+    /** The named header, matched case-insensitively, or `undefined`. */
+    header(name) {
+        return this.headers[name.toLowerCase()];
+    }
+    /** The body decoded as JSON or as a urlencoded form. */
+    parsedBody() {
+        return (0, json_js_1.toPlainObject)(losslessBody(this));
+    }
+    /** The parsed body merged over the query string. */
+    input() {
+        return (0, json_js_1.toPlainObject)(losslessInput(this));
+    }
+    /** The query string merged over the parsed body. */
+    queryInput() {
+        return (0, json_js_1.toPlainObject)(losslessQueryInput(this));
+    }
+}
+exports.CallbackRequest = CallbackRequest;
+/** The body as JSON (numbers kept exact) or a form, or `{}`. @internal */
+function losslessBody(request) {
+    const body = request.body.trim();
+    if (body === '') {
+        return {};
+    }
+    const json = (0, json_js_1.parseJsonObject)(body);
+    if (json !== undefined) {
+        return json;
+    }
+    return firstValues(new URLSearchParams(body));
+}
+/** @internal */
+function losslessInput(request) {
+    return merge({ ...request.query }, losslessBody(request));
+}
+/** @internal */
+function losslessQueryInput(request) {
+    return merge(losslessBody(request), request.query);
+}
+function merge(target, source) {
+    const result = {};
+    for (const object of [target, source]) {
+        for (const key of Object.keys(object)) {
+            (0, json_js_1.setKey)(result, key, object[key]);
+        }
+    }
+    return result;
+}
+/**
+ * The HTTP response a gateway expects after it delivers a callback. Gateways retry until they
+ * receive it.
+ */
+class Acknowledgement {
+    /** The HTTP status, 200 unless a gateway documents another. */
+    status;
+    /** The response body, e.g. KBZ Pay's plain `success`. */
+    body;
+    /** The response headers. */
+    headers;
+    constructor(init = {}) {
+        this.status = init.status ?? 200;
+        this.body = init.body ?? '';
+        this.headers = Object.freeze({ ...(init.headers ?? { 'Content-Type': 'text/plain' }) });
+    }
+    /** An empty `200 text/plain` response, which most gateways expect. */
+    static default() {
+        return new Acknowledgement();
+    }
+    /** Writes the acknowledgement to a Node `http.ServerResponse` (or Express `res`) and ends it. */
+    send(response) {
+        response.statusCode = this.status;
+        for (const [name, value] of Object.entries(this.headers)) {
+            response.setHeader(name, value);
+        }
+        response.end(this.body);
+    }
+    /** The acknowledgement as a Fetch API `Response`, for Next.js, Hono, Bun and other Fetch servers. */
+    toResponse() {
+        return new Response(this.body, { status: this.status, headers: { ...this.headers } });
+    }
+}
+exports.Acknowledgement = Acknowledgement;
+/**
+ * A gateway notification whose signature has been verified.
+ *
+ * Always compare `amount` with your order before fulfilling it, and handle duplicates: gateways
+ * retry.
+ */
+class PaymentCallback {
+    /** Your order id. */
+    orderId;
+    /** The status mapped onto this package's statuses. */
+    status;
+    /** The gateway's own status value, unmapped. */
+    gatewayStatus;
+    /** The gateway's id for the payment, when it sends one. */
+    gatewayReference;
+    /** The amount the gateway reports, exactly as it sent it, when it sends one. */
+    amount;
+    /** The verified payload. */
+    raw;
+    /** The response to send so the gateway stops retrying. */
+    acknowledgement;
+    constructor(init) {
+        this.orderId = init.orderId;
+        this.status = init.status;
+        this.gatewayStatus = init.gatewayStatus;
+        this.gatewayReference = init.gatewayReference;
+        this.amount = init.amount;
+        this.raw = init.raw ?? {};
+        this.acknowledgement = init.acknowledgement ?? Acknowledgement.default();
+    }
+    /** Whether the customer paid. */
+    isSuccessful() {
+        return this.status === 'successful';
+    }
+}
+exports.PaymentCallback = PaymentCallback;
+/**
+ * The state of a payment as reported by a gateway's status API.
+ */
+class PaymentStatusResult {
+    /** Your order id, when the gateway returns it. */
+    orderId;
+    /** The status mapped onto this package's statuses. */
+    status;
+    /** The gateway's own status value, unmapped. */
+    gatewayStatus;
+    /** The gateway's id for the payment, when it sends one. */
+    gatewayReference;
+    /** The amount the gateway reports, exactly as it sent it, when it sends one. */
+    amount;
+    /** The gateway's response, for logging. */
+    raw;
+    constructor(init) {
+        this.orderId = init.orderId;
+        this.status = init.status;
+        this.gatewayStatus = init.gatewayStatus;
+        this.gatewayReference = init.gatewayReference;
+        this.amount = init.amount;
+        this.raw = init.raw ?? {};
+    }
+    /** Whether the customer paid. */
+    isSuccessful() {
+        return this.status === 'successful';
+    }
+}
+exports.PaymentStatusResult = PaymentStatusResult;
+function bodyText(body) {
+    if (body === undefined || body === null) {
+        return '';
+    }
+    if (typeof body === 'string') {
+        return body;
+    }
+    return new TextDecoder().decode(body);
+}
+function rawBody(value) {
+    if (typeof value === 'string' || value instanceof Uint8Array || value instanceof ArrayBuffer) {
+        return value;
+    }
+    return undefined;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function encodeParsedBody(body, contentType) {
+    if (!contentType.toLowerCase().includes('urlencoded')) {
+        return JSON.stringify(body);
+    }
+    const form = new URLSearchParams();
+    for (const [key, value] of Object.entries(body)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+            form.append(key, String(item));
+        }
+    }
+    return form.toString();
+}
+function normalizeHeaders(headers) {
+    const result = {};
+    if (headers === undefined || headers === null) {
+        return result;
+    }
+    const add = (name, value) => {
+        if (value === undefined) {
+            return;
+        }
+        const text = typeof value === 'string' ? value : value.join(', ');
+        const key = name.toLowerCase();
+        (0, json_js_1.setKey)(result, key, result[key] === undefined ? text : `${result[key]}, ${text}`);
+    };
+    if (typeof headers.forEach === 'function' &&
+        typeof headers.get === 'function') {
+        headers.forEach((value, name) => {
+            add(name, value);
+        });
+    }
+    else if (Symbol.iterator in headers) {
+        for (const [name, value] of headers) {
+            add(name, value);
+        }
+    }
+    else {
+        for (const [name, value] of Object.entries(headers)) {
+            add(name, value);
+        }
+    }
+    return result;
+}
+function normalizeQuery(query) {
+    if (query === undefined || query === null) {
+        return {};
+    }
+    if (typeof query === 'string' || query instanceof URLSearchParams) {
+        return firstValues(new URLSearchParams(query));
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(query)) {
+        const first = typeof value === 'string' ? value : value?.[0];
+        if (first !== undefined) {
+            (0, json_js_1.setKey)(result, key, first);
+        }
+    }
+    return result;
+}
+function firstValues(params) {
+    const result = {};
+    for (const [key, value] of params) {
+        if (!Object.prototype.hasOwnProperty.call(result, key)) {
+            (0, json_js_1.setKey)(result, key, value);
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,19 @@
+/** HMAC-SHA256 of `message`, hex encoded. @internal */
+export declare function hmacSha256Hex(key: string, message: string): string;
+/** HMAC-SHA256 of `message`, base64 encoded. @internal */
+export declare function hmacSha256Base64(key: string, message: string): string;
+/** SHA-256 of `message`, hex encoded. @internal */
+export declare function sha256Hex(message: string): string;
+/** Compares two strings in constant time (for equal lengths). @internal */
+export declare function safeEqual(expected: string, actual: string): boolean;
+/** `bytes` random bytes, hex encoded. @internal */
+export declare function randomHex(bytes?: number): string;
+/**
+ * Escapes text like Go's `url.QueryEscape` and PHP's `urlencode`: everything except letters,
+ * digits and `-_.~` is percent-encoded and spaces become `+`.
+ *
+ * @internal
+ */
+export declare function queryEscape(value: string): string;
+/** Decodes strict standard base64 (with padding), or `undefined`. @internal */
+export declare function decodeBase64(value: string): string | undefined;

package/dist/cjs/core/crypto.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hmacSha256Hex = hmacSha256Hex;
+exports.hmacSha256Base64 = hmacSha256Base64;
+exports.sha256Hex = sha256Hex;
+exports.safeEqual = safeEqual;
+exports.randomHex = randomHex;
+exports.queryEscape = queryEscape;
+exports.decodeBase64 = decodeBase64;
+const node_crypto_1 = require("node:crypto");
+/** HMAC-SHA256 of `message`, hex encoded. @internal */
+function hmacSha256Hex(key, message) {
+    return (0, node_crypto_1.createHmac)('sha256', key).update(message, 'utf8').digest('hex');
+}
+/** HMAC-SHA256 of `message`, base64 encoded. @internal */
+function hmacSha256Base64(key, message) {
+    return (0, node_crypto_1.createHmac)('sha256', key).update(message, 'utf8').digest('base64');
+}
+/** SHA-256 of `message`, hex encoded. @internal */
+function sha256Hex(message) {
+    return (0, node_crypto_1.createHash)('sha256').update(message, 'utf8').digest('hex');
+}
+/** Compares two strings in constant time (for equal lengths). @internal */
+function safeEqual(expected, actual) {
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(actual, 'utf8');
+    return a.length === b.length && (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/** `bytes` random bytes, hex encoded. @internal */
+function randomHex(bytes = 16) {
+    return (0, node_crypto_1.randomBytes)(bytes).toString('hex');
+}
+/**
+ * Escapes text like Go's `url.QueryEscape` and PHP's `urlencode`: everything except letters,
+ * digits and `-_.~` is percent-encoded and spaces become `+`.
+ *
+ * @internal
+ */
+function queryEscape(value) {
+    return encodeURIComponent(value)
+        .replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)
+        .replace(/%20/g, '+');
+}
+/** Decodes strict standard base64 (with padding), or `undefined`. @internal */
+function decodeBase64(value) {
+    if (value === '' || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+        return undefined;
+    }
+    return Buffer.from(value, 'base64').toString('utf8');
+}

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

@@ -0,0 +1,21 @@
+/** Environment variables, e.g. `process.env`. */
+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.
+ *
+ * @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;
+/** 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 */
+export declare function optionalSetting(value: unknown): string | undefined;
+/** Removes trailing slashes. @internal */
+export declare function trimUrl(url: string): string;
+/** The default environment: `process.env`. @internal */
+export declare function defaultEnv(): EnvSource;