enderrealm-api-sdk 0.1.0__tar.gz

enderrealm_api_sdk-0.1.0/.gitignore

@@ -0,0 +1,85 @@
+# Compiled class file
+*.class
+
+# Log file
+*.log
+
+# BlueJ files
+*.ctxt
+
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+*.nar
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*
+replay_pid*
+
+# Gradle
+.gradle/
+build/
+!gradle/wrapper/gradle-wrapper.jar
+
+# IntelliJ IDEA
+.idea/
+*.iml
+*.iws
+*.ipr
+
+# Eclipse
+.classpath
+.project
+.settings/
+
+# VS Code
+.vscode/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+env/
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+
+# Environment variables (keep .env.example)
+.env
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Dev Server
+_server/
+_proxy/
+_login/
+
+# cloudflare
+.wrangler/
+
+# 生成的 OpenAPI 规范（CI 内生成，不提交）
+EnderRealmServerApi/openapi.json
+
+# 生成的 SDK 代码（CI 每次重新生成，不提交）
+sdks/python/enderrealm_api_sdk/
+sdks/typescript/src/api.ts
+
+# Node SDK
+sdks/typescript/node_modules/
+sdks/typescript/dist/

enderrealm_api_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: enderrealm-api-sdk
+Version: 0.1.0
+Summary: EnderRealm Server API Python SDK（由 OpenAPI 规范自动生成）
+Requires-Python: >=3.12
+Requires-Dist: attrs>=23.2.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typing-extensions>=4.9.0

enderrealm_api_sdk-0.1.0/README.md

