@bircleai/widget-protocol 0.6.2 → 0.7.0

package/dist/index.cjs

@@ -21,9 +21,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ALLOWED_UPLOAD_CONTENT_TYPES: () => ALLOWED_UPLOAD_CONTENT_TYPES,
+  DEFAULT_SURVEY_TEXT_LEN: () => DEFAULT_SURVEY_TEXT_LEN,
   MAX_AGENT_NAME: () => MAX_AGENT_NAME,
   MAX_QUICK_REPLIES: () => MAX_QUICK_REPLIES,
   MAX_QUICK_REPLY_LABEL: () => MAX_QUICK_REPLY_LABEL,
+  MAX_SURVEY_CHOICE_OPTIONS: () => MAX_SURVEY_CHOICE_OPTIONS,
+  MAX_SURVEY_ID: () => MAX_SURVEY_ID,
+  MAX_SURVEY_LABEL: () => MAX_SURVEY_LABEL,
+  MAX_SURVEY_OPTION_LABEL: () => MAX_SURVEY_OPTION_LABEL,
+  MAX_SURVEY_STEPS: () => MAX_SURVEY_STEPS,
+  MAX_SURVEY_TEXT_LEN: () => MAX_SURVEY_TEXT_LEN,
   MAX_THEME_FONT_FAMILY: () => MAX_THEME_FONT_FAMILY,
   MAX_THEME_LABEL: () => MAX_THEME_LABEL,
   MAX_THEME_TAGLINE: () => MAX_THEME_TAGLINE,
@@ -44,7 +51,8 @@ __export(index_exports, {
   safeThemeUrl: () => safeThemeUrl,
   sanitizeAssistantIdentity: () => sanitizeAssistantIdentity,
   sanitizeQuickReplies: () => sanitizeQuickReplies,
-  sanitizeServerTheme: () => sanitizeServerTheme
+  sanitizeServerTheme: () => sanitizeServerTheme,
+  sanitizeSurvey: () => sanitizeSurvey
 });
 module.exports = __toCommonJS(index_exports);
 var MEDIA_CONTENT_TYPES = [
@@ -210,6 +218,76 @@ function sanitizeQuickReplies(raw) {
   }
   return out;
 }
