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

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

@@ -0,0 +1,61 @@
+/**
+ * O teste que importa aqui é o do prefixo: ele é duplicado entre este pacote (UI) e o
+ * meta-whatsapp-module (backend), e divergir significa o simulador gerar um id que o servidor não
+ * reconhece — o áudio chega, o backend busca na Meta, volta 404 e ninguém entende por quê.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { PREVIEW_MEDIA_ID_PREFIX as CONTRACT_PREFIX } from '@adatechnology/meta-whatsapp-contracts'
+
+import { createPreviewMediaUploader, PREVIEW_MEDIA_ID_PREFIX } from './createPreviewMediaUploader'
+
+describe('createPreviewMediaUploader', () => {
+  it('reexporta o prefixo do contrato, sem cópia própria', () => {
+    expect(PREVIEW_MEDIA_ID_PREFIX).toBe(CONTRACT_PREFIX)
+  })
+
+  it('devolve o id prefixado com o uploadId da rota', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'chave/do/objeto' }) })
+
+    const result = await upload(new File([new Uint8Array([1, 2, 3])], 'nota.ogg', { type: 'audio/ogg' }))
+
+    expect(result.mediaId).toBe(`${CONTRACT_PREFIX}chave/do/objeto`)
+    expect(result.mimeType).toBe('audio/ogg')
+    expect(result.filename).toBe('nota.ogg')
+  })
+
+  it('manda o binário em base64 para a rota', async () => {
+    let recebido: string | undefined
+    const upload = createPreviewMediaUploader({
+      upload: async (request) => {
+        recebido = request.base64
+        return { uploadId: 'k' }
+      },
+    })
+
+    await upload(new File([new TextEncoder().encode('audio')], 'a.ogg', { type: 'audio/ogg' }))
+
+    expect(atob(recebido!)).toBe('audio')
+  })
+
+  // Gravador entrega áudio sem nome, e navegador antigo entrega sem mime.
+  it('preenche nome e mime quando o arquivo vem sem eles', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'k' }) })
+
+    const result = await upload(new File([new Uint8Array([1])], '', { type: '' }))
+
+    expect(result.mimeType).toBe('audio/ogg')
+    expect(result.filename).toBe('audio.ogg')
+  })
+
+  /**
+   * Espalhar o array de bytes como argumentos estoura a pilha em arquivo grande — o erro que só
+   * aparece na primeira gravação de verdade, nunca no clipe curto do teste.
+   */
+  it('converte arquivo grande sem estourar a pilha', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'k' }) })
+    const grande = new File([new Uint8Array(300_000)], 'longo.ogg', { type: 'audio/ogg' })
+
+    expect((await upload(grande)).mediaId).toContain(CONTRACT_PREFIX)
+  })
+})

package/src/providers/ConversationsProvider.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext, type ReactNode } from 'react'
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
 import type { ConversationsApi, SSEProvider } from './types'
 
 interface ConversationsContextValue {
@@ -17,11 +17,13 @@ export function ConversationsProvider({
   sse: SSEProvider
   children: ReactNode
 }) {
-  return (
-    <ConversationsContext.Provider value={{ api, sse }}>
-      {children}
-    </ConversationsContext.Provider>
-  )
+  // Objeto novo a cada render fazia todo efeito que depende do contexto reexecutar junto — o do
+  // `useConversationRealtime` fecha e reabre o SSE da conversa, e cada reabertura pede um ticket
+  // novo. Uma tela que renderiza em rajada saturava as 6 conexões do navegador com requisições
+  // pendentes que nunca chegavam a servir para nada.
+  const value = useMemo(() => ({ api, sse }), [api, sse])
+
+  return <ConversationsContext.Provider value={value}>{children}</ConversationsContext.Provider>
 }
 
 export function useConversations(): ConversationsContextValue | null {

package/src/providers/types.ts

@@ -1,28 +1,196 @@
-import type { MessagePayload } from '../types'
+import type { MessagePayload, MessageTranscription } 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.
+   *
+   * Seleção múltipla viaja como lista separada por vírgula em vez de virar `string[]`: mudar o
+   * tipo quebraria em compile-time toda implementação de host que já repassa este campo adiante,
+   * e o ganho seria nenhum — quem recebe faz `split(',')`.
+   */
+  source?: string
+  /** Categoria do arquivo (`document`, `image`, `audio`, `video`…), mesma convenção de lista. */
+  fileCategory?: string
+  /** Recorte por data de recebimento, em `YYYY-MM-DD`. */
+  startDate?: string
+  endDate?: string
+  sortDirection?: 'asc' | 'desc'
+  /** Coluna ordenada. Ausente, o host ordena pela data — é o padrão de toda listagem de arquivo. */
+  sortField?: string
+  /**
+   * Filtros que só existem no produto (`clientId`, `unidade`…). O pacote não os interpreta: passa
+   * adiante o que o host injetou pelo slot de filtros. É a porta que evita um fork da tela por
+   * causa de um `<select>`.
+   */
+  extra?: Readonly<Record<string, string | number>>
+}
+
+/** Arquivo na biblioteca da empresa: o mesmo da conversa, mais de qual conversa veio. */
+export interface CompanyDocument extends ConversationDocument {
+  conversationId: string
+  /**
+   * Nome de quem enviou, quando o host o conhece. Opcional porque a biblioteca sempre tem o
+   * telefone e nem todo produto tem cadastro por trás dele — ausente, a coluna cai para o número.
+   */
+  contactName?: string | null
+}
+
+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>
+  /**
+   * Remove um arquivo da biblioteca. **Opcional por capacidade:** apagar anexo trocado com o
+   * cliente é decisão de retenção do produto — instalação que precisa guardar tudo por obrigação
+   * legal não implementa, e a tela simplesmente não desenha a lixeira.
+   */
+  deleteDocument?(uploadId: string): Promise<void>
+  /**
+   * Zip de arquivos avulsos da biblioteca, sem conversa de origem única — irmão do
+   * `downloadDocumentsArchive`, que é por conversa. Ausente, a seleção em lote não oferece o botão.
+   */
+  downloadDocumentsArchiveByIds?(uploadIds: readonly string[]): Promise<Blob>
+  /**
+   * Envia um arquivo avulso direto pra biblioteca, fora do fluxo de uma conversa. **Opcional por
+   * capacidade:** cada host tem seu próprio contrato de upload (base64, multipart, presigned URL) —
+   * o pacote não escolhe um formato de payload, só entrega o `File` do input e deixa o host montar
+   * a chamada do jeito que seu backend espera. Ausente, a tela de biblioteca não desenha o botão de
+   * enviar, em vez de oferecer uma ação que sempre falha.
+   *
+   * `extra` é o mesmo vocabulário livre do produto que já viaja em `renderFilters` — cliente,
+   * unidade, campanha — pra associar o arquivo enviado ao contexto que a tela estava filtrando.
+   */
+  uploadDocument?(file: File, extra?: Readonly<Record<string, string | number>>): Promise<ConversationDocument>
   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 }>
