browsa 0.1.1__py3-none-any.whl
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/__init__.py +63 -0
- browsa/client.py +752 -0
- browsa/errors.py +100 -0
- browsa/types.py +111 -0
- browsa/webhooks.py +103 -0
- browsa-0.1.1.dist-info/METADATA +160 -0
- browsa-0.1.1.dist-info/RECORD +10 -0
- browsa-0.1.1.dist-info/WHEEL +5 -0
- browsa-0.1.1.dist-info/licenses/LICENSE +21 -0
- browsa-0.1.1.dist-info/top_level.txt +1 -0
browsa/__init__.py
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""
|
|
2
|
+
browsa — anti-detect browsers for AI agents.
|
|
3
|
+
|
|
4
|
+
Quickstart:
|
|
5
|
+
|
|
6
|
+
from browsa import Client
|
|
7
|
+
|
|
8
|
+
client = Client(api_key="agt_live_...")
|
|
9
|
+
|
|
10
|
+
# Run a task synchronously (blocks until the agent finishes)
|
|
11
|
+
job = client.run_task(
|
|
12
|
+
task="Go to news.ycombinator.com and return the top story title.",
|
|
13
|
+
llm="claude-opus-4-7",
|
|
14
|
+
llm_api_key="sk-ant-...",
|
|
15
|
+
)
|
|
16
|
+
print(job.final_result)
|
|
17
|
+
print(f"Live stream: {job.live_url}")
|
|
18
|
+
|
|
19
|
+
That's it. Five lines of Python to drive a real anti-detect browser through
|
|
20
|
+
an AI agent, get back structured output, and a live noVNC viewer URL.
|
|
21
|
+
|
|
22
|
+
For async usage:
|
|
23
|
+
|
|
24
|
+
from browsa import AsyncClient
|
|
25
|
+
|
|
26
|
+
async with AsyncClient(api_key="agt_live_...") as c:
|
|
27
|
+
job = await c.run_task(task="...", llm="claude-opus-4-7", ...)
|
|
28
|
+
|
|
29
|
+
For webhooks see browsa.webhooks.verify_signature.
|
|
30
|
+
"""
|
|
31
|
+
from .client import Client, AsyncClient
|
|
32
|
+
from .types import Job, JobStatus, Webhook
|
|
33
|
+
from .errors import (
|
|
34
|
+
BrowsaError,
|
|
35
|
+
NeoutError, # deprecated alias of BrowsaError — kept for backwards compat
|
|
36
|
+
APIError,
|
|
37
|
+
AuthError,
|
|
38
|
+
RateLimitError,
|
|
39
|
+
InvalidIDError,
|
|
40
|
+
NotFoundError,
|
|
41
|
+
TimeoutError,
|
|
42
|
+
)
|
|
43
|
+
from . import webhooks
|
|
44
|
+
|
|
45
|
+
__version__ = "0.1.0"
|
|
46
|
+
|
|
47
|
+
__all__ = [
|
|
48
|
+
"Client",
|
|
49
|
+
"AsyncClient",
|
|
50
|
+
"Job",
|
|
51
|
+
"JobStatus",
|
|
52
|
+
"Webhook",
|
|
53
|
+
"BrowsaError",
|
|
54
|
+
"NeoutError",
|
|
55
|
+
"APIError",
|
|
56
|
+
"AuthError",
|
|
57
|
+
"RateLimitError",
|
|
58
|
+
"InvalidIDError",
|
|
59
|
+
"NotFoundError",
|
|
60
|
+
"TimeoutError",
|
|
61
|
+
"webhooks",
|
|
62
|
+
"__version__",
|
|
63
|
+
]
|
browsa/client.py
ADDED
|
@@ -0,0 +1,752 @@
|
|
|
1
|
+
"""Sync and async REST clients for browsa.io.
|
|
2
|
+
|
|
3
|
+
Zero third-party deps — uses urllib + asyncio + stdlib json. The SDK ships
|
|
4
|
+
as a single small wheel with no transitive dependency surface, which means
|
|
5
|
+
agencies running it inside locked-down LLM agent environments don't have to
|
|
6
|
+
think about wheelhouse builds, version conflicts, or supply-chain audits.
|
|
7
|
+
|
|
8
|
+
If we ever need streaming we can adopt httpx + sse-starlette gracefully —
|
|
9
|
+
this stays pure-stdlib until then.
|
|
10
|
+
"""
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import asyncio
|
|
14
|
+
import json
|
|
15
|
+
import time
|
|
16
|
+
import urllib.error
|
|
17
|
+
import urllib.parse
|
|
18
|
+
import urllib.request
|
|
19
|
+
from typing import Any, Iterable, Optional
|
|
20
|
+
|
|
21
|
+
from . import errors
|
|
22
|
+
from .types import Job, JobStatus, Webhook
|
|
23
|
+
|
|
24
|
+
DEFAULT_BASE_URL = "https://browsa.io"
|
|
25
|
+
DEFAULT_TIMEOUT = 30.0
|
|
26
|
+
DEFAULT_POLL_INTERVAL = 2.0 # seconds between job-status polls
|
|
27
|
+
USER_AGENT = "browsa-python/0.1.0"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class _Transport:
|
|
31
|
+
"""Internal sync HTTP transport. Splits request → response → error parsing
|
|
32
|
+
so the same logic can be reused by AsyncClient via run_in_executor."""
|
|
33
|
+
|
|
34
|
+
def __init__(self, api_key: str, base_url: str, timeout: float) -> None:
|
|
35
|
+
self.api_key = api_key
|
|
36
|
+
self.base_url = base_url.rstrip("/")
|
|
37
|
+
self.timeout = timeout
|
|
38
|
+
|
|
39
|
+
def request(
|
|
40
|
+
self,
|
|
41
|
+
method: str,
|
|
42
|
+
path: str,
|
|
43
|
+
*,
|
|
44
|
+
body: Any = None,
|
|
45
|
+
query: Optional[dict] = None,
|
|
46
|
+
timeout: Optional[float] = None,
|
|
47
|
+
extra_headers: Optional[dict] = None,
|
|
48
|
+
) -> Any:
|
|
49
|
+
url = f"{self.base_url}{path}"
|
|
50
|
+
if query:
|
|
51
|
+
url = f"{url}?{urllib.parse.urlencode({k: v for k, v in query.items() if v is not None})}"
|
|
52
|
+
|
|
53
|
+
data = None
|
|
54
|
+
headers = {
|
|
55
|
+
"X-API-Key": self.api_key,
|
|
56
|
+
"Accept": "application/json",
|
|
57
|
+
"User-Agent": USER_AGENT,
|
|
58
|
+
}
|
|
59
|
+
if body is not None:
|
|
60
|
+
data = json.dumps(body).encode("utf-8")
|
|
61
|
+
headers["Content-Type"] = "application/json"
|
|
62
|
+
if extra_headers:
|
|
63
|
+
# Caller-provided headers (e.g. Idempotency-Key) take priority
|
|
64
|
+
# but never overwrite auth — silently drop X-API-Key overrides.
|
|
65
|
+
for k, v in extra_headers.items():
|
|
66
|
+
if k.lower() in ("x-api-key", "authorization"):
|
|
67
|
+
continue
|
|
68
|
+
if v is not None:
|
|
69
|
+
headers[k] = str(v)
|
|
70
|
+
|
|
71
|
+
req = urllib.request.Request(url, method=method.upper(), headers=headers, data=data)
|
|
72
|
+
eff_timeout = timeout if timeout is not None else self.timeout
|
|
73
|
+
|
|
74
|
+
try:
|
|
75
|
+
with urllib.request.urlopen(req, timeout=eff_timeout) as resp:
|
|
76
|
+
raw = resp.read()
|
|
77
|
+
ctype = (resp.headers.get("Content-Type") or "").lower()
|
|
78
|
+
if not raw:
|
|
79
|
+
return None
|
|
80
|
+
if "application/json" in ctype:
|
|
81
|
+
return json.loads(raw)
|
|
82
|
+
# Some endpoints (CSV/NDJSON export) return raw bytes.
|
|
83
|
+
return raw
|
|
84
|
+
except urllib.error.HTTPError as e:
|
|
85
|
+
try:
|
|
86
|
+
err_body = json.loads(e.read())
|
|
87
|
+
except Exception:
|
|
88
|
+
err_body = {"error": e.reason or str(e), "code": None, "request_id": None}
|
|
89
|
+
retry_after = None
|
|
90
|
+
try:
|
|
91
|
+
ra = e.headers.get("Retry-After") if e.headers else None
|
|
92
|
+
if ra:
|
|
93
|
+
retry_after = float(ra)
|
|
94
|
+
except Exception:
|
|
95
|
+
pass
|
|
96
|
+
if e.code == 429:
|
|
97
|
+
raise errors.RateLimitError(
|
|
98
|
+
err_body.get("error") or "rate limited",
|
|
99
|
+
code=err_body.get("code"),
|
|
100
|
+
request_id=err_body.get("request_id"),
|
|
101
|
+
status=e.code,
|
|
102
|
+
body=err_body,
|
|
103
|
+
retry_after=retry_after,
|
|
104
|
+
)
|
|
105
|
+
raise errors.from_response(e.code, err_body)
|
|
106
|
+
except urllib.error.URLError as e:
|
|
107
|
+
raise errors.BrowsaError(f"network error: {e}") from e
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
class Client:
|
|
111
|
+
"""Synchronous REST client.
|
|
112
|
+
|
|
113
|
+
The simplest usage is `client.run_task(...)` which submits a task and
|
|
114
|
+
blocks until it finishes. For fire-and-poll, call `create_task` +
|
|
115
|
+
`get_job` directly.
|
|
116
|
+
|
|
117
|
+
Args:
|
|
118
|
+
api_key: An `agt_live_*` key minted from browsa.io → API Keys.
|
|
119
|
+
base_url: Override for self-hosted / staging.
|
|
120
|
+
timeout: Per-request HTTP timeout (seconds). Long-poll calls override
|
|
121
|
+
this internally; this is the upper bound for one round trip.
|
|
122
|
+
"""
|
|
123
|
+
|
|
124
|
+
def __init__(
|
|
125
|
+
self,
|
|
126
|
+
api_key: str,
|
|
127
|
+
*,
|
|
128
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
129
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
130
|
+
) -> None:
|
|
131
|
+
if not api_key or not api_key.startswith("agt_"):
|
|
132
|
+
raise ValueError(
|
|
133
|
+
"api_key must start with 'agt_'. Mint one at https://browsa.io/dashboard/keys"
|
|
134
|
+
)
|
|
135
|
+
self._t = _Transport(api_key, base_url, timeout)
|
|
136
|
+
|
|
137
|
+
# ── Tasks ────────────────────────────────────────────────────────────
|
|
138
|
+
|
|
139
|
+
def create_task(
|
|
140
|
+
self,
|
|
141
|
+
*,
|
|
142
|
+
task: str,
|
|
143
|
+
llm: str,
|
|
144
|
+
llm_api_key: str,
|
|
145
|
+
framework: str = "browser-use",
|
|
146
|
+
llm_base_url: Optional[str] = None,
|
|
147
|
+
country: Optional[str] = None,
|
|
148
|
+
os_type: Optional[str] = None,
|
|
149
|
+
max_steps: Optional[int] = None,
|
|
150
|
+
ja3_profile: Optional[str] = None,
|
|
151
|
+
initial_url: Optional[str] = None,
|
|
152
|
+
profile_id: Optional[str] = None,
|
|
153
|
+
webhook_url: Optional[str] = None,
|
|
154
|
+
# Round-4 fingerprint overrides. Forwarded to the burner the
|
|
155
|
+
# task runs on (POST /v1/agents under the hood). Same accepted
|
|
156
|
+
# values as create_agent().
|
|
157
|
+
screen_resolution: Optional[str] = None,
|
|
158
|
+
webrtc_mode: Optional[str] = None,
|
|
159
|
+
geolocation_mode: Optional[str] = None,
|
|
160
|
+
geolocation_data: Optional[str] = None,
|
|
161
|
+
media_devices_mode: Optional[str] = None,
|
|
162
|
+
port_scan_protection: Optional[str] = None,
|
|
163
|
+
**extra: Any,
|
|
164
|
+
) -> Job:
|
|
165
|
+
"""POST /v1/tasks — submit a task; returns immediately with a job id.
|
|
166
|
+
|
|
167
|
+
See run_task() if you want to block until completion.
|
|
168
|
+
"""
|
|
169
|
+
body = {
|
|
170
|
+
"task": task,
|
|
171
|
+
"llm": llm,
|
|
172
|
+
"llm_api_key": llm_api_key,
|
|
173
|
+
"framework": framework,
|
|
174
|
+
}
|
|
175
|
+
for k, v in {
|
|
176
|
+
"llm_base_url": llm_base_url,
|
|
177
|
+
"country": country,
|
|
178
|
+
"os_type": os_type,
|
|
179
|
+
"max_steps": max_steps,
|
|
180
|
+
"ja3_profile": ja3_profile,
|
|
181
|
+
"initial_url": initial_url,
|
|
182
|
+
"profile_id": profile_id,
|
|
183
|
+
"webhook_url": webhook_url,
|
|
184
|
+
"screen_resolution": screen_resolution,
|
|
185
|
+
"webrtc_mode": webrtc_mode,
|
|
186
|
+
"geolocation_mode": geolocation_mode,
|
|
187
|
+
"geolocation_data": geolocation_data,
|
|
188
|
+
"media_devices_mode": media_devices_mode,
|
|
189
|
+
"port_scan_protection": port_scan_protection,
|
|
190
|
+
}.items():
|
|
191
|
+
if v is not None:
|
|
192
|
+
body[k] = v
|
|
193
|
+
body.update(extra)
|
|
194
|
+
return Job.from_response(self._t.request("POST", "/v1/tasks", body=body))
|
|
195
|
+
|
|
196
|
+
def get_job(self, job_id: str, *, wait: int = 0) -> Job:
|
|
197
|
+
"""GET /v1/jobs/:id. Pass `wait=N` (1–120s) to long-poll until the job
|
|
198
|
+
reaches a terminal state or N seconds elapse — saves polling round
|
|
199
|
+
trips on short tasks.
|
|
200
|
+
|
|
201
|
+
Client-side timeout is set to wait+10s so we don't race the server's
|
|
202
|
+
own long-poll deadline (was: identical timeout caused TimeoutError
|
|
203
|
+
right when the server was about to return). Discovered via the SDK
|
|
204
|
+
end-to-end test against prod 2026-06-08.
|
|
205
|
+
"""
|
|
206
|
+
query = {"wait": wait} if wait else None
|
|
207
|
+
eff_timeout = (wait + 10.0) if wait else None
|
|
208
|
+
return Job.from_response(
|
|
209
|
+
self._t.request("GET", f"/v1/jobs/{job_id}", query=query, timeout=eff_timeout)
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
def get_job_status(self, job_id: str) -> str:
|
|
213
|
+
"""GET /v1/jobs/:id/status — lightweight status-only poll."""
|
|
214
|
+
body = self._t.request("GET", f"/v1/jobs/{job_id}/status")
|
|
215
|
+
return body.get("status") if isinstance(body, dict) else ""
|
|
216
|
+
|
|
217
|
+
def cancel_job(self, job_id: str) -> None:
|
|
218
|
+
"""POST /v1/jobs/:id/cancel — 204 on success."""
|
|
219
|
+
self._t.request("POST", f"/v1/jobs/{job_id}/cancel")
|
|
220
|
+
|
|
221
|
+
def respond_to_job(self, job_id: str, response: str) -> Job:
|
|
222
|
+
"""POST /v1/jobs/:id/respond — answer an `input_required` question
|
|
223
|
+
(e.g. captcha solutions, decision-point prompts) and flip the job
|
|
224
|
+
back to `running`."""
|
|
225
|
+
body = self._t.request("POST", f"/v1/jobs/{job_id}/respond", body={"response": response})
|
|
226
|
+
return Job.from_response(body)
|
|
227
|
+
|
|
228
|
+
def wait_for_job(
|
|
229
|
+
self,
|
|
230
|
+
job_id: str,
|
|
231
|
+
*,
|
|
232
|
+
poll: float = DEFAULT_POLL_INTERVAL,
|
|
233
|
+
timeout: Optional[float] = None,
|
|
234
|
+
on_progress: Optional[Any] = None,
|
|
235
|
+
) -> Job:
|
|
236
|
+
"""Block until the job reaches a terminal state.
|
|
237
|
+
|
|
238
|
+
Uses a server-side long-poll (`wait=30`) when possible to minimize
|
|
239
|
+
round trips; falls back to client-side sleep + GET if the server
|
|
240
|
+
cuts the connection (e.g. NAT or LB idle timeout).
|
|
241
|
+
|
|
242
|
+
Args:
|
|
243
|
+
job_id: UUID of the job to wait on.
|
|
244
|
+
poll: Backoff seconds between polls (default 2s).
|
|
245
|
+
timeout: Total wall-clock seconds to wait. None = forever.
|
|
246
|
+
on_progress: Optional callable(Job) called after every poll —
|
|
247
|
+
great for tqdm progress bars or live UI updates.
|
|
248
|
+
"""
|
|
249
|
+
start = time.monotonic()
|
|
250
|
+
while True:
|
|
251
|
+
j = self.get_job(job_id, wait=30)
|
|
252
|
+
if on_progress is not None:
|
|
253
|
+
try:
|
|
254
|
+
on_progress(j)
|
|
255
|
+
except Exception:
|
|
256
|
+
# never let a user callback break the wait loop
|
|
257
|
+
pass
|
|
258
|
+
if j.is_terminal:
|
|
259
|
+
return j
|
|
260
|
+
if timeout is not None and (time.monotonic() - start) > timeout:
|
|
261
|
+
raise errors.TimeoutError(
|
|
262
|
+
f"wait_for_job exceeded {timeout}s — last status: {j.status}",
|
|
263
|
+
status=None,
|
|
264
|
+
)
|
|
265
|
+
time.sleep(poll)
|
|
266
|
+
|
|
267
|
+
def run_task(
|
|
268
|
+
self,
|
|
269
|
+
*,
|
|
270
|
+
task: str,
|
|
271
|
+
llm: str,
|
|
272
|
+
llm_api_key: str,
|
|
273
|
+
framework: str = "browser-use",
|
|
274
|
+
timeout: Optional[float] = 600,
|
|
275
|
+
on_progress: Optional[Any] = None,
|
|
276
|
+
**kwargs: Any,
|
|
277
|
+
) -> Job:
|
|
278
|
+
"""One-shot: submit + wait + return the terminal Job. The "hello world"
|
|
279
|
+
entry point — five lines from `pip install` to a real anti-detect-
|
|
280
|
+
browser-driven AI agent.
|
|
281
|
+
"""
|
|
282
|
+
job = self.create_task(
|
|
283
|
+
task=task,
|
|
284
|
+
llm=llm,
|
|
285
|
+
llm_api_key=llm_api_key,
|
|
286
|
+
framework=framework,
|
|
287
|
+
**kwargs,
|
|
288
|
+
)
|
|
289
|
+
return self.wait_for_job(job.id, timeout=timeout, on_progress=on_progress)
|
|
290
|
+
|
|
291
|
+
# ── Webhooks ─────────────────────────────────────────────────────────
|
|
292
|
+
|
|
293
|
+
def list_webhooks(self) -> list[Webhook]:
|
|
294
|
+
body = self._t.request("GET", "/v1/webhooks")
|
|
295
|
+
return [Webhook.from_response(w) for w in (body.get("webhooks") or [])]
|
|
296
|
+
|
|
297
|
+
def create_webhook(self, *, url: str, events: Optional[Iterable[str]] = None) -> Webhook:
|
|
298
|
+
body = {"url": url}
|
|
299
|
+
if events is not None:
|
|
300
|
+
body["events"] = list(events)
|
|
301
|
+
return Webhook.from_response(self._t.request("POST", "/v1/webhooks", body=body))
|
|
302
|
+
|
|
303
|
+
def delete_webhook(self, webhook_id: str) -> None:
|
|
304
|
+
self._t.request("DELETE", f"/v1/webhooks/{webhook_id}")
|
|
305
|
+
|
|
306
|
+
def test_webhook(self, webhook_id: str) -> dict:
|
|
307
|
+
"""POST /v1/webhooks/:id/test — fires a synthetic delivery so you
|
|
308
|
+
can verify the receiver before depending on real lifecycle traffic."""
|
|
309
|
+
return self._t.request("POST", f"/v1/webhooks/{webhook_id}/test")
|
|
310
|
+
|
|
311
|
+
def get_signing_secret(self) -> str:
|
|
312
|
+
body = self._t.request("GET", "/v1/webhooks/signing-secret")
|
|
313
|
+
return body.get("secret") if isinstance(body, dict) else ""
|
|
314
|
+
|
|
315
|
+
# ── Keys / Credits / Team ────────────────────────────────────────────
|
|
316
|
+
|
|
317
|
+
def list_keys(self) -> list[dict]:
|
|
318
|
+
body = self._t.request("GET", "/v1/keys")
|
|
319
|
+
return body.get("keys") if isinstance(body, dict) else []
|
|
320
|
+
|
|
321
|
+
def credits(self) -> dict:
|
|
322
|
+
return self._t.request("GET", "/v1/credits")
|
|
323
|
+
|
|
324
|
+
def list_ledger(self, *, limit: int = 50) -> dict:
|
|
325
|
+
"""GET /v1/credits/ledger?limit=N — per-job credit-ledger entries.
|
|
326
|
+
|
|
327
|
+
Returns `{balance, count, entries: [{id, delta, balance, reason,
|
|
328
|
+
agent_id, created_at}, ...]}`. Every job-completion writes one
|
|
329
|
+
debit row tagged with the linked job id; signup bonuses, refunds,
|
|
330
|
+
and Stripe top-ups write positive rows. Use this to bill your own
|
|
331
|
+
clients from Browsa usage data.
|
|
332
|
+
"""
|
|
333
|
+
return self._t.request("GET", "/v1/credits/ledger", query={"limit": limit})
|
|
334
|
+
|
|
335
|
+
# ── Quick endpoints (sync or async=true) ──────────────────────────────
|
|
336
|
+
# These don't need an LLM — they're server-side scrape primitives the
|
|
337
|
+
# platform runs in a fresh burner and returns the result directly.
|
|
338
|
+
# Pass async_=True for fire-and-poll (returns a Job envelope you can
|
|
339
|
+
# wait_for_job() on). Without async_, the call blocks server-side
|
|
340
|
+
# until the scrape finishes (~5-30s typical).
|
|
341
|
+
|
|
342
|
+
def scrape(self, url: str, *, async_: bool = False,
|
|
343
|
+
idempotency_key: Optional[str] = None, **opts: Any) -> dict:
|
|
344
|
+
"""POST /v1/scrape — fetch a URL and return rendered HTML +
|
|
345
|
+
readable text + metadata. No LLM involved. ~5s typical.
|
|
346
|
+
|
|
347
|
+
Args:
|
|
348
|
+
url: Target URL.
|
|
349
|
+
async_: True = return a Job envelope immediately; False = block
|
|
350
|
+
until complete (default).
|
|
351
|
+
idempotency_key: Optional. If provided, the platform dedupes
|
|
352
|
+
requests with the same (workspace, key) within 24h —
|
|
353
|
+
a retry returns the cached response without
|
|
354
|
+
re-provisioning a burner. Use a UUID per logical
|
|
355
|
+
request to make retries billing-safe.
|
|
356
|
+
**opts: country, wait_for, screenshot, etc. — see API docs.
|
|
357
|
+
"""
|
|
358
|
+
body = {"url": url}
|
|
359
|
+
body.update(opts)
|
|
360
|
+
path = "/v1/quick/scrape" + ("?async=true" if async_ else "")
|
|
361
|
+
headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
|
|
362
|
+
return self._t.request("POST", path, body=body, timeout=120.0, extra_headers=headers)
|
|
363
|
+
|
|
364
|
+
def extract(self, url: str, *, schema: Any = None, prompt: Optional[str] = None,
|
|
365
|
+
async_: bool = False, idempotency_key: Optional[str] = None,
|
|
366
|
+
**opts: Any) -> dict:
|
|
367
|
+
"""POST /v1/extract — LLM-driven structured extraction. Returns
|
|
368
|
+
JSON matching `schema` (or per `prompt`). Pass exactly one of
|
|
369
|
+
`schema` or `prompt`; `schema` wins if both are supplied.
|
|
370
|
+
|
|
371
|
+
idempotency_key (Stripe-compatible) dedupes retries for 24h.
|
|
372
|
+
"""
|
|
373
|
+
body: dict = {"url": url}
|
|
374
|
+
if schema is not None: body["schema"] = schema
|
|
375
|
+
if prompt is not None: body["prompt"] = prompt
|
|
376
|
+
body.update(opts)
|
|
377
|
+
path = "/v1/quick/extract" + ("?async=true" if async_ else "")
|
|
378
|
+
headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
|
|
379
|
+
return self._t.request("POST", path, body=body, timeout=180.0, extra_headers=headers)
|
|
380
|
+
|
|
381
|
+
def screenshot(self, url: str, *, full_page: bool = True, async_: bool = False,
|
|
382
|
+
idempotency_key: Optional[str] = None, **opts: Any) -> dict:
|
|
383
|
+
"""POST /v1/screenshot — capture a screenshot (base64 PNG by
|
|
384
|
+
default). No LLM. ~3-10s typical. idempotency_key dedupes retries.
|
|
385
|
+
"""
|
|
386
|
+
body: dict = {"url": url, "full_page": full_page}
|
|
387
|
+
body.update(opts)
|
|
388
|
+
path = "/v1/quick/screenshot" + ("?async=true" if async_ else "")
|
|
389
|
+
headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
|
|
390
|
+
return self._t.request("POST", path, body=body, timeout=60.0, extra_headers=headers)
|
|
391
|
+
|
|
392
|
+
def batch(self, urls: Iterable[str], *, mode: str = "scrape",
|
|
393
|
+
async_: bool = True, **opts: Any) -> dict:
|
|
394
|
+
"""POST /v1/batch — scrape/extract/screenshot many URLs in
|
|
395
|
+
parallel. Defaults to async (you almost always want this for batch
|
|
396
|
+
jobs); pass async_=False if you really want to block.
|
|
397
|
+
"""
|
|
398
|
+
body: dict = {"urls": list(urls), "mode": mode}
|
|
399
|
+
body.update(opts)
|
|
400
|
+
path = "/v1/quick/batch" + ("?async=true" if async_ else "")
|
|
401
|
+
return self._t.request("POST", path, body=body, timeout=300.0)
|
|
402
|
+
|
|
403
|
+
def crawl(self, start_url: str, *, max_pages: int = 25,
|
|
404
|
+
async_: bool = True, **opts: Any) -> dict:
|
|
405
|
+
"""POST /v1/crawl — BFS crawl starting from `start_url`, capped at
|
|
406
|
+
`max_pages`. Async by default."""
|
|
407
|
+
body: dict = {"start_url": start_url, "max_pages": max_pages}
|
|
408
|
+
body.update(opts)
|
|
409
|
+
path = "/v1/quick/crawl" + ("?async=true" if async_ else "")
|
|
410
|
+
return self._t.request("POST", path, body=body, timeout=300.0)
|
|
411
|
+
|
|
412
|
+
# ── Agents (burner + persistent) ──────────────────────────────────────
|
|
413
|
+
|
|
414
|
+
def create_agent(self, *, ttl: Optional[str] = None, country: Optional[str] = None,
|
|
415
|
+
persona: Optional[str] = None, os_type: Optional[str] = None,
|
|
416
|
+
ja3_profile: Optional[str] = None,
|
|
417
|
+
screen_resolution: Optional[str] = None,
|
|
418
|
+
webrtc_mode: Optional[str] = None,
|
|
419
|
+
geolocation_mode: Optional[str] = None,
|
|
420
|
+
geolocation_data: Optional[str] = None,
|
|
421
|
+
media_devices_mode: Optional[str] = None,
|
|
422
|
+
port_scan_protection: Optional[str] = None,
|
|
423
|
+
**opts: Any) -> dict:
|
|
424
|
+
"""POST /v1/agents — provision an agent.
|
|
425
|
+
|
|
426
|
+
Mode auto-detection:
|
|
427
|
+
- if `persona` set + no `ttl` → persistent (vault-synced, monthly)
|
|
428
|
+
- else → burner (ephemeral, pay-per-call)
|
|
429
|
+
|
|
430
|
+
Fingerprint overrides (power-user — leave empty for platform defaults):
|
|
431
|
+
- screen_resolution: "1366x768" | "1920x1080" | "2560x1440" |
|
|
432
|
+
"3840x2160" | "mobile-iphone" |
|
|
433
|
+
"mobile-android-pixel" | "WxH" custom
|
|
434
|
+
- webrtc_mode: "masked" | "real" | "disabled"
|
|
435
|
+
- geolocation_mode: "prompt" | "allow" | "block"
|
|
436
|
+
- geolocation_data: "lat,lng" (when geolocation_mode="allow")
|
|
437
|
+
- media_devices_mode: "masked" | "real"
|
|
438
|
+
- port_scan_protection: "masked" | "real"
|
|
439
|
+
|
|
440
|
+
Mismatched combinations (e.g. mobile resolution + os_type=MACOS)
|
|
441
|
+
will return a non-fatal `warnings` array in the fingerprint
|
|
442
|
+
preview AND may lower the agent's trust score.
|
|
443
|
+
|
|
444
|
+
Returns the agent envelope incl. `id`, `cdp_url`, `expires_at`.
|
|
445
|
+
"""
|
|
446
|
+
body: dict = {}
|
|
447
|
+
for k, v in {
|
|
448
|
+
"ttl": ttl, "country": country, "persona": persona,
|
|
449
|
+
"os_type": os_type, "ja3_profile": ja3_profile,
|
|
450
|
+
"screen_resolution": screen_resolution,
|
|
451
|
+
"webrtc_mode": webrtc_mode,
|
|
452
|
+
"geolocation_mode": geolocation_mode,
|
|
453
|
+
"geolocation_data": geolocation_data,
|
|
454
|
+
"media_devices_mode": media_devices_mode,
|
|
455
|
+
"port_scan_protection": port_scan_protection,
|
|
456
|
+
}.items():
|
|
457
|
+
if v is not None: body[k] = v
|
|
458
|
+
body.update(opts)
|
|
459
|
+
return self._t.request("POST", "/v1/agents", body=body)
|
|
460
|
+
|
|
461
|
+
def get_agent(self, agent_id: str) -> dict:
|
|
462
|
+
return self._t.request("GET", f"/v1/agents/{agent_id}")
|
|
463
|
+
|
|
464
|
+
def destroy_agent(self, agent_id: str) -> None:
|
|
465
|
+
self._t.request("DELETE", f"/v1/agents/{agent_id}")
|
|
466
|
+
|
|
467
|
+
def get_cdp_url(self, agent_id: str) -> str:
|
|
468
|
+
"""GET /v1/agents/:id/cdp — returns the CDP WebSocket URL to
|
|
469
|
+
connect Playwright/Puppeteer over."""
|
|
470
|
+
r = self._t.request("GET", f"/v1/agents/{agent_id}/cdp")
|
|
471
|
+
return r.get("cdp_url") if isinstance(r, dict) else ""
|
|
472
|
+
|
|
473
|
+
def open_session(self, agent_id: str, *, ttl: Optional[str] = None) -> dict:
|
|
474
|
+
"""POST /v1/agents/:id/sessions — open a new session on a
|
|
475
|
+
persistent agent (returns a CDP URL bound to a fresh session).
|
|
476
|
+
Burner agents already have an implicit session; use get_cdp_url for those."""
|
|
477
|
+
body: dict = {}
|
|
478
|
+
if ttl is not None: body["ttl"] = ttl
|
|
479
|
+
return self._t.request("POST", f"/v1/agents/{agent_id}/sessions", body=body)
|
|
480
|
+
|
|
481
|
+
def fingerprint(self, agent_id: str) -> dict:
|
|
482
|
+
"""GET /v1/agents/:id/fingerprint — return the wire-level fingerprint
|
|
483
|
+
preview (navigator, screen, webgl, timezone, canvas, audio, tls).
|
|
484
|
+
Lets you pin an identity and validate it against your own
|
|
485
|
+
anti-fingerprint test suite before running tasks. Competitor parity-plus:
|
|
486
|
+
browser-use cloud profiles don't expose this at all."""
|
|
487
|
+
return self._t.request("GET", f"/v1/agents/{agent_id}/fingerprint")
|
|
488
|
+
|
|
489
|
+
def trust_breakdown(self, agent_id: str) -> dict:
|
|
490
|
+
"""GET /v1/agents/:id/trust — return the per-factor breakdown of the
|
|
491
|
+
agent's trust_score (baseline + mode + os + warmup + age + sessions +
|
|
492
|
+
harness signal). Tells you WHY the identity scored what it did and
|
|
493
|
+
which knob to turn to raise it (e.g. add a warmup_recipe, or
|
|
494
|
+
promote burner → persistent)."""
|
|
495
|
+
return self._t.request("GET", f"/v1/agents/{agent_id}/trust")
|
|
496
|
+
|
|
497
|
+
def detection_signal(self, agent_id: str) -> dict:
|
|
498
|
+
"""GET /v1/agents/:id/detection-signal — return the most-recent
|
|
499
|
+
detection-harness verdict for this identity's fingerprint shape.
|
|
500
|
+
Returns {signal: null} when no recent harness run is on file
|
|
501
|
+
(trust score falls back to the static formula). When populated,
|
|
502
|
+
includes sites_tested + sites_passed + per-site verdicts.
|
|
503
|
+
The empirical proof behind the trust score number."""
|
|
504
|
+
return self._t.request("GET", f"/v1/agents/{agent_id}/detection-signal")
|
|
505
|
+
|
|
506
|
+
def auto(self, task: str, *, llm: Optional[str] = None,
|
|
507
|
+
llm_api_key: Optional[str] = None, llm_base_url: Optional[str] = None,
|
|
508
|
+
max_steps: Optional[int] = None, max_cost_usd: Optional[float] = None,
|
|
509
|
+
country: Optional[str] = None, **opts: Any) -> dict:
|
|
510
|
+
"""POST /v1/auto — smart-router. Same body as create_task but the
|
|
511
|
+
platform inspects the task wording:
|
|
512
|
+
- fetch-only ("go to URL, return text/h1/json", no clicks/types)
|
|
513
|
+
short-circuits to /v1/quick/scrape → ~5s response.
|
|
514
|
+
- interactive (clicks, form submits, login flows) falls through
|
|
515
|
+
to the regular task path (job_id + poll).
|
|
516
|
+
|
|
517
|
+
Response carries `routed_via: "scrape" | "task"` so you can
|
|
518
|
+
branch your client code accordingly. Competitor-parity feature
|
|
519
|
+
2026-06-09: matches browser-use cloud's Computer Use v3 dispatch.
|
|
520
|
+
"""
|
|
521
|
+
body: dict = {"task": task}
|
|
522
|
+
if llm is not None: body["llm"] = llm
|
|
523
|
+
if llm_api_key is not None: body["llm_api_key"] = llm_api_key
|
|
524
|
+
if llm_base_url is not None: body["llm_base_url"] = llm_base_url
|
|
525
|
+
if max_steps is not None: body["max_steps"] = max_steps
|
|
526
|
+
if max_cost_usd is not None: body["max_cost_usd"] = max_cost_usd
|
|
527
|
+
if country is not None: body["country"] = country
|
|
528
|
+
body.update(opts)
|
|
529
|
+
return self._t.request("POST", "/v1/auto", body=body, timeout=120.0)
|
|
530
|
+
|
|
531
|
+
def connect(self, agent_id: str, *, framework: str = "playwright_py") -> dict:
|
|
532
|
+
"""Convenience helper: returns a ready-to-paste connect snippet
|
|
533
|
+
for the given client framework. No round-trip if the agent's
|
|
534
|
+
cdp_url is already in scope — we just format the boilerplate.
|
|
535
|
+
|
|
536
|
+
framework choices: 'playwright_py', 'playwright_ts', 'puppeteer_js',
|
|
537
|
+
'curl'. Returns {framework, cdp_http, cdp_url, snippet}.
|
|
538
|
+
|
|
539
|
+
Competitor-audit 2026-06-09 P0: browser-use cloud forces devs to
|
|
540
|
+
hand-write the connect boilerplate every time. We surface it as
|
|
541
|
+
one SDK call.
|
|
542
|
+
"""
|
|
543
|
+
agent = self.get_agent(agent_id)
|
|
544
|
+
profile_id = agent.get("profile_id") or ""
|
|
545
|
+
cdp_http = agent.get("cdp_http") or (
|
|
546
|
+
f"https://browsa.io/api/v1/cdp/{profile_id}" if profile_id else ""
|
|
547
|
+
)
|
|
548
|
+
cdp_url = agent.get("cdp_url") or (
|
|
549
|
+
f"wss://browsa.io/api/v1/cdp/{profile_id}/ws/page/..." if profile_id else ""
|
|
550
|
+
)
|
|
551
|
+
if not cdp_http:
|
|
552
|
+
raise RuntimeError(
|
|
553
|
+
f"agent {agent_id} has no CDP URL — is it status=running? "
|
|
554
|
+
f"current status: {agent.get('status', 'unknown')}"
|
|
555
|
+
)
|
|
556
|
+
snippets = {
|
|
557
|
+
"playwright_py": (
|
|
558
|
+
"import asyncio\n"
|
|
559
|
+
"from playwright.async_api import async_playwright\n\n"
|
|
560
|
+
f'CDP_URL = "{cdp_http}"\n\n'
|
|
561
|
+
"async def main():\n"
|
|
562
|
+
" async with async_playwright() as p:\n"
|
|
563
|
+
" browser = await p.chromium.connect_over_cdp(CDP_URL)\n"
|
|
564
|
+
" page = browser.contexts[0].pages[0]\n"
|
|
565
|
+
' await page.goto("https://example.com")\n'
|
|
566
|
+
" print(await page.title())\n"
|
|
567
|
+
" await browser.close()\n\n"
|
|
568
|
+
"asyncio.run(main())\n"
|
|
569
|
+
),
|
|
570
|
+
"playwright_ts": (
|
|
571
|
+
'import { chromium } from "playwright";\n\n'
|
|
572
|
+
f'const CDP_URL = "{cdp_http}";\n\n'
|
|
573
|
+
"const browser = await chromium.connectOverCDP(CDP_URL);\n"
|
|
574
|
+
"const page = browser.contexts()[0].pages()[0];\n"
|
|
575
|
+
'await page.goto("https://example.com");\n'
|
|
576
|
+
"console.log(await page.title());\n"
|
|
577
|
+
"await browser.close();\n"
|
|
578
|
+
),
|
|
579
|
+
"puppeteer_js": (
|
|
580
|
+
'import puppeteer from "puppeteer";\n\n'
|
|
581
|
+
f'const CDP_URL = "{cdp_http}";\n\n'
|
|
582
|
+
"const browser = await puppeteer.connect({ browserURL: CDP_URL });\n"
|
|
583
|
+
"const page = await browser.newPage();\n"
|
|
584
|
+
'await page.goto("https://example.com");\n'
|
|
585
|
+
"console.log(await page.title());\n"
|
|
586
|
+
"await browser.disconnect();\n"
|
|
587
|
+
),
|
|
588
|
+
"curl": (
|
|
589
|
+
"# CDP HTTP endpoint (Playwright/Puppeteer call this for /json/version):\n"
|
|
590
|
+
f'curl -H "X-API-Key: {self._t.api_key[:14]}..." {cdp_http}/json/version\n\n'
|
|
591
|
+
"# CDP WebSocket (first page):\n"
|
|
592
|
+
f"# {cdp_url}\n"
|
|
593
|
+
),
|
|
594
|
+
}
|
|
595
|
+
if framework not in snippets:
|
|
596
|
+
raise ValueError(
|
|
597
|
+
f"unknown framework {framework!r} — "
|
|
598
|
+
f"choose from {list(snippets.keys())}"
|
|
599
|
+
)
|
|
600
|
+
return {
|
|
601
|
+
"framework": framework,
|
|
602
|
+
"cdp_http": cdp_http,
|
|
603
|
+
"cdp_url": cdp_url,
|
|
604
|
+
"snippet": snippets[framework],
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
# ── API keys ──────────────────────────────────────────────────────────
|
|
608
|
+
|
|
609
|
+
def mint_key(self, *, name: str) -> dict:
|
|
610
|
+
"""POST /v1/keys — mint a new API key.
|
|
611
|
+
|
|
612
|
+
IMPORTANT: The full secret is returned EXACTLY ONCE in the `secret`
|
|
613
|
+
field. The dashboard surface only ever has the prefix after this
|
|
614
|
+
call. Copy + store it immediately.
|
|
615
|
+
"""
|
|
616
|
+
return self._t.request("POST", "/v1/keys", body={"name": name})
|
|
617
|
+
|
|
618
|
+
def revoke_key(self, key_id: str) -> None:
|
|
619
|
+
"""DELETE /v1/keys/:id — revoke. Idempotent; revoked keys cannot
|
|
620
|
+
be unrevoked."""
|
|
621
|
+
self._t.request("DELETE", f"/v1/keys/{key_id}")
|
|
622
|
+
|
|
623
|
+
def list_team(self) -> dict:
|
|
624
|
+
return self._t.request("GET", "/v1/team/members")
|
|
625
|
+
|
|
626
|
+
# ── Persistent identities ────────────────────────────────────────────
|
|
627
|
+
|
|
628
|
+
def list_identities(self) -> list[dict]:
|
|
629
|
+
body = self._t.request("GET", "/v1/agents")
|
|
630
|
+
return body.get("agents") if isinstance(body, dict) else []
|
|
631
|
+
|
|
632
|
+
def __repr__(self) -> str:
|
|
633
|
+
return f"<browsa.Client base_url={self._t.base_url!r}>"
|
|
634
|
+
|
|
635
|
+
|
|
636
|
+
# ─── Async client ────────────────────────────────────────────────────────
|
|
637
|
+
|
|
638
|
+
|
|
639
|
+
class AsyncClient:
|
|
640
|
+
"""Asyncio-friendly wrapper.
|
|
641
|
+
|
|
642
|
+
Backed by `asyncio.to_thread` over the sync client — keeps the codebase
|
|
643
|
+
small. If we ever need true high-concurrency streaming, swap in aiohttp
|
|
644
|
+
behind the same surface.
|
|
645
|
+
"""
|
|
646
|
+
|
|
647
|
+
def __init__(
|
|
648
|
+
self,
|
|
649
|
+
api_key: str,
|
|
650
|
+
*,
|
|
651
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
652
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
653
|
+
) -> None:
|
|
654
|
+
self._sync = Client(api_key, base_url=base_url, timeout=timeout)
|
|
655
|
+
|
|
656
|
+
async def __aenter__(self) -> "AsyncClient":
|
|
657
|
+
return self
|
|
658
|
+
|
|
659
|
+
async def __aexit__(self, *exc: Any) -> None:
|
|
660
|
+
return None
|
|
661
|
+
|
|
662
|
+
async def create_task(self, **kw: Any) -> Job:
|
|
663
|
+
return await asyncio.to_thread(self._sync.create_task, **kw)
|
|
664
|
+
|
|
665
|
+
async def get_job(self, job_id: str, *, wait: int = 0) -> Job:
|
|
666
|
+
return await asyncio.to_thread(self._sync.get_job, job_id, wait=wait)
|
|
667
|
+
|
|
668
|
+
async def get_job_status(self, job_id: str) -> str:
|
|
669
|
+
return await asyncio.to_thread(self._sync.get_job_status, job_id)
|
|
670
|
+
|
|
671
|
+
async def cancel_job(self, job_id: str) -> None:
|
|
672
|
+
await asyncio.to_thread(self._sync.cancel_job, job_id)
|
|
673
|
+
|
|
674
|
+
async def respond_to_job(self, job_id: str, response: str) -> Job:
|
|
675
|
+
return await asyncio.to_thread(self._sync.respond_to_job, job_id, response)
|
|
676
|
+
|
|
677
|
+
async def wait_for_job(self, job_id: str, *, poll: float = DEFAULT_POLL_INTERVAL,
|
|
678
|
+
timeout: Optional[float] = None, on_progress: Optional[Any] = None) -> Job:
|
|
679
|
+
return await asyncio.to_thread(self._sync.wait_for_job, job_id,
|
|
680
|
+
poll=poll, timeout=timeout, on_progress=on_progress)
|
|
681
|
+
|
|
682
|
+
async def run_task(self, **kw: Any) -> Job:
|
|
683
|
+
return await asyncio.to_thread(self._sync.run_task, **kw)
|
|
684
|
+
|
|
685
|
+
async def list_webhooks(self) -> list[Webhook]:
|
|
686
|
+
return await asyncio.to_thread(self._sync.list_webhooks)
|
|
687
|
+
|
|
688
|
+
async def create_webhook(self, **kw: Any) -> Webhook:
|
|
689
|
+
return await asyncio.to_thread(self._sync.create_webhook, **kw)
|
|
690
|
+
|
|
691
|
+
async def delete_webhook(self, webhook_id: str) -> None:
|
|
692
|
+
await asyncio.to_thread(self._sync.delete_webhook, webhook_id)
|
|
693
|
+
|
|
694
|
+
async def test_webhook(self, webhook_id: str) -> dict:
|
|
695
|
+
return await asyncio.to_thread(self._sync.test_webhook, webhook_id)
|
|
696
|
+
|
|
697
|
+
async def get_signing_secret(self) -> str:
|
|
698
|
+
return await asyncio.to_thread(self._sync.get_signing_secret)
|
|
699
|
+
|
|
700
|
+
async def list_keys(self) -> list[dict]:
|
|
701
|
+
return await asyncio.to_thread(self._sync.list_keys)
|
|
702
|
+
|
|
703
|
+
async def credits(self) -> dict:
|
|
704
|
+
return await asyncio.to_thread(self._sync.credits)
|
|
705
|
+
|
|
706
|
+
async def list_ledger(self, *, limit: int = 50) -> dict:
|
|
707
|
+
return await asyncio.to_thread(self._sync.list_ledger, limit=limit)
|
|
708
|
+
|
|
709
|
+
# Quick endpoints
|
|
710
|
+
async def scrape(self, url: str, **kw: Any) -> dict:
|
|
711
|
+
return await asyncio.to_thread(self._sync.scrape, url, **kw)
|
|
712
|
+
|
|
713
|
+
async def extract(self, url: str, **kw: Any) -> dict:
|
|
714
|
+
return await asyncio.to_thread(self._sync.extract, url, **kw)
|
|
715
|
+
|
|
716
|
+
async def screenshot(self, url: str, **kw: Any) -> dict:
|
|
717
|
+
return await asyncio.to_thread(self._sync.screenshot, url, **kw)
|
|
718
|
+
|
|
719
|
+
async def batch(self, urls: Iterable[str], **kw: Any) -> dict:
|
|
720
|
+
return await asyncio.to_thread(self._sync.batch, urls, **kw)
|
|
721
|
+
|
|
722
|
+
async def crawl(self, start_url: str, **kw: Any) -> dict:
|
|
723
|
+
return await asyncio.to_thread(self._sync.crawl, start_url, **kw)
|
|
724
|
+
|
|
725
|
+
# Agents
|
|
726
|
+
async def create_agent(self, **kw: Any) -> dict:
|
|
727
|
+
return await asyncio.to_thread(self._sync.create_agent, **kw)
|
|
728
|
+
|
|
729
|
+
async def get_agent(self, agent_id: str) -> dict:
|
|
730
|
+
return await asyncio.to_thread(self._sync.get_agent, agent_id)
|
|
731
|
+
|
|
732
|
+
async def destroy_agent(self, agent_id: str) -> None:
|
|
733
|
+
await asyncio.to_thread(self._sync.destroy_agent, agent_id)
|
|
734
|
+
|
|
735
|
+
async def get_cdp_url(self, agent_id: str) -> str:
|
|
736
|
+
return await asyncio.to_thread(self._sync.get_cdp_url, agent_id)
|
|
737
|
+
|
|
738
|
+
async def open_session(self, agent_id: str, **kw: Any) -> dict:
|
|
739
|
+
return await asyncio.to_thread(self._sync.open_session, agent_id, **kw)
|
|
740
|
+
|
|
741
|
+
# Keys
|
|
742
|
+
async def mint_key(self, **kw: Any) -> dict:
|
|
743
|
+
return await asyncio.to_thread(self._sync.mint_key, **kw)
|
|
744
|
+
|
|
745
|
+
async def revoke_key(self, key_id: str) -> None:
|
|
746
|
+
await asyncio.to_thread(self._sync.revoke_key, key_id)
|
|
747
|
+
|
|
748
|
+
async def list_team(self) -> dict:
|
|
749
|
+
return await asyncio.to_thread(self._sync.list_team)
|
|
750
|
+
|
|
751
|
+
async def list_identities(self) -> list[dict]:
|
|
752
|
+
return await asyncio.to_thread(self._sync.list_identities)
|
browsa/errors.py
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
"""Canonical error envelope from browsa.io:
|
|
2
|
+
|
|
3
|
+
{ "code": "INVALID_ID", "error": "...", "request_id": "uuid" }
|
|
4
|
+
|
|
5
|
+
Every error response from the API is wrapped in this shape. The SDK
|
|
6
|
+
parses it and raises the most specific subclass of BrowsaError that
|
|
7
|
+
matches the HTTP status + envelope code.
|
|
8
|
+
"""
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
from typing import Any, Optional
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class BrowsaError(Exception):
|
|
14
|
+
"""Base class for all SDK errors. Always carries the canonical envelope
|
|
15
|
+
fields (code, error, request_id) plus the raw HTTP status so the caller
|
|
16
|
+
can branch on either."""
|
|
17
|
+
|
|
18
|
+
def __init__(
|
|
19
|
+
self,
|
|
20
|
+
message: str,
|
|
21
|
+
*,
|
|
22
|
+
code: Optional[str] = None,
|
|
23
|
+
request_id: Optional[str] = None,
|
|
24
|
+
status: Optional[int] = None,
|
|
25
|
+
body: Any = None,
|
|
26
|
+
) -> None:
|
|
27
|
+
super().__init__(message)
|
|
28
|
+
self.code = code
|
|
29
|
+
self.request_id = request_id
|
|
30
|
+
self.status = status
|
|
31
|
+
self.body = body
|
|
32
|
+
|
|
33
|
+
def __str__(self) -> str:
|
|
34
|
+
bits = [super().__str__()]
|
|
35
|
+
if self.code:
|
|
36
|
+
bits.append(f"code={self.code}")
|
|
37
|
+
if self.status:
|
|
38
|
+
bits.append(f"status={self.status}")
|
|
39
|
+
if self.request_id:
|
|
40
|
+
bits.append(f"request_id={self.request_id}")
|
|
41
|
+
return " | ".join(bits)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class APIError(BrowsaError):
|
|
45
|
+
"""Any non-2xx response that doesn't match a more specific subclass."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class AuthError(BrowsaError):
|
|
49
|
+
"""401 / 403 — invalid or revoked API key."""
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class RateLimitError(BrowsaError):
|
|
53
|
+
"""429 — slow down. The server may set Retry-After; check `retry_after`."""
|
|
54
|
+
|
|
55
|
+
def __init__(self, *args: Any, retry_after: Optional[float] = None, **kwargs: Any) -> None:
|
|
56
|
+
super().__init__(*args, **kwargs)
|
|
57
|
+
self.retry_after = retry_after
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class InvalidIDError(BrowsaError):
|
|
61
|
+
"""400 INVALID_ID — caller passed a non-UUID job/webhook/key id."""
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class NotFoundError(BrowsaError):
|
|
65
|
+
"""404 — the resource doesn't exist, was deleted, or belongs to a different workspace."""
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class TimeoutError(BrowsaError): # noqa: A001 — shadows builtin intentionally
|
|
69
|
+
"""Local: the SDK timed out waiting on a long-poll or socket read."""
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def from_response(status: int, body: Any) -> BrowsaError:
|
|
73
|
+
"""Build the most-specific subclass given a raw response."""
|
|
74
|
+
code = None
|
|
75
|
+
error = None
|
|
76
|
+
request_id = None
|
|
77
|
+
if isinstance(body, dict):
|
|
78
|
+
code = body.get("code")
|
|
79
|
+
error = body.get("error") or body.get("message")
|
|
80
|
+
request_id = body.get("request_id")
|
|
81
|
+
message = error or f"HTTP {status}"
|
|
82
|
+
|
|
83
|
+
if status == 401 or code in ("UNAUTHORIZED", "INVALID_API_KEY"):
|
|
84
|
+
cls = AuthError
|
|
85
|
+
elif status == 429 or code == "RATE_LIMIT":
|
|
86
|
+
cls = RateLimitError
|
|
87
|
+
elif status == 400 and code == "INVALID_ID":
|
|
88
|
+
cls = InvalidIDError
|
|
89
|
+
elif status == 404 or code == "NOT_FOUND":
|
|
90
|
+
cls = NotFoundError
|
|
91
|
+
else:
|
|
92
|
+
cls = APIError
|
|
93
|
+
|
|
94
|
+
return cls(message, code=code, request_id=request_id, status=status, body=body)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
# Deprecated alias: BrowsaError was renamed from NeoutError during the
|
|
98
|
+
# neout→browsa rebrand. Existing `except NeoutError` handlers keep working.
|
|
99
|
+
# Will be removed in a future major release.
|
|
100
|
+
NeoutError = BrowsaError
|
browsa/types.py
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
"""Light typed wrappers around the API's JSON envelopes.
|
|
2
|
+
|
|
3
|
+
Intentionally NOT pydantic — zero deps is a feature (see RATIONALE).
|
|
4
|
+
These are tiny dataclasses that surface the fields you actually use.
|
|
5
|
+
The raw dict is always available on `.raw` for fields we haven't typed.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
from dataclasses import dataclass, field
|
|
9
|
+
from typing import Any, Optional
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class JobStatus:
|
|
13
|
+
"""String enum of canonical job statuses. Compare with == to literals."""
|
|
14
|
+
QUEUED = "queued"
|
|
15
|
+
RUNNING = "running"
|
|
16
|
+
COMPLETED = "completed"
|
|
17
|
+
FAILED = "failed"
|
|
18
|
+
CANCELLED = "cancelled"
|
|
19
|
+
INPUT_REQUIRED = "input_required"
|
|
20
|
+
|
|
21
|
+
@classmethod
|
|
22
|
+
def is_terminal(cls, s: str) -> bool:
|
|
23
|
+
return s in (cls.COMPLETED, cls.FAILED, cls.CANCELLED)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass
|
|
27
|
+
class Job:
|
|
28
|
+
"""Single job envelope returned by GET /v1/jobs/:id and POST /v1/tasks."""
|
|
29
|
+
id: str
|
|
30
|
+
status: str
|
|
31
|
+
kind: str
|
|
32
|
+
step_count: int
|
|
33
|
+
progress_done: int
|
|
34
|
+
progress_total: int
|
|
35
|
+
framework: Optional[str] = None
|
|
36
|
+
live_url: Optional[str] = None
|
|
37
|
+
agent_id: Optional[str] = None
|
|
38
|
+
created_at: Optional[str] = None
|
|
39
|
+
started_at: Optional[str] = None
|
|
40
|
+
completed_at: Optional[str] = None
|
|
41
|
+
error_message: Optional[str] = None
|
|
42
|
+
error_code: Optional[str] = None
|
|
43
|
+
credits_charged: Optional[int] = None
|
|
44
|
+
final_result: Optional[str] = None
|
|
45
|
+
input_question: Optional[str] = None
|
|
46
|
+
result_url: Optional[str] = None
|
|
47
|
+
status_url: Optional[str] = None
|
|
48
|
+
raw: dict = field(default_factory=dict, repr=False)
|
|
49
|
+
|
|
50
|
+
@classmethod
|
|
51
|
+
def from_response(cls, body: dict) -> "Job":
|
|
52
|
+
result = body.get("result") or {}
|
|
53
|
+
final_result = result.get("final_result") if isinstance(result, dict) else None
|
|
54
|
+
return cls(
|
|
55
|
+
id=body.get("id") or body.get("job_id") or "",
|
|
56
|
+
status=body.get("status") or "",
|
|
57
|
+
kind=body.get("kind") or "",
|
|
58
|
+
step_count=int(body.get("step_count") or 0),
|
|
59
|
+
progress_done=int(body.get("progress_done") or 0),
|
|
60
|
+
progress_total=int(body.get("progress_total") or 0),
|
|
61
|
+
framework=body.get("framework"),
|
|
62
|
+
live_url=body.get("live_url"),
|
|
63
|
+
agent_id=body.get("agent_id"),
|
|
64
|
+
created_at=body.get("created_at"),
|
|
65
|
+
started_at=body.get("started_at"),
|
|
66
|
+
completed_at=body.get("completed_at"),
|
|
67
|
+
error_message=body.get("error_message"),
|
|
68
|
+
error_code=body.get("error_code"),
|
|
69
|
+
credits_charged=body.get("credits_charged"),
|
|
70
|
+
final_result=final_result,
|
|
71
|
+
input_question=body.get("input_question"),
|
|
72
|
+
result_url=body.get("result_url"),
|
|
73
|
+
status_url=body.get("status_url"),
|
|
74
|
+
raw=body,
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
@property
|
|
78
|
+
def is_terminal(self) -> bool:
|
|
79
|
+
return JobStatus.is_terminal(self.status)
|
|
80
|
+
|
|
81
|
+
@property
|
|
82
|
+
def succeeded(self) -> bool:
|
|
83
|
+
return self.status == JobStatus.COMPLETED and not self.error_message
|
|
84
|
+
|
|
85
|
+
def __str__(self) -> str:
|
|
86
|
+
return f"Job(id={self.id[:8]}…, status={self.status}, steps={self.step_count}/{self.progress_total})"
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
@dataclass
|
|
90
|
+
class Webhook:
|
|
91
|
+
id: str
|
|
92
|
+
url: str
|
|
93
|
+
events: list
|
|
94
|
+
created_at: Optional[str] = None
|
|
95
|
+
last_sent_at: Optional[str] = None
|
|
96
|
+
last_error: Optional[str] = None
|
|
97
|
+
disabled_at: Optional[str] = None
|
|
98
|
+
raw: dict = field(default_factory=dict, repr=False)
|
|
99
|
+
|
|
100
|
+
@classmethod
|
|
101
|
+
def from_response(cls, body: dict) -> "Webhook":
|
|
102
|
+
return cls(
|
|
103
|
+
id=body.get("id") or "",
|
|
104
|
+
url=body.get("url") or "",
|
|
105
|
+
events=list(body.get("events") or []),
|
|
106
|
+
created_at=body.get("created_at"),
|
|
107
|
+
last_sent_at=body.get("last_sent_at"),
|
|
108
|
+
last_error=body.get("last_error"),
|
|
109
|
+
disabled_at=body.get("disabled_at"),
|
|
110
|
+
raw=body,
|
|
111
|
+
)
|
browsa/webhooks.py
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
"""Webhook signature verification for inbound deliveries.
|
|
2
|
+
|
|
3
|
+
The agents service signs every outbound POST with HMAC-SHA256:
|
|
4
|
+
|
|
5
|
+
X-Agents-Signature: t=<unix>, v1=<hex>
|
|
6
|
+
|
|
7
|
+
where v1 = HMAC-SHA256(secret, "<unix>.<raw-request-body>")
|
|
8
|
+
|
|
9
|
+
This module exposes a single function `verify_signature` that returns
|
|
10
|
+
True iff the header matches the body AND the timestamp is within the
|
|
11
|
+
allowed skew (default 300s). Use it in your receiver BEFORE trusting
|
|
12
|
+
any payload field.
|
|
13
|
+
|
|
14
|
+
Example with FastAPI:
|
|
15
|
+
|
|
16
|
+
from fastapi import Request, HTTPException
|
|
17
|
+
from browsa import webhooks
|
|
18
|
+
|
|
19
|
+
SECRET = bytes.fromhex(os.environ["BROWSA_WEBHOOK_SECRET"])
|
|
20
|
+
|
|
21
|
+
@app.post("/webhooks/browsa")
|
|
22
|
+
async def receive(req: Request):
|
|
23
|
+
raw = await req.body()
|
|
24
|
+
sig = req.headers.get("X-Agents-Signature", "")
|
|
25
|
+
if not webhooks.verify_signature(raw, sig, SECRET):
|
|
26
|
+
raise HTTPException(401, "bad signature")
|
|
27
|
+
payload = json.loads(raw)
|
|
28
|
+
...
|
|
29
|
+
"""
|
|
30
|
+
from __future__ import annotations
|
|
31
|
+
|
|
32
|
+
import hashlib
|
|
33
|
+
import hmac
|
|
34
|
+
import time
|
|
35
|
+
from typing import Union
|
|
36
|
+
|
|
37
|
+
DEFAULT_SKEW_SECONDS = 300 # 5 minutes
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def parse_signature_header(header: str) -> tuple[str, str]:
|
|
41
|
+
"""Parse `t=<unix>, v1=<hex>` into (t, v1). Returns ("", "") on parse fail."""
|
|
42
|
+
if not header:
|
|
43
|
+
return "", ""
|
|
44
|
+
t = ""
|
|
45
|
+
v1 = ""
|
|
46
|
+
for part in header.split(","):
|
|
47
|
+
kv = part.strip().split("=", 1)
|
|
48
|
+
if len(kv) != 2:
|
|
49
|
+
continue
|
|
50
|
+
k, v = kv[0].strip(), kv[1].strip()
|
|
51
|
+
if k == "t":
|
|
52
|
+
t = v
|
|
53
|
+
elif k == "v1":
|
|
54
|
+
v1 = v
|
|
55
|
+
return t, v1
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def verify_signature(
|
|
59
|
+
body: Union[bytes, str],
|
|
60
|
+
header: str,
|
|
61
|
+
secret: Union[bytes, str],
|
|
62
|
+
*,
|
|
63
|
+
skew_seconds: int = DEFAULT_SKEW_SECONDS,
|
|
64
|
+
) -> bool:
|
|
65
|
+
"""Verify an X-Agents-Signature header against the raw body.
|
|
66
|
+
|
|
67
|
+
Args:
|
|
68
|
+
body: Raw request body bytes (BEFORE any JSON parsing). Strings
|
|
69
|
+
are utf-8 encoded.
|
|
70
|
+
header: Value of the X-Agents-Signature header.
|
|
71
|
+
secret: Workspace signing secret. Bytes or hex string (the dashboard
|
|
72
|
+
shows it as hex; this function accepts either form).
|
|
73
|
+
skew_seconds: Reject deliveries whose timestamp is more than this many
|
|
74
|
+
seconds away from now. Default 300s. Set to None to disable.
|
|
75
|
+
|
|
76
|
+
Returns:
|
|
77
|
+
True iff signature and timestamp both verify. False otherwise.
|
|
78
|
+
Never raises — always safe to call before parsing body.
|
|
79
|
+
"""
|
|
80
|
+
t, v1 = parse_signature_header(header)
|
|
81
|
+
if not t or not v1:
|
|
82
|
+
return False
|
|
83
|
+
try:
|
|
84
|
+
unix = int(t)
|
|
85
|
+
except ValueError:
|
|
86
|
+
return False
|
|
87
|
+
if skew_seconds is not None:
|
|
88
|
+
now = int(time.time())
|
|
89
|
+
if abs(now - unix) > skew_seconds:
|
|
90
|
+
return False
|
|
91
|
+
|
|
92
|
+
if isinstance(body, str):
|
|
93
|
+
body = body.encode("utf-8")
|
|
94
|
+
if isinstance(secret, str):
|
|
95
|
+
try:
|
|
96
|
+
secret = bytes.fromhex(secret)
|
|
97
|
+
except ValueError:
|
|
98
|
+
secret = secret.encode("utf-8")
|
|
99
|
+
|
|
100
|
+
signed = f"{t}.".encode("utf-8") + body
|
|
101
|
+
expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
|
|
102
|
+
# Constant-time compare — never use ==
|
|
103
|
+
return hmac.compare_digest(expected, v1)
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: browsa
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Official Python SDK for Browsa — anti-detect cloud browsers for AI agents (browsa.io)
|
|
5
|
+
Author-email: Browsa <support@browsa.io>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://browsa.io
|
|
8
|
+
Project-URL: Documentation, https://browsa.io/docs
|
|
9
|
+
Project-URL: Source, https://pypi.org/project/browsa/
|
|
10
|
+
Project-URL: Issues, https://browsa.io/docs
|
|
11
|
+
Keywords: browser-automation,ai-agents,browser-use,anti-detect,captcha-solver,scraping,playwright
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Requires-Python: >=3.9
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
27
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
|
|
28
|
+
Requires-Dist: ruff>=0.1; extra == "dev"
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
# browsa (Python)
|
|
32
|
+
|
|
33
|
+
Anti-detect browsers for AI agents — official Python SDK for [browsa.io](https://browsa.io).
|
|
34
|
+
|
|
35
|
+
[](https://pypi.org/project/browsa/)
|
|
36
|
+
[](https://pypi.org/project/browsa/)
|
|
37
|
+
|
|
38
|
+
## Install
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
pip install browsa
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Zero dependencies. Pure stdlib. Single-file wheel.
|
|
45
|
+
|
|
46
|
+
## Five-line hello world
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from browsa import Client
|
|
50
|
+
|
|
51
|
+
c = Client(api_key="agt_live_...")
|
|
52
|
+
job = c.run_task(
|
|
53
|
+
task="Go to news.ycombinator.com and return the top story title.",
|
|
54
|
+
llm="claude-opus-4-7",
|
|
55
|
+
llm_api_key="sk-ant-...",
|
|
56
|
+
)
|
|
57
|
+
print(job.final_result)
|
|
58
|
+
print("watch live:", job.live_url)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
That runs a real Chromium fork (Phantom — our anti-detect 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.
|
|
62
|
+
|
|
63
|
+
## Async
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import asyncio
|
|
67
|
+
from browsa import AsyncClient
|
|
68
|
+
|
|
69
|
+
async def main():
|
|
70
|
+
async with AsyncClient(api_key="agt_live_...") as c:
|
|
71
|
+
job = await c.run_task(
|
|
72
|
+
task="Scrape the top 5 products on producthunt.com today.",
|
|
73
|
+
llm="claude-opus-4-7",
|
|
74
|
+
llm_api_key="sk-ant-...",
|
|
75
|
+
country="US",
|
|
76
|
+
)
|
|
77
|
+
print(job.final_result)
|
|
78
|
+
|
|
79
|
+
asyncio.run(main())
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Webhooks
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
from browsa import webhooks
|
|
86
|
+
|
|
87
|
+
# In your receiver (Flask/FastAPI/whatever):
|
|
88
|
+
ok = webhooks.verify_signature(
|
|
89
|
+
body=raw_request_body,
|
|
90
|
+
header=request.headers["X-Agents-Signature"],
|
|
91
|
+
secret=os.environ["BROWSA_WEBHOOK_SECRET"], # hex-encoded
|
|
92
|
+
)
|
|
93
|
+
if not ok:
|
|
94
|
+
return 401
|
|
95
|
+
# Trust the payload only after this point.
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## What you get
|
|
99
|
+
|
|
100
|
+
| Capability | Notes |
|
|
101
|
+
|---|---|
|
|
102
|
+
| Sync + async clients | `Client` + `AsyncClient`, same surface |
|
|
103
|
+
| Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
|
|
104
|
+
| Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
|
|
105
|
+
| Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
|
|
106
|
+
| Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
|
|
107
|
+
| `X-Request-Id` propagation | Every error carries the server's request id |
|
|
108
|
+
| Zero deps | Single wheel, audit-friendly, no transitive surface |
|
|
109
|
+
|
|
110
|
+
## Advanced
|
|
111
|
+
|
|
112
|
+
### Long-running tasks with progress callback
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
def show(job):
|
|
116
|
+
print(f" step {job.step_count}/{job.progress_total} status={job.status}")
|
|
117
|
+
|
|
118
|
+
job = c.run_task(
|
|
119
|
+
task="Open-ended research: scrape arxiv for papers on test-time compute, return top 10 by citation.",
|
|
120
|
+
llm="claude-opus-4-7",
|
|
121
|
+
llm_api_key="sk-ant-...",
|
|
122
|
+
max_steps=80,
|
|
123
|
+
on_progress=show,
|
|
124
|
+
)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Interactive (input_required) tasks
|
|
128
|
+
|
|
129
|
+
If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
job = c.create_task(task="...", llm="...", llm_api_key="...")
|
|
133
|
+
while not job.is_terminal:
|
|
134
|
+
job = c.get_job(job.id, wait=30)
|
|
135
|
+
if job.status == "input_required":
|
|
136
|
+
answer = input(f"Agent asks: {job.input_question}\n> ")
|
|
137
|
+
job = c.respond_to_job(job.id, answer)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### JA3-spoofed sessions
|
|
141
|
+
|
|
142
|
+
Some sites fingerprint TLS handshake shape. Set a profile to spoof macOS Chrome:
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
job = c.run_task(
|
|
146
|
+
task="Go to a TLS-fingerprint-fingerprinted site",
|
|
147
|
+
llm="claude-opus-4-7", llm_api_key="sk-...",
|
|
148
|
+
ja3_profile="macos_chrome_137", # uses utls
|
|
149
|
+
)
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## Docs
|
|
153
|
+
|
|
154
|
+
- API reference: <https://browsa.io/docs>
|
|
155
|
+
- Source: <https://github.com/mohasaaid/neout/tree/main/sdks/browsa-python>
|
|
156
|
+
- Issues: <https://github.com/mohasaaid/neout/issues>
|
|
157
|
+
|
|
158
|
+
## License
|
|
159
|
+
|
|
160
|
+
MIT.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
browsa/__init__.py,sha256=YJAHAvLEIRfawoSIhVIiDTT9inCkF__DtJWFybgerh0,1473
|
|
2
|
+
browsa/client.py,sha256=8lDdB0X4uUjfP_LVUjhoQhe888UYEDoYlBVzJjb3qdU,33442
|
|
3
|
+
browsa/errors.py,sha256=L5JX2GWMsFXNqCP3Ia0QqSCxzorzxYFlem8_VNWx7I8,3206
|
|
4
|
+
browsa/types.py,sha256=Vi3sZvqbkOvXjiq7Zl1nkR5Nl2qB0lS-OWwlMlBV6rI,3814
|
|
5
|
+
browsa/webhooks.py,sha256=gIviHzzO4v_VXdzRDIEQKQLD_zuD9hOePnsLCR3XnI8,3151
|
|
6
|
+
browsa-0.1.1.dist-info/licenses/LICENSE,sha256=qypkKrDj5iSqv-21o4ySkR-vG6vXIWsfZh71T0CCpU8,1062
|
|
7
|
+
browsa-0.1.1.dist-info/METADATA,sha256=h60qY5WNMWw_PmT_G545BvdkGWAJQ5X6LjgspR1rjM8,4919
|
|
8
|
+
browsa-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
|
|
9
|
+
browsa-0.1.1.dist-info/top_level.txt,sha256=emwNr0BHwSWj-FAuy4ZLVbYdShd879FoMw32UEVpUn8,7
|
|
10
|
+
browsa-0.1.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 neout
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
browsa
|