pesafy 0.4.2 → 0.4.3

package/dist/index.cjs

@@ -312,6 +312,160 @@ function getB2BConversationId(callback) {
   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",
@@ -884,6 +1038,7 @@ var Mpesa = class {
       passKey
     });
   }
+  // ── Transaction Status ─────────────────────────────────────────────────────
   /**
    * Transaction Status — queries the result of a completed M-Pesa transaction.
    *
@@ -926,9 +1081,6 @@ var Mpesa = class {
   /**
    * 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",
@@ -948,13 +1100,6 @@ var Mpesa = class {
   /**
    * 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.
-   *
    * @example
    * await mpesa.registerC2BUrls({
    *   shortCode:       "600984",
@@ -972,9 +1117,6 @@ var Mpesa = class {
   /**
    * 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.
-   *
    * @example
    * await mpesa.simulateC2B({
    *   shortCode:     600984,
@@ -995,20 +1137,6 @@ var Mpesa = class {
    *
    * Requires: initiatorName + 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):
-   *   CommandID:              "PayTaxToKRA"
-   *   SenderIdentifierType:   "4"
-   *   RecieverIdentifierType: "4"
-   *   PartyB:                 "572572" (KRA shortcode)
-   *
    * @example
    * await mpesa.remitTax({
    *   amount:           5000,
@@ -1037,51 +1165,90 @@ var Mpesa = class {
   /**
    * 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)
+   *   primaryShortCode:  "000001",
+   *   receiverShortCode: "000002",
    *   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);
   }
+  // ── 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();
@@ -1224,6 +1391,18 @@ 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;
@@ -1232,9 +1411,13 @@ 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;