browserless-bap 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. browserless_bap-0.2.0/.gitignore +26 -0
  2. browserless_bap-0.2.0/AGENTS.md +69 -0
  3. browserless_bap-0.2.0/CONTRIBUTING.md +118 -0
  4. browserless_bap-0.2.0/LICENSE +21 -0
  5. browserless_bap-0.2.0/PKG-INFO +264 -0
  6. browserless_bap-0.2.0/README.md +229 -0
  7. browserless_bap-0.2.0/llms.txt +87 -0
  8. browserless_bap-0.2.0/pyproject.toml +97 -0
  9. browserless_bap-0.2.0/schema.lock +5 -0
  10. browserless_bap-0.2.0/scripts/__init__.py +1 -0
  11. browserless_bap-0.2.0/scripts/check_public_text.py +68 -0
  12. browserless_bap-0.2.0/scripts/codegen/__init__.py +5 -0
  13. browserless_bap-0.2.0/scripts/codegen/config/__init__.py +1 -0
  14. browserless_bap-0.2.0/scripts/codegen/config/client_only.py +45 -0
  15. browserless_bap-0.2.0/scripts/codegen/config/docs.py +11 -0
  16. browserless_bap-0.2.0/scripts/codegen/config/methods.py +199 -0
  17. browserless_bap-0.2.0/scripts/codegen/config/naming.py +44 -0
  18. browserless_bap-0.2.0/scripts/codegen/config/schema_map.py +46 -0
  19. browserless_bap-0.2.0/scripts/codegen/emit_docs.py +396 -0
  20. browserless_bap-0.2.0/scripts/codegen/emit_enums.py +37 -0
  21. browserless_bap-0.2.0/scripts/codegen/emit_events.py +153 -0
  22. browserless_bap-0.2.0/scripts/codegen/emit_inputs.py +45 -0
  23. browserless_bap-0.2.0/scripts/codegen/emit_operations.py +47 -0
  24. browserless_bap-0.2.0/scripts/codegen/emit_options.py +57 -0
  25. browserless_bap-0.2.0/scripts/codegen/emit_page.py +262 -0
  26. browserless_bap-0.2.0/scripts/codegen/emit_responses.py +49 -0
  27. browserless_bap-0.2.0/scripts/codegen/emit_types_init.py +20 -0
  28. browserless_bap-0.2.0/scripts/codegen/generate.py +64 -0
  29. browserless_bap-0.2.0/scripts/codegen/model.py +189 -0
  30. browserless_bap-0.2.0/scripts/codegen/schema.py +280 -0
  31. browserless_bap-0.2.0/scripts/codegen/writer.py +35 -0
  32. browserless_bap-0.2.0/scripts/codegen.py +30 -0
  33. browserless_bap-0.2.0/scripts/docs.py +24 -0
  34. browserless_bap-0.2.0/scripts/sync_schema.py +223 -0
  35. browserless_bap-0.2.0/src/browserless_bap/__init__.py +35 -0
  36. browserless_bap-0.2.0/src/browserless_bap/_codec.py +29 -0
  37. browserless_bap-0.2.0/src/browserless_bap/_io.py +27 -0
  38. browserless_bap-0.2.0/src/browserless_bap/_page_generated.py +1322 -0
  39. browserless_bap-0.2.0/src/browserless_bap/_unset.py +12 -0
  40. browserless_bap-0.2.0/src/browserless_bap/_version.py +1 -0
  41. browserless_bap-0.2.0/src/browserless_bap/async_api.py +3 -0
  42. browserless_bap-0.2.0/src/browserless_bap/browser.py +108 -0
  43. browserless_bap-0.2.0/src/browserless_bap/browserless.py +30 -0
  44. browserless_bap-0.2.0/src/browserless_bap/element_handle.py +120 -0
  45. browserless_bap-0.2.0/src/browserless_bap/emitter.py +134 -0
  46. browserless_bap-0.2.0/src/browserless_bap/errors.py +64 -0
  47. browserless_bap-0.2.0/src/browserless_bap/graphql/__init__.py +11 -0
  48. browserless_bap-0.2.0/src/browserless_bap/graphql/builder.py +37 -0
  49. browserless_bap-0.2.0/src/browserless_bap/graphql/mutations.py +417 -0
  50. browserless_bap-0.2.0/src/browserless_bap/graphql/subscriptions.py +47 -0
  51. browserless_bap-0.2.0/src/browserless_bap/mutations.graphql +5560 -0
  52. browserless_bap-0.2.0/src/browserless_bap/page.py +771 -0
  53. browserless_bap-0.2.0/src/browserless_bap/py.typed +1 -0
  54. browserless_bap-0.2.0/src/browserless_bap/sync_api/__init__.py +24 -0
  55. browserless_bap-0.2.0/src/browserless_bap/sync_api/_base.py +32 -0
  56. browserless_bap-0.2.0/src/browserless_bap/sync_api/_bridge.py +419 -0
  57. browserless_bap-0.2.0/src/browserless_bap/sync_api/_page_generated.py +979 -0
  58. browserless_bap-0.2.0/src/browserless_bap/sync_api/browser.py +48 -0
  59. browserless_bap-0.2.0/src/browserless_bap/sync_api/browserless.py +33 -0
  60. browserless_bap-0.2.0/src/browserless_bap/sync_api/element_handle.py +70 -0
  61. browserless_bap-0.2.0/src/browserless_bap/sync_api/page.py +383 -0
  62. browserless_bap-0.2.0/src/browserless_bap/transport.py +522 -0
  63. browserless_bap-0.2.0/src/browserless_bap/types/__init__.py +7 -0
  64. browserless_bap-0.2.0/src/browserless_bap/types/enums.py +717 -0
  65. browserless_bap-0.2.0/src/browserless_bap/types/events.py +121 -0
  66. browserless_bap-0.2.0/src/browserless_bap/types/inputs.py +71 -0
  67. browserless_bap-0.2.0/src/browserless_bap/types/options.py +367 -0
  68. browserless_bap-0.2.0/src/browserless_bap/types/responses.py +314 -0
  69. browserless_bap-0.2.0/tests/e2e/__init__.py +1 -0
  70. browserless_bap-0.2.0/tests/e2e/config.py +61 -0
  71. browserless_bap-0.2.0/tests/e2e/conftest.py +26 -0
  72. browserless_bap-0.2.0/tests/e2e/test_config.py +135 -0
  73. browserless_bap-0.2.0/tests/e2e/test_live.py +166 -0
  74. browserless_bap-0.2.0/tests/sync/__init__.py +1 -0
  75. browserless_bap-0.2.0/tests/sync/_server.py +165 -0
  76. browserless_bap-0.2.0/tests/sync/test_bridge.py +290 -0
  77. browserless_bap-0.2.0/tests/sync/test_parity.py +23 -0
  78. browserless_bap-0.2.0/tests/sync/test_sync_events.py +38 -0
  79. browserless_bap-0.2.0/tests/sync/test_sync_page.py +67 -0
  80. browserless_bap-0.2.0/tests/sync/test_wrappers.py +364 -0
  81. browserless_bap-0.2.0/tests/test_browser.py +118 -0
  82. browserless_bap-0.2.0/tests/test_check_public_text.py +158 -0
  83. browserless_bap-0.2.0/tests/test_codegen_docs.py +112 -0
  84. browserless_bap-0.2.0/tests/test_codegen_drift.py +26 -0
  85. browserless_bap-0.2.0/tests/test_codegen_edge_cases.py +63 -0
  86. browserless_bap-0.2.0/tests/test_codegen_operations.py +120 -0
  87. browserless_bap-0.2.0/tests/test_codegen_parity.py +45 -0
  88. browserless_bap-0.2.0/tests/test_codegen_schema.py +84 -0
  89. browserless_bap-0.2.0/tests/test_emitter.py +146 -0
  90. browserless_bap-0.2.0/tests/test_errors.py +50 -0
  91. browserless_bap-0.2.0/tests/test_graphql_builder.py +33 -0
  92. browserless_bap-0.2.0/tests/test_io.py +44 -0
  93. browserless_bap-0.2.0/tests/test_live_complete.py +418 -0
  94. browserless_bap-0.2.0/tests/test_package.py +23 -0
  95. browserless_bap-0.2.0/tests/test_page_events.py +313 -0
  96. browserless_bap-0.2.0/tests/test_page_overrides.py +301 -0
  97. browserless_bap-0.2.0/tests/test_sync_schema.py +93 -0
  98. browserless_bap-0.2.0/tests/test_transport.py +125 -0
  99. browserless_bap-0.2.0/tests/test_transport_protocol.py +560 -0
