Debian Codegraph @

pkg/services/chat/zulip/doc.go

raw
1 // Package zulip provides a notification service for sending messages to Zulip streams or topics.
2 //
3 // This package is part of the shoutrrr notification library and implements the Service interface
4 // for delivering notifications to Zulip, an open-source team chat application with topic-based
5 // threading.
6 //
7 // # Service Configuration
8 //
9 // The Service struct provides the main functionality for sending notifications to Zulip.
10 // It embeds standard.Standard for common service features and uses form-encoded API requests
11 // for message delivery.
12 //
13 // # Configuration Fields
14 //
15 // The Config struct supports the following settings:
16 //
17 // - BotMail: The bot's email address for authentication (required)
18 // - BotKey: The bot's API key for authentication (required)
19 // - Host: The Zulip server hostname (with optional port) (required)
20 // - Type: Message type, "channel" or "direct" (optional, defaults to channel)
21 // - Stream: The target stream (channel) name (optional)
22 // - Topic: The target topic within the stream (optional)
23 // - Title: Notification title prepended to message content (optional)
24 // - To: Comma-separated recipients for direct messages (optional)
25 // - ReadBySender: Whether to mark sent DM read by the bot (optional, default false)
26 //
27 // # Direct Messages
28 //
29 // Set Type to MessageTypeDirect (or "direct" in params/URL) and provide recipients via the To
30 // field or "to" param (comma separated emails/IDs). The "stream" field can be used as fallback
31 // recipient for direct if To is not set.
32 //
33 // # Server-Side Limits
34 //
35 // On first send, the service fetches max_message_length and max_topic_length from the
36 // Zulip /api/v1/register endpoint (realm section). Falls back to built-in defaults (10000 bytes
37 // content, 60 chars topic) if the call fails or returns zero/ non-success.
38 //
39 // # Usage Example
40 //
41 // service := &zulip.Service{}
42 // err := service.Initialize(serviceURL, logger)
43 // if err != nil {
44 // // handle error
45 // }
46 // err = service.Send("Your message here", nil)
47 //
48 // # Payload Creation
49 //
50 // The package provides CreatePayload for building properly formatted form-encoded requests
51 // for the Zulip messages API, supporting channel/direct types, JSON-encoded recipient lists
52 // for DMs, topics, and read_by_sender.
53 //
54 // # URL Format
55 //
56 // The configuration URL format is:
57 //
58 // zulip://botmail:botkey@host?stream=general&topic=alerts
59 //
60 // Or for direct:
61 //
62 // zulip://botmail:botkey@host?type=direct&[email protected],[email protected]
63 //
64 // # Validation
65 //
66 // The package includes validation for:
67 // - Bot email address presence
68 // - API key presence
69 // - Host configuration (including optional :port)
70 // - Message type (channel/direct/empty)
71 // - Recipient presence per message type
72 // - Topic length (server or default 60 chars)
73 // - Message size (server or default 10000 bytes)
74 //
75 // For more information about Zulip bots, visit: https://zulip.com/help/bots-and-integrations
76 package zulip