browsa 0.3.1__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.1
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
@@ -63,7 +63,7 @@ job = c.run_task(
63
63
  print(job.outcome, job.final_result)
64
64
  ```
65
65
 
66
- That runs Phantom, our Chromium build, 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).
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
67
 
68
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
69
 
@@ -137,6 +137,46 @@ print(job.llm_cost_usd) # None for hosted runs
137
137
 
138
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.
139
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
+
140
180
  ## Async
141
181
 
142
182
  ```python
@@ -206,7 +246,7 @@ job = c.run_task(
206
246
 
207
247
  ### Interactive (input_required) tasks
208
248
 
209
- 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:
210
250
 
211
251
  ```python
212
252
  job = c.create_task(task="...", llm="...", llm_api_key="...")
@@ -222,7 +262,7 @@ while not job.is_terminal:
222
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.
223
263
 
224
264
  ```python
225
- 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")
226
266
  first = c.wait_for_job(s.id)
227
267
  print(first.final_result)
228
268
 
@@ -284,6 +324,38 @@ print(link["live_url"]) # opens once; make one per p
284
324
 
285
325
  `scope` is `"view"` (default) or `"control"`. Both calls are free.
286
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
+
287
359
  ## Docs
288
360
 
289
361
  - API reference: <https://browsa.io/docs>
@@ -31,7 +31,7 @@ job = c.run_task(
31
31
  print(job.outcome, job.final_result)
32
32
  ```
33
33
 
34
- That runs Phantom, our Chromium build, 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).
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
35
 
36
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
37
 
@@ -105,6 +105,46 @@ print(job.llm_cost_usd) # None for hosted runs
105
105
 
106
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.
107
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
+
108
148
  ## Async
109
149
 
110
150
  ```python
@@ -174,7 +214,7 @@ job = c.run_task(
174
214
 
175
215
  ### Interactive (input_required) tasks
176
216
 
177
- 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:
178
218
 
179
219
  ```python
180
220
  job = c.create_task(task="...", llm="...", llm_api_key="...")
@@ -190,7 +230,7 @@ while not job.is_terminal:
190
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.
191
231
 
192
232
  ```python
193
- 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")
194
234
  first = c.wait_for_job(s.id)
195
235
  print(first.final_result)
196
236
 
@@ -252,6 +292,38 @@ print(link["live_url"]) # opens once; make one per p
252
292
 
253
293
  `scope` is `"view"` (default) or `"control"`. Both calls are free.
254
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
+
255
327
  ## Docs
256
328
 
257
329
  - API reference: <https://browsa.io/docs>
@@ -29,6 +29,8 @@ For webhooks see browsa.webhooks.verify_signature.
29
29
  from .client import Client, AsyncClient
30
30
  from .types import (
31
31
  HostedModel, Job, JobFile, JobStatus, LLMKey, Models, OwnKeyModels, Schedule,
32
+ Recipe, RecipeRun, RecipeVersion,
33
+ Robot, RobotAlert, RobotHealth, RobotRun, RobotRunRow,
32
34
  Session, SessionBrowser, SessionTurn, Usage, Webhook,
33
35
  NetworkProxy, Proxy, ProxyConfig, ProxyNetwork, ProxyNetworkTier,
34
36
  )
@@ -56,6 +58,14 @@ __all__ = [
56
58
  "Models",
57
59
  "OwnKeyModels",
58
60
  "Schedule",
61
+ "Recipe",
62
+ "RecipeRun",
63
+ "RecipeVersion",
64
+ "Robot",
65
+ "RobotAlert",
66
+ "RobotHealth",
67
+ "RobotRun",
68
+ "RobotRunRow",
59
69
  "Session",
60
70
  "SessionBrowser",
61
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)
@@ -0,0 +1,165 @@
1
+ """Shims for the client libraries that cannot be pointed at another server as they are.
2
+
3
+ - 2Captcha (``2captcha-python``) speaks 2Captcha's own ``in.php`` / ``res.php`` protocol.
4
+ ``TwoCaptcha`` here has the same constructor and the same ``normal``, ``recaptcha``,
5
+ ``turnstile`` and ``balance`` methods, returning ``{"captchaId", "code"}``; change the import.
6
+ - Anti-Captcha (``anticaptchaofficial``) has its host written in the code.
7
+ ``use_with_anticaptcha()`` sends its requests to Browsa instead; the rest of your code stays.
8
+
9
+ CapSolver (``capsolver.api_base``) and CapMonster (``ClientOptions(service_url=...)``) take a
10
+ base URL and need nothing from here.
11
+ """
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ import os
16
+ import urllib.error
17
+ import urllib.request
18
+ from typing import Any, Callable, Dict, Mapping, Optional
19
+
20
+ from ._client import USER_AGENT, CaptchaClient, CaptchaError, CaptchaTimeoutError
21
+ from .tasks import normalize_task, recaptcha_v2, recaptcha_v3, turnstile as turnstile_task, image_to_text
22
+
23
+ # ── 2Captcha ─────────────────────────────────────────────────────────────
24
+
25
+ ApiException = CaptchaError # 2captcha-python's names, so `except` clauses keep working
26
+ TimeoutException = CaptchaTimeoutError
27
+
28
+
29
+ class ValidationException(CaptchaError):
30
+ """A required argument is missing (2captcha-python raises this name too)."""
31
+
32
+
33
+ def _twocaptcha_proxy(proxy: Any) -> Optional[str]:
34
+ """2Captcha's ``{"type": "HTTPS", "uri": "login:password@1.2.3.4:3128"}`` -> ``https://login:...``."""
35
+ if not proxy:
36
+ return None
37
+ if isinstance(proxy, str):
38
+ return proxy if "://" in proxy else "http://" + proxy
39
+ typ = str(proxy.get("type") or "http").lower()
40
+ return f"{typ}://{proxy['uri']}"
41
+
42
+
43
+ class TwoCaptcha:
44
+ """Drop-in for ``twocaptcha.TwoCaptcha`` on the task types Browsa solves.
45
+
46
+ # before: from twocaptcha import TwoCaptcha
47
+ from browsa.captcha.compat import TwoCaptcha
48
+ solver = TwoCaptcha("agt_live_...")
49
+ result = solver.recaptcha(sitekey="6Le-...", url="https://example.com/login")
50
+ token = result["code"]
51
+
52
+ ``softId``, ``callback`` and ``server`` (unless it is a Browsa URL) are accepted and ignored.
53
+ """
54
+
55
+ def __init__(self, apiKey: str, softId: Optional[int] = None, callback: Optional[str] = None,
56
+ defaultTimeout: int = 120, recaptchaTimeout: int = 600, pollingInterval: int = 10,
57
+ server: Optional[str] = None, extendedResponse: Optional[bool] = None,
58
+ *, base_url: Optional[str] = None, client: Optional[CaptchaClient] = None) -> None:
59
+ if server and "browsa" in server:
60
+ base_url = base_url or (server if "://" in server else "https://" + server)
61
+ self.API_KEY = apiKey
62
+ self.default_timeout = defaultTimeout
63
+ self.recaptcha_timeout = recaptchaTimeout
64
+ self.polling_interval = pollingInterval
65
+ self.extended_response = bool(extendedResponse)
66
+ self._client = client or CaptchaClient(apiKey, base_url=base_url, poll_interval=min(pollingInterval, 5))
67
+
68
+ def _run(self, task: Mapping[str, Any], timeout: float, pick: Callable[[Mapping[str, Any]], Any]) -> Dict[str, Any]:
69
+ sol = self._client.solve(task, timeout=timeout)
70
+ out: Dict[str, Any] = {"captchaId": sol.task_id, "code": pick(sol)}
71
+ if self.extended_response:
72
+ out["solution"] = dict(sol)
73
+ return out
74
+
75
+ def normal(self, file: Any, **kwargs: Any) -> Dict[str, Any]:
76
+ """Image text. ``file``: a path, a base64 string, or bytes."""
77
+ if isinstance(file, (bytes, bytearray)):
78
+ body: Any = bytes(file)
79
+ elif isinstance(file, str) and os.path.isfile(file):
80
+ with open(file, "rb") as f:
81
+ body = f.read()
82
+ elif isinstance(file, str) and file:
83
+ body = file
84
+ else:
85
+ raise ValidationException("file must be a path, a base64 string or bytes", code="ERROR_INVALID_TASK_DATA")
86
+ sol_text = lambda s: s.get("text") if "text" in s else ",".join(s.get("answers") or []) # noqa: E731
87
+ return self._run(image_to_text(body), kwargs.get("timeout", self.default_timeout), sol_text)
88
+
89
+ def recaptcha(self, sitekey: str, url: str, version: str = "v2", enterprise: int = 0, **kwargs: Any) -> Dict[str, Any]:
90
+ """reCAPTCHA v2 or v3 (``version="v3"``, ``action``, ``score``), ``invisible=1``, ``enterprise=1``."""
91
+ if not sitekey or not url:
92
+ raise ValidationException("sitekey and url are required", code="ERROR_INVALID_TASK_DATA")
93
+ proxy = _twocaptcha_proxy(kwargs.get("proxy"))
94
+ if str(version).lower() == "v3":
95
+ task = recaptcha_v3(url, sitekey, page_action=kwargs.get("action"), enterprise=bool(enterprise),
96
+ min_score=kwargs.get("score") or kwargs.get("min_score"), proxy=proxy)
97
+ else:
98
+ task = recaptcha_v2(url, sitekey, invisible=bool(int(kwargs.get("invisible") or 0)),
99
+ enterprise=bool(enterprise), api_domain=kwargs.get("domain"), proxy=proxy)
100
+ return self._run(task, kwargs.get("timeout", self.recaptcha_timeout), lambda s: s.get("gRecaptchaResponse"))
101
+
102
+ def turnstile(self, sitekey: str, url: str, **kwargs: Any) -> Dict[str, Any]:
103
+ """Cloudflare Turnstile (``action``, ``data`` = cData)."""
104
+ if not sitekey or not url:
105
+ raise ValidationException("sitekey and url are required", code="ERROR_INVALID_TASK_DATA")
106
+ task = turnstile_task(url, sitekey, action=kwargs.get("action"), cdata=kwargs.get("data"),
107
+ proxy=_twocaptcha_proxy(kwargs.get("proxy")))
108
+ return self._run(task, kwargs.get("timeout", self.default_timeout), lambda s: s.get("token"))
109
+
110
+ def balance(self) -> float:
111
+ return self._client.get_balance()
112
+
113
+
114
+ # ── Anti-Captcha ─────────────────────────────────────────────────────────
115
+
116
+
117
+ def use_with_anticaptcha(base_url: Optional[str] = None, *, opener: Optional[Callable[..., Any]] = None) -> Callable[[], None]:
118
+ """Send ``anticaptchaofficial``'s requests to Browsa. Call once, before solving:
119
+
120
+ from anticaptchaofficial.recaptchav2proxyless import recaptchaV2Proxyless
121
+ from browsa.captcha.compat import use_with_anticaptcha
122
+ use_with_anticaptcha()
123
+ solver = recaptchaV2Proxyless()
124
+ solver.set_key("agt_live_...") # your Browsa key
125
+ ...
126
+
127
+ Task type names are mapped to Browsa's on the way. Returns a function that undoes it.
128
+ """
129
+ from anticaptchaofficial import antinetworking # the caller's own dependency
130
+
131
+ base = (base_url or os.environ.get("BROWSA_CAPTCHA_URL") or "https://captcha.browsa.io").rstrip("/")
132
+ open_ = opener or urllib.request.urlopen
133
+ cls = antinetworking.antiNetworking
134
+ original = cls.make_request
135
+
136
+ def make_request(self: Any, method: str, data: Dict[str, Any]) -> Any:
137
+ self.log("making request to " + method)
138
+ payload = dict(data)
139
+ if method == "createTask" and isinstance(payload.get("task"), dict):
140
+ payload["task"] = normalize_task({k: v for k, v in payload["task"].items() if v is not None})
141
+ req = urllib.request.Request(f"{base}/{method}", method="POST", data=json.dumps(payload).encode("utf-8"),
142
+ headers={"Content-Type": "application/json", "Accept": "application/json",
143
+ "User-Agent": USER_AGENT})
144
+ try:
145
+ with open_(req, timeout=30) as resp:
146
+ return json.loads(resp.read())
147
+ except urllib.error.HTTPError as e:
148
+ try:
149
+ return json.loads(e.read())
150
+ except ValueError:
151
+ self.err_string = f"http_error {e.code}"
152
+ return 0
153
+ except (urllib.error.URLError, OSError, ValueError) as e:
154
+ self.err_string = f"Connection error: {e}"
155
+ return 0
156
+
157
+ cls.make_request = make_request
158
+
159
+ def undo() -> None:
160
+ cls.make_request = original
161
+
162
+ return undo
163
+
164
+
165
+ __all__ = ["TwoCaptcha", "ApiException", "TimeoutException", "ValidationException", "use_with_anticaptcha"]