@banksapitechnology/regprotect-web-component/README.md

BANKSapi Web Component for REG/Protect. This package is part of the BANKSapi WEB/Connect Banking Widgets to integrate banking features directly into your app.

# regprotect-web-component

This library is maintained by [BANKSapi Technology GmbH](https://banksapi.de/).
For an overview of the features and benefits, visit our [Banking Widgets page](https://banksapi.de/en/banking-widgets-en/).

You can find more helpful technical documentation for this and other products in our [developer portal](https://docs.banksapi.de/).
For support or assistance with integration, feel free to [contact us](https://banksapi.de/contact/).

## Usage
We recommend including this library via a public CDN to automatically benefit from future improvements without requiring any action on your part.
```html
<script src="https://cdn.jsdelivr.net/npm/@banksapitechnology/regprotect-web-component/dist/ba-regprotect.js"></script>
```
#### Properties

| Property      | Attribute      | Type      | Description                                                                                                                        |
|---------------|----------------|-----------|------------------------------------------------------------------------------------------------------------------------------------|
| `sessionLink` | `session-link` | `string`  | `This link provides session information and the customer callback URL, which you are redirected to as soon as REG/Protect process is finished`                       |
| `reentryUrl`  | `reentry-url`  | `string`  | `REG/Protect Web Component needs to be reinstantiated when you get redirected to this URL. Background: A user of a provider/bank sometimes needs to perform a Redirect SCA (Strong Customer Authentication) to authenticate  with the bank/provider on the banks/providers website` |

#### Events
| Event        | Type          | Description                                                                                                                                                                                            |                                                                         
|--------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `subscribed` | `CustomEvent` | `Event emitted when REG/Protect process is finshed. "event.detail" contains the link where you can take the user back (this is the same link which was part of "sessionLink" as the "callbackUrl" query param)` |
## ba-regprotect
First, in the HTML, we need to define a container element where our web component will be mounted. This container can be any element, including the document body.
```html
<div id="ba-reprotect-container"></div>
```

Some JavaScript is required to create the web component and handle its events.  
The first step is to [generate a BANKS/Connect token](https://docs.banksapi.de/api-documentation/ui/banks-connect-api-reference.html#tag/auth/POST/auth/oauth2/token).  
**Important:** This step should be performed on the backend to avoid exposing your BANKS/Connect API credentials in the frontend.  
Once you have the token, use it to [invalidate all previous REG/Protect sessions](https://docs.banksapi.de/api-documentation/ui/banks-connect-api-reference.html#tag/customer-regprotect/DELETE/customer/v2/regprotect/sessions) for the corresponding user.

```js
async function invalidateSessions() {
  try {
    const response = await fetch(`https://banksapi.io/customer/regshield/sessions`, {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
    });

    if (!response.ok) {
      throw new Error(`${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    console.log('invalidate sessions done:', data);
  } catch (error) {
    console.error('invalidate sessions endpoint error:', error);
  }
}
```
This will give us a fresh start, so we can now implement a use case like adding a bank access

```js
async function addBankAccess() {
  try {
    // you decide what ID (usually UUIDv4) you bank access will have
    const accessId = generateUUID();
    const payload = {
      [accessId]: {}
    }
    const response = await fetch(`${API_DOMAIN}/customer/v2/bankzugaenge`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Customer-Ip-Address': customerIp,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload),
    });

    const location = response.headers.get('Location');
    // the Callback URL, will only be used in the "subscribed" event, but must adhere to the whitelist that you communicated to BANKSapi
    const callbackUrl = `${window.location.href}?event=accessCreated&accountId=${accessId}`;
    if (!location || callbackUrl.length === 0) {
      alert('the bank access request was not successful, please check your network log');
    } else {
      const wcConfirm = confirm('Switching to REG/Protect. OK?');
      if (wcConfirm) {
        const sessionLink = `${location}&callbackUrl=${callbackUrl}`;
        console.log('[sessionLink]', sessionLink);
        console.log('creating web component');
        this.createWCElement(sessionLink);
      }
    }
  } catch (error) {
    console.error('adding the bank access resulted in an error:', error);
  }
}

function createWCElement(sessionLink) {
  const demoButton = document.getElementById('start-demo');
  wcContainer = document.getElementById('ba-reprotect-container'); //.attachShadow({mode: 'closed'});
  wcElement = document.createElement('ba-regprotect');
  wcElement.sessionLink = sessionLink;
  // URL where the user will be redirected after performing SCA at Bank Provider
  wcElement.reentryUrl = 'some.example.url/path';

  wcContainer?.classList.add('regprotect-active')
  wcContainer?.appendChild(wcElement);

  wcElement.addEventListener('subscribed', handleWebComponentListener);
}

function handleWebComponentListener(event) {
  const demoButton = document.getElementById('start-demo');
  console.log('[REG/Protect WC event]', event);
  console.log('[REG/Protect WC event]', event.detail);
  // event.detail will look something like this ->
  // http://localhost:8081/?event=accountCreated&accountId=06f589bd-8d35-494a-8056-2e5d927a3aa3&baReentry=ACCOUNT_CREATED

  const callbackUrl = event.detail;
  // evaluate query param, handle event and/or baReentry

  // add use cases for add bank access, payments, etc., remove web component from DOM beforehand
  wcContainer?.removeChild(wcElement);
  wcContainer?.classList.remove('regprotect-active');

  console.log('web component event listener removed.');
  wcElement.removeEventListener('subscribed');
  wcElement = undefined;
}
```