@bircleai/widget-protocol 0.5.0 → 0.6.1

package/dist/index.cjs

@@ -90,7 +90,8 @@ var SERVER_PROVIDED_THEME_FIELDS = [
   "colorScheme",
   "poweredBy",
   "locale",
-  "texts"
+  "texts",
+  "faqs"
 ];
 var MAX_THEME_LABEL = 40;
 var MAX_THEME_TAGLINE = 80;
@@ -159,8 +160,28 @@ function sanitizeServerTheme(raw) {
   if (locale !== null) out.locale = locale;
   const texts = sanitizeThemeTexts(o.texts);
   if (texts !== null) out.texts = texts;
+  const faqs = sanitizeThemeFaqs(o.faqs);
+  if (faqs !== null) out.faqs = faqs;
   return out;
 }
+function sanitizeThemeFaqs(raw) {
+  if (!Array.isArray(raw)) return null;
+  const out = [];
+  for (const item of raw) {
+    if (out.length >= 6) break;
+    if (typeof item !== "object" || item === null) continue;
+    const v = item;
+    const label = typeof v.label === "string" ? v.label.trim() : "";
+    if (label === "" || label.length > 60) continue;
+    const entry = { label };
+    if (typeof v.message === "string") {
+      const message = v.message.trim();
+      if (message !== "" && message.length <= 500) entry.message = message;
+    }
+    out.push(entry);
+  }
+  return out.length > 0 ? out : null;
+}
 function safeThemeLocale(value) {
   if (typeof value !== "string") return null;
   const v = value.trim();

package/dist/index.d.cts

@@ -357,6 +357,21 @@ interface ThemeResponse {
     launcherLabel?: string;
     /** `false` oculta el footer "Powered by BircleAI". Cualquier otro valor lo muestra. */
     poweredBy?: boolean;
+    /**
+     * Preguntas frecuentes del chat: chips que se muestran sobre el composer
+     * mientras la conversación está vacía (después colapsan a un botón que las
+     * re-despliega). Tocar una envía su `message` (o el `label` si no hay) como
+     * mensaje del usuario, por el camino normal — el agente la responde como
+     * cualquier consulta.
+     *
+     * Configurables desde la pestaña Apariencia del Dashboard, por embed key.
+     * Tope 6; `label` <= 60 chars (lo que se ve), `message` <= 500 (lo que se
+     * envía). Ambos se renderizan como `textContent`, nunca como markup.
+     */
+    faqs?: Array<{
+        label: string;
+        message?: string;
+    }>;
     /**
      * Hosts https permitidos para renderizar media rica (allow-list; lo consume la
      * UI, no el core).
@@ -410,7 +425,7 @@ interface ThemeResponse {
  * blancas (el `toUiView` del Gateway y la del widget web) — son defensa en
  * profundidad a propósito, no una duplicación accidental.
  */
-declare const SERVER_PROVIDED_THEME_FIELDS: readonly ["primaryColor", "accentColor", "launcherIcon", "launcherLabel", "position", "headerLogo", "assistantName", "assistantTagline", "assistantAvatar", "fontFamily", "colorScheme", "poweredBy", "locale", "texts"];
+declare const SERVER_PROVIDED_THEME_FIELDS: readonly ["primaryColor", "accentColor", "launcherIcon", "launcherLabel", "position", "headerLogo", "assistantName", "assistantTagline", "assistantAvatar", "fontFamily", "colorScheme", "poweredBy", "locale", "texts", "faqs"];
 /** Subconjunto de `ThemeResponse` que el server realmente puede mandar (ver `SERVER_PROVIDED_THEME_FIELDS`). */
 type ServerThemeResponse = Pick<ThemeResponse, (typeof SERVER_PROVIDED_THEME_FIELDS)[number]>;
 /** Tope de `assistantName` y `launcherLabel`. Más que esto no entra en un header de teléfono. */

package/dist/index.d.ts

@@ -357,6 +357,21 @@ interface ThemeResponse {
     launcherLabel?: string;
     /** `false` oculta el footer "Powered by BircleAI". Cualquier otro valor lo muestra. */
     poweredBy?: boolean;
+    /**
+     * Preguntas frecuentes del chat: chips que se muestran sobre el composer
+     * mientras la conversación está vacía (después colapsan a un botón que las
+     * re-despliega). Tocar una envía su `message` (o el `label` si no hay) como
+     * mensaje del usuario, por el camino normal — el agente la responde como
+     * cualquier consulta.
+     *
+     * Configurables desde la pestaña Apariencia del Dashboard, por embed key.
+     * Tope 6; `label` <= 60 chars (lo que se ve), `message` <= 500 (lo que se
+     * envía). Ambos se renderizan como `textContent`, nunca como markup.
+     */
+    faqs?: Array<{
+        label: string;
+        message?: string;
+    }>;
     /**
      * Hosts https permitidos para renderizar media rica (allow-list; lo consume la
      * UI, no el core).
@@ -410,7 +425,7 @@ interface ThemeResponse {
  * blancas (el `toUiView` del Gateway y la del widget web) — son defensa en
  * profundidad a propósito, no una duplicación accidental.
  */
-declare const SERVER_PROVIDED_THEME_FIELDS: readonly ["primaryColor", "accentColor", "launcherIcon", "launcherLabel", "position", "headerLogo", "assistantName", "assistantTagline", "assistantAvatar", "fontFamily", "colorScheme", "poweredBy", "locale", "texts"];
+declare const SERVER_PROVIDED_THEME_FIELDS: readonly ["primaryColor", "accentColor", "launcherIcon", "launcherLabel", "position", "headerLogo", "assistantName", "assistantTagline", "assistantAvatar", "fontFamily", "colorScheme", "poweredBy", "locale", "texts", "faqs"];
 /** Subconjunto de `ThemeResponse` que el server realmente puede mandar (ver `SERVER_PROVIDED_THEME_FIELDS`). */
 type ServerThemeResponse = Pick<ThemeResponse, (typeof SERVER_PROVIDED_THEME_FIELDS)[number]>;
 /** Tope de `assistantName` y `launcherLabel`. Más que esto no entra en un header de teléfono. */

package/dist/index.js

@@ -42,7 +42,8 @@ var SERVER_PROVIDED_THEME_FIELDS = [
   "colorScheme",
   "poweredBy",
   "locale",
-  "texts"
+  "texts",
+  "faqs"
 ];
 var MAX_THEME_LABEL = 40;
 var MAX_THEME_TAGLINE = 80;
@@ -111,8 +112,28 @@ function sanitizeServerTheme(raw) {
   if (locale !== null) out.locale = locale;
   const texts = sanitizeThemeTexts(o.texts);
   if (texts !== null) out.texts = texts;
+  const faqs = sanitizeThemeFaqs(o.faqs);
+  if (faqs !== null) out.faqs = faqs;
   return out;
 }
+function sanitizeThemeFaqs(raw) {
+  if (!Array.isArray(raw)) return null;
+  const out = [];
+  for (const item of raw) {
+    if (out.length >= 6) break;
+    if (typeof item !== "object" || item === null) continue;
+    const v = item;
+    const label = typeof v.label === "string" ? v.label.trim() : "";
+    if (label === "" || label.length > 60) continue;
+    const entry = { label };
+    if (typeof v.message === "string") {
+      const message = v.message.trim();
+      if (message !== "" && message.length <= 500) entry.message = message;
+    }
+    out.push(entry);
+  }
+  return out.length > 0 ? out : null;
+}
 function safeThemeLocale(value) {
   if (typeof value !== "string") return null;
   const v = value.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bircleai/widget-protocol",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Contrato compartido del Chat Gateway de BircleAI (tipos + helpers de parseo).",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",