s-clientkit 0.0.1__py3-none-any.whl

clientkit/identity.py

@@ -0,0 +1,249 @@
+"""ЕДИНОЕ ИМЯ СЕРВИСА и его входы — данные, а не строка в каждом коде.
+
+ЗАЧЕМ ЭТОТ МОДУЛЬ ПОЯВИЛСЯ. Замер 2026-08-08: навыки пишут сессии под именами
+``grok``, ``chatgpt``, ``deepseek``, ``gigachat``, ``google-flow``, ``qwen``,
+``b24`` — и СЕМЬ ИЗ ДЕВЯТИ в реестре сервисов отсутствуют вовсе, а совпадающие
+названы иначе (реестр знает ``chatgpt-chat``, навык пишет ``chatgpt``; реестр
+``flow`` — навык ``google-flow``). Реестр и хранилище сессий живут в параллельных
+вселенных, потому что сверять их нечем: имя — просто строка, которую каждый
+пишет как помнит. Достаточно опечатки, чтобы у одного аккаунта стало две сессии.
+
+ПОЧЕМУ ЗДЕСЬ, А НЕ РЯДОМ С ТАБЛИЦАМИ. Имя сервиса нужно ВСЕМ — в том числе тем,
+кто базы не держит: навыку, чтобы назвать свою сессию; записи трафика, чтобы
+положить снимок; CLI, чтобы показать список. Положив это знание к таблицам, мы
+заставили бы каждого потребителя тянуть ORM и вендора БД ради одной строки.
+Здесь — только значения (кит зависит от одного основания), а хранилище получает
+их снаружи и сеет у себя.
+
+СИНОНИМЫ — СПОСОБ ПЕРЕВЕСТИ, НЕ ЛОМАЯ. `b24` и `google-flow` не переименовать
+одним днём: под ними уже лежат сессии и на них ссылается чужой код. Поэтому у
+сервиса есть канонический ``code`` и список ``aliases``; резолвер сводит их к
+одному сервису, и две сессии перестают быть двумя — без правки навыков в тот же
+день.
+
+ИНСТАНС — НЕ ОТДЕЛЬНЫЙ СЕРВИС. У Битрикс24 порталов много (``acme.bitrix24.ru``,
+``beta.bitrix24.kz``), и куки у них разные — но продукт ОДИН. Заводить
+``bitrix24-kz`` отдельным сервисом значит снова размножить имена, то есть
+воспроизвести ровно ту болезнь, которую лечим. Поэтому ``instancing=MULTI`` и
+адрес входа собирается из шаблона по хосту портала.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+__all__ = [
+    "CATALOG",
+    "resolve_service",
+    "suggest_service",
+    "Instancing",
+    "ServiceIdentity",
+    "UnknownService",
+    "canonical",
+    "resolve",
+    "suggest",
+]
+
+
+class UnknownService(LookupError):  # noqa: N818  # доменное имя контракта (не *Error)
+    """Такого сервиса нет ни по коду, ни по синониму."""
+
+
+class Instancing(StrEnum):
+    """Сколько входов у сервиса.
+
+    ``SINGLE`` — один адрес на всех (``grok.com``). ``MULTI`` — у каждого клиента
+    свой хост (портал Битрикса, поддомен арендатора), и адрес собирается из
+    шаблона.
+    """
+
+    SINGLE = "single"
+    MULTI = "multi"
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceIdentity:
+    """Кто такой сервис: канон-имя, синонимы и куда вести браузер за входом."""
+
+    code: str
+    display: str = ""
+    aliases: tuple[str, ...] = ()
+    #: Полный URL входа (SINGLE) либо шаблон с ``{host}`` (MULTI).
+    auth_url: str = ""
+    instancing: Instancing = Instancing.SINGLE
+    #: Хосты, по которым сервис узнаётся в capture и в ссылках.
+    hosts: tuple[str, ...] = ()
+    note: str = ""
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        """Все имена, по которым сервис узнаётся (канон первым)."""
+        seen: list[str] = []
+        for name in (self.code, *self.aliases):
+            if name and name not in seen:
+                seen.append(name)
+        return tuple(seen)
+
+    def knows(self, name: str) -> bool:
+        """Отзывается ли сервис на это имя (регистр не важен)."""
+        wanted = (name or "").strip().casefold()
+        return any(alias.casefold() == wanted for alias in self.names)
+
+    def login_url(self, host: str = "") -> str:
+        """Адрес входа: для MULTI — подставив хост портала.
+
+        :raises ValueError: сервис многоинстансный, а хост не назван — вести
+            браузер «куда-нибудь» хуже, чем честно сказать, чего не хватает.
+        """
+        if self.instancing is Instancing.SINGLE:
+            return self.auth_url
+        if not host:
+            raise ValueError(
+                f"у сервиса `{self.code}` свой адрес у каждого клиента "
+                f"(например {self.hosts[0] if self.hosts else 'portal.example'}) — "
+                "назови хост инстанса"
+            )
+        return self.auth_url.format(host=host.strip().strip("/"))
+
+
+#: КАТАЛОГ известных сервисов. Коды — те, под которыми уже лежат сессии: менять
+#: их значило бы устроить миграцию данных ради красоты имени. Расхождения с
+#: прежними названиями закрыты синонимами.
+CATALOG: tuple[ServiceIdentity, ...] = (
+    ServiceIdentity(
+        code="grok",
+        display="Grok (xAI)",
+        auth_url="https://grok.com/",
+        hosts=("grok.com",),
+    ),
+    ServiceIdentity(
+        code="chatgpt",
+        display="ChatGPT",
+        aliases=("chatgpt-chat",),
+        auth_url="https://chatgpt.com/",
+        hosts=("chatgpt.com", "chat.openai.com"),
+        note="`chatgpt-chat` — имя из прежнего каталога сервисов",
+    ),
+    ServiceIdentity(
+        code="gemini",
+        display="Gemini",
+        aliases=("gemini-chat",),
+        auth_url="https://gemini.google.com/app",
+        hosts=("gemini.google.com",),
+    ),
+    ServiceIdentity(
+        code="qwen",
+        display="Qwen",
+        auth_url="https://chat.qwen.ai/",
+        hosts=("chat.qwen.ai",),
+    ),
+    ServiceIdentity(
+        code="deepseek",
+        display="DeepSeek",
+        auth_url="https://chat.deepseek.com/",
+        hosts=("chat.deepseek.com",),
+    ),
+    ServiceIdentity(
+        code="gigachat",
+        display="GigaChat",
+        auth_url="https://giga.chat/",
+        hosts=("giga.chat",),
+    ),
+    ServiceIdentity(
+        code="flow",
+        display="Google Flow",
+        aliases=("google-flow",),
+        auth_url="https://labs.google/fx/tools/flow",
+        hosts=("labs.google",),
+        note="`google-flow` — имя пакета навыка, под ним уже лежат сессии",
+    ),
+    ServiceIdentity(
+        code="notebooklm",
+        display="NotebookLM",
+        auth_url="https://notebooklm.google.com/",
+        hosts=("notebooklm.google.com",),
+    ),
+    ServiceIdentity(
+        code="bitrix24",
+        display="Битрикс24",
+        aliases=("b24",),
+        auth_url="https://{host}/auth/",
+        instancing=Instancing.MULTI,
+        hosts=("bitrix24.ru", "bitrix24.kz", "bitrix24.by", "bitrix24.com"),
+        note=(
+            "портал у каждого клиента свой, национальные домены — ИНСТАНСЫ одного "
+            "сервиса, а не разные сервисы"
+        ),
+    ),
+    ServiceIdentity(
+        code="telegram",
+        display="Telegram",
+        aliases=("tg",),
+        auth_url="https://web.telegram.org/",
+        hosts=("web.telegram.org", "telegram.org"),
+    ),
+)
+
+_BY_NAME: dict[str, ServiceIdentity] = {
+    alias.casefold(): svc for svc in CATALOG for alias in svc.names
+}
+
+
+def resolve(name: str, catalog: tuple[ServiceIdentity, ...] = CATALOG) -> ServiceIdentity:
+    """Имя (канон или синоним) → сервис.
+
+    :raises UnknownService: имени нет — с подсказкой, что похоже. Молча заводить
+        новый сервис нельзя: именно так рядом с ``grok`` появляется ``grok-chat``.
+    """
+    wanted = (name or "").strip()
+    if not wanted:
+        raise UnknownService("имя сервиса пустое — нечего резолвить")
+    index = _BY_NAME if catalog is CATALOG else {
+        alias.casefold(): svc for svc in catalog for alias in svc.names
+    }
+    found = index.get(wanted.casefold())
+    if found is not None:
+        return found
+    hint = suggest(wanted, catalog)
+    tail = f" Возможно, имелось в виду: {', '.join(hint)}." if hint else ""
+    raise UnknownService(f"сервис `{wanted}` неизвестен.{tail}")
+
+
+def canonical(name: str, catalog: tuple[ServiceIdentity, ...] = CATALOG) -> str:
+    """Каноническое имя сервиса по любому из его имён."""
+    return resolve(name, catalog).code
+
+
+def suggest(
+    name: str, catalog: tuple[ServiceIdentity, ...] = CATALOG, *, limit: int = 3
+) -> tuple[str, ...]:
+    """Похожие известные имена — чтобы отказ говорил, что делать.
+
+    Сравнение простое и объяснимое: общее начало либо вхождение одного в другое.
+    Умная метрика тут не нужна — ошибаются в дефисе и суффиксе (``grok-chat``,
+    ``google-flow``), а не в буквах.
+    """
+    wanted = (name or "").strip().casefold()
+    if not wanted:
+        return ()
+    scored: list[tuple[int, str]] = []
+    for svc in catalog:
+        for alias in svc.names:
+            low = alias.casefold()
+            if low == wanted:
+                continue
+            if wanted in low or low in wanted:
+                scored.append((0, svc.code))
+            elif low[:3] == wanted[:3]:
+                scored.append((1, svc.code))
+    seen: list[str] = []
+    for _, code in sorted(scored):
+        if code not in seen:
+            seen.append(code)
+    return tuple(seen[:limit])
+
+
+#: Псевдонимы для корня пакета: в общем пространстве имён `resolve`/`suggest`
+#: ничего не говорят о предмете, а `resolve_service` — говорит.
+resolve_service = resolve
+suggest_service = suggest

clientkit/ports.py

@@ -0,0 +1,70 @@
+"""Порты сборщика: чем ходить в сеть и откуда брать секреты.
+
+Сборщик СВОЕГО HTTP-клиента не имеет — и это не аскеза. Стоит зашить httpx, и
+кит перестанет собираться там, где ходят curl_cffi (антибот), где ходит netkit с
+своей политикой повторов, где вообще нет сети (тест). Поэтому «чем ходить»
+приходит аргументом, а умолчание резолвится ЛЕНИВО и только если аргумент не дали.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Protocol, runtime_checkable
+
+__all__ = ["RequestPort", "ResponseLike", "SecretLookup", "resolve_transport"]
+
+
+@runtime_checkable
+class ResponseLike(Protocol):
+    """Утиный ответ: столько, сколько нужно и для разбора, и для диагноза."""
+
+    status_code: int
+    text: str
+
+
+@runtime_checkable
+class RequestPort(Protocol):
+    """Одна операция: сходить и вернуть ответ. Sync либо async — сборщик дождётся."""
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> Any: ...
+
+
+@runtime_checkable
+class SecretLookup(Protocol):
+    """``(name) -> секрет | None``. Реализуют env, `SecretStorePort`, keyring, vault."""
+
+    def __call__(self, name: str) -> str | None: ...
+
+
+def resolve_transport() -> RequestPort:
+    """Умолчание «чем ходить»: netkit → httpx → внятный отказ.
+
+    Порядок не случаен: netkit — наш сетевой слой (повторы, лимиты, egress из
+    контекста), httpx — честный запасной вариант для того, кто netkit не ставил.
+    Отказ, если нет ни одного, звучит инструкцией, а не `ModuleNotFoundError`:
+    человек должен прочитать, ЧТО поставить или ЧТО передать.
+    """
+    try:  # netkit — предпочтительный: он знает про контекст и повторы
+        from netkit import HttpxTransport  # type: ignore[attr-defined]
+
+        return HttpxTransport()  # type: ignore[return-value]
+    except Exception:
+        pass
+    try:
+        import httpx
+
+        return httpx.AsyncClient()  # type: ignore[return-value]
+    except ImportError as exc:  # pragma: no cover — окружение без обоих колёс
+        raise RuntimeError(
+            "нечем ходить в сеть: не установлены ни s-netkit, ни httpx. "
+            "Поставь одно из них — либо передай свой транспорт "
+            "`build_client(decl, transport=...)` (годится любой объект с "
+            "методом `request(method, url, headers=, params=, json=)`)."
+        ) from exc

