feat: Add `oplats` Home Assistant custom integration for bill management by Copilot · Pull Request #1 · CodekExplor/Bills-ha

Copilot · 2026-04-13T06:45:37Z

Implements a full Home Assistant custom integration for manually tracking bills/payments with paid/unpaid state, automatic transfer timestamp recording, and persistence across restarts.

Integration structure (`custom_components/oplats/`)

coordinator.py — Core data layer using HA Store (.storage/oplats_bills). Handles CRUD + mark_paid (sets data_przelewu=now()) / mark_unpaid (clears it). Notifies sensor listeners on every mutation.
__init__.py — Registers 5 HA services with Voluptuous schema validation:
- oplats.add_bill, oplats.update_bill, oplats.delete_bill
- oplats.mark_paid, oplats.mark_unpaid
sensor.py — Three aggregate sensors with live listener-based updates:
- Opłaty – Niezapłacone (unpaid count + list in attributes)
- Opłaty – Przeterminowane (overdue count — unpaid + past due date)
- Opłaty – Najbliższy termin (nearest upcoming due date)
config_flow.py — Single-instance UI config flow
services.yaml — Polish-labeled field definitions with typed selectors
translations/pl.json — Full PL translations for config flow and all services
README.md — Install guide (manual + HACS), service call examples, Lovelace card YAML

Example service calls

# Add a bill
service: oplats.add_bill
data:
  nazwa: "Czynsz"
  kwota: 1500.00
  termin_platnosci: "2025-05-10"
  cyklicznosc: "miesięczna"

# Mark paid — records data_przelewu = now()
service: oplats.mark_paid
data:
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Bill data (including paid status and transfer timestamps) survives HA restarts via .storage.

Original prompt

Cel repozytorium
Zbuduj custom integration (dodatek) do Home Assistant, która pozwala ręcznie prowadzić listę opłat/rachunków oraz potwierdzać wykonanie przelewu, zapisując datę wykonania.

Zakres funkcjonalny (MVP)

Dane opłaty (pozycja na liście):

id (unikalne)

nazwa (string, np. "Czynsz", "Internet")

kwota (float, PLN)

termin_platnosci (date lub datetime)

zaplacone (boolean)

data_przelewu (datetime; ustawiane automatycznie w momencie potwierdzenia zapłaty)

notatka (opcjonalnie)

cyklicznosc (opcjonalnie: brak/miesięczna)

Operacje:

dodaj opłatę

edytuj opłatę

usuń opłatę

oznacz jako zapłacone:

ustawia zaplacone=true

ustawia data_przelewu=now()

oznacz jako niezapłacone:

ustawia zaplacone=false

czyści data_przelewu (np. na null lub wartość umowną, jeśli HA wymaga)

Wymagania techniczne

Home Assistant custom integration w katalogu: custom_components/oplats/

Minimalne pliki:

manifest.json

init.py

sensor.py (lub coordinator + sensor)

services.yaml (jeśli wymagane)

config_flow.py (opcjonalnie, ale mile widziane: integracja dodawana z UI)

translations/pl.json (nazwy i opisy po polsku)

Przechowywanie danych:

preferowane w .storage (np. wykorzystać Store/StorageCollection) albo w lokalnym JSON w config,

dane muszą przetrwać restart HA.

Encje:

co najmniej sensory agregujące:

liczba opłat niezapłaconych

liczba opłat przeterminowanych

najbliższy termin płatności (data)

(opcjonalnie) encja per opłata albo inna czytelna prezentacja danych.

Usługi (Home Assistant Services) w domenie oplats:

oplats.add_bill

oplats.update_bill

oplats.delete_bill

oplats.mark_paid (zapisuje data_przelewu=now)

oplats.mark_unpaid

Logowanie:

dodaj sensowne logi (debug/info) ułatwiające diagnozę.

Wymagania UX / UI

Język: PL (nazwy usług, opisów, pól w config flow i atrybutów encji).

Przygotuj README:

jak zainstalować (ręcznie / HACS jeśli możliwe),

jak dodać integrację,

przykłady wywołań usług (Developer Tools → Services),

przykładowa karta Lovelace (Entities) pokazująca encje.

Kryteria akceptacji

Po oznaczeniu opłaty jako zapłaconej zapisuje się data_przelewu z aktualną datą i czasem.

Po restarcie Home Assistanta lista opłat i statusy pozostają zachowane.

Integracja nie sypie błędami w logach podczas startu.

Agent-Logs-Url: https://github.com/CodekExplor/Bills-ha/sessions/c1d50f92-e391-4883-a759-a0eb229bbd27 Co-authored-by: CodekExplor <24770587+CodekExplor@users.noreply.github.com>

…te import to top of sensor.py Agent-Logs-Url: https://github.com/CodekExplor/Bills-ha/sessions/c1d50f92-e391-4883-a759-a0eb229bbd27 Co-authored-by: CodekExplor <24770587+CodekExplor@users.noreply.github.com>

Copilot

Pull request overview

This PR introduces a new Home Assistant custom integration (custom_components/oplats/) for manual bill/payment tracking with persistent storage, service-based CRUD operations, and aggregate sensors for unpaid/overdue/next-due insights.