@@ -0,0 +1,173 @@
+# enderrealm-api-sdk
+
+EnderRealm Server API 的官方 Python SDK。
+
+EnderRealm Server API 是 EnderRealm 服务器网络的后端服务，提供账号系统、i18n 国际化文本、服务器注册与心跳、在线状态、战斗配置、Stage/Lobby 匹配等能力。本 SDK 由 OpenAPI 规范自动生成，类型与后端接口一一对应。
+
+- 需要 **Python 3.12+**
+
+## 安装
+
+```bash
+pip install enderrealm-api-sdk
+# 或
+uv add enderrealm-api-sdk
+```
+
+## 快速开始
+
+只需两步：创建客户端（后端地址 + API Key），然后调用接口。
+
+```python
+from enderrealm_api_sdk.client import AuthenticatedClient
+
+# 1. 创建客户端（API Key 形如 er_xxx，从后端获取）
+client = AuthenticatedClient(
+    base_url="https://api.example.com",
+    token="er_xxxxxxxx",
+)
+
+# 2. 调用接口
+from enderrealm_api_sdk.api.i18n import get_i18n_full_v1_i18n_get
+
+texts = get_i18n_full_v1_i18n_get.sync(client=client)
+if texts is not None:
+    print(texts.timestamp)
+```
+
+## 认证
+
+- 除公开端点外的所有端点都需要 API Key。`AuthenticatedClient` 会在每次请求自动携带 `Authorization: Bearer <key>` 头。
+- 公开端点（`/v1/health/`、`/v1/environment/`）无需认证，用 `Client` 即可：
+
+```python
+from enderrealm_api_sdk.client import Client
+from enderrealm_api_sdk.api.health import health_check_v1_health_get
+
+health = health_check_v1_health_get.sync(client=Client(base_url="https://api.example.com"))
+print(health.status, health.database)
+```
+
+## 常用示例
+
+### 服务器管理
+
+```python
+from enderrealm_api_sdk.api.servers import (
+    list_servers_v1_servers_get,
+    register_server_v1_servers_register_post,
+)
+from enderrealm_api_sdk.models.server_register_request import ServerRegisterRequest
+
+# 查询在线服务器（可按类型筛选：login / mixed）
+servers = list_servers_v1_servers_get.sync(client=client, type_="mixed")
+if servers is not None:
+    for s in servers.servers:
+        print(s.server_id, s.host, s.port, s.online_players, "/", s.max_players)
+
+# 注册服务器
+result = register_server_v1_servers_register_post.sync(
+    client=client,
+    body=ServerRegisterRequest(
+        server_type="mixed",
+        host="10.0.0.1",
+        port=25565,
+        motd="EnderRealm 生存服",
+        max_players=100,
+    ),
+)
+print(result.server_id)  # 例如 server-1
+```
+
+### 账号登录
+
+```python
+from enderrealm_api_sdk.api.account import login_v1_account_login_post
+from enderrealm_api_sdk.models.login_request import LoginRequest
+
+result = login_v1_account_login_post.sync(
+    client=client,
+    body=LoginRequest(
+        ruid="je12345678",
+        password="******",
+        identifier="f3f1b8b2-...",  # UUID（Java）或 XUID（基岩版）
+        identifier_type="java",      # java / bedrock
+    ),
+)
+if result is not None and result.success:
+    print("登录成功")
+```
+
+### 路径参数
+
+```python
+from enderrealm_api_sdk.api.account import get_account_v1_account_ruid_get
+
+account = get_account_v1_account_ruid_get.sync(ruid="je12345678", client=client)
+if account is not None:
+    print(account.display_name, account.is_system_account)
+```
+
+### 异步调用
+
+所有接口都有对应的 `asyncio` 变体：
+
+```python
+import asyncio
+
+from enderrealm_api_sdk.api.i18n import get_i18n_full_v1_i18n_get
+
+
+async def main() -> None:
+    texts = await get_i18n_full_v1_i18n_get.asyncio(client=client)
+    print(texts.timestamp)
+
+
+asyncio.run(main())
+```
+
+## 错误处理
+
+- 后端声明的错误状态码（400/401/403/404/409/500/503）**不会抛异常**，而是作为返回值返回。返回类型为 `XxxResponse | ErrorResponse | None`，失败时为 `ErrorResponse`：
+
+```python
+from enderrealm_api_sdk.models.error_response import ErrorResponse
+
+resp = get_i18n_full_v1_i18n_get.sync(client=client)
+if isinstance(resp, ErrorResponse):
+    print("请求失败:", resp.detail)
+```
+
+- 请求参数校验失败（422）由 FastAPI 自动注入，返回的是独立的 `HTTPValidationError` 模型（结构为 `{"detail": [{"loc": [...], "msg": "...", "type": "..."}]}`），同样作为返回值返回：
+
+```python
+from enderrealm_api_sdk.api.account import login_v1_account_login_post
+from enderrealm_api_sdk.models.http_validation_error import HTTPValidationError
+from enderrealm_api_sdk.models.login_request import LoginRequest
+
+resp = login_v1_account_login_post.sync(
+    client=client,
+    body=LoginRequest(ruid="je12345678", password="******", identifier="uuid", identifier_type="java"),
+)
+if isinstance(resp, HTTPValidationError):
+    print("参数校验失败:", resp.detail)
+```
+
+- 未声明的状态码在 `Client(raise_on_unexpected_status=True)` 下会抛出 `enderrealm_api_sdk.errors.UnexpectedStatus`
+- 网络层异常直接抛 `httpx` 异常（`httpx.ConnectError`、`httpx.TimeoutException` 等）
+
+## 完整接口
+
+所有端点按模块组织在 `enderrealm_api_sdk.api` 下：
+
+| 模块 | 能力 |
+|------|------|
+| `api.account` | 账号注册/登录/登出/绑定/踢人 |
+| `api.i18n` | 国际化文本同步与管理 |
+| `api.servers` | 服务器注册/心跳/列表 |
+| `api.online` | 玩家在线状态 |
+| `api.combat` | 战斗配置 |
+| `api.keys` | API Key 管理 |
+| `api.stages` / `api.lobbies` | Stage / Lobby 实例与预约 |
+
+完整的接口与字段说明见 OpenAPI 规范（每个端点函数的 docstring 与类型注解即最新文档）。

enderrealm_api_sdk-0.1.0/enderrealm_api_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing EnderRealm Server API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

enderrealm_api_sdk-0.1.0/enderrealm_api_sdk/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

enderrealm_api_sdk-0.1.0/enderrealm_api_sdk/api/account/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

enderrealm_api_sdk-0.1.0/enderrealm_api_sdk/api/account/auto_login_bedrock_reactivate_v1_account_auto_bedrock_reactivate_post.py

