pesafy 0.0.2

package/dist/types.d.ts

@@ -0,0 +1,1259 @@
+//#region src/core/idempotency/store.d.ts
+/**
+ * In-memory idempotency store (per-process).
+ * For multi-instance deployments, supply a custom IdempotencyStore (e.g. Redis).
+ */
+interface IdempotencyEntry {
+  key: string;
+  createdAt: number;
+  completedAt?: number;
+}
+interface IdempotencyStore {
+  get(key: string): IdempotencyEntry | undefined;
+  set(key: string, entry: IdempotencyEntry): void;
+  delete(key: string): void;
+}
+//#endregion
+//#region src/core/idempotency/manager.d.ts
+interface IdempotencyConfig {
+  /** Default true for mutating POSTs */
+  enabled?: boolean;
+  /** HTTP header name. Default: Idempotency-Key */
+  headerName?: string;
+  /** Pluggable store; default in-memory */
+  store?: IdempotencyStore;
+  /** Dedup window in ms. Default: 24h */
+  ttlMs?: number;
+  /** Custom key generator */
+  generateKey?: () => string;
+}
+declare class IdempotencyManager {
+  readonly enabled: boolean;
+  readonly headerName: string;
+  readonly ttlMs: number;
+  private readonly store;
+  private readonly generateKey;
+  constructor(config?: IdempotencyConfig);
+  /**
+   * Reserve an idempotency key before the HTTP call.
+   * @throws PesafyError with IDEMPOTENCY_ERROR if duplicate in-flight/completed within TTL.
+   */
+  reserve(key?: string): string;
+  /** Mark key as successfully completed. */
+  complete(key: string): void;
+  /** Release reservation on failure so callers can retry with same key. */
+  release(key: string): void;
+  private pruneExpired;
+}
+//#endregion
+//#region src/mpesa/transaction-status/types.d.ts
+/**
+ * Transaction Status Query types
+ *
+ * API: POST /mpesa/transactionstatus/v1/query
+ *
+ * Daraja request body (from official documentation):
+ * {
+ *   "Initiator":                "",
+ *   "SecurityCredential":       "",
+ *   "CommandID":                "TransactionStatusQuery",
+ *   "TransactionID":            "",
+ *   "OriginalConversationID":   "",
+ *   "PartyA":                   "",
+ *   "IdentifierType":           "",
+ *   "ResultURL":                "",
+ *   "QueueTimeOutURL":          "",
+ *   "Remarks":                  "",
+ *   "Occasion":                 ""
+ * }
+ *
+ * NOTE: This is an ASYNCHRONOUS API.
+ * The synchronous response only confirms Safaricom received the request.
+ * The actual transaction details arrive later via POST to your ResultURL.
+ *
+ * Reconciliation: Either transactionId OR originalConversationId is required.
+ */
+interface TransactionStatusRequest {
+  /**
+   * M-Pesa transaction ID to look up (M-Pesa Receipt Number).
+   * Either transactionId OR originalConversationId is required.
+   * Daraja field: TransactionID
+   * Example: "NEF61H8J60"
+   */
+  transactionId?: string;
+  /**
+   * The Originator Conversation ID of the transaction whose status is being
+   * checked. Either transactionId OR originalConversationId is required.
+   * Use this when you have a ConversationID from the original API response
+   * but no M-Pesa receipt number.
+   * Daraja field: OriginalConversationID
+   * Example: "7071-4170-a0e5-8345632bad4421"
+   */
+  originalConversationId?: string;
+  /**
+   * Organization/MSISDN receiving the transaction.
+   * Usually your business shortcode.
+   * Daraja field: PartyA
+   */
+  partyA: string;
+  /**
+   * Type of the partyA identifier.
+   *   "1" = MSISDN
+   *   "2" = Till Number (Buy Goods)
+   *   "4" = Organisation ShortCode (Paybill / B2C) ← most common
+   * Daraja field: IdentifierType
+   */
+  identifierType: '1' | '2' | '4';
+  /**
+   * URL where Safaricom POSTs the final result.
+   * Must be publicly accessible.
+   * Daraja field: ResultURL
+   */
+  resultUrl: string;
+  /**
+   * URL Safaricom calls when the request times out in the queue.
+   * Must be publicly accessible.
+   * Daraja field: QueueTimeOutURL
+   */
+  queueTimeOutUrl: string;
+  /**
+   * CommandID — always "TransactionStatusQuery".
+   * Defaults to "TransactionStatusQuery" if omitted.
+   */
+  commandId?: 'TransactionStatusQuery';
+  /** Optional remarks (up to 100 characters) */
+  remarks?: string;
+  /** Optional occasion / reference (up to 100 characters) */
+  occasion?: string;
+}
+interface TransactionStatusResponse {
+  /** Unique request ID for tracking */
+  OriginatorConversationID: string;
+  /** Unique request ID returned by M-PESA */
+  ConversationID: string;
+  /** "0" = request accepted */
+  ResponseCode: string;
+  ResponseDescription: string;
+}
+/**
+ * Documented result parameter keys for the Transaction Status callback.
+ * @see Daraja Transaction Status result documentation
+ */
+type TransactionStatusResultParameterKey = 'DebitPartyName' | 'TransactionStatus' | 'Amount' | 'ReceiptNo' | 'DebitAccountBalance' | 'TransactionDate' | 'CreditPartyName';
+interface TransactionStatusResultParameter {
+  Key: TransactionStatusResultParameterKey | string;
+  Value: string | number;
+}
+interface TransactionStatusResult {
+  Result: {
+    /** 0 = completed, 1 = waiting for further messages */ResultType: number | string; /** 0 = success */
+    ResultCode: number | string; /** Human-readable description of the result */
+    ResultDesc: string;
+    OriginatorConversationID: string;
+    ConversationID: string;
+    TransactionID: string;
+    ResultParameters?: {
+      ResultParameter: TransactionStatusResultParameter | TransactionStatusResultParameter[];
+    };
+    ReferenceData?: {
+      ReferenceItem: {
+        Key: string;
+        Value?: string;
+      } | Array<{
+        Key: string;
+        Value?: string;
+      }>;
+    };
+  };
+}
+//#endregion
+//#region src/mpesa/types.d.ts
+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;
+  /** Automatic Idempotency-Key headers and duplicate detection */
+  idempotency?: IdempotencyConfig;
+  webhooks?: {
+    allowedIPs?: readonly string[]; /** HMAC secret when Safaricom ships signature support */
+    secret?: string; /** Signature header name (placeholder until official docs) */
+    signatureHeader?: string; /** Fail closed if HMAC required but missing. Default false */
+    requireHMAC?: boolean;
+  };
+}
+//#endregion
+//#region src/mpesa/account-balance/types.d.ts
+interface AccountBalanceRequest {
+  /**
+   * Your business shortcode from which balance is queried.
+   * Daraja field: PartyA (Numeric)
+   * Example: "600000"
+   */
+  partyA: string;
+  /**
+   * Type of the PartyA identifier.
+   *   "1" = MSISDN
+   *   "2" = Till Number
+   *   "4" = Organisation ShortCode (most common — Paybill/B2C/Buy Goods)
+   * Daraja field: IdentifierType (Numeric)
+   * Sample: 4
+   */
+  identifierType: '1' | '2' | '4';
+  /**
+   * URL where Safaricom POSTs the balance result (async callback).
+   * Must be publicly accessible. HTTPS required in production.
+   * Daraja field: ResultURL (URL)
+   * Sample: https://ip:port/path or domain:port/path
+   */
+  resultUrl: string;
+  /**
+   * URL Safaricom calls when the request times out.
+   * Daraja field: QueueTimeOutURL (URL)
+   * Sample: https://ip:port/path or domain:port/path
+   */
+  queueTimeOutUrl: string;
+  /**
+   * Comments sent along with the transaction (up to 100 characters).
+   * Daraja field: Remarks (String)
+   * Sample: ok
+   */
+  remarks?: string;
+}
+/**
+ * Synchronous response from Daraja confirming the request was received.
+ * This is NOT the balance data — balance arrives via async callback to ResultURL.
+ *
+ * ResponseCode "0" = request accepted for processing.
+ */
+interface AccountBalanceResponse {
+  /** Unique identifier of the request. Auto-generated by M-PESA. */
+  OriginatorConversationID: string;
+  /** Unique identifier generated by M-PESA for this request */
+  ConversationID: string;
+  /** "0" = request accepted by Mobile Money */
+  ResponseCode: string;
+  /** Description of the ResponseCode */
+  ResponseDescription: string;
+}
+/**
+ * AccountBalance result parameter key names as documented by Daraja.
+ */
+type AccountBalanceResultParameterKey = 'AccountBalance' | 'BOCompletedTime';
+/**
+ * A single result parameter entry from the Daraja callback.
+ */
+interface AccountBalanceResultParameter {
+  Key: AccountBalanceResultParameterKey | string;
+  Value: string | number;
+}
+/**
+ * The ReferenceItem from the async callback.
+ * Key is typically "QueueTimeoutURL" as documented.
+ */
+interface AccountBalanceReferenceItem {
+  Key: string;
+  Value: string;
+}
+/**
+ * Full async callback payload POSTed to your ResultURL after processing.
+ *
+ * ResultCode 0 = success; non-zero = failure.
+ *
+ * ResultParameters.ResultParameter contains:
+ *   - AccountBalance: pipe-delimited balance string for all accounts
+ *   - BOCompletedTime: completion timestamp (format: YYYYMMDDHHmmss)
+ *
+ * Ref: Callback Result Payload — Daraja Account Balance docs
+ */
+interface AccountBalanceResult {
+  Result: {
+    /**
+     * ResultType:
+     *   "0" = completed
+     *   "1" = waiting for further messages
+     */
+    ResultType: string | number;
+    /**
+     * Result code indicating success or failure.
+     * 0 = success; see ACCOUNT_BALANCE_ERROR_CODES for failure codes.
+     * Note: Daraja may return this as string "0" or number 0 on success.
+     */
+    ResultCode: number | string; /** Human-readable description of the result */
+    ResultDesc: string; /** Unique identifier from the original request */
+    OriginatorConversationID: string; /** Unique identifier generated by M-PESA */
+    ConversationID: string; /** M-PESA transaction identifier */
+    TransactionID: string; /** Balance data — only present on success (ResultCode 0) */
+    ResultParameters?: {
+      /**
+       * Can be an array (multiple params) or a single object (Daraja inconsistency).
+       * Use getAccountBalanceParam() to handle both forms safely.
+       */
+      ResultParameter: AccountBalanceResultParameter[] | AccountBalanceResultParameter;
+    }; /** Reference data Daraja records in transaction logs */
+    ReferenceData?: {
+      ReferenceItem: AccountBalanceReferenceItem | AccountBalanceReferenceItem[];
+    };
+  };
+}
+//#endregion
+//#region src/mpesa/b2b-express-checkout/types.d.ts
+/**
+ * src/mpesa/b2b-express-checkout/types.ts
+ *
+ * B2B Express Checkout (USSD Push to Till) type definitions.
+ * Strictly aligned with Safaricom Daraja B2B Express Checkout API documentation.
+ *
+ * Endpoint: POST https://sandbox.safaricom.co.ke/v1/ussdpush/get-msisdn
+ *
+ * Flow:
+ *   1. Vendor initiates USSD push via Daraja
+ *   2. Merchant receives USSD prompt on their till
+ *   3. Merchant enters Operator ID + M-PESA PIN
+ *   4. M-PESA debits merchant, credits vendor
+ *   5. Daraja POSTs callback to your callbackUrl
+ */
+/**
+ * Request payload for B2B Express Checkout USSD Push.
+ *
+ * Daraja payload shape (all field names are camelCase except RequestRefID):
+ * {
+ *   "primaryShortCode": "000001",
+ *   "receiverShortCode": "000002",
+ *   "amount":            "100",          ← sent as string per Daraja spec
+ *   "paymentRef":        "paymentRef",
+ *   "callbackUrl":       "https://...",
+ *   "partnerName":       "Vendor",
+ *   "RequestRefID":      "uuid"          ← PascalCase per Daraja spec
+ * }
+ */
+interface B2BExpressCheckoutRequest {
+  /**
+   * Debit party — the merchant's till number that will be charged.
+   * Daraja field: primaryShortCode
+   */
+  primaryShortCode: string;
+  /**
+   * Credit party — the vendor's Paybill account that will receive funds.
+   * Daraja field: receiverShortCode
+   */
+  receiverShortCode: string;
+  /**
+   * Amount to send. Must be a whole number ≥ 1.
+   * Sent as a string in the Daraja payload (e.g. "100").
+   * Daraja field: amount
+   */
+  amount: number;
+  /**
+   * Payment reference shown in the merchant's USSD prompt.
+   * Daraja field: paymentRef
+   */
+  paymentRef: string;
+  /**
+   * Publicly accessible URL where Daraja POSTs the transaction result.
+   * Daraja field: callbackUrl
+   */
+  callbackUrl: string;
+  /**
+   * Vendor's friendly name shown in the merchant's USSD prompt:
+   * "You are about to send Ksh {{amount}} to {{partnerName}}..."
+   * Daraja field: partnerName
+   */
+  partnerName: string;
+  /**
+   * Unique identifier for this request — used for idempotency.
+   * Auto-generated (UUID v4) if not provided.
+   * Daraja field: RequestRefID (PascalCase per Daraja spec)
+   */
+  requestRefId?: string;
+}
+/**
+ * Synchronous acknowledgement returned immediately by Daraja.
+ *
+ * Daraja response shape:
+ * {
+ *   "code":   "0",
+ *   "status": "USSD Initiated Successfully"
+ * }
+ *
+ * code "0" means the USSD push was initiated. The actual transaction result
+ * comes later via the callbackUrl.
+ */
+interface B2BExpressCheckoutResponse {
+  /** "0" = USSD push initiated successfully */
+  code: string;
+  /** Human-readable status, e.g. "USSD Initiated Successfully" */
+  status: string;
+}
+/**
+ * Callback when the merchant CANCELLED the USSD prompt.
+ *
+ * Daraja callback shape:
+ * {
+ *   "resultCode":       "4001",
+ *   "resultDesc":       "User cancelled transaction",
+ *   "requestId":        "c2a9ba32-9e11-4b90-892c-7bc54944609a",
+ *   "amount":           "71.0",
+ *   "paymentReference": "MAndbubry3hi"
+ * }
+ */
+interface B2BExpressCheckoutCallbackCancelled {
+  /** "4001" for user cancellation */
+  resultCode: string;
+  resultDesc: string;
+  requestId: string;
+  /** Amount as a string, e.g. "71.0" */
+  amount: string;
+  /** The payment reference from the original request */
+  paymentReference: string;
+}
+/**
+ * Callback when the M-PESA transaction SUCCEEDED.
+ *
+ * Daraja callback shape:
+ * {
+ *   "resultCode":    "0",
+ *   "resultDesc":    "The service request is processed successfully.",
+ *   "amount":        "71.0",
+ *   "requestId":     "404e1aec-19e0-4ce3-973d-bd92e94c8021",
+ *   "resultType":    "0",
+ *   "conversationID":"AG_20230426_2010434680d9f5a73766",
+ *   "transactionId": "RDQ01NFT1Q",
+ *   "status":        "SUCCESS"
+ * }
+ */
+interface B2BExpressCheckoutCallbackSuccess {
+  /** "0" */
+  resultCode: string;
+  resultDesc: string;
+  /** Amount as a string, e.g. "71.0" */
+  amount: string;
+  requestId: string;
+  /** Usually "0" */
+  resultType: string;
+  /** M-PESA conversation ID, e.g. "AG_20230426_..." */
+  conversationID: string;
+  /** M-PESA receipt number, e.g. "RDQ01NFT1Q" */
+  transactionId: string;
+  /** "SUCCESS" */
+  status: string;
+}
+/**
+ * Callback for any non-zero, non-cancelled failure
+ * (e.g. KYC failure, USSD network error, missing nominated number).
+ *
+ * Error codes documented by Daraja:
+ *   4102 — Merchant KYC failure
+ *   4104 — Missing nominated number
+ *   4201 — USSD network error
+ *   4203 — USSD exception error
+ */
+interface B2BExpressCheckoutCallbackFailed {
+  resultCode: string;
+  resultDesc: string;
+  requestId: string;
+  amount: string;
+}
+/**
+ * Union of all possible callback payload shapes.
+ * Discriminate on `resultCode`:
+ *   "0"    → B2BExpressCheckoutCallbackSuccess
+ *   "4001" → B2BExpressCheckoutCallbackCancelled
+ *   other  → B2BExpressCheckoutCallbackFailed
+ */
+type B2BExpressCheckoutCallback = B2BExpressCheckoutCallbackSuccess | B2BExpressCheckoutCallbackCancelled | B2BExpressCheckoutCallbackFailed;
+//#endregion
+//#region src/mpesa/b2c/types.d.ts
+/**
+ * src/mpesa/b2c/types.ts
+ *
+ * Strictly aligned with Safaricom Daraja B2C Account Top Up API documentation.
+ * Endpoint: POST /mpesa/b2b/v1/paymentrequest
+ *
+ * Only CommandID = "BusinessPayToBulk" is documented and supported.
+ * SenderIdentifierType and RecieverIdentifierType are always "4" per docs.
+ */
+/**
+ * The only CommandID supported by the B2C Account Top Up API.
+ * Docs: "Use BusinessPayToBulk only"
+ */
+type B2CCommandID = 'BusinessPayToBulk';
+interface B2CRequest {
+  /**
+   * Transaction type. Must be "BusinessPayToBulk".
+   * Daraja field: CommandID
+   */
+  commandId: B2CCommandID;
+  /**
+   * Transaction amount in KES. Must be a whole number ≥ 1.
+   * Daraja field: Amount (sent as string per API spec)
+   */
+  amount: number;
+  /**
+   * Sender shortcode — the originating business shortcode.
+   * Daraja field: PartyA
+   * SenderIdentifierType is always "4" (Organisation ShortCode) per docs.
+   */
+  partyA: string;
+  /**
+   * Receiver shortcode — the B2C shortcode that receives the funds.
+   * Daraja field: PartyB
+   * RecieverIdentifierType is always "4" (Organisation ShortCode) per docs.
+   */
+  partyB: string;
+  /**
+   * Account reference for the transaction (e.g. invoice or batch number).
+   * Daraja field: AccountReference
+   */
+  accountReference: string;
+  /**
+   * Optional. Customer phone number on whose behalf the transfer is made.
+   * Format: 254XXXXXXXXX
+   * Daraja field: Requester
+   */
+  requester?: string;
+  /**
+   * Additional remarks for the transaction. Up to 100 characters.
+   * Daraja field: Remarks
+   */
+  remarks?: string;
+  /**
+   * URL Safaricom calls with the final async result after processing.
+   * Must be publicly accessible. HTTPS required in production.
+   * Daraja field: ResultURL
+   */
+  resultUrl: string;
+  /**
+   * URL Safaricom calls when the request times out in the queue.
+   * Must be publicly accessible. HTTPS required in production.
+   * Daraja field: QueueTimeOutURL
+   */
+  queueTimeOutUrl: string;
+}
+interface B2CResponse {
+  /**
+   * Unique request identifier assigned by Daraja upon successful submission.
+   * Daraja field: OriginatorConversationID
+   */
+  OriginatorConversationID: string;
+  /**
+   * Unique request identifier assigned by M-Pesa.
+   * Daraja field: ConversationID
+   */
+  ConversationID: string;
+  /**
+   * "0" indicates the request was accepted for processing.
+   * Daraja field: ResponseCode
+   */
+  ResponseCode: string;
+  /**
+   * Human-readable submission status description.
+   * Daraja field: ResponseDescription
+   */
+  ResponseDescription: string;
+}
+/**
+ * Documented result parameter keys for B2C Account Top Up transactions.
+ * Source: Safaricom Daraja B2C Account Top Up — Successful Result Parameters.
+ *
+ * `(string & {})` is used as a catch-all so:
+ *   - Named literals appear in IntelliSense/autocomplete.
+ *   - Future undocumented keys from Daraja are still accepted at runtime.
+ */
+type B2CResultParameterKey = 'DebitAccountBalance' | 'Amount' | 'Currency' | 'ReceiverPartyPublicName' | 'TransactionCompletedTime' | 'DebitPartyCharges' | (string & {});
+interface B2CResultParameter {
+  Key: B2CResultParameterKey;
+  Value: string | number;
+}
+interface B2CResult {
+  Result: {
+    /**
+     * Usually "0" for success. Docs show "0" (string) on success,
+     * numeric (e.g. 2001) on failure — typed as both for safety.
+     */
+    ResultType: string | number;
+    /**
+     * "0" or 0 = success; non-zero = failure.
+     * Docs show string "0" on success, number 2001 on failure.
+     */
+    ResultCode: string | number; /** Human-readable result description */
+    ResultDesc: string;
+    OriginatorConversationID: string;
+    ConversationID: string;
+    TransactionID: string;
+    ResultParameters?: {
+      ResultParameter: B2CResultParameter | B2CResultParameter[];
+    };
+    ReferenceData?: {
+      ReferenceItem: {
+        Key: string;
+        Value?: string;
+      } | Array<{
+        Key: string;
+        Value?: string;
+      }>;
+    };
+  };
+}
+//#endregion
+//#region src/mpesa/b2c-disbursement/types.d.ts
+/**
+ * src/mpesa/b2c-disbursement/types.ts
+
+// ── Command IDs ───────────────────────────────────────────────────────────────
+
+/**
+ * Supported CommandIDs for B2C Disbursement.
+ * Source: Safaricom Daraja B2C API documentation.
+ */
+type B2CDisbursementCommandID = 'BusinessPayment' | 'SalaryPayment' | 'PromotionPayment';
+interface B2CDisbursementRequest {
+  /**
+   * Unique request ID from the merchant.
+   * Daraja field: OriginatorConversationID
+   */
+  /** Auto-generated when omitted (via Mpesa client idempotency helper). */
+  originatorConversationId?: string;
+  /**
+   * Transaction type.
+   * Daraja field: CommandID
+   */
+  commandId: B2CDisbursementCommandID;
+  /**
+   * Transaction amount in KES.
+   * Daraja field: Amount
+   */
+  amount: number;
+  /**
+   * Sending organisation shortcode.
+   * Daraja field: PartyA
+   */
+  partyA: string;
+  /**
+   * Receiving customer MSISDN (2547XXXXXXXX).
+   * Daraja field: PartyB
+   */
+  partyB: string;
+  /**
+   * Additional transaction info (2–100 characters).
+   * Daraja field: Remarks
+   */
+  remarks: string;
+  /**
+   * URL Safaricom calls with the async result.
+   * Daraja field: ResultURL
+   */
+  resultUrl: string;
+  /**
+   * URL Safaricom calls on queue timeout.
+   * Daraja field: QueueTimeOutURL
+   */
+  queueTimeOutUrl: string;
+  /**
+   * Optional additional info.
+   * Daraja field: Occassion (sic — preserved from Daraja docs)
+   */
+  occasion?: string;
+}
+interface B2CDisbursementResponse {
+  /** Unique request ID assigned by M-Pesa */
+  ConversationID: string;
+  /** Merchant-supplied request ID echoed back */
+  OriginatorConversationID: string;
+  /** "0" = accepted */
+  ResponseCode: string;
+  /** Human-readable submission status */
+  ResponseDescription: string;
+}
+interface B2CDisbursementResultParameter {
+  Key: B2CDisbursementResultParameterKey;
+  Value: string | number;
+}
+/**
+ * Known result parameter keys from Daraja B2C success callback.
+ */
+type B2CDisbursementResultParameterKey = 'TransactionAmount' | 'TransactionReceipt' | 'ReceiverPartyPublicName' | 'TransactionCompletedDateTime' | 'B2CUtilityAccountAvailableFunds' | 'B2CWorkingAccountAvailableFunds' | 'B2CRecipientIsRegisteredCustomer' | 'B2CChargesPaidAccountAvailableFunds' | (string & {});
+interface B2CDisbursementResult {
+  Result: {
+    ResultType: number;
+    ResultCode: number | string;
+    ResultDesc: string;
+    OriginatorConversationID: string;
+    ConversationID: string;
+    TransactionID: string;
+    ResultParameters?: {
+      ResultParameter: B2CDisbursementResultParameter | B2CDisbursementResultParameter[];
+    };
+    ReferenceData?: {
+      ReferenceItem: {
+        Key: string;
+        Value?: string;
+      } | Array<{
+        Key: string;
+        Value?: string;
+      }>;
+    };
+  };
+}
+//#endregion
+//#region src/mpesa/c2b/types.d.ts
+/**
+ * src/mpesa/c2b/types.ts
+ *
+ * Customer to Business (C2B) type definitions.
+ * Strictly aligned with Safaricom Daraja C2B Register URL API documentation.
+ *
+ * Docs: https://developer.safaricom.co.ke/APIs/CustomerToBusinessRegisterURL
+ */
+type C2BApiVersion = 'v1' | 'v2';
+/**
+ * ResponseType for Register URL.
+ *
+ * Determines what M-PESA does when the Validation URL is unreachable.
+ *
+ * IMPORTANT (per docs): Must be sentence case — "Completed" or "Cancelled".
+ *   ✓ "Completed"  ✗ "COMPLETED"  ✗ "completed"
+ *   ✓ "Cancelled"  ✗ "CANCELLED"  ✗ "cancelled"
+ */
+type C2BResponseType = 'Completed' | 'Cancelled';
+/**
+ * Request body for C2B Register URL API.
+ *
+ * Daraja payload shape (v1):
+ * {
+ *   "ShortCode":        "601426",
+ *   "ResponseType":     "Completed",
+ *   "ConfirmationURL":  "https://yourdomain.com/confirm",
+ *   "ValidationURL":    "https://yourdomain.com/validate"
+ * }
+ */
+interface C2BRegisterUrlRequest {
+  /** Paybill or Till shortcode */
+  shortCode: string;
+  /**
+   * Default action when Validation URL is unreachable.
+   * Must be sentence-case: "Completed" or "Cancelled".
+   * Per docs: "The words Cancelled and Completed must be in Sentence case."
+   */
+  responseType: C2BResponseType;
+  /**
+   * URL that receives the confirmation callback after payment completes.
+   * Must be publicly accessible and internet-reachable.
+   * Production requires HTTPS; Sandbox allows HTTP.
+   */
+  confirmationUrl: string;
+  /**
+   * URL that receives the validation callback before payment completes.
+   * Only called when external validation is enabled on the shortcode.
+   * To enable external validation, email apisupport@safaricom.co.ke.
+   */
+  validationUrl: string;
+  /** API version to use — defaults to "v1" (documented endpoint) */
+  apiVersion?: C2BApiVersion;
+}
+/**
+ * Shared Daraja C2B response fields (Register URL, Simulate, etc.).
+ *
+ * Note: "OriginatorCoversationID" — Daraja spells "Conversation" as
+ * "Coversation" in the actual API response. We preserve the typo to
+ * match the real payload.
+ */
+interface C2BBaseResponse {
+  /** Global unique identifier for this request (note Daraja's spelling typo) */
+  OriginatorCoversationID: string;
+  /** "0" = success */
+  ResponseCode: string;
+  ResponseDescription: string;
+}
+/**
+ * Response from C2B Register URL API.
+ */
+interface C2BRegisterUrlResponse extends C2BBaseResponse {}
+/**
+ * CommandID for C2B simulation.
+ *
+ * "CustomerPayBillOnline" — payment to a Paybill number
+ * "CustomerBuyGoodsOnline" — payment to a Till number
+ */
+type C2BCommandID = 'CustomerPayBillOnline' | 'CustomerBuyGoodsOnline';
+/**
+ * Request body for C2B Simulate API (Sandbox only).
+ *
+ * Daraja payload shape:
+ * {
+ *   "ShortCode":      600984,          ← numeric
+ *   "CommandID":      "CustomerPayBillOnline",
+ *   "Amount":         1,               ← numeric, whole number
+ *   "Msisdn":         254708374149,    ← numeric
+ *   "BillRefNumber":  "TestRef"        ← omit entirely for CustomerBuyGoodsOnline
+ * }
+ */
+interface C2BSimulateRequest {
+  /** Paybill or Till shortcode — sent as a number in the payload */
+  shortCode: string | number;
+  /** Transaction type — Paybill or BuyGoods */
+  commandId: C2BCommandID;
+  /** Amount in KES — whole numbers only; fractional values are rounded */
+  amount: number;
+  /** Sender MSISDN. Sandbox test number: 254708374149 */
+  msisdn: string | number;
+  /**
+   * Account reference for Paybill payments.
+   * MUST be omitted (not null, not "") for CustomerBuyGoodsOnline.
+   * Per docs: "null for customer buy goods"
+   */
+  billRefNumber?: string | null;
+  /** API version to use — defaults to "v2" */
+  apiVersion?: C2BApiVersion;
+}
+/** Response from C2B Simulate API. */
+interface C2BSimulateResponse extends C2BBaseResponse {}
+/**
+ * Payload POSTed to your ValidationURL by M-PESA.
+ *
+ * Only received when external validation is enabled on the shortcode.
+ * OrgAccountBalance is BLANK for validation requests.
+ *
+ * Sample from Daraja docs:
+ * {
+ *   "TransactionType": "Pay Bill",
+ *   "TransID":         "RKTQDM7W6S",
+ *   "TransTime":       "20191122063845",
+ *   "TransAmount":     "10",
+ *   "BusinessShortCode": "600638",
+ *   "BillRefNumber":   "invoice008",
+ *   "InvoiceNumber":   "",
+ *   "OrgAccountBalance": "",
+ *   "ThirdPartyTransID": "",
+ *   "MSISDN":          "25470****149",
+ *   "FirstName":       "John",
+ *   "MiddleName":      "",
+ *   "LastName":        "Doe"
+ * }
+ */
+interface C2BValidationPayload {
+  /**
+   * Transaction type as received from M-PESA.
+   * Per docs: "Pay Bill" or "Buy Goods"
+   * (NOT the CommandID strings "CustomerPayBillOnline" / "CustomerBuyGoodsOnline")
+   */
+  TransactionType: string;
+  /** Unique M-PESA transaction ID */
+  TransID: string;
+  /** Transaction timestamp: YYYYMMDDHHmmss */
+  TransTime: string;
+  /**
+   * Amount the customer is paying.
+   * Per docs: whole numbers only.
+   */
+  TransAmount: string;
+  /** Your shortcode (5–6 digits) */
+  BusinessShortCode: string;
+  /** Account reference (Paybill only) — up to 20 alphanumeric chars */
+  BillRefNumber: string;
+  /** Invoice number — usually empty */
+  InvoiceNumber: string;
+  /**
+   * Blank for validation requests per docs.
+   * Contains new balance after payment for confirmation requests.
+   */
+  OrgAccountBalance: string;
+  /** Third-party transaction ID. Can echo back in your validation response. */
+  ThirdPartyTransID: string;
+  /**
+   * Masked mobile number of the customer.
+   * Format example from docs: "25470****149"
+   */
+  MSISDN: string;
+  FirstName: string;
+  MiddleName: string;
+  LastName: string;
+}
+/**
+ * Result codes for validation response.
+ *
+ * Per Daraja documentation:
+ *   "0"        → Accept the payment
+ *   "C2B00011" → Invalid MSISDN
+ *   "C2B00012" → Invalid Account Number
+ *   "C2B00013" → Invalid Amount
+ *   "C2B00014" → Invalid KYC Details
+ *   "C2B00015" → Invalid Shortcode
+ *   "C2B00016" → Other Error
+ */
+type C2BValidationResultCode = '0' | 'C2B00011' | 'C2B00012' | 'C2B00013' | 'C2B00014' | 'C2B00015' | 'C2B00016';
+/**
+ * Response your ValidationURL must return to M-PESA.
+ *
+ * To accept (per docs):
+ *   { "ResultCode": "0",        "ResultDesc": "Accepted" }
+ *
+ * To reject (per docs):
+ *   { "ResultCode": "C2B00011", "ResultDesc": "Rejected" }
+ *
+ * Per docs, you can also echo back ThirdPartyTransID.
+ */
+interface C2BValidationResponse {
+  /** "0" to accept; any C2B error code to reject */
+  ResultCode: C2BValidationResultCode;
+  /** "Accepted" or "Rejected" */
+  ResultDesc: 'Accepted' | 'Rejected';
+  /**
+   * Optional — echo back the ThirdPartyTransID from the validation request.
+   * M-PESA will include it in the subsequent confirmation callback.
+   */
+  ThirdPartyTransID?: string;
+}
+/**
+ * Payload POSTed to your ConfirmationURL by M-PESA after payment completes.
+ *
+ * OrgAccountBalance contains the NEW balance after this payment.
+ * This payload is only sent when the transaction completes successfully.
+ *
+ * Per docs process flow:
+ * - External Validation ON: sent after validation succeeds
+ * - External Validation OFF: sent automatically after every completed payment
+ */
+interface C2BConfirmationPayload {
+  /**
+   * Transaction type as received from M-PESA.
+   * Per docs: "Pay Bill" or "Buy Goods"
+   */
+  TransactionType: string;
+  /** Unique M-PESA transaction ID */
+  TransID: string;
+  /** Transaction timestamp: YYYYMMDDHHmmss */
+  TransTime: string;
+  /** Amount transacted — whole numbers only per docs */
+  TransAmount: string;
+  /** Your shortcode (5–6 digits) */
+  BusinessShortCode: string;
+  /** Account reference (Paybill only) */
+  BillRefNumber: string;
+  /** Invoice number — usually empty */
+  InvoiceNumber: string;
+  /**
+   * New utility account balance after this payment.
+   * Blank for validation requests; populated in confirmation.
+   */
+  OrgAccountBalance: string;
+  /** Third-party transaction ID (echoed from validation response if set) */
+  ThirdPartyTransID: string;
+  /** Masked mobile number — e.g. "25470****149" */
+  MSISDN: string;
+  FirstName: string;
+  MiddleName: string;
+  LastName: string;
+}
+//#endregion
+//#region src/mpesa/reversal/types.d.ts
+/**
+ * Keys present in the ResultParameters.ResultParameter array of a successful
+ * reversal callback, as documented by Daraja.
+ */
+type ReversalResultParameterKey = 'DebitAccountBalance' | 'Amount' | 'TransCompletedTime' | 'OriginalTransactionID' | 'Charge' | 'CreditPartyPublicName' | 'DebitPartyPublicName';
+/**
+ * Parameters for the Reversals API request.
+ *
+ * Daraja request body shape:
+ * ```json
+ * {
+ *   "Initiator":             "apiop37",
+ *   "SecurityCredential":    "RC6E9WDx9X2c6z3gp0oC5Th==",
+ *   "CommandID":             "TransactionReversal",
+ *   "TransactionID":         "PDU91HIVIT",
+ *   "Amount":                "200",
+ *   "ReceiverParty":         "603021",
+ *   "RecieverIdentifierType":"11",
+ *   "ResultURL":             "https://mydomain.com/reversal/result",
+ *   "QueueTimeOutURL":       "https://mydomain.com/reversal/queue",
+ *   "Remarks":               "Payment reversal"
+ * }
+ * ```
+ *
+ * Note: Initiator and SecurityCredential are supplied by the SDK layer;
+ * they are not part of this user-facing request interface.
+ */
+interface ReversalRequest {
+  /**
+   * The M-PESA receipt number of the transaction to reverse.
+   * Example: "PDU91HIVIT"
+   * Daraja field: TransactionID
+   */
+  transactionId: string;
+  /**
+   * Your organisation shortcode (Paybill or Till number).
+   * Daraja field: ReceiverParty
+   */
+  receiverParty: string;
+  /**
+   * Identifier type for ReceiverParty.
+   * Per Daraja docs: MUST be "11" (Organisation/ShortCode reversal type).
+   * This value is validated and always sent as "11".
+   * Daraja field: RecieverIdentifierType (note Daraja's spelling)
+   *
+   * @default "11"
+   */
+  receiverIdentifierType?: '11';
+  /**
+   * Amount to reverse. Must equal the original transaction amount.
+   * Must be a whole number ≥ 1.
+   * Daraja field: Amount (sent as string per Daraja docs sample)
+   */
+  amount: number;
+  /**
+   * URL where Safaricom POSTs the reversal result asynchronously.
+   * Must be publicly accessible over the internet.
+   * Daraja field: ResultURL
+   */
+  resultUrl: string;
+  /**
+   * URL called when the request times out in the Daraja queue.
+   * Must be publicly accessible over the internet.
+   * Daraja field: QueueTimeOutURL
+   */
+  queueTimeOutUrl: string;
+  /**
+   * Short description of the reversal reason (2–100 characters).
+   * Daraja field: Remarks
+   * @default "Transaction Reversal"
+   */
+  remarks?: string;
+  /**
+   * Optional occasion/reference string.
+   * Not in the Daraja sample payload but accepted by the API.
+   * Daraja field: Occasion
+   */
+  occasion?: string;
+}
+/**
+ * Synchronous response from the Reversals API.
+ *
+ * This is only an acknowledgement that the request was received.
+ * The actual reversal result arrives asynchronously at your ResultURL.
+ *
+ * Daraja response shape:
+ * ```json
+ * {
+ *   "OriginatorConversationID": "f1e2-4b95-a71d-b30d3cdbb7a7735297",
+ *   "ConversationID":           "AG_20210706_20106e9209f64bebd05b",
+ *   "ResponseCode":             "0",
+ *   "ResponseDescription":      "Accept the service request successfully."
+ * }
+ * ```
+ */
+interface ReversalResponse {
+  /** Unique identifier for this reversal request from M-PESA */
+  OriginatorConversationID: string;
+  /** Unique global identifier for the transaction request */
+  ConversationID: string;
+  /**
+   * "0" = request accepted successfully.
+   * Any other value = API-level error (not reversal failure).
+   */
+  ResponseCode: string;
+  /** Human-readable acknowledgement message */
+  ResponseDescription: string;
+}
+/**
+ * Result parameter item in a successful reversal callback.
+ */
+interface ReversalResultParameter {
+  Key: ReversalResultParameterKey;
+  Value: string | number;
+}
+/**
+ * Full async reversal result POSTed to your ResultURL after processing.
+ *
+ * Successful callback shape (per Daraja docs):
+ * ```json
+ * {
+ *   "Result": {
+ *     "ResultType": 0,
+ *     "ResultCode": 0,
+ *     "ResultDesc": "The service request is processed successfully.",
+ *     "OriginatorConversationID": "...",
+ *     "ConversationID": "AG_...",
+ *     "TransactionID": "SKE52PAWR9",
+ *     "ResultParameters": {
+ *       "ResultParameter": [
+ *         { "Key": "DebitAccountBalance",  "Value": "Utility Account|KES|..." },
+ *         { "Key": "Amount",               "Value": 1.00 },
+ *         { "Key": "TransCompletedTime",   "Value": 20211114132711 },
+ *         { "Key": "OriginalTransactionID","Value": "SKC82PACB8" },
+ *         { "Key": "Charge",               "Value": 0.00 },
+ *         { "Key": "CreditPartyPublicName","Value": "254705912645 - NICHOLAS JOHN SONGOK" },
+ *         { "Key": "DebitPartyPublicName", "Value": "600992 - Safaricom Daraja 992" }
+ *       ]
+ *     },
+ *     "ReferenceData": {
+ *       "ReferenceItem": {
+ *         "Key": "QueueTimeoutURL",
+ *         "Value": "https://..."
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Failed callback shape (per Daraja docs):
+ * ```json
+ * {
+ *   "Result": {
+ *     "ResultType": 0,
+ *     "ResultCode": "R000002",
+ *     "ResultDesc": "The OriginalTransactionID is invalid.",
+ *     ...
+ *   }
+ * }
+ * ```
+ *
+ * Note: ResultCode is 0 (number) on success and a string like "R000002" on failure.
+ */
+interface ReversalResult {
+  Result: {
+    /** Status type (usually 0) */ResultType: number;
+    /**
+     * 0 (number) = success.
+     * String codes like "R000002" = failure.
+     * See REVERSAL_RESULT_CODES for all documented values.
+     */
+    ResultCode: number | string; /** Human-readable result description */
+    ResultDesc: string; /** Unique identifier for the reversal request */
+    OriginatorConversationID: string; /** Unique identifier from M-PESA */
+    ConversationID: string; /** M-PESA receipt number for the reversal transaction */
+    TransactionID: string;
+    /**
+     * Present on success — contains transaction details.
+     * Absent on failure.
+     */
+    ResultParameters?: {
+      ResultParameter: ReversalResultParameter[];
+    };
+    ReferenceData?: {
+      ReferenceItem: {
+        Key: string;
+        Value: string;
+      } | Array<{
+        Key: string;
+        Value: string;
+      }>;
+    };
+  };
+}
+//#endregion
+//#region src/mpesa/tax-remittance/types.d.ts
+interface TaxRemittanceRequest {
+  /**
+   * The transaction amount to remit to KRA.
+   * Must be a whole number ≥ 1.
+   * Daraja field: Amount
+   */
+  amount: number;
+  /**
+   * Your own M-PESA business shortcode from which the money is deducted.
+   * Daraja field: PartyA
+   */
+  partyA: string;
+  /**
+   * The KRA account to which money is credited.
+   * For Tax Remittance, only "572572" is allowed.
+   * Defaults to KRA_SHORTCODE ("572572") when omitted.
+   * Daraja field: PartyB
+   */
+  partyB?: string;
+  /**
+   * The Payment Registration Number (PRN) issued by KRA.
+   * This is your tax declaration reference from KRA.
+   * Daraja field: AccountReference
+   */
+  accountReference: string;
+  /**
+   * URL where Safaricom POSTs the final result after processing.
+   * Must be publicly accessible.
+   * Daraja field: ResultURL
+   */
+  resultUrl: string;
+  /**
+   * URL Safaricom calls when the request times out in the queue.
+   * Must be publicly accessible.
+   * Daraja field: QueueTimeOutURL
+   */
+  queueTimeOutUrl: string;
+  /**
+   * Additional information associated with the transaction.
+   * Optional — defaults to "Tax Remittance" when omitted.
+   * Daraja field: Remarks
+   */
+  remarks?: string;
+}
+interface TaxRemittanceResponse {
+  /** Unique request identifier assigned by Daraja upon successful submission */
+  OriginatorConversationID: string;
+  /** Unique request identifier assigned by M-Pesa upon successful submission */
+  ConversationID: string;
+  /** "0" = successful submission */
+  ResponseCode: string;
+  /** Descriptive message of the submission status */
+  ResponseDescription: string;
+}
+/**
+ * Known result parameter keys for Tax Remittance as documented by Daraja.
+ *
+ * `(string & {})` is used as the catch-all so that:
+ *   - Named literals appear in IntelliSense / autocomplete.
+ *   - Any unknown future key Daraja may return is still accepted.
+ *   - The `no-redundant-type-constituents` ESLint rule is not triggered.
+ */
+type TaxRemittanceResultParameterKey = 'Amount' | 'TransactionCompletedTime' | 'ReceiverPartyPublicName' | (string & {});
+interface TaxRemittanceResultParameter {
+  Key: TaxRemittanceResultParameterKey;
+  Value: string | number;
+}
+interface TaxRemittanceResult {
+  Result: {
+    /**
+     * Result type indicator.
+     * Daraja returns "0" (string) in success callbacks.
+     * Can also be numeric in some environments.
+     */
+    ResultType: string | number;
+    /**
+     * 0 / "0" = success; non-zero = failure.
+     * Daraja returns "0" (string) in success callbacks per the docs.
+     * Failure codes (e.g. 2001) are typically returned as numbers.
+     */
+    ResultCode: string | number; /** Human-readable result description */
+    ResultDesc: string;
+    OriginatorConversationID: string;
+    ConversationID: string;
+    TransactionID: string;
+    /**
+     * Present on successful results only.
+     * Daraja may return ResultParameter as a single object or an array —
+     * both shapes are handled by the webhook helpers.
+     */
+    ResultParameters?: {
+      ResultParameter: TaxRemittanceResultParameter | TaxRemittanceResultParameter[];
+    };
+  };
+}
+//#endregion
+export { TransactionStatusResult as A, AccountBalanceRequest as C, MpesaConfig as D, Environment as E, TransactionStatusRequest as O, B2BExpressCheckoutResponse as S, AccountBalanceResult as T, B2CRequest as _, ReversalResponse as a, B2BExpressCheckoutCallback as b, C2BRegisterUrlRequest as c, C2BSimulateResponse as d, C2BValidationPayload as f, B2CDisbursementResult as g, B2CDisbursementResponse as h, ReversalRequest as i, IdempotencyManager as j, TransactionStatusResponse as k, C2BRegisterUrlResponse as l, B2CDisbursementRequest as m, TaxRemittanceResponse as n, ReversalResult as o, C2BValidationResponse as p, TaxRemittanceResult as r, C2BConfirmationPayload as s, TaxRemittanceRequest as t, C2BSimulateRequest as u, B2CResponse as v, AccountBalanceResponse as w, B2BExpressCheckoutRequest as x, B2CResult as y };