# retoor <retoor@molodetz.nl>

from .._shared import endpoint, field

GROUP = {
        "slug": "messaging",
        "title": "Messaging",
        "intro": """
# Messaging

Direct messages between users. The inbox renders HTML; sending uses form fields. Look up
recipients with [Search & Lookups](/docs/lookups.html) and attach files via [Uploads](/docs/uploads.html).

Every endpoint follows the shared [Conventions & Errors](/docs/conventions.html) (auth, content
negotiation, pagination, status codes); see [Authentication](/docs/authentication.html) for the
four ways to sign requests.
""",
        "endpoints": [
            endpoint(
                id="messages-inbox",
                method="GET",
                path="/messages",
                title="Open the inbox",
                summary="Render conversations. Returns an HTML page.",
                auth="user",
                interactive=True,
                params=[
                    field(
                        "with_uid",
                        "query",
                        "string",
                        False,
                        "",
                        "Open a specific conversation by user UID.",
                    ),
                    field(
                        "search",
                        "query",
                        "string",
                        False,
                        "",
                        "Jump to a conversation by username.",
                    ),
                ],
            ),
            endpoint(
                id="messages-send",
                method="POST",
                path="/messages/send",
                title="Send a message",
                summary="Send a direct message to a user.",
                auth="user",
                encoding="form",
                destructive=True,
                params=[
                    field(
                        "content",
                        "form",
                        "textarea",
                        False,
                        "Hello there.",
                        "Body, 0-2000 characters. May be empty when at least one attachment is provided.",
                    ),
                    field(
                        "receiver_uid",
                        "form",
                        "string",
                        True,
                        "RECEIVER_UID",
                        "Recipient user UID.",
                    ),
                ],
            ),
            endpoint(
                id="messages-conversations",
                method="GET",
                path="/messages/conversations",
                title="List conversations",
                summary="Return the signed-in user's conversation list as JSON, for live refresh without a full page reload.",
                auth="user",
                interactive=False,
                sample_response={
                    "conversations": [
                        {
                            "other_user": {"uid": "8f14e45f-...", "username": "alice_test"},
                            "last_message": "Hello there.",
                            "last_message_at": "2026-07-21T10:00:00+00:00",
                            "unread": True,
                        }
                    ]
                },
            ),
            endpoint(
                id="messages-ws-ticket",
                method="POST",
                path="/messages/ws-ticket",
                title="Issue a WebSocket ticket",
                summary="Exchange the caller's session/API-key auth for a short-lived, single-use ticket that a browser WebSocket handshake can carry as a query parameter (a native WebSocket cannot set custom auth headers).",
                auth="user",
                encoding="none",
                interactive=False,
                notes=[
                    "The ticket is valid for 30 seconds and can be redeemed exactly once, as `wss://.../messages/ws?ticket=<ticket>`.",
                ],
                sample_response={"ticket": "3f9c2a...", "expires_in": 30},
            ),
        ],
}