pesafy 0.4.0 → 0.4.2

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,101 @@ 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/c2b/register-url.ts
 var FORBIDDEN_URL_KEYWORDS = [
   "mpesa",
@@ -732,7 +827,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.
    *
@@ -827,7 +922,7 @@ var Mpesa = class {
       request
     );
   }
-  // ── Dynamic QR Code ───────────────────────────────────────────────────────
+  // ── Dynamic QR Code ────────────────────────────────────────────────────────
   /**
    * Dynamic QR — generates an M-PESA QR code for LNM merchant payments.
    *
@@ -839,19 +934,17 @@ var Mpesa = class {
    *   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.
    *
@@ -862,61 +955,45 @@ var Mpesa = class {
    * 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)
+   * Requires: initiatorName + certificate (or pre-computed securityCredential).
    *
    * This is ASYNCHRONOUS. The synchronous response only confirms receipt.
    * Final details are POSTed to your resultUrl.
@@ -926,17 +1003,17 @@ var Mpesa = class {
    *   - 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):
+   * Fixed values (set automatically — do NOT override):
    *   CommandID:              "PayTaxToKRA"
    *   SenderIdentifierType:   "4"
    *   RecieverIdentifierType: "4"
-   *   PartyB:                 "572572"  (KRA shortcode)
+   *   PartyB:                 "572572" (KRA shortcode)
    *
    * @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 +1033,55 @@ 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.
+   *
+   * Enables vendors to request payment from a fellow merchant by triggering
+   * a USSD Push to the merchant's till number. The merchant is prompted to
+   * enter their Operator ID and M-PESA PIN to authorise the payment.
+   *
+   * Requires: standard OAuth credentials only (consumerKey + consumerSecret).
+   * NO initiatorName or SecurityCredential needed.
+   *
+   * Flow:
+   *   1. You call b2bExpressCheckout() → Daraja sends USSD to merchant's till.
+   *   2. Merchant enters Operator ID + PIN to confirm.
+   *   3. M-PESA debits merchant (primaryShortCode), credits you (receiverShortCode).
+   *   4. Daraja POSTs result to your callbackUrl.
+   *
+   * Synchronous response: confirms USSD was triggered (code "0").
+   * Async callback: final success or cancellation result POSTed to callbackUrl.
+   *
+   * Prerequisites (from Daraja docs):
+   *   - Merchant's till (primaryShortCode) must have a Nominated Number
+   *     configured in M-PESA Web Portal (Organization Details).
+   *   - Merchant KYC must be valid.
+   *
+   * Error codes:
+   *   4104 — Missing Nominated Number → configure in M-PESA Web Portal
+   *   4102 — Merchant KYC Fail        → provide valid KYC
+   *   4201 — USSD Network Error       → retry on stable network
+   *   4203 — USSD Exception Error     → retry on stable network
+   *
+   * @example
+   * const res = await mpesa.b2bExpressCheckout({
+   *   primaryShortCode:  "000001",   // merchant's till (debit party)
+   *   receiverShortCode: "000002",   // your Paybill (credit party)
+   *   amount:            5000,
+   *   paymentRef:        "INV-001",
+   *   callbackUrl:       "https://yourdomain.com/mpesa/b2b/callback",
+   *   partnerName:       "My Vendor Co.",
+   * });
+   *
+   * if (res.code === "0") {
+   *   console.log("USSD Push triggered:", res.status);
+   * }
+   */
+  async b2bExpressCheckout(request) {
+    const token = await this.getToken();
+    return initiateB2BExpressCheckout(this.baseUrl, token, request);
+  }
   /** Force the cached OAuth token to be refreshed on the next API call */
   clearTokenCache() {
     this.tokenManager.clearCache();
@@ -1094,6 +1220,10 @@ 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.getC2BAccountRef = getC2BAccountRef;
 exports.getC2BAmount = getC2BAmount;
 exports.getC2BCustomerName = getC2BCustomerName;
@@ -1101,6 +1231,10 @@ exports.getC2BTransactionId = getC2BTransactionId;
 exports.getCallbackValue = getCallbackValue;
 exports.getTimestamp = getTimestamp;
 exports.handleWebhook = handleWebhook;
+exports.initiateB2BExpressCheckout = initiateB2BExpressCheckout;
+exports.isB2BCheckoutCallback = isB2BCheckoutCallback;
+exports.isB2BCheckoutCancelled = isB2BCheckoutCancelled;
+exports.isB2BCheckoutSuccess = isB2BCheckoutSuccess;
 exports.isBuyGoodsPayment = isBuyGoodsPayment;
 exports.isC2BPayload = isC2BPayload;
 exports.isPaybillPayment = isPaybillPayment;