Metadata-Version: 2.4
Name: s-librarykit
Version: 0.1.3
Summary: Жирный КОРЕНЬ китов: единая error-иерархия, config/retry/paths-утили, checkpoint/resume, транспорт/auth/sessions — общий код для clikit, adapterkit и доменных пакетов.
Author: Dmitry
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cryptography>=43
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.0
Requires-Dist: oschmod>=0.3
Requires-Dist: platformdirs>=4.0
Requires-Dist: stamina>=24.3
Requires-Dist: tomli-w>=1.0
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; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: oauth
Requires-Dist: authlib>=1.3; extra == 'oauth'
Provides-Extra: ws
Requires-Dist: websockets>=12.0; extra == 'ws'
Description-Content-Type: text/markdown

# librarykit

**Жирное ядро экосистемы китов** — переиспользуемый фундамент, на котором строятся
тонкие надстройки (`adapterkit`, `clikit`) и любые доменные пакеты. Вся общая логика
живёт здесь один раз, вместо копипасты по проектам: единая иерархия ошибок,
config/paths-утили, политики повторов, HTTP-транспорт, авторизация, шифрованное
хранилище сессий, antibot/браузер, пагинация, RPC/stream и оркестраторы
онбординга/health.

```
librarykit   ← КОРЕНЬ: errors · config · retry · transport · auth · sessions ·
                        errmap · pagination · antibot · browser · rpc · stream ·
                        orchestration.  Зависит НИ ОТ ЧЕГО из китов.
   ▲
clikit       ← CLI-обёртка (поверх librarykit)
   ▲
adapterkit   ← SDK сетевых адаптеров (поверх librarykit + clikit)
   ▲
домен        ← конкретный продукт (поверх всех трёх)
```

Зависимости направлены **только внутрь, к корню**. librarykit не импортирует ни
один другой кит и ничего не знает о потребителях.

## Установка

```bash
uv add s-librarykit
```

Имя дистрибутива — `s-librarykit`, имя для импорта — `librarykit`.

Опциональные extra (тяжёлые зависимости ставятся по требованию):

```bash
uv add "s-librarykit[browser]"   # Playwright — warm/cold-login, snapshot сессий
uv add "s-librarykit[antibot]"   # curl-cffi — JA3-impersonate транспорт
uv add "s-librarykit[ws]"        # websockets — persistent stream-транспорт
```

Ядро (`errors`/`config_util`/`retry`/`checkpoint`/`contract`) почти-stdlib —
единственная не-stdlib зависимость ядра `platformdirs` (нативные пути ОС для
`AppPaths`). Сетевые модули тянут `httpx`/`stamina`, шифрование сессий —
`cryptography`/`keyring`.

## Состав

| Слой | Модуль | Что даёт |
|------|--------|----------|
| Ошибки | `librarykit.errors` | единая иерархия `CliError`/`ApiError` + сетевые подклассы (`AuthRequired`/`RateLimited`/`NotFound`/`ServerError`/`TransportError`/`Blocked`) + множество `RETRYABLE` |
| Конфиг/пути | `librarykit.config_util` | `deep_merge`, `interpolate_env`, `load_dotenv`, `slugify`, `normalize_account_id`, `atomic_write_text`, `chmod_600`, `AppPaths` |
| Контракт | `librarykit.contract` | граничные `Protocol` (`Transport`/`Auth`/`Refreshable`/`ErrorMapper`/`Paginator`/`SessionStoreProtocol`/`StreamTransport`/`Codec`) + DTO/enum (`SessionRef`/`Creds`/`PaginationMode`/`AuthMode`/`TransportKind`) |
| Протоколы | `librarykit.protocols` | опциональные онбординг/health-контракты (`LoginMode`/`OnboardingProtocol`/`HealthProtocol`/`HealthState`/`InteractiveFlow`) |
| Повторы | `librarykit.retry` | `RetryPolicy` (header-driven: `Retry-After`/rate-limit) поверх `stamina` + `SimpleRetryPolicy` |
| Транспорт | `librarykit.transport` | `HttpxTransport` + `HttpClient` — единый choke-point HTTP-вызовов |
| Ошибки→исключения | `librarykit.errmap` | декларативная карта `{status\|code\|body-predicate → ErrorSubclass}` (`build_error_map`) |
| Пагинация | `librarykit.pagination` | `CursorPaginator` (offset/cursor/page) + tweepy-стиль обёртки |
| Авторизация | `librarykit.auth` | `TokenAuth`/`CookieSessionAuth`/`OAuth2Auth`/`BrowserLoginAuth` + dump/load/encrypt настроек |
| Сессии | `librarykit.sessions` | `SessionStore` — envelope-шифрованное файловое хранилище сессий (DEK под KEK), `resolve_kek` |
| Секреты | `librarykit.secret_store` | `SecretStore` — keyring + file-fallback |
| Antibot | `librarykit.antibot` | выбор транспорта Tier 0-4 (curl-cffi JA3 / реальный браузер по CDP) |
| Браузер | `librarykit.browser` | warm/cold-login, snapshot/restore storage-state |
| RPC | `librarykit.rpc` | `RpcClient` + codec-слой (`JsonCodec`/`PrefixedJsonCodec`) поверх `HttpClient` |
| Stream | `librarykit.stream` | persistent-транспорты (`StubStreamTransport` + `WebSocketsStreamTransport`) |
| Checkpoint | `librarykit.checkpoint` | `Checkpoint` (атомарный JSON-state), `JsonlSink` (forensic-лог), `RunMetrics` |
| Сущности | `librarykit.entities` | нейтральные data-классы (`Session`/`SessionContext`/`HealthReport`) |
| Оркестрация | `librarykit.orchestration` | `OnboardingService`, `HealthMonitor`, `SessionLoader` — переиспользуемые сценарии онбординга/health |

Топ-уровневый `import librarykit` ре-экспортирует публичный API (см. `librarykit.__all__`).

## Быстрый старт

```python
import librarykit as lk

# единая иерархия ошибок
try:
    ...
except lk.RateLimited as e:
    ...

# header-driven повторы + choke-point HTTP-клиент
client = lk.HttpClient(base_url="https://api.example.com", retry=lk.DEFAULT_RETRY)

# декларативная карта ответ → доменная ошибка
err_map = lk.build_error_map()

# envelope-шифрованное хранилище сессий
store = lk.SessionStore(root=..., kek=lk.resolve_kek())
```

## Разработка

```bash
uv sync --extra dev
uv run --extra dev pytest -q
uv run --extra dev ruff check librarykit
```

## Лицензия

MIT © 2026 Dmitry.
