tello-usage 2026.0__tar.gz

tello_usage-2026.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Jackson
+
+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.

tello_usage-2026.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: tello-usage
+Version: 2026.0
+Summary: Retrieve data balances and billing cycle information for every line in a Tello Mobile account.
+Author: William Jackson
+Author-email: William Jackson <william@subtlecoolness.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.15.0
+Requires-Dist: httpx2>=2.16.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/williamjacksn/tello-usage
+Project-URL: Issues, https://github.com/williamjacksn/tello-usage/issues
+Description-Content-Type: text/markdown
+
+# tello-usage
+
+tello-usage is a Python package and command-line tool that retrieves data balances for every line in a Tello Mobile
+account. It reports remaining data, percentage available, renewal dates, and days remaining in each billing cycle.
+
+The package uses httpx2 and Beautiful Soup to access Tello Mobile's account pages. It does not require a browser or
+browser automation software.
+
+This is an independent, unofficial package. It is not developed by, affiliated with, or endorsed by Tello Mobile.
+
+## Requirements
+
+The package requires Python 3.11 or later and a Tello Mobile account with an email address and password.
+
+## Installation
+
+Install the command-line tool with uv:
+
+```sh
+uv tool install tello-usage
+```
+
+To use the package in a Python project, add it as a dependency:
+
+```sh
+uv add tello-usage
+```
+
+The distribution is named `tello-usage`. The Python import is named `tello_usage`,
+and the command-line executable is named `tello-usage`.
+
+## Command-line usage
+
+Run the following command to retrieve balances:
+
+```sh
+tello-usage
+```
+
+The command prompts for your Tello Mobile email address and password. The password is hidden while you type.
+
+Each output line includes the account's line label, remaining data, percentage available, and days left in the billing
+cycle:
+
+```text
+(555) 010-0100 - Example: 457.59 MB remaining / 10 GB (4.58% available); 4 days left in billing cycle
+```
+
+Use `--json` to produce JSON output:
+
+```sh
+tello-usage --json
+```
+
+The output contains one object for each line:
+
+```json
+[
+  {
+    "subscription_id": "12345678",
+    "line": "(555) 010-0100 - Example",
+    "remaining": "457.59 MB",
+    "allowance": "10 GB",
+    "renewal_date": "2026-10-23",
+    "percentage_available": 4.58,
+    "days_left": 4
+  }
+]
+```
+
+This example assumes the command runs on October 19, 2026.
+
+If you installed the package as a project dependency, run the command through uv:
+
+```sh
+uv run tello-usage --json
+```
+
+### Credentials
+
+You can supply your email address with `--username`:
+
+```sh
+tello-usage --username you@example.com
+```
+
+The command also accepts the following environment variables:
+
+- `TELLO_USERNAME` supplies the account email address.
+- `TELLO_PASSWORD` supplies the account password.
+
+The `--username` argument takes precedence over `TELLO_USERNAME`. Missing credentials are requested through terminal
+prompts.
+
+For unattended use, supply both credentials through your process environment. You can also provide the email address
+with `--username`. The command exits with an error if credentials are missing and a terminal prompt is unavailable.
+
+There is no password command-line argument. The package does not load `.env` files automatically.
+
+## Python usage
+
+Use `TelloClient` in a `with` statement so its HTTP connections are closed after use:
+
+```python
+import os
+
+from tello_usage import TelloClient
+
+with TelloClient() as client:
+    balances = client.balances(
+        os.environ["TELLO_USERNAME"],
+        os.environ["TELLO_PASSWORD"],
+    )
+
+for balance in balances:
+    print(
+        balance.line,
+        balance.remaining,
+        balance.percentage_available,
+        balance.renewal_date,
+        balance.days_left,
+    )
+```
+
+The synchronous `balances(username, password)` method logs in and returns a list of `Balance` objects.
+
+The default HTTP timeout is 30 seconds. You can override it when creating the client:
+
+```python
+with TelloClient(timeout=60) as client:
+    balances = client.balances(username, password)
+```
+
+### Balance values
+
+Each `Balance` object provides the following values. JSON output uses the same names.
+
+- `subscription_id` is Tello Mobile's identifier for the line.
+- `line` is the label displayed in the account's line selector.
+- `remaining` is the displayed remaining data amount, including its unit.
+- `allowance` is the displayed data allowance, including its unit.
+- `renewal_date` is the data plan's renewal or expiration date in `YYYY-MM-DD` format.
+- `percentage_available` is the remaining data expressed as a percentage of the displayed allowance.
+- `days_left` is the number of calendar days until the renewal date.
+
+The percentage calculation uses the displayed amounts, assumes 1 GB equals 1,000 MB, and rounds the result to two
+decimal places. The result is limited to 0–100 percent. A rollover balance above the allowance therefore reports 100
+percent available.
+
+An unlimited or zero allowance produces `None` for `percentage_available`.
+
+Days remaining are calculated using the computer's local date. A renewal date of today or a date in the past produces
+zero days remaining. This value does not measure the exact number of hours until renewal.
+
+If the account page does not provide a recognized renewal date, `renewal_date` and `days_left` are `None`. Python `None`
+values appear as `null` in JSON.
+
+## Error handling
+
+The client raises `TelloError` when login fails, required account information is missing, a line cannot be selected, or
+a data balance cannot be read. Network and HTTP errors are raised as httpx2 exceptions.
+
+```python
+import os
+
+import httpx2
+from tello_usage import TelloClient, TelloError
+
+try:
+    with TelloClient() as client:
+        balances = client.balances(
+            os.environ["TELLO_USERNAME"],
+            os.environ["TELLO_PASSWORD"],
+        )
+except TelloError as error:
+    print(f"Could not read account balances: {error}")
+except httpx2.HTTPError as error:
+    print(f"The HTTP request failed: {error}")
+```
+
+The command-line tool writes errors to standard error and exits with a nonzero status.
+
+A missing data balance stops the operation without returning partial results. This can occur when a line has no active
+data plan.
+
+## Website access and limitations
+
+The package accesses Tello Mobile's website forms rather than a documented API. It logs in, discovers the account's
+lines, and selects each line to read its balance. It maintains session cookies and reads fresh form tokens between
+requests.
+
+The client changes the selected account line while retrieving balances. It does not purchase data or change plan
+settings.
+
+Changes to Tello Mobile's website, a CAPTCHA, or an additional account verification step may prevent the client from
+working.
+
+Credentials and session cookies are held in memory and are not saved by the package. No HAR recording is required.
+
+## Development
+
+From a source checkout, install dependencies and run the tests with uv:
+
+```sh
+uv sync
+uv run python -m unittest discover -s tests -v
+```
+
+The tests use generated account pages and simulated HTTP responses. They do not require account credentials or make
+requests to Tello Mobile.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

