Skip to content

Commit 82c0889

Browse files
author
stlc-bot
committed
seal
1 parent 085f227 commit 82c0889

9 files changed

Lines changed: 817 additions & 25 deletions

‎src/context/dev/resources/web.py‎

Lines changed: 524 additions & 16 deletions
Large diffs are not rendered by default.

‎src/context/dev/types/web_screenshot_params.py‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
from __future__ import annotations
44

5-
from typing import Optional
5+
from typing import Dict, Optional
66
from typing_extensions import Literal, Required, Annotated, TypedDict
77

88
from .._types import SequenceNotStr
@@ -266,6 +266,17 @@ class WebScreenshotParams(TypedDict, total=False):
266266
captures the page without that step.
267267
"""
268268

269+
headers: Dict[str, str]
270+
"""
271+
Optional outbound HTTP headers, using the same JSON object or deep-object query
272+
format as other scrape endpoints (for example headers[Authorization]=Bearer
273+
token). Headers are scoped to the target origin during capture. For domain/page
274+
requests, discovery receives no custom headers and only pages on the resolved
275+
origin are eligible. Non-empty headers bypass screenshot caching and return an
276+
in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted
277+
headers.
278+
"""
279+
269280
max_age_ms: Annotated[Optional[int], PropertyInfo(alias="maxAgeMs")]
270281
"""
271282
Return a cached screenshot if a prior screenshot for the same parameters exists

‎src/context/dev/types/web_screenshot_response.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,8 +74,8 @@ class WebScreenshotResponse(BaseModel):
7474

7575
screenshot: Optional[str] = None
7676
"""
77-
Public image URL for standard requests, or an in-memory data URL when ZDR is
78-
enabled.
77+
Public image URL for standard requests, or an in-memory data URL when ZDR or
78+
non-empty custom headers are supplied.
7979
"""
8080

8181
screenshot_type: Optional[Literal["viewport", "fullPage"]] = FieldInfo(alias="screenshotType", default=None)

‎src/context/dev/types/web_web_scrape_bytes_params.py‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
from __future__ import annotations
44

5-
from typing import Dict
5+
from typing import Dict, Optional
66
from typing_extensions import Literal, Required, Annotated, TypedDict
77

88
from .._types import SequenceNotStr
@@ -232,7 +232,15 @@ class WebWebScrapeBytesParams(TypedDict, total=False):
232232
Send as a JSON object or deep-object query params such as
233233
headers[Referer]=https://example.com/. Host, Content-Length, and hop-by-hop
234234
transport headers are rejected. Authorization and cookies are removed when a
235-
redirect changes origin.
235+
redirect changes origin. Credential-bearing headers bypass cache reads and
236+
writes; other headers are included in the cache key.
237+
"""
238+
239+
max_age_ms: Annotated[Optional[int], PropertyInfo(alias="maxAgeMs")]
240+
"""
241+
Return a cached result if a prior scrape for the same parameters exists and is
242+
younger than this many milliseconds. Defaults to 1 day (86400000 ms) when
243+
omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.
236244
"""
237245

238246
tags: SequenceNotStr[str]
@@ -248,6 +256,16 @@ class WebWebScrapeBytesParams(TypedDict, total=False):
248256
or a JSON-encoded timeoutOpts object.
249257
"""
250258

