Saltar al contenido principal
Novedades en la API de Theo, @hitheo/sdk, @hitheo/mcp, @hitheo/telegram y @hitheo/whatsapp. Publicamos aquí cuando lanzamos algo que las personas desarrolladoras pueden usar.

​
Política de versionado

  • Los paquetes siguen semver. Antes de 1.0.0, el incremento minor es la señal de cambio incompatible (coincide con cómo el operador ^ de npm resuelve 0.x.y) — ^0.1.6 no se actualiza automáticamente a 0.2.0.
  • Los cambios aditivos (nuevos endpoints, campos opcionales, nuevos métodos del SDK) salen como minor o patch y nunca rompen a quienes están fijados en una versión.
  • La superficie de API en https://www.hitheo.ai/api/v1/* está versionada por fecha, no por ruta. La versión actual es 2026-03-28, devuelta en el encabezado Theo-Api-Version.

​
[Sin publicar]

​
Añadido

  • El modo de voz del widget embebible es totalmente consciente de tu marca. Abre la voz en tu widget y quienes te visitan ven tu logo y el nombre de tu marca en el encabezado, una esfera que brilla con tu color principal mientras escucha y habla, transcripciones que coinciden con tus burbujas de chat de texto y una barra de controles limpia con tu tema — cada superficie que toca una persona visitante en modo voz ahora coincide con la marca que configuraste en el constructor de iframes. La antigua interfaz compartida del playground se ha retirado de la superficie de embed.
  • Respuestas acotadas a tu marca en widgets embebibles. Activa el nuevo conmutador Scope responses to this brand en cualquier clave de API y Theo se mantiene dentro del catálogo de esa marca — recomienda solo tus propios productos y contenido, nunca menciona ni se compara con la competencia (ni siquiera como analogía o referencia de estilo) y redirige educadamente las solicitudes fuera de tema hacia tu URL de soporte. El conmutador se activa automáticamente cuando usas Fetch Brand en el constructor de iframes, así que importar una marca es un solo clic para obtener un asistente bloqueado a tu marca de extremo a extremo.
  • Respuestas enriquecidas en los chats del widget embebible. Las respuestas de Theo dentro de los widgets en iframe ahora renderizan el formato visualmente — imágenes en línea del logo de marca, encabezados, listas, tablas, bloques de código, enlaces — en lugar de filtrar el Markdown subyacente como texto plano. El estilo coincide con el tema de tu widget (los colores de encabezados y enlaces siguen tu color principal, los bloques de código toman el fondo de tus burbujas).

