feat(scrape): add unified scrape API (#1182)

Stainless-Generated-From: 3e47848454ce16dfa04feab91529465422e6b86f

Author: stlc-bot

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 50
+configured_endpoints: 51

api.md

@@ -21,6 +21,7 @@ from context.dev.types import (
     WebExtractCompetitorsResponse,
     WebExtractFontsResponse,
     WebExtractStyleguideResponse,
+    WebScrapeResponse,
     WebScreenshotResponse,
     WebSearchResponse,
     WebWebCrawlMdResponse,
@@ -40,6 +41,7 @@ Methods:
 - <code title="get /web/competitors">client.web.<a href="./src/context/dev/resources/web.py">extract_competitors</a>(\*\*<a href="src/context/dev/types/web_extract_competitors_params.py">params</a>) -> <a href="./src/context/dev/types/web_extract_competitors_response.py">WebExtractCompetitorsResponse</a></code>
 - <code title="get /web/fonts">client.web.<a href="./src/context/dev/resources/web.py">extract_fonts</a>(\*\*<a href="src/context/dev/types/web_extract_fonts_params.py">params</a>) -> <a href="./src/context/dev/types/web_extract_fonts_response.py">WebExtractFontsResponse</a></code>
 - <code title="get /web/styleguide">client.web.<a href="./src/context/dev/resources/web.py">extract_styleguide</a>(\*\*<a href="src/context/dev/types/web_extract_styleguide_params.py">params</a>) -> <a href="./src/context/dev/types/web_extract_styleguide_response.py">WebExtractStyleguideResponse</a></code>
+- <code title="post /web/scrape">client.web.<a href="./src/context/dev/resources/web.py">scrape</a>(\*\*<a href="src/context/dev/types/web_scrape_params.py">params</a>) -> <a href="./src/context/dev/types/web_scrape_response.py">WebScrapeResponse</a></code>
 - <code title="get /web/screenshot">client.web.<a href="./src/context/dev/resources/web.py">screenshot</a>(\*\*<a href="src/context/dev/types/web_screenshot_params.py">params</a>) -> <a href="./src/context/dev/types/web_screenshot_response.py">WebScreenshotResponse</a></code>
 - <code title="post /web/search">client.web.<a href="./src/context/dev/resources/web.py">search</a>(\*\*<a href="src/context/dev/types/web_search_params.py">params</a>) -> <a href="./src/context/dev/types/web_search_response.py">WebSearchResponse</a></code>
 - <code title="post /web/crawl">client.web.<a href="./src/context/dev/resources/web.py">web_crawl_md</a>(\*\*<a href="src/context/dev/types/web_web_crawl_md_params.py">params</a>) -> <a href="./src/context/dev/types/web_web_crawl_md_response.py">WebWebCrawlMdResponse</a></code>

src/context/dev/resources/web.py

@@ -8,6 +8,7 @@
 import httpx
 
 from ..types import (
+    web_scrape_params,
     web_search_params,
     web_answers_params,
     web_extract_params,
@@ -34,6 +35,7 @@
     async_to_streamed_response_wrapper,
 )
 from .._base_client import make_request_options
+from ..types.web_scrape_response import WebScrapeResponse
 from ..types.web_search_response import WebSearchResponse
 from ..types.web_answers_response import WebAnswersResponse
 from ..types.web_extract_response import WebExtractResponse
@@ -496,6 +498,93 @@ def extract_styleguide(
             cast_to=WebExtractStyleguideResponse,
         )
 
+    def scrape(
+        self,
+        *,
+        formats: web_scrape_params.Formats,
+        url: str,
+        image_params: web_scrape_params.ImageParams | Omit = omit,
+        markdown_params: web_scrape_params.MarkdownParams | Omit = omit,
+        max_age_ms: int | Omit = omit,
+        parse_params: web_scrape_params.ParseParams | Omit = omit,
+        screenshot_params: web_scrape_params.ScreenshotParams | Omit = omit,
+        shared_params: web_scrape_params.SharedParams | Omit = omit,
+        tags: SequenceNotStr[str] | Omit = omit,
+        timeout_ms: int | Omit = omit,
+        zdr: Literal["enabled", "disabled"] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> WebScrapeResponse:
+        """Capture the requested formats from one page visit.
+
+        Shared settings apply once.
+        HTML-only requests use the existing fast acquisition path. One credit per
+        capture, or two with browser actions; PDF OCR adds one credit per recovered
+        page. Original response bytes and screenshots are limited to 20 MiB each,
+        screenshots to 40 megapixels, and the combined browser capture to 60 MiB.
+
+        Args:
+          formats: Outputs to return. Enable at least one; omitted formats are false.
+
+          url: The URL to scrape.
+
+          image_params: Image options. Requires formats.images: true.
+
+          markdown_params: Markdown options. Requires formats.markdown: true.
+
+          max_age_ms: Maximum age for the entire capture, including bytes. Defaults to 1 day; 0
+              fetches fresh. Captures with hosted image files refresh after 23 hours.
+
+          parse_params: Required when formats.parse is true.
+
+          screenshot_params: Screenshot options. Requires formats.screenshot: true.
+
+          shared_params: Shared browser and content settings. Content filters leave screenshots and
+              original bytes unchanged.
+
+          tags: Labels for tracking request usage. Not retained when zdr is enabled.
+
+          timeout_ms: Total deadline, including navigation, actions, waiting, and all outputs.
+
+          zdr: Zero data retention. Bypasses caches and uploads; excludes request/response
+              content and tags from logs. Must be enabled for your organization.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._post(
+            "/web/scrape",
+            body=maybe_transform(
+                {
+                    "formats": formats,
+                    "url": url,
+                    "image_params": image_params,
+                    "markdown_params": markdown_params,
+                    "max_age_ms": max_age_ms,
+                    "parse_params": parse_params,
+                    "screenshot_params": screenshot_params,
+                    "shared_params": shared_params,
+                    "tags": tags,
+                    "timeout_ms": timeout_ms,
+                    "zdr": zdr,
+                },
+                web_scrape_params.WebScrapeParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=WebScrapeResponse,
+        )
+
     def screenshot(
         self,
         *,
@@ -3761,6 +3850,93 @@ async def extract_styleguide(
             cast_to=WebExtractStyleguideResponse,
         )
 
+    async def scrape(
+        self,
+        *,
+        formats: web_scrape_params.Formats,
+        url: str,
+        image_params: web_scrape_params.ImageParams | Omit = omit,
+        markdown_params: web_scrape_params.MarkdownParams | Omit = omit,
+        max_age_ms: int | Omit = omit,
+        parse_params: web_scrape_params.ParseParams | Omit = omit,
+        screenshot_params: web_scrape_params.ScreenshotParams | Omit = omit,
+        shared_params: web_scrape_params.SharedParams | Omit = omit,
+        tags: SequenceNotStr[str] | Omit = omit,
+        timeout_ms: int | Omit = omit,
+        zdr: Literal["enabled", "disabled"] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> WebScrapeResponse:
+        """Capture the requested formats from one page visit.
+
+        Shared settings apply once.
+        HTML-only requests use the existing fast acquisition path. One credit per
+        capture, or two with browser actions; PDF OCR adds one credit per recovered
+        page. Original response bytes and screenshots are limited to 20 MiB each,
+        screenshots to 40 megapixels, and the combined browser capture to 60 MiB.
+
+        Args:
+          formats: Outputs to return. Enable at least one; omitted formats are false.
+
+          url: The URL to scrape.
+
+          image_params: Image options. Requires formats.images: true.
+
+          markdown_params: Markdown options. Requires formats.markdown: true.
+
+          max_age_ms: Maximum age for the entire capture, including bytes. Defaults to 1 day; 0
+              fetches fresh. Captures with hosted image files refresh after 23 hours.
+
+          parse_params: Required when formats.parse is true.
+
+          screenshot_params: Screenshot options. Requires formats.screenshot: true.
+
+          shared_params: Shared browser and content settings. Content filters leave screenshots and
+              original bytes unchanged.
+
+          tags: Labels for tracking request usage. Not retained when zdr is enabled.
+
+          timeout_ms: Total deadline, including navigation, actions, waiting, and all outputs.
+
+          zdr: Zero data retention. Bypasses caches and uploads; excludes request/response
+              content and tags from logs. Must be enabled for your organization.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._post(
+            "/web/scrape",
+            body=await async_maybe_transform(
+                {
+                    "formats": formats,
+                    "url": url,
+                    "image_params": image_params,
+                    "markdown_params": markdown_params,
+                    "max_age_ms": max_age_ms,
+                    "parse_params": parse_params,
+                    "screenshot_params": screenshot_params,
+                    "shared_params": shared_params,
+                    "tags": tags,
+                    "timeout_ms": timeout_ms,
+                    "zdr": zdr,
+                },
+                web_scrape_params.WebScrapeParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=WebScrapeResponse,
+        )
+
     async def screenshot(
         self,
         *,
@@ -6601,6 +6777,9 @@ def __init__(self, web: WebResource) -> None:
         self.extract_styleguide = to_raw_response_wrapper(
             web.extract_styleguide,
         )
+        self.scrape = to_raw_response_wrapper(
+            web.scrape,
+        )
         self.screenshot = to_raw_response_wrapper(
             web.screenshot,
         )
@@ -6649,6 +6828,9 @@ def __init__(self, web: AsyncWebResource) -> None:
         self.extract_styleguide = async_to_raw_response_wrapper(
             web.extract_styleguide,
         )
+        self.scrape = async_to_raw_response_wrapper(
+            web.scrape,
+        )
         self.screenshot = async_to_raw_response_wrapper(
             web.screenshot,
         )
@@ -6697,6 +6879,9 @@ def __init__(self, web: WebResource) -> None:
         self.extract_styleguide = to_streamed_response_wrapper(
             web.extract_styleguide,
         )
+        self.scrape = to_streamed_response_wrapper(
+            web.scrape,
+        )
         self.screenshot = to_streamed_response_wrapper(
             web.screenshot,
         )
@@ -6745,6 +6930,9 @@ def __init__(self, web: AsyncWebResource) -> None:
         self.extract_styleguide = async_to_streamed_response_wrapper(
             web.extract_styleguide,
         )
+        self.scrape = async_to_streamed_response_wrapper(
+            web.scrape,
+        )
         self.screenshot = async_to_streamed_response_wrapper(
             web.screenshot,
         )

src/context/dev/types/__init__.py

@@ -11,6 +11,7 @@
 from .webhook_delivery import WebhookDelivery as WebhookDelivery
 from .batch_list_params import BatchListParams as BatchListParams
 from .log_list_response import LogListResponse as LogListResponse
+from .web_scrape_params import WebScrapeParams as WebScrapeParams
 from .web_search_params import WebSearchParams as WebSearchParams
 from .news_search_params import NewsSearchParams as NewsSearchParams
 from .retry_config_param import RetryConfigParam as RetryConfigParam
@@ -21,6 +22,7 @@
 from .brand_search_params import BrandSearchParams as BrandSearchParams
 from .monitor_list_params import MonitorListParams as MonitorListParams
 from .parse_handle_params import ParseHandleParams as ParseHandleParams
+from .web_scrape_response import WebScrapeResponse as WebScrapeResponse
 from .web_search_response import WebSearchResponse as WebSearchResponse
 from .monitor_run_response import MonitorRunResponse as MonitorRunResponse
 from .news_search_response import NewsSearchResponse as NewsSearchResponse