+var MAX_SURVEY_STEPS = 5;
+var MAX_SURVEY_CHOICE_OPTIONS = 10;
+var MAX_SURVEY_LABEL = 100;
+var MAX_SURVEY_OPTION_LABEL = 30;
+var MAX_SURVEY_ID = 64;
+var MAX_SURVEY_TEXT_LEN = 1e3;
+var DEFAULT_SURVEY_TEXT_LEN = 500;
+function surveyId(value, max = MAX_SURVEY_ID) {
+  if (typeof value !== "string") return null;
+  const v = value.trim();
+  return v !== "" && v.length <= max ? v : null;
+}
+function sanitizeSurveyStep(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const o = raw;
+  const key = surveyId(o.key);
+  const label = surveyId(o.label, MAX_SURVEY_LABEL);
+  if (key === null || label === null) return null;
+  switch (o.type) {
+    case "stars":
+      return { type: "stars", key, label };
+    case "choice": {
+      if (!Array.isArray(o.options)) return null;
+      if (o.options.length === 0 || o.options.length > MAX_SURVEY_CHOICE_OPTIONS) return null;
+      const options = [];
+      for (const item of o.options) {
+        if (typeof item !== "object" || item === null) return null;
+        const opt = item;
+        const id = surveyId(opt.id);
+        const optLabel = surveyId(opt.label, MAX_SURVEY_OPTION_LABEL);
+        if (id === null || optLabel === null) return null;
+        options.push({ id, label: optLabel });
+      }
+      return { type: "choice", key, label, options };
+    }
+    case "text": {
+      const step = { type: "text", key, label };
+      if (typeof o.max_len === "number" && Number.isInteger(o.max_len) && o.max_len > 0 && o.max_len <= MAX_SURVEY_TEXT_LEN) {
+        step.max_len = o.max_len;
+      }
+      return step;
+    }
+    default:
+      return null;
+  }
+}
+function sanitizeSurvey(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const o = raw;
+  const survey_id = surveyId(o.survey_id);
+  const survey_msg_id = surveyId(o.survey_msg_id);
+  if (survey_id === null || survey_msg_id === null) return null;
+  if (typeof o.version !== "number" || !Number.isInteger(o.version) || o.version <= 0) return null;
+  if (!Array.isArray(o.steps)) return null;
+  if (o.steps.length === 0 || o.steps.length > MAX_SURVEY_STEPS) return null;
+  const steps = [];
+  for (const rawStep of o.steps) {
+    const step = sanitizeSurveyStep(rawStep);
+    if (step === null) return null;
+    steps.push(step);
+  }
+  let answered;
+  if (o.answered === void 0 || o.answered === null) answered = false;
+  else if (typeof o.answered === "boolean") answered = o.answered;
+  else return null;
+  const out = { survey_id, version: o.version, survey_msg_id, steps, answered };
+  const case_ref = surveyId(o.case_ref, MAX_SURVEY_LABEL);
+  if (case_ref !== null) out.case_ref = case_ref;
+  return out;
+}
 var MAX_AGENT_NAME = 40;
 function sanitizeAssistantIdentity(raw, kind = "human") {
   if (typeof raw !== "object" || raw === null) return null;
@@ -250,6 +328,7 @@ function isAssistantMessageEvent(v) {
   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;
+  if (v.survey !== void 0 && sanitizeSurvey(v.survey) === null) return false;
   return v.turn_ids.every((t) => typeof t === "string");
 }
 function normalizeAssistantMessageEvent(raw, now = Date.now) {
@@ -268,6 +347,13 @@ function normalizeAssistantMessageEvent(raw, now = Date.now) {
       const qr = sanitizeQuickReplies(raw.quick_replies);
       return qr.length > 0 ? { quick_replies: qr } : {};
     })(),
+    // La FUNCIÓN es la barrera (lección FAQs): un `survey` que no pasa el saneo
+    // no viaja — el mensaje conserva su `content` de texto fallback, así que
+    // una encuesta corrupta nunca cuesta la respuesta del agente.
+    ...(() => {
+      const sv = sanitizeSurvey(raw.survey);
+      return sv !== null ? { survey: sv } : {};
+    })(),
     // 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.
@@ -294,9 +380,16 @@ function parseWidgetEvent(raw, now = Date.now) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALLOWED_UPLOAD_CONTENT_TYPES,
+  DEFAULT_SURVEY_TEXT_LEN,
   MAX_AGENT_NAME,
   MAX_QUICK_REPLIES,
   MAX_QUICK_REPLY_LABEL,
+  MAX_SURVEY_CHOICE_OPTIONS,
+  MAX_SURVEY_ID,
+  MAX_SURVEY_LABEL,
+  MAX_SURVEY_OPTION_LABEL,
+  MAX_SURVEY_STEPS,
+  MAX_SURVEY_TEXT_LEN,
   MAX_THEME_FONT_FAMILY,
   MAX_THEME_LABEL,
   MAX_THEME_TAGLINE,
@@ -317,5 +410,6 @@ function parseWidgetEvent(raw, now = Date.now) {
   safeThemeUrl,
   sanitizeAssistantIdentity,
   sanitizeQuickReplies,
-  sanitizeServerTheme
+  sanitizeServerTheme,
+  sanitizeSurvey
 });

package/dist/index.d.cts

@@ -194,6 +194,16 @@ interface HistoryMessageDto {
      * elegir, al volver tiene que poder elegir igual.
      */
     quick_replies?: QuickReply[];
+    /**
+     * Encuesta embebida del mensaje (`content_type: "survey"`), con su estado
+     * `answered` denormalizado EN el item (Red Team #4): reabrir el chat no
+     * re-ofrece una encuesta contestada.
+     *
+     * Mismo trato que en el evento WS: el valor crudo del wire pasa por
+     * `sanitizeSurvey` en el consumidor ANTES de renderizar — el tipo documenta
+     * el contrato, la función es la barrera.
+     */
+    survey?: SurveyPayload;
     /** Ausente ⇒ `bot`. Ver `MessageAuthorKind`. */
     author?: MessageAuthorKind;
 }
@@ -500,6 +510,119 @@ declare const MAX_QUICK_REPLY_LABEL = 40;
  * respuesta del agente por un botón mal formado sería mucho peor.
  */
 declare function sanitizeQuickReplies(raw: unknown): QuickReply[];
