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

package/src/preview/createMockConversationsApi.ts

@@ -8,13 +8,18 @@
  */
 
 import type { MessagePayload } from '../types'
-import type { ConversationDocument, ConversationsApi, ConversationSummary } from '../providers/types'
+import type {
+  CompanyDocumentPage,
+  ConversationDocumentPage,
+  ConversationPage,
+  ConversationTemplate,
+  ConversationsApi,
+  ListConversationsParams,
+} from '../providers/types'
+import { PREVIEW_DOCUMENTS } from './previewFixtures'
+import { previewFileBase64, previewFileUrl } from './previewMediaSource'
 import type { PreviewStore } from './previewStore'
 
-// PNG 1x1 transparente: o suficiente para o MediaRenderer ter algo válido para desenhar.
-const PREVIEW_IMAGE_BASE64 =
-  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYGD4DwABBAEAX+XyEgAAAABJRU5ErkJggg=='
-
 export type CreateMockConversationsApiParams = {
   readonly store: PreviewStore
   readonly latencyMs?: number
@@ -23,7 +28,24 @@ export type CreateMockConversationsApiParams = {
 
 const DEFAULT_LATENCY_MS = 120
 
-export function createMockConversationsApi(params: CreateMockConversationsApiParams): ConversationsApi {
+const PREVIEW_AGENT_ID = 'preview-agent'
+
+const PREVIEW_TEMPLATES: readonly ConversationTemplate[] = [
+  { name: 'retomada_atendimento', language: 'pt_BR', status: 'APPROVED', category: 'UTILITY' },
+  { name: 'lembrete_documentos', language: 'pt_BR', status: 'APPROVED', category: 'UTILITY' },
+  { name: 'promocao_taxa', language: 'pt_BR', status: 'PENDING', category: 'MARKETING' },
+]
+
+/**
+ * O mock satisfaz `ConversationsApi`, mas com o retorno de `fetchConversations` ESTREITADO para a
+ * forma paginada. Sem isto o contrato — que aceita array ou página — obrigaria todo consumidor do
+ * preview a desempacotar uma união que aqui nunca varia.
+ */
+export type MockConversationsApi = Omit<ConversationsApi, 'fetchConversations'> & {
+  fetchConversations(params?: ListConversationsParams): Promise<ConversationPage>
+}
+
+export function createMockConversationsApi(params: CreateMockConversationsApiParams): MockConversationsApi {
   const latencyMs = params.latencyMs ?? DEFAULT_LATENCY_MS
 
   async function withLatency<TResult>(produce: () => TResult): Promise<TResult> {
@@ -32,7 +54,10 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
   }
 
   return {
-    fetchConversations(fetchParams): Promise<ConversationSummary[]> {
+    // Devolve a forma paginada, não o array puro: é a que o contrato passou a oferecer e a que
+    // permite o preview desenhar controles de página. O total é contado ANTES do corte — depois
+    // dele seria sempre o tamanho da página, e a paginação nunca sairia da primeira.
+    fetchConversations(fetchParams): Promise<ConversationPage> {
       return withLatency(() => {
         const conversations = params.store.listConversations({
           waitingHuman: fetchParams?.waitingHuman,
@@ -41,7 +66,10 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
 
         const limit = fetchParams?.limit ?? conversations.length
         const page = fetchParams?.page ?? 1
-        return conversations.slice((page - 1) * limit, page * limit)
+        return {
+          conversations: conversations.slice((page - 1) * limit, page * limit),
+          total: conversations.length,
+        }
       })
     },
 
@@ -74,7 +102,9 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
       return withLatency(() => {
         params.store.appendMessage({
           conversationId,
-          content: `[template] ${data.templateName}`,
+          // Sem nome, o host está pedindo o template padrão do backend — o mock representa isso
+          // pelo que o atendente veria, não por um nome inventado.
+          content: `[template] ${data.templateName ?? PREVIEW_TEMPLATES[0]?.name ?? 'padrao'}`,
           direction: 'outbound',
           sender: 'agent',
         })
@@ -96,16 +126,146 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
       })
     },
 
-    getDocuments(): Promise<ConversationDocument[]> {
-      return withLatency(() => [])
+    /**
+     * Espelha o backend em busca, filtro de origem, ordenação E paginação. Mock que ignora params
+     * faz o painel parecer quebrado aqui e, pior, esconde o caso em que o backend também os ignora
+     * — foi exatamente assim que o filtro de origem passou a existir só no contrato.
+     */
+    getDocuments(conversationId, documentParams): Promise<ConversationDocumentPage> {
+      return withLatency(() => {
+        let documents = [...(PREVIEW_DOCUMENTS[conversationId] ?? [])]
+
+        const search = documentParams?.search?.trim().toLowerCase()
+        if (search) {
+          documents = documents.filter((document) => document.filename.toLowerCase().includes(search))
+        }
+
+        // 'team' agrupa agent + bot, como o painel apresenta.
+        const source = documentParams?.source
+        if (source === 'team') {
+          documents = documents.filter((document) => document.source === 'agent' || document.source === 'bot')
+        } else if (source) {
+          documents = documents.filter((document) => document.source === source)
+        }
+
+        documents.sort((left, right) =>
+          documentParams?.sortDirection === 'asc'
+            ? left.linkedAt.localeCompare(right.linkedAt)
+            : right.linkedAt.localeCompare(left.linkedAt),
+        )
+
+        // Total contado ANTES do corte — depois seria sempre o tamanho da página, e a paginação
+        // nunca sairia da primeira.
+        const total = documents.length
+        const limit = documentParams?.limit ?? total
+        const page = documentParams?.page ?? 1
+
+        return { documents: documents.slice((page - 1) * limit, page * limit), total }
+      })
+    },
+
+    /**
+     * Zip de mentira: um texto listando o que entraria. Basta para exercitar seleção, botão e o
+     * caminho de download no preview, sem arrastar uma lib de compactação para o pacote.
+     */
+    downloadDocumentsArchive(conversationId, uploadIds): Promise<Blob> {
+      return withLatency(() => {
+        const known = PREVIEW_DOCUMENTS[conversationId] ?? []
+        const names = uploadIds.map((id) => known.find((document) => document.id === id)?.filename ?? id)
+        return new Blob([`preview: ${names.length} arquivo(s)\n${names.join('\n')}`], { type: 'application/zip' })
+      })
     },
 
-    getDocumentUrl(): Promise<string> {
-      return withLatency(() => `data:image/png;base64,${PREVIEW_IMAGE_BASE64}`)
+    /** Junta as bibliotecas de todas as conversas do fixture, com a origem de cada arquivo. */
+    getAllDocuments(documentParams): Promise<CompanyDocumentPage> {
+      return withLatency(() => {
+        let all = Object.entries(PREVIEW_DOCUMENTS).flatMap(([conversationId, docs]) =>
+          docs.map((document) => ({ ...document, conversationId })),
+        )
+
+        // Mesma regra do backend (`companyDocumentSearch`): o termo casa nome do arquivo OU
+        // telefone da conversa, e o telefone só pelos dígitos — o preview mostra o número
+        // formatado, então é assim que o atendente vai colá-lo na busca.
+        const search = documentParams?.search?.trim().toLowerCase()
+        if (search) {
+          const digits = search.replace(/\D/g, '')
+          all = all.filter(
+            (document) =>
+              document.filename.toLowerCase().includes(search) ||
+              (digits !== '' && document.conversationId.includes(digits)),
+          )
+        }
+
+        const source = documentParams?.source
+        if (source === 'team') {
+          all = all.filter((document) => document.source === 'agent' || document.source === 'bot')
+        } else if (source) {
+          all = all.filter((document) => document.source === source)
+        }
+
+        all.sort((left, right) =>
+          documentParams?.sortDirection === 'asc'
+            ? left.linkedAt.localeCompare(right.linkedAt)
+            : right.linkedAt.localeCompare(left.linkedAt),
+        )
+
+        const total = all.length
+        const limit = documentParams?.limit ?? total
+        const page = documentParams?.page ?? 1
+        return { documents: all.slice((page - 1) * limit, page * limit), total }
+      })
+    },
+
+    // Devolve os bytes DO TIPO do documento, não uma imagem para tudo: antes, abrir um PDF entregava
+    // um PNG rotulado `application/pdf` e o leitor recusava o arquivo. O `uploadId` é a única pista
+    // que o contrato dá, então o tipo vem da própria biblioteca.
+    getDocumentUrl(uploadId): Promise<string> {
+      return withLatency(() => {
+        const found = Object.values(PREVIEW_DOCUMENTS)
+          .flat()
+          .find((document) => document.id === uploadId)
+        return previewFileUrl(found?.mimeType, found?.filename)
+      })
+    },
+
+    // Caminho da mídia ainda não ingerida: o backend busca na Meta e devolve base64. Resolve pelo
+    // id para a bolha receber os bytes DO TIPO dela — devolvendo um PNG para todo id, vídeo e áudio
+    // apareciam quebrados na thread mesmo havendo amostra válida do formato.
+    getMediaProxyUrl(mediaId): Promise<{ mimeType: string; data: string }> {
+      return withLatency(() => {
+        const found = Object.values(PREVIEW_DOCUMENTS)
+          .flat()
+          .find((document) => document.id === `preview/inbound/${mediaId}`)
+        return previewFileBase64(found?.mimeType, found?.filename)
+      })
+    },
+
+    takeover(conversationId): Promise<void> {
+      return withLatency(() =>
+        params.store.setMode({ conversationId, mode: 'human', assignedUserId: PREVIEW_AGENT_ID }),
+      )
+    },
+
+    release(conversationId): Promise<void> {
+      return withLatency(() => params.store.setMode({ conversationId, mode: 'bot' }))
+    },
+
+    // Encerrar devolve ao bot como o release, e é de propósito: a diferença entre os dois é a
+    // despedida, que o host manda antes de chamar aqui. O mock não a inventa.
+    finalize(conversationId): Promise<void> {
+      return withLatency(() => params.store.setMode({ conversationId, mode: 'bot' }))
+    },
+
+    markAllRead(): Promise<void> {
+      return withLatency(() => {
+        for (const conversation of params.store.listConversations()) {
+          params.store.markRead(conversation.id)
+        }
+      })
     },
 
-    getMediaProxyUrl(): Promise<{ mimeType: string; data: string }> {
-      return withLatency(() => ({ mimeType: 'image/png', data: PREVIEW_IMAGE_BASE64 }))
+    listTemplates(): Promise<ConversationTemplate[]> {
+      return withLatency(() => [...PREVIEW_TEMPLATES])
     },
   }
 }

package/src/preview/createPreviewBridgeClient.test.ts

@@ -0,0 +1,92 @@
+/**
+ * O que estes testes protegem é a propriedade de segurança da ponte: nenhum caminho pode voltar a
+ * exigir segredo no navegador, e o corpo enviado tem que ser a INTENÇÃO — se um refactor passar a
+ * mandar payload da Meta montado no cliente, a rota do host vira injetor de webhook arbitrário.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { createPreviewBridgeClient, PreviewBridgeRejectedError } from './createPreviewBridgeClient'
+import type { PreviewInboundCommand } from './createPreviewBridgeClient'
+
+const FROM = '5511999999999'
+
+function createRecordingClient() {
+  const commands: PreviewInboundCommand[] = []
+  const client = createPreviewBridgeClient({
+    from: FROM,
+    sendCommand: async (command) => {
+      commands.push(command)
+    },
+  })
+  return { client, commands }
+}
+
+describe('createPreviewBridgeClient', () => {
+  it('entrega a intenção do cliente, carimbando o remetente em cada comando', async () => {
+    const { client, commands } = createRecordingClient()
+
+    await client.sendText('quero simular')
+    await client.sendButtonReply({ id: 'hab_pronto', title: 'Imóvel pronto' })
+    await client.sendListReply({ id: 'faixa_2', title: 'Faixa 2' })
+    await client.sendAudio('media-1')
+    await client.sendMedia({ mediaType: 'document', mediaId: 'media-2', filename: 'rg.pdf' })
+
+    expect(commands).toEqual([
+      { kind: 'text', from: FROM, text: 'quero simular' },
+      { kind: 'buttonReply', from: FROM, reply: { id: 'hab_pronto', title: 'Imóvel pronto' } },
+      { kind: 'listReply', from: FROM, reply: { id: 'faixa_2', title: 'Faixa 2' } },
+      { kind: 'audio', from: FROM, mediaId: 'media-1' },
+      { kind: 'media', from: FROM, mediaType: 'document', mediaId: 'media-2', filename: 'rg.pdf' },
+    ])
+  })
+
+  it('nunca embute assinatura nem segredo no que sai do navegador', async () => {
+    const { client, commands } = createRecordingClient()
+
+    await client.sendText('oi')
+
+    const serialized = JSON.stringify(commands[0])
+    expect(serialized).not.toMatch(/sha256=/)
+    expect(serialized).not.toMatch(/secret/i)
+    expect(commands[0]).not.toHaveProperty('entry')
+  })
+
+  it('posta no endpoint do host com os headers de sessão que o host injeta', async () => {
+    const calls: Array<{ url: string; init: RequestInit }> = []
+    const client = createPreviewBridgeClient({
+      from: FROM,
+      endpointUrl: 'https://host.test/api/conversations/preview/inbound',
+      headers: { authorization: 'Bearer token-do-painel' },
+      fetchImplementation: (async (url: string, init: RequestInit) => {
+        calls.push({ url, init })
+        return { ok: true } as Response
+      }) as unknown as typeof fetch,
+    })
+
+    await client.sendText('oi')
+
+    expect(calls[0]?.url).toBe('https://host.test/api/conversations/preview/inbound')
+    expect(calls[0]?.init.method).toBe('POST')
+    expect(calls[0]?.init.headers).toMatchObject({
+      'content-type': 'application/json',
+      authorization: 'Bearer token-do-painel',
+    })
+    expect(JSON.parse(String(calls[0]?.init.body))).toEqual({ kind: 'text', from: FROM, text: 'oi' })
+  })
+
+  it('converte recusa do host em erro tipado, para o painel poder mostrar o motivo', async () => {
+    const client = createPreviewBridgeClient({
+      from: FROM,
+      endpointUrl: 'https://host.test/preview',
+      fetchImplementation: (async () => ({ ok: false, status: 403 }) as Response) as unknown as typeof fetch,
+    })
+
+    await expect(client.sendText('oi')).rejects.toBeInstanceOf(PreviewBridgeRejectedError)
+    await expect(client.sendText('oi')).rejects.toThrow(/403/)
+  })
+
+  it('recusa configuração sem forma de entregar, em vez de falhar só no primeiro envio', () => {
+    expect(() => createPreviewBridgeClient({ from: FROM })).toThrow(/sendCommand.*endpointUrl/)
+  })
+})

package/src/preview/createPreviewBridgeClient.ts

@@ -0,0 +1,124 @@
+/**
+ * Cliente do preview que NÃO carrega segredo: em vez de montar e assinar o payload da Meta no
+ * navegador, manda um comando semântico (`{ kind: 'text', text }`) para uma rota do próprio host,
+ * autenticada pela sessão que o painel já tem. Quem monta o payload e assina é o servidor, com o
+ * app secret que nunca sai de lá.
+ *
+ * Por que esta fábrica existe ao lado de `createPreviewWebhookClient`: assinar no navegador exige o
+ * app secret dentro do bundle, e bundle é público por definição — em qualquer ambiente com URL
+ * acessível isso é o mesmo que publicar o segredo. Com o segredo vazado, qualquer um forja webhooks
+ * válidos daquele app: injeta mensagens de qualquer número e dispara os fluxos. `createPreviewWebhook
+ * Client` continua servindo para execução puramente local (docker de dev, onde o bundle não é
+ * servido para ninguém); para qualquer ambiente publicado, a ponte é o caminho.
+ *
+ * O pacote não decide autenticação: o host injeta `sendCommand` (ou `headers` + `fetchImplementation`),
+ * porque token, cookie e cabeçalho de sessão são do produto, não da biblioteca.
+ */
+
+import type { InboundMediaType, InteractiveReplyOption } from '@adatechnology/meta-whatsapp-contracts/testing'
+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:
+ * se o navegador mandasse o payload pronto, a rota viraria um injetor de webhook arbitrário para
+ * quem tivesse sessão. Mandando a intenção, o servidor é quem escolhe a forma.
+ */
+export type PreviewInboundCommand =
+  | { readonly kind: 'text'; readonly from: string; readonly text: string }
+  | { readonly kind: 'buttonReply'; readonly from: string; readonly reply: InteractiveReplyOption }
+  | { readonly kind: 'listReply'; readonly from: string; readonly reply: InteractiveReplyOption }
+  | { readonly kind: 'audio'; readonly from: string; readonly mediaId: string }
+  | ({ readonly kind: 'media'; readonly from: string } & SendPreviewMediaParams)
+
+export type SendPreviewInboundCommand = (command: PreviewInboundCommand) => Promise<void>
+
+export class PreviewBridgeRejectedError extends Error {
+  constructor(readonly status: number) {
+    super(`A rota de preview do host recusou a entrega (HTTP ${status}).`)
+    this.name = 'PreviewBridgeRejectedError'
+  }
+}
+
+export type CreatePreviewBridgeClientParams = {
+  readonly from: string
+  /**
+   * Entrega o comando. Use quando o host já tem um cliente HTTP com sessão, interceptors e refresh
+   * de token — reimplementar isso aqui só duplicaria a autenticação do produto.
+   */
+  readonly sendCommand?: SendPreviewInboundCommand
+  /** Alternativa a `sendCommand` para hosts sem cliente HTTP próprio. */
+  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 {
+  const endpointUrl = params.endpointUrl
+  if (!endpointUrl) {
+    throw new Error('createPreviewBridgeClient exige `sendCommand` ou `endpointUrl`.')
+  }
+
+  return async (command) => {
+    const performRequest = params.fetchImplementation ?? fetch
+    const response = await performRequest(endpointUrl, {
+      method: 'POST',
+      // `credentials` fica com o host via `headers`/`fetchImplementation`: sessão por cookie e por
+      // bearer não convivem numa escolha default sem quebrar um dos dois.
+      headers: { 'content-type': 'application/json', ...params.headers },
+      body: JSON.stringify(command),
+    })
+
+    if (!response.ok) throw new PreviewBridgeRejectedError(response.status)
+  }
+}
+
+/** 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 }),
+    sendButtonReply: (reply) => send({ kind: 'buttonReply', from, reply }),
+    sendListReply: (reply) => send({ kind: 'listReply', from, reply }),
+    sendAudio: (mediaId) => send({ kind: 'audio', from, mediaId }),
+    sendMedia: (media) => send({ kind: 'media', from, ...media }),
+    ...(uploadMedia ? { uploadMedia } : {}),
+  }
+}
+
+export type { InboundMediaType }

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 }
+  }
+}

package/src/preview/createPreviewWebhookClient.test.ts

@@ -10,8 +10,10 @@ import {
   assertPreviewEnvironment,
   createPreviewWebhookClient,
   PreviewInProductionError,
+  PreviewMediaUploadRejectedError,
   PreviewWebhookRejectedError,
 } from './createPreviewWebhookClient'
+import { PREVIEW_MEDIA_ID_PREFIX } from './createPreviewMediaUploader'
 
 const APP_SECRET = 'dev-app-secret'
 const FROM = '5511988887777'
@@ -34,6 +36,13 @@ function createCapturingFetch(status = 200): { fetchImplementation: typeof fetch
   return { fetchImplementation, captured }
 }
 
+/** `uploadMedia` é opcional no contrato — o cliente do webhook sempre traz, o teste garante isso. */
+function uploadMediaOf(client: { uploadMedia?: (file: File) => Promise<unknown> }) {
+  const upload = client.uploadMedia
+  if (!upload) throw new Error('createPreviewWebhookClient deveria expor uploadMedia')
+  return upload
+}
+
 describe('createPreviewWebhookClient', () => {
   it('assina com o mesmo HMAC que o servidor calcula em node:crypto', async () => {
     const { fetchImplementation, captured } = createCapturingFetch()
@@ -103,3 +112,90 @@ describe('assertPreviewEnvironment', () => {
     expect(() => assertPreviewEnvironment(false)).not.toThrow()
   })
 })
+
+/**
+ * O microfone do simulador depende disto existir no cliente.
+ *
+ * Enquanto o upload era prop de quem montava a tela, um produto tinha gravador e o outro não — e a
+ * diferença não aparecia em teste nenhum, porque cada host montava o seu. Aqui a garantia é do
+ * pacote: cliente montado, upload assinado, id prefixado.
+ */
+describe('createPreviewWebhookClient.uploadMedia', () => {
+  function createUploadFetch(status = 201): {
+    fetchImplementation: typeof fetch
+    calls: Array<{ url: string; signature: string; body: string }>
+  } {
+    const calls: Array<{ url: string; signature: string; body: string }> = []
+
+    const fetchImplementation = (async (url: string, init?: RequestInit) => {
+      const headers = (init?.headers ?? {}) as Record<string, string>
+      calls.push({ url: String(url), signature: headers['x-preview-signature'] ?? '', body: String(init?.body) })
+      return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => ({ data: { uploadId: 'upl_123' } }),
+      } as Response
+    }) as unknown as typeof fetch
+
+    return { fetchImplementation, calls }
+  }
+
+  const audioFile = () => new File([new Uint8Array([1, 2, 3])], 'nota.ogg', { type: 'audio/ogg' })
+
+  it('sobe na mesma origem do webhook e devolve o id já prefixado', async () => {
+    const { fetchImplementation, calls } = createUploadFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    const uploaded = (await uploadMediaOf(client)(audioFile())) as { mediaId: string; mimeType?: string }
+
+    expect(calls[0]?.url).toBe('http://localhost:3000/v1/preview/media')
+    expect(uploaded.mediaId).toBe(`${PREVIEW_MEDIA_ID_PREFIX}upl_123`)
+    expect(uploaded.mimeType).toBe('audio/ogg')
+  })
+
+  it('assina o MIME com o mesmo HMAC que o servidor confere', async () => {
+    const { fetchImplementation, calls } = createUploadFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await uploadMediaOf(client)(audioFile())
+
+    const expected = `sha256=${createHmac('sha256', APP_SECRET).update('audio/ogg').digest('hex')}`
+    expect(calls[0]?.signature).toBe(expected)
+  })
+
+  it('usa caminho relativo quando a URL do webhook não tem origem', async () => {
+    const { fetchImplementation, calls } = createUploadFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: '/v1/webhook/whatsapp',
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await uploadMediaOf(client)(audioFile())
+
+    expect(calls[0]?.url).toBe('/v1/preview/media')
+  })
+
+  it('avisa com erro próprio quando a rota de mídia recusa', async () => {
+    const { fetchImplementation } = createUploadFetch(404)
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await expect(uploadMediaOf(client)(audioFile())).rejects.toBeInstanceOf(PreviewMediaUploadRejectedError)
+  })
+})