funora 0.0.1.dev2__py3-none-any.whl

funora/_price_audit.py

@@ -0,0 +1,281 @@
+"""Журнал правок цены: что стояло у лота до того, как его тронул бот.
+
+ЗАЧЕМ. Контракт требует у lots.update_price аудита before_state, и требование
+это единственное в своём роде: больше ни одной операции аудит не предписан.
+Довод у него простой и невесёлый. Правку цены нельзя отменить обращением к
+площадке - у неё нет ни истории цен, ни отката. Единственный способ вернуть как
+было - знать, как было. Знать это обязаны МЫ.
+
+ЗАПИСЬ ИДЁТ ВПЕРЕДИ СОХРАНЕНИЯ. Тот же приём и тот же довод, что у реестра
+выданного: «запишем, когда подтвердится» означает не записать ровно те правки,
+которые могли уйти. Процесс, упавший между отправкой и подтверждением, оставил
+бы лот с новой ценой и без следа прежней.
+
+ЖУРНАЛ ОГРАНИЧЕН, И ПРЕДЕЛ НАЗВАН ВСЛУХ. Реестр выданного растёт на запись за
+заказ и не забывает ничего; здесь так нельзя. Переоценщик, ходящий раз в минуту,
+за год напишет полмиллиона записей. Поэтому старые вытесняются - но счётчик
+вытесненных хранится и отдаётся: молчаливое усечение читалось бы как «правок
+было столько», а их было больше.
+
+ПЕРВАЯ ЗАПИСЬ О ЛОТЕ НЕ ВЫТЕСНЯЕТСЯ. Она отвечает на вопрос «какая цена стояла
+до того, как бот вмешался вообще», и ответ на него не устаревает - в отличие от
+любой промежуточной.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Final
+
+from .errors import StateSchemaIncompatibleError
+
+__all__ = [
+    "PriceChange",
+    "PriceAudit",
+    "DEFAULT_JOURNAL_LIMIT",
+    "UNSAFE_PRICE_CHANGES_WITHOUT_AUDIT",
+]
+
+#: Имя послабления и имя отметки в состоянии здоровья. Одно на оба места
+#: нарочно: два имени одного послабления расходятся молча.
+UNSAFE_PRICE_CHANGES_WITHOUT_AUDIT: Final[str] = "unsafe_price_changes_without_audit"
+
+#: Сколько правок журнал держит сверх первых записей о каждом лоте.
+#:
+#: Число выбрано не измерением, а прикидкой: пятьсот записей - это сотня
+#: килобайт в файле состояния и заведомо больше, чем успевает набежать между
+#: двумя взглядами человека на журнал.
+DEFAULT_JOURNAL_LIMIT: Final[int] = 500
+
+
+@dataclass(frozen=True, slots=True)
+class PriceChange:
+    """Запись о правке цены.
+
+    Attributes:
+        offer_id (str): Предложение, которому меняли цену.
+        node_id (str): Раздел, в котором оно лежит.
+        price_before (str): Цена, стоявшая в поле до правки.
+        price_after (str): Цена, которую отправили.
+        revision_before (str): Отпечаток лота до правки.
+        at_ms (int): Момент записи по стенным часам. Момент ЗАПИСИ, а не
+            подтверждения: запись идёт впереди сохранения, и подтверждения на
+            этот момент ещё нет.
+    """
+
+    offer_id: str
+    node_id: str
+    price_before: str
+    price_after: str
+    revision_before: str
+    at_ms: int
+
+
+class PriceAudit:
+    """Журнал правок цены.
+
+    Args:
+        limit (int): Сколько записей держать сверх первой записи о каждом лоте.
+            Ноль и отрицательное означают «не вытеснять».
+    """
+
+    __slots__ = ("_first", "_journal", "_dropped", "_limit", "durable")
+
+    def __init__(self, limit: int = DEFAULT_JOURNAL_LIMIT) -> None:
+        #: Переживает ли журнал перезапуск. Ставится движком, когда файл
+        #: состояния есть либо когда вызывающий назвал послабление вслух.
+        #: Ложь означает отказ правки цены, а не молчаливую правку без следа.
+        self.durable: bool = False
+        #: Первая правка каждого лота. Не вытесняется никогда.
+        self._first: dict[str, PriceChange] = {}
+        #: Все правки по порядку, включая первые.
+        self._journal: list[PriceChange] = []
+        #: Сколько записей вытеснено пределом.
+        self._dropped: int = 0
+        self._limit = limit
+
+    def record(self, change: PriceChange) -> None:
+        """Записывает правку.
+
+        Аргументы:
+            change (PriceChange): Что и на что меняли.
+
+        Возвращает:
+            None
+        """
+        self._first.setdefault(change.offer_id, change)
+        self._journal.append(change)
+        if self._limit > 0:
+            while len(self._journal) > self._limit:
+                self._journal.pop(0)
+                self._dropped += 1
+
+    def original(self, offer_id: str) -> PriceChange | None:
+        """Возвращает первую известную правку лота.
+
+        Она и отвечает на вопрос «как было до бота»: промежуточные цены ставил
+        тот же бот, а эта стояла до него.
+
+        Аргументы:
+            offer_id (str): Предложение.
+
+        Возвращает:
+            PriceChange | None: Первая запись либо None, если лот не трогали.
+        """
+        return self._first.get(offer_id)
+
+    def history(self, offer_id: str | None = None) -> tuple[PriceChange, ...]:
+        """Возвращает записи журнала по порядку.
+
+        Аргументы:
+            offer_id (str | None): Отобрать по предложению либо None - все.
+
+        Возвращает:
+            tuple[PriceChange, ...]: Записи от старой к новой.
+        """
+        if offer_id is None:
+            return tuple(self._journal)
+        return tuple(one for one in self._journal if one.offer_id == offer_id)
+
+    @property
+    def dropped(self) -> int:
+        """Сколько записей вытеснено пределом.
+
+        Возвращает:
+            int: Число вытесненных. Ноль означает, что вытеснения не было.
+        """
+        return self._dropped
+
+    def snapshot(self) -> dict[str, Any]:
+        """Отдаёт состояние обычными значениями для файла состояния.
+
+        Возвращает:
+            dict[str, Any]: Состояние, пригодное для записи в файл.
+        """
+        return {
+            "journal": [_flatten(one) for one in self._journal],
+            "first": [_flatten(one) for one in self._first.values()],
+            "dropped": self._dropped,
+        }
+
+    def restore(self, payload: dict[str, Any], *, merge: bool = False) -> None:
+        """Восстанавливает состояние из файла.
+
+        Проверяется целиком до изменения живого журнала. Повреждённые записи
+        отклоняются: пропуск мог бы выдать промежуточную цену за исходную.
+
+        Аргументы:
+            payload (dict[str, Any]): Прочитанное из файла состояния.
+            merge (bool): Добавить записи текущего сеанса после сохранённых.
+                Первые цены с диска имеют приоритет; порядок не зависит от
+                перевода стенных часов.
+
+        Возвращает:
+            None
+
+        Raises:
+            StateSchemaIncompatibleError: Если раздел или запись повреждены.
+        """
+        if not isinstance(payload, dict):
+            raise StateSchemaIncompatibleError("раздел price_audit обязан быть объектом")
+        journal = _records(payload.get("journal", []))
+        first: dict[str, PriceChange] = {}
+        for one in _records(payload.get("first", [])):
+            if one.offer_id in first:
+                raise StateSchemaIncompatibleError("повтор первой цены лота в price_audit")
+            first[one.offer_id] = one
+        # Записи журнала тоже кандидаты в первые: файл мог быть записан прежней
+        # редакцией, у которой раздела first не было вовсе, и терять из-за
+        # этого «как было до бота» нельзя.
+        for one in journal:
+            if "first" in payload and one.offer_id not in first:
+                raise StateSchemaIncompatibleError("в price_audit отсутствует первая цена лота")
+            first.setdefault(one.offer_id, one)
+
+        dropped = payload.get("dropped", 0)
+        # Логическое исключается отдельно: истина в Python - это единица, и
+        # счётчик True прочитался бы как одна вытесненная запись.
+        if isinstance(dropped, bool) or not isinstance(dropped, int) or dropped < 0:
+            raise StateSchemaIncompatibleError("неверный счётчик вытеснения price_audit")
+
+        if merge:
+            journal.extend(self._journal)
+            for offer_id, one in self._first.items():
+                first.setdefault(offer_id, one)
+            dropped += self._dropped
+            if self._limit > 0 and len(journal) > self._limit:
+                dropped += len(journal) - self._limit
+                journal = journal[-self._limit :]
+
+        self._journal = journal
+        self._first = first
+        self._dropped = dropped
+
+    def __len__(self) -> int:
+        """Возвращает число записей в журнале.
+
+        Возвращает:
+            int: Сколько правок хранится. Вытесненные не считаются.
+        """
+        return len(self._journal)
+
+
+def _flatten(change: PriceChange) -> dict[str, Any]:
+    """Раскладывает запись обычными значениями.
+
+    Аргументы:
+        change (PriceChange): Запись.
+
+    Возвращает:
+        dict[str, Any]: Поля записи.
+    """
+    return {
+        "offer_id": change.offer_id,
+        "node_id": change.node_id,
+        "price_before": change.price_before,
+        "price_after": change.price_after,
+        "revision_before": change.revision_before,
+        "at_ms": change.at_ms,
+    }
+
+
+def _records(raw: Any) -> list[PriceChange]:
+    """Проверяет и собирает все записи без приведения и потери полей.
+
+    Аргументы:
+        raw (Any): Прочитанное из файла.
+
+    Возвращает:
+        list[PriceChange]: Пригодные записи по порядку.
+    """
+    if not isinstance(raw, list):
+        raise StateSchemaIncompatibleError("записи price_audit обязаны быть списком")
+
+    out: list[PriceChange] = []
+    for one in raw:
+        if not isinstance(one, dict):
+            raise StateSchemaIncompatibleError("запись price_audit обязана быть объектом")
+
+        offer_id = one.get("offer_id")
+        if not isinstance(offer_id, str) or not offer_id.strip():
+            raise StateSchemaIncompatibleError("неверный offer_id в price_audit")
+
+        for field in ("node_id", "price_before", "price_after", "revision_before"):
+            if not isinstance(one.get(field), str):
+                raise StateSchemaIncompatibleError(f"неверное поле {field} в price_audit")
+
+        at_ms = one.get("at_ms")
+        if isinstance(at_ms, bool) or not isinstance(at_ms, int):
+            raise StateSchemaIncompatibleError("неверное время записи price_audit")
+
+        out.append(
+            PriceChange(
+                offer_id=offer_id,
+                node_id=one["node_id"],
+                price_before=one["price_before"],
+                price_after=one["price_after"],
+                revision_before=one["revision_before"],
+                at_ms=at_ms,
+            )
+        )
+    return out

funora/_proxies.py

@@ -0,0 +1,232 @@
+"""Перечень прокси и выбор того, через который сейчас идти.
+
+Прокси здесь - не способ ходить чаще, а способ ходить ОТКУДА-ТО. Спецификация
+привязывает бюджет к сетевой идентичности, то есть к паре «исходящий адрес,
+целевой хост», и прокси меняет первую половину пары: у каждого свой запас
+токенов, своё остывание и свой счёт ограничений.
+
+Из этого следует всё остальное.
+
+Переключение не отменяет отступления. Прокси, получивший ограничение частоты,
+остывает по объявленному правилу независимо от того, ушла работа на другой или
+нет: вернуться к нему раньше срока нельзя. Иначе переключение означало бы
+«продолжать в прежнем темпе с другого адреса», а не «дать этому адресу
+отдохнуть».
+
+Аккаунт привязан к прокси. Аккаунт, ходивший с одного адреса и вдруг сменивший
+его, выглядит иначе, чем аккаунт, у которого адрес постоянен: привязка держит
+пару стабильной, пока прокси жив. Смена происходит только когда прежний не
+может работать - остывает после ограничения либо не отвечает.
+
+Порядок перечня уважается. Вызывающий назвал прокси в том порядке, в каком хочет
+ими пользоваться; перебирать по кругу значило бы размазывать один аккаунт по
+всем адресам, а это ровно то, чего привязка избегает.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from time import monotonic
+from typing import Final
+
+from ._identity import REGISTRY, IdentityRegistry, identity_of
+from .errors import ConfigurationError
+
+__all__ = ["Proxy", "ProxyPool", "DEFAULT_ACCOUNT"]
+
+#: Имя аккаунта, под которым клиент выбирает идентичность до того, как
+#: наблюдение назвало настоящее.
+#:
+#: Клиент заводится раньше, чем становится известен аккаунт: секрет у него
+#: есть, а идентификатор аккаунта читается со страницы. Привязка при первом
+#: же наблюдении перезаписывается настоящим именем.
+DEFAULT_ACCOUNT: Final[str] = "self"
+
+_log = logging.getLogger("funora.proxies")
+
+#: Схемы, через которые ходить нельзя.
+#:
+#: Секрет уходит в заголовке каждого запроса, и прокси видит весь трафик. Схема
+#: без шифрования до прокси означает, что ключ читает любой на пути до него -
+#: то есть прокси, поставленный ради приватности, её и отменяет.
+_INSECURE_SCHEMES: Final[frozenset[str]] = frozenset({"http"})
+
+
+@dataclass(frozen=True, slots=True)
+class Proxy:
+    """Один прокси из перечня.
+
+    Attributes:
+        name (str): Имя для журналов и для имени идентичности. Адрес сюда не
+            попадает намеренно: он может нести пароль, а имя уходит в журналы.
+        url (str): Адрес прокси в форме, которую понимает транспорт.
+    """
+
+    name: str
+    url: str
+
+
+class ProxyPool:
+    """Перечень прокси и выбор пригодного.
+
+    Args:
+        proxies (tuple[Proxy, ...]): Прокси в порядке предпочтения. Пустой
+            перечень означает прямое соединение.
+        host (str): Целевой хост. Входит в имя идентичности: один и тот же
+            прокси к разным хостам - разные идентичности, потому что
+            ограничения применяет хост.
+        registry (IdentityRegistry): Реестр идентичностей. По умолчанию общий
+            на процесс.
+
+    Raises:
+        ConfigurationError: Если два прокси названы одинаково либо адрес
+            небезопасен.
+    """
+
+    __slots__ = ("_by_account", "_host", "_proxies", "_registry")
+
+    def __init__(
+        self,
+        proxies: tuple[Proxy, ...] = (),
+        *,
+        host: str,
+        registry: IdentityRegistry | None = None,
+    ) -> None:
+        names = [proxy.name for proxy in proxies]
+        if len(set(names)) != len(names):
+            raise ConfigurationError(
+                "имена прокси повторяются: имя входит в имя идентичности, и "
+                "одинаковые имена свели бы два разных адреса в одно ведро токенов"
+            )
+        for proxy in proxies:
+            scheme = proxy.url.split("://", 1)[0].lower()
+            if scheme in _INSECURE_SCHEMES:
+                raise ConfigurationError(
+                    f"прокси {proxy.name} объявлен по схеме {scheme}: секрет "
+                    "уходит в заголовке каждого запроса, и без шифрования до "
+                    "прокси его читает любой на пути. Возьмите https или socks5"
+                )
+
+        self._proxies = proxies
+        self._host = host
+        self._registry = registry if registry is not None else REGISTRY
+        self._by_account: dict[str, str] = {}
+
+    @property
+    def proxies(self) -> tuple[Proxy, ...]:
+        """Перечень прокси в порядке предпочтения.
+
+        Returns:
+            tuple[Proxy, ...]: Объявленные прокси.
+        """
+        return self._proxies
+
+    def _identity_names(self) -> tuple[str, ...]:
+        """Собирает имена идентичностей в порядке предпочтения.
+
+        Returns:
+            tuple[str, ...]: Имена. При пустом перечне - одно прямое соединение.
+        """
+        if not self._proxies:
+            return (identity_of(None, self._host),)
+        return tuple(identity_of(proxy.name, self._host) for proxy in self._proxies)
+
+    def _url_by_identity(self, name: str) -> str | None:
+        """Находит адрес прокси по имени идентичности.
+
+        Args:
+            name (str): Имя идентичности.
+
+        Returns:
+            str | None: Адрес либо None при прямом соединении.
+        """
+        for proxy in self._proxies:
+            if identity_of(proxy.name, self._host) == name:
+                return proxy.url
+        return None
+
+    def choose(self, account_id: str, now: float | None = None) -> tuple[str, str | None]:
+        """Выбирает идентичность для аккаунта.
+
+        Привязка держится, пока прокси работает: аккаунт, ходивший с одного
+        адреса и вдруг сменивший его, выглядит иначе, чем аккаунт с постоянным
+        адресом. Смена происходит только когда прежний остывает после
+        ограничения либо был отставлен как неработающий.
+
+        Args:
+            account_id (str): Аккаунт, для которого идёт запрос.
+            now (float | None): Момент. По умолчанию текущий.
+
+        Returns:
+            tuple[str, str | None]: Имя идентичности и адрес прокси. Адрес None
+            означает прямое соединение.
+
+        Raises:
+            ConfigurationError: Если остывают все объявленные прокси. Отказ
+                вслух честнее молчаливого возврата к прямому соединению: прямое
+                соединение раскрывает адрес, который вызывающий намеренно
+                прятал.
+        """
+        moment = monotonic() if now is None else now
+        names = self._identity_names()
+
+        bound = self._by_account.get(account_id)
+        if bound in names and not self._registry.get(bound).is_cooling(moment):
+            return bound, self._url_by_identity(bound)
+
+        chosen = self._registry.healthy(names, moment)
+        if chosen is None:
+            cooling = ", ".join(
+                f"{name} ещё {self._registry.get(name).cooldown_until - moment:.0f} с"
+                for name in names
+            )
+            raise ConfigurationError(
+                "все объявленные прокси остывают после ограничения частоты: "
+                f"{cooling}. Возврат к прямому соединению не делается: он "
+                "раскрыл бы адрес, который вы намеренно прятали"
+            )
+
+        if bound is not None and bound != chosen:
+            _log.warning(
+                "аккаунт %s переведён с %s на %s: прежний остывает после ограничения частоты",
+                account_id,
+                bound,
+                chosen,
+            )
+        self._by_account[account_id] = chosen
+        return chosen, self._url_by_identity(chosen)
+
+    def note_limit(self, name: str, now: float | None = None) -> None:
+        """Учитывает ограничение частоты, полученное этой идентичностью.
+
+        Args:
+            name (str): Имя идентичности.
+            now (float | None): Момент. По умолчанию текущий.
+
+        Returns:
+            None
+        """
+        self._registry.get(name).note_limit(monotonic() if now is None else now)
+
+    def note_success(self, name: str) -> None:
+        """Учитывает успешный запрос этой идентичности.
+
+        Args:
+            name (str): Имя идентичности.
+
+        Returns:
+            None
+        """
+        self._registry.get(name).note_success()
+
+    def bound_to(self, account_id: str) -> str | None:
+        """Сообщает, к какой идентичности привязан аккаунт.
+
+        Args:
+            account_id (str): Аккаунт.
+
+        Returns:
+            str | None: Имя идентичности либо None, если привязки ещё нет.
+        """
+        return self._by_account.get(account_id)

