@adatechnology/conversations-ui 0.1.0-rc.9 → 0.1.0

package/src/preview/createPreviewWebhookClient.ts

@@ -6,9 +6,14 @@
  * 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.
  *
- * ⚠️ Isto carrega o app secret de DESENVOLVIMENTO no bundle. Só existe para o docker local, e
- * `assertPreviewEnvironment` recusa rodar em produção — um segredo de dev vazado é irrelevante,
- * mas o hábito de embarcar segredo em frontend não é.
+ * ⚠️ 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 {
@@ -20,6 +25,7 @@ import {
   type InboundMediaType,
   type InteractiveReplyOption,
 } from '@adatechnology/meta-whatsapp-contracts/testing'
+import { createPreviewMediaUploader, type PreviewUploadedMedia } from './createPreviewMediaUploader'
 
 export type PreviewWebhookClient = {
   sendText(text: string): Promise<void>
@@ -27,6 +33,19 @@ export type PreviewWebhookClient = {
   sendListReply(reply: InteractiveReplyOption): Promise<void>
   sendAudio(mediaId: string): Promise<void>
   sendMedia(params: SendPreviewMediaParams): Promise<void>
+  /**
+   * Guarda um arquivo gravado e devolve o `mediaId` já prefixado, pronto para `sendMedia`.
+   *
+   * Existe no cliente, e não como prop de quem monta a tela, porque isto é exatamente o que ele já
+   * sabe fazer: falar com ESTE host usando ESTE segredo. Enquanto era responsabilidade do produto,
+   * o resultado prático foi um produto com microfone no simulador e outro sem — não por decisão,
+   * por esquecimento. Cliente montado, microfone na tela.
+   *
+   * Opcional porque o cliente-ponte só consegue oferecer isto quando sabe a rota de mídia (ou quando
+   * o host injeta a função): sem destino, gravar áudio seria falar para o vazio, e aí a tela
+   * corretamente não desenha o gravador.
+   */
+  uploadMedia?(file: File): Promise<PreviewUploadedMedia>
 }
 
 export type SendPreviewMediaParams = {
@@ -47,10 +66,25 @@ export type CreatePreviewWebhookClientParams = {
   readonly appSecret: string
   readonly from: string
   readonly phoneNumberId?: string
+  /**
+   * Rota que guarda o áudio gravado. Por padrão, `/v1/preview/media` na mesma origem do webhook.
+   *
+   * O padrão cobre o caso normal — as duas rotas são do mesmo servidor — e a prop existe para quem
+   * publica a API em outro host ou versiona o caminho.
+   */
+  readonly mediaUploadUrl?: string
   // Escape hatch para teste; em runtime real é sempre o fetch global.
   readonly fetchImplementation?: typeof fetch
 }
 
+/** Falha da rota de upload, separada da do webhook: os dois lados quebram por motivos diferentes. */
+export class PreviewMediaUploadRejectedError extends Error {
+  constructor(readonly status: number) {
+    super(`A rota de mídia do simulador recusou o upload (HTTP ${status}).`)
+    this.name = 'PreviewMediaUploadRejectedError'
+  }
+}
+
 export class PreviewInProductionError extends Error {
   constructor() {
     super('O preview de conversa carrega um app secret e não pode ser montado em produção.')
@@ -97,6 +131,53 @@ export async function signPreviewPayload(params: { rawBody: string; appSecret: s
 
 const signWithWebCrypto = signPreviewPayload
 
+export const DEFAULT_MEDIA_UPLOAD_PATH = '/v1/preview/media'
+
+/**
+ * Mesma origem do webhook: as duas rotas são do mesmo servidor no caso normal.
+ *
+ * Quando `webhookUrl` é relativa — que é o que sai de um `VITE_API_URL` vazio, com o front servido
+ * pela própria API — não há origem para resolver contra, e o caminho relativo já aponta para o
+ * lugar certo. `new URL` com base relativa lançaria, e o microfone morreria no `createClient`.
+ */
+export function defaultMediaUploadUrl(webhookUrl: string): string {
+  try {
+    return new URL(DEFAULT_MEDIA_UPLOAD_PATH, webhookUrl).toString()
+  } catch {
+    return DEFAULT_MEDIA_UPLOAD_PATH
+  }
+}
+
+/**
+ * O POST de mídia, sem a parte de assinatura — para os dois clientes usarem o mesmo caminho.
+ *
+ * O cliente-ponte autentica por sessão e o de webhook por HMAC; o que não muda é a rota, o formato
+ * do corpo e a leitura do `uploadId`. Duas cópias disso é como o prefixo de mídia divergiu antes.
+ */
+export function createPreviewMediaPoster(params: {
+  readonly url: string
+  readonly headers?: (mimeType: string) => Promise<Readonly<Record<string, string>>>
+  readonly fetchImplementation?: typeof fetch
+}): (file: File) => Promise<PreviewUploadedMedia> {
+  return createPreviewMediaUploader({
+    upload: async (request) => {
+      const performRequest = params.fetchImplementation ?? fetch
+      const extraHeaders = (await params.headers?.(request.mimeType)) ?? {}
+
+      const response = await performRequest(params.url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+        body: JSON.stringify(request),
+      })
+
+      if (!response.ok) throw new PreviewMediaUploadRejectedError(response.status)
+
+      const body = (await response.json()) as { data: { uploadId: string } }
+      return { uploadId: body.data.uploadId }
+    },
+  })
+}
+
 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
@@ -114,6 +195,20 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     if (!response.ok) throw new PreviewWebhookRejectedError(response.status)
   }
 
+  /**
+   * Assina o MIME, não o binário — mesmo contrato da rota.
+   *
+   * Passar megabytes de base64 pelo HMAC do navegador travaria a aba a cada nota de voz; o que a
+   * assinatura protege aqui é o acesso à rota, e o binário já tem teto de tamanho no servidor.
+   */
+  const uploadMedia = createPreviewMediaPoster({
+    url: params.mediaUploadUrl ?? defaultMediaUploadUrl(params.webhookUrl),
+    headers: async (mimeType) => ({
+      'x-preview-signature': await signWithWebCrypto({ rawBody: mimeType, appSecret: params.appSecret }),
+    }),
+    ...(params.fetchImplementation ? { fetchImplementation: params.fetchImplementation } : {}),
+  })
+
   const envelope = { from: params.from, phoneNumberId: params.phoneNumberId }
 
   return {
@@ -122,5 +217,6 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     sendListReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, listReply: reply })),
     sendAudio: (mediaId) => sendPayload(buildInboundAudioPayload({ ...envelope, mediaId })),
     sendMedia: (media) => sendPayload(buildInboundMediaPayload({ ...envelope, ...media })),
+    uploadMedia,
   }
 }

package/src/preview/index.ts

@@ -25,12 +25,33 @@ export type { CreateMockSSEProviderParams } from './createMockSSEProvider'
 
 export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES, PREVIEW_DOCUMENTS } from './previewFixtures'
 
