Saltar al contenido principal

CLI y despliegue de configuración

Los artefactos CLI/config publicados en la versión 0.3.1 implementan el contrato de configuración/backend 0.3.0 y rechazan las claves desconocidas tanto localmente como en el backend.

La CLI crea, valida, despliega, promociona y revierte versiones inmutables de la configuración de ChattyBox. Los tokens de despliegue están limitados a un proyecto y a los entornos seleccionados, por lo que el mismo flujo sirve para el desarrollo local y CI.

Estado de versión y runtime​

El registro público ofrece @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 y el SDK JavaScript independiente @openstaticfish/chattybox@0.1.4. Los paquetes CLI y config publicados en la versión 0.3.1 admiten los campos ampliados (proyecto, descubrimiento/programación, controles de idioma ampliados, widget.icon, widget.showBranding) conforme al contrato de configuración/backend 0.3.0. schemaVersion: "1" es independiente de las versiones de paquete.

La CLI es un programa ESM de línea de comandos que declara Node.js 20 o posterior; no es una herramienta de navegador. bunx respeta por defecto su shebang de Node, así que instala Node o selecciona Bun explícitamente con bunx --bun @openstaticfish/chattybox-cli .... El CI para consumidores de los paquetes publicados cubre Node 20, 22 y 24 en Linux, no una matriz general de sistemas operativos o navegadores. Fija una versión probada del paquete en la automatización de producción: los ejemplos sin versión usan el paquete instalado, en caché o del registro, no el código fuente de este repositorio.

Qué gestiona la configuración como código​

La configuración controla el nombre y la descripción del proyecto, la persona y el comportamiento alternativo del asistente, el descubrimiento y la actualización del sitio, el idioma y la presentación del widget alojado. Una implementación en preview o production aplica esos valores y pone en cola una actualización del corpus existente. Con Config-as-code lock, los ajustes gestionados se cambian mediante despliegues versionados, salvo la preferencia de marca, que sigue sujeta al plan.

La creación inicial del proyecto requiere un paso único en el panel. Las claves públicas y sus restricciones opcionales de origen, el ciclo de vida de los tokens de despliegue, la analítica, conversaciones y brechas, las acciones destructivas y los archivos de iconos subidos no son campos de configuración. Usa una URL o un emoji para un icono personalizado declarativo. El archivo no contiene un ID de proyecto: el token secreto selecciona el único proyecto que recibe la configuración.

La clave pública sirve para el chat y la configuración del widget y puede estar en código del navegador; una clave sin restricciones funciona entre orígenes y una preparada para un sitio puede estar ya restringida. Las restricciones exactas de origen son opcionales y no autentican visitantes. El token de despliegue sirve para desplegar, promocionar, revertir y consultar el estado de un proyecto y los entornos autorizados; mantenlo en secretos locales o de CI, nunca en el navegador.

Crear una configuración​

bunx @openstaticfish/chattybox-cli init

Esto crea chattybox.config.json:

{
"schemaVersion": "1",
"assistant": {
"name": "Support"
},
"knowledge": {
"sources": [
{
"type": "website",
"url": "https://example.com"
}
]
},
"widget": {
"enabled": true
}
}

Utiliza una ruta personalizada si la configuración debe estar en un subdirectorio:

bunx @openstaticfish/chattybox-cli init config/chattybox.config.json

Validar localmente o en CI​

bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json

La validación del código fuente actual comprueba la estructura de los objetos, el nombre obligatorio del asistente, valores enumerados, URL HTTP(S), límites enteros, combinaciones de idioma y colores hexadecimales de seis dígitos. knowledge puede omitirse en la validación local o desarrollo, pero si está presente debe contener exactamente una fuente web; preview y production la requieren. Si widget está presente, widget.enabled es obligatorio.

