@adatechnology/conversations-ui 0.1.0-rc.34 → 0.1.0-rc.35

package/src/preview/ConversationSimulatorClient.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ *
+ * Author: Anderson Filho <andersonfrfilho@gmail.com>
+ *
+ * Porta do simulador: o que a visão lado-cliente precisa saber fazer, sem canal no nome.
+ *
+ * O simulador nasceu falando WhatsApp — `PreviewWebhookClient`, payload assinado, mídia por
+ * `mediaId`. Só que a mesma casa atende pelo chat do próprio site, e simular ali não é uma segunda
+ * tela: é o mesmo painel, no mesmo lugar da conversa, com outro transporte. Sem esta porta cada
+ * canal novo viraria uma cópia da tela — e cópia de tela diverge, que é exatamente o que o
+ * `ConversationSimulatorPanel` existe para ter parado.
+ *
+ * O que é específico de canal fica no adaptador, nunca aqui:
+ * - **resposta de menu:** a Meta distingue `button_reply` de `list_reply`, e o roteador do fluxo lê
+ *   campos diferentes; o chat do site manda o rótulo como texto, que é literalmente o que o
+ *   visitante produz ao tocar no botão do widget. A porta entrega a seleção inteira e deixa cada
+ *   adaptador escolher a forma de fio.
+ * - **mídia:** a Meta entrega por REFERÊNCIA (sobe o arquivo primeiro, o webhook carrega o `id`); o
+ *   widget manda os BYTES no `FormData`. A porta trafega o `File` que a tela tem em mão — quem
+ *   tiver passo de upload faz o upload por dentro.
+ */
+
+import type { InteractiveSelection } from '../types'
+import type { PreviewUploadedMedia } from './createPreviewMediaUploader'
+import type { PreviewWebhookClient } from './createPreviewWebhookClient'
+
+/**
+ * Tipos de mídia que o cliente pode mandar de dentro do simulador.
+ *
+ * Subconjunto proposital do que a Meta aceita: `sticker` chega do aparelho, mas não há como
+ * escolher um no seletor de arquivo do navegador — oferecer o tipo aqui seria um caminho morto.
+ */
+export type SimulatorMediaKind = 'image' | 'video' | 'audio' | 'document'
+
+/** Os tipos que saem do seletor de arquivo. `audio` fica de fora: ele vem do microfone. */
+export const SIMULATOR_FILE_MEDIA_KINDS: readonly SimulatorMediaKind[] = ['image', 'video', 'document']
+
+/** Deriva o tipo de mídia a partir do MIME do arquivo escolhido. */
+export function mediaKindOf(mimeType: string): SimulatorMediaKind {
+  if (mimeType.startsWith('image/')) return 'image'
+  if (mimeType.startsWith('video/')) return 'video'
+  if (mimeType.startsWith('audio/')) return 'audio'
+  return 'document'
+}
+
+export type SendSimulatorMediaParams = {
+  readonly mediaKind: SimulatorMediaKind
+  /** O arquivo do disco ou o áudio recém-gravado. Referência × bytes é decisão do adaptador. */
+  readonly file: File
+  readonly mimeType?: string
+  readonly filename?: string
+  readonly caption?: string
+}
+
+export type ConversationSimulatorClient = {
+  sendText(text: string): Promise<void>
+  sendReply(selection: InteractiveSelection): Promise<void>
+  /**
+   * Ausente = este canal não recebe mídia do cliente, e o compositor não desenha clipe nem
+   * microfone. Melhor um botão que não existe do que um que falha ao ser tocado.
+   */
+  sendMedia?(params: SendSimulatorMediaParams): Promise<void>
+  /**
+   * Restringe o que `sendMedia` aceita. Ausente = todos os tipos.
+   *
+   * Existe porque canal com meia capacidade é comum: o chat do site sobe áudio (a API transcreve)
+   * mas não tem rota para imagem. Sem esta lista o clipe e o microfone apareciam juntos, e um dos
+   * dois falhava ao ser tocado.
+   */
+  readonly acceptedMediaKinds?: readonly SimulatorMediaKind[]
+}
+
+/** Responde se o compositor deve desenhar o affordance daquele tipo. */
+export function acceptsMediaKind(client: ConversationSimulatorClient, kind: SimulatorMediaKind): boolean {
+  if (!client.sendMedia) return false
+
+  return client.acceptedMediaKinds?.includes(kind) ?? true
+}
+
+export type ToSimulatorClientParams = {
+  readonly client: PreviewWebhookClient
+  /** Destino alternativo do upload. Sem isto, usa o do próprio `client`. */
+  readonly uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
+}
+
+/**
+ * Distingue a porta neutra do cliente WhatsApp legado, que continua aceito na prop.
+ *
+ * Leitura estrutural e não `instanceof`: os dois são objetos literais devolvidos por fábrica, e o
+ * host pode ter montado o seu à mão.
+ */
+export function isConversationSimulatorClient(
+  candidate: ConversationSimulatorClient | PreviewWebhookClient,
+): candidate is ConversationSimulatorClient {
+  return typeof (candidate as ConversationSimulatorClient).sendReply === 'function'
+}
+
+/**
+ * Adapta o cliente WhatsApp (webhook assinado ou ponte) para a porta neutra.
+ *
+ * O upload vive aqui dentro porque ele é uma etapa DO CANAL: no caminho da Meta a mídia precisa
+ * existir como `id` antes do webhook citá-la. Sem passo de upload disponível, `sendMedia` sai
+ * ausente — é o que mantém o clipe escondido em host que não montou destino para o arquivo, o
+ * comportamento que já existia antes desta porta.
+ */
+export function toConversationSimulatorClient({
+  client,
+  uploadMedia,
+}: ToSimulatorClientParams): ConversationSimulatorClient {
+  const upload = uploadMedia ?? client.uploadMedia
+
+  const base: ConversationSimulatorClient = {
+    sendText: (text) => client.sendText(text),
+    sendReply: (selection) => {
+      const reply = { id: selection.option.id, title: selection.option.title }
+      return selection.kind === 'button' ? client.sendButtonReply(reply) : client.sendListReply(reply)
+    },
+  }
+
+  if (!upload) return base
+
+  return {
+    ...base,
+    sendMedia: async ({ mediaKind, file, mimeType, filename, caption }) => {
+      const uploaded = await upload(file)
+      await client.sendMedia({
+        // O tipo sai do MIME que o upload devolveu quando ele existe: host que normaliza o formato
+        // (áudio gravado em `webm` que sobe como `ogg`) mudava de tipo, e a mídia chegava como
+        // documento.
+        mediaType: uploaded.mimeType ? mediaKindOf(uploaded.mimeType) : mediaKind,
+        mediaId: uploaded.mediaId,
+        mimeType: uploaded.mimeType ?? mimeType ?? file.type,
+        filename: uploaded.filename ?? filename ?? file.name,
+        ...(caption ? { caption } : {}),
+      })
+    },
+  }
+}

