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

package/src/hooks/useScrollToLatestMessage.ts

@@ -0,0 +1,127 @@
+import { useCallback, useLayoutEffect, useRef, useState, type RefObject, type UIEvent } from 'react'
+
+/**
+ * Mantém a conversa no fim, como todo mensageiro.
+ *
+ * Abrir uma conversa no topo do histórico é errado por um motivo simples: o que interessa ao
+ * atendente é a última mensagem, e ele teria que rolar por semanas de conversa para chegar nela.
+ *
+ * Existe no pacote, e não em cada host, porque a regra tem duas sutilezas que se descobre só
+ * errando — o salto instantâneo na troca de conversa e o respeito a quem rolou para trás — e
+ * reimplementá-las em cada inbox garante que uma delas fique de fora.
+ */
+
+/**
+ * Distância do fim, em pixels, dentro da qual ainda consideramos o operador "acompanhando".
+ *
+ * Não é zero porque o navegador arredonda `scrollTop` fracionário em telas com zoom ou densidade
+ * alta: exigir o fim exato faria o painel achar que o operador rolou para trás sem ele ter tocado
+ * em nada, e a próxima mensagem não apareceria.
+ */
+const NEAR_BOTTOM_THRESHOLD_PX = 120
+
+/**
+ * Toda rolagem aqui é `'auto'` — nunca `'smooth'`.
+ *
+ * Tentamos suave para mensagem nova e medimos: em ambiente onde a rolagem suave está desligada, o
+ * `scrollTo({ behavior: 'smooth' })` **não faz nada e não avisa** — a mensagem nova simplesmente não
+ * entra na vista. E não dá para detectar isso pelo `prefers-reduced-motion`: no navegador em que
+ * reproduzimos, a media query respondia `false` e o smooth continuava sendo no-op.
+ *
+ * Trocar uma animação cosmética por garantia de que o operador vê a mensagem é barato: seguir uma
+ * mensagem nova salta a altura de uma bolha, que é quase imperceptível de qualquer forma.
+ */
+const SCROLL_BEHAVIOR: ScrollBehavior = 'auto'
+
+export type UseScrollToLatestMessageParams = {
+  /** Troca de conversa. Muda ⇒ salto instantâneo para o fim. */
+  readonly conversationId: string | undefined
+  /** Quantidade de mensagens carregadas. Cresce ⇒ acompanha o fim, se o operador estiver lá. */
+  readonly messageCount: number
+}
+
+export type UseScrollToLatestMessageResult = {
+  /** Vai no elemento que rola — tipicamente o `ConversationWallpaper`. */
+  readonly containerRef: RefObject<HTMLDivElement | null>
+  /** Ligue no `onScroll` do mesmo elemento: é o que detecta o operador lendo o histórico. */
+  readonly handleScroll: (event: UIEvent<HTMLDivElement>) => void
+  /** `true` quando o operador rolou para trás — serve a um botão "ir para a última". */
+  readonly isAwayFromBottom: boolean
+  readonly scrollToBottom: (behavior?: ScrollBehavior) => void
+}
+
+export function useScrollToLatestMessage({
+  conversationId,
+  messageCount,
+}: UseScrollToLatestMessageParams): UseScrollToLatestMessageResult {
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const [isAwayFromBottom, setIsAwayFromBottom] = useState(false)
+
+  /**
+   * Espelha `isAwayFromBottom` para o efeito de mensagens novas ler o valor atual sem depender dele.
+   *
+   * Se o efeito dependesse do estado, cada rolagem do operador o re-disparava e o puxava de volta
+   * para o fim — exatamente o que a checagem existe para evitar.
+   */
+  const isAwayFromBottomRef = useRef(false)
+
+  const scrollToBottom = useCallback((behavior: ScrollBehavior = SCROLL_BEHAVIOR) => {
+    const container = containerRef.current
+    if (!container) return
+    container.scrollTo({ top: container.scrollHeight, behavior })
+  }, [])
+
+  const handleScroll = useCallback((event: UIEvent<HTMLDivElement>) => {
+    const target = event.currentTarget
+    const distanceFromBottom = target.scrollHeight - target.scrollTop - target.clientHeight
+    const away = distanceFromBottom > NEAR_BOTTOM_THRESHOLD_PX
+
+    isAwayFromBottomRef.current = away
+    setIsAwayFromBottom((current) => (current === away ? current : away))
+  }, [])
+
+  /**
+   * Qual conversa já recebeu o salto de abertura.
+   *
+   * É o que separa "abriu a conversa" de "chegou mensagem", e não dá para usar só `conversationId`
+   * num efeito próprio: quando a conversa troca, a lista de mensagens ainda está vazia, então um
+   * salto ali rola um container sem conteúdo e não faz nada. O salto real precisa esperar a primeira
+   * leva de mensagens — e foi exatamente isso que deixou a conversa abrindo no topo.
+   */
+  const jumpedForConversationRef = useRef<string | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    const isNewConversation = jumpedForConversationRef.current !== conversationId
+
+    if (isNewConversation) {
+      // Zera antes de qualquer coisa: "rolado para trás" da conversa anterior não pode bloquear o
+      // salto de abertura desta.
+      isAwayFromBottomRef.current = false
+      setIsAwayFromBottom(false)
+
+      // Sem mensagens ainda — o salto acontece quando a primeira leva chegar.
+      if (messageCount === 0) return
+
+      jumpedForConversationRef.current = conversationId
+      /**
+       * `'auto'`, sempre. Animar a rolagem por meses de histórico demora, mostra um borrão de
+       * mensagens antigas que ninguém pediu, e some por completo onde a rolagem suave está desligada
+       * (`prefers-reduced-motion`, alguns navegadores automatizados) — a conversa simplesmente
+       * abriria no topo. Abertura é salto, não animação.
+       */
+      scrollToBottom(SCROLL_BEHAVIOR)
+      return
+    }
+
+    /**
+     * Mensagem nova: acompanha, mas só se o operador já estava no fim.
+     *
+     * Puxar a rolagem de quem está lendo o histórico é pior do que não mostrar a mensagem — ele perde
+     * a posição e não sabe por quê. Quem rolou para trás recebe `isAwayFromBottom` e decide.
+     */
+    if (isAwayFromBottomRef.current) return
+    scrollToBottom(SCROLL_BEHAVIOR)
+  }, [conversationId, messageCount, scrollToBottom])
+
+  return { containerRef, handleScroll, isAwayFromBottom, scrollToBottom }
+}

