s-clientkit 0.0.1__tar.gz

s_clientkit-0.0.1/.gitignore

@@ -0,0 +1,47 @@
+# === atlas universal gitignore ===
+
+# OS / IDE
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Sensitive
+.env
+.env.local
+*.key
+*.pem
+secrets/
+private/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+
+# Node / JS
+node_modules/
+.next/
+dist/
+build/
+
+# Temporary / large
+*.log
+*.tmp
+nul
+NUL
+*.zip
+*.rar
+*.7z
+
+# Media (selectively unignore via !path/*.ext if needed for fixtures)
+*.mp4
+*.mov
+*.avi
+*.mkv

s_clientkit-0.0.1/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md — clientkit
+
+> Контекст для AI-ассистентов (Claude Code, ChatGPT, Cursor и т.п.), работающих
+> над этим проектом.
+
+## Что это
+
+(заполнить one-line)
+
+## Atlas
+
+Проект зарегистрирован в Atlas-БД (Atlas). Карточка:
+
+```sh
+atlas project get clientkit
+```
+
+Любые изменения метаданных (приоритет, статус, теги) — через atlas CLI:
+
+- `atlas project update clientkit --priority P0` — поменять приоритет
+- `atlas project tag add clientkit -t domain:<slug>` — добавить тег
+- `atlas project move clientkit --to-type <type>` — конвертировать тип
+
+## Тип / Статус (на момент создания)
+
+- type=`kit`, status=`active`, priority=`P2`
+
+## Правила работы
+
+- Все исходные тексты, документы, код проекта — в этом репо.
+- Чувствительные данные (`.env`, токены, ключи) — игнорируются `.gitignore`.
+- AI-ассистенту разрешено: читать, генерировать, редактировать в этом репо.
+
+## Канонические команды
+
+- `atlas project get clientkit` — карточка проекта
+- `atlas task list --project clientkit` — задачи проекта (когда W7
+  волна будет реализована)
+
+<!-- atlas:usage:start -->
+## Управление проектом — через Atlas
+
+Этот проект ведётся в Atlas (личная PM-система портфеля). Для задач/проектов/эпиков/бэкапов
+используй CLI `atlas` и вызывай навык `atlas` — вся логика и роутинг внутри навыка.
+<!-- atlas:usage:end -->

s_clientkit-0.0.1/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog — s-clientkit
+
+## 0.0.1 — кит-сборщик (задача #1423)
+
+Первый выпуск.
+
+- `clientkit.declaration` — декларация сервиса как ДАННЫЕ (`ServiceDecl` и
+  соседи, frozen dataclass'ы, round-trip в обычный dict, загрузка из TOML,
+  валидация при загрузке).
+- `clientkit.builder` — `build_client` / `build_from_toml`: единственная развилка
+  кита, и она смотрит на `decl.kind`.
+- `clientkit.white` — белый API: заголовок авторизации (`api_key`/`bearer`/
+  `oauth` с проактивным TTL) + прямой запрос. Ни сессий, ни чеканки, ни антибота.
+- `clientkit.hidden` — скрытый API: лестница доступа из декларации, чеканка через
+  порт слоя доступа, ротация адресов-кандидатов, разбор отказов через
+  `corekit.diagnosis.access`.
+- `clientkit._candidates` — книга адресов поверх `adapterkit.EndpointRegistry`
+  либо равнозначная встроенная (совпадение проверено тестом).
+- `clientkit.ports` — `RequestPort` / `SecretLookup`; умолчание транспорта
+  (netkit → httpx) резолвится лениво.
+
+Главное свойство: потребитель зовёт `await client.call("me")` одинаково в обоих
+мирах, при этом белый путь не поднимает ни сессий, ни чеканки, ни антибота и
+делает ровно один запрос.

