diff --git a/engine/vibes_auth/docs/drf/messaging.py b/engine/vibes_auth/docs/drf/messaging.py index 30d99ae1..6898b062 100644 --- a/engine/vibes_auth/docs/drf/messaging.py +++ b/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", - "description": "some_method_description", - "request": PingPongSerializer, - "responses": PingPongSerializer, + "summary": _("User messages entrypoint"), + "description": _("Anonymous or authenticated non-staff users send messages. Also supports action=ping."), + "request": UserMessageRequestSerializer, + "responses": UserMessageResponseSerializer, } STAFF_INBOX_CONSUMER_SCHEMA = { @@ -18,9 +24,10 @@ STAFF_INBOX_CONSUMER_SCHEMA = { "messaging", ], "type": "send", - "summary": "some_method_summary", - "description": "some_method_description", - "responses": OkSerializer, + "summary": _("Staff inbox control"), + "description": _("Staff-only actions: list_open, assign, reply, close, ping. Unified event payloads are emitted."), + "request": StaffInboxEventSerializer, + "responses": StaffInboxEventSerializer, } THREAD_CONSUMER_SCHEMA = { @@ -28,8 +35,9 @@ THREAD_CONSUMER_SCHEMA = { "messaging", ], "type": "send", - "summary": "some_method_summary", - "description": "some_method_description", + "summary": _("Per-thread staff channel"), + "description": _("Reply, close, and ping within a specific thread."), "parameters": [OpenApiParameter(name="thread_id")], - "responses": ThreadSerializer, + "request": ThreadReplyRequestSerializer, + "responses": ThreadOkResponseSerializer, } diff --git a/engine/vibes_auth/messaging/serializers.py b/engine/vibes_auth/messaging/serializers.py index dcbf928a..ac2c9384 100644 --- a/engine/vibes_auth/messaging/serializers.py +++ b/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)