pesafy 0.3.0 → 0.3.2

package/dist/index.d.cts

@@ -99,145 +99,127 @@ interface DynamicQRResponse {
  * C2B v1 used SHA-256 hashed MSISDN — do NOT use v1.
  */
 /**
- * ResponseType controls what M-Pesa does if your Validation URL is unreachable.
- * "Completed" = auto-complete. "Cancelled" = auto-cancel.
- * Note: Must be sentence case exactly as shown.
+ * The two valid C2B CommandID values:
+ *  - CustomerPayBillOnline  → payment to a Paybill number
+ *  - CustomerBuyGoodsOnline → payment to a Till number
+ */
+type C2BCommandId = "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
+/**
+ * Default action when the ValidationURL is unreachable.
+ * "Completed" → M-PESA auto-completes the transaction.
+ * "Cancelled" → M-PESA auto-cancels the transaction.
+ * Note: values are case-sensitive per Daraja docs.
  */
 type C2BResponseType = "Completed" | "Cancelled";
 interface C2BRegisterUrlRequest {
-    /** Your Paybill or Till shortcode (5–6 digits). */
+    /** Paybill or Till short code */
     shortCode: string;
-    /**
-     * What M-Pesa does if your Validation URL is unreachable.
-     * Only relevant if External Validation is enabled on your shortcode.
-     * Defaults to "Completed".
-     */
-    responseType?: C2BResponseType;
-    /**
-     * URL that receives payment confirmation after transaction completes.
-     * Must be HTTPS in production. HTTP is allowed in sandbox.
-     */
+    /** URL that receives payment confirmation after a successful transaction */
     confirmationUrl: string;
-    /**
-     * URL for payment validation before M-Pesa completes the transaction.
-     * Only called if External Validation is enabled on your shortcode.
-     * Optional — omit if validation is not required.
-     */
-    validationUrl?: string;
-}
-interface C2BRegisterUrlResponse {
-    /**
-     * Global unique identifier for the request.
-     * NOTE: Daraja has a typo in their field name ("Coversa" not "Conversa").
-     * We mirror it exactly so JSON parsing works.
-     */
-    OriginatorCoversationID: string;
-    ResponseCode: string;
-    ResponseDescription: string;
+    /** URL that receives validation requests (only when external validation is enabled) */
+    validationUrl: string;
+    responseType?: C2BResponseType;
 }
-/**
- * CommandID controls whether this is a Paybill or Buy Goods (Till) payment.
- * - "CustomerPayBillOnline" → Paybill (requires BillRefNumber / account number)
- * - "CustomerBuyGoodsOnline" → Till/Buy Goods (BillRefNumber is null)
- */
-type C2BCommandId = "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
 interface C2BSimulateRequest {
-    /** Your Paybill or Till shortcode. */
+    /** Paybill or Till short code */
     shortCode: string;
-    /** Payment type. Paybill = "CustomerPayBillOnline", Till = "CustomerBuyGoodsOnline". */
-    commandId: C2BCommandId;
-    /** Amount to simulate (whole numbers only — Daraja rejects decimals). */
+    /**
+     * Transaction type.
+     * "CustomerPayBillOnline"  → payment to a Paybill number (default)
+     * "CustomerBuyGoodsOnline" → payment to a Till number
+     */
+    commandId?: C2BCommandId;
+    /** Transaction amount (whole number, min 1 KES) */
     amount: number;
-    /** Phone number to debit in simulation. Use sandbox test numbers. */
+    /** Customer's phone number — any valid Kenyan MSISDN */
     phoneNumber: string;
     /**
-     * Account number / reference for Paybill payments.
-     * Pass null or omit for Buy Goods (Till) transactions.
+     * Account reference for Paybill payments.
+     * Must be null / omitted for CustomerBuyGoodsOnline.
      */
-    billRefNumber?: string | null;
-}
-interface C2BSimulateResponse {
-    /** @see C2BRegisterUrlResponse.OriginatorCoversationID (Daraja typo) */
-    OriginatorCoversationID: string;
-    ResponseCode: string;
-    ResponseDescription: string;
+    billRefNumber?: string;
 }
 /**
- * C2B Confirmation/Validation callback body posted by Safaricom to your URLs.
- * C2B v2 returns a masked MSISDN: "2547 ***** 126"
- *
- * This type covers BOTH the confirmation and validation callbacks —
- * they share the same shape. The difference is:
- *   - Validation: OrgAccountBalance is blank; you must respond Accept/Reject.
- *   - Confirmation: OrgAccountBalance has the post-payment balance.
+ * Shared fields present in both Validation and Confirmation callback payloads.
  */
-interface C2BCallbackPayload {
-    /** "Pay Bill" or "Buy Goods" */
+interface C2BCallbackPayloadBase {
     TransactionType: string;
-    /** Unique M-Pesa transaction ID (e.g. "RKL51ZDR4F") */
+    /** Unique M-PESA transaction ID (e.g. "RKL51ZDR4F") */
     TransID: string;
-    /** Timestamp: "YYYYMMDDHHmmss" (e.g. "20231121121325") */
+    /** 14-digit timestamp: YYYYMMDDHHmmss */
     TransTime: string;
-    /** Amount as string decimal (e.g. "5.00") */
+    /** Transaction amount as a string (e.g. "5.00") */
     TransAmount: string;
-    /** Your Paybill or Till shortcode */
     BusinessShortCode: string;
-    /**
-     * Account reference / bill number entered by customer.
-     * Applies to Paybill transactions. Empty string for Buy Goods.
-     */
+    /** Account reference; empty for Till transactions */
     BillRefNumber: string;
-    /** Invoice number if applicable (usually empty string) */
     InvoiceNumber: string;
-    /**
-     * Post-payment balance of your Utility Account (confirmation only).
-     * Empty string in validation requests.
-     */
     OrgAccountBalance: string;
-    /**
-     * Opaque ID the partner can echo back in the validation response.
-     * Safaricom sends it back in the confirmation if you returned it.
-     */
     ThirdPartyTransID: string;
-    /**
-     * Masked phone number: "2547 ***** 126"
-     * C2B v2 masks for privacy. C2B v1 used SHA-256 hash.
-     */
+    /** v2: masked MSISDN e.g. "2547 ***** 126" */
     MSISDN: string;
-    /** Customer first name (may be empty) */
     FirstName: string;
-    /** Customer middle name (may be empty) */
     MiddleName: string;
-    /** Customer last name (may be empty) */
     LastName: string;
 }
+/** Payload posted to your ValidationURL (if external validation is enabled) */
+type C2BValidationPayload = C2BCallbackPayloadBase;
+/** Payload posted to your ConfirmationURL after successful payment */
+type C2BConfirmationPayload = C2BCallbackPayloadBase;
 /**
- * Your response to M-Pesa's Validation request.
- * You must reply within ~8 seconds or M-Pesa uses ResponseType default.
+ * Union of both C2B callback types.
+ * Use the discriminated `TransactionType` field if you need to distinguish them,
+ * or register separate Express routes for each URL.
  */
-interface C2BValidationResponse {
-    /**
-     * "0" to accept the payment.
-     * Any of the C2B rejection codes to reject (e.g. "C2B00011").
-     */
-    ResultCode: string;
-    /** "Accepted" or "Rejected" */
-    ResultDesc: string;
-}
+type C2BCallbackPayload = C2BValidationPayload | C2BConfirmationPayload;
 /**
- * Rejection codes for the Validation response.
- * Use these ResultCode values when rejecting a payment.
+ * Codes your ValidationURL must return to Safaricom to accept or reject
+ * a payment before it is processed.
  */
 declare const C2B_REJECTION_CODES: {
-    readonly INVALID_MSISDN: "C2B00011";
-    readonly INVALID_ACCOUNT_NUMBER: "C2B00012";
-    readonly INVALID_AMOUNT: "C2B00013";
-    readonly INVALID_KYC_DETAILS: "C2B00014";
-    readonly INVALID_SHORT_CODE: "C2B00015";
-    readonly OTHER_ERROR: "C2B00016";
+    /** Accept the transaction — M-PESA proceeds to process and confirm */
+    readonly ACCEPT: "0";
+    /** Reject the transaction — M-PESA cancels and notifies the customer */
+    readonly REJECT: "1";
 };
 type C2BRejectionCode = (typeof C2B_REJECTION_CODES)[keyof typeof C2B_REJECTION_CODES];
 
+/**
+ * Actual response shape from Daraja.
+ * Note: Daraja's field name has a typo ("CoversationID" — missing the 'n').
+ * We match it exactly so JSON parsing is lossless.
+ */
+interface C2BRegisterUrlResponse {
+    /** Global unique identifier for this registration request. Daraja typo: "Coversation" */
+    OriginatorCoversationID: string;
+    /** "0" = accepted */
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+/**
+ * C2B Simulate (sandbox only)
+ * API: POST /mpesa/c2b/v2/simulate
+ *
+ * Simulates a customer paying a Paybill or Till number.
+ * This endpoint is NOT available in production — use STK Push or Dynamic QR
+ * for production payment initiation.
+ */
+
+/**
+ * Actual response shape from Daraja.
+ * Note: Daraja's field name has a typo ("CoversationID" — missing the 'n').
+ * We match it exactly so JSON parsing is lossless.
+ * There is NO ConversationID field in this response (unlike B2C/B2B).
+ */
+interface C2BSimulateResponse {
+    /** Global unique identifier for this simulate request. Daraja typo: "Coversation" */
+    OriginatorCoversationID: string;
+    /** "0" = accepted */
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
 /** B2B (Business to Business) types */
 type B2BCommandId = "BusinessPayBill" | "BusinessBuyGoods" | "DisburseFundsToBusiness" | "BusinessToBusinessTransfer";
 interface B2BRequest {
@@ -339,6 +321,92 @@ interface StkQueryResponse {
     ResultCode: number;
     ResultDesc: string;
 }
+/** A single metadata item in a successful STK callback */
+interface StkCallbackMetadataItem {
+    Name: "Amount" | "MpesaReceiptNumber" | "TransactionDate" | "PhoneNumber";
+    /** Present on successful transactions; absent on failure */
+    Value?: number | string;
+}
+/** Inner callback object for a SUCCESSFUL STK Push */
+interface StkCallbackSuccess {
+    MerchantRequestID: string;
+    CheckoutRequestID: string;
+    /** 0 = success */
+    ResultCode: 0;
+    ResultDesc: string;
+    CallbackMetadata: {
+        Item: StkCallbackMetadataItem[];
+    };
+}
+/** Inner callback object for a FAILED/CANCELLED STK Push */
+interface StkCallbackFailure {
+    MerchantRequestID: string;
+    CheckoutRequestID: string;
+    /** Non-zero result codes: e.g. 1032 = cancelled by user */
+    ResultCode: number;
+    ResultDesc: string;
+    CallbackMetadata?: never;
+}
+type StkCallbackInner = StkCallbackSuccess | StkCallbackFailure;
+/** Full wrapper that Safaricom POSTs to your CallBackURL */
+interface StkPushCallback {
+    Body: {
+        stkCallback: StkCallbackInner;
+    };
+}
+/**
+ * Type guard — narrows an StkCallbackInner to the success shape.
+ * Usage:
+ *   if (isStkCallbackSuccess(callback.Body.stkCallback)) {
+ *     const receipt = getCallbackValue(callback, "MpesaReceiptNumber");
+ *   }
+ */
+declare function isStkCallbackSuccess(cb: StkCallbackInner): cb is StkCallbackSuccess;
+/**
+ * Extracts a named value from a successful callback's metadata items.
+ * Returns undefined if the key is absent or the callback failed.
+ */
+declare function getCallbackValue(callback: StkPushCallback, name: StkCallbackMetadataItem["Name"]): string | number | undefined;
+
+/**
+ * Shared phone number utilities for M-Pesa API calls.
+ *
+ * Two formatters are intentionally separate:
+ *  - formatSafaricomPhone  → strict, for STK Push (only Safaricom/Airtel)
+ *  - formatKenyanMsisdn    → permissive, for C2B simulate and B2C PartyB
+ *
+ * Daraja consistently expects 12-digit MSISDN without the '+' prefix.
+ */
+/**
+ * Strict formatter for STK Push.
+ * Accepts Safaricom (2547xx) and Airtel Kenya (2541x) numbers only.
+ * Throws a clear error on invalid input so Daraja never receives a bad MSISDN.
+ */
+declare function formatSafaricomPhone(phone: string): string;
+/**
+ * Permissive formatter for C2B simulate and B2C PartyB.
+ * Accepts any valid 12-digit Kenyan MSISDN (Safaricom, Airtel, Telkom, …).
+ * Still throws if the result is structurally impossible.
+ */
+declare function formatKenyanMsisdn(phone: string): string;
+/**
+ * Converts a formatted MSISDN string to the numeric form Daraja expects in
+ * C2B simulate requests ("Msisdn": 254708374149 — no quotes in the JSON).
+ */
+declare function msisdnToNumber(phone: string): number;
+
+/**
+ * STK Push utilities
+ *
+ * Phone formatting delegates to the shared `formatSafaricomPhone` util which
+ * validates Safaricom/Airtel numbers and throws a clear error on bad input.
+ */
+
+/**
+ * Generates a Daraja-compatible timestamp: YYYYMMDDHHmmss
+ * Call this once per request and reuse the value.
+ */
+declare function getTimestamp(): string;
 
 type Environment = "sandbox" | "production";
 declare const DARAJA_BASE_URLS: {
@@ -560,4 +628,4 @@ declare class PesafyError extends Error {
 }
 declare function createError(options: PesafyErrorOptions): PesafyError;
 
-export { type B2BRequest, type B2BResponse, type B2CRequest, type B2CResponse, type B2CWebhook, type C2BCallbackPayload, type C2BCommandId, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BRejectionCode, type C2BResponseType, type C2BSimulateRequest, type C2BSimulateResponse, type C2BValidationResponse, type C2BWebhook, C2B_REJECTION_CODES, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type ErrorCode, Mpesa, type MpesaConfig, type MpesaExpressConfig, PesafyError, type RetryOptions, type RetryResult, type ReversalRequest, type ReversalResponse, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, TokenManager, type TransactionStatusRequest, type TransactionStatusResponse, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, createError, createMpesaExpressClient, createMpesaExpressRouter, encryptSecurityCredential, extractAmount, extractTransactionId, handleWebhook, retryWithBackoff, verifyWebhookIP };
+export { type B2BRequest, type B2BResponse, type B2CRequest, type B2CResponse, type B2CWebhook, type C2BCallbackPayload, type C2BCallbackPayloadBase, type C2BCommandId, type C2BConfirmationPayload, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BRejectionCode, type C2BSimulateRequest, type C2BSimulateResponse, type C2BValidationPayload, type C2BWebhook, C2B_REJECTION_CODES, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type ErrorCode, Mpesa, type MpesaConfig, type MpesaExpressConfig, PesafyError, type RetryOptions, type RetryResult, type ReversalRequest, type ReversalResponse, type StkCallbackFailure, type StkCallbackInner, type StkCallbackMetadataItem, type StkCallbackSuccess, type StkPushCallback, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, TokenManager, type TransactionStatusRequest, type TransactionStatusResponse, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, createError, createMpesaExpressClient, createMpesaExpressRouter, encryptSecurityCredential, extractAmount, extractTransactionId, formatKenyanMsisdn, formatSafaricomPhone as formatPhoneNumber, formatSafaricomPhone, getCallbackValue, getTimestamp, handleWebhook, isStkCallbackSuccess, msisdnToNumber, retryWithBackoff, verifyWebhookIP };

package/dist/index.d.ts

@@ -99,145 +99,127 @@ interface DynamicQRResponse {
  * C2B v1 used SHA-256 hashed MSISDN — do NOT use v1.
  */
 /**
- * ResponseType controls what M-Pesa does if your Validation URL is unreachable.
- * "Completed" = auto-complete. "Cancelled" = auto-cancel.
- * Note: Must be sentence case exactly as shown.
+ * The two valid C2B CommandID values:
+ *  - CustomerPayBillOnline  → payment to a Paybill number
+ *  - CustomerBuyGoodsOnline → payment to a Till number
+ */
+type C2BCommandId = "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
+/**
+ * Default action when the ValidationURL is unreachable.
+ * "Completed" → M-PESA auto-completes the transaction.
+ * "Cancelled" → M-PESA auto-cancels the transaction.
+ * Note: values are case-sensitive per Daraja docs.
  */
 type C2BResponseType = "Completed" | "Cancelled";
 interface C2BRegisterUrlRequest {
-    /** Your Paybill or Till shortcode (5–6 digits). */
+    /** Paybill or Till short code */
     shortCode: string;
-    /**
-     * What M-Pesa does if your Validation URL is unreachable.
-     * Only relevant if External Validation is enabled on your shortcode.
-     * Defaults to "Completed".
-     */
-    responseType?: C2BResponseType;
-    /**
-     * URL that receives payment confirmation after transaction completes.
-     * Must be HTTPS in production. HTTP is allowed in sandbox.
-     */
+    /** URL that receives payment confirmation after a successful transaction */
     confirmationUrl: string;
-    /**
-     * URL for payment validation before M-Pesa completes the transaction.
-     * Only called if External Validation is enabled on your shortcode.
-     * Optional — omit if validation is not required.
-     */
-    validationUrl?: string;
-}
-interface C2BRegisterUrlResponse {
-    /**
-     * Global unique identifier for the request.
-     * NOTE: Daraja has a typo in their field name ("Coversa" not "Conversa").
-     * We mirror it exactly so JSON parsing works.
-     */
-    OriginatorCoversationID: string;
-    ResponseCode: string;
-    ResponseDescription: string;
+    /** URL that receives validation requests (only when external validation is enabled) */
+    validationUrl: string;
+    responseType?: C2BResponseType;
 }
-/**
- * CommandID controls whether this is a Paybill or Buy Goods (Till) payment.
- * - "CustomerPayBillOnline" → Paybill (requires BillRefNumber / account number)
- * - "CustomerBuyGoodsOnline" → Till/Buy Goods (BillRefNumber is null)
- */
-type C2BCommandId = "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
 interface C2BSimulateRequest {
-    /** Your Paybill or Till shortcode. */
+    /** Paybill or Till short code */
     shortCode: string;
-    /** Payment type. Paybill = "CustomerPayBillOnline", Till = "CustomerBuyGoodsOnline". */
-    commandId: C2BCommandId;
-    /** Amount to simulate (whole numbers only — Daraja rejects decimals). */
+    /**
+     * Transaction type.
+     * "CustomerPayBillOnline"  → payment to a Paybill number (default)
+     * "CustomerBuyGoodsOnline" → payment to a Till number
+     */
+    commandId?: C2BCommandId;
+    /** Transaction amount (whole number, min 1 KES) */
     amount: number;
-    /** Phone number to debit in simulation. Use sandbox test numbers. */
+    /** Customer's phone number — any valid Kenyan MSISDN */
     phoneNumber: string;
     /**
-     * Account number / reference for Paybill payments.
-     * Pass null or omit for Buy Goods (Till) transactions.
+     * Account reference for Paybill payments.
+     * Must be null / omitted for CustomerBuyGoodsOnline.
      */
-    billRefNumber?: string | null;
-}
-interface C2BSimulateResponse {
-    /** @see C2BRegisterUrlResponse.OriginatorCoversationID (Daraja typo) */
-    OriginatorCoversationID: string;
-    ResponseCode: string;
-    ResponseDescription: string;
+    billRefNumber?: string;
 }
 /**
- * C2B Confirmation/Validation callback body posted by Safaricom to your URLs.
- * C2B v2 returns a masked MSISDN: "2547 ***** 126"
- *
- * This type covers BOTH the confirmation and validation callbacks —
- * they share the same shape. The difference is:
- *   - Validation: OrgAccountBalance is blank; you must respond Accept/Reject.
- *   - Confirmation: OrgAccountBalance has the post-payment balance.
+ * Shared fields present in both Validation and Confirmation callback payloads.
  */
-interface C2BCallbackPayload {
-    /** "Pay Bill" or "Buy Goods" */
+interface C2BCallbackPayloadBase {
     TransactionType: string;
-    /** Unique M-Pesa transaction ID (e.g. "RKL51ZDR4F") */
+    /** Unique M-PESA transaction ID (e.g. "RKL51ZDR4F") */
     TransID: string;
-    /** Timestamp: "YYYYMMDDHHmmss" (e.g. "20231121121325") */
+    /** 14-digit timestamp: YYYYMMDDHHmmss */
     TransTime: string;
-    /** Amount as string decimal (e.g. "5.00") */
+    /** Transaction amount as a string (e.g. "5.00") */
     TransAmount: string;
-    /** Your Paybill or Till shortcode */
     BusinessShortCode: string;
-    /**
-     * Account reference / bill number entered by customer.
-     * Applies to Paybill transactions. Empty string for Buy Goods.
-     */
+    /** Account reference; empty for Till transactions */
     BillRefNumber: string;
-    /** Invoice number if applicable (usually empty string) */
     InvoiceNumber: string;
-    /**
-     * Post-payment balance of your Utility Account (confirmation only).
-     * Empty string in validation requests.
-     */
     OrgAccountBalance: string;
-    /**
-     * Opaque ID the partner can echo back in the validation response.
-     * Safaricom sends it back in the confirmation if you returned it.
-     */
     ThirdPartyTransID: string;
-    /**
-     * Masked phone number: "2547 ***** 126"
-     * C2B v2 masks for privacy. C2B v1 used SHA-256 hash.
-     */
+    /** v2: masked MSISDN e.g. "2547 ***** 126" */
     MSISDN: string;
-    /** Customer first name (may be empty) */
     FirstName: string;
-    /** Customer middle name (may be empty) */
     MiddleName: string;
-    /** Customer last name (may be empty) */
     LastName: string;
 }
+/** Payload posted to your ValidationURL (if external validation is enabled) */
+type C2BValidationPayload = C2BCallbackPayloadBase;
+/** Payload posted to your ConfirmationURL after successful payment */
+type C2BConfirmationPayload = C2BCallbackPayloadBase;
 /**
- * Your response to M-Pesa's Validation request.
- * You must reply within ~8 seconds or M-Pesa uses ResponseType default.
+ * Union of both C2B callback types.
+ * Use the discriminated `TransactionType` field if you need to distinguish them,
+ * or register separate Express routes for each URL.
  */
-interface C2BValidationResponse {
-    /**
-     * "0" to accept the payment.
-     * Any of the C2B rejection codes to reject (e.g. "C2B00011").
-     */
-    ResultCode: string;
-    /** "Accepted" or "Rejected" */
-    ResultDesc: string;
-}
+type C2BCallbackPayload = C2BValidationPayload | C2BConfirmationPayload;
 /**
- * Rejection codes for the Validation response.
- * Use these ResultCode values when rejecting a payment.
+ * Codes your ValidationURL must return to Safaricom to accept or reject
+ * a payment before it is processed.
  */
 declare const C2B_REJECTION_CODES: {
-    readonly INVALID_MSISDN: "C2B00011";
-    readonly INVALID_ACCOUNT_NUMBER: "C2B00012";
-    readonly INVALID_AMOUNT: "C2B00013";
-    readonly INVALID_KYC_DETAILS: "C2B00014";
-    readonly INVALID_SHORT_CODE: "C2B00015";
-    readonly OTHER_ERROR: "C2B00016";
+    /** Accept the transaction — M-PESA proceeds to process and confirm */
+    readonly ACCEPT: "0";
+    /** Reject the transaction — M-PESA cancels and notifies the customer */
+    readonly REJECT: "1";
 };
 type C2BRejectionCode = (typeof C2B_REJECTION_CODES)[keyof typeof C2B_REJECTION_CODES];
 
+/**
+ * Actual response shape from Daraja.
+ * Note: Daraja's field name has a typo ("CoversationID" — missing the 'n').
+ * We match it exactly so JSON parsing is lossless.
+ */
+interface C2BRegisterUrlResponse {
+    /** Global unique identifier for this registration request. Daraja typo: "Coversation" */
+    OriginatorCoversationID: string;
+    /** "0" = accepted */
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+/**
+ * C2B Simulate (sandbox only)
+ * API: POST /mpesa/c2b/v2/simulate
+ *
+ * Simulates a customer paying a Paybill or Till number.
+ * This endpoint is NOT available in production — use STK Push or Dynamic QR
+ * for production payment initiation.
+ */
+
+/**
+ * Actual response shape from Daraja.
+ * Note: Daraja's field name has a typo ("CoversationID" — missing the 'n').
+ * We match it exactly so JSON parsing is lossless.
+ * There is NO ConversationID field in this response (unlike B2C/B2B).
+ */
+interface C2BSimulateResponse {
+    /** Global unique identifier for this simulate request. Daraja typo: "Coversation" */
+    OriginatorCoversationID: string;
+    /** "0" = accepted */
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
 /** B2B (Business to Business) types */
 type B2BCommandId = "BusinessPayBill" | "BusinessBuyGoods" | "DisburseFundsToBusiness" | "BusinessToBusinessTransfer";
 interface B2BRequest {
@@ -339,6 +321,92 @@ interface StkQueryResponse {
     ResultCode: number;
     ResultDesc: string;
 }
+/** A single metadata item in a successful STK callback */
+interface StkCallbackMetadataItem {
+    Name: "Amount" | "MpesaReceiptNumber" | "TransactionDate" | "PhoneNumber";
+    /** Present on successful transactions; absent on failure */
+    Value?: number | string;
+}
+/** Inner callback object for a SUCCESSFUL STK Push */
+interface StkCallbackSuccess {
+    MerchantRequestID: string;
+    CheckoutRequestID: string;
+    /** 0 = success */
+    ResultCode: 0;
+    ResultDesc: string;
+    CallbackMetadata: {
+        Item: StkCallbackMetadataItem[];
+    };
+}
+/** Inner callback object for a FAILED/CANCELLED STK Push */
+interface StkCallbackFailure {
+    MerchantRequestID: string;
+    CheckoutRequestID: string;
+    /** Non-zero result codes: e.g. 1032 = cancelled by user */
+    ResultCode: number;
+    ResultDesc: string;
+    CallbackMetadata?: never;
+}
+type StkCallbackInner = StkCallbackSuccess | StkCallbackFailure;
+/** Full wrapper that Safaricom POSTs to your CallBackURL */
+interface StkPushCallback {
+    Body: {
+        stkCallback: StkCallbackInner;
+    };
+}
+/**
+ * Type guard — narrows an StkCallbackInner to the success shape.
+ * Usage:
+ *   if (isStkCallbackSuccess(callback.Body.stkCallback)) {
+ *     const receipt = getCallbackValue(callback, "MpesaReceiptNumber");
+ *   }
+ */
+declare function isStkCallbackSuccess(cb: StkCallbackInner): cb is StkCallbackSuccess;
+/**
+ * Extracts a named value from a successful callback's metadata items.
+ * Returns undefined if the key is absent or the callback failed.
+ */
+declare function getCallbackValue(callback: StkPushCallback, name: StkCallbackMetadataItem["Name"]): string | number | undefined;
+
+/**
+ * Shared phone number utilities for M-Pesa API calls.
+ *
+ * Two formatters are intentionally separate:
+ *  - formatSafaricomPhone  → strict, for STK Push (only Safaricom/Airtel)
+ *  - formatKenyanMsisdn    → permissive, for C2B simulate and B2C PartyB
+ *
+ * Daraja consistently expects 12-digit MSISDN without the '+' prefix.
+ */
+/**
+ * Strict formatter for STK Push.
+ * Accepts Safaricom (2547xx) and Airtel Kenya (2541x) numbers only.
+ * Throws a clear error on invalid input so Daraja never receives a bad MSISDN.
+ */
+declare function formatSafaricomPhone(phone: string): string;
+/**
+ * Permissive formatter for C2B simulate and B2C PartyB.
+ * Accepts any valid 12-digit Kenyan MSISDN (Safaricom, Airtel, Telkom, …).
+ * Still throws if the result is structurally impossible.
+ */
+declare function formatKenyanMsisdn(phone: string): string;
+/**
+ * Converts a formatted MSISDN string to the numeric form Daraja expects in
+ * C2B simulate requests ("Msisdn": 254708374149 — no quotes in the JSON).
+ */
+declare function msisdnToNumber(phone: string): number;
+
+/**
+ * STK Push utilities
+ *
+ * Phone formatting delegates to the shared `formatSafaricomPhone` util which
+ * validates Safaricom/Airtel numbers and throws a clear error on bad input.
+ */
+
+/**
+ * Generates a Daraja-compatible timestamp: YYYYMMDDHHmmss
+ * Call this once per request and reuse the value.
+ */
+declare function getTimestamp(): string;
 
 type Environment = "sandbox" | "production";
 declare const DARAJA_BASE_URLS: {
@@ -560,4 +628,4 @@ declare class PesafyError extends Error {
 }
 declare function createError(options: PesafyErrorOptions): PesafyError;
 
-export { type B2BRequest, type B2BResponse, type B2CRequest, type B2CResponse, type B2CWebhook, type C2BCallbackPayload, type C2BCommandId, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BRejectionCode, type C2BResponseType, type C2BSimulateRequest, type C2BSimulateResponse, type C2BValidationResponse, type C2BWebhook, C2B_REJECTION_CODES, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type ErrorCode, Mpesa, type MpesaConfig, type MpesaExpressConfig, PesafyError, type RetryOptions, type RetryResult, type ReversalRequest, type ReversalResponse, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, TokenManager, type TransactionStatusRequest, type TransactionStatusResponse, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, createError, createMpesaExpressClient, createMpesaExpressRouter, encryptSecurityCredential, extractAmount, extractTransactionId, handleWebhook, retryWithBackoff, verifyWebhookIP };
+export { type B2BRequest, type B2BResponse, type B2CRequest, type B2CResponse, type B2CWebhook, type C2BCallbackPayload, type C2BCallbackPayloadBase, type C2BCommandId, type C2BConfirmationPayload, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BRejectionCode, type C2BSimulateRequest, type C2BSimulateResponse, type C2BValidationPayload, type C2BWebhook, C2B_REJECTION_CODES, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type ErrorCode, Mpesa, type MpesaConfig, type MpesaExpressConfig, PesafyError, type RetryOptions, type RetryResult, type ReversalRequest, type ReversalResponse, type StkCallbackFailure, type StkCallbackInner, type StkCallbackMetadataItem, type StkCallbackSuccess, type StkPushCallback, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, TokenManager, type TransactionStatusRequest, type TransactionStatusResponse, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, createError, createMpesaExpressClient, createMpesaExpressRouter, encryptSecurityCredential, extractAmount, extractTransactionId, formatKenyanMsisdn, formatSafaricomPhone as formatPhoneNumber, formatSafaricomPhone, getCallbackValue, getTimestamp, handleWebhook, isStkCallbackSuccess, msisdnToNumber, retryWithBackoff, verifyWebhookIP };