s-adapterkit 0.1.1__tar.gz

s_adapterkit-0.1.1/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# venv / tooling
+.venv/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# uv
+uv.lock
+
+# OS
+.DS_Store
+Thumbs.db

s_adapterkit-0.1.1/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md — adapterkit
+
+> Контекст для AI-ассистентов (Claude Code, ChatGPT, Cursor и т.п.), работающих
+> над этим проектом.
+
+## Что это
+
+Переиспользуемый SDK сетевых адаптеров: transport/auth/retry/errmap/pagination/sessions/browser/antibot, контракт плагинов; цель — onboarding+health как публичный API
+
+## Atlas
+
+Проект зарегистрирован в Atlas-БД (NP-005). Карточка:
+
+```sh
+atlas projects get adapterkit
+```
+
+Любые изменения метаданных (приоритет, статус, теги) — через atlas CLI:
+
+- `atlas projects update adapterkit --priority P0` — поменять приоритет
+- `atlas add-tags adapterkit -t domain:<slug>` — добавить тег
+- `atlas projects move adapterkit --to-type <type>` — конвертировать тип
+
+## Тип / Статус (на момент создания)
+
+- type=`shared-infrastructure`, status=`experiment`, priority=`P0`
+
+## Правила работы
+
+- Все исходные тексты, документы, код проекта — в этом репо.
+- Чувствительные данные (`.env`, токены, ключи) — игнорируются `.gitignore`.
+- AI-ассистенту разрешено: читать, генерировать, редактировать в этом репо.
+
+## Канонические команды
+
+- `atlas projects get adapterkit` — карточка проекта
+- `atlas pm-tasks list --project adapterkit` — задачи проекта (когда W7
+  волна будет реализована)

s_adapterkit-0.1.1/BACKLOG-nlm-migration.md

