Metadata-Version: 2.5
Name: stealthhub
Version: 0.1.3
Summary: Official Python SDK for StealthHub - Headless Browser as a Service
Author: StealthHub
License-Expression: MIT
Keywords: antidetect,headless-browser,scraper,stealthhub
Requires-Python: >=3.9
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# stealthhub — Python SDK

The official Python SDK for [StealthHub](https://stealthhub.online) — Headless Browser as a Service.

## Installation

```bash
pip install stealthhub
```

## Quick Start

```python
from stealthhub import StealthHub

hub = StealthHub(api_key="sk_your_api_key")

# Create a session
session = hub.create_session(os_type="windows")
cdp_url = hub.get_cdp_url(session["id"])
print(f"CDP URL: {cdp_url}")

# Use with Playwright
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(cdp_url)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())

# Kill session
hub.kill_session(session["id"])
```

## Context Manager

```python
with StealthHub(api_key="sk_your_api_key") as hub:
    session = hub.create_session()
    # ... use session ...
    hub.kill_session(session["id"])
# Connection is automatically closed
```

## API Reference

### Sessions

```python
hub.create_session(profile_id=None, os_type="windows", proxy_url=None, team_id=None, record=False, size=None, stealth=False)
hub.kill_session(session_id)
hub.list_sessions()
hub.get_session_history(page=1, limit=20)
hub.get_recording_url(session_id)
hub.get_cdp_url(session_id)
```

### Fetch & Scrape

```python
# Lightweight HTTP fetch (no browser, fast, 1 credit)
hub.fetch(url, format="html", proxy_url=None, headers=None, extract=None)

# Full browser render (JS/SPA support, credits per minute)
hub.scrape(url, format="html", wait_for=None, timeout=30000, screenshot=False, proxy_url=None, extract=None)
```

**Structured data extraction:**
```python
result = hub.fetch(
    url="https://shopee.vn/product/123",
    extract={
        "title": "h1",
        "price": ".price",
        "images": "img[src]"
    }
)
# result["structured_data"] = {"title": "iPhone 15", "price": "29.990.000₫", "images": [...]}
```

### Profiles

```python
hub.create_profile(name, os_type="windows")
hub.list_profiles()
hub.delete_profile(profile_id)
```

### Billing

```python
hub.get_balance()
hub.get_history(page=1, limit=20)
hub.get_pricing()
hub.create_deposit(amount)  # VietQR deposit, amount in VND (min 10,000)
```

### Auth

```python
hub.get_me()
```

### Search

```python
hub.search(query, limit=10, country="us")
```

### CAPTCHA

```python
hub.solve_captcha(session_id, captcha_type, site_key, page_url)
```


### Webhooks

```python
hub.register_webhook(url, secret, events=None)
hub.list_webhooks()
hub.delete_webhook(webhook_id)
```

### Teams

```python
hub.get_teams()
hub.create_team(name)
hub.add_team_member(team_id, email, role="member")
```

### API Keys

```python
hub.create_api_key(name)
hub.list_api_keys()
hub.revoke_api_key(key_id)
```

### Credentials

```python
hub.create_credential(name, username, password, notes=None)
hub.list_credentials()
hub.delete_credential(credential_id)
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `STEALTHHUB_API_KEY` | API key (alternative to constructor argument) |

## Requirements

- Python 3.10+
- `requests` library

## License

MIT