package/src/preview/ConversationSimulatorPanel.tsx

@@ -20,15 +20,20 @@
  *
  * O efeito de cada envio aparece na thread ao lado pelo mesmo stream que a inbox já assina — este
  * painel não abre conexão própria.
+ *
+ * A moldura é a mesma em todo canal — o que muda é o transporte, que entra pelo `client`, e duas
+ * frases do cabeçalho: dizer "entrega no webhook real" num chat de site descreveria um caminho que
+ * ali não existe, e "escreva como o cliente" num visitante anônimo nomeia alguém que ainda não é.
  */
 
 import type { ReactNode } from 'react'
 
+import { CONVERSATION_CHANNEL, DEFAULT_CONVERSATION_CHANNEL, type ConversationChannel } from '../conversationChannel'
 import { ConversationPreview, type ConversationPreviewProps } from './ConversationPreview'
 
 export type ConversationSimulatorPanelLabels = {
   readonly title: string
-  /** Complementa o telefone no subtítulo, explicando para onde a mensagem realmente vai. */
+  /** Complementa o identificador no subtítulo, explicando para onde a mensagem realmente vai. */
   readonly destinationHint: string
   readonly close: string
   readonly placeholder: string
@@ -41,12 +46,47 @@ export const DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS: ConversationSimulatorP
   placeholder: 'Escreva como o cliente…',
 }
 
