Debian Codegraph @

pkg/services/push/join/doc.go

raw
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