hyperbrowser 0.90.7__tar.gz → 0.91.0__tar.gz

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperbrowser
-Version: 0.90.7
+Version: 0.91.0
 Summary: Python SDK for hyperbrowser
 License: MIT
 License-File: LICENSE
@@ -48,6 +48,12 @@ Both the sync and async client follow similar configuration params
 ### API Key
 The API key can be configured either from the constructor arguments or environment variables using `HYPERBROWSER_API_KEY`
 
+If no API key is provided, the client falls back to a saved OAuth session created by `hx auth login`. By default it reads `~/.hx_config/auth/default.json`, or `~/.hx_config/auth/<profile>.json` when `HYPERBROWSER_PROFILE` or `ClientConfig(profile=...)` is set.
+
+Profile names must match `^[A-Za-z0-9._-]+$`.
+
+`base_url` and `HYPERBROWSER_BASE_URL` accept either `https://host` or `https://host/api`. The client normalizes both to the same control-plane base URL.
+
 ## Usage
 
 ### Async

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/README.md

@@ -22,6 +22,12 @@ Both the sync and async client follow similar configuration params
 ### API Key
 The API key can be configured either from the constructor arguments or environment variables using `HYPERBROWSER_API_KEY`
 
+If no API key is provided, the client falls back to a saved OAuth session created by `hx auth login`. By default it reads `~/.hx_config/auth/default.json`, or `~/.hx_config/auth/<profile>.json` when `HYPERBROWSER_PROFILE` or `ClientConfig(profile=...)` is set.
+
+Profile names must match `^[A-Za-z0-9._-]+$`.
+
+`base_url` and `HYPERBROWSER_BASE_URL` accept either `https://host` or `https://host/api`. The client normalizes both to the same control-plane base URL.
+
 ## Usage
 
 ### Async

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/client/managers/async_manager/computer_action.py

@@ -18,6 +18,7 @@ from hyperbrowser.models import (
     ComputerActionMouseButton,
     GetClipboardTextActionParams,
     PutSelectionTextActionParams,
+    ListWindowsActionParams,
 )
 
 
@@ -175,3 +176,11 @@ class ComputerActionManager:
             text=text, return_screenshot=return_screenshot
         )
         return await self._execute_request(session, params)
+
+    async def list_windows(
+        self,
+        session: Union[SessionDetail, str],
+        return_screenshot: bool = False,
+    ) -> ComputerActionResponse:
+        params = ListWindowsActionParams(return_screenshot=return_screenshot)
+        return await self._execute_request(session, params)

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/client/managers/async_manager/session.py

@@ -2,6 +2,8 @@ from typing import List, Optional, Union, IO, overload
 import warnings
 from ....models.session import (
     BasicResponse,
+    CaptchaEvaluationParams,
+    CaptchaEvaluationResponse,
     CreateSessionParams,
     GetSessionDownloadsUrlResponse,
     GetSessionRecordingUrlResponse,
@@ -17,9 +19,13 @@ from ....models.session import (
     UpdateSessionProfileParams,
     UpdateSessionProxyParams,
     UpdateSessionScreenParams,
+    UpdateSessionSolveCaptchasParams,
+    UpdateSessionSolveCaptchasResponse,
     SessionGetParams,
 )
 
+CAPTCHA_EVALUATION_REQUEST_TIMEOUT_SECONDS = 185
+
 
 class SessionEventLogsManager:
     def __init__(self, client):
@@ -70,6 +76,21 @@ class SessionManager:
         )
         return BasicResponse(**response.data)
 
+    async def evaluate_captcha(
+        self,
+        id: str,
+        params: Optional[CaptchaEvaluationParams] = None,
+    ) -> CaptchaEvaluationResponse:
+        params_obj = params or CaptchaEvaluationParams()
+        response = await self._client.transport.post(
+            self._client._build_url(f"/session/{id}/captcha/evaluate"),
+            data=params_obj.model_dump(exclude_none=True, by_alias=True),
+            timeout=max(
+                self._client.timeout, CAPTCHA_EVALUATION_REQUEST_TIMEOUT_SECONDS
+            ),
+        )
+        return CaptchaEvaluationResponse(**response.data)
+
     async def list(
         self, params: SessionListParams = SessionListParams()
     ) -> SessionListResponse:
@@ -213,6 +234,36 @@ class SessionManager:
         )
         return BasicResponse(**response.data)
 