@@ -0,0 +1,155 @@
+# BACKLOG — миграция NotebookLM на clikit + adapterkit (мультипротокол)
+
+> SSOT для реализующей сессии. Эпики/задачи зеркалируются в Atlas
+> (`atlas epic list --project adapterkit`, `atlas task list --project adapterkit`).
+> Этот файл — глубина (файл:строка, подходы, решения), Atlas — трекинг.
+>
+> Источник: brainstorming-сессия 2026-06-22 (после фикса авто-refresh сессии
+> notebooklm, ветка `fix/notebooklm-auto-headless-refresh` в репо notebooklm).
+
+## Цель
+
+Сделать `nlm-tools` (обёртка над `notebooklm-py`) переиспользуемым
+**adapterkit-адаптером**, подключаемым к другим проектам через
+`AdapterRegistry`/entry-points, с единым `nlm` CLI на clikit. Попутно —
+**расширить сам adapterkit до мультипротокольности** (REST/RPC/WS/др.), чтобы
+NotebookLM-RPC и будущие WS-сервисы (MAX/Telegram) были first-class.
+
+## Решения пользователя (зафиксированы в brainstorming)
+
+1. **Форма адаптера** — НЕ duck-typed обход, а **расширить `BaseAdapter`/транспорт
+   adapterkit под мультипротокол** (REST/RPC/WS и др.) как first-class.
+2. **Канал подключения** — universal adapterkit entry-point (`adapterkit.adapters`),
+   переиспользуем в любом проекте; bublictr-мост — отложен (только если NLM реально
+   понадобится в кросспосте, потребует PR в bublictr core: `NetworkId.NOTEBOOKLM` + SP-3).
+3. **SessionStore** — интегрировать **сразу** (envelope-шифрование + единое
+   мультиаккаунт-хранилище), несмотря на конфликт владения файлом.
+4. **CLI Фаза 1** — готовые сценарии (sources/youtube/ask/transcripts/session) **+**
+   notebooks CRUD.
+
+## Ключевые факты из разбора кода (на чём строится дизайн)
+
+- **adapterkit НЕ обязан владеть транспортом.** `BaseAdapter` зависит от
+  структурного `HttpClientLike` Protocol (`adapterkit/base.py:44-80,110-117`),
+  `_request` переопределяем (escape-hatch, base.py:18-22,103-104). Реестр —
+  структурный `NetworkAdapter` Protocol (`adapterkit/contract.py:284-338`),
+  наследование НЕ требуется. ENTRY_POINT_GROUP = `adapterkit.adapters`
+  (`adapterkit/registry.py:41`), ленивый `ep.load()` + ручной `register_adapter`
+  (registry.py:71-82,155-165).
+- **`notebooklm-py` НАТИВНО async** (`.../notebooklm/client.py:74` "Async client",
+  свой httpx + RPC + пулы client.py:118-120). `await client.notebooks.list()`,
+  `async __aenter__/__aexit__` (455/472), `async refresh_auth()` (827),
+  `from_storage(path,profile,keepalive)` (719-733). → **`asyncio.to_thread` НЕ нужен**
+  (в отличие от RuTube, который оборачивает SYNC-клиент).
+- **`notebooklm-py` сам владеет профилем/сессией:** `from_storage(profile=...)`,
+  путь `$NOTEBOOKLM_HOME/storage_state.json` или `~/.notebooklm`
+  (`_auth/cookies.py:266,326`); account-метаданные ВНУТРИ storage_state.json под
+  ключом `notebooklm` (`_auth/account.py:204,224,269`). Есть seam'ы
+  `cookie_saver`/`cookie_rotator` (client.py:332-333) — точка перехвата записи.
+- **Эталон оборачивания чужого клиента** — `RuTubeAdapter` в bublictr: duck-typed,
+  клиент внутри, adapterkit HttpClient только для fallback-пинга
+  (`bublictr/.../rutube/__init__.py:167-177,553-557`).
+- **Конфликт SessionStore ↔ notebooklm-py:** `SessionStore` шифрует (envelope,
+  `BUBLICTR_*` KEK), а notebooklm-py сам перезаписывает plaintext
+  `storage_state.json` в keepalive/rotate (`_auth/keepalive.py`). Два владельца
+  файла — нужно примирить через seam (см. E2).
+- **clikit:** `build_root_app(brand=...)`, async-команды, `emit_data` json-дефолт,
+  `NlmConfig(AppConfig)`. **НЕ** использовать `clikit.transport.HttpClient`
+  (`clikit/transport.py:128` ждёт `httpx.AsyncClient`, а `NotebookLMClient` им не
+  является) и **НЕ** `clikit.SecretStore` (сессия — browser storage_state, не JWT).
+
+## Эпики и задачи
+
+### EPIC E1 — Мультипротокольный транспорт adapterkit (RPC/WS first-class)
+**Цель:** транспорт-слой adapterkit перестаёт быть только httpx-REST; RPC и WS —
+first-class, чтобы NotebookLM-RPC и будущие WS-сервисы строились на нём.
+Текущее: `Transport` Protocol + `HttpxTransport` (request→`httpx.Response`,
+transport.py), curl-cffi/CDP (antibot.py).
+
+- **E1.T1 — Stream/протокол-абстракция для WS.** `Transport.request` (один
+  req→resp) не годится для WS (persistent send/recv). Ввести `StreamTransport`
+  Protocol (connect/send/recv/close) рядом с `Transport`. Файлы: `contract.py`
+  (Transport), новый stream-контракт.
+- **E1.T2 — Codec-слой для RPC.** Обобщить `HttpClient.get_json/post_json`
+  (client.py:40) до pluggable codec (request/response сериализация ≠ JSON; пример —
+  NotebookLM `batchexecute`). Endpoint получает codec.
+- **E1.T3 — Протокол-агностичный результат BaseAdapter.** Сейчас
+  `HttpClientLike.request` обязан вернуть `httpx.Response` (base.py:45). Ввести
+  абстрактный результат или параллельные choke-points (`RpcClient`/`WsClient`)
+  так, чтобы `BaseAdapter` не был привязан к httpx.
+- **E1.T4 — Conformance/contract-тесты** для новых транспортов (`testing/contract.py`).
+- **E1.T5 (опц) — WS reference-транспорт** (websockets/httpx-ws) под `StreamTransport` —
+  задел под MAX/Telegram. YAGNI-проверить: делать только если WS-сервис на горизонте.
+
+### EPIC E2 — SessionStore ↔ внешний клиент (owner reconciliation)
+**Цель:** SessionStore хранит/шифрует сессии мультиаккаунт, НЕ конфликтуя с тем,
+что notebooklm-py сам пишет storage_state.json.
+
+- **E2.T1 — Перехват записи через seam.** Использовать `cookie_saver`/`cookie_rotator`
+  (notebooklm `client.py:332-333`), чтобы момент сохранения сессии шёл через
+  SessionStore (вариант C2: шифровать после записи; расшифровывать во временный
+  path перед open). Альтернатива C1 (SessionStore как индекс путей, plaintext) —
+  фиксировать как fallback.
+- **E2.T2 — Нейтральный KEK-namespace.** Вынести env KEK из `BUBLICTR_*` в
+  `ADAPTERKIT_*`/конфиг (`adapterkit/sessions.py`), чтобы адаптер не тянул
+  bublictr-namespace.
+- **E2.T3 — Маппинг (profile/social/account_id) ↔ profile notebooklm-py.**
+  account_id схлопывается в profile (один профиль = один аккаунт, метаданные
+  внутри storage_state, `_auth/account.py:204`).
+- **E2.T4 — Тесты** SessionStore с внешним владельцем файла (keepalive/rotate).
+
+### EPIC E3 — NlmAdapter (первый RPC-адаптер на новом фундаменте)
+**Цель:** подключаемый адаптер NotebookLM в namespace adapterkit.
+
+- **E3.T1 — NlmAdapter под `NetworkAdapter` Protocol** (contract.py:284):
+  `api_version=1` (class-attr int, НЕ property), `service='notebooklm'`,
+  `capabilities`, `health_check`, `__aenter__/__aexit__`. Внутри — `open_client`→
+  `NotebookLMClient` как transport-слой.
+- **E3.T2 — Порты content** (notebooks/sources/ask/transcripts) делегируют в async
+  sub-clients напрямую (БЕЗ `to_thread`). Перенести lib `nlm_tools/{notebooks,
+  sources,ask,transcripts}.py`.
+- **E3.T3 — entry-point** в pyproject: `[project.entry-points."adapterkit.adapters"]
+  notebooklm = "nlm_tools.adapter:NlmAdapter"`.
+- **E3.T4 — AdapterContractTests** с переопределённым `make_adapter`
+  (`adapterkit/testing/contract.py:263-285` — дефолт `cls(StubHttpClient())` не
+  сработает).
+- **E3.T5 — Перенести session-слой** (session_refresh/nlm_refresh/nlm_keepalive из
+  репо notebooklm) внутрь адаптера; `map_error` → adapterkit errmap/доменные ошибки.
+- **E3.T6 — Target-гранулярность.** Решить единицу: один аккаунт NLM (OWN_PROFILE)
+  vs каждый notebook = Target. Для standalone хватит одного; для bublictr-кросспоста
+  Target обязателен.
+
+### EPIC E4 — clikit `nlm` CLI (сценарии + CRUD + session)
+**Цель:** единый `nlm` CLI вместо разрозненных `scripts/nlm_*.py`, с профилями и
+единым sh-xray egress (закрывает остаточный момент egress-рассинхрона из фикса).
+
+- **E4.T1 — Каркас:** `build_root_app(brand='nlm')`, `NlmConfig(AppConfig)`,
+  `--json` дефолт (`emit_data`). Без `clikit.transport.HttpClient`/`SecretStore`.
+- **E4.T2 — notebooks CRUD** (create/list/delete/use) — lib `notebooks.py` готов,
+  команд-скриптов не было.
+- **E4.T3 — source/ask/transcripts/generate** — перенести `scripts/nlm_add_sources,
+  nlm_add_youtube, nlm_ask_series, nlm_export_transcripts` в подкоманды.
+- **E4.T4 — session-подкоманды** (login/refresh/keepalive/check) поверх
+  session-слоя; профиль `--profile/-P` → `NLM_PROFILE` → `open_client(profile=...)`.
+- **E4.T5 — keepalive entrypoint** для Task Scheduler: решить — отдельный тонкий
+  entrypoint (без typer-overhead) vs `nlm session keepalive`. Логика
+  `session_refresh.py` переезжает без изменений.
+
+## Порядок / зависимости
+
+```
+E1 (мультипротокол) ─┐
+E2 (SessionStore)   ─┴─► E3 (NlmAdapter) ─► E4 (clikit nlm CLI)
+```
+
+E1 и E2 можно вести параллельно. E3 зависит от E1+E2. E4 зависит от E3.
+Минимальный путь к рабочему `nlm` без полного E1: можно начать E3 в духе
+duck-typed (RuTube-паттерн) и наполнять мультипротокол E1 итеративно — но
+пользователь выбрал first-class мультипротокол, поэтому E1 — фундамент.
+
+## Что уже готово (фикс сессии, репо notebooklm)
+
+Ветка `fix/notebooklm-auto-headless-refresh` (commit ef01ae2): `session_refresh.py`
+(чистая логика, 25 тестов), `nlm_refresh.py` (headless re-login patchright→cdp),
+`nlm_keepalive.py` (poke+heal), `open_client` (боевая ~/.notebooklm + REFRESH_CMD).
+Этот session-слой переезжает в адаптер (E3.T5) и CLI (E4.T4) почти без изменений.

