python-mytnb 0.3.0__tar.gz → 0.5.0__tar.gz

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mytnb
-Version: 0.3.0
+Version: 0.5.0
 Summary: Python library to interface with the myTNB API (Tenaga Nasional Berhad)
 Project-URL: Repository, https://github.com/danieyal/python-mytnb
 License-Expression: MIT
@@ -16,16 +16,19 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
-Requires-Dist: click>=8.3.3
 Requires-Dist: cryptography>=42.0
 Requires-Dist: curl-cffi>=0.7
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.0
-Requires-Dist: rich>=15.0.0
+Provides-Extra: cli
+Requires-Dist: click>=8.3.3; extra == 'cli'
+Requires-Dist: rich>=15.0.0; extra == 'cli'
 Provides-Extra: dev
+Requires-Dist: click>=8.3.3; extra == 'dev'
 Requires-Dist: pylint>=3.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: rich>=15.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -79,6 +82,14 @@ asyncio.run(main())
 
 ## CLI
 
+The `mytnb` command-line tool requires the optional `cli` extra (it pulls in
+`click` and `rich`, which the library itself does not need). If you installed
+without it, `mytnb` (or `python -m mytnb`) will fail to start:
+
+```bash
+pip install "python-mytnb[cli]"
+```
+
 Pass credentials directly:
 
 ```bash

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/README.md

@@ -48,6 +48,14 @@ asyncio.run(main())
 
 ## CLI
 
+The `mytnb` command-line tool requires the optional `cli` extra (it pulls in
+`click` and `rich`, which the library itself does not need). If you installed
+without it, `mytnb` (or `python -m mytnb`) will fail to start:
+
+```bash
+pip install "python-mytnb[cli]"
+```
+
 Pass credentials directly:
 
 ```bash

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mytnb"
-version = "0.3.0"
+version = "0.5.0"
 description = "Python library to interface with the myTNB API (Tenaga Nasional Berhad)"
 readme = "README.md"
 license = "MIT"
@@ -26,16 +26,20 @@ dependencies = [
     "pydantic>=2.0",
     "cryptography>=42.0",
     "curl_cffi>=0.7",
-    "click>=8.3.3",
-    "rich>=15.0.0",
 ]
 
 [project.optional-dependencies]
+cli = [
+    "click>=8.3.3",
+    "rich>=15.0.0",
+]
 dev = [
     "pytest>=7.0",
     "pytest-asyncio>=0.21",
     "pylint>=3.0",
     "ruff>=0.6",
+    "click>=8.3.3",
+    "rich>=15.0.0",
 ]
 
 [project.scripts]

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/src/mytnb/__init__.py