259+
wait_for_ms: Annotated[Optional[int], PropertyInfo(alias="waitForMs")]
260+
"""
261+
Optional browser wait time after initial page load, in milliseconds (0–30000; 0
262+
uses 500). When supplied, HTML is rendered with JavaScript and returned as UTF-8
263+
bytes. Other resources keep their original bytes without a browser wait. Omit to
264+
download the original HTTP response. When combined with timeoutOpts,
265+
timeoutOpts.milliseconds must be at least waitForMs + 10000 ms; a shorter
266+
deadline is rejected with 400 TIMEOUT_TOO_SHORT_FOR_WAIT.
267+
"""
268+
251269
zdr: Literal["enabled", "disabled"]
252270
"""
253271
Set to enabled to bypass shared caches and omit request and response content

‎src/context/dev/types/web_web_scrape_bytes_response.py‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,23 @@
77

88
from .._models import BaseModel
99

10-
__all__ = ["WebWebScrapeBytesResponse", "KeyMetadata"]
10+
__all__ = ["WebWebScrapeBytesResponse", "CacheMetadata", "KeyMetadata"]
11+
12+
13+
class CacheMetadata(BaseModel):
14+
"""Cache outcome for this response.
15+
16+
Composite responses are hits only when every cache-controlled fetch contributing to the output was a hit; age_ms is the oldest contributing hit.
17+
"""
18+
19+
age_ms: int
20+
"""Age of the cached data in milliseconds. Zero for miss and zdr responses."""
21+
22+
status: Literal["hit", "miss", "zdr"]
23+
"""
24+
Whether the response was served from cache, required fresh work, or honored
25+
zero-data-retention cache bypass.
26+
"""
1127

1228

1329
class KeyMetadata(BaseModel):
@@ -27,6 +43,13 @@ class WebWebScrapeBytesResponse(BaseModel):
2743
Decode this field to recover the downloaded file.
2844
"""
2945

46+
cache_metadata: CacheMetadata
47+
"""Cache outcome for this response.
48+
49+
Composite responses are hits only when every cache-controlled fetch contributing
50+
to the output was a hit; age_ms is the oldest contributing hit.
51+
"""
52+
3053
content_length: int = FieldInfo(alias="contentLength")
3154
"""Number of decoded resource bytes, before base64 encoding."""
3255