s_adapterkit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

s_adapterkit-0.1.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: s-adapterkit
+Version: 0.1.1
+Summary: Переиспользуемый SDK сетевых адаптеров: Transport/Auth/RetryPolicy/HttpClient, ErrorMap, пагинация, браузер/антибот-транспорты, SessionStore, BaseAdapter + контракт плагинов. Тонкий коннектор поверх librarykit.
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: s-clikit
+Requires-Dist: s-librarykit
+Provides-Extra: antibot
+Requires-Dist: curl-cffi>=0.7; extra == 'antibot'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: oauth
+Requires-Dist: authlib>=1.3; extra == 'oauth'
+Description-Content-Type: text/markdown
+
+# adapterkit
+
+Переиспользуемый **SDK сетевых адаптеров** для соцсетей и любых REST/гибридных
+сервисов. Пишется один раз, потребляется всеми адаптерами `bublictr` и
+`reverse-factory` — чтобы HTTP/retry/auth/session/antibot не переписывались под
+каждую сеть заново.
+
+adapterkit **строится поверх `clikit`** и переиспользует его примитивы
+(`CliError`-иерархию, `RetryPolicy`, `AppPaths`, `SecretStore`, transport-разбор
+ошибок), не дублируя их.
+
+## Слои
+
+```
+clikit            CLI-методика + примитивы (errors, retry, paths, SecretStore, transport)
+   ▲ depends-on
+adapterkit        сетевой SDK: Transport/Auth/HttpClient/ErrorMap/Pagination/SessionStore/BaseAdapter/contract
+   ▲ depends-on
+bublictr / reverse-factory   домен/фабрика: endpoint-table + чистые мапперы + capabilities на сеть
+```
+
+Принцип зависимостей — **только внутрь**. Адаптеры кодируются против стабильных
+`typing.Protocol` из `adapterkit.contract` (структурный контракт, не наследование
+от домена). Композиция конкретных реализаций — единственный composition root на
+приложение.
+
+## Карта модулей
+
+| Модуль | Назначение | Статус |
+|--------|-----------|--------|
+| `errors.py` | `AdapterError` + `TransportError/NotFound/Blocked/ServerError` поверх `clikit.errors`; `RETRYABLE` | ✅ spine |
+| `contract.py` | граничные `Protocol` (`Transport/Auth/ErrorMapper/Paginator/SessionStoreProtocol/NetworkAdapter`) + DTO (`Endpoint/PaginationMode/SessionRef/Creds`) + `ADAPTER_API_VERSION` | ✅ spine |
+| `retry.py` | `RetryPolicy` (header-driven: `Retry-After` / rate-limit) поверх `stamina`; `DEFAULT_RETRY` | ✅ spine |
+| `transport.py` | `HttpxTransport(Transport)` — обёртка `httpx.AsyncClient` + `RetryPolicy`, per-instance | ✅ spine |
+| `auth.py` | `TokenAuth / OAuth2Auth / CookieSessionAuth / BrowserLoginAuth` | ⏳ позже |
+| `client.py` | `HttpClient` — единственный choke-point (owns Transport+Auth+RetryPolicy) | ⏳ позже |
+| `errmap.py` | декларативная таблица `{status\|code\|body-predicate -> ErrorSubclass}` | ⏳ позже |
+| `pagination.py` | `paginate(...)` обёртка: offset \| cursor \| page | ⏳ позже |
+| `browser.py` | warm/cold-login, self-heal (transport CDP/Playwright) | ⏳ позже |
+| `antibot.py` | Tier 0-4: выбор транспорта (curl-cffi JA3, real Edge CDP) | ⏳ позже |
+| `sessions.py` | `SessionStore` — единое файловое хранилище сессий + индекс | ⏳ позже |
+| `base.py` | `BaseAdapter` + `Resource` sub-services (Stripe-фасад) | ⏳ позже |
+| `registry.py` | discovery через entry-points `adapterkit.adapters`, ленивая загрузка | ⏳ позже |
+| `testing/contract.py` | параметризованный conformance-сьют | ⏳ позже |
+
+Текущая ревизия — **фундамент (scaffold + spine)**: `errors`, `contract`,
+`retry`, `transport`. Остальные модули реализуются в фазах интеграции; их
+интерфейсы уже зафиксированы как `Protocol` в `contract.py`.
+
+## Установка (dev)
+
+```bash
+uv sync --extra dev
+```
+
+`clikit` подтягивается как editable path-зависимость (`../clikit`).

