python-iwk 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.
- iwk/__init__.py +30 -0
- iwk/__main__.py +4 -0
- iwk/cli.py +68 -0
- iwk/client.py +296 -0
- iwk/exceptions.py +40 -0
- iwk/models.py +136 -0
- iwk/recaptcha.py +96 -0
- iwk/retry.py +71 -0
- python_iwk-0.1.0.dist-info/METADATA +49 -0
- python_iwk-0.1.0.dist-info/RECORD +13 -0
- python_iwk-0.1.0.dist-info/WHEEL +5 -0
- python_iwk-0.1.0.dist-info/entry_points.txt +2 -0
- python_iwk-0.1.0.dist-info/top_level.txt +1 -0
iwk/__init__.py
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Python client library for Indah Water Konsortium (IWK) customer portal."""
|
|
2
|
+
|
|
3
|
+
from .client import IWKClient
|
|
4
|
+
from .exceptions import (
|
|
5
|
+
GeoBlockedError,
|
|
6
|
+
IWKAuthError,
|
|
7
|
+
IWKCaptchaError,
|
|
8
|
+
IWKConnectionError,
|
|
9
|
+
IWKError,
|
|
10
|
+
RecaptchaError,
|
|
11
|
+
)
|
|
12
|
+
from .models import IWKAccount, parse_history, pdf_source_url
|
|
13
|
+
from .recaptcha import HttpRecaptcha
|
|
14
|
+
|
|
15
|
+
__version__ = "0.1.0"
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"GeoBlockedError",
|
|
19
|
+
"HttpRecaptcha",
|
|
20
|
+
"IWKAccount",
|
|
21
|
+
"IWKAuthError",
|
|
22
|
+
"IWKCaptchaError",
|
|
23
|
+
"IWKClient",
|
|
24
|
+
"IWKConnectionError",
|
|
25
|
+
"IWKError",
|
|
26
|
+
"RecaptchaError",
|
|
27
|
+
"__version__",
|
|
28
|
+
"parse_history",
|
|
29
|
+
"pdf_source_url",
|
|
30
|
+
]
|
iwk/__main__.py
ADDED
iwk/cli.py
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""CLI tool for testing IWK credentials and inspecting accounts."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import asyncio
|
|
7
|
+
import sys
|
|
8
|
+
|
|
9
|
+
from .client import IWKClient
|
|
10
|
+
from .exceptions import GeoBlockedError, IWKError
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
async def _run_cli(args: argparse.Namespace) -> int:
|
|
14
|
+
print(f"Connecting to IWK Customer Portal as {args.username}...")
|
|
15
|
+
|
|
16
|
+
async with IWKClient(args.username, args.password) as client:
|
|
17
|
+
try:
|
|
18
|
+
await client.login()
|
|
19
|
+
print("Authentication successful!")
|
|
20
|
+
|
|
21
|
+
profile = await client.get_profile()
|
|
22
|
+
name = profile.get("name") or args.username
|
|
23
|
+
print(f"User: {name}")
|
|
24
|
+
|
|
25
|
+
accounts = await client.get_accounts()
|
|
26
|
+
print(f"\nDiscovered {len(accounts)} sewerage account(s):")
|
|
27
|
+
|
|
28
|
+
for idx, (san, acc) in enumerate(accounts.items(), start=1):
|
|
29
|
+
label = acc.nickname or acc.owner_name or san
|
|
30
|
+
print(f"\n--- [{idx}] SAN: {san} ({label}) ---")
|
|
31
|
+
if acc.address:
|
|
32
|
+
print(f"Address : {acc.address}")
|
|
33
|
+
print(f"Amount Due : RM {acc.amount_due or 0.0:.2f}")
|
|
34
|
+
print(f"eBill Status : {acc.ebill_status or 'N/A'} ({acc.ebill_channel or 'None'})")
|
|
35
|
+
|
|
36
|
+
if acc.last_bill:
|
|
37
|
+
b = acc.last_bill
|
|
38
|
+
print(f"Last Bill : {b.get('date')} -> RM {b.get('amount') or 0.0:.2f} (Ref: {b.get('bill_no')})")
|
|
39
|
+
|
|
40
|
+
if acc.last_payment:
|
|
41
|
+
p = acc.last_payment
|
|
42
|
+
print(f"Last Payment : {p.get('date')} -> RM {p.get('amount') or 0.0:.2f}")
|
|
43
|
+
|
|
44
|
+
return 0
|
|
45
|
+
|
|
46
|
+
except GeoBlockedError as err:
|
|
47
|
+
print(f"\n[GEO-BLOCKED ERROR] {err}", file=sys.stderr)
|
|
48
|
+
return 2
|
|
49
|
+
except IWKError as err:
|
|
50
|
+
print(f"\n[ERROR] {err}", file=sys.stderr)
|
|
51
|
+
return 1
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def main() -> None:
|
|
55
|
+
parser = argparse.ArgumentParser(
|
|
56
|
+
prog="python -m iwk",
|
|
57
|
+
description="IWK (Indah Water) CLI test utility",
|
|
58
|
+
)
|
|
59
|
+
parser.add_argument("username", help="Registered email or login ID")
|
|
60
|
+
parser.add_argument("password", help="Account password")
|
|
61
|
+
|
|
62
|
+
args = parser.parse_args()
|
|
63
|
+
code = asyncio.run(_run_cli(args))
|
|
64
|
+
sys.exit(code)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
if __name__ == "__main__":
|
|
68
|
+
main()
|
iwk/client.py
ADDED
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
"""Async client for the IWK customer portal and mobile app API."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import base64
|
|
7
|
+
import binascii
|
|
8
|
+
import logging
|
|
9
|
+
from typing import Any
|
|
10
|
+
from urllib.parse import urlparse
|
|
11
|
+
|
|
12
|
+
import aiohttp
|
|
13
|
+
|
|
14
|
+
from .exceptions import (
|
|
15
|
+
GeoBlockedError,
|
|
16
|
+
IWKAuthError,
|
|
17
|
+
IWKCaptchaError,
|
|
18
|
+
IWKConnectionError,
|
|
19
|
+
IWKError,
|
|
20
|
+
RecaptchaError,
|
|
21
|
+
)
|
|
22
|
+
from .models import IWKAccount, _to_float, parse_history, pdf_source_url
|
|
23
|
+
from .recaptcha import HttpRecaptcha
|
|
24
|
+
from .retry import RETRYABLE_STATUS_CODES, with_retry
|
|
25
|
+
|
|
26
|
+
_LOGGER = logging.getLogger(__name__)
|
|
27
|
+
|
|
28
|
+
API_BASE = "https://customerportal.iwk.com.my/api/{lang}/5"
|
|
29
|
+
DEFAULT_TIMEOUT = aiohttp.ClientTimeout(total=30)
|
|
30
|
+
_EXPIRED_HINTS = ("session expired", "please login again", "invalid token")
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class IWKClient:
|
|
34
|
+
"""Async API client for Indah Water Konsortium (IWK) with automatic session recovery."""
|
|
35
|
+
|
|
36
|
+
def __init__(
|
|
37
|
+
self,
|
|
38
|
+
username: str,
|
|
39
|
+
password: str,
|
|
40
|
+
session: aiohttp.ClientSession | None = None,
|
|
41
|
+
*,
|
|
42
|
+
lang: str = "en",
|
|
43
|
+
retry_attempts: int = 3,
|
|
44
|
+
retry_base_delay: float = 0.5,
|
|
45
|
+
) -> None:
|
|
46
|
+
self._username = username
|
|
47
|
+
self._password = password
|
|
48
|
+
self._external_session = session is not None
|
|
49
|
+
self._session = session
|
|
50
|
+
self._lang = lang
|
|
51
|
+
self._retry_attempts = retry_attempts
|
|
52
|
+
self._retry_base_delay = retry_base_delay
|
|
53
|
+
|
|
54
|
+
self._base = API_BASE.format(lang=lang)
|
|
55
|
+
self._token: str | None = None
|
|
56
|
+
self._http_rc = HttpRecaptcha()
|
|
57
|
+
self._login_lock = asyncio.Lock()
|
|
58
|
+
self.profile: dict[str, Any] = {}
|
|
59
|
+
|
|
60
|
+
async def __aenter__(self) -> IWKClient:
|
|
61
|
+
return self
|
|
62
|
+
|
|
63
|
+
async def __aexit__(
|
|
64
|
+
self,
|
|
65
|
+
exc_type: type[BaseException] | None,
|
|
66
|
+
exc_val: BaseException | None,
|
|
67
|
+
exc_tb: Any,
|
|
68
|
+
) -> None:
|
|
69
|
+
await self.close()
|
|
70
|
+
|
|
71
|
+
async def _get_session(self) -> aiohttp.ClientSession:
|
|
72
|
+
if self._session is None or self._session.closed:
|
|
73
|
+
self._session = aiohttp.ClientSession(timeout=DEFAULT_TIMEOUT)
|
|
74
|
+
self._external_session = False
|
|
75
|
+
return self._session
|
|
76
|
+
|
|
77
|
+
async def close(self) -> None:
|
|
78
|
+
"""Close internal session if created by this client."""
|
|
79
|
+
if not self._external_session and self._session and not self._session.closed:
|
|
80
|
+
await self._session.close()
|
|
81
|
+
|
|
82
|
+
@property
|
|
83
|
+
def has_token(self) -> bool:
|
|
84
|
+
return self._token is not None
|
|
85
|
+
|
|
86
|
+
async def _raw_post_single(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
|
|
87
|
+
session = await self._get_session()
|
|
88
|
+
url = f"{self._base}/{path}"
|
|
89
|
+
|
|
90
|
+
try:
|
|
91
|
+
async with session.post(url, json=body, timeout=DEFAULT_TIMEOUT) as resp:
|
|
92
|
+
status = resp.status
|
|
93
|
+
if status == 403:
|
|
94
|
+
text = await resp.text()
|
|
95
|
+
if "Access denied" in text or "Cloudflare" in text or "WAF" in text:
|
|
96
|
+
raise GeoBlockedError()
|
|
97
|
+
raise IWKAuthError(f"{path}: HTTP 403 Forbidden")
|
|
98
|
+
|
|
99
|
+
if status in RETRYABLE_STATUS_CODES:
|
|
100
|
+
raise IWKConnectionError(f"{path}: HTTP {status} transient error")
|
|
101
|
+
|
|
102
|
+
resp.raise_for_status()
|
|
103
|
+
try:
|
|
104
|
+
data = await resp.json(content_type=None)
|
|
105
|
+
except (aiohttp.ContentTypeError, ValueError):
|
|
106
|
+
data = None
|
|
107
|
+
|
|
108
|
+
except (TimeoutError, aiohttp.ClientError) as err:
|
|
109
|
+
raise IWKConnectionError(f"{path}: {err}") from err
|
|
110
|
+
|
|
111
|
+
if not isinstance(data, dict):
|
|
112
|
+
raise IWKError(f"{path}: unexpected response {str(data)[:200]}")
|
|
113
|
+
return data
|
|
114
|
+
|
|
115
|
+
async def _raw_post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
|
|
116
|
+
"""Wrap request in bounded retry with exponential backoff and jitter."""
|
|
117
|
+
return await with_retry(
|
|
118
|
+
lambda: self._raw_post_single(path, body),
|
|
119
|
+
attempts=self._retry_attempts,
|
|
120
|
+
base_delay=self._retry_base_delay,
|
|
121
|
+
logger=_LOGGER,
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
async def login(self) -> None:
|
|
125
|
+
"""Mint a reCAPTCHA v3 token over plain HTTP and log in."""
|
|
126
|
+
async with self._login_lock:
|
|
127
|
+
session = await self._get_session()
|
|
128
|
+
try:
|
|
129
|
+
rc = await self._http_rc.get_token(f"{self._base}/recaptcha?action=Login", session=session)
|
|
130
|
+
except RecaptchaError as err:
|
|
131
|
+
raise IWKCaptchaError(f"reCAPTCHA generation failed: {err}") from err
|
|
132
|
+
|
|
133
|
+
data = await self._raw_post(
|
|
134
|
+
"login",
|
|
135
|
+
{"username": self._username, "password": self._password, "recaptcha": rc},
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
if data.get("status") != 1 or not data.get("data"):
|
|
139
|
+
msg = str(data.get("msg", ""))
|
|
140
|
+
if "error 1.0" in msg.lower():
|
|
141
|
+
raise IWKCaptchaError(f"reCAPTCHA rejected by IWK: {msg}")
|
|
142
|
+
raise IWKAuthError(msg or "Login failed")
|
|
143
|
+
|
|
144
|
+
tok = data["data"]
|
|
145
|
+
if isinstance(tok, dict):
|
|
146
|
+
tok = tok.get("accesstoken") or tok.get("token")
|
|
147
|
+
self._token = str(tok)
|
|
148
|
+
_LOGGER.debug("IWK login successful")
|
|
149
|
+
|
|
150
|
+
async def _post(self, path: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
|
|
151
|
+
"""Authenticated POST request with automatic re-login on expired token."""
|
|
152
|
+
for attempt in (1, 2):
|
|
153
|
+
if not self._token:
|
|
154
|
+
await self.login()
|
|
155
|
+
payload = {"token": self._token, **(body or {})}
|
|
156
|
+
data = await self._raw_post(path, payload)
|
|
157
|
+
|
|
158
|
+
if data.get("status") == 1:
|
|
159
|
+
return data
|
|
160
|
+
|
|
161
|
+
msg = str(data.get("msg", "")).lower()
|
|
162
|
+
if any(h in msg for h in _EXPIRED_HINTS) and attempt == 1:
|
|
163
|
+
_LOGGER.debug("IWK token expired, re-authenticating")
|
|
164
|
+
self._token = None
|
|
165
|
+
continue
|
|
166
|
+
|
|
167
|
+
raise IWKError(f"{path}: {data.get('msg')}")
|
|
168
|
+
|
|
169
|
+
raise IWKError(f"{path}: session could not be renewed")
|
|
170
|
+
|
|
171
|
+
async def get_profile(self) -> dict[str, Any]:
|
|
172
|
+
"""Fetch user profile information."""
|
|
173
|
+
data = await self._post("getProfile")
|
|
174
|
+
self.profile = data.get("data") or {}
|
|
175
|
+
return self.profile
|
|
176
|
+
|
|
177
|
+
async def get_accounts(self) -> dict[str, IWKAccount]:
|
|
178
|
+
"""Return every linked sewerage account (SAN) with balance and eBill info."""
|
|
179
|
+
listing = await self._post("getSewerageAccount")
|
|
180
|
+
rows = listing.get("data") or []
|
|
181
|
+
accounts: dict[str, IWKAccount] = {}
|
|
182
|
+
for row in rows:
|
|
183
|
+
san = str(row.get("sanNo") or row.get("san") or "").strip()
|
|
184
|
+
if san:
|
|
185
|
+
accounts[san] = IWKAccount(san=san, nickname=row.get("nickname"))
|
|
186
|
+
|
|
187
|
+
if not accounts:
|
|
188
|
+
return accounts
|
|
189
|
+
|
|
190
|
+
# One call returns eBill info for all accounts
|
|
191
|
+
try:
|
|
192
|
+
ebill = await self._post(
|
|
193
|
+
"getSewerageAccountEBillInfo", {"san": next(iter(accounts))}
|
|
194
|
+
)
|
|
195
|
+
for row in ebill.get("data") or []:
|
|
196
|
+
acc = accounts.get(str(row.get("sanNo")))
|
|
197
|
+
if not acc:
|
|
198
|
+
continue
|
|
199
|
+
acc.ebill_status = row.get("ebillstatus")
|
|
200
|
+
acc.ebill_channel = row.get("ebillChannel")
|
|
201
|
+
acc.ebill_registered_date = row.get("registerEBilldate")
|
|
202
|
+
acc.ownership = row.get("ownership")
|
|
203
|
+
acc.account_status = row.get("status")
|
|
204
|
+
except IWKError as err:
|
|
205
|
+
_LOGGER.warning("Could not fetch eBill info: %s", err)
|
|
206
|
+
|
|
207
|
+
for san, acc in accounts.items():
|
|
208
|
+
detail = (await self._post("getOneSewerageAccount", {"san": san})).get("data") or {}
|
|
209
|
+
acc.raw = detail
|
|
210
|
+
acc.owner_name = detail.get("ownername")
|
|
211
|
+
acc.nickname = detail.get("nickname") or acc.nickname
|
|
212
|
+
acc.address = detail.get("address")
|
|
213
|
+
acc.amount_due = _to_float(detail.get("amt"))
|
|
214
|
+
acc.bill_no = detail.get("billno")
|
|
215
|
+
acc.old_san = detail.get("oldSan")
|
|
216
|
+
acc.ctos_tag = detail.get("ctos_tag") or None
|
|
217
|
+
acc.dca_tag = detail.get("dca_tag") or None
|
|
218
|
+
|
|
219
|
+
try:
|
|
220
|
+
hist = await self._post("getViewBill", {"sanNo": san, "san": san})
|
|
221
|
+
acc.history = parse_history(hist.get("data"))
|
|
222
|
+
except IWKError as err:
|
|
223
|
+
_LOGGER.warning("Could not fetch history for %s: %s", san, err)
|
|
224
|
+
|
|
225
|
+
return accounts
|
|
226
|
+
|
|
227
|
+
async def fetch_pdf(self, pfile: str) -> bytes:
|
|
228
|
+
"""Download or decode a bill PDF."""
|
|
229
|
+
val = str(pfile or "").strip()
|
|
230
|
+
if val.lower().startswith("data:"):
|
|
231
|
+
val = val.split(",", 1)[-1]
|
|
232
|
+
|
|
233
|
+
if val.startswith("JVBER") or (len(val) > 512 and "://" not in val[:16]):
|
|
234
|
+
try:
|
|
235
|
+
body = base64.b64decode(val + "=" * (-len(val) % 4), validate=False)
|
|
236
|
+
except (binascii.Error, ValueError) as err:
|
|
237
|
+
raise IWKError(f"pfile is not valid base64: {err}") from err
|
|
238
|
+
if body[:5] == b"%PDF-":
|
|
239
|
+
return body
|
|
240
|
+
|
|
241
|
+
url = pdf_source_url(val)
|
|
242
|
+
if not url:
|
|
243
|
+
raise IWKError("PDF location is not a recognized IWK URL")
|
|
244
|
+
|
|
245
|
+
session = await self._get_session()
|
|
246
|
+
attempts: list[dict[str, Any]] = [{}]
|
|
247
|
+
if self._token:
|
|
248
|
+
attempts.append({"params": {"token": self._token}})
|
|
249
|
+
|
|
250
|
+
for kw in attempts:
|
|
251
|
+
try:
|
|
252
|
+
async with session.get(url, timeout=aiohttp.ClientTimeout(total=60), **kw) as resp:
|
|
253
|
+
body = await resp.read()
|
|
254
|
+
if resp.status == 200 and body[:5] == b"%PDF-":
|
|
255
|
+
return body
|
|
256
|
+
except (aiohttp.ClientError, TimeoutError) as err:
|
|
257
|
+
raise IWKError(f"PDF download failed: {err}") from err
|
|
258
|
+
|
|
259
|
+
raise IWKError("IWK did not return a valid PDF")
|
|
260
|
+
|
|
261
|
+
async def subscribe_ebill(
|
|
262
|
+
self, san: str, ownership: str = "Owner", channel: str = "Email"
|
|
263
|
+
) -> dict[str, Any]:
|
|
264
|
+
"""Subscribe an account to eBill delivery."""
|
|
265
|
+
return await self._post(
|
|
266
|
+
"subscribeToEbill", {"san": san, "ownership": ownership, "ebill_channel": channel}
|
|
267
|
+
)
|
|
268
|
+
|
|
269
|
+
async def create_payment(
|
|
270
|
+
self, account: IWKAccount, amount: float, email: str, name: str | None = None
|
|
271
|
+
) -> dict[str, Any]:
|
|
272
|
+
"""Create a pay-bill pre-order for eGHL payment gateway."""
|
|
273
|
+
form = {
|
|
274
|
+
"name": name or self.profile.get("name") or account.owner_name or "",
|
|
275
|
+
"address": account.address or "",
|
|
276
|
+
"amount": f"{amount:.2f}",
|
|
277
|
+
"billno": account.bill_no or "",
|
|
278
|
+
"accountno": account.san,
|
|
279
|
+
"email": email,
|
|
280
|
+
"payfrom": "App",
|
|
281
|
+
}
|
|
282
|
+
session = await self._get_session()
|
|
283
|
+
try:
|
|
284
|
+
async with session.post(
|
|
285
|
+
f"{self._base}/addPayBillPreorder",
|
|
286
|
+
data=form,
|
|
287
|
+
timeout=aiohttp.ClientTimeout(total=30),
|
|
288
|
+
) as resp:
|
|
289
|
+
resp.raise_for_status()
|
|
290
|
+
data = await resp.json(content_type=None)
|
|
291
|
+
except (aiohttp.ClientError, TimeoutError) as err:
|
|
292
|
+
raise IWKError(f"addPayBillPreorder: {err}") from err
|
|
293
|
+
|
|
294
|
+
if not isinstance(data, dict) or data.get("status") != 1:
|
|
295
|
+
raise IWKError(f"addPayBillPreorder failed: {data}")
|
|
296
|
+
return data
|
iwk/exceptions.py
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""Custom exceptions for the IWK API client."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class IWKError(Exception):
|
|
7
|
+
"""Base exception for all IWK client errors."""
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class IWKAuthError(IWKError):
|
|
11
|
+
"""Raised when authentication credentials are rejected."""
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class IWKCaptchaError(IWKError):
|
|
15
|
+
"""Raised when reCAPTCHA token cannot be minted or is rejected by IWK."""
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class RecaptchaError(IWKCaptchaError):
|
|
19
|
+
"""Raised when fetching or parsing the reCAPTCHA token fails."""
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class IWKConnectionError(IWKError):
|
|
23
|
+
"""Raised on network failure, timeout, or transient 5xx error."""
|
|
24
|
+
|
|
25
|
+
def __init__(self, message: str) -> None:
|
|
26
|
+
super().__init__(message)
|
|
27
|
+
self.retryable = True
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class GeoBlockedError(IWKAuthError):
|
|
31
|
+
"""Raised when request is geo-blocked outside Malaysia or by a VPN."""
|
|
32
|
+
|
|
33
|
+
def __init__(
|
|
34
|
+
self,
|
|
35
|
+
message: str = (
|
|
36
|
+
"Access denied — IWK customer portal API is restricted to Malaysian IP addresses. "
|
|
37
|
+
"Please connect directly from a Malaysian network without VPN."
|
|
38
|
+
),
|
|
39
|
+
) -> None:
|
|
40
|
+
super().__init__(message)
|
iwk/models.py
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
"""Data models and helper parsers for IWK accounts, bills, and transactions."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from datetime import date, datetime
|
|
8
|
+
from typing import Any
|
|
9
|
+
from urllib.parse import urljoin, urlparse
|
|
10
|
+
|
|
11
|
+
_DATE_FORMATS = (
|
|
12
|
+
"%d %b %Y",
|
|
13
|
+
"%d/%m/%Y",
|
|
14
|
+
"%d-%m-%Y",
|
|
15
|
+
"%Y-%m-%d",
|
|
16
|
+
"%d %B %Y",
|
|
17
|
+
"%d.%m.%Y",
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
_PDF_HOSTS = ("iwk.com.my", "indahwater.app")
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _to_float(val: Any) -> float | None:
|
|
24
|
+
if val is None or val == "":
|
|
25
|
+
return None
|
|
26
|
+
try:
|
|
27
|
+
return float(str(val).replace(",", "").strip())
|
|
28
|
+
except (TypeError, ValueError):
|
|
29
|
+
return None
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _to_date(val: Any) -> date | None:
|
|
33
|
+
if not val:
|
|
34
|
+
return None
|
|
35
|
+
txt = str(val).strip()
|
|
36
|
+
parts = txt.split()
|
|
37
|
+
candidates = (txt, txt.split("T")[0], " ".join(parts[:3]), parts[0] if parts else txt)
|
|
38
|
+
for cand in candidates:
|
|
39
|
+
for fmt in _DATE_FORMATS:
|
|
40
|
+
try:
|
|
41
|
+
return datetime.strptime(cand, fmt).date()
|
|
42
|
+
except ValueError:
|
|
43
|
+
pass
|
|
44
|
+
try:
|
|
45
|
+
return datetime.fromisoformat(txt.replace("Z", "+00:00")).date()
|
|
46
|
+
except ValueError:
|
|
47
|
+
return None
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _ci(row: dict[str, Any], *keys: str) -> Any:
|
|
51
|
+
"""Case-insensitive, underscore-insensitive dictionary lookup."""
|
|
52
|
+
low = {str(k).lower().replace("_", ""): v for k, v in row.items()}
|
|
53
|
+
for k in keys:
|
|
54
|
+
v = low.get(k.lower())
|
|
55
|
+
if v not in (None, ""):
|
|
56
|
+
return v
|
|
57
|
+
return None
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def parse_history(data: Any) -> list[dict[str, Any]]:
|
|
61
|
+
"""Normalise getViewBill rows into structured bill/payment dicts."""
|
|
62
|
+
if isinstance(data, str):
|
|
63
|
+
try:
|
|
64
|
+
data = json.loads(data)
|
|
65
|
+
except ValueError:
|
|
66
|
+
return []
|
|
67
|
+
if isinstance(data, dict):
|
|
68
|
+
data = next((v for v in data.values() if isinstance(v, list)), [])
|
|
69
|
+
out: list[dict[str, Any]] = []
|
|
70
|
+
for row in data or []:
|
|
71
|
+
if not isinstance(row, dict):
|
|
72
|
+
continue
|
|
73
|
+
btype = str(_ci(row, "type", "billtype") or "")
|
|
74
|
+
amt = _to_float(_ci(row, "billamount", "amount", "amt"))
|
|
75
|
+
out.append(
|
|
76
|
+
{
|
|
77
|
+
"type": btype,
|
|
78
|
+
"is_payment": btype.lower() == "payment" or (amt is not None and amt < 0),
|
|
79
|
+
"date": _to_date(_ci(row, "billdate", "date")),
|
|
80
|
+
"bill_no": (lambda r: None if str(r).strip("- ") == "" else str(r).strip())(
|
|
81
|
+
_ci(row, "refno", "billno") or ""
|
|
82
|
+
),
|
|
83
|
+
"amount": amt,
|
|
84
|
+
"pdf": _ci(row, "pfile", "pdffile", "pdf"),
|
|
85
|
+
}
|
|
86
|
+
)
|
|
87
|
+
out.sort(key=lambda h: h["date"] or date.min, reverse=True)
|
|
88
|
+
return out
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def pdf_source_url(pfile: str) -> str | None:
|
|
92
|
+
"""Resolve an IWK pfile value to an absolute URL on an IWK host (or None)."""
|
|
93
|
+
if not pfile or len(str(pfile)) > 2000:
|
|
94
|
+
return None
|
|
95
|
+
url = urljoin("https://customerportal.iwk.com.my/", str(pfile).strip())
|
|
96
|
+
host = (urlparse(url).hostname or "").lower()
|
|
97
|
+
if urlparse(url).scheme not in ("https", "http") or not any(
|
|
98
|
+
host == h or host.endswith("." + h) for h in _PDF_HOSTS
|
|
99
|
+
):
|
|
100
|
+
return None
|
|
101
|
+
return url
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
@dataclass(slots=True)
|
|
105
|
+
class IWKAccount:
|
|
106
|
+
"""One sewerage service account (SAN)."""
|
|
107
|
+
|
|
108
|
+
san: str
|
|
109
|
+
nickname: str | None = None
|
|
110
|
+
owner_name: str | None = None
|
|
111
|
+
address: str | None = None
|
|
112
|
+
amount_due: float | None = None
|
|
113
|
+
bill_no: str | None = None
|
|
114
|
+
old_san: str | None = None
|
|
115
|
+
ctos_tag: str | None = None
|
|
116
|
+
dca_tag: str | None = None
|
|
117
|
+
ebill_status: str | None = None
|
|
118
|
+
ebill_channel: str | None = None
|
|
119
|
+
ebill_registered_date: str | None = None
|
|
120
|
+
ownership: str | None = None
|
|
121
|
+
account_status: str | None = None
|
|
122
|
+
history: list[dict[str, Any]] = field(default_factory=list)
|
|
123
|
+
raw: dict[str, Any] = field(default_factory=dict)
|
|
124
|
+
|
|
125
|
+
def _latest(self, payment: bool) -> dict[str, Any] | None:
|
|
126
|
+
rows = [h for h in self.history if h["is_payment"] == payment]
|
|
127
|
+
rows.sort(key=lambda h: h["date"] or date.min, reverse=True)
|
|
128
|
+
return rows[0] if rows else None
|
|
129
|
+
|
|
130
|
+
@property
|
|
131
|
+
def last_bill(self) -> dict[str, Any] | None:
|
|
132
|
+
return self._latest(False)
|
|
133
|
+
|
|
134
|
+
@property
|
|
135
|
+
def last_payment(self) -> dict[str, Any] | None:
|
|
136
|
+
return self._latest(True)
|
iwk/recaptcha.py
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"""Mint IWK reCAPTCHA v3 tokens over plain HTTP.
|
|
2
|
+
|
|
3
|
+
The IWK mobile app loads {API_BASE}/recaptcha?action=Login in a WebView and
|
|
4
|
+
reads the token from a recaptcha://token?value=... redirect.
|
|
5
|
+
|
|
6
|
+
Tokens are minted over plain HTTP via Google's reCAPTCHA anchor/reload
|
|
7
|
+
endpoints; no browser or headless automation is needed.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import base64
|
|
13
|
+
import logging
|
|
14
|
+
import re
|
|
15
|
+
|
|
16
|
+
import aiohttp
|
|
17
|
+
|
|
18
|
+
from .exceptions import RecaptchaError
|
|
19
|
+
|
|
20
|
+
_LOGGER = logging.getLogger(__name__)
|
|
21
|
+
|
|
22
|
+
DEFAULT_SITE_KEY = "6Le7JKUrAAAAABiDWLLeqHj9iLVVxuKmwV1O6IMM"
|
|
23
|
+
DEFAULT_ACTION = "appLogin"
|
|
24
|
+
|
|
25
|
+
_UA = (
|
|
26
|
+
"Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 "
|
|
27
|
+
"(KHTML, like Gecko) Chrome/129.0.0.0 Mobile Safari/537.36"
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class HttpRecaptcha:
|
|
32
|
+
"""Mint a v3 token over plain HTTP via Google's anchor + reload endpoints."""
|
|
33
|
+
|
|
34
|
+
ORIGIN = "https://customerportal.iwk.com.my:443"
|
|
35
|
+
|
|
36
|
+
def __init__(
|
|
37
|
+
self,
|
|
38
|
+
site_key: str = DEFAULT_SITE_KEY,
|
|
39
|
+
action: str = DEFAULT_ACTION,
|
|
40
|
+
) -> None:
|
|
41
|
+
self.site_key = site_key
|
|
42
|
+
self.action = action
|
|
43
|
+
|
|
44
|
+
async def get_token(
|
|
45
|
+
self,
|
|
46
|
+
page_url: str,
|
|
47
|
+
session: aiohttp.ClientSession | None = None,
|
|
48
|
+
) -> str:
|
|
49
|
+
key = self.site_key
|
|
50
|
+
co = base64.b64encode(self.ORIGIN.encode()).decode().replace("=", ".")
|
|
51
|
+
headers = {"User-Agent": _UA, "Referer": page_url}
|
|
52
|
+
timeout = aiohttp.ClientTimeout(total=30)
|
|
53
|
+
|
|
54
|
+
should_close = False
|
|
55
|
+
if session is None or session.closed:
|
|
56
|
+
session = aiohttp.ClientSession(headers=headers, timeout=timeout)
|
|
57
|
+
should_close = True
|
|
58
|
+
|
|
59
|
+
try:
|
|
60
|
+
async with session.get(f"https://www.google.com/recaptcha/api.js?render={key}", headers=headers) as r:
|
|
61
|
+
text = await r.text()
|
|
62
|
+
m = re.search(r"releases/([^/]+)/", text)
|
|
63
|
+
if not m:
|
|
64
|
+
raise RecaptchaError("Could not find reCAPTCHA release version")
|
|
65
|
+
ver = m.group(1)
|
|
66
|
+
|
|
67
|
+
async with session.get(
|
|
68
|
+
"https://www.google.com/recaptcha/api2/anchor",
|
|
69
|
+
params={"ar": "1", "k": key, "co": co, "hl": "en", "v": ver, "size": "invisible", "cb": "iwkha"},
|
|
70
|
+
headers=headers,
|
|
71
|
+
) as r:
|
|
72
|
+
text = await r.text()
|
|
73
|
+
m = re.search(r'id="recaptcha-token" value="([^"]+)"', text)
|
|
74
|
+
if not m:
|
|
75
|
+
raise RecaptchaError("reCAPTCHA anchor returned no token")
|
|
76
|
+
|
|
77
|
+
c_val = m.group(1)
|
|
78
|
+
async with session.post(
|
|
79
|
+
f"https://www.google.com/recaptcha/api2/reload?k={key}",
|
|
80
|
+
data={"v": ver, "reason": "q", "c": c_val, "k": key, "co": co, "sa": self.action},
|
|
81
|
+
headers=headers,
|
|
82
|
+
) as r:
|
|
83
|
+
text = await r.text()
|
|
84
|
+
m = re.search(r'"rresp","([^"]+)"', text)
|
|
85
|
+
if not m:
|
|
86
|
+
raise RecaptchaError("reCAPTCHA reload returned no token")
|
|
87
|
+
|
|
88
|
+
token = m.group(1)
|
|
89
|
+
_LOGGER.debug("reCAPTCHA token successfully minted over HTTP (%d chars)", len(token))
|
|
90
|
+
return token
|
|
91
|
+
|
|
92
|
+
except (aiohttp.ClientError, TimeoutError) as err:
|
|
93
|
+
raise RecaptchaError(f"HTTP request error while minting reCAPTCHA: {err}") from err
|
|
94
|
+
finally:
|
|
95
|
+
if should_close:
|
|
96
|
+
await session.close()
|
iwk/retry.py
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
"""Bounded retry with exponential backoff and jitter for transient transport failures."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import logging
|
|
7
|
+
import random
|
|
8
|
+
from collections.abc import Awaitable, Callable
|
|
9
|
+
from typing import TypeVar
|
|
10
|
+
|
|
11
|
+
import aiohttp
|
|
12
|
+
|
|
13
|
+
from .exceptions import IWKError
|
|
14
|
+
|
|
15
|
+
T = TypeVar("T")
|
|
16
|
+
|
|
17
|
+
RETRYABLE_STATUS_CODES = frozenset({500, 502, 503, 504})
|
|
18
|
+
|
|
19
|
+
_RETRYABLE_EXCEPTIONS = (
|
|
20
|
+
asyncio.TimeoutError,
|
|
21
|
+
TimeoutError,
|
|
22
|
+
aiohttp.ClientError,
|
|
23
|
+
aiohttp.ServerDisconnectedError,
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
DEFAULT_MAX_ATTEMPTS = 3
|
|
27
|
+
DEFAULT_BASE_DELAY = 0.5
|
|
28
|
+
DEFAULT_BACKOFF_FACTOR = 2.0
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def is_retryable_error(err: Exception) -> bool:
|
|
32
|
+
"""Return True if the error is a transient failure worth retrying."""
|
|
33
|
+
if isinstance(err, _RETRYABLE_EXCEPTIONS):
|
|
34
|
+
return True
|
|
35
|
+
return isinstance(err, IWKError) and getattr(err, "retryable", False)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
async def with_retry(
|
|
39
|
+
send: Callable[[], Awaitable[T]],
|
|
40
|
+
*,
|
|
41
|
+
attempts: int = DEFAULT_MAX_ATTEMPTS,
|
|
42
|
+
base_delay: float = DEFAULT_BASE_DELAY,
|
|
43
|
+
backoff_factor: float = DEFAULT_BACKOFF_FACTOR,
|
|
44
|
+
logger: logging.Logger | None = None,
|
|
45
|
+
) -> T:
|
|
46
|
+
"""Call ``send`` with exponential backoff + jitter on transient failures."""
|
|
47
|
+
if attempts < 1:
|
|
48
|
+
raise ValueError(f"attempts must be >= 1, got {attempts}")
|
|
49
|
+
if base_delay < 0:
|
|
50
|
+
raise ValueError(f"base_delay must be >= 0, got {base_delay}")
|
|
51
|
+
if backoff_factor < 1:
|
|
52
|
+
raise ValueError(f"backoff_factor must be >= 1, got {backoff_factor}")
|
|
53
|
+
|
|
54
|
+
for attempt in range(attempts):
|
|
55
|
+
try:
|
|
56
|
+
return await send()
|
|
57
|
+
except Exception as err:
|
|
58
|
+
if attempt >= attempts - 1 or not is_retryable_error(err):
|
|
59
|
+
raise
|
|
60
|
+
delay = base_delay * (backoff_factor**attempt) + random.uniform(0, base_delay)
|
|
61
|
+
if logger is not None:
|
|
62
|
+
logger.debug(
|
|
63
|
+
"Transient IWK request failure (attempt %d/%d), retrying in %.2fs: %s",
|
|
64
|
+
attempt + 1,
|
|
65
|
+
attempts,
|
|
66
|
+
delay,
|
|
67
|
+
err,
|
|
68
|
+
)
|
|
69
|
+
await asyncio.sleep(delay)
|
|
70
|
+
|
|
71
|
+
raise RuntimeError("with_retry exhausted attempts without returning")
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: python-iwk
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Asynchronous Python client for Indah Water Konsortium (IWK) customer portal API
|
|
5
|
+
Author: Zubir Jamal
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/zubirjamal/python-iwk
|
|
8
|
+
Project-URL: Repository, https://github.com/zubirjamal/python-iwk
|
|
9
|
+
Project-URL: Issues, https://github.com/zubirjamal/python-iwk/issues
|
|
10
|
+
Keywords: iwk,indah-water,sewerage,utilities,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: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Topic :: Home Automation
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
19
|
+
Classifier: Intended Audience :: Developers
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
Requires-Dist: aiohttp>=3.9.0
|
|
23
|
+
Provides-Extra: test
|
|
24
|
+
Requires-Dist: pytest>=8.0.0; extra == "test"
|
|
25
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
|
|
26
|
+
|
|
27
|
+
# python-iwk
|
|
28
|
+
|
|
29
|
+
Asynchronous Python client library for Indah Water Konsortium (IWK) customer portal API.
|
|
30
|
+
|
|
31
|
+
## Features
|
|
32
|
+
|
|
33
|
+
* **Async-First**: Built with `aiohttp` for modern async applications.
|
|
34
|
+
* **HTTP reCAPTCHA v3 Minting**: Built-in support to acquire valid reCAPTCHA tokens over HTTP without running Chrome/browser automation.
|
|
35
|
+
* **Transient Error Resilience**: Backoff retry with jitter for connection and gateway errors.
|
|
36
|
+
* **Account & Bill Management**: Fetch sewerage accounts, eBill status, billing history, and PDF bills.
|
|
37
|
+
* **CLI Utility**: Test credentials and view accounts from terminal.
|
|
38
|
+
|
|
39
|
+
## Installation
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
pip install python-iwk
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## CLI Usage
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
python -m iwk <username> <password>
|
|
49
|
+
```
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
iwk/__init__.py,sha256=V-Qy_8GFBkrK7WIDfG6vVgHSDwRzVaDjXbU5VGb4WjY,640
|
|
2
|
+
iwk/__main__.py,sha256=_T1rpC5O-WYXPCgeJGqeJuerToWaRB7m4Oy8pvqSTI4,64
|
|
3
|
+
iwk/cli.py,sha256=SUpoKF4IbHy1MfGo5KbceJzAhdOrkRWDceN9MQimk58,2295
|
|
4
|
+
iwk/client.py,sha256=cqSG1H5shDJZconLjavOQzkKX-3vpEnlQDZlTYy1Ikw,11338
|
|
5
|
+
iwk/exceptions.py,sha256=yD_-Le5D0vwSEZEZbbdjbjTIFxbDqR6nQTm23hIkGRU,1108
|
|
6
|
+
iwk/models.py,sha256=UsjISxwN9NaGiicITbzPVpCBJw5lVZoR87oFErDN1Ps,4289
|
|
7
|
+
iwk/recaptcha.py,sha256=AEUgUBeuf8nJwcHdEVwsq52Ljr6RMZdtOKDHlXM3Ujo,3324
|
|
8
|
+
iwk/retry.py,sha256=6yxva-ACJ2yX4USrJ8PV5Dp8GEeg9eWYPyoJgIt8Www,2181
|
|
9
|
+
python_iwk-0.1.0.dist-info/METADATA,sha256=rlmQYBiG_nFl7EKV4g5CNG72EvGJnYidNL3zvHoeugg,1823
|
|
10
|
+
python_iwk-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
11
|
+
python_iwk-0.1.0.dist-info/entry_points.txt,sha256=N7AWFJgbZxe-khLM2Z15dSJRZtNmS96BaDi8obfdaHM,37
|
|
12
|
+
python_iwk-0.1.0.dist-info/top_level.txt,sha256=RnwqFE78AqZh3yzpJ5VGnQWa7c9IMT9wdnjKc61u41M,4
|
|
13
|
+
python_iwk-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
iwk
|