Debian Codegraph @

pkg/services/push/pushover/doc.go

raw
1 // Package pushover provides a notification service for sending push notifications via Pushover.
2 //
3 // The Pushover service allows sending push notifications to devices running the Pushover
4 // application on iOS, Android, and Desktop. Pushover is a simple notification service
5 // that delivers instant notifications from scripts, applications, and devices to your
6 // phone or desktop. It supports different priority levels, custom sounds, and
7 // notification titles.
8 //
9 // # URL Format
10 //
11 // The service URL follows the format:
12 //
13 // pushover://userKey:apiToken@host[?query]
14 //
15 // Where:
16 // - userKey: Pushover user key (required, found in your Pushover dashboard)
17 // - apiToken: Pushover application API token (required, created in your application)
18 // - host: optional, but typically not used (included for URL scheme compatibility)
19 // - query: configuration parameters
20 //
21 // # Configuration Options
22 //
23 // The following query parameters can be used to configure the service:
24 //
25 // - devices: comma-separated list of target device names (optional, sends to all devices if not specified)
26 // - priority: message priority (-2 to 1, default: 0)
27 // - title: notification title (optional, defaults to application name)
28 //
29 // Priority levels:
30 // - -2: lowest - no sound, no notification, stored for later
31 // - -1: low - no sound, vibration only
32 // - 0: normal (default) - normal notification behavior
33 // - 1: high - bypasses quiet hours, plays sound
34 //
35 // # Templates
36 //
37 // Pushover does not use templates in the Shoutrrr sense, but supports notification
38 // customization through its native features like titles and priority levels.
39 //
40 // # Usage Examples
41 //
42 // ## Basic notification to all devices
43 //
44 // url := "pushover://userkey:apitoken@"
45 // err := shoutrrr.Send(url, "Hello from Shoutrrr!")
46 //
47 // ## Notification to specific devices
48 //
49 // url := "pushover://userkey:apitoken@?devices=phone,tablet"
50 // err := shoutrrr.Send(url, "Hello on specific devices!")
51 //
52 // ## Notification with custom title
53 //
54 // url := "pushover://userkey:apitoken@?title=Alert"
55 // err := shoutrrr.Send(url, "System is down!")
56 //
57 // ## High priority notification
58 //
59 // url := "pushover://userkey:apitoken@?priority=1"
60 // err := shoutrrr.Send(url, "Critical alert - immediate attention required!")
61 //
62 // ## Quiet notification (no sound)
63 //
64 // url := "pushover://userkey:apitoken@?priority=-1"
65 // err := shoutrrr.Send(url, "Background notification")
66 //
67 // # Common Use Cases
68 //
69 // ## System Monitoring Alerts
70 //
71 // Send alerts from monitoring systems like Nagios, Prometheus, or Zabbix:
72 //
73 // url := "pushover://userkey:apitoken@?title=Alert&priority=1"
74 // err := shoutrrr.Send(url, "Disk space critical: 95% used")
75 //
76 // ## CI/CD Pipeline Notifications
77 //
78 // Notify about build status from Jenkins, GitHub Actions, or GitLab CI:
79 //
80 // url := "pushover://userkey:apitoken@?title=Build%20Failed&priority=1"
81 // err := shoutrrr.Send(url, "Build #123 failed on main branch")
82 //
83 // ## Home Automation
84 //
85 // Integrate with home automation systems:
86 //
87 // url := "pushover://userkey:apitoken@?title=Security&priority=1"
88 // err := shoutrrr.Send(url, "Motion detected at front door")
89 //
90 // ## Backup Completion Notifications
91 //
92 // Notify when backups complete:
93 //
94 // url := "pushover://userkey:apitoken@?title=Backup"
95 // err := shoutrrr.Send(url, "Daily backup finished successfully")
96 //
97 // ## Application Health Monitoring
98 //
99 // Send health check notifications from applications:
100 //
101 // url := "pushover://userkey:apitoken@?title=Health%20Check&priority=-1"
102 // err := shoutrrr.Send(url, "All services are healthy")
103 //
104 // ## Incident Response
105 //
106 // Send urgent notifications for incident response:
107 //
108 // url := "pushover://userkey:apitoken@?title=INCIDENT&priority=1"
109 // err := shoutrrr.Send(url, "Database connection lost - immediate attention required")
110 //
111 // # Error Handling
112 //
113 // The service returns errors for various failure scenarios. Always check the returned error:
114 //
115 // err := shoutrrr.Send(url, message)
116 // if err != nil {
117 // log.Printf("Failed to send Pushover notification: %v", err)
118 // }
119 //
120 // Common error scenarios:
121 // - Invalid or missing user key
122 // - Invalid or missing API token
123 // - Network connectivity issues
124 // - Invalid device names (devices that don't exist in your Pushover account)
125 // - HTTP error status codes from the Pushover API
126 // - Empty message content
127 //
128 // # Security Considerations
129 //
130 // - Store API tokens securely - avoid hardcoding them in source code or configuration files
131 // - Use appropriate priority levels - high priority notifications bypass quiet hours and should be reserved for critical events
132 // - Consider device-specific targeting when needed using the devices parameter
133 // - The user key is not secret, but the API token should be treated as a secret
134 // - Pushover notifications may contain sensitive information - consider this when sending notifications
135 // - Review Pushover's terms of service for any usage restrictions
136 //
137 // # Limitations and Behaviors
138 //
139 // - Message content cannot be empty
140 // - Priority can be set to values between -2 and 1
141 // - Priority 2 (emergency) requires additional parameters (retry, expire) which are not currently supported
142 //
143 // - Device names must match exactly how they appear in your Pushover account
144 // - HTTP client timeout is set to 10 seconds for API requests
145 // - The Pushover API endpoint is https://api.pushover.net/1/messages.json
146 // - Notifications are delivered instantly under normal conditions
147 // - Priority -2 messages are stored for 7 days, -1 and 0 for 30 days, 1 for 7 days
148 // - Maximum message length is 1024 characters
149 package pushover