@@ -0,0 +1,26 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .coverage
6
+ .mypy_cache/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+
10
+ # Environments and local secrets
11
+ .venv/
12
+ venv/
13
+ .env
14
+ .env.*
15
+
16
+ # Build output
17
+ build/
18
+ dist/
19
+ site/
20
+
21
+ # Editors and operating systems
22
+ .DS_Store
23
+ .idea/
24
+ .vscode/
25
+
26
+ # Generated SDK modules are intentionally committed. Do not ignore src/browserless_bap.
@@ -0,0 +1,69 @@
1
+ # AGENTS.md
2
+
3
+ Guidance for coding agents working in this repository. Humans should start
4
+ with [CONTRIBUTING.md](./CONTRIBUTING.md); SDK users should read
5
+ [README.md](./README.md) and [llms.txt](./llms.txt).
6
+
7
+ ## What this is
8
+
9
+ `browserless-bap` is the Python SDK for Browserless's Browser Automation Protocol. It
10
+ is a GraphQL-over-WebSocket client, not a CDP client. It offers equivalent
11
+ async and sync APIs with Playwright-style Python names.
12
+
13
+ ## Source of truth
14
+
15
+ The vendored schema is `src/browserless_bap/mutations.graphql`. Generated modules and the
16
+ README/llms method lists come from `scripts/codegen.py` and are committed.
17
+ Never hand-edit generated output or content inside AUTOGEN markers.
18
+
19
+ To change generated output:
20
+
21
+ 1. Update the schema with `scripts/sync_schema.py` or change generator inputs.
22
+ 2. Run `python scripts/codegen.py`.
23
+ 3. Run the drift check and commit the inputs and outputs together.
24
+
25
+ `src/browserless_bap/_version.py` is hand-written. Hatch reads the package version from
26
+ that file so installed wheels never need `pyproject.toml`.
27
+
28
+ ## Runtime constraints
29
+
30
+ - Python 3.11 or newer.
31
+ - `websockets` is the only runtime dependency.
32
+ - Keep GraphQL wire dictionaries zero-conversion; generated input/response
33
+ dictionaries retain GraphQL field names.
34
+ - Transport clients must use `max_size=None`, `ping_interval=20`,
35
+ `ping_timeout=None`, `open_timeout=None`, and `close_timeout=5`.
36
+ - Never block the asyncio loop with file I/O.
37
+ - Keep strong references to background tasks until completion.
38
+ - Sync callbacks run on the callback dispatcher, never the bridge loop.
39
+
40
+ ## Commands
41
+
42
+ ```bash
43
+ python -m pip install -e ".[dev]"
44
+ ruff format --check .
45
+ ruff check .
46
+ mypy
47
+ pytest -m "not e2e"
48
+ python scripts/codegen.py
49
+ python scripts/sync_schema.py --check
50
+ ```
51
+
52
+ Live tests are selected with `pytest -m e2e`, need `BROWSERLESS_TOKEN`, and use
53
+ `BROWSERLESS_URL` (default `wss://production-sfo.browserless.io/chromium/bql`).
54
+ Do not put tokens in source, tests, logs, screenshots, or recorded evidence.
55
+
56
+ ## Before opening a PR
57
+
58
+ The offline suite, lint, strict typing, codegen drift check, and wheel smoke
59
+ must pass. Follow the pull request and public repository rules in
60
+ CONTRIBUTING.md. Publishing and deploying are human-owned; never create a
61
+ release, tag, or PyPI upload unless explicitly authorized.
62
+
63
+ ## Public repository rules
64
+
65
+ Never write internal ticket IDs, internal tool links (issue tracker, chat,
66
+ coding-agent threads, support desk), private repository names or customer
67
+ details into PR titles, PR descriptions, commit messages, code comments, test
68
+ names, docs or review replies. CI enforces the title, description and commit
69
+ part. Link from the internal tracker to the PR, never the reverse.
@@ -0,0 +1,118 @@
1
+ # Contributing to browserless-bap
2
+
3
+ ## Setup
4
+
5
+ Create a Python 3.11-or-newer virtual environment and install the editable
6
+ development dependencies:
7
+
8
+ ```bash
9
+ python -m venv .venv
10
+ source .venv/bin/activate
11
+ python -m pip install -e ".[dev]"
12
+ ```
13
+
14
+ ## Development checks
15
+
16
+ Run these before opening a pull request:
17
+
18
+ ```bash
19
+ ruff format --check .
20
+ ruff check .
21
+ mypy
22
+ pytest -m "not e2e"
23
+ python scripts/codegen.py
24
+ git diff --exit-code -- README.md llms.txt src/browserless_bap
25
+ python -m build
26
+ python -m venv /tmp/bap-wheel-smoke
27
+ /tmp/bap-wheel-smoke/bin/python -m pip install dist/*.whl
28
+ /tmp/bap-wheel-smoke/bin/python -c \
29
+ "import browserless_bap, browserless_bap.sync_api; assert not hasattr(browserless_bap, 'schema_source')"
30
+ ! python -m zipfile -l dist/*.whl | grep -q 'mutations.graphql'
31
+ ```
32
+
33
+ ### Live tests
34
+
35
+ The live suite (`pytest -m e2e`) connects to a real Browserless BrowserQL
36
+ endpoint and uses your account. It runs only when selected with `-m e2e` and is
37
+ skipped when `BROWSERLESS_TOKEN` is unset.
38
+ `BROWSERLESS_URL` defaults to `wss://production-sfo.browserless.io/chromium/bql`
39
+ and may be any `ws://` or `wss://` BrowserQL endpoint, for example another
40
+ region or a self-hosted server:
41
+
42
+ ```bash
43
+ BROWSERLESS_TOKEN=your-api-token pytest -m e2e
44
+ BROWSERLESS_URL=wss://production-lon.browserless.io/chromium/bql BROWSERLESS_TOKEN=your-api-token pytest -m e2e
45
+ ```
46
+
47
+ Never commit tokens or paste them into issues, pull requests, logs or
48
+ screenshots.
49
+
50
+ ## Updating the BrowserQL schema
51
+
52
+ The integrity check is self-contained and needs no sibling repository:
53
+
54
+ ```bash
55
+ python scripts/sync_schema.py --check
56
+ ```
57
+
58
+ By default, syncing reads `../bap-ts/src/mutations.graphql` from a sibling
59
+ checkout of the TypeScript SDK:
60
+
61
+ ```bash
62
+ python scripts/sync_schema.py
63
+ ```
64
+
65
+ Contributors without that checkout can pass any schema file with `--schema`,
66
+ for example `src/mutations.graphql` from the published `@browserless.io/bap-ts`
67
+ npm package (version 2.2.0 or later):
68
+
69
+ ```bash
70
+ python scripts/sync_schema.py --from-bap-ts
71
+ python scripts/sync_schema.py --schema /path/to/mutations.graphql
72
+ ```
73
+
74
+ Schema and codegen changes must include `schema.lock` and all regenerated
75
+ files. Generated files and AUTOGEN regions must not be edited manually.
76
+
77
+ ## API reference
78
+
79
+ The generated Python API reference is published at
80
+ <https://docs.browserless.io/bap/python/reference>. Maintainers regenerate it
81
+ with `python scripts/docs.py --output <directory>`, which writes Docusaurus
82
+ `.mdx` files, and publish the output to the documentation site.
83
+
84
+ ## Pull requests
85
+
86
+ - Branch from `main` and keep changes focused.
87
+ - Use Conventional Commits-compatible titles and reference related GitHub
88
+ issues (for example `Closes #123`).
89
+ - Include tests for behavior changes.
90
+ - Do not publish packages or create release tags from a pull request branch.
91
+
92
+ ## Public repository rules
93
+
94
+ PR titles, descriptions, commit messages and review comments must not contain
95
+ internal ticket IDs (text like `ABC-123`), links to internal tools (issue
96
+ tracker, chat, coding-agent or support-desk links), private repository names,
97
+ or customer details. PR titles matter most: they become squash-commit subjects
98
+ and changelog entries.
99
+
100
+ CI (`Public PR rules`) rejects titles, descriptions and commit messages that
101
+ match these patterns; harmless technical identifiers such as `UTF-8`,
102
+ `SHA-256` and `CVE-2025-1234` are allowed. Maintainers link from the internal
103
+ tracker to the public PR, never the reverse.
104
+
105
+ PR titles also follow [Conventional Commits](https://www.conventionalcommits.org/):
106
+ `type: summary` or `type(scope): summary`, with type one of `feat`, `fix`,
107
+ `perf`, `revert`, `build`, `chore`, `ci`, `docs`, `style`, `refactor` or
108
+ `test`. The `PR title` check enforces this.
109
+
110
+ ## Reporting security issues
111
+
112
+ Please report vulnerabilities privately as described in
113
+ [SECURITY.md](./SECURITY.md).
114
+
115
+ ## Code of conduct
116
+
117
+ Everyone taking part in this project is expected to follow the
118
+ [Code of Conduct](./CODE_OF_CONDUCT.md).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 browserless.io
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,264 @@
1
+ Metadata-Version: 2.5
2
+ Name: browserless-bap
3
+ Version: 0.2.0
4
+ Summary: Python async and sync client for Browserless's Browser Automation Protocol
5
+ Project-URL: Homepage, https://github.com/browserless/bap-py
6
+ Project-URL: Documentation, https://docs.browserless.io/bap/python/reference
7
+ Project-URL: Source, https://github.com/browserless/bap-py
8
+ Project-URL: Changelog, https://github.com/browserless/bap-py/releases
9
+ Project-URL: Issues, https://github.com/browserless/bap-py/issues
10
+ Author-email: Browserless <eng@browserless.io>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: browser-automation,browserless,browserql,playwright
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.11
23
+ Requires-Dist: websockets>=14.0
24
+ Provides-Extra: dev
25
+ Requires-Dist: build>=1.2; extra == 'dev'
26
+ Requires-Dist: graphql-core>=3.2; extra == 'dev'
27
+ Requires-Dist: griffe>=1.0; extra == 'dev'
28
+ Requires-Dist: mypy>=1.14; extra == 'dev'
29
+ Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
30
+ Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
31
+ Requires-Dist: pytest>=8.3; extra == 'dev'
32
+ Requires-Dist: ruff>=0.9; extra == 'dev'
33
+ Requires-Dist: twine>=6.0; extra == 'dev'
34
+ Description-Content-Type: text/markdown
35
+
36
+ # browserless-bap
37
+
38
+ The Python client for Browserless's Browser Automation Protocol (BAP).
39
+ `browserless-bap` provides Playwright-style async and sync APIs over Browserless's
40
+ GraphQL-over-WebSocket transport.
41
+
42
+ ## Requirements
43
+
44
+ - Python 3.11 or newer
45
+ - A Browserless API token for live use
46
+
47
+ ## Install
48
+
49
+ ```bash
50
+ pip install browserless-bap
51
+ ```
52
+
53
+ ## Quick start
54
+
55
+ ```python
56
+ import asyncio
57
+
58
+ import browserless_bap as bap
59
+
60
+
61
+ async def run() -> None:
62
+ async with bap.Browserless.connect(
63
+ browser_ws_endpoint="wss://production-sfo.browserless.io/chromium/bql",
64
+ token="your-api-token",
65
+ ) as browser:
66
+ async with browser.page() as page:
67
+ await page.goto("https://example.com")
68
+ print(await page.title())
69
+
70
+
71
+ asyncio.run(run())
72
+ ```
73
+
74
+ The same script with the sync API, from `browserless_bap.sync_api`:
75
+
76
+ ```python
77
+ import browserless_bap.sync_api as bap
78
+
79
+ with bap.Browserless.connect(
80
+ browser_ws_endpoint="wss://production-sfo.browserless.io/chromium/bql",
81
+ token="your-api-token",
82
+ ) as browser:
83
+ with browser.page() as page:
84
+ page.goto("https://example.com")
85
+ print(page.title())
86
+ ```
87
+
88
+ > [!TIP]
89
+ > Jupyter notebooks already run an asyncio event loop, so use the async API
90
+ > there and replace `asyncio.run(run())` with `await run()`. The sync API
91
+ > raises `RuntimeError` inside a running event loop.
92
+
93
+ ## API methods
94
+
95
+ This table is generated from the vendored GraphQL schema. Do not edit the
96
+ contents between the markers by hand.
97
+
98
+ <!-- AUTOGEN:method-table START -->
99
+
100
+ | Method | Source mutation | Returns | Playwright-named |
101
+ | ------ | --------------- | ------- | ---------------- |
102
+ | `add_cookies` | `cookies` | `CookieResponse` | ✅ |
103
+ | `add_script_tag` | `addScriptTag` | `AddScriptTagResponse` | ✅ |
104
+ | `add_style_tag` | `addStyleTag` | `AddStyleTagResponse` | ✅ |
105
+ | `authenticate` | `authenticate` | `HTTPResponse \| None` | — |
106
+ | `check` | `checkbox` | `ClickResponse` | — |
107
+ | `click` | `click` | `ClickResponse` | ✅ |
108
+ | `close` | `—` | `None` | ✅ |
109
+ | `close_live_url` | `closeLiveURL` | `CloseLiveURLResponse` | — |
110
+ | `content` | `html` | `str` | ✅ |
111
+ | `cookies` | `cookies` | `list[StandardCookie]` | ✅ |
112
+ | `emulate_media` | `emulateMediaType` | `EmulateMediaTypeResponse` | ✅ |
113
+ | `eval_on_selector` | `text` | `str` | ✅ |
114
+ | `eval_on_selector_all` | `mapSelector` | `list[MapSelectorResponse]` | ✅ |
115
+ | `evaluate` | `evaluate` | `str \| None` | ✅ |
116
+ | `fulfill` | `fulfill` | `FulfillResponse` | — |
117
+ | `go_back` | `back` | `HTTPResponse \| None` | ✅ |
118
+ | `go_forward` | `forward` | `HTTPResponse \| None` | ✅ |
119
+ | `goto` | `goto` | `HTTPResponse \| None` | ✅ |
120
+ | `hover` | `hover` | `HoverResponse` | ✅ |
121
+ | `html` | `html` | `HTMLResponse` | — |
122
+ | `live_url` | `liveURL` | `LiveURLResponse` | — |
123
+ | `load_secret` | `loadSecret` | `LoadSecretResponse` | — |
124
+ | `map_selector` | `mapSelector` | `list[MapSelectorResponse]` | — |
125
+ | `markdown` | `markdown` | `MarkdownResponse` | — |
126
+ | `pdf` | `pdf` | `bytes` | ✅ |
127
+ | `preferences` | `preferences` | `DefaultResponse` | — |
128
+ | `proxy` | `proxy` | `ProxyResponse` | — |
129
+ | `query_selector` | `querySelector` | `ElementHandle \| None` | ✅ |
130
+ | `query_selector_all` | `querySelectorAll` | `list[ElementHandle]` | ✅ |
131
+ | `reconnect` | `reconnect` | `ReconnectionResponse` | — |
132
+ | `reject` | `reject` | `RejectResponse` | — |
133
+ | `reload` | `reload` | `HTTPResponse \| None` | ✅ |
134
+ | `request` | `request` | `list[RequestResponse]` | — |
135
+ | `response` | `response` | `list[ResponseResponse]` | — |
136
+ | `screenshot` | `screenshot` | `bytes` | ✅ |
137
+ | `scroll` | `scroll` | `ScrollResponse` | — |
138
+ | `select_option` | `select` | `SelectResponse` | ✅ |
139
+ | `send` | `—` | `T` | — |
140
+ | `set_content` | `content` | `HTTPResponse \| None` | ✅ |
141
+ | `set_extra_http_headers` | `setExtraHTTPHeaders` | `HTTPHeadersResponse` | ✅ |
142
+ | `set_java_script_enabled` | `javaScriptEnabled` | `JavaScriptResponse` | — |
143
+ | `set_user_agent` | `userAgent` | `UserAgentResponse` | ✅ |
144
+ | `set_viewport_size` | `viewport` | `ViewportResponse` | ✅ |
145
+ | `solve` | `solve` | `CaptchaResponse` | — |
146
+ | `solve_image_captcha` | `solveImageCaptcha` | `CaptchaResponse` | — |
147
+ | `stop_session_recording` | `stopSessionRecording` | `StopSessionRecordingResponse` | — |
148
+ | `switch_to_window` | `switchToWindow` | `SwitchWindowResponse` | — |
149
+ | `text` | `text` | `TextResponse` | — |
150
+ | `title` | `title` | `str` | ✅ |
151
+ | `type` | `type` | `TypeResponse` | ✅ |
152
+ | `uncheck` | `checkbox` | `ClickResponse` | — |
153
+ | `url` | `url` | `str` | ✅ |
154
+ | `wait_for_event` | `waitForEvent` | `WaitForEvent` | — |
155
+ | `wait_for_function` | `waitForFunction` | `WaitForFunction` | ✅ |
156
+ | `wait_for_live_complete` | `liveComplete` | `LiveURLCompleteEvent` | — |
157
+ | `wait_for_navigation` | `waitForNavigation` | `HTTPResponse` | ✅ |
158
+ | `wait_for_network_idle` | `waitForNetworkIdle` | `WaitForTimeoutResponse` | — |
159
+ | `wait_for_request` | `waitForRequest` | `WaitForRequestResponse` | ✅ |
160
+ | `wait_for_response` | `waitForResponse` | `WaitForResponseResponse` | ✅ |
161
+ | `wait_for_selector` | `waitForSelector` | `WaitForSelectorResponse` | ✅ |
162
+ | `wait_for_timeout` | `waitForTimeout` | `None` | ✅ |
163
+ | `watch_event` | `watchEvent` | `WaitForEvent` | — |
164
+
165
+ <!-- AUTOGEN:method-table END -->
166
+
167
+ ## Schema and generated code
168
+
169
+ `src/browserless_bap/mutations.graphql` is the vendored GraphQL schema. Its full digest,
170
+ line count, and source provenance are committed in `schema.lock`. Verify the
171
+ vendored schema without requiring any sibling checkout:
172
+
173
+ ```bash
174
+ python scripts/sync_schema.py --check
175
+ ```
176
+
177
+ By default, syncing reads the schema from a sibling checkout of the TypeScript
178
+ SDK (`../bap-ts/src/mutations.graphql`). Any schema file can be selected with
179
+ `--schema`, for example `src/mutations.graphql` from the `@browserless.io/bap-ts`
180
+ npm package:
181
+
182
+ ```bash
183
+ python scripts/sync_schema.py --from-bap-ts
184
+ python scripts/sync_schema.py --schema /path/to/mutations.graphql
185
+ ```
186
+
187
+ Generated Python modules are committed to git. Update the schema or generator,
188
+ run `python scripts/codegen.py`, and commit the inputs and generated outputs
189
+ together.
190
+
191
+ ## Development
192
+
193
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, testing, and contribution
194
+ instructions.
195
+
196
+ ## Wait for a Live URL handoff
197
+
198
+ ```python
199
+ link = await page.live_url(instructions="Sign in, then click Done.", timeout=120_000)
200
+ print(link["liveURL"])
201
+ completion = await page.wait_for_live_complete(timeout=120_000)
202
+ if completion["reason"] != "userDone":
203
+ raise RuntimeError(f"Handoff ended: {completion['reason']}")
204
+ # To cancel a link instead: await page.close_live_url(link["liveURLId"])
205
+ ```
206
+
207
+ The sync facade uses the same calls without `await`.
208
+
209
+ For a richer human handoff, pass an instructions card:
210
+
211
+ ```python
212
+ link = await page.live_url(
213
+ instructions={
214
+ "layout": "panel",
215
+ "format": "markdown",
216
+ "title": "Complete sign in",
217
+ "summary": "**Sign in** to continue.",
218
+ "steps": ["Open your inbox", "Enter the code"],
219
+ "currentStep": 2,
220
+ },
221
+ done_label="Continue",
222
+ fail_label="Need help",
223
+ requester_name="Support",
224
+ )
225
+ ```
226
+
227
+ With string instructions, use the top-level `instructions_title`, `steps`,
228
+ `current_step` and `instructions_format`. With a card, put `title`, `steps`,
229
+ `currentStep` and `format` inside it. Button labels and `requester_name` always
230
+ stay top-level. The server validates card limits. For an explicitly annotated
231
+ card, import `LiveURLInstructions` from `browserless_bap.types`.
232
+
233
+ The SDK subscribes before minting and retains completion until the next mint,
234
+ so a quick completion is not lost between `live_url()` and `wait_for_live_complete()`.
235
+ Wait timeouts are in milliseconds and raise the SDK `TimeoutError`. By default
236
+ there is no client wait deadline; pass a positive timeout to bound the wait.
237
+ `timeout=0` also disables the wait deadline. Timing out or cancelling a wait does
238
+ not close the live URL.
239
+
240
+ Completion reasons are `userDone`, `userFailed`, `timeout`, `closed`, and
241
+ `viewerDisconnected`. Only `userDone` explicitly means the person finished.
242
+ Use `close_live_url(id)` to end a link programmatically;
243
+ the response contains `liveURLId`. Await each mint before starting another one.
244
+ A re-mint starts a new wait even when the server reuses its ID; existing waits
245
+ remain associated with the preceding handoff. Closing the page or losing the
246
+ connection rejects pending waits. The completion subscription closes when no pending handoffs or public listeners
247
+ remain; cached results remain available. Public listeners use `on`/`off`.
248
+ For reused IDs, the server emits the preceding handoff’s completion before the
249
+ replacement’s completion on the same ordered subscription stream.
250
+
251
+ Live URL handoffs need a Browserless server that supports
252
+ `wait_for_live_complete()` (the `liveComplete` event), `close_live_url()` and
253
+ instruction cards. When a live URL call passes `instructions`, this client sends
254
+ them in the newer format, which older servers reject even for a plain string.
255
+ Older clients send a format that newer servers reject. Upgrading is
256
+ therefore a coordinated client/server cutover, not a rolling server-first
257
+ upgrade.
258
+
259
+ For self-hosted upgrades, pause new handoffs and drain active ones, upgrade the
260
+ server and all clients together, then verify mint, completion, and close before
261
+ resuming handoffs. Handoffs remain unavailable during this cutover. To roll back,
262
+ pause and drain again and restore both the previous server and previous clients;
263
+ rolling back only one side leaves an incompatible pair. No mixed-version
264
+ compatibility path is provided by this SDK.