pesafy 0.3.10 → 0.3.12

package/dist/index.cjs

@@ -193,6 +193,174 @@ var TokenManager = class {
   }
 };
 
+// src/mpesa/c2b/register-url.ts
+var FORBIDDEN_URL_KEYWORDS = [
+  "mpesa",
+  "safaricom",
+  ".exe",
+  ".exec",
+  "cmd",
+  "sql",
+  "query"
+];
+function validateCallbackUrl(url, fieldName) {
+  if (!url || !url.trim()) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: `${fieldName} is required`
+    });
+  }
+  const lower = url.toLowerCase();
+  for (const keyword of FORBIDDEN_URL_KEYWORDS) {
+    if (lower.includes(keyword)) {
+      throw createError({
+        code: "VALIDATION_ERROR",
+        message: `${fieldName} must not contain the keyword "${keyword}". Daraja rejects URLs containing: M-PESA, Safaricom, exe, exec, cmd, sql, query.`
+      });
+    }
+  }
+}
+async function registerC2BUrls(baseUrl, accessToken, request) {
+  if (!request.shortCode) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "shortCode is required"
+    });
+  }
+  if (!request.responseType) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: 'responseType is required: "Completed" or "Cancelled" (sentence case, exactly as spelled)'
+    });
+  }
+  if (request.responseType !== "Completed" && request.responseType !== "Cancelled") {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: `responseType must be exactly "Completed" or "Cancelled" (sentence case). Got: "${request.responseType}"`
+    });
+  }
+  validateCallbackUrl(request.confirmationUrl, "confirmationUrl");
+  validateCallbackUrl(request.validationUrl, "validationUrl");
+  const version = request.apiVersion ?? "v2";
+  const payload = {
+    ShortCode: String(request.shortCode),
+    ResponseType: request.responseType,
+    ConfirmationURL: request.confirmationUrl,
+    ValidationURL: request.validationUrl
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/c2b/${version}/registerurl`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body: payload
+    }
+  );
+  return data;
+}
+
+// src/mpesa/c2b/simulate.ts
+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."
+    });
+  }
+  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"'
+    });
+  }
+  if (request.commandId !== "CustomerPayBillOnline" && request.commandId !== "CustomerBuyGoodsOnline") {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: `commandId must be "CustomerPayBillOnline" or "CustomerBuyGoodsOnline". 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})`
+    });
+  }
+  if (!request.msisdn) {
+    throw createError({
+      code: "VALIDATION_ERROR",
+      message: "msisdn is required. Use the test phone number from the Daraja simulator."
+    });
+  }
+  const version = request.apiVersion ?? "v2";
+  const isBuyGoods = request.commandId === "CustomerBuyGoodsOnline";
+  const payload = {
+    ShortCode: Number(request.shortCode),
+    CommandID: request.commandId,
+    Amount: amount,
+    Msisdn: Number(request.msisdn)
+  };
+  if (!isBuyGoods) {
+    payload.BillRefNumber = request.billRefNumber ?? "";
+  }
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/c2b/${version}/simulate`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body: payload
+    }
+  );
+  return data;
+}
+
+// src/mpesa/c2b/webhooks.ts
+function isC2BPayload(body) {
+  if (!body || typeof body !== "object") return false;
+  const b = body;
+  return typeof b["TransID"] === "string" && typeof b["BusinessShortCode"] === "string" && typeof b["TransAmount"] === "string";
+}
+function acceptC2BValidation(thirdPartyTransID) {
+  return {
+    ResultCode: "0",
+    ResultDesc: "Accepted",
+    ...thirdPartyTransID ? { ThirdPartyTransID: thirdPartyTransID } : {}
+  };
+}
+function rejectC2BValidation(resultCode = "C2B00016", resultDesc = "Rejected") {
+  return {
+    ResultCode: resultCode,
+    ResultDesc: resultDesc
+  };
+}
+function acknowledgeC2BConfirmation() {
+  return { ResultCode: 0, ResultDesc: "Success" };
+}
+function getC2BAmount(payload) {
+  return Number(payload.TransAmount);
+}
+function getC2BTransactionId(payload) {
+  return payload.TransID;
+}
+function getC2BAccountRef(payload) {
+  return payload.BillRefNumber;
+}
+function getC2BCustomerName(payload) {
+  return [payload.FirstName, payload.MiddleName, payload.LastName].filter(Boolean).join(" ").trim();
+}
+function isPaybillPayment(payload) {
+  return payload.TransactionType === "Pay Bill" || payload.TransactionType === "CustomerPayBillOnline";
+}
+function isBuyGoodsPayment(payload) {
+  return payload.TransactionType === "Buy Goods" || payload.TransactionType === "CustomerBuyGoodsOnline";
+}
+
 // src/mpesa/dynamic-qr/generate.ts
 async function generateDynamicQR(baseUrl, accessToken, request) {
   if (!request.merchantName?.trim()) {
@@ -598,6 +766,65 @@ var Mpesa = class {
     const token = await this.getToken();
     return generateDynamicQR(this.baseUrl, token, request);
   }
+  // ── 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
+   * });
+   */
+  async registerC2BUrls(request) {
+    const token = await this.getToken();
+    return registerC2BUrls(this.baseUrl, token, request);
+  }
+  // ── 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
+   * });
+   */
+  async simulateC2B(request) {
+    const token = await this.getToken();
+    return simulateC2B(this.baseUrl, token, request);
+  }
   /** Force the cached OAuth token to be refreshed on the next API call */
   clearTokenCache() {
     this.tokenManager.clearCache();
@@ -726,19 +953,31 @@ exports.DARAJA_BASE_URLS = DARAJA_BASE_URLS;
 exports.Mpesa = Mpesa;
 exports.PesafyError = PesafyError;
 exports.SAFARICOM_IPS = SAFARICOM_IPS;
+exports.acceptC2BValidation = acceptC2BValidation;
+exports.acknowledgeC2BConfirmation = acknowledgeC2BConfirmation;
 exports.createError = createError;
 exports.encryptSecurityCredential = encryptSecurityCredential;
 exports.extractAmount = extractAmount;
 exports.extractPhoneNumber = extractPhoneNumber;
 exports.extractTransactionId = extractTransactionId;
 exports.formatPhoneNumber = formatSafaricomPhone;
+exports.getC2BAccountRef = getC2BAccountRef;
+exports.getC2BAmount = getC2BAmount;
+exports.getC2BCustomerName = getC2BCustomerName;
+exports.getC2BTransactionId = getC2BTransactionId;
 exports.getCallbackValue = getCallbackValue;
 exports.getTimestamp = getTimestamp;
 exports.handleWebhook = handleWebhook;
+exports.isBuyGoodsPayment = isBuyGoodsPayment;
+exports.isC2BPayload = isC2BPayload;
+exports.isPaybillPayment = isPaybillPayment;
 exports.isStkCallbackSuccess = isStkCallbackSuccess;
 exports.isSuccessfulCallback = isSuccessfulCallback;
 exports.parseStkPushWebhook = parseStkPushWebhook;
+exports.registerC2BUrls = registerC2BUrls;
+exports.rejectC2BValidation = rejectC2BValidation;
 exports.retryWithBackoff = retryWithBackoff;
+exports.simulateC2B = simulateC2B;
 exports.verifyWebhookIP = verifyWebhookIP;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map