tinyfish 0.2.4__tar.gz → 0.2.5__tar.gz

tinyfish-0.2.5/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

{tinyfish-0.2.4 → tinyfish-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyfish
-Version: 0.2.4
+Version: 0.2.5
 Summary: Official Python SDK for the TinyFish API
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0

{tinyfish-0.2.4 → tinyfish-0.2.5}/RELEASE.md

@@ -33,13 +33,13 @@ Commit and merge to main.
 ### Step 2: Create a GitHub Release
 
 1. Go to the `ux-labs` repo on GitHub → **Releases** → **Draft a new release**
-2. Set the tag to match the version exactly, prefixed with `v`:
-   - Version `0.2.0` → tag `v0.2.0`
+2. Set the tag to match the version exactly, prefixed with `sdk-py/v`:
+   - Version `0.2.0` → tag `sdk-py/v0.2.0`
 3. Set the target to `main`
 4. Write release notes summarizing what changed
 5. Click **Publish release**
 
-The workflow validates that the tag matches the version in `pyproject.toml` — if they don't match, the build fails before anything is published.
+The CD workflow (`CD_sdk_python.yml`) only triggers on tags prefixed with `sdk-py/v`. It validates that the version portion of the tag matches `pyproject.toml` — if they don't match, the build fails before anything is published.
 
 ### Step 3: Monitor the workflow
 
@@ -56,13 +56,13 @@ After the workflow completes, verify the release:
 
 ```bash
 pip install tinyfish==0.2.0
-python -c "from tinyfish import Tinyfish; print('ok')"
+python -c "from tinyfish import TinyFish; print('ok')"
 ```
 
 ## Troubleshooting
 
 **Tag does not match pyproject.toml version**
-The build job validates that the git tag (e.g., `v0.2.0`) matches the version in `pyproject.toml` (e.g., `0.2.0`). Fix by updating `pyproject.toml` to match the tag before publishing, then delete and recreate the release.
+The build job validates that the git tag (e.g., `sdk-py/v0.2.0`) matches the version in `pyproject.toml` (e.g., `0.2.0`). Fix by updating `pyproject.toml` to match the tag before publishing, then delete and recreate the release.
 
 **403 / authentication error**
 Verify that `PYPI_API_TOKEN` has been added to the `ux-labs` repo secrets in `github-control`. The token must exist as a GitHub Actions secret before the workflow can publish.

{tinyfish-0.2.4 → tinyfish-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tinyfish"
-version = "0.2.4"
+version = "0.2.5"
 description = "Official Python SDK for the TinyFish API"
 readme = "README.md"
 requires-python = ">=3.11"

{tinyfish-0.2.4 → tinyfish-0.2.5}/src/tinyfish/__init__.py

@@ -26,8 +26,6 @@ from ._utils.exceptions import (
 
 # Agent resource
 from .agent import AgentStream, AsyncAgentStream
-
-# Agent types
 from .agent.types import (
     AgentRunAsyncResponse,
     AgentRunResponse,
@@ -42,7 +40,16 @@ from .agent.types import (
     StartedEvent,
     StreamingUrlEvent,
 )
+
+# Browser types
+from .browser.types import BrowserSession, BrowserSessionCreateParams
 from .client import AsyncTinyFish, TinyFish
+from .fetch.types import (
+    FetchError,
+    FetchFormat,
+    FetchResponse,
+    FetchResult,
+)
 
 # Runs types
 from .runs.types import (
@@ -55,6 +62,9 @@ from .runs.types import (
     SortDirection,
 )
 
+# Search types
+from .search.types import SearchQueryResponse, SearchResult
+
 __version__ = version("tinyfish")
 
 __all__ = [
@@ -80,6 +90,9 @@ __all__ = [
     # Agent resource
     "AgentStream",
     "AsyncAgentStream",
+    # Browser types
+    "BrowserSession",
+    "BrowserSessionCreateParams",
     # Agent types
     "EventType",
     "BrowserProfile",
@@ -93,6 +106,14 @@ __all__ = [
     "HeartbeatEvent",
     "CompleteEvent",
     "AgentRunWithStreamingResponse",
+    # Fetch types
+    "FetchFormat",
+    "FetchResult",
+    "FetchError",
+    "FetchResponse",
+    # Search types
+    "SearchResult",
+    "SearchQueryResponse",
     # Runs types
     "ErrorCategory",
     "SortDirection",

{tinyfish-0.2.4 → tinyfish-0.2.5}/src/tinyfish/agent/types.py

@@ -186,7 +186,7 @@ class CompleteEvent(BaseModel):
     status: RunStatus = Field(..., description="Final status of the automation")
     timestamp: datetime = Field(..., description="Timestamp of the event")
     result_json: dict[str, object] | None = Field(
-        None, alias="resultJson", description="Structured JSON result extracted from the automation"
+        None, alias="result", description="Structured JSON result extracted from the automation"
     )
     error: RunError | None = Field(None, description="Error details if the run failed. None if succeeded.")
 

tinyfish-0.2.5/src/tinyfish/browser/__init__.py

@@ -0,0 +1,86 @@
+"""Browser resource for creating remote browser sessions."""
+
+from __future__ import annotations
+
+from tinyfish._utils.client import BaseAsyncAPIClient, BaseSyncAPIClient
+from tinyfish._utils.resource import BaseAsyncAPIResource, BaseSyncAPIResource
+
+from .types import BrowserSession, BrowserSessionCreateParams
+
+
+class BrowserSessionsResource(BaseSyncAPIResource):
+    """Create remote browser sessions (sync)."""
+
+    def create(
+        self,
+        *,
+        url: str | None = None,
+        timeout_seconds: int | None = None,
+    ) -> BrowserSession:
+        """Create a new remote browser session.
+
+        Args:
+            url: Target URL for the browser session. If omitted, browser starts at about:blank.
+            timeout_seconds: Inactivity timeout in seconds. If omitted or exceeds plan max,
+                the plan max is used.
+
+        Returns:
+            BrowserSession with session_id, cdp_url, and base_url.
+
+        Raises:
+            BadRequestError: Invalid parameters.
+            AuthenticationError: Invalid API key.
+        """
+        params = BrowserSessionCreateParams(url=url, timeout_seconds=timeout_seconds)
+        body = params.model_dump(exclude_none=True)
+        return self._post("/v1/browser", json=body, cast_to=BrowserSession)
+
+
+class AsyncBrowserSessionsResource(BaseAsyncAPIResource):
+    """Create remote browser sessions (async)."""
+
+    async def create(
+        self,
+        *,
+        url: str | None = None,
+        timeout_seconds: int | None = None,
+    ) -> BrowserSession:
+        """Create a new remote browser session.
+
+        Async version of `BrowserSessionsResource.create()`.
+
+        Args:
+            url: Target URL for the browser session. If omitted, browser starts at about:blank.
+            timeout_seconds: Inactivity timeout in seconds. If omitted or exceeds plan max,
+                the plan max is used.
+
+        Returns:
+            BrowserSession with session_id, cdp_url, and base_url.
+
+        Raises:
+            BadRequestError: Invalid parameters.
+            AuthenticationError: Invalid API key.
+        """
+        params = BrowserSessionCreateParams(url=url, timeout_seconds=timeout_seconds)
+        body = params.model_dump(exclude_none=True)
+        return await self._post("/v1/browser", json=body, cast_to=BrowserSession)
+
+
+class BrowserResource(BaseSyncAPIResource):
+    """Browser API namespace (sync)."""
+
+    sessions: BrowserSessionsResource
+
+    def __init__(self, client: BaseSyncAPIClient) -> None:
+        super().__init__(client)
+        self.sessions = BrowserSessionsResource(client)
+
+
+class AsyncBrowserResource(BaseAsyncAPIResource):
+    """Browser API namespace (async)."""
+
+    sessions: AsyncBrowserSessionsResource
+
+    def __init__(self, client: BaseAsyncAPIClient) -> None:
+        super().__init__(client)
+        self.sessions = AsyncBrowserSessionsResource(client)

tinyfish-0.2.5/src/tinyfish/browser/types.py

@@ -0,0 +1,24 @@
+"""Browser API request/response types."""
+
+from pydantic import BaseModel, Field
+
+
+class BrowserSessionCreateParams(BaseModel):
+    """Parameters for `browser.sessions.create()`."""
+
+    url: str | None = Field(
+        None,
+        description="Target URL for the browser session. If omitted, browser starts at about:blank.",
+    )
+    timeout_seconds: int | None = Field(
+        None,
+        description="Inactivity timeout in seconds. If omitted or exceeds plan max, the plan max is used.",
+    )
+
+
+class BrowserSession(BaseModel):
+    """Response from creating a browser session."""
+
+    session_id: str = Field(..., description="Unique session identifier")
+    cdp_url: str = Field(..., description="CDP WebSocket URL for direct browser connection")
+    base_url: str = Field(..., description="HTTPS base URL for the browser session")

{tinyfish-0.2.4 → tinyfish-0.2.5}/src/tinyfish/client.py

@@ -4,7 +4,10 @@ from tinyfish._utils.client import BaseAsyncAPIClient, BaseSyncAPIClient
 from tinyfish._utils.client._base import _DEFAULT_TIMEOUT
 
 from .agent import AgentResource, AsyncAgentResource
+from .browser import AsyncBrowserResource, BrowserResource
+from .fetch import AsyncFetchResource, FetchResource
 from .runs import AsyncRunsResource, RunsResource
+from .search import AsyncSearchResource, SearchResource
 
 __all__ = ["TinyFish", "AsyncTinyFish"]
 
@@ -21,7 +24,10 @@ class TinyFish(BaseSyncAPIClient):
     # __init__ assignments below — which means no autocomplete for users who just
     # did `pip install tinyfish`.
     agent: AgentResource
+    browser: BrowserResource
+    fetch: FetchResource
     runs: RunsResource
+    search: SearchResource
 
     def __init__(
         self,
@@ -42,7 +48,10 @@ class TinyFish(BaseSyncAPIClient):
         )
 
         self.agent = AgentResource(self)
+        self.browser = BrowserResource(self)
+        self.fetch = FetchResource(self)
         self.runs = RunsResource(self)
+        self.search = SearchResource(self)
 
 
 class AsyncTinyFish(BaseAsyncAPIClient):
@@ -52,7 +61,10 @@ class AsyncTinyFish(BaseAsyncAPIClient):
     # checkers recognise these as AsyncAgentResource / AsyncRunsResource (not
     # the sync variants) when resolving types from an installed package.
     agent: AsyncAgentResource
+    browser: AsyncBrowserResource
+    fetch: AsyncFetchResource
     runs: AsyncRunsResource
+    search: AsyncSearchResource
 
     def __init__(
         self,
@@ -73,4 +85,7 @@ class AsyncTinyFish(BaseAsyncAPIClient):
         )
 
         self.agent = AsyncAgentResource(self)
+        self.browser = AsyncBrowserResource(self)
+        self.fetch = AsyncFetchResource(self)
         self.runs = AsyncRunsResource(self)
+        self.search = AsyncSearchResource(self)

tinyfish-0.2.5/src/tinyfish/fetch/__init__.py

@@ -0,0 +1,99 @@
+"""Fetch resource for extracting clean content from URLs."""
+
+from __future__ import annotations
+
+from tinyfish._utils.exceptions import SDKError
+from tinyfish._utils.resource import BaseAsyncAPIResource, BaseSyncAPIResource
+
+from .types import FetchFormat, FetchResponse
+
+MIN_URLS = 1
+MAX_URLS = 10
+
+
+class FetchResource(BaseSyncAPIResource):
+    """Fetch and extract clean content from URLs."""
+
+    def get_contents(
+        self,
+        urls: list[str],
+        *,
+        format: FetchFormat | None = None,
+        links: bool | None = None,
+        image_links: bool | None = None,
+    ) -> FetchResponse:
+        """Fetch and extract content from one or more URLs.
+
+        Args:
+            urls: List of URLs to fetch (1-10 items).
+            format: Output format — "markdown", "html", or "json".
+            links: Whether to extract links from the page.
+            image_links: Whether to extract image links from the page.
+
+        Returns:
+            FetchResponse with results and errors lists.
+
+        Raises:
+            SDKError: urls is empty or has more than 10 items.
+            AuthenticationError: Invalid API key.
+        """
+        _validate_urls(urls)
+        body = _build_body(urls, format=format, links=links, image_links=image_links)
+        return self._post("/v1/fetch", json=body, cast_to=FetchResponse)
+
+
+class AsyncFetchResource(BaseAsyncAPIResource):
+    """Async fetch and extract clean content from URLs."""
+
+    async def get_contents(
+        self,
+        urls: list[str],
+        *,
+        format: FetchFormat | None = None,
+        links: bool | None = None,
+        image_links: bool | None = None,
+    ) -> FetchResponse:
+        """Fetch and extract content from one or more URLs.
+
+        Async version of `FetchResource.get_contents()`.
+
+        Args:
+            urls: List of URLs to fetch (1-10 items).
+            format: Output format — "markdown", "html", or "json".
+            links: Whether to extract links from the page.
+            image_links: Whether to extract image links from the page.
+
+        Returns:
+            FetchResponse with results and errors lists.
+
+        Raises:
+            SDKError: urls is empty or has more than 10 items.
+            AuthenticationError: Invalid API key.
+        """
+        _validate_urls(urls)
+        body = _build_body(urls, format=format, links=links, image_links=image_links)
+        return await self._post("/v1/fetch", json=body, cast_to=FetchResponse)
+
+
+def _validate_urls(urls: list[str]) -> None:
+    if len(urls) < MIN_URLS:
+        raise SDKError("urls must be a non-empty array")
+    if len(urls) > MAX_URLS:
+        raise SDKError("urls must contain at most 10 items")
+
+
+def _build_body(
+    urls: list[str],
+    *,
+    format: FetchFormat | None,
+    links: bool | None,
+    image_links: bool | None,
+) -> dict[str, object]:
+    body: dict[str, object] = {"urls": urls}
+    if format is not None:
+        body["format"] = format
+    if links is not None:
+        body["links"] = links
+    if image_links is not None:
+        body["image_links"] = image_links
+    return body

tinyfish-0.2.5/src/tinyfish/fetch/types.py

@@ -0,0 +1,40 @@
+"""Fetch API request/response types."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+FetchFormat = Literal["markdown", "html", "json"]
+
+
+class FetchResult(BaseModel):
+    """A single successfully fetched URL result."""
+
+    url: str = Field(..., description="The original requested URL")
+    final_url: str | None = Field(None, description="The final URL after redirects")
+    title: str | None = Field(None, description="Page title")
+    description: str | None = Field(None, description="Page meta description")
+    language: str | None = Field(None, description="Detected language code")
+    author: str | None = Field(None, description="Content author")
+    published_date: str | None = Field(None, description="Publication date")
+    text: str | None = Field(None, description="Extracted content in the requested format")
+    format: FetchFormat = Field(..., description="Output format used")
+    links: list[str] = Field(default_factory=list, description="Extracted links")
+    image_links: list[str] = Field(default_factory=list, description="Extracted image links")
+    latency_ms: float | None = Field(None, description="Fetch latency in milliseconds")
+
+
+class FetchError(BaseModel):
+    """A single failed fetch result."""
+
+    url: str = Field(..., description="The URL that failed")
+    error: str = Field(..., description="Error message")
+
+
+class FetchResponse(BaseModel):
+    """Response from POST /v1/fetch."""
+
+    results: list[FetchResult] = Field(..., description="Successfully fetched results")
+    errors: list[FetchError] = Field(..., description="Failed fetch results")

tinyfish-0.2.5/src/tinyfish/search/__init__.py

@@ -0,0 +1,79 @@
+"""Search API resource."""
+
+from __future__ import annotations
+
+from tinyfish._utils.resource import BaseAsyncAPIResource, BaseSyncAPIResource
+
+from .types import SearchQueryResponse
+
+
+class SearchResource(BaseSyncAPIResource):
+    """Search the web using TinyFish's search API."""
+
+    def query(
+        self,
+        query: str,
+        *,
+        location: str | None = None,
+        language: str | None = None,
+    ) -> SearchQueryResponse:
+        """Execute a web search query.
+
+        Args:
+            query: The search query string.
+            location: Optional location to scope results (e.g. "United States").
+            language: Optional language code (e.g. "en").
+
+        Returns:
+            SearchQueryResponse with query echo, results list, and total count.
+
+        Raises:
+            ValueError: query is empty or whitespace.
+            AuthenticationError: Invalid API key.
+            RateLimitError: Too many requests.
+        """
+        if not query or not query.strip():
+            raise ValueError("query must be a non-empty string")
+        params: dict[str, str] = {"query": query}
+        if location is not None:
+            params["location"] = location
+        if language is not None:
+            params["language"] = language
+        return self._get("/v1/search", params=params, cast_to=SearchQueryResponse)
+
+
+class AsyncSearchResource(BaseAsyncAPIResource):
+    """Async search the web using TinyFish's search API."""
+
+    async def query(
+        self,
+        query: str,
+        *,
+        location: str | None = None,
+        language: str | None = None,
+    ) -> SearchQueryResponse:
+        """Execute a web search query.
+
+        Async version of `SearchResource.query()`.
+
+        Args:
+            query: The search query string.
+            location: Optional location to scope results (e.g. "United States").
+            language: Optional language code (e.g. "en").
+
+        Returns:
+            SearchQueryResponse with query echo, results list, and total count.
+
+        Raises:
+            ValueError: query is empty or whitespace.
+            AuthenticationError: Invalid API key.
+            RateLimitError: Too many requests.
+        """
+        if not query or not query.strip():
+            raise ValueError("query must be a non-empty string")
+        params: dict[str, str] = {"query": query}
+        if location is not None:
+            params["location"] = location
+        if language is not None:
+            params["language"] = language
+        return await self._get("/v1/search", params=params, cast_to=SearchQueryResponse)

tinyfish-0.2.5/src/tinyfish/search/types.py

@@ -0,0 +1,21 @@
+"""Search API request/response types."""
+
+from pydantic import BaseModel, Field
+
+
+class SearchResult(BaseModel):
+    """A single search result item."""
+
+    position: int = Field(..., description="Position in the search results")
+    site_name: str = Field(..., description="Domain name of the result")
+    snippet: str = Field(..., description="Text snippet from the result")
+    title: str = Field(..., description="Title of the result")
+    url: str = Field(..., description="URL of the result")
+
+
+class SearchQueryResponse(BaseModel):
+    """Response from a search query."""
+
+    query: str = Field(..., description="The search query that was executed")
+    results: list[SearchResult] = Field(..., description="List of search results")
+    total_results: int = Field(..., description="Total number of results found")

{tinyfish-0.2.4 → tinyfish-0.2.5}/tests/test_agent.py

@@ -56,7 +56,7 @@ _EV_COMPLETE_OK: dict[str, Any] = {
     "runId": _RUN_ID,
     "status": "COMPLETED",
     "timestamp": _TS,
-    "resultJson": {"price": "$999"},
+    "result": {"price": "$999"},
     "error": None,
 }
 _EV_COMPLETE_FAIL: dict[str, Any] = {
@@ -64,7 +64,7 @@ _EV_COMPLETE_FAIL: dict[str, Any] = {
     "runId": _RUN_ID,
     "status": "FAILED",
     "timestamp": _TS,
-    "resultJson": None,
+    "result": None,
     "error": {"message": "something went wrong", "category": "AGENT_FAILURE"},
 }
 _EV_COMPLETE_CANCELLED: dict[str, Any] = {
@@ -72,7 +72,7 @@ _EV_COMPLETE_CANCELLED: dict[str, Any] = {
     "runId": _RUN_ID,
     "status": "CANCELLED",
     "timestamp": _TS,
-    "resultJson": None,
+    "result": None,
     "error": None,
 }
 

tinyfish-0.2.5/tests/test_browser.py

@@ -0,0 +1,141 @@
+"""Tests for browser.sessions.create() — sync and async."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+from respx import MockRouter
+
+from tests.conftest import BASE_URL
+from tinyfish import AsyncTinyFish, AuthenticationError, BadRequestError, InternalServerError, TinyFish
+from tinyfish.browser.types import BrowserSession
+
+# ─── Constants ────────────────────────────────────────────────────────────────
+
+_BROWSER_PATH = "/v1/browser"
+_SESSION_ID = "tf-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+_CDP_URL = "wss://tetra-abc123.cluster.example.com/cdp"
+_BASE_URL = "https://tetra-abc123.cluster.example.com"
+
+
+def _session_response(**overrides: Any) -> dict[str, Any]:
+    base: dict[str, Any] = {
+        "session_id": _SESSION_ID,
+        "cdp_url": _CDP_URL,
+        "base_url": _BASE_URL,
+    }
+    return {**base, **overrides}
+
+
+# ─── Param cases shared by sync and async ─────────────────────────────────────
+
+_PARAM_CASES: list[tuple[str, dict[str, Any], dict[str, Any]]] = [
+    ("url_only", {"url": "https://example.com"}, {"url": "https://example.com"}),
+    ("timeout_only", {"timeout_seconds": 300}, {"timeout_seconds": 300}),
+    (
+        "both",
+        {"url": "https://example.com", "timeout_seconds": 600},
+        {"url": "https://example.com", "timeout_seconds": 600},
+    ),
+]
+
+_ERROR_CASES: list[tuple[int, type[Exception]]] = [
+    (400, BadRequestError),
+    (401, AuthenticationError),
+    (500, InternalServerError),
+]
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# browser.sessions.create() — sync
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_create_returns_browser_session(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.post(_BROWSER_PATH).mock(return_value=httpx.Response(201, json=_session_response()))
+    result = client.browser.sessions.create()
+    assert isinstance(result, BrowserSession)
+    assert result.session_id == _SESSION_ID
+    assert result.cdp_url == _CDP_URL
+    assert result.base_url == _BASE_URL
+
+
+@pytest.mark.parametrize("name,kwargs,expected", _PARAM_CASES, ids=[c[0] for c in _PARAM_CASES])
+@pytest.mark.respx(base_url=BASE_URL)
+def test_create_sends_params(name: str, kwargs: dict, expected: dict, client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.post(_BROWSER_PATH).mock(return_value=httpx.Response(201, json=_session_response()))
+    client.browser.sessions.create(**kwargs)
+    parsed = json.loads(route.calls[0].request.content)
+    for key, value in expected.items():
+        assert parsed[key] == value
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_create_omits_none_values(client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.post(_BROWSER_PATH).mock(return_value=httpx.Response(201, json=_session_response()))
+    client.browser.sessions.create()
+    parsed = json.loads(route.calls[0].request.content)
+    assert "url" not in parsed
+    assert "timeout_seconds" not in parsed
+
+
+@pytest.mark.parametrize("status,error_class", _ERROR_CASES, ids=[str(c[0]) for c in _ERROR_CASES])
+@pytest.mark.respx(base_url=BASE_URL)
+def test_create_error_status(status: int, error_class: type, client: TinyFish, respx_mock: MockRouter):
+    respx_mock.post(_BROWSER_PATH).mock(return_value=httpx.Response(status, json={"error": {"message": "err"}}))
+    with pytest.raises(error_class):
+        client.browser.sessions.create()
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# browser.sessions.create() — async
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_create_returns_browser_session(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    respx_mock.post(_BROWSER_PATH).mock(return_value=httpx.Response(201, json=_session_response()))
+    async with async_client as c:
+        result = await c.browser.sessions.create()
+    assert isinstance(result, BrowserSession)
+    assert result.session_id == _SESSION_ID
+    assert result.cdp_url == _CDP_URL
+    assert result.base_url == _BASE_URL
+
+
+@pytest.mark.parametrize("name,kwargs,expected", _PARAM_CASES, ids=[c[0] for c in _PARAM_CASES])
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_create_sends_params(
+    name: str, kwargs: dict, expected: dict, async_client: AsyncTinyFish, respx_mock: MockRouter
+):
+    route = respx_mock.post(_BROWSER_PATH).mock(return_value=httpx.Response(201, json=_session_response()))
+    async with async_client as c:
+        await c.browser.sessions.create(**kwargs)
+    parsed = json.loads(route.calls[0].request.content)
+    for key, value in expected.items():
+        assert parsed[key] == value
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_create_omits_none_values(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    route = respx_mock.post(_BROWSER_PATH).mock(return_value=httpx.Response(201, json=_session_response()))
+    async with async_client as c:
+        await c.browser.sessions.create()
+    parsed = json.loads(route.calls[0].request.content)
+    assert "url" not in parsed
+    assert "timeout_seconds" not in parsed
+
+
+@pytest.mark.parametrize("status,error_class", _ERROR_CASES, ids=[str(c[0]) for c in _ERROR_CASES])
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_create_error_status(
+    status: int, error_class: type, async_client: AsyncTinyFish, respx_mock: MockRouter
+):
+    respx_mock.post(_BROWSER_PATH).mock(return_value=httpx.Response(status, json={"error": {"message": "err"}}))
+    async with async_client as c:
+        with pytest.raises(error_class):
+            await c.browser.sessions.create()

tinyfish-0.2.5/tests/test_fetch.py

@@ -0,0 +1,267 @@
+"""Tests for fetch resource — get_contents()."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+from respx import MockRouter
+
+from tests.conftest import BASE_URL
+from tinyfish import AsyncTinyFish, AuthenticationError, SDKError, TinyFish
+from tinyfish.fetch.types import FetchResponse
+
+# ─── Paths ────────────────────────────────────────────────────────────────────
+
+_FETCH_PATH = "/v1/fetch"
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _result(url: str = "https://example.com", **overrides: Any) -> dict[str, Any]:
+    base: dict[str, Any] = {
+        "url": url,
+        "final_url": f"{url}/",
+        "title": "Example",
+        "description": "An example page",
+        "language": "en",
+        "author": None,
+        "published_date": None,
+        "text": "# Example\nHello world",
+        "format": "markdown",
+        "links": [],
+        "image_links": [],
+        "latency_ms": 450,
+    }
+    return {**base, **overrides}
+
+
+def _response(
+    results: list[dict[str, Any]] | None = None,
+    errors: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    return {
+        "results": results or [],
+        "errors": errors or [],
+    }
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# fetch.get_contents() — sync
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_returns_response(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(200, json=_response(results=[_result()])))
+    result = client.fetch.get_contents(["https://example.com"])
+    assert isinstance(result, FetchResponse)
+    assert len(result.results) == 1
+    assert result.results[0].url == "https://example.com"
+    assert result.results[0].title == "Example"
+    assert result.results[0].format == "markdown"
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_sends_urls(client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(200, json=_response(results=[_result()])))
+    client.fetch.get_contents(["https://example.com"])
+    body = json.loads(route.calls[0].request.content)
+    assert body["urls"] == ["https://example.com"]
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_multiple_urls(client: TinyFish, respx_mock: MockRouter):
+    urls = ["https://a.com", "https://b.com", "https://c.com"]
+    route = respx_mock.post(_FETCH_PATH).mock(
+        return_value=httpx.Response(200, json=_response(results=[_result(u) for u in urls]))
+    )
+    result = client.fetch.get_contents(urls)
+    body = json.loads(route.calls[0].request.content)
+    assert body["urls"] == urls
+    assert len(result.results) == 3
+
+
+@pytest.mark.parametrize(
+    ("kwarg", "value", "body_key"),
+    [
+        ("format", "html", "format"),
+        ("links", True, "links"),
+        ("image_links", True, "image_links"),
+    ],
+)
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_optional_param(
+    kwarg: str, value: object, body_key: str, client: TinyFish, respx_mock: MockRouter
+):
+    route = respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(200, json=_response(results=[_result()])))
+    client.fetch.get_contents(["https://example.com"], **{kwarg: value})
+    body = json.loads(route.calls[0].request.content)
+    assert body[body_key] == value
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_omits_optional_params(client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(200, json=_response(results=[_result()])))
+    client.fetch.get_contents(["https://example.com"])
+    body = json.loads(route.calls[0].request.content)
+    assert "format" not in body
+    assert "links" not in body
+    assert "image_links" not in body
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_all_params(client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(200, json=_response(results=[_result()])))
+    client.fetch.get_contents(["https://example.com"], format="json", links=True, image_links=True)
+    body = json.loads(route.calls[0].request.content)
+    assert body["format"] == "json"
+    assert body["links"] is True
+    assert body["image_links"] is True
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_nullable_fields(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.post(_FETCH_PATH).mock(
+        return_value=httpx.Response(
+            200,
+            json=_response(
+                results=[
+                    _result(
+                        final_url=None,
+                        title=None,
+                        description=None,
+                        language=None,
+                        author=None,
+                        published_date=None,
+                        text=None,
+                        latency_ms=None,
+                    )
+                ]
+            ),
+        )
+    )
+    r = client.fetch.get_contents(["https://example.com"]).results[0]
+    assert r.final_url is None
+    assert r.title is None
+    assert r.text is None
+    assert r.latency_ms is None
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_with_errors(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.post(_FETCH_PATH).mock(
+        return_value=httpx.Response(
+            200,
+            json=_response(
+                results=[_result()],
+                errors=[{"url": "https://bad.com", "error": "Connection timeout"}],
+            ),
+        )
+    )
+    result = client.fetch.get_contents(["https://example.com", "https://bad.com"])
+    assert len(result.results) == 1
+    assert len(result.errors) == 1
+    assert result.errors[0].url == "https://bad.com"
+    assert result.errors[0].error == "Connection timeout"
+
+
+@pytest.mark.parametrize(
+    ("urls", "match"),
+    [
+        ([], "non-empty"),
+        ([f"https://x{i}.com" for i in range(11)], "at most 10"),
+    ],
+    ids=["empty", "too_many"],
+)
+def test_get_contents_url_count_validation(urls: list[str], match: str, client: TinyFish):
+    with pytest.raises(SDKError, match=match):
+        client.fetch.get_contents(urls)
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_exactly_10_urls(client: TinyFish, respx_mock: MockRouter):
+    urls = [f"https://example{i}.com" for i in range(10)]
+    respx_mock.post(_FETCH_PATH).mock(
+        return_value=httpx.Response(200, json=_response(results=[_result(u) for u in urls]))
+    )
+    assert len(client.fetch.get_contents(urls).results) == 10
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_get_contents_401(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(401, json={"error": {"message": "unauthorized"}}))
+    with pytest.raises(AuthenticationError):
+        client.fetch.get_contents(["https://example.com"])
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# fetch.get_contents() — async
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_get_contents_returns_response(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(200, json=_response(results=[_result()])))
+    async with async_client as c:
+        result = await c.fetch.get_contents(["https://example.com"])
+    assert isinstance(result, FetchResponse)
+    assert len(result.results) == 1
+    assert result.results[0].url == "https://example.com"
+
+
+@pytest.mark.parametrize(
+    ("kwarg", "value", "body_key"),
+    [
+        ("format", "html", "format"),
+        ("links", True, "links"),
+        ("image_links", True, "image_links"),
+    ],
+)
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_get_contents_optional_param(
+    kwarg: str, value: object, body_key: str, async_client: AsyncTinyFish, respx_mock: MockRouter
+):
+    route = respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(200, json=_response(results=[_result()])))
+    async with async_client as c:
+        await c.fetch.get_contents(["https://example.com"], **{kwarg: value})
+    body = json.loads(route.calls[0].request.content)
+    assert body[body_key] == value
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_get_contents_with_errors(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    respx_mock.post(_FETCH_PATH).mock(
+        return_value=httpx.Response(
+            200,
+            json=_response(errors=[{"url": "https://bad.com", "error": "timeout"}]),
+        )
+    )
+    async with async_client as c:
+        result = await c.fetch.get_contents(["https://bad.com"])
+    assert len(result.errors) == 1
+    assert result.errors[0].error == "timeout"
+
+
+@pytest.mark.parametrize(
+    ("urls", "match"),
+    [
+        ([], "non-empty"),
+        ([f"https://x{i}.com" for i in range(11)], "at most 10"),
+    ],
+    ids=["empty", "too_many"],
+)
+async def test_async_get_contents_url_count_validation(urls: list[str], match: str, async_client: AsyncTinyFish):
+    async with async_client as c:
+        with pytest.raises(SDKError, match=match):
+            await c.fetch.get_contents(urls)
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_get_contents_401(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    respx_mock.post(_FETCH_PATH).mock(return_value=httpx.Response(401, json={"error": {"message": "unauthorized"}}))
+    async with async_client as c:
+        with pytest.raises(AuthenticationError):
+            await c.fetch.get_contents(["https://example.com"])

tinyfish-0.2.5/tests/test_search.py

@@ -0,0 +1,229 @@
+"""Tests for search resource — query()."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import pytest
+from respx import MockRouter
+
+from tests.conftest import BASE_URL
+from tinyfish import AsyncTinyFish, AuthenticationError, SearchQueryResponse, TinyFish
+
+# ─── Constants ────────────────────────────────────────────────────────────────
+
+_SEARCH_PATH = "/v1/search"
+
+
+def _search_response(
+    *,
+    query: str = "web automation tools",
+    total_results: int = 2,
+    results: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    if results is None:
+        results = [
+            {
+                "position": 1,
+                "site_name": "example.com",
+                "snippet": "Example snippet one",
+                "title": "Example Title One",
+                "url": "https://example.com/one",
+            },
+            {
+                "position": 2,
+                "site_name": "other.com",
+                "snippet": "Example snippet two",
+                "title": "Example Title Two",
+                "url": "https://other.com/two",
+            },
+        ]
+    return {"query": query, "results": results, "total_results": total_results}
+
+
+# ─── Sync/async call helpers ─────────────────────────────────────────────────
+
+
+async def _do_query(client: TinyFish | AsyncTinyFish, *args: Any, **kwargs: Any) -> SearchQueryResponse:
+    if isinstance(client, AsyncTinyFish):
+        async with client as c:
+            return await c.search.query(*args, **kwargs)
+    return client.search.query(*args, **kwargs)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# search.query() — sync
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_returns_response(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    result = client.search.query("web automation tools")
+    assert isinstance(result, SearchQueryResponse)
+    assert result.query == "web automation tools"
+    assert result.total_results == 2
+    assert len(result.results) == 2
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_parses_result_fields(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    first = client.search.query("web automation tools").results[0]
+    assert first.position == 1
+    assert first.site_name == "example.com"
+    assert first.snippet == "Example snippet one"
+    assert first.title == "Example Title One"
+    assert first.url == "https://example.com/one"
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "expected_key", "expected_val"),
+    [
+        ({"location": "United States"}, "location", "United States"),
+        ({"language": "en"}, "language", "en"),
+    ],
+)
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_forwards_optional_param(
+    kwargs: dict[str, str],
+    expected_key: str,
+    expected_val: str,
+    client: TinyFish,
+    respx_mock: MockRouter,
+):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    client.search.query("test", **kwargs)
+    assert route.calls[0].request.url.params[expected_key] == expected_val
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_sends_all_params(client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    client.search.query("test", location="US", language="en")
+    params = route.calls[0].request.url.params
+    assert params["query"] == "test"
+    assert params["location"] == "US"
+    assert params["language"] == "en"
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_omits_optional_params(client: TinyFish, respx_mock: MockRouter):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    client.search.query("test")
+    params = route.calls[0].request.url.params
+    assert "location" not in params
+    assert "language" not in params
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_empty_results(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.get(_SEARCH_PATH).mock(
+        return_value=httpx.Response(200, json=_search_response(results=[], total_results=0))
+    )
+    result = client.search.query("no results")
+    assert result.results == []
+    assert result.total_results == 0
+
+
+@pytest.mark.parametrize("bad_query", ["", "   "])
+def test_query_rejects_empty_query(bad_query: str, client: TinyFish):
+    with pytest.raises(ValueError, match="non-empty"):
+        client.search.query(bad_query)
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_query_401(client: TinyFish, respx_mock: MockRouter):
+    respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(401, json={"error": {"message": "unauthorized"}}))
+    with pytest.raises(AuthenticationError):
+        client.search.query("test")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# search.query() — async (mirrors sync tests above)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_returns_response(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    result = await _do_query(async_client, "web automation tools")
+    assert isinstance(result, SearchQueryResponse)
+    assert result.query == "web automation tools"
+    assert result.total_results == 2
+    assert len(result.results) == 2
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_parses_result_fields(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    result = await _do_query(async_client, "web automation tools")
+    first = result.results[0]
+    assert first.position == 1
+    assert first.site_name == "example.com"
+    assert first.snippet == "Example snippet one"
+    assert first.title == "Example Title One"
+    assert first.url == "https://example.com/one"
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "expected_key", "expected_val"),
+    [
+        ({"location": "United States"}, "location", "United States"),
+        ({"language": "en"}, "language", "en"),
+    ],
+)
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_forwards_optional_param(
+    kwargs: dict[str, str],
+    expected_key: str,
+    expected_val: str,
+    async_client: AsyncTinyFish,
+    respx_mock: MockRouter,
+):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    await _do_query(async_client, "test", **kwargs)
+    assert route.calls[0].request.url.params[expected_key] == expected_val
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_sends_all_params(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    await _do_query(async_client, "test", location="UK", language="en")
+    params = route.calls[0].request.url.params
+    assert params["query"] == "test"
+    assert params["location"] == "UK"
+    assert params["language"] == "en"
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_omits_optional_params(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    route = respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(200, json=_search_response()))
+    await _do_query(async_client, "test")
+    params = route.calls[0].request.url.params
+    assert "location" not in params
+    assert "language" not in params
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_empty_results(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    respx_mock.get(_SEARCH_PATH).mock(
+        return_value=httpx.Response(200, json=_search_response(results=[], total_results=0))
+    )
+    result = await _do_query(async_client, "nothing")
+    assert result.results == []
+    assert result.total_results == 0
+
+
+@pytest.mark.parametrize("bad_query", ["", "   "])
+async def test_async_query_rejects_empty_query(bad_query: str, async_client: AsyncTinyFish):
+    with pytest.raises(ValueError, match="non-empty"):
+        await _do_query(async_client, bad_query)
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+async def test_async_query_401(async_client: AsyncTinyFish, respx_mock: MockRouter):
+    respx_mock.get(_SEARCH_PATH).mock(return_value=httpx.Response(401, json={"error": {"message": "unauthorized"}}))
+    with pytest.raises(AuthenticationError):
+        await _do_query(async_client, "test")