​
Mejorado

  • El autorrelleno de marca en el constructor de iframes llega a más dominios. Pega un subdominio de marketing como os.example.com y el importador reintenta contra tu raíz example.com si el subdominio exacto no tiene datos indexados, de modo que la importación tiene éxito donde antes devolvía silenciosamente un resultado vacío. La tarjeta de resultado muestra la fuente canónica de la marca para que veas exactamente de dónde vinieron los datos.
  • El autorrelleno de marca te dice por qué no tuvo éxito una importación. Cuando una consulta no devuelve datos de marca, no hay proveedor configurado o la URL es inválida, ves un mensaje en línea debajo de la entrada con el motivo específico. Se acabaron los clics silenciosos.
  • El autorrelleno de marca te muestra la marca importada en el momento en que está lista en lugar de esperar la captura de pantalla en paralelo. Una consulta fallida muestra su razón en menos de dos segundos; una consulta exitosa rellena los campos de marca de inmediato y deja que la captura aterrice por separado cuando termina.
  • Fetch Brand en el constructor de iframes también actualiza la Brand Soul de la clave de API. Una importación de marca exitosa ahora importa la identidad de marca sobre la clave de API vinculada — nombre, eslogan, logo, colores, ethos, industria y URL de soporte — para que el asistente orientado al visitante se presente como tu marca desde el primer mensaje, no solo el cromado del widget.
  • La Brand Soul del widget embebible se aplica en cada turno — incluidos los flujos de voz y de formularios de captación previos al chat. La identidad de marca que configures en una clave de API (nombre, eslogan, tono, ethos, CTA, URL de soporte) determina cómo el widget saluda a las personas visitantes y responde a “¿quién eres?” en cada canal, de extremo a extremo.
  • Las claves de API de equipo ya funcionan en el constructor de widgets. Si tu equipo comparte una clave de API a través de una organización, ahora puedes seleccionarla al crear un widget de chat. Las claves personales y las de equipo aparecen en el mismo selector y ambas se vinculan limpiamente.
  • Errores más claros cuando no se puede crear un widget. El botón Create Widget ahora te dice por qué falla la solicitud — clave inválida, problema de validación, estado de facturación — en lugar de un marcador genérico.
  • El input de chat embebible maneja contenido largo con elegancia. El área de texto del chat crece con el mensaje de la persona visitante, ajusta URLs muy largas o texto sin saltos en lugar de empujar el botón de enviar fuera de pantalla y nunca se colapsa a una sola línea en respuestas multilínea.
  • Ask Theo en el editor de canvas — pequeño icono de Theo junto a cada campo de texto en el E.V.I. Canvas (nodos Prompt, Tool, Vision, Output, Condition, Webhook, Web Knowledge, además del texto del diálogo Publish). Haz clic y Theo lee tu canvas en vivo y luego transmite una sugerencia contextual al campo mientras observas. El menú Theo Assist del constructor de Prompt ahora comienza con Write from Scratch — genera un nuevo prompt de sistema compatible con el validador con el rol, las restricciones y las variables de plantilla en tiempo de ejecución correctas, todo inferido de tu canvas. Las cinco acciones existentes (Enhance, Rewrite, Simplify, Add Examples, Make Concise) siguen debajo en el mismo menú para que tengas un único punto de entrada de Theo por campo.
  • Selector de habilidades por clave — nueva pastilla Skills en cada clave de API de tu panel. Haz clic para elegir exactamente cuáles de tus habilidades instaladas puede llamar esa clave. Las nuevas habilidades que publiques o instales más tarde no se adjuntarán automáticamente — tú mantienes el control sobre la superficie de capacidades de cada clave.
  • Selector de claves por habilidad — vista inversa dentro del panel de detalle de cualquier habilidad instalada (My Skills → haz clic en una habilidad). Marca cuáles de tus claves de API pueden llamar a esta habilidad sin salir de la vista de habilidad.
  • Paso “Enable on which keys?” en el momento de publicar — el diálogo Publish ahora termina con un selector explícito para que elijas qué claves verán tu nueva habilidad. Por defecto no hay nada marcado — opta por activarla por clave, o sáltatelo por completo y añádelo después desde las páginas Skills o Keys.
  • Gateway Guardrails — políticas opcionales de entrada/salida aplicadas en cada completion vinculado a una clave de API. Cinco protecciones integradas (redactor de PII, denegación de inyección de prompts, reparación de JSON, truncado por longitud máxima, marcado de lenguaje obsceno) con cinco veredictos (flag, redact, truncate, repair, deny). La aplicación está unificada entre /v1/completions (con y sin streaming), /v1/images, /v1/code, /v1/documents, el playground y los widgets embebibles. El SDK añade theo.guardrails.policies, theo.guardrails.presets, theo.guardrails.executions y theo.keys.{get,set}GuardrailPolicy(). Nuevo código de error guardrail_violation (HTTP 422) en veredictos de denegación. Consulta la guía de Guardrails.
  • Routing Studio — preferencias de enrutamiento por cliente con un editor visual, galería de presets, reglas por palabras clave, ejemplos few-shot y overrides de piso de confianza por modo. API en /api/v1/routing-preferences con CRUD completo más un endpoint /test que reproduce un prompt de fixture antes y después de la preferencia. Vinculación por clave en /api/v1/keys/{id}/routing-preference. Los eventos de streaming meta y done exponen routing.customer_preference siempre que una preferencia vinculada contribuye. El SDK añade theo.routingPreferences.* y theo.keys.{get,set}RoutingPreference. Consulta la guía de Routing Studio.
  • Recibo de enrutamiento del playground — cada turno del asistente renderiza un recibo en línea debajo de la insignia del modelo, exponiendo la decisión de enrutamiento detrás de cada respuesta. La vista compacta muestra el modo solicitado → resuelto y un chip Promoted cuando el enrutamiento anuló la elección de quien llamó. Expande para ver la confianza de la clasificación, los overrides de habilidad, la familia bloqueada y la visual del pipeline de cuatro etapas. Un chip verde Studio se enciende cuando una preferencia de Routing Studio contribuyó.
  • SDK theo.verify() — diagnóstico de conectividad y autenticación para el primer arranque. Devuelve { healthy, authenticated, baseUrl, latencyMs } con consejos accionables para estados comunes de configuración.
  • CLI theo verify — salida JSON legible por máquina para el mismo diagnóstico. Salida con código distinto de cero en caso de fallo para que CI pueda bloquear según ello.
  • SDK TheoStream — theo.stream(...) devuelve un async-iterable con un método cancel() para abortar limpiamente a mitad de generación, además de propiedades de metadatos finales (conversationId, usage, model, requestId) rellenadas a partir de los eventos meta y done.
  • Unión StreamEvent discriminada — switch (event.type) reduce event.data automáticamente. No hace falta as any.
  • Retornos tipados de list y get del SDK — conversations(), skills(), tools(), workflows(), submissions(), listWebhooks(), listHooks(), usage() y sus pares de mutación ahora devuelven interfaces con nombre (ConversationSummary, SkillSummary, WorkflowRecord, etc.) en lugar de unknown[].
  • Extensiones de CompletionRequest — conversation (envoltorio en línea), personality_config, response_style, theo_branding, brand_soul, attachments, image_model, image_quality, stealth_model, stealth_aspect, stealth_duration.
  • Soporte de Idempotency-Key — los POST que cambian estado en /workflows, /skills, /webhooks, /hooks, /events, /evi/canvases, /iframes, /browser/sessions aceptan el encabezado Idempotency-Key. Las respuestas se almacenan en caché 24 horas por clave.
  • request_id en respuestas JSON — /completions, /images, /video, /code, /research, /documents, /audio/stt exponen el id de solicitud como campo de nivel superior además del encabezado de respuesta existente.
  • conversation_id en eventos de stream — los eventos meta y done en /completions incluyen conversation_id para que las personas clientes no tengan que leerlo por separado.
  • Documentación de Follow-ups — página de concepto que cubre cuándo se genera follow_ups[] y patrones de integración en la UI de chat.
  • Esquemas SSE completos publicados — la referencia de Streaming Completions ahora publica interfaces TypeScript para cada evento (meta, token, tool, artifact, genui_meta, skills, done, error).
  • Memoria entre sesiones — Theo ahora arrastra contexto relevante entre conversaciones y canales automáticamente. Los nuevos hilos pueden abrir con un recap corto y relevante de trabajo previo relacionado, y Theo lleva el seguimiento de bucles abiertos para que los seguimientos posteriores retomen donde lo dejaste. La memoria está acotada por propietario y nunca se usa para entrenar modelos. Consulta Conversaciones y memoria.
  • Herramientas de operador para widgets embebibles — los widgets de chat embebibles ahora admiten toma de control humana en vivo, una vista de analíticas completa (sesiones, leads, conversión, geo) y captación de leads con exportación a CSV. Lista sesiones, lee transcripciones, toma o libera una conversación y publica mensajes de operador bajo /api/v1/iframes/{id}/conversations. Consulta la guía del widget embebible.

