guardcoreapi 0.3.0.dev20251113215748__py3-none-any.whl

guardcoreapi/__init__.py

@@ -0,0 +1,3 @@
+from .manager import GuardCoreApi
+
+__all__ = ["GuardCoreApi"]

guardcoreapi/core/__init__.py

@@ -0,0 +1,17 @@
+from .request import RequestCore
+from .exceptions import (
+    GuardCoreApiException,
+    RequestAuthenticationError,
+    RequestConnectionError,
+    RequestResponseError,
+    RequestTimeoutError,
+)
+
+__all__ = [
+    "RequestCore",
+    "GuardCoreApiException",
+    "RequestAuthenticationError",
+    "RequestConnectionError",
+    "RequestResponseError",
+    "RequestTimeoutError",
+]

guardcoreapi/core/exceptions.py

@@ -0,0 +1,28 @@
+class GuardCoreApiException(Exception):
+    """Base class for request errors."""
+
+    pass
+
+
+class RequestTimeoutError(GuardCoreApiException):
+    """Exception raised for request timeouts."""
+
+    pass
+
+
+class RequestConnectionError(GuardCoreApiException):
+    """Exception raised for connection errors."""
+
+    pass
+
+
+class RequestResponseError(GuardCoreApiException):
+    """Exception raised for invalid responses."""
+
+    pass
+
+
+class RequestAuthenticationError(GuardCoreApiException):
+    """Exception raised for authentication failures."""
+
+    pass

guardcoreapi/core/request.py

@@ -0,0 +1,145 @@
+import asyncio
+from typing import Optional
+
+import aiohttp
+from pydantic import BaseModel
+from .exceptions import (
+    RequestAuthenticationError,
+    RequestConnectionError,
+    RequestResponseError,
+    RequestTimeoutError,
+)
+
+
+class RequestCore:
+    _BASE_URL = "https://core.erfjab.com"
+
+    @staticmethod
+    def generate_headers(
+        api_key: Optional[str] = None, access_token: Optional[str] = None
+    ) -> dict:
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+        if api_key:
+            headers["X-API-Key"] = api_key
+        if access_token:
+            headers["Authorization"] = f"Bearer {access_token}"
+        return headers
+
+    @staticmethod
+    async def fetch(
+        endpoint: str,
+        method: str = "GET",
+        headers: Optional[dict] = None,
+        params: Optional[dict] = None,
+        data: Optional[dict] = None,
+        json: Optional[dict] = None,
+        response_model: Optional[BaseModel] = None,
+        use_list: bool = False,
+        timeout: float = 10.0,
+    ) -> dict:
+        try:
+            async with aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=timeout)
+            ) as session:
+                async with session.request(
+                    method=method,
+                    url=RequestCore._BASE_URL + endpoint,
+                    headers=headers,
+                    params=params,
+                    data=data,
+                    json=json,
+                ) as response:
+                    response.raise_for_status()
+                    resp_json = await response.json()
+                    if response_model:
+                        if use_list:
+                            return [response_model(**item) for item in resp_json]
+                        return response_model(**resp_json)
+                    return resp_json
+        except aiohttp.ClientResponseError as e:
+            if e.status == 401:
+                raise RequestAuthenticationError("Authentication failed") from e
+            else:
+                raise RequestResponseError(f"Invalid response: {e.status}") from e
+        except aiohttp.ClientConnectionError as e:
+            raise RequestConnectionError("Connection error occurred") from e
+        except asyncio.TimeoutError as e:
+            raise RequestTimeoutError("Request timed out") from e
+
+    @staticmethod
+    async def get(
+        endpoint: str,
+        headers: Optional[dict] = None,
+        params: Optional[dict] = None,
+        response_model: Optional[BaseModel] = None,
+        use_list: bool = False,
+        timeout: float = 10.0,
+    ) -> dict:
+        return await RequestCore.fetch(
+            endpoint=endpoint,
+            method="GET",
+            headers=headers,
+            params=params,
+            timeout=timeout,
+            use_list=use_list,
+            response_model=response_model,
+        )
+
+    @staticmethod
+    async def post(
+        endpoint: str,
+        headers: Optional[dict] = None,
+        data: Optional[dict] = None,
+        json: Optional[dict] = None,
+        timeout: float = 10.0,
+        response_model: Optional[BaseModel] = None,
+        use_list: bool = False,
+    ) -> dict:
+        return await RequestCore.fetch(
+            endpoint=endpoint,
+            method="POST",
+            headers=headers,
+            data=data,
+            json=json,
+            timeout=timeout,
+            response_model=response_model,
+            use_list=use_list,
+        )
+
+    @staticmethod
+    async def put(
+        endpoint: str,
+        headers: Optional[dict] = None,
+        data: Optional[dict] = None,
+        json: Optional[dict] = None,
+        timeout: float = 10.0,
+        response_model: Optional[BaseModel] = None,
+        use_list: bool = False,
+    ) -> dict:
+        return await RequestCore.fetch(
+            endpoint=endpoint,
+            method="PUT",
+            headers=headers,
+            data=data,
+            json=json,
+            timeout=timeout,
+            response_model=response_model,
+            use_list=use_list,
+        )
+
+    @staticmethod
+    async def delete(
+        endpoint: str,
+        headers: Optional[dict] = None,
+        timeout: float = 10.0,
+    ) -> dict:
+        return await RequestCore.fetch(
+            endpoint=endpoint,
+            method="DELETE",
+            headers=headers,
+            timeout=timeout,
+        )

