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

Stainless-Generated-From: 3bf3428

Author: stlc-bot

src/ServiceContracts/WebContract.php

@@ -220,7 +220,7 @@ public function extractStyleguide(
      * @param string $url the URL to scrape
      * @param ImageParams|ImageParamsShape $imageParams Image options. Requires formats.images: true.
      * @param MarkdownParams|MarkdownParamsShape $markdownParams Markdown options. Requires formats.markdown: true.
-     * @param int $maxAgeMs Maximum age for the entire capture, including bytes. Defaults to 1 day; 0 fetches fresh. Captures with hosted image files refresh after 23 hours.
+     * @param int $maxAgeMs 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.
      * @param ParseParams|ParseParamsShape $parseParams Required when formats.parse is true.
      * @param ScreenshotParams|ScreenshotParamsShape $screenshotParams Screenshot options. Requires formats.screenshot: true.
      * @param SharedParams|SharedParamsShape $sharedParams Shared browser and content settings. Content filters leave screenshots and original bytes unchanged.

src/Services/WebRawService.php

@@ -306,7 +306,7 @@ public function extractStyleguide(
     /**
      * @api
      *
-     * 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.
+     * Reuse cached outputs independently and capture missing formats in one page visit. 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.
      *
      * @param array{
      *   formats: Formats|FormatsShape,

src/Services/WebService.php

@@ -332,13 +332,13 @@ public function extractStyleguide(
     /**
      * @api
      *
-     * 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.
+     * Reuse cached outputs independently and capture missing formats in one page visit. 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.
      *
      * @param Formats|FormatsShape $formats Outputs to return. Enable at least one; omitted formats are false.
      * @param string $url the URL to scrape
      * @param ImageParams|ImageParamsShape $imageParams Image options. Requires formats.images: true.
      * @param MarkdownParams|MarkdownParamsShape $markdownParams Markdown options. Requires formats.markdown: true.
-     * @param int $maxAgeMs Maximum age for the entire capture, including bytes. Defaults to 1 day; 0 fetches fresh. Captures with hosted image files refresh after 23 hours.
+     * @param int $maxAgeMs 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.
      * @param ParseParams|ParseParamsShape $parseParams Required when formats.parse is true.
      * @param ScreenshotParams|ScreenshotParamsShape $screenshotParams Screenshot options. Requires formats.screenshot: true.
      * @param SharedParams|SharedParamsShape $sharedParams Shared browser and content settings. Content filters leave screenshots and original bytes unchanged.

src/Web/WebScrapeParams.php

@@ -18,7 +18,7 @@
 use ContextDev\Web\WebScrapeParams\Zdr;
 
 /**
- * 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.
+ * Reuse cached outputs independently and capture missing formats in one page visit. 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.
  *
  * @see ContextDev\Services\WebService::scrape()
  *
@@ -74,7 +74,7 @@ final class WebScrapeParams implements BaseModel
     public ?MarkdownParams $markdownParams;
 
     /**
-     * Maximum age for the entire capture, including bytes. Defaults to 1 day; 0 fetches fresh. Captures with hosted image files refresh after 23 hours.
+     * 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.
      */
     #[Optional]
     public ?int $maxAgeMs;
@@ -235,7 +235,7 @@ public function withMarkdownParams(
     }
 
     /**
-     * Maximum age for the entire capture, including bytes. Defaults to 1 day; 0 fetches fresh. Captures with hosted image files refresh after 23 hours.
+     * 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.
      */
     public function withMaxAgeMs(int $maxAgeMs): self
     {