s_clientkit-0.0.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_clientkit-0.0.1/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: s-clientkit
+Version: 0.0.1
+Summary: КИТ-СБОРЩИК: по ДЕКЛАРАЦИИ сервиса (TOML/dataclass) собирает готовый клиент из слоёв — белый API прямыми запросами, скрытый с удержанием доступа. Потребитель зовёт одинаково.
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: s-corekit>=0.0.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: endpoints
+Requires-Dist: s-adapterkit>=0.1.8; extra == 'endpoints'
+Provides-Extra: hidden
+Requires-Dist: s-authkit-client>=0.0.2; extra == 'hidden'
+Provides-Extra: http
+Requires-Dist: httpx>=0.27; extra == 'http'
+Provides-Extra: net
+Requires-Dist: s-netkit>=0.0.2; extra == 'net'
+Description-Content-Type: text/markdown
+
+# s-clientkit — кит-сборщик клиентов
+
+Готовый клиент сервиса **собирается по декларации**, а не пишется заново.
+
+```
+    clientkit                     <- СБОРЩИК (этот кит)
+    /        \
+authkit-client  browserkit        <- доступ (кто ты) / чеканка (как войти)
+    \        /
+      netkit                      <- сеть (чем ходить)
+         |
+      corekit                     <- основание
+```
+
+## Один вызов на оба мира
+
+```python
+from clientkit import build_from_toml
+
+white  = build_from_toml("examples/white_service.toml",  secrets=os.environ.get)
+hidden = build_from_toml("examples/hidden_service.toml", session_store=store)
+
+await white.call("me")      # белый REST с api-ключом
+await hidden.call("me")     # скрытый API с сессией и лестницей деградации
+```
+
+Потребитель зовёт **одинаково** и по поверхности клиента не может отличить один
+от другого. Разница — в цене:
+
+| | белый | скрытый |
+| --- | --- | --- |
+| поднимает сессии/чеканку/антибот | **нет** | да |
+| запросов на `call("me")` | **ровно 1** | 1 (+чеканка, если доступа нет) |
+| авторизация | заголовок (`api_key` / `bearer` / `oauth` с проактивным TTL) | cookies живой сессии |
+| смерть адреса | ошибка сервиса | следующий кандидат, без релиза |
+
+Обе половины проверяются тестом `tests/test_same_call_both_kinds.py` — по
+`sys.modules` свежего интерпретатора и по счётчику запросов, а не декларацией.
+
+## Декларация — данные
+
+`ServiceDecl` (frozen dataclass) читается из TOML и валидируется при загрузке:
+белый сервис с рецептом доступа или скрытый без чеканщика — опечатка, о которой
+надо узнать при сборке, а не ночью в бою. Round-trip
+`decl_to_data ∘ decl_from_data` проверяется тестом.
+
+Смотри `examples/white_service.toml` и `examples/hidden_service.toml`.
+
+## Чего в ките нет
+
+* **своего HTTP** — «чем ходить» приходит аргументом (`RequestPort`), умолчание
+  (netkit → httpx) резолвится лениво;
+* **своего браузера** — чеканка приходит через порт слоя доступа;
+* **своей таксономии отказов** — диагноз ставит `corekit.diagnosis.access`, та же
+  функция, что у живой пробы и у реестра эндпоинтов.

s_clientkit-0.0.1/README.md

@@ -0,0 +1,55 @@
+# s-clientkit — кит-сборщик клиентов
+
+Готовый клиент сервиса **собирается по декларации**, а не пишется заново.
+
+```
+    clientkit                     <- СБОРЩИК (этот кит)
+    /        \
+authkit-client  browserkit        <- доступ (кто ты) / чеканка (как войти)
+    \        /
+      netkit                      <- сеть (чем ходить)
+         |
+      corekit                     <- основание
+```
+
+## Один вызов на оба мира
+
+```python
+from clientkit import build_from_toml
+
+white  = build_from_toml("examples/white_service.toml",  secrets=os.environ.get)
+hidden = build_from_toml("examples/hidden_service.toml", session_store=store)
+
+await white.call("me")      # белый REST с api-ключом
+await hidden.call("me")     # скрытый API с сессией и лестницей деградации
+```
+
+Потребитель зовёт **одинаково** и по поверхности клиента не может отличить один
+от другого. Разница — в цене:
+
+| | белый | скрытый |
+| --- | --- | --- |
+| поднимает сессии/чеканку/антибот | **нет** | да |
+| запросов на `call("me")` | **ровно 1** | 1 (+чеканка, если доступа нет) |
+| авторизация | заголовок (`api_key` / `bearer` / `oauth` с проактивным TTL) | cookies живой сессии |
+| смерть адреса | ошибка сервиса | следующий кандидат, без релиза |
+
+Обе половины проверяются тестом `tests/test_same_call_both_kinds.py` — по
+`sys.modules` свежего интерпретатора и по счётчику запросов, а не декларацией.
+
+## Декларация — данные
+
+`ServiceDecl` (frozen dataclass) читается из TOML и валидируется при загрузке:
+белый сервис с рецептом доступа или скрытый без чеканщика — опечатка, о которой
+надо узнать при сборке, а не ночью в бою. Round-trip
+`decl_to_data ∘ decl_from_data` проверяется тестом.
+
+Смотри `examples/white_service.toml` и `examples/hidden_service.toml`.
+
+## Чего в ките нет
+
+* **своего HTTP** — «чем ходить» приходит аргументом (`RequestPort`), умолчание
+  (netkit → httpx) резолвится лениво;
+* **своего браузера** — чеканка приходит через порт слоя доступа;
+* **своей таксономии отказов** — диагноз ставит `corekit.diagnosis.access`, та же
+  функция, что у живой пробы и у реестра эндпоинтов.