+    async def start_captcha_solving(
+        self,
+        id: str,
+        params: Optional[UpdateSessionSolveCaptchasParams] = None,
+    ) -> UpdateSessionSolveCaptchasResponse:
+        params_obj = params or UpdateSessionSolveCaptchasParams()
+        response = await self._client.transport.put(
+            self._client._build_url(f"/session/{id}/update"),
+            data={
+                "type": "solveCaptchas",
+                "params": {
+                    "enabled": True,
+                    **params_obj.model_dump(exclude_none=True, by_alias=True),
+                },
+            },
+        )
+        return UpdateSessionSolveCaptchasResponse(**response.data)
+
+    async def stop_captcha_solving(self, id: str) -> UpdateSessionSolveCaptchasResponse:
+        response = await self._client.transport.put(
+            self._client._build_url(f"/session/{id}/update"),
+            data={
+                "type": "solveCaptchas",
+                "params": {
+                    "enabled": False,
+                },
+            },
+        )
+        return UpdateSessionSolveCaptchasResponse(**response.data)
+
     def _warn_update_profile_params_boolean_deprecated(self) -> None:
         if SessionManager._has_warned_update_profile_params_boolean_deprecated:
             return

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/client/managers/sync_manager/computer_action.py

@@ -18,6 +18,7 @@ from hyperbrowser.models import (
     ComputerActionMouseButton,
     GetClipboardTextActionParams,
     PutSelectionTextActionParams,
+    ListWindowsActionParams,
 )
 
 
@@ -175,3 +176,11 @@ class ComputerActionManager:
             text=text, return_screenshot=return_screenshot
         )
         return self._execute_request(session, params)
+
+    def list_windows(
+        self,
+        session: Union[SessionDetail, str],
+        return_screenshot: bool = False,
+    ) -> ComputerActionResponse:
+        params = ListWindowsActionParams(return_screenshot=return_screenshot)
+        return self._execute_request(session, params)

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/client/managers/sync_manager/session.py

@@ -2,6 +2,8 @@ from typing import List, Optional, Union, IO, overload
 import warnings
 from ....models.session import (
     BasicResponse,
+    CaptchaEvaluationParams,
+    CaptchaEvaluationResponse,
     CreateSessionParams,
     GetSessionDownloadsUrlResponse,
     GetSessionRecordingUrlResponse,
@@ -16,9 +18,13 @@ from ....models.session import (
     UpdateSessionProfileParams,
     UpdateSessionProxyParams,
     UpdateSessionScreenParams,
+    UpdateSessionSolveCaptchasParams,
+    UpdateSessionSolveCaptchasResponse,
     SessionGetParams,
 )
 
+CAPTCHA_EVALUATION_REQUEST_TIMEOUT_SECONDS = 185
+
 
 class SessionEventLogsManager:
     def __init__(self, client):
@@ -69,6 +75,21 @@ class SessionManager:
         )
         return BasicResponse(**response.data)
 
+    def evaluate_captcha(
+        self,
+        id: str,
+        params: Optional[CaptchaEvaluationParams] = None,
+    ) -> CaptchaEvaluationResponse:
+        params_obj = params or CaptchaEvaluationParams()
+        response = self._client.transport.post(
+            self._client._build_url(f"/session/{id}/captcha/evaluate"),
+            data=params_obj.model_dump(exclude_none=True, by_alias=True),
+            timeout=max(
+                self._client.timeout, CAPTCHA_EVALUATION_REQUEST_TIMEOUT_SECONDS
+            ),
+        )
+        return CaptchaEvaluationResponse(**response.data)
+
     def list(
         self, params: SessionListParams = SessionListParams()
     ) -> SessionListResponse:
@@ -208,6 +229,36 @@ class SessionManager:
         )
         return BasicResponse(**response.data)
 
+    def start_captcha_solving(
+        self,
+        id: str,
+        params: Optional[UpdateSessionSolveCaptchasParams] = None,
+    ) -> UpdateSessionSolveCaptchasResponse:
+        params_obj = params or UpdateSessionSolveCaptchasParams()
+        response = self._client.transport.put(
+            self._client._build_url(f"/session/{id}/update"),
+            data={
+                "type": "solveCaptchas",
+                "params": {
+                    "enabled": True,
+                    **params_obj.model_dump(exclude_none=True, by_alias=True),
+                },
+            },
+        )
+        return UpdateSessionSolveCaptchasResponse(**response.data)
+
+    def stop_captcha_solving(self, id: str) -> UpdateSessionSolveCaptchasResponse:
+        response = self._client.transport.put(
+            self._client._build_url(f"/session/{id}/update"),
+            data={
+                "type": "solveCaptchas",
+                "params": {
+                    "enabled": False,
+                },
+            },
+        )
+        return UpdateSessionSolveCaptchasResponse(**response.data)
+
     def _warn_update_profile_params_boolean_deprecated(self) -> None:
         if SessionManager._has_warned_update_profile_params_boolean_deprecated:
             return

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/models/__init__.py

