@myzonerocks/pact 0.1.0

package/dist/test/erc20.test.js

@@ -0,0 +1,131 @@
+import { describe, it, expect } from "vitest";
+import { Client } from "../src/client.js";
+import { Money } from "../src/money.js";
+import { State } from "../src/state.js";
+import { isDirect } from "../src/message.js";
+import { RefundKind } from "../src/adapter.js";
+import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
+import { fromHex } from "../src/crypto.js";
+import { Erc20Leg, transferCalldata } from "../src/adapters/erc20.js";
+function counter() {
+    let n = 0;
+    return () => `0xtx${String(++n).padStart(3, "0")}`;
+}
+function signerVerifier(identity) {
+    const seed = fromHex("00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff");
+    const signer = Ed25519Signer.fromSeed(identity, seed);
+    return { signer, verifier: new Ed25519Verifier(new Map([[identity, signer.publicKey]])) };
+}
+// FakeChain records the calls it is asked to broadcast and returns a receipt the
+// test controls, so the leg runs with no chain and no key.
+class FakeChain {
+    calls = [];
+    ids = counter();
+    status = "success";
+    async send(call) {
+        this.calls.push(call);
+        return this.ids();
+    }
+    async receipt(_txHash) {
+        return { status: this.status, blockTimestampMs: 1_700_000_005_000 };
+    }
+}
+const usdcToken = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
+const recipient = "0x00000000000000000000000000000000000000aa";
+describe("erc20 transfer calldata", () => {
+    it("encodes selector, padded address, and 32-byte amount", () => {
+        // 1_000_000 minor units of a 6-decimal token is one whole token: 0xf4240.
+        const data = transferCalldata(recipient, 1000000n);
+        expect(data).toBe("0xa9059cbb" +
+            "000000000000000000000000" + "00000000000000000000000000000000000000aa" +
+            "00000000000000000000000000000000000000000000000000000000000f4240");
+    });
+    it("rejects a non-address recipient and an oversized amount", () => {
+        expect(() => transferCalldata("0x1234", 1n)).toThrow();
+        expect(() => transferCalldata(recipient, 1n << 256n)).toThrow();
+    });
+});
+describe("erc20 direct corridor", () => {
+    const now = 1_700_000_000_000;
+    function build(chain) {
+        const { signer, verifier } = signerVerifier("alice");
+        const leg = new Erc20Leg({ token: usdcToken, currency: "USDC", chain, ids: counter() });
+        const client = new Client({ payIn: [leg], payOut: [leg], verifier, clock: () => now, idGen: counter() });
+        return { signer, leg, client };
+    }
+    it("settles a token transfer through the kernel", async () => {
+        const chain = new FakeChain();
+        const { signer, client } = build(chain);
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: Money.parse("USDC", 6, "1000000"),
+            expiresAt: now + 600_000,
+            allowedRails: ["erc20"],
+            metadata: { recipient_destination: recipient },
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "erc20", currency: "USDC", exponent: 6 }]);
+        const quote = await client.select(quotes, signer.identity());
+        expect(isDirect(quote)).toBe(true);
+        expect(quote.fees.minor()).toBe("0");
+        expect(quote.srcAmount.minor()).toBe("1000000");
+        const auth = await client.authorize(intent, quote, signer);
+        await client.initiate(intent, quote, auth);
+        await client.advance(intent.id, "erc20", { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 });
+        expect(client.state(intent.id)).toBe(State.Settled);
+        // The broadcast call carried the correct token contract and transfer calldata.
+        expect(chain.calls).toHaveLength(1);
+        expect(chain.calls[0].to).toBe(usdcToken);
+        expect(chain.calls[0].data).toBe(transferCalldata(recipient, 1000000n));
+    });
+    it("only refunds by counter-transfer", async () => {
+        const chain = new FakeChain();
+        const { leg } = build(chain);
+        await leg.collect("intent-1", {
+            id: "q",
+            intentId: "intent-1",
+            payInAdapterId: "erc20",
+            payInRail: "erc20",
+            payOutAdapterId: "erc20",
+            payOutRail: "erc20",
+            bridgeId: "passthrough",
+            srcAmount: Money.parse("USDC", 6, "1000000"),
+            dstAmount: Money.parse("USDC", 6, "1000000"),
+            fees: Money.parse("USDC", 6, "0"),
+            fxRate: "1",
+            expiresAt: 0,
+            providerQuoteRef: "",
+            latencyEstimateMs: 0,
+        }, {
+            intentId: "intent-1",
+            quoteId: "q",
+            signerIdentity: "",
+            signedAt: 0,
+            signature: new Uint8Array(0),
+        }, recipient);
+        await expect(leg.refundIn("intent-1", RefundKind.Full, "x")).rejects.toThrow();
+        const settlement = await leg.refundIn("intent-1", RefundKind.CounterTransfer, "returning funds");
+        expect(settlement.state).toBe(State.Refunded);
+    });
+    it("fails the intent when the transaction reverts", async () => {
+        const chain = new FakeChain();
+        chain.status = "reverted";
+        const { signer, client, leg } = build(chain);
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: Money.parse("USDC", 6, "500000"),
+            expiresAt: now + 600_000,
+            allowedRails: ["erc20"],
+            metadata: { recipient_destination: recipient },
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "erc20", currency: "USDC", exponent: 6 }]);
+        const quote = await client.select(quotes, signer.identity());
+        const auth = await client.authorize(intent, quote, signer);
+        await client.initiate(intent, quote, auth);
+        // A direct corridor broadcasts on initiate; the host polls the receipt to
+        // learn the transaction reverted on chain.
+        const event = await leg.settlementEvent(intent.id);
+        expect(event.state).toBe(State.Failed);
+    });
+});