tello_usage-2026.0/README.md

@@ -0,0 +1,214 @@
+# tello-usage
+
+tello-usage is a Python package and command-line tool that retrieves data balances for every line in a Tello Mobile
+account. It reports remaining data, percentage available, renewal dates, and days remaining in each billing cycle.
+
+The package uses httpx2 and Beautiful Soup to access Tello Mobile's account pages. It does not require a browser or
+browser automation software.
+
+This is an independent, unofficial package. It is not developed by, affiliated with, or endorsed by Tello Mobile.
+
+## Requirements
+
+The package requires Python 3.11 or later and a Tello Mobile account with an email address and password.
+
+## Installation
+
+Install the command-line tool with uv:
+
+```sh
+uv tool install tello-usage
+```
+
+To use the package in a Python project, add it as a dependency:
+
+```sh
+uv add tello-usage
+```
+
+The distribution is named `tello-usage`. The Python import is named `tello_usage`,
+and the command-line executable is named `tello-usage`.
+
+## Command-line usage
+
+Run the following command to retrieve balances:
+
+```sh
+tello-usage
+```
+
+The command prompts for your Tello Mobile email address and password. The password is hidden while you type.
+
+Each output line includes the account's line label, remaining data, percentage available, and days left in the billing
+cycle:
+
+```text
+(555) 010-0100 - Example: 457.59 MB remaining / 10 GB (4.58% available); 4 days left in billing cycle
+```
+
+Use `--json` to produce JSON output:
+
+```sh
+tello-usage --json
+```
+
+The output contains one object for each line:
+
+```json
+[
+  {
+    "subscription_id": "12345678",
+    "line": "(555) 010-0100 - Example",
+    "remaining": "457.59 MB",
+    "allowance": "10 GB",
+    "renewal_date": "2026-10-23",
+    "percentage_available": 4.58,
+    "days_left": 4
+  }
+]
+```
+
+This example assumes the command runs on October 19, 2026.
+
+If you installed the package as a project dependency, run the command through uv:
+
+```sh
+uv run tello-usage --json
+```
+
+### Credentials
+
+You can supply your email address with `--username`:
+
+```sh
+tello-usage --username you@example.com
+```
+
+The command also accepts the following environment variables:
+
+- `TELLO_USERNAME` supplies the account email address.
+- `TELLO_PASSWORD` supplies the account password.
+
+The `--username` argument takes precedence over `TELLO_USERNAME`. Missing credentials are requested through terminal
+prompts.
+
+For unattended use, supply both credentials through your process environment. You can also provide the email address
+with `--username`. The command exits with an error if credentials are missing and a terminal prompt is unavailable.
+
+There is no password command-line argument. The package does not load `.env` files automatically.
+
+## Python usage
+
+Use `TelloClient` in a `with` statement so its HTTP connections are closed after use:
+
+```python
+import os
+
+from tello_usage import TelloClient
+
+with TelloClient() as client:
+    balances = client.balances(
+        os.environ["TELLO_USERNAME"],
+        os.environ["TELLO_PASSWORD"],
+    )
+
+for balance in balances:
+    print(
+        balance.line,
+        balance.remaining,
+        balance.percentage_available,
+        balance.renewal_date,
+        balance.days_left,
+    )
+```
+
+The synchronous `balances(username, password)` method logs in and returns a list of `Balance` objects.
+
+The default HTTP timeout is 30 seconds. You can override it when creating the client:
+
+```python
+with TelloClient(timeout=60) as client:
+    balances = client.balances(username, password)
+```
+
+### Balance values
+
+Each `Balance` object provides the following values. JSON output uses the same names.
+
+- `subscription_id` is Tello Mobile's identifier for the line.
+- `line` is the label displayed in the account's line selector.
+- `remaining` is the displayed remaining data amount, including its unit.
+- `allowance` is the displayed data allowance, including its unit.
+- `renewal_date` is the data plan's renewal or expiration date in `YYYY-MM-DD` format.
+- `percentage_available` is the remaining data expressed as a percentage of the displayed allowance.
+- `days_left` is the number of calendar days until the renewal date.
+
+The percentage calculation uses the displayed amounts, assumes 1 GB equals 1,000 MB, and rounds the result to two
+decimal places. The result is limited to 0–100 percent. A rollover balance above the allowance therefore reports 100
+percent available.
+
+An unlimited or zero allowance produces `None` for `percentage_available`.
+
+Days remaining are calculated using the computer's local date. A renewal date of today or a date in the past produces
+zero days remaining. This value does not measure the exact number of hours until renewal.
+
+If the account page does not provide a recognized renewal date, `renewal_date` and `days_left` are `None`. Python `None`
+values appear as `null` in JSON.
+
+## Error handling
+
+The client raises `TelloError` when login fails, required account information is missing, a line cannot be selected, or
+a data balance cannot be read. Network and HTTP errors are raised as httpx2 exceptions.
+
+```python
+import os
+
+import httpx2
+from tello_usage import TelloClient, TelloError
+
+try:
+    with TelloClient() as client:
+        balances = client.balances(
+            os.environ["TELLO_USERNAME"],
+            os.environ["TELLO_PASSWORD"],
+        )
+except TelloError as error:
+    print(f"Could not read account balances: {error}")
+except httpx2.HTTPError as error:
+    print(f"The HTTP request failed: {error}")
+```
+
+The command-line tool writes errors to standard error and exits with a nonzero status.
+
+A missing data balance stops the operation without returning partial results. This can occur when a line has no active
+data plan.
+
+## Website access and limitations
+
+The package accesses Tello Mobile's website forms rather than a documented API. It logs in, discovers the account's
+lines, and selects each line to read its balance. It maintains session cookies and reads fresh form tokens between
+requests.
+
+The client changes the selected account line while retrieving balances. It does not purchase data or change plan
+settings.
+
+Changes to Tello Mobile's website, a CAPTCHA, or an additional account verification step may prevent the client from
+working.
+
+Credentials and session cookies are held in memory and are not saved by the package. No HAR recording is required.
+
+## Development
+
+From a source checkout, install dependencies and run the tests with uv:
+
+```sh
+uv sync
+uv run python -m unittest discover -s tests -v
+```
+
+The tests use generated account pages and simulated HTTP responses. They do not require account credentials or make
+requests to Tello Mobile.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

