stealthhub 0.1.0__tar.gz

stealthhub-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Ignore environment variables
+.env
+.env.prod
+
+# Ignore binaries
+server
+server.exe
+worker
+worker.exe
+
+# Ignore node_modules in scripts
+scripts/node_modules/
+
+scripts/screenshot_test.png
+
+sdks/nodejs/node_modules/
+tests/fingerprint-test/node_modules
+
+tests/e2e/node_modules/*
+tests/e2e/node_modules

stealthhub-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: stealthhub
+Version: 0.1.0
+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.io) — 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)
+hub.kill_session(session_id)
+hub.list_sessions()
+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.create_deposit(amount)  # VietQR deposit, amount in VND (min 10,000)
+```
+
+### CAPTCHA
+
+```python
+hub.solve_captcha(session_id, captcha_type, site_key, page_url)
+```
+
+### OTP
+
+```python
+hub.request_otp(service, country="vn")
+hub.list_otps()
+```
+
+### 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

stealthhub-0.1.0/README.md

@@ -0,0 +1,153 @@
+# stealthhub — Python SDK
+
+The official Python SDK for [StealthHub](https://stealthhub.io) — 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)
+hub.kill_session(session_id)
+hub.list_sessions()
+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.create_deposit(amount)  # VietQR deposit, amount in VND (min 10,000)
+```
+
+### CAPTCHA
+
+```python
+hub.solve_captcha(session_id, captcha_type, site_key, page_url)
+```
+
+### OTP
+
+```python
+hub.request_otp(service, country="vn")
+hub.list_otps()
+```
+
+### 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

stealthhub-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stealthhub"
+version = "0.1.0"
+description = "Official Python SDK for StealthHub - Headless Browser as a Service"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = [
+    "requests>=2.28.0"
+]
+authors = [
+  { name="StealthHub" }
+]
+keywords = ["stealthhub", "headless-browser", "scraper", "antidetect"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["stealthhub"]

stealthhub-0.1.0/stealthhub/__init__.py

@@ -0,0 +1,4 @@
+from .client import StealthHub
+
+__version__ = "0.1.0"
+__all__ = ["StealthHub"]

stealthhub-0.1.0/stealthhub/client.py

@@ -0,0 +1,193 @@
+import os
+from typing import Any, Optional
+
+import requests
+
+
+class StealthHub:
+    """StealthHub Python SDK — Full API client for Headless Browser as a Service."""
+
+    def __init__(self, api_key: str | None = None, base_url: str = "http://localhost:8080/v1"):
+        self.api_key = api_key or os.environ.get("STEALTHHUB_API_KEY")
+        if not self.api_key:
+            raise ValueError("API key must be provided")
+        self.base_url = base_url
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        })
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.session.close()
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        res = self.session.request(method, f"{self.base_url}{path}", **kwargs)
+        res.raise_for_status()
+        data = res.json()
+        return data.get("data", data)
+
+    # --- Sessions ---
+
+    def create_session(
+        self,
+        profile_id: str | None = None,
+        os_type: str = "windows",
+        proxy_url: str | None = None,
+        team_id: str | None = None,
+        record: bool = False,
+    ) -> dict[str, Any]:
+        """Creates a new headless browser session."""
+        payload: dict[str, Any] = {"os": os_type, "record": record}
+        if profile_id:
+            payload["profile_id"] = profile_id
+        if proxy_url:
+            payload["proxy_url"] = proxy_url
+        if team_id:
+            payload["team_id"] = team_id
+        return self._request("POST", "/sessions", json=payload)
+
+    def kill_session(self, session_id: str) -> bool:
+        """Kills an active session."""
+        self._request("DELETE", f"/sessions/{session_id}")
+        return True
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """Lists active sessions."""
+        return self._request("GET", "/sessions/list")
+
+    def get_cdp_url(self, session_id: str) -> str:
+        """Helper to construct CDP URL for Playwright/Puppeteer."""
+        ws_base = self.base_url.replace("http", "ws", 1)
+        return f"{ws_base}/cdp/{session_id}?api_key={self.api_key}"
+
+    # --- Fetch & Scrape ---
+
+    def fetch(
+        self,
+        url: str,
+        format: str = "html",
+        proxy_url: str | None = None,
+        headers: dict[str, str] | None = None,
+        extract: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Lightweight HTTP fetch (no browser). Fast and cheap."""
+        payload: dict[str, Any] = {"url": url, "format": format}
+        if proxy_url:
+            payload["proxy_url"] = proxy_url
+        if headers:
+            payload["headers"] = headers
+        if extract:
+            payload["extract"] = extract
+        return self._request("POST", "/fetch", json=payload)
+
+    def scrape(
+        self,
+        url: str,
+        format: str = "html",
+        wait_for: str | None = None,
+        timeout: int = 30000,
+        screenshot: bool = False,
+        proxy_url: str | None = None,
+        extract: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Full browser render + extract. Accurate for SPAs and JS-heavy pages."""
+        payload: dict[str, Any] = {"url": url, "format": format, "timeout": timeout, "screenshot": screenshot}
+        if wait_for:
+            payload["wait_for"] = wait_for
+        if proxy_url:
+            payload["proxy_url"] = proxy_url
+        if extract:
+            payload["extract"] = extract
+        return self._request("POST", "/scrape", json=payload)
+
+    # --- Profiles ---
+
+    def create_profile(self, name: str, os_type: str = "windows") -> dict[str, Any]:
+        return self._request("POST", "/profiles/create", json={"name": name, "os": os_type})
+
+    def list_profiles(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/profiles")
+
+    def delete_profile(self, profile_id: str) -> dict[str, Any]:
+        return self._request("POST", "/profiles/delete", json={"id": profile_id})
+
+    # --- Billing ---
+
+    def get_balance(self) -> dict[str, Any]:
+        return self._request("GET", "/billing/balance")
+
+    def get_history(self, page: int = 1, limit: int = 20) -> list[dict[str, Any]]:
+        return self._request("GET", f"/billing/history?page={page}&limit={limit}")
+
+    def create_deposit(self, amount: int) -> dict[str, Any]:
+        """Create VietQR deposit order. Amount in VND (min 10,000)."""
+        return self._request("POST", "/billing/deposit", json={"amount": amount})
+
+    # --- CAPTCHA ---
+
+    def solve_captcha(self, session_id: str, captcha_type: str, site_key: str, page_url: str) -> dict[str, Any]:
+        return self._request("POST", "/captcha/solve", json={
+            "session_id": session_id,
+            "type": captcha_type,
+            "site_key": site_key,
+            "page_url": page_url,
+        })
+
+    # --- OTP ---
+
+    def request_otp(self, service: str, country: str = "vn") -> dict[str, Any]:
+        return self._request("POST", "/otp/request", json={"service": service, "country": country})
+
+    def list_otps(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/otp/list")
+
+    # --- Webhooks ---
+
+    def register_webhook(self, url: str, secret: str, events: list[str] | None = None) -> dict[str, Any]:
+        return self._request("POST", "/webhooks", json={"url": url, "secret": secret, "events": events or ["*"]})
+
+    def list_webhooks(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/webhooks")
+
+    def delete_webhook(self, webhook_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/webhooks/{webhook_id}")
+
+    # --- Teams ---
+
+    def get_teams(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/teams")
+
+    def create_team(self, name: str) -> dict[str, Any]:
+        return self._request("POST", "/teams/create", json={"name": name})
+
+    def add_team_member(self, team_id: str, email: str, role: str = "member") -> dict[str, Any]:
+        return self._request("POST", "/teams/add-member", json={"team_id": team_id, "email": email, "role": role})
+
+    # --- API Keys ---
+
+    def create_api_key(self, name: str) -> dict[str, Any]:
+        return self._request("POST", "/api-keys", json={"name": name})
+
+    def list_api_keys(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/api-keys")
+
+    def revoke_api_key(self, key_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/api-keys/{key_id}")
+
+    # --- Credentials ---
+
+    def create_credential(self, name: str, username: str, password: str, notes: str | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {"name": name, "username": username, "password": password}
+        if notes:
+            payload["notes"] = notes
+        return self._request("POST", "/credentials", json=payload)
+
+    def list_credentials(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/credentials")
+
+    def delete_credential(self, credential_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/credentials/{credential_id}")