@myzonerocks/pact 0.1.3 → 0.1.6

package/dist/src/adapters/paypal.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 { PayOutLeg, InteractivePayInLeg, PayInCapabilities, PayOutCapabilities, CollectResult, DisburseResult, PayInPreparation } from "../leg.js";
@@ -32,6 +33,8 @@ export interface Payout {
 export interface RefundParams {
     captureId: string;
     reason: string;
+    value?: string;
+    currencyCode?: string;
 }
 export interface Refund {
     id: string;
@@ -49,20 +52,38 @@ export interface PaypalConfig {
     currencies: string[];
     api: PaypalApi;
     ids: () => string;
+    store?: CaptureStore;
+}
+export interface CaptureRecord {
+    intentId: string;
+    captureId: string;
+    expected: {
+        value: string;
+        currency: string;
+    };
+}
+export interface CaptureStore {
+    save(rec: CaptureRecord): Promise<void>;
+    byIntent(intentId: string): Promise<CaptureRecord | undefined>;
+}
+export declare class MemoryCaptureStore implements CaptureStore {
+    private readonly byIntentMap;
+    save(rec: CaptureRecord): Promise<void>;
+    byIntent(intentId: string): Promise<CaptureRecord | undefined>;
 }
 export declare class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
     readonly id: string;
     private readonly currencies;
     private readonly api;
     private readonly ids;
-    private readonly captures;
+    private readonly store;
     constructor(cfg: PaypalConfig);
     payInCapabilities(): PayInCapabilities;
     payOutCapabilities(): PayOutCapabilities;
     collect(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<CollectResult>;
     prepare(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<PayInPreparation>;
     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[]>): Promise<AdapterEvent[]>;
 }

package/dist/src/adapters/paypal.js

@@ -6,6 +6,8 @@
 // can be refunded in full, but a delivered payout cannot be pulled back.
 import { State } from "../state.js";
 import { RefundKind } from "../adapter.js";
+import { idempotencyKey } from "../protocol.js";
+import { fetchWithTimeout } from "./http.js";
 // The public base of the PayPal REST API. It is the same for every live
 // integration and carries no secret; the sandbox host or a local test server is
 // injected instead.
@@ -15,25 +17,36 @@ const defaultBaseURL = "https://api-m.paypal.com";
 const referencePrefix = "pact:";
 // ErrSignatureMismatch reports a webhook PayPal could not authenticate.
 export const ErrSignatureMismatch = "paypal: webhook signature does not verify";
+// MemoryCaptureStore is the default in-process store.
+export class MemoryCaptureStore {
+    byIntentMap = new Map();
+    async save(rec) {
+        this.byIntentMap.set(rec.intentId, rec);
+    }
+    async byIntent(intentId) {
+        return this.byIntentMap.get(intentId);
+    }
+}
 // PaypalLeg moves money over PayPal, serving both sides of a corridor.
 export class PaypalLeg {
     id;
     currencies;
     api;
     ids;
-    captures = new Map();
+    store;
     constructor(cfg) {
         this.id = cfg.id ?? "paypal";
         this.currencies = cfg.currencies;
         this.api = cfg.api;
         this.ids = cfg.ids;
+        this.store = cfg.store ?? new MemoryCaptureStore();
     }
     payInCapabilities() {
         return {
             rails: ["paypal"],
             currencies: this.currencies,
             methods: ["paypal", "venmo", "card"],
-            refunds: RefundKind.Full,
+            refunds: RefundKind.Partial,
         };
     }
     payOutCapabilities() {
@@ -49,7 +62,11 @@ export class PaypalLeg {
             payee: deliverTo,
             referenceId: referencePrefix + intentId,
         });
-        this.captures.set(intentId, capture.captureId);
+        await this.store.save({
+            intentId,
+            captureId: capture.captureId,
+            expected: { value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent), currency: quote.srcAmount.currency },
+        });
         return { providerRef: capture.captureId, received: quote.srcAmount.sub(quote.fees) };
     }
     // prepare creates an order the payer approves and captures on their own device
@@ -69,6 +86,11 @@ export class PaypalLeg {
             params.platformFee = majorAmount(quote.fees.minor(), quote.fees.exponent);
         }
         const order = await this.api.createOrder(params);
+        await this.store.save({
+            intentId,
+            captureId: "",
+            expected: { value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent), currency: quote.srcAmount.currency },
+        });
         return { providerRef: order.id, clientSecret: order.id, method: "paypal" };
     }
     // disburse sends a payout of the recipient's amount to recipientRef and returns
