pesafy 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # pesafy
 
+## 0.5.2
+
+### Patch Changes
+
+- migrate from cjs/esm to only esm
+
+## 0.5.1
+
+### Patch Changes
+
+- reduce size increase speed
+
 ## 0.5.0
 
 ### Minor Changes
@@ -34,14 +46,20 @@
 
 ### Patch Changes
 
-- C2B URL registration panel with per-shortcode tracking (Paybill + Buy Goods), dual registration support, and session-persisted status badges"
+- C2B URL registration panel with per-shortcode tracking (Paybill + Buy Goods),
+  dual registration support, and session-persisted status badges"
 
 ## 0.3.12
 
 ### Patch Changes
 
-- 047c30f: The payload was always sending BillRefNumber: request.billRefNumber ?? "". For CustomerBuyGoodsOnline, Daraja treats any BillRefNumber field — even "" — as an invalid AccountReference and rejects the request (400 or 503). The fix conditionally includes the field only for Paybill
-- fix error handling and URLs only registered for 600977, never for 600000. The log shows registerC2BUrls shortCode=600977 but then simulateC2B shortCode=600000
+- 047c30f: The payload was always sending BillRefNumber: request.billRefNumber
+  ?? "". For CustomerBuyGoodsOnline, Daraja treats any BillRefNumber field —
+  even "" — as an invalid AccountReference and rejects the request (400 or 503).
+  The fix conditionally includes the field only for Paybill
+- fix error handling and URLs only registered for 600977, never for 600000. The
+  log shows registerC2BUrls shortCode=600977 but then simulateC2B
+  shortCode=600000
 
 ## 0.3.11
 
@@ -53,7 +71,17 @@
 
 ### Patch Changes
 
-- Added Dynamic QR Code support to the pesafy SDK as a new mpesa/dynamic-qr module. This introduces three new files — types.ts, generate.ts, and index.ts — under src/mpesa/dynamic-qr/, implementing the Safaricom Daraja POST /mpesa/qrcode/v1/generate endpoint. The Mpesa class gains a new generateDynamicQR() method that handles token retrieval and delegates to the internal generateDynamicQR function, which validates all inputs (merchant name, reference, amount, transaction code, CPI, and size) before dispatching the request via the existing httpRequest utility. Three new public types — DynamicQRRequest, DynamicQRResponse, and QRTransactionCode — are exported from the root src/index.ts. No breaking changes were introduced; all existing APIs remain untouched.
+- Added Dynamic QR Code support to the pesafy SDK as a new mpesa/dynamic-qr
+  module. This introduces three new files — types.ts, generate.ts, and index.ts
+  — under src/mpesa/dynamic-qr/, implementing the Safaricom Daraja POST
+  /mpesa/qrcode/v1/generate endpoint. The Mpesa class gains a new
+  generateDynamicQR() method that handles token retrieval and delegates to the
+  internal generateDynamicQR function, which validates all inputs (merchant
+  name, reference, amount, transaction code, CPI, and size) before dispatching
+  the request via the existing httpRequest utility. Three new public types —
+  DynamicQRRequest, DynamicQRResponse, and QRTransactionCode — are exported from
+  the root src/index.ts. No breaking changes were introduced; all existing APIs
+  remain untouched.
 
 ## 0.3.9
 
@@ -65,7 +93,15 @@
 
 ### Patch Changes
 
-- Fixed four blocking TypeScript compilation errors before prepublish by extending the `ErrorCode` union to include `API_ERROR`, `NETWORK_ERROR`, and `TIMEOUT`, which resolved type assignment issues in the HTTP layer. Consolidated a duplicate `PesafyError` class (previously split between `index.ts` and `types.ts`) into a single authoritative implementation that preserves all fields, including `requestId`, `toJSON()`, and stack trace handling. Also corrected `x-forwarded-for` IP extraction in the Express webhook handler using safe optional chaining to prevent potential undefined access from the `split()` result.
+- Fixed four blocking TypeScript compilation errors before prepublish by
+  extending the `ErrorCode` union to include `API_ERROR`, `NETWORK_ERROR`, and
+  `TIMEOUT`, which resolved type assignment issues in the HTTP layer.
+  Consolidated a duplicate `PesafyError` class (previously split between
+  `index.ts` and `types.ts`) into a single authoritative implementation that
+  preserves all fields, including `requestId`, `toJSON()`, and stack trace
+  handling. Also corrected `x-forwarded-for` IP extraction in the Express
+  webhook handler using safe optional chaining to prevent potential undefined
+  access from the `split()` result.
 
 ## 0.3.7
 
@@ -89,7 +125,9 @@
 
 ### Patch Changes
 
-- f983f64: The /v2/simulate path is the most critical bug — it will cause persistent 500.003.1001 errors in sandbox just like the /v2/registerurl issue you already fixed.
+- f983f64: The /v2/simulate path is the most critical bug — it will cause
+  persistent 500.003.1001 errors in sandbox just like the /v2/registerurl issue
+  you already fixed.
 
 ## 0.3.3
 
@@ -107,21 +145,67 @@
 
 ### Patch Changes
 
-- **C2B module rewrite & phone utility refactor** — Fixed `simulateC2B` where `CommandID` was hardcoded to `CustomerPayBillOnline`, making `CustomerBuyGoodsOnline` (Till) payments impossible. Corrected `BillRefNumber` logic so the field is omitted entirely for BuyGoods requests rather than defaulting to the string `"default"`, which caused a `400` from Daraja. Fixed `Msisdn` being sent as a quoted string instead of a JSON number as the spec requires. Removed the phantom `ConversationID` field from both `C2BSimulateResponse` and `C2BRegisterUrlResponse` — Daraja never returns this field for C2B, only `OriginatorCoversationID`. Extracted phone formatting into a shared `src/utils/phone.ts` module with two intentionally separate formatters: `formatSafaricomPhone` (strict, Safaricom/Airtel only, for STK Push) and `formatKenyanMsisdn` (permissive, all Kenyan networks, for C2B and B2C), eliminating duplicated logic across modules. Added the `C2BCommandId` union type and full callback payload types — `C2BValidationPayload`, `C2BConfirmationPayload`, and `C2BCallbackPayload` — to enable type-safe webhook handlers.
+- **C2B module rewrite & phone utility refactor** — Fixed `simulateC2B` where
+  `CommandID` was hardcoded to `CustomerPayBillOnline`, making
+  `CustomerBuyGoodsOnline` (Till) payments impossible. Corrected `BillRefNumber`
+  logic so the field is omitted entirely for BuyGoods requests rather than
+  defaulting to the string `"default"`, which caused a `400` from Daraja. Fixed
+  `Msisdn` being sent as a quoted string instead of a JSON number as the spec
+  requires. Removed the phantom `ConversationID` field from both
+  `C2BSimulateResponse` and `C2BRegisterUrlResponse` — Daraja never returns this
+  field for C2B, only `OriginatorCoversationID`. Extracted phone formatting into
+  a shared `src/utils/phone.ts` module with two intentionally separate
+  formatters: `formatSafaricomPhone` (strict, Safaricom/Airtel only, for STK
+  Push) and `formatKenyanMsisdn` (permissive, all Kenyan networks, for C2B and
+  B2C), eliminating duplicated logic across modules. Added the `C2BCommandId`
+  union type and full callback payload types — `C2BValidationPayload`,
+  `C2BConfirmationPayload`, and `C2BCallbackPayload` — to enable type-safe
+  webhook handlers.
 - fbfa311: fix url patch and add elemt accountref