package/src/index.ts

@@ -1,26 +1,107 @@
 export { MessageBubble } from './MessageBubble'
+export { InteractiveMessage, DEFAULT_INTERACTIVE_MESSAGE_LABELS } from './InteractiveMessage'
 export { ConversationWallpaper } from './Wallpaper'
 export { ConversationLocalesProvider, useConversationLocales } from './ConversationLocalesProvider'
 export { AudioPlayer } from './AudioPlayer'
-export { EmojiPicker } from './EmojiPicker'
-export { MessageComposer } from './MessageComposer'
-export { WhatsAppMessageEditor } from './WhatsAppMessageEditor'
+export { AudioTranscription } from './AudioTranscription'
+export { EmojiPicker, DEFAULT_EMOJI_PICKER_LABELS } from './EmojiPicker'
+export { EMOJI_CATEGORIES, searchEmojis } from './emojiCatalog'
+export { MessageComposer, DEFAULT_MESSAGE_COMPOSER_LABELS, DEFAULT_ACCEPTED_FILE_TYPES } from './MessageComposer'
+export { RichMessageComposer, RICH_COMPOSER_ACTION, DEFAULT_RICH_COMPOSER_TOOLTIPS } from './RichMessageComposer'
+export type {
+  RichMessageComposerProps,
+  RichComposerAction,
+  RichComposerTooltips,
+  RichComposerQuickReply,
+  RichComposerVariable,
+  RichMessageComposerHandle,
+} from './RichMessageComposer'
+export {
+  AudioRecorderButton,
+  DEFAULT_AUDIO_RECORDER_BUTTON_LABELS,
+  DEFAULT_MAX_RECORDING_MILLISECONDS,
+} from './AudioRecorderButton'
+export type { AudioRecorderButtonProps, AudioRecorderButtonLabels } from './AudioRecorderButton'
+export { WhatsAppMessageEditor, DEFAULT_WHATSAPP_MESSAGE_EDITOR_LABELS } from './WhatsAppMessageEditor'
 export { SimpleEmojiPicker } from './SimpleEmojiPicker'
 export { DateDivider } from './DateDivider'
