karaca-connect-client 0.1.0a1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- karaca_connect_client/__init__.py +18 -0
- karaca_connect_client/client.py +204 -0
- karaca_connect_client/exceptions.py +29 -0
- karaca_connect_client/py.typed +0 -0
- karaca_connect_client-0.1.0a1.dist-info/METADATA +92 -0
- karaca_connect_client-0.1.0a1.dist-info/RECORD +9 -0
- karaca_connect_client-0.1.0a1.dist-info/WHEEL +5 -0
- karaca_connect_client-0.1.0a1.dist-info/licenses/LICENSE +21 -0
- karaca_connect_client-0.1.0a1.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"""Unofficial asynchronous Karaca Connect cloud API client."""
|
|
2
|
+
|
|
3
|
+
from .client import KaracaClient
|
|
4
|
+
from .exceptions import (
|
|
5
|
+
KaracaApiError,
|
|
6
|
+
KaracaAuthError,
|
|
7
|
+
KaracaConnectionError,
|
|
8
|
+
KaracaDeviceNotFound,
|
|
9
|
+
KaracaError,
|
|
10
|
+
KaracaRateLimitError,
|
|
11
|
+
KaracaServiceError,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
__all__ = [
|
|
15
|
+
"KaracaClient", "KaracaApiError", "KaracaAuthError",
|
|
16
|
+
"KaracaConnectionError", "KaracaDeviceNotFound", "KaracaError",
|
|
17
|
+
"KaracaRateLimitError", "KaracaServiceError",
|
|
18
|
+
]
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
"""Pre-release client adapted from the existing public integration's API shape.
|
|
2
|
+
|
|
3
|
+
No Karaca credentials or requests have been used to live-test this code.
|
|
4
|
+
Endpoint paths are reverse-engineered / undocumented and may change.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import asyncio
|
|
10
|
+
from collections.abc import Mapping
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
from aiohttp import ClientError, ClientSession, ClientTimeout
|
|
14
|
+
|
|
15
|
+
from .exceptions import (
|
|
16
|
+
KaracaApiError,
|
|
17
|
+
KaracaAuthError,
|
|
18
|
+
KaracaConnectionError,
|
|
19
|
+
KaracaDeviceNotFound,
|
|
20
|
+
KaracaRateLimitError,
|
|
21
|
+
KaracaServiceError,
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
DEFAULT_BASE_URL = "https://karacaconnectapi.krc.com.tr"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class KaracaClient:
|
|
28
|
+
"""Asynchronous cloud client. The caller owns the aiohttp session."""
|
|
29
|
+
|
|
30
|
+
def __init__(
|
|
31
|
+
self,
|
|
32
|
+
session: ClientSession,
|
|
33
|
+
*,
|
|
34
|
+
email: str,
|
|
35
|
+
password: str,
|
|
36
|
+
device_id: str | None = None,
|
|
37
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
38
|
+
timeout_seconds: float = 20.0,
|
|
39
|
+
) -> None:
|
|
40
|
+
if not email or not password:
|
|
41
|
+
raise ValueError("Email and password must be provided")
|
|
42
|
+
if timeout_seconds <= 0:
|
|
43
|
+
raise ValueError("timeout_seconds must be greater than zero")
|
|
44
|
+
self._session = session
|
|
45
|
+
self._email = email
|
|
46
|
+
self._password = password
|
|
47
|
+
self._device_id = str(device_id) if device_id else None
|
|
48
|
+
self._base_url = base_url.rstrip("/")
|
|
49
|
+
self._timeout = ClientTimeout(total=timeout_seconds)
|
|
50
|
+
self._token: str | None = None
|
|
51
|
+
self._auth_lock = asyncio.Lock()
|
|
52
|
+
|
|
53
|
+
@property
|
|
54
|
+
def device_id(self) -> str | None:
|
|
55
|
+
return self._device_id
|
|
56
|
+
|
|
57
|
+
async def _send(
|
|
58
|
+
self,
|
|
59
|
+
method: str,
|
|
60
|
+
path: str,
|
|
61
|
+
*,
|
|
62
|
+
payload: Mapping[str, Any] | None = None,
|
|
63
|
+
token: str | None = None,
|
|
64
|
+
) -> tuple[int, Mapping[str, Any]]:
|
|
65
|
+
headers = {
|
|
66
|
+
"Accept": "application/json",
|
|
67
|
+
"Content-Type": "application/json",
|
|
68
|
+
"User-Agent": "KaracaConnectClient/0.1.0a1",
|
|
69
|
+
}
|
|
70
|
+
if token:
|
|
71
|
+
headers["Authorization"] = f"Bearer {token}"
|
|
72
|
+
try:
|
|
73
|
+
async with self._session.request(
|
|
74
|
+
method,
|
|
75
|
+
f"{self._base_url}{path}",
|
|
76
|
+
headers=headers,
|
|
77
|
+
json=dict(payload) if payload is not None else None,
|
|
78
|
+
timeout=self._timeout,
|
|
79
|
+
) as response:
|
|
80
|
+
status = response.status
|
|
81
|
+
try:
|
|
82
|
+
data = await response.json(content_type=None)
|
|
83
|
+
except (ValueError, ClientError, TypeError) as exc:
|
|
84
|
+
# Error pages can be HTML or empty: retain the HTTP status
|
|
85
|
+
# so callers can distinguish auth, throttling and outages.
|
|
86
|
+
if status >= 400:
|
|
87
|
+
data = {}
|
|
88
|
+
else:
|
|
89
|
+
raise KaracaConnectionError("Invalid cloud API response") from exc
|
|
90
|
+
except (ClientError, TimeoutError, asyncio.TimeoutError) as exc:
|
|
91
|
+
raise KaracaConnectionError("Unable to reach Karaca cloud service") from exc
|
|
92
|
+
if not isinstance(data, Mapping):
|
|
93
|
+
if status >= 400:
|
|
94
|
+
data = {}
|
|
95
|
+
else:
|
|
96
|
+
raise KaracaConnectionError("Unexpected cloud API response type")
|
|
97
|
+
return status, data
|
|
98
|
+
|
|
99
|
+
@staticmethod
|
|
100
|
+
def _check(status: int, data: Mapping[str, Any]) -> None:
|
|
101
|
+
if status in (401, 403):
|
|
102
|
+
raise KaracaAuthError("Karaca authentication or authorization failed")
|
|
103
|
+
if status == 429:
|
|
104
|
+
raise KaracaRateLimitError("Karaca cloud rate limit reached")
|
|
105
|
+
if status >= 500:
|
|
106
|
+
raise KaracaServiceError("Karaca cloud service unavailable")
|
|
107
|
+
if not 200 <= status < 300 or data.get("succeeded") is False:
|
|
108
|
+
raise KaracaApiError("Karaca cloud request rejected")
|
|
109
|
+
|
|
110
|
+
async def login(self, *, force: bool = False) -> None:
|
|
111
|
+
async with self._auth_lock:
|
|
112
|
+
if self._token and not force:
|
|
113
|
+
return
|
|
114
|
+
status, data = await self._send(
|
|
115
|
+
"POST",
|
|
116
|
+
"/api/auth/signin",
|
|
117
|
+
payload={"email": self._email, "password": self._password},
|
|
118
|
+
)
|
|
119
|
+
# A service outage / throttle must not become "invalid password".
|
|
120
|
+
if status in (401, 403) or (
|
|
121
|
+
200 <= status < 300 and data.get("succeeded") is False
|
|
122
|
+
):
|
|
123
|
+
raise KaracaAuthError("Karaca credentials were rejected")
|
|
124
|
+
self._check(status, data)
|
|
125
|
+
payload = data.get("data")
|
|
126
|
+
token = payload.get("jwToken") if isinstance(payload, Mapping) else None
|
|
127
|
+
if not isinstance(token, str) or not token:
|
|
128
|
+
raise KaracaAuthError("Cloud response did not include a token")
|
|
129
|
+
self._token = token
|
|
130
|
+
|
|
131
|
+
async def _request(
|
|
132
|
+
self,
|
|
133
|
+
method: str,
|
|
134
|
+
path: str,
|
|
135
|
+
*,
|
|
136
|
+
payload: Mapping[str, Any] | None = None,
|
|
137
|
+
) -> Mapping[str, Any]:
|
|
138
|
+
await self.login()
|
|
139
|
+
token = self._token
|
|
140
|
+
status, data = await self._send(method, path, payload=payload, token=token)
|
|
141
|
+
if status == 401:
|
|
142
|
+
# Another coroutine may already have refreshed the expired token.
|
|
143
|
+
if self._token == token:
|
|
144
|
+
self._token = None
|
|
145
|
+
await self.login()
|
|
146
|
+
status, data = await self._send(
|
|
147
|
+
method, path, payload=payload, token=self._token
|
|
148
|
+
)
|
|
149
|
+
self._check(status, data)
|
|
150
|
+
return data
|
|
151
|
+
|
|
152
|
+
async def get_devices(self) -> list[dict[str, Any]]:
|
|
153
|
+
data = await self._request("GET", "/api/v1/devices/me")
|
|
154
|
+
devices = data.get("data")
|
|
155
|
+
if not isinstance(devices, list) or not all(isinstance(d, dict) for d in devices):
|
|
156
|
+
raise KaracaConnectionError("Malformed device list")
|
|
157
|
+
return devices
|
|
158
|
+
|
|
159
|
+
async def resolve_device_id(self) -> str:
|
|
160
|
+
if self._device_id:
|
|
161
|
+
return self._device_id
|
|
162
|
+
devices = await self.get_devices()
|
|
163
|
+
# Never guess which device to control from a multi-device account.
|
|
164
|
+
# The Home Assistant config flow selects and stores a device explicitly.
|
|
165
|
+
if len(devices) != 1 or not devices[0].get("id"):
|
|
166
|
+
raise KaracaDeviceNotFound(
|
|
167
|
+
"Select a device ID explicitly; automatic selection requires exactly one device"
|
|
168
|
+
)
|
|
169
|
+
self._device_id = str(devices[0]["id"])
|
|
170
|
+
return self._device_id
|
|
171
|
+
|
|
172
|
+
async def get_detail(self) -> dict[str, Any]:
|
|
173
|
+
device_id = await self.resolve_device_id()
|
|
174
|
+
response = await self._request("GET", f"/api/v1/devices/{device_id}")
|
|
175
|
+
data = response.get("data")
|
|
176
|
+
if not isinstance(data, dict):
|
|
177
|
+
raise KaracaConnectionError("Malformed device detail response")
|
|
178
|
+
return data
|
|
179
|
+
|
|
180
|
+
async def get_settings(self) -> list[dict[str, Any]]:
|
|
181
|
+
device_id = await self.resolve_device_id()
|
|
182
|
+
response = await self._request("GET", f"/api/v1/devices/{device_id}/settings")
|
|
183
|
+
data = response.get("data")
|
|
184
|
+
settings = data.get("notifications") if isinstance(data, dict) else None
|
|
185
|
+
if not isinstance(settings, list):
|
|
186
|
+
raise KaracaConnectionError("Malformed settings response")
|
|
187
|
+
return settings
|
|
188
|
+
|
|
189
|
+
async def set_mode(self, mode_id: int, active: bool = True) -> None:
|
|
190
|
+
device_id = await self.resolve_device_id()
|
|
191
|
+
await self._request(
|
|
192
|
+
"PUT", f"/api/v1/devices/{device_id}/modes/{mode_id}",
|
|
193
|
+
payload={"active": active},
|
|
194
|
+
)
|
|
195
|
+
|
|
196
|
+
async def set_setting(self, setting_id: int, value: bool) -> None:
|
|
197
|
+
device_id = await self.resolve_device_id()
|
|
198
|
+
path = f"/api/v1/devices/{device_id}/settings/{setting_id}"
|
|
199
|
+
try:
|
|
200
|
+
await self._request("PUT", path, payload={"value": value})
|
|
201
|
+
except KaracaApiError:
|
|
202
|
+
# Existing integration uses this fallback; compatibility must be
|
|
203
|
+
# confirmed against the live API before any public release.
|
|
204
|
+
await self._request("PUT", path, payload={"active": value})
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Public client exceptions. Never include credentials or response bodies."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class KaracaError(Exception):
|
|
5
|
+
"""Base error for Karaca cloud requests."""
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class KaracaAuthError(KaracaError):
|
|
9
|
+
"""Authentication failed or credentials need attention."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class KaracaConnectionError(KaracaError):
|
|
13
|
+
"""Connection or response format failed."""
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class KaracaServiceError(KaracaError):
|
|
17
|
+
"""The service is temporarily unavailable."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class KaracaRateLimitError(KaracaServiceError):
|
|
21
|
+
"""Cloud API request frequency was limited."""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class KaracaDeviceNotFound(KaracaError):
|
|
25
|
+
"""No matching device was found."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class KaracaApiError(KaracaError):
|
|
29
|
+
"""Cloud API rejected the request."""
|
|
File without changes
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: karaca-connect-client
|
|
3
|
+
Version: 0.1.0a1
|
|
4
|
+
Summary: Unofficial asynchronous client for the Karaca Connect cloud API
|
|
5
|
+
Author: AzadGLR
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Azadglr/karaca-connect-client
|
|
8
|
+
Project-URL: Repository, https://github.com/Azadglr/karaca-connect-client
|
|
9
|
+
Project-URL: Issues, https://github.com/Azadglr/karaca-connect-client/issues
|
|
10
|
+
Keywords: karaca,home-assistant,asyncio,tea-maker
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Framework :: AsyncIO
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Topic :: Home Automation
|
|
19
|
+
Requires-Python: >=3.12
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: aiohttp<4,>=3.9
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
# Karaca Connect Client
|
|
26
|
+
|
|
27
|
+
Unofficial asynchronous Python client for the Karaca Connect cloud service.
|
|
28
|
+
|
|
29
|
+
> **Alpha** — This library is extracted from the community Home Assistant integration at
|
|
30
|
+
> [Azadglr/karaca-connect-unofficial](https://github.com/Azadglr/karaca-connect-unofficial).
|
|
31
|
+
> It has been tested with simulated API responses but has **not yet been independently
|
|
32
|
+
> authenticated against the live Karaca service** in this extracted form.
|
|
33
|
+
|
|
34
|
+
This project is not affiliated with or endorsed by Karaca. The service API is not publicly documented;
|
|
35
|
+
its behavior and availability can change without notice. Currently the original community integration
|
|
36
|
+
reports verified support for the Karaca Çaysever Robotea Pro Connect 4in1 only.
|
|
37
|
+
|
|
38
|
+
## Installation
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
pip install karaca-connect-client
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Read-only example
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
import asyncio
|
|
48
|
+
import getpass
|
|
49
|
+
from aiohttp import ClientSession
|
|
50
|
+
from karaca_connect_client import KaracaClient
|
|
51
|
+
|
|
52
|
+
async def main():
|
|
53
|
+
email = input("Karaca Connect email: ")
|
|
54
|
+
password = getpass.getpass("Karaca Connect password: ")
|
|
55
|
+
async with ClientSession() as session:
|
|
56
|
+
client = KaracaClient(session, email=email, password=password)
|
|
57
|
+
devices = await client.get_devices()
|
|
58
|
+
for device in devices:
|
|
59
|
+
print(device.get("id"), device.get("label"))
|
|
60
|
+
# In multi-device accounts, pass device_id=... explicitly.
|
|
61
|
+
# No device mode or settings are changed by this example.
|
|
62
|
+
|
|
63
|
+
asyncio.run(main())
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The caller owns the `aiohttp.ClientSession` and is responsible for securing account credentials.
|
|
67
|
+
Please do not paste credentials, tokens, or device details into public issues.
|
|
68
|
+
|
|
69
|
+
## Functions
|
|
70
|
+
|
|
71
|
+
- Authenticate and renew tokens when the cloud API rejects expired authorization
|
|
72
|
+
- List devices, retrieve device details and notification settings
|
|
73
|
+
- Set device modes and notification settings (optional; supported capabilities may differ by model)
|
|
74
|
+
- Distinguish authentication, connectivity, rate-limit, cloud availability and API errors
|
|
75
|
+
- Refuse to silently select a device when more than one device is present
|
|
76
|
+
|
|
77
|
+
## Development
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
python -m pip install -e . pytest
|
|
81
|
+
python -m pytest tests
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Release policy
|
|
85
|
+
|
|
86
|
+
Source code and GitHub release tags are public. Publishing to PyPI is performed solely
|
|
87
|
+
by the `publish.yml` GitHub Actions workflow using PyPI Trusted Publishing. The version
|
|
88
|
+
in `pyproject.toml` must match the release tag without its leading `v`.
|
|
89
|
+
|
|
90
|
+
**Initial alpha release:** `v0.1.0a1`. No credentials or API tokens are stored in this repository.
|
|
91
|
+
|
|
92
|
+
License: MIT.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
karaca_connect_client/__init__.py,sha256=lK1AITEMtFGIlOBAx5_wydXsGCLphe_g65zzFUwKlbA,476
|
|
2
|
+
karaca_connect_client/client.py,sha256=SHWAaw7056mV3RsmuTswIBCF3Ke92hxsQDnuHpq3rns,8035
|
|
3
|
+
karaca_connect_client/exceptions.py,sha256=e3lMFg8OY8Hs9UCstj4lQPiKPWNYx6DPbhcz_ZwxoLE,705
|
|
4
|
+
karaca_connect_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
karaca_connect_client-0.1.0a1.dist-info/licenses/LICENSE,sha256=MAs-y6pDbCHyPv6DRQ8L4lTTRZ_3VovLiqjnEbFS7xU,1064
|
|
6
|
+
karaca_connect_client-0.1.0a1.dist-info/METADATA,sha256=uFdjuziL6d45eBe6Lkw2lFafn_XqvvxK4IT3v-5Hb5g,3496
|
|
7
|
+
karaca_connect_client-0.1.0a1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
8
|
+
karaca_connect_client-0.1.0a1.dist-info/top_level.txt,sha256=QopXZxuMIgGiBs8LuW_BvWGQQeKiIdpEBMbnx_kw5_E,22
|
|
9
|
+
karaca_connect_client-0.1.0a1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AzadGLR
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
karaca_connect_client
|