@camstack/addon-waste-collections 0.0.0-stage → 0.1.1

package/python/vendor/waste_collection_schedule/source/municipium_it.py

@@ -0,0 +1,244 @@
+import datetime
+from difflib import get_close_matches
+
+import requests
+from waste_collection_schedule import Collection, Icons  # type: ignore[attr-defined]
+from waste_collection_schedule.exceptions import (
+    SourceArgAmbiguousWithSuggestions,
+    SourceArgumentNotFoundWithSuggestions,
+    SourceArgumentRequiredWithSuggestions,
+)
+
+TITLE = "Municipium"
+DESCRIPTION = (
+    "Source for the Municipium app (Maggioli S.p.A.), used by many Italian "
+    "municipalities to publish their door-to-door waste collection calendar."
+)
+URL = "https://www.municipiumapp.it"
+COUNTRY = "it"
+SOURCE_CODEOWNERS = ["@fedfus"]
+
+# Central directory of every municipality on the platform.
+CLOUD_URL = "https://cloud.municipiumapp.it"
+
+# Network timeout (seconds) for every outbound request, so an unresponsive
+# endpoint cannot occupy a Home Assistant executor worker indefinitely.
+TIMEOUT = 30
+
+TEST_CASES = {
+    "Serrastretta (CZ) - Zona 2 Migliuso": {
+        "municipality": "Serrastretta",
+        "area": "Zona 2",
+    },
+    "Serrastretta (CZ) - by calendar id": {
+        "municipality": "Serrastretta",
+        "area": 10325,
+    },
+    "Acate (RG)": {
+        "municipality": "Acate",
+    },
+}
+
+# Municipalities on the platform that expose a waste calendar, as (name,
+# province). This only advertises coverage in the docs; it does NOT limit which
+# comuni work, because the source resolves the comune against the platform
+# directory at runtime. More comuni can be added here as they are verified.
+COMUNI = [
+    ("Acate", "RG"),
+    ("Serrastretta", "CZ"),
+]
+
+
+def EXTRA_INFO():
+    for name, province in COMUNI:
+        yield {"title": f"{name} ({province})", "country": "it"}
+
+
+# Municipium categories vary per municipality; match on a normalised keyword.
+ICON_MAP = {
+    "umido": Icons.BIO_KITCHEN,
+    "organico": Icons.BIO_KITCHEN,
+    "secco": Icons.GENERAL_WASTE,
+    "indifferenziato": Icons.GENERAL_WASTE,
+    "residuo": Icons.GENERAL_WASTE,
+    "carta": Icons.PAPER,
+    "cartone": Icons.PAPER,
+    "vetro": Icons.GLASS,
+    "plastica": Icons.PLASTIC_PACKAGING,
+    "lattine": Icons.METAL,
+    "metallo": Icons.METAL,
+    "multimateriale": Icons.RECYCLING,
+    "verde": Icons.GARDEN,
+    "sfalci": Icons.GARDEN,
+    "vegetale": Icons.GARDEN,
+}
+
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": "Enter the name of your municipality (comune) as it appears in the "
+    "Municipium app. If the municipality has more than one collection zone "
+    "(area), the error message will list the available zone names; pass the one "
+    "that matches your address as 'area'. A partial name (e.g. 'Zona 2') is "
+    "enough, or you can pass the numeric calendar id.",
+    "it": "Inserisci il nome del tuo comune così come appare nell'app Municipium. "
+    "Se il comune ha più di una zona di raccolta (area), il messaggio di errore "
+    "elencherà i nomi delle zone disponibili; indica come 'area' quella che "
+    "corrisponde al tuo indirizzo. È sufficiente un nome parziale (es. 'Zona 2'), "
+    "oppure puoi passare l'id numerico del calendario.",
+}
+
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "municipality": "The municipality (comune), e.g. 'Serrastretta'.",
+        "area": "The collection zone name (or a part of it), or the numeric "
+        "calendar id. Only needed when the municipality has more than one zone.",
+    },
+    "it": {
+        "municipality": "Il comune, ad esempio 'Serrastretta'.",
+        "area": "Il nome della zona di raccolta (o una parte), oppure l'id "
+        "numerico del calendario. Serve solo se il comune ha più di una zona.",
+    },
+}
+
+PARAM_TRANSLATIONS = {
+    "en": {"municipality": "Municipality", "area": "Zone / Calendar"},
+    "it": {"municipality": "Comune", "area": "Zona / Calendario"},
+}
+
+
+def _icon_for(name: str):
+    low = name.casefold()
+    for key, icon in ICON_MAP.items():
+        if key in low:
+            return icon
+    return None
+
+
+class Source:
+    def __init__(self, municipality: str, area: "str | int | None" = None):
+        self._municipality: str = municipality
+        self._area = area
+
+    def _find_municipality(self, session: requests.Session) -> dict:
+        r = session.get(f"{CLOUD_URL}/api/v2/municipalities", timeout=TIMEOUT)
+        r.raise_for_status()
+        comuni = r.json()
+
+        wanted = self._municipality.strip().casefold()
+        matches = [
+            c
+            for c in comuni
+            if c["name"].casefold() == wanted
+            or f"{c['name']} ({c.get('province_initials')})".casefold() == wanted
+        ]
+        if not matches:
+            names = [c["name"] for c in comuni]
+            suggestions = get_close_matches(self._municipality, names, n=5, cutoff=0.4)
+            raise SourceArgumentNotFoundWithSuggestions(
+                "municipality", self._municipality, suggestions
+            )
+        if len(matches) > 1:
+            # Same comune name in several provinces: disambiguate by province.
+            labels = [f"{c['name']} ({c.get('province_initials')})" for c in matches]
+            raise SourceArgAmbiguousWithSuggestions(
+                "municipality", self._municipality, labels
+            )
+
+        muni_id = matches[0]["id"]
+        r = session.get(
+            f"{CLOUD_URL}/api/v2/municipalities/show_mobile/{muni_id}",
+            timeout=TIMEOUT,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def _pick_calendar(self, calendars: "list[dict]") -> dict:
+        if not calendars:
+            raise SourceArgumentNotFoundWithSuggestions("area", self._area, [])
+
+        names = [c["name"] for c in calendars]
+
+        # Explicit calendar id.
+        if isinstance(self._area, int) or (
+            isinstance(self._area, str) and self._area.isdigit()
+        ):
+            wanted_id = int(self._area)
+            found = next((c for c in calendars if c["id"] == wanted_id), None)
+            if found is None:
+                # Suggest the zone names: they are valid `area` inputs (an
+                # id label like "Name (id 123)" would be rejected on re-entry).
+                raise SourceArgumentNotFoundWithSuggestions("area", self._area, names)
+            return found
+
+        if self._area is None:
+            if len(calendars) == 1:
+                return calendars[0]
+            raise SourceArgumentRequiredWithSuggestions(
+                "area", "this municipality has more than one collection zone", names
+            )
+
+        wanted = self._area.strip().casefold()
+        # Exact match, then unambiguous substring, then fuzzy suggestions.
+        found = next((c for c in calendars if c["name"].casefold() == wanted), None)
+        if found is None:
+            subs = [c for c in calendars if wanted in c["name"].casefold()]
+            if len(subs) == 1:
+                found = subs[0]
+            elif len(subs) > 1:
+                raise SourceArgAmbiguousWithSuggestions(
+                    "area", self._area, [c["name"] for c in subs]
+                )
+        if found is None:
+            suggestions = get_close_matches(str(self._area), names, n=5, cutoff=0.3)
+            raise SourceArgumentNotFoundWithSuggestions(
+                "area", self._area, suggestions or names
+            )
+        return found
+
+    def fetch(self) -> "list[Collection]":
+        session = requests.Session()
+        session.headers["Accept"] = "application/json"
+        # The platform WAF rejects the default python-requests User-Agent.
+        session.headers["User-Agent"] = "Mozilla/5.0 (waste_collection_schedule)"
+
+        details = self._find_municipality(session)
+        subdomain = details.get("subdomain")
+        if not subdomain or not details.get("enable_garbage_calendar"):
+            raise SourceArgumentNotFoundWithSuggestions(
+                "municipality", self._municipality, []
+            )
+        api = f"https://{subdomain}/api/v2"
+
+        r = session.get(f"{api}/calendars", timeout=TIMEOUT)
+        r.raise_for_status()
+        calendar = self._pick_calendar(r.json())
+
+        # The calendar endpoint filters events by a [start, end] epoch-second window.
+        today = datetime.date.today()
+        start = int(
+            datetime.datetime.combine(
+                today - datetime.timedelta(days=30), datetime.time()
+            ).timestamp()
+        )
+        end = int(
+            datetime.datetime.combine(
+                today + datetime.timedelta(days=365), datetime.time()
+            ).timestamp()
+        )
+
+        r = session.get(
+            f"{api}/calendars/{calendar['id']}",
+            params={"start": start, "end": end},
+            timeout=TIMEOUT,
+        )
+        r.raise_for_status()
+
+        entries: list[Collection] = []
+        for ev in r.json():
+            title = (ev.get("category") or {}).get("name") or ev.get("title")
+            date_str = ev.get("start")
+            if not title or not date_str:
+                continue
+            date = datetime.datetime.fromisoformat(date_str).date()
+            entries.append(Collection(date=date, t=title, icon=_icon_for(title)))
+
+        return entries

package/python/vendor/waste_collection_schedule/source/murray_wa_gov_au.py

@@ -0,0 +1,85 @@
+from datetime import datetime
+
+import requests
+from waste_collection_schedule import Collection, Icons  # type: ignore[attr-defined]
+from waste_collection_schedule.exceptions import (
+    SourceArgAmbiguousWithSuggestions,
+    SourceArgumentNotFoundWithSuggestions,
+)
+
+TITLE = "Shire of Murray"
+DESCRIPTION = "Source for Shire of Murray waste collection."
+URL = "https://www.murray.wa.gov.au/"
+COUNTRY = "au"
+TEST_CASES = {
+    "41 Wilson Road, Pinjarra": {"address": "41 Wilson Road"},
+    "58 McLarty Street, Dwellingup": {"address": "58 McLarty Street"},
+    "28 Woodview Way, Barragup": {"address": "28 Woodview Way"},
+}
+
+ICON_MAP = {
+    "General Waste": Icons.GENERAL_WASTE,
+    "Recycling": Icons.RECYCLING,
+    "Verge Collection - Green waste": Icons.GARDEN,
+    "Verge Collection - Hard waste": Icons.BULKY,
+}
+
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": "Visit https://www.murray.wa.gov.au/waste-and-environment/waste-and-recycling/bins.aspx and search for your address to verify it is found.",
+}
+
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "address": "Your street address as shown on the Shire of Murray bins page (e.g. '41 Wilson Road').",
+    },
+}
+
+API_BASE = "https://www.murray.wa.gov.au/api/cms/v1/wastecollection"
+ADDRESS_URL = f"{API_BASE}/GetAddressesByQuery"
+DETAILS_URL = f"{API_BASE}/GetAddressDetailsByGuid"
+
+
+class Source:
+    def __init__(self, address: str):
+        self._address = address.strip()
+
+    def fetch(self) -> list[Collection]:
+        # Step 1: Look up the address to get a GUID
+        r = requests.get(
+            ADDRESS_URL, params={"addressQuery": self._address}, timeout=30
+        )
+        r.raise_for_status()
+        addresses = r.json()
+
+        if len(addresses) == 0:
+            raise SourceArgumentNotFoundWithSuggestions("address", self._address, [])
+
+        if len(addresses) > 1:
+            raise SourceArgAmbiguousWithSuggestions(
+                "address",
+                self._address,
+                [a["Address"] for a in addresses],
+            )
+
+        guid = addresses[0]["Guid"]
+
+        # Step 2: Fetch collection details by GUID
+        r = requests.get(DETAILS_URL, params={"id": guid}, timeout=30)
+        r.raise_for_status()
+        data = r.json()
+
+        entries = []
+        for item in data.get("CollectionData", []):
+            bin_name = item["BinType"]["Name"]
+            date = datetime.strptime(
+                item["NextCollectionDate"], "%Y-%m-%dT%H:%M:%S"
+            ).date()
+            entries.append(
+                Collection(
+                    date=date,
+                    t=bin_name,
+                    icon=ICON_MAP.get(bin_name, "mdi:trash-can"),
+                )
+            )
+
+        return entries

