Metadata-Version: 2.4
Name: skalaio
Version: 0.2.0
Summary: Python SDK for the Skala fraud detection API
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# Skala Python SDK

Python SDK for the Skala fraud detection API.

Requires Python 3.11+.

## Install

```bash
pip install skalaio
```

## Quick Start

```python
from skala import Skala, SkalaOptions, ScoreRequest

skala = Skala(SkalaOptions(api_key="sk_live_..."))

result = skala.score(ScoreRequest(
    event_type="signup",
    ip=req.ip,
    email=body.email,
    user_agent=req.headers["user-agent"],
))

if result.decision == "block":
    return {"error": "Request blocked"}, 403

if result.decision == "step_up":
    return {"requires_verification": True}, 200
```

## Report an Outcome

Feed back fraud signals to improve future scoring:

```python
from skala import OutcomeRequest

skala.outcome(OutcomeRequest(
    request_id=result.request_id,
    outcome="confirmed_fraud",
))
```

## Timeout Fallback

`score()` auto-allows when the API is unreachable (timeout or network failure), so scoring does not block user traffic.

HTTP API responses (for example 4xx/5xx) still raise errors.

```python
result = skala.score(...)

if hasattr(result, "fallback") and result.fallback:
    # request was auto-allowed by SDK fallback
    # result.reason_codes is SDK_TIMEOUT_FALLBACK or SDK_NETWORK_FALLBACK
```

## Error Handling

Use structured SDK errors for predictable handling:

```python
from skala import (
    SkalaApiError,
    SkalaNetworkError,
    SkalaTimeoutError,
)

try:
    skala.outcome(OutcomeRequest(request_id="req_123", outcome="confirmed_fraud"))
except SkalaTimeoutError:
    # request timed out
except SkalaNetworkError:
    # API unreachable (DNS/TLS/connectivity)
except SkalaApiError as e:
    # API returned non-2xx
    print(e.status, e.body, e.request_id)
```

## Configuration

```python
from skala import Skala, SkalaOptions

skala = Skala(SkalaOptions(
    api_key="sk_live_...",
    base_url="https://apiskala.varityweb.com",  # default
    timeout_ms=5000,                             # default
    retries=2,                                   # default, only retries 5xx
))
```

## License

MIT
