Metadata-Version: 2.4
Name: bigshield
Version: 1.0.0
Summary: Multi-signal email validation SDK. Detect fake signups, burner emails, and disposable domains.
Project-URL: Homepage, https://bigshield.app
Project-URL: Documentation, https://bigshield.app/docs
Project-URL: Repository, https://github.com/bigshield/bigshield-python
Author-email: BigShield <support@bigshield.app>
License-Expression: MIT
Keywords: bigshield,detection,email,fraud,validation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# BigShield Python SDK

Multi-signal email validation SDK. Detect fake signups, burner emails, and disposable domains.

## Install

```bash
pip install bigshield
```

## Quick Start

```python
from bigshield import BigShield

client = BigShield("ev_live_your_api_key")

# Validate a single email
result = client.validate("user@example.com")
print(result.risk_score)    # 22
print(result.is_valid)      # True
print(result.recommendation)  # "accept"

# Check individual signals
for signal in result.signals:
    print(f"{signal.name}: {signal.score_impact} (confidence: {signal.confidence})")
```

## Async Support

```python
from bigshield import AsyncBigShield

client = AsyncBigShield("ev_live_your_api_key")
result = await client.validate("user@example.com")
```

## Validate with Context

Pass additional context for stronger fraud detection:

```python
result = client.validate(
    "user@example.com",
    wait=True,          # Wait for Tier 2 signals
    ip="203.0.113.1",   # Client IP
    fingerprint="fp_abc123",
    user_agent="Mozilla/5.0 ...",
)
```

## Batch Validation

```python
result = client.batch_validate([
    "alice@example.com",
    "bob@tempmail.com",
    "carol@gmail.com",
])

for r in result.results:
    print(f"{r.email}: {r.risk_score} ({r.recommendation})")
```

## Error Handling

```python
from bigshield import BigShield, AuthError, RateLimitError

client = BigShield("ev_live_your_api_key")

try:
    result = client.validate("user@example.com")
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
```

## Configuration

```python
client = BigShield(
    "ev_live_your_api_key",
    base_url="https://bigshield.app",  # Custom base URL
    timeout=15.0,                       # Request timeout in seconds
    retries=3,                          # Number of retries on server errors
)
```

## Documentation

Full API docs at [bigshield.app/docs](https://bigshield.app/docs).
