pesafy 0.3.13 → 0.4.0

package/dist/index.cjs

@@ -561,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) {
@@ -850,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();
@@ -975,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;
@@ -1001,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;