cristalixapi 1.0.0__tar.gz

cristalixapi-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+**/__pycache__/
+dist/
+*.egg-info/
+build/

cristalixapi-1.0.0/.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

cristalixapi-1.0.0/.idea/CristalixAPI.iml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="Python 3.14 (CristalixAPI)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

cristalixapi-1.0.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

cristalixapi-1.0.0/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.14 (CristalixAPI)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.14 (CristalixAPI)" project-jdk-type="Python SDK" />
+</project>

cristalixapi-1.0.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/CristalixAPI.iml" filepath="$PROJECT_DIR$/.idea/CristalixAPI.iml" />
+    </modules>
+  </component>
+</project>

cristalixapi-1.0.0/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

cristalixapi-1.0.0/.idea/workspace.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="0a030fa9-f362-479a-9f03-749968cab870" name="Changes" comment="1">
+      <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
+    </list>
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="Git.Settings">
+    <option name="RECENT_GIT_ROOT_PATH" value="$PROJECT_DIR$" />
+  </component>
+  <component name="GitHubPullRequestSearchHistory"><![CDATA[{
+  "lastFilter": {
+    "state": "OPEN",
+    "assignee": "LisoMandiy"
+  }
+}]]></component>
+  <component name="GithubPullRequestsUISettings"><![CDATA[{
+  "selectedUrlAndAccountId": {
+    "url": "https://github.com/LisoMandiy/CristalixAPI.git",
+    "accountId": "c075a5f7-1695-45aa-8489-7d0bf4e28a00"
+  }
+}]]></component>
+  <component name="McpProjectServerCommands">
+    <commands />
+    <urls />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 5
+}]]></component>
+  <component name="ProjectId" id="3F3Cc95CxbOYMdCIvkPdH4WhF58" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.MCP Project settings loaded": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "com.intellij.ml.llm.matterhorn.ej.ui.settings.DefaultModelSelectionForGA.v1": "true",
+    "git-widget-placeholder": "master",
+    "junie.onboarding.icon.badge.shown": "true",
+    "settings.editor.selected.configurable": "org.jetbrains.plugins.github.ui.GithubSettingsConfigurable",
+    "to.speed.mode.migration.done": "true"
+  }
+}]]></component>
+  <component name="RecentsManager">
+    <key name="MoveFile.RECENT_KEYS">
+      <recent name="C:\Users\LisoMandiy\PycharmProjects\CristalixAPI" />
+    </key>
+  </component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-python-sdk-2653e85de345-6d6dccd035ac-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-253.31033.139" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="0a030fa9-f362-479a-9f03-749968cab870" name="Changes" comment="" />
+      <created>1781294443142</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1781294443142</updated>
+    </task>
+    <task id="LOCAL-00001" summary="1">
+      <option name="closed" value="true" />
+      <created>1781295080192</created>
+      <option name="number" value="00001" />
+      <option name="presentableId" value="LOCAL-00001" />
+      <option name="project" value="LOCAL" />
+      <updated>1781295080193</updated>
+    </task>
+    <option name="localTasksCounter" value="2" />
+    <servers />
+  </component>
+  <component name="VcsManagerConfiguration">
+    <MESSAGE value="1" />
+    <option name="LAST_COMMIT_MESSAGE" value="1" />
+  </component>
+</project>

cristalixapi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CristalixAPI
+
+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.

