aquamatrix-simar 0.1.0__tar.gz

aquamatrix_simar-0.1.0/.github/workflows/documentation.yml

@@ -0,0 +1,43 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - run: python -m pip install -e ".[dev]"
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        if: github.event_name != 'pull_request'
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

aquamatrix_simar-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  validate-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Verify release tag matches package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected_tag = f"v{version}"
+          if os.environ["RELEASE_TAG"] != expected_tag:
+              raise SystemExit(f"Release tag must be {expected_tag}")
+          PY
+      - run: python -m pip install -e ".[dev]" build
+      - run: pytest
+      - run: ruff check .
+      - run: mypy src
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: validate-and-build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/aquamatrix-simar
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

aquamatrix_simar-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+site/
+coverage.xml
+.coverage
+
+# Local browser captures may contain credentials, cookies, or personal data.
+/temp/

aquamatrix_simar-0.1.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
+}

aquamatrix_simar-0.1.0/AGENTS.md

@@ -0,0 +1,34 @@
+# Agent Guide
+
+## Project intent
+
+This repository is an unofficial async Python SDK for reading SIMAR customer data from the Aquamatrix portal. Its primary consumers are independent integrations such as Home Assistant and MCP servers. Keep the public interface stable, typed, read-only, and independent from those consumer frameworks.
+
+## Required practices
+
+- Read `PRD.md` and `ARCH.md` before changing scope or architecture.
+- Keep portal-specific HTTP paths, HTML token parsing, form fields, and response mapping inside `src/aquamatrix_simar/client.py`.
+- Add or update deterministic `httpx.MockTransport` tests for protocol behavior. Unit tests must not contact real accounts or the live portal.
+- Use `Decimal` for money and `date` for calendar dates. Do not expose portal JSON dictionaries as the primary public API.
+- Preserve async operation and explicit client lifecycle. Do not add blocking network calls.
+- Never log or commit credentials, cookies, NIFs, invoice identifiers, addresses, raw request/response bodies, or unsanitized browser captures. Keep local captures under ignored `/temp/`; sanitize any fixture committed to tests.
+- Do not add payment submission, account mutation, CAPTCHA/MFA bypass, or browser automation without explicit product and security review.
+- Do not disable TLS verification or persist credentials in this library.
+- Keep errors actionable and avoid leaking secrets or personal data in exception messages.
+- Preserve the MIT license and attribution to Oldemar Jesus (`oldemego@gmail.com`).
+
+## Validation
+
+Run the focused test file first, then the complete checks before finalizing:
+
+```shell
+pytest
+ruff check .
+mypy src
+```
+
+Use the project's declared minimum Python version for syntax and typing decisions. Python has no official LTS release; the current package metadata targets Python 3.14+.
+
+## Upstream uncertainty
+
+Aquamatrix's portal endpoints are not documented as a stable public API. Treat captured behavior as evidence, not a contract. When a protocol change is needed, document the observed behavior, add sanitized tests, and fail clearly on unknown response shapes rather than silently returning misleading data.

aquamatrix_simar-0.1.0/ARCH.md

