Python-3xui 0.0.1__py3-none-any.whl

python_3xui/endpoints.py

@@ -0,0 +1,361 @@
+import json
+from datetime import datetime, UTC
+from typing import Generic, Literal, List, Dict
+
+from httpx import Response
+from pydantic import ValidationError
+from pydantic.main import ModelT
+
+from . import models
+from .api import XUIClient
+from .models import Inbound, SingleInboundClient
+from .util import JsonType
+
+
+class BaseEndpoint(Generic[ModelT]):
+    """Base class for API endpoint handlers.
+
+    Provides common functionality for making API requests to the 3X-UI panel.
+
+    Attributes:
+        _url: The base URL path for this endpoint group.
+        client: Reference to the XUIClient instance.
+    """
+    _url: str
+
+    def __init__(self, client: "XUIClient") -> None:
+        self.client = client
+
+    async def _simple_get(self, caller_endpoint: str) -> JsonType:
+        """Perform a simple GET request and return the response object.
+
+        Args:
+            caller_endpoint: The endpoint path to request. If it doesn't start
+                with the base URL, the base URL will be prepended.
+
+        Returns:
+            The 'obj' field from the JSON response.
+
+        Raises:
+            RuntimeError: If the response status code is not 200.
+        """
+        endpoint_url: str = caller_endpoint
+        if self._url not in caller_endpoint:
+            endpoint_url = f"{self._url}{caller_endpoint}"
+        resp = await self.client.safe_get(endpoint_url)
+        if resp.status_code == 200:
+            resp_json = resp.json()
+            return resp_json["obj"]
+        else:
+            raise RuntimeError(f"Error: wrong status code {resp.status_code}")
+
+
+class Server(BaseEndpoint):
+    """Handler for server-related API endpoints.
+
+    Provides methods for generating cryptographic keys and UUIDs.
+
+    Endpoints:
+        - /panel/api/server/getNewUUID
+        - /panel/api/server/getNewX25519Cert
+        - /panel/api/server/getNewmldsa65
+        - /panel/api/server/getNewmlkem768x
+    """
+    _url = "panel/api/server"
+
+    async def new_uuid(self) -> str:
+        """Generate a new UUID from the server.
+
+        Returns:
+            A new UUID string.
+        """
+        endpoint = "/getNewUUID"
+        resp_json = await self._simple_get(endpoint)
+        return resp_json["uuid"]
+
+    async def new_x25519(self) -> dict[Literal["privateKey", "publicKey"], str]:
+        """Generate a new X25519 key pair.
+
+        Returns:
+            A dictionary containing 'privateKey' and 'publicKey' strings.
+        """
+        endpoint = "/getNewX25519Cert"
+        resp_json = await self._simple_get(endpoint)
+        return resp_json
+
+    async def new_mldsa65(self) -> dict[Literal["verify", "seed"], str]:
+        """Generate a new ML-DSA-65 post-quantum key pair.
+
+        ML-DSA-65 is a post-quantum signature algorithm.
+
+        Returns:
+            A dictionary containing 'verify' (public key) and 'seed' values.
+        """
+        endpoint = "/getNewmldsa65"
+        resp_json = await self._simple_get(endpoint)
+        return resp_json
+
+    async def new_mlkem768(self) -> dict[Literal["client", "seed"], str]:
+        """Generate a new ML-KEM-768 post-quantum key pair.
+
+        ML-KEM-768 is a post-quantum key encapsulation mechanism.
+
+        Returns:
+            A dictionary containing 'client' and 'seed' values.
+        """
+        endpoint = "/getNewmlkem768x"
+        resp_json = await self._simple_get(endpoint)
+        return resp_json
+
+
+class Inbounds(BaseEndpoint):
+    """Handler for inbound-related API endpoints.
+
+    Provides methods for retrieving inbound configurations.
+
+    Endpoints:
+        - /panel/api/inbounds/list
+        - /panel/api/inbounds/get/{id}
+    """
+    _url = "panel/api/inbounds"
+
+    async def get_all(self) -> List[Inbound]:
+        """Retrieve all inbounds from the server.
+
+        Returns:
+            A list of Inbound model instances.
+        """
+        endpoint = "/list"
+        json = await self._simple_get(f"{endpoint}")
+        inbounds = Inbound.from_list(json, client=self.client)
+        return inbounds
+
+    async def get_specific_inbound(self, id) -> Inbound:
+        """Retrieve a specific inbound by ID.
+
+        Args:
+            id: The ID of the inbound to retrieve.
+
+        Returns:
+            An Inbound model instance for the specified ID.
+        """
+        endpoint = f"/get/{id}"
+        json = await self._simple_get(f"{endpoint}")
+        inbound = Inbound(client=self.client, **json)
+        return inbound
+
+
+class Clients(BaseEndpoint):
+    """Handler for client-related API endpoints.
+
+    Provides methods for retrieving, adding, updating, and deleting clients.
+
+    Endpoints:
+        - /panel/api/inbounds/getClientTraffics/{email}
+        - /panel/api/inbounds/getClientTrafficsById/{uuid}
+        - /panel/api/inbounds/addClient
+        - /panel/api/inbounds/updateClient/{uuid}
+        - /panel/api/inbounds/delDepletedClients/{inbound_id}
+        - /panel/api/inbounds/{inbound_id}/delClient/{email|uuid}
+    """
+    _url = "panel/api/inbounds/"
+
+    #although it's the same url, they should be differentiated
+
+    async def get_client_with_email(self, email: str) -> models.ClientStats:
+        """Retrieve client statistics by email.
+
+        Args:
+            email: The client's email identifier.
+
+        Returns:
+            A ClientStats model instance with the client's statistics.
+        """
+        endpoint = f"getClientTraffics/{email}"
+        resp = await self._simple_get(endpoint)
+        return models.ClientStats.model_validate(resp)
+
+    async def get_client_with_uuid(self, uuid: str) -> List[models.ClientStats]:
+        """Retrieve client statistics by UUID.
+
+        Args:
+            uuid: The client's unique identifier.
+
+        Returns:
+            A list of ClientStats model instances matching the UUID.
+        """
+        endpoint = f"getClientTrafficsById/{uuid}"
+        resp = await self._simple_get(endpoint)
+        client_stats = models.ClientStats.from_list(resp, client=self.client)
+        return client_stats
+
+
+    async def add_client(self, client: models.InboundClients | models.SingleInboundClient | Dict,
+                         inbound_id: int | None = None) -> Response:
+        """Add a new client to an inbound.
+
+        Args:
+            client: The client to add. Can be:
+                - A dict (will be parsed as JSON)
+                - A SingleInboundClient (requires inbound_id)
+                - An InboundClients object
+            inbound_id: The ID of the inbound to add the client to.
+                Required if client is a SingleInboundClient.
+
+        Returns:
+            The HTTP response from the API.
+
+        Raises:
+            ValueError: If a single client is provided without an inbound_id.
+            TypeError: If the client type is not supported.
+        """
+        endpoint = f"addClient"
+        if isinstance(client, Dict):
+            try:
+                client = str(client)
+                final = models.InboundClients.model_validate_json(client)
+            except ValidationError:
+                # if there is in fact an error, I want it to raise
+                tmp = models.SingleInboundClient.model_validate_json(client)
+                if inbound_id:
+                    final = models.InboundClients(id=inbound_id,
+                                                  settings=models.InboundClients.Settings(clients=[tmp]))
+                else:
+                    raise ValueError("A single client was provided to be added but no parent inbound id")
+        elif isinstance(client, models.SingleInboundClient):
+            final = models.InboundClients(id=inbound_id,
+                                          settings=models.InboundClients.Settings(clients=[client]))
+        elif isinstance(client, models.InboundClients):
+            final = client
+            if inbound_id:
+                final.parent_id = inbound_id
+        else:
+            raise TypeError
+        # send request
+        
+        
+        data = final.model_dump(by_alias=True)
+        
+        
+        
+        resp = await self.client.safe_post(f"{self._url}{endpoint}", data=data)
+
+        #YOU NEED TO PASS SETTINGS AS A STRING, NOT AS A DICT, YOU FUCKING DUMBASS!
+        
+        
+        return resp
+
+    async def _request_update_client(self, client: models.InboundClients | models.SingleInboundClient,
+                                     inbound_id: int | None = None,
+                                     *, original_uuid: str | None = None) -> Response:
+        """Request to update an existing client.
+
+        Args:
+            client: The client data to update. Can be:
+                - A SingleInboundClient (requires inbound_id)
+                - An InboundClients object (with one client)
+            inbound_id: The ID of the inbound the client belongs to.
+                Required if client is a SingleInboundClient.
+            original_uuid: The original UUID of the client to update.
+                Required if client is a SingleInboundClient.
+
+        Returns:
+            The HTTP response from the API.
+        """
+        if isinstance(client, models.SingleInboundClient):
+            if inbound_id is None:
+                raise ValueError("Provide a parent inbound ID or pass models.InboundClients")
+            client = models.InboundClients(parent_id=inbound_id,
+                                           settings=models.InboundClients.Settings(clients=[client]))
+        else:
+            if len(client.settings.clients) != 1:
+                raise ValueError(f"You can only update 1 client at a time, instead got {len(client.settings.clients)}")
+
+        _endpoint = f"updateClient/{original_uuid if original_uuid else client.settings.clients[0].uuid}"
+        resp = await self.client.safe_post(f"{self._url}{_endpoint}", json=client.model_dump_json())
+
+        return resp
+
+    async def update_single_client(self, existing_client: SingleInboundClient, inbound_id: int, /, *,
+                                   security: str | None = None,
+                                   password: str | None = None,
+                                   flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"] | None = None,
+                                   email: str | None = None,
+                                   limit_ip: int | None = None,
+                                   limit_gb: int | None = None,
+                                   expiry_time: models.timestamp | None = None,
+                                   enable: bool | None = None,
+                                   sub_id: str | None = None,
+                                   comment: str | None = None,
+                                   ):
+        """Update an existing client's details.
+
+        Args:
+            existing_client: The existing client object to update.
+            inbound_id: The ID of the inbound the client belongs to.
+            security: New security settings (optional).
+            password: New password (optional).
+            flow: New flow settings (optional).
+            email: New email address (optional).
+            limit_ip: New IP limit (optional).
+            limit_gb: New GB limit (optional).
+            expiry_time: New expiry time (optional).
+            enable: New enable status (optional).
+            sub_id: New subscription ID (optional).
+            comment: New comment (optional).
+
+        Returns:
+            The HTTP response from the API.
+        """
+        # Collect only the arguments that were explicitly provided (not None)
+        changes = {k: v for k, v in locals().items()
+                   if k != 'self' and k != 'existing_client' and v is not None}
+        # Rename sub_id to subscription_id if needed
+        if 'sub_id' in changes:
+            changes['subscription_id'] = changes.pop('sub_id')
+        changes["updated_at"] = int(datetime.now(UTC).timestamp())
+        updated = existing_client.model_copy(update=changes)
+
+        resp = await self._request_update_client(updated, inbound_id)
+        return resp
+
+    async def delete_expired_clients(self, inbound_id: int) -> Response:
+        """Delete expired clients from an inbound.
+
+        Args:
+            inbound_id: The ID of the inbound to delete expired clients from.
+
+        Returns:
+            The HTTP response from the API.
+        """
+        _endpoint = f"delDepletedClients/"
+        resp = await self.client.safe_post(f"{self._url}{_endpoint}{inbound_id}")
+        return resp
+
+    async def delete_client_by_email(self, email: str, inbound_id: int) -> Response:
+        """Delete a client by email.
+
+        Args:
+            email: The email of the client to delete.
+            inbound_id: The ID of the inbound the client belongs to.
+
+        Returns:
+            The HTTP response from the API.
+        """
+        _endpoint = f"{inbound_id}/delClient/{email}"
+        resp = await self.client.safe_post(f"{self._url}{_endpoint}")
+        return resp
+
+    async def delete_client_by_uuid(self, uuid: str, inbound_id: int) -> Response:
+        """Delete a client by UUID.
+
+        Args:
+            uuid: The UUID of the client to delete.
+            inbound_id: The ID of the inbound the client belongs to.
+
+        Returns:
+            The HTTP response from the API.
+        """
+        _endpoint = f"{inbound_id}/delClient/{uuid}"
+        resp = await self.client.safe_post(f"{self._url}{_endpoint}")
+        return resp

