Visión General del Cliente ToDus

El módulo client es el núcleo del SDK. Contiene la lógica de conexión XMPP, autenticación y todas las funcionalidades de la plataforma.

Arquitectura

El cliente principal ToDusClient2 combina múltiples mixins que agrupan funcionalidades específicas.

ToDusClient2
├── ToDusClientBase          # Socket XMPP, Handshake, Sesiones
├── ToDusAuthMixin           # Autenticación (login, código SMS)
├── ToDusMessageMixin        # Mensajería (texto, archivos, etc.)
├── ToDusFileMixin           # Subida/descarga de archivos
├── ToDusProfileMixin        # Perfil y avatar
├── ToDusChannelMixin        # Canales públicos/privados
├── ToDusStatusMixin         # Estados/Historias
├── ToDusPrivacyMixin        # Configuración de privacidad
├── ToDusBlockMixin          # Bloqueo de usuarios
├── ToDusLastMixin           # Última conexión
├── ToDusLocationMixin       # Ubicación (Near)
└── ToDusCallMixin           # Señalización de llamadas

Clases Principales

ToDusClient2 (Recomendado)

Clase stateful que mantiene la sesión, el token y el número de teléfono.

Constructor:

ToDusClient2(
    phone_number: str,
    password: str = "",
    proxy: Optional[str] = None,
    verify_ssl: bool = False,
    **kwargs
)

Propiedades:

  • token – JWT actual.
  • logged – bool indica si hay sesión activa.
  • phone_number – Número normalizado.
  • groups – Instancia de GroupClient.

Métodos principales:

  • login() → Inicia sesión.
  • send_message(to, body, reply_to_id) → Envía texto.
  • upload_file(data, file_type, progress_callback, file_name) → Sube archivo.
  • listen_messages(callback) → Bucle de escucha.

ToDusClient (Stateless)

Clase que hereda todos los mixins pero no mantiene estado. Todos los métodos requieren token como primer argumento. Útil para aplicaciones que manejan múltiples cuentas simultáneamente.

# Ejemplo stateless
client = ToDusClient()
token = client.login("5312345678", "password")
client.send_message(token, "5387654321@im.todus.cu", "Hola")

Detección Automática de Grupos

ToDusClient2 incluye un mecanismo de detección inteligente:

  • Si to_phone es un número de 10 dígitos empezando por 53 → se envía como mensaje privado.
  • Si no cumple con el patrón → se trata como ID de grupo y se reenvía a client.groups.

Esto permite usar los mismos métodos (send_message, send_image_message, etc.) indistintamente para privados o grupos.

Ciclo de Vida de la Conexión

  1. Autenticación: login() obtiene el token JWT.
  2. Handshake: Se establece el socket XMPP y se negocia SASL.
  3. Sesión: Se envía presencia inicial y se mantiene el stream.
  4. Escucha: listen_messages() entra en un bucle recibiendo stanzas.
  5. Keepalive: Envía pings cada 25 segundos para mantener la conexión.
  6. Reconexión: Si la conexión se pierde, listen_messages espera 15s y reintenta.

Acceso a Mixins

Todos los mixins están disponibles directamente en la instancia de ToDusClient2. Por ejemplo:

client.send_message(...)        # ToDusMessageMixin
client.upload_file(...)         # ToDusFileMixin
client.update_profile(...)      # ToDusProfileMixin
client.block_user(...)          # ToDusBlockMixin
client.set_location(...)        # ToDusLocationMixin
client.start_call(...)          # ToDusCallMixin

Consulta la página Mixins para la referencia completa de todos los métodos.