proxyhat 0.2.0__py3-none-any.whl

proxyhat/__init__.py

@@ -0,0 +1,39 @@
+"""ProxyHat Python SDK — official client for the ProxyHat residential proxy API."""
+
+from proxyhat.async_client import AsyncProxyHat
+from proxyhat.client import ProxyHat
+from proxyhat.connection import (
+    PROXYHAT_GATEWAY,
+    PROXYHAT_PORT_HTTP,
+    PROXYHAT_PORT_SOCKS5,
+    build_connection_url,
+    build_proxy_username,
+)
+from proxyhat.errors import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionError,
+    ProxyHatError,
+    RateLimitError,
+    ValidationError,
+)
+
+__all__ = [
+    "PROXYHAT_GATEWAY",
+    "PROXYHAT_PORT_HTTP",
+    "PROXYHAT_PORT_SOCKS5",
+    "APIError",
+    "AsyncProxyHat",
+    "AuthenticationError",
+    "NotFoundError",
+    "PermissionError",
+    "ProxyHat",
+    "ProxyHatError",
+    "RateLimitError",
+    "ValidationError",
+    "build_connection_url",
+    "build_proxy_username",
+]
+
+__version__ = "0.2.0"

proxyhat/_base_client.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any
+
+from proxyhat.errors import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.proxyhat.com/v1"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "proxyhat-python/0.1.0"
+
+
+def _build_headers(api_key: str | None) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "User-Agent": USER_AGENT,
+        "Accept": "application/json",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def _raise_for_status(status_code: int, body: Any, headers: Any) -> None:
+    if 200 <= status_code < 300:
+        return
+
+    message = ""
+    errors = None
+
+    if isinstance(body, dict):
+        message = body.get("description", "") or body.get("message", "")
+        errors = body.get("errors")
+
+    if not message:
+        message = f"HTTP {status_code}"
+
+    if status_code == 401:
+        raise AuthenticationError(message=message, errors=errors)
+    elif status_code == 403:
+        raise PermissionError(message=message, errors=errors)
+    elif status_code == 404:
+        raise NotFoundError(message=message, errors=errors)
+    elif status_code == 422:
+        raise ValidationError(message=message, errors=errors)
+    elif status_code == 429:
+        retry_after = None
+        retry_header = headers.get("retry-after") if hasattr(headers, "get") else None
+        if retry_header:
+            try:
+                retry_after = int(retry_header)
+            except (ValueError, TypeError):
+                pass
+        raise RateLimitError(message=message, errors=errors, retry_after=retry_after)
+    else:
+        raise APIError(message=message, status_code=status_code, errors=errors)
+
+
+def _parse_json_body(response: Any) -> Any:
+    """Attempt to parse response as JSON, return empty dict on failure."""
+    content_type = response.headers.get("content-type", "")
+    if "application/json" not in content_type:
+        return {}
+    try:
+        return response.json()
+    except Exception:
+        return {}
+
+
+class BaseClientConfig:
+    """Shared configuration for sync and async clients."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return _build_headers(self.api_key)
+
+    def build_url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+    @staticmethod
+    def handle_response(status_code: int, body: Any, headers: Any) -> Any:
+        _raise_for_status(status_code, body, headers)
+
+        if isinstance(body, dict):
+            if "payload" in body:
+                return body["payload"]
+            if "data" in body:
+                return body["data"]
+        return body

proxyhat/async_client.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from proxyhat._base_client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, BaseClientConfig, _parse_json_body
+from proxyhat.connection import ProxyProtocol, build_connection_url
+from proxyhat.resources.analytics import AsyncAnalyticsResource
+from proxyhat.resources.auth import AsyncAuthResource
+from proxyhat.resources.coupons import AsyncCouponsResource
+from proxyhat.resources.email import AsyncEmailResource
+from proxyhat.resources.locations import AsyncLocationsResource
+from proxyhat.resources.payments import AsyncPaymentsResource
+from proxyhat.resources.plans import AsyncPlansResource
+from proxyhat.resources.profile import AsyncProfileResource
+from proxyhat.resources.proxy_descriptors import AsyncProxyDescriptorsResource
+from proxyhat.resources.proxy_presets import AsyncProxyPresetsResource
+from proxyhat.resources.sub_user_groups import AsyncSubUserGroupsResource
+from proxyhat.resources.sub_users import AsyncSubUsersResource
+from proxyhat.resources.two_factor import AsyncTwoFactorResource
+
+
+class AsyncProxyHat:
+    """Asynchronous client for the ProxyHat API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._config = BaseClientConfig(api_key=api_key, base_url=base_url, timeout=timeout)
+        self._http = httpx.AsyncClient(headers=self._config.headers, timeout=self._config.timeout)
+
+        self.auth = AsyncAuthResource(self)
+        self.sub_users = AsyncSubUsersResource(self)
+        self.sub_user_groups = AsyncSubUserGroupsResource(self)
+        self.locations = AsyncLocationsResource(self)
+        self.analytics = AsyncAnalyticsResource(self)
+        self.proxy_presets = AsyncProxyPresetsResource(self)
+        self.proxy_descriptors = AsyncProxyDescriptorsResource(self)
+        self.profile = AsyncProfileResource(self)
+        self.two_factor = AsyncTwoFactorResource(self)
+        self.email = AsyncEmailResource(self)
+        self.coupons = AsyncCouponsResource(self)
+        self.plans = AsyncPlansResource(self)
+        self.payments = AsyncPaymentsResource(self)
+
+    async def connection_url(
+        self,
+        *,
+        sub_user: str | None = None,
+        country: str | None = None,
+        region: str | None = None,
+        city: str | None = None,
+        sticky: bool | str | None = None,
+        filter: str | None = None,
+        protocol: ProxyProtocol = "http",
+    ) -> str:
+        """Return a ready-to-use residential proxy URL (see ``ProxyHat.connection_url``)."""
+        users = await self.sub_users.list()
+        want = sub_user.strip() if sub_user else None
+        if want:
+            chosen = next((s for s in users if s.uuid == want or s.name == want), None)
+        else:
+            usable = [
+                s for s in users if not s.suspended_at and (s.traffic_limit == 0 or s.used_traffic < s.traffic_limit)
+            ]
+            chosen = usable[0] if usable else None
+        if chosen is None or not chosen.proxy_username or not chosen.proxy_password:
+            raise ValueError(
+                f'No sub-user matched "{want}" (or it has no proxy credentials).'
+                if want
+                else "No usable sub-user found (all suspended or out of traffic). "
+                "Create one, top up, or pass sub_user=."
+            )
+        return build_connection_url(
+            username=chosen.proxy_username,
+            password=chosen.proxy_password,
+            country=country,
+            region=region,
+            city=city,
+            sticky=sticky,
+            filter=filter,
+            protocol=protocol,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        url = self._config.build_url(path)
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        response = await self._http.request(method, url, json=json, params=params)
+        body = _parse_json_body(response)
+        return self._config.handle_response(response.status_code, body, response.headers)
+
+    async def request_raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make a request and return the raw httpx.Response (for binary downloads)."""
+        url = self._config.build_url(path)
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        return await self._http.request(method, url, params=params)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncProxyHat:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

proxyhat/client.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from proxyhat._base_client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, BaseClientConfig, _parse_json_body
+from proxyhat.connection import ProxyProtocol, build_connection_url
+from proxyhat.resources.analytics import AnalyticsResource
+from proxyhat.resources.auth import AuthResource
+from proxyhat.resources.coupons import CouponsResource
+from proxyhat.resources.email import EmailResource
+from proxyhat.resources.locations import LocationsResource
+from proxyhat.resources.payments import PaymentsResource
+from proxyhat.resources.plans import PlansResource
+from proxyhat.resources.profile import ProfileResource
+from proxyhat.resources.proxy_descriptors import ProxyDescriptorsResource
+from proxyhat.resources.proxy_presets import ProxyPresetsResource
+from proxyhat.resources.sub_user_groups import SubUserGroupsResource
+from proxyhat.resources.sub_users import SubUsersResource
+from proxyhat.resources.two_factor import TwoFactorResource
+
+
+class ProxyHat:
+    """Synchronous client for the ProxyHat API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._config = BaseClientConfig(api_key=api_key, base_url=base_url, timeout=timeout)
+        self._http = httpx.Client(headers=self._config.headers, timeout=self._config.timeout)
+
+        self.auth = AuthResource(self)
+        self.sub_users = SubUsersResource(self)
+        self.sub_user_groups = SubUserGroupsResource(self)
+        self.locations = LocationsResource(self)
+        self.analytics = AnalyticsResource(self)
+        self.proxy_presets = ProxyPresetsResource(self)
+        self.proxy_descriptors = ProxyDescriptorsResource(self)
+        self.profile = ProfileResource(self)
+        self.two_factor = TwoFactorResource(self)
+        self.email = EmailResource(self)
+        self.coupons = CouponsResource(self)
+        self.plans = PlansResource(self)
+        self.payments = PaymentsResource(self)
+
+    def connection_url(
+        self,
+        *,
+        sub_user: str | None = None,
+        country: str | None = None,
+        region: str | None = None,
+        city: str | None = None,
+        sticky: bool | str | None = None,
+        filter: str | None = None,
+        protocol: ProxyProtocol = "http",
+    ) -> str:
+        """Return a ready-to-use residential proxy URL.
+
+        Looks up your sub-users, picks an active one with remaining traffic (or
+        the one named by ``sub_user``), and builds the gateway URL locally.
+        """
+        users = self.sub_users.list()
+        want = sub_user.strip() if sub_user else None
+        if want:
+            chosen = next((s for s in users if s.uuid == want or s.name == want), None)
+        else:
+            usable = [
+                s for s in users if not s.suspended_at and (s.traffic_limit == 0 or s.used_traffic < s.traffic_limit)
+            ]
+            chosen = usable[0] if usable else None
+        if chosen is None or not chosen.proxy_username or not chosen.proxy_password:
+            raise ValueError(
+                f'No sub-user matched "{want}" (or it has no proxy credentials).'
+                if want
+                else "No usable sub-user found (all suspended or out of traffic). "
+                "Create one, top up, or pass sub_user=."
+            )
+        return build_connection_url(
+            username=chosen.proxy_username,
+            password=chosen.proxy_password,
+            country=country,
+            region=region,
+            city=city,
+            sticky=sticky,
+            filter=filter,
+            protocol=protocol,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        url = self._config.build_url(path)
+        # Filter out None params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        response = self._http.request(method, url, json=json, params=params)
+        body = _parse_json_body(response)
+        return self._config.handle_response(response.status_code, body, response.headers)
+
+    def request_raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make a request and return the raw httpx.Response (for binary downloads)."""
+        url = self._config.build_url(path)
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        return self._http.request(method, url, params=params)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> ProxyHat:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

proxyhat/connection.py

@@ -0,0 +1,90 @@
+"""ProxyHat gateway connection helpers.
+
+The API resources manage your account; these helpers turn a sub-user's
+``proxy_username`` / ``proxy_password`` into a ready-to-use proxy URL, building
+the gateway username with ProxyHat's targeting grammar. Everything here is
+offline (no network) — see https://docs.proxyhat.com/connecting.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import Literal
+from urllib.parse import quote
+
+PROXYHAT_GATEWAY = "gate.proxyhat.com"
+PROXYHAT_PORT_HTTP = 8080
+PROXYHAT_PORT_SOCKS5 = 1080
+
+ProxyProtocol = Literal["http", "socks5"]
+
+
+def _slug(value: str) -> str:
+    return "_".join(value.strip().lower().split())
+
+
+def build_proxy_username(
+    base: str,
+    *,
+    country: str | None = None,
+    region: str | None = None,
+    city: str | None = None,
+    sticky: bool | str | None = None,
+    filter: str | None = None,
+) -> str:
+    """Build a gateway username from a base ``proxy_username`` plus targeting tokens.
+
+    Fixed order: ``<base>-country-<iso>[-region-<slug>][-city-<slug>]``
+    ``[-sid-<16hex>-ttl-<dur>]-filter-<tier>``.
+
+    ``sticky``: ``True`` → 30m default; a string sets the TTL ("30m"/"12h");
+    omit / ``False`` for a fresh rotating IP per request.
+    """
+    parts = [base.strip(), "country", (country or "any").strip().lower()]
+
+    if region and region.strip().lower() != "any":
+        parts += ["region", _slug(region)]
+    if city:
+        parts += ["city", _slug(city)]
+    if sticky is not None and sticky is not False:
+        if sticky is True:
+            ttl = "30m"
+        else:
+            raw = str(sticky).strip()
+            ttl = "30m" if raw.lower() in ("", "true", "1", "yes", "on") else raw
+        parts += ["sid", secrets.token_hex(8), "ttl", ttl]
+    if isinstance(filter, str):
+        tier = filter.strip().lower()
+        if tier.startswith("filter-"):
+            tier = tier[len("filter-") :]
+        if tier and tier != "none":
+            parts += ["filter", tier]
+
+    return "-".join(parts)
+
+
+def build_connection_url(
+    *,
+    username: str,
+    password: str,
+    country: str | None = None,
+    region: str | None = None,
+    city: str | None = None,
+    sticky: bool | str | None = None,
+    filter: str | None = None,
+    protocol: ProxyProtocol = "http",
+) -> str:
+    """Build a full proxy connection URL for the ProxyHat gateway.
+
+    Example: ``http://<user>-country-us:<pass>@gate.proxyhat.com:8080``.
+    """
+    port = PROXYHAT_PORT_SOCKS5 if protocol == "socks5" else PROXYHAT_PORT_HTTP
+    user = build_proxy_username(
+        username,
+        country=country,
+        region=region,
+        city=city,
+        sticky=sticky,
+        filter=filter,
+    )
+    return f"{protocol}://{quote(user, safe='')}:{quote(password, safe='')}@{PROXYHAT_GATEWAY}:{port}"

proxyhat/errors.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class ProxyHatError(Exception):
+    """Base exception for all ProxyHat SDK errors."""
+
+    message: str
+    status_code: int | None
+    errors: Any
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        errors: Any = None,
+    ) -> None:
+        self.message = message
+        self.status_code = status_code
+        self.errors = errors
+        super().__init__(message)
+
+
+class AuthenticationError(ProxyHatError):
+    """Raised on 401 Unauthorized responses."""
+
+    def __init__(self, message: str = "Unauthorized", errors: Any = None) -> None:
+        super().__init__(message, status_code=401, errors=errors)
+
+
+class PermissionError(ProxyHatError):
+    """Raised on 403 Forbidden responses."""
+
+    def __init__(self, message: str = "Forbidden", errors: Any = None) -> None:
+        super().__init__(message, status_code=403, errors=errors)
+
+
+class NotFoundError(ProxyHatError):
+    """Raised on 404 Not Found responses."""
+
+    def __init__(self, message: str = "Not Found", errors: Any = None) -> None:
+        super().__init__(message, status_code=404, errors=errors)
+
+
+class ValidationError(ProxyHatError):
+    """Raised on 422 Unprocessable Entity responses. Includes field-level errors."""
+
+    def __init__(self, message: str = "Validation Error", errors: Any = None) -> None:
+        super().__init__(message, status_code=422, errors=errors)
+
+
+class RateLimitError(ProxyHatError):
+    """Raised on 429 Too Many Requests responses."""
+
+    retry_after: int | None
+
+    def __init__(
+        self,
+        message: str = "Rate Limited",
+        errors: Any = None,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(message, status_code=429, errors=errors)
+        self.retry_after = retry_after
+
+
+class APIError(ProxyHatError):
+    """Raised for all other HTTP errors (500, etc.)."""
+
+    def __init__(self, message: str = "API Error", status_code: int = 500, errors: Any = None) -> None:
+        super().__init__(message, status_code=status_code, errors=errors)