pesafy 0.0.2 → 0.2.0

package/dist/cli.mjs

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { t as __exportAll } from "./rolldown-runtime.mjs";
+import { n as createError, t as PesafyError } from "./errors.mjs";
+import { t as formatSafaricomPhone } from "./phone.mjs";
 import { createInterface } from "node:readline";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { constants, publicEncrypt } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
 
-//#region src/cli/index.ts
+//#region src/cli/lib/output.ts
 const C = {
 	reset: "\x1B[0m",
 	bold: "\x1B[1m",
@@ -22,6 +28,69 @@ const r = (s) => `${C.red}${s}${C.reset}`;
 const b = (s) => `${C.bold}${s}${C.reset}`;
 const c = (s) => `${C.cyan}${s}${C.reset}`;
 const dim = (s) => `${C.dim}${s}${C.reset}`;
+function printJson(data) {
+	console.log(JSON.stringify(data, null, 2));
+}
+
+//#endregion
+//#region src/cli/lib/env.ts
+function loadEnv(envFile) {
+	const envPath = resolve(process.cwd(), envFile ?? ".env");
+	if (!existsSync(envPath)) return {};
+	const lines = readFileSync(envPath, "utf-8").split("\n");
+	const env = {};
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq === -1) continue;
+		const key = trimmed.slice(0, eq).trim();
+		env[key] = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+	}
+	return env;
+}
+function applyEnvOverride(env, override) {
+	if (!override) return env;
+	return {
+		...env,
+		MPESA_ENVIRONMENT: override
+	};
+}
+function requireEnv(env, ...keys) {
+	const missing = keys.filter((k) => !env[k]);
+	if (missing.length) {
+		console.error(`✖  Missing env vars: ${missing.join(", ")}`);
+		console.error("  Run: npx pesafy init");
+		process.exit(2);
+	}
+}
+function getBaseUrl(env) {
+	return env["MPESA_ENVIRONMENT"] === "production" ? "https://api.safaricom.co.ke" : "https://sandbox.safaricom.co.ke";
+}
+
+//#endregion
+//#region src/cli/lib/context.ts
+function createCliContext(argv) {
+	const args = [];
+	let json = false;
+	let envFile;
+	let envOverride;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--json") json = true;
+		else if (a === "--env-file" && argv[i + 1]) envFile = argv[++i];
+		else if (a === "--env" && argv[i + 1]) {
+			const v = argv[++i];
+			if (v === "sandbox" || v === "production") envOverride = v;
+		} else args.push(a ?? "");
+	}
+	const env = applyEnvOverride(loadEnv(envFile), envOverride);
+	return {
+		args,
+		json,
+		env
+	};
+}
 function getPkgVersion() {
 	try {
 		const pkgPath = resolve(new URL("../../package.json", import.meta.url).pathname);
@@ -30,85 +99,2101 @@ function getPkgVersion() {
 		return "unknown";
 	}
 }
-function prompt(question, defaultVal = "") {
-	const rl = createInterface({
-		input: process.stdin,
-		output: process.stdout
+function prompt(question, defaultVal = "") {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	const displayDefault = defaultVal ? dim(` [${defaultVal}]`) : "";
+	return new Promise((resolve) => {
+		rl.question(`${question}${displayDefault}: `, (answer) => {
+			rl.close();
+			resolve(answer.trim() || defaultVal);
+		});
+	});
+}
+
+//#endregion
+//#region src/cli/lib/daraja.ts
+async function fetchJson(url, method, headers, body) {
+	const res = await fetch(url, {
+		method,
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json",
+			...headers
+		},
+		...body ? { body: JSON.stringify(body) } : {}
+	});
+	const text = await res.text();
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new Error(`Non-JSON response (${res.status}): ${text.slice(0, 200)}`);
+	}
+}
+async function getToken(consumerKey, consumerSecret, baseUrl) {
+	const creds = Buffer.from(`${consumerKey}:${consumerSecret}`).toString("base64");
+	const data = await fetchJson(`${baseUrl}/oauth/v1/generate?grant_type=client_credentials`, "GET", { Authorization: `Basic ${creds}` });
+	if (!data.access_token) throw new Error("No access_token in response");
+	return data.access_token;
+}
+
+//#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/encryption/index.ts
+var encryption_exports = /* @__PURE__ */ __exportAll({ encryptSecurityCredential: () => encryptSecurityCredential });
+
+//#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/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/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-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-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/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/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 displayDefault = defaultVal ? dim(` [${defaultVal}]`) : "";
-	return new Promise((resolve) => {
-		rl.question(`${question}${displayDefault}: `, (answer) => {
-			rl.close();
-			resolve(answer.trim() || defaultVal);
-		});
+	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");
 }
-function loadEnv() {
-	const envPath = resolve(process.cwd(), ".env");
-	if (!existsSync(envPath)) return {};
-	const lines = readFileSync(envPath, "utf-8").split("\n");
-	const env = {};
-	for (const line of lines) {
-		const trimmed = line.trim();
-		if (!trimmed || trimmed.startsWith("#")) continue;
-		const eq = trimmed.indexOf("=");
-		if (eq === -1) continue;
-		const key = trimmed.slice(0, eq).trim();
-		env[key] = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
-	}
-	return env;
+
+//#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";
+
+//#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");
 }
-function requireEnv(env, ...keys) {
-	const missing = keys.filter((k) => !env[k]);
-	if (missing.length) {
-		console.error(r(`✖  Missing env vars: ${missing.join(", ")}`));
-		console.error(dim("  Run: npx pesafy init"));
-		process.exit(1);
-	}
+
+//#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/mpesa/stk-push/utils.ts
+var utils_exports = /* @__PURE__ */ __exportAll({
+	getStkPushPassword: () => getStkPushPassword,
+	getTimestamp: () => getTimestamp
+});
+/**
+* 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}`);
 }
-async function fetchJson(url, method, headers, body) {
-	const res = await fetch(url, {
-		method,
-		headers: {
-			"Content-Type": "application/json",
-			Accept: "application/json",
-			...headers
-		},
-		...body ? { body: JSON.stringify(body) } : {}
+/**
+* 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 text = await res.text();
-	try {
-		return JSON.parse(text);
-	} catch {
-		throw new Error(`Non-JSON response (${res.status}): ${text.slice(0, 200)}`);
-	}
+	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");
 }
-async function getToken(consumerKey, consumerSecret, baseUrl) {
-	const creds = Buffer.from(`${consumerKey}:${consumerSecret}`).toString("base64");
-	const data = await fetchJson(`${baseUrl}/oauth/v1/generate?grant_type=client_credentials`, "GET", { Authorization: `Basic ${creds}` });
-	if (!data.access_token) throw new Error("No access_token in response");
-	return data.access_token;
+
+//#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/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/types.ts
+const DARAJA_BASE_URLS = {
+	sandbox: "https://sandbox.safaricom.co.ke",
+	production: "https://api.safaricom.co.ke"
+};
+
+//#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/cli/lib/mpesa-from-env.ts
+async function mpesaFromEnv(env, opts = {}) {
+	requireEnv(env, "MPESA_CONSUMER_KEY", "MPESA_CONSUMER_SECRET", "MPESA_ENVIRONMENT");
+	const config = {
+		consumerKey: env["MPESA_CONSUMER_KEY"],
+		consumerSecret: env["MPESA_CONSUMER_SECRET"],
+		environment: env["MPESA_ENVIRONMENT"] === "production" ? "production" : "sandbox",
+		lipaNaMpesaShortCode: env["MPESA_SHORTCODE"] ?? "",
+		lipaNaMpesaPassKey: env["MPESA_PASSKEY"] ?? ""
+	};
+	if (opts.requireInitiator) {
+		requireEnv(env, "MPESA_INITIATOR_NAME", "MPESA_INITIATOR_PASSWORD", "MPESA_CERTIFICATE_PATH");
+		const certPath = resolve(process.cwd(), env["MPESA_CERTIFICATE_PATH"]);
+		if (!existsSync(certPath)) {
+			console.error(`✖  Certificate not found: ${certPath}`);
+			process.exit(2);
+		}
+		const pem = await readFile(certPath, "utf-8");
+		const initiatorName = env["MPESA_INITIATOR_NAME"];
+		const initiatorPassword = env["MPESA_INITIATOR_PASSWORD"];
+		config.initiatorName = initiatorName;
+		config.initiatorPassword = initiatorPassword;
+		config.securityCredential = encryptSecurityCredential(initiatorPassword, pem);
+	}
+	return new Mpesa(config);
 }
-async function cmdVersion() {
+
+//#endregion
+//#region src/cli/commands/version.ts
+async function cmdVersion(ctx) {
 	console.log(`pesafy v${getPkgVersion()}`);
 }
-async function cmdHelp() {
+
+//#endregion
+//#region src/cli/commands/help.ts
+async function cmdHelp(ctx) {
 	console.log(`
 ${b(`pesafy`)} ${dim(`v${getPkgVersion()}`)} — M-PESA Daraja SDK CLI
 
-${b("COMMANDS")}
-  ${g("init")}                  Scaffold .env + config file interactively
-  ${g("doctor")}                Validate .env config for common mistakes
-  ${g("token")}                 Print a fresh Daraja OAuth token
-  ${g("encrypt")}               Encrypt an initiator password → SecurityCredential
-  ${g("validate-phone")} ${c("<phone>")}  Validate and normalise a Kenyan phone number
-  ${g("stk-push")}              Initiate an STK Push payment prompt
-  ${g("stk-query")} ${c("<checkoutId>")}  Query status of an STK Push
-  ${g("balance")}               Query M-PESA account balance (async — result via ResultURL)
-  ${g("reversal")} ${c("<txId>")}         Initiate a transaction reversal
-  ${g("register-c2b-urls")}     Register C2B Confirmation + Validation URLs
-  ${g("simulate-c2b")}          Simulate a C2B payment (sandbox only)
-  ${g("version")}               Print library version
+${b("SETUP")}
+  ${g("init")}                  Scaffold .env interactively
+  ${g("doctor")}                Validate .env configuration
+  ${g("token")}                 Print Daraja OAuth token
+  ${g("encrypt")}               Encrypt initiator password → SecurityCredential
+  ${g("validate-phone")} ${c("<phone>")}  Normalise Kenyan MSISDN
+
+${b("PAYMENTS")}
+  ${g("stk-push")}              STK Push (M-PESA Express)
+  ${g("stk-query")} ${c("<checkoutId>")}  Query STK status
+  ${g("b2b-checkout")}          B2B Express Checkout
+  ${g("qr-generate")}           Dynamic QR (JSON body optional)
+
+${b("ASYNC")}
+  ${g("balance")}               Account balance query
+  ${g("reversal")} ${c("<txId>")}         Transaction reversal
+  ${g("tx-status")}              Transaction status query
+  ${g("b2c-payment")}            B2C account top-up
+  ${g("b2c-disburse")}           B2C disbursement
+  ${g("tax-remit")}              KRA tax remittance
+  ${g("register-c2b-urls")}     Register C2B URLs
+  ${g("simulate-c2b")}          C2B simulate (sandbox)
+
+${b("BILLS")}
+  ${g("bills")} ${c("<optin|invoice|bulk|reconcile>")}  Bill Manager API
+
+${b("FLAGS")}
+  ${g("--json")}                Machine-readable output
+  ${g("--env-file")} ${c("<path>")}   Alternate .env path
+  ${g("--env")} ${c("sandbox|production")}  Override MPESA_ENVIRONMENT
+
+${b("UTILS")}
+  ${g("version")}               Print version
   ${g("help")}                  Show this help
 
 ${b("ENVIRONMENT")}
@@ -150,7 +2235,10 @@ ${b("EXAMPLES")}
   ${dim("$ npx pesafy validate-phone 0712345678")}
 `);
 }
-async function cmdInit() {
+
+//#endregion
+//#region src/cli/commands/init.ts
+async function cmdInit(ctx) {
 	console.log(`\n${b("🚀  pesafy — Interactive Setup")}\n`);
 	console.log(dim("This will create a .env file in the current directory.\n"));
 	const content = `# pesafy — M-PESA Daraja configuration
@@ -163,7 +2251,7 @@ MPESA_CONSUMER_SECRET=${await prompt("Consumer Secret")}
 # STK Push (M-PESA Express)
 MPESA_SHORTCODE=${await prompt("Lipa Na M-PESA Shortcode (for STK Push)", "174379")}
 MPESA_PASSKEY=${await prompt("Lipa Na M-PESA Passkey")}
-MPESA_CALLBACK_URL=${await prompt("STK Push Callback URL", "https://yourdomain.com/api/mpesa/callback")}
+MPESA_CALLBACK_URL=${await prompt("STK Push Callback URL", "https://example.com/api/mpesa/callback")}
 
 # Initiator (Account Balance / B2C / Reversal / Transaction Status / Tax Remittance)
 # Required org portal role for Account Balance: "Balance Query ORG API"
@@ -172,8 +2260,8 @@ MPESA_INITIATOR_PASSWORD=${await prompt("Initiator Password (leave blank if not
 MPESA_CERTIFICATE_PATH=${await prompt("Certificate path (leave blank to skip)", "./SandboxCertificate.cer")}
 
 # Async API result endpoints (Account Balance, Reversal, B2C)
-MPESA_RESULT_URL=${await prompt("Result URL (for async APIs — Account Balance, Reversal, B2C)", "https://yourdomain.com/api/mpesa/result")}
-MPESA_QUEUE_TIMEOUT_URL=${await prompt("Queue Timeout URL", "https://yourdomain.com/api/mpesa/timeout")}
+MPESA_RESULT_URL=${await prompt("Result URL (for async APIs — Account Balance, Reversal, B2C)", "https://example.com/api/mpesa/result")}
+MPESA_QUEUE_TIMEOUT_URL=${await prompt("Queue Timeout URL", "https://example.com/api/mpesa/timeout")}
 `;
 	const envPath = resolve(process.cwd(), ".env");
 	if (existsSync(envPath)) {
@@ -185,9 +2273,12 @@ MPESA_QUEUE_TIMEOUT_URL=${await prompt("Queue Timeout URL", "https://yourdomain.
 	writeFileSync(envPath, content);
 	console.log(`\n${g("✔  .env created")} — run ${c("npx pesafy doctor")} to validate.\n`);
 }
-async function cmdDoctor() {
+
+//#endregion
+//#region src/cli/commands/doctor.ts
+async function cmdDoctor(ctx) {
 	console.log(`\n${b("🩺  pesafy doctor")}\n`);
-	const env = loadEnv();
+	const env = ctx.env;
 	let ok = true;
 	function check(key, hint = "") {
 		if (env[key]) console.log(`${g("✔")}  ${key}`);
@@ -257,14 +2348,24 @@ async function cmdDoctor() {
 		process.exit(1);
 	}
 }
-async function cmdToken() {
-	const env = loadEnv();
+
+//#endregion
+//#region src/cli/commands/token.ts
+async function cmdToken(ctx) {
+	const env = ctx.env;
 	requireEnv(env, "MPESA_CONSUMER_KEY", "MPESA_CONSUMER_SECRET", "MPESA_ENVIRONMENT");
-	const baseUrl = env["MPESA_ENVIRONMENT"] === "production" ? "https://api.safaricom.co.ke" : "https://sandbox.safaricom.co.ke";
+	const baseUrl = getBaseUrl(env);
 	process.stdout.write(dim("Fetching token…"));
 	try {
 		const token = await getToken(env["MPESA_CONSUMER_KEY"], env["MPESA_CONSUMER_SECRET"], baseUrl);
 		process.stdout.write("\r");
+		if (ctx.json) {
+			printJson({
+				access_token: token,
+				expires_in: 3600
+			});
+			return;
+		}
 		console.log(`\n${b("Access Token:")}\n\n${c(token)}\n`);
 		console.log(dim("Token is valid for 3600 seconds (1 hour)."));
 	} catch (e) {
@@ -273,8 +2374,12 @@ async function cmdToken() {
 		process.exit(1);
 	}
 }
-async function cmdEncrypt(args) {
-	const env = loadEnv();
+
+//#endregion
+//#region src/cli/commands/encrypt.ts
+async function cmdEncrypt(ctx) {
+	const args = ctx.args;
+	const env = ctx.env;
 	let password = args[0];
 	let certPath = args[1] ?? env["MPESA_CERTIFICATE_PATH"];
 	if (!password) password = await prompt("Initiator password to encrypt");
@@ -284,7 +2389,7 @@ async function cmdEncrypt(args) {
 		process.exit(1);
 	}
 	try {
-		const { encryptSecurityCredential } = await import("./encryption.mjs");
+		const { encryptSecurityCredential } = await Promise.resolve().then(() => encryption_exports);
 		const { readFile } = await import("node:fs/promises");
 		const pem = await readFile(resolve(process.cwd(), certPath), "utf-8");
 		const credential = encryptSecurityCredential(password, pem);
@@ -295,11 +2400,14 @@ async function cmdEncrypt(args) {
 		process.exit(1);
 	}
 }
-async function cmdValidatePhone(args) {
-	let phone = args[0];
+
+//#endregion
+//#region src/cli/commands/validate-phone.ts
+async function cmdValidatePhone(ctx) {
+	let phone = ctx.args[0];
 	if (!phone) phone = await prompt("Phone number to validate");
 	try {
-		const { formatSafaricomPhone } = await import("./phone.mjs");
+		const { formatSafaricomPhone } = await import("./phone.mjs").then((n) => n.n);
 		const normalised = formatSafaricomPhone(phone);
 		console.log(`\n${g("✔")}  ${b(phone)} → ${c(normalised)}\n`);
 	} catch (e) {
@@ -307,8 +2415,12 @@ async function cmdValidatePhone(args) {
 		process.exit(1);
 	}
 }
-async function cmdStkPush(args) {
-	const env = loadEnv();
+
+//#endregion
+//#region src/cli/commands/stk-push.ts
+async function cmdStkPush(ctx) {
+	const args = ctx.args;
+	const env = ctx.env;
 	requireEnv(env, "MPESA_CONSUMER_KEY", "MPESA_CONSUMER_SECRET", "MPESA_ENVIRONMENT", "MPESA_SHORTCODE", "MPESA_PASSKEY", "MPESA_CALLBACK_URL");
 	const getArg = (flag) => {
 		const idx = args.indexOf(flag);
@@ -324,9 +2436,9 @@ async function cmdStkPush(args) {
 	const baseUrl = env["MPESA_ENVIRONMENT"] === "production" ? "https://api.safaricom.co.ke" : "https://sandbox.safaricom.co.ke";
 	console.log(dim("\nFetching token…"));
 	const token = await getToken(env["MPESA_CONSUMER_KEY"], env["MPESA_CONSUMER_SECRET"], baseUrl);
-	const { formatSafaricomPhone } = await import("./phone.mjs");
+	const { formatSafaricomPhone } = await import("./phone.mjs").then((n) => n.n);
 	const msisdn = formatSafaricomPhone(phone);
-	const { getStkPushPassword, getTimestamp } = await import("./utils.mjs");
+	const { getStkPushPassword, getTimestamp } = await Promise.resolve().then(() => utils_exports);
 	const timestamp = getTimestamp();
 	const password = getStkPushPassword(env["MPESA_SHORTCODE"], env["MPESA_PASSKEY"], timestamp);
 	console.log(dim("Sending STK Push…\n"));
@@ -359,14 +2471,18 @@ async function cmdStkPush(args) {
 		process.exit(1);
 	}
 }
-async function cmdStkQuery(args) {
-	const env = loadEnv();
+
+//#endregion
+//#region src/cli/commands/stk-query.ts
+async function cmdStkQuery(ctx) {
+	const args = ctx.args;
+	const env = ctx.env;
 	requireEnv(env, "MPESA_CONSUMER_KEY", "MPESA_CONSUMER_SECRET", "MPESA_ENVIRONMENT", "MPESA_SHORTCODE", "MPESA_PASSKEY");
 	let checkoutId = args[0];
 	if (!checkoutId) checkoutId = await prompt("CheckoutRequestID");
 	const baseUrl = env["MPESA_ENVIRONMENT"] === "production" ? "https://api.safaricom.co.ke" : "https://sandbox.safaricom.co.ke";
 	const token = await getToken(env["MPESA_CONSUMER_KEY"], env["MPESA_CONSUMER_SECRET"], baseUrl);
-	const { getStkPushPassword, getTimestamp } = await import("./utils.mjs");
+	const { getStkPushPassword, getTimestamp } = await Promise.resolve().then(() => utils_exports);
 	const timestamp = getTimestamp();
 	const password = getStkPushPassword(env["MPESA_SHORTCODE"], env["MPESA_PASSKEY"], timestamp);
 	try {
@@ -406,8 +2522,12 @@ async function cmdStkQuery(args) {
 *   --identifier-type <type>  — "1" MSISDN | "2" Till | "4" ShortCode (default: "4")
 *   --remarks <text>          — Optional remarks (default: "Balance query via pesafy CLI")
 */
-async function cmdBalance(args) {
-	const env = loadEnv();
+
+//#endregion
+//#region src/cli/commands/balance.ts
+async function cmdBalance(ctx) {
+	const args = ctx.args;
+	const env = ctx.env;
 	requireEnv(env, "MPESA_CONSUMER_KEY", "MPESA_CONSUMER_SECRET", "MPESA_ENVIRONMENT", "MPESA_INITIATOR_NAME", "MPESA_INITIATOR_PASSWORD");
 	const getArg = (flag) => {
 		const idx = args.indexOf(flag);
@@ -438,7 +2558,7 @@ async function cmdBalance(args) {
 	const baseUrl = env["MPESA_ENVIRONMENT"] === "production" ? "https://api.safaricom.co.ke" : "https://sandbox.safaricom.co.ke";
 	console.log(dim("\nFetching token…"));
 	const token = await getToken(env["MPESA_CONSUMER_KEY"], env["MPESA_CONSUMER_SECRET"], baseUrl);
-	const { encryptSecurityCredential } = await import("./encryption.mjs");
+	const { encryptSecurityCredential } = await Promise.resolve().then(() => encryption_exports);
 	const { readFile } = await import("node:fs/promises");
 	const certPath = env["MPESA_CERTIFICATE_PATH"] ?? "./SandboxCertificate.cer";
 	if (!existsSync(resolve(process.cwd(), certPath))) {
@@ -501,8 +2621,12 @@ async function cmdBalance(args) {
 		process.exit(1);
 	}
 }
-async function cmdRegisterC2BUrls(args) {
-	const env = loadEnv();
+
+//#endregion
+//#region src/cli/commands/register-c2b-urls.ts
+async function cmdRegisterC2BUrls(ctx) {
+	const args = ctx.args;
+	const env = ctx.env;
 	requireEnv(env, "MPESA_CONSUMER_KEY", "MPESA_CONSUMER_SECRET", "MPESA_ENVIRONMENT");
 	const shortCode = args[0] ?? env["MPESA_SHORTCODE"] ?? await prompt("Shortcode");
 	const confirmationUrl = args[1] ?? await prompt("Confirmation URL");
@@ -527,8 +2651,12 @@ async function cmdRegisterC2BUrls(args) {
 		process.exit(1);
 	}
 }
-async function cmdSimulateC2B(args) {
-	const env = loadEnv();
+
+//#endregion
+//#region src/cli/commands/simulate-c2b.ts
+async function cmdSimulateC2B(ctx) {
+	const args = ctx.args;
+	const env = ctx.env;
 	requireEnv(env, "MPESA_CONSUMER_KEY", "MPESA_CONSUMER_SECRET");
 	if (env["MPESA_ENVIRONMENT"] === "production") {
 		console.error(r("✖  C2B simulate is only available in sandbox."));
@@ -560,8 +2688,12 @@ async function cmdSimulateC2B(args) {
 		process.exit(1);
 	}
 }
-async function cmdReversal(args) {
-	const env = loadEnv();
+
+//#endregion
+//#region src/cli/commands/reversal.ts
+async function cmdReversal(ctx) {
+	const args = ctx.args;
+	const env = ctx.env;
 	requireEnv(env, "MPESA_CONSUMER_KEY", "MPESA_CONSUMER_SECRET", "MPESA_ENVIRONMENT", "MPESA_INITIATOR_NAME", "MPESA_INITIATOR_PASSWORD");
 	const transactionId = args[0] ?? await prompt("Transaction ID to reverse");
 	const receiverParty = args[1] ?? env["MPESA_SHORTCODE"] ?? await prompt("Receiver Party (shortcode)");
@@ -570,7 +2702,7 @@ async function cmdReversal(args) {
 	const queueTimeoutUrl = env["MPESA_QUEUE_TIMEOUT_URL"] ?? await prompt("Queue Timeout URL");
 	const baseUrl = env["MPESA_ENVIRONMENT"] === "production" ? "https://api.safaricom.co.ke" : "https://sandbox.safaricom.co.ke";
 	const token = await getToken(env["MPESA_CONSUMER_KEY"], env["MPESA_CONSUMER_SECRET"], baseUrl);
-	const { encryptSecurityCredential } = await import("./encryption.mjs");
+	const { encryptSecurityCredential } = await Promise.resolve().then(() => encryption_exports);
 	const { readFile } = await import("node:fs/promises");
 	const certPath = env["MPESA_CERTIFICATE_PATH"] ?? "./SandboxCertificate.cer";
 	const pem = await readFile(resolve(process.cwd(), certPath), "utf-8");
@@ -599,22 +2731,164 @@ async function cmdReversal(args) {
 		process.exit(1);
 	}
 }
+
+//#endregion
+//#region src/cli/commands/mpesa-api.ts
+function getArg(args, flag) {
+	const idx = args.indexOf(flag);
+	return idx !== -1 ? args[idx + 1] : void 0;
+}
+async function cmdTxStatus(ctx) {
+	const mpesa = await mpesaFromEnv(ctx.env, { requireInitiator: true });
+	requireEnv(ctx.env, "MPESA_RESULT_URL", "MPESA_QUEUE_TIMEOUT_URL");
+	const partyA = getArg(ctx.args, "--party-a") ?? ctx.args[0] ?? ctx.env["MPESA_SHORTCODE"] ?? "";
+	const transactionId = getArg(ctx.args, "--tx") ?? ctx.args[1];
+	const result = await mpesa.transactionStatus({
+		...transactionId ? { transactionId } : {},
+		partyA,
+		identifierType: getArg(ctx.args, "--identifier-type") ?? "4",
+		resultUrl: ctx.env["MPESA_RESULT_URL"],
+		queueTimeOutUrl: ctx.env["MPESA_QUEUE_TIMEOUT_URL"]
+	});
+	if (ctx.json) printJson(result);
+	else console.log(`${g("✔")} Transaction status query submitted\n`, result);
+}
+async function cmdB2cPayment(ctx) {
+	const mpesa = await mpesaFromEnv(ctx.env, { requireInitiator: true });
+	requireEnv(ctx.env, "MPESA_RESULT_URL", "MPESA_QUEUE_TIMEOUT_URL");
+	const amount = Number(getArg(ctx.args, "--amount") ?? ctx.args[0] ?? 0);
+	const partyB = getArg(ctx.args, "--phone") ?? ctx.args[1] ?? "";
+	const result = await mpesa.b2cPayment({
+		commandId: "BusinessPayToBulk",
+		amount,
+		partyA: getArg(ctx.args, "--party-a") ?? ctx.env["MPESA_SHORTCODE"] ?? "",
+		partyB,
+		accountReference: getArg(ctx.args, "--ref") ?? `CLI-${Date.now()}`,
+		resultUrl: ctx.env["MPESA_RESULT_URL"],
+		queueTimeOutUrl: ctx.env["MPESA_QUEUE_TIMEOUT_URL"]
+	});
+	if (ctx.json) printJson(result);
+	else console.log(`${g("✔")} B2C payment submitted\n`, result);
+}
+async function cmdB2cDisburse(ctx) {
+	const mpesa = await mpesaFromEnv(ctx.env, { requireInitiator: true });
+	requireEnv(ctx.env, "MPESA_RESULT_URL", "MPESA_QUEUE_TIMEOUT_URL");
+	const result = await mpesa.b2cDisbursement({
+		originatorConversationId: getArg(ctx.args, "--originator-id") ?? await prompt("OriginatorConversationID"),
+		commandId: getArg(ctx.args, "--command") ?? "BusinessPayment",
+		amount: Number(getArg(ctx.args, "--amount") ?? ctx.args[0] ?? 0),
+		partyA: getArg(ctx.args, "--party-a") ?? ctx.env["MPESA_SHORTCODE"] ?? "",
+		partyB: getArg(ctx.args, "--phone") ?? ctx.args[1] ?? "",
+		remarks: getArg(ctx.args, "--remarks") ?? "pesafy CLI",
+		resultUrl: ctx.env["MPESA_RESULT_URL"],
+		queueTimeOutUrl: ctx.env["MPESA_QUEUE_TIMEOUT_URL"]
+	});
+	if (ctx.json) printJson(result);
+	else console.log(`${g("✔")} B2C disbursement submitted\n`, result);
+}
+async function cmdB2bCheckout(ctx) {
+	const result = await (await mpesaFromEnv(ctx.env)).b2bExpressCheckout({
+		primaryShortCode: getArg(ctx.args, "--primary") ?? ctx.env["MPESA_SHORTCODE"] ?? "",
+		receiverShortCode: getArg(ctx.args, "--receiver") ?? ctx.env["MPESA_SHORTCODE"] ?? "",
+		amount: Number(getArg(ctx.args, "--amount") ?? 0),
+		paymentRef: getArg(ctx.args, "--ref") ?? `REF-${Date.now()}`,
+		callbackUrl: getArg(ctx.args, "--callback") ?? ctx.env["MPESA_CALLBACK_URL"] ?? "",
+		partnerName: getArg(ctx.args, "--partner") ?? "pesafy"
+	});
+	if (ctx.json) printJson(result);
+	else console.log(`${g("✔")} B2B checkout initiated\n`, result);
+}
+async function cmdTaxRemit(ctx) {
+	const mpesa = await mpesaFromEnv(ctx.env, { requireInitiator: true });
+	requireEnv(ctx.env, "MPESA_RESULT_URL", "MPESA_QUEUE_TIMEOUT_URL");
+	const result = await mpesa.remitTax({
+		amount: Number(getArg(ctx.args, "--amount") ?? 0),
+		partyA: getArg(ctx.args, "--party-a") ?? ctx.env["MPESA_SHORTCODE"] ?? "",
+		accountReference: getArg(ctx.args, "--prn") ?? await prompt("KRA PRN"),
+		resultUrl: ctx.env["MPESA_RESULT_URL"],
+		queueTimeOutUrl: ctx.env["MPESA_QUEUE_TIMEOUT_URL"]
+	});
+	if (ctx.json) printJson(result);
+	else console.log(`${g("✔")} Tax remittance submitted\n`, result);
+}
+async function cmdQrGenerate(ctx) {
+	const result = await (await mpesaFromEnv(ctx.env)).generateDynamicQR(ctx.args[0] ? JSON.parse(ctx.args[0]) : {});
+	if (ctx.json) printJson(result);
+	else console.log(`${g("✔")} Dynamic QR generated\n`, result);
+}
+async function cmdBills(ctx) {
+	const sub = ctx.args[0];
+	const mpesa = await mpesaFromEnv(ctx.env);
+	const body = ctx.args[1] ? JSON.parse(ctx.args[1]) : {};
+	let result;
+	switch (sub) {
+		case "optin":
+			result = await mpesa.billManagerOptIn(body);
+			break;
+		case "invoice":
+			result = await mpesa.sendInvoice(body);
+			break;
+		case "bulk":
+			result = await mpesa.sendBulkInvoices(body);
+			break;
+		case "reconcile":
+			result = await mpesa.reconcilePayment(body);
+			break;
+		default:
+			console.error(r("Usage: pesafy bills <optin|invoice|bulk|reconcile> [json-body]"));
+			process.exit(1);
+	}
+	if (ctx.json) printJson(result);
+	else console.log(`${g("✔")} Bill manager ${sub}\n`, result);
+}
+
+//#endregion
+//#region src/cli/index.ts
+const GLOBAL_FLAGS = new Set([
+	"--json",
+	"--env-file",
+	"--env"
+]);
 async function main() {
-	const [, , command = "help", ...args] = process.argv;
-	const banner = `${C.cyan}${C.bold}  pesafy${C.reset} ${C.dim}v${getPkgVersion()}${C.reset}`;
+	const rawArgv = process.argv.slice(2);
+	const globalArgv = [];
+	let command = "help";
+	const commandArgs = [];
+	for (let i = 0; i < rawArgv.length; i++) {
+		const a = rawArgv[i];
+		if (GLOBAL_FLAGS.has(a)) {
+			globalArgv.push(a);
+			if (a === "--env-file" || a === "--env") globalArgv.push(rawArgv[++i] ?? "");
+			continue;
+		}
+		if (command === "help" && !a.startsWith("--")) {
+			command = a;
+			continue;
+		}
+		commandArgs.push(a);
+	}
+	const ctx = createCliContext([...globalArgv, ...commandArgs]);
+	const banner = `${C.cyan}${C.bold}  pesafy${C.reset} ${dim(`v${getPkgVersion()}`)}${C.reset}`;
 	process.stdout.write(`\n${banner}\n`);
 	const handler = {
 		init: cmdInit,
 		doctor: cmdDoctor,
 		token: cmdToken,
-		encrypt: () => cmdEncrypt(args),
-		"validate-phone": () => cmdValidatePhone(args),
-		"stk-push": () => cmdStkPush(args),
-		"stk-query": () => cmdStkQuery(args),
-		balance: () => cmdBalance(args),
-		"register-c2b-urls": () => cmdRegisterC2BUrls(args),
-		"simulate-c2b": () => cmdSimulateC2B(args),
-		reversal: () => cmdReversal(args),
+		encrypt: cmdEncrypt,
+		"validate-phone": cmdValidatePhone,
+		"stk-push": cmdStkPush,
+		"stk-query": cmdStkQuery,
+		balance: cmdBalance,
+		"register-c2b-urls": cmdRegisterC2BUrls,
+		"simulate-c2b": cmdSimulateC2B,
+		reversal: cmdReversal,
+		"tx-status": cmdTxStatus,
+		"b2c-payment": cmdB2cPayment,
+		"b2c-disburse": cmdB2cDisburse,
+		"b2b-checkout": cmdB2bCheckout,
+		"tax-remit": cmdTaxRemit,
+		"qr-generate": cmdQrGenerate,
+		bills: cmdBills,
 		version: cmdVersion,
 		help: cmdHelp,
 		"--help": cmdHelp,
@@ -628,7 +2902,7 @@ async function main() {
 		process.exit(1);
 	}
 	try {
-		await handler();
+		await handler(ctx);
 	} catch (e) {
 		console.error(r(`\n✖  Unhandled error: ${e.message}\n`));
 		if (process.env["PESAFY_DEBUG"]) console.error(e);
@@ -638,4 +2912,5 @@ async function main() {
 main();
 
 //#endregion
-export {  };
+export {  };
+//# sourceMappingURL=cli.mjs.map