skalaio 0.2.0__tar.gz

skalaio-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/

skalaio-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

skalaio-0.2.0/PKG-INFO

@@ -0,0 +1,107 @@
+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

skalaio-0.2.0/README.md

@@ -0,0 +1,98 @@
+# 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

skalaio-0.2.0/publish.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Exit immediately if any command fails
+set -e
+
+# Change directory to the script's directory
+cd "$(dirname "$0")"
+
+# Load environment variables from .env
+if [ -f .env ]; then
+  echo "Loading credentials from .env..."
+  export $(grep -v '^#' .env | xargs)
+else
+  echo "Error: .env file not found. Create one with TWINE_USERNAME and TWINE_PASSWORD."
+  exit 1
+fi
+
+# Ensure Twine environment variables are set and map them to UV variables
+if [ -z "$TWINE_PASSWORD" ]; then
+  echo "Error: TWINE_PASSWORD is not set in .env."
+  exit 1
+fi
+
+export UV_PUBLISH_TOKEN="$TWINE_PASSWORD"
+
+# 1. Clean previous build artifacts
+echo "Cleaning old dist/ and build/ directories..."
+rm -rf dist/ build/ *.egg-info/
+
+# 2. Build the package using uv
+echo "Building the Python package with uv..."
+uv build
+
+# 3. Upload to PyPI using uv
+echo "Uploading package to PyPI with uv..."
+uv publish
+
+echo "Success! Package version $(grep -m 1 'version =' pyproject.toml | cut -d '"' -f 2) published successfully."

skalaio-0.2.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "skalaio"
+version = "0.2.0"
+description = "Python SDK for the Skala fraud detection API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["skala"]

skalaio-0.2.0/skala/__init__.py

@@ -0,0 +1,38 @@
+from skala._client import Skala, DEFAULT_BASE_URL
+from skala._errors import (
+    SkalaApiError,
+    SkalaConfigError,
+    SkalaError,
+    SkalaNetworkError,
+    SkalaTimeoutError,
+)
+from skala._types import (
+    OutcomeRequest,
+    OutcomeResponse,
+    ScoreFallbackResponse,
+    ScoreRequest,
+    ScoreResponse,
+    SkalaDecision,
+    SkalaEventType,
+    SkalaOptions,
+    SkalaOutcome,
+)
+
+__all__ = [
+    "Skala",
+    "DEFAULT_BASE_URL",
+    "SkalaApiError",
+    "SkalaConfigError",
+    "SkalaError",
+    "SkalaNetworkError",
+    "SkalaTimeoutError",
+    "OutcomeRequest",
+    "OutcomeResponse",
+    "ScoreFallbackResponse",
+    "ScoreRequest",
+    "ScoreResponse",
+    "SkalaDecision",
+    "SkalaEventType",
+    "SkalaOptions",
+    "SkalaOutcome",
+]

