@openstaticfish/chattybox-config 0.3.0 → 0.3.1

package/README.md

@@ -2,6 +2,12 @@
 
 Typed configuration and runtime validation for ChattyBox config-as-code projects.
 
+## Availability and Usage
+
+Public registry check on 2026-09-07: `@openstaticfish/chattybox-config@0.2.0` is available. This checkout prepares the expanded contract as `0.3.0`, but that version has not been published. The published types do not include `project`, source discovery/scheduling fields, `runtime.localeMode/defaultLocale/allowLocaleOverride`, `widget.icon`, or `widget.showBranding`. The example below targets current repository source, not the published `0.2.0` declarations. Publishing config `0.3.0` and the matching CLI release is required because the CLI validator is bundled, not replaced by upgrading a config dependency.
+
+Install the published baseline with `bun add -d @openstaticfish/chattybox-config`. Use ESM imports; the package exports `import` and `types` entrypoints with no CommonJS `require` entrypoint. It declares no minimum Node/Bun version or browser support matrix. The implementation uses the standard `URL` API and has no network or filesystem side effects. Published-consumer CI exercises Node 20, 22, and 24 on Linux; the separate CLI declares Node `>=20`.
+
 ```ts
 import { defineConfig } from "@openstaticfish/chattybox-config";
 
@@ -16,7 +22,7 @@ export default defineConfig({
       mode: "sitemap",
       sitemapUrl: "https://docs.example.com/sitemap.xml",
       autoRescrape: true,
-      rescrapeInterval: "daily",
+      rescrapeInterval: "weekly",
     }],
   },
   runtime: { localeMode: "auto", defaultLocale: "en", allowLocaleOverride: true },
@@ -24,8 +30,76 @@ export default defineConfig({
 });
 ```
 
