Skip to content

Commit 38f520d

Browse files
HackTheW2dclaudeEvanReinstein
authored
Feature/comments update (#836)
* update hooks document * fix document for components * chore: add changeset for doc comment audit Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * pr feedback: remove unneccessary comments * update example function name to be more accurate Co-authored-by: Evan Reinstein <42251756+EvanReinstein@users.noreply.github.com> * update example function name to be more accurate Co-authored-by: Evan Reinstein <42251756+EvanReinstein@users.noreply.github.com> * update example function name to be more accurate Co-authored-by: Evan Reinstein <42251756+EvanReinstein@users.noreply.github.com> * update example function name to be more accurate Co-authored-by: Evan Reinstein <42251756+EvanReinstein@users.noreply.github.com> * update example function name to be more accurate Co-authored-by: Evan Reinstein <42251756+EvanReinstein@users.noreply.github.com> * update example function name to be more accurate Co-authored-by: Evan Reinstein <42251756+EvanReinstein@users.noreply.github.com> * update example function name to be more accurate Co-authored-by: Evan Reinstein <42251756+EvanReinstein@users.noreply.github.com> * pr feedback: paypal messages example modification --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Evan Reinstein <42251756+EvanReinstein@users.noreply.github.com>
1 parent ac3bb9e commit 38f520d

16 files changed

+245
-89
lines changed

‎.changeset/quiet-birds-teach.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@paypal/react-paypal-js": patch
3+
---
4+
5+
Audit and update JSDoc comments for V6 hooks and components. Add missing doc comments for usePayLaterOneTimePaymentSession and useVenmoOneTimePaymentSession, fix inaccurate documentation in useFetchEligibleMethods and usePayPal, and normalize doc style across all payment session hooks and button components.

‎packages/react-paypal-js/src/v6/components/PayLaterOneTimePaymentButton.tsx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ export type PayLaterOneTimePaymentButtonProps =
1414
/**
1515
* `PayLaterOneTimePaymentButton` is a button that provides a PayLater payment flow.
1616
*
17+
* `PayLaterOneTimePaymentButtonProps` combines the arguments for {@link UsePayLaterOneTimePaymentSessionProps}
18+
* with a `disabled` prop.
19+
*
1720
* The `countryCode` and `productCode` are automatically populated from the eligibility API response
1821
* (available via `usePayPal().eligiblePaymentMethods`). The button requires eligibility to be configured
1922
* in the parent `PayPalProvider`.

‎packages/react-paypal-js/src/v6/components/PayPalGuestPaymentButton.tsx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,12 @@ type PayPalGuestPaymentButtonProps = UsePayPalGuestPaymentSessionProps & {
1212
/**
1313
* `PayPalGuestPaymentButton` is a button that provides a guest checkout (BCDC) payment flow.
1414
*
15+
* `PayPalGuestPaymentButtonProps` combines the arguments for {@link UsePayPalGuestPaymentSessionProps}
16+
* with a `disabled` prop.
17+
*
1518
* This component automatically wraps the button with `<paypal-basic-card-container>` which is
1619
* required for the guest checkout form to display properly.
1720
*
18-
* `PayPalGuestPaymentButtonProps` combines the arguments for {@link UsePayPalGuestPaymentSessionProps}.
19-
*
2021
* @example
2122
* <PayPalGuestPaymentButton
2223
* createOrder={createOrder}

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ type PayPalProviderProps =
6363
* components={["paypal-payments", "venmo-payments"]}
6464
* pageType="checkout"
6565
* >
66-
* <PayPalButton />
66+
* <PayPalOneTimePaymentButton />
6767
* </PayPalProvider>
6868
*
6969
* @example
@@ -73,7 +73,7 @@ type PayPalProviderProps =
7373
* components={["paypal-payments"]}
7474
* pageType="checkout"
7575
* >
76-
* <PayPalButton />
76+
* <PayPalOneTimePaymentButton />
7777
* </PayPalProvider>
7878
*
7979
* @example
@@ -84,7 +84,7 @@ type PayPalProviderProps =
8484
* clientToken={tokenPromise}
8585
* pageType="checkout"
8686
* >
87-
* <PayPalButton />
87+
* <PayPalOneTimePaymentButton />
8888
* </PayPalProvider>
8989
*
9090
* @example
@@ -95,7 +95,7 @@ type PayPalProviderProps =
9595
* clientId={clientIdPromise}
9696
* pageType="checkout"
9797
* >
98-
* <PayPalButton />
98+
* <PayPalOneTimePaymentButton />
9999
* </PayPalProvider>
100100
*
101101
* @example
@@ -110,7 +110,7 @@ type PayPalProviderProps =
110110
* clientToken={clientToken}
111111
* pageType="checkout"
112112
* >
113-
* <PayPalButton />
113+
* <PayPalOneTimePaymentButton />
114114
* </PayPalProvider>
115115
*
116116
* @example
@@ -125,7 +125,7 @@ type PayPalProviderProps =
125125
* clientId={clientId}
126126
* pageType="checkout"
127127
* >
128-
* <PayPalButton />
128+
* <PayPalOneTimePaymentButton />
129129
* </PayPalProvider>
130130
*
131131
* @example
@@ -138,7 +138,7 @@ type PayPalProviderProps =
138138
* return <div>Loading PayPal SDK...</div>;
139139
* }
140140
*
141-
* return <PayPalButton orderId="ORDER-123" />;
141+
* return <PayPalOneTimePaymentButton orderId="ORDER-123" />;
142142
* }
143143
*
144144
* <PayPalProvider clientToken={token} pageType="checkout">

‎packages/react-paypal-js/src/v6/hooks/useEligibleMethods.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ export interface UseFetchEligibleMethodsResult {
5050
* if (error) return <Error message={error.message} />;
5151
* return (
5252
* <paypal-pay-later-button
53-
* handleClick={handleClick}
53+
* onClick={handleClick}
5454
* countryCode={countryCode}
5555
* productCode={productCode}
5656
* />

‎packages/react-paypal-js/src/v6/hooks/useFetchEligibleMethods.ts‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -72,18 +72,21 @@ export type FindEligiblePaymentMethodsRequestPayload = {
7272
* to the `PayPalProvider` via the `eligibleMethodsResponse` prop.
7373
*
7474
* @param options - Configuration for the eligibility request
75-
* @param options.clientToken - Bearer token for API authentication
75+
* @param options.headers - HTTP headers for the request, including the `Authorization` bearer token
7676
* @param options.environment - Target environment ("sandbox" or "production")
7777
* @param options.payload - Optional request payload with customer/purchase details
7878
* @param options.signal - Optional AbortSignal for request cancellation
7979
* @returns Promise resolving to the eligibility API response
8080
*
8181
* @example
8282
* // Next.js server component
83-
* const response = await fetchEligibleMethods({
84-
* clientToken: token,
83+
* const response = await useFetchEligibleMethods({
84+
* headers: {
85+
* "Content-Type": "application/json",
86+
* Authorization: `Bearer ${clientToken}`,
87+
* },
8588
* environment: "sandbox",
86-
* payload: { purchase_units: [{ amount: { currency_code: "USD" } }] }
89+
* payload: { purchase_units: [{ amount: { currency_code: "USD" } }] },
8790
* });
8891
*
8992
* <PayPalProvider eligibleMethodsResponse={response} ... />

‎packages/react-paypal-js/src/v6/hooks/usePayLaterOneTimePaymentSession.ts‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,39 @@ export type UsePayLaterOneTimePaymentSessionProps = (
2626
) &
2727
PayPalPresentationModeOptions;
2828

29+
/**
30+
* Hook for managing Pay Later one-time payment sessions.
31+
*
32+
* This hook creates and manages a Pay Later payment session. It handles session lifecycle, resume flows
33+
* for redirect-based presentation modes (`"redirect"` and `"direct-app-switch"`), and provides methods
34+
* to start, cancel, and destroy the session.
35+
*
36+
* @returns Object with: `error` (any session error), `isPending` (SDK loading), `handleClick` (starts session), `handleCancel` (cancels session), `handleDestroy` (cleanup)
37+
*
38+
* @example
39+
* function PayLaterCheckoutButton() {
40+
* const { error, isPending, handleClick, handleCancel } = usePayLaterOneTimePaymentSession({
41+
* presentationMode: 'popup',
42+
* createOrder: async () => ({ orderId: 'ORDER-123' }),
43+
* onApprove: (data) => console.log('Approved:', data),
44+
* onCancel: () => console.log('Cancelled'),
45+
* });
46+
* const { eligiblePaymentMethods } = usePayPal();
47+
* const payLaterDetails = eligiblePaymentMethods?.getDetails?.("paylater");
48+
*
49+
* if (isPending) return null;
50+
* if (error) return <div>Error: {error.message}</div>;
51+
*
52+
* return (
53+
* <paypal-pay-later-button
54+
* countryCode={payLaterDetails?.countryCode}
55+
* productCode={payLaterDetails?.productCode}
56+
* onClick={handleClick}
57+
* onCancel={handleCancel}
58+
* />
59+
* );
60+
* }
61+
*/
2962
export function usePayLaterOneTimePaymentSession({
3063
presentationMode,
3164
fullPageOverlay,

‎packages/react-paypal-js/src/v6/hooks/usePayPal.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ import type { PayPalProvider } from "../components/PayPalProvider";
66
import type { PayPalState } from "../context/PayPalProviderContext";
77

88
/**
9-
* Returns {@link PayPalContext} provided by a parent {@link PayPalProvider}.
9+
* Returns {@link PayPalState} provided by a parent {@link PayPalProvider}.
1010
*
11-
* @returns {PayPalContext}
11+
* @returns {PayPalState}
1212
*/
1313
export function usePayPal(): PayPalState {
1414
const context = useContext(PayPalContext);

‎packages/react-paypal-js/src/v6/hooks/usePayPalCreditOneTimePaymentSession.ts‎

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -31,20 +31,30 @@ export type UsePayPalCreditOneTimePaymentSessionProps = (
3131
* This hook creates and manages a PayPal Credit payment session. It handles session lifecycle, resume flows
3232
* for redirect-based flows, and provides methods to start, cancel, and destroy the session.
3333
*
34+
* @returns Object with: `error` (any session error), `isPending` (SDK loading), `handleClick` (starts session), `handleCancel` (cancels session), `handleDestroy` (cleanup)
3435
*
3536
* @example
36-
* const { error, handleClick, handleCancel, handleDestroy } = usePayPalCreditOneTimePaymentSession({
37-
* presentationMode: 'popup',
38-
* createOrder: async () => ({ orderId: 'ORDER-123' }),
39-
* onApprove: (data) => console.log('Approved:', data),
40-
* onCancel: () => console.log('Cancelled'),
41-
* });
42-
* const { eligiblePaymentMethods } = usePayPal();
43-
* const countryCode = eligiblePaymentMethods.eligible_methods.paypal_credit.country_code;
37+
* function CreditCheckoutButton() {
38+
* const { error, isPending, handleClick, handleCancel } = usePayPalCreditOneTimePaymentSession({
39+
* presentationMode: 'popup',
40+
* createOrder: async () => ({ orderId: 'ORDER-123' }),
41+
* onApprove: (data) => console.log('Approved:', data),
42+
* onCancel: () => console.log('Cancelled'),
43+
* });
44+
* const { eligiblePaymentMethods } = usePayPal();
45+
* const creditDetails = eligiblePaymentMethods?.getDetails?.("paypal_credit");
4446
*
45-
* return (
46-
* <paypal-credit-button countryCode={countryCode} onClick={handleClick}></paypal-credit-button>
47-
* )
47+
* if (isPending) return null;
48+
* if (error) return <div>Error: {error.message}</div>;
49+
*
50+
* return (
51+
* <paypal-credit-button
52+
* countryCode={creditDetails?.countryCode}
53+
* onClick={handleClick}
54+
* onCancel={handleCancel}
55+
* />
56+
* );
57+
* }
4858
*/
4959
export function usePayPalCreditOneTimePaymentSession({
5060
presentationMode,

‎packages/react-paypal-js/src/v6/hooks/usePayPalCreditSavePaymentSession.ts‎

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -31,19 +31,30 @@ export type UsePayPalCreditSavePaymentSessionProps = (
3131
* This hook creates and manages a PayPal Credit save payment session for vaulting payment methods.
3232
* It handles session lifecycle, resume flows for redirect-based flows, and provides methods to start, cancel, and destroy the session.
3333
*
34+
* @returns Object with: `error` (any session error), `isPending` (SDK loading), `handleClick` (starts session), `handleCancel` (cancels session), `handleDestroy` (cleanup)
35+
*
3436
* @example
35-
* const { error, handleClick, handleCancel, handleDestroy } = usePayPalCreditSavePaymentSession({
36-
* presentationMode: 'redirect',
37-
* createVaultToken: async () => ({ vaultSetupToken: 'VAULT-TOKEN-123' }),
38-
* onApprove: (data) => console.log('Vaulted:', data),
39-
* onCancel: () => console.log('Cancelled'),
40-
* });
41-
* const { eligiblePaymentMethods } = usePayPal();
42-
* const countryCode = eligiblePaymentMethods.eligible_methods.paypal_credit.country_code;
37+
* function SaveCreditButton() {
38+
* const { error, isPending, handleClick, handleCancel } = usePayPalCreditSavePaymentSession({
39+
* presentationMode: 'redirect',
40+
* createVaultToken: async () => ({ vaultSetupToken: 'VAULT-TOKEN-123' }),
41+
* onApprove: (data) => console.log('Vaulted:', data),
42+
* onCancel: () => console.log('Cancelled'),
43+
* });
44+
* const { eligiblePaymentMethods } = usePayPal();
45+
* const creditDetails = eligiblePaymentMethods?.getDetails?.("paypal_credit");
46+
*
47+
* if (isPending) return null;
48+
* if (error) return <div>Error: {error.message}</div>;
4349
*
44-
* return (
45-
* <paypal-credit-button countryCode={countryCode} onClick={handleClick}></paypal-credit-button>
46-
* )
50+
* return (
51+
* <paypal-credit-button
52+
* countryCode={creditDetails?.countryCode}
53+
* onClick={handleClick}
54+
* onCancel={handleCancel}
55+
* />
56+
* );
57+
* }
4758
*/
4859
export function usePayPalCreditSavePaymentSession({
4960
presentationMode,

0 commit comments

Comments
 (0)