Metadata-Version: 2.4
Name: webskillet
Version: 0.1.1
Summary: Python SDK for the Webskillet runs API
Author-email: Webskillet <engineering@intunedhq.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: pydantic<3,>=2.11.0
Description-Content-Type: text/markdown

# webskillet

The official Python SDK for the [Webskillet](https://webskillet.ai) API. Run web
tasks programmatically, poll for results, and manage skillets and auth sessions —
with full type hints and Pydantic models throughout.

## Installation

```bash
pip install webskillet
```

Requires Python 3.10+.

## Quickstart

```python
from webskillet_client import WebskilletClient

with WebskilletClient(api_key="your-webskillet-api-key") as client:
    result = client.runs.run(
        body={
            "task": "Extract the title of example.com",
            "startUrl": "https://example.com",
            "skilletId": "example-title",
        },
        timeout_seconds=600,
    )
    print(result.status, getattr(result, "result", None))
```

`runs.run()` starts a run and polls every five seconds until it is `completed`
or `canceled`. It waits indefinitely by default; pass `timeout_seconds` to stop
waiting after a fixed duration (raises `TimeoutError`). A run that completes
with `outcome="failed"` raises `RunFailedError`.

## Async usage

`AsyncWebskilletClient` exposes the same services with the same signatures:

```python
from webskillet_client import AsyncWebskilletClient

async with AsyncWebskilletClient(api_key="your-webskillet-api-key") as client:
    result = await client.runs.run(body={"task": "Extract the page title"})
```

## Managing runs manually

Skip `runs.run()` when you need custom polling or fire-and-forget behavior:

```python
started = client.runs.start(body={"task": "Extract the page title"})
current = client.runs.get(run_id=started.id)
updated = client.runs.update(
    run_id=started.id,
    body={"title": "Example page title"},
)
recent = client.runs.list(limit=20)
```

## Skillets and auth sessions

```python
skillets = client.skillets.list()

sessions = client.auth_sessions.list()
session = client.auth_sessions.get(auth_session_id=sessions[0].id)
recording = client.auth_sessions.record(
    body={"name": "GitHub", "startUrl": "https://github.com/login"}
)
```

## Error handling

All errors inherit from `WebskilletError`, so one `except` clause covers
everything. Catch more specific types when you need to branch:

```python
from webskillet_client import (
    AuthenticationError,  # 401/403 — missing or invalid API key
    NotFoundError,        # 404
    ValidationError,      # other 4xx
    ServerError,          # 5xx
    NetworkError,         # connection, DNS, TLS, or timeout failures
    RunFailedError,       # run completed with outcome="failed"
)

try:
    result = client.runs.run(body={"task": "Extract the page title"})
except RunFailedError as e:
    print(f"Run {e.run_id} failed: {e.error}")
except AuthenticationError:
    print("Check your API key")
```

API errors carry `status_code` and the response `body`; `RunFailedError`
carries `run_id` and the run's `error` payload.

## Configuration

```python
client = WebskilletClient(
    api_key="your-webskillet-api-key",
    base_url="https://webskillet.ai",  # default
    timeout=30.0,                       # per-request timeout in seconds
)
```

Requests authenticate with the `x-api-key` header. You can also pass a
preconfigured `httpx.Client` (or `httpx.AsyncClient`) via the `client`
parameter for custom proxies, retries, or transports.
