CLI en configuratiedeployment
De gepubliceerde CLI/config-artefacten van versie 0.3.1 implementeren het configuratie-/backendcontract 0.3.0 en weigeren onbekende sleutels zowel lokaal als in de backend.
De CLI maakt, valideert, deployt, promoot en rolt onveranderlijke ChattyBox-configuratieversies terug. Elk deploymenttoken is beperkt tot precies één bestaand project en geselecteerde omgevingen. Beschouw één configuratiebestand en één projectgebonden token samen als één beheerd ChattyBox-project.
Publicatie- en runtimestatus
In het openbare register zijn @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 en de afzonderlijke JavaScript-SDK @openstaticfish/chattybox@0.1.4 gepubliceerd. Deze artefacten ondersteunen de uitgebreide velden samen met het backendcontract 0.3.0. schemaVersion: "1" hoort bij een afzonderlijk versiesysteem en staat los van de pakketversies 0.3.1 en het backendcontract 0.3.0. status toont de omgevingsversie, terwijl runtimeConfigVersionId de laatst op de gedeelde runtime toegepaste configuratie aanduidt en kan verschillen. Een weggelaten mode kiest crawl en behoudt een expliciete maxDepth: 0.
De ESM-CLI is een opdrachtregelprogramma en vereist Node.js 20 of hoger. bunx volgt standaard de Node-shebang: installeer Node of selecteer Bun expliciet met bunx --bun @openstaticfish/chattybox-cli .... De CLI is geen browserhulpmiddel. CI voor gepubliceerde pakketten test Node 20, 22 en 24 op Linux, geen algemene OS- of browsercompatibiliteit. Zet in productieautomatisering een geteste pakketversie vast; voorbeelden zonder versie gebruiken het geïnstalleerde of gecachte pakket of dat uit het register, niet de broncode van deze repository.
Wat configuratie als code beheert
De configuratie beheert projectnaam en -beschrijving, persona en fallback van de assistent, websiteontdekking en verversing, taalgedrag en presentatie van de gehoste widget. Een deployment naar preview of productie past deze waarden toe en plant een verversing van het bestaande corpus. Met Configuratievergrendeling verlopen wijzigingen aan deze instellingen via versiebeheer, behalve de brandingvoorkeur waarvoor abonnementsrechten gelden.
Een project maak je voorlopig eenmalig aan in het dashboard. Publieke widgetsleutels en optionele originbeperkingen, beheer van deploymenttokens, analytics, gesprekken, inhoudshiaten, destructieve acties en geüploade pictogrambestanden vallen buiten de configuratie. Gebruik een URL of emoji voor een declaratief aangepast pictogram. De configuratie bevat geen project-ID: het geheime deploymenttoken bepaalt welk project de configuratie ontvangt.
Een publieke widgetsleutel is bedoeld voor chat en widgetconfiguratie en mag in browsercode staan. Een zonder beperkingen gemaakte sleutel werkt over browserorigins heen; een voor een website voorbereide sleutel kan al beperkt zijn. Exacte originbeperkingen zijn optionele extra beveiliging, geen bezoekersauthenticatie. Een configuratiedeploymenttoken is daarentegen een geheim voor deploy, promote, rollback en status van één project en geselecteerde omgevingen: houd het buiten browsercode en bewaar het lokaal of in CI-geheimen.
Een configuratie maken
bunx @openstaticfish/chattybox-cli init
Hiermee wordt chattybox.config.json gemaakt:
{
"schemaVersion": "1",
"assistant": {
"name": "Support"
},
"knowledge": {
"sources": [
{
"type": "website",
"url": "https://example.com"
}
]
},
"widget": {
"enabled": true
}
}
Gebruik een aangepast pad wanneer de configuratie in een submap thuishoort:
bunx @openstaticfish/chattybox-cli init config/chattybox.config.json
Lokaal of in CI valideren
bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json
De validatie in de huidige broncode controleert objectstructuren, de verplichte assistentnaam, toegestane waarden, HTTP(S)-URL's, gehele limieten, localecombinaties en hexkleuren van zes cijfers. knowledge mag bij lokale validatie of ontwikkeling ontbreken, maar moet indien aanwezig precies één websitebron bevatten. Preview en productie vereisen die bron. Als widget aanwezig is, is widget.enabled verplicht.
Validatie leest alleen JSON, geen TypeScript, JSONC, YAML of extern schema. Ze doet geen netwerkverzoek, controleert geen token of abonnementsrechten en past geen standaardwaarden toe. Lokale en backendvalidatie weigeren onbekende eigenschappen; lokaal slagen garandeert geen deployment. Schema v1 weigert onbekende velden op elk objectniveau en vereist niet-lege include-/exclude-waarden. runtime.locale is een afkorting voor een vaste taal zonder overrides en kan niet worden gecombineerd met localeMode, defaultLocale of allowLocaleOverride: true. De server controleert abonnementsrechten en tokenscope.
Een deploymenttoken maken
Open Chatbotinstellingen → Ontwikkelaarsconfiguratie en zoek Tokens voor configuratiedeployment. Maak een token aan voor de omgevingen die je workflow moet kunnen wijzigen. Kopieer het volledige token meteen: ChattyBox bewaart een hash en beperkte identificatie- en levenscyclusmetadata, maar kan het volledige token niet opnieuw tonen.
Het formulier selecteert aanvankelijk alleen development en stelt geen vervaldatum in. Selecteer zo nodig expliciet preview of production. In het dashboard kun je kiezen voor geen vervaldatum of voor 7, 30, 90 of 365 dagen; de geauthenticeerde API accepteert een geheel getal van 1 tot en met 365 dagen of geen vervaldatum. Per project zijn maximaal 20 actieve, niet-verlopen tokens toegestaan. Roteer een token door een vervanger te maken, CI bij te werken en het oude token in te trekken. Er zijn geen CLI-opdrachten voor aanmelden of voor het maken, weergeven of intrekken van tokens.
Stel het token en de widget-API-URL in. Gebruik onder Installeren → Installatie op website zo mogelijk data-api-url uit het snippet; haal anders de HTTP-actions-deployment-URL uit je deploymentconfiguratie. Mogelijk moet de installatie eerst gereed zijn:
export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'
Commit het token nooit. Dit is een server-side Bearer-geheim: bewaar het in de versleutelde secretopslag van je CI-provider en zet het niet in browsercode. Beheerroutes gebruiken geen widget-oorsprongsbeperkingen, vereisen geen Origin-header en bieden geen browser-CORS-toegang. Het token is niet aan een oorsprong gebonden: iedereen die het bezit kan de API vanaf een server aanroepen. Publieke widgetkeys kunnen dit token niet vervangen. Ontbrekende, onjuist opgemaakte, verlopen, ingetrokken, voor de omgeving onbevoegde of anderszins ongeldige tokens geven HTTP 401 INVALID_TOKEN; tokens werken ook niet meer als hun project of eigenaar ontbreekt of wordt verwijderd.
Gebruik de HTTP-actions-deploymentroot of de widget-URL die eindigt op /chat, niet een .convex.cloud-client-URL of een volledig /v1/config/deployments-endpoint. De CLI verwijdert afsluitende slashes en een laatste /chat, en voegt daarna de beheersroute toe. HTTPS is verplicht, behalve voor localhost, 127.0.0.1 of [::1]; in de API-URL zijn inloggegevens, query's en fragmenten niet toegestaan. Controleer de bestemming voordat je een geheim verstrekt.
Configuratievergrendeling
Schakel na verificatie van de deploymentworkflow eventueel Configuratievergrendeling in dezelfde sectie in. Dit is onomkeerbaar via het huidige dashboard, de CLI en de openbare API; er is geen ondersteunde ontgrendeling. Vergrendelen maakt geen token aan en deployt geen versie. Test eerst een werkende token- en configuratieworkflow.
De vergrendeling blokkeert dashboardwijzigingen aan configuratiegestuurde project- en widgetinstellingen, het uploaden van pictogrammen en handmatige corpusacties zoals scrapen, pagina's verwijderen, inhoud wissen en embeddings opnieuw genereren. Gepland werk en het verwijderen van het project worden niet geblokkeerd. Tokens maken/intrekken, openbare sleutels beheren en operationele gegevens lezen blijft mogelijk.
Branding is de uitzondering: de brandinginstelling blijft via het dashboard wijzigbaar op vergrendelde projecten. Attributie verbergen vereist Starter of hoger, ook via een configuratiedeployment. Als je widget.showBranding weglaat, blijft de opgeslagen voorkeur behouden (of wordt true gebruikt als er geen voorkeur is); een expliciete waarde overschrijft deze bij de volgende runtimepromotie. De runtime dwingt branding op het Free-abonnement nog steeds af.
Configuratie deployen
Een deployment maakt een onveranderlijke versie en promoot deze naar de geselecteerde omgeving. Deploy de volledige gewenste configuratie, niet een patch: weggelaten waarden kunnen bij runtimepromotie eerdere dashboardinstellingen wissen of terugzetten.
bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production
Omgevingslabels isoleren de runtime niet. development legt alleen een versie en pointer vast (applied: false, indexingStatus: "not_required"). preview en production overschrijven dezelfde projectruntime-instellingen en gebruiken hetzelfde corpus en dezelfde openbare widgetkeys. De laatste runtimepromotie wint, ook als de status van het andere label nog naar een oudere versie verwijst. Een token met de scope preview kan dus een project wijzigen dat productieverkeer afhandelt. Gebruik voor echte isolatie afzonderlijke projecten met hun eigen tokens en keys.
Promoties naar preview en production passen de configuratie atomair toe en zetten een scrapejob in de wachtrij (applied: true, indexingStatus: "pending"), maar wachten niet op scraping of embeddings. Verversingen werken bestaande pagina's bij en vragen embeddings aan wanneer inhoud verandert; oude URL's worden niet verwijderd alleen omdat een nieuwe bron of filter ze weglaat. Het corpus is geen versie-snapshot: gedeeltelijke updates kunnen na fouten blijven staan en een mislukte verversing draait de toegepaste configuratie niet terug. Jobs registreren een configuratieversie-ID, maar lezen ook veranderlijke scrape-instellingen; vermijd overlappende deployments als consistente indexering belangrijk is.
Gebruik --json in automatisering om het API-resultaat te ontvangen, inclusief version._id, de pointer van de omgeving, applied, indexingStatus en de ID van de scrapejob als er een is ingepland. Bewaar version._id voor latere promotie of rollback; het leesbare volgnummer is geen bruikbare waarde voor --version.
Vervanging en planlimieten
Runtimepromotie wist of reset weggelaten configuratiegestuurde waarden, ook eerdere dashboardinstellingen:
| Weggelaten waarde | Effect op runtime |
|---|---|
project.description, assistentprompt/-profiel/-fallback | Wist opgeslagen overrides; het runtime-fallbackgedrag wordt toegepast. |
runtime | Reset naar automatische taal, standaard en en toegestane taaloverrides. |
widget of optionele widgettekst/-thema/-positie | Als het volledige object widget ontbreekt, wordt de widget ingeschakeld; als het object aanwezig is, wordt de verplichte waarde van enabled gevolgd. Weggelaten presentatie-overrides worden afzonderlijk gewist, zodat runtime-standaarden gelden. |
widget.icon | Reset naar het standaardpictogram, middelgroot. Runtimepromotie verwijdert het eerder geüploade pictogrambestand, ook als je een declaratief vervangend pictogram opgeeft. |
| Bronmodus/-filters/-planning | Standaardmodus is crawl; weggelaten filters worden gewist en automatisch verversen wordt uitgeschakeld. Modusspecifieke instellingen gelden alleen voor de bijbehorende modus. |
widget.showBranding | Uitzondering: behoudt de opgeslagen voorkeur, of gebruikt true als er geen voorkeur is. |
De onveranderlijke configuratieversie bewaart het aangevraagde maxPages, terwijl runtimepromotie de operationele scrapeconfiguratie begrenst op 100.000. Per run begrenst de worker de selectie tot het minimum van de aangevraagde maxPages en het maximum van de providercapaciteit of het aantal bestaande projectpagina's; toelating van nieuwe pagina's wordt apart getoetst aan de paginaquota van het account. Als maxPages ontbreekt, is de standaard voor de aanvraag het inbegrepen paginabudget van het account: Free 10, Starter 150, Pro 5.000 en Business 25.000. Dit is alleen een standaardwaarde voor de aanvraag en geen extra quotum; elke scrape controleert opnieuw de actuele pagina-/PAYG-limiet en de maandelijkse refreshlimieten. Sitemapdetectie kan sitemapdocumenten ophalen en URL's inventariseren voordat de selectie plaatsvindt. Capaciteit is dus geen privacygrens en biedt geen garantie dat er geen uitgaande verzoeken worden gedaan. Het is geen belofte dat alle aangevraagde pagina's worden geïndexeerd.
In de modus sitemap probeert de scraper, als sitemapUrl ontbreekt, eerst een gedetecteerde sitemap, daarna /sitemap.xml en /sitemap_index.xml; als die geen URL's opleveren, gebruikt hij de opgeslagen website-URL.
Dagelijkse automatische verversing en expliciet showBranding: false vereisen Starter of hoger. Free accepteert wekelijkse of maandelijkse automatische verversing. Deze rechten worden gecontroleerd bij promotie naar preview of productie, ook bij rollback, niet bij lokale validatie of vastlegging voor development. Een eerder geldige versie kan na een abonnementswijziging niet meer promoveerbaar zijn. De server bepaalt het abonnement op basis van gecachte project-/werkruimtegegevens, niet via een live verzoek aan de betaalprovider; controleer facturatiesynchronisatie en daadwerkelijk scrapequotum apart na een recente wijziging.
Status, promotie en rollback
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 verwacht de ondoorzichtige configuratieversie-ID: gebruik version._id uit de JSON-uitvoer van deploy/promote/rollback of activeVersion._id uit de JSON-uitvoer van status, niet het zichtbare nummer, een Git-SHA of een configuratiehash. Laat de aanhalingstekens rond placeholders staan zoals hierboven en vervang ze door echte ID's van het project van het token. Rollback gebruikt dezelfde backendbewerking als promote, hoeft geen oudere versie te kiezen en selecteert niet automatisch de vorige versie. Onveranderlijke versiegegevens blijven bewaard, maar de pointer en promotiemetadata van de geselecteerde omgeving worden overschreven; er is geen append-only promotiegeschiedenis. Voor preview of production past rollback de configuratie opnieuw toe met de huidige rechten en zet het een nieuwe vernieuwing in de wachtrij, in plaats van historische inhoud te herstellen. Herhaalde deployments maken ook bij identieke configuratie nieuwe versies; herhaalde promoties kunnen nieuwe jobs inplannen.
status toont de Environment version en pointer van het gekozen label, niet de effectieve runtimeconfiguratie, verschillen met het dashboard of de voortgang van scraping en embeddings. Een niet-gedeployd label toont Environment version: none en geeft environment: null en activeVersion: null terug. runtimeConfigVersionId geeft de laatst op de gedeelde runtime toegepaste configuratie aan en kan na promotie van een ander label verschillen. Ook een geslaagde statusaanvraag werkt lastUsedAt van het token bij en verbruikt capaciteit van de beheerratelimiet. Controleer de indexering afzonderlijk in het dashboard.
Opdrachten, opties en fouten
| Opdracht | Argumenten en werking |
|---|---|
init [path] | Gebruikt standaard chattybox.config.json, maakt bovenliggende mappen en overschrijft geen bestaand bestand. |
validate [path] | Gebruikt hetzelfde standaardpad en valideert JSON zonder externe toegang. |
deploy | Vereist --environment; --config <path> is optioneel. Valideert en maakt en promoot een versie. |
promote, rollback | Vereisen --environment en --version <opaque-id>; lezen geen lokale configuratie. |
status | Vereist --environment; leest geen lokale configuratie. |
Geen opdracht, help, --help, -h | Algemene hulp. Gebruik chattybox --help, niet chattybox deploy --help. |
--version, -v | Algemene CLI-versie; niet de --version-optie voor promotie. |
Alle vier beheeropdrachten accepteren --token, --api-url en --json. Expliciete opties hebben voorrang op CHATTYBOX_DEPLOY_TOKEN en CHATTYBOX_API_URL. Gebruik liever geheime omgevingsvariabelen dan tokens in shellgeschiedenis of procesargumenten. Opties met een waarde accepteren --flag value of --flag=value; --json is een schakelaar zonder waarde. Er is geen standaardomgeving. Onbekende, dubbele, lege en niet-toepasselijke beheeropties worden geweigerd; lokale opdrachten accepteren slechts één positioneel pad en geen opties of extra argumenten.
Er zijn geen --dry-run, --wait, --force, --project, bericht- of optimistic-concurrency-opties. De HTTP-API ondersteunt verwachte versievelden, maar de CLI verstuurt ze niet. Voer CI-deployments voor hetzelfde project na elkaar uit.
Geslaagde uitvoerbare opdrachten eindigen met exitcode 0. Bestands-, JSON-, validatie-, argument-, transport-, responslees- en HTTP-fouten eindigen met code 1 en een ChattyBox: ...-melding op stderr. --json formatteert alleen geslaagde resultaten, geen fouten. API-fouten bevatten de HTTP-status en foutcode indien beschikbaar; geslaagde niet-JSON-antwoorden worden geweigerd. De CLI heeft geen automatische retries, polling of ingestelde aanvraagtimeout. Controleer na een transportfout eerst de status voordat je opnieuw probeert: de server kan de deployment al hebben verwerkt.
De beheerroutes zijn POST /v1/config/deployments (201), POST /v1/config/deployments/promote en /rollback (200), en GET /v1/config/deployments/status?environment=... (200). HTTP-succes is verpakt in { "data": ... }; CLI-JSON haalt die verpakking weg. Fouten gebruiken normaal { "error": { "code": ..., "message": ... } }: 401 INVALID_TOKEN, 404 NOT_FOUND voor een ontbrekende versie of versie van een ander project, 409 CONFIG_CONFLICT, 413 BODY_TOO_LARGE, 422 INVALID_CONFIG of 500 INTERNAL_ERROR. Ongeldig opgemaakte getypeerde ID's geven 422, niet noodzakelijk 404. De aanvraagbody is beperkt tot 262.144 bytes. Alle beheerroutes delen een limiet van 20 aanvragen per minuut per token; 429-reacties gebruiken het gedeelde ratelimitformaat en de header Retry-After. Een volledig ontbrekende POST-body geeft momenteel 500, anders dan ongeldige JSON (422).
activeVersion in de status is de laatst gepromoveerde versie van het gekozen omgevingslabel; runtimeConfigVersionId is de laatst op de gedeelde projectruntime toegepaste configuratie. Een development-promotie wijzigt die runtimepointer niet. Als de configuratie niet vergrendeld is, kunnen latere dashboardwijzigingen runtimevelden veranderen zonder de laatst toegepaste configuratie-ID te wijzigen.
CI/CD-workflows
Voeg CHATTYBOX_DEPLOY_TOKEN toe als een versleuteld geheim met productiescope bij je CI-provider. Voeg CHATTYBOX_API_URL toe als geheim of variabele met de HTTP-actions-deployment-URL of, indien beschikbaar, de widget-API-URL onder Installeren → Installatie op website. Voer validatie uit voor pull requests, maar beperk productie-deployments tot je beveiligde standaardbranch of een goedgekeurde deploymentomgeving.
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
Gebruik een productiegeheim dat aan de omgeving is gebonden en vereist deploymentgoedkeuring wanneer je repository dit ondersteunt. De CLI legt veelgebruikte CI-commit- en branchvariabelen vast bij de onveranderlijke versie.
GitLab CI/CD
Sla beide waarden op onder Settings → CI/CD → Variables. Bescherm het deploymenttoken, maskeer het en beperk het tot de omgeving 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
GitLab stelt CHATTYBOX_DEPLOY_TOKEN en CHATTYBOX_API_URL automatisch beschikbaar aan de job met hun variabelenamen. Gebruik een beveiligde standaardbranch, zodat beschermde variabelen niet beschikbaar zijn voor onbetrouwbare branches. De Bun-containervoorbeelden gebruiken expliciet --bun en hebben daardoor geen afzonderlijke Node-installatie nodig; controleer de vastgezette Bun-/imageversie in CI.
Bitbucket Pipelines
Voeg beide waarden als deploymentvariabelen toe onder Repository settings → Pipelines → Deployments → Production. Markeer het deploymenttoken als beveiligd.
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
Vervang main als je standaardbranch een andere naam heeft. Bitbucket injecteert deploymentvariabelen alleen in stappen die aan die deploymentomgeving zijn gekoppeld. De CLI heeft geen specifieke BITBUCKET_*-metadatakoppeling en valt terug op lokale Git-gegevens voor commit en branch; in een detached checkout kan de branchnaam ontbreken.
Configuratiesecties
| Sectie | Doel |
|---|---|
schemaVersion | Selecteert het openbare configuratiecontract. Versie 1 wordt momenteel ondersteund. |
project | Optionele projectmetadata, zoals de dashboardbeschrijving. |
assistant | Geeft de assistent een naam en definieert een ingebouwde persona of aangepaste systeeminstructie en fallbacktekst. |
knowledge.sources | Selecteert homepage, sitemap, handmatige URL's of crawl, plus limieten, filters en verversingsschema. |
runtime | Beheert automatische of vaste taal, standaardtaal en taaloverrides op paginaniveau. |
widget | Beheert inschakeling, positie, tekst, kleuren en standaard-, emoji- of URL-pictogram. |
Persona's
Stel promptProfile in op default, support, sales of sarcastic voor de onderhouden persona-instructies. Gebruik custom en geef systemPrompt op voor een aangepaste persona. Als zowel een ingebouwd profiel als systemPrompt is opgegeven, krijgt de expliciete prompt voorrang.
Kennis ontdekken
Dit voorbeeld is één item in knowledge.sources, geen volledige configuratie. Het vereist de gepubliceerde CLI/config-pakketten 0.3.1 en het bijbehorende backendcontract 0.3.0. Dagelijks verversen vereist Starter of hoger; maxPages: 500 is een verzoek dat onder de beschikbare capaciteit valt, geen garantie op indexering.
{
"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"
}
De uitgebreide configuratie vereist de gepubliceerde 0.3.1-configuratietypen en het bijbehorende backendcontract 0.3.0. Ondersteunde modi zijn:
homepage: selecteer alleenurlvoor deze verversing; bestaande pagina's worden niet verwijderd.sitemap: gebruiksitemapUrl; een expliciete sitemap zonder URL's laat de job mislukken. Als deze ontbreekt, probeert de scraper eerst een gevonden sitemap, dan/sitemap.xmlen/sitemap_index.xml, en ten slotte de opgeslagen website-URL als geen daarvan URL's oplevert.manual: indexeer de niet-lege lijstmanualUrls.crawl: probeer conventionele sitemaps en volg anders links vanafurltotmaxDepth(standaard3).
include en exclude vergelijken hoofdlettergevoelige URL-substrings, geen glob- of regexpatronen. Elke include-match laat een URL toe; elke exclude-match weigert die, ook als deze is opgenomen. Lege lijsten filteren niet. Filters gelden ook voor homepage en handmatige selectie.
maxPages moet een positief geheel getal zijn; de onveranderlijke versie bewaart de gevraagde waarde, terwijl runtimeconfiguratie en selectie worden begrensd zoals hierboven beschreven. Sitemapontdekking kan URL's inventariseren vóór selectie. maxDepth moet een geheel getal van 0 tot en met 20 zijn en bepaalt de link-crawlfallback, niet de inventarisatie van sitemaps. Een weggelaten mode kiest crawl en behoudt een expliciete maxDepth, ook nul. autoRescrape: true vereist rescrapeInterval: "daily", "weekly" of "monthly"; alleen een interval opgeven activeert geen planning. Maandelijks betekent 30 dagen; de planner kan na het geplande tijdstip uitvoeren.
Validatie van locale en widget
Ondersteunde localecodes zijn en, de, fr, es, it, nl, pl, pt, sv, fi, et, cs, cy en id. localeMode is auto of fixed; voor fixed is defaultLocale vereist. allowLocaleOverride is onafhankelijk instelbaar. De afkorting runtime.locale kiest de vaste modus en schakelt overrides uit; de huidige lokale validatie weigert een combinatie met localeMode, defaultLocale of allowLocaleOverride: true.
Widgetposities zijn bottom-right, bottom-left, top-right en top-left. Alle drie themakleuren gebruiken #RRGGBB, geen korte hexwaarden, kleurnamen of alpha. Pictogrammen gebruiken default, emoji (niet-lege string emoji) of url (HTTP(S)-url), met optionele grootte small, medium of large. Validatie haalt pictogram-URL's niet op, controleert geen MIME-typen en vereist niet precies één emoji. URL-validatie controleert syntaxis en protocol, niet bereikbaarheid of toestemming om te crawlen. Optionele beschrijving, assistentprompt/-fallback, widgettitel en welkomsttekst moeten indien opgegeven niet leeg zijn; laat ze weg om overrides te wissen.
Helper voor getypeerde configuratie
Installeer het configuratiepakket wanneer je afzonderlijke TypeScript-tooling rond het schema bouwt:
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 },
});
De CLI zelf leest JSON-bestanden. defineConfig() is bedoeld voor getypeerde applicatie- of buildtooling; TypeScript-bestanden worden hierdoor niet rechtstreeks laadbaar voor de CLI. Zowel defineConfig(config) als validateConfig(config) valideert synchroon, werpt een gewone Error bij de eerste fout en retourneert hetzelfde object zonder klonen, bevriezen, typeconversie of standaardwaarden. Het pakket exporteert TypeScript-typen en deze functies, geen JSON Schema-document of $schema-URL. Het gepubliceerde pakket 0.3.1 ondersteunt de uitgebreide velden hierboven in TypeScript.
Gebruik voor een werkende productie-integratie op dit moment de gehoste widget of bouw een aangepaste interface met de JavaScript-SDK.