package/dist/test/lifecycle.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/lifecycle.test.js

@@ -0,0 +1,212 @@
+import { describe, it, expect } from "vitest";
+import { Client } from "../src/client.js";
+import { Money } from "../src/money.js";
+import { State } from "../src/state.js";
+import { isDirect } from "../src/message.js";
+import { UsdcBridge } from "../src/bridge.js";
+import { FakeLeg, FakeRates, FakeVault } from "../src/fake.js";
+import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
+import { fromHex } from "../src/crypto.js";
+function counter() {
+    let n = 0;
+    return () => `id-${String(++n).padStart(3, "0")}`;
+}
+function signerVerifier(identity) {
+    const seed = fromHex("00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff");
+    const signer = Ed25519Signer.fromSeed(identity, seed);
+    return { signer, verifier: new Ed25519Verifier(new Map([[identity, signer.publicKey]])) };
+}
+const now = 1_700_000_000_000;
+describe("corridor lifecycle", () => {
+    // A direct corridor: one provider serves both legs in one currency, so the
+    // pay-in collects straight to the recipient and settlement is single-phase.
+    it("settles a direct corridor in one phase and folds a Merkle head", async () => {
+        const { signer, verifier } = signerVerifier("alice");
+        const wallet = new FakeLeg("wallet", "wallet", "USD", counter());
+        const client = new Client({
+            payIn: [wallet],
+            payOut: [wallet],
+            verifier,
+            clock: () => now,
+            idGen: counter(),
+        });
+        let settled = false;
+        client.subscribe((e) => {
+            if (e.state === State.Settled)
+                settled = true;
+        });
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: Money.parse("USD", 2, "1500"),
+            memo: "lunch",
+            expiresAt: now + 600_000,
+            allowedRails: ["wallet"],
+        });
+        expect(client.state(intent.id)).toBe(State.Draft);
+        const funding = [{ payInAdapterId: "wallet", currency: "USD", exponent: 2 }];
+        const quotes = await client.quoteOptions(intent, funding);
+        const quote = await client.select(quotes, signer.identity());
+        expect(isDirect(quote)).toBe(true);
+        expect(quote.srcAmount.minor()).toBe("1500");
+        expect(quote.dstAmount.minor()).toBe("1500");
+        const auth = await client.authorize(intent, quote, signer);
+        expect(client.state(intent.id)).toBe(State.Authorized);
+        await client.initiate(intent, quote, auth);
+        // The pay-in provider confirms out of band; a direct corridor then settles.
+        await client.advance(intent.id, "wallet", { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 });
+        expect(client.state(intent.id)).toBe(State.Settled);
+        expect(settled).toBe(true);
+        const states = client.history(intent.id).map((e) => e.state);
+        expect(states).toEqual([State.Draft, State.Quoted, State.Authorized, State.Submitted, State.Settled]);
+        expect(client.head(intent.id)).toBeDefined();
+    });
+    // A bridged corridor: the payer funds in USD by card, a USDC bridge converts to
+    // KES, and an M-Pesa leg delivers to the recipient.
+    it("settles a bridged card-USD to USDC to mpesa-KES corridor end to end", async () => {
+        const { signer, verifier } = signerVerifier("alice");
+        const card = new FakeLeg("card", "card", "USD", counter());
+        const mpesa = new FakeLeg("mpesa", "mpesa", "KES", counter());
+        const bridge = new UsdcBridge(new FakeRates({ "USD:KES": "129" }), new FakeVault(), 100n);
+        const client = new Client({
+            payIn: [card],
+            payOut: [mpesa],
+            bridges: [bridge],
+            verifier,
+            clock: () => now,
+            idGen: counter(),
+            escrowRef: "escrow",
+        });
+        // The recipient requests 1290 KES.
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: Money.parse("KES", 0, "1290"),
+            expiresAt: now + 600_000,
+            allowedRails: ["mpesa"],
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "card", currency: "USD", exponent: 2 }]);
+        const quote = await client.select(quotes, signer.identity());
+        expect(isDirect(quote)).toBe(false);
+        // 1290 KES at 129 KES/USD is 10.00 USD, plus a 1% bridge fee = 10.10 USD.
+        expect(quote.srcAmount.minor()).toBe("1010");
+        expect(quote.srcAmount.currency).toBe("USD");
+        expect(quote.dstAmount.minor()).toBe("1290");
+        expect(quote.dstAmount.currency).toBe("KES");
+        const auth = await client.authorize(intent, quote, signer);
+        await client.initiate(intent, quote, auth);
+        const confirm = { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 };
+        // The pay-in webhook drives collecting -> held -> disbursing; the corridor now
+        // waits on the pay-out.
+        const held = await client.advance(intent.id, "card", confirm);
+        expect(held.state).toBe(State.Disbursing);
+        // The pay-out callback settles it.
+        const { settlement } = await client.advance(intent.id, "mpesa", confirm);
+        expect(settlement.state).toBe(State.Settled);
+        const states = client.history(intent.id).map((e) => e.state);
+        expect(states).toEqual([
+            State.Draft,
+            State.Quoted,
+            State.Authorized,
+            State.Collecting,
+            State.Held,
+            State.Disbursing,
+            State.Settled,
+        ]);
+    });
+    // When the pay-out cannot complete, the corridor unwinds from escrow: held ->
+    // refunding -> refunded, so the payer is made whole.
+    it("unwinds a bridged corridor to refunded when the pay-out fails", async () => {
+        const { signer, verifier } = signerVerifier("alice");
+        const card = new FakeLeg("card", "card", "USD", counter());
+        const mpesa = new FakeLeg("mpesa", "mpesa", "KES", counter());
+        mpesa.failPayout = true;
+        const bridge = new UsdcBridge(new FakeRates({ "USD:KES": "129" }), new FakeVault(), 0n);
+        const client = new Client({
+            payIn: [card],
+            payOut: [mpesa],
+            bridges: [bridge],
+            verifier,
+            clock: () => now,
+            idGen: counter(),
+            escrowRef: "escrow",
+        });
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: Money.parse("KES", 0, "1290"),
+            expiresAt: now + 600_000,
+            allowedRails: ["mpesa"],
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "card", currency: "USD", exponent: 2 }]);
+        const quote = await client.select(quotes, signer.identity());
+        const auth = await client.authorize(intent, quote, signer);
+        await client.initiate(intent, quote, auth);
+        // The pay-in confirms, but the pay-out leg fails; the corridor unwinds from
+        // escrow rather than erroring.
+        const { settlement } = await client.advance(intent.id, "card", { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 });
+        expect(settlement.state).toBe(State.Refunded);
+        expect(client.state(intent.id)).toBe(State.Refunded);
+        // The escrow-unwind path must have been traversed.
+        const states = client.history(intent.id).map((e) => e.state);
+        expect(states).toContain(State.Held);
+        expect(states).toContain(State.Refunding);
+        expect(states[states.length - 1]).toBe(State.Refunded);
+    });
+    // A re-delivered provider webhook must not advance the corridor twice.
+    it("advances idempotently so a duplicate webhook settles once", async () => {
+        const { signer, verifier } = signerVerifier("alice");
+        const card = new FakeLeg("card", "card", "USD", counter());
+        const mpesa = new FakeLeg("mpesa", "mpesa", "KES", counter());
+        const bridge = new UsdcBridge(new FakeRates({ "USD:KES": "129" }), new FakeVault(), 0n);
+        const client = new Client({
+            payIn: [card],
+            payOut: [mpesa],
+            bridges: [bridge],
+            verifier,
+            clock: () => now,
+            idGen: counter(),
+            escrowRef: "escrow",
+        });
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: Money.parse("KES", 0, "1290"),
+            expiresAt: now + 600_000,
+            allowedRails: ["mpesa"],
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "card", currency: "USD", exponent: 2 }]);
+        const quote = await client.select(quotes, signer.identity());
+        const auth = await client.authorize(intent, quote, signer);
+        await client.initiate(intent, quote, auth);
+        const confirm = { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 };
+        // The pay-in webhook is delivered twice; the second must be a no-op.
+        await client.advance(intent.id, "card", confirm);
+        const duplicate = await client.advance(intent.id, "card", confirm);
+        expect(duplicate.state).toBe(State.Disbursing);
+        // The pay-out callback settles it once.
+        await client.advance(intent.id, "mpesa", confirm);
+        expect(client.state(intent.id)).toBe(State.Settled);
+        const disbursing = client.history(intent.id).filter((e) => e.state === State.Disbursing).length;
+        expect(disbursing).toBe(1);
+    });
+    it("expires idempotently", () => {
+        const { verifier } = signerVerifier("alice");
+        const client = new Client({
+            payIn: [new FakeLeg("wallet", "wallet", "USD", counter())],
+            verifier,
+            clock: () => 1,
+            idGen: counter(),
+        });
+        const intent = client.createIntent({
+            senderRef: "a",
+            recipientRef: "b",
+            amount: Money.parse("USD", 2, "100"),
+            expiresAt: 0,
+            allowedRails: ["wallet"],
+        });
+        client.expire(intent.id);
+        expect(client.state(intent.id)).toBe(State.Expired);
+        expect(() => client.expire(intent.id)).not.toThrow();
+    });
+});

