scalebrowser 0.2.0__py3-none-any.whl

scalebrowser/models_control.py

@@ -0,0 +1,128 @@
+"""What the browser asks (interruptions), the bytes that go in and out
+(artifacts), and what the licence says (account).
+
+Interruption shapes mirror ``web-ui/src/api/types/credentials.ts``, the shared
+source of contract truth.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from .models import _ReadModel, _WriteModel
+
+#: What an operator has taken out of an agent's hands.
+InterruptionLock = Literal["always_block", "always_allow", "agent_decides"]
+
+#: One answer, in the browser's OWN vocabulary — hence ``allowOnce`` in
+#: camelCase while everything else in this API is snake_case. The daemon's enum
+#: is ``#[serde(rename_all = "camelCase")]``; sending ``allow_once`` is a 400.
+InterruptionChoice = Literal["allow", "allowOnce", "block", "dismiss"]
+
+#: Who wrote a standing rule. An agent must not be able to widen what the
+#: operator allowed, so the two are told apart at rest.
+InterruptionAuthor = Literal["operator", "agent"]
+
+
+class InterruptionLockRow(_ReadModel):
+    kind: str
+    #: ``None`` for the account-wide row.
+    profile_id: Optional[str] = None
+    decision: InterruptionLock
+
+
+class EffectiveInterruptionLock(_ReadModel):
+    """What applies right now for one kind, account-wide."""
+
+    kind: str
+    #: ``None`` means the agent decides.
+    decision: Optional[InterruptionLock] = None
+
+
+class InterruptionLockView(_ReadModel):
+    """Everything about locks in one call, ``effective`` included.
+
+    The daemon computes ``effective`` with the same function the launch path
+    uses. Recomputing it yourself would be a second opinion, and code that
+    disagrees with the browser is worse than code that shows nothing.
+    """
+
+    kinds: list[str] = []
+    locked_by_default: list[str] = []
+    rows: list[InterruptionLockRow] = []
+    effective: list[EffectiveInterruptionLock] = []
+
+
+class SetInterruptionLockBody(_WriteModel):
+    kind: str
+    profile_id: Optional[str] = None
+    decision: InterruptionLock
+
+
+class InterruptionRuleRow(_ReadModel):
+    origin: str
+    kind: str
+    choice: InterruptionChoice
+    author: InterruptionAuthor
+    profile_id: Optional[str] = None
+
+
+class SetInterruptionRuleBody(_WriteModel):
+    origin: str
+    kind: str
+    choice: InterruptionChoice
+    profile_id: Optional[str] = None
+
+
+class ArtifactPutResult(_ReadModel):
+    """The reply to a file handed in for a later upload."""
+
+    artifact_id: str
+    size_bytes: int
+    name: Optional[str] = None
+
+
+class ArtifactBytes(_ReadModel):
+    """Bytes plus what the daemon said they are."""
+
+    data: bytes
+    content_type: Optional[str] = None
+    #: Parsed out of ``Content-Disposition``, when the daemon sent one.
+    filename: Optional[str] = None
+
+
+class Account(_ReadModel):
+    """Licence state, for display.
+
+    The daemon decides on every launch whether a start is allowed; this never
+    gets a say in it. Never gate your own code on it — a green light on a
+    profile the launch gate refuses is worse than no light.
+    """
+
+    #: ``False`` on a self-hosted build with no control plane.
+    licensed: bool = False
+    plan: Optional[str] = None
+    status: Optional[str] = None
+    #: Browsers the subscription may run AT ONCE. Replaced the profile allowance
+    #: on 2026-08-18: profiles are unlimited on every plan now.
+    concurrency: Optional[int] = None
+    #: Browsers running on THIS machine, not the abo-wide count.
+    running_local: int = 0
+    #: Profiles stored on THIS machine.
+    profiles_local: int = 0
+    features: list[str] = []
+    #: Unix seconds; when the cached entitlement stops being valid.
+    expires_at: Optional[int] = None
+    permits_launch: bool = True
+
+
+class HealthStatus(_ReadModel):
+    status: str
+    service: Optional[str] = None
+
+
+class ReadyStatus(_ReadModel):
+    status: str
+    #: Where the daemon looks for engines. Whether one is INSTALLED is a
+    #: launch-time question the preflight answers properly.
+    engines_dir: str = ""

scalebrowser/models_identity.py

@@ -0,0 +1,130 @@
+"""The account layer: mailboxes, passkeys and the one door a cookie value leaves
+through.
+
+Mailbox and passkey shapes mirror ``web-ui/src/api/types/{inboxes,credentials}.ts``,
+the shared source of contract truth. The cookie reveal has no UI counterpart: it
+is a REST-only route deliberately kept off every screen.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from .models import _ReadModel, _WriteModel
+
+#: Which channel a confirmation code arrives on.
+InboxChannel = Literal["email", "sms"]
+
+#: Why a credential disappeared. ``unknown`` is a reason this build cannot name,
+#: and it deliberately claims nothing — reading it as ``operator`` would tell you
+#: that you had deleted something you never touched.
+PasskeyRetiredReason = Literal["operator", "agent", "site_revoked", "unknown"]
+
+
+class Inbox(_ReadModel):
+    """One configured mailbox. The password is never sent back."""
+
+    id: str
+    name: str
+    host: str
+    port: int
+    #: The mailbox login. Not a secret, and it is how two rows are told apart.
+    user: str
+    #: TLS from the first byte. ``False`` is only accepted towards this machine.
+    tls: bool = True
+    folder: str = "INBOX"
+    #: The domain new addresses are minted under. ``None`` for a mailbox with
+    #: exactly one address.
+    address_domain: Optional[str] = None
+    created_at: int
+    #: The stored password could not be decrypted — a restored database without
+    #: its key. The row stays visible and deletable; every use fails closed.
+    credentials_unreadable: bool = False
+
+
+class PutInboxBody(_WriteModel):
+    """Create or update a mailbox.
+
+    An omitted ``password`` means "leave the stored one unchanged", never
+    "delete it" — which is why it is optional on an edit and required on create.
+    """
+
+    name: str
+    host: str
+    port: int
+    user: str
+    password: Optional[str] = None
+    tls: bool = True
+    folder: str = "INBOX"
+    address_domain: Optional[str] = None
+
+
+class InboxBinding(_ReadModel):
+    """What one profile is bound to, per channel."""
+
+    profile_id: str
+    channel: InboxChannel
+    #: The address or number this profile is known by.
+    address: str
+    #: The mailbox that answers. ``None`` means the operator's configured
+    #: command does, which is the only shape an SMS binding can have.
+    inbox_id: Optional[str] = None
+    created_at: int
+
+
+class BindInboxBody(_WriteModel):
+    channel: InboxChannel
+    inbox_id: Optional[str] = None
+    #: Absent mints one under the mailbox's catch-all domain.
+    address: Optional[str] = None
+
+
+class InboxBindings(_ReadModel):
+    bindings: list[InboxBinding] = []
+
+
+class PasskeyRow(_ReadModel):
+    """One passkey of a profile — a login that needs no password.
+
+    ``credential_id`` names the row for deletion and nothing else. The private
+    key has no field here and no endpoint: it IS the account, and it could not
+    be typed anywhere useful, so returning it would be risk without a purpose.
+    """
+
+    credential_id: str
+    #: The site it belongs to, e.g. ``github.com``.
+    rp_id: str
+    user_name: Optional[str] = None
+    user_display: Optional[str] = None
+    created_at: int
+    last_used_at: Optional[int] = None
+    #: True when a stored secret cannot be decrypted — the sign-in WILL fail.
+    secrets_unreadable: bool = False
+    #: When the key stopped being usable, if it has. A retired key is never
+    #: loaded into the browser and never offered to an agent, but it stays
+    #: visible until it is cleared: an account that quietly stops working is the
+    #: first thing anyone asks about.
+    retired_at: Optional[int] = None
+    retired_reason: Optional[PasskeyRetiredReason] = None
+
+
+class RevealedCookie(_ReadModel):
+    """A cookie VALUE skips both the password and the second factor beside it."""
+
+    name: str
+    domain: str
+    path: str
+    value: str
+
+
+class RevealCookiesBody(_WriteModel):
+    #: The same gate a far weaker password sits behind.
+    vault_password: str
+    domain: str
+    #: One cookie by name; omit for every cookie on the domain.
+    name: Optional[str] = None
+
+
+class RevealCookiesResult(_ReadModel):
+    domain: str
+    cookies: list[RevealedCookie] = []

