Debian Codegraph @

pkg/services/push/pushbullet/doc.go

raw
1 // Package pushbullet provides a notification service for sending push notifications via Pushbullet.
2 //
3 // The Pushbullet service allows sending push notifications to devices, email addresses,
4 // or channels that are connected to a Pushbullet account. Pushbullet is a cross-platform
5 // notification service that enables sending push notifications between devices, with
6 // support for note-type messages containing a title and body. It uses API token-based
7 // authentication and supports targeting specific devices, email contacts, or channels.
8 //
9 // # URL Format
10 //
11 // The service URL follows the format:
12 //
13 // pushbullet://token[/targets][?query]
14 //
15 // Where:
16 // - token: Pushbullet API token for authentication (required, must be 34 characters)
17 // - targets: optional path components specifying recipients (devices, emails, or channels)
18 // - query: configuration parameters
19 //
20 // # Configuration Options
21 //
22 // The following query parameters can be used to configure the service:
23 //
24 // - title: notification title (default: "Shoutrrr notification")
25 //
26 // # Target Types
27 //
28 // Targets can be specified in the URL path and support three formats:
29 //
30 // - Device: a device identifier (e.g., "mydevice")
31 // - Email: an email address (e.g., "[email protected]")
32 // - Channel: a channel tag prefixed with # (e.g., "#mychannel")
33 //
34 // Multiple targets can be specified as path components:
35 //
36 // pushbullet://token/device1/device2?title=Alert
37 // pushbullet://token/[email protected]?title=Email%20Alert
38 // pushbullet://token/#mychannel?title=Channel%20Alert
39 //
40 // # Templates
41 //
42 // Pushbullet does not use templates in the Shoutrrr sense, but supports note-type
43 // push notifications with titles and body content.
44 //
45 // # Usage Examples
46 //
47 // ## Basic notification to all devices
48 //
49 // url := "pushbullet://o.34charactertokenstringhere1234"
50 // err := shoutrrr.Send(url, "Hello from Shoutrrr!")
51 //
52 // ## Notification with custom title
53 //
54 // url := "pushbullet://o.34charactertokenstringhere1234?title=Alert"
55 // err := shoutrrr.Send(url, "System notification message")
56 //
57 // ## Notification to specific device
58 //
59 // url := "pushbullet://o.34charactertokenstringhere1234/mydevice"
60 // err := shoutrrr.Send(url, "Message to specific device")
61 //
62 // ## Notification to email address
63 //
64 // url := "pushbullet://o.34charactertokenstringhere1234/[email protected]"
65 // err := shoutrrr.Send(url, "Message to email recipient")
66 //
67 // ## Notification to channel
68 //
69 // url := "pushbullet://o.34charactertokenstringhere1234/#mychannel"
70 // err := shoutrrr.Send(url, "Message to channel subscribers")
71 //
72 // ## Notification to multiple targets
73 //
74 // url := "pushbullet://o.34charactertokenstringhere1234/device1/device2/#channel"
75 // err := shoutrrr.Send(url, "Message to multiple targets")
76 //
77 // # Common Use Cases
78 //
79 // ## System Monitoring Alerts
80 //
81 // Send alerts from monitoring systems like Nagios, Prometheus, or Zabbix:
82 //
83 // url := "pushbullet://o.34charactertokenstringhere1234?title=Alert"
84 // err := shoutrrr.Send(url, "Disk space critical: 95% used")
85 //
86 // ## CI/CD Pipeline Notifications
87 //
88 // Notify about build status from Jenkins, GitHub Actions, or GitLab CI:
89 //
90 // url := "pushbullet://o.34charactertokenstringhere1234?title=Build%20Status"
91 // err := shoutrrr.Send(url, "Build #123 completed successfully")
92 //
93 // ## Cross-Device Notifications
94 //
95 // Send notifications that appear on all your connected devices:
96 //
97 // url := "pushbullet://o.34charactertokenstringhere1234"
98 // err := shoutrrr.Send(url, "Reminder from my server")
99 //
100 // ## Team Notifications via Channel
101 //
102 // Share notifications with team members subscribed to a channel:
103 //
104 // url := "pushbullet://o.34charactertokenstringhere1234/#operations"
105 // err := shoutrrr.Send(url, "Deployment started")
106 //
107 // ## Email-Based Notifications
108 //
109 // Send notifications to specific email addresses:
110 //
111 // url := "pushbullet://o.34charactertokenstringhere1234/[email protected]?title=Admin%20Alert"
112 // err := shoutrrr.Send(url, "Server requires attention")
113 //
114 // # Error Handling
115 //
116 // The service returns errors for various failure scenarios. Always check the returned error:
117 //
118 // err := shoutrrr.Send(url, message)
119 // if err != nil {
120 // log.Printf("Failed to send Pushbullet notification: %v", err)
121 // }
122 //
123 // Common error scenarios:
124 // - Invalid token format (must be exactly 34 characters)
125 // - Empty message content
126 // - Network connectivity issues
127 // - Invalid or non-existent target device
128 // - Invalid email address format
129 // - Invalid channel (channel must exist and be accessible)
130 // - HTTP error status codes (4xx/5xx) from the Pushbullet API
131 // - Authentication failures (invalid or expired token)
132 // - Push notification marked as inactive by the server
133 // - Response validation failures (mismatched title or body)
134 //
135 // # Security Considerations
136 //
137 // - API tokens are sensitive credentials - treat them like passwords
138 // - Store tokens securely - avoid hardcoding them in source code or public repositories
139 // - Use HTTPS (default) to protect token and message content in transit
140 // - Be cautious about who has access to your Pushbullet account and tokens
141 // - Consider message content - avoid sending sensitive information in notifications
142 // - Review Pushbullet's privacy policy and data handling practices
143 // - Rotate tokens periodically if supported
144 // - Use channel-based notifications for group communications instead of sharing tokens
145 //
146 // # Limitations and Behaviors
147 //
148 // - API token must be exactly 34 characters long
149 // - Message content cannot be empty
150 // - Title has a maximum length (typically truncated by the Pushbullet service)
151 // - Targets are processed sequentially - if one fails, the service returns an error
152 // - Channel names must be prefixed with # in the URL path
153 // - Email targets must be valid email addresses
154 // - Device targets must match the device identifier exactly
155 // - The service validates API responses to ensure message integrity
156 // - Push notifications are sent as "note" type messages
157 // - HTTP client timeout is set for API requests
158 // - Successful responses are validated for correctness (type, title, body, active status)
159 //
160 // # Related Links
161 //
162 // - Pushbullet Official Website: https://www.pushbullet.com
163 // - Pushbullet API Documentation: https://docs.pushbullet.com
164 // - Pushbullet Account Settings: https://www.pushbullet.com/settings
165 package pushbullet