-export { Avatar } from './Avatar'
-export { ConversationListItem } from './ConversationListItem'
+export { Avatar, DEFAULT_AVATAR_LABELS } from './Avatar'
+export { ConversationListItem, DEFAULT_CONVERSATION_LIST_ITEM_LABELS } from './ConversationListItem'
 export { ToastProvider, useToast, toast } from './Toast'
 
 export { StatusTicks } from './StatusTicks'
-export { Lightbox } from './Lightbox'
+export { Lightbox, DEFAULT_LIGHTBOX_LABELS } from './Lightbox'
 export { MediaRenderer } from './MediaRenderer'
 export { FileIcon } from './FileIcon'
 export { MessageText } from './MessageText'
 export { MessageTimestamp } from './MessageTimestamp'
 export { MessageTail } from './MessageTail'
 
-export { useDarkMode } from './useDarkMode'
+// Operação da inbox: janela de 24h da Meta, linha com ações e painéis do atendimento. Regras da
+// plataforma e do ofício de atender, não de um produto — por isso moram aqui.
+export { CONVERSATION_WINDOW, WINDOW_FILTERS, windowOf, formatStalledFor } from './conversationWindow'
+export type { WindowOfParams } from './conversationWindow'
+// Canal de origem: capacidades por plataforma (janela de sessão, reabertura, tipo de identificador).
+export {
+  CONVERSATION_CHANNEL,
+  DEFAULT_CONVERSATION_CHANNEL,
+  CHANNEL_CAPABILITIES,
+  channelFiltersFor,
+  CHANNEL_FILTER_ALL,
+  REOPEN_MECHANISM,
+  HANDLE_KIND,
+  capabilitiesOf,
+  formatContactHandle,
+  contactFlag,
+} from './conversationChannel'
+export type {
+  ConversationChannel,
+  ChannelCapabilities,
+  ChannelFilter,
+  ChannelFilterOption,
+  ReopenMechanism,
+  HandleKind,
+  FormatContactHandleParams,
+} from './conversationChannel'
+export type { ConversationWindow } from './conversationWindow'
+export { ConversationRow } from './ConversationRow'
+export { ChannelIcon, CHANNEL_BRAND_COLOR } from './ChannelIcon'
+export type { ChannelIconProps } from './ChannelIcon'
+export type { ConversationRowProps, ConversationRowClassNames } from './ConversationRow'
+export { ConversationHeader, DEFAULT_CONVERSATION_HEADER_LABELS } from './ConversationHeader'
+export type {
+  ConversationHeaderProps,
+  ConversationHeaderLabels,
+  ConversationHeaderClassNames,
+} from './ConversationHeader'
+export { ConversationContextPanel, DEFAULT_CONVERSATION_CONTEXT_LABELS } from './ConversationContextPanel'
+export type {
+  ConversationContextPanelProps,
+  ConversationContextEntry,
+  ConversationContextStatus,
+  ConversationContextPanelLabels,
+  ConversationContextPanelClassNames,
+} from './ConversationContextPanel'
+export { WindowExpiredNotice, isWindowBlocking, DEFAULT_WINDOW_EXPIRED_LABELS } from './WindowExpiredNotice'
+export type { WindowExpiredNoticeProps, WindowExpiredNoticeLabels } from './WindowExpiredNotice'
+export { DocumentsLibrary, DEFAULT_DOCUMENTS_LIBRARY_LABELS } from './DocumentsLibrary'
+export type { DocumentsLibraryProps, DocumentsLibraryLabels, DocumentsLibraryClassNames } from './DocumentsLibrary'
+export { DOCUMENT_SOURCE_FILTER } from './ConversationDocumentsPanel'
+export type { DocumentSourceFilter } from './ConversationDocumentsPanel'
+export type { ConversationDocumentsPanelClassNames } from './ConversationDocumentsPanel'
+export { ConversationDocumentsPanel, DEFAULT_CONVERSATION_DOCUMENTS_LABELS } from './ConversationDocumentsPanel'
+export type { ConversationDocumentsPanelProps, ConversationDocumentsPanelLabels } from './ConversationDocumentsPanel'
+export { buildTranscriptText, buildTranscriptFilename, downloadTextFile } from './conversationTranscript'
+export type { BuildTranscriptTextParams } from './conversationTranscript'
+
+export { useDarkMode, useIsDarkTheme } from './useDarkMode'
+export { useIsNarrow, NARROW_MAX_WIDTH_PX } from './useIsNarrow'
 export { useWaitingNotifications } from './useWaitingNotifications'
