@customerhero/js 2.1.1 → 2.3.0

package/README.md

@@ -56,6 +56,25 @@ chat.identify({
 | `locale`            | `string`                          | Widget locale (e.g. `"en"`, `"es"`). Auto-detected from browser if omitted. |
 | `suggestedMessages` | `string[]`                        | Quick-reply options shown before the first message.                         |
 
+### Appearance
+
+| Option                   | Type                                | Description                                                                       |
+| ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------- |
+| `colorScheme`            | `"auto" \| "light" \| "dark"`       | `auto` follows the visitor's OS preference. Defaults to `light`.                  |
+| `primaryColorDark`       | `string`                            | Primary color used in dark mode. Only honoured when the effective scheme is dark. |
+| `backgroundColorDark`    | `string`                            | Background color used in dark mode.                                               |
+| `textColorDark`          | `string`                            | Text color used in dark mode.                                                     |
+| `size`                   | `"compact" \| "default" \| "large"` | Launcher diameter, panel dimensions, and base font size.                          |
+| `cornerStyle`            | `"soft" \| "rounded" \| "square"`   | Panel border-radius preset.                                                       |
+| `launcher.iconUrl`       | `string`                            | Custom launcher icon URL (replaces the default chat-bubble glyph).                |
+| `launcher.label`         | `string`                            | CTA label next to the launcher (turns the bubble into a pill). Max 60 chars.      |
+| `launcher.showOnlineDot` | `boolean`                           | Show a small green dot on the launcher when agents are available.                 |
+| `offset.bottom`          | `number`                            | Pixel offset from the bottom edge. 0–1000. Defaults to 20.                        |
+| `offset.side`            | `number`                            | Pixel offset from the side (mirrors `position`). 0–1000. Defaults to 20.          |
+| `zIndex`                 | `number`                            | Z-index override. Defaults to 99999. Capped at 2 000 000 000.                     |
+
+Dark colors are never auto-derived from `primaryColor`/`backgroundColor`/`textColor` — set them explicitly when enabling dark or auto modes.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -20,8 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CORNER_RADIUS: () => CORNER_RADIUS,
   CustomerHeroChat: () => CustomerHeroChat,
   DEFAULTS: () => DEFAULTS,
+  SIZE_PRESETS: () => SIZE_PRESETS,
   SUPPORTED_LOCALES: () => SUPPORTED_LOCALES,
   ScreenshotCancelled: () => ScreenshotCancelled,
   ScreenshotUnavailable: () => ScreenshotUnavailable,
@@ -29,10 +31,14 @@ __export(index_exports, {
   captureScreenshot: () => captureScreenshot,
   createTranslator: () => createTranslator,
   detectLocale: () => detectLocale,
+  effectiveColors: () => effectiveColors,
   evaluate: () => evaluate,
   isRtlLocale: () => isRtlLocale,
+  panelRadius: () => panelRadius,
   pickFire: () => pickFire,
   resolveLocale: () => resolveLocale,
+  resolveScheme: () => resolveScheme,
+  sizePreset: () => sizePreset,
   startTriggersRuntime: () => startTriggersRuntime
 });
 module.exports = __toCommonJS(index_exports);
@@ -46,7 +52,29 @@ var DEFAULTS = {
   position: "bottom-right",
   placeholderText: "Type your message...",
   welcomeMessage: "Hi! How can I help you today?",
-  title: "CustomerHero"
+  title: "CustomerHero",
+  // Appearance pack (B1–B6) defaults.
+  colorScheme: "light",
+  // Dark fallbacks used when the effective scheme is dark and no per-chatbot
+  // dark color is configured. Operators can — and should — override these.
+  primaryColorDark: "#A78BFA",
+  backgroundColorDark: "#0F172A",
+  textColorDark: "#E5E7EB",
+  size: "default",
+  cornerStyle: "rounded",
+  offsetBottom: 20,
+  offsetSide: 20,
+  zIndex: 99999
+};
+var SIZE_PRESETS = {
+  compact: { bubble: 48, width: 320, height: 480, fontSize: 13 },
+  default: { bubble: 56, width: 380, height: 520, fontSize: 14 },
+  large: { bubble: 64, width: 440, height: 600, fontSize: 15 }
+};
+var CORNER_RADIUS = {
+  soft: 8,
+  rounded: 16,
+  square: 0
 };
 
 // src/i18n/locales/en.ts
@@ -75,6 +103,8 @@ var en = {
   attach_menu_open: "Add attachment",
   attach_photo: "Choose file",
   drop_files_here: "Drop files here",
+  incident_dismiss: "Dismiss",
+  incident_default_link_label: "Learn more",
   attachment_unsupported_type: "Unsupported file type"
 };
 
@@ -104,6 +134,8 @@ var es = {
   attach_menu_open: "A\xF1adir adjunto",
   attach_photo: "Elegir archivo",
   drop_files_here: "Suelta los archivos aqu\xED",
+  incident_dismiss: "Descartar",
+  incident_default_link_label: "M\xE1s informaci\xF3n",
   attachment_unsupported_type: "Tipo de archivo no admitido"
 };
 
@@ -133,6 +165,8 @@ var ptBR = {
   attach_menu_open: "Adicionar anexo",
   attach_photo: "Escolher arquivo",
   drop_files_here: "Solte os arquivos aqui",
+  incident_dismiss: "Dispensar",
+  incident_default_link_label: "Saiba mais",
   attachment_unsupported_type: "Tipo de arquivo n\xE3o suportado"
 };
 
@@ -162,6 +196,8 @@ var ptPT = {
   attach_menu_open: "Adicionar anexo",
   attach_photo: "Escolher ficheiro",
   drop_files_here: "Largue os ficheiros aqui",
+  incident_dismiss: "Dispensar",
+  incident_default_link_label: "Saiba mais",
   attachment_unsupported_type: "Tipo de ficheiro n\xE3o suportado"
 };
 
@@ -191,6 +227,8 @@ var fr = {
   attach_menu_open: "Ajouter une pi\xE8ce jointe",
   attach_photo: "Choisir un fichier",
   drop_files_here: "D\xE9posez les fichiers ici",
+  incident_dismiss: "Ignorer",
+  incident_default_link_label: "En savoir plus",
   attachment_unsupported_type: "Type de fichier non pris en charge"
 };
 
@@ -220,6 +258,8 @@ var de = {
   attach_menu_open: "Anhang hinzuf\xFCgen",
   attach_photo: "Datei ausw\xE4hlen",
   drop_files_here: "Dateien hier ablegen",
+  incident_dismiss: "Schlie\xDFen",
+  incident_default_link_label: "Mehr erfahren",
   attachment_unsupported_type: "Dateityp nicht unterst\xFCtzt"
 };
 
@@ -249,6 +289,8 @@ var it = {
   attach_menu_open: "Aggiungi allegato",
   attach_photo: "Scegli file",
   drop_files_here: "Trascina qui i file",
+  incident_dismiss: "Chiudi",
+  incident_default_link_label: "Scopri di pi\xF9",
   attachment_unsupported_type: "Tipo di file non supportato"
 };
 
@@ -278,6 +320,8 @@ var nl = {
   attach_menu_open: "Bijlage toevoegen",
   attach_photo: "Bestand kiezen",
   drop_files_here: "Sleep bestanden hier",
+  incident_dismiss: "Sluiten",
+  incident_default_link_label: "Meer informatie",
   attachment_unsupported_type: "Bestandstype niet ondersteund"
 };
 
@@ -307,6 +351,8 @@ var pl = {
   attach_menu_open: "Dodaj za\u0142\u0105cznik",
   attach_photo: "Wybierz plik",
   drop_files_here: "Upu\u015B\u0107 pliki tutaj",
+  incident_dismiss: "Zamknij",
+  incident_default_link_label: "Dowiedz si\u0119 wi\u0119cej",
   attachment_unsupported_type: "Nieobs\u0142ugiwany typ pliku"
 };
 
@@ -336,6 +382,8 @@ var tr = {
   attach_menu_open: "Ek ekle",
   attach_photo: "Dosya se\xE7",
   drop_files_here: "Dosyalar\u0131 buraya b\u0131rak",
+  incident_dismiss: "Kapat",
+  incident_default_link_label: "Daha fazla bilgi",
   attachment_unsupported_type: "Desteklenmeyen dosya t\xFCr\xFC"
 };
 
@@ -365,6 +413,8 @@ var ar = {
   attach_menu_open: "\u0625\u0636\u0627\u0641\u0629 \u0645\u0631\u0641\u0642",
   attach_photo: "\u0627\u062E\u062A\u0631 \u0645\u0644\u0641\u064B\u0627",
   drop_files_here: "\u0623\u0641\u0644\u062A \u0627\u0644\u0645\u0644\u0641\u0627\u062A \u0647\u0646\u0627",
+  incident_dismiss: "\u0625\u063A\u0644\u0627\u0642",
+  incident_default_link_label: "\u0627\u0639\u0631\u0641 \u0627\u0644\u0645\u0632\u064A\u062F",
   attachment_unsupported_type: "\u0646\u0648\u0639 \u0627\u0644\u0645\u0644\u0641 \u063A\u064A\u0631 \u0645\u062F\u0639\u0648\u0645"
 };
 
@@ -394,6 +444,8 @@ var ja = {
   attach_menu_open: "\u6DFB\u4ED8\u30D5\u30A1\u30A4\u30EB\u3092\u8FFD\u52A0",
   attach_photo: "\u30D5\u30A1\u30A4\u30EB\u3092\u9078\u629E",
   drop_files_here: "\u30D5\u30A1\u30A4\u30EB\u3092\u3053\u3053\u306B\u30C9\u30ED\u30C3\u30D7",
+  incident_dismiss: "\u9589\u3058\u308B",
+  incident_default_link_label: "\u8A73\u7D30\u3092\u898B\u308B",
   attachment_unsupported_type: "\u30B5\u30DD\u30FC\u30C8\u3055\u308C\u3066\u3044\u306A\u3044\u30D5\u30A1\u30A4\u30EB\u5F62\u5F0F"
 };
 
@@ -423,6 +475,8 @@ var ko = {
   attach_menu_open: "\uCCA8\uBD80 \uD30C\uC77C \uCD94\uAC00",
   attach_photo: "\uD30C\uC77C \uC120\uD0DD",
   drop_files_here: "\uD30C\uC77C\uC744 \uC5EC\uAE30\uC5D0 \uB193\uAE30",
+  incident_dismiss: "\uB2EB\uAE30",
+  incident_default_link_label: "\uC790\uC138\uD788 \uC54C\uC544\uBCF4\uAE30",
   attachment_unsupported_type: "\uC9C0\uC6D0\uB418\uC9C0 \uC54A\uB294 \uD30C\uC77C \uD615\uC2DD"
 };
 
@@ -452,6 +506,8 @@ var zhCN = {
   attach_menu_open: "\u6DFB\u52A0\u9644\u4EF6",
   attach_photo: "\u9009\u62E9\u6587\u4EF6",
   drop_files_here: "\u5C06\u6587\u4EF6\u62D6\u653E\u5230\u6B64\u5904",
+  incident_dismiss: "\u5173\u95ED",
+  incident_default_link_label: "\u4E86\u89E3\u66F4\u591A",
   attachment_unsupported_type: "\u4E0D\u652F\u6301\u7684\u6587\u4EF6\u7C7B\u578B"
 };
 
@@ -481,6 +537,8 @@ var zhTW = {
   attach_menu_open: "\u65B0\u589E\u9644\u4EF6",
   attach_photo: "\u9078\u64C7\u6A94\u6848",
   drop_files_here: "\u5C07\u6A94\u6848\u62D6\u653E\u5230\u6B64\u8655",
+  incident_dismiss: "\u95DC\u9589",
+  incident_default_link_label: "\u77AD\u89E3\u66F4\u591A",
   attachment_unsupported_type: "\u4E0D\u652F\u63F4\u7684\u6A94\u6848\u985E\u578B"
 };
 
@@ -984,7 +1042,14 @@ function startTriggersRuntime(options) {
 }
 
 // src/client.ts
+function clampInt(value, min, max, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
 function resolveConfig(userConfig, fetched) {
+  const launcherUser = userConfig.launcher ?? {};
+  const launcherFetched = fetched?.launcher ?? {};
+  const offsetUser = userConfig.offset ?? {};
   return {
     chatbotId: userConfig.chatbotId,
     apiBase: userConfig.apiBase ?? DEFAULTS.apiBase,
@@ -997,12 +1062,78 @@ function resolveConfig(userConfig, fetched) {
     title: userConfig.title ?? fetched?.title ?? DEFAULTS.title,
     avatarUrl: userConfig.avatarUrl ?? fetched?.avatarUrl,
     suggestedMessages: userConfig.suggestedMessages ?? fetched?.suggestedMessages ?? [],
-    stringOverrides: fetched?.stringOverrides
+    stringOverrides: fetched?.stringOverrides,
+    // Appearance pack. Color palette + size + corner style + launcher all
+    // come from the server widget_config (with host-side override). The
+    // *runtime* knobs — colorScheme, offset, zIndex — are host-only because
+    // they depend on the page the widget is embedded in, not the chatbot.
+    primaryColorDark: userConfig.primaryColorDark ?? fetched?.primaryColorDark,
+    backgroundColorDark: userConfig.backgroundColorDark ?? fetched?.backgroundColorDark,
+    textColorDark: userConfig.textColorDark ?? fetched?.textColorDark,
+    size: userConfig.size ?? fetched?.size ?? DEFAULTS.size,
+    cornerStyle: userConfig.cornerStyle ?? fetched?.cornerStyle ?? DEFAULTS.cornerStyle,
+    launcher: {
+      iconUrl: launcherUser.iconUrl ?? launcherFetched.iconUrl,
+      label: launcherUser.label ?? launcherFetched.label,
+      showOnlineDot: launcherUser.showOnlineDot ?? launcherFetched.showOnlineDot ?? false
+    },
+    colorScheme: userConfig.colorScheme ?? DEFAULTS.colorScheme,
+    offset: {
+      bottom: clampInt(offsetUser.bottom, 0, 1e3, DEFAULTS.offsetBottom),
+      side: clampInt(offsetUser.side, 0, 1e3, DEFAULTS.offsetSide)
+    },
+    zIndex: clampInt(userConfig.zIndex, 0, 2e9, DEFAULTS.zIndex),
+    // Defaults to true — the widget shows the attach button unless the
+    // chatbot explicitly opts out via widget_config or the host passes
+    // allowAttachments=false. Server still enforces the same flag at the
+    // upload endpoint either way.
+    allowAttachments: userConfig.allowAttachments ?? fetched?.allowAttachments ?? true
   };
 }
+function sanitizeIncidentBanner(input) {
+  if (!input || typeof input !== "object") return null;
+  const raw = input;
+  const sev = raw.severity;
+  if (sev !== "info" && sev !== "warning" && sev !== "outage") return null;
+  if (typeof raw.title !== "string" || raw.title.length === 0) return null;
+  if (typeof raw.expiresAt === "string") {
+    const t = Date.parse(raw.expiresAt);
+    if (!Number.isNaN(t) && t <= Date.now()) return null;
+  }
+  const out = { severity: sev, title: raw.title };
+  if (typeof raw.body === "string") out.body = raw.body;
+  if (typeof raw.eta === "string") out.eta = raw.eta;
+  if (raw.link && typeof raw.link === "object") {
+    const link = raw.link;
+    if (typeof link.url === "string") {
+      out.link = { url: link.url };
+      if (typeof link.label === "string") out.link.label = link.label;
+    }
+  }
+  if (typeof raw.expiresAt === "string") out.expiresAt = raw.expiresAt;
+  return out;
+}
+function bannerKey(banner) {
+  if (!banner) return null;
+  return JSON.stringify([
+    banner.severity,
+    banner.title,
+    banner.body ?? "",
+    banner.eta ?? "",
+    banner.link?.url ?? "",
+    banner.link?.label ?? "",
+    banner.expiresAt ?? ""
+  ]);
+}
 function getStorage() {
   try {
-    return typeof window !== "undefined" ? window.localStorage : null;
+    if (typeof window !== "undefined" && window.localStorage)
+      return window.localStorage;
+    if (typeof globalThis !== "undefined") {
+      const ls = globalThis.localStorage;
+      if (ls) return ls;
+    }
+    return null;
   } catch {
     return null;
   }
@@ -1044,9 +1175,42 @@ var CustomerHeroChat = class {
       preChatSubmission: null,
       consent: this.readStoredConsent(),
       pendingTriggerId: null,
-      pendingPrefill: null
+      pendingPrefill: null,
+      incidentBanner: null,
+      incidentBannerDismissed: false,
+      readOnly: false
     };
   }
+  /**
+   * Mark the config as loaded and put the client into read-only preview
+   * mode without hitting the API. Used by `@customerhero/react/preview` to
+   * render the widget against a host-supplied config (the dashboard preview
+   * pane). Public API consumers should not call this.
+   *
+   * Pass a config to re-resolve and update the rendered colors/size/launcher
+   * in place. Callers should reuse the same client instance across config
+   * changes so the open animation only fires once.
+   *
+   * @internal
+   */
+  __seedForPreview(config, extras) {
+    const resolved = config ? resolveConfig(config) : this.state.config;
+    if (config) this.userConfig = config;
+    const seededMessages = resolved.welcomeMessage ? [{ role: "bot", content: resolved.welcomeMessage }] : [];
+    const sanitizedBanner = extras && "banner" in extras ? sanitizeIncidentBanner(extras.banner ?? null) : this.state.incidentBanner;
+    this.setState({
+      config: resolved,
+      configLoaded: true,
+      configError: null,
+      readOnly: true,
+      isOpen: true,
+      messages: seededMessages,
+      incidentBanner: sanitizedBanner,
+      // Reset the dismissed flag so toggling the banner on in the dashboard
+      // re-renders it after a previous preview-side dismiss.
+      incidentBannerDismissed: false
+    });
+  }
   // ── Proactive engagement state ─────────────────────────────────────
   triggersRuntime = null;
   preChatFormSubmitted = false;
@@ -1123,11 +1287,18 @@ var CustomerHeroChat = class {
       const resolved = resolveConfig(this.userConfig, fetched);
       const triggers = Array.isArray(fetched.triggers) ? fetched.triggers : [];
       const preChatForm = fetched.preChatForm ?? null;
+      const incidentBanner = sanitizeIncidentBanner(fetched.incidentBanner);
+      const prevBannerKey = bannerKey(this.state.incidentBanner);
+      const nextBannerKey = bannerKey(incidentBanner);
+      const dismissedFromStorage = nextBannerKey && nextBannerKey === this.readStoredBannerDismissal();
+      const incidentBannerDismissed = nextBannerKey === prevBannerKey ? this.state.incidentBannerDismissed || !!dismissedFromStorage : !!dismissedFromStorage;
       this.setState({
         config: resolved,
         configLoaded: true,
         triggers,
-        preChatForm
+        preChatForm,
+        incidentBanner,
+        incidentBannerDismissed
       });
       if (resolved.stringOverrides) this.rebuildTranslator();
       this.startTriggersRuntimeIfPossible();
@@ -1185,6 +1356,7 @@ var CustomerHeroChat = class {
     }
   }
   async sendMessage(message, options) {
+    if (this.state.readOnly) return;
     const trimmed = message.trim();
     const attachmentTokens = options?.attachmentTokens ?? [];
     if (!trimmed || this.state.isLoading) return;
@@ -1552,6 +1724,34 @@ var CustomerHeroChat = class {
   setTraits(traits) {
     this.triggersRuntime?.setTraits(traits);
   }
+  /** Hide the active incident banner for this visitor. Persisted in
+   *  localStorage so a refresh keeps it dismissed; resets automatically
+   *  when the operator changes the banner content. No-op when no banner
+   *  is showing. */
+  dismissIncidentBanner() {
+    const key = bannerKey(this.state.incidentBanner);
+    if (!key) return;
+    this.writeStoredBannerDismissal(key);
+    this.setState({ incidentBannerDismissed: true });
+  }
+  readStoredBannerDismissal() {
+    try {
+      return this.storage?.getItem(
+        `ch_incident_dismissed_${this.userConfig.chatbotId}`
+      ) ?? null;
+    } catch {
+      return null;
+    }
+  }
+  writeStoredBannerDismissal(key) {
+    try {
+      this.storage?.setItem(
+        `ch_incident_dismissed_${this.userConfig.chatbotId}`,
+        key
+      );
+    } catch {
+    }
+  }
   /** Submit pre-chat form answers. Synthesizes a customer record server-side
    *  on the next sendMessage. Resumes any pending message that was deferred
    *  while the form was open. */
@@ -1709,6 +1909,33 @@ function pickExtension(mime) {
   return "jpg";
 }
 
+// src/theme.ts
+function resolveScheme(colorScheme, prefersDark) {
+  if (colorScheme === "dark") return "dark";
+  if (colorScheme === "light") return "light";
+  return prefersDark ? "dark" : "light";
+}
+function effectiveColors(config, scheme) {
+  if (scheme === "dark") {
+    return {
+      primary: config.primaryColorDark ?? DEFAULTS.primaryColorDark,
+      background: config.backgroundColorDark ?? DEFAULTS.backgroundColorDark,
+      text: config.textColorDark ?? DEFAULTS.textColorDark
+    };
+  }
+  return {
+    primary: config.primaryColor,
+    background: config.backgroundColor,
+    text: config.textColor
+  };
+}
+function sizePreset(size) {
+  return SIZE_PRESETS[size];
+}
+function panelRadius(cornerStyle) {
+  return CORNER_RADIUS[cornerStyle];
+}
+
 // src/screenshot.ts
 var ScreenshotCancelled = class extends Error {
   constructor(message = "Screenshot cancelled") {
@@ -1843,8 +2070,10 @@ async function canvasToBlob(canvas, quality) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CORNER_RADIUS,
   CustomerHeroChat,
   DEFAULTS,
+  SIZE_PRESETS,
   SUPPORTED_LOCALES,
   ScreenshotCancelled,
   ScreenshotUnavailable,
@@ -1852,9 +2081,13 @@ async function canvasToBlob(canvas, quality) {
   captureScreenshot,
   createTranslator,
   detectLocale,
+  effectiveColors,
   evaluate,
   isRtlLocale,
+  panelRadius,
   pickFire,
   resolveLocale,
+  resolveScheme,
+  sizePreset,
   startTriggersRuntime
 });