Metadata-Version: 2.4
Name: helixwright
Version: 0.1.0
Summary: Python automation SDK for Helix Browser Local API and the private Helix RPC page-control plane.
Author: Helix Browser
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://pypi.org/project/helixwright/
Project-URL: Documentation, https://pypi.org/project/helixwright/
Keywords: automation,browser,fingerprint,chromium,local-api,helix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Helixwright

Helixwright is the Python automation SDK for Helix Browser.

It does not create fingerprints locally, manage browser profile folders, or
start `chrome.exe` directly. Profile creation, fingerprint generation, proxy
configuration, browser launch, and profile sync are delegated to Helix Browser
Desktop through its Local API. Page actions then use the private Helix RPC
control plane built into the Helix Chromium fork, not CDP, DevTools, WebDriver,
Playwright, or Selenium.

## Install

```bash
pip install helixwright
```

Requirements:

1. Helix Browser Desktop is installed and running.
2. The desktop app is logged in.
3. The desktop Local API is available, usually at `http://127.0.0.1:59777`.
4. The desktop build supports `/api/v1/automation/sessions`.

Helixwright discovers the Local API from:

```text
%APPDATA%\Helix Browser\local_api.json
```

You can override it explicitly:

```powershell
$env:HELIX_LOCAL_API = "http://127.0.0.1:59777"
```

## Quick Start

Reuse an existing Helix profile:

```python
import helixwright as hw

with hw.launch(profile_id="profile_123", url="https://example.com") as page:
    page.ele("#email").input("user@example.com")
    page.ele("#submit").click()
```

Create or reuse a profile by `account_id`:

```python
import helixwright as hw

with hw.launch(
    "https://example.com",
    account_id="shop-001",
    name="Shop 001",
    proxy="http://user:pass@127.0.0.1:7890",
    fingerprint=hw.Fingerprint(locale="en-US", region="US", group="octo"),
    update_existing=True,
) as page:
    page.wait_for("body", timeout=10_000)
    print(page.title())
```

Use a reusable launch config:

```python
import helixwright as hw

cfg = hw.LaunchConfig(
    account_id="shop-002",
    name="Shop 002",
    url="https://example.com",
    start_pages=["https://example.com", "https://example.com/login"],
    proxy="http://127.0.0.1:7890",
    fingerprint=hw.Fingerprint(locale="en-US", region="US"),
    update_existing=True,
)

with hw.launch(config=cfg) as page:
    page.ele("text=Login").click()
```

## Client API

Use `Client` when you want to manage profiles, fingerprints, proxies, cores, or
automation sessions explicitly:

```python
import helixwright as hw

client = hw.Client()
print(client.health())
print(client.session())

profile = client.profiles.ensure(
    account_id="shop-003",
    name="Shop 003",
    proxy=hw.Proxy("http", "127.0.0.1", 7890),
    fingerprint=hw.Fingerprint(locale="en-US", region="US"),
    update_existing=True,
)

with profile.launch(url="https://example.com") as page:
    print(page.url)
```

Common managers:

```python
client.profiles.list(page=1, size=20)
client.profiles.get("profile_123")
client.profiles.create(name="A", account_id="acct_A")
client.profiles.ensure(account_id="acct_A")
client.profiles.clone("profile_123", count=2)
client.profiles.sync_up("profile_123")
client.profiles.sync_down("profile_123")

client.fingerprint.options()
client.fingerprint.draw(account_id="acct_A", group="octo")
client.fingerprint.serialize({"ua": "..."}, seed=123)
client.fingerprint.redraw({"ua": "..."}, "ua")

client.proxy.check("http://127.0.0.1:7890")
client.cores.list()
client.cores.ensure("chromium", "150")
client.browser.active()
client.browser.start("profile_123")
client.browser.stop("profile_123")
client.browser.stop_all()
client.automation.list()
client.automation.start("profile_123", url="https://example.com")
client.automation.stop("auto_123")
```

## Launch Rules

`hw.launch()` requires either `profile_id` or `account_id`/`account`.

Important behavior:

- `profile_id` means reuse that exact Helix profile.
- `account_id` means find an existing profile by account ID, or create one
  when `create=True`.
- `fingerprint=hw.Fingerprint(...)` only sends creation hints to Helix Local
  API. The SDK does not generate fingerprints itself.
- `proxy` can be a string, dict, or `hw.Proxy`.
- `start_pages` is passed to the Local API automation session.
- `config=hw.LaunchConfig(...)` should not be mixed with explicit
  `profile_id`, `account_id`, `name`, `proxy`, or `fingerprint` arguments.

Unsupported legacy direct-launch arguments are rejected, including `chrome`,
`user_data_dir`, `persona`, `seed`, `geoip`, and `extra_args`.

## Errors

Common error types:

| Error | Meaning |
| --- | --- |
| `LocalApiUnavailable` | Helix Desktop is not running, the Local API address is wrong, or the port is unreachable. |
| `DesktopNotLoggedIn` | Desktop is reachable but not logged in. |
| `LocalApiError` | Local API returned a business error. |
| `ProfileNotFound` | The requested profile does not exist. |
| `AutomationEndpointUnavailable` | The desktop build did not return a usable automation RPC endpoint. |
| `AutomationSessionNotFound` | The requested automation session does not exist. |
| `TransportError` | The private page RPC connection failed, usually because the browser exited. |
| `WaitTimeoutError` | A page wait condition timed out. |

## Examples

From the source repository:

```powershell
cd "E:\Helix Browser\repos\helixwright"
python examples\99_offline_mock_demo.py
```

The offline demo does not need Helix Browser. It starts a mock Local API and
mock RPC endpoint, then exercises the public SDK surface.

Real desktop examples require Helix Browser Desktop to be running and logged in:

```powershell
python examples\00_helixwright_quickstart.py
python examples\01_client_managers.py
python examples\02_launch_config_and_actions.py
```

Useful environment variables:

```powershell
$env:HELIX_LOCAL_API = "http://127.0.0.1:59777"
$env:HELIX_EXAMPLE_ACCOUNT = "demo-account"
$env:HELIX_EXAMPLE_URL = "https://example.com"
$env:HELIX_EXAMPLE_PROXY = "http://127.0.0.1:7890"
$env:HELIX_EXAMPLE_TIMEOUT_MS = "30000"
```

## Development

```powershell
cd "E:\Helix Browser\repos\helixwright"
pip install -e .
python tests\ci.py
```

Build and validate a distribution:

```powershell
python -m build
python -m twine check dist/*
```

## Boundary

Helixwright is only the automation SDK. The authoritative source for profiles,
fingerprints, proxies, browser core downloads, cloud sync, and launch lifecycle
is Helix Browser Desktop plus its Local API.

