npm package: @purefi/verifier-widget
Description: Node.js module with the Verifier Widget for PureFI decentralized AML protocol. Providing widgets for communicating with PureFI issuers
Author: Mikhail Radchenko
Latest version: 1.4.0

![Logo](https://user-images.githubusercontent.com/23620645/136548302-6bf7f6e0-8236-44bf-b75a-9c067e9347da.png)

# @purefi/verifier-widget

Node.js module with the Verifier Widget for PureFI decentralized AML protocol. Providing widgets for communicating with PureFI issuers

![typescript](https://img.shields.io/npm/types/@purefi/verifier-widget)

## Documentation

The package is built on top of [@purefi/verifier-sdk](https://verifier-sdk.purefi.io/)


## Widget API
PureFIWidget works around concept of signing messages and to do it properly it needs a [signer](https://verifier-sdk.purefi.io/interfaces/ISigner.html).

So every time chain or user account changes, pass the new signer instance to PureFIWidget.setSigner()

```javascript
// Example is based on ethers and metamask
import { ethers } from 'ethers';

const updateSigner = () => {
  const provider = new ethers.providers.Web3Provider(ethereum);
  const signer = provider.getSigner();
  PureFIWidget.setSigner(signer);
}

ethereum.on('accountsChanged', (accounts) => {
  // handling account changes
  updateSigner();
});

ethereum.on('chainChanged', (chainId) => {
  // handling chain changes
  updateSigner();
});
```

To render a widget into a DOM node, pass the element and relevant config to PureFIWidget.render()

```javascript
import { PureFIWidget } from '@purefi/verifier-widget';

const element = document.querySelector('#widget');
const config = {
  address: {
    address: '0xaAaAAAAaaAAaaaAAAaaaaaAAAAAaaAaAaAAAAaaa',
    type: 'wallet',
  },
};

PureFIWidget.render(element, config);
```
In case you need more control over screening results, pass onSuccess and onError callbacks to PureFIWidget.render()

```javascript
import { PureFIWidget } from '@purefi/verifier-widget';

const element = document.querySelector('#widget');
const config = {
  address: {
    address: '0xaAaAAAAaaAAaaaAAAaaaaaAAAAAaaAaAaAAAAaaa',
    type: 'wallet',
  },
};
const onSuccess = (response, thresholds) => console.log('onSuccess', response, thresholds);
const onError = (error) => console.log('onError', error);

PureFIWidget.render(element, config, onSuccess, onError);
```

Whenever widget container unmounts, you are supposed to notify PureFIWidget about it by passing the element to PureFIWidget.unmount()

```javascript
// React example
const widgetContainerRef = useRef();

useEffect(() => {
  const widgetContainerElement = widgetContainerRef.current;
  PureFIWidget.render(
    widgetContainerElement,
    { shouldCheckSignerAddress: true, }
  );
  return () => {
    PureFIWidget.unmount(widgetContainerElement);
  };
}, []);

return (
  <div ref={widgetContainerRef}></div>
)
```

## Widget Config
These are the available config options for a widget


```javascript
{
  // 'address' to screen. If you ommit it, 'shouldCheckSignerAddress' will be forced to true
  address?: PureFIAddress;

  // 'riskThresholds' is used for evaluation
  // the status of wallet/contract from application perspective
  // Possible values are in range [0..100]. 'low' is supposed to be less than 'high' 
  riskThresholds?: {
    low?: number; // default is 25
    high?: number; // default is 75
  };

  // 'shouldFlushOnSignerChange' instructs PureFIWidget whether it should
  // or should not flush widget instance's state when signer changes 
  shouldFlushOnSignerChange?: boolean; // default is true

  // 'shouldShowNotice' option is responsible for showing or not showing
  // notice modal on every check
  shouldShowNotice?: boolean; // default is true

  // 'shouldCloseModalOnOverlayClick' option makes widget modals closable
  // on overlay click
  shouldCloseModalOnOverlayClick?: boolean; // default is true

  // 'shouldCheckSignerAddress' instructs PureFIWidget whether it should
  // or should not include signer address(user account) into screening
  shouldCheckSignerAddress?: boolean; // default is false

  // 'shouldShowUserRejectedError' defines to show or not to show
  // error message if a user cancels 'sign message' request
  shouldShowUserRejectedError?: boolean; // default is false

  // 'shouldShowMissingSignerError' defines to show or not to show
  // error message when signer is missing
  shouldShowMissingSignerError?: boolean; // default is true
  
  // 'i18n' can be used either to change or translate all the widget texts
  // feel free to import { DefaultI18n } from '@purefi/verifier-widget'
  // and check all the available options for replacing
  i18n?: PureFII18n;
}
```

## Widget Styles
You are welcome to modify all the styles used by widget. Original styles can be found at
```javascript
node_modules/@purefi/verifier-widget/lib/purefi-widget-example.css
```
We recommend that you copy them into your own app and modify to suit your needs


## Demo
Codesanbox [demo](https://codesandbox.io/embed/github/purefiprotocol/verifier-widget-demo/tree/main/?fontsize=14&hidenavigation=1&theme=dark
)

Demo source code https://github.com/purefiprotocol/verifier-widget-demo