@adatechnology/conversations-ui 0.1.0-rc.2 → 0.1.0-rc.21

package/src/preview/createMockConversationsApi.ts

@@ -0,0 +1,271 @@
+/**
+ * `ConversationsApi` servido pelo store em memória. Como o pacote é headless e recebe a API por
+ * injeção, o preview de atendimento humano não precisa de servidor, banco nem Meta: é só outra
+ * implementação deste mesmo contrato.
+ *
+ * Toda resposta é assíncrona e passa por um atraso configurável — API instantânea esconde estados
+ * de carregamento, e é neles que a inbox costuma mostrar defeito.
+ */
+
+import type { MessagePayload } from '../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'
+
+export type CreateMockConversationsApiParams = {
+  readonly store: PreviewStore
+  readonly latencyMs?: number
+  readonly agentName?: string
+}
+
+const DEFAULT_LATENCY_MS = 120
+
+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> {
+    await new Promise((resolve) => setTimeout(resolve, latencyMs))
+    return produce()
+  }
+
+  return {
+    // 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,
+          search: fetchParams?.search,
+        })
+
+        const limit = fetchParams?.limit ?? conversations.length
+        const page = fetchParams?.page ?? 1
+        return {
+          conversations: conversations.slice((page - 1) * limit, page * limit),
+          total: conversations.length,
+        }
+      })
+    },
+
+    fetchMessages(conversationId, fetchParams): Promise<MessagePayload[]> {
+      return withLatency(() => {
+        const messages = params.store.listMessages(conversationId)
+        const limit = fetchParams?.limit
+        return limit ? messages.slice(-limit) : messages
+      })
+    },
+
+    sendMessage(conversationId, text): Promise<MessagePayload> {
+      return withLatency(() =>
+        params.store.appendMessage({ conversationId, content: text, direction: 'outbound', sender: 'agent' }),
+      )
+    },
+
+    sendMedia(conversationId, data): Promise<MessagePayload> {
+      return withLatency(() =>
+        params.store.appendMessage({
+          conversationId,
+          content: data.caption ?? data.filename,
+          direction: 'outbound',
+          sender: 'agent',
+        }),
+      )
+    },
+
+    sendTemplate(conversationId, data): Promise<void> {
+      return withLatency(() => {
+        params.store.appendMessage({
+          conversationId,
+          // 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',
+        })
+      })
+    },
+
+    markRead(conversationId): Promise<void> {
+      return withLatency(() => params.store.markRead(conversationId))
+    },
+
+    getContext(conversationId): Promise<Record<string, unknown>> {
+      return withLatency(() => {
+        const conversation = params.store.listConversations().find((item) => item.id === conversationId)
+        return {
+          currentState: conversation?.currentState ?? 'unknown',
+          mode: conversation?.mode ?? 'bot',
+          preview: true,
+        }
+      })
+    },
+
+    /**
+     * 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' })
+      })
+    },
+
+    /** 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)
+        }
+      })
+    },
+
+    listTemplates(): Promise<ConversationTemplate[]> {
+      return withLatency(() => [...PREVIEW_TEMPLATES])
+    },
+  }
+}

package/src/preview/createMockSSEProvider.ts

@@ -0,0 +1,40 @@
+/**
+ * `SSEProvider` servido pelo store em memória. Mesmo mapeamento de canal do servidor
+ * (`conv:<conversationId>` e `global`), para que a UI não perceba a troca.
+ */
+
+import type { SSEProvider } from '../providers/types'
+import { createMockEventSource } from './mockEventSource'
+import { conversationChannel, GLOBAL_CHANNEL, type PreviewStore } from './previewStore'
+
+export type CreateMockSSEProviderParams = {
+  readonly store: PreviewStore
+}
+
+export function createMockSSEProvider(params: CreateMockSSEProviderParams): SSEProvider {
+  function connect(channel: string): ReturnType<typeof createMockEventSource> {
+    const source = createMockEventSource()
+    const unsubscribe = params.store.subscribe(channel, (emission) => {
+      source.emit(emission.event, emission.payload)
+    })
+
+    const close = source.close.bind(source)
+    // O unsubscribe tem de acontecer no close, senão cada remontagem de componente deixa um
+    // listener preso no store e a mesma mensagem chega duplicada na UI.
+    source.close = (): void => {
+      unsubscribe()
+      close()
+    }
+
+    return source
+  }
+
+  return {
+    connectConversationStream(conversationId: string) {
+      return connect(conversationChannel(conversationId))
+    },
+    connectGlobalStream() {
+      return connect(GLOBAL_CHANNEL)
+    },
+  }
+}

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