# retoor <retoor@molodetz.nl>

from __future__ import annotations

from ..spec import Action
from ._shared import body, confirm, path, query, upload


UPLOAD_ACTIONS: tuple[Action, ...] = (
    Action(
        name="upload_file",
        method="POST",
        path="/uploads/upload",
        summary="Upload a local file and obtain its attachment uid",
        params=(upload("file", "Local filesystem path of the file to upload."),),
    ),
    Action(
        name="list_attachments",
        method="GET",
        path="/uploads",
        summary="List your own uploaded attachments, newest first",
        description=(
            "Returns the signed-in user's attachments as {attachments, pagination, total}. Each item "
            "carries its uid, original_filename, mime_type, url, size, target_type/target_uid/target_url "
            "(where it is used, if any), and a 'linked' flag. Pass linked=true to list only attachments "
            "already attached to a post/comment/project/gist/issue, or linked=false for orphaned uploads."
        ),
        params=(
            query("page", "1-based page number, 24 per page."),
            query("linked", "Filter: true = attached only, false = orphaned only."),
        ),
    ),
    Action(
        name="get_attachment",
        method="GET",
        path="/uploads/{attachment_uid}",
        summary="Get the metadata of one of your attachments by uid",
        params=(path("attachment_uid", "Uid of the attachment."),),
    ),
    Action(
        name="rename_attachment",
        method="PATCH",
        path="/uploads/{attachment_uid}",
        summary="Rename an attachment you own (its display filename); the file extension is preserved",
        description=(
            "Updates only the display filename of the attachment; the stored file and its extension are "
            "unchanged (the original extension is always kept, so the file type cannot be altered). "
            "Administrators may rename any user's attachment."
        ),
        params=(
            path("attachment_uid", "Uid of the attachment."),
            body("filename", "New display filename.", required=True),
        ),
    ),
    Action(
        name="attach_url",
        method="POST",
        path="/uploads/upload-url",
        summary="Download a file from a public URL and store it as an attachment, returning its uid",
        description=(
            "Fetches the file at the given URL on the server (size-capped, SSRF-guarded) and stores it "
            "as an attachment exactly like an upload, returning {uid, url, mime_type, ...}. Pass the "
            "returned uid in attachment_uids when you create_post, create_project, create_gist, "
            "create_comment, create_issue, or send_message to attach it. The file type is taken from the "
            "URL or its Content-Type; supply 'filename' (with an allowed extension) when the URL has no "
            "usable name. Use this to attach an image or file straight from the internet."
        ),
        params=(
            body("url", "Public http(s) URL of the file to download and attach.", required=True),
            body(
                "filename",
                "Optional filename with an allowed extension, used when the URL has no clear name.",
            ),
        ),
    ),
    Action(
        name="delete_attachment",
        method="DELETE",
        path="/uploads/delete/{attachment_uid}",
        summary="Delete an uploaded attachment (your own, or anyone's when you are an administrator). Confirmation required",
        description=(
            "Removes one attachment by uid. Use list_attachments (or get_attachment) to find the uid of the "
            "file the user wants gone, then delete it. The attachment leaves the owner's attachment list and "
            "disappears from every post, comment, project, gist, message, or issue it was attached to, and its "
            "file stops being served. Only the owner may delete their own; an administrator may delete anyone's "
            "(otherwise 403); an unknown or already-removed uid returns 404. This is confirmation-gated: the "
            "first call is refused so you can show the user the exact attachment (filename + where it is used) "
            "first, and only a repeat call with confirm=true performs it."
        ),
        params=(path("attachment_uid", "Uid of the attachment."), confirm()),
    ),
)