funora/_raise.py

@@ -0,0 +1,150 @@
+"""Поднятие предложений раздела и разбор ответа площадки.
+
+ЧТО ЭТА ОПЕРАЦИЯ ДЕЛАЕТ. Поднимает В ВЫДАЧЕ ВСЕ предложения раздела сразу, а не
+одно: запрос несёт игру и раздел, идентификатора предложения в нём нет. Кнопка
+на странице так и называется - «Поднять предложения».
+
+ЧЕМ ОНА ОПАСНА. Поднятие тратит суточный предел, восстановить который нельзя.
+Повтор при неоднозначном исходе запрещён контрактом: вместо него положена сверка
+фактического состояния.
+
+ПЛОЩАДКА ОТВЕЧАЕТ ПРИЗНАКОМ ОТКАЗА, А НЕ УСПЕХА - поле error. Это важно: читать
+надо его отрицание, и молчаливое «нет поля error, значит успех» было бы неверно.
+Отсутствие поля означает не успех, а непонятный ответ.
+
+ОДНОГО ОТРИЦАНИЯ ERROR МАЛО, и это выяснилось сверкой с независимой реализацией
+того же протокола. Ответ без признака отказа, но С КЛЮЧОМ url, поднятием не
+является: площадка возвращает адрес окна выбора подкатегорий, то есть спрашивает,
+что именно поднимать. Прочитать такой ответ успехом значило бы сказать «поднято»
+там, где не поднято ничего, - ровно та молчаливая неправда, ради которой весь
+этот разбор и написан подробным.
+
+Сами мы такого ответа не наблюдали. Пометка - third_party_report, источник назван
+в правиле извлечения; наше обращение с ним от чужого отличается тем, что мы не
+толкуем незнакомое, а отказываемся объявлять успех.
+
+Наблюдено 31.08.2026: POST /lots/raise, поля game_id и node_id, ответ
+{error, msg, unlock_at, wait}.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Final
+
+from ._observed import Observed
+from .errors import ProtocolChangedError
+
+__all__ = ["RaiseResult", "parse_raise", "RAISE_PATH"]
+
+#: Адрес поднятия. Наблюдён записью запроса.
+RAISE_PATH: Final[str] = "/lots/raise"
+
+
+@dataclass(frozen=True, slots=True)
+class RaiseResult:
+    """Исход поднятия предложений раздела.
+
+    Attributes:
+        raised (bool): Состоялось ли поднятие. Читается отрицанием поля error
+            И отсутствием ключа url: ответ с адресом окна выбора подкатегорий
+            поднятием не является.
+        choice_url (Observed[str]): Адрес окна выбора подкатегорий, если площадка
+            его вернула. Присутствие означает, что поднятие НЕ состоялось и
+            площадка спрашивает, что поднимать.
+        message (str): Сообщение площадки человеку, как есть. Не разбирается:
+            это текст на локали интерфейса, и выводить из него причину значило
+            бы строить разбор на переводе.
+        unlock_at (Observed[str]): Момент следующего поднятия, как его назвала
+            площадка. ТЕКСТОМ: формат не установлен, и разбирать его в момент
+            времени значило бы гадать о часовом поясе.
+        wait_seconds (Observed[int]): Сколько ждать, как назвала площадка.
+            ЕДИНИЦА НЕ НАБЛЮДАЛАСЬ: поле называется wait и приходит целым, а
+            секунды это или что-то ещё - неизвестно.
+        observed_at (datetime): Момент получения ответа.
+    """
+
+    raised: bool
+    message: str
+    unlock_at: Observed[str]
+    wait_seconds: Observed[int]
+    choice_url: Observed[str]
+    observed_at: datetime
+
+
+def parse_raise(payload: Any, *, observed_at: datetime) -> RaiseResult:
+    """Разбирает ответ площадки на поднятие.
+
+    ПРИЗНАК ОТКАЗА ОБЯЗАТЕЛЕН. Без него неизвестно, состоялось поднятие или нет,
+    а повторить, чтобы выяснить, нельзя: повтор тратит невосполнимый предел.
+    Поэтому ответ без error отвергается вслух, а не толкуется как успех.
+
+    Аргументы:
+        payload (Any): Разобранное тело ответа.
+        observed_at (datetime): Момент получения.
+
+    Возвращает:
+        RaiseResult: Исход.
+
+    Raises:
+        ProtocolChangedError: Если в ответе нет признака отказа.
+    """
+    if not isinstance(payload, dict):
+        raise ProtocolChangedError(
+            f"ответ на поднятие не объект, а {type(payload).__name__}. Что "
+            "случилось с предложениями - неизвестно, а повторить, чтобы "
+            "выяснить, нельзя: повтор тратит суточный предел"
+        )
+
+    error = payload.get("error")
+    if not isinstance(error, bool):
+        raise ProtocolChangedError(
+            "в ответе на поднятие нет признака отказа error. Площадка отвечает "
+            "признаком ОТКАЗА, а не успеха, и без него исход неизвестен; "
+            "считать отсутствие поля успехом нельзя - повтор здесь тратит "
+            "невосполнимый предел"
+        )
+
+    raw_wait = payload.get("wait")
+    # Логическое исключается отдельно: истина в Python - это единица, и
+    # wait=True прочиталось бы как «ждать одну единицу».
+    wait = (
+        Observed.present(raw_wait)
+        if isinstance(raw_wait, int) and not isinstance(raw_wait, bool)
+        else Observed.missing("wait_not_in_response")
+    )
+
+    raw_unlock = payload.get("unlock_at")
+    unlock = (
+        Observed.present(raw_unlock)
+        if isinstance(raw_unlock, str) and raw_unlock.strip()
+        else Observed.missing("unlock_at_not_in_response")
+    )
+
+    # КЛЮЧ url ОТМЕНЯЕТ УСПЕХ. Ответ без признака отказа, но с адресом окна
+    # выбора подкатегорий, означает не поднятие, а вопрос «что поднимать»:
+    # площадка ждёт перечня подкатегорий, которого в нашем запросе нет.
+    #
+    # Сами мы такого ответа не видели - знаем о нём от независимой реализации
+    # того же протокола. Поэтому обращение с ним осторожное: мы не берёмся
+    # толковать, что именно площадка спросила, и лишь отказываемся объявлять
+    # успех. Ошибиться здесь в другую сторону дороже - поднятие тратит
+    # невосполнимый суточный предел, и «поднято» вместо «не поднято» пошлёт
+    # вызывающего ждать сутки впустую.
+    raw_url = payload.get("url")
+    choice = (
+        Observed.present(raw_url)
+        if isinstance(raw_url, str) and raw_url.strip()
+        else Observed.missing("url_not_in_response")
+    )
+
+    raw_message = payload.get("msg")
+    return RaiseResult(
+        raised=not error and choice.or_none() is None,
+        message=raw_message if isinstance(raw_message, str) else "",
+        unlock_at=unlock,
+        wait_seconds=wait,
+        choice_url=choice,
+        observed_at=observed_at,
+    )