python-mytnb 0.1.0__py3-none-any.whl

mytnb/__init__.py

@@ -0,0 +1,26 @@
+"""Python library for the myTNB API."""
+
+from mytnb.client import MyTNBClient
+from mytnb.crypto import EncryptedPayload, encrypt_request
+from mytnb.models import (
+    AccountUsage,
+    BillingMonth,
+    CostMetric,
+    DailyUsage,
+    Metric,
+    TariffBlock,
+    UsageMetric,
+)
+
+__all__ = [
+    "MyTNBClient",
+    "EncryptedPayload",
+    "encrypt_request",
+    "AccountUsage",
+    "BillingMonth",
+    "CostMetric",
+    "DailyUsage",
+    "Metric",
+    "TariffBlock",
+    "UsageMetric",
+]

mytnb/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m mytnb`."""
+
+from mytnb.cli import main
+
+main()

mytnb/auth.py

@@ -0,0 +1,67 @@
+"""Authentication handling for myTNB API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class DeviceInfo:
+    """Device information sent with API requests."""
+
+    device_id: str
+    app_version: str = "4.0.2"
+    os_type: str = "2"  # 1=Android, 2=iOS
+    os_version: str = "18.0"
+    device_desc: str = "EN"
+    version_code: str = "1425"
+
+    def to_dict(self) -> dict:
+        return {
+            "deviceId": self.device_id,
+            "appVersion": self.app_version,
+            "osType": self.os_type,
+            "osVersion": self.os_version,
+            "deviceDesc": self.device_desc,
+            "versionCode": self.version_code,
+        }
+
+
+@dataclass
+class UserInfo:
+    """User information for authenticated requests."""
+
+    user_name: str
+    user_id: str
+    display_name: str = ""
+    role_id: str = "16"
+    language: str = "EN"
+
+    def to_dict(self) -> dict:
+        return {
+            "RoleId": self.role_id,
+            "UserId": self.user_id,
+            "UserName": self.user_name,
+            "Lang": self.language,
+        }
+
+
+@dataclass
+class Credentials:
+    """API credentials for myTNB."""
+
+    # REST API (api.mytnb.com.my)
+    api_key: str
+    authorization_token: str
+    # Optional bearer token for some endpoints
+    bearer_token: Optional[str] = None
+    # Channel API key (static JWT)
+    channel_api_key: Optional[str] = None
+
+    # Legacy API (mytnbapp.tnb.com.my)
+    secure_key: Optional[str] = None
+
+    # User context
+    user_info: Optional[UserInfo] = None
+    device_info: Optional[DeviceInfo] = None

mytnb/cli.py

@@ -0,0 +1,379 @@
+"""Command-line interface for myTNB API."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.json import JSON
+from rich.panel import Panel
+from rich.table import Table
+
+from mytnb.auth import Credentials, DeviceInfo, UserInfo
+from mytnb.client import MyTNBClient
+from mytnb.exceptions import MyTNBError
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+# ─── Exception handling ──────────────────────────────────────────────────────
+
+
+def _handle_exception(debug: bool, exc: BaseException) -> None:
+    """Handle exceptions with nice output."""
+    if isinstance(exc, click.ClickException):
+        raise exc
+    if isinstance(exc, click.exceptions.Exit):
+        sys.exit(exc.code)
+    if isinstance(exc, click.exceptions.Abort):
+        sys.exit(0)
+
+    if isinstance(exc, MyTNBError):
+        code = f" [{exc.error_code}]" if exc.error_code else ""
+        err_console.print(f"[bold red]Error[/] ({type(exc).__name__}{code}): {exc}")
+    else:
+        err_console.print(f"[bold red]Error[/]: {exc}")
+
+    if debug:
+        err_console.print_exception()
+    else:
+        err_console.print("[dim]Run with --debug to see the full traceback[/]")
+    sys.exit(1)
+
+
+class CatchAllGroup(click.Group):
+    """Click Group that catches all exceptions and prints them nicely."""
+
+    def invoke(self, ctx: click.Context):
+        try:
+            return super().invoke(ctx)
+        except Exception as exc:
+            _handle_exception(ctx.params.get("debug", False), exc)
+            return None
+
+    def main(self, *args, **kwargs):
+        try:
+            return super().main(*args, **kwargs)
+        except KeyboardInterrupt:
+            err_console.print("\n[yellow]Aborted![/]")
+            sys.exit(1)
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+
+
+def _load_config(path: str | None = None) -> dict:
+    """Load credentials from a JSON config file."""
+    candidates = []
+    if path:
+        candidates.append(Path(path))
+    if env := os.environ.get("MYTNB_CONFIG"):
+        candidates.append(Path(env))
+    candidates.append(Path("mytnb.json"))
+    candidates.append(Path.home() / ".config" / "mytnb" / "config.json")
+
+    for p in candidates:
+        if p.is_file():
+            with open(p, encoding="utf-8") as f:
+                return json.load(f)
+
+    return {}
+
+
+def _build_credentials(cfg: dict) -> Credentials:
+    """Build Credentials from a config dict."""
+    user_info = None
+    if "user" in cfg:
+        u = cfg["user"]
+        user_info = UserInfo(
+            user_name=u.get("user_name", ""),
+            user_id=u.get("user_id", ""),
+            language=u.get("language", "EN"),
+        )
+
+    device_info = None
+    if "device" in cfg:
+        d = cfg["device"]
+        device_info = DeviceInfo(
+            device_id=d.get("device_id", ""),
+            app_version=d.get("app_version", "4.0.2"),
+            os_type=d.get("os_type", "2"),
+        )
+
+    return Credentials(
+        api_key=cfg.get("api_key", ""),
+        authorization_token=cfg.get("authorization_token", ""),
+        bearer_token=cfg.get("bearer_token"),
+        channel_api_key=cfg.get("channel_api_key"),
+        secure_key=cfg.get("secure_key"),
+        user_info=user_info,
+        device_info=device_info,
+    )
+
+
+def _to_json(data: object) -> str:
+    """Serialize any object to JSON string."""
+    if hasattr(data, "model_dump"):
+        data = data.model_dump()
+    elif hasattr(data, "__dict__") and not isinstance(data, dict):
+        data = data.__dict__
+    return json.dumps(data, indent=2, default=str)
+
+
+def _print_json(data: object) -> None:
+    """Pretty-print any object as highlighted JSON."""
+    console.print(JSON(_to_json(data)))
+
+
+def _run_async(coro):
+    """Run an async coroutine."""
+    return asyncio.run(coro)
+
+
+async def _get_client(ctx: click.Context) -> MyTNBClient:
+    """Build and return a MyTNBClient from CLI context."""
+    email = ctx.obj.get("email")
+    password = ctx.obj.get("password")
+    config_path = ctx.obj.get("config")
+
+    if email and password:
+        with console.status("[bold green]Logging in..."):
+            return await MyTNBClient.login(email, password)
+
+    cfg = _load_config(config_path)
+    if not cfg:
+        raise click.UsageError(
+            "No credentials. Use --email/--password, set MYTNB_EMAIL/MYTNB_PASSWORD "
+            "env vars, or create a config file (run: mytnb init-config)"
+        )
+    creds = _build_credentials(cfg)
+    staging = cfg.get("staging", False)
+    return MyTNBClient(creds, use_staging_key=staging)
+
+
+# ─── CLI definition ─────────────────────────────────────────────────────────
+
+
+@click.group(cls=CatchAllGroup)
+@click.option("-c", "--config", help="Path to config JSON file.")
+@click.option("-e", "--email", envvar="MYTNB_EMAIL", help="myTNB account email.")
+@click.option("-p", "--password", envvar="MYTNB_PASSWORD", help="myTNB account password.")
+@click.option("--debug", is_flag=True, help="Show full traceback on errors.")
+@click.version_option(package_name="python-mytnb")
+@click.pass_context
+def cli(ctx, config, email, password, debug):
+    """CLI for the myTNB API (Tenaga Nasional Berhad)."""
+    ctx.ensure_object(dict)
+    ctx.obj["config"] = config
+    ctx.obj["email"] = email
+    ctx.obj["password"] = password
+    ctx.obj["debug"] = debug
+
+
+@cli.command()
+@click.pass_context
+def login(ctx):
+    """Test login and show user info."""
+
+    async def _login():
+        client = await _get_client(ctx)
+        async with client:
+            ui = client.credentials.user_info
+            table = Table(title="Login Successful", show_header=False)
+            table.add_column("Field", style="bold cyan")
+            table.add_column("Value")
+            table.add_row("User ID", ui.user_id)
+            table.add_row("Email", ui.user_name)
+            table.add_row("Display Name", getattr(ui, "display_name", "") or "")
+            console.print(table)
+
+    _run_async(_login())
+
+
+@cli.command()
+@click.argument("account")
+@click.option("--json", "as_json", is_flag=True, help="Output full JSON instead of table.")
+@click.option("--daily", is_flag=True, help="Show daily usage breakdown instead of monthly.")
+@click.pass_context
+def usage(ctx, account, as_json, daily):
+    """Get smart meter usage & billing data."""
+
+    async def _usage():
+        client = await _get_client(ctx)
+        async with client:
+            with console.status("[bold green]Fetching usage data..."):
+                result = await client.get_account_usage_smart(account)
+
+            if as_json:
+                _print_json(result)
+                return
+
+            if daily:
+                # Show daily usage table
+                for period in result.by_day:
+                    table = Table(title=f"Daily Usage — {period.range}")
+                    table.add_column("Date", style="cyan")
+                    table.add_column("Usage (kWh)", justify="right")
+                    table.add_column("Cost (RM)", justify="right", style="green")
+                    for day in period.days:
+                        table.add_row(
+                            day.date,
+                            day.consumption or "0",
+                            day.amount or "0.00",
+                        )
+                    console.print(table)
+                    console.print()
+                return
+
+            # Show monthly summary table
+            table = Table(title=f"Usage — {account}")
+            table.add_column("Month", style="cyan")
+            table.add_column("Usage (kWh)", justify="right")
+            table.add_column("Amount (RM)", justify="right", style="green")
+
+            if result.by_month:
+                for m in result.by_month.months:
+                    table.add_row(
+                        f"{m.month} {m.year}",
+                        m.usage_total or "--",
+                        m.amount_total or "--",
+                    )
+
+            console.print(table)
+
+            # Current usage metrics
+            if result.usage_metrics or result.cost_metrics:
+                console.print()
+                for metric in result.usage_metrics:
+                    if metric.value and metric.value != "--":
+                        console.print(f"  [cyan]{metric.title}:[/] {metric.value} {metric.value_unit}")
+                for metric in result.cost_metrics:
+                    if metric.value and metric.value != "--":
+                        console.print(f"  [green]{metric.title}:[/] {metric.value_unit} {metric.value}")
+
+    _run_async(_usage())
+
+
+@cli.command("current-usage")
+@click.argument("account")
+@click.pass_context
+def current_usage(ctx, account):
+    """Get simplified current usage summary."""
+
+    async def _current():
+        client = await _get_client(ctx)
+        async with client:
+            with console.status("[bold green]Fetching..."):
+                result = await client.get_current_usage(account)
+            _print_json(result)
+
+    _run_async(_current())
+
+
+@cli.command("due-amount")
+@click.argument("account")
+@click.option("--json", "as_json", is_flag=True, help="Output full JSON.")
+@click.pass_context
+def due_amount(ctx, account, as_json):
+    """Get account outstanding balance."""
+
+    async def _due():
+        client = await _get_client(ctx)
+        async with client:
+            with console.status("[bold green]Fetching..."):
+                result = await client.get_account_due_amount(account)
+
+            if 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)
+
+    _run_async(_due())
+
+
+@cli.command("bill-history")
+@click.argument("account")
+@click.option("--json", "as_json", is_flag=True, help="Output full JSON.")
+@click.pass_context
+def bill_history(ctx, account, as_json):
+    """Get bill payment history."""
+
+    async def _history():
+        client = await _get_client(ctx)
+        async with client:
+            with console.status("[bold green]Fetching..."):
+                result = await client.get_bill_history(account)
+
+            if 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)
+
+    _run_async(_history())
+
+
+@cli.command("init-config")
+@click.option("-o", "--output", default="mytnb.json", help="Output path.")
+def init_config(output):
+    """Generate a starter config file."""
+    target = Path(output)
+    if target.exists():
+        raise click.ClickException(f"{target} already exists")
+
+    template = {
+        "api_key": "",
+        "authorization_token": "",
+        "secure_key": "",
+        "user": {
+            "user_name": "",
+            "user_id": "",
+            "language": "EN",
+        },
+        "device": {
+            "device_id": "",
+            "app_version": "4.0.2",
+            "os_type": "2",
+        },
+    }
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with open(target, "w", encoding="utf-8") as f:
+        json.dump(template, f, indent=2)
+    console.print(f"[green]Config written to[/] {target}")
+
+
+def main() -> None:
+    cli()  # pylint: disable=no-value-for-parameter
+
+
+if __name__ == "__main__":
+    main()

mytnb/client/__init__.py

@@ -0,0 +1,3 @@
+from mytnb.client.client import MyTNBClient
+
+__all__ = ["MyTNBClient"]

mytnb/client/auth.py

@@ -0,0 +1,159 @@
+"""Authentication login flow for myTNB."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import re
+import uuid
+from typing import TYPE_CHECKING
+
+import httpx
+
+from mytnb.auth import Credentials, DeviceInfo, UserInfo
+from mytnb.client.config import (
+    DEFAULT_API_KEY,
+    REST_BASE_URL,
+    SITECORE_LOGIN_URL,
+    SSO_HANDLER_URL,
+    USER_AGENT,
+)
+from mytnb.exceptions import AuthenticationError, GeoBlockedError
+
+if TYPE_CHECKING:
+    from mytnb.client.client import MyTNBClient
+
+logger = logging.getLogger(__name__)
+
+
+async def login(
+    cls: type[MyTNBClient],
+    email: str,
+    password: str,
+    *,
+    device_id: str | None = None,
+    timeout: float = 30.0,
+    use_staging_key: bool = False,
+) -> MyTNBClient:
+    """Authenticate with email and password, returning a ready-to-use client.
+
+    Performs the full login flow:
+    1. Authenticate via Sitecore web login (plaintext credentials)
+    2. Submit SSO form to get user identity (userId)
+    3. Generate an access token via the REST Identity API
+    """
+    if not device_id:
+        device_id = str(uuid.uuid4()).upper()
+
+    device_info = DeviceInfo(device_id=device_id)
+
+    async with httpx.AsyncClient(
+        follow_redirects=False,
+        timeout=timeout,
+        headers={"User-Agent": USER_AGENT},
+    ) as http:
+        await http.get("https://www.mytnb.com.my/")
+
+        login_resp = await http.post(
+            SITECORE_LOGIN_URL,
+            data={"Email": email, "Password": password},
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Origin": "https://www.mytnb.com.my",
+                "Referer": "https://www.mytnb.com.my/",
+            },
+        )
+        logger.info("Sitecore login response: %s", login_resp.status_code)
+
+        if login_resp.status_code == 403:
+            raise GeoBlockedError()
+        if login_resp.status_code != 200:
+            raise AuthenticationError(
+                "Login failed",
+                error_code=str(login_resp.status_code),
+            )
+
+        sso_fields = dict(
+            re.findall(
+                r'name="([^"]+)"\s+value="([^"]*)"',
+                login_resp.text,
+            )
+        )
+        if "USERNAME" not in sso_fields:
+            raise AuthenticationError(
+                "Invalid credentials or unexpected login response",
+                error_code="LOGIN_FAILED",
+            )
+
+        sso_resp = await http.post(
+            SSO_HANDLER_URL,
+            data=sso_fields,
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Origin": "https://www.mytnb.com.my",
+            },
+        )
+
+        if sso_resp.status_code != 200:
+            raise AuthenticationError(
+                "SSO authentication failed",
+                error_code=str(sso_resp.status_code),
+            )
+
+        user_id = None
+        user_name = email
+        display_name = ""
+        for cookie_header in sso_resp.headers.get_list("set-cookie"):
+            if "eyJhbGci" not in cookie_header:
+                continue
+            jwt_match = re.search(r"=(eyJ[^;]+)", cookie_header)
+            if not jwt_match:
+                continue
+            parts = jwt_match.group(1).split(".")
+            payload_b64 = parts[1] + "=" * (4 - len(parts[1]) % 4)
+            jwt_data = json.loads(base64.b64decode(payload_b64))
+            ui = json.loads(jwt_data["UserInfo"])
+            user_id = ui["UserId"]
+            user_name = ui.get("UserName", email)
+            display_name = ui.get("DisplayName", "")
+            break
+
+        if not user_id:
+            raise AuthenticationError(
+                "Failed to extract user identity from SSO response",
+                error_code="SSO_PARSE_FAILED",
+            )
+
+        token_resp = await http.post(
+            f"{REST_BASE_URL}/Identity/api/v1/Identity/GenerateAccessToken",
+            headers={
+                "Content-Type": "application/json",
+                "x-api-key": DEFAULT_API_KEY,
+                "Accept": "application/json",
+            },
+            params={"environment": "Prod"},
+            json={
+                "channel": "myTNB_API_Mobile",
+                "userId": user_id,
+            },
+        )
+        token_resp.raise_for_status()
+        token_data = token_resp.json()
+        access_token = token_data["content"]["accessToken"]
+
+    secure_key = str(uuid.uuid4()).upper()
+
+    credentials = Credentials(
+        api_key=DEFAULT_API_KEY,
+        authorization_token=access_token,
+        secure_key=secure_key,
+        user_info=UserInfo(
+            user_name=user_name,
+            user_id=user_id,
+            display_name=display_name,
+        ),
+        device_info=device_info,
+    )
+
+    return cls(credentials, timeout=timeout, use_staging_key=use_staging_key)