Files
Use files to stage host-provided bytes for browser-side upload workflows.| Method | Signature | Description |
|---|---|---|
browser.files.create | (input: CreateBrowserFileOptions) => Promise<BrowserFileSummary> | Stage a file from memory. |
browser.files.createFromPath | (path: string, options?: CreateBrowserFileFromPathOptions) => Promise<BrowserFileSummary> | Stage a file from a local path. |
browser.files.list | (options?: BrowserArtifactListOptions) => Promise<ListBrowserFilesResponse> | List staged files. |
browser.files.get | (fileId: FileId, options?: { signal?: AbortSignal }) => Promise<BrowserFileSummary> | Fetch staged file metadata. |
browser.files.content | (fileId: FileId, options?: { signal?: AbortSignal }) => Promise<Uint8Array> | Download staged file bytes. |
browser.files.delete | (fileId: FileId, options?: { signal?: AbortSignal }) => Promise<void> | Delete a staged file. |
CreateBrowserFileOptions fields:
| Field | Description |
|---|---|
name | File name. Required. |
mimeType | Optional MIME type. |
base64 | Base64-encoded contents. |
bytes | Raw bytes. |
signal | Abort signal. |
Downloads
| Method | Signature | Description |
|---|---|---|
browser.downloads.list | (options?: BrowserArtifactListOptions) => Promise<ListBrowserDownloadsResponse> | List browser downloads. |
browser.downloads.get | (downloadId: DownloadId, options?: { signal?: AbortSignal }) => Promise<BrowserDownloadSummary> | Fetch download metadata. |
browser.downloads.content | (downloadId: DownloadId, options?: { signal?: AbortSignal; maxBytes?: number }) => Promise<Uint8Array> | Fetch download bytes, optionally capped by maxBytes. |
browser.downloads.save | (downloadId: DownloadId, outputPath: string, options?: BrowserDownloadSaveOptions) => Promise<BrowserDownloadSaveResult> | Save download bytes to a local file. |
BrowserDownloadSaveOptions:
| Field | Description |
|---|---|
overwrite | Replace an existing output file. Defaults to false. |
maxBytes | Maximum bytes to save. |
signal | Abort signal. |
Dialogs
| Method | Signature | Description |
|---|---|---|
browser.dialogs.list | (options?: { pageId?: PageId; status?: "open" | "recent"; cursor?: string; limit?: number; signal?: AbortSignal }) => Promise<ListBrowserDialogsResponse> | List JavaScript dialogs. |
browser.dialogs.accept | (dialogId: DialogId, options?: { promptText?: string; includeState?: "auto" | "never" | "none" | "compact" | "full"; maxStateChars?: number; signal?: AbortSignal }) => Promise<BrowserDialogResponse> | Accept a dialog. promptText applies to prompt dialogs. |
browser.dialogs.dismiss | (dialogId: DialogId, options?: { includeState?: "auto" | "never" | "none" | "compact" | "full"; maxStateChars?: number; signal?: AbortSignal }) => Promise<BrowserDialogResponse> | Dismiss a dialog. |
Permissions
Use permission helpers when a workflow needs explicit browser permissions such as geolocation.| Method | Signature | Description |
|---|---|---|
browser.permissions.grant | (request: BrowserPermissionGrant & { geolocation?: BrowserGeolocation; signal?: AbortSignal }) => Promise<BrowserPermissionsResponse> | Grant permissions. |
browser.permissions.deny | (request: BrowserPermissionGrant & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse> | Deny permissions. |
browser.permissions.clear | (request?: BrowserClearPermissionsRequest & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse> | Clear permission overrides. |
browser.permissions.reset | (request?: BrowserClearPermissionsRequest & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse> | Alias for clearing permission overrides. |
Recordings
Recording methods are useful only for browsers created withrecording: true.
| Method | Signature | Description |
|---|---|---|
browser.recordings.get | (options?: { signal?: AbortSignal }) => Promise<BrowserRecordingResponse> | Fetch recording summary. |
browser.recordings.segments | (options?: RecordingListOptions) => Promise<ListRecordingSegmentsResponse> | List recording segments. |
browser.recordings.segment | (segmentId: RecordingSegmentId, options?: { signal?: AbortSignal }) => Promise<RecordingSegmentManifestResponse> | Fetch a segment manifest. |
browser.recordings.events | (segmentId: RecordingSegmentId, options?: RecordingEventsOptions) => Promise<ListRecordingEventsResponse> | List events for one segment. |
browser.recordings.frame | (segmentId: RecordingSegmentId, frameKey: string, options?: { signal?: AbortSignal }) => Promise<Uint8Array> | Fetch a recorded frame. |
browser.recordings.download | (segmentId: RecordingSegmentId, outputDir: string, options?: RecordingDownloadOptions) => Promise<RecordingDownloadResult> | Download manifest, events, and frames to local files. |
RecordingDownloadResult contains segmentId, outputDir, manifestPath, eventsPath, and framePaths.
Events
| Method | Signature | Description |
|---|---|---|
browser.events | (options?: BrowserEventsOptions) => Promise<ListBrowserEventsResponse> | Fetch browser events. |
browser.streamEvents | (options?: BrowserEventStreamOptions) => AsyncIterable<BrowserEvent> | Poll events as an async stream. |
BrowserEventsOptions fields:
| Field | Description |
|---|---|
cursor | Pagination cursor. |
limit | Results per page. |
since | Lower time bound. |
until | Upper time bound. |
type | Event type filter. |
category | Event category filter. |
pageId | Page filter. |
severity | Event severity filter. |
visibility | Event visibility filter. |
signal | Abort signal. |
BrowserEventStreamOptions also accepts pollIntervalMs.
Pages
browser.pages(options?) returns page summaries with:
| Field | Description |
|---|---|
id | Page ID. |
browserId | Browser ID. |
url | Current page URL. |
title | Current page title. |
active | Whether this page is the active page. |
CAPTCHA and blockers
| Method | Signature | Description |
|---|---|---|
browser.captcha.status | (options?: { signal?: AbortSignal }) => Promise<BrowserStatusResponse> | Fetch compact blocker status. |
browser.captcha.resolve | (options?: BrowserCaptchaResolveOptions) => Promise<ResolveCaptchaResponse> | Ask the runtime to resolve a detected CAPTCHA blocker. |
BrowserCaptchaResolveOptions accepts resolver options plus signal.