+/** Tope de pasos de una encuesta (límite del contrato de `surveys`). */
+declare const MAX_SURVEY_STEPS = 5;
+/** Tope de opciones de un paso `choice`. */
+declare const MAX_SURVEY_CHOICE_OPTIONS = 10;
+/** Tope del `label` de un paso. */
+declare const MAX_SURVEY_LABEL = 100;
+/** Tope del `label` de una opción de `choice` (entra en un chip de teléfono). */
+declare const MAX_SURVEY_OPTION_LABEL = 30;
+/** Tope de los ids/keys (`survey_id`, `survey_msg_id`, `key`, `option.id`). */
+declare const MAX_SURVEY_ID = 64;
+/** Tope duro de `max_len` de un paso `text` (mismo límite que el builder). */
+declare const MAX_SURVEY_TEXT_LEN = 1000;
+/** `max_len` efectivo cuando la definición no trae uno. */
+declare const DEFAULT_SURVEY_TEXT_LEN = 500;
+/** Paso de estrellas 1–5 (el rating principal). */
+interface SurveyStepStars {
+    type: "stars";
+    /** Clave del answer en el POST de respuesta (ej. `rating`). */
+    key: string;
+    /** Pregunta a mostrar. Texto plano, nunca markup. */
+    label: string;
+}
+/** Una opción elegible de un paso `choice`. */
+interface SurveyChoiceOption {
+    /** Id estable de la opción — es lo que se REPORTA, el label es lo que se ve. */
+    id: string;
+    label: string;
+}
+/** Paso de opciones (motivo de la calificación), render tipo chips. */
+interface SurveyStepChoice {
+    type: "choice";
+    key: string;
+    label: string;
+    options: SurveyChoiceOption[];
+}
+/** Paso de texto libre (comentario). */
+interface SurveyStepText {
+    type: "text";
+    key: string;
+    label: string;
+    /** Tope de caracteres del comentario. Ausente ⇒ `DEFAULT_SURVEY_TEXT_LEN`. */
+    max_len?: number;
+}
+type SurveyStep = SurveyStepStars | SurveyStepChoice | SurveyStepText;
+/**
+ * Encuesta embebida en un mensaje del asistente. Campo hermano de
+ * `quick_replies` — viaja igual en el evento WS y en el DTO del historial.
+ */
+interface SurveyPayload {
+    /** Id de la DEFINICIÓN (tabla `surveys`). */
+    survey_id: string;
+    /** Versión de la definición con la que se generó este mensaje. */
+    version: number;
+    /**
+     * Id del MENSAJE survey. Es la clave con la que se responde
+     * (`POST /v1/widget/survey-response`) y con la que el server deduplica: el
+     * `response_id` determinístico sale de acá.
+     */
+    survey_msg_id: string;
+    /** Pasos a renderizar, en orden. Nunca vacío (sin pasos no hay encuesta). */
+    steps: SurveyStep[];
+    /** Referencia legible del caso que se califica ("¿Cómo resolvimos tu caso #123?"). */
+    case_ref?: string;
+    /**
+     * `true` = ya respondida. Denormalizado EN el item del mensaje (Red Team #4)
+     * para que la rehidratación no re-ofrezca una encuesta contestada — la UI la
+     * muestra en su estado "¡Gracias!" directamente.
+     */
+    answered: boolean;
+}
+/**
+ * Encuesta USABLE del wire, o `null`.
+ *
+ * ES LA BARRERA (no el tipo): todo `survey` que llega del server —evento WS o
+ * DTO de historial— pasa por acá antes de tocar la UI. Valida el contrato
+ * completo: ids/keys no vacíos ≤ 64, ≤ 5 pasos, choice con 1..10 opciones,
+ * labels ≤ 100 (≤ 30 en opciones), `version` entero positivo.
+ *
+ * TODO-O-NADA A PROPÓSITO (distinto de `sanitizeQuickReplies`): una encuesta
+ * con un paso corrupto no es "una encuesta más corta", es un instrumento que ya
+ * no coincide con la definición contra la que el Gateway valida la respuesta.
+ * Ofrecerla garantiza un 400 DESPUÉS de que el usuario contestó — peor que no
+ * ofrecerla (el mensaje conserva su `content` de texto fallback). NUNCA lanza.
+ *
+ * Tolerancias deliberadas (ausencia ≠ inválido):
+ *  - `answered` ausente o `null` ⇒ `false` (un productor viejo que no
+ *    denormaliza el estado no debe matar la encuesta); cualquier otro no-bool
+ *    (`"true"`) sí es inválido — adivinar el estado re-ofrecería encuestas
+ *    contestadas.
+ *  - `case_ref` es decorativo: no-string/vacío/gigante ⇒ se omite el campo,
+ *    la encuesta sigue (mismo criterio que el avatar en
+ *    `sanitizeAssistantIdentity`).
+ */
+declare function sanitizeSurvey(raw: unknown): SurveyPayload | null;
+/**
+ * `POST /v1/widget/survey-response` — body (auth: Bearer JWT de sesión, igual
+ * que `/messages`). `reason` debe ser un `option.id` de la definición y
+ * `comment` respetar el `max_len` — el Gateway valida contra la definición y
+ * responde 400 si no. 409 = ya respondida (el `response_id` determinístico hace
+ * el retry no-op). 404 = mensaje survey inexistente.
+ */
+interface SurveyResponseRequest {
+    survey_msg_id: string;
+    /** 1..5 (entero). */
+    rating: number;
+    /** `option.id` del paso choice, si el usuario eligió uno. */
+    reason?: string;
+    comment?: string;
+}
+/** `POST /v1/widget/survey-response` — respuesta 200. */
+interface SurveyResponseAck {
+    answered: true;
+}
 /**
  * Quién escribió un mensaje del lado del asistente.
  *
@@ -545,6 +668,13 @@ interface AssistantMessageEvent {
     ts: number;
     /** Botones para responder sin escribir. Ver `QuickReply`. */
     quick_replies?: QuickReply[];
