wlt-platform 0.1.0__py3-none-any.whl

wlt/__init__.py

@@ -0,0 +1,28 @@
+"""WLT Python SDK -- Official client library for the WLT (White Label Token) Console API.
+
+Quick start::
+
+    from wlt import WltClient
+
+    client = WltClient(api_key="sk-xxx")
+    result = client.secrets.list()
+    print(result.data)
+
+For async usage::
+
+    from wlt import AsyncWltClient
+
+    async def main():
+        async with AsyncWltClient(api_key="sk-xxx") as client:
+            result = await client.secrets.list()
+"""
+
+from .client import AsyncWltClient, WltClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "WltClient",
+    "AsyncWltClient",
+    "__version__",
+]

wlt/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as ``python -m wlt`` or ``python -m wlt.cli``."""
+from wlt.cli import main
+
+main()

wlt/_config.py

@@ -0,0 +1,34 @@
+"""Client configuration for the WLT SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ClientConfig:
+    """Configuration for the WLT client.
+
+    Attributes:
+        api_key: API key used to obtain a Bearer Token via loginByApiKey.
+            The SDK automatically calls ``POST /xt-console/api/user/loginByApiKey``
+            to exchange the api_key for a short-lived token, then uses that token
+            in the ``Authorization: Bearer {token}`` header for all subsequent requests.
+        base_url: The base URL of the WLT Console API.
+            Trailing slashes are stripped automatically.
+        timeout: Request timeout in seconds. Default is 30.
+        max_retries: Maximum number of retry attempts for transient failures.
+            Default is 2. Retries use exponential backoff with jitter.
+        default_headers: Additional headers to include in every request.
+    """
+
+    api_key: str = ""
+    base_url: str = "https://daily.sssxuntui.com"
+    timeout: float = 30.0
+    max_retries: int = 2
+    default_headers: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.base_url = self.base_url.rstrip("/")
+        if not self.api_key:
+            raise ValueError("api_key is required and must not be empty")

wlt/_exceptions.py

@@ -0,0 +1,120 @@
+"""Exception hierarchy for the WLT SDK.
+
+The exception hierarchy maps business error codes from BaseResponse.code
+to specific exception types:
+
+    WltError (base)
+    +-- APIError (generic API error with code/message)
+    |   +-- AuthenticationError (code 2000 / 2002 / 3001)
+    |   +-- PermissionError (code 2007)
+    |   +-- NotFoundError (code 1002)
+    |   +-- ValidationError (code 1001)
+    |   +-- RateLimitError (code 3002)
+    |   +-- InternalError (code 1000)
+    +-- ConnectionError (network-level failures)
+    +-- TimeoutError (request timeout)
+"""
+
+from __future__ import annotations
+
+
+class WltError(Exception):
+    """Base exception for all WLT SDK errors."""
+
+    def __init__(self, message: str = "An error occurred") -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class APIError(WltError):
+    """Generic API error carrying business code and message from BaseResponse."""
+
+    def __init__(self, code: int, message: str) -> None:
+        self.code = code
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"APIError(code={self.code}, message={self.message!r})"
+
+    def __repr__(self) -> str:
+        return f"APIError(code={self.code}, message={self.message!r})"
+
+
+class AuthenticationError(APIError):
+    """Raised when authentication fails (business code 2000, 2002, or 3001)."""
+
+    def __str__(self) -> str:
+        return f"AuthenticationError(code={self.code}, message={self.message!r})"
+
+
+class PermissionError(APIError):
+    """Raised when the user lacks permission (business code 2007)."""
+
+    def __str__(self) -> str:
+        return f"PermissionError(code={self.code}, message={self.message!r})"
+
+
+class NotFoundError(APIError):
+    """Raised when the requested resource is not found (business code 1002)."""
+
+    def __str__(self) -> str:
+        return f"NotFoundError(code={self.code}, message={self.message!r})"
+
+
+class ValidationError(APIError):
+    """Raised when request parameters are invalid (business code 1001)."""
+
+    def __str__(self) -> str:
+        return f"ValidationError(code={self.code}, message={self.message!r})"
+
+
+class RateLimitError(APIError):
+    """Raised when the request rate limit is exceeded (business code 3002)."""
+
+    def __str__(self) -> str:
+        return f"RateLimitError(code={self.code}, message={self.message!r})"
+
+
+class InternalError(APIError):
+    """Raised on system-level errors (business code 1000)."""
+
+    def __str__(self) -> str:
+        return f"InternalError(code={self.code}, message={self.message!r})"
+
+
+class ConnectionError(WltError):
+    """Raised when a network connection error occurs."""
+
+    pass
+
+
+class TimeoutError(WltError):
+    """Raised when a request times out."""
+
+    pass
+
+
+# Mapping from business error code to exception class
+_ERROR_CODE_MAP: dict[int, type[APIError]] = {
+    1000: InternalError,
+    1001: ValidationError,
+    1002: NotFoundError,
+    2000: AuthenticationError,
+    2002: AuthenticationError,
+    2007: PermissionError,
+    3001: AuthenticationError,
+    3002: RateLimitError,
+}
+
+
+def raise_for_code(code: int, message: str) -> None:
+    """Raise the appropriate exception for the given business error code.
+
+    If the code is 200 (success), this function does nothing. Otherwise,
+    it looks up the code in the error map and raises the corresponding
+    exception, falling back to APIError for unknown codes.
+    """
+    if code == 200:
+        return
+    exc_cls = _ERROR_CODE_MAP.get(code, APIError)
+    raise exc_cls(code=code, message=message)

