smooth-py 0.3.0.dev20251014__tar.gz → 0.3.1__tar.gz

{smooth_py-0.3.0.dev20251014 → smooth_py-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: smooth-py
-Version: 0.3.0.dev20251014
+Version: 0.3.1
 Summary: 
 Author: Luca Pinchetti
 Author-email: luca@circlemind.co

{smooth_py-0.3.0.dev20251014 → smooth_py-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "smooth-py"
-version = "0.3.0.dev20251014"
+version = "0.3.1"
 description = ""
 authors = [
     {name = "Luca Pinchetti",email = "luca@circlemind.co"}

{smooth_py-0.3.0.dev20251014 → smooth_py-0.3.1}/src/smooth/__init__.py

@@ -1,6 +1,7 @@
 """Smooth python SDK."""
 
 import asyncio
+import base64
 import io
 import logging
 import os
@@ -8,7 +9,7 @@ import time
 import urllib.parse
 import warnings
 from pathlib import Path
-from typing import Any, Literal, Type
+from typing import Any, Literal, NotRequired, Type, TypedDict
 
 import httpx
 import requests
@@ -33,7 +34,47 @@ def _encode_url(url: str, interactive: bool = True, embed: bool = False) -> str:
 
 
 # --- Models ---
-# These models define the data structures for API requests and responses.
+
+class Certificate(TypedDict):
+  """Client certificate for accessing secure websites.
+
+  Attributes:
+      file: p12 file object to be uploaded (e.g., open("cert.p12", "rb")).
+      password: Password to decrypt the certificate file. Optional.
+  """
+
+  file: str | io.IOBase  # Required - base64 string or binary IO
+  password: NotRequired[str]  # Optional
+  filters: NotRequired[list[str]]  # Optional - TODO: Reserved for future use to specify URL patterns where the certificate should be applied.
+
+
+def _process_certificates(certificates: list[Certificate] | None) -> list[dict[str, Any]] | None:
+  """Process certificates, converting binary IO to base64-encoded strings.
+
+  Args:
+      certificates: List of certificates with file field as string or binary IO.
+
+  Returns:
+      List of certificates with file field as base64-encoded string, or None if input is None.
+  """
+  if certificates is None:
+    return None
+
+  processed_certs = []
+  for cert in certificates:
+    processed_cert = dict(cert)  # Create a copy
+
+    file_content = processed_cert["file"]
+    if isinstance(file_content, io.IOBase):
+      # Read the binary content and encode to base64
+      binary_data = file_content.read()
+      processed_cert["file"] = base64.b64encode(binary_data).decode("utf-8")
+    elif not isinstance(file_content, str):
+      raise TypeError(f"Certificate file must be a string or binary IO, got {type(file_content)}")
+
+    processed_certs.append(processed_cert)
+
+  return processed_certs
 
 
 class TaskResponse(BaseModel):
@@ -48,6 +89,8 @@ class TaskResponse(BaseModel):
   device: Literal["desktop", "mobile"] | None = Field(default=None, description="The device type used for the task.")
   live_url: str | None = Field(default=None, description="The URL to view and interact with the task execution.")
   recording_url: str | None = Field(default=None, description="The URL to view the task recording.")
+  downloads_url: str | None = Field(default=None, description="The URL of the archive containing the downloaded files.")
+  created_at: int | None = Field(default=None, description="The timestamp when the task was created.")
 
 
 class TaskRequest(BaseModel):
@@ -69,7 +112,7 @@ class TaskRequest(BaseModel):
   files: list[str] | None = Field(default=None, description="A list of file ids to pass to the agent.")
   agent: Literal["smooth", "smooth-lite"] = Field(default="smooth", description="The agent to use for the task.")
   max_steps: int = Field(default=32, ge=2, le=128, description="Maximum number of steps the agent can take (min 2, max 128).")
-  device: Literal["desktop", "mobile"] = Field(default="mobile", description="Device type for the task. Default is mobile.")
+  device: Literal["desktop", "mobile"] = Field(default="desktop", description="Device type for the task. Default is desktop.")
   allowed_urls: list[str] | None = Field(
     default=None,
     description=(
@@ -82,7 +125,11 @@ class TaskRequest(BaseModel):
     description=("Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials."),
   )
   profile_read_only: bool = Field(
-    default=False, description="If true, the profile specified by `profile_id` will be loaded in read-only mode."
+    default=False,
+    description=(
+      "If true, the profile specified by `profile_id` will be loaded in read-only mode. "
+      "Changes made during the task will not be saved back to the profile."
+    ),
   )
   stealth_mode: bool = Field(default=False, description="Run the browser in stealth mode.")
   proxy_server: str | None = Field(
@@ -93,6 +140,16 @@ class TaskRequest(BaseModel):
   )
   proxy_username: str | None = Field(default=None, description="Proxy server username.")
   proxy_password: str | None = Field(default=None, description="Proxy server password.")
+  certificates: list[dict[str, Any]] | None = Field(
+    default=None,
+    description=(
+      "List of client certificates to use when accessing secure websites. "
+      "Each certificate is a dictionary with the following fields:\n"
+      " - `file`: p12 file object to be uploaded (e.g., open('cert.p12', 'rb')).\n"
+      " - `password` (optional): Password to decrypt the certificate file."
+    ),
+  )
+  use_adblock: bool | None = Field(default=True, description="Enable adblock for the browser session. Default is True.")
   experimental_features: dict[str, Any] | None = Field(
     default=None, description="Experimental features to enable for the task."
   )
@@ -330,6 +387,10 @@ class BrowserSessionHandle(BaseModel):
       return _encode_url(self.browser_session.live_url, interactive=interactive, embed=embed)
     return None
 
+  def live_id(self):
+    """Returns the live ID for the browser session."""
+    return self.browser_session.live_id
+
 
 class TaskHandle:
   """A handle to a running task."""
@@ -393,10 +454,40 @@ class TaskHandle:
       task_response = self._client._get_task(self.id())
       self._task_response = task_response
       if task_response.recording_url is not None:
+        if not task_response.recording_url:
+          raise ApiError(
+            status_code=404,
+            detail=(
+              f"Recording URL not available for task {self.id()}."
+              " Set `enable_recording=True` when creating the task to enable it."
+            )
+          )
         return task_response.recording_url
       time.sleep(1)
     raise TimeoutError(f"Recording URL not available for task {self.id()}.")
 
+  def downloads_url(self, timeout: int | None = None) -> str:
+    """Returns the downloads URL for the task."""
+    if self._task_response and self._task_response.downloads_url is not None:
+      return self._task_response.downloads_url
+
+    start_time = time.time()
+    while timeout is None or (time.time() - start_time) < timeout:
+      task_response = self._client._get_task(self.id(), query_params={"downloads": "true"})
+      self._task_response = task_response
+      if task_response.downloads_url is not None:
+        if not task_response.downloads_url:
+          raise ApiError(
+            status_code=404,
+            detail=(
+              f"Downloads URL not available for task {self.id()}."
+              " Make sure the task downloaded files during its execution."
+            )
+          )
+        return task_response.downloads_url
+      time.sleep(1)
+    raise TimeoutError(f"Downloads URL not available for task {self.id()}.")
+
 
 class SmoothClient(BaseClient):
   """A synchronous client for the API."""
@@ -423,20 +514,21 @@ class SmoothClient(BaseClient):
   def _submit_task(self, payload: TaskRequest) -> TaskResponse:
     """Submits a task to be run."""
     try:
-      response = self._session.post(f"{self.base_url}/task", json=payload.model_dump(exclude_none=True))
+      response = self._session.post(f"{self.base_url}/task", json=payload.model_dump())
       data = self._handle_response(response)
       return TaskResponse(**data["r"])
     except requests.exceptions.RequestException as e:
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  def _get_task(self, task_id: str) -> TaskResponse:
+  def _get_task(self, task_id: str, query_params: dict[str, Any] | None = None) -> TaskResponse:
     """Retrieves the status and result of a task."""
     if not task_id:
       raise ValueError("Task ID cannot be empty.")
 
     try:
-      response = self._session.get(f"{self.base_url}/task/{task_id}")
+      url = f"{self.base_url}/task/{task_id}"
+      response = self._session.get(url, params=query_params)
       data = self._handle_response(response)
       return TaskResponse(**data["r"])
     except requests.exceptions.RequestException as e:
@@ -466,7 +558,7 @@ class SmoothClient(BaseClient):
     max_steps: int = 32,
     device: Literal["desktop", "mobile"] = "mobile",
     allowed_urls: list[str] | None = None,
-    enable_recording: bool = False,
+    enable_recording: bool = True,
     session_id: str | None = None,
     profile_id: str | None = None,
     profile_read_only: bool = False,
@@ -474,6 +566,8 @@ class SmoothClient(BaseClient):
     proxy_server: str | None = None,
     proxy_username: str | None = None,
     proxy_password: str | None = None,
+    certificates: list[Certificate] | None = None,
+    use_adblock: bool | None = True,
     experimental_features: dict[str, Any] | None = None,
   ) -> TaskHandle:
     """Runs a task and returns a handle to the task.
@@ -500,6 +594,11 @@ class SmoothClient(BaseClient):
         proxy_server: Proxy server url to route browser traffic through.
         proxy_username: Proxy server username.
         proxy_password: Proxy server password.
+        certificates: List of client certificates to use when accessing secure websites.
+          Each certificate is a dictionary with the following fields:
+          - `file` (required): p12 file object to be uploaded (e.g., open("cert.p12", "rb")).
+          - `password` (optional): Password to decrypt the certificate file, if password-protected.
+        use_adblock: Enable adblock for the browser session. Default is True.
         experimental_features: Experimental features to enable for the task.
 
     Returns:
@@ -525,6 +624,8 @@ class SmoothClient(BaseClient):
       proxy_server=proxy_server,
       proxy_username=proxy_username,
       proxy_password=proxy_password,
+      certificates=_process_certificates(certificates),
+      use_adblock=use_adblock,
       experimental_features=experimental_features,
     )
     initial_response = self._submit_task(payload)
@@ -550,7 +651,7 @@ class SmoothClient(BaseClient):
     try:
       response = self._session.post(
         f"{self.base_url}/browser/session",
-        json=BrowserSessionRequest(profile_id=profile_id or session_id, live_view=live_view).model_dump(exclude_none=True),
+        json=BrowserSessionRequest(profile_id=profile_id or session_id, live_view=live_view).model_dump(),
       )
       data = self._handle_response(response)
       return BrowserSessionHandle(browser_session=BrowserSessionResponse(**data["r"]))
@@ -577,7 +678,7 @@ class SmoothClient(BaseClient):
         ApiException: If the API request fails.
     """
     try:
-      response = self._session.get(f"{self.base_url}/browser/session")
+      response = self._session.get(f"{self.base_url}/browser/profile")
       data = self._handle_response(response)
       return BrowserProfilesResponse(**data["r"])
     except requests.exceptions.RequestException as e:
@@ -592,7 +693,7 @@ class SmoothClient(BaseClient):
   def delete_profile(self, profile_id: str):
     """Delete a browser profile."""
     try:
-      response = self._session.delete(f"{self.base_url}/browser/session/{profile_id}")
+      response = self._session.delete(f"{self.base_url}/browser/profile/{profile_id}")
       self._handle_response(response)
     except requests.exceptions.RequestException as e:
       logger.error(f"Request failed: {e}")
@@ -711,11 +812,42 @@ class AsyncTaskHandle:
       task_response = await self._client._get_task(self.id())
       self._task_response = task_response
       if task_response.recording_url is not None:
+        if not task_response.recording_url:
+          raise ApiError(
+            status_code=404,
+            detail=(
+              f"Recording URL not available for task {self.id()}."
+              " Set `enable_recording=True` when creating the task to enable it."
+            )
+          )
         return task_response.recording_url
       await asyncio.sleep(1)
 
     raise TimeoutError(f"Recording URL not available for task {self.id()}.")
 
+  async def downloads_url(self, timeout: int | None = None) -> str:
+    """Returns the downloads URL for the task."""
+    if self._task_response and self._task_response.downloads_url is not None:
+      return self._task_response.downloads_url
+
+    start_time = time.time()
+    while timeout is None or (time.time() - start_time) < timeout:
+      task_response = await self._client._get_task(self.id(), query_params={"downloads": "true"})
+      self._task_response = task_response
+      if task_response.downloads_url is not None:
+        if not task_response.downloads_url:
+          raise ApiError(
+            status_code=404,
+            detail=(
+              f"Downloads URL not available for task {self.id()}."
+              " Make sure the task downloaded files during its execution."
+            )
+          )
+        return task_response.downloads_url
+      await asyncio.sleep(1)
+
+    raise TimeoutError(f"Downloads URL not available for task {self.id()}.")
+
 
 class SmoothAsyncClient(BaseClient):
   """An asynchronous client for the API."""
@@ -736,20 +868,21 @@ class SmoothAsyncClient(BaseClient):
   async def _submit_task(self, payload: TaskRequest) -> TaskResponse:
     """Submits a task to be run asynchronously."""
     try:
-      response = await self._client.post(f"{self.base_url}/task", json=payload.model_dump(exclude_none=True))
+      response = await self._client.post(f"{self.base_url}/task", json=payload.model_dump())
       data = self._handle_response(response)
       return TaskResponse(**data["r"])
     except httpx.RequestError as e:
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-  async def _get_task(self, task_id: str) -> TaskResponse:
+  async def _get_task(self, task_id: str, query_params: dict[str, Any] | None = None) -> TaskResponse:
     """Retrieves the status and result of a task asynchronously."""
     if not task_id:
       raise ValueError("Task ID cannot be empty.")
 
     try:
-      response = await self._client.get(f"{self.base_url}/task/{task_id}")
+      url = f"{self.base_url}/task/{task_id}"
+      response = await self._client.get(url, params=query_params)
       data = self._handle_response(response)
       return TaskResponse(**data["r"])
     except httpx.RequestError as e:
@@ -779,7 +912,7 @@ class SmoothAsyncClient(BaseClient):
     max_steps: int = 32,
     device: Literal["desktop", "mobile"] = "mobile",
     allowed_urls: list[str] | None = None,
-    enable_recording: bool = False,
+    enable_recording: bool = True,
     session_id: str | None = None,
     profile_id: str | None = None,
     profile_read_only: bool = False,
@@ -787,6 +920,8 @@ class SmoothAsyncClient(BaseClient):
     proxy_server: str | None = None,
     proxy_username: str | None = None,
     proxy_password: str | None = None,
+    certificates: list[Certificate] | None = None,
+    use_adblock: bool | None = True,
     experimental_features: dict[str, Any] | None = None,
   ) -> AsyncTaskHandle:
     """Runs a task and returns a handle to the task asynchronously.
@@ -813,6 +948,11 @@ class SmoothAsyncClient(BaseClient):
         proxy_server: Proxy server url to route browser traffic through.
         proxy_username: Proxy server username.
         proxy_password: Proxy server password.
+        certificates: List of client certificates to use when accessing secure websites.
+          Each certificate is a dictionary with the following fields:
+          - `file` (required): p12 file object to be uploaded (e.g., open("cert.p12", "rb")).
+          - `password` (optional): Password to decrypt the certificate file.
+        use_adblock: Enable adblock for the browser session. Default is True.
         experimental_features: Experimental features to enable for the task.
 
     Returns:
@@ -838,6 +978,8 @@ class SmoothAsyncClient(BaseClient):
       proxy_server=proxy_server,
       proxy_username=proxy_username,
       proxy_password=proxy_password,
+      certificates=_process_certificates(certificates),
+      use_adblock=use_adblock,
       experimental_features=experimental_features,
     )
 
@@ -863,7 +1005,7 @@ class SmoothAsyncClient(BaseClient):
     try:
       response = await self._client.post(
         f"{self.base_url}/browser/session",
-        json=BrowserSessionRequest(profile_id=profile_id or session_id, live_view=live_view).model_dump(exclude_none=True),
+        json=BrowserSessionRequest(profile_id=profile_id or session_id, live_view=live_view).model_dump(),
       )
       data = self._handle_response(response)
       return BrowserSessionHandle(browser_session=BrowserSessionResponse(**data["r"]))
@@ -890,7 +1032,7 @@ class SmoothAsyncClient(BaseClient):
         ApiException: If the API request fails.
     """
     try:
-      response = await self._client.get(f"{self.base_url}/browser/session")
+      response = await self._client.get(f"{self.base_url}/browser/profile")
       data = self._handle_response(response)
       return BrowserProfilesResponse(**data["r"])
     except httpx.RequestError as e:
@@ -905,7 +1047,7 @@ class SmoothAsyncClient(BaseClient):
   async def delete_profile(self, profile_id: str):
     """Delete a browser profile."""
     try:
-      response = await self._client.delete(f"{self.base_url}/browser/session/{profile_id}")
+      response = await self._client.delete(f"{self.base_url}/browser/profile/{profile_id}")
       self._handle_response(response)
     except httpx.RequestError as e:
       logger.error(f"Request failed: {e}")
@@ -976,6 +1118,7 @@ __all__ = [
   "BrowserSessionResponse",
   "BrowserSessionsResponse",
   "UploadFileResponse",
+  "Certificate",
   "ApiError",
   "TimeoutError",
 ]