asockslib 0.1.0__py3-none-any.whl

asockslib/models/__init__.py

@@ -0,0 +1,72 @@
+"""Pydantic models for ASocks API v2 requests and responses.
+
+Covers all 25 endpoints documented at https://docs.asocks.com/en/.
+
+Modules:
+    - :mod:`.enums` — port statuses and connection/proxy type identifiers.
+    - :mod:`.directory` — countries, states, cities, ASN entries.
+    - :mod:`.port` — proxy port models and list responses.
+    - :mod:`.requests` — bodies and query parameters for mutations.
+    - :mod:`.responses` — typed wrappers for API responses.
+
+Every model uses ``extra="allow"`` so that new fields added by the API
+are accepted without breaking existing code.
+"""
+
+from __future__ import annotations
+
+from asockslib.models.directory import (
+    ASNInfo,
+    ASNListResponse,
+    CityInfo,
+    CountryInfo,
+    StateInfo,
+)
+from asockslib.models.enums import (
+    AuthType,
+    ConnectionType,
+    ConnectionTypeId,
+    PortStatus,
+    ProxyType,
+    ProxyTypeId,
+    ServerPortType,
+)
+from asockslib.models.port import (
+    PortInfo,
+    PortListResponse,
+)
+from asockslib.models.requests import (
+    CreatePortRequest,
+    CreateTemplateRequest,
+    PortFilterParams,
+    UpdatePortRequest,
+    UpdateTemplateRequest,
+    WhitelistAddRequest,
+)
+from asockslib.models.responses import (
+    BalanceResponse,
+)
+
+__all__ = [
+    "ASNInfo",
+    "ASNListResponse",
+    "AuthType",
+    "BalanceResponse",
+    "CityInfo",
+    "ConnectionType",
+    "ConnectionTypeId",
+    "CountryInfo",
+    "CreatePortRequest",
+    "CreateTemplateRequest",
+    "PortFilterParams",
+    "PortInfo",
+    "PortListResponse",
+    "PortStatus",
+    "ProxyType",
+    "ProxyTypeId",
+    "ServerPortType",
+    "StateInfo",
+    "UpdatePortRequest",
+    "UpdateTemplateRequest",
+    "WhitelistAddRequest",
+]

asockslib/models/directory.py

@@ -0,0 +1,65 @@
+"""Directory (geo) models for the ASocks API v2.
+
+Country, state, city, and ASN data structures returned by the
+``/v2/dir/*`` endpoints.
+"""
+
+from __future__ import annotations
+
+from pydantic import AliasChoices, BaseModel, Field
+
+
+class CountryInfo(BaseModel, extra="allow"):
+    """Country entry from ``GET /v2/dir/countries``."""
+
+    id: int = Field(description="Internal country ID")
+    name: str = Field(default="", description="Full country name")
+    code: str = Field(
+        default="",
+        description="ISO country code (e.g. US, DE)",
+        validation_alias=AliasChoices("code", "short_name"),
+    )
+
+    @property
+    def short_name(self) -> str:
+        """Alias for :pyattr:`code` (backward-compatible)."""
+        return self.code
+
+
+class StateInfo(BaseModel, extra="allow"):
+    """State/region entry from ``GET /v2/dir/states``."""
+
+    id: int = Field(description="Internal state ID")
+    name: str = Field(default="", description="State/region name")
+    dir_country_id: int | None = Field(default=None, description="Parent country ID")
+
+
+class CityInfo(BaseModel, extra="allow"):
+    """City entry from ``GET /v2/dir/cities``."""
+
+    id: int = Field(description="Internal city ID")
+    name: str = Field(default="", description="City name")
+    dir_country_id: int | None = Field(default=None, description="Parent country ID")
+    dir_state_id: int | None = Field(default=None, description="Parent state ID")
+
+
+class ASNInfo(BaseModel, extra="allow"):
+    """ASN (Autonomous System Number) entry from ``GET /v2/dir/asns``."""
+
+    asn: int = Field(description="Autonomous System Number")
+    name: str = Field(default="", description="ISP / provider name")
+
+
+class ASNListResponse(BaseModel, extra="allow"):
+    """Paginated response for ``GET /v2/dir/asns``."""
+
+    data: list[ASNInfo] = Field(default_factory=list[ASNInfo], description="ASN entries")
+    current_page: int = Field(default=1, description="Current page number")
+    per_page: int = Field(default=1000, description="Items per page")
+    total: int = Field(default=0, description="Total number of ASN entries")
+    last_page: int = Field(default=1, description="Last page number")
+
+    @property
+    def items(self) -> list[ASNInfo]:
+        """Alias for ``data``."""
+        return self.data

