Metadata-Version: 2.4
Name: fraudshield-sdk
Version: 0.1.0
Summary: Official Python SDK for the FraudShield fraud-detection API
Author-email: Elijah Samuel <iamelijahsamz@gmail.com>
Maintainer-email: Elijah Samuel <iamelijahsamz@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ulaitorcodes/fraudshield-python-sdk
Project-URL: Repository, https://github.com/ulaitorcodes/fraudshield-python-sdk.git
Project-URL: Bug Tracker, https://github.com/ulaitorcodes/fraudshield-python-sdk/issues
Keywords: fraud,fraud-detection,risk,payments,sdk,api
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests<3,>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: requests-mock>=1.11; extra == "dev"

# fraudshield

Python SDK for the FraudShield fraud-detection API. Covers transaction
analysis only — analytics and API key management are handled on the
dashboard, not through this SDK.

## Install

```bash
pip install fraudshield-sdk
# for local dev:
pip install -e ".[dev]"
```

## Usage

```python
from fraudshield import Client

client = Client(
    api_key="fs_test_...",
    base_url="https://your-api-host/api/v1",
)

result = client.transactions.analyze(
    user_id="U123",
    amount=50000,
    currency="NGN",
    device_id="dev_1",
)
if result.is_blocked:
    raise PaymentError("Declined")

print(result.risk_score, result.decision, result.triggered_rules)
```

Extra keyword arguments to `analyze(...)` are passed straight through as
additional JSON fields, so new API parameters work without an SDK update.

### Auth

`api_key` is sent as an `Api-Key` header on every request. Alternatively, set
`FRAUDSHIELD_API_KEY` as an environment variable and omit `api_key` when
constructing `Client`.

### Errors

All errors inherit from `fraudshield.FraudShieldError`
(`AuthenticationError`, `ValidationError`, `RateLimitError`, `APIError`,
`APIConnectionError`, ...). Connection errors and `429`/`5xx` responses are
automatically retried with exponential backoff (`max_retries=2` by default).

### Idempotency

Pass `idempotency_key=` to `transactions.analyze(...)` to safely retry the
same request without double-processing server-side (if supported by the API).

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
```
