@adatechnology/conversations-ui 0.1.0-rc.2 → 0.1.0-rc.20

package/src/preview/createPreviewWebhookClient.ts

@@ -0,0 +1,131 @@
+/**
+ * Cliente que entrega mensagens do preview no webhook real, assinadas com HMAC — a mesma validação
+ * de staging e produção, sem rota alternativa e sem bypass. Do ponto de vista da API, este cliente
+ * é indistinguível da Meta; o que muda é apenas quem assina.
+ *
+ * Assina com WebCrypto porque `node:crypto` não existe no navegador. Os builders vêm dos contratos
+ * (isomórficos) justamente para que o mesmo payload seja montado nos dois runtimes.
+ *
+ * ⚠️ SOMENTE EXECUÇÃO LOCAL. Isto carrega o app secret no bundle, e bundle é público onde quer que
+ * seja servido — em qualquer ambiente com URL acessível (homologação inclusive) usar esta fábrica
+ * equivale a publicar o segredo, e quem o tiver forja webhooks válidos daquele app da Meta: injeta
+ * mensagem de qualquer número e dispara os fluxos. `assertPreviewEnvironment` barra produção, mas
+ * homologação passaria, então a barreira não basta.
+ *
+ * Para qualquer ambiente publicado use `createPreviewBridgeClient`: o navegador manda a intenção e
+ * o servidor assina com o segredo que ele já tem.
+ */
+
+import {
+  buildInboundAudioPayload,
+  buildInboundInteractivePayload,
+  buildInboundMediaPayload,
+  buildInboundTextPayload,
+  serializeWebhookPayload,
+  type InboundMediaType,
+  type InteractiveReplyOption,
+} from '@adatechnology/meta-whatsapp-contracts/testing'
+
+export type PreviewWebhookClient = {
+  sendText(text: string): Promise<void>
+  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 = {
+  readonly webhookUrl: string
+  readonly appSecret: string
+  readonly from: string
+  readonly phoneNumberId?: string
+  // Escape hatch para teste; em runtime real é sempre o fetch global.
+  readonly fetchImplementation?: typeof fetch
+}
+
+export class PreviewInProductionError extends Error {
+  constructor() {
+    super('O preview de conversa carrega um app secret e não pode ser montado em produção.')
+    this.name = 'PreviewInProductionError'
+  }
+}
+
+export class PreviewWebhookRejectedError extends Error {
+  constructor(readonly status: number) {
+    super(`O webhook recusou a entrega do preview (HTTP ${status}).`)
+    this.name = 'PreviewWebhookRejectedError'
+  }
+}
+
+/**
+ * Falha alto em vez de degradar em silêncio: um preview que "quase funciona" em produção é pior
+ * que um que se recusa a montar.
+ */
+export function assertPreviewEnvironment(isProduction: boolean): void {
+  if (isProduction) throw new PreviewInProductionError()
+}
+
+/**
+ * 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',
+    encoder.encode(params.appSecret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  )
+  const signature = await globalThis.crypto.subtle.sign('HMAC', key, encoder.encode(params.rawBody))
+
+  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
+    // validação, porque o HMAC cobre os bytes exatos.
+    const rawBody = serializeWebhookPayload(payload)
+    const signature = await signWithWebCrypto({ rawBody, appSecret: params.appSecret })
+    const performRequest = params.fetchImplementation ?? fetch
+
+    const response = await performRequest(params.webhookUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-hub-signature-256': signature },
+      body: rawBody,
+    })
+
+    if (!response.ok) throw new PreviewWebhookRejectedError(response.status)
+  }
+
+  const envelope = { from: params.from, phoneNumberId: params.phoneNumberId }
+
+  return {
+    sendText: (text) => sendPayload(buildInboundTextPayload({ ...envelope, text })),
+    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 })),
+  }
+}

package/src/preview/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Export separado (`@adatechnology/conversations-ui/preview`) para que fixtures e mocks nunca
+ * entrem no bundle de produção de quem consome o pacote.
+ */
+
+export { createPreviewStore, conversationChannel, GLOBAL_CHANNEL } from './previewStore'
+export type {
+  PreviewStore,
+  CreatePreviewStoreParams,
+  PreviewEmission,
+  PreviewStoreListener,
+  AppendMessageParams,
+  SetModeParams,
+  ListConversationsFilters,
+} from './previewStore'
+
+export { createMockEventSource } from './mockEventSource'
+export type { MockEventSource } from './mockEventSource'
+
+export { createMockConversationsApi } from './createMockConversationsApi'
+export type { CreateMockConversationsApiParams } from './createMockConversationsApi'
+
+export { createMockSSEProvider } from './createMockSSEProvider'
+export type { CreateMockSSEProviderParams } from './createMockSSEProvider'
+
+export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES, PREVIEW_DOCUMENTS } from './previewFixtures'
+
+export { ConversationPreview } from './ConversationPreview'
+export { mediaTypeOf } from './ConversationPreview'
+export type { ConversationPreviewProps, PreviewUploadedMedia } from './ConversationPreview'
+
+export { AudioRecorderButton, DEFAULT_AUDIO_RECORDER_BUTTON_LABELS } from '../AudioRecorderButton'
+export type { AudioRecorderButtonProps, AudioRecorderButtonLabels } from '../AudioRecorderButton'
+
+export {
+  createPreviewWebhookClient,
+  signPreviewPayload,
+  assertPreviewEnvironment,
+  PreviewInProductionError,
+  PreviewWebhookRejectedError,
+} from './createPreviewWebhookClient'
+export type {
+  PreviewWebhookClient,
+  CreatePreviewWebhookClientParams,
+  SendPreviewMediaParams,
+} from './createPreviewWebhookClient'
+
+export { createPreviewBridgeClient, PreviewBridgeRejectedError } from './createPreviewBridgeClient'
+export type {
+  CreatePreviewBridgeClientParams,
+  PreviewInboundCommand,
+  SendPreviewInboundCommand,
+} from './createPreviewBridgeClient'
+
+export { startPreviewScript, DEFAULT_PREVIEW_SCRIPT } from './startPreviewScript'
+export type { PreviewScriptStep, StartPreviewScriptParams } from './startPreviewScript'
+export { PREVIEW_FILE_SAMPLES, resolvePreviewFileSample } from './previewFileSamples'
+export { createPreviewMediaResolver, previewFileUrl } from './previewMediaSource'
+export { previewFileBase64 } from './previewMediaSource'
+export { MediaTypesPreview, MEDIA_TYPES_CONVERSATION_ID } from './MediaTypesPreview'
+export type { MediaTypesPreviewProps } from './MediaTypesPreview'

