@adatechnology/conversations-ui 0.0.0

package/src/hooks/useConversationDocuments.ts

@@ -0,0 +1,33 @@
+import { useConversations } from '../providers/ConversationsProvider'
+import { useAsyncResource } from './useAsyncResource'
+import type { ConversationDocument } from '../providers/types'
+
+export interface UseConversationDocumentsParams {
+  search?: string
+  page?: number
+}
+
+export interface UseConversationDocumentsResult {
+  documents: ConversationDocument[]
+  loading: boolean
+  error: Error | undefined
+  refetch: () => Promise<void>
+}
+
+export function useConversationDocuments(
+  conversationId: string,
+  params?: UseConversationDocumentsParams,
+): UseConversationDocumentsResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useConversationDocuments requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  const { data, loading, error, refetch } = useAsyncResource(
+    () => api.getDocuments(conversationId, params),
+    [conversationId, params?.search, params?.page],
+  )
+
+  return { documents: data ?? [], loading, error, refetch }
+}

package/src/hooks/useConversationList.ts

@@ -0,0 +1,32 @@
+import { useConversations } from '../providers/ConversationsProvider'
+import { useAsyncResource } from './useAsyncResource'
+import type { ConversationSummary } from '../providers/types'
+
+export interface UseConversationListParams {
+  page?: number
+  limit?: number
+  waitingHuman?: boolean
+  search?: string
+}
+
+export interface UseConversationListResult {
+  conversations: ConversationSummary[]
+  loading: boolean
+  error: Error | undefined
+  refetch: () => Promise<void>
+}
+
+export function useConversationList(params?: UseConversationListParams): UseConversationListResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useConversationList requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  const { data, loading, error, refetch } = useAsyncResource(
+    () => api.fetchConversations(params),
+    [params?.page, params?.limit, params?.waitingHuman, params?.search],
+  )
+
+  return { conversations: data ?? [], loading, error, refetch }
+}

package/src/hooks/useConversationMessages.ts

@@ -0,0 +1,64 @@
+import { useCallback } from 'react'
+import { useConversations } from '../providers/ConversationsProvider'
+import { useAsyncResource } from './useAsyncResource'
+import type { MessagePayload } from '../types'
+
+export interface UseConversationMessagesResult {
+  messages: MessagePayload[]
+  loading: boolean
+  error: Error | undefined
+  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>
+  markRead: () => Promise<void>
+}
+
+// Camada headless: dados + ações de uma conversa, sem nenhuma tela acoplada — o produto
+// consome este hook e monta a UI que quiser (ou usa <MessageBubble>/<MessageComposer>
+// por cima, como o pacote já oferece). Requer <ConversationsProvider> como ancestral.
+export function useConversationMessages(
+  conversationId: string,
+  params?: { limit?: number; before?: string },
+): UseConversationMessagesResult {
+  const context = useConversations()
+  if (!context) {
+    throw new Error('useConversationMessages requires an ancestor <ConversationsProvider>')
+  }
+  const { api } = context
+
+  const { data, loading, error, refetch } = useAsyncResource(
+    () => api.fetchMessages(conversationId, params),
+    [conversationId, params?.limit, params?.before],
+  )
+
+  const sendMessage = useCallback(
+    async (text: string) => {
+      const message = await api.sendMessage(conversationId, text)
+      await refetch()
+      return message
+    },
+    [api, conversationId, refetch],
+  )
+
+  const sendMedia = useCallback(
+    async (mediaData: { base64: string; mimeType: string; filename: string; caption?: string }) => {
+      const message = await api.sendMedia(conversationId, mediaData)
+      await refetch()
+      return message
+    },
+    [api, conversationId, refetch],
+  )
+
+  const sendTemplate = useCallback(
+    async (templateData: { templateName: string; languageCode?: string; bodyParams?: string[] }) => {
+      await api.sendTemplate(conversationId, templateData)
+      await refetch()
+    },
+    [api, conversationId, refetch],
+  )
+
+  const markRead = useCallback(() => api.markRead(conversationId), [api, conversationId])
+
+  return { messages: data ?? [], loading, error, refetch, sendMessage, sendMedia, sendTemplate, markRead }
+}