scalebrowser/models_runs.py

@@ -0,0 +1,56 @@
+"""Agent runs and live activity (``/v1/runs``, ``/v1/activity``).
+
+All of it is display: nothing here starts, stops or changes anything.
+
+``RunActor``, ``RunOutcome``, ``StepKind``, ``StepTarget``, ``RunStep`` and
+``ProfileActivity`` are NOT redeclared here — they live in :mod:`.models`
+because the live event stream carries them, and the run list describes the same
+rows. A second copy would let the two drift apart while both looked right.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from .models import ProfileActivity, RunActor, RunOutcome, _ReadModel
+
+#: Who made the outcome claim. ``derived`` means nobody did.
+OutcomeSource = Literal["agent", "check", "human", "derived"]
+
+#: Whether the goal text was stated or merely describes the session.
+GoalSource = Literal["agent", "derived"]
+
+
+class AgentRun(_ReadModel):
+    """One agent run, as the activity view reads it back."""
+
+    id: str
+    #: Groups runs that shared one profile reservation.
+    session_id: str
+    profile_id: str
+    profile_name: str
+    actor: RunActor
+    #: Never empty — described when it was not declared (see :attr:`goal_source`).
+    goal: str
+    goal_source: GoalSource
+    #: ``reached`` and ``partial`` are CLAIMS: the daemon can tell that a run
+    #: ended, never that it worked, so those two only ever come from an agent, a
+    #: check or a person.
+    outcome: RunOutcome
+    outcome_source: Optional[OutcomeSource] = None
+    note: Optional[str] = None
+    started_at: int
+    ended_at: Optional[int] = None
+    step_count: int = 0
+    #: Steps that never reached the trail because the writer queue was full.
+    #: Zero on a healthy run, and worth reading: a trail missing entries looks
+    #: exactly like an agent that did less work.
+    steps_lost: int = 0
+    first_domain: Optional[str] = None
+
+
+class ActivitySnapshot(_ReadModel):
+    """What every running profile currently shows."""
+
+    sampled_at: Optional[int] = None
+    profiles: list[ProfileActivity] = []

scalebrowser-0.2.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: scalebrowser
+Version: 0.2.0
+Summary: Official Python SDK for the Scalebrowser daemon — typed REST client + direct-CDP driver (nodriver-style).
+Project-URL: Homepage, https://scalebrowser.net
+Project-URL: Documentation, https://scalebrowser.net
+Author: Scalebrowser
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-browser,ai-agents,browser,browser-automation,cdp,mcp,scalebrowser
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: websockets>=13
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scalebrowser — Python SDK
+
+Official Python SDK for the [Scalebrowser](https://scalebrowser.net) daemon: a
+typed REST client **plus a direct-CDP driver** (nodriver-style) for the
+self-hosted browser infrastructure that gives each AI agent its own browser.
+
+The driver plane is **direct-CDP, not** Playwright/Puppeteer: anti-bot stacks
+block the Playwright control plane regardless of how good the browser patches
+are. `start_profile` returns a `cdp_ws` endpoint and this SDK speaks the Chrome
+DevTools Protocol over it directly. Credentials never leave the daemon and are
+never logged by the SDK.
+
+## Install
+
+```bash
+pip install scalebrowser
+```
+
+Requires Python ≥ 3.10 and depends on `httpx`, `websockets`, `pydantic` v2. The
+SDK is MIT-licensed; the daemon it talks to is a separate, licensed product.
+
+## Quickstart (sync)
+
+```python
+from scalebrowser import ScalebrowserClient, CreateProfileBody
+
+sb = ScalebrowserClient(base_url="http://127.0.0.1:8787", token="…")
+
+profile = sb.create_profile(CreateProfileBody(name="acct-01"))
+
+# start → direct-CDP connect → navigate → humanized click → stop
+with sb.launch(profile.id, headless=True) as page:
+    page.navigate("https://example.com")
+    print(page.evaluate("document.title"))
+    page.humanize_click(120, 240)        # routed through the daemon trusted-input (G8)
+
+sb.close()
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+from scalebrowser import AsyncScalebrowserClient
+
+async def main():
+    async with AsyncScalebrowserClient(token="…") as sb:
+        started = await sb.start_profile(profile_id, headless=True)   # StartProfileResult
+        async with await sb.connect_cdp(started, profile_id) as page:
+            await page.navigate("https://example.com")
+            title = await page.evaluate("document.title")
+            await page.humanize_click(120, 240)
+        await sb.stop_profile(profile_id)
+
+asyncio.run(main())
+```
+
+## REST surface
+
+Every `/v1` endpoint is a typed method on the client, under the same name in
+both the sync and the async client:
+
+- **Profiles** — `list_profiles`, `get_profile`, `create_profile`,
+  `update_profile`, `delete_profile`, `start_profile`, `stop_profile`
+- **Bulk** — `bulk_create_profiles`, `bulk_start`, `bulk_stop`, `bulk_delete`,
+  `bulk_assign_proxy`
+- **Groups / Presets** — `list_groups`/`create_group`/`get_group`/`update_group`/`delete_group`,
+  `list_presets`/`create_preset`/`get_preset`/`update_preset`/`delete_preset`,
+  `get_persona_constraints`. A preset is `config` (what the profiles do:
+  `geo_mode`, `proxy_id`, …) plus `constraints` (what they are: `country`, which
+  pins the persona's language, timezone and voices). Both are typed
+  (`PresetConfig` / `PresetConstraints`) and the daemon refuses an unknown key
+  with a 400 — read the valid regions from `get_persona_constraints()` rather than
+  hardcoding them.
+- **Proxies** — `list_proxies`/`create_proxy`/`get_proxy`/`update_proxy`/`delete_proxy`/`check_proxy`,
+  plus `check_proxy_config` (probe a config before saving it; pass `id` to reuse
+  an existing proxy's stored credentials)
+- **Extensions** — `list_extensions`, `attach_extension`, `detach_extension`,
+  plus the daemon-wide library (`upload_extension`, `get_library_extension`,
+  `delete_library_extension`). An attached package IS loaded into the browser at
+  launch, under the canonical Web-Store id its own key derives
+- **Credentials** — `list_credentials`, `put_credential`, `reveal_credential`
+  (needs the vault password), `export_credentials`, `import_credentials`
+- **Cookies** — `reveal_cookies`, the one route a cookie VALUE leaves through,
+  behind the same vault password
+- **Sessions** — `export_session`, `import_session`
+- **Mailboxes** — `list_inboxes`, `create_inbox`, `update_inbox`, `delete_inbox`,
+  `get_inbox_bindings`, `bind_inbox`, `unbind_inbox` — where a profile's
+  confirmation codes arrive
+- **Passkeys** — `list_passkeys`, `delete_passkey`. Metadata only: the private
+  key has no field and no endpoint
+- **Agent runs** — `list_runs`, `get_run`, `list_run_steps`, `get_run_shot`,
+  `get_activity`. Read-only, all of it
+- **Interruptions** — `list_interruption_locks`, `set_interruption_lock`,
+  `list_interruption_rules`, `set_interruption_rule`,
+  `delete_interruption_rule` — who may answer when the browser asks something
+- **Artifacts** — `put_artifact` (hand the daemon a file to upload later),
+  `get_artifact` (fetch a screenshot, download or saved PDF as bytes)
+- **Input / Metrics / Account / Events** — `send_input`, `get_metrics`,
+  `get_account`, `health`, `ready`, `events()`
+
+```python
+async for event in sb_async.events():        # SSE lifecycle stream (Bearer-authenticated)
+    print(event.type)                          # typed: profile_started / profile_crashed / …
+```
+
+Errors map the daemon contract: `ApiError(status, code, message)` with codes
+`4001–4010` (`ApiError.is_auth_error` for 401 / 4010); `NetworkError` when the
+daemon is unreachable; `CdpError` for protocol-level failures.
+
+## Direct-CDP driver
+
+`CdpSession` (async) / `SyncCdpSession` give you:
+
+- `send(method, params)` — any CDP command, awaited by `id`
+- `navigate(url)`, `evaluate(expr, isolated=False)` — **never** calls
+  `Runtime.enable` (a detection leak); isolated worlds via
+  `create_isolated_world()`
+- `on(method, cb)` / `events()` — subscribe to CDP events
+- `humanize_move/click/type/scroll` — humanized OS-level input via the daemon
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest                       # unit tests (mock REST + a real fake-CDP ws server)
+SCALEBROWSER_E2E=1 pytest tests/test_e2e.py   # against a real daemon
+```
+
+## Contract assumptions
+
+- Default base URL `http://127.0.0.1:8787`; Bearer token always.
+- The trusted-input body beyond `{action, humanize}` (coordinates, `button`,
+  `delta_x/y`, `text`) is an SDK convention — see `cdp.py`.
+- Two endpoints are optional and answer 404 on a daemon without them, which the
+  SDK treats as information rather than as an error: `get_metrics()` then derives
+  running counts from profile state, and `get_account()` returns
+  `licensed=False`, which is what "self-hosted, no control plane" means.
+- Every method is present on BOTH clients under the same name. The sync client
+  is a hand-written mirror over one background event loop; there is no duplicated
+  endpoint logic.

scalebrowser-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+scalebrowser/__init__.py,sha256=LO-KXc0vC5Nwxxv8iRg4Y3u0FHk77gweFUwSSBoRlhQ,5232
+scalebrowser/_http.py,sha256=Jy8s8uVVNf1gXbu0KyL0IxFRcHPsPkGHvGHXWgWXZBc,7302
+scalebrowser/_sync.py,sha256=aH5Wvo-kwmOWxi0k0a588YgTXT28TjmFt1FwscWF3bA,24565
+scalebrowser/_version.py,sha256=jo6gYau27_G4AJyjriElyTAix57i6fx3UJk35fJuhF8,67
+scalebrowser/cdp.py,sha256=YpRfSK2SsUZS6lud-IUO72K6VKPODBUgQTzePxGYdZs,16506
+scalebrowser/client.py,sha256=lQaDPYuFqXX-risuY4pY2xLTNvyk7IZUaGWCoK7-Pug,36616
+scalebrowser/errors.py,sha256=Du98Ow_Z2wdtLZyvptXSQhcPXvgnwWSIwPAWVg-UsPo,3337
+scalebrowser/events.py,sha256=a65ZypdsFJxWAe06nAErPRKdGNbj8_jU8yUm-HQ2F20,1686
+scalebrowser/models.py,sha256=sAbn_bZjP48C3kQuhZNrC9Hp5kv8SOYH7OyYnfLtZNU,24974
+scalebrowser/models_control.py,sha256=GMZYF7tO7jYiODSYfz7wCXYIID3lplD1NzLl9KMt4Fc,3950
+scalebrowser/models_identity.py,sha256=y1xtclyf2lWGKCXx4TGw1OcD1siLK69uVkhxnx-UrTY,4206
+scalebrowser/models_runs.py,sha256=ul45KLZa2RctK6QQ54LzjLFtwPkfRT04bE6bUJNLlZA,2007
+scalebrowser-0.2.0.dist-info/METADATA,sha256=6QD2SpinSZIwpjcbiemW_qiCmRDe0ZLzrfgxb0m1D8U,7567
+scalebrowser-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+scalebrowser-0.2.0.dist-info/licenses/LICENSE,sha256=_ev9UGCBOfQuc_ESy8jXDlrXrTeUb-t3wg3we1JDTbg,1069
+scalebrowser-0.2.0.dist-info/RECORD,,

scalebrowser-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

scalebrowser-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scalebrowser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.