package/src/preview/mediaTypeOf.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'bun:test'
+import { mediaTypeOf } from './ConversationPreview'
+
+describe('mediaTypeOf', () => {
+  it('deriva imagem, vídeo e áudio pelo prefixo do MIME', () => {
+    expect(mediaTypeOf('image/jpeg')).toBe('image')
+    expect(mediaTypeOf('video/mp4')).toBe('video')
+    expect(mediaTypeOf('audio/webm')).toBe('audio')
+  })
+
+  it('trata o resto como documento, inclusive MIME desconhecido', () => {
+    expect(mediaTypeOf('application/pdf')).toBe('document')
+    expect(mediaTypeOf('')).toBe('document')
+  })
+})

package/src/preview/mockDocumentsSearch.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Guarda a busca da biblioteca no mock — que é a implementação de referência da UI do SDK e tem de
+ * casar com o `companyDocumentSearch` do backend, senão o preview ensina um comportamento que a
+ * tela real não entrega.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { createMockConversationsApi } from './createMockConversationsApi'
+import { createPreviewStore } from './previewStore'
+import { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES } from './previewFixtures'
+
+function buildApi() {
+  const store = createPreviewStore({ conversations: PREVIEW_CONVERSATIONS, messages: PREVIEW_MESSAGES })
+  return createMockConversationsApi({ store })
+}
+
+async function search(term: string): Promise<{ total: number; conversations: string[] }> {
+  const page = await buildApi().getAllDocuments!({ search: term })
+  return { total: page.total, conversations: [...new Set(page.documents.map((document) => document.conversationId))] }
+}
+
+describe('busca da biblioteca no mock', () => {
+  it('acha por nome do arquivo', async () => {
+    const result = await search('contrato')
+
+    expect(result.total).toBe(1)
+  })
+
+  it('acha por telefone da conversa', async () => {
+    const porNumero = await search('94444')
+
+    expect(porNumero.conversations).toEqual(['5511944443333'])
+    expect(porNumero.total).toBeGreaterThan(0)
+    // Discrimina de verdade: 98888 é conversa que existe nas fixtures, mas sem arquivo — se o
+    // predicado do telefone não estivesse valendo, esta busca devolveria a biblioteca inteira.
+    expect((await search('98888')).total).toBe(0)
+  })
+
+  // O caso real: o atendente copia o número como a tela o mostra.
+  it('acha com o telefone formatado, como aparece na tela', async () => {
+    const cru = await search('5511944443333')
+    const formatado = await search('+55 (11) 94444-3333')
+
+    expect(formatado.total).toBe(cru.total)
+    expect(formatado.total).toBeGreaterThan(0)
+  })
+
+  it('não devolve nada para número de outra conversa', async () => {
+    expect((await search('99999999999')).total).toBe(0)
+  })
+
+  // Sem dígito, o predicado do telefone não existe — senão qualquer palavra casaria toda conversa.
+  it('termo sem dígito filtra só por nome', async () => {
+    expect((await search('zzz-inexistente')).total).toBe(0)
+  })
+})