‎src/context/dev/types/web_web_scrape_images_params.py‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,217 @@ class WebWebScrapeImagesParams(TypedDict, total=False):
3030
parameter. Maximum: 5 actions.
3131
"""
3232

33+
country: Literal[
34+
"ad",
35+
"ae",
36+
"af",
37+
"ag",
38+
"ai",
39+
"al",
40+
"am",
41+
"ao",
42+
"ar",
43+
"at",
44+
"au",
45+
"aw",
46+
"az",
47+
"ba",
48+
"bb",
49+
"bd",
50+
"be",
51+
"bf",
52+
"bg",
53+
"bh",
54+
"bi",
55+
"bj",
56+
"bm",
57+
"bn",
58+
"bo",
59+
"bq",
60+
"br",
61+
"bs",
62+
"bw",
63+
"by",
64+
"bz",
65+
"ca",
66+
"cd",
67+
"cf",
68+
"cg",
69+
"ch",
70+
"ci",
71+
"cl",
72+
"cm",
73+
"cn",
74+
"co",
75+
"cr",
76+
"cv",
77+
"cw",
78+
"cy",
79+
"cz",
80+
"de",
81+
"dj",
82+
"dk",
83+
"dm",
84+
"do",
85+
"dz",
86+
"ec",
87+
"ee",
88+
"eg",
89+
"es",
90+
"et",
91+
"fi",
92+
"fj",
93+
"fr",
94+
"ga",
95+
"gb",
96+
"gd",
97+
"ge",
98+
"gf",
99+
"gg",
100+
"gh",
101+
"gm",
102+
"gn",
103+
"gp",
104+
"gq",
105+
"gr",
106+
"gt",
107+
"gu",
108+
"gw",
109+
"gy",
110+
"hk",
111+
"hn",
112+
"hr",
113+
"ht",
114+
"hu",
115+
"id",
116+
"ie",
117+
"il",
118+
"im",
119+
"in",
120+
"iq",
121+
"ir",
122+
"is",
123+
"it",
124+
"je",
125+
"jm",
126+
"jo",
127+
"jp",
128+
"ke",
129+
"kg",
130+
"kh",
131+
"kn",
132+
"kr",
133+
"kw",
134+
"ky",
135+
"kz",
136+
"la",
137+
"lb",
138+
"lc",
139+
"lk",
140+
"lr",
141+
"ls",
142+
"lt",
143+
"lu",
144+
"lv",
145+
"ly",
146+
"ma",
147+
"mc",
148+
"md",
149+
"me",
150+
"mf",
151+
"mg",
152+
"mk",
153+
"ml",
154+
"mm",
155+
"mn",
156+
"mo",
157+
"mq",
158+
"mr",
159+
"mt",
160+
"mu",
161+
"mv",
162+
"mw",
163+
"mx",
164+
"my",
165+
"mz",
166+
"na",
167+
"nc",
168+
"ne",
169+
"ng",
170+
"ni",
171+
"nl",
172+
"no",
173+
"np",
174+
"nz",
175+
"om",
176+
"pa",
177+
"pe",
178+
"pf",
179+
"pg",
180+
"ph",
181+
"pk",
182+
"pl",
183+
"pr",
184+
"ps",
185+
"pt",
186+
"py",
187+
"qa",
188+
"re",
189+
"ro",
190+
"rs",
191+
"ru",
192+
"rw",
193+
"sa",
194+
"sc",
195+
"sd",
196+
"se",
197+
"sg",
198+
"si",
199+
"sk",
200+
"sl",
201+
"sm",
202+
"sn",
203+
"so",
204+
"sr",
205+
"ss",
206+
"st",
207+
"sv",
208+
"sx",
209+
"sy",
210+
"sz",
211+
"tc",
212+
"td",
213+
"tg",
214+
"th",
215+
"tj",
216+
"tl",
217+
"tm",
218+
"tn",
219+
"tr",
220+
"tt",
221+
"tw",
222+
"tz",
223+
"ua",
224+
"ug",
225+
"us",
226+
"uy",
227+
"uz",
228+
"vc",
229+
"ve",
230+
"vg",
231+
"vi",
232+
"vn",
233+
"ye",
234+
"yt",
235+
"za",
236+
"zm",
237+
"zw",
238+
]
239+
"""
240+
Fetch the target page through a residential proxy in this country (ISO 3166-1
241+
alpha-2).
242+
"""
243+
33244
dedupe: bool
34245
"""
35246
When true, visually duplicate images are removed: every image is loaded and

‎src/context/dev/types/web_web_scrape_screenshot_params.py‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
from __future__ import annotations
44

5-
from typing import Optional
5+
from typing import Dict, Optional
66
from typing_extensions import Literal, Required, Annotated, TypedDict
77

88
from .._types import SequenceNotStr
@@ -254,6 +254,17 @@ class WebWebScrapeScreenshotParams(TypedDict, total=False):
254254
captures the page without that step.
255255
"""
256256

257+
headers: Dict[str, str]
258+
"""
259+
Optional outbound HTTP headers, using the same JSON object or deep-object query
260+
format as other scrape endpoints (for example headers[Authorization]=Bearer
261+
token). Headers are scoped to the target origin during capture. For domain/page
262+
requests, discovery receives no custom headers and only pages on the resolved
263+
origin are eligible. Non-empty headers bypass screenshot caching and return an
264+
in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted
265+
headers.
266+
"""
267+
257268
max_age_ms: Annotated[Optional[int], PropertyInfo(alias="maxAgeMs")]
258269
"""
259270
Return a cached screenshot if a prior screenshot for the same parameters exists

‎src/context/dev/types/web_web_scrape_screenshot_response.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ class WebWebScrapeScreenshotResponse(BaseModel):
5555

5656
screenshot: str
5757
"""
58-
Public image URL for standard requests, or an in-memory data URL when ZDR is
59-
enabled.
58+
Public image URL for standard requests, or an in-memory data URL when ZDR or
59+
non-empty custom headers are supplied.
6060
"""
6161

6262
url: str

0 commit comments

Comments
 (0)