-Schema version 1 supports exactly one website source per project when `knowledge` is provided. Preview and production deployments require that source for an in-place, non-destructive refresh. Discovery modes are `homepage`, `sitemap`, `manual`, and `crawl`; omitting mode means crawl and preserves an explicit `maxDepth`, including zero. Source changes and include/exclude filters govern discovery, not deletion of existing indexed pages. Existing content consumes page capacity, so check refresh outcomes when changing sources.
+For a published-`0.2.0`-compatible typed baseline, use `defineConfig({ schemaVersion: "1", assistant: { name: "Support" }, knowledge: { sources: [{ type: "website", url: "https://docs.example.com" }] }, widget: { enabled: true } })`.
+
+## Exports and Validation
+
+The package exports `defineConfig(config)` and `validateConfig(config)`, both with the signature `(config: ChattyboxConfig) => ChattyboxConfig`. Both validate synchronously, throw an ordinary `Error` at the first failure, and return the same object. They do not clone, freeze, trim stored strings, coerce types, apply defaults, or perform network requests. Their parameter is typed as `ChattyboxConfig`, not `unknown`; handle untrusted input and validation exceptions in your tooling.
+
+Type-only exports are `ChattyboxConfig`, `WebsiteSource`, `ConfigMode` (`collaborative | config_locked`), and `DeploymentEnvironment` (`development | preview | production`). The mode/environment types are not fields you can add to config. This package does not export a JSON Schema document, `$schema` URL, file loader, deployment client, or environment overlay/merge utility. `schemaVersion: "1"` selects the config contract, not the package version.
+
+The CLI only reads JSON. A TypeScript default export as above is useful in your own build tooling, but is not directly loadable by the CLI. `defineConfig` validates immediately; it does not deploy anything or make the object immutable. Backend version records, rather than local objects, are the immutable snapshots.
+
+## Current Source Contract
+
+Only `schemaVersion` and `assistant` are required at the top level. Optional means omitted/`undefined`, not `null`. Local validation rejects unknown properties at every documented object boundary, matching the backend's strict config objects. TypeScript checks and backend deployment/entitlement validation remain separate boundaries.
+
+| Field | Validation and meaning |
+|---|---|
+| `schemaVersion` | Exactly the string `"1"`. |
+| `project.description` | Optional non-empty string. `project` itself is optional. |
+| `assistant.name` | Required non-empty string; also becomes the project's dashboard name. |
+| `assistant.promptProfile` | `default`, `support`, `sales`, `sarcastic`, or `custom`. Custom requires a non-empty `systemPrompt`. |
+| `assistant.systemPrompt`, `assistant.fallbackMessage` | Optional non-empty strings. An explicit system prompt wins over a built-in profile. |
+| `knowledge.sources` | Exactly one website source when `knowledge` is provided. No empty or multi-source list. May be omitted locally/development; required for preview/production. |
+| `runtime` | Optional locale settings described below. |
+| `widget.enabled` | Required boolean whenever `widget` is provided. |
+| `widget.position` | `bottom-right`, `bottom-left`, `top-right`, or `top-left`. |
+| `widget.headerTitle`, `widget.welcomeMessage` | Optional non-empty strings. |
+| `widget.showBranding` | Optional boolean. Local validation does not check entitlement. |
+| `widget.theme` | Optional `primaryColor`, `backgroundColor`, `textColor`, each a six-digit `#RRGGBB` string (case-insensitive). No shorthand, names, or alpha. |
+| `widget.icon` | Required `type` when present: `default`, `emoji`, or `url`. Optional `size`: `small`, `medium`, `large`. Emoji type requires a non-empty `emoji`; URL type requires an HTTP(S) `url`. |
+
+Non-empty means the string contains non-whitespace text; the original string is returned unchanged. Icon validation does not count emoji characters, fetch an image, or check MIME type. Only the selected icon payload is required/validated by local runtime checks; inactive `emoji`/`url` fields are not a discriminated union in the type. Uploaded storage IDs are not config fields.
+
+### Website Sources
+
+| Field | Validation and runtime use |
+|---|---|
+| `type`, `url` | Type must be `website`; URL must parse as HTTP(S). No local reachability, same-origin, crawl-permission, or public-host check. |
+| `mode` | Optional `homepage`, `sitemap`, `manual`, or `crawl`; runtime defaults to crawl. |
+| `sitemapUrl` | Optional HTTP(S) URL; only used for explicit sitemap mode. An explicit sitemap yielding no URLs fails; omission tries `/sitemap.xml`, then `/sitemap_index.xml`, then homepage. |
+| `manualUrls` | Optional array of HTTP(S) URLs; non-empty in manual mode. Manual discovery selects these URLs. |
+| `include`, `exclude` | Optional arrays of non-empty strings. Case-sensitive URL substring matching, not glob/regex. Any include match admits, any exclude match rejects. Empty lists do not filter. Applied to all discovery modes. |
+| `maxPages` | Optional positive integer; the matching `0.3.0` backend stores the request without clamping it to an entitlement. Each run limits outbound discovery and selection to the smaller of the request and the larger of current provider capacity or known existing project pages. |
+| `maxDepth` | Optional integer from 0 through 20; link-crawl fallback depth, not sitemap depth. When `mode` is omitted it still selects crawl and preserves an explicit depth, including zero. |
+| `autoRescrape` | Optional boolean; defaults to false at runtime. |
+| `rescrapeInterval` | `daily`, `weekly`, or `monthly`; required when `autoRescrape` is true. Interval alone does not enable refresh. Monthly is 30 days; scheduling is not an exact execution-time guarantee. |
+
+Homepage selects only `url` for the next refresh. Crawl first tries conventional sitemaps at the source origin, then follows links from `url` if neither sitemap yields URLs. Selecting fewer URLs does not delete existing corpus pages.
+
+### Locale Settings
+
+Supported codes: `en`, `de`, `fr`, `es`, `it`, `nl`, `pl`, `pt`, `sv`, `fi`, `et`, `cs`, `cy`, `id`.
+
+`runtime.localeMode` is `auto` or `fixed`. Fixed mode requires `defaultLocale`; `allowLocaleOverride` is an optional boolean independent of mode. Omission of runtime settings resets to auto, default `en`, and overrides allowed when applied.
+
+`runtime.locale` is shorthand for fixed mode with overrides disabled. Current local validation forbids combining it with `localeMode`, `defaultLocale`, or `allowLocaleOverride: true`; an explicit false is accepted. Published `0.2.0` types expose only this shorthand, not the expanded controls.
+
+## Backend Application
+
+**Environment labels do not isolate runtimes.** Development only records a version/pointer. Preview and production require one website source and both overwrite the same project's runtime/corpus used by its public keys; the latest runtime promotion wins. A preview-only token is not protection for production traffic in the same project. Use distinct projects/tokens/keys for isolation.
+
+Config application is full replacement of config-owned settings, not a partial update. Omitted description, prompt/profile/fallback, and widget copy/theme/position overrides clear so runtime defaults apply. Omitted widget enablement becomes true; icon becomes default/medium and an uploaded icon is unlinked. Source mode defaults to crawl, filters clear when omitted, and automatic refresh defaults to off; mode-specific fields apply only to their corresponding mode.
+
+**Branding is the replacement and lock exception:** omitted `widget.showBranding` preserves its stored value, otherwise defaults to true. Explicit values overwrite it on the next runtime promotion. The dashboard branding-only control remains available even under config lock, subject to entitlement. Hiding branding and automatic daily refresh require Starter or higher; Free accepts weekly/monthly refresh and still enforces branding in public runtime output.
+
+With the matching backend for the prepared `0.3.0` release, the immutable version keeps the requested `maxPages` value without clamping it to an entitlement. Each run limits outbound discovery and selection to the smaller of that request and the larger of current provider page capacity or known existing project pages. At zero or denied capacity, only known existing pages may refresh; with none, it makes no unknown-page outbound discovery. Omission uses the included-plan request default: Free 10, Starter 150, Pro 5,000, Business 25,000. Persistent page capacity is shared across the account's projects; this changes no owner-pool or plan entitlements. The worker rechecks page/PAYG permission and reserves new pages against that pool. Entitlement checks apply on preview/production promotion and rollback, not local validation/development recording.
+
+Promotion reads the server-cached project/workspace plan rather than querying the billing provider live. Recent billing changes therefore also require verification of plan synchronization and the worker's actual allowance.
+
+Runtime promotion applies configuration and queues an asynchronous in-place scrape. It does not wait for indexing, prune old URLs omitted by the new source/filter, or atomically swap a historical corpus. Changed content triggers embedding work. Failed refreshes do not revert config and can leave partial page updates. Jobs record a version ID but also read mutable scrape settings, so avoid overlapping deployments when consistency matters. Rollback reapplies a stored version under current entitlements and refreshes again; it is not historical content restoration. Config versions stay immutable, while environment pointers/promotion metadata are overwritten rather than appended to a promotion event log.
 