La validación solo lee JSON, no TypeScript, JSONC, YAML ni un esquema remoto. No hace solicitudes de red, no comprueba el token ni los permisos del plan y no aplica valores predeterminados. La validación local y la del backend rechazan claves desconocidas en todos los niveles; el éxito local no garantiza el despliegue. Las entradas include y exclude deben ser cadenas no vacías. runtime.locale abrevia el modo fijo con anulaciones desactivadas y no puede combinarse con localeMode, defaultLocale ni allowLocaleOverride: true. El servidor comprueba el plan y el alcance del token.

Crear un token de despliegue​

En el proyecto, abre Configuración del chatbot → Configuración de desarrollo → Tokens de despliegue de configuración y crea un token para los entornos que tu flujo de trabajo pueda modificar. Copia inmediatamente el valor completo: solo se muestra una vez. ChattyBox conserva un hash y metadatos limitados de identificación y ciclo de vida, pero no puede volver a mostrar el valor completo.

El formulario selecciona inicialmente solo development y no establece caducidad. Selecciona explícitamente preview o production cuando lo necesites. El panel ofrece sin caducidad o 7, 30, 90 o 365 días; la API autenticada acepta un entero de 1 a 365 días o la omisión para no caducar. Un proyecto admite como máximo 20 tokens activos y no caducados. Para rotar uno, crea un reemplazo, actualiza CI y revoca el anterior. La CLI no tiene comandos de inicio de sesión ni de creación, listado o revocación de tokens.

Establece el token y la URL de la API del widget. En Instalar → Instalación en el sitio web, usa el valor data-api-url del fragmento cuando esté disponible; en caso contrario, obtén la URL del despliegue de las acciones HTTP en tu configuración de despliegue. Es posible que el flujo de instalación requiera que la configuración esté lista primero:

export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'

Usa la URL raíz del despliegue de HTTP Actions o la URL del widget terminada en /chat, no una URL de cliente .convex.cloud ni el endpoint completo de gestión. Se requiere HTTPS, salvo para localhost, 127.0.0.1 y [::1]. La URL no debe incluir credenciales, parámetros de consulta ni fragmentos. Verifica el host de destino antes de enviar el secreto.

No hagas commit del token ni lo expongas en código del navegador. Guárdalo como secreto solo del servidor o en el almacén de secretos cifrados de tu proveedor de CI.

El token de despliegue se autentica con Authorization: Bearer ...; las claves públicas del widget no pueden sustituirlo. Las rutas de administración no aplican las restricciones de origen del widget, no requieren una cabecera Origin y no ofrecen acceso CORS desde el navegador. Este secreto no está vinculado a un origen: cualquiera que lo tenga puede llamar a la API desde un servidor. Los tokens ausentes, malformados, caducados, revocados, para otro entorno o inválidos devuelven HTTP 401 INVALID_TOKEN; también dejan de funcionar si falta su proyecto o propietario o están en proceso de eliminación.

Tras comprobar el flujo de despliegue, puedes activar Config-as-code lock en esa misma sección. Es irreversible mediante el panel, la CLI y la API pública actuales: no existe una operación de desbloqueo admitida. Activarlo no crea un token ni despliega una versión. Conserva un flujo de tokens probado antes de bloquear.

El bloqueo impide modificar desde el panel los ajustes gestionados del proyecto y widget, subir iconos y realizar operaciones manuales del corpus como extraer, eliminar páginas, borrar contenido y regenerar embeddings. No detiene los trabajos programados ni la eliminación del proyecto. Siguen disponibles la gestión de tokens y claves públicas y las consultas operativas. La marca es la excepción: su control sigue siendo editable, sujeto al plan. Ocultar la atribución requiere Starter o superior, incluso mediante configuración; en Free sigue mostrándose. Omitir widget.showBranding conserva la preferencia guardada o usa true si no existe; un valor explícito la sobrescribe en la siguiente promoción de runtime.

Desplegar la configuración​

El despliegue crea una versión inmutable y la promociona al entorno seleccionado:

bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production