+    /**
+     * Encuesta embebida (`content_type: "survey"`). Campo hermano de
+     * `quick_replies`, mismo patrón: sólo aparece si el wire trajo una encuesta
+     * VÁLIDA (pasó por `sanitizeSurvey`); un cliente que no la renderice sigue
+     * mostrando el `content` de texto fallback.
+     */
+    survey?: SurveyPayload;
     /**
      * Quién lo escribió. Ausente ⇒ `bot` (todo lo que existía antes de que hubiera
      * handover es del agente de IA).
@@ -569,12 +699,15 @@ interface AssistantMessageEvent {
  *  - `caption` `| null`: mismo motivo que `ts` (Python `None` ⇒ `null`).
  *  - `turn_ids` como `readonly unknown[]`: el guard solo verifica que sea un
  *    array; los elementos los filtra `normalizeAssistantMessageEvent`.
+ *  - `survey` como `unknown`: mismo tratamiento que `quick_replies` — el guard
+ *    no lo mira y `sanitizeSurvey` decide en la normalización.
  */
-type RawAssistantMessageEvent = Omit<AssistantMessageEvent, "ts" | "turn_ids" | "content_type" | "caption"> & {
+type RawAssistantMessageEvent = Omit<AssistantMessageEvent, "ts" | "turn_ids" | "content_type" | "caption" | "survey"> & {
     ts?: number | null;
     content_type?: string | null;
     caption?: string | null;
     turn_ids: readonly unknown[];
+    survey?: unknown;
 };
 type WidgetEvent = AssistantMessageEvent;
 /** Union cruda del wire (hoy un solo tipo de evento; `typing`/etc. se sumarían acá). */
@@ -665,4 +798,4 @@ declare function normalizeAssistantMessageEvent(raw: RawAssistantMessageEvent, n
  */
 declare function parseWidgetEvent(raw: string, now?: () => number): WidgetEvent | null;
 
-export { ALLOWED_UPLOAD_CONTENT_TYPES, type AssistantIdentity, type AssistantMessageEvent, type ChallengeUiConfig, type HistoryMessageDto, type HistoryResponse, 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, type MediaContentType, type MessageAccepted, type MessageAuthorKind, type MessageRequest, type QuickReply, type RawAssistantMessageEvent, type RawWidgetEvent, type RefreshRequest, type RefreshResponse, SERVER_PROVIDED_THEME_FIELDS, type ServerThemeResponse, type SessionRefreshRequest, type SessionRefreshResponse, type SessionRequest, type SessionResponse, type ThemeResponse, type UploadRequest, type UploadResponse, type WidgetEvent, isAllowedUploadContentType, isAssistantMessageEvent, isMediaContentType, isRawAssistantMessageEvent, mediaKindForContentType, normalizeAssistantMessageEvent, parseWidgetEvent, safeThemeColor, safeThemeUrl, sanitizeAssistantIdentity, sanitizeQuickReplies, sanitizeServerTheme };
+export { ALLOWED_UPLOAD_CONTENT_TYPES, type AssistantIdentity, type AssistantMessageEvent, type ChallengeUiConfig, DEFAULT_SURVEY_TEXT_LEN, type HistoryMessageDto, type HistoryResponse, MAX_AGENT_NAME, MAX_QUICK_REPLIES, MAX_QUICK_REPLY_LABEL, MAX_SURVEY_CHOICE_OPTIONS, MAX_SURVEY_ID, MAX_SURVEY_LABEL, MAX_SURVEY_OPTION_LABEL, MAX_SURVEY_STEPS, MAX_SURVEY_TEXT_LEN, 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, type MediaContentType, type MessageAccepted, type MessageAuthorKind, type MessageRequest, type QuickReply, type RawAssistantMessageEvent, type RawWidgetEvent, type RefreshRequest, type RefreshResponse, SERVER_PROVIDED_THEME_FIELDS, type ServerThemeResponse, type SessionRefreshRequest, type SessionRefreshResponse, type SessionRequest, type SessionResponse, type SurveyChoiceOption, type SurveyPayload, type SurveyResponseAck, type SurveyResponseRequest, type SurveyStep, type SurveyStepChoice, type SurveyStepStars, type SurveyStepText, type ThemeResponse, type UploadRequest, type UploadResponse, type WidgetEvent, isAllowedUploadContentType, isAssistantMessageEvent, isMediaContentType, isRawAssistantMessageEvent, mediaKindForContentType, normalizeAssistantMessageEvent, parseWidgetEvent, safeThemeColor, safeThemeUrl, sanitizeAssistantIdentity, sanitizeQuickReplies, sanitizeServerTheme, sanitizeSurvey };

package/dist/index.d.ts

@@ -194,6 +194,16 @@ interface HistoryMessageDto {
      * elegir, al volver tiene que poder elegir igual.
      */
     quick_replies?: QuickReply[];
+    /**
+     * Encuesta embebida del mensaje (`content_type: "survey"`), con su estado
+     * `answered` denormalizado EN el item (Red Team #4): reabrir el chat no
+     * re-ofrece una encuesta contestada.
+     *
+     * Mismo trato que en el evento WS: el valor crudo del wire pasa por
+     * `sanitizeSurvey` en el consumidor ANTES de renderizar — el tipo documenta
+     * el contrato, la función es la barrera.
+     */
+    survey?: SurveyPayload;
     /** Ausente ⇒ `bot`. Ver `MessageAuthorKind`. */
     author?: MessageAuthorKind;
 }
@@ -500,6 +510,119 @@ declare const MAX_QUICK_REPLY_LABEL = 40;
  * respuesta del agente por un botón mal formado sería mucho peor.
  */
 declare function sanitizeQuickReplies(raw: unknown): QuickReply[];
+/** Tope de pasos de una encuesta (límite del contrato de `surveys`). */
+declare const MAX_SURVEY_STEPS = 5;
+/** Tope de opciones de un paso `choice`. */
+declare const MAX_SURVEY_CHOICE_OPTIONS = 10;
+/** Tope del `label` de un paso. */
+declare const MAX_SURVEY_LABEL = 100;
+/** Tope del `label` de una opción de `choice` (entra en un chip de teléfono). */
+declare const MAX_SURVEY_OPTION_LABEL = 30;
+/** Tope de los ids/keys (`survey_id`, `survey_msg_id`, `key`, `option.id`). */
+declare const MAX_SURVEY_ID = 64;
+/** Tope duro de `max_len` de un paso `text` (mismo límite que el builder). */
+declare const MAX_SURVEY_TEXT_LEN = 1000;
+/** `max_len` efectivo cuando la definición no trae uno. */
+declare const DEFAULT_SURVEY_TEXT_LEN = 500;
+/** Paso de estrellas 1–5 (el rating principal). */
+interface SurveyStepStars {
+    type: "stars";
+    /** Clave del answer en el POST de respuesta (ej. `rating`). */
+    key: string;
+    /** Pregunta a mostrar. Texto plano, nunca markup. */
+    label: string;
+}
+/** Una opción elegible de un paso `choice`. */
+interface SurveyChoiceOption {
+    /** Id estable de la opción — es lo que se REPORTA, el label es lo que se ve. */
+    id: string;
+    label: string;
+}
+/** Paso de opciones (motivo de la calificación), render tipo chips. */
+interface SurveyStepChoice {
+    type: "choice";
+    key: string;
+    label: string;
+    options: SurveyChoiceOption[];
+}
+/** Paso de texto libre (comentario). */
+interface SurveyStepText {
+    type: "text";
+    key: string;
+    label: string;
+    /** Tope de caracteres del comentario. Ausente ⇒ `DEFAULT_SURVEY_TEXT_LEN`. */
+    max_len?: number;
+}
+type SurveyStep = SurveyStepStars | SurveyStepChoice | SurveyStepText;
+/**
+ * Encuesta embebida en un mensaje del asistente. Campo hermano de
+ * `quick_replies` — viaja igual en el evento WS y en el DTO del historial.
+ */
+interface SurveyPayload {
+    /** Id de la DEFINICIÓN (tabla `surveys`). */
+    survey_id: string;
+    /** Versión de la definición con la que se generó este mensaje. */
+    version: number;
+    /**
+     * Id del MENSAJE survey. Es la clave con la que se responde
+     * (`POST /v1/widget/survey-response`) y con la que el server deduplica: el
+     * `response_id` determinístico sale de acá.
+     */
+    survey_msg_id: string;
+    /** Pasos a renderizar, en orden. Nunca vacío (sin pasos no hay encuesta). */
+    steps: SurveyStep[];
+    /** Referencia legible del caso que se califica ("¿Cómo resolvimos tu caso #123?"). */
+    case_ref?: string;
+    /**
+     * `true` = ya respondida. Denormalizado EN el item del mensaje (Red Team #4)
+     * para que la rehidratación no re-ofrezca una encuesta contestada — la UI la
+     * muestra en su estado "¡Gracias!" directamente.
+     */
+    answered: boolean;
+}
+/**
+ * Encuesta USABLE del wire, o `null`.
+ *
+ * ES LA BARRERA (no el tipo): todo `survey` que llega del server —evento WS o
+ * DTO de historial— pasa por acá antes de tocar la UI. Valida el contrato
+ * completo: ids/keys no vacíos ≤ 64, ≤ 5 pasos, choice con 1..10 opciones,
+ * labels ≤ 100 (≤ 30 en opciones), `version` entero positivo.
+ *
+ * TODO-O-NADA A PROPÓSITO (distinto de `sanitizeQuickReplies`): una encuesta
+ * con un paso corrupto no es "una encuesta más corta", es un instrumento que ya
+ * no coincide con la definición contra la que el Gateway valida la respuesta.
+ * Ofrecerla garantiza un 400 DESPUÉS de que el usuario contestó — peor que no
+ * ofrecerla (el mensaje conserva su `content` de texto fallback). NUNCA lanza.
+ *
+ * Tolerancias deliberadas (ausencia ≠ inválido):
+ *  - `answered` ausente o `null` ⇒ `false` (un productor viejo que no
+ *    denormaliza el estado no debe matar la encuesta); cualquier otro no-bool
+ *    (`"true"`) sí es inválido — adivinar el estado re-ofrecería encuestas
+ *    contestadas.
+ *  - `case_ref` es decorativo: no-string/vacío/gigante ⇒ se omite el campo,
+ *    la encuesta sigue (mismo criterio que el avatar en
+ *    `sanitizeAssistantIdentity`).
+ */
+declare function sanitizeSurvey(raw: unknown): SurveyPayload | null;
+/**
+ * `POST /v1/widget/survey-response` — body (auth: Bearer JWT de sesión, igual
+ * que `/messages`). `reason` debe ser un `option.id` de la definición y
+ * `comment` respetar el `max_len` — el Gateway valida contra la definición y
+ * responde 400 si no. 409 = ya respondida (el `response_id` determinístico hace
+ * el retry no-op). 404 = mensaje survey inexistente.
+ */
+interface SurveyResponseRequest {
+    survey_msg_id: string;
+    /** 1..5 (entero). */
+    rating: number;
+    /** `option.id` del paso choice, si el usuario eligió uno. */
+    reason?: string;
+    comment?: string;
+}
+/** `POST /v1/widget/survey-response` — respuesta 200. */
+interface SurveyResponseAck {
+    answered: true;
+}
 /**
  * Quién escribió un mensaje del lado del asistente.
  *
@@ -545,6 +668,13 @@ interface AssistantMessageEvent {
     ts: number;
     /** Botones para responder sin escribir. Ver `QuickReply`. */
     quick_replies?: QuickReply[];
+    /**
+     * Encuesta embebida (`content_type: "survey"`). Campo hermano de
+     * `quick_replies`, mismo patrón: sólo aparece si el wire trajo una encuesta
+     * VÁLIDA (pasó por `sanitizeSurvey`); un cliente que no la renderice sigue
+     * mostrando el `content` de texto fallback.
+     */
+    survey?: SurveyPayload;
     /**
      * Quién lo escribió. Ausente ⇒ `bot` (todo lo que existía antes de que hubiera
      * handover es del agente de IA).
@@ -569,12 +699,15 @@ interface AssistantMessageEvent {
  *  - `caption` `| null`: mismo motivo que `ts` (Python `None` ⇒ `null`).
  *  - `turn_ids` como `readonly unknown[]`: el guard solo verifica que sea un
  *    array; los elementos los filtra `normalizeAssistantMessageEvent`.
+ *  - `survey` como `unknown`: mismo tratamiento que `quick_replies` — el guard
+ *    no lo mira y `sanitizeSurvey` decide en la normalización.
  */
-type RawAssistantMessageEvent = Omit<AssistantMessageEvent, "ts" | "turn_ids" | "content_type" | "caption"> & {
+type RawAssistantMessageEvent = Omit<AssistantMessageEvent, "ts" | "turn_ids" | "content_type" | "caption" | "survey"> & {
     ts?: number | null;
     content_type?: string | null;
     caption?: string | null;
     turn_ids: readonly unknown[];
+    survey?: unknown;
 };
 type WidgetEvent = AssistantMessageEvent;
 /** Union cruda del wire (hoy un solo tipo de evento; `typing`/etc. se sumarían acá). */
@@ -665,4 +798,4 @@ declare function normalizeAssistantMessageEvent(raw: RawAssistantMessageEvent, n
  */
 declare function parseWidgetEvent(raw: string, now?: () => number): WidgetEvent | null;
 
-export { ALLOWED_UPLOAD_CONTENT_TYPES, type AssistantIdentity, type AssistantMessageEvent, type ChallengeUiConfig, type HistoryMessageDto, type HistoryResponse, 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, type MediaContentType, type MessageAccepted, type MessageAuthorKind, type MessageRequest, type QuickReply, type RawAssistantMessageEvent, type RawWidgetEvent, type RefreshRequest, type RefreshResponse, SERVER_PROVIDED_THEME_FIELDS, type ServerThemeResponse, type SessionRefreshRequest, type SessionRefreshResponse, type SessionRequest, type SessionResponse, type ThemeResponse, type UploadRequest, type UploadResponse, type WidgetEvent, isAllowedUploadContentType, isAssistantMessageEvent, isMediaContentType, isRawAssistantMessageEvent, mediaKindForContentType, normalizeAssistantMessageEvent, parseWidgetEvent, safeThemeColor, safeThemeUrl, sanitizeAssistantIdentity, sanitizeQuickReplies, sanitizeServerTheme };
+export { ALLOWED_UPLOAD_CONTENT_TYPES, type AssistantIdentity, type AssistantMessageEvent, type ChallengeUiConfig, DEFAULT_SURVEY_TEXT_LEN, type HistoryMessageDto, type HistoryResponse, MAX_AGENT_NAME, MAX_QUICK_REPLIES, MAX_QUICK_REPLY_LABEL, MAX_SURVEY_CHOICE_OPTIONS, MAX_SURVEY_ID, MAX_SURVEY_LABEL, MAX_SURVEY_OPTION_LABEL, MAX_SURVEY_STEPS, MAX_SURVEY_TEXT_LEN, 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, type MediaContentType, type MessageAccepted, type MessageAuthorKind, type MessageRequest, type QuickReply, type RawAssistantMessageEvent, type RawWidgetEvent, type RefreshRequest, type RefreshResponse, SERVER_PROVIDED_THEME_FIELDS, type ServerThemeResponse, type SessionRefreshRequest, type SessionRefreshResponse, type SessionRequest, type SessionResponse, type SurveyChoiceOption, type SurveyPayload, type SurveyResponseAck, type SurveyResponseRequest, type SurveyStep, type SurveyStepChoice, type SurveyStepStars, type SurveyStepText, type ThemeResponse, type UploadRequest, type UploadResponse, type WidgetEvent, isAllowedUploadContentType, isAssistantMessageEvent, isMediaContentType, isRawAssistantMessageEvent, mediaKindForContentType, normalizeAssistantMessageEvent, parseWidgetEvent, safeThemeColor, safeThemeUrl, sanitizeAssistantIdentity, sanitizeQuickReplies, sanitizeServerTheme, sanitizeSurvey };

package/dist/index.js

@@ -162,6 +162,76 @@ function sanitizeQuickReplies(raw) {
   }
   return out;
 }
+var MAX_SURVEY_STEPS = 5;
+var MAX_SURVEY_CHOICE_OPTIONS = 10;
+var MAX_SURVEY_LABEL = 100;
+var MAX_SURVEY_OPTION_LABEL = 30;
+var MAX_SURVEY_ID = 64;
+var MAX_SURVEY_TEXT_LEN = 1e3;
+var DEFAULT_SURVEY_TEXT_LEN = 500;
+function surveyId(value, max = MAX_SURVEY_ID) {
+  if (typeof value !== "string") return null;
+  const v = value.trim();
+  return v !== "" && v.length <= max ? v : null;
+}
+function sanitizeSurveyStep(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const o = raw;
+  const key = surveyId(o.key);
+  const label = surveyId(o.label, MAX_SURVEY_LABEL);
+  if (key === null || label === null) return null;
+  switch (o.type) {
+    case "stars":
+      return { type: "stars", key, label };
+    case "choice": {
+      if (!Array.isArray(o.options)) return null;
+      if (o.options.length === 0 || o.options.length > MAX_SURVEY_CHOICE_OPTIONS) return null;
+      const options = [];
+      for (const item of o.options) {
+        if (typeof item !== "object" || item === null) return null;
+        const opt = item;
+        const id = surveyId(opt.id);
+        const optLabel = surveyId(opt.label, MAX_SURVEY_OPTION_LABEL);
+        if (id === null || optLabel === null) return null;
+        options.push({ id, label: optLabel });
+      }
+      return { type: "choice", key, label, options };
+    }
+    case "text": {
+      const step = { type: "text", key, label };
+      if (typeof o.max_len === "number" && Number.isInteger(o.max_len) && o.max_len > 0 && o.max_len <= MAX_SURVEY_TEXT_LEN) {
+        step.max_len = o.max_len;
+      }
+      return step;
+    }
+    default:
+      return null;
+  }
+}
+function sanitizeSurvey(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const o = raw;
+  const survey_id = surveyId(o.survey_id);
+  const survey_msg_id = surveyId(o.survey_msg_id);
+  if (survey_id === null || survey_msg_id === null) return null;
+  if (typeof o.version !== "number" || !Number.isInteger(o.version) || o.version <= 0) return null;
+  if (!Array.isArray(o.steps)) return null;
+  if (o.steps.length === 0 || o.steps.length > MAX_SURVEY_STEPS) return null;
+  const steps = [];
+  for (const rawStep of o.steps) {
+    const step = sanitizeSurveyStep(rawStep);
+    if (step === null) return null;
+    steps.push(step);
+  }
+  let answered;
+  if (o.answered === void 0 || o.answered === null) answered = false;
+  else if (typeof o.answered === "boolean") answered = o.answered;
+  else return null;
+  const out = { survey_id, version: o.version, survey_msg_id, steps, answered };
+  const case_ref = surveyId(o.case_ref, MAX_SURVEY_LABEL);
+  if (case_ref !== null) out.case_ref = case_ref;
+  return out;
+}
 var MAX_AGENT_NAME = 40;
 function sanitizeAssistantIdentity(raw, kind = "human") {
   if (typeof raw !== "object" || raw === null) return null;
@@ -202,6 +272,7 @@ function isAssistantMessageEvent(v) {
   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;
+  if (v.survey !== void 0 && sanitizeSurvey(v.survey) === null) return false;
   return v.turn_ids.every((t) => typeof t === "string");
 }
 function normalizeAssistantMessageEvent(raw, now = Date.now) {
@@ -220,6 +291,13 @@ function normalizeAssistantMessageEvent(raw, now = Date.now) {
       const qr = sanitizeQuickReplies(raw.quick_replies);
       return qr.length > 0 ? { quick_replies: qr } : {};
     })(),
+    // La FUNCIÓN es la barrera (lección FAQs): un `survey` que no pasa el saneo
+    // no viaja — el mensaje conserva su `content` de texto fallback, así que
+    // una encuesta corrupta nunca cuesta la respuesta del agente.
+    ...(() => {
+      const sv = sanitizeSurvey(raw.survey);
+      return sv !== null ? { survey: sv } : {};
+    })(),
     // 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.
@@ -245,9 +323,16 @@ function parseWidgetEvent(raw, now = Date.now) {
 }
 export {
   ALLOWED_UPLOAD_CONTENT_TYPES,
+  DEFAULT_SURVEY_TEXT_LEN,
   MAX_AGENT_NAME,
   MAX_QUICK_REPLIES,
   MAX_QUICK_REPLY_LABEL,
+  MAX_SURVEY_CHOICE_OPTIONS,
+  MAX_SURVEY_ID,
+  MAX_SURVEY_LABEL,
+  MAX_SURVEY_OPTION_LABEL,
+  MAX_SURVEY_STEPS,
+  MAX_SURVEY_TEXT_LEN,
   MAX_THEME_FONT_FAMILY,
   MAX_THEME_LABEL,
   MAX_THEME_TAGLINE,
@@ -268,5 +353,6 @@ export {
   safeThemeUrl,
   sanitizeAssistantIdentity,
   sanitizeQuickReplies,
-  sanitizeServerTheme
+  sanitizeServerTheme,
+  sanitizeSurvey
 };

package/package.json

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