@@ -82,18 +104,24 @@ export class PaypalLeg {
         });
         return { providerRef: payout.batchId };
     }
-    // refundIn reverses a captured payment in full. PayPal captures the order id in
-    // the capture id it returned from collect, so the refund binds to that
-    // reference.
-    async refundIn(intentId, kind, reason) {
-        if (kind !== RefundKind.Full) {
+    // refundIn reverses a captured payment, in full or in part. PayPal captures the
+    // order id in the capture id it returned from collect, so the refund binds to
+    // that reference; a partial refund names the amount to return.
+    async refundIn(intentId, kind, amount, reason) {
+        if (kind !== RefundKind.Full && kind !== RefundKind.Partial) {
             throw new Error(`paypal: cannot perform refund kind ${kind}`);
         }
-        const captureId = this.captures.get(intentId);
-        if (!captureId) {
+        const rec = await this.store.byIntent(intentId);
+        if (!rec || !rec.captureId) {
             throw new Error(`paypal: no capture for intent ${intentId}`);
         }
-        const refund = await this.api.refundCapture({ captureId, reason });
+        const captureId = rec.captureId;
+        // A partial refund names the amount in major units; a full refund leaves it
+        // absent so PayPal returns the whole capture.
+        const params = kind === RefundKind.Partial
+            ? { captureId, reason, value: majorAmount(amount.minor(), amount.exponent), currencyCode: amount.currency }
+            : { captureId, reason };
+        const refund = await this.api.refundCapture(params);
         return {
             intentId,
             state: State.Refunded,
@@ -123,8 +151,21 @@ export class PaypalLeg {
         const intentId = intentFromReference(resource.custom_id ?? "", resource.invoice_id ?? "");
         const providerRef = resource.id ?? "";
         switch (event.event_type) {
-            case "PAYMENT.CAPTURE.COMPLETED":
+            case "PAYMENT.CAPTURE.COMPLETED": {
+                // The custom_id that ties a capture to an intent is chosen by whoever
+                // created the order, so a genuine, signed capture for a different order can
+                // carry a target intent's id. Settle only when the captured amount and
+                // currency match what the intent was quoted to collect.
+                const rec = await this.store.byIntent(intentId);
+                if (!rec) {
+                    throw new Error(`paypal: capture for unknown intent ${JSON.stringify(intentId)}`);
+                }
+                const want = rec.expected;
+                if (resource.amount?.value !== want.value || resource.amount?.currency_code !== want.currency) {
+                    throw new Error(`paypal: captured ${resource.amount?.value} ${resource.amount?.currency_code} does not match the quoted ${want.value} ${want.currency}`);
+                }
                 return [oneEvent(intentId, State.Settled, providerRef, "")];
+            }
             case "PAYMENT.CAPTURE.DENIED":
                 return [oneEvent(intentId, State.Failed, providerRef, "capture denied")];
             case "PAYMENT.CAPTURE.REFUNDED":
@@ -182,7 +223,7 @@ class HttpPaypalApi {
             return this.token;
         }
         const basic = Buffer.from(`${this.creds.clientId}:${this.creds.clientSecret}`).toString("base64");
-        const resp = await fetch(`${this.baseURL}/v1/oauth2/token`, {
+        const resp = await fetchWithTimeout(`${this.baseURL}/v1/oauth2/token`, {
             method: "POST",
             headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
             body: "grant_type=client_credentials",
@@ -203,15 +244,12 @@ class HttpPaypalApi {
         if (params.payee) {
             unit.payee = { email_address: params.payee };
         }
-        const created = await this.postJSON("/v2/checkout/orders", {
-            intent: "CAPTURE",
-            purchase_units: [unit],
-        });
+        const created = await this.postJSON("/v2/checkout/orders", { intent: "CAPTURE", purchase_units: [unit] }, idempotencyKey(params.referenceId, "paypal-order"));
         const existing = firstCapture(created);
         if (existing) {
             return { orderId: created.id ?? "", captureId: existing.id ?? "", status: existing.status ?? "" };
         }
-        const captured = await this.postJSON(`/v2/checkout/orders/${encodeURIComponent(created.id ?? "")}/capture`, {});
+        const captured = await this.postJSON(`/v2/checkout/orders/${encodeURIComponent(created.id ?? "")}/capture`, {}, idempotencyKey(params.referenceId, "paypal-capture"));
         const capture = firstCapture(captured);
         if (!capture) {
             throw new Error(`paypal: order ${created.id} captured without a capture id`);
@@ -235,10 +273,7 @@ class HttpPaypalApi {
                 platform_fees: [{ amount: { currency_code: params.currencyCode, value: params.platformFee } }],
             };
         }
-        const created = await this.postJSON("/v2/checkout/orders", {
-            intent: "CAPTURE",
-            purchase_units: [unit],
-        });
+        const created = await this.postJSON("/v2/checkout/orders", { intent: "CAPTURE", purchase_units: [unit] }, idempotencyKey(params.referenceId, "paypal-order"));
         let approve = "";
         for (const link of created.links ?? []) {
             if (link.rel === "approve" || link.rel === "payer-action") {
@@ -267,7 +302,11 @@ class HttpPaypalApi {
         if (params.reason) {
             body.note_to_payer = params.reason;
         }
-        const out = await this.postJSON(`/v2/payments/captures/${encodeURIComponent(params.captureId)}/refund`, body);
+        // A partial refund names the amount; an absent value refunds the full capture.
+        if (params.value) {
+            body.amount = { value: params.value, currency_code: params.currencyCode };
+        }
+        const out = await this.postJSON(`/v2/payments/captures/${encodeURIComponent(params.captureId)}/refund`, body, idempotencyKey(params.captureId, "paypal-refund"));
         return { id: out.id ?? "", status: out.status ?? "" };
     }
     // verifyWebhook forwards the signature headers and the raw body to PayPal's
@@ -275,23 +314,46 @@ class HttpPaypalApi {
     // binds a payload to this integration; PayPal reports whether the signature is
     // authentic.
     async verifyWebhook(headers, body) {
-        const out = await this.postJSON("/v1/notifications/verify-webhook-signature", {
+        // PayPal's signature covers the exact bytes of the event it delivered, so the
+        // event is forwarded verbatim. Parsing and re-serializing it would reorder
+        // keys or restyle numbers and make an authentic webhook fail verification.
+        const rawEvent = new TextDecoder().decode(body);
+        const sentinel = "__pact_raw_webhook_event__";
+        const envelope = JSON.stringify({
             webhook_id: this.creds.webhookId,
             transmission_id: header(headers, "PayPal-Transmission-Id"),
             transmission_time: header(headers, "PayPal-Transmission-Time"),
             transmission_sig: header(headers, "PayPal-Transmission-Sig"),
             cert_url: header(headers, "PayPal-Cert-Url"),
             auth_algo: header(headers, "PayPal-Auth-Algo"),
-            webhook_event: JSON.parse(new TextDecoder().decode(body)),
+            webhook_event: sentinel,
         });
+        const payload = envelope.replace(`"${sentinel}"`, rawEvent);
+        const out = await this.postSerialized("/v1/notifications/verify-webhook-signature", payload);
         return out.verification_status === "SUCCESS";
     }
-    async postJSON(path, body) {
+    // requestId, when set, is sent as PayPal-Request-Id. PayPal deduplicates a
+    // mutation that carries a request id it has already seen, so a retry after a
+    // lost response reuses the first order, capture, or refund rather than creating
+    // a second.
+    async postJSON(path, body, requestId) {
+        return this.postSerialized(path, JSON.stringify(body), requestId);
+    }
+    // postSerialized posts an already-serialized JSON payload, so a caller that must
+    // control the exact bytes on the wire — a webhook forwarded verbatim — can do so.
+    async postSerialized(path, payload, requestId) {
         const token = await this.accessToken();
-        const resp = await fetch(this.baseURL + path, {
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+        };
+        if (requestId) {
+            headers["PayPal-Request-Id"] = requestId;
+        }
+        const resp = await fetchWithTimeout(this.baseURL + path, {
             method: "POST",
-            headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
-            body: JSON.stringify(body),
+            headers,
+            body: payload,
         });
         if (resp.status >= 300) {
             throw new Error(`paypal: ${path} returned ${resp.status}`);

package/dist/src/adapters/stripe.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 { InteractivePayInLeg, PayInCapabilities, CollectResult, PayInPreparation } from "../leg.js";
@@ -45,7 +46,7 @@ export interface StripeConfig {
     currencies: string[];
     api: StripeApi;
     webhookKey: string;
-    clock?: () => number;
+    clock: () => number;
     tolerance?: number;
     ids: () => string;
     methods?: string[];
@@ -63,7 +64,7 @@ export declare class StripeLeg implements InteractivePayInLeg {
     payInCapabilities(): PayInCapabilities;
     collect(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<CollectResult>;
     prepare(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<PayInPreparation>;
-    refundIn(intentId: string, kind: RefundKind, reason: string): Promise<Settlement>;
+    refundIn(intentId: string, kind: RefundKind, amount: Money, reason: string): Promise<Settlement>;
     parseWebhook(raw: Uint8Array, headers: Record<string, string[]>): AdapterEvent[];
 }
 export declare const ErrNoSignature = "stripe: missing signature header";

package/dist/src/adapters/stripe.js

@@ -8,6 +8,8 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { State } from "../state.js";
 import { RefundKind } from "../adapter.js";
+import { idempotencyKey } from "../protocol.js";
+import { fetchWithTimeout } from "./http.js";
 // The public base of the Stripe REST API. It is the same for every integration
 // and carries no secret; tests point the leg at a local server instead.
 const defaultBaseURL = "https://api.stripe.com";
@@ -20,8 +22,6 @@ const metadataIntentKey = "pact_intent_id";
 // defaultToleranceSeconds is how far a webhook timestamp may drift from now
 // before it is rejected as a possible replay.
 const defaultToleranceSeconds = 300;
-// The protocol identifier used to bind an idempotency key to one protocol step.
-const idPrefix = "pact";
 // Capture selects when the charge is captured. Manual creates the intent already
 // carrying a payment method for the server to capture immediately — the flow an
 // agent or a saved-card charge uses. OnConfirmation defers capture to the moment
@@ -48,11 +48,16 @@ export class StripeLeg {
         if (!cfg.webhookKey) {
             throw new Error("stripe: config requires a webhook signing key");
         }
+        // Without a clock every webhook timestamp reads as far in the past and
+        // silently fails the tolerance check, so a real webhook never verifies.
+        if (!cfg.clock) {
+            throw new Error("stripe: config requires a clock for webhook timestamp checks");
+        }
         this.id = cfg.id ?? "stripe";
         this.currencies = cfg.currencies;
         this.api = cfg.api;
         this.webhookKey = cfg.webhookKey;
-        this.clock = cfg.clock ?? (() => 0);
+        this.clock = cfg.clock;
         this.tolerance = cfg.tolerance ?? defaultToleranceSeconds;
         this.ids = cfg.ids;
         this.methods = cfg.methods;
@@ -106,12 +111,15 @@ export class StripeLeg {
     // refundIn reverses a captured payment, in full or in part. Stripe supports
     // both, so the leg accepts the full and partial refund kinds and rejects a
     // counter-transfer it cannot express.
-    async refundIn(intentId, kind, reason) {
+    async refundIn(intentId, kind, amount, reason) {
         if (kind !== RefundKind.Full && kind !== RefundKind.Partial) {
             throw new Error(`stripe: cannot perform refund kind ${kind}`);
         }
         const pi = await this.api.findPaymentIntent(intentId);
-        const refund = await this.api.createRefund({ paymentIntentId: pi.id, amount: 0, reason }, idempotencyKey(intentId, "refund"));
+        // Stripe refunds the full capture when no amount is set, so a full refund
+        // leaves amount zero and a partial one carries the exact minor units to return.
+        const minor = kind === RefundKind.Partial ? minorToInteger(amount) : 0;
+        const refund = await this.api.createRefund({ paymentIntentId: pi.id, amount: minor, reason }, idempotencyKey(intentId, "refund"));
         return {
             intentId,
             state: State.Refunded,
@@ -145,11 +153,6 @@ function signatureHeader(headers) {
     }
     return "";
 }
-// idempotencyKey binds a Stripe mutation to one protocol step so a retry reuses
-// the original result instead of acting twice.
-function idempotencyKey(ref, step) {
-    return `${idPrefix}:${ref}:${step}`;
-}
 // minorToInteger narrows a Money amount to the safe integer Stripe expects,
 // refusing anything that would overflow. Fiat amounts fit comfortably; the guard
 // exists so a token amount can never be sent to a card rail by mistake.
@@ -342,7 +345,7 @@ class HttpStripeApi {
             Authorization: `Bearer ${this.secretKey}`,
             "Stripe-Version": apiVersion,
         };
-        const resp = await fetch(this.baseURL + path, { ...init, headers });
+        const resp = await fetchWithTimeout(this.baseURL + path, { ...init, headers });
         const body = await resp.text();
         if (resp.status >= 300) {
             throw new Error(`stripe: ${path} returned ${resp.status}: ${stripeErrorMessage(body)}`);

package/dist/src/bridge.js

@@ -83,14 +83,21 @@ export function applyInverseRate(dst, rate, srcCurrency, srcExponent) {
 // parseRate reads a decimal rate like "129.45" into a numerator and denominator,
 // so the conversion stays exact integer arithmetic with no floating point.
 export function parseRate(rate) {
+    // Bound the length so an untrusted rate can't force a huge bigint parse and
+    // exponentiation in the FX math.
+    if (rate.length > 80) {
+        throw new Error("pact: rate has more than 80 characters");
+    }
+    // A non-negative integer part with no leading zeros and an optional fractional
+    // part; no sign, no radix prefix, no whitespace, matching the amount grammar so
+    // the SDKs never disagree on a rate's validity or value.
+    if (!/^(0|[1-9][0-9]*)(\.[0-9]+)?$/.test(rate)) {
+        throw new Error(`pact: ${JSON.stringify(rate)} is not a canonical decimal rate`);
+    }
     const dot = rate.indexOf(".");
     const whole = dot < 0 ? rate : rate.slice(0, dot);
     const frac = dot < 0 ? "" : rate.slice(dot + 1);
-    const digits = whole + frac;
-    if (!/^\d+$/.test(digits)) {
-        throw new Error(`pact: ${JSON.stringify(rate)} is not a decimal rate`);
-    }
-    const num = BigInt(digits);
+    const num = BigInt(whole + frac);
     const den = frac.length > 0 ? pow10(frac.length) : 1n;
     return [num, den];
 }

package/dist/src/canonical.js

@@ -20,6 +20,11 @@ export class CanonicalWriter {
         this.push(b);
         return this;
     }
+    // str writes a string as its raw UTF-8 bytes. No Unicode normalization is
+    // applied: the bytes are hashed as given, so two participants that compose the
+    // same text in different Unicode forms produce different hashes. Callers that
+    // need them to agree must normalize before building a message; string fields are
+    // otherwise treated as opaque bytes.
     str(s) {
         return this.bytes(encoder.encode(s));
     }

package/dist/src/client.d.ts

@@ -4,9 +4,9 @@ import { type Intent, type Quote, type Authorization, type Settlement } from "./
 import { type Signer, type Verifier } from "./signing.js";
 import { type Bridge } from "./bridge.js";
 import { type PayInLeg, type PayOutLeg, type PayInPreparation } from "./leg.js";
-import type { AdapterEvent } from "./adapter.js";
+import { type AdapterEvent } from "./adapter.js";
 import { type Policy } from "./router.js";
-import { type KycProvider, type RiskHook } from "./compliance.js";
+import { type KycProvider, type RiskHook, type SignerAuthorizer } from "./compliance.js";
 import { type Ledger, type LedgerEvent } from "./ledger.js";
 export type Clock = () => number;
 export type IdGen = () => string;
@@ -21,6 +21,7 @@ export interface ClientConfig {
     verifier: Verifier;
     kyc?: KycProvider;
     risk?: RiskHook;
+    signerAuth?: SignerAuthorizer;
     clock?: Clock;
     idGen?: IdGen;
     skew?: number;
@@ -49,6 +50,7 @@ export declare class Client {
     private readonly verifier;
     private readonly kyc;
     private readonly risk;
+    private readonly signerAuth;
     private readonly clock;
     private readonly idGen;
     private readonly skew;
@@ -63,6 +65,7 @@ export declare class Client {
     private pickBridge;
     select(quotes: Quote[], identity: string): Promise<Quote>;
     authorize(intent: Intent, quote: Quote, signer: Signer): Promise<Authorization>;
+    private resolvePayIn;
     initiate(intent: Intent, quote: Quote, auth: Authorization): Promise<State>;
     interactiveInitiate(intent: Intent, quote: Quote, auth: Authorization): Promise<{
         preparation: PayInPreparation;
@@ -74,7 +77,12 @@ export declare class Client {
     }>;
     private holdAndDisburse;
     private settleBridged;
+    private claimRefund;
     private unwind;
+    refund(intentId: string, amount: Money, reason: string): Promise<{
+        settlement: Settlement;
+        state: State;
+    }>;
     private recordFailure;
     private finishAdvance;
     private finish;