Metadata-Version: 2.4
Name: fingerprint_server_sdk
Version: 9.3.0rc0
Summary: Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. 
Author: Fingerprint Support
Author-email: Fingerprint Support <support@fingerprint.com>
License: MIT
Project-URL: Repository, https://github.com/fingerprintjs/python-sdk
Keywords: OpenAPI,OpenAPI-Generator,Server API
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1
Requires-Dist: cryptography>=46.0.5
Provides-Extra: examples
Requires-Dist: python-dotenv>=1.0.0; extra == "examples"
Dynamic: author
Dynamic: license-file

<p align="center">
  <a href="https://fingerprint.com">
    <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://fingerprintjs.github.io/home/resources/logo_light.svg" />
     <source media="(prefers-color-scheme: light)" srcset="https://fingerprintjs.github.io/home/resources/logo_dark.svg" />
     <img src="https://fingerprintjs.github.io/home/resources/logo_dark.svg" alt="Fingerprint logo" width="312px" />
   </picture>
  </a>
</p>
<p align="center">
  <a href="https://pypi.org/project/fingerprint-server-sdk/"><img alt="PyPI" src="https://img.shields.io/pypi/v/fingerprint-server-sdk"></a>
  <a href="https://fingerprintjs.github.io/python-sdk/"><img src="https://fingerprintjs.github.io/python-sdk/badges.svg" alt="coverage"></a>
  <a href="https://github.com/fingerprintjs/python-sdk/actions/workflows/release.yml"><img src="https://github.com/fingerprintjs/python-sdk/actions/workflows/release.yml/badge.svg" alt="CI badge" /></a>
  <a href="https://github.com/fingerprintjs/python-sdk/actions/workflows/test.yml"><img src="https://github.com/fingerprintjs/python-sdk/actions/workflows/test.yml/badge.svg" alt="CI badge" /></a>
  <a href="https://github.com/fingerprintjs/python-sdk/actions/workflows/functional_tests.yml"><img src="https://github.com/fingerprintjs/python-sdk/actions/workflows/functional_tests.yml/badge.svg" alt="CI badge" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/:license-mit-blue.svg?style=flat"/></a>
  <a href="https://discord.gg/39EpE2neBg"><img src="https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white" alt="Discord server"></a>
</p>

# Fingerprint Server Python SDK