+export {
+  ConversationSimulatorPanel,
+  DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS,
+  simulatorPanelLabelsOf,
+} from './ConversationSimulatorPanel'
+export type { ConversationSimulatorPanelProps, ConversationSimulatorPanelLabels } from './ConversationSimulatorPanel'
+
+export {
+  acceptsMediaKind,
+  mediaKindOf,
+  isConversationSimulatorClient,
+  toConversationSimulatorClient,
+  SIMULATOR_FILE_MEDIA_KINDS,
+} from './ConversationSimulatorClient'
+export type {
+  ConversationSimulatorClient,
+  SendSimulatorMediaParams,
+  SimulatorMediaKind,
+  ToSimulatorClientParams,
+} from './ConversationSimulatorClient'
+
 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 { AudioRecorderButton, DEFAULT_AUDIO_RECORDER_BUTTON_LABELS } from '../AudioRecorderButton'
+export type { AudioRecorderButtonProps, AudioRecorderButtonLabels } from '../AudioRecorderButton'
 
 export {
   createPreviewWebhookClient,
@@ -38,6 +59,9 @@ export {
   assertPreviewEnvironment,
   PreviewInProductionError,
   PreviewWebhookRejectedError,
+  PreviewMediaUploadRejectedError,
+  createPreviewMediaPoster,
+  DEFAULT_MEDIA_UPLOAD_PATH,
 } from './createPreviewWebhookClient'
 export type {
   PreviewWebhookClient,
@@ -45,6 +69,13 @@ export type {
   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'
@@ -52,3 +83,6 @@ export { createPreviewMediaResolver, previewFileUrl } from './previewMediaSource
 export { previewFileBase64 } from './previewMediaSource'
 export { MediaTypesPreview, MEDIA_TYPES_CONVERSATION_ID } from './MediaTypesPreview'
 export type { MediaTypesPreviewProps } from './MediaTypesPreview'
+
+export { createPreviewMediaUploader, PREVIEW_MEDIA_ID_PREFIX } from './createPreviewMediaUploader'
+export type { CreatePreviewMediaUploaderParams, PreviewMediaUploadRequest } from './createPreviewMediaUploader'

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,4 +1,4 @@
-import type { MessagePayload } from '../types'
+import type { MessagePayload, MessageTranscription } from '../types'
 import type { ConversationChannel } from '../conversationChannel'
 
 export interface ListConversationsParams {
@@ -31,14 +31,38 @@ export interface ListDocumentsParams {
   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. */
+  /**
+   * 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 {
@@ -110,6 +134,28 @@ export interface ConversationsApi {
    * 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 }>
 
   /**
@@ -134,6 +180,17 @@ export interface ConversationsApi {
    * 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>
 }
 
 /**

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

package/src/replyLatency.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * A distinção que estes testes protegem: janela de sessão e tempo sem resposta medem coisas
+ * diferentes, e reaproveitar `windowOf` para o SLA marcaria como atrasada toda conversa já
+ * respondida — o alerta apontaria para tudo, ou seja, para nada.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { REPLY_LATENCY, isReplyOverdue, replyLatencyOf } from './replyLatency'
+
+const NOW = new Date('2026-08-29T12:00:00Z').getTime()
+const hoursAgo = (hours: number) => new Date(NOW - hours * 60 * 60 * 1000).toISOString()
+
+describe('faixas de espera', () => {
+  it('até 6h está dentro do combinado', () => {
+    expect(replyLatencyOf({ lastDirection: 'inbound', lastInboundAt: hoursAgo(0), now: NOW })).toBe(
+      REPLY_LATENCY.WITHIN,
+    )
+    expect(replyLatencyOf({ lastDirection: 'inbound', lastInboundAt: hoursAgo(5.9), now: NOW })).toBe(
+      REPLY_LATENCY.WITHIN,
+    )
+  })
+
+  it('de 6h a 12h já passou do combinado', () => {
+    expect(replyLatencyOf({ lastDirection: 'inbound', lastInboundAt: hoursAgo(6), now: NOW })).toBe(REPLY_LATENCY.LATE)
+    expect(replyLatencyOf({ lastDirection: 'inbound', lastInboundAt: hoursAgo(11.9), now: NOW })).toBe(
+      REPLY_LATENCY.LATE,
+    )
+  })
+
+  it('acima de 12h é crítico — não se confunde com uma espera de 7h', () => {
+    expect(replyLatencyOf({ lastDirection: 'inbound', lastInboundAt: hoursAgo(12), now: NOW })).toBe(
+      REPLY_LATENCY.CRITICAL,
+    )
+    expect(replyLatencyOf({ lastDirection: 'inbound', lastInboundAt: hoursAgo(72), now: NOW })).toBe(
+      REPLY_LATENCY.CRITICAL,
+    )
+  })
+})
+
+describe('quando não há espera a mostrar', () => {
+  it('conversa já respondida não tem selo, por mais antiga que seja', () => {
+    // É aqui que o SLA se separa da janela de sessão: `windowOf` marcaria isto como crítico.
+    expect(replyLatencyOf({ lastDirection: 'outbound', lastInboundAt: hoursAgo(20), now: NOW })).toBeNull()
+  })
+
+  it('cliente que nunca escreveu não tem espera', () => {
+    expect(replyLatencyOf({ lastDirection: 'inbound', lastInboundAt: null, now: NOW })).toBeNull()
+  })
+
+  it('direção desconhecida não afirma espera', () => {
+    expect(replyLatencyOf({ lastInboundAt: hoursAgo(20), now: NOW })).toBeNull()
+  })
+
+  it('relógio adiantado não vira conversa crítica', () => {
+    expect(replyLatencyOf({ lastDirection: 'inbound', lastInboundAt: hoursAgo(-0.05), now: NOW })).toBe(
+      REPLY_LATENCY.WITHIN,
+    )
+  })
+})
+
+describe('o que merece alerta', () => {
+  it('só o que passou de 6h', () => {
+    expect(isReplyOverdue(REPLY_LATENCY.WITHIN)).toBe(false)
+    expect(isReplyOverdue(REPLY_LATENCY.LATE)).toBe(true)
+    expect(isReplyOverdue(REPLY_LATENCY.CRITICAL)).toBe(true)
+    expect(isReplyOverdue(null)).toBe(false)
+  })
+})

package/src/replyLatency.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Há quanto tempo o cliente espera resposta.
+ *
+ * Não confundir com `conversationWindow`: aquilo é a janela de sessão da plataforma (o que o canal
+ * ainda deixa enviar), isto é serviço (quanto o cliente esperou). Os dois divergem justamente no
+ * caso que interessa — respondida a conversa, o relógio do SLA para e o da janela continua correndo.
+ *
+ * A conta sai de dados que a listagem já traz: se a última mensagem foi do cliente, ninguém
+ * respondeu ainda e a espera conta desde ela. Se a última foi nossa, não há espera pendente.
+ */
+
+const HOUR_MS = 60 * 60 * 1000
+
+export const REPLY_LATENCY = {
+  /** Até 6h — dentro do combinado. */
+  WITHIN: 'within',
+  /** 6h a 12h — passou do combinado. */
+  LATE: 'late',
+  /** Acima de 12h. */
+  CRITICAL: 'critical',
+} as const
+export type ReplyLatency = (typeof REPLY_LATENCY)[keyof typeof REPLY_LATENCY]
+
+export const REPLY_LATENCY_LATE_HOURS = 6
+export const REPLY_LATENCY_CRITICAL_HOURS = 12
+
+export type ReplyLatencyParams = {
+  /** Direção da última mensagem. Ausente = desconhecida, e aí não se afirma espera. */
+  readonly lastDirection?: 'inbound' | 'outbound' | undefined
+  readonly lastInboundAt: string | null
+  readonly now: number
+}
+
+/**
+ * `null` quando não há espera a mostrar — conversa já respondida, ou cliente que nunca escreveu.
+ *
+ * Devolver uma faixa nesses casos encheria a lista de selos em conversa que não deve nada, e o
+ * alerta que aponta para todo lado não aponta para lugar nenhum.
+ */
+export function replyLatencyOf(params: ReplyLatencyParams): ReplyLatency | null {
+  if (params.lastDirection !== 'inbound') return null
+  if (!params.lastInboundAt) return null
+
+  const elapsedHours = (params.now - new Date(params.lastInboundAt).getTime()) / HOUR_MS
+  // Espera negativa é relógio fora de sincronia entre servidor e navegador, não conversa do futuro:
+  // tratar como recém-chegada evita um selo "crítico" nascido de alguns segundos de diferença.
+  if (elapsedHours < REPLY_LATENCY_LATE_HOURS) return REPLY_LATENCY.WITHIN
+  if (elapsedHours < REPLY_LATENCY_CRITICAL_HOURS) return REPLY_LATENCY.LATE
+  return REPLY_LATENCY.CRITICAL
+}
+
+/** Só o que passou do combinado merece alerta — é o corte que a lista usa para destacar. */
+export function isReplyOverdue(latency: ReplyLatency | null): boolean {
+  return latency === REPLY_LATENCY.LATE || latency === REPLY_LATENCY.CRITICAL
+}