development solo registra una versión sin aplicarla. preview y production comparten el mismo runtime, corpus y claves públicas: gana la última promoción de runtime, sin aislamiento entre entornos. Por tanto, un token limitado a preview también puede cambiar el runtime de un proyecto que atiende tráfico de producción. Para aislarlos de verdad, usa proyectos separados con sus respectivos tokens y claves públicas. La promoción aplica la configuración y pone un scrape en cola, sin esperar a que termine el scrape o la generación de embeddings ni crear una instantánea del corpus. Las URL antiguas no se eliminan por omitirlas y un fallo no revierte la configuración.

La aplicación y la puesta en cola son atómicas, pero pueden quedar actualizaciones parciales si falla el trabajo. Los trabajos registran el ID de versión y también leen ajustes de scraping modificables; evita desplegar versiones simultáneamente cuando importe la consistencia de la indexación.

Usa --json en las automatizaciones para recibir el resultado de la API, incluidos version._id, el puntero del entorno, applied, indexingStatus y el ID del trabajo de scrape cuando se pone uno en cola. En el resultado JSON de status, el campo de ID correspondiente es activeVersion._id.

Reemplazo de configuración y límites de páginas​

Despliega la configuración completa deseada, no un parche. Una promoción a preview o production borra o restablece los valores gestionados por la configuración que se omitan, incluidos los ajustes anteriores del panel:

Valor omitidoEfecto en runtime
project.description, prompt/perfil/mensaje alternativo del asistenteBorra las personalizaciones guardadas; se aplica el comportamiento alternativo del runtime.
runtimeRestablece el idioma automático, en como predeterminado y permite las anulaciones de idioma.
widget o texto, tema o posición opcionales del widgetSi se omite widget, se habilita el widget. Si el objeto widget está presente, se respeta su valor obligatorio enabled. Las personalizaciones de presentación omitidas se borran para aplicar los valores predeterminados del runtime.
widget.iconRestablece el icono predeterminado de tamaño mediano. La promoción elimina el archivo de icono que se hubiera subido previamente, incluso si se proporciona un reemplazo declarativo.
Modo, filtros o programación de la fuenteEl modo pasa a crawl, se borran los filtros omitidos y se desactiva la actualización automática. Los ajustes específicos de un modo solo se aplican cuando se selecciona ese modo.
widget.showBrandingExcepción: si se omite, conserva la preferencia guardada o usa true si no existe; un valor explícito la sobrescribe en la siguiente promoción de runtime.

La versión de configuración inmutable conserva el valor solicitado de maxPages, mientras que la configuración de scrape aplicada al runtime tiene un límite de 100.000. Para seleccionar páginas, el worker tiene en cuenta el valor solicitado y el mayor entre la capacidad del proveedor y el número de páginas existentes del proyecto; la admisión de páginas nuevas se comprueba por separado según el límite de páginas del propietario. La detección de sitemaps puede descargar sus documentos y enumerar URL antes de seleccionarlas: la capacidad no es una garantía de privacidad ni un límite a las solicitudes salientes. Tampoco garantiza que se indexen todas las páginas solicitadas. Si se omite maxPages, el valor solicitado predeterminado corresponde a la cuota de páginas por cuenta incluida en el plan: Free 10, Starter 150, Pro 5.000 y Business 25.000. Esto no añade capacidad al conjunto del propietario ni derechos del plan; cada scrape vuelve a comprobar por separado la cuota actual de páginas/PAYG y los límites mensuales de actualización.

En modo sitemap, una sitemapUrl explícita que no devuelva URL provoca un error. Si se omite sitemapUrl, primero se intenta usar cualquier sitemap detectado; después, /sitemap.xml, luego /sitemap_index.xml y, por último, la URL guardada del sitio web si ninguno devuelve URL.

Estado, promoción y reversión​

bunx @openstaticfish/chattybox-cli status --environment production

bunx @openstaticfish/chattybox-cli promote \
--version '<config-version-id>' \
--environment production

bunx @openstaticfish/chattybox-cli rollback \
--version '<known-good-config-version-id>' \
--environment production

