s-netkit 0.0.1__py3-none-any.whl

netkit/__init__.py

@@ -0,0 +1,240 @@
+"""netkit — СЕТЕВОЙ слой китов. Всё, чем интеграция ходит наружу.
+
+ФОРМА ГРАФА::
+
+        clikit          adapterkit          <- ветки-оболочки
+             \\             /
+              \\           /
+               librarykit                   <- ОРКЕСТРАТОР (сессии, браузер, склад)
+                    |
+                 netkit                     <- СЕТЬ (транспорт, лимиты, повторы)
+                    |
+                 corekit                    <- ОСНОВАНИЕ (значения и правила)
+
+ЧТО СЮДА ПЕРЕЕХАЛО ИЗ librarykit И ПО КАКОМУ ПРИЗНАКУ. Ровно одно: **модуль
+живёт разговором с чужим сервером**. Не «использует httpx», а именно отвечает за
+доставку, темп и живучесть обмена:
+
+* :mod:`netkit.transport` — исполнители запроса поверх httpx (async + sync
+  близнец), choke-point `HttpClient`/`SyncHttpClient`, REST-клиент к своему
+  backend, permissive-рецепты;
+* :mod:`netkit.stream` — persistent-каналы (WebSocket) — `StreamTransport`;
+* :mod:`netkit.rpc` — codec-слой RPC (`JsonCodec`/`PrefixedJsonCodec`);
+* :mod:`netkit.graphql` — GraphQL-клиент поверх транспорта;
+* :mod:`netkit.limit` — `RateLimiter` + token-bucket (проактивный темп);
+* :mod:`netkit.retry` — политики повторов (header-driven и фиксированная);
+* :mod:`netkit.ladder` — ЛЕСТНИЦА ДЕГРАДАЦИИ: чем выполнять запросы и чем
+  добывать состояние, с памятью ступени и событиями спуска;
+* :mod:`netkit.pagination` / :mod:`netkit.upload` / :mod:`netkit.forms` —
+  листание ресурса, resumable-догрузка, form-urlencoded кодек;
+* :mod:`netkit.errmap` — ответ сервера → доменная ошибка;
+* :mod:`netkit.declare` — ОБЪЯВЛЕНИЕ транспорта (http/ws/rpc/graphql) с ЕДИНЫМ
+  поведением лимитов и повторов поверх любого вида.
+
+ЧЕГО ЗДЕСЬ НЕТ И НЕ БУДЕТ: браузера, антибота, хранилища сессий, keyring,
+шифрования, путей состояния. Всё, что живёт ВЫШЕ, приходит сюда СЛОТАМИ
+(:mod:`netkit.providers`) — не импортом. Поэтому netkit ставится и работает без
+оркестратора, а зависимости идут строго вниз: ``netkit → corekit``.
+
+ЛЕНИВЫЙ ФАСАД. Корень пакета не исполняет НИ ОДНОГО подмодуля: `import netkit`
+не тянет ни httpx, ни stamina, ни asyncio. Имена резолвятся по PEP 562 при
+первом обращении (см. `_LAZY_NAMES` и `__getattr__` ниже) — платит тот, кому
+нужно. Это не украшение: `librarykit` реэкспортирует отсюда десятки имён своими
+жадными импортами, и любой жадный импорт здесь мгновенно вернул бы 264 мс httpx
+в стоимость `import librarykit` (зафиксировано fitness-тестами обоих китов).
+
+СОВМЕСТИМОСТЬ. Ни одно имя отсюда не «переехало» для потребителя: `librarykit`
+и его подмодули (`librarykit.transport`, `librarykit.ladder`, `librarykit.limit`,
+…) реэкспортируют ТЕ ЖЕ объекты (не копии), поэтому ``isinstance``/``except``/
+``is``-сравнения работают через любой из путей.
+"""
+from __future__ import annotations
+
+from importlib import import_module as _import_module
+from importlib.util import find_spec as _find_spec
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover — только статическая видимость для IDE/mypy
+    from typing import Any
+
+__version__ = "0.0.1"
+
+#: Ленивые ИМЕНА: имя в корне → модуль, из которого оно берётся. Все они входят в
+#: `__all__`, поэтому `from netkit import *`, `getattr` и `dir()` видят полную
+#: поверхность, ничего при этом не исполняя.
+_LAZY_NAMES: dict[str, str] = {
+    # contract: формы «талии» сетевого слоя + реэкспорт значений основания
+    "PaginationMode": "netkit.contract",
+    "AuthMode": "netkit.contract",
+    "TransportKind": "netkit.contract",
+    "RequestExecutionMode": "netkit.contract",
+    "DEFAULT_TENANT": "netkit.contract",
+    "SessionRef": "netkit.contract",
+    "ExecutionContext": "netkit.contract",
+    "Creds": "netkit.contract",
+    "RequestBody": "netkit.contract",
+    "QuotaScope": "netkit.contract",
+    "QuotaInfo": "netkit.contract",
+    "LimitSpec": "netkit.contract",
+    "ResponseLike": "netkit.contract",
+    "Transport": "netkit.contract",
+    "SyncTransport": "netkit.contract",
+    "HttpRequestExecutor": "netkit.contract",
+    "SyncHttpRequestExecutor": "netkit.contract",
+    "StreamTransport": "netkit.contract",
+    "Codec": "netkit.contract",
+    "Auth": "netkit.contract",
+    "Refreshable": "netkit.contract",
+    "ProactiveRefreshable": "netkit.contract",
+    "ApplyRefreshable": "netkit.contract",
+    "SyncRefreshable": "netkit.contract",
+    "SyncProactiveRefreshable": "netkit.contract",
+    "ErrorMapper": "netkit.contract",
+    "Paginator": "netkit.contract",
+    # transport: исполнители запроса + choke-point'ы + REST-клиент
+    "HttpxTransport": "netkit.transport",
+    "HttpxRequestExecutor": "netkit.transport",
+    "HttpxSyncTransport": "netkit.transport",
+    "HttpxSyncRequestExecutor": "netkit.transport",
+    "HttpClient": "netkit.transport",
+    "SyncHttpClient": "netkit.transport",
+    "RestHttpClient": "netkit.transport",
+    "NoopAuth": "netkit.transport",
+    "PermissiveErrorMapper": "netkit.transport",
+    "build_permissive_http_client": "netkit.transport",
+    "build_permissive_sync_http_client": "netkit.transport",
+    "aclose_http_client": "netkit.transport",
+    "close_sync_http_client": "netkit.transport",
+    "RefreshCallback": "netkit.transport",
+    # limit / retry: темп и живучесть обмена
+    "LimitWindow": "netkit.limit",
+    "LimitPolicy": "netkit.limit",
+    "LimitScope": "netkit.limit",
+    "RateLimiter": "netkit.limit",
+    "RetryPolicy": "netkit.retry",
+    "DEFAULT_RETRY": "netkit.retry",
+    "SimpleRetryPolicy": "netkit.retry",
+    "DEFAULT_SIMPLE_RETRY": "netkit.retry",
+    # errmap: ответ сервера → доменная ошибка
+    "ErrorMap": "netkit.errmap",
+    "ErrorMapBuilder": "netkit.errmap",
+    "BodyRule": "netkit.errmap",
+    "ExcFactory": "netkit.errmap",
+    "AuthExpired": "netkit.errmap",
+    "build_error_map": "netkit.errmap",
+    "DEFAULT_ERROR_MAP": "netkit.errmap",
+    # rpc / stream / graphql: не-REST виды обмена
+    "JsonCodec": "netkit.rpc",
+    "PrefixedJsonCodec": "netkit.rpc",
+    "RpcClient": "netkit.rpc",
+    "StubStreamTransport": "netkit.stream",
+    "WebSocketsStreamTransport": "netkit.stream",
+    "StreamClosedError": "netkit.stream",
+    "GraphQLClient": "netkit.graphql",
+    # pagination / upload / forms: листание, догрузка, кодек тел
+    "CursorPaginator": "netkit.pagination",
+    "PageParams": "netkit.pagination",
+    "DEFAULT_PAGE_PARAMS": "netkit.pagination",
+    "ItemsExtractor": "netkit.pagination",
+    "CursorExtractor": "netkit.pagination",
+    "default_extract_items": "netkit.pagination",
+    "default_extract_cursor": "netkit.pagination",
+    "with_page_params": "netkit.pagination",
+    "FlatPage": "netkit.pagination",
+    "parse_flat_page": "netkit.pagination",
+    "next_flat_offset": "netkit.pagination",
+    "ChunkedUploader": "netkit.upload",
+    "UploadResult": "netkit.upload",
+    "FormCodec": "netkit.forms",
+    # declare: объявление транспорта + единое поведение лимитов и повторов
+    "TransportSpec": "netkit.declare",
+    "DeclaredTransport": "netkit.declare",
+    "declare": "netkit.declare",
+    "register_kind": "netkit.declare",
+    "kinds": "netkit.declare",
+    "UnknownTransportKind": "netkit.declare",
+    "KIND_HTTP": "netkit.declare",
+    "KIND_WS": "netkit.declare",
+    "KIND_RPC": "netkit.declare",
+    "KIND_GRAPHQL": "netkit.declare",
+    # providers: слоты верхнего слоя (браузер, склад, диагностика, egress)
+    "provider": "netkit.providers",
+    "register_provider": "netkit.providers",
+    "unregister_provider": "netkit.providers",
+    "registered_slots": "netkit.providers",
+    "ProviderMissing": "netkit.providers",
+    "SLOTS": "netkit.providers",
+    "SLOT_BROWSER_MINT": "netkit.providers",
+    "SLOT_BROWSER_PROVIDER": "netkit.providers",
+    "SLOT_ENGINE_PROFILE_DIR": "netkit.providers",
+    "SLOT_TRANSPORT_FACTORY": "netkit.providers",
+    "SLOT_DIAGNOSE": "netkit.providers",
+    "SLOT_EGRESS_PROXY": "netkit.providers",
+    "SLOT_JSON_STORE": "netkit.providers",
+    "SLOT_FILE_LOCK": "netkit.providers",
+    "SLOT_STATE_ROOT": "netkit.providers",
+    "SLOT_PATH_SLUG": "netkit.providers",
+    # ladder: лестница деградации (её поверхность полностью — в netkit.ladder)
+    "TransportLadder": "netkit.ladder",
+    "SyncTransportLadder": "netkit.ladder",
+    "ServiceSpec": "netkit.ladder",
+    "MinterLadder": "netkit.ladder",
+    "ExecutorStep": "netkit.ladder",
+    "MinterStep": "netkit.ladder",
+    "DegradationEvent": "netkit.ladder",
+    "subscribe_degradation": "netkit.ladder",
+    "unsubscribe_degradation": "netkit.ladder",
+    "emit_degradation": "netkit.ladder",
+}
+
+#: Подсказки по extras: модуль → что поставить, если внутри не хватило вендора.
+_EXTRA_HINTS: dict[str, str] = {
+    "netkit.stream": "s-netkit[ws]",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Ленивый резолв имён корня (PEP 562).
+
+    Порядок: (1) карта ленивых ИМЁН `_LAZY_NAMES`; (2) РЕАЛЬНЫЙ подмодуль с таким
+    именем — чтобы `import netkit; netkit.transport.HttpClient` работало без
+    отдельного импорта подмодуля. Промах — обычная `AttributeError` (иначе
+    `hasattr()` у потребителя взрывался бы вместо возврата False).
+    """
+    target = _LAZY_NAMES.get(name)
+    if target is None:
+        if not name.startswith("_"):
+            try:
+                found = _find_spec(f"{__name__}.{name}") is not None
+            except (ImportError, ValueError):
+                found = False
+            if found:
+                module = _import_module(f"{__name__}.{name}")
+                globals()[name] = module
+                return module
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        module = _import_module(target)
+    except ModuleNotFoundError as exc:
+        missing = exc.name or ""
+        if missing.startswith(__name__):
+            raise  # сломан сам кит — не маскируем подсказкой про extras
+        hint = _EXTRA_HINTS.get(target)
+        raise ImportError(
+            f"{name!r} требует модуль {target!r}, но тому не хватает пакета {missing!r}."
+            + (f" Поставь extra: `pip install '{hint}'`." if hint else "")
+        ) from exc
+    value = getattr(module, name)
+    # Кэш в globals(): второй доступ идёт напрямую, мимо хука. Присваивание в dict
+    # атомарно, повторный импорт из другого потока вернёт ТОТ ЖЕ объект из
+    # sys.modules — гонка идемпотентна (важно под free-threading).
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Полная поверхность корня: жадные атрибуты + `__all__` + ленивые имена."""
+    return sorted(set(globals()) | set(__all__) | set(_LAZY_NAMES))
+
+
+__all__ = ["__version__", *sorted(_LAZY_NAMES)]

netkit/contract.py

@@ -0,0 +1,380 @@
+"""Сетевые структурные контракты «талии песочных часов» (кит netkit).
+
+Здесь живут `Protocol`-формы СЕТЕВОГО слоя: чем выполняется запрос (`Transport`/
+`SyncTransport`), как выглядит его результат (`ResponseLike`), чем подмешиваются
+и обновляются credentials (`Auth`/`Refreshable`/`ProactiveRefreshable`), как
+кодируется RPC-кадр (`Codec`), как живёт persistent-канал (`StreamTransport`),
+как ответ превращается в доменную ошибку (`ErrorMapper`) и как листается ресурс
+(`Paginator`).
+
+ОТКУДА ОНИ ПРИЕХАЛИ. Раньше все эти формы лежали в
+`netkit.contract` вперемешку с браузерными (`BrowserBackend`) и складскими
+(`SessionStoreProtocol`). Сеть выделена в отдельный кит — значит и её контракт
+должен жить в ките сети, иначе `netkit` зависел бы от `librarykit` (цикл).
+`netkit.contract` теперь ИМПОРТИРУЕТ эти имена отсюда и реэкспортирует ТЕМИ
+ЖЕ объектами: `from netkit.contract import Transport` даёт ровно тот объект,
+что и `from netkit.contract import Transport` — `isinstance`/`is` не разъезжаются.
+
+Значения и перечисления («талия» без реализации — `TransportKind`, `SessionRef`,
+`LimitSpec`, `ExecutionContext`, …) живут ЭТАЖОМ НИЖЕ, в `corekit`, и
+реэкспортируются здесь, чтобы сетевому слою хватало одного импорта.
+
+ЗАКОН СЛОЁВ: только stdlib, `corekit` и `httpx` (типовая граница HTTP; httpx
+фигурирует ИСКЛЮЧИТЕЛЬНО в аннотациях, см. `TYPE_CHECKING` ниже — рантайм его не
+тянет). Ни `librarykit`, ни `adapterkit`, ни `clikit` отсюда не импортируются
+НИКОГДА: `corekit <- netkit <- ...` — направление зависимостей однонаправленное.
+"""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+# ОСНОВАНИЕ: значения и перечисления «талии». Реэкспортируются ниже через
+# `__all__` — сетевому слою (и его потребителям) хватает одного импорта, а
+# объекты остаются ТЕМИ ЖЕ, что в `corekit` (identity не дублируется).
+from corekit.context import DEFAULT_TENANT, ExecutionContext
+from corekit.dto import Creds, RequestBody, SessionRef
+from corekit.enums import AuthMode, PaginationMode, RequestExecutionMode, TransportKind
+from corekit.limits import LimitSpec, QuotaInfo, QuotaScope
+
+if TYPE_CHECKING:  # pragma: no cover — только для тайпчекера, не в рантайме
+    # httpx фигурирует ИСКЛЮЧИТЕЛЬНО в аннотациях методов (`-> httpx.Response`).
+    # PEP 563 (`from __future__ import annotations`) оставляет их строками,
+    # поэтому рантайму имя не нужно — `import netkit.contract` не стоит 264 мс.
+    import httpx
+
+# =========================================================================== #
+# Транспорт / авторизация / маппинг ошибок                                      #
+# =========================================================================== #
+
+
+@runtime_checkable
+class ResponseLike(Protocol):
+    """Протокол-агностичный результат запроса: status/headers/json/text.
+
+    «Талия» поверх конкретного ответного типа: `httpx.Response` СТРУКТУРНО уже
+    совпадает с этой формой (`status_code: int`, `headers: Mapping`, `json()`,
+    `text: str`), поэтому REST-путь продолжает возвращать `httpx.Response` без
+    оборачивания. Не-HTTP транспорты (RPC поверх не-JSON envelope, будущие WS-
+    ответы) реализуют ту же форму своим лёгким DTO — `BaseAdapter`/потребитель
+    кодится против `ResponseLike`, а не против httpx.
+
+    `json()` возвращает разобранное тело (`Any`); реализация без JSON-семантики
+    вправе поднять ошибку или вернуть сырой payload. `headers` — case-insensitive
+    маппинг (как у httpx), но протокол требует лишь `Mapping[str, str]`.
+    """
+
+    @property
+    def status_code(self) -> int:
+        """Статус-код результата (HTTP-код либо его протокольный эквивалент)."""
+        ...
+
+    @property
+    def headers(self) -> Mapping[str, str]:
+        """Заголовки/метаданные результата (case-insensitive у HTTP-реализаций)."""
+        ...
+
+    @property
+    def text(self) -> str:
+        """Тело результата как текст (для не-JSON envelope и диагностики)."""
+        ...
+
+    def json(self) -> Any:
+        """Разобранное тело результата (обычно JSON); реализация вправе сузить."""
+        ...
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Контракт транспорта: один способ доставить HTTP-запрос и вернуть ответ.
+
+    Реализации (`HttpxTransport`, `CurlCffiTransport`, `BrowserTransport`)
+    инкапсулируют свой движок и retry, но дают единую async-сигнатуру. Per-
+    instance, НИКОГДА не глобальный (урок Stripe v8). Маппинг кодов в ошибки —
+    НЕ здесь (это делает `HttpClient`/`ErrorMapper`); транспорт возвращает сырой
+    `httpx.Response`, бросая `TransportError` только на сетевых сбоях.
+    """
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        content: bytes | str | None = None,
+        headers: Mapping[str, str] | None = None,
+        files: Any | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Выполнить запрос и вернуть HTTP-ответ (без маппинга в доменные ошибки).
+
+        ``content`` — сырое тело (bytes/str) для не-form/не-json envelope (ручной
+        urlencode, protobuf, NDJSON). Взаимоисключимо с ``json``/``data``/``files``
+        (валидирует httpx).
+        """
+        ...
+
+
+@runtime_checkable
+class SyncTransport(Protocol):
+    """Синхронный сиблинг `Transport`: один способ доставить HTTP-запрос (БЕЗ await).
+
+    Та же роль и контракт, что у `Transport` (несёт запрос, retry внутри, маппинг
+    в доменные ошибки — НЕ здесь), но синхронная сигнатура `def request` поверх
+    `httpx.Client`. Нужен навыкам, которые принципиально синхронны (Playwright sync
+    API, sync-CLI без event-loop) — им незачем тянуть asyncio ради одного клиента.
+    Реализация — `HttpxSyncTransport`. Per-instance, НИКОГДА не глобальный.
+    """
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        content: bytes | str | None = None,
+        headers: Mapping[str, str] | None = None,
+        files: Any | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Выполнить запрос и вернуть HTTP-ответ (без маппинга в доменные ошибки).
+
+        ``content`` — сырое тело (bytes/str), как у async-сиблинга ``Transport``.
+        """
+        ...
+
+
+# Первичные ролевые имена «исполнителя HTTP-запроса» (было `Transport`/`SyncTransport`).
+# Это HTTP-executor, а не абстрактный транспорт: тот же Protocol-объект → isinstance и
+# аннотации совпадают; старые имена остаются deprecated-псевдонимами.
+HttpRequestExecutor = Transport
+SyncHttpRequestExecutor = SyncTransport
+
+
+@runtime_checkable
+class SyncRefreshable(Protocol):
+    """Синхронный сиблинг `Refreshable`: обновить протухшие credentials (БЕЗ await).
+
+    `Refreshable.refresh` асинхронна — `SyncHttpClient` не может её await'ить, поэтому
+    для refresh-on-401 в sync-клиенте нужен синхронный вариант. Проверка:
+    ``isinstance(auth, SyncRefreshable)``.
+    """
+
+    def refresh(self) -> bool:
+        """Обновить протухшие credentials. True — успех, False — обновить нельзя."""
+        ...
+
+
+@runtime_checkable
+class SyncProactiveRefreshable(Protocol):
+    """Синхронный сиблинг `ProactiveRefreshable`: проактивный throttled refresh (БЕЗ await).
+
+    Для sync-клиента: choke-point дёргает `maybe_refresh` ПЕРЕД каждым запросом, тот
+    сам решает по TTL/throttle, ротировать ли. Проверка:
+    ``isinstance(auth, SyncProactiveRefreshable)``.
+    """
+
+    def maybe_refresh(self) -> bool:
+        """Обновиться, ЕСЛИ пора по TTL/throttle. True — обновились; False — рано/нельзя."""
+        ...
+
+
+@runtime_checkable
+class StreamTransport(Protocol):
+    """Контракт persistent-транспорта для WS-подобных каналов.
+
+    `Transport.request` — один req→resp; для WebSocket это не годится: соединение
+    живёт долго, кадры идут в обе стороны асинхронно. `StreamTransport` отделяет
+    жизненный цикл (`connect`/`close`) от обмена (`send`/`recv`). Реализации
+    (`StubStreamTransport`, `WebSocketsStreamTransport` под extra `[ws]`)
+    инкапсулируют свой движок; per-instance, НИКОГДА не глобальный.
+
+    `recv` — async-iterator семантика: ``async for frame in transport.recv():``
+    отдаёт входящие кадры (str/bytes) до закрытия канала, после чего итератор
+    исчерпывается (`StopAsyncIteration`). На сетевом сбое реализация поднимает
+    `TransportError`. Маппинг payload в доменные DTO — НЕ здесь (это codec/адаптер).
+    """
+
+    async def connect(
+        self,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        protocols: Sequence[str] | None = None,
+    ) -> None:
+        """Открыть persistent-соединение к `url` (handshake/upgrade)."""
+        ...
+
+    async def send(self, data: str | bytes) -> None:
+        """Отправить один кадр в открытый канал (текст или бинарь)."""
+        ...
+
+    def recv(self) -> AsyncIterator[str | bytes]:
+        """Async-итератор входящих кадров до закрытия канала."""
+        ...
+
+    async def close(self, *, code: int = 1000, reason: str = "") -> None:
+        """Закрыть канал (graceful close-handshake), идемпотентно."""
+        ...
+
+
+@runtime_checkable
+class Codec(Protocol):
+    """Контракт сериализации RPC: payload⇄provod, не обязательно JSON.
+
+    Обобщает `HttpClient.get_json/post_json` (жёстко зашитый `response.json()`)
+    до подключаемого слоя. `encode_request` превращает доменный payload в тело
+    запроса (`json`/`data` для транспорта); `decode_response` разбирает сырой
+    `ResponseLike` обратно в доменный объект. Дефолт — `JsonCodec`; пример иного —
+    NotebookLM `batchexecute` (не-JSON envelope ``)]}'`` + вложенный массив).
+    """
+
+    def encode_request(self, payload: Any) -> RequestBody:
+        """Сериализовать payload в тело запроса для транспорта."""
+        ...
+
+    def decode_response(self, response: ResponseLike) -> Any:
+        """Разобрать сырой ответ в доменный объект (обратная к encode)."""
+        ...
+
+
+@runtime_checkable
+class Auth(Protocol):
+    """Контракт авторизации: подмешивает учётные данные в исходящий запрос.
+
+    `apply` — чистая мутация-обогащение `httpx.Request` (заголовок Authorization,
+    cookies, подпись). `refresh` — опциональный async-метод обновления протухших
+    credentials (OAuth2/cookie-renew); реализации без refresh его просто не
+    объявляют — потребитель проверяет наличие через `runtime` (hasattr) или
+    `isinstance(obj, Refreshable)`.
+    """
+
+    def apply(self, request: httpx.Request) -> httpx.Request:
+        """Обогатить запрос учётными данными и вернуть его (тот же или новый)."""
+        ...
+
+
+@runtime_checkable
+class Refreshable(Protocol):
+    """Опциональная способность `Auth` обновлять credentials (OAuth2/cookie).
+
+    Выделено в отдельный `Protocol`, чтобы базовый `Auth` не навязывал refresh
+    реализациям без него (token-auth). Проверка: ``isinstance(auth, Refreshable)``.
+    """
+
+    async def refresh(self) -> bool:
+        """Обновить протухшие credentials. True — успех, False — обновить нельзя."""
+        ...
+
+
+@runtime_checkable
+class ProactiveRefreshable(Protocol):
+    """Способность `Auth` обновляться ПРОАКТИВНО (до ошибки), throttled.
+
+    Для сессий с ротируемым freshness-токеном (Google ``__Secure-1PSIDTS`` и
+    подобные): токен тихо стухает, если его периодически не «толкать», а
+    реактивного refresh-on-401 не хватает (нужен спец-вызов ротации ДО смерти).
+    `maybe_refresh` дёргается choke-point'ом (`HttpClient`) ПЕРЕД каждым запросом
+    и сам решает по TTL/throttle, делать ли реальную ротацию (дёшево, если рано).
+
+    Отделено от `Refreshable`: `refresh` — реактивная (форс на 401), `maybe_refresh`
+    — проактивная (throttled). Реализация (`librarykit.refresh.RotatingAuth`) обычно
+    умеет обе. Проверка: ``isinstance(auth, ProactiveRefreshable)``.
+    """
+
+    async def maybe_refresh(self) -> bool:
+        """Обновиться, ЕСЛИ пора по TTL/throttle. True — обновились; False — рано/нельзя."""
+        ...
+
+
+@runtime_checkable
+class ApplyRefreshable(Auth, Refreshable, Protocol):
+    """Комбинированный контракт: `Auth.apply` + `Refreshable.refresh` в одном объекте.
+
+    Узкая «талия» для мест, которым нужен объект, УМЕЮЩИЙ И подмешать credentials
+    (`apply`), И обновить их (`refresh`): например `primary` в
+    `refresh.RefreshableChain` (`RotatingAuth`/`OAuth2Auth`/`CsrfHeaderAuth`
+    структурно подходят — у них есть оба метода). Раньше такие места типизировались
+    широким `Auth` + `getattr`-дак-тайпингом по `refresh`; combined-Protocol делает
+    контракт явным и `isinstance`-проверяемым (``isinstance(auth, ApplyRefreshable)``),
+    рантайм-поведение потребителя не меняя.
+    """
+
+
+@runtime_checkable
+class ErrorMapper(Protocol):
+    """Контракт маппинга HTTP-ответа в доменную ошибку (декларативная таблица).
+
+    Реализация (`ErrorMap`) держит правила ``{status | code | body-predicate ->
+    ErrorSubclass}`` и решает, является ли ответ ошибкой. Возвращает экземпляр
+    исключения (для `raise`) либо `None`, если ответ успешен и ошибки нет.
+    """
+
+    def map(self, response: httpx.Response) -> Exception | None:
+        """Вернуть исключение для не-успешного ответа либо `None`, если ОК."""
+        ...
+
+
+# =========================================================================== #
+# Пагинация                                                                     #
+# =========================================================================== #
+
+
+@runtime_checkable
+class Paginator(Protocol):
+    """Контракт листания результата (offset | cursor | page) — обёртка tweepy-стиля.
+
+    Скрывает механику следующей страницы за единым async-итератором сырых страниц.
+    Конкретная реализация выбирается по `PaginationMode` эндпоинта; маппинг
+    страницы в доменные DTO — НЕ здесь (это чистые мапперы адаптера).
+    """
+
+    def paginate(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        mode: PaginationMode = PaginationMode.CURSOR,
+        limit: int | None = None,
+    ) -> AsyncIterator[httpx.Response]:
+        """Итерировать сырые страницы-ответы согласно `mode` до исчерпания/`limit`."""
+        ...
+
+
+__all__ = [
+    # перечисления (реэкспорт corekit)
+    "PaginationMode",
+    "AuthMode",
+    "TransportKind",
+    "RequestExecutionMode",
+    # DTO-значения (реэкспорт corekit)
+    "DEFAULT_TENANT",
+    "SessionRef",
+    "ExecutionContext",
+    "Creds",
+    "RequestBody",
+    "QuotaScope",
+    "QuotaInfo",
+    "LimitSpec",
+    # граничные Protocol сетевого слоя
+    "ResponseLike",
+    "Transport",
+    "SyncTransport",
+    "HttpRequestExecutor",  # первичное ролевое имя (алиас Transport)
+    "SyncHttpRequestExecutor",  # первичное ролевое имя (алиас SyncTransport)
+    "StreamTransport",
+    "Codec",
+    "Auth",
+    "Refreshable",
+    "ProactiveRefreshable",
+    "ApplyRefreshable",
+    "SyncRefreshable",
+    "SyncProactiveRefreshable",
+    "ErrorMapper",
+    "Paginator",
+]