remnawave-api 1.0.0__tar.gz

remnawave_api-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 sm1ky
+
+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.

remnawave_api-1.0.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.3
+Name: remnawave_api
+Version: 1.0.0
+Summary: A Python SDK for interacting with the Remnawave API.
+License: MIT
+Author: sm1ky
+Author-email: sm1ky@forestsnet.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: orjson (>=3.10.15,<4.0.0)
+Requires-Dist: rapid-api-client (==0.6.0)
+Description-Content-Type: text/markdown
+
+# Remnawave SDK
+
+A Python SDK client for interacting with the [Remnawave API](https://remna.st).
+This library simplifies working with the API by providing convenient controllers, Pydantic models for requests and responses, and fast serialization with `orjson`.
+
+## ✨ Key Features
+
+- **Controller-based design**: Split functionality into separate controllers for flexibility. Use only what you need!
+- **Pydantic models**: Strongly-typed requests and responses for better reliability.
+- **Fast serialization**: Powered by `orjson` for efficient JSON handling.
+- **Modular usage**: Import individual controllers or the full SDK as needed.
+
+## 📦 Installation
+
+Currently, the SDK is available via Git. You can install it directly using `pip`:
+
+```bash
+pip install git+https://github.com/sm1ky/remnawave_api.git
+```
+
+---
+
+### Dependencies
+- `orjson` (>=3.10.15, <4.0.0)
+- `rapid-api-client` (==0.6.0)
+
+## 🚀 Usage
+
+Here’s a quick example to get you started:
+
+```python
+import os
+import asyncio
+
+from remnawave import RemnawaveSDK
+from remnawave.models import UsersResponseDto, UserResponseDto
+
+async def main():
+    # URL to your panel (ex. https://vpn.com or http://127.0.0.1:3000)
+    base_url: str = os.getenv("REMNAWAVE_BASE_URL")
+    # Bearer Token from panel (section: API Tokens) 
+    token: str = os.getenv("REMNAWAVE_TOKEN")
+
+    # Initialize the SDK
+    remnawave = RemnawaveSDK(base_url=base_url, token=token)
+
+    # Fetch all users
+    response: UsersResponseDto = await remnawave.users.get_all_users_v2()
+    total_users: int = response.total
+    users: list[UserResponseDto] = response.users
+    print("Total users: ", total_users)
+    print("List of users: ", users)
+
+    # Disable a specific user
+    test_uuid: str = "e4d3f3d2-4f4f-4f4f-4f4f-4f4f4f4f4f4f"
+    disabled_user: UserResponseDto = await remnawave.users.disable_user(test_uuid)
+    print("Disabled user: ", disabled_user)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 🧪 Running Tests
+
+To run the test suite, use Poetry:
+
+```bash
+poetry run pytest
+```
+
+## ❤️ About
+
+This SDK was originally developed by [@kesevone](https://github.com/kesevone) for integration with Remnawave's API.
+
+Maintained and extended by [@sm1ky](https://github.com/sm1ky).

remnawave_api-1.0.0/README.md

@@ -0,0 +1,77 @@
+# Remnawave SDK
+
+A Python SDK client for interacting with the [Remnawave API](https://remna.st).
+This library simplifies working with the API by providing convenient controllers, Pydantic models for requests and responses, and fast serialization with `orjson`.
+
+## ✨ Key Features
+
+- **Controller-based design**: Split functionality into separate controllers for flexibility. Use only what you need!
+- **Pydantic models**: Strongly-typed requests and responses for better reliability.
+- **Fast serialization**: Powered by `orjson` for efficient JSON handling.
+- **Modular usage**: Import individual controllers or the full SDK as needed.
+
+## 📦 Installation
+
+Currently, the SDK is available via Git. You can install it directly using `pip`:
+
+```bash
+pip install git+https://github.com/sm1ky/remnawave_api.git
+```
+
+---
+
+### Dependencies
+- `orjson` (>=3.10.15, <4.0.0)
+- `rapid-api-client` (==0.6.0)
+
+## 🚀 Usage
+
+Here’s a quick example to get you started:
+
+```python
+import os
+import asyncio
+
+from remnawave import RemnawaveSDK
+from remnawave.models import UsersResponseDto, UserResponseDto
+
+async def main():
+    # URL to your panel (ex. https://vpn.com or http://127.0.0.1:3000)
+    base_url: str = os.getenv("REMNAWAVE_BASE_URL")
+    # Bearer Token from panel (section: API Tokens) 
+    token: str = os.getenv("REMNAWAVE_TOKEN")
+
+    # Initialize the SDK
+    remnawave = RemnawaveSDK(base_url=base_url, token=token)
+
+    # Fetch all users
+    response: UsersResponseDto = await remnawave.users.get_all_users_v2()
+    total_users: int = response.total
+    users: list[UserResponseDto] = response.users
+    print("Total users: ", total_users)
+    print("List of users: ", users)
+
+    # Disable a specific user
+    test_uuid: str = "e4d3f3d2-4f4f-4f4f-4f4f-4f4f4f4f4f4f"
+    disabled_user: UserResponseDto = await remnawave.users.disable_user(test_uuid)
+    print("Disabled user: ", disabled_user)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 🧪 Running Tests
+
+To run the test suite, use Poetry:
+
+```bash
+poetry run pytest
+```
+
+## ❤️ About
+
+This SDK was originally developed by [@kesevone](https://github.com/kesevone) for integration with Remnawave's API.
+
+Maintained and extended by [@sm1ky](https://github.com/sm1ky).

remnawave_api-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "remnawave_api"
+version = "1.0.0"
+description = "A Python SDK for interacting with the Remnawave API."
+authors = [
+    {name = "sm1ky",email = "sm1ky@forestsnet.com"}
+]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "rapid-api-client (==0.6.0)",
+    "orjson (>=3.10.15,<4.0.0)",
+]
+
+[tool.poetry.group.test.dependencies]
+ruff = "^0.4.4"
+black = "^24.4.2"
+pytest = ">=8.0"
+pytest-asyncio = "^0.25.3"
+pytest-mock = ">=3.9"
+httpx = ">=0.27.2,<0.28.0"
+python-dotenv = "^1.0.1"
+pytz = "^2025.1"
+
+[tool.pytest.ini_options]
+addopts = [ "-n", "logical", "-ra", "--strict-config", "--strict-markers" ]
+testpaths = ["tests"]
+log_cli_level = "INFO"
+xfail_strict = true
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

remnawave_api-1.0.0/remnawave_api/__init__.py

@@ -0,0 +1,90 @@
+import logging
+from typing import Optional
+
+import httpx
+
+from remnawave_api.controllers import (
+    APITokensManagementController,
+    AuthController,
+    BandWidthStatsController,
+    HostsBulkActionsController,
+    HostsController,
+    InboundsBulkActionsController,
+    InboundsController,
+    KeygenController,
+    NodesController,
+    SubscriptionController,
+    SubscriptionsSettingsController,
+    SubscriptionsTemplateController,
+    SystemController,
+    UsersBulkActionsController,
+    UsersController,
+    UsersStatsController,
+    XrayConfigController,
+)
+
+
+class RemnawaveSDK:
+    def __init__(
+        self,
+        client: Optional[httpx.AsyncClient] = None,
+        base_url: Optional[str] = None,
+        token: Optional[str] = None,
+    ):
+        self._client = client
+        self._token = token
+        self.base_url = base_url
+
+        self._validate_params()
+
+        if self._client is None:
+            self._client = self._prepare_client()
+
+        self.api_tokens_management = APITokensManagementController(self._client)
+        self.auth = AuthController(self._client)
+        self.bandwidthstats = BandWidthStatsController(self._client)
+        self.hosts = HostsController(self._client)
+        self.hosts_bulk_actions = HostsBulkActionsController(self._client)
+        self.inbounds = InboundsController(self._client)
+        self.inbounds_bulk_actions = InboundsBulkActionsController(self._client)
+        self.keygen = KeygenController(self._client)
+        self.nodes = NodesController(self._client)
+        self.subscription = SubscriptionController(self._client)
+        self.subscriptions_settings = SubscriptionsSettingsController(self._client)
+        self.subscriptions_template = SubscriptionsTemplateController(self._client)
+        self.system = SystemController(self._client)
+        self.users = UsersController(self._client)
+        self.users_bulk_actions = UsersBulkActionsController(self._client)
+        self.users_stats = UsersStatsController(self._client)
+        self.xray_config = XrayConfigController(self._client)
+
+    def _validate_params(self) -> None:
+        if self._client is None:
+            if self.base_url is None or self._token is None:
+                raise ValueError(
+                    "base_url and token must be provided if client is not provided"
+                )
+        else:
+            if self.base_url is not None or self._token is not None:
+                logging.warning(
+                    "base_url and token will be ignored if client is provided"
+                )
+
+    def _prepare_client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            base_url=self._prepare_url(), headers=self._prepare_headers()
+        )
+
+    def _prepare_headers(self) -> dict:
+        if not self._token.startswith("Bearer "):
+            self._token = "Bearer " + self._token
+        return {"Authorization": self._token}
+
+    def _prepare_url(self) -> str:
+        if self.base_url.endswith("/"):
+            self.base_url[:-1]
+
+        if not self.base_url.endswith("/api"):
+            self.base_url += "/api"
+
+        return self.base_url

remnawave_api-1.0.0/remnawave_api/controllers/__init__.py

@@ -0,0 +1,37 @@
+from .api_tokens_management import APITokensManagementController
+from .auth import AuthController
+from .bandwidthstats import BandWidthStatsController
+from .hosts import HostsController
+from .hosts_bulk_actions import HostsBulkActionsController
+from .inbounds import InboundsController
+from .inbounds_bulk_actions import InboundsBulkActionsController
+from .keygen import KeygenController
+from .nodes import NodesController
+from .subscription import SubscriptionController
+from .subscriptions_settings import SubscriptionsSettingsController
+from .subscriptions_template import SubscriptionsTemplateController
+from .system import SystemController
+from .users import UsersController
+from .users_bulk_actions import UsersBulkActionsController
+from .users_stats import UsersStatsController
+from .xray_config import XrayConfigController
+
+__all__ = [
+    "APITokensManagementController",
+    "AuthController",
+    "BandWidthStatsController",
+    "HostsController",
+    "HostsBulkActionsController",
+    "InboundsController",
+    "InboundsBulkActionsController",
+    "KeygenController",
+    "NodesController",
+    "SubscriptionController",
+    "SubscriptionsSettingsController",
+    "SubscriptionsTemplateController",
+    "SystemController",
+    "UsersController",
+    "UsersBulkActionsController",
+    "UsersStatsController",
+    "XrayConfigController",
+]

remnawave_api-1.0.0/remnawave_api/controllers/api_tokens_management.py

@@ -0,0 +1,33 @@
+from typing import Annotated
+
+from httpx import Response
+from rapid_api_client import Path
+from rapid_api_client.annotations import PydanticBody
+
+from remnawave_api.models import CreateApiTokenRequestDto
+from remnawave_api.rapid import BaseController, delete, get, post
+
+
+class APITokensManagementController(BaseController):
+    @post("/tokens/create", response_class=Response)
+    async def create(
+        self,
+        body: Annotated[CreateApiTokenRequestDto, PydanticBody()],
+    ) -> Response:
+        """Create new API token"""
+        ...
+
+    @delete("/tokens/delete/{uuid}", response_class=Response)
+    async def delete(
+        self,
+        uuid: Annotated[str, Path(description="UUID of the API token")],
+    ) -> Response:
+        """Delete API token"""
+        ...
+
+    @get("/tokens", response_class=Response)
+    async def find_all(
+        self,
+    ) -> Response:
+        """Get all API tokens"""
+        ...

remnawave_api-1.0.0/remnawave_api/controllers/auth.py

@@ -0,0 +1,37 @@
+from typing import Annotated
+
+from rapid_api_client.annotations import PydanticBody
+
+from remnawave_api.models import (
+    LoginRequestDto,
+    LoginResponseDto,
+    RegisterRequestDto,
+    RegisterResponseDto,
+    StatusResponseDto,
+)
+from remnawave_api.rapid import BaseController, get, post
+
+
+class AuthController(BaseController):
+    @post("/auth/login", response_class=LoginResponseDto)
+    async def login(
+        self,
+        body: Annotated[LoginRequestDto, PydanticBody()],
+    ) -> LoginResponseDto:
+        """Login"""
+        ...
+
+    @post("/auth/register", response_class=RegisterResponseDto)
+    async def register(
+        self,
+        body: Annotated[RegisterRequestDto, PydanticBody()],
+    ) -> RegisterResponseDto:
+        """Register"""
+        ...
+
+    @get("/auth/status", response_class=StatusResponseDto)
+    async def get_status(
+        self,
+    ) -> StatusResponseDto:
+        """Get status"""
+        ...

remnawave_api-1.0.0/remnawave_api/controllers/bandwidthstats.py

@@ -0,0 +1,17 @@
+from typing import Annotated
+
+from rapid_api_client import Query
+
+from remnawave_api.models import NodesUsageResponseDto
+from remnawave_api.rapid import BaseController, get
+
+
+class BandWidthStatsController(BaseController):
+    @get("/nodes/usage/range", response_class=NodesUsageResponseDto)
+    async def get_nodes_usage_by_range(
+        self,
+        start: Annotated[str, Query(description="Start date in ISO format")],
+        end: Annotated[str, Query(description="End date in ISO format")],
+    ) -> NodesUsageResponseDto:
+        """Get Nodes Usage By Range"""
+        ...

remnawave_api-1.0.0/remnawave_api/controllers/hosts.py

@@ -0,0 +1,64 @@
+from typing import Annotated, List
+
+from rapid_api_client import Path
+from rapid_api_client.annotations import PydanticBody
+
+from remnawave_api.models import (
+    CreateHostRequestDto,
+    DeleteHostResponseDto,
+    HostResponseDto,
+    HostsResponseDto,
+    ReorderHostRequestDto,
+    ReorderHostResponseDto,
+    UpdateHostRequestDto,
+)
+from remnawave_api.rapid import AttributeBody, BaseController, delete, get, post
+
+
+class HostsController(BaseController):
+    @post("/hosts/create", response_class=HostResponseDto)
+    async def create_host(
+        self,
+        body: Annotated[CreateHostRequestDto, PydanticBody()],
+    ) -> HostResponseDto:
+        """Create Host"""
+        ...
+
+    @post("/hosts/update", response_class=HostResponseDto)
+    async def update_host(
+        self,
+        body: Annotated[UpdateHostRequestDto, PydanticBody()],
+    ) -> HostResponseDto:
+        """Update Host"""
+        ...
+
+    @get("/hosts/all", response_class=HostsResponseDto)
+    async def get_all_hosts(
+        self,
+    ) -> HostsResponseDto:
+        """Get All Hosts"""
+        ...
+
+    @get("/hosts/get-one/{uuid}", response_class=HostResponseDto)
+    async def get_one_host(
+        self,
+        uuid: Annotated[str, Path(description="UUID of the host")],
+    ) -> HostResponseDto:
+        """Get One Host"""
+        ...
+
+    @post("/hosts/reorder", response_class=ReorderHostResponseDto)
+    async def reorder_hosts(
+        self,
+        hosts: Annotated[List[ReorderHostRequestDto], AttributeBody()],
+    ) -> ReorderHostResponseDto:
+        """Reorder Hosts"""
+        ...
+
+    @delete("/hosts/delete/{uuid}", response_class=DeleteHostResponseDto)
+    async def delete_host(
+        self,
+        uuid: Annotated[str, Path(description="UUID of the host")],
+    ) -> DeleteHostResponseDto:
+        """Delete Host"""
+        ...

remnawave_api-1.0.0/remnawave_api/controllers/hosts_bulk_actions.py

@@ -0,0 +1,60 @@
+from typing import Annotated, List
+from uuid import UUID
+
+from rapid_api_client import PydanticBody
+
+from remnawave_api.models import (
+    BulkDeleteHostsResponseDto,
+    BulkDisableHostsResponseDto,
+    BulkEnableHostsResponseDto,
+    SetInboundToManyHostsRequestDto,
+    SetInboundToManyHostsResponseDto,
+    SetPortToManyHostsResponseDto,
+)
+from remnawave_api.rapid import AttributeBody, BaseController, post
+
+
+class HostsBulkActionsController(BaseController):
+    @post("/hosts/bulk/delete", response_class=BulkDeleteHostsResponseDto)
+    async def delete_hosts(
+        self,
+        uuids: Annotated[List[UUID], AttributeBody()],
+    ) -> BulkDeleteHostsResponseDto:
+        """Delete many hosts"""
+        ...
+
+    @post("/hosts/bulk/disable", response_class=BulkDisableHostsResponseDto)
+    async def disable_hosts(
+        self,
+        uuids: Annotated[List[UUID], AttributeBody()],
+    ) -> BulkDisableHostsResponseDto:
+        """Disable many hosts"""
+        ...
+
+    @post("/hosts/bulk/enable", response_class=BulkEnableHostsResponseDto)
+    async def enable_hosts(
+        self,
+        uuids: Annotated[List[UUID], AttributeBody()],
+    ) -> BulkEnableHostsResponseDto:
+        """Enable many hosts"""
+        ...
+
+    @post(
+        "/hosts/bulk/set-inbound",
+        response_class=SetInboundToManyHostsResponseDto,
+    )
+    async def set_inbound_to_hosts(
+        self,
+        body: Annotated[SetInboundToManyHostsRequestDto, PydanticBody()],
+    ) -> SetInboundToManyHostsResponseDto:
+        """Set inbound to many hosts"""
+        ...
+
+    @post("/hosts/bulk/set-port", response_class=SetPortToManyHostsResponseDto)
+    async def set_port_to_hosts(
+        self,
+        uuids: Annotated[List[UUID], AttributeBody()],
+        port: Annotated[float, AttributeBody()],
+    ) -> SetPortToManyHostsResponseDto:
+        """Set port to many hosts"""
+        ...

remnawave_api-1.0.0/remnawave_api/controllers/inbounds.py

@@ -0,0 +1,18 @@
+from remnawave_api.models import FullInboundsResponseDto, InboundsResponseDto
+from remnawave_api.rapid import BaseController, get
+
+
+class InboundsController(BaseController):
+    @get("/inbounds", response_class=InboundsResponseDto)
+    async def get_inbounds(
+        self,
+    ) -> InboundsResponseDto:
+        """Get Inbounds"""
+        ...
+
+    @get("/inbounds/full", response_class=FullInboundsResponseDto)
+    async def get_full_inbounds(
+        self,
+    ) -> FullInboundsResponseDto:
+        """Get Full Inbounds"""
+        ...

remnawave_api-1.0.0/remnawave_api/controllers/inbounds_bulk_actions.py

@@ -0,0 +1,50 @@
+from typing import Annotated
+from uuid import UUID
+
+from remnawave_api.models import (
+    AddInboundToNodesResponseDto,
+    AddInboundToUsersResponseDto,
+    RemoveInboundFromNodesResponseDto,
+    RemoveInboundFromUsersResponseDto,
+)
+from remnawave_api.rapid import AttributeBody, BaseController, post
+
+
+class InboundsBulkActionsController(BaseController):
+    @post("/inbounds/bulk/add-to-users", response_class=AddInboundToUsersResponseDto)
+    async def add_inbound_to_users(
+        self,
+        inbound_uuid: Annotated[UUID, AttributeBody()],
+    ) -> AddInboundToUsersResponseDto:
+        """Add Inbound To Users"""
+        ...
+
+    @post(
+        "/inbounds/bulk/remove-from-users",
+        response_class=RemoveInboundFromUsersResponseDto,
+    )
+    async def remove_inbound_from_users(
+        self,
+        inbound_uuid: Annotated[UUID, AttributeBody()],
+    ) -> RemoveInboundFromUsersResponseDto:
+        """Remove Inbound From Users"""
+        ...
+
+    @post("/inbounds/bulk/add-to-nodes", response_class=AddInboundToNodesResponseDto)
+    async def add_inbound_to_nodes(
+        self,
+        inbound_uuid: Annotated[UUID, AttributeBody()],
+    ) -> AddInboundToNodesResponseDto:
+        """Add Inbound To All Nodes"""
+        ...
+
+    @post(
+        "/inbounds/bulk/remove-from-nodes",
+        response_class=RemoveInboundFromNodesResponseDto,
+    )
+    async def remove_inbound_from_nodes(
+        self,
+        inbound_uuid: Annotated[UUID, AttributeBody()],
+    ) -> RemoveInboundFromNodesResponseDto:
+        """Remove Inbound From All Nodes"""
+        ...

remnawave_api-1.0.0/remnawave_api/controllers/keygen.py

@@ -0,0 +1,11 @@
+from remnawave_api.models import PubKeyResponseDto
+from remnawave_api.rapid import BaseController, get
+
+
+class KeygenController(BaseController):
+    @get("/keygen/get", response_class=PubKeyResponseDto)
+    async def generate_key(
+        self,
+    ) -> PubKeyResponseDto:
+        """Get Public Key"""
+        ...