@singularity-payments/core 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/index.d.mts

@@ -262,17 +262,6 @@ interface DynamicQRResponse {
     ResponseDescription: string;
     QRCode: string;
 }
-interface C2BSimulateRequest {
-    amount: number;
-    msisdn: string;
-    billRefNumber: string;
-    commandID?: "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
-}
-interface C2BSimulateResponse {
-    ConversationID: string;
-    OriginatorCoversationID: string;
-    ResponseDescription: string;
-}
 
 interface ParsedCallbackData {
     merchantRequestId: string;
@@ -305,6 +294,11 @@ interface CallbackHandlerOptions {
     onCallback?: (data: ParsedCallbackData) => void | Promise<void>;
     onC2BConfirmation?: (data: ParsedC2BCallback) => void | Promise<void>;
     onC2BValidation?: (data: ParsedC2BCallback) => Promise<boolean>;
+    onB2CResult?: (data: any) => void | Promise<void>;
+    onB2BResult?: (data: any) => void | Promise<void>;
+    onAccountBalanceResult?: (data: any) => void | Promise<void>;
+    onTransactionStatusResult?: (data: any) => void | Promise<void>;
+    onReversalResult?: (data: any) => void | Promise<void>;
     validateIp?: boolean;
     allowedIps?: string[];
     isDuplicate?: (CheckoutRequestID: string) => boolean | Promise<boolean>;
@@ -350,6 +344,26 @@ declare class MpesaCallbackHandler {
      * Get a readable error message based on the code
      */
     getErrorMessage(resultCode: number): string;
+    /**
+     * Handle B2C result callback
+     */
+    handleB2CResult(callback: B2BCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle B2B result callback
+     */
+    handleB2BResult(callback: B2BCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle Account Balance result callback
+     */
+    handleAccountBalanceResult(callback: AccountBalanceCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle Transaction Status result callback
+     */
+    handleTransactionStatusResult(callback: TransactionStatusCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle Reversal result callback
+     */
+    handleReversalResult(callback: ReversalCallback, ipAddress?: string): Promise<void>;
     /**
      * Handle STK Push callback and invoke appropriate handlers
      */
@@ -548,11 +562,6 @@ declare class MpesaClient {
      * Handle C2B validation request
      */
     handleC2BValidation(callback: C2BCallback): Promise<object>;
-    /**
-     * Simulate C2B transaction (Sandbox only)
-     * Used for testing C2B payments in sandbox environment
-     */
-    simulateC2B(request: C2BSimulateRequest): Promise<C2BSimulateResponse>;
     /**
      * B2C - Send money from business to customer
      */
@@ -593,6 +602,26 @@ declare class MpesaClient {
      * Get configuration (for plugins)
      */
     getConfig(): MpesaConfig;
+    /**
+     * Handle B2C result callback
+     */
+    handleB2CResult(callback: B2BCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle B2B result callback
+     */
+    handleB2BResult(callback: B2BCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle Account Balance result callback
+     */
+    handleAccountBalanceResult(callback: AccountBalanceCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle Transaction Status result callback
+     */
+    handleTransactionStatusResult(callback: TransactionStatusCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle Reversal result callback
+     */
+    handleReversalResult(callback: ReversalCallback, ipAddress?: string): Promise<object>;
     /**
      * Get rate limiter usage for a key
      */

package/dist/index.d.ts

@@ -262,17 +262,6 @@ interface DynamicQRResponse {
     ResponseDescription: string;
     QRCode: string;
 }
-interface C2BSimulateRequest {
-    amount: number;
-    msisdn: string;
-    billRefNumber: string;
-    commandID?: "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
-}
-interface C2BSimulateResponse {
-    ConversationID: string;
-    OriginatorCoversationID: string;
-    ResponseDescription: string;
-}
 
 interface ParsedCallbackData {
     merchantRequestId: string;
@@ -305,6 +294,11 @@ interface CallbackHandlerOptions {
     onCallback?: (data: ParsedCallbackData) => void | Promise<void>;
     onC2BConfirmation?: (data: ParsedC2BCallback) => void | Promise<void>;
     onC2BValidation?: (data: ParsedC2BCallback) => Promise<boolean>;
+    onB2CResult?: (data: any) => void | Promise<void>;
+    onB2BResult?: (data: any) => void | Promise<void>;
+    onAccountBalanceResult?: (data: any) => void | Promise<void>;
+    onTransactionStatusResult?: (data: any) => void | Promise<void>;
+    onReversalResult?: (data: any) => void | Promise<void>;
     validateIp?: boolean;
     allowedIps?: string[];
     isDuplicate?: (CheckoutRequestID: string) => boolean | Promise<boolean>;
@@ -350,6 +344,26 @@ declare class MpesaCallbackHandler {
      * Get a readable error message based on the code
      */
     getErrorMessage(resultCode: number): string;
+    /**
+     * Handle B2C result callback
+     */
+    handleB2CResult(callback: B2BCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle B2B result callback
+     */
+    handleB2BResult(callback: B2BCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle Account Balance result callback
+     */
+    handleAccountBalanceResult(callback: AccountBalanceCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle Transaction Status result callback
+     */
+    handleTransactionStatusResult(callback: TransactionStatusCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle Reversal result callback
+     */
+    handleReversalResult(callback: ReversalCallback, ipAddress?: string): Promise<void>;
     /**
      * Handle STK Push callback and invoke appropriate handlers
      */
@@ -548,11 +562,6 @@ declare class MpesaClient {
      * Handle C2B validation request
      */
     handleC2BValidation(callback: C2BCallback): Promise<object>;
-    /**
-     * Simulate C2B transaction (Sandbox only)
-     * Used for testing C2B payments in sandbox environment
-     */
-    simulateC2B(request: C2BSimulateRequest): Promise<C2BSimulateResponse>;
     /**
      * B2C - Send money from business to customer
      */
@@ -593,6 +602,26 @@ declare class MpesaClient {
      * Get configuration (for plugins)
      */
     getConfig(): MpesaConfig;
+    /**
+     * Handle B2C result callback
+     */
+    handleB2CResult(callback: B2BCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle B2B result callback
+     */
+    handleB2BResult(callback: B2BCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle Account Balance result callback
+     */
+    handleAccountBalanceResult(callback: AccountBalanceCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle Transaction Status result callback
+     */
+    handleTransactionStatusResult(callback: TransactionStatusCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle Reversal result callback
+     */
+    handleReversalResult(callback: ReversalCallback, ipAddress?: string): Promise<object>;
     /**
      * Get rate limiter usage for a key
      */

package/dist/index.js

@@ -419,6 +419,91 @@ var MpesaCallbackHandler = class {
     };
     return errorMessages[resultCode] || `Transaction failed with code: ${resultCode}`;
   }
+  /**
+   * Handle B2C result callback
+   */
+  async handleB2CResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseB2CCallback(callback);
+    this.log("info", "Processing B2C result", {
+      transactionId: parsed.transactionId,
+      isSuccess: parsed.isSuccess
+    });
+    if (this.options.onB2CResult) {
+      await this.options.onB2CResult(parsed);
+    }
+  }
+  /**
+   * Handle B2B result callback
+   */
+  async handleB2BResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseB2BCallback(callback);
+    this.log("info", "Processing B2B result", {
+      transactionId: parsed.transactionId,
+      isSuccess: parsed.isSuccess
+    });
+    if (this.options.onB2BResult) {
+      await this.options.onB2BResult(parsed);
+    }
+  }
+  /**
+   * Handle Account Balance result callback
+   */
+  async handleAccountBalanceResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseAccountBalanceCallback(callback);
+    this.log("info", "Processing Account Balance result", {
+      isSuccess: parsed.isSuccess,
+      availableBalance: parsed.availableBalance
+    });
+    if (this.options.onAccountBalanceResult) {
+      await this.options.onAccountBalanceResult(parsed);
+    }
+  }
+  /**
+   * Handle Transaction Status result callback
+   */
+  async handleTransactionStatusResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseTransactionStatusCallback(callback);
+    this.log("info", "Processing Transaction Status result", {
+      isSuccess: parsed.isSuccess,
+      receiptNo: parsed.receiptNo
+    });
+    if (this.options.onTransactionStatusResult) {
+      await this.options.onTransactionStatusResult(parsed);
+    }
+  }
+  /**
+   * Handle Reversal result callback
+   */
+  async handleReversalResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseReversalCallback(callback);
+    this.log("info", "Processing Reversal result", {
+      isSuccess: parsed.isSuccess,
+      transactionId: parsed.transactionId
+    });
+    if (this.options.onReversalResult) {
+      await this.options.onReversalResult(parsed);
+    }
+  }
   /**
    * Handle STK Push callback and invoke appropriate handlers
    */
@@ -956,38 +1041,6 @@ var MpesaClient = class {
       );
     }
   }
-  /**
-   * Simulate C2B transaction (Sandbox only)
-   * Used for testing C2B payments in sandbox environment
-   */
-  async simulateC2B(request) {
-    if (this.config.environment !== "sandbox") {
-      throw new MpesaValidationError(
-        "C2B simulation is only available in sandbox environment"
-      );
-    }
-    if (request.amount < 1) {
-      throw new MpesaValidationError("Amount must be at least 1 KES");
-    }
-    if (!request.billRefNumber || request.billRefNumber.length > 20) {
-      throw new MpesaValidationError(
-        "Bill reference is required and must be 20 characters or less"
-      );
-    }
-    const phone = this.validateAndFormatPhone(request.msisdn);
-    const payload = {
-      ShortCode: this.config.shortcode,
-      CommandID: request.commandID || "CustomerPayBillOnline",
-      Amount: Math.floor(request.amount),
-      Msisdn: phone,
-      BillRefNumber: request.billRefNumber
-    };
-    return this.makeRequest(
-      "/mpesa/c2b/v2/simulate",
-      payload,
-      `c2b:simulate:${phone}`
-    );
-  }
   /**
    * B2C - Send money from business to customer
    */
@@ -1194,6 +1247,87 @@ var MpesaClient = class {
   getConfig() {
     return this.config;
   }
+  /**
+   * Handle B2C result callback
+   */
+  async handleB2CResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleB2CResult(callback, ipAddress);
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("B2C result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Handle B2B result callback
+   */
+  async handleB2BResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleB2BResult(callback, ipAddress);
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("B2B result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Handle Account Balance result callback
+   */
+  async handleAccountBalanceResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleAccountBalanceResult(
+        callback,
+        ipAddress
+      );
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("Account Balance result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Handle Transaction Status result callback
+   */
+  async handleTransactionStatusResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleTransactionStatusResult(
+        callback,
+        ipAddress
+      );
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("Transaction Status result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Handle Reversal result callback
+   */
+  async handleReversalResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleReversalResult(callback, ipAddress);
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("Reversal result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
   /**
    * Get rate limiter usage for a key
    */

package/dist/index.mjs

@@ -370,6 +370,91 @@ var MpesaCallbackHandler = class {
     };
     return errorMessages[resultCode] || `Transaction failed with code: ${resultCode}`;
   }
+  /**
+   * Handle B2C result callback
+   */
+  async handleB2CResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseB2CCallback(callback);
+    this.log("info", "Processing B2C result", {
+      transactionId: parsed.transactionId,
+      isSuccess: parsed.isSuccess
+    });
+    if (this.options.onB2CResult) {
+      await this.options.onB2CResult(parsed);
+    }
+  }
+  /**
+   * Handle B2B result callback
+   */
+  async handleB2BResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseB2BCallback(callback);
+    this.log("info", "Processing B2B result", {
+      transactionId: parsed.transactionId,
+      isSuccess: parsed.isSuccess
+    });
+    if (this.options.onB2BResult) {
+      await this.options.onB2BResult(parsed);
+    }
+  }
+  /**
+   * Handle Account Balance result callback
+   */
+  async handleAccountBalanceResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseAccountBalanceCallback(callback);
+    this.log("info", "Processing Account Balance result", {
+      isSuccess: parsed.isSuccess,
+      availableBalance: parsed.availableBalance
+    });
+    if (this.options.onAccountBalanceResult) {
+      await this.options.onAccountBalanceResult(parsed);
+    }
+  }
+  /**
+   * Handle Transaction Status result callback
+   */
+  async handleTransactionStatusResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseTransactionStatusCallback(callback);
+    this.log("info", "Processing Transaction Status result", {
+      isSuccess: parsed.isSuccess,
+      receiptNo: parsed.receiptNo
+    });
+    if (this.options.onTransactionStatusResult) {
+      await this.options.onTransactionStatusResult(parsed);
+    }
+  }
+  /**
+   * Handle Reversal result callback
+   */
+  async handleReversalResult(callback, ipAddress) {
+    if (ipAddress && !this.validateCallbackIp(ipAddress)) {
+      this.log("warn", `Invalid callback IP: ${ipAddress}`);
+      throw new Error(`Invalid callback IP: ${ipAddress}`);
+    }
+    const parsed = this.parseReversalCallback(callback);
+    this.log("info", "Processing Reversal result", {
+      isSuccess: parsed.isSuccess,
+      transactionId: parsed.transactionId
+    });
+    if (this.options.onReversalResult) {
+      await this.options.onReversalResult(parsed);
+    }
+  }
   /**
    * Handle STK Push callback and invoke appropriate handlers
    */
@@ -907,38 +992,6 @@ var MpesaClient = class {
       );
     }
   }
-  /**
-   * Simulate C2B transaction (Sandbox only)
-   * Used for testing C2B payments in sandbox environment
-   */
-  async simulateC2B(request) {
-    if (this.config.environment !== "sandbox") {
-      throw new MpesaValidationError(
-        "C2B simulation is only available in sandbox environment"
-      );
-    }
-    if (request.amount < 1) {
-      throw new MpesaValidationError("Amount must be at least 1 KES");
-    }
-    if (!request.billRefNumber || request.billRefNumber.length > 20) {
-      throw new MpesaValidationError(
-        "Bill reference is required and must be 20 characters or less"
-      );
-    }
-    const phone = this.validateAndFormatPhone(request.msisdn);
-    const payload = {
-      ShortCode: this.config.shortcode,
-      CommandID: request.commandID || "CustomerPayBillOnline",
-      Amount: Math.floor(request.amount),
-      Msisdn: phone,
-      BillRefNumber: request.billRefNumber
-    };
-    return this.makeRequest(
-      "/mpesa/c2b/v2/simulate",
-      payload,
-      `c2b:simulate:${phone}`
-    );
-  }
   /**
    * B2C - Send money from business to customer
    */
@@ -1145,6 +1198,87 @@ var MpesaClient = class {
   getConfig() {
     return this.config;
   }
+  /**
+   * Handle B2C result callback
+   */
+  async handleB2CResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleB2CResult(callback, ipAddress);
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("B2C result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Handle B2B result callback
+   */
+  async handleB2BResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleB2BResult(callback, ipAddress);
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("B2B result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Handle Account Balance result callback
+   */
+  async handleAccountBalanceResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleAccountBalanceResult(
+        callback,
+        ipAddress
+      );
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("Account Balance result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Handle Transaction Status result callback
+   */
+  async handleTransactionStatusResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleTransactionStatusResult(
+        callback,
+        ipAddress
+      );
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("Transaction Status result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
+  /**
+   * Handle Reversal result callback
+   */
+  async handleReversalResult(callback, ipAddress) {
+    try {
+      await this.callbackHandler.handleReversalResult(callback, ipAddress);
+      return this.callbackHandler.createCallbackResponse(true);
+    } catch (error) {
+      console.error("Reversal result handling error:", error);
+      return this.callbackHandler.createCallbackResponse(
+        false,
+        "Processing failed"
+      );
+    }
+  }
   /**
    * Get rate limiter usage for a key
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@singularity-payments/core",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.5",
   "publishConfig": {
     "access": "public"
   },