package/src/hooks/useConversationRealtime.ts

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from 'react'
+import { useConversations } from '../providers/ConversationsProvider'
+
+export type ConversationRealtimeHandler = (event: MessageEvent) => void
+
+// Assina o SSE de uma conversa via a porta SSEProvider injetada no ConversationsProvider —
+// o pacote nunca abre a conexão diretamente contra um endpoint fixo. Reconecta ao trocar
+// de conversationId e sempre fecha a EventSource anterior no cleanup.
+export function useConversationRealtime(
+  conversationId: string | undefined,
+  onEvent: ConversationRealtimeHandler,
+): void {
+  const context = useConversations()
+  const onEventRef = useRef(onEvent)
+  onEventRef.current = onEvent
+
+  useEffect(() => {
+    if (!context || !conversationId) return
+
+    const source = context.sse.connectConversationStream(conversationId)
+    const handler = (event: MessageEvent) => onEventRef.current(event)
+    source.addEventListener('message', handler)
+
+    return () => {
+      source.removeEventListener('message', handler)
+      source.close()
+    }
+  }, [context, conversationId])
+}
+
+// Assina o stream global (ex: novas conversas entrando na fila, notificações cross-conversa)
+// — mesma porta SSEProvider, sem conversationId.
+export function useGlobalRealtime(onEvent: ConversationRealtimeHandler): void {
+  const context = useConversations()
+  const onEventRef = useRef(onEvent)
+  onEventRef.current = onEvent
+
+  useEffect(() => {
+    if (!context) return
+
+    const source = context.sse.connectGlobalStream()
+    const handler = (event: MessageEvent) => onEventRef.current(event)
+    source.addEventListener('message', handler)
+
+    return () => {
+      source.removeEventListener('message', handler)
+      source.close()
+    }
+  }, [context])
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+export { MessageBubble } from './MessageBubble'
+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 { SimpleEmojiPicker } from './SimpleEmojiPicker'
+export { DateDivider } from './DateDivider'
+export { Avatar } from './Avatar'
+export { ConversationListItem } from './ConversationListItem'
+export { ToastProvider, useToast, toast } from './Toast'
+
+export { StatusTicks } from './StatusTicks'
+export { Lightbox } 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'
+export { useWaitingNotifications } from './useWaitingNotifications'
+
+export { ConversationsProvider, useConversations } from './providers/ConversationsProvider'
+
+// Telas de Settings (T7.1) — apresentacionais, sem chamada de rede própria; o host busca
+// dados (templates da Meta, mensagens salvas) e injeta via props.
+export { WhatsAppTemplateSettingsForm } from './settings/WhatsAppTemplateSettingsForm'
+export { WhatsAppCreateTemplateForm } from './settings/WhatsAppCreateTemplateForm'
+export { WelcomeFarewellForm } from './settings/WelcomeFarewellForm'
+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 { useConversationList } from './hooks/useConversationList'
+export { useConversationContext } from './hooks/useConversationContext'
+export { useConversationDocuments } from './hooks/useConversationDocuments'
+export { useConversationRealtime, useGlobalRealtime } from './hooks/useConversationRealtime'
+
+export { parseWhatsAppFormatting, waToHTML, htmlToWA, waToHTMLInline } from './lib/whatsapp-formatting'
+export { formatPhone, phoneInitials } from './lib/phone'
+export { formatTimestamp, formatFileSize } from './lib/format'
+
+export type { MessagePayload, ConversationsUIConfig, ConversationsTheme, ConversationsFeatures } from './types'
+export type { ConversationsApi, SSEProvider, ConversationSummary, ConversationDocument } from './providers/types'
+
+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 { SimpleEmojiPickerProps } from './SimpleEmojiPicker'
+export type { DateDividerProps } from './DateDivider'
+export type { AvatarProps } from './Avatar'
+export type { ConversationListItemProps } from './ConversationListItem'
+export type { StatusTicksProps } from './StatusTicks'
+export type { LightboxProps } from './Lightbox'
+export type { MediaRendererProps, ResolveMediaUrl } from './MediaRenderer'
+export type { FileIconProps } from './FileIcon'
+export type { MessageTextProps } from './MessageText'
+
+export type {
+  WhatsAppTemplateSettingsFormProps,
+  WhatsAppTemplateSummary,
+  WhatsAppTemplateVariableSuggestion,
+  WhatsAppTemplateSettingsFormLabels,
+} from './settings/WhatsAppTemplateSettingsForm'
+export type {
+  WhatsAppCreateTemplateFormProps,
+  WhatsAppCreateTemplateState,
+  WhatsAppCreateTemplateResult,
+  WhatsAppTemplateHeaderType,
+  WhatsAppCreateTemplateFormLabels,
+} from './settings/WhatsAppCreateTemplateForm'
+export type { WelcomeFarewellFormProps, WelcomeFarewellFormLabels } from './settings/WelcomeFarewellForm'
+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 { UseConversationDocumentsParams, UseConversationDocumentsResult } from './hooks/useConversationDocuments'
+export type { ConversationRealtimeHandler } from './hooks/useConversationRealtime'
+export type { AsyncResourceState } from './hooks/useAsyncResource'

package/src/lib/format.ts

@@ -0,0 +1,32 @@
+export function formatTimestamp(timestamp: string): string {
+  try {
+    const date = new Date(timestamp)
+    const hours = date.getHours().toString().padStart(2, '0')
+    const minutes = date.getMinutes().toString().padStart(2, '0')
+    return `${hours}:${minutes}`
+  } catch {
+    return timestamp
+  }
+}
+
+export function formatDateTime(iso: string): string {
+  const d = new Date(iso)
+  return d.toLocaleString('pt-BR', { day: '2-digit', month: '2-digit', hour: '2-digit', minute: '2-digit' })
+}
+
+export function isSameDay(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate()
+}
+
+const FILE_SIZE_UNITS = ['B', 'KB', 'MB', 'GB'] as const
+
+export function formatFileSize(bytes: number): string {
+  if (!isFinite(bytes) || bytes < 0) return ''
+  if (bytes < 1) return '0 B'
+
+  const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), FILE_SIZE_UNITS.length - 1)
+  const value = bytes / 1024 ** exponent
+  const formatted = exponent === 0 ? value.toString() : value.toFixed(value < 10 ? 1 : 0)
+
+  return `${formatted} ${FILE_SIZE_UNITS[exponent]}`
+}