-Unknown fields and empty include/exclude entries are rejected. Preview and production are promotion labels for one shared project runtime, not isolated environments. Use separate projects for independent runtimes.
+Config lock is enabled separately, not via `ConfigMode` in the JSON. It is **irreversible through the current dashboard, CLI, and public API**. It blocks config-owned dashboard settings and manual corpus writes, not the branding-only control, token/public-key management, scheduled work, or project deletion. Keep a verified deployment-token workflow before locking. Tokens belong in server/CI secrets, never in config or browser code.
 
-This contract requires config and CLI 0.3.0 or later. Version 0.2.0 lacks several fields in this example; use compatible config and CLI versions together.
+The [CLI README](../cli/README.md) and [deployment guide](https://chattybox.ai/docs/cli/) cover tokens, flags, errors, and CI. Current-source local validation and backend deployment validation both reject unknown config keys, blank include/exclude entries and widget copy, and incompatible locale shorthand settings. Confirm the deployed backend and newly released package artifacts before relying on expanded fields in production.

package/dist/index.js

@@ -20,6 +20,12 @@ function requireRecord(value, path, keys) {
     }
   }
 }
+function requireKnownKeys(value, path, keys) {
+  for (const key of Object.keys(value)) {
+    if (!keys.has(key))
+      throw new Error(`${path}.${key} is not supported`);
+  }
+}
 function requireNonEmptyString(value, path) {
   if (typeof value !== "string" || value.trim().length === 0) {
     throw new Error(`${path} must be a non-empty string`);
@@ -51,12 +57,15 @@ function validateConfig(config) {
   if (!isRecord(config))
     throw new Error("Config must be an object");
   requireRecord(config, "Config", ["schemaVersion", "project", "assistant", "knowledge", "runtime", "widget"]);
+  requireKnownKeys(config, "config", new Set(["schemaVersion", "project", "assistant", "knowledge", "runtime", "widget"]));
   if (config.schemaVersion !== "1")
     throw new Error('schemaVersion must be "1"');
   requireRecord(config.assistant, "assistant", ["name", "systemPrompt", "promptProfile", "fallbackMessage"]);
+  requireKnownKeys(config.assistant, "assistant", new Set(["name", "systemPrompt", "promptProfile", "fallbackMessage"]));
   requireNonEmptyString(config.assistant.name, "assistant.name");
   if (config.project !== undefined) {
     requireRecord(config.project, "project", ["description"]);
+    requireKnownKeys(config.project, "project", new Set(["description"]));
     if (config.project.description !== undefined) {
       requireNonEmptyString(config.project.description, "project.description");
     }
@@ -76,6 +85,7 @@ function validateConfig(config) {
   let sources = [];
   if (config.knowledge !== undefined) {
     requireRecord(config.knowledge, "knowledge", ["sources"]);
+    requireKnownKeys(config.knowledge, "knowledge", new Set(["sources"]));
     if (!Array.isArray(config.knowledge.sources)) {
       throw new Error("knowledge.sources must be an array");
     }
@@ -88,6 +98,19 @@ function validateConfig(config) {
     const sourcePath = `knowledge.sources[${index}]`;
     requireRecord(sourceValue, sourcePath, ["type", "url", "mode", "sitemapUrl", "manualUrls", "include", "exclude", "maxPages", "maxDepth", "autoRescrape", "rescrapeInterval"]);
     const source = sourceValue;
+    requireKnownKeys(source, sourcePath, new Set([
+      "type",
+      "url",
+      "mode",
+      "sitemapUrl",
+      "manualUrls",
+      "include",
+      "exclude",
+      "maxPages",
+      "maxDepth",
+      "autoRescrape",
+      "rescrapeInterval"
+    ]));
     if (source.type !== "website") {
       throw new Error(`${sourcePath}.type is not supported`);
     }
@@ -127,6 +150,7 @@ function validateConfig(config) {
   }
   if (config.runtime !== undefined) {
     requireRecord(config.runtime, "runtime", ["locale", "localeMode", "defaultLocale", "allowLocaleOverride"]);
+    requireKnownKeys(config.runtime, "runtime", new Set(["locale", "localeMode", "defaultLocale", "allowLocaleOverride"]));
     for (const [path, locale] of [["runtime.locale", config.runtime.locale], ["runtime.defaultLocale", config.runtime.defaultLocale]]) {
       if (locale !== undefined && (typeof locale !== "string" || !WIDGET_LOCALES.has(locale))) {
         throw new Error(`${path} is not supported`);
@@ -147,6 +171,15 @@ function validateConfig(config) {
   }
   if (config.widget !== undefined) {
     requireRecord(config.widget, "widget", ["enabled", "position", "headerTitle", "welcomeMessage", "showBranding", "icon", "theme"]);
+    requireKnownKeys(config.widget, "widget", new Set([
+      "enabled",
+      "position",
+      "headerTitle",
+      "welcomeMessage",
+      "showBranding",
+      "icon",
+      "theme"
+    ]));
     if (typeof config.widget.enabled !== "boolean") {
       throw new Error("widget.enabled must be a boolean");
     }
@@ -159,6 +192,8 @@ function validateConfig(config) {
     const icon = config.widget.icon;
     if (icon !== undefined)
       requireRecord(icon, "widget.icon", ["type", "size", "emoji", "url"]);
+    if (icon !== undefined)
+      requireKnownKeys(icon, "widget.icon", new Set(["type", "size", "emoji", "url"]));
     if (icon && !ICON_TYPES.has(icon.type))
       throw new Error("widget.icon.type is not supported");
     if (icon?.size !== undefined && (typeof icon.size !== "string" || !ICON_SIZES.has(icon.size))) {
@@ -179,6 +214,8 @@ function validateConfig(config) {
       requireNonEmptyString(config.widget.welcomeMessage, "widget.welcomeMessage");
     if (config.widget.theme !== undefined)
       requireRecord(config.widget.theme, "widget.theme", ["primaryColor", "backgroundColor", "textColor"]);
+    if (config.widget.theme !== undefined)
+      requireKnownKeys(config.widget.theme, "widget.theme", new Set(["primaryColor", "backgroundColor", "textColor"]));
   }
   validateOptionalColor(config.widget?.theme?.primaryColor, "widget.theme.primaryColor");
   validateOptionalColor(config.widget?.theme?.backgroundColor, "widget.theme.backgroundColor");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openstaticfish/chattybox-config",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",