npm package: @kuantaz/api-client
Description: JS API client to communicate with kzCaptcha.
Author: Kuantaz
Latest version: 1.0.0

&nbsp;

<h1 align="center">
    KzCaptcha JS API Client
</h1>
<p align="center">
    This library offers the API client to communicate with kzCaptcha to verify a submission.
</p>

---

## Description

With this JavaScript library you can connect to a kzCaptcha installation and verify the submitted data.

## Installation

Install this library by using npm:

```text
npm install @kuantaz/api-client
```

## Usage

1. Create a project in your kzCaptcha installation
2. Include the kzCaptcha script in your form

```html
<div id="kzCaptcha-box"></div>

<script src="https://[URL]/build/kzCaptcha-frontend.js" defer></script>
<script>
  var m;
  window.onload = function () {
    m = new kzCaptcha("kzCaptcha-box", "https://[URL]", "[UUID]", "[PUBLIC_KEY]", { loadCssResource: true });
  };
</script>
```

3. Include the library in your project

```text
const kzCaptcha = require('@kzCaptcha/api-client');
```

4. After the form was submitted, verify the data before processing it

```js
let client = new kzCaptcha.Client(host, publicKey, privateKey, {});

kzCaptchaSubmitToken = formData._kzCaptcha_submitToken;
kzCaptchaValidationToken = formData._kzCaptcha_validationToken;

client.verifySubmission(formData, kzCaptchaSubmitToken, kzCaptchaValidationToken).then((verificationResult) => {
  if (verificationResult.isSubmittable()) {
    // Send the email or process the data
  } else {
    // Show error message
  }
});
```

## API Documentation

### Client

#### Client initialization

Create a new client object to use the API client.

```js
/**
 * @param string url URL of the kzCaptcha installation
 * @param string publicKey Public key of the kzCaptcha project
 * @param string privateKey Private key of the kzCaptcha project
 * @param array args Arguments for the axios request
 */
let client = new Client(url, publicKey, privateKey, args);
```

#### Verify form data

To verify the form data, call `verifySubmission` with the form data in an array and the submit and validation token, which kzCaptcha generated on the form initialization and the form data validation. The method will return a new Promise object that is resolved with the `VerificationResult` object.

```js
/**
 * @param array formData Array with the form values. All not-processed fields by kzCaptcha (hidden, checkbox,
 *                       radio and so on) have to be removed from this array
 * @param string kzCaptchaSubmitToken Submit token which kzCaptcha returned on the form initialization
 * @param string kzCaptchaValidationToken Validation token which kzCaptcha returned after the form was validated
 * @return Promise Returns a Promise object that is resolved with a VerificationResult object
 */
client.verifySubmission(formData, kzCaptchaSubmitToken, kzCaptchaValidationToken).then((validationResult) => {
  if (verificationResult.isSubmittable()) {
    // Do your stuff, e.g. sending emails...
  }
});
```

### VerificationResult

#### Constants

    - FIELD_NOT_VERIFIED: 'not-verified'
    - FIELD_VALID: 'valid'
    - FIELD_INVALID: 'invalid'

#### isSubmittable(): boolean

Returns true, if the form is submittable. This means that the verification was successful and the form data are valid.

#### isValid(): boolean

Returns true, if kzCaptcha determined the form as valid. The difference to `isSubmittable()` is, that this is the raw result from kzCaptcha while `isSubmittable()` also checks if the verification was done correctly.

#### getVerifiedFields(): array (see Constants)

Returns an array with all verified field keys.

#### getVerifiedField(key): string (see Constants)

Returns the verification status of one field.

#### hasIssues(): boolean

Returns true, if there were verification issues.

#### getIssues(): array

Returns an array with all verification issues.