@adatechnology/conversations-ui 0.1.0-rc.3 → 0.1.0-rc.30

package/src/preview/ConversationPreview.tsx

@@ -13,13 +13,14 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { MessagePayload } from '../types'
+import type { InteractiveSelection, MessagePayload } from '../types'
 import type { SSEProvider } from '../providers/types'
 import { MessageBubble } from '../MessageBubble'
 import { MessageComposer } from '../MessageComposer'
 import { DateDivider } from '../DateDivider'
 import { ConversationWallpaper } from '../Wallpaper'
-import type { PreviewWebhookClient } from './createPreviewWebhookClient'
+import type { PreviewWebhookClient, SendPreviewMediaParams } from './createPreviewWebhookClient'
+import { AudioRecorderButton } from '../AudioRecorderButton'
 
 export type ConversationPreviewProps = {
   client: PreviewWebhookClient
@@ -27,12 +28,44 @@ export type ConversationPreviewProps = {
   conversationId: string
   loadMessages: (conversationId: string) => Promise<MessagePayload[]>
   placeholder?: string
+  /**
+   * Recarrega o transcript a cada N ms. Serve a host SEM stream: a resposta do bot é assíncrona, e
+   * sem SSE nem polling ela só apareceria no próximo envio — o sintoma é "às vezes ele não
+   * responde". Ausente, não faz polling (host com SSE não precisa).
+   */
+  pollIntervalMs?: number
+  /**
+   * Como transformar um arquivo do disco (ou o áudio gravado) na referência que o webhook carrega.
+   * O caminho da Meta entrega mídia por `id`, e quem sabe hospedar o arquivo é o host — a SDK não
+   * inventa um endpoint de upload. Ausente, o compositor não oferece anexo nem gravação: melhor um
+   * botão que não existe do que um que falha ao ser tocado.
+   */
+  /** Destino alternativo do áudio gravado. Sem isto, usa o do próprio `client`. */
+  uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
+}
+
+export type PreviewUploadedMedia = {
+  readonly mediaId: string
+  readonly mimeType?: string
+  readonly filename?: string
+}
+
+/** Deriva o tipo de mídia do WhatsApp a partir do MIME do arquivo escolhido. */
+export function mediaTypeOf(mimeType: string): SendPreviewMediaParams['mediaType'] {
+  if (mimeType.startsWith('image/')) return 'image'
+  if (mimeType.startsWith('video/')) return 'video'
+  if (mimeType.startsWith('audio/')) return 'audio'
+  return 'document'
 }
 
 // Mesma janela usada pelo WhatsApp para colar bolhas do mesmo autor: acima disso, a mensagem
 // recomeça um grupo (com rabicho e espaçamento maior).
 const GROUPING_WINDOW_MS = 5 * 60 * 1000
 
+// Escalonado, não um atraso fixo: a maioria das respostas chega em ~300ms, mas fluxo que consulta
+// catálogo ou IA demora mais — e recarregar três vezes é mais barato que a conversa parecer morta.
+const FOLLOW_UP_REFRESH_MS = [400, 1200, 3000]
+
 type RenderedMessage = {
   readonly message: MessagePayload
   readonly isFirstInGroup: boolean
@@ -55,26 +88,80 @@ function decorate(messages: readonly MessagePayload[]): RenderedMessage[] {
   })
 }
 