package/src/preview/mockEventSource.ts

@@ -0,0 +1,53 @@
+/**
+ * `EventSource` só existe com um servidor HTTP do outro lado — é justamente o que falta quando se
+ * quer a inbox rodando com dados mockados. Este é o objeto mínimo que satisfaz
+ * `ConversationEventSource`: assina eventos nomeados, desassina e fecha.
+ *
+ * Não imita `EventSource` por completo de propósito: um fake "quase real" convida a depender de
+ * membros que o pacote não usa, e passa a quebrar a cada mudança de runtime.
+ */
+
+import type { ConversationEventSource } from '../providers/types'
+
+export type MockEventSource = ConversationEventSource & {
+  emit(event: string, payload: unknown): void
+  readonly closed: boolean
+}
+
+export function createMockEventSource(): MockEventSource {
+  const listeners = new Map<string, Set<(event: MessageEvent) => void>>()
+  let closed = false
+
+  return {
+    get closed(): boolean {
+      return closed
+    },
+
+    addEventListener(type: string, listener: (event: MessageEvent) => void): void {
+      const typeListeners = listeners.get(type) ?? new Set<(event: MessageEvent) => void>()
+      typeListeners.add(listener)
+      listeners.set(type, typeListeners)
+    },
+
+    removeEventListener(type: string, listener: (event: MessageEvent) => void): void {
+      listeners.get(type)?.delete(listener)
+    },
+
+    close(): void {
+      closed = true
+      listeners.clear()
+    },
+
+    emit(event: string, payload: unknown): void {
+      // Depois de fechado, emitir é no-op: o servidor real também não entrega em socket fechado, e
+      // silenciar aqui é o que faz vazamento de listener aparecer como bug de cleanup, não como
+      // evento fantasma na UI.
+      if (closed) return
+
+      // `data` é string no fio; entregar o objeto já parseado esconderia erro de serialização que
+      // aparece em produção.
+      const messageEvent = new MessageEvent(event, { data: JSON.stringify(payload) })
+      for (const listener of listeners.get(event) ?? []) listener(messageEvent)
+    },
+  }
+}