s_adapterkit-0.1.1/README.md

@@ -0,0 +1,56 @@
+# adapterkit
+
+Переиспользуемый **SDK сетевых адаптеров** для соцсетей и любых REST/гибридных
+сервисов. Пишется один раз, потребляется всеми адаптерами `bublictr` и
+`reverse-factory` — чтобы HTTP/retry/auth/session/antibot не переписывались под
+каждую сеть заново.
+
+adapterkit **строится поверх `clikit`** и переиспользует его примитивы
+(`CliError`-иерархию, `RetryPolicy`, `AppPaths`, `SecretStore`, transport-разбор
+ошибок), не дублируя их.
+
+## Слои
+
+```
+clikit            CLI-методика + примитивы (errors, retry, paths, SecretStore, transport)
+   ▲ depends-on
+adapterkit        сетевой SDK: Transport/Auth/HttpClient/ErrorMap/Pagination/SessionStore/BaseAdapter/contract
+   ▲ depends-on
+bublictr / reverse-factory   домен/фабрика: endpoint-table + чистые мапперы + capabilities на сеть
+```
+
+Принцип зависимостей — **только внутрь**. Адаптеры кодируются против стабильных
+`typing.Protocol` из `adapterkit.contract` (структурный контракт, не наследование
+от домена). Композиция конкретных реализаций — единственный composition root на
+приложение.
+
+## Карта модулей
+
+| Модуль | Назначение | Статус |
+|--------|-----------|--------|
+| `errors.py` | `AdapterError` + `TransportError/NotFound/Blocked/ServerError` поверх `clikit.errors`; `RETRYABLE` | ✅ spine |
+| `contract.py` | граничные `Protocol` (`Transport/Auth/ErrorMapper/Paginator/SessionStoreProtocol/NetworkAdapter`) + DTO (`Endpoint/PaginationMode/SessionRef/Creds`) + `ADAPTER_API_VERSION` | ✅ spine |
+| `retry.py` | `RetryPolicy` (header-driven: `Retry-After` / rate-limit) поверх `stamina`; `DEFAULT_RETRY` | ✅ spine |
+| `transport.py` | `HttpxTransport(Transport)` — обёртка `httpx.AsyncClient` + `RetryPolicy`, per-instance | ✅ spine |
+| `auth.py` | `TokenAuth / OAuth2Auth / CookieSessionAuth / BrowserLoginAuth` | ⏳ позже |
+| `client.py` | `HttpClient` — единственный choke-point (owns Transport+Auth+RetryPolicy) | ⏳ позже |
+| `errmap.py` | декларативная таблица `{status\|code\|body-predicate -> ErrorSubclass}` | ⏳ позже |
+| `pagination.py` | `paginate(...)` обёртка: offset \| cursor \| page | ⏳ позже |
+| `browser.py` | warm/cold-login, self-heal (transport CDP/Playwright) | ⏳ позже |
+| `antibot.py` | Tier 0-4: выбор транспорта (curl-cffi JA3, real Edge CDP) | ⏳ позже |
+| `sessions.py` | `SessionStore` — единое файловое хранилище сессий + индекс | ⏳ позже |
+| `base.py` | `BaseAdapter` + `Resource` sub-services (Stripe-фасад) | ⏳ позже |
+| `registry.py` | discovery через entry-points `adapterkit.adapters`, ленивая загрузка | ⏳ позже |
+| `testing/contract.py` | параметризованный conformance-сьют | ⏳ позже |
+
+Текущая ревизия — **фундамент (scaffold + spine)**: `errors`, `contract`,
+`retry`, `transport`. Остальные модули реализуются в фазах интеграции; их
+интерфейсы уже зафиксированы как `Protocol` в `contract.py`.
+
+## Установка (dev)
+
+```bash
+uv sync --extra dev
+```
+
+`clikit` подтягивается как editable path-зависимость (`../clikit`).

