| 1 |
// Package bark provides a notification service for sending push notifications via Bark. |
| 2 |
// |
| 3 |
// The Bark service allows sending push notifications to iOS devices through a self-hosted |
| 4 |
// Bark server. Bark is an iOS push notification service that provides a simple REST API |
| 5 |
// for sending custom notifications with titles, sounds, badges, and more. It supports |
| 6 |
// device-specific keys for targeted notifications and offers rich notification features |
| 7 |
// including custom icons (iOS 15+), notification grouping, and actionable notifications. |
| 8 |
// |
| 9 |
// For more information about the Bark server, see: https://github.com/Finb/Bark |
| 10 |
// |
| 11 |
// # URL Format |
| 12 |
// |
| 13 |
// The service URL follows the format: |
| 14 |
// |
| 15 |
// bark://:devicekey@host[:port][/path][?query] |
| 16 |
// |
| 17 |
// Where: |
| 18 |
// - devicekey: device key for authentication (required, passed as password in URL) |
| 19 |
// - host: Bark server hostname (required) |
| 20 |
// - port: optional port number (default: 443 for HTTPS, 80 for HTTP) |
| 21 |
// - path: optional server path (default: "/") |
| 22 |
// - query: configuration parameters |
| 23 |
// |
| 24 |
// # Configuration Options |
| 25 |
// |
| 26 |
// The following query parameters can be used to configure the service: |
| 27 |
// |
| 28 |
// - title: notification title (default: empty, uses app name) |
| 29 |
// - sound: notification sound (default: empty, uses default system sound) |
| 30 |
// See: https://github.com/Finb/Bark/tree/master/Sounds |
| 31 |
// - badge: badge number displayed next to app icon (default: 0) |
| 32 |
// - icon: URL to notification icon (iOS 15+ only) |
| 33 |
// - group: notification group identifier |
| 34 |
// - url: URL to open when notification is tapped |
| 35 |
// - category: notification category (reserved for future use) |
| 36 |
// - copy: text to copy to clipboard when notification is tapped |
| 37 |
// - scheme: server protocol, "http" or "https" (default: "https") |
| 38 |
// |
| 39 |
// # Templates |
| 40 |
// |
| 41 |
// Bark does not use templates in the Shoutrrr sense, but supports rich notification |
| 42 |
// formatting through its native features like titles, sounds, badges, and custom actions. |
| 43 |
// |
| 44 |
// # Usage Examples |
| 45 |
// |
| 46 |
// ## Basic notification |
| 47 |
// |
| 48 |
// url := "bark://:[email protected]" |
| 49 |
// err := shoutrrr.Send(url, "Hello from Shoutrrr!") |
| 50 |
// |
| 51 |
// ## Notification with custom title and sound |
| 52 |
// |
| 53 |
// url := "bark://:[email protected]?title=Alert&sound=alarm" |
| 54 |
// err := shoutrrr.Send(url, "System is down!") |
| 55 |
// |
| 56 |
// ## Notification with badge count |
| 57 |
// |
| 58 |
// url := "bark://:[email protected]?title=Messages&badge=5" |
| 59 |
// err := shoutrrr.Send(url, "You have 5 new messages") |
| 60 |
// |
| 61 |
// ## Notification with custom icon |
| 62 |
// |
| 63 |
// url := "bark://:[email protected]?icon=https://example.com/icon.png" |
| 64 |
// err := shoutrrr.Send(url, "Notification with custom icon") |
| 65 |
// |
| 66 |
// ## Notification with group and URL |
| 67 |
// |
| 68 |
// url := "bark://:[email protected]?group=alerts&url=https://example.com/details" |
| 69 |
// err := shoutrrr.Send(url, "Click to view alert details") |
| 70 |
// |
| 71 |
// ## Notification that copies to clipboard |
| 72 |
// |
| 73 |
// url := "bark://:[email protected]?copy=https://example.com/api/token" |
| 74 |
// err := shoutrrr.Send(url, "API token copied to clipboard") |
| 75 |
// |
| 76 |
// ## Notification to custom server path |
| 77 |
// |
| 78 |
// url := "bark://:[email protected]:2225/bark/push" |
| 79 |
// err := shoutrrr.Send(url, "Notification to custom path") |
| 80 |
// |
| 81 |
// ## Notification with HTTP (insecure) |
| 82 |
// |
| 83 |
// url := "bark://:[email protected]?scheme=http" |
| 84 |
// err := shoutrrr.Send(url, "Insecure notification (not recommended)") |
| 85 |
// |
| 86 |
// # Common Use Cases |
| 87 |
// |
| 88 |
// ## System Monitoring Alerts |
| 89 |
// |
| 90 |
// Send alerts from monitoring systems like Nagios, Prometheus, or Zabbix: |
| 91 |
// |
| 92 |
// url := "bark://:[email protected]?title=Alert&sound=alarm" |
| 93 |
// err := shoutrrr.Send(url, "Disk space critical: 95% used") |
| 94 |
// |
| 95 |
// ## CI/CD Pipeline Notifications |
| 96 |
// |
| 97 |
// Notify about build status from Jenkins, GitHub Actions, or GitLab CI: |
| 98 |
// |
| 99 |
// url := "bark://:[email protected]?title=Build%20Failed&sound=alert" |
| 100 |
// err := shoutrrr.Send(url, "Build #123 failed on main branch") |
| 101 |
// |
| 102 |
// ## Home Automation |
| 103 |
// |
| 104 |
// Integrate with home automation systems like Home Assistant: |
| 105 |
// |
| 106 |
// url := "bark://:[email protected]?title=Security&sound=alarm&group=home" |
| 107 |
// err := shoutrrr.Send(url, "Motion detected at front door") |
| 108 |
// |
| 109 |
// ## Backup Completion Notifications |
| 110 |
// |
| 111 |
// Notify when backups complete: |
| 112 |
// |
| 113 |
// url := "bark://:[email protected]?title=Backup&sound=complete" |
| 114 |
// err := shoutrrr.Send(url, "Daily backup finished successfully") |
| 115 |
// |
| 116 |
// ## Application Health Monitoring |
| 117 |
// |
| 118 |
// Send health check notifications from applications: |
| 119 |
// |
| 120 |
// url := "bark://:[email protected]?title=Health%20Check" |
| 121 |
// err := shoutrrr.Send(url, "All services are healthy") |
| 122 |
// |
| 123 |
// ## Incident Response |
| 124 |
// |
| 125 |
// Send urgent notifications for incident response: |
| 126 |
// |
| 127 |
// url := "bark://:[email protected]?title=INCIDENT&sound=alarm&group=ops" |
| 128 |
// err := shoutrrr.Send(url, "Database connection lost - immediate attention required") |
| 129 |
// |
| 130 |
// # Error Handling |
| 131 |
// |
| 132 |
// The service returns errors for various failure scenarios. Always check the returned error: |
| 133 |
// |
| 134 |
// err := shoutrrr.Send(url, message) |
| 135 |
// if err != nil { |
| 136 |
// log.Printf("Failed to send Bark notification: %v", err) |
| 137 |
// } |
| 138 |
// |
| 139 |
// Common error scenarios: |
| 140 |
// - Invalid device key format |
| 141 |
// - Empty message content |
| 142 |
// - Network connectivity issues |
| 143 |
// - Invalid server hostname or port |
| 144 |
// - TLS certificate verification failures (when HTTPS is used) |
| 145 |
// - HTTP error status codes (4xx/5xx) from the Bark server |
| 146 |
// - Invalid icon URL |
| 147 |
// - Server-side errors (returned in API response message) |
| 148 |
// |
| 149 |
// # Security Considerations |
| 150 |
// |
| 151 |
// - Use HTTPS whenever possible (default behavior) to protect notification content in transit |
| 152 |
// - Store device keys securely - avoid hardcoding them in source code or configuration files |
| 153 |
// - Device keys are device-specific and act as authentication tokens |
| 154 |
// - Be cautious with scheme=http - only use in trusted environments as it disables encryption |
| 155 |
// - Validate icon URLs - ensure they point to trusted sources |
| 156 |
// - Consider message content - avoid sending sensitive information in notification messages |
| 157 |
// - Use appropriate notification sounds - avoid disruptive sounds in production environments |
| 158 |
// - Implement proper access controls on your Bark server to prevent unauthorized key usage |
| 159 |
// |
| 160 |
// # Limitations and Behaviors |
| 161 |
// |
| 162 |
// - Device key is required and must be provided in the URL password field |
| 163 |
// - Message content cannot be empty |
| 164 |
// - Icon is only available on iOS 15 or later |
| 165 |
// - Category is reserved for future use |
| 166 |
// - Badge number can be any non-negative integer |
| 167 |
// - Sound values must match available sounds in the Bark server |
| 168 |
// (see: https://github.com/Finb/Bark/tree/master/Sounds) |
| 169 |
// - Custom sounds can be added to the Bark server |
| 170 |
// - Group helps organize notifications but display depends on the client |
| 171 |
// - URL field specifies what URL to open when notification is tapped |
| 172 |
// - Copy field specifies text to copy to clipboard when notification is tapped |
| 173 |
// - Server path defaults to "/" if not specified |
| 174 |
// - Default scheme is "https" for secure communication |
| 175 |
// - HTTP client timeout is set for API requests |
| 176 |
// - Server response includes code, message, and timestamp upon delivery |
| 177 |
// - Failed requests return structured error responses with error codes and descriptions |
| 178 |
package bark |