@@ -0,0 +1,53 @@
+# Architecture
+
+## Boundary
+
+`SimarClient` is the integration-facing facade. It owns one `httpx.AsyncClient`, its cookies, and the credentials for the lifetime of that client. It exposes async operations and translates HTTP/portal behavior into `Invoice` models and stable SDK exceptions. Consumers do not need to know the portal's URL paths, form encoding, token field, or DataTables parameter names.
+
+```text
+Home Assistant / MCP / Python application
+                 |
+            SimarClient
+       /         |         \
+ session     protocol     mapping
+ cookies     CSRF/forms    Invoice
+                 |
+       Aquamatrix SIMARnet portal
+```
+
+## Modules
+
+- `client.py`: async transport, login, token refresh, billing requests, pagination input, and wire-format mapping.
+- `models.py`: immutable public domain values; currently `Invoice` with `Decimal` amount and `date` fields.
+- `errors.py`: stable base, authentication, session-expiry, and protocol exceptions.
+- `__init__.py`: supported public exports.
+
+## Authentication and request flow
+
+1. `login()` GETs `/SIMARnet/Account/Login`, allowing the HTTP cookie jar to retain portal cookies.
+2. The response HTML is parsed for `__RequestVerificationToken` using the standard-library HTML parser.
+3. The token, `UserCode` (NIF), password, and `RememberMe=false` are submitted as form data. A redirect into SIMARnet marks the client authenticated; credentials are not persisted.
+4. Each invoice-history request fetches the authenticated billing page for a fresh token, then POSTs the DataTables fields and date filters to `GetInvoicesHistory`.
+5. Portal rows are converted into immutable `Invoice` values. Pending filtering only accepts known unpaid states and excludes records with a payment date.
+
+The portal is currently observed to return dates as ISO strings for display and ASP.NET `/Date(milliseconds)/` values for raw fields. The mapper accepts either representation. Monetary values are represented by JSON numbers and converted through their string form to `Decimal`.
+
+## Error behavior
+
+- `AuthenticationError`: login was not completed or a protected operation was called before login.
+- `SessionExpiredError`: the authenticated page/token is no longer available or the portal rejects the session.
+- `ProtocolError`: unexpected HTTP, JSON, or data shape indicates an upstream change.
+
+No automatic retry is performed. Consumers decide whether and when to re-authenticate. The client is an async context manager and should be closed when an integration unloads.
+
+## Security and privacy
+
+- Credentials and session cookies remain in memory for the client lifetime.
+- Do not log credentials, form bodies, cookies, NIF, invoice identifiers, addresses, or returned personal data.
+- Tests must use synthetic fixtures. Browser captures, HAR/SAR files, and account exports are ignored and must never be committed.
+- TLS verification remains enabled; do not add credential submission over insecure transport.
+- Scope is read-only. Payment submission is deliberately excluded.
+
+## Evolution
+
+Treat all portal wire formats as private implementation details. Add a normalized model or public method only where downstream callers have a concrete need; keep selectors, forms, and response peculiarities private. Tests should mock HTTP and use sanitized generic fixtures so protocol regressions are observable offline.

aquamatrix_simar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oldemar Jesus <oldemego@gmail.com>
+
+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.