tello_usage-2026.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "tello-usage"
+version = "2026.0"
+description = "Retrieve data balances and billing cycle information for every line in a Tello Mobile account."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "beautifulsoup4>=4.15.0",
+    "httpx2>=2.16.0",
+]
+
+[[project.authors]]
+name = "William Jackson"
+email = "william@subtlecoolness.com"
+
+[project.urls]
+Homepage = "https://github.com/williamjacksn/tello-usage"
+Issues = "https://github.com/williamjacksn/tello-usage/issues"
+
+[project.scripts]
+tello-usage = "tello_usage:main"
+
+[build-system]
+requires = ["uv-build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.17.1",
+    "ty>=0.0.90",
+    "uv-build>=0.13.5",
+]
+
+[tool.ruff.lint]
+extend-select = [
+    "ANN",
+    "DTZ",
+    "E",
+    "F",
+    "FURB",
+    "I",
+    "ICN",
+    "PERF",
+    "Q",
+    "RSE",
+    "RUF",
+    "S",
+    "UP",
+]

tello_usage-2026.0/pyproject.toml.orig

@@ -0,0 +1,37 @@
+[project]
+name = "tello-usage"
+version = "2026.0"
+description = "Retrieve data balances and billing cycle information for every line in a Tello Mobile account."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "beautifulsoup4>=4.15.0",
+    "httpx2>=2.16.0",
+]
+
+[[project.authors]]
+name = "William Jackson"
+email = "william@subtlecoolness.com"
+
+[project.urls]
+"Homepage" = "https://github.com/williamjacksn/tello-usage"
+"Issues" = "https://github.com/williamjacksn/tello-usage/issues"
+
+[project.scripts]
+tello-usage = "tello_usage:main"
+
+[build-system]
+requires = ["uv-build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.17.1",
+    "ty>=0.0.90",
+    "uv-build>=0.13.5",
+]
+
+[tool.ruff.lint]
+extend-select = ["ANN", "DTZ", "E", "F", "FURB", "I", "ICN", "PERF", "Q", "RSE", "RUF", "S", "UP"]