asockslib/models/enums.py

@@ -0,0 +1,65 @@
+"""Enum types for the ASocks API v2.
+
+Centralizes all enumeration types used across the library:
+port statuses, proxy types, connection types, and identifiers.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum, StrEnum
+
+
+class PortStatus(IntEnum):
+    """Port status codes used by the ASocks API."""
+
+    ACTIVE = 1
+    INACTIVE = 0
+    EXPIRED = 2
+
+
+class ProxyType(StrEnum):
+    """Proxy category."""
+
+    RESIDENTIAL = "residential"
+    MOBILE = "mobile"
+    CORPORATE = "corporate"
+
+
+class ConnectionType(StrEnum):
+    """Connection mode for a proxy port."""
+
+    KEEP_PROXY = "keep-proxy"
+    KEEP_CONNECTION = "keep-connection"
+    ROTATE_CONNECTION = "rotate-connection"
+    KEEP_CONNECTION_LOW_TRUST = "keep-connection-low-trust"
+
+
+class AuthType(StrEnum):
+    """Authentication method."""
+
+    LOGIN_PASSWORD = "login-and-password"
+    IP_WHITELIST = "ip-whitelist"
+
+
+class ProxyTypeId(IntEnum):
+    """Numeric proxy-type identifiers for API requests."""
+
+    RESIDENTIAL = 1
+    ALL = 2
+    MOBILE = 3
+    CORPORATE = 4
+
+
+class ConnectionTypeId(IntEnum):
+    """Numeric connection-type identifiers for API requests."""
+
+    KEEP_PROXY = 1
+    KEEP_CONNECTION = 2
+    ROTATE_CONNECTION = 3
+
+
+class ServerPortType(IntEnum):
+    """Server port type."""
+
+    SHARED = 0
+    DEDICATED = 1

asockslib/models/port.py

@@ -0,0 +1,187 @@
+"""Port models for the ASocks API v2.
+
+Defines :class:`PortInfo` (single proxy port) and
+:class:`PortListResponse` (paginated port list wrapper).
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, cast
+
+from beartype import beartype
+from pydantic import AliasChoices, BaseModel, Field, field_validator, model_validator
+
+from asockslib.models.enums import PortStatus
+
+
+class PortInfo(BaseModel, extra="allow"):
+    """A single proxy port returned by the API.
+
+    Produced by ``GET /v2/proxy/ports``, ``GET /v2/proxy/port-info``
+    and ``POST /v2/proxy/create-port``.
+
+    Attributes:
+        id: Unique port identifier.
+        host: Proxy server address.
+        port: Port number.
+        login: Authentication login.
+        password: Authentication password.
+        protocol: Proxy protocol (``socks5``, ``http``, …).
+        proxy_type: Proxy category.
+        country_code: ISO country code.
+        status: Port status code (see :class:`PortStatus`).
+
+    Example::
+
+        print(port.proxy_url)   # socks5://user:pass@host:10001
+        print(port.is_active)   # True
+    """
+
+    id: int = Field(description="Unique port identifier")
+    host: str = Field(
+        default="",
+        description="Proxy host address",
+        validation_alias=AliasChoices("host", "server"),
+    )
+    port: int = Field(default=0, description="Proxy port number")
+    login: str = Field(default="", description="Authentication login")
+    password: str = Field(default="", description="Authentication password")
+    protocol: str = Field(default="socks5", description="Proxy protocol")
+    proxy_type: str | None = Field(default=None, description="Proxy type category")
+    country: str = Field(default="", description="Country name")
+    country_code: str = Field(default="", description="ISO country code")
+    city: str = Field(default="", description="City name")
+    state: str = Field(default="", description="State name")
+    status: int | str = Field(default=1, description="Port status code")
+    name: str = Field(default="", description="User-defined port name")
+    asn: int | None = Field(default=None, description="Autonomous System Number")
+    external_ip: str = Field(default="", description="External IP address")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_none_strings(cls, data: dict[str, object] | object) -> dict[str, object] | object:
+        """Coerce ``None`` values to empty strings for str fields."""
+        if not isinstance(data, dict):
+            return data
+        data = cast("dict[str, object]", data)
+        _str_fields = (
+            "host",
+            "login",
+            "password",
+            "protocol",
+            "country",
+            "country_code",
+            "city",
+            "state",
+            "name",
+            "external_ip",
+        )
+        for fld in _str_fields:
+            if fld in data and data[fld] is None:
+                data[fld] = ""
+        return data
+
+    expires_at: str | None = Field(default=None, description="Expiration timestamp")
+    created_at: str | None = Field(default=None, description="Creation timestamp")
+    ttl: int | None = Field(default=None, description="Time-to-live in days")
+    traffic_limit: float | None = Field(default=None, description="Traffic limit in GB")
+    traffic_used: float | None = Field(default=None, description="Traffic used in GB")
+    type_id: int | None = Field(default=None, description="Connection type ID")
+    proxy_type_id: int | None = Field(default=None, description="Proxy type ID")
+    server_port_type_id: int | None = Field(default=None, description="Server port type ID")
+
+    _STATUS_MAP: ClassVar[dict[str, int]] = {
+        "active": 1,
+        "inactive": 0,
+        "expired": 2,
+        "stopped": 0,
+        "error": 0,
+    }
+
+    @field_validator("status", mode="before")
+    @classmethod
+    def _coerce_status(cls, v: object) -> int:
+        """Accept both int and string status from the API.
+
+        Typed ``object`` (not ``int | str``): a ``mode="before"`` validator
+        receives the raw, not-yet-validated JSON value, which may be any type.
+        """
+        if isinstance(v, int):
+            return v
+        if isinstance(v, str):
+            low = v.strip().lower()
+            if low.isdigit():
+                return int(low)
+            return cls._STATUS_MAP.get(low, 0)
+        return int(cast("int", v))
+
+    @property
+    def proxy_url(self) -> str:
+        """Full proxy URL (``protocol://login:password@host:port``)."""
+        auth = f"{self.login}:{self.password}@" if self.login else ""
+        proto = self.protocol or "socks5"
+        return f"{proto}://{auth}{self.host}:{self.port}"
+
+    @beartype
+    def format_with_template(self, template: str) -> str:
+        """Format the proxy using a template string.
+
+        Supported placeholders: ``{protocol}``, ``{id}``, ``{login}``,
+        ``{password}``, ``{ip}``, ``{port}``, ``{refresh_link}``,
+        ``{name}``, ``{external_ip}``.
+
+        Example::
+
+            port.format_with_template("{ip}:{port}:{login}:{password}")
+            # "1.2.3.4:8080:u:p"
+        """
+        refresh = f"https://api.asocks.com/v2/proxy/refresh-ip/{self.id}"
+        return (
+            template.replace("{protocol}", self.protocol or "socks5")
+            .replace("{id}", str(self.id))
+            .replace("{login}", self.login)
+            .replace("{password}", self.password)
+            .replace("{ip}", self.host)
+            .replace("{port}", str(self.port))
+            .replace("{refresh_link}", refresh)
+            .replace("{name}", self.name)
+            .replace("{external_ip}", self.external_ip)
+        )
+
+    @property
+    def is_active(self) -> bool:
+        """``True`` when the port status is :attr:`PortStatus.ACTIVE`."""
+        return self.status == PortStatus.ACTIVE  # type: ignore[comparison-overlap]
+
+
+class PortListResponse(BaseModel, extra="allow"):
+    """Response wrapper for ``GET /v2/proxy/ports``.
+
+    The API may return either a flat list or a paginated envelope
+    (``{data: [...], total: N, ...}``); this model handles both.
+    """
+
+    success: bool = Field(default=True)
+    message: list[PortInfo] | dict[str, object] = Field(default_factory=list[PortInfo])
+
+    @property
+    def items(self) -> list[PortInfo]:
+        """Port list regardless of the envelope format."""
+        if isinstance(self.message, list):
+            return self.message
+        data = self.message.get("data", [])
+        if isinstance(data, list):
+            return [PortInfo.model_validate(d) for d in cast("list[object]", data)]
+        return []
+
+    @property
+    def total(self) -> int:
+        """Total number of ports."""
+        if isinstance(self.message, dict):
+            raw_total = self.message.get("total", 0)
+            if isinstance(raw_total, int):
+                return raw_total
+            if isinstance(raw_total, str) and raw_total.strip().lstrip("-").isdigit():
+                return int(raw_total)
+            return 0
+        return len(self.message)

