# retoor <retoor@molodetz.nl>

from __future__ import annotations

from ..spec import Action
from ._shared import body, confirm, path, 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="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). Soft delete, confirmation required",
        params=(path("attachment_uid", "Uid of the attachment."), confirm()),
    ),
)