proxyhubb 0.1.0__tar.gz → 0.3.0__tar.gz

proxyhubb-0.3.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: proxyhubb
+Version: 0.3.0
+Summary: Official Python SDK for ProxyHubb (buyer Connect/bulk + seller/provider APIs)
+Author: ProxyHubb
+License: MIT
+Project-URL: Homepage, https://proxyhubb.com
+Project-URL: Repository, https://github.com/proxyhubb/proxyhubb
+Project-URL: Issues, https://github.com/proxyhubb/proxyhubb/issues
+Keywords: proxyhubb,proxy,sdk,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: urllib3>=2.0.0
+Dynamic: license-file
+
+# proxyhubb
+
+Official Python client for ProxyHubb Connect (session intents), marketplace credentials, and bulk pools.
+
+## Install
+
+```bash
+pip install proxyhubb
+```
+
+## Auth
+
+- **API key** (`phub_…`): bulk pools — `X-API-Key`
+- **JWT** (dashboard): session intents + order credentials — `Authorization: Bearer`
+
+## Quick start — Connect (rotating / sticky)
+
+```python
+from proxyhubb import ProxyHubClient, session_intent_proxy_url
+import requests
+
+client = ProxyHubClient(access_token="eyJ...")  # dashboard JWT
+intent = client.create_session_intent("rotating", target_geo="US")
+proxies = client.as_requests_proxy_from_intent(intent["token"])
+print(requests.get("https://httpbin.org/ip", proxies=proxies).json())
+
+# or curl:
+# curl -x "http://session-intent:TOKEN@proxy.proxyhubb.com:8090" https://httpbin.org/ip
+```
+
+## Marketplace credentials
+
+```python
+creds = client.get_order_credentials("ORDER_UUID")
+proxies = client.as_requests_proxy_from_credentials(creds)
+```
+
+## Bulk pools
+
+```python
+client = ProxyHubClient("phub_...")
+pool = client.create_pool("scrapers", size=5)
+proxies = client.as_requests_proxy(pool["id"])
+```
+
+Buyer proxy is HTTP CONNECT / SOCKS5 (`proxy.proxyhubb.com:8090`). See [docs/buyer-proxy.md](../../docs/buyer-proxy.md).
+
+## License
+
+MIT

proxyhubb-0.3.0/README.md

@@ -0,0 +1,50 @@
+# proxyhubb
+
+Official Python client for ProxyHubb Connect (session intents), marketplace credentials, and bulk pools.
+
+## Install
+
+```bash
+pip install proxyhubb
+```
+
+## Auth
+
+- **API key** (`phub_…`): bulk pools — `X-API-Key`
+- **JWT** (dashboard): session intents + order credentials — `Authorization: Bearer`
+
+## Quick start — Connect (rotating / sticky)
+
+```python
+from proxyhubb import ProxyHubClient, session_intent_proxy_url
+import requests
+
+client = ProxyHubClient(access_token="eyJ...")  # dashboard JWT
+intent = client.create_session_intent("rotating", target_geo="US")
+proxies = client.as_requests_proxy_from_intent(intent["token"])
+print(requests.get("https://httpbin.org/ip", proxies=proxies).json())
+
+# or curl:
+# curl -x "http://session-intent:TOKEN@proxy.proxyhubb.com:8090" https://httpbin.org/ip
+```
+
+## Marketplace credentials
+
+```python
+creds = client.get_order_credentials("ORDER_UUID")
+proxies = client.as_requests_proxy_from_credentials(creds)
+```
+
+## Bulk pools
+
+```python
+client = ProxyHubClient("phub_...")
+pool = client.create_pool("scrapers", size=5)
+proxies = client.as_requests_proxy(pool["id"])
+```
+
+Buyer proxy is HTTP CONNECT / SOCKS5 (`proxy.proxyhubb.com:8090`). See [docs/buyer-proxy.md](../../docs/buyer-proxy.md).
+
+## License
+
+MIT

proxyhubb-0.3.0/proxyhubb/__init__.py

@@ -0,0 +1,24 @@
+"""Official ProxyHubb Python SDK."""
+
+from proxyhubb.client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_PROXY_ENDPOINT,
+    ProxyHubClient,
+    as_requests_proxies,
+    default_proxy_endpoint,
+    proxy_url,
+    session_intent_proxy_url,
+)
+from proxyhubb.proxy import ProxyClient
+
+__all__ = [
+    "ProxyHubClient",
+    "ProxyClient",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_PROXY_ENDPOINT",
+    "as_requests_proxies",
+    "default_proxy_endpoint",
+    "proxy_url",
+    "session_intent_proxy_url",
+]
+__version__ = "0.3.0"

proxyhubb-0.3.0/proxyhubb/client.py