s_adapterkit-0.1.1/adapterkit/__init__.py

@@ -0,0 +1,293 @@
+"""adapterkit — переиспользуемый SDK сетевых адаптеров (поверх clikit).
+
+Сетевой слой, который пишется один раз и потребляется всеми адаптерами
+`bublictr` и `reverse-factory`: транспорт + retry + auth + session + antibot,
+декларативный контракт плагинов (`typing.Protocol` + `ADAPTER_API_VERSION`) и
+базовый фасад адаптера. adapterkit зависит ТОЛЬКО от `clikit` (и стандартных
+сетевых библиотек) — без импортов домена, чтобы reverse-factory брал тот же SDK.
+
+Публичный API сгруппирован по слоям (как в `clikit.__init__`): ошибки → контракт
+→ retry → transport → client → auth → errmap → pagination → sessions → base →
+registry → antibot. Браузерный слой (`adapterkit.browser`) тащит опциональный
+Playwright и здесь НЕ ре-экспортируется на верхний уровень — импортируется явно
+из подмодуля (``from adapterkit.browser import maximized_chromium``), чтобы
+верхнеуровневый импорт пакета не зависел от extra `browser`.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.1"
+
+# Импорты сгруппированы по слоям, но отсортированы по алфавиту (isort/ruff):
+# заголовки-комментарии ниже маркируют слой каждого подмодуля, а __all__ в конце
+# держит исходную смысловую группировку (ошибки → контракт → транспорт → ...).
+
+# --------------------------------------------------------------------------- #
+# antibot — выбор транспорта (curl-cffi JA3 / реальный браузер по CDP)          #
+# --------------------------------------------------------------------------- #
+from adapterkit.antibot import (
+    CdpBrowserBackend,
+    CdpTransport,
+    CurlCffiTransport,
+    pick_chrome_impersonate,
+)
+
+# --------------------------------------------------------------------------- #
+# auth — стратегии авторизации + персистентность сессии                        #
+# --------------------------------------------------------------------------- #
+from adapterkit.auth import (
+    BrowserLoginAuth,
+    CookieSessionAuth,
+    OAuth2Auth,
+    TokenAuth,
+    decrypt_settings,
+    dump_settings,
+    encrypt_settings,
+    load_settings,
+)
+
+# --------------------------------------------------------------------------- #
+# base — базовый адаптер + ресурс-под-сервисы (Stripe-фасад)                    #
+# --------------------------------------------------------------------------- #
+from adapterkit.base import (
+    BaseAdapter,
+    CommentsResource,
+    ContentResource,
+    HttpClientLike,
+    MetricsResource,
+    Resource,
+    SearchResource,
+)
+
+# --------------------------------------------------------------------------- #
+# client — единый choke-point HTTP-вызовов                                     #
+# --------------------------------------------------------------------------- #
+from adapterkit.client import HttpClient
+
+# --------------------------------------------------------------------------- #
+# contract — Protocol-«талия» + версии контракта + DTO/enum                    #
+# --------------------------------------------------------------------------- #
+from adapterkit.contract import (
+    ADAPTER_API_VERSION,
+    MIN_SUPPORTED_API_VERSION,
+    Auth,
+    AuthMode,
+    Creds,
+    Endpoint,
+    ErrorMapper,
+    NetworkAdapter,
+    PaginationMode,
+    Paginator,
+    Refreshable,
+    SessionRef,
+    SessionStoreProtocol,
+    Transport,
+    TransportKind,
+)
+
+# --------------------------------------------------------------------------- #
+# errmap — декларативный маппинг ответа в доменную ошибку                       #
+# --------------------------------------------------------------------------- #
+from adapterkit.errmap import (
+    DEFAULT_ERROR_MAP,
+    AuthExpired,
+    BodyRule,
+    ErrorMap,
+    ErrorMapBuilder,
+    ExcFactory,
+    build_error_map,
+)
+
+# --------------------------------------------------------------------------- #
+# errors — единая иерархия (реэкспорт clikit + сетевые подклассы)              #
+# --------------------------------------------------------------------------- #
+from adapterkit.errors import (
+    RETRYABLE,
+    AdapterError,
+    AuthRequired,
+    Blocked,
+    CliError,
+    NotFound,
+    RateLimited,
+    ServerError,
+    SessionExpired,
+    TransportError,
+    ValidationError,
+)
+
+# --------------------------------------------------------------------------- #
+# onboarding_contract — опциональные онбординг/health-контракты (api_version 2) #
+# --------------------------------------------------------------------------- #
+from adapterkit.onboarding_contract import (
+    HealthProtocol,
+    HealthState,
+    HealthStatus,
+    InteractiveFlow,
+    LoginMode,
+    LoginRequirements,
+    OnboardingProtocol,
+)
+
+# --------------------------------------------------------------------------- #
+# orchestration_api — тонкий registry-driven API онбординга/health (W5)         #
+# --------------------------------------------------------------------------- #
+from adapterkit.orchestration_api import (
+    OnboardReport,
+    OnboardResult,
+    health_check_all,
+    onboard_all,
+)
+
+# --------------------------------------------------------------------------- #
+# pagination — три стратегии листания + tweepy-обёртки                          #
+# --------------------------------------------------------------------------- #
+from adapterkit.pagination import (
+    DEFAULT_PAGE_PARAMS,
+    CursorExtractor,
+    CursorPaginator,
+    ItemsExtractor,
+    PageParams,
+    default_extract_cursor,
+    default_extract_items,
+    with_page_params,
+)
+
+# --------------------------------------------------------------------------- #
+# registry — discovery плагинов + ручная регистрация                           #
+# --------------------------------------------------------------------------- #
+from adapterkit.registry import (
+    ENTRY_POINT_GROUP,
+    AdapterClass,
+    AdapterRegistry,
+    default_registry,
+    discover_adapters,
+    get_adapter_class,
+    get_health_adapters,
+    get_onboarding_adapters,
+    register_adapter,
+)
+
+# --------------------------------------------------------------------------- #
+# retry — header-driven политика повторов                                      #
+# --------------------------------------------------------------------------- #
+from adapterkit.retry import DEFAULT_RETRY, RetryPolicy
+
+# --------------------------------------------------------------------------- #
+# sessions — единое хранилище сессий (каталог + SQLite-индекс)                  #
+# --------------------------------------------------------------------------- #
+from adapterkit.sessions import (
+    KekUnavailableError,
+    SessionStore,
+    SessionStoreError,
+    resolve_kek,
+)
+
+# --------------------------------------------------------------------------- #
+# transport — конкретный httpx-транспорт                                       #
+# --------------------------------------------------------------------------- #
+from adapterkit.transport import HttpxTransport
+
+__all__ = [
+    "__version__",
+    # errors (единая иерархия поверх clikit)
+    "CliError",
+    "AuthRequired",
+    "SessionExpired",
+    "RateLimited",
+    "ValidationError",
+    "AdapterError",
+    "TransportError",
+    "NotFound",
+    "Blocked",
+    "ServerError",
+    "RETRYABLE",
+    # contract: версии + Protocol-«талия» + DTO/enum
+    "ADAPTER_API_VERSION",
+    "MIN_SUPPORTED_API_VERSION",
+    "Transport",
+    "Auth",
+    "Refreshable",
+    "ErrorMapper",
+    "Paginator",
+    "SessionStoreProtocol",
+    "NetworkAdapter",
+    "Endpoint",
+    "SessionRef",
+    "Creds",
+    "PaginationMode",
+    "AuthMode",
+    "TransportKind",
+    # onboarding/health контракты (api_version 2, опциональные)
+    "LoginMode",
+    "LoginRequirements",
+    "InteractiveFlow",
+    "OnboardingProtocol",
+    "HealthState",
+    "HealthStatus",
+    "HealthProtocol",
+    # retry
+    "RetryPolicy",
+    "DEFAULT_RETRY",
+    # transport
+    "HttpxTransport",
+    # client (choke-point)
+    "HttpClient",
+    # auth: стратегии + персистентность сессии
+    "TokenAuth",
+    "CookieSessionAuth",
+    "OAuth2Auth",
+    "BrowserLoginAuth",
+    "dump_settings",
+    "load_settings",
+    "encrypt_settings",
+    "decrypt_settings",
+    # errmap
+    "ErrorMap",
+    "ErrorMapBuilder",
+    "BodyRule",
+    "ExcFactory",
+    "AuthExpired",
+    "build_error_map",
+    "DEFAULT_ERROR_MAP",
+    # pagination
+    "CursorPaginator",
+    "PageParams",
+    "DEFAULT_PAGE_PARAMS",
+    "ItemsExtractor",
+    "CursorExtractor",
+    "default_extract_items",
+    "default_extract_cursor",
+    "with_page_params",
+    # sessions
+    "SessionStore",
+    "SessionStoreError",
+    "KekUnavailableError",
+    "resolve_kek",
+    # base (адаптер + ресурсы)
+    "BaseAdapter",
+    "Resource",
+    "ContentResource",
+    "CommentsResource",
+    "MetricsResource",
+    "SearchResource",
+    "HttpClientLike",
+    # registry
+    "AdapterRegistry",
+    "AdapterClass",
+    "ENTRY_POINT_GROUP",
+    "default_registry",
+    "register_adapter",
+    "get_adapter_class",
+    "discover_adapters",
+    "get_onboarding_adapters",
+    "get_health_adapters",
+    # orchestration_api (тонкий registry-driven онбординг/health поверх librarykit)
+    "onboard_all",
+    "health_check_all",
+    "OnboardResult",
+    "OnboardReport",
+    # antibot (выбор транспорта)
+    "CurlCffiTransport",
+    "CdpTransport",
+    "CdpBrowserBackend",
+    "pick_chrome_impersonate",
+]