sub2api 0.1.0__py3-none-any.whl

sub2api/__init__.py

@@ -0,0 +1,61 @@
+from ._client import Sub2API
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    Sub2APIError,
+    TransportError,
+    TwoFactorRequired,
+    ValidationError,
+)
+from ._models import (
+    Announcement,
+    APIKey,
+    Balance,
+    Group,
+    KeyGroupMultiplier,
+    Page,
+    PlatformQuota,
+    Redemption,
+    Resource,
+    SessionTokens,
+    Subscription,
+    UsageRecord,
+    User,
+)
+
+__all__ = [
+    "APIError",
+    "APIKey",
+    "Announcement",
+    "AuthenticationError",
+    "Balance",
+    "ConfigurationError",
+    "ConflictError",
+    "Group",
+    "KeyGroupMultiplier",
+    "NotFoundError",
+    "Page",
+    "PermissionDeniedError",
+    "PlatformQuota",
+    "ProtocolError",
+    "RateLimitError",
+    "Redemption",
+    "Resource",
+    "SessionTokens",
+    "Sub2API",
+    "Sub2APIError",
+    "Subscription",
+    "TransportError",
+    "TwoFactorRequired",
+    "UsageRecord",
+    "User",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"

sub2api/_client.py

@@ -0,0 +1,486 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Mapping
+from datetime import date, datetime
+from typing import Any, cast
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+from curl_cffi import requests as curl_requests
+
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    TransportError,
+    TwoFactorRequired,
+    ValidationError,
+)
+from ._models import Balance, Resource, SessionTokens, User
+from ._resources import (
+    AccountResource,
+    AnnouncementsResource,
+    GroupsResource,
+    KeysResource,
+    RedeemResource,
+    SubscriptionsResource,
+    UsageResource,
+)
+
+_ERROR_TYPES: dict[int, type[APIError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+def _api_base_url(value: str, allow_insecure: bool) -> str:
+    candidate = value.strip()
+    if not candidate:
+        raise ConfigurationError("base_url must not be empty")
+    if "://" not in candidate:
+        candidate = f"https://{candidate}"
+    parsed = urlsplit(candidate)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ConfigurationError("base_url must be an HTTP or HTTPS instance URL")
+    if parsed.username or parsed.password:
+        raise ConfigurationError("base_url must not contain credentials")
+    if parsed.query or parsed.fragment:
+        raise ConfigurationError("base_url must not contain a query string or fragment")
+    local = parsed.hostname in _LOCAL_HOSTS or parsed.hostname.endswith(".localhost")
+    if parsed.scheme == "http" and not local and not allow_insecure:
+        raise ConfigurationError(
+            "remote HTTP would expose credentials; use HTTPS or set allow_insecure=True"
+        )
+    path = parsed.path.rstrip("/")
+    if not path.endswith("/api/v1"):
+        path = f"{path}/api/v1"
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+def _request_path(value: str) -> str:
+    parsed = urlsplit(value)
+    if parsed.scheme or parsed.netloc or parsed.fragment:
+        raise ConfigurationError("request path must be relative to the configured instance")
+    if parsed.query:
+        raise ConfigurationError("request path must not contain a query string; use params instead")
+    path = unquote(parsed.path).lstrip("/")
+    if path == "api/v1":
+        path = ""
+    elif path.startswith("api/v1/"):
+        path = path[len("api/v1/") :]
+    if any(segment == ".." for segment in path.split("/")):
+        raise ConfigurationError("request path must not contain parent traversal")
+    if not path:
+        raise ConfigurationError("request path must identify an endpoint")
+    return path
+
+
+def _query_value(value: Any) -> Any:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    return value
+
+
+def _query(params: Mapping[str, Any] | None, timezone: str, method: str) -> dict[str, Any]:
+    output = {
+        key: _query_value(value) for key, value in (params or {}).items() if value is not None
+    }
+    if method == "GET" and "timezone" not in output:
+        output["timezone"] = timezone
+    return output
+
+
+def _success(response: Any) -> bool:
+    return 200 <= int(response.status_code) < 300
+
+
+def _retry_after(response: Any) -> float | None:
+    value = response.headers.get("Retry-After")
+    if value is None:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None
+
+
+class Sub2API:
+    """An authenticated user session for one Sub2API instance."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        access_token: str | None = None,
+        refresh_token: str | None = None,
+        expires_at: float | None = None,
+        timeout: float | tuple[float, float] = 30.0,
+        timezone: str = "UTC",
+        language: str = "en",
+        allow_insecure: bool = False,
+        impersonate: str | None = "chrome",
+        session: Any | None = None,
+    ) -> None:
+        self.base_url = _api_base_url(base_url, allow_insecure)
+        self.timezone = timezone
+        self.language = language
+        self._tokens = SessionTokens(access_token, refresh_token, expires_at)
+        self._refresh_lock = threading.RLock()
+        self._pending_2fa_token: str | None = None
+        self.timeout = timeout
+        self.impersonate = impersonate
+        self._owns_http_client = session is None
+        if session is None:
+            if impersonate:
+                self._http: Any = cast(
+                    Any,
+                    curl_requests.Session(impersonate=impersonate),
+                )
+            else:
+                self._http = cast(Any, curl_requests.Session())
+        else:
+            self._http = session
+        self.account = AccountResource(self)
+        self.keys = KeysResource(self)
+        self.groups = GroupsResource(self)
+        self.usage = UsageResource(self)
+        self.history = self.usage
+        self.subscriptions = SubscriptionsResource(self)
+        self.announcements = AnnouncementsResource(self)
+        self.redeem = RedeemResource(self)
+
+    @property
+    def tokens(self) -> SessionTokens:
+        return self._tokens
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._tokens.authenticated
+
+    def login(
+        self,
+        email: str,
+        password: str,
+        *,
+        turnstile_token: str | None = None,
+        tencent_captcha_ticket: str | None = None,
+        tencent_captcha_randstr: str | None = None,
+    ) -> User:
+        if not email.strip() or not password:
+            raise ValueError("email and password are required")
+        payload = {
+            "email": email,
+            "password": password,
+            "turnstile_token": turnstile_token,
+            "tencent_captcha_ticket": tencent_captcha_ticket,
+            "tencent_captcha_randstr": tencent_captcha_randstr,
+        }
+        data = self._request(
+            "POST",
+            "auth/login",
+            json={key: value for key, value in payload.items() if value is not None},
+            authenticated=False,
+            allow_refresh=False,
+        )
+        auth = self._auth_mapping(data, "login")
+        if auth.get("requires_2fa") is True:
+            temp_token = auth.get("temp_token")
+            if not isinstance(temp_token, str) or not temp_token:
+                raise ProtocolError("2FA login response did not contain a temporary token")
+            self._pending_2fa_token = temp_token
+            masked = auth.get("user_email_masked")
+            raise TwoFactorRequired(
+                temp_token,
+                masked if isinstance(masked, str) else None,
+            )
+        return self._accept_auth(auth)
+
+    def complete_2fa(self, totp_code: str, *, temp_token: str | None = None) -> User:
+        token = temp_token or self._pending_2fa_token
+        if not token:
+            raise ValueError("temp_token is required when no 2FA login is pending")
+        if len(totp_code) != 6 or not totp_code.isdigit():
+            raise ValueError("totp_code must contain exactly six digits")
+        data = self._request(
+            "POST",
+            "auth/login/2fa",
+            json={"temp_token": token, "totp_code": totp_code},
+            authenticated=False,
+            allow_refresh=False,
+        )
+        user = self._accept_auth(self._auth_mapping(data, "2FA login"))
+        self._pending_2fa_token = None
+        return user
+
+    def refresh(self) -> SessionTokens:
+        with self._refresh_lock:
+            refresh_token = self._tokens.refresh_token
+            if not refresh_token:
+                raise AuthenticationError(
+                    "No refresh token is available",
+                    status_code=401,
+                    code="NO_REFRESH_TOKEN",
+                )
+            try:
+                data = self._request(
+                    "POST",
+                    "auth/refresh",
+                    json={"refresh_token": refresh_token},
+                    authenticated=False,
+                    allow_refresh=False,
+                )
+                auth = self._auth_mapping(data, "token refresh")
+                access_token = auth.get("access_token")
+                rotated_token = auth.get("refresh_token")
+                if not isinstance(access_token, str) or not access_token:
+                    raise ProtocolError("token refresh did not return an access token")
+                if not isinstance(rotated_token, str) or not rotated_token:
+                    raise ProtocolError("token refresh did not return a refresh token")
+                self._tokens = self._tokens_from_auth(auth)
+                return self._tokens
+            except APIError as error:
+                if 400 <= error.status_code < 500:
+                    self.clear_auth()
+                raise
+
+    def logout(self) -> None:
+        refresh_token = self._tokens.refresh_token
+        try:
+            if refresh_token:
+                self._request(
+                    "POST",
+                    "auth/logout",
+                    json={"refresh_token": refresh_token},
+                    authenticated=False,
+                    allow_refresh=False,
+                )
+        finally:
+            self.clear_auth()
+
+    def clear_auth(self) -> None:
+        self._tokens = SessionTokens()
+        self._pending_2fa_token = None
+
+    def me(self) -> User:
+        return self.account.profile()
+
+    def balance(self) -> Balance:
+        return self.account.balance()
+
+    def public_settings(self) -> Resource:
+        data = self._request(
+            "GET",
+            "settings/public",
+            authenticated=False,
+            allow_refresh=False,
+        )
+        if not isinstance(data, Mapping):
+            raise ProtocolError("public settings returned a non-object response")
+        return Resource(data)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+        authenticated: bool = True,
+    ) -> Any:
+        return self._request(
+            method,
+            path,
+            params=params,
+            json=json,
+            headers=headers,
+            authenticated=authenticated,
+            allow_refresh=True,
+        )
+
+    def close(self) -> None:
+        if self._owns_http_client:
+            self._http.close()
+
+    def __enter__(self) -> Sub2API:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+        authenticated: bool,
+        allow_refresh: bool,
+    ) -> Any:
+        normalized_method = method.upper()
+        if authenticated and allow_refresh:
+            self._refresh_if_expiring()
+        failed_token = self._tokens.access_token
+        response = self._send(
+            normalized_method,
+            path,
+            params=params,
+            json=json,
+            headers=headers,
+            authenticated=authenticated,
+        )
+        if (
+            response.status_code == 401
+            and authenticated
+            and allow_refresh
+            and self._tokens.refresh_token
+        ):
+            self._refresh_after_unauthorized(failed_token)
+            response = self._send(
+                normalized_method,
+                path,
+                params=params,
+                json=json,
+                headers=headers,
+                authenticated=authenticated,
+            )
+        return self._decode(response)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None,
+        json: Any,
+        headers: Mapping[str, str] | None,
+        authenticated: bool,
+    ) -> Any:
+        relative_path = _request_path(path)
+        request_headers = {
+            "Accept": "application/json",
+            "Accept-Language": self.language,
+            "User-Agent": "sub2api-python/0.1.0",
+            "X-User-UI-Request": "1",
+        }
+        if authenticated and self._tokens.access_token:
+            request_headers["Authorization"] = (
+                f"{self._tokens.token_type} {self._tokens.access_token}"
+            )
+        if headers:
+            request_headers.update(headers)
+        try:
+            return cast(Any, self._http).request(
+                method,
+                f"{self.base_url}/{relative_path}",
+                params=_query(params, self.timezone, method),
+                json=json,
+                headers=request_headers,
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except curl_requests.RequestsError as error:
+            raise TransportError(f"{method} request to the Sub2API instance failed") from error
+
+    def _decode(self, response: Any) -> Any:
+        if not response.content:
+            if _success(response):
+                return None
+            self._raise_api_error(response, {})
+        try:
+            payload = response.json()
+        except ValueError as error:
+            if not _success(response):
+                raise ProtocolError(
+                    f"Sub2API returned non-JSON HTTP {response.status_code}"
+                ) from error
+            raise ProtocolError("Sub2API returned a non-JSON success response") from error
+        if not _success(response):
+            self._raise_api_error(response, payload)
+        if isinstance(payload, Mapping) and "code" in payload:
+            code = payload.get("code")
+            if code != 0:
+                self._raise_api_error(response, payload)
+            return payload.get("data")
+        return payload
+
+    def _raise_api_error(self, response: Any, payload: Any) -> None:
+        data = payload if isinstance(payload, Mapping) else {}
+        code = data.get("code")
+        reason = data.get("reason")
+        fallback_message = (
+            getattr(response, "reason_phrase", None)
+            or getattr(response, "reason", None)
+            or f"HTTP {response.status_code}"
+        )
+        message = data.get("message") or data.get("detail") or fallback_message
+        metadata = data.get("metadata")
+        status_code = response.status_code
+        if _success(response) and isinstance(code, int) and 400 <= code <= 599:
+            status_code = code
+        error_type = _ERROR_TYPES.get(status_code, APIError)
+        raise error_type(
+            str(message),
+            status_code=status_code,
+            code=code if isinstance(code, (int, str)) else None,
+            reason=reason if isinstance(reason, str) else None,
+            metadata=metadata if isinstance(metadata, Mapping) else None,
+            retry_after=_retry_after(response),
+        )
+
+    def _refresh_if_expiring(self) -> None:
+        with self._refresh_lock:
+            if self._tokens.needs_refresh():
+                self.refresh()
+
+    def _refresh_after_unauthorized(self, failed_token: str | None) -> None:
+        with self._refresh_lock:
+            if self._tokens.access_token and self._tokens.access_token != failed_token:
+                return
+            self.refresh()
+
+    def _auth_mapping(self, data: Any, operation: str) -> Mapping[str, Any]:
+        if not isinstance(data, Mapping):
+            raise ProtocolError(f"{operation} returned a non-object response")
+        return data
+
+    def _accept_auth(self, auth: Mapping[str, Any]) -> User:
+        access_token = auth.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise ProtocolError("login did not return an access token")
+        user_data = auth.get("user")
+        if not isinstance(user_data, Mapping):
+            raise ProtocolError("login did not return a user profile")
+        self._tokens = self._tokens_from_auth(auth)
+        return User(user_data)
+
+    def _tokens_from_auth(self, auth: Mapping[str, Any]) -> SessionTokens:
+        expires_in = auth.get("expires_in")
+        expires_at = None
+        if isinstance(expires_in, (int, float)) and not isinstance(expires_in, bool):
+            expires_at = time.time() + max(0.0, float(expires_in))
+        token_type = auth.get("token_type")
+        return SessionTokens(
+            access_token=str(auth["access_token"]),
+            refresh_token=(
+                str(auth["refresh_token"]) if auth.get("refresh_token") not in (None, "") else None
+            ),
+            expires_at=expires_at,
+            token_type=str(token_type) if token_type else "Bearer",
+        )

sub2api/_exceptions.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+class Sub2APIError(Exception):
+    """Base exception for the package."""
+
+
+class ConfigurationError(Sub2APIError, ValueError):
+    """Raised when client configuration is invalid or unsafe."""
+
+
+class TransportError(Sub2APIError):
+    """Raised when the instance cannot be reached or times out."""
+
+
+class ProtocolError(Sub2APIError):
+    """Raised when an instance returns an unsupported response shape."""
+
+
+class APIError(Sub2APIError):
+    """An error returned by a Sub2API instance."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: int | str | None = None,
+        reason: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.reason = reason
+        self.metadata = dict(metadata or {})
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        label = str(self.code or self.reason or self.status_code)
+        return f"Sub2API request failed ({label}): {self.message}"
+
+
+class AuthenticationError(APIError):
+    """Raised when login or session authentication fails."""
+
+
+class PermissionDeniedError(APIError):
+    """Raised when the user cannot perform an operation."""
+
+
+class NotFoundError(APIError):
+    """Raised when a requested resource does not exist."""
+
+
+class ValidationError(APIError):
+    """Raised when the instance rejects request input."""
+
+
+class ConflictError(APIError):
+    """Raised when an operation conflicts with current server state."""
+
+
+class RateLimitError(APIError):
+    """Raised when the panel API rate limit is exceeded."""
+
+
+class TwoFactorRequired(AuthenticationError):
+    """Raised when login must be completed with a TOTP code."""
+
+    def __init__(self, temp_token: str, user_email_masked: str | None = None) -> None:
+        super().__init__(
+            "Two-factor authentication is required",
+            status_code=401,
+            code="TWO_FACTOR_REQUIRED",
+        )
+        self.temp_token = temp_token
+        self.user_email_masked = user_email_masked