fastbrowse 0.10.0 → 0.11.1
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/README.md +5 -2
- package/dist/addon.d.ts +2 -7
- package/dist/addon.js +1 -4
- package/dist/callbacks.d.ts +2 -2
- package/dist/callbacks.js +1 -0
- package/dist/index.d.ts +1 -1
- package/dist/protocol.d.ts +36 -5
- package/dist/protocol.js +1 -1
- package/dist/run.d.ts +9 -6
- package/dist/run.js +1 -0
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -18,8 +18,9 @@ With it npm installs the binary for your platform as an optional dependency: `@f
|
|
|
18
18
|
`darwin-x64`, `linux-arm64`, `linux-x64` or `win32-x64`. No install script runs and nothing is downloaded on
|
|
19
19
|
first use. It needs Node.js 20 or newer, and on Linux it needs glibc.
|
|
20
20
|
|
|
21
|
-
The binary brings no browser. `local: true` drives
|
|
22
|
-
|
|
21
|
+
The binary brings no browser. `local: true` drives your own Chrome through the
|
|
22
|
+
[fastbrowse extension](../../docs/cli.md#your-own-chrome), signed in as you are; add `launch: true` to start a separate
|
|
23
|
+
Chrome instead. Without either a run starts a Browser Use Cloud browser, which needs `BROWSER_USE_API_KEY`.
|
|
23
24
|
|
|
24
25
|
## First run
|
|
25
26
|
|
|
@@ -95,6 +96,8 @@ starts one from the first step; the server refuses the two together. `allowedOri
|
|
|
95
96
|
may open, read and control to those exact origins: navigations, redirects, frames and popups elsewhere are refused
|
|
96
97
|
before they are sent, so a sign-in that redirects through another origin needs it listed too. It scopes documents,
|
|
97
98
|
not the network, and a scoped run sends no frames and cannot `record`.
|
|
99
|
+
Set `EXA_API_KEY` in the server environment to offer browserless web search. Jev picks among LLM-proposed queries;
|
|
100
|
+
result fields become citable records and links use the same origin checks. Search charges appear under `search`.
|
|
98
101
|
`env` in `Fastbrowse.start` adds to the environment the process inherits.
|
|
99
102
|
Recipe paths name files on the server running fastbrowse. `saveRecipe` writes after a completed run; a write failure is logged without changing the task status, so check the file before replay;
|
|
100
103
|
`recipe` reuses saved values for matching live actions with the same task.
|
package/dist/addon.d.ts
CHANGED
|
@@ -22,12 +22,8 @@ export interface Addon {
|
|
|
22
22
|
protocolVersion(): number;
|
|
23
23
|
/**
|
|
24
24
|
* Read PDFs by running this fastbrowse binary as a helper process. False when a helper was already set.
|
|
25
|
-
*
|
|
26
|
-
* Optional because an addon built before it still speaks protocol 2 and must still load with its original PDF
|
|
27
|
-
* handling. Make it required when the protocol version next changes, since the check in `Fastbrowse.start` then
|
|
28
|
-
* refuses every addon that lacks it before `readPdfsWith` is called.
|
|
29
25
|
*/
|
|
30
|
-
setPdfHelper
|
|
26
|
+
setPdfHelper(path: string): boolean;
|
|
31
27
|
}
|
|
32
28
|
/**
|
|
33
29
|
* The addon to load: the caller's own path first, then the one the environment names, then the `fastbrowse.node`
|
|
@@ -37,8 +33,7 @@ export declare function loadAddon(addonPath: string | undefined, env: NodeJS.Pro
|
|
|
37
33
|
/**
|
|
38
34
|
* Have `addon` read PDFs with the fastbrowse binary `env` resolves to, once its protocol is known to match. A PDF is
|
|
39
35
|
* read in a process the run can kill, and Node is no program the addon can run again for that: the binary beside it
|
|
40
|
-
* is. Without a binary, the
|
|
41
|
-
* addon without this method retains its original PDF handling.
|
|
36
|
+
* is. Without a binary, the addon still runs and says of each PDF that its text went unread.
|
|
42
37
|
*/
|
|
43
38
|
export declare function readPdfsWith(addon: Addon, env: NodeJS.ProcessEnv, binaryPath?: string): void;
|
|
44
39
|
/** Runs on the addon, one at a time as the fastbrowse process runs them, so the two modes answer alike. */
|
package/dist/addon.js
CHANGED
|
@@ -25,12 +25,9 @@ export function loadAddon(addonPath, env) {
|
|
|
25
25
|
/**
|
|
26
26
|
* Have `addon` read PDFs with the fastbrowse binary `env` resolves to, once its protocol is known to match. A PDF is
|
|
27
27
|
* read in a process the run can kill, and Node is no program the addon can run again for that: the binary beside it
|
|
28
|
-
* is. Without a binary, the
|
|
29
|
-
* addon without this method retains its original PDF handling.
|
|
28
|
+
* is. Without a binary, the addon still runs and says of each PDF that its text went unread.
|
|
30
29
|
*/
|
|
31
30
|
export function readPdfsWith(addon, env, binaryPath) {
|
|
32
|
-
if (typeof addon.setPdfHelper !== 'function')
|
|
33
|
-
return;
|
|
34
31
|
let binary;
|
|
35
32
|
try {
|
|
36
33
|
binary = resolveBinary(binaryPath, env);
|
package/dist/callbacks.d.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
import { type BrowserEvent, type RunResult, type StepEvent } from './protocol.ts';
|
|
1
|
+
import { type BrowserEvent, type BrowserWarningEvent, type RunResult, type StepEvent } from './protocol.ts';
|
|
2
2
|
import type { Connection } from './rpc.ts';
|
|
3
3
|
import type { RunOptions } from './run.ts';
|
|
4
4
|
export declare class Callbacks {
|
|
5
5
|
#private;
|
|
6
6
|
/** Without a connection, the in-process core calls the four methods below itself. */
|
|
7
7
|
constructor(connection?: Connection);
|
|
8
|
-
event(runId: string, event: StepEvent | BrowserEvent): void;
|
|
8
|
+
event(runId: string, event: StepEvent | BrowserEvent | BrowserWarningEvent): void;
|
|
9
9
|
frame(runId: string, jpeg: Uint8Array): void;
|
|
10
10
|
until(runId: string, url: string): Promise<boolean>;
|
|
11
11
|
resolve(runId: string, name: string, origin: string): Promise<string | null>;
|
package/dist/callbacks.js
CHANGED
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export { AbortError, FastbrowseError, ProcessExitedError, RpcError } from './errors.ts';
|
|
2
2
|
export { type CloseOptions, Fastbrowse, type StartOptions } from './fastbrowse.ts';
|
|
3
3
|
export { type JsonSchema, type OutputIssue, type OutputOf, type OutputSchema, OutputValidationError, type StandardOutputSchema, type TypedRunResult, } from './output.ts';
|
|
4
|
-
export type { Artifact, BrowserEvent, BudgetStop, CancellationReceipt, Citation, CostBreakdown, CostLine, ErrorCode, Evidence, RunResult, SecretRef, Status, StepChoice, StepEvent, StepFact, StepResult, } from './protocol.ts';
|
|
4
|
+
export type { Artifact, BrowserEvent, BrowserWarningEvent, BudgetStop, CancellationReceipt, Citation, CostBreakdown, CostLine, ErrorCode, Evidence, RunResult, SecretRef, Status, StepChoice, StepEvent, StepFact, StepResult, } from './protocol.ts';
|
|
5
5
|
export type { Attachment, BrowserOptions, RunOptions, Secrets } from './run.ts';
|
package/dist/protocol.d.ts
CHANGED
|
@@ -3,16 +3,22 @@ export type ArtifactKind = 'download' | 'screenshot' | 'capture';
|
|
|
3
3
|
* How a run reached the browser it drove.
|
|
4
4
|
*/
|
|
5
5
|
export type BrowserVia = 'cloud' | 'launched' | 'attached' | 'extension';
|
|
6
|
-
export type
|
|
6
|
+
export type BrowserWarningOperation = 'screencast_start' | 'screencast_stop' | 'screencast_frame_ack' | 'paint_keeper_attach' | 'popup_setup_close' | 'popup_setup_release' | 'frame_callback_shutdown' | 'live_frame_delivery' | 'download_capture';
|
|
7
|
+
export type BrowserWarningFailure = 'browser_error' | 'context_lost' | 'browser_unavailable' | 'screenshots_unavailable' | 'navigation_timeout' | 'site_unreachable' | 'browser_unresponsive' | 'page_unresponsive' | 'origin_not_allowed' | 'script_error' | 'timeout' | 'callback_exception' | 'payload_decode' | 'capture_failed' | 'cancelled';
|
|
8
|
+
export type Operation = 'click' | 'hover' | 'drag' | 'fill' | 'press' | 'blur' | 'select' | 'enter' | 'escape' | 'scroll' | 'scroll_up' | 'back' | 'switch_tab' | 'upload' | 'dialog' | 'wait' | 'read' | 'done' | 'navigate' | 'search';
|
|
7
9
|
/**
|
|
8
10
|
* Who chose a step: Jev, a rule in code, or a saved recipe action confirmed by Jev.
|
|
9
11
|
*/
|
|
10
12
|
export type Decider = 'jev' | 'code' | 'recipe';
|
|
11
13
|
export type StepOutcome = 'executed' | 'covered' | 'stale' | 'failed';
|
|
14
|
+
/**
|
|
15
|
+
* A closed reason for a failed browser step; ``note`` remains diagnostic text.
|
|
16
|
+
*/
|
|
17
|
+
export type StepFailure = 'missing_target' | 'target_gone' | 'unauthorized_origin' | 'navigation_failed' | 'dialog_interrupted' | 'browser_error';
|
|
12
18
|
export type FactReader = 'jev_choice' | 'llm_image';
|
|
13
|
-
export type CostComponent = 'jev' | 'llm' | 'browser' | 'proxy';
|
|
19
|
+
export type CostComponent = 'jev' | 'llm' | 'browser' | 'proxy' | 'search';
|
|
14
20
|
export type CostBasis = 'metered' | 'estimated' | 'bounded' | 'unsettled' | 'unknown';
|
|
15
|
-
export type LLMPurpose = 'start' | 'compose' | 'image_read' | 'fill' | 'pages' | 'dates';
|
|
21
|
+
export type LLMPurpose = 'start' | 'compose' | 'image_read' | 'fill' | 'pages' | 'dates' | 'known_pages' | 'recovery_pages' | 'search' | 'unobtainable' | 'groups' | 'action';
|
|
16
22
|
export type JevPurpose = 'action' | 'authorization' | 'relevance' | 'read' | 'verify' | 'locate';
|
|
17
23
|
/**
|
|
18
24
|
* Every code an error reply can carry: the JSON-RPC standard ones, then this protocol's own.
|
|
@@ -76,6 +82,14 @@ export interface BrowserUsed {
|
|
|
76
82
|
*/
|
|
77
83
|
browser: string | null;
|
|
78
84
|
}
|
|
85
|
+
/**
|
|
86
|
+
* A browser warning with only a closed operation and failure kind; it contains no page or transport text.
|
|
87
|
+
*/
|
|
88
|
+
export interface BrowserWarningEvent {
|
|
89
|
+
type: 'browser_warning';
|
|
90
|
+
operation: BrowserWarningOperation;
|
|
91
|
+
failure: BrowserWarningFailure;
|
|
92
|
+
}
|
|
79
93
|
export interface BudgetStop {
|
|
80
94
|
resource: 'steps' | 'dollars' | 'seconds' | 'jev_calls' | 'llm_calls';
|
|
81
95
|
limit: number;
|
|
@@ -99,6 +113,7 @@ export interface StepResult {
|
|
|
99
113
|
operation: Operation;
|
|
100
114
|
decided_by: Decider;
|
|
101
115
|
outcome: StepOutcome;
|
|
116
|
+
failure: StepFailure | null;
|
|
102
117
|
url: string;
|
|
103
118
|
/**
|
|
104
119
|
* Human-readable label of the chosen element; never contains a secret value.
|
|
@@ -213,12 +228,22 @@ export interface Evidence {
|
|
|
213
228
|
* The `uri` of the `capture` artifact holding the page text `start` and `end` index into, if one was kept.
|
|
214
229
|
*/
|
|
215
230
|
capture_artifact?: string | null;
|
|
231
|
+
/**
|
|
232
|
+
* The links inside the quote and where each leads, which its text alone does not say.
|
|
233
|
+
*/
|
|
234
|
+
links?: Link[];
|
|
216
235
|
}
|
|
217
236
|
export interface SourceControl {
|
|
218
237
|
role: string;
|
|
219
238
|
label: string;
|
|
220
239
|
context: string | null;
|
|
221
240
|
}
|
|
241
|
+
export interface Link {
|
|
242
|
+
text: string;
|
|
243
|
+
start: number;
|
|
244
|
+
end: number;
|
|
245
|
+
href: string;
|
|
246
|
+
}
|
|
222
247
|
/**
|
|
223
248
|
* The client's side of the handshake.
|
|
224
249
|
*
|
|
@@ -321,7 +346,7 @@ export interface RunCancelParams {
|
|
|
321
346
|
*/
|
|
322
347
|
export interface RunEvent {
|
|
323
348
|
run_id: string;
|
|
324
|
-
event: StepEvent | BrowserEvent;
|
|
349
|
+
event: StepEvent | BrowserEvent | BrowserWarningEvent;
|
|
325
350
|
}
|
|
326
351
|
export interface StepEvent {
|
|
327
352
|
type: 'step';
|
|
@@ -368,6 +393,7 @@ export interface RunParams {
|
|
|
368
393
|
save_recipe?: string | null;
|
|
369
394
|
cursor?: boolean | null;
|
|
370
395
|
local?: boolean;
|
|
396
|
+
launch?: boolean;
|
|
371
397
|
chrome?: LocalChrome | null;
|
|
372
398
|
cloud_profile?: string | null;
|
|
373
399
|
cdp_url?: string | null;
|
|
@@ -384,6 +410,7 @@ export interface RunParams {
|
|
|
384
410
|
browser?: boolean;
|
|
385
411
|
extension?: boolean;
|
|
386
412
|
extension_browser?: string | null;
|
|
413
|
+
desktop?: string | null;
|
|
387
414
|
}
|
|
388
415
|
export interface SecretRef {
|
|
389
416
|
name: string;
|
|
@@ -403,6 +430,10 @@ export interface RunResult {
|
|
|
403
430
|
artifacts: Artifact[];
|
|
404
431
|
citations: Citation[];
|
|
405
432
|
error: string | null;
|
|
433
|
+
/**
|
|
434
|
+
* The error's provider or browser variant path, never message text; present for failures, absent otherwise.
|
|
435
|
+
*/
|
|
436
|
+
failure_kind: string | null;
|
|
406
437
|
/**
|
|
407
438
|
* Where the browser was last observed; what a caller checks when the task was to arrive somewhere.
|
|
408
439
|
*/
|
|
@@ -483,7 +514,7 @@ export declare const Method: {
|
|
|
483
514
|
readonly RUN_CANCEL: 'run/cancel';
|
|
484
515
|
readonly SHUTDOWN: 'shutdown';
|
|
485
516
|
};
|
|
486
|
-
export declare const PROTOCOL_VERSION =
|
|
517
|
+
export declare const PROTOCOL_VERSION = 3;
|
|
487
518
|
export declare const ServerMethod: {
|
|
488
519
|
readonly RUN_EVENT: 'run/event';
|
|
489
520
|
readonly RUN_FRAME: 'run/frame';
|
package/dist/protocol.js
CHANGED
package/dist/run.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type OutputSchema } from './output.ts';
|
|
2
|
-
import type { Authorization, BrowserEvent, Limits, LocalChrome, RunParams, SecretRef, StepEvent } from './protocol.ts';
|
|
2
|
+
import type { Authorization, BrowserEvent, BrowserWarningEvent, Limits, LocalChrome, RunParams, SecretRef, StepEvent } from './protocol.ts';
|
|
3
3
|
type Camel<Name extends string> = Name extends `${infer Head}_${infer Tail}` ? `${Head}${Capitalize<Camel<Tail>>}` : Name;
|
|
4
4
|
/** A wire model with its field names in camelCase, so its fields follow the wire model without a second list. */
|
|
5
5
|
export type CamelKeys<Model> = {
|
|
@@ -7,9 +7,11 @@ export type CamelKeys<Model> = {
|
|
|
7
7
|
};
|
|
8
8
|
/** Which browser a run drives. Given to `Fastbrowse.start`, these are the defaults of every run it makes. */
|
|
9
9
|
export interface BrowserOptions {
|
|
10
|
-
/**
|
|
10
|
+
/** A browser on this machine instead of a Browser Use Cloud browser: your own Chrome through the fastbrowse extension, unless `launch` asks for a separate one. */
|
|
11
11
|
local?: boolean;
|
|
12
|
-
/**
|
|
12
|
+
/** Start a separate local Chrome instead of driving your own through the extension. Implies `local`. */
|
|
13
|
+
launch?: boolean;
|
|
14
|
+
/** Which local Chrome, and how. A headed window or a kept profile implies `launch`. */
|
|
13
15
|
chrome?: CamelKeys<LocalChrome>;
|
|
14
16
|
cloudProfile?: string;
|
|
15
17
|
/** The DevTools WebSocket URL of a browser that is already running. The run neither starts nor stops it. */
|
|
@@ -100,10 +102,11 @@ export interface RunOptions extends PerRun<BrowserOptions> {
|
|
|
100
102
|
/** Called with the address the run ended on. Anything but true keeps the run from `complete`. */
|
|
101
103
|
until?: (url: string) => MaybePromise<boolean>;
|
|
102
104
|
/**
|
|
103
|
-
* Called with the browser event
|
|
104
|
-
* callback here, one that throws or rejects ends the run with
|
|
105
|
+
* Called with the browser event, step events, and typed browser warnings. Warning codes contain no page
|
|
106
|
+
* content or transport error text. Like any callback here, one that throws or rejects ends the run with
|
|
107
|
+
* status `error`.
|
|
105
108
|
*/
|
|
106
|
-
onEvent?: (event: StepEvent | BrowserEvent) => void;
|
|
109
|
+
onEvent?: (event: StepEvent | BrowserEvent | BrowserWarningEvent) => void;
|
|
107
110
|
/** Called with JPEG frames of the active tab while the run goes on. Without it the page is never filmed. */
|
|
108
111
|
onFrame?: (frame: Uint8Array) => void;
|
|
109
112
|
/**
|
package/dist/run.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fastbrowse",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.1",
|
|
4
4
|
"description": "Browser automation with cited answers, structured output and code-controlled credentials and authorization.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -27,10 +27,10 @@
|
|
|
27
27
|
"test": "npm run build && node --test \"test/*.test.ts\""
|
|
28
28
|
},
|
|
29
29
|
"optionalDependencies": {
|
|
30
|
-
"@fastbrowse/darwin-arm64": "0.
|
|
31
|
-
"@fastbrowse/darwin-x64": "0.
|
|
32
|
-
"@fastbrowse/linux-arm64": "0.
|
|
33
|
-
"@fastbrowse/linux-x64": "0.
|
|
34
|
-
"@fastbrowse/win32-x64": "0.
|
|
30
|
+
"@fastbrowse/darwin-arm64": "0.11.1",
|
|
31
|
+
"@fastbrowse/darwin-x64": "0.11.1",
|
|
32
|
+
"@fastbrowse/linux-arm64": "0.11.1",
|
|
33
|
+
"@fastbrowse/linux-x64": "0.11.1",
|
|
34
|
+
"@fastbrowse/win32-x64": "0.11.1"
|
|
35
35
|
}
|
|
36
36
|
}
|