tello_usage-2026.0/src/tello_usage/__init__.py

@@ -0,0 +1,4 @@
+from .cli import main
+from .client import Balance, TelloClient, TelloError
+
+__all__ = ["Balance", "TelloClient", "TelloError", "main"]

tello_usage-2026.0/src/tello_usage/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

tello_usage-2026.0/src/tello_usage/cli.py

@@ -0,0 +1,86 @@
+import argparse
+import json
+import os
+import sys
+from dataclasses import asdict
+from getpass import getpass
+
+import httpx2
+
+from .client import TelloClient, TelloError
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Get remaining data balances for all Tello Mobile lines."
+    )
+    parser.add_argument(
+        "--username",
+        help="Tello Mobile email address (defaults to TELLO_USERNAME or a prompt)",
+    )
+    parser.add_argument("--json", action="store_true", help="Print balances as JSON")
+    args = parser.parse_args()
+    username = args.username or os.environ.get("TELLO_USERNAME")
+    password = os.environ.get("TELLO_PASSWORD")
+    try:
+        if not username:
+            if not sys.stdin.isatty():
+                parser.error(
+                    "set TELLO_USERNAME or pass --username "
+                    "when running without a terminal"
+                )
+            username = input("Tello Mobile email: ").strip()
+        if not password:
+            if not sys.stdin.isatty():
+                parser.error("set TELLO_PASSWORD when running without a terminal")
+            password = getpass("Tello Mobile password: ")
+        if not username or not password:
+            parser.error("username and password must not be empty")
+        with TelloClient() as client:
+            balances = client.balances(username, password)
+    except (EOFError, KeyboardInterrupt):
+        parser.exit(130, "\nCanceled.\n")
+    except TelloError as error:
+        parser.exit(1, f"Error: {error}\n")
+    except httpx2.HTTPStatusError as error:
+        parser.exit(
+            1, f"Error: Tello Mobile returned HTTP {error.response.status_code}.\n"
+        )
+    except httpx2.RequestError:
+        parser.exit(
+            1,
+            "Error: Could not connect to Tello Mobile. "
+            "Check your network connection and try again.\n",
+        )
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    asdict(balance)
+                    | {
+                        "percentage_available": balance.percentage_available,
+                        "days_left": balance.days_left,
+                    }
+                    for balance in balances
+                ],
+                indent=2,
+            )
+        )
+    else:
+        for balance in balances:
+            available = balance.percentage_available
+            percentage = (
+                f"{available:.2f}% available"
+                if available is not None
+                else "percentage unavailable"
+            )
+            days = balance.days_left
+            cycle = (
+                f"{days} {'day' if days == 1 else 'days'} left in billing cycle"
+                if days is not None
+                else "billing cycle days unavailable"
+            )
+            print(
+                f"{balance.line}: {balance.remaining} remaining / "
+                f"{balance.allowance} ({percentage}); {cycle}"
+            )

