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.
@@ -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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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