@adatechnology/conversations-ui 0.1.0-rc.4 → 0.1.0-rc.6

package/src/preview/previewFixtures.ts

@@ -5,7 +5,7 @@
  */
 
 import type { MessagePayload } from '../types'
-import type { ConversationSummary } from '../providers/types'
+import type { ConversationDocument, ConversationSummary } from '../providers/types'
 
 // Datas fixas: fixture com data relativa ao relógio faz o mesmo cenário renderizar diferente a
 // cada execução, e separadores de dia deixam de ser verificáveis.
@@ -71,6 +71,24 @@ export const PREVIEW_CONVERSATIONS: readonly ConversationSummary[] = [
     unread: 1,
     currentState: 'list_import',
   },
+  {
+    // Cobre TODO tipo que o composer aceita (DEFAULT_ACCEPTED_FILE_TYPES: image/*, video/*,
+    // audio/*, .pdf, .doc, .docx, .xls, .xlsx, .zip) mais sticker. Existe para que cada ramo do
+    // MediaRenderer e cada ícone/cor do FileIcon apareçam em algum lugar — ramo sem fixture é ramo
+    // que ninguém olha até quebrar em produção.
+    id: '5511944443333',
+    whatsappNumber: '5511944443333',
+    clientName: 'Rita Documentos',
+    lastContent: 'segue a planilha do pedido',
+    lastDirection: 'inbound',
+    lastAt: at('15:10:00'),
+    lastInboundAt: at('15:10:00'),
+    mode: 'human',
+    assignedUserId: 'agent-1',
+    waitingHuman: false,
+    unread: 3,
+    currentState: 'human_handling',
+  },
 ]
 
 export const PREVIEW_MESSAGES: Readonly<Record<string, readonly MessagePayload[]>> = {
@@ -150,4 +168,273 @@ export const PREVIEW_MESSAGES: Readonly<Record<string, readonly MessagePayload[]
       timestamp: at('13:31:00'),
     },
   ],
