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 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
+ [![PyPI version](https://img.shields.io/pypi/v/browsa.svg)](https://pypi.org/project/browsa/)
36
+ [![Python](https://img.shields.io/pypi/pyversions/browsa.svg)](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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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