aquamatrix_simar-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: aquamatrix-simar
+Version: 0.1.0
+Summary: Async Python client for SIMAR customer accounts on Aquamatrix
+Project-URL: Homepage, https://github.com/OldemarJesus/aquamatrix-python-sdk
+Project-URL: Repository, https://github.com/OldemarJesus/aquamatrix-python-sdk
+Project-URL: Issues, https://github.com/OldemarJesus/aquamatrix-python-sdk/issues
+Project-URL: Documentation, https://oldemarjesus.github.io/aquamatrix-python-sdk/
+Author-email: Oldemar Jesus <oldemego@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aquamatrix,async,simar,utilities,water
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.14
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.29; extra == 'dev'
+Requires-Dist: mypy>=1.16; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Aquamatrix SIMAR Python SDK
+
+An async Python client for reading customer billing data from the SIMAR portal hosted by Aquamatrix. It manages the web session and anti-forgery tokens so integrations can work with typed Python objects instead of portal-specific HTML and form fields.
+
+**Documentation:** [User guide and API reference](https://oldemarjesus.github.io/aquamatrix-python-sdk/)
+
+This is an **unofficial** integration. It is not affiliated with or endorsed by SIMAR or Aquamatrix, and the website does not present a stable public API. Portal changes, additional authentication requirements, or access policies may affect compatibility.
+
+## Requirements
+
+- Python 3.14 or newer. Python does not designate a long-term-support release; this project targets the latest stable CPython release available at initial development.
+- A SIMAR portal account.
+
+## Install
+
+```shell
+python -m pip install aquamatrix-simar
+```
+
+Until the first PyPI release, install from the repository:
+
+```shell
+python -m pip install "git+https://github.com/OldemarJesus/aquamatrix-python-sdk.git"
+```
+
+## Usage
+
+```python
+import asyncio
+import os
+
+from aquamatrix_simar import SimarClient
+
+
+async def main() -> None:
+    async with SimarClient(os.environ["SIMAR_NIF"], os.environ["SIMAR_PASSWORD"]) as simar:
+        await simar.login()
+        summary = await simar.get_billing_summary()
+        print(f"Portal says {summary['invoices_to_pay']} invoice(s) need payment")
+
+        for invoice in await simar.get_pending_invoices():
+            print(
+                invoice.document_number,
+                invoice.amount,
+                invoice.year,
+                invoice.issue_date,
+                invoice.payment_until,
+            )
+
+
+asyncio.run(main())
+```
+
+`get_invoices()` returns a page of history and accepts `start`, `limit`, `date_from`, and `date_to`. By default, the portal's recent one-year window is requested. Invoice amounts are `Decimal`; issue and payment dates are `datetime.date` values. This SDK currently reads data only; it does not initiate payments.
+
+For Home Assistant, create and retain a client in the integration's coordinator lifecycle, refresh it asynchronously, and close it during unload. Do not log credentials, cookies, request bodies, or personal invoice data.
+
+## Development
+
+```shell
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+mypy src
+```
+
+See [PRD.md](PRD.md), [ARCH.md](ARCH.md), and [AGENTS.md](AGENTS.md) for product scope, design boundaries, and contributor guidance.
+
+## Author and license
+
+Copyright (c) 2026 Oldemar Jesus <oldemego@gmail.com>. Released under the MIT License; see [LICENSE](LICENSE).

aquamatrix_simar-0.1.0/PRD.md

@@ -0,0 +1,35 @@
+# TL;DR PRD: Aquamatrix SIMAR SDK
+
+## Product
+
+An async, typed Python library that lets authorized SIMAR customers and downstream projects retrieve account billing data from the Aquamatrix customer portal without reimplementing login, session-cookie, anti-forgery-token, or portal-form mechanics.
+
+## Users and problem
+
+Primary users are Python integration maintainers, especially Home Assistant and MCP developers. They need dependable access to whether invoices are pending and to each invoice's amount, issue year/date, payment deadline, and status. Directly embedding portal scraping and session logic in each integration duplicates brittle implementation details and increases credential-handling risk.
+
+## MVP outcomes
+
+- Authenticate with NIF and password and retain the portal session in an owned HTTP client.
+- Expose typed invoice history, pending invoices, and billing summary counts.
+- Convert portal dates and amounts to standard Python types and surface stable SDK exceptions.
+- Keep all portal-specific paths, CSRF handling, and DataTables forms behind a small client boundary.
+- Provide deterministic offline tests and integration-oriented lifecycle/documentation guidance.
+
+## Out of scope
+
+- Initiating payments, modifying customer details, or any other write operation.
+- Browser automation, unofficial credential storage, account discovery, or bypassing MFA/CAPTCHA/access controls.
+- Guaranteeing compatibility with a website that has no documented stable API.
+- Home Assistant or MCP adapters in this repository; those consume the SDK separately.
+
+## Constraints and success criteria
+
+- Python 3.14+ (latest stable at project inception; Python has no official LTS release designation).
+- Async HTTP interface, explicit client lifecycle, no credential or personal-data logging.
+- Tests cover token acquisition, login, invoice mapping, pending filtering, and expired sessions without contacting the live portal.
+- Public MIT project authored by Oldemar Jesus.
+
+## Risks
+
+Aquamatrix may change its private portal endpoints, CSRF mechanics, response fields, authentication requirements, or terms. Such changes must fail with clear errors, be captured in sanitized fixtures, and be reviewed against applicable service terms before release.

aquamatrix_simar-0.1.0/README.md

@@ -0,0 +1,71 @@
+# Aquamatrix SIMAR Python SDK
+
+An async Python client for reading customer billing data from the SIMAR portal hosted by Aquamatrix. It manages the web session and anti-forgery tokens so integrations can work with typed Python objects instead of portal-specific HTML and form fields.
+
+**Documentation:** [User guide and API reference](https://oldemarjesus.github.io/aquamatrix-python-sdk/)
+
+This is an **unofficial** integration. It is not affiliated with or endorsed by SIMAR or Aquamatrix, and the website does not present a stable public API. Portal changes, additional authentication requirements, or access policies may affect compatibility.
+
+## Requirements
+
+- Python 3.14 or newer. Python does not designate a long-term-support release; this project targets the latest stable CPython release available at initial development.
+- A SIMAR portal account.
+
+## Install
+
+```shell
+python -m pip install aquamatrix-simar
+```
+
+Until the first PyPI release, install from the repository:
+
+```shell
+python -m pip install "git+https://github.com/OldemarJesus/aquamatrix-python-sdk.git"
+```
+
+## Usage
+
+```python
+import asyncio
+import os
+
+from aquamatrix_simar import SimarClient
+
+
+async def main() -> None:
+    async with SimarClient(os.environ["SIMAR_NIF"], os.environ["SIMAR_PASSWORD"]) as simar:
+        await simar.login()
+        summary = await simar.get_billing_summary()
+        print(f"Portal says {summary['invoices_to_pay']} invoice(s) need payment")
+
+        for invoice in await simar.get_pending_invoices():
+            print(
+                invoice.document_number,
+                invoice.amount,
+                invoice.year,
+                invoice.issue_date,
+                invoice.payment_until,
+            )
+
+
+asyncio.run(main())
+```
+
+`get_invoices()` returns a page of history and accepts `start`, `limit`, `date_from`, and `date_to`. By default, the portal's recent one-year window is requested. Invoice amounts are `Decimal`; issue and payment dates are `datetime.date` values. This SDK currently reads data only; it does not initiate payments.
+
+For Home Assistant, create and retain a client in the integration's coordinator lifecycle, refresh it asynchronously, and close it during unload. Do not log credentials, cookies, request bodies, or personal invoice data.
+
+## Development
+
+```shell
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+mypy src
+```
+
+See [PRD.md](PRD.md), [ARCH.md](ARCH.md), and [AGENTS.md](AGENTS.md) for product scope, design boundaries, and contributor guidance.
+
+## Author and license
+
+Copyright (c) 2026 Oldemar Jesus <oldemego@gmail.com>. Released under the MIT License; see [LICENSE](LICENSE).

aquamatrix_simar-0.1.0/docs/api.md

@@ -0,0 +1,15 @@
+# API Reference
+
+The public API is intentionally small. Portal paths, HTML token parsing, and form encoding are implementation details.
+
+::: aquamatrix_simar
+    options:
+      members:
+        - SimarClient
+        - Invoice
+        - SimarError
+        - AuthenticationError
+        - SessionExpiredError
+        - ProtocolError
+      show_root_heading: false
+      show_root_toc_entry: false

aquamatrix_simar-0.1.0/docs/guide/installation.md

@@ -0,0 +1,15 @@
+# Installation
+
+The package requires Python 3.14 or newer and a SIMAR customer portal account. Python does not define an official LTS release; this project targets the latest stable version available at its initial development.
+
+```shell
+python -m pip install aquamatrix-simar
+```
+
+For development or installation directly from the source repository:
+
+```shell
+python -m pip install "git+https://github.com/OldemarJesus/aquamatrix-python-sdk.git"
+```
+
+The public package name is `aquamatrix-simar`; the Python import package is `aquamatrix_simar`.

aquamatrix_simar-0.1.0/docs/guide/integrations.md

@@ -0,0 +1,21 @@
+# Integration Patterns
+
+The SDK is framework-independent. An integration should own one client for the lifetime of its account entry, refresh it asynchronously, and close it during unload or shutdown.
+
+## Home Assistant
+
+Use the config entry's stored credentials to construct the client and a coordinator to refresh data. Perform login and reads through Home Assistant's async setup/update lifecycle; do not block the event loop. Call `aclose()` when unloading the config entry. Keep the NIF and password in the integration's secret storage, not in entity attributes or logs.
+
+```python
+client = SimarClient(nif, password)
+await client.login()
+invoices = await client.get_pending_invoices()
+```
+
+## MCP server
+
+Create the client within the server's account/session lifecycle. Return only the fields a tool needs, such as amount and payment deadline; avoid exposing address, client code, or invoice identifiers unless the tool's use case requires them. Close the client when the session ends.
+
+## Error handling
+
+Catch `AuthenticationError` for rejected credentials and `SessionExpiredError` for a stale session. Treat `ProtocolError` as an upstream compatibility problem rather than returning partial or fabricated billing data. Retry or reauthenticate only according to the host application's policy.

aquamatrix_simar-0.1.0/docs/guide/quickstart.md

@@ -0,0 +1,36 @@
+# Quick Start
+
+Keep credentials outside source control, such as in environment variables supplied by your application or secret manager.
+
+```python
+import asyncio
+import os
+
+from aquamatrix_simar import SimarClient
+
+
+async def main() -> None:
+    async with SimarClient(
+        os.environ["SIMAR_NIF"],
+        os.environ["SIMAR_PASSWORD"],
+    ) as client:
+        await client.login()
+
+        summary = await client.get_billing_summary()
+        print("Invoices to pay:", summary["invoices_to_pay"])
+
+        for invoice in await client.get_pending_invoices():
+            print(
+                invoice.document_number,
+                invoice.amount,
+                invoice.issue_date,
+                invoice.payment_until,
+            )
+
+
+asyncio.run(main())
+```
+
+`get_invoices()` returns one page and accepts `start`, `limit`, `date_from`, and `date_to`. The default date range covers the recent year. Amounts are `Decimal` and calendar fields are `datetime.date` objects.
+
+The client owns its HTTP session and cookie jar. Use `async with` or call `await client.aclose()` when finished. A session-expired response raises `SessionExpiredError`; call `login()` again when appropriate.

aquamatrix_simar-0.1.0/docs/guide/releasing.md

@@ -0,0 +1,19 @@
+# Release and Publishing
+
+## GitHub Pages setup
+
+The `documentation.yml` workflow builds MkDocs on pull requests and publishes the site on pushes to `main` or a manual workflow run. In the repository settings, set **Pages → Build and deployment → Source** to **GitHub Actions**. The public site URL is <https://oldemarjesus.github.io/aquamatrix-python-sdk/>.
+
+## PyPI trusted publishing setup
+
+Configure PyPI once before the first release:
+
+1. Create the `aquamatrix-simar` project on PyPI, or open its **Publishing** settings if it already exists.
+2. Add a pending trusted publisher with owner `OldemarJesus`, repository `aquamatrix-python-sdk`, workflow filename `publish.yml`, and environment name `pypi`.
+3. In GitHub repository settings, create the `pypi` deployment environment. Optionally require approval for that environment.
+4. Update `project.version` in `pyproject.toml`, run the checks, and commit the change.
+5. Create a GitHub Release whose tag matches the version, for example `v0.1.0`. Publishing starts only after the release is published.
+
+The workflow runs tests, lint, and type checks, builds wheel and source distributions, then publishes those exact artifacts using GitHub's OIDC identity. It does not need a PyPI API token or PyPI password stored in GitHub secrets.
+
+Verify the version in `pyproject.toml` before each release; PyPI versions are immutable and cannot be overwritten. If a release fails, inspect the Actions run, correct the issue, and publish a new version rather than reusing an already published version.

aquamatrix_simar-0.1.0/docs/guide/security.md

@@ -0,0 +1,12 @@
+# Security and Limitations
+
+This is an unofficial client for a private web interface, not a documented Aquamatrix or SIMAR API. Endpoint paths and response formats may change without notice. Compatibility is best-effort and no availability or correctness guarantee is implied.
+
+- Use only accounts you are authorized to access and follow the portal's applicable terms.
+- Credentials and session cookies are held in memory for the client lifetime; this library does not persist them.
+- Do not log credentials, cookies, NIFs, raw request or response bodies, addresses, or invoice identifiers.
+- Keep credentials in a host application's secret store.
+- The client verifies TLS and performs read-only operations. It does not submit payments or mutate account state.
+- Authentication challenges such as MFA or CAPTCHA are not bypassed. If the portal requires a new flow, access may fail until the client is updated appropriately.
+
+If the portal changes, report a sanitized description of the response shape; never attach unredacted browser captures or account data to an issue.

aquamatrix_simar-0.1.0/docs/index.md

@@ -0,0 +1,28 @@
+# Aquamatrix SIMAR Python SDK
+
+An async Python client for reading billing information from the SIMAR customer portal hosted by Aquamatrix.
+
+Use the SDK to establish a portal session and retrieve typed invoice data without putting Aquamatrix's HTML, CSRF tokens, or form fields into each integration.
+
+## Capabilities
+
+- Authenticate with a SIMAR NIF and password.
+- Retrieve billing summary counts and invoice history.
+- List pending invoices with amount, issue date, year, and payment deadline.
+- Use an async context manager and typed `Invoice` values.
+
+The client is read-only and unofficial. See [Security and limitations](guide/security.md) before connecting an account.
+
+## Start here
+
+- [Install the package](guide/installation.md)
+- [Run the quick start](guide/quickstart.md)
+- [Integrate with Home Assistant or an MCP server](guide/integrations.md)
+- [Browse the API reference](api.md)
+
+## Project
+
+- [Product requirements](https://github.com/OldemarJesus/aquamatrix-python-sdk/blob/main/PRD.md)
+- [Architecture](https://github.com/OldemarJesus/aquamatrix-python-sdk/blob/main/ARCH.md)
+- [MIT License](https://github.com/OldemarJesus/aquamatrix-python-sdk/blob/main/LICENSE)
+- [Release and publishing](guide/releasing.md)

aquamatrix_simar-0.1.0/mkdocs.yml

@@ -0,0 +1,54 @@
+site_name: Aquamatrix SIMAR Python SDK
+site_description: Async Python client for SIMAR customer accounts on Aquamatrix
+site_url: https://oldemarjesus.github.io/aquamatrix-python-sdk/
+repo_url: https://github.com/OldemarJesus/aquamatrix-python-sdk
+repo_name: OldemarJesus/aquamatrix-python-sdk
+
+theme:
+  name: material
+  features:
+    - content.code.copy
+    - navigation.footer
+    - navigation.sections
+    - navigation.tabs
+    - search.highlight
+    - search.suggest
+  palette:
+    - scheme: default
+      primary: teal
+      accent: amber
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_style: google
+            members_order: source
+            show_root_heading: true
+            show_source: false
+
+nav:
+  - Home: index.md
+  - Guide:
+      - Installation: guide/installation.md
+      - Quick start: guide/quickstart.md
+      - Integrations: guide/integrations.md
+      - Security and limitations: guide/security.md
+  - API reference: api.md
+  - Project:
+      - Product requirements: https://github.com/OldemarJesus/aquamatrix-python-sdk/blob/main/PRD.md
+      - Architecture: https://github.com/OldemarJesus/aquamatrix-python-sdk/blob/main/ARCH.md
+      - License: https://github.com/OldemarJesus/aquamatrix-python-sdk/blob/main/LICENSE
+      - Release and publishing: guide/releasing.md
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.superfences
+
+strict: true