python-mytnb 0.1.0__py3-none-any.whl

mytnb/exceptions.py

@@ -0,0 +1,47 @@
+"""Custom exceptions for the myTNB API client."""
+
+from __future__ import annotations
+
+
+class MyTNBError(Exception):
+    """Base exception for myTNB API errors."""
+
+    def __init__(self, message: str, error_code: str | None = None):
+        self.error_code = error_code
+        super().__init__(message)
+
+
+class AuthenticationError(MyTNBError):
+    """Raised when authentication fails."""
+
+
+class APIError(MyTNBError):
+    """Raised when the API returns an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        error_code: str | None = None,
+        display_message: str | None = None,
+    ):
+        self.display_message = display_message
+        super().__init__(message, error_code)
+
+
+class RateLimitError(MyTNBError):
+    """Raised when rate limited by the API."""
+
+
+class GeoBlockedError(MyTNBError):
+    """Raised when the request is blocked due to geographic restrictions.
+
+    The myTNB API only allows connections from Malaysian IP addresses
+    and blocks most VPNs.
+    """
+
+    def __init__(self):
+        super().__init__(
+            "Access denied — the myTNB API is restricted to Malaysian IP addresses "
+            "and blocks VPN connections. Connect from a Malaysian network without a VPN.",
+            error_code="403",
+        )

mytnb/models.py

@@ -0,0 +1,236 @@
+"""Data models for myTNB API responses."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TariffBlock(BaseModel):
+    """A tariff block within a billing period."""
+
+    block_id: str = Field(alias="BlockId")
+    amount: float = Field(alias="Amount")
+    usage: float = Field(alias="Usage")
+    is_block_available: bool = Field(alias="IsBlockAvailable")
+    block_pricing: Optional[str] = Field(default=None, alias="BlockPricing")
+    peak_usage: Optional[str] = Field(default=None, alias="PeakUsage")
+    off_peak_usage: Optional[str] = Field(default=None, alias="OffPeakUsage")
+    start_date: Optional[str] = Field(default=None, alias="StartDate")
+    end_date: Optional[str] = Field(default=None, alias="EndDate")
+
+    model_config = {"populate_by_name": True}
+
+
+class Metric(BaseModel):
+    """A usage or cost metric returned by the myTNB API."""
+
+    key: str = Field(alias="Key")
+    title: str = Field(alias="Title")
+    sub_title: str = Field(alias="SubTitle")
+    value: str = Field(alias="Value")
+    value_unit: str = Field(alias="ValueUnit")
+    value_indicator: str = Field(default="", alias="ValueIndicator")
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def numeric_value(self) -> float:
+        try:
+            return float(self.value)
+        except (ValueError, TypeError):
+            return 0.0
+
+
+UsageMetric = Metric  # backward-compatible alias
+CostMetric = Metric  # backward-compatible alias
+
+
+class DailyUsage(BaseModel):
+    """Daily electricity usage data."""
+
+    date: str = Field(alias="Date")
+    year: str = Field(alias="Year")
+    month: str = Field(alias="Month")
+    day: str = Field(alias="Day")
+    consumption: str = Field(alias="Consumption")
+    amount: str = Field(alias="Amount")
+    is_estimated_reading: bool = Field(default=False, alias="IsEstimatedReading")
+    is_missing_reading: bool = Field(default=False, alias="IsMissingReading")
+    is_current_bill_cycle: bool = Field(default=False, alias="IsCurrentBillCycle")
+    tariff_blocks: list[TariffBlock] = Field(default_factory=list, alias="tariffBlocks")
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def consumption_kwh(self) -> float:
+        return float(self.consumption)
+
+    @property
+    def amount_rm(self) -> float:
+        return float(self.amount)
+
+
+class DailyUsageWeek(BaseModel):
+    """A week range of daily usage data."""
+
+    range: str = Field(alias="Range")
+    days: list[DailyUsage] = Field(default_factory=list, alias="Days")
+
+    model_config = {"populate_by_name": True}
+
+
+class RP4Usage(BaseModel):
+    """RP4 tariff usage breakdown."""
+
+    block_id: str = Field(alias="BlockId")
+    amount: str = Field(alias="Amount")
+    usage: str = Field(alias="Usage")
+    is_block_available: bool = Field(default=False, alias="IsBlockAvailable")
+    peak_usage: Optional[str] = Field(default=None, alias="PeakUsage")
+    off_peak_usage: Optional[str] = Field(default=None, alias="OffPeakUsage")
+    start_date: Optional[str] = Field(default=None, alias="StartDate")
+    end_date: Optional[str] = Field(default=None, alias="EndDate")
+
+    model_config = {"populate_by_name": True}
+
+
+class MonthlyTariffBlock(BaseModel):
+    """Tariff block for monthly billing."""
+
+    block_id: str = Field(alias="BlockId")
+    amount: float = Field(alias="Amount")
+    usage: float = Field(alias="Usage")
+    is_block_available: bool = Field(alias="IsBlockAvailable")
+    block_pricing: Optional[str] = Field(default=None, alias="BlockPricing")
+    rp4_usage: Optional[list[RP4Usage]] = Field(default=None, alias="RP4Usage")
+
+    model_config = {"populate_by_name": True}
+
+
+class BillingMonth(BaseModel):
+    """Monthly billing data."""
+
+    billing_no: Optional[str] = Field(default=None, alias="BillingNo")
+    date: str = Field(alias="Date")
+    year: str = Field(alias="Year")
+    month: str = Field(alias="Month")
+    day: str = Field(alias="Day")
+    amount_total: str = Field(alias="AmountTotal")
+    usage_total: str = Field(alias="UsageTotal")
+    currency: str = Field(default="RM", alias="Currency")
+    usage_unit: str = Field(default="kWh", alias="UsageUnit")
+    is_estimated_reading: bool = Field(default=False, alias="IsEstimatedReading")
+    is_unbilled: bool = Field(default=False, alias="IsUnbilled")
+    tariff_blocks: list[MonthlyTariffBlock] = Field(
+        default_factory=list, alias="tariffBlocks"
+    )
+    billing_start_date: Optional[str] = Field(default=None, alias="BillingStartDate")
+    billing_end_date: Optional[str] = Field(default=None, alias="BillingEndDate")
+    has_periodic_billing: bool = Field(default=False, alias="HasPeriodicBilling")
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def amount_rm(self) -> float:
+        return float(self.amount_total)
+
+    @property
+    def usage_kwh(self) -> float:
+        return float(self.usage_total)
+
+
+class ByMonthData(BaseModel):
+    """Monthly billing history."""
+
+    range: str = Field(alias="Range")
+    months: list[BillingMonth] = Field(default_factory=list, alias="Months")
+
+    model_config = {"populate_by_name": True}
+
+
+class AccountUsage(BaseModel):
+    """Full account usage response from GetAccountUsageSmart."""
+
+    usage_metrics: list[Metric] = Field(default_factory=list)
+    cost_metrics: list[Metric] = Field(default_factory=list)
+    current_cycle_start_date: Optional[str] = None
+    by_month: Optional[ByMonthData] = None
+    by_day: list[DailyUsageWeek] = Field(default_factory=list)
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+    date_range: Optional[str] = None
+
+    @classmethod
+    def from_api_response(cls, data: dict) -> "AccountUsage":
+        """Parse the API response data into an AccountUsage model."""
+        other_usage = data.get("OtherUsageMetrics", {})
+        usage_list = other_usage.get("Usage", [])
+        cost_list = other_usage.get("Cost", [])
+
+        usage_metrics = [Metric.model_validate(u) for u in usage_list]
+        cost_metrics = [Metric.model_validate(c) for c in cost_list]
+
+        by_month_raw = data.get("ByMonth")
+        by_month = ByMonthData.model_validate(by_month_raw) if by_month_raw else None
+
+        by_day_raw = data.get("ByDay", [])
+        by_day = [DailyUsageWeek.model_validate(w) for w in by_day_raw]
+
+        return cls(
+            usage_metrics=usage_metrics,
+            cost_metrics=cost_metrics,
+            current_cycle_start_date=other_usage.get("CurrentCycleStartDate"),
+            by_month=by_month,
+            by_day=by_day,
+            start_date=data.get("StartDate"),
+            end_date=data.get("EndDate"),
+            date_range=data.get("DateRange"),
+        )
+
+    @property
+    def current_usage_kwh(self) -> Optional[float]:
+        for m in self.usage_metrics:
+            if m.key == "CURRENTUSAGE":
+                return m.numeric_value
+        return None
+
+    @property
+    def current_cost_rm(self) -> Optional[float]:
+        for m in self.cost_metrics:
+            if m.key == "CURRENTCOST":
+                return m.numeric_value
+        return None
+
+    @property
+    def projected_cost_rm(self) -> Optional[float]:
+        for m in self.cost_metrics:
+            if m.key == "PROJECTEDCOST":
+                return m.numeric_value
+        return None
+
+
+class SMRAccount(BaseModel):
+    """Smart Meter Reading account status."""
+
+    contract_account: str = Field(alias="ContractAccount")
+    smr_eligibility: str = Field(alias="SMREligibility")
+    is_tagged_smr: str = Field(alias="IsTaggedSMR")
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def is_smart_meter(self) -> bool:
+        return self.is_tagged_smr.lower() == "true"  # pylint: disable=no-member
+
+
+class BREligibility(BaseModel):
+    """Bill Rendering eligibility indicator."""
+
+    ca_no: str = Field(alias="caNo")
+    is_owner_over_rule: bool = Field(default=False, alias="isOwnerOverRule")
+    is_owner_already_opt_in: bool = Field(default=False, alias="isOwnerAlreadyOptIn")
+    is_tenant_already_opt_in: bool = Field(default=False, alias="isTenantAlreadyOptIn")
+
+    model_config = {"populate_by_name": True}

