from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True, slots=True)
class Route:
    """Immutable descriptor for a single API endpoint.

    Attributes:
        method: HTTP method (e.g. ``"GET"``, ``"POST"``).
        path: Relative or absolute endpoint path.
        doc: Optional human-readable description of the endpoint.
    """

    method: str
    path: str
    doc: str | None = None


class Health:
    """Endpoints for API health checks."""

    PING = Route(
        method="POST",
        path="ping",
        doc="Check if the API is responsive.",
    )


class Auth:
    """Endpoints for authentication (login, logout, password reset, etc.)."""

    LOGIN = Route(
        method="POST",
        path="account/login-in",
        doc="Login with username and password.",
    )
    LOGIN_TOURIST = Route(
        method="POST",
        path="account/login-in/tourist",
        doc="Login as a tourist (no credentials required, only device-id).",
    )
    LOGOUT = Route(
        method="POST",
        path="account/logout",
        doc="Logout from the current session.",
    )
    FORGOT_PASSWORD = Route(
        method="POST",
        path="account/forgot",
        doc="Send a message with password reset instructions to the email associated with the account.",
    )


class Account:
    """Endpoints for account management."""

    ME = Route(
        method="POST",
        path="account/my",
        doc="Get information about the current account.",
    )
    EDIT = Route(
        method="POST",
        path="account/base/edit",
        doc="Edit account information.",
    )
    SETTINGS = Route(
        method="POST",
        path="account/settings",
        doc="Edit account settings.",
    )
    PASSWORD = Route(
        method="POST",
        path="account/pwd/update",
        doc="Change account password.",
    )
    CANCEL = Route(
        method="POST",
        path="account/cancel",
        doc="Delete (cancel) the account.",
    )


class Images:
    """Endpoints for image generation, upscaling, upload, etc."""

    TEXT_TO_IMG = Route(
        method="POST",
        path="task/v2/text-to-img",
        doc="Create an image based on a text prompt.",
    )
    IMG_TO_IMG = Route(
        method="POST",
        path="task/v2/img-to-img",
        doc="Create a new image based on an existing one.",
    )
    IMG_TO_TEXT = Route(
        method="POST",
        path="task/v2/img-to-text",
        doc="Get a text description of an image.",
    )
    CONTROL_NET_TO_IMG = Route(
        method="POST",
        path="task/v2/controlNet-to-img",
        doc="ControlNet-based image generation.",
    )
    SMART_EDIT = Route(
        method="POST",
        path="creativity/generate/apply",
        doc="Apply smart edit / character reference using an input image.",
    )
    UPSCALE = Route(
        method="POST",
        path="task/v2/upscale",
        doc="Upscale an image.",
    )
    DOWNLOAD_URL = Route(
        method="POST",
        path="resource/download",
        doc="Get a download URL for an image.",
    )
    UPLOAD = Route(
        method="POST",
        path="https://www.seaart.ai/api/upload/image-v2",
        doc="Upload an image (absolute endpoint outside base_url).",
    )
    UPLOAD_BY_URL = Route(
        method="POST",
        path="resource/uploadImageByUrl",
        doc="Upload an image by URL.",
    )

    class History:
        """Endpoints for image history."""

        ADD = Route(
            method="POST",
            path="account/img-use/history/add",
            doc="Add an image generation task to the history.",
        )
        LIST = Route(
            method="POST",
            path="account/img-use/history",
            doc="Get the history of image generation tasks.",
        )
        LIST_V2 = Route(
            method="POST",
            path="task/v2/histories",
            doc="Get task histories (v2 endpoint).",
        )
        DELETE = Route(
            method="POST",
            path="account/img-use/history/del",
            doc="Delete an image generation task from the history.",
        )


class Payments:
    """Endpoints for payments and wallet balance."""

    ASSETS = Route(
        method="POST",
        path="payment/assets/get",
        doc="Get wallet/assets info (coins, balances, etc.).",
    )


class Prompts:
    """Endpoints for prompt rendering and recommendations."""

    RENDER = Route(
        method="GET",
        path="task/prompt-render",
        doc="Render a prompt based on the input parameters.",
    )
    RECOMMEND = Route(
        method="POST",
        path="tool/prompt/recommend",
        doc="Get recommended prompts.",
    )


class Tasks:
    """Endpoints for task lifecycle management."""

    PROGRESS = Route(
        method="POST",
        path="task/batch-progress",
        doc="Get progress details for a batch of tasks.",
    )
    CANCEL = Route(
        method="POST",
        path="task/operate",
        doc="Cancel a task.",
    )
    DELETE = Route(
        method="POST",
        path="task/delete",
        doc="Delete a task.",
    )
    CREATE = Route(
        method="POST",
        path="task/create",
        doc="Create a new task.",
    )
    DETAIL = Route(
        method="POST",
        path="task/detail",
        doc="Get detailed information about a task.",
    )
    ESTIMATE = Route(
        method="POST",
        path="task/v2/estimate",
        doc="Estimate the cost of a task.",
    )
    SPEED_UP = Route(
        method="POST",
        path="task/speed-up",
        doc="Attempt to speed up a task.",
    )


