FauxShield Python SDK

Official Python client for the FauxShield anti-counterfeiting platform API.

Requirements

• Python 3.9+

Installation

pip install fauxshield

Or from source:

pip install -e packages/python-sdk

Quick Start

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

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

Configuration

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

Pagination

All list methods return a PaginatedIterator that automatically fetches pages:

# 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

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:

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:

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

Development

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

# Run tests
pytest

# Type checking
mypy fauxshield/

# Linting
ruff check fauxshield/

License

MIT