@herberthtk/yo-payments-api 0.1.0

package/dist/index.js

@@ -0,0 +1,828 @@
+// src/errors.ts
+var YoAPIError = class extends Error {
+  /** HTTP status code when the failure came with an HTTP response. */
+  status;
+  /** Truncated response body (up to 500 chars) when one was received. */
+  body;
+  constructor(message, options) {
+    super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "YoAPIError";
+    this.status = options?.status;
+    this.body = options?.body;
+  }
+};
+
+// src/YoAPI.ts
+import { createHash, createPrivateKey, sign as rsaSign, verify as rsaVerify } from "crypto";
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/constants.ts
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+// src/embeddedCerts.ts
+var YO_UGANDA_SANDBOX_CERTIFICATE = "-----BEGIN CERTIFICATE-----\nMIIGJTCCBA2gAwIBAgIJALqNKn338j3LMA0GCSqGSIb3DQEBCwUAMIGoMQswCQYD\nVQQGEwJVRzEPMA0GA1UECAwGVWdhbmRhMRAwDgYDVQQHDAdLYW1wYWxhMRowGAYD\nVQQKDBFZbyBVZ2FuZGEgTGltaXRlZDEeMBwGA1UECwwVWW8hIFBheW1lbnRzIFNl\nY3VyaXR5MRkwFwYDVQQDDBBzYW5kYm94LnlvLmNvLnVnMR8wHQYJKoZIhvcNAQkB\nFhBzdXBwb3J0QHlvLmNvLnVnMB4XDTIzMTExMDA5Mjg0NFoXDTQzMTEwNTA5Mjg0\nNFowgagxCzAJBgNVBAYTAlVHMQ8wDQYDVQQIDAZVZ2FuZGExEDAOBgNVBAcMB0th\nbXBhbGExGjAYBgNVBAoMEVlvIFVnYW5kYSBMaW1pdGVkMR4wHAYDVQQLDBVZbyEg\nUGF5bWVudHMgU2VjdXJpdHkxGTAXBgNVBAMMEHNhbmRib3gueW8uY28udWcxHzAd\nBgkqhkiG9w0BCQEWEHN1cHBvcnRAeW8uY28udWcwggIiMA0GCSqGSIb3DQEBAQUA\nA4ICDwAwggIKAoICAQDX9GqOzAK5CG/K7ndZnr+Zi1kTiQ8BS6sH7NnsQPLv0sVa\nCZ5mclhdSaeDe4d+atVT6SMvB5zu1KSGmJ3iX7S0B/ctkQUaw6HuvPWfDqWTHO+G\nJehGEJfcEzSbGw/t3/mByJTFOOaUDG4riqXCYX+C/rcF3dZEgMKTzTWWx9sMuZRO\ni9Atn8QGrCecTILn/VGQHw94P/FU6CjEwnOCPbx6ErWkNUSDx9e/e8pSzPn2sWYE\ngBE+joy0itpehIfnUig0G57zsfqE5GC8yNKP47NIsdeR83I3mCjxjKVQ2F/kLBXM\ni/TALadUI36dmvtVkaJEAyCA5tdUOkuUuPaang1hoUBRO0Iz14y+hoSqe37JlhPN\n3jtxmOXJ5j0neSlXH/4JtSv+yy0o1J0VxTIjKMWSJGeWsn3Q/dMDEr35NQ+MI129\nVqmmRpjCAR+5aJjBBfckI12l0oKhtS3XAgc6S1mhbatvyCyh4g6pAEo9/1rT2iRJ\nmdCOztvJejEecuYJPcwzI67LfPxhEKpalAy9LD8mZbs85eq/0o9VhpSp8/BRErqg\nA2M0rYrD/GaE1B/4k0d2sbuQ3M/2LvWfCL75TzxNgEld/6x2dp+59WrYcdoj91b4\nnh30WeYRN1fB4Vg0zYJssPfOWB3Ucj5GpayGgRaKgJL/On4f69BocDdXvUr8zwID\nAQABo1AwTjAdBgNVHQ4EFgQUkBq/k9Kveaw40I2iXIvZGOT5q4kwHwYDVR0jBBgw\nFoAUkBq/k9Kveaw40I2iXIvZGOT5q4kwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0B\nAQsFAAOCAgEAQ43vDjl7PDuPFzDlqTfPo8ed2CVYtwSM+uhMIim5UdFai3fzMGUa\n27FSXdHU6VnSw7MuJlF4BHmptW6Z+kIv0+E2x8FUj12GSruJihkNAwMC3KAUH9qT\nNSr5/aSdaM0o9VyAWLE6XhNBSHwVaPItnIktlq9JGwHmlHcNoyOo0bAhf36aWp1f\nKJhSpx4yXg/8KIiYIlV9GpK2877eRBbnpobNHbVzrpFnpVryRHtvecKYBGNh0gII\n+QstdRgCxRPuLJ1JatekSUDgmkcMgGIrM/scAaBL+MrgdZiALlPJTp1sABIeRUxL\nwdrizMfwtHfLizaWTs8bedBDAVbn/fiARcjDbnx5nec2sczCGI7eVPpF20qdGhBc\npC1nt+zGEdEqO7KLQFzuqvez+NXdnjk82RC/CzOSCL9bYo2b0vVGLEtb1oufm3xZ\nn4+nx+VCkPM5++rXGiUjr4lhyRDzrlVEdOD9hW/V5rkM2vgqGOGaJPOem5Dcvgfx\nkG4vwmPAzEYYaVbq8F2H4uirIzmDYlnmrX6ir/DESaVynjyQzMo6bcaey3ukFRM/\n3fLASrGyxOm0ffGoiT1Y4Rus68EV4wBLcSe9v/npWxlf7nMhdiAwn4sRr00yciuu\nVHxWRkVTpePhScSglaj9fcjnMb0OiaeX4TXOAw/UWpW/jDpo4WFZfgI=\n-----END CERTIFICATE-----\n";
+var YO_UGANDA_PRODUCTION_CERTIFICATE = "-----BEGIN CERTIFICATE-----\nMIIEvTCCA6WgAwIBAgIJAN3e7VqDg5zQMA0GCSqGSIb3DQEBBQUAMIGaMQswCQYD\nVQQGEwJVRzEQMA4GA1UECBMHS2FtcGFsYTEQMA4GA1UEBxMHS2FtcGFsYTEbMBkG\nA1UECgwSWW8hIFVnYW5kYSBMaW1pdGVkMRUwEwYDVQQLDAxZbyEgUGF5bWVudHMx\nFTATBgNVBAMTDHd3dy55by5jby51ZzEcMBoGCSqGSIb3DQEJARYNaW5mb0B5by5j\nby51ZzAeFw0xMzA4MDkwNTQyMTRaFw0yMzA4MDcwNTQyMTRaMIGaMQswCQYDVQQG\nEwJVRzEQMA4GA1UECBMHS2FtcGFsYTEQMA4GA1UEBxMHS2FtcGFsYTEbMBkGA1UE\nCgwSWW8hIFVnYW5kYSBMaW1pdGVkMRUwEwYDVQQLDAxZbyEgUGF5bWVudHMxFTAT\nBgNVBAMTDHd3dy55by5jby51ZzEcMBoGCSqGSIb3DQEJARYNaW5mb0B5by5jby51\nZzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAPPo+N67Z56ebScXJ9tX\ntFpSNBNNyDlqU/X8bqouZjWuvxpWOI4xZkPKXi0t205ooVbQL/+962NASjJRrouQ\nIUhJq7xhwb+KKcWyFpA25742mNgaxeZJa9iofiHeKotBvHz6pswuqa2gXAyTTmYf\nj6BOIFhDeUffOjfJYbzACy7WLtbK6VIRSTHypQY+zMQluw1euyY8524GYzf8E+c5\n9qjIa5YY5PPianvvR25VDNRCm0Z6GPolhIGvYPUWHFZx+HtU8xoZumi5Kddvipew\nuujxNVBRyQ8bVRoYxKKuDMFHiXA6V01oPzSOtfPK7JI+rd2JFU7dQgbFxTXI9+Qx\n2yUCAwEAAaOCAQIwgf8wHQYDVR0OBBYEFPj0nwwE8lJByx243yV6cfXbTKbhMIHP\nBgNVHSMEgccwgcSAFPj0nwwE8lJByx243yV6cfXbTKbhoYGgpIGdMIGaMQswCQYD\nVQQGEwJVRzEQMA4GA1UECBMHS2FtcGFsYTEQMA4GA1UEBxMHS2FtcGFsYTEbMBkG\nA1UECgwSWW8hIFVnYW5kYSBMaW1pdGVkMRUwEwYDVQQLDAxZbyEgUGF5bWVudHMx\nFTATBgNVBAMTDHd3dy55by5jby51ZzEcMBoGCSqGSIb3DQEJARYNaW5mb0B5by5j\nby51Z4IJAN3e7VqDg5zQMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEFBQADggEB\nAGCaUMHBxGVtVsA8xMDWknjH6hV9yuca3s0qRrOoMfM7nyOjeYtUNgZlsLxuX2n3\nFhoeK9DUBvIKVSlVfO5SXgsXyWKG54YFEkZ8D50Krsyl5NCfaAJezkQ0MNdtpG98\nwlD/cYa6C6DC/s1eilUbI5QqaxLo+EFy5VuHQ8tAuxJbNTVPMW9GvTjxofeMUnug\nSxUMDqHmEkzbQV7yCBVqf3yi4XOM4/6B7Tr6gaandpuR+v2XaKl4SOf8G5svn96g\nKn+Bk8p6rlBWAl+5hWxHWi4dkjiLsk8q+aeKh6ibwYtRjEt/sbWTgJAZjI1mTT8d\nwsLYlL7k1O3wCjUeMQzi274=\n-----END CERTIFICATE-----\n";
+
+// src/constants.ts
+var SANDBOX_URL = "https://sandbox.yo.co.ug/services/yopaymentsdev/task.php";
+var PRODUCTION_URL = "https://paymentsapi1.yo.co.ug/ybs/task.php";
+var PUBLIC_KEY_FILE_FOR_SANDBOX = "Yo_Uganda_Public_Sandbox_Certificate.crt";
+var PUBLIC_KEY_FILE_FOR_PRODUCTION = "Yo_Uganda_Public_Certificate.crt";
+var DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
+var MODULE_DIR = resolveModuleDir();
+var CERTS_DIR = join(MODULE_DIR, "..", "certs");
+function resolveModuleDir() {
+  try {
+    const metaUrl = import.meta?.url;
+    if (typeof metaUrl === "string" && metaUrl.length > 0) {
+      return dirname(fileURLToPath(metaUrl));
+    }
+  } catch {
+  }
+  return process.cwd();
+}
+function defaultVerificationCertificate(mode) {
+  return mode === "sandbox" ? YO_UGANDA_SANDBOX_CERTIFICATE : YO_UGANDA_PRODUCTION_CERTIFICATE;
+}
+
+// src/http.ts
+async function postXml(url, xml, options) {
+  const init = {
+    method: "POST",
+    body: xml,
+    headers: {
+      "Content-Type": "text/xml",
+      "Content-transfer-encoding": "text",
+      "Content-Length": String(Buffer.byteLength(xml))
+    }
+  };
+  if (options.timeoutMs > 0) {
+    init.signal = AbortSignal.timeout(options.timeoutMs);
+  }
+  if (!options.verifyTls) {
+    init.tls = { rejectUnauthorized: false };
+  }
+  let res;
+  try {
+    res = await fetch(url, init);
+  } catch (error) {
+    throw new YoAPIError(
+      `Request to the Yo! Payments gateway failed: ${error?.message ?? error}`,
+      { cause: error }
+    );
+  }
+  const text = await readBoundedText(res, options.maxResponseBytes);
+  if (!res.ok) {
+    throw new YoAPIError(`Yo! Payments gateway responded with HTTP ${res.status}`, {
+      status: res.status,
+      body: text.slice(0, 500)
+    });
+  }
+  return text;
+}
+async function readBoundedText(res, limit) {
+  const declared = res.headers.get("content-length");
+  if (declared !== null && Number(declared) > limit) {
+    throw new YoAPIError(
+      `Yo! Payments gateway response (${declared} bytes) exceeds the limit of ${limit} bytes`
+    );
+  }
+  if (res.body === null) {
+    return "";
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > limit) {
+        await reader.cancel().catch(() => void 0);
+        throw new YoAPIError(
+          `Yo! Payments gateway response exceeds the limit of ${limit} bytes`
+        );
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+// src/keys.ts
+import { createPublicKey } from "crypto";
+import { readFileSync, statSync } from "fs";
+var publicKeyCache = /* @__PURE__ */ new Map();
+function loadPublicKeyCached(filePath, fallbackPem) {
+  const fromFile = loadFromFile(filePath);
+  if (fromFile !== null) return fromFile;
+  if (fallbackPem === void 0) return null;
+  try {
+    return createPublicKey(fallbackPem);
+  } catch {
+    return null;
+  }
+}
+function loadFromFile(filePath) {
+  let size;
+  let mtimeMs;
+  try {
+    const stat = statSync(filePath);
+    size = stat.size;
+    mtimeMs = stat.mtimeMs;
+  } catch {
+    return null;
+  }
+  const cached = publicKeyCache.get(filePath);
+  if (cached !== void 0 && cached.size === size && cached.mtimeMs === mtimeMs) {
+    return cached.key;
+  }
+  try {
+    const key = createPublicKey(readFileSync(filePath, "utf-8"));
+    publicKeyCache.set(filePath, { size, mtimeMs, key });
+    return key;
+  } catch {
+    return null;
+  }
+}
+
+// src/xml.ts
+import { XMLParser, XMLValidator } from "fast-xml-parser";
+var XML_HEADER = '<?xml version="1.0" encoding="UTF-8"?>';
+var responseParser = new XMLParser({
+  ignoreAttributes: true,
+  parseTagValue: false,
+  ignoreDeclaration: true,
+  ignorePiTags: true
+});
+function el(tag, value) {
+  return `<${tag}>${value}</${tag}>`;
+}
+function opt(tag, value) {
+  if (value === null || value === void 0 || value === "") return "";
+  return el(tag, value);
+}
+function str(value) {
+  if (value === void 0 || value === null) return "";
+  if (typeof value === "object") return "";
+  return String(value);
+}
+function setIfNonEmpty(target, key, value) {
+  if (value !== "" && value !== "0") target[key] = value;
+}
+function setIfNotNull(target, key, value) {
+  if (value === void 0 || value === null) return;
+  if (typeof value === "object") return;
+  if (String(value) !== "") target[key] = String(value);
+}
+function asArray(value) {
+  if (value === void 0 || value === null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function asRecord(value) {
+  if (value === void 0 || value === null || typeof value !== "object") return {};
+  return value;
+}
+function parseGatewayResponse(responseXml) {
+  const validation = XMLValidator.validate(responseXml);
+  if (validation !== true) {
+    throw new YoAPIError(`Invalid XML response from the Yo! Payments gateway: ${validation.err.msg}`, {
+      body: responseXml.slice(0, 500)
+    });
+  }
+  const doc = asRecord(responseParser.parse(responseXml));
+  if (doc.Response !== void 0) return doc;
+  for (const value of Object.values(doc)) {
+    const node = asRecord(value);
+    if (node.Response !== void 0) return node;
+  }
+  throw new YoAPIError("Yo! Payments gateway response did not contain a <Response> node", {
+    body: responseXml.slice(0, 500)
+  });
+}
+
+// src/YoAPI.ts
+var YoAPI = class {
+  /** The Yo! Payments API Username. Required. */
+  username;
+  /** The Yo! Payments API Password. Required. */
+  password;
+  /** Whether the gateway connection is held open until the request completes. Default "FALSE". */
+  nonBlocking = "FALSE";
+  /** An externally agreed reference (e.g. an invoice number). */
+  externalReference = null;
+  /** A reference code related to another Yo! Payments system transaction. */
+  internalReference = null;
+  /** Text appended to the confirmation SMS sent by the mobile money provider. */
+  providerReferenceText = null;
+  /** URL notified as soon as funds are successfully deposited into your account. */
+  instantNotificationUrl = null;
+  /** URL notified as soon as a deposit request fails. */
+  failureNotificationUrl = null;
+  /** May be required to authenticate certain deposit requests. */
+  authenticationSignatureBase64 = null;
+  /** "PULL" or "PUSH". Default "PULL". */
+  depositTransactionType = "PULL";
+  /** The URL API requests are submitted to. */
+  yoUrl = PRODUCTION_URL;
+  /** Certificate used to verify IPN signatures (sandbox or production). */
+  publicKeyFile;
+  /** Whether publicKeyFile is still the bundled default (enables the embedded-cert fallback). */
+  publicKeyFileIsDefault = true;
+  transactionLimitAccountIdentifier = null;
+  /** Unique nonce per request, required when public key authentication is enabled. */
+  publicKeyAuthenticationNonce = null;
+  /** Base64 RSA signature over SHA1(username+amount+account+narrative+external_ref+nonce). */
+  publicKeyAuthenticationSignatureBase64 = null;
+  /** Location of the private key used to sign the public key authentication signature. */
+  privateKeyFileLocation = null;
+  /**
+   * Private key PEM content used to sign the public key authentication signature.
+   * Prefer this over a file location on serverless/bundled hosts where the
+   * filesystem is ephemeral (e.g. Vercel). Takes precedence when both are set.
+   */
+  privateKeyContent = null;
+  mode;
+  /** Request timeout in milliseconds (PHP library uses curl timeout 120s). <= 0 means no timeout, like curl. */
+  timeoutMs = 12e4;
+  /**
+   * Whether to verify the gateway TLS certificate. Default true.
+   * The PHP library disables peer verification; this port verifies by default and
+   * only skips verification when explicitly opted out via setTlsVerificationEnabled(false).
+   */
+  verifyTls = true;
+  /** Maximum accepted gateway response body in bytes (default 1 MiB). */
+  maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES;
+  constructor(username, password, mode = "production") {
+    this.username = username;
+    this.password = password;
+    this.mode = mode;
+    if (mode === "sandbox") {
+      this.yoUrl = SANDBOX_URL;
+      this.publicKeyFile = join2(CERTS_DIR, PUBLIC_KEY_FILE_FOR_SANDBOX);
+    } else {
+      this.yoUrl = PRODUCTION_URL;
+      this.publicKeyFile = join2(CERTS_DIR, PUBLIC_KEY_FILE_FOR_PRODUCTION);
+    }
+  }
+  /** Returns the mode ("production" or "sandbox") this instance was created with. */
+  getMode() {
+    return this.mode;
+  }
+  /** Set the API Username. */
+  setUsername(username) {
+    this.username = username;
+  }
+  /** Returns the API Username. */
+  getUsername() {
+    return this.username;
+  }
+  /** Set the API Password. */
+  setPassword(password) {
+    this.password = password;
+  }
+  /** Returns the API Password. */
+  getPassword() {
+    return this.password;
+  }
+  /** Set the URL to submit API requests to. */
+  setUrl(url) {
+    this.yoUrl = url;
+  }
+  /** Returns the URL API requests are submitted to. */
+  getUrl() {
+    return this.yoUrl;
+  }
+  /** Set the path of the certificate used to verify IPN signatures. */
+  setPublicKeyFileUrl(publicKeyFileUrl) {
+    this.publicKeyFile = publicKeyFileUrl;
+    this.publicKeyFileIsDefault = false;
+  }
+  /** Returns the path of the certificate used to verify IPN signatures. */
+  getPublicKeyFileUrl() {
+    return this.publicKeyFile;
+  }
+  /** Set the NonBlocking variable: "TRUE" for non-blocking API requests. */
+  setNonblocking(nonblocking) {
+    this.nonBlocking = nonblocking;
+  }
+  /** Returns the NonBlocking variable. */
+  getNonblocking() {
+    return this.nonBlocking;
+  }
+  /** Set the External Reference used when submitting payment requests. */
+  setExternalReference(externalReference) {
+    this.externalReference = externalReference;
+  }
+  /** Returns the externalReference variable. */
+  getExternalReference() {
+    return this.externalReference;
+  }
+  /** Set the Internal Reference used when submitting payment requests. */
+  setInternalReference(internalReference) {
+    this.internalReference = internalReference;
+  }
+  /** Returns the internalReference variable. */
+  getInternalReference() {
+    return this.internalReference;
+  }
+  /** Set the Provider Reference Text used when submitting payment requests. */
+  setProviderReferenceText(providerReferenceText) {
+    this.providerReferenceText = providerReferenceText;
+  }
+  /** Returns the providerReferenceText variable. */
+  getProviderReferenceText() {
+    return this.providerReferenceText;
+  }
+  /** Set the Instant Notification URL (useful for non-blocking requests). */
+  setInstantNotificationUrl(instantNotificationUrl) {
+    this.instantNotificationUrl = instantNotificationUrl;
+  }
+  /** Returns the instantNotificationUrl variable. */
+  getInstantNotificationUrl() {
+    return this.instantNotificationUrl;
+  }
+  /** Set the Failure Notification URL (useful for non-blocking requests). */
+  setFailureNotificationUrl(failureNotificationUrl) {
+    this.failureNotificationUrl = failureNotificationUrl;
+  }
+  /** Returns the failureNotificationUrl variable. */
+  getFailureNotificationUrl() {
+    return this.failureNotificationUrl;
+  }
+  /** Set the Authentication Signature Base64. */
+  setAuthenticationSignatureBase64(authenticationSignatureBase64) {
+    this.authenticationSignatureBase64 = authenticationSignatureBase64;
+  }
+  /** Returns the Authentication Signature Base64 variable. */
+  getAuthenticationSignatureBase64() {
+    return this.authenticationSignatureBase64;
+  }
+  /** Set the Deposit Transaction Type ("PULL" or "PUSH") used by acTransactionCheckStatus. */
+  setDepositTransactionType(depositTransactionType) {
+    this.depositTransactionType = depositTransactionType;
+  }
+  /** Returns the Deposit Transaction Type variable. */
+  getDepositTransactionType() {
+    return this.depositTransactionType;
+  }
+  /** Set the Transaction Limit Account Identifier (refer to your account administrator). */
+  setTransactionLimitAccountIdentifier(transactionLimitAccountIdentifier) {
+    this.transactionLimitAccountIdentifier = transactionLimitAccountIdentifier;
+  }
+  /** Returns the Transaction Limit Account Identifier variable. */
+  getTransactionLimitAccountIdentifier() {
+    return this.transactionLimitAccountIdentifier;
+  }
+  /** Set the Public Key Authentication Nonce (refer to your account administrator). */
+  setPublicKeyAuthenticationNonce(publicKeyAuthenticationNonce) {
+    this.publicKeyAuthenticationNonce = publicKeyAuthenticationNonce;
+  }
+  /** Returns the Public Key Authentication Nonce variable. */
+  getPublicKeyAuthenticationNonce() {
+    return this.publicKeyAuthenticationNonce;
+  }
+  /** Set the Public Key Authentication Base64-Encoded Signature (refer to your account administrator). */
+  setPublicKeyAuthenticationSignatureBase64(publicKeyAuthenticationSignatureBase64) {
+    this.publicKeyAuthenticationSignatureBase64 = publicKeyAuthenticationSignatureBase64;
+  }
+  /** Returns the Public Key Authentication Base64-Encoded Signature variable. */
+  getPublicKeyAuthenticationSignatureBase64() {
+    return this.publicKeyAuthenticationSignatureBase64;
+  }
+  /** Set the location of the private key used to sign the public key authentication signature. */
+  setPrivateKeyFileLocation(privateKeyFileLocation) {
+    this.privateKeyFileLocation = privateKeyFileLocation;
+  }
+  /** Returns the Private Key File variable. */
+  getPrivateKeyFileLocation() {
+    return this.privateKeyFileLocation;
+  }
+  /**
+   * Set the private key PEM content directly (alternative to setPrivateKeyFileLocation).
+   * Useful where key files are unavailable, e.g. serverless deployments reading
+   * the key from an environment variable. Takes precedence when both are set.
+   */
+  setPrivateKeyContent(privateKeyContent) {
+    this.privateKeyContent = privateKeyContent;
+  }
+  /** Returns the Private Key PEM content variable. */
+  getPrivateKeyContent() {
+    return this.privateKeyContent;
+  }
+  /** Set the request timeout in milliseconds. Values <= 0 disable the timeout (like PHP curl timeout 0). */
+  setTimeout(timeoutMs) {
+    this.timeoutMs = timeoutMs;
+  }
+  /** Returns the request timeout in milliseconds. */
+  getTimeout() {
+    return this.timeoutMs;
+  }
+  /**
+   * Enable or disable verification of the gateway TLS certificate (default enabled).
+   * Disable only for testing against endpoints with self-signed certificates —
+   * the PHP library always skips verification.
+   * Note: the underlying mechanism is a Bun fetch extension; on Node.js, disabling
+   * verification additionally requires NODE_TLS_REJECT_UNAUTHORIZED=0 in the environment.
+   */
+  setTlsVerificationEnabled(enabled) {
+    this.verifyTls = enabled;
+  }
+  /** Returns whether gateway TLS certificate verification is enabled. */
+  getTlsVerificationEnabled() {
+    return this.verifyTls;
+  }
+  /** Set the maximum accepted gateway response body in bytes (default 1048576). */
+  setMaxResponseBytes(maxResponseBytes) {
+    this.maxResponseBytes = maxResponseBytes;
+  }
+  /** Returns the maximum accepted gateway response body in bytes. */
+  getMaxResponseBytes() {
+    return this.maxResponseBytes;
+  }
+  /**
+   * Request Mobile Money User to deposit funds into your account.
+   * Shortly after submitting, the mobile money user receives an on-screen prompt to
+   * authorize the transfer. Not supported by all mobile money operator networks.
+   * @param msisdn the mobile money phone number in the format 256772123456
+   * @param amount the amount to deposit into your account (fractions supported)
+   * @param narrative the reason for the mobile money user to deposit funds
+   */
+  async acDepositFunds(msisdn, amount, narrative) {
+    const xml = this.requestXml(
+      this.authXml() + el("Method", "acdepositfunds") + el("NonBlocking", this.nonBlocking) + el("Account", msisdn) + el("Amount", amount) + el("Narrative", narrative) + opt("ExternalReference", this.externalReference) + opt("InternalReference", this.internalReference) + opt("ProviderReferenceText", this.providerReferenceText) + opt("InstantNotificationUrl", this.instantNotificationUrl) + opt("FailureNotificationUrl", this.failureNotificationUrl) + opt("AuthenticationSignatureBase64", this.authenticationSignatureBase64)
+    );
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode),
+      StatusMessage: str(response.StatusMessage),
+      TransactionStatus: str(response.TransactionStatus)
+    };
+    setIfNonEmpty(result, "ErrorMessageCode", str(response.ErrorMessageCode));
+    setIfNonEmpty(result, "ErrorMessage", str(response.ErrorMessage));
+    setIfNonEmpty(result, "TransactionReference", str(response.TransactionReference));
+    setIfNonEmpty(result, "MNOTransactionReferenceId", str(response.MNOTransactionReferenceId));
+    setIfNonEmpty(result, "IssuedReceiptNumber", str(response.IssuedReceiptNumber));
+    return result;
+  }
+  /**
+   * Check the status of a transaction that was earlier submitted for processing.
+   * Particularly useful when NonBlocking is "TRUE".
+   * @param transactionReference the gateway reference uniquely identifying the transaction
+   * @param privateTransactionReference the External Reference used to carry out the transaction
+   */
+  async acTransactionCheckStatus(transactionReference, privateTransactionReference = null) {
+    const xml = this.requestXml(
+      this.authXml() + el("Method", "actransactioncheckstatus") + opt("TransactionReference", transactionReference) + opt("PrivateTransactionReference", privateTransactionReference) + el("DepositTransactionType", this.depositTransactionType)
+    );
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode),
+      StatusMessage: str(response.StatusMessage),
+      TransactionStatus: str(response.TransactionStatus)
+    };
+    setIfNonEmpty(result, "ErrorMessageCode", str(response.ErrorMessageCode));
+    setIfNonEmpty(result, "ErrorMessage", str(response.ErrorMessage));
+    setIfNonEmpty(result, "TransactionReference", str(response.TransactionReference));
+    setIfNonEmpty(result, "MNOTransactionReferenceId", str(response.MNOTransactionReferenceId));
+    setIfNonEmpty(result, "Amount", str(response.Amount));
+    setIfNonEmpty(result, "AmountFormatted", str(response.AmountFormatted));
+    setIfNonEmpty(result, "CurrencyCode", str(response.CurrencyCode));
+    setIfNonEmpty(result, "TransactionInitiationDate", str(response.TransactionInitiationDate));
+    setIfNonEmpty(result, "TransactionCompletionDate", str(response.TransactionCompletionDate));
+    setIfNonEmpty(result, "IssuedReceiptNumber", str(response.IssuedReceiptNumber));
+    return result;
+  }
+  /**
+   * Transfer funds from your Payment Account to another Yo! Payments Account.
+   * @param currencyCode e.g. "UGX-MTNMM", "UGX-MTNAT", "UGX-WTLAT", "UGX-OULAT", "UGX-AIRAT"
+   * @param amount the amount to be transferred
+   * @param beneficiaryAccount account number of the beneficiary Yo! Payments user
+   * @param beneficiaryEmail email address of the recipient of funds
+   * @param narrative textual narrative about the transaction
+   */
+  async acInternalTransfer(currencyCode, amount, beneficiaryAccount, beneficiaryEmail, narrative) {
+    const xml = this.requestXml(
+      this.authXml() + el("Method", "acinternaltransfer") + el("CurrencyCode", currencyCode) + el("Amount", amount) + el("BeneficiaryAccount", beneficiaryAccount) + el("BeneficiaryEmail", beneficiaryEmail) + el("Narrative", narrative) + opt("InternalReference", this.internalReference) + opt("ExternalReference", this.externalReference)
+    );
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode),
+      StatusMessage: str(response.StatusMessage),
+      TransactionStatus: str(response.TransactionStatus)
+    };
+    setIfNonEmpty(result, "ErrorMessageCode", str(response.ErrorMessageCode));
+    setIfNonEmpty(result, "ErrorMessage", str(response.ErrorMessage));
+    setIfNonEmpty(result, "TransactionReference", str(response.TransactionReference));
+    setIfNonEmpty(result, "MNOTransactionReferenceId", str(response.MNOTransactionReferenceId));
+    setIfNonEmpty(result, "IssuedReceiptNumber", str(response.IssuedReceiptNumber));
+    return result;
+  }
+  /**
+   * Get the current balance of your Yo! Payments Account.
+   * The returned object contains an array of balances (including airtime).
+   */
+  async acAcctBalance() {
+    const xml = this.requestXml(this.authXml() + el("Method", "acacctbalance"));
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode),
+      balance: []
+    };
+    const currencies = asArray(asRecord(asRecord(response.Balance).Currency));
+    for (const currency of currencies) {
+      const node = asRecord(currency);
+      result.balance.push({ code: str(node.Code), balance: str(node.Balance) });
+    }
+    setIfNonEmpty(result, "StatusMessage", str(response.StatusMessage));
+    setIfNonEmpty(result, "ErrorMessageCode", str(response.ErrorMessageCode));
+    setIfNonEmpty(result, "ErrorMessage", str(response.ErrorMessage));
+    return result;
+  }
+  /**
+   * Return transactions carried out on your account for a certain period of time.
+   * @param startDate format YYYY-MM-DD HH:MM:SS
+   * @param endDate format YYYY-MM-DD HH:MM:SS
+   * @param transactionStatus e.g. "FAILED", "PENDING", "INDETERMINATE", "SUCCEEDED", "FAILED,SUCCEEDED"
+   * @param currencyCode e.g. "UGX-MTNMM", "UGX-WARIDMM", "UGX-MTNAT", "UGX-WTLAT", "UGX-OULAT", "UGX-AIRAT"
+   * @param resultSetLimit a value of 0 returns all; default gateway limit = 15
+   * @param transactionEntryDesignation "TRANSACTION", "CHARGES" or "ANY"
+   * @param externalReference filter using this external reference
+   */
+  async acGetMinistatement(startDate = null, endDate = null, transactionStatus = null, currencyCode = null, resultSetLimit = null, transactionEntryDesignation = "ANY", externalReference = null) {
+    const xml = this.requestXml(
+      this.authXml() + el("Method", "acgetministatement") + opt("StartDate", startDate) + opt("EndDate", endDate) + opt("TransactionStatus", transactionStatus) + opt("CurrencyCode", currencyCode) + opt("ResultSetLimit", resultSetLimit) + el("TransactionEntryDesignation", transactionEntryDesignation) + opt("ExternalReference", externalReference)
+    );
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode),
+      TotalTransactions: str(response.TotalTransactions),
+      ReturnedTransactions: str(response.ReturnedTransactions),
+      Transactions: []
+    };
+    const transactions = asArray(asRecord(response.Transactions).Transaction);
+    for (const transaction of transactions) {
+      const node = asRecord(transaction);
+      const detail = {
+        TransactionSystemId: str(node.TransactionSystemId),
+        TransactionReference: str(node.TransactionReference),
+        TransactionStatus: str(node.TransactionStatus),
+        InitiationDate: str(node.InitiationDate),
+        CompletionDate: str(node.CompletionDate),
+        NarrativeBase64: str(asArray(node.NarrativeBase64)[0]),
+        Currency: str(node.Currency),
+        Amount: str(node.Amount),
+        Balance: str(node.Balance),
+        GeneralType: str(node.GeneralType),
+        DetailedType: str(node.DetailedType),
+        BeneficiaryBase64: str(node.BeneficiaryBase64),
+        SenderBase64: str(node.SenderBase64),
+        TransactionEntryDesignation: str(node.TransactionEntryDesignation)
+      };
+      setIfNonEmpty(detail, "BeneficiaryMsisdn", str(node.BeneficiaryMsisdn));
+      setIfNonEmpty(detail, "SenderMsisdn", str(node.SenderMsisdn));
+      setIfNonEmpty(detail, "Base64TransactionExternalReference", str(node.Base64TransactionExternalReference));
+      result.Transactions.push(detail);
+    }
+    setIfNonEmpty(result, "ErrorMessageCode", str(response.ErrorMessageCode));
+    setIfNonEmpty(result, "ErrorMessage", str(response.ErrorMessage));
+    return result;
+  }
+  /**
+   * Send airtime to a mobile phone user.
+   * @param msisdn the mobile phone number in the format 256772123456
+   * @param amount the amount of airtime to be sent to the mobile user
+   * @param narrative textual narrative about the transfer
+   */
+  async acSendAirtimeMobile(msisdn, amount, narrative) {
+    const xml = this.requestXml(
+      this.authXml() + el("Method", "acsendairtimemobile") + el("NonBlocking", this.nonBlocking) + el("Account", msisdn) + el("Amount", amount) + el("Narrative", narrative) + opt("ExternalReference", this.externalReference) + opt("InternalReference", this.internalReference) + opt("ProviderReferenceText", this.providerReferenceText)
+    );
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode),
+      StatusMessage: str(response.StatusMessage),
+      TransactionStatus: str(response.TransactionStatus)
+    };
+    setIfNotNull(result, "ErrorMessageCode", response.ErrorMessageCode);
+    setIfNotNull(result, "ErrorMessage", response.ErrorMessage);
+    setIfNotNull(result, "TransactionReference", response.TransactionReference);
+    setIfNotNull(result, "MNOTransactionReferenceId", response.MNOTransactionReferenceId);
+    setIfNotNull(result, "IssuedReceiptNumber", response.IssuedReceiptNumber);
+    return result;
+  }
+  /**
+   * Send airtime from your Yo! Payments account to another Yo! Payments user account.
+   * @param currencyCode e.g. "UGX-MTNAT", "UGX-WTLAT", "UGX-OULAT", "UGX-AIRAT"
+   * @param amount the amount of airtime to be sent to the beneficiary Yo! Payments user
+   * @param beneficiaryAccount the beneficiary Yo! Payments account number
+   * @param beneficiaryEmail the beneficiary email address
+   * @param narrative textual narrative about the transfer
+   */
+  async acSendAirtimeInternal(currencyCode, amount, beneficiaryAccount, beneficiaryEmail, narrative) {
+    const xml = this.requestXml(
+      this.authXml() + el("Method", "acsendairtimeinternal") + el("CurrencyCode", currencyCode) + el("Amount", amount) + el("BeneficiaryAccount", beneficiaryAccount) + el("BeneficiaryEmail", beneficiaryEmail) + el("Narrative", narrative) + opt("InternalReference", this.internalReference) + opt("ExternalReference", this.externalReference)
+    );
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode),
+      StatusMessage: str(response.StatusMessage),
+      TransactionStatus: str(response.TransactionStatus)
+    };
+    setIfNotNull(result, "ErrorMessageCode", response.ErrorMessageCode);
+    setIfNotNull(result, "ErrorMessage", response.ErrorMessage);
+    setIfNotNull(result, "TransactionReference", response.TransactionReference);
+    setIfNotNull(result, "MNOTransactionReferenceId", response.MNOTransactionReferenceId);
+    setIfNotNull(result, "IssuedReceiptNumber", response.IssuedReceiptNumber);
+    return result;
+  }
+  /**
+   * Withdraw funds from your Yo! Payments Account to a mobile money user.
+   * Handle with care: if compromised, it can lead to withdrawal of funds from your account.
+   * Requires permission granted by the issuance of an API Access Letter.
+   * @param msisdn the mobile money phone number in the format 256772123456
+   * @param amount the amount to withdraw from your account (fractions supported)
+   * @param narrative the reason for withdrawal of funds from your account
+   */
+  async acWithdrawFunds(msisdn, amount, narrative) {
+    const xml = this.requestXml(
+      this.authXml() + el("Method", "acwithdrawfunds") + el("NonBlocking", this.nonBlocking) + el("Account", msisdn) + el("Amount", amount) + el("Narrative", narrative) + opt("ExternalReference", this.externalReference) + opt("InternalReference", this.internalReference) + opt("ProviderReferenceText", this.providerReferenceText) + opt("TransactionLimitAccountIdentifier", this.transactionLimitAccountIdentifier) + opt("PublicKeyAuthenticationNonce", this.publicKeyAuthenticationNonce) + opt("PublicKeyAuthenticationSignatureBase64", this.publicKeyAuthenticationSignatureBase64)
+    );
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode),
+      StatusMessage: str(response.StatusMessage),
+      TransactionStatus: str(response.TransactionStatus)
+    };
+    setIfNonEmpty(result, "ErrorMessageCode", str(response.ErrorMessageCode));
+    setIfNonEmpty(result, "ErrorMessage", str(response.ErrorMessage));
+    setIfNonEmpty(result, "TransactionReference", str(response.TransactionReference));
+    setIfNonEmpty(result, "MNOTransactionReferenceId", str(response.MNOTransactionReferenceId));
+    setIfNonEmpty(result, "IssuedReceiptNumber", str(response.IssuedReceiptNumber));
+    return result;
+  }
+  /**
+   * Purchase airtime using your Mobile Money Credit.
+   * @param airtimeCurrencyCode e.g. "UGX-MTNAT", "UGX-AIRAT", "UGX-OULAT", "UGX-UTLAT", "UGX-SMTAT"
+   * @param amount the amount to spend (fractions supported)
+   */
+  async acUserPurchaseAirtimestock(airtimeCurrencyCode, amount) {
+    const xml = this.requestXml(
+      this.authXml() + el("Method", "acuserpurchaseairtimestock") + el("AirtimeCurrencyCode", airtimeCurrencyCode) + el("Amount", amount) + // The PHP library sends externalReference inside a TransactionReference tag; kept for parity.
+      opt("TransactionReference", this.externalReference)
+    );
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode)
+    };
+    setIfNonEmpty(result, "StatusMessage", str(response.StatusMessage));
+    setIfNonEmpty(result, "TransactionReference", str(response.TransactionReference));
+    setIfNonEmpty(result, "TotalCurrencyDebited", str(response.TotalCurrencyDebited));
+    setIfNonEmpty(result, "CommissionAmount", str(response.CommissionAmount));
+    setIfNonEmpty(result, "ErrorMessageCode", str(response.ErrorMessageCode));
+    setIfNonEmpty(result, "ErrorMessage", str(response.ErrorMessage));
+    return result;
+  }
+  /**
+   * Obtain the name of a phone number before paying out funds.
+   * Only available for MTN Uganda and Airtel Uganda networks; requires permission
+   * from support@yo.co.ug.
+   * @param msisdn the phone number in the format 2567XXXXXXXXXX
+   */
+  async acGetMsisdnKycInfo(msisdn) {
+    const xml = this.requestXml(this.authXml() + el("Method", "acgetmsisdnkycinfo") + el("Msisdn", msisdn));
+    const response = asRecord((await this.parseResponse(xml)).Response);
+    const result = {
+      Status: str(response.Status),
+      StatusCode: str(response.StatusCode)
+    };
+    setIfNonEmpty(result, "StatusMessage", str(response.StatusMessage));
+    const names = asRecord(asRecord(asRecord(response.AccountInformation).PersonalInformation).Names);
+    setIfNonEmpty(result, "FirstName", str(names.FirstName));
+    setIfNonEmpty(result, "MiddleName", str(names.MiddleName));
+    setIfNonEmpty(result, "Surname", str(names.Surname));
+    return result;
+  }
+  /**
+   * Decode and verify a successful payment notification (IPN) POSTed to your
+   * Instant Notification URL. Pass the parsed form body of the request.
+   */
+  receivePaymentNotification(body) {
+    return {
+      is_verified: this.verifyPaymentNotification(body),
+      date_time: body.date_time ?? "",
+      amount: body.amount ?? "",
+      narrative: body.narrative ?? "",
+      network_ref: body.network_ref ?? "",
+      external_ref: body.external_ref ?? "",
+      msisdn: body.msisdn ?? ""
+    };
+  }
+  /**
+   * Decode and verify a failed payment notification POSTed to your
+   * Failure Notification URL. Pass the parsed form body of the request.
+   */
+  receivePaymentFailureNotification(body) {
+    return {
+      is_verified: this.verifyPaymentFailureNotification(body),
+      failed_transaction_reference: body.failed_transaction_reference ?? "",
+      transaction_init_date: body.transaction_init_date ?? ""
+    };
+  }
+  /**
+   * Calculate the Public Key Authentication Signature required by some payout requests.
+   * Sets publicKeyAuthenticationSignatureBase64 on success.
+   * @param msisdn the account the funds will be pushed to
+   * @param amount the transaction amount
+   * @param narrative the transaction narrative
+   */
+  generatePublicKeyAuthenticationSignature(msisdn, amount, narrative) {
+    if (!this.publicKeyAuthenticationNonce) {
+      throw new Error("Public key authentication nonce is not set. Please set it to continue");
+    }
+    if (!this.privateKeyFileLocation && this.privateKeyContent === null) {
+      throw new Error("Private key file location cannot be NULL");
+    }
+    let privateKeyPem = this.privateKeyContent;
+    if (privateKeyPem === null) {
+      try {
+        privateKeyPem = readFileSync2(this.privateKeyFileLocation, "utf-8");
+      } catch {
+        throw new Error(
+          `Private key file could not be opened. Confirm your file location ${this.privateKeyFileLocation}`
+        );
+      }
+    }
+    let privateKey;
+    try {
+      privateKey = createPrivateKey(privateKeyPem);
+    } catch {
+      throw new Error("Private key is invalid");
+    }
+    const data = this.username + String(amount) + msisdn + narrative + (this.externalReference ?? "") + this.publicKeyAuthenticationNonce;
+    const sha1Hex = createHash("sha1").update(data).digest("hex");
+    const signature = rsaSign("sha1", Buffer.from(sha1Hex, "utf-8"), privateKey);
+    this.publicKeyAuthenticationSignatureBase64 = signature.toString("base64");
+  }
+  /** POST raw XML to the gateway and return the XML response body. */
+  async getXmlResponse(xml) {
+    return postXml(this.yoUrl, xml, {
+      timeoutMs: this.timeoutMs,
+      verifyTls: this.verifyTls,
+      maxResponseBytes: this.maxResponseBytes
+    });
+  }
+  /** Verify the RSA-SHA256 signature on a payment notification against the Yo public certificate. */
+  verifyPaymentNotification(body) {
+    const data = (body.date_time ?? "") + (body.amount ?? "") + (body.narrative ?? "") + (body.network_ref ?? "") + (body.external_ref ?? "") + (body.msisdn ?? "");
+    return this.verifySignature(data, body.signature);
+  }
+  /** Verify the RSA-SHA256 signature on a payment failure notification against the Yo public certificate. */
+  verifyPaymentFailureNotification(body) {
+    const data = (body.failed_transaction_reference ?? "") + (body.transaction_init_date ?? "");
+    return this.verifySignature(data, body.verification);
+  }
+  verifySignature(data, signatureBase64) {
+    if (!signatureBase64) return false;
+    const publicKey = loadPublicKeyCached(
+      this.publicKeyFile,
+      this.publicKeyFileIsDefault ? defaultVerificationCertificate(this.mode) : void 0
+    );
+    if (publicKey === null) return false;
+    try {
+      return rsaVerify("sha256", Buffer.from(data, "utf-8"), publicKey, Buffer.from(signatureBase64, "base64"));
+    } catch {
+      return false;
+    }
+  }
+  authXml() {
+    return el("APIUsername", this.username) + el("APIPassword", this.password);
+  }
+  requestXml(body) {
+    return `${XML_HEADER}<AutoCreate><Request>${body}</Request></AutoCreate>`;
+  }
+  /** POST the request XML to the gateway and return the parsed envelope that holds the <Response> node. */
+  async parseResponse(requestXml) {
+    return parseGatewayResponse(await this.getXmlResponse(requestXml));
+  }
+};
+export {
+  YoAPI,
+  YoAPIError,
+  YoAPI as default
+};
+//# sourceMappingURL=index.js.map