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

package/src/conversationTranscript.test.ts

@@ -62,4 +62,61 @@ describe('buildTranscriptFilename', () => {
       `conversa-${NUMBER}-2026-07-27.txt`,
     )
   })
+
+  /**
+   * O áudio saía como `<audio>` no arquivo baixado. Um histórico onde o pedido do cliente aparece
+   * como marcador vazio é inútil justamente para o caso que motiva o download: auditoria e repasse.
+   */
+  it('escreve a transcrição do áudio no lugar do marcador de tipo', () => {
+    const texto = buildTranscriptText({
+      whatsappNumber: '5511999999999',
+      messages: [
+        {
+          id: '1',
+          type: 'audio',
+          direction: 'inbound',
+          sender: 'customer',
+          timestamp: '2026-07-31T12:00:00.000Z',
+          transcription: { status: 'done', text: 'quero dois quilos de arroz' },
+        },
+      ],
+    })
+
+    expect(texto).toContain('[áudio] quero dois quilos de arroz')
+    expect(texto).not.toContain('<audio>')
+  })
+
+  it('mantém o marcador de tipo quando o áudio não foi transcrito', () => {
+    const texto = buildTranscriptText({
+      whatsappNumber: '5511999999999',
+      messages: [
+        { id: '1', type: 'audio', direction: 'inbound', sender: 'customer', timestamp: '2026-07-31T12:00:00.000Z' },
+      ],
+    })
+
+    expect(texto).toContain('<audio>')
+  })
+
+  /**
+   * A rota de export do módulo devolve `createdAt`, não `sentAt` — quem mapeia esperando `sentAt`
+   * entrega `undefined` aqui, e o arquivo saía com "Invalid Date" em todas as linhas.
+   */
+  it('escreve "data indisponível" em vez de Invalid Date quando o horário não vem', () => {
+    const texto = buildTranscriptText({
+      whatsappNumber: '5511999999999',
+      messages: [
+        {
+          id: '1',
+          type: 'text',
+          direction: 'inbound',
+          sender: 'customer',
+          content: 'ola',
+          timestamp: undefined as unknown as string,
+        },
+      ],
+    })
+
+    expect(texto).toContain('data indisponível')
+    expect(texto).not.toContain('Invalid Date')
+  })
 })

package/src/conversationTranscript.ts

@@ -33,16 +33,41 @@ export function buildTranscriptText(params: BuildTranscriptTextParams): string {
   ]
 
   const lines = params.messages.map((message) => {
-    const stamp = new Date(message.timestamp).toLocaleString('pt-BR')
     const author = message.agentName ?? SENDER_LABEL[message.sender]
-    // Mídia sem legenda não tem texto nenhum; marcar o tipo evita uma linha vazia sem explicação.
-    const body = message.content ?? message.caption ?? `<${message.type}>`
-    return `[${stamp}] ${author}: ${body}`
+    return `[${formatStamp(message.timestamp)}] ${author}: ${bodyOf(message)}`
   })
 
   return [...header, ...lines].join('\n')
 }
 
