pesafy 0.4.1 → 0.4.3

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var crypto = require('crypto');
+var crypto$1 = require('crypto');
 
 // Pesafy - Payment Gateway Library
 // https://github.com/levos-snr/pesafy
@@ -45,11 +45,11 @@ function createError(options) {
 function encryptSecurityCredential(initiatorPassword, certificatePem) {
   try {
     const passwordBuffer = Buffer.from(initiatorPassword, "utf-8");
-    const encrypted = crypto.publicEncrypt(
+    const encrypted = crypto$1.publicEncrypt(
       {
         key: certificatePem,
         // RSA_PKCS1_PADDING = 1  (NOT RSA_PKCS1_OAEP_PADDING = 4)
-        padding: crypto.constants.RSA_PKCS1_PADDING
+        padding: crypto$1.constants.RSA_PKCS1_PADDING
       },
       passwordBuffer
     );
@@ -217,6 +217,255 @@ var TokenManager = class {
   }
 };
 
+// src/mpesa/b2b-express-checkout/initiate.ts
+function generateRequestRefId() {
+  try {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+  } catch {
+  }
+  return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}-${Math.random().toString(16).slice(2)}`;
+}
+async function initiateB2BExpressCheckout(baseUrl, accessToken, request) {
+  if (!request.primaryShortCode?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "primaryShortCode is required \u2014 the merchant's till number (debit party)."
+    });
+  }
+  if (!request.receiverShortCode?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "receiverShortCode is required \u2014 the vendor's Paybill account (credit party)."
+    });
+  }
+  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.paymentRef?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "paymentRef is required \u2014 shown in the merchant's USSD prompt as the payment reference."
+    });
+  }
+  if (!request.callbackUrl?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "callbackUrl is required \u2014 Safaricom POSTs the transaction result here."
+    });
+  }
+  if (!request.partnerName?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "partnerName is required \u2014 your friendly name shown in the merchant's USSD prompt."
+    });
+  }
+  const payload = {
+    primaryShortCode: String(request.primaryShortCode),
+    receiverShortCode: String(request.receiverShortCode),
+    amount: String(amount),
+    paymentRef: request.paymentRef,
+    callbackUrl: request.callbackUrl,
+    partnerName: request.partnerName,
+    RequestRefID: request.requestRefId ?? generateRequestRefId()
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/v1/ussdpush/get-msisdn`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body: payload
+    }
+  );
+  return data;
+}
+
+// src/mpesa/b2b-express-checkout/webhooks.ts
+function isB2BCheckoutSuccess(callback) {
+  return callback.resultCode === "0";
+}
+function isB2BCheckoutCancelled(callback) {
+  return callback.resultCode === "4001";
+}
+function isB2BCheckoutCallback(body) {
+  if (!body || typeof body !== "object") return false;
+  const b = body;
+  return typeof b["resultCode"] === "string" && typeof b["requestId"] === "string" && typeof b["amount"] === "string";
+}
+function getB2BTransactionId(callback) {
+  if (!isB2BCheckoutSuccess(callback)) return null;
+  return callback.transactionId ?? null;
+}
+function getB2BAmount(callback) {
+  return Number(callback.amount);
+}
+function getB2BRequestId(callback) {
+  return callback.requestId;
+}
+function getB2BConversationId(callback) {
+  if (!isB2BCheckoutSuccess(callback)) return null;
+  return callback.conversationID ?? null;
+}
+
+// src/mpesa/b2c/payment.ts
+async function initiateB2CPayment(baseUrl, accessToken, securityCredential, initiatorName, request) {
+  if (!request.commandId) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: 'commandId is required: "BusinessPayToBulk" | "BusinessPayment" | "SalaryPayment" | "PromotionPayment"'
+    });
+  }
+  const validCommandIds = [
+    "BusinessPayToBulk",
+    "BusinessPayment",
+    "SalaryPayment",
+    "PromotionPayment"
+  ];
+  if (!validCommandIds.includes(request.commandId)) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: `commandId must be one of: ${validCommandIds.join(", ")}. Got: "${request.commandId}"`
+    });
+  }
+  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?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "partyA is required \u2014 your business shortcode from which money is deducted."
+    });
+  }
+  if (!request.partyB?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "partyB is required \u2014 the recipient shortcode (BusinessPayToBulk) or customer MSISDN (other commands)."
+    });
+  }
+  if (!request.accountReference?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "accountReference is required \u2014 a reference for this transaction."
+    });
+  }
+  if (!request.resultUrl?.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "resultUrl is required \u2014 Safaricom POSTs the B2C 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: request.commandId,
+    SenderIdentifierType: request.senderIdentifierType ?? "4",
+    RecieverIdentifierType: request.receiverIdentifierType ?? "4",
+    Amount: String(amount),
+    PartyA: String(request.partyA),
+    PartyB: String(request.partyB),
+    AccountReference: request.accountReference,
+    Remarks: request.remarks ?? "B2C Payment",
+    QueueTimeOutURL: request.queueTimeOutUrl,
+    ResultURL: request.resultUrl
+  };
+  if (request.requester?.trim()) {
+    payload["Requester"] = String(request.requester);
+  }
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/b2b/v1/paymentrequest`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body: payload
+    }
+  );
+  return data;
+}
+
+// src/mpesa/b2c/webhooks.ts
+function isB2CResult(body) {
+  if (!body || typeof body !== "object") return false;
+  const b = body;
+  if (!b["Result"] || typeof b["Result"] !== "object") return false;
+  const result = b["Result"];
+  return typeof result["ResultCode"] === "number" && typeof result["ConversationID"] === "string";
+}
+function isB2CSuccess(result) {
+  return result.Result.ResultCode === 0;
+}
+function isB2CFailure(result) {
+  return result.Result.ResultCode !== 0;
+}
+function getB2CTransactionId(result) {
+  return result.Result.TransactionID ?? null;
+}
+function getB2CConversationId(result) {
+  return result.Result.ConversationID;
+}
+function getB2COriginatorConversationId(result) {
+  return result.Result.OriginatorConversationID;
+}
+function getB2CResultDesc(result) {
+  return result.Result.ResultDesc;
+}
+function getB2CAmount(result) {
+  const value = getB2CResultParam(result, "Amount");
+  if (value === void 0) return null;
+  return Number(value);
+}
+function getB2CTransactionCompletedTime(result) {
+  const value = getB2CResultParam(result, "TransCompletedTime");
+  if (value === void 0) return null;
+  return String(value);
+}
+function getB2CDebitPartyCharges(result) {
+  const value = getB2CResultParam(result, "DebitPartyCharges");
+  if (value === void 0 || value === "") return null;
+  return String(value);
+}
+function getB2CReceiverPublicName(result) {
+  const value = getB2CResultParam(result, "ReceiverPartyPublicName");
+  if (value === void 0) return null;
+  return String(value);
+}
+function getB2CCurrency(result) {
+  const value = getB2CResultParam(result, "Currency");
+  if (value === void 0) return "KES";
+  return String(value);
+}
+function getB2CDebitAccountBalance(result) {
+  const value = getB2CResultParam(result, "DebitAccountBalance");
+  if (value === void 0) return null;
+  return String(value);
+}
+function getB2CInitiatorAccountBalance(result) {
+  const value = getB2CResultParam(result, "InitiatorAccountCurrentBalance");
+  if (value === void 0) return null;
+  return String(value);
+}
+function getB2CResultParam(result, key) {
+  const params = result.Result.ResultParameters?.ResultParameter;
+  if (!params) return void 0;
+  const paramArray = Array.isArray(params) ? params : [params];
+  const item = paramArray.find((p) => p.Key === key);
+  return item?.Value;
+}
+
 // src/mpesa/c2b/register-url.ts
 var FORBIDDEN_URL_KEYWORDS = [
   "mpesa",
@@ -732,7 +981,7 @@ var Mpesa = class {
     }
     return encryptSecurityCredential(this.config.initiatorPassword, cert);
   }
-  // ── STK Push ──────────────────────────────────────────────────────────────
+  // ── STK Push ───────────────────────────────────────────────────────────────
   /**
    * M-Pesa Express — sends a payment prompt to the customer's phone.
    *
@@ -789,6 +1038,7 @@ var Mpesa = class {
       passKey
     });
   }
+  // ── Transaction Status ─────────────────────────────────────────────────────
   /**
    * Transaction Status — queries the result of a completed M-Pesa transaction.
    *
@@ -827,116 +1077,71 @@ var Mpesa = class {
       request
     );
   }
-  // ── Dynamic QR Code ───────────────────────────────────────────────────────
+  // ── Dynamic QR Code ────────────────────────────────────────────────────────
   /**
    * Dynamic QR — generates an M-PESA QR code for LNM merchant payments.
    *
-   * Customers scan the code with My Safaricom App or M-PESA app to
-   * capture the till/paybill number and amount, then authorize payment.
-   *
    * @example
    * const res = await mpesa.generateDynamicQR({
    *   merchantName: "My Shop",
    *   refNo:        "INV-001",
    *   amount:       500,
-   *   trxCode:      "BG",   // Buy Goods (till number)
+   *   trxCode:      "BG",
    *   cpi:          "373132",
    *   size:         300,
    * });
-   *
-   * // res.QRCode is a base64-encoded PNG — render in an <img> tag:
    * // <img src={`data:image/png;base64,${res.QRCode}`} />
    */
   async generateDynamicQR(request) {
     const token = await this.getToken();
     return generateDynamicQR(this.baseUrl, token, request);
   }
-  // ── C2B Register URL ──────────────────────────────────────────────────────
+  // ── C2B Register URL ───────────────────────────────────────────────────────
   /**
    * Registers your Confirmation and Validation URLs with M-PESA.
    *
-   * Use v2 (default) for new integrations — callbacks include a masked MSISDN.
-   * Use v1 only if you need SHA256-hashed MSISDN in callbacks.
-   *
-   * Sandbox: URLs can be re-registered freely (overwriting existing ones).
-   * Production: One-time call. To change URLs, delete them via Daraja Self
-   *   Services → URL Management, then call this again.
-   *
-   * URL rules (Daraja docs — enforced by this library):
-   *   ✓ Must be publicly accessible
-   *   ✓ Production: HTTPS required
-   *   ✗ Must NOT contain: M-PESA, Safaricom, exe, exec, cmd, sql, query
-   *   ✗ Do NOT use ngrok, mockbin, requestbin in production
-   *   ✓ responseType must be exactly "Completed" or "Cancelled" (sentence case)
-   *
-   * External Validation (optional):
-   *   By default it is disabled. To enable, email apisupport@safaricom.co.ke.
-   *   When enabled, Safaricom calls your validationUrl before processing payment.
-   *   You must respond within ~8 seconds.
-   *
    * @example
    * await mpesa.registerC2BUrls({
    *   shortCode:       "600984",
    *   responseType:    "Completed",
    *   confirmationUrl: "https://yourdomain.com/mpesa/c2b/confirmation",
    *   validationUrl:   "https://yourdomain.com/mpesa/c2b/validation",
-   *   apiVersion:      "v2",  // default — recommended
+   *   apiVersion:      "v2",
    * });
    */
   async registerC2BUrls(request) {
     const token = await this.getToken();
     return registerC2BUrls(this.baseUrl, token, request);
   }
-  // ── C2B Simulate (Sandbox ONLY) ───────────────────────────────────────────
+  // ── C2B Simulate (Sandbox ONLY) ────────────────────────────────────────────
   /**
    * Simulates a C2B customer payment. SANDBOX ONLY.
    *
-   * In production, real customers initiate payments via M-PESA App, USSD,
-   * or SIM Toolkit — simulation is not available.
-   *
-   * The API version used here should match the version used when registering URLs.
-   *
    * @example
    * await mpesa.simulateC2B({
    *   shortCode:     600984,
    *   commandId:     "CustomerPayBillOnline",
    *   amount:        10,
-   *   msisdn:        254708374149,  // Daraja test MSISDN
-   *   billRefNumber: "INV-001",     // account ref for Paybill; null for Till
-   *   apiVersion:    "v2",          // must match registered URL version
+   *   msisdn:        254708374149,
+   *   billRefNumber: "INV-001",
+   *   apiVersion:    "v2",
    * });
    */
   async simulateC2B(request) {
     const token = await this.getToken();
     return simulateC2B(this.baseUrl, token, request);
   }
-  // ── Tax Remittance ────────────────────────────────────────────────────────
+  // ── 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)
+   * Requires: initiatorName + certificate (or pre-computed securityCredential).
    *
    * @example
    * await mpesa.remitTax({
    *   amount:           5000,
    *   partyA:           "888880",
-   *   accountReference: "PRN1234XN",   // PRN from KRA
+   *   accountReference: "PRN1234XN",
    *   resultUrl:        "https://yourdomain.com/mpesa/tax/result",
    *   queueTimeOutUrl:  "https://yourdomain.com/mpesa/tax/timeout",
    *   remarks:          "Monthly PAYE remittance",
@@ -956,6 +1161,94 @@ var Mpesa = class {
     ]);
     return remitTax(this.baseUrl, token, securityCred, initiator, request);
   }
+  // ── B2B Express Checkout ───────────────────────────────────────────────────
+  /**
+   * B2B Express Checkout — initiates a USSD Push to a merchant's till.
+   *
+   * @example
+   * const res = await mpesa.b2bExpressCheckout({
+   *   primaryShortCode:  "000001",
+   *   receiverShortCode: "000002",
+   *   amount:            5000,
+   *   paymentRef:        "INV-001",
+   *   callbackUrl:       "https://yourdomain.com/mpesa/b2b/callback",
+   *   partnerName:       "My Vendor Co.",
+   * });
+   */
+  async b2bExpressCheckout(request) {
+    const token = await this.getToken();
+    return initiateB2BExpressCheckout(this.baseUrl, token, request);
+  }
+  // ── B2C Payment ────────────────────────────────────────────────────────────
+  /**
+   * B2C Payment — sends money from a business to customers, or loads funds
+   * to a B2C shortcode for bulk disbursement.
+   *
+   * Requires: initiatorName + (initiatorPassword + certificate) OR securityCredential.
+   * The initiator must have the appropriate role for the chosen CommandID.
+   *
+   * This is ASYNCHRONOUS. The synchronous response only confirms receipt.
+   * Final details are POSTed to your resultUrl.
+   *
+   * CommandID options:
+   *   "BusinessPayToBulk"  — Load funds to a B2C shortcode (Account Top Up)
+   *   "BusinessPayment"    — Direct unsecured payment to a customer
+   *   "SalaryPayment"      — Salary disbursement to a customer
+   *   "PromotionPayment"   — Promotion/bonus payment to a customer
+   *
+   * Required M-PESA org portal roles:
+   *   BusinessPayToBulk  → "Org Business Pay to Bulk API initiator"
+   *   BusinessPayment    → "Org Business Payment API initiator"
+   *   SalaryPayment      → "Org Salary Payment API initiator"
+   *   PromotionPayment   → "Org Promotion Payment API initiator"
+   *
+   * @example
+   * // B2C Account Top Up (load funds to B2C shortcode)
+   * await mpesa.b2cPayment({
+   *   commandId:        "BusinessPayToBulk",
+   *   amount:           10000,
+   *   partyA:           "600979",
+   *   partyB:           "600000",
+   *   accountReference: "BATCH-001",
+   *   resultUrl:        "https://yourdomain.com/mpesa/b2c/result",
+   *   queueTimeOutUrl:  "https://yourdomain.com/mpesa/b2c/timeout",
+   *   remarks:          "Monthly salary batch load",
+   * });
+   *
+   * @example
+   * // Direct customer payment
+   * await mpesa.b2cPayment({
+   *   commandId:        "SalaryPayment",
+   *   amount:           5000,
+   *   partyA:           "600979",
+   *   partyB:           "254712345678",
+   *   accountReference: "SAL-JAN-2024",
+   *   requester:        "254712345678",
+   *   resultUrl:        "https://yourdomain.com/mpesa/b2c/result",
+   *   queueTimeOutUrl:  "https://yourdomain.com/mpesa/b2c/timeout",
+   *   remarks:          "January salary",
+   * });
+   */
+  async b2cPayment(request) {
+    const initiator = this.config.initiatorName ?? "";
+    if (!initiator) {
+      throw new PesafyError({
+        code: "VALIDATION_ERROR",
+        message: "initiatorName is required for B2C Payment"
+      });
+    }
+    const [token, securityCred] = await Promise.all([
+      this.getToken(),
+      this.buildSecurityCredential()
+    ]);
+    return initiateB2CPayment(
+      this.baseUrl,
+      token,
+      securityCred,
+      initiator,
+      request
+    );
+  }
   /** Force the cached OAuth token to be refreshed on the next API call */
   clearTokenCache() {
     this.tokenManager.clearCache();
@@ -1094,6 +1387,22 @@ exports.extractAmount = extractAmount;
 exports.extractPhoneNumber = extractPhoneNumber;
 exports.extractTransactionId = extractTransactionId;
 exports.formatPhoneNumber = formatSafaricomPhone;
+exports.getB2BAmount = getB2BAmount;
+exports.getB2BConversationId = getB2BConversationId;
+exports.getB2BRequestId = getB2BRequestId;
+exports.getB2BTransactionId = getB2BTransactionId;
+exports.getB2CAmount = getB2CAmount;
+exports.getB2CConversationId = getB2CConversationId;
+exports.getB2CCurrency = getB2CCurrency;
+exports.getB2CDebitAccountBalance = getB2CDebitAccountBalance;
+exports.getB2CDebitPartyCharges = getB2CDebitPartyCharges;
+exports.getB2CInitiatorAccountBalance = getB2CInitiatorAccountBalance;
+exports.getB2COriginatorConversationId = getB2COriginatorConversationId;
+exports.getB2CReceiverPublicName = getB2CReceiverPublicName;
+exports.getB2CResultDesc = getB2CResultDesc;
+exports.getB2CResultParam = getB2CResultParam;
+exports.getB2CTransactionCompletedTime = getB2CTransactionCompletedTime;
+exports.getB2CTransactionId = getB2CTransactionId;
 exports.getC2BAccountRef = getC2BAccountRef;
 exports.getC2BAmount = getC2BAmount;
 exports.getC2BCustomerName = getC2BCustomerName;
@@ -1101,6 +1410,14 @@ exports.getC2BTransactionId = getC2BTransactionId;
 exports.getCallbackValue = getCallbackValue;
 exports.getTimestamp = getTimestamp;
 exports.handleWebhook = handleWebhook;
+exports.initiateB2BExpressCheckout = initiateB2BExpressCheckout;
+exports.initiateB2CPayment = initiateB2CPayment;
+exports.isB2BCheckoutCallback = isB2BCheckoutCallback;
+exports.isB2BCheckoutCancelled = isB2BCheckoutCancelled;
+exports.isB2BCheckoutSuccess = isB2BCheckoutSuccess;
+exports.isB2CFailure = isB2CFailure;
+exports.isB2CResult = isB2CResult;
+exports.isB2CSuccess = isB2CSuccess;
 exports.isBuyGoodsPayment = isBuyGoodsPayment;
 exports.isC2BPayload = isC2BPayload;
 exports.isPaybillPayment = isPaybillPayment;