@myzonerocks/pact 0.1.1 → 0.1.3

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

@@ -1,12 +1,18 @@
 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";
+import type { PayOutLeg, InteractivePayInLeg, PayInCapabilities, PayOutCapabilities, CollectResult, DisburseResult, PayInPreparation } from "../leg.js";
 export declare const ErrSignatureMismatch = "paypal: webhook signature does not verify";
 export interface CreateOrderParams {
     value: string;
     currencyCode: string;
     payee: string;
     referenceId: string;
+    platformFee?: string;
+}
+export interface Order {
+    id: string;
+    status: string;
+    approveUrl: string;
 }
 export interface Capture {
     orderId: string;
@@ -33,6 +39,7 @@ export interface Refund {
 }
 export interface PaypalApi {
     createAndCaptureOrder(params: CreateOrderParams): Promise<Capture>;
+    createOrder(params: CreateOrderParams): Promise<Order>;
     sendPayout(params: PayoutParams): Promise<Payout>;
     refundCapture(params: RefundParams): Promise<Refund>;
     verifyWebhook(headers: Record<string, string[]>, body: Uint8Array): Promise<boolean>;
@@ -43,7 +50,7 @@ export interface PaypalConfig {
     api: PaypalApi;
     ids: () => string;
 }
-export declare class PaypalLeg implements PayInLeg, PayOutLeg {
+export declare class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
     readonly id: string;
     private readonly currencies;
     private readonly api;
@@ -53,6 +60,7 @@ export declare class PaypalLeg implements PayInLeg, PayOutLeg {
     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>;
     reverseOut(_intentId: string, _reason: string): Promise<Settlement>;

package/dist/src/adapters/paypal.js

@@ -52,6 +52,25 @@ export class PaypalLeg {
         this.captures.set(intentId, capture.captureId);
         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);
+        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) {
@@ -199,6 +218,36 @@ class HttpPaypalApi {
         }
         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],
+        });
+        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 },

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

