pesafy 0.0.2 → 0.2.0

package/dist/route-definitions.js

@@ -0,0 +1,3292 @@
+import { readFile } from "node:fs/promises";
+import { constants, publicEncrypt } from "node:crypto";
+import { z } from "zod";
+
+//#region src/utils/errors/index.ts
+var PesafyError = class PesafyError extends Error {
+	code;
+	statusCode;
+	response;
+	requestId;
+	cause;
+	retryable;
+	constructor(options) {
+		super(options.message);
+		Object.defineProperty(this, "name", { value: "PesafyError" });
+		this.code = options.code;
+		this.statusCode = options.statusCode;
+		this.response = options.response;
+		this.requestId = options.requestId;
+		this.cause = options.cause;
+		this.retryable = options.retryable ?? (options.code === "NETWORK_ERROR" || options.code === "TIMEOUT" || options.code === "RATE_LIMITED" || options.code === "REQUEST_FAILED");
+		if (Error.captureStackTrace) Error.captureStackTrace(this, PesafyError);
+	}
+	/** Returns true if this is a validation error (user bug — do not retry) */
+	get isValidation() {
+		return this.code === "VALIDATION_ERROR";
+	}
+	/** Returns true if this is an auth error */
+	get isAuth() {
+		return this.code === "AUTH_FAILED" || this.code === "INVALID_CREDENTIALS";
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			statusCode: this.statusCode,
+			requestId: this.requestId,
+			retryable: this.retryable
+		};
+	}
+};
+/** Convenience factory */
+function createError(options) {
+	return new PesafyError(options);
+}
+
+//#endregion
+//#region src/utils/http/index.ts
+/** Merge explicit Daraja HTTP options into an httpRequest options object. */
+function withDarajaHttp(options, http) {
+	if (!http?.idempotency) return options;
+	return {
+		...options,
+		idempotency: http.idempotency
+	};
+}
+const RETRYABLE_STATUSES = new Set([
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+function withJitter(base) {
+	const spread = base * .25;
+	return base + (Math.random() * spread * 2 - spread);
+}
+/** Origin + path only (no query) for safe retry logs. */
+function logSafeUrl(url) {
+	try {
+		const u = new URL(url);
+		return `${u.origin}${u.pathname}`;
+	} catch {
+		return url.split("?")[0] ?? url;
+	}
+}
+/**
+* Sends an HTTP request to Daraja and returns parsed JSON.
+* Automatically retries transient failures with exponential back-off.
+*
+* @throws {PesafyError} on non-retryable errors or exhausted retries.
+*/
+async function httpRequest(url, options) {
+	const maxRetries = options.retries ?? 4;
+	const baseDelay = options.retryDelay ?? 2e3;
+	const timeout = options.timeout ?? 3e4;
+	const headers = {
+		"Content-Type": "application/json",
+		Accept: "application/json",
+		...options.headers
+	};
+	const manager = options.idempotency;
+	let idempotencyKey = options.idempotencyKey;
+	if (options.method === "POST" && manager?.enabled) {
+		idempotencyKey = manager.reserve(idempotencyKey);
+		const headerName = manager.headerName;
+		headers[headerName] = idempotencyKey;
+	} else if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+	const init = {
+		method: options.method,
+		headers,
+		...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {}
+	};
+	let lastError = null;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		if (attempt > 0) {
+			const delay = withJitter(baseDelay * Math.pow(2, attempt - 1));
+			console.warn(`[pesafy] Retry ${attempt}/${maxRetries} → ${options.method} ${logSafeUrl(url)} in ${Math.round(delay)} ms`);
+			await sleep(delay);
+		}
+		const controller = new AbortController();
+		const tid = setTimeout(() => controller.abort(), timeout);
+		let response;
+		try {
+			response = await fetch(url, {
+				...init,
+				signal: controller.signal
+			});
+		} catch (err) {
+			clearTimeout(tid);
+			if (err instanceof Error && err.name === "AbortError") lastError = new PesafyError({
+				code: "TIMEOUT",
+				message: `Request to ${url} timed out after ${timeout} ms`,
+				cause: err,
+				retryable: true
+			});
+			else lastError = new PesafyError({
+				code: "NETWORK_ERROR",
+				message: `Network error: ${err instanceof Error ? err.message : String(err)}`,
+				cause: err,
+				retryable: true
+			});
+			if (attempt < maxRetries) continue;
+			if (idempotencyKey && manager?.enabled) manager.release(idempotencyKey);
+			throw lastError;
+		} finally {
+			clearTimeout(tid);
+		}
+		let rawText = "";
+		let data = null;
+		const ct = response.headers.get("content-type") ?? "";
+		try {
+			rawText = await response.text();
+			if (rawText) data = ct.includes("application/json") ? JSON.parse(rawText) : rawText;
+		} catch {
+			data = rawText || null;
+		}
+		const responseHeaders = {};
+		response.headers.forEach((v, k) => {
+			responseHeaders[k] = v;
+		});
+		if (response.ok) {
+			if (idempotencyKey && manager?.enabled) manager.complete(idempotencyKey);
+			return {
+				data,
+				status: response.status,
+				headers: responseHeaders
+			};
+		}
+		const isTransient = RETRYABLE_STATUSES.has(response.status);
+		const daraja = typeof data === "object" && data !== null ? data : {};
+		const message = daraja["errorMessage"] ?? daraja["ResponseDescription"] ?? daraja["resultDesc"] ?? rawText ?? `HTTP ${response.status}`;
+		lastError = new PesafyError({
+			code: isTransient ? "REQUEST_FAILED" : "API_ERROR",
+			message,
+			statusCode: response.status,
+			response: data,
+			retryable: isTransient,
+			...typeof daraja["requestId"] === "string" ? { requestId: daraja["requestId"] } : {}
+		});
+		if (isTransient && attempt < maxRetries) continue;
+		if (idempotencyKey && manager?.enabled) manager.release(idempotencyKey);
+		throw lastError;
+	}
+	if (idempotencyKey && manager?.enabled) manager.release(idempotencyKey);
+	throw lastError;
+}
+
+//#endregion
+//#region src/core/auth/types.ts
+/**
+* Daraja Authorization API error codes
+* Documented at: https://developer.safaricom.co.ke/APIs/Authorization
+*
+* These are returned in the `errorCode` field of a 400 error response body
+* when the OAuth token request is malformed.
+*/
+const AUTH_ERROR_CODES = {
+	INVALID_AUTH_TYPE: "400.008.01",
+	INVALID_GRANT_TYPE: "400.008.02"
+};
+
+//#endregion
+//#region src/core/auth/token-manager.ts
+/** Refresh the token this many seconds before it actually expires */
+const TOKEN_BUFFER_SECONDS = 60;
+var TokenManager = class {
+	consumerKey;
+	consumerSecret;
+	baseUrl;
+	cachedToken = null;
+	tokenExpiresAt = 0;
+	constructor(consumerKey, consumerSecret, baseUrl) {
+		this.consumerKey = consumerKey;
+		this.consumerSecret = consumerSecret;
+		this.baseUrl = baseUrl;
+	}
+	getBasicAuthHeader() {
+		const credentials = `${this.consumerKey}:${this.consumerSecret}`;
+		return `Basic ${Buffer.from(credentials, "utf-8").toString("base64")}`;
+	}
+	/**
+	* Maps Daraja-specific auth error codes (400.008.01 / 400.008.02) to
+	* descriptive PesafyError messages so callers get actionable feedback.
+	*
+	* Always throws — the `never` return type signals this to TypeScript.
+	*/
+	mapAuthError(error) {
+		if (error instanceof PesafyError) {
+			if (error.code === "AUTH_FAILED") throw error;
+			const raw = error.response;
+			if (raw && typeof raw === "object") {
+				const errorCode = raw["errorCode"] ?? raw["error_code"];
+				if (errorCode === AUTH_ERROR_CODES.INVALID_AUTH_TYPE) throw new PesafyError({
+					code: "AUTH_FAILED",
+					message: "Invalid authentication type (400.008.01). Use Basic authentication: Authorization: Basic <Base64(consumerKey:consumerSecret)>.",
+					...error.statusCode !== void 0 && { statusCode: error.statusCode },
+					response: error.response
+				});
+				if (errorCode === AUTH_ERROR_CODES.INVALID_GRANT_TYPE) throw new PesafyError({
+					code: "AUTH_FAILED",
+					message: "Invalid grant type (400.008.02). Set grant_type=client_credentials in the request query parameters.",
+					...error.statusCode !== void 0 && { statusCode: error.statusCode },
+					response: error.response
+				});
+			}
+			throw error;
+		}
+		throw error;
+	}
+	/**
+	* Returns a valid access token, fetching a new one when the cached token
+	* is absent or within TOKEN_BUFFER_SECONDS of expiry.
+	*
+	* Daraja endpoint: GET /oauth/v1/generate?grant_type=client_credentials
+	* Auth:            Basic Base64(consumerKey:consumerSecret)
+	* Token lifetime:  3599 seconds (Daraja docs)
+	*/
+	async getAccessToken() {
+		const now = Date.now() / 1e3;
+		if (this.cachedToken && this.tokenExpiresAt > now + TOKEN_BUFFER_SECONDS) return this.cachedToken;
+		const url = `${this.baseUrl}/oauth/v1/generate?grant_type=client_credentials`;
+		try {
+			const response = await httpRequest(url, {
+				method: "GET",
+				headers: { Authorization: this.getBasicAuthHeader() }
+			});
+			const { access_token, expires_in } = response.data;
+			if (!access_token) throw new PesafyError({
+				code: "AUTH_FAILED",
+				message: "Daraja did not return an access token. Verify your consumer key and consumer secret.",
+				response: response.data
+			});
+			this.cachedToken = access_token;
+			this.tokenExpiresAt = now + (expires_in ?? 3600);
+			return this.cachedToken;
+		} catch (error) {
+			return this.mapAuthError(error);
+		}
+	}
+	/** Force token refresh on the next call (e.g. after a 401 response) */
+	clearCache() {
+		this.cachedToken = null;
+		this.tokenExpiresAt = 0;
+	}
+};
+
+//#endregion
+//#region src/core/encryption/security-credentials.ts
+function encryptSecurityCredential(initiatorPassword, certificatePem) {
+	try {
+		const passwordBuffer = Buffer.from(initiatorPassword, "utf-8");
+		return publicEncrypt({
+			key: certificatePem,
+			padding: constants.RSA_PKCS1_PADDING
+		}, passwordBuffer).toString("base64");
+	} catch (error) {
+		throw new PesafyError({
+			code: "ENCRYPTION_FAILED",
+			message: "Failed to encrypt security credential. Ensure the certificate PEM is valid and matches the environment (sandbox/production).",
+			cause: error
+		});
+	}
+}
+
+//#endregion
+//#region src/core/idempotency/generate-key.ts
+/**
+* Generate idempotency keys for Daraja mutating requests.
+*/
+/** UUID v4 idempotency key, optionally prefixed for debugging. */
+function generateIdempotencyKey(prefix) {
+	const id = crypto.randomUUID();
+	return prefix ? `${prefix}-${id}` : id;
+}
+/** Daraja OriginatorConversationID — unique per async API request. */
+function generateOriginatorConversationId() {
+	return generateIdempotencyKey("pesafy");
+}
+/** B2B Express RequestRefID — unique per checkout request. */
+function generateRequestRefId() {
+	return crypto.randomUUID();
+}
+
+//#endregion
+//#region src/core/idempotency/store.ts
+var InMemoryIdempotencyStore = class {
+	entries = /* @__PURE__ */ new Map();
+	get(key) {
+		return this.entries.get(key);
+	}
+	set(key, entry) {
+		this.entries.set(key, entry);
+	}
+	delete(key) {
+		this.entries.delete(key);
+	}
+	/** Remove entries older than ttlMs. */
+	prune(ttlMs) {
+		const cutoff = Date.now() - ttlMs;
+		for (const [key, entry] of this.entries) if (entry.createdAt < cutoff) this.entries.delete(key);
+	}
+};
+
+//#endregion
+//#region src/core/idempotency/manager.ts
+const DEFAULT_TTL_MS = 1440 * 60 * 1e3;
+var IdempotencyManager = class {
+	enabled;
+	headerName;
+	ttlMs;
+	store;
+	generateKey;
+	constructor(config = {}) {
+		this.enabled = config.enabled !== false;
+		this.headerName = config.headerName ?? "Idempotency-Key";
+		this.ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+		this.store = config.store ?? new InMemoryIdempotencyStore();
+		this.generateKey = config.generateKey ?? generateIdempotencyKey;
+	}
+	/**
+	* Reserve an idempotency key before the HTTP call.
+	* @throws PesafyError with IDEMPOTENCY_ERROR if duplicate in-flight/completed within TTL.
+	*/
+	reserve(key) {
+		if (!this.enabled) return key ?? this.generateKey();
+		this.pruneExpired();
+		const resolved = key ?? this.generateKey();
+		const existing = this.store.get(resolved);
+		if (existing) {
+			if (Date.now() - existing.createdAt < this.ttlMs) throw new PesafyError({
+				code: "IDEMPOTENCY_ERROR",
+				message: `Duplicate request detected for idempotency key "${resolved}".`
+			});
+			this.store.delete(resolved);
+		}
+		this.store.set(resolved, {
+			key: resolved,
+			createdAt: Date.now()
+		});
+		return resolved;
+	}
+	/** Mark key as successfully completed. */
+	complete(key) {
+		if (!this.enabled) return;
+		const entry = this.store.get(key);
+		if (entry) this.store.set(key, {
+			...entry,
+			completedAt: Date.now()
+		});
+	}
+	/** Release reservation on failure so callers can retry with same key. */
+	release(key) {
+		if (!this.enabled) return;
+		this.store.delete(key);
+	}
+	pruneExpired() {
+		if (this.store instanceof InMemoryIdempotencyStore) this.store.prune(this.ttlMs);
+	}
+};
+
+//#endregion
+//#region src/types/branded.ts
+function ok(data) {
+	return {
+		ok: true,
+		data
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+
+//#endregion
+//#region src/core/validation/zod-error.ts
+/** Map Zod validation failures to PesafyError. */
+function zodToPesafyError(error, label = "Request") {
+	return new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `${label} validation failed: ${error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+		cause: error
+	});
+}
+/** Parse with Zod; throw PesafyError on failure. */
+function parseWithSchema(schema, data, label) {
+	const result = schema.safeParse(data);
+	if (!result.success) throw zodToPesafyError(result.error, label);
+	return result.data;
+}
+
+//#endregion
+//#region src/schemas/common.ts
+const EnvironmentSchema = z.enum(["sandbox", "production"]);
+const MsisdnSchema = z.string().min(10).regex(/^254\d{9}$/, "Must be Safaricom format 2547XXXXXXXX");
+const KesAmountSchema = z.number().finite().positive().refine((n) => Math.round(n) >= 1, { message: "amount must round to at least 1 KES" });
+const NonEmptyStringSchema = z.string().trim().min(1);
+const UrlSchema = z.string().url();
+const DarajaErrorResponseSchema = z.object({
+	errorMessage: z.string().optional(),
+	ResponseDescription: z.string().optional(),
+	resultDesc: z.string().optional(),
+	requestId: z.string().optional()
+}).passthrough();
+
+//#endregion
+//#region src/schemas/async-apis.ts
+const IdentifierTypeSchema = z.enum([
+	"1",
+	"2",
+	"4"
+]);
+const AsyncApiResponseSchema = z.object({
+	ConversationID: z.string().optional(),
+	OriginatorConversationID: z.string().optional(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+const TransactionStatusRequestSchema = z.object({
+	transactionId: z.string().optional(),
+	originalConversationId: z.string().optional(),
+	partyA: NonEmptyStringSchema,
+	identifierType: IdentifierTypeSchema,
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	commandId: z.literal("TransactionStatusQuery").optional(),
+	remarks: z.string().optional(),
+	occasion: z.string().optional()
+}).superRefine((data, ctx) => {
+	if (!data.transactionId?.trim() && !data.originalConversationId?.trim()) ctx.addIssue({
+		code: "custom",
+		message: "Either transactionId (M-Pesa Receipt Number) or originalConversationId is required",
+		path: ["transactionId"]
+	});
+});
+const TransactionStatusResponseSchema = AsyncApiResponseSchema;
+const AccountBalanceRequestSchema = z.object({
+	partyA: NonEmptyStringSchema,
+	identifierType: IdentifierTypeSchema,
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	remarks: z.string().optional()
+});
+const AccountBalanceResponseSchema = AsyncApiResponseSchema;
+const ReversalRequestSchema = z.object({
+	transactionId: NonEmptyStringSchema,
+	receiverParty: NonEmptyStringSchema,
+	receiverIdentifierType: z.literal("11").optional(),
+	amount: KesAmountSchema,
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	remarks: z.string().optional(),
+	occasion: z.string().optional()
+}).superRefine((data, ctx) => {
+	if (data.receiverIdentifierType !== void 0 && data.receiverIdentifierType !== "11") ctx.addIssue({
+		code: "custom",
+		message: "receiverIdentifierType must be \"11\" for the Reversals API",
+		path: ["receiverIdentifierType"]
+	});
+	const remarks = data.remarks ?? "Transaction Reversal";
+	if (remarks.length < 2 || remarks.length > 100) ctx.addIssue({
+		code: "custom",
+		message: "remarks must be between 2 and 100 characters",
+		path: ["remarks"]
+	});
+});
+const ReversalResponseSchema = AsyncApiResponseSchema;
+const TaxRemittanceRequestSchema = z.object({
+	amount: KesAmountSchema,
+	partyA: NonEmptyStringSchema,
+	partyB: z.string().optional(),
+	accountReference: NonEmptyStringSchema,
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	remarks: z.string().optional()
+});
+const TaxRemittanceResponseSchema = AsyncApiResponseSchema;
+const DynamicQRRequestSchema = z.object({
+	merchantName: NonEmptyStringSchema,
+	refNo: NonEmptyStringSchema,
+	amount: KesAmountSchema,
+	trxCode: z.enum([
+		"BG",
+		"WA",
+		"PB",
+		"SM",
+		"SB"
+	]),
+	cpi: NonEmptyStringSchema,
+	size: z.number().int().min(1).max(1e3).optional()
+});
+const DynamicQRResponseSchema = z.object({
+	ResponseCode: z.string(),
+	RequestID: z.string().optional(),
+	ResponseDescription: z.string(),
+	QRCode: z.string().optional()
+}).passthrough();
+
+//#endregion
+//#region src/mpesa/account-balance/query.ts
+/**
+* Account Balance Query — checks the balance of an M-PESA shortcode.
+*
+* API: POST /mpesa/accountbalance/v1/query
+*
+* This is ASYNCHRONOUS. The sync response only confirms receipt.
+* Balance data arrives via POST to your ResultURL.
+*
+* Required org portal role: "Balance Query ORG API" (Account Balance ORG API initiator)
+*
+* Ref: https://sandbox.safaricom.co.ke/mpesa/accountbalance/v1/query
+*/
+async function queryAccountBalance(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(AccountBalanceRequestSchema, request, "Account Balance request");
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: "AccountBalance",
+		PartyA: String(validated.partyA.trim()),
+		IdentifierType: validated.identifierType,
+		ResultURL: validated.resultUrl,
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		Remarks: validated.remarks ?? "Account Balance Query"
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/accountbalance/v1/query`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(AccountBalanceResponseSchema, data, "Account Balance response");
+}
+
+//#endregion
+//#region src/mpesa/account-balance/types.ts
+/**
+* Parses the raw Daraja AccountBalance string into structured account objects.
+*
+* Daraja returns each account as 3 consecutive pipe-separated fields:
+*   AccountName | Currency | Amount
+* Multiple accounts are concatenated, with additional balance sub-fields interleaved.
+*
+* The parser extracts triplets where the first element is a non-numeric account name.
+*
+* Example input:
+*   "Working Account|KES|700000.00|KES|0.00|KES|0.00|Utility Account|KES|228037.00|"
+*
+* Example output:
+*   [
+*     { name: "Working Account", currency: "KES", amount: "700000.00" },
+*     { name: "Utility Account", currency: "KES", amount: "228037.00" },
+*   ]
+*/
+function parseAccountBalance(raw) {
+	if (!raw.trim()) return [];
+	const parts = raw.split("|");
+	const accounts = [];
+	for (let i = 0; i + 2 < parts.length; i++) {
+		const candidate = parts[i]?.trim();
+		const currency = parts[i + 1]?.trim();
+		const amount = parts[i + 2]?.trim();
+		if (candidate && currency && amount !== void 0 && isNaN(Number(candidate)) && candidate.length > 0) accounts.push({
+			name: candidate,
+			currency,
+			amount
+		});
+	}
+	return accounts;
+}
+/**
+* Extracts a result parameter value from an AccountBalanceResult by key.
+* Handles both array and single-object forms of ResultParameter (Daraja inconsistency).
+*
+* Documented keys: "AccountBalance", "BOCompletedTime"
+*/
+function getAccountBalanceParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return (Array.isArray(params) ? params : [params]).find((p) => p.Key === key)?.Value;
+}
+/**
+* Returns the raw AccountBalance pipe-delimited string from the result, or null if absent.
+* Use parseAccountBalance() to parse this into structured account objects.
+*/
+function getAccountBalanceRawBalance(result) {
+	const value = getAccountBalanceParam(result, "AccountBalance");
+	if (value === void 0 || value === null) return null;
+	return String(value);
+}
+/**
+* Returns true if the Account Balance result indicates success (ResultCode 0).
+* Handles both numeric 0 and string "0" (Daraja inconsistency).
+*/
+function isAccountBalanceSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+
+//#endregion
+//#region src/schemas/b2b.ts
+const B2BAsyncResponseSchema = z.object({
+	ConversationID: z.string(),
+	OriginatorConversationID: z.string(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+const B2BPaymentBaseSchema = z.object({
+	amount: KesAmountSchema,
+	partyA: NonEmptyStringSchema,
+	partyB: NonEmptyStringSchema,
+	accountReference: NonEmptyStringSchema,
+	requester: z.string().optional(),
+	remarks: z.string().optional(),
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	occasion: z.string().optional()
+});
+const B2BBuyGoodsRequestSchema = B2BPaymentBaseSchema.extend({ commandId: z.literal("BusinessBuyGoods") });
+const B2BPayBillRequestSchema = B2BPaymentBaseSchema.extend({ commandId: z.literal("BusinessPayBill") });
+const B2BBuyGoodsResponseSchema = B2BAsyncResponseSchema;
+const B2BPayBillResponseSchema = B2BAsyncResponseSchema;
+const B2BExpressCheckoutRequestSchema = z.object({
+	primaryShortCode: NonEmptyStringSchema,
+	receiverShortCode: NonEmptyStringSchema,
+	amount: KesAmountSchema,
+	paymentRef: NonEmptyStringSchema,
+	callbackUrl: UrlSchema,
+	partnerName: NonEmptyStringSchema,
+	requestRefId: NonEmptyStringSchema.optional()
+});
+const B2BExpressCheckoutResponseSchema = z.object({
+	code: z.string(),
+	status: z.string()
+}).passthrough();
+const B2BResponseSchema = z.object({
+	ConversationID: z.string().optional(),
+	OriginatorConversationID: z.string().optional(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+
+//#endregion
+//#region src/mpesa/b2b-express-checkout/initiate.ts
+/**
+* src/mpesa/b2b-express-checkout/initiate.ts
+*
+* B2B Express Checkout USSD Push to Till implementation.
+*/
+async function initiateB2BExpressCheckout(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(B2BExpressCheckoutRequestSchema, request, "B2B Express Checkout request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		primaryShortCode: String(validated.primaryShortCode),
+		receiverShortCode: String(validated.receiverShortCode),
+		amount: String(amount),
+		paymentRef: validated.paymentRef,
+		callbackUrl: validated.callbackUrl,
+		partnerName: validated.partnerName,
+		RequestRefID: validated.requestRefId ?? generateRequestRefId()
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/ussdpush/get-msisdn`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(B2BExpressCheckoutResponseSchema, data, "B2B Express Checkout response");
+}
+
+//#endregion
+//#region src/mpesa/b2b-express-checkout/types.ts
+/**
+* Known B2B Express Checkout result codes.
+*
+* SUCCESS  (0)    — Transaction completed successfully
+* CANCELLED(4001) — Merchant cancelled the USSD prompt
+* KYC_FAIL (4102) — Merchant KYC failure; provide valid KYC
+* NO_NUMBER(4104) — Missing nominated number; configure in M-PESA portal
+* NET_ERROR(4201) — USSD network error; retry on stable network
+* USSD_ERR (4203) — USSD exception error; retry on stable network
+*/
+const B2B_RESULT_CODES = {
+	SUCCESS: "0",
+	CANCELLED: "4001",
+	KYC_FAIL: "4102",
+	NO_NOMINATED_NUMBER: "4104",
+	USSD_NETWORK_ERROR: "4201",
+	USSD_EXCEPTION_ERROR: "4203"
+};
+
+//#endregion
+//#region src/mpesa/b2b-express-checkout/webhooks.ts
+/**
+* src/mpesa/b2b-express-checkout/webhooks.ts
+*
+* B2B Express Checkout callback (webhook) helpers.
+* Strictly aligned with Safaricom Daraja B2B Express Checkout documentation.
+*
+* All callbacks are discriminated on `resultCode`:
+*   "0"    → success  (B2BExpressCheckoutCallbackSuccess)
+*   "4001" → cancelled (B2BExpressCheckoutCallbackCancelled)
+*   other  → failed   (B2BExpressCheckoutCallbackFailed)
+*/
+const KNOWN_RESULT_CODES$1 = new Set(Object.values(B2B_RESULT_CODES));
+/**
+* Runtime type guard — returns true if `body` looks like a valid B2B
+* Express Checkout callback payload.
+*
+* Use this in your callback route before casting the body:
+* @example
+* app.post('/mpesa/b2b/callback', (req, res) => {
+*   if (!isB2BCheckoutCallback(req.body)) {
+*     return res.status(400).json({ error: 'unrecognised payload' })
+*   }
+*   // safe to use as B2BExpressCheckoutCallback
+* })
+*/
+function isB2BCheckoutCallback(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	return typeof b["resultCode"] === "string" && typeof b["requestId"] === "string" && typeof b["amount"] === "string";
+}
+/**
+* Returns true when the B2B callback represents a SUCCESSFUL transaction.
+* A successful callback has resultCode "0" and includes transactionId.
+*
+* Per Daraja docs:
+* {
+*   "resultCode":    "0",
+*   "resultDesc":    "The service request is processed successfully.",
+*   "transactionId": "RDQ01NFT1Q",
+*   "status":        "SUCCESS",
+*   ...
+* }
+*/
+function isB2BCheckoutSuccess(callback) {
+	return callback.resultCode === B2B_RESULT_CODES.SUCCESS;
+}
+/**
+* Returns true when the merchant CANCELLED the USSD prompt.
+* resultCode "4001" = "User cancelled transaction".
+*
+* Per Daraja docs:
+* {
+*   "resultCode":       "4001",
+*   "resultDesc":       "User cancelled transaction",
+*   "paymentReference": "MAndbubry3hi",
+*   ...
+* }
+*/
+function isB2BCheckoutCancelled(callback) {
+	return callback.resultCode === B2B_RESULT_CODES.CANCELLED;
+}
+/**
+* Returns the transaction amount as a number from any B2B callback.
+* Daraja sends amount as a string (e.g. "71.0"); this converts it to number.
+*/
+function getB2BAmount(callback) {
+	return Number(callback.amount);
+}
+/**
+* Returns the M-PESA receipt number from a SUCCESSFUL callback.
+* Returns null if the callback is not a success.
+*/
+function getB2BTransactionId(callback) {
+	if (!isB2BCheckoutSuccess(callback)) return null;
+	return callback.transactionId ?? null;
+}
+/**
+* Returns the M-PESA conversationID from a SUCCESSFUL callback.
+* Returns null if the callback is not a success.
+*/
+function getB2BConversationId(callback) {
+	if (!isB2BCheckoutSuccess(callback)) return null;
+	return callback.conversationID ?? null;
+}
+
+//#endregion
+//#region src/mpesa/b2b-buy-goods/payment.ts
+/**
+* src/mpesa/b2b-buy-goods/payment.ts
+*
+* Initiates a Business Buy Goods payment via Safaricom Daraja.
+* Endpoint: POST /mpesa/b2b/v1/paymentrequest
+*
+* Strictly follows the Safaricom Daraja Business Buy Goods API documentation:
+*   - CommandID must be "BusinessBuyGoods"
+*   - SenderIdentifierType is always "4" (hardcoded per docs)
+*   - RecieverIdentifierType is always "4" (hardcoded per docs)
+*   - Amount is sent as a string per the JSON spec
+*   - AccountReference is truncated to max 13 characters per docs
+*   - Requester and Occassion are optional
+*/
+/** Daraja Business Buy Goods endpoint — same as Pay Bill per docs */
+const B2B_BUY_GOODS_ENDPOINT = "/mpesa/b2b/v1/paymentrequest";
+/**
+* Per documentation: SenderIdentifierType and RecieverIdentifierType
+* must always be "4" (Organisation ShortCode). Not configurable.
+*/
+const IDENTIFIER_TYPE$2 = "4";
+/**
+* Initiates a Business Buy Goods payment request.
+*
+* Moves money from your MMF/Working account to the recipient's merchant account
+* (till number, merchant store number, or Merchant HO).
+* The sync response is acknowledgement only — the result arrives via resultUrl.
+*
+* @param baseUrl             - Daraja base URL (sandbox or production)
+* @param accessToken         - Valid OAuth Bearer token
+* @param securityCredential  - RSA-encrypted initiator password (base64)
+* @param initiatorName       - M-Pesa API operator username with B2B role
+* @param request             - Business Buy Goods request parameters
+* @returns                   Synchronous acknowledgement response from Daraja
+* @throws {PesafyError}      VALIDATION_ERROR for invalid input before HTTP call
+* @throws {PesafyError}      From httpRequest on network / API errors
+*/
+async function initiateB2BBuyGoods(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(B2BBuyGoodsRequestSchema, request, "B2B Buy Goods request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: validated.commandId,
+		SenderIdentifierType: IDENTIFIER_TYPE$2,
+		RecieverIdentifierType: IDENTIFIER_TYPE$2,
+		Amount: String(amount),
+		PartyA: String(validated.partyA),
+		PartyB: String(validated.partyB),
+		AccountReference: validated.accountReference.slice(0, 13),
+		Remarks: validated.remarks ?? "Business Buy Goods",
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		ResultURL: validated.resultUrl
+	};
+	if (validated.requester?.trim()) payload["Requester"] = String(validated.requester);
+	if (validated.occasion?.trim()) payload["Occassion"] = validated.occasion;
+	const { data } = await httpRequest(`${baseUrl}${B2B_BUY_GOODS_ENDPOINT}`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(B2BBuyGoodsResponseSchema, data, "B2B Buy Goods response");
+}
+
+//#endregion
+//#region src/mpesa/b2b-pay-bill/payment.ts
+/**
+* src/mpesa/b2b-pay-bill/payment.ts
+*
+* Initiates a Business Pay Bill payment via Safaricom Daraja.
+* Endpoint: POST /mpesa/b2b/v1/paymentrequest
+*
+* Strictly follows the Safaricom Daraja Business Pay Bill API documentation:
+*   - CommandID must be "BusinessPayBill"
+*   - SenderIdentifierType is always "4" (hardcoded per docs)
+*   - RecieverIdentifierType is always "4" (hardcoded per docs)
+*   - Amount is sent as a string per the JSON spec
+*   - AccountReference is truncated to max 13 characters per docs
+*   - Requester and Occassion are optional
+*/
+/** Daraja Business Pay Bill endpoint */
+const B2B_PAY_BILL_ENDPOINT = "/mpesa/b2b/v1/paymentrequest";
+/**
+* Per documentation: SenderIdentifierType and RecieverIdentifierType
+* must always be "4" (Organisation ShortCode). Not configurable.
+*/
+const IDENTIFIER_TYPE$1 = "4";
+/**
+* Initiates a Business Pay Bill payment request.
+*
+* Moves money from your MMF/Working account to the recipient's utility account.
+* The sync response is acknowledgement only — the result arrives via resultUrl.
+*
+* @param baseUrl             - Daraja base URL (sandbox or production)
+* @param accessToken         - Valid OAuth Bearer token
+* @param securityCredential  - RSA-encrypted initiator password (base64)
+* @param initiatorName       - M-Pesa API operator username with B2B role
+* @param request             - Business Pay Bill request parameters
+* @returns                   Synchronous acknowledgement response from Daraja
+* @throws {PesafyError}      VALIDATION_ERROR for invalid input before HTTP call
+* @throws {PesafyError}      From httpRequest on network / API errors
+*/
+async function initiateB2BPayBill(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(B2BPayBillRequestSchema, request, "B2B Pay Bill request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: validated.commandId,
+		SenderIdentifierType: IDENTIFIER_TYPE$1,
+		RecieverIdentifierType: IDENTIFIER_TYPE$1,
+		Amount: String(amount),
+		PartyA: String(validated.partyA),
+		PartyB: String(validated.partyB),
+		AccountReference: validated.accountReference.slice(0, 13),
+		Remarks: validated.remarks ?? "Business Pay Bill",
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		ResultURL: validated.resultUrl
+	};
+	if (validated.requester?.trim()) payload["Requester"] = String(validated.requester);
+	if (validated.occasion?.trim()) payload["Occassion"] = validated.occasion;
+	const { data } = await httpRequest(`${baseUrl}${B2B_PAY_BILL_ENDPOINT}`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(B2BPayBillResponseSchema, data, "B2B Pay Bill response");
+}
+
+//#endregion
+//#region src/schemas/b2c.ts
+const B2CAsyncResponseSchema = z.object({
+	ConversationID: z.string(),
+	OriginatorConversationID: z.string(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+/** B2C Account Top Up (BusinessPayToBulk) */
+const B2CRequestSchema = z.object({
+	commandId: z.literal("BusinessPayToBulk"),
+	amount: KesAmountSchema,
+	partyA: NonEmptyStringSchema,
+	partyB: NonEmptyStringSchema,
+	accountReference: NonEmptyStringSchema,
+	requester: z.string().optional(),
+	remarks: z.string().optional(),
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema
+});
+const B2CResponseSchema = B2CAsyncResponseSchema;
+const B2CDisbursementRequestSchema = z.object({
+	commandId: z.enum([
+		"BusinessPayment",
+		"SalaryPayment",
+		"PromotionPayment"
+	]),
+	amount: z.number().finite().positive(),
+	partyA: NonEmptyStringSchema,
+	partyB: NonEmptyStringSchema,
+	remarks: NonEmptyStringSchema,
+	queueTimeOutUrl: UrlSchema,
+	resultUrl: UrlSchema,
+	originatorConversationId: NonEmptyStringSchema.optional(),
+	occasion: z.string().optional()
+});
+const B2CDisbursementResponseSchema = B2CAsyncResponseSchema;
+
+//#endregion
+//#region src/mpesa/b2c/payment.ts
+/**
+* src/mpesa/b2c/payment.ts
+*
+* Initiates a B2C Account Top Up via Safaricom Daraja.
+* Endpoint: POST /mpesa/b2b/v1/paymentrequest
+*
+* Strictly follows the Safaricom Daraja B2C Account Top Up API documentation:
+*   - CommandID must be "BusinessPayToBulk"
+*   - SenderIdentifierType is always "4" (hardcoded per docs)
+*   - RecieverIdentifierType is always "4" (hardcoded per docs)
+*   - Amount is sent as a string per the JSON spec
+*   - Requester is optional
+*/
+/** The only endpoint documented for this API */
+const B2C_ENDPOINT = "/mpesa/b2b/v1/paymentrequest";
+/**
+* Per documentation: SenderIdentifierType and RecieverIdentifierType
+* must always be "4" (Organisation ShortCode). Not configurable.
+*/
+const IDENTIFIER_TYPE = "4";
+/**
+* Initiates a B2C Account Top Up payment request.
+*
+* @param baseUrl         - Daraja base URL (sandbox or production)
+* @param accessToken     - Valid OAuth Bearer token
+* @param securityCredential - RSA-encrypted initiator password (base64)
+* @param initiatorName   - M-Pesa API operator username with B2B role
+* @param request         - B2C top-up request parameters
+* @returns               Synchronous acknowledgement response from Daraja
+* @throws {PesafyError}  VALIDATION_ERROR for invalid input before HTTP call
+* @throws {PesafyError}  From httpRequest on network / API errors
+*/
+async function initiateB2CPayment(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(B2CRequestSchema, request, "B2C request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: validated.commandId,
+		SenderIdentifierType: IDENTIFIER_TYPE,
+		RecieverIdentifierType: IDENTIFIER_TYPE,
+		Amount: String(amount),
+		PartyA: String(validated.partyA),
+		PartyB: String(validated.partyB),
+		AccountReference: validated.accountReference,
+		Remarks: validated.remarks ?? "B2C Account Top Up",
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		ResultURL: validated.resultUrl
+	};
+	if (validated.requester?.trim()) payload["Requester"] = String(validated.requester);
+	const { data } = await httpRequest(`${baseUrl}${B2C_ENDPOINT}`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(B2CResponseSchema, data, "B2C response");
+}
+
+//#endregion
+//#region src/mpesa/b2c/webhooks.ts
+/**
+* Runtime type guard — checks if a body looks like a B2C result callback.
+* Validates the minimum documented structure.
+*/
+function isB2CResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const result = b["Result"];
+	return (typeof result["ResultCode"] === "number" || typeof result["ResultCode"] === "string") && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+/**
+* Returns true if the B2C result represents a successful transaction.
+* Handles both string "0" (documented in success sample) and number 0.
+*/
+function isB2CSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+/**
+* Extracts the M-PESA transaction ID from a B2C result.
+* Present on both success and failure (generic ID on failure).
+*/
+function getB2CTransactionId(result) {
+	return result.Result.TransactionID ?? null;
+}
+/**
+* Extracts the OriginatorConversationID from a B2C result.
+* Use this to correlate with the original API call response.
+*/
+function getB2COriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+/**
+* Extracts the transaction amount from B2C result parameters.
+* Documented field: "Amount"
+* Returns null if not present (e.g. on failure).
+*/
+function getB2CAmount(result) {
+	const value = getB2CResultParam(result, "Amount");
+	if (value === void 0) return null;
+	const num = Number(value);
+	return Number.isFinite(num) ? num : null;
+}
+/**
+* Extracts a named value from B2C result parameters.
+* Handles both single-object and array forms of ResultParameter
+* (Daraja returns either depending on how many parameters are present).
+* Returns undefined if key is absent or no ResultParameters exist.
+*/
+function getB2CResultParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return (Array.isArray(params) ? params : [params]).find((p) => p.Key === key)?.Value;
+}
+
+//#endregion
+//#region src/mpesa/b2c-disbursement/payment.ts
+/**
+* src/mpesa/b2c-disbursement/payment.ts
+*
+* Initiates a B2C Disbursement payment (Salary / Cashback / Promotion).
+* Endpoint: POST /mpesa/b2c/v3/paymentrequest
+*/
+const B2C_DISBURSEMENT_ENDPOINT = "/mpesa/b2c/v3/paymentrequest";
+const VALID_COMMAND_IDS = new Set([
+	"BusinessPayment",
+	"SalaryPayment",
+	"PromotionPayment"
+]);
+/**
+* Initiates a B2C disbursement payment request.
+*
+* @param baseUrl              - Daraja base URL (sandbox or production)
+* @param accessToken          - Valid OAuth Bearer token
+* @param securityCredential   - RSA-encrypted initiator password (base64)
+* @param initiatorName        - M-Pesa API operator username
+* @param request              - B2C disbursement request parameters
+*/
+async function initiateB2CDisbursement(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const originatorConversationId = request.originatorConversationId?.trim() || generateOriginatorConversationId();
+	const validated = parseWithSchema(B2CDisbursementRequestSchema, {
+		...request,
+		originatorConversationId
+	}, "B2C Disbursement request");
+	if (!validated.commandId || !VALID_COMMAND_IDS.has(validated.commandId)) throw createError({
+		code: "VALIDATION_ERROR",
+		message: `commandId must be one of: BusinessPayment, SalaryPayment, PromotionPayment. Got "${validated.commandId}".`
+	});
+	const amount = Math.round(validated.amount);
+	if (!Number.isFinite(amount) || amount < 10) throw createError({
+		code: "VALIDATION_ERROR",
+		message: `amount must be ≥ 10 KES (got ${validated.amount} which rounds to ${amount}).`
+	});
+	if (!validated.partyA?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "partyA is required — the sending organisation shortcode."
+	});
+	if (!validated.partyB?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "partyB is required — the receiving customer MSISDN (2547XXXXXXXX)."
+	});
+	if (!validated.remarks?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "remarks is required (2–100 characters)."
+	});
+	if (!validated.resultUrl?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "resultUrl is required — Safaricom POSTs the async result here."
+	});
+	if (!validated.queueTimeOutUrl?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "queueTimeOutUrl is required — Safaricom calls this on request timeout."
+	});
+	const payload = {
+		OriginatorConversationID: originatorConversationId,
+		InitiatorName: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: validated.commandId,
+		Amount: amount,
+		PartyA: String(validated.partyA),
+		PartyB: String(validated.partyB),
+		Remarks: validated.remarks,
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		ResultURL: validated.resultUrl
+	};
+	if (validated.occasion?.trim()) payload["Occassion"] = validated.occasion;
+	const { data } = await httpRequest(`${baseUrl}${B2C_DISBURSEMENT_ENDPOINT}`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(B2CDisbursementResponseSchema, data, "B2C Disbursement response");
+}
+
+//#endregion
+//#region src/mpesa/b2c-disbursement/webhooks.ts
+function isB2CDisbursementResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const result = b["Result"];
+	return (typeof result["ResultCode"] === "number" || typeof result["ResultCode"] === "string") && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+function isB2CDisbursementSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+
+//#endregion
+//#region src/schemas/bill-manager.ts
+const SendRemindersSchema = z.enum(["0", "1"]);
+const BillManagerOptInRequestSchema = z.object({
+	shortcode: NonEmptyStringSchema,
+	email: NonEmptyStringSchema,
+	officialContact: NonEmptyStringSchema,
+	sendReminders: SendRemindersSchema,
+	logo: z.string().optional(),
+	callbackUrl: UrlSchema
+});
+const BillManagerOptInResponseSchema = z.object({
+	app_key: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+const BillManagerUpdateOptInRequestSchema = BillManagerOptInRequestSchema;
+const BillManagerUpdateOptInResponseSchema = z.object({
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+const BillManagerInvoiceItemSchema = z.object({
+	itemName: NonEmptyStringSchema,
+	amount: KesAmountSchema
+});
+const BillManagerSingleInvoiceRequestSchema = z.object({
+	externalReference: NonEmptyStringSchema,
+	billedFullName: NonEmptyStringSchema,
+	billedPhoneNumber: NonEmptyStringSchema,
+	billedPeriod: NonEmptyStringSchema,
+	invoiceName: NonEmptyStringSchema,
+	dueDate: NonEmptyStringSchema,
+	accountReference: NonEmptyStringSchema,
+	amount: KesAmountSchema,
+	invoiceItems: z.array(BillManagerInvoiceItemSchema).optional()
+});
+const BillManagerSingleInvoiceResponseSchema = z.object({
+	Status_Message: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+const BillManagerBulkInvoiceRequestSchema = z.object({ invoices: z.array(BillManagerSingleInvoiceRequestSchema).min(1).max(1e3) });
+const BillManagerBulkInvoiceResponseSchema = z.object({
+	Status_Message: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+const BillManagerCancelInvoiceRequestSchema = z.object({ externalReference: NonEmptyStringSchema });
+const BillManagerCancelInvoiceResponseSchema = z.object({
+	Status_Message: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string(),
+	errors: z.array(z.unknown()).optional()
+}).passthrough();
+const BillManagerCancelBulkInvoiceRequestSchema = z.object({ externalReferences: z.array(NonEmptyStringSchema).min(1) });
+const BillManagerCancelBulkInvoiceResponseSchema = z.object({
+	Status_Message: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string(),
+	errors: z.array(z.unknown()).optional()
+}).passthrough();
+const BillManagerReconciliationRequestSchema = z.object({
+	paymentDate: NonEmptyStringSchema,
+	paidAmount: NonEmptyStringSchema,
+	accountReference: NonEmptyStringSchema,
+	transactionId: NonEmptyStringSchema,
+	phoneNumber: NonEmptyStringSchema,
+	fullName: NonEmptyStringSchema,
+	invoiceName: NonEmptyStringSchema,
+	externalReference: NonEmptyStringSchema
+});
+const BillManagerReconciliationResponseSchema = z.object({
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+
+//#endregion
+//#region src/mpesa/bill-manager/invoice.ts
+/**
+* src/mpesa/bill-manager/invoice.ts
+*
+* Bill Manager — opt-in, invoice creation/cancellation, and payment reconciliation.
+*
+* 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
+*/
+async function billManagerOptIn(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerOptInRequestSchema, request, "Bill Manager opt-in request");
+	const payload = {
+		shortcode: validated.shortcode,
+		email: validated.email,
+		officialContact: validated.officialContact,
+		sendReminders: validated.sendReminders,
+		logo: validated.logo ?? "",
+		callbackurl: validated.callbackUrl
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/optin`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerOptInResponseSchema, data, "Bill Manager opt-in response");
+}
+async function updateOptIn(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerUpdateOptInRequestSchema, request, "Bill Manager update opt-in request");
+	const payload = {
+		shortcode: validated.shortcode,
+		email: validated.email,
+		officialContact: validated.officialContact,
+		sendReminders: validated.sendReminders,
+		logo: validated.logo ?? "",
+		callbackurl: validated.callbackUrl
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/change-optin-details`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerUpdateOptInResponseSchema, data, "Bill Manager update opt-in response");
+}
+async function sendSingleInvoice(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerSingleInvoiceRequestSchema, request, "Bill Manager single invoice request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		externalReference: validated.externalReference,
+		billedFullName: validated.billedFullName,
+		billedPhoneNumber: validated.billedPhoneNumber,
+		billedPeriod: validated.billedPeriod,
+		invoiceName: validated.invoiceName,
+		dueDate: validated.dueDate,
+		accountReference: validated.accountReference,
+		amount: String(amount),
+		invoiceItems: validated.invoiceItems?.map((i) => ({
+			itemName: i.itemName,
+			amount: String(Math.round(i.amount))
+		})) ?? []
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/single-invoicing`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerSingleInvoiceResponseSchema, data, "Bill Manager single invoice response");
+}
+async function sendBulkInvoices(baseUrl, accessToken, request, http) {
+	const payload = parseWithSchema(BillManagerBulkInvoiceRequestSchema, request, "Bill Manager bulk invoice request").invoices.map((inv) => ({
+		externalReference: inv.externalReference,
+		billedFullName: inv.billedFullName,
+		billedPhoneNumber: inv.billedPhoneNumber,
+		billedPeriod: inv.billedPeriod,
+		invoiceName: inv.invoiceName,
+		dueDate: inv.dueDate,
+		accountReference: inv.accountReference,
+		amount: String(Math.round(inv.amount)),
+		invoiceItems: inv.invoiceItems?.map((item) => ({
+			itemName: item.itemName,
+			amount: String(Math.round(item.amount))
+		})) ?? []
+	}));
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/bulk-invoicing`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerBulkInvoiceResponseSchema, data, "Bill Manager bulk invoice response");
+}
+async function cancelInvoice(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerCancelInvoiceRequestSchema, request, "Bill Manager cancel invoice request");
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/cancel-single-invoice`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: { externalReference: validated.externalReference }
+	}, http));
+	return parseWithSchema(BillManagerCancelInvoiceResponseSchema, data, "Bill Manager cancel invoice response");
+}
+async function cancelBulkInvoices(baseUrl, accessToken, request, http) {
+	const payload = parseWithSchema(BillManagerCancelBulkInvoiceRequestSchema, request, "Bill Manager cancel bulk invoices request").externalReferences.map((ref) => ({ externalReference: ref }));
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/cancel-bulk-invoices`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerCancelBulkInvoiceResponseSchema, data, "Bill Manager cancel bulk invoices response");
+}
+async function reconcilePayment(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerReconciliationRequestSchema, request, "Bill Manager reconciliation request");
+	const payload = {
+		paymentDate: validated.paymentDate,
+		paidAmount: validated.paidAmount,
+		accountReference: validated.accountReference,
+		transactionId: validated.transactionId,
+		phoneNumber: validated.phoneNumber,
+		fullName: validated.fullName,
+		invoiceName: validated.invoiceName,
+		externalReference: validated.externalReference
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/reconciliation`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerReconciliationResponseSchema, data, "Bill Manager reconciliation response");
+}
+
+//#endregion
+//#region src/schemas/c2b.ts
+const C2BRegisterUrlRequestSchema = z.object({
+	shortCode: NonEmptyStringSchema,
+	responseType: z.enum(["Completed", "Cancelled"]),
+	confirmationUrl: UrlSchema,
+	validationUrl: UrlSchema,
+	apiVersion: z.enum(["v1", "v2"]).optional()
+});
+const C2BBaseResponseSchema = z.object({
+	OriginatorCoversationID: z.string(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+const C2BRegisterUrlResponseSchema = C2BBaseResponseSchema;
+const C2BSimulateResponseSchema = C2BBaseResponseSchema;
+const C2BSimulateRequestSchema = z.object({
+	shortCode: z.union([NonEmptyStringSchema, z.number()]),
+	commandId: z.enum(["CustomerPayBillOnline", "CustomerBuyGoodsOnline"]),
+	amount: KesAmountSchema,
+	msisdn: z.union([NonEmptyStringSchema, z.number()]),
+	billRefNumber: z.union([NonEmptyStringSchema, z.null()]).optional(),
+	apiVersion: z.enum(["v1", "v2"]).optional()
+}).superRefine((data, ctx) => {
+	if (data.commandId === "CustomerPayBillOnline" && !data.billRefNumber?.trim()) ctx.addIssue({
+		code: "custom",
+		message: "billRefNumber is required for CustomerPayBillOnline",
+		path: ["billRefNumber"]
+	});
+});
+const C2BValidationWebhookSchema = z.object({
+	TransactionType: z.string(),
+	TransID: z.string(),
+	TransTime: z.string(),
+	TransAmount: z.union([z.string(), z.number()]),
+	BusinessShortCode: z.string(),
+	BillRefNumber: z.string().optional(),
+	MSISDN: z.string()
+}).passthrough();
+
+//#endregion
+//#region src/mpesa/c2b/register-url.ts
+/**
+* src/mpesa/c2b/register-url.ts
+*
+* C2B Register URL implementation.
+* Strictly aligned with Safaricom Daraja C2B Register URL API documentation.
+*
+* Endpoint (v1 — documented primary):
+*   Sandbox:    POST https://sandbox.safaricom.co.ke/mpesa/c2b/v1/registerurl
+*   Production: POST https://api.safaricom.co.ke/mpesa/c2b/v1/registerurl
+*
+* Also supports v2 via the apiVersion option.
+*/
+/**
+* Forbidden URL keywords per Daraja documentation:
+* "Avoid keywords such as M-PESA, M-Pesa, Safaricom, exe, exec, cme, or variants in your URLs."
+*
+* We lowercase-compare, so "MPESA", "Mpesa", "mPeSa" are all caught.
+*
+* Additional blocked keywords (documented variants): cmd, sql, query
+*/
+const FORBIDDEN_URL_KEYWORDS = [
+	"mpesa",
+	"safaricom",
+	"exec",
+	"exe",
+	"cme",
+	"cmd",
+	"sql",
+	"query"
+];
+/**
+* Validates a callback URL against Daraja's documented URL requirements.
+* Throws PesafyError if the URL violates any documented rule.
+*/
+function validateCallbackUrl(url, fieldName) {
+	if (!url || !url.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: `${fieldName} is required`
+	});
+	const lower = url.toLowerCase();
+	for (const keyword of FORBIDDEN_URL_KEYWORDS) if (lower.includes(keyword)) throw createError({
+		code: "VALIDATION_ERROR",
+		message: `${fieldName} must not contain the keyword "${keyword}". Daraja rejects URLs containing: mpesa, safaricom, exe, exec, cme (and variants: cmd, sql, query).`
+	});
+}
+/**
+* Registers C2B Confirmation and Validation URLs with Safaricom.
+*
+* Per Daraja documentation:
+*   - Sandbox: may be called multiple times (URLs can be overwritten).
+*   - Production: one-time call. To change URLs, delete existing on the portal
+*     or email apisupport@safaricom.co.ke, then re-register.
+*   - ResponseType must be sentence-case: "Completed" or "Cancelled".
+*   - Both URLs must be publicly accessible and internet-reachable.
+*   - Production requires HTTPS; Sandbox allows HTTP.
+*   - Do not use public URL testers (ngrok, mockbin, requestbin) — they are blocked.
+*   - The Validation URL is only called when external validation is enabled.
+*     To activate, email apisupport@safaricom.co.ke.
+*   - If M-PESA cannot reach your Validation URL within ~8 seconds, it defaults
+*     to the ResponseType action set during registration.
+*
+* @param baseUrl     - Daraja environment base URL
+* @param accessToken - Valid OAuth bearer token from Authorization API
+* @param request     - Registration parameters
+* @returns           - Daraja registration response (ResponseCode "0" = success)
+*/
+async function registerC2BUrls(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(C2BRegisterUrlRequestSchema, request, "C2B Register URL request");
+	validateCallbackUrl(validated.confirmationUrl, "confirmationUrl");
+	validateCallbackUrl(validated.validationUrl, "validationUrl");
+	const version = validated.apiVersion ?? "v2";
+	const payload = {
+		ShortCode: String(validated.shortCode),
+		ResponseType: validated.responseType,
+		ConfirmationURL: validated.confirmationUrl,
+		ValidationURL: validated.validationUrl
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/c2b/${version}/registerurl`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(C2BRegisterUrlResponseSchema, data, "C2B Register URL response");
+}
+
+//#endregion
+//#region src/mpesa/c2b/simulate.ts
+/**
+* src/mpesa/c2b/simulate.ts
+*
+* C2B Simulate implementation (Sandbox ONLY).
+* Strictly aligned with Safaricom Daraja C2B API documentation.
+*
+* Per docs: "NB: Simulation is not supported on production."
+*
+* Endpoint (v2, sandbox only):
+*   POST https://sandbox.safaricom.co.ke/mpesa/c2b/v2/simulate
+*/
+/**
+* Simulates a C2B customer payment. SANDBOX ONLY.
+*
+* Daraja payload shape:
+* {
+*   "ShortCode":     600984,                   ← numeric
+*   "CommandID":     "CustomerPayBillOnline",
+*   "Amount":        1,                        ← numeric, whole number ≥ 1
+*   "Msisdn":        254708374149,             ← numeric
+*   "BillRefNumber": "AccountRef"              ← Paybill only; OMIT for BuyGoods
+* }
+*
+* CRITICAL — BillRefNumber handling (per docs):
+*   "Account reference for Customer paybills and null for customer buy goods"
+*   We omit the key entirely for BuyGoods (not null, not "") because Daraja
+*   validates field presence and rejects even null/empty values for Buy Goods.
+*
+* @param baseUrl     - Must be the sandbox base URL
+* @param accessToken - Valid OAuth bearer token from Authorization API
+* @param request     - Simulation parameters
+* @returns           - Daraja simulate response (ResponseCode "0" = accepted)
+*/
+async function simulateC2B(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(C2BSimulateRequestSchema, request, "C2B Simulate request");
+	if (!baseUrl.includes("sandbox")) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "C2B simulate is only available in the Sandbox environment (per Daraja docs). In production, customers initiate payments directly via M-PESA App, USSD, or SIM Toolkit."
+	});
+	const amount = Math.round(validated.amount);
+	const isBuyGoods = validated.commandId === "CustomerBuyGoodsOnline";
+	const version = validated.apiVersion ?? "v2";
+	const payload = {
+		ShortCode: Number(validated.shortCode),
+		CommandID: validated.commandId,
+		Amount: amount,
+		Msisdn: Number(validated.msisdn)
+	};
+	if (!isBuyGoods) payload["BillRefNumber"] = validated.billRefNumber.trim();
+	const { data } = await httpRequest(`${baseUrl}/mpesa/c2b/${version}/simulate`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(C2BSimulateResponseSchema, data, "C2B Simulate response");
+}
+
+//#endregion
+//#region src/mpesa/c2b/webhooks.ts
+/**
+* Builds an "accept" validation response.
+*
+* Per Daraja docs (to accept the payment):
+*   { "ResultCode": "0", "ResultDesc": "Accepted" }
+*
+* @param thirdPartyTransID - Optional: echo back the ThirdPartyTransID received
+*   in the validation request. M-PESA includes it in the confirmation callback.
+*/
+function acceptC2BValidation(thirdPartyTransID) {
+	return {
+		ResultCode: "0",
+		ResultDesc: "Accepted",
+		...thirdPartyTransID ? { ThirdPartyTransID: thirdPartyTransID } : {}
+	};
+}
+
+//#endregion
+//#region src/mpesa/dynamic-qr/generate.ts
+/**
+* src/mpesa/dynamic-qr/generate.ts
+*
+* Core logic for the Safaricom Daraja Dynamic QR Code API.
+*
+* API: POST /mpesa/qrcode/v1/generate
+*
+* Error codes from Daraja docs:
+*   404.001.04 — Invalid Authentication Header
+*   400.002.05 — Invalid Request Payload
+*   400.003.01 — Invalid Access Token
+*/
+/**
+* Maps Daraja-specific error codes to structured PesafyErrors with
+* actionable developer guidance.
+*
+* @internal
+*/
+function mapDarajaError(errorCode, errorMessage) {
+	switch (errorCode) {
+		case "404.001.04": return new PesafyError({
+			code: "AUTH_FAILED",
+			message: `Daraja rejected the request due to an invalid authentication header. Ensure the Dynamic QR endpoint is called with POST and that the Authorization: Bearer <token> header is present. Daraja: "${errorMessage}"`,
+			statusCode: 404
+		});
+		case "400.003.01": return new PesafyError({
+			code: "AUTH_FAILED",
+			message: `The M-PESA access token is invalid or has expired. Call clearTokenCache() on the Mpesa instance to force a token refresh and retry the request. Daraja: "${errorMessage}"`,
+			statusCode: 401
+		});
+		case "400.002.05": return new PesafyError({
+			code: "VALIDATION_ERROR",
+			message: `Daraja rejected the request payload as malformed. Verify that all required fields (MerchantName, RefNo, Amount, TrxCode, CPI, Size) are present and have correct types. Daraja: "${errorMessage}"`,
+			statusCode: 400
+		});
+		default: return new PesafyError({
+			code: "REQUEST_FAILED",
+			message: `Dynamic QR request failed (${errorCode}): ${errorMessage}`,
+			statusCode: 400
+		});
+	}
+}
+/**
+* Returns `true` when the raw response body looks like a Daraja error object.
+* @internal
+*/
+function isDarajaError(body) {
+	return typeof body === "object" && body !== null && "errorCode" in body && typeof body.errorCode === "string";
+}
+/**
+* Returns `true` when the response has the required QR success fields.
+* @internal
+*/
+function isDarajaSuccess(body) {
+	return typeof body === "object" && body !== null && "ResponseCode" in body && "QRCode" in body && typeof body.QRCode === "string" && body.QRCode.length > 0;
+}
+/**
+* Generates a Dynamic M-PESA QR Code via the Safaricom Daraja API.
+*
+* The QR code can be rendered directly in a browser as a base64 PNG:
+* ```html
+* <img src="data:image/png;base64,{response.QRCode}" />
+* ```
+* Or written to disk:
+* ```ts
+* import { writeFileSync } from 'node:fs'
+* writeFileSync('qr.png', Buffer.from(response.QRCode, 'base64'))
+* ```
+*
+* @param baseUrl     - Daraja base URL (`https://sandbox.safaricom.co.ke` or
+*                      `https://api.safaricom.co.ke`)
+* @param accessToken - Valid Daraja OAuth2 Bearer token
+* @param request     - QR generation parameters (see {@link DynamicQRRequest})
+* @returns           - Daraja response including the base64-encoded QR image
+*
+* @throws {PesafyError} `VALIDATION_ERROR`  — payload failed pre-flight checks
+* @throws {PesafyError} `AUTH_FAILED`       — bad/expired token or wrong headers
+* @throws {PesafyError} `REQUEST_FAILED`    — unexpected Daraja error
+*
+* @example
+* ```ts
+* const response = await generateDynamicQR(
+*   'https://sandbox.safaricom.co.ke',
+*   accessToken,
+*   {
+*     merchantName: 'Test Supermarket',
+*     refNo:        'INV-001',
+*     amount:       500,
+*     trxCode:      'BG',
+*     cpi:          '373132',
+*     size:         300,
+*   },
+* )
+* console.log(response.QRCode) // base64 PNG
+* ```
+*/
+async function generateDynamicQR(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(DynamicQRRequestSchema, request, "Dynamic QR request");
+	if (!accessToken || typeof accessToken !== "string" || accessToken.trim().length === 0) throw new PesafyError({
+		code: "AUTH_FAILED",
+		message: "accessToken is required. Obtain one via the Daraja Authorization API (GET /oauth/v1/generate?grant_type=client_credentials)."
+	});
+	const size = validated.size ?? 300;
+	const amount = Math.round(validated.amount);
+	const payload = {
+		MerchantName: validated.merchantName.trim(),
+		RefNo: validated.refNo.trim(),
+		Amount: amount,
+		TrxCode: validated.trxCode,
+		CPI: validated.cpi.trim(),
+		Size: String(size)
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/qrcode/v1/generate`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	if (isDarajaError(data)) throw mapDarajaError(data.errorCode, data.errorMessage);
+	if (!isDarajaSuccess(data)) throw new PesafyError({
+		code: "REQUEST_FAILED",
+		message: `Daraja returned an unexpected response structure for the Dynamic QR request. The response was missing required fields (ResponseCode, QRCode). Raw response: ${JSON.stringify(data).slice(0, 300)}`
+	});
+	return parseWithSchema(DynamicQRResponseSchema, data, "Dynamic QR response");
+}
+
+//#endregion
+//#region src/mpesa/reversal/types.ts
+/**
+* src/mpesa/reversal/types.ts
+*
+* Transaction Reversal types, constants, and helpers.
+*
+* API: POST /mpesa/reversal/v1/request
+*
+* Reverses a completed M-PESA C2B transaction. The API is ASYNCHRONOUS —
+* the synchronous response is only an acknowledgement. The actual reversal
+* result is POSTed to your ResultURL after processing.
+*
+* Required org portal role: "Org Reversals Initiator"
+*
+* Per Daraja docs:
+*   RecieverIdentifierType MUST always be "11" for reversals.
+*   CommandID MUST always be "TransactionReversal".
+*
+* Ref: Reversals — Safaricom Daraja Developer Portal
+*/
+/**
+* CommandID for the Reversals API.
+* Only "TransactionReversal" is allowed per Daraja docs.
+*/
+const REVERSAL_COMMAND_ID = "TransactionReversal";
+/**
+* Result codes returned in the async callback POSTed to your ResultURL.
+*
+* Per Daraja Reversals documentation:
+*
+* | ResultCode | Meaning                                            |
+* |------------|----------------------------------------------------|
+* | 0          | Success — transaction reversed                     |
+* | 1          | Insufficient balance                               |
+* | 11         | DebitParty in invalid state (shortcode not active) |
+* | 21         | Initiator not allowed to initiate reversals        |
+* | 2001       | Initiator information invalid (bad credentials)    |
+* | 2006       | Declined due to account rule (shortcode inactive)  |
+* | 2028       | Not permitted (shortcode lacks reversal permission)|
+* | 8006       | Security credential locked                         |
+* | R000001    | Transaction already reversed                       |
+* | R000002    | OriginalTransactionID is invalid / does not exist  |
+*/
+const REVERSAL_RESULT_CODES = {
+	SUCCESS: 0,
+	INSUFFICIENT_BALANCE: 1,
+	DEBIT_PARTY_INVALID_STATE: 11,
+	INITIATOR_NOT_ALLOWED: 21,
+	INITIATOR_INFORMATION_INVALID: 2001,
+	DECLINED_ACCOUNT_RULE: 2006,
+	NOT_PERMITTED: 2028,
+	SECURITY_CREDENTIAL_LOCKED: 8006,
+	ALREADY_REVERSED: "R000001",
+	INVALID_TRANSACTION_ID: "R000002"
+};
+/**
+* Returns true when the payload matches the shape of a ReversalResult.
+* Works for both success and failure callbacks.
+*/
+function isReversalResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const r = b["Result"];
+	return typeof r["ResultCode"] !== "undefined" && typeof r["ResultDesc"] === "string" && typeof r["ConversationID"] === "string";
+}
+/**
+* Returns true when the reversal result indicates a successful reversal.
+* A successful reversal has ResultCode === 0 (number).
+*/
+function isReversalSuccess(result) {
+	return result.Result.ResultCode === REVERSAL_RESULT_CODES.SUCCESS;
+}
+/**
+* Extracts the M-PESA receipt number for the reversal transaction.
+* Returns null if the result does not contain a TransactionID.
+*/
+function getReversalTransactionId(result) {
+	return result.Result.TransactionID ?? null;
+}
+
+//#endregion
+//#region src/mpesa/reversal/request.ts
+/**
+* src/mpesa/reversal/request.ts
+*
+* Transaction Reversal — reverses a completed M-PESA C2B transaction.
+*
+* API: POST /mpesa/reversal/v1/request
+*
+* ASYNCHRONOUS: The synchronous response is acknowledgement only.
+* The actual reversal result is POSTed to your ResultURL after processing.
+*
+* Per Daraja docs:
+*   - CommandID is always "TransactionReversal"
+*   - RecieverIdentifierType is always "11" (Organisation ShortCode for reversals)
+*   - Amount is sent as a string per the Daraja sample payload
+*   - Remarks must be 2–100 characters
+*   - Cannot be used for B2C reversals (those are done on the M-PESA portal)
+*
+* Required org portal role: "Org Reversals Initiator"
+*/
+async function requestReversal(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(ReversalRequestSchema, request, "Reversal request");
+	const amount = Math.round(validated.amount);
+	const remarks = validated.remarks ?? "Transaction Reversal";
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: REVERSAL_COMMAND_ID,
+		TransactionID: validated.transactionId,
+		Amount: String(amount),
+		ReceiverParty: String(validated.receiverParty),
+		RecieverIdentifierType: "11",
+		ResultURL: validated.resultUrl,
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		Remarks: remarks
+	};
+	if (validated.occasion !== void 0 && validated.occasion !== null) payload["Occasion"] = validated.occasion;
+	const { data } = await httpRequest(`${baseUrl}/mpesa/reversal/v1/request`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(ReversalResponseSchema, data, "Reversal response");
+}
+
+//#endregion
+//#region src/schemas/stk-push.ts
+const TransactionTypeSchema = z.enum(["CustomerPayBillOnline", "CustomerBuyGoodsOnline"]);
+const StkPushRequestSchema = z.object({
+	amount: z.number().finite({ message: "amount must be a finite number (not NaN or Infinity)" }),
+	phoneNumber: NonEmptyStringSchema,
+	shortCode: NonEmptyStringSchema,
+	passKey: NonEmptyStringSchema,
+	callbackUrl: UrlSchema,
+	accountReference: NonEmptyStringSchema,
+	transactionDesc: NonEmptyStringSchema,
+	transactionType: TransactionTypeSchema.optional(),
+	partyB: z.string().optional()
+});
+const StkPushResponseSchema = z.object({
+	MerchantRequestID: z.string(),
+	CheckoutRequestID: z.string(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string(),
+	CustomerMessage: z.string().optional()
+}).passthrough();
+const StkQueryRequestSchema = z.object({
+	checkoutRequestId: NonEmptyStringSchema,
+	shortCode: NonEmptyStringSchema,
+	passKey: NonEmptyStringSchema
+});
+const StkQueryResponseSchema = z.object({
+	ResponseCode: z.string(),
+	ResponseDescription: z.string(),
+	MerchantRequestID: z.string().optional(),
+	CheckoutRequestID: z.string().optional(),
+	ResultCode: z.union([z.string(), z.number()]).optional(),
+	ResultDesc: z.string().optional()
+}).passthrough();
+const StkPushWebhookSchema = z.object({ Body: z.object({ stkCallback: z.object({
+	MerchantRequestID: z.string(),
+	CheckoutRequestID: z.string(),
+	ResultCode: z.number(),
+	ResultDesc: z.string(),
+	CallbackMetadata: z.object({ Item: z.array(z.object({
+		Name: z.string(),
+		Value: z.union([z.string(), z.number()])
+	})) }).optional()
+}).passthrough() }) });
+
+//#endregion
+//#region src/mpesa/stk-push/types.ts
+/**
+* M-PESA transaction limits as documented by Safaricom Daraja.
+*
+* | Limit            | Value      |
+* |------------------|-----------|
+* | Min per tx       | KES 1     |
+* | Max per tx       | KES 250 000|
+* | Max daily        | KES 500 000|
+* | Max balance      | KES 500 000|
+*/
+const STK_PUSH_LIMITS = {
+	MIN_AMOUNT: 1,
+	MAX_AMOUNT: 25e4
+};
+
+//#endregion
+//#region src/utils/phone/index.ts
+/** Normalises any common Kenyan phone format to 254XXXXXXXXX (12 digits) */
+function formatSafaricomPhone(phone) {
+	const digits = phone.replace(/\D/g, "");
+	let n;
+	if (digits.startsWith("254") && digits.length === 12) n = digits;
+	else if (digits.startsWith("0") && digits.length === 10) n = `254${digits.slice(1)}`;
+	else if (digits.length === 9) n = `254${digits}`;
+	else throw new PesafyError({
+		code: "INVALID_PHONE",
+		message: `Cannot parse "${phone}". Use 07XXXXXXXX, 2547XXXXXXXX, 2541XXXXXXXX (Airtel), or +2547XXXXXXXX.`
+	});
+	/* v8 ignore next 6 -- unreachable: all branches above assign exactly 12 digits */
+	if (n.length !== 12) throw new PesafyError({
+		code: "INVALID_PHONE",
+		message: `"${phone}" normalised to "${n}" — expected 12 digits.`
+	});
+	return n;
+}
+
+//#endregion
+//#region src/mpesa/stk-push/utils.ts
+/**
+* Generates the STK Push password.
+* Formula: Base64( Shortcode + Passkey + Timestamp )
+*
+* Uses btoa() — works in Node.js ≥18, Bun, browsers, and edge runtimes.
+*/
+function getStkPushPassword(shortCode, passKey, timestamp) {
+	return btoa(`${shortCode}${passKey}${timestamp}`);
+}
+/**
+* Returns a Daraja-compatible timestamp: YYYYMMDDHHmmss
+*
+* Call this ONCE per request and reuse the result.
+*/
+function getTimestamp() {
+	const now = /* @__PURE__ */ new Date();
+	const pad = (n) => n.toString().padStart(2, "0");
+	return [
+		now.getFullYear(),
+		pad(now.getMonth() + 1),
+		pad(now.getDate()),
+		pad(now.getHours()),
+		pad(now.getMinutes()),
+		pad(now.getSeconds())
+	].join("");
+}
+
+//#endregion
+//#region src/mpesa/stk-push/stk-push.ts
+/**
+* src/mpesa/stk-push/stk-push.ts
+*
+* Initiates an STK Push (M-PESA Express) payment.
+*
+* Daraja endpoint: POST /mpesa/stkpush/v1/processrequest
+*
+* Transaction limits (Daraja docs):
+*   Min per transaction: KES 1
+*   Max per transaction: KES 250,000
+*/
+async function processStkPush(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(StkPushRequestSchema, request, "STK Push request");
+	if (!Number.isFinite(validated.amount)) throw new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `amount must be a finite number (got ${validated.amount}).`
+	});
+	const amount = Math.round(validated.amount);
+	if (amount < STK_PUSH_LIMITS.MIN_AMOUNT) throw new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `Amount must be at least KES ${STK_PUSH_LIMITS.MIN_AMOUNT} (got ${validated.amount} which rounds to ${amount}).`
+	});
+	if (amount > STK_PUSH_LIMITS.MAX_AMOUNT) throw new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `Amount must not exceed KES ${STK_PUSH_LIMITS.MAX_AMOUNT.toLocaleString()} per transaction as per Safaricom Daraja limits (got ${validated.amount} which rounds to ${amount}).`
+	});
+	const timestamp = getTimestamp();
+	const partyB = validated.partyB ?? validated.shortCode;
+	const body = {
+		BusinessShortCode: validated.shortCode,
+		Password: getStkPushPassword(validated.shortCode, validated.passKey, timestamp),
+		Timestamp: timestamp,
+		TransactionType: validated.transactionType ?? "CustomerPayBillOnline",
+		Amount: amount,
+		PartyA: formatSafaricomPhone(validated.phoneNumber),
+		PartyB: partyB,
+		PhoneNumber: formatSafaricomPhone(validated.phoneNumber),
+		CallBackURL: validated.callbackUrl,
+		AccountReference: validated.accountReference.slice(0, 12),
+		TransactionDesc: validated.transactionDesc.slice(0, 13)
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/stkpush/v1/processrequest`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body,
+		retries: 5,
+		retryDelay: 3e3
+	}, http));
+	return parseWithSchema(StkPushResponseSchema, data, "STK Push response");
+}
+
+//#endregion
+//#region src/mpesa/stk-push/stk-query.ts
+async function queryStkPush(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(StkQueryRequestSchema, request, "STK Query request");
+	const timestamp = getTimestamp();
+	const body = {
+		BusinessShortCode: validated.shortCode,
+		Password: getStkPushPassword(validated.shortCode, validated.passKey, timestamp),
+		Timestamp: timestamp,
+		CheckoutRequestID: validated.checkoutRequestId
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/stkpushquery/v1/query`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body
+	}, http));
+	return parseWithSchema(StkQueryResponseSchema, data, "STK Query response");
+}
+
+//#endregion
+//#region src/mpesa/tax-remittance/remit-tax.ts
+/** KRA's M-PESA shortcode — the only allowed PartyB for tax remittance */
+const KRA_SHORTCODE = "572572";
+/** The only CommandID accepted by the Tax Remittance API */
+const TAX_COMMAND_ID = "PayTaxToKRA";
+/**
+* Remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+*
+* Endpoint: POST /mpesa/b2b/v1/remittax
+*
+* @param baseUrl            - Daraja base URL (sandbox or production)
+* @param accessToken        - Valid OAuth bearer token
+* @param securityCredential - RSA-encrypted initiator password (base64)
+* @param initiatorName      - M-PESA org portal API operator username
+* @param request            - Tax remittance parameters
+* @returns                  - Daraja synchronous acknowledgement response
+*
+* @example
+* const response = await remitTax(
+*   'https://sandbox.safaricom.co.ke',
+*   accessToken,
+*   securityCredential,
+*   'TaxPayer',
+*   {
+*     amount:           239,
+*     partyA:           '888880',
+*     accountReference: '353353',
+*     resultUrl:        'https://example.org/b2b/remittax/result/',
+*     queueTimeOutUrl:  'https://example.org/b2b/remittax/queue/',
+*   },
+* )
+*/
+async function remitTax(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(TaxRemittanceRequestSchema, request, "Tax Remittance request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: TAX_COMMAND_ID,
+		SenderIdentifierType: "4",
+		RecieverIdentifierType: "4",
+		Amount: String(amount),
+		PartyA: String(validated.partyA),
+		PartyB: validated.partyB ?? "572572",
+		AccountReference: validated.accountReference,
+		Remarks: validated.remarks ?? "Tax Remittance",
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		ResultURL: validated.resultUrl
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/b2b/v1/remittax`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(TaxRemittanceResponseSchema, data, "Tax Remittance response");
+}
+
+//#endregion
+//#region src/mpesa/tax-remittance/webhooks.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normaliseResultCode(code) {
+	return typeof code === "string" ? Number(code) : code;
+}
+/**
+* Returns `true` when the value is a valid Tax Remittance async result payload
+* (the shape POSTed by Safaricom to your ResultURL).
+*
+* Checks the minimum required fields per the Daraja documentation:
+*   - Result.ResultCode
+*   - Result.ConversationID
+*   - Result.OriginatorConversationID
+*/
+function isTaxRemittanceResult(value) {
+	if (!isObject(value)) return false;
+	const root = value;
+	if (!isObject(root["Result"])) return false;
+	const result = root["Result"];
+	return result["ResultCode"] !== void 0 && result["ResultCode"] !== null && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+/**
+* Returns `true` when the Tax Remittance result indicates a successful
+* transaction — i.e. ResultCode is 0 or "0".
+*/
+function isTaxRemittanceSuccess(result) {
+	return normaliseResultCode(result.Result.ResultCode) === 0;
+}
+
+//#endregion
+//#region src/mpesa/transaction-status/query.ts
+/**
+* Transaction Status Query implementation
+*
+* API: POST /mpesa/transactionstatus/v1/query
+*
+* This is ASYNCHRONOUS. The synchronous response only acknowledges receipt.
+* Final results arrive via POST to your ResultURL.
+*
+* Required M-PESA org portal role: "Transaction Status query ORG API"
+*
+* Reconciliation options (at least one required):
+*   - transactionId          — M-Pesa Receipt Number (e.g. "NEF61H8J60")
+*   - originalConversationId — OriginatorConversationID from the original call
+*/
+async function queryTransactionStatus(baseUrl, token, securityCredential, initiator, request, http) {
+	const validated = parseWithSchema(TransactionStatusRequestSchema, request, "Transaction Status request");
+	const payload = {
+		Initiator: initiator,
+		SecurityCredential: securityCredential,
+		CommandID: validated.commandId ?? "TransactionStatusQuery",
+		TransactionID: validated.transactionId ?? "",
+		OriginalConversationID: validated.originalConversationId ?? "",
+		PartyA: validated.partyA,
+		IdentifierType: validated.identifierType,
+		ResultURL: validated.resultUrl,
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		Remarks: validated.remarks ?? "Transaction Status Query",
+		Occasion: validated.occasion ?? ""
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/transactionstatus/v1/query`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${token}` },
+		body: payload
+	}, http));
+	return parseWithSchema(TransactionStatusResponseSchema, data, "Transaction Status response");
+}
+
+//#endregion
+//#region src/mpesa/transaction-status/types.ts
+/**
+* Documented result codes for the Transaction Status async callback.
+* ResultCode 0 = success; anything else is a failure.
+*/
+const TRANSACTION_STATUS_RESULT_CODES = {
+	SUCCESS: 0,
+	INVALID_INITIATOR: 2001
+};
+
+//#endregion
+//#region src/mpesa/transaction-status/webhooks.ts
+/**
+* Type guards and payload extractors for Transaction Status result callbacks.
+*
+* Documented result parameters (POSTed to your ResultURL):
+*   - DebitPartyName
+*   - TransactionStatus
+*   - Amount
+*   - ReceiptNo
+*   - DebitAccountBalance
+*   - TransactionDate
+*   - CreditPartyName
+*
+* Docs note: ResultCode is 0 (number) on success. Daraja may return either
+* a number or a string depending on the transaction type — both forms handled.
+*
+* @see https://developer.safaricom.co.ke/APIs/TransactionStatus
+*/
+const KNOWN_RESULT_CODES = new Set(Object.values(TRANSACTION_STATUS_RESULT_CODES));
+/**
+* Runtime type guard — checks if a body looks like a Transaction Status
+* result callback. Validates the minimum documented structure.
+*/
+function isTransactionStatusResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const result = b["Result"];
+	return (typeof result["ResultCode"] === "number" || typeof result["ResultCode"] === "string") && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+/**
+* Returns true if the Transaction Status result represents a successful query.
+* Handles both string "0" and number 0 (Daraja inconsistency).
+*/
+function isTransactionStatusSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+
+//#endregion
+//#region src/mpesa/types.ts
+const DARAJA_BASE_URLS = {
+	sandbox: "https://sandbox.safaricom.co.ke",
+	production: "https://api.safaricom.co.ke"
+};
+
+//#endregion
+//#region src/mpesa/webhooks/hmac-verifier.ts
+/** Default algorithm until Safaricom documents the official scheme. */
+const DEFAULT_WEBHOOK_HMAC_ALGORITHM = "sha256";
+const ALGO_MAP = {
+	sha256: "SHA-256",
+	sha512: "SHA-512"
+};
+function hexToBytes(hex) {
+	const trimmed = hex.trim();
+	if (!/^[0-9a-fA-F]+$/.test(trimmed) || trimmed.length % 2 !== 0) return null;
+	const bytes = new Uint8Array(trimmed.length / 2);
+	for (let i = 0; i < bytes.length; i++) bytes[i] = Number.parseInt(trimmed.slice(i * 2, i * 2 + 2), 16);
+	return bytes;
+}
+function bytesToHex(bytes) {
+	return [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Constant-time comparison for equal-length byte arrays. */
+function timingSafeEqualBytes(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+	return diff === 0;
+}
+/**
+* Verify webhook HMAC signature (preview — opt-in until Safaricom publishes spec).
+* Uses Web Crypto (`globalThis.crypto.subtle`) for Node, Bun, Deno, and Workers.
+*/
+async function verifyWebhookHMAC(payload, signature, secret, algorithm = DEFAULT_WEBHOOK_HMAC_ALGORITHM) {
+	if (!secret || !signature) return false;
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) return false;
+	const body = typeof payload === "string" ? new TextEncoder().encode(payload) : payload instanceof Uint8Array ? payload : new Uint8Array(payload);
+	const sigBytes = hexToBytes(signature);
+	if (!sigBytes) return false;
+	try {
+		const key = await subtle.importKey("raw", new TextEncoder().encode(secret), {
+			name: "HMAC",
+			hash: ALGO_MAP[algorithm]
+		}, false, ["sign"]);
+		const expected = hexToBytes(bytesToHex(await subtle.sign("HMAC", key, body)));
+		if (!expected) return false;
+		return timingSafeEqualBytes(sigBytes, expected);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/mpesa/webhooks/signature-verifier.ts
+/** Official Safaricom API Gateway IP addresses */
+const SAFARICOM_IPS = [
+	"196.201.214.200",
+	"196.201.214.206",
+	"196.201.213.114",
+	"196.201.214.207",
+	"196.201.214.208",
+	"196.201.213.44",
+	"196.201.212.127",
+	"196.201.212.138",
+	"196.201.212.129",
+	"196.201.212.136",
+	"196.201.212.74",
+	"196.201.212.69"
+];
+/**
+* Returns true if requestIP is in the allowed list.
+* Defaults to the official Safaricom IP whitelist.
+*/
+function verifyWebhookIP(requestIP, allowedIPs = SAFARICOM_IPS) {
+	return allowedIPs.includes(requestIP);
+}
+/**
+* Combined webhook verification: IP allowlist (default) + optional HMAC.
+*/
+async function verifyWebhook(options) {
+	const errors = [];
+	const allowed = options.allowedIPs ?? SAFARICOM_IPS;
+	const ipValid = options.skipIPCheck === true || verifyWebhookIP(options.requestIP, allowed);
+	if (!ipValid) errors.push("Request IP is not in the Safaricom allowlist.");
+	let hmacValid = true;
+	if (options.secret && options.signature && options.rawBody !== void 0) {
+		hmacValid = await verifyWebhookHMAC(options.rawBody, options.signature, options.secret, options.hmacAlgorithm);
+		if (!hmacValid) errors.push("Webhook HMAC signature verification failed.");
+	} else if (options.requireHMAC) {
+		hmacValid = false;
+		errors.push("HMAC verification required but secret, signature, or rawBody missing.");
+	}
+	return {
+		valid: ipValid && hmacValid,
+		ipValid,
+		hmacValid,
+		errors
+	};
+}
+
+//#endregion
+//#region src/mpesa/webhooks/webhook-handler.ts
+/** Extracts the M-Pesa receipt number from a successful STK Push callback */
+function extractTransactionId(webhook) {
+	const item = (webhook.Body?.stkCallback?.CallbackMetadata?.Item)?.find((i) => i.Name === "MpesaReceiptNumber");
+	return item ? String(item.Value) : null;
+}
+/** Extracts the transaction amount from a successful STK Push callback */
+function extractAmount(webhook) {
+	const item = (webhook.Body?.stkCallback?.CallbackMetadata?.Item)?.find((i) => i.Name === "Amount");
+	return item ? Number(item.Value) : null;
+}
+/** Extracts the phone number from a successful STK Push callback */
+function extractPhoneNumber(webhook) {
+	const item = (webhook.Body?.stkCallback?.CallbackMetadata?.Item)?.find((i) => i.Name === "PhoneNumber");
+	return item ? String(item.Value) : null;
+}
+/** Returns true if the STK Push callback represents a successful transaction */
+function isSuccessfulCallback(webhook) {
+	return webhook.Body?.stkCallback?.ResultCode === 0;
+}
+
+//#endregion
+//#region src/mpesa/index.ts
+/**
+* src/mpesa/index.ts
+*
+* Primary M-PESA module entry point.
+*
+* Exports:
+*   1. Mpesa class — the main SDK client
+*   2. All submodule APIs, types, constants, and helpers
+*
+* Submodules re-exported here:
+*   - account-balance
+*   - b2b-buy-goods
+*   - b2b-express-checkout
+*   - b2b-pay-bill
+*   - b2c (Account Top Up)
+*   - b2c-disbursement
+*   - bill-manager
+*   - c2b
+*   - dynamic-qr
+*   - reversal
+*   - stk-push
+*   - tax-remittance
+*   - transaction-status
+*   - webhooks
+*/
+var Mpesa = class {
+	config;
+	tokenManager;
+	baseUrl;
+	idempotencyManager;
+	constructor(config) {
+		if (!config.consumerKey || !config.consumerSecret) throw new PesafyError({
+			code: "INVALID_CREDENTIALS",
+			message: "consumerKey and consumerSecret are required."
+		});
+		this.config = config;
+		this.baseUrl = DARAJA_BASE_URLS[config.environment];
+		this.tokenManager = new TokenManager(config.consumerKey, config.consumerSecret, this.baseUrl);
+		this.idempotencyManager = new IdempotencyManager(config.idempotency);
+	}
+	/** Idempotency options passed to all outbound Daraja HTTP calls. */
+	darajaHttp() {
+		return { idempotency: this.idempotencyManager };
+	}
+	getToken() {
+		return this.tokenManager.getAccessToken();
+	}
+	async buildSecurityCredential() {
+		if (this.config.securityCredential) return this.config.securityCredential;
+		if (!this.config.initiatorPassword) throw new PesafyError({
+			code: "INVALID_CREDENTIALS",
+			message: "Provide securityCredential (pre-encrypted) OR (initiatorPassword + certificatePath/certificatePem)."
+		});
+		let cert;
+		if (this.config.certificatePem) cert = this.config.certificatePem;
+		else if (this.config.certificatePath) cert = await readFile(this.config.certificatePath, "utf-8");
+		else throw new PesafyError({
+			code: "INVALID_CREDENTIALS",
+			message: "certificatePath or certificatePem is required to encrypt the initiator password."
+		});
+		return encryptSecurityCredential(this.config.initiatorPassword, cert);
+	}
+	requireInitiator(forApi) {
+		const name = this.config.initiatorName ?? "";
+		if (!name) throw new PesafyError({
+			code: "VALIDATION_ERROR",
+			message: `initiatorName is required for ${forApi}.`
+		});
+		return name;
+	}
+	async stkPushSafe(request) {
+		try {
+			return ok(await this.stkPush(request));
+		} catch (e) {
+			return err(e);
+		}
+	}
+	async accountBalanceSafe(request) {
+		try {
+			return ok(await this.accountBalance(request));
+		} catch (e) {
+			return err(e);
+		}
+	}
+	async stkPush(request) {
+		const shortCode = this.config.lipaNaMpesaShortCode ?? "";
+		const passKey = this.config.lipaNaMpesaPassKey ?? "";
+		if (!shortCode || !passKey) throw new PesafyError({
+			code: "VALIDATION_ERROR",
+			message: "lipaNaMpesaShortCode and lipaNaMpesaPassKey are required for STK Push."
+		});
+		const token = await this.getToken();
+		return processStkPush(this.baseUrl, token, {
+			...request,
+			shortCode,
+			passKey
+		}, this.darajaHttp());
+	}
+	async stkQuery(request) {
+		const shortCode = this.config.lipaNaMpesaShortCode ?? "";
+		const passKey = this.config.lipaNaMpesaPassKey ?? "";
+		if (!shortCode || !passKey) throw new PesafyError({
+			code: "VALIDATION_ERROR",
+			message: "lipaNaMpesaShortCode and lipaNaMpesaPassKey are required for STK Query."
+		});
+		const token = await this.getToken();
+		return queryStkPush(this.baseUrl, token, {
+			...request,
+			shortCode,
+			passKey
+		}, this.darajaHttp());
+	}
+	async transactionStatus(request) {
+		const initiator = this.requireInitiator("Transaction Status");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return queryTransactionStatus(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async accountBalance(request) {
+		const initiator = this.requireInitiator("Account Balance");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return queryAccountBalance(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async reverseTransaction(request) {
+		const initiator = this.requireInitiator("Reversal");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return requestReversal(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async generateDynamicQR(request) {
+		const token = await this.getToken();
+		return generateDynamicQR(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async registerC2BUrls(request) {
+		const token = await this.getToken();
+		return registerC2BUrls(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async simulateC2B(request) {
+		const token = await this.getToken();
+		return simulateC2B(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async remitTax(request) {
+		const initiator = this.requireInitiator("Tax Remittance");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return remitTax(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async b2bExpressCheckout(request) {
+		const token = await this.getToken();
+		return initiateB2BExpressCheckout(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async b2bBuyGoods(request) {
+		const initiator = this.requireInitiator("B2B Buy Goods");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return initiateB2BBuyGoods(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async b2bPayBill(request) {
+		const initiator = this.requireInitiator("B2B Pay Bill");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return initiateB2BPayBill(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async b2cPayment(request) {
+		const initiator = this.requireInitiator("B2C Payment");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return initiateB2CPayment(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async b2cDisbursement(request) {
+		const initiator = this.requireInitiator("B2C Disbursement");
+		const req = {
+			...request,
+			originatorConversationId: request.originatorConversationId ?? generateOriginatorConversationId()
+		};
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return initiateB2CDisbursement(this.baseUrl, token, cred, initiator, req, this.darajaHttp());
+	}
+	async billManagerOptIn(request) {
+		const token = await this.getToken();
+		return billManagerOptIn(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async updateOptIn(request) {
+		const token = await this.getToken();
+		return updateOptIn(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async sendInvoice(request) {
+		const token = await this.getToken();
+		return sendSingleInvoice(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async sendBulkInvoices(request) {
+		const token = await this.getToken();
+		return sendBulkInvoices(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async cancelInvoice(request) {
+		const token = await this.getToken();
+		return cancelInvoice(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async cancelBulkInvoices(request) {
+		const token = await this.getToken();
+		return cancelBulkInvoices(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async reconcilePayment(request) {
+		const token = await this.getToken();
+		return reconcilePayment(this.baseUrl, token, request, this.darajaHttp());
+	}
+	clearTokenCache() {
+		this.tokenManager.clearCache();
+	}
+	get environment() {
+		return this.config.environment;
+	}
+};
+
+//#endregion
+//#region src/adapters/webhook-guard.ts
+const DEFAULT_SIGNATURE_HEADER = "x-safaricom-signature";
+/**
+* Verify webhook IP (+ optional HMAC). Logs warnings on failure; does not throw.
+* Returns whether verification passed (IP and HMAC when configured).
+*/
+async function guardWebhookRequest(requestIP, rawBody, getHeader, config) {
+	const headerName = config.signatureHeader ?? DEFAULT_SIGNATURE_HEADER;
+	const signature = getHeader(headerName) ?? getHeader(headerName.toLowerCase()) ?? getHeader(headerName.toUpperCase());
+	const result = await verifyWebhook({
+		requestIP,
+		...config.skipIPCheck !== void 0 ? { skipIPCheck: config.skipIPCheck } : {},
+		...config.webhookSecret !== void 0 ? { secret: config.webhookSecret } : {},
+		...signature !== void 0 ? { signature } : {},
+		...rawBody !== void 0 ? { rawBody } : {},
+		...config.requireHMAC !== void 0 ? { requireHMAC: config.requireHMAC } : {}
+	});
+	if (!result.valid) console.warn("[pesafy] Webhook verification failed:", result.errors.join("; "));
+	return result.valid;
+}
+
+//#endregion
+//#region src/adapters/shared/helpers.ts
+function resolveUrl(explicit, override, fallback, label) {
+	const resolved = explicit || override || fallback || "";
+	if (!resolved) throw new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `${label} is required. Set it in config or include it in the request body.`
+	});
+	return resolved;
+}
+function fireHook(fn, label) {
+	if (!fn) return;
+	fn().catch((err) => console.error(`[pesafy] ${label} hook error:`, err));
+}
+
+//#endregion
+//#region src/adapters/shared/handlers.ts
+async function runWebhookGuard(ctx, config) {
+	if (!await guardWebhookRequest(ctx.requestIP, ctx.rawBody, ctx.getHeader, config)) throw new PesafyError({
+		code: "AUTH_FAILED",
+		message: "Webhook verification failed: invalid source IP or HMAC signature",
+		statusCode: 403
+	});
+}
+function createRouteHandlers(mpesa, config) {
+	return {
+		"stk.push": async (ctx) => {
+			const { amount, phoneNumber, accountReference, transactionDesc, transactionType, partyB } = ctx.body;
+			if (!amount || amount <= 0) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "amount must be > 0"
+			});
+			if (!phoneNumber) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "phoneNumber is required"
+			});
+			return {
+				type: "api",
+				body: await mpesa.stkPush({
+					amount,
+					phoneNumber,
+					callbackUrl: config.callbackUrl,
+					accountReference: accountReference ?? `REF-${Date.now().toString(36).toUpperCase()}`,
+					transactionDesc: transactionDesc ?? "Payment",
+					...transactionType !== void 0 ? { transactionType } : {},
+					...partyB !== void 0 ? { partyB } : {}
+				})
+			};
+		},
+		"stk.query": async (ctx) => {
+			const { checkoutRequestId } = ctx.body;
+			if (!checkoutRequestId) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "checkoutRequestId is required"
+			});
+			return {
+				type: "api",
+				body: await mpesa.stkQuery({ checkoutRequestId })
+			};
+		},
+		"stk.callback": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const webhook = ctx.body;
+			const cb = webhook?.Body?.stkCallback;
+			if (!cb) return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+			if (isSuccessfulCallback(webhook)) {
+				const payload = {
+					receiptNumber: extractTransactionId(webhook),
+					amount: extractAmount(webhook),
+					phone: extractPhoneNumber(webhook),
+					checkoutRequestId: cb.CheckoutRequestID,
+					merchantRequestId: cb.MerchantRequestID
+				};
+				console.info("[pesafy] STK success:", payload);
+				fireHook(config.onStkSuccess ? () => Promise.resolve(config.onStkSuccess(payload)) : void 0, "onStkSuccess");
+			} else {
+				const payload = {
+					resultCode: cb.ResultCode,
+					resultDesc: cb.ResultDesc,
+					checkoutRequestId: cb.CheckoutRequestID,
+					merchantRequestId: cb.MerchantRequestID
+				};
+				console.warn("[pesafy] STK failure:", payload);
+				fireHook(config.onStkFailure ? () => Promise.resolve(config.onStkFailure(payload)) : void 0, "onStkFailure");
+			}
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+		},
+		"c2b.register": async (ctx) => {
+			const { shortCode = config.c2b?.shortCode, confirmationUrl = config.c2b?.confirmationUrl, validationUrl = config.c2b?.validationUrl, responseType = config.c2b?.responseType ?? "Completed", apiVersion = config.c2b?.apiVersion ?? "v2" } = ctx.body;
+			if (!shortCode) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "shortCode is required"
+			});
+			if (!confirmationUrl) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "confirmationUrl is required"
+			});
+			if (!validationUrl) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "validationUrl is required"
+			});
+			return {
+				type: "api",
+				body: await mpesa.registerC2BUrls({
+					shortCode,
+					responseType,
+					confirmationUrl,
+					validationUrl,
+					apiVersion
+				})
+			};
+		},
+		"c2b.simulate": async (ctx) => {
+			const { commandId, amount, msisdn, billRefNumber, shortCode, apiVersion } = ctx.body;
+			if (!commandId) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "commandId is required"
+			});
+			if (!amount || amount <= 0) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "amount must be > 0"
+			});
+			if (!msisdn) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "msisdn is required"
+			});
+			return {
+				type: "api",
+				body: await mpesa.simulateC2B({
+					shortCode: shortCode ?? config.c2b?.shortCode ?? "",
+					commandId,
+					amount,
+					msisdn,
+					apiVersion: apiVersion ?? config.c2b?.apiVersion ?? "v2",
+					...billRefNumber !== void 0 ? { billRefNumber } : {}
+				})
+			};
+		},
+		"c2b.validation": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const payload = ctx.body;
+			return {
+				type: "daraja",
+				body: config.onC2BValidation ? await config.onC2BValidation(payload) : acceptC2BValidation()
+			};
+		},
+		"c2b.confirmation": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const payload = ctx.body;
+			console.info("[pesafy] C2B confirmation:", {
+				transactionId: payload.TransID,
+				amount: payload.TransAmount,
+				billRef: payload.BillRefNumber
+			});
+			fireHook(config.onC2BConfirmation ? () => Promise.resolve(config.onC2BConfirmation(payload)) : void 0, "onC2BConfirmation");
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Success"
+				}
+			};
+		},
+		"balance.query": async (ctx) => {
+			const body = ctx.body;
+			return {
+				type: "api",
+				body: await mpesa.accountBalance({
+					partyA: body.partyA ?? config.balance?.shortCode ?? "",
+					identifierType: body.identifierType ?? "4",
+					resultUrl: resolveUrl(body.resultUrl, config.balance?.resultUrl, config.resultUrl, "resultUrl"),
+					queueTimeOutUrl: resolveUrl(body.queueTimeoutUrl, config.balance?.queueTimeoutUrl, config.queueTimeoutUrl, "queueTimeoutUrl"),
+					...body.remarks !== void 0 ? { remarks: body.remarks } : {}
+				})
+			};
+		},
+		"balance.result": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const body = ctx.body;
+			if (!isAccountBalanceSuccess(body)) console.warn("[pesafy] Account balance failed:", body);
+			else {
+				const raw = getAccountBalanceRawBalance(body);
+				console.info("[pesafy] Account balance:", raw ? parseAccountBalance(raw) : body);
+			}
+			fireHook(config.onAccountBalanceResult ? () => Promise.resolve(config.onAccountBalanceResult(body)) : void 0, "onAccountBalanceResult");
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+		},
+		"qr.generate": async (ctx) => {
+			return {
+				type: "api",
+				body: await mpesa.generateDynamicQR(ctx.body)
+			};
+		},
+		"reversal.request": async (ctx) => {
+			const body = ctx.body;
+			if (!body.transactionId) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "transactionId is required"
+			});
+			if (!body.receiverParty) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "receiverParty is required"
+			});
+			if (!body.amount || body.amount <= 0) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "amount must be > 0"
+			});
+			return {
+				type: "api",
+				body: await mpesa.reverseTransaction({
+					transactionId: body.transactionId,
+					receiverParty: body.receiverParty,
+					amount: body.amount,
+					resultUrl: resolveUrl(body.resultUrl, config.reversal?.resultUrl, config.resultUrl, "resultUrl"),
+					queueTimeOutUrl: resolveUrl(body.queueTimeoutUrl, config.reversal?.queueTimeoutUrl, config.queueTimeoutUrl, "queueTimeoutUrl"),
+					...body.remarks !== void 0 ? { remarks: body.remarks } : {},
+					...body.occasion !== void 0 ? { occasion: body.occasion } : {}
+				})
+			};
+		},
+		"reversal.result": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const body = ctx.body;
+			if (isReversalResult(body)) {
+				if (isReversalSuccess(body)) console.info("[pesafy] Reversal success:", { txId: getReversalTransactionId(body) });
+				else console.warn("[pesafy] Reversal failed:", body.Result.ResultDesc);
+				fireHook(config.onReversalResult ? () => Promise.resolve(config.onReversalResult(body)) : void 0, "onReversalResult");
+			}
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+		},
+		"txStatus.query": async (ctx) => {
+			const body = ctx.body;
+			return {
+				type: "api",
+				body: await mpesa.transactionStatus({
+					...body.transactionId !== void 0 ? { transactionId: body.transactionId } : {},
+					...body.originalConversationId !== void 0 ? { originalConversationId: body.originalConversationId } : {},
+					partyA: body.partyA,
+					identifierType: body.identifierType,
+					resultUrl: resolveUrl(body.resultUrl, config.txStatus?.resultUrl, config.resultUrl, "resultUrl"),
+					queueTimeOutUrl: resolveUrl(body.queueTimeoutUrl, config.txStatus?.queueTimeoutUrl, config.queueTimeoutUrl, "queueTimeoutUrl"),
+					...body.remarks !== void 0 ? { remarks: body.remarks } : {},
+					...body.occasion !== void 0 ? { occasion: body.occasion } : {}
+				})
+			};
+		},
+		"txStatus.result": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const body = ctx.body;
+			if (isTransactionStatusResult(body)) {
+				if (isTransactionStatusSuccess(body)) console.info("[pesafy] Transaction status success:", body.Result.TransactionID);
+				else console.warn("[pesafy] Transaction status failed:", body.Result.ResultDesc);
+				fireHook(config.onTxStatusResult ? () => Promise.resolve(config.onTxStatusResult(body)) : void 0, "onTxStatusResult");
+			}
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+		},
+		"tax.remit": async (ctx) => {
+			const body = ctx.body;
+			if (!body.amount || body.amount <= 0) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "amount must be > 0"
+			});
+			if (!body.accountReference) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "accountReference (KRA PRN) is required"
+			});
+			return {
+				type: "api",
+				body: await mpesa.remitTax({
+					amount: body.amount,
+					partyA: body.partyA ?? config.tax?.partyA ?? "",
+					accountReference: body.accountReference,
+					resultUrl: resolveUrl(body.resultUrl, config.tax?.resultUrl, config.resultUrl, "resultUrl"),
+					queueTimeOutUrl: resolveUrl(body.queueTimeoutUrl, config.tax?.queueTimeoutUrl, config.queueTimeoutUrl, "queueTimeoutUrl"),
+					...body.partyB !== void 0 ? { partyB: body.partyB } : {},
+					...body.remarks !== void 0 ? { remarks: body.remarks } : {}
+				})
+			};
+		},
+		"tax.result": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const body = ctx.body;
+			if (isTaxRemittanceResult(body)) {
+				if (isTaxRemittanceSuccess(body)) console.info("[pesafy] Tax remittance success:", body.Result.TransactionID);
+				else console.warn("[pesafy] Tax remittance failed:", body.Result.ResultDesc);
+				fireHook(config.onTaxResult ? () => Promise.resolve(config.onTaxResult(body)) : void 0, "onTaxResult");
+			}
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+		},
+		"b2b.checkout": async (ctx) => {
+			const body = ctx.body;
+			if (!body.primaryShortCode) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "primaryShortCode is required"
+			});
+			if (!body.amount || body.amount <= 0) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "amount must be > 0"
+			});
+			if (!body.paymentRef) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "paymentRef is required"
+			});
+			if (!body.partnerName) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "partnerName is required"
+			});
+			const receiverShortCode = body.receiverShortCode ?? config.b2b?.receiverShortCode ?? "";
+			if (!receiverShortCode) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "receiverShortCode is required"
+			});
+			const callbackUrl = body.callbackUrl ?? config.b2b?.callbackUrl ?? "";
+			if (!callbackUrl) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "callbackUrl is required"
+			});
+			return {
+				type: "api",
+				body: await mpesa.b2bExpressCheckout({
+					primaryShortCode: body.primaryShortCode,
+					receiverShortCode,
+					amount: body.amount,
+					paymentRef: body.paymentRef,
+					callbackUrl,
+					partnerName: body.partnerName,
+					...body.requestRefId !== void 0 ? { requestRefId: body.requestRefId } : {}
+				})
+			};
+		},
+		"b2b.callback": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const body = ctx.body;
+			if (!isB2BCheckoutCallback(body)) {
+				console.warn("[pesafy] Unknown B2B callback payload");
+				return {
+					type: "daraja",
+					body: {
+						ResultCode: 0,
+						ResultDesc: "Accepted"
+					}
+				};
+			}
+			const callback = body;
+			if (isB2BCheckoutSuccess(callback)) console.info("[pesafy] B2B checkout success:", {
+				txId: getB2BTransactionId(callback),
+				conversationId: getB2BConversationId(callback),
+				amount: getB2BAmount(callback)
+			});
+			else if (isB2BCheckoutCancelled(callback)) console.warn("[pesafy] B2B checkout cancelled by merchant");
+			else console.warn("[pesafy] B2B checkout failed:", callback.resultDesc);
+			fireHook(config.onB2BCheckoutCallback ? () => Promise.resolve(config.onB2BCheckoutCallback(callback)) : void 0, "onB2BCheckoutCallback");
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+		},
+		"b2c.payment": async (ctx) => {
+			const body = ctx.body;
+			if (body.commandId !== "BusinessPayToBulk") throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "commandId must be \"BusinessPayToBulk\""
+			});
+			if (!body.amount || body.amount <= 0) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "amount must be > 0"
+			});
+			if (!body.partyB) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "partyB is required"
+			});
+			if (!body.accountReference) throw new PesafyError({
+				code: "VALIDATION_ERROR",
+				message: "accountReference is required"
+			});
+			return {
+				type: "api",
+				body: await mpesa.b2cPayment({
+					commandId: "BusinessPayToBulk",
+					amount: body.amount,
+					partyA: body.partyA ?? config.b2c?.partyA ?? "",
+					partyB: body.partyB,
+					accountReference: body.accountReference,
+					resultUrl: resolveUrl(body.resultUrl, config.b2c?.resultUrl, config.resultUrl, "resultUrl"),
+					queueTimeOutUrl: resolveUrl(body.queueTimeoutUrl, config.b2c?.queueTimeoutUrl, config.queueTimeoutUrl, "queueTimeoutUrl"),
+					...body.requester !== void 0 ? { requester: body.requester } : {},
+					...body.remarks !== void 0 ? { remarks: body.remarks } : {}
+				})
+			};
+		},
+		"b2c.result": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const body = ctx.body;
+			if (isB2CResult(body)) {
+				if (isB2CSuccess(body)) console.info("[pesafy] B2C success:", {
+					txId: getB2CTransactionId(body),
+					amount: getB2CAmount(body),
+					origConvId: getB2COriginatorConversationId(body)
+				});
+				else console.warn("[pesafy] B2C failed:", body.Result.ResultDesc);
+				fireHook(config.onB2CResult ? () => Promise.resolve(config.onB2CResult(body)) : void 0, "onB2CResult");
+			}
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+		},
+		"b2c.disburse": async (ctx) => {
+			const body = ctx.body;
+			return {
+				type: "api",
+				body: await mpesa.b2cDisbursement({
+					originatorConversationId: body.originatorConversationId,
+					commandId: body.commandId,
+					amount: body.amount,
+					partyA: body.partyA,
+					partyB: body.partyB,
+					remarks: body.remarks,
+					resultUrl: resolveUrl(body.resultUrl, config.b2c?.resultUrl, config.resultUrl, "resultUrl"),
+					queueTimeOutUrl: resolveUrl(body.queueTimeoutUrl, config.b2c?.queueTimeoutUrl, config.queueTimeoutUrl, "queueTimeoutUrl"),
+					...body.occasion !== void 0 ? { occasion: body.occasion } : {}
+				})
+			};
+		},
+		"b2c.disburse.result": async (ctx) => {
+			await runWebhookGuard(ctx, config);
+			const body = ctx.body;
+			if (isB2CDisbursementResult(body)) {
+				if (isB2CDisbursementSuccess(body)) console.info("[pesafy] B2C disbursement success:", body.Result.TransactionID);
+				else console.warn("[pesafy] B2C disbursement failed:", body.Result.ResultDesc);
+				fireHook(config.onB2CDisbursementResult ? () => Promise.resolve(config.onB2CDisbursementResult(body)) : void 0, "onB2CDisbursementResult");
+			}
+			return {
+				type: "daraja",
+				body: {
+					ResultCode: 0,
+					ResultDesc: "Accepted"
+				}
+			};
+		},
+		"bills.optin": async (ctx) => {
+			return {
+				type: "api",
+				body: await mpesa.billManagerOptIn(ctx.body)
+			};
+		},
+		"bills.optin.patch": async (ctx) => {
+			return {
+				type: "api",
+				body: await mpesa.updateOptIn(ctx.body)
+			};
+		},
+		"bills.invoice": async (ctx) => {
+			return {
+				type: "api",
+				body: await mpesa.sendInvoice(ctx.body)
+			};
+		},
+		"bills.invoice.delete": async (ctx) => {
+			return {
+				type: "api",
+				body: await mpesa.cancelInvoice(ctx.body)
+			};
+		},
+		"bills.invoice.bulk": async (ctx) => {
+			return {
+				type: "api",
+				body: await mpesa.sendBulkInvoices(ctx.body)
+			};
+		},
+		"bills.invoice.bulk.delete": async (ctx) => {
+			return {
+				type: "api",
+				body: await mpesa.cancelBulkInvoices(ctx.body)
+			};
+		},
+		"bills.reconcile": async (ctx) => {
+			return {
+				type: "api",
+				body: await mpesa.reconcilePayment(ctx.body)
+			};
+		},
+		health: async () => ({
+			type: "api",
+			body: {
+				ok: true,
+				environment: mpesa.environment,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			}
+		})
+	};
+}
+
+//#endregion
+//#region src/adapters/shared/route-definitions.ts
+const ROUTE_DEFINITIONS = [
+	{
+		id: "stk.push",
+		method: "POST",
+		path: "/mpesa/stk/push"
+	},
+	{
+		id: "stk.query",
+		method: "POST",
+		path: "/mpesa/stk/query"
+	},
+	{
+		id: "stk.callback",
+		method: "POST",
+		path: "/mpesa/stk/callback",
+		webhook: true
+	},
+	{
+		id: "c2b.register",
+		method: "POST",
+		path: "/mpesa/c2b/register"
+	},
+	{
+		id: "c2b.simulate",
+		method: "POST",
+		path: "/mpesa/c2b/simulate"
+	},
+	{
+		id: "c2b.validation",
+		method: "POST",
+		path: "/mpesa/c2b/validation",
+		webhook: true
+	},
+	{
+		id: "c2b.confirmation",
+		method: "POST",
+		path: "/mpesa/c2b/confirmation",
+		webhook: true
+	},
+	{
+		id: "balance.query",
+		method: "POST",
+		path: "/mpesa/balance/query"
+	},
+	{
+		id: "balance.result",
+		method: "POST",
+		path: "/mpesa/balance/result",
+		webhook: true
+	},
+	{
+		id: "qr.generate",
+		method: "POST",
+		path: "/mpesa/qr/generate"
+	},
+	{
+		id: "reversal.request",
+		method: "POST",
+		path: "/mpesa/reversal/request"
+	},
+	{
+		id: "reversal.result",
+		method: "POST",
+		path: "/mpesa/reversal/result",
+		webhook: true
+	},
+	{
+		id: "txStatus.query",
+		method: "POST",
+		path: "/mpesa/tx-status/query"
+	},
+	{
+		id: "txStatus.result",
+		method: "POST",
+		path: "/mpesa/tx-status/result",
+		webhook: true
+	},
+	{
+		id: "tax.remit",
+		method: "POST",
+		path: "/mpesa/tax/remit"
+	},
+	{
+		id: "tax.result",
+		method: "POST",
+		path: "/mpesa/tax/result",
+		webhook: true
+	},
+	{
+		id: "b2b.checkout",
+		method: "POST",
+		path: "/mpesa/b2b/checkout"
+	},
+	{
+		id: "b2b.callback",
+		method: "POST",
+		path: "/mpesa/b2b/callback",
+		webhook: true
+	},
+	{
+		id: "b2c.payment",
+		method: "POST",
+		path: "/mpesa/b2c/payment"
+	},
+	{
+		id: "b2c.result",
+		method: "POST",
+		path: "/mpesa/b2c/result",
+		webhook: true
+	},
+	{
+		id: "b2c.disburse",
+		method: "POST",
+		path: "/mpesa/b2c/disburse"
+	},
+	{
+		id: "b2c.disburse.result",
+		method: "POST",
+		path: "/mpesa/b2c/disburse/result",
+		webhook: true
+	},
+	{
+		id: "bills.optin",
+		method: "POST",
+		path: "/mpesa/bills/optin"
+	},
+	{
+		id: "bills.optin.patch",
+		method: "PATCH",
+		path: "/mpesa/bills/optin"
+	},
+	{
+		id: "bills.invoice",
+		method: "POST",
+		path: "/mpesa/bills/invoice"
+	},
+	{
+		id: "bills.invoice.delete",
+		method: "DELETE",
+		path: "/mpesa/bills/invoice"
+	},
+	{
+		id: "bills.invoice.bulk",
+		method: "POST",
+		path: "/mpesa/bills/invoice/bulk"
+	},
+	{
+		id: "bills.invoice.bulk.delete",
+		method: "DELETE",
+		path: "/mpesa/bills/invoice/bulk"
+	},
+	{
+		id: "bills.reconcile",
+		method: "POST",
+		path: "/mpesa/bills/reconcile"
+	},
+	{
+		id: "health",
+		method: "GET",
+		path: "/mpesa/health"
+	}
+];
+/** Base paths (no routePrefix) for all adapter routes. */
+function getRoutePaths(prefix = "") {
+	return ROUTE_DEFINITIONS.map((r) => `${prefix}${r.path}`);
+}
+
+//#endregion
+export { PesafyError as a, Mpesa as i, getRoutePaths as n, createRouteHandlers as r, ROUTE_DEFINITIONS as t };
+//# sourceMappingURL=route-definitions.js.map