@paypal/merchant-onboarding-sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,19 +1,8 @@
 # Merchant Onboarding SDK
 
 This SDK simplifies the integration of merchant onboarding workflows into any
-application that includes the SDK script. It provides a set of tools and
-utilities to manage the onboarding process, including:
-
-- **Workflow Management:** Handles complex onboarding flows with dynamic steps
-  and redirects.
-- **Data Collection and Validation:** Simplifies the collection and validation
-  of merchant data.
-- **Integration with Backend Services:** Provides seamless integration with
-  backend services for data persistence and other operations.
-- **User Context Management:** Maintains user context throughout the onboarding
-  journey.
-- **Tracking and Analytics:** Tracks onboarding progress and gathers analytics
-  data.
+application that uses the SDK package. It provides a set of tools and utilities
+to manage the onboarding process, including:
 
 ## Table of Contents
 
@@ -24,150 +13,126 @@ utilities to manage the onboarding process, including:
   - [`Paypal.onboard.initialize()`](#paypalonboardinitialize)
   - [`Paypal.onboard.render()`](#paypalonboardrender)
   - [Styling Options](#styling-options)
-- [CDN Information](#cdn-information)
-  - [Current CDN Locations](#current-cdn-locations)
-  - [CDN Distribution](#cdn-distribution)
 
 ## Getting Started
 
 ### Installation
 
-#### Install all dependencies to run the sdk
+#### Install the SDK
 
 ```bash
-npm install
+npm install @paypal/merchant-onboarding-sdk
 ```
 
-#### Build to generate the distribution files under dist
-
-This will generate all the distribution files for development,staging,sandbox
-and production
-
-```bash
-npm run build
-```
-
-#### Build to generate the distribution file for a specific test environment
-
-This will generate a distribution file for a specific test environment
-
-```bash
-npm run build:staging:te -- te=<<te-name>>
-```
-
-Ex: npm run build:staging:te -- te=te-rio-hybrid
-
-#### Run and test locally
+## Usage
 
-1. generate sdk for development ` npm run build:dev`
-2. copy dist/v1/js/development.partner.js into partner application
-3. on partner application add script referencing the file you just copy
+### 1. Add sdk package to your UI element
 
-```
-<script src="./script/development.partner.js"></script>
-<div id="root"></div>
+```aiexclude
+import { onboard } from "@paypal/merchant-onboarding-sdk/onboarding";
 ```
 
-4. on partner application initialize and render the sdk using `Paypal` object:
+OR
 
 ```aiexclude
-       window.Paypal.onboard
-            .initialize({
-                env: 'production', // required for node_module integrations only
-                accessToken: 'A21_A.AAdU_t4bpoqBrSPWCvZWX7px-4feNn6Ap1Ixon9zgB46GNnibPWM_GrYcwTUBou-8LUM1WSOP5-XUecATSod2E1x-eoYPA',
-                actionUrl: 'https://te-hybrid-path-sdk.qa.paypal.com/bizsignup/partner/entry?referralToken=ZjRmMTdiNjItMDhlNi00ZjJiLTk3ODAtNTQ0NzE3YjI5MTRkQ3pncW5vYlZpaEZOUnpmc082bTRVekphRENVcy9iWjJmWUt1b3l3TWNidz12Mg==',
-                cancelUrl: 'http://localhost:3002/index3.html' // add partner's app url
-                style: {
-                    color: {
-                        background: {
-                            highContrast: '#48484a', // font color
-                        },
-                        primary: {
-                            main: '#1b75bc', //header & button
-                            mainHover: '#1871b6',
-                            mainActive: '#204d74', // button color after you click
-                        },
-                    },
-                },
-                onError: function (error,errorInfo) {
-                    alert("There is an error\nError: " + error +"\nError Description: \n"+ errorInfo)
-                    window.location.reload()
-                },
-                onSDKError: function (error,errorInfo) {
-                    alert("There is an error\nError: " + error +"\nError Description: \n"+ errorInfo.componentStack)
-                    window.location.reload()
-                },
-                onProgress: function (progress) {},
-                onComplete: function () { alert("Onboard completed!!")},
-                onAccessTokenExpiry: function () {},
-                onReferralTokenExpiry: function () {},
-                onCancel: function () {alert("User cancelled the onboarding")},
-                onContactUs: function () {}
-                onLoginRequested: async function (spokePayerId) {} // STANDALONE_HYBRID partners only
-            })
-            .render('root')
-    }
+import { servicing } from "@paypal/merchant-onboarding-sdk/servicing";
 ```
 
-5. start partner app
-6. Launch sample partner html and test
-
-## Usage
+Do not add both packages to the DOM at the same time as they should not be used
+concurrently.
 
-1- Add sdk and create container to the partner app (external to paypal)
+#### Usage NOTE
 
-```aiexclude
-<script src="https://www.paypalobjects.com/sdk/v1/js/partner.js"></script>
-<div id="container"></div>
-```
+If you use SSR, import the script only in the UI as it relies on client-side
+global objects like `window`
 
-2- initialize sdk in the partner app
+Example:
 
 ```aiexclude
-window.Paypal.onboard
-            .initialize({
-                env: '<<desired_env>>',
-                accessToken: '<<partner_access_Token>>',
-                actionUrl: '<<action_url_with_referral_token>>',
-                style: <<customized_styling_object>>,
-                onError: <<callback_OnError_function>>
-                onSDKError: <<callback_onSDKError_function>>,
-                onProgress: <<callback_onProgress_function>>,
-                onComplete: <<callback_onComplete_function>>,
-                onAccessTokenExpiry: <<callback_onAccessTokenExpiry_function>>,
-                onReferralTokenExpiry: <<callback_onReferralTokenExpiry_function>>,
-                onCancel: <<callback_onCancel_function>>,
-                onContactUs: <<callback_onContactUs_function>>
-                onLoginRequested: <<callback_onLoginRequested_function>>
-            })
+import {
+    Onboard,
+    OnboardOptions,
+} from "@paypal/merchant-onboarding-sdk/onboarding";
+
+const [onboard, setOnboard] = useState<Onboard>(null as unknown as Onboard);
+
+useEffect(() => {
+    const initSdk = async () => {
+      const onbPackage = await import(
+        "@paypal/merchant-onboarding-sdk/onboarding"
+      );
+      setOnboard(onbPackage.default as unknown as Onboard);
+    };
+    initSdk();
+}, []);
+
+useEffect(() => {
+    if (onboard) {
+      onboard.initialize({ // props }).render("elementId")
+    }
+}, [onboard])
 ```
 
-3- render onboarding flow in the partner app
+### 2. initialize sdk in your app and render
 
 ```aiexclude
-window.Paypal.onboard.render('container')
+onboard
+    .initialize({
+        env: 'production', // required for node_module integrations only
+        accessToken: 'A21_A.AAdU_t4bpoqBrSPWCvZWX7px-4feNn6Ap1Ixon9zgB46GNnibPWM_GrYcwTUBou-8LUM1WSOP5-XUecATSod2E1x-eoYPA',
+        actionUrl: 'https://www.paypal.com/bizsignup/partner/entry?referralToken=ZjRmMTdiNjItMDhlNi00ZjJiLTk3ODAtNTQ0NzE3YjI5MTRkQ3pncW5vYlZpaEZOUnpmc082bTRVekphRENVcy9iWjJmWUt1b3l3TWNidz12Mg==',
+        cancelUrl: 'http://www.partner.com/cancelUrl' // add partner's app url
+        style: {
+            color: {
+                background: {
+                    highContrast: '#48484a', // font color
+                },
+                primary: {
+                    main: '#1b75bc', //header & button
+                    mainHover: '#1871b6',
+                    mainActive: '#204d74', // button color after you click
+                },
+            },
+        },
+        onError: async function (error,errorInfo) {
+            alert("There is an error\nError: " + error +"\nError Description: \n"+ errorInfo)
+            window.location.reload()
+        },
+        onSDKError: async function (error,errorInfo) {
+            alert("There is an error\nError: " + error +"\nError Description: \n"+ errorInfo.componentStack)
+            window.location.reload()
+        },
+        onProgress: async function (progress) {},
+        onComplete: async function () { alert("Onboard completed!!")},
+        onAccessTokenExpiry: async function () {},
+        onReferralTokenExpiry: async function () {},
+        onCancel: async function () {alert("User cancelled the onboarding")},
+        onContactUs: async function () {}
+        onLoginRequested: async function (spokePayerId) { return await getToken()} // STANDALONE_HYBRID partners only
+    })
+    .render('root')
 ```
 
 ## SDK Reference
 
 ### `Paypal.onboard.initialize(props)`
 
-| Parameter               | Type       | Description                                                                                                                    | Required                                           |
-| ----------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
-| `accessToken`           | `string`   | The access token for authentication.                                                                                           | Yes                                                |
-| `env`                   | `string`   | The env that should be used. Possible values are 'sandbox' or 'production'                                                     | No (defaults to 'production' for npm integrations) |
-| `actionUrl`             | `string`   | The URL containing the `referralToken`.                                                                                        | Yes                                                |
-| `cancelUrl`             | `string`   | The URL to return from onboarding on cancel.                                                                                   | No                                                 |
-| `style`                 | `object`   | Styling options (see below).                                                                                                   | No                                                 |
-| `onProgress`            | `function` | Callback function that receives a `progress` object (structure TBD).                                                           | No                                                 |
-| `onComplete`            | `function` | Callback function invoked when onboarding completes successfully.                                                              | No                                                 |
-| `onAccessTokenExpiry`   | `function` | Callback function invoked when the access token expires. The partner should refresh the token and provide a new `actionUrl`.   | No                                                 |
-| `onReferralTokenExpiry` | `function` | Callback function invoked when the referral token expires. The partner should refresh the token and provide a new `actionUrl`. | No                                                 |
-| `onCancel`              | `function` | Callback function invoked when the user cancels onboarding.                                                                    | No                                                 |
-| `onError`               | `function` | Callback function invoked when an error occurs during onboarding. Receives `error` and `errorInfo` objects.                    | No                                                 |
-| `onSDKError`            | `function` | Callback function invoked for SDK-specific errors. Receives `error` and `errorInfo` objects.                                   | No                                                 |
-| `onContactUs`           | `function` | Callback function to display contact information when appropriate.                                                             | No                                                 |
-| `onLoginRequested`      | `function` | Callback function to fetch access token for spoke-only merchant.                                                               | Yes (only for spoke-only partners)                 |
+| Parameter               | Type       | Description                                                                                                                          | Required                                           |
+| ----------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
+| `accessToken`           | `string`   | The access token for authentication.                                                                                                 | Yes                                                |
+| `env`                   | `string`   | The env that should be used. Possible values are 'sandbox' or 'production'                                                           | No (defaults to 'production' for npm integrations) |
+| `actionUrl`             | `string`   | The URL containing the `referralToken`.                                                                                              | Yes                                                |
+| `cancelUrl`             | `string`   | The URL to return from onboarding on cancel.                                                                                         | No                                                 |
+| `style`                 | `object`   | Styling options (see below).                                                                                                         | No                                                 |
+| `onProgress`            | `function` | Async Callback function that receives a `progress` object (structure TBD).                                                           | No                                                 |
+| `onComplete`            | `function` | Async Callback function invoked when onboarding completes successfully.                                                              | No                                                 |
+| `onAccessTokenExpiry`   | `function` | Async Callback function invoked when the access token expires. The partner should refresh the token and provide a new `actionUrl`.   | No                                                 |
+| `onReferralTokenExpiry` | `function` | Async Callback function invoked when the referral token expires. The partner should refresh the token and provide a new `actionUrl`. | No                                                 |
+| `onCancel`              | `function` | Async Callback function invoked when the user cancels onboarding.                                                                    | No                                                 |
+| `onError`               | `function` | Async Callback function invoked when an error occurs during onboarding. Receives `error` and `errorInfo` objects.                    | No                                                 |
+| `onSDKError`            | `function` | Async Callback function invoked for SDK-specific errors. Receives `error` and `errorInfo` objects.                                   | No                                                 |
+| `onContactUs`           | `function` | Async Callback function to display contact information when appropriate.                                                             | No                                                 |
+| `onLoginRequested`      | `function` | Async Callback function to fetch access token for STANDALONE_HYBRID merchant.                                                        | Yes (only for spoke-only partners)                 |
 
 ### `Paypal.onboard.render(containerId)`
 
@@ -180,33 +145,9 @@ maintain a design system, such as spacing, color, size, space, motion, etc.
 Styles can be passed using these tokens and Paypal will override its Theme with
 the tokens passed using vanilla-extract.
 
-You can check the Paypal theme token and values in
-https://github.paypal.com/PayPal-UI-R/pp-react/blob/f3dd9e2cd9b8478f0d9a07411290314ca127de52/packages/theme/src/theme.css.ts#L6C14-L6C27
-To override with specific styles just add in <<customized_styling_object>> the
-desire tokens following the PayPal Theme token format(see example in
-[Installation](#installation))
-
-## CDN Information
-
-### Current CDN locations
-
-| Environment | sdk to use                                                                                                        |
-| ----------- | ----------------------------------------------------------------------------------------------------------------- |
-| Production  | https://www.paypalobjects.com/sdk/v1/js/partner.js https://www.paypalobjects.com/sdk/v1/js/partner.js.LICENSE.txt |
-| Sandbox     | https://www.paypalobjects.com/sdk/v1/js/sandbox.partner.js                                                        |
-| Staging     | https://www.paypalobjects.com/sdk/v1/js/staging.partner.js                                                        |
-| Development | https://www.paypalobjects.com/sdk/v1/js/development.partner.js                                                    |
-
-## CDN distribution:
-
-Once distribution files are generated and tested locally using demo pages, you
-can deploy them by
+To override with specific styles just add the `style` object to the props in
+onboard.initialize({}) as shown in
+[Initialize and Render](#2-initialize-sdk-in-your-app-and-render)
 
-1. go to https://go/cdnxui
-2. the namespace is 'sdk'. If you don't see the namespace under "Your
-   Namespaces" list, please contact @besierra or @augreer
-3. click on Files
-4. Start a new upload
-5. Test using staging url
-6. Send for approval
-7. You can deploy once approved
+The Style object takes the format of a vanilla-extract Theme:
+https://vanilla-extract.style/documentation/theming/

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export interface OnboardOptions {
     onError?: (error: any, errorInfo?: any) => void;
     onSDKError?: (error: any, errorInfo?: any) => void;
     onContactUs?: () => void;
+    onLoginRequested?: (payerId: string) => Promise<string>;
     [key: string]: any;
 }
 
@@ -18,12 +19,13 @@ export interface Onboard {
     initialize(props: OnboardOptions): this;
     onProgress(progress: any): void;
     onComplete(): void;
-    onAccessTokenExpiry(): any;
+    onAccessTokenExpiry(): Promise<string>;
     onReferralTokenExpiry(): void;
     onCancel(): void;
     onError(error: any, errorInfo?: any): void;
     onSDKError(error: any, errorInfo?: any): void;
     onContactUs(): void;
+    onLoginRequested(payerId: string): Promise<string>;
     render(elementId: string): this;
     _getClientToken(): Promise<string>;
 }