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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: browsa
3
- Version: 0.3.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="claude-opus-5-5",
60
- llm_api_key="sk-ant-...",
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 a real Chromium fork (Phantom, our real browser) inside an isolated burner session, driven by [browser-use](https://browser-use.com) + Claude Opus. The agent navigates, extracts, and returns. A live noVNC stream URL is available the moment the burner spawns.
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 H1.", llm="browsa")
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="claude-opus-5-5",
29
- llm_api_key="sk-ant-...",
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 a real Chromium fork (Phantom, our real browser) inside an isolated burner session, driven by [browser-use](https://browser-use.com) + Claude Opus. The agent navigates, extracts, and returns. A live noVNC stream URL is available the moment the burner spawns.
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 H1.", llm="browsa")
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 synchronously (blocks until the agent finishes)
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="claude-opus-5-5",
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
- That's it. Five lines of Python to drive a real browser through
20
- an AI agent, get back structured output, and a live noVNC viewer URL.
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="claude-opus-5-5", ...)
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)