fastbrowse 0.8.3 → 0.9.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 +44 -2
- package/dist/callbacks.js +0 -1
- package/dist/index.d.ts +1 -1
- package/dist/protocol.d.ts +21 -5
- package/dist/protocol.js +2 -2
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -8,9 +8,14 @@ a native binary, so the machine needs no Python.
|
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
10
|
npm install fastbrowse
|
|
11
|
+
export TYPESAFE_API_KEY=...
|
|
11
12
|
export OPENROUTER_API_KEY=...
|
|
12
13
|
```
|
|
13
14
|
|
|
15
|
+
`TYPESAFE_API_KEY` is the recommended Jev route. `OPENROUTER_API_KEY` serves the LLM and, when it is the
|
|
16
|
+
only Jev key, Jev text; it is not the recommended Jev route and never receives Jev image input. Without it,
|
|
17
|
+
the LLM uses `AI_GATEWAY_API_KEY`.
|
|
18
|
+
|
|
14
19
|
With it npm installs the binary for your platform as an optional dependency: `@fastbrowse/darwin-arm64`,
|
|
15
20
|
`darwin-x64`, `linux-arm64`, `linux-x64` or `win32-x64`. No install script runs and nothing is downloaded on
|
|
16
21
|
first use. It needs Node.js 20 or newer, and on Linux it needs glibc.
|
|
@@ -41,10 +46,47 @@ try {
|
|
|
41
46
|
stopped it in `result.wall`: `kind` is `password`, `one_time_code`, `sign_in` or `bot_check`, with the page's
|
|
42
47
|
`origin`, the labels of the `fields` it asked for and `seen_at_ms`.
|
|
43
48
|
|
|
49
|
+
## Processes and errors
|
|
50
|
+
|
|
51
|
+
`Fastbrowse.start` starts one fastbrowse process and `run` sends it a task. The process serves one run at a time:
|
|
52
|
+
a second `run` while one is active rejects with the busy error, so start more instances to run side by side.
|
|
53
|
+
`close()` shuts the process down and waits for it, and the process also exits when yours does.
|
|
54
|
+
|
|
55
|
+
`run` rejects when no run took place or none finished: with `RpcError` when the server refuses the request before
|
|
56
|
+
a browser opens (a bad option, a missing key, a busy server), with `AbortError` when `signal` stopped the run, and
|
|
57
|
+
with `ProcessExitedError` when the process is gone. It also rejects with `OutputValidationError` when a run
|
|
58
|
+
finished but its data fails the `output` schema. A run that fails after it starts, including one whose
|
|
59
|
+
callback throws, resolves with status `error`.
|
|
60
|
+
|
|
61
|
+
## Options
|
|
62
|
+
|
|
63
|
+
The result is the `RunResult` the Python library returns. Its fields keep their Python names, such as
|
|
64
|
+
`final_url`, since the types are generated from the protocol's schema; the options are camelCase.
|
|
65
|
+
|
|
66
|
+
`output` is `data` after a Zod (4.2 or newer) or ArkType schema's validation and transforms, or a Valibot schema
|
|
67
|
+
wrapped by `@valibot/to-json-schema`, typed as the schema's output. Data the schema refuses rejects with
|
|
68
|
+
`OutputValidationError`, which carries the result. A plain JSON Schema object is accepted too; `output` is then
|
|
69
|
+
`data`, typed `unknown`. The server accepts nested objects, arrays, `enum`, `const` and optional values and refuses
|
|
70
|
+
any other keyword by name, but a run fills only a flat object of required string, number, integer and boolean
|
|
71
|
+
fields. With any other field it ends `unverified` with no data.
|
|
72
|
+
|
|
73
|
+
`run` also takes `context`, `inputs`, `attachments` as bytes, `downloads`, `record`, `onFrame` (JPEG frames of the
|
|
74
|
+
active tab; none are sent without it), and the browser choices `chrome`, `cloudProfile`, `cdpUrl`, `cdpPort`,
|
|
75
|
+
`attach`, `targetMatch`, `foreground`, `proxyCountry`, `viewport` and `cloudAllowResizing`. `Fastbrowse.start`
|
|
76
|
+
takes the browser choices as defaults for every run, and a run passes `null` for one to go without that default.
|
|
77
|
+
`env` in `Fastbrowse.start` adds to the environment the process inherits.
|
|
78
|
+
|
|
79
|
+
## Platforms
|
|
80
|
+
|
|
81
|
+
There is no binary for Alpine or another musl system, and none for a platform outside the five. There
|
|
82
|
+
`Fastbrowse.start` rejects with an error that names the platform; name a binary of your own with `binaryPath` or
|
|
83
|
+
`FASTBROWSE_BINARY`. The macOS binaries carry an ad-hoc signature and are not notarized, which a Mac that allows
|
|
84
|
+
programs only by the team that signed them refuses. The Windows binary is not signed. Bun and Deno are untested.
|
|
85
|
+
|
|
44
86
|
## The rest
|
|
45
87
|
|
|
46
88
|
[Use it from JavaScript](https://github.com/agent-labs-dev/fastbrowse#use-it-from-javascript) in the repository
|
|
47
|
-
README
|
|
48
|
-
events
|
|
89
|
+
README has a fuller example: output typed by a Zod schema, secrets your own code resolves, the `until` check,
|
|
90
|
+
step events and stopping a run with an `AbortSignal`.
|
|
49
91
|
|
|
50
92
|
MIT licence.
|
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, Citation, CostBreakdown, CostLine, ErrorCode, Evidence, RunResult, SecretRef, Status, StepEvent, StepFact, StepResult, } from './protocol.ts';
|
|
4
|
+
export type { Artifact, BrowserEvent, BudgetStop, 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
|
@@ -21,7 +21,6 @@ export type ServerMethod = 'run/event' | 'run/frame' | 'run/until' | 'secrets/re
|
|
|
21
21
|
export type Operation = 'click' | 'hover' | 'drag' | 'fill' | 'select' | 'enter' | 'escape' | 'scroll' | 'scroll_up' | 'back' | 'switch_tab' | 'upload' | 'dialog' | 'read' | 'done' | 'escalate' | 'navigate';
|
|
22
22
|
export type StepOutcome = 'executed' | 'covered' | 'stale' | 'failed';
|
|
23
23
|
export type Status = 'complete' | 'unverified' | 'needs_confirmation' | 'needs_login' | 'blocked' | 'needs_input' | 'stuck' | 'budget_exceeded' | 'observation_limit' | 'unavailable' | 'error';
|
|
24
|
-
export type Tripwire = 'no_progress' | 'action_repetition' | 'plan_stagnation';
|
|
25
24
|
/**
|
|
26
25
|
* What a sign-in or bot wall asks of the person who has to get the run past it.
|
|
27
26
|
*/
|
|
@@ -259,6 +258,10 @@ export interface StepResult {
|
|
|
259
258
|
*/
|
|
260
259
|
page_changed: boolean | null;
|
|
261
260
|
duration_ms: number;
|
|
261
|
+
/**
|
|
262
|
+
* The controls Jev was offered for this step's decision, when `Config.step_choices` asked for them.
|
|
263
|
+
*/
|
|
264
|
+
choices?: StepChoice[];
|
|
262
265
|
}
|
|
263
266
|
export interface StepFact {
|
|
264
267
|
text: string;
|
|
@@ -271,6 +274,23 @@ export interface StepFact {
|
|
|
271
274
|
reader: FactReader;
|
|
272
275
|
deep_link: string | null;
|
|
273
276
|
}
|
|
277
|
+
export interface StepChoice {
|
|
278
|
+
id: string;
|
|
279
|
+
role: string;
|
|
280
|
+
/**
|
|
281
|
+
* The label as Jev read it, with resolved secrets masked.
|
|
282
|
+
*/
|
|
283
|
+
label: string;
|
|
284
|
+
/**
|
|
285
|
+
* The card or row that tells this control from its twins, as Jev read it, with resolved secrets masked.
|
|
286
|
+
*/
|
|
287
|
+
context: string | null;
|
|
288
|
+
operations: Operation[];
|
|
289
|
+
/**
|
|
290
|
+
* Whether Jev chose this control: the target, and for a drag the destination too.
|
|
291
|
+
*/
|
|
292
|
+
chosen: boolean;
|
|
293
|
+
}
|
|
274
294
|
/**
|
|
275
295
|
* The params of `run/frame`: the active tab as it looked a moment ago. Sent only to a run that set `frames`.
|
|
276
296
|
*/
|
|
@@ -338,10 +358,6 @@ export interface RunResult {
|
|
|
338
358
|
* Where the browser was last observed; what a caller checks when the task was to arrive somewhere.
|
|
339
359
|
*/
|
|
340
360
|
final_url: string | null;
|
|
341
|
-
/**
|
|
342
|
-
* Shadow tripwires retain each occurrence so eval counts do not depend on logging configuration.
|
|
343
|
-
*/
|
|
344
|
-
would_fire: Tripwire[];
|
|
345
361
|
/**
|
|
346
362
|
* The videos this run finished writing, captioned then plain; empty when it recorded nothing or encoding failed.
|
|
347
363
|
*/
|
package/dist/protocol.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
// Generated from
|
|
2
|
-
// Do not edit: change the
|
|
1
|
+
// Generated from protocol/schema.json, which crates/fastbrowse-core/src/protocol.rs writes.
|
|
2
|
+
// Do not edit: change the types there, then run `npm run generate:sdk`.
|
|
3
3
|
export const ErrorCode = {
|
|
4
4
|
PARSE_ERROR: -32700,
|
|
5
5
|
INVALID_REQUEST: -32600,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fastbrowse",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.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.9.1",
|
|
31
|
+
"@fastbrowse/darwin-x64": "0.9.1",
|
|
32
|
+
"@fastbrowse/linux-arm64": "0.9.1",
|
|
33
|
+
"@fastbrowse/linux-x64": "0.9.1",
|
|
34
|
+
"@fastbrowse/win32-x64": "0.9.1"
|
|
35
35
|
}
|
|
36
36
|
}
|