python-spfm 0.1.0__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,79 @@
1
+ Metadata-Version: 2.4
2
+ Name: python-spfm
3
+ Version: 0.1.0
4
+ Summary: Asynchronous Python client for the Sunway Property Facility Management (SPFM) Selfcare portal
5
+ Author: Zubir Jamal
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/zubirjamal/python-spfm
8
+ Project-URL: Repository, https://github.com/zubirjamal/python-spfm
9
+ Project-URL: Issues, https://github.com/zubirjamal/python-spfm/issues
10
+ Keywords: spfm,sunway,property,facility-management,selfcare,malaysia,home-assistant
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Programming Language :: Python :: 3.14
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Topic :: Home Automation
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Intended Audience :: Developers
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: aiohttp>=3.9.0
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest>=8.0.0; extra == "test"
27
+ Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
28
+ Dynamic: license-file
29
+
30
+ # python-spfm
31
+
32
+ Asynchronous Python client library for the Sunway Property Facility Management (SPFM) Selfcare portal (`spfm.com.my`).
33
+
34
+ Used by the Home Assistant SPFM integration to query units, billing, outstanding balances, invoices, payment history, visitor management, and project announcements.
35
+
36
+ ## Features
37
+
38
+ - **Asynchronous**: Built on `aiohttp` for non-blocking I/O.
39
+ - **Full Selfcare Suite**:
40
+ - Discover member units, projects, and management companies.
41
+ - Fetch account balances, billing statements, and outstanding invoices.
42
+ - Download official invoices, receipts, and credit/debit note PDFs.
43
+ - Retrieve project announcements, attachments, and resident notices.
44
+ - Visitor pass and appointment management (guest registration, pending visitor approval/rejection).
45
+ - **Resilient**: Includes bounded retry with exponential backoff and jitter for transient 5xx errors and connection dropouts.
46
+
47
+ ## Installation
48
+
49
+ ```bash
50
+ pip install python-spfm
51
+ ```
52
+
53
+ ## Quick Start
54
+
55
+ ```python
56
+ import asyncio
57
+ import aiohttp
58
+ from spfm import SPFMClient
59
+
60
+ async def main():
61
+ async with aiohttp.ClientSession() as session:
62
+ client = SPFMClient(session, "username@example.com", "your_password")
63
+ await client.login()
64
+ units = await client.get_units()
65
+ for unit in units:
66
+ print(f"Unit: {unit.label} (ID: {unit.unit_id})")
67
+
68
+ asyncio.run(main())
69
+ ```
70
+
71
+ ## CLI Usage
72
+
73
+ ```bash
74
+ spfm -u username@example.com -p your_password
75
+ ```
76
+
77
+ ## License
78
+
79
+ MIT
@@ -0,0 +1,13 @@
1
+ python_spfm-0.1.0.dist-info/licenses/LICENSE,sha256=CV9UcjHZBMuVjUPCSgOJpqCp8L0ekkcK1UAomLpdW9Y,1068
2
+ spfm/__init__.py,sha256=OeXiEyHHy_QOuKvVE4qln5sI35tWqkdiGtIWoRtu9rI,1073
3
+ spfm/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
4
+ spfm/cli.py,sha256=0mgxK0wivzjUsUd7maboa6JpjoGSI7ZCQr3NLsZvuwI,1211
5
+ spfm/client.py,sha256=Z7w-BEQFNCxEtbWESGR7ftQRpNOlQ39n2eFA1YUs9kg,17250
6
+ spfm/exceptions.py,sha256=jI-mEe1yDdw2iPOthNV6C8oYYtF-reXXRe5ARJhu_eY,599
7
+ spfm/parsing.py,sha256=936Au34V4PGx9y3jfGcl29P3PkGnQdTbxBXyqIfdfwE,16216
8
+ spfm/retry.py,sha256=D4ajQadA5SMI1_yCofwqKOz-7UMUZ-PKaqgZtDZIvS4,3469
9
+ python_spfm-0.1.0.dist-info/METADATA,sha256=zX-xkpxMYk1-LYZEvZt1p8hegYXyT7YOBRbNZo3-gMo,2711
10
+ python_spfm-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
11
+ python_spfm-0.1.0.dist-info/entry_points.txt,sha256=f_RVRFeoGSfFVszEQiAO_LSmFiFqumc9inaIgTM8Xig,39
12
+ python_spfm-0.1.0.dist-info/top_level.txt,sha256=VdYF09NxPExlU1h_pKDZhrc7cohosXf-eLWIbjSWoho,5
13
+ python_spfm-0.1.0.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,2 @@
1
+ [console_scripts]
2
+ spfm = spfm.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zubir Jamal
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
+ spfm
spfm/__init__.py ADDED
@@ -0,0 +1,52 @@
1
+ """Asynchronous Python client for SPFM Selfcare portal."""
2
+ from __future__ import annotations
3
+
4
+ from .client import (
5
+ DOCUMENT_PATHS,
6
+ SPFMClient,
7
+ SPFMUnit,
8
+ )
9
+ from .exceptions import (
10
+ SPFMApiError,
11
+ SPFMAuthError,
12
+ SPFMConnectionError,
13
+ SPFMError,
14
+ SPFMTwoFactorRequired,
15
+ )
16
+ from .parsing import (
17
+ MYT,
18
+ announcement_feed,
19
+ group_outstanding,
20
+ html_to_text,
21
+ merge_announcements,
22
+ notification_title,
23
+ parse_portal_datetime,
24
+ summarize,
25
+ summarize_announcements,
26
+ summarize_notifications,
27
+ summarize_visitors,
28
+ )
29
+ from .retry import with_retry
30
+
31
+ __all__ = [
32
+ "DOCUMENT_PATHS",
33
+ "MYT",
34
+ "SPFMApiError",
35
+ "SPFMAuthError",
36
+ "SPFMClient",
37
+ "SPFMConnectionError",
38
+ "SPFMError",
39
+ "SPFMTwoFactorRequired",
40
+ "SPFMUnit",
41
+ "announcement_feed",
42
+ "group_outstanding",
43
+ "html_to_text",
44
+ "merge_announcements",
45
+ "notification_title",
46
+ "parse_portal_datetime",
47
+ "summarize",
48
+ "summarize_announcements",
49
+ "summarize_notifications",
50
+ "summarize_visitors",
51
+ "with_retry",
52
+ ]
spfm/__main__.py ADDED
@@ -0,0 +1,4 @@
1
+ from .cli import main
2
+
3
+ if __name__ == "__main__":
4
+ main()
spfm/cli.py ADDED
@@ -0,0 +1,41 @@
1
+ """CLI entrypoint for testing SPFM connectivity."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import asyncio
6
+ import json
7
+ import sys
8
+
9
+ import aiohttp
10
+
11
+ from .client import SPFMClient
12
+ from .exceptions import SPFMError
13
+
14
+
15
+ async def _run(args: argparse.Namespace) -> int:
16
+ async with aiohttp.ClientSession() as session:
17
+ client = SPFMClient(session, args.username, args.password)
18
+ try:
19
+ print("Authenticating...")
20
+ await client.login()
21
+ print("Authentication successful.")
22
+ units = await client.get_units()
23
+ print(f"Discovered {len(units)} units:")
24
+ for u in units:
25
+ print(f" - [{u.unit_id}] {u.label}")
26
+ return 0
27
+ except SPFMError as err:
28
+ print(f"Error: {err}", file=sys.stderr)
29
+ return 1
30
+
31
+
32
+ def main() -> None:
33
+ parser = argparse.ArgumentParser(description="SPFM Selfcare CLI")
34
+ parser.add_argument("-u", "--username", required=True, help="SPFM account username")
35
+ parser.add_argument("-p", "--password", required=True, help="SPFM account password")
36
+ args = parser.parse_args()
37
+ sys.exit(asyncio.run(_run(args)))
38
+
39
+
40
+ if __name__ == "__main__":
41
+ main()
spfm/client.py ADDED
@@ -0,0 +1,420 @@
1
+ from __future__ import annotations
2
+
3
+ from .exceptions import (
4
+ SPFMError,
5
+ SPFMAuthError,
6
+ SPFMTwoFactorRequired,
7
+ SPFMConnectionError,
8
+ SPFMApiError,
9
+ )
10
+ """Minimal async client for the SPFM (Sunway Property Facility Management) selfcare portal.
11
+
12
+ The portal at https://spfm.com.my/prod/ is a Vue SPA backed by a Laravel API
13
+ under https://spfm.com.my/service. Authentication is a Laravel Passport
14
+ "password" grant using the public client credentials shipped in the SPA bundle,
15
+ with ``provider=members`` for owner/resident (selfcare) accounts.
16
+
17
+ This module has no Home Assistant imports so it can be tested standalone.
18
+ """
19
+
20
+
21
+ import asyncio
22
+ import logging
23
+ import re
24
+ from dataclasses import dataclass
25
+ from typing import Any
26
+
27
+ import aiohttp
28
+
29
+ _LOGGER = logging.getLogger(__name__)
30
+
31
+ PORTAL_BASE = "https://spfm.com.my/prod"
32
+ SERVICE_BASE = "https://spfm.com.my/service"
33
+ API_BASE = f"{SERVICE_BASE}/api"
34
+
35
+ # Public Passport client used by the SPFM web app (visible in its JS bundle).
36
+ CLIENT_ID = "2"
37
+ CLIENT_SECRET = "OiyeoNx5slPvbtYjwqV0R3i91VtTPjXrI1aXTGcv"
38
+ PROVIDER = "members"
39
+
40
+ DEFAULT_TIMEOUT = aiohttp.ClientTimeout(total=45)
41
+ USER_AGENT = "HomeAssistant-SPFM/0.1 (+https://github.com/zubir2k/homeassistant-spfm)"
42
+
43
+
44
+ DOCUMENT_PATHS = {
45
+ "BILL": "selfcare/billing/download-invoice",
46
+ "RECEIPT": "selfcare/billing/download-receipt",
47
+ "CN": "selfcare/billing/download-crnote",
48
+ "DN": "selfcare/billing/download-dbnote",
49
+ }
50
+
51
+
52
+ @dataclass(frozen=True, slots=True)
53
+ class SPFMUnit:
54
+ """A unit the member owns or occupies."""
55
+
56
+ unit_id: int
57
+ unit_no: str
58
+ project_id: int
59
+ company_id: int
60
+ project_name: str = ""
61
+ company_name: str = ""
62
+
63
+ @property
64
+ def key(self) -> str:
65
+ return str(self.unit_id)
66
+
67
+ @property
68
+ def label(self) -> str:
69
+ return f"{self.unit_no} · {self.project_name}".strip(" ·")
70
+
71
+ def as_dict(self) -> dict[str, Any]:
72
+ return {
73
+ "unit_id": self.unit_id,
74
+ "unit_no": self.unit_no,
75
+ "project_id": self.project_id,
76
+ "company_id": self.company_id,
77
+ "project_name": self.project_name,
78
+ "company_name": self.company_name,
79
+ }
80
+
81
+ @classmethod
82
+ def from_dict(cls, data: dict[str, Any]) -> SPFMUnit:
83
+ return cls(
84
+ unit_id=int(data["unit_id"]),
85
+ unit_no=str(data.get("unit_no", "")),
86
+ project_id=int(data["project_id"]),
87
+ company_id=int(data["company_id"]),
88
+ project_name=str(data.get("project_name", "")),
89
+ company_name=str(data.get("company_name", "")),
90
+ )
91
+
92
+
93
+ class SPFMClient:
94
+ """Async client. Pass an aiohttp session (HA's shared one in production)."""
95
+
96
+ def __init__(
97
+ self,
98
+ session: aiohttp.ClientSession,
99
+ username: str,
100
+ password: str,
101
+ *,
102
+ access_token: str | None = None,
103
+ ) -> None:
104
+ self._session = session
105
+ self._username = username
106
+ self._password = password
107
+ self._token = access_token
108
+ self._login_lock = asyncio.Lock()
109
+
110
+ @property
111
+ def username(self) -> str:
112
+ return self._username
113
+
114
+ @property
115
+ def access_token(self) -> str | None:
116
+ return self._token
117
+
118
+ # ------------------------------------------------------------------ auth
119
+ async def login(self) -> str:
120
+ """Run the Passport password grant and store the bearer token."""
121
+ payload = {
122
+ "grant_type": "password",
123
+ "client_id": CLIENT_ID,
124
+ "client_secret": CLIENT_SECRET,
125
+ "scope": "*",
126
+ "username": self._username,
127
+ "password": self._password,
128
+ "provider": PROVIDER,
129
+ }
130
+ try:
131
+ async with self._session.post(
132
+ f"{SERVICE_BASE}/oauth/token",
133
+ json=payload,
134
+ headers={"Accept": "application/json", "User-Agent": USER_AGENT},
135
+ timeout=DEFAULT_TIMEOUT,
136
+ ) as resp:
137
+ body = await _json_or_text(resp)
138
+ if resp.status in (400, 401):
139
+ raise SPFMAuthError(_message(body) or "Invalid credentials")
140
+ if resp.status >= 500:
141
+ raise SPFMConnectionError(f"Login HTTP {resp.status}")
142
+ if resp.status != 200 or not isinstance(body, dict):
143
+ raise SPFMApiError(f"Login HTTP {resp.status}: {body!r:.200}")
144
+ except (aiohttp.ClientError, asyncio.TimeoutError) as err:
145
+ raise SPFMConnectionError(f"Login failed: {err}") from err
146
+
147
+ token = body.get("access_token")
148
+ if not token:
149
+ raise SPFMApiError("Login response had no access_token")
150
+ self._token = token
151
+
152
+ # The SPA only asks for an OTP when the token says 2fa AND the member has it on
153
+ # (or the server forces it). We cannot complete an OTP headlessly.
154
+ if body.get("2fa") and (body.get("force_2fa") is True):
155
+ raise SPFMTwoFactorRequired("This SPFM account requires an OTP")
156
+ if body.get("2fa"):
157
+ account = await self.get_account()
158
+ if int(account.get("enable2fa") or 0) == 1:
159
+ raise SPFMTwoFactorRequired("This SPFM account has 2FA enabled")
160
+ return token
161
+
162
+ # --------------------------------------------------------------- request
163
+ async def _get(self, path: str, params: dict[str, Any] | None = None, *, base: str = API_BASE) -> Any:
164
+ return await self._request("GET", path, params=params, base=base)
165
+
166
+ async def _put(self, path: str, payload: dict[str, Any], *, base: str = API_BASE) -> Any:
167
+ return await self._request("PUT", path, json=payload, base=base)
168
+
169
+ async def _request(
170
+ self,
171
+ method: str,
172
+ path: str,
173
+ *,
174
+ params: dict[str, Any] | None = None,
175
+ json: dict[str, Any] | None = None,
176
+ base: str = API_BASE,
177
+ ) -> Any:
178
+ if not self._token:
179
+ async with self._login_lock:
180
+ if not self._token:
181
+ await self.login()
182
+ for attempt in (1, 2):
183
+ used_token = self._token
184
+ try:
185
+ async with self._session.request(
186
+ method,
187
+ f"{base}/{path.lstrip('/')}",
188
+ params={k: v for k, v in (params or {}).items() if v is not None} or None,
189
+ json=json,
190
+ headers={
191
+ "Accept": "application/json",
192
+ "Authorization": f"Bearer {used_token}",
193
+ "User-Agent": USER_AGENT,
194
+ },
195
+ timeout=DEFAULT_TIMEOUT,
196
+ ) as resp:
197
+ body = await _json_or_text(resp)
198
+ if resp.status == 401 and attempt == 1:
199
+ _LOGGER.debug("SPFM token rejected, logging in again")
200
+ async with self._login_lock:
201
+ if self._token == used_token:
202
+ await self.login()
203
+ continue
204
+ if resp.status == 401:
205
+ raise SPFMAuthError("Session rejected after re-login")
206
+ if resp.status >= 500:
207
+ raise SPFMConnectionError(f"{method} {path} HTTP {resp.status}")
208
+ if resp.status not in (200, 201):
209
+ raise SPFMApiError(f"{method} {path} HTTP {resp.status}: {_message(body)}")
210
+ return body
211
+ except (aiohttp.ClientError, asyncio.TimeoutError) as err:
212
+ raise SPFMConnectionError(f"{method} {path} failed: {err}") from err
213
+ raise SPFMApiError("unreachable")
214
+
215
+ # ------------------------------------------------------------- endpoints
216
+ async def get_account(self) -> dict[str, Any]:
217
+ body = await self._get("api/selfcare/my-account", base=SERVICE_BASE)
218
+ return (body or {}).get("data") or {}
219
+
220
+ async def get_units(self) -> list[SPFMUnit]:
221
+ """Discover every unit linked to this member, with project/company names."""
222
+ units_b, projects_b, companies_b = await asyncio.gather(
223
+ self._get("selfcare/my-unit"),
224
+ self._get("selfcare/my-project", {"type": ""}),
225
+ self._get("selfcare/my-company", {"type": ""}),
226
+ )
227
+ projects = {p["id"]: p for p in (projects_b or {}).get("data") or []}
228
+ companies = {c["id"]: c for c in (companies_b or {}).get("data") or []}
229
+ units: list[SPFMUnit] = []
230
+ for u in (units_b or {}).get("data") or []:
231
+ proj = projects.get(u.get("project_id"), {})
232
+ units.append(
233
+ SPFMUnit(
234
+ unit_id=int(u["id"]),
235
+ unit_no=str(u.get("unit_no", "")),
236
+ project_id=int(u["project_id"]),
237
+ company_id=int(u["company_id"]),
238
+ project_name=str(proj.get("name", "")),
239
+ company_name=str(
240
+ proj.get("company_name")
241
+ or companies.get(u.get("company_id"), {}).get("name", "")
242
+ ),
243
+ )
244
+ )
245
+ return units
246
+
247
+ def _unit_params(self, unit: SPFMUnit) -> dict[str, Any]:
248
+ return {
249
+ "project_id": unit.project_id,
250
+ "company_id": unit.company_id,
251
+ "my_username": self._username,
252
+ "my_unit_id": unit.unit_id,
253
+ }
254
+
255
+ async def get_billing_and_payment(self, unit: SPFMUnit, rows: int = 200) -> list[dict[str, Any]]:
256
+ """Statement lines: BILL (per charge item), RECEIPT, DN, CN, newest first."""
257
+ body = await self._get(
258
+ "selfcare/billing/billing-and-payment",
259
+ {**self._unit_params(unit), "page": 1, "rows_per_page": rows, "descending": "true"},
260
+ )
261
+ return list((body or {}).get("data") or [])
262
+
263
+ async def get_outstanding(self, unit: SPFMUnit) -> list[dict[str, Any]]:
264
+ """Unpaid items (empty list when fully paid)."""
265
+ body = await self._get(
266
+ "selfcare/billing/outstanding",
267
+ {**self._unit_params(unit), "page": 1, "rows_per_page": 999, "cleared": 0},
268
+ )
269
+ data = (body or {}).get("data") or {}
270
+ if isinstance(data, dict):
271
+ return list(data.get("data") or [])
272
+ return list(data)
273
+
274
+ async def download_document(self, unit: SPFMUnit, doc_type: str, record_id: int | str) -> tuple[bytes, str, str | None]:
275
+ """PDF for a statement line, as the portal's Print button fetches it.
276
+
277
+ Returns (body, content_type, filename). Needs the bearer token, so Home
278
+ Assistant proxies it rather than linking to SPFM directly.
279
+ """
280
+ path = DOCUMENT_PATHS.get(str(doc_type).upper())
281
+ if path is None:
282
+ raise SPFMApiError(f"No document for type {doc_type!r}")
283
+ if not self._token:
284
+ async with self._login_lock:
285
+ if not self._token:
286
+ await self.login()
287
+ for attempt in (1, 2):
288
+ used_token = self._token
289
+ try:
290
+ async with self._session.get(
291
+ f"{API_BASE}/{path}/{record_id}",
292
+ params=self._unit_params(unit),
293
+ headers={"Authorization": f"Bearer {used_token}", "User-Agent": USER_AGENT},
294
+ timeout=aiohttp.ClientTimeout(total=60),
295
+ ) as resp:
296
+ if resp.status == 401 and attempt == 1:
297
+ async with self._login_lock:
298
+ if self._token == used_token:
299
+ await self.login()
300
+ continue
301
+ if resp.status == 401:
302
+ raise SPFMAuthError("Session rejected after re-login")
303
+ if resp.status != 200:
304
+ raise SPFMApiError(f"Document HTTP {resp.status}")
305
+ disp = resp.headers.get("Content-Disposition", "")
306
+ m = re.search(r'filename="?([^";]+)"?', disp)
307
+ return await resp.read(), resp.content_type or "application/pdf", m.group(1) if m else None
308
+ except (aiohttp.ClientError, asyncio.TimeoutError) as err:
309
+ raise SPFMConnectionError(f"Document download failed: {err}") from err
310
+ raise SPFMApiError("unreachable")
311
+
312
+ async def get_announcements(self, unit: SPFMUnit, max_pages: int = 5) -> list[dict[str, Any]]:
313
+ """Announcements visible to this unit (title, start/end date, HTML message, attachments).
314
+
315
+ The endpoint is paginated server-side at 10 per page and ignores
316
+ ``rows_per_page``, so walk ``meta.last_page`` (capped) and de-duplicate.
317
+ """
318
+ items: list[dict[str, Any]] = []
319
+ seen: set[Any] = set()
320
+ page = 1
321
+ while page <= max_pages:
322
+ body = await self._get(
323
+ "selfcare/announcement",
324
+ {
325
+ "project_id": unit.project_id,
326
+ "company_id": unit.company_id,
327
+ "username": self._username,
328
+ "unit_id": unit.unit_id,
329
+ "page": page,
330
+ "rows_per_page": 50,
331
+ "per_page": 50,
332
+ "descending": "true",
333
+ },
334
+ )
335
+ rows = list((body or {}).get("data") or []) if isinstance(body, dict) else []
336
+ for row in rows:
337
+ if row.get("id") not in seen:
338
+ seen.add(row.get("id"))
339
+ items.append(row)
340
+ meta = (body or {}).get("meta") or {} if isinstance(body, dict) else {}
341
+ try:
342
+ last = int(meta.get("last_page") or 1)
343
+ except (TypeError, ValueError):
344
+ last = 1
345
+ if not rows or page >= last:
346
+ break
347
+ page += 1
348
+ return items
349
+
350
+ def _member_params(self, unit: SPFMUnit) -> dict[str, Any]:
351
+ return {
352
+ "project_id": unit.project_id,
353
+ "company_id": unit.company_id,
354
+ "unit_id": unit.unit_id,
355
+ "username": self._username,
356
+ }
357
+
358
+ async def get_dashboard_announcements(self, unit: SPFMUnit) -> list[dict[str, Any]]:
359
+ """Mobile-app feed: every notice for the project incl. expired ones (no attachments)."""
360
+ body = await self._get(
361
+ "selfcare/dashboard/announcement/",
362
+ {**self._member_params(unit), "filter": "start_date", "sort_by": "start_date", "descending": "true"},
363
+ )
364
+ return list((body or {}).get("data") or []) if isinstance(body, dict) else []
365
+
366
+ async def get_notifications(self, unit: SPFMUnit, member_id: int | str, rows: int = 30) -> list[dict[str, Any]]:
367
+ """The app's Notifications tab (the same items the SPFM push sends).
368
+
369
+ Items: id, module (ANNOUNCEMENT, OWNER_MANUAL, FORM, BOOKING, ...),
370
+ object_id (id of the announcement/form/...), message, created_at.
371
+ """
372
+ body = await self._get(
373
+ "selfcare/selfcare-notification",
374
+ {
375
+ **self._member_params(unit),
376
+ "user_id": member_id,
377
+ "rows_per_page": str(rows),
378
+ "sort_by": "created_at",
379
+ "descending": "true",
380
+ },
381
+ )
382
+ return list((body or {}).get("data") or []) if isinstance(body, dict) else []
383
+
384
+ async def get_appointments(self, unit: SPFMUnit) -> list[dict[str, Any]]:
385
+ """Visitor appointments registered for the unit (guests, contractors, deliveries)."""
386
+ body = await self._get(
387
+ "selfcare/appointment/",
388
+ {**self._member_params(unit), "sort_by": "datetime", "descending": "true"},
389
+ )
390
+ return list((body or {}).get("data") or []) if isinstance(body, dict) else []
391
+
392
+ async def get_pending_visitors(self, unit: SPFMUnit) -> list[dict[str, Any]]:
393
+ """Walk-in visitors waiting at the guardhouse for the resident's approval."""
394
+ body = await self._get("selfcare/appointment-guest-pending", {**self._member_params(unit), "descending": "true"})
395
+ return list((body or {}).get("data") or []) if isinstance(body, dict) else []
396
+
397
+ async def respond_pending_visitor(self, unit: SPFMUnit, visitor_id: int | str, approve: bool) -> Any:
398
+ """Approve or reject a pending walk-in visitor (same call the app makes)."""
399
+ action = "approve" if approve else "reject"
400
+ return await self._put(
401
+ f"selfcare/appointment/appointment-guest-pending/{visitor_id}/{action}",
402
+ self._member_params(unit),
403
+ )
404
+
405
+ async def get_recurring_payment(self, unit: SPFMUnit) -> list[dict[str, Any]]:
406
+ body = await self._get("selfcare/billing/recurring-payment", self._unit_params(unit))
407
+ return list((body or {}).get("data") or [])
408
+
409
+
410
+ async def _json_or_text(resp: aiohttp.ClientResponse) -> Any:
411
+ try:
412
+ return await resp.json(content_type=None)
413
+ except (aiohttp.ContentTypeError, ValueError):
414
+ return await resp.text()
415
+
416
+
417
+ def _message(body: Any) -> str:
418
+ if isinstance(body, dict):
419
+ return str(body.get("message") or body.get("error_description") or body.get("error") or "")
420
+ return str(body)[:200]
spfm/exceptions.py ADDED
@@ -0,0 +1,26 @@
1
+ """Exceptions for the SPFM client library."""
2
+ from __future__ import annotations
3
+
4
+
5
+ class SPFMError(Exception):
6
+ """Base error for SPFM operations."""
7
+
8
+ retryable = False
9
+
10
+
11
+ class SPFMAuthError(SPFMError):
12
+ """Credentials rejected or session cannot be re-established."""
13
+
14
+
15
+ class SPFMTwoFactorRequired(SPFMAuthError):
16
+ """Account has 2FA (OTP) enabled; not supported headlessly."""
17
+
18
+
19
+ class SPFMConnectionError(SPFMError):
20
+ """Network problem or 5xx from the portal (safe to retry)."""
21
+
22
+ retryable = True
23
+
24
+
25
+ class SPFMApiError(SPFMError):
26
+ """Unexpected 4xx or malformed payload."""
spfm/parsing.py ADDED
@@ -0,0 +1,394 @@
1
+ """Turn raw SPFM statement lines into a per-unit summary (no HA imports)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import date, datetime, timedelta, timezone
6
+ from typing import Any
7
+ from zoneinfo import ZoneInfo
8
+
9
+ # Portal timestamps are midnights in Malaysia time (UTC+8).
10
+ try:
11
+ MYT = ZoneInfo("Asia/Kuala_Lumpur")
12
+ except Exception:
13
+ MYT = timezone(timedelta(hours=8))
14
+
15
+ TYPE_BILL = "BILL"
16
+ TYPE_RECEIPT = "RECEIPT"
17
+ TYPE_DEBIT_NOTE = "DN"
18
+ TYPE_CREDIT_NOTE = "CN"
19
+
20
+ CHARGE_SERVICE = "IVSC" # service / maintenance charge
21
+ CHARGE_SINKING = "IVSF" # sinking fund
22
+ CHARGE_INSURANCE = "IVIN"
23
+ CHARGE_WATER = "IVWA" # assumed code for metered water; matched by name too
24
+
25
+
26
+ def _to_date(ts: Any) -> date | None:
27
+ if ts in (None, "", 0, "0"):
28
+ return None
29
+ try:
30
+ return datetime.fromtimestamp(int(float(ts)), MYT).date()
31
+ except (TypeError, ValueError, OSError):
32
+ return None
33
+
34
+
35
+ def _money(value: Any) -> float:
36
+ try:
37
+ return round(float(value), 2)
38
+ except (TypeError, ValueError):
39
+ return 0.0
40
+
41
+
42
+ def _line(row: dict[str, Any]) -> dict[str, Any]:
43
+ d = _to_date(row.get("date"))
44
+ due = _to_date(row.get("due"))
45
+ return {
46
+ "type": row.get("type"),
47
+ "reference_no": row.get("reference_no"),
48
+ "date": d.isoformat() if d else None,
49
+ "due": due.isoformat() if due else None,
50
+ "item": row.get("charge_item_name") or None,
51
+ "charge_code": row.get("charge_code") or None,
52
+ "period": _period(row.get("year_month_str")),
53
+ "amount": _money(row.get("amount")),
54
+ "outstanding": _money(row.get("outstanding")),
55
+ "record_id": row.get("record_id"),
56
+ }
57
+
58
+
59
+ def _period(ym: Any) -> str | None:
60
+ ym = str(ym or "")
61
+ return f"{ym[:4]}-{ym[4:6]}" if len(ym) == 6 and ym.isdigit() else None
62
+
63
+
64
+ def summarize(lines: list[dict[str, Any]], outstanding_rows: list[dict[str, Any]] | None = None) -> dict[str, Any]:
65
+ """Build the coordinator payload for one unit."""
66
+ parsed = [_line(r) for r in lines]
67
+ parsed.sort(key=lambda r: (r["date"] or "", r["reference_no"] or ""), reverse=True)
68
+
69
+ bills = [r for r in parsed if r["type"] == TYPE_BILL]
70
+ receipts = [r for r in parsed if r["type"] == TYPE_RECEIPT]
71
+
72
+ # Group bill lines by invoice number (one invoice = several charge items).
73
+ invoices: dict[str, dict[str, Any]] = {}
74
+ for r in bills:
75
+ inv = invoices.setdefault(
76
+ r["reference_no"],
77
+ {"reference_no": r["reference_no"], "date": r["date"], "due": r["due"], "amount": 0.0,
78
+ "outstanding": 0.0, "record_id": r["record_id"], "items": []},
79
+ )
80
+ inv["amount"] = round(inv["amount"] + r["amount"], 2)
81
+ inv["outstanding"] = round(inv["outstanding"] + r["outstanding"], 2)
82
+ inv["items"].append({"item": r["item"], "period": r["period"], "amount": r["amount"]})
83
+ invoice_list = sorted(invoices.values(), key=lambda i: (i["date"] or "", i["reference_no"] or ""), reverse=True)
84
+
85
+ # Outstanding: prefer the dedicated endpoint; fall back to statement lines.
86
+ if outstanding_rows:
87
+ out_lines = [_line(r) for r in outstanding_rows]
88
+ balance = round(sum(r["outstanding"] or r["amount"] for r in out_lines), 2)
89
+ else:
90
+ out_lines = [r for r in parsed if r["outstanding"] > 0]
91
+ balance = round(sum(r["outstanding"] for r in out_lines), 2)
92
+ # The outstanding feed's row shape is unverified: borrow what it lacks
93
+ # (record id, item name, dates) from the matching statement line.
94
+ by_ref = {}
95
+ for r in parsed:
96
+ by_ref.setdefault((r["type"], r["reference_no"]), []).append(r)
97
+ for r in out_lines:
98
+ match = by_ref.get((r["type"] or TYPE_BILL, r["reference_no"])) or by_ref.get((TYPE_BILL, r["reference_no"])) or []
99
+ twin = next((m for m in match if m["item"] == r["item"]), match[0] if match else None)
100
+ if twin:
101
+ for k in ("record_id", "item", "date", "due", "type", "period"):
102
+ if not r.get(k):
103
+ r[k] = twin[k]
104
+ due_dates = sorted(r["due"] for r in out_lines if r["due"])
105
+ out_bills = group_outstanding(out_lines)
106
+
107
+ def latest_item(code: str, name_hint: str) -> dict[str, Any] | None:
108
+ for r in bills:
109
+ if r["charge_code"] == code or (r["item"] or "").upper() == name_hint:
110
+ return r
111
+ return None
112
+
113
+ last_invoice = invoice_list[0] if invoice_list else None
114
+ last_receipt = receipts[0] if receipts else None
115
+ service = latest_item(CHARGE_SERVICE, "CHARGES")
116
+ sinking = latest_item(CHARGE_SINKING, "SINKING FUND")
117
+
118
+ return {
119
+ "outstanding_balance": balance,
120
+ "outstanding_items": out_lines,
121
+ "outstanding_bills": out_bills,
122
+ "next_due_date": due_dates[0] if due_dates else None,
123
+ "last_bill": last_invoice,
124
+ "last_payment": last_receipt,
125
+ "service_charge": service,
126
+ "sinking_fund": sinking,
127
+ "invoices": invoice_list[:12],
128
+ "payments": receipts[:12],
129
+ "statement": parsed[:30],
130
+ }
131
+
132
+
133
+ def group_outstanding(lines: list[dict[str, Any]]) -> list[dict[str, Any]]:
134
+ """Unpaid lines grouped per document (one bill = several charge items), oldest due first."""
135
+ groups: dict[tuple, dict[str, Any]] = {}
136
+ for r in lines:
137
+ g = groups.setdefault(
138
+ (r["type"], r["reference_no"]),
139
+ {"type": r["type"] or TYPE_BILL, "reference_no": r["reference_no"], "date": r["date"],
140
+ "due": r["due"], "record_id": r["record_id"], "amount": 0.0, "items": []},
141
+ )
142
+ owed = r["outstanding"] or r["amount"]
143
+ g["amount"] = round(g["amount"] + owed, 2)
144
+ g["items"].append({"item": r["item"], "period": r["period"], "amount": owed})
145
+ if not g["record_id"]:
146
+ g["record_id"] = r["record_id"]
147
+ return sorted(groups.values(), key=lambda g: (g["due"] or "9999", g["reference_no"] or ""))
148
+
149
+
150
+ # --------------------------------------------------------------------------
151
+ # Announcements
152
+ # --------------------------------------------------------------------------
153
+ import re # noqa: E402
154
+ from html import unescape # noqa: E402
155
+ from html.parser import HTMLParser # noqa: E402
156
+
157
+ PORTAL_ANNOUNCEMENT_URL = "https://spfm.com.my/prod/selfcare/announcement/detail/{id}"
158
+ PORTAL_ANNOUNCEMENT_LIST_URL = "https://spfm.com.my/prod/selfcare/announcement/listing"
159
+
160
+ # The API returns ISO 8601 ("2026-10-09T14:30:00+08:00"); the web UI shows
161
+ # "Fri 2026-10-09 2:30 PM (UTC+08:00)". Accept both.
162
+ _PORTAL_DT = re.compile(r"(\d{4}-\d{2}-\d{2})\s+(\d{1,2}):(\d{2})\s*([AP]M)", re.I)
163
+
164
+
165
+ def parse_portal_datetime(value: Any) -> datetime | None:
166
+ """Parse the portal's human timestamp into an aware datetime (MYT)."""
167
+ if not value:
168
+ return None
169
+ try:
170
+ dt = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
171
+ return dt if dt.tzinfo else dt.replace(tzinfo=MYT)
172
+ except ValueError:
173
+ pass
174
+ m = _PORTAL_DT.search(str(value))
175
+ if not m:
176
+ return None
177
+ day, hh, mm, ampm = m.groups()
178
+ hour = int(hh) % 12 + (12 if ampm.upper() == "PM" else 0)
179
+ y, mo, d = (int(x) for x in day.split("-"))
180
+ return datetime(y, mo, d, hour, int(mm), tzinfo=MYT)
181
+
182
+
183
+ class _TextExtractor(HTMLParser):
184
+ _BLOCK = {"p", "div", "br", "li", "tr", "h1", "h2", "h3", "h4", "h5", "h6"}
185
+
186
+ def __init__(self) -> None:
187
+ super().__init__(convert_charrefs=True)
188
+ self.parts: list[str] = []
189
+
190
+ def handle_starttag(self, tag: str, attrs: Any) -> None:
191
+ if tag in self._BLOCK:
192
+ self.parts.append("\n")
193
+
194
+ def handle_data(self, data: str) -> None:
195
+ self.parts.append(data)
196
+
197
+
198
+ def html_to_text(html: str | None) -> str:
199
+ if not html:
200
+ return ""
201
+ ex = _TextExtractor()
202
+ ex.feed(html)
203
+ text = unescape("".join(ex.parts)).replace("\xa0", " ")
204
+ lines = [re.sub(r"[ \t]+", " ", ln).strip() for ln in text.splitlines()]
205
+ return "\n".join(ln for ln in lines if ln)
206
+
207
+
208
+ def _announcement(raw: dict[str, Any], now: datetime) -> dict[str, Any]:
209
+ start = parse_portal_datetime(raw.get("start_date"))
210
+ end = parse_portal_datetime(raw.get("end_date"))
211
+ created = parse_portal_datetime(raw.get("created_at"))
212
+ notified = parse_portal_datetime(raw.get("last_notification"))
213
+ text = html_to_text(raw.get("message"))
214
+ return {
215
+ "id": raw.get("id"),
216
+ "title": (raw.get("title") or "").strip(),
217
+ "url": PORTAL_ANNOUNCEMENT_URL.format(id=raw.get("id")),
218
+ "published": (notified or created or start).isoformat() if (notified or created or start) else None,
219
+ "start_date": start.date().isoformat() if start else None,
220
+ "end_date": end.date().isoformat() if end else None,
221
+ "active": (start is None or start <= now) and (end is None or end > now),
222
+ "summary": text[:400] + ("…" if len(text) > 400 else ""),
223
+ "text": text,
224
+ "attachments": [
225
+ {"name": a.get("filename"), "url": a.get("url")}
226
+ for a in raw.get("attachments") or []
227
+ if a.get("url")
228
+ ],
229
+ "image": (raw.get("image") or {}).get("url") if isinstance(raw.get("image"), dict) else raw.get("image"),
230
+ "_sort": (created or start or datetime.min.replace(tzinfo=MYT)).isoformat(),
231
+ }
232
+
233
+
234
+ def summarize_announcements(raw_items: list[dict[str, Any]], now: datetime | None = None) -> dict[str, Any]:
235
+ """Newest-first announcements plus counts. ``now`` is injectable for tests."""
236
+ now = now or datetime.now(MYT)
237
+ items = [_announcement(r, now) for r in raw_items if r.get("id") is not None]
238
+ items.sort(key=lambda a: (a["_sort"], a["id"]), reverse=True)
239
+ for a in items:
240
+ a.pop("_sort", None)
241
+ return {
242
+ "latest": items[0] if items else None,
243
+ "items": items,
244
+ "active_count": sum(1 for a in items if a["active"]),
245
+ "total": len(items),
246
+ "list_url": PORTAL_ANNOUNCEMENT_LIST_URL,
247
+ }
248
+
249
+
250
+ # ---------------------------------------------------------------- merging
251
+ def merge_announcements(
252
+ web: list[dict[str, Any]] | None, dashboard: list[dict[str, Any]] | None
253
+ ) -> list[dict[str, Any]]:
254
+ """Union of the web listing (has attachments, hides expired) and the app's
255
+ dashboard feed (all notices incl. expired, no attachments), keyed by id."""
256
+ merged: dict[Any, dict[str, Any]] = {}
257
+ for row in dashboard or []:
258
+ if row.get("id") is not None:
259
+ merged[row["id"]] = dict(row)
260
+ for row in web or []:
261
+ if row.get("id") is None:
262
+ continue
263
+ base = merged.get(row["id"], {})
264
+ merged[row["id"]] = {**base, **{k: v for k, v in row.items() if v not in (None, "", [])}}
265
+ return list(merged.values())
266
+
267
+
268
+ # ---------------------------------------------------------- notifications
269
+ _NOTIF_PREFIX = re.compile(r"^.*?\bNew\s+Announcement\s*-\s*", re.I)
270
+
271
+
272
+ def notification_title(message: str | None) -> str:
273
+ """'RESIDENSI JERNIH KAJANG New Announcement - X' -> 'X'."""
274
+ text = (message or "").strip()
275
+ return _NOTIF_PREFIX.sub("", text, count=1).strip() or text
276
+
277
+
278
+ def _notification(raw: dict[str, Any]) -> dict[str, Any]:
279
+ created = parse_portal_datetime(raw.get("created_at"))
280
+ module = str(raw.get("module") or "").upper()
281
+ obj = raw.get("object_id")
282
+ return {
283
+ "id": raw.get("id"),
284
+ "module": module,
285
+ "object_id": obj,
286
+ "title": notification_title(raw.get("message")) if module == "ANNOUNCEMENT" else (raw.get("message") or "").strip(),
287
+ "message": (raw.get("message") or "").strip(),
288
+ "created": created.isoformat() if created else None,
289
+ "url": PORTAL_ANNOUNCEMENT_URL.format(id=obj) if module == "ANNOUNCEMENT" and obj else None,
290
+ }
291
+
292
+
293
+ def summarize_notifications(raw_items: list[dict[str, Any]]) -> dict[str, Any]:
294
+ items = [_notification(r) for r in raw_items if r.get("id") is not None]
295
+ items.sort(key=lambda n: (n["created"] or "", n["id"]), reverse=True)
296
+ return {"latest": items[0] if items else None, "items": items, "total": len(items)}
297
+
298
+
299
+ # ---------------------------------------------------------------- visitors
300
+ def _label(value: Any) -> str | None:
301
+ if isinstance(value, dict):
302
+ return value.get("label") or value.get("name")
303
+ return str(value) if value not in (None, "") else None
304
+
305
+
306
+ def _visitor(raw: dict[str, Any]) -> dict[str, Any]:
307
+ when = parse_portal_datetime(raw.get("datetime") or raw.get("appointment_datetime"))
308
+ scan_in = parse_portal_datetime(raw.get("scan_in_time"))
309
+ scan_out = parse_portal_datetime(raw.get("scan_out_time"))
310
+ return {
311
+ "id": raw.get("id"),
312
+ "name": (raw.get("visitor_name") or raw.get("appointment_name") or "").strip(),
313
+ "type": _label(raw.get("visitor_type")),
314
+ "datetime": when.isoformat() if when else None,
315
+ "company": raw.get("company_name") or None,
316
+ "purpose": raw.get("purpose") or raw.get("appointment_purpose") or None,
317
+ "vehicle": raw.get("vehicle_reg_no") or None,
318
+ "arrive_by": raw.get("arrive_by") or None,
319
+ "persons": raw.get("no_of_person"),
320
+ "status": _label(raw.get("status")),
321
+ "scan_in": scan_in.isoformat() if scan_in else None,
322
+ "scan_out": scan_out.isoformat() if scan_out else None,
323
+ "link": raw.get("appointment_link") or None,
324
+ "image_url": raw.get("image_url") or None,
325
+ "recurring": bool(raw.get("is_recurring")),
326
+ }
327
+
328
+
329
+ def summarize_visitors(
330
+ appointments: list[dict[str, Any]] | None,
331
+ pending: list[dict[str, Any]] | None,
332
+ now: datetime | None = None,
333
+ ) -> dict[str, Any]:
334
+ now = now or datetime.now(MYT)
335
+ today = now.astimezone(MYT).replace(hour=0, minute=0, second=0, microsecond=0)
336
+ items = [_visitor(r) for r in appointments or [] if r.get("id") is not None]
337
+ items.sort(key=lambda v: (v["datetime"] or "", v["id"]), reverse=True)
338
+ upcoming = sorted(
339
+ (v for v in items if v["datetime"] and datetime.fromisoformat(v["datetime"]) >= today and not v["scan_out"]),
340
+ key=lambda v: v["datetime"],
341
+ )
342
+ pend = [_visitor(r) for r in pending or [] if r.get("id") is not None]
343
+ return {
344
+ "items": items,
345
+ "upcoming": upcoming,
346
+ "next": upcoming[0] if upcoming else None,
347
+ "pending": pend,
348
+ }
349
+
350
+ def announcement_feed(
351
+ notifications: dict[str, Any] | None,
352
+ notices: dict[str, Any] | None,
353
+ limit: int = 15,
354
+ ) -> dict[str, Any]:
355
+ """Announcements as the app's bell shows them, shaped like the notice list.
356
+
357
+ One row per announcement (re-sent pushes fold into the newest). When an
358
+ announcement points at an official notice (its object_id is a notice id),
359
+ the notice's full title, text, dates and PDF are used and ``notice`` is
360
+ true. Otherwise only the push text exists (SPFM cuts it at ~60 chars).
361
+ """
362
+ by_id = {a.get("id"): a for a in (notices or {}).get("items") or []}
363
+ rows: list[dict[str, Any]] = []
364
+ seen: set[Any] = set()
365
+ for n in (notifications or {}).get("items") or []:
366
+ oid = n.get("object_id")
367
+ if n.get("module") != "ANNOUNCEMENT" or oid in seen:
368
+ continue
369
+ seen.add(oid)
370
+ linked = by_id.get(oid)
371
+ rows.append(
372
+ {
373
+ "id": oid,
374
+ "title": (linked or {}).get("title") or n.get("title"),
375
+ "published": n.get("created"),
376
+ "active": (linked or {}).get("active"),
377
+ "url": n.get("url"),
378
+ "pdf_url": next((x["url"] for x in (linked or {}).get("attachments") or []), None),
379
+ "notice": linked is not None,
380
+ # not exposed in the list; used for the latest row
381
+ "_message": (linked or {}).get("text") or n.get("title"),
382
+ "_start": (linked or {}).get("start_date"),
383
+ "_end": (linked or {}).get("end_date"),
384
+ }
385
+ )
386
+ latest = dict(rows[0]) if rows else None
387
+ for r in rows:
388
+ for k in ("_message", "_start", "_end"):
389
+ r.pop(k, None)
390
+ if latest:
391
+ latest["message"] = latest.pop("_message")
392
+ latest["start_date"] = latest.pop("_start")
393
+ latest["end_date"] = latest.pop("_end")
394
+ return {"latest": latest, "items": rows[:limit], "total": len(rows)}
spfm/retry.py ADDED
@@ -0,0 +1,97 @@
1
+ """Bounded retry with exponential backoff + jitter for SPFM API calls.
2
+
3
+ Adapted from danieyal/ha-mytnb (MIT). Auth and non-transient API errors
4
+ propagate immediately; SPFMConnectionError, timeouts and connection errors
5
+ are retried.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import asyncio
11
+ import logging
12
+ import random
13
+ from collections.abc import Awaitable, Callable
14
+
15
+ import aiohttp
16
+
17
+ from .exceptions import SPFMError
18
+
19
+ _RETRYABLE_EXCEPTIONS: tuple[type[Exception], ...] = (
20
+ asyncio.TimeoutError,
21
+ aiohttp.ClientConnectionError,
22
+ )
23
+
24
+
25
+ def _is_retryable(err: Exception) -> bool:
26
+ """Return True if the error is a transient failure worth retrying."""
27
+ if isinstance(err, _RETRYABLE_EXCEPTIONS):
28
+ return True
29
+ return isinstance(err, SPFMError) and getattr(err, "retryable", False)
30
+
31
+
32
+ async def with_retry[T](
33
+ send: Callable[[], Awaitable[T]],
34
+ *,
35
+ attempts: int,
36
+ base_delay: float,
37
+ backoff_factor: float = 2.0,
38
+ sleep: Callable[[float], Awaitable[None]] | None = None,
39
+ logger: logging.Logger | None = None,
40
+ ) -> T:
41
+ """Call ``send`` with exponential backoff + jitter on transient failures.
42
+
43
+ ``send`` is a zero-arg coroutine factory: each call performs one attempt.
44
+ The delay before a retry is ``base_delay * backoff_factor**attempt`` plus a
45
+ uniform jitter in ``[0, base_delay]`` (mirroring the original ha-mytnb cadence).
46
+
47
+ Args:
48
+ send: Zero-arg coroutine factory performing one attempt.
49
+ attempts: Maximum number of attempts (including the first).
50
+ base_delay: Base backoff delay in seconds (with added jitter).
51
+ backoff_factor: Multiplier applied per attempt to grow the delay.
52
+ sleep: Awaitable used to pause between attempts; defaults to
53
+ ``asyncio.sleep`` and resolved at call time so tests can patch the
54
+ module-level ``asyncio.sleep``.
55
+ logger: Optional logger for debug messages between retries.
56
+
57
+ Returns:
58
+ Whatever ``send`` returns on the first successful attempt.
59
+
60
+ Raises:
61
+ ValueError: If ``attempts`` < 1, ``base_delay`` < 0, or
62
+ ``backoff_factor`` < 1.
63
+ The last exception raised by ``send`` once attempts are exhausted, or
64
+ immediately for any non-retryable error.
65
+ """
66
+ if attempts < 1:
67
+ raise ValueError(f"attempts must be >= 1, got {attempts}")
68
+ if base_delay < 0:
69
+ raise ValueError(f"base_delay must be >= 0, got {base_delay}")
70
+ if backoff_factor < 1:
71
+ raise ValueError(f"backoff_factor must be >= 1, got {backoff_factor}")
72
+ if sleep is None:
73
+ sleep = asyncio.sleep
74
+
75
+ last_exc: Exception | None = None
76
+ for attempt in range(attempts):
77
+ try:
78
+ return await send()
79
+ except Exception as err: # noqa: BLE001 - re-raised below unless retryable
80
+ last_exc = err
81
+ if attempt >= attempts - 1 or not _is_retryable(err):
82
+ raise
83
+ delay = base_delay * (backoff_factor**attempt) + random.uniform(
84
+ 0, base_delay
85
+ )
86
+ if logger is not None:
87
+ logger.debug(
88
+ "Transient failure (attempt %d/%d), retrying in %.2fs: %s",
89
+ attempt + 1,
90
+ attempts,
91
+ delay,
92
+ err,
93
+ )
94
+ await sleep(delay)
95
+ # Unreachable: the loop either returns or raises on the final attempt.
96
+ assert last_exc is not None
97
+ raise last_exc