pesafy 0.1.0

package/dist/index.cjs

@@ -0,0 +1,729 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// Pesafy - Payment Gateway Library
+// https://github.com/levos-snr/pesafy
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/utils/errors/error-factory.ts
+var PesafyError = class _PesafyError extends Error {
+  constructor(options) {
+    super(options.message);
+    __publicField(this, "code");
+    __publicField(this, "statusCode");
+    __publicField(this, "response");
+    __publicField(this, "requestId");
+    __publicField(this, "cause");
+    Object.defineProperty(this, "name", { value: "PesafyError" });
+    this.code = options.code;
+    this.statusCode = options.statusCode;
+    this.response = options.response;
+    this.requestId = options.requestId;
+    this.cause = options.cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _PesafyError);
+    }
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      requestId: this.requestId
+    };
+  }
+};
+function createError(options) {
+  return new PesafyError(options);
+}
+
+// src/utils/http/client.ts
+var DEFAULT_TIMEOUT = 3e4;
+async function httpRequest(url, options = {}) {
+  const {
+    method = "GET",
+    headers = {},
+    body,
+    timeout = DEFAULT_TIMEOUT
+  } = options;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      },
+      body: body ? JSON.stringify(body) : void 0,
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    let data;
+    const text = await response.text();
+    try {
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      data = { raw: text };
+    }
+    if (!response.ok) {
+      throw new PesafyError({
+        code: "API_ERROR",
+        message: `Request failed with status ${response.status}`,
+        statusCode: response.status,
+        response: data
+      });
+    }
+    return {
+      data,
+      status: response.status,
+      headers: response.headers
+    };
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof PesafyError) throw error;
+    if (error instanceof Error) {
+      if (error.name === "AbortError") {
+        throw new PesafyError({
+          code: "TIMEOUT",
+          message: `Request timed out after ${timeout}ms`,
+          cause: error
+        });
+      }
+      throw new PesafyError({
+        code: "NETWORK_ERROR",
+        message: error.message,
+        cause: error
+      });
+    }
+    throw new PesafyError({
+      code: "REQUEST_FAILED",
+      message: "An unknown error occurred",
+      cause: error
+    });
+  }
+}
+
+// src/core/auth/token-manager.ts
+var TOKEN_BUFFER_SECONDS = 60;
+var TokenManager = class {
+  constructor(consumerKey, consumerSecret, baseUrl) {
+    __publicField(this, "consumerKey");
+    __publicField(this, "consumerSecret");
+    __publicField(this, "baseUrl");
+    __publicField(this, "cachedToken", null);
+    __publicField(this, "tokenExpiresAt", 0);
+    this.consumerKey = consumerKey;
+    this.consumerSecret = consumerSecret;
+    this.baseUrl = baseUrl;
+  }
+  getAuthHeader() {
+    const credentials = `${this.consumerKey}:${this.consumerSecret}`;
+    const encoded = Buffer.from(credentials, "utf-8").toString("base64");
+    return `Basic ${encoded}`;
+  }
+  async getAccessToken() {
+    const now = Date.now() / 1e3;
+    if (this.cachedToken && this.tokenExpiresAt > now + TOKEN_BUFFER_SECONDS) {
+      return this.cachedToken;
+    }
+    const url = `${this.baseUrl}/oauth/v1/generate?grant_type=client_credentials`;
+    const response = await httpRequest(url, {
+      method: "GET",
+      headers: {
+        Authorization: this.getAuthHeader()
+      }
+    });
+    const data = response.data;
+    if (!data.access_token) {
+      throw new PesafyError({
+        code: "AUTH_FAILED",
+        message: "Failed to obtain access token",
+        response: data
+      });
+    }
+    this.cachedToken = data.access_token;
+    this.tokenExpiresAt = now + (data.expires_in ?? 3600);
+    return this.cachedToken;
+  }
+  clearCache() {
+    this.cachedToken = null;
+    this.tokenExpiresAt = 0;
+  }
+};
+function encryptSecurityCredential(initiatorPassword, certificatePem) {
+  try {
+    const passwordBuffer = Buffer.from(initiatorPassword, "utf-8");
+    const encrypted = crypto.publicEncrypt(
+      {
+        key: certificatePem,
+        padding: 1
+        // RSA_PKCS1_PADDING
+      },
+      passwordBuffer
+    );
+    return encrypted.toString("base64");
+  } catch (error) {
+    throw new PesafyError({
+      code: "ENCRYPTION_FAILED",
+      message: "Failed to encrypt security credential",
+      cause: error
+    });
+  }
+}
+
+// src/mpesa/b2b/b2b.ts
+async function processB2B(baseUrl, accessToken, securityCredential, initiatorName, request) {
+  const body = {
+    Initiator: initiatorName,
+    SecurityCredential: securityCredential,
+    CommandID: request.commandId ?? "BusinessPayBill",
+    SenderIdentifierType: request.senderIdentifierType ?? 4,
+    RecieverIdentifierType: request.receiverIdentifierType ?? 4,
+    Amount: Math.round(request.amount),
+    PartyA: request.shortCode,
+    PartyB: request.receiverShortCode,
+    AccountReference: request.accountReference ?? "",
+    Remarks: request.remarks ?? "B2B Payment",
+    QueueTimeOutURL: request.timeoutUrl,
+    ResultURL: request.resultUrl
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/b2b/v1/paymentrequest`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/stk-push/utils.ts
+function formatPhoneNumber(phone) {
+  const cleaned = phone.replace(/\D/g, "");
+  if (cleaned.startsWith("0")) return "254" + cleaned.slice(1);
+  if (cleaned.startsWith("254")) return cleaned;
+  return "254" + cleaned;
+}
+function getStkPushPassword(shortCode, passKey) {
+  const timestamp = getTimestamp();
+  const password = `${shortCode}${passKey}${timestamp}`;
+  return Buffer.from(password, "utf-8").toString("base64");
+}
+function getTimestamp() {
+  const now = /* @__PURE__ */ new Date();
+  const pad = (n) => n.toString().padStart(2, "0");
+  return [
+    now.getFullYear(),
+    pad(now.getMonth() + 1),
+    pad(now.getDate()),
+    pad(now.getHours()),
+    pad(now.getMinutes()),
+    pad(now.getSeconds())
+  ].join("");
+}
+
+// src/mpesa/b2c/b2c.ts
+async function processB2C(baseUrl, accessToken, securityCredential, initiatorName, request) {
+  const body = {
+    OriginatorConversationID: `AG_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+    InitiatorName: initiatorName,
+    SecurityCredential: securityCredential,
+    CommandID: request.commandId ?? "BusinessPayment",
+    Amount: Math.round(request.amount),
+    PartyA: request.shortCode,
+    PartyB: formatPhoneNumber(request.phoneNumber),
+    Remarks: request.remarks ?? "Payment",
+    QueueTimeOutURL: request.timeoutUrl,
+    ResultURL: request.resultUrl,
+    Occasion: request.occasion ?? ""
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/b2c/v3/paymentrequest`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/c2b/register-url.ts
+async function registerC2BUrls(baseUrl, accessToken, request) {
+  const body = {
+    ShortCode: request.shortCode,
+    ResponseType: request.responseType ?? "Completed",
+    ConfirmationURL: request.confirmationUrl,
+    ValidationURL: request.validationUrl
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/c2b/v2/registerurl`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/c2b/simulate.ts
+async function simulateC2B(baseUrl, accessToken, request) {
+  const body = {
+    ShortCode: request.shortCode,
+    CommandID: "CustomerPayBillOnline",
+    Amount: Math.round(request.amount),
+    Msisdn: formatPhoneNumber(request.phoneNumber),
+    BillRefNumber: request.billRefNumber ?? "default"
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/c2b/v2/simulate`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/qr-code/dynamic-qr.ts
+async function generateDynamicQR(baseUrl, accessToken, request) {
+  const body = {
+    MerchantName: request.merchantName,
+    RefNo: request.refNo,
+    Amount: Math.round(request.amount),
+    TrxCode: request.trxCode,
+    CPI: request.cpi,
+    Size: request.size ?? "300"
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/qrcode/v1/generate`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/reversal/reversal.ts
+async function processReversal(baseUrl, accessToken, securityCredential, initiatorName, request) {
+  const body = {
+    Initiator: initiatorName,
+    SecurityCredential: securityCredential,
+    CommandID: "TransactionReversal",
+    TransactionID: request.transactionId,
+    Amount: Math.round(request.amount),
+    ReceiverParty: request.shortCode,
+    RecieverIdentifierType: 4,
+    ResultURL: request.resultUrl,
+    QueueTimeOutURL: request.timeoutUrl,
+    Remarks: request.remarks ?? "Reversal",
+    Occasion: request.occasion ?? "Reversal"
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/reversal/v1/request`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/stk-push/stk-push.ts
+async function processStkPush(baseUrl, accessToken, request) {
+  const body = {
+    BusinessShortCode: request.shortCode,
+    Password: getStkPushPassword(request.shortCode, request.passKey),
+    Timestamp: getTimestamp(),
+    TransactionType: request.transactionType ?? "CustomerPayBillOnline",
+    Amount: Math.round(request.amount),
+    PartyA: formatPhoneNumber(request.phoneNumber),
+    PartyB: request.shortCode,
+    PhoneNumber: formatPhoneNumber(request.phoneNumber),
+    CallBackURL: request.callbackUrl,
+    AccountReference: request.accountReference.slice(0, 12),
+    TransactionDesc: request.transactionDesc.slice(0, 13)
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/stkpush/v1/processrequest`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/stk-push/stk-query.ts
+async function queryStkPush(baseUrl, accessToken, request) {
+  const body = {
+    BusinessShortCode: request.shortCode,
+    Password: getStkPushPassword(request.shortCode, request.passKey),
+    Timestamp: getTimestamp(),
+    CheckoutRequestID: request.checkoutRequestId
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/stkpushquery/v1/query`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/transaction-status/query.ts
+async function queryTransactionStatus(baseUrl, accessToken, securityCredential, initiatorName, request) {
+  const body = {
+    Initiator: initiatorName,
+    SecurityCredential: securityCredential,
+    CommandID: "TransactionStatusQuery",
+    TransactionID: request.transactionId,
+    PartyA: request.shortCode,
+    IdentifierType: request.identifierType ?? 4,
+    ResultURL: request.resultUrl,
+    QueueTimeOutURL: request.timeoutUrl,
+    Remarks: "Status",
+    Occasion: "Query"
+  };
+  const { data } = await httpRequest(
+    `${baseUrl}/mpesa/transactionstatus/v1/query`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+      body
+    }
+  );
+  return data;
+}
+
+// src/mpesa/types.ts
+var DARAJA_BASE_URLS = {
+  sandbox: "https://sandbox.safaricom.co.ke",
+  production: "https://api.safaricom.co.ke"
+};
+
+// src/mpesa/index.ts
+var Mpesa = class {
+  constructor(config) {
+    __publicField(this, "config");
+    __publicField(this, "tokenManager");
+    __publicField(this, "baseUrl");
+    this.config = config;
+    this.baseUrl = DARAJA_BASE_URLS[config.environment];
+    this.tokenManager = new TokenManager(
+      config.consumerKey,
+      config.consumerSecret,
+      this.baseUrl
+    );
+  }
+  async getToken() {
+    return this.tokenManager.getAccessToken();
+  }
+  async getSecurityCredential() {
+    if (this.config.securityCredential) return this.config.securityCredential;
+    if (!this.config.initiatorPassword) {
+      throw new Error(
+        "Security credential required: provide securityCredential or (initiatorPassword + certificatePath/certificatePem)"
+      );
+    }
+    let cert;
+    if (this.config.certificatePem) {
+      cert = this.config.certificatePem;
+    } else if (this.config.certificatePath) {
+      cert = await Bun.file(this.config.certificatePath).text();
+    } else {
+      throw new Error(
+        "certificatePath or certificatePem required for B2C/B2B/Reversal"
+      );
+    }
+    return encryptSecurityCredential(this.config.initiatorPassword, cert);
+  }
+  /** STK Push (M-Pesa Express) - Initiate payment on customer phone */
+  async stkPush(request) {
+    const shortCode = this.config.lipaNaMpesaShortCode ?? "";
+    const passKey = this.config.lipaNaMpesaPassKey ?? "";
+    if (!shortCode || !passKey) {
+      throw new Error(
+        "lipaNaMpesaShortCode and lipaNaMpesaPassKey required for STK Push"
+      );
+    }
+    const token = await this.getToken();
+    return processStkPush(this.baseUrl, token, {
+      ...request,
+      shortCode,
+      passKey
+    });
+  }
+  /** STK Query - Check STK Push transaction status */
+  async stkQuery(request) {
+    const shortCode = this.config.lipaNaMpesaShortCode ?? "";
+    const passKey = this.config.lipaNaMpesaPassKey ?? "";
+    if (!shortCode || !passKey) {
+      throw new Error(
+        "lipaNaMpesaShortCode and lipaNaMpesaPassKey required for STK Query"
+      );
+    }
+    const token = await this.getToken();
+    return queryStkPush(this.baseUrl, token, {
+      ...request,
+      shortCode,
+      passKey
+    });
+  }
+  /** B2C - Send money to customer */
+  async b2c(request) {
+    const initiator = this.config.initiatorName ?? "";
+    const securityCred = await this.getSecurityCredential();
+    if (!initiator) throw new Error("initiatorName required for B2C");
+    const token = await this.getToken();
+    return processB2C(this.baseUrl, token, securityCred, initiator, request);
+  }
+  /** B2B - Send money to business */
+  async b2b(request) {
+    const initiator = this.config.initiatorName ?? "";
+    const securityCred = await this.getSecurityCredential();
+    if (!initiator) throw new Error("initiatorName required for B2B");
+    const token = await this.getToken();
+    return processB2B(this.baseUrl, token, securityCred, initiator, request);
+  }
+  /** C2B - Register validation/confirmation URLs */
+  async c2bRegisterUrls(request) {
+    const token = await this.getToken();
+    return registerC2BUrls(this.baseUrl, token, request);
+  }
+  /** C2B - Simulate payment (sandbox only) */
+  async c2bSimulate(request) {
+    const token = await this.getToken();
+    return simulateC2B(this.baseUrl, token, request);
+  }
+  /** Dynamic QR - Generate LIPA NA M-PESA QR code */
+  async qrCode(request) {
+    const token = await this.getToken();
+    return generateDynamicQR(this.baseUrl, token, request);
+  }
+  /** Transaction Status - Query transaction status */
+  async transactionStatus(request) {
+    const initiator = this.config.initiatorName ?? "";
+    const securityCred = await this.getSecurityCredential();
+    if (!initiator)
+      throw new Error("initiatorName required for Transaction Status");
+    const token = await this.getToken();
+    return queryTransactionStatus(
+      this.baseUrl,
+      token,
+      securityCred,
+      initiator,
+      request
+    );
+  }
+  /** Reversal - Reverse a transaction */
+  async reversal(request) {
+    const initiator = this.config.initiatorName ?? "";
+    const securityCred = await this.getSecurityCredential();
+    if (!initiator) throw new Error("initiatorName required for Reversal");
+    const token = await this.getToken();
+    return processReversal(
+      this.baseUrl,
+      token,
+      securityCred,
+      initiator,
+      request
+    );
+  }
+};
+
+// src/mpesa/webhooks/retry.ts
+var DEFAULT_OPTIONS = {
+  maxRetries: Infinity,
+  initialDelay: 1e3,
+  // 1 second
+  maxDelay: 36e5,
+  // 1 hour
+  backoffMultiplier: 2,
+  maxRetryDuration: 30 * 24 * 60 * 60 * 1e3
+  // 30 days
+};
+async function retryWithBackoff(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let delay = opts.initialDelay;
+  let attempts = 0;
+  const startTime = Date.now();
+  while (attempts < opts.maxRetries) {
+    attempts++;
+    if (Date.now() - startTime > opts.maxRetryDuration) {
+      return {
+        success: false,
+        attempts,
+        error: new Error("Max retry duration exceeded")
+      };
+    }
+    try {
+      const data = await fn();
+      return { success: true, data, attempts };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (err.message.includes("4")) {
+        return { success: false, attempts, error: err };
+      }
+      if (attempts < opts.maxRetries) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(delay * opts.backoffMultiplier, opts.maxDelay);
+      }
+    }
+  }
+  return {
+    success: false,
+    attempts,
+    error: new Error("Max retries exceeded")
+  };
+}
+
+// src/mpesa/webhooks/signature-verifier.ts
+var SAFARICOM_IPS = [
+  "196.201.214.200",
+  "196.201.214.206",
+  "196.201.213.114",
+  "196.201.214.207",
+  "196.201.214.208",
+  "196.201.213.44",
+  "196.201.212.127",
+  "196.201.212.138",
+  "196.201.212.129",
+  "196.201.212.136",
+  "196.201.212.74",
+  "196.201.212.69"
+];
+function verifyWebhookIP(requestIP, allowedIPs = SAFARICOM_IPS) {
+  return allowedIPs.includes(requestIP);
+}
+function parseStkPushWebhook(body) {
+  try {
+    const parsed = body;
+    if (parsed.Body?.stkCallback) return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+function parseB2CWebhook(body) {
+  try {
+    const parsed = body;
+    if (parsed.Result?.ResultCode !== void 0) return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+function parseC2BWebhook(body) {
+  try {
+    const parsed = body;
+    if (parsed.TransID && parsed.TransAmount) return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/mpesa/webhooks/webhook-handler.ts
+function handleWebhook(body, options = {}) {
+  if (!options.skipIPCheck && options.requestIP) {
+    if (!verifyWebhookIP(options.requestIP, options.allowedIPs)) {
+      return {
+        success: false,
+        eventType: null,
+        data: null,
+        error: "IP address not whitelisted"
+      };
+    }
+  }
+  const stkPush = parseStkPushWebhook(body);
+  if (stkPush) {
+    return {
+      success: true,
+      eventType: "stk_push",
+      data: stkPush
+    };
+  }
+  const b2c = parseB2CWebhook(body);
+  if (b2c) {
+    return {
+      success: true,
+      eventType: "b2c",
+      data: b2c
+    };
+  }
+  const c2b = parseC2BWebhook(body);
+  if (c2b) {
+    return {
+      success: true,
+      eventType: "c2b",
+      data: c2b
+    };
+  }
+  return {
+    success: false,
+    eventType: null,
+    data: null,
+    error: "Unknown webhook format"
+  };
+}
+function extractTransactionId(webhook) {
+  if ("Body" in webhook && webhook.Body?.stkCallback) {
+    const items = webhook.Body.stkCallback.CallbackMetadata?.Item;
+    const mpesaReceipt = items?.find(
+      (item) => item.Name === "MpesaReceiptNumber"
+    );
+    return mpesaReceipt ? String(mpesaReceipt.Value) : null;
+  }
+  if ("Result" in webhook && webhook.Result?.TransactionID) {
+    return webhook.Result.TransactionID;
+  }
+  if ("TransID" in webhook) {
+    return webhook.TransID;
+  }
+  return null;
+}
+function extractAmount(webhook) {
+  if ("Body" in webhook && webhook.Body?.stkCallback) {
+    const items = webhook.Body.stkCallback.CallbackMetadata?.Item;
+    const amount = items?.find((item) => item.Name === "Amount");
+    return amount ? Number(amount.Value) : null;
+  }
+  if ("Result" in webhook && webhook.Result?.ResultParameters) {
+    const params = webhook.Result.ResultParameters.ResultParameter;
+    const amount = params?.find((p) => p.Key === "Amount");
+    return amount ? Number(amount.Value) : null;
+  }
+  if ("TransAmount" in webhook) {
+    return Number.parseFloat(webhook.TransAmount);
+  }
+  return null;
+}
+
+exports.DARAJA_BASE_URLS = DARAJA_BASE_URLS;
+exports.Mpesa = Mpesa;
+exports.PesafyError = PesafyError;
+exports.TokenManager = TokenManager;
+exports.createError = createError;
+exports.encryptSecurityCredential = encryptSecurityCredential;
+exports.extractAmount = extractAmount;
+exports.extractTransactionId = extractTransactionId;
+exports.handleWebhook = handleWebhook;
+exports.retryWithBackoff = retryWithBackoff;
+exports.verifyWebhookIP = verifyWebhookIP;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map