Debian Codegraph @

shoutrrr.go

raw
1 // Package shoutrrr provides a simple API for sending notifications to various services.
2 //
3 // The package supports multiple notification services including Slack, Discord,
4 // Telegram, and many others. Notifications are sent using service-specific URLs
5 // that contain all necessary configuration and authentication details.
6 //
7 // Basic usage:
8 //
9 // if err := shoutrrr.Send("slack://webhook/...", "Hello, World!"); err != nil {
10 // // handle error
11 // }
12 //
13 // For more complex scenarios, create a sender with multiple service URLs:
14 //
15 // sender, err := shoutrrr.CreateSender("slack://webhook/...", "discord://webhook/...")
16 //
17 // The package uses a default router, but you can also create custom routers
18 // using router.New for more control over the notification pipeline.
19 package shoutrrr
20
21 import (
22 "fmt"
23
24 "github.com/nicholas-fedor/shoutrrr/internal/meta"
25 "github.com/nicholas-fedor/shoutrrr/pkg/router"
26 "github.com/nicholas-fedor/shoutrrr/pkg/types"
27 )
28
29 // defaultRouter manages the creation and routing of notification services.
30 var defaultRouter = router.ServiceRouter{
31 Timeout: router.DefaultTimeout,
32 }
33
34 // Send delivers a notification message using the specified URL.
35 func Send(rawURL, message string) error {
36 service, err := defaultRouter.Locate(rawURL)
37 if err != nil {
38 return fmt.Errorf("locating service for URL %q: %w", rawURL, err)
39 }
40
41 if err := service.Send(message, &types.Params{}); err != nil {
42 return fmt.Errorf("sending message via service at %q: %w", rawURL, err)
43 }
44
45 return nil
46 }
47
48 // CreateSender constructs a new service router for the given URLs without a logger.
49 func CreateSender(rawURLs ...string) (*router.ServiceRouter, error) {
50 sr, err := router.New(nil, rawURLs...)
51 if err != nil {
52 return nil, fmt.Errorf("creating sender for URLs %v: %w", rawURLs, err)
53 }
54
55 return sr, nil
56 }
57
58 // NewSender constructs a new service router with a logger for the given URLs.
59 func NewSender(logger types.StdLogger, serviceURLs ...string) (*router.ServiceRouter, error) {
60 sr, err := router.New(logger, serviceURLs...)
61 if err != nil {
62 return nil, fmt.Errorf("creating sender with logger for URLs %v: %w", serviceURLs, err)
63 }
64
65 return sr, nil
66 }
67
68 // SetLogger configures the logger for all services in the default router.
69 func SetLogger(logger types.StdLogger) {
70 defaultRouter.SetLogger(logger)
71 }
72
73 // Version returns the current Shoutrrr version.
74 func Version() string {
75 return meta.Version
76 }