+/**
+ * Status HTTP do erro, quando o host o preserva.
+ *
+ * O contrato não exige um tipo de erro — cada host tem o seu —, então a leitura é estrutural: basta
+ * carregar `status` (ou `statusCode`) para ser classificável. Host que joga `new Error(texto)` cai no
+ * caminho genérico, que ainda é melhor que silêncio.
+ */
+function statusOf(error: unknown): number | undefined {
+  if (typeof error !== 'object' || error === null) return undefined
+  const candidate = error as { status?: unknown; statusCode?: unknown }
+  const value = candidate.status ?? candidate.statusCode
+  return typeof value === 'number' ? value : undefined
+}
+
+export function isNotFound(error: unknown): boolean {
+  return statusOf(error) === 404
+}
+
+export function describeLoadFailure(error: unknown): string {
+  const status = statusOf(error)
+  // 401/403 no simulador quase sempre é a aba sem sessão: `sessionStorage` é por aba, e link com
+  // `rel="noreferrer"` abre contexto novo que não herda o token do painel.
+  if (status === 401 || status === 403) {
+    return 'Sem sessão de administrador nesta aba: a mensagem é entregue no webhook, mas o transcript não pode ser lido. Entre no painel nesta mesma aba e reabra o simulador.'
+  }
+  if (error instanceof Error && error.message) return `Não foi possível ler o transcript: ${error.message}`
+  return 'Não foi possível ler o transcript da conversa.'
+}
+
 export function ConversationPreview({
   client,
   sse,
   conversationId,
   loadMessages,
   placeholder,
+  pollIntervalMs,
+  uploadMedia,
 }: ConversationPreviewProps) {
   const [messages, setMessages] = useState<MessagePayload[]>([])
   const [failure, setFailure] = useState<string | undefined>(undefined)
+  const [loadFailure, setLoadFailure] = useState<string | undefined>(undefined)
+  const [isRecording, setIsRecording] = useState(false)
+  // Mensagens que o servidor ainda não devolveu. Sem isto, quem não consegue LER a conversa (sessão
+  // ausente, API fora) digita, envia com sucesso e não vê absolutamente nada mudar — o preview fica
+  // indistinguível de quebrado. São descartadas assim que uma leitura dá certo: aí quem manda na
+  // tela é o servidor, que já tem a mensagem gravada.
+  const [pendingLocal, setPendingLocal] = useState<MessagePayload[]>([])
   const loadMessagesRef = useRef(loadMessages)
   const bottomRef = useRef<HTMLDivElement>(null)
   loadMessagesRef.current = loadMessages
 
   const refresh = useCallback(async (): Promise<void> => {
     try {
-      setMessages(await loadMessagesRef.current(conversationId))
-    } catch {
-      // Conversa que ainda não existe é o estado normal do primeiro contato — a API responde erro
-      // e a tela deve mostrar o transcript vazio, não uma falha.
-      setMessages([])
+      const loaded = await loadMessagesRef.current(conversationId)
+      setMessages(loaded)
+      setLoadFailure(undefined)
+      // Só descarta o eco quando o servidor de fato devolveu conversa: lista vazia é "não consegui
+      // ver nada" (sessão ausente, primeiro contato), e limpar aí apagava da tela a mensagem que o
+      // usuário acabou de mandar — o sintoma que este eco existe para evitar.
+      if (loaded.length > 0) setPendingLocal([])
+    } catch (error) {
+      // Conversa que ainda não existe é o estado normal do primeiro contato — transcript vazio, sem
+      // alarme. QUALQUER outra falha precisa aparecer: engolir todas era o que transformava sessão
+      // expirada (401) em silêncio absoluto, com a thread limpa e o operador concluindo que o envio
+      // não funcionou — quando a mensagem tinha sido entregue no webhook.
+      if (isNotFound(error)) {
+        setMessages([])
+        setLoadFailure(undefined)
+        return
+      }
+
+      // Não limpa o que já está na tela: perder o histórico por causa de um refresh que falhou é
+      // dano maior que o próprio erro.
+      setLoadFailure(describeLoadFailure(error))
     }
   }, [conversationId])
 
@@ -96,18 +183,49 @@ export function ConversationPreview({
   }, [sse, conversationId, refresh])
 
   useEffect(() => {
-    bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
+    if (!pollIntervalMs) return
+    const timer = setInterval(() => void refresh(), pollIntervalMs)
+    return () => clearInterval(timer)
+  }, [pollIntervalMs, refresh])
+
+  useEffect(() => {
+    // `block: 'nearest'` e não o padrão ('start'): o padrão alinha o elemento ao topo da área
+    // visível MAIS PRÓXIMA que role — e quando o container do preview não tem altura limitada, essa
+    // área é a PÁGINA. O efeito era a tela inteira saltar para baixo ao abrir/usar o simulador.
+    bottomRef.current?.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
   }, [messages])
 
-  const rendered = useMemo(() => decorate(messages), [messages])
+  const rendered = useMemo(() => decorate([...messages, ...pendingLocal]), [messages, pendingLocal])
+
+  async function refreshWithFollowUps(): Promise<void> {
+    await refresh()
+    for (const atraso of FOLLOW_UP_REFRESH_MS) {
+      setTimeout(() => void refresh(), atraso)
+    }
+  }
 
   async function handleSend(text: string): Promise<void> {
     setFailure(undefined)
     try {
       await client.sendText(text)
-      // O bot responde de forma assíncrona e o ping do SSE cobre isso; este refresh é para a
-      // própria mensagem enviada aparecer na hora, sem esperar o ciclo de evento.
-      await refresh()
+      setPendingLocal((current) => [
+        ...current,
+        {
+          id: `local-${current.length}-${text.length}`,
+          type: 'text',
+          content: text,
+          // Do ponto de vista do servidor, mensagem do cliente é inbound — é assim que ela aparece
+          // como "minha" nesta visão.
+          direction: 'inbound',
+          sender: 'customer',
+          timestamp: new Date().toISOString(),
+          status: 'sent',
+        },
+      ])
+      // O bot responde de forma assíncrona: gravar a resposta leva algumas centenas de ms depois do
+      // 200 do webhook. Um refresh único aqui frequentemente chegava ANTES dela, e a conversa ficava
+      // com a pergunta sem resposta até o envio seguinte.
+      await refreshWithFollowUps()
     } catch (error) {
       // A recusa mais provável é assinatura inválida (segredo divergente do que a API valida), e
       // ela precisa aparecer na tela: silenciada, o sintoma vira "mandei e não aconteceu nada".
@@ -115,6 +233,45 @@ export function ConversationPreview({
     }
   }
 
+  async function handleInteractiveSelect(selection: InteractiveSelection): Promise<void> {
+    setFailure(undefined)
+    const reply = { id: selection.option.id, title: selection.option.title }
+    try {
+      // Botão e lista são payloads diferentes para a Meta (`button_reply` × `list_reply`), e o
+      // roteador do fluxo lê campos distintos: tratar os dois como um só faria o menu responder no
+      // simulador e falhar no aparelho do cliente.
+      await (selection.kind === 'button' ? client.sendButtonReply(reply) : client.sendListReply(reply))
+      await refreshWithFollowUps()
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : 'Falha ao entregar a resposta no webhook.')
+    }
+  }
+
+  /**
+   * O cliente do preview sabe subir mídia sozinho; a prop é só para quem quer outro destino.
+   *
+   * Antes isto era `uploadMedia` puro, e o microfone só aparecia no produto que lembrasse de montar
+   * o upload — de onde veio a divergência entre dois simuladores da mesma casa.
+   */
+  const uploadFile = uploadMedia ?? client.uploadMedia
+
+  async function handleAttach(file: File): Promise<void> {
+    if (!uploadFile) return
+    setFailure(undefined)
+    try {
+      const uploaded = await uploadFile(file)
+      await client.sendMedia({
+        mediaType: mediaTypeOf(uploaded.mimeType ?? file.type),
+        mediaId: uploaded.mediaId,
+        mimeType: uploaded.mimeType ?? file.type,
+        filename: uploaded.filename ?? file.name,
+      })
+      await refreshWithFollowUps()
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : 'Falha ao enviar o arquivo.')
+    }
+  }
+
   return (
     <div className="flex h-full min-h-0 flex-col">
       <ConversationWallpaper className="flex-1 min-h-0 overflow-y-auto px-4 py-3">
@@ -127,6 +284,11 @@ export function ConversationPreview({
               // vista do servidor.
               isMine={message.direction === 'inbound'}
               isFirstInGroup={isFirstInGroup}
+              // Só o que o bot ofereceu é tocável: reoferecer as opções da própria mensagem do
+              // cliente deixaria o menu clicável para sempre, o que o WhatsApp não faz.
+              onInteractiveSelect={
+                message.direction === 'outbound' ? (selection) => void handleInteractiveSelect(selection) : undefined
+              }
             />
           </div>
         ))}
@@ -139,9 +301,33 @@ export function ConversationPreview({
         </p>
       ) : null}
 
+      {/* Separado da falha de ENVIO: são causas diferentes e confundi-las manda o operador
+          investigar assinatura de webhook quando o problema é sessão. Amarelo, não vermelho — a
+          mensagem foi entregue; o que faltou foi poder ler a conversa de volta. */}
+      {loadFailure ? (
+        <p role="status" className="px-4 py-2 text-sm text-amber-700 dark:text-amber-400">
+          {loadFailure}
+        </p>
+      ) : null}
+
       <MessageComposer
         onSend={(text) => void handleSend(text)}
-        placeholder={placeholder ?? 'Escreva como o cliente…'}
+        onAttach={uploadFile ? (file) => void handleAttach(file) : undefined}
+        /* Gravando, o campo diz o que falta fazer: o botão é um interruptor e o segundo toque é
+           que envia — sem esse aviso o operador grava, não vê nada acontecer e conclui que o
+           microfone está quebrado. */
+        placeholder={
+          isRecording ? 'Gravando… toque no quadrado para ouvir' : (placeholder ?? 'Escreva como o cliente…')
+        }
+        idleAction={
+          uploadFile ? (
+            <AudioRecorderButton
+              onRecorded={(file) => void handleAttach(file)}
+              onFailure={(message) => setFailure(message)}
+              onRecordingChange={setIsRecording}
+            />
+          ) : undefined
+        }
       />
     </div>
   )