-- aa9c176: **C2B module rewrite & phone utility refactor** — Fixed `simulateC2B` where `CommandID` was hardcoded to `CustomerPayBillOnline`, making `CustomerBuyGoodsOnline` (Till) payments impossible. Corrected `BillRefNumber` logic so the field is omitted entirely for BuyGoods requests rather than defaulting to the string `"default"`, which caused a `400` from Daraja. Fixed `Msisdn` being sent as a quoted string instead of a JSON number as the spec requires. Removed the phantom `ConversationID` field from both `C2BSimulateResponse` and `C2BRegisterUrlResponse` — Daraja never returns this field for C2B, only `OriginatorCoversationID`. Extracted phone formatting into a shared `src/utils/phone.ts` module with two intentionally separate formatters: `formatSafaricomPhone` (strict, Safaricom/Airtel only, for STK Push) and `formatKenyanMsisdn` (permissive, all Kenyan networks, for C2B and B2C), eliminating duplicated logic across modules. Added the `C2BCommandId` union type and full callback payload types — `C2BValidationPayload`, `C2BConfirmationPayload`, and `C2BCallbackPayload` — to enable type-safe webhook handlers.
+- aa9c176: **C2B module rewrite & phone utility refactor** — Fixed `simulateC2B`
+  where `CommandID` was hardcoded to `CustomerPayBillOnline`, making
+  `CustomerBuyGoodsOnline` (Till) payments impossible. Corrected `BillRefNumber`
+  logic so the field is omitted entirely for BuyGoods requests rather than
+  defaulting to the string `"default"`, which caused a `400` from Daraja. Fixed
+  `Msisdn` being sent as a quoted string instead of a JSON number as the spec
+  requires. Removed the phantom `ConversationID` field from both
+  `C2BSimulateResponse` and `C2BRegisterUrlResponse` — Daraja never returns this
+  field for C2B, only `OriginatorCoversationID`. Extracted phone formatting into
+  a shared `src/utils/phone.ts` module with two intentionally separate
+  formatters: `formatSafaricomPhone` (strict, Safaricom/Airtel only, for STK
+  Push) and `formatKenyanMsisdn` (permissive, all Kenyan networks, for C2B and
+  B2C), eliminating duplicated logic across modules. Added the `C2BCommandId`
+  union type and full callback payload types — `C2BValidationPayload`,
+  `C2BConfirmationPayload`, and `C2BCallbackPayload` — to enable type-safe
+  webhook handlers.
 
 ## 0.3.0
 
 ### Minor Changes
 
-- fe95c2b: The C2B M-Pesa implementation in the pesafy package has been comprehensively overhauled for full Daraja C2B v2 compliance, including a complete rewrite of types.ts with all 13 callback fields (C2BCallbackPayload), validation responses, rejection codes, and command/response unions; fixes to register-url.ts ensuring ValidationURL is always sent (defaulting to confirmationUrl); enhanced simulate.ts supporting both CustomerPayBillOnline and CustomerBuyGoodsOnline with proper BillRefNumber handling, amount validation, and Msisdn casting; new c2b index exports; root index public exports; and improved http client error reporting. Dashboard updates add c2bRegisterUrls and c2bSimulate actions in mpesaActions.ts, fix http.ts webhook handlers with 6 missing fields (TransactionType, TransTime, etc.), upsert logic via createTransaction, a new getByShortCode query in businesses.ts, and a complete C2B tab in PaymentsPage.tsx featuring URL registration, simulation forms, and unified transactions—addressing prior gaps like hardcoded commands, missing UI, incomplete types, and non-upserting handlers.
+- fe95c2b: The C2B M-Pesa implementation in the pesafy package has been
+  comprehensively overhauled for full Daraja C2B v2 compliance, including a
+  complete rewrite of types.ts with all 13 callback fields (C2BCallbackPayload),
+  validation responses, rejection codes, and command/response unions; fixes to
+  register-url.ts ensuring ValidationURL is always sent (defaulting to
+  confirmationUrl); enhanced simulate.ts supporting both CustomerPayBillOnline
+  and CustomerBuyGoodsOnline with proper BillRefNumber handling, amount
+  validation, and Msisdn casting; new c2b index exports; root index public
+  exports; and improved http client error reporting. Dashboard updates add
+  c2bRegisterUrls and c2bSimulate actions in mpesaActions.ts, fix http.ts
+  webhook handlers with 6 missing fields (TransactionType, TransTime, etc.),
+  upsert logic via createTransaction, a new getByShortCode query in
+  businesses.ts, and a complete C2B tab in PaymentsPage.tsx featuring URL
+  registration, simulation forms, and unified transactions—addressing prior gaps
+  like hardcoded commands, missing UI, incomplete types, and non-upserting
+  handlers.
 
 ## 0.2.4
 
 ### Patch Changes
 
-- 4a535ef: Request failed with status 500 but swallows the actual Daraja error body — it parses it into data but never includes it in the error message.
+- 4a535ef: Request failed with status 500 but swallows the actual Daraja error
+  body — it parses it into data but never includes it in the error message.
 
 ## 0.2.3
 
@@ -146,14 +230,14 @@
 ### Minor Changes
 
 - Add M-Pesa Express (STK Push) support
-  - Add `processStkPush` to initiate STK Push payment prompts on a
-    customer's phone via POST /mpesa/stkpush/v1/processrequest
-  - Add `queryStkPush` to check the status of an STK Push transaction
-    via POST /mpesa/stkpushquery/v1/query
+  - Add `processStkPush` to initiate STK Push payment prompts on a customer's
+    phone via POST /mpesa/stkpush/v1/processrequest
+  - Add `queryStkPush` to check the status of an STK Push transaction via POST
+    /mpesa/stkpushquery/v1/query
   - Add `StkPushRequest`, `StkPushResponse`, `StkQueryRequest`,
     `StkQueryResponse` and `TransactionType` types
-  - Add `formatPhoneNumber` utility to normalize Kenyan phone numbers
-    to 254 format
+  - Add `formatPhoneNumber` utility to normalize Kenyan phone numbers to 254
+    format
   - Add `getStkPushPassword` to generate Base64(Shortcode+Passkey+Timestamp)
   - Add `getTimestamp` helper for Daraja-formatted timestamps
   - Export all STK Push types and utilities from the package root

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lewis Odero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/{express/index.d.cts → adapters/express.d.ts}

@@ -1,3 +1,4 @@
+import { n as MpesaConfig, t as Environment } from "../types.js";
 import { Router } from "express";
 
 //#region src/mpesa/stk-push/types.d.ts
