spgroup 0.1.0__tar.gz

spgroup-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,113 @@
+name: Publish spgroup to PyPI
+run-name: ${{ github.actor }} is publishing spgroup to PyPI
+
+on: [push]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build tools
+        run: |
+          python -m pip install build
+          python -m pip install -e . pytest
+      - name: Build a binary wheel and a source tarball
+        run: python -m build
+      - name: Verify wheel and sdist integrity
+        run: python -m pytest tests/test_sdk_packaging.py -v
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    if: github.ref_name == 'main' && !startsWith(github.ref, 'refs/tags/')
+    needs: [build]
+    runs-on: ubuntu-latest
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/spgroup
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [build]
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/spgroup
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Sign and upload to GitHub Release
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [publish-to-pypi]
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v2.1.1
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create
+          '${{ github.ref_name }}'
+          --repo '${{ github.repository }}'
+          --notes ""
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          gh release upload
+          '${{ github.ref_name }}' dist/**
+          --repo '${{ github.repository }}'

spgroup-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.DS_Store
+node_modules/
+.runtime/
+.pytest_cache/
+prototype/

spgroup-0.1.0/.postman/resources.yaml

@@ -0,0 +1,7 @@
+workspace:
+  id: 030fd6da-c0cc-428e-8c68-0b63593aa702
+collections:
+  - path: postman/collections/energy-monitoring-api.json
+  - path: postman/collections/sp-mobile-api.json
+environments:
+  - path: postman/environments/local.json

spgroup-0.1.0/AGENTS.md

@@ -0,0 +1,56 @@
+# spgroup SDK — Repository Guidelines
+
+Async Python SDK for SP Group (Singapore Power) mobile APIs.
+
+## Project Structure
+
+- `src/spgroup/` — SDK source package
+- `tests/` — Hermetic SDK tests (default `mise run python:test`)
+- `tests/e2e/` — Opt-in live tests against production SP Group endpoints
+- `docs/api/` — Reverse-engineered API reference (APK v15.9.0)
+- `docs/` — SDK-specific docs, roadmaps, plans
+- `prototype/` — Original TypeScript reverse-engineering harness
+- `postman/` — Postman collections for manual API testing
+
+The HA integration that consumes this SDK lives in
+[energy-monitoring](../energy-monitoring/).
+
+## Commands
+
+Use `python`, not `python3`, when invoking Python directly.
+
+- `mise run python:install` — Install SDK in editable mode with test/lint deps
+- `mise run python:test` — Run hermetic SDK tests
+- `mise run python:test:e2e` — Run opt-in live e2e tests
+- `mise run python:lint` — Run Ruff and mypy
+- `mise run python:build` — Build wheel for publishing
+
+## Publishing
+
+The primary publishing path is **GitHub Actions CI** using Trusted Publishing.
+Push a `vX.Y.Z` tag to trigger a production PyPI release.
+
+### Local/Developer Publishing (TestPyPI dry-run)
+
+```bash
+mise run python:build
+mise run python:publish:testpypi
+```
+
+Only after verifying the TestPyPI install:
+
+```bash
+mise run python:publish
+```
+
+**Never run `python -m twine upload dist/*` without first confirming
+via TestPyPI.**
+
+## Testing
+
+Hermetic tests use fake transports and must not call live services.
+Live tests require `--spgroup-live` and a cached mobile session.
+
+## Agent Instructions
+
+Append discoveries and decisions to `docs/context-tracker.md`.

spgroup-0.1.0/LICENSE

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

spgroup-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+exclude tests
+recursive-exclude tests *

spgroup-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: spgroup
+Version: 0.1.0
+Summary: Async Python SDK scaffold for SP Group APIs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ashe0047/spgroup
+Project-URL: Source, https://github.com/ashe0047/spgroup
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Dynamic: license-file
+
+# spgroup
+
+Async Python SDK for SP Group (Singapore Power) utility APIs.
+
+Reverse-engineered from the SP Group Android mobile app (v15.9.0).
+
+## Installation
+
+```bash
+pip install spgroup
+```
+
+## Quick Start
+
+```python
+import asyncio
+from spgroup import MobileAuthClient, JarvisClient
+
+async def main():
+    auth = MobileAuthClient(session=None)
+    print(f"Client ID: {auth._client_id}")
+
+asyncio.run(main())
+```
+
+## Documentation
+
+API reference and usage guides are available on
+[GitHub](https://github.com/ashe0047/spgroup).
+
+For developers working on the SDK: see `docs/`, `prototype/`, and `postman/`
+in the [GitHub repository](https://github.com/ashe0047/spgroup).
+
+## License
+
+MIT

spgroup-0.1.0/README.md

@@ -0,0 +1,36 @@
+# spgroup
+
+Async Python SDK for SP Group (Singapore Power) utility APIs.
+
+Reverse-engineered from the SP Group Android mobile app (v15.9.0).
+
+## Installation
+
+```bash
+pip install spgroup
+```
+
+## Quick Start
+
+```python
+import asyncio
+from spgroup import MobileAuthClient, JarvisClient
+
+async def main():
+    auth = MobileAuthClient(session=None)
+    print(f"Client ID: {auth._client_id}")
+
+asyncio.run(main())
+```
+
+## Documentation
+
+API reference and usage guides are available on
+[GitHub](https://github.com/ashe0047/spgroup).
+
+For developers working on the SDK: see `docs/`, `prototype/`, and `postman/`
+in the [GitHub repository](https://github.com/ashe0047/spgroup).
+
+## License
+
+MIT

spgroup-0.1.0/docs/adr/adr-two-mode-sdk-vendoring.md

@@ -0,0 +1,248 @@
+# ADR: Two-Mode SDK Vendoring — Dev Vendor vs. Production Pip
+
+## Status
+
+Revised — 2026-07-17 (replaced try/except fallback with unconditional vendor path)
+
+## Context
+
+The SP Group HA custom integration depends on a reusable Python SDK
+(`../python-packages/spgroup/src/spgroup/`) that provides Auth0 authentication,
+SP Group API clients (Jarvis, Yggdrasil, Profile), and mobile session management.
+
+The SDK lives in its own repo at `../python-packages/spgroup/`. During
+development, the vendored copy at `custom_components/sp_group/vendor/spgroup/`
+provides the SDK. For production, `manifest.json` declares
+`"requirements": ["spgroup>=0.1.0"]` and HA installs the SDK from PyPI.
+
+The integration has two distinct deployment scenarios:
+
+| Scenario | SDK source | Import path | Works today? |
+|----------|-----------|-------------|--------------|
+| Development (local checkout) | Vendored copy in vendor/spgroup/ | `from spgroup.mobile import ...` | Yes |
+| Production (HACS / PyPI) | Manifest requirements → pip install | `from spgroup.mobile import ...` | Yes |
+
+The core challenge is making `from spgroup.mobile import ...` resolve correctly
+in both modes without changing the import statement.
+
+### What the authoritative docs say
+
+**Python Language Reference (import system):**
+`sys.path` is a list of directories searched for modules. Programs can modify
+it at runtime. Inserting a directory at position 0 makes it the first search
+location. A non-existent path in `sys.path` is silently ignored during import
+resolution.
+
+**HA Developer Docs (manifest requirements):**
+The `requirements` field in `manifest.json` is the official HA mechanism for
+declaring pip dependencies. HA installs them automatically at startup.
+
+**Repository split (2026-07-17):**
+The SDK was extracted from the HA integration repo into its own repository at
+`../python-packages/spgroup/`. The vendored copy is refreshed from this repo.
+
+### Constraints
+
+1. The import statement must be `from spgroup.mobile import ...` in all modes
+2. Dev workflow must not require pip-installing the SDK — the vendor directory
+   provides it directly
+3. Production installs must resolve via `manifest.json` requirements (pip)
+4. The existing `test_packaging_boundary.py` test allows `from spgroup.mobile
+   import ...` but blocks bare `import spgroup` and `from spgroup.mobile.auth
+   import ...` — the import pattern must not violate this contract
+
+### Risks
+
+1. **sys.path is process-global**: Adding a directory to `sys.path` affects all
+   Python code in the HA process. The name `spgroup` is narrow enough that
+   conflicts are unlikely, but it must be documented.
+2. **Stale vendored copy**: The vendored SDK is a snapshot. If the upstream SDK
+   is updated, the vendored copy must be manually refreshed:
+   `cp -a ../python-packages/spgroup/src/spgroup/* vendor/spgroup/`
+
+## Decision
+
+**Use an unconditional sys.path insert** in the integration's `__init__.py`.
+The vendor path is always added. In development (local checkout), the vendor
+directory exists on disk and provides the SDK. In production (HACS/PyPI), the
+vendor directory is not shipped and the pip-installed SDK takes over.
+
+```python
+from __future__ import annotations
+
+from pathlib import Path
+
+# Dev mode: vendor directory provides the SDK directly.
+# Production: vendor not shipped; manifest.json installs spgroup from pip.
+import sys
+_VENDOR_PATH = str(Path(__file__).resolve().parent / "vendor")
+if _VENDOR_PATH not in sys.path:
+    sys.path.insert(0, _VENDOR_PATH)
+
+from spgroup.mobile import JarvisClient, MobileAuthClient, ...
+```
+
+### Mode 1: Development (local checkout)
+
+The vendored SDK copy lives at `custom_components/sp_group/vendor/spgroup/`.
+When `import spgroup` is attempted:
+
+1. `sys.path` includes the vendor directory (unconditionally inserted)
+2. Python finds `spgroup` at `vendor/spgroup/` — returns it
+3. `from spgroup.mobile import ...` resolves to the **vendored copy**
+4. To update the vendored copy: `cp -a ../python-packages/spgroup/src/spgroup/* vendor/spgroup/`
+5. If the SDK is also pip-installed, the vendored copy takes priority
+   (sys.path[0] is checked before site-packages)
+
+**sys.path is modified once at import time, then cached for the process lifetime.**
+
+### Mode 2: Production / HACS (pip-installed SDK)
+
+The vendored copy is not shipped with the production package. When
+`import spgroup` is attempted:
+
+1. `sys.path` includes the vendor directory (unconditionally inserted, but the
+   path does not exist on disk — harmless)
+2. Python does not find `spgroup` at the non-existent vendor path
+3. Python continues searching `sys.path` — finds `spgroup` in site-packages
+   (installed via `manifest.json` requirements)
+4. `from spgroup.mobile import ...` resolves to the **pip-installed SDK**
+
+Adding a non-existent path to `sys.path` is silently ignored by Python's
+import machinery.
+
+### Import path resolution summary
+
+```
+sys.path[0] = vendor/ (always inserted)
+    │
+    ├── vendor/spgroup/ exists on disk? ─── Yes ──→ Import from vendored copy
+    │                                            (development)
+    │
+    └── vendor/spgroup/ does not exist
+        │
+        └── sys.path search continues
+            │
+            └── spgroup found in site-packages?
+                │
+                ├── Yes ──→ Import from pip-installed SDK (production)
+                │
+                └── No ──→ ImportError (misconfigured install)
+```
+
+### Comparison to previous approach
+
+The previous approach used a try/except fallback pattern:
+
+```python
+try:
+    import spgroup  # pip/editable install exists
+except ImportError:
+    _VENDOR_PATH = ...
+    if _VENDOR_PATH not in sys.path:
+        sys.path.insert(0, _VENDOR_PATH)
+```
+
+This had dual-mode priority where pip-installed took precedence and the
+vendored copy was a fallback. The unconditional approach inverts and
+simplifies this:
+
+| Installation | SDK source |
+|-------------|-----------|
+| Dev checkout (vendor exists on disk) | Vendored copy (sys.path[0]) |
+| Production (vendor not shipped) | Pip-installed SDK (site-packages) |
+
+Reasons for the change:
+
+- **Clear decision split**: Vendor = dev, pip = production. No ambiguous
+  try/except priority.
+- **No import overhead**: The unconditional insert costs ~0.01ms (one sys.path
+  mutation) vs ~0.5ms for a failed import + mutation in the try/except approach.
+- **Manifest requirements now declared**: The manifest explicitly requires
+  `spgroup>=0.1.0`, so production installs fail fast if the SDK is missing.
+- **SDK in its own repo**: After the repo split, the vendored copy is a
+  deliberate snapshot, refreshed from `../python-packages/spgroup/`.
+
+### Implementation rules
+
+1. **Self-containment**: The vendored SDK lives at
+   `custom_components/sp_group/vendor/spgroup/` and is a complete, regular
+   Python package with `__init__.py` files, not a namespace package.
+
+2. **sys.path hygiene**: Insert only once, using the `if path not in
+   sys.path` guard. No cleanup needed — the path entry is harmless for the
+   process lifetime.
+
+3. **Test compatibility**: The `test_packaging_boundary.py` test enforces that
+   HA code must not use `import spgroup` (bare top-level) or
+   `from spgroup.mobile.auth import ...` (deep submodule). The allowed
+   `from spgroup.mobile import ...` pattern matches our usage.
+
+4. **No import changes**: The same `from spgroup.mobile import ...` statement
+   works in both modes. No `from .vendor.spgroup.mobile import ...` or other
+   path-manipulation imports are needed.
+
+5. **Manifest requirements**: `manifest.json` declares
+   `"requirements": ["spgroup>=0.1.0"]`. In production, HA installs the SDK
+   via pip. In development, the vendored copy shadows the pip install.
+
+## Consequences
+
+### Positive
+
+- Single, clean import path everywhere: `from spgroup.mobile import ...`
+- Development workflow does not require pip-installing the SDK
+- Production installs get the SDK via HA's built-in dependency resolution
+- The vendored copy is an explicit dev-mode decision, not a fallback
+- The manifest explicitly declares the dependency
+
+### Negative
+
+- `sys.path` manipulation is process-global; the `spgroup` name is sufficiently
+  unique but must be documented
+- The vendored copy must be manually refreshed from the SDK repo when the
+  SDK source changes
+- If the vendored copy and pip-installed SDK are both present, the vendored
+  copy wins (sys.path[0] priority) — this is correct for dev but could
+  mask version mismatches
+
+## Alternatives Considered
+
+### try/except fallback (previous approach, now superseded)
+
+The initial approach used `try: import spgroup / except ImportError` to
+prefer the pip-installed SDK, falling back to the vendored copy. Superseded
+because:
+- The fallback logic added import overhead for production installs
+- The pip-installed SDK could silently shadow a stale vendored copy during
+  development if the developer forgot to uninstall the pip version
+- The manifest had empty requirements — no explicit dependency declaration
+- After the SDK repo split, the unconditional approach makes the dev vs.
+  production boundary clearer
+
+### Relative imports via `.vendor.spgroup.mobile` (rejected)
+
+The initial vendoring implementation used `from .vendor.spgroup.mobile import
+...` — a direct relative import into the vendored copy. This was rejected
+because:
+- Import path differs from the natural `from spgroup.mobile import ...`
+- Tests need a different import path
+- Cannot support the dual-mode (dev vs production) pattern
+- No graceful fallback when the SDK is published to PyPI
+
+### Copy SDK files directly into the custom component root (rejected)
+
+Placing `spgroup/` as a sibling of `__init__.py` would make it importable as
+`from spgroup.mobile import ...` without `sys.path` manipulation. Rejected
+because:
+- The SDK `spgroup/` dir and the HA integration code (`__init__.py`, `auth.py`,
+  etc.) would intermingle in the same directory, creating confusion
+- The `spgroup/` top-level import name would shadow any pip-installed version
+- The `__init__.py` files would be easy to confuse between the SDK and the HA
+  integration
+
+### Copy-once via a setup script (rejected)
+
+A build script that copies the SDK into the custom component at release time.
+Rejected because it adds build complexity and the unconditional path approach
+handles both modes more simply.

spgroup-0.1.0/docs/api/README.md

@@ -0,0 +1,88 @@
+# SP Group Mobile API Reference
+
+> Reconstructed from `sg.com.singaporepower.spservices` APK v15.9.0
+> Decompiled via JADX from production APK splits (base + arm64_v8a).
+
+## Document Structure
+
+| File | Covers |
+|------|--------|
+| `auth0-flow.md` | Authentication flow: password-realm login, MFA, token refresh |
+| `auth0-api.md` | Auth0 `/oauth/token` grant types, `/mfa/*` endpoints |
+| `jarvis-api.md` | Utility accounts, usage charts, meter readings, green goals |
+| `skalbox-api.md` | Meter reading, billing preferences, customer consent |
+| `yggdrasil-api.md` | Premises management, sharing, invites |
+| `payment-api.md` | Njord/Nomisma/Sersi payments, subscriptions, UND |
+| `ev-api.md` | EV charging: locations, sessions, subscriptions |
+| `greenup-api.md` | GreenUp quests, OneUp GraphQL, advocado rewards |
+| `frieza-api.md` | Tengah cooling, FCU pairing, appointments |
+| `content-api.md` | Magnolia banners/themes, CMS, system status |
+| `utility-apis.md` | Paladin PPMS, Titan EMA, Mera, Halp, minor APIs |
+| `models.md` | Data models: Credentials, JWT, Premise, Accounts, Charts |
+| `network-layer.md` | Retrofit builders, interceptor chain, error handling |
+| `queries.md` | Full GraphQL query/mutation strings from the APK |
+
+## Base URLs
+
+| Context | Base URL |
+|---------|----------|
+| Auth0 (mobile) | `https://identity.spdigital.sg` |
+| Authenticated MuleSoft | `https://b2c.api.spdigital.sg` |
+| Public MuleSoft | `https://public.api.spdigital.sg` |
+| Mera API | `https://mera.api.spdigital.sg` |
+| SPC-HC Gateway | `https://sphc-gateway.api.spdigital.sg` |
+
+## Authentication Headers
+
+All authenticated requests to `b2c.api.spdigital.sg` include:
+
+```
+Authorization: Bearer <access_token>
+X-id-token: <id_token>
+```
+
+## Response Wrapper
+
+Most endpoints return a `ResourceV2<T>` envelope:
+
+```json
+{
+  "data": { ... },
+  "error": { "code": "ERROR_CODE", "message": "..." }
+}
+```
+
+## Domain Glossary
+
+| Term | Meaning |
+|------|---------|
+| Premise | Physical address with utility services |
+| BP Number | Billing Party number |
+| MSSL | Meter Serial Number |
+| EBS | Enterprise Billing System reference |
+| PPMS | Pre-Payment Metering System |
+| FCU | Fan Coil Unit (Tengah cooling) |
+| UND | UniDollar payment token |
+| EVSE | Electric Vehicle Supply Equipment |
+| CPO | Charge Point Operator |
+| YCS | Yggdrasil Core Services |
+| OOB | Out-of-Band (SMS MFA) |
+| AMI | Advanced Metering Infrastructure |
+| SMRD | Self-Meter Reading Data |
+
+## Service-to-Domain Mapping
+
+| Service | Backend | Domain |
+|---------|---------|--------|
+| Jarvis | MuleSoft (b2c) | Utility accounts, charts, meters |
+| Skalbox | MuleSoft (b2c + public) | Meter reading, billing |
+| Yggdrasil | MuleSoft (b2c) | Premises, sharing |
+| Njord | MuleSoft (b2c) | Payments, payables |
+| Nomisma | MuleSoft (b2c) | EV subscriptions |
+| EVA | MuleSoft (b2c) | EV charging |
+| Frosty | MuleSoft (b2c) | Tengah cooling |
+| Frieza | MuleSoft (b2c) | Servicing, warranty |
+| OneUp | MuleSoft (b2c + public) | GreenUp quests |
+| Paladin | MuleSoft (b2c) | PPMS |
+| Magnolia | Contents CDN | Banners, themes |
+| Sersi | MuleSoft (b2c) | UND authorization |