feat(system-notifications): warn when system notifications have no recipient device (#7)

Notifications were silently dropped when the admin had no paired device
on the topic and TotalSent was zero without raising any error

The server now logs a warning when a system notification reaches zero
devices so the misconfiguration is visible in logs

The admin UI also shows a warning when the configured recipient has no
active device on the chosen topic so the issue is caught at setup time
instead of through missing events later

Save remains enabled intentionally so admins can enable notifications
now and pair a device right after without being blocked

Author: lucor

cmd/beebuzz-server/adapter.go

@@ -154,6 +154,26 @@ func (a *systemNotificationTopicProviderAdapter) GetTopicByID(ctx context.Contex
 
 var _ systemnotifications.TopicProvider = (*systemNotificationTopicProviderAdapter)(nil)
 
+// systemNotificationDeviceSubscriptionAdapter adapts device.Service to the
+// system notifications device subscription checker. It is used by the admin
+// settings response to flag the misconfiguration where notifications are
+// enabled but the recipient has no paired device on the chosen topic.
+type systemNotificationDeviceSubscriptionAdapter struct {
+	deviceSvc *device.Service
+}
+
+// HasActiveDeviceForTopic reports whether the user has at least one paired
+// device subscribed to topicName.
+func (a *systemNotificationDeviceSubscriptionAdapter) HasActiveDeviceForTopic(ctx context.Context, userID, topicName string) (bool, error) {
+	subs, err := a.deviceSvc.GetSubscribedDevices(ctx, userID, topicName)
+	if err != nil {
+		return false, err
+	}
+	return len(subs) > 0, nil
+}
+
+var _ systemnotifications.DeviceSubscriptionChecker = (*systemNotificationDeviceSubscriptionAdapter)(nil)
+
 // pushAuthorizerAdapter adapts token.Service to notification.PushAuthorizer.
 type pushAuthorizerAdapter struct {
 	tokenSvc *token.Service
@@ -242,15 +262,30 @@ type systemNotificationDeliveryAdapter struct {
 }
 
 // SendSystemNotification sends a server-trusted notification generated by BeeBuzz itself.
+//
+// A zero TotalSent is logged at warn level: the call succeeded but no paired
+// device on the configured topic received the push, which usually means the
+// admin enabled system notifications without pairing a device on that topic.
+// Without this signal the misconfiguration is silent in production.
 func (a *systemNotificationDeliveryAdapter) SendSystemNotification(ctx context.Context, input systemnotifications.DeliveryInput) error {
-	_, err := a.notifSvc.Send(ctx, input.RecipientUserID, input.TopicID, notification.SendInput{
+	report, err := a.notifSvc.Send(ctx, input.RecipientUserID, input.TopicID, notification.SendInput{
 		TopicName:    input.TopicName,
 		Title:        input.Title,
 		Body:         input.Body,
 		Source:       event.SourceInternal,
 		DeliveryMode: notification.DeliveryModeServerTrusted,
 	}, a.log)
-	return err
+	if err != nil {
+		return err
+	}
+	if report != nil && report.TotalSent == 0 {
+		a.log.Warn("system notification delivered to zero devices",
+			"recipient_user_id", input.RecipientUserID,
+			"topic_id", input.TopicID,
+			"topic", input.TopicName,
+		)
+	}
+	return nil
 }
 
 var _ systemnotifications.Delivery = (*systemNotificationDeliveryAdapter)(nil)

cmd/beebuzz-server/serve.go

@@ -174,7 +174,8 @@ func buildServices(db *sqlx.DB, cfg *config.Config, log *slog.Logger, m mailer.M
 	systemNotifRepo := systemnotifications.NewRepository(db)
 	systemNotifTopics := &systemNotificationTopicProviderAdapter{topicSvc: topicSvc}
 	systemNotifDelivery := &systemNotificationDeliveryAdapter{notifSvc: notifSvc, log: log}
-	systemNotifSvc := systemnotifications.NewService(systemNotifRepo, systemNotifTopics, systemNotifDelivery, log)
+	systemNotifSubscriptions := &systemNotificationDeviceSubscriptionAdapter{deviceSvc: deviceSvc}
+	systemNotifSvc := systemnotifications.NewService(systemNotifRepo, systemNotifTopics, systemNotifDelivery, systemNotifSubscriptions, log)
 	authSvc.SetSignupNotifier(systemNotifSvc)
 
 	webhookRepo := webhook.NewRepository(db)

docs/openapi.yaml

@@ -2219,7 +2219,7 @@ components:
             $ref: "#/components/schemas/AdminUserResponse"
     SystemNotificationSettingsResponse:
       type: object
-      required: [enabled, signup_created_enabled]
+      required: [enabled, signup_created_enabled, recipient_has_active_device_for_topic]
       properties:
         enabled:
           type: boolean
@@ -2229,6 +2229,13 @@ components:
           type: string
         signup_created_enabled:
           type: boolean
+        recipient_has_active_device_for_topic:
+          type: boolean
+          description: |
+            Best-effort flag computed at read time. True when the recipient
+            admin has at least one paired device subscribed to the configured
+            topic. Used by the admin UI to warn about a misconfiguration that
+            would silently drop deliveries.
         created_at:
           type: string
           format: date-time

internal/system/notifications/service.go

@@ -12,25 +12,33 @@ const signupCreatedTitle = "New BeeBuzz signup"
 
 // Service owns system notification policy and dispatch decisions.
 type Service struct {
-	repo     *Repository
-	topics   TopicProvider
-	delivery Delivery
-	log      *slog.Logger
+	repo          *Repository
+	topics        TopicProvider
+	delivery      Delivery
+	subscriptions DeviceSubscriptionChecker
+	log           *slog.Logger
 }
 
 // NewService creates a system notifications service.
-func NewService(repo *Repository, topics TopicProvider, delivery Delivery, log *slog.Logger) *Service {
+func NewService(repo *Repository, topics TopicProvider, delivery Delivery, subscriptions DeviceSubscriptionChecker, log *slog.Logger) *Service {
 	return &Service{
-		repo:     repo,
-		topics:   topics,
-		delivery: delivery,
-		log:      log,
+		repo:          repo,
+		topics:        topics,
+		delivery:      delivery,
+		subscriptions: subscriptions,
+		log:           log,
 	}
 }
 
-// GetSettings returns the current singleton settings.
+// GetSettings returns the current singleton settings, enriched with the
+// best-effort RecipientHasActiveDeviceForTopic flag for the admin UI.
 func (s *Service) GetSettings(ctx context.Context) (*Settings, error) {
-	return s.repo.GetSettings(ctx)
+	settings, err := s.repo.GetSettings(ctx)
+	if err != nil {
+		return nil, err
+	}
+	s.fillRecipientDeviceFlag(ctx, settings)
+	return settings, nil
 }
 
 // UpdateSettings validates and stores settings for the current admin user.
@@ -49,12 +57,46 @@ func (s *Service) UpdateSettings(ctx context.Context, adminUserID string, input
 		}
 	}
 
-	return s.repo.UpsertSettings(ctx, Settings{
+	settings, err := s.repo.UpsertSettings(ctx, Settings{
 		Enabled:              input.Enabled,
 		RecipientUserID:      adminUserID,
 		TopicID:              input.TopicID,
 		SignupCreatedEnabled: input.SignupCreatedEnabled,
 	})
+	if err != nil {
+		return nil, err
+	}
+	s.fillRecipientDeviceFlag(ctx, settings)
+	return settings, nil
+}
+
+// fillRecipientDeviceFlag sets RecipientHasActiveDeviceForTopic on the given
+// settings. The check is skipped (flag stays false) when there is no topic
+// configured. Lookup failures are logged but not propagated: this flag is a
+// UI hint, never a gate.
+func (s *Service) fillRecipientDeviceFlag(ctx context.Context, settings *Settings) {
+	if settings == nil || s.subscriptions == nil {
+		return
+	}
+	if settings.RecipientUserID == "" || settings.TopicID == "" {
+		return
+	}
+
+	topic, err := s.topics.GetTopicByID(ctx, settings.RecipientUserID, settings.TopicID)
+	if err != nil {
+		s.log.Warn("failed to resolve topic for system notification device check", "error", err)
+		return
+	}
+	if topic == nil {
+		return
+	}
+
+	hasDevice, err := s.subscriptions.HasActiveDeviceForTopic(ctx, settings.RecipientUserID, topic.Name)
+	if err != nil {
+		s.log.Warn("failed to check active device for system notification topic", "error", err)
+		return
+	}
+	settings.RecipientHasActiveDeviceForTopic = hasDevice
 }
 
 // NotifySignupCreated sends the configured notification for a newly created account.

internal/system/notifications/service_test.go

@@ -21,15 +21,29 @@ func (p *testTopicProvider) GetTopicByID(ctx context.Context, userID, topicID st
 	return &Topic{ID: t.ID, UserID: t.UserID, Name: t.Name}, nil
 }
 
+type testDeviceSubscriptions struct {
+	withDevice map[string]bool // key: userID + "|" + topicName
+}
+
+func (c *testDeviceSubscriptions) HasActiveDeviceForTopic(_ context.Context, userID, topicName string) (bool, error) {
+	return c.withDevice[userID+"|"+topicName], nil
+}
+
 func newTestService(t *testing.T) (*Service, *topic.Service, context.Context) {
 	t.Helper()
+	return newTestServiceWith(t, nil)
+}
+
+func newTestServiceWith(t *testing.T, subs DeviceSubscriptionChecker) (*Service, *topic.Service, context.Context) {
+	t.Helper()
 
 	db := testutil.NewDBWithUsers(t, "admin-1", "other-1")
 	topicSvc := topic.NewService(topic.NewRepository(db), slog.Default())
 	svc := NewService(
 		NewRepository(db),
 		&testTopicProvider{svc: topicSvc},
 		nil,
+		subs,
 		slog.Default(),
 	)
 
@@ -99,3 +113,38 @@ func TestUpdateSettingsRequiresTopicWhenEnabled(t *testing.T) {
 		t.Fatalf("UpdateSettings() error = %v, want %v", err, ErrTopicRequired)
 	}
 }
+
+func TestGetSettingsReportsRecipientDevicePresence(t *testing.T) {
+	subs := &testDeviceSubscriptions{withDevice: map[string]bool{}}
+	svc, topicSvc, ctx := newTestServiceWith(t, subs)
+	topicRow, err := topicSvc.CreateTopic(ctx, "admin-1", "ops", "Operational alerts")
+	if err != nil {
+		t.Fatalf("CreateTopic() error = %v", err)
+	}
+	if _, err := svc.UpdateSettings(ctx, "admin-1", UpdateSettingsRequest{
+		Enabled:              true,
+		TopicID:              topicRow.ID,
+		SignupCreatedEnabled: true,
+	}); err != nil {
+		t.Fatalf("UpdateSettings() error = %v", err)
+	}
+
+	// Recipient has no paired device on the topic: flag must be false.
+	got, err := svc.GetSettings(ctx)
+	if err != nil {
+		t.Fatalf("GetSettings() error = %v", err)
+	}
+	if got.RecipientHasActiveDeviceForTopic {
+		t.Fatalf("RecipientHasActiveDeviceForTopic = true, want false when no device is paired")
+	}
+
+	// Once a device is registered for the recipient on that topic, the flag flips.
+	subs.withDevice["admin-1|ops"] = true
+	got, err = svc.GetSettings(ctx)
+	if err != nil {
+		t.Fatalf("GetSettings() error = %v", err)
+	}
+	if !got.RecipientHasActiveDeviceForTopic {
+		t.Fatalf("RecipientHasActiveDeviceForTopic = false, want true once a device is paired")
+	}
+}

internal/system/notifications/types.go

@@ -31,6 +31,14 @@ type Delivery interface {
 	SendSystemNotification(ctx context.Context, input DeliveryInput) error
 }
 
+// DeviceSubscriptionChecker reports whether a user has at least one active
+// paired device subscribed to the given topic. It is used to surface a
+// configuration warning when system notifications are enabled but would have
+// no destination at delivery time.
+type DeviceSubscriptionChecker interface {
+	HasActiveDeviceForTopic(ctx context.Context, userID, topicName string) (bool, error)
+}
+
 // DeliveryInput carries a resolved system notification delivery request.
 type DeliveryInput struct {
 	RecipientUserID string
@@ -41,23 +49,31 @@ type DeliveryInput struct {
 }
 
 // Settings is the persisted system notifications configuration.
+//
+// RecipientHasActiveDeviceForTopic is a derived (non-persisted) flag computed
+// at read time so the admin UI can warn when delivery would have no
+// destination. It is best-effort: callers may leave it false when the check
+// is not applicable or fails.
 type Settings struct {
 	Enabled              bool   `db:"enabled"`
 	RecipientUserID      string `db:"recipient_user_id"`
 	TopicID              string `db:"topic_id"`
 	SignupCreatedEnabled bool   `db:"signup_created_enabled"`
 	CreatedAt            int64  `db:"created_at"`
 	UpdatedAt            int64  `db:"updated_at"`
+
+	RecipientHasActiveDeviceForTopic bool `db:"-"`
 }
 
 // SettingsResponse is the admin API response for system notification settings.
 type SettingsResponse struct {
-	Enabled              bool      `json:"enabled"`
-	RecipientUserID      string    `json:"recipient_user_id,omitempty"`
-	TopicID              string    `json:"topic_id,omitempty"`
-	SignupCreatedEnabled bool      `json:"signup_created_enabled"`
-	CreatedAt            time.Time `json:"created_at,omitempty"`
-	UpdatedAt            time.Time `json:"updated_at,omitempty"`
+	Enabled                          bool      `json:"enabled"`
+	RecipientUserID                  string    `json:"recipient_user_id,omitempty"`
+	TopicID                          string    `json:"topic_id,omitempty"`
+	SignupCreatedEnabled             bool      `json:"signup_created_enabled"`
+	RecipientHasActiveDeviceForTopic bool      `json:"recipient_has_active_device_for_topic"`
+	CreatedAt                        time.Time `json:"created_at,omitempty"`
+	UpdatedAt                        time.Time `json:"updated_at,omitempty"`
 }
 
 // UpdateSettingsRequest is the admin API request for system notification settings.
@@ -74,12 +90,13 @@ func ToSettingsResponse(settings *Settings) SettingsResponse {
 	}
 
 	return SettingsResponse{
-		Enabled:              settings.Enabled,
-		RecipientUserID:      settings.RecipientUserID,
-		TopicID:              settings.TopicID,
-		SignupCreatedEnabled: settings.SignupCreatedEnabled,
-		CreatedAt:            time.UnixMilli(settings.CreatedAt).UTC(),
-		UpdatedAt:            time.UnixMilli(settings.UpdatedAt).UTC(),
+		Enabled:                          settings.Enabled,
+		RecipientUserID:                  settings.RecipientUserID,
+		TopicID:                          settings.TopicID,
+		SignupCreatedEnabled:             settings.SignupCreatedEnabled,
+		RecipientHasActiveDeviceForTopic: settings.RecipientHasActiveDeviceForTopic,
+		CreatedAt:                        time.UnixMilli(settings.CreatedAt).UTC(),
+		UpdatedAt:                        time.UnixMilli(settings.UpdatedAt).UTC(),
 	}
 }
 

web/apps/site/src/routes/(protected)/admin/system/notifications/+page.svelte

@@ -12,6 +12,12 @@
 	let signupCreatedEnabled = $state(false);
 	let selectedTopicID = $state('');
 	let recipientUserID = $state('');
+	let recipientHasActiveDeviceForTopic = $state(false);
+	// Tracks the topic the server actually computed the device flag against, so
+	// we only show the "no paired device" warning when the dropdown still
+	// matches the persisted selection.
+	let persistedTopicID = $state('');
+	let persistedEnabled = $state(false);
 
 	onMount(async () => {
 		await loadSettings();
@@ -30,6 +36,9 @@
 			signupCreatedEnabled = settings.signup_created_enabled;
 			selectedTopicID = settings.topic_id ?? '';
 			recipientUserID = settings.recipient_user_id ?? '';
+			recipientHasActiveDeviceForTopic = settings.recipient_has_active_device_for_topic;
+			persistedTopicID = settings.topic_id ?? '';
+			persistedEnabled = settings.enabled;
 		} catch (err) {
 			toast.error(
 				err instanceof ApiError ? err.userMessage : 'Failed to load system notifications'
@@ -53,6 +62,9 @@
 				signup_created_enabled: signupCreatedEnabled
 			});
 			recipientUserID = settings.recipient_user_id ?? '';
+			recipientHasActiveDeviceForTopic = settings.recipient_has_active_device_for_topic;
+			persistedTopicID = settings.topic_id ?? '';
+			persistedEnabled = settings.enabled;
 			toast.success('System notification settings saved');
 		} catch (err) {
 			toast.error(err instanceof ApiError ? err.userMessage : 'Failed to save settings');
@@ -143,6 +155,15 @@
 					</div>
 				{/if}
 
+				{#if persistedEnabled && persistedTopicID !== '' && persistedTopicID === selectedTopicID && !recipientHasActiveDeviceForTopic}
+					<div class="alert alert-warning">
+						<span>
+							No paired device is subscribed to this topic for the recipient admin. System
+							notifications will be silently dropped until a device is paired and subscribed.
+						</span>
+					</div>
+				{/if}
+
 				<div class="card-actions justify-end">
 					<button type="button" class="btn btn-primary" disabled={!canSave} onclick={saveSettings}>
 						{#if saving}

web/packages/shared/src/api/admin.ts

@@ -59,6 +59,13 @@ export interface SystemNotificationSettings {
 	recipient_user_id?: string;
 	topic_id?: string;
 	signup_created_enabled: boolean;
+	/**
+	 * Best-effort flag computed at read time: true when the recipient admin
+	 * has at least one paired device subscribed to the configured topic.
+	 * Used by the admin UI to warn about a misconfiguration that would
+	 * silently drop deliveries (TotalSent=0).
+	 */
+	recipient_has_active_device_for_topic: boolean;
 	created_at?: string;
 	updated_at?: string;
 }