feat(api): notifications inbox and per-user settings endpoints (#5339)

M489 step 2.

- GET /api/me/notifications?limit&before: newest first, keyset-paged on
  (created_at, id) with an opaque cursor, plus the unread count.
- GET /api/me/notifications/unread-count: the badge's cheap call.
- POST /api/me/notifications/{id}/read and /read-all. Mark-read is
  idempotent; another user's id is a 404, the same as a malformed one.
- GET/PUT /api/me/notification-settings: every kind the caller can receive
  (admin kinds only for admins) with inbox/phone/email. PUT is partial, so an
  offline replay sends only what was touched, and a batch with any invalid
  change applies nothing. The response says whether email can be delivered
  at all: no address on file, or SMTP not configured. A failed SMTP config
  read is a 500, not "not configured".

notifications.Render turns kind + payload into title, body and link on the
server, so the web inbox, the Android inbox, the phone's shade and the email
digest all say the same thing. mailer.Configured lifts Send's readiness
check out so settings can report it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/notifications/render.go

@@ -0,0 +1,134 @@
+package notifications
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// Rendered is a notification as people read it. The server renders it once,
+// so the web inbox, the Android inbox, the phone's shade and the email digest
+// all say the same thing, and a wording change is one edit here rather than
+// a phrase table per client.
+type Rendered struct {
+	Title string `json:"title"`
+	Body  string `json:"body"`
+	// Link is the web path the notification opens. Android maps the same
+	// paths onto its screens.
+	Link string `json:"link"`
+}
+
+// Payload is what producers put in a notification. Every field is optional;
+// each kind documents the ones it uses in Render.
+type Payload struct {
+	RequestID   string `json:"request_id,omitempty"`
+	RequestKind string `json:"request_kind,omitempty"` // artist | album | track
+	// Name is what was requested or flagged, as the user would say it:
+	// "WWW", "Moe Shop", "Moe Shop – WWW".
+	Name     string `json:"name,omitempty"`
+	ArtistID string `json:"artist_id,omitempty"`
+	AlbumID  string `json:"album_id,omitempty"`
+	// Actor is the other person involved: who asked, who flagged.
+	Actor  string `json:"actor,omitempty"`
+	Reason string `json:"reason,omitempty"`
+	// Count is the coalesced kinds' running total.
+	Count int64 `json:"count,omitempty"`
+	// Detail is free text for scan_failed (the error message).
+	Detail string `json:"detail,omitempty"`
+}
+
+// Map turns a Payload into the map Notify takes, dropping empty fields.
+func (p Payload) Map() map[string]any {
+	b, _ := json.Marshal(p)
+	var m map[string]any
+	_ = json.Unmarshal(b, &m)
+	return m
+}
+
+// Render turns a stored row into what people read. An unreadable payload
+// still renders, from the kind alone, rather than failing the whole inbox.
+func Render(kind Kind, payload []byte) Rendered {
+	var p Payload
+	_ = json.Unmarshal(payload, &p)
+	name := p.Name
+	if name == "" {
+		name = "Your request"
+	}
+
+	switch kind {
+	case KindRequestApproved:
+		return Rendered{Title: "Request approved", Body: name + " is on its way.", Link: "/requests"}
+	case KindRequestRejected:
+		body := name + " was declined."
+		if p.Reason != "" {
+			body = name + " was declined: " + p.Reason
+		}
+		return Rendered{Title: "Request declined", Body: body, Link: "/requests"}
+	case KindRequestCompleted:
+		link := "/requests"
+		switch {
+		case p.AlbumID != "":
+			link = "/albums/" + p.AlbumID
+		case p.ArtistID != "":
+			link = "/artists/" + p.ArtistID
+		}
+		return Rendered{Title: "Now in your library", Body: name + " has arrived.", Link: link}
+	case KindRequestPending:
+		who := p.Actor
+		if who == "" {
+			who = "Someone"
+		}
+		return Rendered{Title: "Request to review", Body: who + " asked for " + name + ".", Link: "/admin/requests"}
+	case KindQuarantineFlagged:
+		who := p.Actor
+		if who == "" {
+			who = "Someone"
+		}
+		body := who + " flagged " + name + "."
+		if p.Reason != "" {
+			body = who + " flagged " + name + ": " + p.Reason
+		}
+		return Rendered{Title: "Track flagged", Body: body, Link: "/admin/quarantine"}
+	case KindScanFailed:
+		title := "Library scan failed"
+		if p.Count > 1 {
+			title = fmt.Sprintf("Library scan failed %d times", p.Count)
+		}
+		body := p.Detail
+		if body == "" {
+			body = "The last scan stopped with an error."
+		}
+		return Rendered{Title: title, Body: body, Link: "/admin"}
+	case KindTracksMissing:
+		return Rendered{
+			Title: plural(p.Count, "track went missing", "tracks went missing"),
+			Body:  "Their files are no longer where the library expects them.",
+			Link:  "/admin/missing-files",
+		}
+	case KindDuplicatesFound:
+		return Rendered{
+			Title: plural(p.Count, "duplicate group to review", "duplicate groups to review"),
+			Body:  "The duplicate sweep found tracks holding the same recording.",
+			Link:  "/admin/duplicates",
+		}
+	case KindPlaybackErrors:
+		return Rendered{
+			Title: plural(p.Count, "playback error reported", "playback errors reported"),
+			Body:  "A track failed to play for someone.",
+			Link:  "/admin/playback-errors",
+		}
+	default:
+		return Rendered{Title: "Notification", Link: "/"}
+	}
+}
+
+func plural(n int64, one, many string) string {
+	if n == 1 {
+		return "1 " + one
+	}
+	if n < 1 {
+		// A coalesced kind always carries a count; this only guards a
+		// malformed row from reading "0 tracks went missing".
+		return "Some " + many
+	}
+	return fmt.Sprintf("%d %s", n, many)
+}

internal/notifications/render_test.go

@@ -0,0 +1,56 @@
+package notifications
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// render stores p the way Notify does (through Map) and reads it back.
+func render(k Kind, p Payload) Rendered {
+	b, err := json.Marshal(p.Map())
+	if err != nil {
+		panic(err)
+	}
+	return Render(k, b)
+}
+
+func TestRender_EveryKindHasATitleAndALink(t *testing.T) {
+	for _, k := range Kinds() {
+		r := Render(k, []byte(`{}`))
+		require.NotEmpty(t, r.Title, k)
+		require.NotEqual(t, "Notification", r.Title, "%s falls through to the default", k)
+		require.NotEmpty(t, r.Link, k)
+	}
+}
+
+func TestRender_RequestCompletedLinksToWhatArrived(t *testing.T) {
+	require.Equal(t, "/albums/al-1", render(KindRequestCompleted, Payload{Name: "WWW", AlbumID: "al-1", ArtistID: "ar-1"}).Link)
+	require.Equal(t, "/artists/ar-1", render(KindRequestCompleted, Payload{Name: "Moe Shop", ArtistID: "ar-1"}).Link)
+	require.Equal(t, "/requests", render(KindRequestCompleted, Payload{Name: "WWW"}).Link)
+	require.Equal(t, "WWW has arrived.", render(KindRequestCompleted, Payload{Name: "WWW"}).Body)
+}
+
+func TestRender_RejectionCarriesTheReasonWhenThereIsOne(t *testing.T) {
+	require.Equal(t, "WWW was declined.", render(KindRequestRejected, Payload{Name: "WWW"}).Body)
+	require.Equal(t, "WWW was declined: already owned", render(KindRequestRejected, Payload{Name: "WWW", Reason: "already owned"}).Body)
+}
+
+func TestRender_CoalescedCountsReadNaturally(t *testing.T) {
+	require.Equal(t, "1 track went missing", render(KindTracksMissing, Payload{Count: 1}).Title)
+	require.Equal(t, "14 tracks went missing", render(KindTracksMissing, Payload{Count: 14}).Title)
+	require.Equal(t, "Library scan failed", render(KindScanFailed, Payload{Count: 1, Detail: "x"}).Title)
+	require.Equal(t, "Library scan failed 3 times", render(KindScanFailed, Payload{Count: 3}).Title)
+	require.Equal(t, "Some tracks went missing", Render(KindTracksMissing, []byte(`{}`)).Title)
+}
+
+func TestRender_AnUnreadablePayloadStillRenders(t *testing.T) {
+	r := Render(KindRequestApproved, []byte(`not json`))
+	require.Equal(t, "Request approved", r.Title)
+	require.Equal(t, "Your request is on its way.", r.Body)
+}
+
+func TestPayloadMap_DropsEmptyFields(t *testing.T) {
+	require.Equal(t, map[string]any{"name": "WWW", "count": float64(2)}, Payload{Name: "WWW", Count: 2}.Map())
+}

internal/notifications/settings.go

@@ -0,0 +1,102 @@
+package notifications
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// KindSetting is one row of a user's notification settings.
+type KindSetting struct {
+	Kind      Kind `json:"kind"`
+	AdminOnly bool `json:"admin_only"`
+	Inbox     bool `json:"inbox"`
+	Phone     bool `json:"phone"`
+	Email     bool `json:"email"`
+}
+
+// SettingChange changes one kind. A nil field is left as it is, so a client
+// replaying a queued toggle offline sends only what the user touched.
+type SettingChange struct {
+	Kind  Kind  `json:"kind"`
+	Inbox *bool `json:"inbox,omitempty"`
+	Phone *bool `json:"phone,omitempty"`
+	Email *bool `json:"email,omitempty"`
+}
+
+// ErrSettingInvalid is a change naming an unknown kind, or an admin kind for
+// a user who is not an admin.
+var ErrSettingInvalid = errors.New("notification setting invalid")
+
+// LoadSettings returns every kind the user can receive, in display order,
+// with their stored channels or the kind's defaults. Admin kinds are listed
+// only for admins.
+//
+// The stored values are returned as set, not as Effective: a user who turns
+// the inbox off and on again gets back the phone and email choices they had.
+func LoadSettings(ctx context.Context, q *dbq.Queries, userID pgtype.UUID, isAdmin bool) ([]KindSetting, error) {
+	rows, err := q.ListNotificationPrefsForUser(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("notifications: load settings: %w", err)
+	}
+	stored := make(map[Kind]Channels, len(rows))
+	for _, r := range rows {
+		stored[Kind(r.Kind)] = Channels{Inbox: r.Inbox, Phone: r.Phone, Email: r.Email}
+	}
+	out := make([]KindSetting, 0, len(order))
+	for _, k := range order {
+		if k.AdminOnly() && !isAdmin {
+			continue
+		}
+		c, ok := stored[k]
+		if !ok {
+			c = k.Defaults()
+		}
+		out = append(out, KindSetting{Kind: k, AdminOnly: k.AdminOnly(), Inbox: c.Inbox, Phone: c.Phone, Email: c.Email})
+	}
+	return out, nil
+}
+
+// SaveSettings applies changes and returns the settings as they now stand.
+// The whole batch is validated before anything is written.
+func SaveSettings(ctx context.Context, q *dbq.Queries, userID pgtype.UUID, isAdmin bool, changes []SettingChange) ([]KindSetting, error) {
+	for _, c := range changes {
+		if !c.Kind.Valid() {
+			return nil, fmt.Errorf("%w: unknown kind %q", ErrSettingInvalid, c.Kind)
+		}
+		if c.Kind.AdminOnly() && !isAdmin {
+			return nil, fmt.Errorf("%w: %s is for admins", ErrSettingInvalid, c.Kind)
+		}
+	}
+	current, err := LoadSettings(ctx, q, userID, isAdmin)
+	if err != nil {
+		return nil, err
+	}
+	byKind := make(map[Kind]KindSetting, len(current))
+	for _, s := range current {
+		byKind[s.Kind] = s
+	}
+	for _, c := range changes {
+		s := byKind[c.Kind]
+		if c.Inbox != nil {
+			s.Inbox = *c.Inbox
+		}
+		if c.Phone != nil {
+			s.Phone = *c.Phone
+		}
+		if c.Email != nil {
+			s.Email = *c.Email
+		}
+		byKind[c.Kind] = s
+		if err := q.UpsertNotificationPref(ctx, dbq.UpsertNotificationPrefParams{
+			UserID: userID, Kind: string(c.Kind), Inbox: s.Inbox, Phone: s.Phone, Email: s.Email,
+		}); err != nil {
+			return nil, fmt.Errorf("notifications: save %s: %w", c.Kind, err)
+		}
+	}
+	return LoadSettings(ctx, q, userID, isAdmin)
+}