@adatechnology/conversations-ui 0.1.0-rc.5 → 0.1.0-rc.7

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,43 @@ 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.
+   */
+  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 +87,79 @@ 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)
+  // 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])
 
@@ -95,19 +180,47 @@ export function ConversationPreview({
     }
   }, [sse, conversationId, refresh])
 
+  useEffect(() => {
+    if (!pollIntervalMs) return
+    const timer = setInterval(() => void refresh(), pollIntervalMs)
+    return () => clearInterval(timer)
+  }, [pollIntervalMs, refresh])
+
   useEffect(() => {
     bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
   }, [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 +228,37 @@ 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.')
+    }
+  }
+
+  async function handleAttach(file: File): Promise<void> {
+    if (!uploadMedia) return
+    setFailure(undefined)
+    try {
+      const uploaded = await uploadMedia(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 +271,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,10 +288,30 @@ export function ConversationPreview({
         </p>
       ) : null}
 
-      <MessageComposer
-        onSend={(text) => void handleSend(text)}
-        placeholder={placeholder ?? 'Escreva como o cliente…'}
-      />
+      {/* 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}
+
+      <div className="flex items-end gap-1">
+        <div className="min-w-0 flex-1">
+          <MessageComposer
+            onSend={(text) => void handleSend(text)}
+            onAttach={uploadMedia ? (file) => void handleAttach(file) : undefined}
+            placeholder={placeholder ?? 'Escreva como o cliente…'}
+          />
+        </div>
+        {uploadMedia ? (
+          <AudioRecorderButton
+            onRecorded={(file) => void handleAttach(file)}
+            onFailure={(message) => setFailure(message)}
+          />
+        ) : null}
+      </div>
     </div>
   )
 }

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/audioRecorderFormat.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+
+import { resolveRecordingFormat } from './AudioRecorderButton'
+import { DEFAULT_ACCEPTED_FILE_TYPES } from '../MessageComposer'
+
+const originalMediaRecorder = (globalThis as Record<string, unknown>).MediaRecorder
+
+function stubMediaRecorder(supported: readonly string[] | undefined): void {
+  const stub = supported ? { isTypeSupported: (mimeType: string) => supported.includes(mimeType) } : {}
+  ;(globalThis as Record<string, unknown>).MediaRecorder = stub
+}
+
+afterEach(() => {
+  ;(globalThis as Record<string, unknown>).MediaRecorder = originalMediaRecorder
+})
+
+describe('resolveRecordingFormat', () => {
+  it('prefere ogg/opus, que o WhatsApp aceita, sobre webm', () => {
+    stubMediaRecorder(['audio/ogg;codecs=opus', 'audio/webm'])
+
+    expect(resolveRecordingFormat()?.uploadMimeType).toBe('audio/ogg')
+  })
+
+  it('cai para mp4 no navegador que não grava ogg', () => {
+    stubMediaRecorder(['audio/mp4', 'audio/webm'])
+
+    const format = resolveRecordingFormat()
+    expect(format?.uploadMimeType).toBe('audio/mp4')
+    expect(format?.extension).toBe('m4a')
+  })
+
+  it('devolve indefinido quando o navegador não grava nenhum formato', () => {
+    stubMediaRecorder([])
+
+    expect(resolveRecordingFormat()).toBeUndefined()
+  })
+
+  it('devolve indefinido sem MediaRecorder no ambiente', () => {
+    ;(globalThis as Record<string, unknown>).MediaRecorder = undefined
+
+    expect(resolveRecordingFormat()).toBeUndefined()
+  })
+})
+
+describe('DEFAULT_ACCEPTED_FILE_TYPES', () => {
+  it('cobre Word, Excel e PowerPoint nos dois formatos, legado e OpenXML', () => {
+    const accepted = DEFAULT_ACCEPTED_FILE_TYPES.split(',')
+
+    expect(accepted).toContain('application/msword')
+    expect(accepted).toContain('application/vnd.openxmlformats-officedocument.wordprocessingml.document')
+    expect(accepted).toContain('application/vnd.ms-excel')
+    expect(accepted).toContain('application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')
+    expect(accepted).toContain('application/vnd.ms-powerpoint')
+    expect(accepted).toContain('application/vnd.openxmlformats-officedocument.presentationml.presentation')
+  })
+
+  it('cobre texto, PDF, áudio e vídeo, e não oferece formato que o WhatsApp recusa', () => {
+    const accepted = DEFAULT_ACCEPTED_FILE_TYPES.split(',')
+
+    expect(accepted).toContain('application/pdf')
+    expect(accepted).toContain('text/plain')
+    expect(accepted).toContain('audio/ogg')
+    expect(accepted).toContain('video/mp4')
+    expect(DEFAULT_ACCEPTED_FILE_TYPES).not.toContain('.zip')
+    expect(DEFAULT_ACCEPTED_FILE_TYPES).not.toContain('.rtf')
+  })
+})

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)
+  })
+})

package/src/preview/createMockConversationsApi.ts

@@ -9,6 +9,7 @@
 
 import type { MessagePayload } from '../types'
 import type {
+  CompanyDocumentPage,
   ConversationDocumentPage,
   ConversationPage,
   ConversationTemplate,
@@ -16,12 +17,9 @@ import type {
   ListConversationsParams,
 } from '../providers/types'
 import { PREVIEW_DOCUMENTS } from './previewFixtures'
+import { previewFileBase64, previewFileUrl } from './previewMediaSource'
 import type { PreviewStore } from './previewStore'
 
-// PNG 1x1 transparente: o suficiente para o MediaRenderer ter algo válido para desenhar.
-const PREVIEW_IMAGE_BASE64 =
-  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYGD4DwABBAEAX+XyEgAAAABJRU5ErkJggg=='
-
 export type CreateMockConversationsApiParams = {
   readonly store: PreviewStore
   readonly latencyMs?: number
@@ -178,12 +176,68 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
       })
     },
 
-    getDocumentUrl(): Promise<string> {
-      return withLatency(() => `data:image/png;base64,${PREVIEW_IMAGE_BASE64}`)
+    /** Junta as bibliotecas de todas as conversas do fixture, com a origem de cada arquivo. */
+    getAllDocuments(documentParams): Promise<CompanyDocumentPage> {
+      return withLatency(() => {
+        let all = Object.entries(PREVIEW_DOCUMENTS).flatMap(([conversationId, docs]) =>
+          docs.map((document) => ({ ...document, conversationId })),
+        )
+
+        // Mesma regra do backend (`companyDocumentSearch`): o termo casa nome do arquivo OU
+        // telefone da conversa, e o telefone só pelos dígitos — o preview mostra o número
+        // formatado, então é assim que o atendente vai colá-lo na busca.
+        const search = documentParams?.search?.trim().toLowerCase()
+        if (search) {
+          const digits = search.replace(/\D/g, '')
+          all = all.filter(
+            (document) =>
+              document.filename.toLowerCase().includes(search) ||
+              (digits !== '' && document.conversationId.includes(digits)),
+          )
+        }
+
+        const source = documentParams?.source
+        if (source === 'team') {
+          all = all.filter((document) => document.source === 'agent' || document.source === 'bot')
+        } else if (source) {
+          all = all.filter((document) => document.source === source)
+        }
+
+        all.sort((left, right) =>
+          documentParams?.sortDirection === 'asc'
+            ? left.linkedAt.localeCompare(right.linkedAt)
+            : right.linkedAt.localeCompare(left.linkedAt),
+        )
+
+        const total = all.length
+        const limit = documentParams?.limit ?? total
+        const page = documentParams?.page ?? 1
+        return { documents: all.slice((page - 1) * limit, page * limit), total }
+      })
     },
 
-    getMediaProxyUrl(): Promise<{ mimeType: string; data: string }> {
-      return withLatency(() => ({ mimeType: 'image/png', data: PREVIEW_IMAGE_BASE64 }))
+    // Devolve os bytes DO TIPO do documento, não uma imagem para tudo: antes, abrir um PDF entregava
+    // um PNG rotulado `application/pdf` e o leitor recusava o arquivo. O `uploadId` é a única pista
+    // que o contrato dá, então o tipo vem da própria biblioteca.
+    getDocumentUrl(uploadId): Promise<string> {
+      return withLatency(() => {
+        const found = Object.values(PREVIEW_DOCUMENTS)
+          .flat()
+          .find((document) => document.id === uploadId)
+        return previewFileUrl(found?.mimeType, found?.filename)
+      })
+    },
+
+    // Caminho da mídia ainda não ingerida: o backend busca na Meta e devolve base64. Resolve pelo
+    // id para a bolha receber os bytes DO TIPO dela — devolvendo um PNG para todo id, vídeo e áudio
+    // apareciam quebrados na thread mesmo havendo amostra válida do formato.
+    getMediaProxyUrl(mediaId): Promise<{ mimeType: string; data: string }> {
+      return withLatency(() => {
+        const found = Object.values(PREVIEW_DOCUMENTS)
+          .flat()
+          .find((document) => document.id === `preview/inbound/${mediaId}`)
+        return previewFileBase64(found?.mimeType, found?.filename)
+      })
     },
 
     takeover(conversationId): Promise<void> {

package/src/preview/createPreviewWebhookClient.ts

@@ -14,8 +14,10 @@
 import {
   buildInboundAudioPayload,
   buildInboundInteractivePayload,
+  buildInboundMediaPayload,
   buildInboundTextPayload,
   serializeWebhookPayload,
+  type InboundMediaType,
   type InteractiveReplyOption,
 } from '@adatechnology/meta-whatsapp-contracts/testing'
 
@@ -24,6 +26,20 @@ export type PreviewWebhookClient = {
   sendButtonReply(reply: InteractiveReplyOption): Promise<void>
   sendListReply(reply: InteractiveReplyOption): Promise<void>
   sendAudio(mediaId: string): Promise<void>
+  sendMedia(params: SendPreviewMediaParams): Promise<void>
+}
+
+export type SendPreviewMediaParams = {
+  readonly mediaType: InboundMediaType
+  /**
+   * Id que o host já usa para buscar o arquivo. Não é bytes: o webhook da Meta entrega mídia por
+   * referência, e o consumidor baixa depois — mandar base64 aqui simularia um payload que a Meta
+   * nunca produz, e o caminho testado deixaria de ser o de produção.
+   */
+  readonly mediaId: string
+  readonly mimeType?: string
+  readonly filename?: string
+  readonly caption?: string
 }
 
 export type CreatePreviewWebhookClientParams = {
@@ -57,7 +73,15 @@ export function assertPreviewEnvironment(isProduction: boolean): void {
   if (isProduction) throw new PreviewInProductionError()
 }
 
-async function signWithWebCrypto(params: { rawBody: string; appSecret: string }): Promise<string> {
+/**
+ * Assina um texto qualquer com o app secret, no mesmo formato do header da Meta.
+ *
+ * Exportada porque o preview precisa provar identidade em MAIS de um lugar: além de entregar a
+ * mensagem no webhook, ele lê o transcript de volta — e ler pela API de admin exigia uma sessão que
+ * a aba do simulador não tem. Assinar a leitura com o segredo que ele já carrega resolve sem token
+ * de admin e sem rota aberta.
+ */
+export async function signPreviewPayload(params: { rawBody: string; appSecret: string }): Promise<string> {
   const encoder = new TextEncoder()
   const key = await globalThis.crypto.subtle.importKey(
     'raw',
@@ -71,6 +95,8 @@ async function signWithWebCrypto(params: { rawBody: string; appSecret: string })
   return `sha256=${[...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, '0')).join('')}`
 }
 
+const signWithWebCrypto = signPreviewPayload
+
 export function createPreviewWebhookClient(params: CreatePreviewWebhookClientParams): PreviewWebhookClient {
   const sendPayload = async (payload: ReturnType<typeof buildInboundTextPayload>): Promise<void> => {
     // Serializa uma vez só: assinar um texto e enviar outro (mesmo com o conteúdo igual) derruba a
@@ -95,5 +121,6 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     sendButtonReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, buttonReply: reply })),
     sendListReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, listReply: reply })),
     sendAudio: (mediaId) => sendPayload(buildInboundAudioPayload({ ...envelope, mediaId })),
+    sendMedia: (media) => sendPayload(buildInboundMediaPayload({ ...envelope, ...media })),
   }
 }