package/dist/test/mpesa.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/mpesa.test.js

@@ -0,0 +1,180 @@
+import { describe, it, expect } from "vitest";
+import { Client } from "../src/client.js";
+import { Money } from "../src/money.js";
+import { State } from "../src/state.js";
+import { isDirect } from "../src/message.js";
+import { RefundKind } from "../src/adapter.js";
+import { UsdcBridge } from "../src/bridge.js";
+import { FakeLeg, FakeRates, FakeVault } from "../src/fake.js";
+import { Ed25519Signer, Ed25519Verifier } from "../src/signing.js";
+import { fromHex } from "../src/crypto.js";
+import { MpesaLeg, ErrUnknownCheckout, normalizePhone, } from "../src/adapters/mpesa.js";
+function counter(prefix) {
+    let n = 0;
+    return () => `${prefix}_${String(++n).padStart(3, "0")}`;
+}
+function signerVerifier(identity) {
+    const seed = fromHex("00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff");
+    const signer = Ed25519Signer.fromSeed(identity, seed);
+    return { signer, verifier: new Ed25519Verifier(new Map([[identity, signer.publicKey]])) };
+}
+// FakeDaraja is an in-memory stand-in for Daraja so the leg runs end to end with
+// no network and no credentials.
+class FakeDaraja {
+    lastPush;
+    lastB2C;
+    ids;
+    constructor(ids) {
+        this.ids = ids;
+    }
+    async stkPush(params) {
+        this.lastPush = params;
+        return { merchantRequestId: this.ids(), checkoutRequestId: this.ids(), responseCode: "0" };
+    }
+    async b2cPayment(params) {
+        this.lastB2C = params;
+        return { conversationId: this.ids(), responseCode: "0" };
+    }
+}
+function buildLeg(api) {
+    return new MpesaLeg({
+        api,
+        callbackURL: "https://host.example/paylink/webhook/mpesa",
+        ids: counter("mp"),
+    });
+}
+function kes(whole) {
+    return Money.parse("KES", 0, whole);
+}
+function quote(fields) {
+    return {
+        id: "q",
+        intentId: "intent-1",
+        payInAdapterId: "mpesa",
+        payInRail: "mpesa",
+        payOutAdapterId: "mpesa",
+        payOutRail: "mpesa",
+        bridgeId: "passthrough",
+        srcAmount: kes("0"),
+        dstAmount: kes("0"),
+        fees: kes("0"),
+        fxRate: "1",
+        expiresAt: 0,
+        providerQuoteRef: "",
+        latencyEstimateMs: 0,
+        ...fields,
+    };
+}
+const emptyAuth = {
+    intentId: "intent-1",
+    quoteId: "q",
+    signerIdentity: "",
+    signedAt: 0,
+    signature: new Uint8Array(0),
+};
+function successCallback(checkoutId, receipt) {
+    const json = `{"Body":{"stkCallback":{"MerchantRequestID":"m","CheckoutRequestID":${JSON.stringify(checkoutId)},"ResultCode":0,"ResultDesc":"Success","CallbackMetadata":{"Item":[{"Name":"Amount","Value":1500},{"Name":"MpesaReceiptNumber","Value":${JSON.stringify(receipt)}},{"Name":"PhoneNumber","Value":254711000111}]}}}}`;
+    return new TextEncoder().encode(json);
+}
+function failureCallback(checkoutId) {
+    const json = `{"Body":{"stkCallback":{"MerchantRequestID":"m","CheckoutRequestID":${JSON.stringify(checkoutId)},"ResultCode":1032,"ResultDesc":"Request cancelled by user"}}}`;
+    return new TextEncoder().encode(json);
+}
+describe("mpesa phone normalization", () => {
+    it("trims the common inputs to the 2547XXXXXXXX form", () => {
+        expect(normalizePhone("0711000111")).toBe("254711000111");
+        expect(normalizePhone("+254711000111")).toBe("254711000111");
+        expect(normalizePhone("254711000111")).toBe("254711000111");
+    });
+});
+describe("mpesa whole-shilling guard", () => {
+    it("refuses a fractional destination amount", async () => {
+        const leg = buildLeg(new FakeDaraja(counter("tx")));
+        const cents = Money.parse("KES", 2, "129000");
+        await expect(leg.disburse("intent-2", quote({ dstAmount: cents }), "0711000111")).rejects.toThrow();
+    });
+});
+describe("mpesa unknown checkout", () => {
+    it("rejects a callback whose checkout id it never started", () => {
+        const leg = buildLeg(new FakeDaraja(counter("tx")));
+        expect(() => leg.parseWebhook(successCallback("never-started", "ABC"), {})).toThrow(ErrUnknownCheckout);
+    });
+});
+describe("mpesa pay-out", () => {
+    it("delivers a whole-shilling payout to the normalized phone", async () => {
+        const api = new FakeDaraja(counter("tx"));
+        const leg = buildLeg(api);
+        const result = await leg.disburse("intent-1", quote({ dstAmount: kes("1290") }), "0711000111");
+        expect(result.providerRef).not.toBe("");
+        expect(api.lastB2C.phone).toBe("254711000111");
+        expect(api.lastB2C.amount).toBe(1290);
+    });
+});
+describe("mpesa bridged corridor", () => {
+    const now = 1_700_000_000_000;
+    it("pays out to the recipient's phone after a card-USD to USDC to KES conversion", async () => {
+        const { signer, verifier } = signerVerifier("alice");
+        const api = new FakeDaraja(counter("tx"));
+        const leg = buildLeg(api);
+        const card = new FakeLeg("card", "card", "USD", counter("card"));
+        const bridge = new UsdcBridge(new FakeRates({ "USD:KES": "129" }), new FakeVault(), 100n);
+        const client = new Client({
+            payIn: [card],
+            payOut: [leg],
+            bridges: [bridge],
+            verifier,
+            clock: () => now,
+            idGen: counter("intent"),
+            escrowRef: "escrow",
+        });
+        const intent = client.createIntent({
+            senderRef: "alice",
+            recipientRef: "bob",
+            amount: kes("1290"),
+            expiresAt: now + 600_000,
+            allowedRails: ["mpesa"],
+            metadata: { recipient_destination: "0711000111" },
+        });
+        const quotes = await client.quoteOptions(intent, [{ payInAdapterId: "card", currency: "USD", exponent: 2 }]);
+        const chosen = await client.select(quotes, signer.identity());
+        expect(isDirect(chosen)).toBe(false);
+        const auth = await client.authorize(intent, chosen, signer);
+        await client.initiate(intent, chosen, auth);
+        const confirm = { intentId: intent.id, state: State.Settled, providerTxRef: "", onchainTxHash: "", reason: "", settledAt: 0 };
+        await client.advance(intent.id, "card", confirm);
+        const { settlement } = await client.advance(intent.id, "mpesa", confirm);
+        expect(settlement.state).toBe(State.Settled);
+        expect(client.state(intent.id)).toBe(State.Settled);
+        // The pay-out delivered the whole 1290 KES to the recipient's normalized phone.
+        expect(api.lastB2C.phone).toBe("254711000111");
+        expect(api.lastB2C.amount).toBe(1290);
+    });
+});
+describe("mpesa pay-in", () => {
+    it("pushes, settles from the callback, and refunds by counter-transfer", async () => {
+        const api = new FakeDaraja(counter("tx"));
+        const leg = buildLeg(api);
+        const q = quote({ srcAmount: kes("1500"), fees: kes("0") });
+        const collected = await leg.collect("intent-1", q, emptyAuth, "0711000111");
+        expect(api.lastPush.accountReference).toBe("intent-1");
+        expect(api.lastPush.payerPhone).toBe("254711000111");
+        const events = leg.parseWebhook(successCallback(collected.providerRef, "QGR7XYZ123"), {});
+        expect(events).toHaveLength(1);
+        expect(events[0].state).toBe(State.Settled);
+        expect(events[0].intentId).toBe("intent-1");
+        expect(events[0].providerTxRef).toBe("QGR7XYZ123");
+        // A refund is a business-to-customer counter-transfer back to the payer.
+        await leg.refundIn("intent-1", RefundKind.CounterTransfer, "returning funds");
+        expect(api.lastB2C.phone).toBe("254711000111");
+        expect(api.lastB2C.amount).toBe(1500);
+    });
+    it("maps a cancelled push to a failed event", async () => {
+        const api = new FakeDaraja(counter("tx"));
+        const leg = buildLeg(api);
+        const q = quote({ srcAmount: kes("1500"), fees: kes("0") });
+        const collected = await leg.collect("intent-1", q, emptyAuth, "0711000111");
+        const events = leg.parseWebhook(failureCallback(collected.providerRef), {});
+        expect(events).toHaveLength(1);
+        expect(events[0].state).toBe(State.Failed);
+    });
+});