class GenAgent:
    """Endpoints for GenAgent conversational generation."""

    STREAM = Route(
        method="POST",
        path="https://www.seaart.ai/api/stream/task/gen-agent/conv",
        doc="Send a message to the GenAgent and receive a streaming response.",
    )
    CREATE = Route(
        method="POST",
        path="task/gen-agent/conv/create",
        doc="Create a new GenAgent conversation session.",
    )
    DELETE = Route(
        method="POST",
        path="task/gen-agent/conv/delete",
        doc="Delete a GenAgent conversation session.",
    )


class Characters:
    """Endpoints for character interactions and chat."""

    COLLECT = Route(
        method="POST",
        path="account/collect",
        doc="Follow/unfollow (collect) a character depending on payload.",
    )
    DETAIL = Route(
        method="POST",
        path="character/detail",
        doc="Get detailed information about a character.",
    )
    MODELS = Route(
        method="POST",
        path="character/model_list",
        doc="Get a list of available models for character chat.",
    )

    class Chat:
        """Endpoints for character chat session management."""

        CREATE = Route(
            method="POST",
            path="character/session/create",
            doc="Create a new character chat session.",
        )
        START = Route(
            method="POST",
            path="character/session/chat/start",
            doc="Start a character chat session.",
        )
        LIST = Route(
            method="POST",
            path="character/session/list",
            doc="Get a list of all character chat sessions.",
        )
        DELETE = Route(
            method="POST",
            path="character/session/delete",
            doc="Delete a character chat session.",
        )
        DELETE_ALL = Route(
            method="POST",
            path="character/session/delete-all",
            doc="Delete all character chat sessions.",
        )

        class Settings:
            """Endpoints for character chat settings."""

            UPDATE = Route(
                method="POST",
                path="character/chat_setting",
                doc="General settings for character chat.",
            )

        class Messages:
            """Endpoints for character chat messages and streaming."""

            LIST = Route(
                method="POST",
                path="character/session/message/list",
                doc="Get the message history of a character chat session.",
            )
            STREAM = Route(
                method="POST",
                path="https://www.seaart.ai/api/stream/character/session/chat_new",
                doc="Send a message to the character and receive a streaming response.",
            )
            STREAM_TOURIST = Route(
                method="POST",
                path="https://www.seaart.ai/api/stream/character/session/tourist_chat",
                doc="Send a message to the character as a tourist and receive a streaming response.",
            )
            STREAM_VOICE = Route(
                method="POST",
                path="timbre/chunk-tts",
                doc="Send a message to the character and receive a streaming voice response (text-to-speech).",
            )

    class DataCards:
        """Endpoints for character datacards."""

        MY = Route(
            method="POST",
            path="datacard/my",
            doc="Get a list of the user's datacards.",
        )
        CREATE = Route(
            method="POST",
            path="datacard/create",
            doc="Create a new datacard.",
        )

    class Replies:
        """Endpoints for recommended character replies."""

        RECOMMEND = Route(
            method="POST",
            path="character/reply/recommend",
            doc="Get recommended replies for a character chat session.",
        )

    class Settings:
        """Endpoints for character account-level settings."""

        UPDATE = Route(
            method="POST",
            path="account/character/setting/update",
            doc="Update character chat settings.",
        )
        SET_DEFAULT = Route(
            method="POST",
            path="character/default_setting",
            doc="Set default character chat settings.",
        )


class Search:
    """Endpoints for search."""

    SEARCH = Route(
        method="POST",
        path="square/v3/search/list",
        doc="Search for characters, prompts, etc.",
    )


class Comments:
    """Endpoints for comments on characters, images, posts, etc."""

    CREATE = Route(
        method="POST",
        path="comment2/create",
        doc="Post a comment on a character, image, etc.",
    )
    LIST = Route(
        method="POST",
        path="comment2/list",
        doc="Get a list of comments for a character, image, etc.",
    )
    DELETE = Route(
        method="POST",
        path="comment2/delete",
        doc="Delete a comment.",
    )


class Posts:
    """Endpoints for posts."""

    CREATE = Route(
        method="POST",
        path="post/v2/create",
        doc="Create a new post.",
    )


class Models:
    """Endpoints for model information and generation parameters."""

    DETAIL = Route(
        method="POST",
        path="model/detail",
        doc="Get detailed information about a model.",
    )
    GENERATION_PARAMETERS = Route(
        method="POST",
        path="task/v2/model-gen-param/v2",
        doc="Get the generation parameters for a model.",
    )