--version usa el ID opaco de versión, no el número visible: obténlo de version._id en el JSON de deploy, promote o rollback, o de activeVersion._id en el JSON de status. Rollback usa la misma operación que la promoción, puede apuntar a cualquier versión y reaplica con los límites y permisos actuales; no restaura el contenido histórico exacto.

Las actualizaciones automáticas diarias y widget.showBranding: false requieren Starter o superior. Free permite actualizaciones automáticas semanales o mensuales. Estas comprobaciones se realizan al promover a preview o production, incluido el rollback, no durante la validación local ni al registrar una versión en development. Una versión que antes era válida puede dejar de promocionarse después de un cambio de plan.

La promoción determina el plan a partir de datos del proyecto o espacio de trabajo guardados en caché en el servidor, no mediante una consulta en vivo al proveedor de facturación. Comprueba por separado la sincronización de facturación y la cuota efectiva de scraping al investigar un cambio reciente de plan o PAYG.

Rollback no selecciona automáticamente una versión anterior. Conserva los registros inmutables, pero sobrescribe el puntero del entorno y sus metadatos de promoción; no existe un historial de eventos de promoción que solo admita añadidos. Un rollback de preview o production vuelve a aplicar la configuración y pone otra actualización en cola. Los despliegues repetidos crean versiones nuevas incluso con configuración idéntica y las promociones repetidas pueden generar nuevos trabajos.

status muestra la versión y el resumen del puntero de la etiqueta elegida, no la configuración efectiva, las diferencias respecto al panel ni el progreso del scraping o los embeddings. Una etiqueta sin despliegue muestra Environment version: none y devuelve environment: null y activeVersion: null. runtimeConfigVersionId identifica la última configuración aplicada al runtime compartido y puede diferir; promover a development no lo cambia. Sin bloqueo, una edición posterior en el panel también puede cambiar campos del runtime sin cambiar ese ID. Una consulta de estado satisfactoria actualiza lastUsedAt del token y consume capacidad del límite de solicitudes de gestión. Comprueba la indexación por separado en el panel.

Comandos, opciones y errores​

init [path] crea también los directorios necesarios y no sobrescribe archivos. validate [path] valida JSON sin acceso remoto; ambos usan chattybox.config.json por defecto. deploy requiere --environment y acepta --config <path>. promote y rollback requieren --environment y --version <opaque-id>; status requiere --environment. Estos tres últimos no leen una configuración local. Usa chattybox --help para la ayuda general y --version o -v para la versión de la CLI; esta opción es distinta de --version para promocionar o revertir.

Los cuatro comandos de gestión aceptan --token, --api-url y --json. Las opciones explícitas prevalecen sobre CHATTYBOX_DEPLOY_TOKEN y CHATTYBOX_API_URL; prefiere variables secretas a tokens en el historial del shell o los argumentos del proceso. No hay entorno predeterminado. Se rechazan opciones desconocidas, duplicadas, vacías o inaplicables; los comandos locales solo aceptan una ruta posicional y rechazan opciones y argumentos adicionales. No existen --dry-run, --wait, --force, --project, opciones de mensaje ni de concurrencia optimista. La API HTTP admite campos de versión esperada, pero la CLI no los envía: serializa los despliegues de CI al mismo proyecto.

Los comandos correctos terminan con código 0; los errores de archivo, JSON, validación, argumentos, transporte, lectura de respuesta o HTTP terminan con código 1. --json solo formatea resultados correctos, no errores. La CLI no reintenta ni consulta el estado automáticamente y no configura un tiempo de espera de solicitud. Tras un fallo de transporte, comprueba el estado antes de reintentar: el servidor puede haber confirmado ya el despliegue.

Las rutas de gestión comparten un límite de 20 solicitudes por minuto por token y las respuestas 429 incluyen Retry-After. Entre los errores están 401 INVALID_TOKEN, 404 NOT_FOUND, 409 CONFIG_CONFLICT, 413 BODY_TOO_LARGE, 422 INVALID_CONFIG y 500 INTERNAL_ERROR; un ID tipado malformado devuelve 422, no necesariamente 404. El cuerpo de la solicitud se limita a 262.144 bytes. Actualmente, un POST sin cuerpo devuelve 500, a diferencia de un JSON malformado (422).