+  // Um tipo por mensagem, na ordem em que o MediaRenderer os trata.
+  '5511944443333': [
+    {
+      id: 'fixture-doc-image',
+      type: 'image',
+      mediaId: 'preview-image-1',
+      mimeType: 'image/png',
+      caption: 'foto da prateleira',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:00:00'),
+    },
+    {
+      id: 'fixture-doc-video',
+      type: 'video',
+      mediaId: 'preview-video-1',
+      mimeType: 'video/mp4',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:01:00'),
+    },
+    {
+      id: 'fixture-doc-audio',
+      type: 'audio',
+      mediaId: 'preview-audio-2',
+      mimeType: 'audio/ogg',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:02:00'),
+    },
+    {
+      id: 'fixture-doc-sticker',
+      type: 'sticker',
+      mediaId: 'preview-sticker-1',
+      mimeType: 'image/webp',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:03:00'),
+    },
+    // Os cinco ramos do FileIcon: pdf, doc, xls, zip e o genérico do fallback.
+    {
+      id: 'fixture-doc-pdf',
+      type: 'document',
+      uploadId: 'preview/documentos/nota-fiscal.pdf',
+      filename: 'nota-fiscal.pdf',
+      mimeType: 'application/pdf',
+      sizeBytes: 184_320,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:04:00'),
+    },
+    {
+      id: 'fixture-doc-docx',
+      type: 'document',
+      uploadId: 'preview/documentos/contrato.docx',
+      filename: 'contrato.docx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      sizeBytes: 42_112,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:05:00'),
+    },
+    {
+      id: 'fixture-doc-doc',
+      type: 'document',
+      uploadId: 'preview/documentos/procuracao.doc',
+      filename: 'procuracao.doc',
+      mimeType: 'application/msword',
+      sizeBytes: 31_744,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:06:00'),
+    },
+    {
+      id: 'fixture-doc-xlsx',
+      type: 'document',
+      uploadId: 'preview/documentos/pedido.xlsx',
+      filename: 'pedido.xlsx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      sizeBytes: 15_872,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:07:00'),
+    },
+    {
+      id: 'fixture-doc-xls',
+      type: 'document',
+      uploadId: 'preview/documentos/tabela-antiga.xls',
+      filename: 'tabela-antiga.xls',
+      mimeType: 'application/vnd.ms-excel',
+      sizeBytes: 9_216,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:08:00'),
+    },
+    {
+      id: 'fixture-doc-zip',
+      type: 'document',
+      uploadId: 'preview/documentos/comprovantes.zip',
+      filename: 'comprovantes.zip',
+      mimeType: 'application/zip',
+      sizeBytes: 2_355_200,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:09:00'),
+    },
+    {
+      id: 'fixture-doc-txt',
+      type: 'document',
+      uploadId: 'preview/documentos/lista-compras.txt',
+      filename: 'lista-compras.txt',
+      mimeType: 'text/plain',
+      sizeBytes: 1_024,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:10:00'),
+    },
+    {
+      id: 'fixture-doc-csv',
+      type: 'document',
+      uploadId: 'preview/documentos/planilha-do-pedido.csv',
+      filename: 'planilha-do-pedido.csv',
+      mimeType: 'text/csv',
+      sizeBytes: 2_048,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:11:00'),
+    },
+    {
+      id: 'fixture-doc-pptx',
+      type: 'document',
+      uploadId: 'preview/documentos/apresentacao.pptx',
+      filename: 'apresentacao.pptx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      sizeBytes: 512_000,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:12:00'),
+    },
+    {
+      id: 'fixture-doc-ppt',
+      type: 'document',
+      uploadId: 'preview/documentos/antiga.ppt',
+      filename: 'antiga.ppt',
+      mimeType: 'application/vnd.ms-powerpoint',
+      sizeBytes: 348_160,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:13:00'),
+    },
+    // Mídia enviada COMO arquivo: aí a Meta manda o nome, então é onde a extensão de música e de
+    // vídeo aparece na lista. Mandada como `image`/`audio`/`video` (acima e abaixo) ela chega sem
+    // nome nenhum, e o rótulo vira o id da mídia — como em produção.
+    {
+      id: 'fixture-doc-mp3',
+      type: 'document',
+      uploadId: 'preview/documentos/musica-do-anuncio.mp3',
+      filename: 'musica-do-anuncio.mp3',
+      mimeType: 'audio/mpeg',
+      sizeBytes: 3_145_728,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:14:00'),
+    },
+    {
+      id: 'fixture-doc-m4a',
+      type: 'document',
+      uploadId: 'preview/documentos/recado.m4a',
+      filename: 'recado.m4a',
+      mimeType: 'audio/mp4',
+      sizeBytes: 486_400,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:15:00'),
+    },
+    {
+      id: 'fixture-doc-mp4-file',
+      type: 'document',
+      uploadId: 'preview/documentos/video-do-produto.mp4',
+      filename: 'video-do-produto.mp4',
+      mimeType: 'video/mp4',
+      sizeBytes: 8_388_608,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:16:00'),
+    },
+    {
+      id: 'fixture-doc-jpg',
+      type: 'document',
+      uploadId: 'preview/documentos/foto-do-recibo.jpg',
+      filename: 'foto-do-recibo.jpg',
+      mimeType: 'image/jpeg',
+      sizeBytes: 262_144,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:17:00'),
+    },
+    // As espécies restantes que a Meta aceita, sem nome de arquivo — fecham a lista de tipos
+    // aceitos e exercitam o fallback de ícone pela família do mimeType.
+    {
+      id: 'fixture-media-jpeg',
+      type: 'image',
+      mediaId: 'preview-image-jpeg',
+      mimeType: 'image/jpeg',
+      sizeBytes: 138_240,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:18:00'),
+    },
+    {
+      id: 'fixture-media-3gp',
+      type: 'video',
+      mediaId: 'preview-video-3gp',
+      mimeType: 'video/3gp',
+      sizeBytes: 921_600,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:19:00'),
+    },
+    {
+      id: 'fixture-media-aac',
+      type: 'audio',
+      mediaId: 'preview-audio-aac',
+      mimeType: 'audio/aac',
+      sizeBytes: 76_800,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:20:00'),
+    },
+    {
+      id: 'fixture-media-amr',
+      type: 'audio',
+      mediaId: 'preview-audio-amr',
+      mimeType: 'audio/amr',
+      sizeBytes: 24_576,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:21:00'),
+    },
+  ],
+}
+
+/**
+ * A biblioteca de arquivos da conversa, como o backend a devolveria. Deriva das mensagens acima em
+ * vez de repetir os dados: fixture duplicada divergiria na primeira edição, e o painel passaria a
+ * mostrar arquivo que a thread não tem.
+ *
+ * Entram as CINCO espécies de mídia, na mesma lista de `extractMediaDescriptor` no backend — não só
+ * `document`. Filtrar por documento era infidelidade grave do preview: `IngestInboundMedia` linka
+ * foto, vídeo, áudio e sticker na mesma tabela, então na tela real eles aparecem na biblioteca e no
+ * preview não apareciam.
+ */
+const LIBRARY_MEDIA_TYPES = new Set(['document', 'image', 'video', 'audio', 'sticker'])
+
+export const PREVIEW_DOCUMENTS: Readonly<Record<string, readonly ConversationDocument[]>> = {
+  '5511944443333': (PREVIEW_MESSAGES['5511944443333'] ?? [])
+    .filter((message) => LIBRARY_MEDIA_TYPES.has(message.type))
+    .map((message) => ({
+      // Mídia não tem `uploadId` na mensagem: o backend deriva a key do id da mídia na Meta, e o
+      // caminho abaixo imita esse formato para o download assinado receber algo do mesmo feitio.
+      id: message.uploadId ?? (message.mediaId ? `preview/inbound/${message.mediaId}` : message.id),
+      // Só documento chega nomeado. Para os outros o backend salva o id da mídia como rótulo —
+      // manter isso aqui é o que faz o ícone por família do mimeType ser exercitado de verdade.
+      filename: message.filename ?? message.mediaId ?? message.id,
+      mimeType: message.mimeType ?? 'application/octet-stream',
+      sizeBytes: message.sizeBytes ?? 0,
+      source: message.sender,
+      linkedAt: message.timestamp,
+    })),
 }

