@adatechnology/conversations-ui 0.1.0-rc.8 → 0.1.0

package/src/preview/ConversationSimulatorPanel.tsx

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ *
+ * 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 identificador 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…',
+}
+
+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
+  /**
+   * 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. */
+  readonly headerActions?: ReactNode
+}
+
+export function ConversationSimulatorPanel({
+  onClose,
+  channel,
+  displayHandle,
+  displayNumber,
+  labels,
+  headerActions,
+  ...previewProps
+}: ConversationSimulatorPanelProps) {
+  const text = { ...simulatorPanelLabelsOf(channel), ...labels }
+  const subtitle = [displayHandle ?? 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} data-cv-tooltip={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.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)
+  })
+})