@myzonerocks/pact 0.1.3 → 0.1.6

package/README.md

@@ -105,9 +105,9 @@ webhooks, so run them on a server, never in a browser bundle.
 
 ## Conformance
 
-The Go, TypeScript, and Dart SDKs are held to one wire format by shared vectors: a
-fixed intent produces a fixed canonical preimage, hash, and signature that all
-three reproduce byte-for-byte.
+The Go, TypeScript, Dart, Swift, and Kotlin SDKs are held to one wire format by
+shared vectors: a fixed intent produces a fixed canonical preimage, hash, and
+signature that every one of them reproduces byte-for-byte.
 
 ```
 bun run test

package/dist/src/adapter.d.ts

@@ -14,5 +14,5 @@ export interface AdapterEvent {
     settledAt: number;
 }
 export interface WebhookParser {
-    parseWebhook(raw: Uint8Array, headers: Record<string, string[]>): AdapterEvent[];
+    parseWebhook(raw: Uint8Array, headers: Record<string, string[]>): AdapterEvent[] | Promise<AdapterEvent[]>;
 }

package/dist/src/adapters/erc20.d.ts

@@ -1,3 +1,4 @@
+import type { Money } from "../money.js";
 import type { Quote, Authorization, Settlement } from "../message.js";
 import { RefundKind, type AdapterEvent } from "../adapter.js";
 import type { PayInLeg, PayOutLeg, PayInCapabilities, PayOutCapabilities, CollectResult, DisburseResult } from "../leg.js";
@@ -7,11 +8,16 @@ export interface Call {
 }
 export interface ChainReceipt {
     status: "success" | "reverted" | "pending";
+    blockNumber: number;
     blockTimestampMs: number;
+    tokenAddress: string;
+    to: string;
+    amount: bigint;
 }
 export interface ChainClient {
     send(call: Call): Promise<string>;
     receipt(txHash: string): Promise<ChainReceipt>;
+    blockNumber(): Promise<number>;
 }
 export interface Erc20Config {
     id?: string;
@@ -20,6 +26,24 @@ export interface Erc20Config {
     rail?: string;
     chain: ChainClient;
     ids: () => string;
+    decimals: number;
+    minConfirmations?: number;
+    store?: SentStore;
+}
+export interface SentRecord {
+    intentId: string;
+    txHash: string;
+    to: string;
+    amount: bigint;
+}
+export interface SentStore {
+    save(rec: SentRecord): Promise<void>;
+    byIntent(intentId: string): Promise<SentRecord | undefined>;
+}
+export declare class MemorySentStore implements SentStore {
+    private readonly byIntentMap;
+    save(rec: SentRecord): Promise<void>;
+    byIntent(intentId: string): Promise<SentRecord | undefined>;
 }
 export declare class Erc20Leg implements PayInLeg, PayOutLeg {
     readonly id: string;
@@ -28,16 +52,18 @@ export declare class Erc20Leg implements PayInLeg, PayOutLeg {
     private readonly rail;
     private readonly chain;
     private readonly ids;
-    private readonly sent;
+    private readonly decimals;
+    private readonly minConf;
+    private readonly store;
     constructor(cfg: Erc20Config);
+    private checkScale;
     payInCapabilities(): PayInCapabilities;
     payOutCapabilities(): PayOutCapabilities;
     collect(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<CollectResult>;
     disburse(intentId: string, quote: Quote, recipientRef: string): Promise<DisburseResult>;
-    refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement>;
-    reverseOut(intentId: string, reason: string): Promise<Settlement>;
+    refundIn(_intentId: string, _kind: RefundKind, _amount: Money, _reason: string): Promise<Settlement>;
+    reverseOut(_intentId: string, _reason: string): Promise<Settlement>;
     settlementEvent(intentId: string): Promise<AdapterEvent>;
     private transfer;
-    private terminal;
 }
 export declare function transferCalldata(recipient: string, amount: bigint): string;

package/dist/src/adapters/erc20.js

@@ -10,6 +10,20 @@ import { RefundKind } from "../adapter.js";
 // The 4-byte selector for the ERC-20 transfer(address,uint256) call. It is a
 // fixed constant of the standard, so building the calldata needs no hashing.
 const transferSelector = "a9059cbb";
+// The confirmation depth a transfer must reach before it settles. A shallow
+// success can still be reorged out, so a settlement waits for enough blocks on
+// top of it.
+const defaultMinConfirmations = 12;
+// MemorySentStore is the default in-process store.
+export class MemorySentStore {
+    byIntentMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+}
 // Erc20Leg settles a payment as an ERC-20 token transfer. Refunds are a
 // counter-transfer only, because a token transfer is irreversible.
 export class Erc20Leg {
@@ -19,20 +33,43 @@ export class Erc20Leg {
     rail;
     chain;
     ids;
-    sent = new Map();
+    decimals;
+    minConf;
+    // Broadcast transfers, so a settlement can confirm the mined transaction really
+    // matches the payment, and a repeat returns the first transfer.
+    store;
     constructor(cfg) {
         if (!cfg.token || !cfg.currency) {
             throw new Error("erc20: config requires a token address and currency");
         }
+        // The token address is fixed for the leg's lifetime, so validate it once here
+        // rather than discover a malformed contract address at the first transfer.
+        if (!/^[0-9a-f]{40}$/.test(normalizeAddress(cfg.token))) {
+            throw new Error(`erc20: token ${JSON.stringify(cfg.token)} is not a 20-byte address`);
+        }
         this.id = cfg.id ?? "erc20";
         this.token = cfg.token;
         this.currency = cfg.currency;
         this.rail = cfg.rail ?? "erc20";
         this.chain = cfg.chain;
         this.ids = cfg.ids;
+        this.decimals = cfg.decimals;
+        this.minConf = cfg.minConfirmations ?? defaultMinConfirmations;
+        this.store = cfg.store ?? new MemorySentStore();
+    }
+    // checkScale refuses an amount whose exponent does not match the token's
+    // decimals, so a quote priced at the wrong scale never moves the wrong number
+    // of tokens.
+    checkScale(m) {
+        if (m.exponent !== this.decimals) {
+            throw new Error(`erc20: amount exponent ${m.exponent} does not match the token's ${this.decimals} decimals`);
+        }
     }
     payInCapabilities() {
-        return { rails: [this.rail], currencies: [this.currency], refunds: RefundKind.CounterTransfer };
+        // A token collection is irreversible and the leg holds no custody to send the
+        // payer back, so it advertises no refund rather than a capability it cannot
+        // honour. An adopter that wires refund custody supplies a leg that offers one.
+        return { rails: [this.rail], currencies: [this.currency], refunds: RefundKind.None };
     }
     payOutCapabilities() {
         return { rails: [this.rail], currencies: [this.currency], reversible: false };
@@ -41,62 +78,82 @@ export class Erc20Leg {
     // direct corridor, the escrow for a bridged one. received is the net a bridge
     // would convert: the source the payer paid less the corridor fees.
     async collect(intentId, quote, _auth, deliverTo) {
+        this.checkScale(quote.srcAmount);
         const net = quote.srcAmount.sub(quote.fees);
+        // A repeat for the same intent returns the transfer already broadcast rather
+        // than sending the payer's tokens twice.
+        const prev = await this.store.byIntent(intentId);
+        if (prev) {
+            return { providerRef: prev.txHash, received: net };
+        }
         const txHash = await this.transfer(deliverTo, net.value());
-        this.sent.set(intentId, txHash);
+        await this.store.save({ intentId, txHash, to: normalizeAddress(deliverTo), amount: net.value() });
         return { providerRef: txHash, received: net };
     }
     // disburse delivers the recipient's tokens.
     async disburse(intentId, quote, recipientRef) {
-        const txHash = await this.transfer(recipientRef, quote.dstAmount.value());
-        this.sent.set(intentId, txHash);
+        this.checkScale(quote.dstAmount);
+        // A repeat for the same intent returns the transfer already broadcast rather
+        // than delivering the recipient's tokens twice.
+        const prev = await this.store.byIntent(intentId);
+        if (prev) {
+            return { providerRef: prev.txHash };
+        }
+        const amount = quote.dstAmount.value();
+        const txHash = await this.transfer(recipientRef, amount);
+        await this.store.save({ intentId, txHash, to: normalizeAddress(recipientRef), amount });
         return { providerRef: txHash };
     }
-    // refundIn and reverseOut both answer with a counter-transfer, the only refund
-    // an irreversible token movement supports.
-    async refundIn(intentId, kind, reason) {
-        if (kind !== RefundKind.CounterTransfer) {
-            throw new Error("erc20: a token transfer can only be refunded by counter-transfer");
-        }
-        return this.terminal(intentId, reason);
+    // refundIn refuses: an ERC-20 collection is irreversible and the leg holds no
+    // custody to counter-transfer the payer back, so it will not record a refund
+    // that moves no tokens. An adopter that wires refund custody supplies a leg
+    // that advertises and honours a refund.
+    async refundIn(_intentId, _kind, _amount, _reason) {
+        throw new Error("erc20: a token collection cannot be refunded in place; wire refund custody to return the payer");
     }
-    async reverseOut(intentId, reason) {
-        return this.terminal(intentId, reason);
+    // reverseOut refuses, reporting the truth of the rail: a delivered token
+    // transfer cannot be pulled back.
+    async reverseOut(_intentId, _reason) {
+        throw new Error("erc20: a delivered token transfer cannot be reversed");
     }
-    // settlementEvent reads the receipt for an intent's transaction and produces the
-    // event a host feeds back once the transfer confirms. Crypto has no webhook, so
-    // the host polls this instead.
+    // settlementEvent reads a broadcast transfer back from chain and reports its
+    // outcome. A token transfer has no webhook, so a host polls this. It settles
+    // only when the transaction is final: mined successfully, buried under the
+    // required confirmations, and carrying a Transfer of the configured token, in
+    // the amount that was sent, to the recipient it was sent to. A pending or
+    // shallow success stays submitted so the host keeps polling; a revert or a
+    // mismatch fails, so a dropped, reorged, or spoofed transfer never settles.
     async settlementEvent(intentId) {
-        const txHash = this.sent.get(intentId);
-        if (!txHash) {
+        const rec = await this.store.byIntent(intentId);
+        if (!rec) {
             throw new Error("erc20: no broadcast transaction for intent");
         }
-        const receipt = await this.chain.receipt(txHash);
-        return {
-            intentId,
-            state: receiptState(receipt),
-            providerTxRef: txHash,
-            onchainTxHash: txHash,
-            reason: receipt.status === "reverted" ? "transaction reverted" : "",
-            settledAt: receipt.blockTimestampMs,
-        };
+        const receipt = await this.chain.receipt(rec.txHash);
+        const base = { intentId, providerTxRef: rec.txHash, onchainTxHash: rec.txHash, settledAt: 0 };
+        if (receipt.status === "reverted") {
+            return { ...base, state: State.Failed, reason: "transaction reverted" };
+        }
+        if (receipt.status !== "success") {
+            return { ...base, state: State.Submitted, reason: "" };
+        }
+        const head = await this.chain.blockNumber();
+        if (receipt.blockNumber === 0 || head < receipt.blockNumber || head - receipt.blockNumber + 1 < this.minConf) {
+            return { ...base, state: State.Submitted, reason: "" };
+        }
+        if (!sameAddress(receipt.tokenAddress, this.token) ||
+            !sameAddress(receipt.to, rec.to) ||
+            receipt.amount !== rec.amount) {
+            return {
+                ...base,
+                state: State.Failed,
+                reason: "on-chain transfer does not match the expected token, recipient, or amount",
+            };
+        }
+        return { ...base, state: State.Settled, reason: "", settledAt: receipt.blockTimestampMs };
     }
     async transfer(to, amount) {
         return this.chain.send({ to: this.token, data: transferCalldata(to, amount) });
     }
-    terminal(intentId, reason) {
-        const txHash = this.sent.get(intentId) ?? "";
-        return {
-            intentId,
-            state: State.Refunded,
-            adapterId: this.id,
-            providerTxRef: txHash,
-            onchainTxHash: txHash,
-            receiptHash: new Uint8Array(0),
-            reason,
-            settledAt: 0,
-        };
-    }
 }
 // transferCalldata builds the ERC-20 transfer calldata: the selector, the
 // recipient address left-padded to 32 bytes, and the amount as a 32-byte word.
@@ -114,13 +171,11 @@ export function transferCalldata(recipient, amount) {
     }
     return "0x" + transferSelector + address.padStart(64, "0") + amountHex.padStart(64, "0");
 }
-function receiptState(receipt) {
-    switch (receipt.status) {
-        case "success":
-            return State.Settled;
-        case "reverted":
-            return State.Failed;
-        default:
-            return State.Submitted;
-    }
+// normalizeAddress lowercases an EVM address and drops any 0x prefix, so two
+// spellings of the same address compare equal.
+function normalizeAddress(addr) {
+    return addr.toLowerCase().replace(/^0x/, "");
+}
+function sameAddress(a, b) {
+    return normalizeAddress(a) === normalizeAddress(b);
 }

package/dist/src/adapters/http.d.ts

@@ -0,0 +1,2 @@
+export declare const httpTimeoutMs = 30000;
+export declare function fetchWithTimeout(url: string, init?: RequestInit): Promise<Response>;

package/dist/src/adapters/http.js

@@ -0,0 +1,12 @@
+// Shared HTTP settings for the network adapters. A provider call that never
+// answers must not hang the corridor forever, so every outbound request carries
+// the same deadline. The Go adapters bound their http.Client the same way.
+// httpTimeoutMs bounds how long an outbound provider request may run before it is
+// aborted. It matches the 30-second ceiling the Go adapters use.
+export const httpTimeoutMs = 30_000;
+// fetchWithTimeout issues a fetch that aborts once httpTimeoutMs elapses, so a
+// stalled provider surfaces as an error rather than an unbounded wait. A caller
+// that already supplies a signal is left untouched.
+export function fetchWithTimeout(url, init = {}) {
+    return fetch(url, { signal: AbortSignal.timeout(httpTimeoutMs), ...init });
+}

package/dist/src/adapters/mpesa.d.ts

@@ -1,3 +1,4 @@
+import { Money } from "../money.js";
 import type { Quote, Authorization, Settlement } from "../message.js";
 import { RefundKind, type AdapterEvent } from "../adapter.js";
 import type { PayInLeg, PayOutLeg, PayInCapabilities, PayOutCapabilities, CollectResult, DisburseResult } from "../leg.js";
@@ -19,36 +20,61 @@ export interface B2CParams {
     phone: string;
     reference: string;
     remarks: string;
+    idempotencyKey: string;
 }
 export interface B2CResult {
     conversationId: string;
     responseCode: string;
 }
+export interface StkQueryResult {
+    resultCode: number;
+    resultDesc: string;
+    pending: boolean;
+}
 export interface DarajaApi {
     stkPush(params: StkPushParams): Promise<StkPushResult>;
     b2cPayment(params: B2CParams): Promise<B2CResult>;
+    query(checkoutRequestId: string): Promise<StkQueryResult>;
+}
+export interface PushRecord {
+    intentId: string;
+    checkoutId: string;
+    payerPhone: string;
+    amount: number;
+}
+export interface PushStore {
+    save(rec: PushRecord): Promise<void>;
+    byIntent(intentId: string): Promise<PushRecord | undefined>;
+    byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+}
+export declare class MemoryPushStore implements PushStore {
+    private readonly byIntentMap;
+    private readonly byCheckoutMap;
+    save(rec: PushRecord): Promise<void>;
+    byIntent(intentId: string): Promise<PushRecord | undefined>;
+    byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
 }
 export interface MpesaConfig {
     id?: string;
     api: DarajaApi;
     callbackURL: string;
     ids: () => string;
+    store?: PushStore;
 }
 export declare class MpesaLeg implements PayInLeg, PayOutLeg {
     readonly id: string;
     private readonly api;
     private readonly callbackURL;
     private readonly ids;
-    private readonly byIntent;
-    private readonly byCheckout;
+    private readonly store;
     constructor(cfg: MpesaConfig);
     payInCapabilities(): PayInCapabilities;
     payOutCapabilities(): PayOutCapabilities;
     collect(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<CollectResult>;
     disburse(intentId: string, quote: Quote, recipientRef: string): Promise<DisburseResult>;
-    refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement>;
+    refundIn(intentId: string, kind: RefundKind, amount: Money, reason: string): Promise<Settlement>;
     reverseOut(_intentId: string, _reason: string): Promise<Settlement>;
-    parseWebhook(raw: Uint8Array, _headers: Record<string, string[]>): AdapterEvent[];
+    parseWebhook(raw: Uint8Array, _headers: Record<string, string[]>): Promise<AdapterEvent[]>;
 }
 export declare function normalizePhone(phone: string): string;
 export interface Credentials {

package/dist/src/adapters/mpesa.js

@@ -1,5 +1,6 @@
 import { State } from "../state.js";
 import { RefundKind } from "../adapter.js";
+import { fetchWithTimeout } from "./http.js";
 // The public Daraja host. It is the same for every integration and holds no
 // secret; tests point the leg at a local server instead.
 const defaultBaseURL = "https://api.safaricom.co.ke";
@@ -8,14 +9,29 @@ const defaultBaseURL = "https://api.safaricom.co.ke";
 // checkout id to one we started is the authentication: an unrecognized id is
 // rejected rather than acted on.
 export const ErrUnknownCheckout = "mpesa: callback for an unknown checkout request";
+// MemoryPushStore is the default in-process store.
+export class MemoryPushStore {
+    byIntentMap = new Map();
+    byCheckoutMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+        if (rec.checkoutId)
+            this.byCheckoutMap.set(rec.checkoutId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+    async byCheckout(checkoutId) {
+        return this.byCheckoutMap.get(checkoutId);
+    }
+}
 // MpesaLeg moves mobile money over M-Pesa.
 export class MpesaLeg {
     id;
     api;
     callbackURL;
     ids;
-    byIntent = new Map();
-    byCheckout = new Map();
+    store;
     constructor(cfg) {
         if (!cfg.callbackURL) {
             throw new Error("mpesa: config requires a callback URL");
@@ -24,6 +40,7 @@ export class MpesaLeg {
         this.api = cfg.api;
         this.callbackURL = cfg.callbackURL;
         this.ids = cfg.ids;
+        this.store = cfg.store ?? new MemoryPushStore();
     }
     payInCapabilities() {
         return { rails: ["mpesa"], currencies: ["KES"], refunds: RefundKind.CounterTransfer };
@@ -44,7 +61,6 @@ export class MpesaLeg {
         if (!phone) {
             throw new Error("mpesa: collect requires the payer's phone");
         }
-        const rec = { intentId, payerPhone: phone, amount, state: State.Unspecified };
         const result = await this.api.stkPush({
             amount,
             payerPhone: phone,
@@ -52,8 +68,7 @@ export class MpesaLeg {
             description: "payment",
             callbackURL: this.callbackURL,
         });
-        this.byIntent.set(intentId, rec);
-        this.byCheckout.set(result.checkoutRequestId, rec);
+        await this.store.save({ intentId, checkoutId: result.checkoutRequestId, payerPhone: phone, amount });
         return { providerRef: result.checkoutRequestId, received: net };
     }
     // disburse delivers the recipient's shillings by a business-to-customer payout
@@ -64,25 +79,31 @@ export class MpesaLeg {
         if (!phone) {
             throw new Error("mpesa: disburse requires the recipient's phone");
         }
-        const result = await this.api.b2cPayment({ amount, phone, reference: intentId, remarks: "payout" });
+        const result = await this.api.b2cPayment({ amount, phone, reference: intentId, remarks: "payout", idempotencyKey: `pact:payout:${intentId}` });
         return { providerRef: result.conversationId };
     }
     // refundIn answers a collected payment with a business-to-customer payout back
     // to the payer. An STK collection cannot be reversed in place, so a
     // counter-transfer is the only refund this rail supports.
-    async refundIn(intentId, kind, reason) {
+    async refundIn(intentId, kind, amount, reason) {
         if (kind !== RefundKind.CounterTransfer) {
             throw new Error("mpesa: a collection can only be refunded by counter-transfer");
         }
-        const rec = this.byIntent.get(intentId);
+        const shillings = wholeShillings(amount);
+        const rec = await this.store.byIntent(intentId);
         if (!rec) {
             throw new Error(`mpesa: no push for intent ${intentId}`);
         }
+        // A refund cannot return more shillings than the push collected.
+        if (shillings > rec.amount) {
+            throw new Error(`mpesa: refund of ${shillings} exceeds the ${rec.amount} collected`);
+        }
         const result = await this.api.b2cPayment({
-            amount: rec.amount,
+            amount: shillings,
             phone: rec.payerPhone,
             reference: intentId,
             remarks: reason,
+            idempotencyKey: `pact:refund:${intentId}`,
         });
         return {
             intentId,
@@ -101,32 +122,44 @@ export class MpesaLeg {
         throw new Error("mpesa: a delivered payout cannot be reversed");
     }
     // parseWebhook reads an STK callback and normalizes it into a protocol event.
-    // The callback is unsigned, so it is authenticated by matching its checkout id
-    // to a push this leg started; an unrecognized id is refused. The headers are
-    // accepted for interface symmetry and for a host that adds its own IP or
-    // shared-secret gate on top.
-    parseWebhook(raw, _headers) {
+    // The callback is unsigned and its CheckoutRequestID is a value we hand back to
+    // the caller — not a secret — so the callback body is treated only as a nudge.
+    // The real outcome is read back from Daraja with our own credentials, and a
+    // settlement is emitted only when that authenticated query confirms success and
+    // the amount Daraja paid equals the amount we authorized. The headers are
+    // accepted for interface symmetry and for a host that adds its own gate on top.
+    async parseWebhook(raw, _headers) {
         const envelope = JSON.parse(new TextDecoder().decode(raw));
         const cb = envelope.Body?.stkCallback;
-        const rec = cb ? this.byCheckout.get(cb.CheckoutRequestID) : undefined;
+        const rec = cb ? await this.store.byCheckout(cb.CheckoutRequestID) : undefined;
         if (!cb || !rec) {
             throw new Error(ErrUnknownCheckout);
         }
-        if (cb.ResultCode !== 0) {
-            rec.state = State.Failed;
+        const confirmed = await this.api.query(cb.CheckoutRequestID);
+        // No outcome yet — wait for a later callback rather than settling or failing
+        // on an unconfirmed body.
+        if (confirmed.pending) {
+            return [];
+        }
+        if (confirmed.resultCode !== 0) {
             return [
                 {
                     intentId: rec.intentId,
                     state: State.Failed,
                     providerTxRef: cb.CheckoutRequestID,
                     onchainTxHash: "",
-                    reason: cb.ResultDesc ?? "",
+                    reason: confirmed.resultDesc,
                     settledAt: 0,
                 },
             ];
         }
+        // The amount Daraja collected must equal the amount we authorized; a partial
+        // or tampered collection settles nothing.
+        const paid = metadataInt(cb.CallbackMetadata?.Item ?? [], "Amount");
+        if (paid !== rec.amount) {
+            throw new Error(`mpesa: confirmed amount ${paid} does not match the authorized ${rec.amount}`);
+        }
         const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
-        rec.state = State.Settled;
         return [
             {
                 intentId: rec.intentId,
@@ -152,6 +185,19 @@ function wholeShillings(m) {
     }
     return Number(amount);
 }
+// metadataInt pulls a named numeric value out of the callback metadata items,
+// used to read the paid Amount. M-Pesa amounts are whole shillings but may arrive
+// as a number with a fractional part, so it is floored to the shilling.
+function metadataInt(items, name) {
+    for (const item of items) {
+        if (item.Name !== name) {
+            continue;
+        }
+        const n = Number(item.Value);
+        return Number.isFinite(n) ? Math.floor(n) : 0;
+    }
+    return 0;
+}
 // metadataString pulls a named string value out of the callback metadata items.
 function metadataString(items, name) {
     for (const item of items) {
@@ -183,14 +229,21 @@ class HttpDarajaApi {
     creds;
     baseURL;
     now;
+    cachedToken = "";
+    tokenExpiryMs = 0;
     constructor(creds, now) {
         this.creds = creds;
         this.baseURL = creds.baseURL || defaultBaseURL;
         this.now = now;
     }
     async token() {
+        // Reuse the cached token until it is within a minute of expiry, so a burst of
+        // pushes does not re-authenticate against Daraja on every call.
+        if (this.cachedToken && this.now().getTime() < this.tokenExpiryMs - 60_000) {
+            return this.cachedToken;
+        }
         const basic = Buffer.from(`${this.creds.consumerKey}:${this.creds.consumerSecret}`).toString("base64");
-        const resp = await fetch(`${this.baseURL}/oauth/v1/generate?grant_type=client_credentials`, {
+        const resp = await fetchWithTimeout(`${this.baseURL}/oauth/v1/generate?grant_type=client_credentials`, {
             method: "GET",
             headers: { Authorization: `Basic ${basic}` },
         });
@@ -198,7 +251,11 @@ class HttpDarajaApi {
             throw new Error(`mpesa: /oauth/v1/generate returned ${resp.status}`);
         }
         const out = (await resp.json());
-        return out.access_token ?? "";
+        // Daraja tokens live an hour; fall back to that if the field is absent.
+        const ttlSeconds = Number(out.expires_in) > 0 ? Number(out.expires_in) : 3599;
+        this.cachedToken = out.access_token ?? "";
+        this.tokenExpiryMs = this.now().getTime() + ttlSeconds * 1000;
+        return this.cachedToken;
     }
     // password is the base64 of shortcode+passkey+timestamp Daraja requires on each
     // STK push.
@@ -228,9 +285,36 @@ class HttpDarajaApi {
             responseCode: out.ResponseCode ?? "",
         };
     }
+    async query(checkoutRequestId) {
+        const token = await this.token();
+        const timestamp = formatTimestamp(this.now());
+        const body = {
+            BusinessShortCode: this.creds.shortCode,
+            Password: this.password(timestamp),
+            Timestamp: timestamp,
+            CheckoutRequestID: checkoutRequestId,
+        };
+        const resp = await fetchWithTimeout(this.baseURL + "/mpesa/stkpushquery/v1/query", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+            body: JSON.stringify(body),
+        });
+        const out = (await resp.json());
+        // Daraja answers a query for a push it is still processing with an error code
+        // rather than a result; treat that as pending so the outcome is confirmed on a
+        // later query rather than mistaken for a failure.
+        if (out.errorCode === "500.001.1001") {
+            return { resultCode: 0, resultDesc: "", pending: true };
+        }
+        if (resp.status >= 300) {
+            throw new Error(`mpesa: stk query returned ${resp.status}`);
+        }
+        return { resultCode: Number(out.ResultCode ?? -1), resultDesc: out.ResultDesc ?? "", pending: false };
+    }
     async b2cPayment(params) {
         const token = await this.token();
         const body = {
+            OriginatorConversationID: params.idempotencyKey,
             InitiatorName: this.creds.shortCode,
             CommandID: "BusinessPayment",
             Amount: params.amount,
@@ -243,7 +327,7 @@ class HttpDarajaApi {
         return { conversationId: out.ConversationID ?? "", responseCode: out.ResponseCode ?? "" };
     }
     async postJSON(token, path, body) {
-        const resp = await fetch(this.baseURL + path, {
+        const resp = await fetchWithTimeout(this.baseURL + path, {
             method: "POST",
             headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
             body: JSON.stringify(body),