@@ -26,6 +26,7 @@ export interface CreateIntentParams {
     destination: string;
     applicationFee?: number;
     capture?: Capture;
+    methods?: string[];
     metadata: Record<string, string>;
 }
 export interface CreateRefundParams {
@@ -47,6 +48,7 @@ export interface StripeConfig {
     clock?: () => number;
     tolerance?: number;
     ids: () => string;
+    methods?: string[];
 }
 export declare class StripeLeg implements InteractivePayInLeg {
     readonly id: string;
@@ -56,6 +58,7 @@ 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>;

package/dist/src/adapters/stripe.js

@@ -43,6 +43,7 @@ export class StripeLeg {
     clock;
     tolerance;
     ids;
+    methods;
     constructor(cfg) {
         if (!cfg.webhookKey) {
             throw new Error("stripe: config requires a webhook signing key");
@@ -54,6 +55,7 @@ export class StripeLeg {
         this.clock = cfg.clock ?? (() => 0);
         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 +98,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" };
@@ -277,7 +280,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);
         }

package/dist/test/paypal.test.js

@@ -33,6 +33,10 @@ class FakePaypal {
         const id = this.ids();
         return { orderId: `order_${id}`, captureId: `capture_${id}`, status: "COMPLETED" };
     }
+    async createOrder(params) {
+        this.lastOrder = params;
+        return { id: `order_${this.ids()}`, status: "CREATED", approveUrl: "https://paypal.test/approve" };
+    }
     async sendPayout(params) {
         this.lastPayout = params;
         return { batchId: `batch_${this.ids()}`, status: "PENDING" };
@@ -127,6 +131,23 @@ describe("paypal direct corridor", () => {
         await expect(leg.refundIn(intent.id, RefundKind.Partial, "half")).rejects.toThrow();
     });
 });
+describe("paypal interactive pay-in", () => {
+    it("prepares an order to the recipient payee with our cut as a platform fee", async () => {
+        const api = new FakePaypal(counter("tx"));
+        const leg = buildLeg(api);
+        const prep = await leg.prepare("intent-1", quote({ srcAmount: Money.parse("USD", 2, "1500"), fees: Money.parse("USD", 2, "45") }), { intentId: "intent-1", quoteId: "q", signerIdentity: "alice", signature: new Uint8Array(0), signedAt: 0 }, "merchant@example.com");
+        expect(prep.providerRef).not.toBe("");
+        expect(prep.clientSecret).toBe(prep.providerRef);
+        expect(prep.method).toBe("paypal");
+        expect(api.lastOrder.payee).toBe("merchant@example.com");
+        expect(api.lastOrder.value).toBe("15.00");
+        expect(api.lastOrder.platformFee).toBe("0.45");
+        expect(api.lastOrder.referenceId).toBe("pact:intent-1");
+        // A zero fee omits the platform fee rather than sending "0.00".
+        await leg.prepare("intent-2", quote({ srcAmount: Money.parse("USD", 2, "1500"), fees: Money.parse("USD", 2, "0") }), { intentId: "intent-2", quoteId: "q", signerIdentity: "alice", signature: new Uint8Array(0), signedAt: 0 }, "merchant@example.com");
+        expect(api.lastOrder.platformFee).toBeUndefined();
+    });
+});
 describe("paypal pay-out", () => {
     it("sends the recipient's amount and refuses a reversal", async () => {
         const api = new FakePaypal(counter("tx"));

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@myzonerocks/pact",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "TypeScript SDK for the PACT payment abstraction protocol",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/myzonerocks/pact.git", "directory": "sdk/ts" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/myzonerocks/pact.git",
+    "directory": "sdk/ts"
+  },
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
@@ -33,7 +37,10 @@
       "import": "./dist/src/policy.js"
     }
   },
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",

package/src/adapters/paypal.ts

@@ -8,12 +8,13 @@ import { State } from "../state.js";
 import type { Quote, Authorization, Settlement } from "../message.js";
 import { RefundKind, type AdapterEvent } from "../adapter.js";
 import type {
-  PayInLeg,
   PayOutLeg,
+  InteractivePayInLeg,
   PayInCapabilities,
   PayOutCapabilities,
   CollectResult,
   DisburseResult,
+  PayInPreparation,
 } from "../leg.js";
 
 // The public base of the PayPal REST API. It is the same for every live
@@ -36,6 +37,18 @@ export interface CreateOrderParams {
   currencyCode: string;
   payee: string;
   referenceId: string;
+  // platformFee, when set, is the decimal-major cut the platform takes from the
+  // payee's proceeds.
+  platformFee?: string;
+}
+
+// Order is a created-but-not-yet-captured order: the buyer approves it on their own
+// device, then it is captured. approveUrl is PayPal's hosted approval link, offered
+// for hosts that redirect rather than drive the JS SDK.
+export interface Order {
+  id: string;
+  status: string;
+  approveUrl: string;
 }
 
 // Capture is the result of capturing an order: the capture id is the reference a
@@ -80,6 +93,9 @@ export interface Refund {
 // endpoint, so the verification secret never lives in this package.
 export interface PaypalApi {
   createAndCaptureOrder(params: CreateOrderParams): Promise<Capture>;
+  // createOrder creates an order the buyer approves and captures on their own
+  // device — the interactive pay-in path — rather than capturing it server-side.
+  createOrder(params: CreateOrderParams): Promise<Order>;
   sendPayout(params: PayoutParams): Promise<Payout>;
   refundCapture(params: RefundParams): Promise<Refund>;
   verifyWebhook(headers: Record<string, string[]>, body: Uint8Array): Promise<boolean>;
@@ -93,7 +109,7 @@ export interface PaypalConfig {
 }
 
 // PaypalLeg moves money over PayPal, serving both sides of a corridor.
-export class PaypalLeg implements PayInLeg, PayOutLeg {
+export class PaypalLeg implements InteractivePayInLeg, PayOutLeg {
   readonly id: string;
   private readonly currencies: string[];
   private readonly api: PaypalApi;
@@ -134,6 +150,26 @@ export class PaypalLeg implements PayInLeg, PayOutLeg {
     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: string, quote: Quote, _auth: Authorization, deliverTo: string): Promise<PayInPreparation> {
+    const params: CreateOrderParams = {
+      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);
+    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: string, quote: Quote, recipientRef: string): Promise<DisburseResult> {
@@ -310,6 +346,37 @@ class HttpPaypalApi implements PaypalApi {
     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: CreateOrderParams): Promise<Order> {
+    const unit: Record<string, unknown> = {
+      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<PaypalOrder>("/v2/checkout/orders", {
+      intent: "CAPTURE",
+      purchase_units: [unit],
+    });
+    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: PayoutParams): Promise<Payout> {
     const out = await this.postJSON<{ batch_header?: { payout_batch_id?: string; batch_status?: string } }>(
       "/v1/payments/payouts",
@@ -377,6 +444,7 @@ interface PaypalOrder {
   id?: string;
   status?: string;
   purchase_units?: Array<{ payments?: { captures?: Array<{ id?: string; status?: string }> } }>;
+  links?: Array<{ href?: string; rel?: string }>;
 }
 
 function firstCapture(order: PaypalOrder): { id?: string; status?: string } | undefined {

package/src/adapters/stripe.ts

@@ -75,6 +75,10 @@ export interface CreateIntentParams {
   destination: string;
   applicationFee?: number;
   capture?: Capture;
+  // methods pins the exact payment method types offered (e.g. card, cashapp, link);
+  // wallets like Apple Pay and Google Pay ride on "card". Empty falls back to the
+  // account's dynamic payment methods.
+  methods?: string[];
   metadata: Record<string, string>;
 }
 
@@ -110,6 +114,9 @@ export interface StripeConfig {
   // tolerance is the webhook timestamp tolerance in seconds; defaults to 300.
   tolerance?: number;
   ids: () => string;
+  // methods pins the payment method types offered on the card rail (e.g. card,
+  // cashapp, link). Empty offers the account's dynamic payment methods.
+  methods?: string[];
 }
 
 // StripeLeg collects card payments through Stripe. It exposes the wallets that
@@ -123,6 +130,7 @@ export class StripeLeg implements InteractivePayInLeg {
   private readonly clock: () => number;
   private readonly tolerance: number;
   private readonly ids: () => string;
+  private readonly methods: string[] | undefined;
 
   constructor(cfg: StripeConfig) {
     if (!cfg.webhookKey) {
@@ -135,6 +143,7 @@ export class StripeLeg implements InteractivePayInLeg {
     this.clock = cfg.clock ?? (() => 0);
     this.tolerance = cfg.tolerance ?? defaultToleranceSeconds;
     this.ids = cfg.ids;
+    this.methods = cfg.methods;
   }
 
   // payInCapabilities advertises the card rail and the wallets that fund through
@@ -184,6 +193,7 @@ export class StripeLeg implements InteractivePayInLeg {
         destination: deliverTo,
         applicationFee: minorToInteger(quote.fees),
         capture: Capture.OnConfirmation,
+        ...(this.methods ? { methods: this.methods } : {}),
         metadata: { [metadataIntentKey]: intentId },
       },
       idempotencyKey(intentId, "prepare"),
@@ -403,7 +413,13 @@ class HttpStripeApi implements StripeApi {
     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);
     }