python_mytnb-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: python-mytnb
+Version: 0.1.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
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+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: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tls-client>=1.0
+Provides-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: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-mytnb
+
+A Python library to interface with the myTNB (Tenaga Nasional Berhad) API for electricity account management and usage monitoring in Malaysia.
+
+## Installation
+
+```bash
+uv add python-mytnb
+```
+
+Or with pip:
+
+```bash
+pip install python-mytnb
+```
+
+## Quick Start
+
+```python
+import asyncio
+from mytnb import MyTNBClient
+
+async def main():
+    client = await MyTNBClient.login("user@example.com", "your-password")
+
+    async with client:
+        # Get smart meter usage & billing history
+        usage = await client.get_account_usage_smart("220123456789")
+
+        # Monthly billing breakdown
+        for month in usage.by_month.months:
+            print(f"{month.month} {month.year}: {month.usage_total} kWh — RM {month.amount_total}")
+
+        # Bill history & due amount
+        history = await client.get_bill_history("220123456789")
+        due = await client.get_account_due_amount("220123456789")
+
+asyncio.run(main())
+```
+
+## CLI
+
+Pass credentials directly:
+
+```bash
+mytnb --email user@example.com --password yourpass usage 220123456789
+```
+
+Or via environment variables:
+
+```bash
+export MYTNB_EMAIL=user@example.com
+export MYTNB_PASSWORD=yourpass
+mytnb usage 220123456789
+```
+
+All commands:
+
+```
+mytnb login                                  # Test login, show user info
+mytnb usage <account>                        # Monthly usage & billing summary
+mytnb usage --daily <account>                # Daily usage breakdown
+mytnb usage --json <account>                 # Full usage data as JSON
+mytnb current-usage <account>                # Simplified current usage summary
+mytnb due-amount <account>                   # Outstanding balance
+mytnb bill-history <account>                 # Payment history
+```
+
+Global options: `--debug` for full tracebacks, `--version`.
+
+Use a config file instead of flags (`--config <path>`, `mytnb.json`, or `~/.config/mytnb/config.json`):
+
+```bash
+mytnb init-config   # Generate a starter config file
+```
+
+## API Architecture
+
+myTNB uses two API backends, both handled transparently by this library:
+
+| Backend     | Domain                | Auth                                        | Used for                            |
+| ----------- | --------------------- | ------------------------------------------- | ----------------------------------- |
+| REST        | `api.mytnb.com.my`    | JWT + API key                               | Account listing, eligibility checks |
+| Legacy ASMX | `mytnbapp.tnb.com.my` | Encrypted payloads (AES-256-CBC + RSA-OAEP) | Usage data, billing, services       |
+
+Request encryption for the ASMX API is automatic — just pass plaintext parameters.
+
+## Data Models
+
+| Model           | Description                                          |
+| --------------- | ---------------------------------------------------- |
+| `AccountUsage`  | Full usage response: metrics, monthly and daily data |
+| `UsageMetric`   | Current/average usage (kWh)                          |
+| `CostMetric`    | Current/projected cost (RM)                          |
+| `BillingMonth`  | Monthly billing record with tariff blocks            |
+| `DailyUsage`    | Daily consumption and cost                           |
+| `TariffBlock`   | Tariff pricing block details                         |
+| `SMRAccount`    | Smart Meter Reading eligibility status               |
+| `BREligibility` | Bill rendering opt-in status                         |
+
+## Geographic Restrictions
+
+The myTNB API only accepts connections from **Malaysian IP addresses** and blocks most VPN services. If you get a `GeoBlockedError` (HTTP 403), make sure you are connecting from a Malaysian network without a VPN.
+
+## Error Handling
+
+```python
+from mytnb.exceptions import MyTNBError, APIError, AuthenticationError, GeoBlockedError
+
+try:
+    client = await MyTNBClient.login("user@example.com", "password")
+    async with client:
+        usage = await client.get_account_usage_smart("220123456789")
+except GeoBlockedError:
+    print("Blocked — connect from a Malaysian IP without VPN")
+except AuthenticationError:
+    print("Invalid email or password")
+except APIError as e:
+    print(f"API error {e.error_code}: {e.display_message}")
+except MyTNBError as e:
+    print(f"Error: {e}")
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run pylint src/mytnb/
+```
+
+## License
+
+MIT