package/src/preview/ConversationSimulatorPanel.test.tsx

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ConversationSimulatorPanel, type ConversationSimulatorPanelProps } from './ConversationSimulatorPanel'
+import { createMockSSEProvider } from './createMockSSEProvider'
+import { createPreviewStore } from './previewStore'
+
+function markupOf(overrides: Partial<ConversationSimulatorPanelProps> = {}): string {
+  const store = createPreviewStore({ conversations: [], messages: {} })
+
+  return renderToStaticMarkup(
+    <ConversationSimulatorPanel
+      conversationId="5511900000042"
+      onClose={() => {}}
+      client={{ sendText: async () => {}, sendInteractiveReply: async () => {} } as never}
+      sse={createMockSSEProvider({ store })}
+      loadMessages={async () => []}
+      {...overrides}
+    />,
+  )
+}
+
+describe('ConversationSimulatorPanel', () => {
+  it('mostra o telefone formatado pelo host, e não o id cru', () => {
+    expect(markupOf({ displayNumber: '+55 (11) 90000-0042' })).toContain('+55 (11) 90000-0042')
+  })
+
+  it('cai no id da conversa quando o host não formata', () => {
+    expect(markupOf()).toContain('5511900000042')
+  })
+
+  it('avisa para onde a mensagem vai, para ninguém achar que é conversa de mentira', () => {
+    expect(markupOf()).toContain('entrega no webhook real')
+  })
+
+  it('dá nome acessível ao botão de fechar, que só tem ícone', () => {
+    expect(markupOf()).toContain('aria-label="Fechar simulador"')
+  })
+
+  it('aceita rótulos parciais do host sem exigir o conjunto inteiro', () => {
+    const markup = markupOf({ labels: { title: 'Testar fluxo' } })
+
+    expect(markup).toContain('Testar fluxo')
+    // O que não foi sobrescrito continua no default.
+    expect(markup).toContain('aria-label="Fechar simulador"')
+  })
+
+  it('renderiza ação extra do host no cabeçalho', () => {
+    expect(markupOf({ headerActions: <button type="button">Rodar roteiro</button> })).toContain('Rodar roteiro')
+  })
+
+  it('nomeia o próprio aside, para o leitor de tela distinguir do transcript ao lado', () => {
+    expect(markupOf()).toContain('aria-label="Simulador do cliente"')
+  })
+})

