aetheris-sdk 0.1.12__tar.gz

aetheris_sdk-0.1.12/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: aetheris-sdk
+Version: 0.1.12
+Summary: Aetheris SDK: браузер профиля в твоём процессе, наружу — Playwright
+Project-URL: Homepage, https://aetheris.h316.online
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: camoufox[geoip]>=0.5.4
+
+# aetheris-sdk
+
+Aetheris SDK: браузер профиля в твоём процессе, наружу — Playwright
+
+```python
+import asyncio
+from aetheris_client import Aetheris
+
+async def main():
+    async with Aetheris("http://127.0.0.1:8766/api/v1", token=KEY) as ae:
+        async with ae.open_profile(2, headless=False) as ctx:
+            page = await ctx.new_page()
+            await page.goto("https://example.com")
+            print(await page.title())
+
+asyncio.run(main())
+```
+
+`open_profile` отдаёт настоящий `BrowserContext` Playwright — работает всё,
+что умеет Playwright. Аренда профиля, отпечаток, прокси, выгрузка каталога и
+освобождение аренды делаются за тебя; выходить из `async with` обязательно.
+
+Ключ создаётся в самом Aetheris, на экране «API и MCP», и читается из файла, а
+не вписывается в код.
+
+Полное описание установки — `http://127.0.0.1:8766/guide` при запущенном
+Aetheris.
+
+Версия 0.1.012, она же версия клиента, к которому эта раздача подходит.

aetheris_sdk-0.1.12/README.md

@@ -0,0 +1,29 @@
+# aetheris-sdk
+
+Aetheris SDK: браузер профиля в твоём процессе, наружу — Playwright
+
+```python
+import asyncio
+from aetheris_client import Aetheris
+
+async def main():
+    async with Aetheris("http://127.0.0.1:8766/api/v1", token=KEY) as ae:
+        async with ae.open_profile(2, headless=False) as ctx:
+            page = await ctx.new_page()
+            await page.goto("https://example.com")
+            print(await page.title())
+
+asyncio.run(main())
+```
+
+`open_profile` отдаёт настоящий `BrowserContext` Playwright — работает всё,
+что умеет Playwright. Аренда профиля, отпечаток, прокси, выгрузка каталога и
+освобождение аренды делаются за тебя; выходить из `async with` обязательно.
+
+Ключ создаётся в самом Aetheris, на экране «API и MCP», и читается из файла, а
+не вписывается в код.
+
+Полное описание установки — `http://127.0.0.1:8766/guide` при запущенном
+Aetheris.
+
+Версия 0.1.012, она же версия клиента, к которому эта раздача подходит.

aetheris_sdk-0.1.12/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aetheris-sdk"
+version = "0.1.012"
+description = "Aetheris SDK: браузер профиля в твоём процессе, наружу — Playwright"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27", "camoufox[geoip]>=0.5.4"]
+
+[project.urls]
+Homepage = "https://aetheris.h316.online"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = ["aetheris_client"]

aetheris_sdk-0.1.12/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aetheris_sdk-0.1.12/src/aetheris_client/__init__.py