package/python/vendor/waste_collection_schedule/source/mustankorkea_fi.py

@@ -0,0 +1,199 @@
+from contextlib import contextmanager
+from datetime import datetime, timedelta, timezone
+
+from curl_cffi import requests
+from waste_collection_schedule import Collection, Icons
+from waste_collection_schedule import exceptions as exc
+
+TITLE = "Mustankorkea"
+DESCRIPTION = "Schedule for Mustankorkea"
+URL = "https://www.mustankorkea.fi"
+TEST_CASES = {
+    "CID": {
+        "username": "!secret mustankorkea_fi_username",
+        "password": "!secret mustankorkea_fi_password",
+        "contract_id": "!secret mustankorkea_fi_contract_id",
+    },
+    "NoCID": {
+        "username": "!secret mustankorkea_fi_username",
+        "password": "!secret mustankorkea_fi_password",
+    },
+}
+ICON_MAP = {
+    "SEKA": Icons.GENERAL_WASTE,
+    "BIO": Icons.ORGANIC,
+}
+
+API_URL = "https://oma.mustankorkea.fi/api"
+
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": "Create an account at oma.mustankorkea.fi to get username and password."
+    'If you have more than one contract, after logging in select your contract under "Omat kohteet" and '
+    "then see the last part of the URL after emptying-infos/ for the contract ID."
+}
+
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "username": "Username for oma.mustankorkea.fi account",
+        "password": "Password for oma.mustankorkea.fi account",
+        "contract_id": "Waste collection contract ID, only required if you have multiple contracts",
+    }
+}
+
+PARAM_TRANSLATIONS = {
+    "en": {
+        "username": "",
+        "password": "",
+        "contract_id": "e.g. 30-00012345-00",
+    }
+}
+
+
+class Source:
+    REQUEST_TIMEOUT = 10
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        contract_id: str | None = None,
+    ):
+        self._username = username
+        self._password = password
+        self._contract_id = contract_id
+        self._token = None
+        self._token_expires = None
+
+    @contextmanager
+    def get_session(self):
+        ses = requests.Session(impersonate="chrome124")
+        try:
+            if not self._token or (
+                self._token_expires
+                and self._token_expires
+                <= (datetime.now(timezone.utc) + timedelta(minutes=2))
+            ):
+                try:
+                    r = ses.post(
+                        f"{API_URL}/customers/Users/login",
+                        json={
+                            "userName": self._username,
+                            "password": self._password,
+                        },
+                        headers={
+                            "Tenant-Id": "3b09f6f9-9458-40e2-9f69-e16e198d0353",
+                        },
+                        timeout=self.REQUEST_TIMEOUT,
+                    )
+                    r.raise_for_status()
+                    data = r.json()
+                    self._token = data["token"]
+                    expires = datetime.fromisoformat(data["expiresAt"])
+
+                    if expires.tzinfo is None:
+                        expires = expires.replace(tzinfo=timezone.utc)
+
+                    self._token_expires = expires
+                except Exception as e:
+                    raise exc.SourceArgumentExceptionMultiple(
+                        ["username", "password"], "Failed to login, check credentials"
+                    ) from e
+
+            ses.headers.update({"Authorization": f"Vingo-e-services {self._token}"})
+
+            if not self._contract_id:
+                try:
+                    r = ses.get(
+                        f"{API_URL}/customers/Customers/emptying-infos",
+                        timeout=self.REQUEST_TIMEOUT,
+                    )
+                    r.raise_for_status()
+                    data = r.json()
+                    if not isinstance(data, list):
+                        raise TypeError(
+                            f"Expected emptying-infos response to be a list, not {type(data)}"
+                        )
+                    if len(data) == 0:
+                        raise ValueError("No contracts found")
+                    if len(data) > 1:
+                        raise exc.SourceArgumentRequiredWithSuggestions(
+                            "contract_id",
+                            "Multiple contracts found",
+                            [c["id"] for c in data],
+                        )
+                    self._contract_id = data[0]["id"]
+                except (
+                    exc.SourceArgumentException,
+                    exc.SourceArgumentExceptionMultiple,
+                ):
+                    raise
+                except Exception as e:
+                    raise exc.SourceArgumentException(
+                        "contract_id",
+                        "Failed to get contract ID, please specify it manually",
+                    ) from e
+            yield ses
+        finally:
+            ses.close()
+
+    def fetch(self) -> list[Collection]:
+        entries = []
+        with self.get_session() as session:
+            try:
+                r = session.get(
+                    f"{API_URL}/customers/Customers/emptying-infos/{self._contract_id}/contracts",
+                    timeout=self.REQUEST_TIMEOUT,
+                )
+                r.raise_for_status()
+                data = r.json()
+                if not isinstance(data, list):
+                    raise TypeError(
+                        f"Expected contracts response to be a list, not {type(data)}"
+                    )
+            except Exception as e:
+                raise exc.SourceArgumentException(
+                    "contract_id",
+                    "Failed to get collection data, please check contract ID",
+                ) from e
+
+            for contract in data:
+                # Filter out contracts w/o collection date (base fees etc)
+                if "nextEmptying" not in contract or not contract["nextEmptying"]:
+                    continue
+
+                # Basic info for this contract
+                t = contract["name"]
+                icon = ICON_MAP.get(contract["size"].split(" ")[0], "mdi:trash-can")
+
+                try:
+                    # Get full emptying schedule for this product in the contract
+                    r = session.get(
+                        f"{API_URL}/customers/Customers/emptying-infos/{self._contract_id}/contracts/{contract['position']}",
+                        timeout=self.REQUEST_TIMEOUT,
+                    )
+                    r.raise_for_status()
+                    details = r.json()
+                    if "allEmptyings" not in details:
+                        raise KeyError("No allEmptyings in response")
+                    if not isinstance(details["allEmptyings"], dict):
+                        raise TypeError(
+                            f"Expected allEmptyings to be a dict, not {type(details['allEmptyings'])}"
+                        )
+                    for _kind, info in details["allEmptyings"].items():
+                        if not isinstance(info, list):
+                            continue
+                        for entry in info:
+                            date = datetime.fromisoformat(entry["emptyingDate"]).date()
+                            entries.append(Collection(date=date, t=t, icon=icon))
+                except Exception:
+                    # Full schedule not available for some reason, fall back to nextEmptying only
+                    entries.append(
+                        Collection(
+                            date=datetime.fromisoformat(
+                                contract["nextEmptying"]
+                            ).date(),
+                            t=t,
+                            icon=icon,
+                        )
+                    )
+        return entries