package/src/lib/phone.ts

@@ -0,0 +1,26 @@
+export function formatPhone(number: string): string {
+  const digits = number.replace(/\D/g, '')
+
+  if (digits.length === 13) {
+    return `+${digits.slice(0, 2)} (${digits.slice(2, 4)}) ${digits.slice(4, 9)}-${digits.slice(9, 13)}`
+  }
+
+  if (digits.length === 12) {
+    return `+${digits.slice(0, 2)} (${digits.slice(2, 4)}) ${digits.slice(4, 8)}-${digits.slice(8, 12)}`
+  }
+
+  if (digits.length === 11) {
+    return `(${digits.slice(0, 2)}) ${digits.slice(2, 7)}-${digits.slice(7, 11)}`
+  }
+
+  if (digits.length === 10) {
+    return `(${digits.slice(0, 2)}) ${digits.slice(2, 6)}-${digits.slice(6, 10)}`
+  }
+
+  return number
+}
+
+export function phoneInitials(number: string): string {
+  const digits = number.replace(/\D/g, '')
+  return digits.slice(-2)
+}

package/src/lib/whatsapp-formatting.tsx

@@ -0,0 +1,215 @@
+import type { ReactNode } from 'react'
+
+interface FormatToken {
+  type: 'text' | 'bold' | 'italic' | 'strikethrough' | 'monospace' | 'codeblock'
+  content: string
+}
+
+const MONOSPACE_REGEX = /```([\s\S]*?)```/g
+const BOLD_REGEX = /\*([^*]+)\*/g
+const ITALIC_REGEX = /_([^_]+)_/g
+const STRIKETHROUGH_REGEX = /~([^~]+)~/g
+const INLINE_CODE_REGEX = /`([^`]+)`/g
+
+function tokenize(text: string): FormatToken[] {
+  const tokens: FormatToken[] = []
+
+  let remaining = text
+
+  const codeBlocks: { index: number; content: string }[] = []
+  remaining = remaining.replace(MONOSPACE_REGEX, (_match, content, offset) => {
+    codeBlocks.push({ index: offset, content })
+    return '\u0000'.repeat(_match.length)
+  })
+
+  let codeBlockIndex = 0
+  let i = 0
+  let buffer = ''
+
+  while (i < remaining.length) {
+    if (remaining[i] === '\u0000') {
+      if (buffer) {
+        tokens.push(...parseInlineTokens(buffer))
+        buffer = ''
+      }
+      const cb = codeBlocks[codeBlockIndex++]
+      tokens.push({ type: 'codeblock', content: cb.content })
+      const skip = '```' + cb.content + '```'
+      i += skip.length
+      continue
+    }
+    // Check for inline code
+    const inlineMatch = remaining.slice(i).match(/^`([^`]+)`/)
+    if (inlineMatch && inlineMatch.index === 0) {
+      if (buffer) {
+        tokens.push(...parseInlineTokens(buffer))
+        buffer = ''
+      }
+      tokens.push({ type: 'monospace', content: inlineMatch[1] })
+      i += inlineMatch[0].length
+      continue
+    }
+
+    buffer += remaining[i]
+    i++
+  }
+
+  if (buffer) {
+    tokens.push(...parseInlineTokens(buffer))
+  }
+
+  return tokens
+}
+
+function parseInlineTokens(text: string): FormatToken[] {
+  const result: FormatToken[] = []
+  let remaining = text
+
+  while (remaining.length > 0) {
+    const boldMatch = remaining.match(/^\*([^*]+)\*/)
+    if (boldMatch) {
+      result.push({ type: 'bold', content: boldMatch[1] })
+      remaining = remaining.slice(boldMatch[0].length)
+      continue
+    }
+    const italicMatch = remaining.match(/^_([^_]+)_/)
+    if (italicMatch) {
+      result.push({ type: 'italic', content: italicMatch[1] })
+      remaining = remaining.slice(italicMatch[0].length)
+      continue
+    }
+    const strikeMatch = remaining.match(/^~([^~]+)~/)
+    if (strikeMatch) {
+      result.push({ type: 'strikethrough', content: strikeMatch[1] })
+      remaining = remaining.slice(strikeMatch[0].length)
+      continue
+    }
+
+    const nextSpecial = remaining.search(/[*_~`]/)
+    if (nextSpecial === -1) {
+      if (remaining) result.push({ type: 'text', content: remaining })
+      break
+    }
+    if (nextSpecial > 0) {
+      result.push({ type: 'text', content: remaining.slice(0, nextSpecial) })
+    }
+    remaining = remaining.slice(nextSpecial)
+  }
+
+  return result
+}
+
+export function parseWhatsAppFormatting(text: string): ReactNode[] {
+  const tokens = tokenize(text)
+
+  return tokens.map((token, index) => {
+    switch (token.type) {
+      case 'bold':
+        return <strong key={index}>{token.content}</strong>
+      case 'italic':
+        return <em key={index}>{token.content}</em>
+      case 'strikethrough':
+        return <del key={index}>{token.content}</del>
+      case 'monospace':
+        return <code key={index} className="bg-gray-100 px-1 py-0.5 rounded text-sm">{token.content}</code>
+      case 'codeblock':
+        return (
+          <pre key={index} className="bg-gray-100 p-2 rounded text-sm overflow-x-auto my-1">
+            <code>{token.content}</code>
+          </pre>
+        )
+      default:
+        return <span key={index}>{token.content}</span>
+    }
+  })
+}
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+function unescapeHtml(text: string): string {
+  return text.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&nbsp;/g, ' ')
+}
+
+// Marcador da Private Use Area do Unicode — praticamente impossível de colidir com
+// texto real de mensagem, ao contrário de um sentinela em ASCII (ex: dígitos soltos).
+const CODE_TOKEN_MARK = String.fromCharCode(0xe000)
+const CODE_TOKEN_REGEX = new RegExp(`${CODE_TOKEN_MARK}(\\d+)${CODE_TOKEN_MARK}`, 'g')
+
+// waToHTML/htmlToWA formam um par round-trip: todo texto que sai de waToHTML deve
+// reconstruir exatamente o original ao passar por htmlToWA (inclusive blocos de
+// código multi-linha, que exigem distinguir ``` de ` via atributo data-wa).
+export function waToHTML(text: string): string {
+  if (!text) return ''
+
+  const codeTokens: { type: 'block' | 'inline'; content: string }[] = []
+  let working = text.replace(/```([\s\S]*?)```/g, (_match, content: string) => {
+    codeTokens.push({ type: 'block', content })
+    return `${CODE_TOKEN_MARK}${codeTokens.length - 1}${CODE_TOKEN_MARK}`
+  })
+  working = working.replace(/`([^`\n]+)`/g, (_match, content: string) => {
+    codeTokens.push({ type: 'inline', content })
+    return `${CODE_TOKEN_MARK}${codeTokens.length - 1}${CODE_TOKEN_MARK}`
+  })
+
+  let html = escapeHtml(working)
+  html = html.replace(/\*([^*\n]+)\*/g, '<strong>$1</strong>')
+  html = html.replace(/_([^_\n]+)_/g, '<em>$1</em>')
+  html = html.replace(/~([^~\n]+)~/g, '<del>$1</del>')
+  html = html.replace(/\n/g, '<br>')
+
+  html = html.replace(CODE_TOKEN_REGEX, (_match, indexStr: string) => {
+    const token = codeTokens[Number(indexStr)]
+    const escaped = escapeHtml(token.content)
+    if (token.type === 'block') {
+      return `<code data-wa="block" class="block bg-black/5 dark:bg-white/10 rounded px-1.5 py-0.5 font-mono text-sm whitespace-pre-wrap">${escaped.replace(/\n/g, '<br>')}</code>`
+    }
+    return `<code data-wa="inline" class="bg-black/5 dark:bg-white/10 rounded px-0.5 font-mono text-sm">${escaped}</code>`
+  })
+
+  return html
+}
+
+export function htmlToWA(html: string): string {
+  if (!html) return ''
+
+  let text = html
+  text = text.replace(/<code data-wa="block"[^>]*>([\s\S]*?)<\/code>/gi, (_match, inner: string) => (
+    `\`\`\`${unescapeHtml(inner.replace(/<br\s*\/?>/gi, '\n'))}\`\`\``
+  ))
+  text = text.replace(/<code data-wa="inline"[^>]*>([\s\S]*?)<\/code>/gi, (_match, inner: string) => (
+    `\`${unescapeHtml(inner)}\``
+  ))
+
+  text = text
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<div>/gi, '\n')
+    .replace(/<\/div>/gi, '')
+    .replace(/<\/p>/gi, '\n')
+    .replace(/<p[^>]*>/gi, '')
+
+  text = text.replace(/<strong>(.*?)<\/strong>/gi, '*$1*')
+  text = text.replace(/<b>(.*?)<\/b>/gi, '*$1*')
+  text = text.replace(/<em>(.*?)<\/em>/gi, '_$1_')
+  text = text.replace(/<i>(.*?)<\/i>/gi, '_$1_')
+  text = text.replace(/<del>(.*?)<\/del>/gi, '~$1~')
+  text = text.replace(/<s>(.*?)<\/s>/gi, '~$1~')
+  // Compat: HTML sem os marcadores data-wa (ex: vindo de outro editor) ainda vira código inline.
+  text = text.replace(/<code[^>]*>(.*?)<\/code>/gi, '`$1`')
+
+  text = text.replace(/<[^>]+>/g, '')
+  text = unescapeHtml(text)
+  return text.trim()
+}
+
+// Variante inline para contextos de preview (ex: última mensagem numa lista) — sem
+// suporte a bloco de código nem quebras de linha, propositalmente mais simples.
+export function waToHTMLInline(text: string): string {
+  if (!text) return ''
+  return escapeHtml(text)
+    .replace(/\*([^*\n]+)\*/g, '<strong>$1</strong>')
+    .replace(/_([^_\n]+)_/g, '<em>$1</em>')
+    .replace(/~([^~\n]+)~/g, '<del>$1</del>')
+    .replace(/`([^`\n]+)`/g, '<code>$1</code>')
+}

package/src/providers/ConversationsProvider.tsx

@@ -0,0 +1,29 @@
+import { createContext, useContext, type ReactNode } from 'react'
+import type { ConversationsApi, SSEProvider } from './types'
+
+interface ConversationsContextValue {
+  api: ConversationsApi
+  sse: SSEProvider
+}
+
+const ConversationsContext = createContext<ConversationsContextValue | null>(null)
+
+export function ConversationsProvider({
+  api,
+  sse,
+  children,
+}: {
+  api: ConversationsApi
+  sse: SSEProvider
+  children: ReactNode
+}) {
+  return (
+    <ConversationsContext.Provider value={{ api, sse }}>
+      {children}
+    </ConversationsContext.Provider>
+  )
+}
+
+export function useConversations(): ConversationsContextValue | null {
+  return useContext(ConversationsContext)
+}

package/src/providers/types.ts

@@ -0,0 +1,54 @@
+import type { MessagePayload } from '../types'
+
+export interface ConversationsApi {
+  fetchMessages(conversationId: string, params?: { limit?: number; before?: string }): Promise<MessagePayload[]>
+  fetchConversations(params?: {
+    page?: number
+    limit?: number
+    waitingHuman?: boolean
+    search?: string
+  }): Promise<ConversationSummary[]>
+  sendMessage(conversationId: string, text: string): Promise<MessagePayload>
+  sendMedia(
+    conversationId: string,
+    data: { base64: string; mimeType: string; filename: string; caption?: string },
+  ): Promise<MessagePayload>
+  sendTemplate(
+    conversationId: string,
+    data: { templateName: string; languageCode?: string; bodyParams?: string[] },
+  ): Promise<void>
+  markRead(conversationId: string): Promise<void>
+  getContext(conversationId: string): Promise<Record<string, unknown>>
+  getDocuments(conversationId: string, params?: { search?: string; page?: number }): Promise<ConversationDocument[]>
+  getDocumentUrl(uploadId: string): Promise<string>
+  getMediaProxyUrl(mediaId: string): Promise<{ mimeType: string; data: string }>
+}
+
+export interface SSEProvider {
+  connectConversationStream(conversationId: string): EventSource
+  connectGlobalStream(): EventSource
+}
+
+export interface ConversationSummary {
+  id: string
+  whatsappNumber: string
+  clientName?: string
+  lastContent?: string
+  lastDirection?: 'inbound' | 'outbound'
+  lastAt: string
+  lastInboundAt: string | null
+  mode: 'bot' | 'human'
+  assignedUserId: string | null
+  waitingHuman: boolean
+  unread: number
+  currentState: string
+}
+
+export interface ConversationDocument {
+  id: string
+  filename: string
+  mimeType: string
+  sizeBytes: number
+  source: string
+  linkedAt: string
+}