​
Mejorado

  • Las vinculaciones de habilidades por clave de API son explícitas por defecto. Cuando creas una nueva clave de API, empieza con cero habilidades invocables. Tú decides qué habilidades puede usar, cuando las quieras en ella. Los conjuntos de capacidades actuales de las claves existentes se preservan durante la migración — tus apps siguen funcionando sin ningún cambio por tu parte.
  • Prompt Builder escribe prompts compatibles con el validador a la primera. La nueva acción Write from Scratch conoce los requisitos del validador del canvas (definición de rol, restricciones explícitas) y las variables de plantilla en tiempo de ejecución disponibles ({{user_name}}, {{user_input}}, {{current_date}}, {{language}}, {{skill_name}}) para que el prompt generado pase la validación inmediatamente, sin una segunda ronda de edición.
  • Campos de descripción con autoajuste en los nodos Tool y Output. Las descripciones crecen verticalmente conforme escribes — o conforme Ask Theo las transmite — para que los resúmenes largos de capacidades sigan siendo totalmente visibles en lugar de cortarse a una línea.
  • Fiabilidad y cromado de la generación de documentos. La generación de PDF / DOCX / CSV / PPTX / XLSX produce un archivo correctamente renderizado en el playground, con una tarjeta de descarga limpia debajo de la respuesta del asistente (insignia de formato, tamaño de archivo, clic para descargar). Los mensajes de error en la rara ruta de reintento se mantienen neutrales respecto al proveedor y acordes a la marca.
  • Barra de herramientas más compacta en el editor de canvas. El atajo ▶ FULL (abrir la versión publicada en el Playground principal) ahora solo se renderiza una vez que el canvas se ha publicado, para que la barra se lea como un pipeline limpio TEST → COMPILE → PUBLISH hasta que tenga un destino que abrir.
  • El baseUrl por defecto del SDK ahora es https://www.hitheo.ai. Fija baseUrl explícitamente si apuntas a otro host.
  • El THEO_BASE_URL por defecto del servidor MCP ahora es https://www.hitheo.ai.
  • CompletionResponse.usage incluye prompt_tokens, completion_tokens, total_tokens y una bandera opcional cached. cached: true está presente en las respuestas servidas desde la caché semántica.
  • theo status CLI sondea tanto hitheo.ai como www.hitheo.ai y avisa cuando el baseUrl configurado es un destino de redirección.
  • El envoltorio del evento SSE error coincide con el envoltorio de error REST — { error: { message, type, code, request_id } }. Una sola ruta de manejo de errores para REST y streaming.
  • Los campos opcionales aceptan null en /completions, /chat/completions, /conversations, /playground/completions, /events, /images, /video, /code, /research, /documents, /audio/tts. Coincide con la norma del sector de tratar null como “campo omitido”.
  • EviInstance.stream() devuelve un TheoStream. for await sigue funcionando sin cambios; .cancel() y los metadatos finales ya están disponibles.