+type ChannelWording = Pick<ConversationSimulatorPanelLabels, 'destinationHint' | 'placeholder'>
+
+/** Só o que muda de canal para canal; o resto continua vindo do default. */
+const SIMULATOR_PANEL_CHANNEL_WORDING: Readonly<Record<ConversationChannel, ChannelWording>> = {
+  [CONVERSATION_CHANNEL.WHATSAPP]: {
+    destinationHint: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.destinationHint,
+    placeholder: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.placeholder,
+  },
+  [CONVERSATION_CHANNEL.MESSENGER]: {
+    destinationHint: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.destinationHint,
+    placeholder: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.placeholder,
+  },
+  [CONVERSATION_CHANNEL.INSTAGRAM]: {
+    destinationHint: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.destinationHint,
+    placeholder: DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS.placeholder,
+  },
+  [CONVERSATION_CHANNEL.WEBCHAT]: {
+    destinationHint: 'entrega na API do chat do site',
+    placeholder: 'Escreva como o visitante…',
+  },
+}
+
+/** Rótulos do painel já resolvidos para o canal — útil para o host que monta o cabeçalho por fora. */
+export function simulatorPanelLabelsOf(channel: ConversationChannel | undefined): ConversationSimulatorPanelLabels {
+  return {
+    ...DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS,
+    ...SIMULATOR_PANEL_CHANNEL_WORDING[channel ?? DEFAULT_CONVERSATION_CHANNEL],
+  }
+}
+
 export type ConversationSimulatorPanelProps = Omit<ConversationPreviewProps, 'placeholder'> & {
   readonly onClose: () => void
+  /** Ausente = WhatsApp, que era o único canal antes desta prop existir. */
+  readonly channel?: ConversationChannel
   /**
-   * Telefone já formatado para leitura. É o host que formata: máscara de telefone é convenção
+   * Identificador do contato já formatado para leitura — telefone no WhatsApp, apelido no Instagram,
+   * "Visitante 3f9c21" no chat do site. É o host que formata: máscara de telefone é convenção
    * regional, e o pacote não tem como saber a do produto.
    */
+  readonly displayHandle?: string
+  /** @deprecated Use `displayHandle` — o simulador deixou de ser só telefone. */
   readonly displayNumber?: string
   readonly labels?: Partial<ConversationSimulatorPanelLabels>
   /** Ações extras no cabeçalho — roteiro automático, limpar conversa, trocar de contato. */
@@ -55,13 +95,15 @@ export type ConversationSimulatorPanelProps = Omit<ConversationPreviewProps, 'pl
 
 export function ConversationSimulatorPanel({
   onClose,
+  channel,
+  displayHandle,
   displayNumber,
   labels,
   headerActions,
   ...previewProps
 }: ConversationSimulatorPanelProps) {
-  const text = { ...DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS, ...labels }
-  const subtitle = [displayNumber ?? previewProps.conversationId, text.destinationHint].join(' · ')
+  const text = { ...simulatorPanelLabelsOf(channel), ...labels }
+  const subtitle = [displayHandle ?? displayNumber ?? previewProps.conversationId, text.destinationHint].join(' · ')
 
   return (
     <aside className="cv-simulator-panel" aria-label={text.title}>

package/src/preview/index.ts

@@ -25,9 +25,27 @@ export type { CreateMockSSEProviderParams } from './createMockSSEProvider'
 
 export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES, PREVIEW_DOCUMENTS } from './previewFixtures'
 
-export { ConversationSimulatorPanel, DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS } from './ConversationSimulatorPanel'
+export {
+  ConversationSimulatorPanel,
+  DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS,
+  simulatorPanelLabelsOf,
+} from './ConversationSimulatorPanel'
 export type { ConversationSimulatorPanelProps, ConversationSimulatorPanelLabels } from './ConversationSimulatorPanel'
 
+export {
+  acceptsMediaKind,
+  mediaKindOf,
+  isConversationSimulatorClient,
+  toConversationSimulatorClient,
+  SIMULATOR_FILE_MEDIA_KINDS,
+} from './ConversationSimulatorClient'
+export type {
+  ConversationSimulatorClient,
+  SendSimulatorMediaParams,
+  SimulatorMediaKind,
+  ToSimulatorClientParams,
+} from './ConversationSimulatorClient'
+
 export { ConversationPreview } from './ConversationPreview'
 export { mediaTypeOf } from './ConversationPreview'
 export type { ConversationPreviewProps, PreviewUploadedMedia } from './ConversationPreview'

package/src/workspace/ConversationsWorkspace.tsx

@@ -9,6 +9,11 @@
  * Customização: `labels` (texto e idioma), `renderFilters` / `renderBulkActions` /
  * `renderAboveTranscript` / `renderRow` (peças do produto), `contextEntriesOf` (vocabulário do
  * contexto), `extraUtilities` (ações no cabeçalho da conversa) e `simulator` (painel de preview).
+ *
+ * O simulador é montado aqui, e não pelo host: com `simulator.transports` o produto entrega só o
+ * transporte de cada canal e a moldura vem do pacote. Isso traz o `preview/` para o bundle de quem
+ * usa o workspace — o preço de a tela composta ser o padrão de consumo, que é o que impede a inbox
+ * de divergir entre produtos.
  */
 
 import { useEffect, useMemo, useState, type ReactNode } from 'react'
@@ -20,6 +25,14 @@ import type { ConversationHeaderUtility } from '../ConversationHeader'
 import type { QuickReply } from '../MessageComposer'
 import type { RichComposerVariable } from '../RichMessageComposer'
 import type { ConversationSummary } from '../providers/types'
+import { useConversations } from '../providers/ConversationsProvider'
+import { DEFAULT_CONVERSATION_CHANNEL, formatContactHandle, type ConversationChannel } from '../conversationChannel'
+import type { ConversationSimulatorClient } from '../preview/ConversationSimulatorClient'
+import type { PreviewUploadedMedia } from '../preview/createPreviewMediaUploader'
+import {
+  ConversationSimulatorPanel,
+  type ConversationSimulatorPanelLabels,
+} from '../preview/ConversationSimulatorPanel'
 import { BulkTemplateModal } from './BulkTemplateModal'
 import { ConversationPane } from './ConversationPane'
 import { ConversationsInboxList } from './ConversationsInboxList'
@@ -27,17 +40,49 @@ import { DEFAULT_CONVERSATIONS_WORKSPACE_LABELS, type ConversationsWorkspaceLabe
 import { useConversationsInbox, type UseConversationsInboxResult } from './useConversationsInbox'
 import { TooltipLayer } from '../Tooltip'
 
+export type SimulatorTransportParams = {
+  readonly conversationId: string
+  readonly channel: ConversationChannel
+  /** Identificador do contato no canal: telefone no WhatsApp, id de sessão no chat do site. */
+  readonly handle: string
+}
+
+/**
+ * Fábrica do transporte daquele canal.
+ *
+ * É o único ponto onde o host precisa saber de canal: o painel, a moldura e o comportamento são os
+ * mesmos em todos. No WhatsApp devolve o cliente-ponte (assinatura no servidor do host); no chat do
+ * site, o cliente das rotas do widget.
+ */
+export type SimulatorTransportFactory = (params: SimulatorTransportParams) => ConversationSimulatorClient
+
 export interface ConversationsWorkspaceSimulator {
   /**
-   * Desenha o painel do cliente. Fica com o host porque o simulador precisa da rota assinada no
-   * servidor DELE — e é o que mantém o `preview/` fora do bundle de quem não usa.
+   * Um transporte por canal — o workspace monta o painel com o da conversa selecionada.
+   *
+   * Canal sem transporte não desenha o botão: capacidade é opcional por ausência, e oferecer
+   * "simular" numa conversa que não tem como receber a mensagem é um botão que falha ao ser tocado.
+   */
+  readonly transports?: Partial<Record<ConversationChannel, SimulatorTransportFactory>>
+  /**
+   * Válvula de escape: o host desenha o painel inteiro. Tem precedência sobre `transports`.
+   *
+   * Era a única porta antes de `transports`, quando o simulador só falava WhatsApp e cada produto
+   * remontava a moldura — o que fez duas telas da mesma casa divergirem. Continua aceito para não
+   * quebrar quem já a usa.
    */
-  render(params: { conversationId: string; close: () => void }): ReactNode
+  render?(params: { conversationId: string; channel: ConversationChannel; close: () => void }): ReactNode
   /** Ausente = ligado. Serve para esconder fora de desenvolvimento sem condicionar o JSX. */
   readonly enabled?: boolean
   /** Ícone da biblioteca (lucide) no utilitário do cabeçalho. Ausente, entra o frasco de teste. */
   readonly icon?: ReactNode
   readonly label?: string
+  /** Vocabulário do painel. O que muda de canal (destino, placeholder) já vem resolvido. */
+  readonly labels?: Partial<ConversationSimulatorPanelLabels>
+  /** Destino do upload no canal que entrega mídia por referência (o caminho da Meta). */
+  readonly uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
+  /** Recarrega o transcript a cada N ms. Serve a host sem stream. */
+  readonly pollIntervalMs?: number
 }
 
 export interface ConversationsWorkspaceProps {
@@ -157,9 +202,23 @@ export function ConversationsWorkspace({
   }, [initialConversationId, initialWhatsappNumber, openedFromLink, inbox])
 
   const selected = inbox.selectedConversation
-  const simulatorEnabled = Boolean(simulator && (simulator.enabled ?? true))
+  const conversations = useConversations()
+  const selectedId = selected?.id
+  const channel = selected?.channel ?? DEFAULT_CONVERSATION_CHANNEL
+  const handle = selected ? (selected.contactId ?? selected.whatsappNumber) : ''
+  const transport = simulator?.transports?.[channel]
+  const simulatorEnabled = Boolean(
+    simulator && (simulator.enabled ?? true) && (simulator.render ?? transport),
+  )
   const showSimulator = simulatorEnabled && simulatorOpen && Boolean(selected)
 
+  // O transporte é recriado só quando a conversa (ou o canal dela) muda: identidade nova a cada
+  // render reiniciaria a leitura do transcript dentro do painel a cada digitação.
+  const simulatorClient = useMemo(
+    () => (transport && selectedId ? transport({ conversationId: selectedId, channel, handle }) : undefined),
+    [transport, selectedId, channel, handle],
+  )
+
   const paneUtilities = useMemo(() => {
     if (!selected) return undefined
     const fromProduct = extraUtilitiesFor?.(selected) ?? []
@@ -325,7 +384,25 @@ export function ConversationsWorkspace({
           // `min-height:0` junto do `min-width:0`: sem isso a linha do grid cresce com o conteúdo do
           // painel, o scroll interno nunca ativa e quem rola passa a ser a página inteira.
           <div className="cv-workspace-simulator">
-            {simulator?.render({ conversationId: selected.id, close: () => setSimulatorOpen(false) })}
+            {simulator?.render ? (
+              simulator.render({ conversationId: selected.id, channel, close: () => setSimulatorOpen(false) })
+            ) : simulatorClient && conversations ? (
+              // `key` pela conversa: trocar de contato sem remontar deixaria o transcript e o campo
+              // de texto do contato anterior na tela.
+              <ConversationSimulatorPanel
+                key={selected.id}
+                client={simulatorClient}
+                sse={conversations.sse}
+                conversationId={selected.id}
+                channel={channel}
+                displayHandle={formatContactHandle({ handle, channel })}
+                loadMessages={(conversationId) => conversations.api.fetchMessages(conversationId)}
+                onClose={() => setSimulatorOpen(false)}
+                {...(simulator?.labels ? { labels: simulator.labels } : {})}
+                {...(simulator?.uploadMedia ? { uploadMedia: simulator.uploadMedia } : {})}
+                {...(simulator?.pollIntervalMs ? { pollIntervalMs: simulator.pollIntervalMs } : {})}
+              />
+            ) : null}
           </div>
         ) : null}
       </div>

package/src/workspace/index.ts

@@ -1,5 +1,10 @@
 export { ConversationsWorkspace } from './ConversationsWorkspace'
-export type { ConversationsWorkspaceProps, ConversationsWorkspaceSimulator } from './ConversationsWorkspace'
+export type {
+  ConversationsWorkspaceProps,
+  ConversationsWorkspaceSimulator,
+  SimulatorTransportFactory,
+  SimulatorTransportParams,
+} from './ConversationsWorkspace'
 export { ConversationPane } from './ConversationPane'
 export type { ConversationPaneProps } from './ConversationPane'
 export { BulkTemplateModal } from './BulkTemplateModal'