asockslib/models/requests.py

@@ -0,0 +1,89 @@
+"""Request models for the ASocks API v2.
+
+Bodies and query parameters for mutations: port creation, updates,
+template management, and whitelist operations.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class CreatePortRequest(BaseModel):
+    """Body for ``POST /v2/proxy/create-port``.
+
+    Example::
+
+        req = CreatePortRequest(country_code="US", count=5, ttl=7)
+    """
+
+    country_code: str = Field(default="", description="ISO country code (e.g. US)")
+    state: str = Field(default="", description="State name")
+    city: str = Field(default="", description="City name")
+    asn: int | None = Field(default=None, description="Autonomous System Number")
+    type_id: int = Field(default=1, description="Connection type ID")
+    proxy_type_id: int = Field(default=1, description="Proxy type ID")
+    name: str = Field(default="", description="Port display name")
+    server_port_type_id: int = Field(
+        default=0,
+        description="Server port type (0=shared, 1=dedicated)",
+    )
+    count: int = Field(default=1, ge=1, le=1000, description="Number of ports to create")
+    ttl: int = Field(default=1, ge=1, description="Time-to-live in days")
+    traffic_limit: int = Field(default=10, ge=1, description="Traffic limit in GB")
+
+
+class PortFilterParams(BaseModel):
+    """Query parameters for ``GET /v2/proxy/ports``.
+
+    All fields are optional; omitted filters return all ports.
+    """
+
+    id: int | None = Field(default=None, description="Filter by port ID")
+    proxy: str | None = Field(default=None, description="Filter by proxy address")
+    # Field names mirror the ASocks API's camelCase query params exactly
+    # (sent verbatim by ASocksClient.list_ports) — not a style violation.
+    countryName: str | None = Field(default=None, description="Filter by country name")  # noqa: N815
+    stateName: str | None = Field(default=None, description="Filter by state name")  # noqa: N815
+    cityName: str | None = Field(default=None, description="Filter by city name")  # noqa: N815
+    asn: int | None = Field(default=None, description="Filter by ASN")
+    status: int | None = Field(default=None, description="Filter by status")
+    template_id: int | None = Field(default=None, description="Filter by template ID")
+    page: int = Field(default=1, ge=1)
+    per_page: int = Field(default=50, ge=1, le=200)
+
+
+class UpdatePortRequest(BaseModel):
+    """Body for ``PATCH /v2/proxy/update-port/{id}``."""
+
+    geo_country_ids: list[int] | None = Field(default=None, description="Country IDs")
+    geo_state_id: int | None = Field(default=None, description="State ID")
+    geo_city_id: int | None = Field(default=None, description="City ID")
+    asns: list[int] | None = Field(default=None, description="ASN list")
+    connection_type: str | None = Field(default=None, description="Connection type")
+    auth_type: str | None = Field(default=None, description="Auth type")
+    proxy_types: list[str] | None = Field(default=None, description="Proxy type list")
+    name: str | None = Field(default=None, description="Port name")
+    ttl: int | None = Field(default=None, description="TTL in days")
+    traffic_limit: int | None = Field(default=None, description="Traffic limit in GB")
+
+
+class CreateTemplateRequest(BaseModel):
+    """Body for ``POST /v2/proxy-template/create-template``."""
+
+    label: str = Field(description="Template label")
+    template: str = Field(description="Template pattern, e.g. {ip}:{port}")
+
+
+class UpdateTemplateRequest(BaseModel):
+    """Body for ``PATCH /v2/proxy-template/update-template``."""
+
+    label: str | None = Field(default=None, description="Template label")
+    template: str | None = Field(default=None, description="Template pattern")
+
+
+class WhitelistAddRequest(BaseModel):
+    """Body for ``POST /v2/whitelist/add``."""
+
+    ip: str = Field(description="IP address to whitelist")
+    description: str = Field(default="", description="Description for the IP entry")

asockslib/models/responses.py

@@ -0,0 +1,20 @@
+"""Response models for the ASocks API v2.
+
+Typed wrappers for API response payloads that don't fit into
+the port or directory categories.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class BalanceResponse(BaseModel, extra="allow"):
+    """Response for ``GET /v2/user/balance``."""
+
+    success: bool = Field(default=True)
+    balance: float = Field(default=0, description="Account balance in USD")
+    balance_traffic: float = Field(default=0, description="Traffic balance")
+    all_available_traffic: float = Field(default=0, description="Total available traffic")
+    prepared_traffic_balance: float = Field(default=0, description="Prepared traffic balance")
+    balance_hold: float = Field(default=0, description="Held balance")