@myzonerocks/pact 0.1.0

package/dist/src/adapter.d.ts

@@ -0,0 +1,18 @@
+import type { State } from "./state.js";
+export declare enum RefundKind {
+    None = 0,
+    Full = 1,
+    Partial = 2,
+    CounterTransfer = 3
+}
+export interface AdapterEvent {
+    intentId: string;
+    state: State;
+    providerTxRef: string;
+    onchainTxHash: string;
+    reason: string;
+    settledAt: number;
+}
+export interface WebhookParser {
+    parseWebhook(raw: Uint8Array, headers: Record<string, string[]>): AdapterEvent[];
+}

package/dist/src/adapter.js

@@ -0,0 +1,11 @@
+// RefundKind is the shape of refund a rail can perform. A card network can
+// reverse part of a capture; an irreversible rail can only answer with a
+// counter-transfer. A leg declares the truth in its capabilities and the kernel
+// holds it to it.
+export var RefundKind;
+(function (RefundKind) {
+    RefundKind[RefundKind["None"] = 0] = "None";
+    RefundKind[RefundKind["Full"] = 1] = "Full";
+    RefundKind[RefundKind["Partial"] = 2] = "Partial";
+    RefundKind[RefundKind["CounterTransfer"] = 3] = "CounterTransfer";
+})(RefundKind || (RefundKind = {}));

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

@@ -0,0 +1,43 @@
+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";
+export interface Call {
+    to: string;
+    data: string;
+}
+export interface ChainReceipt {
+    status: "success" | "reverted" | "pending";
+    blockTimestampMs: number;
+}
+export interface ChainClient {
+    send(call: Call): Promise<string>;
+    receipt(txHash: string): Promise<ChainReceipt>;
+}
+export interface Erc20Config {
+    id?: string;
+    token: string;
+    currency: string;
+    rail?: string;
+    chain: ChainClient;
+    ids: () => string;
+}
+export declare class Erc20Leg implements PayInLeg, PayOutLeg {
+    readonly id: string;
+    private readonly token;
+    private readonly currency;
+    private readonly rail;
+    private readonly chain;
+    private readonly ids;
+    private readonly sent;
+    constructor(cfg: Erc20Config);
+    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>;
+    settlementEvent(intentId: string): Promise<AdapterEvent>;
+    private transfer;
+    private terminal;
+}
+export declare function transferCalldata(recipient: string, amount: bigint): string;

package/dist/src/adapters/erc20.js

@@ -0,0 +1,126 @@
+// ERC-20 leg for the PACT protocol. It is architecture-neutral: signing and
+// broadcast go through an injected chain client, so where the private key lives —
+// on a device, in a server HSM, behind a smart-account validator — is the
+// adopter's decision, not this package's. The leg never holds key material and
+// never prompts for one. It serves both sides of a corridor: as a pay-in leg it
+// moves the payer's tokens to a destination, as a pay-out leg it delivers tokens
+// to the recipient.
+import { State } from "../state.js";
+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";
+// 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 {
+    id;
+    token;
+    currency;
+    rail;
+    chain;
+    ids;
+    sent = new Map();
+    constructor(cfg) {
+        if (!cfg.token || !cfg.currency) {
+            throw new Error("erc20: config requires a token address and currency");
+        }
+        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;
+    }
+    payInCapabilities() {
+        return { rails: [this.rail], currencies: [this.currency], refunds: RefundKind.CounterTransfer };
+    }
+    payOutCapabilities() {
+        return { rails: [this.rail], currencies: [this.currency], reversible: false };
+    }
+    // collect moves the payer's tokens to the destination — the recipient for a
+    // 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) {
+        const net = quote.srcAmount.sub(quote.fees);
+        const txHash = await this.transfer(deliverTo, net.value());
+        this.sent.set(intentId, txHash);
+        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);
+        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);
+    }
+    async reverseOut(intentId, reason) {
+        return this.terminal(intentId, reason);
+    }
+    // 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.
+    async settlementEvent(intentId) {
+        const txHash = this.sent.get(intentId);
+        if (!txHash) {
+            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,
+        };
+    }
+    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.
+export function transferCalldata(recipient, amount) {
+    const address = recipient.toLowerCase().replace(/^0x/, "");
+    if (!/^[0-9a-f]{40}$/.test(address)) {
+        throw new Error("erc20: recipient is not a 20-byte address");
+    }
+    if (amount < 0n) {
+        throw new Error("erc20: amount must be non-negative");
+    }
+    const amountHex = amount.toString(16);
+    if (amountHex.length > 64) {
+        throw new Error("erc20: amount exceeds a 256-bit word");
+    }
+    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;
+    }
+}

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

