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

package/src/MessageBubble.tsx

@@ -6,6 +6,7 @@ import { StatusTicks } from './StatusTicks'
 import { MediaRenderer, type ResolveMediaUrl } from './MediaRenderer'
 import { Lightbox } from './Lightbox'
 import { parseWhatsAppFormatting } from './lib/whatsapp-formatting'
+import { cn } from './lib/cn'
 import { formatTimestamp, formatDateTime } from './lib/format'
 
 export interface MessageBubbleProps {
@@ -17,6 +18,7 @@ export interface MessageBubbleProps {
   isSelected?: boolean
   onToggleSelect?: () => void
   onResolveMediaUrl?: ResolveMediaUrl
+  className?: string
 }
 
 // Hex arbitrários (não os tokens `whatsapp.*` do Tailwind) — o pacote fica autocontido,
@@ -37,7 +39,7 @@ const MEDIA_TYPES = new Set(['image', 'audio', 'video', 'document', 'sticker'])
 // tailwind.config do host expondo as cores `whatsapp.*` — ver Wallpaper.tsx e T6.2.
 export function MessageBubble({
   message, isMine, senderName, isFirstInGroup = true, isSelecting = false, isSelected = false, onToggleSelect,
-  onResolveMediaUrl,
+  onResolveMediaUrl, className,
 }: MessageBubbleProps) {
   const { bubble, selection } = useConversationLocales()
   const [lightboxSrc, setLightboxSrc] = useState<string | null>(null)
@@ -73,7 +75,14 @@ export function MessageBubble({
   )
 
   return (
-    <div className={`flex items-end gap-1.5 ${isMine ? 'justify-end' : 'justify-start'} group ${isFirstInGroup ? 'mt-2' : 'mt-0.5'}`}>
+    <div
+      className={cn(
+        'flex items-end gap-1.5 group',
+        isMine ? 'justify-end' : 'justify-start',
+        isFirstInGroup ? 'mt-2' : 'mt-0.5',
+        className,
+      )}
+    >
       {isMine && checkbox}
       <div
         onClick={isSelecting ? onToggleSelect : undefined}
@@ -92,6 +101,19 @@ export function MessageBubble({
           </div>
         )}
 
+        {/* Sinaliza, não censura nem esconde: cliente xingando é cliente irritado, e o atendente
+            precisa ler o que foi dito para responder. A etiqueta serve para achar o caso na thread
+            e para justificar escalar. */}
+        {message.moderation?.isOffensive && (
+          <div
+            className="mb-1 inline-flex items-center gap-1 rounded-full bg-amber-100 px-2 py-0.5 text-xs font-medium text-amber-800 dark:bg-amber-950/60 dark:text-amber-300"
+            title={message.moderation.terms.length > 0 ? message.moderation.terms.join(', ') : undefined}
+          >
+            <span aria-hidden>⚠️</span>
+            <span>{bubble.moderationFlagged}</span>
+          </div>
+        )}
+
         {isMedia ? (
           <MediaRenderer message={message} onLightbox={setLightboxSrc} onResolveUrl={onResolveMediaUrl} />
         ) : (

package/src/MessageComposer.tsx

@@ -1,5 +1,6 @@
 import { useState, useRef, useCallback, type KeyboardEvent, type ChangeEvent } from 'react'
 import type { ConversationsFeatures } from './types'
+import { cn } from './lib/cn'
 import { EmojiPicker } from './EmojiPicker'
 
 export interface MessageComposerProps {
@@ -12,6 +13,13 @@ export interface MessageComposerProps {
   maxLength?: number
   disabled?: boolean
   acceptedFileTypes?: string
+  className?: string
+  classNames?: Partial<MessageComposerClassNames>
+}
+
+export interface MessageComposerClassNames {
+  root: string
+  field: string
 }
 
 // Paridade com financiamento-imobiliario-bot/apps/web/src/pages/ConversationsPage.tsx:1490
@@ -32,6 +40,8 @@ export const MessageComposer = ({
   maxLength,
   disabled = false,
   acceptedFileTypes = DEFAULT_ACCEPTED_FILE_TYPES,
+  className,
+  classNames,
 }: MessageComposerProps) => {
   const [internalText, setInternalText] = useState('')
   const [showEmoji, setShowEmoji] = useState(false)
@@ -134,7 +144,10 @@ export const MessageComposer = ({
   const remaining = maxLength ? maxLength - text.length : null
 
   return (
-    <div>
+    /* A barra é a superfície (cinza, largura cheia, sem raio) e o campo dentro é que arredonda —
+       ordem do WhatsApp. Invertido, o pill arredondado ia até a borda da tela e os cantos
+       descobriam o fundo branco da página, que lia como defeito. */
+    <div className={cn('bg-[#f0f2f5] px-2 py-2', className)}>
       {attachments.length > 0 && (
         <div className="flex gap-2 px-1 pb-2 overflow-x-auto">
           {attachments.map((a, i) => (
@@ -152,7 +165,7 @@ export const MessageComposer = ({
         </div>
       )}
 
-      <div className="flex items-end gap-1.5 bg-[#f0f2f5] rounded-xl px-3 py-2">
+      <div className={cn('flex items-end gap-1.5 rounded-xl bg-white px-3 py-2', classNames?.field)}>
         {showEmojiButton && (
           <div className="relative flex-shrink-0">
             <button onClick={() => setShowEmoji(v => !v)} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 transition-colors" aria-label="Emoji">

package/src/Wallpaper.tsx

@@ -1,5 +1,7 @@
 import type { ReactNode } from 'react'
 
+import { cn } from './lib/cn'
+
 export interface ConversationWallpaperProps {
   children?: ReactNode
   className?: string
@@ -8,6 +10,6 @@ export interface ConversationWallpaperProps {
 // Requer o import de '@adatechnology/conversations-ui/styles.css' uma vez no host —
 // a classe `.cv-wallpaper` (e sua variante `.dark`) vive nesse stylesheet, não em CSS-in-JS,
 // para não depender da configuração de Tailwind do consumidor.
-export function ConversationWallpaper({ children, className = '' }: ConversationWallpaperProps) {
-  return <div className={`cv-wallpaper ${className}`.trim()}>{children}</div>
+export function ConversationWallpaper({ children, className }: ConversationWallpaperProps) {
+  return <div className={cn('cv-wallpaper', className)}>{children}</div>
 }

package/src/WindowExpiredNotice.tsx

@@ -0,0 +1,57 @@
+/**
+ * Aviso de janela de 24h expirada, no lugar do composer.
+ *
+ * Trocar o composer pelo aviso, em vez de deixar o campo lá e falhar no envio, é o ponto: fora da
+ * janela o WhatsApp recusa texto livre, e um campo habilitado promete algo que a plataforma não
+ * cumpre. O caminho que resta — template — fica visível na mesma altura da tela.
+ */
+
+import { CONVERSATION_WINDOW, type ConversationWindow } from './conversationWindow'
+import { cn } from './lib/cn'
+
+export interface WindowExpiredNoticeLabels {
+  title: string
+  description: string
+  sendTemplate: string
+}
+
+export const DEFAULT_WINDOW_EXPIRED_LABELS: WindowExpiredNoticeLabels = {
+  title: '⏰ Janela de 24h expirada — o WhatsApp não aceita mensagens livres.',
+  description: 'Envie uma mensagem de template para reabrir a conversa com o cliente.',
+  sendTemplate: '📨 Enviar Template (HSM)',
+}
+
+export interface WindowExpiredNoticeProps {
+  onSendTemplate?: () => void
+  disabled?: boolean
+  labels?: Partial<WindowExpiredNoticeLabels>
+  className?: string
+}
+
+export function WindowExpiredNotice({
+  onSendTemplate,
+  disabled = false,
+  labels: labelsOverride,
+  className,
+}: WindowExpiredNoticeProps) {
+  const labels = { ...DEFAULT_WINDOW_EXPIRED_LABELS, ...labelsOverride }
+
+  return (
+    <div role="status" className={cn('border-t bg-yellow-50 px-4 py-3 text-sm dark:bg-yellow-950', className)}>
+      <p className="font-medium text-yellow-900 dark:text-yellow-200">{labels.title}</p>
+      <p className="text-yellow-800 dark:text-yellow-300">{labels.description}</p>
+      {onSendTemplate ? (
+        <button type="button" onClick={onSendTemplate} disabled={disabled} className="cv-header-action mt-2">
+          {labels.sendTemplate}
+        </button>
+      ) : null}
+    </div>
+  )
+}
+
+/**
+ * Só a faixa `expired` bloqueia: 21-24h ainda aceita texto livre e merece alerta, não impedimento.
+ */
+export function isWindowBlocking(window: ConversationWindow): boolean {
+  return window === CONVERSATION_WINDOW.EXPIRED
+}

package/src/conversationChannel.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'bun:test'
+import { CONVERSATION_CHANNEL, CHANNEL_FILTER_ALL, channelFiltersFor } from './conversationChannel'
+
+describe('channelFiltersFor', () => {
+  // O ponto do helper: a barra oferece só o que existe. Oferecer Instagram numa conta que só tem
+  // WhatsApp promete um recorte que nunca traz resultado.
+  it('lista apenas os canais presentes, com Todos na frente', () => {
+    const options = channelFiltersFor([
+      { channel: CONVERSATION_CHANNEL.WHATSAPP },
+      { channel: CONVERSATION_CHANNEL.INSTAGRAM },
+      { channel: CONVERSATION_CHANNEL.WHATSAPP },
+    ])
+
+    expect(options.map((option) => option.value)).toEqual([
+      CHANNEL_FILTER_ALL,
+      CONVERSATION_CHANNEL.WHATSAPP,
+      CONVERSATION_CHANNEL.INSTAGRAM,
+    ])
+  })
+
+  it('não oferece filtro quando há um canal só', () => {
+    expect(channelFiltersFor([{ channel: CONVERSATION_CHANNEL.WHATSAPP }, {}])).toEqual([])
+  })
+
+  it('não oferece filtro para lista vazia', () => {
+    expect(channelFiltersFor([])).toEqual([])
+  })
+
+  // Conversa sem canal é WhatsApp por compatibilidade — não pode virar uma quinta opção fantasma.
+  it('trata ausência de canal como whatsapp', () => {
+    const options = channelFiltersFor([{}, { channel: CONVERSATION_CHANNEL.WEBCHAT }])
+
+    expect(options.map((option) => option.value)).toEqual([
+      CHANNEL_FILTER_ALL,
+      CONVERSATION_CHANNEL.WHATSAPP,
+      CONVERSATION_CHANNEL.WEBCHAT,
+    ])
+  })
+
+  // Ordem do catálogo: se dependesse da ordem de chegada, a barra se reorganizaria a cada refetch.
+  it('mantém ordem estável independente da ordem da lista', () => {
+    const first = channelFiltersFor([
+      { channel: CONVERSATION_CHANNEL.WEBCHAT },
+      { channel: CONVERSATION_CHANNEL.WHATSAPP },
+    ])
+    const second = channelFiltersFor([
+      { channel: CONVERSATION_CHANNEL.WHATSAPP },
+      { channel: CONVERSATION_CHANNEL.WEBCHAT },
+    ])
+
+    expect(first).toEqual(second)
+  })
+})

package/src/conversationChannel.ts

@@ -0,0 +1,146 @@
+/**
+ * Canal de origem da conversa e o que cada um permite.
+ *
+ * Existe porque as regras que a inbox precisa respeitar não são do WhatsApp, são **de cada canal**:
+ * a janela de sessão, o jeito de reabrir a conversa e o formato do identificador do contato mudam
+ * entre WhatsApp, Messenger, Instagram e chat de site. Tratar a regra do WhatsApp como universal
+ * faria a UI bloquear o composer num chat de site, onde janela nenhuma existe.
+ *
+ * `whatsapp` é o padrão em todo lugar: instalações que ainda não informam canal continuam
+ * funcionando exatamente como antes.
+ */
+
+import { formatPhone, phoneCountryFlag } from './lib/phone'
+
+export const CONVERSATION_CHANNEL = {
+  WHATSAPP: 'whatsapp',
+  MESSENGER: 'messenger',
+  INSTAGRAM: 'instagram',
+  WEBCHAT: 'webchat',
+} as const
+export type ConversationChannel = (typeof CONVERSATION_CHANNEL)[keyof typeof CONVERSATION_CHANNEL]
+
+export const DEFAULT_CONVERSATION_CHANNEL: ConversationChannel = CONVERSATION_CHANNEL.WHATSAPP
+
+/** Como o canal reabre uma conversa fora da janela de sessão. */
+export const REOPEN_MECHANISM = {
+  TEMPLATE: 'template',
+  TAG: 'tag',
+  NONE: 'none',
+} as const
+export type ReopenMechanism = (typeof REOPEN_MECHANISM)[keyof typeof REOPEN_MECHANISM]
+
+/** Natureza do identificador do contato — decide como exibi-lo. */
+export const HANDLE_KIND = {
+  PHONE: 'phone',
+  USERNAME: 'username',
+  SESSION: 'session',
+} as const
+export type HandleKind = (typeof HANDLE_KIND)[keyof typeof HANDLE_KIND]
+
+export type ChannelCapabilities = {
+  readonly label: string
+  readonly icon: string
+  readonly hasSessionWindow: boolean
+  readonly windowHours: number
+  readonly reopenMechanism: ReopenMechanism
+  readonly handleKind: HandleKind
+}
+
+export const CHANNEL_CAPABILITIES: Readonly<Record<ConversationChannel, ChannelCapabilities>> = {
+  [CONVERSATION_CHANNEL.WHATSAPP]: {
+    label: 'WhatsApp',
+    icon: '💬',
+    hasSessionWindow: true,
+    windowHours: 24,
+    reopenMechanism: REOPEN_MECHANISM.TEMPLATE,
+    handleKind: HANDLE_KIND.PHONE,
+  },
+  [CONVERSATION_CHANNEL.MESSENGER]: {
+    // Messenger também tem 24h, mas reabre com message tag — não com template aprovado.
+    label: 'Messenger',
+    icon: '📨',
+    hasSessionWindow: true,
+    windowHours: 24,
+    reopenMechanism: REOPEN_MECHANISM.TAG,
+    handleKind: HANDLE_KIND.USERNAME,
+  },
+  [CONVERSATION_CHANNEL.INSTAGRAM]: {
+    label: 'Instagram',
+    icon: '📷',
+    hasSessionWindow: true,
+    windowHours: 24,
+    reopenMechanism: REOPEN_MECHANISM.TAG,
+    handleKind: HANDLE_KIND.USERNAME,
+  },
+  [CONVERSATION_CHANNEL.WEBCHAT]: {
+    // Chat próprio: sem intermediário, sem janela. Bloquear o composer aqui seria inventar limite.
+    label: 'Chat do site',
+    icon: '🌐',
+    hasSessionWindow: false,
+    windowHours: 0,
+    reopenMechanism: REOPEN_MECHANISM.NONE,
+    handleKind: HANDLE_KIND.SESSION,
+  },
+}
+
+export function capabilitiesOf(channel: ConversationChannel | undefined): ChannelCapabilities {
+  return CHANNEL_CAPABILITIES[channel ?? DEFAULT_CONVERSATION_CHANNEL]
+}
+
+export const CHANNEL_FILTER_ALL = 'all'
+export type ChannelFilter = ConversationChannel | typeof CHANNEL_FILTER_ALL
+
+export type ChannelFilterOption = {
+  readonly value: ChannelFilter
+  readonly label: string
+}
+
+/**
+ * Opções derivadas do que existe na lista, não do catálogo inteiro: oferecer Instagram numa conta
+ * que só tem WhatsApp promete um recorte que nunca traz resultado.
+ *
+ * Devolve vazio com menos de dois canais — um filtro de opção única não filtra nada, e a barra só
+ * ocuparia espaço. O host usa isso para esconder a seção.
+ */
+export function channelFiltersFor(
+  conversations: readonly { readonly channel?: ConversationChannel | undefined }[],
+): ChannelFilterOption[] {
+  const present = new Set<ConversationChannel>(
+    conversations.map((conversation) => conversation.channel ?? DEFAULT_CONVERSATION_CHANNEL),
+  )
+
+  if (present.size < 2) return []
+
+  // Ordem do catálogo, não de chegada: a barra não pode reordenar sozinha a cada refetch.
+  const ordered = (Object.keys(CHANNEL_CAPABILITIES) as ConversationChannel[]).filter((channel) => present.has(channel))
+
+  return [
+    { value: CHANNEL_FILTER_ALL, label: 'Todos' },
+    ...ordered.map((channel) => ({ value: channel, label: CHANNEL_CAPABILITIES[channel].label })),
+  ]
+}
+
+export type FormatContactHandleParams = {
+  readonly handle: string
+  readonly channel?: ConversationChannel | undefined
+}
+
+/**
+ * Exibição do identificador conforme a natureza dele. Formatar tudo como telefone — o que a UI
+ * fazia — transforma um `@perfil` do Instagram em dígitos sem sentido.
+ */
+export function formatContactHandle(params: FormatContactHandleParams): string {
+  const { handleKind } = capabilitiesOf(params.channel)
+
+  if (handleKind === HANDLE_KIND.PHONE) return formatPhone(params.handle)
+  if (handleKind === HANDLE_KIND.USERNAME) return params.handle.startsWith('@') ? params.handle : `@${params.handle}`
+
+  // Sessão de chat de site é um id opaco: mostrar o hash inteiro não ajuda ninguém.
+  return `Visitante ${params.handle.slice(-6)}`
+}
+
+/** Bandeira só faz sentido quando o identificador é telefone. */
+export function contactFlag(params: FormatContactHandleParams): string {
+  return capabilitiesOf(params.channel).handleKind === HANDLE_KIND.PHONE ? phoneCountryFlag(params.handle) : ''
+}

package/src/conversationTranscript.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'bun:test'
+import { buildTranscriptFilename, buildTranscriptText } from './conversationTranscript'
+import type { MessagePayload } from './types'
+
+const NUMBER = '5511988887777'
+
+function message(partial: Partial<MessagePayload>): MessagePayload {
+  return {
+    id: 'm1',
+    type: 'text',
+    direction: 'inbound',
+    sender: 'customer',
+    timestamp: '2026-07-27T12:00:00.000Z',
+    ...partial,
+  }
+}
+
+describe('buildTranscriptText', () => {
+  it('escreve cabeçalho e uma linha por mensagem', () => {
+    const text = buildTranscriptText({
+      messages: [
+        message({ id: 'm1', content: 'oi' }),
+        message({ id: 'm2', content: 'Olá!', direction: 'outbound', sender: 'bot' }),
+      ],
+      whatsappNumber: NUMBER,
+      clientName: 'Marina',
+    })
+
+    expect(text).toContain('Conversa: Marina')
+    expect(text).toContain(`Número: ${NUMBER}`)
+    expect(text).toContain('Mensagens: 2')
+    expect(text).toContain('Cliente: oi')
+    expect(text).toContain('Bot: Olá!')
+  })
+
+  // Sem isto a linha sairia vazia e o histórico esconderia que houve um anexo ali.
+  it('marca o tipo quando a mensagem não tem texto', () => {
+    const text = buildTranscriptText({ messages: [message({ type: 'audio' })], whatsappNumber: NUMBER })
+
+    expect(text).toContain('<audio>')
+  })
+
+  it('usa o nome do atendente quando existe, em vez do papel genérico', () => {
+    const text = buildTranscriptText({
+      messages: [message({ direction: 'outbound', sender: 'agent', agentName: 'Ana', content: 'já separei' })],
+      whatsappNumber: NUMBER,
+    })
+
+    expect(text).toContain('Ana: já separei')
+  })
+
+  it('cai no número quando não há nome do cliente', () => {
+    const text = buildTranscriptText({ messages: [], whatsappNumber: NUMBER })
+
+    expect(text).toContain(`Conversa: ${NUMBER}`)
+  })
+})
+
+describe('buildTranscriptFilename', () => {
+  it('inclui número e data', () => {
+    expect(buildTranscriptFilename(NUMBER, new Date('2026-07-27T23:00:00.000Z'))).toBe(
+      `conversa-${NUMBER}-2026-07-27.txt`,
+    )
+  })
+})

package/src/conversationTranscript.ts

@@ -0,0 +1,64 @@
+/**
+ * Serialização do transcript para download. Fica no pacote porque o formato de um histórico de
+ * WhatsApp legível não é regra de negócio de ninguém — e porque o host que já tem as mensagens em
+ * tela não deveria precisar de rota nova só para salvar um arquivo.
+ *
+ * Funções puras, separadas do disparo do download: é o que permite testá-las sem DOM.
+ */
+
+import type { MessagePayload } from './types'
+
+const SENDER_LABEL: Record<MessagePayload['sender'], string> = {
+  customer: 'Cliente',
+  bot: 'Bot',
+  agent: 'Atendente',
+}
+
+export type BuildTranscriptTextParams = {
+  readonly messages: readonly MessagePayload[]
+  readonly whatsappNumber: string
+  readonly clientName?: string | undefined
+}
+
+/**
+ * Formato próximo ao export nativo do WhatsApp (`[data hora] Autor: texto`), que é o que pessoas e
+ * ferramentas de suporte já sabem ler.
+ */
+export function buildTranscriptText(params: BuildTranscriptTextParams): string {
+  const header = [
+    `Conversa: ${params.clientName ?? params.whatsappNumber}`,
+    `Número: ${params.whatsappNumber}`,
+    `Mensagens: ${params.messages.length}`,
+    '',
+  ]
+
+  const lines = params.messages.map((message) => {
+    const stamp = new Date(message.timestamp).toLocaleString('pt-BR')
+    const author = message.agentName ?? SENDER_LABEL[message.sender]
+    // Mídia sem legenda não tem texto nenhum; marcar o tipo evita uma linha vazia sem explicação.
+    const body = message.content ?? message.caption ?? `<${message.type}>`
+    return `[${stamp}] ${author}: ${body}`
+  })
+
+  return [...header, ...lines].join('\n')
+}
+
+export function buildTranscriptFilename(whatsappNumber: string, generatedAt: Date): string {
+  const stamp = generatedAt.toISOString().slice(0, 10)
+  return `conversa-${whatsappNumber}-${stamp}.txt`
+}
+
+/**
+ * Dispara o download no navegador. `revokeObjectURL` no fim não é higiene opcional: sem ele cada
+ * export retém o blob inteiro em memória até a aba fechar.
+ */
+export function downloadTextFile(filename: string, content: string): void {
+  const blob = new Blob([content], { type: 'text/plain;charset=utf-8' })
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+
+  anchor.href = url
+  anchor.download = filename
+  anchor.click()
+  URL.revokeObjectURL(url)
+}

package/src/conversationWindow.test.ts

@@ -0,0 +1,90 @@
+/**
+ * A classificação de janela decide se o atendente pode mandar texto livre. Errar a fronteira não
+ * quebra a tela — faz o WhatsApp recusar o envio depois, longe da causa.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { CONVERSATION_WINDOW, formatStalledFor, windowOf } from './conversationWindow'
+import { CONVERSATION_CHANNEL, contactFlag, formatContactHandle } from './conversationChannel'
+
+const NOW = new Date('2026-07-27T12:00:00.000Z').getTime()
+const HOUR = 60 * 60 * 1000
+
+function hoursAgo(hours: number): string {
+  return new Date(NOW - hours * HOUR).toISOString()
+}
+
+describe('windowOf', () => {
+  it('classifica por faixa de horas desde o último contato do cliente', () => {
+    expect(windowOf({ lastInboundAt: hoursAgo(0), now: NOW })).toBe(CONVERSATION_WINDOW.FRESH)
+    expect(windowOf({ lastInboundAt: hoursAgo(11.9), now: NOW })).toBe(CONVERSATION_WINDOW.FRESH)
+    expect(windowOf({ lastInboundAt: hoursAgo(15), now: NOW })).toBe(CONVERSATION_WINDOW.WARNING)
+    expect(windowOf({ lastInboundAt: hoursAgo(22), now: NOW })).toBe(CONVERSATION_WINDOW.CRITICAL)
+    expect(windowOf({ lastInboundAt: hoursAgo(30), now: NOW })).toBe(CONVERSATION_WINDOW.EXPIRED)
+  })
+
+  // As fronteiras são exatamente onde o erro custa caro: 24h em ponto já é recusa da Meta.
+  it('trata as fronteiras como início da faixa seguinte', () => {
+    expect(windowOf({ lastInboundAt: hoursAgo(12), now: NOW })).toBe(CONVERSATION_WINDOW.WARNING)
+    expect(windowOf({ lastInboundAt: hoursAgo(21), now: NOW })).toBe(CONVERSATION_WINDOW.CRITICAL)
+    expect(windowOf({ lastInboundAt: hoursAgo(24), now: NOW })).toBe(CONVERSATION_WINDOW.EXPIRED)
+  })
+
+  // Sem inbound não há janela aberta; classificar como expirada evita prometer texto livre.
+  it('considera expirada quando o cliente nunca escreveu', () => {
+    expect(windowOf({ lastInboundAt: null, now: NOW })).toBe(CONVERSATION_WINDOW.EXPIRED)
+  })
+
+  // O defeito que isto tranca: aplicar a regra do WhatsApp ao chat de site bloquearia o composer
+  // num canal onde nada expira.
+  it('nunca expira em canal sem janela de sessão', () => {
+    expect(windowOf({ lastInboundAt: hoursAgo(720), now: NOW, channel: CONVERSATION_CHANNEL.WEBCHAT })).toBe(
+      CONVERSATION_WINDOW.FRESH,
+    )
+    expect(windowOf({ lastInboundAt: null, now: NOW, channel: CONVERSATION_CHANNEL.WEBCHAT })).toBe(
+      CONVERSATION_WINDOW.FRESH,
+    )
+  })
+
+  it('mantém a regra do WhatsApp quando o canal não é informado', () => {
+    expect(windowOf({ lastInboundAt: hoursAgo(30), now: NOW })).toBe(
+      windowOf({ lastInboundAt: hoursAgo(30), now: NOW, channel: CONVERSATION_CHANNEL.WHATSAPP }),
+    )
+  })
+})
+
+describe('formatContactHandle', () => {
+  it('formata telefone no WhatsApp e arroba nas redes', () => {
+    expect(formatContactHandle({ handle: '5511988887777', channel: CONVERSATION_CHANNEL.WHATSAPP })).toBe(
+      '+55 (11) 98888-7777',
+    )
+    expect(formatContactHandle({ handle: 'marina.alves', channel: CONVERSATION_CHANNEL.INSTAGRAM })).toBe(
+      '@marina.alves',
+    )
+    expect(formatContactHandle({ handle: '@ja.tem', channel: CONVERSATION_CHANNEL.INSTAGRAM })).toBe('@ja.tem')
+  })
+
+  it('encurta a sessão anônima do chat de site', () => {
+    expect(formatContactHandle({ handle: 'sess_9f2a7c41b8', channel: CONVERSATION_CHANNEL.WEBCHAT })).toBe(
+      'Visitante 7c41b8',
+    )
+  })
+
+  // Bandeira em @perfil não significaria nada: o identificador não carrega país.
+  it('só devolve bandeira quando o identificador é telefone', () => {
+    expect(contactFlag({ handle: '5511988887777' })).toBe('🇧🇷')
+    expect(contactFlag({ handle: 'marina.alves', channel: CONVERSATION_CHANNEL.INSTAGRAM })).toBe('')
+  })
+})
+
+describe('formatStalledFor', () => {
+  it('formata dias, horas e minutos', () => {
+    expect(formatStalledFor(hoursAgo(5 * 24 + 6.2), NOW)).toBe('5d 6h:12m')
+    expect(formatStalledFor(hoursAgo(3.5), NOW)).toBe('3h:30m')
+    expect(formatStalledFor(hoursAgo(0.25), NOW)).toBe('15m')
+  })
+
+  it('não devolve tempo negativo para carimbo no futuro', () => {
+    expect(formatStalledFor(new Date(NOW + HOUR).toISOString(), NOW)).toBe('0m')
+  })
+})