@bircleai/widget-protocol 0.4.3

package/LICENSE.md

@@ -0,0 +1,50 @@
+# Bircle SDK License
+
+Copyright (c) 2026 Bircle AI. All rights reserved.
+
+## Grant
+
+Subject to the terms below, Bircle AI grants you a limited, non-exclusive,
+non-transferable, revocable license to install this package and to use it,
+including in compiled or bundled form within your application, **solely to
+develop, test and operate applications that integrate with the services
+provided by Bircle AI** under an active service relationship.
+
+## Restrictions
+
+Except as expressly permitted above, you may NOT:
+
+1. Copy, redistribute, publish, sublicense, sell, rent or otherwise make this
+   software (or any part or derivative of it) available as a standalone
+   library, template, UI kit, or as part of any product or service that does
+   not connect to the services of Bircle AI;
+2. Use this software to build, or assist in building, a product or service
+   that competes with the services of Bircle AI;
+3. Remove or alter any copyright, trademark or attribution notices;
+4. Use the Bircle name or logos except to state that your application
+   integrates with Bircle.
+
+Modifications strictly necessary for the permitted integration (including
+bundling, minification and tree-shaking performed by standard build tooling)
+are permitted and are covered by the same restrictions.
+
+## Termination
+
+This license terminates automatically if you breach any of its terms or when
+your service relationship with Bircle AI ends. Upon termination you must stop
+distributing builds that include this software, except that end-user
+applications already published may continue to operate while an active service
+relationship exists for them.
+
+## No warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+BIRCLE AI BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+For licensing questions: soporte@bircle.ai

package/README.md

@@ -0,0 +1,13 @@
+# `@bircleai/widget-protocol`
+
+Tipos y validadores del protocolo de mensajes del chat de BircleAI (eventos,
+mensajes, quick replies, adjuntos, handover). Sin dependencias.
+
+Lo consumen el widget web, el SDK y el backend; publicado para que una integración
+custom pueda tipar los mismos eventos.
+
+```sh
+npm install @bircleai/widget-protocol
+```
+
+Licencia: Propietaria — ver [LICENSE.md](./LICENSE.md). Uso permitido únicamente para integrar con los servicios de Bircle; prohibida la redistribución standalone y la reventa.

package/dist/index.cjs

