@myzonerocks/pact 0.1.0

package/src/adapters/paypal.ts

@@ -0,0 +1,409 @@
+// PayPal leg for the PACT protocol. It runs server-side: it holds the PayPal
+// client credentials and webhook id, creates and captures Orders on the pay-in
+// side, sends Payouts on the pay-out side, and verifies inbound webhooks through
+// PayPal's own verification call. The payer approves the order in the PayPal or
+// Venmo flow client-side; this package never sees card data. A captured payment
+// can be refunded in full, but a delivered payout cannot be pulled back.
+import { State } from "../state.js";
+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";
+
+// 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.
+const defaultBaseURL = "https://api-m.paypal.com";
+
+// The pact intent id travels on the order and payout reference so a webhook can
+// be tied back to the intent it settles.
+const referencePrefix = "pact:";
+
+// ErrSignatureMismatch reports a webhook PayPal could not authenticate.
+export const ErrSignatureMismatch = "paypal: webhook signature does not verify";
+
+// CreateOrderParams describes an order to create and capture. value is the
+// decimal-major amount PayPal expects, e.g. "15.00"; payee is the merchant the
+// captured funds settle to.
+export interface CreateOrderParams {
+  value: string;
+  currencyCode: string;
+  payee: string;
+  referenceId: string;
+}
+
+// Capture is the result of capturing an order: the capture id is the reference a
+// refund and a settlement receipt bind to.
+export interface Capture {
+  orderId: string;
+  captureId: string;
+  status: string;
+}
+
+// PayoutParams describes a single-item payout to a recipient.
+export interface PayoutParams {
+  value: string;
+  currencyCode: string;
+  receiver: string;
+  referenceId: string;
+}
+
+// Payout is the result of sending a payout: the batch id is its provider
+// reference.
+export interface Payout {
+  batchId: string;
+  status: string;
+}
+
+// RefundParams describes a refund against a capture.
+export interface RefundParams {
+  captureId: string;
+  reason: string;
+}
+
+// Refund is the result of refunding a capture.
+export interface Refund {
+  id: string;
+  status: string;
+}
+
+// PaypalApi is the surface of PayPal this leg depends on. Depending on an
+// interface keeps the leg unit-testable without a network and without
+// credentials. verifyWebhook authenticates an inbound webhook: the live client
+// forwards the signature headers and body to PayPal's verify-webhook-signature
+// endpoint, so the verification secret never lives in this package.
+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;
+}
+
+// PaypalLeg moves money over PayPal, serving both sides of a corridor.
+export class PaypalLeg implements PayInLeg, PayOutLeg {
+  readonly id: string;
+  private readonly currencies: string[];
+  private readonly api: PaypalApi;
+  private readonly ids: () => string;
+  private readonly captures = new Map<string, string>();
+
+  constructor(cfg: PaypalConfig) {
+    this.id = cfg.id ?? "paypal";
+    this.currencies = cfg.currencies;
+    this.api = cfg.api;
+    this.ids = cfg.ids;
+  }
+
+  payInCapabilities(): PayInCapabilities {
+    return {
+      rails: ["paypal"],
+      currencies: this.currencies,
+      methods: ["paypal", "venmo", "card"],
+      refunds: RefundKind.Full,
+    };
+  }
+
+  payOutCapabilities(): PayOutCapabilities {
+    return { rails: ["paypal"], currencies: this.currencies, reversible: false };
+  }
+
+  // collect creates and captures an order to deliverTo — the recipient's payee for
+  // a direct corridor, the escrow payee for a bridged one — and returns the
+  // capture id. received is the net a bridge would convert.
+  async collect(intentId: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<CollectResult> {
+    const capture = await this.api.createAndCaptureOrder({
+      value: majorAmount(quote.srcAmount.minor(), quote.srcAmount.exponent),
+      currencyCode: quote.srcAmount.currency,
+      payee: deliverTo,
+      referenceId: referencePrefix + intentId,
+    });
+    this.captures.set(intentId, capture.captureId);
+    return { providerRef: capture.captureId, received: quote.srcAmount.sub(quote.fees) };
+  }
+
+  // disburse sends a payout of the recipient's amount to recipientRef and returns
+  // the batch id.
+  async disburse(intentId: string, quote: Quote, recipientRef: string): Promise<DisburseResult> {
+    const payout = await this.api.sendPayout({
+      value: majorAmount(quote.dstAmount.minor(), quote.dstAmount.exponent),
+      currencyCode: quote.dstAmount.currency,
+      receiver: recipientRef,
+      referenceId: referencePrefix + intentId,
+    });
+    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: string, kind: RefundKind, reason: string): Promise<Settlement> {
+    if (kind !== RefundKind.Full) {
+      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 });
+    return {
+      intentId,
+      state: State.Refunded,
+      adapterId: this.id,
+      providerTxRef: refund.id,
+      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: string, _reason: string): Promise<Settlement> {
+    throw new Error("paypal: a delivered payout cannot be reversed");
+  }
+
+  // parseWebhook authenticates an inbound webhook through PayPal's own
+  // verification call, then maps the event onto the protocol. A payload that does
+  // not verify is rejected; an event the leg does not act on yields no protocol
+  // event.
+  async parseWebhook(raw: Uint8Array, headers: Record<string, string[]>): Promise<AdapterEvent[]> {
+    if (!(await this.api.verifyWebhook(headers, raw))) {
+      throw new Error(ErrSignatureMismatch);
+    }
+    const event = JSON.parse(new TextDecoder().decode(raw)) as PaypalWebhook;
+    const resource = event.resource ?? {};
+    const intentId = intentFromReference(resource.custom_id ?? "", resource.invoice_id ?? "");
+    const providerRef = resource.id ?? "";
+
+    switch (event.event_type) {
+      case "PAYMENT.CAPTURE.COMPLETED":
+        return [oneEvent(intentId, State.Settled, providerRef, "")];
+      case "PAYMENT.CAPTURE.DENIED":
+        return [oneEvent(intentId, State.Failed, providerRef, "capture denied")];
+      case "PAYMENT.CAPTURE.REFUNDED":
+        return [oneEvent(intentId, State.Refunded, providerRef, "refunded")];
+      default:
+        return [];
+    }
+  }
+}
+
+interface PaypalWebhook {
+  event_type?: string;
+  resource?: { id?: string; custom_id?: string; invoice_id?: string };
+}
+
+function oneEvent(intentId: string, state: State, providerRef: string, reason: string): AdapterEvent {
+  return { intentId, state, providerTxRef: providerRef, onchainTxHash: "", reason, settledAt: 0 };
+}
+
+// intentFromReference strips the reference prefix off whichever field carried it.
+function intentFromReference(...refs: string[]): string {
+  for (const ref of refs) {
+    if (ref.length > referencePrefix.length && ref.startsWith(referencePrefix)) {
+      return ref.slice(referencePrefix.length);
+    }
+  }
+  return "";
+}
+
+// majorAmount renders whole-and-fraction minor units as the decimal-major string
+// PayPal expects, e.g. 1500 minor at exponent 2 becomes "15.00".
+export function majorAmount(minor: string, exponent: number): string {
+  if (exponent === 0) {
+    return minor;
+  }
+  const neg = minor.startsWith("-");
+  let digits = neg ? minor.slice(1) : minor;
+  while (digits.length <= exponent) {
+    digits = "0" + digits;
+  }
+  const split = digits.length - exponent;
+  const value = digits.slice(0, split) + "." + digits.slice(split);
+  return neg ? "-" + value : value;
+}
+
+// Credentials are the PayPal secrets a host injects from its own store. This
+// package holds no defaults for any of them.
+export interface Credentials {
+  clientId: string;
+  clientSecret: string;
+  webhookId: string;
+  baseURL?: string; // optional, defaults to the public PayPal host
+}
+
+// httpPaypalApi is the live PayPal REST client. It fetches a client-credentials
+// access token, reuses it until it nears expiry, and presents it as a Bearer on
+// each call.
+class HttpPaypalApi implements PaypalApi {
+  private readonly creds: Credentials;
+  private readonly baseURL: string;
+  private readonly now: () => number;
+  private token = "";
+  private tokenExpiryMs = 0;
+
+  constructor(creds: Credentials, now: () => number) {
+    this.creds = creds;
+    this.baseURL = creds.baseURL || defaultBaseURL;
+    this.now = now;
+  }
+
+  // accessToken returns a cached client-credentials token, refreshing it when it
+  // is missing or within a minute of expiry.
+  private async accessToken(): Promise<string> {
+    if (this.token && this.now() < this.tokenExpiryMs - 60_000) {
+      return this.token;
+    }
+    const basic = Buffer.from(`${this.creds.clientId}:${this.creds.clientSecret}`).toString("base64");
+    const resp = await fetch(`${this.baseURL}/v1/oauth2/token`, {
+      method: "POST",
+      headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
+      body: "grant_type=client_credentials",
+    });
+    if (resp.status >= 300) {
+      throw new Error(`paypal: /v1/oauth2/token returned ${resp.status}`);
+    }
+    const out = (await resp.json()) as { access_token?: string; expires_in?: number };
+    this.token = out.access_token ?? "";
+    this.tokenExpiryMs = this.now() + (out.expires_in ?? 0) * 1000;
+    return this.token;
+  }
+
+  async createAndCaptureOrder(params: CreateOrderParams): Promise<Capture> {
+    const unit: Record<string, unknown> = {
+      reference_id: params.referenceId,
+      amount: { currency_code: params.currencyCode, value: params.value },
+    };
+    if (params.payee) {
+      unit.payee = { email_address: params.payee };
+    }
+    const created = await this.postJSON<PaypalOrder>("/v2/checkout/orders", {
+      intent: "CAPTURE",
+      purchase_units: [unit],
+    });
+    const existing = firstCapture(created);
+    if (existing) {
+      return { orderId: created.id ?? "", captureId: existing.id ?? "", status: existing.status ?? "" };
+    }
+    const captured = await this.postJSON<PaypalOrder>(
+      `/v2/checkout/orders/${encodeURIComponent(created.id ?? "")}/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 ?? "" };
+  }
+
+  async sendPayout(params: PayoutParams): Promise<Payout> {
+    const out = await this.postJSON<{ batch_header?: { payout_batch_id?: string; batch_status?: string } }>(
+      "/v1/payments/payouts",
+      {
+        sender_batch_header: { sender_batch_id: params.referenceId },
+        items: [
+          {
+            recipient_type: "EMAIL",
+            amount: { currency: params.currencyCode, value: params.value },
+            receiver: params.receiver,
+            sender_item_id: params.referenceId,
+          },
+        ],
+      },
+    );
+    return { batchId: out.batch_header?.payout_batch_id ?? "", status: out.batch_header?.batch_status ?? "" };
+  }
+
+  async refundCapture(params: RefundParams): Promise<Refund> {
+    const body: Record<string, unknown> = {};
+    if (params.reason) {
+      body.note_to_payer = params.reason;
+    }
+    const out = await this.postJSON<{ id?: string; status?: string }>(
+      `/v2/payments/captures/${encodeURIComponent(params.captureId)}/refund`,
+      body,
+    );
+    return { id: out.id ?? "", status: out.status ?? "" };
+  }
+
+  // verifyWebhook forwards the signature headers and the raw body to PayPal's
+  // verify-webhook-signature endpoint. The webhook id is the shared reference that
+  // binds a payload to this integration; PayPal reports whether the signature is
+  // authentic.
+  async verifyWebhook(headers: Record<string, string[]>, body: Uint8Array): Promise<boolean> {
+    const out = await this.postJSON<{ verification_status?: string }>("/v1/notifications/verify-webhook-signature", {
+      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)),
+    });
+    return out.verification_status === "SUCCESS";
+  }
+
+  private async postJSON<T>(path: string, body: unknown): Promise<T> {
+    const token = await this.accessToken();
+    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(`paypal: ${path} returned ${resp.status}`);
+    }
+    const text = await resp.text();
+    return (text ? JSON.parse(text) : {}) as T;
+  }
+}
+
+// paypalOrder is the subset of an Orders v2 response the leg reads.
+interface PaypalOrder {
+  id?: string;
+  status?: string;
+  purchase_units?: Array<{ payments?: { captures?: Array<{ id?: string; status?: string }> } }>;
+}
+
+function firstCapture(order: PaypalOrder): { id?: string; status?: string } | undefined {
+  for (const unit of order.purchase_units ?? []) {
+    const captures = unit.payments?.captures ?? [];
+    if (captures.length > 0) {
+      return captures[0];
+    }
+  }
+  return undefined;
+}
+
+// header reads a single request header case-insensitively.
+function header(headers: Record<string, string[]>, name: string): string {
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === name.toLowerCase()) {
+      const values = headers[key];
+      if (values && values.length > 0) {
+        return values[0]!;
+      }
+    }
+  }
+  return "";
+}
+
+// newHttpPaypalApi builds a live PayPal client. now is injectable so token expiry
+// is deterministic in tests.
+export function newHttpPaypalApi(creds: Credentials, now: () => number = () => Date.now()): PaypalApi {
+  return new HttpPaypalApi(creds, now);
+}