sub2api 0.1.0__py3-none-any.whl

sub2api/_models.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator, Mapping
+from copy import deepcopy
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any, Generic, TypeVar
+
+_SENSITIVE_FIELDS = frozenset(
+    {
+        "access_token",
+        "authorization",
+        "code",
+        "cookie",
+        "custom_key",
+        "key",
+        "password",
+        "refresh_token",
+        "temp_token",
+    }
+)
+
+
+def _redacted(value: Any, field: str | None = None) -> Any:
+    if field is not None and field.lower() in _SENSITIVE_FIELDS and value not in (None, ""):
+        return "********"
+    if isinstance(value, Mapping):
+        return {str(key): _redacted(item, str(key)) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_redacted(item) for item in value]
+    return value
+
+
+def _wrapped(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return Resource(value)
+    if isinstance(value, list):
+        return [_wrapped(item) for item in value]
+    return value
+
+
+class Resource(Mapping[str, Any]):
+    """A response object supporting both mapping and attribute access."""
+
+    __slots__ = ("_data",)
+
+    def __init__(self, data: Mapping[str, Any]) -> None:
+        self._data = dict(data)
+
+    def __getitem__(self, key: str) -> Any:
+        return _wrapped(self._data[key])
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError as error:
+            raise AttributeError(name) from error
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({_redacted(self._data)!r})"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return an independent dictionary containing the full response data."""
+        return deepcopy(self._data)
+
+
+class User(Resource):
+    """The authenticated user's profile."""
+
+
+class APIKey(Resource):
+    """A user-owned gateway API key."""
+
+
+class Group(Resource):
+    """A group available to the authenticated user."""
+
+
+class UsageRecord(Resource):
+    """One gateway usage-history record."""
+
+
+class PlatformQuota(Resource):
+    """Usage and limit values for one upstream platform."""
+
+
+class Subscription(Resource):
+    """A user subscription."""
+
+
+class Announcement(Resource):
+    """A user-visible announcement."""
+
+
+class Redemption(Resource):
+    """A redemption result or history item."""
+
+
+@dataclass(frozen=True)
+class KeyGroupMultiplier:
+    """The group multiplier resolved for one API key."""
+
+    api_key: APIKey
+    group: Group | None
+    group_id: int | None
+    base_multiplier: float | None
+    custom_multiplier: float | None
+    effective_multiplier: float | None
+
+    @property
+    def is_custom(self) -> bool:
+        return self.custom_multiplier is not None
+
+
+T = TypeVar("T", bound=Resource)
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """One page returned by a list endpoint."""
+
+    items: tuple[T, ...]
+    total: int
+    page: int
+    page_size: int
+    pages: int
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    @property
+    def has_next(self) -> bool:
+        return self.page < self.pages
+
+    @classmethod
+    def from_data(cls, data: Mapping[str, Any], item_type: type[T]) -> Page[T]:
+        raw_items = data.get("items", [])
+        if not isinstance(raw_items, list):
+            raise TypeError("paginated response items must be a list")
+        if any(not isinstance(item, Mapping) for item in raw_items):
+            raise TypeError("paginated response items must contain objects")
+        return cls(
+            items=tuple(item_type(item) for item in raw_items),
+            total=int(data.get("total", len(raw_items))),
+            page=int(data.get("page", 1)),
+            page_size=int(data.get("page_size", len(raw_items) or 1)),
+            pages=int(data.get("pages", 1)),
+        )
+
+
+@dataclass(frozen=True)
+class Balance:
+    """The user's USD-denominated balance values."""
+
+    balance: Decimal
+    frozen_balance: Decimal
+    total_recharged: Decimal
+
+
+@dataclass(frozen=True)
+class SessionTokens:
+    """The current in-memory dashboard session tokens."""
+
+    access_token: str | None = field(default=None, repr=False)
+    refresh_token: str | None = field(default=None, repr=False)
+    expires_at: float | None = None
+    token_type: str = "Bearer"
+
+    @property
+    def authenticated(self) -> bool:
+        return bool(self.access_token)
+
+    @property
+    def expires_in(self) -> float | None:
+        if self.expires_at is None:
+            return None
+        return max(0.0, self.expires_at - time.time())
+
+    def needs_refresh(self, leeway: float = 30.0) -> bool:
+        return (
+            self.refresh_token is not None
+            and self.expires_at is not None
+            and self.expires_at <= time.time() + leeway
+        )