@@ -3,7 +3,9 @@
 from mytnb.client import MyTNBClient
 from mytnb.crypto import EncryptedPayload, encrypt_request
 from mytnb.models import (
+    AccountDueAmount,
     AccountUsage,
+    BillHistoryEntry,
     BillingMonth,
     CostMetric,
     CustomerAccount,
@@ -19,7 +21,9 @@ __all__ = [
     "MyTNBClient",
     "EncryptedPayload",
     "encrypt_request",
+    "AccountDueAmount",
     "AccountUsage",
+    "BillHistoryEntry",
     "BillingMonth",
     "CostMetric",
     "CustomerAccount",

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/src/mytnb/cli.py

@@ -118,9 +118,14 @@ def _build_credentials(cfg: dict) -> Credentials:
 
 
 def _to_json(data: object) -> str:
-    """Serialize any object to JSON string."""
+    """Serialize any object (or list of models) to JSON string."""
     if hasattr(data, "model_dump"):
         data = data.model_dump()
+    elif isinstance(data, list):
+        data = [
+            item.model_dump() if hasattr(item, "model_dump") else item
+            for item in data
+        ]
     elif hasattr(data, "__dict__") and not isinstance(data, dict):
         data = data.__dict__
     return json.dumps(data, indent=2, default=str)
@@ -293,16 +298,12 @@ def due_amount(ctx, account, as_json):
                 _print_json(result)
                 return
 
-            data = result.get("AccountAmountDue", result) if isinstance(result, dict) else result
-            if isinstance(data, dict):
-                amount = data.get("amountDue", "--")
-                due_date = data.get("billDueDate", "--")
-                console.print(Panel(
-                    f"[bold green]RM {amount}[/]\nDue by [cyan]{due_date}[/]",
-                    title=f"Due Amount — {account}",
-                ))
-            else:
-                _print_json(result)
+            amount = "--" if result.amount_due is None else f"{result.amount_due:.2f}"
+            due_date = result.due_date.isoformat() if result.due_date else "--"
+            console.print(Panel(
+                f"[bold green]RM {amount}[/]\nDue by [cyan]{due_date}[/]",
+                title=f"Due Amount — {account}",
+            ))
 
     _run_async(_due())
 
@@ -324,20 +325,17 @@ def bill_history(ctx, account, as_json):
                 _print_json(result)
                 return
 
-            if isinstance(result, list):
-                table = Table(title=f"Bill History — {account}")
-                table.add_column("Date", style="cyan")
-                table.add_column("Bill No")
-                table.add_column("Amount (RM)", justify="right", style="green")
-                for bill in result:
-                    table.add_row(
-                        bill.get("DtBill", "--"),
-                        bill.get("BillingNo", "--"),
-                        bill.get("AmPayable", "--"),
-                    )
-                console.print(table)
-            else:
-                _print_json(result)
+            table = Table(title=f"Bill History — {account}")
+            table.add_column("Date", style="cyan")
+            table.add_column("Bill No")
+            table.add_column("Amount (RM)", justify="right", style="green")
+            for bill in result:
+                table.add_row(
+                    bill.date.isoformat() if bill.date else "--",
+                    bill.billing_no or "--",
+                    "--" if bill.amount is None else f"{bill.amount:.2f}",
+                )
+            console.print(table)
 
     _run_async(_history())
 

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/src/mytnb/client/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from typing import Any, Optional
 
 import httpx
@@ -14,7 +15,16 @@ from mytnb.client.legacy import _LegacyTransport
 from mytnb.client.rest import _RestTransport
 from mytnb.crypto import encrypt_request
 from mytnb.exceptions import APIError
-from mytnb.models import AccountUsage, BREligibility, CustomerAccount, SMRAccount
+from mytnb.models import (
+    AccountDueAmount,
+    AccountUsage,
+    BillHistoryEntry,
+    BREligibility,
+    CustomerAccount,
+    SMRAccount,
+)
+
+logger = logging.getLogger(__name__)
 
 
 class MyTNBClient:
@@ -229,30 +239,45 @@ class MyTNBClient:
         account_number: str,
         *,
         is_owner: bool = True,
-    ) -> dict:
-        """Get account due amount."""
+    ) -> AccountDueAmount:
+        """Get account due amount as a typed model."""
         data = {
             "contractAccount": account_number,
             "isOwnedAccount": "true" if is_owner else "false",
             "usrInf": self._legacy_transport.base_user_info(),
         }
         result = await self._legacy_transport.post("GetAccountDueAmount", data)
-        return result.get("data") or result
+        return AccountDueAmount.from_api_response(result.get("data", result))
 
     async def get_bill_history(
         self,
         account_number: str,
         *,
         is_owner: bool = True,
-    ) -> dict:
-        """Get bill payment history."""
+    ) -> list[BillHistoryEntry]:
+        """Get bill payment history as typed models (most recent first)."""
         data = {
             "contractAccount": account_number,
             "isOwnedAccount": "true" if is_owner else "false",
             "usrInf": self._legacy_transport.base_user_info(),
         }
         result = await self._legacy_transport.post("GetBillHistory", data)
-        return result.get("data") or result
+        raw = result.get("data")
+        if isinstance(raw, list):
+            return [
+                BillHistoryEntry.model_validate(item)
+                for item in raw
+                if isinstance(item, dict)
+            ]
+        # ``data`` absent/empty is a legitimate "no bill history"; anything else
+        # is an unexpected shape worth surfacing when debugging (but not worth
+        # failing the whole account fetch over).
+        if raw is not None:
+            logger.debug(
+                "Unexpected GetBillHistory 'data' payload type: %s",
+                type(raw).__name__,
+            )
+        return []
 
     async def get_current_usage(self, account_number: str) -> dict:
         """Get a simplified summary of current usage."""

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/src/mytnb/models.py

@@ -2,10 +2,45 @@
 
 from __future__ import annotations
 
