Metadata-Version: 2.1
Name: kuantaz-api-client
Version: 1.0.1
Summary: Python API Client to communicate with kzCaptcha.
Author-email: Kuantaz Core Developers <kuantaz@kuantaz.com>
Project-URL: Website, https://kuantaz.com
Keywords: kuantaz,api-client,spam-protection,accessibility,captcha
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Requires-Python: >=3.5
Description-Content-Type: text/markdown
Requires-Dist: requests (>=2.31.0)
Provides-Extra: dev
Requires-Dist: pytest-runner ; extra == 'dev'
Requires-Dist: requests-mock ; extra == 'dev'
Requires-Dist: pip-tools ; extra == 'dev'

&nbsp;

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

---

## Description

This Python library lets you connect to a kuantaz installation and verify the submitted data.

## Installation

### Install using pip

Install this library by using pip:

```text
pip install kuantaz-api-client
```

## Usage

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

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

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

3. Include the library in your project

```text
pip install kuantaz-api-client
```

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

```python
from kuantaz_api_client import Client

api_client = Client(host, public_key, private_key)

your_post_data = {}  # This needs to be filled with the post data

kuantaz_submit_token = your_post_data['_kuantaz_submitToken']
kuantaz_validation_token = your_post_data['_kuantaz_validationToken']

result = api_client.verify_submission(your_post_data, kuantaz_submit_token, kuantaz_validation_token)

if result.is_submittable():
    # Send the email or process the data
    pass
else:
    # Show error message
    pass
```

## API Documentation

### Client

#### Client initialization

Create a new client object to use the API client.

```python
from kuantaz_api_client import Client

api_client = Client(host, public_key, private_key, verify_ssl)
```

| Parameter   | Type | Description                                                 |
| ----------- | ---- | ----------------------------------------------------------- |
| host        | str  | The host of the kuantaz installation                        |
| public_key  | str  | The public key of the kuantaz project                       |
| private_key | str  | The private key of the kuantaz project                      |
| verify_ssl  | bool | Set to False if the SSL certificate should not be verified. |

#### Verify form data

To verify the form data, call `verify_submission` with the form data in an array and the submit and validation tokens, which kuantaz generated on the form initialization and the form data validation. The method will return a `VerificationResult` object.

```python
result = api_client.verify_submission(form_data, kuantaz_submit_token, kuantaz_validation_token)
```

| Parameter                | Type | Description                                                                                                  |
| ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------ |
| form_data                | dict | The dictionary with all the submitted form data.                                                             |
| kuantaz_submit_token     | str  | The submit token which was generated by kuantaz and submitted with the form data                             |
| kuantaz_validation_token | str  | The validation token which kuantaz generated after the validation and which was submitted with the form data |

### VerificationResult

#### Constants

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

#### `is_submittable()`: bool

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

#### `is_valid()`: bool

Returns `True` if kuantaz determined the form as valid. The difference to `is_submittable()` is, that this
is the original result from kuantaz, while `is_submittable()` also checks if the verification was done correctly.

#### `get_verified_fields()`: list (see [Constants](#constants))

Returns an array with all verified field keys.

#### `get_verified_field(key)`: string (see [Constants](#constants))

Returns the verification status of one field.

#### `has_issues()`: bool

Returns `True` if there were verification issues.

#### `get_issues()`: list

Returns an array with all verification issues.

#### Get the statistic data by date

To get the statistic data grouped by date, call `get_statistic_by_date`. The method accepts a time range in seconds for which the data should be returned (last x seconds). The method will return a `StatisticResult` object.

```python
result = api_client.get_statistic_by_date(range)
```

| Parameter | Type | Description                                                                           |
| --------- | ---- | ------------------------------------------------------------------------------------- |
| range     | int  | The time range in seconds for which the statistic should be returned (last X seconds) |

### StatisticResult

#### `get_number_of_valid_submissions()`: int

Return the number of valid submissions in the requested time range.

#### `get_number_of_spam_submissions()`: int

Return the number of spam submissions in the requested time range.

#### `get_numbers_by_date()`: dict

Return the numbers grouped by date.