python_3xui/models.py

@@ -0,0 +1,277 @@
+import json
+from types import NoneType
+from datetime import datetime, UTC
+from typing import Union, Optional, TypeAlias, Any, Annotated, Literal, List, Dict
+
+from pydantic import field_validator, Field, field_serializer
+import pydantic
+
+from . import base_model
+from .util import JsonType
+
+timestamp: TypeAlias = int
+ip_address: TypeAlias = str
+json_string: TypeAlias = str
+
+def exclude_if_none(field) -> bool:
+    """Check if a field value is None for exclusion purposes.
+
+    Args:
+        field: The field value to check.
+
+    Returns:
+        True if the field is None, False otherwise.
+    """
+    if field is None:
+        return True
+    return False
+
+class SingleInboundClient(pydantic.BaseModel):
+    """Represents a single client within a VLESS/VMess inbound.
+
+    This model represents an individual VPN client with all its configuration
+    settings including traffic limits, expiry, and authentication details.
+
+    Attributes:
+        uuid: The unique identifier for the client (aliased as 'id' in API).
+        security: The security protocol used by the client.
+        password: The client's password for authentication.
+        flow: The VLESS flow type controlling connection behavior.
+        email: The client's email identifier.
+        limit_ip: Maximum number of simultaneous IP connections.
+        limit_gb: Total data limit in gigabytes.
+        expiry_time: Client expiry time as UNIX timestamp (0 = no expiry).
+        enable: Whether the client is enabled.
+        tg_id: Associated Telegram ID for notifications.
+        subscription_id: Subscription identifier for URL generation.
+        comment: Admin notes or comments for the client.
+        created_at: Timestamp of client creation.
+        updated_at: Timestamp of last client update.
+    """
+    uuid:  Annotated[str, Field(alias="id")] #yes they really did that...
+    security: str = ""
+    password: str = ""
+    flow: Literal["", "xtls-rprx-vision", "xtls-rprx-vision-udp443"]
+    email: Annotated[str, Field(alias="email")]
+    limit_ip: Annotated[int, Field(alias="limitIp")] = 20
+    limit_gb: Annotated[int, Field(alias="totalGB")] # total flow
+    expiry_time: Annotated[timestamp, Field(alias="expiryTime")] = 0
+    enable: bool = True
+    tg_id: Annotated[Union[int, str], Field(alias="tgId")] = ""
+    subscription_id: Annotated[str, Field(alias="subId")]
+    comment: str = ""
+    created_at: Annotated[timestamp, Field(default_factory=(lambda: int(datetime.now(UTC).timestamp())))]
+    updated_at: Annotated[timestamp, Field(default_factory=(lambda: int(datetime.now(UTC).timestamp())))]
+
+class InboundClients(pydantic.BaseModel):
+    """Represents a collection of clients for an inbound connection.
+
+    This model is used when adding or updating clients on an inbound,
+    containing the parent inbound ID and the list of clients.
+
+    Attributes:
+        parent_id: The ID of the parent inbound (aliased as 'id').
+        settings: The settings object containing the client list.
+    """
+
+    class Settings(pydantic.BaseModel):
+        """Settings container for inbound clients.
+
+        Attributes:
+            clients: List of SingleInboundClient objects.
+        """
+        clients: list[SingleInboundClient]
+
+    parent_id: Annotated[int|None, Field(exclude_if=exclude_if_none, alias="id")] = None
+    settings: Settings
+
+    @field_serializer("settings")
+    def stringify_settings(self, value: Settings) -> str:
+        """Serialize the settings object to a JSON string.
+
+        The 3X-UI API expects settings as a JSON string, not an object.
+
+        Args:
+            value: The Settings object to serialize.
+
+        Returns:
+            A JSON string representation of the settings.
+        """
+        return json.dumps(value.model_dump(by_alias=True), ensure_ascii=False)
+
+
+#class InboundSettings(base_model.BaseModel):
+#     clients: list[Clients]
+#     decryption: str
+#     encryption: str
+#     selectedAuth: Annotated[Union[str|None], Field(exclude_if=exclude_if_none)] = None # "X25519, not Post-Quantum"
+#
+# "StreamSettings Stuff"
+#
+# class ExternalProxy(base_model.BaseModel):
+#     force_tls: Annotated[str, Field(alias="ForceTls")]
+#     dest: str
+#     port: int
+#     remark: str
+#
+# class StreamRequest(base_model.BaseModel):
+#     version: str
+#     method: str
+#     path: List[str]
+#     headers: dict[str, str|int]
+#
+# class StreamResponse(base_model.BaseModel):
+#     version: str
+#     status: int
+#     reason: str
+#     headers: dict[str, str|int]
+#
+# class TCPSettingsHeader(base_model.BaseModel):
+#     type: str
+#     request: Annotated[Optional[StreamRequest], Field(exclude_if=exclude_if_none)] = None
+#     response: Annotated[Optional[StreamRequest], Field(exclude_if=exclude_if_none)] = None
+#
+# class TCPSettings(base_model.BaseModel):
+#     accept_proxy_protocol: Annotated[bool, Field(alias="acceptProxyProtocol")]
+#
+# class SockOpt(base_model.BaseModel):
+#     acceptProxyProtocol: bool
+#     tcpFastOpen: bool
+#     mark: int
+#     tproxy: str
+#     tcpMptcp: bool
+#     penetrate: bool
+#     domainStrategy: str
+#     tcpMaxSeg: int
+#     dialerProxy: str
+#     tcpKeepAliveInterval: int
+#     tcpKeepAliveIdle: int
+#     tcpUserTimeout: int
+#     tcpcongestion: str
+#     V6Only: bool
+#     tcpWindowClamp: int
+#     interface: str
+#
+# class StreamSettings(base_model.BaseModel):
+#     network_type: Annotated[str, Field(alias="network")]
+#     security: str # none, reality, TLS
+#     external_proxy: Annotated[list[ExternalProxy], Field(alias="externalProxy")]
+#     tcp_settings: TCPSettings
+
+class ClientStats(base_model.BaseModel):
+    """Statistics and configuration for a VPN client.
+
+    This model represents client statistics returned by the 3X-UI API,
+    including traffic usage, expiry information, and connection details.
+
+    Attributes:
+        id: Internal database ID of the client record.
+        inboundId: The ID of the inbound this client belongs to.
+        enable: Whether the client is currently enabled.
+        email: The client's email identifier.
+        uuid: The client's unique identifier.
+        subId: The subscription ID for URL generation.
+        up: Total uploaded bytes.
+        down: Total downloaded bytes.
+        allTime: Total bytes transferred (up + down).
+        expiryTime: Client expiry time as UNIX timestamp.
+        total: Total data limit in bytes.
+        reset: Counter for traffic resets.
+        lastOnline: UNIX timestamp of last connection.
+    """
+    id: int
+    inboundId: int
+    enable: bool
+    email: str
+    uuid: str
+    subId: str
+    up: int  # bytes
+    down: int  # bytes
+    allTime: int  # bytes
+    expiryTime: timestamp  # UNIX timestamp
+    total: int
+    reset: int
+    lastOnline: timestamp
+
+
+class Inbound(base_model.BaseModel):
+    """Represents a VPN inbound connection configuration.
+
+    An inbound defines how VPN clients connect to the server, including
+    the protocol, port, traffic statistics, and client list.
+
+    Attributes:
+        id: The unique identifier for this inbound.
+        up: Total uploaded bytes through this inbound.
+        down: Total downloaded bytes through this inbound.
+        total: Total data limit in bytes.
+        allTime: Total bytes transferred (up + down).
+        remark: Human-readable name/description for the inbound.
+        enable: Whether the inbound is currently enabled.
+        expiryTime: Inbound expiry time as UNIX timestamp.
+        trafficReset: Traffic reset schedule ("Never", "Weekly", "Monthly", "Daily").
+        lastTrafficResetTime: UNIX timestamp of last traffic reset.
+        clientStats: List of client statistics, or None if no clients.
+        listen: The IP address the inbound listens on.
+        port: The port number the inbound listens on.
+        protocol: The VPN protocol (vless, vmess, trojan, shadowsocks, wireguard).
+        settings: JSON configuration for the inbound (auto-parsed from string).
+        streamSettings: JSON stream configuration (auto-parsed from string).
+        tag: Internal tag identifier for routing.
+        sniffing: JSON sniffing configuration (auto-parsed from string).
+    """
+    id: int
+    up: int  # bytes
+    down: int  # bytes
+    total: int  # bytes
+    allTime: int  # bytes
+    remark: str
+    enable: bool
+    expiryTime: timestamp  # UNIX timestamp
+    trafficReset: str  # "Never", "Weekly", "Monthly", "Daily"
+    lastTrafficResetTime: timestamp  # UNIX timestamp
+    clientStats: Union[list[ClientStats], None]
+    listen: str
+    port: int
+    protocol: Literal["vless", "vmess", "trojan", "shadowsocks", "wireguard"]  # note: there are some "deprecated" like wireguard
+    settings: Union[json_string, Dict[Any, Any]]  # JSON packed value, stringified
+    streamSettings: Union[json_string, Dict[Any, Any]]  # JSON packed value, stringified
+    tag: str
+    sniffing: Union[json_string, Dict[Any, Any]]  # JSON packed value, stringified
+
+    # noinspection PyNestedDecorators
+    @field_validator('settings', 'streamSettings', 'sniffing', mode='after')
+    @classmethod
+    def parse_json_fields(cls, value: str) -> JsonType|Literal[""]:
+        """Parse JSON string fields into dictionaries.
+
+        The 3X-UI API returns settings, streamSettings, and sniffing as
+        JSON strings. This validator automatically parses them into dicts.
+
+        Args:
+            value: The JSON string to parse, or empty string.
+
+        Returns:
+            Parsed dictionary, or empty string if input was empty.
+        """
+        if value == "":
+            return ""
+        return json.loads(value)
+
+    # noinspection PyNestedDecorators
+    @field_serializer("settings", "streamSettings", "sniffing")
+    @classmethod
+    def stringify_json_fields(cls, value: Dict|Literal[""]) -> str:
+        """Serialize dictionary fields back to JSON strings.
+
+        When sending data back to the API, these fields must be JSON strings.
+
+        Args:
+            value: The dictionary to serialize, or empty string.
+
+        Returns:
+            JSON string representation, or empty string if input was empty.
+        """
+        if value == "":
+            return ""
+        return json.dumps(value, ensure_ascii=False)