CLI et déploiement de configuration

La CLI crée, valide, déploie, promeut et restaure des versions immuables de la configuration ChattyBox. Les jetons de déploiement sont limités à un projet et aux environnements sélectionnés, ce qui rend le même flux adapté au développement local et à la CI.

Créer une configuration

bunx @openstaticfish/chattybox-cli init

Cette commande crée chattybox.config.json :

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

Utilisez un chemin personnalisé lorsque la configuration doit se trouver dans un sous-répertoire :

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

Valider localement ou dans la CI

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

La validation vérifie le schéma, le nom obligatoire de l'assistant, les types de sources pris en charge, les URL HTTP des sources, les limites de pages positives et les couleurs du widget. Une validation réussie ne déploie ni ne modifie aucun état distant.

Créer un jeton de déploiement

Ouvrez l'onglet Settings du projet, recherchez Config deployment tokens et créez un jeton pour les environnements que votre flux de travail peut modifier. Copiez-le immédiatement ; ChattyBox ne stocke que son hash et ne peut plus l'afficher.

Définissez le jeton et l'URL d'API du widget depuis l'onglet Embed du projet :

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

Ne commitez jamais le jeton. Stockez-le dans le gestionnaire de secrets chiffrés de votre fournisseur CI.

Après avoir vérifié le flux de déploiement, activez Config-as-code lock dans la même section des paramètres. Le verrou désactive les modifications de configuration et du corpus depuis le tableau de bord, de sorte que seuls les jetons de déploiement avec la portée appropriée puissent modifier le runtime. La création et la révocation des jetons restent disponibles si un identifiant CI doit faire l’objet d’une rotation.

Déployer la configuration

Le déploiement crée une version immuable et la promeut dans l'environnement sélectionné :

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

Les promotions vers development et preview sont enregistrées pour examen. Les promotions vers production appliquent atomiquement le prompt de l'assistant, la réponse de secours, les paramètres du widget, la locale et la source du site au projet en production. La configuration de production doit contenir exactement une source de site web. Un déploiement met en file d’attente un scraping lié à la version, qui s’exécute après la fin des jobs précédents. Il remplace ensuite l’ancien corpus et régénère les embeddings. Le runtime actuel rejette les configurations comportant plusieurs sources.

Utilisez --json dans les automatisations pour recevoir la version, l'environnement, l'état de l'application et l'ID du job de scraping sous forme structurée.

État, promotion et restauration

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

La restauration promeut et réapplique une version immuable antérieure ; elle ne réécrit jamais l'historique des déploiements. Elle restaure immédiatement la configuration, tandis que toute actualisation nécessaire du contenu se poursuit de manière asynchrone.

GitHub Actions

- name: Deploy ChattyBox configuration
  env:
    CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
    CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
  run: bunx @openstaticfish/chattybox-cli deploy --environment production --json

Utilisez un secret de production limité à l'environnement et exigez une approbation de déploiement lorsque votre dépôt le permet. La CLI enregistre les variables CI courantes du commit et de la branche avec la version immuable.

Sections de configuration

Section	Objectif
schemaVersion	Sélectionne le contrat de configuration public. La version 1 est actuellement prise en charge.
assistant	Nomme l'assistant et définit facultativement son profil de prompt et son prompt système.
knowledge.sources	Déclare les sources de sites web et les modèles facultatifs d'inclusion ou d'exclusion.
runtime	Contient les valeurs par défaut d'exécution, telles que la locale.
widget	Décrit les paramètres de présentation facultatifs du widget hébergé.

Utilitaire de configuration typé

Installez le package de configuration pour créer des outils TypeScript distincts autour du schéma :

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 CLI elle-même lit des fichiers JSON. defineConfig() est destiné aux applications typées ou aux outils de build ; il ne permet pas à la CLI de charger directement des fichiers TypeScript.

Pour une intégration fonctionnelle en production dès aujourd'hui, utilisez le widget hébergé ou créez une interface personnalisée avec le SDK JavaScript.