​
Corregido

  • Theo Reason y Theo Flash ya no derivan a generación de PDF en solicitudes de texto. Las llamadas a /api/v1/chat/completions y /api/v1/completions ahora siempre devuelven texto de razonamiento, incluso cuando tu prompt mencione palabras como “report”, “memo”, “brief”, “PDF”, “docx” o “presentation”. El comportamiento anterior secuestraba silenciosamente tu solicitud hacia generación de documentos y luego o agotaba el tiempo o devolvía un mensaje “couldn’t generate your PDF” — rompiendo a quienes consumen el SDK de OpenAI esperando choices[].message.content. La generación de documentos a través de la API de chat ya no se infiere a partir del fraseo del prompt — si quieres un documento, usa el endpoint dedicado /api/v1/documents.
  • La generación de documentos vuelve a producir descargas reales. Los PDF, archivos DOCX, presentaciones de PowerPoint, hojas de Excel y CSV de /api/v1/documents y del playground ahora se renderizan de forma fiable y exponen un download_url que funciona. Los modos de fallo anteriores (una respuesta enlatada “Theo couldn’t generate your PDF document” o un timeout 504 tras ~90 segundos) han desaparecido, y un upstream lento ahora cae a un artefacto de marcador de posición en lugar de hacer timeout en la solicitud.

​
Migración

La mayoría de quienes llaman a la API solo necesitan npm update @hitheo/sdk. Consulta la guía de actualización incluida en el README del SDK.

​
[0.3.0] — 2026-06-01

​
Añadido

  • Configuración streamIdleTimeoutMs del SDK (por defecto 120s) — las respuestas en streaming usan un timeout de inactividad (entre chunks) en lugar de un tope de duración total, para que un stream largo pero produciendo activamente nunca se corte a mitad de vuelo.
  • Nuevos tipos de error del SDK — TheoTimeoutError (lleva timeoutMs) y TheoCancelledError, además de un discriminador kind ("http" | "timeout" | "cancelled" | "network") en TheoApiError. TheoUsageError se lanza síncronamente para mal uso del SDK. Todas las subclases siguen siendo instanceof TheoApiError.
  • Resultados de jobs asíncronos tipados — JobStatus<T> es genérico con ResearchJobResult, VideoJobResult, ImageJobResult, DocumentJobResult; job<T>() y waitForJob<T>() son genéricos.
  • Objeto de opciones de waitForJob — { intervalMs, maxWaitMs, signal, onProgress } añade callback de progreso y cancelación por AbortSignal. La firma posicional heredada (id, intervalMs?, maxWaitMs?) sigue funcionando.
  • Tolerancia del parser SSE — las líneas event: / data: se aceptan con o sin el espacio final.
  • Nueva documentación — Timeouts y reintentos y Async Jobs.

​
Mejorado

  • El resultado de GET /api/v1/jobs/{id} está saneado — los jobs de video/imagen completados exponen model / engine con marca Theo en lugar del crudo providerId / modelId upstream.
  • La URL base compatible con OpenAI se documenta de forma consistente como https://www.hitheo.ai/api/v1.
  • Los timeouts ya no se reintentan en POST no idempotentes (complete, research, video) — elimina el riesgo de doble ejecución / doble facturación en generaciones lentas. Un timeout ahora lanza TheoTimeoutError en lugar de un TheoApiError(0) genérico.
  • Los modos asíncronos fallan rápido — pasar mode: "research" | "video" a complete() / stream() lanza TheoUsageError inmediatamente en lugar de quedar colgado hasta el timeout de la solicitud.

