Metadata-Version: 2.4
Name: deflect
Version: 0.1.1
Summary: Official Deflect Protection SDK for Python
Author: Deflect
License: MIT
Project-URL: Homepage, https://docs.deflect.bot/
Project-URL: Source, https://github.com/deflectbot/deflect-python
Project-URL: Issues, https://github.com/deflectbot/deflect-python/issues
Keywords: deflect,bot,security,antibot
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx<0.28.0,>=0.27.0
Provides-Extra: async
Requires-Dist: httpx[http2]<0.28.0,>=0.27.0; extra == "async"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"

# Deflect Python SDK

Early Python SDK for the Deflect Bot Protection API (experimental).

## Installation

Install PyPi package:
```bash
pip install deflect
```

## Quick Start (Sync)
```python
from deflect import Deflect, DeflectOptions, VerdictRequest

client = Deflect(DeflectOptions(api_key="YOUR_KEY", action_id="YOUR_ACTION"))
verdict = client.get_verdict(VerdictRequest(
    token=user_session_token,
    # Optional Identity Enrichment
    id="user_123",  # Required for access control
    email="user@example.com",  # Optional email
    phone_number="+14155552671"  # Optional phone number
))
if verdict.get("verdict", {}).get("can_pass"):
    # allow
    ...
else:
    # block
    ...
```

## Quick Start (Async)
```python
import asyncio
from deflect import AsyncDeflect, DeflectOptions, VerdictRequest

async def main():
    client = AsyncDeflect(DeflectOptions(api_key="YOUR_KEY", action_id="YOUR_ACTION"))
    verdict = await client.get_verdict(VerdictRequest(token=user_session_token))
    print(verdict)

asyncio.run(main())
```

## Intelligence APIs

### Email Intelligence
```python
from deflect import Deflect, DeflectOptions

client = Deflect(DeflectOptions(api_key="YOUR_KEY", action_id="YOUR_ACTION"))
result = client.email_intelligence("user@example.com")

if result.get("success"):
    data = result.get("data", {})
    print(f"Valid: {data.get('is_valid')}")
    print(f"Trusted: {data.get('is_trusted')}")
    print(f"Trust Score: {data.get('trust_score')}")
    print(f"Has Aliasing: {data.get('has_aliasing')}")
    print(f"Normalized: {data.get('normalized_email')}")
```

### Phone Intelligence
```python
from deflect import Deflect, DeflectOptions

client = Deflect(DeflectOptions(api_key="YOUR_KEY", action_id="YOUR_ACTION"))
result = client.phone_intelligence("+14155552671")

if result.get("success"):
    data = result.get("data", {})
    print(f"Valid: {data.get('is_valid')}")
    print(f"Country: {data.get('country_name')}")
    print(f"Carrier: {data.get('carrier')}")
    print(f"Line Type: {data.get('line_type')}")
    print(f"Risk Score: {data.get('risk_score')}")
    print(f"Is Spam: {data.get('is_spam')}")
```

### IP Intelligence
```python
from deflect import Deflect, DeflectOptions

client = Deflect(DeflectOptions(api_key="YOUR_KEY", action_id="YOUR_ACTION"))
result = client.ip_intelligence("8.8.8.8")

if result.get("success"):
    data = result.get("data", {})
    print(f"Is VPN: {data.get('is_vpn')}")
    print(f"Is Proxy: {data.get('is_datacenter_proxy')}")
    print(f"Is Threat: {data.get('is_threat')}")
    print(f"Location: {data.get('city')}, {data.get('country')}")
    print(f"ISP: {data.get('isp')}")
```

## Configuration
`DeflectOptions`:
- `api_key` (str, required)
- `action_id` (str, required)
- `base_url` (str, default `https://api.deflect.bot`)
- `timeout` (float seconds, default 4.0)
- `max_retries` (int, default 2)
- `client` / `async_client` (inject custom `httpx` client instances)

## Errors
Raises `DeflectError` with attributes:
- `status` (int | None)
- `body` (parsed JSON or None)

## Testing
```bash
pytest -q
```

## License
MIT
