Metadata-Version: 2.4
Name: doja-sdk
Version: 0.4.5
Summary: Official Python SDK for DoJa Chatbots and WhatsApp Business Integration
Author-email: DoJa Consulting <contact@dojaconsulting.cloud>
Project-URL: Homepage, https://dojaconsulting.cloud
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests

# DoJa Python SDK 🚀

El **DoJa SDK** es la biblioteca oficial de Python para conectar, automatizar y escalar envíos masivos o transaccionales a través de **WhatsApp Cloud API (Meta)** y **Email (Resend)**.

Con DoJa SDK, te olvidas de integraciones complejas. Usa **la misma licencia** para disparar notificaciones en ambos canales mediante un código elegante, rápido y sin dependencias pesadas.

---

## 💻 Instalación

Solo requieres Python 3.7+ y `pip`. El SDK **no** empuja dependencias pesadas ni requiere que instales las librerías oficiales de Meta o Resend:

```bash
pip install doja-sdk
```

---

## 📚 Índice
1. [WhatsApp (Mensajería, Templates y Multimedia)](#1-módulo-de-whatsapp)
2. [Email (Texto, HTML y Adjuntos)](#2-módulo-de-email)
3. [Manejo de Errores y Excepciones](#3-manejo-de-errores)

---

## 1. Módulo de WhatsApp 💬

Para interactuar con WhatsApp, necesitas tu Token de Licencia DoJa, tu Token de Meta y tu Phone ID.

### Configuración Inicial
```python
from doja_sdk import DojaClient, DojaAuthError

try:
    wa = DojaClient(
        doja_token="TU-LICENCIA-DOJA",   # Token de tu suscripción en DoJa
        whatsapp_token="EAAB12345...",    # Token Permanente/Temporal de Meta
        phone_id="100747123456"           # Identificador de tu número en Meta
    )
    print("¡Conexión a WhatsApp exitosa!")
except DojaAuthError as e:
    print(f"Error de licencia: {e}")
```

### Ejemplos de Envío (WhatsApp)
*(Nota: El destinatario debe incluir código de país sin el signo '+'. Ej: `"525512345678"`)*

**Mensaje de Texto Simple:**
```python
wa.send_text("525512345678", "¡Hola! Hemos recibido tu pago exitosamente.")
```

**Documentos (PDF, Facturas, Excel):**
```python
wa.send_document(
    to="525512345678", 
    url="https://ejemplo.com/factura.pdf", 
    caption="Aquí tienes tu factura del mes 📝", 
    filename="Factura_Octubre.pdf" # Opcional: Nombre con el que se descarga
)
```

**Imágenes y Promocionales:**
```python
wa.send_image(
    to="525512345678", 
    url="https://ejemplo.com/promo.jpg", 
    caption="¡Aprovecha nuestro descuento de temporada!"
)
```

**Ubicación Compartida (Abre interactivo en Google Maps/Waze):**
```python
wa.send_location(
    to="525512345678", 
    latitude=19.432608, 
    longitude=-99.133209, 
    name="Sucursal Centro", 
    address="Centro Histórico, CDMX, México"
)
```

**Botones Interactivos (Máximo 3 botones):**
```python
botones = [
    {"id": "soporte", "title": "Hablar con Soporte"},
    {"id": "ventas", "title": "Cotizar Servicios"}
]

wa.send_interactive_button(
    to="525512345678", 
    body_text="¿En qué área podemos apoyarte hoy?", 
    buttons_list=botones
)
```

**Listas Desplegables (Ideal para menús largos):**
```python
secciones = [
    {
        "title": "Áreas de Atención",
        "rows": [
            {"id": "1", "title": "Soporte", "description": "Fallas técnicas"},
            {"id": "2", "title": "Ventas", "description": "Nuevas suscripciones"}
        ]
    }
]

wa.send_interactive_list(
    to="525512345678", 
    body_text="Por favor selecciona el área deseada:", 
    button_text="Ver Opciones", 
    sections=secciones
)
```

**Templates Aprobados por Meta:**
*(Requerido para iniciar conversación fuera de la ventana de atención de 24 hrs)*
```python
wa.send_template(
    to="525512345678",
    template_name="confirmacion_pedido",  # Nombre idéntico al de Meta
    language_code="es",
    body_variables=["Juan", "#123456", "Mañana a las 15:00 hrs"] 
)
```

---

## 2. Módulo de Email 📧

El Módulo de Email está diseñado para ser extremadamente intuitivo. Para autenticarte, **no requieres doble token**. Tu clave de licencia de DoJa funciona automáticamente como la llave para despachar los correos mediante nuestro proveedor subyacente (Resend).

### Configuración Inicial
```python
from doja_sdk import DojaEmailClient, DojaAuthError

try:
    email = DojaEmailClient(
        doja_token="re_123456789...",           # Tu licencia se mapea directo aquí
        from_address="no-reply@tuempresa.com"    # Remitente previamente verificado
    )
    print("¡Conexión de Email exitosa!")
except DojaAuthError as e:
    print(f"Error de licencia o permisos: {e}")
```

### Ejemplos de Envío (Email)

**Texto Plano Rápido:**
```python
email.send(
    to="cliente@empresa.com",
    subject="Confirmación de Registro",
    body="Gracias por registrarte en nuestra plataforma."
)
```

**Email con HTML enriquecido:**
```python
email.send(
    to="cliente@empresa.com",
    subject="Bienvenido a tu suscripción Pro",
    body="<h1>¡Hola Juan!</h1><p>Tu cuenta ya está activa. <a href='https://app.doja.com'>Ingresa aquí</a>.</p>",
    html=True
)
```

**Email con Archivos Adjuntos Locales:**
*(El SDK se encarga por debajo de codificar los archivos en Base64 de forma automática)*
```python
email.send(
    to="cliente@empresa.com",
    subject="Tu Factura de Marzo",
    body="Adjuntamos tu factura digitalizada correspondiente a este mes.",
    attachments=["/ruta/absoluta/factura_marzo.pdf"]
)
```

**Funciones Avanzadas (Múltiples destinatarios, CC, BCC y Reply-To):**
```python
email.send(
    to="gerente@empresa.com, asistente@empresa.com",   # Puedes separar por comas
    subject="Reporte Financiero Semanal",
    body="<h2>Reporte Generado</h2><p>Aquí tienes el archivo de esta semana.</p>",
    html=True,
    cc=["director@empresa.com"],
    bcc=["auditoria@empresa.com"],
    reply_to="soporte@empresa.com",
    attachments=["/ruta/reporte.xlsx", "/ruta/resumen.pdf"]
)
```

---

## 3. Manejo de Errores 🛡️

El SDK expone excepciones estandarizadas que te permiten saber exactamente qué falló (si fue un problema de saldo, de licencia o de la API destino). Las puedes importar todas desde `doja_sdk`:

```python
from doja_sdk import (
    DojaClient,
    DojaAuthError,
    DojaQuotaExceeded,
    DojaAPIError
)

try:
    client = DojaClient(...)
    client.send_text(...)

except DojaAuthError as e:
    # 404 No encontrado, 422 Inválido, 409 Suspendido, o no tiene el canal (WhatsApp/Email) pagado
    print(f"Problema con la Licencia: {e}")

except DojaQuotaExceeded as e:
    # 409 La licencia es válida, pero el cliente se acabó su bolsa de mensajes
    print(f"Saldo Agotado: {e}")

except DojaAPIError as e:
    # Ocurre si Meta o Resend rechazan la petición (Ej: plantilla mal armada, mal teléfono, adjunto pesado)
    print(f"Problema con el Proveedor Destino: {e}")
```

---
**¿Dudas adicionales o soporte técnico?**  
Comunícate directamente a: contact@dojaconsulting.cloud


