Metadata-Version: 2.4
Name: todus-sdk
Version: 1.10.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-SDK
Project-URL: Repository, https://github.com/nyxthor-dev/toDus-SDK
Project-URL: Issues, https://github.com/nyxthor-dev/toDus-SDK/issues
Project-URL: Changelog, https://github.com/nyxthor-dev/toDus-SDK/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

<p align="center">
  <img src="docs/assets/logo.png" alt="toDus-API" width="128"/>
</p>

<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)
```

### 🔓 Login solo con número (sin password)

```python
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](https://nyxthor-dev.github.io/toDus-API/authentication/)
para más detalles.

---

## 📚 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
- **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
```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)

## 🔌 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`.

```python
# 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](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">
  <img src="docs/assets/logo.png" width="64" alt="logo"/><br>
  Desarrollado con ❤️ por <strong>nyxthor-dev</strong><br>
</p>
