python-iwk 0.1.0__tar.gz

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,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,23 @@
1
+ # python-iwk
2
+
3
+ Asynchronous Python client library for Indah Water Konsortium (IWK) customer portal API.
4
+
5
+ ## Features
6
+
7
+ * **Async-First**: Built with `aiohttp` for modern async applications.
8
+ * **HTTP reCAPTCHA v3 Minting**: Built-in support to acquire valid reCAPTCHA tokens over HTTP without running Chrome/browser automation.
9
+ * **Transient Error Resilience**: Backoff retry with jitter for connection and gateway errors.
10
+ * **Account & Bill Management**: Fetch sewerage accounts, eBill status, billing history, and PDF bills.
11
+ * **CLI Utility**: Test credentials and view accounts from terminal.
12
+
13
+ ## Installation
14
+
15
+ ```bash
16
+ pip install python-iwk
17
+ ```
18
+
19
+ ## CLI Usage
20
+
21
+ ```bash
22
+ python -m iwk <username> <password>
23
+ ```
@@ -0,0 +1,52 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "python-iwk"
7
+ version = "0.1.0"
8
+ description = "Asynchronous Python client for Indah Water Konsortium (IWK) customer portal API"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = { text = "MIT" }
12
+ authors = [
13
+ { name = "Zubir Jamal" }
14
+ ]
15
+ keywords = ["iwk", "indah-water", "sewerage", "utilities", "malaysia", "home-assistant"]
16
+ classifiers = [
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.11",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
21
+ "License :: OSI Approved :: MIT License",
22
+ "Operating System :: OS Independent",
23
+ "Topic :: Home Automation",
24
+ "Topic :: Software Development :: Libraries :: Python Modules",
25
+ "Intended Audience :: Developers",
26
+ ]
27
+ dependencies = [
28
+ "aiohttp>=3.9.0",
29
+ ]
30
+
31
+ [project.optional-dependencies]
32
+ test = [
33
+ "pytest>=8.0.0",
34
+ "pytest-asyncio>=0.23.0",
35
+ ]
36
+
37
+ [project.urls]
38
+ Homepage = "https://github.com/zubirjamal/python-iwk"
39
+ Repository = "https://github.com/zubirjamal/python-iwk"
40
+ Issues = "https://github.com/zubirjamal/python-iwk/issues"
41
+
42
+ [project.scripts]
43
+ iwk = "iwk.cli:main"
44
+
45
+ [tool.setuptools.packages.find]
46
+ where = ["src"]
47
+
48
+ [tool.pytest.ini_options]
49
+ asyncio_mode = "auto"
50
+ asyncio_default_fixture_loop_scope = "function"
51
+ testpaths = ["tests"]
52
+ pythonpath = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+ ]
@@ -0,0 +1,4 @@
1
+ from iwk.cli import main
2
+
3
+ if __name__ == "__main__":
4
+ main()
@@ -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()
@@ -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
@@ -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)
@@ -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)
@@ -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()
@@ -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,17 @@
1
+ README.md
2
+ pyproject.toml
3
+ src/iwk/__init__.py
4
+ src/iwk/__main__.py
5
+ src/iwk/cli.py
6
+ src/iwk/client.py
7
+ src/iwk/exceptions.py
8
+ src/iwk/models.py
9
+ src/iwk/recaptcha.py
10
+ src/iwk/retry.py
11
+ src/python_iwk.egg-info/PKG-INFO
12
+ src/python_iwk.egg-info/SOURCES.txt
13
+ src/python_iwk.egg-info/dependency_links.txt
14
+ src/python_iwk.egg-info/entry_points.txt
15
+ src/python_iwk.egg-info/requires.txt
16
+ src/python_iwk.egg-info/top_level.txt
17
+ tests/test_client.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ iwk = iwk.cli:main
@@ -0,0 +1,5 @@
1
+ aiohttp>=3.9.0
2
+
3
+ [test]
4
+ pytest>=8.0.0
5
+ pytest-asyncio>=0.23.0
@@ -0,0 +1,90 @@
1
+ """Unit tests for python-iwk models, parsers, and retry logic."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import date
6
+ from unittest.mock import AsyncMock, MagicMock
7
+
8
+ import pytest
9
+
10
+ from iwk import (
11
+ GeoBlockedError,
12
+ IWKClient,
13
+ IWKConnectionError,
14
+ IWKError,
15
+ parse_history,
16
+ pdf_source_url,
17
+ )
18
+ from iwk.models import _to_date, _to_float
19
+ from iwk.retry import with_retry
20
+
21
+
22
+ def test_to_float():
23
+ assert _to_float("123.45") == 123.45
24
+ assert _to_float("1,234.50") == 1234.50
25
+ assert _to_float("") is None
26
+ assert _to_float(None) is None
27
+
28
+
29
+ def test_to_date():
30
+ assert _to_date("21 Oct 2026") == date(2026, 10, 21)
31
+ assert _to_date("21/10/2026") == date(2026, 10, 21)
32
+ assert _to_date("2026-10-21") == date(2026, 10, 21)
33
+ assert _to_date(None) is None
34
+ assert _to_date("invalid") is None
35
+
36
+
37
+ def test_pdf_source_url():
38
+ valid = pdf_source_url("/bills/sample.pdf")
39
+ assert valid == "https://customerportal.iwk.com.my/bills/sample.pdf"
40
+
41
+ app_valid = pdf_source_url("https://pdf.indahwater.app/bill.pdf")
42
+ assert app_valid == "https://pdf.indahwater.app/bill.pdf"
43
+
44
+ invalid_host = pdf_source_url("https://malicious-site.com/bill.pdf")
45
+ assert invalid_host is None
46
+
47
+ assert pdf_source_url("") is None
48
+
49
+
50
+ def test_parse_history():
51
+ raw_data = [
52
+ {"billtype": "Bill", "amount": "32.00", "date": "15 Sep 2026", "refno": "INV-001", "pfile": "inv1.pdf"},
53
+ {"billtype": "Payment", "amount": "-32.00", "date": "20 Sep 2026", "refno": "REC-001", "pfile": ""},
54
+ ]
55
+ parsed = parse_history(raw_data)
56
+ assert len(parsed) == 2
57
+ assert parsed[0]["is_payment"] is True
58
+ assert parsed[0]["date"] == date(2026, 9, 20)
59
+ assert parsed[1]["is_payment"] is False
60
+ assert parsed[1]["amount"] == 32.00
61
+
62
+
63
+ async def test_retry_on_transient_5xx():
64
+ attempts = 0
65
+
66
+ async def flaky_api():
67
+ nonlocal attempts
68
+ attempts += 1
69
+ if attempts < 3:
70
+ raise IWKConnectionError("502 Bad Gateway")
71
+ return {"status": 1}
72
+
73
+ result = await with_retry(flaky_api, attempts=3, base_delay=0.01)
74
+ assert result == {"status": 1}
75
+ assert attempts == 3
76
+
77
+
78
+ async def test_geoblock_detection():
79
+ mock_resp = AsyncMock()
80
+ mock_resp.status = 403
81
+ mock_resp.text = AsyncMock(return_value="Cloudflare Access denied Error 1020")
82
+
83
+ mock_session = MagicMock()
84
+ mock_session.closed = False
85
+ mock_session.post.return_value.__aenter__.return_value = mock_resp
86
+
87
+ client = IWKClient("user", "pass", session=mock_session)
88
+
89
+ with pytest.raises(GeoBlockedError):
90
+ await client._raw_post_single("test", {})