Features: 1) Add detailed serializers for user messages, staff inbox, and thread consumers; 2) Update schema definitions to support new serializers with improved descriptions and summaries; 3) Introduce flexible event-based serializer for staff inbox actions.

Fixes: 1) Replace generic serializers with context-specific implementations in schema definitions.

Extra: 1) Minor code cleanup and reorganization for improved readability and maintainability; 2) Add comments for new serializers.

engine/vibes_auth/docs/drf/messaging.py

@@ -1,16 +1,22 @@
 from drf_spectacular.utils import OpenApiParameter
 
-from engine.vibes_auth.messaging.serializers import OkSerializer, PingPongSerializer, ThreadSerializer
+from engine.vibes_auth.messaging.serializers import (
+    StaffInboxEventSerializer,
+    ThreadOkResponseSerializer,
+    ThreadReplyRequestSerializer,
+    UserMessageRequestSerializer,
+    UserMessageResponseSerializer,
+)
 
 USER_MESSAGE_CONSUMER_SCHEMA = {
     "tags": [
         "messaging",
     ],
     "type": "send",
-    "summary": "some_method_summary",
+    "summary": _("User messages entrypoint"),
-    "description": "some_method_description",
+    "description": _("Anonymous or authenticated non-staff users send messages. Also supports action=ping."),
-    "request": PingPongSerializer,
+    "request": UserMessageRequestSerializer,
-    "responses": PingPongSerializer,
+    "responses": UserMessageResponseSerializer,
 }
 
 STAFF_INBOX_CONSUMER_SCHEMA = {
@@ -18,9 +24,10 @@ STAFF_INBOX_CONSUMER_SCHEMA = {
         "messaging",
     ],
     "type": "send",
-    "summary": "some_method_summary",
+    "summary": _("Staff inbox control"),
-    "description": "some_method_description",
+    "description": _("Staff-only actions: list_open, assign, reply, close, ping. Unified event payloads are emitted."),
-    "responses": OkSerializer,
+    "request": StaffInboxEventSerializer,
+    "responses": StaffInboxEventSerializer,
 }
 
 THREAD_CONSUMER_SCHEMA = {
@@ -28,8 +35,9 @@ THREAD_CONSUMER_SCHEMA = {
         "messaging",
     ],
     "type": "send",
-    "summary": "some_method_summary",
+    "summary": _("Per-thread staff channel"),
-    "description": "some_method_description",
+    "description": _("Reply, close, and ping within a specific thread."),
     "parameters": [OpenApiParameter(name="thread_id")],
-    "responses": ThreadSerializer,
+    "request": ThreadReplyRequestSerializer,
+    "responses": ThreadOkResponseSerializer,
 }

engine/vibes_auth/messaging/serializers.py

@@ -1,15 +1,112 @@
-from rest_framework.fields import CharField, BooleanField
+from rest_framework.fields import CharField, BooleanField, IntegerField, ListField
 from rest_framework.serializers import Serializer
 
 
-class PingPongSerializer(Serializer):
+# Generic/common serializers
+class ErrorResponseSerializer(Serializer):
+    error = CharField(required=True)
+    detail = CharField(required=False)
+
+
+class PongResponseSerializer(Serializer):
+    type = CharField(required=True)
+
+
+# User message consumer
+class UserMessageRequestSerializer(Serializer):
     text = CharField(required=True)
 
 
-class OkSerializer(Serializer):
+class UserMessageResponseSerializer(Serializer):
     ok = BooleanField(required=True)
+    thread_id = CharField(required=True)
+    message_id = CharField(required=True)
 
 
-class ThreadSerializer(Serializer):
+# Staff inbox consumer
+class InboxThreadItemSerializer(Serializer):
+    uuid = CharField(required=True)
+    user_id = IntegerField(required=False, allow_null=True)
+    email = CharField(required=True)
+    assigned_to_id = IntegerField(required=False, allow_null=True)
+    last_message_at = CharField(required=True)
+
+
+class StaffInboxListResponseSerializer(Serializer):
+    type = CharField(required=True)
+    threads = ListField(child=InboxThreadItemSerializer())
+
+
+class StaffAssignRequestSerializer(Serializer):
+    action = CharField(required=True)
+    thread_id = CharField(required=True)
+
+
+class StaffAssignResponseSerializer(Serializer):
+    type = CharField(required=True)
+    thread_id = CharField(required=True)
+    user = CharField(required=True)
+
+
+class StaffReplyRequestSerializer(Serializer):
+    action = CharField(required=True)
+    thread_id = CharField(required=True)
+    text = CharField(required=True)
+
+
+class StaffReplyResponseSerializer(Serializer):
+    type = CharField(required=True)
+    message_id = CharField(required=True)
+
+
+class StaffCloseRequestSerializer(Serializer):
+    action = CharField(required=True)
+    thread_id = CharField(required=True)
+
+
+class StaffCloseResponseSerializer(Serializer):
+    type = CharField(required=True)
+    thread_id = CharField(required=True)
+
+
+class StaffInboxEventSerializer(Serializer):
+    """A flexible event serializer for staff inbox messages over WS."""
+
+    type = CharField(required=True)
+    # Optional fields depending on event type
+    threads = ListField(child=InboxThreadItemSerializer(), required=False)
+    thread_id = CharField(required=False)
+    user = CharField(required=False)
+    message_id = CharField(required=False)
+    error = CharField(required=False)
+    detail = CharField(required=False)
+
+
+# Thread consumer
+class ThreadReplyRequestSerializer(Serializer):
+    action = CharField(required=True)
+    text = CharField(required=True)
+
+
+class ThreadReplyResponseSerializer(Serializer):
+    type = CharField(required=True)
+    message_id = CharField(required=True)
+
+
+class ThreadCloseRequestSerializer(Serializer):
+    action = CharField(required=True)
+
+
+class ThreadCloseResponseSerializer(Serializer):
+    type = CharField(required=True)
+    thread_id = CharField(required=True)
+
+
+class ThreadOkResponseSerializer(Serializer):
     thread = CharField(required=True)
     ok = BooleanField(required=True)
+
+
+class ThreadPongResponseSerializer(Serializer):
+    type = CharField(required=True)
+    thread = CharField(required=True)