Flujos de trabajo de CI/CD​

Añade CHATTYBOX_DEPLOY_TOKEN como secreto cifrado con alcance de producción en tu proveedor de CI. Añade CHATTYBOX_API_URL como secreto o variable usando la URL de la API del widget en Instalar → Instalación en el sitio web, si está disponible, o la URL del despliegue de las acciones HTTP. Ejecuta la validación en los pull requests, pero restringe el despliegue de producción a tu rama predeterminada protegida o a un entorno de despliegue aprobado.

GitHub Actions​

name: Deploy ChattyBox configuration

on:
pull_request:
push:
branches: [main]

jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- uses: actions/setup-node@v6
with:
node-version: 24
- run: bunx @openstaticfish/chattybox-cli validate

deploy:
if: github.event_name == 'push'
needs: validate
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- uses: actions/setup-node@v6
with:
node-version: 24
- name: Validate and deploy
env:
CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
run: |
bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli deploy --environment production --json

Usa un secreto de producción limitado al entorno y exige aprobación para el despliegue cuando tu repositorio lo admita. La CLI registra las variables habituales de CI relacionadas con el commit y la rama junto con la versión inmutable.

GitLab CI/CD​

Guarda ambos valores en Settings → CI/CD → Variables. Protege el token de despliegue, enmascáralo y limita su alcance al entorno production.

.gitlab-ci.yml
image: oven/bun:1

validate_chattybox:
stage: test
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
script:
- bunx --bun @openstaticfish/chattybox-cli validate

deploy_chattybox:
stage: deploy
environment: production
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
- bunx --bun @openstaticfish/chattybox-cli validate
- bunx --bun @openstaticfish/chattybox-cli deploy --environment production --json

GitLab expone automáticamente CHATTYBOX_DEPLOY_TOKEN y CHATTYBOX_API_URL al trabajo usando sus nombres de variable. Usa una rama predeterminada protegida para que las variables protegidas no estén disponibles para ramas que no sean de confianza. Los ejemplos del contenedor Bun usan --bun para no depender de una instalación separada de Node; verifica la versión fijada de Bun y de la imagen en CI.

Bitbucket Pipelines​

Añade ambos valores como variables de despliegue en Repository settings → Pipelines → Deployments → Production. Marca el token de despliegue como protegido.

bitbucket-pipelines.yml
image: oven/bun:1

pipelines:
pull-requests:
'**':
- step:
name: Validate ChattyBox configuration
script:
- bunx --bun @openstaticfish/chattybox-cli validate
branches:
main:
- step:
name: Deploy ChattyBox configuration
deployment: Production
script:
- bunx --bun @openstaticfish/chattybox-cli validate
- bunx --bun @openstaticfish/chattybox-cli deploy --environment production --json

Sustituye main si tu rama predeterminada tiene otro nombre. Bitbucket inyecta las variables de despliegue únicamente en los pasos asociados a ese entorno de despliegue. La CLI no tiene un mapeo específico de metadatos BITBUCKET_*; recurre a Git local para el commit y la rama, que puede no tener nombre en un checkout desacoplado.

Secciones de configuración​

SecciónFinalidad
schemaVersionSelecciona el contrato público de configuración. Actualmente se admite la versión 1.
projectMetadatos opcionales del proyecto, como su descripción en el panel.
assistantAsigna un nombre al asistente y define una persona integrada o instrucción personalizada y el mensaje alternativo.
knowledge.sourcesSelecciona el modo de descubrimiento, límites, filtros y calendario de actualización.
runtimeControla el idioma automático o fijo, el idioma predeterminado y las anulaciones desde la página.
widgetControla la activación, posición, textos, colores e icono predeterminado, emoji o URL.

Personas y descubrimiento​