+export type {
+  UseWaitingNotificationsLabels,
+  UseWaitingNotificationsParams,
+  UseWaitingNotificationsResult,
+} from './useWaitingNotifications'
 
 export { ConversationsProvider, useConversations } from './providers/ConversationsProvider'
 
@@ -29,36 +110,65 @@ export { ConversationsProvider, useConversations } from './providers/Conversatio
 export { WhatsAppTemplateSettingsForm } from './settings/WhatsAppTemplateSettingsForm'
 export { WhatsAppCreateTemplateForm } from './settings/WhatsAppCreateTemplateForm'
 export { WelcomeFarewellForm } from './settings/WelcomeFarewellForm'
+export { TranscriptionSettingsForm } from './settings/TranscriptionSettingsForm'
+export {
+  WhatsAppTemplatesSettings,
+  TEMPLATE_SETTINGS_TAB,
+  DEFAULT_TEMPLATES_SETTINGS_LABELS,
+} from './settings/WhatsAppTemplatesSettings'
 export { TopicsForm } from './settings/TopicsForm'
 
 // Camada headless (T6.9) — hooks de dados/ações independentes de qualquer tela, para o
 // produto montar sua própria UI sobre eles. Requerem <ConversationsProvider> como ancestral.
 export { useConversationMessages } from './hooks/useConversationMessages'
+export { useScrollToLatestMessage } from './hooks/useScrollToLatestMessage'
 export { useConversationList } from './hooks/useConversationList'
 export { useConversationContext } from './hooks/useConversationContext'
 export { useConversationDocuments } from './hooks/useConversationDocuments'
 export { useConversationRealtime, useGlobalRealtime } from './hooks/useConversationRealtime'
+export { useConversationActions, useInboxActions } from './hooks/useConversationActions'
 
 export { parseWhatsAppFormatting, waToHTML, htmlToWA, waToHTMLInline } from './lib/whatsapp-formatting'
 export { formatPhone, phoneInitials } from './lib/phone'
-export { formatTimestamp, formatFileSize } from './lib/format'
+// `formatDateTime` e `isSameDay` já eram usados pelas bolhas e pelo divisor de data; exportá-los
+// evita que cada host mantenha a própria cópia e acabe com timeline e transcript divergindo.
+export { formatTimestamp, formatFileSize, formatDateTime, isSameDay } from './lib/format'
 
 export type { MessagePayload, ConversationsUIConfig, ConversationsTheme, ConversationsFeatures } from './types'
-export type { ConversationsApi, SSEProvider, ConversationSummary, ConversationDocument } from './providers/types'
+export type { InteractivePayload, InteractiveSection, InteractiveOption, InteractiveSelection } from './types'
+export type { MessageTranscription, TranscriptionStatus, TranscriptionMode } from './types'
+export type {
+  ConversationsApi,
+  SSEProvider,
+  ConversationEventSource,
+  ConversationSummary,
+  ConversationDocument,
+  ConversationPage,
+  ConversationDocumentPage,
+  CompanyDocument,
+  CompanyDocumentPage,
+  ConversationTemplate,
+  ListConversationsParams,
+  ListDocumentsParams,
+} from './providers/types'
+export type { UseConversationActionsResult, UseInboxActionsResult } from './hooks/useConversationActions'
 
 export type { MessageBubbleProps } from './MessageBubble'
 export type { ConversationWallpaperProps } from './Wallpaper'
 export type { ConversationLocales, ConversationLocalesProviderProps } from './ConversationLocalesProvider'
 export type { AudioPlayerProps } from './AudioPlayer'
