Feature/client token check provider (#781)

* checking clientToken

* checking clientToken to render Provider children

* Updating testcases

* Changeset added

* addressing PR comments

* Using deferLoading option

* Removing deferLoading prop and allowing clientToken to be a string or promise

* improving clientToken Promise error with descriptive message

---------

Co-authored-by: Nitya <nsattaru@paypal.com>

Author: nityasp

.changeset/mighty-towns-dream.md

@@ -0,0 +1,5 @@
+---
+"@paypal/react-paypal-js": patch
+---
+
+Checking clientToken to render the PayPalProvider children while rendering the provider

packages/react-paypal-js/src/v6/components/PayPalProvider.test.tsx

@@ -290,6 +290,148 @@ describe("PayPalProvider", () => {
         });
     });
 
+    describe("ClientToken Handling", () => {
+        test("should wait for clientToken and render children immediately", async () => {
+            const mockCreateInstance = jest
+                .fn()
+                .mockResolvedValue(createMockSdkInstance());
+
+            (loadCoreSdkScript as jest.Mock).mockResolvedValue({
+                createInstance: mockCreateInstance,
+            });
+
+            const childRenderSpy = jest.fn();
+            const TestChild = () => {
+                childRenderSpy();
+                return <div>Test Child Content</div>;
+            };
+
+            const { state, TestComponent } = setupTestComponent();
+            const { rerender, getByText } = render(
+                <PayPalProvider
+                    components={["paypal-payments"]}
+                    clientToken={undefined}
+                    environment="sandbox"
+                >
+                    <TestComponent>
+                        <TestChild />
+                    </TestComponent>
+                </PayPalProvider>,
+            );
+
+            expect(childRenderSpy).toHaveBeenCalled();
+            expect(getByText("Test Child Content")).toBeInTheDocument();
+            expect(loadCoreSdkScript).not.toHaveBeenCalled();
+            expect(state.loadingStatus).toBe(INSTANCE_LOADING_STATE.PENDING);
+            expect(state.sdkInstance).toBe(null);
+
+            rerender(
+                <PayPalProvider
+                    components={["paypal-payments"]}
+                    clientToken={TEST_CLIENT_TOKEN}
+                    environment="sandbox"
+                >
+                    <TestComponent>
+                        <TestChild />
+                    </TestComponent>
+                </PayPalProvider>,
+            );
+
+            await waitFor(() => expect(loadCoreSdkScript).toHaveBeenCalled());
+            await waitFor(() => expectResolvedState(state));
+            expect(mockCreateInstance).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    clientToken: TEST_CLIENT_TOKEN,
+                }),
+            );
+        });
+
+        test("should create instance immediately if clientToken is provided on mount", async () => {
+            const mockCreateInstance = jest
+                .fn()
+                .mockResolvedValue(createMockSdkInstance());
+
+            (loadCoreSdkScript as jest.Mock).mockResolvedValue({
+                createInstance: mockCreateInstance,
+            });
+
+            const { state } = renderProvider({
+                clientToken: TEST_CLIENT_TOKEN,
+            });
+
+            await waitFor(() => expectResolvedState(state));
+            expect(mockCreateInstance).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    clientToken: TEST_CLIENT_TOKEN,
+                }),
+            );
+        });
+
+        test("should handle Promise rejection for clientToken", async () => {
+            const tokenError = new Error("Token fetch failed");
+            const tokenPromise = Promise.reject(tokenError);
+
+            tokenPromise.catch(() => {});
+
+            const { state } = renderProvider({
+                clientToken: tokenPromise,
+            });
+
+            await waitFor(() => {
+                expect(state.loadingStatus).toBe(
+                    INSTANCE_LOADING_STATE.REJECTED,
+                );
+                expect(state.error?.message).toBe(
+                    "Failed to resolve clientToken. Expected a Promise that resolves to a string, but it was rejected with: Token fetch failed",
+                );
+            });
+            expect(loadCoreSdkScript).not.toHaveBeenCalled();
+        });
+
+        test("should resolve Promise and load SDK when clientToken is a Promise", async () => {
+            const mockCreateInstance = jest
+                .fn()
+                .mockResolvedValue(createMockSdkInstance());
+
+            (loadCoreSdkScript as jest.Mock).mockResolvedValue({
+                createInstance: mockCreateInstance,
+            });
+
+            const childRenderSpy = jest.fn();
+            const TestChild = () => {
+                childRenderSpy();
+                return <div>Test Child Content</div>;
+            };
+
+            let resolveToken: (value: string) => void;
+            const tokenPromise = new Promise<string>((resolve) => {
+                resolveToken = resolve;
+            });
+
+            const { state, TestComponent } = setupTestComponent();
+            const { getByText } = render(
+                <PayPalProvider
+                    components={["paypal-payments"]}
+                    clientToken={tokenPromise}
+                    environment="sandbox"
+                >
+                    <TestComponent>
+                        <TestChild />
+                    </TestComponent>
+                </PayPalProvider>,
+            );
+
+            expect(childRenderSpy).toHaveBeenCalled();
+            expect(getByText("Test Child Content")).toBeInTheDocument();
+            expect(loadCoreSdkScript).not.toHaveBeenCalled();
+
+            resolveToken!(TEST_CLIENT_TOKEN);
+
+            await waitFor(() => expect(loadCoreSdkScript).toHaveBeenCalled());
+            await waitFor(() => expectResolvedState(state));
+        });
+    });
+
     describe("Eligibility Loading", () => {
         test("should load eligible payment methods", async () => {
             const { state } = renderProvider();

packages/react-paypal-js/src/v6/components/PayPalProvider.tsx

@@ -29,26 +29,57 @@ import type { usePayPal } from "../hooks/usePayPal";
 
 type PayPalProviderProps = Omit<
     CreateInstanceOptions<readonly [Components, ...Components[]]>,
-    "components"
+    "components" | "clientToken"
 > &
     LoadCoreSdkScriptOptions & {
         components?: Components[];
         eligibleMethodsResponse?: FindEligiblePaymentMethodsResponse;
         eligibleMethodsPayload?: FindEligiblePaymentMethodsRequestPayload;
         children: React.ReactNode;
+        clientToken?: string | Promise<string>;
     };
 
 /**
  * {@link PayPalProvider} creates the SDK script, component scripts, runs eligibility, then
  * provides these in context to child components via the {@link usePayPal} hook.
  *
+ * SDK loading is automatically deferred until clientToken is available.
+ * clientToken can be a string, Promise, or undefined.
+ *
  * @example
+ * // With string token
  * <PayPalProvider
- *   clientToken={clientToken}
+ *   clientToken={token}
  *   components={["paypal-payments", "venmo-payments"]}
  *   pageType="checkout"
- *  >
- *      // payment buttons
+ * >
+ *   <PayPalButton />
+ * </PayPalProvider>
+ *
+ * @example
+ * // With Promise token (memoize to prevent re-fetching)
+ * const tokenPromise = useMemo(() => fetchClientToken(), []);
+ *
+ * <PayPalProvider
+ *   clientToken={tokenPromise}
+ *   pageType="checkout"
+ * >
+ *   <PayPalButton />
+ * </PayPalProvider>
+ *
+ * @example
+ * // With deferred loading
+ * const [clientToken, setClientToken] = useState<string>();
+ *
+ * useEffect(() => {
+ *   fetchClientToken().then(setClientToken);
+ * }, []);
+ *
+ * <PayPalProvider
+ *   clientToken={clientToken}
+ *   pageType="checkout"
+ * >
+ *   <PayPalButton />
  * </PayPalProvider>
  */
 export const PayPalProvider: React.FC<PayPalProviderProps> = ({
@@ -70,6 +101,9 @@ export const PayPalProvider: React.FC<PayPalProviderProps> = ({
     const [paypalNamespace, setPaypalNamespace] =
         useState<PayPalV6Namespace | null>(null);
     const [state, dispatch] = useReducer(instanceReducer, initialState);
+    const [clientTokenValue, setClientTokenValue] = useState<
+        string | undefined
+    >(undefined);
     // Ref to hold script options to avoid re-running effect
     const loadCoreScriptOptions = useRef(scriptOptions);
     // Using the error hook here so it can participate in side-effects provided by the hook. The actual error
@@ -78,7 +112,7 @@ export const PayPalProvider: React.FC<PayPalProviderProps> = ({
 
     const { eligibleMethods, isLoading } = useEligibleMethods({
         eligibleMethodsResponse,
-        clientToken,
+        clientToken: clientTokenValue,
         payload: eligibleMethodsPayload,
         environment: loadCoreScriptOptions.current.environment,
     });
@@ -92,33 +126,58 @@ export const PayPalProvider: React.FC<PayPalProviderProps> = ({
         }
     }, [isLoading, eligibleMethods]);
 
-    // Load Core SDK Script
+    // Load Core SDK script
     useEffect(() => {
         let isSubscribed = true;
 
         const loadSdk = async () => {
+            let token: string | undefined;
+
+            if (!clientToken) {
+                setClientTokenValue(undefined);
+                return;
+            }
+
+            if (typeof clientToken === "string") {
+                token = clientToken;
+                setClientTokenValue(token);
+            } else {
+                try {
+                    token = await clientToken;
+                    setClientTokenValue(token);
+                } catch (error) {
+                    const clientTokenError = new Error(
+                        `Failed to resolve clientToken. Expected a Promise that resolves to a string, but it was rejected with: ${toError(error).message}`,
+                    );
+                    setError(clientTokenError);
+                    dispatch({
+                        type: INSTANCE_DISPATCH_ACTION.SET_ERROR,
+                        value: clientTokenError,
+                    });
+                    return;
+                }
+            }
+
+            if (!isSubscribed || !token) {
+                return;
+            }
+
             try {
                 const paypal = await loadCoreSdkScript({
                     environment: loadCoreScriptOptions.current.environment,
                     debug: loadCoreScriptOptions.current.debug,
                     dataNamespace: loadCoreScriptOptions.current.dataNamespace,
                 });
 
-                if (!isSubscribed) {
-                    return;
-                }
-
                 if (paypal) {
                     setPaypalNamespace(paypal);
                 }
             } catch (error) {
-                if (isSubscribed) {
-                    setError(error);
-                    dispatch({
-                        type: INSTANCE_DISPATCH_ACTION.SET_ERROR,
-                        value: toError(error),
-                    });
-                }
+                setError(error);
+                dispatch({
+                    type: INSTANCE_DISPATCH_ACTION.SET_ERROR,
+                    value: toError(error),
+                });
             }
         };
 
@@ -127,14 +186,18 @@ export const PayPalProvider: React.FC<PayPalProviderProps> = ({
         return () => {
             isSubscribed = false;
         };
-    }, [setError]);
+    }, [clientToken, setError]);
 
     // Create SDK Instance
     useEffect(() => {
         if (!paypalNamespace) {
             return;
         }
 
+        if (!clientTokenValue) {
+            return;
+        }
+
         // This dispatch is for instance creations after initial mount
         dispatch({
             type: INSTANCE_DISPATCH_ACTION.SET_LOADING_STATUS,
@@ -148,7 +211,7 @@ export const PayPalProvider: React.FC<PayPalProviderProps> = ({
                 // Create SDK instance
                 const instance = await paypalNamespace.createInstance({
                     clientMetadataId,
-                    clientToken,
+                    clientToken: clientTokenValue,
                     components: memoizedComponents,
                     locale,
                     pageType,
@@ -183,7 +246,7 @@ export const PayPalProvider: React.FC<PayPalProviderProps> = ({
         };
     }, [
         clientMetadataId,
-        clientToken,
+        clientTokenValue,
         locale,
         memoizedComponents,
         pageType,