@singularity-payments/core 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,896 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MpesaApiError: () => MpesaApiError,
+  MpesaAuthError: () => MpesaAuthError,
+  MpesaCallbackHandler: () => MpesaCallbackHandler,
+  MpesaClient: () => MpesaClient,
+  MpesaError: () => MpesaError,
+  MpesaNetworkError: () => MpesaNetworkError,
+  MpesaRateLimitError: () => MpesaRateLimitError,
+  MpesaTimeoutError: () => MpesaTimeoutError,
+  MpesaValidationError: () => MpesaValidationError,
+  RateLimiter: () => RateLimiter,
+  RedisRateLimiter: () => RedisRateLimiter,
+  retryWithBackoff: () => retryWithBackoff
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils/errors.ts
+var MpesaError = class _MpesaError extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "MpesaError";
+    Object.setPrototypeOf(this, _MpesaError.prototype);
+  }
+};
+var MpesaAuthError = class _MpesaAuthError extends MpesaError {
+  constructor(message, details) {
+    super(message, "AUTH_ERROR", 401, details);
+    this.name = "MpesaAuthError";
+    Object.setPrototypeOf(this, _MpesaAuthError.prototype);
+  }
+};
+var MpesaValidationError = class _MpesaValidationError extends MpesaError {
+  constructor(message, details) {
+    super(message, "VALIDATION_ERROR", 400, details);
+    this.name = "MpesaValidationError";
+    Object.setPrototypeOf(this, _MpesaValidationError.prototype);
+  }
+};
+var MpesaNetworkError = class _MpesaNetworkError extends MpesaError {
+  constructor(message, isRetryable, details) {
+    super(message, "NETWORK_ERROR", 503, details);
+    this.isRetryable = isRetryable;
+    this.name = "MpesaNetworkError";
+    Object.setPrototypeOf(this, _MpesaNetworkError.prototype);
+  }
+};
+var MpesaTimeoutError = class _MpesaTimeoutError extends MpesaError {
+  constructor(message, details) {
+    super(message, "TIMEOUT_ERROR", 408, details);
+    this.name = "MpesaTimeoutError";
+    Object.setPrototypeOf(this, _MpesaTimeoutError.prototype);
+  }
+};
+var MpesaRateLimitError = class _MpesaRateLimitError extends MpesaError {
+  constructor(message, retryAfter, details) {
+    super(message, "RATE_LIMIT_ERROR", 429, details);
+    this.retryAfter = retryAfter;
+    this.name = "MpesaRateLimitError";
+    Object.setPrototypeOf(this, _MpesaRateLimitError.prototype);
+  }
+};
+var MpesaApiError = class _MpesaApiError extends MpesaError {
+  constructor(message, code, statusCode, responseBody) {
+    super(message, code, statusCode, responseBody);
+    this.responseBody = responseBody;
+    this.name = "MpesaApiError";
+    Object.setPrototypeOf(this, _MpesaApiError.prototype);
+  }
+};
+function parseMpesaApiError(statusCode, responseBody) {
+  const errorMessage = responseBody?.errorMessage || responseBody?.ResponseDescription || responseBody?.message || "Unknown API error";
+  const errorCode = responseBody?.errorCode || responseBody?.ResponseCode || "UNKNOWN_ERROR";
+  if (statusCode === 401 || statusCode === 403) {
+    return new MpesaAuthError(errorMessage, responseBody);
+  }
+  if (statusCode === 400) {
+    return new MpesaValidationError(errorMessage, responseBody);
+  }
+  if (statusCode === 429) {
+    const retryAfter = responseBody?.retryAfter;
+    return new MpesaRateLimitError(errorMessage, retryAfter, responseBody);
+  }
+  if (statusCode >= 500) {
+    return new MpesaNetworkError(errorMessage, true, responseBody);
+  }
+  return new MpesaApiError(errorMessage, errorCode, statusCode, responseBody);
+}
+
+// src/utils/retry.ts
+var DEFAULT_RETRY_OPTIONS = {
+  maxRetries: 3,
+  initialDelayMs: 1e3,
+  maxDelayMs: 1e4,
+  backoffMultiplier: 2,
+  retryableStatusCodes: [408, 429, 500, 502, 503, 504],
+  onRetry: () => {
+  }
+};
+function isRetryableError(error, retryableStatusCodes) {
+  if (error instanceof MpesaNetworkError) {
+    return error.isRetryable;
+  }
+  if (error instanceof MpesaRateLimitError) {
+    return true;
+  }
+  if (error instanceof MpesaError && error.statusCode) {
+    return retryableStatusCodes.includes(error.statusCode);
+  }
+  if (error.name === "FetchError" || error.code === "ECONNREFUSED" || error.code === "ETIMEDOUT") {
+    return true;
+  }
+  return false;
+}
+function calculateDelay(attempt, options, error) {
+  if (error instanceof MpesaRateLimitError && error.retryAfter) {
+    return error.retryAfter * 1e3;
+  }
+  const delay = Math.min(
+    options.initialDelayMs * Math.pow(options.backoffMultiplier, attempt),
+    options.maxDelayMs
+  );
+  const jitter = delay * 0.2 * (Math.random() - 0.5) * 2;
+  return Math.floor(delay + jitter);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retryWithBackoff(fn, options = {}) {
+  const opts = { ...DEFAULT_RETRY_OPTIONS, ...options };
+  let lastError;
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (!isRetryableError(error, opts.retryableStatusCodes) || attempt === opts.maxRetries) {
+        throw error;
+      }
+      const delay = calculateDelay(attempt, opts, error);
+      opts.onRetry(error, attempt + 1);
+      await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+
+// src/utils/auth.ts
+var ENDPOINTS = {
+  sandbox: "https://sandbox.safaricom.co.ke",
+  production: "https://api.safaricom.co.ke"
+};
+var MpesaAuth = class {
+  // 30 seconds
+  constructor(config) {
+    this.token = null;
+    this.tokenExpiry = 0;
+    this.REQUEST_TIMEOUT = 3e4;
+    this.config = config;
+  }
+  async getAccessToken() {
+    if (this.token && Date.now() < this.tokenExpiry) {
+      return this.token;
+    }
+    return retryWithBackoff(
+      async () => {
+        const baseUrl = ENDPOINTS[this.config.environment];
+        const auth = Buffer.from(
+          `${this.config.consumerKey}:${this.config.consumerSecret}`
+        ).toString("base64");
+        const controller = new AbortController();
+        const timeoutId = setTimeout(
+          () => controller.abort(),
+          this.REQUEST_TIMEOUT
+        );
+        try {
+          const response = await fetch(
+            `${baseUrl}/oauth/v1/generate?grant_type=client_credentials`,
+            {
+              headers: {
+                Authorization: `Basic ${auth}`
+              },
+              signal: controller.signal
+            }
+          );
+          clearTimeout(timeoutId);
+          if (!response.ok) {
+            const errorBody = await response.json().catch(() => ({}));
+            throw parseMpesaApiError(response.status, errorBody);
+          }
+          const data = await response.json();
+          if (!data.access_token) {
+            throw new MpesaAuthError("No access token in response", data);
+          }
+          this.token = data.access_token;
+          this.tokenExpiry = Date.now() + 50 * 60 * 1e3;
+          return this.token;
+        } catch (error) {
+          clearTimeout(timeoutId);
+          if (error.name === "AbortError") {
+            throw new MpesaTimeoutError(
+              "Request timed out while getting access token"
+            );
+          }
+          if (error instanceof MpesaAuthError) {
+            throw error;
+          }
+          throw new MpesaNetworkError(
+            `Failed to get access token: ${error.message}`,
+            true,
+            error
+          );
+        }
+      },
+      {
+        maxRetries: 3,
+        initialDelayMs: 1e3,
+        onRetry: (error, attempt) => {
+          console.warn(
+            `Retrying authentication (attempt ${attempt}):`,
+            error.message
+          );
+        }
+      }
+    );
+  }
+  getBaseUrl() {
+    return ENDPOINTS[this.config.environment];
+  }
+  getPassword() {
+    const timestamp = this.getTimestamp();
+    const password = Buffer.from(
+      `${this.config.shortcode}${this.config.passkey}${timestamp}`
+    ).toString("base64");
+    return password;
+  }
+  getTimestamp() {
+    const now = /* @__PURE__ */ new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, "0");
+    const day = String(now.getDate()).padStart(2, "0");
+    const hours = String(now.getHours()).padStart(2, "0");
+    const minutes = String(now.getMinutes()).padStart(2, "0");
+    const seconds = String(now.getSeconds()).padStart(2, "0");
+    return `${year}${month}${day}${hours}${minutes}${seconds}`;
+  }
+};
+
+// src/utils/callback.ts
+var MpesaCallbackHandler = class {
+  constructor(options = {}) {
+    // Safaricom's known IP ranges (periodically updated) - Link(https://developer.safaricom.co.ke/dashboard/apis?api=GettingStarted)
+    this.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"
+    ];
+    this.options = {
+      validateIp: true,
+      allowedIps: this.SAFARICOM_IPS,
+      ...options
+    };
+  }
+  /**
+   * Validate that the callback is from a trusted IP
+   */
+  validateCallbackIp(ipAddress) {
+    if (!this.options.validateIp) {
+      return true;
+    }
+    const allowedIps = this.options.allowedIps || this.SAFARICOM_IPS;
+    return allowedIps.includes(ipAddress);
+  }
+  /**
+   * Parse STK Push callback data from M-Pesa
+   */
+  parseCallback(callback) {
+    const stkCallback = callback.Body.stkCallback;
+    const parsed = {
+      merchantRequestId: stkCallback.MerchantRequestID,
+      CheckoutRequestID: stkCallback.CheckoutRequestID,
+      resultCode: stkCallback.ResultCode,
+      resultDescription: stkCallback.ResultDesc,
+      isSuccess: stkCallback.ResultCode === 0,
+      errorMessage: stkCallback.ResultCode !== 0 ? this.getErrorMessage(stkCallback.ResultCode) : void 0
+    };
+    if (stkCallback.ResultCode === 0 && stkCallback.CallbackMetadata) {
+      const metadata = this.extractMetadata(stkCallback.CallbackMetadata);
+      Object.assign(parsed, metadata);
+    }
+    return parsed;
+  }
+  /**
+   * Parse C2B callback data
+   */
+  parseC2BCallback(callback) {
+    return {
+      transactionType: callback.TransactionType,
+      transactionId: callback.TransID,
+      transactionTime: callback.TransTime,
+      amount: parseFloat(callback.TransAmount),
+      businessShortCode: callback.BusinessShortCode,
+      billRefNumber: callback.BillRefNumber,
+      invoiceNumber: callback.InvoiceNumber,
+      msisdn: callback.MSISDN,
+      firstName: callback.FirstName,
+      middleName: callback.MiddleName,
+      lastName: callback.LastName
+    };
+  }
+  /**
+   * Extract metadata from STK callback
+   */
+  extractMetadata(metadata) {
+    const result = {};
+    metadata.Item.forEach((item) => {
+      switch (item.Name) {
+        case "Amount":
+          result.amount = Number(item.Value);
+          break;
+        case "MpesaReceiptNumber":
+          result.mpesaReceiptNumber = String(item.Value);
+          break;
+        case "TransactionDate":
+          result.transactionDate = this.formatTransactionDate(
+            String(item.Value)
+          );
+          break;
+        case "PhoneNumber":
+          result.phoneNumber = String(item.Value);
+          break;
+      }
+    });
+    return result;
+  }
+  /**
+   * Format transaction date from M-Pesa format (YYYYMMDDHHmmss) to ISO
+   */
+  formatTransactionDate(dateStr) {
+    const year = dateStr.substring(0, 4);
+    const month = dateStr.substring(4, 6);
+    const day = dateStr.substring(6, 8);
+    const hours = dateStr.substring(8, 10);
+    const minutes = dateStr.substring(10, 12);
+    const seconds = dateStr.substring(12, 14);
+    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}`;
+  }
+  /**
+   * Check if callback indicates success
+   */
+  isSuccess(data) {
+    return data.resultCode === 0;
+  }
+  /**
+   * Check if callback indicates failure
+   */
+  isFailure(data) {
+    return data.resultCode !== 0;
+  }
+  /**
+   * Get a readable error message based on the code
+   */
+  getErrorMessage(resultCode) {
+    const errorMessages = {
+      0: "Success",
+      1: "Insufficient funds in M-Pesa account",
+      17: "User cancelled the transaction",
+      26: "System internal error",
+      1001: "Unable to lock subscriber, a transaction is already in process",
+      1019: "Transaction expired. No response from user",
+      1032: "Request cancelled by user",
+      1037: "Timeout in sending PIN request",
+      2001: "Wrong PIN entered",
+      9999: "Request cancelled by user"
+    };
+    return errorMessages[resultCode] || `Transaction failed with code: ${resultCode}`;
+  }
+  /**
+   * Handle STK Push callback and invoke appropriate handlers
+   */
+  async handleCallback(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseCallback(callback);
+    this.log("info", "Processing STK callback", {
+      CheckoutRequestID: parsed.CheckoutRequestID,
+      resultCode: parsed.resultCode
+    });
+    if (this.options.isDuplicate) {
+      const isDupe = await this.options.isDuplicate(parsed.CheckoutRequestID);
+      if (isDupe) {
+        this.log("warn", "Duplicate callback detected", {
+          CheckoutRequestID: parsed.CheckoutRequestID
+        });
+        return;
+      }
+    }
+    if (this.options.onCallback) {
+      await this.options.onCallback(parsed);
+    }
+    if (this.isSuccess(parsed) && this.options.onSuccess) {
+      await this.options.onSuccess(parsed);
+    } else if (this.isFailure(parsed) && this.options.onFailure) {
+      await this.options.onFailure(parsed);
+    }
+  }
+  /**
+   * Handle C2B validation request
+   * Returns true if validation passes, false otherwise
+   */
+  async handleC2BValidation(callback) {
+    this.log("info", "Processing C2B validation", {
+      transactionId: callback.TransID
+    });
+    if (this.options.onC2BValidation) {
+      return await this.options.onC2BValidation(
+        this.parseC2BCallback(callback)
+      );
+    }
+    return true;
+  }
+  /**
+   * Handle C2B confirmation
+   */
+  async handleC2BConfirmation(callback) {
+    this.log("info", "Processing C2B confirmation", {
+      transactionId: callback.TransID
+    });
+    if (this.options.onC2BConfirmation) {
+      await this.options.onC2BConfirmation(this.parseC2BCallback(callback));
+    }
+  }
+  /**
+   * Create a standard callback response for M-Pesa
+   */
+  createCallbackResponse(success = true, message) {
+    return {
+      ResultCode: success ? 0 : 1,
+      ResultDesc: message || (success ? "Accepted" : "Rejected")
+    };
+  }
+  /**
+   * Internal logging helper
+   */
+  log(level, message, data) {
+    if (this.options.logger) {
+      this.options.logger[level](message, data);
+    }
+  }
+};
+
+// src/utils/ratelimiter.ts
+var RateLimiter = class {
+  constructor(options) {
+    this.store = /* @__PURE__ */ new Map();
+    this.cleanupInterval = null;
+    this.options = {
+      keyPrefix: "mpesa",
+      ...options
+    };
+    this.startCleanup();
+  }
+  /**
+   * Check if request is allowed
+   */
+  async checkLimit(key) {
+    const fullKey = `${this.options.keyPrefix}:${key}`;
+    const now = Date.now();
+    const entry = this.store.get(fullKey);
+    if (!entry || now >= entry.resetAt) {
+      this.store.set(fullKey, {
+        count: 1,
+        resetAt: now + this.options.windowMs
+      });
+      return;
+    }
+    if (entry.count >= this.options.maxRequests) {
+      const retryAfter = Math.ceil((entry.resetAt - now) / 1e3);
+      throw new MpesaRateLimitError(
+        `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+        retryAfter,
+        {
+          limit: this.options.maxRequests,
+          windowMs: this.options.windowMs,
+          resetAt: entry.resetAt
+        }
+      );
+    }
+    entry.count++;
+  }
+  /**
+   * Get current usage for a key
+   */
+  getUsage(key) {
+    const fullKey = `${this.options.keyPrefix}:${key}`;
+    const entry = this.store.get(fullKey);
+    const now = Date.now();
+    if (!entry || now >= entry.resetAt) {
+      return {
+        count: 0,
+        remaining: this.options.maxRequests,
+        resetAt: now + this.options.windowMs
+      };
+    }
+    return {
+      count: entry.count,
+      remaining: Math.max(0, this.options.maxRequests - entry.count),
+      resetAt: entry.resetAt
+    };
+  }
+  /**
+   * Reset rate limit for a key
+   */
+  reset(key) {
+    const fullKey = `${this.options.keyPrefix}:${key}`;
+    this.store.delete(fullKey);
+  }
+  /**
+   * Clear all rate limits
+   */
+  resetAll() {
+    this.store.clear();
+  }
+  /**
+   * Start cleanup interval
+   */
+  startCleanup() {
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [key, entry] of this.store.entries()) {
+        if (now >= entry.resetAt) {
+          this.store.delete(key);
+        }
+      }
+    }, 6e4);
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+  /**
+   * Stop cleanup interval
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.store.clear();
+  }
+};
+var RedisRateLimiter = class {
+  constructor(redis, options) {
+    this.redis = redis;
+    this.options = {
+      keyPrefix: "mpesa",
+      ...options
+    };
+  }
+  async checkLimit(key) {
+    const fullKey = `${this.options.keyPrefix}:${key}`;
+    const count = await this.redis.incr(fullKey);
+    if (count === 1) {
+      await this.redis.expire(fullKey, Math.ceil(this.options.windowMs / 1e3));
+    }
+    if (count > this.options.maxRequests) {
+      const ttlKey = `${fullKey}:ttl`;
+      const ttl = await this.redis.get(ttlKey);
+      const retryAfter = ttl ? parseInt(ttl) : Math.ceil(this.options.windowMs / 1e3);
+      throw new MpesaRateLimitError(
+        `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+        retryAfter,
+        {
+          limit: this.options.maxRequests,
+          windowMs: this.options.windowMs
+        }
+      );
+    }
+  }
+  async reset(key) {
+    const fullKey = `${this.options.keyPrefix}:${key}`;
+    await this.redis.set(fullKey, "0", "EX", 0);
+  }
+};
+
+// src/client/mpesa-client.ts
+var MpesaClient = class {
+  constructor(config, options = {}) {
+    this.plugins = [];
+    this.rateLimiter = null;
+    this.config = config;
+    this.auth = new MpesaAuth(config);
+    this.callbackHandler = new MpesaCallbackHandler(options.callbackOptions);
+    this.retryOptions = options.retryOptions || {};
+    this.REQUEST_TIMEOUT = options.requestTimeout || 3e4;
+    if (options.rateLimitOptions?.enabled !== false) {
+      const rateLimitOpts = {
+        maxRequests: options.rateLimitOptions?.maxRequests || 100,
+        windowMs: options.rateLimitOptions?.windowMs || 6e4
+      };
+      if (options.rateLimitOptions?.redis) {
+        this.rateLimiter = new RedisRateLimiter(
+          options.rateLimitOptions.redis,
+          rateLimitOpts
+        );
+      } else {
+        this.rateLimiter = new RateLimiter(rateLimitOpts);
+      }
+    }
+  }
+  /**
+   * Make HTTP request with error handling
+   */
+  async makeRequest(endpoint, payload, rateLimitKey) {
+    return retryWithBackoff(async () => {
+      if (this.rateLimiter && rateLimitKey) {
+        await this.rateLimiter.checkLimit(rateLimitKey);
+      }
+      const token = await this.auth.getAccessToken();
+      const baseUrl = this.auth.getBaseUrl();
+      const controller = new AbortController();
+      const timeoutId = setTimeout(
+        () => controller.abort(),
+        this.REQUEST_TIMEOUT
+      );
+      try {
+        const response = await fetch(`${baseUrl}${endpoint}`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(payload),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          const errorBody = await response.json().catch(() => ({}));
+          throw parseMpesaApiError(response.status, errorBody);
+        }
+        return await response.json();
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error.name === "AbortError") {
+          throw new MpesaTimeoutError(`Request timed out for ${endpoint}`);
+        }
+        if (error.statusCode) {
+          throw error;
+        }
+        throw new MpesaNetworkError(
+          `Network error on ${endpoint}: ${error.message}`,
+          true,
+          error
+        );
+      }
+    }, this.retryOptions);
+  }
+  /**
+   * Validate phone number format
+   */
+  validateAndFormatPhone(phone) {
+    let formatted = phone.replace(/[\s\-\+]/g, "");
+    if (formatted.startsWith("0")) {
+      formatted = "254" + formatted.substring(1);
+    } else if (!formatted.startsWith("254")) {
+      formatted = "254" + formatted;
+    }
+    if (!/^254[17]\d{8}$/.test(formatted)) {
+      throw new MpesaValidationError(
+        `Invalid phone number format: ${phone}. Must be a valid Kenyan number.`
+      );
+    }
+    return formatted;
+  }
+  /**
+   * Add a plugin to extend functionality
+   */
+  use(plugin) {
+    this.plugins.push(plugin);
+    plugin.init(this);
+    return this;
+  }
+  /**
+   * Initiate STK Push (Lipa Na M-Pesa Online)
+   */
+  async stkPush(request) {
+    if (request.amount < 1) {
+      throw new MpesaValidationError("Amount must be at least 1 KES");
+    }
+    if (!request.accountReference || request.accountReference.length > 13) {
+      throw new MpesaValidationError(
+        "Account reference is required and must be 13 characters or less"
+      );
+    }
+    if (!request.transactionDesc) {
+      throw new MpesaValidationError("Transaction description is required");
+    }
+    const phone = this.validateAndFormatPhone(request.phoneNumber);
+    const payload = {
+      BusinessShortCode: this.config.shortcode,
+      Password: this.auth.getPassword(),
+      Timestamp: this.auth.getTimestamp(),
+      TransactionType: "CustomerPayBillOnline",
+      Amount: Math.floor(request.amount),
+      PartyA: phone,
+      PartyB: this.config.shortcode,
+      PhoneNumber: phone,
+      CallBackURL: request.callbackUrl || this.config.callbackUrl,
+      AccountReference: request.accountReference,
+      TransactionDesc: request.transactionDesc
+    };
+    return this.makeRequest(
+      "/mpesa/stkpush/v1/processrequest",
+      payload,
+      `stk:${phone}`
+    );
+  }
+  /**
+   * Query STK Push transaction status
+   */
+  async stkQuery(request) {
+    if (!request.CheckoutRequestID) {
+      throw new MpesaValidationError("CheckoutRequestID is required");
+    }
+    const payload = {
+      BusinessShortCode: this.config.shortcode,
+      Password: this.auth.getPassword(),
+      Timestamp: this.auth.getTimestamp(),
+      CheckoutRequestID: request.CheckoutRequestID
+    };
+    return this.makeRequest(
+      "/mpesa/stkpushquery/v1/query",
+      payload,
+      `query:${request.CheckoutRequestID}`
+    );
+  }
+  /**
+   * Register C2B URLs for validation and confirmation
+   */
+  async registerC2BUrl(request) {
+    if (!request.confirmationURL || !request.validationURL) {
+      throw new MpesaValidationError(
+        "Both confirmationURL and validationURL are required"
+      );
+    }
+    const payload = {
+      ShortCode: request.shortCode,
+      ResponseType: request.responseType,
+      ConfirmationURL: request.confirmationURL,
+      ValidationURL: request.validationURL
+    };
+    return this.makeRequest(
+      "/mpesa/c2b/v1/registerurl",
+      payload,
+      "c2b:register"
+    );
+  }
+  /**
+   * Get the callback handler instance
+   */
+  getCallbackHandler() {
+    return this.callbackHandler;
+  }
+  /**
+   * Handle an incoming STK Push callback
+   * Returns M-Pesa compliant response
+   */
+  async handleSTKCallback(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleCallback(callback, ipAddress);
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("STK Callback handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Internal error"
+      );
+    }
+  }
+  /**
+   * Handle C2B validation request
+   */
+  async handleC2BValidation(callback) {
+    try {
+      const isValid = await this.callbackHandler.handleC2BValidation(callback);
+      return this.callbackHandler.createCallbackResponse(
+        isValid,
+        isValid ? "Accepted" : "Rejected"
+      );
+    } catch (error) {
+      console.error("C2B Validation error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Validation failed"
+      );
+    }
+  }
+  /**
+   * Handle C2B confirmation
+   */
+  async handleC2BConfirmation(callback) {
+    try {
+      await this.callbackHandler.handleC2BConfirmation(callback);
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("C2B Confirmation error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Parse STK callback without handling (for testing)
+   */
+  parseSTKCallback(callback) {
+    return this.callbackHandler.parseCallback(callback);
+  }
+  /**
+   * Parse C2B callback without handling (for testing)
+   */
+  parseC2BCallback(callback) {
+    return this.callbackHandler.parseC2BCallback(callback);
+  }
+  /**
+   * Get configuration (for plugins)
+   */
+  getConfig() {
+    return this.config;
+  }
+  /**
+   * Get rate limiter usage for a key
+   */
+  getRateLimitUsage(key) {
+    if (this.rateLimiter instanceof RateLimiter) {
+      return this.rateLimiter.getUsage(key);
+    }
+    return null;
+  }
+  /**
+   * Cleanup resources
+   */
+  destroy() {
+    if (this.rateLimiter instanceof RateLimiter) {
+      this.rateLimiter.destroy();
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MpesaApiError,
+  MpesaAuthError,
+  MpesaCallbackHandler,
+  MpesaClient,
+  MpesaError,
+  MpesaNetworkError,
+  MpesaRateLimitError,
+  MpesaTimeoutError,
+  MpesaValidationError,
+  RateLimiter,
+  RedisRateLimiter,
+  retryWithBackoff
+});