-export type { EmojiPickerProps } from './EmojiPicker'
-export type { MessageComposerProps } from './MessageComposer'
-export type { WhatsAppMessageEditorProps } from './WhatsAppMessageEditor'
+export type { AudioTranscriptionProps } from './AudioTranscription'
+export type { EmojiPickerProps, EmojiPickerLabels } from './EmojiPicker'
+export type { EmojiEntry, EmojiCategory } from './emojiCatalog'
+export type { InteractiveMessageProps, InteractiveMessageLabels } from './InteractiveMessage'
+export type { MessageComposerProps, MessageComposerClassNames, MessageComposerLabels } from './MessageComposer'
+export type { WhatsAppMessageEditorProps, WhatsAppMessageEditorLabels } from './WhatsAppMessageEditor'
 export type { SimpleEmojiPickerProps } from './SimpleEmojiPicker'
-export type { DateDividerProps } from './DateDivider'
-export type { AvatarProps } from './Avatar'
-export type { ConversationListItemProps } from './ConversationListItem'
+export type { DateDividerProps, DateDividerClassNames } from './DateDivider'
+export type { AvatarProps, AvatarLabels } from './Avatar'
+export type { ConversationListItemProps, ConversationListItemLabels } from './ConversationListItem'
 export type { StatusTicksProps } from './StatusTicks'
-export type { LightboxProps } from './Lightbox'
+export type { LightboxProps, LightboxLabels } from './Lightbox'
 export type { MediaRendererProps, ResolveMediaUrl } from './MediaRenderer'
 export type { FileIconProps } from './FileIcon'
 export type { MessageTextProps } from './MessageText'
@@ -77,11 +187,25 @@ export type {
   WhatsAppCreateTemplateFormLabels,
 } from './settings/WhatsAppCreateTemplateForm'
 export type { WelcomeFarewellFormProps, WelcomeFarewellFormLabels } from './settings/WelcomeFarewellForm'
+export type {
+  TranscriptionSettingsFormProps,
+  TranscriptionSettingsFormLabels,
+} from './settings/TranscriptionSettingsForm'
+export type {
+  WhatsAppTemplatesSettingsProps,
+  WhatsAppTemplatesSettingsLabels,
+  TemplateSettingsTab,
+} from './settings/WhatsAppTemplatesSettings'
 export type { TopicsFormProps, TopicItem, TopicsFormLabels } from './settings/TopicsForm'
 
 export type { UseConversationMessagesResult } from './hooks/useConversationMessages'
 export type { UseConversationListParams, UseConversationListResult } from './hooks/useConversationList'
 export type { UseConversationContextResult } from './hooks/useConversationContext'
+export type { UseScrollToLatestMessageParams, UseScrollToLatestMessageResult } from './hooks/useScrollToLatestMessage'
 export type { UseConversationDocumentsParams, UseConversationDocumentsResult } from './hooks/useConversationDocuments'
 export type { ConversationRealtimeHandler } from './hooks/useConversationRealtime'
 export type { AsyncResourceState } from './hooks/useAsyncResource'
+export { createMediaUrlResolver } from './lib/createMediaUrlResolver'
+export type { ConversationHeaderUtility } from './ConversationHeader'
+export { applyQuickReplyVariables, resolveQuickReply } from './MessageComposer'
+export type { QuickReply } from './MessageComposer'

