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

package/src/flows/FlowPalette.tsx

@@ -72,7 +72,9 @@ export function FlowPalette({ onAdd, labels: labelsOverride, actionOptions }: Fl
               onClick={() => setSubmenu(submenu === 'question' ? null : 'question')}
               className="w-full flex items-center justify-between gap-2 px-3 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"
             >
-              <span className="flex items-center gap-2"><MessageCircleQuestion size={15} className="text-blue-500" /> {labels.palette.question}</span>
+              <span className="flex items-center gap-2">
+                <MessageCircleQuestion size={15} className="text-blue-500" /> {labels.palette.question}
+              </span>
               <ChevronRight size={13} className="text-gray-400" />
             </button>
             {submenu === 'question' && (
@@ -113,7 +115,9 @@ export function FlowPalette({ onAdd, labels: labelsOverride, actionOptions }: Fl
               onClick={() => setSubmenu(submenu === 'action' ? null : 'action')}
               className="w-full flex items-center justify-between gap-2 px-3 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"
             >
-              <span className="flex items-center gap-2"><Zap size={15} className="text-orange-500" /> {labels.palette.action}</span>
+              <span className="flex items-center gap-2">
+                <Zap size={15} className="text-orange-500" /> {labels.palette.action}
+              </span>
               <ChevronRight size={13} className="text-gray-400" />
             </button>
             {submenu === 'action' && (

package/src/flows/FlowWhatsAppPreview.tsx

@@ -13,7 +13,11 @@ export interface FlowWhatsAppPreviewProps {
 // opções, botões (≤3) ou lista (4+) — para o editor mostrar exatamente o que o cliente verá.
 // Consome a mesma bolha/formatação do pacote (parseWhatsAppFormatting, T6.5) — T7.3 elimina a
 // duplicação de estilo que existia entre este preview e o MessageBubble do bot.
-export function FlowWhatsAppPreview({ body, options, labels = DEFAULT_FLOW_EDITOR_LABELS.nodePanel }: FlowWhatsAppPreviewProps) {
+export function FlowWhatsAppPreview({
+  body,
+  options,
+  labels = DEFAULT_FLOW_EDITOR_LABELS.nodePanel,
+}: FlowWhatsAppPreviewProps) {
   if (!body && (!options || options.length === 0)) {
     return <p className="text-xs text-gray-400 dark:text-gray-500 italic px-1">{labels.previewPlaceholder}</p>
   }
@@ -25,7 +29,11 @@ export function FlowWhatsAppPreview({ body, options, labels = DEFAULT_FLOW_EDITO
     <div className="rounded-xl bg-[#e5ddd5] dark:bg-gray-900 p-3 space-y-1.5">
       <div className="max-w-[85%]">
         <div className="rounded-lg rounded-tl-none bg-white dark:bg-gray-700 px-3 py-2 text-sm text-gray-900 dark:text-gray-100 shadow-sm whitespace-pre-wrap break-words">
-          {body ? parseWhatsAppFormatting(body) : <span className="italic text-gray-400">{labels.previewEmptyBody}</span>}
+          {body ? (
+            parseWhatsAppFormatting(body)
+          ) : (
+            <span className="italic text-gray-400">{labels.previewEmptyBody}</span>
+          )}
           {hasOptions && !usesButtons && (
             <div className="mt-2 -mx-3 -mb-2 border-t border-gray-100 dark:border-gray-600">
               <div className="flex items-center justify-center gap-1.5 py-2 text-sm font-medium text-cyan-600 dark:text-cyan-400">
@@ -38,7 +46,10 @@ export function FlowWhatsAppPreview({ body, options, labels = DEFAULT_FLOW_EDITO
         {hasOptions && usesButtons && (
           <div className="mt-1 space-y-1">
             {options!.map(([id, label]) => (
-              <div key={id} className="rounded-lg bg-white dark:bg-gray-700 py-1.5 text-center text-sm font-medium text-cyan-600 dark:text-cyan-400 shadow-sm">
+              <div
+                key={id}
+                className="rounded-lg bg-white dark:bg-gray-700 py-1.5 text-center text-sm font-medium text-cyan-600 dark:text-cyan-400 shadow-sm"
+              >
                 {label || <span className="italic text-gray-400">{labels.previewEmptyOption}</span>}
               </div>
             ))}

package/src/flows/flowGraph.ts

@@ -13,6 +13,7 @@ import type {
   FlowNodeData,
   FlowGraphData,
 } from '@adatechnology/meta-whatsapp-contracts'
+import { FLOW_ACTION_KIND } from '@adatechnology/meta-whatsapp-contracts'
 
 export type {
   FlowNodeType,
@@ -28,11 +29,10 @@ export const CONDITION_OPERATORS: FlowConditionOperator[] = ['>', '>=', '<', '<=
 
 // Kinds de ação genéricos que o pacote conhece de fábrica — o host pode registrar quaisquer
 // outros via `actionKindLabels`/`actionKinds` nos componentes (ver FlowPalette, labels.ts).
-export const BUILT_IN_ACTION_KINDS = {
-  HANDOFF: 'handoff',
-  RATE_LIMITED_HANDOFF: 'rate_limited_handoff',
-  SEND_PRODUCT_LIST: 'send_product_list',
-} as const
+// Reexporta o vocabulário do contrato em vez de redeclarar os literais: o editor oferece na
+// paleta exatamente os `actionKind` que o backend sabe interpretar, e duas listas separadas
+// divergiriam em silêncio (um nó publicável que nenhum handler atende).
+export const BUILT_IN_ACTION_KINDS = FLOW_ACTION_KIND
 
 // Destinos "flow:<key>" são saltos para outro fluxo, resolvidos pelo motor do host. Duplicado
 // (em vez de importado do contracts) de propósito: são três linhas triviais e importá-las como

package/src/flows/labels.ts

@@ -47,6 +47,8 @@ export interface FlowEditorLabels {
     conditionTrue: string
     conditionFalse: string
     conditionVariableMissing: string
+    media: string
+    mediaUnavailable: string
   }
   palette: {
     title: string
@@ -87,6 +89,7 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     handoff: 'Encaminhar para atendimento',
     rate_limited_handoff: 'Encaminhar (limite de simulações atingido)',
     send_product_list: 'Enviar catálogo de produtos',
+    send_media: 'Enviar arquivos da biblioteca',
   },
   conditionOperatorLabels: {
     '>': 'maior que',
@@ -143,6 +146,8 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     conditionTrue: 'Se verdadeiro →',
     conditionFalse: 'Se falso →',
     conditionVariableMissing: 'Se a variável ainda não foi coletada →',
+    media: 'Arquivos enviados neste ponto',
+    mediaUnavailable: 'A biblioteca de arquivos não está disponível neste painel.',
   },
   palette: {
     title: 'Adicionar ao fluxo',

package/src/hooks/useConversationActions.ts

@@ -0,0 +1,56 @@
+import { useMemo } from 'react'
+import { useConversations } from '../providers/ConversationsProvider'
+import type { ConversationTemplate } from '../providers/types'
+
+export interface UseConversationActionsResult {
+  /** `undefined` quando a API do host não implementa a operação — a UI esconde a afordância. */
+  takeover: (() => Promise<void>) | undefined
+  release: (() => Promise<void>) | undefined
+  finalize: (() => Promise<void>) | undefined
+}
+
+/**
+ * Ações de atendimento de UMA conversa, já ligadas ao id.
+ *
+ * Separado de `useConversationMessages` porque assumir e devolver conversa também acontece a
+ * partir da lista, onde nenhuma thread está aberta — embutir nas mensagens obrigaria a carregar
+ * a thread inteira só para desenhar um botão na linha.
+ */
+export function useConversationActions(conversationId: string): UseConversationActionsResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useConversationActions requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  return useMemo(
+    () => ({
+      takeover: api.takeover ? () => api.takeover!(conversationId) : undefined,
+      release: api.release ? () => api.release!(conversationId) : undefined,
+      finalize: api.finalize ? () => api.finalize!(conversationId) : undefined,
+    }),
+    [api, conversationId],
+  )
+}
+
+export interface UseInboxActionsResult {
+  markAllRead: (() => Promise<void>) | undefined
+  listTemplates: (() => Promise<ConversationTemplate[]>) | undefined
+}
+
+/** Ações que valem para a caixa inteira, sem conversa selecionada. */
+export function useInboxActions(): UseInboxActionsResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useInboxActions requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  return useMemo(
+    () => ({
+      markAllRead: api.markAllRead ? () => api.markAllRead!() : undefined,
+      listTemplates: api.listTemplates ? () => api.listTemplates!() : undefined,
+    }),
+    [api],
+  )
+}

package/src/hooks/useConversationDocuments.ts

@@ -1,21 +1,23 @@
 import { useConversations } from '../providers/ConversationsProvider'
 import { useAsyncResource } from './useAsyncResource'
-import type { ConversationDocument } from '../providers/types'
+import { documentsOf, totalOf } from '../lib/paginated'
+import type { ConversationDocument, ListDocumentsParams } from '../providers/types'
 
-export interface UseConversationDocumentsParams {
-  search?: string
-  page?: number
-}
+export type UseConversationDocumentsParams = ListDocumentsParams
 
 export interface UseConversationDocumentsResult {
   documents: ConversationDocument[]
+  /** Total no servidor. Cai para o tamanho da página quando a API devolve só o array. */
+  total: number
   loading: boolean
   error: Error | undefined
   refetch: () => Promise<void>
 }
 
+// Aceita `undefined` como "ainda não buscar", igual a `useConversationRealtime`: a lista de anexos
+// é consulta extra, e quem só abre o painel sob demanda não deve pagar por ela em toda conversa.
 export function useConversationDocuments(
-  conversationId: string,
+  conversationId: string | undefined,
   params?: UseConversationDocumentsParams,
 ): UseConversationDocumentsResult {
   const context = useConversations()
@@ -25,9 +27,13 @@ export function useConversationDocuments(
   const { api } = context
 
   const { data, loading, error, refetch } = useAsyncResource(
-    () => api.getDocuments(conversationId, params),
-    [conversationId, params?.search, params?.page],
+    () => (conversationId ? api.getDocuments(conversationId, params) : Promise.resolve([])),
+    [conversationId, params?.search, params?.page, params?.limit, params?.source, params?.sortDirection],
   )
 
-  return { documents: data ?? [], loading, error, refetch }
+  if (data === undefined) {
+    return { documents: [], total: 0, loading, error, refetch }
+  }
+
+  return { documents: documentsOf(data), total: totalOf(data), loading, error, refetch }
 }

package/src/hooks/useConversationList.ts

@@ -1,16 +1,14 @@
 import { useConversations } from '../providers/ConversationsProvider'
 import { useAsyncResource } from './useAsyncResource'
-import type { ConversationSummary } from '../providers/types'
+import { conversationsOf, totalOf } from '../lib/paginated'
+import type { ConversationSummary, ListConversationsParams } from '../providers/types'
 
-export interface UseConversationListParams {
-  page?: number
-  limit?: number
-  waitingHuman?: boolean
-  search?: string
-}
+export type UseConversationListParams = ListConversationsParams
 
 export interface UseConversationListResult {
   conversations: ConversationSummary[]
+  /** Total no servidor. Cai para o tamanho da página quando a API devolve só o array. */
+  total: number
   loading: boolean
   error: Error | undefined
   refetch: () => Promise<void>
@@ -23,10 +21,18 @@ export function useConversationList(params?: UseConversationListParams): UseConv
   }
   const { api } = context
 
+  // `filters` é objeto novo a cada render do host; serializar evita refetch em laço sem obrigar
+  // o consumidor a memoizar — omissão que só apareceria como loop de rede em produção.
+  const filtersKey = JSON.stringify(params?.filters ?? {})
+
   const { data, loading, error, refetch } = useAsyncResource(
     () => api.fetchConversations(params),
-    [params?.page, params?.limit, params?.waitingHuman, params?.search],
+    [params?.page, params?.limit, params?.waitingHuman, params?.search, filtersKey],
   )
 
-  return { conversations: data ?? [], loading, error, refetch }
+  if (data === undefined) {
+    return { conversations: [], total: 0, loading, error, refetch }
+  }
+
+  return { conversations: conversationsOf(data), total: totalOf(data), loading, error, refetch }
 }

package/src/hooks/useConversationMessages.ts

@@ -10,7 +10,7 @@ export interface UseConversationMessagesResult {
   refetch: () => Promise<void>
   sendMessage: (text: string) => Promise<MessagePayload>
   sendMedia: (data: { base64: string; mimeType: string; filename: string; caption?: string }) => Promise<MessagePayload>
-  sendTemplate: (data: { templateName: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
+  sendTemplate: (data: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
   markRead: () => Promise<void>
 }
 
@@ -51,7 +51,7 @@ export function useConversationMessages(
   )
 
   const sendTemplate = useCallback(
-    async (templateData: { templateName: string; languageCode?: string; bodyParams?: string[] }) => {
+    async (templateData: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => {
       await api.sendTemplate(conversationId, templateData)
       await refetch()
     },

package/src/index.ts

@@ -1,26 +1,105 @@
 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 { 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,
+  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,6 +108,11 @@ export { ConversationsProvider, useConversations } from './providers/Conversatio
 export { WhatsAppTemplateSettingsForm } from './settings/WhatsAppTemplateSettingsForm'
 export { WhatsAppCreateTemplateForm } from './settings/WhatsAppCreateTemplateForm'
 export { WelcomeFarewellForm } from './settings/WelcomeFarewellForm'
+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
@@ -38,27 +122,47 @@ 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 {
+  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 { 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,6 +181,11 @@ export type {
   WhatsAppCreateTemplateFormLabels,
 } from './settings/WhatsAppCreateTemplateForm'
 export type { WelcomeFarewellFormProps, WelcomeFarewellFormLabels } from './settings/WelcomeFarewellForm'
+export type {
+  WhatsAppTemplatesSettingsProps,
+  WhatsAppTemplatesSettingsLabels,
+  TemplateSettingsTab,
+} from './settings/WhatsAppTemplatesSettings'
 export type { TopicsFormProps, TopicItem, TopicsFormLabels } from './settings/TopicsForm'
 
 export type { UseConversationMessagesResult } from './hooks/useConversationMessages'
@@ -85,3 +194,7 @@ export type { UseConversationContextResult } from './hooks/useConversationContex
 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
+}