@@ -0,0 +1,61 @@
+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";
+export declare const ErrUnknownCheckout = "mpesa: callback for an unknown checkout request";
+export interface StkPushParams {
+    amount: number;
+    payerPhone: string;
+    accountReference: string;
+    description: string;
+    callbackURL: string;
+}
+export interface StkPushResult {
+    merchantRequestId: string;
+    checkoutRequestId: string;
+    responseCode: string;
+}
+export interface B2CParams {
+    amount: number;
+    phone: string;
+    reference: string;
+    remarks: string;
+}
+export interface B2CResult {
+    conversationId: string;
+    responseCode: string;
+}
+export interface DarajaApi {
+    stkPush(params: StkPushParams): Promise<StkPushResult>;
+    b2cPayment(params: B2CParams): Promise<B2CResult>;
+}
+export interface MpesaConfig {
+    id?: string;
+    api: DarajaApi;
+    callbackURL: string;
+    ids: () => string;
+}
+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;
+    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>;
+    reverseOut(_intentId: string, _reason: string): Promise<Settlement>;
+    parseWebhook(raw: Uint8Array, _headers: Record<string, string[]>): AdapterEvent[];
+}
+export declare function normalizePhone(phone: string): string;
+export interface Credentials {
+    consumerKey: string;
+    consumerSecret: string;
+    shortCode: string;
+    passkey: string;
+    baseURL?: string;
+}
+export declare function newHttpDarajaApi(creds: Credentials, now?: () => Date): DarajaApi;

package/dist/src/adapters/mpesa.js

