@bircleai/widget-protocol 0.4.3

package/dist/index.d.cts

@@ -0,0 +1,657 @@
+/**
+ * `@bircleai/widget-protocol` — contrato compartido del Chat Gateway de BircleAI
+ * (endpoints `/v1/widget/*` + WebSocket). Fuente de verdad del contrato DENTRO
+ * DE ESTE REPO: hoy lo consumen el core del SDK y los wrappers de framework
+ * (React); a futuro lo consumirán también el widget web embebible y el SDK
+ * mobile. No inventar campos: reflejar exactamente lo que expone el Gateway.
+ *
+ * POR QUÉ este paquete: el widget web mantiene HOY su PROPIA copia del contrato
+ * (`bircle-web-widget/src/protocol/index.ts`) y las dos copias divergieron — el
+ * widget tenía media (`content_type`/`caption` en el request, `UploadRequest`/
+ * `UploadResponse`) y campos de theme que acá no existían, y cada lado tiene su
+ * propio type-guard del MISMO envelope de WS con criterios distintos de
+ * aceptación (el del widget, por ejemplo, no valida `ts` en absoluto). Eso es un
+ * bug latente: un evento que un lado acepta el otro lo descarta EN SILENCIO.
+ * Este archivo es el superset unificado; cualquier campo nuevo se agrega ACÁ
+ * primero.
+ *
+ * ALCANCE REAL DEL "GUARD ÚNICO" (no sobrevender): mientras el paquete no esté
+ * publicado, el guard único vale SOLO para los consumidores de este monorepo. La
+ * copia del widget web sigue viva e independiente.
+ * TODO (follow-up, ver tarea "SDK follow-ups"): publicar `@bircleai/widget-protocol`
+ * en el registry privado y reemplazar `bircle-web-widget/src/protocol/index.ts`
+ * por un import de este paquete — recién ahí la unificación es efectiva.
+ */
+/** `POST /v1/widget/session` — body. */
+interface SessionRequest {
+    embedKey: string;
+    /** Token del challenge (WAF Challenge / Turnstile en prod; DevChallengeVerifier en staging). */
+    challengeToken?: string;
+    /**
+     * Origen del sitio/app que embebe el chat, declarado por el CLIENTE. Es el
+     * valor que el Gateway valida contra `allowed_origins` del tenant cuando el
+     * header `Origin` NO es el del tenant (caso del frame servido desde nuestro
+     * CDN, y caso de una app nativa).
+     *
+     * OJO — declarar esto NO reemplaza al header `Origin`: `bootstrapWidgetSession`
+     * rechaza con `origin_not_allowed` ANTES de mirar `host_origin` si el request
+     * llega sin `Origin` (deny-by-default explícito, para que un cliente no-browser
+     * no obtenga token con solo agregar un campo al body). Ver el bloque
+     * "ORIGIN EN CLIENTES NATIVOS" del README del SDK.
+     */
+    host_origin?: string;
+    /**
+     * Identificador OPACO y persistente del visitante, generado y guardado por el
+     * cliente (`localStorage` en web, `AsyncStorage`/Keychain en mobile). Si cumple
+     * el formato del contrato (`^[A-Za-z0-9_-]{22,64}$`) y el Gateway tiene el
+     * secreto configurado, el `user_ref` se deriva determinísticamente de él ⇒ el
+     * MISMO usuario retoma SU conversación entre visitas / reinicios de la app.
+     *
+     * Un valor ausente o inválido NO falla la request: el Gateway cae al `user_ref`
+     * aleatorio de siempre — o sea, la continuidad se pierde EN SILENCIO. Por eso
+     * el formato lo valida también el cliente (`isValidVisitorId` en el core).
+     *
+     * SEGURIDAD: es un bearer de facto (quien lo tenga lee esa conversación). No
+     * loguearlo, no mandarlo a terceros, no ponerlo en una URL.
+     */
+    visitor_id?: string;
+    /**
+     * Id del usuario LOGUEADO en el sistema del cliente (1..128 chars, sin espacios
+     * en los bordes). Cuando viene con una `user_hash` que el Gateway puede
+     * verificar, el `user_ref` se deriva de ESTE valor y no del origen ⇒ la misma
+     * persona retoma su conversación desde cualquier browser o dispositivo.
+     *
+     * Un valor vacío o de solo espacios NO es un error: el Gateway lo trata como
+     * AUSENTE ("no hay nadie logueado") y da una sesión anónima. Eso permite montar
+     * el chat en una página donde el login es opcional sin ramificar la integración.
+     *
+     * ⚠️ NUNCA se manda solo: sin `user_hash` verificable el Gateway responde 403
+     * (ver ahí).
+     */
+    user_id?: string;
+    /**
+     * Firma del `user_id`: HMAC-SHA256 en HEX (64 chars, case-insensitive) del
+     * `user_id` con el identity secret del tenant.
+     *
+     * POR QUÉ HACE FALTA UNA FIRMA: sin ella, "soy el usuario 42" sería un dato que
+     * declara el cliente, y cualquiera leería la conversación del usuario 42
+     * cambiando un valor. El secreto vive SOLO en el backend del cliente y el hash
+     * lo calcula ESE backend — calcularlo en el browser o en la app significa poner
+     * el secreto ahí, y entonces la firma no prueba nada.
+     *
+     * FALLA CERRADO A PROPÓSITO: si viene un `user_id` cuya firma el Gateway no
+     * puede verificar (falta, no matchea, el tenant no tiene secreto configurado),
+     * la respuesta es 403 — NO degrada a sesión anónima. Degradar en silencio haría
+     * que el sitio crea que ató la conversación a su usuario logueado cuando en
+     * realidad quedó suelta.
+     */
+    user_hash?: string;
+}
+/** `POST /v1/widget/session` — respuesta 200. */
+interface SessionResponse {
+    token: string;
+    expiresInSeconds?: number;
+    /**
+     * Refresh token para renovar la sesión SIN volver a resolver el challenge
+     * (`POST /v1/widget/session/refresh`).
+     *
+     * POR QUÉ EXISTE (y por qué el cliente lo tiene que usar): la renovación de
+     * hoy es reactiva y consiste en RE-BOOTSTRAPEAR mandando OTRA VEZ el mismo
+     * `challengeToken`. Eso solo funciona porque el challenge de staging es
+     * estático. Un challenge REAL (Turnstile / WAF Challenge) es ONE-SHOT: el
+     * segundo uso del mismo token lo rechaza el proveedor, así que el día que se
+     * active, el primer 401 dejaría al cliente en un 403 permanente.
+     *
+     * OPCIONAL A PROPÓSITO: el Gateway lo emite solo si el operador tiene prendido
+     * `WIDGET_REFRESH_TOKEN_ENABLED` (default true, pero apagable). Con la feature
+     * apagada la respuesta es IDÉNTICA a la de antes —el campo ni aparece— y el
+     * cliente tiene que seguir funcionando con el re-bootstrap de siempre.
+     *
+     * ⚠️ El nombre en el wire es `refreshToken` (camelCase), igual que `token` y
+     * `expiresInSeconds` — NO `refresh_token`. El endpoint de canje sí acepta las
+     * dos formas en el body, pero la RESPUESTA del bootstrap usa solo esta.
+     *
+     * SEGURIDAD: es un bearer de larga vida. Va SOLO en memoria (nunca
+     * localStorage, cookie, AsyncStorage ni Keychain), nunca en una URL y nunca en
+     * un log. Tiene un `scope` propio (`widget:refresh`): usarlo como token de
+     * sesión en `/messages` da 403.
+     */
+    refreshToken?: string;
+    /** TTL del `refreshToken` en segundos. Solo viene si vino `refreshToken`. */
+    refreshExpiresInSeconds?: number;
+}
+/**
+ * `POST /v1/widget/session/refresh` — body. Canjea un refresh token por un par
+ * (sesión + refresh) NUEVO, sin authorizer y SIN challenge.
+ *
+ * El token va en el BODY, no en `Authorization`: el Gateway acepta las dos
+ * formas, pero mandarlo como bearer invita a que un interceptor/proxy lo trate
+ * como credencial de sesión y lo reenvíe a otras rutas. Acá es un dato del
+ * request, no una credencial de transporte.
+ *
+ * EL ORIGEN SÍ IMPORTA: `refreshWidgetSession` compara el `Origin` del request
+ * contra el claim `origin` que quedó firmado en el token (`origin_mismatch`) —
+ * el MISMO pinning que el resto del gateway. En browser lo pone el browser; en
+ * React Native NO hay `Origin`, así que el cliente tiene que mandarlo a mano
+ * (ver `appOrigin` en `@bircleai/chat-widget-core`). Sin eso, el canje da 401.
+ */
+interface SessionRefreshRequest {
+    refreshToken: string;
+}
+/**
+ * `POST /v1/widget/session/refresh` — respuesta 200.
+ *
+ * A diferencia de `SessionResponse`, acá los cuatro campos son OBLIGATORIOS: si
+ * el endpoint contesta 200 es porque emitió el par completo (ver
+ * `handleRefreshRequest`). Un backend que no tenga la feature no devuelve un 200
+ * incompleto: devuelve 404/401 y el cliente cae al re-bootstrap.
+ *
+ * ROTACIÓN DE UN SOLO USO (lo que hace delicado al cliente): el refresh que se
+ * canjeó queda QUEMADO — reusarlo da 401. Por eso el `refreshToken` de esta
+ * respuesta REEMPLAZA al anterior, y por eso no puede haber dos canjes
+ * concurrentes del mismo token (el segundo pierde la sesión). El `user_ref` y la
+ * familia (`sid`) se conservan: el visitante no pierde su conversación.
+ */
+interface SessionRefreshResponse {
+    token: string;
+    expiresInSeconds: number;
+    refreshToken: string;
+    refreshExpiresInSeconds: number;
+}
+/** `POST /v1/widget/messages` — body. El tenant y el conversation_id se resuelven server-side desde el JWT. */
+/**
+ * `GET /v1/widget/messages` — historial de la conversación del token, para
+ * rehidratar la UI al reabrir el chat.
+ *
+ * La media viene RE-FIRMADA con una presignada GET fresca cuando el Gateway
+ * puede hacerlo; si no puede, llega saneada (sin firma) y el cliente muestra un
+ * placeholder en vez de un 403.
+ */
+interface HistoryResponse {
+    messages: HistoryMessageDto[];
+}
+interface HistoryMessageDto {
+    role: "user" | "assistant";
+    content: string;
+    content_type?: string;
+    caption?: string;
+    /** ISO-8601. Opcional: los mensajes viejos pueden no tenerlo. */
+    ts?: string;
+    /**
+     * Botones del mensaje, si el server los persistió.
+     *
+     * Va en el historial y no sólo en el evento del WebSocket para que reabrir el
+     * chat no borre los botones del último mensaje: si el usuario cerró sin
+     * elegir, al volver tiene que poder elegir igual.
+     */
+    quick_replies?: QuickReply[];
+    /** Ausente ⇒ `bot`. Ver `MessageAuthorKind`. */
+    author?: MessageAuthorKind;
+}
+/**
+ * Alias históricos: el widget web nombraba así a los tipos del refresh. Se
+ * mantienen para que migrar al paquete no obligue a tocar todos sus call sites
+ * en el mismo commit.
+ */
+type RefreshRequest = SessionRefreshRequest;
+type RefreshResponse = SessionRefreshResponse;
+interface MessageRequest {
+    content: string;
+    turn_id: string;
+    /**
+     * Ausente ⇒ texto (backward-compat: el Gateway trata el mensaje igual que
+     * hoy). Para media, `content` lleva la `media_url` devuelta por
+     * `POST /v1/widget/uploads` y `content_type` el kind del media.
+     */
+    content_type?: "text" | MediaContentType;
+    /** Leyenda opcional del media (el Gateway la valida y la UI la renderiza como textContent, nunca como markup). */
+    caption?: string;
+}
+/** `POST /v1/widget/messages` — respuesta 202 (la respuesta del agente llega por WebSocket). */
+interface MessageAccepted {
+    accepted: true;
+    turn_id: string;
+}
+/** Tipos de contenido de un mensaje (cross-canal). Ausente/"text" ⇒ texto; para media la URL va en `content`. */
+type MediaContentType = "image" | "audio" | "video" | "document";
+/**
+ * Kinds de media que el SDK sabe renderizar HOY. Exportado como const para que
+ * el narrowing del normalizador y los tests usen la MISMA lista (sin duplicarla).
+ */
+declare const MEDIA_CONTENT_TYPES: readonly ["image", "audio", "video", "document"];
+/**
+ * ¿El valor crudo del wire es un kind de media conocido?
+ *
+ * POR QUÉ existe: el guard del envelope valida TIPOS, no dominios (un kind nuevo
+ * del server no debe romper a los clientes viejos), así que `content_type` crudo
+ * es `string`. Pero el tipo canónico promete `"text" | MediaContentType`: sin
+ * este narrowing, un `"sticker"` del server viajaría con ese valor hasta un
+ * `switch` exhaustivo del consumidor, que TS considera imposible. Acá se cumple
+ * de verdad el "kind desconocido ⇒ el renderer degrada a texto".
+ */
+declare function isMediaContentType(v: unknown): v is MediaContentType;
+/**
+ * `POST /v1/widget/uploads` — body. Pide una URL presignada de subida directa a
+ * S3 (el binario NUNCA pasa por el Gateway). El tenant se resuelve server-side
+ * desde el JWT (header `authorization: Bearer <session token>`).
+ *
+ * `content_type` va contra una allow-list ESTRICTA server-side (imagen/audio/
+ * video/pdf): un tipo fuera de la lista → 400. `size_bytes` es un hint
+ * OPCIONAL, validado best-effort (<= 10 MiB); el presigned PUT no firma
+ * `Content-Length`, así que NO es un tope duro.
+ */
+interface UploadRequest {
+    content_type: string;
+    /** Tamaño del archivo en bytes (hint para que el server pueda acotar el presigned PUT). */
+    size_bytes?: number;
+}
+/**
+ * `POST /v1/widget/uploads` — respuesta 200. `upload_url` es el presigned PUT
+ * (subida directa a S3, con el MISMO header `content-type` que se pidió);
+ * `media_url` es la URL final (https, bucket privado) con la que después se
+ * manda el mensaje en `MessageRequest.content`.
+ *
+ * `expires_in` (segundos) hoy el Gateway lo manda SIEMPRE, pero se tipa
+ * opcional a propósito: es un dato informativo y no queremos que el cliente
+ * dependa de su presencia.
+ */
+interface UploadResponse {
+    upload_url: string;
+    media_url: string;
+    media_kind: MediaContentType;
+    expires_in?: number;
+}
+/**
+ * Espejo cliente-side de la allow-list ESTRICTA de MIME types de
+ * `WidgetChatGateway/uploads.ts::ALLOWED_UPLOAD_CONTENT_TYPES`.
+ *
+ * POR QUÉ existe una copia (y por qué no es una duplicación gratuita): el
+ * server es la fuente de verdad y rechaza con 400 cualquier tipo fuera de la
+ * lista. En web eso es un molestia; en MOBILE es un pozo, porque el MIME lo
+ * elige el RECORDER/PICKER del sistema y varía por plataforma — un
+ * `expo-av` mal configurado en Android graba `.3gp` (`audio/3gpp`), que NO está
+ * en la lista, y el dev se come un 400 opaco DESPUÉS de que el usuario grabó la
+ * nota de voz. Con este mapa el SDK falla antes de pedir el presigned, con un
+ * error que dice qué tipo mandó y cuáles se aceptan.
+ *
+ * Si el Gateway agrega un tipo, esta lista queda CORTA (rechaza de más), nunca
+ * larga: el server sigue validando igual. Es el sentido seguro del desfasaje.
+ */
+declare const ALLOWED_UPLOAD_CONTENT_TYPES: Readonly<Record<string, MediaContentType>>;
+/**
+ * Tope que el Gateway aplica al hint `size_bytes` (10 MiB). NO es un tope duro
+ * de S3 (el presigned PUT no firma `Content-Length`), pero mandar un
+ * `size_bytes` mayor da 400, así que el cliente lo chequea antes.
+ */
+declare const MAX_UPLOAD_SIZE_BYTES: number;
+/** `true` si el Gateway acepta ese MIME en `POST /v1/widget/uploads`. */
+declare function isAllowedUploadContentType(contentType: string): boolean;
+/** Kind de media que el Gateway va a asignar a ese MIME, o `null` si no está permitido. */
+declare function mediaKindForContentType(contentType: string): MediaContentType | null;
+/**
+ * `GET /v1/widget/theme?embedKey=` — solo campos de UI (branding por proyecto).
+ *
+ * IMPORTANTE — qué manda el server y qué NO: el Gateway arma la respuesta con
+ * un WHITELIST EXPLÍCITO (`WidgetChatGateway/theme.ts::toUiView`), no con un
+ * spread del theme config crudo. Ese whitelist expone los campos de BRANDING
+ * (ver `SERVER_PROVIDED_THEME_FIELDS`) y stripea todo lo demás.
+ *
+ * POR QUÉ EL WHITELIST CRECIÓ A TODO EL BRANDING: hasta la 0.3.0 sólo viajaban
+ * seis campos y el resto (`assistantName`, `colorScheme`, `accentColor`…) sólo
+ * se podía pasar en el `Bircle('init', …)` del sitio del cliente. O sea que
+ * cambiarle el nombre del asistente al chat de un banco le exigía a ELLOS tocar
+ * y redesplegar su sitio. Con el contrato completo eso se configura desde el
+ * Dashboard y llega solo.
+ *
+ * Los campos que SIGUEN siendo client-only están marcados abajo uno por uno,
+ * con el motivo. No son branding: son allow-lists de seguridad o decisiones de
+ * layout del host.
+ */
+/**
+ * Configuración del challenge anti-bot que el cliente tiene que resolver ANTES
+ * del bootstrap.
+ *
+ * Viaja en el `/theme` y no en la config del snippet a propósito: cambiar o
+ * apagar el mecanismo no debe obligar a que cada cliente redespliegue su sitio.
+ */
+interface ChallengeUiConfig {
+    /**
+     * Hoy sólo `"pow"` (prueba de trabajo). Un valor desconocido se ignora — el
+     * cliente no manda token y el Gateway, que es quien decide, rechaza. O sea:
+     * fail-open del cliente, fail-closed del server.
+     */
+    provider: string;
+}
+interface ThemeResponse {
+    /** Color de marca. `#rgb` o `#rrggbb`. Pasa por `safeThemeColor`. */
+    primaryColor?: string;
+    /** URL https del ícono del launcher. */
+    launcherIcon?: string;
+    position?: "bottom-right" | "bottom-left";
+    /** URL https del logo del header. */
+    headerLogo?: string;
+    locale?: string;
+    texts?: Record<string, string>;
+    /** Color de acento (botón de enviar, foco del input). Como `primaryColor`, pasa por `safeThemeColor`. */
+    accentColor?: string;
+    /** Familia tipográfica de la UI del chat (≤ 120 chars). */
+    fontFamily?: string;
+    /** Esquema de color forzado. Si se omite, se resuelve por `prefers-color-scheme` (fallback "light"). */
+    colorScheme?: "light" | "dark";
+    /** Nombre que muestra el header ("quién responde"). Se renderiza como `textContent`. */
+    assistantName?: string;
+    /** Subtítulo/estado del header cuando la conexión está abierta (ej. "En línea · responde al instante"). `textContent`. */
+    assistantTagline?: string;
+    /** URL del avatar del asistente (branding del cliente). Se setea como `.src` de un `<img>`, nunca interpolado en HTML. */
+    assistantAvatar?: string;
+    /** Etiqueta del launcher (burbuja de apertura). Consumida por el loader (R2). */
+    launcherLabel?: string;
+    /** `false` oculta el footer "Powered by BircleAI". Cualquier otro valor lo muestra. */
+    poweredBy?: boolean;
+    /**
+     * Hosts https permitidos para renderizar media rica (allow-list; lo consume la
+     * UI, no el core).
+     *
+     * NO entra al whitelist de branding A PROPÓSITO: es una decisión de SEGURIDAD,
+     * no de estética. Dejar que el theme del tenant la escriba equivale a dejar que
+     * el tenant amplíe desde dónde el widget carga contenido — el mismo motivo por
+     * el que `mediaBucketHost` se deriva server-side. Ver `toUiView`.
+     */
+    mediaHosts?: string[];
+    /**
+     * Host del bucket de media, para poder renderizar la del HISTORIAL — que el
+     * Gateway devuelve con una presignada GET fresca.
+     *
+     * Va aparte de `mediaHosts` a propósito: habilitar el historial NO debe
+     * ampliar la allow-list con la que se renderiza la media ENTRANTE del agente
+     * (contenido no confiable). Sin este campo la media histórica cae al
+     * placeholder — aditivo y safe-by-default.
+     */
+    mediaBucketHost?: string;
+    /**
+     * Challenge anti-bot a resolver antes del bootstrap. Ausente ⇒ no hay ninguno
+     * (staging con el verificador `dev`).
+     */
+    challenge?: ChallengeUiConfig;
+    /**
+     * Pantalla completa en teléfonos (debajo de 480px de ancho): el panel ocupa el
+     * viewport entero, sin bordes redondeados ni sombra, y el launcher se oculta
+     * mientras está abierto.
+     *
+     * Lo consume el LOADER del widget web, no la app del iframe: el tamaño y la
+     * posición del iframe los decide la página host (el frame no se puede
+     * redimensionar solo). En el SDK mobile no aplica.
+     */
+    mobileFullscreen?: boolean;
+}
+/**
+ * Campos que el Gateway SÍ devuelve en `GET /v1/widget/theme` (whitelist de
+ * `theme.ts::toUiView`). Exportado para que la UI/los tests puedan distinguir
+ * "lo que vino del server" de la config local sin duplicar la lista a mano.
+ *
+ * Es TODO el branding del contrato del tema (v1) y nada más. Lo que quedó
+ * afuera está afuera por un motivo, no por olvido:
+ *  - `mediaHosts` / `mediaBucketHost`: allow-lists de seguridad. La segunda la
+ *    DERIVA el Gateway de la misma fuente que el presigner, después del
+ *    whitelist, justo para que un theme del tenant no la pueda inyectar.
+ *  - `challenge`: lo decide el operador, no el tenant. Mismo tratamiento.
+ *  - `mobileFullscreen`: layout del host web, no branding.
+ *
+ * Si se agrega un campo acá hay que agregarlo TAMBIÉN en las otras dos listas
+ * 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"];
+/** 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. */
+declare const MAX_THEME_LABEL = 40;
+/** Tope de `assistantTagline` (el subtítulo del header). */
+declare const MAX_THEME_TAGLINE = 80;
+/** Tope de `fontFamily` (una pila de fuentes razonable entra de sobra). */
+declare const MAX_THEME_FONT_FAMILY = 120;
+/** Tope de claves en `texts`. La UI tiene ~25 textos; 40 deja margen sin volverse un blob. */
+declare const MAX_THEME_TEXT_KEYS = 40;
+/** Tope de una clave de `texts`. */
+declare const MAX_THEME_TEXT_KEY = 60;
+/** Tope de un valor de `texts`. */
+declare const MAX_THEME_TEXT_VALUE = 200;
+/**
+ * Color usable para el tema: `#rgb` o `#rrggbb`, nada más.
+ *
+ * Devuelve `null` en vez de un default para que quien llama decida a qué caer
+ * (cada superficie tiene el suyo). Se rechaza todo lo demás —incluido
+ * `rgb()`/`hsl()`— porque en web el valor termina interpolado en una custom
+ * property de CSS: cuanto más chico el dominio aceptado, menos superficie hay
+ * para un `);…` inyectado. Es exactamente lo que valida el contrato del tema.
+ */
+declare function safeThemeColor(value: unknown): string | null;
+/**
+ * URL https absoluta, o `null`.
+ *
+ * `new URL` y no un regex: parsear es lo único que distingue de verdad un
+ * esquema de un prefijo que se le parece (`https:/\/evil` y compañía). Sólo
+ * `https:` — un `http://` en el logo hace que el browser marque contenido mixto
+ * (y en iOS ATS directamente falla el request), y `javascript:`/`data:` en algo
+ * que termina en un `<img src>` es un vector de XSS en el sitio del cliente.
+ */
+declare function safeThemeUrl(value: unknown): string | null;
+/**
+ * Tema del server, saneado campo por campo contra el contrato.
+ *
+ * ES EL ÚNICO CAMINO DE ENTRADA del branding remoto: lo que no sale de acá no
+ * debería aplicarse. Devuelve un objeto NUEVO con sólo los campos válidos —
+ * nunca el input— así ninguna clave extra del wire (una que el server agregue
+ * mañana, o una que un theme viejo tenga guardada) se cuela por un spread.
+ *
+ * NUNCA LANZA Y NUNCA RECHAZA EL TEMA ENTERO: un campo inválido se descarta y el
+ * consumidor cae a su default. Perder el branding completo —o peor, no pintar el
+ * chat— porque el `accentColor` está mal cargado sería mucho peor que mostrar el
+ * acento por default.
+ */
+declare function sanitizeServerTheme(raw: unknown): ServerThemeResponse;
+/**
+ * Evento entregado por el WebSocket del widget (respuesta del asistente o del
+ * agente humano), en su forma CANÓNICA/normalizada: `ts` garantizado y
+ * `turn_ids` garantizado `string[]`. Es lo que devuelve `parseWidgetEvent` y lo
+ * que consume la UI.
+ */
+/**
+ * Botón que el agente ofrece para responder sin escribir.
+ *
+ * POR QUÉ IMPORTA: obligar a tipear es la fricción más grande de un chat de
+ * cobranzas. Un "Ver mi deuda" / "Hablar con una persona" a un toque cambia
+ * cuánta gente contesta, sobre todo en teléfono.
+ *
+ * ADITIVO Y SEGURO POR DEFECTO: un cliente que no conozca el campo lo ignora y
+ * sigue viendo el texto del mensaje, que tiene que ser autosuficiente — las
+ * quick replies son un atajo, nunca la única forma de seguir.
+ */
+interface QuickReply {
+    /** Lo que ve el usuario. Se renderiza como texto plano, NUNCA como markup. */
+    label: string;
+    /**
+     * Lo que se manda al agente si el `label` no alcanza (un id, un código).
+     * Ausente ⇒ se manda el `label`.
+     */
+    value?: string;
+}
+/** Tope de botones por mensaje. Ver `MAX_QUICK_REPLIES`. */
+declare const MAX_QUICK_REPLIES = 6;
+/** Largo máximo de un `label`. Más que esto no entra en un chip en teléfono. */
+declare const MAX_QUICK_REPLY_LABEL = 40;
+/**
+ * Quick replies USABLES de una lista cruda.
+ *
+ * El contenido lo escribe el cerebro y llega por WebSocket: se sanea acá y no en
+ * cada cliente para que el widget y el SDK no puedan divergir en qué aceptan.
+ * Descarta lo inválido en vez de rechazar el mensaje entero — perder la
+ * respuesta del agente por un botón mal formado sería mucho peor.
+ */
+declare function sanitizeQuickReplies(raw: unknown): QuickReply[];
+/**
+ * Quién escribió un mensaje del lado del asistente.
+ *
+ * `bot` (o ausente) ⇒ el agente de IA. `human` ⇒ una persona del equipo del
+ * cliente que tomó la conversación (handover). El usuario TIENE que poder
+ * distinguirlos: creer que le contesta un bot cuando es una persona —o al revés—
+ * cambia cómo escribe y qué espera.
+ */
+type MessageAuthorKind = "bot" | "human";
+/** Quién atiende del otro lado. Lo consume el header del chat. */
+interface AssistantIdentity {
+    kind: MessageAuthorKind;
+    /** Nombre a mostrar. Ausente ⇒ el cliente usa el del tema. */
+    name?: string;
+    /** URL https del avatar. Ausente ⇒ iniciales. */
+    avatar?: string;
+}
+/** Tope del nombre del agente. Más que esto no entra en el header de un teléfono. */
+declare const MAX_AGENT_NAME = 40;
+/**
+ * Identidad del agente humano, saneada.
+ *
+ * Se sanea acá y no en cada cliente por dos razones. La primera es que el widget
+ * y el SDK no puedan divergir en qué aceptan. La segunda es de SEGURIDAD: el
+ * `avatar` termina en un `<img src>` (web) y en un `<Image source>` (mobile), así
+ * que una URL `javascript:`/`data:` inyectada en el dato del agente sería un
+ * vector de XSS en el sitio del cliente. Sólo pasa `https:`.
+ *
+ * Devuelve `null` si no hay NADA usable: así el cliente cae a su propio default
+ * (iniciales, nombre genérico) en vez de mostrar un header vacío.
+ */
+declare function sanitizeAssistantIdentity(raw: unknown, kind?: MessageAuthorKind): AssistantIdentity | null;
+interface AssistantMessageEvent {
+    type: "assistant_message";
+    conversation_id: string;
+    content: string;
+    /** Ausente o "text" ⇒ texto; para media (`image`/`audio`/`video`/`document`) `content` lleva la URL. */
+    content_type?: "text" | MediaContentType;
+    /** Leyenda del media (texto plano; se renderiza como textContent, nunca como markup). */
+    caption?: string;
+    turn_ids: string[];
+    /** Epoch ms. El worker actual siempre lo manda; si faltara, `parseWidgetEvent` lo normaliza con el reloj local. */
+    ts: number;
+    /** Botones para responder sin escribir. Ver `QuickReply`. */
+    quick_replies?: QuickReply[];
+    /**
+     * Quién lo escribió. Ausente ⇒ `bot` (todo lo que existía antes de que hubiera
+     * handover es del agente de IA).
+     */
+    author?: MessageAuthorKind;
+    /** Identidad del humano que tomó la conversación. Sólo con `author: "human"`. */
+    agent?: AssistantIdentity;
+}
+/**
+ * Envelope TAL COMO PUEDE LLEGAR del wire, antes de normalizar. Difiere del
+ * canónico SOLO en lo que el guard tolerante NO garantiza, para no mentir en el
+ * tipo que se afirma:
+ *  - `ts` OPCIONAL y `| null`: el server no lo garantiza como parte del contrato
+ *    mínimo (hoy `WidgetInboundWorker` lo manda SIEMPRE, pero un productor nuevo
+ *    —o un handover humano— podría no hacerlo). `| null` porque un productor en
+ *    PYTHON (el futuro handover humano publicando al broadcaster) serializaría
+ *    `None` como `null`, NO como campo ausente. Hoy ese productor no existe: es
+ *    endurecimiento preventivo, no un bug vivo.
+ *  - `content_type` como `string | null`: el guard valida TIPOS, no el dominio
+ *    del valor (un kind nuevo del server no debe romper clientes viejos). El
+ *    narrowing al dominio canónico lo hace `normalizeAssistantMessageEvent`.
+ *  - `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`.
+ */
+type RawAssistantMessageEvent = Omit<AssistantMessageEvent, "ts" | "turn_ids" | "content_type" | "caption"> & {
+    ts?: number | null;
+    content_type?: string | null;
+    caption?: string | null;
+    turn_ids: readonly unknown[];
+};
+type WidgetEvent = AssistantMessageEvent;
+/** Union cruda del wire (hoy un solo tipo de evento; `typing`/etc. se sumarían acá). */
+type RawWidgetEvent = RawAssistantMessageEvent;
+/**
+ * ÚNICA validación de shape del envelope entrante del WS (nunca confía en la
+ * forma). Tolerante a propósito: rechaza solo lo que hace al evento INUTILIZABLE
+ * y deja pasar todo lo que la UI puede degradar sola. Antes existían dos guards
+ * distintos (SDK vs widget) sobre este MISMO envelope; ahora hay uno.
+ *
+ * Se valida (obligatorio — sin esto no hay evento que mostrar):
+ *  - `type === "assistant_message"`: discrimina la union; otro tipo no es este evento.
+ *  - `conversation_id` string: sin conversación no se puede rutear el mensaje.
+ *  - `content` string: es el cuerpo (texto o URL del media).
+ *  - `turn_ids` es Array: se usa para correlacionar/deduplicar turnos.
+ *
+ * NO se valida (tolerancia deliberada):
+ *  - `ts`: OPCIONAL. Si viene con valor debe ser numérico; si falta NO se
+ *    descarta el evento — `parseWidgetEvent` lo completa con el reloj local.
+ *    Este era el bug latente: el guard viejo del SDK exigía
+ *    `typeof ts === "number"` y tiraba a la basura, en silencio, un evento por lo
+ *    demás perfecto.
+ *  - elementos de `turn_ids`: alcanza con que sea un array. Un id basura
+ *    (número, null) NO justifica perder la respuesta del agente;
+ *    `normalizeAssistantMessageEvent` filtra los no-string.
+ *  - dominio de `content_type`: solo se valida que sea string si viene con
+ *    valor. Un kind desconocido (ej. "sticker") lo degrada el normalizador a
+ *    texto — el guard valida TIPOS, no el dominio del valor (si no, un kind
+ *    nuevo del server rompería a los clientes viejos).
+ *  - campos extra desconocidos: se ignoran (forward-compat).
+ *
+ * `null` == AUSENCIA, no valor inválido (POR QUÉ): un `{"ts": null}` o
+ * `{"caption": null}` es una forma NORMAL de decir "este campo opcional no
+ * aplica", no un envelope corrupto. Tratarlo como inválido descartaría el evento
+ * ENTERO en silencio. Por eso los tres opcionales se chequean con
+ * `!== undefined && !== null`.
+ *
+ * ALCANCE (verificado, para no sobrevender esto): hoy el ÚNICO productor es
+ * TypeScript (`WidgetInboundWorker/worker.ts`), que manda `ts` SIEMPRE y nunca
+ * emite `content_type`/`caption` ⇒ hoy no se pierde ninguna respuesta por esta
+ * vía. Es defensa a futuro: un productor en PYTHON (el handover humano
+ * publicando al broadcaster) serializaría `None` como `null`, y ahí un guard
+ * estricto sí habría descartado el evento.
+ */
+declare function isRawAssistantMessageEvent(v: unknown): v is RawAssistantMessageEvent;
+/**
+ * Type guard del evento YA CANÓNICO (`AssistantMessageEvent`): además del shape
+ * validado por `isRawAssistantMessageEvent`, exige lo que la normalización
+ * garantiza — `ts` numérico y `turn_ids` todos string.
+ *
+ * POR QUÉ existen los dos: son preguntas distintas, no criterios divergentes.
+ * `isRawAssistantMessageEvent` = "¿esto es un envelope del wire que puedo
+ * aprovechar?" (tolerante, es el que usa el transporte). Este = "¿esto YA
+ * cumple el tipo canónico?" (para no mentir en el tipo que se afirma). Ambos
+ * comparten la MISMA validación de campos; la única diferencia es la frontera
+ * de normalización. Para consumir el WS usá `parseWidgetEvent`.
+ *
+ * Sobre los opcionales: el crudo tolera `null` y un `content_type` fuera del
+ * dominio, pero el tipo canónico promete `caption?: string` y
+ * `content_type?: "text" | MediaContentType`. Si acá no se chequeara eso, este
+ * guard afirmaría un tipo que el valor NO cumple.
+ */
+declare function isAssistantMessageEvent(v: unknown): v is AssistantMessageEvent;
+/**
+ * Normaliza un envelope crudo al evento canónico:
+ *  - completa `ts` con el reloj local si el server no lo mandó (o mandó basura);
+ *  - descarta los `turn_ids` que no sean string (en vez de perder el evento);
+ *  - narrowea `content_type` al dominio conocido (kind raro ⇒ `"text"`).
+ * `now` es inyectable para tests.
+ *
+ * `ts` con sanity-check (`Number.isFinite` && `> 0`), no solo `typeof number`:
+ * un `0`, un negativo, un `NaN` o un `Infinity` pasarían el typeof y la UI
+ * renderizaría "1 ene 1970" (o una fecha inválida) como si fuera el dato real
+ * del server. Un timestamp imposible es lo mismo que un timestamp ausente: se
+ * completa con el reloj local, que al menos es plausible.
+ *
+ * Los spreads usan `!= null` (no `!== undefined`) A PROPÓSITO: cubre `undefined`
+ * Y `null` con una sola comparación, así un `caption: null` (que emitiría un
+ * productor Python futuro) NO se copia al evento canónico (tipo `caption?: string`).
+ * `exactOptionalPropertyTypes` obliga a copiarlos solo si están presentes (no se
+ * puede asignar `undefined` explícito).
+ */
+declare function normalizeAssistantMessageEvent(raw: RawAssistantMessageEvent, now?: () => number): AssistantMessageEvent;
+/**
+ * Parseo seguro de un mensaje crudo del WS (nunca lanza; devuelve `null` si no
+ * es un evento válido). Valida con el guard tolerante y devuelve el evento YA
+ * normalizado, así el consumidor siempre ve `ts: number` y `turn_ids: string[]`.
+ */
+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 };