feat: support custom notifications (#19751)

## Description

Adds support for sending an ad‑hoc custom notification to the
authenticated user via API and CLI. This is useful for surfacing the
result of scripts or long‑running tasks. Notifications are delivered
through the configured method and the dashboard Inbox, respecting
existing preferences and delivery settings.

## Changes

* New notification template: “Custom Notification” with a label for a
custom title and a custom message.
* New API endpoint: `POST /api/v2/notifications/custom` to send a custom
notification to the requesting user.
* New API endpoint: `GET /notifications/templates/custom` to get custom
notification template.
* New CLI subcommand: `coder notifications custom <title> <message>` to
send a custom notification to the requesting user.
* Documentation updates: Add a “Custom notifications” section under
Administration > Monitoring > Notifications, including instructions on
sending custom notifications and examples of when to use them.

Closes: https://github.com/coder/coder/issues/19611

codersdk/notifications.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"strings"
 	"time"
 
 	"github.com/google/uuid"
@@ -280,3 +281,53 @@ func (c *Client) PostTestWebpushMessage(ctx context.Context) error {
 	}
 	return nil
 }
+
+type CustomNotificationContent struct {
+	Title   string `json:"title"`
+	Message string `json:"message"`
+}
+
+type CustomNotificationRequest struct {
+	Content *CustomNotificationContent `json:"content"`
+	// TODO(ssncferreira): Add target (user_ids, roles) to support multi-user and role-based delivery.
+	//   See: https://github.com/coder/coder/issues/19768
+}
+
+const (
+	maxCustomNotificationTitleLen   = 120
+	maxCustomNotificationMessageLen = 2000
+)
+
+func (c CustomNotificationRequest) Validate() error {
+	if c.Content == nil {
+		return xerrors.Errorf("content is required")
+	}
+	return c.Content.Validate()
+}
+
+func (c CustomNotificationContent) Validate() error {
+	if strings.TrimSpace(c.Title) == "" ||
+		strings.TrimSpace(c.Message) == "" {
+		return xerrors.Errorf("provide a non-empty 'content.title' and 'content.message'")
+	}
+	if len(c.Title) > maxCustomNotificationTitleLen {
+		return xerrors.Errorf("'content.title' must be less than %d characters", maxCustomNotificationTitleLen)
+	}
+	if len(c.Message) > maxCustomNotificationMessageLen {
+		return xerrors.Errorf("'content.message' must be less than %d characters", maxCustomNotificationMessageLen)
+	}
+	return nil
+}
+
+func (c *Client) PostCustomNotification(ctx context.Context, req CustomNotificationRequest) error {
+	res, err := c.Request(ctx, http.MethodPost, "/api/v2/notifications/custom", req)
+	if err != nil {
+		return err
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusNoContent {
+		return ReadBodyAsError(res)
+	}
+	return nil
+}