package/src/lib/cn.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'bun:test'
+
+import { cn } from './cn'
+
+describe('cn', () => {
+  // O contrato de `classNames`/`className` dos componentes depende disto: se o override não vencer,
+  // a API de customização é decorativa. Concatenar falharia justo no caso comum — o Tailwind emite
+  // `px-2` antes de `px-4`, então a base ganharia de quem quer apertar o espaçamento.
+  it('o override do host vence a classe base em conflito', () => {
+    expect(cn('px-4 py-3', 'px-2')).toBe('py-3 px-2')
+  })
+
+  it('mantém o que não conflita', () => {
+    expect(cn('flex items-center gap-3', 'gap-1')).toBe('flex items-center gap-1')
+  })
+
+  it('preserva classes próprias do pacote, que o merge não conhece', () => {
+    expect(cn('cv-row flex', 'bg-red-50')).toBe('cv-row flex bg-red-50')
+  })
+
+  it('ignora ausente, falso e vazio', () => {
+    expect(cn('border-b', undefined, false, '')).toBe('border-b')
+  })
+
+  it('aplica condicional na ordem recebida', () => {
+    const isCompact = false
+    expect(cn('mt-2', isCompact && 'mt-8', 'mt-4')).toBe('mt-4')
+  })
+})

package/src/lib/cn.ts

@@ -0,0 +1,15 @@
+/**
+ * Junta classes resolvendo conflitos de utilitário do Tailwind.
+ *
+ * Concatenar não basta: a ordem no atributo `class` não decide nada, quem decide é a ordem no CSS
+ * gerado. Com `px-4` na base e `px-2` vindo do host, o Tailwind emite `px-2` antes de `px-4` e a
+ * base ganharia — justo o caso de quem quer apertar o espaçamento. O `twMerge` descarta a classe
+ * base quando o host manda uma da mesma família, então o override do produto sempre vence.
+ */
+
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}

package/src/lib/createMediaUrlResolver.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve a mídia de uma mensagem numa URL exibível, usando só o `ConversationsApi`.
+ *
+ * Mora no pacote, e não em cada host, porque a regra não tem nada de específico de produto: é a
+ * tradução de `uploadId`/`mediaId` pelos dois métodos que o próprio contrato já declara. Deixá-la no
+ * host significava que todo projeto que adotasse o SDK reescreveria as mesmas oito linhas — e, na
+ * prática, ninguém escrevia: o `MediaRenderer` só busca mídia pela porta `onResolveMediaUrl`, então
+ * onde nada era injetado foto, vídeo e áudio ficavam no placeholder para sempre.
+ */
+
+import type { MessagePayload } from '../types'
+import type { ConversationsApi } from '../providers/types'
+import type { ResolveMediaUrl } from '../MediaRenderer'
+
+export function createMediaUrlResolver(
+  api: Pick<ConversationsApi, 'getDocumentUrl' | 'getMediaProxyUrl'>,
+): ResolveMediaUrl {
+  return async (message: MessagePayload): Promise<string | null> => {
+    // Mídia já copiada para o storage do host: sai por URL assinada e o binário não passa pela API.
+    // `inline` porque aqui o arquivo é para VER na tela — `attachment` faria o navegador baixar.
+    if (message.uploadId) return api.getDocumentUrl(message.uploadId, 'inline')
+
+    // Antes da ingestão só existe o id na Meta, cuja URL expira; o backend busca e devolve base64.
+    // Data URL serve de `src` para `<img>`/`<video>`/`<audio>`: o bloqueio do Chrome a `data:` vale
+    // para navegação de topo, não para carregar mídia dentro da página.
+    if (message.mediaId) {
+      const { mimeType, data } = await api.getMediaProxyUrl(message.mediaId)
+      return `data:${mimeType};base64,${data}`
+    }
+
+    return null
+  }
+}