​
Migración

  • Si comparabas el timeout de polling de waitForJob mediante err.status === 408, cambia a err instanceof TheoTimeoutError (status ahora es 0, kind: "timeout").
  • Si ejecutabas research / video a través de complete() / stream(), muévete a theo.research() / theo.video() + theo.waitForJob(). Consulta Async Jobs.

​
[0.1.6] — 2026-04-17

​
Añadido

  • Theo Browser SDK — @hitheo/sdk expone theo.browser.* envolviendo la API de navegador headless gestionada (POST /api/v1/browser/sessions, refresco de vista en vivo, snapshot, end). Consulta Theo Browser (API) y Theo Browser (SDK).
  • Iframe de Theo Browser listo para embeber — cada nueva sesión incluye un embed_url que las apps de terceros pueden colocar en un iframe sin construir UI. Token firmado de corta duración; auto-refresco al desconectar.
  • Identificadores de voz TTS con marca — POST /api/v1/audio/tts ahora acepta theo-voice-classic, theo-voice-bright, theo-voice-storyteller, theo-voice-deep, theo-voice-warm, theo-voice-soft.

​
Mejorado

  • GET /api/v1/benchmarks ahora es un endpoint autenticado. Las respuestas incluyen Cache-Control: private.

​
[0.1.5] — 2026-04-17

​
Mejorado

  • Los READMEs publicados en cada paquete @hitheo en npm se actualizaron para reflejar la superficie en tiempo de ejecución actual, con guía de actualización para releases anteriores.

​
[0.1.4] — 2026-04-17

​
Añadido

  • Atestaciones firmadas de procedencia de GitHub en cada tarball de npm publicado. Verifica con npm audit signatures @hitheo/sdk @hitheo/mcp @hitheo/telegram @hitheo/whatsapp.

​
[0.1.3] — 2026-04-16

​
Mejorado

  • Superficie consistente con marca Theo en la documentación, el SDK y los adaptadores de canal.

​
[0.1.2] — 2026-04-15

​
Añadido

​
Mejorado

  • @hitheo/mcp, @hitheo/telegram, @hitheo/whatsapp ahora se publican con READMEs completos en npm.
  • La guía de seguridad del README de @hitheo/sdk actualizada — apunta a allowed_origins por clave y a la documentación de seguridad.

​
[0.1.1] — 2026-04-15

​
Añadido

  • Métodos del SDK para E.V.I. Canvas — canvases, canvas, createCanvas, updateCanvas, deleteCanvas, compileCanvas, testCanvas, publishCanvas.
  • Métodos del SDK para Webhooks — listWebhooks, createWebhook, updateWebhook, deleteWebhook, testWebhook, webhookDeliveries.
  • Métodos del SDK para Hooks — listHooks, createHook, updateHook, deleteHook, hookExecutions.
  • SDK de Events — publishEvent.
  • @hitheo/telegram — soporte de adjuntos (foto, voz, audio, documento), almacén de conversaciones conectable, verificación de X-Telegram-Bot-Api-Secret-Token, respuestas troceadas.
  • @hitheo/whatsapp — manejo de medios, verificación HMAC X-Hub-Signature-256 (helpers verifySignature, verifyWebhook), almacén de conversaciones, respuestas troceadas.
  • @hitheo/mcp — refresco del catálogo de herramientas, cargador de configuración de proyecto (theo.config.json|js|ts).

​
[0.1.0] — 2026-04-15

​
Añadido

​
Documentación

  • Documentación exhaustiva publicada en docs.hitheo.ai.
  • Referencia de API completa con especificación OpenAPI 3.1.
  • Guías de referencia del SDK, la CLI y MCP.
  • Inmersión profunda en Skills con guía de autoría para el marketplace.
  • Más de 10 guías que cubren E.V.I., integración con IDE y workflows.

​
[API v1] — 2026-03-28

​
Añadido

  • API de completions principal con enrutamiento multi-modelo.
  • Marketplace de habilidades con pipeline de revisión automatizado.
  • Soporte de E.V.I. (Embedded Virtual Intelligence).
  • SDK (@hitheo/sdk), CLI y servidor MCP (@hitheo/mcp).
  • Adaptadores de canal para Telegram y WhatsApp.
  • Automatización de workflows con horarios y disparadores de eventos.
  • Generación de imágenes, video, código, investigación y documentos.
  • TTS y STT de audio.
  • Facturación por token con sistema de créditos.