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

package/src/providers/types.ts

@@ -1,28 +1,122 @@
 import type { MessagePayload } from '../types'
 import type { ConversationChannel } from '../conversationChannel'
 
+export interface ListConversationsParams {
+  page?: number
+  limit?: number
+  waitingHuman?: boolean
+  search?: string
+  /**
+   * Recortes que só o produto conhece (tipo de financiamento, carteira, campanha) repassados
+   * crus ao backend dele. É o que evita o vocabulário de uma vertical virar campo fixo aqui:
+   * o pacote transporta o filtro sem saber o que ele significa.
+   */
+  filters?: Record<string, string | undefined>
+}
+
+/**
+ * Página com o total, para a UI conseguir desenhar controles de paginação.
+ *
+ * `fetchConversations` devolve isto **ou** o array puro de antes: implementações existentes
+ * continuam válidas sem mudar uma linha, e quem precisa paginar passa a ter o total. Sem a união
+ * seria impossível saber se um retorno curto é a última página ou uma página cheia por acaso.
+ */
+export interface ConversationPage {
+  conversations: ConversationSummary[]
+  total: number
+}
+
+export interface ListDocumentsParams {
+  search?: string
+  page?: number
+  /** Tamanho da página. Sem ele, `page` sozinho não define fatia nenhuma. */
+  limit?: number
+  /** Origem do arquivo (`customer`, `agent`, `bot`…). O vocabulário é do host. */
+  source?: string
+  sortDirection?: 'asc' | 'desc'
+}
+
+export interface ConversationDocumentPage {
+  documents: ConversationDocument[]
+  total: number
+}
+
+/**
+ * Template disponível para envio a partir da inbox. Distinto do `WhatsAppTemplateSummary` de
+ * `settings/`, e de propósito: aquele serve ao formulário que **edita** template e carrega o que
+ * a edição precisa (`shortId`, `variableCount`); este serve a quem só vai **escolher um para
+ * enviar**, e pedir os campos de edição obrigaria todo host a produzi-los sem uso.
+ */
+export interface ConversationTemplate {
+  name: string
+  language: string
+  status: string
+  category?: string
+  bodyText?: string | null
+}
+
 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[]>
+  fetchConversations(params?: ListConversationsParams): Promise<ConversationSummary[] | ConversationPage>
   sendMessage(conversationId: string, text: string): Promise<MessagePayload>
   sendMedia(
     conversationId: string,
     data: { base64: string; mimeType: string; filename: string; caption?: string },
   ): Promise<MessagePayload>
