stagehand 4.2.0a0.dev1541__tar.gz → 4.2.0a0.dev1544__tar.gz

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.2.0a0.dev1541
+Version: 4.2.0a0.dev1544
 Summary: Browserbase's SDK for building browser agents
 Keywords: ai,browser,automation,web-scraping,testing
 Author: Browserbase

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stagehand"
-version = "4.2.0a0.dev1541"
+version = "4.2.0a0.dev1544"
 description = "Browserbase's SDK for building browser agents"
 readme = "README.md"
 requires-python = ">=3.11"

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/src/stagehand/__init__.py

@@ -11,6 +11,7 @@ from ._generated.input_types import (
     ModelConfig,
     PageDragAndDropRoutePoint,
     PageEventName,
+    PagePDFMargin,
     PageScreenshotClip,
     RgbaColor,
     TelemetryConfig,
@@ -147,6 +148,7 @@ __all__ = [
     "ToolsRemovedListener",
     "WebMCPToolIdentity",
     "PageEventName",
+    "PagePDFMargin",
     "PageScreenshotClip",
     "ProtocolLocator",
     "RgbaColor",

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/src/stagehand/_extension/service-worker.js

@@ -7305,6 +7305,10 @@ var defaultOpaqueKeys = /* @__PURE__ */ new Set([
 	"data",
 	"userMetadata"
 ]);
+var apiAcronymWireKeys = {
+	base_url: "base_URL",
+	prefer_css_page_size: "prefer_CSS_page_size"
+};
 function wireSchema(schema, options = {}) {
 	return preprocess((value) => isCaseable(value) ? camelcaseKeys(preserveApiAcronyms(value, options.opaqueKeys), {
 		deep: true,
@@ -7347,7 +7351,7 @@ function preserveApiAcronyms(value, additionalOpaqueKeys = []) {
 	function visit(entry) {
 		if (Array.isArray(entry)) return entry.map(visit);
 		if (!isRecord$1(entry)) return entry;
-		return Object.fromEntries(Object.entries(entry).map(([key, child]) => [key === "base_url" ? "base_URL" : key, opaqueKeys.has(key) ? child : visit(child)]));
+		return Object.fromEntries(Object.entries(entry).map(([key, child]) => [Object.hasOwn(apiAcronymWireKeys, key) ? apiAcronymWireKeys[key] : key, opaqueKeys.has(key) ? child : visit(child)]));
 	}
 	return visit(value);
 }
@@ -7359,7 +7363,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "2.1.0-alpha-70f4e91f1983677c1e8ca9a86f0b738f828d059a",
+	version: "2.1.0-alpha-5acf85448e65ece824e417d3de7eac884593f794",
 	"private": true,
 	type: "module",
 	exports: {
@@ -8618,6 +8622,29 @@ var PageScreenshotOptionsSchema = strictObject({
 	path: ["quality"]
 }).meta({ id: "PageScreenshotOptions" });
 var PageScreenshotParamsSchema = PageIdParamsSchema.extend({ options: PageScreenshotOptionsSchema.optional() }).meta({ id: "PageScreenshotParams" });
+var PagePDFMarginSchema = strictObject({
+	top: number$1().nonnegative().optional(),
+	bottom: number$1().nonnegative().optional(),
+	left: number$1().nonnegative().optional(),
+	right: number$1().nonnegative().optional()
+}).meta({ id: "PagePDFMargin" });
+var PagePDFOptionsSchema = strictObject({
+	landscape: boolean().optional(),
+	displayHeaderFooter: boolean().optional(),
+	printBackground: boolean().optional(),
+	scale: number$1().min(.1).max(2).optional(),
+	width: number$1().positive().optional(),
+	height: number$1().positive().optional(),
+	margin: PagePDFMarginSchema.optional(),
+	pageRanges: string().optional(),
+	headerTemplate: string().optional(),
+	footerTemplate: string().optional(),
+	preferCSSPageSize: boolean().optional(),
+	tagged: boolean().optional(),
+	outline: boolean().optional(),
+	timeout: number$1().nonnegative().max(2147473647).optional()
+}).meta({ id: "PagePDFOptions" });
+var PagePDFParamsSchema = PageIdParamsSchema.extend({ options: PagePDFOptionsSchema.optional() }).meta({ id: "PagePDFParams" });
 var PageSnapshotParamsSchema = PageIdParamsSchema.extend({ options: PageSnapshotOptionsSchema.optional() }).meta({ id: "PageSnapshotParams" });
 var PageSetViewportSizeParamsSchema = PageIdParamsSchema.extend({
 	width: number$1().int().positive(),
@@ -8698,6 +8725,7 @@ var PageTitleResultSchema = string().meta({ id: "PageTitleResult" });
 var PageCloseResultSchema = strictObject({ closed: literal(true) }).meta({ id: "PageCloseResult" });
 var PageEvaluateResultSchema = strictObject({ value: json$1() }).meta({ id: "PageEvaluateResult" });
 var PageScreenshotResultSchema = strictObject({ data: base64().meta({ format: "byte" }) }).meta({ id: "PageScreenshotResult" });
+var PagePDFResultSchema = strictObject({ data: base64().meta({ format: "byte" }) }).meta({ id: "PagePDFResult" });
 var PageWaitForSelectorResultSchema = strictObject({ matched: boolean() }).meta({ id: "PageWaitForSelectorResult" });
 var LocatorClickResultSchema = strictObject({ clicked: literal(true) }).meta({ id: "LocatorClickResult" });
 var LocatorFillResultSchema = strictObject({ filled: literal(true) }).meta({ id: "LocatorFillResult" });
@@ -8977,6 +9005,11 @@ var StagehandMethods = {
 		params: PageScreenshotParamsSchema,
 		result: PageScreenshotResultSchema
 	},
+	pagePDF: {
+		name: "page.pdf",
+		params: PagePDFParamsSchema,
+		result: PagePDFResultSchema
+	},
 	pageSnapshot: {
 		name: "page.snapshot",
 		params: PageSnapshotParamsSchema,
@@ -12323,24 +12356,20 @@ var Page$1 = class {
 	}
 	async screenshot(options) {
 		const { path, mask, ...screenshotOptions } = options ?? {};
-		const bytes = decodeBase64((await this.rpcClient.send(StagehandMethods.pageScreenshot, {
+		return await decodeCaptureResult((await this.rpcClient.send(StagehandMethods.pageScreenshot, {
 			pageId: this.pageId,
 			options: {
 				...screenshotOptions,
 				...mask ? { mask: mask.map((locator) => locator.descriptor) } : {}
 			}
-		})).data, "page.screenshot");
-		if (path) {
-			const moduleName = "node:fs/promises";
-			const { writeFile } = await __vitePreload(() => import(
-				/* @vite-ignore */
-				moduleName
-), []).catch(() => {
-				throw new TypeError("page.screenshot(): path is only supported in Node.js; omit path to receive screenshot bytes");
-			});
-			await writeFile(path, bytes);
-		}
-		return bytes;
+		})).data, "screenshot", path);
+	}
+	async pdf(options) {
+		const { path, ...pdfOptions } = options ?? {};
+		return await decodeCaptureResult((await this.rpcClient.send(StagehandMethods.pagePDF, {
+			pageId: this.pageId,
+			options: pdfOptions
+		})).data, "pdf", path);
 	}
 	async snapshot(options) {
 		return await this.rpcClient.send(StagehandMethods.pageSnapshot, {
@@ -12371,6 +12400,20 @@ var Page$1 = class {
 		});
 	}
 };
+async function decodeCaptureResult(data, method, path) {
+	const bytes = decodeBase64(data, `page.${method}`);
+	if (path !== void 0) {
+		const moduleName = "node:fs/promises";
+		const { writeFile } = await __vitePreload(() => import(
+			/* @vite-ignore */
+			moduleName
+), []).catch(() => {
+			throw new TypeError(`page.${method}(): path is only supported in Node.js; omit path to receive ${method === "pdf" ? "PDF" : "screenshot"} bytes`);
+		});
+		await writeFile(path, bytes);
+	}
+	return bytes;
+}
 function reportPageEventListenerError(error) {
 	process.emitWarning(error instanceof Error ? error.message : String(error), { code: "STAGEHAND_PAGE_EVENT_LISTENER_ERROR" });
 }
@@ -12931,6 +12974,10 @@ function createPageController(runtime) {
 		logger.debug("page.screenshot", {});
 		return runtime.pageScreenshot(params);
 	}
+	async function pdf(params, { logger }) {
+		logger.debug("page.pdf", {});
+		return runtime.pagePDF(params);
+	}
 	async function snapshot(params, { logger }) {
 		logger.debug("page.snapshot", {});
 		return runtime.pageSnapshot(params);
@@ -12990,6 +13037,7 @@ function createPageController(runtime) {
 		waitForTimeout,
 		waitForSelector,
 		screenshot,
+		pdf,
 		snapshot,
 		webMCPTools,
 		webMCPInvokeTool,
@@ -16290,7 +16338,7 @@ function resolveMaskRect(maskToken) {
 //#region understudy/screenshotUtils.ts
 var screenshotQueues = /* @__PURE__ */ new WeakMap();
 /** Serialize page mutations, or the browser-wide activation/capture critical section. */
-async function withScreenshotLock(owner, capture, timeout) {
+async function withScreenshotLock(owner, capture, timeout, operation = "screenshot") {
 	const queue = screenshotQueues.get(owner) ?? {
 		tail: Promise.resolve(),
 		blocked: new AbortController()
@@ -16299,8 +16347,9 @@ async function withScreenshotLock(owner, capture, timeout) {
 	const controller = new AbortController();
 	let started = false;
 	const timer = typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0 ? setTimeout(() => {
-		controller.abort(new TimeoutError("screenshot", timeout));
-		if (started) queue.blocked.abort(/* @__PURE__ */ new Error("screenshot: a previous timed-out capture is still recovering"));
+		const error = new TimeoutError(operation, timeout);
+		controller.abort(error);
+		if (started) queue.blocked.abort(new Error(`A previous capture is still recovering: ${error.message}`, { cause: error }));
 	}, Math.min(timeout, 2147483647)) : void 0;
 	const pending = queue.tail.then(() => {
 		queue.blocked.signal.throwIfAborted();
@@ -51568,6 +51617,7 @@ var RPCRouter = class {
 			case "page.wait_for_timeout": return this.pageController.waitForTimeout(parseParams(StagehandMethods.pageWaitForTimeout, request.params), context);
 			case "page.wait_for_selector": return this.pageController.waitForSelector(parseParams(StagehandMethods.pageWaitForSelector, request.params), context);
 			case "page.screenshot": return this.pageController.screenshot(parseParams(StagehandMethods.pageScreenshot, request.params), context);
+			case "page.pdf": return this.pageController.pdf(parseParams(StagehandMethods.pagePDF, request.params), context);
 			case "page.snapshot": return this.pageController.snapshot(parseParams(StagehandMethods.pageSnapshot, request.params), context);
 			case "page.webmcp_tools": return this.pageController.webMCPTools(parseParams(StagehandMethods.pageWebMCPTools, request.params), context);
 			case "page.webmcp_invoke_tool": return this.pageController.webMCPInvokeTool(parseParams(StagehandMethods.pageWebMCPInvokeTool, request.params), context);
@@ -53961,7 +54011,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.1.0-alpha-70f4e91f1983677c1e8ca9a86f0b738f828d059a",
+	version: "1.1.0-alpha-5acf85448e65ece824e417d3de7eac884593f794",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -56387,6 +56437,25 @@ var Page = class Page {
 		};
 		return await withScreenshotLock(this, exec, opts.timeout);
 	}
+	/** Keep the PDF base64-encoded for transport; SDKs decode it to bytes. */
+	async pdf(options) {
+		const { timeout = 3e4, width, height, margin, tagged = false, outline = false, ...printOptions } = options ?? {};
+		return await withScreenshotLock(this, async () => {
+			const { data } = await this.mainSession.send("Page.printToPDF", {
+				...printOptions,
+				paperWidth: width,
+				paperHeight: height,
+				marginTop: margin?.top ?? 0,
+				marginBottom: margin?.bottom ?? 0,
+				marginLeft: margin?.left ?? 0,
+				marginRight: margin?.right ?? 0,
+				generateTaggedPDF: tagged,
+				generateDocumentOutline: outline,
+				transferMode: "ReturnAsBase64"
+			});
+			return { data };
+		}, timeout, "pdf");
+	}
 	/**
 	* specifies additional HTTP headers to be included in every request sent by
 	* the root CDP session of the page, and all of its child CDP sessions.
@@ -57659,6 +57728,9 @@ var StagehandRuntime = class {
 		}
 		return { data: bytesToBase64(await page.screenshot(options)) };
 	}
+	async pagePDF(params) {
+		return await this.resolvePage(params.pageId).pdf(params.options);
+	}
 	async pageSnapshot(params) {
 		return await this.resolvePage(params.pageId).snapshot(params.options);
 	}

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/src/stagehand/_generated/input_types.py

@@ -781,6 +781,39 @@ class PageOffParams(TypedDict):
     subscription_id: str
 
 
+class PagePDFMargin(TypedDict):
+    top: NotRequired[float]
+    bottom: NotRequired[float]
+    left: NotRequired[float]
+    right: NotRequired[float]
+
+
+class PagePDFOptions(TypedDict):
+    landscape: NotRequired[bool]
+    display_header_footer: NotRequired[bool]
+    print_background: NotRequired[bool]
+    scale: NotRequired[float]
+    width: NotRequired[float]
+    height: NotRequired[float]
+    margin: NotRequired[PagePDFMargin]
+    page_ranges: NotRequired[str]
+    header_template: NotRequired[str]
+    footer_template: NotRequired[str]
+    prefer_css_page_size: NotRequired[bool]
+    tagged: NotRequired[bool]
+    outline: NotRequired[bool]
+    timeout: NotRequired[float]
+
+
+class PagePDFParams(TypedDict):
+    page_id: str
+    options: NotRequired[PagePDFOptions]
+
+
+class PagePDFResult(TypedDict):
+    data: str
+
+
 class PageRef(TypedDict):
     page_id: str
     url: NotRequired[str]

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/src/stagehand/_generated/models.py

@@ -1677,6 +1677,61 @@ class PageOnParams(WireModel):
     event: PageSubscriptionEventName
 
 
+class PagePDFMargin(WireModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_by_name=True,
+    )
+    top: Annotated[Optional[StrictFloat], Field(ge=0.0)] = None
+    bottom: Annotated[Optional[StrictFloat], Field(ge=0.0)] = None
+    left: Annotated[Optional[StrictFloat], Field(ge=0.0)] = None
+    right: Annotated[Optional[StrictFloat], Field(ge=0.0)] = None
+
+
+class PagePDFOptions(WireModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_by_name=True,
+    )
+    landscape: Optional[StrictBool] = None
+    display_header_footer: Optional[StrictBool] = None
+    print_background: Optional[StrictBool] = None
+    scale: Annotated[Optional[StrictFloat], Field(ge=0.1, le=2.0)] = None
+    width: Annotated[Optional[StrictFloat], Field(gt=0.0)] = None
+    height: Annotated[Optional[StrictFloat], Field(gt=0.0)] = None
+    margin: Optional[PagePDFMargin] = None
+    page_ranges: Optional[StrictStr] = None
+    header_template: Optional[StrictStr] = None
+    footer_template: Optional[StrictStr] = None
+    prefer_css_page_size: Optional[StrictBool] = None
+    tagged: Optional[StrictBool] = None
+    outline: Optional[StrictBool] = None
+    timeout: Annotated[Optional[StrictFloat], Field(ge=0.0, le=2147473647.0)] = None
+
+
+class PagePDFParams(WireModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_by_name=True,
+    )
+    page_id: StrictStr
+    options: Optional[PagePDFOptions] = None
+
+
+class PagePDFResult(WireModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_by_name=True,
+    )
+    data: Annotated[
+        StrictStr,
+        Field(
+            json_schema_extra={"contentEncoding": "base64"},
+            pattern="^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$",
+        ),
+    ]
+
+
 class PageRef(WireModel):
     model_config = ConfigDict(
         extra="forbid",

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/src/stagehand/_generated/protocol_version.py

@@ -1,4 +1,4 @@
 """Generated from packages/protocol/package.json. Do not edit."""
 
 PROTOCOL_SEMVER_PATTERN = '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$'
-STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-70f4e91f1983677c1e8ca9a86f0b738f828d059a'
+STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-5acf85448e65ece824e417d3de7eac884593f794'

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/src/stagehand/page.py

@@ -14,6 +14,7 @@ from pydantic import JsonValue, TypeAdapter
 from ._generated.input_types import (
     PageDragAndDropRoutePoint,
     PageEventName,
+    PagePDFMargin,
     PageScreenshotClip,
     PageSubscriptionEventName,
 )
@@ -44,6 +45,9 @@ from ._generated.models import (
     PageNavigationResult,
     PageOffParams,
     PageOnParams,
+    PagePDFOptions,
+    PagePDFParams,
+    PagePDFResult,
     PageRef,
     PageReloadOptions,
     PageReloadParams,
@@ -613,6 +617,54 @@ class Page:
             Path(path).write_bytes(data)
         return data
 
+    async def pdf(
+        self,
+        *,
+        landscape: bool | None = None,
+        display_header_footer: bool | None = None,
+        print_background: bool | None = None,
+        scale: float | None = None,
+        width: float | None = None,
+        height: float | None = None,
+        margin: PagePDFMargin | None = None,
+        page_ranges: str | None = None,
+        header_template: str | None = None,
+        footer_template: str | None = None,
+        prefer_css_page_size: bool | None = None,
+        tagged: bool | None = None,
+        outline: bool | None = None,
+        timeout: float | None = None,
+        path: str | Path | None = None,
+    ) -> bytes:
+        params = PagePDFParams(page_id=self.page_id)
+        options = PagePDFOptions.model_validate({
+            name: value
+            for name, value in (
+                ("landscape", landscape),
+                ("display_header_footer", display_header_footer),
+                ("print_background", print_background),
+                ("scale", scale),
+                ("width", width),
+                ("height", height),
+                ("margin", margin),
+                ("page_ranges", page_ranges),
+                ("header_template", header_template),
+                ("footer_template", footer_template),
+                ("prefer_css_page_size", prefer_css_page_size),
+                ("tagged", tagged),
+                ("outline", outline),
+                ("timeout", timeout),
+            )
+            if value is not None
+        })
+        if options.model_fields_set:
+            params.options = options
+        result = await self._rpc_client.send("page.pdf", params, PagePDFResult)
+        data = base64.b64decode(result.data, validate=True)
+        if path is not None:
+            Path(path).write_bytes(data)
+        return data
+
     async def snapshot(self, *, include_iframes: bool | None = None) -> SnapshotResult:
         params = PageSnapshotParams(page_id=self.page_id)
         if include_iframes is not None:

{stagehand-4.2.0a0.dev1541 → stagehand-4.2.0a0.dev1544}/src/stagehand/rpc_client.py

@@ -29,6 +29,7 @@ _DEFAULT_OPERATION_TIMEOUT_MS = {
     "page.go_forward": 15_000,
     "page.wait_for_load_state": 15_000,
     "page.wait_for_selector": 30_000,
+    "page.pdf": 30_000,
     "page.webmcp_tools": 1_000,
 }
 _UNBOUNDED_BY_DEFAULT_METHODS = {
@@ -207,7 +208,8 @@ class RPCClient:
             tracestate=trace_context.get("tracestate"),
         )
 
-        response_timeout = asyncio.timeout(_rpc_response_timeout_seconds(method, parsed_params))
+        response_timeout_seconds = _rpc_response_timeout_seconds(method, parsed_params)
+        response_timeout = asyncio.timeout(response_timeout_seconds)
         try:
             try:
                 async with response_timeout:
@@ -219,8 +221,10 @@ class RPCClient:
                     )
                     return await response
             except TimeoutError as error:
-                if response_timeout.expired():
-                    raise TimeoutError(f"RPC response timed out: {method}") from error
+                if response_timeout.expired() and response_timeout_seconds is not None:
+                    raise TimeoutError(
+                        f"RPC response timed out after {response_timeout_seconds:g}s: {method}"
+                    ) from error
                 raise
         finally:
             self._pending.pop(request_id, None)
@@ -543,6 +547,7 @@ def _rpc_response_timeout_seconds(method: str, params: BaseModel) -> float | Non
         "page.go_back",
         "page.go_forward",
         "page.screenshot",
+        "page.pdf",
         "page.wait_for_selector",
         "page.webmcp_tools",
         "page.webmcp_invocation_result",
@@ -554,6 +559,8 @@ def _rpc_response_timeout_seconds(method: str, params: BaseModel) -> float | Non
         operation_timeout_ms = _numeric_property(params, "ms")
 
     if operation_timeout_ms is not None:
+        if method == "page.pdf" and operation_timeout_ms == 0:
+            return None
         return (_RPC_RESPONSE_GRACE_MS + max(0, operation_timeout_ms)) / 1_000
 
     if (default_timeout_ms := _DEFAULT_OPERATION_TIMEOUT_MS.get(method)) is not None: