@myzonerocks/pact 0.1.2 → 0.1.4

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.
@@ -22,6 +24,9 @@ export class PaypalLeg {
     api;
     ids;
     captures = new Map();
+    // What each intent was quoted to collect, so a capture webhook can be
+    // cross-checked: the paid amount and currency must match before it settles.
+    expected = new Map();
     constructor(cfg) {
         this.id = cfg.id ?? "paypal";
         this.currencies = cfg.currencies;
@@ -33,7 +38,7 @@ export class PaypalLeg {
             rails: ["paypal"],
             currencies: this.currencies,
             methods: ["paypal", "venmo", "card"],
-            refunds: RefundKind.Full,
+            refunds: RefundKind.Partial,
         };
     }
     payOutCapabilities() {
@@ -50,8 +55,35 @@ export class PaypalLeg {
             referenceId: referencePrefix + intentId,
         });
         this.captures.set(intentId, capture.captureId);
+        this.expected.set(intentId, {
+            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
+    // through the PayPal or Venmo flow — the interactive pay-in path — so nothing is
+    // captured here. The order names the recipient as payee and our cut as a platform
+    // fee; the buyer's capture then fires PAYMENT.CAPTURE.COMPLETED, which advances
+    // the corridor through the same pay-in path as a server-side collection. The
+    // order id is the token the payer's PayPal buttons need.
+    async prepare(intentId, quote, _auth, deliverTo) {
+        const params = {
+            value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent),
+            currencyCode: quote.srcAmount.currency,
+            payee: deliverTo,
+            referenceId: referencePrefix + intentId,
+        };
+        if (!quote.fees.isZero()) {
+            params.platformFee = majorAmount(quote.fees.minor(), quote.fees.exponent);
+        }
+        const order = await this.api.createOrder(params);
+        this.expected.set(intentId, {
+            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
     // the batch id.
     async disburse(intentId, quote, recipientRef) {
@@ -63,18 +95,23 @@ 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) {
             throw new Error(`paypal: no capture for intent ${intentId}`);
         }
-        const refund = await this.api.refundCapture({ captureId, reason });
+        // 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,
@@ -104,8 +141,20 @@ 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 want = this.expected.get(intentId);
+                if (!want) {
+                    throw new Error(`paypal: capture for unknown intent ${JSON.stringify(intentId)}`);
+                }
+                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":
@@ -163,7 +212,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",
@@ -184,21 +233,45 @@ 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`);
         }
         return { orderId: captured.id ?? "", captureId: capture.id ?? "", status: capture.status ?? "" };
     }
+    // createOrder creates an order the buyer approves and captures on their own
+    // device. It carries custom_id so the capture webhook ties back to the intent,
+    // and a platform fee via payment_instruction when one is set.
+    async createOrder(params) {
+        const unit = {
+            reference_id: params.referenceId,
+            custom_id: params.referenceId,
+            amount: { currency_code: params.currencyCode, value: params.value },
+        };
+        if (params.payee) {
+            unit.payee = { email_address: params.payee };
+        }
+        if (params.platformFee) {
+            unit.payment_instruction = {
+                platform_fees: [{ amount: { currency_code: params.currencyCode, value: params.platformFee } }],
+            };
+        }
+        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") {
+                approve = link.href ?? "";
+                break;
+            }
+        }
+        return { id: created.id ?? "", status: created.status ?? "", approveUrl: approve };
+    }
     async sendPayout(params) {
         const out = await this.postJSON("/v1/payments/payouts", {
             sender_batch_header: { sender_batch_id: params.referenceId },
@@ -218,7 +291,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
@@ -226,23 +303,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";
@@ -26,6 +27,7 @@ export interface CreateIntentParams {
     destination: string;
     applicationFee?: number;
     capture?: Capture;
+    methods?: string[];
     metadata: Record<string, string>;
 }
 export interface CreateRefundParams {
@@ -44,9 +46,10 @@ export interface StripeConfig {
     currencies: string[];
     api: StripeApi;
     webhookKey: string;
-    clock?: () => number;
+    clock: () => number;
     tolerance?: number;
     ids: () => string;
+    methods?: string[];
 }
 export declare class StripeLeg implements InteractivePayInLeg {
     readonly id: string;
@@ -56,11 +59,12 @@ export declare class StripeLeg implements InteractivePayInLeg {
     private readonly clock;
     private readonly tolerance;
     private readonly ids;
+    private readonly methods;
     constructor(cfg: StripeConfig);
     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
@@ -43,17 +43,24 @@ export class StripeLeg {
     clock;
     tolerance;
     ids;
+    methods;
     constructor(cfg) {
         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;
     }
     // payInCapabilities advertises the card rail and the wallets that fund through
     // it. The methods are informational; the corridor routes on the rail.
@@ -96,6 +103,7 @@ export class StripeLeg {
             destination: deliverTo,
             applicationFee: minorToInteger(quote.fees),
             capture: Capture.OnConfirmation,
+            ...(this.methods ? { methods: this.methods } : {}),
             metadata: { [metadataIntentKey]: intentId },
         }, idempotencyKey(intentId, "prepare"));
         return { providerRef: pi.id, clientSecret: pi.clientSecret, method: "card" };
@@ -103,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,
@@ -142,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.
@@ -277,7 +283,14 @@ class HttpStripeApi {
         if ((params.capture ?? Capture.Manual) === Capture.Manual) {
             form.set("capture_method", "manual");
         }
-        form.set("automatic_payment_methods[enabled]", "true");
+        // Pinning the method types offers exactly those and nothing else; without a
+        // pin, dynamic payment methods surface whatever the dashboard has enabled.
+        if (params.methods && params.methods.length > 0) {
+            params.methods.forEach((m, i) => form.set(`payment_method_types[${i}]`, m));
+        }
+        else {
+            form.set("automatic_payment_methods[enabled]", "true");
+        }
         if (params.destination) {
             form.set("transfer_data[destination]", params.destination);
         }
@@ -332,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;
@@ -75,6 +77,10 @@ export declare class Client {
     private holdAndDisburse;
     private settleBridged;
     private unwind;
+    refund(intentId: string, amount: Money, reason: string): Promise<{
+        settlement: Settlement;
+        state: State;
+    }>;
     private recordFailure;
     private finishAdvance;
     private finish;