<!--
hoody-notifications Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-20T00:46:54.212Z
Model: mimo-v2.5-pro
Mode: http


Tokens: 6336

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-notifications Subskill

## Overview
`hoody-notifications` is a Hoody Kit service that provides desktop and device notification delivery via a simple HTTP API. It enables applications to trigger, retrieve, and manage system-level notifications on user displays across the Hoody ecosystem.

**When to Use This Service:**
- Sending desktop notifications (e.g., alerts, updates, messages) to user displays
- Retrieving notification history for specific displays or all active displays
- Real-time notification streaming for live updates
- Managing notification lifecycle (dismissing, clearing dismissed state)
- Accessing notification icons and service health/metrics

**Integration Philosophy:**
This service follows Hoody's containerized microservice model, running within your project's container infrastructure. All communication occurs via HTTP endpoints following the Hoody Kit service routing pattern, providing secure, authenticated access without requiring direct API credentials in your applications.

**Key Characteristics:**
- Stateless HTTP API with WebSocket support for real-time streams
- Display-centric addressing (supports single, multiple, or "all" displays)
- Automatic icon serving for notification attachments
- Built-in health monitoring and Prometheus-compatible metrics

---

## Common Workflows

### 1. Sending a Desktop Notification
The core workflow to trigger a notification on a specific display.

**Step 1: Identify Target Display**
Determine which display(s) should receive the notification. Displays are identified by their ID (e.g., "0", ":0", "all").

**Step 2: Send Notification**
```
curl -s -X POST "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/notify" \
  -H "Content-Type: application/json" \
  -d '{
    "display": "0",
    "summary": "System Alert",
    "body": "Backup completed successfully"
  }'
```

**Step 3: Verify Delivery**
Retrieve notifications to confirm delivery:
```
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/0"
```

### 2. Multi-Display Broadcasting
Send the same notification to multiple displays.

**Step 1: Send to Multiple Displays**
Use comma-separated display IDs:
```
curl -s -X POST "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/notify" \
  -H "Content-Type: application/json" \
  -d '{
    "display": "0,1,2",
    "summary": "Broadcast Message",
    "body": "Scheduled maintenance in 5 minutes"
  }'
```

**Step 2: Verify on Each Display**
```
# Check display 0
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/0"

# Check display 1
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/1"
```

### 3. Notification Management Cycle
Standard lifecycle: send → retrieve → dismiss → clear dismissed.

**Step 1: Send Test Notification**
```
curl -s -X POST "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/notify" \
  -H "Content-Type: application/json" \
  -d '{
    "display": "0",
    "summary": "Test",
    "body": "Test notification content"
  }'
```

**Step 2: Retrieve Notifications**
```
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/0"
```

**Step 3: Dismiss Specific Notifications**
Extract notification IDs from the response and dismiss them:
```
curl -s -X POST "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/dismiss" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationIds": ["notif-123", "notif-456"]
  }'
```

**Step 4: Clear Dismissed State** (if needed)
```
curl -s -X DELETE "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/dismiss"
```

### 4. Real-time Notification Streaming
Establish WebSocket connection for live updates.

**Step 1: Connect to Stream**
```
# Using wscat (example)
wscat -c "wss://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/stream?displays=0,1"
```

**Step 2: Send Notification While Stream Open**
From another terminal:
```
curl -s -X POST "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/notify" \
  -H "Content-Type: application/json" \
  -d '{
    "display": "0",
    "summary": "Real-time Alert",
    "body": "This should appear in stream"
  }'
```

**Step 3: Observe Stream Output**
The stream will deliver the notification in real-time.

### 5. Health Check and Monitoring
Essential for production monitoring.

**Step 1: Basic Health Check**
```
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/health"
```
Returns 9-field health response (always HTTP 200 when service is up).

**Step 2: Get Prometheus Metrics**
```
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/metrics"
```

---

## Advanced Operations

### 1. Notification Batch Processing with Verification
Handle large notification volumes with verification at each stage.

**Step 1: Send Multiple Notifications**
```
# Create array of notifications to send
notifications=(
  '{"display": "0", "summary": "Alert 1", "body": "Content 1"}'
  '{"display": "0", "summary": "Alert 2", "body": "Content 2"}'
  '{"display": "1", "summary": "Alert 3", "body": "Content 3"}'
)

for notif in "${notifications[@]}"; do
  curl -s -X POST "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/notify" \
    -H "Content-Type: application/json" \
    -d "$notif"
done
```

**Step 2: Retrieve and Count by Display**
```
# Count notifications per display
for display in 0 1 2; do
  count=$(curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/$display" | jq '.notifications | length')
  echo "Display $display: $count notifications"
done
```

### 2. Conditional Dismissal Pattern
Dismiss notifications based on specific criteria.

**Step 1: Retrieve Notifications with Metadata**
```
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/0" > notifications.json
```

**Step 2: Filter and Dismiss**
```
# Extract IDs of notifications older than 24 hours (example logic)
ids_to_dismiss=$(jq -r '.notifications[] | select(.timestamp < (now - 86400)) | .id' notifications.json)

# Convert to JSON array
json_array=$(echo "$ids_to_dismiss" | jq -R . | jq -s .)

# Send dismissal request
curl -s -X POST "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/dismiss" \
  -H "Content-Type: application/json" \
  -d "{\"notificationIds\": $json_array}"
```