python_mytnb-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+mytnb/__init__.py,sha256=XTMrHOGpHL5XSpQ7_jh-cuuwMNrdZAH3eh4QXkuuwjw,489
+mytnb/__main__.py,sha256=JmAjczPoUDep52BmNaMngOBE1IZSfGtQPAvMPzNbpHA,78
+mytnb/auth.py,sha256=KygAcTVb_AXP3ZIcmNt4Jb5vCKfLAPMu2OC9wTaFZBE,1620
+mytnb/cli.py,sha256=2wPLzo75Q6_ZrzPm-Hy2PxIishgt1E4tl1ke6L2KL-w,12649
+mytnb/crypto.py,sha256=E39ZRHQwTl0jbKtITp9vyRMjXjwFVTbscSc-Z1wIYog,5102
+mytnb/exceptions.py,sha256=lpttDB08gRo74e3RoO8ee7AYMdnsRekoWo0VZ2WwiBQ,1283
+mytnb/models.py,sha256=BcC56KkriM1RXmCdT9guVghhqGtX2Gvt_u_jLvbLPCo,8150
+mytnb/client/__init__.py,sha256=k5TEcrevXSts0rcT1Vvzv9qRSawgCfJLKwRWOkCw-y0,71
+mytnb/client/auth.py,sha256=l-BUha0suxncRhMD8bgP4ECZ9ZTHBB3OCC-MZZyG3eE,4861
+mytnb/client/client.py,sha256=zsdv6j_ESMuMK5-qyJs_AL1QueB0FTy2XjmyoFTvtNg,8476
+mytnb/client/config.py,sha256=bQIg3vOjHCXZw3LFrgkopXcm9qA3jBgUyhjM_IHK0kQ,1243
+mytnb/client/legacy.py,sha256=A4etA3ViDafsfulKGSq59OdwpNqX7bXVaNw0yHVmDwk,3739
+mytnb/client/rest.py,sha256=mW9Und9e4cvemTy64uuNRmN4h7Kx0CQ5-K4uRoVnQGI,3794
+python_mytnb-0.1.0.dist-info/METADATA,sha256=fpmak3IGBqg8DcIqjXiA-rNAeWWimi2W08Ct0esPdMQ,5508
+python_mytnb-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_mytnb-0.1.0.dist-info/entry_points.txt,sha256=8Fm6WPzObtoBS3j0vIXSansgPZBREAVgysltc3ypvTk,41
+python_mytnb-0.1.0.dist-info/licenses/LICENSE,sha256=m-85-NGNTFu9N-mdpF0sYLupMloWk6_kcGbQlEmTfpQ,1071
+python_mytnb-0.1.0.dist-info/RECORD,,

python_mytnb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

python_mytnb-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mytnb = mytnb.cli:main

python_mytnb-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Latiff Danieyal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.