package/python/vendor/waste_collection_schedule/source/muswellbrook_nsw_gov_au.py

@@ -0,0 +1,93 @@
+import datetime
+
+import requests
+from bs4 import BeautifulSoup
+from waste_collection_schedule import Collection, Icons  # type: ignore[attr-defined]
+from waste_collection_schedule.exceptions import SourceArgumentNotFound
+
+TITLE = "Muswellbrook Shire Council"
+DESCRIPTION = "Source for Muswellbrook Shire Council, NSW, Australia."
+URL = "https://www.muswellbrook.nsw.gov.au"
+TEST_CASES = {
+    "Zone 3A": {"zone": "3a"},
+    "Zone 5B": {"zone": "5b"},
+    "Zone 1B": {"zone": "1b"},
+}
+HOW_TO_GET_ARGUMENTS_DESCRIPTION = {
+    "en": "Find your collection zone at https://www.muswellbrook.nsw.gov.au/waste-collection/ and enter it as e.g. '3a' or '5b'."
+}
+PARAM_DESCRIPTIONS = {
+    "en": {
+        "zone": "Collection zone, e.g. '3a' or '5b'. Find your zone at https://www.muswellbrook.nsw.gov.au/waste-collection/"
+    }
+}
+
+ICON_MAP = {
+    "general waste": Icons.GENERAL_WASTE,
+    "recycling": Icons.RECYCLING,
+    "fogo": Icons.BIO_KITCHEN,
+}
+
+COLLECTION_URL = "https://www.muswellbrook.nsw.gov.au/waste-collection/zone-{}/"
+LOOKAHEAD_WEEKS = 52
+
+
+class Source:
+    def __init__(self, zone: str):
+        self._zone = zone.lower().strip()
+
+    def fetch(self) -> list[Collection]:
+        r = requests.get(COLLECTION_URL.format(self._zone))
+        r.raise_for_status()
+        soup = BeautifulSoup(r.text, "html.parser")
+
+        bins = []
+        for block in soup.find_all(class_="waste-block"):
+            title_el = block.find(class_="waste-block__title")
+            often_el = block.find(class_="waste-block__often")
+            time_el = block.find(class_="waste-block__time")
+
+            if not title_el or not often_el or not time_el:
+                continue
+
+            title = title_el.get_text(strip=True)
+            often = often_el.get_text(strip=True).lower()
+            dt_str = time_el.get("datetime", "")
+
+            try:
+                next_date = datetime.date.fromisoformat(dt_str[:10])
+            except (ValueError, IndexError):
+                continue
+
+            interval = datetime.timedelta(weeks=1 if "weekly" in often else 2)
+            bins.append((title, next_date, interval))
+
+        if not bins:
+            raise SourceArgumentNotFound("zone", self._zone)
+
+        entries = []
+        end_date = datetime.date.today() + datetime.timedelta(weeks=LOOKAHEAD_WEEKS)
+
+        for title, next_date, interval in bins:
+            d = next_date
+            while d <= end_date:
+                # Christmas Day collections are moved to Boxing Day
+                if d.month == 12 and d.day == 25:
+                    d += datetime.timedelta(days=1)
+                entries.append(
+                    Collection(
+                        date=d,
+                        t=title,
+                        icon=self._get_icon(title),
+                    )
+                )
+                d += interval
+
+        return entries
+
+    def _get_icon(self, waste_type: str) -> str | None:
+        lower = waste_type.lower()
+        for key, icon in ICON_MAP.items():
+            if key in lower:
+                return icon
+        return None