| 1 |
// Package ntfy provides a notification service for sending push notifications via ntfy.sh. |
| 2 |
// |
| 3 |
// The ntfy service allows sending notifications to ntfy topics, which can be subscribed to |
| 4 |
// by mobile apps, web browsers, and other clients. It supports rich notifications with |
| 5 |
// titles, priorities, tags, attachments, actions, and more. ntfy is a simple HTTP-based |
| 6 |
// pub-sub notification service that works with any programming language. |
| 7 |
// |
| 8 |
// # URL Format |
| 9 |
// |
| 10 |
// The service URL follows the format: |
| 11 |
// |
| 12 |
// ntfy://[user:password@]host[:port]/topic[?query] |
| 13 |
// |
| 14 |
// Where: |
| 15 |
// - user: optional username for authentication |
| 16 |
// - password: optional password for authentication |
| 17 |
// - host: ntfy server hostname (default: ntfy.sh) |
| 18 |
// - port: optional port number (default: 443 for HTTPS, 80 for HTTP) |
| 19 |
// - topic: target topic name (required) |
| 20 |
// - query: configuration parameters |
| 21 |
// |
| 22 |
// # Configuration Options |
| 23 |
// |
| 24 |
// The following query parameters can be used to configure the service: |
| 25 |
// |
| 26 |
// - title: notification title |
| 27 |
// - priority: message priority (1=min, 2=low, 3=default, 4=high, 5=max/urgent) |
| 28 |
// - tags: comma-separated list of tags (may map to emojis) |
| 29 |
// - actions: semicolon-separated list of user action buttons |
| 30 |
// - click: URL to open when notification is clicked |
| 31 |
// - attach: URL of attachment to include |
| 32 |
// - filename: filename for attachment |
| 33 |
// - delay: timestamp or duration for delayed delivery (e.g., "30m", "1h", "2023-12-25T10:00:00Z") |
| 34 |
// - email: email address for email notifications |
| 35 |
// - icon: URL to use as notification icon |
| 36 |
// - cache: whether to cache messages (default: yes) |
| 37 |
// - firebase: whether to send via Firebase (default: yes) |
| 38 |
// - disabletls: set to "yes" to disable TLS verification |
| 39 |
// |
| 40 |
// # Templates |
| 41 |
// |
| 42 |
// ntfy does not use templates in the Shoutrrr sense, but supports rich message formatting |
| 43 |
// through its native features like titles, tags, priorities, and actions. |
| 44 |
// |
| 45 |
// # Usage Examples |
| 46 |
// |
| 47 |
// ## Basic notification |
| 48 |
// |
| 49 |
// url := "ntfy://mytopic" |
| 50 |
// err := shoutrrr.Send(url, "Hello from Shoutrrr!") |
| 51 |
// |
| 52 |
// ## Notification with title and high priority |
| 53 |
// |
| 54 |
// url := "ntfy://mytopic?title=Alert&priority=high" |
| 55 |
// err := shoutrrr.Send(url, "System is down!") |
| 56 |
// |
| 57 |
// ## Notification with tags and actions |
| 58 |
// |
| 59 |
// url := "ntfy://mytopic?tags=warning,server&actions=view,%20View%20logs,%20https://logs.example.com" |
| 60 |
// err := shoutrrr.Send(url, "Server error occurred") |
| 61 |
// |
| 62 |
// ## Notification with attachment |
| 63 |
// |
| 64 |
// url := "ntfy://mytopic?title=Backup&attach=https://files.example.com/backup.zip&filename=backup.zip" |
| 65 |
// err := shoutrrr.Send(url, "Backup completed successfully") |
| 66 |
// |
| 67 |
// ## Delayed notification |
| 68 |
// |
| 69 |
// url := "ntfy://mytopic?delay=1h" |
| 70 |
// err := shoutrrr.Send(url, "Reminder: Meeting in 1 hour") |
| 71 |
// |
| 72 |
// ## Notification with authentication |
| 73 |
// |
| 74 |
// url := "ntfy://user:[email protected]/mytopic" |
| 75 |
// err := shoutrrr.Send(url, "Authenticated notification") |
| 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 := "ntfy://alerts?priority=high&tags=warning,server" |
| 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 := "ntfy://builds?tags=success,github&title=Build%20Successful" |
| 91 |
// err := shoutrrr.Send(url, "Build #123 passed") |
| 92 |
// |
| 93 |
// ## Home Automation |
| 94 |
// |
| 95 |
// Integrate with home automation systems like Home Assistant: |
| 96 |
// |
| 97 |
// url := "ntfy://home?tags=home,security&priority=urgent" |
| 98 |
// err := shoutrrr.Send(url, "Motion detected at front door") |
| 99 |
// |
| 100 |
// ## Backup Completion Notifications |
| 101 |
// |
| 102 |
// Notify when backups complete: |
| 103 |
// |
| 104 |
// url := "ntfy://backups?tags=backup,done&title=Backup%20Complete" |
| 105 |
// err := shoutrrr.Send(url, "Daily backup finished successfully") |
| 106 |
// |
| 107 |
// ## Scheduled Reminders |
| 108 |
// |
| 109 |
// Send delayed notifications for reminders: |
| 110 |
// |
| 111 |
// url := "ntfy://reminders?delay=9am&title=Morning%20Reminder" |
| 112 |
// err := shoutrrr.Send(url, "Don't forget the team meeting!") |
| 113 |
// |
| 114 |
// # Error Handling |
| 115 |
// |
| 116 |
// The service returns errors for network failures, HTTP error status codes (4xx/5xx), |
| 117 |
// authentication failures, and configuration issues. Always check the returned error: |
| 118 |
// |
| 119 |
// err := shoutrrr.Send(url, message) |
| 120 |
// if err != nil { |
| 121 |
// log.Printf("Failed to send ntfy notification: %v", err) |
| 122 |
// } |
| 123 |
// |
| 124 |
// Common error scenarios: |
| 125 |
// - Invalid topic name |
| 126 |
// - Authentication failure (wrong credentials) |
| 127 |
// - Network connectivity issues |
| 128 |
// - Server rate limiting |
| 129 |
// - Invalid attachment URLs |
| 130 |
// |
| 131 |
// # Security Considerations |
| 132 |
// |
| 133 |
// - Use HTTPS whenever possible (default behavior) |
| 134 |
// - Store credentials securely, not in URLs if possible |
| 135 |
// - Consider topic names as passwords - use unique, hard-to-guess names |
| 136 |
// - Be cautious with attachment URLs - ensure they are from trusted sources |
| 137 |
// - Use authentication for private topics |
| 138 |
// - Consider message content - avoid sending sensitive information in notifications |
| 139 |
// - Rate limiting may apply depending on server configuration |
| 140 |
// |
| 141 |
// # Limitations and Behaviors |
| 142 |
// |
| 143 |
// - Topic names are case-sensitive |
| 144 |
// - Maximum message size depends on server configuration (typically 4KB) |
| 145 |
// - Attachments are referenced by URL, not uploaded directly |
| 146 |
// - Actions are limited to view, broadcast, and http types |
| 147 |
// - Delayed delivery minimum is 10 seconds, maximum is 3 days |
| 148 |
// - Messages may be cached on the server for up to 12 hours after delivery |
| 149 |
// - Firebase notifications may not work in all regions or for all clients |
| 150 |
// - Some features (like actions) are client-dependent and may not work on all platforms |
| 151 |
package ntfy |