tinyfish 0.2.6__tar.gz → 0.4.0__tar.gz

tinyfish-0.4.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.4.0](https://github.com/tinyfish-io/ux-labs/compare/sdk-py/v0.3.0...sdk-py/v0.4.0) (2026-07-23)
+
+
+### Features
+
+* **search:** add pub_year_min/pub_year_max publication-year filter ([#3691](https://github.com/tinyfish-io/ux-labs/issues/3691)) ([8728754](https://github.com/tinyfish-io/ux-labs/commit/8728754206fe4b7cf3a4ee8226c74bb364532869))
+* **search:** expose include_domains/exclude_domains in SDKs, CLI, MCP prose (ML-2084) ([#3692](https://github.com/tinyfish-io/ux-labs/issues/3692)) ([6c2079f](https://github.com/tinyfish-io/ux-labs/commit/6c2079f52872f9c9472cde8ec95d70280f25defa))
+
+## [0.3.0](https://github.com/tinyfish-io/ux-labs/compare/sdk-py/v0.2.6...sdk-py/v0.3.0) (2026-07-22)
+
+
+### Features
+
+* **ci:** automate SDK/CLI releases via release-please ([#3632](https://github.com/tinyfish-io/ux-labs/issues/3632)) ([1b311ea](https://github.com/tinyfish-io/ux-labs/commit/1b311ea6d6277fad21b57baf0b7cfdc6619a3b93))
+* **sdk:** add domain_type to search.query() in TypeScript and Python SDKs ([#3432](https://github.com/tinyfish-io/ux-labs/issues/3432)) ([1c2954c](https://github.com/tinyfish-io/ux-labs/commit/1c2954cb192324cdca1ce206515de72df2cd231d))

{tinyfish-0.2.6 → tinyfish-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyfish
-Version: 0.2.6
+Version: 0.4.0
 Summary: Official Python SDK for the TinyFish API
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0
@@ -53,8 +53,10 @@ Every method below is available on both `TinyFish` (sync) and `AsyncTinyFish` (a
 | [`agent.run()`](#agentrun--block-until-done) | Run an automation, wait for the result | `AgentRunResponse` | Yes |
 | [`agent.queue()`](#agentqueue--fire-and-forget) | Start an automation, return immediately | `AgentRunAsyncResponse` | No |
 | [`agent.stream()`](#agentstream--real-time-events) | Stream live SSE events as the agent works | `AgentStream` | No |
+| [`fetch.get_contents()`](#fetchget_contents--clean-content) | Fetch extracted page content without running a browser agent | `FetchResponse` | Yes |
 | [`runs.get()`](#runsget--retrieve-a-single-run) | Retrieve a single run by ID | `Run` | — |
 | [`runs.list()`](#runslist--list-and-filter-runs) | List runs with filtering, sorting, pagination | `RunListResponse` | — |
+| [`search.query()`](#searchquery--search-the-web) | Search the web for ranked results | `SearchQueryResponse` | Yes |
 
 ---
 
@@ -183,6 +185,41 @@ See the [Streaming Guide](docs/streaming-guide.md) for the full event lifecycle,
 
 ---
 
+### `fetch.get_contents()` — clean content
+
+Fetch extracted content from one or more URLs without a browser-agent run.
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish()
+
+response = client.fetch.get_contents(
+    [
+        "https://example.com",
+        "https://example.org",
+    ],
+    format="markdown",
+    links=True,
+    image_links=False,
+    per_url_timeout_ms=45_000,
+)
+
+print(response.results)
+print(response.errors)
+```
+
+`fetch.get_contents()` accepts 1 to 10 URLs. Set `per_url_timeout_ms` to apply an independent timeout budget to each URL in the batch; slow URLs return in `errors` with `timeout` while siblings can still complete.
+
+**Returns `FetchResponse`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `results` | `list[FetchResult]` | Successfully fetched URLs |
+| `errors` | `list[FetchError]` | URLs that failed to fetch or extract |
+
+---
+
 ### `runs.get()` — retrieve a single run
 
 Fetch the full details of a run by its ID.
@@ -258,6 +295,64 @@ See the [Pagination Guide](docs/pagination-guide.md) for full pagination loop ex
 
 ---
 
+### `search.query()` — search the web
+
+Returns ranked web search results with titles, snippets, and URLs.
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish()
+
+response = client.search.query("FIFA")
+
+print(response.query)
+print(response.total_results)
+print(response.results[0].title if response.results else "No results")
+```
+
+Optional parameters:
+
+- `location` — country code for geo-targeted results (e.g. `"US"`, `"GB"`)
+- `language` — language code (e.g. `"en"`, `"fr"`)
+- `page` — page number, 0-indexed, max `10`
+- `recency_minutes` — freshness window in minutes (`1` to `5256000`)
+- `after_date` / `before_date` — calendar date range in `YYYY-MM-DD`
+- `domain_type` — result category: `"web"` (default), `"news"`, or `"research_paper"`
+- `pub_year_min` / `pub_year_max` — publication-year range, inclusive (`0` to `9999`). Only supported for `domain_type="research_paper"`
+
+```python
+# geo-targeted
+response = client.search.query("FIFA", location="US", language="en")
+
+# freshness window
+response = client.search.query("FIFA", recency_minutes=60)
+
+# calendar date range
+response = client.search.query("FIFA", after_date="2026-06-01", before_date="2026-06-18")
+
+# domain type
+response = client.search.query("FIFA", domain_type="news")
+response = client.search.query("machine learning", domain_type="research_paper")
+
+# publication-year range (research_paper only)
+response = client.search.query(
+    "transformer architecture", domain_type="research_paper", pub_year_min=2019, pub_year_max=2022
+)
+```
+
+Filter validation rules:
+
+- `recency_minutes` must be an integer from `1` to `5256000`
+- `after_date` and `before_date` must use `YYYY-MM-DD`
+- `recency_minutes` cannot be combined with `after_date` or `before_date`
+- if both dates are present, `after_date` must be less than or equal to `before_date`
+- `domain_type` must be one of `"web"`, `"news"`, or `"research_paper"`
+- `pub_year_min` and `pub_year_max` must be integers from `0` to `9999`
+- if both are present, `pub_year_min` must be less than or equal to `pub_year_max`
+
+---
+
 ## Sync vs Async
 
 Use `AsyncTinyFish` when you're in an async context (FastAPI, aiohttp, etc.):
@@ -280,7 +375,7 @@ client = AsyncTinyFish()
 response = await client.agent.run(goal="...", url="...")
 ```
 
-All five methods (`agent.run()`, `agent.queue()`, `agent.stream()`, `runs.get()`, `runs.list()`) work the same way — same parameters, just `await`-ed.
+All seven methods (`agent.run()`, `agent.queue()`, `agent.stream()`, `fetch.get_contents()`, `runs.get()`, `runs.list()`, `search.query()`) work the same way — same parameters, just `await`-ed.
 
 ## Configuration
 

{tinyfish-0.2.6 → tinyfish-0.4.0}/README.md

@@ -43,8 +43,10 @@ Every method below is available on both `TinyFish` (sync) and `AsyncTinyFish` (a
 | [`agent.run()`](#agentrun--block-until-done) | Run an automation, wait for the result | `AgentRunResponse` | Yes |
 | [`agent.queue()`](#agentqueue--fire-and-forget) | Start an automation, return immediately | `AgentRunAsyncResponse` | No |
 | [`agent.stream()`](#agentstream--real-time-events) | Stream live SSE events as the agent works | `AgentStream` | No |
+| [`fetch.get_contents()`](#fetchget_contents--clean-content) | Fetch extracted page content without running a browser agent | `FetchResponse` | Yes |
 | [`runs.get()`](#runsget--retrieve-a-single-run) | Retrieve a single run by ID | `Run` | — |
 | [`runs.list()`](#runslist--list-and-filter-runs) | List runs with filtering, sorting, pagination | `RunListResponse` | — |
+| [`search.query()`](#searchquery--search-the-web) | Search the web for ranked results | `SearchQueryResponse` | Yes |
 
 ---
 
@@ -173,6 +175,41 @@ See the [Streaming Guide](docs/streaming-guide.md) for the full event lifecycle,
 
 ---
 
+### `fetch.get_contents()` — clean content
+
+Fetch extracted content from one or more URLs without a browser-agent run.
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish()
+
+response = client.fetch.get_contents(
+    [
+        "https://example.com",
+        "https://example.org",
+    ],
+    format="markdown",
+    links=True,
+    image_links=False,
+    per_url_timeout_ms=45_000,
+)
+
+print(response.results)
+print(response.errors)
+```
+
+`fetch.get_contents()` accepts 1 to 10 URLs. Set `per_url_timeout_ms` to apply an independent timeout budget to each URL in the batch; slow URLs return in `errors` with `timeout` while siblings can still complete.
+
+**Returns `FetchResponse`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `results` | `list[FetchResult]` | Successfully fetched URLs |
+| `errors` | `list[FetchError]` | URLs that failed to fetch or extract |
+
+---
+
 ### `runs.get()` — retrieve a single run
 
 Fetch the full details of a run by its ID.
@@ -248,6 +285,64 @@ See the [Pagination Guide](docs/pagination-guide.md) for full pagination loop ex
 
 ---
 
+### `search.query()` — search the web
+
+Returns ranked web search results with titles, snippets, and URLs.
+
+```python
+from tinyfish import TinyFish
+
+client = TinyFish()
+
+response = client.search.query("FIFA")
+
+print(response.query)
+print(response.total_results)
+print(response.results[0].title if response.results else "No results")
+```
+
+Optional parameters:
+
+- `location` — country code for geo-targeted results (e.g. `"US"`, `"GB"`)
+- `language` — language code (e.g. `"en"`, `"fr"`)
+- `page` — page number, 0-indexed, max `10`
+- `recency_minutes` — freshness window in minutes (`1` to `5256000`)
+- `after_date` / `before_date` — calendar date range in `YYYY-MM-DD`
+- `domain_type` — result category: `"web"` (default), `"news"`, or `"research_paper"`
+- `pub_year_min` / `pub_year_max` — publication-year range, inclusive (`0` to `9999`). Only supported for `domain_type="research_paper"`
+
+```python
+# geo-targeted
+response = client.search.query("FIFA", location="US", language="en")
+
+# freshness window
+response = client.search.query("FIFA", recency_minutes=60)
+
+# calendar date range
+response = client.search.query("FIFA", after_date="2026-06-01", before_date="2026-06-18")
+
+# domain type
+response = client.search.query("FIFA", domain_type="news")
+response = client.search.query("machine learning", domain_type="research_paper")
+
+# publication-year range (research_paper only)
+response = client.search.query(
+    "transformer architecture", domain_type="research_paper", pub_year_min=2019, pub_year_max=2022
+)
+```
+
+Filter validation rules:
+
+- `recency_minutes` must be an integer from `1` to `5256000`
+- `after_date` and `before_date` must use `YYYY-MM-DD`
+- `recency_minutes` cannot be combined with `after_date` or `before_date`
+- if both dates are present, `after_date` must be less than or equal to `before_date`
+- `domain_type` must be one of `"web"`, `"news"`, or `"research_paper"`
+- `pub_year_min` and `pub_year_max` must be integers from `0` to `9999`
+- if both are present, `pub_year_min` must be less than or equal to `pub_year_max`
+
+---
+
 ## Sync vs Async
 
 Use `AsyncTinyFish` when you're in an async context (FastAPI, aiohttp, etc.):
@@ -270,7 +365,7 @@ client = AsyncTinyFish()
 response = await client.agent.run(goal="...", url="...")
 ```
 
-All five methods (`agent.run()`, `agent.queue()`, `agent.stream()`, `runs.get()`, `runs.list()`) work the same way — same parameters, just `await`-ed.
+All seven methods (`agent.run()`, `agent.queue()`, `agent.stream()`, `fetch.get_contents()`, `runs.get()`, `runs.list()`, `search.query()`) work the same way — same parameters, just `await`-ed.
 
 ## Configuration
 

{tinyfish-0.2.6 → tinyfish-0.4.0}/RELEASE.md

@@ -19,25 +19,22 @@ This is a one-time change. Once merged and applied, the workflow will have acces
 
 ## Release process
 
-### Step 1: Bump the version
+### Step 1: Merge SDK changes to main
 
-Edit `sdk/sdk-python/pyproject.toml` and update the `version` field:
+Use conventional commits (`feat:`, `fix:`, `feat!:`) for changes under `sdk/sdk-python/`.
+After merge, `release-please.yml` opens or updates a Python SDK release PR with:
 
-```toml
-[project]
-version = "0.2.0"  # bump this
-```
+- `sdk/sdk-python/pyproject.toml` version bump
+- `sdk/sdk-python/CHANGELOG.md` release notes
+- `.github/release-please/manifest.json` version tracking
+
+Review and merge that release PR when you're ready to publish.
 
-Commit and merge to main.
+### Step 2: Release Please creates the GitHub Release
 
-### Step 2: Create a GitHub Release
+Merging the release PR creates a GitHub Release tagged with the Python SDK component:
 
-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 `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**
+- Version `0.2.7` → tag `sdk-py/v0.2.7`
 
 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.
 
@@ -52,15 +49,18 @@ Monitor progress at: `github.com/tinyfish-io/ux-labs/actions`
 
 ### Step 4: Verify
 
-After the workflow completes, verify the release:
+After the workflow completes, verify the release (replace `0.2.7` with the released version):
 
 ```bash
-pip install tinyfish==0.2.0
+pip install tinyfish==0.2.7
 python -c "from tinyfish import TinyFish; print('ok')"
 ```
 
 ## Troubleshooting
 
+**Manual release escape hatch**
+Use `workflow_dispatch` on `CD_sdk_python.yml` at a `sdk-py/v*` tag if Release Please created the tag but the publish workflow did not run.
+
 **Tag does not match pyproject.toml version**
 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.
 

{tinyfish-0.2.6 → tinyfish-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tinyfish"
-version = "0.2.6"
+version = "0.4.0"
 description = "Official Python SDK for the TinyFish API"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -11,6 +11,7 @@ dependencies = [
 ]
 
 [tool.uv]
+exclude-newer = "7 days"
 constraint-dependencies = [
   "pygments>=2.20.0",
 ]

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

@@ -0,0 +1,273 @@
+"""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
+MIN_PER_URL_TIMEOUT_MS = 1
+MAX_PER_URL_TIMEOUT_MS = 110_000
+FETCH_PURPOSE_MAX_LENGTH = 2000
+
+
+class FetchResource(BaseSyncAPIResource):
+    """Fetch and extract clean content from URLs."""
+
+    def get_contents(
+        self,
+        urls: list[str],
+        *,
+        purpose: str | None = None,
+        format: FetchFormat | None = None,
+        include_html_head: bool | None = None,
+        links: bool | None = None,
+        image_links: bool | None = None,
+        ttl: int | None = None,
+        per_url_timeout_ms: int | None = None,
+        if_none_match: str | None = None,
+        if_modified_since: str | None = None,
+        include_etag_and_last_modified: bool | None = None,
+    ) -> FetchResponse:
+        """Fetch and extract content from one or more URLs.
+
+        Args:
+            urls: List of URLs to fetch (1-10 items).
+            purpose: Optional short statement of why these URLs are being
+                fetched — the goal or task the content will be used for.
+                Freeform; gives the fetch additional intent signal for
+                better-quality results. When supplied it must be non-empty;
+                max 2000 characters.
+            format: Output format — "markdown", "html", or "json".
+            include_html_head: Whether to wrap html output in a complete document with a head tag.
+            links: Whether to extract links from the page.
+            image_links: Whether to extract image links from the page.
+            ttl: Caller freshness tolerance in seconds for the cached entry.
+                Omit (default) for unlimited tolerance — any cached entry is
+                acceptable. Pass 0 to prefer a live fetch; the cached entry
+                is still served if the origin's Cache-Control: max-age
+                covers its age, or the host is on the small allowlist of
+                operator-pinned never-expire domains. Pass N > 0 to accept
+                an entry whose age is below N seconds; the upstream max-age
+                and the never-expire list may extend (never shorten) this.
+            per_url_timeout_ms: Wall-clock timeout budget in milliseconds
+                applied independently to each URL.
+            if_none_match: ETag validator from a prior fetch, forwarded
+                verbatim as the If-None-Match header on the origin request.
+                Single-URL only — combining it with a batch of URLs is
+                rejected. Validators are not persisted; the caller replays
+                them on the next request.
+            if_modified_since: Last-Modified validator from a prior fetch,
+                forwarded verbatim as the If-Modified-Since header on the
+                origin request. Single-URL only — combining it with a batch
+                of URLs is rejected. Validators are not persisted; the caller
+                replays them on the next request.
+            include_etag_and_last_modified: Opt-in to receiving the ``etag`` /
+                ``last_modified`` validators (and ``not_modified`` detection)
+                on each result. Defaults to false — those fields come back
+                only when this is set. Works with a single URL or a batch.
+
+        Returns:
+            FetchResponse with results and errors lists.
+
+        Raises:
+            SDKError: urls is empty or has more than 10 items, purpose is
+                empty or over 2000 characters, ttl is negative or not an
+                integer, or per_url_timeout_ms is outside 1..110000.
+            AuthenticationError: Invalid API key.
+        """
+        _validate_urls(urls)
+        _validate_purpose(purpose)
+        _validate_ttl(ttl)
+        _validate_per_url_timeout_ms(per_url_timeout_ms)
+        _validate_conditional_headers(urls, if_none_match, if_modified_since)
+        body = _build_body(
+            urls,
+            purpose=purpose,
+            format=format,
+            include_html_head=include_html_head,
+            links=links,
+            image_links=image_links,
+            ttl=ttl,
+            per_url_timeout_ms=per_url_timeout_ms,
+            if_none_match=if_none_match,
+            if_modified_since=if_modified_since,
+            include_etag_and_last_modified=include_etag_and_last_modified,
+        )
+        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],
+        *,
+        purpose: str | None = None,
+        format: FetchFormat | None = None,
+        include_html_head: bool | None = None,
+        links: bool | None = None,
+        image_links: bool | None = None,
+        ttl: int | None = None,
+        per_url_timeout_ms: int | None = None,
+        if_none_match: str | None = None,
+        if_modified_since: str | None = None,
+        include_etag_and_last_modified: 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).
+            purpose: Optional short statement of why these URLs are being
+                fetched — the goal or task the content will be used for.
+                Freeform; gives the fetch additional intent signal for
+                better-quality results. When supplied it must be non-empty;
+                max 2000 characters.
+            format: Output format — "markdown", "html", or "json".
+            include_html_head: Whether to wrap html output in a complete document with a head tag.
+            links: Whether to extract links from the page.
+            image_links: Whether to extract image links from the page.
+            ttl: Caller freshness tolerance in seconds for the cached entry.
+                See FetchResource.get_contents for full semantics.
+            per_url_timeout_ms: Wall-clock timeout budget in milliseconds
+                applied independently to each URL.
+            if_none_match: ETag validator from a prior fetch, forwarded
+                verbatim as the If-None-Match header on the origin request.
+                Single-URL only. See FetchResource.get_contents for full
+                semantics.
+            if_modified_since: Last-Modified validator from a prior fetch,
+                forwarded verbatim as the If-Modified-Since header on the
+                origin request. Single-URL only. See FetchResource.get_contents
+                for full semantics.
+            include_etag_and_last_modified: Opt-in to receiving the ``etag`` /
+                ``last_modified`` validators (and ``not_modified`` detection)
+                on each result. Defaults to false. Works with a single URL or
+                a batch.
+
+        Returns:
+            FetchResponse with results and errors lists.
+
+        Raises:
+            SDKError: urls is empty or has more than 10 items, purpose is
+                empty or over 2000 characters, ttl is negative or not an
+                integer, or per_url_timeout_ms is outside 1..110000.
+            AuthenticationError: Invalid API key.
+        """
+        _validate_urls(urls)
+        _validate_purpose(purpose)
+        _validate_ttl(ttl)
+        _validate_per_url_timeout_ms(per_url_timeout_ms)
+        _validate_conditional_headers(urls, if_none_match, if_modified_since)
+        body = _build_body(
+            urls,
+            purpose=purpose,
+            format=format,
+            include_html_head=include_html_head,
+            links=links,
+            image_links=image_links,
+            ttl=ttl,
+            per_url_timeout_ms=per_url_timeout_ms,
+            if_none_match=if_none_match,
+            if_modified_since=if_modified_since,
+            include_etag_and_last_modified=include_etag_and_last_modified,
+        )
+        return await self._post("/v1/fetch", json=body, cast_to=FetchResponse)
+
+
+def _validate_purpose(purpose: str | None) -> None:
+    if purpose is None:
+        return
+    if not purpose.strip():
+        raise SDKError("purpose must be a non-empty string")
+    if len(purpose) > FETCH_PURPOSE_MAX_LENGTH:
+        raise SDKError(f"purpose must be at most {FETCH_PURPOSE_MAX_LENGTH} characters")
+
+
+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 _validate_ttl(ttl: int | None) -> None:
+    """Reject negative or non-integer ttl values client-side.
+
+    Matches the TypeScript SDK's `z.int().min(0)`. `bool` is excluded
+    explicitly (Python treats `bool` as a subclass of `int`, so the
+    `isinstance(ttl, int)` check alone would accept `True`/`False`).
+    """
+    if ttl is None:
+        return
+    if isinstance(ttl, bool) or not isinstance(ttl, int):
+        raise SDKError("ttl must be a non-negative integer")
+    if ttl < 0:
+        raise SDKError("ttl must be a non-negative integer")
+
+
+def _validate_per_url_timeout_ms(per_url_timeout_ms: int | None) -> None:
+    if per_url_timeout_ms is None:
+        return
+    if isinstance(per_url_timeout_ms, bool) or not isinstance(per_url_timeout_ms, int):
+        raise SDKError("per_url_timeout_ms must be an integer between 1 and 110000")
+    if not MIN_PER_URL_TIMEOUT_MS <= per_url_timeout_ms <= MAX_PER_URL_TIMEOUT_MS:
+        raise SDKError("per_url_timeout_ms must be an integer between 1 and 110000")
+
+
+def _validate_conditional_headers(urls: list[str], if_none_match: str | None, if_modified_since: str | None) -> None:
+    """Reject `if_none_match` / `if_modified_since` when combined with a batch of URLs.
+
+    Conditional GETs only make sense against a single resource. Mirrors the
+    API's own validation (`api/models.py` `_check_flags`) so the error
+    surfaces client-side before the request is sent.
+    """
+    if len(urls) <= 1:
+        return
+    if if_none_match is not None:
+        raise SDKError("if_none_match can only be used with a single URL, not a batch")
+    if if_modified_since is not None:
+        raise SDKError("if_modified_since can only be used with a single URL, not a batch")
+
+
+def _build_body(
+    urls: list[str],
+    *,
+    purpose: str | None,
+    format: FetchFormat | None,
+    include_html_head: bool | None,
+    links: bool | None,
+    image_links: bool | None,
+    ttl: int | None,
+    per_url_timeout_ms: int | None,
+    if_none_match: str | None,
+    if_modified_since: str | None,
+    include_etag_and_last_modified: bool | None,
+) -> dict[str, object]:
+    body: dict[str, object] = {"urls": urls}
+    if purpose is not None:
+        body["purpose"] = purpose
+    if format is not None:
+        body["format"] = format
+    if include_html_head is not None:
+        body["include_html_head"] = include_html_head
+    if links is not None:
+        body["links"] = links
+    if image_links is not None:
+        body["image_links"] = image_links
+    if ttl is not None:
+        body["ttl"] = ttl
+    if per_url_timeout_ms is not None:
+        body["per_url_timeout_ms"] = per_url_timeout_ms
+    if if_none_match is not None:
+        body["if_none_match"] = if_none_match
+    if if_modified_since is not None:
+        body["if_modified_since"] = if_modified_since
+    if include_etag_and_last_modified is not None:
+        body["include_etag_and_last_modified"] = include_etag_and_last_modified
+    return body

{tinyfish-0.2.6 → tinyfish-0.4.0}/src/tinyfish/fetch/types.py

@@ -24,6 +24,20 @@ class FetchResult(BaseModel):
     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")
+    not_modified: bool | None = Field(
+        None,
+        description=(
+            "True only for a successful 304 returned against the caller-supplied "
+            "if_none_match / if_modified_since validators. Omitted (None) when "
+            "conditional headers were not used or not requested via "
+            "include_etag_and_last_modified."
+        ),
+    )
+    etag: str | None = Field(None, description="Origin ETag validator; omitted when not applicable")
+    last_modified: str | None = Field(
+        None,
+        description="Origin Last-Modified validator; omitted when not applicable",
+    )
 
 
 class FetchError(BaseModel):