@openstaticfish/chattybox-config 0.2.0 → 0.3.0

package/README.md

@@ -7,12 +7,25 @@ import { defineConfig } from "@openstaticfish/chattybox-config";
 
 export default defineConfig({
   schemaVersion: "1",
-  assistant: { name: "Support" },
+  project: { description: "Managed from Git" },
+  assistant: { name: "Support", promptProfile: "support" },
   knowledge: {
-    sources: [{ type: "website", url: "https://docs.example.com" }],
+    sources: [{
+      type: "website",
+      url: "https://docs.example.com",
+      mode: "sitemap",
+      sitemapUrl: "https://docs.example.com/sitemap.xml",
+      autoRescrape: true,
+      rescrapeInterval: "daily",
+    }],
   },
-  widget: { enabled: true },
+  runtime: { localeMode: "auto", defaultLocale: "en", allowLocaleOverride: true },
+  widget: { enabled: true, icon: { type: "emoji", emoji: "💬" } },
 });
 ```
 
-Version 1 supports exactly one website source per project when `knowledge` is provided. Production deployments require that source so the runtime can replace and re-index the project corpus deterministically.
+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.
+
+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.
+
+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.

package/dist/index.d.ts

@@ -3,12 +3,21 @@ export type DeploymentEnvironment = "development" | "preview" | "production";
 export type WebsiteSource = {
     type: "website";
     url: string;
+    mode?: "homepage" | "sitemap" | "manual" | "crawl";
+    sitemapUrl?: string;
+    manualUrls?: Array<string>;
     include?: Array<string>;
     exclude?: Array<string>;
     maxPages?: number;
+    maxDepth?: number;
+    autoRescrape?: boolean;
+    rescrapeInterval?: "daily" | "weekly" | "monthly";
 };
 export type ChattyboxConfig = {
     schemaVersion: "1";
+    project?: {
+        description?: string;
+    };
     assistant: {
         name: string;
         systemPrompt?: string;
@@ -19,6 +28,10 @@ export type ChattyboxConfig = {
         sources: Array<WebsiteSource>;
     };
     runtime?: {
+        localeMode?: "auto" | "fixed";
+        defaultLocale?: string;
+        allowLocaleOverride?: boolean;
+        /** Shorthand for fixed mode with locale overrides disabled. */
         locale?: string;
     };
     widget?: {
@@ -26,6 +39,14 @@ export type ChattyboxConfig = {
         position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
         headerTitle?: string;
         welcomeMessage?: string;
+        /** Starter and higher plans may hide the maintained widget attribution. */
+        showBranding?: boolean;
+        icon?: {
+            type: "default" | "emoji" | "url";
+            size?: "small" | "medium" | "large";
+            emoji?: string;
+            url?: string;
+        };
         theme?: {
             primaryColor?: string;
             backgroundColor?: string;

package/dist/index.js

@@ -3,6 +3,23 @@ var HEX_COLOR = /^#[0-9a-f]{6}$/i;
 var PROMPT_PROFILES = new Set(["default", "support", "sales", "sarcastic", "custom"]);
 var WIDGET_POSITIONS = new Set(["bottom-right", "bottom-left", "top-right", "top-left"]);
 var WIDGET_LOCALES = new Set(["en", "de", "fr", "es", "it", "nl", "pl", "pt", "sv", "fi", "et", "cs", "cy", "id"]);
+var SOURCE_MODES = new Set(["homepage", "sitemap", "manual", "crawl"]);
+var RESCRAPE_INTERVALS = new Set(["daily", "weekly", "monthly"]);
+var ICON_TYPES = new Set(["default", "emoji", "url"]);
+var ICON_SIZES = new Set(["small", "medium", "large"]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireRecord(value, path, keys) {
+  if (!isRecord(value))
+    throw new Error(`${path} must be an object`);
+  if (keys) {
+    for (const key of Object.keys(value)) {
+      if (!keys.includes(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`);
@@ -13,50 +30,155 @@ function validateOptionalColor(value, path) {
     throw new Error(`${path} must be a six-digit hex color`);
   }
 }
