feat: add environment param to support sdk url in sandbox (#485)

.changeset/good-falcons-turn.md

@@ -0,0 +1,5 @@
+---
+"@paypal/paypal-js": minor
+---
+
+Support env param in loadScript options object

.gitignore

@@ -6,3 +6,4 @@ node_modules
 /test-results/
 /playwright-report/
 /playwright/.cache/
+.idea

packages/paypal-js/src/load-script.test.ts

@@ -37,7 +37,38 @@ describe("loadScript()", () => {
         expect(window.paypal).toBe(undefined);
 
         const response = await loadScript({ clientId: "test" });
+        expect(mockedInsertScriptElement.mock.calls[0][0].url).toEqual(
+            "https://www.paypal.com/sdk/js?client-id=test"
+        );
+        expect(mockedInsertScriptElement).toHaveBeenCalledTimes(1);
+        expect(response).toEqual(window.paypal);
+    });
+
+    test("should insert <script> using environment option as sandbox", async () => {
+        expect(window.paypal).toBe(undefined);
+
+        const response = await loadScript({
+            clientId: "test",
+            environment: "sandbox",
+        });
         expect(mockedInsertScriptElement).toHaveBeenCalledTimes(1);
+        expect(mockedInsertScriptElement.mock.calls[0][0].url).toEqual(
+            "https://www.sandbox.paypal.com/sdk/js?client-id=test"
+        );
+        expect(response).toEqual(window.paypal);
+    });
+
+    test("should insert <script> using environment option as production", async () => {
+        expect(window.paypal).toBe(undefined);
+
+        const response = await loadScript({
+            clientId: "test",
+            environment: "production",
+        });
+        expect(mockedInsertScriptElement).toHaveBeenCalledTimes(1);
+        expect(mockedInsertScriptElement.mock.calls[0][0].url).toEqual(
+            "https://www.paypal.com/sdk/js?client-id=test"
+        );
         expect(response).toEqual(window.paypal);
     });
 
@@ -91,6 +122,19 @@ describe("loadScript()", () => {
         }
     });
 
+    test("should fail to insert <script> using invalid environment option", async () => {
+        expect(window.paypal).toBe(undefined);
+        expect(() =>
+            loadScript({
+                clientId: "test",
+                // @ts-expect-error intentionally sending invalid value
+                environment: "invalid",
+            })
+        ).toThrowError(
+            'The `environment` option must be either "production" or "sandbox"'
+        );
+    });
+
     test("should throw an error from invalid arguments", () => {
         // @ts-expect-error ignore invalid arguments error
         expect(() => loadScript()).toThrow("Expected an options object.");

packages/paypal-js/src/load-script.ts

@@ -104,6 +104,17 @@ function validateArguments(options: unknown, PromisePonyfill?: unknown) {
     if (typeof options !== "object" || options === null) {
         throw new Error("Expected an options object.");
     }
+    const { environment } = options as PayPalScriptOptions;
+
+    if (
+        environment &&
+        environment !== "production" &&
+        environment !== "sandbox"
+    ) {
+        throw new Error(
+            'The `environment` option must be either "production" or "sandbox".'
+        );
+    }
 
     if (
         typeof PromisePonyfill !== "undefined" &&

packages/paypal-js/src/utils.ts

@@ -66,7 +66,15 @@ export function processOptions(options: PayPalScriptOptions): {
     url: string;
     attributes: StringMap;
 } {
-    let sdkBaseUrl = "https://www.paypal.com/sdk/js";
+    const { environment } = options;
+    // Keeping production as default to maintain backward compatibility.
+    // In the future this logic needs to be changed to use sandbox domain as default instead of production.
+    let sdkBaseUrl =
+        environment === "sandbox"
+            ? "https://www.sandbox.paypal.com/sdk/js"
+            : "https://www.paypal.com/sdk/js";
+    // env is not an allowed key for sdk/js url.
+    delete options.environment;
 
     if (options.sdkBaseUrl) {
         sdkBaseUrl = options.sdkBaseUrl;

packages/paypal-js/types/components/card-fields.d.ts

@@ -114,7 +114,7 @@ export interface PayPalCardFieldsIndividualFieldOptions {
 }
 
 export interface PayPalCardFieldsIndividualField {
-    render: (container: string | HTMLElement) => Promise<void>;
+    render: (container: string | HTMLElement) => Promise<void>;
     addClass: (className: string) => Promise<void>;
     clear: () => void;
     focus: () => void;
@@ -124,7 +124,7 @@ export interface PayPalCardFieldsIndividualField {
     removeClass: (className: string) => Promise<void>;
     setAttribute: (name: string, value: string) => Promise<void>;
     setMessage: (message: string) => void;
-    close: ()=> Promise<void>;
+    close: () => Promise<void>;
 }
 
 export interface PayPalCardFieldsComponentOptions {

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

@@ -25,15 +25,15 @@ import type {
 
 export interface PayPalNamespace {
     Buttons?: (
-        options?: PayPalButtonsComponentOptions,
+        options?: PayPalButtonsComponentOptions
     ) => PayPalButtonsComponent;
     Marks?: (options?: PayPalMarksComponentOptions) => PayPalMarksComponent;
     Messages?: (
-        options?: PayPalMessagesComponentOptions,
+        options?: PayPalMessagesComponentOptions
     ) => PayPalMessagesComponent;
     HostedFields?: PayPalHostedFieldsComponent;
     CardFields?: (
-        options?: PayPalCardFieldsComponentOptions,
+        options?: PayPalCardFieldsComponentOptions
     ) => PayPalCardFieldsComponent;
     getFundingSources?: getFundingSources;
     isFundingEligible?: isFundingEligible;
@@ -44,7 +44,7 @@ export interface PayPalNamespace {
 
 export function loadScript(
     options: PayPalScriptOptions,
-    PromisePonyfill?: PromiseConstructor,
+    PromisePonyfill?: PromiseConstructor
 ): Promise<PayPalNamespace | null>;
 
 export function loadCustomScript(options: {
@@ -67,7 +67,7 @@ export * from "./components/funding-eligibility";
 export * from "./components/hosted-fields";
 export * from "./components/marks";
 export * from "./components/messages";
-export * from "./components/card-fields"
+export * from "./components/card-fields";
 
 // Export apis
 export * from "./apis/orders";

packages/paypal-js/types/script-options.d.ts

@@ -44,5 +44,6 @@ export interface PayPalScriptOptions
     extends PayPalScriptQueryParameters,
         PayPalScriptDataAttributes,
         ScriptAttributes {
+    environment?: "production" | "sandbox";
     sdkBaseUrl?: string;
 }