s-clientkit 0.0.1__py3-none-any.whl

clientkit/declaration.py

@@ -0,0 +1,338 @@
+"""ДЕКЛАРАЦИЯ СЕРВИСА — данные, а не код.
+
+Здесь нет ни одного вызова к сети и ни одной ветки «как ходить». Только
+описание: где сервис живёт, чем ему представляться, сколько можно стучать, какие
+у него операции и — для СКРЫТОГО API — чем чеканить доступ и как деградировать.
+
+ПОЧЕМУ ЭТО ПРИНЦИПИАЛЬНО. Пока адрес, схема авторизации и лимит зашиты в код
+клиента, каждый новый сервис — это новый файл на 300 строк, который через месяц
+разъедется с соседним. Когда они данные: подключение сервиса — правка TOML,
+смерть `rpcid` — правка одной строки, а различие «белый/скрытый» перестаёт быть
+различием ДЛЯ ПОТРЕБИТЕЛЯ (он в обоих случаях зовёт ``client.call("me")``).
+
+ДВЕ ФОРМЫ, ОДНА МОДЕЛЬ. :func:`decl_from_data` принимает обычный ``Mapping``
+(из TOML/JSON/YAML — чем прочитали, тем и прочитали), :func:`load_toml` —
+готовый файл. Обратно — :func:`decl_to_data`. Round-trip проверяется тестом:
+декларация, прошедшая туда-обратно, обязана быть равна исходной, иначе «данные»
+были бы односторонним фасадом над кодом.
+
+ТИП СЕРВИСА (:class:`ServiceKind`) — не украшение, а ВЫБОР СБОРКИ:
+
+* ``WHITE``  — прямые запросы, авторизация заголовком, ни сессий, ни антибота;
+* ``HIDDEN`` — доступ приходится ДЕРЖАТЬ: сессия, чеканка, лестница деградации,
+  адреса-кандидаты.
+
+Проверка непротиворечивости живёт в :meth:`ServiceDecl.validate` и зовётся при
+сборке: белый сервис с рецептом доступа — почти наверняка опечатка, и узнать об
+этом надо при загрузке файла, а не на первом ночном запуске.
+"""
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "AccessRecipe",
+    "AuthDecl",
+    "AuthScheme",
+    "EndpointDecl",
+    "LimitDecl",
+    "ServiceDecl",
+    "ServiceKind",
+    "decl_from_data",
+    "decl_to_data",
+    "load_toml",
+]
+
+
+class ServiceKind(StrEnum):
+    """Как СОБИРАТЬ клиента: прямыми запросами или с удержанием доступа."""
+
+    WHITE = "white"
+    HIDDEN = "hidden"
+
+
+class AuthScheme(StrEnum):
+    """Чем представляться сервису."""
+
+    NONE = "none"
+    API_KEY = "api_key"
+    BEARER = "bearer"
+    OAUTH = "oauth"
+    #: Скрытый API: авторизует САМА СЕССИЯ (cookies), заголовка-ключа нет.
+    SESSION = "session"
+
+
+@dataclass(frozen=True, slots=True)
+class AuthDecl:
+    """Схема авторизации. Секрет тут НЕ ЛЕЖИТ — лежит ИМЯ, по которому его брать.
+
+    Декларация — данные, которые не стыдно положить в git; значение приходит из
+    хранилища секретов/env в момент сборки клиента.
+    """
+
+    scheme: AuthScheme = AuthScheme.NONE
+    #: Заголовок, в который уезжает значение (``Authorization``/``X-Api-Key``/…).
+    header: str = "Authorization"
+    #: Шаблон значения; ``{secret}`` подставляется. Для bearer — ``"Bearer {secret}"``.
+    template: str = "{secret}"
+    #: Имя секрета в `SecretStorePort`/env (НЕ сам секрет).
+    secret_name: str = ""
+    #: OAuth: адрес токен-эндпоинта.
+    token_url: str = ""
+    #: OAuth: за сколько секунд ДО истечения обновляться проактивно.
+    leeway: float = 60.0
+
+    def to_data(self) -> dict[str, Any]:
+        """Плоский словарь; умолчания опускаются (декларация читаемая)."""
+        data: dict[str, Any] = {"scheme": self.scheme.value}
+        for key, value, default in (
+            ("header", self.header, "Authorization"),
+            ("template", self.template, "{secret}"),
+            ("secret_name", self.secret_name, ""),
+            ("token_url", self.token_url, ""),
+            ("leeway", self.leeway, 60.0),
+        ):
+            if value != default:
+                data[key] = value
+        return data
+
+    @classmethod
+    def from_data(cls, data: Mapping[str, Any]) -> AuthDecl:
+        return cls(
+            scheme=AuthScheme(data.get("scheme", AuthScheme.NONE)),
+            header=str(data.get("header", "Authorization")),
+            template=str(data.get("template", "{secret}")),
+            secret_name=str(data.get("secret_name", "")),
+            token_url=str(data.get("token_url", "")),
+            leeway=float(data.get("leeway", 60.0)),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class LimitDecl:
+    """Лимит вызовов: ``rate`` запросов в секунду при ёмкости ``burst``.
+
+    ``rate == 0`` — лимита нет (и тогда сборщик не строит гейт вовсе: платить
+    блокировкой за то, чего не объявляли, никто не обязан).
+    """
+
+    rate: float = 0.0
+    burst: int = 1
+
+    def to_data(self) -> dict[str, Any]:
+        data: dict[str, Any] = {}
+        if self.rate:
+            data["rate"] = self.rate
+        if self.burst != 1:
+            data["burst"] = self.burst
+        return data
+
+    @classmethod
+    def from_data(cls, data: Mapping[str, Any]) -> LimitDecl:
+        return cls(rate=float(data.get("rate", 0.0)), burst=int(data.get("burst", 1)))
+
+
+@dataclass(frozen=True, slots=True)
+class EndpointDecl:
+    """Операция: ИМЯ, которым её зовут, и адрес(а), которыми она ходит.
+
+    ``candidates`` — запасные адреса ОДНОЙ И ТОЙ ЖЕ операции. Это про скрытый
+    API: там адрес (`rpcid`, внутренний путь) умирает без предупреждения, и
+    единственный способ пережить смерть без релиза — держать список. Для белого
+    API список обычно пуст: у белого адрес меняется по документации и с версией.
+    """
+
+    name: str
+    path: str = ""
+    method: str = "GET"
+    candidates: tuple[str, ...] = ()
+
+    def to_data(self) -> dict[str, Any]:
+        data: dict[str, Any] = {"name": self.name, "path": self.path}
+        if self.method != "GET":
+            data["method"] = self.method
+        if self.candidates:
+            data["candidates"] = list(self.candidates)
+        return data
+
+    @classmethod
+    def from_data(cls, data: Mapping[str, Any]) -> EndpointDecl:
+        return cls(
+            name=str(data["name"]),
+            path=str(data.get("path", "")),
+            method=str(data.get("method", "GET")).upper(),
+            candidates=tuple(str(c) for c in data.get("candidates", ())),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class AccessRecipe:
+    """РЕЦЕПТ ДОСТУПА — только для скрытого API: чем доказывается вход и чем чеканить.
+
+    * ``session_markers`` — имена cookie, наличие которых означает «сессия есть».
+      Не «файл лежит», а именно маркеры: файл лежит и у мёртвой сессии;
+    * ``minter``          — имя способа чеканки в
+      :func:`authkit_client.ports.register_minter` (регистрирует `browserkit`);
+    * ``ladder``          — ЛЕСТНИЦА ДЕГРАДАЦИИ: что пробовать по порядку, когда
+      доступа нет. ``"session"`` (взять сохранённую) → ``"mint"`` (отчеканить
+      заново) → ``"antibot"`` (сходить обходным транспортом);
+    * ``probe_path``      — дешёвый адрес живой пробы доступа;
+    * ``dead_endpoint_markers`` / ``dead_session_markers`` — ДОМЕННЫЕ улики в
+      ТЕЛЕ ответа: «у нас мёртвый метод отвечает вот так». Общие улики
+      (``unknown rpcid``, ``please sign in``, …) уже знает
+      `corekit.diagnosis.access` — сюда пишут ТОЛЬКО то, чего он знать не может,
+      потому что это специфика конкретного сервиса. Транспортные улики
+      (обрыв выхода) не расширяются намеренно: их единственный источник —
+      `corekit.diagnosis.egress`, иначе два сервиса разъедутся в диагнозах на
+      одном тексте.
+    """
+
+    session_markers: tuple[str, ...] = ()
+    minter: str = ""
+    ladder: tuple[str, ...] = ("session", "mint")
+    probe_path: str = "/"
+    social: str = ""
+    dead_endpoint_markers: tuple[str, ...] = ()
+    dead_session_markers: tuple[str, ...] = ()
+
+    def to_data(self) -> dict[str, Any]:
+        data: dict[str, Any] = {}
+        if self.dead_endpoint_markers:
+            data["dead_endpoint_markers"] = list(self.dead_endpoint_markers)
+        if self.dead_session_markers:
+            data["dead_session_markers"] = list(self.dead_session_markers)
+        if self.session_markers:
+            data["session_markers"] = list(self.session_markers)
+        if self.minter:
+            data["minter"] = self.minter
+        if self.ladder != ("session", "mint"):
+            data["ladder"] = list(self.ladder)
+        if self.probe_path != "/":
+            data["probe_path"] = self.probe_path
+        if self.social:
+            data["social"] = self.social
+        return data
+
+    @classmethod
+    def from_data(cls, data: Mapping[str, Any]) -> AccessRecipe:
+        return cls(
+            session_markers=tuple(str(m) for m in data.get("session_markers", ())),
+            minter=str(data.get("minter", "")),
+            ladder=tuple(str(s) for s in data.get("ladder", ("session", "mint"))),
+            probe_path=str(data.get("probe_path", "/")),
+            social=str(data.get("social", "")),
+            dead_endpoint_markers=tuple(str(m) for m in data.get("dead_endpoint_markers", ())),
+            dead_session_markers=tuple(str(m) for m in data.get("dead_session_markers", ())),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceDecl:
+    """ПОЛНОЕ описание сервиса — единственный вход декларации в рантайм."""
+
+    name: str
+    kind: ServiceKind
+    base_url: str
+    auth: AuthDecl = field(default_factory=AuthDecl)
+    limits: LimitDecl = field(default_factory=LimitDecl)
+    endpoints: tuple[EndpointDecl, ...] = ()
+    access: AccessRecipe | None = None
+
+    def endpoint(self, name: str) -> EndpointDecl:
+        """Операция по имени. Нет — `KeyError` со списком известных."""
+        for ep in self.endpoints:
+            if ep.name == name:
+                return ep
+        known = ", ".join(sorted(e.name for e in self.endpoints)) or "—"
+        raise KeyError(f"операции {name!r} нет в декларации {self.name!r}; известны: {known}")
+
+    def validate(self) -> ServiceDecl:
+        """Проверить непротиворечивость. Возвращает себя — удобно в цепочке.
+
+        Ловим ровно то, что иначе всплывёт ночью в бою:
+
+        * белый сервис с рецептом доступа (или скрытый без него) — опечатка в
+          ``kind``, а не «гибкость»;
+        * скрытый сервис без чеканщика в лестнице — доступ держать нечем;
+        * пустой ``base_url``/дубли имён операций.
+        """
+        if not self.base_url:
+            raise ValueError(f"сервис {self.name!r}: пустой base_url")
+        names = [e.name for e in self.endpoints]
+        dupes = sorted({n for n in names if names.count(n) > 1})
+        if dupes:
+            raise ValueError(f"сервис {self.name!r}: операции объявлены дважды: {dupes}")
+        if self.kind is ServiceKind.WHITE:
+            if self.access is not None:
+                raise ValueError(
+                    f"сервис {self.name!r} объявлен белым, но несёт рецепт доступа. "
+                    "Белый путь не поднимает сессий и не чеканит — либо убери "
+                    "[access], либо поставь kind = \"hidden\"."
+                )
+            if self.auth.scheme is AuthScheme.SESSION:
+                raise ValueError(
+                    f"сервис {self.name!r}: схема 'session' — это авторизация "
+                    "СЕССИЕЙ, она бывает только у скрытого API"
+                )
+        else:
+            if self.access is None:
+                raise ValueError(
+                    f"сервис {self.name!r} объявлен скрытым, но рецепта доступа нет: "
+                    "нечем ни доказать вход, ни отчеканить его заново"
+                )
+            if "mint" in self.access.ladder and not self.access.minter:
+                raise ValueError(
+                    f"сервис {self.name!r}: в лестнице есть ступень 'mint', "
+                    "но чеканщик не назван (`minter`)"
+                )
+        return self
+
+
+def decl_to_data(decl: ServiceDecl) -> dict[str, Any]:
+    """Декларация → обычный словарь (то, что ложится в TOML/JSON)."""
+    data: dict[str, Any] = {
+        "name": decl.name,
+        "kind": decl.kind.value,
+        "base_url": decl.base_url,
+    }
+    auth = decl.auth.to_data()
+    if auth != {"scheme": AuthScheme.NONE.value}:
+        data["auth"] = auth
+    limits = decl.limits.to_data()
+    if limits:
+        data["limits"] = limits
+    if decl.endpoints:
+        data["endpoint"] = [e.to_data() for e in decl.endpoints]
+    if decl.access is not None:
+        data["access"] = decl.access.to_data()
+    return data
+
+
+def decl_from_data(data: Mapping[str, Any]) -> ServiceDecl:
+    """Словарь → декларация. ЕДИНСТВЕННЫЙ вход данных в рантайм."""
+    raw_endpoints: Sequence[Mapping[str, Any]] = data.get("endpoint", ()) or ()
+    access = data.get("access")
+    return ServiceDecl(
+        name=str(data["name"]),
+        kind=ServiceKind(data.get("kind", ServiceKind.WHITE)),
+        base_url=str(data.get("base_url", "")),
+        auth=AuthDecl.from_data(data.get("auth", {})),
+        limits=LimitDecl.from_data(data.get("limits", {})),
+        endpoints=tuple(EndpointDecl.from_data(e) for e in raw_endpoints),
+        access=AccessRecipe.from_data(access) if access is not None else None,
+    )
+
+
+def load_toml(path: str | Path) -> ServiceDecl:
+    """Прочитать декларацию из TOML-файла и проверить её.
+
+    Ошибка формата всплывает ЗДЕСЬ — при загрузке, а не на первом вызове в три
+    часа ночи.
+    """
+    raw = Path(path).read_bytes()
+    return decl_from_data(tomllib.loads(raw.decode("utf-8"))).validate()

clientkit/errors.py

@@ -0,0 +1,37 @@
+"""Ошибки сборщика — ветви ЕДИНОЙ иерархии `corekit`.
+
+Наследуемся от `corekit.errors._DomainError` (доменная база: один обязательный
+``message``, ``code`` из ``default_code``), а не от голого `Exception`: у
+потребителя уже написан ``except CliError`` вокруг всей работы с сервисом, и
+новый кит не имеет права выпасть мимо него. Тем, кому нужна разница между «не
+достучались» и «сервис отказал по существу», доступен точный тип.
+"""
+from __future__ import annotations
+
+from corekit.errors import _DomainError
+
+__all__ = ["AccessUnavailable", "ClientBuildError", "OperationFailed"]
+
+
+class ClientBuildError(_DomainError):
+    """Декларация есть, но клиента из неё не собрать (противоречие/нехватка порта)."""
+
+    default_code = "CLIENT_BUILD_ERROR"
+
+
+class AccessUnavailable(_DomainError):  # noqa: N818  # доменное имя контракта (не *Error)
+    """Скрытый сервис: лестница пройдена до конца, доступа нет.
+
+    Отдельный тип намеренно: «не смогли ДОСТУЧАТЬСЯ» и «достучались, сервис
+    ответил ошибкой» требуют разных действий — в первом случае чинят вход, во
+    втором читают ответ. Одно имя на оба случая означало бы, что человек снова
+    идёт делать бесполезный ручной перевход.
+    """
+
+    default_code = "ACCESS_UNAVAILABLE"
+
+
+class OperationFailed(_DomainError):  # noqa: N818  # доменное имя контракта (не *Error)
+    """Сервис ответил, но по существу операции — отказом (не про доступ)."""
+
+    default_code = "OPERATION_FAILED"

clientkit/hidden.py

@@ -0,0 +1,194 @@
+"""СКРЫТЫЙ путь: клиент, который САМ держит доступ.
+
+Разница с белым не в «сложнее», а в другом виде отказа. У белого API отказ — это
+ответ сервиса по существу операции. У скрытого отказов ЧЕТЫРЕ вида, и они
+требуют разных действий:
+
+  ==============================  =========================================
+  сервер увёл на страницу входа   сессия мертва → отчеканить заново
+  сервер не знает метода          адрес мёртв → взять следующего кандидата
+  до сервера не дошли             инфраструктура → человека звать не за чем
+  сервис ответил по существу      обычный ответ
+  ==============================  =========================================
+
+Таксономию мы не изобретаем: диагноз ставит `corekit.diagnosis.access` по
+ПОДПИСИ ОТВЕТА — та же функция, что у живой пробы и у реестра эндпоинтов. Две
+таксономии на одних уликах разъехались бы за месяц.
+
+ЧТО ЗДЕСЬ СОБИРАЕТСЯ ИЗ ГОТОВЫХ ЧАСТЕЙ (ни строчки заново):
+
+* сессия — `authkit_client.sessions.SessionStore` (или любой `SessionStorePort`);
+* чеканка — `authkit_client.ports.minted_state` (регистрирует `browserkit`,
+  этот модуль браузер НЕ импортирует);
+* адреса-кандидаты — `adapterkit.endpoints.EndpointRegistry`, если adapterkit
+  установлен; иначе равнозначный внутренний реестр (:mod:`clientkit._candidates`).
+
+ЛЕСТНИЦА ДЕГРАДАЦИИ идёт из ДЕКЛАРАЦИИ (``access.ladder``), а не из кода:
+``["session", "mint"]`` значит «сперва взять сохранённую, потом чеканить». Порядок
+и состав правятся в TOML.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from corekit import SessionRef
+from corekit.diagnosis.access import AccessState, classify_access
+
+from clientkit._base import ServiceClientBase
+from clientkit._candidates import CandidateBook
+from clientkit.declaration import EndpointDecl, ServiceDecl
+from clientkit.errors import AccessUnavailable
+from clientkit.ports import RequestPort
+
+__all__ = ["HiddenApiClient"]
+
+
+class HiddenApiClient(ServiceClientBase):
+    """Клиент скрытого API: держит сессию, переживает смерть адреса.
+
+    Аргументы сверх базовых:
+
+    * ``session_store`` — любой `SessionStorePort` (по умолчанию — поставляемый
+      `SessionStore`, но подменяется без правок этого файла);
+    * ``profile``/``account_id`` — координаты сессии в сторе;
+    * ``mint`` — ``async (SessionRef) -> storage_state``. По умолчанию —
+      :func:`authkit_client.ports.minted_state` с чеканщиком из декларации.
+    """
+
+    def __init__(
+        self,
+        decl: ServiceDecl,
+        transport: RequestPort,
+        *,
+        session_store: Any | None = None,
+        profile: str = "default",
+        account_id: str = "me",
+        mint: Any | None = None,
+    ) -> None:
+        super().__init__(decl, transport)
+        recipe = decl.access
+        assert recipe is not None  # гарантировано ServiceDecl.validate()
+        self._recipe = recipe
+        self._store = session_store
+        self._ref = SessionRef(
+            profile=profile,
+            social=recipe.social or decl.name,
+            account_id=account_id,
+        )
+        self._mint = mint
+        self._cookies: dict[str, str] | None = None
+        self._book = CandidateBook.for_service(decl)
+        #: сколько раз пришлось чеканить — улика для тестов и отчётов
+        self.mints = 0
+
+    # ------------------------------------------------------------------ #
+    # доступ                                                             #
+    # ------------------------------------------------------------------ #
+    async def _headers(self) -> dict[str, str]:
+        """Cookie-заголовок из ЖИВОЙ сессии; нет сессии — пройти лестницу."""
+        if self._cookies is None:
+            self._cookies = await self._acquire_access()
+        return {"Cookie": "; ".join(f"{k}={v}" for k, v in self._cookies.items())}
+
+    async def _acquire_access(self, *, force_mint: bool = False) -> dict[str, str]:
+        """ЛЕСТНИЦА ДЕГРАДАЦИИ из декларации: ступень за ступенью, до первой годной.
+
+        ``force_mint`` пропускает ступень ``session``: она только что доказала
+        свою негодность (сервер увёл на вход), и брать её снова — гарантированный
+        второй отказ.
+        """
+        tried: list[str] = []
+        for step in self._recipe.ladder:
+            if step == "session" and not force_mint:
+                cookies = await self._cookies_from_store()
+                tried.append("session")
+                if cookies:
+                    return cookies
+            elif step == "mint":
+                tried.append("mint")
+                state = await self._do_mint()
+                cookies = _cookies_from_state(state)
+                if cookies:
+                    await self._save_state(state)
+                    return cookies
+        raise AccessUnavailable(
+            f"сервис {self.decl.name!r}: лестница доступа пройдена целиком "
+            f"({' → '.join(tried) or '—'}), годного доступа нет. Маркеры сессии "
+            f"по декларации: {list(self._recipe.session_markers) or '—'}."
+        )
+
+    async def _cookies_from_store(self) -> dict[str, str]:
+        """Сохранённая сессия → cookies, ЕСЛИ в ней есть объявленные маркеры.
+
+        Маркеры, а не факт наличия файла: файл лежит и у мёртвой сессии — ровно
+        та ложь, из-за которой `login-status` годами отвечал по файлу.
+        """
+        store = self._store
+        if store is None:
+            return {}
+        state = await store.load_state(self._ref)
+        if not state:
+            return {}
+        cookies = _cookies_from_state(state)
+        markers = self._recipe.session_markers
+        if markers and not all(m in cookies for m in markers):
+            return {}
+        return cookies
+
+    async def _do_mint(self) -> dict[str, Any]:
+        """Отчеканить доступ. Браузер приходит ЧЕРЕЗ ПОРТ, импорта его тут нет."""
+        self.mints += 1
+        if self._mint is not None:
+            return await self._mint(self._ref)
+        from authkit_client.ports import minted_state
+
+        return await minted_state(self._recipe.minter, self._ref)
+
+    async def _save_state(self, state: dict[str, Any]) -> None:
+        if self._store is not None:
+            await self._store.save_state(self._ref, state)
+
+    # ------------------------------------------------------------------ #
+    # адреса-кандидаты                                                    #
+    # ------------------------------------------------------------------ #
+    async def _address(self, endpoint: EndpointDecl) -> str:
+        """Текущий ЖИВОЙ адрес операции (кандидаты — данные, а не код)."""
+        return self._book.active(endpoint)
+
+    async def _inspect(self, endpoint: EndpointDecl, response: Any) -> bool:
+        """Разобрать отказ по ПОДПИСИ и решить: чинить и повторять — или отдать.
+
+        Ровно три исхода, и все три диктуются `classify_access`:
+
+        * ``SESSION_DEAD``  → выбросить cookies, чеканить, повторить;
+        * ``ENDPOINT_DEAD`` → пометить адрес мёртвым, взять следующего, повторить;
+        * всё остальное     → это ответ сервиса, повторять нечего.
+        """
+        verdict = classify_access(
+            response=response,
+            # ДОМЕННЫЕ улики — из ДЕКЛАРАЦИИ, а не из кода: «у этого сервиса
+            # мёртвый метод отвечает вот так». Общие улики знает сам классификатор.
+            endpoint_markers=self._recipe.dead_endpoint_markers,
+            session_markers=self._recipe.dead_session_markers,
+        )
+        if verdict.state is AccessState.SESSION_DEAD:
+            self._cookies = await self._acquire_access(force_mint=True)
+            return True
+        if verdict.state is AccessState.ENDPOINT_DEAD:
+            if self._book.bury(endpoint, why=verdict.why):
+                return True
+            # Заменять нечем. Это НЕ «сервис ответил ошибкой» и НЕ «сессия
+            # протухла»: отдать такой ответ наверх как обычный — значит снова
+            # отправить человека делать бесполезный перевход.
+            raise AccessUnavailable(
+                f"сервис {self.decl.name!r}, операция {endpoint.name!r}: живых "
+                f"адресов не осталось ({verdict.why}). Нужен актуальный адрес "
+                "метода — перевход не поможет."
+            )
+        return False
+
+
+def _cookies_from_state(state: Any) -> dict[str, str]:
+    """``storage_state`` (форма Playwright) → ``{name: value}``."""
+    raw = (state or {}).get("cookies", []) or []
+    return {c["name"]: c.get("value", "") for c in raw if isinstance(c, dict) and c.get("name")}