pesafy 0.0.2 → 0.2.0

package/dist/types.d.ts

@@ -46,6 +46,138 @@ declare class IdempotencyManager {
   private pruneExpired;
 }
 //#endregion
+//#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/mpesa/transaction-status/types.d.ts
 /**
  * Transaction Status Query types
@@ -200,6 +332,72 @@ interface MpesaConfig {
   };
 }
 //#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/account-balance/types.d.ts
 interface AccountBalanceRequest {
   /**
@@ -480,6 +678,242 @@ interface B2BExpressCheckoutCallbackFailed {
  */
 type B2BExpressCheckoutCallback = B2BExpressCheckoutCallbackSuccess | B2BExpressCheckoutCallbackCancelled | B2BExpressCheckoutCallbackFailed;
 //#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/b2c/types.d.ts
 /**
  * src/mpesa/b2c/types.ts
@@ -713,6 +1147,226 @@ interface B2CDisbursementResult {
   };
 }
 //#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/c2b/types.d.ts
 /**
  * src/mpesa/c2b/types.ts
@@ -740,8 +1394,8 @@ type C2BResponseType = 'Completed' | 'Cancelled';
  * {
  *   "ShortCode":        "601426",
  *   "ResponseType":     "Completed",
- *   "ConfirmationURL":  "https://yourdomain.com/confirm",
- *   "ValidationURL":    "https://yourdomain.com/validate"
+ *   "ConfirmationURL":  "https://example.com/confirm",
+ *   "ValidationURL":    "https://example.com/validate"
  * }
  */
 interface C2BRegisterUrlRequest {
@@ -963,6 +1617,147 @@ interface C2BConfirmationPayload {
   LastName: 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/reversal/types.d.ts
 /**
  * Keys present in the ResultParameters.ResultParameter array of a successful
@@ -982,8 +1777,8 @@ type ReversalResultParameterKey = 'DebitAccountBalance' | 'Amount' | 'TransCompl
  *   "Amount":                "200",
  *   "ReceiverParty":         "603021",
  *   "RecieverIdentifierType":"11",
- *   "ResultURL":             "https://mydomain.com/reversal/result",
- *   "QueueTimeOutURL":       "https://mydomain.com/reversal/queue",
+ *   "ResultURL":             "https://example.org/reversal/result",
+ *   "QueueTimeOutURL":       "https://example.org/reversal/queue",
  *   "Remarks":               "Payment reversal"
  * }
  * ```
@@ -1256,4 +2051,128 @@ interface TaxRemittanceResult {
   };
 }
 //#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 };
+//#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
+//#region src/adapters/webhook-guard.d.ts
+/** Optional webhook security settings shared by framework adapters. */
+interface AdapterWebhookSecurityConfig {
+  /** Skip Safaricom IP allowlist (local dev only). */
+  skipIPCheck?: boolean;
+  /** Shared secret for opt-in HMAC verification. */
+  webhookSecret?: string;
+  /** Reject when HMAC is required but missing/invalid. */
+  requireHMAC?: boolean;
+  /** Header carrying the HMAC signature (default: x-safaricom-signature). */
+  signatureHeader?: string;
+}
+//#endregion
+//#region src/adapters/shared/types.d.ts
+type Awaitable<T> = T | Promise<T>;
+interface StkSuccessPayload {
+  receiptNumber: string | null;
+  amount: number | null;
+  phone: string | null;
+  checkoutRequestId: string;
+  merchantRequestId: string;
+}
+interface StkFailurePayload {
+  resultCode: number;
+  resultDesc: string;
+  checkoutRequestId: string;
+  merchantRequestId: string;
+}
+interface MpesaAdapterConfig extends MpesaConfig, AdapterWebhookSecurityConfig {
+  /** STK Push callback URL (required) */
+  callbackUrl: string;
+  /** Default ResultURL for async APIs (balance, reversal, tx-status, b2c, tax) */
+  resultUrl?: string;
+  /** Default QueueTimeOutURL */
+  queueTimeoutUrl?: string;
+  /** Prefix for all routes — default "" */
+  routePrefix?: string;
+  balance?: {
+    resultUrl?: string;
+    queueTimeoutUrl?: string;
+    shortCode?: string;
+  };
+  reversal?: {
+    resultUrl?: string;
+    queueTimeoutUrl?: string;
+  };
+  txStatus?: {
+    resultUrl?: string;
+    queueTimeoutUrl?: string;
+  };
+  tax?: {
+    resultUrl?: string;
+    queueTimeoutUrl?: string;
+    partyA?: string;
+  };
+  b2c?: {
+    resultUrl?: string;
+    queueTimeoutUrl?: string;
+    partyA?: string;
+  };
+  c2b?: {
+    shortCode?: string;
+    confirmationUrl?: string;
+    validationUrl?: string;
+    responseType?: 'Completed' | 'Cancelled';
+    apiVersion?: 'v1' | 'v2';
+  };
+  b2b?: {
+    receiverShortCode?: string;
+    callbackUrl?: string;
+  };
+  onStkSuccess?: (data: StkSuccessPayload) => Awaitable<void>;
+  onStkFailure?: (data: StkFailurePayload) => Awaitable<void>;
+  onC2BValidation?: (payload: C2BValidationPayload) => Awaitable<C2BValidationResponse>;
+  onC2BConfirmation?: (payload: C2BConfirmationPayload) => Awaitable<void>;
+  onAccountBalanceResult?: (result: AccountBalanceResult) => Awaitable<void>;
+  onReversalResult?: (result: ReversalResult) => Awaitable<void>;
+  onTxStatusResult?: (result: TransactionStatusResult) => Awaitable<void>;
+  onTaxResult?: (result: TaxRemittanceResult) => Awaitable<void>;
+  onB2BCheckoutCallback?: (callback: B2BExpressCheckoutCallback) => Awaitable<void>;
+  onB2CResult?: (result: B2CResult) => Awaitable<void>;
+  onB2CDisbursementResult?: (result: B2CDisbursementResult) => Awaitable<void>;
+}
+//#endregion
+export { Mpesa as i, StkFailurePayload as n, StkSuccessPayload as r, MpesaAdapterConfig as t };
+//# sourceMappingURL=types.d.ts.map