borealhost-sdk 0.1.0__tar.gz

borealhost_sdk-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+venv/
+.pytest_cache/
+db.sqlite3
+
+# Node
+node_modules/
+dist/
+bun.lock
+
+# Secrets
+.env
+*.key
+*.pem
+secrets/
+.ssh/
+
+# Claude Code
+.claude/
+.mcp.json
+
+# Deploy artifacts & large files
+*.tar.gz
+*.tar
+*.mo
+
+# Backups
+*.bak.*
+
+# OS
+.DS_Store
+*.swp
+*~

borealhost_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: borealhost-sdk
+Version: 0.1.0
+Summary: Python SDK for the BorealHost.ai REST API — agent-native web hosting
+Project-URL: Homepage, https://borealhost.ai
+Project-URL: Documentation, https://borealhost.ai/api/v1/docs/
+Project-URL: Repository, https://github.com/alainsvrd/platform
+Author-email: BorealHost <hello@borealhost.ai>
+License: MIT
+Keywords: api,borealhost,hosting,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# BorealHost Python SDK
+
+Python SDK for the [BorealHost.ai](https://borealhost.ai) REST API.
+
+BorealHost is an agent-native Quebec-based web hosting platform. This SDK wraps the full public REST API (`/api/v1/*`) — purchase hosting, deploy sites, manage DNS, register domains, run SSH commands, and scale infrastructure.
+
+## Install
+
+```bash
+pip install borealhost-sdk
+```
+
+## Usage
+
+```python
+from borealhost_sdk import Client
+
+client = Client(api_key="bh_...")
+
+# List plans (no auth needed)
+plans = client.list_plans()
+
+# Manage sites
+sites = client.list_sites()
+status = client.get_site("my-site")
+client.deploy("my-site")
+
+# DNS
+client.add_domain_dns("example.com", record_type="A", value="1.2.3.4", subdomain="www")
+```
+
+## Authentication
+
+API keys are in the format `bh_<48 hex chars>`.
+
+```python
+# Pass at construction
+client = Client(api_key="bh_...")
+
+# Or via environment variable
+# export BOREALHOST_API_KEY="bh_..."
+client = Client()
+
+# Or set later
+client = Client()
+client.set_api_key("bh_...")
+```
+
+## Custom base URL
+
+```python
+client = Client(api_key="bh_...", base_url="https://staging.borealhost.ai")
+```
+
+## Errors
+
+All errors from the API raise `ApiError`:
+
+```python
+from borealhost_sdk import Client, ApiError
+
+try:
+    client.deploy("unknown-site")
+except ApiError as e:
+    print(e.code)     # "NOT_FOUND"
+    print(e.message)  # "Site 'unknown-site' not found"
+```
+
+## Related packages
+
+- [`borealhost`](https://pypi.org/project/borealhost/) — command-line tool (`bh`)
+- [`borealhost-mcp`](https://pypi.org/project/borealhost-mcp/) — MCP server for AI agents
+
+## Links
+
+- API docs: https://borealhost.ai/api/v1/docs/
+- Homepage: https://borealhost.ai

borealhost_sdk-0.1.0/README.md

@@ -0,0 +1,77 @@
+# BorealHost Python SDK
+
+Python SDK for the [BorealHost.ai](https://borealhost.ai) REST API.
+
+BorealHost is an agent-native Quebec-based web hosting platform. This SDK wraps the full public REST API (`/api/v1/*`) — purchase hosting, deploy sites, manage DNS, register domains, run SSH commands, and scale infrastructure.
+
+## Install
+
+```bash
+pip install borealhost-sdk
+```
+
+## Usage
+
+```python
+from borealhost_sdk import Client
+
+client = Client(api_key="bh_...")
+
+# List plans (no auth needed)
+plans = client.list_plans()
+
+# Manage sites
+sites = client.list_sites()
+status = client.get_site("my-site")
+client.deploy("my-site")
+
+# DNS
+client.add_domain_dns("example.com", record_type="A", value="1.2.3.4", subdomain="www")
+```
+
+## Authentication
+
+API keys are in the format `bh_<48 hex chars>`.
+
+```python
+# Pass at construction
+client = Client(api_key="bh_...")
+
+# Or via environment variable
+# export BOREALHOST_API_KEY="bh_..."
+client = Client()
+
+# Or set later
+client = Client()
+client.set_api_key("bh_...")
+```
+
+## Custom base URL
+
+```python
+client = Client(api_key="bh_...", base_url="https://staging.borealhost.ai")
+```
+
+## Errors
+
+All errors from the API raise `ApiError`:
+
+```python
+from borealhost_sdk import Client, ApiError
+
+try:
+    client.deploy("unknown-site")
+except ApiError as e:
+    print(e.code)     # "NOT_FOUND"
+    print(e.message)  # "Site 'unknown-site' not found"
+```
+
+## Related packages
+
+- [`borealhost`](https://pypi.org/project/borealhost/) — command-line tool (`bh`)
+- [`borealhost-mcp`](https://pypi.org/project/borealhost-mcp/) — MCP server for AI agents
+
+## Links
+
+- API docs: https://borealhost.ai/api/v1/docs/
+- Homepage: https://borealhost.ai

borealhost_sdk-0.1.0/borealhost_sdk/__init__.py

@@ -0,0 +1,82 @@
+"""BorealHost Python SDK.
+
+The primary interface is the :class:`Client` class::
+
+    from borealhost_sdk import Client
+    client = Client(api_key="bh_...")
+    client.list_plans()
+
+A module-level flat function interface is also provided for backward
+compatibility and convenience. These functions operate on a shared default
+``Client`` instance::
+
+    import borealhost_sdk as bh
+    bh.set_session_key("bh_...")
+    bh.list_plans()
+"""
+
+from .client import Client
+from .exceptions import ApiError
+
+__all__ = ["Client", "ApiError", "set_session_key", "get_session_key"]
+
+__version__ = "0.1.0"
+
+
+# ── Shared default client for the module-level flat function interface ──
+
+_default = Client()
+
+
+def set_session_key(key):
+    """Set the API key on the shared default client.
+
+    Equivalent to ``Client().set_api_key(key)`` but mutates the shared
+    default client used by all module-level function calls.
+    """
+    _default.set_api_key(key)
+
+
+def get_session_key():
+    """Return the API key of the shared default client (or empty string)."""
+    return _default.get_api_key()
+
+
+def _get_default_client():
+    """Return the shared default client (internal use)."""
+    return _default
+
+
+# ── Module-level flat function shims ──
+#
+# Every public method on ``Client`` is re-exposed as a top-level function
+# that delegates to the shared default client. This preserves the flat
+# ``borealhost_sdk.list_plans(...)`` interface without duplicating code.
+#
+# Adding a new method to ``Client`` automatically exposes it at the module
+# level — no bookkeeping required.
+
+def _make_shim(name):
+    method = getattr(Client, name)
+
+    def shim(*args, **kwargs):
+        return getattr(_default, name)(*args, **kwargs)
+
+    shim.__name__ = name
+    shim.__qualname__ = name
+    shim.__doc__ = method.__doc__ or f"Delegates to Client.{name}() on the shared default client."
+    return shim
+
+
+for _name in dir(Client):
+    if _name.startswith("_"):
+        continue
+    if _name in ("set_api_key", "get_api_key"):
+        # These correspond to set_session_key / get_session_key above.
+        continue
+    _attr = getattr(Client, _name)
+    if callable(_attr):
+        globals()[_name] = _make_shim(_name)
+        __all__.append(_name)
+
+del _name, _attr

borealhost_sdk-0.1.0/borealhost_sdk/client.py

@@ -0,0 +1,779 @@
+"""BorealHost REST API client.
+
+Wraps the public REST API at https://borealhost.ai/api/v1/ with a single
+``Client`` class. All 100+ endpoints are exposed as instance methods.
+
+Example:
+
+    from borealhost_sdk import Client
+
+    client = Client(api_key="bh_...")
+    plans = client.list_plans()
+    client.deploy("my-site")
+"""
+
+import httpx
+
+from .config import DEFAULT_API_KEY, DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from .exceptions import ApiError
+
+
+class Client:
+    """HTTP client for the BorealHost REST API.
+
+    Args:
+        api_key: API key in ``bh_<48 hex chars>`` format. Falls back to the
+            ``BOREALHOST_API_KEY`` env var.
+        base_url: API root (default ``https://borealhost.ai``, override with
+            ``BOREALHOST_BASE_URL`` env var).
+        timeout: Default HTTP timeout in seconds.
+    """
+
+    def __init__(self, api_key=None, base_url=None, timeout=DEFAULT_TIMEOUT):
+        self.api_key = api_key if api_key is not None else DEFAULT_API_KEY
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.api_base = f"{self.base_url}/api/v1"
+        self.timeout = timeout
+        # Checkout secrets — keyed by checkout_id, auto-stored on create_checkout.
+        self._checkout_secrets = {}
+
+    # ── Session / auth helpers ──
+
+    def set_api_key(self, key):
+        """Set the API key used by subsequent authenticated calls."""
+        self.api_key = key
+
+    def get_api_key(self):
+        """Return the current API key (or empty string)."""
+        return self.api_key
+
+    def _headers(self, api_key=None):
+        h = {"Content-Type": "application/json"}
+        key = api_key if api_key is not None else self.api_key
+        if key:
+            h["Authorization"] = f"Bearer {key}"
+        return h
+
+    def _checkout_headers(self, checkout_id):
+        """Build headers with checkout_secret if available."""
+        h = {"Content-Type": "application/json"}
+        secret = self._checkout_secrets.get(checkout_id)
+        if secret:
+            h["X-Checkout-Secret"] = secret
+        return h
+
+    def _handle(self, resp):
+        """Parse API response envelope, raise ApiError on failure."""
+        try:
+            data = resp.json()
+        except ValueError:
+            raise ApiError(
+                code="INVALID_RESPONSE",
+                message=f"Non-JSON response (status {resp.status_code})",
+                status_code=resp.status_code,
+            )
+        if not data.get("ok", False):
+            error = data.get("error", {}) or {}
+            meta = data.get("meta", {}) or {}
+            raise ApiError(
+                code=error.get("code", "UNKNOWN"),
+                message=error.get("message", "Unknown error"),
+                status_code=resp.status_code,
+                request_id=meta.get("request_id"),
+            )
+        return data.get("data")
+
+    # ── Auth (unauthenticated) ──
+
+    def register(self, email=None, name="Agent Key"):
+        """Register an agent account and get an API key."""
+        body = {"name": name}
+        if email:
+            body["email"] = email
+        resp = httpx.post(
+            f"{self.api_base}/auth/register/",
+            headers={"Content-Type": "application/json"},
+            json=body,
+            timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def whoami(self):
+        """Get current account info from API key."""
+        resp = httpx.get(f"{self.api_base}/auth/whoami/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    # ── Plans (unauthenticated) ──
+
+    def list_plans(self, include_deprecated=False, track=None):
+        params = {}
+        if include_deprecated:
+            params["include_deprecated"] = "true"
+        if track:
+            params["track"] = track
+        resp = httpx.get(f"{self.api_base}/plans/", headers=self._headers(), params=params, timeout=self.timeout)
+        return self._handle(resp)
+
+    def get_plan(self, slug):
+        resp = httpx.get(f"{self.api_base}/plans/{slug}/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    # ── ACP Checkout (unauthenticated) ──
+
+    def create_checkout(self, sku):
+        """Create an ACP checkout session for a plan SKU."""
+        resp = httpx.post(
+            f"{self.api_base}/acp/checkouts/",
+            headers={"Content-Type": "application/json"},
+            json={"sku": sku},
+            timeout=self.timeout,
+        )
+        result = self._handle(resp)
+        # Store checkout_secret for subsequent update/complete calls
+        if result and result.get("checkout_secret"):
+            self._checkout_secrets[result["id"]] = result["checkout_secret"]
+        return result
+
+    def get_checkout(self, checkout_id):
+        """Get ACP checkout session status."""
+        resp = httpx.get(
+            f"{self.api_base}/acp/checkouts/{checkout_id}/",
+            headers=self._checkout_headers(checkout_id),
+            timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def update_checkout(self, checkout_id, buyer_email=None, requested_slug=None):
+        """Update ACP checkout with buyer info."""
+        body = {}
+        if buyer_email:
+            body["buyer_email"] = buyer_email
+        if requested_slug:
+            body["requested_slug"] = requested_slug
+        resp = httpx.post(
+            f"{self.api_base}/acp/checkouts/{checkout_id}/update/",
+            headers=self._checkout_headers(checkout_id),
+            json=body,
+            timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def complete_checkout(self, checkout_id, payment_method="stripe_checkout", payment_method_id=None):
+        """Complete ACP checkout with payment."""
+        body = {"payment_method": payment_method}
+        if payment_method_id:
+            body["payment_method_id"] = payment_method_id
+        # admin_bypass needs auth header; others use checkout_secret
+        headers = self._headers() if payment_method == "admin_bypass" else self._checkout_headers(checkout_id)
+        resp = httpx.post(
+            f"{self.api_base}/acp/checkouts/{checkout_id}/complete/",
+            headers=headers,
+            json=body,
+            timeout=60,
+        )
+        return self._handle(resp)
+
+    # ── Sites (authenticated) ──
+
+    def create_site(self, checkout_id):
+        """Create a site from a completed ACP checkout."""
+        resp = httpx.post(
+            f"{self.api_base}/sites/create/",
+            headers=self._headers(),
+            json={"checkout_id": checkout_id},
+            timeout=60,
+        )
+        return self._handle(resp)
+
+    def list_sites(self):
+        resp = httpx.get(f"{self.api_base}/sites/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def get_site(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def manage_dns(self, slug, action, record_type, subdomain="", value="", ttl=3600, priority=None):
+        body = {"action": action, "type": record_type, "subdomain": subdomain, "value": value, "ttl": ttl}
+        if priority is not None:
+            body["priority"] = priority
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/dns/", headers=self._headers(), json=body, timeout=self.timeout)
+        return self._handle(resp)
+
+    def deploy(self, slug):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/deploy/", headers=self._headers(), json={}, timeout=120)
+        return self._handle(resp)
+
+    def create_snapshot(self, slug, description=""):
+        body = {"description": description} if description else {}
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/snapshots/create/", headers=self._headers(), json=body, timeout=180)
+        return self._handle(resp)
+
+    def list_snapshots(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/snapshots/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def create_b2_snapshot(self, slug, description=""):
+        body = {"description": description} if description else {}
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/snapshots/b2/", headers=self._headers(), json=body, timeout=1800)
+        return self._handle(resp)
+
+    def delete_snapshot(self, slug, snapshot_id):
+        resp = httpx.delete(f"{self.api_base}/sites/{slug}/snapshots/{snapshot_id}/", headers=self._headers(), timeout=60)
+        return self._handle(resp)
+
+    def rollback_snapshot(self, slug, snapshot_id):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/snapshots/{snapshot_id}/rollback/", headers=self._headers(), json={}, timeout=300)
+        return self._handle(resp)
+
+    def get_snapshot_usage(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/snapshots/usage/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def schedule_snapshot(self, slug, scheduled_at, description=""):
+        body = {"scheduled_at": scheduled_at, "description": description}
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/snapshots/schedule/", headers=self._headers(), json=body, timeout=self.timeout)
+        return self._handle(resp)
+
+    def cancel_scheduled_snapshot(self, slug, schedule_id):
+        resp = httpx.delete(f"{self.api_base}/sites/{slug}/snapshots/schedule/{schedule_id}/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    # ── Backups (authenticated) ──
+
+    def list_backups(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/backups/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def create_backup(self, slug):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/backups/create/", headers=self._headers(), json={}, timeout=self.timeout)
+        return self._handle(resp)
+
+    def restore_backup(self, slug, backup_id):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/backups/{backup_id}/restore/", headers=self._headers(), json={}, timeout=self.timeout)
+        return self._handle(resp)
+
+    def get_metrics(self, slug, days=7):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/metrics/", headers=self._headers(), params={"days": days}, timeout=self.timeout)
+        return self._handle(resp)
+
+    def scale(self, slug, new_plan):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/scale/", headers=self._headers(), json={"new_plan": new_plan}, timeout=self.timeout)
+        return self._handle(resp)
+
+    def decommission(self, slug):
+        resp = httpx.delete(f"{self.api_base}/sites/{slug}/delete/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    # ── Account Management (authenticated) ──
+
+    def update_account(self, email=None, language=None, first_name=None, last_name=None):
+        """Update account profile fields."""
+        body = {}
+        if email is not None:
+            body["email"] = email
+        if language is not None:
+            body["language"] = language
+        if first_name is not None:
+            body["first_name"] = first_name
+        if last_name is not None:
+            body["last_name"] = last_name
+        resp = httpx.post(f"{self.api_base}/account/update/", headers=self._headers(), json=body, timeout=self.timeout)
+        return self._handle(resp)
+
+    def delete_account(self):
+        """Soft-delete (anonymize) the account. Irreversible."""
+        resp = httpx.request(
+            "DELETE", f"{self.api_base}/account/delete/",
+            headers=self._headers(), json={"confirm": "DELETE"}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def list_subscriptions(self):
+        """List all subscriptions for the account."""
+        resp = httpx.get(f"{self.api_base}/account/subscriptions/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def get_billing_portal(self, flow=None):
+        """Get Stripe billing portal URL."""
+        params = {}
+        if flow:
+            params["flow"] = flow
+        resp = httpx.get(f"{self.api_base}/account/billing-portal/", headers=self._headers(), params=params, timeout=self.timeout)
+        return self._handle(resp)
+
+    def rotate_key(self, key_id):
+        """Atomically rotate an API key."""
+        resp = httpx.post(f"{self.api_base}/keys/{key_id}/rotate/", headers=self._headers(), json={}, timeout=self.timeout)
+        return self._handle(resp)
+
+    def create_api_key(self, name, scopes, site_slug=None, disabled_tools=None):
+        """Create a new API key."""
+        body = {"name": name, "scopes": scopes}
+        if site_slug:
+            body["site_slug"] = site_slug
+        if disabled_tools:
+            body["disabled_tools"] = disabled_tools
+        resp = httpx.post(f"{self.api_base}/keys/create/", headers=self._headers(), json=body, timeout=self.timeout)
+        return self._handle(resp)
+
+    def list_api_keys(self):
+        """List all API keys for the account."""
+        resp = httpx.get(f"{self.api_base}/keys/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def revoke_api_key(self, key_id):
+        """Revoke (deactivate) an API key."""
+        resp = httpx.post(f"{self.api_base}/keys/{key_id}/revoke/", headers=self._headers(), json={}, timeout=self.timeout)
+        return self._handle(resp)
+
+    # ── File Management (authenticated) ──
+
+    def list_files(self, slug, path=""):
+        """List directory contents for a site."""
+        params = {"path": path} if path else {}
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/files/", headers=self._headers(), params=params, timeout=self.timeout)
+        return self._handle(resp)
+
+    def read_file(self, slug, path):
+        """Read a file from a site."""
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/files/read/", headers=self._headers(), params={"path": path}, timeout=self.timeout)
+        return self._handle(resp)
+
+    def write_file(self, slug, path, content):
+        """Write content to a file on a site."""
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/files/write/",
+            headers=self._headers(), json={"path": path, "content": content}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def upload_file(self, slug, path, content_b64):
+        """Upload a base64-encoded file to a site."""
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/files/upload/",
+            headers=self._headers(), json={"path": path, "content_b64": content_b64}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def mkdir(self, slug, path):
+        """Create a directory on a site."""
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/files/mkdir/",
+            headers=self._headers(), json={"path": path}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def delete_file(self, slug, path):
+        """Delete a file or directory on a site."""
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/files/delete/",
+            headers=self._headers(), json={"path": path}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    # ── Apps (authenticated, VPS only) ──
+
+    def list_apps(self, slug):
+        """List installed apps on a site."""
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/apps/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def install_app(self, slug, template, app_name, db_type="none", domain="", display_name=""):
+        """Install an app template on a VPS site."""
+        body = {"template": template, "app_name": app_name, "db_type": db_type}
+        if domain:
+            body["domain"] = domain
+        if display_name:
+            body["display_name"] = display_name
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/apps/install/",
+            headers=self._headers(),
+            json=body,
+            timeout=60,
+        )
+        return self._handle(resp)
+
+    def get_app(self, slug, app_id):
+        """Get app status and install log."""
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/apps/{app_id}/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    # ── Logs (authenticated) ──
+
+    def get_logs(self, slug, log_type="error", lines=100, search=None):
+        """Get container logs for a site."""
+        params = {"type": log_type, "lines": lines}
+        if search:
+            params["search"] = search
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/logs/", headers=self._headers(), params=params, timeout=self.timeout)
+        return self._handle(resp)
+
+    # ── Modules (authenticated) ──
+
+    def list_modules(self, slug):
+        """List modules and availability for a site."""
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/modules/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def toggle_module(self, slug, module_name):
+        """Toggle a module on/off for a site."""
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/modules/{module_name}/toggle/",
+            headers=self._headers(), json={}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    # ── Domains (authenticated) ──
+
+    def list_domains(self):
+        """List all domains owned by the user."""
+        resp = httpx.get(f"{self.api_base}/domains/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def search_domain(self, domain):
+        """Check domain availability and pricing."""
+        resp = httpx.get(f"{self.api_base}/domains/search/", headers=self._headers(), params={"domain": domain}, timeout=self.timeout)
+        return self._handle(resp)
+
+    def register_domain(self, domain, contact, period=1, subscription_id=None, ca_legal_type=None):
+        """Register a domain with contact info and Stripe billing."""
+        body = {"domain": domain, "period": period, "contact": contact}
+        if subscription_id:
+            body["subscription_id"] = subscription_id
+        if ca_legal_type:
+            body["ca_legal_type"] = ca_legal_type
+        resp = httpx.post(
+            f"{self.api_base}/domains/register/",
+            headers=self._headers(), json=body, timeout=60,
+        )
+        return self._handle(resp)
+
+    def get_domain_detail(self, domain_name):
+        """Get domain detail with infrastructure status."""
+        resp = httpx.get(f"{self.api_base}/domains/{domain_name}/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def list_domain_dns(self, domain_name):
+        """List DNS records for a domain."""
+        resp = httpx.get(f"{self.api_base}/domains/{domain_name}/dns/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def add_domain_dns(self, domain_name, record_type, value, subdomain="", ttl=3600, priority=None):
+        """Add a DNS record to a domain."""
+        body = {"type": record_type, "value": value, "subdomain": subdomain, "ttl": ttl}
+        if priority is not None:
+            body["priority"] = priority
+        resp = httpx.post(f"{self.api_base}/domains/{domain_name}/dns/add/", headers=self._headers(), json=body, timeout=self.timeout)
+        return self._handle(resp)
+
+    def delete_domain_dns(self, domain_name, record_id):
+        """Delete a DNS record from a domain."""
+        resp = httpx.post(
+            f"{self.api_base}/domains/{domain_name}/dns/delete/",
+            headers=self._headers(), json={"record_id": record_id}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def link_domain(self, domain_name, site_slug):
+        """Link a domain to a site."""
+        resp = httpx.post(
+            f"{self.api_base}/domains/{domain_name}/link/",
+            headers=self._headers(), json={"site_slug": site_slug}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def domain_settings(self, domain_name, auto_renew=None, whois_privacy=None, locked=None):
+        """Update domain settings."""
+        body = {}
+        if auto_renew is not None:
+            body["auto_renew"] = auto_renew
+        if whois_privacy is not None:
+            body["whois_privacy"] = whois_privacy
+        if locked is not None:
+            body["locked"] = locked
+        resp = httpx.post(
+            f"{self.api_base}/domains/{domain_name}/settings/",
+            headers=self._headers(), json=body, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    # ── SSH Access (authenticated) ──
+
+    def get_ssh_info(self, slug):
+        """Get SSH connection info for a site."""
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/ssh/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def add_ssh_key(self, slug, public_key):
+        """Inject an SSH public key into a site's container."""
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/ssh/keys/",
+            headers=self._headers(), json={"public_key": public_key}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    # ── WordPress Management (authenticated) ──
+
+    def list_plugins(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/wordpress/plugins/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def list_themes(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/wordpress/themes/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def manage_plugin(self, slug, action, plugin):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/wordpress/plugins/manage/",
+            headers=self._headers(), json={"action": action, "plugin": plugin}, timeout=60,
+        )
+        return self._handle(resp)
+
+    def manage_theme(self, slug, action, theme):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/wordpress/themes/manage/",
+            headers=self._headers(), json={"action": action, "theme": theme}, timeout=60,
+        )
+        return self._handle(resp)
+
+    def wp_check_updates(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/wordpress/updates/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def wp_update_all(self, slug):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/wordpress/update-all/", headers=self._headers(), json={}, timeout=120)
+        return self._handle(resp)
+
+    # ── Cron (authenticated) ──
+
+    def list_cron(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/cron/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    def add_cron(self, slug, schedule, command):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/cron/add/",
+            headers=self._headers(), json={"schedule": schedule, "command": command}, timeout=15,
+        )
+        return self._handle(resp)
+
+    def delete_cron(self, slug, line_number):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/cron/delete/",
+            headers=self._headers(), json={"line_number": line_number}, timeout=15,
+        )
+        return self._handle(resp)
+
+    # ── SSL (authenticated) ──
+
+    def get_ssl_info(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/ssl/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def renew_ssl(self, slug):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/ssl/renew/", headers=self._headers(), json={}, timeout=120)
+        return self._handle(resp)
+
+    # ── PHP (authenticated) ──
+
+    def list_php_versions(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/php/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    def switch_php(self, slug, version):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/php/switch/",
+            headers=self._headers(), json={"version": version}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    # ── Cache (authenticated) ──
+
+    def get_cache_status(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/cache/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    def flush_cache(self, slug):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/cache/flush/", headers=self._headers(), json={}, timeout=self.timeout)
+        return self._handle(resp)
+
+    def toggle_cache(self, slug, enable):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/cache/toggle/",
+            headers=self._headers(), json={"enable": enable}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    # ── Database (authenticated) ──
+
+    def wpdb_info(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/database/info/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def wpdb_optimize(self, slug):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/database/optimize/", headers=self._headers(), json={}, timeout=60)
+        return self._handle(resp)
+
+    def wpdb_search_replace(self, slug, old, new, dry_run=True):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/database/search-replace/",
+            headers=self._headers(), json={"old": old, "new": new, "dry_run": dry_run}, timeout=120,
+        )
+        return self._handle(resp)
+
+    def list_databases(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/database/databases/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    def list_tables(self, slug, database):
+        resp = httpx.get(
+            f"{self.api_base}/sites/{slug}/database/tables/",
+            headers=self._headers(), params={"database": database}, timeout=15,
+        )
+        return self._handle(resp)
+
+    def execute_query(self, slug, database, query):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/database/query/",
+            headers=self._headers(), json={"database": database, "query": query}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    # ── System (authenticated) ──
+
+    def get_stack_info(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/system/stack/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    def get_resource_snapshot(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/system/resources/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    # ── FTP Accounts (authenticated) ──
+
+    def list_ftp_accounts(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/ftp/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    def create_ftp_account(self, slug, username, password, home_dir="/var/www/html"):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/ftp/create/",
+            headers=self._headers(), json={"username": username, "password": password, "home_dir": home_dir},
+            timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def remove_ftp_account(self, slug, username):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/ftp/remove/",
+            headers=self._headers(), json={"username": username}, timeout=15,
+        )
+        return self._handle(resp)
+
+    def ftp_set_password(self, slug, username, password):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/ftp/password/",
+            headers=self._headers(), json={"username": username, "password": password}, timeout=15,
+        )
+        return self._handle(resp)
+
+    # ── Alert Rules (authenticated) ──
+
+    def list_alert_rules(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/alerts/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    def create_alert_rule(self, slug, metric, threshold, operator="gt", severity="warning",
+                          cooldown_minutes=30, notify_email=True, notify_webhook=""):
+        body = {
+            "metric": metric, "threshold": threshold, "operator": operator,
+            "severity": severity, "cooldown_minutes": cooldown_minutes,
+            "notify_email": notify_email, "notify_webhook": notify_webhook,
+        }
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/alerts/create/", headers=self._headers(), json=body, timeout=15)
+        return self._handle(resp)
+
+    def delete_alert_rule(self, slug, rule_id):
+        resp = httpx.post(f"{self.api_base}/sites/{slug}/alerts/{rule_id}/delete/", headers=self._headers(), json={}, timeout=15)
+        return self._handle(resp)
+
+    # ── Security Scanning (authenticated) ──
+
+    def malware_scan(self, slug, path=""):
+        body = {"path": path} if path else {}
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/security/scan/",
+            headers=self._headers(), json=body, timeout=320,
+        )
+        return self._handle(resp)
+
+    # ── Cloudflare CDN (authenticated) ──
+
+    def cf_proxy_status(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/cloudflare/proxy/", headers=self._headers(), timeout=self.timeout)
+        return self._handle(resp)
+
+    def cf_set_proxy(self, slug, proxied):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/cloudflare/proxy/set/",
+            headers=self._headers(), json={"proxied": proxied}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def cf_cache_purge(self, slug, urls=None):
+        body = {"urls": urls} if urls else {}
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/cloudflare/cache/purge/",
+            headers=self._headers(), json=body, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    def cf_analytics(self, slug, minutes=1440):
+        resp = httpx.get(
+            f"{self.api_base}/sites/{slug}/cloudflare/analytics/",
+            headers=self._headers(), params={"minutes": minutes}, timeout=self.timeout,
+        )
+        return self._handle(resp)
+
+    # ── Firewall (authenticated) ──
+
+    def list_firewall_rules(self, slug):
+        resp = httpx.get(f"{self.api_base}/sites/{slug}/firewall/", headers=self._headers(), timeout=15)
+        return self._handle(resp)
+
+    def add_firewall_rule(self, slug, ip, action="deny"):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/firewall/add/",
+            headers=self._headers(), json={"ip": ip, "action": action}, timeout=15,
+        )
+        return self._handle(resp)
+
+    def remove_firewall_rule(self, slug, ip):
+        resp = httpx.post(
+            f"{self.api_base}/sites/{slug}/firewall/remove/",
+            headers=self._headers(), json={"ip": ip}, timeout=15,
+        )
+        return self._handle(resp)
+
+    # ── Key Claim (challenge-response) ──
+
+    def request_api_key(self, site_slug):
+        """Request a claim token for challenge-response key provisioning."""
+        resp = httpx.post(
+            f"{self.api_base}/keys/claim/request/",
+            headers={"Content-Type": "application/json"},
+            json={"site_slug": site_slug},
+            timeout=15,
+        )
+        return self._handle(resp)
+
+    def claim_api_key(self, claim_token):
+        """Claim an API key using a claim token from the container."""
+        resp = httpx.post(
+            f"{self.api_base}/keys/claim/",
+            headers={"Content-Type": "application/json"},
+            json={"claim_token": claim_token},
+            timeout=15,
+        )
+        return self._handle(resp)

borealhost_sdk-0.1.0/borealhost_sdk/config.py

@@ -0,0 +1,7 @@
+"""Default configuration for the BorealHost SDK."""
+
+import os
+
+DEFAULT_BASE_URL = os.environ.get("BOREALHOST_BASE_URL", "https://borealhost.ai")
+DEFAULT_API_KEY = os.environ.get("BOREALHOST_API_KEY", "")
+DEFAULT_TIMEOUT = 30

borealhost_sdk-0.1.0/borealhost_sdk/exceptions.py

@@ -0,0 +1,19 @@
+"""Exceptions raised by the BorealHost SDK."""
+
+
+class ApiError(Exception):
+    """Raised when the BorealHost API returns an error envelope.
+
+    Attributes:
+        code: Short error code from the API (e.g. "NOT_FOUND", "UNAUTHORIZED").
+        message: Human-readable error message.
+        status_code: HTTP status code.
+        request_id: API request ID for support/debugging (if present).
+    """
+
+    def __init__(self, code="UNKNOWN", message="Unknown error", status_code=None, request_id=None):
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        super().__init__(f"{code}: {message}")

borealhost_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "borealhost-sdk"
+version = "0.1.0"
+description = "Python SDK for the BorealHost.ai REST API — agent-native web hosting"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "BorealHost", email = "hello@borealhost.ai" },
+]
+keywords = ["borealhost", "hosting", "sdk", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://borealhost.ai"
+Documentation = "https://borealhost.ai/api/v1/docs/"
+Repository = "https://github.com/alainsvrd/platform"
+
+[tool.hatch.build.targets.wheel]
+packages = ["borealhost_sdk"]
+
+[tool.hatch.build]
+include = ["borealhost_sdk/**"]