Este ejemplo es una entrada de knowledge.sources, no una configuración completa. Requiere los paquetes CLI/config publicados en 0.3.1 y el contrato de backend 0.3.0 correspondiente. La actualización diaria requiere Starter o superior; maxPages: 500 es una solicitud sujeta a la capacidad disponible, no una garantía de indexación.

{
"type": "website",
"url": "https://docs.example.com",
"mode": "sitemap",
"sitemapUrl": "https://docs.example.com/docs-sitemap.xml",
"include": ["/docs/"],
"exclude": ["/private/"],
"maxPages": 500,
"autoRescrape": true,
"rescrapeInterval": "daily"
}

Usa promptProfile con default, support, sales o sarcastic para las instrucciones integradas, o custom con systemPrompt para una persona personalizada. Si se indican un perfil integrado y systemPrompt, prevalece la instrucción explícita.

Los modos de fuente son homepage (solo url para esa actualización, sin eliminar páginas existentes), sitemap, manual (lista manualUrls no vacía) y crawl (primero sitemaps convencionales y luego enlaces hasta maxDepth). include y exclude buscan subcadenas de URL distinguiendo mayúsculas, no usan glob ni expresiones regulares; cualquier exclusión prevalece. Las listas vacías no filtran y los filtros también se aplican a la página inicial y las URL manuales.

maxPages debe ser un entero positivo y está sujeto a los límites y comprobaciones anteriores. maxDepth debe ser un entero de 0 a 20 y limita el seguimiento alternativo de enlaces, no la enumeración de sitemaps. Si se omite mode, se elige crawl y se conserva un maxDepth explícito, incluido cero. autoRescrape: true requiere rescrapeInterval: "daily", "weekly" o "monthly"; indicar solo el intervalo no activa la programación. Mensual significa 30 días y el programador puede ejecutarse después de la hora prevista.

Validación de idioma y widget​

Los códigos admitidos son en, de, fr, es, it, nl, pl, pt, sv, fi, et, cs, cy e id. localeMode admite auto o fixed; el modo fijo requiere defaultLocale. allowLocaleOverride se configura por separado, sujeto a las restricciones de la abreviatura runtime.locale indicadas arriba.

Las posiciones son bottom-right, bottom-left, top-right y top-left. Los tres colores usan #RRGGBB, no hex abreviado, nombres de colores ni alfa. Los iconos usan default, emoji (cadena emoji no vacía) o url (URL HTTP(S)), con tamaño opcional small, medium o large. La validación no descarga las URL de iconos, comprueba su tipo MIME ni exige exactamente un emoji. La validación de URL comprueba sintaxis y protocolo, no accesibilidad ni permiso de rastreo. La descripción, el prompt o mensaje alternativo del asistente y el título o bienvenida del widget deben ser cadenas no vacías si se proporcionan; omítelos para eliminar las personalizaciones.

Función auxiliar de configuración tipada​

Instala el paquete de configuración si vas a crear herramientas TypeScript independientes basadas en el esquema:

bun add -d @openstaticfish/chattybox-config
import { defineConfig } from '@openstaticfish/chattybox-config';

const config = defineConfig({
schemaVersion: '1',
assistant: { name: 'Support' },
knowledge: {
sources: [{ type: 'website', url: 'https://docs.example.com' }],
},
widget: { enabled: true },
});

La propia CLI lee archivos JSON. defineConfig() está destinada a aplicaciones tipadas o herramientas de compilación; no permite que la CLI cargue directamente archivos TypeScript. Tanto defineConfig(config) como validateConfig(config) validan de forma síncrona, lanzan un Error ordinario en el primer fallo y devuelven el mismo objeto sin clonarlo, congelarlo, convertirlo ni insertar valores predeterminados. El paquete exporta tipos TypeScript y estas funciones, no un documento JSON Schema ni una URL $schema. La versión publicada 0.3.1 admite los campos ampliados anteriores.

Para una integración funcional en producción hoy, utiliza el widget alojado o crea una interfaz personalizada con el SDK de JavaScript.