pseg-nj-mymeter 0.2.0__tar.gz

pseg_nj_mymeter-0.2.0/LICENSE

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

pseg_nj_mymeter-0.2.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: pseg-nj-mymeter
+Version: 0.2.0
+Summary: Asynchronous PSE&G NJ MyMeter export client and electricity data models
+Author: brylee123
+License-Expression: MIT
+Keywords: pseg,mymeter,home-assistant,electricity,energy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.12
+Requires-Dist: tzdata>=2026.1; platform_system == "Windows"
+Dynamic: license-file
+
+# PSE&G NJ MyMeter client
+
+An experimental, unofficial client for PSE&G New Jersey's MyMeter portal.
+Author: **brylee123**. License: **MIT**. Requires Python 3.13 or newer.
+This project is not affiliated with or endorsed by PSE&G.
+
+Install with `python -m pip install pseg-nj-mymeter`.
+
+An independent asynchronous Python library. It has no Home Assistant imports.
+It accepts an injected `aiohttp.ClientSession`, reads the current export form,
+maps displayed meters to internal IDs, and downloads Hourly consumption CSV.
+The data module validates exports and constructs hourly cumulative statistics.
+It supports an existing user session; password login and MFA are not implemented.
+
+```python
+from aiohttp import ClientSession, CookieJar
+from pseg_mymeter.client import PsegClient
+
+async with ClientSession(cookie_jar=CookieJar()) as session:
+    client = PsegClient(session, cookie_header, meter_number)
+    await client.async_validate_session()
+    csv_text = await client.async_usage()
+```
+
+Build locally with `python -m build library` from the repository root.
+Use `python -m pip install -e library` for development. A public source repository,
+issue tracker, release tags and automated publishing are still prerequisites
+before this library is ready to become a Home Assistant core dependency.
+
+The current custom integration bundles an exact copy under
+`_vendor/pseg_mymeter`; `scripts/sync_vendor.py --check` verifies it against this
+canonical source. The bundle is a temporary custom-integration accommodation,
+not the final core dependency architecture.

pseg_nj_mymeter-0.2.0/README.md

@@ -0,0 +1,33 @@
+# PSE&G NJ MyMeter client
+
+An experimental, unofficial client for PSE&G New Jersey's MyMeter portal.
+Author: **brylee123**. License: **MIT**. Requires Python 3.13 or newer.
+This project is not affiliated with or endorsed by PSE&G.
+
+Install with `python -m pip install pseg-nj-mymeter`.
+
+An independent asynchronous Python library. It has no Home Assistant imports.
+It accepts an injected `aiohttp.ClientSession`, reads the current export form,
+maps displayed meters to internal IDs, and downloads Hourly consumption CSV.
+The data module validates exports and constructs hourly cumulative statistics.
+It supports an existing user session; password login and MFA are not implemented.
+
+```python
+from aiohttp import ClientSession, CookieJar
+from pseg_mymeter.client import PsegClient
+
+async with ClientSession(cookie_jar=CookieJar()) as session:
+    client = PsegClient(session, cookie_header, meter_number)
+    await client.async_validate_session()
+    csv_text = await client.async_usage()
+```
+
+Build locally with `python -m build library` from the repository root.
+Use `python -m pip install -e library` for development. A public source repository,
+issue tracker, release tags and automated publishing are still prerequisites
+before this library is ready to become a Home Assistant core dependency.
+
+The current custom integration bundles an exact copy under
+`_vendor/pseg_mymeter`; `scripts/sync_vendor.py --check` verifies it against this
+canonical source. The bundle is a temporary custom-integration accommodation,
+not the final core dependency architecture.