@@ -233,7 +233,10 @@ from .computer_action import (
     ComputerActionMouseButton,
     GetClipboardTextActionParams,
     PutSelectionTextActionParams,
+    ListWindowsActionParams,
+    ComputerActionWindow,
     ComputerActionResponseDataClipboardText,
+    ComputerActionResponseDataListWindows,
     ComputerActionResponseData,
 )
 from .session import (
@@ -259,10 +262,18 @@ from .session import (
     SessionLaunchState,
     UploadFileResponse,
     ImageCaptchaParam,
+    CaptchaSolverType,
+    CaptchaEvaluationPageResult,
+    CaptchaEvaluationParams,
+    CaptchaEvaluationResponse,
+    CaptchaEvaluationTarget,
+    CaptchaEvaluationType,
     UpdateSessionProfileParams,
     UpdateSessionProxyLocationParams,
     UpdateSessionProxyParams,
     UpdateSessionScreenParams,
+    UpdateSessionSolveCaptchasParams,
+    UpdateSessionSolveCaptchasResponse,
 )
 from .sandbox import (
     SandboxStatus,
@@ -521,10 +532,18 @@ __all__ = [
     "SessionLaunchState",
     "UploadFileResponse",
     "ImageCaptchaParam",
+    "CaptchaSolverType",
+    "CaptchaEvaluationPageResult",
+    "CaptchaEvaluationParams",
+    "CaptchaEvaluationResponse",
+    "CaptchaEvaluationTarget",
+    "CaptchaEvaluationType",
     "UpdateSessionProfileParams",
     "UpdateSessionProxyLocationParams",
     "UpdateSessionProxyParams",
     "UpdateSessionScreenParams",
+    "UpdateSessionSolveCaptchasParams",
+    "UpdateSessionSolveCaptchasResponse",
     # sandbox
     "SandboxStatus",
     "SandboxRegion",
@@ -548,6 +567,7 @@ __all__ = [
     "SandboxMemorySnapshotResult",
     "SandboxExposeParams",
     "SandboxExposeResult",
+    "SandboxUnexposeResult",
     "SandboxProcessStatus",
     "SandboxExecParams",
     "SandboxProcessSummary",
@@ -628,7 +648,10 @@ __all__ = [
     "ComputerActionMouseButton",
     "GetClipboardTextActionParams",
     "PutSelectionTextActionParams",
+    "ListWindowsActionParams",
+    "ComputerActionWindow",
     "ComputerActionResponseDataClipboardText",
+    "ComputerActionResponseDataListWindows",
     "ComputerActionResponseData",
     # web
     "StartBatchFetchJobParams",

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/models/computer_action.py

@@ -18,6 +18,7 @@ class ComputerAction(str, Enum):
     TYPE_TEXT = "type_text"
     GET_CLIPBOARD_TEXT = "get_clipboard_text"
     PUT_SELECTION_TEXT = "put_selection_text"
+    LIST_WINDOWS = "list_windows"
 
 
 ComputerActionMouseButton = Literal[
@@ -183,6 +184,17 @@ class PutSelectionTextActionParams(BaseModel):
     )
 
 
+class ListWindowsActionParams(BaseModel):
+    """Parameters for list windows action."""
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    action: Literal[ComputerAction.LIST_WINDOWS] = ComputerAction.LIST_WINDOWS
+    return_screenshot: bool = Field(
+        serialization_alias="returnScreenshot", default=False
+    )
+
+
 ComputerActionParams = Union[
     ClickActionParams,
     DragActionParams,
@@ -196,6 +208,7 @@ ComputerActionParams = Union[
     MouseUpActionParams,
     GetClipboardTextActionParams,
     PutSelectionTextActionParams,
+    ListWindowsActionParams,
 ]
 
 
@@ -207,7 +220,27 @@ class ComputerActionResponseDataClipboardText(BaseModel):
     clipboard_text: Optional[str] = Field(default=None, alias="clipboardText")
 
 
-ComputerActionResponseData = Union[ComputerActionResponseDataClipboardText]
+class ComputerActionWindow(BaseModel):
+    model_config = ConfigDict(populate_by_alias=True)
+
+    id: str
+    name: str
+    active: bool
+
+
+class ComputerActionResponseDataListWindows(BaseModel):
+    """Data for list windows action."""
+
+    model_config = ConfigDict(populate_by_alias=True)
+
+    active_window_id: str = Field(default="", alias="activeWindowId")
+    windows: List[ComputerActionWindow] = Field(default_factory=list)
+
+
+ComputerActionResponseData = Union[
+    ComputerActionResponseDataListWindows,
+    ComputerActionResponseDataClipboardText,
+]
 
 
 class ComputerActionResponse(BaseModel):

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/models/session.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import Any, List, Literal, Optional, Union, Dict
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
@@ -16,6 +16,16 @@ from hyperbrowser.models.consts import (
 )
 
 SessionStatus = Literal["active", "closed", "error"]
+CaptchaSolverType = Literal["visual"]
+CaptchaEvaluationType = Literal[
+    "turnstile",
+    "cloudflare-challenge",
+    "aliexpress",
+    "recaptcha",
+    "recaptcha-visual",
+    "amazon",
+]
+CaptchaEvaluationTarget = CaptchaEvaluationType
 
 
 class BasicResponse(BaseModel):
@@ -134,6 +144,7 @@ class SessionLaunchState(BaseModel):
     )
     enable_log_capture: Optional[bool] = Field(default=None, alias="enableLogCapture")
     accept_cookies: Optional[bool] = Field(default=None, alias="acceptCookies")
+    solver_type: Optional[CaptchaSolverType] = Field(default=None, alias="solverType")
     profile: Optional[SessionProfile] = Field(default=None, alias="profile")
     static_ip_id: Optional[str] = Field(default=None, alias="staticIpId")
     save_downloads: Optional[bool] = Field(default=None, alias="saveDownloads")
@@ -303,6 +314,75 @@ class ImageCaptchaParam(BaseModel):
     input_selector: str = Field(serialization_alias="inputSelector")
 
 
+class CaptchaEvaluationParams(BaseModel):
+    """
+    Parameters for manually evaluating captchas in a running session.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    captcha: Optional[CaptchaEvaluationTarget] = Field(default=None)
+    captcha_type: Optional[CaptchaEvaluationTarget] = Field(
+        default=None, serialization_alias="captchaType"
+    )
+    text: Optional[CaptchaEvaluationTarget] = Field(default=None)
+    iterations: Optional[int] = Field(default=None)
+    max_iterations: Optional[int] = Field(
+        default=None, serialization_alias="maxIterations"
+    )
+    solver_type: Optional[CaptchaSolverType] = Field(
+        default=None, serialization_alias="solverType"
+    )
+    image_captcha_params: Optional[List[ImageCaptchaParam]] = Field(
+        default=None, serialization_alias="imageCaptchaParams"
+    )
+    use_gemini_captcha_solver: Optional[bool] = Field(
+        default=None, serialization_alias="useGeminiCaptchaSolver"
+    )
+    use_ultra_stealth: Optional[bool] = Field(
+        default=None, serialization_alias="useUltraStealth"
+    )
+
+
+class CaptchaEvaluationPageResult(BaseModel):
+    """
+    Result of manually evaluating captchas on a single page target.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    url: str = Field(alias="url")
+    target_id: Optional[str] = Field(default=None, alias="targetId")
+    iterations_run: int = Field(alias="iterationsRun")
+    solved: bool = Field(alias="solved")
+    solved_captchas: List[CaptchaEvaluationType] = Field(alias="solvedCaptchas")
+    checked_captchas: List[CaptchaEvaluationType] = Field(alias="checkedCaptchas")
+    captcha_solved_counts: Dict[str, int] = Field(alias="captchaSolvedCounts")
+    last_solve_time: Dict[str, float] = Field(alias="lastSolveTime")
+
+
+class CaptchaEvaluationResponse(BaseModel):
+    """
+    Response from manually evaluating captchas in a running session.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    success: bool = Field(alias="success")
+    captcha: Optional[CaptchaEvaluationType] = Field(default=None, alias="captcha")
+    iterations_requested: int = Field(alias="iterationsRequested")
+    iterations_run: int = Field(alias="iterationsRun")
+    solved: bool = Field(alias="solved")
+    solved_captchas: List[CaptchaEvaluationType] = Field(alias="solvedCaptchas")
+    pages: List[CaptchaEvaluationPageResult] = Field(alias="pages")
+
+
 class CreateSessionParams(BaseModel):
     """
     Parameters for creating a new browser session.
@@ -337,6 +417,9 @@ class CreateSessionParams(BaseModel):
     locales: List[ISO639_1] = Field(default=["en"])
     screen: Optional[ScreenConfig] = Field(default=None)
     solve_captchas: bool = Field(default=False, serialization_alias="solveCaptchas")
+    solver_type: Optional[CaptchaSolverType] = Field(
+        default=None, serialization_alias="solverType"
+    )
     adblock: bool = Field(default=False, serialization_alias="adblock")
     trackers: bool = Field(default=False, serialization_alias="trackers")
     annoyances: bool = Field(default=False, serialization_alias="annoyances")
@@ -480,6 +563,35 @@ class UploadFileResponse(BaseModel):
     original_name: Optional[str] = Field(default=None, alias="originalName")
 
 
+class UpdateSessionSolveCaptchasParams(BaseModel):
+    """
+    Parameters for starting automatic captcha solving in a running session.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    solver_type: Optional[CaptchaSolverType] = Field(
+        default=None,
+        serialization_alias="solverType",
+    )
+
+
+class UpdateSessionSolveCaptchasResponse(BasicResponse):
+    """
+    Response from updating automatic captcha solving in a running session.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    solve_captchas: Optional[bool] = Field(default=None, alias="solveCaptchas")
+    session_id: Optional[str] = Field(default=None, alias="sessionId")
+    telemetry_ready: Optional[bool] = Field(default=None, alias="telemetryReady")
+
+
 class SessionEventLog(BaseModel):
     model_config = ConfigDict(
         populate_by_alias=True,

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/transport/async_transport.py

@@ -55,7 +55,7 @@ class AsyncTransport(TransportStrategy):
             try:
                 error_data = response.json()
                 message = error_data.get("message") or error_data.get("error") or str(e)
-            except:
+            except Exception:
                 message = str(e)
             raise HyperbrowserError(
                 message,
@@ -67,13 +67,20 @@ class AsyncTransport(TransportStrategy):
             raise HyperbrowserError("Request failed", original_error=e)
 
     async def post(
-        self, url: str, data: Optional[dict] = None, files: Optional[dict] = None
+        self,
+        url: str,
+        data: Optional[dict] = None,
+        files: Optional[dict] = None,
+        timeout: Optional[float] = None,
     ) -> APIResponse:
         try:
+            kwargs = {}
+            if timeout is not None:
+                kwargs["timeout"] = timeout
             if files:
-                response = await self.client.post(url, data=data, files=files)
+                response = await self.client.post(url, data=data, files=files, **kwargs)
             else:
-                response = await self.client.post(url, json=data)
+                response = await self.client.post(url, json=data, **kwargs)
             return await self._handle_response(response)
         except HyperbrowserError:
             raise

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/transport/base.py

@@ -45,7 +45,13 @@ class TransportStrategy(ABC):
         pass
 
     @abstractmethod
-    def post(self, url: str) -> APIResponse:
+    def post(
+        self,
+        url: str,
+        data: Optional[dict] = None,
+        files: Optional[dict] = None,
+        timeout: Optional[float] = None,
+    ) -> APIResponse:
         pass
 
     @abstractmethod

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/hyperbrowser/transport/sync.py

@@ -31,7 +31,7 @@ class SyncTransport(TransportStrategy):
             try:
                 error_data = response.json()
                 message = error_data.get("message") or error_data.get("error") or str(e)
-            except:
+            except Exception:
                 message = str(e)
             raise HyperbrowserError(
                 message,
@@ -46,13 +46,20 @@ class SyncTransport(TransportStrategy):
         self.client.close()
 
     def post(
-        self, url: str, data: Optional[dict] = None, files: Optional[dict] = None
+        self,
+        url: str,
+        data: Optional[dict] = None,
+        files: Optional[dict] = None,
+        timeout: Optional[float] = None,
     ) -> APIResponse:
         try:
+            kwargs = {}
+            if timeout is not None:
+                kwargs["timeout"] = timeout
             if files:
-                response = self.client.post(url, data=data, files=files)
+                response = self.client.post(url, data=data, files=files, **kwargs)
             else:
-                response = self.client.post(url, json=data)
+                response = self.client.post(url, json=data, **kwargs)
             return self._handle_response(response)
         except HyperbrowserError:
             raise

{hyperbrowser-0.90.7 → hyperbrowser-0.91.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "hyperbrowser"
-version = "0.90.7"
+version = "0.91.0"
 description = "Python SDK for hyperbrowser"
 authors = ["Nikhil Shahi <nshahi1998@gmail.com>"]
 license = "MIT"