@@ -0,0 +1,293 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ALLOWED_UPLOAD_CONTENT_TYPES: () => ALLOWED_UPLOAD_CONTENT_TYPES,
+  MAX_AGENT_NAME: () => MAX_AGENT_NAME,
+  MAX_QUICK_REPLIES: () => MAX_QUICK_REPLIES,
+  MAX_QUICK_REPLY_LABEL: () => MAX_QUICK_REPLY_LABEL,
+  MAX_THEME_FONT_FAMILY: () => MAX_THEME_FONT_FAMILY,
+  MAX_THEME_LABEL: () => MAX_THEME_LABEL,
+  MAX_THEME_TAGLINE: () => MAX_THEME_TAGLINE,
+  MAX_THEME_TEXT_KEY: () => MAX_THEME_TEXT_KEY,
+  MAX_THEME_TEXT_KEYS: () => MAX_THEME_TEXT_KEYS,
+  MAX_THEME_TEXT_VALUE: () => MAX_THEME_TEXT_VALUE,
+  MAX_UPLOAD_SIZE_BYTES: () => MAX_UPLOAD_SIZE_BYTES,
+  MEDIA_CONTENT_TYPES: () => MEDIA_CONTENT_TYPES,
+  SERVER_PROVIDED_THEME_FIELDS: () => SERVER_PROVIDED_THEME_FIELDS,
+  isAllowedUploadContentType: () => isAllowedUploadContentType,
+  isAssistantMessageEvent: () => isAssistantMessageEvent,
+  isMediaContentType: () => isMediaContentType,
+  isRawAssistantMessageEvent: () => isRawAssistantMessageEvent,
+  mediaKindForContentType: () => mediaKindForContentType,
+  normalizeAssistantMessageEvent: () => normalizeAssistantMessageEvent,
+  parseWidgetEvent: () => parseWidgetEvent,
+  safeThemeColor: () => safeThemeColor,
+  safeThemeUrl: () => safeThemeUrl,
+  sanitizeAssistantIdentity: () => sanitizeAssistantIdentity,
+  sanitizeQuickReplies: () => sanitizeQuickReplies,
+  sanitizeServerTheme: () => sanitizeServerTheme
+});
+module.exports = __toCommonJS(index_exports);
+var MEDIA_CONTENT_TYPES = [
+  "image",
+  "audio",
+  "video",
+  "document"
+];
+function isMediaContentType(v) {
+  return typeof v === "string" && MEDIA_CONTENT_TYPES.includes(v);
+}
+var ALLOWED_UPLOAD_CONTENT_TYPES = {
+  "image/png": "image",
+  "image/jpeg": "image",
+  "image/webp": "image",
+  "image/gif": "image",
+  "audio/webm": "audio",
+  "audio/mp4": "audio",
+  "audio/mpeg": "audio",
+  "audio/ogg": "audio",
+  "video/mp4": "video",
+  "video/webm": "video",
+  "application/pdf": "document"
+};
+var MAX_UPLOAD_SIZE_BYTES = 10 * 1024 * 1024;
+function isAllowedUploadContentType(contentType) {
+  return Object.prototype.hasOwnProperty.call(ALLOWED_UPLOAD_CONTENT_TYPES, contentType);
+}
+function mediaKindForContentType(contentType) {
+  return ALLOWED_UPLOAD_CONTENT_TYPES[contentType] ?? null;
+}
+var SERVER_PROVIDED_THEME_FIELDS = [
+  "primaryColor",
+  "accentColor",
+  "launcherIcon",
+  "launcherLabel",
+  "position",
+  "headerLogo",
+  "assistantName",
+  "assistantTagline",
+  "assistantAvatar",
+  "fontFamily",
+  "colorScheme",
+  "poweredBy",
+  "locale",
+  "texts"
+];
+var MAX_THEME_LABEL = 40;
+var MAX_THEME_TAGLINE = 80;
+var MAX_THEME_FONT_FAMILY = 120;
+var MAX_THEME_TEXT_KEYS = 40;
+var MAX_THEME_TEXT_KEY = 60;
+var MAX_THEME_TEXT_VALUE = 200;
+function safeThemeColor(value) {
+  if (typeof value !== "string") return null;
+  const v = value.trim();
+  return /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(v) ? v : null;
+}
+function safeThemeUrl(value) {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  try {
+    const u = new URL(value.trim());
+    return u.protocol === "https:" ? u.toString() : null;
+  } catch {
+    return null;
+  }
+}
+function safeThemeText(value, max) {
+  if (typeof value !== "string") return null;
+  const v = value.trim();
+  return v !== "" && v.length <= max ? v : null;
+}
+function sanitizeThemeTexts(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const out = {};
+  let n = 0;
+  for (const [k, v] of Object.entries(raw)) {
+    if (n >= MAX_THEME_TEXT_KEYS) break;
+    if (k === "" || k.length > MAX_THEME_TEXT_KEY) continue;
+    if (typeof v !== "string" || v === "" || v.length > MAX_THEME_TEXT_VALUE) continue;
+    out[k] = v;
+    n += 1;
+  }
+  return n > 0 ? out : null;
+}
+function sanitizeServerTheme(raw) {
+  if (typeof raw !== "object" || raw === null) return {};
+  const o = raw;
+  const out = {};
+  const primaryColor = safeThemeColor(o.primaryColor);
+  if (primaryColor !== null) out.primaryColor = primaryColor;
+  const accentColor = safeThemeColor(o.accentColor);
+  if (accentColor !== null) out.accentColor = accentColor;
+  const launcherIcon = safeThemeUrl(o.launcherIcon);
+  if (launcherIcon !== null) out.launcherIcon = launcherIcon;
+  const headerLogo = safeThemeUrl(o.headerLogo);
+  if (headerLogo !== null) out.headerLogo = headerLogo;
+  const assistantAvatar = safeThemeUrl(o.assistantAvatar);
+  if (assistantAvatar !== null) out.assistantAvatar = assistantAvatar;
+  const launcherLabel = safeThemeText(o.launcherLabel, MAX_THEME_LABEL);
+  if (launcherLabel !== null) out.launcherLabel = launcherLabel;
+  const assistantName = safeThemeText(o.assistantName, MAX_THEME_LABEL);
+  if (assistantName !== null) out.assistantName = assistantName;
+  const assistantTagline = safeThemeText(o.assistantTagline, MAX_THEME_TAGLINE);
+  if (assistantTagline !== null) out.assistantTagline = assistantTagline;
+  const fontFamily = safeThemeText(o.fontFamily, MAX_THEME_FONT_FAMILY);
+  if (fontFamily !== null) out.fontFamily = fontFamily;
+  if (o.position === "bottom-right" || o.position === "bottom-left") out.position = o.position;
+  if (o.colorScheme === "light" || o.colorScheme === "dark") out.colorScheme = o.colorScheme;
+  if (typeof o.poweredBy === "boolean") out.poweredBy = o.poweredBy;
+  const locale = safeThemeLocale(o.locale);
+  if (locale !== null) out.locale = locale;
+  const texts = sanitizeThemeTexts(o.texts);
+  if (texts !== null) out.texts = texts;
+  return out;
+}
+function safeThemeLocale(value) {
+  if (typeof value !== "string") return null;
+  const v = value.trim();
+  return v.length >= 2 && v.length <= 5 && /^[a-zA-Z-]+$/.test(v) ? v : null;
+}
+var MAX_QUICK_REPLIES = 6;
+var MAX_QUICK_REPLY_LABEL = 40;
+function sanitizeQuickReplies(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const item of raw) {
+    if (out.length >= MAX_QUICK_REPLIES) break;
+    if (typeof item !== "object" || item === null) continue;
+    const o = item;
+    const label = typeof o.label === "string" ? o.label.trim() : "";
+    if (label === "" || label.length > MAX_QUICK_REPLY_LABEL) continue;
+    const value = typeof o.value === "string" && o.value.trim() !== "" ? o.value.trim() : void 0;
+    out.push(value !== void 0 ? { label, value } : { label });
+  }
+  return out;
+}
+var MAX_AGENT_NAME = 40;
+function sanitizeAssistantIdentity(raw, kind = "human") {
+  if (typeof raw !== "object" || raw === null) return null;
+  const o = raw;
+  const rawName = typeof o.name === "string" ? o.name.trim() : "";
+  const name = rawName !== "" && rawName.length <= MAX_AGENT_NAME ? rawName : void 0;
+  let avatar;
+  if (typeof o.avatar === "string" && o.avatar.trim() !== "") {
+    try {
+      const u = new URL(o.avatar.trim());
+      if (u.protocol === "https:") avatar = u.toString();
+    } catch {
+    }
+  }
+  if (name === void 0 && avatar === void 0) return null;
+  return {
+    kind,
+    ...name !== void 0 ? { name } : {},
+    ...avatar !== void 0 ? { avatar } : {}
+  };
+}
+function isRawAssistantMessageEvent(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v;
+  if (o.type !== "assistant_message") return false;
+  if (typeof o.conversation_id !== "string") return false;
+  if (typeof o.content !== "string") return false;
+  if (!Array.isArray(o.turn_ids)) return false;
+  if (o.ts !== void 0 && o.ts !== null && typeof o.ts !== "number") return false;
+  if (o.content_type !== void 0 && o.content_type !== null && typeof o.content_type !== "string")
+    return false;
+  if (o.caption !== void 0 && o.caption !== null && typeof o.caption !== "string") return false;
+  return true;
+}
+function isAssistantMessageEvent(v) {
+  if (!isRawAssistantMessageEvent(v)) return false;
+  if (typeof v.ts !== "number") return false;
+  if (v.caption !== void 0 && typeof v.caption !== "string") return false;
+  if (v.content_type !== void 0 && v.content_type !== "text" && !isMediaContentType(v.content_type))
+    return false;
+  return v.turn_ids.every((t) => typeof t === "string");
+}
+function normalizeAssistantMessageEvent(raw, now = Date.now) {
+  const turnIds = raw.turn_ids.filter((t) => typeof t === "string");
+  return {
+    type: "assistant_message",
+    conversation_id: raw.conversation_id,
+    content: raw.content,
+    turn_ids: turnIds,
+    ts: typeof raw.ts === "number" && Number.isFinite(raw.ts) && raw.ts > 0 ? raw.ts : now(),
+    ...raw.content_type != null ? {
+      content_type: isMediaContentType(raw.content_type) ? raw.content_type : "text"
+    } : {},
+    ...raw.caption != null ? { caption: raw.caption } : {},
+    ...(() => {
+      const qr = sanitizeQuickReplies(raw.quick_replies);
+      return qr.length > 0 ? { quick_replies: qr } : {};
+    })(),
+    // Cualquier valor que no sea exactamente "human" cuenta como bot: es el
+    // default seguro — decirle al usuario que lo atiende una persona cuando no
+    // es cierto es peor que lo contrario.
+    ...raw.author === "human" ? { author: "human" } : {},
+    // La identidad SÓLO se propaga junto a `author: "human"`. Un `agent` en un
+    // mensaje del bot le pondría cara y nombre de persona a algo que escribió
+    // una máquina, que es exactamente la confusión que el handover evita.
+    ...(() => {
+      if (raw.author !== "human") return {};
+      const id = sanitizeAssistantIdentity(raw.agent);
+      return id !== null ? { agent: id } : {};
+    })()
+  };
+}
+function parseWidgetEvent(raw, now = Date.now) {
+  let v;
+  try {
+    v = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  return isRawAssistantMessageEvent(v) ? normalizeAssistantMessageEvent(v, now) : null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ALLOWED_UPLOAD_CONTENT_TYPES,
+  MAX_AGENT_NAME,
+  MAX_QUICK_REPLIES,
+  MAX_QUICK_REPLY_LABEL,
+  MAX_THEME_FONT_FAMILY,
+  MAX_THEME_LABEL,
+  MAX_THEME_TAGLINE,
+  MAX_THEME_TEXT_KEY,
+  MAX_THEME_TEXT_KEYS,
+  MAX_THEME_TEXT_VALUE,
+  MAX_UPLOAD_SIZE_BYTES,
+  MEDIA_CONTENT_TYPES,
+  SERVER_PROVIDED_THEME_FIELDS,
+  isAllowedUploadContentType,
+  isAssistantMessageEvent,
+  isMediaContentType,
+  isRawAssistantMessageEvent,
+  mediaKindForContentType,
+  normalizeAssistantMessageEvent,
+  parseWidgetEvent,
+  safeThemeColor,
+  safeThemeUrl,
+  sanitizeAssistantIdentity,
+  sanitizeQuickReplies,
+  sanitizeServerTheme
+});