@@ -0,0 +1,453 @@
+"""ProxyHubb Python SDK — Control API client (buyer + seller/provider)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping, Optional
+from urllib.parse import quote, urlencode
+
+import requests
+
+DEFAULT_BASE_URL = "https://api.proxyhubb.com"
+DEFAULT_PROXY_ENDPOINT = "proxy.proxyhubb.com:8090"
+
+
+def default_proxy_endpoint() -> str:
+    """Buyer CONNECT host:port (env ``PROXYHUBB_PROXY_ENDPOINT`` overrides)."""
+    return (
+        os.environ.get("PROXYHUBB_PROXY_ENDPOINT", "").strip()
+        or DEFAULT_PROXY_ENDPOINT
+    )
+
+
+def proxy_url(
+    username: str,
+    password: str,
+    *,
+    host: Optional[str] = None,
+) -> str:
+    """Build an HTTP proxy URL for CONNECT clients (curl ``-x``, requests, etc.)."""
+    endpoint = (host or default_proxy_endpoint()).removeprefix("http://").removeprefix(
+        "https://"
+    )
+    user = quote(username, safe="")
+    pwd = quote(password, safe="")
+    return f"http://{user}:{pwd}@{endpoint}"
+
+
+def session_intent_proxy_url(token: str, *, host: Optional[str] = None) -> str:
+    """Proxy URL using session-intent auth (Connect rotating/sticky)."""
+    return proxy_url("session-intent", token, host=host)
+
+
+def as_requests_proxies(proxy: str) -> dict[str, str]:
+    """``requests``-compatible ``proxies`` dict from a proxy URL string."""
+    return {"http": proxy, "https": proxy}
+
+
+class ProxyHubClient:
+    """Client for ProxyHubb Control API (buyer Connect/bulk + seller/provider).
+
+    Parameters
+    ----------
+    api_key:
+        ``phub_…`` / ``pk_…`` key for bulk pool endpoints (``X-API-Key``).
+        Buyer keys do **not** authorize provider/seller routes.
+    access_token:
+        Dashboard JWT for session intents, order credentials, and seller ops
+        (``Authorization: Bearer``).
+    provider_token:
+        Provider CLI/dashboard token; alias of ``access_token`` (same Bearer header).
+    base_url:
+        Control API base URL. Defaults to production.
+    proxy_endpoint:
+        Buyer CONNECT host:port. Defaults to ``PROXYHUBB_PROXY_ENDPOINT`` or production.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        access_token: Optional[str] = None,
+        provider_token: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        proxy_endpoint: Optional[str] = None,
+    ) -> None:
+        bearer = access_token or provider_token or ""
+        if not api_key and not bearer:
+            raise ValueError("api_key, access_token, or provider_token is required")
+        self._api_key = api_key or ""
+        self._access_token = bearer
+        self._base_url = base_url.rstrip("/")
+        self._proxy_endpoint = (
+            proxy_endpoint.strip()
+            if proxy_endpoint
+            else default_proxy_endpoint()
+        )
+        self._session = requests.Session()
+        if self._api_key:
+            self._session.headers.update({"X-API-Key": self._api_key})
+        if self._access_token:
+            self._session.headers.update(
+                {"Authorization": f"Bearer {self._access_token}"}
+            )
+
+    @property
+    def proxy_endpoint(self) -> str:
+        return self._proxy_endpoint
+
+    def set_access_token(self, token: str) -> None:
+        """Update Bearer JWT / provider token used for authenticated calls."""
+        self._access_token = token
+        if token:
+            self._session.headers["Authorization"] = f"Bearer {token}"
+        else:
+            self._session.headers.pop("Authorization", None)
+
+    def set_provider_token(self, token: str) -> None:
+        """Alias for :meth:`set_access_token` (same Bearer header)."""
+        self.set_access_token(token)
+
+    def _url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        url = f"{self._base_url}{path}"
+        if query:
+            filtered = {
+                k: v for k, v in query.items() if v is not None and v != ""
+            }
+            if filtered:
+                url = f"{url}?{urlencode(filtered)}"
+        return url
+
+    def _raise(self, resp: requests.Response) -> None:
+        if resp.ok:
+            return
+        try:
+            data = resp.json()
+            message = data.get("error") or resp.reason
+        except Exception:
+            message = resp.reason or resp.text
+        raise requests.HTTPError(
+            f"ProxyHubb API error {resp.status_code}: {message}",
+            response=resp,
+        )
+
+    def _get(self, path: str, *, query: Optional[Mapping[str, Any]] = None) -> dict[str, Any]:
+        resp = self._session.get(self._url(path, query))
+        self._raise(resp)
+        return resp.json()
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        resp = self._session.post(self._url(path), json=payload)
+        self._raise(resp)
+        return resp.json()
+
+    def _put(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        resp = self._session.put(self._url(path), json=payload)
+        self._raise(resp)
+        return resp.json()
+
+    def _patch(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        resp = self._session.patch(self._url(path), json=payload)
+        self._raise(resp)
+        return resp.json()
+
+    def _delete(self, path: str) -> dict[str, Any] | None:
+        resp = self._session.delete(self._url(path))
+        self._raise(resp)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        try:
+            return resp.json()
+        except Exception:
+            return None
+
+    # ── Session intent (Connect) ──────────────────────────────────────────
+
+    def create_session_intent(
+        self,
+        session_type: str = "rotating",
+        *,
+        listing_id: Optional[str] = None,
+        bandwidth_limit: Optional[int] = None,
+        target_geo: Optional[str] = None,
+        target_isp: Optional[str] = None,
+        routing_profile: Optional[str] = None,
+        allowed_domains: Optional[list[str]] = None,
+        blocked_domains: Optional[list[str]] = None,
+        rotation_type: Optional[str] = None,
+        rotation_interval_seconds: Optional[int] = None,
+        time_limit_minutes: Optional[int] = None,
+        preferred_tier: Optional[str] = None,
+        max_price_per_gb: Optional[float] = None,
+    ) -> dict[str, Any]:
+        """Issue a signed session intent (requires ``access_token``).
+
+        Returns ``token``, ``expires_at``, ``lifecycle_state``, and ``intent``.
+        """
+        if session_type not in ("rotating", "sticky"):
+            raise ValueError("session_type must be 'rotating' or 'sticky'")
+        payload: dict[str, Any] = {"type": session_type}
+        if listing_id is not None:
+            payload["listing_id"] = listing_id
+        if bandwidth_limit is not None:
+            payload["bandwidth_limit"] = bandwidth_limit
+        if target_geo is not None:
+            payload["target_geo"] = target_geo
+        if target_isp is not None:
+            payload["target_isp"] = target_isp
+        if routing_profile is not None:
+            payload["routing_profile"] = routing_profile
+        if allowed_domains is not None:
+            payload["allowed_domains"] = allowed_domains
+        if blocked_domains is not None:
+            payload["blocked_domains"] = blocked_domains
+        if rotation_type is not None:
+            payload["rotation_type"] = rotation_type
+        if rotation_interval_seconds is not None:
+            payload["rotation_interval_seconds"] = rotation_interval_seconds
+        if time_limit_minutes is not None:
+            payload["time_limit_minutes"] = time_limit_minutes
+        if preferred_tier is not None:
+            payload["preferred_tier"] = preferred_tier
+        if max_price_per_gb is not None:
+            payload["max_price_per_gb"] = max_price_per_gb
+        return self._post("/v1/sessions/intent", payload)
+
+    def as_requests_proxy_from_intent(self, token: str) -> dict[str, str]:
+        """``requests`` proxies dict for a session-intent token."""
+        return as_requests_proxies(
+            session_intent_proxy_url(token, host=self._proxy_endpoint)
+        )
+
+    # ── Order credentials (marketplace) ───────────────────────────────────
+
+    def get_order_credentials(self, order_id: str) -> dict[str, Any]:
+        """Fetch proxy credentials after escrow activation (requires JWT).
+
+        Returns the API payload, typically
+        ``{"proxy_credentials": {username, password, host, port, protocol, endpoint}}``.
+        """
+        if not order_id:
+            raise ValueError("order_id is required")
+        return self._get(f"/v1/orders/{order_id}/credentials")
+
+    def as_requests_proxy_from_credentials(
+        self, credentials: Mapping[str, Any]
+    ) -> dict[str, str]:
+        """Build ``requests`` proxies from a credentials object or envelope."""
+        creds = credentials.get("proxy_credentials", credentials)
+        username = creds["username"]
+        password = creds["password"]
+        host = creds.get("host") or creds.get("endpoint") or self._proxy_endpoint
+        port = creds.get("port")
+        if port and ":" not in str(host):
+            host = f"{host}:{port}"
+        return as_requests_proxies(proxy_url(username, password, host=str(host)))
+
+    # ── Bulk pools ────────────────────────────────────────────────────────
+
+    def create_pool(
+        self,
+        name: str,
+        size: int = 10,
+        session_type: str = "rotating",
+        description: str = "",
+        bytes_limit: int = 0,
+    ) -> dict[str, Any]:
+        """Create a new proxy pool."""
+        return self._post(
+            "/v1/bulk/pools",
+            {
+                "name": name,
+                "size": size,
+                "session_type": session_type,
+                "description": description,
+                "bytes_limit": bytes_limit,
+            },
+        )
+
+    def list_pools(self) -> dict[str, Any]:
+        """List proxy pools for the authenticated account."""
+        return self._get("/v1/bulk/pools")
+
+    def get_pool(self, pool_id: str) -> dict[str, Any]:
+        """Retrieve the endpoints of a proxy pool."""
+        return self._get(f"/v1/bulk/pools/{pool_id}/endpoints")
+
+    def get_proxies(self, pool_id: str) -> list[dict[str, Any]]:
+        """Return the list of endpoint dicts for a pool."""
+        data = self.get_pool(pool_id)
+        return data.get("endpoints", [])
+
+    def revoke_pool(self, pool_id: str) -> None:
+        """Soft-delete a proxy pool."""
+        self._delete(f"/v1/bulk/pools/{pool_id}")
+
+    def as_requests_proxy(self, pool_id: str, index: int = 0) -> dict[str, str]:
+        """Return a ``proxies`` dict compatible with the ``requests`` library.
+
+        Endpoint host/port come from the API (production buyer proxy is
+        ``proxy.proxyhubb.com:8090``).
+        """
+        endpoints = self.get_proxies(pool_id)
+        if not endpoints:
+            raise ValueError(f"Pool {pool_id!r} has no endpoints")
+        if index >= len(endpoints):
+            raise IndexError(
+                f"index {index} is out of range for pool with {len(endpoints)} endpoints"
+            )
+        ep = endpoints[index]
+        return as_requests_proxies(
+            proxy_url(
+                ep["username"],
+                ep["password"],
+                host=f"{ep['host']}:{ep['port']}",
+            )
+        )
+
+    # ── Provider tokens ───────────────────────────────────────────────────
+
+    def list_provider_tokens(self) -> dict[str, Any]:
+        """List provider tokens (masked). Requires JWT or provider token Bearer."""
+        return self._get("/v1/provider/tokens")
+
+    def create_provider_token(
+        self,
+        *,
+        name: Optional[str] = None,
+        expires_in: Optional[int] = None,
+        node_id: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Create a provider token. Plaintext ``token`` is returned once."""
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if expires_in is not None:
+            payload["expires_in"] = expires_in
+        if node_id is not None:
+            payload["node_id"] = node_id
+        return self._post("/v1/provider/tokens", payload)
+
+    def rotate_provider_token(self, token_id: str) -> dict[str, Any]:
+        """Rotate a provider token; returns new plaintext ``token`` once."""
+        if not token_id:
+            raise ValueError("token_id is required")
+        return self._post(f"/v1/provider/tokens/{token_id}/rotate", {})
+
+    def revoke_provider_token(self, token_id: str) -> dict[str, Any] | None:
+        """Revoke a provider token."""
+        if not token_id:
+            raise ValueError("token_id is required")
+        return self._delete(f"/v1/provider/tokens/{token_id}")
+
+    # ── Provider nodes ────────────────────────────────────────────────────
+
+    def get_provider_readiness(self) -> dict[str, Any]:
+        return self._get("/v1/provider/readiness")
+
+    def list_provider_nodes(self) -> dict[str, Any]:
+        return self._get("/v1/provider/nodes")
+
+    def create_provider_node(
+        self,
+        name: str,
+        *,
+        ip_address: Optional[str] = None,
+        country: Optional[str] = None,
+        city: Optional[str] = None,
+        connection_type: Optional[str] = None,
+    ) -> dict[str, Any]:
+        if not name:
+            raise ValueError("name is required")
+        payload: dict[str, Any] = {"name": name}
+        if ip_address is not None:
+            payload["ip_address"] = ip_address
+        if country is not None:
+            payload["country"] = country
+        if city is not None:
+            payload["city"] = city
+        if connection_type is not None:
+            payload["connection_type"] = connection_type
+        return self._post("/v1/provider/nodes", payload)
+
+    def update_provider_node(
+        self,
+        node_id: str,
+        *,
+        name: Optional[str] = None,
+        ip_address: Optional[str] = None,
+        country: Optional[str] = None,
+        city: Optional[str] = None,
+        connection_type: Optional[str] = None,
+    ) -> dict[str, Any]:
+        if not node_id:
+            raise ValueError("node_id is required")
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if ip_address is not None:
+            payload["ip_address"] = ip_address
+        if country is not None:
+            payload["country"] = country
+        if city is not None:
+            payload["city"] = city
+        if connection_type is not None:
+            payload["connection_type"] = connection_type
+        return self._put(f"/v1/provider/nodes/{node_id}", payload)
+
+    def delete_provider_node(self, node_id: str) -> dict[str, Any] | None:
+        if not node_id:
+            raise ValueError("node_id is required")
+        return self._delete(f"/v1/provider/nodes/{node_id}")
+
+    def get_node_connect(self, node_id: str) -> dict[str, Any]:
+        """Connect hints for provider-cli / provider-node join."""
+        if not node_id:
+            raise ValueError("node_id is required")
+        return self._get(f"/v1/provider/nodes/{node_id}/connect")
+
+    # ── Listings (seller) ─────────────────────────────────────────────────
+
+    def list_my_listings(
+        self, *, page: Optional[int] = None, limit: Optional[int] = None
+    ) -> dict[str, Any]:
+        return self._get("/v1/listings/my", query={"page": page, "limit": limit})
+
+    def get_listing(self, listing_id: str) -> dict[str, Any]:
+        if not listing_id:
+            raise ValueError("listing_id is required")
+        return self._get(f"/v1/listings/{listing_id}")
+
+    def create_listing(self, **fields: Any) -> dict[str, Any]:
+        """Create a marketplace listing as seller.
+
+        Required fields typically include ``title``, ``proxy_type``, ``protocol``,
+        ``price_per_gb``, ``available_bandwidth_gb``.
+        """
+        return self._post("/v1/listings", dict(fields))
+
+    def update_listing(self, listing_id: str, **fields: Any) -> dict[str, Any]:
+        """Update a listing. Pause/activate with ``status="active"|"paused"``."""
+        if not listing_id:
+            raise ValueError("listing_id is required")
+        return self._patch(f"/v1/listings/{listing_id}", dict(fields))
+
+    def delete_listing(self, listing_id: str) -> dict[str, Any] | None:
+        if not listing_id:
+            raise ValueError("listing_id is required")
+        return self._delete(f"/v1/listings/{listing_id}")
+
+    # ── Earnings ──────────────────────────────────────────────────────────
+
+    def get_earnings_summary(self) -> dict[str, Any]:
+        return self._get("/v1/provider/earnings/summary")
+
+    def list_earnings(
+        self, *, page: Optional[int] = None, limit: Optional[int] = None
+    ) -> dict[str, Any]:
+        return self._get(
+            "/v1/provider/earnings", query={"page": page, "limit": limit}
+        )
+
+    def list_earnings_history(self) -> dict[str, Any]:
+        return self._get("/v1/provider/earnings/history")

{proxyhubb-0.1.0 → proxyhubb-0.3.0}/proxyhubb/proxy.py

@@ -8,21 +8,25 @@ from typing import Any, Optional
 
 import requests
 
-DEFAULT_GATEWAY = "http://proxy.proxyhubb.com:8090"
+from proxyhubb.client import DEFAULT_PROXY_ENDPOINT, default_proxy_endpoint, proxy_url
 
 
 class ProxyClient:
     """Thin helper that builds ``requests``-compatible proxy URLs for the gateway.
 
-    Prefer :class:`proxyhubb.ProxyHubClient` to create pools and obtain credentials.
+    Prefer :class:`proxyhubb.ProxyHubClient` for session intents, order credentials,
+    and bulk pools.
     """
 
     def __init__(
         self,
-        gateway_url: str = DEFAULT_GATEWAY,
+        gateway_url: Optional[str] = None,
         proxy_auth: Optional[str] = None,
     ) -> None:
-        self.gateway_url = gateway_url
+        endpoint = gateway_url or f"http://{default_proxy_endpoint()}"
+        if not endpoint.startswith("http://") and not endpoint.startswith("https://"):
+            endpoint = f"http://{endpoint}"
+        self.gateway_url = endpoint
         self.proxy_auth = proxy_auth
         self.current_session_id = str(uuid.uuid4())
         self.session_start = time.time()
@@ -32,10 +36,15 @@ class ProxyClient:
             self.current_session_id = str(uuid.uuid4())
             self.session_start = time.time()
 
-        auth_str = self.proxy_auth if self.proxy_auth else "anonymous"
         host = self.gateway_url.split("//")[-1]
-        proxy_str = f"http://{auth_str}:{self.current_session_id}@{host}"
-        return {"http": proxy_str, "https": proxy_str}
+        if self.proxy_auth and ":" in self.proxy_auth:
+            user, _, password = self.proxy_auth.partition(":")
+            url = proxy_url(user, password, host=host)
+        elif self.proxy_auth:
+            url = proxy_url(self.proxy_auth, self.current_session_id, host=host)
+        else:
+            url = proxy_url("anonymous", self.current_session_id, host=host)
+        return {"http": url, "https": url}
 
     def request(self, method: str, url: str, rotate: bool = False, **kwargs: Any):
         proxies = self.get_proxy_config(rotate=rotate)
@@ -45,3 +54,6 @@ class ProxyClient:
             return requests.request(
                 method, url, proxies=self.get_proxy_config(rotate=True), **kwargs
             )
+
+
+__all__ = ["ProxyClient", "DEFAULT_PROXY_ENDPOINT"]

proxyhubb-0.3.0/proxyhubb.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: proxyhubb
+Version: 0.3.0
+Summary: Official Python SDK for ProxyHubb (buyer Connect/bulk + seller/provider APIs)
+Author: ProxyHubb
+License: MIT
+Project-URL: Homepage, https://proxyhubb.com
+Project-URL: Repository, https://github.com/proxyhubb/proxyhubb
+Project-URL: Issues, https://github.com/proxyhubb/proxyhubb/issues
+Keywords: proxyhubb,proxy,sdk,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: urllib3>=2.0.0
+Dynamic: license-file
+
+# proxyhubb
+
+Official Python client for ProxyHubb Connect (session intents), marketplace credentials, and bulk pools.
+
+## Install
+
+```bash
+pip install proxyhubb
+```
+
+## Auth
+
+- **API key** (`phub_…`): bulk pools — `X-API-Key`
+- **JWT** (dashboard): session intents + order credentials — `Authorization: Bearer`
+
+## Quick start — Connect (rotating / sticky)
+
+```python
+from proxyhubb import ProxyHubClient, session_intent_proxy_url
+import requests
+
+client = ProxyHubClient(access_token="eyJ...")  # dashboard JWT
+intent = client.create_session_intent("rotating", target_geo="US")
+proxies = client.as_requests_proxy_from_intent(intent["token"])
+print(requests.get("https://httpbin.org/ip", proxies=proxies).json())
+
+# or curl:
+# curl -x "http://session-intent:TOKEN@proxy.proxyhubb.com:8090" https://httpbin.org/ip
+```
+
+## Marketplace credentials
+
+```python
+creds = client.get_order_credentials("ORDER_UUID")
+proxies = client.as_requests_proxy_from_credentials(creds)
+```
+
+## Bulk pools
+
+```python
+client = ProxyHubClient("phub_...")
+pool = client.create_pool("scrapers", size=5)
+proxies = client.as_requests_proxy(pool["id"])
+```
+
+Buyer proxy is HTTP CONNECT / SOCKS5 (`proxy.proxyhubb.com:8090`). See [docs/buyer-proxy.md](../../docs/buyer-proxy.md).
+
+## License
+
+MIT

{proxyhubb-0.1.0 → proxyhubb-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proxyhubb"
-version = "0.1.0"
-description = "Official Python SDK for the ProxyHubb Bulk Proxy Pool API"
+version = "0.3.0"
+description = "Official Python SDK for ProxyHubb (buyer Connect/bulk + seller/provider APIs)"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.9"

proxyhubb-0.3.0/tests/test_client.py

@@ -0,0 +1,153 @@
+from unittest.mock import MagicMock, patch
+
+from proxyhubb import (
+    DEFAULT_BASE_URL,
+    DEFAULT_PROXY_ENDPOINT,
+    ProxyClient,
+    ProxyHubClient,
+    as_requests_proxies,
+    proxy_url,
+    session_intent_proxy_url,
+)
+
+
+def test_defaults():
+    assert DEFAULT_BASE_URL == "https://api.proxyhubb.com"
+    client = ProxyHubClient("phub_test")
+    assert client._base_url == "https://api.proxyhubb.com"
+    assert client.proxy_endpoint == DEFAULT_PROXY_ENDPOINT
+
+
+def test_requires_auth():
+    try:
+        ProxyHubClient()
+        assert False, "expected ValueError"
+    except ValueError:
+        pass
+
+
+def test_access_token_only():
+    client = ProxyHubClient(access_token="jwt_test")
+    assert client._session.headers["Authorization"] == "Bearer jwt_test"
+    assert "X-API-Key" not in client._session.headers
+
+
+def test_provider_token_alias():
+    client = ProxyHubClient(provider_token="ptok")
+    assert client._session.headers["Authorization"] == "Bearer ptok"
+    client.set_provider_token("ptok2")
+    assert client._session.headers["Authorization"] == "Bearer ptok2"
+
+
+def test_proxy_url_helpers():
+    assert (
+        proxy_url("user", "pass", host="proxy.proxyhubb.com:8090")
+        == "http://user:pass@proxy.proxyhubb.com:8090"
+    )
+    assert session_intent_proxy_url("tok").startswith(
+        "http://session-intent:tok@proxy.proxyhubb.com:8090"
+    )
+    assert as_requests_proxies("http://a:b@h:1") == {
+        "http": "http://a:b@h:1",
+        "https": "http://a:b@h:1",
+    }
+
+
+def test_proxy_client_default_gateway():
+    gw = ProxyClient()
+    assert "proxy.proxyhubb.com" in gw.gateway_url
+
+
+def test_create_session_intent_posts():
+    client = ProxyHubClient(access_token="jwt")
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_resp.json.return_value = {
+        "token": "abc",
+        "expires_at": "2099-01-01T00:00:00Z",
+        "lifecycle_state": "authorized",
+        "intent": {"intent_id": "i1", "session_type": "rotating"},
+    }
+    with patch.object(client._session, "post", return_value=mock_resp) as post:
+        out = client.create_session_intent("sticky", target_geo="US")
+    assert out["token"] == "abc"
+    post.assert_called_once()
+    args, kwargs = post.call_args
+    assert args[0].endswith("/v1/sessions/intent")
+    assert kwargs["json"]["type"] == "sticky"
+    assert kwargs["json"]["target_geo"] == "US"
+
+
+def test_get_order_credentials_gets():
+    client = ProxyHubClient(access_token="jwt")
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_resp.json.return_value = {
+        "proxy_credentials": {
+            "username": "u",
+            "password": "p",
+            "host": "proxy.proxyhubb.com",
+            "port": 8090,
+            "endpoint": "proxy.proxyhubb.com:8090",
+        }
+    }
+    with patch.object(client._session, "get", return_value=mock_resp) as get:
+        out = client.get_order_credentials("order-1")
+    assert out["proxy_credentials"]["username"] == "u"
+    get.assert_called_once()
+    assert get.call_args[0][0].endswith("/v1/orders/order-1/credentials")
+
+
+def test_as_requests_proxy_from_credentials():
+    client = ProxyHubClient("phub_x")
+    proxies = client.as_requests_proxy_from_credentials(
+        {
+            "username": "u",
+            "password": "p",
+            "host": "proxy.proxyhubb.com",
+            "port": 8090,
+        }
+    )
+    assert proxies["https"] == "http://u:p@proxy.proxyhubb.com:8090"
+
+
+def test_as_requests_proxy_from_intent():
+    client = ProxyHubClient(access_token="jwt")
+    proxies = client.as_requests_proxy_from_intent("tok")
+    assert "session-intent:tok@" in proxies["http"]
+
+
+def test_create_provider_token():
+    client = ProxyHubClient(provider_token="ptok")
+    mock_resp = MagicMock()
+    mock_resp.ok = True
+    mock_resp.status_code = 201
+    mock_resp.json.return_value = {"id": "t1", "token": "raw-once"}
+    with patch.object(client._session, "post", return_value=mock_resp) as post:
+        out = client.create_provider_token(name="edge", node_id="n1")
+    assert out["token"] == "raw-once"
+    assert post.call_args[0][0].endswith("/v1/provider/tokens")
+    assert post.call_args[1]["json"]["node_id"] == "n1"
+
+
+def test_seller_listing_and_earnings():
+    client = ProxyHubClient(access_token="jwt")
+    mock_resp = MagicMock()
+    mock_resp.ok = True
+    mock_resp.status_code = 200
+    mock_resp.content = b"{}"
+    mock_resp.json.return_value = {"ok": True}
+
+    with patch.object(client._session, "get", return_value=mock_resp) as get:
+        client.get_node_connect("n1")
+        client.get_earnings_summary()
+        client.list_my_listings(page=1, limit=5)
+    paths = [c.args[0] for c in get.call_args_list]
+    assert paths[0].endswith("/v1/provider/nodes/n1/connect")
+    assert paths[1].endswith("/v1/provider/earnings/summary")
+    assert "page=1" in paths[2] and "limit=5" in paths[2]
+
+    with patch.object(client._session, "patch", return_value=mock_resp) as patch_call:
+        client.update_listing("l1", status="paused")
+    assert patch_call.call_args[0][0].endswith("/v1/listings/l1")
+    assert patch_call.call_args[1]["json"]["status"] == "paused"

proxyhubb-0.1.0/PKG-INFO

@@ -1,54 +0,0 @@
-Metadata-Version: 2.4
-Name: proxyhubb
-Version: 0.1.0
-Summary: Official Python SDK for the ProxyHubb Bulk Proxy Pool API
-Author: ProxyHubb
-License: MIT
-Project-URL: Homepage, https://proxyhubb.com
-Project-URL: Repository, https://github.com/proxyhubb/proxyhubb
-Project-URL: Issues, https://github.com/proxyhubb/proxyhubb/issues
-Keywords: proxyhubb,proxy,sdk,api
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.31.0
-Requires-Dist: urllib3>=2.0.0
-Dynamic: license-file
-
-# proxyhubb
-
-Official Python client for the ProxyHubb Bulk Proxy Pool API.
-
-## Install
-
-```bash
-pip install proxyhubb
-```
-
-## Usage
-
-```python
-from proxyhubb import ProxyHubClient
-
-client = ProxyHubClient("phub_...")  # default: https://api.proxyhubb.com
-pool = client.create_pool("scrapers", size=5)
-proxies = client.as_requests_proxy(pool["id"])
-```
-
-Create an API key in the dashboard (`phub_…`).
-
-Gateway helper (optional):
-
-```python
-from proxyhubb import ProxyClient
-
-gw = ProxyClient(proxy_auth="user:pass")
-resp = gw.request("GET", "https://api.ipify.org")
-```
-
-## License
-
-MIT

proxyhubb-0.1.0/README.md

@@ -1,34 +0,0 @@
-# proxyhubb
-
-Official Python client for the ProxyHubb Bulk Proxy Pool API.
-
-## Install
-
-```bash
-pip install proxyhubb
-```
-
-## Usage
-
-```python
-from proxyhubb import ProxyHubClient
-
-client = ProxyHubClient("phub_...")  # default: https://api.proxyhubb.com
-pool = client.create_pool("scrapers", size=5)
-proxies = client.as_requests_proxy(pool["id"])
-```
-
-Create an API key in the dashboard (`phub_…`).
-
-Gateway helper (optional):
-
-```python
-from proxyhubb import ProxyClient
-
-gw = ProxyClient(proxy_auth="user:pass")
-resp = gw.request("GET", "https://api.ipify.org")
-```
-
-## License
-
-MIT

proxyhubb-0.1.0/proxyhubb/__init__.py

@@ -1,7 +0,0 @@
-"""Official ProxyHubb Python SDK."""
-
-from proxyhubb.client import ProxyHubClient, DEFAULT_BASE_URL
-from proxyhubb.proxy import ProxyClient
-
-__all__ = ["ProxyHubClient", "ProxyClient", "DEFAULT_BASE_URL"]
-__version__ = "0.1.0"

proxyhubb-0.1.0/proxyhubb/client.py

@@ -1,106 +0,0 @@
-"""ProxyHubb Python SDK — Bulk Proxy Pool Control API client."""
-
-from __future__ import annotations
-
-from typing import Any
-
-import requests
-
-DEFAULT_BASE_URL = "https://api.proxyhubb.com"
-
-
-class ProxyHubClient:
-    """Client for the ProxyHubb Bulk Proxy Pool API.
-
-    Parameters
-    ----------
-    api_key:
-        A ProxyHubb API key starting with ``phub_`` (or ``pk_``).
-    base_url:
-        Base URL of the Control API. Defaults to production.
-    """
-
-    def __init__(
-        self,
-        api_key: str,
-        base_url: str = DEFAULT_BASE_URL,
-    ) -> None:
-        if not api_key:
-            raise ValueError("api_key is required")
-        self._api_key = api_key
-        self._base_url = base_url.rstrip("/")
-        self._session = requests.Session()
-        self._session.headers.update({"X-API-Key": self._api_key})
-
-    def _url(self, path: str) -> str:
-        return f"{self._base_url}{path}"
-
-    def _get(self, path: str) -> dict[str, Any]:
-        resp = self._session.get(self._url(path))
-        resp.raise_for_status()
-        return resp.json()
-
-    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
-        resp = self._session.post(self._url(path), json=payload)
-        resp.raise_for_status()
-        return resp.json()
-
-    def _delete(self, path: str) -> None:
-        resp = self._session.delete(self._url(path))
-        resp.raise_for_status()
-
-    def create_pool(
-        self,
-        name: str,
-        size: int = 10,
-        session_type: str = "rotating",
-        description: str = "",
-        bytes_limit: int = 0,
-    ) -> dict[str, Any]:
-        """Create a new proxy pool."""
-        return self._post(
-            "/v1/bulk/pools",
-            {
-                "name": name,
-                "size": size,
-                "session_type": session_type,
-                "description": description,
-                "bytes_limit": bytes_limit,
-            },
-        )
-
-    def list_pools(self) -> dict[str, Any]:
-        """List proxy pools for the authenticated account."""
-        return self._get("/v1/bulk/pools")
-
-    def get_pool(self, pool_id: str) -> dict[str, Any]:
-        """Retrieve the endpoints of a proxy pool."""
-        return self._get(f"/v1/bulk/pools/{pool_id}/endpoints")
-
-    def get_proxies(self, pool_id: str) -> list[dict[str, Any]]:
-        """Return the list of endpoint dicts for a pool."""
-        data = self.get_pool(pool_id)
-        return data.get("endpoints", [])
-
-    def revoke_pool(self, pool_id: str) -> None:
-        """Soft-delete a proxy pool."""
-        self._delete(f"/v1/bulk/pools/{pool_id}")
-
-    def as_requests_proxy(self, pool_id: str, index: int = 0) -> dict[str, str]:
-        """Return a ``proxies`` dict compatible with the ``requests`` library.
-
-        Endpoint host/port come from the API (production buyer proxy is
-        ``proxy.proxyhubb.com:8090``).
-        """
-        endpoints = self.get_proxies(pool_id)
-        if not endpoints:
-            raise ValueError(f"Pool {pool_id!r} has no endpoints")
-        if index >= len(endpoints):
-            raise IndexError(
-                f"index {index} is out of range for pool with {len(endpoints)} endpoints"
-            )
-        ep = endpoints[index]
-        proxy_url = (
-            f"http://{ep['username']}:{ep['password']}@{ep['host']}:{ep['port']}"
-        )
-        return {"http": proxy_url, "https": proxy_url}

proxyhubb-0.1.0/proxyhubb.egg-info/PKG-INFO

@@ -1,54 +0,0 @@
-Metadata-Version: 2.4
-Name: proxyhubb
-Version: 0.1.0
-Summary: Official Python SDK for the ProxyHubb Bulk Proxy Pool API
-Author: ProxyHubb
-License: MIT
-Project-URL: Homepage, https://proxyhubb.com
-Project-URL: Repository, https://github.com/proxyhubb/proxyhubb
-Project-URL: Issues, https://github.com/proxyhubb/proxyhubb/issues
-Keywords: proxyhubb,proxy,sdk,api
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.31.0
-Requires-Dist: urllib3>=2.0.0
-Dynamic: license-file
-
-# proxyhubb
-
-Official Python client for the ProxyHubb Bulk Proxy Pool API.
-
-## Install
-
-```bash
-pip install proxyhubb
-```
-
-## Usage
-
-```python
-from proxyhubb import ProxyHubClient
-
-client = ProxyHubClient("phub_...")  # default: https://api.proxyhubb.com
-pool = client.create_pool("scrapers", size=5)
-proxies = client.as_requests_proxy(pool["id"])
-```
-
-Create an API key in the dashboard (`phub_…`).
-
-Gateway helper (optional):
-
-```python
-from proxyhubb import ProxyClient
-
-gw = ProxyClient(proxy_auth="user:pass")
-resp = gw.request("GET", "https://api.ipify.org")
-```
-
-## License
-
-MIT

proxyhubb-0.1.0/tests/test_client.py

@@ -1,20 +0,0 @@
-from proxyhubb import ProxyHubClient, ProxyClient, DEFAULT_BASE_URL
-
-
-def test_defaults():
-    assert DEFAULT_BASE_URL == "https://api.proxyhubb.com"
-    client = ProxyHubClient("phub_test")
-    assert client._base_url == "https://api.proxyhubb.com"
-
-
-def test_requires_api_key():
-    try:
-        ProxyHubClient("")
-        assert False, "expected ValueError"
-    except ValueError:
-        pass
-
-
-def test_proxy_client_default_gateway():
-    gw = ProxyClient()
-    assert "proxy.proxyhubb.com" in gw.gateway_url