Metadata-Version: 2.4
Name: BeddrokClient
Version: 2.0.3
Summary: Client for interacting with Beddrok
Author: Alexander Koutakis
License: GPL-3.0
Project-URL: Homepage, https://github.com/Koutakis/beddrokclient
Project-URL: Issues, https://github.com/Koutakis/beddrokclient/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.32.3
Requires-Dist: pandas<3.0.0,>=2.2.3
Requires-Dist: roskarl<3.0.0,>=2.3.4
Requires-Dist: polars>=1.36.1
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Dynamic: license-file

# BeddrokClient

Python client for the Beddrok encryption API with automatic token management and robust error handling.

## Installation
```bash
pip install BeddrokClient
```

## Development
Dependencies are declared in `pyproject.toml`. For a local editable install with the dev tools (pytest, ruff, pyright):
```bash
pip install -e ".[dev]"
ruff check . && ruff format --check .
pyright
pytest
```
These are the same checks the PR workflow runs.

## Quick Start
```python
from beddrok_client import BeddrokClient

client = BeddrokClient(
    user="username",
    password="password",
    api_url="https://api.beddrok.com"
)

# Encrypt/decrypt individual PINs
encrypted = client.encrypt_pins(["123456", "789012"])
decrypted = client.decrypt_pins(["enc_abc123", "enc_def456"])

# Validate PINs
validation = client.validate_pins(["123456", "789012"])
```

## DataFrame Operations

### Pandas
```python
import pandas as pd

df = pd.DataFrame({
    'id': [1, 2, 3],
    'pin': ['123456', '789012', '345678']
})

# Encrypt
encrypted_df = client.encrypt_pandas_dataframe(df, 'pin', batch_size=100)

# Decrypt
decrypted_df = client.decrypt_pandas_dataframe(encrypted_df, 'pin', batch_size=100)
```

### Polars
```python
import polars as pl

df = pl.DataFrame({
    'id': [1, 2, 3],
    'pin': ['123456', '789012', '345678']
})

# Encrypt
encrypted_df = client.encrypt_polars_dataframe(df, 'pin', batch_size=100)

# Decrypt
decrypted_df = client.decrypt_polars_dataframe(encrypted_df, 'pin', batch_size=100)
```

## Configuration
```python
client = BeddrokClient(
    user="username",
    password="password",
    api_url="https://api.beddrok.com",
    refresh_token_after_x_minutes=5,  # Token refresh buffer (default: 5)
    timeout=30,                        # Request timeout (default: 30)
    max_retries=3,                     # Retry attempts (default: 3)
    backoff_base=2.0,                  # Exponential backoff (default: 2.0)
    token_endpoint="auth/token",       # Relative to api_url (default shown)
    encrypt_endpoint="v2/encrypt",
    decrypt_endpoint="v2/decrypt",
    validate_endpoint="v2/validate",
)
```

### Token Management

- Automatic token refresh before expiration
- Thread-safe token operations
- JWT payload parsing for expiration tracking

### Network Resilience

- Exponential backoff retry: `backoff_base ^ (attempt + 1)`
- Handles 503 database errors
- Connection/timeout error recovery

## License

GPL-3.0

## Links

- [GitHub](https://github.com/Koutakis/beddrokclient)
- [PyPI](https://pypi.org/project/BeddrokClient/)
