CLI e implementação de configurações
A CLI cria, valida, implementa, promove e reverte versões imutáveis da configuração do ChattyBox. Cada token de implementação está associado a exatamente um projeto existente e aos ambientes selecionados. Considere um ficheiro de configuração e um token associado a um projeto como um projeto ChattyBox gerido.
Estado de release e runtime
Os artefactos publicados são @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 e o SDK JavaScript separado @openstaticfish/chattybox@0.1.4. Suportam os campos ampliados com o contrato do backend 0.3.0. schemaVersion: "1" pertence a um sistema de versões distinto e não corresponde às versões dos pacotes (0.3.1) nem ao contrato do backend (0.3.0). status mostra a versão do ambiente, enquanto runtimeConfigVersionId identifica a última configuração aplicada ao runtime partilhado e pode ser diferente. Omitir mode seleciona crawl e preserva um maxDepth: 0 explícito. development apenas regista uma versão; preview e production partilham o runtime, o corpus e as chaves públicas do widget. A promoção de runtime mais recente prevalece; use projetos separados para isolamento real.
A configuração inicial e os comandos básicos abaixo estão disponíveis na CLI publicada. A referência alargada é suportada pelos pacotes CLI/config 0.3.1 e pelo contrato de backend 0.3.0 correspondente. O validador incluído abrange project, os campos de descoberta e agendamento, os controlos de idioma alargados, widget.icon e widget.showBranding; a validação local e a do backend rejeitam chaves desconhecidas.
A CLI é um programa ESM de linha de comandos que declara Node.js 20 ou superior. Por predefinição, bunx respeita o shebang de Node: instale Node ou selecione explicitamente Bun com bunx --bun @openstaticfish/chattybox-cli .... A CLI não é uma ferramenta para o navegador. A CI de consumo dos pacotes publicados cobre Node 20, 22 e 24 em Linux, não uma matriz geral de compatibilidade de sistemas operativos ou navegadores. Fixe uma versão testada dos pacotes na automação de produção; os exemplos sem versão utilizam o pacote instalado, em cache ou do registo, não o código-fonte deste repositório.
O que a configuração como código gere
A configuração controla o nome e a descrição do projeto, a persona e o comportamento de fallback do assistente, a descoberta e atualização do site, os idiomas e a apresentação do widget alojado. Uma implementação em preview ou produção aplica esses valores e coloca na fila uma atualização do corpus existente. Com o Bloqueio da configuração ativo, as definições geridas pela configuração são alteradas através de implementações versionadas, com uma exceção deliberada para a preferência de marca sujeita ao plano.
A criação inicial do projeto continua a ser um passo único no painel. Credenciais e dados operacionais ficam fora da configuração: chaves públicas e restrições de origem opcionais, ciclo de vida dos tokens de implementação, análises, conversas, lacunas de conteúdo, ações destrutivas e ficheiros de ícones carregados não são campos de configuração. Para um ícone personalizado declarativo, use um URL ou emoji. A configuração não contém intencionalmente um ID de projeto: o token secreto de implementação seleciona o único projeto que a recebe.
| Credencial | Âmbito | Segura no código do navegador? |
|---|---|---|
| Chave pública da API do widget | Conversa e configuração do widget | Sim; uma chave criada sem restrições funciona entre origens do navegador, enquanto uma chave preparada para um site pode já estar restrita. As restrições de origem exatas são uma proteção adicional opcional, não autenticação de visitantes. |
| Token de implementação da configuração | Implementação, promoção, reversão e estado da configuração para um projeto e ambientes selecionados | Não; guarde-o nos segredos locais ou da CI. |
Criar uma configuração
bunx @openstaticfish/chattybox-cli init
Este comando cria chattybox.config.json:
{
"schemaVersion": "1",
"assistant": {
"name": "Support"
},
"knowledge": {
"sources": [
{
"type": "website",
"url": "https://example.com"
}
]
},
"widget": {
"enabled": true
}
}
Use um caminho personalizado quando a configuração pertencer a um subdiretório:
bunx @openstaticfish/chattybox-cli init config/chattybox.config.json
Validar localmente ou na CI
bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json
A validação do código-fonte atual verifica a estrutura dos objetos, o nome obrigatório do assistente, os valores enumerados, URLs HTTP(S), limites inteiros, combinações de idiomas e cores hexadecimais de seis dígitos. knowledge pode ser omitido para validação local ou desenvolvimento, mas, quando presente, tem de conter exatamente uma fonte de website. Preview e produção exigem essa fonte. widget.enabled é obrigatório se widget estiver presente.
A validação lê apenas JSON; não carrega TypeScript, JSONC, YAML nem um esquema remoto. Não faz pedidos de rede, não verifica tokens nem direitos do plano e não aplica valores predefinidos. A validação local e a do backend rejeitam propriedades desconhecidas; o sucesso local não garante a implementação. O esquema v1 rejeita campos desconhecidos em todos os níveis, incluindo erros de escrita e extensões arbitrárias. As entradas de inclusão/exclusão têm de ser cadeias não vazias. runtime.locale é uma forma abreviada para idioma fixo sem substituições e não pode ser combinado com localeMode, defaultLocale ou allowLocaleOverride: true. O servidor verifica os direitos do plano e o âmbito do token.
Criar um token de implementação
Abra Definições do chatbot → Definições de programador e procure Tokens de implementação de configuração. Crie um token para os ambientes que o seu fluxo de trabalho tem de poder alterar. Copie imediatamente o token completo: o ChattyBox guarda um hash e apenas metadados de identificação e ciclo de vida limitados, e não pode voltar a mostrar o token completo.
O formulário seleciona inicialmente apenas development e não define uma data de expiração. Se necessário, selecione explicitamente preview ou production. No painel, pode optar por não definir uma data de expiração ou por definir 7, 30, 90 ou 365 dias; a API autenticada aceita um número inteiro de 1 a 365 dias ou a ausência de expiração. Cada projeto pode ter, no máximo, 20 tokens ativos e não expirados. Para substituir um token, crie outro, atualize a CI e revogue o anterior. Não existem comandos da CLI para iniciar sessão ou criar, listar ou revogar tokens.
Defina o token e o URL da API do widget. Em Instalar → Instalação no site, use data-api-url do snippet, quando disponível; caso contrário, obtenha o URL de implementação HTTP actions na configuração de implementação. Poderá ser necessário concluir primeiro a configuração da instalação:
export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'
Nunca faça commit do token. É uma credencial secreta Bearer para utilização apenas no servidor: guarde-a nos segredos encriptados do seu fornecedor de CI e não a inclua em código executado no navegador. As rotas de gestão não usam as restrições de origem do widget, não exigem um cabeçalho Origin e não permitem acesso CORS pelo navegador. O token não está associado a uma origem: qualquer pessoa que o obtenha pode chamar a API a partir de um servidor. As chaves públicas do widget não o substituem. Tokens em falta, malformados, expirados, revogados, sem autorização para o ambiente pedido ou inválidos por outro motivo devolvem HTTP 401 INVALID_TOKEN; também deixam de funcionar se o projeto ou o proprietário tiver sido removido ou estiver a ser eliminado.
Use a raiz de implementação HTTP actions ou o URL do widget terminado em /chat, não um URL de cliente .convex.cloud nem um endpoint completo /v1/config/deployments. A CLI remove barras finais e um /chat final e acrescenta a rota de gestão. HTTPS é obrigatório, exceto para localhost, 127.0.0.1 ou [::1]; o URL da API não pode conter credenciais, query ou fragmento. Verifique o destino antes de fornecer um segredo.
Bloqueio da configuração
Depois de verificar o fluxo de implementação, pode ativar o Bloqueio da configuração na mesma secção. É irreversível no painel, na CLI e na API pública atuais: não existe uma operação de desbloqueio suportada. Ativá-lo não cria um token nem implementa uma versão. Teste primeiro um fluxo funcional com token e configuração.
O bloqueio impede alterações no painel às definições de projeto/widget geridas pela configuração, o carregamento de ícones e operações manuais no corpus, como iniciar recolhas, eliminar páginas, limpar conteúdo ou regenerar embeddings. Não impede trabalho agendado nem a eliminação do projeto. A criação/revogação de tokens, a gestão de chaves públicas e as consultas operacionais continuam disponíveis.
A preferência de marca é a exceção: o controlo de marca no painel continua editável em projetos bloqueados. Ocultar a atribuição requer o plano Starter ou superior, também através da implementação da configuração. Se omitir widget.showBranding, mantém-se a preferência guardada (ou usa-se true se não existir); um valor explícito substitui-a na promoção de runtime seguinte. O runtime do plano Free continua a impor a apresentação da marca.
Implementar a configuração
A implementação cria uma versão imutável e promove-a para o ambiente selecionado. Implemente a configuração pretendida completa, não uma atualização parcial (patch): durante a promoção do runtime, os valores omitidos podem limpar ou repor definições anteriores do painel.
bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production
Os rótulos de ambiente não isolam runtimes. development apenas regista uma versão e um ponteiro (applied: false, indexingStatus: "not_required"). preview e production substituem as definições de runtime do mesmo projeto e usam o mesmo corpus e as mesmas chaves públicas do widget. Prevalece a promoção de runtime mais recente, mesmo que o estado do outro rótulo ainda aponte para uma versão anterior. Assim, um token com âmbito preview pode alterar um projeto que serve tráfego de produção. Para isolamento real, use projetos separados com os respetivos tokens e chaves.
As promoções de preview e production aplicam a configuração atomicamente e colocam um trabalho de recolha na fila (applied: true, indexingStatus: "pending"), mas não aguardam pela recolha nem pelos embeddings. As atualizações alteram as páginas existentes e pedem embeddings quando o conteúdo muda; não eliminam URLs antigos apenas por uma nova fonte ou filtro os omitir. O corpus não é um snapshot versionado: podem permanecer atualizações parciais após uma falha, que também não reverte a configuração aplicada. Os trabalhos registam o ID da versão de configuração, mas também leem definições de recolha mutáveis; evite implementações sobrepostas quando a consistência da indexação for importante.
Use --json na automação para receber o resultado da API, incluindo version._id, o ponteiro do ambiente, applied, indexingStatus e o ID do trabalho de recolha, quando for colocado na fila. Guarde version._id para promoções ou reversões posteriores: o número sequencial legível não é um valor válido para --version.
Substituição e limites do plano
A promoção do runtime limpa ou repõe valores geridos pela configuração que tenham sido omitidos, incluindo definições anteriores do painel:
| Valor omitido | Efeito no runtime |
|---|---|
project.description, prompt/perfil/mensagem de fallback do assistente | Limpa substituições guardadas; aplica-se o comportamento de fallback do runtime. |
runtime | Repõe o idioma automático, en como predefinição e a possibilidade de substituições de idioma. |
widget ou textos/tema/posição opcionais do widget | A omissão do objeto widget completo ativa o widget; se o objeto estiver presente, é respeitado o valor obrigatório de enabled. As substituições de apresentação omitidas são limpas separadamente, aplicando-se as predefinições do runtime. |
widget.icon | Repõe o ícone predefinido de tamanho médio. A promoção do runtime elimina o ficheiro do ícone carregado anteriormente, mesmo que seja fornecido um substituto declarativo. |
| Modo/filtros/agendamento da origem | O modo predefinido é crawl; os filtros omitidos são limpos e a atualização automática é desativada. As definições específicas do modo só se aplicam ao modo correspondente. |
widget.showBranding | Exceção: mantém a preferência guardada ou usa true se não existir. |
A versão de configuração imutável mantém o maxPages pedido, enquanto a promoção do runtime limita a configuração operacional de recolha a 100 000. Em cada execução, o worker limita a seleção ao menor entre o maxPages pedido e o maior valor entre a capacidade do fornecedor e o número de páginas já existentes no projeto; a admissão de páginas novas é verificada separadamente face à quota de páginas da conta. Se maxPages for omitido, o valor predefinido do pedido é o limite de páginas incluído no plano da conta: Free 10, Starter 150, Pro 5 000 e Business 25 000. Este valor predefinido não concede capacidade adicional nem aumenta os benefícios do plano; cada recolha volta a verificar o limite atual de páginas/PAYG e os limites mensais de atualização. A descoberta de sitemaps pode obter documentos sitemap e enumerar URLs antes da seleção. Por isso, a capacidade não constitui um limite de privacidade nem uma garantia contra pedidos de saída. Não é garantido que todas as páginas pedidas sejam indexadas.
No modo sitemap, se sitemapUrl não for especificado, a recolha tenta primeiro o sitemap detetado, depois /sitemap.xml e /sitemap_index.xml; se nenhum devolver URLs, usa o URL do site guardado.
A atualização automática diária e showBranding: false explícito exigem Starter ou superior. Free aceita atualizações automáticas semanais ou mensais. Estas verificações do plano ocorrem na promoção de preview/produção, incluindo reversões, e não na validação local nem no registo em development. Uma versão anteriormente válida pode falhar a promoção após uma alteração de plano. A promoção determina o plano a partir de dados do projeto/espaço de trabalho em cache no servidor, não de uma consulta em tempo real ao fornecedor de faturação; verifique separadamente a sincronização da faturação e a quota efetiva de recolha após alterações recentes ao plano ou PAYG.
Status, promoção e reversão
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 o ID opaco da versão de configuração: use version._id no JSON de deploy/promote/rollback ou activeVersion._id no JSON de status, não o número visível, um SHA do Git ou o hash da configuração. A reversão usa a mesma operação de backend que a promoção, não precisa de visar uma versão anterior e substitui o ponteiro e os metadados de promoção do ambiente selecionado; não existe histórico de promoções append-only. Para preview ou production, reaplica a configuração com os direitos atuais e enfileira uma nova atualização, em vez de restaurar o corpus histórico.
Substitua os IDs entre aspas nos exemplos por IDs reais pertencentes ao projeto do token. A reversão não seleciona automaticamente uma versão anterior. Implementações repetidas criam novas versões mesmo com configuração idêntica; promoções repetidas podem colocar novos trabalhos na fila.
status mostra a versão do ambiente e o respetivo ponteiro, não a configuração efetiva do runtime, diferenças face ao painel ou o progresso da recolha e dos embeddings. Um ambiente sem implementação mostra Environment version: none e devolve environment: null e activeVersion: null. runtimeConfigVersionId identifica a última configuração aplicada ao runtime partilhado e pode ser diferente após a promoção de outro ambiente. Consultas de estado bem-sucedidas também atualizam lastUsedAt do token e consomem capacidade do limite de pedidos de gestão. Verifique a indexação separadamente no painel. Se a configuração não estiver bloqueada, alterações posteriores no painel também podem mudar o runtime sem alterar o ID da última configuração aplicada.
Comandos, opções e erros
| Comando | Argumentos e efeito |
|---|---|
init [path] | Usa chattybox.config.json por predefinição; cria diretórios superiores e não substitui ficheiros existentes. |
validate [path] | Usa o mesmo caminho predefinido; lê e valida JSON sem acesso remoto. |
deploy | Exige --environment; aceita --config <path>; valida, cria e promove uma versão. |
promote, rollback | Exigem --environment e --version <opaque-id>; não leem uma configuração local. |
status | Exige --environment; não lê uma configuração local. |
Sem comando, help, --help, -h | Ajuda geral. Use chattybox --help, não chattybox deploy --help. |
--version, -v | Versão da CLI; distinta da opção --version da promoção. |
Os quatro comandos de gestão aceitam --token, --api-url e --json. As opções explícitas prevalecem sobre CHATTYBOX_DEPLOY_TOKEN e CHATTYBOX_API_URL. Prefira variáveis de ambiente secretas a tokens no histórico da shell ou nos argumentos do processo. As opções com valor aceitam --flag value ou --flag=value; --json é uma opção sem valor. Não há ambiente predefinido. Opções de gestão desconhecidas, duplicadas, vazias ou não aplicáveis ao comando são rejeitadas. Os comandos locais aceitam apenas um caminho posicional e rejeitam opções ou argumentos adicionais.
Não existem opções --dry-run, --wait, --force, --project, de mensagem ou de concorrência otimista. A API HTTP suporta campos de versão esperada, mas a CLI não os envia. Execute as implementações de CI para o mesmo projeto sequencialmente.
Comandos executáveis bem-sucedidos terminam com código 0. Erros de ficheiro, JSON, validação, argumentos, transporte, leitura da resposta ou HTTP terminam com código 1 e uma mensagem ChattyBox: ... em stderr. --json só formata resultados bem-sucedidos; os erros não são JSON. Os erros da API incluem o estado HTTP e o código de erro quando fornecidos; respostas bem-sucedidas que não sejam JSON são rejeitadas. A CLI não tem repetição automática, polling nem timeout configurado. Após uma falha de transporte, verifique o estado antes de repetir: o servidor pode já ter concluído a implementação.
As rotas de gestão são POST /v1/config/deployments (201), POST /v1/config/deployments/promote e /rollback (200), e GET /v1/config/deployments/status?environment=... (200). A resposta HTTP bem-sucedida é envolvida em { "data": ... }; o JSON da CLI remove esse invólucro. Os erros usam normalmente { "error": { "code": ..., "message": ... } }: 401 INVALID_TOKEN, 404 NOT_FOUND para uma versão inexistente ou de outro projeto, 409 CONFIG_CONFLICT, 413 BODY_TOO_LARGE, 422 INVALID_CONFIG ou 500 INTERNAL_ERROR. IDs tipados malformados dão 422, não necessariamente 404. O limite do corpo do pedido é 262.144 bytes. Todas as rotas de gestão partilham um limite de 20 pedidos por minuto por token; as respostas 429 usam o formato de limite partilhado e o cabeçalho Retry-After. Atualmente, a ausência completa de corpo num POST resulta em 500, ao contrário de JSON malformado (422).
Fluxos de trabalho de CI/CD
Adicione CHATTYBOX_DEPLOY_TOKEN como um segredo encriptado com âmbito de produção no fornecedor de CI. Adicione CHATTYBOX_API_URL como segredo ou variável, usando o URL de implementação HTTP actions ou, quando disponível, o URL da API do widget em Instalar → Instalação no site. Execute a validação em pull requests, mas limite a implementação de produção à branch predefinida protegida ou a um ambiente de implementação aprovado.
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
Use um segredo de produção associado ao ambiente e exija aprovação para a implementação quando o repositório o permitir. A CLI regista as variáveis comuns de commit e branch da CI juntamente com a versão imutável.
GitLab CI/CD
Guarde os dois valores em Settings → CI/CD → Variables. Proteja o token de implementação, mascare-o e limite-o ao ambiente production.
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
O GitLab disponibiliza automaticamente CHATTYBOX_DEPLOY_TOKEN e CHATTYBOX_API_URL ao job através dos nomes das variáveis. Use uma branch predefinida protegida para que as variáveis protegidas não fiquem disponíveis para branches não fidedignas. Os exemplos no contentor Bun usam explicitamente --bun, pelo que não dependem de uma instalação separada de Node; verifique a versão fixada do Bun/da imagem na CI.
Bitbucket Pipelines
Adicione os dois valores como variáveis de implementação em Repository settings → Pipelines → Deployments → Production. Marque o token de implementação como protegido.
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
Substitua main se a sua branch predefinida tiver outro nome. O Bitbucket disponibiliza variáveis de implementação apenas nos passos associados a esse ambiente. A CLI não tem um mapeamento específico para os metadados BITBUCKET_*; recorre ao Git local para o commit e a branch, que pode não ter nome num checkout detached.
Secções da configuração
| Secção | Finalidade |
|---|---|
schemaVersion | Seleciona o contrato público de configuração. Atualmente é suportada a versão 1. |
project | Metadados opcionais do projeto, como a descrição no painel. |
assistant | Define o nome do assistente, uma persona incorporada ou um prompt de sistema personalizado e a mensagem de fallback. |
knowledge.sources | Seleciona a descoberta por página inicial, sitemap, URLs manuais ou rastreio, bem como limites, filtros e calendário de atualização. |
runtime | Controla o idioma automático ou fixo, o idioma predefinido e as substituições de idioma ao nível da página. |
widget | Controla a ativação, a posição, os textos, as cores e a apresentação do ícone predefinido, emoji ou URL. |
Personas
Defina promptProfile como default, support, sales ou sarcastic para utilizar as instruções de persona mantidas pelo produto. Para uma persona personalizada, escolha custom e forneça systemPrompt. Se indicar um perfil incorporado e systemPrompt, prevalece o prompt explícito.
Descoberta de conhecimento
Este fragmento de configuração alargada requer os tipos de configuração publicados 0.3.1 e o contrato de backend 0.3.0 correspondente. O agendamento diário requer Starter ou superior; maxPages: 500 guarda um pedido que continua sujeito à capacidade efetiva da execução.
{
"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"
}
Modos suportados:
homepage: seleciona apenasurlpara esta atualização; não elimina páginas existentes.sitemap: usasitemapUrl; um sitemap explícito que não devolva URLs faz falhar o trabalho. Se for omitido, tenta um sitemap detetado, depois/sitemap.xmle/sitemap_index.xmle, se nenhum devolver URLs, o URL guardado do site.manual: indexa a lista não vaziamanualUrls.crawl: tenta os sitemaps convencionais e depois segue ligações a partir deurlatémaxDepth(predefinição3).
include e exclude usam correspondência de substrings do URL sensível a maiúsculas e minúsculas, não sintaxe glob ou regex. Qualquer correspondência de inclusão admite um URL; qualquer correspondência de exclusão rejeita-o, mesmo que tenha sido incluído. Listas vazias não filtram. Os filtros também se aplicam à página inicial e à seleção manual.
maxPages tem de ser um inteiro positivo; a versão imutável mantém o valor pedido, enquanto a configuração do runtime é limitada e a seleção está sujeita às verificações de capacidade descritas acima. A descoberta de sitemaps pode enumerar URLs antes da seleção. maxDepth tem de ser um inteiro entre 0 e 20 e controla o recurso ao rastreio de ligações, não a enumeração de sitemaps. Omitir mode seleciona crawl e preserva um maxDepth explícito, incluindo zero. autoRescrape: true requer rescrapeInterval: "daily", "weekly" ou "monthly"; um intervalo isolado não ativa o agendamento. Mensal significa 30 dias e o agendador pode executar depois da hora prevista.
Validação do idioma e do widget
Os códigos de idioma suportados são en, de, fr, es, it, nl, pl, pt, sv, fi, et, cs, cy e id. localeMode é auto ou fixed; o modo fixo exige defaultLocale. allowLocaleOverride pode ser configurado independentemente. A forma abreviada runtime.locale seleciona o modo fixo e desativa substituições; a validação local atual rejeita a combinação com localeMode, defaultLocale ou allowLocaleOverride: true.
As posições do widget são bottom-right, bottom-left, top-right e top-left. As três cores do tema usam #RRGGBB, não hexadecimal abreviado, nomes de cores ou alfa. Os ícones usam default, emoji (cadeia emoji não vazia) ou url (um url HTTP(S)), com tamanho opcional small, medium ou large. A validação não obtém os URLs dos ícones, não verifica tipos MIME de imagem nem exige que a cadeia contenha exatamente um emoji. A validação de URLs de fontes e ícones verifica a sintaxe e o protocolo, não a acessibilidade nem a autorização de recolha. A descrição, o prompt e o fallback do assistente, o título e a mensagem de boas-vindas do widget são opcionais, mas não podem estar vazios quando fornecidos; omita-os para limpar as substituições.
Auxiliar de configuração tipada
Instale o pacote de configuração ao criar ferramentas TypeScript separadas em torno do 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 },
});
A CLI lê ficheiros JSON. defineConfig() serve para aplicações tipadas ou ferramentas de build; não permite carregar ficheiros TypeScript diretamente na CLI. Tanto defineConfig(config) como validateConfig(config) validam de forma síncrona, lançam um Error normal na primeira falha e devolvem o mesmo objeto sem o clonar, congelar, converter ou preencher com valores predefinidos. O pacote exporta tipos TypeScript e estas funções, não um documento JSON Schema nem um URL $schema. O pacote publicado 0.3.1 disponibiliza suporte TypeScript para os campos alargados acima.
Para uma integração funcional em produção, use o widget alojado ou crie uma interface personalizada com o SDK JavaScript.