pesafy 0.3.12 → 0.4.0

package/dist/index.cjs

@@ -68,13 +68,14 @@ var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function jitter(baseMs) {
+function withJitter(baseMs) {
   const spread = baseMs * 0.25;
   return baseMs + (Math.random() * spread * 2 - spread);
 }
 async function httpRequest(url, options) {
   const maxRetries = options.retries ?? 4;
   const baseDelay = options.retryDelay ?? 2e3;
+  const timeout = options.timeout ?? 3e4;
   const headers = {
     "Content-Type": "application/json",
     Accept: "application/json",
@@ -88,27 +89,50 @@ async function httpRequest(url, options) {
   let lastError = null;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     if (attempt > 0) {
-      const delay = jitter(baseDelay * Math.pow(2, attempt - 1));
+      const delay = withJitter(baseDelay * Math.pow(2, attempt - 1));
+      console.warn(
+        `[pesafy/http] Retry ${attempt}/${maxRetries} for ${options.method} ${url} in ${Math.round(delay)}ms (last error: ${lastError?.message ?? "unknown"})`
+      );
       await sleep(delay);
     }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
     let response;
     try {
-      response = await fetch(url, init);
+      response = await fetch(url, { ...init, signal: controller.signal });
     } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError") {
+        lastError = new PesafyError({
+          code: "TIMEOUT",
+          message: `Request to ${url} timed out after ${timeout}ms`,
+          cause: err
+        });
+        if (attempt < maxRetries) continue;
+        throw lastError;
+      }
       lastError = new PesafyError({
         code: "NETWORK_ERROR",
-        message: `Network error calling ${url}: ${String(err)}`,
+        message: `Network error calling ${url}: ${err instanceof Error ? err.message : String(err)}`,
         cause: err
       });
       if (attempt < maxRetries) continue;
       throw lastError;
+    } finally {
+      clearTimeout(timeoutId);
     }
+    let rawText = "";
     let data;
     const contentType = response.headers.get("content-type") ?? "";
     try {
-      data = contentType.includes("application/json") ? await response.json() : await response.text();
+      rawText = await response.text();
+      if (rawText) {
+        data = contentType.includes("application/json") ? JSON.parse(rawText) : rawText;
+      } else {
+        data = null;
+      }
     } catch {
-      data = null;
+      data = rawText || null;
     }
     const responseHeaders = {};
     response.headers.forEach((value, key) => {
@@ -122,11 +146,11 @@ async function httpRequest(url, options) {
       };
     }
     const isTransient = RETRYABLE_STATUSES.has(response.status);
-    const daraja = data ?? {};
-    const message = daraja.errorMessage ?? daraja.ResponseDescription ?? `HTTP ${response.status}`;
+    const daraja = typeof data === "object" && data !== null ? data : {};
+    const errorMessage = daraja.errorMessage ?? daraja.ResponseDescription ?? rawText ?? `HTTP ${response.status}`;
     lastError = new PesafyError({
-      code: isTransient ? "REQUEST_FAILED" : "HTTP_ERROR",
-      message,
+      code: isTransient ? "REQUEST_FAILED" : "API_ERROR",
+      message: errorMessage,
       statusCode: response.status,
       response: data,
       requestId: daraja.requestId
@@ -264,19 +288,13 @@ async function simulateC2B(baseUrl, accessToken, request) {
   if (!baseUrl.includes("sandbox")) {
     throw createError({
       code: "VALIDATION_ERROR",
-      message: "C2B simulate is only available in the Sandbox environment. Production M-PESA payments must be initiated by the customer via M-PESA App, USSD, or SIM Toolkit."
+      message: "C2B simulate is only available in the Sandbox environment. In production, customers initiate payments via M-PESA App, USSD, or SIM Toolkit."
     });
   }
   if (!request.shortCode) {
     throw createError({
       code: "VALIDATION_ERROR",
-      message: "shortCode is required"
-    });
-  }
-  if (!request.commandId) {
-    throw createError({
-      code: "VALIDATION_ERROR",
-      message: 'commandId is required: "CustomerPayBillOnline" | "CustomerBuyGoodsOnline"'
+      message: "shortCode is required."
     });
   }
   if (request.commandId !== "CustomerPayBillOnline" && request.commandId !== "CustomerBuyGoodsOnline") {
@@ -289,25 +307,32 @@ async function simulateC2B(baseUrl, accessToken, request) {
   if (!Number.isFinite(amount) || amount < 1) {
     throw createError({
       code: "VALIDATION_ERROR",
-      message: `amount must be a whole number \u2265 1 (got ${request.amount})`
+      message: `amount must be a whole number \u2265 1 (got ${request.amount}).`
     });
   }
   if (!request.msisdn) {
     throw createError({
       code: "VALIDATION_ERROR",
-      message: "msisdn is required. Use the test phone number from the Daraja simulator."
+      message: "msisdn is required. Sandbox test MSISDN: 254708374149."
     });
   }
-  const version = request.apiVersion ?? "v2";
   const isBuyGoods = request.commandId === "CustomerBuyGoodsOnline";
+  const version = request.apiVersion ?? "v2";
   const payload = {
     ShortCode: Number(request.shortCode),
     CommandID: request.commandId,
     Amount: amount,
     Msisdn: Number(request.msisdn)
+    // BillRefNumber is NOT here — added conditionally below for Paybill only
   };
   if (!isBuyGoods) {
-    payload.BillRefNumber = request.billRefNumber ?? "";
+    payload["BillRefNumber"] = request.billRefNumber ?? "";
+  }
+  if (isBuyGoods && Object.prototype.hasOwnProperty.call(payload, "BillRefNumber")) {
+    delete payload["BillRefNumber"];
+    console.warn(
+      "[pesafy/simulateC2B] BillRefNumber leaked into Buy Goods payload \u2014 removed. This is a library bug; please report it."
+    );
   }
   const { data } = await httpRequest(
     `${baseUrl}/mpesa/c2b/${version}/simulate`,
@@ -536,6 +561,66 @@ function getCallbackValue(callback, name) {
   return inner.CallbackMetadata.Item.find((i) => i.Name === name)?.Value;
 }
 
+// src/mpesa/tax-remittance/remit-tax.ts
+var KRA_SHORTCODE = "572572";
+var TAX_COMMAND_ID = "PayTaxToKRA";
+async function remitTax(baseUrl, accessToken, securityCredential, initiatorName, request) {
+  const amount = Math.round(request.amount);
+  if (!Number.isFinite(amount) || amount < 1) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: `amount must be a whole number \u2265 1 (got ${request.amount} which rounds to ${amount}).`
+    });
+  }
+  if (!request.partyA) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "partyA is required \u2014 your M-PESA business shortcode from which tax is deducted."
+    });
+  }
+  if (!request.accountReference?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "accountReference is required \u2014 the Payment Registration Number (PRN) issued by KRA."
+    });
+  }
+  if (!request.resultUrl?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "resultUrl is required \u2014 Safaricom POSTs the tax remittance result here."
+    });
+  }
+  if (!request.queueTimeOutUrl?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "queueTimeOutUrl is required \u2014 Safaricom calls this on request timeout."
+    });
+  }
+  const payload = {
+    Initiator: initiatorName,
+    SecurityCredential: securityCredential,
+    CommandID: TAX_COMMAND_ID,
+    SenderIdentifierType: "4",
+    RecieverIdentifierType: "4",
+    Amount: String(amount),
+    PartyA: String(request.partyA),
+    PartyB: request.partyB ?? KRA_SHORTCODE,
+    AccountReference: request.accountReference,
+    Remarks: request.remarks ?? "Tax Remittance",
+    QueueTimeOutURL: request.queueTimeOutUrl,
+    ResultURL: request.resultUrl
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/b2b/v1/remittax`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body: payload
+    }
+  );
+  return data;
+}
+
 // src/mpesa/transaction-status/query.ts
 async function queryTransactionStatus(baseUrl, token, securityCredential, initiator, request) {
   if (!request.transactionId) {
@@ -825,6 +910,52 @@ var Mpesa = class {
     const token = await this.getToken();
     return simulateC2B(this.baseUrl, token, request);
   }
+  // ── Tax Remittance ────────────────────────────────────────────────────────
+  /**
+   * Tax Remittance — remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+   *
+   * Requires:
+   *   - initiatorName in config
+   *   - initiatorPassword + certificate (or pre-computed securityCredential)
+   *
+   * This is ASYNCHRONOUS. The synchronous response only confirms receipt.
+   * Final details are POSTed to your resultUrl.
+   *
+   * Prerequisites (from Daraja docs):
+   *   - Prior integration with KRA for tax declaration.
+   *   - A Payment Registration Number (PRN) from KRA.
+   *   - Initiator with "Tax Remittance ORG API" role on M-PESA org portal.
+   *
+   * Fixed values (set automatically — do NOT override unless Safaricom changes them):
+   *   CommandID:              "PayTaxToKRA"
+   *   SenderIdentifierType:   "4"
+   *   RecieverIdentifierType: "4"
+   *   PartyB:                 "572572"  (KRA shortcode)
+   *
+   * @example
+   * await mpesa.remitTax({
+   *   amount:           5000,
+   *   partyA:           "888880",
+   *   accountReference: "PRN1234XN",   // PRN from KRA
+   *   resultUrl:        "https://yourdomain.com/mpesa/tax/result",
+   *   queueTimeOutUrl:  "https://yourdomain.com/mpesa/tax/timeout",
+   *   remarks:          "Monthly PAYE remittance",
+   * });
+   */
+  async remitTax(request) {
+    const initiator = this.config.initiatorName ?? "";
+    if (!initiator) {
+      throw new PesafyError({
+        code: "VALIDATION_ERROR",
+        message: "initiatorName is required for Tax Remittance"
+      });
+    }
+    const [token, securityCred] = await Promise.all([
+      this.getToken(),
+      this.buildSecurityCredential()
+    ]);
+    return remitTax(this.baseUrl, token, securityCred, initiator, request);
+  }
   /** Force the cached OAuth token to be refreshed on the next API call */
   clearTokenCache() {
     this.tokenManager.clearCache();
@@ -950,9 +1081,11 @@ function isSuccessfulCallback(webhook) {
 }
 
 exports.DARAJA_BASE_URLS = DARAJA_BASE_URLS;
+exports.KRA_SHORTCODE = KRA_SHORTCODE;
 exports.Mpesa = Mpesa;
 exports.PesafyError = PesafyError;
 exports.SAFARICOM_IPS = SAFARICOM_IPS;
+exports.TAX_COMMAND_ID = TAX_COMMAND_ID;
 exports.acceptC2BValidation = acceptC2BValidation;
 exports.acknowledgeC2BConfirmation = acknowledgeC2BConfirmation;
 exports.createError = createError;
@@ -976,6 +1109,7 @@ exports.isSuccessfulCallback = isSuccessfulCallback;
 exports.parseStkPushWebhook = parseStkPushWebhook;
 exports.registerC2BUrls = registerC2BUrls;
 exports.rejectC2BValidation = rejectC2BValidation;
+exports.remitTax = remitTax;
 exports.retryWithBackoff = retryWithBackoff;
 exports.simulateC2B = simulateC2B;
 exports.verifyWebhookIP = verifyWebhookIP;