tello_usage-2026.0/src/tello_usage/client.py

@@ -0,0 +1,259 @@
+import re
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+from importlib.metadata import version
+from types import TracebackType
+from typing import Self
+from urllib.parse import urljoin, urlsplit
+
+import httpx2
+from bs4 import BeautifulSoup, Tag
+
+BASE_URL = "https://tello.com"
+DATA_AMOUNT = r"\d[\d,]*(?:\.\d+)?\s*(?:KB|MB|GB|TB)"
+DATA_BALANCE = re.compile(
+    rf"(?P<remaining>{DATA_AMOUNT})\s+remaining\s*/\s*"
+    rf"(?P<allowance>{DATA_AMOUNT}|Unlimited(?:\s+data)?)",
+    re.IGNORECASE,
+)
+
+
+class TelloError(Exception):
+    """Authentication failed or Tello Mobile returned an unexpected account page."""
+
+
+@dataclass(frozen=True)
+class Balance:
+    subscription_id: str
+    line: str
+    remaining: str
+    allowance: str
+    renewal_date: str | None = None
+
+    @property
+    def days_left(self) -> int | None:
+        """Calendar days until renewal, using the computer's local date."""
+        if self.renewal_date is None:
+            return None
+        # Billing cycles use the local calendar date, not a timestamp.
+        today = date.today()  # noqa: DTZ011
+        return max(0, (date.fromisoformat(self.renewal_date) - today).days)
+
+    @property
+    def percentage_available(self) -> float | None:
+        """Estimate available data from displayed balances, using 1 GB = 1,000 MB."""
+
+        def amount(value: str) -> Decimal | None:
+            match = re.fullmatch(r"([\d,.]+)\s*(KB|MB|GB|TB)", value, re.IGNORECASE)
+            if match is None:
+                return None
+            unit = match[2].upper()
+            return Decimal(match[1].replace(",", "")) * 1000 ** (
+                "KB",
+                "MB",
+                "GB",
+                "TB",
+            ).index(unit)
+
+        remaining = amount(self.remaining)
+        allowance = amount(self.allowance)
+        if remaining is None or allowance is None or allowance <= 0:
+            return None
+        available = remaining / allowance * 100
+        return float(
+            max(Decimal(0), min(Decimal(100), available)).quantize(Decimal("0.01"))
+        )
+
+
+def _form_fields(form: Tag) -> dict[str, str]:
+    """Include fresh CSRF, snowman and dynamically named honeypot fields."""
+    return {
+        str(field["name"]): str(field.get("value", ""))
+        for field in form.select("input[name]")
+        if not field.has_attr("disabled")
+        and field.get("type", "text") not in {"submit", "button", "checkbox", "radio"}
+    }
+
+
+def _form(soup: BeautifulSoup, selector: str, action: str) -> Tag:
+    form = soup.select_one(selector)
+    if form is None:
+        raise TelloError(
+            "Expected Tello Mobile form is missing. Login may require verification, "
+            "or the website has changed."
+        )
+    if (
+        urljoin(BASE_URL, str(form.get("action", ""))) != BASE_URL + action
+        or str(form.get("method", "get")).lower() != "post"
+    ):
+        raise TelloError("Tello Mobile returned an unexpected form action or method.")
+    if not _form_fields(form).get("_token"):
+        raise TelloError("Tello Mobile's form is missing its CSRF token.")
+    return form
+
+
+def _account_page(html: str) -> BeautifulSoup:
+    soup = BeautifulSoup(html, "html.parser")
+    if soup.select_one('#account_login_form, input[name="password"]'):
+        raise TelloError(
+            "Tello Mobile login failed or the session expired. Check your credentials "
+            "and whether Tello Mobile requires account verification."
+        )
+    return soup
+
+
+def _lines(soup: BeautifulSoup) -> tuple[dict[str, str], str, Tag]:
+    selector = soup.select_one('select[name="selected_subscription_id"]')
+    if selector is None:
+        raise TelloError(
+            "Tello Mobile's account line selector is missing; cannot enumerate lines."
+        )
+    form = _form(
+        soup,
+        'form:has(select[name="selected_subscription_id"])',
+        "/account/process_home",
+    )
+    lines = {
+        str(option["value"]): option.get_text(" ", strip=True)
+        for option in selector.select("option[value]")
+        if option["value"] and not option.has_attr("disabled")
+    }
+    selected = selector.select_one("option[selected]")
+    if selected is None:
+        selected = selector.select_one("option[value]")
+    current = str(selected.get("value", "")) if selected else ""
+    if not lines or current not in lines:
+        raise TelloError("Tello Mobile returned no selectable account lines.")
+    if _form_fields(form).get("action") != "change_selected_subscription":
+        raise TelloError("Tello Mobile returned an unexpected line-selection action.")
+    return lines, current, form
+
+
+def _renewal_date(detail: Tag) -> str | None:
+    # Use the date beside the data balance, not voice/text or add-on dates.
+    holder = detail.find_parent(class_="progress_holder")
+    if holder is None:
+        return None
+    for node in holder.select(".valid-date"):
+        match = re.fullmatch(
+            r"(?:Renewal|Expiration|Expiry) date:\s*(\d{1,2}/\d{1,2}/\d{4})",
+            node.get_text(" ", strip=True),
+            re.IGNORECASE,
+        )
+        if match:
+            try:
+                month, day, year = map(int, match[1].split("/"))
+                return date(year, month, day).isoformat()
+            except ValueError:
+                return None
+    return None
+
+
+def _balance(soup: BeautifulSoup, subscription_id: str, label: str) -> Balance:
+    # Restrict parsing to balance blocks, excluding plan offers and add-ons.
+    for detail in soup.select(".balance-details .balance-from"):
+        match = DATA_BALANCE.fullmatch(detail.get_text(" ", strip=True))
+        if match:
+            return Balance(
+                subscription_id,
+                label,
+                match["remaining"],
+                match["allowance"],
+                _renewal_date(detail),
+            )
+    raise TelloError(
+        "Could not find a remaining data balance for an account line. The line may "
+        "have no active data plan, or Tello Mobile's page format has changed."
+    )
+
+
+class TelloClient:
+    """A fresh, in-memory cookie session; close it after fetching balances."""
+
+    def __init__(
+        self,
+        *,
+        timeout: float = 30,
+        transport: httpx2.BaseTransport | None = None,
+    ) -> None:
+        _version = version("tello-usage")
+        self._client = httpx2.Client(
+            base_url=BASE_URL,
+            timeout=timeout,
+            follow_redirects=True,
+            headers={"User-Agent": f"tello-usage/{_version}"},
+            event_hooks={"request": [self._check_origin]},
+            transport=transport,
+        )
+
+    @staticmethod
+    def _check_origin(request: httpx2.Request) -> None:
+        url = urlsplit(str(request.url))
+        if (url.scheme, url.hostname, url.port) != ("https", "tello.com", None):
+            raise TelloError(
+                "Tello Mobile redirected outside the expected secure account website."
+            )
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self._client.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        data: dict[str, str] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> str:
+        response = self._client.request(method, path, data=data, headers=headers)
+        response.raise_for_status()
+        return response.text
+
+    def balances(self, username: str, password: str) -> list[Balance]:
+        """Log in, enumerate every line and read each line's data balance."""
+        login = BeautifulSoup(self._request("GET", "/account/login"), "html.parser")
+        form = _form(login, "#account_login_form", "/account/process_login")
+        fields = _form_fields(form)
+        fields.update(username=username, password=password, return_to="/account/home")
+        soup = _account_page(
+            self._request(
+                "POST",
+                "/account/process_login",
+                data=fields,
+                headers={"Origin": BASE_URL, "Referer": BASE_URL + "/account/login"},
+            )
+        )
+        lines, current, _ = _lines(soup)
+        results = {current: _balance(soup, current, lines[current])}
+        for subscription_id, label in lines.items():
+            if subscription_id in results:
+                continue
+            # Tokens and honeypot field names rotate after every line switch.
+            _, _, switch_form = _lines(soup)
+            fields = _form_fields(switch_form)
+            fields["selected_subscription_id"] = subscription_id
+            soup = _account_page(
+                self._request(
+                    "POST",
+                    "/account/process_home",
+                    data=fields,
+                    headers={"Origin": BASE_URL, "Referer": BASE_URL + "/account/home"},
+                )
+            )
+            _, selected, _ = _lines(soup)
+            if selected != subscription_id:
+                raise TelloError(
+                    "Tello Mobile did not switch to the requested line; "
+                    "stopping to avoid mislabeling balances."
+                )
+            results[subscription_id] = _balance(soup, subscription_id, label)
+        return [results[subscription_id] for subscription_id in lines]