# chaser-sdk

Official Python SDK for Chaser.

This package is the Python SDK for the core public Chaser surface:

- sessions
- workspaces
- exec
- command lifecycle
- files
- runtime self-tests and preview URLs
- browser CDP helpers
- accounts and organizations
- service accounts and keys
- billing
- lifecycle webhooks
- audit
- jobs

## Installation

```bash
pip install chaser-sdk
```

Optional CDP websocket support:

```bash
pip install 'chaser-sdk[cdp]'
```

## Quickstart

```py
from chaser_sdk import ChaserClient

client = ChaserClient(api_key="sk_...", account="personal")

workspace = client.workspaces.create(
    {
        "name": "frontend-app",
        "session_type": "sandbox",
        "image": "ghcr.io/example/dev:latest",
    }
)

session = client.sessions.create(
    {
        "workspace": workspace["name"],
        "session_type": "sandbox",
    }
)

client.sessions.wait_until_ready(session["id"])
result = client.exec.in_session(
    session["id"],
    {
        "command": "node -v && pwd",
        "cwd": "/workspace",
    },
)

print(result.get("output"))
```

## Stateless exec

```py
result = client.exec.run(
    {
        "ephemeral": True,
        "image": "node:20-bookworm",
        "command": "python3 -c 'print(42)'",
    }
)
```

## Files and previews

```py
client.files.upload_text(session["id"], "/workspace/hello.txt", "hello from sdk")
text = client.files.download_text(session["id"], "/workspace/hello.txt")
preview = client.sessions.forward_url(session["id"], 3000)
```

## Runtime self-test

```py
diagnostics = client.sessions.self_test(session["id"])
print(diagnostics["runtime"]["tools"].get("node"))
```

## Network controls

```py
session = client.sessions.create(
    {
        "ephemeral": True,
        "session_type": "sandbox",
        "network": {
            "mode": "proxy",
            "proxy": {
                "url": "socks5h://proxy.example.com:1080",
                "username": "svc-user",
                "password": "svc-pass",
            },
        },
    }
)
```

## Browser CDP helper

```py
browser = client.sessions.create({"session_type": "browser", "ephemeral": True})
ws_url = client.browser.cdp_websocket_url(browser["id"])
print(ws_url)
```

If you install the optional `cdp` extra, you can also open a lightweight websocket client:

```py
cdp = client.browser.connect(browser["id"])
print(cdp.send("Browser.getVersion"))
cdp.close()
```

## Organization automation

```py
org_client = client.with_account("Acme Engineering")
service_account = org_client.accounts.service_accounts.create("ci-bot")
key = org_client.accounts.service_accounts.keys.create(
    service_account["id"],
    name="ci-key",
    scopes=["sessions.read", "workspaces.write", "exec.write", "files.read", "webhooks.write"],
)
print(key["key"])
```
