browsa 0.3.0__tar.gz → 0.5.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.
- {browsa-0.3.0 → browsa-0.5.0}/PKG-INFO +106 -9
- {browsa-0.3.0 → browsa-0.5.0}/README.md +104 -8
- {browsa-0.3.0 → browsa-0.5.0}/browsa/__init__.py +16 -8
- browsa-0.5.0/browsa/_version.py +1 -0
- browsa-0.5.0/browsa/captcha/__init__.py +28 -0
- browsa-0.5.0/browsa/captcha/_client.py +194 -0
- browsa-0.5.0/browsa/captcha/compat.py +165 -0
- browsa-0.5.0/browsa/captcha/tasks.py +248 -0
- {browsa-0.3.0 → browsa-0.5.0}/browsa/client.py +386 -2
- browsa-0.5.0/browsa/py.typed +0 -0
- {browsa-0.3.0 → browsa-0.5.0}/browsa/types.py +354 -0
- {browsa-0.3.0 → browsa-0.5.0}/browsa.egg-info/PKG-INFO +106 -9
- {browsa-0.3.0 → browsa-0.5.0}/browsa.egg-info/SOURCES.txt +8 -0
- {browsa-0.3.0 → browsa-0.5.0}/pyproject.toml +4 -0
- browsa-0.5.0/tests/test_captcha.py +306 -0
- browsa-0.5.0/tests/test_recipes.py +153 -0
- browsa-0.5.0/tests/test_robots.py +212 -0
- {browsa-0.3.0 → browsa-0.5.0}/tests/test_unit.py +95 -0
- browsa-0.3.0/browsa/_version.py +0 -1
- {browsa-0.3.0 → browsa-0.5.0}/LICENSE +0 -0
- {browsa-0.3.0 → browsa-0.5.0}/browsa/errors.py +0 -0
- {browsa-0.3.0 → browsa-0.5.0}/browsa/webhooks.py +0 -0
- {browsa-0.3.0 → browsa-0.5.0}/browsa.egg-info/dependency_links.txt +0 -0
- {browsa-0.3.0 → browsa-0.5.0}/browsa.egg-info/requires.txt +0 -0
- {browsa-0.3.0 → browsa-0.5.0}/browsa.egg-info/top_level.txt +0 -0
- {browsa-0.3.0 → browsa-0.5.0}/setup.cfg +0 -0
- {browsa-0.3.0 → browsa-0.5.0}/tests/test_live.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: browsa
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Official Python SDK for Browsa: real cloud browsers for AI agents (browsa.io)
|
|
5
5
|
Author-email: Browsa <support@browsa.io>
|
|
6
6
|
License: MIT
|
|
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.9
|
|
|
18
18
|
Classifier: Programming Language :: Python :: 3.10
|
|
19
19
|
Classifier: Programming Language :: Python :: 3.11
|
|
20
20
|
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Typing :: Typed
|
|
21
22
|
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
|
|
22
23
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
23
24
|
Requires-Python: >=3.9
|
|
@@ -56,14 +57,17 @@ from browsa import Client
|
|
|
56
57
|
c = Client(api_key="agt_live_...")
|
|
57
58
|
job = c.run_task(
|
|
58
59
|
task="Go to news.ycombinator.com and return the top story title.",
|
|
59
|
-
llm="
|
|
60
|
-
|
|
60
|
+
llm="browsa",
|
|
61
|
+
on_progress=lambda j: j.live_url and print("watch live:", j.live_url),
|
|
61
62
|
)
|
|
62
|
-
print(job.final_result)
|
|
63
|
-
print("watch live:", job.live_url)
|
|
63
|
+
print(job.outcome, job.final_result)
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
That runs
|
|
66
|
+
That runs Phantom, our own browser, in a temporary cloud browser, driven by Browsa's hosted model: no LLM key needed. To use your own model instead, pass `llm="anthropic:claude-sonnet-5-5"` with `llm_api_key`, or save the key once (below).
|
|
67
|
+
|
|
68
|
+
`job.status` says the run ended; `job.outcome` says how. `outcome == "failed"` with `status == "completed"` means the agent finished but could not do the task, and `final_result` says what stopped it.
|
|
69
|
+
|
|
70
|
+
`live_url` is a Phantom Live link to watch the browser. It exists only while the task runs (so read it in `on_progress` or from `create_task`), and each link opens once.
|
|
67
71
|
|
|
68
72
|
## Saved LLM keys
|
|
69
73
|
|
|
@@ -133,6 +137,46 @@ print(job.llm_cost_usd) # None for hosted runs
|
|
|
133
137
|
|
|
134
138
|
A finished job has `usage` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `requests`), `llm_cost_usd`, `llm_tier` and `reasoning` (the level that was applied). `llm_cost_usd` is an estimate from public list prices for runs with your own key; it is `None` when unknown and always `None` for hosted runs, which are paid in credits. All four are `None` on jobs that do not have them, such as jobs run before these fields existed.
|
|
135
139
|
|
|
140
|
+
## Robots
|
|
141
|
+
|
|
142
|
+
A robot is a browser job you set up once: record a task, then run it on rows of input, on demand, on a schedule or from the API. Runs replay the recording on Phantom with no model.
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
BOOK = "https://books.toscrape.com/catalogue"
|
|
146
|
+
|
|
147
|
+
# 1. Record a task once
|
|
148
|
+
job = c.run_task(
|
|
149
|
+
task="Open the product page and return title, price and in_stock",
|
|
150
|
+
llm="browsa",
|
|
151
|
+
initial_url=f"{BOOK}/sharp-objects_997/index.html",
|
|
152
|
+
record_recipe=True,
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
# 2. Save it as a robot
|
|
156
|
+
robot = c.robots.create(
|
|
157
|
+
name="Book prices",
|
|
158
|
+
from_job_id=job.id,
|
|
159
|
+
inputs=[{"url": f"{BOOK}/sharp-objects_997/index.html"}, {"url": f"{BOOK}/soumission_998/index.html"}],
|
|
160
|
+
schedule={"interval_seconds": 86400, "at": "09:00", "tz": "UTC"},
|
|
161
|
+
monitors=[{"field": "price", "op": "changed"}],
|
|
162
|
+
settings={"proxy": {"network": "datacenter"}},
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
# 3. Run it and read the rows
|
|
166
|
+
run = c.robot_runs.wait(c.robots.run(robot.id).id)
|
|
167
|
+
for r in run.rows or []:
|
|
168
|
+
print(r.row, r.status, r.output or r.error_code)
|
|
169
|
+
csv_text = c.robot_runs.export(run.id) # or format="json"
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
| | |
|
|
173
|
+
|---|---|
|
|
174
|
+
| Price | `robot.health.price_credits` per successful row, the same as the agent task. Failed rows are free. |
|
|
175
|
+
| Settings | `model` (records and repairs), `proxy` (Browsa's network: datacenter 5, residential 50 credits/GB; or a saved `proxy_id`, free), `browser` (`os`, `screen`). Unset is Auto. |
|
|
176
|
+
| More | `list`, `get`, `update`, `delete`, `pause`, `resume`, `runs`, `alerts`, `mark_alerts_read`. `AsyncClient` has the same under `await`. Recipes alone: `create_recipe`, `run_recipe`, `get_recipe_run`. |
|
|
177
|
+
|
|
178
|
+
Guide: <https://browsa.io/guides/robots>.
|
|
179
|
+
|
|
136
180
|
## Async
|
|
137
181
|
|
|
138
182
|
```python
|
|
@@ -178,7 +222,8 @@ if not ok:
|
|
|
178
222
|
| Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
|
|
179
223
|
| Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
|
|
180
224
|
| Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
|
|
181
|
-
| Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc
|
|
225
|
+
| Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, `TimeoutError`, etc.; every one is a `BrowsaError` |
|
|
226
|
+
| Typed | Ships `py.typed`; works with `mypy --strict` and pyright |
|
|
182
227
|
| `X-Request-Id` propagation | Every error carries the server's request id |
|
|
183
228
|
| Zero deps | Single wheel, audit-friendly, no transitive surface |
|
|
184
229
|
|
|
@@ -201,7 +246,7 @@ job = c.run_task(
|
|
|
201
246
|
|
|
202
247
|
### Interactive (input_required) tasks
|
|
203
248
|
|
|
204
|
-
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
|
|
249
|
+
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond. Hosted tasks solve reCAPTCHA v2 image grids (3 x 3, 4 x 4 and reloading tiles), image-text captchas, GeeTest slide puzzles (v3 and v4) and AWS WAF captchas in the browser's own session on workspaces that have bought a pack (fair use applies); the types and measured pass rates are at https://browsa.io/captcha. A type that is not supported yet, or a workspace on free credits only, may still need you here. Respond like this:
|
|
205
250
|
|
|
206
251
|
```python
|
|
207
252
|
job = c.create_task(task="...", llm="...", llm_api_key="...")
|
|
@@ -217,7 +262,7 @@ while not job.is_terminal:
|
|
|
217
262
|
Start a task with `create_session` and the browser stays up after it ends (15 minutes by default, `browser_ttl_seconds` up to 3600), so you can send follow-ups that continue on the same page. A follow-up pays no new browser, only the task's base and step credits.
|
|
218
263
|
|
|
219
264
|
```python
|
|
220
|
-
s = c.create_session("Go to example.com and return the
|
|
265
|
+
s = c.create_session("Go to example.com and return the page title.", llm="browsa")
|
|
221
266
|
first = c.wait_for_job(s.id)
|
|
222
267
|
print(first.final_result)
|
|
223
268
|
|
|
@@ -259,6 +304,58 @@ c.act(b["id"], "click", role="button", name="Sign in")
|
|
|
259
304
|
|
|
260
305
|
`status` is `ok`, `failed`, `blocked`, `challenge` or `stale`; none of them raises. `stale` means the ids came from a view the server no longer has (`ids_reset` is true): nothing was done and `text` carries a new view. Both calls are free. Format and actions: <https://browsa.io/docs#agents-observe>.
|
|
261
306
|
|
|
307
|
+
### Downloads and Phantom Live
|
|
308
|
+
|
|
309
|
+
Files a browser downloads are kept with the browser, not on your machine, so Playwright's `download.save_as()` cannot reach them. List and fetch them through the API before you stop the browser:
|
|
310
|
+
|
|
311
|
+
```python
|
|
312
|
+
files = c.list_downloads(b["id"]) # [{"name", "size", "modified_at"}]
|
|
313
|
+
data = c.download_file(b["id"], files[0]["name"]) # bytes
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
With Playwright the name is the last part of `download.path()`.
|
|
317
|
+
|
|
318
|
+
`create_live_link` gives a link that shows a running browser in any web browser, to watch or to take over:
|
|
319
|
+
|
|
320
|
+
```python
|
|
321
|
+
link = c.create_live_link(b["id"], scope="control", ttl_seconds=600)
|
|
322
|
+
print(link["live_url"]) # opens once; make one per person
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
`scope` is `"view"` (default) or `"control"`. Both calls are free.
|
|
326
|
+
|
|
327
|
+
## Captcha solving
|
|
328
|
+
|
|
329
|
+
`browsa.captcha` is a client for Browsa's captcha API: `createTask`, `getTaskResult` and `getBalance` in the format CapSolver, Anti-Captcha, CapMonster and 2Captcha's v2 API share. Same key and credits as the browser API. Failed and unsolvable tasks are not charged. Measured pass rates per type: <https://browsa.io/captcha>.
|
|
330
|
+
|
|
331
|
+
```python
|
|
332
|
+
from browsa.captcha import CaptchaClient, CaptchaError, tasks
|
|
333
|
+
|
|
334
|
+
cap = CaptchaClient() # BROWSA_API_KEY; https://captcha.browsa.io (or BROWSA_CAPTCHA_URL)
|
|
335
|
+
sol = cap.solve(tasks.recaptcha_v3("https://example.com/login", "6Lc...", page_action="login"))
|
|
336
|
+
token = sol["gRecaptchaResponse"] # sol.task_id is the task id
|
|
337
|
+
|
|
338
|
+
text = cap.solve(tasks.image_to_text(open("captcha.png", "rb").read()))["text"]
|
|
339
|
+
print(cap.get_balance()) # credits
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
Builders: `image_to_text`, `recaptcha_v2`, `recaptcha_v3`, `turnstile`, `recaptcha_v2_classification` (and `aws_waf_classification`, `slider`). Each takes `proxy=` (a URL string or `{"type", "host", "port", "username", "password"}`); without one the proxyless type is used. `AsyncCaptchaClient` has the same methods.
|
|
343
|
+
|
|
344
|
+
A task copied from code for another service works as it is: `RecaptchaV2TaskProxyless`, `TurnstileTask`, `NoCaptchaTaskProxyless` and the like are sent under Browsa's names. Errors raise `CaptchaError` with the API's `code` (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_ZERO_BALANCE`, ...).
|
|
345
|
+
|
|
346
|
+
Coming from a library that cannot be pointed at another server:
|
|
347
|
+
|
|
348
|
+
```python
|
|
349
|
+
from browsa.captcha.compat import TwoCaptcha # instead of: from twocaptcha import TwoCaptcha
|
|
350
|
+
solver = TwoCaptcha("agt_live_...")
|
|
351
|
+
solver.recaptcha(sitekey="6Le-...", url="https://example.com")["code"]
|
|
352
|
+
|
|
353
|
+
from browsa.captcha.compat import use_with_anticaptcha # anticaptchaofficial: its requests go to Browsa
|
|
354
|
+
use_with_anticaptcha()
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
CapSolver (`capsolver.api_base = ...`) and CapMonster (`ClientOptions(service_url=...)`) take a base URL as they are.
|
|
358
|
+
|
|
262
359
|
## Docs
|
|
263
360
|
|
|
264
361
|
- API reference: <https://browsa.io/docs>
|
|
@@ -25,14 +25,17 @@ from browsa import Client
|
|
|
25
25
|
c = Client(api_key="agt_live_...")
|
|
26
26
|
job = c.run_task(
|
|
27
27
|
task="Go to news.ycombinator.com and return the top story title.",
|
|
28
|
-
llm="
|
|
29
|
-
|
|
28
|
+
llm="browsa",
|
|
29
|
+
on_progress=lambda j: j.live_url and print("watch live:", j.live_url),
|
|
30
30
|
)
|
|
31
|
-
print(job.final_result)
|
|
32
|
-
print("watch live:", job.live_url)
|
|
31
|
+
print(job.outcome, job.final_result)
|
|
33
32
|
```
|
|
34
33
|
|
|
35
|
-
That runs
|
|
34
|
+
That runs Phantom, our own browser, in a temporary cloud browser, driven by Browsa's hosted model: no LLM key needed. To use your own model instead, pass `llm="anthropic:claude-sonnet-5-5"` with `llm_api_key`, or save the key once (below).
|
|
35
|
+
|
|
36
|
+
`job.status` says the run ended; `job.outcome` says how. `outcome == "failed"` with `status == "completed"` means the agent finished but could not do the task, and `final_result` says what stopped it.
|
|
37
|
+
|
|
38
|
+
`live_url` is a Phantom Live link to watch the browser. It exists only while the task runs (so read it in `on_progress` or from `create_task`), and each link opens once.
|
|
36
39
|
|
|
37
40
|
## Saved LLM keys
|
|
38
41
|
|
|
@@ -102,6 +105,46 @@ print(job.llm_cost_usd) # None for hosted runs
|
|
|
102
105
|
|
|
103
106
|
A finished job has `usage` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `requests`), `llm_cost_usd`, `llm_tier` and `reasoning` (the level that was applied). `llm_cost_usd` is an estimate from public list prices for runs with your own key; it is `None` when unknown and always `None` for hosted runs, which are paid in credits. All four are `None` on jobs that do not have them, such as jobs run before these fields existed.
|
|
104
107
|
|
|
108
|
+
## Robots
|
|
109
|
+
|
|
110
|
+
A robot is a browser job you set up once: record a task, then run it on rows of input, on demand, on a schedule or from the API. Runs replay the recording on Phantom with no model.
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
BOOK = "https://books.toscrape.com/catalogue"
|
|
114
|
+
|
|
115
|
+
# 1. Record a task once
|
|
116
|
+
job = c.run_task(
|
|
117
|
+
task="Open the product page and return title, price and in_stock",
|
|
118
|
+
llm="browsa",
|
|
119
|
+
initial_url=f"{BOOK}/sharp-objects_997/index.html",
|
|
120
|
+
record_recipe=True,
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
# 2. Save it as a robot
|
|
124
|
+
robot = c.robots.create(
|
|
125
|
+
name="Book prices",
|
|
126
|
+
from_job_id=job.id,
|
|
127
|
+
inputs=[{"url": f"{BOOK}/sharp-objects_997/index.html"}, {"url": f"{BOOK}/soumission_998/index.html"}],
|
|
128
|
+
schedule={"interval_seconds": 86400, "at": "09:00", "tz": "UTC"},
|
|
129
|
+
monitors=[{"field": "price", "op": "changed"}],
|
|
130
|
+
settings={"proxy": {"network": "datacenter"}},
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
# 3. Run it and read the rows
|
|
134
|
+
run = c.robot_runs.wait(c.robots.run(robot.id).id)
|
|
135
|
+
for r in run.rows or []:
|
|
136
|
+
print(r.row, r.status, r.output or r.error_code)
|
|
137
|
+
csv_text = c.robot_runs.export(run.id) # or format="json"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
| | |
|
|
141
|
+
|---|---|
|
|
142
|
+
| Price | `robot.health.price_credits` per successful row, the same as the agent task. Failed rows are free. |
|
|
143
|
+
| Settings | `model` (records and repairs), `proxy` (Browsa's network: datacenter 5, residential 50 credits/GB; or a saved `proxy_id`, free), `browser` (`os`, `screen`). Unset is Auto. |
|
|
144
|
+
| More | `list`, `get`, `update`, `delete`, `pause`, `resume`, `runs`, `alerts`, `mark_alerts_read`. `AsyncClient` has the same under `await`. Recipes alone: `create_recipe`, `run_recipe`, `get_recipe_run`. |
|
|
145
|
+
|
|
146
|
+
Guide: <https://browsa.io/guides/robots>.
|
|
147
|
+
|
|
105
148
|
## Async
|
|
106
149
|
|
|
107
150
|
```python
|
|
@@ -147,7 +190,8 @@ if not ok:
|
|
|
147
190
|
| Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
|
|
148
191
|
| Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
|
|
149
192
|
| Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
|
|
150
|
-
| Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc
|
|
193
|
+
| Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, `TimeoutError`, etc.; every one is a `BrowsaError` |
|
|
194
|
+
| Typed | Ships `py.typed`; works with `mypy --strict` and pyright |
|
|
151
195
|
| `X-Request-Id` propagation | Every error carries the server's request id |
|
|
152
196
|
| Zero deps | Single wheel, audit-friendly, no transitive surface |
|
|
153
197
|
|
|
@@ -170,7 +214,7 @@ job = c.run_task(
|
|
|
170
214
|
|
|
171
215
|
### Interactive (input_required) tasks
|
|
172
216
|
|
|
173
|
-
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
|
|
217
|
+
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond. Hosted tasks solve reCAPTCHA v2 image grids (3 x 3, 4 x 4 and reloading tiles), image-text captchas, GeeTest slide puzzles (v3 and v4) and AWS WAF captchas in the browser's own session on workspaces that have bought a pack (fair use applies); the types and measured pass rates are at https://browsa.io/captcha. A type that is not supported yet, or a workspace on free credits only, may still need you here. Respond like this:
|
|
174
218
|
|
|
175
219
|
```python
|
|
176
220
|
job = c.create_task(task="...", llm="...", llm_api_key="...")
|
|
@@ -186,7 +230,7 @@ while not job.is_terminal:
|
|
|
186
230
|
Start a task with `create_session` and the browser stays up after it ends (15 minutes by default, `browser_ttl_seconds` up to 3600), so you can send follow-ups that continue on the same page. A follow-up pays no new browser, only the task's base and step credits.
|
|
187
231
|
|
|
188
232
|
```python
|
|
189
|
-
s = c.create_session("Go to example.com and return the
|
|
233
|
+
s = c.create_session("Go to example.com and return the page title.", llm="browsa")
|
|
190
234
|
first = c.wait_for_job(s.id)
|
|
191
235
|
print(first.final_result)
|
|
192
236
|
|
|
@@ -228,6 +272,58 @@ c.act(b["id"], "click", role="button", name="Sign in")
|
|
|
228
272
|
|
|
229
273
|
`status` is `ok`, `failed`, `blocked`, `challenge` or `stale`; none of them raises. `stale` means the ids came from a view the server no longer has (`ids_reset` is true): nothing was done and `text` carries a new view. Both calls are free. Format and actions: <https://browsa.io/docs#agents-observe>.
|
|
230
274
|
|
|
275
|
+
### Downloads and Phantom Live
|
|
276
|
+
|
|
277
|
+
Files a browser downloads are kept with the browser, not on your machine, so Playwright's `download.save_as()` cannot reach them. List and fetch them through the API before you stop the browser:
|
|
278
|
+
|
|
279
|
+
```python
|
|
280
|
+
files = c.list_downloads(b["id"]) # [{"name", "size", "modified_at"}]
|
|
281
|
+
data = c.download_file(b["id"], files[0]["name"]) # bytes
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
With Playwright the name is the last part of `download.path()`.
|
|
285
|
+
|
|
286
|
+
`create_live_link` gives a link that shows a running browser in any web browser, to watch or to take over:
|
|
287
|
+
|
|
288
|
+
```python
|
|
289
|
+
link = c.create_live_link(b["id"], scope="control", ttl_seconds=600)
|
|
290
|
+
print(link["live_url"]) # opens once; make one per person
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
`scope` is `"view"` (default) or `"control"`. Both calls are free.
|
|
294
|
+
|
|
295
|
+
## Captcha solving
|
|
296
|
+
|
|
297
|
+
`browsa.captcha` is a client for Browsa's captcha API: `createTask`, `getTaskResult` and `getBalance` in the format CapSolver, Anti-Captcha, CapMonster and 2Captcha's v2 API share. Same key and credits as the browser API. Failed and unsolvable tasks are not charged. Measured pass rates per type: <https://browsa.io/captcha>.
|
|
298
|
+
|
|
299
|
+
```python
|
|
300
|
+
from browsa.captcha import CaptchaClient, CaptchaError, tasks
|
|
301
|
+
|
|
302
|
+
cap = CaptchaClient() # BROWSA_API_KEY; https://captcha.browsa.io (or BROWSA_CAPTCHA_URL)
|
|
303
|
+
sol = cap.solve(tasks.recaptcha_v3("https://example.com/login", "6Lc...", page_action="login"))
|
|
304
|
+
token = sol["gRecaptchaResponse"] # sol.task_id is the task id
|
|
305
|
+
|
|
306
|
+
text = cap.solve(tasks.image_to_text(open("captcha.png", "rb").read()))["text"]
|
|
307
|
+
print(cap.get_balance()) # credits
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Builders: `image_to_text`, `recaptcha_v2`, `recaptcha_v3`, `turnstile`, `recaptcha_v2_classification` (and `aws_waf_classification`, `slider`). Each takes `proxy=` (a URL string or `{"type", "host", "port", "username", "password"}`); without one the proxyless type is used. `AsyncCaptchaClient` has the same methods.
|
|
311
|
+
|
|
312
|
+
A task copied from code for another service works as it is: `RecaptchaV2TaskProxyless`, `TurnstileTask`, `NoCaptchaTaskProxyless` and the like are sent under Browsa's names. Errors raise `CaptchaError` with the API's `code` (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_ZERO_BALANCE`, ...).
|
|
313
|
+
|
|
314
|
+
Coming from a library that cannot be pointed at another server:
|
|
315
|
+
|
|
316
|
+
```python
|
|
317
|
+
from browsa.captcha.compat import TwoCaptcha # instead of: from twocaptcha import TwoCaptcha
|
|
318
|
+
solver = TwoCaptcha("agt_live_...")
|
|
319
|
+
solver.recaptcha(sitekey="6Le-...", url="https://example.com")["code"]
|
|
320
|
+
|
|
321
|
+
from browsa.captcha.compat import use_with_anticaptcha # anticaptchaofficial: its requests go to Browsa
|
|
322
|
+
use_with_anticaptcha()
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
CapSolver (`capsolver.api_base = ...`) and CapMonster (`ClientOptions(service_url=...)`) take a base URL as they are.
|
|
326
|
+
|
|
231
327
|
## Docs
|
|
232
328
|
|
|
233
329
|
- API reference: <https://browsa.io/docs>
|
|
@@ -7,30 +7,30 @@ Quickstart:
|
|
|
7
7
|
|
|
8
8
|
client = Client(api_key="agt_live_...")
|
|
9
9
|
|
|
10
|
-
# Run a task
|
|
10
|
+
# Run a task and wait for it (hosted model: no LLM key needed)
|
|
11
11
|
job = client.run_task(
|
|
12
12
|
task="Go to news.ycombinator.com and return the top story title.",
|
|
13
|
-
llm="
|
|
14
|
-
llm_api_key="sk-ant-...",
|
|
13
|
+
llm="browsa",
|
|
15
14
|
)
|
|
16
|
-
print(job.final_result)
|
|
17
|
-
print(f"Live stream: {job.live_url}")
|
|
15
|
+
print(job.outcome, job.final_result)
|
|
18
16
|
|
|
19
|
-
|
|
20
|
-
|
|
17
|
+
job.status says the run ended; job.outcome says how ("failed" with status
|
|
18
|
+
"completed": the agent finished but could not do the task).
|
|
21
19
|
|
|
22
20
|
For async usage:
|
|
23
21
|
|
|
24
22
|
from browsa import AsyncClient
|
|
25
23
|
|
|
26
24
|
async with AsyncClient(api_key="agt_live_...") as c:
|
|
27
|
-
job = await c.run_task(task="...", llm="
|
|
25
|
+
job = await c.run_task(task="...", llm="browsa")
|
|
28
26
|
|
|
29
27
|
For webhooks see browsa.webhooks.verify_signature.
|
|
30
28
|
"""
|
|
31
29
|
from .client import Client, AsyncClient
|
|
32
30
|
from .types import (
|
|
33
31
|
HostedModel, Job, JobFile, JobStatus, LLMKey, Models, OwnKeyModels, Schedule,
|
|
32
|
+
Recipe, RecipeRun, RecipeVersion,
|
|
33
|
+
Robot, RobotAlert, RobotHealth, RobotRun, RobotRunRow,
|
|
34
34
|
Session, SessionBrowser, SessionTurn, Usage, Webhook,
|
|
35
35
|
NetworkProxy, Proxy, ProxyConfig, ProxyNetwork, ProxyNetworkTier,
|
|
36
36
|
)
|
|
@@ -58,6 +58,14 @@ __all__ = [
|
|
|
58
58
|
"Models",
|
|
59
59
|
"OwnKeyModels",
|
|
60
60
|
"Schedule",
|
|
61
|
+
"Recipe",
|
|
62
|
+
"RecipeRun",
|
|
63
|
+
"RecipeVersion",
|
|
64
|
+
"Robot",
|
|
65
|
+
"RobotAlert",
|
|
66
|
+
"RobotHealth",
|
|
67
|
+
"RobotRun",
|
|
68
|
+
"RobotRunRow",
|
|
61
69
|
"Session",
|
|
62
70
|
"SessionBrowser",
|
|
63
71
|
"SessionTurn",
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.5.0"
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""Browsa's captcha-solving API, in the createTask / getTaskResult / getBalance format that
|
|
2
|
+
CapSolver, Anti-Captcha, CapMonster and 2Captcha's v2 API share. Same key and credits as the
|
|
3
|
+
browser API.
|
|
4
|
+
|
|
5
|
+
from browsa.captcha import CaptchaClient, tasks
|
|
6
|
+
|
|
7
|
+
cap = CaptchaClient() # BROWSA_API_KEY
|
|
8
|
+
sol = cap.solve(tasks.recaptcha_v3("https://example.com/login", "6Lc...", page_action="login"))
|
|
9
|
+
token = sol["gRecaptchaResponse"]
|
|
10
|
+
|
|
11
|
+
Coming from another service: ``browsa.captcha.compat`` (2Captcha and Anti-Captcha libraries).
|
|
12
|
+
Measured pass rates per type: https://browsa.io/captcha
|
|
13
|
+
"""
|
|
14
|
+
from . import compat, tasks
|
|
15
|
+
from ._client import (
|
|
16
|
+
DEFAULT_CAPTCHA_URL,
|
|
17
|
+
AsyncCaptchaClient,
|
|
18
|
+
CaptchaClient,
|
|
19
|
+
CaptchaError,
|
|
20
|
+
CaptchaTimeoutError,
|
|
21
|
+
Solution,
|
|
22
|
+
)
|
|
23
|
+
from .tasks import TASK_TYPES, normalize_task
|
|
24
|
+
|
|
25
|
+
__all__ = [
|
|
26
|
+
"CaptchaClient", "AsyncCaptchaClient", "CaptchaError", "CaptchaTimeoutError", "Solution",
|
|
27
|
+
"DEFAULT_CAPTCHA_URL", "TASK_TYPES", "normalize_task", "tasks", "compat",
|
|
28
|
+
]
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
"""Client for Browsa's captcha API: createTask, getTaskResult, getBalance.
|
|
2
|
+
|
|
3
|
+
Every answer is HTTP 200 with ``errorId`` 0 (ok) or 1 (error, with ``errorCode``), as at
|
|
4
|
+
CapSolver, Anti-Captcha and CapMonster. Recognition tasks are answered inside createTask;
|
|
5
|
+
token tasks return a ``taskId`` to poll. Stdlib only, like the rest of the SDK.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import asyncio
|
|
10
|
+
import json
|
|
11
|
+
import os
|
|
12
|
+
import socket
|
|
13
|
+
import time
|
|
14
|
+
import urllib.error
|
|
15
|
+
import urllib.request
|
|
16
|
+
from typing import Any, Callable, Dict, Mapping, Optional
|
|
17
|
+
|
|
18
|
+
from .. import errors
|
|
19
|
+
from .._version import __version__
|
|
20
|
+
from .tasks import normalize_task
|
|
21
|
+
|
|
22
|
+
DEFAULT_CAPTCHA_URL = "https://captcha.browsa.io"
|
|
23
|
+
DEFAULT_TIMEOUT = 30.0 # one HTTP request
|
|
24
|
+
DEFAULT_SOLVE_TIMEOUT = 180.0 # createTask to a ready token (a reCAPTCHA v2 puzzle can take 2 minutes)
|
|
25
|
+
DEFAULT_POLL_INTERVAL = 3.0
|
|
26
|
+
USER_AGENT = f"browsa-python/{__version__} (captcha)"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class CaptchaError(errors.BrowsaError):
|
|
30
|
+
"""The API answered ``errorId`` 1. ``code`` is the API's ``errorCode``
|
|
31
|
+
(``ERROR_CAPTCHA_UNSOLVABLE``, ``ERROR_ZERO_BALANCE``, ...); ``task_id`` is set when the
|
|
32
|
+
task exists. Failed and unsolvable tasks are not charged."""
|
|
33
|
+
|
|
34
|
+
def __init__(self, message: str, *, code: Optional[str] = None, task_id: Optional[str] = None,
|
|
35
|
+
status: Optional[int] = None, body: Any = None) -> None:
|
|
36
|
+
super().__init__(message, code=code, status=status, body=body)
|
|
37
|
+
self.task_id = task_id
|
|
38
|
+
self.description = message
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class CaptchaTimeoutError(CaptchaError, errors.TimeoutError):
|
|
42
|
+
"""Local: ``solve`` gave up waiting. The task may still finish; it is charged only if solved."""
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class Solution(dict): # type: ignore[type-arg]
|
|
46
|
+
"""The task's ``solution`` object, with the task id as ``.task_id``."""
|
|
47
|
+
|
|
48
|
+
task_id: str = ""
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _raise_for(body: Any, status: int) -> Dict[str, Any]:
|
|
52
|
+
if not isinstance(body, dict) or "errorId" not in body:
|
|
53
|
+
raise CaptchaError(f"unexpected answer (HTTP {status})", code=f"HTTP_{status}", status=status, body=body)
|
|
54
|
+
if body.get("errorId"):
|
|
55
|
+
raise CaptchaError(body.get("errorDescription") or body.get("errorCode") or "error",
|
|
56
|
+
code=body.get("errorCode") or None, task_id=body.get("taskId"), status=status, body=body)
|
|
57
|
+
return body
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class CaptchaClient:
|
|
61
|
+
"""Sync client.
|
|
62
|
+
|
|
63
|
+
from browsa.captcha import CaptchaClient, tasks
|
|
64
|
+
cap = CaptchaClient() # BROWSA_API_KEY from the environment
|
|
65
|
+
sol = cap.solve(tasks.turnstile("https://example.com", "0x4AAAA..."))
|
|
66
|
+
print(sol["token"])
|
|
67
|
+
|
|
68
|
+
Args:
|
|
69
|
+
api_key: your Browsa API key (the same key and credits as the browser API);
|
|
70
|
+
default ``BROWSA_API_KEY``.
|
|
71
|
+
base_url: default ``BROWSA_CAPTCHA_URL`` or ``https://captcha.browsa.io``.
|
|
72
|
+
normalize: map other services' task type names to Browsa's (default on).
|
|
73
|
+
opener: replaces ``urllib.request.urlopen`` (tests).
|
|
74
|
+
"""
|
|
75
|
+
|
|
76
|
+
def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None,
|
|
77
|
+
timeout: float = DEFAULT_TIMEOUT, poll_interval: float = DEFAULT_POLL_INTERVAL,
|
|
78
|
+
normalize: bool = True, opener: Optional[Callable[..., Any]] = None) -> None:
|
|
79
|
+
key = api_key or os.environ.get("BROWSA_API_KEY") or ""
|
|
80
|
+
if not key:
|
|
81
|
+
raise ValueError("api_key is required (or set BROWSA_API_KEY)")
|
|
82
|
+
self.api_key = key
|
|
83
|
+
self.base_url = (base_url or os.environ.get("BROWSA_CAPTCHA_URL") or DEFAULT_CAPTCHA_URL).rstrip("/")
|
|
84
|
+
self.timeout = timeout
|
|
85
|
+
self.poll_interval = poll_interval
|
|
86
|
+
self.normalize = normalize
|
|
87
|
+
self._open = opener or urllib.request.urlopen
|
|
88
|
+
|
|
89
|
+
# ── raw methods ──────────────────────────────────────────────────────
|
|
90
|
+
|
|
91
|
+
def call(self, method: str, payload: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
|
|
92
|
+
"""POST ``/{method}`` with ``clientKey`` added; returns the answer, raises CaptchaError."""
|
|
93
|
+
body = {"clientKey": self.api_key, **(payload or {})}
|
|
94
|
+
req = urllib.request.Request(
|
|
95
|
+
f"{self.base_url}/{method}", method="POST", data=json.dumps(body).encode("utf-8"),
|
|
96
|
+
headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": USER_AGENT},
|
|
97
|
+
)
|
|
98
|
+
try:
|
|
99
|
+
with self._open(req, timeout=self.timeout) as resp:
|
|
100
|
+
status, raw = getattr(resp, "status", 200), resp.read()
|
|
101
|
+
except urllib.error.HTTPError as e:
|
|
102
|
+
status, raw = e.code, e.read()
|
|
103
|
+
except urllib.error.URLError as e:
|
|
104
|
+
if isinstance(e.reason, (socket.timeout, TimeoutError)):
|
|
105
|
+
raise errors.TimeoutError(f"request timed out after {self.timeout}s") from e
|
|
106
|
+
raise errors.BrowsaError(f"network error: {e}") from e
|
|
107
|
+
except (socket.timeout, TimeoutError) as e:
|
|
108
|
+
raise errors.TimeoutError(f"request timed out after {self.timeout}s") from e
|
|
109
|
+
except OSError as e:
|
|
110
|
+
raise errors.BrowsaError(f"network error: {e}") from e
|
|
111
|
+
try:
|
|
112
|
+
parsed = json.loads(raw) if raw else None
|
|
113
|
+
except ValueError:
|
|
114
|
+
parsed = None
|
|
115
|
+
return _raise_for(parsed, status)
|
|
116
|
+
|
|
117
|
+
def create_task(self, task: Mapping[str, Any]) -> Dict[str, Any]:
|
|
118
|
+
"""``{"taskId", "status": "ready", "solution"}`` for recognition, ``{"taskId"}`` for tokens."""
|
|
119
|
+
return self.call("createTask", {"task": normalize_task(task) if self.normalize else dict(task)})
|
|
120
|
+
|
|
121
|
+
def get_task_result(self, task_id: str) -> Dict[str, Any]:
|
|
122
|
+
"""``{"status": "processing"}`` or ``{"status": "ready", "solution"}``; a failed task raises."""
|
|
123
|
+
return self.call("getTaskResult", {"taskId": task_id})
|
|
124
|
+
|
|
125
|
+
def get_balance(self) -> float:
|
|
126
|
+
"""Balance: credits with a Browsa key."""
|
|
127
|
+
return float(self.call("getBalance").get("balance") or 0.0)
|
|
128
|
+
|
|
129
|
+
# ── create and wait ──────────────────────────────────────────────────
|
|
130
|
+
|
|
131
|
+
def solve(self, task: Mapping[str, Any], *, timeout: float = DEFAULT_SOLVE_TIMEOUT,
|
|
132
|
+
poll_interval: Optional[float] = None) -> Solution:
|
|
133
|
+
"""Create the task and wait for its solution."""
|
|
134
|
+
created = self.create_task(task)
|
|
135
|
+
tid = str(created.get("taskId") or "")
|
|
136
|
+
if created.get("status") == "ready" and created.get("solution") is not None:
|
|
137
|
+
return _solution(created, tid)
|
|
138
|
+
if not tid:
|
|
139
|
+
raise CaptchaError("createTask returned no taskId", code="ERROR_NO_TASK_ID", body=created)
|
|
140
|
+
interval = self.poll_interval if poll_interval is None else poll_interval
|
|
141
|
+
deadline = time.monotonic() + timeout
|
|
142
|
+
while True:
|
|
143
|
+
time.sleep(min(interval, max(0.0, deadline - time.monotonic())))
|
|
144
|
+
r = self.get_task_result(tid)
|
|
145
|
+
if r.get("status") == "ready":
|
|
146
|
+
return _solution(r, tid)
|
|
147
|
+
if time.monotonic() >= deadline:
|
|
148
|
+
raise CaptchaTimeoutError(f"no solution after {timeout:.0f}s", code="TIMEOUT", task_id=tid)
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _solution(body: Mapping[str, Any], tid: str) -> Solution:
|
|
152
|
+
s = Solution(body.get("solution") or {})
|
|
153
|
+
s.task_id = tid
|
|
154
|
+
return s
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
class AsyncCaptchaClient:
|
|
158
|
+
"""Async client: the sync client on a worker thread (``asyncio.to_thread``), like ``AsyncClient``."""
|
|
159
|
+
|
|
160
|
+
def __init__(self, api_key: Optional[str] = None, **kwargs: Any) -> None:
|
|
161
|
+
self._sync = CaptchaClient(api_key, **kwargs)
|
|
162
|
+
|
|
163
|
+
async def __aenter__(self) -> "AsyncCaptchaClient":
|
|
164
|
+
return self
|
|
165
|
+
|
|
166
|
+
async def __aexit__(self, *exc: Any) -> None:
|
|
167
|
+
return None
|
|
168
|
+
|
|
169
|
+
async def create_task(self, task: Mapping[str, Any]) -> Dict[str, Any]:
|
|
170
|
+
return await asyncio.to_thread(self._sync.create_task, task)
|
|
171
|
+
|
|
172
|
+
async def get_task_result(self, task_id: str) -> Dict[str, Any]:
|
|
173
|
+
return await asyncio.to_thread(self._sync.get_task_result, task_id)
|
|
174
|
+
|
|
175
|
+
async def get_balance(self) -> float:
|
|
176
|
+
return await asyncio.to_thread(self._sync.get_balance)
|
|
177
|
+
|
|
178
|
+
async def solve(self, task: Mapping[str, Any], *, timeout: float = DEFAULT_SOLVE_TIMEOUT,
|
|
179
|
+
poll_interval: Optional[float] = None) -> Solution:
|
|
180
|
+
created = await self.create_task(task)
|
|
181
|
+
tid = str(created.get("taskId") or "")
|
|
182
|
+
if created.get("status") == "ready" and created.get("solution") is not None:
|
|
183
|
+
return _solution(created, tid)
|
|
184
|
+
if not tid:
|
|
185
|
+
raise CaptchaError("createTask returned no taskId", code="ERROR_NO_TASK_ID", body=created)
|
|
186
|
+
interval = self._sync.poll_interval if poll_interval is None else poll_interval
|
|
187
|
+
deadline = time.monotonic() + timeout
|
|
188
|
+
while True:
|
|
189
|
+
await asyncio.sleep(min(interval, max(0.0, deadline - time.monotonic())))
|
|
190
|
+
r = await self.get_task_result(tid)
|
|
191
|
+
if r.get("status") == "ready":
|
|
192
|
+
return _solution(r, tid)
|
|
193
|
+
if time.monotonic() >= deadline:
|
|
194
|
+
raise CaptchaTimeoutError(f"no solution after {timeout:.0f}s", code="TIMEOUT", task_id=tid)
|