Add webhooks, status badge

Author: MrEricSir

README.md

@@ -6,6 +6,8 @@ Real-time monitoring of San Francisco's Muni Metro subway using OpenCV-based com
 
 URL: https://munimet.ro
 
+Current status: [![Muni Metro Status](https://munimet.ro/badge.svg)](https://munimet.ro)
+
 This project was "vibe coded" using Anthropic's Claude Code. Uses deterministic computer vision analysis; no ML models or external AI services required.
 
 ## Quick Start
@@ -62,21 +64,19 @@ See [deploy/README.md](deploy/README.md) for detailed deployment instructions.
 
 ### Credentials Setup (Optional)
 
-To enable Bluesky status posting, configure credentials:
+To enable social media posting and webhook notifications:
 
 ```bash
-# Local development - saves to .env file
-python3 scripts/setup/setup-credentials.py
+# Social media credentials (Bluesky, Mastodon)
+python3 scripts/setup/setup-credentials.py           # Local (.env file)
+python3 scripts/setup/setup-credentials.py --cloud    # Google Cloud Secret Manager
 
-# Cloud deployment - saves to Google Cloud Secret Manager
-python3 scripts/setup/setup-credentials.py --cloud
+# Webhook URLs (Slack, Discord, Teams, etc.)
+python3 scripts/setup/manage-webhooks.py              # Local (.env file)
+python3 scripts/setup/manage-webhooks.py --cloud      # Google Cloud Secret Manager
 ```
 
-The setup script will prompt for:
-- **Bluesky handle** - Your account (e.g., `munimetro.bsky.social`)
-- **Bluesky app password** - Generate at [bsky.app/settings/app-passwords](https://bsky.app/settings/app-passwords)
-
-Credentials are optional - the app works without them, but won't post status updates to Bluesky.
+Credentials and webhooks are optional - the app works without them, but won't post status updates or send notifications.
 
 ## Accessing Training Data
 
@@ -140,14 +140,18 @@ munimet.ro/
 │   ├── train_detector.py  # Train ID detection (OCR)
 │   ├── station_constants.py # Station definitions
 │   ├── analytics.py       # SQLite-based delay analytics
-│   └── notifiers/         # Notification channels (Bluesky, RSS)
+│   ├── badge.py           # SVG status badge generator
+│   └── notifiers/         # Notification channels (Bluesky, Mastodon, RSS, webhooks)
 │
 ├── scripts/               # Development and utility scripts
 │   ├── analyze.py         # CLI tool for image analysis
 │   ├── detect_stations.py # Station detection CLI
 │   ├── detection_viewer.py # Interactive detection viewer
 │   ├── validate.sh        # Local validation (lint + tests)
-│   └── install-hooks.sh   # Git hooks installer
+│   ├── install-hooks.sh   # Git hooks installer
+│   └── setup/             # Setup and configuration scripts
+│       ├── setup-credentials.py  # Social media credentials
+│       └── manage-webhooks.py    # Webhook URL manager
 │
 ├── api/                   # Production web API
 │   ├── api.py             # Falcon web server
@@ -243,9 +247,59 @@ Users
 - **Smart Caching** - Best-of-three smoothing reduces false positives (~30ms local response time)
 - **Cloud Native** - Serverless deployment on Google Cloud Run with automatic scaling
 - **No ML Dependencies** - No PyTorch or large model files required
-- **Multi-Channel Notifications** - Status updates via Bluesky and RSS feed
+- **Multi-Channel Notifications** - Status updates via Bluesky, Mastodon, RSS, and webhooks (Slack, Discord, Teams)
 - **Delay Analytics** - SQLite-based tracking with visual dashboard for delay patterns
 
+## Integrations
+
+### Status Badge
+
+Embed a live status badge on any site or README:
+
+```markdown
+[![Muni Metro Status](https://munimet.ro/badge.svg)](https://munimet.ro)
+```
+
+The badge updates automatically and shows the current system status (green/yellow/red).
+
+### Webhooks
+
+Get notified on Slack, Discord, Microsoft Teams, or any HTTP endpoint when the system status changes.
+
+```bash
+# Interactive manager — add, remove, test, list webhooks
+python scripts/setup/manage-webhooks.py           # Local (.env)
+python scripts/setup/manage-webhooks.py --cloud   # Google Cloud Secret Manager
+
+# Non-interactive
+python scripts/setup/manage-webhooks.py --add https://hooks.slack.com/services/T00/B00/xxx
+python scripts/setup/manage-webhooks.py --remove https://hooks.slack.com/services/T00/B00/xxx
+python scripts/setup/manage-webhooks.py --list
+python scripts/setup/manage-webhooks.py --test    # Send a test notification
+```
+
+Slack, Discord, and Teams URLs are auto-detected and receive platform-native payloads (rich embeds, action buttons, etc.). All other URLs receive a generic JSON payload:
+
+```json
+{
+  "status": "yellow",
+  "previous_status": "green",
+  "description": "Uh oh: Muni's not feeling well",
+  "delay_summaries": ["Westbound delay at Powell"],
+  "timestamp": "2026-03-01T12:00:00",
+  "url": "https://munimet.ro",
+  "badge_url": "https://munimet.ro/badge.svg"
+}
+```
+
+### RSS Feed
+
+Subscribe to status changes via RSS at `https://munimet.ro/feed.xml`. Works with any RSS reader, and can be bridged to Slack or Discord using their built-in RSS integrations.
+
+### Social Media
+
+Follow [@munimetro.bsky.social](https://bsky.app/profile/munimetro.bsky.social) on Bluesky or [@MuniMetro@mastodon.social](https://mastodon.social/@MuniMetro) on Mastodon for status updates.
+
 ## Development Workflow
 
 1. **Collect Data** - Run `download_muni_image.py` periodically

api/README.md

@@ -181,6 +181,28 @@ Analytics dashboard showing delay statistics.
 - Delays by hour of day (bar chart)
 - Delays by day of week (bar chart)
 
+### GET /badge.svg
+
+Embeddable status badge (shields.io style). Shows current system status as a small SVG image suitable for embedding in READMEs, dashboards, or external sites.
+
+**Response** (200 OK): SVG image
+
+**Example**:
+
+```markdown
+[![Muni Metro Status](https://munimet.ro/badge.svg)](https://munimet.ro)
+```
+
+**Status values**:
+| Status | Label | Color |
+|--------|-------|-------|
+| green | on track | green |
+| yellow | delays | yellow |
+| red | down | red |
+| unknown | unknown | gray |
+
+**Caching**: 1 minute (`Cache-Control: public, max-age=60`)
+
 ### GET /analytics-data
 
 JSON API for delay analytics.
@@ -318,6 +340,23 @@ curl https://munimetro-api-438243686292.us-west1.run.app/status
 - `ENABLE_FALLBACK`: `false` - Cache-only mode (no fallback)
 - `PORT`: `8000` - HTTP server port
 
+### Webhooks
+
+- `WEBHOOK_URLS`: Comma-separated list of webhook URLs to notify on status changes
+
+Slack, Discord, and Microsoft Teams URLs are auto-detected and receive platform-native payloads. All other URLs receive a generic JSON payload.
+
+Manage webhooks with the interactive script:
+
+```bash
+python scripts/setup/manage-webhooks.py              # Local (.env)
+python scripts/setup/manage-webhooks.py --cloud       # Secret Manager
+python scripts/setup/manage-webhooks.py --list        # Show current webhooks
+python scripts/setup/manage-webhooks.py --test        # Send test notification
+python scripts/setup/manage-webhooks.py --add URL     # Add a webhook
+python scripts/setup/manage-webhooks.py --remove URL  # Remove a webhook
+```
+
 See [CONFIGURATION.md](../CONFIGURATION.md) for complete configuration reference.
 
 ## Troubleshooting

api/api.py

@@ -33,7 +33,7 @@
 
 # Add parent directory to path for lib imports
 sys.path.insert(0, str(PROJECT_ROOT))
-from lib.muni_lib import download_muni_image, detect_muni_status, read_cache, read_cached_image
+from lib.muni_lib import download_muni_image, detect_muni_status, read_cache, read_cached_image, read_cached_badge
 from lib.config import (
     CACHE_MAX_AGE,
     STALENESS_FRESH,
@@ -482,6 +482,33 @@ def on_get(self, req, resp):
         resp.set_header('Cache-Control', 'public, max-age=1800')
 
 
+class BadgeResource:
+    """Serve a pre-generated SVG status badge for embedding on external sites."""
+
+    def on_get(self, req, resp):
+        """Handle GET request to /badge.svg"""
+        # Serve pre-generated badge from cache (written by checker job)
+        badge_svg = read_cached_badge()
+
+        if not badge_svg:
+            # Fallback: generate on the fly from current status
+            from lib.badge import generate_badge
+
+            status = None
+            cache_data = read_cache()
+            if cache_data:
+                reported = cache_data.get('reported_status') or cache_data.get('best_status')
+                if reported:
+                    status = reported.get('status')
+            badge_svg = generate_badge(status)
+
+        resp.status = falcon.HTTP_200
+        resp.content_type = 'image/svg+xml; charset=utf-8'
+        resp.text = badge_svg
+        # Cache for 1 minute — badge is updated by checker job every 3 min
+        resp.set_header('Cache-Control', 'public, max-age=60')
+
+
 class StaticResource:
     """Serve the frontend HTML files with proper caching."""
     def __init__(self, filename, content_type):
@@ -547,6 +574,7 @@ def __init__(self, filename):
 falcon_app.add_route('/latest-image', LatestImageResource())
 falcon_app.add_route('/feed.xml', RSSFeedResource())
 falcon_app.add_route('/analytics-data', AnalyticsResource())
+falcon_app.add_route('/badge.svg', BadgeResource())
 falcon_app.add_route('/analytics', TextResource('analytics.html'))
 
 # Wrap with WhiteNoise for efficient static file serving with compression and caching

api/check_status.py

@@ -23,7 +23,7 @@
 
 # Add parent directory to path for lib imports
 sys.path.insert(0, str(PROJECT_ROOT))
-from lib.muni_lib import download_muni_image, detect_muni_status, read_cache, write_cache, write_cached_image, calculate_best_status
+from lib.muni_lib import download_muni_image, detect_muni_status, read_cache, write_cache, write_cached_image, write_cached_badge, calculate_best_status
 from lib.detection import apply_status_hysteresis
 from lib.notifiers import notify_status_change
 from lib.analytics import log_status_check
@@ -253,11 +253,15 @@ def check_status(should_write_cache=False, interval_seconds=None):
             if len(statuses) > 1:
                 history = ' -> '.join(s['status'] for s in statuses)
                 print(f"  History: [{history}], Reported: {reported_status['status']}")
-            # Also cache the image for the dashboard
+            # Also cache the image and badge for the dashboard
             if write_cached_image(result['filepath']):
                 print(f"  Image cached")
             else:
                 print(f"  Image cache failed")
+            if write_cached_badge(reported_status['status']):
+                print(f"  Badge cached")
+            else:
+                print(f"  Badge cache failed")
 
             # Notify all channels — done early so notifications aren't lost to timeouts.
             # Determines whether to notify due to a new transition or a missed previous notification.

lib/badge.py

@@ -0,0 +1,70 @@
+"""
+SVG badge generator for MuniMet.ro status.
+
+Generates shields.io-style flat badges showing current system status.
+"""
+
+# Badge colors (shields.io conventions)
+_COLORS = {
+    'green': '#4c1',
+    'yellow': '#dfb317',
+    'red': '#e05d44',
+    'unknown': '#9f9f9f',
+}
+
+_LABELS = {
+    'green': 'on track',
+    'yellow': 'delays',
+    'red': 'down',
+    'unknown': 'unknown',
+}
+
+# Approximate character width for Verdana 11px (shields.io uses this)
+_CHAR_WIDTH = 6.8
+_PADDING = 10
+_LABEL_TEXT = 'MuniMet.ro'
+
+
+def generate_badge(status):
+    """
+    Generate an SVG badge for the given status.
+
+    Args:
+        status: One of 'green', 'yellow', 'red', or None for unknown.
+
+    Returns:
+        str: SVG markup string.
+    """
+    status = status if status in _COLORS else 'unknown'
+    color = _COLORS[status]
+    value_text = _LABELS[status]
+
+    # Calculate widths
+    label_width = int(len(_LABEL_TEXT) * _CHAR_WIDTH + _PADDING * 2)
+    value_width = int(len(value_text) * _CHAR_WIDTH + _PADDING * 2)
+    total_width = label_width + value_width
+
+    label_x = label_width / 2
+    value_x = label_width + value_width / 2
+
+    return f'''<svg xmlns="http://www.w3.org/2000/svg" width="{total_width}" height="20" role="img" aria-label="{_LABEL_TEXT}: {value_text}">
+  <title>{_LABEL_TEXT}: {value_text}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r">
+    <rect width="{total_width}" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="{label_width}" height="20" fill="#555"/>
+    <rect x="{label_width}" width="{value_width}" height="20" fill="{color}"/>
+    <rect width="{total_width}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
+    <text aria-hidden="true" x="{label_x * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)">{_LABEL_TEXT}</text>
+    <text x="{label_x * 10}" y="140" transform="scale(.1)">{_LABEL_TEXT}</text>
+    <text aria-hidden="true" x="{value_x * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)">{value_text}</text>
+    <text x="{value_x * 10}" y="140" transform="scale(.1)">{value_text}</text>
+  </g>
+</svg>'''

lib/muni_lib.py

@@ -177,6 +177,74 @@ def write_cached_image(image_path):
         return False
 
 
+def write_cached_badge(status):
+    """
+    Generate and write a status badge SVG to cache (local file or Cloud Storage).
+
+    Args:
+        status: Current status ('green', 'yellow', 'red')
+
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    from lib.badge import generate_badge
+
+    svg_content = generate_badge(status)
+    cache_path = get_cache_path()
+
+    try:
+        if cache_path.startswith('gs://'):
+            from lib.gcs_utils import parse_gcs_path, gcs_upload_from_string
+
+            bucket_name, _ = parse_gcs_path(cache_path)
+
+            gcs_upload_from_string(
+                bucket_name,
+                'badge.svg',
+                svg_content,
+                content_type='image/svg+xml'
+            )
+            return True
+        else:
+            badge_path = os.path.join(os.path.dirname(cache_path), 'badge.svg')
+            os.makedirs(os.path.dirname(badge_path), exist_ok=True)
+            with open(badge_path, 'w') as f:
+                f.write(svg_content)
+            return True
+    except Exception as e:
+        print(f"Error writing cached badge: {e}")
+        return False
+
+
+def read_cached_badge():
+    """
+    Read the cached badge SVG from local file or Cloud Storage.
+
+    Returns:
+        str: SVG content, or None if not found
+    """
+    cache_path = get_cache_path()
+
+    try:
+        if cache_path.startswith('gs://'):
+            from lib.gcs_utils import parse_gcs_path, gcs_download_as_string
+
+            bucket_name, _ = parse_gcs_path(cache_path)
+            content = gcs_download_as_string(bucket_name, 'badge.svg')
+            if content is not None:
+                return content.decode('utf-8') if isinstance(content, bytes) else content
+            return None
+        else:
+            badge_path = os.path.join(os.path.dirname(cache_path), 'badge.svg')
+            if os.path.exists(badge_path):
+                with open(badge_path, 'r') as f:
+                    return f.read()
+            return None
+    except Exception as e:
+        print(f"Error reading cached badge: {e}")
+        return None
+
+
 def read_cached_image():
     """
     Read the cached image from local file or Cloud Storage.