package/src/preview/preview.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'bun:test'
+import { createMockConversationsApi } from './createMockConversationsApi'
+import { createMockSSEProvider } from './createMockSSEProvider'
+import { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES } from './previewFixtures'
+import { createPreviewStore, type PreviewStore } from './previewStore'
+import { DEFAULT_PREVIEW_SCRIPT } from './startPreviewScript'
+
+function createStore(): PreviewStore {
+  return createPreviewStore({ conversations: PREVIEW_CONVERSATIONS, messages: PREVIEW_MESSAGES })
+}
+
+const WAITING_CONVERSATION_ID = '5511977776666'
+const BOT_CONVERSATION_ID = '5511988887777'
+
+describe('previewStore', () => {
+  it('filtra a fila de espera humana', () => {
+    const store = createStore()
+
+    const waiting = store.listConversations({ waitingHuman: true })
+
+    expect(waiting.map((conversation) => conversation.id)).toEqual([WAITING_CONVERSATION_ID])
+  })
+
+  it('busca por nome e por número', () => {
+    const store = createStore()
+
+    expect(store.listConversations({ search: 'marina' })).toHaveLength(1)
+    expect(store.listConversations({ search: '9777' })).toHaveLength(1)
+  })
+
+  it('assumir a conversa apaga a espera por humano', () => {
+    const store = createStore()
+
+    store.setMode({ conversationId: WAITING_CONVERSATION_ID, mode: 'human', assignedUserId: 'agent-2' })
+    const conversation = store.listConversations().find((item) => item.id === WAITING_CONVERSATION_ID)
+
+    expect(conversation?.mode).toBe('human')
+    expect(conversation?.assignedUserId).toBe('agent-2')
+    expect(conversation?.waitingHuman).toBe(false)
+  })
+
+  it('mensagem recebida incrementa não-lidas e markRead zera', () => {
+    const store = createStore()
+    const before = store.listConversations().find((item) => item.id === BOT_CONVERSATION_ID)?.unread ?? 0
+
+    store.appendMessage({
+      conversationId: BOT_CONVERSATION_ID,
+      content: 'e o troco?',
+      direction: 'inbound',
+      sender: 'customer',
+    })
+    const after = store.listConversations().find((item) => item.id === BOT_CONVERSATION_ID)?.unread
+
+    expect(after).toBe(before + 1)
+
+    store.markRead(BOT_CONVERSATION_ID)
+    expect(store.listConversations().find((item) => item.id === BOT_CONVERSATION_ID)?.unread).toBe(0)
+  })
+})
+
+describe('createMockSSEProvider', () => {
+  // Paridade com o servidor: o evento `message` é ping, não entrega de dados. Se este teste
+  // começar a exigir `content`, o mock passou a mentir sobre o que a produção envia.
+  it('entrega evento message como ping, sem conteúdo, com data serializada', () => {
+    const store = createStore()
+    const sse = createMockSSEProvider({ store })
+    const source = sse.connectConversationStream(BOT_CONVERSATION_ID)
+    const received: string[] = []
+
+    source.addEventListener('message', (event) => received.push(event.data as string))
+    store.appendMessage({
+      conversationId: BOT_CONVERSATION_ID,
+      content: 'oi',
+      direction: 'inbound',
+      sender: 'customer',
+    })
+
+    expect(received).toHaveLength(1)
+    expect(JSON.parse(received[0] ?? '{}')).toEqual({ direction: 'inbound', sender: 'customer' })
+  })
+
+  it('emite mode-changed e data-changed nos canais certos', () => {
+    const store = createStore()
+    const sse = createMockSSEProvider({ store })
+    const conversationEvents: string[] = []
+    const globalEvents: string[] = []
+
+    sse
+      .connectConversationStream(WAITING_CONVERSATION_ID)
+      .addEventListener('mode-changed', () => conversationEvents.push('mode-changed'))
+    sse.connectGlobalStream().addEventListener('data-changed', () => globalEvents.push('data-changed'))
+
+    store.setMode({ conversationId: WAITING_CONVERSATION_ID, mode: 'human', assignedUserId: 'agent-2' })
+
+    expect(conversationEvents).toEqual(['mode-changed'])
+    expect(globalEvents).toEqual(['data-changed'])
+  })
+
+  // A regressão que isto tranca: sem desassinar do store no close, cada remontagem de componente
+  // deixaria um listener preso e a mesma mensagem chegaria duplicada na UI.
+  it('desassina do store ao fechar o stream', () => {
+    const store = createStore()
+    const sse = createMockSSEProvider({ store })
+    const source = sse.connectConversationStream(BOT_CONVERSATION_ID)
+    const received: string[] = []
+
+    source.addEventListener('message', (event) => received.push(event.data as string))
+    source.close()
+    store.appendMessage({
+      conversationId: BOT_CONVERSATION_ID,
+      content: 'oi',
+      direction: 'inbound',
+      sender: 'customer',
+    })
+
+    expect(received).toHaveLength(0)
+  })
+})
+
+describe('createMockConversationsApi', () => {
+  // Modela o fluxo real: o ping avisa, o refetch traz o dado. É o compartilhamento de store que
+  // faz os dois concordarem — com estados separados, o ping anunciaria algo que a query não vê.
+  it('ping do SSE e refetch da API contam a mesma história', async () => {
+    const store = createStore()
+    const api = createMockConversationsApi({ store, latencyMs: 0 })
+    const sse = createMockSSEProvider({ store })
+    const pings: unknown[] = []
+
+    sse.connectConversationStream(BOT_CONVERSATION_ID).addEventListener('message', (event) => {
+      pings.push(JSON.parse(event.data as string))
+    })
+
+    await api.sendMessage(BOT_CONVERSATION_ID, 'já separei aqui')
+    const messages = await api.fetchMessages(BOT_CONVERSATION_ID)
+
+    expect(pings).toEqual([{ direction: 'outbound', sender: 'agent' }])
+    expect(messages.at(-1)?.content).toBe('já separei aqui')
+    expect(messages.at(-1)?.sender).toBe('agent')
+  })
+
+  it('pagina e filtra pela mesma regra do store', async () => {
+    const store = createStore()
+    const api = createMockConversationsApi({ store, latencyMs: 0 })
+
+    const firstPage = await api.fetchConversations({ page: 1, limit: 2 })
+    const waiting = await api.fetchConversations({ waitingHuman: true })
+
+    expect(firstPage.conversations).toHaveLength(2)
+    // O total conta o conjunto filtrado inteiro, não a fatia — é o que a paginação da UI lê.
+    expect(firstPage.total).toBeGreaterThan(2)
+    expect(waiting.conversations.every((conversation) => conversation.waitingHuman)).toBe(true)
+  })
+
+  it('markRead zera as não-lidas vistas pela lista', async () => {
+    const store = createStore()
+    const api = createMockConversationsApi({ store, latencyMs: 0 })
+
+    await api.markRead(BOT_CONVERSATION_ID)
+    const conversations = await api.fetchConversations()
+
+    expect(conversations.conversations.find((item) => item.id === BOT_CONVERSATION_ID)?.unread).toBe(0)
+  })
+})
+
+describe('roteiro padrão', () => {
+  // O roteiro é o que faz a inbox deixar de ser tela estática; se algum passo apontar para uma
+  // conversa que não existe nas fixtures, ele passa a ser no-op silencioso.
+  it('todos os passos alteram o estado das conversas das fixtures', () => {
+    const store = createStore()
+    const before = JSON.stringify(store.listConversations())
+
+    for (const step of DEFAULT_PREVIEW_SCRIPT) step(store)
+
+    expect(JSON.stringify(store.listConversations())).not.toBe(before)
+    expect(store.listMessages(WAITING_CONVERSATION_ID).at(-1)?.sender).toBe('agent')
+  })
+})

