Metadata-Version: 2.4
Name: saytoken-agent-sdk
Version: 0.2.0
Summary: SDK Python para conectar aplicaciones al Canal API de agentes SayToken
Author: Saytoken
License-Expression: MIT
Project-URL: Homepage, https://saytoken.com
Keywords: saytoken,agents,chatbot,api
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Dynamic: license-file

# saytoken-agent-sdk

SDK Python para conectar una aplicación externa a un agente de SayToken a través del Canal API.
Requiere Python 3.9 o superior.

Requiere que el Canal API esté activo en el agente (`Modificar agente > Canal API`) y tener a mano:

- `api_channel_key`
- `api_channel_secret` (se muestra una sola vez; si lo perdés, rotalo en el mismo panel)

## Instalación

```bash
pip install saytoken-agent-sdk
```

## Modo 1: polling (sin servidor propio)

Ideal para scripts, jobs o backends que no exponen un endpoint HTTPS público. `ask(...)` envía el
mensaje y hace polling hasta que el agente responde o se agota el timeout.

```python
from saytoken_agent_sdk import SayTokenAgentClient

client = SayTokenAgentClient(
    base_url="https://TU_DOMINIO",
    api_channel_key="ack_live_...",
    api_channel_secret="acs_live_...",
)

reply = client.ask(
    message="Hola, necesito ayuda con mi pedido.",
    external_user_id="cliente_123",
    conversation_id="ticket_456",
)

print(reply.status)   # "completed" | "failed"
print(reply.reply)    # texto de respuesta del agente
```

Usá siempre el mismo `conversation_id` para mantener el hilo: si cambia, el agente pierde el
contexto previo. Cada mensaje admite hasta 8000 caracteres.

Para reintentar sin duplicar el mensaje ni su consumo, pasá tu propio `external_event_id` y repetí
la llamada con ese mismo valor. Si no lo pasás, el SDK genera uno nuevo en cada llamada:

```python
reply = client.ask(
    message="Hola, necesito ayuda con mi pedido.",
    external_user_id="cliente_123",
    conversation_id="ticket_456",
    external_event_id="pedido_789_mensaje_1",
)
```

Durante el polling, `ask(...)` reintenta los errores 429, 5xx y fallos de red con espera creciente
hasta agotar `timeout`. Las consultas de estado admiten 120 por minuto por IP y canal; si hacés
muchas `ask(...)` en paralelo, subí `poll_interval`. Si el agente tiene carga, subí `timeout`.

Si preferís controlar el envío y la consulta por separado:

```python
inbound_message_id = client.send_message(
    message="Hola",
    external_user_id="cliente_123",
)

reply = client.get_status(inbound_message_id)
```

`get_status` usa el endpoint `GET /api/agent-api/{api_channel_key}/messages/{inbound_message_id}`,
autenticado con la misma firma HMAC del canal (no requiere login de usuario SayToken).

## Modo 2: callback (tiempo real, requiere HTTPS público)

Si tu app ya expone un servidor HTTPS, configurá `Callback URL` en el panel del agente y usá
`parse_callback` para validar la firma y parsear el evento que SayToken te envía cuando el agente
termina de responder:

```python
from saytoken_agent_sdk import parse_callback, InvalidCallbackSignature

@app.post("/saytoken/callback")
def saytoken_callback():
    raw_body = request.get_data()
    try:
        event = parse_callback(
            raw_body,
            request.headers.get("X-SayToken-Timestamp", ""),
            request.headers.get("X-SayToken-Signature", ""),
            callback_secret="tu_callback_secret_opcional",
        )
    except InvalidCallbackSignature:
        return jsonify({"error": "invalid signature"}), 401

    print(event.status, event.reply)
    return jsonify({"ok": True}), 200
```

Con `callback_secret`, `parse_callback` rechaza firmas inválidas y callbacks con más de 5 minutos
de antigüedad (ajustable con `tolerance_seconds`), así que tu servidor debe tener la hora
sincronizada. Sin `callback_secret` no se valida nada: cualquiera que conozca tu URL podría
enviarte eventos falsos. Tu endpoint debe responder 2xx; si no, SayToken reintenta hasta completar 5 intentos.

## Seguridad

`api_channel_secret` da permiso para enviar mensajes al agente y leer sus respuestas. Guardalo
solo en tu backend (variables de entorno / secret manager) — nunca lo incluyas en una app
distribuida al usuario final (móvil, frontend, extensión).

## Manejo de errores

- `SayTokenAuthError` — firma HMAC inválida o secreto incorrecto.
- `SayTokenAPIError` — cualquier otro error HTTP (`status_code`, `detail`). Si ocurre durante el
  polling de `ask(...)`, incluye `inbound_message_id`.
- `SayTokenTimeoutError` — `ask(...)` no obtuvo `completed`/`failed` dentro del `timeout`; el
  mensaje puede seguir procesándose. Consultalo luego con
  `get_status(exc.inbound_message_id)`, sin volver a enviarlo.

| Código | Causa probable |
|---|---|
| 401 | `api_channel_secret` incorrecto o reloj desfasado más de 5 minutos. |
| 403 | Agente no publicado o IP fuera de `Allowed IPs`. |
| 404 | `api_channel_key` incorrecta, canal apagado o mensaje inexistente. |
| 413 | El mensaje supera los 8000 caracteres. |
| 422 | Faltan `message` o `external_user_id`. |
| 429 | Demasiadas solicitudes o límite diario del canal agotado. |

## Licencia

MIT. Ver el archivo `LICENSE`.