s_clientkit-0.0.1/clientkit/__init__.py

@@ -0,0 +1,120 @@
+"""clientkit — КИТ-СБОРЩИК: готовый клиент сервиса собирается, а не пишется.
+
+ФОРМА ГРАФА::
+
+        clientkit                     <- СБОРЩИК (вы здесь)
+        /        \\
+    authkit-client  browserkit        <- доступ (кто ты) / чеканка (как войти)
+        \\        /
+          netkit                      <- сеть (чем ходить)
+             |
+          corekit                     <- основание (значения и чистые правила)
+
+ЗАЧЕМ. Интеграция с сервисом — это каждый раз одни и те же пять решений: куда
+ходить, чем представляться, как часто можно, какие операции есть и (если API
+скрытый) чем держать доступ. Пока эти решения — КОД, каждый новый сервис стоит
+файла на триста строк, который через месяц разъедется с соседним. Здесь они —
+ДАННЫЕ (:class:`~clientkit.declaration.ServiceDecl`, читается из TOML), а код
+один на всех.
+
+ОДИН ВЫЗОВ НА ОБА МИРА::
+
+    from clientkit import build_from_toml
+
+    white  = build_from_toml("examples/white_service.toml",  secrets=os.environ.get)
+    hidden = build_from_toml("examples/hidden_service.toml", session_store=store)
+
+    await white.call("me")      # белый REST с api-ключом
+    await hidden.call("me")     # скрытый API с сессией и лестницей деградации
+
+Потребитель зовёт ОДИНАКОВО и по поверхности клиента не может отличить один от
+другого. При этом белый путь НЕ поднимает ни сессий, ни чеканки, ни антибота и
+делает ровно один запрос — это проверяется тестом по ``sys.modules`` и по
+счётчику запросов, а не декларируется.
+
+ЧЕГО ЗДЕСЬ НЕТ. Своего HTTP: «чем ходить» приходит аргументом
+(:class:`~clientkit.ports.RequestPort`), умолчание резолвится лениво. Своего
+браузера: чеканка приходит через порт слоя доступа. Своей таксономии отказов:
+диагноз ставит `corekit.diagnosis.access` — та же функция, что у живой пробы и у
+реестра эндпоинтов.
+"""
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+__version__ = "0.0.1"
+
+if TYPE_CHECKING:  # pragma: no cover — для тайпчекера/IDE
+    from clientkit._base import ServiceClient
+    from clientkit.builder import build_client, build_from_toml
+    from clientkit.declaration import (
+        AccessRecipe,
+        AuthDecl,
+        AuthScheme,
+        EndpointDecl,
+        LimitDecl,
+        ServiceDecl,
+        ServiceKind,
+        decl_from_data,
+        decl_to_data,
+        load_toml,
+    )
+    from clientkit.errors import AccessUnavailable, ClientBuildError, OperationFailed
+    from clientkit.hidden import HiddenApiClient
+    from clientkit.ports import RequestPort, SecretLookup
+    from clientkit.white import WhiteApiClient
+
+#: имя -> модуль-владелец. `hidden` в этой таблице стоит РЯДОМ с `white`, но
+#: цена у них разная: обращение к `HiddenApiClient` подтягивает слой доступа, а
+#: к `WhiteApiClient` — нет. Ленивость здесь и защищает эту разницу.
+_LAZY_NAMES: dict[str, str] = {
+    "build_client": "clientkit.builder",
+    "build_from_toml": "clientkit.builder",
+    "ServiceClient": "clientkit._base",
+    # ИМЯ сервиса — тоже данные, и притом нужные тем, кто базы не держит:
+    # навыку назвать свою сессию, записи трафика — положить снимок.
+    "ServiceIdentity": "clientkit.identity",
+    "Instancing": "clientkit.identity",
+    "UnknownService": "clientkit.identity",
+    "CATALOG": "clientkit.identity",
+    "canonical": "clientkit.identity",
+    "resolve_service": "clientkit.identity",
+    "suggest_service": "clientkit.identity",
+    # декларация — данные
+    "ServiceDecl": "clientkit.declaration",
+    "ServiceKind": "clientkit.declaration",
+    "AuthDecl": "clientkit.declaration",
+    "AuthScheme": "clientkit.declaration",
+    "LimitDecl": "clientkit.declaration",
+    "EndpointDecl": "clientkit.declaration",
+    "AccessRecipe": "clientkit.declaration",
+    "decl_from_data": "clientkit.declaration",
+    "decl_to_data": "clientkit.declaration",
+    "load_toml": "clientkit.declaration",
+    # порты
+    "RequestPort": "clientkit.ports",
+    "SecretLookup": "clientkit.ports",
+    # клиенты (обычно не нужны напрямую — собирает build_client)
+    "WhiteApiClient": "clientkit.white",
+    "HiddenApiClient": "clientkit.hidden",
+    # ошибки
+    "ClientBuildError": "clientkit.errors",
+    "AccessUnavailable": "clientkit.errors",
+    "OperationFailed": "clientkit.errors",
+}
+
+__all__ = ["__version__", *sorted(_LAZY_NAMES)]
+
+
+def __getattr__(name: str):
+    module_name = _LAZY_NAMES.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(module_name), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_LAZY_NAMES})

