Debian Codegraph @

pkg/services/specialized/notifiarr/doc.go

raw
1 // Package notifiarr provides a notification service for Notifiarr API integration.
2 //
3 // The Notifiarr service enables sending notifications through the Notifiarr platform,
4 // which supports multiple notification channels including Discord, Slack, and more.
5 // It provides a unified interface for sending notifications with optional Discord-specific
6 // features like channel targeting, thumbnails, images, colors, and mention parsing.
7 //
8 // # URL Format
9 //
10 // The service URL follows the format:
11 //
12 // notifiarr://API_KEY[?query]
13 //
14 // Where:
15 // - API_KEY: Your Notifiarr API key
16 // - query: Optional configuration parameters
17 //
18 // # Configuration Options
19 //
20 // The following query parameters can be used to configure the service:
21 //
22 // - channel: Discord channel ID for notifications (optional)
23 // - thumbnail: Thumbnail URL for Discord notifications (optional)
24 // - image: Image URL for Discord notifications (optional)
25 // - color: Color for Discord notifications (optional)
26 //
27 // # Event ID for Message Updates
28 //
29 // You can specify an event ID to enable message updates:
30 //
31 // params := types.Params{"id": "unique-event-id"}
32 // err := shoutrrr.Send(url, "Message content", params)
33 //
34 // # Discord Mention Parsing
35 //
36 // The service automatically parses Discord user and role mentions from message content.
37 // Mentions are extracted and included in the Discord payload:
38 //
39 // // Message with mentions
40 // message := "Alert for <@123456789> and <@&987654321>"
41 // err := shoutrrr.Send(url, message, nil)
42 //
43 // # Image/Thumbnail Support
44 //
45 // Set thumbnail and image URLs for Discord notifications:
46 //
47 // url := "notifiarr://your-api-key?thumbnail=https://example.com/thumbnail.png&image=https://example.com/image.png"
48 // err := shoutrrr.Send(url, "Message with thumbnail and image", nil)
49 //
50 // # Advanced Text Fields
51 //
52 // The service supports advanced text formatting through parameter fields:
53 //
54 // - icon: Icon URL for the notification embed
55 // - content: Additional content text above the main message
56 // - footer: Footer text for the notification embed
57 //
58 // Example usage:
59 //
60 // params := types.Params{
61 // "icon": "https://example.com/icon.png",
62 // "content": "Additional context information",
63 // "footer": "Generated by MyApp v1.0",
64 // }
65 // err := shoutrrr.Send(url, "Main message content", params)
66 //
67 // # Color Customization
68 //
69 // Customize the color of Discord notifications:
70 //
71 // url := "notifiarr://your-api-key?color=16711680" // Red color
72 // err := shoutrrr.Send(url, "Colored notification", nil)
73 //
74 // # URL Parameter Configuration
75 //
76 // Configure channel targeting:
77 //
78 // url := "notifiarr://your-api-key?channel=123456789012345678"
79 // err := shoutrrr.Send(url, "Channel-specific message", nil)
80 //
81 // # Examples
82 //
83 // ## Basic notification sending
84 //
85 // url := "notifiarr://your-api-key"
86 // err := shoutrrr.Send(url, "Hello from Notifiarr!")
87 //
88 // ## Notification with title and event ID
89 //
90 // url := "notifiarr://your-api-key"
91 // params := types.Params{
92 // "id": "alert-123",
93 // "title": "System Alert",
94 // }
95 // err := shoutrrr.Send(url, "Server is down", params)
96 //
97 // ## Discord notification with channel, thumbnail, and image
98 //
99 // url := "notifiarr://your-api-key?channel=123456789012345678&thumbnail=https://example.com/thumbnail.png&image=https://example.com/image.png"
100 // err := shoutrrr.Send(url, "Alert message", nil)
101 //
102 // ## Notification with mentions and color
103 //
104 // url := "notifiarr://your-api-key?color=65280" // Green color
105 // message := "Task completed <@123456789>"
106 // err := shoutrrr.Send(url, message, nil)
107 //
108 // # Common Use Cases
109 //
110 // ## Monitoring System Integration
111 //
112 // Send alerts from monitoring systems:
113 //
114 // url := "notifiarr://your-api-key?channel=monitoring-channel-id"
115 // err := shoutrrr.Send(url, "High CPU usage detected", types.Params{"title": "System Monitor"})
116 //
117 // ## Application Notifications
118 //
119 // Send notifications from applications:
120 //
121 // url := "notifiarr://your-api-key"
122 // err := shoutrrr.Send(url, "Deployment completed successfully", types.Params{
123 // "id": "deploy-2024-01-01",
124 // "title": "Deployment Status",
125 // })
126 //
127 // ## Discord Bot Integration
128 //
129 // Send formatted Discord messages:
130 //
131 // url := "notifiarr://your-api-key?channel=discord-channel-id&color=16776960&thumbnail=https://example.com/thumbnail.png&image=https://example.com/image.png"
132 // message := "New user registered: <@newuser123>"
133 // err := shoutrrr.Send(url, message, types.Params{
134 // "title": "User Registration",
135 // "icon": "https://example.com/icon.png",
136 // "content": "Welcome to our platform!",
137 // "footer": "User management system",
138 // })
139 //
140 // # Error Handling
141 //
142 // The service returns errors for network failures, invalid API keys, and API errors.
143 // Always check the returned error:
144 //
145 // err := shoutrrr.Send(url, message)
146 // if err != nil {
147 // log.Printf("Failed to send notification: %v", err)
148 // }
149 //
150 // # Security Considerations
151 //
152 // - Store API keys securely, not in URLs in production
153 // - Validate API keys before deployment
154 // - Use HTTPS for all communications
155 // - Consider rate limiting for high-volume notifications
156 package notifiarr