@@ -0,0 +1,479 @@
+"""Тонкий клиент Aetheris для автоматизации. Решение — ADR-0006.
+
+Браузер поднимается **в процессе того, кто автоматизирует**, потому что папка
+профиля лежит на диске его машины. По HTTP ходят только аренда и метаданные.
+
+    from aetheris_client import Aetheris
+
+    client = Aetheris("http://127.0.0.1:8765", token="...")
+
+    async with client.open_profile(12) as context:      # BrowserContext
+        page = await context.new_page()
+        await page.goto("https://www.tiktok.com")
+
+Цикл — аренда, забрать каталог, запуск, полное закрытие, выгрузка, отпустить
+аренду — живёт здесь целиком. Написанный руками в клиенте, он был бы забыт
+наполовину, и первым забыли бы выгрузку.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "Aetheris",
+    "AetherisError",
+    "AccountInfo",
+    "BrowserStillRunning",
+    "ProfileBusy",
+    "ProfileInfo",
+    "ProxyDead",
+]
+
+
+class AetherisError(RuntimeError):
+    """Ошибка API. Код сравнивается, текст читается человеком."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class ProfileBusy(AetherisError):
+    """Профиль открыт другой машиной. Ждать в цикле бессмысленно."""
+
+
+class ProxyDead(AetherisError):
+    """Прокси помечен мёртвым — нужно решение владельца, а не повтор."""
+
+
+class BrowserStillRunning(AetherisError):
+    """Выгрузка на живом браузере. Это ошибка в самом клиенте."""
+
+
+#: Код ошибки API -> тип исключения. Клиент ловит смысл, а не разбирает строки.
+ERRORS = {
+    "profile_locked": ProfileBusy,
+    "proxy_dead": ProxyDead,
+    "proxy_conflict": ProxyDead,
+    "browser_running": BrowserStillRunning,
+}
+
+
+@dataclass(frozen=True)
+class AccountInfo:
+    """Аккаунт профиля. **Пароля здесь нет и не будет** (ADR-0008)."""
+
+    id: int
+    platform: str
+    username: str
+    label: str | None = None
+    has_credentials: bool = False
+
+
+@dataclass(frozen=True)
+class ProfileInfo:
+    id: int
+    slug: str
+    name: str
+    status: str
+    is_open: bool
+    accounts: tuple[AccountInfo, ...] = ()
+    proxy_ip: str | None = None
+    proxy_country: str | None = None
+
+
+class Aetheris:
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:8765",
+        token: str | None = None,
+        timeout: float = 120.0,
+        addons_root: str | Path | None = None,
+    ) -> None:
+        self._base = base_url.rstrip("/") + "/api/v1"
+        self._token = token
+        self._timeout = timeout
+        # Корень распакованных расширений ЭТОЙ машины. Ядро отдаёт имена
+        # каталогов, путь собирается здесь: то же правило, что у пути к бинарю.
+        self._addons_root = Path(addons_root or os.getenv("ADDONS_ROOT", "./data/addons"))
+
+    # -- транспорт ---------------------------------------------------------
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        import httpx
+
+        headers = {"Authorization": f"Bearer {self._token}"} if self._token else {}
+        async with httpx.AsyncClient(timeout=self._timeout) as http:
+            response = await http.request(
+                method, self._base + path, headers=headers, **kwargs
+            )
+
+        if response.status_code == 204:
+            return None
+
+        body = response.json() if response.content else None
+        if response.is_error:
+            envelope = (body or {}).get("error", {})
+            code = envelope.get("code", "unknown")
+            message = envelope.get("message") or f"запрос не прошёл ({response.status_code})"
+            raise ERRORS.get(code, AetherisError)(code, message)
+        return body
+
+    # -- справочное --------------------------------------------------------
+
+    async def profiles(self, **filters: Any) -> list[ProfileInfo]:
+        params = {key: value for key, value in filters.items() if value is not None}
+        rows = await self._request("GET", "/profiles", params=params)
+        return [_profile(row) for row in rows]
+
+    async def profile(self, profile_id: int) -> ProfileInfo:
+        return _profile(await self._request("GET", f"/profiles/{profile_id}"))
+
+    async def find_account(self, platform: str, username: str) -> ProfileInfo | None:
+        """В каком профиле живёт этот аккаунт.
+
+        Закрывает вопрос, ради которого продукт и затевался: не держать
+        в отдельной таблице соответствие «профиль — аккаунт».
+        """
+        for profile in await self.profiles(platform=platform):
+            for account in profile.accounts:
+                if account.username.lower() == username.lower():
+                    return profile
+        return None
+
+    # -- отпечаток ---------------------------------------------------------
+
+    async def fingerprint(self, profile_id: int) -> dict[str, Any]:
+        """Отпечаток профиля: разложенный по разделам и правимые ручки.
+
+        Значения ручек лежат в ``editable``, режимы возможностей браузера —
+        в ``settings``. Теми же именами их и меняют.
+        """
+        return await self._request("GET", f"/profiles/{profile_id}/fingerprint")
+
+    async def tune_fingerprint(
+        self,
+        profile_id: int,
+        *,
+        reseed: list[str] | None = None,
+        settings: dict[str, str] | None = None,
+        **knobs: Any,
+    ) -> dict[str, Any]:
+        """Поправить отпечаток профиля.
+
+        ::
+
+            await client.tune_fingerprint(7, timezone="Asia/Almaty", cores=8)
+            await client.tune_fingerprint(7, reseed=["canvas"])
+            await client.tune_fingerprint(7, settings={"webrtc": "off"})
+
+        Присланная ручка меняется, не присланная не трогается, ``None`` снимает
+        подмену — значение отдаст сам браузер.
+
+        Правки применяются **при следующем запуске**: конфигурация уезжает
+        в браузер в момент старта, и профиль на это время должен быть закрыт.
+        """
+        body: dict[str, Any] = dict(knobs)
+        if reseed:
+            body["reseed"] = reseed
+        if settings:
+            body["settings"] = settings
+        return await self._request("PATCH", f"/profiles/{profile_id}/fingerprint", json=body)
+
+    async def reroll_fingerprint(self, profile_id: int, reason: str = "") -> ProfileInfo:
+        """Выдать профилю другой набор железа целиком.
+
+        Для профиля с живыми аккаунтами это выглядит как вход с нового
+        устройства. Причина необязательна и идёт в заметки профиля.
+        """
+        row = await self._request(
+            "POST", f"/profiles/{profile_id}/reroll-fingerprint", json={"reason": reason}
+        )
+        return _profile(row)
+
+    # -- запуск браузера ---------------------------------------------------
+
+    @asynccontextmanager
+    async def open_profile(self, profile_id: int, *, headless: bool = True):
+        """Взять профиль в работу и отдать ``BrowserContext``.
+
+        Порядок шагов — условие корректности, а не стиль. ``pull`` идёт до
+        запуска, потому что после него Firefox уже держит файлы профиля.
+        Выгрузка — только после ПОЛНОГО закрытия: Firefox дописывает свои
+        файлы при завершении. Аренда отпускается последней, иначе вторая
+        машина заберёт профиль, пока эта ещё пишет.
+        """
+        from camoufox.async_api import AsyncCamoufox
+
+        lease = await self._request("POST", f"/profiles/{profile_id}/lease")
+        directory = Path(lease["dir"])
+        options = dict(lease["launch_options"])
+
+        keepalive = asyncio.create_task(self._keep_lease(profile_id))
+        try:
+            if lease.get("sync_enabled"):
+                await self._request("POST", f"/profiles/{profile_id}/sync/pull")
+
+            directory.mkdir(parents=True, exist_ok=True)
+
+            # Настройки профиля — файлом в каталог, а не опцией запуска: через
+            # Playwright они не доезжают вовсе. Пишется всегда, в том числе
+            # пустым, — иначе выключенный вчера WebRTC остался бы выключенным
+            # после того, как его включили.
+            #
+            # Без этого автоматизация поднимала браузер БЕЗ защиты от утечки
+            # WebRTC, при том что интерфейс показывал её включённой: настройку
+            # клал только путь вебморды, а аренда её не отдавала вовсе.
+            apply_machine_part(
+                options,
+                lease,
+                directory=directory,
+                headless=headless,
+                addons_root=self._addons_root,
+            )
+
+            async with AsyncCamoufox(persistent_context=True, from_options=options) as ctx:
+                yield ctx
+        finally:
+            keepalive.cancel()
+            try:
+                await keepalive
+            except asyncio.CancelledError:
+                pass
+
+            if lease.get("sync_enabled"):
+                # Выгрузка может не пройти — профиль останется помеченным,
+                # но аренду отпустить надо в любом случае.
+                try:
+                    await self._request("POST", f"/profiles/{profile_id}/sync/push")
+                except AetherisError:
+                    pass
+            await self._request("POST", f"/profiles/{profile_id}/release")
+
+    async def _keep_lease(self, profile_id: int) -> None:
+        """Продлевать аренду, пока браузер жив (ADR-0010).
+
+        Интервал заведомо меньше срока аренды: две подряд пропущенные попытки
+        ещё не приводят к истечению.
+        """
+        while True:
+            await asyncio.sleep(60)
+            try:
+                await self._request("POST", f"/profiles/{profile_id}/renew")
+            except AetherisError:
+                # Аренду сняли принудительно. Молча продолжать нельзя: профиль
+                # уже может открывать другая машина.
+                return
+
+
+#: Приставка кусков, на которые Camoufox режет конфигурацию отпечатка.
+_CONFIG_PREFIX = "CAMOU_CONFIG_"
+
+#: Ключ, которым Camoufox рисует курсор поверх страницы. Умолчание у него —
+#: «рисовать», и с `humanize` оно не связано: замерено, что без `humanize`
+#: кружок всё равно виден (`camoucfg.jvv`, `"showcursor": "bool"`).
+#:
+#: Имя дублирует `aetheris.browser.fingerprint.CURSOR_KEY` в ядре. Разъехаться
+#: им негде: это имя ключа в чужом формате, и меняет его Camoufox, а не мы.
+CURSOR_KEY = "showcursor"
+
+
+#: Как называется исполняемый файл браузера после ребрендинга установки.
+#:
+#: Именно это имя человек и видит: и `ps`, и Мониторинг системы, и список
+#: приложений показывают **имя файла**, а не `CFBundleName` — замерено. Отсюда
+#: пробел: «Aetheris Browser» читается, «aetheris-browser» выглядит служебным.
+#: Кавычек он не требует — путь уходит списком аргументов, а не строкой в
+#: оболочку.
+#:
+#: Живёт здесь, а не в модуле ребрендинга: отсюда его читает запуск, и разъезд
+#: этих двух имён означал бы профиль, который перестал открываться.
+BROWSER_EXECUTABLE = "Aetheris Browser"
+
+
+def _launch_path() -> str:
+    """Путь к браузеру с поправкой на наше переименование.
+
+    `camoufox.pkgman.launch_path` собирает путь из своего имени и о
+    переименовании не знает. Без этой развилки первый же ребрендинг сделал бы
+    все профили неоткрываемыми — причём с ошибкой «executable doesn't exist»,
+    по которой не догадаться, что дело в имени.
+    """
+    from camoufox.pkgman import launch_path
+
+    original = Path(launch_path())
+    renamed = original.with_name(BROWSER_EXECUTABLE)
+    return str(renamed if renamed.exists() else original)
+
+
+def _profile(row: dict[str, Any]) -> ProfileInfo:
+    proxy = row.get("proxy") or {}
+    return ProfileInfo(
+        id=row["id"],
+        slug=row["slug"],
+        name=row["name"],
+        status=row["status"],
+        is_open=row.get("is_open", False),
+        accounts=tuple(
+            AccountInfo(
+                id=account["id"],
+                platform=account["platform"],
+                username=account["username"],
+                label=account.get("label"),
+                has_credentials=account.get("has_credentials", False),
+            )
+            for account in row.get("accounts") or ()
+        ),
+        proxy_ip=proxy.get("external_ip"),
+        proxy_country=proxy.get("country"),
+    )
+
+
+
+
+def read_config(options: dict[str, Any]) -> dict[str, Any]:
+    """Собрать конфигурацию отпечатка из кусков окружения.
+
+    Camoufox режет её на `CAMOU_CONFIG_1..N`: целиком она длиннее предела
+    переменной окружения. Пустой словарь означает, что кусков нет вовсе.
+    """
+    env = options.get("env") or {}
+    chunks = sorted(
+        (key for key in env if key.startswith(_CONFIG_PREFIX)),
+        key=lambda key: int(key.removeprefix(_CONFIG_PREFIX)),
+    )
+    return json.loads("".join(env[key] for key in chunks)) if chunks else {}
+
+
+def write_config(
+    options: dict[str, Any], config: dict[str, Any]
+) -> dict[str, Any]:
+    """Разложить конфигурацию обратно по кускам. Правит `options` на месте.
+
+    Число кусков сохраняется прежним: их считает не длина, а то, на сколько
+    частей резал Camoufox, и менять это на ходу незачем.
+    """
+    env = dict(options.get("env") or {})
+    chunks = sorted(
+        (key for key in env if key.startswith(_CONFIG_PREFIX)),
+        key=lambda key: int(key.removeprefix(_CONFIG_PREFIX)),
+    )
+    if not chunks:
+        return options
+
+    packed = json.dumps(config, ensure_ascii=False)
+    for key in chunks:
+        env.pop(key)
+    size = max(1, -(-len(packed) // len(chunks)))
+    for number, start in enumerate(range(0, len(packed), size), start=1):
+        env[f"{_CONFIG_PREFIX}{number}"] = packed[start : start + size]
+    options["env"] = env
+    return options
+
+def apply_machine_part(
+    options: dict[str, Any],
+    lease: dict[str, Any],
+    *,
+    directory: Path,
+    headless: bool,
+    addons_root: Path,
+    show_cursor: bool = True,
+) -> None:
+    """Достроить опции запуска тем, что принадлежит ЭТОЙ машине.
+
+    Ядро отдаёт всё, что переносится между машинами. Не переносится ровно
+    четыре вещи, и все четыре подставляются здесь: каталог профиля, путь к
+    бинарю Camoufox, окружение процесса и пути расширений.
+
+    Общая на двоих: этим пользуется и тонкий клиент, и агент (ADR-0018).
+    Второй копии не будет — разойтись им негде.
+
+    Настройки профиля кладутся файлом, а не опцией: через Playwright они не
+    доезжают вовсе. Пишется всегда, в том числе пустым, — иначе выключенный
+    вчера WebRTC остался бы выключенным после того, как его включили.
+
+    ``show_cursor`` решается **здесь**, а не в ядре. Аренда одна на всех, а
+    красный кружок поверх страницы означает «браузером управляет программа, не
+    лезь руками» — то есть зависит не от профиля, а от того, кто его открыл.
+    Знает это только та сторона, которая браузер поднимает: агент по кнопке
+    открывает человеку, тонкий клиент — автоматизации.
+    """
+    directory.mkdir(parents=True, exist_ok=True)
+    (directory / "user.js").write_text(lease.get("user_js", ""), encoding="utf-8")
+
+    options.update(
+        user_data_dir=str(directory),
+        headless=headless,
+        executable_path=_launch_path(),
+    )
+    # Окружение машины — ПОД конфигурацией отпечатка: Playwright этим полем
+    # окружение браузера заменяет, а не дополняет, и одни куски конфигурации
+    # означали бы Firefox без PATH и TEMP.
+    options["env"] = {**os.environ, **(options.get("env") or {})}
+    _patch_config(
+        options,
+        addons=lease.get("addons") or [],
+        addons_root=addons_root,
+        show_cursor=show_cursor,
+    )
+
+
+def _patch_config(
+    options: dict[str, Any],
+    *,
+    addons: list[str],
+    addons_root: Path,
+    show_cursor: bool,
+) -> None:
+    """Дописать в конфигурацию отпечатка то, что знает только эта сторона.
+
+    Конфигурация лежит кусками в переменных окружения: Camoufox режет её,
+    потому что целиком она длиннее лимита переменной. Собирается и режется
+    обратно она здесь — **один раз на запуск**. Два круга «прочитать —
+    записать» ради двух ключей раскладывали бы её дважды без всякой пользы.
+
+    Пути расширений: ядро отдаёт имена каталогов, а не пути, потому что путь
+    принадлежит машине — то же правило, что у ``executable_path``. Пропала
+    папка — расширение молча выпадает из списка: профиль с кошельком не должен
+    переставать открываться из-за того, что кто-то удалил аддон. Видно это в
+    библиотеке, а не в отказе.
+
+    Курсор: красный кружок поверх страницы рисуется отдельной настройкой со
+    своим умолчанием, и умолчание это — «рисовать». Снимать его приходится
+    явно.
+    """
+    # Путь **абсолютный**, и это несущее. Относительный браузер разрешает от
+    # своего рабочего каталога, а не от нашего: расширение с таким путём молча
+    # не грузится — замерено, `DEBUG: Installed 1 addon(s)` появляется только с
+    # абсолютным. Та же ловушка однажды уже сломала запуск через обёртку
+    # значка профиля (research/window-chrome.md).
+    root = Path(addons_root).absolute()
+    paths = [
+        str(root / name)
+        for name in addons
+        if (root / name / "manifest.json").exists()
+    ]
+
+    # Ранней проверки здесь нет намеренно: пустая, но существующая
+    # конфигурация — это `{}`, то есть ложь, и выход по ней пропускал бы
+    # расширения. `write_config` сам молчит, когда кусков нет.
+    config = read_config(options)
+
+    if paths:
+        config["addons"] = paths
+    else:
+        # Пустой список СНИМАЕТ ключ, а не оставляет прежний: иначе выключенное
+        # расширение продолжало бы ставиться до пересоздания профиля.
+        config.pop("addons", None)
+
+    if not show_cursor:
+        config[CURSOR_KEY] = False
+
+    write_config(options, config)

aetheris_sdk-0.1.12/src/aetheris_sdk.egg-info/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: aetheris-sdk
+Version: 0.1.12
+Summary: Aetheris SDK: браузер профиля в твоём процессе, наружу — Playwright
+Project-URL: Homepage, https://aetheris.h316.online
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: camoufox[geoip]>=0.5.4
+
+# aetheris-sdk
+
+Aetheris SDK: браузер профиля в твоём процессе, наружу — Playwright
+
+```python
+import asyncio
+from aetheris_client import Aetheris
+
+async def main():
+    async with Aetheris("http://127.0.0.1:8766/api/v1", token=KEY) as ae:
+        async with ae.open_profile(2, headless=False) as ctx:
+            page = await ctx.new_page()
+            await page.goto("https://example.com")
+            print(await page.title())
+
+asyncio.run(main())
+```
+
+`open_profile` отдаёт настоящий `BrowserContext` Playwright — работает всё,
+что умеет Playwright. Аренда профиля, отпечаток, прокси, выгрузка каталога и
+освобождение аренды делаются за тебя; выходить из `async with` обязательно.
+
+Ключ создаётся в самом Aetheris, на экране «API и MCP», и читается из файла, а
+не вписывается в код.
+
+Полное описание установки — `http://127.0.0.1:8766/guide` при запущенном
+Aetheris.
+
+Версия 0.1.012, она же версия клиента, к которому эта раздача подходит.

aetheris_sdk-0.1.12/src/aetheris_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+src/aetheris_client/__init__.py
+src/aetheris_sdk.egg-info/PKG-INFO
+src/aetheris_sdk.egg-info/SOURCES.txt
+src/aetheris_sdk.egg-info/dependency_links.txt
+src/aetheris_sdk.egg-info/requires.txt
+src/aetheris_sdk.egg-info/top_level.txt

aetheris_sdk-0.1.12/src/aetheris_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aetheris_sdk-0.1.12/src/aetheris_sdk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.27
+camoufox[geoip]>=0.5.4

aetheris_sdk-0.1.12/src/aetheris_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+aetheris_client