| 1 |
// Package join provides a notification service for sending push notifications via Join. |
| 2 |
// |
| 3 |
// The Join service allows sending push notifications to devices running the Join app |
| 4 |
// (by Joaoapps). Join is a cross-platform notification service that works on Android, |
| 5 |
// iOS, Windows, and other platforms. It enables you to send notifications, SMS, |
| 6 |
// and other messages to your devices from any application that can make HTTP requests. |
| 7 |
// |
| 8 |
// For more information about Join, visit https://joaoapps.com/join/ |
| 9 |
// |
| 10 |
// For more information about the Join API, visit https://joinjoaomgcd.appspot.com/ |
| 11 |
// |
| 12 |
// # URL Format |
| 13 |
// |
| 14 |
// The service URL follows the format: |
| 15 |
// |
| 16 |
// join://:apikey@join[?query] |
| 17 |
// |
| 18 |
// Where: |
| 19 |
// - apikey: Join API key/token (required) - found in the Join app settings |
| 20 |
// - query: configuration parameters |
| 21 |
// |
| 22 |
// # Configuration Options |
| 23 |
// |
| 24 |
// The following query parameters can be used to configure the service: |
| 25 |
// |
| 26 |
// - devices: comma-separated list of device IDs to send notification to (required) |
| 27 |
// - title: notification title (optional) |
| 28 |
// - icon: URL of icon to display with the notification (optional) |
| 29 |
// |
| 30 |
// # Templates |
| 31 |
// |
| 32 |
// Join does not use templates in the Shoutrrr sense, but supports native notification |
| 33 |
// features like titles and custom icons that can be configured via query parameters. |
| 34 |
// |
| 35 |
// # Usage Examples |
| 36 |
// |
| 37 |
// ## Basic notification to specific device |
| 38 |
// |
| 39 |
// url := "join://:my-api-key@join?devices=device-id-123" |
| 40 |
// err := shoutrrr.Send(url, "Hello from Shoutrrr!") |
| 41 |
// |
| 42 |
// ## Notification with title |
| 43 |
// |
| 44 |
// url := "join://:my-api-key@join?devices=device-id-123&title=Alert" |
| 45 |
// err := shoutrrr.Send(url, "System is down!") |
| 46 |
// |
| 47 |
// ## Notification with custom icon |
| 48 |
// |
| 49 |
// url := "join://:my-api-key@join?devices=device-id-123&title=Backup&icon=https://example.com/icon.png" |
| 50 |
// err := shoutrrr.Send(url, "Backup completed successfully") |
| 51 |
// |
| 52 |
// ## Notification to multiple devices |
| 53 |
// |
| 54 |
// url := "join://:my-api-key@join?devices=device1,device2,device3&title=Multi-device" |
| 55 |
// err := shoutrrr.Send(url, "Sent to multiple devices!") |
| 56 |
// |
| 57 |
// # Common Use Cases |
| 58 |
// |
| 59 |
// ## System Monitoring Alerts |
| 60 |
// |
| 61 |
// Send alerts from monitoring systems like Nagios, Prometheus, or Zabbix: |
| 62 |
// |
| 63 |
// url := "join://:my-api-key@join?devices=monitoring-device&title=Alert" |
| 64 |
// err := shoutrrr.Send(url, "Disk space critical: 95% used") |
| 65 |
// |
| 66 |
// ## CI/CD Pipeline Notifications |
| 67 |
// |
| 68 |
// Notify about build status from Jenkins, GitHub Actions, or GitLab CI: |
| 69 |
// |
| 70 |
// url := "join://:my-api-key@join?devices=ci-device&title=Build%20Status" |
| 71 |
// err := shoutrrr.Send(url, "Build #123 completed successfully") |
| 72 |
// |
| 73 |
// ## Cross-Device Notifications |
| 74 |
// |
| 75 |
// Send notifications that appear on multiple devices: |
| 76 |
// |
| 77 |
// url := "join://:my-api-key@join?devices=phone,laptop,tablet&title=Reminder" |
| 78 |
// err := shoutrrr.Send(url, "Don't forget the meeting!") |
| 79 |
// |
| 80 |
// ## Home Automation |
| 81 |
// |
| 82 |
// Integrate with home automation systems like Home Assistant: |
| 83 |
// |
| 84 |
// url := "join://:my-api-key@join?devices=automation-device&title=Security" |
| 85 |
// err := shoutrrr.Send(url, "Motion detected at front door") |
| 86 |
// |
| 87 |
// ## Remote Device Commands |
| 88 |
// |
| 89 |
// Send commands to devices running the Join app: |
| 90 |
// |
| 91 |
// url := "join://:my-api-key@join?devices=remote-device&title=Command" |
| 92 |
// err := shoutrrr.Send(url, "Run backup script now") |
| 93 |
// |
| 94 |
// # Error Handling |
| 95 |
// |
| 96 |
// The service returns errors for various failure scenarios. Always check the returned error: |
| 97 |
// |
| 98 |
// err := shoutrrr.Send(url, message) |
| 99 |
// if err != nil { |
| 100 |
// log.Printf("Failed to send Join notification: %v", err) |
| 101 |
// } |
| 102 |
// |
| 103 |
// Common error scenarios: |
| 104 |
// - Missing API key (required) |
| 105 |
// - Missing device IDs (required) |
| 106 |
// - Network connectivity issues |
| 107 |
// - Invalid API key |
| 108 |
// - Device IDs that don't exist or are offline |
| 109 |
// - HTTP error status codes from Join API (non-2xx responses) |
| 110 |
// |
| 111 |
// # Security Considerations |
| 112 |
// |
| 113 |
// - Store API keys securely - avoid hardcoding them in source code or configuration files |
| 114 |
// - API keys provide access to send notifications to your devices - treat them as secrets |
| 115 |
// - Consider using separate API keys for different purposes to limit exposure |
| 116 |
// - Device IDs are specific to each device and should be kept private |
| 117 |
// - Be cautious about what data you send in notifications - they may be visible on lock screens |
| 118 |
// - Review Join's data handling and privacy policies |
| 119 |
// - Consider implementing rate limiting on your side to avoid triggering any limits |
| 120 |
// - Message content should not contain sensitive information if notifications are visible on lock screens |
| 121 |
// |
| 122 |
// # Limitations and Behaviors |
| 123 |
// |
| 124 |
// - At least one device ID must be specified |
| 125 |
// - API key is required and must be a valid Join API key |
| 126 |
// - Multiple devices can be specified as comma-separated values; notification will be sent to all |
| 127 |
// - The HTTP client timeout is the default Go HTTP client timeout |
| 128 |
// - Join API returns HTTP 200 on successful notification sends |
| 129 |
// - Failed requests (non-2xx responses) will return an error |
| 130 |
// - Title parameter creates a notification with a title (without it, just the message is sent) |
| 131 |
// - Icon parameter expects a valid URL to an image file |
| 132 |
// |
| 133 |
// # Join API Details |
| 134 |
// |
| 135 |
// The notification is sent as a POST request to Join's messaging API: |
| 136 |
// |
| 137 |
// https://joinjoaomgcd.appspot.com/_ah/api/messaging/v1/sendPush |
| 138 |
// |
| 139 |
// The request includes the following parameters: |
| 140 |
// |
| 141 |
// - apikey: Your Join API key |
| 142 |
// - deviceIds: Comma-separated list of device IDs |
| 143 |
// - text: The notification message body |
| 144 |
// - title: Optional notification title |
| 145 |
// - icon: Optional icon URL |
| 146 |
// |
| 147 |
// For more information about the Join API and available parameters, visit |
| 148 |
// the Join API documentation at https://joinjoaomgcd.appspot.com/ |
| 149 |
package join |