feat(types): add v6 types for paypal-guest-payments (#727)

* switch to interfaces for errors/warnings

Author: gregjopa

.changeset/breezy-fishes-act.md

@@ -0,0 +1,5 @@
+---
+"@paypal/paypal-js": minor
+---
+
+Add new types for paypal-guest-payments component

packages/paypal-js/types/v6/components/base-component.d.ts

@@ -15,7 +15,19 @@ export type OnCompleteData = {
     paymentSessionState: "approved" | "canceled" | "error";
 };
 
-export type OnErrorData = Error;
+export interface PayPalError extends Error {
+    code: string;
+    name: string;
+    isRecoverable: boolean;
+}
+
+export interface PayPalWarning {
+    code: string;
+    message: string;
+    name: string;
+}
+
+export type OnErrorData = PayPalError;
 
 /**
  * use Omit\<BasePaymentSessionOptions, "onApprove"\> to change the arguments for onApprove()

packages/paypal-js/types/v6/components/find-eligible-methods.d.ts

@@ -8,13 +8,14 @@ export type EligiblePaymentMethods =
     | "paypal_pay_later"
     | "paypal_credit"
     | "paypal"
-    | "venmo";
+    | "venmo"
+    | "basic_cards";
 
 export type FindEligibleMethodsOptions = {
     currencyCode?: string;
 };
 
-export type FundingSource = "credit" | "paylater" | "paypal" | "venmo";
+export type FundingSource = "credit" | "paylater" | "paypal" | "venmo" | "card";
 
 type BaseEligiblePaymentMethodDetails = {
     canBeVaulted: boolean;

packages/paypal-js/types/v6/components/paypal-guest-payments.d.ts

@@ -0,0 +1,49 @@
+import {
+    BasePaymentSessionOptions,
+    BasePaymentSession,
+    OnApproveDataOneTimePayments,
+    PayPalWarning,
+    PresentationModeOptionsForAuto,
+} from "./base-component";
+
+export type PayPalGuestOneTimePaymentSessionOptions =
+    BasePaymentSessionOptions & {
+        orderId?: string;
+        onApprove: (data: OnApproveDataOneTimePayments) => Promise<void>;
+        onWarn?: (data: PayPalWarning) => void;
+    };
+
+export type PayPalGuestPresentationModeOptions =
+    PresentationModeOptionsForAuto & {
+        targetElement?: string | EventTarget;
+    };
+
+export type PayPalGuestOneTimePaymentSessionPromise = Promise<{
+    orderId: string;
+}>;
+
+export type PayPalGuestOneTimePaymentSession = Omit<
+    BasePaymentSession,
+    "start"
+> & {
+    start: (
+        presentationModeOptions: PayPalGuestPresentationModeOptions,
+        paymentSessionPromise?: PayPalGuestOneTimePaymentSessionPromise,
+    ) => Promise<void>;
+};
+
+/**
+ * Interface for managing PayPal guest payment operations within the PayPal SDK.
+ *
+ * @remarks
+ * This interface provides methods for creating and managing PayPal guest payment sessions,
+ * allowing merchants to integrate the basic credit or debit button as a payment method in their applications.
+ *
+ * The {@link PayPalGuestPaymentsInstance} enables seamless integration with PayPal's guest payment flow,
+ * providing a secure and user-friendly way to process payments through the PayPal platform.
+ */
+export interface PayPalGuestPaymentsInstance {
+    createPayPalGuestOneTimePaymentSession: (
+        paymentSessionOptions: PayPalGuestOneTimePaymentSessionOptions,
+    ) => PayPalGuestOneTimePaymentSession;
+}

packages/paypal-js/types/v6/index.d.ts

@@ -1,4 +1,5 @@
 import { PayPalPaymentsInstance } from "./components/paypal-payments";
+import { PayPalGuestPaymentsInstance } from "./components/paypal-guest-payments";
 import { PayPalLegacyBillingInstance } from "./components/paypal-legacy-billing-agreements";
 import { VenmoPaymentsInstance } from "./components/venmo-payments";
 import {
@@ -35,6 +36,7 @@ export interface PayPalV6Namespace {
 
 export type Components =
     | "paypal-payments"
+    | "paypal-guest-payments"
     | "venmo-payments"
     | "paypal-legacy-billing-agreements";
 
@@ -122,6 +124,9 @@ export type SdkInstance<T extends readonly [Components, ...Components[]]> =
         ("paypal-payments" extends T[number]
             ? PayPalPaymentsInstance
             : unknown) &
+        ("paypal-guest-payments" extends T[number]
+            ? PayPalGuestPaymentsInstance
+            : unknown) &
         ("venmo-payments" extends T[number] ? VenmoPaymentsInstance : unknown) &
         ("paypal-legacy-billing-agreements" extends T[number]
             ? PayPalLegacyBillingInstance
@@ -187,6 +192,7 @@ export function loadCoreSdkScript(
 
 // Components
 export * from "./components/paypal-payments";
+export * from "./components/paypal-guest-payments";
 export * from "./components/paypal-legacy-billing-agreements";
 export * from "./components/venmo-payments";
 export * from "./components/find-eligible-methods";

packages/paypal-js/types/v6/tests/paypal-guest-payments.test.ts

@@ -0,0 +1,70 @@
+import { loadCoreSdkScript } from "../../../src/v6";
+import type { OnApproveDataOneTimePayments, PayPalV6Namespace } from "../index";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+async function main() {
+    let paypal: PayPalV6Namespace | null;
+
+    try {
+        paypal = await loadCoreSdkScript({
+            environment: "sandbox",
+            debug: true,
+        });
+    } catch (err) {
+        throw new Error(`Failed to load the paypal sdk script: ${err}`);
+    }
+
+    if (!paypal?.createInstance) {
+        throw new Error("Invalid paypal object for v6");
+    }
+
+    if (!paypal?.version) {
+        throw new Error("PayPal v6 namespace missing version property");
+    }
+
+    const sdkInstance = await paypal.createInstance({
+        clientToken: "fakeValue",
+        components: ["paypal-guest-payments"],
+    });
+
+    const paymentMethods = await sdkInstance.findEligibleMethods({
+        currencyCode: "USD",
+    });
+
+    if (!paymentMethods.isEligible("card")) {
+        return;
+    }
+
+    function onApproveCallback({
+        orderId,
+        payerId,
+    }: OnApproveDataOneTimePayments) {
+        console.log({
+            orderId,
+            payerId,
+        });
+        return Promise.resolve();
+    }
+
+    const paypalGuestPaymentSession =
+        sdkInstance.createPayPalGuestOneTimePaymentSession({
+            onApprove: onApproveCallback,
+        });
+
+    const createOrder = () => Promise.resolve({ orderId: "ABC123" });
+
+    const paypalBasicCardButton = document.querySelector(
+        "paypal-basic-card-button",
+    );
+
+    paypalBasicCardButton?.addEventListener("click", async () => {
+        try {
+            await paypalGuestPaymentSession.start(
+                { presentationMode: "auto" },
+                createOrder(),
+            );
+        } catch (error) {
+            console.error(error);
+        }
+    });
+}