wlt/_http.py

@@ -0,0 +1,436 @@
+"""Low-level HTTP transport for the WLT SDK.
+
+Provides synchronous and asynchronous HTTP clients built on httpx,
+with automatic two-step token authentication (apiKey -> token),
+retry with exponential backoff, and business-error-code checking.
+
+Authentication flow:
+1. On construction, call POST /xt-console/api/user/loginByApiKey?apiKey={api_key}
+   to exchange the API key for a short-lived Bearer token.
+2. All subsequent requests use Authorization: Bearer {token}.
+3. When a response returns business code 3001 (token expired / permission denied),
+   the client automatically re-authenticates and retries the original request once.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+from typing import Any, Generator, Iterator
+
+import httpx
+
+from ._config import ClientConfig
+from ._exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    TimeoutError,
+    raise_for_code,
+)
+
+_LOGIN_PATH = "/xt-console/api/user/loginByApiKey"
+_CODE_TOKEN_EXPIRED = 3001
+
+
+def _build_url(config: ClientConfig, path: str) -> str:
+    """Build the full URL from config base_url and an API path."""
+    if path.startswith("http://") or path.startswith("https://"):
+        return path
+    return f"{config.base_url}{path}"
+
+
+def _backoff_delay(attempt: int) -> float:
+    """Calculate exponential backoff delay with jitter.
+
+    delay = min(2^attempt * 0.5, 8.0) + random jitter in [0, 0.5)
+    """
+    base = min(2**attempt * 0.5, 8.0)
+    jitter = random.random() * 0.5  # noqa: S311
+    return base + jitter
+
+
+class SyncHTTPClient:
+    """Synchronous HTTP client wrapping httpx.Client with two-step token authentication.
+
+    The client automatically exchanges the api_key for a Bearer token via
+    ``loginByApiKey`` at construction time, and refreshes it when the server
+    returns business code 3001 (token expired / permission denied).
+    """
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._token: str = ""
+        self._client = httpx.Client(
+            timeout=httpx.Timeout(config.timeout),
+            headers=config.default_headers,
+            follow_redirects=True,
+        )
+        # Obtain initial token
+        self._authenticate()
+
+    def _authenticate(self) -> None:
+        """Call loginByApiKey to exchange api_key for a Bearer token."""
+        url = _build_url(self._config, _LOGIN_PATH)
+        try:
+            response = self._client.request(
+                "POST",
+                url,
+                params={"apiKey": self._config.api_key},
+            )
+            data = response.json()
+            code = data.get("code", 0)
+            if code != 200:
+                message = data.get("message", "loginByApiKey failed")
+                raise AuthenticationError(code=code, message=message)
+            token = data.get("data", "")
+            if not token:
+                raise AuthenticationError(
+                    code=code,
+                    message="loginByApiKey returned empty token",
+                )
+            self._token = token
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(
+                f"loginByApiKey timed out after {self._config.timeout}s"
+            ) from exc
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"loginByApiKey connection failed: {exc}") from exc
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send an HTTP request with retry logic and return parsed JSON.
+
+        If the server returns business code 3001 (token expired / permission
+        denied), the client automatically re-authenticates via loginByApiKey
+        and retries the request once.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE).
+            path: API path, e.g. "/xt-console/api/secret/list".
+            json: Request body as JSON dict (for POST/PUT).
+            params: Query parameters dict (for GET/DELETE).
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            ConnectionError: On network-level failures.
+            TimeoutError: When the request times out.
+            APIError (or subclass): When the business code indicates an error.
+        """
+        url = _build_url(self._config, path)
+        last_exc: Exception | None = None
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    json=json,
+                    params=params,
+                    headers={"Authorization": f"Bearer {self._token}"},
+                )
+                # Handle HTTP-level errors (e.g. 500)
+                if response.status_code >= 500:
+                    if attempt < self._config.max_retries:
+                        time.sleep(_backoff_delay(attempt))
+                        continue
+                    response.raise_for_status()
+
+                data = response.json()
+
+                # Check business error code
+                code = data.get("code", 200)
+                message = data.get("message", "")
+
+                # Auto-refresh token on code 3001 (token expired / permission denied)
+                if code == _CODE_TOKEN_EXPIRED:
+                    self._authenticate()
+                    # Retry the original request once with new token
+                    response = self._client.request(
+                        method,
+                        url,
+                        json=json,
+                        params=params,
+                        headers={"Authorization": f"Bearer {self._token}"},
+                    )
+                    data = response.json()
+                    code = data.get("code", 200)
+                    message = data.get("message", "")
+
+                raise_for_code(code, message)
+
+                return data
+
+            except httpx.TimeoutException as exc:
+                last_exc = exc
+                if attempt < self._config.max_retries:
+                    time.sleep(_backoff_delay(attempt))
+                    continue
+                raise TimeoutError(f"Request timed out after {self._config.timeout}s") from exc
+
+            except httpx.ConnectError as exc:
+                last_exc = exc
+                if attempt < self._config.max_retries:
+                    time.sleep(_backoff_delay(attempt))
+                    continue
+                raise ConnectionError(f"Connection failed: {exc}") from exc
+
+            except httpx.HTTPStatusError as exc:
+                raise ConnectionError(
+                    f"HTTP {exc.response.status_code}: {exc.response.text}"
+                ) from exc
+
+        # Should not reach here, but just in case
+        if last_exc is not None:
+            raise ConnectionError(f"Request failed after retries: {last_exc}") from last_exc
+        raise ConnectionError("Request failed after retries")
+
+    def stream_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Iterator[str]:
+        """Send an HTTP request and yield SSE data lines.
+
+        This method is designed for Server-Sent Events (SSE) endpoints
+        like model stream inference. It yields each ``data:`` line content
+        as a string (without the ``data:`` prefix).
+
+        Args:
+            method: HTTP method (GET, POST).
+            path: API path.
+            json_body: Request body as JSON dict.
+            params: Query parameters dict.
+
+        Yields:
+            Each SSE data line content as a string.
+
+        Raises:
+            ConnectionError: On network-level failures.
+            TimeoutError: When the request times out.
+        """
+        url = _build_url(self._config, path)
+        try:
+            with self._client.stream(
+                method,
+                url,
+                json=json_body,
+                params=params,
+                headers={"Authorization": f"Bearer {self._token}"},
+            ) as response:
+                for line in response.iter_lines():
+                    if line.startswith("data:"):
+                        yield line[len("data:"):].strip()
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Stream request timed out after {self._config.timeout}s") from exc
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Stream connection failed: {exc}") from exc
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release resources."""
+        self._client.close()
+
+
+class AsyncHTTPClient:
+    """Asynchronous HTTP client wrapping httpx.AsyncClient with two-step token authentication.
+
+    The client automatically exchanges the api_key for a Bearer token via
+    ``loginByApiKey`` before the first request, and refreshes it when the server
+    returns business code 3001 (token expired / permission denied).
+    """
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._token: str = ""
+        self._authenticated = False
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(config.timeout),
+            headers=config.default_headers,
+            follow_redirects=True,
+        )
+
+    async def _authenticate(self) -> None:
+        """Call loginByApiKey to exchange api_key for a Bearer token."""
+        url = _build_url(self._config, _LOGIN_PATH)
+        try:
+            response = await self._client.request(
+                "POST",
+                url,
+                params={"apiKey": self._config.api_key},
+            )
+            data = response.json()
+            code = data.get("code", 0)
+            if code != 200:
+                message = data.get("message", "loginByApiKey failed")
+                raise AuthenticationError(code=code, message=message)
+            token = data.get("data", "")
+            if not token:
+                raise AuthenticationError(
+                    code=code,
+                    message="loginByApiKey returned empty token",
+                )
+            self._token = token
+            self._authenticated = True
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(
+                f"loginByApiKey timed out after {self._config.timeout}s"
+            ) from exc
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"loginByApiKey connection failed: {exc}") from exc
+
+    async def _ensure_authenticated(self) -> None:
+        """Ensure the client has a valid token (lazy initialization for async)."""
+        if not self._authenticated:
+            await self._authenticate()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send an async HTTP request with retry logic and return parsed JSON.
+
+        If the server returns business code 3001 (token expired / permission
+        denied), the client automatically re-authenticates via loginByApiKey
+        and retries the request once.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE).
+            path: API path, e.g. "/xt-console/api/secret/list".
+            json: Request body as JSON dict (for POST/PUT).
+            params: Query parameters dict (for GET/DELETE).
+
+        Returns:
+            Parsed JSON response as a dict.
+
+        Raises:
+            ConnectionError: On network-level failures.
+            TimeoutError: When the request times out.
+            APIError (or subclass): When the business code indicates an error.
+        """
+        import asyncio
+
+        await self._ensure_authenticated()
+
+        url = _build_url(self._config, path)
+        last_exc: Exception | None = None
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    url,
+                    json=json,
+                    params=params,
+                    headers={"Authorization": f"Bearer {self._token}"},
+                )
+                if response.status_code >= 500:
+                    if attempt < self._config.max_retries:
+                        await asyncio.sleep(_backoff_delay(attempt))
+                        continue
+                    response.raise_for_status()
+
+                data = response.json()
+
+                code = data.get("code", 200)
+                message = data.get("message", "")
+
+                # Auto-refresh token on code 3001 (token expired / permission denied)
+                if code == _CODE_TOKEN_EXPIRED:
+                    await self._authenticate()
+                    # Retry the original request once with new token
+                    response = await self._client.request(
+                        method,
+                        url,
+                        json=json,
+                        params=params,
+                        headers={"Authorization": f"Bearer {self._token}"},
+                    )
+                    data = response.json()
+                    code = data.get("code", 200)
+                    message = data.get("message", "")
+
+                raise_for_code(code, message)
+
+                return data
+
+            except httpx.TimeoutException as exc:
+                last_exc = exc
+                if attempt < self._config.max_retries:
+                    await asyncio.sleep(_backoff_delay(attempt))
+                    continue
+                raise TimeoutError(f"Request timed out after {self._config.timeout}s") from exc
+
+            except httpx.ConnectError as exc:
+                last_exc = exc
+                if attempt < self._config.max_retries:
+                    await asyncio.sleep(_backoff_delay(attempt))
+                    continue
+                raise ConnectionError(f"Connection failed: {exc}") from exc
+
+            except httpx.HTTPStatusError as exc:
+                raise ConnectionError(
+                    f"HTTP {exc.response.status_code}: {exc.response.text}"
+                ) from exc
+
+        if last_exc is not None:
+            raise ConnectionError(f"Request failed after retries: {last_exc}") from last_exc
+        raise ConnectionError("Request failed after retries")
+
+    async def stream_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ):
+        """Send an async HTTP request and yield SSE data lines.
+
+        This method is designed for Server-Sent Events (SSE) endpoints.
+        It yields each ``data:`` line content as a string.
+
+        Args:
+            method: HTTP method (GET, POST).
+            path: API path.
+            json_body: Request body as JSON dict.
+            params: Query parameters dict.
+
+        Yields:
+            Each SSE data line content as a string.
+        """
+        await self._ensure_authenticated()
+        url = _build_url(self._config, path)
+        try:
+            async with self._client.stream(
+                method,
+                url,
+                json=json_body,
+                params=params,
+                headers={"Authorization": f"Bearer {self._token}"},
+            ) as response:
+                async for line in response.aiter_lines():
+                    if line.startswith("data:"):
+                        yield line[len("data:"):].strip()
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Stream request timed out after {self._config.timeout}s") from exc
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"Stream connection failed: {exc}") from exc
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client and release resources."""
+        await self._client.aclose()

wlt/_types.py

@@ -0,0 +1,38 @@
+"""Common type definitions for the WLT SDK."""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+# Sentinel for distinguishing "not provided" from None
+_UNSET = object()
+
+
+class _UnsetType:
+    """Sentinel type used to distinguish 'not provided' from None."""
+
+    _instance: _UnsetType | None = None
+
+    def __new__(cls) -> _UnsetType:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+UNSET = _UnsetType()
+
+
+class HeadersDict(dict):
+    """A dict subclass for HTTP headers."""
+
+    pass