+
+  /**
+   * Transcreve o áudio de uma mensagem e devolve o resultado.
+   *
+   * **Opcional por capacidade.** Um host em modo automático transcreve na ingestão e não expõe rota
+   * nenhuma; um host sem engine configurado não transcreve de jeito algum. Nos dois casos o balão
+   * simplesmente não desenha o botão, em vez de oferecer uma ação que estoura no clique.
+   *
+   * `messageId` e não `conversationId`: transcrição é por áudio, e uma conversa tem vários.
+   */
+  transcribeAudio?(messageId: string): Promise<MessageTranscription>
 }
 
 /**
@@ -76,6 +244,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/quickReply.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Guarda a interpolação das mensagens rápidas.
+ *
+ * O caso que decide o desenho: variável ausente. Deixar `{{nome}}` no texto significa o atendente
+ * mandar "Olá {{nome}}!" para o cliente — pior que a saudação sem nome.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { applyQuickReplyVariables, resolveQuickReply } from './MessageComposer'
+
+describe('applyQuickReplyVariables', () => {
+  it('troca a variável pelo valor', () => {
+    expect(applyQuickReplyVariables('Olá {{nome}}!', { nome: 'Marina' })).toBe('Olá Marina!')
+  })
+
+  it('aceita espaço dentro das chaves', () => {
+    expect(applyQuickReplyVariables('Olá {{ nome }}!', { nome: 'Rita' })).toBe('Olá Rita!')
+  })
+
+  it('troca todas as ocorrências', () => {
+    expect(applyQuickReplyVariables('{{nome}}, confirma? Obrigado, {{nome}}.', { nome: 'Ana' })).toBe(
+      'Ana, confirma? Obrigado, Ana.',
+    )
+  })
+
+  // Nunca vaza o literal para o cliente.
+  it('apaga a variável que não foi passada', () => {
+    expect(applyQuickReplyVariables('Olá {{nome}}!', {})).toBe('Olá !')
+    expect(applyQuickReplyVariables('Olá {{nome}}!')).toBe('Olá !')
+  })
+
+  it('não mexe em texto sem variável', () => {
+    expect(applyQuickReplyVariables('Bom dia!', { nome: 'X' })).toBe('Bom dia!')
+  })
+})
+
+describe('resolveQuickReply', () => {
+  it('interpola quando o texto é string', () => {
+    const resolvido = resolveQuickReply({ key: 'g', label: '👋', text: 'Olá {{nome}}!' }, { nome: 'Rita' })
+
+    expect(resolvido).toBe('Olá Rita!')
+  })
+
+  // A função existe para o que a string não resolve: escolher copy por produto, pluralizar, formatar.
+  it('chama a função com as variáveis', () => {
+    const resolvido = resolveQuickReply(
+      { key: 's', label: '📋', text: (variables) => `Status de ${variables['produto'] ?? 'seu pedido'}` },
+      { produto: 'financiamento' },
+    )
+
+    expect(resolvido).toBe('Status de financiamento')
+  })
+
+  it('função sem variáveis não quebra', () => {
+    expect(resolveQuickReply({ key: 'c', label: '📞', text: () => 'Posso ligar?' })).toBe('Posso ligar?')
+  })
+})