package/src/preview/ConversationSimulatorPanel.tsx

@@ -0,0 +1,89 @@
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ *
+ * Author: Anderson Filho <andersonfrfilho@gmail.com>
+ *
+ * Painel lateral do simulador de cliente: a moldura em volta do `ConversationPreview`.
+ *
+ * Existe como componente do pacote porque cada produto tinha reescrito a mesma moldura —
+ * `<aside>`, cabeçalho com título e telefone, botão de fechar — e as cópias divergiram. Uma delas
+ * migrou para o cliente-ponte (assinatura no servidor) e a outra ficou assinando no navegador, com
+ * o app secret publicado no bundle. É o tipo de correção que precisa chegar a todo mundo de uma vez.
+ *
+ * Mora DENTRO da tela de conversas, e não numa aba própria, por um motivo prático: o token do
+ * atendente costuma viver em `sessionStorage`, que é por aba. Numa aba separada o simulador nascia
+ * sem sessão, o transcript nunca carregava, e o sintoma era "mandei e não aconteceu nada".
+ *
+ * O efeito de cada envio aparece na thread ao lado pelo mesmo stream que a inbox já assina — este
+ * painel não abre conexão própria.
+ */
+
+import type { ReactNode } from 'react'
+
+import { ConversationPreview, type ConversationPreviewProps } from './ConversationPreview'
+
+export type ConversationSimulatorPanelLabels = {
+  readonly title: string
+  /** Complementa o telefone no subtítulo, explicando para onde a mensagem realmente vai. */
+  readonly destinationHint: string
+  readonly close: string
+  readonly placeholder: string
+}
+
+export const DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS: ConversationSimulatorPanelLabels = {
+  title: 'Simulador do cliente',
+  destinationHint: 'entrega no webhook real',
+  close: 'Fechar simulador',
+  placeholder: 'Escreva como o cliente…',
+}
+
+export type ConversationSimulatorPanelProps = Omit<ConversationPreviewProps, 'placeholder'> & {
+  readonly onClose: () => void
+  /**
+   * Telefone já formatado para leitura. É o host que formata: máscara de telefone é convenção
+   * regional, e o pacote não tem como saber a do produto.
+   */
+  readonly displayNumber?: string
+  readonly labels?: Partial<ConversationSimulatorPanelLabels>
+  /** Ações extras no cabeçalho — roteiro automático, limpar conversa, trocar de contato. */
+  readonly headerActions?: ReactNode
+}
+
+export function ConversationSimulatorPanel({
+  onClose,
+  displayNumber,
+  labels,
+  headerActions,
+  ...previewProps
+}: ConversationSimulatorPanelProps) {
+  const text = { ...DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS, ...labels }
+  const subtitle = [displayNumber ?? previewProps.conversationId, text.destinationHint].join(' · ')
+
+  return (
+    <aside className="cv-simulator-panel" aria-label={text.title}>
+      <header className="cv-simulator-panel__header">
+        <div className="cv-simulator-panel__heading">
+          <h2 className="cv-simulator-panel__title">{text.title}</h2>
+          <p className="cv-simulator-panel__subtitle">{subtitle}</p>
+        </div>
+        <div className="cv-simulator-panel__actions">
+          {headerActions}
+          <button type="button" onClick={onClose} data-cv-tooltip={text.close} aria-label={text.close} className="cv-simulator-panel__close">
+            {/* SVG inline em vez de lucide-react: o pacote não impõe biblioteca de ícone ao host. */}
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
+              <path d="M18 6 6 18M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+      </header>
+
+      <div className="cv-simulator-panel__body">
+        <ConversationPreview {...previewProps} placeholder={text.placeholder} />
+      </div>
+    </aside>
+  )
+}