+from datetime import date as date_cls
+from datetime import datetime
 from typing import Any, Optional
 
 from pydantic import AliasChoices, BaseModel, Field, field_validator
 
+# myTNB returns dates as DD/MM/YYYY; keep ISO variants as fallbacks.
+_API_DATE_FORMATS = ("%d/%m/%Y", "%Y-%m-%d", "%d-%m-%Y")
+
+
+def parse_api_date(value: Any) -> Optional[date_cls]:
+    """Parse a myTNB date string (typically DD/MM/YYYY) into a date.
+
+    Returns None for empty/None/unparseable input so a single bad field never
+    breaks an entire response.
+    """
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date_cls):
+        return value
+    if not isinstance(value, str) or not value.strip():
+        return None
+    for fmt in _API_DATE_FORMATS:
+        try:
+            return datetime.strptime(value.strip(), fmt).date()
+        except ValueError:
+            continue
+    return None
+
+
+def _parse_optional_float(value: Any) -> Optional[float]:
+    """Coerce a myTNB numeric string to float, or None if absent/invalid."""
+    if value is None or value == "":
+        return None
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return None
+
 
 class TariffBlock(BaseModel):
     """A tariff block within a billing period."""
@@ -372,3 +407,62 @@ class CustomerAccount(BaseModel):
         """isPaid as a boolean."""
         # pylint: disable=no-member
         return self.is_paid.lower() == "true"
+
+
+class BillHistoryEntry(BaseModel):
+    """A single bill payment history entry from GetBillHistory.
+
+    Raw shape: {"DtBill": "31/05/2026", "AmPayable": "87.50", "BillingNo": "12345"}
+    """
+
+    date: Optional[date_cls] = Field(default=None, alias="DtBill")
+    amount: Optional[float] = Field(default=None, alias="AmPayable")
+    billing_no: str = Field(default="", alias="BillingNo")
+
+    model_config = {"populate_by_name": True, "extra": "ignore"}
+
+    @field_validator("date", mode="before")
+    @classmethod
+    def _parse_date(cls, v: Any) -> Optional[date_cls]:
+        return parse_api_date(v)
+
+    @field_validator("amount", mode="before")
+    @classmethod
+    def _parse_amount(cls, v: Any) -> Optional[float]:
+        return _parse_optional_float(v)
+
+    @field_validator("billing_no", mode="before")
+    @classmethod
+    def _coerce_billing_no(cls, v: Any) -> str:
+        return "" if v is None else str(v)
+
+
+class AccountDueAmount(BaseModel):
+    """Outstanding balance for an account from GetAccountDueAmount.
+
+    Raw shape: {"AccountAmountDue": {"amountDue": "12.34", "billDueDate": "..."}}
+    """
+
+    amount_due: Optional[float] = Field(default=None, alias="amountDue")
+    due_date: Optional[date_cls] = Field(default=None, alias="billDueDate")
+
+    model_config = {"populate_by_name": True, "extra": "ignore"}
+
+    @field_validator("amount_due", mode="before")
+    @classmethod
+    def _parse_amount(cls, v: Any) -> Optional[float]:
+        return _parse_optional_float(v)
+
+    @field_validator("due_date", mode="before")
+    @classmethod
+    def _parse_due_date(cls, v: Any) -> Optional[date_cls]:
+        return parse_api_date(v)
+
+    @classmethod
+    def from_api_response(cls, data: Any) -> "AccountDueAmount":
+        """Parse the (optionally AccountAmountDue-wrapped) due payload."""
+        if isinstance(data, dict):
+            inner = data.get("AccountAmountDue", data)
+            if isinstance(inner, dict):
+                return cls.model_validate(inner)
+        return cls()

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/tests/test_models.py

@@ -2,8 +2,12 @@
 
 # pylint: disable=duplicate-code
 