skalaio-0.2.0/skala/_client.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import hashlib
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from skala._errors import (
+    SkalaApiError,
+    SkalaConfigError,
+    SkalaNetworkError,
+    SkalaTimeoutError,
+)
+from skala._types import (
+    OutcomeRequest,
+    OutcomeResponse,
+    ScoreFallbackResponse,
+    ScoreRequest,
+    ScoreResponse,
+    SkalaOptions,
+)
+
+DEFAULT_BASE_URL = "https://apiskala.varityweb.com"
+_DEFAULT_RETRIES = 2
+_DEFAULT_TIMEOUT_MS = 5_000
+
+
+def _sha256_hex(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+class Skala:
+    def __init__(self, options: SkalaOptions) -> None:
+        if not options.api_key or not options.api_key.strip():
+            raise SkalaConfigError("Skala apiKey is required")
+        if options.retries is not None and options.retries < 0:
+            raise SkalaConfigError(
+                "Skala retries must be greater than or equal to 0"
+            )
+        if options.timeout_ms is not None and options.timeout_ms <= 0:
+            raise SkalaConfigError("Skala timeoutMs must be greater than 0")
+
+        self._api_key = options.api_key
+        self._base_url = (options.base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._retries = (
+            options.retries if options.retries is not None else _DEFAULT_RETRIES
+        )
+        self._timeout = (
+            (options.timeout_ms or _DEFAULT_TIMEOUT_MS) / 1000
+        )
+
+    def _post_json(self, path: str, payload: dict[str, Any]) -> Any:
+        request_id = str(uuid.uuid4())
+        attempt = 0
+
+        while True:
+            try:
+                response = httpx.post(
+                    f"{self._base_url}{path}",
+                    json=payload,
+                    headers={
+                        "Authorization": f"Bearer {self._api_key}",
+                        "Accept": "application/json",
+                        "Content-Type": "application/json",
+                        "X-Request-ID": request_id,
+                    },
+                    timeout=self._timeout,
+                )
+            except httpx.TimeoutException as exc:
+                raise SkalaTimeoutError(
+                    int(self._timeout * 1000), request_id=request_id, cause=exc
+                ) from exc
+            except Exception as exc:
+                raise SkalaNetworkError(
+                    request_id=request_id, cause=exc
+                ) from exc
+
+            if 500 <= response.status_code < 600 and attempt < self._retries:
+                attempt += 1
+                time.sleep(0.05 * attempt)
+                continue
+
+            if response.status_code < 200 or response.status_code >= 300:
+                body: Any = response.text
+                if body:
+                    try:
+                        body = response.json()
+                    except Exception:
+                        pass
+                raise SkalaApiError(
+                    response.status_code, body, request_id=request_id
+                )
+
+            return response.json()
+
+    def score(self, payload: ScoreRequest) -> ScoreResponse | ScoreFallbackResponse:
+        started_at = time.monotonic()
+
+        try:
+            data = payload.to_dict()
+            email = data.pop("email")
+            data["email_hash"] = _sha256_hex(email.strip().lower())
+
+            email_domain = None
+            if email and "@" in email:
+                email_domain = email.split("@")[-1].strip().lower()
+
+            if email_domain:
+                if "metadata" not in data or data["metadata"] is None:
+                    data["metadata"] = {}
+                data["metadata"]["email_domain"] = email_domain
+
+            result = self._post_json("/v1/score", data)
+            return ScoreResponse.from_dict(result)
+        except SkalaTimeoutError as exc:
+            elapsed_ms = int((time.monotonic() - started_at) * 1000)
+            return ScoreFallbackResponse(
+                request_id=exc.request_id or str(uuid.uuid4()),
+                risk_score=0,
+                decision="allow",
+                reason_codes=["SDK_TIMEOUT_FALLBACK"],
+                latency_ms=max(0, round(elapsed_ms)),
+                fallback=True,
+            )
+        except SkalaNetworkError as exc:
+            elapsed_ms = int((time.monotonic() - started_at) * 1000)
+            return ScoreFallbackResponse(
+                request_id=exc.request_id or str(uuid.uuid4()),
+                risk_score=0,
+                decision="allow",
+                reason_codes=["SDK_NETWORK_FALLBACK"],
+                latency_ms=max(0, round(elapsed_ms)),
+                fallback=True,
+            )
+
+    def outcome(self, payload: OutcomeRequest) -> OutcomeResponse:
+        result = self._post_json("/v1/outcome", payload.to_dict())
+        return OutcomeResponse.from_dict(result)

skalaio-0.2.0/skala/_errors.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class SkalaError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        request_id: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.request_id = request_id
+        if cause is not None:
+            self.__cause__ = cause
+
+
+class SkalaConfigError(SkalaError):
+    pass
+
+
+class SkalaTimeoutError(SkalaError):
+    def __init__(
+        self,
+        timeout_ms: int,
+        request_id: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(
+            f"Skala request timed out after {timeout_ms}ms",
+            request_id=request_id,
+            cause=cause,
+        )
+        self.timeout_ms = timeout_ms
+
+
+class SkalaNetworkError(SkalaError):
+    def __init__(
+        self,
+        request_id: str | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(
+            "Skala request failed because the API is unreachable",
+            request_id=request_id,
+            cause=cause,
+        )
+
+
+class SkalaApiError(SkalaError):
+    def __init__(
+        self,
+        status: int,
+        body: Any,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(
+            f"Skala request failed with status {status}",
+            request_id=request_id,
+        )
+        self.status = status
+        self.body = body

skalaio-0.2.0/skala/_types.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+SkalaEventType = Literal[
+    "signup", "login", "trial_start", "checkout", "api_key_create"
+]
+SkalaDecision = Literal["allow", "step_up", "block"]
+SkalaOutcome = Literal["confirmed_fraud", "false_positive", "converted"]
+
+
+@dataclass
+class ScoreRequest:
+    event_type: SkalaEventType
+    ip: str
+    email: str
+    device_id: str | None = None
+    user_agent: str | None = None
+    form_fill_ms: int | None = None
+    metadata: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "event_type": self.event_type,
+            "ip": self.ip,
+            "email": self.email,
+        }
+        if self.device_id is not None:
+            d["device_id"] = self.device_id
+        if self.user_agent is not None:
+            d["user_agent"] = self.user_agent
+        if self.form_fill_ms is not None:
+            d["form_fill_ms"] = self.form_fill_ms
+        if self.metadata is not None:
+            d["metadata"] = self.metadata
+        return d
+
+
+@dataclass
+class ScoreResponse:
+    request_id: str
+    risk_score: float
+    decision: SkalaDecision
+    reason_codes: list[str]
+    latency_ms: int
+    signal_breakdown: dict[str, float] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ScoreResponse:
+        return cls(
+            request_id=data["request_id"],
+            risk_score=data["risk_score"],
+            decision=data["decision"],
+            reason_codes=data["reason_codes"],
+            latency_ms=data["latency_ms"],
+            signal_breakdown=data.get("signal_breakdown") or {},
+        )
+
+
+@dataclass
+class ScoreFallbackResponse(ScoreResponse):
+    fallback: bool = True
+
+
+@dataclass
+class OutcomeRequest:
+    request_id: str
+    outcome: SkalaOutcome
+
+    def to_dict(self) -> dict[str, str]:
+        return {"request_id": self.request_id, "outcome": self.outcome}
+
+
+@dataclass
+class OutcomeResponse:
+    ok: bool
+    identifiers_updated: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> OutcomeResponse:
+        return cls(ok=data["ok"], identifiers_updated=data["identifiers_updated"])
+
+
+@dataclass
+class SkalaOptions:
+    api_key: str
+    base_url: str | None = None
+    retries: int | None = None
+    timeout_ms: int | None = None

skalaio-0.2.0/tests/test_config.py

@@ -0,0 +1,88 @@
+from unittest.mock import patch, MagicMock
+import pytest
+from skala import Skala, SkalaOptions, ScoreRequest
+from skala._client import DEFAULT_BASE_URL
+
+
+def ok_score_response():
+    resp = MagicMock()
+    resp.status_code = 200
+    resp.json.return_value = {
+        "request_id": "req_1",
+        "risk_score": 0,
+        "decision": "allow",
+        "reason_codes": [],
+        "latency_ms": 5,
+    }
+    return resp
+
+
+def test_defaults_to_default_base_url():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = ok_score_response()
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        client.score(ScoreRequest(event_type="signup", ip="1.2.3.4", email="a@b.com"))
+        assert mock_post.call_count == 1
+        url = mock_post.call_args[0][0]
+        assert url == f"{DEFAULT_BASE_URL}/v1/score"
+
+
+def test_strips_trailing_slashes_from_base_url():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = ok_score_response()
+        client = Skala(SkalaOptions(api_key="sk_test", base_url="https://api.test///"))
+        client.score(ScoreRequest(event_type="signup", ip="1.2.3.4", email="a@b.com"))
+        url = mock_post.call_args[0][0]
+        assert url == "https://api.test/v1/score"
+
+
+def test_sets_authorization_header():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = ok_score_response()
+        client = Skala(SkalaOptions(api_key="sk_my_key_123"))
+        client.score(ScoreRequest(event_type="checkout", ip="10.0.0.1", email="x@y.com"))
+        headers = mock_post.call_args[1]["headers"]
+        assert headers["Authorization"] == "Bearer sk_my_key_123"
+
+
+def test_sends_json_content_type():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = ok_score_response()
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        client.score(ScoreRequest(event_type="login", ip="10.0.0.1", email="a@b.com"))
+        headers = mock_post.call_args[1]["headers"]
+        assert headers["Content-Type"] == "application/json"
+
+
+def test_sends_accept_header():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = ok_score_response()
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        client.score(ScoreRequest(event_type="login", ip="10.0.0.1", email="a@b.com"))
+        headers = mock_post.call_args[1]["headers"]
+        assert headers["Accept"] == "application/json"
+
+
+def test_sends_request_id_as_uuid():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = ok_score_response()
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        client.score(ScoreRequest(event_type="login", ip="10.0.0.1", email="a@b.com"))
+        headers = mock_post.call_args[1]["headers"]
+        import re
+        assert re.match(r"^[0-9a-f-]{36}$", headers["X-Request-ID"])
+
+
+def test_throws_when_api_key_is_missing():
+    with pytest.raises(Exception, match="apiKey is required"):
+        Skala(SkalaOptions(api_key=""))
+
+
+def test_throws_when_retries_is_negative():
+    with pytest.raises(Exception, match="retries must be greater"):
+        Skala(SkalaOptions(api_key="sk_test", retries=-1))
+
+
+def test_throws_when_timeout_ms_is_not_positive():
+    with pytest.raises(Exception, match="timeoutMs must be greater"):
+        Skala(SkalaOptions(api_key="sk_test", timeout_ms=0))

skalaio-0.2.0/tests/test_errors.py

@@ -0,0 +1,87 @@
+from unittest.mock import patch, MagicMock
+import pytest
+from skala import Skala, SkalaOptions, ScoreRequest, OutcomeRequest
+from skala._errors import SkalaApiError
+
+
+SCORE_REQ = ScoreRequest(event_type="signup", ip="1.2.3.4", email="err@test.com")
+
+
+def make_error_response(status, body=None):
+    resp = MagicMock()
+    resp.status_code = status
+    if body is None:
+        body = {"error": "unauthorized"}
+    resp.json.return_value = body
+    resp.text = str(body)
+    return resp
+
+
+def test_throws_on_401_without_retrying():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_error_response(401)
+        client = Skala(SkalaOptions(api_key="bad_key", retries=2))
+        with pytest.raises(SkalaApiError) as exc_info:
+            client.score(SCORE_REQ)
+        assert exc_info.value.status == 401
+        assert exc_info.value.body == {"error": "unauthorized"}
+        assert mock_post.call_count == 1
+
+
+def test_throws_on_422_without_retrying():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_error_response(422, {"error": "validation failed"})
+        client = Skala(SkalaOptions(api_key="sk_test", retries=2))
+        with pytest.raises(SkalaApiError):
+            client.score(SCORE_REQ)
+        assert mock_post.call_count == 1
+
+
+def test_throws_on_403_without_retrying():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_error_response(403, {"error": "forbidden"})
+        client = Skala(SkalaOptions(api_key="sk_test", retries=2))
+        with pytest.raises(SkalaApiError):
+            client.score(SCORE_REQ)
+        assert mock_post.call_count == 1
+
+
+def test_does_not_retry_on_429():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_error_response(429, {"error": "rate_limited"})
+        client = Skala(SkalaOptions(api_key="sk_test", retries=3))
+        with pytest.raises(SkalaApiError) as exc_info:
+            client.score(SCORE_REQ)
+        assert exc_info.value.status == 429
+        assert exc_info.value.body == {"error": "rate_limited"}
+        assert mock_post.call_count == 1
+
+
+def test_exhausts_retries_on_500():
+    with patch("skala._client.httpx.post") as mock_post:
+        resp = MagicMock()
+        resp.status_code = 500
+        resp.text = "internal error"
+        resp.json.return_value = "internal error"
+        mock_post.return_value = resp
+        client = Skala(SkalaOptions(api_key="sk_test", retries=2))
+        with pytest.raises(SkalaApiError):
+            client.score(SCORE_REQ)
+        assert mock_post.call_count == 3
+
+
+def test_does_not_retry_when_retries_is_0():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_error_response(502, "error")
+        client = Skala(SkalaOptions(api_key="sk_test", retries=0))
+        with pytest.raises(SkalaApiError):
+            client.score(SCORE_REQ)
+        assert mock_post.call_count == 1
+
+
+def test_throws_on_outcome_4xx_errors():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_error_response(404, {"error": "not found"})
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        with pytest.raises(SkalaApiError):
+            client.outcome(OutcomeRequest(request_id="req_bad", outcome="confirmed_fraud"))

skalaio-0.2.0/tests/test_outcome.py

@@ -0,0 +1,76 @@
+from unittest.mock import patch, MagicMock
+import pytest
+from skala import Skala, SkalaOptions, OutcomeRequest
+from skala._errors import SkalaTimeoutError, SkalaNetworkError
+
+
+def make_outcome_response(ok=True, identifiers_updated=4):
+    resp = MagicMock()
+    resp.status_code = 200
+    resp.json.return_value = {
+        "ok": ok,
+        "identifiers_updated": identifiers_updated,
+    }
+    return resp
+
+
+def test_reports_confirmed_fraud_outcome():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_outcome_response()
+        client = Skala(SkalaOptions(api_key="sk_test_123"))
+        result = client.outcome(
+            OutcomeRequest(request_id="req_123", outcome="confirmed_fraud")
+        )
+
+        assert result.ok is True
+        assert result.identifiers_updated == 4
+
+        url = mock_post.call_args[0][0]
+        assert url == "https://apiskala.varityweb.com/v1/outcome"
+
+        body = mock_post.call_args[1]["json"]
+        assert body == {"request_id": "req_123", "outcome": "confirmed_fraud"}
+
+
+def test_reports_false_positive_outcome():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_outcome_response(identifiers_updated=1)
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        result = client.outcome(
+            OutcomeRequest(request_id="req_456", outcome="false_positive")
+        )
+
+        assert result.ok is True
+        body = mock_post.call_args[1]["json"]
+        assert body["outcome"] == "false_positive"
+
+
+def test_reports_converted_outcome():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_outcome_response(identifiers_updated=2)
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        result = client.outcome(
+            OutcomeRequest(request_id="req_789", outcome="converted")
+        )
+
+        assert result.identifiers_updated == 2
+
+
+def test_throws_on_timeout_without_fallback():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.side_effect = __import__("httpx").TimeoutException("timeout")
+        client = Skala(SkalaOptions(api_key="sk_test", timeout_ms=50))
+        with pytest.raises(SkalaTimeoutError):
+            client.outcome(
+                OutcomeRequest(request_id="req_1", outcome="confirmed_fraud")
+            )
+
+
+def test_throws_network_error_when_api_unreachable():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.side_effect = Exception("fetch failed")
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        with pytest.raises(SkalaNetworkError):
+            client.outcome(
+                OutcomeRequest(request_id="req_2", outcome="converted")
+            )

skalaio-0.2.0/tests/test_score.py

@@ -0,0 +1,152 @@
+from unittest.mock import patch, MagicMock
+import pytest
+from skala import Skala, SkalaOptions, ScoreRequest, ScoreFallbackResponse
+from skala._client import _sha256_hex
+
+
+def make_score_response(
+    request_id="req_123",
+    risk_score=12,
+    decision="allow",
+    reason_codes=None,
+    latency_ms=9,
+):
+    resp = MagicMock()
+    resp.status_code = 200
+    resp.json.return_value = {
+        "request_id": request_id,
+        "risk_score": risk_score,
+        "decision": decision,
+        "reason_codes": reason_codes or [],
+        "latency_ms": latency_ms,
+    }
+    return resp
+
+
+def test_sends_score_request_and_returns_response():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_score_response()
+        client = Skala(SkalaOptions(api_key="sk_test_123"))
+        result = client.score(
+            ScoreRequest(
+                event_type="signup",
+                ip="203.0.113.9",
+                email="user@example.com",
+                user_agent="Mozilla/5.0",
+            )
+        )
+
+        assert result.request_id == "req_123"
+        assert result.risk_score == 12
+        assert result.decision == "allow"
+        assert result.reason_codes == []
+        assert result.latency_ms == 9
+
+        call_args = mock_post.call_args
+        url = call_args[0][0]
+        assert url == "https://apiskala.varityweb.com/v1/score"
+        assert call_args[1]["headers"]["Authorization"] == "Bearer sk_test_123"
+
+        body = call_args[1]["json"]
+        assert body["event_type"] == "signup"
+        assert body["ip"] == "203.0.113.9"
+        assert body["email_hash"] == _sha256_hex("user@example.com")
+        assert body["user_agent"] == "Mozilla/5.0"
+        assert "email" not in body
+
+
+def test_uses_custom_base_url():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_score_response(request_id="req_1")
+        client = Skala(SkalaOptions(api_key="sk_test", base_url="https://custom.api.test"))
+        client.score(ScoreRequest(event_type="login", ip="10.0.0.1", email="test@test.com"))
+        url = mock_post.call_args[0][0]
+        assert url == "https://custom.api.test/v1/score"
+
+
+def test_passes_optional_fields():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_score_response(
+            request_id="req_2",
+            risk_score=30,
+            decision="step_up",
+            reason_codes=["NEW_DEVICE"],
+        )
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        result = client.score(
+            ScoreRequest(
+                event_type="trial_start",
+                ip="10.0.0.2",
+                email="trial@example.com",
+                device_id="device_abc",
+                form_fill_ms=1200,
+                metadata={"plan": "pro"},
+            )
+        )
+
+        assert result.decision == "step_up"
+        assert "NEW_DEVICE" in result.reason_codes
+
+        body = mock_post.call_args[1]["json"]
+        assert body["device_id"] == "device_abc"
+        assert body["form_fill_ms"] == 1200
+        assert body["metadata"] == {"plan": "pro"}
+
+
+def test_retries_5xx_and_succeeds():
+    error_resp = MagicMock()
+    error_resp.status_code = 503
+    error_resp.text = '{"error": "temporary"}'
+    error_resp.json.return_value = {"error": "temporary"}
+
+    ok_resp = make_score_response(request_id="req_456", risk_score=55, decision="step_up", reason_codes=["HIGH_IP_VELOCITY"])
+
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.side_effect = [error_resp, error_resp, ok_resp]
+        client = Skala(SkalaOptions(api_key="sk_test_123", retries=2))
+        result = client.score(
+            ScoreRequest(event_type="signup", ip="203.0.113.9", email="retry@example.com")
+        )
+
+        assert result.decision == "step_up"
+        assert mock_post.call_count == 3
+
+
+def test_returns_allow_fallback_on_timeout():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.side_effect = __import__("httpx").TimeoutException("timeout")
+        client = Skala(SkalaOptions(api_key="sk_test_123", timeout_ms=10))
+        result = client.score(
+            ScoreRequest(event_type="signup", ip="203.0.113.9", email="slow@example.com")
+        )
+
+        assert isinstance(result, ScoreFallbackResponse)
+        assert result.decision == "allow"
+        assert result.risk_score == 0
+        assert result.reason_codes == ["SDK_TIMEOUT_FALLBACK"]
+        assert result.fallback is True
+
+
+def test_returns_allow_fallback_on_network_error():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.side_effect = Exception("fetch failed")
+        client = Skala(SkalaOptions(api_key="sk_test_123"))
+        result = client.score(
+            ScoreRequest(event_type="signup", ip="203.0.113.9", email="netdown@example.com")
+        )
+
+        assert isinstance(result, ScoreFallbackResponse)
+        assert result.decision == "allow"
+        assert result.risk_score == 0
+        assert result.reason_codes == ["SDK_NETWORK_FALLBACK"]
+        assert result.fallback is True
+
+
+def test_hashes_email_before_sending():
+    with patch("skala._client.httpx.post") as mock_post:
+        mock_post.return_value = make_score_response()
+        client = Skala(SkalaOptions(api_key="sk_test"))
+        client.score(ScoreRequest(event_type="signup", ip="1.2.3.4", email="User@Example.COM"))
+        body = mock_post.call_args[1]["json"]
+        assert body["email_hash"] == _sha256_hex("user@example.com")
+        assert "email" not in body