cristalixapi-1.0.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: cristalixapi
+Version: 1.0.0
+Summary: Python client for https://api.cristalix.gg
+Project-URL: Homepage, https://github.com/LisoMandiy/cristalixtopclaude
+Author: LisoMandiy
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx[http2]>=0.27.0
+Description-Content-Type: text/markdown
+
+# CristalixAPI
+
+Python-библиотека для работы с [Cristalix Public API](https://top.cristalix.gg/api-docs).
+
+Есть синхронный и асинхронный клиент, типизированные ответы и автоматические повторы при rate limit.
+
+## Установка
+
+```bash
+pip install cristalixapi
+```
+
+## Авторизация
+
+1. Войди на [top.cristalix.gg/api-docs](https://top.cristalix.gg/api-docs) через аккаунт Cristalix.
+2. Создай проект — получишь `project_key` и `project_token`.
+3. Токен показывается один раз. Если потерял — пересоздай через «Пересоздать токен».
+
+## Быстрый старт
+
+```python
+from cristalixapi import CristalixClient
+
+with CristalixClient(project_key="...", token="...") as client:
+    profile = client.get_profile_by_name("KoTuK_PvP")
+    print(profile["name"], profile["groups"])
+```
+
+## Асинхронный вариант
+
+```python
+import asyncio
+import httpx
+from cristalixapi import AsyncCristalixClient
+
+async def main():
+    limits = httpx.Limits(max_connections=50, max_keepalive_connections=10)
+    async with AsyncCristalixClient(project_key="...", token="...", limits=limits) as client:
+        profile = await client.get_profile_by_name("KoTuK_PvP")
+        print(profile)
+
+asyncio.run(main())
+```
+
+## Что умеет клиент
+
+### Игры
+
+```python
+# Список активных игр с режимами и полями статистики
+games = client.get_games()
+game_id = games[0]["gameId"]
+```
+
+### Лидерборды
+
+```python
+# Топ-10 по победам
+top = client.get_leaderboard(game_id, field="wins", limit=10)
+
+# Топ с динамикой (немного медленнее)
+top = client.get_leaderboard(game_id, field="wins", trends=True)
+
+# Топ с данными по всем периодам сразу
+rich = client.get_leaderboard_rich(game_id, field="wins", period="WEEK")
+```
+
+Периоды: `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`, `ALL`.
+
+### Статистика игрока
+
+```python
+# Статистика за конкретный период
+stats = client.get_player_stats(game_id, player_id, period="WEEK")
+print(stats["fields"])  # {"wins": 5, "kills": 15, ...}
+
+# Сразу все периоды
+periods = client.get_player_periods(game_id, player_id)
+print(periods["periods"]["ALL"])
+
+# Позиция в топе
+pos = client.get_player_position(game_id, player_id, field="wins")
+print(pos["position"])  # -1 если игрок не в рейтинге
+
+# Вся статистика по всем играм одним запросом
+all_stats = client.get_player_aggregated_stats(player_id)
+```
+
+### Профили
+
+```python
+# По UUID
+profile = client.get_profile_by_id("ea0a316c-...")
+
+# По нику
+profile = client.get_profile_by_name("KoTuK_PvP")
+
+# Много игроков сразу (до 200)
+batch = client.get_profiles_batch(["uuid1", "uuid2", "uuid3"])
+print(batch["found"], batch["notFound"])
+
+# То же самое по никам
+batch = client.get_profiles_batch_names(["KoTuK_PvP", "linkerii"])
+
+# Поиск по префиксу ника (автокомплит)
+results = client.search_players("Ko", limit=5)
+```
+
+Лёгкий режим `lite=True` возвращает только `playerId`, `name`, `status`, `groups` — удобно для списков.
+
+### Социальные данные
+
+```python
+# Друзья
+friends = client.get_friends(player_id, limit=50)
+
+# Подписчики (INCOMING) или подписки (OUTGOING)
+subs = client.get_subscribers(player_id, type="OUTGOING")
+
+# История смены ников
+history = client.get_name_history(player_id)
+
+# Текущий онлайн и реалм
+location = client.get_location(player_id)
+
+# Кто поставил лайк / дизлайк
+reactions = client.get_reactions(player_id, type="LIKE")
+```
+
+### Рейтинги
+
+```python
+top_karma = client.get_ratings_karma(limit=10)
+top_likes = client.get_ratings_likes(limit=10)
+top_views = client.get_ratings_views(limit=10)
+```
+
+### Справочники
+
+```python
+# Все группы с цветами и префиксами — кэшируй на ~5 минут
+roles = client.get_roles()
+
+# Сколько стафф сейчас онлайн по группам
+counts = client.get_staff_counts()
+# {"HELPER": 158, "MODERATOR": 27, "TESTER": 28}
+```
+
+## Настройка клиента
+
+```python
+client = CristalixClient(
+    project_key="...",
+    token="...",
+    timeout=15.0,        # таймаут запроса в секундах
+    max_retries=3,       # повторов при 429
+    enforce_http2=True,  # упасть если сервер не HTTP/2
+)
+```
+
+## Обработка ошибок
+
+```python
+from cristalixapi import (
+    CristalixClient,
+    CristalixHTTPError,
+    CristalixRateLimitError,
+    CristalixValidationError,
+)
+
+try:
+    with CristalixClient(project_key="...", token="...") as client:
+        profile = client.get_profile_by_name("KoTuK_PvP")
+except CristalixValidationError as e:
+    print("Неверный параметр:", e)
+except CristalixRateLimitError as e:
+    print("Rate limit:", e.status_code)
+except CristalixHTTPError as e:
+    print(f"HTTP {e.status_code}:", e.payload)
+```
+
+| Исключение | Когда |
+|---|---|
+| `CristalixValidationError` | Неверные параметры на стороне клиента |
+| `CristalixRateLimitError` | 429 после всех повторов |
+| `CristalixHTTPError` | Любой другой 4xx/5xx |
+| `CristalixProtocolError` | Сервер ответил не по HTTP/2 |
+
+## Лимиты API
+
+- **320 запросов/мин** на проект (общий лимит).
+- **60 запросов/мин** для `search_players` — отдельный лимит, не расходует общий.
+- При 429 клиент автоматически делает повтор с экспоненциальной задержкой.
+
+## Приватность
+
+Если игрок скрыл данные, в ответе будет `privacyHidden: true`, а сами поля заменятся на `null`, `-1` или `[]`. Это нормальное поведение API — просто проверяй этот флаг перед отображением данных.
+
+## Что изменилось в v0.2.0
+
+- Новый base URL: `/v1/api/` вместо `/players/v1/` и `/statistics/v1/`
+- Авторизация: добавлен хедер `X-Project-Key`
+- Пагинация: `offset`/`limit` вместо `skip`/`limit`
+- Новые методы: `get_leaderboard_rich`, `get_player_periods`, `get_player_position`, `get_player_aggregated_stats`, `get_profiles_batch`, `get_profiles_batch_names`, `search_players`, `get_subscribers`, `get_name_history`, `get_location`, `get_reactions`, `get_ratings_*`, `get_roles`, `get_staff_counts`
+- Удалены устаревшие методы: `get_profiles_by_names/ids`, `get_profile_reactions`, `get_subscriptions`, `get_profile_activity_statistics`, `get_all_profile_statistics`, `games_list`, `read_by_time_rating`

cristalixapi-1.0.0/README.md

@@ -0,0 +1,205 @@
+# CristalixAPI
+
+Python-библиотека для работы с [Cristalix Public API](https://top.cristalix.gg/api-docs).
+
+Есть синхронный и асинхронный клиент, типизированные ответы и автоматические повторы при rate limit.
+
+## Установка
+
+```bash
+pip install cristalixapi
+```
+
+## Авторизация
+
+1. Войди на [top.cristalix.gg/api-docs](https://top.cristalix.gg/api-docs) через аккаунт Cristalix.
+2. Создай проект — получишь `project_key` и `project_token`.
+3. Токен показывается один раз. Если потерял — пересоздай через «Пересоздать токен».
+
+## Быстрый старт
+
+```python
+from cristalixapi import CristalixClient
+
+with CristalixClient(project_key="...", token="...") as client:
+    profile = client.get_profile_by_name("KoTuK_PvP")
+    print(profile["name"], profile["groups"])
+```
+
+## Асинхронный вариант
+
+```python
+import asyncio
+import httpx
+from cristalixapi import AsyncCristalixClient
+
+async def main():
+    limits = httpx.Limits(max_connections=50, max_keepalive_connections=10)
+    async with AsyncCristalixClient(project_key="...", token="...", limits=limits) as client:
+        profile = await client.get_profile_by_name("KoTuK_PvP")
+        print(profile)
+
+asyncio.run(main())
+```
+
+## Что умеет клиент
+
+### Игры
+
+```python
+# Список активных игр с режимами и полями статистики
+games = client.get_games()
+game_id = games[0]["gameId"]
+```
+
+### Лидерборды
+
+```python
+# Топ-10 по победам
+top = client.get_leaderboard(game_id, field="wins", limit=10)
+
+# Топ с динамикой (немного медленнее)
+top = client.get_leaderboard(game_id, field="wins", trends=True)
+
+# Топ с данными по всем периодам сразу
+rich = client.get_leaderboard_rich(game_id, field="wins", period="WEEK")
+```
+
+Периоды: `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`, `ALL`.
+
+### Статистика игрока
+
+```python
+# Статистика за конкретный период
+stats = client.get_player_stats(game_id, player_id, period="WEEK")
+print(stats["fields"])  # {"wins": 5, "kills": 15, ...}
+
+# Сразу все периоды
+periods = client.get_player_periods(game_id, player_id)
+print(periods["periods"]["ALL"])
+
+# Позиция в топе
+pos = client.get_player_position(game_id, player_id, field="wins")
+print(pos["position"])  # -1 если игрок не в рейтинге
+
+# Вся статистика по всем играм одним запросом
+all_stats = client.get_player_aggregated_stats(player_id)
+```
+
+### Профили
+
+```python
+# По UUID
+profile = client.get_profile_by_id("ea0a316c-...")
+
+# По нику
+profile = client.get_profile_by_name("KoTuK_PvP")
+
+# Много игроков сразу (до 200)
+batch = client.get_profiles_batch(["uuid1", "uuid2", "uuid3"])
+print(batch["found"], batch["notFound"])
+
+# То же самое по никам
+batch = client.get_profiles_batch_names(["KoTuK_PvP", "linkerii"])
+
+# Поиск по префиксу ника (автокомплит)
+results = client.search_players("Ko", limit=5)
+```
+
+Лёгкий режим `lite=True` возвращает только `playerId`, `name`, `status`, `groups` — удобно для списков.
+
+### Социальные данные
+
+```python
+# Друзья
+friends = client.get_friends(player_id, limit=50)
+
+# Подписчики (INCOMING) или подписки (OUTGOING)
+subs = client.get_subscribers(player_id, type="OUTGOING")
+
+# История смены ников
+history = client.get_name_history(player_id)
+
+# Текущий онлайн и реалм
+location = client.get_location(player_id)
+
+# Кто поставил лайк / дизлайк
+reactions = client.get_reactions(player_id, type="LIKE")
+```
+
+### Рейтинги
+
+```python
+top_karma = client.get_ratings_karma(limit=10)
+top_likes = client.get_ratings_likes(limit=10)
+top_views = client.get_ratings_views(limit=10)
+```
+
+### Справочники
+
+```python
+# Все группы с цветами и префиксами — кэшируй на ~5 минут
+roles = client.get_roles()
+
+# Сколько стафф сейчас онлайн по группам
+counts = client.get_staff_counts()
+# {"HELPER": 158, "MODERATOR": 27, "TESTER": 28}
+```
+
+## Настройка клиента
+
+```python
+client = CristalixClient(
+    project_key="...",
+    token="...",
+    timeout=15.0,        # таймаут запроса в секундах
+    max_retries=3,       # повторов при 429
+    enforce_http2=True,  # упасть если сервер не HTTP/2
+)
+```
+
+## Обработка ошибок
+
+```python
+from cristalixapi import (
+    CristalixClient,
+    CristalixHTTPError,
+    CristalixRateLimitError,
+    CristalixValidationError,
+)
+
+try:
+    with CristalixClient(project_key="...", token="...") as client:
+        profile = client.get_profile_by_name("KoTuK_PvP")
+except CristalixValidationError as e:
+    print("Неверный параметр:", e)
+except CristalixRateLimitError as e:
+    print("Rate limit:", e.status_code)
+except CristalixHTTPError as e:
+    print(f"HTTP {e.status_code}:", e.payload)
+```
+
+| Исключение | Когда |
+|---|---|
+| `CristalixValidationError` | Неверные параметры на стороне клиента |
+| `CristalixRateLimitError` | 429 после всех повторов |
+| `CristalixHTTPError` | Любой другой 4xx/5xx |
+| `CristalixProtocolError` | Сервер ответил не по HTTP/2 |
+
+## Лимиты API
+
+- **320 запросов/мин** на проект (общий лимит).
+- **60 запросов/мин** для `search_players` — отдельный лимит, не расходует общий.
+- При 429 клиент автоматически делает повтор с экспоненциальной задержкой.
+
+## Приватность
+
+Если игрок скрыл данные, в ответе будет `privacyHidden: true`, а сами поля заменятся на `null`, `-1` или `[]`. Это нормальное поведение API — просто проверяй этот флаг перед отображением данных.
+
+## Что изменилось в v0.2.0
+
+- Новый base URL: `/v1/api/` вместо `/players/v1/` и `/statistics/v1/`
+- Авторизация: добавлен хедер `X-Project-Key`
+- Пагинация: `offset`/`limit` вместо `skip`/`limit`
+- Новые методы: `get_leaderboard_rich`, `get_player_periods`, `get_player_position`, `get_player_aggregated_stats`, `get_profiles_batch`, `get_profiles_batch_names`, `search_players`, `get_subscribers`, `get_name_history`, `get_location`, `get_reactions`, `get_ratings_*`, `get_roles`, `get_staff_counts`
+- Удалены устаревшие методы: `get_profiles_by_names/ids`, `get_profile_reactions`, `get_subscriptions`, `get_profile_activity_statistics`, `get_all_profile_statistics`, `games_list`, `read_by_time_rating`

cristalixapi-1.0.0/cristalixapi/__init__.py

@@ -0,0 +1,20 @@
+from ._version import __version__
+from .client import AsyncCristalixClient, CristalixClient
+from .errors import (
+    CristalixError,
+    CristalixHTTPError,
+    CristalixProtocolError,
+    CristalixRateLimitError,
+    CristalixValidationError,
+)
+
+__all__ = [
+    "__version__",
+    "AsyncCristalixClient",
+    "CristalixClient",
+    "CristalixError",
+    "CristalixHTTPError",
+    "CristalixProtocolError",
+    "CristalixRateLimitError",
+    "CristalixValidationError",
+]

cristalixapi-1.0.0/cristalixapi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"