package/src/preview/previewFileSamples.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Guarda que o preview entrega arquivo do tipo que promete.
+ *
+ * O defeito que motivou o arquivo: `getDocumentUrl` devolvia sempre a mesma imagem PNG, então
+ * "visualizar" num PDF abria um PNG rotulado `application/pdf` e o leitor dizia que o arquivo era
+ * inválido. Aqui os bytes são decodificados e conferidos pela assinatura de cada formato — teste que
+ * só olhasse o prefixo da data URL passaria com o bug de volta.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { PREVIEW_FILE_SAMPLES, resolvePreviewFileSample } from './previewFileSamples'
+import { PREVIEW_DOCUMENTS } from './previewFixtures'
+
+function decode(dataUrl: string): { mimeType: string; bytes: Uint8Array } {
+  const [head, payload] = dataUrl.split(',')
+  const mimeType = head!.replace(/^data:/, '').replace(/;base64$/, '')
+  if (!head!.endsWith(';base64')) {
+    return { mimeType, bytes: new TextEncoder().encode(decodeURIComponent(payload!)) }
+  }
+  return { mimeType, bytes: Uint8Array.from(atob(payload!), (char) => char.charCodeAt(0)) }
+}
+
+function startsWith(bytes: Uint8Array, signature: readonly number[], offset = 0): boolean {
+  return signature.every((byte, index) => bytes[offset + index] === byte)
+}
+
+const ascii = (text: string): number[] => [...text].map((char) => char.charCodeAt(0))
+
+// Assinatura real de cada formato, não o rótulo do mimeType.
+const SIGNATURES: Record<string, (bytes: Uint8Array) => boolean> = {
+  'application/pdf': (bytes) => startsWith(bytes, ascii('%PDF-')),
+  'image/png': (bytes) => startsWith(bytes, [0x89, 0x50, 0x4e, 0x47]),
+  'image/jpeg': (bytes) => startsWith(bytes, [0xff, 0xd8, 0xff]),
+  'image/webp': (bytes) => startsWith(bytes, ascii('RIFF')) && startsWith(bytes, ascii('WEBP'), 8),
+  'video/mp4': (bytes) => startsWith(bytes, ascii('ftyp'), 4),
+  'audio/mp4': (bytes) => startsWith(bytes, ascii('ftyp'), 4),
+  // ID3 quando há tag, ou o sync do primeiro frame MPEG.
+  'audio/mpeg': (bytes) => startsWith(bytes, ascii('ID3')) || (bytes[0] === 0xff && (bytes[1]! & 0xe0) === 0xe0),
+  'audio/ogg': (bytes) => startsWith(bytes, ascii('OggS')),
+  'audio/aac': (bytes) => bytes[0] === 0xff && (bytes[1]! & 0xf0) === 0xf0,
+  'text/plain': (bytes) => bytes.length > 0,
+  'text/csv': (bytes) => bytes.length > 0,
+  // Todo pacote Office é zip: assinatura PK\x03\x04.
+  'application/zip': (bytes) => startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]),
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': (bytes) =>
+    startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]),
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': (bytes) =>
+    startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]),
+}
+
+describe('amostras de arquivo do preview', () => {
+  it('toda amostra declara o mimeType que anuncia', () => {
+    for (const [mimeType, dataUrl] of Object.entries(PREVIEW_FILE_SAMPLES)) {
+      expect(decode(dataUrl).mimeType).toBe(mimeType)
+    }
+  })
+
+  for (const [mimeType, isValid] of Object.entries(SIGNATURES)) {
+    it(`os bytes de ${mimeType} são realmente desse formato`, () => {
+      const sample = PREVIEW_FILE_SAMPLES[mimeType]
+      expect(sample).toBeDefined()
+      expect(isValid(decode(sample!).bytes)).toBe(true)
+    })
+  }
+
+  // O PDF sem xref/startxref é o caso que alguns leitores recusam de cara.
+  it('o PDF tem tabela xref e termina em %%EOF', () => {
+    const text = new TextDecoder().decode(decode(PREVIEW_FILE_SAMPLES['application/pdf']!).bytes)
+
+    expect(text).toContain('\nxref\n')
+    expect(text).toContain('startxref')
+    expect(text.trimEnd().endsWith('%%EOF')).toBe(true)
+  })
+})
+
+describe('resolvePreviewFileSample', () => {
+  it('descarta parâmetro do mimeType — áudio de WhatsApp chega com codecs', () => {
+    expect(resolvePreviewFileSample('audio/ogg; codecs=opus')).toBe(PREVIEW_FILE_SAMPLES['audio/ogg'])
+  })
+
+  // Tipos aceitos pela Meta sem amostra local (sem encoder amr/3gp nesta máquina): tocam pela
+  // família, em vez de devolver bytes de outro formato.
+  it('cai na família quando não há amostra do tipo exato', () => {
+    expect(resolvePreviewFileSample('audio/amr')).toBe(PREVIEW_FILE_SAMPLES['audio/mpeg'])
+    expect(resolvePreviewFileSample('video/3gp')).toBe(PREVIEW_FILE_SAMPLES['video/mp4'])
+    expect(resolvePreviewFileSample('image/heic')).toBe(PREVIEW_FILE_SAMPLES['image/png'])
+  })
+
+  // Office legado é OLE2, não zip: servir o docx aqui daria arquivo corrompido no Word. Melhor um
+  // texto que abre e se explica.
+  it('explica em texto quando não há como forjar o binário', () => {
+    const resolved = resolvePreviewFileSample('application/msword', 'procuracao.doc')
+
+    expect(resolved.startsWith('data:text/plain')).toBe(true)
+    expect(decodeURIComponent(resolved)).toContain('procuracao.doc')
+  })
+
+  it('não devolve vazio para tipo desconhecido', () => {
+    expect(resolvePreviewFileSample(undefined).length).toBeGreaterThan(0)
+    expect(resolvePreviewFileSample('application/octet-stream').length).toBeGreaterThan(0)
+  })
+})
+
+describe('biblioteca do preview', () => {
+  // A infidelidade que existia: a biblioteca listava só `document`, enquanto o backend linka as
+  // cinco espécies de mídia. Foto, vídeo, áudio e sticker apareciam na tela real e não no preview.
+  it('lista foto, vídeo, áudio e sticker junto dos documentos', () => {
+    const mimeTypes = (PREVIEW_DOCUMENTS['5511944443333'] ?? []).map((document) => document.mimeType)
+
+    expect(mimeTypes.some((mimeType) => mimeType.startsWith('image/'))).toBe(true)
+    expect(mimeTypes.some((mimeType) => mimeType.startsWith('video/'))).toBe(true)
+    expect(mimeTypes.some((mimeType) => mimeType.startsWith('audio/'))).toBe(true)
+    expect(mimeTypes).toContain('image/webp')
+  })
+
+  // Cada tipo que a Cloud API da Meta aceita para envio de mídia.
+  const ACCEPTED_BY_META = [
+    'image/jpeg',
+    'image/png',
+    'image/webp',
+    'video/mp4',
+    'video/3gp',
+    'audio/aac',
+    'audio/amr',
+    'audio/mpeg',
+    'audio/mp4',
+    'audio/ogg',
+    'application/pdf',
+    'application/msword',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.ms-excel',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    'application/vnd.ms-powerpoint',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    'text/plain',
+  ]
+
+  it('cobre todo tipo aceito pela Meta', () => {
+    const present = new Set((PREVIEW_DOCUMENTS['5511944443333'] ?? []).map((document) => document.mimeType))
+    const faltando = ACCEPTED_BY_META.filter((mimeType) => !present.has(mimeType))
+
+    expect(faltando).toEqual([])
+  })
+
+  it('todo item da biblioteca abre com bytes não vazios', () => {
+    for (const document of PREVIEW_DOCUMENTS['5511944443333'] ?? []) {
+      expect(decode(resolvePreviewFileSample(document.mimeType, document.filename)).bytes.length).toBeGreaterThan(0)
+    }
+  })
+})