barebrowse 0.19.2 → 0.20.0
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.
- package/CHANGELOG.md +39 -0
- package/barebrowse.context.md +2 -0
- package/package.json +1 -1
- package/src/firefox-page.js +5 -3
- package/src/index.js +41 -6
- package/types/firefox-page.d.ts +72 -2
- package/types/index.d.ts +147 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,44 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [Unreleased]
|
|
4
|
+
|
|
5
|
+
## [0.20.0] - 2026-08-30
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **Publish workflow gates on the types being usable BY AN ADOPTER, not just internally.** `npm run typecheck` (`tsc --noEmit`) checks the *source*; it cannot see the generated `.d.ts` as an adopter resolves it from inside `node_modules`, which is the one thing consumers actually get. The publish workflow now packs the tarball, installs it into a clean consumer project, and compiles a quickstart against it, so a release whose published types are broken cannot reach the registry. The consumer pins `@types/node` to the major this package builds against instead of floating to the newest, so a stricter DefinitelyTyped release cannot turn the publish gate red for reasons unrelated to the commit being published. Verified locally: the quickstart compiles green against a packed tarball, and a deliberately broken dereference fails it. CI only — no runtime or published-artifact change.
|
|
10
|
+
|
|
11
|
+
### Fixed
|
|
12
|
+
|
|
13
|
+
- **`connect()` now returns a typed page handle instead of bare `object`.** Its
|
|
14
|
+
JSDoc `@returns` was `Promise<object>`, so a TypeScript adopter could not
|
|
15
|
+
dereference `page.goto` / `page.snapshot` / `page.click` / `page.close` off the
|
|
16
|
+
returned handle without casting — the whole interactive surface was unusable
|
|
17
|
+
from types. The return is now inferred structurally from the returned object
|
|
18
|
+
literals and re-exported as a named `Page` type (`import type { Page } from
|
|
19
|
+
'barebrowse'`), so there is no hand-maintained interface to drift. `Page` is a
|
|
20
|
+
union of the two engine shapes (Chromium/CDP and Firefox/BiDi): every shared
|
|
21
|
+
interaction method dereferences without narrowing, while an engine-specific
|
|
22
|
+
escape hatch (`cdp` on Chromium, `bidi` on Firefox) is exposed by narrowing
|
|
23
|
+
(`if ('cdp' in page) …`) — the union is sound where an intersection would falsely
|
|
24
|
+
claim a page carries both engines' hatches. The commonly-omitted option
|
|
25
|
+
parameters on `snapshot()`, `type()`, and `injectCookies()` are now typed
|
|
26
|
+
optional (they always were at runtime), so `page.snapshot()` and
|
|
27
|
+
`page.type(ref, text)` compile — and carry named, member-checked shapes
|
|
28
|
+
(`SnapshotOptions`, `TypeOptions`, `CookieOptions`, all exported), so a typo
|
|
29
|
+
like `snapshot({ mdoe: 'read' })` is now a compile error instead of a silent
|
|
30
|
+
no-op. `browse()` → `Promise<string>` is unchanged.
|
|
31
|
+
Validated by packing the tarball and compiling a strict (`nodenext`,
|
|
32
|
+
`skipLibCheck:false`) consumer quickstart that dereferences the real page
|
|
33
|
+
methods — green after, red before. The publish adopter gate missed this because
|
|
34
|
+
its quickstart only exercises `browse()`'s snapshot string, never the
|
|
35
|
+
`connect()` handle.
|
|
36
|
+
- **Publish workflow pinned to `npm@11` — npm 12.0.0's `npm publish --provenance` is broken.** The job ran `npm install -g npm@latest`, which started resolving to npm 12.0.0 (released 2026-07-09) on the Node 22 runner. npm 12's `libnpmpublish` provenance code does `require('sigstore')`, but the tarball bundles only the `@sigstore/*` scoped packages — so `--provenance` dies with `MODULE_NOT_FOUND` and the publish fails outright. npm@11 bundles `sigstore` and publishes fine. Pinned to the major rather than floating on `@latest`. Revisit once npm ships a provenance fix. CI only — no runtime or published-artifact change.
|
|
37
|
+
|
|
38
|
+
### Changed
|
|
39
|
+
|
|
40
|
+
- **Agent/IDE scratch is gitignored and de-tracked (`.claude/`, `.litectx/`, `.idea/`).** Per-machine agent and IDE state is no part of the package — it regenerates locally and only added noise and churn. Now ignored, and any already-committed copies removed from tracking (local files kept on disk). Functional dot-paths (`.github/`, `.gitignore`, `.npmignore`, `.mcp.json`) stay tracked. Repo hygiene only.
|
|
41
|
+
|
|
3
42
|
## [0.19.2] - 2026-07-11
|
|
4
43
|
|
|
5
44
|
### Fixed
|
package/barebrowse.context.md
CHANGED
|
@@ -61,6 +61,8 @@ const snapshot = await browse('https://example.com', {
|
|
|
61
61
|
|
|
62
62
|
`connect(opts)` returns a page handle for interactive sessions. Same opts as `browse()` for mode. Supports `hybrid` mode — starts headless, auto-launches headed on bot detection (same as `browse()`).
|
|
63
63
|
|
|
64
|
+
**TypeScript:** the handle is the exported `Page` type — `import type { Page } from 'barebrowse'`. It's a union of the Chromium and Firefox page shapes: every method in the table below is available directly, while an engine-specific escape hatch (`cdp` on Chromium, `bidi` on Firefox) is reached by narrowing, e.g. `if ('cdp' in page) page.cdp.send(...)`.
|
|
65
|
+
|
|
64
66
|
| Method | Args | Returns | Notes |
|
|
65
67
|
|---|---|---|---|
|
|
66
68
|
| `goto(url, timeout?)` | url: string, timeout: number (default 30000) | void | Navigate + wait for load + dismiss consent |
|
package/package.json
CHANGED
package/src/firefox-page.js
CHANGED
|
@@ -46,7 +46,6 @@ const BIDI_KEYS = {
|
|
|
46
46
|
* @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
|
|
47
47
|
* @param {boolean} [opts.headed=false] - Whether the browser was launched headed (skips hybrid fallback).
|
|
48
48
|
* @param {?function(): Promise<{bidi: object, topContext: string}>} [opts.relaunchHeaded] - Hybrid relaunch hook (from connectFirefox).
|
|
49
|
-
* @returns {Promise<object>} page object
|
|
50
49
|
*/
|
|
51
50
|
export async function createFirefoxPage(bidi, opts = {}) {
|
|
52
51
|
const defaultPruneMode = opts.pruneMode || 'act';
|
|
@@ -326,7 +325,8 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
326
325
|
}
|
|
327
326
|
},
|
|
328
327
|
|
|
329
|
-
|
|
328
|
+
/** @param {import('./index.js').SnapshotOptions|false} [pruneOpts] */
|
|
329
|
+
async snapshot(pruneOpts = {}) {
|
|
330
330
|
const root = await buildTree();
|
|
331
331
|
if (!root) return '';
|
|
332
332
|
|
|
@@ -349,6 +349,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
349
349
|
|
|
350
350
|
async click(ref) { await pointerClick(ref); },
|
|
351
351
|
|
|
352
|
+
/** @param {string} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
|
|
352
353
|
async type(ref, text, typeOpts = {}) {
|
|
353
354
|
const { context, sharedId } = await resolveRef(ref);
|
|
354
355
|
// Focus the field (and optionally clear it) in-page, then send real key
|
|
@@ -391,7 +392,8 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
391
392
|
* via BiDi storage.setCookie. Scoped to the URL host via the SHARED
|
|
392
393
|
* scopedCookiesForUrl (same as the CDP path) — never the whole jar.
|
|
393
394
|
*/
|
|
394
|
-
|
|
395
|
+
/** @param {string} url @param {import('./index.js').CookieOptions} [cookieOpts] */
|
|
396
|
+
async injectCookies(url, cookieOpts = {}) {
|
|
395
397
|
if (incognito) return 0;
|
|
396
398
|
lastInject = { url, cookieOpts }; // remember for a hybrid re-inject
|
|
397
399
|
const cookies = scopedCookiesForUrl(url, { browser: cookieOpts?.browser });
|
package/src/index.js
CHANGED
|
@@ -162,6 +162,35 @@ export async function browse(url, opts = {}) {
|
|
|
162
162
|
}
|
|
163
163
|
}
|
|
164
164
|
|
|
165
|
+
/**
|
|
166
|
+
* The interactive page handle returned by {@link connect}. Inferred structurally
|
|
167
|
+
* from the returned object literals — no hand-maintained interface to drift.
|
|
168
|
+
*
|
|
169
|
+
* It is a union of the two engine page shapes (Chromium/CDP and Firefox/BiDi),
|
|
170
|
+
* which share every interaction method (`goto`, `snapshot`, `click`, `type`,
|
|
171
|
+
* `close`, …) but differ in their escape hatches — `cdp`/`createTab`/`dialogLog`
|
|
172
|
+
* on Chromium, `bidi`/`context` on Firefox. The shared methods dereference
|
|
173
|
+
* without narrowing; an engine-specific hatch requires knowing the engine
|
|
174
|
+
* (the default is Chromium), e.g. `if ('cdp' in page) page.cdp.send(...)`.
|
|
175
|
+
* @typedef {Awaited<ReturnType<typeof connect>>} Page
|
|
176
|
+
*/
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* Options for `page.snapshot()`. Pass `false` instead of an object to skip
|
|
180
|
+
* pruning and return the raw ARIA tree.
|
|
181
|
+
* @typedef {{ mode?: 'act'|'browse'|'navigate'|'full'|'read' }} SnapshotOptions
|
|
182
|
+
*/
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Options for `page.type()`.
|
|
186
|
+
* @typedef {{ clear?: boolean, keyEvents?: boolean }} TypeOptions
|
|
187
|
+
*/
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* Options for `page.injectCookies()`.
|
|
191
|
+
* @typedef {{ browser?: string }} CookieOptions
|
|
192
|
+
*/
|
|
193
|
+
|
|
165
194
|
/**
|
|
166
195
|
* Connect to a browser for a long-lived interactive session.
|
|
167
196
|
*
|
|
@@ -206,7 +235,10 @@ export async function browse(url, opts = {}) {
|
|
|
206
235
|
* @param {'chromium'|'firefox'} [opts.engine='chromium'] - Browser engine.
|
|
207
236
|
* 'firefox' drives over WebDriver BiDi (a separate transport / page object);
|
|
208
237
|
* 'chromium' (default) uses CDP.
|
|
209
|
-
* @returns
|
|
238
|
+
* @returns The interactive page handle — see the exported `Page` typedef. The
|
|
239
|
+
* return type is left uninferred here (no `{...}` tag) so tsc derives it
|
|
240
|
+
* structurally from the returned object literals; annotating it as `Page`
|
|
241
|
+
* would be a self-reference, since `Page` is `ReturnType<typeof connect>`.
|
|
210
242
|
*/
|
|
211
243
|
export async function connect(opts = {}) {
|
|
212
244
|
// Firefox is driven over WebDriver BiDi (CDP is deprecated there) — a
|
|
@@ -452,14 +484,16 @@ export async function connect(opts = {}) {
|
|
|
452
484
|
refMap = new Map(); // refs from the pre-reload page are invalid
|
|
453
485
|
},
|
|
454
486
|
|
|
455
|
-
|
|
487
|
+
/** @param {string} url @param {CookieOptions} [cookieOpts] */
|
|
488
|
+
async injectCookies(url, cookieOpts = {}) {
|
|
456
489
|
// No-op under incognito: callers (MCP goto, daemon) inject unconditionally,
|
|
457
490
|
// so the gate has to live here, not just at the call site.
|
|
458
491
|
if (incognito) return 0;
|
|
459
492
|
return authenticate(page.session, url, { browser: cookieOpts?.browser });
|
|
460
493
|
},
|
|
461
494
|
|
|
462
|
-
|
|
495
|
+
/** @param {SnapshotOptions|false} [pruneOpts] */
|
|
496
|
+
async snapshot(pruneOpts = {}) {
|
|
463
497
|
const result = await ariaTree(page);
|
|
464
498
|
refMap = result.refMap;
|
|
465
499
|
const raw = formatTree(result.tree);
|
|
@@ -490,7 +524,8 @@ export async function connect(opts = {}) {
|
|
|
490
524
|
await cdpClick(entry.session, entry.backendNodeId);
|
|
491
525
|
},
|
|
492
526
|
|
|
493
|
-
|
|
527
|
+
/** @param {string} ref @param {string} text @param {TypeOptions} [typeOpts] */
|
|
528
|
+
async type(ref, text, typeOpts = {}) {
|
|
494
529
|
const entry = refMap.get(ref);
|
|
495
530
|
if (!entry) throw new Error(`No element found for ref "${ref}"`);
|
|
496
531
|
await cdpType(entry.session, entry.backendNodeId, text, typeOpts);
|
|
@@ -671,7 +706,8 @@ export async function connect(opts = {}) {
|
|
|
671
706
|
tabBotBlocked = isChallengePage(tree, nodeCount);
|
|
672
707
|
},
|
|
673
708
|
get botBlocked() { return tabBotBlocked; },
|
|
674
|
-
|
|
709
|
+
/** @param {string} url @param {CookieOptions} [cookieOpts] */
|
|
710
|
+
async injectCookies(url, cookieOpts = {}) {
|
|
675
711
|
if (incognito) return 0;
|
|
676
712
|
return authenticate(tab.session, url, { browser: cookieOpts?.browser });
|
|
677
713
|
},
|
|
@@ -743,7 +779,6 @@ async function suppressPermissions(cdp) {
|
|
|
743
779
|
* The navigation guard (`allowLocalUrls`/`blockPrivateNetwork`), `uploadDir`
|
|
744
780
|
* sandbox, `incognito`, `proxy`, `viewport`, and `pruneMode` all apply.
|
|
745
781
|
* @param {object} opts - connect() options ({ mode, proxy, binary, viewport, pruneMode, urlGuard, uploadDir, incognito, downloadPath, blockAds, blockUrls })
|
|
746
|
-
* @returns {Promise<object>} Firefox page object
|
|
747
782
|
*/
|
|
748
783
|
async function connectFirefox(opts) {
|
|
749
784
|
const hybrid = opts.mode === 'hybrid';
|
package/types/firefox-page.d.ts
CHANGED
|
@@ -10,7 +10,6 @@
|
|
|
10
10
|
* @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
|
|
11
11
|
* @param {boolean} [opts.headed=false] - Whether the browser was launched headed (skips hybrid fallback).
|
|
12
12
|
* @param {?function(): Promise<{bidi: object, topContext: string}>} [opts.relaunchHeaded] - Hybrid relaunch hook (from connectFirefox).
|
|
13
|
-
* @returns {Promise<object>} page object
|
|
14
13
|
*/
|
|
15
14
|
export function createFirefoxPage(bidi: object, opts?: {
|
|
16
15
|
pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
|
|
@@ -27,4 +26,75 @@ export function createFirefoxPage(bidi: object, opts?: {
|
|
|
27
26
|
bidi: object;
|
|
28
27
|
topContext: string;
|
|
29
28
|
}>) | null | undefined;
|
|
30
|
-
}): Promise<
|
|
29
|
+
}): Promise<{
|
|
30
|
+
/** The BiDi escape hatch, analogous to connect()'s page.cdp. */
|
|
31
|
+
readonly bidi: any;
|
|
32
|
+
/** The active browsing-context id (getter so it tracks switchTab). */
|
|
33
|
+
readonly context: any;
|
|
34
|
+
/** Whether the last goto() landed on a bot-challenge page (parity w/ CDP). */
|
|
35
|
+
readonly botBlocked: boolean;
|
|
36
|
+
goto(url: any, timeout?: number): Promise<void>;
|
|
37
|
+
/** @param {import('./index.js').SnapshotOptions|false} [pruneOpts] */
|
|
38
|
+
snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
|
|
39
|
+
readable(): Promise<any>;
|
|
40
|
+
click(ref: any): Promise<void>;
|
|
41
|
+
/** @param {string} ref @param {string} text @param {import('./index.js').TypeOptions} [typeOpts] */
|
|
42
|
+
type(ref: string, text: string, typeOpts?: import("./index.js").TypeOptions): Promise<void>;
|
|
43
|
+
press(key: any): Promise<void>;
|
|
44
|
+
scroll(deltaY: any): Promise<void>;
|
|
45
|
+
hover(ref: any): Promise<void>;
|
|
46
|
+
/**
|
|
47
|
+
* Inject cookies from the user's real browser into this Firefox session,
|
|
48
|
+
* via BiDi storage.setCookie. Scoped to the URL host via the SHARED
|
|
49
|
+
* scopedCookiesForUrl (same as the CDP path) — never the whole jar.
|
|
50
|
+
*/
|
|
51
|
+
/** @param {string} url @param {import('./index.js').CookieOptions} [cookieOpts] */
|
|
52
|
+
injectCookies(url: string, cookieOpts?: import("./index.js").CookieOptions): Promise<number>;
|
|
53
|
+
select(ref: any, value: any): Promise<void>;
|
|
54
|
+
drag(fromRef: any, toRef: any): Promise<void>;
|
|
55
|
+
upload(ref: any, files: any): Promise<void>;
|
|
56
|
+
goBack(): Promise<void>;
|
|
57
|
+
goForward(): Promise<void>;
|
|
58
|
+
reload(): Promise<void>;
|
|
59
|
+
screenshot(screenshotOpts?: {}): Promise<any>;
|
|
60
|
+
pdf(pdfOpts?: {}): Promise<any>;
|
|
61
|
+
tabs(): Promise<{
|
|
62
|
+
index: number;
|
|
63
|
+
url: any;
|
|
64
|
+
title: any;
|
|
65
|
+
context: any;
|
|
66
|
+
}[]>;
|
|
67
|
+
switchTab(index: any): Promise<void>;
|
|
68
|
+
waitFor(waitOpts?: {}): Promise<void>;
|
|
69
|
+
/**
|
|
70
|
+
* Wait until the network has been idle for `idle` ms, over BiDi
|
|
71
|
+
* network.* events. Parity with the CDP page.waitForNetworkIdle (Phase 2).
|
|
72
|
+
*/
|
|
73
|
+
waitForNetworkIdle(idleOpts?: {}): Promise<void>;
|
|
74
|
+
/** Downloads that began in this session (Phase 4 — see setupDownloads). */
|
|
75
|
+
readonly downloads: any[];
|
|
76
|
+
dialogLog: any[];
|
|
77
|
+
/**
|
|
78
|
+
* Install a custom JS dialog handler, mirroring connect()'s page.onDialog.
|
|
79
|
+
* Called with `{ type, message, defaultPrompt }`; may return (sync or async)
|
|
80
|
+
* `{ accept: bool, promptText: string }` to override the auto-accept
|
|
81
|
+
* default. Pass null to restore default behavior.
|
|
82
|
+
*/
|
|
83
|
+
onDialog(handler: any): void;
|
|
84
|
+
/**
|
|
85
|
+
* Persist cookies + localStorage to a JSON file (parity with the CDP
|
|
86
|
+
* saveState). Cookies come from BiDi storage.getCookies (whose value is a
|
|
87
|
+
* `{type,value}` object) and are flattened to the CDP-symmetric shape so the
|
|
88
|
+
* file format matches across engines. Written 0600 — it holds session
|
|
89
|
+
* tokens, so a multi-user host must not be able to read another user's.
|
|
90
|
+
*/
|
|
91
|
+
saveState(filePath: any): Promise<void>;
|
|
92
|
+
/**
|
|
93
|
+
* Resolve when the active tab fires its next load event (parity with the
|
|
94
|
+
* CDP waitForNavigation → Page.loadEventFired). Scoped to topContext so a
|
|
95
|
+
* subframe load can't resolve it early. Falls back to a short settle delay
|
|
96
|
+
* for SPA navigations that fire no load event.
|
|
97
|
+
*/
|
|
98
|
+
waitForNavigation(timeout?: number): Promise<void>;
|
|
99
|
+
close(): Promise<void>;
|
|
100
|
+
}>;
|
package/types/index.d.ts
CHANGED
|
@@ -49,6 +49,31 @@ export function browse(url: string, opts?: {
|
|
|
49
49
|
consent?: boolean | undefined;
|
|
50
50
|
pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
|
|
51
51
|
}): Promise<string>;
|
|
52
|
+
/**
|
|
53
|
+
* The interactive page handle returned by {@link connect}. Inferred structurally
|
|
54
|
+
* from the returned object literals — no hand-maintained interface to drift.
|
|
55
|
+
*
|
|
56
|
+
* It is a union of the two engine page shapes (Chromium/CDP and Firefox/BiDi),
|
|
57
|
+
* which share every interaction method (`goto`, `snapshot`, `click`, `type`,
|
|
58
|
+
* `close`, …) but differ in their escape hatches — `cdp`/`createTab`/`dialogLog`
|
|
59
|
+
* on Chromium, `bidi`/`context` on Firefox. The shared methods dereference
|
|
60
|
+
* without narrowing; an engine-specific hatch requires knowing the engine
|
|
61
|
+
* (the default is Chromium), e.g. `if ('cdp' in page) page.cdp.send(...)`.
|
|
62
|
+
* @typedef {Awaited<ReturnType<typeof connect>>} Page
|
|
63
|
+
*/
|
|
64
|
+
/**
|
|
65
|
+
* Options for `page.snapshot()`. Pass `false` instead of an object to skip
|
|
66
|
+
* pruning and return the raw ARIA tree.
|
|
67
|
+
* @typedef {{ mode?: 'act'|'browse'|'navigate'|'full'|'read' }} SnapshotOptions
|
|
68
|
+
*/
|
|
69
|
+
/**
|
|
70
|
+
* Options for `page.type()`.
|
|
71
|
+
* @typedef {{ clear?: boolean, keyEvents?: boolean }} TypeOptions
|
|
72
|
+
*/
|
|
73
|
+
/**
|
|
74
|
+
* Options for `page.injectCookies()`.
|
|
75
|
+
* @typedef {{ browser?: string }} CookieOptions
|
|
76
|
+
*/
|
|
52
77
|
/**
|
|
53
78
|
* Connect to a browser for a long-lived interactive session.
|
|
54
79
|
*
|
|
@@ -93,7 +118,10 @@ export function browse(url: string, opts?: {
|
|
|
93
118
|
* @param {'chromium'|'firefox'} [opts.engine='chromium'] - Browser engine.
|
|
94
119
|
* 'firefox' drives over WebDriver BiDi (a separate transport / page object);
|
|
95
120
|
* 'chromium' (default) uses CDP.
|
|
96
|
-
* @returns
|
|
121
|
+
* @returns The interactive page handle — see the exported `Page` typedef. The
|
|
122
|
+
* return type is left uninferred here (no `{...}` tag) so tsc derives it
|
|
123
|
+
* structurally from the returned object literals; annotating it as `Page`
|
|
124
|
+
* would be a self-reference, since `Page` is `ReturnType<typeof connect>`.
|
|
97
125
|
*/
|
|
98
126
|
export function connect(opts?: {
|
|
99
127
|
mode?: "headed" | "headless" | "hybrid" | undefined;
|
|
@@ -116,7 +144,92 @@ export function connect(opts?: {
|
|
|
116
144
|
incognito?: boolean | undefined;
|
|
117
145
|
pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
|
|
118
146
|
engine?: "chromium" | "firefox" | undefined;
|
|
119
|
-
}): Promise<
|
|
147
|
+
}): Promise<{
|
|
148
|
+
readonly bidi: any;
|
|
149
|
+
readonly context: any;
|
|
150
|
+
readonly botBlocked: boolean;
|
|
151
|
+
goto(url: any, timeout?: number): Promise<void>;
|
|
152
|
+
snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
|
|
153
|
+
readable(): Promise<any>;
|
|
154
|
+
click(ref: any): Promise<void>;
|
|
155
|
+
type(ref: string, text: string, typeOpts?: import("./index.js").TypeOptions): Promise<void>;
|
|
156
|
+
press(key: any): Promise<void>;
|
|
157
|
+
scroll(deltaY: any): Promise<void>;
|
|
158
|
+
hover(ref: any): Promise<void>;
|
|
159
|
+
injectCookies(url: string, cookieOpts?: import("./index.js").CookieOptions): Promise<number>;
|
|
160
|
+
select(ref: any, value: any): Promise<void>;
|
|
161
|
+
drag(fromRef: any, toRef: any): Promise<void>;
|
|
162
|
+
upload(ref: any, files: any): Promise<void>;
|
|
163
|
+
goBack(): Promise<void>;
|
|
164
|
+
goForward(): Promise<void>;
|
|
165
|
+
reload(): Promise<void>;
|
|
166
|
+
screenshot(screenshotOpts?: {}): Promise<any>;
|
|
167
|
+
pdf(pdfOpts?: {}): Promise<any>;
|
|
168
|
+
tabs(): Promise<{
|
|
169
|
+
index: number;
|
|
170
|
+
url: any;
|
|
171
|
+
title: any;
|
|
172
|
+
context: any;
|
|
173
|
+
}[]>;
|
|
174
|
+
switchTab(index: any): Promise<void>;
|
|
175
|
+
waitFor(waitOpts?: {}): Promise<void>;
|
|
176
|
+
waitForNetworkIdle(idleOpts?: {}): Promise<void>;
|
|
177
|
+
readonly downloads: any[];
|
|
178
|
+
dialogLog: any[];
|
|
179
|
+
onDialog(handler: any): void;
|
|
180
|
+
saveState(filePath: any): Promise<void>;
|
|
181
|
+
waitForNavigation(timeout?: number): Promise<void>;
|
|
182
|
+
close(): Promise<void>;
|
|
183
|
+
} | {
|
|
184
|
+
goto(url: any, timeout?: number): Promise<void>;
|
|
185
|
+
goBack(): Promise<void>;
|
|
186
|
+
goForward(): Promise<void>;
|
|
187
|
+
reload(reloadOpts?: {}): Promise<void>;
|
|
188
|
+
/** @param {string} url @param {CookieOptions} [cookieOpts] */
|
|
189
|
+
injectCookies(url: string, cookieOpts?: CookieOptions): Promise<number>;
|
|
190
|
+
/** @param {SnapshotOptions|false} [pruneOpts] */
|
|
191
|
+
snapshot(pruneOpts?: SnapshotOptions | false): Promise<string>;
|
|
192
|
+
readable(): Promise<any>;
|
|
193
|
+
click(ref: any): Promise<void>;
|
|
194
|
+
/** @param {string} ref @param {string} text @param {TypeOptions} [typeOpts] */
|
|
195
|
+
type(ref: string, text: string, typeOpts?: TypeOptions): Promise<void>;
|
|
196
|
+
scroll(deltaY: any): Promise<void>;
|
|
197
|
+
press(key: any): Promise<void>;
|
|
198
|
+
hover(ref: any): Promise<void>;
|
|
199
|
+
select(ref: any, value: any): Promise<void>;
|
|
200
|
+
drag(fromRef: any, toRef: any): Promise<void>;
|
|
201
|
+
upload(ref: any, files: any): Promise<void>;
|
|
202
|
+
pdf(pdfOpts?: {}): Promise<any>;
|
|
203
|
+
tabs(): Promise<any>;
|
|
204
|
+
switchTab(index: any): Promise<void>;
|
|
205
|
+
waitFor(waitOpts?: {}): Promise<void>;
|
|
206
|
+
saveState(filePath: any): Promise<void>;
|
|
207
|
+
readonly botBlocked: boolean;
|
|
208
|
+
dialogLog: any[];
|
|
209
|
+
/**
|
|
210
|
+
* Install a custom JS dialog handler. The handler is called with
|
|
211
|
+
* `{ type, message, defaultPrompt }` and may return (sync or async)
|
|
212
|
+
* `{ accept: bool, promptText: string }` to override the auto-accept
|
|
213
|
+
* default. Pass null to restore the default behavior.
|
|
214
|
+
*/
|
|
215
|
+
onDialog(handler: any): void;
|
|
216
|
+
downloads: any[];
|
|
217
|
+
screenshot(screenshotOpts?: {}): Promise<any>;
|
|
218
|
+
waitForNavigation(timeout?: number): Promise<void>;
|
|
219
|
+
waitForNetworkIdle(idleOpts?: {}): Promise<void>;
|
|
220
|
+
/** Raw CDP session for escape hatch — getter so it survives hybrid fallback / tab swaps */
|
|
221
|
+
readonly cdp: any;
|
|
222
|
+
createTab(): Promise<{
|
|
223
|
+
goto(url: any, timeout?: number): Promise<void>;
|
|
224
|
+
readonly botBlocked: boolean;
|
|
225
|
+
/** @param {string} url @param {CookieOptions} [cookieOpts] */
|
|
226
|
+
injectCookies(url: string, cookieOpts?: CookieOptions): Promise<number>;
|
|
227
|
+
waitForNetworkIdle(idleOpts?: {}): Promise<void>;
|
|
228
|
+
cdp: any;
|
|
229
|
+
close(): Promise<void>;
|
|
230
|
+
}>;
|
|
231
|
+
close(): Promise<void>;
|
|
232
|
+
}>;
|
|
120
233
|
/**
|
|
121
234
|
* Apply Network.setBlockedURLs for ad/tracker blocking on a session.
|
|
122
235
|
* Default list is on; pass blockAds:false to skip, blockUrls:[] to extend.
|
|
@@ -130,4 +243,36 @@ export function applyBlocklist(session: any, pageOpts: any): Promise<void>;
|
|
|
130
243
|
/** Test-only: reset the warn-once flag. Not part of the public API. */
|
|
131
244
|
export function _resetBlocklistWarning(): void;
|
|
132
245
|
export { isChallengePage };
|
|
246
|
+
/**
|
|
247
|
+
* The interactive page handle returned by {@link connect}. Inferred structurally
|
|
248
|
+
* from the returned object literals — no hand-maintained interface to drift.
|
|
249
|
+
*
|
|
250
|
+
* It is a union of the two engine page shapes (Chromium/CDP and Firefox/BiDi),
|
|
251
|
+
* which share every interaction method (`goto`, `snapshot`, `click`, `type`,
|
|
252
|
+
* `close`, …) but differ in their escape hatches — `cdp`/`createTab`/`dialogLog`
|
|
253
|
+
* on Chromium, `bidi`/`context` on Firefox. The shared methods dereference
|
|
254
|
+
* without narrowing; an engine-specific hatch requires knowing the engine
|
|
255
|
+
* (the default is Chromium), e.g. `if ('cdp' in page) page.cdp.send(...)`.
|
|
256
|
+
*/
|
|
257
|
+
export type Page = Awaited<ReturnType<typeof connect>>;
|
|
258
|
+
/**
|
|
259
|
+
* Options for `page.snapshot()`. Pass `false` instead of an object to skip
|
|
260
|
+
* pruning and return the raw ARIA tree.
|
|
261
|
+
*/
|
|
262
|
+
export type SnapshotOptions = {
|
|
263
|
+
mode?: "act" | "browse" | "navigate" | "full" | "read";
|
|
264
|
+
};
|
|
265
|
+
/**
|
|
266
|
+
* Options for `page.type()`.
|
|
267
|
+
*/
|
|
268
|
+
export type TypeOptions = {
|
|
269
|
+
clear?: boolean;
|
|
270
|
+
keyEvents?: boolean;
|
|
271
|
+
};
|
|
272
|
+
/**
|
|
273
|
+
* Options for `page.injectCookies()`.
|
|
274
|
+
*/
|
|
275
|
+
export type CookieOptions = {
|
|
276
|
+
browser?: string;
|
|
277
|
+
};
|
|
133
278
|
import { isChallengePage } from './challenge.js';
|