Metadata-Version: 2.5
Name: fauxshield
Version: 0.1.0
Summary: Official Python SDK for the FauxShield anti-counterfeiting platform
Project-URL: Homepage, https://fauxshield.com
Project-URL: Documentation, https://docs.fauxshield.com
Project-URL: Repository, https://github.com/fauxshield/fauxshield-python
Author-email: FauxShield <support@fauxshield.com>
License-Expression: MIT
Keywords: anti-counterfeiting,fauxshield,fraud-detection,product-authentication
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1.0.0,>=0.25.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# FauxShield Python SDK

Official Python client for the [FauxShield](https://fauxshield.com) anti-counterfeiting platform API.

## Requirements

- Python 3.9+

## Installation

```bash
pip install fauxshield
```

Or from source:

```bash
pip install -e packages/python-sdk
```

## Quick Start

```python
from fauxshield import FauxShieldClient

client = FauxShieldClient(api_key="fs_live_your_api_key")

# List products with auto-pagination
for product in client.products.list():
    print(product["name"])

# Create a product
product = client.products.create(
    name="Premium Widget",
    sku="WDG-001",
    category="electronics",
)

# Create a batch
batch = client.batches.create(
    product_id=product["id"],
    quantity=1000,
)

# Generate identities (QR tokens)
identities = client.identities.generate(
    batch_id=batch["id"],
    quantity=100,
)

# Check fraud alerts
for alert in client.fraud_alerts.list(status="open"):
    print(f"Alert: {alert['type']} - {alert['description']}")
```

## Context Manager

```python
with FauxShieldClient(api_key="fs_live_...") as client:
    products = client.products.list().to_list()
```

## Configuration

```python
client = FauxShieldClient(
    api_key="fs_live_...",
    base_url="https://fauxshield.vercel.app/api/v1",  # default
    timeout=30.0,       # request timeout in seconds
    max_retries=3,      # retry attempts for 5xx/network errors
)
```

## Resources

| Resource | Methods |
|----------|---------|
| `client.products` | `list`, `get`, `create`, `update`, `delete` |
| `client.batches` | `list`, `get`, `create`, `update`, `recall` |
| `client.identities` | `list`, `generate` |
| `client.fraud_alerts` | `list`, `get`, `resolve` |
| `client.events` | `list` |
| `client.webhooks` | `list`, `create`, `update`, `delete`, `rotate_secret`, `test`, `list_deliveries` |
| `client.api_keys` | `list`, `create`, `revoke` |

## Pagination

All list methods return a `PaginatedIterator` that automatically fetches pages:

```python
# Iterate one by one (fetches pages lazily)
for product in client.products.list(page_size=50):
    process(product)

# Or collect all into a list
all_products = client.products.list().to_list()
```

## Error Handling

```python
from fauxshield import (
    FauxShieldError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

try:
    product = client.products.get("nonexistent")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Invalid request: {e.fields}")
except AuthenticationError:
    print("Check your API key")
except FauxShieldError as e:
    print(f"API error [{e.status_code}]: {e.message}")
```

## Webhook Verification

Verify incoming webhook signatures in your endpoint handler:

```python
from fauxshield import verify_webhook_signature, WebhookVerificationError

try:
    verify_webhook_signature(
        payload=request.body,
        signature=request.headers["X-FauxShield-Signature"],
        secret="whsec_your_webhook_secret",
        tolerance=300,  # 5 minute tolerance (default)
    )
    # Signature valid — process the event
except WebhookVerificationError as e:
    # Reject the request
    print(f"Invalid webhook: {e}")
```

## Rate Limiting

The SDK automatically retries on rate limit (429) responses. You can also inspect rate limit info:

```python
client.products.list()
info = client.last_rate_limit
if info:
    print(f"Remaining: {info['remaining']}/{info['limit']}")
```

## Development

```bash
# Install dev dependencies
pip install -e "packages/python-sdk[dev]"

# Run tests
pytest

# Type checking
mypy fauxshield/

# Linting
ruff check fauxshield/
```

## License

MIT
