Stanzas – Generadores de XML

El módulo stanzas contiene generadores de XML para todas las interacciones con el servidor XMPP de ToDus. Estos generadores son utilizados internamente por los mixins del cliente, pero también pueden ser usados directamente para personalizar comportamientos.

Estructura del Módulo

stanzas/
├── private.py      # Mensajes privados (texto, archivos, etc.)
├── group.py        # Mensajes de grupo
├── presence.py     # Presencia (online, offline, MUC)
├── utils.py        # Utilidades XMPP (IQ, ping, auth, MAM, upload)
├── channels.py     # Canales (crear, publicar, suscribir)
├── status.py       # Estados/Historias
├── privacy.py      # Privacidad
├── block.py        # Bloqueos
├── last.py         # Última conexión
├── location.py     # Ubicación (Near)
├── call.py         # Llamadas (TURN)
└── profile.py      # Cambio de @username

Uso Básico

Cada función retorna una cadena XML lista para enviar por el socket XMPP.

from todus.stanzas import private, group, presence, utils

# Mensaje privado
xml = private.message("5351111111@im.todus.cu", "Hola")
sock.send(xml.encode())

# Mensaje de grupo
xml = group.group_message("grupo@muclight.im.todus.cu", "Hola grupo")

# Presencia
xml = presence.presence("Online", priority=5)

Módulos Destacados

`private.py` – Mensajes Privados

Función	Descripción
`message(to, body, msg_id, msg_type, reply_to_id)`	Texto.
`edit_message(to, new_body, original_msg_id, edit_id, reply_to_id)`	Edición.
`file_message(to, url, file_type, caption, msg_id, file_name, file_size, reply_to_id)`	Archivo.
`image_message(...)`	Imagen.
`image_message_simple(...)`	Imagen simple.
`button_message(to, text, buttons, msg_id, reply_to_id)`	Botones.
`contact_message(...)`	Contacto.
`sticker_message(...)`	Sticker.
`video_message(...)`	Video.
`delete_message(...)`	Eliminación.
`location_message(...)`	Ubicación.
`event_message(...)`	Evento.

Estructura de un botón:

button = {
    "text": "Enviar",
    "command": "cmd_type_send",
    "data": "Hola",
    "size": "0.82",        # FULL
    "color": "primary",    # opcional
    "row": True            # opcional
}

`group.py` – Mensajes de Grupo

Similar a private.py pero con t='gc' y destinados a JID de grupo.

Además incluye funciones para administración:

Función	Descripción
`group_update_name(to, name, msg_id)`	Cambiar nombre.
`group_update_subject(to, subject, msg_id)`	Cambiar asunto.
`group_update_avatar(to, avatar_url, msg_id)`	Cambiar avatar.
`group_update_avatar_thumbnail(to, thumbnail_url, msg_id)`	Cambiar miniatura.
`group_leave_iq(to, msg_id)`	Salir.
`group_get_link_iq(to, msg_id)`	Obtener enlace.
`group_set_link_iq(to, msg_id)`	Revocar enlace.
`group_get_members_iq(to, msg_id)`	Lista miembros.
`group_set_members_iq(to, affiliations, msg_id)`	Modificar roles.

`presence.py`

Función	Descripción
`presence(status, priority, show, caps)`	Presencia estándar.
`muc_presence(group_jid, nickname)`	Unirse a grupo.
`muc_unavailable(group_jid)`	Salir de grupo.

`utils.py`

Función	Descripción
`iq(type_, iq_id, payload, to)`	IQ genérico.
`build_iq(type_, to, query)`	IQ con ID autogenerado.
`ping(ping_id)`	Ping XMPP.
`chat_state(to, state, msg_id, msg_type)`	Estado de escritura.
`receipt(to, msg_id, receipt_id, msg_type)`	ACK de entrega.
`read_receipt(to, msg_id, receipt_id, msg_type)`	ACK de lectura.
`ack(msg_id, to)`	TDACK.
`keepalive()`	Espacio en blanco.
`stream_open(host)`	Inicio de stream.
`stream_restart(host)`	Reinicio de stream.
`stream_close()`	Cierre de stream.
`sasl_auth(authstr)`	Autenticación SASL PLAIN.
`bind(iq_id)`	Resource bind.
`mam_query(query_id, since, before, limit)`	MAM (archivo de mensajes).
`upload_query(iq_id, size, file_type, persistent, file_name)`	Reserva de subida.
`download_query(iq_id, url)`	Resolución de descarga.

Canales, Estados, Privacidad, etc.

Estos módulos generan stanzas IQ para sus respectivos dominios. Todas las funciones reciben parámetros específicos y retornan XML con msg_id autogenerado.

Ejemplo con canales:

from todus.stanzas import channels

xml = channels.create_channel_iq(
    name="Mi Canal",
    link="micanal",
    public=1,
    desc="Descripción",
    picture="https://...",
    subs=["5351111111", "5352222222"]
)

Uso Avanzado: Envío Directo

Puedes enviar stanzas manualmente si necesitas un control total:

with client._xmpp_session(client.token) as sock:
    sock.send(xml.encode())