@myzonerocks/pact 0.1.8 → 0.2.0

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

@@ -46,13 +46,18 @@ export interface PushStore {
     save(rec: PushRecord): Promise<void>;
     byIntent(intentId: string): Promise<PushRecord | undefined>;
     byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+    pending(olderThanMs: number): Promise<PushRecord[]>;
+    resolve(checkoutId: string): Promise<void>;
 }
 export declare class MemoryPushStore implements PushStore {
     private readonly byIntentMap;
     private readonly byCheckoutMap;
+    now: () => number;
     save(rec: PushRecord): Promise<void>;
     byIntent(intentId: string): Promise<PushRecord | undefined>;
     byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+    pending(olderThanMs: number): Promise<PushRecord[]>;
+    resolve(checkoutId: string): Promise<void>;
 }
 export interface MpesaConfig {
     id?: string;
@@ -75,6 +80,8 @@ export declare class MpesaLeg implements PayInLeg, PayOutLeg {
     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[]>): Promise<AdapterEvent[]>;
+    reconcile(olderThanMs: number): Promise<AdapterEvent[]>;
+    private resolve;
 }
 export declare function normalizePhone(phone: string): string;
 export interface Credentials {

package/dist/src/adapters/mpesa.js

@@ -13,16 +13,41 @@ export const ErrUnknownCheckout = "mpesa: callback for an unknown checkout reque
 export class MemoryPushStore {
     byIntentMap = new Map();
     byCheckoutMap = new Map();
+    // now is the clock the push age is measured against; it is a field so a test can make
+    // "old enough to reconcile" deterministic.
+    now = () => Date.now();
     async save(rec) {
-        this.byIntentMap.set(rec.intentId, rec);
+        // A re-save for the same intent keeps the original send time and resolved state,
+        // mirroring the durable store, so re-pushing never resets the reconcile clock.
+        let entry = this.byIntentMap.get(rec.intentId);
+        if (!entry) {
+            entry = { rec, createdAt: this.now(), resolved: false };
+            this.byIntentMap.set(rec.intentId, entry);
+        }
+        entry.rec = rec;
         if (rec.checkoutId)
-            this.byCheckoutMap.set(rec.checkoutId, rec);
+            this.byCheckoutMap.set(rec.checkoutId, entry);
     }
     async byIntent(intentId) {
-        return this.byIntentMap.get(intentId);
+        return this.byIntentMap.get(intentId)?.rec;
     }
     async byCheckout(checkoutId) {
-        return this.byCheckoutMap.get(checkoutId);
+        return this.byCheckoutMap.get(checkoutId)?.rec;
+    }
+    async pending(olderThanMs) {
+        const cutoff = this.now() - olderThanMs;
+        const out = [];
+        for (const entry of this.byIntentMap.values()) {
+            if (entry.resolved || entry.createdAt > cutoff)
+                continue;
+            out.push(entry.rec);
+        }
+        return out;
+    }
+    async resolve(checkoutId) {
+        const entry = this.byCheckoutMap.get(checkoutId);
+        if (entry)
+            entry.resolved = true;
     }
 }
 // MpesaLeg moves mobile money over M-Pesa.
@@ -135,31 +160,64 @@ export class MpesaLeg {
         if (!cb || !rec) {
             throw new Error(ErrUnknownCheckout);
         }
-        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.
+        // The receipt is taken from the callback only as an audit reference; the settled
+        // amount is never read from the unsigned body. The authoritative outcome comes from
+        // the query in resolve.
+        const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
+        return this.resolve(rec, receipt);
+    }
+    // reconcile settles or fails the pushes whose callback has not arrived by reading
+    // their outcome back from Daraja. It is the recovery path for a dropped or delayed STK
+    // callback: a host runs it on a timer so a lost callback is not terminal. Only pushes
+    // older than olderThanMs are queried, so a healthy collection still settles from its
+    // callback and only an overdue one is polled; a push that fails to query is left for
+    // the next run rather than stalling the rest. The events it returns are the same
+    // settle and fail events a callback would have produced, applied through the same path.
+    async reconcile(olderThanMs) {
+        const pending = await this.store.pending(olderThanMs);
+        const events = [];
+        for (const rec of pending) {
+            try {
+                // Queried one at a time on purpose: this is a background sweep and Daraja
+                // rate-limits its query endpoint, so a burst of parallel reads would be
+                // throttled rather than faster. The sweep runs off any request path, so
+                // serializing it costs no user-facing latency.
+                // eslint-disable-next-line no-await-in-loop
+                events.push(...(await this.resolve(rec, "")));
+            }
+            catch {
+                // One push failing to query must not stall the batch; the next run retries it.
+            }
+        }
+        return events;
+    }
+    // resolve reads a push's authoritative outcome from Daraja and maps it to a protocol
+    // event, the single mapping both the callback and the reconcile timer go through. A
+    // push still processing yields no event and stays pending for a later look; a settled
+    // or failed one is marked resolved so it is not queried again. The settled amount is
+    // the one we recorded when the STK push fixed it, never read from the unsigned
+    // callback: a payer approves that exact amount or cancels, and reading it from a body
+    // whose checkout id is not a secret would let a forged callback carry a wrong amount
+    // and block a collection the payer completed. receipt is the callback's audit
+    // reference; the reconcile path, which has no callback body, passes none.
+    async resolve(rec, receipt) {
+        const confirmed = await this.api.query(rec.checkoutId);
         if (confirmed.pending) {
             return [];
         }
+        await this.store.resolve(rec.checkoutId);
         if (confirmed.resultCode !== 0) {
             return [
                 {
                     intentId: rec.intentId,
                     state: State.Failed,
-                    providerTxRef: cb.CheckoutRequestID,
+                    providerTxRef: rec.checkoutId,
                     onchainTxHash: "",
                     reason: confirmed.resultDesc,
                     settledAt: 0,
                 },
             ];
         }
-        // The STK push fixed the amount we authorized; a payer approves that exact amount
-        // or cancels, so an approved collection is always the full authorized amount. The
-        // authenticated query above confirms success, so the settled amount is the one we
-        // recorded — it is never read from the unsigned callback, since a forged callback
-        // (the checkout id is not a secret) could otherwise carry a wrong amount and block
-        // a collection the payer completed. The receipt is an audit reference only.
-        const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
         return [
             {
                 intentId: rec.intentId,

package/dist/test/mpesa.test.js

@@ -8,7 +8,7 @@ import { UsdcBridge } from "../src/bridge.js";
 import { FakeLeg, FakeRates, FakeVault } from "./fake.js";
 import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
 import { fromHex } from "../src/crypto.js";
-import { MpesaLeg, ErrUnknownCheckout, normalizePhone, } from "../src/adapters/mpesa.js";
+import { MpesaLeg, MemoryPushStore, ErrUnknownCheckout, normalizePhone, } from "../src/adapters/mpesa.js";
 function counter(prefix) {
     let n = 0;
     return () => `${prefix}_${String(++n).padStart(3, "0")}`;
@@ -215,3 +215,40 @@ describe("mpesa pay-in", () => {
         expect(events[0].providerTxRef).toBe("QGR7XYZ123");
     });
 });
+describe("mpesa reconcile", () => {
+    // A leg over a store whose clock the test drives, so "old enough to reconcile" is
+    // deterministic, together with the fake Daraja and the stock quote the cases share.
+    function reconcileHarness() {
+        const clock = { now: 1_700_000_000_000 };
+        const store = new MemoryPushStore();
+        store.now = () => clock.now;
+        const api = new FakeDaraja(counter("tx"));
+        const leg = new MpesaLeg({ api, callbackURL: "https://host.example/webhook/mpesa", ids: counter("mp"), store });
+        const q = quote({ srcAmount: kes("1500"), fees: kes("0") });
+        return { clock, store, api, leg, q };
+    }
+    it("settles a dropped callback once it is overdue, and never twice", async () => {
+        const { clock, leg, q } = reconcileHarness();
+        await leg.collect("intent-1", q, emptyAuth, "0711000111");
+        // The callback never arrives and the push is still young, so reconcile leaves it be.
+        expect(await leg.reconcile(30_000)).toHaveLength(0);
+        // A minute passes with no callback: the overdue push settles from Daraja's query.
+        clock.now += 60_000;
+        const events = await leg.reconcile(30_000);
+        expect(events).toHaveLength(1);
+        expect(events[0].state).toBe(State.Settled);
+        expect(events[0].intentId).toBe("intent-1");
+        // The settled push is marked resolved, so a later run does not re-emit it.
+        expect(await leg.reconcile(30_000)).toHaveLength(0);
+    });
+    it("leaves a push the payer has not acted on pending", async () => {
+        const { clock, store, api, leg, q } = reconcileHarness();
+        const collected = await leg.collect("intent-1", q, emptyAuth, "0711000111");
+        // Daraja is still processing this checkout: the payer has not approved.
+        api.queryResults.set(collected.providerRef, { resultCode: 0, resultDesc: "", pending: true });
+        clock.now += 60_000;
+        expect(await leg.reconcile(30_000)).toHaveLength(0);
+        // Still unresolved, so a later run will pick it up once it resolves.
+        expect(await store.pending(30_000)).toHaveLength(1);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myzonerocks/pact",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "TypeScript SDK for the PACT payment abstraction protocol",
   "license": "Apache-2.0",
   "repository": {

package/src/adapters/mpesa.ts

@@ -100,25 +100,69 @@ export interface PushRecord {
 // resolves it. The default store keeps them in memory; a deployment that runs more than
 // one instance, or must survive a restart with collections in flight, supplies a
 // durable one so a callback never arrives to find its checkout forgotten.
+//
+// pending and resolve are the recovery path for a callback that never lands: pending
+// lists the pushes still awaiting an outcome so their result can be read back from
+// Daraja, and resolve marks one done so it drops out of that list. A push is queried
+// only while it is both unresolved and old enough that its callback is overdue, so the
+// set pending returns shrinks as collections settle rather than growing without bound.
 export interface PushStore {
   save(rec: PushRecord): Promise<void>;
   byIntent(intentId: string): Promise<PushRecord | undefined>;
   byCheckout(checkoutId: string): Promise<PushRecord | undefined>;
+  // pending lists unresolved pushes whose STK push went out at least olderThanMs ago,
+  // so a young push is left to its callback and only an overdue one is queried.
+  pending(olderThanMs: number): Promise<PushRecord[]>;
+  // resolve marks the push under checkoutId settled or failed so it is no longer
+  // returned by pending. It is safe to call more than once for the same checkout.
+  resolve(checkoutId: string): Promise<void>;
+}
+
+// pushEntry is a stored push with the metadata reconciliation needs: when it went out,
+// so an overdue push can be told from a young one, and whether it has resolved, so a
+// settled push is not queried again.
+interface pushEntry {
+  rec: PushRecord;
+  createdAt: number;
+  resolved: boolean;
 }
 
 // MemoryPushStore is the default in-process store.
 export class MemoryPushStore implements PushStore {
-  private readonly byIntentMap = new Map<string, PushRecord>();
-  private readonly byCheckoutMap = new Map<string, PushRecord>();
+  private readonly byIntentMap = new Map<string, pushEntry>();
+  private readonly byCheckoutMap = new Map<string, pushEntry>();
+  // now is the clock the push age is measured against; it is a field so a test can make
+  // "old enough to reconcile" deterministic.
+  now: () => number = () => Date.now();
   async save(rec: PushRecord): Promise<void> {
-    this.byIntentMap.set(rec.intentId, rec);
-    if (rec.checkoutId) this.byCheckoutMap.set(rec.checkoutId, rec);
+    // A re-save for the same intent keeps the original send time and resolved state,
+    // mirroring the durable store, so re-pushing never resets the reconcile clock.
+    let entry = this.byIntentMap.get(rec.intentId);
+    if (!entry) {
+      entry = { rec, createdAt: this.now(), resolved: false };
+      this.byIntentMap.set(rec.intentId, entry);
+    }
+    entry.rec = rec;
+    if (rec.checkoutId) this.byCheckoutMap.set(rec.checkoutId, entry);
   }
   async byIntent(intentId: string): Promise<PushRecord | undefined> {
-    return this.byIntentMap.get(intentId);
+    return this.byIntentMap.get(intentId)?.rec;
   }
   async byCheckout(checkoutId: string): Promise<PushRecord | undefined> {
-    return this.byCheckoutMap.get(checkoutId);
+    return this.byCheckoutMap.get(checkoutId)?.rec;
+  }
+  async pending(olderThanMs: number): Promise<PushRecord[]> {
+    const cutoff = this.now() - olderThanMs;
+    const out: PushRecord[] = [];
+    for (const entry of this.byIntentMap.values()) {
+      if (entry.resolved || entry.createdAt > cutoff) continue;
+      out.push(entry.rec);
+    }
+    return out;
+  }
+  async resolve(checkoutId: string): Promise<void> {
+    const entry = this.byCheckoutMap.get(checkoutId);
+    if (entry) entry.resolved = true;
   }
 }
 
@@ -251,32 +295,65 @@ export class MpesaLeg implements PayInLeg, PayOutLeg {
     if (!cb || !rec) {
       throw new Error(ErrUnknownCheckout);
     }
+    // The receipt is taken from the callback only as an audit reference; the settled
+    // amount is never read from the unsigned body. The authoritative outcome comes from
+    // the query in resolve.
+    const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
+    return this.resolve(rec, receipt);
+  }
+
+  // reconcile settles or fails the pushes whose callback has not arrived by reading
+  // their outcome back from Daraja. It is the recovery path for a dropped or delayed STK
+  // callback: a host runs it on a timer so a lost callback is not terminal. Only pushes
+  // older than olderThanMs are queried, so a healthy collection still settles from its
+  // callback and only an overdue one is polled; a push that fails to query is left for
+  // the next run rather than stalling the rest. The events it returns are the same
+  // settle and fail events a callback would have produced, applied through the same path.
+  async reconcile(olderThanMs: number): Promise<AdapterEvent[]> {
+    const pending = await this.store.pending(olderThanMs);
+    const events: AdapterEvent[] = [];
+    for (const rec of pending) {
+      try {
+        // Queried one at a time on purpose: this is a background sweep and Daraja
+        // rate-limits its query endpoint, so a burst of parallel reads would be
+        // throttled rather than faster. The sweep runs off any request path, so
+        // serializing it costs no user-facing latency.
+        // eslint-disable-next-line no-await-in-loop
+        events.push(...(await this.resolve(rec, "")));
+      } catch {
+        // One push failing to query must not stall the batch; the next run retries it.
+      }
+    }
+    return events;
+  }
 
-    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.
+  // resolve reads a push's authoritative outcome from Daraja and maps it to a protocol
+  // event, the single mapping both the callback and the reconcile timer go through. A
+  // push still processing yields no event and stays pending for a later look; a settled
+  // or failed one is marked resolved so it is not queried again. The settled amount is
+  // the one we recorded when the STK push fixed it, never read from the unsigned
+  // callback: a payer approves that exact amount or cancels, and reading it from a body
+  // whose checkout id is not a secret would let a forged callback carry a wrong amount
+  // and block a collection the payer completed. receipt is the callback's audit
+  // reference; the reconcile path, which has no callback body, passes none.
+  private async resolve(rec: PushRecord, receipt: string): Promise<AdapterEvent[]> {
+    const confirmed = await this.api.query(rec.checkoutId);
     if (confirmed.pending) {
       return [];
     }
+    await this.store.resolve(rec.checkoutId);
     if (confirmed.resultCode !== 0) {
       return [
         {
           intentId: rec.intentId,
           state: State.Failed,
-          providerTxRef: cb.CheckoutRequestID,
+          providerTxRef: rec.checkoutId,
           onchainTxHash: "",
           reason: confirmed.resultDesc,
           settledAt: 0,
         },
       ];
     }
-    // The STK push fixed the amount we authorized; a payer approves that exact amount
-    // or cancels, so an approved collection is always the full authorized amount. The
-    // authenticated query above confirms success, so the settled amount is the one we
-    // recorded — it is never read from the unsigned callback, since a forged callback
-    // (the checkout id is not a secret) could otherwise carry a wrong amount and block
-    // a collection the payer completed. The receipt is an audit reference only.
-    const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
     return [
       {
         intentId: rec.intentId,