newapi-python 0.1.0__py3-none-any.whl

newapi/_resources.py

@@ -0,0 +1,775 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Iterator, Mapping, Sequence
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
+
+from ._exceptions import ProtocolError
+from ._models import (
+    CheckinResult,
+    CheckinStatus,
+    Group,
+    Log,
+    LoginSession,
+    Page,
+    PaymentConfig,
+    PaymentLink,
+    Redemption,
+    Resource,
+    Subscription,
+    SubscriptionPlan,
+    Token,
+    TopUpOrder,
+    User,
+)
+
+if TYPE_CHECKING:
+    from ._client import NewAPI
+
+R = TypeVar("R", bound=Resource)
+_UNSET = object()
+
+LOG_TYPES: dict[str, int] = {
+    "unknown": 0,
+    "topup": 1,
+    "consume": 2,
+    "manage": 3,
+    "system": 4,
+    "error": 5,
+    "refund": 6,
+    "login": 7,
+}
+TOKEN_STATUS = {"unknown": 0, "enabled": 1, "disabled": 2, "expired": 3, "exhausted": 4}
+
+
+def _mapping(data: Any, operation: str) -> Mapping[str, Any]:
+    if not isinstance(data, Mapping):
+        raise ProtocolError(f"{operation} returned {type(data).__name__}, expected an object")
+    return data
+
+
+def _list(data: Any, operation: str) -> list[Any]:
+    if not isinstance(data, list):
+        raise ProtocolError(f"{operation} returned {type(data).__name__}, expected a list")
+    return data
+
+
+def _page(data: Any, item_type: type[R], operation: str) -> Page[R]:
+    payload = _mapping(data, operation)
+    try:
+        return Page.from_data(payload, item_type)
+    except (TypeError, ValueError) as error:
+        raise ProtocolError(f"{operation} returned invalid pagination data") from error
+
+
+def _positive(value: int, name: str) -> int:
+    if isinstance(value, bool) or value < 1:
+        raise ValueError(f"{name} must be at least 1")
+    return value
+
+
+def _nonnegative(value: int | float, name: str) -> int | float:
+    if isinstance(value, bool) or not math.isfinite(value) or value < 0:
+        raise ValueError(f"{name} must be a finite non-negative number")
+    return value
+
+
+def _log_type(value: int | str | None) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise ValueError("log_type must be an integer or one of: " + ", ".join(LOG_TYPES))
+    if isinstance(value, int):
+        return value
+    try:
+        return LOG_TYPES[value.strip().lower()]
+    except KeyError as error:
+        raise ValueError(
+            "log_type must be an integer or one of: " + ", ".join(LOG_TYPES)
+        ) from error
+
+
+def _timestamp(value: datetime | int | None, name: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise ValueError(f"{name} must be a datetime or a Unix timestamp")
+    if isinstance(value, int):
+        return value
+    return int(value.timestamp())
+
+
+def _expiry(value: datetime | int | str) -> int:
+    if isinstance(value, bool):
+        raise ValueError("expired_time must be a datetime, a Unix timestamp, or -1")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, datetime):
+        return int(value.timestamp())
+    value = value.strip()
+    if value in {"", "-1", "never"}:
+        return -1
+    try:
+        return int(value)
+    except ValueError as error:
+        raise ValueError("expired_time must be a datetime, a Unix timestamp, or -1") from error
+
+
+def _allow_ips(value: str | Sequence[str] | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (bytes, bytearray)) or any(not isinstance(item, str) for item in value):
+        raise ValueError("allow_ips must be a string or a sequence of strings")
+    return ",".join(value)
+
+
+def _string_list(value: Sequence[str], name: str) -> list[str]:
+    if isinstance(value, (str, bytes)) or any(not isinstance(item, str) for item in value):
+        raise ValueError(f"{name} must be a sequence of strings")
+    return list(value)
+
+
+class AccountResource:
+    def __init__(self, client: NewAPI) -> None:
+        self._client = client
+
+    def profile(self) -> User:
+        return User(_mapping(self._client.request("GET", "user/self"), "profile"))
+
+    def update_self(self, fields: Mapping[str, Any]) -> None:
+        if not _mapping(fields, "update_self fields"):
+            raise ValueError("fields must not be empty")
+        self._client.request("PUT", "user/self", json=dict(fields))
+
+    def generate_access_token(self) -> str:
+        data = self._client.request("GET", "user/token")
+        if not isinstance(data, str) or not data.strip():
+            raise ProtocolError("access token generation did not return a key")
+        return data
+
+    def sessions(self) -> tuple[LoginSession, ...]:
+        data = _list(self._client.request("GET", "user/sessions"), "login sessions")
+        return tuple(LoginSession(item) for item in data if isinstance(item, Mapping))
+
+    def revoke_session(self, sid: str) -> None:
+        if not sid.strip():
+            raise ValueError("sid must not be empty")
+        self._client.request("DELETE", f"user/sessions/{sid}")
+
+    def revoke_other_sessions(self) -> int:
+        data = _mapping(
+            self._client.request("POST", "user/sessions/revoke-others"),
+            "session revocation",
+        )
+        return int(data.get("revoked_count", 0))
+
+    def aff_code(self) -> str:
+        data = self._client.request("GET", "user/aff")
+        if not isinstance(data, str) or not data.strip():
+            raise ProtocolError("affiliate code response did not return a code")
+        return data
+
+    def transfer_aff_quota(self, quota: int) -> None:
+        quota = int(_nonnegative(quota, "quota"))
+        if quota == 0:
+            raise ValueError("quota must be greater than zero")
+        self._client.request("POST", "user/aff_transfer", json={"quota": quota})
+
+    def checkin_status(self, month: str | None = None) -> CheckinStatus:
+        params = {"month": month}
+        data = _mapping(
+            self._client.request("GET", "user/checkin", params=params),
+            "check-in status",
+        )
+        return CheckinStatus(data)
+
+    def checkin(self, *, turnstile_token: str | None = None) -> CheckinResult:
+        params = {"turnstile": turnstile_token} if turnstile_token else None
+        data = _mapping(self._client.request("POST", "user/checkin", params=params), "check-in")
+        return CheckinResult(data)
+
+    def models(self, *, group: str | None = None) -> tuple[str, ...]:
+        params = {"group": group}
+        data = _list(
+            self._client.request("GET", "user/self/models", params=params),
+            "user models",
+        )
+        return tuple(item for item in data if isinstance(item, str))
+
+
+class TokensResource:
+    def __init__(self, client: NewAPI) -> None:
+        self._client = client
+
+    def __call__(self, **kwargs: Any) -> Page[Token]:
+        return self.list(**kwargs)
+
+    def list(
+        self,
+        *,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> Page[Token]:
+        params = {
+            "p": _positive(page, "page"),
+            "page_size": _positive(page_size, "page_size"),
+        }
+        return _page(self._client.request("GET", "token/", params=params), Token, "tokens")
+
+    def iter(self, **kwargs: Any) -> Iterator[Token]:
+        page_number = int(kwargs.pop("page", 1))
+        while True:
+            result = self.list(page=page_number, **kwargs)
+            yield from result
+            if not result.has_next:
+                return
+            page_number += 1
+
+    def all(self, *, page_size: int = 100, **filters: Any) -> tuple[Token, ...]:
+        return tuple(self.iter(page_size=page_size, **filters))
+
+    def search(
+        self,
+        *,
+        keyword: str | None = None,
+        token: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> Page[Token]:
+        params = {
+            "keyword": keyword,
+            "token": token,
+            "p": _positive(page, "page"),
+            "page_size": _positive(page_size, "page_size"),
+        }
+        return _page(self._client.request("GET", "token/search", params=params), Token, "tokens")
+
+    def get(self, token_id: int) -> Token:
+        token_id = _positive(token_id, "token_id")
+        return Token(_mapping(self._client.request("GET", f"token/{token_id}"), "token"))
+
+    def reveal(self, token_id: int) -> str:
+        token_id = _positive(token_id, "token_id")
+        data = _mapping(
+            self._client.request("POST", f"token/{token_id}/key"),
+            "token key",
+        )
+        key = data.get("key")
+        if not isinstance(key, str) or not key:
+            raise ProtocolError("token key response did not contain a key")
+        return key
+
+    def reveal_batch(self, token_ids: Sequence[int]) -> dict[int, str]:
+        ids = [_positive(token_id, "token_id") for token_id in token_ids]
+        if not ids:
+            return {}
+        if len(ids) > 100:
+            raise ValueError("at most 100 token IDs can be revealed per batch")
+        data = _mapping(
+            self._client.request("POST", "token/batch/keys", json={"ids": ids}),
+            "token keys",
+        )
+        keys = _mapping(data.get("keys", {}), "token keys")
+        try:
+            return {int(key): str(value) for key, value in keys.items()}
+        except (TypeError, ValueError) as error:
+            raise ProtocolError("token keys contained invalid entries") from error
+
+    def create(
+        self,
+        name: str,
+        *,
+        expired_time: datetime | int = -1,
+        remain_quota: int = 500000,
+        unlimited_quota: bool = True,
+        model_limits_enabled: bool = False,
+        model_limits: str = "",
+        allow_ips: str | Sequence[str] | None = None,
+        group: str = "",
+        auto_groups: Sequence[str] | None = None,
+        cross_group_retry: bool = False,
+    ) -> None:
+        if not name.strip():
+            raise ValueError("name must not be empty")
+        if len(name) > 50:
+            raise ValueError("name must be at most 50 characters")
+        remain_quota = int(_nonnegative(remain_quota, "remain_quota"))
+        payload: dict[str, Any] = {
+            "name": name,
+            "expired_time": _expiry(expired_time),
+            "remain_quota": remain_quota,
+            "unlimited_quota": unlimited_quota,
+            "model_limits_enabled": model_limits_enabled,
+            "model_limits": model_limits,
+            "allow_ips": _allow_ips(allow_ips) if allow_ips is not None else "",
+            "group": group,
+            "cross_group_retry": cross_group_retry,
+        }
+        if auto_groups is not None:
+            payload["auto_groups"] = _string_list(auto_groups, "auto_groups")
+        self._client.request("POST", "token/", json=payload)
+
+    def create_and_reveal(
+        self,
+        name: str,
+        *,
+        expired_time: datetime | int = -1,
+        remain_quota: int = 500000,
+        unlimited_quota: bool = True,
+        model_limits_enabled: bool = False,
+        model_limits: str = "",
+        allow_ips: str | Sequence[str] | None = None,
+        group: str = "",
+        auto_groups: Sequence[str] | None = None,
+        cross_group_retry: bool = False,
+    ) -> tuple[Token, str]:
+        self.create(
+            name,
+            expired_time=expired_time,
+            remain_quota=remain_quota,
+            unlimited_quota=unlimited_quota,
+            model_limits_enabled=model_limits_enabled,
+            model_limits=model_limits,
+            allow_ips=allow_ips,
+            group=group,
+            auto_groups=auto_groups,
+            cross_group_retry=cross_group_retry,
+        )
+        for token in self.iter(page_size=100):
+            if token.get("name") == name:
+                return token, self.reveal(int(token["id"]))
+        raise ProtocolError("created token could not be found in the token list")
+
+    def update(
+        self,
+        token_id: int,
+        *,
+        name: Any = _UNSET,
+        expired_time: Any = _UNSET,
+        remain_quota: Any = _UNSET,
+        unlimited_quota: Any = _UNSET,
+        model_limits_enabled: Any = _UNSET,
+        model_limits: Any = _UNSET,
+        allow_ips: Any = _UNSET,
+        group: Any = _UNSET,
+        auto_groups: Any = _UNSET,
+        cross_group_retry: Any = _UNSET,
+        fetch_current: bool = True,
+    ) -> Token:
+        token_id = _positive(token_id, "token_id")
+        current: Token | None = None
+        if fetch_current:
+            current = self.get(token_id)
+        payload: dict[str, Any] = {"id": token_id}
+
+        def value_or_current(field: str, provided: Any, default: Any) -> Any:
+            if provided is not _UNSET:
+                return provided
+            if current is not None and current.get(field) is not None:
+                return current[field]
+            return default
+
+        raw_name = value_or_current("name", name, "")
+        if not isinstance(raw_name, str) or not raw_name.strip():
+            raise ValueError("name must not be empty")
+        if len(raw_name) > 50:
+            raise ValueError("name must be at most 50 characters")
+        payload["name"] = raw_name
+        raw_expired = value_or_current("expired_time", expired_time, -1)
+        if expired_time is not _UNSET:
+            payload["expired_time"] = _expiry(expired_time)
+        else:
+            payload["expired_time"] = int(raw_expired) if raw_expired is not None else -1
+        raw_quota = value_or_current("remain_quota", remain_quota, 0)
+        if remain_quota is not _UNSET:
+            payload["remain_quota"] = int(_nonnegative(remain_quota, "remain_quota"))
+        else:
+            payload["remain_quota"] = int(raw_quota) if raw_quota is not None else 0
+        payload["unlimited_quota"] = bool(
+            value_or_current("unlimited_quota", unlimited_quota, False)
+        )
+        payload["model_limits_enabled"] = bool(
+            value_or_current("model_limits_enabled", model_limits_enabled, False)
+        )
+        payload["model_limits"] = str(value_or_current("model_limits", model_limits, ""))
+        raw_ips = value_or_current("allow_ips", allow_ips, "")
+        if allow_ips is not _UNSET:
+            payload["allow_ips"] = _allow_ips(allow_ips) if allow_ips is not None else ""
+        else:
+            payload["allow_ips"] = str(raw_ips) if raw_ips is not None else ""
+        payload["group"] = str(value_or_current("group", group, ""))
+        if auto_groups is not _UNSET:
+            if auto_groups is None:
+                payload["auto_groups"] = None
+            else:
+                payload["auto_groups"] = _string_list(auto_groups, "auto_groups")
+        elif current is not None:
+            payload["auto_groups"] = current.get("auto_groups")
+        payload["cross_group_retry"] = bool(
+            value_or_current("cross_group_retry", cross_group_retry, False)
+        )
+        data = self._client.request("PUT", "token/", json=payload)
+        if data is None:
+            return self.get(token_id)
+        return Token(_mapping(data, "updated token"))
+
+    def set_status(
+        self,
+        token_id: int,
+        status: int | Literal["enabled", "disabled", "expired", "exhausted"],
+    ) -> Token:
+        token_id = _positive(token_id, "token_id")
+        if isinstance(status, str):
+            try:
+                status = TOKEN_STATUS[status.strip().lower()]
+            except KeyError as error:
+                raise ValueError(
+                    "status must be an integer or one of: " + ", ".join(TOKEN_STATUS)
+                ) from error
+        if isinstance(status, bool) or not isinstance(status, int) or status < 0:
+            raise ValueError("status must be an integer or one of: " + ", ".join(TOKEN_STATUS))
+        data = self._client.request(
+            "PUT",
+            "token/",
+            params={"status_only": "true"},
+            json={"id": token_id, "status": status},
+        )
+        if data is None:
+            return self.get(token_id)
+        return Token(_mapping(data, "updated token"))
+
+    def enable(self, token_id: int) -> Token:
+        return self.set_status(token_id, "enabled")
+
+    def disable(self, token_id: int) -> Token:
+        return self.set_status(token_id, "disabled")
+
+    def delete(self, token_id: int) -> None:
+        token_id = _positive(token_id, "token_id")
+        self._client.request("DELETE", f"token/{token_id}")
+
+    def delete_batch(self, token_ids: Sequence[int]) -> int:
+        ids = [_positive(token_id, "token_id") for token_id in token_ids]
+        if not ids:
+            raise ValueError("token_ids must not be empty")
+        data = self._client.request("POST", "token/batch", json={"ids": ids})
+        return int(data) if isinstance(data, int) else 0
+
+    def auto_groups(self) -> Resource:
+        data = _mapping(self._client.request("GET", "token/auto-groups"), "auto groups")
+        return Resource(data)
+
+
+class LogsResource:
+    def __init__(self, client: NewAPI) -> None:
+        self._client = client
+
+    def __call__(self, **kwargs: Any) -> Page[Log]:
+        return self.list(**kwargs)
+
+    def list(
+        self,
+        *,
+        page: int = 1,
+        page_size: int = 20,
+        log_type: int | str | None = None,
+        start_timestamp: datetime | int | None = None,
+        end_timestamp: datetime | int | None = None,
+        token_name: str | None = None,
+        model_name: str | None = None,
+        group: str | None = None,
+        request_id: str | None = None,
+        upstream_request_id: str | None = None,
+    ) -> Page[Log]:
+        params = {
+            "p": _positive(page, "page"),
+            "page_size": _positive(page_size, "page_size"),
+            "type": _log_type(log_type),
+            "start_timestamp": _timestamp(start_timestamp, "start_timestamp"),
+            "end_timestamp": _timestamp(end_timestamp, "end_timestamp"),
+            "token_name": token_name,
+            "model_name": model_name,
+            "group": group,
+            "request_id": request_id,
+            "upstream_request_id": upstream_request_id,
+        }
+        return _page(self._client.request("GET", "log/self", params=params), Log, "logs")
+
+    def iter(self, **kwargs: Any) -> Iterator[Log]:
+        page_number = int(kwargs.pop("page", 1))
+        while True:
+            result = self.list(page=page_number, **kwargs)
+            yield from result
+            if not result.has_next:
+                return
+            page_number += 1
+
+    def all(self, *, page_size: int = 100, **filters: Any) -> tuple[Log, ...]:
+        return tuple(self.iter(page_size=page_size, **filters))
+
+    def stat(
+        self,
+        *,
+        log_type: int | str | None = None,
+        start_timestamp: datetime | int | None = None,
+        end_timestamp: datetime | int | None = None,
+        token_name: str | None = None,
+        model_name: str | None = None,
+        group: str | None = None,
+    ) -> Resource:
+        params = {
+            "type": _log_type(log_type),
+            "start_timestamp": _timestamp(start_timestamp, "start_timestamp"),
+            "end_timestamp": _timestamp(end_timestamp, "end_timestamp"),
+            "token_name": token_name,
+            "model_name": model_name,
+            "group": group,
+        }
+        return Resource(
+            _mapping(self._client.request("GET", "log/self/stat", params=params), "log stats")
+        )
+
+
+class DashboardResource:
+    def __init__(self, client: NewAPI) -> None:
+        self._client = client
+
+    def quota_data(
+        self,
+        *,
+        start_timestamp: datetime | int | None = None,
+        end_timestamp: datetime | int | None = None,
+    ) -> tuple[Resource, ...]:
+        params = {
+            "start_timestamp": _timestamp(start_timestamp, "start_timestamp"),
+            "end_timestamp": _timestamp(end_timestamp, "end_timestamp"),
+        }
+        data = _list(
+            self._client.request("GET", "data/self", params=params),
+            "quota data",
+        )
+        return tuple(Resource(item) for item in data if isinstance(item, Mapping))
+
+    def flow_data(
+        self,
+        *,
+        start_timestamp: datetime | int,
+        end_timestamp: datetime | int,
+    ) -> tuple[Resource, ...]:
+        params = {
+            "start_timestamp": _timestamp(start_timestamp, "start_timestamp"),
+            "end_timestamp": _timestamp(end_timestamp, "end_timestamp"),
+        }
+        if not params["start_timestamp"] or not params["end_timestamp"]:
+            raise ValueError("start_timestamp and end_timestamp are required and must be positive")
+        if params["end_timestamp"] < params["start_timestamp"]:
+            raise ValueError("end_timestamp must not be before start_timestamp")
+        data = _list(
+            self._client.request("GET", "data/flow/self", params=params),
+            "flow quota data",
+        )
+        return tuple(Resource(item) for item in data if isinstance(item, Mapping))
+
+
+class GroupsResource:
+    def __init__(self, client: NewAPI) -> None:
+        self._client = client
+
+    def __call__(self) -> dict[str, Group]:
+        return self.list()
+
+    def list(self) -> dict[str, Group]:
+        data = _mapping(self._client.request("GET", "user/self/groups"), "groups")
+        groups: dict[str, Group] = {}
+        for name, item in data.items():
+            if not isinstance(item, Mapping):
+                raise ProtocolError("groups response contained a non-object group")
+            fields = dict(item)
+            fields["name"] = name
+            groups[str(name)] = Group(fields)
+        return groups
+
+
+class TopUpResource:
+    def __init__(self, client: NewAPI) -> None:
+        self._client = client
+
+    def info(self) -> PaymentConfig:
+        data = _mapping(self._client.request("GET", "user/topup/info"), "topup info")
+        return PaymentConfig(data)
+
+    def __call__(self, **kwargs: Any) -> Page[TopUpOrder]:
+        return self.list(**kwargs)
+
+    def list(
+        self,
+        *,
+        page: int = 1,
+        page_size: int = 20,
+        keyword: str | None = None,
+    ) -> Page[TopUpOrder]:
+        params = {
+            "p": _positive(page, "page"),
+            "page_size": _positive(page_size, "page_size"),
+            "keyword": keyword,
+        }
+        return _page(
+            self._client.request("GET", "user/topup/self", params=params),
+            TopUpOrder,
+            "topup orders",
+        )
+
+    def orders(self, **kwargs: Any) -> Page[TopUpOrder]:
+        return self.list(**kwargs)
+
+    def redeem(self, code: str) -> Redemption:
+        if not code.strip():
+            raise ValueError("code must not be empty")
+        data = self._client.request("POST", "user/topup", json={"key": code})
+        return Redemption({"quota": data} if not isinstance(data, Mapping) else data)
+
+
+class PaymentResource:
+    def __init__(self, client: NewAPI) -> None:
+        self._client = client
+
+    def epay_amount(self, amount: int) -> Decimal:
+        amount = int(_nonnegative(amount, "amount"))
+        return self._amount("user/amount", {"amount": amount})
+
+    def epay_pay(self, amount: int, payment_method: str) -> PaymentLink:
+        amount = int(_nonnegative(amount, "amount"))
+        if not payment_method.strip():
+            raise ValueError("payment_method must not be empty")
+        payload = {"amount": amount, "payment_method": payment_method}
+        data = _mapping(
+            self._client.request("POST", "user/pay", json=payload),
+            "epay payment",
+        )
+        url = data.get("url")
+        return PaymentLink(
+            {
+                "url": url if isinstance(url, str) else None,
+                "params": data.get("data") if isinstance(data.get("data"), Mapping) else None,
+            }
+        )
+
+    def stripe_amount(self, amount: int) -> Decimal:
+        amount = int(_nonnegative(amount, "amount"))
+        return self._amount("user/stripe/amount", {"amount": amount, "payment_method": "stripe"})
+
+    def stripe_pay(
+        self,
+        amount: int,
+        *,
+        success_url: str | None = None,
+        cancel_url: str | None = None,
+    ) -> str:
+        amount = int(_nonnegative(amount, "amount"))
+        payload: dict[str, Any] = {"amount": amount, "payment_method": "stripe"}
+        if success_url is not None:
+            payload["success_url"] = success_url
+        if cancel_url is not None:
+            payload["cancel_url"] = cancel_url
+        data = _mapping(
+            self._client.request("POST", "user/stripe/pay", json=payload),
+            "stripe payment",
+        ).get("data")
+        if not isinstance(data, Mapping):
+            raise ProtocolError("stripe payment did not return a pay link")
+        pay_link = data.get("pay_link")
+        if not isinstance(pay_link, str) or not pay_link:
+            raise ProtocolError("stripe payment did not return a pay link")
+        return pay_link
+
+    def creem_pay(self, product_id: str) -> str:
+        if not product_id.strip():
+            raise ValueError("product_id must not be empty")
+        payload = {"product_id": product_id, "payment_method": "creem"}
+        data = _mapping(
+            self._client.request("POST", "user/creem/pay", json=payload),
+            "creem payment",
+        ).get("data")
+        if not isinstance(data, Mapping):
+            raise ProtocolError("creem payment did not return a pay link")
+        pay_link = data.get("pay_link")
+        if not isinstance(pay_link, str) or not pay_link:
+            raise ProtocolError("creem payment did not return a pay link")
+        return pay_link
+
+    def _amount(self, path: str, payload: Mapping[str, Any]) -> Decimal:
+        data = _mapping(self._client.request("POST", path, json=dict(payload)), "payment amount")
+        value = data.get("data")
+        if not isinstance(value, str) or not value:
+            raise ProtocolError("payment amount response did not contain an amount")
+        try:
+            return Decimal(value)
+        except InvalidOperation as error:
+            raise ProtocolError("payment amount response contained an invalid amount") from error
+
+
+class SubscriptionResource:
+    def __init__(self, client: NewAPI) -> None:
+        self._client = client
+
+    def __call__(self) -> Resource:
+        return self.self()
+
+    def plans(self) -> tuple[SubscriptionPlan, ...]:
+        data = _list(self._client.request("GET", "subscription/plans"), "subscription plans")
+        plans: list[SubscriptionPlan] = []
+        for item in data:
+            if not isinstance(item, Mapping):
+                continue
+            plan = item.get("plan")
+            if isinstance(plan, Mapping):
+                plans.append(SubscriptionPlan(plan))
+        return tuple(plans)
+
+    def self(self) -> Resource:
+        data = _mapping(self._client.request("GET", "subscription/self"), "subscriptions")
+        return Resource(data)
+
+    def active(self) -> tuple[Subscription, ...]:
+        data = _mapping(self.self(), "subscriptions").get("subscriptions", [])
+        return tuple(
+            Subscription(item) for item in _list(data, "subscriptions") if isinstance(item, Mapping)
+        )
+
+    def set_preference(
+        self, preference: Literal["subscription_first", "balance_first", "subscription_only"]
+    ) -> Resource:
+        data = _mapping(
+            self._client.request(
+                "PUT",
+                "subscription/self/preference",
+                json={"billing_preference": preference},
+            ),
+            "billing preference",
+        )
+        return Resource(data)
+
+    def purchase_with_balance(self, plan_id: int) -> None:
+        plan_id = _positive(plan_id, "plan_id")
+        self._client.request("POST", "subscription/balance/pay", json={"plan_id": plan_id})
+
+    def stripe_pay(self, plan_id: int) -> str:
+        plan_id = _positive(plan_id, "plan_id")
+        data = _mapping(
+            self._client.request(
+                "POST",
+                "subscription/stripe/pay",
+                json={"plan_id": plan_id},
+            ),
+            "subscription stripe payment",
+        ).get("data")
+        if not isinstance(data, Mapping):
+            raise ProtocolError("subscription stripe payment did not return a pay link")
+        pay_link = data.get("pay_link")
+        if not isinstance(pay_link, str) or not pay_link:
+            raise ProtocolError("subscription stripe payment did not return a pay link")
+        return pay_link