[Fingerprint](https://fingerprint.com) is a device intelligence platform offering industry-leading accuracy.
The Fingerprint Server Python SDK is an easy way to interact with the Fingerprint [Server API](https://dev.fingerprint.com/reference/pro-server-api) from your Python application. You can retrieve visitor history or individual identification events.


This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:

- API version: 4
- Package version: 9.3.0-rc.0
- Generator version: 7.19.0
- Build package: org.openapitools.codegen.languages.PythonClientCodegen

## Requirements

The following Python versions are supported:

- Python 3.9+

## Installation & Usage
### pip install

You can install the package directly from the Github

```sh
pip install git+https://github.com/fingerprintjs/python-sdk.git
```

Or from the PyPI

```sh
pip install fingerprint_server_sdk
```

Then import the package:
```python
import fingerprint_server_sdk
```

### Setuptools

Install via [Setuptools](http://pypi.python.org/pypi/setuptools).

```sh
python setup.py install --user
```
(or `sudo python setup.py install` to install the package for all users)

Then import the package:
```python
import fingerprint_server_sdk
```

## Getting Started

Please follow the [installation procedure](#installation--usage) and then run the following:

```python
import os

import fingerprint_server_sdk
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
# create an instance of the API class
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)
```

## Examples

Delete visitor data using `visitorId`:
```python
import os

import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, ErrorResponse
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

visitor_id = 'visitor_id_example'

try:
    api_instance.delete_visitor_data(visitor_id)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when calling FingerprintApi->delete_visitor_data: {e}'
    print(message)
```

To learn more, refer to example located in [examples/delete_visitor_example.py](examples/delete_visitor_example.py).

Fetching event details for `eventId`:
```python
import os

import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, ErrorResponse
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

event_id = 'event_id_example'

try:
    events_response = api_instance.get_event(event_id)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when calling FingerprintApi->get_event: {e}'
    print(message)
```

To learn more, refer to example located in [examples/get_event_example.py](examples/get_event_example.py).

Search events with custom filters:
```python
import os

import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, SearchEventsBot, ErrorResponse
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

limit = 20
pagination_key = 'key_example'
visitor_id = 'VISITOR_ID'
bot = SearchEventsBot.GOOD
ip_address = '192.168.0.1/32'
linked_id = 'linked_id_example'
start = 1738687200000
end = 1738773600000
reverse = True
suspect = False

try:
    # Get events via search
    api_response = api_instance.search_events(limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
    print(api_response)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when calling FingerprintApi->get_event: {e}'
    print(message)
```

To learn more, refer to example located in [examples/search_events_example.py](examples/search_events_example.py).

Update event for `eventId`:
```python
import os

import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, EventUpdate, ErrorResponse
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

event_id = 'event_id_example'
body = EventUpdate(linked_id='foo')
# body = EventUpdate(tags={'bar': 123})
# body = EventUpdate(suspect=True)
# body = EventUpdate(linked_id='foo', tags={'bar': 123}, suspect=False)

try:
    api_instance.update_event(event_id, body)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when calling FingerprintApi->update_event: {e}'
    print(message)
```

To learn more, refer to example located in [examples/update_event_example.py](examples/update_event_example.py).

## Sealed results

This SDK provides utility methods for decoding [sealed results](https://dev.fingerprint.com/docs/sealed-client-results).
```python
import base64
import os

from dotenv import load_dotenv

from fingerprint_server_sdk import unseal_event_response, DecryptionKey, DecryptionAlgorithm

load_dotenv()

sealed_result = base64.b64decode(os.environ["BASE64_SEALED_RESULT"])
key = base64.b64decode(os.environ["BASE64_KEY"])

try:
    event_response = unseal_event_response(sealed_result, [DecryptionKey(key, DecryptionAlgorithm['Aes256Gcm'])])
    print("\n\n\nEvent response: \n", event_response)
except Exception as e:
    print(f'Exception when calling unsealing events response: {e}\n')
    exit(1)

print("Unseal successful!")

exit(0)
```
To learn more, refer to example located in [examples/sealed_results_example.py](examples/sealed_results_example.py).

## Webhook signature validation

This SDK provides utility method for verifying the HMAC signature of the incoming webhook request.
```python
import os
from flask import Flask, request, jsonify
from fingerprint_server_sdk import WebhookValidation

app = Flask(__name__)

@app.route('/api/webhook', methods=['POST'])
def webhook_handler():
    try:
        # Retrieve the secret key from environment variables
        secret = os.getenv("WEBHOOK_SIGNATURE_SECRET")
        if not secret:
            return jsonify({"message": "Secret key is not configured."}), 400

        # Get the "fpjs-event-signature" header from the incoming request
        header = request.headers.get('fpjs-event-signature')
        if not header:
            return jsonify({"message": "Missing fpjs-event-signature header."}), 400

        # Read the raw body of the incoming request
        data = request.get_data()

        # Validate the webhook signature
        is_valid = WebhookValidation.is_valid_webhook_signature(header, data, secret)
        if not is_valid:
            return jsonify({"message": "Webhook signature is invalid."}), 403

        # Process the webhook data here
        return jsonify({"message": "Webhook received."}), 200

    except Exception as e:
        # Handle any unexpected errors
        return jsonify({"error": str(e)}), 500

if __name__ == '__main__':
    # Start the Flask application on the specified host and port
    app.run(host='0.0.0.0', port=5000)
```
To learn more, refer to example located in [examples/webhook_signature_example.py](examples/webhook_signature_example.py).

## Documentation for API Endpoints

All URIs are relative to *https://api.fpjs.io/v4*

Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
*FingerprintApi* | [**delete_visitor_data**](docs/FingerprintApi.md#delete_visitor_data) | **DELETE** /visitors/{visitor_id} | Delete a visitor ID
*FingerprintApi* | [**get_event**](docs/FingerprintApi.md#get_event) | **GET** /events/{event_id} | Get an event by event ID
*FingerprintApi* | [**search_events**](docs/FingerprintApi.md#search_events) | **GET** /events | Search events
*FingerprintApi* | [**update_event**](docs/FingerprintApi.md#update_event) | **PATCH** /events/{event_id} | Update an event


## Documentation For Models

 - [BotInfo](docs/BotInfo.md)
 - [BotInfoCategory](docs/BotInfoCategory.md)
 - [BotInfoConfidence](docs/BotInfoConfidence.md)
 - [BotInfoIdentity](docs/BotInfoIdentity.md)
 - [BotResult](docs/BotResult.md)
 - [BrowserDetails](docs/BrowserDetails.md)
 - [Canvas](docs/Canvas.md)
 - [Emoji](docs/Emoji.md)
 - [Error](docs/Error.md)
 - [ErrorCode](docs/ErrorCode.md)
 - [ErrorResponse](docs/ErrorResponse.md)
 - [Event](docs/Event.md)
 - [EventRuleAction](docs/EventRuleAction.md)
 - [EventRuleActionAllow](docs/EventRuleActionAllow.md)
 - [EventRuleActionBlock](docs/EventRuleActionBlock.md)
 - [EventSearch](docs/EventSearch.md)
 - [EventUpdate](docs/EventUpdate.md)
 - [FontPreferences](docs/FontPreferences.md)
 - [Geolocation](docs/Geolocation.md)
 - [GeolocationSubdivisionsInner](docs/GeolocationSubdivisionsInner.md)
 - [IPBlockList](docs/IPBlockList.md)
 - [IPInfo](docs/IPInfo.md)
 - [IPInfoV4](docs/IPInfoV4.md)
 - [IPInfoV6](docs/IPInfoV6.md)
 - [Identification](docs/Identification.md)
 - [IdentificationConfidence](docs/IdentificationConfidence.md)
 - [IncrementalIdentificationStatus](docs/IncrementalIdentificationStatus.md)
 - [Integration](docs/Integration.md)
 - [IntegrationSubintegration](docs/IntegrationSubintegration.md)
 - [LabelsInner](docs/LabelsInner.md)
 - [PluginsInner](docs/PluginsInner.md)
 - [PluginsInnerMimeTypesInner](docs/PluginsInnerMimeTypesInner.md)
 - [Proximity](docs/Proximity.md)
 - [ProxyConfidence](docs/ProxyConfidence.md)
 - [ProxyDetails](docs/ProxyDetails.md)
 - [RareDevicePercentileBucket](docs/RareDevicePercentileBucket.md)
 - [RawDeviceAttributes](docs/RawDeviceAttributes.md)
 - [RequestHeaderModifications](docs/RequestHeaderModifications.md)
 - [RuleActionHeaderField](docs/RuleActionHeaderField.md)
 - [RuleActionType](docs/RuleActionType.md)
 - [SDK](docs/SDK.md)
 - [SearchEventsBot](docs/SearchEventsBot.md)
 - [SearchEventsBotInfo](docs/SearchEventsBotInfo.md)
 - [SearchEventsEndParameter](docs/SearchEventsEndParameter.md)
 - [SearchEventsIncrementalIdentificationStatus](docs/SearchEventsIncrementalIdentificationStatus.md)
 - [SearchEventsRareDevicePercentileBucket](docs/SearchEventsRareDevicePercentileBucket.md)
 - [SearchEventsSdkPlatform](docs/SearchEventsSdkPlatform.md)
 - [SearchEventsStartParameter](docs/SearchEventsStartParameter.md)
 - [SearchEventsVpnConfidence](docs/SearchEventsVpnConfidence.md)
 - [SupplementaryIDHighRecall](docs/SupplementaryIDHighRecall.md)
 - [TamperingConfidence](docs/TamperingConfidence.md)
 - [TamperingDetails](docs/TamperingDetails.md)
 - [TouchSupport](docs/TouchSupport.md)
 - [Velocity](docs/Velocity.md)
 - [VelocityData](docs/VelocityData.md)
 - [VpnConfidence](docs/VpnConfidence.md)
 - [VpnMethods](docs/VpnMethods.md)
 - [WebGlBasics](docs/WebGlBasics.md)
 - [WebGlExtensions](docs/WebGlExtensions.md)


## Documentation for sealed results

- [SealedResults](docs/SealedResults.md)
- [DecryptionKey](docs/DecryptionKey.md)

## Support

To report problems, ask questions or provide feedback, please use [Issues](https://github.com/fingerprintjs/python-sdk/issues).
If you need private support, you can email us at [oss-support@fingerprint.com](mailto:oss-support@fingerprint.com).

## License

This project is licensed under the [MIT License](https://github.com/fingerprintjs/python-sdk/blob/main/LICENSE).
