📱 toDus-API

Cliente Python 🐍 para ToDus — la plataforma de mensajería instantánea cubana.

📖 LEER LA DOCUMENTACIÓN COMPLETA 📖

---

✨ ¿Qué es toDus-API?

Es una librería moderna y poderosa para interactuar con la red de ToDus desde Python. Te permite crear:

• 🤖 Bots inteligentes - Responden a comandos y preguntas
• 📢 Notificadores - Envíos masivos con reintentos automáticos
• 💬 Chat bots - Integración con IA y LLMs
• 📊 Sistemas de reportes - Automatización de reportes
• 🔗 Integraciones - Sincroniza ToDus con tus sistemas

Cobertura del protocolo: ✅ 100% de las funciones de la app oficial

---

🚀 Instalación

pip install todus-sdk

---

🧪 Primeros Pasos

from todus import ToDusClientWithQueue

# Crear cliente con cola persistente
client = ToDusClientWithQueue("5312345678", "tu_contraseña")
client.login()

# Enviar mensaje
msg_id = client.send_message_queued("5387654321", "¡Hola!")

# Escuchar mensajes
def on_message(msg):
    print(f"{msg.get('from')}: {msg.get('body')}")

client.listen_messages(client.token, on_message)

🔓 Login solo con número (sin password)

from todus import ToDusClient2

client = ToDusClient2("5312345678")
client.login_with_phone_only()  # sin password, sin SMS

Explota una debilidad del endpoint /v2/auth/token que acepta cualquier UUID como "password". Ver Autenticación para más detalles.

---

📚 Documentación Completa

📖 Tema	📝 Descripción
🚀 Inicio Rápido	Tutorial paso a paso
🔐 Autenticación	SMS vs Contraseña
💬 Mensajería	API de mensajes
👥 Grupos MUC	Administración de grupos
💾 Cola Persistente	Entrega garantizada
🔧 Solución de Problemas	Errores comunes
💡 Ejemplos Avanzados	Patrones reales

---

⚡ Características

📱 Mensajería Completa

• Texto, imágenes, videos, stickers
• Notas de voz con forma de onda y GIFs
• Reacciones (emojis) y reenvíos
• Ubicación, contactos, eventos
• Botones interactivos (comandos oficiales)
• Ediciones y eliminaciones
• Confirmación de entrega y lectura

👥 Soporte para Grupos

• Unirse/Salir de grupos MUC Light
• Crear grupos y listar los tuyos
• Promover/degradar administradores
• Administración de miembros
• Roles (Owner, Moderator, Participant)
• Eventos de grupo (join, leave, kick)
• Enlaces de invitación + info por link/id

💾 Persistencia

• Cola de mensajes con SQLite
• Reintentos exponenciales automáticos
• Callbacks para eventos
• Estadísticas en tiempo real

🌐 Avanzado

• Canales públicos/privados
• Estados/Historias
• Proxies (HTTP, SOCKS4/5)
• Autenticación SMS
• Reconexión automática

---

💻 Casos de Uso

🤖 Bot con Comandos

def on_message(msg):
    if msg.get('body', '').startswith('/'):
        cmd = msg['body'][1:]
        client.send_message_queued(
            msg['from'].split('@')[0],
            f"Ejecutaste: {cmd}"
        )

client.listen_messages(client.token, on_message)

📢 Newsletter

phones = ["5351234567", "5387654321", "5362222222"]
for phone in phones:
    client.send_message_queued(phone, "📰 Última noticia: ...")

👥 Administrador de Grupo

groups = client.groups
groups.join("id_grupo", nickname="AdminBot")
groups.send_message("id_grupo", "¡Hola grupo!")
members = groups.get_members("id_grupo")

Ver más ejemplos en Ejemplos Avanzados

---

🤝 Contribuir

Las contribuciones son bienvenidas! Ver guía de contribución.

Pasos rápidos:

1. Fork el repositorio
2. Crea una rama: git checkout -b feature/tu-feature
3. Commit cambios: git commit -am 'Añade feature'
4. Push: git push origin feature/tu-feature
5. Abre Pull Request

---

📋 Requisitos

• Python >= 3.11
• pip (incluido en Python)

🔌 Conexión XMPP

Desde la v1.8.0 el SDK usa el puerto 1756 de producción (el mismo que la app oficial v2.1.2). Puerto alternativo PROD_2: 5443.

# Puerto por defecto (1756)
client = ToDusClientWithQueue("5312345678", "tu_contraseña")

# Puerto alternativo
client = ToDusClientWithQueue("5312345678", "tu_contraseña", xmpp_port=5443)

⚖️ Licencia

Este proyecto está bajo la licencia MIT. Ver LICENSE para más detalles.

---

👥 Contribuidores

Agradecemos a todos los que han contribuido:

• nyxthor-dev - Mantenedor actual
• OrionWolf - Creador original
• Comunidad toDus - Bug reports y sugerencias

¿Quieres aparecer aquí? ¡Contribuye!

---

📞 Soporte

• 📖 Documentación
• 🐛 Reportar bug
• 💬 Discusiones
• 📝 CHANGELOG

---

🔗 Enlaces

• 🌐 Página de toDus
• 📦 PyPI Package
• 📖 Documentación
• 💻 Repositorio GitHub

---

Desarrollado con ❤️ por nyxthor-dev