package/dist/test/payload.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/payload.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { Money } from "../src/money.js";
+import { WireKind } from "../src/wire.js";
+import { encodePayload, decodePayload, isPayload, NotPayloadError } from "../src/payload.js";
+const intent = {
+    id: "intent-1",
+    senderRef: "alice",
+    recipientRef: "bob",
+    amount: Money.parse("USD", 2, "1500"),
+    memo: "",
+    expiresAt: 0,
+    allowedRails: ["card"],
+    metadata: {},
+};
+describe("pact payload wrapper", () => {
+    it("round-trips a message through the self-identifying header", () => {
+        const payload = encodePayload({ kind: WireKind.Intent, message: intent });
+        expect(isPayload(payload)).toBe(true);
+        const decoded = decodePayload(payload);
+        expect(decoded.kind).toBe(WireKind.Intent);
+        expect(decoded.message.id).toBe(intent.id);
+    });
+    it("rejects foreign bytes", () => {
+        expect(isPayload(new TextEncoder().encode("hello there"))).toBe(false);
+        expect(() => decodePayload(new TextEncoder().encode("hello there"))).toThrow(NotPayloadError);
+    });
+    it("rejects an unknown framing version", () => {
+        const payload = encodePayload({ kind: WireKind.Intent, message: intent });
+        payload[4] = 0xff; // corrupt the version byte after the 4-byte magic
+        expect(() => decodePayload(payload)).toThrow();
+    });
+});

package/dist/test/paypal.test.d.ts

@@ -0,0 +1 @@
+export {};