package/src/preview/previewMediaSource.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Guarda o resolvedor de mídia do preview.
+ *
+ * As asserções comparam com `previewFileUrl(tipo)` em vez de com a data URL da amostra: o bun também
+ * tem `URL.createObjectURL`, então o retorno é `blob:` aqui como no navegador, e blob URL não expõe
+ * o conteúdo para comparar. O que este teste trava é o MAPEAMENTO — mensagem → amostra do tipo certo
+ * —, enquanto os bytes de cada tipo são conferidos em `previewFileSamples.test.ts`.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { createPreviewMediaResolver, previewFileUrl } from './previewMediaSource'
+import type { MessagePayload } from '../types'
+
+const resolve = createPreviewMediaResolver()
+
+function message(partial: Partial<MessagePayload>): MessagePayload {
+  return {
+    id: 'msg-1',
+    type: 'image',
+    direction: 'inbound',
+    sender: 'customer',
+    timestamp: '2026-07-26T15:00:00.000Z',
+    ...partial,
+  } as MessagePayload
+}
+
+describe('createPreviewMediaResolver', () => {
+  it('resolve mídia pelo mediaId, achando o tipo na biblioteca do fixture', async () => {
+    // preview-image-1 é a foto png da thread da Rita.
+    expect(await resolve(message({ mediaId: 'preview-image-1' }))).toBe(previewFileUrl('image/png'))
+  })
+
+  it('resolve documento pelo uploadId', async () => {
+    const resolved = await resolve(message({ type: 'document', uploadId: 'preview/documentos/nota-fiscal.pdf' }))
+
+    expect(resolved).toBe(previewFileUrl('application/pdf'))
+  })
+
+  // O sticker é webp e o áudio de voz é opus: dois tipos que o painel antes nem listava.
+  it('resolve sticker e áudio', async () => {
+    expect(await resolve(message({ mediaId: 'preview-sticker-1' }))).toBe(previewFileUrl('image/webp'))
+    expect(await resolve(message({ mediaId: 'preview-audio-2' }))).toBe(previewFileUrl('audio/ogg'))
+  })
+
+  // Mídia que não está na biblioteca ainda tem de abrir: cai no mimeType da própria mensagem.
+  it('usa o mimeType da mensagem quando o id é desconhecido', async () => {
+    const resolved = await resolve(message({ mediaId: 'nunca-visto', mimeType: 'image/jpeg' }))
+
+    expect(resolved).toBe(previewFileUrl('image/jpeg'))
+  })
+
+  // Sem referência nenhuma o MediaRenderer não deve receber URL — devolver algo aqui faria a bolha
+  // mostrar arquivo que a mensagem não tem.
+  it('devolve null para mensagem sem uploadId nem mediaId', async () => {
+    expect(await resolve(message({ type: 'text' }))).toBeNull()
+  })
+
+  it('reaproveita a mesma URL para o mesmo tipo', () => {
+    expect(previewFileUrl('application/pdf')).toBe(previewFileUrl('application/pdf'))
+  })
+})

