fix(scrape): reuse legacy caches across all output formats (#1197)

Stainless-Generated-From: 89f722a

Author: stlc-bot

src/context/dev/resources/web.py

@@ -519,13 +519,16 @@ def scrape(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> WebScrapeResponse:
-        """Capture the requested formats from one page visit.
+        """Reuse cached outputs independently and capture missing formats in 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.
+        Each cache key includes only the settings that affect that output. HTML
+        is shared with Markdown and parsed fields. Cached outputs can come from
+        different visits within maxAgeMs; use 0 for a fresh capture. HTML-only requests
+        use the existing fast acquisition path. One credit per request, including cache
+        hits, or two with browser actions; PDF OCR adds one credit per recovered page on
+        fresh extraction. 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.
@@ -536,8 +539,10 @@ def scrape(
 
           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.
+          max_age_ms: Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and
+              updates the requested outputs. Compatible outputs are shared with the individual
+              scrape endpoints. Image results with hosted files refresh after 23 hours; other
+              outputs retain their own freshness.
 
           parse_params: Required when formats.parse is true.
 
@@ -3871,13 +3876,16 @@ async def scrape(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> WebScrapeResponse:
-        """Capture the requested formats from one page visit.
+        """Reuse cached outputs independently and capture missing formats in 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.
+        Each cache key includes only the settings that affect that output. HTML
+        is shared with Markdown and parsed fields. Cached outputs can come from
+        different visits within maxAgeMs; use 0 for a fresh capture. HTML-only requests
+        use the existing fast acquisition path. One credit per request, including cache
+        hits, or two with browser actions; PDF OCR adds one credit per recovered page on
+        fresh extraction. 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.
@@ -3888,8 +3896,10 @@ async def scrape(
 
           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.
+          max_age_ms: Maximum age of each cached output. Defaults to 1 day; 0 fetches fresh and
+              updates the requested outputs. Compatible outputs are shared with the individual
+              scrape endpoints. Image results with hosted files refresh after 23 hours; other
+              outputs retain their own freshness.
 
           parse_params: Required when formats.parse is true.
 

src/context/dev/types/web_scrape_params.py

@@ -46,10 +46,11 @@ class WebScrapeParams(TypedDict, total=False):
     """Markdown options. Requires formats.markdown: true."""
 
     max_age_ms: Annotated[int, PropertyInfo(alias="maxAgeMs")]
-    """Maximum age for the entire capture, including bytes.
+    """Maximum age of each cached output.
 
-    Defaults to 1 day; 0 fetches fresh. Captures with hosted image files refresh
-    after 23 hours.
+    Defaults to 1 day; 0 fetches fresh and updates the requested outputs. Compatible
+    outputs are shared with the individual scrape endpoints. Image results with
+    hosted files refresh after 23 hours; other outputs retain their own freshness.
     """
 
     parse_params: Annotated[ParseParams, PropertyInfo(alias="parseParams")]