+  /**
+   * `templateName` é opcional porque reabrir a janela é a operação, e escolher *qual* template a
+   * usa nem sempre é decisão da UI: backends que guardam um template padrão configurado só
+   * precisam do "reabra". Exigir o nome obrigaria toda inbox a listar templates antes de poder
+   * mandar o primeiro — e a listagem é `listTemplates?`, opcional.
+   */
   sendTemplate(
     conversationId: string,
-    data: { templateName: string; languageCode?: string; bodyParams?: 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>
+  getDocuments(
+    conversationId: string,
+    params?: ListDocumentsParams,
+  ): Promise<ConversationDocument[] | ConversationDocumentPage>
+  /**
+   * `disposition` decide entre abrir no navegador e baixar. É o backend que assina a URL e grava
+   * o `Content-Disposition` nela, então a escolha precisa viajar na chamada — depois de assinada
+   * não há como o cliente mudá-la. Ausente = o padrão do host.
+   */
+  getDocumentUrl(uploadId: string, disposition?: 'inline' | 'attachment'): Promise<string>
+  /**
+   * Baixa vários arquivos num zip único.
+   *
+   * **Opcional por capacidade:** montar zip exige o host LER os bytes do storage, o que nem toda
+   * instalação faz — as que só assinam URL não conseguem. Ausente, o painel esconde a seleção em
+   * lote em vez de oferecer um botão que falha.
+   */
+  downloadDocumentsArchive?(conversationId: string, uploadIds: readonly string[]): Promise<Blob>
   getMediaProxyUrl(mediaId: string): Promise<{ mimeType: string; data: string }>
+
+  /**
+   * Operações de atendimento humano. **Opcionais por capacidade, não por descuido:** nem toda
+   * inbox tem fila humana — um canal só-bot, ou um chat de site sem operador, não sabe o que é
+   * assumir conversa. Quem não implementa não ganha o botão, em vez de ganhar um botão que
+   * estoura no clique. Os hooks devolvem `undefined` para a ação ausente, e é isso que a UI
+   * consulta para decidir se desenha a afordância.
+   */
+  takeover?(conversationId: string): Promise<void>
+  release?(conversationId: string): Promise<void>
+  /** Encerra o atendimento. Despedida, se houver, é decisão do host — o pacote não a inventa. */
+  finalize?(conversationId: string): Promise<void>
+
+  markAllRead?(): Promise<void>
+  listTemplates?(): Promise<ConversationTemplate[]>
+
+  /**
+   * Transcrição completa gerada pelo servidor. Existe ao lado de `buildTranscriptText`, que monta
+   * a partir das mensagens já em memória: a tela costuma ter só a última página carregada, e
+   * exportar dali entregaria um recorte parcial com cara de histórico inteiro. Opcional porque
+   * nem todo backend expõe a rota — quem não tem continua usando o builder local.
+   */
+  exportTranscript?(conversationId: string): Promise<{ transcript: string; filename: string }>
 }
 
 /**
@@ -76,6 +170,13 @@ export interface ConversationSummary {
   waitingHuman: boolean
   unread: number
   currentState: string
+  /**
+   * Atributos que só o produto conhece e desenha (tipo de financiamento, carteira, campanha). É a
+   * contraparte de leitura do `filters` de `ListConversationsParams`: o pacote transporta e nunca
+   * interpreta. Sem isto, exibir um selo próprio na linha exigiria o host manter uma segunda
+   * consulta paralela à mesma listagem — a implementação duplicada que o pacote existe para evitar.
+   */
+  attributes?: Record<string, string | undefined>
 }
 
 export interface ConversationDocument {

package/src/useWaitingNotifications.ts

@@ -1,64 +1,109 @@
 import { useState, useEffect, useRef, useCallback } from 'react'
 import { useConversations } from './providers/ConversationsProvider'
-import type { ConversationSummary } from './providers/types'
+import { conversationsOf } from './lib/paginated'
+import type { ConversationSummary, ListConversationsParams } from './providers/types'
 
-interface UseWaitingNotificationsResult {
+const DEFAULT_POLL_INTERVAL_MS = 10_000
+const DEFAULT_LIMIT = 50
+
+export interface UseWaitingNotificationsLabels {
+  /** Título da notificação do sistema. Recebe a conversa para o host escolher nome × número. */
+  title: (conversation: ConversationSummary) => string
+  body: (conversation: ConversationSummary) => string
+}
+
+export interface UseWaitingNotificationsParams {
+  /**
+   * Repassado cru ao `fetchConversations`. É o que permite filtrar não lidas **no servidor** em
+   * vez de baixar a lista inteira e contar no cliente: um painel com milhares de conversas não
+   * pode paginar 50 por vez atrás de quem tem `unread > 0`.
+   */
+  readonly params?: ListConversationsParams
+  readonly intervalMs?: number
+  /** Desliga o polling sem desmontar quem chama — útil com a aba em segundo plano. */
+  readonly enabled?: boolean
+  readonly icon?: string
+  readonly labels?: Partial<UseWaitingNotificationsLabels>
+}
+
+export interface UseWaitingNotificationsResult {
   unreadCount: number
   conversations: ConversationSummary[]
+  /**
+   * Releitura sob demanda. Existe porque o polling é o piso, não o mecanismo: quem já recebe SSE
+   * ou acabou de marcar tudo como lido sabe da mudança antes do próximo tick, e esperar 10s para
+   * o contador acompanhar faz a interface parecer travada.
+   */
+  refresh: () => Promise<void>
+}
+
+const DEFAULT_LABELS: UseWaitingNotificationsLabels = {
+  title: (conversation) => conversation.clientName ?? conversation.whatsappNumber,
+  body: (conversation) => conversation.lastContent ?? 'Nova mensagem',
 }
 
-export function useWaitingNotifications(): UseWaitingNotificationsResult {
-  const conversationsCtx = useConversations()
+export function useWaitingNotifications(params?: UseWaitingNotificationsParams): UseWaitingNotificationsResult {
+  const conversationsContext = useConversations()
   const [conversations, setConversations] = useState<ConversationSummary[]>([])
   const previousUnreadMap = useRef<Map<string, number>>(new Map())
   const notifiedIds = useRef<Set<string>>(new Set())
+  // Trava de reentrância: com a rede lenta, o tick de 10s dispara sobre a busca anterior ainda em
+  // voo, e duas respostas fora de ordem fazem o contador oscilar e a notificação repetir.
+  const isPollingRef = useRef(false)
+
+  const isEnabled = params?.enabled ?? true
+  const intervalMs = params?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS
+  const icon = params?.icon
+  const listParams = params?.params
+  const labelTitle = params?.labels?.title ?? DEFAULT_LABELS.title
+  const labelBody = params?.labels?.body ?? DEFAULT_LABELS.body
 
-  const pollConversations = useCallback(async () => {
-    if (!conversationsCtx) return
+  const refresh = useCallback(async () => {
+    if (!conversationsContext || isPollingRef.current) return
+    isPollingRef.current = true
 
     try {
-      const result = await conversationsCtx.api.fetchConversations({ limit: 50 })
+      const result = conversationsOf(
+        await conversationsContext.api.fetchConversations({ limit: DEFAULT_LIMIT, ...listParams }),
+      )
       setConversations(result)
 
       const currentMap = new Map<string, number>()
-      for (const conv of result) {
-        currentMap.set(conv.id, conv.unread)
-      }
+      for (const conversation of result) currentMap.set(conversation.id, conversation.unread)
 
-      for (const conv of result) {
-        if (conv.unread <= 0) continue
+      for (const conversation of result) {
+        if (conversation.unread <= 0) continue
 
-        const prev = previousUnreadMap.current.get(conv.id) ?? 0
+        const previousUnread = previousUnreadMap.current.get(conversation.id) ?? 0
+        if (conversation.unread <= previousUnread || notifiedIds.current.has(conversation.id)) continue
 
-        if (conv.unread > prev && !notifiedIds.current.has(conv.id)) {
-          notifiedIds.current.add(conv.id)
-
-          if (typeof window !== 'undefined' && 'Notification' in window && Notification.permission === 'granted') {
-            const title = conv.clientName ?? conv.whatsappNumber
-            const body = conv.lastContent ?? 'Nova mensagem'
-            new Notification(title, { body, icon: '/favicon.ico' })
-          }
+        notifiedIds.current.add(conversation.id)
+        if (typeof window !== 'undefined' && 'Notification' in window && Notification.permission === 'granted') {
+          new Notification(labelTitle(conversation), { body: labelBody(conversation), ...(icon ? { icon } : {}) })
         }
       }
 
       previousUnreadMap.current = currentMap
     } catch {
-      // Silently ignore polling errors
+      // Contador de badge não interrompe o atendimento: uma falha de rede some no próximo tick.
+    } finally {
+      isPollingRef.current = false
     }
-  }, [conversationsCtx])
+  }, [conversationsContext, listParams, icon, labelTitle, labelBody])
 
   useEffect(() => {
+    if (!isEnabled) return
+
     if (typeof window !== 'undefined' && 'Notification' in window && Notification.permission === 'default') {
       Notification.requestPermission()
     }
 
-    pollConversations()
-
-    const interval = setInterval(pollConversations, 10_000)
+    void refresh()
+    const interval = setInterval(() => void refresh(), intervalMs)
     return () => clearInterval(interval)
-  }, [pollConversations])
+  }, [refresh, isEnabled, intervalMs])
 
-  const unreadCount = conversations.reduce((sum, conv) => sum + conv.unread, 0)
+  const unreadCount = conversations.reduce((sum, conversation) => sum + conversation.unread, 0)
 
-  return { unreadCount, conversations }
+  return { unreadCount, conversations, refresh }
 }