fastbrowse 0.8.3 → 0.9.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/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 covers output typed by a Zod or JSON Schema, secrets your own code resolves, the `until` check, step
48
- events, live frames and stopping a run with an `AbortSignal`.
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
@@ -111,7 +111,6 @@ function endedBy(failure) {
111
111
  citations: [],
112
112
  error: failure,
113
113
  final_url: null,
114
- would_fire: [],
115
114
  recordings: [],
116
115
  wall: null,
117
116
  };
@@ -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
  */
@@ -338,10 +337,6 @@ export interface RunResult {
338
337
  * Where the browser was last observed; what a caller checks when the task was to arrive somewhere.
339
338
  */
340
339
  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
340
  /**
346
341
  * The videos this run finished writing, captioned then plain; empty when it recorded nothing or encoding failed.
347
342
  */
package/dist/protocol.js CHANGED
@@ -1,5 +1,5 @@
1
- // Generated from the models in src/fastbrowse/protocol.py and src/fastbrowse/models.py.
2
- // Do not edit: change the models, then run `npm run generate:sdk`.
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.8.3",
3
+ "version": "0.9.0",
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.8.3",
31
- "@fastbrowse/darwin-x64": "0.8.3",
32
- "@fastbrowse/linux-arm64": "0.8.3",
33
- "@fastbrowse/linux-x64": "0.8.3",
34
- "@fastbrowse/win32-x64": "0.8.3"
30
+ "@fastbrowse/darwin-arm64": "0.9.0",
31
+ "@fastbrowse/darwin-x64": "0.9.0",
32
+ "@fastbrowse/linux-arm64": "0.9.0",
33
+ "@fastbrowse/linux-x64": "0.9.0",
34
+ "@fastbrowse/win32-x64": "0.9.0"
35
35
  }
36
36
  }