+function validateOptionalStringArray(value, path) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error(`${path} must be an array of strings`);
+  value.forEach((entry, index) => requireNonEmptyString(entry, `${path}[${index}]`));
+}
+function validateHttpUrl(value, path) {
+  requireNonEmptyString(value, path);
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+      throw new Error;
+  } catch {
+    throw new Error(`${path} must be an HTTP(S) URL`);
+  }
+}
 function validateConfig(config) {
-  if (!config || typeof config !== "object")
+  if (!isRecord(config))
     throw new Error("Config must be an object");
+  requireRecord(config, "Config", ["schemaVersion", "project", "assistant", "knowledge", "runtime", "widget"]);
   if (config.schemaVersion !== "1")
     throw new Error('schemaVersion must be "1"');
-  requireNonEmptyString(config.assistant?.name, "assistant.name");
+  requireRecord(config.assistant, "assistant", ["name", "systemPrompt", "promptProfile", "fallbackMessage"]);
+  requireNonEmptyString(config.assistant.name, "assistant.name");
+  if (config.project !== undefined) {
+    requireRecord(config.project, "project", ["description"]);
+    if (config.project.description !== undefined) {
+      requireNonEmptyString(config.project.description, "project.description");
+    }
+  }
   if (config.assistant.systemPrompt !== undefined) {
     requireNonEmptyString(config.assistant.systemPrompt, "assistant.systemPrompt");
   }
-  if (config.assistant.promptProfile !== undefined && !PROMPT_PROFILES.has(config.assistant.promptProfile)) {
+  if (config.assistant.promptProfile === "custom" && !config.assistant.systemPrompt) {
+    throw new Error("assistant.systemPrompt is required for the custom prompt profile");
+  }
+  if (config.assistant.promptProfile !== undefined && (typeof config.assistant.promptProfile !== "string" || !PROMPT_PROFILES.has(config.assistant.promptProfile))) {
     throw new Error("assistant.promptProfile is not supported");
   }
   if (config.assistant.fallbackMessage !== undefined) {
     requireNonEmptyString(config.assistant.fallbackMessage, "assistant.fallbackMessage");
   }
-  if (config.knowledge !== undefined && config.knowledge.sources.length !== 1) {
-    throw new Error("knowledge.sources must contain exactly one website source when provided");
+  let sources = [];
+  if (config.knowledge !== undefined) {
+    requireRecord(config.knowledge, "knowledge", ["sources"]);
+    if (!Array.isArray(config.knowledge.sources)) {
+      throw new Error("knowledge.sources must be an array");
+    }
+    if (config.knowledge.sources.length !== 1) {
+      throw new Error("knowledge.sources must contain exactly one website source when provided");
+    }
+    sources = config.knowledge.sources;
   }
-  for (const [index, source] of (config.knowledge?.sources ?? []).entries()) {
+  for (const [index, sourceValue] of sources.entries()) {
+    const sourcePath = `knowledge.sources[${index}]`;
+    requireRecord(sourceValue, sourcePath, ["type", "url", "mode", "sitemapUrl", "manualUrls", "include", "exclude", "maxPages", "maxDepth", "autoRescrape", "rescrapeInterval"]);
+    const source = sourceValue;
     if (source.type !== "website") {
-      throw new Error(`knowledge.sources[${index}].type is not supported`);
+      throw new Error(`${sourcePath}.type is not supported`);
+    }
+    validateHttpUrl(source.url, `${sourcePath}.url`);
+    const maxPages = source.maxPages;
+    if (maxPages !== undefined && (typeof maxPages !== "number" || !Number.isInteger(maxPages) || maxPages < 1)) {
+      throw new Error(`${sourcePath}.maxPages must be a positive integer`);
     }
-    requireNonEmptyString(source.url, `knowledge.sources[${index}].url`);
-    try {
-      const url = new URL(source.url);
-      if (url.protocol !== "http:" && url.protocol !== "https:")
-        throw new Error;
-    } catch {
-      throw new Error(`knowledge.sources[${index}].url must be an HTTP(S) URL`);
+    if (source.mode !== undefined && (typeof source.mode !== "string" || !SOURCE_MODES.has(source.mode))) {
+      throw new Error(`${sourcePath}.mode is not supported`);
     }
-    if (source.maxPages !== undefined && (!Number.isInteger(source.maxPages) || source.maxPages < 1)) {
-      throw new Error(`knowledge.sources[${index}].maxPages must be a positive integer`);
+    if (source.sitemapUrl !== undefined)
+      validateHttpUrl(source.sitemapUrl, `${sourcePath}.sitemapUrl`);
+    const manualUrls = source.manualUrls;
+    validateOptionalStringArray(manualUrls, `${sourcePath}.manualUrls`);
+    for (const [urlIndex, manualUrl] of (manualUrls ?? []).entries()) {
+      validateHttpUrl(manualUrl, `${sourcePath}.manualUrls[${urlIndex}]`);
     }
+    if (source.mode === "manual" && (!manualUrls || manualUrls.length === 0)) {
+      throw new Error(`${sourcePath}.manualUrls must contain at least one URL in manual mode`);
+    }
+    const maxDepth = source.maxDepth;
+    if (maxDepth !== undefined && (typeof maxDepth !== "number" || !Number.isInteger(maxDepth) || maxDepth < 0 || maxDepth > 20)) {
+      throw new Error(`${sourcePath}.maxDepth must be an integer between 0 and 20`);
+    }
+    if (source.autoRescrape !== undefined && typeof source.autoRescrape !== "boolean") {
+      throw new Error(`${sourcePath}.autoRescrape must be a boolean`);
+    }
+    if (source.rescrapeInterval !== undefined && (typeof source.rescrapeInterval !== "string" || !RESCRAPE_INTERVALS.has(source.rescrapeInterval))) {
+      throw new Error(`${sourcePath}.rescrapeInterval is not supported`);
+    }
+    if (source.autoRescrape && !source.rescrapeInterval) {
+      throw new Error(`${sourcePath}.rescrapeInterval is required when autoRescrape is enabled`);
+    }
+    validateOptionalStringArray(source.include, `${sourcePath}.include`);
+    validateOptionalStringArray(source.exclude, `${sourcePath}.exclude`);
   }
-  if (config.runtime?.locale !== undefined && !WIDGET_LOCALES.has(config.runtime.locale)) {
-    throw new Error("runtime.locale is not supported");
+  if (config.runtime !== undefined) {
+    requireRecord(config.runtime, "runtime", ["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`);
+      }
+    }
+    if (config.runtime.locale !== undefined && (config.runtime.localeMode !== undefined || config.runtime.defaultLocale !== undefined || config.runtime.allowLocaleOverride === true)) {
+      throw new Error("runtime.locale cannot be combined with localeMode, defaultLocale, or an enabled locale override");
+    }
+    if (config.runtime.localeMode === "fixed" && !config.runtime.defaultLocale) {
+      throw new Error("runtime.defaultLocale is required in fixed locale mode");
+    }
+    if (config.runtime.localeMode !== undefined && config.runtime.localeMode !== "auto" && config.runtime.localeMode !== "fixed") {
+      throw new Error("runtime.localeMode is not supported");
+    }
+    if (config.runtime.allowLocaleOverride !== undefined && typeof config.runtime.allowLocaleOverride !== "boolean") {
+      throw new Error("runtime.allowLocaleOverride must be a boolean");
+    }
   }
   if (config.widget !== undefined) {
+    requireRecord(config.widget, "widget", ["enabled", "position", "headerTitle", "welcomeMessage", "showBranding", "icon", "theme"]);
     if (typeof config.widget.enabled !== "boolean") {
       throw new Error("widget.enabled must be a boolean");
     }
-    if (config.widget.position !== undefined && !WIDGET_POSITIONS.has(config.widget.position)) {
+    if (config.widget.showBranding !== undefined && typeof config.widget.showBranding !== "boolean") {
+      throw new Error("widget.showBranding must be a boolean");
+    }
+    if (config.widget.position !== undefined && (typeof config.widget.position !== "string" || !WIDGET_POSITIONS.has(config.widget.position))) {
       throw new Error("widget.position is not supported");
     }
+    const icon = config.widget.icon;
+    if (icon !== undefined)
+      requireRecord(icon, "widget.icon", ["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))) {
+      throw new Error("widget.icon.size is not supported");
+    }
+    if (icon?.type === "emoji")
+      requireNonEmptyString(icon.emoji, "widget.icon.emoji");
+    if (icon?.type === "url")
+      validateHttpUrl(icon.url, "widget.icon.url");
+    for (const field of ["emoji", "url"]) {
+      if (icon?.[field] !== undefined && typeof icon[field] !== "string") {
+        throw new Error(`widget.icon.${field} must be a string`);
+      }
+    }
+    if (config.widget.headerTitle !== undefined)
+      requireNonEmptyString(config.widget.headerTitle, "widget.headerTitle");
+    if (config.widget.welcomeMessage !== undefined)
+      requireNonEmptyString(config.widget.welcomeMessage, "widget.welcomeMessage");
+    if (config.widget.theme !== undefined)
+      requireRecord(config.widget.theme, "widget.theme", ["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.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",