Initial commit: Waste Collection API

README.md

@@ -0,0 +1,78 @@
+# Waste Collection API
+
+FastAPI backend for German municipal waste collection schedules with Telegram notification support.
+
+## ⚠️ Required Setup Step
+
+The `waste_collection_schedule` library has a file `calendar.py` that conflicts with Python's stdlib `calendar` module. **You must rename it before running:**
+
+```bash
+mv waste_lib/custom_components/waste_collection_schedule/calendar.py \
+   waste_lib/custom_components/waste_collection_schedule/calendar_SKIPPED.py
+```
+
+## Setup
+
+```bash
+# 1. Install dependencies
+pip install -r requirements.txt
+
+# 2. Rename the conflicting calendar.py (see above)
+
+# 3. Copy .env
+cp .env.example .env
+# Edit .env with your Telegram bot token and chat ID
+
+# 4. Run
+PYTHONPATH=. uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+## Project Structure
+
+```
+waste_api/
+├── app/
+│   ├── main.py              # FastAPI app + routes
+│   ├── collector.py          # waste_collection_schedule wrapper + icalevents bug fix
+│   ├── schemas.py            # Pydantic request/response models
+│   ├── routes/
+│   │   ├── sources.py        # GET /sources, GET /sources/{id}
+│   │   ├── collections.py    # POST /collections/{ics,abfall_io,awm_muenchen_de}
+│   │   └── notifications.py  # POST/GET/DELETE /notifications
+│   └── core/
+│       ├── scheduler.py      # Notification storage + due check
+│       └── notifier.py       # Telegram sender
+├── SPEC.md                   # Full OpenAPI spec
+└── requirements.txt
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Health check |
+| `GET` | `/sources` | List all source IDs |
+| `GET` | `/sources/{id}` | Get params for a source |
+| `POST` | `/collections/ics` | Fetch via generic ICS URL |
+| `POST` | `/collections/abfall_io` | Fetch via Abfall.IO |
+| `POST` | `/collections/awm_muenchen_de` | Fetch Munich waste schedule |
+| `POST` | `/notifications` | Create notification rule |
+| `GET` | `/notifications` | List all notification rules |
+| `DELETE` | `/notifications/{id}` | Delete a rule |
+
+## API Docs
+
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+## Example: Munich
+
+```bash
+curl -X POST http://localhost:8000/collections/awm_muenchen_de \
+  -H "Content-Type: application/json" \
+  -d '{"street": "Bahnstr.", "house_number": "11", "count": 5}'
+```
+
+## Notifications
+
+The scheduler runs via cron (not implemented yet) and fires Telegram messages when collections are due. Notifications are stored in `data/notifications.json`.