guardcoreapi/manager.py

@@ -0,0 +1,585 @@
+from .core import RequestCore
+from .types import (
+    AdminToken,
+    AdminResponse,
+    AdminCreate,
+    AdminCurrentUpdate,
+    AdminUsageLogsResponse,
+    AdminUpdate,
+    SubscriptionResponse,
+    SubscriptionCreate,
+    SubscriptionStatsResponse,
+    SubscriptionUpdate,
+    SubscriptionUsageLogsResponse,
+    NodeResponse,
+    NodeCreate,
+    NodeUpdate,
+    NodeStatsResponse,
+    ServiceCreate,
+    ServiceResponse,
+    ServiceUpdate,
+    StatsResponse,
+    AdminStatsResponseNew,
+)
+
+
+class GuardCoreApi:
+    @staticmethod
+    async def get_all_admin(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> list[AdminResponse]:
+        return await RequestCore.get(
+            "/api/admins",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminResponse,
+            use_list=True,
+        )
+
+    @staticmethod
+    async def create_admin(
+        data: AdminCreate, api_key: str | None = None, access_token: str | None = None
+    ) -> AdminResponse:
+        return await RequestCore.post(
+            "/api/admins",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=data.dict(),
+            response_model=AdminResponse,
+        )
+
+    @staticmethod
+    async def generate_admin_token(username: str, password: str) -> AdminToken:
+        return await RequestCore.post(
+            "/api/admins/token",
+            data={
+                "username": username,
+                "password": password,
+            },
+            response_model=AdminToken,
+        )
+
+    @staticmethod
+    async def get_current_admin(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> AdminResponse:
+        return await RequestCore.get(
+            "/api/admins/current",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminResponse,
+        )
+
+    @staticmethod
+    async def update_current_admin(
+        data: AdminCurrentUpdate,
+        api_key: str | None = None,
+        access_token: str | None = None,
+    ) -> AdminResponse:
+        return await RequestCore.put(
+            "/api/admins/current",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=data.dict(),
+            response_model=AdminResponse,
+        )
+
+    @staticmethod
+    async def get_current_admin_usages(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.get(
+            "/api/admins/current/usages",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminUsageLogsResponse,
+        )
+
+    @staticmethod
+    async def get_admin(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> AdminResponse:
+        return await RequestCore.get(
+            f"/api/admins/{username}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminResponse,
+        )
+
+    @staticmethod
+    async def update_admin(
+        username: str,
+        data: AdminUpdate,
+        api_key: str | None = None,
+        access_token: str | None = None,
+    ) -> AdminResponse:
+        return await RequestCore.put(
+            f"/api/admins/{username}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=data.dict(),
+            response_model=AdminResponse,
+        )
+
+    @staticmethod
+    async def delete_admin(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.delete(
+            f"/api/admins/{username}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def get_admin_usages(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.get(
+            f"/api/admins/{username}/usages",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminUsageLogsResponse,
+        )
+
+    @staticmethod
+    async def enable_admin(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> AdminResponse:
+        return await RequestCore.post(
+            f"/api/admins/{username}/enable",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminResponse,
+        )
+
+    @staticmethod
+    async def disable_admin(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> AdminResponse:
+        return await RequestCore.post(
+            f"/api/admins/{username}/disable",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminResponse,
+        )
+
+    @staticmethod
+    async def revoke_admin_api_key(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> AdminResponse:
+        return await RequestCore.post(
+            f"/api/admins/{username}/revoke",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminResponse,
+        )
+
+    @staticmethod
+    async def get_admin_subscriptions(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> list[SubscriptionResponse]:
+        return await RequestCore.get(
+            f"/api/admins/{username}/subscriptions",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=SubscriptionResponse,
+            use_list=True,
+        )
+
+    @staticmethod
+    async def revoke_admin(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.post(
+            f"/api/admins/{username}/revoke",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def delete_admin_subscriptions(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.delete(
+            f"/api/admins/{username}/subscriptions",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def activate_admin_subscriptions(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.post(
+            f"/api/admins/{username}/subscriptions/activate",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def deactivate_admin_subscriptions(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.post(
+            f"/api/admins/{username}/subscriptions/deactivate",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def get_all_subscriptions(
+        api_key: str | None = None,
+        access_token: str | None = None,
+        limited: bool | None = None,
+        expired: bool | None = None,
+        is_active: bool | None = None,
+        enabled: bool | None = None,
+        search: str | None = None,
+        online: bool | None = None,
+        order_by: str | None = None,
+        page: int | None = 1,
+        size: int | None = 10,
+    ) -> list[SubscriptionResponse]:
+        params = {}
+        if limited is not None:
+            params["limited"] = limited
+        if expired is not None:
+            params["expired"] = expired
+        if is_active is not None:
+            params["is_active"] = is_active
+        if enabled is not None:
+            params["enabled"] = enabled
+        if search is not None:
+            params["search"] = search
+        if online is not None:
+            params["online"] = online
+        if order_by is not None:
+            params["order_by"] = order_by
+        if page is not None:
+            params["page"] = page
+        if size is not None:
+            params["size"] = size
+
+        return await RequestCore.get(
+            "/api/subscriptions",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            params=params,
+            response_model=SubscriptionResponse,
+            use_list=True,
+        )
+
+    @staticmethod
+    async def create_subscription(
+        data: list[SubscriptionCreate],
+        api_key: str | None = None,
+        access_token: str | None = None,
+    ) -> SubscriptionResponse:
+        return await RequestCore.post(
+            "/api/subscriptions",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=[item.dict() for item in data],
+            response_model=SubscriptionResponse,
+            use_list=True,
+        )
+
+    @staticmethod
+    async def get_subscription_count(
+        api_key: str | None = None,
+        access_token: str | None = None,
+        limited: bool | None = None,
+        expired: bool | None = None,
+        is_active: bool | None = None,
+        enabled: bool | None = None,
+        online: bool | None = None,
+    ) -> int:
+        params = {}
+        if limited is not None:
+            params["limited"] = limited
+        if expired is not None:
+            params["expired"] = expired
+        if is_active is not None:
+            params["is_active"] = is_active
+        if enabled is not None:
+            params["enabled"] = enabled
+        if online is not None:
+            params["online"] = online
+
+        return await RequestCore.get(
+            "/api/subscriptions/count",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            params=params,
+        )
+
+    @staticmethod
+    async def get_subscription_stats(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> SubscriptionStatsResponse:
+        return await RequestCore.get(
+            "/api/subscriptions/stats",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=SubscriptionStatsResponse,
+        )
+
+    @staticmethod
+    async def get_subscription(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> SubscriptionResponse:
+        return await RequestCore.get(
+            f"/api/subscriptions/{username}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=SubscriptionResponse,
+        )
+
+    @staticmethod
+    async def update_subscription(
+        username: str,
+        data: SubscriptionUpdate,
+        api_key: str | None = None,
+        access_token: str | None = None,
+    ) -> SubscriptionResponse:
+        return await RequestCore.put(
+            f"/api/subscriptions/{username}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=data.dict(),
+            response_model=SubscriptionResponse,
+        )
+
+    @staticmethod
+    async def delete_subscription(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.delete(
+            f"/api/subscriptions/{username}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def get_subscription_usages(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> SubscriptionUsageLogsResponse:
+        return await RequestCore.get(
+            f"/api/subscriptions/{username}/usages",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=SubscriptionUsageLogsResponse,
+        )
+
+    @staticmethod
+    async def enable_subscription(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> SubscriptionResponse:
+        return await RequestCore.post(
+            f"/api/subscriptions/{username}/enable",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=SubscriptionResponse,
+        )
+
+    @staticmethod
+    async def disable_subscription(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> SubscriptionResponse:
+        return await RequestCore.post(
+            f"/api/subscriptions/{username}/disable",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=SubscriptionResponse,
+        )
+
+    @staticmethod
+    async def revoke_subscription(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> SubscriptionResponse:
+        return await RequestCore.post(
+            f"/api/subscriptions/{username}/revoke",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=SubscriptionResponse,
+        )
+
+    @staticmethod
+    async def reset_subscription(
+        username: str, api_key: str | None = None, access_token: str | None = None
+    ) -> SubscriptionResponse:
+        return await RequestCore.post(
+            f"/api/subscriptions/{username}/reset",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=SubscriptionResponse,
+        )
+
+    @staticmethod
+    async def bulk_add_service(
+        service_id: int, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.post(
+            f"/api/subscriptions/services/{service_id}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def bulk_remove_service(
+        service_id: int, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.delete(
+            f"/api/subscriptions/services/{service_id}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def get_nodes(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> list[NodeResponse]:
+        return await RequestCore.get(
+            "/api/nodes",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=NodeResponse,
+            use_list=True,
+        )
+
+    @staticmethod
+    async def create_node(
+        data: NodeCreate, api_key: str | None = None, access_token: str | None = None
+    ) -> NodeResponse:
+        return await RequestCore.post(
+            "/api/nodes",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=data.dict(),
+            response_model=NodeResponse,
+        )
+
+    @staticmethod
+    async def get_node_stats(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> NodeStatsResponse:
+        return await RequestCore.get(
+            "/api/nodes/stats",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=NodeStatsResponse,
+        )
+
+    @staticmethod
+    async def get_node(
+        node_id: int, api_key: str | None = None, access_token: str | None = None
+    ) -> NodeResponse:
+        return await RequestCore.get(
+            f"/api/nodes/{node_id}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=NodeResponse,
+        )
+
+    @staticmethod
+    async def update_node(
+        node_id: int,
+        data: NodeUpdate,
+        api_key: str | None = None,
+        access_token: str | None = None,
+    ) -> NodeResponse:
+        return await RequestCore.put(
+            f"/api/nodes/{node_id}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=data.dict(),
+            response_model=NodeResponse,
+        )
+
+    @staticmethod
+    async def delete_node(
+        node_id: int, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.delete(
+            f"/api/nodes/{node_id}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def enable_node(
+        node_id: int, api_key: str | None = None, access_token: str | None = None
+    ) -> NodeResponse:
+        return await RequestCore.post(
+            f"/api/nodes/{node_id}/enable",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=NodeResponse,
+        )
+
+    @staticmethod
+    async def disable_node(
+        node_id: int, api_key: str | None = None, access_token: str | None = None
+    ) -> NodeResponse:
+        return await RequestCore.post(
+            f"/api/nodes/{node_id}/disable",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=NodeResponse,
+        )
+
+    @staticmethod
+    async def get_services(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> list[ServiceResponse]:
+        return await RequestCore.get(
+            "/api/services",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=ServiceResponse,
+            use_list=True,
+        )
+
+    @staticmethod
+    async def create_service(
+        data: ServiceCreate, api_key: str | None = None, access_token: str | None = None
+    ) -> ServiceResponse:
+        return await RequestCore.post(
+            "/api/services",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=data.dict(),
+            response_model=ServiceResponse,
+        )
+
+    @staticmethod
+    async def get_service(
+        service_id: int, api_key: str | None = None, access_token: str | None = None
+    ) -> ServiceResponse:
+        return await RequestCore.get(
+            f"/api/services/{service_id}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=ServiceResponse,
+        )
+
+    @staticmethod
+    async def update_service(
+        service_id: int,
+        data: ServiceUpdate,
+        api_key: str | None = None,
+        access_token: str | None = None,
+    ) -> ServiceResponse:
+        return await RequestCore.put(
+            f"/api/services/{service_id}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            json=data.dict(),
+            response_model=ServiceResponse,
+        )
+
+    @staticmethod
+    async def delete_service(
+        service_id: int, api_key: str | None = None, access_token: str | None = None
+    ) -> dict:
+        return await RequestCore.delete(
+            f"/api/services/{service_id}",
+            headers=RequestCore.generate_headers(api_key, access_token),
+        )
+
+    @staticmethod
+    async def get_guard(secret: str) -> list[str]:
+        return await RequestCore.get(
+            f"/guards/{secret}",
+        )
+
+    @staticmethod
+    async def get_guard_info(secret: str) -> SubscriptionResponse:
+        return await RequestCore.get(
+            f"/guards/{secret}/info",
+        )
+
+    @staticmethod
+    async def get_guard_usage_logs(secret: str) -> SubscriptionUsageLogsResponse:
+        return await RequestCore.get(
+            f"/guards/{secret}/usages",
+            response_model=SubscriptionUsageLogsResponse,
+        )
+
+    @staticmethod
+    async def get_stats(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> StatsResponse:
+        return await RequestCore.get(
+            "/api/stats",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=StatsResponse,
+        )
+
+    @staticmethod
+    async def get_admin_stats_combined(
+        api_key: str | None = None, access_token: str | None = None
+    ) -> AdminStatsResponseNew:
+        return await RequestCore.get(
+            "/api/stats/admin",
+            headers=RequestCore.generate_headers(api_key, access_token),
+            response_model=AdminStatsResponseNew,
+        )

guardcoreapi/types/__init__.py

@@ -0,0 +1,71 @@
+from .admins import (
+    AdminPlaceHolderCategory,
+    AdminPlaceHolder,
+    AdminRole,
+    AdminToken,
+    AdminResponse,
+    ADMIN_PLACEHOLDER_REMARK_FORMATS,
+    AdminCreate,
+    AdminCurrentUpdate,
+    AdminUpdate,
+    AdminUsageLog,
+    AdminUsageLogsResponse,
+)
+from .subscriptions import (
+    SubscriptionCreate,
+    SubscriptionResponse,
+    SubscriptionUpdate,
+    SubscriptionUsageLog,
+    SubscriptionUsageLogsResponse,
+    SubscriptionStatsResponse,
+)
+from .nodes import (
+    NodeCategory,
+    NodeResponse,
+    NodeCreate,
+    NodeUpdate,
+    NodeStatsResponse,
+)
+from .services import ServiceResponse, ServiceCreate, ServiceUpdate
+from .stats import (
+    StatsResponse,
+    UsageDetailStats,
+    CountDetailStats,
+    TopSubDetailStats,
+    ExpireSubDetailStats,
+    AdminStatsResponseNew,
+)
+
+__all__ = [
+    "AdminPlaceHolderCategory",
+    "AdminPlaceHolder",
+    "AdminRole",
+    "AdminToken",
+    "AdminResponse",
+    "ADMIN_PLACEHOLDER_REMARK_FORMATS",
+    "AdminCreate",
+    "AdminCurrentUpdate",
+    "AdminUpdate",
+    "AdminUsageLog",
+    "AdminUsageLogsResponse",
+    "SubscriptionCreate",
+    "SubscriptionResponse",
+    "SubscriptionUpdate",
+    "SubscriptionUsageLog",
+    "SubscriptionUsageLogsResponse",
+    "SubscriptionStatsResponse",
+    "NodeCategory",
+    "NodeResponse",
+    "NodeCreate",
+    "NodeUpdate",
+    "NodeStatsResponse",
+    "ServiceResponse",
+    "ServiceCreate",
+    "ServiceUpdate",
+    "StatsResponse",
+    "UsageDetailStats",
+    "CountDetailStats",
+    "TopSubDetailStats",
+    "ExpireSubDetailStats",
+    "AdminStatsResponseNew",
+]

guardcoreapi/types/admins.py

@@ -0,0 +1,125 @@
+from enum import StrEnum
+from typing import Optional
+from datetime import datetime
+from pydantic import BaseModel
+
+
+class AdminPlaceHolderCategory(StrEnum):
+    INFO = "info"
+    LIMITED = "limited"
+    EXPIRED = "expired"
+    DISABLED = "disabled"
+
+
+ADMIN_PLACEHOLDER_REMARK_FORMATS = [
+    "id",
+    "username",
+    "owner_username",
+    "enabled",
+    "activated",
+    "limited",
+    "expired",
+    "is_active",
+    "limit_usage",
+    "current_usage",
+    "left_usage",
+    "expire_date",
+    "expire_in",
+    "expire_in_days",
+]
+
+
+class AdminPlaceHolder(BaseModel):
+    remark: str
+    categories: list[AdminPlaceHolderCategory]
+
+
+class AdminRole(StrEnum):
+    OWNER = "owner"
+    SELLER = "seller"
+    RESELLER = "reseller"
+
+
+class AdminToken(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+
+
+class AdminResponse(BaseModel):
+    id: int
+    enabled: bool
+    username: str
+    role: AdminRole
+    service_ids: list[int]
+    create_access: Optional[bool]
+    update_access: Optional[bool]
+    remove_access: Optional[bool]
+    count_limit: Optional[int]
+    current_count: Optional[int]
+    left_count: Optional[int]
+    reached_count_limit: Optional[bool]
+    usage_limit: Optional[int]
+    current_usage: Optional[int]
+    left_usage: Optional[int]
+    reached_usage_limit: Optional[bool]
+    placeholders: Optional[list[AdminPlaceHolder]]
+    max_links: Optional[int]
+    shuffle_links: Optional[bool]
+    api_key: str
+    last_login_at: Optional[datetime]
+    last_online_at: Optional[datetime]
+    access_title: Optional[str] = None
+    access_description: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class AdminCreate(BaseModel):
+    username: str
+    password: str
+    role: AdminRole
+    service_ids: Optional[list[int]]
+    create_access: Optional[bool] = False
+    update_access: Optional[bool] = False
+    remove_access: Optional[bool] = False
+    count_limit: Optional[int] = None
+    usage_limit: Optional[int] = None
+    access_prefix: Optional[str] = None
+
+
+class AdminUpdate(BaseModel):
+    password: Optional[str] = None
+    create_access: Optional[bool] = None
+    update_access: Optional[bool] = None
+    remove_access: Optional[bool] = None
+    count_limit: Optional[int] = None
+    usage_limit: Optional[int] = None
+    service_ids: Optional[list[int]] = None
+    placeholders: Optional[list[AdminPlaceHolder]] = None
+    max_links: Optional[int] = None
+    shuffle_links: Optional[bool] = None
+    access_prefix: Optional[str] = None
+    access_title: Optional[str] = None
+    access_description: Optional[str] = None
+
+
+class AdminCurrentUpdate(BaseModel):
+    password: Optional[str] = None
+    placeholders: Optional[list[AdminPlaceHolder]] = None
+    max_links: Optional[int] = None
+    shuffle_links: Optional[bool] = None
+    access_title: Optional[str] = None
+    access_description: Optional[str] = None
+
+
+class AdminUsageLog(BaseModel):
+    usage: int
+    created_at: datetime
+
+
+class AdminUsageLogsResponse(BaseModel):
+    admin: AdminResponse
+    usages: list[AdminUsageLog]

guardcoreapi/types/nodes.py

@@ -0,0 +1,55 @@
+from enum import StrEnum
+from datetime import datetime
+from pydantic import BaseModel
+
+
+class NodeCategory(StrEnum):
+    marzban = "marzban"
+    marzneshin = "marzneshin"
+
+
+class NodeResponse(BaseModel):
+    id: int
+    enabled: bool
+    remark: str
+    category: NodeCategory
+    username: str
+    password: str
+    host: str
+    current_usage: int
+    last_used_at: datetime | None
+    offset_link: int
+    batch_size: int
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class NodeCreate(BaseModel):
+    remark: str
+    category: NodeCategory
+    username: str
+    password: str
+    host: str
+    offset_link: int = 0
+    batch_size: int = 1
+
+
+class NodeUpdate(BaseModel):
+    remark: str | None = None
+    username: str | None = None
+    password: str | None = None
+    host: str | None = None
+    offset_link: int | None = None
+    batch_size: int | None = None
+
+
+class NodeStatsResponse(BaseModel):
+    total_nodes: int
+    active_nodes: int
+    inactive_nodes: int
+
+    class Config:
+        from_attributes = True

guardcoreapi/types/services.py

@@ -0,0 +1,21 @@
+from typing import List
+from pydantic import BaseModel
+
+
+class ServiceResponse(BaseModel):
+    id: int
+    remark: str
+    node_ids: List[int]
+
+    class Config:
+        from_attributes = True
+
+
+class ServiceCreate(BaseModel):
+    remark: str
+    node_ids: List[int]
+
+
+class ServiceUpdate(BaseModel):
+    remark: str | None = None
+    node_ids: List[int] | None = None

guardcoreapi/types/stats.py

@@ -0,0 +1,96 @@
+from datetime import datetime
+from pydantic import BaseModel
+
+
+class UsageDetailStats(BaseModel):
+    start: datetime | None = None
+    end: datetime | None = None
+    remark: str | None = None
+    step: int | None = None
+    usage: int
+
+
+class CountDetailStats(BaseModel):
+    start: datetime | None = None
+    end: datetime | None = None
+    count: int
+
+
+class TopSubDetailStats(BaseModel):
+    username: str
+    is_active: bool
+    usage: int
+
+
+class ExpireSubDetailStats(BaseModel):
+    username: str
+    is_active: bool
+    expire: int
+
+
+class StatsResponse(BaseModel):
+    total_subscriptions: int
+    active_subscriptions: int
+    inactive_subscriptions: int
+    online_subscriptions: int
+    most_usage_subscription: str | None = None
+    most_usage_subscriptions: list[UsageDetailStats]
+
+    total_admins: int
+    active_admins: int
+    inactive_admins: int
+    most_usage_admins: list[UsageDetailStats]
+
+    total_nodes: int
+    active_nodes: int
+    inactive_nodes: int
+    most_usage_nodes: list[UsageDetailStats]
+
+    total_lifetime_usages: int
+    total_day_usages: int
+    total_week_usages: int
+    last_24h_usages: list[UsageDetailStats]
+    last_7d_usages: list[UsageDetailStats]
+
+
+class AdminStatsResponseNew(BaseModel):
+    usage_limit: int | None
+    current_usage: int
+    left_usage: int | None
+    lifetime_usage: int
+    current_day_usage: int
+    current_week_usage: int
+    yesterday_usage: int
+    last_week_usage: int
+    last_24h_usages: list[UsageDetailStats]
+    last_7d_usages: list[UsageDetailStats]
+    last_1m_usages: list[UsageDetailStats]
+    last_3m_usages: list[UsageDetailStats]
+    last_1y_usages: list[UsageDetailStats]
+    today_top_10_usage_subscriptions: list[TopSubDetailStats]
+    week_top_10_usage_subscriptions: list[TopSubDetailStats]
+    month_top_10_usage_subscriptions: list[TopSubDetailStats]
+    last_24h_counts: list[CountDetailStats]
+    last_7d_counts: list[CountDetailStats]
+    last_1m_counts: list[CountDetailStats]
+    last_3m_counts: list[CountDetailStats]
+    last_1y_counts: list[CountDetailStats]
+    limit_count: int
+    current_count: int
+    left_count: int
+    total_subscriptions: int
+    active_subscriptions: int
+    inactive_subscriptions: int
+    disabled_subscriptions: int
+    expired_subscriptions: int
+    limited_subscriptions: int
+    today_new_subscriptions: int
+    yesterday_new_subscriptions: int
+    today_requested_subscriptions: int
+    today_revoked_subscriptions: int
+    today_reseted_subscriptions: int
+    today_expire_soon_subscriptions: list[ExpireSubDetailStats]
+    week_expire_soon_subscriptions: list[ExpireSubDetailStats]
+    today_removed_subscriptions: int
+    yesterday_removed_subscriptions: int
+    total_removed_subscriptions: int

guardcoreapi/types/subscriptions.py

@@ -0,0 +1,76 @@
+from typing import Optional
+from datetime import datetime
+from pydantic import BaseModel
+
+
+class SubscriptionResponse(BaseModel):
+    id: int
+    username: str
+    owner_username: str
+    access_key: str
+
+    enabled: bool
+    activated: bool
+    reached: bool
+    limited: bool
+    expired: bool
+    is_active: bool
+    is_online: bool
+
+    link: str
+
+    limit_usage: int
+    reset_usage: int
+    total_usage: int
+    current_usage: int
+    limit_expire: int
+
+    service_ids: list[int]
+
+    online_at: Optional[datetime]
+    last_reset_at: Optional[datetime]
+    last_revoke_at: Optional[datetime]
+    last_request_at: Optional[datetime]
+    last_client_agent: Optional[str]
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class SubscriptionCreate(BaseModel):
+    username: str
+    limit_usage: int
+    limit_expire: int
+    service_ids: list[int]
+    access_key: Optional[str] = None
+
+
+class SubscriptionUpdate(BaseModel):
+    limit_usage: Optional[int] = None
+    limit_expire: Optional[int] = None
+    service_ids: Optional[list[int]] = None
+
+
+class SubscriptionUsageLog(BaseModel):
+    usage: int
+    created_at: datetime
+
+
+class SubscriptionUsageLogsResponse(BaseModel):
+    subscription: SubscriptionResponse
+    usages: list[SubscriptionUsageLog]
+
+
+class SubscriptionStatsResponse(BaseModel):
+    total: int
+    active: int
+    inactive: int
+    disabled: int
+    expired: int
+    limited: int
+    has_revoked: int
+    has_reseted: int
+    total_removed: int
+    total_usage: int

guardcoreapi-0.3.0.dev20251113215748.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: guardcoreapi
+Version: 0.3.0.dev20251113215748
+Summary: Guard Management Core Api Python lib
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.13.1
+Requires-Dist: pydantic>=2.12.3
+Dynamic: license-file

guardcoreapi-0.3.0.dev20251113215748.dist-info/RECORD

@@ -0,0 +1,16 @@
+guardcoreapi/__init__.py,sha256=GohrmPFFH_Bfa5Ex3n0u-c4RjU47KbmoBYi38k8S_NI,62
+guardcoreapi/manager.py,sha256=kpQmyathhP6Ye7-AOC08tfOQJ7ST22kzEnwCST1lQTc,20017
+guardcoreapi/core/__init__.py,sha256=QJhZCPZui7zDpnQJbmWZsEijiAAP3rglUZb_w6E61_M,381
+guardcoreapi/core/exceptions.py,sha256=KbmdV8p31gSlKXjmJoW3lR9wGOQSvaaZKl9oGb7qlFI,555
+guardcoreapi/core/request.py,sha256=YHW2CB5MBA0geBsad4XtjcuhaZORzr2dE1Z5j_MfjQQ,4436
+guardcoreapi/types/__init__.py,sha256=z_PjXR-tCAOhJhNNa7s6S3l7lGglxNJ76wvTqrDC4fM,1587
+guardcoreapi/types/admins.py,sha256=trhhEAw2PbKYlkPL41vwglaRLrarDCYSzoiMibZnmRM,3107
+guardcoreapi/types/nodes.py,sha256=U4uCTm2TYETysceN_5ap4dP2if6sIUyEnavCvzlNpUo,1075
+guardcoreapi/types/services.py,sha256=3lpP76Q9iij2zSEXutDg1IatIslLokQ-DNPvSdckRCQ,369
+guardcoreapi/types/stats.py,sha256=gFeIgRB-8dtqbdsLwI5NZ3PeDnNWsR-LLg9vjZQljFk,2738
+guardcoreapi/types/subscriptions.py,sha256=gWoOwm_sARjVvd6Wut8zb4uVGaZCaUcATFRdcdo2VrY,1544
+guardcoreapi-0.3.0.dev20251113215748.dist-info/licenses/LICENSE,sha256=BPTJfvegcaek6E2PQ2rViLbxbfB1AbjIauxVQWo5Od4,1062
+guardcoreapi-0.3.0.dev20251113215748.dist-info/METADATA,sha256=BQbPkvLyq-UcO9SWL55z5Zhg7gnG_TOOg_hX3AvF6BY,291
+guardcoreapi-0.3.0.dev20251113215748.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+guardcoreapi-0.3.0.dev20251113215748.dist-info/top_level.txt,sha256=ArZR_iOVG8XvUCTMHioVgKI8CkJOX_yH8t7898OXBF8,13
+guardcoreapi-0.3.0.dev20251113215748.dist-info/RECORD,,

guardcoreapi-0.3.0.dev20251113215748.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

guardcoreapi-0.3.0.dev20251113215748.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Erfan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

guardcoreapi-0.3.0.dev20251113215748.dist-info/top_level.txt

@@ -0,0 +1 @@
+guardcoreapi