Changes:

Added core data layer (BillsCoordinator) using HA Store for persistence and bill state transitions (paid/unpaid).
Registered HA services (oplats.add_bill, update_bill, delete_bill, mark_paid, mark_unpaid) and added three aggregate sensors.
Added config flow, Polish translations, service descriptions, and a full README with install/usage examples.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`README.md`	Documents installation/configuration and service usage examples for the new integration.
`custom_components/oplats/__init__.py`	Sets up the config entry, forwards platforms, and registers bill-management services.
`custom_components/oplats/config_flow.py`	Adds a single-instance UI config flow.
`custom_components/oplats/const.py`	Defines domain, storage keys, bill field names, and sensor constants.
`custom_components/oplats/coordinator.py`	Implements persistent CRUD and paid/unpaid operations with listener notifications.
`custom_components/oplats/sensor.py`	Adds three aggregate sensors driven by coordinator updates.
`custom_components/oplats/services.yaml`	Defines service metadata/selectors for HA UI.
`custom_components/oplats/translations/pl.json`	Provides Polish UI translations for config flow and services.
`custom_components/oplats/manifest.json`	Declares the new integration’s metadata and config-flow support.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    if not hass.services.has_service(DOMAIN, "add_bill"):
+        hass.services.async_register(
+            DOMAIN, "add_bill", handle_add_bill, schema=SERVICE_ADD_BILL_SCHEMA
+        )
+    if not hass.services.has_service(DOMAIN, "update_bill"):
+        hass.services.async_register(
+            DOMAIN, "update_bill", handle_update_bill, schema=SERVICE_UPDATE_BILL_SCHEMA
+        )
+    if not hass.services.has_service(DOMAIN, "delete_bill"):
+        hass.services.async_register(
+            DOMAIN, "delete_bill", handle_delete_bill, schema=SERVICE_BILL_ID_SCHEMA
+        )
+    if not hass.services.has_service(DOMAIN, "mark_paid"):
+        hass.services.async_register(
+            DOMAIN, "mark_paid", handle_mark_paid, schema=SERVICE_BILL_ID_SCHEMA
+        )
+    if not hass.services.has_service(DOMAIN, "mark_unpaid"):
+        hass.services.async_register(
+            DOMAIN, "mark_unpaid", handle_mark_unpaid, schema=SERVICE_BILL_ID_SCHEMA
+        )


+        bill[FIELD_PAID] = True
+        bill[FIELD_PAYMENT_DATE] = datetime.now().isoformat()
+        await self.async_save()


+    {
+        vol.Required(FIELD_NAME): cv.string,
+        vol.Required(FIELD_AMOUNT): vol.Coerce(float),
+        vol.Required(FIELD_DUE_DATE): cv.string,
+        vol.Optional(FIELD_NOTE, default=""): cv.string,


+    icon: mdi:calendar-clock
+```
+
+> Dokładne nazwy encji zależą od nazwy instancji integracji. Sprawdź je w **Ustawienia → Urządzenia i usługi → Opłaty**.


+  "domain": "oplats",
+  "name": "Opłaty",
+  "version": "1.0.0",
+  "codeowners": [],


Initial plan

b6e811b

Copilot AI assigned Copilot and CodekExplor Apr 13, 2026

Copilot started work on behalf of CodekExplor April 13, 2026 06:45 View session

Copilot AI and others added 2 commits April 13, 2026 06:49

feat: Add oplats custom integration for Home Assistant

6d80165

Agent-Logs-Url: https://github.com/CodekExplor/Bills-ha/sessions/c1d50f92-e391-4883-a759-a0eb229bbd27 Co-authored-by: CodekExplor <24770587+CodekExplor@users.noreply.github.com>

fix: Address code review – fix SENSOR_UNPAID_KEY spelling and move da…

f84f230

…te import to top of sensor.py Agent-Logs-Url: https://github.com/CodekExplor/Bills-ha/sessions/c1d50f92-e391-4883-a759-a0eb229bbd27 Co-authored-by: CodekExplor <24770587+CodekExplor@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add custom integration for manual payment tracking in Home Assistant~~ feat: Add oplats Home Assistant custom integration for bill management Apr 13, 2026

Copilot AI requested a review from CodekExplor April 13, 2026 06:52

Copilot finished work on behalf of CodekExplor April 13, 2026 06:52

CodekExplor requested a review from Copilot April 13, 2026 06:57

Copilot started reviewing on behalf of CodekExplor April 13, 2026 06:58 View session

CodekExplor approved these changes Apr 13, 2026

View reviewed changes

CodekExplor marked this pull request as ready for review April 13, 2026 06:58

CodekExplor merged commit 51d8fac into main Apr 13, 2026
2 checks passed

Copilot AI reviewed Apr 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add `oplats` Home Assistant custom integration for bill management#1

feat: Add `oplats` Home Assistant custom integration for bill management#1
CodekExplor merged 3 commits intomainfrom
copilot/add-custom-integration-home-assistant

Copilot AI commented Apr 13, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Integration structure (custom_components/oplats/)

Example service calls

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 13, 2026 •

edited

Loading

Integration structure (`custom_components/oplats/`)