@@ -13,7 +14,7 @@ import { Router } from "express";
  * CustomerPayBillOnline  → Paybill numbers  (PartyB = shortcode)
  * CustomerBuyGoodsOnline → Till numbers     (PartyB = till number)
  */
-type TransactionType = "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
+type TransactionType = 'CustomerPayBillOnline' | 'CustomerBuyGoodsOnline';
 interface StkPushRequest {
   /** Transaction amount (minimum KES 1, must round to a whole number ≥ 1) */
   amount: number;
@@ -138,7 +139,7 @@ interface TransactionStatusRequest {
    *   "4" = Organisation ShortCode (Paybill / B2C) ← most common
    * Daraja field: IdentifierType
    */
-  identifierType: "1" | "2" | "4";
+  identifierType: '1' | '2' | '4';
   /**
    * URL where Safaricom POSTs the final result.
    * Must be publicly accessible.
@@ -168,34 +169,6 @@ interface TransactionStatusResponse {
   OriginatorConversationID?: string;
 }
 //#endregion
-//#region src/mpesa/types.d.ts
-/**
- * Core M-Pesa / Daraja configuration types
- */
-type Environment = "sandbox" | "production";
-interface MpesaConfig {
-  consumerKey: string;
-  consumerSecret: string;
-  environment: Environment;
-  lipaNaMpesaShortCode?: string;
-  lipaNaMpesaPassKey?: string;
-  initiatorName?: string;
-  initiatorPassword?: string;
-  certificatePath?: string;
-  certificatePem?: string;
-  /**
-   * Pre-computed base64 SecurityCredential — skips RSA encryption.
-   * Use when you encrypt at startup outside the library.
-   */
-  securityCredential?: string;
-  /** Override default retry count (4) for all API calls */
-  retries?: number;
-  /** Override default base retry delay in ms (2000) */
-  retryDelay?: number;
-  /** Override default per-request timeout in ms (30000) */
-  timeout?: number;
-}
-//#endregion
 //#region src/utils/errors/index.d.ts
 /**
  * Pesafy error types — single source of truth.
@@ -288,7 +261,7 @@ interface AccountBalanceRequest {
    *   "4" = Organisation ShortCode (most common — Paybill/B2C)
    * Daraja field: IdentifierType
    */
-  identifierType: "1" | "2" | "4";
+  identifierType: '1' | '2' | '4';
   /**
    * URL where Safaricom POSTs the balance result.
    * Must be publicly accessible. HTTPS required in production.
@@ -447,7 +420,7 @@ type B2BExpressCheckoutCallback = B2BExpressCheckoutCallbackSuccess | B2BExpress
  *   PromotionPayment     — Payment of promotions/bonuses
  *   BusinessPayToBulk    — Load funds to a B2C shortcode for bulk disbursement
  */
-type B2CCommandID = "BusinessPayment" | "SalaryPayment" | "PromotionPayment" | "BusinessPayToBulk";
+type B2CCommandID = 'BusinessPayment' | 'SalaryPayment' | 'PromotionPayment' | 'BusinessPayToBulk';
 interface B2CRequest {
   /**
    * The type of transaction. Use "BusinessPayToBulk" for account top-up.
@@ -485,14 +458,14 @@ interface B2CRequest {
    * Daraja field: SenderIdentifierType
    * Default: "4"
    */
-  senderIdentifierType?: "4";
+  senderIdentifierType?: '4';
   /**
    * Type of the receiver (PartyB) identifier.
    * For this API, only "4" (Organisation ShortCode) is allowed.
    * Daraja field: RecieverIdentifierType
    * Default: "4"
    */
-  receiverIdentifierType?: "4";
+  receiverIdentifierType?: '4';
   /**
    * A reference for this transaction (e.g. invoice number, batch reference).
    * Daraja field: AccountReference
@@ -540,7 +513,7 @@ interface B2CResponse {
  *   - Any unknown future key Daraja may return is still accepted.
  *   - The `no-redundant-type-constituents` ESLint rule is not triggered.
  */
-type B2CResultParameterKey = "DebitAccountBalance" | "Amount" | "DebitPartyAffectedAccountBalance" | "TransCompletedTime" | "DebitPartyCharges" | "ReceiverPartyPublicName" | "Currency" | "InitiatorAccountCurrentBalance" | "B2CRecipientIsRegisteredCustomer" | "B2CChargesPaidAccountAvailableFunds" | "B2CWorkingAccountAvailableFunds" | "B2CUtilityAccountAvailableFunds" | (string & {});
+type B2CResultParameterKey = 'DebitAccountBalance' | 'Amount' | 'DebitPartyAffectedAccountBalance' | 'TransCompletedTime' | 'DebitPartyCharges' | 'ReceiverPartyPublicName' | 'Currency' | 'InitiatorAccountCurrentBalance' | 'B2CRecipientIsRegisteredCustomer' | 'B2CChargesPaidAccountAvailableFunds' | 'B2CWorkingAccountAvailableFunds' | 'B2CUtilityAccountAvailableFunds' | (string & {});
 interface B2CResultParameter {
   Key: B2CResultParameterKey;
   Value: string | number;
@@ -592,7 +565,7 @@ interface BillManagerOptInRequest {
   /** Your logo URL (public HTTPS link) */
   officialContact: string;
   /** Sender name shown on push notifications */
-  sendReminders: "1" | "0";
+  sendReminders: '1' | '0';
   /** Logo URL */
   logo?: string;
   /** Callback URL for payment confirmations */
@@ -660,7 +633,7 @@ interface BillManagerCancelInvoiceResponse {
  * Ref: Customer To Business (C2B) — Daraja Developer Portal
  */
 /** C2B API version. v2 is recommended; v1 sends SHA256-hashed MSISDN. */
-type C2BApiVersion = "v1" | "v2";
+type C2BApiVersion = 'v1' | 'v2';
 /**
  * What M-PESA should do if your Validation URL is unreachable or times out.
  *   "Completed" — M-PESA automatically completes the transaction.
@@ -669,7 +642,7 @@ type C2BApiVersion = "v1" | "v2";
  * NOTE: Must be exactly "Completed" or "Cancelled" (sentence case, no typos).
  * Daraja docs: "the words Cancelled/Completed must be in sentence case and well-spelled."
  */
-type C2BResponseType = "Completed" | "Cancelled";
+type C2BResponseType = 'Completed' | 'Cancelled';
 interface C2BRegisterUrlRequest {
   /**
    * Your M-PESA Paybill or Till shortcode.
@@ -716,7 +689,7 @@ interface C2BRegisterUrlResponse {
  *
  * NOTE: Simulation is ONLY supported in Sandbox, NOT in production.
  */
-type C2BCommandID = "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
+type C2BCommandID = 'CustomerPayBillOnline' | 'CustomerBuyGoodsOnline';
 interface C2BSimulateRequest {
   /**
    * Your M-PESA Paybill or Till shortcode.
@@ -808,7 +781,7 @@ interface C2BValidationPayload {
  *   "C2B00015" — Invalid Short code
  *   "C2B00016" — Other Error
  */
-type C2BValidationResultCode = "0" | "C2B00011" | "C2B00012" | "C2B00013" | "C2B00014" | "C2B00015" | "C2B00016";
+type C2BValidationResultCode = '0' | 'C2B00011' | 'C2B00012' | 'C2B00013' | 'C2B00014' | 'C2B00015' | 'C2B00016';
 interface C2BValidationResponse {
   /**
    * "0" = Accept the transaction.
@@ -822,7 +795,7 @@ interface C2BValidationResponse {
    * "Accepted" when ResultCode is "0".
    * "Rejected" when ResultCode is a non-zero error code.
    */
-  ResultDesc: "Accepted" | "Rejected";
+  ResultDesc: 'Accepted' | 'Rejected';
   /**
    * Optional. If set, this value is echoed back in the Confirmation callback
    * as ThirdPartyTransID. Useful for correlating validation → confirmation.
@@ -883,7 +856,7 @@ interface C2BConfirmationPayload {
  *   SM: Send Money (Mobile number)
  *   SB: Sent to Business (Business number CPI in MSISDN format)
  */
-type QRTransactionCode = "BG" | "WA" | "PB" | "SM" | "SB";
+type QRTransactionCode = 'BG' | 'WA' | 'PB' | 'SM' | 'SB';
 interface DynamicQRRequest {
   /**
    * Name of the Company / M-Pesa Merchant Name.
@@ -975,7 +948,7 @@ interface ReversalRequest {
    *   "4" = Organisation ShortCode
    * Daraja field: RecieverIdentifierType
    */
-  receiverIdentifierType: "1" | "2" | "4";
+  receiverIdentifierType: '1' | '2' | '4';
   /**
    * URL where Safaricom POSTs the reversal result.
    * Daraja field: ResultURL
@@ -1077,7 +1050,7 @@ interface TaxRemittanceResponse {
  *   - Any unknown future key Daraja may return is still accepted.
  *   - The `no-redundant-type-constituents` ESLint rule is not triggered.
  */
-type TaxRemittanceResultParameterKey = "DebitAccountBalance" | "Amount" | "DebitPartyAffectedAccountBalance" | "TransCompletedTime" | "DebitPartyCharges" | "ReceiverPartyPublicName" | "Currency" | "InitiatorAccountCurrentBalance" | (string & {});
+type TaxRemittanceResultParameterKey = 'DebitAccountBalance' | 'Amount' | 'DebitPartyAffectedAccountBalance' | 'TransCompletedTime' | 'DebitPartyCharges' | 'ReceiverPartyPublicName' | 'Currency' | 'InitiatorAccountCurrentBalance' | (string & {});
 interface TaxRemittanceResultParameter {
   Key: TaxRemittanceResultParameterKey;
   Value: string | number;
@@ -1118,9 +1091,9 @@ declare class Mpesa {
    * Like stkPush() but returns Result<T> instead of throwing.
    * Ideal for application-level code that prefers not to use try/catch.
    */
-  stkPushSafe(request: Omit<StkPushRequest, "shortCode" | "passKey">): Promise<Result<Awaited<ReturnType<typeof this.stkPush>>>>;
-  stkPush(request: Omit<StkPushRequest, "shortCode" | "passKey">): Promise<StkPushResponse>;
-  stkQuery(request: Omit<StkQueryRequest, "shortCode" | "passKey">): Promise<StkQueryResponse>;
+  stkPushSafe(request: Omit<StkPushRequest, 'shortCode' | 'passKey'>): Promise<Result<Awaited<ReturnType<typeof this.stkPush>>>>;
+  stkPush(request: Omit<StkPushRequest, 'shortCode' | 'passKey'>): Promise<StkPushResponse>;
+  stkQuery(request: Omit<StkQueryRequest, 'shortCode' | 'passKey'>): Promise<StkQueryResponse>;
   transactionStatus(request: TransactionStatusRequest): Promise<TransactionStatusResponse>;
   /**
    * Queries the balance of your M-PESA shortcode.
@@ -1203,25 +1176,14 @@ declare class Mpesa {
 //#endregion
 //#region src/express/index.d.ts
 interface MpesaExpressConfig extends MpesaConfig {
-  /**
-   * Full public URL Safaricom will POST STK Push callbacks to.
-   * @example "https://yourdomain.com/api/mpesa/express/callback"
-   */
   callbackUrl: string;
-  /**
-   * Full public URL Safaricom will POST Transaction Status results to.
-   * Required when using transactionStatus routes.
-   */
   resultUrl?: string;
-  /**
-   * Full public URL Safaricom calls on queue timeout.
-   */
   queueTimeOutUrl?: string;
   c2bShortCode?: string;
   c2bConfirmationUrl?: string;
   c2bValidationUrl?: string;
-  c2bResponseType?: "Completed" | "Cancelled";
-  c2bApiVersion?: "v1" | "v2";
+  c2bResponseType?: 'Completed' | 'Cancelled';
+  c2bApiVersion?: 'v1' | 'v2';
   onC2BValidation?: (payload: C2BValidationPayload) => Promise<C2BValidationResponse> | C2BValidationResponse;
   onC2BConfirmation?: (payload: C2BConfirmationPayload) => Promise<void> | void;
   taxPartyA?: string;
@@ -1231,92 +1193,15 @@ interface MpesaExpressConfig extends MpesaConfig {
   b2bReceiverShortCode?: string;
   b2bCallbackUrl?: string;
   onB2BCheckoutCallback?: (callback: B2BExpressCheckoutCallback) => Promise<void> | void;
-  /**
-   * Your business shortcode from which B2C money is deducted.
-   * Used as the default partyA for B2C payments when not in the request body.
-   */
   b2cPartyA?: string;
-  /**
-   * Full public URL Safaricom POSTs B2C results to.
-   * Required when using B2C routes.
-   * @example "https://yourdomain.com/api/mpesa/b2c/result"
-   */
   b2cResultUrl?: string;
-  /**
-   * Full public URL Safaricom calls on B2C queue timeout.
-   * Required when using B2C routes.
-   * @example "https://yourdomain.com/api/mpesa/b2c/timeout"
-   */
   b2cQueueTimeOutUrl?: string;
-  /**
-   * Optional hook called when a B2C result arrives at the result URL.
-   * Called for BOTH successful and failed results.
-   *
-   * Fire-and-forget — 200 response to Safaricom is sent immediately.
-   * Errors in this hook are logged but do NOT affect the response.
-   *
-   * @example
-   * onB2CResult: async (result) => {
-   *   if (isB2CSuccess(result)) {
-   *     await db.disbursements.markCompleted({
-   *       transactionId: getB2CTransactionId(result),
-   *       amount:        getB2CAmount(result),
-   *     });
-   *   }
-   * }
-   */
   onB2CResult?: (result: B2CResult) => Promise<void> | void;
-  /**
-   * Skip Safaricom IP verification on callback routes.
-   * ONLY set true in local development — never in production.
-   */
   skipIPCheck?: boolean;
 }
 declare function createMpesaExpressClient(config: MpesaExpressConfig): {
   mpesa: Mpesa;
 };
-/**
- * Attaches all M-Pesa routes to the given Express Router.
- *
- * @example
- * import express from "express";
- * import {
- *   createMpesaExpressRouter,
- *   acceptC2BValidation,
- *   rejectC2BValidation,
- *   isB2CSuccess,
- *   getB2CTransactionId,
- *   getB2CAmount,
- * } from "pesafy/express";
- *
- * const router = express.Router();
- * createMpesaExpressRouter(router, {
- *   consumerKey:          process.env.MPESA_CONSUMER_KEY!,
- *   consumerSecret:       process.env.MPESA_CONSUMER_SECRET!,
- *   environment:          "sandbox",
- *   lipaNaMpesaShortCode: "174379",
- *   lipaNaMpesaPassKey:   "bfb279...",
- *   callbackUrl:          "https://yourdomain.com/mpesa/express/callback",
- *   initiatorName:        "testapi",
- *   initiatorPassword:    "Safaricom123!",
- *   certificatePath:      "./SandboxCertificate.cer",
- *   // B2C
- *   b2cPartyA:            "600979",
- *   b2cResultUrl:         "https://yourdomain.com/mpesa/b2c/result",
- *   b2cQueueTimeOutUrl:   "https://yourdomain.com/mpesa/b2c/timeout",
- *   onB2CResult: async (result) => {
- *     if (isB2CSuccess(result)) {
- *       await db.disbursements.markCompleted({
- *         transactionId: getB2CTransactionId(result),
- *         amount:        getB2CAmount(result),
- *       });
- *     }
- *   },
- *   skipIPCheck: true, // local dev only
- * });
- * app.use("/api", router);
- */
 declare function createMpesaExpressRouter(router: Router, config: MpesaExpressConfig): Router;
 //#endregion
-export { MpesaExpressConfig, createMpesaExpressClient, createMpesaExpressRouter };
-//# sourceMappingURL=index.d.cts.map
+export { MpesaExpressConfig, createMpesaExpressClient, createMpesaExpressRouter };

package/dist/adapters/express.js

@@ -0,0 +1 @@
+import{i as e,n as t,r as n}from"../signature-verifier.js";import{a as r,i,n as a,r as o,t as s}from"../webhook-handler.js";function c(e){return e.resultCode===`0`}function l(e){return e.resultCode===`4001`}function u(e){if(!e||typeof e!=`object`)return!1;let t=e;return typeof t.resultCode==`string`&&typeof t.requestId==`string`&&typeof t.amount==`string`}function d(e){return c(e)?e.transactionId??null:null}function f(e){return Number(e.amount)}function p(e){return c(e)?e.conversationID??null:null}function m(e){if(!e||typeof e!=`object`)return!1;let t=e;if(!t.Result||typeof t.Result!=`object`)return!1;let n=t.Result;return typeof n.ResultCode==`number`&&typeof n.ConversationID==`string`}function h(e){return e.Result.ResultCode===0}function g(e){return e.Result.TransactionID??null}function _(e){return e.Result.ConversationID}function v(e){return e.Result.OriginatorConversationID}function y(e){let t=b(e,`Amount`);return t===void 0?null:Number(t)}function b(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n)return(Array.isArray(n)?n:[n]).find(e=>e.Key===t)?.Value}function x(e){return{ResultCode:`0`,ResultDesc:`Accepted`,...e?{ThirdPartyTransID:e}:{}}}function S(t){if(!t.consumerKey||!t.consumerSecret)throw new e({code:`INVALID_CREDENTIALS`,message:`consumerKey and consumerSecret are required`});if(!t.lipaNaMpesaShortCode||!t.lipaNaMpesaPassKey)throw new e({code:`VALIDATION_ERROR`,message:`lipaNaMpesaShortCode and lipaNaMpesaPassKey are required for STK Push`});if(!t.callbackUrl)throw new e({code:`VALIDATION_ERROR`,message:`callbackUrl is required for STK Push callbacks`});return{mpesa:new n(t)}}function C(t,n){if(n instanceof e){let e=n.statusCode??400;t.status(e).json({error:n.code,message:n.message,statusCode:e});return}t.status(500).json({error:`REQUEST_FAILED`,message:`An unexpected error occurred while processing the M-Pesa request`})}function w(e){return e.headers[`x-forwarded-for`]?.split(`,`)[0]?.trim()??e.ip??``}function T(n,b){let{mpesa:T}=S(b);return n.post(`/mpesa/express/stk-push`,async(t,n,r)=>{try{let r=t.body;if(!r||typeof r.amount!=`number`||r.amount<=0)throw new e({code:`VALIDATION_ERROR`,message:`amount must be a positive number`});if(!r.phoneNumber)throw new e({code:`VALIDATION_ERROR`,message:`phoneNumber is required`});let i=await T.stkPush({amount:r.amount,phoneNumber:r.phoneNumber,callbackUrl:b.callbackUrl,accountReference:r.accountReference??`PESAFY-${Date.now().toString(36).toUpperCase()}`,transactionDesc:r.transactionDesc??`Payment`,...r.transactionType===void 0?{}:{transactionType:r.transactionType},...r.partyB===void 0?{}:{partyB:r.partyB}});n.status(200).json(i)}catch(e){if(n.headersSent)return r(e);C(n,e)}}),n.post(`/mpesa/express/stk-query`,async(t,n,r)=>{try{let r=t.body;if(!r?.checkoutRequestId)throw new e({code:`VALIDATION_ERROR`,message:`checkoutRequestId is required`});let i=await T.stkQuery({checkoutRequestId:r.checkoutRequestId});n.status(200).json(i)}catch(e){if(n.headersSent)return r(e);C(n,e)}}),n.post(`/mpesa/express/callback`,(e,t)=>{let n=w(e),c=i(e.body,{requestIP:n,...b.skipIPCheck===void 0?{}:{skipIPCheck:b.skipIPCheck}});if(!c.success)return console.error(`[pesafy] STK Push webhook rejected:`,c.error),t.status(200).json({ResultCode:0,ResultDesc:`Accepted`});let l=c.data;return r(l)?console.info(`[pesafy] STK Push success:`,{receiptNumber:o(l),amount:s(l),phone:a(l)}):console.warn(`[pesafy] STK Push failed:`,{resultCode:l.Body.stkCallback.ResultCode,resultDesc:l.Body.stkCallback.ResultDesc}),t.status(200).json({ResultCode:0,ResultDesc:`Accepted`})}),n.post(`/mpesa/transaction-status/query`,async(t,n,r)=>{try{if(!b.resultUrl||!b.queueTimeOutUrl)throw new e({code:`VALIDATION_ERROR`,message:`resultUrl and queueTimeOutUrl must be set in config to use transaction status routes`});let r=t.body;if(!r?.transactionId)throw new e({code:`VALIDATION_ERROR`,message:`transactionId is required`});if(!r.partyA)throw new e({code:`VALIDATION_ERROR`,message:`partyA is required`});if(!r.identifierType)throw new e({code:`VALIDATION_ERROR`,message:`identifierType is required: "1" | "2" | "4"`});let i=await T.transactionStatus({transactionId:r.transactionId,partyA:r.partyA,identifierType:r.identifierType,resultUrl:b.resultUrl,queueTimeOutUrl:b.queueTimeOutUrl,...r.remarks===void 0?{}:{remarks:r.remarks},...r.occasion===void 0?{}:{occasion:r.occasion}});n.status(200).json(i)}catch(e){if(n.headersSent)return r(e);C(n,e)}}),n.post(`/mpesa/transaction-status/result`,(e,t)=>{let n=e.body?.Result;n&&(n.ResultCode===0?console.info(`[pesafy] Transaction Status result (success):`,{transactionId:n.TransactionID,conversationId:n.ConversationID,resultDesc:n.ResultDesc}):console.warn(`[pesafy] Transaction Status result (failed):`,{resultCode:n.ResultCode,resultDesc:n.ResultDesc,transactionId:n.TransactionID})),t.status(200).json({ResultCode:0,ResultDesc:`Accepted`})}),n.post(`/mpesa/c2b/register-url`,async(t,n,r)=>{try{let r=t.body,i=r.shortCode??b.c2bShortCode,a=r.confirmationUrl??b.c2bConfirmationUrl,o=r.validationUrl??b.c2bValidationUrl,s=r.responseType??b.c2bResponseType??`Completed`,c=r.apiVersion??b.c2bApiVersion??`v2`;if(!i)throw new e({code:`VALIDATION_ERROR`,message:`shortCode is required`});if(!a)throw new e({code:`VALIDATION_ERROR`,message:`confirmationUrl is required`});if(!o)throw new e({code:`VALIDATION_ERROR`,message:`validationUrl is required`});let l=await T.registerC2BUrls({shortCode:i,responseType:s,confirmationUrl:a,validationUrl:o,apiVersion:c});n.status(200).json(l)}catch(e){if(n.headersSent)return r(e);C(n,e)}}),n.post(`/mpesa/c2b/simulate`,async(t,n,r)=>{try{let r=t.body;if(!r?.commandId)throw new e({code:`VALIDATION_ERROR`,message:`commandId is required: "CustomerPayBillOnline" | "CustomerBuyGoodsOnline"`});if(!r.amount||r.amount<=0)throw new e({code:`VALIDATION_ERROR`,message:`amount must be a positive number`});if(!r.msisdn)throw new e({code:`VALIDATION_ERROR`,message:`msisdn is required`});let i=await T.simulateC2B({shortCode:r.shortCode??b.c2bShortCode??``,commandId:r.commandId,amount:r.amount,msisdn:r.msisdn,apiVersion:b.c2bApiVersion??`v2`,...r.billRefNumber===void 0?{}:{billRefNumber:r.billRefNumber}});n.status(200).json(i)}catch(e){if(n.headersSent)return r(e);C(n,e)}}),n.post(`/mpesa/c2b/validation`,async(e,n)=>{if(!b.skipIPCheck){let r=w(e);if(!t(r))return console.error(`[pesafy] C2B validation rejected — IP not in Safaricom whitelist:`,r),n.status(200).json({ResultCode:`0`,ResultDesc:`Accepted`})}let r=e.body;try{let e;return e=b.onC2BValidation?await b.onC2BValidation(r):x(),console.info(`[pesafy] C2B validation response:`,{transactionId:r.TransID,amount:r.TransAmount,billRef:r.BillRefNumber,resultCode:e.ResultCode}),n.status(200).json(e)}catch(e){return console.error(`[pesafy] C2B validation hook threw an error:`,e),n.status(200).json({ResultCode:`0`,ResultDesc:`Accepted`})}}),n.post(`/mpesa/c2b/confirmation`,(e,t)=>{let n=e.body;console.info(`[pesafy] C2B confirmation received:`,{transactionId:n.TransID,amount:n.TransAmount,shortCode:n.BusinessShortCode,billRef:n.BillRefNumber,transactionType:n.TransactionType,transTime:n.TransTime,balance:n.OrgAccountBalance}),b.onC2BConfirmation&&Promise.resolve(b.onC2BConfirmation(n)).catch(e=>{console.error(`[pesafy] C2B confirmation hook error:`,e)}),t.status(200).json({ResultCode:0,ResultDesc:`Success`})}),n.post(`/mpesa/tax/remit`,async(t,n,r)=>{try{if(!b.taxResultUrl||!b.taxQueueTimeOutUrl)throw new e({code:`VALIDATION_ERROR`,message:`taxResultUrl and taxQueueTimeOutUrl must be set in config to use tax remittance routes`});let r=t.body;if(!r||typeof r.amount!=`number`||r.amount<=0)throw new e({code:`VALIDATION_ERROR`,message:`amount must be a positive number`});if(!r.accountReference)throw new e({code:`VALIDATION_ERROR`,message:`accountReference is required — the KRA PRN`});let i=r.partyA??b.taxPartyA??``;if(!i)throw new e({code:`VALIDATION_ERROR`,message:`partyA is required — set taxPartyA in config or provide in request body`});let a=await T.remitTax({amount:r.amount,partyA:i,accountReference:r.accountReference,resultUrl:b.taxResultUrl,queueTimeOutUrl:b.taxQueueTimeOutUrl,...r.remarks===void 0?{}:{remarks:r.remarks}});n.status(200).json(a)}catch(e){if(n.headersSent)return r(e);C(n,e)}}),n.post(`/mpesa/tax/result`,(e,t)=>{let n=e.body,r=n?.Result;r&&(r.ResultCode===0?console.info(`[pesafy] Tax Remittance result (success):`,{transactionId:r.TransactionID,conversationId:r.ConversationID,resultDesc:r.ResultDesc}):console.warn(`[pesafy] Tax Remittance result (failed):`,{resultCode:r.ResultCode,resultDesc:r.ResultDesc,transactionId:r.TransactionID})),b.onTaxRemittanceResult&&n&&Promise.resolve(b.onTaxRemittanceResult(n)).catch(e=>{console.error(`[pesafy] Tax Remittance result hook error:`,e)}),t.status(200).json({ResultCode:0,ResultDesc:`Accepted`})}),n.post(`/mpesa/b2b/checkout`,async(t,n,r)=>{try{let r=t.body;if(!r?.primaryShortCode)throw new e({code:`VALIDATION_ERROR`,message:`primaryShortCode is required`});if(!r.amount||r.amount<=0)throw new e({code:`VALIDATION_ERROR`,message:`amount must be a positive number`});if(!r.paymentRef)throw new e({code:`VALIDATION_ERROR`,message:`paymentRef is required`});if(!r.partnerName)throw new e({code:`VALIDATION_ERROR`,message:`partnerName is required`});let i=r.receiverShortCode??b.b2bReceiverShortCode??``;if(!i)throw new e({code:`VALIDATION_ERROR`,message:`receiverShortCode is required — set b2bReceiverShortCode in config or provide in request body`});let a=r.callbackUrl??b.b2bCallbackUrl??``;if(!a)throw new e({code:`VALIDATION_ERROR`,message:`callbackUrl is required — set b2bCallbackUrl in config or provide in request body`});let o=await T.b2bExpressCheckout({primaryShortCode:r.primaryShortCode,receiverShortCode:i,amount:r.amount,paymentRef:r.paymentRef,callbackUrl:a,partnerName:r.partnerName,...r.requestRefId===void 0?{}:{requestRefId:r.requestRefId}});n.status(200).json(o)}catch(e){if(n.headersSent)return r(e);C(n,e)}}),n.post(`/mpesa/b2b/callback`,(e,t)=>{let n=e.body;if(!u(n))return console.error(`[pesafy] B2B callback received unrecognised payload:`,JSON.stringify(n).slice(0,200)),t.status(200).json({ResultCode:0,ResultDesc:`Accepted`});let r=n;return c(r)?console.info(`[pesafy] B2B Express Checkout success:`,{transactionId:d(r),conversationId:p(r),amount:f(r),requestId:r.requestId,status:r.status}):l(r)?console.warn(`[pesafy] B2B Express Checkout cancelled by merchant:`,{resultCode:r.resultCode,resultDesc:r.resultDesc,requestId:r.requestId,amount:f(r)}):console.warn(`[pesafy] B2B Express Checkout unknown result:`,{resultCode:r.resultCode,resultDesc:r.resultDesc}),b.onB2BCheckoutCallback&&Promise.resolve(b.onB2BCheckoutCallback(r)).catch(e=>{console.error(`[pesafy] B2B callback hook error:`,e)}),t.status(200).json({ResultCode:0,ResultDesc:`Accepted`})}),n.post(`/mpesa/b2c/payment`,async(t,n,r)=>{try{if(!b.b2cResultUrl||!b.b2cQueueTimeOutUrl)throw new e({code:`VALIDATION_ERROR`,message:`b2cResultUrl and b2cQueueTimeOutUrl must be set in config to use B2C routes`});let r=t.body;if(!r?.commandId)throw new e({code:`VALIDATION_ERROR`,message:`commandId is required: "BusinessPayToBulk" | "BusinessPayment" | "SalaryPayment" | "PromotionPayment"`});if(!r.amount||r.amount<=0)throw new e({code:`VALIDATION_ERROR`,message:`amount must be a positive number`});if(!r.partyB)throw new e({code:`VALIDATION_ERROR`,message:`partyB is required — the recipient shortcode (BusinessPayToBulk) or customer MSISDN`});if(!r.accountReference)throw new e({code:`VALIDATION_ERROR`,message:`accountReference is required`});let i=r.partyA??b.b2cPartyA??``;if(!i)throw new e({code:`VALIDATION_ERROR`,message:`partyA is required — set b2cPartyA in config or provide in request body`});let a=await T.b2cPayment({commandId:r.commandId,amount:r.amount,partyA:i,partyB:r.partyB,accountReference:r.accountReference,resultUrl:r.resultUrl??b.b2cResultUrl,queueTimeOutUrl:r.queueTimeOutUrl??b.b2cQueueTimeOutUrl,...r.requester===void 0?{}:{requester:r.requester},...r.remarks===void 0?{}:{remarks:r.remarks}});n.status(200).json(a)}catch(e){if(n.headersSent)return r(e);C(n,e)}}),n.post(`/mpesa/b2c/result`,(e,t)=>{let n=e.body;if(!m(n))return console.error(`[pesafy] B2C result received unrecognised payload:`,JSON.stringify(n).slice(0,200)),t.status(200).json({ResultCode:0,ResultDesc:`Accepted`});let r=n;return h(r)?console.info(`[pesafy] B2C payment result (success):`,{transactionId:g(r),conversationId:_(r),originatorConversationId:v(r),amount:y(r),resultDesc:r.Result.ResultDesc}):console.warn(`[pesafy] B2C payment result (failed):`,{resultCode:r.Result.ResultCode,resultDesc:r.Result.ResultDesc,transactionId:r.Result.TransactionID,conversationId:_(r),originatorConversationId:v(r)}),b.onB2CResult&&Promise.resolve(b.onB2CResult(r)).catch(e=>{console.error(`[pesafy] B2C result hook error:`,e)}),t.status(200).json({ResultCode:0,ResultDesc:`Accepted`})}),n}export{S as createMpesaExpressClient,T as createMpesaExpressRouter};

package/dist/adapters/fastify.d.ts

@@ -0,0 +1,21 @@
+import { n as MpesaConfig } from "../types.js";
+import { FastifyInstance } from "fastify";
+
+//#region src/adapters/fastify.d.ts
+interface MpesaFastifyConfig extends MpesaConfig {
+  callbackUrl: string;
+  resultUrl?: string;
+  queueTimeOutUrl?: string;
+  skipIPCheck?: boolean;
+  onStkSuccess?: (data: {
+    receiptNumber: string | null;
+    amount: number | null;
+    phone: string | null;
+  }) => Promise<void> | void;
+}
+/**
+ * Registers all M-PESA Fastify routes.
+ */
+declare function registerMpesaRoutes(app: FastifyInstance, config: MpesaFastifyConfig): Promise<void>;
+//#endregion
+export { MpesaFastifyConfig, registerMpesaRoutes };

package/dist/adapters/fastify.js

@@ -0,0 +1 @@
+import{i as e,n as t,r as n}from"../signature-verifier.js";function r(e){let t=e.headers[`x-forwarded-for`];return typeof t==`string`?t.split(`,`)[0]?.trim()??``:e.ip??``}function i(t,n){n instanceof e?t.status(n.statusCode??400).send({error:n.code,message:n.message}):t.status(500).send({error:`INTERNAL_ERROR`})}async function a(a,o){let s=new n(o);a.post(`/mpesa/stk-push`,async(t,n)=>{try{let n=t.body;if(!n.amount||n.amount<=0)throw new e({code:`VALIDATION_ERROR`,message:`amount must be > 0`});if(!n.phoneNumber)throw new e({code:`VALIDATION_ERROR`,message:`phoneNumber is required`});return await s.stkPush({amount:n.amount,phoneNumber:n.phoneNumber,callbackUrl:o.callbackUrl,accountReference:n.accountReference??`REF-${Date.now().toString(36).toUpperCase()}`,transactionDesc:n.transactionDesc??`Payment`,...n.partyB===void 0?{}:{partyB:n.partyB}})}catch(e){i(n,e);return}}),a.post(`/mpesa/stk-query`,async(t,n)=>{try{let{checkoutRequestId:n}=t.body;if(!n)throw new e({code:`VALIDATION_ERROR`,message:`checkoutRequestId is required`});return await s.stkQuery({checkoutRequestId:n})}catch(e){i(n,e);return}}),a.post(`/mpesa/callback`,async(e,n)=>{if(!o.skipIPCheck){let n=r(e);n&&!t(n)&&e.log.warn({ip:n},`[pesafy/fastify] Callback from unknown IP`)}let i=e.body?.Body?.stkCallback;if(i&&i.ResultCode===0){let t=i.CallbackMetadata?.Item??[],n=e=>t.find(t=>t.Name===e)?.Value??null;o.onStkSuccess&&Promise.resolve(o.onStkSuccess({receiptNumber:n(`MpesaReceiptNumber`),amount:n(`Amount`),phone:n(`PhoneNumber`)})).catch(e.log.error)}return{ResultCode:0,ResultDesc:`Accepted`}}),a.post(`/mpesa/balance`,async(t,n)=>{try{if(!o.resultUrl||!o.queueTimeOutUrl)throw new e({code:`VALIDATION_ERROR`,message:`resultUrl and queueTimeOutUrl must be set in config`});return await s.accountBalance({...t.body,resultUrl:o.resultUrl,queueTimeOutUrl:o.queueTimeOutUrl})}catch(e){i(n,e);return}}),a.post(`/mpesa/balance/result`,e=>(e.log.info(e.body,`[pesafy/fastify] Balance result`),{ResultCode:0,ResultDesc:`Accepted`})),a.post(`/mpesa/reversal`,async(t,n)=>{try{if(!o.resultUrl||!o.queueTimeOutUrl)throw new e({code:`VALIDATION_ERROR`,message:`resultUrl and queueTimeOutUrl must be set in config`});return await s.reverseTransaction({...t.body,resultUrl:o.resultUrl,queueTimeOutUrl:o.queueTimeOutUrl})}catch(e){i(n,e);return}}),a.post(`/mpesa/reversal/result`,e=>(e.log.info(e.body,`[pesafy/fastify] Reversal result`),{ResultCode:0,ResultDesc:`Accepted`}))}export{a as registerMpesaRoutes};

package/dist/adapters/hono.d.ts

@@ -0,0 +1,27 @@
+import { n as MpesaConfig } from "../types.js";
+import { Hono } from "hono";
+
+//#region src/adapters/hono.d.ts
+interface MpesaHonoConfig extends MpesaConfig {
+  callbackUrl: string;
+  resultUrl?: string;
+  queueTimeOutUrl?: string;
+  skipIPCheck?: boolean;
+  onStkSuccess?: (data: {
+    receiptNumber: string | null;
+    amount: number | null;
+    phone: string | null;
+  }) => Promise<void> | void;
+  onStkFailure?: (data: {
+    resultCode: number;
+    resultDesc: string;
+  }) => Promise<void> | void;
+  onAccountBalanceResult?: (body: unknown) => Promise<void> | void;
+  onReversalResult?: (body: unknown) => Promise<void> | void;
+}
+/**
+ * Mounts M-PESA routes onto a Hono app instance.
+ */
+declare function createMpesaHonoRouter(app: Hono, config: MpesaHonoConfig): void;
+//#endregion
+export { type MpesaConfig, MpesaHonoConfig, createMpesaHonoRouter };

package/dist/adapters/hono.js

@@ -0,0 +1 @@
+import{i as e,n as t,r as n}from"../signature-verifier.js";import{a as r,n as i,r as a,t as o}from"../webhook-handler.js";function s(e){return e.req.header(`x-forwarded-for`)?.split(`,`)[0]?.trim()??e.req.header(`cf-connecting-ip`)??e.req.header(`x-real-ip`)??``}function c(t,n){if(n instanceof e){let e=n.statusCode??400;return t.json({error:n.code,message:n.message},e)}return t.json({error:`INTERNAL_ERROR`,message:`An unexpected error occurred`},500)}function l(l,u){let d=new n(u);l.post(`/mpesa/express/stk-push`,async t=>{try{let n=await t.req.json();if(!n.amount||n.amount<=0)throw new e({code:`VALIDATION_ERROR`,message:`amount must be > 0`});if(!n.phoneNumber)throw new e({code:`VALIDATION_ERROR`,message:`phoneNumber is required`});let r=await d.stkPush({amount:n.amount,phoneNumber:n.phoneNumber,callbackUrl:u.callbackUrl,accountReference:n.accountReference??`REF-${Date.now().toString(36).toUpperCase()}`,transactionDesc:n.transactionDesc??`Payment`,...n.partyB===void 0?{}:{partyB:n.partyB}});return t.json(r)}catch(e){return c(t,e)}}),l.post(`/mpesa/express/stk-query`,async t=>{try{let{checkoutRequestId:n}=await t.req.json();if(!n)throw new e({code:`VALIDATION_ERROR`,message:`checkoutRequestId is required`});return t.json(await d.stkQuery({checkoutRequestId:n}))}catch(e){return c(t,e)}}),l.post(`/mpesa/express/callback`,async e=>{if(!u.skipIPCheck){let n=s(e);n&&!t(n)&&console.warn(`[pesafy/hono] STK callback from unknown IP:`,n)}let n=await e.req.json(),c=n?.Body?.stkCallback;if(!c)return e.json({ResultCode:0,ResultDesc:`Accepted`});if(r(n)){let e={receiptNumber:a(n),amount:o(n),phone:i(n)};console.info(`[pesafy/hono] STK success:`,e),u.onStkSuccess&&Promise.resolve(u.onStkSuccess(e)).catch(console.error)}else{let e={resultCode:c.ResultCode,resultDesc:c.ResultDesc};console.warn(`[pesafy/hono] STK failed:`,e),u.onStkFailure&&Promise.resolve(u.onStkFailure(e)).catch(console.error)}return e.json({ResultCode:0,ResultDesc:`Accepted`})}),l.post(`/mpesa/balance/query`,async t=>{try{if(!u.resultUrl||!u.queueTimeOutUrl)throw new e({code:`VALIDATION_ERROR`,message:`resultUrl and queueTimeOutUrl are required in config for balance queries`});let n=await t.req.json();return t.json(await d.accountBalance({...n,resultUrl:u.resultUrl,queueTimeOutUrl:u.queueTimeOutUrl}))}catch(e){return c(t,e)}}),l.post(`/mpesa/balance/result`,async e=>{let t=await e.req.json();return u.onAccountBalanceResult&&Promise.resolve(u.onAccountBalanceResult(t)).catch(console.error),console.info(`[pesafy/hono] Account balance result:`,JSON.stringify(t).slice(0,300)),e.json({ResultCode:0,ResultDesc:`Accepted`})}),l.post(`/mpesa/reversal/request`,async t=>{try{if(!u.resultUrl||!u.queueTimeOutUrl)throw new e({code:`VALIDATION_ERROR`,message:`resultUrl and queueTimeOutUrl are required in config for reversals`});let n={...await t.req.json(),resultUrl:u.resultUrl,queueTimeOutUrl:u.queueTimeOutUrl};return t.json(await d.reverseTransaction(n))}catch(e){return c(t,e)}}),l.post(`/mpesa/reversal/result`,async e=>{let t=await e.req.json();return u.onReversalResult&&Promise.resolve(u.onReversalResult(t)).catch(console.error),console.info(`[pesafy/hono] Reversal result:`,JSON.stringify(t).slice(0,300)),e.json({ResultCode:0,ResultDesc:`Accepted`})})}export{l as createMpesaHonoRouter};