package/src/preview/previewMediaSource.ts

@@ -0,0 +1,91 @@
+/**
+ * Como o preview entrega mídia para a UI abrir.
+ *
+ * Separado de `previewFileSamples` (que é gerado) porque aqui está a parte que depende do navegador:
+ * **blob URL, não data URL**. O Chrome bloqueia navegação de topo para `data:` desde a v60, então
+ * `window.open(dataUrl)` — que é o que os botões "visualizar" e "baixar" fazem — abre aba em branco
+ * mesmo com bytes perfeitamente válidos. Em `src` de `<img>`/`<video>` a data URL funcionaria; no
+ * `window.open` não, e o mesmo `getDocumentUrl` alimenta os dois.
+ */
+
+import type { MessagePayload } from '../types'
+import type { ResolveMediaUrl } from '../MediaRenderer'
+import { resolvePreviewFileSample } from './previewFileSamples'
+import { PREVIEW_DOCUMENTS } from './previewFixtures'
+
+// Uma blob URL por tipo, reaproveitada: cada `createObjectURL` retém o blob até um `revokeObjectURL`
+// que ninguém chamaria, e a lista redesenha a cada filtro digitado.
+const blobUrlCache = new Map<string, string>()
+
+function toBlob(dataUrl: string): Blob {
+  const [head, payload] = dataUrl.split(',')
+  const mimeType = head!
+    .replace(/^data:/, '')
+    .replace(/;base64$/, '')
+    .replace(/;charset=.*$/, '')
+
+  if (!head!.endsWith(';base64')) {
+    return new Blob([decodeURIComponent(payload!)], { type: mimeType || 'text/plain' })
+  }
+
+  const binary = atob(payload!)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index)
+  return new Blob([bytes], { type: mimeType })
+}
+
+/** URL que o preview pode abrir em aba nova. Cai na data URL fora do navegador (teste, SSR). */
+export function previewFileUrl(mimeType: string | undefined, filename?: string): string {
+  const dataUrl = resolvePreviewFileSample(mimeType, filename)
+  if (typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') return dataUrl
+
+  const cached = blobUrlCache.get(dataUrl)
+  if (cached) return cached
+
+  const blobUrl = URL.createObjectURL(toBlob(dataUrl))
+  blobUrlCache.set(dataUrl, blobUrl)
+  return blobUrl
+}
+
+/**
+ * A mesma amostra em base64 cru, como o proxy de mídia do backend a devolveria.
+ *
+ * Existe porque `getMediaProxyUrl` é o caminho da mídia AINDA NÃO ingerida (só existe o id na Meta),
+ * e o contrato pede `{ mimeType, data }` — não URL. Sem isto o mock devolvia o PNG 1x1 para
+ * qualquer id, e vídeo e áudio da thread apareciam quebrados apesar de haver amostra válida.
+ */
+export function previewFileBase64(mimeType: string | undefined, filename?: string): { mimeType: string; data: string } {
+  const dataUrl = resolvePreviewFileSample(mimeType, filename)
+  const [head, payload] = dataUrl.split(',')
+  const declared = head!
+    .replace(/^data:/, '')
+    .replace(/;base64$/, '')
+    .replace(/;charset=.*$/, '')
+
+  if (head!.endsWith(';base64')) return { mimeType: declared, data: payload! }
+  return { mimeType: declared, data: btoa(decodeURIComponent(payload!)) }
+}
+
+/**
+ * O `onResolveMediaUrl` que o `MessageBubble` espera.
+ *
+ * Sem ele, foto, vídeo e áudio da thread ficam parados no placeholder para sempre — o
+ * `MediaRenderer` só resolve `uploadId`/`mediaId` por esta porta, de propósito, para o pacote nunca
+ * chamar endpoint fixo. O preview não tinha resolvedor nenhum, então nenhuma mídia carregava.
+ */
+export function createPreviewMediaResolver(): ResolveMediaUrl {
+  const byId = new Map<string, { mimeType: string; filename: string }>()
+  for (const documents of Object.values(PREVIEW_DOCUMENTS)) {
+    for (const document of documents) {
+      byId.set(document.id, { mimeType: document.mimeType, filename: document.filename })
+    }
+  }
+
+  return async (message: MessagePayload): Promise<string | null> => {
+    const reference = message.uploadId ?? (message.mediaId ? `preview/inbound/${message.mediaId}` : undefined)
+    if (!reference) return null
+
+    const known = byId.get(reference)
+    return previewFileUrl(known?.mimeType ?? message.mimeType, known?.filename ?? message.filename)
+  }
+}

package/src/providers/types.ts

@@ -1,28 +1,139 @@
 import type { MessagePayload } from '../types'
 import type { ConversationChannel } from '../conversationChannel'
 
+export interface ListConversationsParams {
+  page?: number
+  limit?: number
+  waitingHuman?: boolean
+  search?: string
+  /**
+   * Recortes que só o produto conhece (tipo de financiamento, carteira, campanha) repassados
+   * crus ao backend dele. É o que evita o vocabulário de uma vertical virar campo fixo aqui:
+   * o pacote transporta o filtro sem saber o que ele significa.
+   */
+  filters?: Record<string, string | undefined>
+}
+
+/**
+ * Página com o total, para a UI conseguir desenhar controles de paginação.
+ *
+ * `fetchConversations` devolve isto **ou** o array puro de antes: implementações existentes
+ * continuam válidas sem mudar uma linha, e quem precisa paginar passa a ter o total. Sem a união
+ * seria impossível saber se um retorno curto é a última página ou uma página cheia por acaso.
+ */
+export interface ConversationPage {
+  conversations: ConversationSummary[]
+  total: number
+}
+
+export interface ListDocumentsParams {
+  search?: string
+  page?: number
+  /** Tamanho da página. Sem ele, `page` sozinho não define fatia nenhuma. */
+  limit?: number
+  /** Origem do arquivo (`customer`, `agent`, `bot`…). O vocabulário é do host. */
+  source?: string
+  sortDirection?: 'asc' | 'desc'
+}
+
+/** Arquivo na biblioteca da empresa: o mesmo da conversa, mais de qual conversa veio. */
+export interface CompanyDocument extends ConversationDocument {
+  conversationId: string
+}
+
+export interface CompanyDocumentPage {
+  documents: CompanyDocument[]
+  total: number
+}
+
+export interface ConversationDocumentPage {
+  documents: ConversationDocument[]
+  total: number
+}
+
+/**
+ * Template disponível para envio a partir da inbox. Distinto do `WhatsAppTemplateSummary` de
+ * `settings/`, e de propósito: aquele serve ao formulário que **edita** template e carrega o que
+ * a edição precisa (`shortId`, `variableCount`); este serve a quem só vai **escolher um para
+ * enviar**, e pedir os campos de edição obrigaria todo host a produzi-los sem uso.
+ */
+export interface ConversationTemplate {
+  name: string
+  language: string
+  status: string
+  category?: string
+  bodyText?: string | null
+}
+
 export interface ConversationsApi {
   fetchMessages(conversationId: string, params?: { limit?: number; before?: string }): Promise<MessagePayload[]>
-  fetchConversations(params?: {
-    page?: number
-    limit?: number
-    waitingHuman?: boolean
-    search?: string
-  }): Promise<ConversationSummary[]>
+  fetchConversations(params?: ListConversationsParams): Promise<ConversationSummary[] | ConversationPage>
   sendMessage(conversationId: string, text: string): Promise<MessagePayload>
   sendMedia(
     conversationId: string,
     data: { base64: string; mimeType: string; filename: string; caption?: string },
   ): Promise<MessagePayload>
+  /**
+   * `templateName` é opcional porque reabrir a janela é a operação, e escolher *qual* template a
+   * usa nem sempre é decisão da UI: backends que guardam um template padrão configurado só
+   * precisam do "reabra". Exigir o nome obrigaria toda inbox a listar templates antes de poder
+   * mandar o primeiro — e a listagem é `listTemplates?`, opcional.
+   */
   sendTemplate(
     conversationId: string,
-    data: { templateName: string; languageCode?: string; bodyParams?: string[] },
+    data: { templateName?: string; languageCode?: string; bodyParams?: string[] },
   ): Promise<void>
   markRead(conversationId: string): Promise<void>
   getContext(conversationId: string): Promise<Record<string, unknown>>
-  getDocuments(conversationId: string, params?: { search?: string; page?: number }): Promise<ConversationDocument[]>
-  getDocumentUrl(uploadId: string): Promise<string>
+  getDocuments(
+    conversationId: string,
+    params?: ListDocumentsParams,
+  ): Promise<ConversationDocument[] | ConversationDocumentPage>
+  /**
+   * `disposition` decide entre abrir no navegador e baixar. É o backend que assina a URL e grava
+   * o `Content-Disposition` nela, então a escolha precisa viajar na chamada — depois de assinada
+   * não há como o cliente mudá-la. Ausente = o padrão do host.
+   */
+  getDocumentUrl(uploadId: string, disposition?: 'inline' | 'attachment'): Promise<string>
+  /**
+   * Baixa vários arquivos num zip único.
+   *
+   * **Opcional por capacidade:** montar zip exige o host LER os bytes do storage, o que nem toda
+   * instalação faz — as que só assinam URL não conseguem. Ausente, o painel esconde a seleção em
+   * lote em vez de oferecer um botão que falha.
+   */
+  downloadDocumentsArchive?(conversationId: string, uploadIds: readonly string[]): Promise<Blob>
+  /**
+   * Biblioteca de TODAS as conversas, para uma tela de Documentos fora do atendimento.
+   *
+   * Opcional por capacidade: host que só expõe anexo dentro da conversa não implementa, e o
+   * componente de biblioteca simplesmente não é usável — melhor que uma tela que sempre erra.
+   */
+  getAllDocuments?(params?: ListDocumentsParams): Promise<CompanyDocumentPage>
   getMediaProxyUrl(mediaId: string): Promise<{ mimeType: string; data: string }>
+
+  /**
+   * Operações de atendimento humano. **Opcionais por capacidade, não por descuido:** nem toda
+   * inbox tem fila humana — um canal só-bot, ou um chat de site sem operador, não sabe o que é
+   * assumir conversa. Quem não implementa não ganha o botão, em vez de ganhar um botão que
+   * estoura no clique. Os hooks devolvem `undefined` para a ação ausente, e é isso que a UI
+   * consulta para decidir se desenha a afordância.
+   */
+  takeover?(conversationId: string): Promise<void>
+  release?(conversationId: string): Promise<void>
+  /** Encerra o atendimento. Despedida, se houver, é decisão do host — o pacote não a inventa. */
+  finalize?(conversationId: string): Promise<void>
+
+  markAllRead?(): Promise<void>
+  listTemplates?(): Promise<ConversationTemplate[]>
+
+  /**
+   * Transcrição completa gerada pelo servidor. Existe ao lado de `buildTranscriptText`, que monta
+   * a partir das mensagens já em memória: a tela costuma ter só a última página carregada, e
+   * exportar dali entregaria um recorte parcial com cara de histórico inteiro. Opcional porque
+   * nem todo backend expõe a rota — quem não tem continua usando o builder local.
+   */
+  exportTranscript?(conversationId: string): Promise<{ transcript: string; filename: string }>
 }
 
 /**
@@ -76,6 +187,13 @@ export interface ConversationSummary {
   waitingHuman: boolean
   unread: number
   currentState: string
+  /**
+   * Atributos que só o produto conhece e desenha (tipo de financiamento, carteira, campanha). É a
+   * contraparte de leitura do `filters` de `ListConversationsParams`: o pacote transporta e nunca
+   * interpreta. Sem isto, exibir um selo próprio na linha exigiria o host manter uma segunda
+   * consulta paralela à mesma listagem — a implementação duplicada que o pacote existe para evitar.
+   */
+  attributes?: Record<string, string | undefined>
 }
 
 export interface ConversationDocument {

package/src/settings/WhatsAppCreateTemplateForm.tsx

@@ -24,6 +24,7 @@ export interface WhatsAppCreateTemplateFormLabels {
   sectionDescription: string
   nameLabel: string
   nameHint: string
+  namePlaceholder: string
   categoryLabel: string
   languageLabel: string
   headerLabel: string
@@ -57,6 +58,7 @@ const DEFAULT_LABELS: WhatsAppCreateTemplateFormLabels = {
   sectionDescription: 'Envia um template para aprovação da Meta.',
   nameLabel: 'Nome do template',
   nameHint: 'Somente letras minúsculas, números e underscore.',
+  namePlaceholder: 'reengajamento_cliente',
   categoryLabel: 'Categoria',
   languageLabel: 'Idioma',
   headerLabel: 'Cabeçalho',
@@ -142,7 +144,7 @@ export function WhatsAppCreateTemplateForm({
             type="text"
             value={value.name}
             onChange={(e) => set('name', e.target.value.toLowerCase().replace(/[^a-z0-9_]/g, '_'))}
-            placeholder="reengajamento_cliente"
+            placeholder={labels.namePlaceholder}
             className="w-full border border-gray-200 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-100 rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-blue-400 focus:border-transparent transition-all"
             required
           />