pesafy 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,837 @@
+import { C as AccountBalanceRequest, D as MpesaConfig, E as Environment, O as TransactionStatusRequest, S as B2BExpressCheckoutResponse, _ as B2CRequest, a as ReversalResponse, c as C2BRegisterUrlRequest, d as C2BSimulateResponse, h as B2CDisbursementResponse, i as ReversalRequest, j as IdempotencyManager, k as TransactionStatusResponse, l as C2BRegisterUrlResponse, m as B2CDisbursementRequest, n as TaxRemittanceResponse, t as TaxRemittanceRequest, u as C2BSimulateRequest, v as B2CResponse, w as AccountBalanceResponse, x as B2BExpressCheckoutRequest } from "./types.js";
+
+//#region src/mpesa/stk-push/types.d.ts
+/**
+ * src/mpesa/stk-push/types.ts
+ *
+ * Types, constants, and helpers for the M-PESA STK Push (M-PESA Express) API.
+ *
+ * Daraja docs:
+ *   STK Push  → POST /mpesa/stkpush/v1/processrequest
+ *   STK Query → POST /mpesa/stkpushquery/v1/query
+ */
+type TransactionType = 'CustomerPayBillOnline' | 'CustomerBuyGoodsOnline';
+interface StkPushRequest {
+  /**
+   * Transaction amount in KES.
+   * Min: {@link STK_PUSH_LIMITS.MIN_AMOUNT} (KES 1)
+   * Max: {@link STK_PUSH_LIMITS.MAX_AMOUNT} (KES 250 000)
+   * Must round to a whole number ≥ 1.
+   * Daraja field: `Amount`
+   */
+  amount: number;
+  /**
+   * Phone number sending the money. Format: 2547XXXXXXXX.
+   * Must be a valid Safaricom M-PESA number.
+   * Daraja fields: `PartyA`, `PhoneNumber`
+   */
+  phoneNumber: string;
+  /**
+   * URL where Safaricom will POST the callback result.
+   * Must be publicly accessible (use ngrok/localtunnel for local dev).
+   * Daraja field: `CallBackURL`
+   */
+  callbackUrl: string;
+  /**
+   * Alpha-numeric reference shown to customer in the USSD prompt.
+   * Truncated to max 12 characters before sending.
+   * Daraja field: `AccountReference`
+   */
+  accountReference: string;
+  /**
+   * Additional description for the transaction.
+   * Truncated to max 13 characters before sending.
+   * Daraja field: `TransactionDesc`
+   */
+  transactionDesc: string;
+  /**
+   * Business shortcode — Paybill number or HO/Store number for Till.
+   * Daraja field: `BusinessShortCode`
+   */
+  shortCode: string;
+  /**
+   * Passkey used to generate the Password.
+   * Sandbox: from Daraja simulator test data.
+   * Production: emailed after Go Live.
+   */
+  passKey: string;
+  /**
+   * "CustomerPayBillOnline" (default) for Paybill.
+   * "CustomerBuyGoodsOnline" for Till Numbers.
+   * Daraja field: `TransactionType`
+   */
+  transactionType?: TransactionType;
+  /**
+   * Credit party receiving funds.
+   * - CustomerPayBillOnline → defaults to `shortCode`
+   * - CustomerBuyGoodsOnline → set to the Till Number
+   * Daraja field: `PartyB`
+   */
+  partyB?: string;
+}
+/**
+ * Synchronous acknowledgement returned immediately after STK Push submission.
+ * This is NOT the payment result — the result arrives via callback.
+ *
+ * Daraja endpoint: POST /mpesa/stkpush/v1/processrequest
+ */
+interface StkPushResponse {
+  /** Global unique identifier for the submitted payment request */
+  MerchantRequestID: string;
+  /** Global unique identifier for the checkout transaction — use this for STK Query */
+  CheckoutRequestID: string;
+  /**
+   * "0" = request accepted successfully.
+   * Any other value = submission error.
+   */
+  ResponseCode: string;
+  /** Human-readable submission status */
+  ResponseDescription: string;
+  /** Message shown to customer on their device */
+  CustomerMessage: string;
+}
+/**
+ * Parameters for querying the status of a previously initiated STK Push.
+ *
+ * Daraja endpoint: POST /mpesa/stkpushquery/v1/query
+ */
+interface StkQueryRequest {
+  /** `CheckoutRequestID` from the STK Push response */
+  checkoutRequestId: string;
+  shortCode: string;
+  passKey: string;
+}
+/**
+ * Response from the STK Query API.
+ *
+ * Note: `ResultCode` is documented as "Numeric" by Daraja.
+ * The Daraja JSON example shows it as a string (`"ResultCode": "0"`),
+ * but actual API responses return a number. Typed as `number` here.
+ * Use {@link STK_RESULT_CODES} constants for comparisons.
+ */
+interface StkQueryResponse {
+  /** "0" = request accepted. Not the final payment status. */
+  ResponseCode: string;
+  /** Submission status message */
+  ResponseDescription: string;
+  /** Unique identifier for the merchant request */
+  MerchantRequestID: string;
+  /** Unique identifier for the checkout transaction */
+  CheckoutRequestID: string;
+  /**
+   * Payment processing status code.
+   * See {@link STK_RESULT_CODES} for all documented values:
+   *   0    → success
+   *   1    → insufficient balance
+   *   1032 → cancelled by user
+   *   1037 → phone unreachable
+   *   2001 → wrong PIN
+   */
+  ResultCode: number;
+  /** Human-readable description of the result */
+  ResultDesc: string;
+}
+//#endregion
+//#region src/utils/errors/index.d.ts
+/**
+ * Pesafy error types — single source of truth.
+ *
+ * All codes map to a specific failure category so callers can handle
+ * them without string-matching on the message.
+ */
+declare const ERROR_CODES: readonly ["AUTH_FAILED", "INVALID_CREDENTIALS", "INVALID_PHONE", "ENCRYPTION_FAILED", "VALIDATION_ERROR", "API_ERROR", "HTTP_ERROR", "NETWORK_ERROR", "REQUEST_FAILED", "INVALID_RESPONSE", "TIMEOUT", "RATE_LIMITED", "INSUFFICIENT_FUNDS", "TRANSACTION_FAILED", "DUPLICATE_REQUEST", "IDEMPOTENCY_ERROR"];
+type ErrorCode = (typeof ERROR_CODES)[number];
+interface PesafyErrorOptions {
+  code: ErrorCode;
+  message: string;
+  /** HTTP status code from Daraja (if applicable) */
+  statusCode?: number;
+  /** Raw Daraja response body (for debugging) */
+  response?: unknown;
+  /** Underlying caught error (network, crypto, etc.) */
+  cause?: unknown;
+  /** Daraja requestId from the error envelope */
+  requestId?: string;
+  /** Whether this error is retryable */
+  retryable?: boolean;
+}
+declare class PesafyError extends Error {
+  readonly code: ErrorCode;
+  readonly statusCode: number | undefined;
+  readonly response: unknown;
+  readonly requestId: string | undefined;
+  readonly cause: unknown;
+  readonly retryable: boolean;
+  constructor(options: PesafyErrorOptions);
+  /** Returns true if this is a validation error (user bug — do not retry) */
+  get isValidation(): boolean;
+  /** Returns true if this is an auth error */
+  get isAuth(): boolean;
+  toJSON(): {
+    name: string;
+    code: "AUTH_FAILED" | "INVALID_CREDENTIALS" | "INVALID_PHONE" | "ENCRYPTION_FAILED" | "VALIDATION_ERROR" | "API_ERROR" | "HTTP_ERROR" | "NETWORK_ERROR" | "REQUEST_FAILED" | "INVALID_RESPONSE" | "TIMEOUT" | "RATE_LIMITED" | "INSUFFICIENT_FUNDS" | "TRANSACTION_FAILED" | "DUPLICATE_REQUEST" | "IDEMPOTENCY_ERROR";
+    message: string;
+    statusCode: number | undefined;
+    requestId: string | undefined;
+    retryable: boolean;
+  };
+}
+//#endregion
+//#region src/types/branded.d.ts
+/**
+ * A discriminated union result — either Ok<T> or Err<E>.
+ * Prefer this over throwing in application-level code.
+ *
+ * @example
+ * const result = await mpesa.stkPushSafe({ ... });
+ * if (result.ok) {
+ *   console.log(result.data.CheckoutRequestID);
+ * } else {
+ *   console.error(result.error.code, result.error.message);
+ * }
+ */
+type Result<T, E = PesafyError> = {
+  readonly ok: true;
+  readonly data: T;
+} | {
+  readonly ok: false;
+  readonly error: E;
+};
+//#endregion
+//#region src/mpesa/b2b-buy-goods/types.d.ts
+/**
+ * src/mpesa/b2b-buy-goods/types.ts
+ *
+ * Strictly aligned with Safaricom Daraja Business Buy Goods API documentation.
+ * Endpoint: POST /mpesa/b2b/v1/paymentrequest
+ * CommandID: "BusinessBuyGoods"
+ *
+ * Moves money from your MMF/Working account to the recipient's merchant account
+ * (till number, merchant store number, or Merchant HO).
+ * SenderIdentifierType and RecieverIdentifierType are always "4" per docs.
+ */
+/**
+ * The only CommandID supported by the Business Buy Goods API.
+ * Docs: "For this API use BusinessBuyGoods only"
+ */
+type B2BBuyGoodsCommandID = 'BusinessBuyGoods';
+/**
+ * Request payload for Business Buy Goods.
+ *
+ * Daraja payload shape:
+ * {
+ *   "Initiator":              "API_Username",
+ *   "SecurityCredential":     "FKX1/KPzT8hFO...",
+ *   "CommandID":              "BusinessBuyGoods",
+ *   "SenderIdentifierType":   "4",
+ *   "RecieverIdentifierType": "4",
+ *   "Amount":                 "239",
+ *   "PartyA":                 "123456",
+ *   "PartyB":                 "000000",
+ *   "AccountReference":       "353353",
+ *   "Requester":              "254700000000",
+ *   "Remarks":                "OK",
+ *   "QueueTimeOutURL":        "https://...",
+ *   "ResultURL":              "https://...",
+ *   "Occassion":              ""
+ * }
+ */
+interface B2BBuyGoodsRequest {
+  /**
+   * Transaction type. Must be "BusinessBuyGoods".
+   * Daraja field: CommandID
+   */
+  commandId: B2BBuyGoodsCommandID;
+  /**
+   * Transaction amount in KES. Must be a whole number ≥ 1.
+   * Daraja field: Amount (sent as string per API spec)
+   */
+  amount: number;
+  /**
+   * Your shortcode from which money will be deducted.
+   * SenderIdentifierType is always "4" (Organisation ShortCode) per docs.
+   * Daraja field: PartyA
+   */
+  partyA: string;
+  /**
+   * The till number / merchant store number / Merchant HO to which money is moved.
+   * RecieverIdentifierType is always "4" (Organisation ShortCode) per docs.
+   * Daraja field: PartyB
+   */
+  partyB: string;
+  /**
+   * The account number associated with the payment (up to 13 characters).
+   * Daraja field: AccountReference
+   */
+  accountReference: string;
+  /**
+   * Optional. The consumer's mobile number on whose behalf you are paying.
+   * Format: 254XXXXXXXXX
+   * Daraja field: Requester
+   */
+  requester?: string;
+  /**
+   * Any additional information for the transaction.
+   * 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;
+  /**
+   * Optional additional information for the transaction.
+   * Daraja field: Occassion (sic — preserved Daraja typo)
+   */
+  occasion?: string;
+}
+/**
+ * Synchronous acknowledgement returned immediately by Daraja.
+ *
+ * Daraja response shape:
+ * {
+ *   "OriginatorConversationID": "5118-111210482-1",
+ *   "ConversationID":           "AG_20230420_2010759fd5662ef6d054",
+ *   "ResponseCode":             "0",
+ *   "ResponseDescription":      "Accept the service request successfully"
+ * }
+ */
+interface B2BBuyGoodsResponse {
+  /** Unique request identifier assigned by Daraja upon successful submission */
+  OriginatorConversationID: string;
+  /** Unique request identifier assigned by M-Pesa */
+  ConversationID: string;
+  /** "0" indicates the request was accepted for processing */
+  ResponseCode: string;
+  /** Human-readable submission status description */
+  ResponseDescription: string;
+}
+//#endregion
+//#region src/mpesa/b2b-pay-bill/types.d.ts
+/**
+ * src/mpesa/b2b-pay-bill/types.ts
+ *
+ * Strictly aligned with Safaricom Daraja Business Pay Bill API documentation.
+ * Endpoint: POST /mpesa/b2b/v1/paymentrequest
+ * CommandID: "BusinessPayBill"
+ *
+ * Moves money from your MMF/Working account to a recipient's utility account.
+ * SenderIdentifierType and RecieverIdentifierType are always "4" per docs.
+ */
+/**
+ * The only CommandID supported by the Business Pay Bill API.
+ * Docs: "For this API use Business PayBill only"
+ */
+type B2BPayBillCommandID = 'BusinessPayBill';
+/**
+ * Request payload for Business Pay Bill.
+ *
+ * Daraja payload shape:
+ * {
+ *   "Initiator":             "API Username",
+ *   "SecurityCredential":    "FKX1/KPzT8hFO...",
+ *   "CommandID":             "BusinessPayBill",
+ *   "SenderIdentifierType":  "4",
+ *   "RecieverIdentifierType":"4",
+ *   "Amount":                "239",
+ *   "PartyA":                "123456",
+ *   "PartyB":                "000000",
+ *   "AccountReference":      "353353",
+ *   "Requester":             "254700000000",
+ *   "Remarks":               "OK",
+ *   "QueueTimeOutURL":       "https://...",
+ *   "ResultURL":             "https://...",
+ *   "Occassion":             ""
+ * }
+ */
+interface B2BPayBillRequest {
+  /**
+   * Transaction type. Must be "BusinessPayBill".
+   * Daraja field: CommandID
+   */
+  commandId: B2BPayBillCommandID;
+  /**
+   * Transaction amount in KES. Must be a whole number ≥ 1.
+   * Daraja field: Amount (sent as string per API spec)
+   */
+  amount: number;
+  /**
+   * Your shortcode from which money will be deducted.
+   * SenderIdentifierType is always "4" (Organisation ShortCode) per docs.
+   * Daraja field: PartyA
+   */
+  partyA: string;
+  /**
+   * The shortcode to which money will be moved (Paybill number).
+   * RecieverIdentifierType is always "4" (Organisation ShortCode) per docs.
+   * Daraja field: PartyB
+   */
+  partyB: string;
+  /**
+   * The account number associated with the payment (up to 13 characters).
+   * Daraja field: AccountReference
+   */
+  accountReference: string;
+  /**
+   * Optional. The consumer's mobile number on whose behalf you are paying.
+   * Format: 254XXXXXXXXX
+   * Daraja field: Requester
+   */
+  requester?: string;
+  /**
+   * Any additional information for the transaction.
+   * 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;
+  /**
+   * Optional additional information for the transaction.
+   * Daraja field: Occassion (sic — preserved Daraja typo)
+   */
+  occasion?: string;
+}
+/**
+ * Synchronous acknowledgement returned immediately by Daraja.
+ *
+ * Daraja response shape:
+ * {
+ *   "OriginatorConversationID": "5118-111210482-1",
+ *   "ConversationID":           "AG_20230420_2010759fd5662ef6d054",
+ *   "ResponseCode":             "0",
+ *   "Response Description":     "Accept the service request successfully"
+ * }
+ *
+ * Note: Daraja uses "Response Description" (with a space) in their docs.
+ * We map this to ResponseDescription for consistency.
+ */
+interface B2BPayBillResponse {
+  /** Unique request identifier assigned by Daraja upon successful submission */
+  OriginatorConversationID: string;
+  /** Unique request identifier assigned by M-Pesa */
+  ConversationID: string;
+  /** "0" indicates the request was accepted for processing */
+  ResponseCode: string;
+  /** Human-readable submission status description */
+  ResponseDescription: string;
+}
+//#endregion
+//#region src/mpesa/bill-manager/types.d.ts
+/**
+ * Bill Manager types.
+ *
+ * Strictly aligned with Safaricom Daraja Bill Manager API documentation.
+ *
+ * APIs:
+ *   POST /v1/billmanager-invoice/optin                 — Opt-in shortcode
+ *   POST /v1/billmanager-invoice/change-optin-details  — Update opt-in details
+ *   POST /v1/billmanager-invoice/single-invoicing      — Send a single invoice
+ *   POST /v1/billmanager-invoice/bulk-invoicing        — Send bulk invoices (up to 1000)
+ *   POST /v1/billmanager-invoice/cancel-single-invoice — Cancel a single invoice
+ *   POST /v1/billmanager-invoice/cancel-bulk-invoices  — Cancel multiple invoices
+ *   POST /v1/billmanager-invoice/reconciliation        — Acknowledge a payment
+ *
+ * Ref: Bill Manager — Daraja Developer Portal
+ */
+interface BillManagerOptInRequest {
+  /**
+   * Organisation shortcode (Paybill or Buy Goods — 5 to 6 digits).
+   * Daraja field: shortcode
+   */
+  shortcode: string;
+  /**
+   * Official contact email for the organisation.
+   * Appears in invoices and receipts.
+   * Daraja field: email
+   */
+  email: string;
+  /**
+   * Official contact phone number (e.g. 0710XXXXXX).
+   * Appears in invoices and receipts.
+   * Daraja field: officialContact
+   */
+  officialContact: string;
+  /**
+   * Enable or disable SMS payment reminders.
+   * "1" = Enable (reminders sent 7 days, 3 days, and on the due date)
+   * "0" = Disable
+   * Daraja field: sendReminders
+   */
+  sendReminders: '1' | '0';
+  /**
+   * Logo image to embed in invoices and receipts.
+   * Accepts JPEG / JPG.
+   * Daraja field: logo
+   */
+  logo?: string;
+  /**
+   * Callback URL where Bill Manager POSTs payment notifications.
+   * Daraja field: callbackurl (lowercase — mapped internally)
+   */
+  callbackUrl: string;
+}
+interface BillManagerOptInResponse {
+  /**
+   * App key assigned upon successful onboarding.
+   * Example: "AG_2376487236_126732989KJ"
+   */
+  app_key?: string;
+  /** Human-readable result message */
+  resmsg: string;
+  /** Numeric status code — "200" = success */
+  rescode: string;
+}
+/**
+ * Same fields as opt-in.
+ * Sent to /v1/billmanager-invoice/change-optin-details.
+ */
+type BillManagerUpdateOptInRequest = BillManagerOptInRequest;
+interface BillManagerUpdateOptInResponse {
+  resmsg: string;
+  rescode: string;
+}
+interface BillManagerInvoiceItem {
+  /** Name / description of the billable item */
+  itemName: string;
+  /** Amount for this item in KES (whole number ≥ 1) */
+  amount: number;
+}
+interface BillManagerSingleInvoiceRequest {
+  /**
+   * Unique invoice reference on your system.
+   * Used to reference the invoice from both Bill Manager and your system.
+   * Daraja field: externalReference
+   */
+  externalReference: string;
+  /**
+   * Full name of the billed recipient — appears in the invoice SMS.
+   * Daraja field: billedFullName
+   */
+  billedFullName: string;
+  /**
+   * Safaricom phone number to receive the invoice SMS.
+   * Formats: 07XXXXXXXX or 254XXXXXXXXX
+   * Daraja field: billedPhoneNumber
+   */
+  billedPhoneNumber: string;
+  /**
+   * Month and year of the billing period, e.g. "August 2021".
+   * Daraja field: billedPeriod
+   */
+  billedPeriod: string;
+  /**
+   * Descriptive invoice name — appears in the SMS sent to the customer.
+   * Daraja field: invoiceName
+   */
+  invoiceName: string;
+  /**
+   * Payment due date.
+   * Format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
+   * Daraja field: dueDate
+   */
+  dueDate: string;
+  /**
+   * Account number that uniquely identifies the customer.
+   * Could be a customer name, property unit, student name, etc.
+   * Daraja field: accountReference
+   */
+  accountReference: string;
+  /**
+   * Total invoice amount in KES. Must be a whole number ≥ 1.
+   * Sent as a string per Daraja docs.
+   * Daraja field: amount
+   */
+  amount: number;
+  /**
+   * Additional billable line items shown on the invoice (optional).
+   * Daraja field: invoiceItems
+   */
+  invoiceItems?: BillManagerInvoiceItem[];
+}
+interface BillManagerSingleInvoiceResponse {
+  /** Descriptive status message, e.g. "Invoice sent successfully" */
+  Status_Message?: string;
+  resmsg: string;
+  /** Numeric status code — "200" = success */
+  rescode: string;
+}
+interface BillManagerBulkInvoiceRequest {
+  /**
+   * Array of invoices to send.
+   * Maximum 1000 invoices per request.
+   * Daraja receives these as a JSON array (unwrapped internally).
+   */
+  invoices: BillManagerSingleInvoiceRequest[];
+}
+interface BillManagerBulkInvoiceResponse {
+  Status_Message?: string;
+  resmsg: string;
+  rescode: string;
+}
+interface BillManagerCancelInvoiceRequest {
+  /**
+   * External reference of the invoice to cancel.
+   * Partially or fully paid invoices cannot be cancelled.
+   */
+  externalReference: string;
+}
+interface BillManagerCancelInvoiceResponse {
+  Status_Message?: string;
+  resmsg: string;
+  rescode: string;
+  errors?: unknown[];
+}
+interface BillManagerCancelBulkInvoiceRequest {
+  /**
+   * External references of the invoices to cancel.
+   * Partially or fully paid invoices cannot be cancelled.
+   */
+  externalReferences: string[];
+}
+interface BillManagerCancelBulkInvoiceResponse {
+  Status_Message?: string;
+  resmsg: string;
+  rescode: string;
+  errors?: unknown[];
+}
+/**
+ * Acknowledgment body sent to Daraja after your system has processed a payment.
+ *
+ * Endpoint: POST /v1/billmanager-invoice/reconciliation
+ *
+ * Per Daraja docs:
+ * ```json
+ * {
+ *   "paymentDate": "2021-10-01",
+ *   "paidAmount": "800",
+ *   "accountReference": "Balboa95",
+ *   "transactionId": "PJB53MYR1N",
+ *   "phoneNumber": "0710XXXXXX",
+ *   "fullName": "John Doe",
+ *   "invoiceName": "School Fees",
+ *   "externalReference": "955"
+ * }
+ * ```
+ */
+interface BillManagerReconciliationRequest {
+  /** Date payment was received, e.g. "2021-10-01" */
+  paymentDate: string;
+  /** Amount paid */
+  paidAmount: string;
+  /** Account reference */
+  accountReference: string;
+  /** M-PESA receipt / transaction ID */
+  transactionId: string;
+  /** Customer phone number */
+  phoneNumber: string;
+  /** Customer full name */
+  fullName: string;
+  /** Invoice name */
+  invoiceName: string;
+  /** Your external invoice reference */
+  externalReference: string;
+}
+interface BillManagerReconciliationResponse {
+  resmsg: string;
+  rescode: string;
+}
+//#endregion
+//#region src/mpesa/dynamic-qr/types.d.ts
+/**
+ * src/mpesa/dynamic-qr/types.ts
+ *
+ * Strict TypeScript types for the Safaricom Daraja Dynamic QR API.
+ *
+ * API endpoint: POST /mpesa/qrcode/v1/generate
+ *
+ * Daraja reference:
+ *   https://developer.safaricom.co.ke/APIs/DynamicQRCode
+ */
+/**
+ * Valid transaction type codes for Dynamic QR generation.
+ *
+ * | Code | Description                              |
+ * |------|------------------------------------------|
+ * | BG   | Pay Merchant – Buy Goods (till number)   |
+ * | WA   | Withdraw Cash at Agent Till              |
+ * | PB   | Paybill or Business number               |
+ * | SM   | Send Money (mobile number)               |
+ * | SB   | Send to Business (MSISDN-format CPI)     |
+ */
+type QRTransactionCode = 'BG' | 'WA' | 'PB' | 'SM' | 'SB';
+/**
+ * Parameters for generating a Dynamic QR code.
+ *
+ * Maps 1-to-1 to the Daraja API body (camelCase → Daraja PascalCase
+ * conversion is handled inside `generateDynamicQR`).
+ */
+interface DynamicQRRequest {
+  /**
+   * Name of the company / M-PESA merchant to embed in the QR.
+   * Daraja field: `MerchantName`
+   *
+   * @example "TEST SUPERMARKET"
+   */
+  merchantName: string;
+  /**
+   * Transaction reference shown to the customer on their phone.
+   * Daraja field: `RefNo`
+   *
+   * @example "Invoice Test"
+   * @example "INV-2024-001"
+   */
+  refNo: string;
+  /**
+   * Total transaction amount in KES (whole numbers only — fractions are
+   * rejected by Daraja). The value is rounded to the nearest integer
+   * before being sent.
+   * Daraja field: `Amount`
+   *
+   * @minimum 1
+   * @example 500
+   */
+  amount: number;
+  /**
+   * Transaction type code.
+   *
+   * - `"BG"` — Buy Goods (till number as CPI)
+   * - `"WA"` — Withdraw Cash at Agent Till
+   * - `"PB"` — Paybill / Business Number
+   * - `"SM"` — Send Money (customer MSISDN as CPI)
+   * - `"SB"` — Send to Business (MSISDN-format CPI)
+   *
+   * Daraja field: `TrxCode`
+   */
+  trxCode: QRTransactionCode;
+  /**
+   * Credit Party Identifier — the destination of funds.
+   *
+   * The required format depends on `trxCode`:
+   * - `BG` → till number
+   * - `WA` → agent till number
+   * - `PB` → paybill / business number
+   * - `SM` → customer MSISDN (e.g. `"254712345678"`)
+   * - `SB` → MSISDN-format business number
+   *
+   * Daraja field: `CPI`
+   *
+   * @example "373132"        // BG
+   * @example "174379"        // PB
+   * @example "254712345678"  // SM
+   */
+  cpi: string;
+  /**
+   * Width (and height) of the generated QR code image in pixels.
+   * The image is always square.
+   *
+   * Daraja field: `Size` (sent as a string, e.g. `"300"`)
+   *
+   * @default 300
+   * @minimum 1
+   * @maximum 1000
+   * @example 300
+   */
+  size?: number;
+}
+/**
+ * Successful response from the Daraja Dynamic QR API.
+ */
+interface DynamicQRResponse {
+  /**
+   * Unique transaction identifier assigned by Daraja.
+   * Daraja field: `ResponseCode`
+   *
+   * @example "AG_20191219_000043fdf61864fe9ff5"
+   */
+  ResponseCode: string;
+  /**
+   * Internal Daraja request ID for tracing.
+   * Daraja field: `RequestID`
+   *
+   * @example "16738-27456357-1"
+   */
+  RequestID: string;
+  /**
+   * Human-readable status message.
+   * Daraja field: `ResponseDescription`
+   *
+   * @example "QR Code Successfully Generated."
+   */
+  ResponseDescription: string;
+  /**
+   * Base64-encoded PNG of the QR code image.
+   *
+   * Render in a browser:
+   * ```html
+   * <img src="data:image/png;base64,{QRCode}" />
+   * ```
+   *
+   * Or write to disk:
+   * ```ts
+   * import { writeFileSync } from 'node:fs'
+   * writeFileSync('qr.png', Buffer.from(response.QRCode, 'base64'))
+   * ```
+   *
+   * Daraja field: `QRCode`
+   */
+  QRCode: string;
+}
+//#endregion
+//#region src/mpesa/index.d.ts
+declare class Mpesa {
+  private readonly config;
+  private readonly tokenManager;
+  private readonly baseUrl;
+  readonly idempotencyManager: IdempotencyManager;
+  constructor(config: MpesaConfig);
+  /** Idempotency options passed to all outbound Daraja HTTP calls. */
+  private darajaHttp;
+  private getToken;
+  private buildSecurityCredential;
+  private requireInitiator;
+  stkPushSafe(request: Omit<StkPushRequest, 'shortCode' | 'passKey'>): Promise<Result<Awaited<ReturnType<typeof this.stkPush>>>>;
+  accountBalanceSafe(request: AccountBalanceRequest): Promise<Result<AccountBalanceResponse>>;
+  stkPush(request: Omit<StkPushRequest, 'shortCode' | 'passKey'>): Promise<StkPushResponse>;
+  stkQuery(request: Omit<StkQueryRequest, 'shortCode' | 'passKey'>): Promise<StkQueryResponse>;
+  transactionStatus(request: TransactionStatusRequest): Promise<TransactionStatusResponse>;
+  accountBalance(request: AccountBalanceRequest): Promise<AccountBalanceResponse>;
+  reverseTransaction(request: ReversalRequest): Promise<ReversalResponse>;
+  generateDynamicQR(request: DynamicQRRequest): Promise<DynamicQRResponse>;
+  registerC2BUrls(request: C2BRegisterUrlRequest): Promise<C2BRegisterUrlResponse>;
+  simulateC2B(request: C2BSimulateRequest): Promise<C2BSimulateResponse>;
+  remitTax(request: TaxRemittanceRequest): Promise<TaxRemittanceResponse>;
+  b2bExpressCheckout(request: B2BExpressCheckoutRequest): Promise<B2BExpressCheckoutResponse>;
+  b2bBuyGoods(request: B2BBuyGoodsRequest): Promise<B2BBuyGoodsResponse>;
+  b2bPayBill(request: B2BPayBillRequest): Promise<B2BPayBillResponse>;
+  b2cPayment(request: B2CRequest): Promise<B2CResponse>;
+  b2cDisbursement(request: B2CDisbursementRequest): Promise<B2CDisbursementResponse>;
+  billManagerOptIn(request: BillManagerOptInRequest): Promise<BillManagerOptInResponse>;
+  updateOptIn(request: BillManagerUpdateOptInRequest): Promise<BillManagerUpdateOptInResponse>;
+  sendInvoice(request: BillManagerSingleInvoiceRequest): Promise<BillManagerSingleInvoiceResponse>;
+  sendBulkInvoices(request: BillManagerBulkInvoiceRequest): Promise<BillManagerBulkInvoiceResponse>;
+  cancelInvoice(request: BillManagerCancelInvoiceRequest): Promise<BillManagerCancelInvoiceResponse>;
+  cancelBulkInvoices(request: BillManagerCancelBulkInvoiceRequest): Promise<BillManagerCancelBulkInvoiceResponse>;
+  reconcilePayment(request: BillManagerReconciliationRequest): Promise<BillManagerReconciliationResponse>;
+  clearTokenCache(): void;
+  get environment(): Environment;
+}
+//#endregion
+export { Mpesa as t };