@@ -0,0 +1,210 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.auto_login_request import AutoLoginRequest
+from ...models.auto_login_response import AutoLoginResponse
+from ...models.error_response import ErrorResponse
+from ...models.http_validation_error import HTTPValidationError
+from ...types import Response
+
+
+def _get_kwargs(
+    *,
+    body: AutoLoginRequest,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/v1/account/auto/bedrock/reactivate",
+    }
+
+    _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> AutoLoginResponse | ErrorResponse | HTTPValidationError | None:
+    if response.status_code == 200:
+        response_200 = AutoLoginResponse.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 400:
+        response_400 = ErrorResponse.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = ErrorResponse.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = ErrorResponse.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = ErrorResponse.from_dict(response.json())
+
+        return response_404
+
+    if response.status_code == 409:
+        response_409 = ErrorResponse.from_dict(response.json())
+
+        return response_409
+
+    if response.status_code == 422:
+        response_422 = HTTPValidationError.from_dict(response.json())
+
+        return response_422
+
+    if response.status_code == 500:
+        response_500 = ErrorResponse.from_dict(response.json())
+
+        return response_500
+
+    if response.status_code == 503:
+        response_503 = ErrorResponse.from_dict(response.json())
+
+        return response_503
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: AutoLoginRequest,
+) -> Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]:
+    """Auto Login Bedrock Reactivate
+
+     基岩版重新激活账号（用于 /login 无参数时）.
+
+    Args:
+        body (AutoLoginRequest): 自动登录请求.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+    body: AutoLoginRequest,
+) -> AutoLoginResponse | ErrorResponse | HTTPValidationError | None:
+    """Auto Login Bedrock Reactivate
+
+     基岩版重新激活账号（用于 /login 无参数时）.
+
+    Args:
+        body (AutoLoginRequest): 自动登录请求.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AutoLoginResponse | ErrorResponse | HTTPValidationError
+    """
+
+    return sync_detailed(
+        client=client,
+        body=body,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: AutoLoginRequest,
+) -> Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]:
+    """Auto Login Bedrock Reactivate
+
+     基岩版重新激活账号（用于 /login 无参数时）.
+
+    Args:
+        body (AutoLoginRequest): 自动登录请求.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+    body: AutoLoginRequest,
+) -> AutoLoginResponse | ErrorResponse | HTTPValidationError | None:
+    """Auto Login Bedrock Reactivate
+
+     基岩版重新激活账号（用于 /login 无参数时）.
+
+    Args:
+        body (AutoLoginRequest): 自动登录请求.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AutoLoginResponse | ErrorResponse | HTTPValidationError
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+            body=body,
+        )
+    ).parsed

enderrealm_api_sdk-0.1.0/enderrealm_api_sdk/api/account/auto_login_bedrock_v1_account_auto_bedrock_post.py

@@ -0,0 +1,210 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.auto_login_request import AutoLoginRequest
+from ...models.auto_login_response import AutoLoginResponse
+from ...models.error_response import ErrorResponse
+from ...models.http_validation_error import HTTPValidationError
+from ...types import Response
+
+
+def _get_kwargs(
+    *,
+    body: AutoLoginRequest,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/v1/account/auto/bedrock",
+    }
+
+    _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> AutoLoginResponse | ErrorResponse | HTTPValidationError | None:
+    if response.status_code == 200:
+        response_200 = AutoLoginResponse.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 400:
+        response_400 = ErrorResponse.from_dict(response.json())
+
+        return response_400
+
+    if response.status_code == 401:
+        response_401 = ErrorResponse.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = ErrorResponse.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = ErrorResponse.from_dict(response.json())
+
+        return response_404
+
+    if response.status_code == 409:
+        response_409 = ErrorResponse.from_dict(response.json())
+
+        return response_409
+
+    if response.status_code == 422:
+        response_422 = HTTPValidationError.from_dict(response.json())
+
+        return response_422
+
+    if response.status_code == 500:
+        response_500 = ErrorResponse.from_dict(response.json())
+
+        return response_500
+
+    if response.status_code == 503:
+        response_503 = ErrorResponse.from_dict(response.json())
+
+        return response_503
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: AutoLoginRequest,
+) -> Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]:
+    """Auto Login Bedrock
+
+     基岩版自动登录（只读检查，不修改状态）.
+
+    Args:
+        body (AutoLoginRequest): 自动登录请求.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+    body: AutoLoginRequest,
+) -> AutoLoginResponse | ErrorResponse | HTTPValidationError | None:
+    """Auto Login Bedrock
+
+     基岩版自动登录（只读检查，不修改状态）.
+
+    Args:
+        body (AutoLoginRequest): 自动登录请求.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AutoLoginResponse | ErrorResponse | HTTPValidationError
+    """
+
+    return sync_detailed(
+        client=client,
+        body=body,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: AutoLoginRequest,
+) -> Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]:
+    """Auto Login Bedrock
+
+     基岩版自动登录（只读检查，不修改状态）.
+
+    Args:
+        body (AutoLoginRequest): 自动登录请求.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AutoLoginResponse | ErrorResponse | HTTPValidationError]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+    body: AutoLoginRequest,
+) -> AutoLoginResponse | ErrorResponse | HTTPValidationError | None:
+    """Auto Login Bedrock
+
+     基岩版自动登录（只读检查，不修改状态）.
+
+    Args:
+        body (AutoLoginRequest): 自动登录请求.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AutoLoginResponse | ErrorResponse | HTTPValidationError
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+            body=body,
+        )
+    ).parsed