pseg_nj_mymeter-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pseg-nj-mymeter"
+version = "0.2.0"
+description = "Asynchronous PSE&G NJ MyMeter export client and electricity data models"
+readme = "README.md"
+requires-python = ">=3.13"
+authors = [{name = "brylee123"}]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["pseg", "mymeter", "home-assistant", "electricity", "energy"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.12,<4", "tzdata>=2026.1; platform_system == 'Windows'"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pseg_mymeter = ["py.typed"]

pseg_nj_mymeter-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pseg_nj_mymeter-0.2.0/src/pseg_mymeter/__init__.py

@@ -0,0 +1,3 @@
+"""PSE&G NJ MyMeter asynchronous client and export models."""
+
+__version__ = "0.2.0"

pseg_nj_mymeter-0.2.0/src/pseg_mymeter/client.py

@@ -0,0 +1,197 @@
+"""Session-only MyMeter export client. Never logs cookies or response bodies."""
+
+import json
+import re
+from datetime import date, datetime, timedelta
+from html.parser import HTMLParser
+from http.cookies import CookieError, SimpleCookie
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from aiohttp import ClientError, ClientSession, ClientTimeout
+from yarl import URL
+
+from .data import meter_id
+from .exceptions import CannotConnect, InvalidResponse, MeterNotFound, SessionExpired
+
+BASE = "https://mysmartenergy.nj.pseg.com"
+
+
+class ExportForm(HTMLParser):
+    """Extract successful input/select fields from the recorded export form."""
+
+    def __init__(self) -> None:
+        """Initialize a form-only parser."""
+        super().__init__(convert_charrefs=True)
+        self.active = False
+        self.fields: list[tuple[str, str]] = []
+        self.select: str | None = None
+        self.options: list[tuple[str, bool]] = []
+        self.label: str | None = None
+        self.labels: dict[str, str] = {}
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        """Collect successful form controls and meter labels."""
+        a = dict(attrs)
+        if tag == "form":
+            self.active = a.get("id") == "downloadOptions"
+        if not self.active:
+            return
+        if tag == "input" and a.get("name") and "disabled" not in a:
+            kind = a.get("type", "text")
+            if kind in ("submit", "button", "file"):
+                return
+            if kind in ("checkbox", "radio") and "checked" not in a:
+                return
+            self.fields.append((a["name"], a.get("value") or ""))
+        elif tag == "select" and a.get("name"):
+            self.select, self.options = a["name"], []
+        elif tag == "option" and self.select:
+            self.options.append((a.get("value") or "", "selected" in a))
+        elif tag == "label" and a.get("for"):
+            self.label = a["for"]
+            self.labels[self.label] = ""
+
+    def handle_data(self, data: str) -> None:
+        """Retain label text to map displayed meters to internal IDs."""
+        if self.label:
+            self.labels[self.label] += data
+
+    def handle_endtag(self, tag: str) -> None:
+        """Finish select controls and labels."""
+        if tag == "label":
+            self.label = None
+        elif tag == "select" and self.select:
+            selected = next(
+                (x for x in self.options if x[1]),
+                self.options[0] if self.options else None,
+            )
+            if selected:
+                self.fields.append((self.select, selected[0]))
+            self.select = None
+        elif tag == "form":
+            self.active = False
+
+
+def download_fields(
+    payload: dict[str, Any], meter: str, start: date, end: date
+) -> list[tuple[str, str]]:
+    """Use current server selectors/token; override only export-specific fields."""
+    parser = ExportForm()
+    for item in payload.get("AjaxResults", []):
+        if not isinstance(item, dict):
+            raise InvalidResponse
+        if (
+            isinstance(item.get("Value"), str)
+            and 'id="downloadOptions"' in item["Value"]
+        ):
+            parser.feed(item["Value"])
+    fields = parser.fields
+    if not any(k == "__RequestVerificationToken" and v for k, v in fields):
+        raise SessionExpired("Export form unavailable; reconnect your session")
+    meter_indices = []
+    for key, value in fields:
+        match = re.fullmatch(r"Meters\[(\d+)\]\.Value", key)
+        if match:
+            label = parser.labels.get(f"Meters_{match[1]}__Selected", "")
+            displayed = re.search(r"Meter\s*#\s*([0-9]+)", label, re.IGNORECASE)
+            if displayed and displayed[1] == meter_id(meter):
+                meter_indices.append(match[1])
+    if len(meter_indices) != 1:
+        raise MeterNotFound
+    updates = {
+        "FileFormat": "download-usage-csv",
+        "SelectedFormat": "2",
+        "SelectedServiceType": "1",
+        "SelectedInterval": "5",
+        "SelectedUsageType": "1",
+        "Start": start.isoformat(),
+        "End": end.isoformat(),
+    }
+    result = [
+        (k, v)
+        for k, v in fields
+        if k not in updates and not re.fullmatch(r"Meters\[\d+\]\.Selected", k)
+    ]
+    result.extend(updates.items())
+    result.append((f"Meters[{meter_indices[0]}].Selected", "true"))
+    return result
+
+
+class PsegClient:
+    """An asynchronous, session-injected client without Home Assistant imports."""
+
+    def __init__(self, session: ClientSession, cookie: str, meter: str) -> None:
+        """Initialize an isolated cookie jar with an existing session."""
+        if "\n" in cookie or "\r" in cookie:
+            raise SessionExpired
+        parsed = SimpleCookie()
+        try:
+            parsed.load(cookie)
+        except CookieError:
+            raise SessionExpired from None
+        if not parsed:
+            raise SessionExpired
+        self.session, self.meter = session, meter
+        self.session.cookie_jar.update_cookies(parsed, response_url=URL(BASE))
+
+    async def _async_request(
+        self, method: str, path: str, *, data: list[tuple[str, str]] | None = None
+    ) -> str:
+        """Read a response without redirects or leaking server error text."""
+        try:
+            async with self.session.request(
+                method,
+                BASE + path,
+                headers={
+                    "Referer": BASE + "/Dashboard",
+                    "X-Requested-With": "XMLHttpRequest",
+                },
+                allow_redirects=False,
+                timeout=ClientTimeout(total=90),
+                data=data,
+            ) as response:
+                if response.status in (301, 302, 303, 307, 308, 401, 403):
+                    raise SessionExpired
+                if response.status == 429 or response.status >= 500:
+                    raise CannotConnect
+                if response.status != 200:
+                    raise InvalidResponse
+                if "text/html" in response.headers.get("Content-Type", "").lower():
+                    raise SessionExpired
+                body = await response.text()
+                if len(body) > 25_000_000:
+                    raise InvalidResponse
+                return body
+        except (ClientError, TimeoutError):
+            raise CannotConnect from None
+
+    async def _async_form(self) -> dict[str, Any]:
+        """Retrieve fresh form controls and verification token."""
+        text = await self._async_request("GET", "/Usage/InitializeDownloadSettings")
+        try:
+            payload = json.loads(text)
+        except (ValueError, TypeError):
+            raise InvalidResponse from None
+        if not isinstance(payload, dict) or not isinstance(
+            payload.get("AjaxResults"), list
+        ):
+            raise InvalidResponse
+        return payload
+
+    async def async_validate_session(self) -> None:
+        """Validate authentication and meter membership without downloading."""
+        today = datetime.now(ZoneInfo("America/New_York")).date()
+        download_fields(await self._async_form(), self.meter, today, today)
+
+    async def async_usage(self) -> str:
+        """Download Hourly electricity for the previous seven days."""
+        end = datetime.now(ZoneInfo("America/New_York")).date() - timedelta(days=1)
+        fields = download_fields(
+            await self._async_form(), self.meter, end - timedelta(days=6), end
+        )
+        return await self._async_request("POST", "/Usage/Download", data=fields)
+
+    async def async_close(self) -> None:
+        """Close the caller-owned isolated session on teardown."""
+        await self.session.close()

pseg_nj_mymeter-0.2.0/src/pseg_mymeter/data.py

@@ -0,0 +1,114 @@
+"""Parse hourly MyMeter exports without depending on Home Assistant."""
+
+import csv
+import re
+from datetime import UTC, datetime, timedelta
+from decimal import Decimal, InvalidOperation
+from io import StringIO
+from typing import TypedDict
+from zoneinfo import ZoneInfo
+
+from .exceptions import InvalidUsage
+
+type HourLedger = dict[str, str]
+
+
+class ImportReport(TypedDict):
+    """Aggregate import counts without personal data."""
+
+    rows: int
+    other_meter_rows: int
+    dst_rows_skipped: int
+    hours: int
+
+
+def meter_id(value: str) -> str:
+    """Normalize a displayed meter number, preserving leading zeroes."""
+    return re.sub(r"[^0-9]", "", value)
+
+
+def parse_csv(text: str, meter: str) -> tuple[HourLedger, ImportReport]:
+    """Parse Hourly exports; reject sub-hourly, daily and billing data."""
+    reader = csv.DictReader(StringIO(text.lstrip("\ufeff")))
+    if not reader.fieldnames or not {"Start", "kWh"} <= set(reader.fieldnames):
+        raise InvalidUsage("invalid_columns")
+    if len(reader.fieldnames) != len(set(reader.fieldnames)):
+        raise InvalidUsage("invalid_columns")
+    expected_meter = meter_id(meter)
+    if not expected_meter:
+        raise InvalidUsage("invalid_meter")
+    zone = ZoneInfo("America/New_York")
+    hours: HourLedger = {}
+    seen: set[datetime] = set()
+    report: ImportReport = {
+        "rows": 0,
+        "other_meter_rows": 0,
+        "dst_rows_skipped": 0,
+        "hours": 0,
+    }
+    for row in reader:
+        report["rows"] += 1
+        if None in row or any(value is None for value in row.values()):
+            raise InvalidUsage("invalid_row")
+        if "Meter" in row and meter_id(row["Meter"]) != expected_meter:
+            report["other_meter_rows"] += 1
+            continue
+        try:
+            local = datetime.strptime(row["Start"].strip(), "%m/%d/%Y %I:%M:%S %p")
+            value = Decimal(row["kWh"].replace(",", "").strip())
+        except (ValueError, InvalidOperation) as err:
+            raise InvalidUsage("invalid_row") from err
+        if not value.is_finite() or not 0 <= value <= Decimal("1000000000"):
+            raise InvalidUsage("invalid_value")
+        if local.second or local.minute:
+            raise InvalidUsage("hourly_required")
+        if local in seen:
+            raise InvalidUsage("duplicate_time")
+        seen.add(local)
+        candidates: set[datetime] = set()
+        for fold in (0, 1):
+            candidate = local.replace(tzinfo=zone, fold=fold).astimezone(UTC)
+            if candidate.astimezone(zone).replace(tzinfo=None) == local:
+                candidates.add(candidate)
+        if len(candidates) != 1:
+            report["dst_rows_skipped"] += 1
+            continue
+        hours[candidates.pop().isoformat()] = str(value)
+    starts = sorted(datetime.fromisoformat(key) for key in hours)
+    if not starts:
+        raise InvalidUsage("no_hours")
+    # Headers alone do not distinguish daily/monthly exports. Require an hourly
+    # pair to establish resolution while allowing gaps elsewhere in the file.
+    if not any(b - a == timedelta(hours=1) for a, b in zip(starts, starts[1:])):
+        raise InvalidUsage("hourly_required")
+    report["hours"] = len(hours)
+    return hours, report
+
+
+class HourStatistic(TypedDict, total=False):
+    """Standalone recorder payload before the Home Assistant adapter."""
+
+    start: datetime
+    state: float
+    sum: float
+
+
+def build_statistics(
+    hours: HourLedger, now: datetime | None = None
+) -> list[HourStatistic]:
+    """Build stable sums with baseline markers before contiguous segments."""
+    now = now or datetime.now(UTC)
+    total = Decimal(0)
+    previous: datetime | None = None
+    result: list[HourStatistic] = []
+    for timestamp in sorted(hours):
+        start = datetime.fromisoformat(timestamp)
+        if start + timedelta(hours=1) > now:
+            continue
+        if previous is None or previous + timedelta(hours=1) != start:
+            result.append({"start": start - timedelta(hours=1), "sum": float(total)})
+        value = Decimal(hours[timestamp])
+        total += value
+        result.append({"start": start, "state": float(value), "sum": float(total)})
+        previous = start
+    return result

pseg_nj_mymeter-0.2.0/src/pseg_mymeter/exceptions.py

@@ -0,0 +1,30 @@
+"""Safe client/parser errors that never retain raw input or secrets."""
+
+
+class PsegError(Exception):
+    """Base utility client error."""
+
+
+class SessionExpired(PsegError):
+    """The portal requires authentication."""
+
+
+class CannotConnect(PsegError):
+    """The portal could not be reached."""
+
+
+class InvalidResponse(PsegError):
+    """The portal returned an unsupported response."""
+
+
+class MeterNotFound(PsegError):
+    """The requested meter is unavailable."""
+
+
+class InvalidUsage(ValueError):
+    """A controlled translation key describing invalid CSV data."""
+
+    def __init__(self, translation_key: str) -> None:
+        """Initialize without retaining raw data."""
+        super().__init__(translation_key)
+        self.translation_key = translation_key

pseg_nj_mymeter-0.2.0/src/pseg_nj_mymeter.egg-info/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: pseg-nj-mymeter
+Version: 0.2.0
+Summary: Asynchronous PSE&G NJ MyMeter export client and electricity data models
+Author: brylee123
+License-Expression: MIT
+Keywords: pseg,mymeter,home-assistant,electricity,energy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.12
+Requires-Dist: tzdata>=2026.1; platform_system == "Windows"
+Dynamic: license-file
+
+# PSE&G NJ MyMeter client
+
+An experimental, unofficial client for PSE&G New Jersey's MyMeter portal.
+Author: **brylee123**. License: **MIT**. Requires Python 3.13 or newer.
+This project is not affiliated with or endorsed by PSE&G.
+
+Install with `python -m pip install pseg-nj-mymeter`.
+
+An independent asynchronous Python library. It has no Home Assistant imports.
+It accepts an injected `aiohttp.ClientSession`, reads the current export form,
+maps displayed meters to internal IDs, and downloads Hourly consumption CSV.
+The data module validates exports and constructs hourly cumulative statistics.
+It supports an existing user session; password login and MFA are not implemented.
+
+```python
+from aiohttp import ClientSession, CookieJar
+from pseg_mymeter.client import PsegClient
+
+async with ClientSession(cookie_jar=CookieJar()) as session:
+    client = PsegClient(session, cookie_header, meter_number)
+    await client.async_validate_session()
+    csv_text = await client.async_usage()
+```
+
+Build locally with `python -m build library` from the repository root.
+Use `python -m pip install -e library` for development. A public source repository,
+issue tracker, release tags and automated publishing are still prerequisites
+before this library is ready to become a Home Assistant core dependency.
+
+The current custom integration bundles an exact copy under
+`_vendor/pseg_mymeter`; `scripts/sync_vendor.py --check` verifies it against this
+canonical source. The bundle is a temporary custom-integration accommodation,
+not the final core dependency architecture.

pseg_nj_mymeter-0.2.0/src/pseg_nj_mymeter.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/pseg_mymeter/__init__.py
+src/pseg_mymeter/client.py
+src/pseg_mymeter/data.py
+src/pseg_mymeter/exceptions.py
+src/pseg_mymeter/py.typed
+src/pseg_nj_mymeter.egg-info/PKG-INFO
+src/pseg_nj_mymeter.egg-info/SOURCES.txt
+src/pseg_nj_mymeter.egg-info/dependency_links.txt
+src/pseg_nj_mymeter.egg-info/requires.txt
+src/pseg_nj_mymeter.egg-info/top_level.txt

pseg_nj_mymeter-0.2.0/src/pseg_nj_mymeter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pseg_nj_mymeter-0.2.0/src/pseg_nj_mymeter.egg-info/requires.txt

@@ -0,0 +1,4 @@
+aiohttp<4,>=3.12
+
+[:platform_system == "Windows"]
+tzdata>=2026.1

pseg_nj_mymeter-0.2.0/src/pseg_nj_mymeter.egg-info/top_level.txt

@@ -0,0 +1 @@
+pseg_mymeter