s_clientkit-0.0.1/clientkit/_base.py

@@ -0,0 +1,160 @@
+"""Общая часть обоих клиентов: ОДИН вызов, одна сборка запроса, один разбор.
+
+Смысл файла — в том, чего в нём нет: ни одного ``if kind == HIDDEN``. Различие
+белого и скрытого путей вынесено в ДВЕ вещи, которые подклассы переопределяют,
+— заголовки (:meth:`ServiceClientBase._headers`) и адрес операции
+(:meth:`ServiceClientBase._address`). Всё остальное — подстановка параметров,
+лимит, отправка, разбор — общее, поэтому потребителю нечем отличить один путь от
+другого: он зовёт ``await client.call("me")`` и там, и там.
+"""
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Any, Protocol, runtime_checkable
+
+from clientkit._limit import TokenBucket
+from clientkit.declaration import EndpointDecl, ServiceDecl
+from clientkit.ports import RequestPort
+
+__all__ = ["ServiceClient", "ServiceClientBase"]
+
+#: Потолок починок на один вызов: сессия могла умереть И адрес мог смениться,
+#: но третья попытка починить то же самое — уже круг.
+MAX_REPAIRS = 3
+
+#: ``{name}`` в пути операции — параметр, который уезжает В АДРЕС, а не в запрос.
+_PLACEHOLDER = re.compile(r"\{(\w+)\}")
+
+
+@runtime_checkable
+class ServiceClient(Protocol):
+    """ЕДИНЫЙ контракт готового клиента — то, ради чего собирался кит.
+
+    Ровно два имени. Потребитель, которому дали такой объект, НЕ МОЖЕТ узнать по
+    его поверхности, белый под ним API или скрытый: одна операция вызова и одно
+    свойство с именем сервиса.
+    """
+
+    name: str
+
+    async def call(self, operation: str, **params: Any) -> Any:
+        """Позвать операцию по ИМЕНИ и получить разобранный ответ."""
+        ...
+
+
+class ServiceClientBase:
+    """Скелет клиента: подстановка → лимит → запрос → разбор."""
+
+    def __init__(self, decl: ServiceDecl, transport: RequestPort) -> None:
+        self.decl = decl
+        self.name = decl.name
+        self._transport = transport
+        self._bucket = (
+            TokenBucket(decl.limits.rate, decl.limits.burst) if decl.limits.rate else None
+        )
+        #: счётчик отправленных запросов — улика для тестов и для отчёта о цене
+        #: вызова («белый путь = один запрос» проверяется числом, а не верой).
+        self.requests_sent = 0
+
+    # ------------------------------------------------------------------ #
+    # то, чем различаются белый и скрытый пути                            #
+    # ------------------------------------------------------------------ #
+    async def _headers(self) -> dict[str, str]:
+        """Заголовки авторизации. Белый — ключ/токен, скрытый — cookies сессии."""
+        return {}
+
+    async def _address(self, endpoint: EndpointDecl) -> str:
+        """Адрес операции (у скрытого — текущий живой кандидат)."""
+        return endpoint.path
+
+    async def _inspect(self, endpoint: EndpointDecl, response: Any) -> bool:
+        """Осмотреть ЛЮБОЙ ответ. ``True`` — починили, стоит повторить вызов.
+
+        Зовётся на каждом ответе, а не только на «похожем на ошибку», и это
+        принципиально: скрытый API хоронит метод статусом 200 с телом
+        ``unknown rpcid``. Гадать о виде отказа ЗДЕСЬ нельзя — таксономия одна на
+        экосистему (`corekit.diagnosis.access`), и подключает её тот клиент,
+        которому она нужна.
+
+        База не чинит ничего: у белого API отказ — это ответ сервиса, и глотать
+        его нельзя.
+        """
+        return False
+
+    # ------------------------------------------------------------------ #
+    # общий путь вызова                                                   #
+    # ------------------------------------------------------------------ #
+    async def call(self, operation: str, **params: Any) -> Any:
+        """Позвать операцию по имени. Одинаково для белого и скрытого сервиса."""
+        endpoint = self.decl.endpoint(operation)
+        attempts = 0
+        while True:
+            attempts += 1
+            address = await self._address(endpoint)
+            path, rest = _apply_placeholders(address, params)
+            headers = await self._headers()
+            if self._bucket is not None:
+                await self._bucket.acquire()
+            response = await self._send(endpoint.method, self._url(path), headers, rest)
+            self.requests_sent += 1
+            # Потолок повторов — страховка от бесконечного круга «починили →
+            # снова то же самое». Каждая починка ЧТО-ТО меняет (сессию либо
+            # адрес), поэтому исчерпание потолка означает, что чинить больше
+            # нечем; ответ уходит наверх как есть.
+            if attempts <= MAX_REPAIRS and await self._inspect(endpoint, response):
+                continue
+            return _parse(response)
+
+    def _url(self, path: str) -> str:
+        """Склейка базы и пути без двойных слэшей и без потери суффикса базы."""
+        if path.startswith(("http://", "https://")):
+            return path
+        return f"{self.decl.base_url.rstrip('/')}/{path.lstrip('/')}"
+
+    async def _send(
+        self, method: str, url: str, headers: dict[str, str], params: dict[str, Any]
+    ) -> Any:
+        """Отправить запрос через порт (sync-транспорт тоже годится)."""
+        kwargs: dict[str, Any] = {"headers": headers}
+        if method in {"GET", "HEAD", "DELETE"}:
+            kwargs["params"] = params
+        else:
+            kwargs["json"] = params
+        result = self._transport.request(method, url, **kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+
+def _apply_placeholders(path: str, params: dict[str, Any]) -> tuple[str, dict[str, Any]]:
+    """``/users/{id}`` + ``{"id": 7, "q": "x"}`` → ``/users/7`` + ``{"q": "x"}``.
+
+    Параметр, названный в адресе, в запрос НЕ уезжает — иначе ``id`` уходил бы и
+    в путь, и в query, и половина сервисов отвечала бы 400 на ровном месте.
+    """
+    used: list[str] = []
+
+    def _sub(match: re.Match[str]) -> str:
+        key = match.group(1)
+        if key not in params:
+            raise KeyError(f"адрес {path!r} требует параметр {key!r}, а его не передали")
+        used.append(key)
+        return str(params[key])
+
+    resolved = _PLACEHOLDER.sub(_sub, path)
+    return resolved, {k: v for k, v in params.items() if k not in used}
+
+
+
+
+def _parse(response: Any) -> Any:
+    """Разобрать ответ: ``.json()`` если умеет, иначе ``.text``, иначе как есть."""
+    parser = getattr(response, "json", None)
+    if callable(parser):
+        try:
+            return parser()
+        except Exception:
+            pass
+    text = getattr(response, "text", None)
+    return text if text is not None else response