skalaio 0.2.0__py3-none-any.whl

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",
+]

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)

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

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+skala/__init__.py,sha256=_eoMkrKFicliDegSOu18kz_Jax0i0gl8AnJTV_0l69Q,755
+skala/_client.py,sha256=dPFufJHtcaje1CUwVbfpp9OvMxmeOcyHrsyFZVF1aVE,4838
+skala/_errors.py,sha256=6i19YPazwhvfSSF6hID4coGo4ab4YmafHNJpS4LhwV0,1500
+skala/_types.py,sha256=WZZhTJMPtWzinjNQOu4_s_3P3YNq4HRiKSAWDd-swwA,2392
+skalaio-0.2.0.dist-info/METADATA,sha256=TNMiSb9Ia7CutrCkZfl-klvjgSN5Dyur5th-8yu95qo,2254
+skalaio-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+skalaio-0.2.0.dist-info/RECORD,,

skalaio-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any