| 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 |