package/src/lib/paginated.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'bun:test'
+import { conversationsOf, documentsOf, totalOf } from './paginated'
+import type { ConversationDocument, ConversationSummary } from '../providers/types'
+
+const conversation = { id: '1', whatsappNumber: '5511900000000' } as ConversationSummary
+const document = { id: 'd1', filename: 'contrato.pdf' } as ConversationDocument
+
+describe('normalização de lista ou página', () => {
+  // As duas formas existem porque o contrato aceita as duas: array puro é o retorno original, e
+  // implementações antigas continuam válidas. Um consumidor que só tratasse uma delas quebraria
+  // em runtime, não no compilador.
+  it('aceita o array puro do contrato original', () => {
+    expect(conversationsOf([conversation])).toEqual([conversation])
+    expect(documentsOf([document])).toEqual([document])
+  })
+
+  it('desembrulha a forma paginada', () => {
+    expect(conversationsOf({ conversations: [conversation], total: 42 })).toEqual([conversation])
+    expect(documentsOf({ documents: [document], total: 7 })).toEqual([document])
+  })
+
+  it('usa o total do servidor quando ele vem, e o tamanho da página quando não vem', () => {
+    // A distinção importa: com array puro não dá para saber se a página é a última, então o
+    // melhor palpite honesto é o que se tem em mãos.
+    expect(totalOf({ conversations: [conversation], total: 42 })).toBe(42)
+    expect(totalOf([conversation])).toBe(1)
+  })
+
+  it('trata página vazia sem confundir com ausência de dados', () => {
+    expect(conversationsOf({ conversations: [], total: 0 })).toEqual([])
+    expect(totalOf({ conversations: [], total: 0 })).toBe(0)
+  })
+})

package/src/lib/paginated.ts

@@ -0,0 +1,26 @@
+import type {
+  ConversationDocument,
+  ConversationDocumentPage,
+  ConversationPage,
+  ConversationSummary,
+} from '../providers/types'
+
+/**
+ * `fetchConversations` e `getDocuments` devolvem o array puro (contrato original) ou uma página
+ * com total. Normalizar num lugar só evita que cada consumidor invente sua própria checagem —
+ * e um consumidor esquecido não falha no compilador, falha em runtime com `.map is not a
+ * function`.
+ */
+export function conversationsOf(result: ConversationSummary[] | ConversationPage): ConversationSummary[] {
+  return Array.isArray(result) ? result : result.conversations
+}
+
+export function documentsOf(result: ConversationDocument[] | ConversationDocumentPage): ConversationDocument[] {
+  return Array.isArray(result) ? result : result.documents
+}
+
+export function totalOf(
+  result: ConversationSummary[] | ConversationPage | ConversationDocument[] | ConversationDocumentPage,
+): number {
+  return Array.isArray(result) ? result.length : result.total
+}

package/src/lib/phone.ts

@@ -20,6 +20,40 @@ export function formatPhone(number: string): string {
   return number
 }
 
+// Mapa explícito em vez de derivar o emoji do código: prefixos são ambíguos (1 = EUA e Canadá,
+// 7 = Rússia e Cazaquistão) e mostrar a bandeira errada é pior do que não mostrar nenhuma.
+const COUNTRY_FLAG_BY_DIAL_CODE: Readonly<Record<string, string>> = {
+  '55': '🇧🇷',
+  '351': '🇵🇹',
+  '34': '🇪🇸',
+  '54': '🇦🇷',
+  '56': '🇨🇱',
+  '57': '🇨🇴',
+  '52': '🇲🇽',
+  '598': '🇺🇾',
+  '595': '🇵🇾',
+  '44': '🇬🇧',
+  '49': '🇩🇪',
+  '39': '🇮🇹',
+  '33': '🇫🇷',
+}
+
+/**
+ * Devolve string vazia quando não reconhece o país — quem renderiza decide se some com o espaço.
+ */
+export function phoneCountryFlag(number: string): string {
+  const digits = number.replace(/\D/g, '')
+
+  // Do prefixo mais longo para o mais curto: '55' casaria antes de '551' e daria bandeira errada
+  // em países de código de três dígitos.
+  for (const length of [3, 2, 1]) {
+    const flag = COUNTRY_FLAG_BY_DIAL_CODE[digits.slice(0, length)]
+    if (flag) return flag
+  }
+
+  return ''
+}
+
 export function phoneInitials(number: string): string {
   const digits = number.replace(/\D/g, '')
   return digits.slice(-2)