Metadata-Version: 2.4
Name: doja-sdk
Version: 0.4.2
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 libreria principal de Python para conectar, automatizar y escalar plataformas de mensajeria usando la **API Cloud Oficial de WhatsApp (Meta)** y **Email (SMTP)**. Facilita la construccion de flujos de atencion al cliente, notificaciones transaccionales y catalogos en minutos sin lidiar con los complejos requerimientos de configuracion nativos.

*Nota: El uso de este SDK esta protegido. Requieres una licencia oficial expedida por DoJa Consulting para interactuar con los servidores mediante esta capa.*

---

## Instalacion

Solo requieres Python 3.7+ y `pip`:

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

---

## Configuracion Rapida - WhatsApp

```python
from doja_sdk import DojaClient, DojaAuthError

try:
    client = DojaClient(
        doja_token="TU-LICENCIA-DOJA",
        whatsapp_token="EAAB123456789...", 
        phone_id="100747123456"
    )
    print("Conexion establecida exitosamente!")
except DojaAuthError as e:
    print(f"Error de validacion de licencia: {e}")
```

---

## Tipos de Mensajes WhatsApp

Todas las funciones requieren el numero de telefono del destinatario **con su codigo de pais (sin el signo + ni espacios)**. Ejemplo para Mexico: `"525512345678"`.

### 1. Mensaje de Texto Simple
```python
client.send_text("525512345678", "Hola! Hemos recibido tu solicitud.")
```

### 2. Mensaje con Documento (PDF, Excel, etc.)
```python
client.send_document(
    to="525512345678", 
    url="https://tu-dominio.com/factura-1234.pdf", 
    caption="Aqui tienes tu factura del mes", 
    filename="Factura_Octubre.pdf"
)
```

### 3. Mensaje con Imagen
```python
client.send_image(
    to="525512345678", 
    url="https://tu-dominio.com/promo-verano.jpg", 
    caption="Aprovecha nuestro descuento de temporada!"
)
```

### 4. Ubicacion Compartida
```python
client.send_location(
    to="525512345678", 
    latitude=19.432608, 
    longitude=-99.133209, 
    name="Oficinas Centrales", 
    address="Centro Historico, CDMX, Mexico"
)
```

### 5. Botones Interactivos (Respuesta Rapida)
```python
botones = [
    {"id": "btn_soporte", "title": "Hablar con Soporte"},
    {"id": "btn_ventas", "title": "Cotizar Servicios"},
]

client.send_interactive_button(
    to="525512345678", 
    body_text="Bienvenido a nuestro canal. En que area podemos apoyarte?", 
    buttons_list=botones
)
```

### 6. Menu Desplegable (Lista Interactiva)
```python
secciones = [
    {
        "title": "Areas de Atencion",
        "rows": [
            {"id": "opt_1", "title": "Soporte Tecnico", "description": "Fallas o configuraciones"},
            {"id": "opt_2", "title": "Facturacion", "description": "Dudas sobre pagos"},
            {"id": "opt_3", "title": "Ventas B2B", "description": "Soluciones empresariales"}
        ]
    }
]

client.send_interactive_list(
    to="525512345678", 
    body_text="Selecciona el departamento con el que deseas comunicarte:", 
    button_text="Ver Opciones", 
    sections=secciones
)
```

### 7. Templates (Mensajes Pre-aprobados por Meta)
```python
client.send_template(
    to="525512345678",
    template_name="confirmacion_pedido",
    language_code="es",
    body_variables=["Juan", "#12345", "manana a las 15:00"]
)
```

**Template con imagen en el encabezado:**
```python
client.send_template(
    to="525512345678",
    template_name="promo_verano",
    language_code="es",
    header_image_url="https://tu-dominio.com/banner.jpg",
    body_variables=["30%", "31 de marzo"]
)
```

---

## Configuracion Rapida - Email

```python
from doja_sdk import DojaEmailClient

email = DojaEmailClient(
    doja_token="TU-LICENCIA-DOJA",
    resend_api_key="re_123456789",
    from_address="no-reply@tuempresa.com"
)
```

---

## Tipos de Email Soportados

### 1. Email de Texto Plano
```python
email.send(
    to="cliente@empresa.com",
    subject="Confirmacion de Registro",
    body="Gracias por registrarte en nuestra plataforma. Tu cuenta ha sido activada."
)
```

### 2. Email con HTML
```python
email.send(
    to="cliente@empresa.com",
    subject="Bienvenido a nuestro servicio",
    body="<h1>Hola Juan</h1><p>Tu cuenta esta lista. <a href='https://tuapp.com'>Inicia sesion aqui</a></p>",
    html=True
)
```

### 3. Email con Archivos Adjuntos
```python
email.send(
    to="cliente@empresa.com",
    subject="Tu Factura de Marzo",
    body="Adjuntamos tu factura correspondiente al mes de marzo.",
    attachments=["/ruta/factura_marzo.pdf"]
)
```

### 4. Email con CC, BCC y Reply-To
```python
email.send(
    to="destinatario@empresa.com",
    subject="Reporte Semanal",
    body="<h2>Reporte de Ventas</h2><p>Adjuntamos el resumen de esta semana.</p>",
    html=True,
    cc=["gerente@empresa.com", "director@empresa.com"],
    bcc=["auditor@empresa.com"],
    reply_to="soporte@empresa.com",
    attachments=["/ruta/reporte.xlsx"]
)
```

---
**Dudas o requerimientos personalizados?** | Soporte Oficial: contact@dojaconsulting.cloud