+/**
+ * Corpo da linha no arquivo.
+ *
+ * Áudio transcrito entra com o TEXTO, não como `<audio>`. Quem baixa a conversa quer lê-la, e um
+ * histórico onde o pedido do cliente aparece como marcador vazio é inútil justamente para o caso que
+ * motiva o download: auditoria e repasse. O prefixo `[áudio]` fica na frente para a linha não passar
+ * por mensagem digitada — quem audita precisa saber que aquilo foi falado e transcrito por máquina.
+ */
+function bodyOf(message: MessagePayload): string {
+  const transcript = message.transcription?.text?.trim()
+  if (message.type === 'audio' && transcript) return `[áudio] ${transcript}`
+
+  // Mídia sem legenda não tem texto nenhum; marcar o tipo evita uma linha vazia sem explicação.
+  return message.content ?? message.caption ?? `<${message.type}>`
+}
+
+/**
+ * `Invalid Date` no arquivo é pior do que data ausente: parece dado corrompido e põe em dúvida o
+ * resto do transcript. E acontece de verdade — a rota de export do módulo devolve `createdAt`, não
+ * `sentAt`, então quem mapeia esperando `sentAt` recebe `undefined` aqui.
+ */
+function formatStamp(timestamp: string | undefined): string {
+  if (!timestamp) return 'data indisponível'
+
+  const parsed = new Date(timestamp)
+  return Number.isNaN(parsed.getTime()) ? 'data indisponível' : parsed.toLocaleString('pt-BR')
+}
+
 export function buildTranscriptFilename(whatsappNumber: string, generatedAt: Date): string {
   const stamp = generatedAt.toISOString().slice(0, 10)
   return `conversa-${whatsappNumber}-${stamp}.txt`

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

@@ -3,6 +3,7 @@ export { InteractiveMessage, DEFAULT_INTERACTIVE_MESSAGE_LABELS } from './Intera
 export { ConversationWallpaper } from './Wallpaper'
 export { ConversationLocalesProvider, useConversationLocales } from './ConversationLocalesProvider'
 export { AudioPlayer } from './AudioPlayer'
+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'
@@ -77,6 +78,7 @@ export { ConversationContextPanel, DEFAULT_CONVERSATION_CONTEXT_LABELS } from '.
 export type {
   ConversationContextPanelProps,
   ConversationContextEntry,
+  ConversationContextStatus,
   ConversationContextPanelLabels,
   ConversationContextPanelClassNames,
 } from './ConversationContextPanel'
@@ -108,6 +110,7 @@ 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,
@@ -118,6 +121,7 @@ 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'
@@ -132,6 +136,7 @@ export { formatTimestamp, formatFileSize, formatDateTime, isSameDay } from './li
 
 export type { MessagePayload, ConversationsUIConfig, ConversationsTheme, ConversationsFeatures } from './types'
 export type { InteractivePayload, InteractiveSection, InteractiveOption, InteractiveSelection } from './types'
+export type { MessageTranscription, TranscriptionStatus, TranscriptionMode } from './types'
 export type {
   ConversationsApi,
   SSEProvider,
@@ -152,6 +157,7 @@ export type { MessageBubbleProps } from './MessageBubble'
 export type { ConversationWallpaperProps } from './Wallpaper'
 export type { ConversationLocales, ConversationLocalesProviderProps } from './ConversationLocalesProvider'
 export type { AudioPlayerProps } from './AudioPlayer'
+export type { AudioTranscriptionProps } from './AudioTranscription'
 export type { EmojiPickerProps, EmojiPickerLabels } from './EmojiPicker'
 export type { EmojiEntry, EmojiCategory } from './emojiCatalog'
 export type { InteractiveMessageProps, InteractiveMessageLabels } from './InteractiveMessage'
@@ -181,6 +187,10 @@ export type {
   WhatsAppCreateTemplateFormLabels,
 } from './settings/WhatsAppCreateTemplateForm'
 export type { WelcomeFarewellFormProps, WelcomeFarewellFormLabels } from './settings/WelcomeFarewellForm'
+export type {
+  TranscriptionSettingsFormProps,
+  TranscriptionSettingsFormLabels,
+} from './settings/TranscriptionSettingsForm'
 export type {
   WhatsAppTemplatesSettingsProps,
   WhatsAppTemplatesSettingsLabels,
@@ -191,6 +201,7 @@ export type { TopicsFormProps, TopicItem, TopicsFormLabels } from './settings/To
 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'

package/src/preview/ConversationPreview.tsx

@@ -40,6 +40,7 @@ export type ConversationPreviewProps = {
    * inventa um endpoint de upload. Ausente, o compositor não oferece anexo nem gravação: melhor um
    * botão que não existe do que um que falha ao ser tocado.
    */
+  /** Destino alternativo do áudio gravado. Sem isto, usa o do próprio `client`. */
   uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
 }
 
@@ -246,11 +247,19 @@ export function ConversationPreview({
     }
   }
 
+  /**
+   * O cliente do preview sabe subir mídia sozinho; a prop é só para quem quer outro destino.
+   *
+   * Antes isto era `uploadMedia` puro, e o microfone só aparecia no produto que lembrasse de montar
+   * o upload — de onde veio a divergência entre dois simuladores da mesma casa.
+   */
+  const uploadFile = uploadMedia ?? client.uploadMedia
+
   async function handleAttach(file: File): Promise<void> {
-    if (!uploadMedia) return
+    if (!uploadFile) return
     setFailure(undefined)
     try {
-      const uploaded = await uploadMedia(file)
+      const uploaded = await uploadFile(file)
       await client.sendMedia({
         mediaType: mediaTypeOf(uploaded.mimeType ?? file.type),
         mediaId: uploaded.mediaId,
@@ -303,7 +312,7 @@ export function ConversationPreview({
 
       <MessageComposer
         onSend={(text) => void handleSend(text)}
-        onAttach={uploadMedia ? (file) => void handleAttach(file) : undefined}
+        onAttach={uploadFile ? (file) => void handleAttach(file) : undefined}
         /* Gravando, o campo diz o que falta fazer: o botão é um interruptor e o segundo toque é
            que envia — sem esse aviso o operador grava, não vê nada acontecer e conclui que o
            microfone está quebrado. */
@@ -311,7 +320,7 @@ export function ConversationPreview({
           isRecording ? 'Gravando… toque no quadrado para ouvir' : (placeholder ?? 'Escreva como o cliente…')
         }
         idleAction={
-          uploadMedia ? (
+          uploadFile ? (
             <AudioRecorderButton
               onRecorded={(file) => void handleAttach(file)}
               onFailure={(message) => setFailure(message)}

package/src/preview/ConversationSimulatorPanel.test.tsx

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ConversationSimulatorPanel, type ConversationSimulatorPanelProps } from './ConversationSimulatorPanel'
+import { createMockSSEProvider } from './createMockSSEProvider'
+import { createPreviewStore } from './previewStore'
+
+function markupOf(overrides: Partial<ConversationSimulatorPanelProps> = {}): string {
+  const store = createPreviewStore({ conversations: [], messages: {} })
+
+  return renderToStaticMarkup(
+    <ConversationSimulatorPanel
+      conversationId="5511900000042"
+      onClose={() => {}}
+      client={{ sendText: async () => {}, sendInteractiveReply: async () => {} } as never}
+      sse={createMockSSEProvider({ store })}
+      loadMessages={async () => []}
+      {...overrides}
+    />,
+  )
+}
+
+describe('ConversationSimulatorPanel', () => {
+  it('mostra o telefone formatado pelo host, e não o id cru', () => {
+    expect(markupOf({ displayNumber: '+55 (11) 90000-0042' })).toContain('+55 (11) 90000-0042')
+  })
+
+  it('cai no id da conversa quando o host não formata', () => {
+    expect(markupOf()).toContain('5511900000042')
+  })
+
+  it('avisa para onde a mensagem vai, para ninguém achar que é conversa de mentira', () => {
+    expect(markupOf()).toContain('entrega no webhook real')
+  })
+
+  it('dá nome acessível ao botão de fechar, que só tem ícone', () => {
+    expect(markupOf()).toContain('aria-label="Fechar simulador"')
+  })
+
+  it('aceita rótulos parciais do host sem exigir o conjunto inteiro', () => {
+    const markup = markupOf({ labels: { title: 'Testar fluxo' } })
+
+    expect(markup).toContain('Testar fluxo')
+    // O que não foi sobrescrito continua no default.
+    expect(markup).toContain('aria-label="Fechar simulador"')
+  })
+
+  it('renderiza ação extra do host no cabeçalho', () => {
+    expect(markupOf({ headerActions: <button type="button">Rodar roteiro</button> })).toContain('Rodar roteiro')
+  })
+
+  it('nomeia o próprio aside, para o leitor de tela distinguir do transcript ao lado', () => {
+    expect(markupOf()).toContain('aria-label="Simulador do cliente"')
+  })
+})

package/src/preview/ConversationSimulatorPanel.tsx

@@ -0,0 +1,89 @@
+/**
+ * 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>
+ *
+ * Painel lateral do simulador de cliente: a moldura em volta do `ConversationPreview`.
+ *
+ * Existe como componente do pacote porque cada produto tinha reescrito a mesma moldura —
+ * `<aside>`, cabeçalho com título e telefone, botão de fechar — e as cópias divergiram. Uma delas
+ * migrou para o cliente-ponte (assinatura no servidor) e a outra ficou assinando no navegador, com
+ * o app secret publicado no bundle. É o tipo de correção que precisa chegar a todo mundo de uma vez.
+ *
+ * Mora DENTRO da tela de conversas, e não numa aba própria, por um motivo prático: o token do
+ * atendente costuma viver em `sessionStorage`, que é por aba. Numa aba separada o simulador nascia
+ * sem sessão, o transcript nunca carregava, e o sintoma era "mandei e não aconteceu nada".
+ *
+ * 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.
+ */
+
+import type { ReactNode } from 'react'
+
+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. */
+  readonly destinationHint: string
+  readonly close: string
+  readonly placeholder: string
+}
+
+export const DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS: ConversationSimulatorPanelLabels = {
+  title: 'Simulador do cliente',
+  destinationHint: 'entrega no webhook real',
+  close: 'Fechar simulador',
+  placeholder: 'Escreva como o cliente…',
+}
+
+export type ConversationSimulatorPanelProps = Omit<ConversationPreviewProps, 'placeholder'> & {
+  readonly onClose: () => void
+  /**
+   * Telefone já formatado para leitura. É o host que formata: máscara de telefone é convenção
+   * regional, e o pacote não tem como saber a do produto.
+   */
+  readonly displayNumber?: string
+  readonly labels?: Partial<ConversationSimulatorPanelLabels>
+  /** Ações extras no cabeçalho — roteiro automático, limpar conversa, trocar de contato. */
+  readonly headerActions?: ReactNode
+}
+
+export function ConversationSimulatorPanel({
+  onClose,
+  displayNumber,
+  labels,
+  headerActions,
+  ...previewProps
+}: ConversationSimulatorPanelProps) {
+  const text = { ...DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS, ...labels }
+  const subtitle = [displayNumber ?? previewProps.conversationId, text.destinationHint].join(' · ')
+
+  return (
+    <aside className="cv-simulator-panel" aria-label={text.title}>
+      <header className="cv-simulator-panel__header">
+        <div className="cv-simulator-panel__heading">
+          <h2 className="cv-simulator-panel__title">{text.title}</h2>
+          <p className="cv-simulator-panel__subtitle">{subtitle}</p>
+        </div>
+        <div className="cv-simulator-panel__actions">
+          {headerActions}
+          <button type="button" onClick={onClose} title={text.close} aria-label={text.close} className="cv-simulator-panel__close">
+            {/* SVG inline em vez de lucide-react: o pacote não impõe biblioteca de ícone ao host. */}
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
+              <path d="M18 6 6 18M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+      </header>
+
+      <div className="cv-simulator-panel__body">
+        <ConversationPreview {...previewProps} placeholder={text.placeholder} />
+      </div>
+    </aside>
+  )
+}

package/src/preview/createPreviewBridgeClient.ts

@@ -16,7 +16,13 @@
  */
 
 import type { InboundMediaType, InteractiveReplyOption } from '@adatechnology/meta-whatsapp-contracts/testing'
-import type { PreviewWebhookClient, SendPreviewMediaParams } from './createPreviewWebhookClient'
+import {
+  createPreviewMediaPoster,
+  defaultMediaUploadUrl,
+  type PreviewWebhookClient,
+  type SendPreviewMediaParams,
+} from './createPreviewWebhookClient'
+import type { PreviewUploadedMedia } from './createPreviewMediaUploader'
 
 /**
  * Comando semântico entregue ao host. É deliberadamente o QUE o cliente fez, não o payload da Meta:
@@ -50,6 +56,18 @@ export type CreatePreviewBridgeClientParams = {
   readonly endpointUrl?: string
   readonly headers?: Readonly<Record<string, string>>
   readonly fetchImplementation?: typeof fetch
+  /**
+   * Rota que guarda o áudio gravado. Por padrão, `/v1/preview/media` na origem do `endpointUrl`.
+   *
+   * Aqui não há assinatura a calcular: a ponte existe justamente para não ter segredo no navegador,
+   * e a rota é protegida pela sessão do painel — os mesmos `headers` do comando valem para o upload.
+   */
+  readonly mediaUploadUrl?: string
+  /**
+   * Substitui o upload embutido. Necessário para host que só passa `sendCommand`: sem `endpointUrl`
+   * não há origem a derivar, e sem destino o gravador não é desenhado.
+   */
+  readonly uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
 }
 
 function buildFetchSender(params: CreatePreviewBridgeClientParams): SendPreviewInboundCommand {
@@ -72,9 +90,26 @@ function buildFetchSender(params: CreatePreviewBridgeClientParams): SendPreviewI
   }
 }
 
+/** Só existe quando há para onde mandar: rota explícita, ou origem herdada do `endpointUrl`. */
+function resolveBridgeUpload(
+  params: CreatePreviewBridgeClientParams,
+): ((file: File) => Promise<PreviewUploadedMedia>) | undefined {
+  if (params.uploadMedia) return params.uploadMedia
+
+  const url = params.mediaUploadUrl ?? (params.endpointUrl ? defaultMediaUploadUrl(params.endpointUrl) : undefined)
+  if (!url) return undefined
+
+  return createPreviewMediaPoster({
+    url,
+    ...(params.headers ? { headers: async () => params.headers ?? {} } : {}),
+    ...(params.fetchImplementation ? { fetchImplementation: params.fetchImplementation } : {}),
+  })
+}
+
 export function createPreviewBridgeClient(params: CreatePreviewBridgeClientParams): PreviewWebhookClient {
   const send = params.sendCommand ?? buildFetchSender(params)
   const from = params.from
+  const uploadMedia = resolveBridgeUpload(params)
 
   return {
     sendText: (text) => send({ kind: 'text', from, text }),
@@ -82,6 +117,7 @@ export function createPreviewBridgeClient(params: CreatePreviewBridgeClientParam
     sendListReply: (reply) => send({ kind: 'listReply', from, reply }),
     sendAudio: (mediaId) => send({ kind: 'audio', from, mediaId }),
     sendMedia: (media) => send({ kind: 'media', from, ...media }),
+    ...(uploadMedia ? { uploadMedia } : {}),
   }
 }
 

package/src/preview/createPreviewMediaUploader.ts

@@ -0,0 +1,82 @@
+/**
+ * Entrega ao simulador o `uploadMedia` que ele precisa para desenhar o microfone.
+ *
+ * O `ConversationPreview` esconde o gravador sem esta função, e com razão: microfone que grava sem
+ * ter onde guardar o arquivo faz o operador falar para o vazio. O que faltava era montar isto —
+ * lê o `File`, manda para a rota do host, devolve o `mediaId` prefixado que o webhook referencia.
+ *
+ * Fica no pacote porque a parte que erra é sempre a mesma em todo produto: converter o binário sem
+ * estourar a pilha e marcar o id com o prefixo que o backend reconhece. O que muda por produto é só
+ * a rota e o cliente HTTP — e é exatamente isso que entra por parâmetro.
+ */
+
+/**
+ * Do `contracts`, que este pacote já consome — não uma cópia.
+ *
+ * A convenção tem duas pontas (o front gera o id, o backend resolve) e a versão anterior disso vivia
+ * duplicada em dois pacotes de um produto, cada cópia com um comentário pedindo para não divergir.
+ * Contrato compartilhado é o que o `contracts` existe para guardar.
+ */
+export { PREVIEW_MEDIA_ID_PREFIX } from '@adatechnology/meta-whatsapp-contracts'
+import { toPreviewMediaId } from '@adatechnology/meta-whatsapp-contracts'
+
+export type PreviewUploadedMedia = {
+  readonly mediaId: string
+  readonly mimeType?: string
+  readonly filename?: string
+}
+
+export type PreviewMediaUploadRequest = {
+  readonly base64: string
+  readonly mimeType: string
+  readonly filename: string
+}
+
+export type CreatePreviewMediaUploaderParams = {
+  /**
+   * Envia o arquivo à rota do host e devolve o `uploadId` (sem prefixo) que o backend gerou.
+   *
+   * Recebe a função inteira, e não uma URL, porque autenticação varia: uma instalação assina com
+   * HMAC, outra manda token de admin, outra usa cookie de sessão. Pedir a URL obrigaria o pacote a
+   * escolher por elas.
+   */
+  readonly upload: (request: PreviewMediaUploadRequest) => Promise<{ uploadId: string }>
+  /** Nome usado quando o gravador entrega o áudio sem nome próprio. */
+  readonly fallbackFilename?: string
+  readonly fallbackMimeType?: string
+}
+
+/**
+ * Converte em blocos, não com `String.fromCharCode(...bytes)` de uma vez.
+ *
+ * Espalhar centenas de milhares de bytes como argumentos estoura o limite da engine — poucos segundos
+ * de áudio já chegam perto. O sintoma seria `RangeError` só nos arquivos grandes: passa no teste com
+ * um clipe curto e falha na primeira gravação de verdade.
+ */
+const CHUNK_SIZE = 8192
+
+async function fileToBase64(file: File): Promise<string> {
+  const bytes = new Uint8Array(await file.arrayBuffer())
+  let binary = ''
+  for (let offset = 0; offset < bytes.length; offset += CHUNK_SIZE) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + CHUNK_SIZE))
+  }
+  return btoa(binary)
+}
+
+export function createPreviewMediaUploader(
+  params: CreatePreviewMediaUploaderParams,
+): (file: File) => Promise<PreviewUploadedMedia> {
+  const fallbackMimeType = params.fallbackMimeType ?? 'audio/ogg'
+  const fallbackFilename = params.fallbackFilename ?? 'audio.ogg'
+
+  return async function uploadPreviewMedia(file: File): Promise<PreviewUploadedMedia> {
+    // Gravação de voz chega sem nome, e sem mime em navegador antigo.
+    const mimeType = file.type || fallbackMimeType
+    const filename = file.name || fallbackFilename
+
+    const { uploadId } = await params.upload({ base64: await fileToBase64(file), mimeType, filename })
+
+    return { mediaId: toPreviewMediaId(uploadId), mimeType, filename }
+  }
+}