@adyen/kyc-components 2.39.2 → 2.40.0

package/README.md

@@ -1,163 +1,59 @@
-[![Test CI](https://github.com/Adyen/adyen-kyc-components/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/Adyen/adyen-kyc-components/actions/workflows/main.yml) [![End-to-End Tests](https://github.com/Adyen/adyen-kyc-components/actions/workflows/e2e-test.yml/badge.svg)](https://github.com/Adyen/adyen-kyc-components/actions/workflows/e2e-test.yml)
+# Adyen KYC Components (Onboarding Components)
 
-# Adyen KYC Components
-
-`adyen-kyc-components` provides the required pieces to build an onboarding flow based on a legal entity.
+`adyen-kyc-components` provides the required pieces to build an onboarding flow based on a legal entity. To onboard and verify users, you need to create a user interface (UI) to collect user data. To speed up building your integration, Adyen offers onboarding components. You can integrate these components into your UI to let your users enter their data. The component then uses the entered data to create the relevant resource. This means you don't need to implement the API call to create the resource yourself.
 
 ## Setup
 
-1. Including the sdk
+1. Install and import the npm package
 
-   - if using npm package
+   - Install the node package
 
-   ```js
-   import AdyenKyc from '@adyen/kyc-components';
+   ```
+    npm install @adyen/kyc-components --save
    ```
 
-   - if using umd format, include below in the html file
+   - Import the package and the style sheet in your application
 
    ```
-   <link href="/kycexternalapi/static/sdk/1.0.0/adyen-kyc-components.css" rel="stylesheet"/>
-   <script src="/kycexternalapi/static/sdk/1.0.0/adyen-kyc-components.js"  type="text/javascript" ></script>
+    import AdyenKyc from '@adyen/kyc-components';
+    import '@adyen/kyc-components/styles.css';
    ```
 
 2. Initializing the sdk
 
    ```js
-      const kyc = new AdyenKyc({
-          countryCode: 'US',
-          clientKey: '',
-          environment: 'https://kyc-test.adyen.com/kyc' OR 'https://kyc-live.adyen.com/kyc'
-      });
+   const adyenKycHandler = new AdyenKyc({
+     locale: 'en-US',
+     country: 'US',
+     environment: 'https://test.adyen.com',
+     sdkToken: token,
+     getSdkToken,
+   });
    ```
 
-3. Including form Components
+3. Including createTransferInstrument component
 
    ```js
-   const form = kyc.create('personalDetails', {
-     onChange: (val) => {
-       console.log(val);
-     },
-   });
-
-   form.mount('#container');
+   const createTransferInstrumentComponent = adyenKycHandler
+     .create('createTransferInstrumentComponent', {
+       legalEntityId,
+       transferInstrumentId, // Optional
+       openBankingPartnerConfigId: 'YourBrandOBConfigId',
+       settings: {
+         allowIntraRegionCrossBorderPayout: true, // Optional
+         allowBankAccountFormatSelection: true, // Optional
+       },
+       onSubmitSuccess: (submittedData) => {},
+     })
+     .mount('#create-transfer-instrument-container'); // Mount to the container you created
    ```
 
-Configurations based on a country are underway, each form component will be capable of taking
-in a country as a prop, based on which it will be rendered. If no country is provided the country
-value provided during initialization will be used.
-
-## Configuration
-
-#### **`AdyenKyc(config: Config)`**
-
-**`Config`**
-
-| Key           | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `locale`      | `en-US` | the locale country code                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `country`     | `US`    | the resident country code                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `clientKey`   |         | the client key to contact the KYC external API where the configuration API lives. In order for the SDK to work, your webpage needs to configure a clientKey that can be used by the SDK. The procedure for obtaining a `clientKey` for KYC Components are the same as for our other Web components. The details are listed on [docs.adyen.com](https://docs.adyen.com/development-resources/client-side-authentication#get-your-client-key) |
-| `environment` |         | the domain where the KYC external api can be contacted.                                                                                                                                                                                                                                                                                                                                                                                     |
-
-#### **`AdyenKyc.create(dropinComponentName: ComponentName, options: Options)`**
-
-**`ComponentName`**
-Possible values are:
-| Value | Description |
-|---|---|
-| `'taskList'` **recommended** | Let the SDK list the tasks that require completion. The navigation between each task will be handled internally. The rendering of drop-ins and navigation will be decided automatically. |
-| `'individualDropin'` | KYC details for a natural person
-| `'companyDropin'` | KYC details for an organization
-| `'payoutAccount'` | KYC details for a transfer instrument
-
-**`Options`**
-
-| Option                    | Required  | Type                                                                                                                                                                               | Remarks                                                                                                                                                                                                                                                                                                                               |
-| ------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `legalEntityResponse`     | Required  | Legal Entity _object_ that is returned from the [Legal Entities API](https://docs.adyen.com/api-explorer/#/balanceplatform/v1/get/legalEntities/{id})                              | this now contains extended properties, see [legal-entity.ts](https://github.com/Adyen/adyen-kyc-components/blob/main/packages/lib/src/core/models/api/legal-entity.ts) for more details                                                                                                                                               |
-| `capabilities`            | Required  | _array_                                                                                                                                                                            | List of capabilities that are being requested, e.g. ['PSP_PAYOUT']                                                                                                                                                                                                                                                                    |
-| `readOnly`                | Rrequired | _boolean_                                                                                                                                                                          | to set form to read only mode                                                                                                                                                                                                                                                                                                         |
-| `country`                 | Optional  | _string_                                                                                                                                                                           | overrides resident country set in the Config that initialises the AdyenKyc                                                                                                                                                                                                                                                            |
-| `showInlineErrors`        | Optional  | _boolean_                                                                                                                                                                          | show errors inline or only above form                                                                                                                                                                                                                                                                                                 |
-| `onChange`                | Optional  | _(state) => void_                                                                                                                                                                  | method that passes on the entire state when changes to the state of the forms have changed. _state_ in the case of the Individual form will be of type [IndividualSchema](https://github.com/Adyen/adyen-kyc-components/blob/main/packages/lib/src/components/Individual/types.ts#:~:text=export%20interface-,IndividualSchema,-%7B). |
-| `onSubmit`                | Optional  | _(state) => void_                                                                                                                                                                  | method that passed on the entire state _after_ submitted data has been handled by the backend (successfully received a 200 response). <br />_i.e. User clicks form submit -> API handler promise fired -> promise resolves successfully -> fires onSubmit_                                                                            |
-| `handleGetLegalEntity`    | Required  | _(legalEntityId: string) => Promise\<LegalEntity\>_                                                                                                                                | method for getting a Legal Entity using the [legalEntities API](https://docs.adyen.com/api-explorer/#/balanceplatform/v1/get/legalEntities/{id}).                                                                                                                                                                                     |
-| `handleCreateLegalEntity` | Required  | _(data: [LegalEntity](https://github.com/Adyen/adyen-kyc-components/blob/main/packages/lib/src/core/models/api/legal-entity.ts)) => Promise\<LegalEntity\>_                        | method for creating a legal entity using the [legalEntities API](https://docs.adyen.com/api-explorer/#/balanceplatform/v1/post/legalEntities).                                                                                                                                                                                        |
-| `handleUpdateLegalEntity` | Required  | _(data: [LegalEntity](https://github.com/Adyen/adyen-kyc-components/blob/main/packages/lib/src/core/models/api/legal-entity.ts), legalEntityId: string) => Promise\<LegalEntity\>_ | method for updating a legal entity using the [legalEntities API](https://docs.adyen.com/api-explorer/#/balanceplatform/v1/patch/legalEntities/{id}).                                                                                                                                                                                  |
-| `handleCreateIdDocument`  | Required  | _(data: [Document](https://github.com/Adyen/adyen-kyc-components/blob/main/packages/lib/src/core/models/api/document.ts)) => Promise\<Document\>_                                  | method for creating a document using the [documents API](https://docs.adyen.com/api-explorer/#/balanceplatform/v1/post/documents).                                                                                                                                                                                                    |
-| `handleUpdateIdDocument`  | Required  | _(data: [Document](https://github.com/Adyen/adyen-kyc-components/blob/main/packages/lib/src/core/models/api/document.ts), , documentId: string) => Promise\<Document\>_            | method for updating a document using the [documents API](https://docs.adyen.com/api-explorer/#/balanceplatform/v1/patch/documents/{id}).                                                                                                                                                                                              |
-
-## Server configuration
-
-To complete the setup of the Adyen SDK the following additional configurations are needed on your server. These configurations are listed below.
-
-### Content Security Policy
-
-In order for the SDK to reach out to the Adyen servers for configuration requests and assets, additional [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) need to be configured. On top of your existing configration the following domains need to be added:
-
-| Environment | CSP Section | Value                      |
-| ----------- | ----------- | -------------------------- |
-| Test        | connect-src | https://kyc-test.adyen.com |
-| Test        | font-src    | https://kyc-test.adyen.com |
-| Test        | img-src     | https://kyc-test.adyen.com |
-| Live        | connect-src | https://kyc-live.adyen.com |
-| Live        | font-src    | https://kyc-live.adyen.com |
-| Live        | img-src     | https://kyc-live.adyen.com |
-
-## Mock API
-
-[The `server` folder contains the mock API](./server). It is used to develop without running the Adyen platform.
-It is also used during e2e testing in CI jobs.
-
-## End-to-end tests
-
-End-to-end tests live in the [tests](./tests) folder. The E2E test framework we use is [Playwright](https://playwright.dev/).
-
-To run the e2e tests locally, simply do `npm run test:e2e -- --project {browser}`, where `{browser}` can be one of:
-
-- `local-chrome`: uses the Google Chrome installation already present on your machine.
-- `chromium`: uses the latest stable Chromium binary installed via `playwright install`.
-  This is usually a major version ahead of Chrome & Edge.
-- `firefox`: uses the latest stable Firefox binary installed via `playwright install`.
-- ~~`webkit` : uses the latest stable WebKit binary installed via `playwright install`~~ (currently disabled)
-
-For more info on the available browsers, [see here](https://playwright.dev/docs/browsers).
-
-By default, Playwright runs in headed mode in development, and headless in CI.
-
-### Debugging E2E tests
-
-When you need to figure out why a test is (or isn't) failing, `npm run test:e2e:debug` is your friend.
-There are a few tools here which come in handy:
-
-- [Playwright Inspector](https://playwright.dev/docs/debug#playwright-inspector):
-  This tool allows you to explore the selectors Playwright is checking and see what user actions it is performing.
-- `.only()`: Add this to any of your tests to make it the only test Playwright runs.
-- `page.pause()`: You can use this to make Playwright pause execution (and open the inspector) at a specific point in any test.
-- Dev Tools: You can use the browser's dev tools as normal when inspecting a Playwright test.
-  For example, you can see what network requests are being made in the network tab.
-  Playwright will also add a `window.playwright` object you can use to test out [locators](https://playwright.dev/docs/locators).
-
-For more info on debugging Playwright tests, [see here](https://playwright.dev/docs/debug).
-
-### Viewing traces
-
-When the E2E tests fail on CI, it can be quite difficult to figure out why. For that, we can use [Playwright's trace viewer](https://playwright.dev/docs/trace-viewer).
-This tool lets us view a recorded test run and "replay" what happened. It includes screenshots, logs of browser console & network requests, and more.
-
-To use it, first download the report artifact for the given test run from GitHub:
-
-1. Find your test run [here](https://github.com/Adyen/adyen-kyc-components/actions/workflows/e2e-test.yml) (or click on the check from the PR).
-2. If the tests failed, you should see `playwright-report-{xxxxx}` under _Artifacts_.
-3. Download this file and unzip it. Inside, you will find a `data` directory which contains more `.zip`s. Each of these is the trace for a single test.
-4. To view a trace, upload the `.zip` xto [trace.playwright.dev](https://trace.playwright.dev/).
+See our [Onboarding components documentation](https://docs.adyen.com/platforms/onboard-users/onboarding-components/) for more details.
 
-## Static assets
+## Supported countries/regions
 
-[Static assets](./assets) are compiled and shipped separately to kycexternalapi every time a new asset is added or changed.
-For more information see the [documentation for static assets](./assets/README.md).
+You can use the Onboarding components to onboard users operating in countries listed [here](https://docs.adyen.com/platforms/onboard-users/onboarding-components/#supported-countries-regions).
 
-## Contributing
+## Supported languages
 
-We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to standardize our commit messages and validate this in our CI. [More reading.](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716)
+You can localize the Onboarding components by setting `locale` parameter to one of the supported languages listed [here](https://docs.adyen.com/platforms/onboard-users/onboarding-components/#supported-languages).