+from datetime import date, datetime
+
 from mytnb.models import (
+    AccountDueAmount,
     AccountUsage,
+    BillHistoryEntry,
     BillingMonth,
     BREligibility,
     CustomerAccount,
@@ -511,3 +515,71 @@ class TestTariffBlockLegendGroup:
     def test_empty(self):
         group = TariffBlockLegendGroup.model_validate({"TariffBlocksLegend": []})
         assert group.items == []
+
+
+class TestBillHistoryEntry:
+    def test_parse_ddmmyyyy(self):
+        entry = BillHistoryEntry.model_validate(
+            {"DtBill": "31/05/2026", "AmPayable": "87.50", "BillingNo": "12345"}
+        )
+        assert entry.date == date(2026, 5, 31)
+        assert entry.amount == 87.50
+        assert entry.billing_no == "12345"
+
+    def test_parse_iso_fallback(self):
+        entry = BillHistoryEntry.model_validate(
+            {"DtBill": "2026-05-31", "AmPayable": "10"}
+        )
+        assert entry.date == date(2026, 5, 31)
+        assert entry.amount == 10.0
+        assert entry.billing_no == ""
+
+    def test_unparseable_date_is_none(self):
+        entry = BillHistoryEntry.model_validate(
+            {"DtBill": "not-a-date", "AmPayable": "5.0"}
+        )
+        assert entry.date is None
+
+    def test_missing_and_null_fields(self):
+        entry = BillHistoryEntry.model_validate(
+            {"DtBill": None, "AmPayable": "", "BillingNo": None}
+        )
+        assert entry.date is None
+        assert entry.amount is None
+        assert entry.billing_no == ""
+
+    def test_populate_by_name(self):
+        entry = BillHistoryEntry(date=date(2026, 1, 1), amount=1.0, billing_no="9")
+        assert entry.date == date(2026, 1, 1)
+
+    def test_datetime_input_narrowed_to_date(self):
+        # A datetime must be narrowed to date (it subclasses date), not leak through.
+        entry = BillHistoryEntry.model_validate(
+            {"DtBill": datetime(2026, 5, 31, 14, 30), "AmPayable": "1.0"}
+        )
+        assert entry.date == date(2026, 5, 31)
+        assert not isinstance(entry.date, datetime)
+
+
+class TestAccountDueAmount:
+    def test_from_wrapped_response(self):
+        due = AccountDueAmount.from_api_response(
+            {"AccountAmountDue": {"amountDue": "12.34", "billDueDate": "30/06/2026"}}
+        )
+        assert due.amount_due == 12.34
+        assert due.due_date == date(2026, 6, 30)
+
+    def test_from_unwrapped_response(self):
+        due = AccountDueAmount.from_api_response(
+            {"amountDue": "5.00", "billDueDate": "2026-06-30"}
+        )
+        assert due.amount_due == 5.0
+        assert due.due_date == date(2026, 6, 30)
+
+    def test_empty_and_invalid(self):
+        assert AccountDueAmount.from_api_response(None).amount_due is None
+        due = AccountDueAmount.from_api_response(
+            {"amountDue": None, "billDueDate": "bad"}
+        )
+        assert due.amount_due is None
+        assert due.due_date is None

{python_mytnb-0.3.0 → python_mytnb-0.5.0}/uv.lock

@@ -270,7 +270,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -600,28 +600,33 @@ wheels = [
 
 [[package]]
 name = "python-mytnb"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
-    { name = "click" },
     { name = "cryptography" },
     { name = "curl-cffi" },
     { name = "httpx" },
     { name = "pydantic" },
-    { name = "rich" },
 ]
 
 [package.optional-dependencies]
+cli = [
+    { name = "click" },
+    { name = "rich" },
+]
 dev = [
+    { name = "click" },
     { name = "pylint" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
+    { name = "rich" },
     { name = "ruff" },
 ]
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.3.3" },
+    { name = "click", marker = "extra == 'cli'", specifier = ">=8.3.3" },
+    { name = "click", marker = "extra == 'dev'", specifier = ">=8.3.3" },
     { name = "cryptography", specifier = ">=42.0" },
     { name = "curl-cffi", specifier = ">=0.7" },
     { name = "httpx", specifier = ">=0.27" },
@@ -629,10 +634,11 @@ requires-dist = [
     { name = "pylint", marker = "extra == 'dev'", specifier = ">=3.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.21" },
-    { name = "rich", specifier = ">=15.0.0" },
+    { name = "rich", marker = "extra == 'cli'", specifier = ">=15.0.0" },
+    { name = "rich", marker = "extra == 'dev'", specifier = ">=15.0.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.6" },
 ]
-provides-extras = ["dev"]
+provides-extras = ["cli", "dev"]
 
 [[package]]
 name = "rich"