todus-sdk 1.6.0__tar.gz

todus_sdk-1.6.0/CHANGELOG.md

@@ -0,0 +1,279 @@
+# Changelog
+
+Todos los cambios notables en este proyecto se documentan en este archivo.
+
+El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/),
+y este proyecto sigue [Semantic Versioning](https://semver.org/lang/es/).
+
+## [1.6.0] - 2026-08-20
+
+### Changed
+- Bloques de código en la documentación ahora usan fondo claro en modo claro, corrigiendo el problema donde se veían oscuros.
+- Enlaces del README y documentación actualizados al repositorio nyxthor-dev/toDus-API.
+- Créditos del README actualizados: nyxthor-dev como mantenedor actual.
+
+### Added
+- **Rate Limiter**: Nuevo módulo `todus/ratelimit.py` con `RateLimiter` para control de tasa de peticiones.
+- `RateLimiter` exportado en `todus/__init__`.
+
+---
+
+## [1.5.4] - 2026-06-26
+
+### Added
+- **Event Bus y Sistema de Filtros Avanzados**: Nuevo módulo `todus/events/` con dispatcher centralizado de eventos. Incluye:
+  - `EventBus`: Gestor de eventos thread-safe con prioridades y propagation control.
+  - `Filter` + `build_filter`: Filtros declarativos por `from_phone`, `contains_keyword`, `msg_type`, `is_group`, `group_id`, `regex` y `custom`.
+  - Decorador `@client.events.on(event_type, **filters)` para registrar handlers limpiamente.
+  - Soporte para handlers wildcard (`'*'`) que capturan todos los eventos.
+  - Despacho automático de 7 tipos de eventos: `message`, `presence`, `receipt`, `iq`, `tdack`, `deleted`, `chat_state`.
+  - Método `handle_parsed_stanza(msg, *, sock, callback)` para manejar stanzas parseadas.
+- **Documentación de Event Bus**: Nueva sección `docs/events/overview.md` con guía completa y ejemplos.
+
+### Changed
+- **Integración de EventBus en cliente**: `ToDusClient` ahora inicializa `self.events = EventBus()` automáticamente.
+- **Mejora en `_listen_loop`**: Refactorizada para usar `handle_parsed_stanza` y despachar eventos a `EventBus`.
+- **Actualización de mkdocs.yml**: Agregada sección "🎯 Event Bus y Filtros" en navegación.
+- **Ejemplos avanzados**: Nuevo ejemplo de "Bot Reactivo con EventBus" en `examples_advanced.md`.
+
+### Fixed
+- **Thread-safety en dispatch**: EventBus usa `RLock` para operaciones thread-safe.
+- **Manejo robusto de excepciones**: Si un filtro o handler falla, se registra pero no rompe la propagación.
+
+### Tests Added
+- `tests/test_events.py`: 5 tests para filtros, prioridades, wildcard y unsubscribe.
+- `tests/test_client_events.py`: Integración de eventos en cliente (7 tipos de eventos).
+
+---
+
+## [1.5.3] - 2026-06-21
+
+### Added
+- **Message Queue System**: Nuevo módulo `todus/cache/` con almacenamiento persistente de mensajes en SQLite. Incluye:
+  - `MessageStore`: CRUD thread-safe para mensajes con índices optimizados (status, "to", created_at).
+  - `MessageQueue`: Sistema de cola con reintentos automáticos, callbacks de eventos y backoff exponencial con jitter.
+  - `MessageQueueMixin`: Mixin composable para integrar queue en cualquier cliente.
+  - `ToDusClientWithQueue`: Cliente completo con soporte de queue integrado.
+- **Documentación HTML**: Nueva documentación visual en `documentacion.html` con diseño blanco/rojo, ejemplos terminales Linux/Mac, navegación interactiva y secciones detalladas (Introducción, Inicio Rápido, Instalación, Ejemplos, Características, Mensajería, Message Queue).
+- **Estados de Mensaje**: Implementación completa del ciclo de vida del mensaje (pending → sent → delivered → read/failed).
+- **Callbacks de Evento**: Registro de funciones callback para eventos de mensajes: `on_message_sent`, `on_message_delivered`, `on_message_read`, `on_message_failed`.
+- **Estadísticas de Queue**: Método `get_queue_stats()` para monitoreo en tiempo real de mensajes por estado.
+
+### Changed
+- **Optimización del cliente `ToDusClient2`**: Refactorización elimando ~200 líneas de código duplicado en métodos de envío.
+- **Mejora en `listen_messages`**: Ahora soporta `max_retries` configurable (default 10) con exponential backoff mejorado y mejor logging de errores.
+- **Esquema de persistencia**: Almacenamiento de metadata JSON para campos personalizados en el sistema de queue.
+- **Exports actualizados**: Nuevo `__all__` en `todus/__init__.py` incluyendo `MessageStore`, `Message`, `MessageStatus`, `MessageQueue`, `ToDusClientWithQueue`.
+
+### Fixed
+- **Bug en SQL reserved word**: Corrección del error "sqlite3.OperationalError: near 'to': syntax error" escapando la columna `"to"` en CREATE TABLE e INSERT statements con parámetros posicionales.
+- **Thread-safety mejorada**: Implementación de RLock en todas las operaciones de base de datos del MessageStore para evitar condiciones de carrera.
+- **Limpieza de recursos**: Método `__del__` en `ToDusClientWithQueue` para parar correctamente el worker thread de reintentos.
+- **Eliminación de mensajes antiguos**: Implementación de `clear_old_messages()` para limpiar mensajes con más de 30 días automáticamente.
+
+## [1.5.2] - 2026-06-20
+
+### Added
+- **Sistema de Mensajes Programados (Scheduler)**: Nueva funcionalidad para programar el envío de mensajes automáticos.
+  - `send_later(to, body, delay)`: Envía un mensaje después de un tiempo determinado (ej. 5 minutos).
+  - `schedule_daily(to, body, hour, minute)`: Envía un mensaje todos los días a una hora específica.
+  - `schedule_interval(to, body, interval)`: Envía un mensaje cada cierto intervalo de tiempo (ej. cada hora).
+  - `cancel_task(task_id)`: Cancela una tarea programada.
+  - `list_tasks()`: Lista todas las tareas programadas.
+  - `get_scheduler_stats()`: Obtiene estadísticas del scheduler (tareas pendientes, próxima ejecución, etc.).
+  - `stop_scheduler()`: Detiene el scheduler y libera el hilo.
+- **Verificación SSL configurable**: Nuevo parámetro `verify_ssl` en `ToDusClientBase` y `ToDusClient2` para activar/desactivar la verificación de certificados SSL. Por defecto `False` para mantener compatibilidad con versiones anteriores.
+- **Backoff exponencial con jitter**: Mejora en el método `listen_messages` para reconexiones inteligentes. Ahora los reintentos aumentan progresivamente (1s, 2s, 4s, 8s, 16s, 32s, máximo 60s) con un factor aleatorio del 0-30% para evitar el "efecto rebaño".
+
+### Changed
+- **Refactorización de `ToDusClient2`**: Eliminada la duplicación de código en los métodos de envío (`send_message`, `send_file_message`, `send_image_message`, etc.) mediante el nuevo método interno `_send_to_target`. Centraliza la lógica de detección de grupos y autenticación.
+- **Seguridad SSL mejorada**: Ahora se puede activar la verificación de certificados en conexiones HTTP y XMPP, eliminando la dependencia de la desactivación forzosa de seguridad.
+
+### Fixed
+- **Reconexiones más eficientes**: Reemplazado el `time.sleep(15)` fijo por un sistema de backoff exponencial que reduce la carga del servidor en caídas prolongadas y acelera la reconexión en fallos leves.
+- **Eliminación de duplicación de código**: Los métodos de envío ahora son más mantenibles y fáciles de extender.
+
+## [1.5.1] - 2024-06-20
+
+### Fixed
+- Corrección de la rama de la documentación.
+
+## [1.5.0] - 2024-06-20
+
+### Added
+- **Cobertura 100% de la API de ToDus:** Implementación de todas las funcionalidades internas restantes.
+- **Privacidad (`ToDusPrivacyMixin`)**: Métodos para configurar y consultar quién ve tu perfil o te añade a grupos (`get_profile_privacy`, `set_profile_privacy`, `get_group_privacy`, `set_group_privacy`).
+- **Bloqueos (`ToDusBlockMixin`)**: Gestión de lista negra de contactos (`block_user`, `unblock_user`, `get_block_list`, `get_block_list_paginated`).
+- **Última Conexión (`ToDusLastMixin`)**: Consulta de actividad reciente de usuarios (`get_last_seen`).
+- **Ubicación (`ToDusLocationMixin`)**: Geolocalización y Personas Cerca (`set_location`, `hide_location`, `get_people_near`, `get_near_status`).
+- **Llamadas (`ToDusCallMixin`)**: Señalización XMPP para VoIP (`start_call`, `pickup_call`, `reject_call`, `end_call`, `get_turn_credentials`).
+
+## [1.4.7] - 2026-06-20
+
+### Added
+- Implementación base de **Estados / Historias de ToDus** (`StatusManager`). Se añadió el mixin `ToDusStatusMixin` y soporte nativo XMPP (`td:status:*`):
+  - `publish_status`: Publica historias mediante carga Base64 automática de payloads.
+  - `delete_status`: Permite eliminar un estado publicado.
+  - `get_status`: Recupera un estado de otro usuario.
+  - `follow_user` y `unfollow_user`: Suscripción y cancelación de estados de otros usuarios.
+  - `get_followers`, `get_following` y `get_follower_info`: Interfaz completa para consultar la red de seguidores y seguir de manera paginada.
+
+## [1.4.6] - 2026-06-20
+
+### Added
+- Implementación base completa de **Canales de ToDus**. Se incluyó el mixin `ToDusChannelMixin` con funciones nativas XMPP (`todus:ch:*`) para gestionar canales:
+  - `create_channel`: Permite crear nuevos canales.
+  - `get_my_channels`: Lista los canales del usuario.
+  - `get_channel_info`: Obtiene la información del canal por su enlace.
+  - `publish_to_channel`: Publica mensajes XML nativos en canales.
+  - `get_channel_publications`: Obtiene los últimos mensajes (paginación de historial).
+  - `subscribe_channel` y `leave_channel`: Gestión de membresía de canal.
+- El parser interno `parse_iq` ahora intercepta nativamente los elementos `<query>` que devuelven información compleja (como historiales y propiedades de canales) para su fácil extracción.
+
+### Fixed
+- Solucionado el problema en la actualización del perfil (nombre/alias se convertía en `~`). Ahora se aconseja empaquetar en una misma llamada a `update_profile` todos los atributos que se desean mantener. Se agregó el parámetro opcional `thumbnail_url` faltante en los ejemplos.
+
+## [1.4.5] - 2026-06-20
+
+### Fixed
+- Corregido un test automatizado (`test_upload_avatar_uses_session`) que estaba fallando y bloqueando el despliegue a PyPI debido al cambio previo en la firma de `reserve_upload_url`.
+
+## [1.4.4] - 2026-06-20
+
+### Fixed
+- Corregido un `TypeError` interno en la función `upload_avatar` provocado por la sobreescritura de parámetros en el manejo de firmas mixtas (`reserve_upload_url`).
+
+## [1.4.3] - 2026-06-20
+
+### Added
+- Añadido el método `set_todus_id` al `ToDusProfileMixin` para permitir cambiar el `@username` del usuario mediante la API XMPP nativa de ToDus (utilizando el stanza `todus:users:updatetodusid`).
+
+## [1.4.2] - 2026-06-20
+
+### Changed
+- Reescrito el método `update_profile` del `ToDusProfileMixin` para funcionar con la API REST actual. Ahora utiliza payloads construidos manualmente en Protobuf hacia el endpoint `v2/todus/users.me` en lugar de JSON, reparando finalmente la funcionalidad de actualizar perfil (nombre, biografía y foto).
+- Se modificó la inyección del token JWT en el cliente de perfiles para ajustarse al estándar esperado por `auth.todus.cu` (sin el prefijo `Bearer`).
+
+## [1.4.1] - 2026-06-20
+
+### Added
+- Integración nativa de namespaces `x11`, `x13`, `x14` para gestión avanzada de grupos.
+- Implementado el método correcto de `leave()` mediante petición IQ `x13`.
+- Nuevas funciones de miembros: `get_members`, `set_member_role`, `kick_member`.
+- Nuevas funciones de enlaces: `get_invite_link`, `revoke_invite_link`.
+- Funciones parseadoras auxiliares: `parse_members_response`, `parse_invite_link_response`.
+- Ejemplo funcional `examples/send_grupo_admin.py`.
+
+## [1.4.0] - 2026-06-20
+
+### Added
+- Implementadas funciones para la administración de grupos MUC Light.
+- Nuevos métodos en `GroupClient` para actualizar la información de un grupo:
+  - `set_name`: Permite cambiar el nombre del grupo (`<g4>`).
+  - `set_subject`: Permite cambiar la descripción o asunto del grupo (`<subject>`).
+  - `set_avatar`: Permite actualizar el avatar (imagen) del grupo (`<g3>` y `<picture_thumbnail_url>`).
+
+## [1.3.9] - 2026-06-20
+
+### Fixed
+- Corregida la generación de stanzas salientes (tanto en mensajes de grupo `group.py` como `private.py`), cambiando el atributo `o='{to}'` por el correcto `to='{to}'`. Esto resuelve problemas donde los mensajes no se enrutaban o no se mostraban correctamente al enviar contenidos a los grupos.
+- Añadido el atributo faltante `xmlns='jc'` en `video_message` de los chats privados.
+
+## [1.3.8] - 2026-06-20
+
+### Fixed
+- Corregido un bug en los stanzas de grupos (`group_file_message`, `group_image_message`, `group_video_message`) donde el parámetro `caption` era ignorado y no se incluía en el XML. Ahora los grupos soportan correctamente pies de foto y descripciones.
+
+### Changed
+- Actualizados los parámetros de autenticación a `AUTH_VERSION_NAME = "2.1.2"` y `AUTH_VERSION_CODE = "30102"` para igualar la versión actual de la app oficial de ToDus.
+
+## [1.3.7] - 2026-06-20
+
+### Fixed
+- Normalizado automáticamente el número de teléfono y eliminados espacios/saltos de línea accidentales del token/password en `ToDusClient2` y los métodos del mixin de autenticación.
+- Corregida la serialización de payload protobuf en la autenticación para calcular dinámicamente el tamaño de los campos de texto en lugar de usar longitudes fijas de bytes, evitando fallos `400 Bad Request` ante caracteres extraños (como retornos de carro `\r` generados por archivos `.env` con formato CRLF en Docker).
+
+## [1.3.6] - 2026-06-20
+
+### Fixed
+- Desactivada la verificación SSL en las peticiones HTTP y en el socket XMPP para evitar errores de validación de certificados de ToDus/Cuba en entornos de producción sin CAs locales (como contenedores Docker slim/alpine).
+- Silenciadas las advertencias de `InsecureRequestWarning` producidas por la desactivación de verificación SSL en `requests`.
+
+## [1.3.5] - 2026-06-20
+
+### Fixed
+- Corregidos y optimizados los badges del `README.md` para dar soporte a repositorios privados utilizando badges nativos de GitHub Actions y un badge estático para la licencia.
+
+### Changed
+- Migrado el flujo de publicación de PyPI en GitHub Actions a Trusted Publishing (OIDC) para evitar fallos de autenticación con tokens y simplificar el proceso.
+
+## [1.3.4] - 2026-06-20
+
+### Fixed
+- Asegurado que las operaciones de subida de archivos (`upload_file`) y avatares (`upload_avatar`) utilicen el proxy configurado al direccionarlas a través de la sesión del cliente.
+- Agregados tests unitarios para verificar el comportamiento de proxies en la subida de archivos y avatares.
+
+## [1.3.3] - 2026-06-19
+
+### Changed
+- Renombrado el paquete a `toDus-API`.
+
+## [1.3.2] - 2026-06-19
+
+### Fixed
+- Corregido el flujo de publicación en GitHub Actions para usar `secrets.PYPI_API_TOKEN`.
+
+## [1.3.1] - 2026-06-19
+
+### Added
+- Soporte inicial para proxy HTTP y SOCKS5 en peticiones HTTP y sockets XMPP.
+
+## [1.3.0] - 2026-06-19
+
+### Added
+- Soporte completo para grupos MUC Light (`GroupClient`)
+- Roles de grupo (`GroupRole`) y eventos de grupo (`GroupEvent`)
+- Auto-detección de destino privado/grupo en `ToDusClient2`
+- Envío de mensajes de ubicación (`send_location_message`)
+- Envío de mensajes de eventos/calendario (`send_event_message`)
+- Callbacks específicos por grupo (`on_group_message`)
+- Firma de URLs con nombre legible de archivo (`sanitize_filename`)
+- Soporte de progreso en subidas (`progress_callback`)
+- Módulo `stanzas/` reorganizado en subdirectorio
+- Módulo `client/` reorganizado en subdirectorio con mixins
+- `pyproject.toml` moderno (PEP 621)
+- Tests unitarios con pytest
+- CI/CD con GitHub Actions
+
+### Changed
+- Estructura interna reorganizada para claridad
+- Migración de `setup.py` a `pyproject.toml`
+
+## [1.2.0] - 2026-06-01
+
+### Added
+- Envío de stickers (`send_sticker_message`)
+- Envío de contactos (`send_contact_message`)
+- Envío de botones interactivos (`send_button_message`)
+- Edición de mensajes (`edit_message`)
+- Eliminación de mensajes (`delete_message`)
+- Parser incremental de stanzas XMPP (`IncrementalParser`)
+
+## [1.1.0] - 2026-05-15
+
+### Added
+- Envío de imágenes con dimensiones y thumbnail
+- Envío de videos con metadata
+- Subida y descarga de archivos con `FileType`
+- Perfil de usuario (alias, bio, avatar)
+- Utilidades: `format_size`, `get_image_dimensions`, `generate_blurhash`
+
+## [1.0.0] - 2026-05-01
+
+### Added
+- Cliente básico XMPP para ToDus (`ToDusClient`)
+- Cliente stateful con auto-login (`ToDusClient2`)
+- Autenticación por SMS + JWT
+- Envío y recepción de mensajes de texto
+- Manejo de excepciones personalizadas
+- Constantes del protocolo ToDus

todus_sdk-1.6.0/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2026 OrionWolf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, **subject to the following conditions**:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. **Redistribution of the Software, in whole or in part, is prohibited without
+   the prior written consent of the copyright holder.**
+
+3. Any derivative works must clearly attribute the original work to
+   OrionWolf (https://github.com/vm1008079-web/toDus-API) in their
+   documentation and in any public-facing displays.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

todus_sdk-1.6.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml

todus_sdk-1.6.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: todus-sdk
+Version: 1.6.0
+Summary: Cliente Python para ToDus (mensajería cubana) — chat, grupos, archivos, stickers y más
+Author-email: nyxthor-dev <vm1008079@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nyxthor-dev/toDus-API
+Project-URL: Repository, https://github.com/nyxthor-dev/toDus-API
+Project-URL: Issues, https://github.com/nyxthor-dev/toDus-API/issues
+Project-URL: Changelog, https://github.com/nyxthor-dev/toDus-API/blob/main/CHANGELOG.md
+Keywords: todus,cuba,xmpp,messaging,chat
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pysocks
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mkdocs>=1.6.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
+Requires-Dist: mkdocstrings>=0.27.0; extra == "dev"
+Requires-Dist: mkdocstrings-python>=1.10.0; extra == "dev"
+Requires-Dist: mkdocs-autorefs>=1.2.0; extra == "dev"
+Requires-Dist: mkdocs-macros-plugin>=1.3.0; extra == "dev"
+Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">📱 toDus-API</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/todus-sdk/"><img src="https://img.shields.io/pypi/v/todus-sdk" alt="PyPI"></a>
+  <a href="https://pypi.org/project/todus-sdk/"><img src="https://img.shields.io/pypi/pyversions/todus-sdk" alt="Python"></a>
+  <a href="https://nyxthor-dev.github.io/toDus-API"><img src="https://img.shields.io/badge/docs-mkdocs-blue" alt="Docs"></a>
+  <a href="https://github.com/nyxthor-dev/toDus-API/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen" alt="License"></a>
+  <a href="https://github.com/nyxthor-dev/toDus-API"><img src="https://img.shields.io/github/stars/nyxthor-dev/toDus-API?style=social" alt="Stars"></a>
+</p>
+
+<p align="center"><strong>Cliente Python 🐍 para ToDus</strong> — la plataforma de mensajería instantánea cubana.</p>
+
+<p align="center">
+  <a href="https://nyxthor-dev.github.io/toDus-API"><strong>📖 LEER LA DOCUMENTACIÓN COMPLETA 📖</strong></a>
+</p>
+
+---
+
+## ✨ ¿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
+
+```bash
+pip install todus-sdk
+```
+
+---
+
+## 🧪 Primeros Pasos
+
+```python
+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)
+```
+
+---
+
+## 📚 Documentación Completa
+
+| 📖 Tema | 📝 Descripción |
+|--------|--------------|
+| [🚀 Inicio Rápido](https://nyxthor-dev.github.io/toDus-API/quickstart/) | Tutorial paso a paso |
+| [🔐 Autenticación](https://nyxthor-dev.github.io/toDus-API/authentication/) | SMS vs Contraseña |
+| [💬 Mensajería](https://nyxthor-dev.github.io/toDus-API/client/overview/) | API de mensajes |
+| [👥 Grupos MUC](https://nyxthor-dev.github.io/toDus-API/groups/) | Administración de grupos |
+| [💾 Cola Persistente](https://nyxthor-dev.github.io/toDus-API/cache/overview/) | Entrega garantizada |
+| [🔧 Solución de Problemas](https://nyxthor-dev.github.io/toDus-API/troubleshooting/) | Errores comunes |
+| [💡 Ejemplos Avanzados](https://nyxthor-dev.github.io/toDus-API/examples_advanced/) | Patrones reales |
+
+---
+
+## ⚡ Características
+
+### 📱 Mensajería Completa
+- Texto, imágenes, videos, stickers
+- Ubicación, contactos, eventos
+- Botones interactivos
+- Ediciones y eliminaciones
+- Confirmación de lectura
+
+### 👥 Soporte para Grupos
+- Unirse/Salir de grupos MUC Light
+- Administración de miembros
+- Roles (Owner, Moderator, Participant)
+- Eventos de grupo (join, leave, kick)
+- Enlaces de invitación
+
+### 💾 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
+```python
+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
+```python
+phones = ["5351234567", "5387654321", "5362222222"]
+for phone in phones:
+    client.send_message_queued(phone, "📰 Última noticia: ...")
+```
+
+### 👥 Administrador de Grupo
+```python
+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](https://nyxthor-dev.github.io/toDus-API/examples_advanced/)
+
+---
+
+## 🤝 Contribuir
+
+Las contribuciones son bienvenidas! Ver [guía de contribución](CONTRIBUTING.md).
+
+**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)
+
+## ⚖️ Licencia
+
+Este proyecto está bajo la licencia **MIT**. Ver [LICENSE](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](https://nyxthor-dev.github.io/toDus-API/)
+- 🐛 [Reportar bug](https://github.com/nyxthor-dev/toDus-API/issues)
+- 💬 [Discusiones](https://github.com/nyxthor-dev/toDus-API/discussions)
+- 📝 [CHANGELOG](CHANGELOG.md)
+
+---
+
+## 🔗 Enlaces
+
+- 🌐 [Página de toDus](https://www.todus.cu)
+- 📦 [PyPI Package](https://pypi.org/project/todus-sdk/)
+- 📖 [Documentación](https://nyxthor-dev.github.io/toDus-API/)
+- 💻 [Repositorio GitHub](https://github.com/nyxthor-dev/toDus-API)
+
+---
+
+<p align="center">
+  Desarrollado con ❤️ por <strong>nyxthor-dev</strong><br>
+  <em>Basado en el trabajo original de OrionWolf</em>
+</p>