clientkit/white.py

@@ -0,0 +1,84 @@
+"""БЕЛЫЙ путь: прямые запросы. Ни сессий, ни чеканки, ни антибота.
+
+Здесь важно не то, что написано, а то, чего НЕ написано и не импортируется. У
+белого API есть документированный адрес и документированный способ
+представиться — значит, весь слой удержания доступа ему не нужен НИКОГДА, и
+платить за него импортом он не должен.
+
+Модуль знает ровно три схемы заголовка (api-key / bearer / oauth) и ни одной
+строки про cookies. ``oauth`` — единственное место, где подтягивается
+`authkit_client.oauth`: пара токенов с ПРОАКТИВНЫМ обновлением по TTL (живой
+токен = ноль лишних запросов). Импорт ленивый и точечный — модуль `oauth` не
+тянет за собой ни хранилище сессий, ни SQLite.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from clientkit._base import ServiceClientBase
+from clientkit.declaration import AuthScheme, ServiceDecl
+from clientkit.errors import ClientBuildError
+from clientkit.ports import RequestPort, SecretLookup
+
+__all__ = ["WhiteApiClient"]
+
+
+class WhiteApiClient(ServiceClientBase):
+    """Клиент белого API: заголовок авторизации + прямой запрос.
+
+    ``secrets`` — ``(name) -> секрет | None``: env, `SecretStorePort`, vault —
+    что угодно. Сам секрет в декларации не лежит и лежать не будет.
+    """
+
+    def __init__(
+        self,
+        decl: ServiceDecl,
+        transport: RequestPort,
+        *,
+        secrets: SecretLookup | None = None,
+        oauth_refresher: Any | None = None,
+        tokens: Any | None = None,
+    ) -> None:
+        super().__init__(decl, transport)
+        self._secrets = secrets
+        self._oauth = None
+        if decl.auth.scheme is AuthScheme.OAUTH:
+            self._oauth = self._build_oauth(tokens, oauth_refresher)
+
+    def _build_oauth(self, tokens: Any, refresher: Any):
+        """Собрать `OAuthSession` — ленивый импорт слоя доступа, точечный."""
+        if tokens is None or refresher is None:
+            raise ClientBuildError(
+                f"сервис {self.decl.name!r} объявлен с auth.scheme = 'oauth', но "
+                "пары токенов и/или колбэка обновления не дали. Передай "
+                "`build_client(decl, tokens=..., oauth_refresher=...)`: обмен "
+                "делает потребитель, кит отвечает за ВРЕМЯ, а не за протокол."
+            )
+        from authkit_client.oauth import OAuthSession
+
+        return OAuthSession(tokens, refresher=refresher, leeway=self.decl.auth.leeway)
+
+    async def _headers(self) -> dict[str, str]:
+        """Заголовок авторизации по объявленной схеме."""
+        auth = self.decl.auth
+        if auth.scheme is AuthScheme.NONE:
+            return {}
+        if auth.scheme is AuthScheme.OAUTH:
+            # ПРОАКТИВНО: живой токен — ноль сетевых вызовов (сравнение чисел),
+            # истекающий обновляется ДО основного запроса, а не после 401.
+            await self._oauth.maybe_refresh()
+            secret = self._oauth.tokens.access_token
+        else:
+            secret = self._lookup(auth.secret_name)
+        return {auth.header: auth.template.format(secret=secret)}
+
+    def _lookup(self, name: str) -> str:
+        """Достать секрет по ИМЕНИ; отсутствие — внятный отказ при вызове."""
+        value = self._secrets(name) if self._secrets is not None else None
+        if not value:
+            raise ClientBuildError(
+                f"сервис {self.decl.name!r}: секрет {name!r} не найден. Декларация "
+                "хранит ИМЯ секрета, а значение приносит `secrets=` — env, "
+                "SecretStore, vault: что угодно с сигнатурой (name) -> str | None."
+            )
+        return value

s_clientkit-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+clientkit/__init__.py,sha256=iOM6nC4a6H226paTOStjLVoxNvie_FwXJqXfU6xztYY,5989
+clientkit/_base.py,sha256=Q52yHZ8s4x5fWKzD3spitZzbJA7YX74jm1loVHgzCas,8515
+clientkit/_candidates.py,sha256=1B6h9Z-qL_L-ROIRNRyMGUWaJkWmhM-U9Lob-AMy7lA,7611
+clientkit/_limit.py,sha256=YG_tlJEoWGbiy9R4k1ZSVHncUSW9cEdR4gw129H3HcU,2373
+clientkit/builder.py,sha256=b1Nt4AFWBFLUP833Bi_RQ7BCBwF9FoAhBI-G-W7VBSg,3162
+clientkit/declaration.py,sha256=Si9D9k1v8YMDXZz4QVbTJXF5WGCasbRbJR6eelsTWHc,16556
+clientkit/errors.py,sha256=OfK9UsUoHvltGM66ZtJY3G0Fa4dkkz2xXcX7ZP6rb-g,2118
+clientkit/hidden.py,sha256=ph6hfo-niKLI0xrBatnOZfs_w_Rg8EZvP7U5M86_VG8,10646
+clientkit/identity.py,sha256=ZHLJDiz461FBDU1szAtx9nWKpoqmrwwxGv-FR6CDvCo,11568
+clientkit/ports.py,sha256=smQG7aP7lc8SWn_VOQ7zDvZetMR8-glAkOYiWn29gSQ,3268
+clientkit/white.py,sha256=hCgupqXERArvGOOu4qjVV1vyCtqcppaoxNzFKYDt8Rg,4565
+s_clientkit-0.0.1.dist-info/METADATA,sha256=59q1TfajZeivOVHq3maQy1-EmDmnHixjnODYZASm-3k,3977
+s_clientkit-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+s_clientkit-0.0.1.dist-info/licenses/LICENSE,sha256=j9GKJmUNdQuKRUbKhbpv0uyMaL99xsxE6L2TDtXuaZ4,1063
+s_clientkit-0.0.1.dist-info/RECORD,,

s_clientkit-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

s_clientkit-0.0.1.dist-info/licenses/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.