@cognitiondesk/widget 1.2.0 → 1.2.2

package/src/widget.js

@@ -271,23 +271,57 @@ function generateSessionId() {
 }
 
 export default class CognitionDeskWidget {
+  /**
+   * @param {Object} config
+   * @param {string}  config.apiKey           - Required. Your CognitionDesk API key.
+   * @param {string}  [config.widgetId]        - Widget ID from the dashboard. Enables remote config.
+   * @param {string}  [config.assistantId]     - Assistant ID (overrides server value if set).
+   * @param {string}  [config.backendUrl]      - Custom backend URL.
+   * @param {string}  [config.theme]           - 'light' | 'dark' | 'auto'
+   * @param {string}  [config.primaryColor]    - Hex color for buttons / header.
+   * @param {string}  [config.botName]         - Display name shown in the header.
+   * @param {string}  [config.botEmoji]        - Emoji shown as avatar.
+   * @param {string}  [config.welcomeMessage]  - First message shown to the user.
+   * @param {string}  [config.placeholder]     - Textarea placeholder text.
+   * @param {string}  [config.position]        - 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
+   * @param {boolean} [config.streaming]       - Enable streaming responses (default: true).
+   * @param {Object}  [config.overrideSettings]
+   *   Explicit code-level overrides. Any key listed here takes precedence over
+   *   the server-side dashboard config. Use this when you want to manage
+   *   specific settings from code rather than the CognitionDesk dashboard.
+   *
+   *   Example — let the dashboard control everything except color:
+   *     overrideSettings: { primaryColor: '#e11d48' }
+   *
+   *   Example — full code control (dashboard settings ignored):
+   *     overrideSettings: {
+   *       primaryColor: '#e11d48', botName: 'Aria', welcomeMessage: 'Hi!'
+   *     }
+   *
+   *   When omitted (default), ALL settings come from the dashboard.
+   */
   constructor(config = {}) {
     if (!config.apiKey) throw new Error('[CognitionDesk] apiKey is required');
 
+    // Keys the developer explicitly wants to control from code.
+    // These override whatever the dashboard says.
+    this._overrides = new Set(
+      config.overrideSettings ? Object.keys(config.overrideSettings) : []
+    );
+
     this._cfg = {
       apiKey:         config.apiKey,
       widgetId:       config.widgetId       || null,
       assistantId:    config.assistantId    || null,
       backendUrl:     config.backendUrl     || DEFAULT_BACKEND,
       primaryColor:   config.primaryColor   || '#2563eb',
-      theme:          config.theme          || 'light',  // 'light' | 'dark' | 'auto'
+      theme:          config.theme          || 'light',
       botName:        config.botName        || 'AI Assistant',
       botEmoji:       config.botEmoji       || '🤖',
       welcomeMessage: config.welcomeMessage || 'Hello! How can I help you today?',
       placeholder:    config.placeholder    || 'Type a message…',
       position:       config.position       || 'bottom-right',
-      streaming:      config.streaming      !== false,   // default: true
-      // Rate limiting — can be overridden by inline config or merged from server config
+      streaming:      config.streaming      !== false,
       rateLimiting: {
         enabled:               config.rateLimiting?.enabled              !== false,
         maxMessagesPerSession: config.rateLimiting?.maxMessagesPerSession ?? 0,
@@ -295,30 +329,38 @@ export default class CognitionDeskWidget {
         limitReachedMessage:   config.rateLimiting?.limitReachedMessage   || "You've reached the message limit for this session.",
         rateLimitMessage:      config.rateLimiting?.rateLimitMessage      || "You're sending messages too quickly. Please wait a moment.",
       },
+      // Store overrides for re-application after each config refresh
+      overrideSettings: config.overrideSettings || null,
     };
 
+    // Apply overrides immediately on top of defaults
+    if (config.overrideSettings) {
+      this._applyOverrides(config.overrideSettings);
+    }
+
     this._sessionId    = generateSessionId();
-    this._messageCount = 0;          // total sent this session
-    this._minuteCount  = 0;          // sent in current minute window
-    this._minuteStart  = Date.now(); // start of current minute window
-    this._messages  = [];   // { role: 'user'|'assistant', content: string }[]
-    this._open      = false;
-    this._loading   = false;
-    this._container = null;
-    this._shadow    = null;
-    this._panel     = null;
-    this._messagesEl = null;
-    this._textarea  = null;
-    this._sendBtn   = null;
+    this._messageCount = 0;
+    this._minuteCount  = 0;
+    this._minuteStart  = Date.now();
+    this._messages     = [];
+    this._open         = false;
+    this._loading      = false;
+    this._container    = null;
+    this._shadow       = null;
+    this._panel        = null;
+    this._messagesEl   = null;
+    this._textarea     = null;
+    this._sendBtn      = null;
     this._viewportHandler = null;
+    this._refreshPending  = false;
   }
 
   // ── Public API ──────────────────────────────────────────────────────────────
 
   /**
    * Mount the widget.
-   * If `widgetId` was provided, fetches the server-side config first (async).
-   * Returns a Promise so callers can await full initialisation.
+   * If `widgetId` is set, fetches server config first (async).
+   * Returns a Promise so callers can `await widget.mount()`.
    */
   mount(target) {
     const _mount = () => {
@@ -333,7 +375,7 @@ export default class CognitionDeskWidget {
       this._shadow.appendChild(style);
 
       this._buildDOM();
-      this._applyTheme();
+      this._applyConfig();
       this._syncViewportMetrics();
       this._bindViewportMetrics();
       this._bindEvents();
@@ -346,16 +388,55 @@ export default class CognitionDeskWidget {
     if (this._cfg.widgetId) {
       return this._fetchWidgetConfig()
         .then(() => _mount())
-        .catch(() => _mount()); // fallback to inline config on network error
+        .catch(() => _mount());
     }
 
     _mount();
     return Promise.resolve(this);
   }
 
+  /**
+   * Programmatically update settings at runtime.
+   * Merges `newSettings` into `overrideSettings` and re-applies to the live DOM.
+   * Use this to change colors, bot name, etc. without remounting.
+   *
+   *   widget.updateSettings({ primaryColor: '#dc2626', botName: 'Support Bot' });
+   */
+  updateSettings(newSettings) {
+    if (!newSettings || typeof newSettings !== 'object') return;
+    // Merge into overrides
+    const merged = { ...(this._cfg.overrideSettings || {}), ...newSettings };
+    this._cfg.overrideSettings = merged;
+    this._overrides = new Set(Object.keys(merged));
+    this._applyOverrides(merged);
+    this._applyConfig();
+  }
+
+  /**
+   * Fetch fresh config from the dashboard right now and apply it.
+   * Useful after the user changes settings in the CognitionDesk dashboard
+   * and wants them reflected immediately without reloading the page.
+   */
+  async refreshConfig() {
+    if (!this._cfg.widgetId) return;
+    await this._fetchWidgetConfig();
+    this._applyConfig();
+  }
+
+  // ── Config internals ────────────────────────────────────────────────────────
+
+  /**
+   * Returns true if `key` is explicitly controlled by `overrideSettings`.
+   * Those keys are immune to server config overwrites.
+   */
+  _userSet(key) {
+    return this._overrides.has(key);
+  }
+
   /**
    * Fetch public widget config from the platform and merge into this._cfg.
-   * Only fields not already overridden by the constructor are applied.
+   * Server values apply to any key NOT present in `overrideSettings`.
+   * After merging, overrides are re-applied so they always win.
    */
   async _fetchWidgetConfig() {
     const url = `${this._cfg.backendUrl}/platforms/web-widget/public/${this._cfg.widgetId}`;
@@ -364,27 +445,97 @@ export default class CognitionDeskWidget {
       if (!res.ok) return;
       const { config } = await res.json();
       if (!config) return;
-      // Merge — explicit constructor overrides take precedence
-      if (config.botName        && !this._userSet('botName'))        this._cfg.botName        = config.botName;
-      if (config.welcomeMessage && !this._userSet('welcomeMessage')) this._cfg.welcomeMessage = config.welcomeMessage;
-      if (config.primaryColor   && !this._userSet('primaryColor'))   this._cfg.primaryColor   = config.primaryColor;
-      if (config.placeholder    && !this._userSet('placeholder'))    this._cfg.placeholder    = config.placeholder;
-      if (config.assistantId    && !this._cfg.assistantId)           this._cfg.assistantId    = config.assistantId;
-      if (config.avatar?.value  && !this._userSet('botEmoji'))       this._cfg.botEmoji       = config.avatar.value;
-      // Merge rate limiting from server config (server is authoritative)
+
+      // Apply each server field unless the developer has overridden it
+      const apply = (key, value) => {
+        if (value != null && !this._userSet(key)) this._cfg[key] = value;
+      };
+
+      apply('botName',        config.botName);
+      apply('welcomeMessage', config.welcomeMessage);
+      apply('primaryColor',   config.primaryColor);
+      apply('secondaryColor', config.secondaryColor);
+      apply('placeholder',    config.placeholder);
+      apply('theme',          config.theme);
+      apply('position',       config.position);
+      apply('style',          config.style);
+      apply('size',           config.size);
+
+      // assistantId: use server value only if not set inline
+      if (config.assistantId && !this._cfg.assistantId) {
+        this._cfg.assistantId = config.assistantId;
+      }
+
+      // Avatar emoji
+      if (config.avatar?.value && !this._userSet('botEmoji')) {
+        this._cfg.botEmoji = config.avatar.value;
+      }
+
+      // Rate limiting — server is always authoritative (security-sensitive)
       if (config.rateLimiting) {
         this._cfg.rateLimiting = { ...this._cfg.rateLimiting, ...config.rateLimiting };
       }
+
+      // Re-apply overrides so they always take precedence over server values
+      if (this._cfg.overrideSettings) {
+        this._applyOverrides(this._cfg.overrideSettings);
+      }
     } catch {
-      // Silently ignore — widget falls back to inline config
+      // Network error — keep current config
     }
   }
 
-  // eslint-disable-next-line no-unused-vars
-  _userSet(_key) {
-    // In production use, explicit constructor props shadow defaults.
-    // This is a simple passthrough — override in subclasses if needed.
-    return false;
+  /**
+   * Write override values into this._cfg (flat fields only; rateLimiting is merged).
+   */
+  _applyOverrides(overrides) {
+    for (const [key, value] of Object.entries(overrides)) {
+      if (key === 'rateLimiting' && typeof value === 'object') {
+        this._cfg.rateLimiting = { ...this._cfg.rateLimiting, ...value };
+      } else {
+        this._cfg[key] = value;
+      }
+    }
+  }
+
+  /**
+   * Update live DOM elements to reflect the current this._cfg.
+   * Safe to call before or after mounting.
+   */
+  _applyConfig() {
+    // ── Theme & colors ──
+    const isDark = this._cfg.theme === 'dark'
+      || (this._cfg.theme === 'auto' && window.matchMedia?.('(prefers-color-scheme: dark)').matches);
+
+    this._root?.classList.toggle('cd-dark', isDark);
+    this._root?.style.setProperty('--cd-primary', this._cfg.primaryColor);
+    this._panel?.style.setProperty('--cd-primary', this._cfg.primaryColor);
+    this._toggleBtn?.style.setProperty('--cd-primary', this._cfg.primaryColor);
+
+    // ── Header: avatar + bot name ──
+    const avatarEl = this._shadow?.querySelector('.cd-header-avatar');
+    if (avatarEl) avatarEl.textContent = this._cfg.botEmoji;
+
+    const nameEl = this._shadow?.querySelector('.cd-header-name');
+    if (nameEl) nameEl.textContent = this._cfg.botName;
+
+    // ── Input placeholder ──
+    if (this._textarea) this._textarea.placeholder = this._cfg.placeholder;
+  }
+
+  /**
+   * Silently refresh config from server in the background.
+   * Called each time the panel opens so dashboard changes
+   * are reflected without reloading the page.
+   * Uses a debounce flag to avoid concurrent fetches.
+   */
+  _silentRefresh() {
+    if (!this._cfg.widgetId || this._refreshPending) return;
+    this._refreshPending = true;
+    this._fetchWidgetConfig()
+      .then(() => this._applyConfig())
+      .catch(() => {})
+      .finally(() => { this._refreshPending = false; });
   }
 
   unmount() {
@@ -400,6 +551,8 @@ export default class CognitionDeskWidget {
     this._syncViewportMetrics();
     this._panel?.classList.add('open');
     this._textarea?.focus();
+    // Background refresh so config changes from dashboard appear on next open
+    this._silentRefresh();
   }
 
   close() {