feat(scrape): support custom screenshot headers (#1169)

Stainless-Generated-From: 6bcee363efb01db65999bc98644082358e2f590b

Author: stlc-bot

src/ServiceContracts/WebContract.php

@@ -210,6 +210,7 @@ public function extractStyleguide(
      * @param string $domain Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.
      * @param FullScreenshot|value-of<FullScreenshot> $fullScreenshot Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).
      * @param bool $handleCookiePopup Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.
+     * @param array<string,string> $headers Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers.
      * @param int|null $maxAgeMs Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
      * @param Page|value-of<Page> $page Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'.
      * @param int|null $scrollOffset Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.
@@ -230,6 +231,7 @@ public function screenshot(
         ?string $domain = null,
         FullScreenshot|string|null $fullScreenshot = null,
         bool $handleCookiePopup = false,
+        ?array $headers = null,
         ?int $maxAgeMs = 86400000,
         Page|string|null $page = null,
         ?int $scrollOffset = null,
@@ -489,6 +491,7 @@ public function webScrapeMd(
      * @param \ContextDev\Web\WebWebScrapeScreenshotParams\Country|value-of<\ContextDev\Web\WebWebScrapeScreenshotParams\Country> $country fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2)
      * @param \ContextDev\Web\WebWebScrapeScreenshotParams\FullScreenshot|value-of<\ContextDev\Web\WebWebScrapeScreenshotParams\FullScreenshot> $fullScreenshot Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).
      * @param bool $handleCookiePopup Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.
+     * @param array<string,string> $headers Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers.
      * @param int|null $maxAgeMs Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
      * @param int|null $scrollOffset Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.
      * @param list<string> $tags Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.
@@ -507,6 +510,7 @@ public function webScrapeScreenshot(
         \ContextDev\Web\WebWebScrapeScreenshotParams\Country|string|null $country = null,
         \ContextDev\Web\WebWebScrapeScreenshotParams\FullScreenshot|string|null $fullScreenshot = null,
         bool $handleCookiePopup = false,
+        ?array $headers = null,
         ?int $maxAgeMs = 86400000,
         ?int $scrollOffset = null,
         ?array $tags = null,

src/Services/WebRawService.php

@@ -302,6 +302,7 @@ public function extractStyleguide(
      *   domain?: string,
      *   fullScreenshot?: FullScreenshot|value-of<FullScreenshot>,
      *   handleCookiePopup?: bool,
+     *   headers?: array<string,string>,
      *   maxAgeMs?: int|null,
      *   page?: Page|value-of<Page>,
      *   scrollOffset?: int|null,
@@ -642,6 +643,7 @@ public function webScrapeMd(
      *   country?: value-of<WebWebScrapeScreenshotParams\Country>,
      *   fullScreenshot?: WebWebScrapeScreenshotParams\FullScreenshot|value-of<WebWebScrapeScreenshotParams\FullScreenshot>,
      *   handleCookiePopup?: bool,
+     *   headers?: array<string,string>,
      *   maxAgeMs?: int|null,
      *   scrollOffset?: int|null,
      *   tags?: list<string>,

src/Services/WebService.php

@@ -328,6 +328,7 @@ public function extractStyleguide(
      * @param string $domain Domain name to take screenshot of (e.g., 'example.com', 'google.com'). The domain will be automatically normalized and validated. You must provide either 'domain' or 'directUrl', but not both.
      * @param FullScreenshot|value-of<FullScreenshot> $fullScreenshot Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).
      * @param bool $handleCookiePopup Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.
+     * @param array<string,string> $headers Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers.
      * @param int|null $maxAgeMs Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
      * @param Page|value-of<Page> $page Optional parameter to specify which page type to screenshot. If provided, the system will scrape the domain's links and use heuristics to find the most appropriate URL for the specified page type (30 supported languages). If not provided, screenshots the main domain landing page. Only applicable when using 'domain', not 'directUrl'.
      * @param int|null $scrollOffset Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.
@@ -348,6 +349,7 @@ public function screenshot(
         ?string $domain = null,
         FullScreenshot|string|null $fullScreenshot = null,
         bool $handleCookiePopup = false,
+        ?array $headers = null,
         ?int $maxAgeMs = 86400000,
         Page|string|null $page = null,
         ?int $scrollOffset = null,
@@ -367,6 +369,7 @@ public function screenshot(
                 'domain' => $domain,
                 'fullScreenshot' => $fullScreenshot,
                 'handleCookiePopup' => $handleCookiePopup,
+                'headers' => $headers,
                 'maxAgeMs' => $maxAgeMs,
                 'page' => $page,
                 'scrollOffset' => $scrollOffset,
@@ -808,6 +811,7 @@ public function webScrapeMd(
      * @param \ContextDev\Web\WebWebScrapeScreenshotParams\Country|value-of<\ContextDev\Web\WebWebScrapeScreenshotParams\Country> $country fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2)
      * @param \ContextDev\Web\WebWebScrapeScreenshotParams\FullScreenshot|value-of<\ContextDev\Web\WebWebScrapeScreenshotParams\FullScreenshot> $fullScreenshot Optional parameter to determine screenshot type. If 'true', takes a full page screenshot capturing all content. If 'false' or not provided, takes a viewport screenshot (standard browser view).
      * @param bool $handleCookiePopup Optional parameter to control cookie/consent popup handling. If 'true', we dismiss cookie banner before capture. If 'false' or not provided, captures the page without that step.
+     * @param array<string,string> $headers Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers.
      * @param int|null $maxAgeMs Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
      * @param int|null $scrollOffset Optional vertical scroll offset in pixels for capturing a long page in viewport-sized chunks. When provided, the full page is captured once and the returned image is the viewport-sized slice that begins at this Y offset (e.g. request scrollOffset=0, then 1080, then 2160 to walk a 1920x1080 landing page top to bottom). The final slice may be shorter than the viewport height. Takes precedence over fullScreenshot. Max: 100000.
      * @param list<string> $tags Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.
@@ -826,6 +830,7 @@ public function webScrapeScreenshot(
         \ContextDev\Web\WebWebScrapeScreenshotParams\Country|string|null $country = null,
         \ContextDev\Web\WebWebScrapeScreenshotParams\FullScreenshot|string|null $fullScreenshot = null,
         bool $handleCookiePopup = false,
+        ?array $headers = null,
         ?int $maxAgeMs = 86400000,
         ?int $scrollOffset = null,
         ?array $tags = null,
@@ -845,6 +850,7 @@ public function webScrapeScreenshot(
                 'country' => $country,
                 'fullScreenshot' => $fullScreenshot,
                 'handleCookiePopup' => $handleCookiePopup,
+                'headers' => $headers,
                 'maxAgeMs' => $maxAgeMs,
                 'scrollOffset' => $scrollOffset,
                 'tags' => $tags,

src/Web/WebScreenshotParams.php

@@ -32,6 +32,7 @@
  *   domain?: string|null,
  *   fullScreenshot?: null|FullScreenshot|value-of<FullScreenshot>,
  *   handleCookiePopup?: bool|null,
+ *   headers?: array<string,string>|null,
  *   maxAgeMs?: int|null,
  *   page?: null|Page|value-of<Page>,
  *   scrollOffset?: int|null,
@@ -96,6 +97,14 @@ final class WebScreenshotParams implements BaseModel
     #[Optional]
     public ?bool $handleCookiePopup;
 
+    /**
+     * Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers.
+     *
+     * @var array<string,string>|null $headers
+     */
+    #[Optional(map: 'string')]
+    public ?array $headers;
+
     /**
      * Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
      */
@@ -163,6 +172,7 @@ public function __construct()
      * @param ColorScheme|value-of<ColorScheme>|null $colorScheme
      * @param Country|value-of<Country>|null $country
      * @param FullScreenshot|value-of<FullScreenshot>|null $fullScreenshot
+     * @param array<string,string>|null $headers
      * @param Page|value-of<Page>|null $page
      * @param list<string>|null $tags
      * @param TimeoutOpts|TimeoutOptsShape|null $timeoutOpts
@@ -177,6 +187,7 @@ public static function with(
         ?string $domain = null,
         FullScreenshot|string|null $fullScreenshot = null,
         ?bool $handleCookiePopup = null,
+        ?array $headers = null,
         ?int $maxAgeMs = null,
         Page|string|null $page = null,
         ?int $scrollOffset = null,
@@ -195,6 +206,7 @@ public static function with(
         null !== $domain && $self['domain'] = $domain;
         null !== $fullScreenshot && $self['fullScreenshot'] = $fullScreenshot;
         null !== $handleCookiePopup && $self['handleCookiePopup'] = $handleCookiePopup;
+        null !== $headers && $self['headers'] = $headers;
         null !== $maxAgeMs && $self['maxAgeMs'] = $maxAgeMs;
         null !== $page && $self['page'] = $page;
         null !== $scrollOffset && $self['scrollOffset'] = $scrollOffset;
@@ -291,6 +303,19 @@ public function withHandleCookiePopup(bool $handleCookiePopup): self
         return $self;
     }
 
+    /**
+     * Optional outbound HTTP headers, using the same JSON object or deep-object query format as other scrape endpoints (for example headers[Authorization]=Bearer token). Headers are scoped to the target origin during capture. For domain/page requests, discovery receives no custom headers and only pages on the resolved origin are eligible. Non-empty headers bypass screenshot caching and return an in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted headers.
+     *
+     * @param array<string,string> $headers
+     */
+    public function withHeaders(array $headers): self
+    {
+        $self = clone $this;
+        $self['headers'] = $headers;
+
+        return $self;
+    }
+
     /**
      * Return a cached screenshot if a prior screenshot for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
      */

src/Web/WebScreenshotResponse.php

@@ -81,7 +81,7 @@ final class WebScreenshotResponse implements BaseModel
     public ?KeyMetadata $keyMetadata;
 
     /**
-     * Public image URL for standard requests, or an in-memory data URL when ZDR is enabled.
+     * Public image URL for standard requests, or an in-memory data URL when ZDR or non-empty custom headers are supplied.
      */
     #[Optional]
     public ?string $screenshot;
@@ -250,7 +250,7 @@ public function withKeyMetadata(KeyMetadata|array $keyMetadata): self
     }
 
     /**
-     * Public image URL for standard requests, or an in-memory data URL when ZDR is enabled.
+     * Public image URL for standard requests, or an in-memory data URL when ZDR or non-empty custom headers are supplied.
      */
     public function withScreenshot(string $screenshot): self
     {