newapi-python 0.1.0__py3-none-any.whl

newapi/__init__.py

@@ -0,0 +1,75 @@
+from ._client import NewAPI
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    NewAPIError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    TransportError,
+    TwoFactorRequired,
+    ValidationError,
+)
+from ._models import (
+    Announcement,
+    APIKey,
+    Balance,
+    CheckinResult,
+    CheckinStatus,
+    Group,
+    Log,
+    LoginSession,
+    Page,
+    PaymentConfig,
+    PaymentLink,
+    Redemption,
+    Resource,
+    SessionTokens,
+    Subscription,
+    SubscriptionPlan,
+    Token,
+    TopUpOrder,
+    UsageRecord,
+    User,
+)
+
+__all__ = [
+    "APIError",
+    "APIKey",
+    "Announcement",
+    "AuthenticationError",
+    "Balance",
+    "CheckinResult",
+    "CheckinStatus",
+    "ConfigurationError",
+    "ConflictError",
+    "Group",
+    "Log",
+    "LoginSession",
+    "NewAPI",
+    "NewAPIError",
+    "NotFoundError",
+    "Page",
+    "PaymentConfig",
+    "PaymentLink",
+    "PermissionDeniedError",
+    "ProtocolError",
+    "RateLimitError",
+    "Redemption",
+    "Resource",
+    "SessionTokens",
+    "Subscription",
+    "SubscriptionPlan",
+    "Token",
+    "TopUpOrder",
+    "TransportError",
+    "TwoFactorRequired",
+    "UsageRecord",
+    "User",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"

newapi/_client.py

@@ -0,0 +1,620 @@
+from __future__ import annotations
+
+import re
+import threading
+from collections.abc import Mapping
+from typing import Any, cast
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+from curl_cffi import requests as curl_requests
+
+from ._crypto import rsa_oaep_sha256_encrypt
+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,
+    DashboardResource,
+    GroupsResource,
+    LogsResource,
+    PaymentResource,
+    SubscriptionResource,
+    TokensResource,
+    TopUpResource,
+)
+
+_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"})
+_REFRESH_COOKIE = "new_api_refresh"
+_REFRESH_COOKIE_PATTERN = re.compile(rf"(?:^|[;,\s]){_REFRESH_COOKIE}=([^;\s]+)")
+_DEFAULT_QUOTA_PER_UNIT = 500000.0
+
+
+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"):
+        path = f"{path}/api"
+    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":
+        path = ""
+    elif path.startswith("api/"):
+        path = path[len("api/") :]
+    if any(segment in {"..", "."} 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"
+    return value
+
+
+def _query(params: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    if params is None:
+        return None
+    return {
+        str(key): _query_value(value)
+        for key, value in params.items()
+        if value is not None and value != ""
+    }
+
+
+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
+
+
+def _set_cookie_values(response: Any) -> list[str]:
+    headers = response.headers
+    get_list = getattr(headers, "get_list", None)
+    if callable(get_list):
+        return [str(value) for value in get_list("set-cookie")]
+    raw = headers.get("set-cookie")
+    if raw is None:
+        return []
+    if isinstance(raw, str):
+        return [raw]
+    return [str(value) for value in raw]
+
+
+class NewAPI:
+    """An authenticated user session for one new-api instance."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        access_token: str | None = None,
+        refresh_token: str | None = None,
+        expires_at: float | None = None,
+        session_id: str | None = None,
+        timeout: float | tuple[float, float] = 30.0,
+        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.language = language
+        self._tokens = SessionTokens(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_at=expires_at,
+            session_id=session_id,
+        )
+        self._refresh_lock = threading.RLock()
+        self._pending_2fa_token: str | None = None
+        self.timeout = timeout
+        self.impersonate = impersonate
+        self._quota_per_unit: float | None = None
+        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.tokens = TokensResource(self)
+        self.keys = self.tokens
+        self.logs = LogsResource(self)
+        self.usage = self.logs
+        self.history = self.logs
+        self.groups = GroupsResource(self)
+        self.dashboard = DashboardResource(self)
+        self.topup = TopUpResource(self)
+        self.payment = PaymentResource(self)
+        self.subscriptions = SubscriptionResource(self)
+
+    @property
+    def session(self) -> SessionTokens:
+        return self._tokens
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._tokens.authenticated
+
+    @property
+    def quota_per_unit(self) -> float | None:
+        return self._quota_per_unit
+
+    def login(
+        self,
+        username: str,
+        password: str,
+        *,
+        turnstile_token: str | None = None,
+        encrypt_password: bool = True,
+    ) -> User:
+        if not username.strip() or not password:
+            raise ValueError("username and password are required")
+        payload: dict[str, Any] = {"username": username}
+        key = self._password_encryption_key() if encrypt_password else None
+        if key is not None:
+            payload["password_encrypted"] = rsa_oaep_sha256_encrypt(
+                password.encode(), key["public_key"]
+            )
+            payload["encryption_key_id"] = key["kid"]
+        else:
+            payload["password"] = password
+        params = {"turnstile": turnstile_token} if turnstile_token else None
+        data, response = self._request_with_response(
+            "POST",
+            "user/login",
+            params=params,
+            json=payload,
+            authenticated=False,
+            allow_refresh=False,
+        )
+        auth = self._auth_mapping(data, "login")
+        if auth.get("require_2fa") is True:
+            flow_token = auth.get("flow_token")
+            if not isinstance(flow_token, str) or not flow_token:
+                raise ProtocolError("2FA login response did not contain a flow token")
+            self._pending_2fa_token = flow_token
+            expires_at = auth.get("expires_at")
+            raise TwoFactorRequired(
+                flow_token,
+                float(expires_at) if isinstance(expires_at, (int, float)) else None,
+            )
+        return self._accept_auth(auth, response)
+
+    def complete_2fa(self, code: str, *, flow_token: str | None = None) -> User:
+        token = flow_token or self._pending_2fa_token
+        if not token:
+            raise ValueError("flow_token is required when no 2FA login is pending")
+        if not code.strip():
+            raise ValueError("code must not be empty")
+        data, response = self._request_with_response(
+            "POST",
+            "user/login/2fa",
+            json={"code": code, "flow_token": token},
+            authenticated=False,
+            allow_refresh=False,
+        )
+        user = self._accept_auth(self._auth_mapping(data, "2FA login"), response)
+        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, response = self._request_with_response(
+                    "POST",
+                    "user/auth/refresh",
+                    refresh_cookie=refresh_token,
+                    authenticated=False,
+                    allow_refresh=False,
+                )
+                auth = self._auth_mapping(data, "token refresh")
+                access_token = auth.get("access_token")
+                if not isinstance(access_token, str) or not access_token:
+                    raise ProtocolError("token refresh did not return an access token")
+                rotated = self._harvest_refresh_token(response) or refresh_token
+                self._tokens = self._tokens_from_auth(auth, rotated)
+                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
+        headers: dict[str, str] = {"Origin": self._origin()}
+        if self._tokens.access_token:
+            headers["Authorization"] = f"{self._tokens.token_type} {self._tokens.access_token}"
+        try:
+            self._request(
+                "POST",
+                "user/auth/logout",
+                refresh_cookie=refresh_token,
+                headers=headers,
+                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:
+        profile = self.account.profile()
+        quota_per_unit = self._resolve_quota_per_unit()
+        try:
+            return Balance(
+                quota=int(profile.get("quota", 0)),
+                used_quota=int(profile.get("used_quota", 0)),
+                aff_quota=int(profile.get("aff_quota", 0)),
+                quota_per_unit=quota_per_unit,
+            )
+        except (TypeError, ValueError) as error:
+            raise ProtocolError("profile response did not contain valid quota values") from error
+
+    def status(self) -> Resource:
+        data = self._request(
+            "GET",
+            "status",
+            authenticated=False,
+            allow_refresh=False,
+        )
+        if not isinstance(data, Mapping):
+            raise ProtocolError("status returned a non-object response")
+        quota_per_unit = data.get("quota_per_unit")
+        if isinstance(quota_per_unit, (int, float)) and quota_per_unit > 0:
+            self._quota_per_unit = float(quota_per_unit)
+        return Resource(data)
+
+    def notice(self) -> Any:
+        return self._request("GET", "notice", authenticated=False, allow_refresh=False)
+
+    def about(self) -> Any:
+        return self._request("GET", "about", authenticated=False, allow_refresh=False)
+
+    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) -> NewAPI:
+        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,
+        refresh_cookie: str | None = None,
+    ) -> Any:
+        return self._request_with_response(
+            method,
+            path,
+            params=params,
+            json=json,
+            headers=headers,
+            authenticated=authenticated,
+            allow_refresh=allow_refresh,
+            refresh_cookie=refresh_cookie,
+        )[0]
+
+    def _request_with_response(
+        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,
+        refresh_cookie: str | None = None,
+    ) -> tuple[Any, 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,
+            refresh_cookie=refresh_cookie,
+        )
+        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), response
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None,
+        json: Any,
+        headers: Mapping[str, str] | None,
+        authenticated: bool,
+        refresh_cookie: str | None = None,
+    ) -> Any:
+        relative_path = _request_path(path)
+        request_headers = {
+            "Accept": "application/json",
+            "Accept-Language": self.language,
+            "User-Agent": "newapi-python/0.1.0",
+        }
+        if authenticated and self._tokens.access_token:
+            request_headers["Authorization"] = (
+                f"{self._tokens.token_type} {self._tokens.access_token}"
+            )
+        if refresh_cookie and not self._session_has_refresh_cookie():
+            request_headers["Cookie"] = f"{_REFRESH_COOKIE}={refresh_cookie}"
+        if headers:
+            request_headers.update(headers)
+        try:
+            return cast(Any, self._http).request(
+                method,
+                f"{self.base_url}/{relative_path}",
+                params=_query(params),
+                json=json,
+                headers=request_headers,
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except curl_requests.RequestsError as error:
+            raise TransportError(f"{method} request to the new-api 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"new-api returned non-JSON HTTP {response.status_code}"
+                ) from error
+            raise ProtocolError("new-api returned a non-JSON success response") from error
+        if not _success(response):
+            self._raise_api_error(response, payload)
+        if isinstance(payload, Mapping):
+            if "success" in payload:
+                if payload.get("success") is not True:
+                    self._raise_api_error(response, payload)
+                return payload.get("data")
+            if "message" in payload:
+                if payload.get("message") != "success":
+                    self._raise_api_error(response, payload)
+                return payload
+        return payload
+
+    def _raise_api_error(self, response: Any, payload: Any) -> None:
+        data = payload if isinstance(payload, Mapping) else {}
+        code = data.get("code")
+        fallback_message = (
+            getattr(response, "reason_phrase", None)
+            or getattr(response, "reason", None)
+            or f"HTTP {response.status_code}"
+        )
+        message: Any = data.get("message")
+        detail = data.get("data")
+        if not isinstance(message, str) or message == "" or message == "error":
+            message = detail if isinstance(detail, str) and detail else fallback_message
+        status_code = response.status_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,
+            retry_after=_retry_after(response),
+        )
+
+    def _origin(self) -> str:
+        parsed = urlsplit(self.base_url)
+        return urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+
+    def _password_encryption_key(self) -> Resource | None:
+        data = self._request(
+            "GET",
+            "user/login/encryption-key",
+            authenticated=False,
+            allow_refresh=False,
+        )
+        if not isinstance(data, Mapping):
+            raise ProtocolError("login encryption key response was not an object")
+        key = Resource(data)
+        if not key.get("enabled"):
+            return None
+        if not key.get("kid") or not key.get("public_key"):
+            raise ProtocolError("login encryption key response was incomplete")
+        return key
+
+    def _harvest_refresh_token(self, response: Any) -> str | None:
+        for value in _set_cookie_values(response):
+            match = _REFRESH_COOKIE_PATTERN.search(value)
+            if match:
+                return match.group(1)
+        jar = getattr(self._http, "cookies", None)
+        if jar is not None:
+            try:
+                stored = jar.get(_REFRESH_COOKIE)
+            except Exception:
+                stored = None
+            if isinstance(stored, str) and stored:
+                return stored
+        return None
+
+    def _session_has_refresh_cookie(self) -> bool:
+        jar = getattr(self._http, "cookies", None)
+        if jar is None:
+            return False
+        try:
+            stored = jar.get(_REFRESH_COOKIE)
+        except Exception:
+            return False
+        return isinstance(stored, str) and bool(stored)
+
+    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], response: 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, self._harvest_refresh_token(response))
+        return User(user_data)
+
+    def _tokens_from_auth(
+        self,
+        auth: Mapping[str, Any],
+        refresh_token: str | None,
+    ) -> SessionTokens:
+        expires_at = None
+        raw_expires_at = auth.get("access_expires_at")
+        if isinstance(raw_expires_at, (int, float)) and not isinstance(raw_expires_at, bool):
+            expires_at = float(raw_expires_at)
+        token_type = auth.get("token_type")
+        session = auth.get("session")
+        session_id = None
+        if isinstance(session, Mapping):
+            raw_session_id = session.get("sid")
+            session_id = raw_session_id if isinstance(raw_session_id, str) else None
+        return SessionTokens(
+            access_token=str(auth["access_token"]),
+            refresh_token=refresh_token,
+            expires_at=expires_at,
+            token_type=str(token_type) if token_type else "Bearer",
+            session_id=session_id,
+        )
+
+    def _resolve_quota_per_unit(self) -> float:
+        if self._quota_per_unit is None:
+            self.status()
+        return self._quota_per_unit if self._quota_per_unit is not None else _DEFAULT_QUOTA_PER_UNIT