package/src/preview/MediaTypesPreview.tsx

@@ -0,0 +1,87 @@
+/**
+ * Bancada de teste manual de mídia — montável em uma linha por qualquer projeto que adote o SDK.
+ *
+ * Existe porque o defeito que ela pega não é pegável por teste automatizado: "o PDF abre?" depende
+ * do leitor do navegador, "o vídeo toca?" do decodificador, e "a aba abre?" da política do Chrome
+ * sobre `data:` URL. Teste unitário confere bytes; só o olho confere que o arquivo abre. Sem uma
+ * superfície pronta no pacote, cada projeto teria de montar a sua — e, na prática, nenhum montava.
+ *
+ * Traz o próprio store, o próprio mock e o próprio provider: o host não injeta nada. E não passa
+ * `onResolveMediaUrl` em lugar nenhum de propósito — é o `MessageBubble` resolvendo mídia pelo
+ * `ConversationsApi` do contexto, então se essa resolução automática quebrar, esta tela mostra.
+ */
+
+import { useMemo } from 'react'
+import { ConversationsProvider } from '../providers/ConversationsProvider'
+import { DocumentsLibrary } from '../DocumentsLibrary'
+import { ConversationDocumentsPanel } from '../ConversationDocumentsPanel'
+import { MessageBubble } from '../MessageBubble'
+import { ConversationWallpaper } from '../Wallpaper'
+import { createMockConversationsApi } from './createMockConversationsApi'
+import { createMockSSEProvider } from './createMockSSEProvider'
+import { createPreviewStore } from './previewStore'
+import { PREVIEW_CONVERSATIONS, PREVIEW_DOCUMENTS, PREVIEW_MESSAGES } from './previewFixtures'
+
+/** A conversa do fixture que carrega uma mensagem de cada tipo aceito. */
+export const MEDIA_TYPES_CONVERSATION_ID = '5511944443333'
+
+export type MediaTypesPreviewProps = {
+  /** Outra conversa do fixture, se o projeto tiver acrescentado a sua. */
+  conversationId?: string
+  className?: string
+}
+
+export function MediaTypesPreview({
+  conversationId = MEDIA_TYPES_CONVERSATION_ID,
+  className,
+}: MediaTypesPreviewProps) {
+  const store = useMemo(
+    () => createPreviewStore({ conversations: PREVIEW_CONVERSATIONS, messages: PREVIEW_MESSAGES }),
+    [],
+  )
+  const api = useMemo(() => createMockConversationsApi({ store }), [store])
+  const sse = useMemo(() => createMockSSEProvider({ store }), [store])
+
+  const messages = PREVIEW_MESSAGES[conversationId] ?? []
+  const documents = PREVIEW_DOCUMENTS[conversationId] ?? []
+  const mimeTypes = [...new Set(documents.map((document) => document.mimeType))]
+
+  return (
+    <ConversationsProvider api={api} sse={sse}>
+      <div className={className}>
+        <header className="border-b px-4 py-3 dark:border-gray-700">
+          <h1 className="text-lg font-semibold">Teste manual de mídia</h1>
+          <p className="text-sm text-gray-500">
+            {documents.length} arquivos, {mimeTypes.length} tipos. Clique no olho para abrir em aba nova e no
+            botão da bolha para carregar a mídia na thread — é o que teste automatizado não vê.
+          </p>
+        </header>
+
+        <div className="grid gap-4 p-4 lg:grid-cols-2">
+          <section className="space-y-3">
+            <h2 className="text-sm font-semibold uppercase tracking-wide text-gray-500">Biblioteca da empresa</h2>
+            {/* Sem paginar: a bancada serve para ver TODOS os tipos de uma vez. */}
+            <DocumentsLibrary perPage={documents.length || 20} />
+          </section>
+
+          <section className="space-y-3">
+            <h2 className="text-sm font-semibold uppercase tracking-wide text-gray-500">Painel da conversa</h2>
+            <ConversationDocumentsPanel conversationId={conversationId} open perPage={documents.length || 20} />
+
+            <h2 className="text-sm font-semibold uppercase tracking-wide text-gray-500">Bolhas na thread</h2>
+            <ConversationWallpaper className="max-h-[70vh] overflow-y-auto rounded-lg px-3 py-2">
+              {messages.map((message, index) => (
+                <MessageBubble
+                  key={message.id}
+                  message={message}
+                  isMine={message.direction === 'outbound'}
+                  isFirstInGroup={index === 0 || messages[index - 1]?.sender !== message.sender}
+                />
+              ))}
+            </ConversationWallpaper>
+          </section>
+        </div>
+      </div>
+    </ConversationsProvider>
+  )
+}

