pesafy 0.0.2 → 0.2.0

package/dist/index.js

@@ -1 +1,4197 @@
-import{readFile as e}from"node:fs/promises";import{constants as t,publicEncrypt as n}from"node:crypto";import{z as r}from"zod";var i=class e extends Error{code;statusCode;response;requestId;cause;retryable;constructor(t){super(t.message),Object.defineProperty(this,`name`,{value:`PesafyError`}),this.code=t.code,this.statusCode=t.statusCode,this.response=t.response,this.requestId=t.requestId,this.cause=t.cause,this.retryable=t.retryable??(t.code===`NETWORK_ERROR`||t.code===`TIMEOUT`||t.code===`RATE_LIMITED`||t.code===`REQUEST_FAILED`),Error.captureStackTrace&&Error.captureStackTrace(this,e)}get isValidation(){return this.code===`VALIDATION_ERROR`}get isAuth(){return this.code===`AUTH_FAILED`||this.code===`INVALID_CREDENTIALS`}toJSON(){return{name:this.name,code:this.code,message:this.message,statusCode:this.statusCode,requestId:this.requestId,retryable:this.retryable}}};function a(e){return new i(e)}function o(e){return e instanceof i}function s(e,t){return t?.idempotency?{...e,idempotency:t.idempotency}:e}const c=new Set([429,500,502,503,504]);function l(e){return new Promise(t=>setTimeout(t,e))}function u(e){let t=e*.25;return e+(Math.random()*t*2-t)}async function d(e,t){let n=t.retries??4,r=t.retryDelay??2e3,a=t.timeout??3e4,o={"Content-Type":`application/json`,Accept:`application/json`,...t.headers},s=t.idempotency,d=t.idempotencyKey;if(t.method===`POST`&&s?.enabled){d=s.reserve(d);let e=s.headerName;o[e]=d}else d&&(o[`Idempotency-Key`]=d);let f={method:t.method,headers:o,...t.body===void 0?{}:{body:JSON.stringify(t.body)}},p=null;for(let o=0;o<=n;o++){if(o>0){let i=u(r*2**(o-1));console.warn(`[pesafy] Retry ${o}/${n} → ${t.method} ${e} in ${Math.round(i)} ms`),await l(i)}let m=new AbortController,h=setTimeout(()=>m.abort(),a),g;try{g=await fetch(e,{...f,signal:m.signal})}catch(t){if(clearTimeout(h),p=t instanceof Error&&t.name===`AbortError`?new i({code:`TIMEOUT`,message:`Request to ${e} timed out after ${a} ms`,cause:t,retryable:!0}):new i({code:`NETWORK_ERROR`,message:`Network error: ${t instanceof Error?t.message:String(t)}`,cause:t,retryable:!0}),o<n)continue;throw d&&s?.enabled&&s.release(d),p}finally{clearTimeout(h)}let _=``,v=null,y=g.headers.get(`content-type`)??``;try{_=await g.text(),_&&(v=y.includes(`application/json`)?JSON.parse(_):_)}catch{v=_||null}let b={};if(g.headers.forEach((e,t)=>{b[t]=e}),g.ok)return d&&s?.enabled&&s.complete(d),{data:v,status:g.status,headers:b};let x=c.has(g.status),S=typeof v==`object`&&v?v:{},ee=S.errorMessage??S.ResponseDescription??S.resultDesc??_??`HTTP ${g.status}`;if(p=new i({code:x?`REQUEST_FAILED`:`API_ERROR`,message:ee,statusCode:g.status,response:v,retryable:x,...typeof S.requestId==`string`?{requestId:S.requestId}:{}}),!(x&&o<n))throw d&&s?.enabled&&s.release(d),p}throw d&&s?.enabled&&s.release(d),p}const f={INVALID_AUTH_TYPE:`400.008.01`,INVALID_GRANT_TYPE:`400.008.02`};var p=class{consumerKey;consumerSecret;baseUrl;cachedToken=null;tokenExpiresAt=0;constructor(e,t,n){this.consumerKey=e,this.consumerSecret=t,this.baseUrl=n}getBasicAuthHeader(){let e=`${this.consumerKey}:${this.consumerSecret}`;return`Basic ${Buffer.from(e,`utf-8`).toString(`base64`)}`}mapAuthError(e){if(e instanceof i){if(e.code===`AUTH_FAILED`)throw e;let t=e.response;if(t&&typeof t==`object`){let n=t.errorCode??t.error_code;if(n===f.INVALID_AUTH_TYPE)throw new i({code:`AUTH_FAILED`,message:`Invalid authentication type (400.008.01). Use Basic authentication: Authorization: Basic <Base64(consumerKey:consumerSecret)>.`,...e.statusCode!==void 0&&{statusCode:e.statusCode},response:e.response});if(n===f.INVALID_GRANT_TYPE)throw new i({code:`AUTH_FAILED`,message:`Invalid grant type (400.008.02). Set grant_type=client_credentials in the request query parameters.`,...e.statusCode!==void 0&&{statusCode:e.statusCode},response:e.response})}throw e}throw e}async getAccessToken(){let e=Date.now()/1e3;if(this.cachedToken&&this.tokenExpiresAt>e+60)return this.cachedToken;let t=`${this.baseUrl}/oauth/v1/generate?grant_type=client_credentials`;try{let n=await d(t,{method:`GET`,headers:{Authorization:this.getBasicAuthHeader()}}),{access_token:r,expires_in:a}=n.data;if(!r)throw new i({code:`AUTH_FAILED`,message:`Daraja did not return an access token. Verify your consumer key and consumer secret.`,response:n.data});return this.cachedToken=r,this.tokenExpiresAt=e+(a??3600),this.cachedToken}catch(e){return this.mapAuthError(e)}}clearCache(){this.cachedToken=null,this.tokenExpiresAt=0}};function m(e,r){try{let i=Buffer.from(e,`utf-8`);return n({key:r,padding:t.RSA_PKCS1_PADDING},i).toString(`base64`)}catch(e){throw new i({code:`ENCRYPTION_FAILED`,message:`Failed to encrypt security credential. Ensure the certificate PEM is valid and matches the environment (sandbox/production).`,cause:e})}}function h(e){let t=crypto.randomUUID();return e?`${e}-${t}`:t}function g(){return h(`pesafy`)}function _(){return crypto.randomUUID()}var v=class{entries=new Map;get(e){return this.entries.get(e)}set(e,t){this.entries.set(e,t)}delete(e){this.entries.delete(e)}prune(e){let t=Date.now()-e;for(let[e,n]of this.entries)n.createdAt<t&&this.entries.delete(e)}},y=class{enabled;headerName;ttlMs;store;generateKey;constructor(e={}){this.enabled=e.enabled!==!1,this.headerName=e.headerName??`Idempotency-Key`,this.ttlMs=e.ttlMs??864e5,this.store=e.store??new v,this.generateKey=e.generateKey??h}reserve(e){if(!this.enabled)return e??this.generateKey();this.pruneExpired();let t=e??this.generateKey(),n=this.store.get(t);if(n){if(Date.now()-n.createdAt<this.ttlMs)throw new i({code:`IDEMPOTENCY_ERROR`,message:`Duplicate request detected for idempotency key "${t}".`});this.store.delete(t)}return this.store.set(t,{key:t,createdAt:Date.now()}),t}complete(e){if(!this.enabled)return;let t=this.store.get(e);t&&this.store.set(e,{...t,completedAt:Date.now()})}release(e){this.enabled&&this.store.delete(e)}pruneExpired(){this.store instanceof v&&this.store.prune(this.ttlMs)}};function b(e){let t=Math.round(e);if(!Number.isFinite(t)||t<1)throw TypeError(`KesAmount must be a whole number ≥ 1, got ${e}`);return t}function x(e){let t=e.replace(/\D/g,``),n;if(t.startsWith(`254`)&&t.length===12)n=t;else if(t.startsWith(`0`)&&t.length===10)n=`254${t.slice(1)}`;else if(t.length===9)n=`254${t}`;else throw TypeError(`Cannot normalise "${e}" to 254XXXXXXXXX. Use 07XX…, 2547XX…, or +2547XX….`);if(n.length!==12)throw TypeError(`Phone "${e}" normalised to "${n}" — expected 12 digits.`);return n}function S(e){return String(e)}function ee(e){return String(e)}function te(e){return String(e)}function C(e){return{ok:!0,data:e}}function w(e){return{ok:!1,error:e}}function ne(e){if(!e.trim())throw TypeError(`String must not be empty`);return e}function re(e,t=`Request`){return new i({code:`VALIDATION_ERROR`,message:`${t} validation failed: ${e.issues.map(e=>`${e.path.join(`.`)}: ${e.message}`).join(`; `)}`,cause:e})}function T(e,t,n){let r=e.safeParse(t);if(!r.success)throw re(r.error,n);return r.data}const ie=r.enum([`sandbox`,`production`]),ae=r.string().min(10).regex(/^254\d{9}$/,`Must be Safaricom format 2547XXXXXXXX`),E=r.number().finite().positive().refine(e=>Math.round(e)>=1,{message:`amount must round to at least 1 KES`}),D=r.string().trim().min(1),O=r.string().url(),oe=r.object({errorMessage:r.string().optional(),ResponseDescription:r.string().optional(),resultDesc:r.string().optional(),requestId:r.string().optional()}).passthrough(),se=r.enum([`1`,`2`,`4`]),k=r.object({ConversationID:r.string().optional(),OriginatorConversationID:r.string().optional(),ResponseCode:r.string(),ResponseDescription:r.string()}).passthrough(),ce=r.object({transactionId:r.string().optional(),originalConversationId:r.string().optional(),partyA:D,identifierType:se,resultUrl:O,queueTimeOutUrl:O,commandId:r.literal(`TransactionStatusQuery`).optional(),remarks:r.string().optional(),occasion:r.string().optional()}).superRefine((e,t)=>{!e.transactionId?.trim()&&!e.originalConversationId?.trim()&&t.addIssue({code:`custom`,message:`Either transactionId (M-Pesa Receipt Number) or originalConversationId is required`,path:[`transactionId`]})}),le=k,ue=r.object({partyA:D,identifierType:se,resultUrl:O,queueTimeOutUrl:O,remarks:r.string().optional()}),de=k,fe=r.object({transactionId:D,receiverParty:D,receiverIdentifierType:r.literal(`11`).optional(),amount:E,resultUrl:O,queueTimeOutUrl:O,remarks:r.string().optional(),occasion:r.string().optional()}).superRefine((e,t)=>{e.receiverIdentifierType!==void 0&&e.receiverIdentifierType!==`11`&&t.addIssue({code:`custom`,message:`receiverIdentifierType must be "11" for the Reversals API`,path:[`receiverIdentifierType`]});let n=e.remarks??`Transaction Reversal`;(n.length<2||n.length>100)&&t.addIssue({code:`custom`,message:`remarks must be between 2 and 100 characters`,path:[`remarks`]})}),pe=k,me=r.object({amount:E,partyA:D,partyB:r.string().optional(),accountReference:D,resultUrl:O,queueTimeOutUrl:O,remarks:r.string().optional()}),he=k,ge=r.object({merchantName:D,refNo:D,amount:E,trxCode:r.enum([`BG`,`WA`,`PB`,`SM`,`SB`]),cpi:D,size:r.number().int().min(1).max(1e3).optional()}),_e=r.object({ResponseCode:r.string(),RequestID:r.string().optional(),ResponseDescription:r.string(),QRCode:r.string().optional()}).passthrough();async function ve(e,t,n,r,i,a){let o=T(ue,i,`Account Balance request`),c={Initiator:r,SecurityCredential:n,CommandID:`AccountBalance`,PartyA:String(o.partyA.trim()),IdentifierType:o.identifierType,ResultURL:o.resultUrl,QueueTimeOutURL:o.queueTimeOutUrl,Remarks:o.remarks??`Account Balance Query`},{data:l}=await d(`${e}/mpesa/accountbalance/v1/query`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:c},a));return T(de,l,`Account Balance response`)}const ye={DUPLICATE_DETECTED:15,INTERNAL_FAILURE:17,INITIATOR_CREDENTIAL_CHECK_FAILURE:18,MESSAGE_SEQUENCING_FAILURE:19,UNRESOLVED_INITIATOR:20,INITIATOR_TO_PRIMARY_PARTY_PERMISSION_FAILURE:21,INITIATOR_TO_RECEIVER_PARTY_PERMISSION_FAILURE:22,MISSING_MANDATORY_FIELDS:24,SYSTEM_OVERLOAD:100000001,THROTTLING_ERROR:100000002,INTERNAL_SERVER_ERROR:100000004,INVALID_INPUT_VALUE:100000005,SERVICE_ABNORMAL:100000007,API_STATUS_ABNORMAL:100000009,INSUFFICIENT_PERMISSIONS:100000010,REQUEST_RATE_EXCEEDED:100000011};function be(e){if(!e.trim())return[];let t=e.split(`|`),n=[];for(let e=0;e+2<t.length;e++){let r=t[e]?.trim(),i=t[e+1]?.trim(),a=t[e+2]?.trim();r&&i&&a!==void 0&&isNaN(Number(r))&&r.length>0&&n.push({name:r,currency:i,amount:a})}return n}function A(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n)return(Array.isArray(n)?n:[n]).find(e=>e.Key===t)?.Value}function xe(e){return e.Result.TransactionID}function Se(e){return e.Result.ConversationID}function Ce(e){return e.Result.OriginatorConversationID}function we(e){let t=A(e,`BOCompletedTime`);return t==null?null:String(t)}function Te(e){let t=A(e,`AccountBalance`);return t==null?null:String(t)}function Ee(e){let t=e.Result.ReferenceData;if(!t)return null;let n=t.ReferenceItem;return n?Array.isArray(n)?n[0]??null:n:null}function De(e){let t=e.Result.ResultCode;return t===0||t===`0`}const Oe=r.object({ConversationID:r.string(),OriginatorConversationID:r.string(),ResponseCode:r.string(),ResponseDescription:r.string()}).passthrough(),ke=r.object({amount:E,partyA:D,partyB:D,accountReference:D,requester:r.string().optional(),remarks:r.string().optional(),resultUrl:O,queueTimeOutUrl:O,occasion:r.string().optional()}),Ae=ke.extend({commandId:r.literal(`BusinessBuyGoods`)}),je=ke.extend({commandId:r.literal(`BusinessPayBill`)}),Me=Oe,Ne=Oe,Pe=r.object({primaryShortCode:D,receiverShortCode:D,amount:E,paymentRef:D,callbackUrl:O,partnerName:D,requestRefId:D.optional()}),Fe=r.object({code:r.string(),status:r.string()}).passthrough(),Ie=r.object({ConversationID:r.string().optional(),OriginatorConversationID:r.string().optional(),ResponseCode:r.string(),ResponseDescription:r.string()}).passthrough();async function Le(e,t,n,r){let i=T(Pe,n,`B2B Express Checkout request`),a=Math.round(i.amount),o={primaryShortCode:String(i.primaryShortCode),receiverShortCode:String(i.receiverShortCode),amount:String(a),paymentRef:i.paymentRef,callbackUrl:i.callbackUrl,partnerName:i.partnerName,RequestRefID:i.requestRefId??_()},{data:c}=await d(`${e}/v1/ussdpush/get-msisdn`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:o},r));return T(Fe,c,`B2B Express Checkout response`)}const j={SUCCESS:`0`,CANCELLED:`4001`,KYC_FAIL:`4102`,NO_NOMINATED_NUMBER:`4104`,USSD_NETWORK_ERROR:`4201`,USSD_EXCEPTION_ERROR:`4203`};new Set(Object.values(j));function Re(e){if(!e||typeof e!=`object`)return!1;let t=e;return typeof t.resultCode==`string`&&typeof t.requestId==`string`&&typeof t.amount==`string`}function M(e){return e.resultCode===j.SUCCESS}function ze(e){return e.resultCode===j.CANCELLED}function Be(e){return e.requestId}function Ve(e){return Number(e.amount)}function He(e){return M(e)?e.transactionId??null:null}function Ue(e){return M(e)?e.conversationID??null:null}async function N(e,t,n,r,i,a){let o=T(Ae,i,`B2B Buy Goods request`),c=Math.round(o.amount),l={Initiator:r,SecurityCredential:n,CommandID:o.commandId,SenderIdentifierType:`4`,RecieverIdentifierType:`4`,Amount:String(c),PartyA:String(o.partyA),PartyB:String(o.partyB),AccountReference:o.accountReference.slice(0,13),Remarks:o.remarks??`Business Buy Goods`,QueueTimeOutURL:o.queueTimeOutUrl,ResultURL:o.resultUrl};o.requester?.trim()&&(l.Requester=String(o.requester)),o.occasion?.trim()&&(l.Occassion=o.occasion);let{data:u}=await d(`${e}/mpesa/b2b/v1/paymentrequest`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:l},a));return T(Me,u,`B2B Buy Goods response`)}const We={SUCCESS:0,INSUFFICIENT_FUNDS:1,AMOUNT_TOO_SMALL:2,AMOUNT_TOO_LARGE:3,DAILY_LIMIT_EXCEEDED:4,MAX_BALANCE_EXCEEDED:8,INVALID_INITIATOR_INFO:2001,ACCOUNT_INACTIVE:2006,PRODUCT_NOT_PERMITTED:2028,CUSTOMER_NOT_REGISTERED:2040},Ge={INVALID_ACCESS_TOKEN:`400.003.01`,BAD_REQUEST:`400.003.02`,INTERNAL_SERVER_ERROR:`500.003.1001`,QUOTA_VIOLATION:`500.003.03`,SPIKE_ARREST:`500.003.02`,NOT_FOUND:`404.003.01`,INVALID_AUTH_HEADER:`404.001.04`,INVALID_PAYLOAD:`400.002.05`},Ke=new Set(Object.values(We));function qe(e){if(!e||typeof e!=`object`)return!1;let t=e;if(!t.Result||typeof t.Result!=`object`)return!1;let n=t.Result;return(typeof n.ResultCode==`number`||typeof n.ResultCode==`string`)&&typeof n.ConversationID==`string`&&typeof n.OriginatorConversationID==`string`}function Je(e){let t=e.Result.ResultCode;return t===0||t===`0`}function Ye(e){return!Je(e)}function Xe(e){if(typeof e!=`number`&&typeof e!=`string`||typeof e==`string`&&e.trim()===``)return!1;let t=Number(e);return Number.isFinite(t)&&Ke.has(t)}function Ze(e){return e.Result.TransactionID}function Qe(e){return e.Result.ConversationID}function $e(e){return e.Result.OriginatorConversationID}function et(e){return e.Result.ResultDesc}function tt(e){return e.Result.ResultCode}function nt(e){let t=P(e,`Amount`);if(t===void 0)return null;let n=Number(t);return Number.isFinite(n)?n:null}function rt(e){let t=P(e,`TransCompletedTime`)??P(e,`BOCompletedTime`);return t===void 0?null:String(t)}function it(e){let t=P(e,`ReceiverPartyPublicName`);return t===void 0?null:String(t)}function at(e){let t=P(e,`DebitPartyCharges`);return t===void 0||t===``?null:String(t)}function ot(e){let t=P(e,`Currency`);return t===void 0||t===``?`KES`:String(t)}function st(e){let t=P(e,`DebitPartyAffectedAccountBalance`);return t===void 0?null:String(t)}function ct(e){let t=P(e,`DebitAccountBalance`);return t===void 0?null:String(t)}function lt(e){let t=P(e,`InitiatorAccountCurrentBalance`);return t===void 0?null:String(t)}function ut(e){let t=e.Result.ReferenceData?.ReferenceItem;return t?(Array.isArray(t)?t:[t]).find(e=>e.Key===`BillReferenceNumber`)?.Value??null:null}function dt(e){let t=e.Result.ReferenceData?.ReferenceItem;return t?(Array.isArray(t)?t:[t]).find(e=>e.Key===`QueueTimeoutURL`)?.Value??null:null}function P(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n)return(Array.isArray(n)?n:[n]).find(e=>e.Key===t)?.Value}async function ft(e,t,n,r,i,a){let o=T(je,i,`B2B Pay Bill request`),c=Math.round(o.amount),l={Initiator:r,SecurityCredential:n,CommandID:o.commandId,SenderIdentifierType:`4`,RecieverIdentifierType:`4`,Amount:String(c),PartyA:String(o.partyA),PartyB:String(o.partyB),AccountReference:o.accountReference.slice(0,13),Remarks:o.remarks??`Business Pay Bill`,QueueTimeOutURL:o.queueTimeOutUrl,ResultURL:o.resultUrl};o.requester?.trim()&&(l.Requester=String(o.requester)),o.occasion?.trim()&&(l.Occassion=o.occasion);let{data:u}=await d(`${e}/mpesa/b2b/v1/paymentrequest`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:l},a));return T(Ne,u,`B2B Pay Bill response`)}const pt={SUCCESS:0,INSUFFICIENT_FUNDS:1,AMOUNT_TOO_SMALL:2,AMOUNT_TOO_LARGE:3,DAILY_LIMIT_EXCEEDED:4,MAX_BALANCE_EXCEEDED:8,INVALID_INITIATOR_INFO:2001,ACCOUNT_INACTIVE:2006,PRODUCT_NOT_PERMITTED:2028,CUSTOMER_NOT_REGISTERED:2040},mt={INVALID_ACCESS_TOKEN:`400.003.01`,BAD_REQUEST:`400.003.02`,INTERNAL_SERVER_ERROR:`500.003.1001`,QUOTA_VIOLATION:`500.003.03`,SPIKE_ARREST:`500.003.02`,NOT_FOUND:`404.003.01`,INVALID_AUTH_HEADER:`404.001.04`,INVALID_PAYLOAD:`400.002.05`},ht=new Set(Object.values(pt));function gt(e){if(!e||typeof e!=`object`)return!1;let t=e;if(!t.Result||typeof t.Result!=`object`)return!1;let n=t.Result;return(typeof n.ResultCode==`number`||typeof n.ResultCode==`string`)&&typeof n.ConversationID==`string`&&typeof n.OriginatorConversationID==`string`}function _t(e){let t=e.Result.ResultCode;return t===0||t===`0`}function vt(e){return!_t(e)}function yt(e){if(typeof e!=`number`&&typeof e!=`string`||typeof e==`string`&&e.trim()===``)return!1;let t=Number(e);return Number.isFinite(t)&&ht.has(t)}function bt(e){return e.Result.TransactionID}function xt(e){return e.Result.ConversationID}function St(e){return e.Result.OriginatorConversationID}function Ct(e){return e.Result.ResultDesc}function wt(e){return e.Result.ResultCode}function Tt(e){let t=F(e,`Amount`);if(t===void 0)return null;let n=Number(t);return Number.isFinite(n)?n:null}function Et(e){let t=F(e,`TransCompletedTime`)??F(e,`BOCompletedTime`);return t===void 0?null:String(t)}function Dt(e){let t=F(e,`ReceiverPartyPublicName`);return t===void 0?null:String(t)}function Ot(e){let t=F(e,`DebitPartyCharges`);return t===void 0||t===``?null:String(t)}function kt(e){let t=F(e,`Currency`);return t===void 0||t===``?`KES`:String(t)}function At(e){let t=F(e,`DebitPartyAffectedAccountBalance`);return t===void 0?null:String(t)}function jt(e){let t=F(e,`DebitAccountCurrentBalance`);return t===void 0?null:String(t)}function Mt(e){let t=F(e,`InitiatorAccountCurrentBalance`);return t===void 0?null:String(t)}function Nt(e){let t=e.Result.ReferenceData?.ReferenceItem;return t?(Array.isArray(t)?t:[t]).find(e=>e.Key===`BillReferenceNumber`)?.Value??null:null}function F(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n)return(Array.isArray(n)?n:[n]).find(e=>e.Key===t)?.Value}const Pt=r.object({ConversationID:r.string(),OriginatorConversationID:r.string(),ResponseCode:r.string(),ResponseDescription:r.string()}).passthrough(),Ft=r.object({commandId:r.literal(`BusinessPayToBulk`),amount:E,partyA:D,partyB:D,accountReference:D,requester:r.string().optional(),remarks:r.string().optional(),resultUrl:O,queueTimeOutUrl:O}),It=Pt,Lt=r.object({commandId:r.enum([`BusinessPayment`,`SalaryPayment`,`PromotionPayment`]),amount:r.number().finite().positive(),partyA:D,partyB:D,remarks:D,queueTimeOutUrl:O,resultUrl:O,originatorConversationId:D.optional(),occasion:r.string().optional()}),Rt=Pt;async function zt(e,t,n,r,i,a){let o=T(Ft,i,`B2C request`),c=Math.round(o.amount),l={Initiator:r,SecurityCredential:n,CommandID:o.commandId,SenderIdentifierType:`4`,RecieverIdentifierType:`4`,Amount:String(c),PartyA:String(o.partyA),PartyB:String(o.partyB),AccountReference:o.accountReference,Remarks:o.remarks??`B2C Account Top Up`,QueueTimeOutURL:o.queueTimeOutUrl,ResultURL:o.resultUrl};o.requester?.trim()&&(l.Requester=String(o.requester));let{data:u}=await d(`${e}/mpesa/b2b/v1/paymentrequest`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:l},a));return T(It,u,`B2C response`)}const Bt={INTERNAL_SERVER_ERROR:`500.003.1001`,INVALID_ACCESS_TOKEN:`400.003.01`,BAD_REQUEST:`400.003.02`,QUOTA_VIOLATION:`500.003.03`,SPIKE_ARREST:`500.003.02`,NOT_FOUND:`404.003.01`,INVALID_AUTH_HEADER:`404.001.04`,INVALID_PAYLOAD:`400.002.05`},Vt={SUCCESS:0,INVALID_INITIATOR:2001};function Ht(e){if(!e||typeof e!=`object`)return!1;let t=e;if(!t.Result||typeof t.Result!=`object`)return!1;let n=t.Result;return(typeof n.ResultCode==`number`||typeof n.ResultCode==`string`)&&typeof n.ConversationID==`string`&&typeof n.OriginatorConversationID==`string`}function Ut(e){let t=e.Result.ResultCode;return t===0||t===`0`}function Wt(e){return!Ut(e)}function Gt(e){if(typeof e!=`number`&&typeof e!=`string`||typeof e==`string`&&e.trim()===``)return!1;let t=Number(e);return Object.values(Vt).includes(t)}function Kt(e){return e.Result.TransactionID??null}function qt(e){return e.Result.ConversationID}function Jt(e){return e.Result.OriginatorConversationID}function Yt(e){return e.Result.ResultDesc}function Xt(e){let t=I(e,`Amount`);if(t===void 0)return null;let n=Number(t);return Number.isFinite(n)?n:null}function Zt(e){let t=I(e,`Currency`);return t===void 0||t===``?`KES`:String(t)}function Qt(e){let t=I(e,`ReceiverPartyPublicName`);return t===void 0?null:String(t)}function $t(e){let t=I(e,`TransactionCompletedTime`);return t===void 0?null:String(t)}function en(e){let t=I(e,`DebitAccountBalance`);return t===void 0?null:String(t)}function tn(e){let t=I(e,`DebitPartyCharges`);return t===void 0||t===``?null:String(t)}function I(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n)return(Array.isArray(n)?n:[n]).find(e=>e.Key===t)?.Value}const nn=new Set([`BusinessPayment`,`SalaryPayment`,`PromotionPayment`]);async function rn(e,t,n,r,i,o){let c=i.originatorConversationId?.trim()||g(),l=T(Lt,{...i,originatorConversationId:c},`B2C Disbursement request`);if(!l.commandId||!nn.has(l.commandId))throw a({code:`VALIDATION_ERROR`,message:`commandId must be one of: BusinessPayment, SalaryPayment, PromotionPayment. Got "${l.commandId}".`});let u=Math.round(l.amount);if(!Number.isFinite(u)||u<10)throw a({code:`VALIDATION_ERROR`,message:`amount must be ≥ 10 KES (got ${l.amount} which rounds to ${u}).`});if(!l.partyA?.trim())throw a({code:`VALIDATION_ERROR`,message:`partyA is required — the sending organisation shortcode.`});if(!l.partyB?.trim())throw a({code:`VALIDATION_ERROR`,message:`partyB is required — the receiving customer MSISDN (2547XXXXXXXX).`});if(!l.remarks?.trim())throw a({code:`VALIDATION_ERROR`,message:`remarks is required (2–100 characters).`});if(!l.resultUrl?.trim())throw a({code:`VALIDATION_ERROR`,message:`resultUrl is required — Safaricom POSTs the async result here.`});if(!l.queueTimeOutUrl?.trim())throw a({code:`VALIDATION_ERROR`,message:`queueTimeOutUrl is required — Safaricom calls this on request timeout.`});let f={OriginatorConversationID:c,InitiatorName:r,SecurityCredential:n,CommandID:l.commandId,Amount:u,PartyA:String(l.partyA),PartyB:String(l.partyB),Remarks:l.remarks,QueueTimeOutURL:l.queueTimeOutUrl,ResultURL:l.resultUrl};l.occasion?.trim()&&(f.Occassion=l.occasion);let{data:p}=await d(`${e}/mpesa/b2c/v3/paymentrequest`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:f},o));return T(Rt,p,`B2C Disbursement response`)}const L={SUCCESS:0,INSUFFICIENT_BALANCE:1,AMOUNT_TOO_SMALL:2,AMOUNT_TOO_LARGE:3,DAILY_LIMIT_EXCEEDED:4,MAX_BALANCE_EXCEEDED:8,DEBIT_PARTY_INVALID:11,INITIATOR_NOT_ALLOWED:21,INVALID_INITIATOR_INFO:2001,ACCOUNT_INACTIVE:2006,PRODUCT_NOT_PERMITTED:2028,CUSTOMER_NOT_REGISTERED:2040,SECURITY_CREDENTIAL_LOCKED:8006,OPERATOR_DOES_NOT_EXIST:`SFC_IC0003`};function an(e){if(!e||typeof e!=`object`)return!1;let t=e;if(!t.Result||typeof t.Result!=`object`)return!1;let n=t.Result;return(typeof n.ResultCode==`number`||typeof n.ResultCode==`string`)&&typeof n.ConversationID==`string`&&typeof n.OriginatorConversationID==`string`}function on(e){let t=e.Result.ResultCode;return t===0||t===`0`}function sn(e){return!on(e)}function cn(e){if(e==null||typeof e!=`number`&&typeof e!=`string`)return!1;if(typeof e==`string`&&e===L.OPERATOR_DOES_NOT_EXIST)return!0;if(typeof e==`string`&&e.trim()===``)return!1;let t=Number(e);return Object.values(L).filter(e=>typeof e==`number`).includes(t)}function ln(e){return e.Result.TransactionID??null}function un(e){return e.Result.ConversationID}function dn(e){return e.Result.OriginatorConversationID}function fn(e){return e.Result.ResultDesc}function pn(e){return e.Result.ResultCode}function R(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n)return(Array.isArray(n)?n:[n]).find(e=>e.Key===t)?.Value}function mn(e){let t=R(e,`TransactionAmount`);if(t===void 0)return null;let n=Number(t);return Number.isFinite(n)?n:null}function hn(e){let t=R(e,`TransactionReceipt`);return t===void 0?null:String(t)}function gn(e){let t=R(e,`ReceiverPartyPublicName`);return t===void 0?null:String(t)}function _n(e){let t=R(e,`TransactionCompletedDateTime`);return t===void 0?null:String(t)}function vn(e){let t=R(e,`B2CUtilityAccountAvailableFunds`);if(t===void 0)return null;let n=Number(t);return Number.isFinite(n)?n:null}function yn(e){let t=R(e,`B2CWorkingAccountAvailableFunds`);if(t===void 0)return null;let n=Number(t);return Number.isFinite(n)?n:null}function bn(e){let t=R(e,`B2CRecipientIsRegisteredCustomer`);return t===void 0?null:String(t).toUpperCase()===`Y`}const xn=r.enum([`0`,`1`]),z=r.object({shortcode:D,email:D,officialContact:D,sendReminders:xn,logo:r.string().optional(),callbackUrl:O}),Sn=r.object({app_key:r.string().optional(),resmsg:r.string(),rescode:r.string()}).passthrough(),Cn=z,wn=r.object({resmsg:r.string(),rescode:r.string()}).passthrough(),Tn=r.object({itemName:D,amount:E}),B=r.object({externalReference:D,billedFullName:D,billedPhoneNumber:D,billedPeriod:D,invoiceName:D,dueDate:D,accountReference:D,amount:E,invoiceItems:r.array(Tn).optional()}),En=r.object({Status_Message:r.string().optional(),resmsg:r.string(),rescode:r.string()}).passthrough(),Dn=r.object({invoices:r.array(B).min(1).max(1e3)}),On=r.object({Status_Message:r.string().optional(),resmsg:r.string(),rescode:r.string()}).passthrough(),kn=r.object({externalReference:D}),An=r.object({Status_Message:r.string().optional(),resmsg:r.string(),rescode:r.string(),errors:r.array(r.unknown()).optional()}).passthrough(),jn=r.object({externalReferences:r.array(D).min(1)}),Mn=r.object({Status_Message:r.string().optional(),resmsg:r.string(),rescode:r.string(),errors:r.array(r.unknown()).optional()}).passthrough(),Nn=r.object({paymentDate:D,paidAmount:D,accountReference:D,transactionId:D,phoneNumber:D,fullName:D,invoiceName:D,externalReference:D}),Pn=r.object({resmsg:r.string(),rescode:r.string()}).passthrough();async function Fn(e,t,n,r){let i=T(z,n,`Bill Manager opt-in request`),a={shortcode:i.shortcode,email:i.email,officialContact:i.officialContact,sendReminders:i.sendReminders,logo:i.logo??``,callbackurl:i.callbackUrl},{data:o}=await d(`${e}/v1/billmanager-invoice/optin`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:a},r));return T(Sn,o,`Bill Manager opt-in response`)}async function In(e,t,n,r){let i=T(Cn,n,`Bill Manager update opt-in request`),a={shortcode:i.shortcode,email:i.email,officialContact:i.officialContact,sendReminders:i.sendReminders,logo:i.logo??``,callbackurl:i.callbackUrl},{data:o}=await d(`${e}/v1/billmanager-invoice/change-optin-details`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:a},r));return T(wn,o,`Bill Manager update opt-in response`)}async function Ln(e,t,n,r){let i=T(B,n,`Bill Manager single invoice request`),a=Math.round(i.amount),o={externalReference:i.externalReference,billedFullName:i.billedFullName,billedPhoneNumber:i.billedPhoneNumber,billedPeriod:i.billedPeriod,invoiceName:i.invoiceName,dueDate:i.dueDate,accountReference:i.accountReference,amount:String(a),invoiceItems:i.invoiceItems?.map(e=>({itemName:e.itemName,amount:String(Math.round(e.amount))}))??[]},{data:c}=await d(`${e}/v1/billmanager-invoice/single-invoicing`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:o},r));return T(En,c,`Bill Manager single invoice response`)}async function V(e,t,n,r){let i=T(Dn,n,`Bill Manager bulk invoice request`).invoices.map(e=>({externalReference:e.externalReference,billedFullName:e.billedFullName,billedPhoneNumber:e.billedPhoneNumber,billedPeriod:e.billedPeriod,invoiceName:e.invoiceName,dueDate:e.dueDate,accountReference:e.accountReference,amount:String(Math.round(e.amount)),invoiceItems:e.invoiceItems?.map(e=>({itemName:e.itemName,amount:String(Math.round(e.amount))}))??[]})),{data:a}=await d(`${e}/v1/billmanager-invoice/bulk-invoicing`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:i},r));return T(On,a,`Bill Manager bulk invoice response`)}async function Rn(e,t,n,r){let i=T(kn,n,`Bill Manager cancel invoice request`),{data:a}=await d(`${e}/v1/billmanager-invoice/cancel-single-invoice`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:{externalReference:i.externalReference}},r));return T(An,a,`Bill Manager cancel invoice response`)}async function zn(e,t,n,r){let i=T(jn,n,`Bill Manager cancel bulk invoices request`).externalReferences.map(e=>({externalReference:e})),{data:a}=await d(`${e}/v1/billmanager-invoice/cancel-bulk-invoices`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:i},r));return T(Mn,a,`Bill Manager cancel bulk invoices response`)}async function Bn(e,t,n,r){let i=T(Nn,n,`Bill Manager reconciliation request`),a={paymentDate:i.paymentDate,paidAmount:i.paidAmount,accountReference:i.accountReference,transactionId:i.transactionId,phoneNumber:i.phoneNumber,fullName:i.fullName,invoiceName:i.invoiceName,externalReference:i.externalReference},{data:o}=await d(`${e}/v1/billmanager-invoice/reconciliation`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:a},r));return T(Pn,o,`Bill Manager reconciliation response`)}const Vn=r.object({shortCode:D,responseType:r.enum([`Completed`,`Cancelled`]),confirmationUrl:O,validationUrl:O,apiVersion:r.enum([`v1`,`v2`]).optional()}),H=r.object({OriginatorCoversationID:r.string(),ResponseCode:r.string(),ResponseDescription:r.string()}).passthrough(),Hn=H,Un=H,Wn=r.object({shortCode:r.union([D,r.number()]),commandId:r.enum([`CustomerPayBillOnline`,`CustomerBuyGoodsOnline`]),amount:E,msisdn:r.union([D,r.number()]),billRefNumber:r.union([D,r.null()]).optional(),apiVersion:r.enum([`v1`,`v2`]).optional()}).superRefine((e,t)=>{e.commandId===`CustomerPayBillOnline`&&!e.billRefNumber?.trim()&&t.addIssue({code:`custom`,message:`billRefNumber is required for CustomerPayBillOnline`,path:[`billRefNumber`]})}),Gn=r.object({TransactionType:r.string(),TransID:r.string(),TransTime:r.string(),TransAmount:r.union([r.string(),r.number()]),BusinessShortCode:r.string(),BillRefNumber:r.string().optional(),MSISDN:r.string()}).passthrough(),Kn=[`mpesa`,`safaricom`,`exec`,`exe`,`cme`,`cmd`,`sql`,`query`];function qn(e,t){if(!e||!e.trim())throw a({code:`VALIDATION_ERROR`,message:`${t} is required`});let n=e.toLowerCase();for(let e of Kn)if(n.includes(e))throw a({code:`VALIDATION_ERROR`,message:`${t} must not contain the keyword "${e}". Daraja rejects URLs containing: mpesa, safaricom, exe, exec, cme (and variants: cmd, sql, query).`})}async function Jn(e,t,n,r){let i=T(Vn,n,`C2B Register URL request`);qn(i.confirmationUrl,`confirmationUrl`),qn(i.validationUrl,`validationUrl`);let a=i.apiVersion??`v2`,o={ShortCode:String(i.shortCode),ResponseType:i.responseType,ConfirmationURL:i.confirmationUrl,ValidationURL:i.validationUrl},{data:c}=await d(`${e}/mpesa/c2b/${a}/registerurl`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:o},r));return T(Hn,c,`C2B Register URL response`)}async function Yn(e,t,n,r){let i=T(Wn,n,`C2B Simulate request`);if(!e.includes(`sandbox`))throw a({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.`});let o=Math.round(i.amount),c=i.commandId===`CustomerBuyGoodsOnline`,l=i.apiVersion??`v2`,u={ShortCode:Number(i.shortCode),CommandID:i.commandId,Amount:o,Msisdn:Number(i.msisdn)};c||(u.BillRefNumber=i.billRefNumber.trim());let{data:f}=await d(`${e}/mpesa/c2b/${l}/simulate`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:u},r));return T(Un,f,`C2B Simulate response`)}const Xn={INTERNAL_SERVER_ERROR:`500.003.1001`,INVALID_ACCESS_TOKEN:`400.003.01`,BAD_REQUEST:`400.003.02`,QUOTA_VIOLATION:`500.003.03`,SPIKE_ARREST:`500.003.02`,RESOURCE_NOT_FOUND:`404.003.01`,INVALID_AUTH_HEADER:`404.001.04`,INVALID_REQUEST_PAYLOAD:`400.002.05`},Zn={ACCEPT:`0`,INVALID_MSISDN:`C2B00011`,INVALID_ACCOUNT_NUMBER:`C2B00012`,INVALID_AMOUNT:`C2B00013`,INVALID_KYC_DETAILS:`C2B00014`,INVALID_SHORTCODE:`C2B00015`,OTHER_ERROR:`C2B00016`};function Qn(e){if(!e||typeof e!=`object`)return!1;let t=e;return typeof t.TransID==`string`&&typeof t.BusinessShortCode==`string`&&typeof t.TransAmount==`string`}function $n(e){return{ResultCode:`0`,ResultDesc:`Accepted`,...e?{ThirdPartyTransID:e}:{}}}function er(e=`C2B00016`){return{ResultCode:e,ResultDesc:`Rejected`}}function tr(){return{ResultCode:0,ResultDesc:`Success`}}function nr(e){return Number(e.TransAmount)}function rr(e){return e.TransID}function ir(e){return e.BillRefNumber}function ar(e){return[e.FirstName,e.MiddleName,e.LastName].filter(Boolean).join(` `).trim()}function or(e){return e.TransactionType===`Pay Bill`}function sr(e){return e.TransactionType===`Buy Goods`}const U=[`BG`,`WA`,`PB`,`SM`,`SB`],cr=1,lr=1e3,ur=1,dr=300;function fr(e){return typeof e!=`string`||e.trim().length===0?`merchantName is required and must be a non-empty string`:null}function pr(e){return typeof e!=`string`||e.trim().length===0?`refNo (transaction reference) is required and must be a non-empty string`:null}function mr(e){return typeof e!=`number`||!Number.isFinite(e)?`amount must be a finite number`:Math.round(e)<1?`amount must be at least 1 KES (got ${e})`:null}function hr(e){return U.includes(e)?null:`trxCode must be one of: ${U.join(`, `)} (BG=Buy Goods, WA=Withdraw Cash, PB=Paybill, SM=Send Money, SB=Send to Business)`}function gr(e){return typeof e!=`string`||e.trim().length===0?`cpi (Credit Party Identifier) is required and must be a non-empty string`:null}function _r(e){return e==null?null:typeof e!=`number`||!Number.isFinite(e)?`size must be a finite number when provided`:!Number.isInteger(e)||e<1?`size must be a positive integer (minimum 1)`:e>1e3?`size must not exceed ${lr} pixels (got ${e})`:null}function vr(e){if(typeof e!=`object`||!e)return{valid:!1,errors:{payload:`request payload must be a non-null object`}};let t=e,n={},r=fr(t.merchantName);r&&(n.merchantName=r);let i=pr(t.refNo);i&&(n.refNo=i);let a=mr(t.amount);a&&(n.amount=a);let o=hr(t.trxCode);o&&(n.trxCode=o);let s=gr(t.cpi);s&&(n.cpi=s);let c=_r(t.size);return c&&(n.size=c),Object.keys(n).length>0?{valid:!1,errors:n}:{valid:!0}}function yr(e,t){switch(e){case`404.001.04`:return new i({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: "${t}"`,statusCode:404});case`400.003.01`:return new i({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: "${t}"`,statusCode:401});case`400.002.05`:return new i({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: "${t}"`,statusCode:400});default:return new i({code:`REQUEST_FAILED`,message:`Dynamic QR request failed (${e}): ${t}`,statusCode:400})}}function br(e){return typeof e==`object`&&!!e&&`errorCode`in e&&typeof e.errorCode==`string`}function xr(e){return typeof e==`object`&&!!e&&`ResponseCode`in e&&`QRCode`in e&&typeof e.QRCode==`string`&&e.QRCode.length>0}async function Sr(e,t,n,r){let a=T(ge,n,`Dynamic QR request`);if(!t||typeof t!=`string`||t.trim().length===0)throw new i({code:`AUTH_FAILED`,message:`accessToken is required. Obtain one via the Daraja Authorization API (GET /oauth/v1/generate?grant_type=client_credentials).`});let o=a.size??300,c=Math.round(a.amount),l={MerchantName:a.merchantName.trim(),RefNo:a.refNo.trim(),Amount:c,TrxCode:a.trxCode,CPI:a.cpi.trim(),Size:String(o)},{data:u}=await d(`${e}/mpesa/qrcode/v1/generate`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:l},r));if(br(u))throw yr(u.errorCode,u.errorMessage);if(!xr(u))throw new i({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(u).slice(0,300)}`});return T(_e,u,`Dynamic QR response`)}const Cr=`TransactionReversal`,wr=`11`,W={SUCCESS:0,INSUFFICIENT_BALANCE:1,DEBIT_PARTY_INVALID_STATE:11,INITIATOR_NOT_ALLOWED:21,INITIATOR_INFORMATION_INVALID:2001,DECLINED_ACCOUNT_RULE:2006,NOT_PERMITTED:2028,SECURITY_CREDENTIAL_LOCKED:8006,ALREADY_REVERSED:`R000001`,INVALID_TRANSACTION_ID:`R000002`},Tr={INVALID_ACCESS_TOKEN:`404.001.03`,BAD_REQUEST:`400.002.02`,RESOURCE_NOT_FOUND:`404.001.01`,INTERNAL_SERVER_ERROR:`500.001.1001`,SPIKE_ARREST:`500.003.02`,QUOTA_VIOLATION:`500.003.03`};function Er(e){if(!e||typeof e!=`object`)return!1;let t=e;if(!t.Result||typeof t.Result!=`object`)return!1;let n=t.Result;return n.ResultCode!==void 0&&typeof n.ResultDesc==`string`&&typeof n.ConversationID==`string`}function Dr(e){return e.Result.ResultCode===W.SUCCESS}function Or(e){return!Dr(e)}function kr(e){return Object.values(W).includes(e)}function Ar(e){return e.Result.TransactionID??null}function jr(e){return e.Result.ConversationID}function Mr(e){return e.Result.OriginatorConversationID}function Nr(e){return e.Result.ResultCode}function Pr(e){return e.Result.ResultDesc}function G(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n)return n.find(e=>e.Key===t)?.Value}function Fr(e){let t=G(e,`Amount`);return t===void 0?void 0:Number(t)}function Ir(e){let t=G(e,`OriginalTransactionID`);return t===void 0?void 0:String(t)}function Lr(e){let t=G(e,`CreditPartyPublicName`);return t===void 0?void 0:String(t)}function Rr(e){let t=G(e,`DebitPartyPublicName`);return t===void 0?void 0:String(t)}function zr(e){let t=G(e,`DebitAccountBalance`);return t===void 0?void 0:String(t)}function Br(e){let t=G(e,`TransCompletedTime`);return t===void 0?void 0:Number(t)}function Vr(e){let t=G(e,`Charge`);return t===void 0?void 0:Number(t)}async function Hr(e,t,n,r,i,a){let o=T(fe,i,`Reversal request`),c=Math.round(o.amount),l=o.remarks??`Transaction Reversal`,u={Initiator:r,SecurityCredential:n,CommandID:Cr,TransactionID:o.transactionId,Amount:String(c),ReceiverParty:String(o.receiverParty),RecieverIdentifierType:`11`,ResultURL:o.resultUrl,QueueTimeOutURL:o.queueTimeOutUrl,Remarks:l};o.occasion!==void 0&&o.occasion!==null&&(u.Occasion=o.occasion);let{data:f}=await d(`${e}/mpesa/reversal/v1/request`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:u},a));return T(pe,f,`Reversal response`)}const Ur=r.enum([`CustomerPayBillOnline`,`CustomerBuyGoodsOnline`]),Wr=r.object({amount:r.number().finite({message:`amount must be a finite number (not NaN or Infinity)`}),phoneNumber:D,shortCode:D,passKey:D,callbackUrl:O,accountReference:D,transactionDesc:D,transactionType:Ur.optional(),partyB:r.string().optional()}),Gr=r.object({MerchantRequestID:r.string(),CheckoutRequestID:r.string(),ResponseCode:r.string(),ResponseDescription:r.string(),CustomerMessage:r.string().optional()}).passthrough(),Kr=r.object({checkoutRequestId:D,shortCode:D,passKey:D}),qr=r.object({ResponseCode:r.string(),ResponseDescription:r.string(),MerchantRequestID:r.string().optional(),CheckoutRequestID:r.string().optional(),ResultCode:r.union([r.string(),r.number()]).optional(),ResultDesc:r.string().optional()}).passthrough(),Jr=r.object({Body:r.object({stkCallback:r.object({MerchantRequestID:r.string(),CheckoutRequestID:r.string(),ResultCode:r.number(),ResultDesc:r.string(),CallbackMetadata:r.object({Item:r.array(r.object({Name:r.string(),Value:r.union([r.string(),r.number()])}))}).optional()}).passthrough()})}),K={MIN_AMOUNT:1,MAX_AMOUNT:25e4},q={SUCCESS:0,INSUFFICIENT_BALANCE:1,CANCELLED_BY_USER:1032,PHONE_UNREACHABLE:1037,INVALID_PIN:2001};function Yr(e){return Object.values(q).includes(e)}function Xr(e){return e.ResultCode===q.SUCCESS}function Zr(e,t){let n=e.Body.stkCallback;if(Xr(n))return n.CallbackMetadata.Item.find(e=>e.Name===t)?.Value}function J(e){let t=e.replace(/\D/g,``),n;if(t.startsWith(`254`)&&t.length===12)n=t;else if(t.startsWith(`0`)&&t.length===10)n=`254${t.slice(1)}`;else if(t.length===9)n=`254${t}`;else throw new i({code:`INVALID_PHONE`,message:`Cannot parse "${e}". Use 07XXXXXXXX, 2547XXXXXXXX, 2541XXXXXXXX (Airtel), or +2547XXXXXXXX.`});if(n.length!==12)throw new i({code:`INVALID_PHONE`,message:`"${e}" normalised to "${n}" — expected 12 digits.`});return n}function Qr(e,t,n){return btoa(`${e}${t}${n}`)}function Y(){let e=new Date,t=e=>e.toString().padStart(2,`0`);return[e.getFullYear(),t(e.getMonth()+1),t(e.getDate()),t(e.getHours()),t(e.getMinutes()),t(e.getSeconds())].join(``)}async function $r(e,t,n,r){let a=T(Wr,n,`STK Push request`);if(!Number.isFinite(a.amount))throw new i({code:`VALIDATION_ERROR`,message:`amount must be a finite number (got ${a.amount}).`});let o=Math.round(a.amount);if(o<K.MIN_AMOUNT)throw new i({code:`VALIDATION_ERROR`,message:`Amount must be at least KES ${K.MIN_AMOUNT} (got ${a.amount} which rounds to ${o}).`});if(o>K.MAX_AMOUNT)throw new i({code:`VALIDATION_ERROR`,message:`Amount must not exceed KES ${K.MAX_AMOUNT.toLocaleString()} per transaction as per Safaricom Daraja limits (got ${a.amount} which rounds to ${o}).`});let c=Y(),l=a.partyB??a.shortCode,u={BusinessShortCode:a.shortCode,Password:Qr(a.shortCode,a.passKey,c),Timestamp:c,TransactionType:a.transactionType??`CustomerPayBillOnline`,Amount:o,PartyA:J(a.phoneNumber),PartyB:l,PhoneNumber:J(a.phoneNumber),CallBackURL:a.callbackUrl,AccountReference:a.accountReference.slice(0,12),TransactionDesc:a.transactionDesc.slice(0,13)},{data:f}=await d(`${e}/mpesa/stkpush/v1/processrequest`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:u,retries:5,retryDelay:3e3},r));return T(Gr,f,`STK Push response`)}async function ei(e,t,n,r){let i=T(Kr,n,`STK Query request`),a=Y(),o={BusinessShortCode:i.shortCode,Password:Qr(i.shortCode,i.passKey,a),Timestamp:a,CheckoutRequestID:i.checkoutRequestId},{data:c}=await d(`${e}/mpesa/stkpushquery/v1/query`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:o},r));return T(qr,c,`STK Query response`)}const ti=`572572`,ni=`PayTaxToKRA`;async function ri(e,t,n,r,i,a){let o=T(me,i,`Tax Remittance request`),c=Math.round(o.amount),l={Initiator:r,SecurityCredential:n,CommandID:ni,SenderIdentifierType:`4`,RecieverIdentifierType:`4`,Amount:String(c),PartyA:String(o.partyA),PartyB:o.partyB??`572572`,AccountReference:o.accountReference,Remarks:o.remarks??`Tax Remittance`,QueueTimeOutURL:o.queueTimeOutUrl,ResultURL:o.resultUrl},{data:u}=await d(`${e}/mpesa/b2b/v1/remittax`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:l},a));return T(he,u,`Tax Remittance response`)}function ii(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function ai(e){return typeof e==`string`?Number(e):e}function oi(e){if(!ii(e))return!1;let t=e;if(!ii(t.Result))return!1;let n=t.Result;return n.ResultCode!==void 0&&n.ResultCode!==null&&typeof n.ConversationID==`string`&&typeof n.OriginatorConversationID==`string`}function si(e){return ai(e.Result.ResultCode)===0}function ci(e){return!si(e)}function X(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n==null)return;if(Array.isArray(n))return n.find(e=>e.Key===t)?.Value;let r=n;return r.Key===t?r.Value:void 0}function li(e){return e.Result.ResultCode}function ui(e){return e.Result.ResultDesc}function di(e){return e.Result.TransactionID}function fi(e){return e.Result.ConversationID}function pi(e){return e.Result.OriginatorConversationID}function mi(e){let t=X(e,`Amount`);if(t==null)return null;let n=typeof t==`number`?t:parseFloat(String(t));return Number.isNaN(n)?null:n}function hi(e){let t=X(e,`TransactionCompletedTime`);return t===void 0?null:String(t)}function gi(e){let t=X(e,`ReceiverPartyPublicName`);return t===void 0?null:String(t)}async function _i(e,t,n,r,i,a){let o=T(ce,i,`Transaction Status request`),c={Initiator:r,SecurityCredential:n,CommandID:o.commandId??`TransactionStatusQuery`,TransactionID:o.transactionId??``,OriginalConversationID:o.originalConversationId??``,PartyA:o.partyA,IdentifierType:o.identifierType,ResultURL:o.resultUrl,QueueTimeOutURL:o.queueTimeOutUrl,Remarks:o.remarks??`Transaction Status Query`,Occasion:o.occasion??``},{data:l}=await d(`${e}/mpesa/transactionstatus/v1/query`,s({method:`POST`,headers:{Authorization:`Bearer ${t}`},body:c},a));return T(le,l,`Transaction Status response`)}const vi={INVALID_ACCESS_TOKEN:`400.003.01`,BAD_REQUEST:`400.003.02`,INTERNAL_SERVER_ERROR:`500.003.1001`,QUOTA_VIOLATION:`500.003.03`,SPIKE_ARREST:`500.003.02`,NOT_FOUND:`404.003.01`,INVALID_AUTH_HEADER:`404.001.04`,INVALID_PAYLOAD:`400.002.05`},yi={SUCCESS:0,INVALID_INITIATOR:2001},bi=new Set(Object.values(yi));function xi(e){if(!e||typeof e!=`object`)return!1;let t=e;if(!t.Result||typeof t.Result!=`object`)return!1;let n=t.Result;return(typeof n.ResultCode==`number`||typeof n.ResultCode==`string`)&&typeof n.ConversationID==`string`&&typeof n.OriginatorConversationID==`string`}function Si(e){let t=e.Result.ResultCode;return t===0||t===`0`}function Ci(e){return!Si(e)}function wi(e){if(typeof e!=`number`&&typeof e!=`string`||typeof e==`string`&&e.trim()===``)return!1;let t=Number(e);return Number.isFinite(t)&&bi.has(t)}function Ti(e){return e.Result.TransactionID}function Ei(e){return e.Result.ConversationID}function Di(e){return e.Result.OriginatorConversationID}function Oi(e){return e.Result.ResultDesc}function ki(e){return e.Result.ResultCode}function Ai(e){let t=Z(e,`Amount`);if(t===void 0)return null;let n=Number(t);return Number.isFinite(n)?n:null}function ji(e){let t=Z(e,`ReceiptNo`);return t===void 0?null:String(t)}function Mi(e){let t=Z(e,`TransactionStatus`);return t===void 0?null:String(t)}function Ni(e){let t=Z(e,`DebitPartyName`);return t===void 0?null:String(t)}function Pi(e){let t=Z(e,`CreditPartyName`);return t===void 0?null:String(t)}function Fi(e){let t=Z(e,`DebitAccountBalance`);return t===void 0?null:String(t)}function Ii(e){let t=Z(e,`TransactionDate`);return t===void 0?null:String(t)}function Z(e,t){let n=e.Result.ResultParameters?.ResultParameter;if(n)return(Array.isArray(n)?n:[n]).find(e=>e.Key===t)?.Value}const Li={sandbox:`https://sandbox.safaricom.co.ke`,production:`https://api.safaricom.co.ke`},Ri={maxRetries:1/0,initialDelay:1e3,maxDelay:36e5,backoffMultiplier:2,maxRetryDuration:720*60*60*1e3};async function zi(e,t={}){let n={...Ri,...t},r=n.initialDelay,i=0,a=Date.now();for(;i<=n.maxRetries;){if(i++,Date.now()-a>n.maxRetryDuration)return{success:!1,attempts:i,error:Error(`Max retry duration exceeded`)};try{return{success:!0,data:await e(),attempts:i}}catch(e){let t=e instanceof Error?e:Error(String(e));if(t.message.includes(`4`))return{success:!1,attempts:i,error:t};i<=n.maxRetries&&(await new Promise(e=>setTimeout(e,r)),r=Math.min(r*n.backoffMultiplier,n.maxDelay))}}return{success:!1,attempts:i,error:Error(`Max retries exceeded`)}}const Bi={sha256:`SHA-256`,sha512:`SHA-512`};function Vi(e){let t=e.trim();if(!/^[0-9a-fA-F]+$/.test(t)||t.length%2!=0)return null;let n=new Uint8Array(t.length/2);for(let e=0;e<n.length;e++)n[e]=Number.parseInt(t.slice(e*2,e*2+2),16);return n}function Hi(e){return[...new Uint8Array(e)].map(e=>e.toString(16).padStart(2,`0`)).join(``)}function Ui(e,t){if(e.length!==t.length)return!1;let n=0;for(let r=0;r<e.length;r++)n|=e[r]^t[r];return n===0}async function Wi(e,t,n,r=`sha256`){if(!n||!t)return!1;let i=globalThis.crypto?.subtle;if(!i)return!1;let a=typeof e==`string`?new TextEncoder().encode(e):e instanceof Uint8Array?e:new Uint8Array(e),o=Vi(t);if(!o)return!1;try{let e=await i.importKey(`raw`,new TextEncoder().encode(n),{name:`HMAC`,hash:Bi[r]},!1,[`sign`]),t=Vi(Hi(await i.sign(`HMAC`,e,a)));return t?Ui(o,t):!1}catch{return!1}}const Q=[`196.201.214.200`,`196.201.214.206`,`196.201.213.114`,`196.201.214.207`,`196.201.214.208`,`196.201.213.44`,`196.201.212.127`,`196.201.212.138`,`196.201.212.129`,`196.201.212.136`,`196.201.212.74`,`196.201.212.69`];function $(e,t=Q){return t.includes(e)}function Gi(e){return Jr.safeParse(e).success?e:null}async function Ki(e){let t=[],n=e.allowedIPs??Q,r=e.skipIPCheck===!0||$(e.requestIP,n);r||t.push(`Request IP is not in the Safaricom allowlist.`);let i=!0;return e.secret&&e.signature&&e.rawBody!==void 0?(i=await Wi(e.rawBody,e.signature,e.secret,e.hmacAlgorithm),i||t.push(`Webhook HMAC signature verification failed.`)):e.requireHMAC&&(i=!1,t.push(`HMAC verification required but secret, signature, or rawBody missing.`)),{valid:r&&i,ipValid:r,hmacValid:i,errors:t}}function qi(e,t={}){if(!t.skipIPCheck&&t.requestIP&&!$(t.requestIP,t.allowedIPs))return{success:!1,eventType:null,data:null,error:`IP address ${t.requestIP} is not in the Safaricom whitelist`};let n=Gi(e);return n?{success:!0,eventType:`stk_push`,data:n}:{success:!1,eventType:null,data:null,error:`Unknown or malformed webhook payload`}}function Ji(e){let t=(e.Body?.stkCallback?.CallbackMetadata?.Item)?.find(e=>e.Name===`MpesaReceiptNumber`);return t?String(t.Value):null}function Yi(e){let t=(e.Body?.stkCallback?.CallbackMetadata?.Item)?.find(e=>e.Name===`Amount`);return t?Number(t.Value):null}function Xi(e){let t=(e.Body?.stkCallback?.CallbackMetadata?.Item)?.find(e=>e.Name===`PhoneNumber`);return t?String(t.Value):null}function Zi(e){return e.Body?.stkCallback?.ResultCode===0}var Qi=class{config;tokenManager;baseUrl;idempotencyManager;constructor(e){if(!e.consumerKey||!e.consumerSecret)throw new i({code:`INVALID_CREDENTIALS`,message:`consumerKey and consumerSecret are required.`});this.config=e,this.baseUrl=Li[e.environment],this.tokenManager=new p(e.consumerKey,e.consumerSecret,this.baseUrl),this.idempotencyManager=new y(e.idempotency)}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 i({code:`INVALID_CREDENTIALS`,message:`Provide securityCredential (pre-encrypted) OR (initiatorPassword + certificatePath/certificatePem).`});let t;if(this.config.certificatePem)t=this.config.certificatePem;else if(this.config.certificatePath)t=await e(this.config.certificatePath,`utf-8`);else throw new i({code:`INVALID_CREDENTIALS`,message:`certificatePath or certificatePem is required to encrypt the initiator password.`});return m(this.config.initiatorPassword,t)}requireInitiator(e){let t=this.config.initiatorName??``;if(!t)throw new i({code:`VALIDATION_ERROR`,message:`initiatorName is required for ${e}.`});return t}async stkPushSafe(e){try{return C(await this.stkPush(e))}catch(e){return w(e)}}async accountBalanceSafe(e){try{return C(await this.accountBalance(e))}catch(e){return w(e)}}async stkPush(e){let t=this.config.lipaNaMpesaShortCode??``,n=this.config.lipaNaMpesaPassKey??``;if(!t||!n)throw new i({code:`VALIDATION_ERROR`,message:`lipaNaMpesaShortCode and lipaNaMpesaPassKey are required for STK Push.`});let r=await this.getToken();return $r(this.baseUrl,r,{...e,shortCode:t,passKey:n},this.darajaHttp())}async stkQuery(e){let t=this.config.lipaNaMpesaShortCode??``,n=this.config.lipaNaMpesaPassKey??``;if(!t||!n)throw new i({code:`VALIDATION_ERROR`,message:`lipaNaMpesaShortCode and lipaNaMpesaPassKey are required for STK Query.`});let r=await this.getToken();return ei(this.baseUrl,r,{...e,shortCode:t,passKey:n},this.darajaHttp())}async transactionStatus(e){let t=this.requireInitiator(`Transaction Status`),[n,r]=await Promise.all([this.getToken(),this.buildSecurityCredential()]);return _i(this.baseUrl,n,r,t,e,this.darajaHttp())}async accountBalance(e){let t=this.requireInitiator(`Account Balance`),[n,r]=await Promise.all([this.getToken(),this.buildSecurityCredential()]);return ve(this.baseUrl,n,r,t,e,this.darajaHttp())}async reverseTransaction(e){let t=this.requireInitiator(`Reversal`),[n,r]=await Promise.all([this.getToken(),this.buildSecurityCredential()]);return Hr(this.baseUrl,n,r,t,e,this.darajaHttp())}async generateDynamicQR(e){let t=await this.getToken();return Sr(this.baseUrl,t,e,this.darajaHttp())}async registerC2BUrls(e){let t=await this.getToken();return Jn(this.baseUrl,t,e,this.darajaHttp())}async simulateC2B(e){let t=await this.getToken();return Yn(this.baseUrl,t,e,this.darajaHttp())}async remitTax(e){let t=this.requireInitiator(`Tax Remittance`),[n,r]=await Promise.all([this.getToken(),this.buildSecurityCredential()]);return ri(this.baseUrl,n,r,t,e,this.darajaHttp())}async b2bExpressCheckout(e){let t=await this.getToken();return Le(this.baseUrl,t,e,this.darajaHttp())}async b2bBuyGoods(e){let t=this.requireInitiator(`B2B Buy Goods`),[n,r]=await Promise.all([this.getToken(),this.buildSecurityCredential()]);return N(this.baseUrl,n,r,t,e,this.darajaHttp())}async b2bPayBill(e){let t=this.requireInitiator(`B2B Pay Bill`),[n,r]=await Promise.all([this.getToken(),this.buildSecurityCredential()]);return ft(this.baseUrl,n,r,t,e,this.darajaHttp())}async b2cPayment(e){let t=this.requireInitiator(`B2C Payment`),[n,r]=await Promise.all([this.getToken(),this.buildSecurityCredential()]);return zt(this.baseUrl,n,r,t,e,this.darajaHttp())}async b2cDisbursement(e){let t=this.requireInitiator(`B2C Disbursement`),n={...e,originatorConversationId:e.originatorConversationId??g()},[r,i]=await Promise.all([this.getToken(),this.buildSecurityCredential()]);return rn(this.baseUrl,r,i,t,n,this.darajaHttp())}async billManagerOptIn(e){let t=await this.getToken();return Fn(this.baseUrl,t,e,this.darajaHttp())}async updateOptIn(e){let t=await this.getToken();return In(this.baseUrl,t,e,this.darajaHttp())}async sendInvoice(e){let t=await this.getToken();return Ln(this.baseUrl,t,e,this.darajaHttp())}async sendBulkInvoices(e){let t=await this.getToken();return V(this.baseUrl,t,e,this.darajaHttp())}async cancelInvoice(e){let t=await this.getToken();return Rn(this.baseUrl,t,e,this.darajaHttp())}async cancelBulkInvoices(e){let t=await this.getToken();return zn(this.baseUrl,t,e,this.darajaHttp())}async reconcilePayment(e){let t=await this.getToken();return Bn(this.baseUrl,t,e,this.darajaHttp())}clearTokenCache(){this.tokenManager.clearCache()}get environment(){return this.config.environment}};const $i=r.object({Result:r.object({ResultType:r.number(),ResultCode:r.number(),ResultDesc:r.string(),OriginatorConversationID:r.string().optional(),ConversationID:r.string().optional(),TransactionID:r.string().optional()})}).passthrough(),ea=r.object({TransID:r.string(),TransAmount:r.union([r.string(),r.number()]),MSISDN:r.string(),BusinessShortCode:r.string()}).passthrough();export{ye as ACCOUNT_BALANCE_ERROR_CODES,f as AUTH_ERROR_CODES,ue as AccountBalanceRequestSchema,de as AccountBalanceResponseSchema,k as AsyncApiResponseSchema,Ae as B2BBuyGoodsRequestSchema,Me as B2BBuyGoodsResponseSchema,Pe as B2BExpressCheckoutRequestSchema,Fe as B2BExpressCheckoutResponseSchema,je as B2BPayBillRequestSchema,Ne as B2BPayBillResponseSchema,Ie as B2BResponseSchema,Ge as B2B_BUY_GOODS_ERROR_CODES,We as B2B_BUY_GOODS_RESULT_CODES,mt as B2B_PAY_BILL_ERROR_CODES,pt as B2B_PAY_BILL_RESULT_CODES,j as B2B_RESULT_CODES,Lt as B2CDisbursementRequestSchema,Rt as B2CDisbursementResponseSchema,Ft as B2CRequestSchema,It as B2CResponseSchema,$i as B2CResultWebhookSchema,L as B2C_DISBURSEMENT_RESULT_CODES,Bt as B2C_ERROR_CODES,Vt as B2C_RESULT_CODES,Dn as BillManagerBulkInvoiceRequestSchema,On as BillManagerBulkInvoiceResponseSchema,jn as BillManagerCancelBulkInvoiceRequestSchema,Mn as BillManagerCancelBulkInvoiceResponseSchema,kn as BillManagerCancelInvoiceRequestSchema,An as BillManagerCancelInvoiceResponseSchema,Tn as BillManagerInvoiceItemSchema,z as BillManagerOptInRequestSchema,Sn as BillManagerOptInResponseSchema,Nn as BillManagerReconciliationRequestSchema,Pn as BillManagerReconciliationResponseSchema,B as BillManagerSingleInvoiceRequestSchema,En as BillManagerSingleInvoiceResponseSchema,Cn as BillManagerUpdateOptInRequestSchema,wn as BillManagerUpdateOptInResponseSchema,H as C2BBaseResponseSchema,ea as C2BConfirmationWebhookSchema,Vn as C2BRegisterUrlRequestSchema,Hn as C2BRegisterUrlResponseSchema,Wn as C2BSimulateRequestSchema,Un as C2BSimulateResponseSchema,Gn as C2BValidationWebhookSchema,Xn as C2B_REGISTER_URL_ERROR_CODES,Zn as C2B_VALIDATION_RESULT_CODES,Li as DARAJA_BASE_URLS,dr as DEFAULT_QR_SIZE,oe as DarajaErrorResponseSchema,ge as DynamicQRRequestSchema,_e as DynamicQRResponseSchema,ie as EnvironmentSchema,y as IdempotencyManager,v as InMemoryIdempotencyStore,ti as KRA_SHORTCODE,E as KesAmountSchema,lr as MAX_QR_SIZE,cr as MIN_AMOUNT,ur as MIN_QR_SIZE,Qi as Mpesa,ae as MsisdnSchema,D as NonEmptyStringSchema,i as PesafyError,U as QR_TRANSACTION_CODES,Cr as REVERSAL_COMMAND_ID,Tr as REVERSAL_ERROR_CODES,wr as REVERSAL_RECEIVER_IDENTIFIER_TYPE,W as REVERSAL_RESULT_CODES,fe as ReversalRequestSchema,pe as ReversalResponseSchema,Q as SAFARICOM_IPS,K as STK_PUSH_LIMITS,q as STK_RESULT_CODES,Wr as StkPushRequestSchema,Gr as StkPushResponseSchema,Jr as StkPushWebhookSchema,Kr as StkQueryRequestSchema,qr as StkQueryResponseSchema,ni as TAX_COMMAND_ID,vi as TRANSACTION_STATUS_ERROR_CODES,yi as TRANSACTION_STATUS_RESULT_CODES,me as TaxRemittanceRequestSchema,he as TaxRemittanceResponseSchema,p as TokenManager,ce as TransactionStatusRequestSchema,le as TransactionStatusResponseSchema,Ur as TransactionTypeSchema,O as UrlSchema,$n as acceptC2BValidation,tr as acknowledgeC2BConfirmation,Fn as billManagerOptIn,zn as cancelBulkInvoices,Rn as cancelInvoice,a as createError,m as encryptSecurityCredential,w as err,Yi as extractAmount,Xi as extractPhoneNumber,Ji as extractTransactionId,J as formatPhoneNumber,J as formatSafaricomPhone,Sr as generateDynamicQR,h as generateIdempotencyKey,g as generateOriginatorConversationId,_ as generateRequestRefId,we as getAccountBalanceCompletedTime,Se as getAccountBalanceConversationId,Ce as getAccountBalanceOriginatorConversationId,A as getAccountBalanceParam,Te as getAccountBalanceRawBalance,Ee as getAccountBalanceReferenceItem,xe as getAccountBalanceTransactionId,Ve as getB2BAmount,nt as getB2BBuyGoodsAmount,ut as getB2BBuyGoodsBillReferenceNumber,rt as getB2BBuyGoodsCompletedTime,Qe as getB2BBuyGoodsConversationId,ot as getB2BBuyGoodsCurrency,ct as getB2BBuyGoodsDebitAccountBalance,st as getB2BBuyGoodsDebitPartyAffectedBalance,at as getB2BBuyGoodsDebitPartyCharges,lt as getB2BBuyGoodsInitiatorBalance,$e as getB2BBuyGoodsOriginatorConversationId,dt as getB2BBuyGoodsQueueTimeoutUrl,it as getB2BBuyGoodsReceiverName,tt as getB2BBuyGoodsResultCode,et as getB2BBuyGoodsResultDesc,P as getB2BBuyGoodsResultParam,Ze as getB2BBuyGoodsTransactionId,Ue as getB2BConversationId,Tt as getB2BPayBillAmount,Nt as getB2BPayBillBillReferenceNumber,Et as getB2BPayBillCompletedTime,xt as getB2BPayBillConversationId,kt as getB2BPayBillCurrency,jt as getB2BPayBillDebitAccountBalance,At as getB2BPayBillDebitPartyAffectedBalance,Ot as getB2BPayBillDebitPartyCharges,Mt as getB2BPayBillInitiatorBalance,St as getB2BPayBillOriginatorConversationId,Dt as getB2BPayBillReceiverName,wt as getB2BPayBillResultCode,Ct as getB2BPayBillResultDesc,F as getB2BPayBillResultParam,bt as getB2BPayBillTransactionId,Be as getB2BRequestId,He as getB2BTransactionId,Xt as getB2CAmount,qt as getB2CConversationId,Zt as getB2CCurrency,en as getB2CDebitAccountBalance,tn as getB2CDebitPartyCharges,mn as getB2CDisbursementAmount,_n as getB2CDisbursementCompletedTime,un as getB2CDisbursementConversationId,dn as getB2CDisbursementOriginatorConversationId,hn as getB2CDisbursementReceiptNumber,gn as getB2CDisbursementReceiverName,pn as getB2CDisbursementResultCode,fn as getB2CDisbursementResultDesc,R as getB2CDisbursementResultParam,ln as getB2CDisbursementTransactionId,vn as getB2CDisbursementUtilityBalance,yn as getB2CDisbursementWorkingBalance,Jt as getB2COriginatorConversationId,Qt as getB2CReceiverPublicName,Yt as getB2CResultDesc,I as getB2CResultParam,$t as getB2CTransactionCompletedTime,Kt as getB2CTransactionId,ir as getC2BAccountRef,nr as getC2BAmount,ar as getC2BCustomerName,rr as getC2BTransactionId,Zr as getCallbackValue,Fr as getReversalAmount,Vr as getReversalCharge,Br as getReversalCompletedTime,jr as getReversalConversationId,Lr as getReversalCreditPartyPublicName,zr as getReversalDebitAccountBalance,Rr as getReversalDebitPartyPublicName,Ir as getReversalOriginalTransactionId,Mr as getReversalOriginatorConversationId,Nr as getReversalResultCode,Pr as getReversalResultDesc,G as getReversalResultParam,Ar as getReversalTransactionId,mi as getTaxAmount,hi as getTaxCompletedTime,fi as getTaxConversationId,pi as getTaxOriginatorConversationId,gi as getTaxReceiverName,li as getTaxResultCode,ui as getTaxResultDesc,X as getTaxResultParam,di as getTaxTransactionId,Y as getTimestamp,Ai as getTransactionStatusAmount,Ei as getTransactionStatusConversationId,Pi as getTransactionStatusCreditPartyName,Fi as getTransactionStatusDebitAccountBalance,Ni as getTransactionStatusDebitPartyName,Di as getTransactionStatusOriginatorConversationId,ji as getTransactionStatusReceiptNo,ki as getTransactionStatusResultCode,Oi as getTransactionStatusResultDesc,Z as getTransactionStatusResultParam,Mi as getTransactionStatusStatus,Ii as getTransactionStatusTransactionDate,Ti as getTransactionStatusTransactionId,qi as handleWebhook,d as httpRequest,N as initiateB2BBuyGoods,Le as initiateB2BExpressCheckout,ft as initiateB2BPayBill,rn as initiateB2CDisbursement,zt as initiateB2CPayment,De as isAccountBalanceSuccess,Ye as isB2BBuyGoodsFailure,qe as isB2BBuyGoodsResult,Je as isB2BBuyGoodsSuccess,Re as isB2BCheckoutCallback,ze as isB2BCheckoutCancelled,M as isB2BCheckoutSuccess,vt as isB2BPayBillFailure,gt as isB2BPayBillResult,_t as isB2BPayBillSuccess,sn as isB2CDisbursementFailure,bn as isB2CDisbursementRecipientRegistered,an as isB2CDisbursementResult,on as isB2CDisbursementSuccess,Wt as isB2CFailure,Ht as isB2CResult,Ut as isB2CSuccess,sr as isBuyGoodsPayment,Qn as isC2BPayload,Xe as isKnownB2BBuyGoodsResultCode,yt as isKnownB2BPayBillResultCode,cn as isKnownB2CDisbursementResultCode,Gt as isKnownB2CResultCode,kr as isKnownReversalResultCode,Yr as isKnownStkResultCode,wi as isKnownTransactionStatusResultCode,or as isPaybillPayment,o as isPesafyError,Or as isReversalFailure,Er as isReversalResult,Dr as isReversalSuccess,Xr as isStkCallbackSuccess,Zi as isSuccessfulCallback,ci as isTaxRemittanceFailure,oi as isTaxRemittanceResult,si as isTaxRemittanceSuccess,Ci as isTransactionStatusFailure,xi as isTransactionStatusResult,Si as isTransactionStatusSuccess,C as ok,be as parseAccountBalance,Gi as parseStkPushWebhook,ve as queryAccountBalance,_i as queryTransactionStatus,Bn as reconcilePayment,Jn as registerC2BUrls,er as rejectC2BValidation,ri as remitTax,Hr as requestReversal,zi as retryWithBackoff,V as sendBulkInvoices,Ln as sendSingleInvoice,Yn as simulateC2B,b as toKesAmount,x as toMsisdn,ne as toNonEmpty,S as toPaybill,te as toShortCode,ee as toTill,In as updateOptIn,mr as validateAmount,gr as validateCpi,vr as validateDynamicQRRequest,fr as validateMerchantName,pr as validateRefNo,_r as validateSize,hr as validateTrxCode,Ki as verifyWebhook,Wi as verifyWebhookHMAC,$ as verifyWebhookIP};
+import { readFile } from "node:fs/promises";
+import { constants, publicEncrypt } from "node:crypto";
+import { z } from "zod";
+
+//#region src/utils/errors/index.ts
+var PesafyError = class PesafyError extends Error {
+	code;
+	statusCode;
+	response;
+	requestId;
+	cause;
+	retryable;
+	constructor(options) {
+		super(options.message);
+		Object.defineProperty(this, "name", { value: "PesafyError" });
+		this.code = options.code;
+		this.statusCode = options.statusCode;
+		this.response = options.response;
+		this.requestId = options.requestId;
+		this.cause = options.cause;
+		this.retryable = options.retryable ?? (options.code === "NETWORK_ERROR" || options.code === "TIMEOUT" || options.code === "RATE_LIMITED" || options.code === "REQUEST_FAILED");
+		if (Error.captureStackTrace) Error.captureStackTrace(this, PesafyError);
+	}
+	/** Returns true if this is a validation error (user bug — do not retry) */
+	get isValidation() {
+		return this.code === "VALIDATION_ERROR";
+	}
+	/** Returns true if this is an auth error */
+	get isAuth() {
+		return this.code === "AUTH_FAILED" || this.code === "INVALID_CREDENTIALS";
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			statusCode: this.statusCode,
+			requestId: this.requestId,
+			retryable: this.retryable
+		};
+	}
+};
+/** Convenience factory */
+function createError(options) {
+	return new PesafyError(options);
+}
+/** Type guard */
+function isPesafyError(err) {
+	return err instanceof PesafyError;
+}
+
+//#endregion
+//#region src/utils/http/index.ts
+/** Merge explicit Daraja HTTP options into an httpRequest options object. */
+function withDarajaHttp(options, http) {
+	if (!http?.idempotency) return options;
+	return {
+		...options,
+		idempotency: http.idempotency
+	};
+}
+const RETRYABLE_STATUSES = new Set([
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+function withJitter(base) {
+	const spread = base * .25;
+	return base + (Math.random() * spread * 2 - spread);
+}
+/** Origin + path only (no query) for safe retry logs. */
+function logSafeUrl(url) {
+	try {
+		const u = new URL(url);
+		return `${u.origin}${u.pathname}`;
+	} catch {
+		return url.split("?")[0] ?? url;
+	}
+}
+/**
+* Sends an HTTP request to Daraja and returns parsed JSON.
+* Automatically retries transient failures with exponential back-off.
+*
+* @throws {PesafyError} on non-retryable errors or exhausted retries.
+*/
+async function httpRequest(url, options) {
+	const maxRetries = options.retries ?? 4;
+	const baseDelay = options.retryDelay ?? 2e3;
+	const timeout = options.timeout ?? 3e4;
+	const headers = {
+		"Content-Type": "application/json",
+		Accept: "application/json",
+		...options.headers
+	};
+	const manager = options.idempotency;
+	let idempotencyKey = options.idempotencyKey;
+	if (options.method === "POST" && manager?.enabled) {
+		idempotencyKey = manager.reserve(idempotencyKey);
+		const headerName = manager.headerName;
+		headers[headerName] = idempotencyKey;
+	} else if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+	const init = {
+		method: options.method,
+		headers,
+		...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {}
+	};
+	let lastError = null;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		if (attempt > 0) {
+			const delay = withJitter(baseDelay * Math.pow(2, attempt - 1));
+			console.warn(`[pesafy] Retry ${attempt}/${maxRetries} → ${options.method} ${logSafeUrl(url)} in ${Math.round(delay)} ms`);
+			await sleep(delay);
+		}
+		const controller = new AbortController();
+		const tid = setTimeout(() => controller.abort(), timeout);
+		let response;
+		try {
+			response = await fetch(url, {
+				...init,
+				signal: controller.signal
+			});
+		} catch (err) {
+			clearTimeout(tid);
+			if (err instanceof Error && err.name === "AbortError") lastError = new PesafyError({
+				code: "TIMEOUT",
+				message: `Request to ${url} timed out after ${timeout} ms`,
+				cause: err,
+				retryable: true
+			});
+			else lastError = new PesafyError({
+				code: "NETWORK_ERROR",
+				message: `Network error: ${err instanceof Error ? err.message : String(err)}`,
+				cause: err,
+				retryable: true
+			});
+			if (attempt < maxRetries) continue;
+			if (idempotencyKey && manager?.enabled) manager.release(idempotencyKey);
+			throw lastError;
+		} finally {
+			clearTimeout(tid);
+		}
+		let rawText = "";
+		let data = null;
+		const ct = response.headers.get("content-type") ?? "";
+		try {
+			rawText = await response.text();
+			if (rawText) data = ct.includes("application/json") ? JSON.parse(rawText) : rawText;
+		} catch {
+			data = rawText || null;
+		}
+		const responseHeaders = {};
+		response.headers.forEach((v, k) => {
+			responseHeaders[k] = v;
+		});
+		if (response.ok) {
+			if (idempotencyKey && manager?.enabled) manager.complete(idempotencyKey);
+			return {
+				data,
+				status: response.status,
+				headers: responseHeaders
+			};
+		}
+		const isTransient = RETRYABLE_STATUSES.has(response.status);
+		const daraja = typeof data === "object" && data !== null ? data : {};
+		const message = daraja["errorMessage"] ?? daraja["ResponseDescription"] ?? daraja["resultDesc"] ?? rawText ?? `HTTP ${response.status}`;
+		lastError = new PesafyError({
+			code: isTransient ? "REQUEST_FAILED" : "API_ERROR",
+			message,
+			statusCode: response.status,
+			response: data,
+			retryable: isTransient,
+			...typeof daraja["requestId"] === "string" ? { requestId: daraja["requestId"] } : {}
+		});
+		if (isTransient && attempt < maxRetries) continue;
+		if (idempotencyKey && manager?.enabled) manager.release(idempotencyKey);
+		throw lastError;
+	}
+	if (idempotencyKey && manager?.enabled) manager.release(idempotencyKey);
+	throw lastError;
+}
+
+//#endregion
+//#region src/core/auth/types.ts
+/**
+* Daraja Authorization API error codes
+* Documented at: https://developer.safaricom.co.ke/APIs/Authorization
+*
+* These are returned in the `errorCode` field of a 400 error response body
+* when the OAuth token request is malformed.
+*/
+const AUTH_ERROR_CODES = {
+	INVALID_AUTH_TYPE: "400.008.01",
+	INVALID_GRANT_TYPE: "400.008.02"
+};
+
+//#endregion
+//#region src/core/auth/token-manager.ts
+/** Refresh the token this many seconds before it actually expires */
+const TOKEN_BUFFER_SECONDS = 60;
+var TokenManager = class {
+	consumerKey;
+	consumerSecret;
+	baseUrl;
+	cachedToken = null;
+	tokenExpiresAt = 0;
+	constructor(consumerKey, consumerSecret, baseUrl) {
+		this.consumerKey = consumerKey;
+		this.consumerSecret = consumerSecret;
+		this.baseUrl = baseUrl;
+	}
+	getBasicAuthHeader() {
+		const credentials = `${this.consumerKey}:${this.consumerSecret}`;
+		return `Basic ${Buffer.from(credentials, "utf-8").toString("base64")}`;
+	}
+	/**
+	* Maps Daraja-specific auth error codes (400.008.01 / 400.008.02) to
+	* descriptive PesafyError messages so callers get actionable feedback.
+	*
+	* Always throws — the `never` return type signals this to TypeScript.
+	*/
+	mapAuthError(error) {
+		if (error instanceof PesafyError) {
+			if (error.code === "AUTH_FAILED") throw error;
+			const raw = error.response;
+			if (raw && typeof raw === "object") {
+				const errorCode = raw["errorCode"] ?? raw["error_code"];
+				if (errorCode === AUTH_ERROR_CODES.INVALID_AUTH_TYPE) throw new PesafyError({
+					code: "AUTH_FAILED",
+					message: "Invalid authentication type (400.008.01). Use Basic authentication: Authorization: Basic <Base64(consumerKey:consumerSecret)>.",
+					...error.statusCode !== void 0 && { statusCode: error.statusCode },
+					response: error.response
+				});
+				if (errorCode === AUTH_ERROR_CODES.INVALID_GRANT_TYPE) throw new PesafyError({
+					code: "AUTH_FAILED",
+					message: "Invalid grant type (400.008.02). Set grant_type=client_credentials in the request query parameters.",
+					...error.statusCode !== void 0 && { statusCode: error.statusCode },
+					response: error.response
+				});
+			}
+			throw error;
+		}
+		throw error;
+	}
+	/**
+	* Returns a valid access token, fetching a new one when the cached token
+	* is absent or within TOKEN_BUFFER_SECONDS of expiry.
+	*
+	* Daraja endpoint: GET /oauth/v1/generate?grant_type=client_credentials
+	* Auth:            Basic Base64(consumerKey:consumerSecret)
+	* Token lifetime:  3599 seconds (Daraja docs)
+	*/
+	async getAccessToken() {
+		const now = Date.now() / 1e3;
+		if (this.cachedToken && this.tokenExpiresAt > now + TOKEN_BUFFER_SECONDS) return this.cachedToken;
+		const url = `${this.baseUrl}/oauth/v1/generate?grant_type=client_credentials`;
+		try {
+			const response = await httpRequest(url, {
+				method: "GET",
+				headers: { Authorization: this.getBasicAuthHeader() }
+			});
+			const { access_token, expires_in } = response.data;
+			if (!access_token) throw new PesafyError({
+				code: "AUTH_FAILED",
+				message: "Daraja did not return an access token. Verify your consumer key and consumer secret.",
+				response: response.data
+			});
+			this.cachedToken = access_token;
+			this.tokenExpiresAt = now + (expires_in ?? 3600);
+			return this.cachedToken;
+		} catch (error) {
+			return this.mapAuthError(error);
+		}
+	}
+	/** Force token refresh on the next call (e.g. after a 401 response) */
+	clearCache() {
+		this.cachedToken = null;
+		this.tokenExpiresAt = 0;
+	}
+};
+
+//#endregion
+//#region src/core/encryption/security-credentials.ts
+function encryptSecurityCredential(initiatorPassword, certificatePem) {
+	try {
+		const passwordBuffer = Buffer.from(initiatorPassword, "utf-8");
+		return publicEncrypt({
+			key: certificatePem,
+			padding: constants.RSA_PKCS1_PADDING
+		}, passwordBuffer).toString("base64");
+	} catch (error) {
+		throw new PesafyError({
+			code: "ENCRYPTION_FAILED",
+			message: "Failed to encrypt security credential. Ensure the certificate PEM is valid and matches the environment (sandbox/production).",
+			cause: error
+		});
+	}
+}
+
+//#endregion
+//#region src/core/idempotency/generate-key.ts
+/**
+* Generate idempotency keys for Daraja mutating requests.
+*/
+/** UUID v4 idempotency key, optionally prefixed for debugging. */
+function generateIdempotencyKey(prefix) {
+	const id = crypto.randomUUID();
+	return prefix ? `${prefix}-${id}` : id;
+}
+/** Daraja OriginatorConversationID — unique per async API request. */
+function generateOriginatorConversationId() {
+	return generateIdempotencyKey("pesafy");
+}
+/** B2B Express RequestRefID — unique per checkout request. */
+function generateRequestRefId() {
+	return crypto.randomUUID();
+}
+
+//#endregion
+//#region src/core/idempotency/store.ts
+var InMemoryIdempotencyStore = class {
+	entries = /* @__PURE__ */ new Map();
+	get(key) {
+		return this.entries.get(key);
+	}
+	set(key, entry) {
+		this.entries.set(key, entry);
+	}
+	delete(key) {
+		this.entries.delete(key);
+	}
+	/** Remove entries older than ttlMs. */
+	prune(ttlMs) {
+		const cutoff = Date.now() - ttlMs;
+		for (const [key, entry] of this.entries) if (entry.createdAt < cutoff) this.entries.delete(key);
+	}
+};
+
+//#endregion
+//#region src/core/idempotency/manager.ts
+const DEFAULT_TTL_MS = 1440 * 60 * 1e3;
+var IdempotencyManager = class {
+	enabled;
+	headerName;
+	ttlMs;
+	store;
+	generateKey;
+	constructor(config = {}) {
+		this.enabled = config.enabled !== false;
+		this.headerName = config.headerName ?? "Idempotency-Key";
+		this.ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+		this.store = config.store ?? new InMemoryIdempotencyStore();
+		this.generateKey = config.generateKey ?? generateIdempotencyKey;
+	}
+	/**
+	* Reserve an idempotency key before the HTTP call.
+	* @throws PesafyError with IDEMPOTENCY_ERROR if duplicate in-flight/completed within TTL.
+	*/
+	reserve(key) {
+		if (!this.enabled) return key ?? this.generateKey();
+		this.pruneExpired();
+		const resolved = key ?? this.generateKey();
+		const existing = this.store.get(resolved);
+		if (existing) {
+			if (Date.now() - existing.createdAt < this.ttlMs) throw new PesafyError({
+				code: "IDEMPOTENCY_ERROR",
+				message: `Duplicate request detected for idempotency key "${resolved}".`
+			});
+			this.store.delete(resolved);
+		}
+		this.store.set(resolved, {
+			key: resolved,
+			createdAt: Date.now()
+		});
+		return resolved;
+	}
+	/** Mark key as successfully completed. */
+	complete(key) {
+		if (!this.enabled) return;
+		const entry = this.store.get(key);
+		if (entry) this.store.set(key, {
+			...entry,
+			completedAt: Date.now()
+		});
+	}
+	/** Release reservation on failure so callers can retry with same key. */
+	release(key) {
+		if (!this.enabled) return;
+		this.store.delete(key);
+	}
+	pruneExpired() {
+		if (this.store instanceof InMemoryIdempotencyStore) this.store.prune(this.ttlMs);
+	}
+};
+
+//#endregion
+//#region src/types/branded.ts
+/**
+* Creates a validated KesAmount.
+* @throws {TypeError} if amount is not a whole number ≥ 1
+*/
+function toKesAmount(value) {
+	const rounded = Math.round(value);
+	if (!Number.isFinite(rounded) || rounded < 1) throw new TypeError(`KesAmount must be a whole number ≥ 1, got ${value}`);
+	return rounded;
+}
+/**
+* Creates a validated MsisdnKE from any common Kenyan phone format.
+*/
+function toMsisdn(phone) {
+	const digits = phone.replace(/\D/g, "");
+	let normalised;
+	if (digits.startsWith("254") && digits.length === 12) normalised = digits;
+	else if (digits.startsWith("0") && digits.length === 10) normalised = `254${digits.slice(1)}`;
+	else if (digits.length === 9) normalised = `254${digits}`;
+	else throw new TypeError(`Cannot normalise "${phone}" to 254XXXXXXXXX. Use 07XX…, 2547XX…, or +2547XX….`);
+	if (normalised.length !== 12) throw new TypeError(`Phone "${phone}" normalised to "${normalised}" — expected 12 digits.`);
+	return normalised;
+}
+function toPaybill(code) {
+	return String(code);
+}
+function toTill(code) {
+	return String(code);
+}
+function toShortCode(code) {
+	return String(code);
+}
+function ok(data) {
+	return {
+		ok: true,
+		data
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+function toNonEmpty(s) {
+	if (!s.trim()) throw new TypeError("String must not be empty");
+	return s;
+}
+
+//#endregion
+//#region src/core/validation/zod-error.ts
+/** Map Zod validation failures to PesafyError. */
+function zodToPesafyError(error, label = "Request") {
+	return new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `${label} validation failed: ${error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+		cause: error
+	});
+}
+/** Parse with Zod; throw PesafyError on failure. */
+function parseWithSchema(schema, data, label) {
+	const result = schema.safeParse(data);
+	if (!result.success) throw zodToPesafyError(result.error, label);
+	return result.data;
+}
+
+//#endregion
+//#region src/schemas/common.ts
+const EnvironmentSchema = z.enum(["sandbox", "production"]);
+const MsisdnSchema = z.string().min(10).regex(/^254\d{9}$/, "Must be Safaricom format 2547XXXXXXXX");
+const KesAmountSchema = z.number().finite().positive().refine((n) => Math.round(n) >= 1, { message: "amount must round to at least 1 KES" });
+const NonEmptyStringSchema = z.string().trim().min(1);
+const UrlSchema = z.string().url();
+const DarajaErrorResponseSchema = z.object({
+	errorMessage: z.string().optional(),
+	ResponseDescription: z.string().optional(),
+	resultDesc: z.string().optional(),
+	requestId: z.string().optional()
+}).passthrough();
+
+//#endregion
+//#region src/schemas/async-apis.ts
+const IdentifierTypeSchema = z.enum([
+	"1",
+	"2",
+	"4"
+]);
+const AsyncApiResponseSchema = z.object({
+	ConversationID: z.string().optional(),
+	OriginatorConversationID: z.string().optional(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+const TransactionStatusRequestSchema = z.object({
+	transactionId: z.string().optional(),
+	originalConversationId: z.string().optional(),
+	partyA: NonEmptyStringSchema,
+	identifierType: IdentifierTypeSchema,
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	commandId: z.literal("TransactionStatusQuery").optional(),
+	remarks: z.string().optional(),
+	occasion: z.string().optional()
+}).superRefine((data, ctx) => {
+	if (!data.transactionId?.trim() && !data.originalConversationId?.trim()) ctx.addIssue({
+		code: "custom",
+		message: "Either transactionId (M-Pesa Receipt Number) or originalConversationId is required",
+		path: ["transactionId"]
+	});
+});
+const TransactionStatusResponseSchema = AsyncApiResponseSchema;
+const AccountBalanceRequestSchema = z.object({
+	partyA: NonEmptyStringSchema,
+	identifierType: IdentifierTypeSchema,
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	remarks: z.string().optional()
+});
+const AccountBalanceResponseSchema = AsyncApiResponseSchema;
+const ReversalRequestSchema = z.object({
+	transactionId: NonEmptyStringSchema,
+	receiverParty: NonEmptyStringSchema,
+	receiverIdentifierType: z.literal("11").optional(),
+	amount: KesAmountSchema,
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	remarks: z.string().optional(),
+	occasion: z.string().optional()
+}).superRefine((data, ctx) => {
+	if (data.receiverIdentifierType !== void 0 && data.receiverIdentifierType !== "11") ctx.addIssue({
+		code: "custom",
+		message: "receiverIdentifierType must be \"11\" for the Reversals API",
+		path: ["receiverIdentifierType"]
+	});
+	const remarks = data.remarks ?? "Transaction Reversal";
+	if (remarks.length < 2 || remarks.length > 100) ctx.addIssue({
+		code: "custom",
+		message: "remarks must be between 2 and 100 characters",
+		path: ["remarks"]
+	});
+});
+const ReversalResponseSchema = AsyncApiResponseSchema;
+const TaxRemittanceRequestSchema = z.object({
+	amount: KesAmountSchema,
+	partyA: NonEmptyStringSchema,
+	partyB: z.string().optional(),
+	accountReference: NonEmptyStringSchema,
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	remarks: z.string().optional()
+});
+const TaxRemittanceResponseSchema = AsyncApiResponseSchema;
+const DynamicQRRequestSchema = z.object({
+	merchantName: NonEmptyStringSchema,
+	refNo: NonEmptyStringSchema,
+	amount: KesAmountSchema,
+	trxCode: z.enum([
+		"BG",
+		"WA",
+		"PB",
+		"SM",
+		"SB"
+	]),
+	cpi: NonEmptyStringSchema,
+	size: z.number().int().min(1).max(1e3).optional()
+});
+const DynamicQRResponseSchema = z.object({
+	ResponseCode: z.string(),
+	RequestID: z.string().optional(),
+	ResponseDescription: z.string(),
+	QRCode: z.string().optional()
+}).passthrough();
+
+//#endregion
+//#region src/mpesa/account-balance/query.ts
+/**
+* Account Balance Query — checks the balance of an M-PESA shortcode.
+*
+* API: POST /mpesa/accountbalance/v1/query
+*
+* This is ASYNCHRONOUS. The sync response only confirms receipt.
+* Balance data arrives via POST to your ResultURL.
+*
+* Required org portal role: "Balance Query ORG API" (Account Balance ORG API initiator)
+*
+* Ref: https://sandbox.safaricom.co.ke/mpesa/accountbalance/v1/query
+*/
+async function queryAccountBalance(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(AccountBalanceRequestSchema, request, "Account Balance request");
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: "AccountBalance",
+		PartyA: String(validated.partyA.trim()),
+		IdentifierType: validated.identifierType,
+		ResultURL: validated.resultUrl,
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		Remarks: validated.remarks ?? "Account Balance Query"
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/accountbalance/v1/query`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(AccountBalanceResponseSchema, data, "Account Balance response");
+}
+
+//#endregion
+//#region src/mpesa/account-balance/types.ts
+/**
+* Account Balance Query types
+*
+* API: POST /mpesa/accountbalance/v1/query
+*
+* Queries the current balance of an M-PESA shortcode.
+* This is ASYNCHRONOUS — the sync response is only acknowledgement.
+* Balance data is POSTed to your ResultURL callback.
+*
+* Required org portal role: "Balance Query ORG API" (Account Balance ORG API initiator)
+*
+* Ref: Account Balance — Daraja Developer Portal
+*/
+/**
+* Documented Account Balance API error/result codes.
+* These appear in the async callback ResultCode field.
+*
+* Ref: Account Balance — Error Codes section
+*/
+const ACCOUNT_BALANCE_ERROR_CODES = {
+	DUPLICATE_DETECTED: 15,
+	INTERNAL_FAILURE: 17,
+	INITIATOR_CREDENTIAL_CHECK_FAILURE: 18,
+	MESSAGE_SEQUENCING_FAILURE: 19,
+	UNRESOLVED_INITIATOR: 20,
+	INITIATOR_TO_PRIMARY_PARTY_PERMISSION_FAILURE: 21,
+	INITIATOR_TO_RECEIVER_PARTY_PERMISSION_FAILURE: 22,
+	MISSING_MANDATORY_FIELDS: 24,
+	SYSTEM_OVERLOAD: 100000001,
+	THROTTLING_ERROR: 100000002,
+	INTERNAL_SERVER_ERROR: 100000004,
+	INVALID_INPUT_VALUE: 100000005,
+	SERVICE_ABNORMAL: 100000007,
+	API_STATUS_ABNORMAL: 100000009,
+	INSUFFICIENT_PERMISSIONS: 100000010,
+	REQUEST_RATE_EXCEEDED: 100000011
+};
+/**
+* Parses the raw Daraja AccountBalance string into structured account objects.
+*
+* Daraja returns each account as 3 consecutive pipe-separated fields:
+*   AccountName | Currency | Amount
+* Multiple accounts are concatenated, with additional balance sub-fields interleaved.
+*
+* The parser extracts triplets where the first element is a non-numeric account name.
+*
+* Example input:
+*   "Working Account|KES|700000.00|KES|0.00|KES|0.00|Utility Account|KES|228037.00|"
+*
+* Example output:
+*   [
+*     { name: "Working Account", currency: "KES", amount: "700000.00" },
+*     { name: "Utility Account", currency: "KES", amount: "228037.00" },
+*   ]
+*/
+function parseAccountBalance(raw) {
+	if (!raw.trim()) return [];
+	const parts = raw.split("|");
+	const accounts = [];
+	for (let i = 0; i + 2 < parts.length; i++) {
+		const candidate = parts[i]?.trim();
+		const currency = parts[i + 1]?.trim();
+		const amount = parts[i + 2]?.trim();
+		if (candidate && currency && amount !== void 0 && isNaN(Number(candidate)) && candidate.length > 0) accounts.push({
+			name: candidate,
+			currency,
+			amount
+		});
+	}
+	return accounts;
+}
+/**
+* Extracts a result parameter value from an AccountBalanceResult by key.
+* Handles both array and single-object forms of ResultParameter (Daraja inconsistency).
+*
+* Documented keys: "AccountBalance", "BOCompletedTime"
+*/
+function getAccountBalanceParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return (Array.isArray(params) ? params : [params]).find((p) => p.Key === key)?.Value;
+}
+/**
+* Returns the M-PESA TransactionID from the result.
+*/
+function getAccountBalanceTransactionId(result) {
+	return result.Result.TransactionID;
+}
+/**
+* Returns the ConversationID from the result.
+*/
+function getAccountBalanceConversationId(result) {
+	return result.Result.ConversationID;
+}
+/**
+* Returns the OriginatorConversationID from the result.
+* This correlates the callback to the original request.
+*/
+function getAccountBalanceOriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+/**
+* Returns the BOCompletedTime from the result parameters, or null if not present.
+* Format: YYYYMMDDHHmmss (e.g. "20200109125710")
+*/
+function getAccountBalanceCompletedTime(result) {
+	const value = getAccountBalanceParam(result, "BOCompletedTime");
+	if (value === void 0 || value === null) return null;
+	return String(value);
+}
+/**
+* Returns the raw AccountBalance pipe-delimited string from the result, or null if absent.
+* Use parseAccountBalance() to parse this into structured account objects.
+*/
+function getAccountBalanceRawBalance(result) {
+	const value = getAccountBalanceParam(result, "AccountBalance");
+	if (value === void 0 || value === null) return null;
+	return String(value);
+}
+/**
+* Returns the ReferenceItem from the async callback, or null if not present.
+* Key is typically "QueueTimeoutURL" as documented by Daraja.
+*/
+function getAccountBalanceReferenceItem(result) {
+	const refData = result.Result.ReferenceData;
+	if (!refData) return null;
+	const item = refData.ReferenceItem;
+	if (!item) return null;
+	return Array.isArray(item) ? item[0] ?? null : item;
+}
+/**
+* Returns true if the Account Balance result indicates success (ResultCode 0).
+* Handles both numeric 0 and string "0" (Daraja inconsistency).
+*/
+function isAccountBalanceSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+
+//#endregion
+//#region src/schemas/b2b.ts
+const B2BAsyncResponseSchema = z.object({
+	ConversationID: z.string(),
+	OriginatorConversationID: z.string(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+const B2BPaymentBaseSchema = z.object({
+	amount: KesAmountSchema,
+	partyA: NonEmptyStringSchema,
+	partyB: NonEmptyStringSchema,
+	accountReference: NonEmptyStringSchema,
+	requester: z.string().optional(),
+	remarks: z.string().optional(),
+	resultUrl: UrlSchema,
+	queueTimeOutUrl: UrlSchema,
+	occasion: z.string().optional()
+});
+const B2BBuyGoodsRequestSchema = B2BPaymentBaseSchema.extend({ commandId: z.literal("BusinessBuyGoods") });
+const B2BPayBillRequestSchema = B2BPaymentBaseSchema.extend({ commandId: z.literal("BusinessPayBill") });
+const B2BBuyGoodsResponseSchema = B2BAsyncResponseSchema;
+const B2BPayBillResponseSchema = B2BAsyncResponseSchema;
+const B2BExpressCheckoutRequestSchema = z.object({
+	primaryShortCode: NonEmptyStringSchema,
+	receiverShortCode: NonEmptyStringSchema,
+	amount: KesAmountSchema,
+	paymentRef: NonEmptyStringSchema,
+	callbackUrl: UrlSchema,
+	partnerName: NonEmptyStringSchema,
+	requestRefId: NonEmptyStringSchema.optional()
+});
+const B2BExpressCheckoutResponseSchema = z.object({
+	code: z.string(),
+	status: z.string()
+}).passthrough();
+const B2BResponseSchema = z.object({
+	ConversationID: z.string().optional(),
+	OriginatorConversationID: z.string().optional(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+
+//#endregion
+//#region src/mpesa/b2b-express-checkout/initiate.ts
+/**
+* src/mpesa/b2b-express-checkout/initiate.ts
+*
+* B2B Express Checkout USSD Push to Till implementation.
+*/
+async function initiateB2BExpressCheckout(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(B2BExpressCheckoutRequestSchema, request, "B2B Express Checkout request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		primaryShortCode: String(validated.primaryShortCode),
+		receiverShortCode: String(validated.receiverShortCode),
+		amount: String(amount),
+		paymentRef: validated.paymentRef,
+		callbackUrl: validated.callbackUrl,
+		partnerName: validated.partnerName,
+		RequestRefID: validated.requestRefId ?? generateRequestRefId()
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/ussdpush/get-msisdn`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(B2BExpressCheckoutResponseSchema, data, "B2B Express Checkout response");
+}
+
+//#endregion
+//#region src/mpesa/b2b-express-checkout/types.ts
+/**
+* Known B2B Express Checkout result codes.
+*
+* SUCCESS  (0)    — Transaction completed successfully
+* CANCELLED(4001) — Merchant cancelled the USSD prompt
+* KYC_FAIL (4102) — Merchant KYC failure; provide valid KYC
+* NO_NUMBER(4104) — Missing nominated number; configure in M-PESA portal
+* NET_ERROR(4201) — USSD network error; retry on stable network
+* USSD_ERR (4203) — USSD exception error; retry on stable network
+*/
+const B2B_RESULT_CODES = {
+	SUCCESS: "0",
+	CANCELLED: "4001",
+	KYC_FAIL: "4102",
+	NO_NOMINATED_NUMBER: "4104",
+	USSD_NETWORK_ERROR: "4201",
+	USSD_EXCEPTION_ERROR: "4203"
+};
+
+//#endregion
+//#region src/mpesa/b2b-express-checkout/webhooks.ts
+/**
+* src/mpesa/b2b-express-checkout/webhooks.ts
+*
+* B2B Express Checkout callback (webhook) helpers.
+* Strictly aligned with Safaricom Daraja B2B Express Checkout documentation.
+*
+* All callbacks are discriminated on `resultCode`:
+*   "0"    → success  (B2BExpressCheckoutCallbackSuccess)
+*   "4001" → cancelled (B2BExpressCheckoutCallbackCancelled)
+*   other  → failed   (B2BExpressCheckoutCallbackFailed)
+*/
+const KNOWN_RESULT_CODES$3 = new Set(Object.values(B2B_RESULT_CODES));
+/**
+* Runtime type guard — returns true if `body` looks like a valid B2B
+* Express Checkout callback payload.
+*
+* Use this in your callback route before casting the body:
+* @example
+* app.post('/mpesa/b2b/callback', (req, res) => {
+*   if (!isB2BCheckoutCallback(req.body)) {
+*     return res.status(400).json({ error: 'unrecognised payload' })
+*   }
+*   // safe to use as B2BExpressCheckoutCallback
+* })
+*/
+function isB2BCheckoutCallback(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	return typeof b["resultCode"] === "string" && typeof b["requestId"] === "string" && typeof b["amount"] === "string";
+}
+/**
+* Returns true when the B2B callback represents a SUCCESSFUL transaction.
+* A successful callback has resultCode "0" and includes transactionId.
+*
+* Per Daraja docs:
+* {
+*   "resultCode":    "0",
+*   "resultDesc":    "The service request is processed successfully.",
+*   "transactionId": "RDQ01NFT1Q",
+*   "status":        "SUCCESS",
+*   ...
+* }
+*/
+function isB2BCheckoutSuccess(callback) {
+	return callback.resultCode === B2B_RESULT_CODES.SUCCESS;
+}
+/**
+* Returns true when the merchant CANCELLED the USSD prompt.
+* resultCode "4001" = "User cancelled transaction".
+*
+* Per Daraja docs:
+* {
+*   "resultCode":       "4001",
+*   "resultDesc":       "User cancelled transaction",
+*   "paymentReference": "MAndbubry3hi",
+*   ...
+* }
+*/
+function isB2BCheckoutCancelled(callback) {
+	return callback.resultCode === B2B_RESULT_CODES.CANCELLED;
+}
+/**
+* Returns the requestId from any B2B callback.
+* Use this to correlate the callback with your original request.
+*/
+function getB2BRequestId(callback) {
+	return callback.requestId;
+}
+/**
+* Returns the transaction amount as a number from any B2B callback.
+* Daraja sends amount as a string (e.g. "71.0"); this converts it to number.
+*/
+function getB2BAmount(callback) {
+	return Number(callback.amount);
+}
+/**
+* Returns the M-PESA receipt number from a SUCCESSFUL callback.
+* Returns null if the callback is not a success.
+*/
+function getB2BTransactionId(callback) {
+	if (!isB2BCheckoutSuccess(callback)) return null;
+	return callback.transactionId ?? null;
+}
+/**
+* Returns the M-PESA conversationID from a SUCCESSFUL callback.
+* Returns null if the callback is not a success.
+*/
+function getB2BConversationId(callback) {
+	if (!isB2BCheckoutSuccess(callback)) return null;
+	return callback.conversationID ?? null;
+}
+
+//#endregion
+//#region src/mpesa/b2b-buy-goods/payment.ts
+/**
+* src/mpesa/b2b-buy-goods/payment.ts
+*
+* Initiates a Business Buy Goods payment via Safaricom Daraja.
+* Endpoint: POST /mpesa/b2b/v1/paymentrequest
+*
+* Strictly follows the Safaricom Daraja Business Buy Goods API documentation:
+*   - CommandID must be "BusinessBuyGoods"
+*   - SenderIdentifierType is always "4" (hardcoded per docs)
+*   - RecieverIdentifierType is always "4" (hardcoded per docs)
+*   - Amount is sent as a string per the JSON spec
+*   - AccountReference is truncated to max 13 characters per docs
+*   - Requester and Occassion are optional
+*/
+/** Daraja Business Buy Goods endpoint — same as Pay Bill per docs */
+const B2B_BUY_GOODS_ENDPOINT = "/mpesa/b2b/v1/paymentrequest";
+/**
+* Per documentation: SenderIdentifierType and RecieverIdentifierType
+* must always be "4" (Organisation ShortCode). Not configurable.
+*/
+const IDENTIFIER_TYPE$2 = "4";
+/**
+* Initiates a Business Buy Goods payment request.
+*
+* Moves money from your MMF/Working account to the recipient's merchant account
+* (till number, merchant store number, or Merchant HO).
+* The sync response is acknowledgement only — the result arrives via resultUrl.
+*
+* @param baseUrl             - Daraja base URL (sandbox or production)
+* @param accessToken         - Valid OAuth Bearer token
+* @param securityCredential  - RSA-encrypted initiator password (base64)
+* @param initiatorName       - M-Pesa API operator username with B2B role
+* @param request             - Business Buy Goods request parameters
+* @returns                   Synchronous acknowledgement response from Daraja
+* @throws {PesafyError}      VALIDATION_ERROR for invalid input before HTTP call
+* @throws {PesafyError}      From httpRequest on network / API errors
+*/
+async function initiateB2BBuyGoods(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(B2BBuyGoodsRequestSchema, request, "B2B Buy Goods request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: validated.commandId,
+		SenderIdentifierType: IDENTIFIER_TYPE$2,
+		RecieverIdentifierType: IDENTIFIER_TYPE$2,
+		Amount: String(amount),
+		PartyA: String(validated.partyA),
+		PartyB: String(validated.partyB),
+		AccountReference: validated.accountReference.slice(0, 13),
+		Remarks: validated.remarks ?? "Business Buy Goods",
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		ResultURL: validated.resultUrl
+	};
+	if (validated.requester?.trim()) payload["Requester"] = String(validated.requester);
+	if (validated.occasion?.trim()) payload["Occassion"] = validated.occasion;
+	const { data } = await httpRequest(`${baseUrl}${B2B_BUY_GOODS_ENDPOINT}`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(B2BBuyGoodsResponseSchema, data, "B2B Buy Goods response");
+}
+
+//#endregion
+//#region src/mpesa/b2b-buy-goods/types.ts
+/**
+* Known Business Buy Goods result codes documented by Safaricom Daraja.
+*/
+const B2B_BUY_GOODS_RESULT_CODES = {
+	SUCCESS: 0,
+	INSUFFICIENT_FUNDS: 1,
+	AMOUNT_TOO_SMALL: 2,
+	AMOUNT_TOO_LARGE: 3,
+	DAILY_LIMIT_EXCEEDED: 4,
+	MAX_BALANCE_EXCEEDED: 8,
+	INVALID_INITIATOR_INFO: 2001,
+	ACCOUNT_INACTIVE: 2006,
+	PRODUCT_NOT_PERMITTED: 2028,
+	CUSTOMER_NOT_REGISTERED: 2040
+};
+/**
+* Documented Daraja error codes for the Business Buy Goods API.
+*/
+const B2B_BUY_GOODS_ERROR_CODES = {
+	INVALID_ACCESS_TOKEN: "400.003.01",
+	BAD_REQUEST: "400.003.02",
+	INTERNAL_SERVER_ERROR: "500.003.1001",
+	QUOTA_VIOLATION: "500.003.03",
+	SPIKE_ARREST: "500.003.02",
+	NOT_FOUND: "404.003.01",
+	INVALID_AUTH_HEADER: "404.001.04",
+	INVALID_PAYLOAD: "400.002.05"
+};
+
+//#endregion
+//#region src/mpesa/b2b-buy-goods/webhooks.ts
+/**
+* src/mpesa/b2b-buy-goods/webhooks.ts
+*
+* Type guards and payload extractors for Business Buy Goods result callbacks.
+*
+* Result parameters are aligned strictly to Safaricom Daraja documentation:
+*   - Amount
+*   - TransCompletedTime
+*   - ReceiverPartyPublicName
+*   - DebitPartyCharges
+*   - Currency
+*   - DebitPartyAffectedAccountBalance
+*   - DebitAccountBalance
+*   - InitiatorAccountCurrentBalance
+*   - BillReferenceNumber (from ReferenceData)
+*   - QueueTimeoutURL (from ReferenceData)
+*
+* Docs note: ResultCode is "0" (string) on success but 2001 (number) on
+* failure — both forms are handled.
+*/
+const KNOWN_RESULT_CODES$2 = new Set(Object.values(B2B_BUY_GOODS_RESULT_CODES));
+/**
+* Runtime type guard — checks if a body looks like a B2B Buy Goods result callback.
+* Validates the minimum documented structure.
+*/
+function isB2BBuyGoodsResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const result = b["Result"];
+	return (typeof result["ResultCode"] === "number" || typeof result["ResultCode"] === "string") && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+/**
+* Returns true if the B2B Buy Goods result represents a successful transaction.
+* Handles both string "0" (documented in success sample) and number 0.
+*/
+function isB2BBuyGoodsSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+/**
+* Returns true if the B2B Buy Goods result represents a failure.
+*/
+function isB2BBuyGoodsFailure(result) {
+	return !isB2BBuyGoodsSuccess(result);
+}
+/**
+* Returns true if the result code is among the documented codes.
+* Handles both numeric and string representations.
+* Empty strings are explicitly rejected.
+*/
+function isKnownB2BBuyGoodsResultCode(code) {
+	if (typeof code !== "number" && typeof code !== "string") return false;
+	if (typeof code === "string" && code.trim() === "") return false;
+	const numeric = Number(code);
+	return Number.isFinite(numeric) && KNOWN_RESULT_CODES$2.has(numeric);
+}
+/**
+* Extracts the M-PESA transaction ID from a B2B Buy Goods result.
+* Present on both success and failure (generic ID on failure).
+*/
+function getB2BBuyGoodsTransactionId(result) {
+	return result.Result.TransactionID;
+}
+/**
+* Extracts the ConversationID from a B2B Buy Goods result.
+*/
+function getB2BBuyGoodsConversationId(result) {
+	return result.Result.ConversationID;
+}
+/**
+* Extracts the OriginatorConversationID from a B2B Buy Goods result.
+* Use this to correlate with the original API call response.
+*/
+function getB2BBuyGoodsOriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+/**
+* Extracts the result description (human-readable status).
+*/
+function getB2BBuyGoodsResultDesc(result) {
+	return result.Result.ResultDesc;
+}
+/**
+* Extracts the result code from a B2B Buy Goods result.
+*/
+function getB2BBuyGoodsResultCode(result) {
+	return result.Result.ResultCode;
+}
+/**
+* Extracts the transaction amount from B2B Buy Goods result parameters.
+* Documented field: "Amount"
+* Returns null if not present (e.g. on failure).
+*/
+function getB2BBuyGoodsAmount(result) {
+	const value = getB2BBuyGoodsResultParam(result, "Amount");
+	if (value === void 0) return null;
+	const num = Number(value);
+	return Number.isFinite(num) ? num : null;
+}
+/**
+* Extracts the transaction completion time.
+* Documented field: "TransCompletedTime" — format: YYYYMMDDHHmmss
+* Falls back to "BOCompletedTime" (present on some failure callbacks).
+* Returns null if not present.
+*/
+function getB2BBuyGoodsCompletedTime(result) {
+	const value = getB2BBuyGoodsResultParam(result, "TransCompletedTime") ?? getB2BBuyGoodsResultParam(result, "BOCompletedTime");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the receiver's public name from result parameters.
+* Documented field: "ReceiverPartyPublicName"
+* Returns null if not present.
+*/
+function getB2BBuyGoodsReceiverName(result) {
+	const value = getB2BBuyGoodsResultParam(result, "ReceiverPartyPublicName");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts debit party charges from result parameters.
+* Documented field: "DebitPartyCharges"
+* Returns null if not present or empty string (no charges applied).
+*/
+function getB2BBuyGoodsDebitPartyCharges(result) {
+	const value = getB2BBuyGoodsResultParam(result, "DebitPartyCharges");
+	if (value === void 0 || value === "") return null;
+	return String(value);
+}
+/**
+* Extracts the transaction currency from result parameters.
+* Documented field: "Currency"
+* Returns "KES" as default when not present.
+*/
+function getB2BBuyGoodsCurrency(result) {
+	const value = getB2BBuyGoodsResultParam(result, "Currency");
+	if (value === void 0 || value === "") return "KES";
+	return String(value);
+}
+/**
+* Extracts the debit party affected account balance.
+* Documented field: "DebitPartyAffectedAccountBalance"
+* Format: "Working Account|KES|346568.83|6186.83|340382.00|0.00"
+* Returns null if not present.
+*/
+function getB2BBuyGoodsDebitPartyAffectedBalance(result) {
+	const value = getB2BBuyGoodsResultParam(result, "DebitPartyAffectedAccountBalance");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the debit account balance.
+* Documented field: "DebitAccountBalance"
+* Format: "{Amount={CurrencyCode=KES, MinimumAmount=618683, BasicAmount=6186.83}}"
+* Returns null if not present.
+*/
+function getB2BBuyGoodsDebitAccountBalance(result) {
+	const value = getB2BBuyGoodsResultParam(result, "DebitAccountBalance");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the initiator account current balance.
+* Documented field: "InitiatorAccountCurrentBalance"
+* Returns null if not present.
+*/
+function getB2BBuyGoodsInitiatorBalance(result) {
+	const value = getB2BBuyGoodsResultParam(result, "InitiatorAccountCurrentBalance");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the Bill Reference Number from ReferenceData.
+* Documented field: "BillReferenceNumber" (in ReferenceData, not ResultParameters)
+* Returns null if not present.
+*/
+function getB2BBuyGoodsBillReferenceNumber(result) {
+	const refData = result.Result.ReferenceData?.ReferenceItem;
+	if (!refData) return null;
+	return (Array.isArray(refData) ? refData : [refData]).find((i) => i.Key === "BillReferenceNumber")?.Value ?? null;
+}
+/**
+* Extracts the QueueTimeoutURL from ReferenceData.
+* Documented field: "QueueTimeoutURL" (in ReferenceData)
+* Returns null if not present.
+*/
+function getB2BBuyGoodsQueueTimeoutUrl(result) {
+	const refData = result.Result.ReferenceData?.ReferenceItem;
+	if (!refData) return null;
+	return (Array.isArray(refData) ? refData : [refData]).find((i) => i.Key === "QueueTimeoutURL")?.Value ?? null;
+}
+/**
+* Extracts a named value from B2B Buy Goods result parameters.
+* Handles both single-object and array forms of ResultParameter
+* (Daraja returns either depending on how many parameters are present).
+* Returns undefined if key is absent or no ResultParameters exist.
+*/
+function getB2BBuyGoodsResultParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return (Array.isArray(params) ? params : [params]).find((p) => p.Key === key)?.Value;
+}
+
+//#endregion
+//#region src/mpesa/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/mpesa/b2b-pay-bill/types.ts
+/**
+* Known Business Pay Bill result codes documented by Safaricom Daraja.
+*/
+const B2B_PAY_BILL_RESULT_CODES = {
+	SUCCESS: 0,
+	INSUFFICIENT_FUNDS: 1,
+	AMOUNT_TOO_SMALL: 2,
+	AMOUNT_TOO_LARGE: 3,
+	DAILY_LIMIT_EXCEEDED: 4,
+	MAX_BALANCE_EXCEEDED: 8,
+	INVALID_INITIATOR_INFO: 2001,
+	ACCOUNT_INACTIVE: 2006,
+	PRODUCT_NOT_PERMITTED: 2028,
+	CUSTOMER_NOT_REGISTERED: 2040
+};
+/**
+* Documented Daraja error codes for the Business Pay Bill API.
+*/
+const B2B_PAY_BILL_ERROR_CODES = {
+	INVALID_ACCESS_TOKEN: "400.003.01",
+	BAD_REQUEST: "400.003.02",
+	INTERNAL_SERVER_ERROR: "500.003.1001",
+	QUOTA_VIOLATION: "500.003.03",
+	SPIKE_ARREST: "500.003.02",
+	NOT_FOUND: "404.003.01",
+	INVALID_AUTH_HEADER: "404.001.04",
+	INVALID_PAYLOAD: "400.002.05"
+};
+
+//#endregion
+//#region src/mpesa/b2b-pay-bill/webhooks.ts
+/**
+* src/mpesa/b2b-pay-bill/webhooks.ts
+*
+* Type guards and payload extractors for Business Pay Bill result callbacks.
+*
+* Result parameters are aligned strictly to Safaricom Daraja documentation:
+*   - Amount
+*   - TransCompletedTime
+*   - ReceiverPartyPublicName
+*   - DebitPartyCharges
+*   - Currency
+*   - DebitPartyAffectedAccountBalance
+*   - DebitAccountCurrentBalance
+*   - InitiatorAccountCurrentBalance
+*   - BillReferenceNumber (from ReferenceData)
+*
+* Docs note: ResultCode is "0" (string) on success but 2001 (number) on
+* failure — both forms are handled.
+*/
+const KNOWN_RESULT_CODES$1 = new Set(Object.values(B2B_PAY_BILL_RESULT_CODES));
+/**
+* Runtime type guard — checks if a body looks like a B2B Pay Bill result callback.
+* Validates the minimum documented structure.
+*/
+function isB2BPayBillResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const result = b["Result"];
+	return (typeof result["ResultCode"] === "number" || typeof result["ResultCode"] === "string") && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+/**
+* Returns true if the B2B Pay Bill result represents a successful transaction.
+* Handles both string "0" (documented in success sample) and number 0.
+*/
+function isB2BPayBillSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+/**
+* Returns true if the B2B Pay Bill result represents a failure.
+*/
+function isB2BPayBillFailure(result) {
+	return !isB2BPayBillSuccess(result);
+}
+/**
+* Returns true if the result code is among the documented codes.
+* Handles both numeric and string representations.
+* Empty strings are explicitly rejected.
+*/
+function isKnownB2BPayBillResultCode(code) {
+	if (typeof code !== "number" && typeof code !== "string") return false;
+	if (typeof code === "string" && code.trim() === "") return false;
+	const numeric = Number(code);
+	return Number.isFinite(numeric) && KNOWN_RESULT_CODES$1.has(numeric);
+}
+/**
+* Extracts the M-PESA transaction ID from a B2B Pay Bill result.
+* Present on both success and failure (generic ID on failure).
+*/
+function getB2BPayBillTransactionId(result) {
+	return result.Result.TransactionID;
+}
+/**
+* Extracts the ConversationID from a B2B Pay Bill result.
+*/
+function getB2BPayBillConversationId(result) {
+	return result.Result.ConversationID;
+}
+/**
+* Extracts the OriginatorConversationID from a B2B Pay Bill result.
+* Use this to correlate with the original API call response.
+*/
+function getB2BPayBillOriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+/**
+* Extracts the result description (human-readable status).
+*/
+function getB2BPayBillResultDesc(result) {
+	return result.Result.ResultDesc;
+}
+/**
+* Extracts the numeric result code from a B2B Pay Bill result.
+*/
+function getB2BPayBillResultCode(result) {
+	return result.Result.ResultCode;
+}
+/**
+* Extracts the transaction amount from B2B Pay Bill result parameters.
+* Documented field: "Amount"
+* Returns null if not present (e.g. on failure).
+*/
+function getB2BPayBillAmount(result) {
+	const value = getB2BPayBillResultParam(result, "Amount");
+	if (value === void 0) return null;
+	const num = Number(value);
+	return Number.isFinite(num) ? num : null;
+}
+/**
+* Extracts the transaction completion time.
+* Documented field: "TransCompletedTime" — format: YYYYMMDDHHmmss
+* Returns null if not present.
+*/
+function getB2BPayBillCompletedTime(result) {
+	const value = getB2BPayBillResultParam(result, "TransCompletedTime") ?? getB2BPayBillResultParam(result, "BOCompletedTime");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the receiver's public name from result parameters.
+* Documented field: "ReceiverPartyPublicName"
+* Returns null if not present.
+*/
+function getB2BPayBillReceiverName(result) {
+	const value = getB2BPayBillResultParam(result, "ReceiverPartyPublicName");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts debit party charges from result parameters.
+* Documented field: "DebitPartyCharges"
+* Returns null if not present or empty.
+*/
+function getB2BPayBillDebitPartyCharges(result) {
+	const value = getB2BPayBillResultParam(result, "DebitPartyCharges");
+	if (value === void 0 || value === "") return null;
+	return String(value);
+}
+/**
+* Extracts the transaction currency from result parameters.
+* Documented field: "Currency"
+* Returns "KES" as default when not present.
+*/
+function getB2BPayBillCurrency(result) {
+	const value = getB2BPayBillResultParam(result, "Currency");
+	if (value === void 0 || value === "") return "KES";
+	return String(value);
+}
+/**
+* Extracts the debit party affected account balance.
+* Documented field: "DebitPartyAffectedAccountBalance"
+* Returns null if not present.
+*/
+function getB2BPayBillDebitPartyAffectedBalance(result) {
+	const value = getB2BPayBillResultParam(result, "DebitPartyAffectedAccountBalance");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the debit account current balance.
+* Documented field: "DebitAccountCurrentBalance"
+* Returns null if not present.
+*/
+function getB2BPayBillDebitAccountBalance(result) {
+	const value = getB2BPayBillResultParam(result, "DebitAccountCurrentBalance");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the initiator account current balance.
+* Documented field: "InitiatorAccountCurrentBalance"
+* Returns null if not present.
+*/
+function getB2BPayBillInitiatorBalance(result) {
+	const value = getB2BPayBillResultParam(result, "InitiatorAccountCurrentBalance");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the Bill Reference Number from ReferenceData.
+* Documented field: "BillReferenceNumber" (in ReferenceData, not ResultParameters)
+* Returns null if not present.
+*/
+function getB2BPayBillBillReferenceNumber(result) {
+	const refData = result.Result.ReferenceData?.ReferenceItem;
+	if (!refData) return null;
+	return (Array.isArray(refData) ? refData : [refData]).find((i) => i.Key === "BillReferenceNumber")?.Value ?? null;
+}
+/**
+* Extracts a named value from B2B Pay Bill result parameters.
+* Handles both single-object and array forms of ResultParameter
+* (Daraja returns either depending on how many parameters are present).
+* Returns undefined if key is absent or no ResultParameters exist.
+*/
+function getB2BPayBillResultParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return (Array.isArray(params) ? params : [params]).find((p) => p.Key === key)?.Value;
+}
+
+//#endregion
+//#region src/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/types.ts
+/**
+* Documented Daraja error codes for the B2C Account Top Up API.
+*/
+const B2C_ERROR_CODES = {
+	INTERNAL_SERVER_ERROR: "500.003.1001",
+	INVALID_ACCESS_TOKEN: "400.003.01",
+	BAD_REQUEST: "400.003.02",
+	QUOTA_VIOLATION: "500.003.03",
+	SPIKE_ARREST: "500.003.02",
+	NOT_FOUND: "404.003.01",
+	INVALID_AUTH_HEADER: "404.001.04",
+	INVALID_PAYLOAD: "400.002.05"
+};
+/**
+* Known B2C result codes documented by Safaricom Daraja.
+*/
+const B2C_RESULT_CODES = {
+	SUCCESS: 0,
+	INVALID_INITIATOR: 2001
+};
+
+//#endregion
+//#region src/mpesa/b2c/webhooks.ts
+/**
+* src/mpesa/b2c/webhooks.ts
+*
+* Type guards and payload extractors for B2C Account Top Up result callbacks.
+*
+* Result parameters are aligned strictly to Safaricom Daraja documentation:
+*   - DebitAccountBalance
+*   - Amount
+*   - Currency
+*   - ReceiverPartyPublicName
+*   - TransactionCompletedTime
+*   - DebitPartyCharges
+*
+* Docs note: ResultCode is "0" (string) on success but 2001 (number) on
+* failure — both forms are handled by the type guard.
+*/
+/**
+* Runtime type guard — checks if a body looks like a B2C result callback.
+* Validates the minimum documented structure.
+*/
+function isB2CResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const result = b["Result"];
+	return (typeof result["ResultCode"] === "number" || typeof result["ResultCode"] === "string") && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+/**
+* Returns true if the B2C result represents a successful transaction.
+* Handles both string "0" (documented in success sample) and number 0.
+*/
+function isB2CSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+/**
+* Returns true if the B2C result represents a failure.
+* Handles both string "0" (documented in success sample) and number 0.
+*/
+function isB2CFailure(result) {
+	return !isB2CSuccess(result);
+}
+/**
+* Returns true if the result code matches a known documented code.
+* Empty strings are explicitly rejected — Number('') coerces to 0 which
+* would otherwise incorrectly match B2C_RESULT_CODES.SUCCESS.
+*/
+function isKnownB2CResultCode(code) {
+	if (typeof code !== "number" && typeof code !== "string") return false;
+	if (typeof code === "string" && code.trim() === "") return false;
+	const numeric = Number(code);
+	return Object.values(B2C_RESULT_CODES).includes(numeric);
+}
+/**
+* Extracts the M-PESA transaction ID from a B2C result.
+* Present on both success and failure (generic ID on failure).
+*/
+function getB2CTransactionId(result) {
+	return result.Result.TransactionID ?? null;
+}
+/**
+* Extracts the ConversationID from a B2C result.
+*/
+function getB2CConversationId(result) {
+	return result.Result.ConversationID;
+}
+/**
+* Extracts the OriginatorConversationID from a B2C result.
+* Use this to correlate with the original API call response.
+*/
+function getB2COriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+/**
+* Extracts the result description (human-readable status).
+*/
+function getB2CResultDesc(result) {
+	return result.Result.ResultDesc;
+}
+/**
+* Extracts the transaction amount from B2C result parameters.
+* Documented field: "Amount"
+* Returns null if not present (e.g. on failure).
+*/
+function getB2CAmount(result) {
+	const value = getB2CResultParam(result, "Amount");
+	if (value === void 0) return null;
+	const num = Number(value);
+	return Number.isFinite(num) ? num : null;
+}
+/**
+* Extracts the transaction currency from B2C result parameters.
+* Documented field: "Currency"
+* Returns "KES" as default when not present.
+*/
+function getB2CCurrency(result) {
+	const value = getB2CResultParam(result, "Currency");
+	if (value === void 0 || value === "") return "KES";
+	return String(value);
+}
+/**
+* Extracts the receiver's public name from B2C result parameters.
+* Documented field: "ReceiverPartyPublicName"
+* Returns null if not present.
+*/
+function getB2CReceiverPublicName(result) {
+	const value = getB2CResultParam(result, "ReceiverPartyPublicName");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the transaction completion timestamp from B2C result parameters.
+* Documented field: "TransactionCompletedTime" — format: YYYYMMDDHHmmss
+* Returns null if not present.
+*/
+function getB2CTransactionCompletedTime(result) {
+	const value = getB2CResultParam(result, "TransactionCompletedTime");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the debit account balance from B2C result parameters.
+* Documented field: "DebitAccountBalance" (e.g. "{CurrencyCode=KES}")
+* Returns null if not present.
+*/
+function getB2CDebitAccountBalance(result) {
+	const value = getB2CResultParam(result, "DebitAccountBalance");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the debit party charges from B2C result parameters.
+* Documented field: "DebitPartyCharges"
+* Returns null if not present or empty.
+*/
+function getB2CDebitPartyCharges(result) {
+	const value = getB2CResultParam(result, "DebitPartyCharges");
+	if (value === void 0 || value === "") return null;
+	return String(value);
+}
+/**
+* Extracts a named value from B2C result parameters.
+* Handles both single-object and array forms of ResultParameter
+* (Daraja returns either depending on how many parameters are present).
+* Returns undefined if key is absent or no ResultParameters exist.
+*/
+function getB2CResultParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return (Array.isArray(params) ? params : [params]).find((p) => p.Key === key)?.Value;
+}
+
+//#endregion
+//#region src/mpesa/b2c-disbursement/payment.ts
+/**
+* src/mpesa/b2c-disbursement/payment.ts
+*
+* Initiates a B2C Disbursement payment (Salary / Cashback / Promotion).
+* Endpoint: POST /mpesa/b2c/v3/paymentrequest
+*/
+const B2C_DISBURSEMENT_ENDPOINT = "/mpesa/b2c/v3/paymentrequest";
+const VALID_COMMAND_IDS = new Set([
+	"BusinessPayment",
+	"SalaryPayment",
+	"PromotionPayment"
+]);
+/**
+* Initiates a B2C disbursement payment request.
+*
+* @param baseUrl              - Daraja base URL (sandbox or production)
+* @param accessToken          - Valid OAuth Bearer token
+* @param securityCredential   - RSA-encrypted initiator password (base64)
+* @param initiatorName        - M-Pesa API operator username
+* @param request              - B2C disbursement request parameters
+*/
+async function initiateB2CDisbursement(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const originatorConversationId = request.originatorConversationId?.trim() || generateOriginatorConversationId();
+	const validated = parseWithSchema(B2CDisbursementRequestSchema, {
+		...request,
+		originatorConversationId
+	}, "B2C Disbursement request");
+	if (!validated.commandId || !VALID_COMMAND_IDS.has(validated.commandId)) throw createError({
+		code: "VALIDATION_ERROR",
+		message: `commandId must be one of: BusinessPayment, SalaryPayment, PromotionPayment. Got "${validated.commandId}".`
+	});
+	const amount = Math.round(validated.amount);
+	if (!Number.isFinite(amount) || amount < 10) throw createError({
+		code: "VALIDATION_ERROR",
+		message: `amount must be ≥ 10 KES (got ${validated.amount} which rounds to ${amount}).`
+	});
+	if (!validated.partyA?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "partyA is required — the sending organisation shortcode."
+	});
+	if (!validated.partyB?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "partyB is required — the receiving customer MSISDN (2547XXXXXXXX)."
+	});
+	if (!validated.remarks?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "remarks is required (2–100 characters)."
+	});
+	if (!validated.resultUrl?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "resultUrl is required — Safaricom POSTs the async result here."
+	});
+	if (!validated.queueTimeOutUrl?.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "queueTimeOutUrl is required — Safaricom calls this on request timeout."
+	});
+	const payload = {
+		OriginatorConversationID: originatorConversationId,
+		InitiatorName: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: validated.commandId,
+		Amount: amount,
+		PartyA: String(validated.partyA),
+		PartyB: String(validated.partyB),
+		Remarks: validated.remarks,
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		ResultURL: validated.resultUrl
+	};
+	if (validated.occasion?.trim()) payload["Occassion"] = validated.occasion;
+	const { data } = await httpRequest(`${baseUrl}${B2C_DISBURSEMENT_ENDPOINT}`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(B2CDisbursementResponseSchema, data, "B2C Disbursement response");
+}
+
+//#endregion
+//#region src/mpesa/b2c-disbursement/types.ts
+/**
+* All documented B2C result codes.
+* Note: SFC_IC0003 is a string — all others are numeric.
+*/
+const B2C_DISBURSEMENT_RESULT_CODES = {
+	SUCCESS: 0,
+	INSUFFICIENT_BALANCE: 1,
+	AMOUNT_TOO_SMALL: 2,
+	AMOUNT_TOO_LARGE: 3,
+	DAILY_LIMIT_EXCEEDED: 4,
+	MAX_BALANCE_EXCEEDED: 8,
+	DEBIT_PARTY_INVALID: 11,
+	INITIATOR_NOT_ALLOWED: 21,
+	INVALID_INITIATOR_INFO: 2001,
+	ACCOUNT_INACTIVE: 2006,
+	PRODUCT_NOT_PERMITTED: 2028,
+	CUSTOMER_NOT_REGISTERED: 2040,
+	SECURITY_CREDENTIAL_LOCKED: 8006,
+	OPERATOR_DOES_NOT_EXIST: "SFC_IC0003"
+};
+
+//#endregion
+//#region src/mpesa/b2c-disbursement/webhooks.ts
+/**
+* src/mpesa/b2c-disbursement/webhooks.ts
+*
+* Type guards and payload extractors for B2C Disbursement result callbacks.
+*/
+function isB2CDisbursementResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const result = b["Result"];
+	return (typeof result["ResultCode"] === "number" || typeof result["ResultCode"] === "string") && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+function isB2CDisbursementSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+function isB2CDisbursementFailure(result) {
+	return !isB2CDisbursementSuccess(result);
+}
+/**
+* Returns true if the result code is among the 14 documented codes.
+* Handles both numeric codes and the string code "SFC_IC0003".
+* Rejects empty strings (Number('') → 0 which would falsely match SUCCESS).
+*/
+function isKnownB2CDisbursementResultCode(code) {
+	if (code === null || code === void 0) return false;
+	if (typeof code !== "number" && typeof code !== "string") return false;
+	if (typeof code === "string" && code === B2C_DISBURSEMENT_RESULT_CODES.OPERATOR_DOES_NOT_EXIST) return true;
+	if (typeof code === "string" && code.trim() === "") return false;
+	const numeric = Number(code);
+	return Object.values(B2C_DISBURSEMENT_RESULT_CODES).filter((v) => typeof v === "number").includes(numeric);
+}
+function getB2CDisbursementTransactionId(result) {
+	return result.Result.TransactionID ?? null;
+}
+function getB2CDisbursementConversationId(result) {
+	return result.Result.ConversationID;
+}
+function getB2CDisbursementOriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+function getB2CDisbursementResultDesc(result) {
+	return result.Result.ResultDesc;
+}
+function getB2CDisbursementResultCode(result) {
+	return result.Result.ResultCode;
+}
+function getB2CDisbursementResultParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return (Array.isArray(params) ? params : [params]).find((p) => p.Key === key)?.Value;
+}
+function getB2CDisbursementAmount(result) {
+	const value = getB2CDisbursementResultParam(result, "TransactionAmount");
+	if (value === void 0) return null;
+	const num = Number(value);
+	return Number.isFinite(num) ? num : null;
+}
+function getB2CDisbursementReceiptNumber(result) {
+	const value = getB2CDisbursementResultParam(result, "TransactionReceipt");
+	if (value === void 0) return null;
+	return String(value);
+}
+function getB2CDisbursementReceiverName(result) {
+	const value = getB2CDisbursementResultParam(result, "ReceiverPartyPublicName");
+	if (value === void 0) return null;
+	return String(value);
+}
+function getB2CDisbursementCompletedTime(result) {
+	const value = getB2CDisbursementResultParam(result, "TransactionCompletedDateTime");
+	if (value === void 0) return null;
+	return String(value);
+}
+function getB2CDisbursementUtilityBalance(result) {
+	const value = getB2CDisbursementResultParam(result, "B2CUtilityAccountAvailableFunds");
+	if (value === void 0) return null;
+	const num = Number(value);
+	return Number.isFinite(num) ? num : null;
+}
+function getB2CDisbursementWorkingBalance(result) {
+	const value = getB2CDisbursementResultParam(result, "B2CWorkingAccountAvailableFunds");
+	if (value === void 0) return null;
+	const num = Number(value);
+	return Number.isFinite(num) ? num : null;
+}
+function isB2CDisbursementRecipientRegistered(result) {
+	const value = getB2CDisbursementResultParam(result, "B2CRecipientIsRegisteredCustomer");
+	if (value === void 0) return null;
+	return String(value).toUpperCase() === "Y";
+}
+
+//#endregion
+//#region src/schemas/bill-manager.ts
+const SendRemindersSchema = z.enum(["0", "1"]);
+const BillManagerOptInRequestSchema = z.object({
+	shortcode: NonEmptyStringSchema,
+	email: NonEmptyStringSchema,
+	officialContact: NonEmptyStringSchema,
+	sendReminders: SendRemindersSchema,
+	logo: z.string().optional(),
+	callbackUrl: UrlSchema
+});
+const BillManagerOptInResponseSchema = z.object({
+	app_key: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+const BillManagerUpdateOptInRequestSchema = BillManagerOptInRequestSchema;
+const BillManagerUpdateOptInResponseSchema = z.object({
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+const BillManagerInvoiceItemSchema = z.object({
+	itemName: NonEmptyStringSchema,
+	amount: KesAmountSchema
+});
+const BillManagerSingleInvoiceRequestSchema = z.object({
+	externalReference: NonEmptyStringSchema,
+	billedFullName: NonEmptyStringSchema,
+	billedPhoneNumber: NonEmptyStringSchema,
+	billedPeriod: NonEmptyStringSchema,
+	invoiceName: NonEmptyStringSchema,
+	dueDate: NonEmptyStringSchema,
+	accountReference: NonEmptyStringSchema,
+	amount: KesAmountSchema,
+	invoiceItems: z.array(BillManagerInvoiceItemSchema).optional()
+});
+const BillManagerSingleInvoiceResponseSchema = z.object({
+	Status_Message: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+const BillManagerBulkInvoiceRequestSchema = z.object({ invoices: z.array(BillManagerSingleInvoiceRequestSchema).min(1).max(1e3) });
+const BillManagerBulkInvoiceResponseSchema = z.object({
+	Status_Message: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+const BillManagerCancelInvoiceRequestSchema = z.object({ externalReference: NonEmptyStringSchema });
+const BillManagerCancelInvoiceResponseSchema = z.object({
+	Status_Message: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string(),
+	errors: z.array(z.unknown()).optional()
+}).passthrough();
+const BillManagerCancelBulkInvoiceRequestSchema = z.object({ externalReferences: z.array(NonEmptyStringSchema).min(1) });
+const BillManagerCancelBulkInvoiceResponseSchema = z.object({
+	Status_Message: z.string().optional(),
+	resmsg: z.string(),
+	rescode: z.string(),
+	errors: z.array(z.unknown()).optional()
+}).passthrough();
+const BillManagerReconciliationRequestSchema = z.object({
+	paymentDate: NonEmptyStringSchema,
+	paidAmount: NonEmptyStringSchema,
+	accountReference: NonEmptyStringSchema,
+	transactionId: NonEmptyStringSchema,
+	phoneNumber: NonEmptyStringSchema,
+	fullName: NonEmptyStringSchema,
+	invoiceName: NonEmptyStringSchema,
+	externalReference: NonEmptyStringSchema
+});
+const BillManagerReconciliationResponseSchema = z.object({
+	resmsg: z.string(),
+	rescode: z.string()
+}).passthrough();
+
+//#endregion
+//#region src/mpesa/bill-manager/invoice.ts
+/**
+* src/mpesa/bill-manager/invoice.ts
+*
+* Bill Manager — opt-in, invoice creation/cancellation, and payment reconciliation.
+*
+* Strictly aligned with Safaricom Daraja Bill Manager API documentation.
+*
+* APIs:
+*   POST /v1/billmanager-invoice/optin                 — Opt-in shortcode
+*   POST /v1/billmanager-invoice/change-optin-details  — Update opt-in details
+*   POST /v1/billmanager-invoice/single-invoicing      — Send a single invoice
+*   POST /v1/billmanager-invoice/bulk-invoicing        — Send bulk invoices (up to 1000)
+*   POST /v1/billmanager-invoice/cancel-single-invoice — Cancel a single invoice
+*   POST /v1/billmanager-invoice/cancel-bulk-invoices  — Cancel multiple invoices
+*   POST /v1/billmanager-invoice/reconciliation        — Acknowledge a payment
+*/
+async function billManagerOptIn(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerOptInRequestSchema, request, "Bill Manager opt-in request");
+	const payload = {
+		shortcode: validated.shortcode,
+		email: validated.email,
+		officialContact: validated.officialContact,
+		sendReminders: validated.sendReminders,
+		logo: validated.logo ?? "",
+		callbackurl: validated.callbackUrl
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/optin`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerOptInResponseSchema, data, "Bill Manager opt-in response");
+}
+async function updateOptIn(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerUpdateOptInRequestSchema, request, "Bill Manager update opt-in request");
+	const payload = {
+		shortcode: validated.shortcode,
+		email: validated.email,
+		officialContact: validated.officialContact,
+		sendReminders: validated.sendReminders,
+		logo: validated.logo ?? "",
+		callbackurl: validated.callbackUrl
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/change-optin-details`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerUpdateOptInResponseSchema, data, "Bill Manager update opt-in response");
+}
+async function sendSingleInvoice(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerSingleInvoiceRequestSchema, request, "Bill Manager single invoice request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		externalReference: validated.externalReference,
+		billedFullName: validated.billedFullName,
+		billedPhoneNumber: validated.billedPhoneNumber,
+		billedPeriod: validated.billedPeriod,
+		invoiceName: validated.invoiceName,
+		dueDate: validated.dueDate,
+		accountReference: validated.accountReference,
+		amount: String(amount),
+		invoiceItems: validated.invoiceItems?.map((i) => ({
+			itemName: i.itemName,
+			amount: String(Math.round(i.amount))
+		})) ?? []
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/single-invoicing`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerSingleInvoiceResponseSchema, data, "Bill Manager single invoice response");
+}
+async function sendBulkInvoices(baseUrl, accessToken, request, http) {
+	const payload = parseWithSchema(BillManagerBulkInvoiceRequestSchema, request, "Bill Manager bulk invoice request").invoices.map((inv) => ({
+		externalReference: inv.externalReference,
+		billedFullName: inv.billedFullName,
+		billedPhoneNumber: inv.billedPhoneNumber,
+		billedPeriod: inv.billedPeriod,
+		invoiceName: inv.invoiceName,
+		dueDate: inv.dueDate,
+		accountReference: inv.accountReference,
+		amount: String(Math.round(inv.amount)),
+		invoiceItems: inv.invoiceItems?.map((item) => ({
+			itemName: item.itemName,
+			amount: String(Math.round(item.amount))
+		})) ?? []
+	}));
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/bulk-invoicing`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerBulkInvoiceResponseSchema, data, "Bill Manager bulk invoice response");
+}
+async function cancelInvoice(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerCancelInvoiceRequestSchema, request, "Bill Manager cancel invoice request");
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/cancel-single-invoice`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: { externalReference: validated.externalReference }
+	}, http));
+	return parseWithSchema(BillManagerCancelInvoiceResponseSchema, data, "Bill Manager cancel invoice response");
+}
+async function cancelBulkInvoices(baseUrl, accessToken, request, http) {
+	const payload = parseWithSchema(BillManagerCancelBulkInvoiceRequestSchema, request, "Bill Manager cancel bulk invoices request").externalReferences.map((ref) => ({ externalReference: ref }));
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/cancel-bulk-invoices`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerCancelBulkInvoiceResponseSchema, data, "Bill Manager cancel bulk invoices response");
+}
+async function reconcilePayment(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(BillManagerReconciliationRequestSchema, request, "Bill Manager reconciliation request");
+	const payload = {
+		paymentDate: validated.paymentDate,
+		paidAmount: validated.paidAmount,
+		accountReference: validated.accountReference,
+		transactionId: validated.transactionId,
+		phoneNumber: validated.phoneNumber,
+		fullName: validated.fullName,
+		invoiceName: validated.invoiceName,
+		externalReference: validated.externalReference
+	};
+	const { data } = await httpRequest(`${baseUrl}/v1/billmanager-invoice/reconciliation`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(BillManagerReconciliationResponseSchema, data, "Bill Manager reconciliation response");
+}
+
+//#endregion
+//#region src/schemas/c2b.ts
+const C2BRegisterUrlRequestSchema = z.object({
+	shortCode: NonEmptyStringSchema,
+	responseType: z.enum(["Completed", "Cancelled"]),
+	confirmationUrl: UrlSchema,
+	validationUrl: UrlSchema,
+	apiVersion: z.enum(["v1", "v2"]).optional()
+});
+const C2BBaseResponseSchema = z.object({
+	OriginatorCoversationID: z.string(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string()
+}).passthrough();
+const C2BRegisterUrlResponseSchema = C2BBaseResponseSchema;
+const C2BSimulateResponseSchema = C2BBaseResponseSchema;
+const C2BSimulateRequestSchema = z.object({
+	shortCode: z.union([NonEmptyStringSchema, z.number()]),
+	commandId: z.enum(["CustomerPayBillOnline", "CustomerBuyGoodsOnline"]),
+	amount: KesAmountSchema,
+	msisdn: z.union([NonEmptyStringSchema, z.number()]),
+	billRefNumber: z.union([NonEmptyStringSchema, z.null()]).optional(),
+	apiVersion: z.enum(["v1", "v2"]).optional()
+}).superRefine((data, ctx) => {
+	if (data.commandId === "CustomerPayBillOnline" && !data.billRefNumber?.trim()) ctx.addIssue({
+		code: "custom",
+		message: "billRefNumber is required for CustomerPayBillOnline",
+		path: ["billRefNumber"]
+	});
+});
+const C2BValidationWebhookSchema = z.object({
+	TransactionType: z.string(),
+	TransID: z.string(),
+	TransTime: z.string(),
+	TransAmount: z.union([z.string(), z.number()]),
+	BusinessShortCode: z.string(),
+	BillRefNumber: z.string().optional(),
+	MSISDN: z.string()
+}).passthrough();
+
+//#endregion
+//#region src/mpesa/c2b/register-url.ts
+/**
+* src/mpesa/c2b/register-url.ts
+*
+* C2B Register URL implementation.
+* Strictly aligned with Safaricom Daraja C2B Register URL API documentation.
+*
+* Endpoint (v1 — documented primary):
+*   Sandbox:    POST https://sandbox.safaricom.co.ke/mpesa/c2b/v1/registerurl
+*   Production: POST https://api.safaricom.co.ke/mpesa/c2b/v1/registerurl
+*
+* Also supports v2 via the apiVersion option.
+*/
+/**
+* Forbidden URL keywords per Daraja documentation:
+* "Avoid keywords such as M-PESA, M-Pesa, Safaricom, exe, exec, cme, or variants in your URLs."
+*
+* We lowercase-compare, so "MPESA", "Mpesa", "mPeSa" are all caught.
+*
+* Additional blocked keywords (documented variants): cmd, sql, query
+*/
+const FORBIDDEN_URL_KEYWORDS = [
+	"mpesa",
+	"safaricom",
+	"exec",
+	"exe",
+	"cme",
+	"cmd",
+	"sql",
+	"query"
+];
+/**
+* Validates a callback URL against Daraja's documented URL requirements.
+* Throws PesafyError if the URL violates any documented rule.
+*/
+function validateCallbackUrl(url, fieldName) {
+	if (!url || !url.trim()) throw createError({
+		code: "VALIDATION_ERROR",
+		message: `${fieldName} is required`
+	});
+	const lower = url.toLowerCase();
+	for (const keyword of FORBIDDEN_URL_KEYWORDS) if (lower.includes(keyword)) throw createError({
+		code: "VALIDATION_ERROR",
+		message: `${fieldName} must not contain the keyword "${keyword}". Daraja rejects URLs containing: mpesa, safaricom, exe, exec, cme (and variants: cmd, sql, query).`
+	});
+}
+/**
+* Registers C2B Confirmation and Validation URLs with Safaricom.
+*
+* Per Daraja documentation:
+*   - Sandbox: may be called multiple times (URLs can be overwritten).
+*   - Production: one-time call. To change URLs, delete existing on the portal
+*     or email apisupport@safaricom.co.ke, then re-register.
+*   - ResponseType must be sentence-case: "Completed" or "Cancelled".
+*   - Both URLs must be publicly accessible and internet-reachable.
+*   - Production requires HTTPS; Sandbox allows HTTP.
+*   - Do not use public URL testers (ngrok, mockbin, requestbin) — they are blocked.
+*   - The Validation URL is only called when external validation is enabled.
+*     To activate, email apisupport@safaricom.co.ke.
+*   - If M-PESA cannot reach your Validation URL within ~8 seconds, it defaults
+*     to the ResponseType action set during registration.
+*
+* @param baseUrl     - Daraja environment base URL
+* @param accessToken - Valid OAuth bearer token from Authorization API
+* @param request     - Registration parameters
+* @returns           - Daraja registration response (ResponseCode "0" = success)
+*/
+async function registerC2BUrls(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(C2BRegisterUrlRequestSchema, request, "C2B Register URL request");
+	validateCallbackUrl(validated.confirmationUrl, "confirmationUrl");
+	validateCallbackUrl(validated.validationUrl, "validationUrl");
+	const version = validated.apiVersion ?? "v2";
+	const payload = {
+		ShortCode: String(validated.shortCode),
+		ResponseType: validated.responseType,
+		ConfirmationURL: validated.confirmationUrl,
+		ValidationURL: validated.validationUrl
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/c2b/${version}/registerurl`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(C2BRegisterUrlResponseSchema, data, "C2B Register URL response");
+}
+
+//#endregion
+//#region src/mpesa/c2b/simulate.ts
+/**
+* src/mpesa/c2b/simulate.ts
+*
+* C2B Simulate implementation (Sandbox ONLY).
+* Strictly aligned with Safaricom Daraja C2B API documentation.
+*
+* Per docs: "NB: Simulation is not supported on production."
+*
+* Endpoint (v2, sandbox only):
+*   POST https://sandbox.safaricom.co.ke/mpesa/c2b/v2/simulate
+*/
+/**
+* Simulates a C2B customer payment. SANDBOX ONLY.
+*
+* Daraja payload shape:
+* {
+*   "ShortCode":     600984,                   ← numeric
+*   "CommandID":     "CustomerPayBillOnline",
+*   "Amount":        1,                        ← numeric, whole number ≥ 1
+*   "Msisdn":        254708374149,             ← numeric
+*   "BillRefNumber": "AccountRef"              ← Paybill only; OMIT for BuyGoods
+* }
+*
+* CRITICAL — BillRefNumber handling (per docs):
+*   "Account reference for Customer paybills and null for customer buy goods"
+*   We omit the key entirely for BuyGoods (not null, not "") because Daraja
+*   validates field presence and rejects even null/empty values for Buy Goods.
+*
+* @param baseUrl     - Must be the sandbox base URL
+* @param accessToken - Valid OAuth bearer token from Authorization API
+* @param request     - Simulation parameters
+* @returns           - Daraja simulate response (ResponseCode "0" = accepted)
+*/
+async function simulateC2B(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(C2BSimulateRequestSchema, request, "C2B Simulate request");
+	if (!baseUrl.includes("sandbox")) throw createError({
+		code: "VALIDATION_ERROR",
+		message: "C2B simulate is only available in the Sandbox environment (per Daraja docs). In production, customers initiate payments directly via M-PESA App, USSD, or SIM Toolkit."
+	});
+	const amount = Math.round(validated.amount);
+	const isBuyGoods = validated.commandId === "CustomerBuyGoodsOnline";
+	const version = validated.apiVersion ?? "v2";
+	const payload = {
+		ShortCode: Number(validated.shortCode),
+		CommandID: validated.commandId,
+		Amount: amount,
+		Msisdn: Number(validated.msisdn)
+	};
+	if (!isBuyGoods) payload["BillRefNumber"] = validated.billRefNumber.trim();
+	const { data } = await httpRequest(`${baseUrl}/mpesa/c2b/${version}/simulate`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(C2BSimulateResponseSchema, data, "C2B Simulate response");
+}
+
+//#endregion
+//#region src/mpesa/c2b/types.ts
+/**
+* Error codes returned by the C2B Register URL API.
+*
+* Note: Multiple error conditions share the code "500.003.1001" —
+* the `errorMessage` field in the response distinguishes them.
+*
+* Per Daraja documentation:
+* - 500.003.1001 → Internal Server Error / URLs already registered / Duplicate notification
+* - 400.003.01   → Invalid Access Token
+* - 400.003.02   → Bad Request (missing or malformed payload)
+* - 500.003.03   → Quota Violation (too many requests)
+* - 500.003.02   → Spike Arrest Violation (endpoint errors causing a traffic spike)
+* - 404.003.01   → Resource Not Found (wrong endpoint URL)
+* - 404.001.04   → Invalid Authenticator Header (used GET instead of POST)
+* - 400.002.05   → Invalid Request Payload (typo or schema mismatch)
+*/
+const C2B_REGISTER_URL_ERROR_CODES = {
+	INTERNAL_SERVER_ERROR: "500.003.1001",
+	INVALID_ACCESS_TOKEN: "400.003.01",
+	BAD_REQUEST: "400.003.02",
+	QUOTA_VIOLATION: "500.003.03",
+	SPIKE_ARREST: "500.003.02",
+	RESOURCE_NOT_FOUND: "404.003.01",
+	INVALID_AUTH_HEADER: "404.001.04",
+	INVALID_REQUEST_PAYLOAD: "400.002.05"
+};
+/**
+* Result codes your ValidationURL must return to M-PESA.
+*
+* Per Daraja documentation:
+*   ResultCode "0"        → Accept the payment
+*   ResultCode "C2B00011" → Reject: Invalid MSISDN
+*   ResultCode "C2B00012" → Reject: Invalid Account Number
+*   ResultCode "C2B00013" → Reject: Invalid Amount
+*   ResultCode "C2B00014" → Reject: Invalid KYC Details
+*   ResultCode "C2B00015" → Reject: Invalid Shortcode
+*   ResultCode "C2B00016" → Reject: Other Error
+*/
+const C2B_VALIDATION_RESULT_CODES = {
+	ACCEPT: "0",
+	INVALID_MSISDN: "C2B00011",
+	INVALID_ACCOUNT_NUMBER: "C2B00012",
+	INVALID_AMOUNT: "C2B00013",
+	INVALID_KYC_DETAILS: "C2B00014",
+	INVALID_SHORTCODE: "C2B00015",
+	OTHER_ERROR: "C2B00016"
+};
+
+//#endregion
+//#region src/mpesa/c2b/webhooks.ts
+/**
+* Returns true if `body` looks like a valid C2B callback payload.
+* Works for both Validation and Confirmation payloads.
+*
+* Checks the minimum required fields from the Daraja docs payload sample:
+*   - TransID
+*   - BusinessShortCode
+*   - TransAmount
+*/
+function isC2BPayload(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	return typeof b["TransID"] === "string" && typeof b["BusinessShortCode"] === "string" && typeof b["TransAmount"] === "string";
+}
+/**
+* Builds an "accept" validation response.
+*
+* Per Daraja docs (to accept the payment):
+*   { "ResultCode": "0", "ResultDesc": "Accepted" }
+*
+* @param thirdPartyTransID - Optional: echo back the ThirdPartyTransID received
+*   in the validation request. M-PESA includes it in the confirmation callback.
+*/
+function acceptC2BValidation(thirdPartyTransID) {
+	return {
+		ResultCode: "0",
+		ResultDesc: "Accepted",
+		...thirdPartyTransID ? { ThirdPartyTransID: thirdPartyTransID } : {}
+	};
+}
+/**
+* Builds a "reject" validation response.
+*
+* Per Daraja docs (to reject the payment):
+*   { "ResultCode": "C2B00011", "ResultDesc": "Rejected" }
+*
+* Documented result codes and their meanings:
+*   C2B00011 — Invalid MSISDN
+*   C2B00012 — Invalid Account Number
+*   C2B00013 — Invalid Amount
+*   C2B00014 — Invalid KYC Details
+*   C2B00015 — Invalid Shortcode
+*   C2B00016 — Other Error (default)
+*
+* @param resultCode - Must NOT be "0". Defaults to "C2B00016" (Other Error).
+*/
+function rejectC2BValidation(resultCode = "C2B00016") {
+	return {
+		ResultCode: resultCode,
+		ResultDesc: "Rejected"
+	};
+}
+/**
+* Builds the confirmation acknowledgement your ConfirmationURL must return.
+* Always respond with ResultCode 0 to acknowledge receipt.
+*
+* Per docs process flow: M-PESA expects an acknowledgement response.
+* Failure to acknowledge may cause M-PESA to retry the confirmation.
+*/
+function acknowledgeC2BConfirmation() {
+	return {
+		ResultCode: 0,
+		ResultDesc: "Success"
+	};
+}
+/**
+* Extracts the transaction amount as a number from a C2B callback payload.
+* TransAmount is a string in the payload (e.g. "10" per docs sample).
+*/
+function getC2BAmount(payload) {
+	return Number(payload.TransAmount);
+}
+/**
+* Extracts the M-PESA transaction ID (receipt) from a C2B callback payload.
+* Example from docs: "RKTQDM7W6S"
+*/
+function getC2BTransactionId(payload) {
+	return payload.TransID;
+}
+/**
+* Extracts the account reference (BillRefNumber) from a C2B callback payload.
+* Example from docs: "invoice008"
+* Empty string for Buy Goods payments (no account reference).
+*/
+function getC2BAccountRef(payload) {
+	return payload.BillRefNumber;
+}
+/**
+* Returns the customer's full name from a C2B callback payload.
+* Joins FirstName, MiddleName, LastName; skips empty parts.
+* Per docs: customer names "can be empty".
+*/
+function getC2BCustomerName(payload) {
+	return [
+		payload.FirstName,
+		payload.MiddleName,
+		payload.LastName
+	].filter(Boolean).join(" ").trim();
+}
+/**
+* Returns true if the payload is a Paybill payment.
+*
+* Per Daraja docs, the callback TransactionType for Paybill is "Pay Bill"
+* (NOT "CustomerPayBillOnline" which is the request CommandID).
+*/
+function isPaybillPayment(payload) {
+	return payload.TransactionType === "Pay Bill";
+}
+/**
+* Returns true if the payload is a Buy Goods (Till) payment.
+*
+* Per Daraja docs, the callback TransactionType for Buy Goods is "Buy Goods"
+* (NOT "CustomerBuyGoodsOnline" which is the request CommandID).
+*/
+function isBuyGoodsPayment(payload) {
+	return payload.TransactionType === "Buy Goods";
+}
+
+//#endregion
+//#region src/mpesa/dynamic-qr/types.ts
+/** All valid QR transaction codes as a readonly tuple — useful for validation. */
+const QR_TRANSACTION_CODES = [
+	"BG",
+	"WA",
+	"PB",
+	"SM",
+	"SB"
+];
+
+//#endregion
+//#region src/mpesa/dynamic-qr/validators.ts
+/** Minimum amount Daraja accepts (whole KES). */
+const MIN_AMOUNT = 1;
+/** Maximum allowable QR size in pixels (sanity guard — Daraja has no documented limit). */
+const MAX_QR_SIZE = 1e3;
+/** Minimum QR size in pixels. */
+const MIN_QR_SIZE = 1;
+/** Default QR size when `size` is omitted from the request. */
+const DEFAULT_QR_SIZE = 300;
+/**
+* Validates `merchantName`.
+* @returns Error message string, or `null` if valid.
+*/
+function validateMerchantName(value) {
+	if (typeof value !== "string" || value.trim().length === 0) return "merchantName is required and must be a non-empty string";
+	return null;
+}
+/**
+* Validates `refNo`.
+* @returns Error message string, or `null` if valid.
+*/
+function validateRefNo(value) {
+	if (typeof value !== "string" || value.trim().length === 0) return "refNo (transaction reference) is required and must be a non-empty string";
+	return null;
+}
+/**
+* Validates `amount`.
+* @returns Error message string, or `null` if valid.
+*/
+function validateAmount(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return "amount must be a finite number";
+	if (Math.round(value) < 1) return `amount must be at least ${1} KES (got ${value})`;
+	return null;
+}
+/**
+* Validates `trxCode`.
+* @returns Error message string, or `null` if valid.
+*/
+function validateTrxCode(value) {
+	if (!QR_TRANSACTION_CODES.includes(value)) return `trxCode must be one of: ${QR_TRANSACTION_CODES.join(", ")} (BG=Buy Goods, WA=Withdraw Cash, PB=Paybill, SM=Send Money, SB=Send to Business)`;
+	return null;
+}
+/**
+* Validates `cpi` (Credit Party Identifier).
+* @returns Error message string, or `null` if valid.
+*/
+function validateCpi(value) {
+	if (typeof value !== "string" || value.trim().length === 0) return "cpi (Credit Party Identifier) is required and must be a non-empty string";
+	return null;
+}
+/**
+* Validates `size` (optional).
+* @returns Error message string, or `null` if valid.
+*/
+function validateSize(value) {
+	if (value === void 0 || value === null) return null;
+	if (typeof value !== "number" || !Number.isFinite(value)) return "size must be a finite number when provided";
+	if (!Number.isInteger(value) || value < 1) return `size must be a positive integer (minimum ${1})`;
+	if (value > 1e3) return `size must not exceed ${MAX_QR_SIZE} pixels (got ${value})`;
+	return null;
+}
+/**
+* Validates a full {@link DynamicQRRequest} payload.
+*
+* Runs all field validators and collects every error so callers receive a
+* complete picture rather than failing on the first error only.
+*
+* Accepts `null`, `undefined`, or any non-object — returns `{ valid: false }`
+* with an appropriate error rather than throwing.
+*
+* @example
+* const result = validateDynamicQRRequest(payload)
+* if (!result.valid) {
+*   console.error(result.errors)
+* }
+*/
+function validateDynamicQRRequest(payload) {
+	if (payload === null || payload === void 0 || typeof payload !== "object") return {
+		valid: false,
+		errors: { payload: "request payload must be a non-null object" }
+	};
+	const p = payload;
+	const errors = {};
+	const merchantNameError = validateMerchantName(p.merchantName);
+	if (merchantNameError) errors["merchantName"] = merchantNameError;
+	const refNoError = validateRefNo(p.refNo);
+	if (refNoError) errors["refNo"] = refNoError;
+	const amountError = validateAmount(p.amount);
+	if (amountError) errors["amount"] = amountError;
+	const trxCodeError = validateTrxCode(p.trxCode);
+	if (trxCodeError) errors["trxCode"] = trxCodeError;
+	const cpiError = validateCpi(p.cpi);
+	if (cpiError) errors["cpi"] = cpiError;
+	const sizeError = validateSize(p.size);
+	if (sizeError) errors["size"] = sizeError;
+	if (Object.keys(errors).length > 0) return {
+		valid: false,
+		errors
+	};
+	return { valid: true };
+}
+
+//#endregion
+//#region src/mpesa/dynamic-qr/generate.ts
+/**
+* src/mpesa/dynamic-qr/generate.ts
+*
+* Core logic for the Safaricom Daraja Dynamic QR Code API.
+*
+* API: POST /mpesa/qrcode/v1/generate
+*
+* Error codes from Daraja docs:
+*   404.001.04 — Invalid Authentication Header
+*   400.002.05 — Invalid Request Payload
+*   400.003.01 — Invalid Access Token
+*/
+/**
+* Maps Daraja-specific error codes to structured PesafyErrors with
+* actionable developer guidance.
+*
+* @internal
+*/
+function mapDarajaError(errorCode, errorMessage) {
+	switch (errorCode) {
+		case "404.001.04": return new PesafyError({
+			code: "AUTH_FAILED",
+			message: `Daraja rejected the request due to an invalid authentication header. Ensure the Dynamic QR endpoint is called with POST and that the Authorization: Bearer <token> header is present. Daraja: "${errorMessage}"`,
+			statusCode: 404
+		});
+		case "400.003.01": return new PesafyError({
+			code: "AUTH_FAILED",
+			message: `The M-PESA access token is invalid or has expired. Call clearTokenCache() on the Mpesa instance to force a token refresh and retry the request. Daraja: "${errorMessage}"`,
+			statusCode: 401
+		});
+		case "400.002.05": return new PesafyError({
+			code: "VALIDATION_ERROR",
+			message: `Daraja rejected the request payload as malformed. Verify that all required fields (MerchantName, RefNo, Amount, TrxCode, CPI, Size) are present and have correct types. Daraja: "${errorMessage}"`,
+			statusCode: 400
+		});
+		default: return new PesafyError({
+			code: "REQUEST_FAILED",
+			message: `Dynamic QR request failed (${errorCode}): ${errorMessage}`,
+			statusCode: 400
+		});
+	}
+}
+/**
+* Returns `true` when the raw response body looks like a Daraja error object.
+* @internal
+*/
+function isDarajaError(body) {
+	return typeof body === "object" && body !== null && "errorCode" in body && typeof body.errorCode === "string";
+}
+/**
+* Returns `true` when the response has the required QR success fields.
+* @internal
+*/
+function isDarajaSuccess(body) {
+	return typeof body === "object" && body !== null && "ResponseCode" in body && "QRCode" in body && typeof body.QRCode === "string" && body.QRCode.length > 0;
+}
+/**
+* Generates a Dynamic M-PESA QR Code via the Safaricom Daraja API.
+*
+* The QR code can be rendered directly in a browser as a base64 PNG:
+* ```html
+* <img src="data:image/png;base64,{response.QRCode}" />
+* ```
+* Or written to disk:
+* ```ts
+* import { writeFileSync } from 'node:fs'
+* writeFileSync('qr.png', Buffer.from(response.QRCode, 'base64'))
+* ```
+*
+* @param baseUrl     - Daraja base URL (`https://sandbox.safaricom.co.ke` or
+*                      `https://api.safaricom.co.ke`)
+* @param accessToken - Valid Daraja OAuth2 Bearer token
+* @param request     - QR generation parameters (see {@link DynamicQRRequest})
+* @returns           - Daraja response including the base64-encoded QR image
+*
+* @throws {PesafyError} `VALIDATION_ERROR`  — payload failed pre-flight checks
+* @throws {PesafyError} `AUTH_FAILED`       — bad/expired token or wrong headers
+* @throws {PesafyError} `REQUEST_FAILED`    — unexpected Daraja error
+*
+* @example
+* ```ts
+* const response = await generateDynamicQR(
+*   'https://sandbox.safaricom.co.ke',
+*   accessToken,
+*   {
+*     merchantName: 'Test Supermarket',
+*     refNo:        'INV-001',
+*     amount:       500,
+*     trxCode:      'BG',
+*     cpi:          '373132',
+*     size:         300,
+*   },
+* )
+* console.log(response.QRCode) // base64 PNG
+* ```
+*/
+async function generateDynamicQR(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(DynamicQRRequestSchema, request, "Dynamic QR request");
+	if (!accessToken || typeof accessToken !== "string" || accessToken.trim().length === 0) throw new PesafyError({
+		code: "AUTH_FAILED",
+		message: "accessToken is required. Obtain one via the Daraja Authorization API (GET /oauth/v1/generate?grant_type=client_credentials)."
+	});
+	const size = validated.size ?? 300;
+	const amount = Math.round(validated.amount);
+	const payload = {
+		MerchantName: validated.merchantName.trim(),
+		RefNo: validated.refNo.trim(),
+		Amount: amount,
+		TrxCode: validated.trxCode,
+		CPI: validated.cpi.trim(),
+		Size: String(size)
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/qrcode/v1/generate`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	if (isDarajaError(data)) throw mapDarajaError(data.errorCode, data.errorMessage);
+	if (!isDarajaSuccess(data)) throw new PesafyError({
+		code: "REQUEST_FAILED",
+		message: `Daraja returned an unexpected response structure for the Dynamic QR request. The response was missing required fields (ResponseCode, QRCode). Raw response: ${JSON.stringify(data).slice(0, 300)}`
+	});
+	return parseWithSchema(DynamicQRResponseSchema, data, "Dynamic QR response");
+}
+
+//#endregion
+//#region src/mpesa/reversal/types.ts
+/**
+* src/mpesa/reversal/types.ts
+*
+* Transaction Reversal types, constants, and helpers.
+*
+* API: POST /mpesa/reversal/v1/request
+*
+* Reverses a completed M-PESA C2B transaction. The API is ASYNCHRONOUS —
+* the synchronous response is only an acknowledgement. The actual reversal
+* result is POSTed to your ResultURL after processing.
+*
+* Required org portal role: "Org Reversals Initiator"
+*
+* Per Daraja docs:
+*   RecieverIdentifierType MUST always be "11" for reversals.
+*   CommandID MUST always be "TransactionReversal".
+*
+* Ref: Reversals — Safaricom Daraja Developer Portal
+*/
+/**
+* CommandID for the Reversals API.
+* Only "TransactionReversal" is allowed per Daraja docs.
+*/
+const REVERSAL_COMMAND_ID = "TransactionReversal";
+/**
+* RecieverIdentifierType for the Reversals API.
+* Per Daraja docs: "Type of Organization (should be '11')".
+* This value is fixed for all reversal requests.
+*/
+const REVERSAL_RECEIVER_IDENTIFIER_TYPE = "11";
+/**
+* Result codes returned in the async callback POSTed to your ResultURL.
+*
+* Per Daraja Reversals documentation:
+*
+* | ResultCode | Meaning                                            |
+* |------------|----------------------------------------------------|
+* | 0          | Success — transaction reversed                     |
+* | 1          | Insufficient balance                               |
+* | 11         | DebitParty in invalid state (shortcode not active) |
+* | 21         | Initiator not allowed to initiate reversals        |
+* | 2001       | Initiator information invalid (bad credentials)    |
+* | 2006       | Declined due to account rule (shortcode inactive)  |
+* | 2028       | Not permitted (shortcode lacks reversal permission)|
+* | 8006       | Security credential locked                         |
+* | R000001    | Transaction already reversed                       |
+* | R000002    | OriginalTransactionID is invalid / does not exist  |
+*/
+const REVERSAL_RESULT_CODES = {
+	SUCCESS: 0,
+	INSUFFICIENT_BALANCE: 1,
+	DEBIT_PARTY_INVALID_STATE: 11,
+	INITIATOR_NOT_ALLOWED: 21,
+	INITIATOR_INFORMATION_INVALID: 2001,
+	DECLINED_ACCOUNT_RULE: 2006,
+	NOT_PERMITTED: 2028,
+	SECURITY_CREDENTIAL_LOCKED: 8006,
+	ALREADY_REVERSED: "R000001",
+	INVALID_TRANSACTION_ID: "R000002"
+};
+/**
+* API-level error codes returned in the synchronous HTTP error response.
+*
+* Per Daraja Reversals error response documentation:
+*
+* | errorCode       | Meaning                                         | HTTP |
+* |-----------------|-------------------------------------------------|------|
+* | 404.001.03      | Invalid Access Token                            | 404  |
+* | 400.002.02      | Bad Request — Invalid payload field             | 400  |
+* | 404.001.01      | Resource not found (wrong endpoint)             | 404  |
+* | 500.001.1001    | Internal Server Error                           | 500  |
+* | 500.003.02      | Spike Arrest Violation (TPS limit exceeded)     | 500  |
+* | 500.003.03      | Quota Violation (API request limit exceeded)    | 500  |
+*/
+const REVERSAL_ERROR_CODES = {
+	INVALID_ACCESS_TOKEN: "404.001.03",
+	BAD_REQUEST: "400.002.02",
+	RESOURCE_NOT_FOUND: "404.001.01",
+	INTERNAL_SERVER_ERROR: "500.001.1001",
+	SPIKE_ARREST: "500.003.02",
+	QUOTA_VIOLATION: "500.003.03"
+};
+/**
+* Returns true when the payload matches the shape of a ReversalResult.
+* Works for both success and failure callbacks.
+*/
+function isReversalResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const r = b["Result"];
+	return typeof r["ResultCode"] !== "undefined" && typeof r["ResultDesc"] === "string" && typeof r["ConversationID"] === "string";
+}
+/**
+* Returns true when the reversal result indicates a successful reversal.
+* A successful reversal has ResultCode === 0 (number).
+*/
+function isReversalSuccess(result) {
+	return result.Result.ResultCode === REVERSAL_RESULT_CODES.SUCCESS;
+}
+/**
+* Returns true when the reversal result indicates a failure.
+*/
+function isReversalFailure(result) {
+	return !isReversalSuccess(result);
+}
+/**
+* Returns true when the specified result code is a known documented code.
+*/
+function isKnownReversalResultCode(code) {
+	return Object.values(REVERSAL_RESULT_CODES).includes(code);
+}
+/**
+* Extracts the M-PESA receipt number for the reversal transaction.
+* Returns null if the result does not contain a TransactionID.
+*/
+function getReversalTransactionId(result) {
+	return result.Result.TransactionID ?? null;
+}
+/**
+* Extracts the ConversationID from the reversal result.
+*/
+function getReversalConversationId(result) {
+	return result.Result.ConversationID;
+}
+/**
+* Extracts the OriginatorConversationID from the reversal result.
+*/
+function getReversalOriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+/**
+* Extracts the ResultCode from the reversal result.
+* Returns 0 for success, or a string/number error code for failure.
+*/
+function getReversalResultCode(result) {
+	return result.Result.ResultCode;
+}
+/**
+* Extracts the ResultDesc from the reversal result.
+*/
+function getReversalResultDesc(result) {
+	return result.Result.ResultDesc;
+}
+/**
+* Extracts a named parameter value from the ResultParameters of a successful
+* reversal callback. Returns undefined if absent or if the reversal failed.
+*
+* @example
+* const amount = getReversalResultParam(result, 'Amount')
+* const origTxId = getReversalResultParam(result, 'OriginalTransactionID')
+*/
+function getReversalResultParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return params.find((p) => p.Key === key)?.Value;
+}
+/**
+* Extracts the reversed transaction amount from a successful reversal callback.
+*/
+function getReversalAmount(result) {
+	const val = getReversalResultParam(result, "Amount");
+	return val !== void 0 ? Number(val) : void 0;
+}
+/**
+* Extracts the original TransactionID that was reversed.
+* This is the M-PESA receipt number of the original C2B transaction.
+*/
+function getReversalOriginalTransactionId(result) {
+	const val = getReversalResultParam(result, "OriginalTransactionID");
+	return val !== void 0 ? String(val) : void 0;
+}
+/**
+* Extracts the CreditPartyPublicName from a successful reversal callback.
+* Format: "254705912645 - NICHOLAS JOHN SONGOK"
+*/
+function getReversalCreditPartyPublicName(result) {
+	const val = getReversalResultParam(result, "CreditPartyPublicName");
+	return val !== void 0 ? String(val) : void 0;
+}
+/**
+* Extracts the DebitPartyPublicName from a successful reversal callback.
+* Format: "600992 - Safaricom Daraja 992"
+*/
+function getReversalDebitPartyPublicName(result) {
+	const val = getReversalResultParam(result, "DebitPartyPublicName");
+	return val !== void 0 ? String(val) : void 0;
+}
+/**
+* Extracts the DebitAccountBalance from a successful reversal callback.
+* Format: "Utility Account|KES|7722179.62|7722179.62|0.00|0.00"
+*/
+function getReversalDebitAccountBalance(result) {
+	const val = getReversalResultParam(result, "DebitAccountBalance");
+	return val !== void 0 ? String(val) : void 0;
+}
+/**
+* Extracts the reversal completion timestamp.
+* Format: YYYYMMDDHHmmss (e.g. 20211114132711)
+*/
+function getReversalCompletedTime(result) {
+	const val = getReversalResultParam(result, "TransCompletedTime");
+	return val !== void 0 ? Number(val) : void 0;
+}
+/**
+* Extracts the Charge from a successful reversal callback.
+* Per docs: usually 0.00 for reversals.
+*/
+function getReversalCharge(result) {
+	const val = getReversalResultParam(result, "Charge");
+	return val !== void 0 ? Number(val) : void 0;
+}
+
+//#endregion
+//#region src/mpesa/reversal/request.ts
+/**
+* src/mpesa/reversal/request.ts
+*
+* Transaction Reversal — reverses a completed M-PESA C2B transaction.
+*
+* API: POST /mpesa/reversal/v1/request
+*
+* ASYNCHRONOUS: The synchronous response is acknowledgement only.
+* The actual reversal result is POSTed to your ResultURL after processing.
+*
+* Per Daraja docs:
+*   - CommandID is always "TransactionReversal"
+*   - RecieverIdentifierType is always "11" (Organisation ShortCode for reversals)
+*   - Amount is sent as a string per the Daraja sample payload
+*   - Remarks must be 2–100 characters
+*   - Cannot be used for B2C reversals (those are done on the M-PESA portal)
+*
+* Required org portal role: "Org Reversals Initiator"
+*/
+async function requestReversal(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(ReversalRequestSchema, request, "Reversal request");
+	const amount = Math.round(validated.amount);
+	const remarks = validated.remarks ?? "Transaction Reversal";
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: REVERSAL_COMMAND_ID,
+		TransactionID: validated.transactionId,
+		Amount: String(amount),
+		ReceiverParty: String(validated.receiverParty),
+		RecieverIdentifierType: "11",
+		ResultURL: validated.resultUrl,
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		Remarks: remarks
+	};
+	if (validated.occasion !== void 0 && validated.occasion !== null) payload["Occasion"] = validated.occasion;
+	const { data } = await httpRequest(`${baseUrl}/mpesa/reversal/v1/request`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(ReversalResponseSchema, data, "Reversal response");
+}
+
+//#endregion
+//#region src/schemas/stk-push.ts
+const TransactionTypeSchema = z.enum(["CustomerPayBillOnline", "CustomerBuyGoodsOnline"]);
+const StkPushRequestSchema = z.object({
+	amount: z.number().finite({ message: "amount must be a finite number (not NaN or Infinity)" }),
+	phoneNumber: NonEmptyStringSchema,
+	shortCode: NonEmptyStringSchema,
+	passKey: NonEmptyStringSchema,
+	callbackUrl: UrlSchema,
+	accountReference: NonEmptyStringSchema,
+	transactionDesc: NonEmptyStringSchema,
+	transactionType: TransactionTypeSchema.optional(),
+	partyB: z.string().optional()
+});
+const StkPushResponseSchema = z.object({
+	MerchantRequestID: z.string(),
+	CheckoutRequestID: z.string(),
+	ResponseCode: z.string(),
+	ResponseDescription: z.string(),
+	CustomerMessage: z.string().optional()
+}).passthrough();
+const StkQueryRequestSchema = z.object({
+	checkoutRequestId: NonEmptyStringSchema,
+	shortCode: NonEmptyStringSchema,
+	passKey: NonEmptyStringSchema
+});
+const StkQueryResponseSchema = z.object({
+	ResponseCode: z.string(),
+	ResponseDescription: z.string(),
+	MerchantRequestID: z.string().optional(),
+	CheckoutRequestID: z.string().optional(),
+	ResultCode: z.union([z.string(), z.number()]).optional(),
+	ResultDesc: z.string().optional()
+}).passthrough();
+const StkPushWebhookSchema = z.object({ Body: z.object({ stkCallback: z.object({
+	MerchantRequestID: z.string(),
+	CheckoutRequestID: z.string(),
+	ResultCode: z.number(),
+	ResultDesc: z.string(),
+	CallbackMetadata: z.object({ Item: z.array(z.object({
+		Name: z.string(),
+		Value: z.union([z.string(), z.number()])
+	})) }).optional()
+}).passthrough() }) });
+
+//#endregion
+//#region src/mpesa/stk-push/types.ts
+/**
+* M-PESA transaction limits as documented by Safaricom Daraja.
+*
+* | Limit            | Value      |
+* |------------------|-----------|
+* | Min per tx       | KES 1     |
+* | Max per tx       | KES 250 000|
+* | Max daily        | KES 500 000|
+* | Max balance      | KES 500 000|
+*/
+const STK_PUSH_LIMITS = {
+	MIN_AMOUNT: 1,
+	MAX_AMOUNT: 25e4
+};
+/**
+* All documented STK Push / Query result codes.
+*
+* These codes appear in:
+*   - STK Query response  → `ResultCode` field
+*   - STK Callback body   → `Body.stkCallback.ResultCode`
+*
+* | Code | Meaning                  |
+* |------|--------------------------|
+* |    0 | Transaction successful   |
+* |    1 | Insufficient balance     |
+* | 1032 | Cancelled by user        |
+* | 1037 | Phone unreachable        |
+* | 2001 | Invalid PIN              |
+*/
+const STK_RESULT_CODES = {
+	SUCCESS: 0,
+	INSUFFICIENT_BALANCE: 1,
+	CANCELLED_BY_USER: 1032,
+	PHONE_UNREACHABLE: 1037,
+	INVALID_PIN: 2001
+};
+/**
+* Returns true when `code` is one of the documented STK result codes.
+* Useful for narrowing unknown values from the Daraja response.
+*/
+function isKnownStkResultCode(code) {
+	return Object.values(STK_RESULT_CODES).includes(code);
+}
+/**
+* Narrows `StkCallbackInner` to the success shape.
+* A callback is successful when `ResultCode === 0`.
+*
+* @example
+* if (isStkCallbackSuccess(callback.Body.stkCallback)) {
+*   const receipt = getCallbackValue(callback, 'MpesaReceiptNumber')
+* }
+*/
+function isStkCallbackSuccess(cb) {
+	return cb.ResultCode === STK_RESULT_CODES.SUCCESS;
+}
+/**
+* Extracts a named value from a successful callback's metadata.
+* Returns `undefined` if the key is absent or the transaction failed.
+*
+* @example
+* const receipt = getCallbackValue(callback, 'MpesaReceiptNumber') // "NLJ7RT61SV"
+* const amount  = getCallbackValue(callback, 'Amount')              // 1
+* const phone   = getCallbackValue(callback, 'PhoneNumber')         // 254708374149
+* const date    = getCallbackValue(callback, 'TransactionDate')     // 20191219102115
+*/
+function getCallbackValue(callback, name) {
+	const inner = callback.Body.stkCallback;
+	if (!isStkCallbackSuccess(inner)) return void 0;
+	return inner.CallbackMetadata.Item.find((i) => i.Name === name)?.Value;
+}
+
+//#endregion
+//#region src/utils/phone/index.ts
+/** Normalises any common Kenyan phone format to 254XXXXXXXXX (12 digits) */
+function formatSafaricomPhone(phone) {
+	const digits = phone.replace(/\D/g, "");
+	let n;
+	if (digits.startsWith("254") && digits.length === 12) n = digits;
+	else if (digits.startsWith("0") && digits.length === 10) n = `254${digits.slice(1)}`;
+	else if (digits.length === 9) n = `254${digits}`;
+	else throw new PesafyError({
+		code: "INVALID_PHONE",
+		message: `Cannot parse "${phone}". Use 07XXXXXXXX, 2547XXXXXXXX, 2541XXXXXXXX (Airtel), or +2547XXXXXXXX.`
+	});
+	/* v8 ignore next 6 -- unreachable: all branches above assign exactly 12 digits */
+	if (n.length !== 12) throw new PesafyError({
+		code: "INVALID_PHONE",
+		message: `"${phone}" normalised to "${n}" — expected 12 digits.`
+	});
+	return n;
+}
+
+//#endregion
+//#region src/mpesa/stk-push/utils.ts
+/**
+* Generates the STK Push password.
+* Formula: Base64( Shortcode + Passkey + Timestamp )
+*
+* Uses btoa() — works in Node.js ≥18, Bun, browsers, and edge runtimes.
+*/
+function getStkPushPassword(shortCode, passKey, timestamp) {
+	return btoa(`${shortCode}${passKey}${timestamp}`);
+}
+/**
+* Returns a Daraja-compatible timestamp: YYYYMMDDHHmmss
+*
+* Call this ONCE per request and reuse the result.
+*/
+function getTimestamp() {
+	const now = /* @__PURE__ */ new Date();
+	const pad = (n) => n.toString().padStart(2, "0");
+	return [
+		now.getFullYear(),
+		pad(now.getMonth() + 1),
+		pad(now.getDate()),
+		pad(now.getHours()),
+		pad(now.getMinutes()),
+		pad(now.getSeconds())
+	].join("");
+}
+
+//#endregion
+//#region src/mpesa/stk-push/stk-push.ts
+/**
+* src/mpesa/stk-push/stk-push.ts
+*
+* Initiates an STK Push (M-PESA Express) payment.
+*
+* Daraja endpoint: POST /mpesa/stkpush/v1/processrequest
+*
+* Transaction limits (Daraja docs):
+*   Min per transaction: KES 1
+*   Max per transaction: KES 250,000
+*/
+async function processStkPush(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(StkPushRequestSchema, request, "STK Push request");
+	if (!Number.isFinite(validated.amount)) throw new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `amount must be a finite number (got ${validated.amount}).`
+	});
+	const amount = Math.round(validated.amount);
+	if (amount < STK_PUSH_LIMITS.MIN_AMOUNT) throw new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `Amount must be at least KES ${STK_PUSH_LIMITS.MIN_AMOUNT} (got ${validated.amount} which rounds to ${amount}).`
+	});
+	if (amount > STK_PUSH_LIMITS.MAX_AMOUNT) throw new PesafyError({
+		code: "VALIDATION_ERROR",
+		message: `Amount must not exceed KES ${STK_PUSH_LIMITS.MAX_AMOUNT.toLocaleString()} per transaction as per Safaricom Daraja limits (got ${validated.amount} which rounds to ${amount}).`
+	});
+	const timestamp = getTimestamp();
+	const partyB = validated.partyB ?? validated.shortCode;
+	const body = {
+		BusinessShortCode: validated.shortCode,
+		Password: getStkPushPassword(validated.shortCode, validated.passKey, timestamp),
+		Timestamp: timestamp,
+		TransactionType: validated.transactionType ?? "CustomerPayBillOnline",
+		Amount: amount,
+		PartyA: formatSafaricomPhone(validated.phoneNumber),
+		PartyB: partyB,
+		PhoneNumber: formatSafaricomPhone(validated.phoneNumber),
+		CallBackURL: validated.callbackUrl,
+		AccountReference: validated.accountReference.slice(0, 12),
+		TransactionDesc: validated.transactionDesc.slice(0, 13)
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/stkpush/v1/processrequest`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body,
+		retries: 5,
+		retryDelay: 3e3
+	}, http));
+	return parseWithSchema(StkPushResponseSchema, data, "STK Push response");
+}
+
+//#endregion
+//#region src/mpesa/stk-push/stk-query.ts
+async function queryStkPush(baseUrl, accessToken, request, http) {
+	const validated = parseWithSchema(StkQueryRequestSchema, request, "STK Query request");
+	const timestamp = getTimestamp();
+	const body = {
+		BusinessShortCode: validated.shortCode,
+		Password: getStkPushPassword(validated.shortCode, validated.passKey, timestamp),
+		Timestamp: timestamp,
+		CheckoutRequestID: validated.checkoutRequestId
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/stkpushquery/v1/query`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body
+	}, http));
+	return parseWithSchema(StkQueryResponseSchema, data, "STK Query response");
+}
+
+//#endregion
+//#region src/mpesa/tax-remittance/remit-tax.ts
+/** KRA's M-PESA shortcode — the only allowed PartyB for tax remittance */
+const KRA_SHORTCODE = "572572";
+/** The only CommandID accepted by the Tax Remittance API */
+const TAX_COMMAND_ID = "PayTaxToKRA";
+/**
+* Remits tax to Kenya Revenue Authority (KRA) via M-PESA.
+*
+* Endpoint: POST /mpesa/b2b/v1/remittax
+*
+* @param baseUrl            - Daraja base URL (sandbox or production)
+* @param accessToken        - Valid OAuth bearer token
+* @param securityCredential - RSA-encrypted initiator password (base64)
+* @param initiatorName      - M-PESA org portal API operator username
+* @param request            - Tax remittance parameters
+* @returns                  - Daraja synchronous acknowledgement response
+*
+* @example
+* const response = await remitTax(
+*   'https://sandbox.safaricom.co.ke',
+*   accessToken,
+*   securityCredential,
+*   'TaxPayer',
+*   {
+*     amount:           239,
+*     partyA:           '888880',
+*     accountReference: '353353',
+*     resultUrl:        'https://example.org/b2b/remittax/result/',
+*     queueTimeOutUrl:  'https://example.org/b2b/remittax/queue/',
+*   },
+* )
+*/
+async function remitTax(baseUrl, accessToken, securityCredential, initiatorName, request, http) {
+	const validated = parseWithSchema(TaxRemittanceRequestSchema, request, "Tax Remittance request");
+	const amount = Math.round(validated.amount);
+	const payload = {
+		Initiator: initiatorName,
+		SecurityCredential: securityCredential,
+		CommandID: TAX_COMMAND_ID,
+		SenderIdentifierType: "4",
+		RecieverIdentifierType: "4",
+		Amount: String(amount),
+		PartyA: String(validated.partyA),
+		PartyB: validated.partyB ?? "572572",
+		AccountReference: validated.accountReference,
+		Remarks: validated.remarks ?? "Tax Remittance",
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		ResultURL: validated.resultUrl
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/b2b/v1/remittax`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${accessToken}` },
+		body: payload
+	}, http));
+	return parseWithSchema(TaxRemittanceResponseSchema, data, "Tax Remittance response");
+}
+
+//#endregion
+//#region src/mpesa/tax-remittance/webhooks.ts
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normaliseResultCode(code) {
+	return typeof code === "string" ? Number(code) : code;
+}
+/**
+* Returns `true` when the value is a valid Tax Remittance async result payload
+* (the shape POSTed by Safaricom to your ResultURL).
+*
+* Checks the minimum required fields per the Daraja documentation:
+*   - Result.ResultCode
+*   - Result.ConversationID
+*   - Result.OriginatorConversationID
+*/
+function isTaxRemittanceResult(value) {
+	if (!isObject(value)) return false;
+	const root = value;
+	if (!isObject(root["Result"])) return false;
+	const result = root["Result"];
+	return result["ResultCode"] !== void 0 && result["ResultCode"] !== null && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+/**
+* Returns `true` when the Tax Remittance result indicates a successful
+* transaction — i.e. ResultCode is 0 or "0".
+*/
+function isTaxRemittanceSuccess(result) {
+	return normaliseResultCode(result.Result.ResultCode) === 0;
+}
+/**
+* Returns `true` when the Tax Remittance result indicates a failure
+* — i.e. ResultCode is non-zero.
+*
+* `isTaxRemittanceSuccess` and `isTaxRemittanceFailure` are mutually exclusive.
+*/
+function isTaxRemittanceFailure(result) {
+	return !isTaxRemittanceSuccess(result);
+}
+/**
+* Extracts a single value from the Result's ResultParameter collection.
+*
+* Handles both the array form and the single-object form that Daraja may return.
+* Returns `undefined` when the key is not found or ResultParameters is absent.
+*
+* Documented result parameter keys:
+*   - `Amount`
+*   - `TransactionCompletedTime`
+*   - `ReceiverPartyPublicName`
+*/
+function getTaxResultParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (params === void 0 || params === null) return void 0;
+	if (Array.isArray(params)) return params.find((p) => p.Key === key)?.Value;
+	const single = params;
+	return single.Key === key ? single.Value : void 0;
+}
+/**
+* Returns the ResultCode as-is (string or number) from the result payload.
+*/
+function getTaxResultCode(result) {
+	return result.Result.ResultCode;
+}
+/**
+* Returns the ResultDesc from the result payload.
+*/
+function getTaxResultDesc(result) {
+	return result.Result.ResultDesc;
+}
+/**
+* Returns the TransactionID (M-PESA receipt number) from the result payload.
+*/
+function getTaxTransactionId(result) {
+	return result.Result.TransactionID;
+}
+/**
+* Returns the ConversationID from the result payload.
+*/
+function getTaxConversationId(result) {
+	return result.Result.ConversationID;
+}
+/**
+* Returns the OriginatorConversationID from the result payload.
+*/
+function getTaxOriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+/**
+* Returns the remitted Amount as a number, or `null` when ResultParameters
+* is absent (e.g. on failure callbacks).
+*
+* Documented key: `Amount` — Daraja returns it as a string like "190.00".
+*/
+function getTaxAmount(result) {
+	const raw = getTaxResultParam(result, "Amount");
+	if (raw === void 0 || raw === null) return null;
+	const parsed = typeof raw === "number" ? raw : parseFloat(String(raw));
+	return Number.isNaN(parsed) ? null : parsed;
+}
+/**
+* Returns the TransactionCompletedTime string from ResultParameters,
+* or `null` when absent.
+*
+* Documented key: `TransactionCompletedTime` — format e.g. "20221110110717".
+*/
+function getTaxCompletedTime(result) {
+	const raw = getTaxResultParam(result, "TransactionCompletedTime");
+	return raw !== void 0 ? String(raw) : null;
+}
+/**
+* Returns the ReceiverPartyPublicName from ResultParameters, or `null` when absent.
+*
+* Documented key: `ReceiverPartyPublicName` — e.g. "00000 Tax Collecting Company".
+*/
+function getTaxReceiverName(result) {
+	const raw = getTaxResultParam(result, "ReceiverPartyPublicName");
+	return raw !== void 0 ? String(raw) : null;
+}
+
+//#endregion
+//#region src/mpesa/transaction-status/query.ts
+/**
+* Transaction Status Query implementation
+*
+* API: POST /mpesa/transactionstatus/v1/query
+*
+* This is ASYNCHRONOUS. The synchronous response only acknowledges receipt.
+* Final results arrive via POST to your ResultURL.
+*
+* Required M-PESA org portal role: "Transaction Status query ORG API"
+*
+* Reconciliation options (at least one required):
+*   - transactionId          — M-Pesa Receipt Number (e.g. "NEF61H8J60")
+*   - originalConversationId — OriginatorConversationID from the original call
+*/
+async function queryTransactionStatus(baseUrl, token, securityCredential, initiator, request, http) {
+	const validated = parseWithSchema(TransactionStatusRequestSchema, request, "Transaction Status request");
+	const payload = {
+		Initiator: initiator,
+		SecurityCredential: securityCredential,
+		CommandID: validated.commandId ?? "TransactionStatusQuery",
+		TransactionID: validated.transactionId ?? "",
+		OriginalConversationID: validated.originalConversationId ?? "",
+		PartyA: validated.partyA,
+		IdentifierType: validated.identifierType,
+		ResultURL: validated.resultUrl,
+		QueueTimeOutURL: validated.queueTimeOutUrl,
+		Remarks: validated.remarks ?? "Transaction Status Query",
+		Occasion: validated.occasion ?? ""
+	};
+	const { data } = await httpRequest(`${baseUrl}/mpesa/transactionstatus/v1/query`, withDarajaHttp({
+		method: "POST",
+		headers: { Authorization: `Bearer ${token}` },
+		body: payload
+	}, http));
+	return parseWithSchema(TransactionStatusResponseSchema, data, "Transaction Status response");
+}
+
+//#endregion
+//#region src/mpesa/transaction-status/types.ts
+/**
+* Daraja Transaction Status API error codes.
+* Returned in the errorCode field of error response bodies.
+*
+* @see https://developer.safaricom.co.ke/APIs/TransactionStatus
+*/
+const TRANSACTION_STATUS_ERROR_CODES = {
+	INVALID_ACCESS_TOKEN: "400.003.01",
+	BAD_REQUEST: "400.003.02",
+	INTERNAL_SERVER_ERROR: "500.003.1001",
+	QUOTA_VIOLATION: "500.003.03",
+	SPIKE_ARREST: "500.003.02",
+	NOT_FOUND: "404.003.01",
+	INVALID_AUTH_HEADER: "404.001.04",
+	INVALID_PAYLOAD: "400.002.05"
+};
+/**
+* Documented result codes for the Transaction Status async callback.
+* ResultCode 0 = success; anything else is a failure.
+*/
+const TRANSACTION_STATUS_RESULT_CODES = {
+	SUCCESS: 0,
+	INVALID_INITIATOR: 2001
+};
+
+//#endregion
+//#region src/mpesa/transaction-status/webhooks.ts
+/**
+* Type guards and payload extractors for Transaction Status result callbacks.
+*
+* Documented result parameters (POSTed to your ResultURL):
+*   - DebitPartyName
+*   - TransactionStatus
+*   - Amount
+*   - ReceiptNo
+*   - DebitAccountBalance
+*   - TransactionDate
+*   - CreditPartyName
+*
+* Docs note: ResultCode is 0 (number) on success. Daraja may return either
+* a number or a string depending on the transaction type — both forms handled.
+*
+* @see https://developer.safaricom.co.ke/APIs/TransactionStatus
+*/
+const KNOWN_RESULT_CODES = new Set(Object.values(TRANSACTION_STATUS_RESULT_CODES));
+/**
+* Runtime type guard — checks if a body looks like a Transaction Status
+* result callback. Validates the minimum documented structure.
+*/
+function isTransactionStatusResult(body) {
+	if (!body || typeof body !== "object") return false;
+	const b = body;
+	if (!b["Result"] || typeof b["Result"] !== "object") return false;
+	const result = b["Result"];
+	return (typeof result["ResultCode"] === "number" || typeof result["ResultCode"] === "string") && typeof result["ConversationID"] === "string" && typeof result["OriginatorConversationID"] === "string";
+}
+/**
+* Returns true if the Transaction Status result represents a successful query.
+* Handles both string "0" and number 0 (Daraja inconsistency).
+*/
+function isTransactionStatusSuccess(result) {
+	const code = result.Result.ResultCode;
+	return code === 0 || code === "0";
+}
+/**
+* Returns true if the Transaction Status result represents a failure.
+*/
+function isTransactionStatusFailure(result) {
+	return !isTransactionStatusSuccess(result);
+}
+/**
+* Returns true if the result code is among the documented codes.
+* Handles both numeric and string representations.
+*/
+function isKnownTransactionStatusResultCode(code) {
+	if (typeof code !== "number" && typeof code !== "string") return false;
+	if (typeof code === "string" && code.trim() === "") return false;
+	const numeric = Number(code);
+	return Number.isFinite(numeric) && KNOWN_RESULT_CODES.has(numeric);
+}
+/**
+* Extracts the M-PESA transaction ID from a Transaction Status result.
+*/
+function getTransactionStatusTransactionId(result) {
+	return result.Result.TransactionID;
+}
+/**
+* Extracts the ConversationID from a Transaction Status result.
+*/
+function getTransactionStatusConversationId(result) {
+	return result.Result.ConversationID;
+}
+/**
+* Extracts the OriginatorConversationID from a Transaction Status result.
+* Use this to correlate with the original API call response.
+*/
+function getTransactionStatusOriginatorConversationId(result) {
+	return result.Result.OriginatorConversationID;
+}
+/**
+* Extracts the human-readable result description.
+*/
+function getTransactionStatusResultDesc(result) {
+	return result.Result.ResultDesc;
+}
+/**
+* Extracts the result code from a Transaction Status result.
+*/
+function getTransactionStatusResultCode(result) {
+	return result.Result.ResultCode;
+}
+/**
+* Extracts the transaction amount from result parameters.
+* Documented field: "Amount"
+* Returns null if not present (e.g. on failure).
+*/
+function getTransactionStatusAmount(result) {
+	const value = getTransactionStatusResultParam(result, "Amount");
+	if (value === void 0) return null;
+	const num = Number(value);
+	return Number.isFinite(num) ? num : null;
+}
+/**
+* Extracts the M-Pesa receipt number from result parameters.
+* Documented field: "ReceiptNo"
+* Returns null if not present.
+*/
+function getTransactionStatusReceiptNo(result) {
+	const value = getTransactionStatusResultParam(result, "ReceiptNo");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the transaction status string from result parameters.
+* Documented field: "TransactionStatus" — e.g. "Completed"
+* Returns null if not present.
+*/
+function getTransactionStatusStatus(result) {
+	const value = getTransactionStatusResultParam(result, "TransactionStatus");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the debit party name from result parameters.
+* Documented field: "DebitPartyName" — e.g. "600310 Safaricom333"
+* Returns null if not present.
+*/
+function getTransactionStatusDebitPartyName(result) {
+	const value = getTransactionStatusResultParam(result, "DebitPartyName");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the credit party name from result parameters.
+* Documented field: "CreditPartyName"
+* Returns null if not present.
+*/
+function getTransactionStatusCreditPartyName(result) {
+	const value = getTransactionStatusResultParam(result, "CreditPartyName");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the debit account balance from result parameters.
+* Documented field: "DebitAccountBalance"
+* Returns null if not present.
+*/
+function getTransactionStatusDebitAccountBalance(result) {
+	const value = getTransactionStatusResultParam(result, "DebitAccountBalance");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts the transaction date from result parameters.
+* Documented field: "TransactionDate"
+* Returns null if not present.
+*/
+function getTransactionStatusTransactionDate(result) {
+	const value = getTransactionStatusResultParam(result, "TransactionDate");
+	if (value === void 0) return null;
+	return String(value);
+}
+/**
+* Extracts a named value from Transaction Status result parameters.
+* Handles both single-object and array forms of ResultParameter
+* (Daraja returns either depending on how many parameters are present).
+* Returns undefined if key is absent or no ResultParameters exist.
+*/
+function getTransactionStatusResultParam(result, key) {
+	const params = result.Result.ResultParameters?.ResultParameter;
+	if (!params) return void 0;
+	return (Array.isArray(params) ? params : [params]).find((p) => p.Key === key)?.Value;
+}
+
+//#endregion
+//#region src/mpesa/types.ts
+const DARAJA_BASE_URLS = {
+	sandbox: "https://sandbox.safaricom.co.ke",
+	production: "https://api.safaricom.co.ke"
+};
+
+//#endregion
+//#region src/mpesa/webhooks/retry.ts
+const DEFAULT_OPTIONS = {
+	maxRetries: Infinity,
+	initialDelay: 1e3,
+	maxDelay: 36e5,
+	backoffMultiplier: 2,
+	maxRetryDuration: 720 * 60 * 60 * 1e3
+};
+/**
+* Retries `fn` with exponential backoff until it resolves, or limits are hit.
+*
+* `maxRetries` = number of *retries* after the first attempt.
+*   0 → one attempt total, no retries
+*   N → up to N+1 attempts total
+*/
+async function retryWithBackoff(fn, options = {}) {
+	const opts = {
+		...DEFAULT_OPTIONS,
+		...options
+	};
+	let delay = opts.initialDelay;
+	let attempts = 0;
+	const startTime = Date.now();
+	while (attempts <= opts.maxRetries) {
+		attempts++;
+		if (Date.now() - startTime > opts.maxRetryDuration) return {
+			success: false,
+			attempts,
+			error: /* @__PURE__ */ new Error("Max retry duration exceeded")
+		};
+		try {
+			return {
+				success: true,
+				data: await fn(),
+				attempts
+			};
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
+			if (err.message.includes("4")) return {
+				success: false,
+				attempts,
+				error: err
+			};
+			if (attempts <= opts.maxRetries) {
+				await new Promise((resolve) => setTimeout(resolve, delay));
+				delay = Math.min(delay * opts.backoffMultiplier, opts.maxDelay);
+			}
+		}
+	}
+	return {
+		success: false,
+		attempts,
+		error: /* @__PURE__ */ new Error("Max retries exceeded")
+	};
+}
+
+//#endregion
+//#region src/mpesa/webhooks/hmac-verifier.ts
+/** Default algorithm until Safaricom documents the official scheme. */
+const DEFAULT_WEBHOOK_HMAC_ALGORITHM = "sha256";
+const ALGO_MAP = {
+	sha256: "SHA-256",
+	sha512: "SHA-512"
+};
+function hexToBytes(hex) {
+	const trimmed = hex.trim();
+	if (!/^[0-9a-fA-F]+$/.test(trimmed) || trimmed.length % 2 !== 0) return null;
+	const bytes = new Uint8Array(trimmed.length / 2);
+	for (let i = 0; i < bytes.length; i++) bytes[i] = Number.parseInt(trimmed.slice(i * 2, i * 2 + 2), 16);
+	return bytes;
+}
+function bytesToHex(bytes) {
+	return [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Constant-time comparison for equal-length byte arrays. */
+function timingSafeEqualBytes(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+	return diff === 0;
+}
+/**
+* Verify webhook HMAC signature (preview — opt-in until Safaricom publishes spec).
+* Uses Web Crypto (`globalThis.crypto.subtle`) for Node, Bun, Deno, and Workers.
+*/
+async function verifyWebhookHMAC(payload, signature, secret, algorithm = DEFAULT_WEBHOOK_HMAC_ALGORITHM) {
+	if (!secret || !signature) return false;
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) return false;
+	const body = typeof payload === "string" ? new TextEncoder().encode(payload) : payload instanceof Uint8Array ? payload : new Uint8Array(payload);
+	const sigBytes = hexToBytes(signature);
+	if (!sigBytes) return false;
+	try {
+		const key = await subtle.importKey("raw", new TextEncoder().encode(secret), {
+			name: "HMAC",
+			hash: ALGO_MAP[algorithm]
+		}, false, ["sign"]);
+		const expected = hexToBytes(bytesToHex(await subtle.sign("HMAC", key, body)));
+		if (!expected) return false;
+		return timingSafeEqualBytes(sigBytes, expected);
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/mpesa/webhooks/signature-verifier.ts
+/**
+* Webhook verification utilities
+*
+* Daraja does NOT use HMAC webhook signatures like Stripe.
+* Instead, verify that callbacks come from whitelisted Safaricom IPs.
+*
+* Official Safaricom IP whitelist (from Getting Started docs):
+*   196.201.214.200
+*   196.201.214.206
+*   196.201.213.114
+*   196.201.214.207
+*   196.201.214.208
+*   196.201.213.44
+*   196.201.212.127
+*   196.201.212.138
+*   196.201.212.129
+*   196.201.212.136
+*   196.201.212.74
+*   196.201.212.69
+*/
+/** Official Safaricom API Gateway IP addresses */
+const SAFARICOM_IPS = [
+	"196.201.214.200",
+	"196.201.214.206",
+	"196.201.213.114",
+	"196.201.214.207",
+	"196.201.214.208",
+	"196.201.213.44",
+	"196.201.212.127",
+	"196.201.212.138",
+	"196.201.212.129",
+	"196.201.212.136",
+	"196.201.212.74",
+	"196.201.212.69"
+];
+/**
+* Returns true if requestIP is in the allowed list.
+* Defaults to the official Safaricom IP whitelist.
+*/
+function verifyWebhookIP(requestIP, allowedIPs = SAFARICOM_IPS) {
+	return allowedIPs.includes(requestIP);
+}
+/**
+* Parses and validates an STK Push webhook body.
+* Returns the typed payload or null if it doesn't match the expected shape.
+*/
+function parseStkPushWebhook(body) {
+	if (!StkPushWebhookSchema.safeParse(body).success) return null;
+	return body;
+}
+/**
+* Combined webhook verification: IP allowlist (default) + optional HMAC.
+*/
+async function verifyWebhook(options) {
+	const errors = [];
+	const allowed = options.allowedIPs ?? SAFARICOM_IPS;
+	const ipValid = options.skipIPCheck === true || verifyWebhookIP(options.requestIP, allowed);
+	if (!ipValid) errors.push("Request IP is not in the Safaricom allowlist.");
+	let hmacValid = true;
+	if (options.secret && options.signature && options.rawBody !== void 0) {
+		hmacValid = await verifyWebhookHMAC(options.rawBody, options.signature, options.secret, options.hmacAlgorithm);
+		if (!hmacValid) errors.push("Webhook HMAC signature verification failed.");
+	} else if (options.requireHMAC) {
+		hmacValid = false;
+		errors.push("HMAC verification required but secret, signature, or rawBody missing.");
+	}
+	return {
+		valid: ipValid && hmacValid,
+		ipValid,
+		hmacValid,
+		errors
+	};
+}
+
+//#endregion
+//#region src/mpesa/webhooks/webhook-handler.ts
+/**
+* High-level webhook event handler
+*/
+/**
+* Parses and validates an inbound Daraja webhook payload.
+*
+* @example
+* // Express route
+* app.post("/mpesa/callback", (req, res) => {
+*   const result = handleWebhook(req.body, { requestIP: req.ip });
+*   if (!result.success) return res.status(400).json({ error: result.error });
+*   // process result.data (StkPushWebhook)
+*   res.json({ ResultCode: 0, ResultDesc: "Accepted" });
+* });
+*/
+function handleWebhook(body, options = {}) {
+	if (!options.skipIPCheck && options.requestIP) {
+		if (!verifyWebhookIP(options.requestIP, options.allowedIPs)) return {
+			success: false,
+			eventType: null,
+			data: null,
+			error: `IP address ${options.requestIP} is not in the Safaricom whitelist`
+		};
+	}
+	const stkPush = parseStkPushWebhook(body);
+	if (stkPush) return {
+		success: true,
+		eventType: "stk_push",
+		data: stkPush
+	};
+	return {
+		success: false,
+		eventType: null,
+		data: null,
+		error: "Unknown or malformed webhook payload"
+	};
+}
+/** Extracts the M-Pesa receipt number from a successful STK Push callback */
+function extractTransactionId(webhook) {
+	const item = (webhook.Body?.stkCallback?.CallbackMetadata?.Item)?.find((i) => i.Name === "MpesaReceiptNumber");
+	return item ? String(item.Value) : null;
+}
+/** Extracts the transaction amount from a successful STK Push callback */
+function extractAmount(webhook) {
+	const item = (webhook.Body?.stkCallback?.CallbackMetadata?.Item)?.find((i) => i.Name === "Amount");
+	return item ? Number(item.Value) : null;
+}
+/** Extracts the phone number from a successful STK Push callback */
+function extractPhoneNumber(webhook) {
+	const item = (webhook.Body?.stkCallback?.CallbackMetadata?.Item)?.find((i) => i.Name === "PhoneNumber");
+	return item ? String(item.Value) : null;
+}
+/** Returns true if the STK Push callback represents a successful transaction */
+function isSuccessfulCallback(webhook) {
+	return webhook.Body?.stkCallback?.ResultCode === 0;
+}
+
+//#endregion
+//#region src/mpesa/index.ts
+/**
+* src/mpesa/index.ts
+*
+* Primary M-PESA module entry point.
+*
+* Exports:
+*   1. Mpesa class — the main SDK client
+*   2. All submodule APIs, types, constants, and helpers
+*
+* Submodules re-exported here:
+*   - account-balance
+*   - b2b-buy-goods
+*   - b2b-express-checkout
+*   - b2b-pay-bill
+*   - b2c (Account Top Up)
+*   - b2c-disbursement
+*   - bill-manager
+*   - c2b
+*   - dynamic-qr
+*   - reversal
+*   - stk-push
+*   - tax-remittance
+*   - transaction-status
+*   - webhooks
+*/
+var Mpesa = class {
+	config;
+	tokenManager;
+	baseUrl;
+	idempotencyManager;
+	constructor(config) {
+		if (!config.consumerKey || !config.consumerSecret) throw new PesafyError({
+			code: "INVALID_CREDENTIALS",
+			message: "consumerKey and consumerSecret are required."
+		});
+		this.config = config;
+		this.baseUrl = DARAJA_BASE_URLS[config.environment];
+		this.tokenManager = new TokenManager(config.consumerKey, config.consumerSecret, this.baseUrl);
+		this.idempotencyManager = new IdempotencyManager(config.idempotency);
+	}
+	/** Idempotency options passed to all outbound Daraja HTTP calls. */
+	darajaHttp() {
+		return { idempotency: this.idempotencyManager };
+	}
+	getToken() {
+		return this.tokenManager.getAccessToken();
+	}
+	async buildSecurityCredential() {
+		if (this.config.securityCredential) return this.config.securityCredential;
+		if (!this.config.initiatorPassword) throw new PesafyError({
+			code: "INVALID_CREDENTIALS",
+			message: "Provide securityCredential (pre-encrypted) OR (initiatorPassword + certificatePath/certificatePem)."
+		});
+		let cert;
+		if (this.config.certificatePem) cert = this.config.certificatePem;
+		else if (this.config.certificatePath) cert = await readFile(this.config.certificatePath, "utf-8");
+		else throw new PesafyError({
+			code: "INVALID_CREDENTIALS",
+			message: "certificatePath or certificatePem is required to encrypt the initiator password."
+		});
+		return encryptSecurityCredential(this.config.initiatorPassword, cert);
+	}
+	requireInitiator(forApi) {
+		const name = this.config.initiatorName ?? "";
+		if (!name) throw new PesafyError({
+			code: "VALIDATION_ERROR",
+			message: `initiatorName is required for ${forApi}.`
+		});
+		return name;
+	}
+	async stkPushSafe(request) {
+		try {
+			return ok(await this.stkPush(request));
+		} catch (e) {
+			return err(e);
+		}
+	}
+	async accountBalanceSafe(request) {
+		try {
+			return ok(await this.accountBalance(request));
+		} catch (e) {
+			return err(e);
+		}
+	}
+	async stkPush(request) {
+		const shortCode = this.config.lipaNaMpesaShortCode ?? "";
+		const passKey = this.config.lipaNaMpesaPassKey ?? "";
+		if (!shortCode || !passKey) throw new PesafyError({
+			code: "VALIDATION_ERROR",
+			message: "lipaNaMpesaShortCode and lipaNaMpesaPassKey are required for STK Push."
+		});
+		const token = await this.getToken();
+		return processStkPush(this.baseUrl, token, {
+			...request,
+			shortCode,
+			passKey
+		}, this.darajaHttp());
+	}
+	async stkQuery(request) {
+		const shortCode = this.config.lipaNaMpesaShortCode ?? "";
+		const passKey = this.config.lipaNaMpesaPassKey ?? "";
+		if (!shortCode || !passKey) throw new PesafyError({
+			code: "VALIDATION_ERROR",
+			message: "lipaNaMpesaShortCode and lipaNaMpesaPassKey are required for STK Query."
+		});
+		const token = await this.getToken();
+		return queryStkPush(this.baseUrl, token, {
+			...request,
+			shortCode,
+			passKey
+		}, this.darajaHttp());
+	}
+	async transactionStatus(request) {
+		const initiator = this.requireInitiator("Transaction Status");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return queryTransactionStatus(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async accountBalance(request) {
+		const initiator = this.requireInitiator("Account Balance");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return queryAccountBalance(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async reverseTransaction(request) {
+		const initiator = this.requireInitiator("Reversal");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return requestReversal(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async generateDynamicQR(request) {
+		const token = await this.getToken();
+		return generateDynamicQR(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async registerC2BUrls(request) {
+		const token = await this.getToken();
+		return registerC2BUrls(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async simulateC2B(request) {
+		const token = await this.getToken();
+		return simulateC2B(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async remitTax(request) {
+		const initiator = this.requireInitiator("Tax Remittance");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return remitTax(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async b2bExpressCheckout(request) {
+		const token = await this.getToken();
+		return initiateB2BExpressCheckout(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async b2bBuyGoods(request) {
+		const initiator = this.requireInitiator("B2B Buy Goods");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return initiateB2BBuyGoods(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async b2bPayBill(request) {
+		const initiator = this.requireInitiator("B2B Pay Bill");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return initiateB2BPayBill(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async b2cPayment(request) {
+		const initiator = this.requireInitiator("B2C Payment");
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return initiateB2CPayment(this.baseUrl, token, cred, initiator, request, this.darajaHttp());
+	}
+	async b2cDisbursement(request) {
+		const initiator = this.requireInitiator("B2C Disbursement");
+		const req = {
+			...request,
+			originatorConversationId: request.originatorConversationId ?? generateOriginatorConversationId()
+		};
+		const [token, cred] = await Promise.all([this.getToken(), this.buildSecurityCredential()]);
+		return initiateB2CDisbursement(this.baseUrl, token, cred, initiator, req, this.darajaHttp());
+	}
+	async billManagerOptIn(request) {
+		const token = await this.getToken();
+		return billManagerOptIn(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async updateOptIn(request) {
+		const token = await this.getToken();
+		return updateOptIn(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async sendInvoice(request) {
+		const token = await this.getToken();
+		return sendSingleInvoice(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async sendBulkInvoices(request) {
+		const token = await this.getToken();
+		return sendBulkInvoices(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async cancelInvoice(request) {
+		const token = await this.getToken();
+		return cancelInvoice(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async cancelBulkInvoices(request) {
+		const token = await this.getToken();
+		return cancelBulkInvoices(this.baseUrl, token, request, this.darajaHttp());
+	}
+	async reconcilePayment(request) {
+		const token = await this.getToken();
+		return reconcilePayment(this.baseUrl, token, request, this.darajaHttp());
+	}
+	clearTokenCache() {
+		this.tokenManager.clearCache();
+	}
+	get environment() {
+		return this.config.environment;
+	}
+};
+
+//#endregion
+//#region src/schemas/webhooks.ts
+const B2CResultWebhookSchema = z.object({ Result: z.object({
+	ResultType: z.number(),
+	ResultCode: z.number(),
+	ResultDesc: z.string(),
+	OriginatorConversationID: z.string().optional(),
+	ConversationID: z.string().optional(),
+	TransactionID: z.string().optional()
+}) }).passthrough();
+const C2BConfirmationWebhookSchema = z.object({
+	TransID: z.string(),
+	TransAmount: z.union([z.string(), z.number()]),
+	MSISDN: z.string(),
+	BusinessShortCode: z.string()
+}).passthrough();
+
+//#endregion
+export { ACCOUNT_BALANCE_ERROR_CODES, AUTH_ERROR_CODES, AccountBalanceRequestSchema, AccountBalanceResponseSchema, AsyncApiResponseSchema, B2BBuyGoodsRequestSchema, B2BBuyGoodsResponseSchema, B2BExpressCheckoutRequestSchema, B2BExpressCheckoutResponseSchema, B2BPayBillRequestSchema, B2BPayBillResponseSchema, B2BResponseSchema, B2B_BUY_GOODS_ERROR_CODES, B2B_BUY_GOODS_RESULT_CODES, B2B_PAY_BILL_ERROR_CODES, B2B_PAY_BILL_RESULT_CODES, B2B_RESULT_CODES, B2CDisbursementRequestSchema, B2CDisbursementResponseSchema, B2CRequestSchema, B2CResponseSchema, B2CResultWebhookSchema, B2C_DISBURSEMENT_RESULT_CODES, B2C_ERROR_CODES, B2C_RESULT_CODES, BillManagerBulkInvoiceRequestSchema, BillManagerBulkInvoiceResponseSchema, BillManagerCancelBulkInvoiceRequestSchema, BillManagerCancelBulkInvoiceResponseSchema, BillManagerCancelInvoiceRequestSchema, BillManagerCancelInvoiceResponseSchema, BillManagerInvoiceItemSchema, BillManagerOptInRequestSchema, BillManagerOptInResponseSchema, BillManagerReconciliationRequestSchema, BillManagerReconciliationResponseSchema, BillManagerSingleInvoiceRequestSchema, BillManagerSingleInvoiceResponseSchema, BillManagerUpdateOptInRequestSchema, BillManagerUpdateOptInResponseSchema, C2BBaseResponseSchema, C2BConfirmationWebhookSchema, C2BRegisterUrlRequestSchema, C2BRegisterUrlResponseSchema, C2BSimulateRequestSchema, C2BSimulateResponseSchema, C2BValidationWebhookSchema, C2B_REGISTER_URL_ERROR_CODES, C2B_VALIDATION_RESULT_CODES, DARAJA_BASE_URLS, DEFAULT_QR_SIZE, DarajaErrorResponseSchema, DynamicQRRequestSchema, DynamicQRResponseSchema, EnvironmentSchema, IdempotencyManager, InMemoryIdempotencyStore, KRA_SHORTCODE, KesAmountSchema, MAX_QR_SIZE, MIN_AMOUNT, MIN_QR_SIZE, Mpesa, MsisdnSchema, NonEmptyStringSchema, PesafyError, QR_TRANSACTION_CODES, REVERSAL_COMMAND_ID, REVERSAL_ERROR_CODES, REVERSAL_RECEIVER_IDENTIFIER_TYPE, REVERSAL_RESULT_CODES, ReversalRequestSchema, ReversalResponseSchema, SAFARICOM_IPS, STK_PUSH_LIMITS, STK_RESULT_CODES, StkPushRequestSchema, StkPushResponseSchema, StkPushWebhookSchema, StkQueryRequestSchema, StkQueryResponseSchema, TAX_COMMAND_ID, TRANSACTION_STATUS_ERROR_CODES, TRANSACTION_STATUS_RESULT_CODES, TaxRemittanceRequestSchema, TaxRemittanceResponseSchema, TokenManager, TransactionStatusRequestSchema, TransactionStatusResponseSchema, TransactionTypeSchema, UrlSchema, acceptC2BValidation, acknowledgeC2BConfirmation, billManagerOptIn, cancelBulkInvoices, cancelInvoice, createError, encryptSecurityCredential, err, extractAmount, extractPhoneNumber, extractTransactionId, formatSafaricomPhone as formatPhoneNumber, formatSafaricomPhone, generateDynamicQR, generateIdempotencyKey, generateOriginatorConversationId, generateRequestRefId, getAccountBalanceCompletedTime, getAccountBalanceConversationId, getAccountBalanceOriginatorConversationId, getAccountBalanceParam, getAccountBalanceRawBalance, getAccountBalanceReferenceItem, getAccountBalanceTransactionId, getB2BAmount, getB2BBuyGoodsAmount, getB2BBuyGoodsBillReferenceNumber, getB2BBuyGoodsCompletedTime, getB2BBuyGoodsConversationId, getB2BBuyGoodsCurrency, getB2BBuyGoodsDebitAccountBalance, getB2BBuyGoodsDebitPartyAffectedBalance, getB2BBuyGoodsDebitPartyCharges, getB2BBuyGoodsInitiatorBalance, getB2BBuyGoodsOriginatorConversationId, getB2BBuyGoodsQueueTimeoutUrl, getB2BBuyGoodsReceiverName, getB2BBuyGoodsResultCode, getB2BBuyGoodsResultDesc, getB2BBuyGoodsResultParam, getB2BBuyGoodsTransactionId, getB2BConversationId, getB2BPayBillAmount, getB2BPayBillBillReferenceNumber, getB2BPayBillCompletedTime, getB2BPayBillConversationId, getB2BPayBillCurrency, getB2BPayBillDebitAccountBalance, getB2BPayBillDebitPartyAffectedBalance, getB2BPayBillDebitPartyCharges, getB2BPayBillInitiatorBalance, getB2BPayBillOriginatorConversationId, getB2BPayBillReceiverName, getB2BPayBillResultCode, getB2BPayBillResultDesc, getB2BPayBillResultParam, getB2BPayBillTransactionId, getB2BRequestId, getB2BTransactionId, getB2CAmount, getB2CConversationId, getB2CCurrency, getB2CDebitAccountBalance, getB2CDebitPartyCharges, getB2CDisbursementAmount, getB2CDisbursementCompletedTime, getB2CDisbursementConversationId, getB2CDisbursementOriginatorConversationId, getB2CDisbursementReceiptNumber, getB2CDisbursementReceiverName, getB2CDisbursementResultCode, getB2CDisbursementResultDesc, getB2CDisbursementResultParam, getB2CDisbursementTransactionId, getB2CDisbursementUtilityBalance, getB2CDisbursementWorkingBalance, getB2COriginatorConversationId, getB2CReceiverPublicName, getB2CResultDesc, getB2CResultParam, getB2CTransactionCompletedTime, getB2CTransactionId, getC2BAccountRef, getC2BAmount, getC2BCustomerName, getC2BTransactionId, getCallbackValue, getReversalAmount, getReversalCharge, getReversalCompletedTime, getReversalConversationId, getReversalCreditPartyPublicName, getReversalDebitAccountBalance, getReversalDebitPartyPublicName, getReversalOriginalTransactionId, getReversalOriginatorConversationId, getReversalResultCode, getReversalResultDesc, getReversalResultParam, getReversalTransactionId, getTaxAmount, getTaxCompletedTime, getTaxConversationId, getTaxOriginatorConversationId, getTaxReceiverName, getTaxResultCode, getTaxResultDesc, getTaxResultParam, getTaxTransactionId, getTimestamp, getTransactionStatusAmount, getTransactionStatusConversationId, getTransactionStatusCreditPartyName, getTransactionStatusDebitAccountBalance, getTransactionStatusDebitPartyName, getTransactionStatusOriginatorConversationId, getTransactionStatusReceiptNo, getTransactionStatusResultCode, getTransactionStatusResultDesc, getTransactionStatusResultParam, getTransactionStatusStatus, getTransactionStatusTransactionDate, getTransactionStatusTransactionId, handleWebhook, httpRequest, initiateB2BBuyGoods, initiateB2BExpressCheckout, initiateB2BPayBill, initiateB2CDisbursement, initiateB2CPayment, isAccountBalanceSuccess, isB2BBuyGoodsFailure, isB2BBuyGoodsResult, isB2BBuyGoodsSuccess, isB2BCheckoutCallback, isB2BCheckoutCancelled, isB2BCheckoutSuccess, isB2BPayBillFailure, isB2BPayBillResult, isB2BPayBillSuccess, isB2CDisbursementFailure, isB2CDisbursementRecipientRegistered, isB2CDisbursementResult, isB2CDisbursementSuccess, isB2CFailure, isB2CResult, isB2CSuccess, isBuyGoodsPayment, isC2BPayload, isKnownB2BBuyGoodsResultCode, isKnownB2BPayBillResultCode, isKnownB2CDisbursementResultCode, isKnownB2CResultCode, isKnownReversalResultCode, isKnownStkResultCode, isKnownTransactionStatusResultCode, isPaybillPayment, isPesafyError, isReversalFailure, isReversalResult, isReversalSuccess, isStkCallbackSuccess, isSuccessfulCallback, isTaxRemittanceFailure, isTaxRemittanceResult, isTaxRemittanceSuccess, isTransactionStatusFailure, isTransactionStatusResult, isTransactionStatusSuccess, ok, parseAccountBalance, parseStkPushWebhook, queryAccountBalance, queryTransactionStatus, reconcilePayment, registerC2BUrls, rejectC2BValidation, remitTax, requestReversal, retryWithBackoff, sendBulkInvoices, sendSingleInvoice, simulateC2B, toKesAmount, toMsisdn, toNonEmpty, toPaybill, toShortCode, toTill, updateOptIn, validateAmount, validateCpi, validateDynamicQRRequest, validateMerchantName, validateRefNo, validateSize, validateTrxCode, verifyWebhook, verifyWebhookHMAC, verifyWebhookIP };
+//# sourceMappingURL=index.js.map