docs: reorder & testing

backend/push/service.go

@@ -19,7 +19,6 @@ package push
 
 import (
 	"context"
-	"encoding/json"
 	"errors"
 	"fmt"
 	"strings"
@@ -131,23 +130,30 @@ func (s *Service) Close() {
 	}
 }
 
-// PublishClientEvent enqueues a ClientEvent for delivery. payload is
-// marshalled to JSON; deviceSessionID is optional. eventID, requestID
-// and traceID are correlation identifiers that gateway forwards
-// verbatim into the signed client envelope (typically the producing
-// route id, the originating client request id, and the trace id of the
-// span that produced the event); empty strings are forwarded
-// unchanged. The method satisfies notification.PushPublisher.
-func (s *Service) PublishClientEvent(_ context.Context, userID uuid.UUID, deviceSessionID *uuid.UUID, kind string, payload map[string]any, eventID, requestID, traceID string) error {
+// PublishClientEvent enqueues a ClientEvent for delivery. The typed
+// `event` carries both the catalog kind and the payload bytes;
+// push.Service invokes event.Marshal() at publish time so producers
+// stay decoupled from the wire encoding. deviceSessionID is optional.
+// eventID, requestID and traceID are correlation identifiers that
+// gateway forwards verbatim into the signed client envelope (typically
+// the producing route id, the originating client request id, and the
+// trace id of the span that produced the event); empty strings are
+// forwarded unchanged. The method satisfies
+// notification.PushPublisher.
+func (s *Service) PublishClientEvent(_ context.Context, userID uuid.UUID, deviceSessionID *uuid.UUID, event Event, eventID, requestID, traceID string) error {
+	if event == nil {
+		return errors.New("push.PublishClientEvent: event is required")
+	}
 	if userID == uuid.Nil {
 		return errors.New("push.PublishClientEvent: userID is required")
 	}
+	kind := event.Kind()
 	if strings.TrimSpace(kind) == "" {
-		return errors.New("push.PublishClientEvent: kind is required")
+		return errors.New("push.PublishClientEvent: event kind is required")
 	}
-	encoded, err := json.Marshal(payload)
+	encoded, err := event.Marshal()
 	if err != nil {
-		return fmt.Errorf("push.PublishClientEvent: marshal payload: %w", err)
+		return fmt.Errorf("push.PublishClientEvent: marshal event: %w", err)
 	}
 	ev := &pushv1.PushEvent{
 		Kind: &pushv1.PushEvent_ClientEvent{