# hoody-notifications Subskill ## Overview **Purpose**: hoody-notifications delivers desktop and device notifications via an HTTP API. It enables applications and services running in Hoody containers to trigger system-level notifications on displays, manage notification state, and stream real-time updates through WebSocket connections. ### When to Use This Service Use hoody-notifications when you need to: - **Send desktop notifications** from containerized applications to a host display - **Retrieve pending notifications** for specific displays or all displays - **Manage notification state** by dismissing or clearing dismissed notifications - **Stream real-time updates** via WebSocket for live notification feeds - **Access notification icons** served by the service - **Monitor service health** and metrics for operational awareness ### Service Philosophy Alignment hoody-notifications follows the Hoody principle of container services accessible via HTTP. It abstracts complex desktop notification systems (like `notify-send` on Linux) into a simple API that any containerized application can consume. The service handles display targeting, icon management, and notification lifecycle — your application only needs to trigger and read. ### Key Characteristics | Aspect | Detail | |--------|--------| | **Protocol** | HTTP REST + WebSocket | | **Auth** | Hoody API token (Bearer) | | **Output** | JSON (machine-readable), table (human) | | **Container Targeting** | Required via `-c ` or `HOODY_CONTAINER` | | **URL Segment** | `n` (e.g., `...-n-1.node.containers.hoody.com`) | --- ## Common Workflows ### Workflow 1: Send a Desktop Notification Trigger a notification on a target display from a containerized service. **Step 1**: Identify your container ID. ``` # List running containers to find your notification service hoody containers list -o json ``` **Step 2**: Trigger the notification. ``` hoody notifications trigger \ -c my-container-id \ --display ":0" \ --summary "Build Complete" \ --body "Project X finished building successfully" \ -o json ``` **Step 3**: Verify notification was sent (check service health). ``` hoody notifications health -c my-container-id -o json ``` ``` { "status": "healthy", "service": "hoody-notifications", "version": "1.0.0", "uptime": 3600, "timestamp": "2025-11-05T12:00:00Z", "checks": { "database": "ok", "display": "ok" }, "environment": "production", "region": "us-east-1" } ``` --- ### Workflow 2: Retrieve Notifications for a Display Fetch all pending notifications for one or more displays. **Step 1**: List notifications for a specific display. ``` hoody notifications list "0" -c my-container-id -o json ``` **Step 2**: List notifications for multiple displays. ``` hoody notifications list "0,1" -c my-container-id -o json ``` **Step 3**: List notifications across all displays. ``` hoody notifications list "all" -c my-container-id -o json ``` Example response: ``` { "notifications": [ { "id": "notif-abc123", "display": ":0", "summary": "Build Complete", "body": "Project X finished", "timestamp": "2025-11-05T12:00:00Z", "icon": "icon-def456.png" } ], "count": 1 } ``` --- ### Workflow 3: Dismiss and Manage Notifications Control notification visibility through dismiss and clear operations. **Step 1**: Retrieve current notifications. ``` hoody notifications list "0" -c my-container-id -o json ``` **Step 2**: Dismiss specific notifications by ID. ``` hoody notifications dismiss \ -c my-container-id \ --notification-ids '["notif-abc123", "notif-def456"]' \ -o json ``` **Step 3**: Verify dismissed notifications are filtered from results. ``` hoody notifications list "0" -c my-container-id -o json ``` Dismissed notifications no longer appear in the response. **Step 4**: Clear dismissed state to restore notifications. ``` hoody notifications clear-dismissed -c my-container-id -o json ``` **Step 5**: Verify notifications are visible again. ``` hoody notifications list "0" -c my-container-id -o json ``` Previously dismissed notifications now appear in the list. --- ### Workflow 4: Stream Real-Time Notifications Establish a WebSocket connection for live notification updates. **Step 1**: Start the notification stream for specific displays. ``` hoody notifications stream \ -c my-container-id \ --displays "0,1" \ -o json ``` **Step 2**: Start the stream for all displays. ``` hoody notifications stream \ -c my-container-id \ --displays "all" \ -o json ``` The connection remains open, delivering notification events as they occur. Each event contains the full notification payload including display, summary, body, and icon references. --- ### Workflow 5: Retrieve a Notification Icon Access the icon image associated with a notification. **Step 1**: Identify the icon ID from a notification response. From the notification list, extract the `icon` field value (e.g., `icon-def456`). **Step 2**: Retrieve the icon image. ``` hoody notifications icon icon-def456 -c my-container-id ``` Icon IDs are derived from notification data (session, ID, timestamp, extension). The response is the raw image data (typically PNG). --- ## Advanced Operations ### Multi-Step: Notification Lifecycle Management Complete workflow from triggering to cleanup. **Step 1**: Trigger a notification with icon. ``` hoody notifications trigger \ -c my-container-id \ --display ":0" \ --summary "Deployment Started" \ --body "Deploying v2.1.0 to production" \ -o json ``` **Step 2**: Stream for immediate delivery confirmation. ``` hoody notifications stream \ -c my-container-id \ --displays "0" \ -o json ``` **Step 3**: After user acknowledgment, dismiss the notification. ``` # Get notification ID from stream or list hoody notifications list "0" -c my-container-id -o json # Dismiss using the returned ID hoody notifications dismiss \ -c my-container-id \ --notification-ids '["notif-xyz789"]' \ -o json ``` **Step 4**: Verify clean state. ``` hoody notifications list "0" -c my-container-id -o json ``` --- ### Error Recovery: Service Health Monitoring **Step 1**: Check service health before operations. ``` hoody notifications health -c my-container-id -o json ``` A healthy response is always HTTP 200 with application/json. **Step 2**: Check detailed metrics for capacity planning. ``` hoody notifications metrics -c my-container-id ``` Returns Prometheus text exposition format. Parse for: - Notification count gauges - Display connection status - Icon cache utilization **Step 3**: If health check fails, verify container status. ``` hoody containers status -c my-container-id -o json ``` Restart if needed: ``` hoody containers restart -c my-container-id ``` --- ### Performance Considerations | Operation | Cost | Recommendation | |-----------|------|----------------| | `list` | Read | Cache results; poll at reasonable intervals | | `stream` | Persistent connection | Prefer over polling for real-time needs | | `dismiss` | Write | Batch dismiss operations when possible | | `clear-dismissed` | Write | Use judiciously; affects all dismissed notifications | | `health` | Read | Use for monitoring; unauthenticated | | `metrics` | Read | Use for Prometheus scraping; unauthenticated | | `icon` | Read | Icons are derived from notification data; cache on client | **Tip**: For applications sending high volumes of notifications, use `stream` instead of repeatedly calling `list`. The WebSocket connection delivers updates immediately without polling overhead. --- ## Quick Reference ### Essential Commands | Command | Endpoint | Purpose | |---------|----------|---------| | `hoody notifications trigger` | POST /notify | Send desktop notification | | `hoody notifications list ` | GET /{display} | Get notifications for display(s) | | `hoody notifications dismiss` | POST /dismiss | Dismiss specific notifications | | `hoody notifications clear-dismissed` | DELETE /dismiss | Restore dismissed notifications | | `hoody notifications stream` | GET /stream | Real-time WebSocket feed | | `hoody notifications icon ` | GET /icons/{iconId} | Retrieve notification icon | | `hoody notifications health` | GET /health | Service health check | | `hoody notifications metrics` | GET /metrics | Prometheus metrics | ### Required Parameters | Command | Required | Description | |---------|----------|-------------| | `trigger` | `--display`, `--summary` | Target display and notification title | | `list` | `` argument | Display ID, comma-separated, or "all" | | `dismiss` | `--notification-ids` | JSON array of notification IDs | | `stream` | `--displays` | Display IDs to subscribe to | | `icon` | `` argument | Notification icon identifier | ### Display Parameter Values | Value | Meaning | |-------|---------| | `"0"` | Display :0 (primary) | | `"0,1"` | Multiple displays | | `"all"` | All available displays | ### Common Flags | Flag | Purpose | |------|---------| | `-c ` | Target container (required) | | `-o json` | Machine-readable JSON output | | `-t ` | API token override | | `HOODY_CONTAINER` | Environment variable for container ID | | `HOODY_TOKEN` | Environment variable for API token | ### Response Patterns All JSON responses follow consistent structure. Notifications contain: ``` { "id": "notif-abc123", "display": ":0", "summary": "Notification Title", "body": "Notification body text", "timestamp": "2025-11-05T12:00:00Z", "icon": "icon-id" } ``` Health response (9-field standardized format): ``` { "status": "healthy", "service": "hoody-notifications", "version": "1.0.0", "uptime": 3600, "timestamp": "2025-11-05T12:00:00Z", "checks": {}, "environment": "production", "region": "us-east-1" } ``` ### Service URL Pattern ``` https://{projectId}-{containerId}-n-{serviceId}.{node}.containers.hoody.com ``` The `n` segment identifies hoody-notifications in the routing system.