@@ -0,0 +1,272 @@
+import { State } from "../state.js";
+import { RefundKind } from "../adapter.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";
+// ErrUnknownCheckout reports a callback whose CheckoutRequestID does not match a
+// push this leg initiated. Daraja does not sign callbacks, so matching the
+// 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";
+// MpesaLeg moves mobile money over M-Pesa.
+export class MpesaLeg {
+    id;
+    api;
+    callbackURL;
+    ids;
+    byIntent = new Map();
+    byCheckout = new Map();
+    constructor(cfg) {
+        if (!cfg.callbackURL) {
+            throw new Error("mpesa: config requires a callback URL");
+        }
+        this.id = cfg.id ?? "mpesa";
+        this.api = cfg.api;
+        this.callbackURL = cfg.callbackURL;
+        this.ids = cfg.ids;
+    }
+    payInCapabilities() {
+        return { rails: ["mpesa"], currencies: ["KES"], refunds: RefundKind.CounterTransfer };
+    }
+    payOutCapabilities() {
+        return { rails: ["mpesa"], currencies: ["KES"], reversible: false };
+    }
+    // collect triggers the STK push that prompts the payer to approve on their
+    // handset. deliverTo is the payer's phone the prompt is sent to; the pact intent
+    // id rides along as the account reference, and the returned checkout id is mapped
+    // back to the intent so the unsigned callback can be tied to it. The collection
+    // resolves out of band through the callback; collect returns the checkout id as
+    // its provider reference. received is the net a bridge would convert.
+    async collect(intentId, quote, _auth, deliverTo) {
+        const amount = wholeShillings(quote.srcAmount);
+        const net = quote.srcAmount.sub(quote.fees);
+        const phone = normalizePhone(deliverTo);
+        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,
+            accountReference: intentId,
+            description: "payment",
+            callbackURL: this.callbackURL,
+        });
+        this.byIntent.set(intentId, rec);
+        this.byCheckout.set(result.checkoutRequestId, rec);
+        return { providerRef: result.checkoutRequestId, received: net };
+    }
+    // disburse delivers the recipient's shillings by a business-to-customer payout
+    // and returns the Daraja conversation id.
+    async disburse(intentId, quote, recipientRef) {
+        const amount = wholeShillings(quote.dstAmount);
+        const phone = normalizePhone(recipientRef);
+        if (!phone) {
+            throw new Error("mpesa: disburse requires the recipient's phone");
+        }
+        const result = await this.api.b2cPayment({ amount, phone, reference: intentId, remarks: "payout" });
+        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) {
+        if (kind !== RefundKind.CounterTransfer) {
+            throw new Error("mpesa: a collection can only be refunded by counter-transfer");
+        }
+        const rec = this.byIntent.get(intentId);
+        if (!rec) {
+            throw new Error(`mpesa: no push for intent ${intentId}`);
+        }
+        const result = await this.api.b2cPayment({
+            amount: rec.amount,
+            phone: rec.payerPhone,
+            reference: intentId,
+            remarks: reason,
+        });
+        return {
+            intentId,
+            state: State.Refunded,
+            adapterId: this.id,
+            providerTxRef: result.conversationId,
+            onchainTxHash: "",
+            receiptHash: new Uint8Array(0),
+            reason,
+            settledAt: 0,
+        };
+    }
+    // reverseOut reports the truth of the rail: a delivered payout cannot be pulled
+    // back, so a pay-out reversal is refused rather than faked.
+    async reverseOut(_intentId, _reason) {
+        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) {
+        const envelope = JSON.parse(new TextDecoder().decode(raw));
+        const cb = envelope.Body?.stkCallback;
+        const rec = cb ? this.byCheckout.get(cb.CheckoutRequestID) : undefined;
+        if (!cb || !rec) {
+            throw new Error(ErrUnknownCheckout);
+        }
+        if (cb.ResultCode !== 0) {
+            rec.state = State.Failed;
+            return [
+                {
+                    intentId: rec.intentId,
+                    state: State.Failed,
+                    providerTxRef: cb.CheckoutRequestID,
+                    onchainTxHash: "",
+                    reason: cb.ResultDesc ?? "",
+                    settledAt: 0,
+                },
+            ];
+        }
+        const receipt = metadataString(cb.CallbackMetadata?.Item ?? [], "MpesaReceiptNumber");
+        rec.state = State.Settled;
+        return [
+            {
+                intentId: rec.intentId,
+                state: State.Settled,
+                providerTxRef: receipt,
+                onchainTxHash: "",
+                reason: "",
+                settledAt: 0,
+            },
+        ];
+    }
+}
+// wholeShillings narrows a KES amount to the integer M-Pesa moves. M-Pesa
+// transacts whole shillings, so a fractional exponent is refused rather than
+// silently truncated.
+function wholeShillings(m) {
+    if (m.exponent !== 0) {
+        throw new Error(`mpesa: KES amounts must use exponent 0 (whole shillings), got ${m.exponent}`);
+    }
+    const amount = m.value();
+    if (amount > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error("mpesa: amount exceeds range");
+    }
+    return Number(amount);
+}
+// metadataString pulls a named string value out of the callback metadata items.
+function metadataString(items, name) {
+    for (const item of items) {
+        if (item.Name !== name) {
+            continue;
+        }
+        if (typeof item.Value === "string") {
+            return item.Value;
+        }
+        return String(item.Value);
+    }
+    return "";
+}
+// normalizePhone trims a Kenyan MSISDN into the 2547XXXXXXXX form Daraja expects,
+// accepting the common 07XX and +2547XX inputs.
+export function normalizePhone(phone) {
+    let p = phone.trim();
+    if (p.startsWith("+")) {
+        p = p.slice(1);
+    }
+    if (p.startsWith("0")) {
+        return "254" + p.slice(1);
+    }
+    return p;
+}
+// httpDarajaApi is the live Daraja client. It fetches an OAuth token and signs
+// each STK push with the timestamped password Daraja expects.
+class HttpDarajaApi {
+    creds;
+    baseURL;
+    now;
+    constructor(creds, now) {
+        this.creds = creds;
+        this.baseURL = creds.baseURL || defaultBaseURL;
+        this.now = now;
+    }
+    async token() {
+        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`, {
+            method: "GET",
+            headers: { Authorization: `Basic ${basic}` },
+        });
+        if (resp.status >= 300) {
+            throw new Error(`mpesa: /oauth/v1/generate returned ${resp.status}`);
+        }
+        const out = (await resp.json());
+        return out.access_token ?? "";
+    }
+    // password is the base64 of shortcode+passkey+timestamp Daraja requires on each
+    // STK push.
+    password(timestamp) {
+        return Buffer.from(this.creds.shortCode + this.creds.passkey + timestamp).toString("base64");
+    }
+    async stkPush(params) {
+        const token = await this.token();
+        const timestamp = formatTimestamp(this.now());
+        const body = {
+            BusinessShortCode: this.creds.shortCode,
+            Password: this.password(timestamp),
+            Timestamp: timestamp,
+            TransactionType: "CustomerPayBillOnline",
+            Amount: params.amount,
+            PartyA: params.payerPhone,
+            PartyB: this.creds.shortCode,
+            PhoneNumber: params.payerPhone,
+            CallBackURL: params.callbackURL,
+            AccountReference: params.accountReference,
+            TransactionDesc: params.description,
+        };
+        const out = await this.postJSON(token, "/mpesa/stkpush/v1/processrequest", body);
+        return {
+            merchantRequestId: out.MerchantRequestID ?? "",
+            checkoutRequestId: out.CheckoutRequestID ?? "",
+            responseCode: out.ResponseCode ?? "",
+        };
+    }
+    async b2cPayment(params) {
+        const token = await this.token();
+        const body = {
+            InitiatorName: this.creds.shortCode,
+            CommandID: "BusinessPayment",
+            Amount: params.amount,
+            PartyA: this.creds.shortCode,
+            PartyB: params.phone,
+            Remarks: params.remarks,
+            Occasion: params.reference,
+        };
+        const out = await this.postJSON(token, "/mpesa/b2c/v3/paymentrequest", body);
+        return { conversationId: out.ConversationID ?? "", responseCode: out.ResponseCode ?? "" };
+    }
+    async postJSON(token, path, body) {
+        const resp = await fetch(this.baseURL + path, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+            body: JSON.stringify(body),
+        });
+        if (resp.status >= 300) {
+            throw new Error(`mpesa: ${path} returned ${resp.status}`);
+        }
+        return (await resp.json());
+    }
+}
+// formatTimestamp renders a Date as the yyyyMMddHHmmss string Daraja stamps each
+// push with.
+function formatTimestamp(d) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return (String(d.getFullYear()) +
+        pad(d.getMonth() + 1) +
+        pad(d.getDate()) +
+        pad(d.getHours()) +
+        pad(d.getMinutes()) +
+        pad(d.getSeconds()));
+}
+// newHttpDarajaApi builds a live Daraja client. now is injectable so the STK
+// timestamp and password are deterministic in tests.
+export function newHttpDarajaApi(creds, now = () => new Date()) {
+    return new HttpDarajaApi(creds, now);
+}

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

@@ -0,0 +1,68 @@
+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";
+export declare const ErrSignatureMismatch = "paypal: webhook signature does not verify";
+export interface CreateOrderParams {
+    value: string;
+    currencyCode: string;
+    payee: string;
+    referenceId: string;
+}
+export interface Capture {
+    orderId: string;
+    captureId: string;
+    status: string;
+}
+export interface PayoutParams {
+    value: string;
+    currencyCode: string;
+    receiver: string;
+    referenceId: string;
+}
+export interface Payout {
+    batchId: string;
+    status: string;
+}
+export interface RefundParams {
+    captureId: string;
+    reason: string;
+}
+export interface Refund {
+    id: string;
+    status: string;
+}
+export interface PaypalApi {
+    createAndCaptureOrder(params: CreateOrderParams): Promise<Capture>;
+    sendPayout(params: PayoutParams): Promise<Payout>;
+    refundCapture(params: RefundParams): Promise<Refund>;
+    verifyWebhook(headers: Record<string, string[]>, body: Uint8Array): Promise<boolean>;
+}
+export interface PaypalConfig {
+    id?: string;
+    currencies: string[];
+    api: PaypalApi;
+    ids: () => string;
+}
+export declare class PaypalLeg implements PayInLeg, PayOutLeg {
+    readonly id: string;
+    private readonly currencies;
+    private readonly api;
+    private readonly ids;
+    private readonly captures;
+    constructor(cfg: PaypalConfig);
+    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>;
+    parseWebhook(raw: Uint8Array, headers: Record<string, string[]>): Promise<AdapterEvent[]>;
+}
+export declare function majorAmount(minor: string, exponent: number): string;
+export interface Credentials {
+    clientId: string;
+    clientSecret: string;
+    webhookId: string;
+    baseURL?: string;
+}
+export declare function newHttpPaypalApi(creds: Credentials, now?: () => number): PaypalApi;