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.
- python_spfm-0.1.0.dist-info/METADATA +79 -0
- python_spfm-0.1.0.dist-info/RECORD +13 -0
- python_spfm-0.1.0.dist-info/WHEEL +5 -0
- python_spfm-0.1.0.dist-info/entry_points.txt +2 -0
- python_spfm-0.1.0.dist-info/licenses/LICENSE +21 -0
- python_spfm-0.1.0.dist-info/top_level.txt +1 -0
- spfm/__init__.py +52 -0
- spfm/__main__.py +4 -0
- spfm/cli.py +41 -0
- spfm/client.py +420 -0
- spfm/exceptions.py +26 -0
- spfm/parsing.py +394 -0
- spfm/retry.py +97 -0
|
@@ -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,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
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
|