"""Marca un mensaje IMAP como borrado (\\Deleted) por UID y opcionalmente expurga.

Funcion IMPURA: anade la bandera del sistema `\\Deleted` al mensaje identificado
por su UID en el mailbox seleccionado de una conexion `imaplib.IMAP4_SSL` ya
autenticada y, si `expunge=True`, ejecuta EXPUNGE para materializar el borrado
de todos los mensajes marcados \\Deleted del mailbox.

OJO Gmail: marcar \\Deleted NO borra el mensaje, solo le quita la etiqueta de la
carpeta actual; para un borrado real en Gmail hay que MOVER a "[Gmail]/Trash"
(ver imap_move_message). Esta funcion es el borrado IMAP estandar, util en
servidores no-Gmail (Dovecot, etc.) donde \\Deleted + EXPUNGE si borra.

Nunca lanza: devuelve un dict con `status` ("ok"/"error"). No abre la conexion ni
resuelve credenciales: el caller pasa `conn` ya conectado, autenticado y con
`conn.select("<mailbox>")` hecho.
"""


def imap_delete_message(conn, uid: int, expunge: bool = True) -> dict:
    """Marca como borrado el mensaje `uid` y opcionalmente expurga el mailbox.

    Ejecuta ``conn.uid("STORE", str(uid), "+FLAGS", "(\\Deleted)")`` y, si
    ``expunge=True``, ``conn.expunge()``. La operacion es por UID, no por numero
    de secuencia.

    Args:
        conn: objeto ``imaplib.IMAP4_SSL`` (o ``IMAP4``) YA conectado,
            autenticado y con un mailbox seleccionado (``conn.select(...)``).
        uid: UID del mensaje dentro del mailbox seleccionado. Estable mientras no
            cambie la UIDVALIDITY del mailbox.
        expunge: ``True`` (default) ejecuta EXPUNGE tras marcar \\Deleted, lo que
            elimina del mailbox TODOS los mensajes marcados \\Deleted (no solo
            este). ``False`` deja el mensaje solo marcado \\Deleted, sin expurgar:
            el borrado se materializa en un EXPUNGE posterior o al cerrar el
            mailbox.

    Returns:
        dict. En exito: ``{"status": "ok", "uid": uid, "expunged": expunge}``. En
        fallo (sin lanzar): ``{"status": "error", "error": str}``. Tambien error
        si el STORE responde algo distinto de ``OK``.
    """
    try:
        typ, data = conn.uid("STORE", str(uid), "+FLAGS", "(\\Deleted)")
        if typ != "OK":
            return {
                "status": "error",
                "error": f"imap_delete_message: STORE \\Deleted devolvio {typ!r}: {data!r}",
            }
        if expunge:
            conn.expunge()
        return {"status": "ok", "uid": uid, "expunged": expunge}
    except Exception as e:  # noqa: BLE001
        return {"status": "error", "error": str(e)}


if __name__ == "__main__":
    print("imap_delete_message: importable. Uso real requiere un conn IMAP autenticado.")