### 3. Icon Retrieval and Caching
Efficiently handle notification icons.

**Step 1: Extract Icon IDs**
From notification response:
```
icon_ids=$(curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/0" | jq -r '.notifications[].iconId')
```

**Step 2: Cache Icons Locally**
```
mkdir -p ./notification_icons
for icon_id in $icon_ids; do
  curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/icons/$icon_id" > "./notification_icons/$icon_id"
done
```

### 4. Error Recovery and Retry Pattern
Handle transient failures gracefully.

**Step 1: Implement Retry Logic**
```
send_notification() {
  local max_retries=3
  local retry_count=0
  
  while [ $retry_count -lt $max_retries ]; do
    response=$(curl -s -w "%{http_code}" -X POST \
      "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/notify" \
      -H "Content-Type: application/json" \
      -d "$1")
    
    http_code=$(echo "$response" | tail -c 4)
    
    if [ "$http_code" -eq 200 ] || [ "$http_code" -eq 201 ]; then
      echo "Notification sent successfully"
      return 0
    else
      retry_count=$((retry_count + 1))
      echo "Attempt $retry_count failed (HTTP $http_code), retrying..."
      sleep $((retry_count * 2))  # Exponential backoff
    fi
  done
  
  echo "Failed to send notification after $max_retries attempts"
  return 1
}

# Usage
send_notification '{"display": "0", "summary": "Critical Alert", "body": "System failure detected"}'
```

### 5. Performance Optimization for High-Volume Use
Handle large notification volumes efficiently.

**Step 1: Use Connection Keep-alive**
```
# Send multiple notifications with same connection
for i in {1..100}; do
  curl -s -X POST "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/notify" \
    -H "Content-Type: application/json" \
    -H "Connection: keep-alive" \
    -d "{\"display\": \"0\", \"summary\": \"Notification $i\", \"body\": \"Content $i\"}"
done
```

**Step 2: Monitor Service Load**
```
# Check metrics periodically
watch -n 30 'curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/metrics" | grep -E "^(http_requests|active_connections)"'
```

---

## Quick Reference

### Essential Endpoints
| Endpoint | Method | Description | Key Parameters |
|----------|--------|-------------|----------------|
| `/api/v1/notifications/notify` | POST | Send notification | `display`, `summary` (required) |
| `/api/v1/notifications/{display}` | GET | Get notifications | `display` in path (required) |
| `/api/v1/notifications/dismiss` | POST | Dismiss notifications | `notificationIds` array (required) |
| `/api/v1/notifications/dismiss` | DELETE | Clear dismissed state | None |
| `/api/v1/notifications/stream` | GET | Real-time stream | `displays` query (required) |
| `/api/v1/notifications/health` | GET | Service health | None |
| `/api/v1/notifications/metrics` | GET | Prometheus metrics | None |
| `/api/v1/notifications/icons/{iconId}` | GET | Get notification icon | `iconId` in path (required) |

### Base URL Pattern
```
https://{projectId}-{containerId}-n-{serviceId}.{node}.containers.hoody.com
```

### Required Fields by Endpoint
**POST /notify:**
```
{
  "display": "string (e.g., '0', '0,1', 'all')",
  "summary": "string (notification title)"
}
```

**POST /dismiss:**
```
{
  "notificationIds": ["array", "of", "notification", "ids"]
}
```

**GET /stream:**
- Query parameter: `displays=0,1,2` (comma-separated)

### Typical Response Formats

**Health Check Response (9 fields):**
```
{
  "status": "healthy",
  "service": "hoody-notifications",
  "timestamp": "2025-01-15T10:30:00Z",
  "version": "1.0.0",
  "uptime": 3600,
  "memory": {"used": 1024, "total": 4096},
  "connections": 5,
  "requests": 1000,
  "errors": 0
}
```

**Notification Array Response:**
```
{
  "notifications": [
    {
      "id": "notif-123",
      "display": "0",
      "summary": "Alert",
      "body": "Content",
      "timestamp": "2025-01-15T10:30:00Z",
      "iconId": "icon-456.png"
    }
  ],
  "count": 1,
  "timestamp": "2025-01-15T10:30:00Z"
}
```

### Common Query Patterns
```
# Get all notifications across all displays
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/all"

# Get notifications for specific displays
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/0,1"

# Stream notifications for multiple displays
curl -s "https://PROJECT-CONTAINER-n-1.NODE.containers.hoody.com/api/v1/notifications/stream?displays=0,1,2"
```

### Error Handling Notes
- All endpoints return standard HTTP status codes
- Health endpoint always returns 200 when service is up (even if degraded)
- Notifications array may be empty but valid JSON
- Icon requests return 404 if icon not found
- Dismiss operations are idempotent

**Note**: Replace `PROJECT`, `CONTAINER`, `NODE`, and `serviceId` with actual values from your Hoody project configuration. The service ID for notifications is typically `1` unless configured otherwise.