package/src/preview/conversationPreviewFailures.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Guarda a classificação de falha do simulador do cliente.
+ *
+ * O defeito que motivou o arquivo: o `refresh` tratava QUALQUER erro ao ler o transcript como
+ * "conversa ainda não existe", mostrava thread vazia e não dizia nada. Com sessão ausente (401) o
+ * sintoma era o pior possível — a mensagem ia para o webhook, era aceita, e a tela ficava igual.
+ * Quem olhava concluía que o envio estava quebrado.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { describeLoadFailure, isNotFound } from './ConversationPreview'
+
+class HttpError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message)
+  }
+}
+
+describe('isNotFound', () => {
+  // Primeiro contato: a conversa não existe e transcript vazio é o estado correto, sem alarme.
+  it('reconhece 404 como conversa inexistente', () => {
+    expect(isNotFound(new HttpError('Conversa não encontrada', 404))).toBe(true)
+  })
+
+  it('não confunde 401 com conversa inexistente', () => {
+    expect(isNotFound(new HttpError('Unauthorized', 401))).toBe(false)
+  })
+
+  it('erro sem status não é tratado como inexistente', () => {
+    expect(isNotFound(new Error('Failed to fetch'))).toBe(false)
+    expect(isNotFound(undefined)).toBe(false)
+  })
+
+  // Aceita `statusCode` também: nem todo host nomeia o campo igual.
+  it('lê statusCode quando é esse o nome do campo', () => {
+    expect(isNotFound({ statusCode: 404 })).toBe(true)
+  })
+})
+
+describe('describeLoadFailure', () => {
+  it('explica que falta sessão e que a mensagem FOI entregue', () => {
+    const mensagem = describeLoadFailure(new HttpError('Unauthorized', 401))
+
+    expect(mensagem).toContain('Sem sessão')
+    // O ponto central: não deixar o operador achar que o envio falhou.
+    expect(mensagem).toContain('entregue no webhook')
+  })
+
+  it('trata 403 igual a 401', () => {
+    expect(describeLoadFailure(new HttpError('Forbidden', 403))).toContain('Sem sessão')
+  })
+
+  it('preserva a mensagem do host em falha genérica', () => {
+    expect(describeLoadFailure(new HttpError('API fora do ar', 500))).toContain('API fora do ar')
+  })
+
+  it('tem texto para erro sem mensagem', () => {
+    expect(describeLoadFailure({}).length).toBeGreaterThan(0)
+  })
+})