npm package: @foeewni/oneclick-client
Description: Client for the Oneclick service of Friends of the Earth England Wales and Northern Ireland
Author: Friends of the Earth EWNI
Latest version: 1.3.2

# FOE EWNI OneClick Client 🖱️
This repo contains the build the OneClick.

## Usage

Import the client on your script as such:

```
import OneClick from './oneclick';
```

Instantiate the client with the provided options and relative auth keys for the environment chosen:

```
const client = new OneClick({
  env: 'uat',
  keys: {
    validate: '',
    invalidate: '',
    prefill: '',
    upgrade: '',
    card: '',
  }
});
```

Then dispatch an async call to the client as such:

```
button.addEventListener('click', async () => {
  const response = await client.prefill(token.value);
  console.log(response); // Contains response, if you need it
  client.populate(form); // Populate a form with the previous yielded response.
});
```

Methods available:

- `client.oneClickEnabled()` grabs the oneclick token from the query parameter and yields it in memory.
- `client.prefill(token);` requests a prefill object, token is optional if oneClickEnabled() is called before.
- `client.upgrade(token);` requests a direct debit upgrade, token is optional if oneClickEnabled() is called before.
- `client.card(token);` requests a card information detail, token is optional if oneClickEnabled() is called before.
- `client.populate(formElement);` populates a form element. Requires `data-oneclick` attributes on fields. Requires a previous request. Data is yielded in memory.
- `client.clear(formElement);` clears a form element. Take notice: this method also invalidates the token when called.
- `client.getData();` clears a form element. Take notice: this method also invalidates the token when called.
- `client.getToken();` clears a form element. Take notice: this method also invalidates the token when called.

## Attribute data-oneclick

Adding `data-oneclick` to input or any other element it'll help the oneclick client to target and replace the input values inside when running the `.populate()` method.

The attribute value must be either:

- `hide` or `hidden` to hide the element during population
- `parent.child` key path in dotted notation that corresponds with the actual final value wanted. Eg: `data-oneclick="name.first_name"` will replace the input with the `first_name` value inside `name` from the response object.

Another additional required bit is a placeholder element with the `data-oneclick-greeting` attribute, this is used as a target to create a greeting to the user based on their first name and a button to reset the form to its original state.

By adding a value to the attribute the message will be customised, for example `data-oneclick-greeting="Hey good fella {{name.last_name}}"` will generate a message with a replacement for the curly brackets with the last name.

If a custom greeting is needed you can integrate it yourself by tapping into DOM events described below to know when a form is prefilled and implementing your own reset button.

## DOM Custom events.

Events can be listened for each population event, here is a comprehensive list of listenable events broadcasted to the document root.

- `oneclick:prefilled`
- `oneclick:completed`
- `oneclick:hidden`
- `oneclick:clear`

## How to build
`yarn install` then `yarn run build`

## Launching Dev
`yarn run dev` launches a Vitejs dev server instance, the dev server runs on `http://localhost:3000`. Please read and follow instructions on your `.env.example` file to ease out development.

## Releasing
Run `npm version [major|minor|patch]` to bump the semantic versioning details within our package.json and push a commit via the usual PR/code review route (i.e. PR to `develop` branch, then PR to `main`.).  Check release here https://www.npmjs.com/package/@foeewni/oneclick-client