feat(service): PagerDuty service integration (#933)

Co-authored-by: Niko Köser <koeserniko@gmail.com>

Author: tecnologer

README.md

@@ -95,6 +95,7 @@ Yes, please! Contributions of all kinds are very welcome! Feel free to check our
 | [Mailgun](https://www.mailgun.com)                                                | [service/mailgun](service/mailgun)       | [mailgun/mailgun-go](https://github.com/mailgun/mailgun-go)                                     | :heavy_check_mark: |
 | [Matrix](https://www.matrix.org)                                                  | [service/matrix](service/matrix)         | [mautrix/go](https://github.com/mautrix/go)                                                     | :heavy_check_mark: |
 | [Microsoft Teams](https://www.microsoft.com/microsoft-teams)                      | [service/msteams](service/msteams)       | [atc0005/go-teams-notify](https://github.com/atc0005/go-teams-notify)                           | :heavy_check_mark: |
+| [PagerDuty](https://www.pagerduty.com)                                            | [service/pagerduty](service/pagerduty)   | [PagerDuty/go-pagerduty](https://github.com/PagerDuty/go-pagerduty)                             | :heavy_check_mark: |
 | [Plivo](https://www.plivo.com)                                                    | [service/plivo](service/plivo)           | [plivo/plivo-go](https://github.com/plivo/plivo-go)                                             | :heavy_check_mark: |
 | [Pushover](https://pushover.net/)                                                 | [service/pushover](service/pushover)     | [gregdel/pushover](https://github.com/gregdel/pushover)                                         | :heavy_check_mark: |
 | [Pushbullet](https://www.pushbullet.com)                                          | [service/pushbullet](service/pushbullet) | [cschomburg/go-pushbullet](https://github.com/cschomburg/go-pushbullet)                         | :heavy_check_mark: |

go.mod

@@ -63,6 +63,7 @@ require (
 	github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.49.0 // indirect
 	github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.49.0 // indirect
 	github.com/MicahParks/keyfunc v1.9.0 // indirect
+	github.com/PagerDuty/go-pagerduty v1.8.0 // indirect
 	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.12.1 // indirect
 	github.com/census-instrumentation/opencensus-proto v0.4.1 // indirect
 	github.com/cncf/xds/go v0.0.0-20240905190251-b4127c9b8d78 // indirect

go.sum

@@ -40,6 +40,8 @@ github.com/Jeffail/gabs v1.4.0 h1://5fYRRTq1edjfIrQGvdkcd22pkYUrHZ5YC/H2GJVAo=
 github.com/Jeffail/gabs v1.4.0/go.mod h1:6xMvQMK4k33lb7GUUpaAPh6nKMmemQeg5d4gn7/bOXc=
 github.com/MicahParks/keyfunc v1.9.0 h1:lhKd5xrFHLNOWrDc4Tyb/Q1AJ4LCzQ48GVJyVIID3+o=
 github.com/MicahParks/keyfunc v1.9.0/go.mod h1:IdnCilugA0O/99dW+/MkvlyrsX8+L8+x95xuVNtM5jw=
+github.com/PagerDuty/go-pagerduty v1.8.0 h1:MTFqTffIcAervB83U7Bx6HERzLbyaSPL/+oxH3zyluI=
+github.com/PagerDuty/go-pagerduty v1.8.0/go.mod h1:nzIeAqyFSJAFkjWKvMzug0JtwDg+V+UoCWjFrfFH5mI=
 github.com/RocketChat/Rocket.Chat.Go.SDK v0.0.0-20240116134246-a8cbe886bab0 h1:ztLQGVQsey3BjCoh0TvHc/iKTQmkio2OmsIxhuu+EeY=
 github.com/RocketChat/Rocket.Chat.Go.SDK v0.0.0-20240116134246-a8cbe886bab0/go.mod h1:rjP7sIipbZcagro/6TCk6X0ZeFT2eyudH5+fve/cbBA=
 github.com/SherClockHolmes/webpush-go v1.4.0 h1:ocnzNKWN23T9nvHi6IfyrQjkIc0oJWv1B1pULsf9i3s=

service/pagerduty/README.md

@@ -0,0 +1,70 @@
+ # PagerDuty Notifications
+
+ ## Prerequisites
+
+ Ensure you have a valid PagerDuty API token to authenticate requests.
+
+ ### Compatibility
+
+ This service is compatible with the PagerDuty API for creating incidents.
+
+ ## Usage
+ ```go
+ package main
+
+ import (
+     "context"
+     "log"
+
+     "github.com/nikoksr/notify"
+     "github.com/nikoksr/notify/service/pagerduty"
+ )
+
+ func main() {
+     // Create a new PagerDuty service. Replace 'your_pagerduty_api_token' with your actual PagerDuty API token.
+     pagerDutyService, err := pagerduty.New("your_pagerduty_api_token")
+     if err != nil {
+         log.Fatalf("failed to create pagerduty service: %s", err)
+     }
+
+     // Set the sender address and add receivers. (required)
+     pagerDutyService.SetFromAddress("sender@example.com")
+     pagerDutyService.AddReceivers("ServiceDirectory1", "ServiceDirectory2")
+
+     // Set the urgency, priority ID, and notification type. (optional)
+      pagerDutyService.SetUrgency("high")
+      pagerDutyService.SetPriorityID("P123456")
+      pagerDutyService.SetNotificationType("incident")
+
+     // Create a notifier instance and register the PagerDuty service to it.
+     notifier := notify.New()
+     notifier.UseServices(pagerDutyService)
+
+     // Send a notification.
+     err = notifier.Send(context.Background(), "Test Alert", "This is a test alert from PagerDuty service.")
+     if err != nil {
+         log.Fatalf("failed to send notification: %s", err)
+     }
+
+     log.Println("Notification sent successfully")
+ }
+ ```
+
+ ## Configuration
+
+ ### Required Properties
+ - **API Token**: Your PagerDuty API token.
+ - **From Address**: The email address of the sender. The author of the incident.
+ - **Receivers**: List of PagerDuty service directories to send the incident to.
+
+ ### Optional Properties
+ - **Urgency**: The urgency of the incident (e.g., "high", "low").
+ - **PriorityID**: The ID of the priority level assigned to the incident.
+ - **NotificationType**: Type of notification (default is "incident").
+
+ These properties can be set using the respective setter methods provided by the `Config` struct:
+ - `SetFromAddress(string)`
+ - `AddReceivers(...string)`
+ - `SetUrgency(string)`
+ - `SetPriorityID(string)`
+ - `SetNotificationType(string)`

service/pagerduty/config.go

@@ -0,0 +1,96 @@
+package pagerduty
+
+import (
+	"errors"
+	"fmt"
+	"net/mail"
+
+	"github.com/PagerDuty/go-pagerduty"
+)
+
+const (
+	APIReferenceType        = "service_reference"
+	APIPriorityReference    = "priority_reference"
+	DefaultNotificationType = "incident"
+)
+
+// Config contains the configuration for the PagerDuty service.
+type Config struct {
+	FromAddress      string
+	Receivers        []string
+	NotificationType string
+	Urgency          string
+	PriorityID       string
+}
+
+func NewConfig() *Config {
+	return &Config{
+		NotificationType: DefaultNotificationType,
+		Receivers:        make([]string, 0, 1),
+	}
+}
+
+// OK checks if the configuration is valid.
+// It returns an error if the configuration is invalid.
+func (c *Config) OK() error {
+	if c.FromAddress == "" {
+		return errors.New("from address is required")
+	}
+
+	_, err := mail.ParseAddress(c.FromAddress)
+	if err != nil {
+		return fmt.Errorf("from address is invalid: %w", err)
+	}
+
+	if len(c.Receivers) == 0 {
+		return errors.New("at least one receiver is required")
+	}
+
+	if c.NotificationType == "" {
+		return errors.New("notification type is required")
+	}
+
+	return nil
+}
+
+// PriorityReference returns the PriorityID reference if it is set, otherwise it returns nil.
+func (c *Config) PriorityReference() *pagerduty.APIReference {
+	if c.PriorityID == "" {
+		return nil
+	}
+
+	return &pagerduty.APIReference{
+		ID:   c.PriorityID,
+		Type: APIPriorityReference,
+	}
+}
+
+// SetFromAddress sets the from address in the configuration.
+func (c *Config) SetFromAddress(fromAddress string) {
+	c.FromAddress = fromAddress
+}
+
+// AddReceivers appends the receivers to the configuration.
+func (c *Config) AddReceivers(receivers ...string) {
+	c.Receivers = append(c.Receivers, receivers...)
+}
+
+// SetPriorityID sets the PriorityID in the configuration.
+func (c *Config) SetPriorityID(priorityID string) {
+	c.PriorityID = priorityID
+}
+
+// SetUrgency sets the urgency in the configuration.
+func (c *Config) SetUrgency(urgency string) {
+	c.Urgency = urgency
+}
+
+// SetNotificationType sets the notification type in the configuration.
+// If the notification type is empty, it will be set to the default value "incident".
+func (c *Config) SetNotificationType(notificationType string) {
+	if notificationType == "" {
+		notificationType = DefaultNotificationType
+	}
+
+	c.NotificationType = notificationType
+}