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

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'
@@ -103,3 +105,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 client.uploadMedia(audioFile())
+
+    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 client.uploadMedia(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 client.uploadMedia(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(client.uploadMedia(audioFile())).rejects.toBeInstanceOf(PreviewMediaUploadRejectedError)
+  })
+})

package/src/preview/createPreviewWebhookClient.ts

@@ -25,6 +25,7 @@ import {
   type InboundMediaType,
   type InteractiveReplyOption,
 } from '@adatechnology/meta-whatsapp-contracts/testing'
+import { createPreviewMediaUploader, type PreviewUploadedMedia } from './createPreviewMediaUploader'
 
 export type PreviewWebhookClient = {
   sendText(text: string): Promise<void>
@@ -32,6 +33,19 @@ export type PreviewWebhookClient = {
   sendListReply(reply: InteractiveReplyOption): Promise<void>
   sendAudio(mediaId: string): Promise<void>
   sendMedia(params: SendPreviewMediaParams): Promise<void>
+  /**
+   * Guarda um arquivo gravado e devolve o `mediaId` já prefixado, pronto para `sendMedia`.
+   *
+   * Existe no cliente, e não como prop de quem monta a tela, porque isto é exatamente o que ele já
+   * sabe fazer: falar com ESTE host usando ESTE segredo. Enquanto era responsabilidade do produto,
+   * o resultado prático foi um produto com microfone no simulador e outro sem — não por decisão,
+   * por esquecimento. Cliente montado, microfone na tela.
+   *
+   * Opcional porque o cliente-ponte só consegue oferecer isto quando sabe a rota de mídia (ou quando
+   * o host injeta a função): sem destino, gravar áudio seria falar para o vazio, e aí a tela
+   * corretamente não desenha o gravador.
+   */
+  uploadMedia?(file: File): Promise<PreviewUploadedMedia>
 }
 
 export type SendPreviewMediaParams = {
@@ -52,10 +66,25 @@ export type CreatePreviewWebhookClientParams = {
   readonly appSecret: string
   readonly from: string
   readonly phoneNumberId?: string
+  /**
+   * Rota que guarda o áudio gravado. Por padrão, `/v1/preview/media` na mesma origem do webhook.
+   *
+   * O padrão cobre o caso normal — as duas rotas são do mesmo servidor — e a prop existe para quem
+   * publica a API em outro host ou versiona o caminho.
+   */
+  readonly mediaUploadUrl?: string
   // Escape hatch para teste; em runtime real é sempre o fetch global.
   readonly fetchImplementation?: typeof fetch
 }
 
+/** Falha da rota de upload, separada da do webhook: os dois lados quebram por motivos diferentes. */
+export class PreviewMediaUploadRejectedError extends Error {
+  constructor(readonly status: number) {
+    super(`A rota de mídia do simulador recusou o upload (HTTP ${status}).`)
+    this.name = 'PreviewMediaUploadRejectedError'
+  }
+}
+
 export class PreviewInProductionError extends Error {
   constructor() {
     super('O preview de conversa carrega um app secret e não pode ser montado em produção.')
@@ -102,6 +131,53 @@ export async function signPreviewPayload(params: { rawBody: string; appSecret: s
 
 const signWithWebCrypto = signPreviewPayload
 
+export const DEFAULT_MEDIA_UPLOAD_PATH = '/v1/preview/media'
+
+/**
+ * Mesma origem do webhook: as duas rotas são do mesmo servidor no caso normal.
+ *
+ * Quando `webhookUrl` é relativa — que é o que sai de um `VITE_API_URL` vazio, com o front servido
+ * pela própria API — não há origem para resolver contra, e o caminho relativo já aponta para o
+ * lugar certo. `new URL` com base relativa lançaria, e o microfone morreria no `createClient`.
+ */
+export function defaultMediaUploadUrl(webhookUrl: string): string {
+  try {
+    return new URL(DEFAULT_MEDIA_UPLOAD_PATH, webhookUrl).toString()
+  } catch {
+    return DEFAULT_MEDIA_UPLOAD_PATH
+  }
+}
+
+/**
+ * O POST de mídia, sem a parte de assinatura — para os dois clientes usarem o mesmo caminho.
+ *
+ * O cliente-ponte autentica por sessão e o de webhook por HMAC; o que não muda é a rota, o formato
+ * do corpo e a leitura do `uploadId`. Duas cópias disso é como o prefixo de mídia divergiu antes.
+ */
+export function createPreviewMediaPoster(params: {
+  readonly url: string
+  readonly headers?: (mimeType: string) => Promise<Readonly<Record<string, string>>>
+  readonly fetchImplementation?: typeof fetch
+}): (file: File) => Promise<PreviewUploadedMedia> {
+  return createPreviewMediaUploader({
+    upload: async (request) => {
+      const performRequest = params.fetchImplementation ?? fetch
+      const extraHeaders = (await params.headers?.(request.mimeType)) ?? {}
+
+      const response = await performRequest(params.url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...extraHeaders },
+        body: JSON.stringify(request),
+      })
+
+      if (!response.ok) throw new PreviewMediaUploadRejectedError(response.status)
+
+      const body = (await response.json()) as { data: { uploadId: string } }
+      return { uploadId: body.data.uploadId }
+    },
+  })
+}
+
 export function createPreviewWebhookClient(params: CreatePreviewWebhookClientParams): PreviewWebhookClient {
   const sendPayload = async (payload: ReturnType<typeof buildInboundTextPayload>): Promise<void> => {
     // Serializa uma vez só: assinar um texto e enviar outro (mesmo com o conteúdo igual) derruba a
@@ -119,6 +195,20 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     if (!response.ok) throw new PreviewWebhookRejectedError(response.status)
   }
 
+  /**
+   * Assina o MIME, não o binário — mesmo contrato da rota.
+   *
+   * Passar megabytes de base64 pelo HMAC do navegador travaria a aba a cada nota de voz; o que a
+   * assinatura protege aqui é o acesso à rota, e o binário já tem teto de tamanho no servidor.
+   */
+  const uploadMedia = createPreviewMediaPoster({
+    url: params.mediaUploadUrl ?? defaultMediaUploadUrl(params.webhookUrl),
+    headers: async (mimeType) => ({
+      'x-preview-signature': await signWithWebCrypto({ rawBody: mimeType, appSecret: params.appSecret }),
+    }),
+    ...(params.fetchImplementation ? { fetchImplementation: params.fetchImplementation } : {}),
+  })
+
   const envelope = { from: params.from, phoneNumberId: params.phoneNumberId }
 
   return {
@@ -127,5 +217,6 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     sendListReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, listReply: reply })),
     sendAudio: (mediaId) => sendPayload(buildInboundAudioPayload({ ...envelope, mediaId })),
     sendMedia: (media) => sendPayload(buildInboundMediaPayload({ ...envelope, ...media })),
+    uploadMedia,
   }
 }

package/src/preview/index.ts

@@ -38,6 +38,9 @@ export {
   assertPreviewEnvironment,
   PreviewInProductionError,
   PreviewWebhookRejectedError,
+  PreviewMediaUploadRejectedError,
+  createPreviewMediaPoster,
+  DEFAULT_MEDIA_UPLOAD_PATH,
 } from './createPreviewWebhookClient'
 export type {
   PreviewWebhookClient,
@@ -59,3 +62,6 @@ export { createPreviewMediaResolver, previewFileUrl } from './previewMediaSource
 export { previewFileBase64 } from './previewMediaSource'
 export { MediaTypesPreview, MEDIA_TYPES_CONVERSATION_ID } from './MediaTypesPreview'
 export type { MediaTypesPreviewProps } from './MediaTypesPreview'
+
+export { createPreviewMediaUploader, PREVIEW_MEDIA_ID_PREFIX } from './createPreviewMediaUploader'
+export type { CreatePreviewMediaUploaderParams, PreviewMediaUploadRequest } from './createPreviewMediaUploader'

package/src/preview/previewMediaUploader.test.ts

@@ -0,0 +1,61 @@
+/**
+ * O teste que importa aqui é o do prefixo: ele é duplicado entre este pacote (UI) e o
+ * meta-whatsapp-module (backend), e divergir significa o simulador gerar um id que o servidor não
+ * reconhece — o áudio chega, o backend busca na Meta, volta 404 e ninguém entende por quê.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { PREVIEW_MEDIA_ID_PREFIX as CONTRACT_PREFIX } from '@adatechnology/meta-whatsapp-contracts'
+
+import { createPreviewMediaUploader, PREVIEW_MEDIA_ID_PREFIX } from './createPreviewMediaUploader'
+
+describe('createPreviewMediaUploader', () => {
+  it('reexporta o prefixo do contrato, sem cópia própria', () => {
+    expect(PREVIEW_MEDIA_ID_PREFIX).toBe(CONTRACT_PREFIX)
+  })
+
+  it('devolve o id prefixado com o uploadId da rota', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'chave/do/objeto' }) })
+
+    const result = await upload(new File([new Uint8Array([1, 2, 3])], 'nota.ogg', { type: 'audio/ogg' }))
+
+    expect(result.mediaId).toBe(`${CONTRACT_PREFIX}chave/do/objeto`)
+    expect(result.mimeType).toBe('audio/ogg')
+    expect(result.filename).toBe('nota.ogg')
+  })
+
+  it('manda o binário em base64 para a rota', async () => {
+    let recebido: string | undefined
+    const upload = createPreviewMediaUploader({
+      upload: async (request) => {
+        recebido = request.base64
+        return { uploadId: 'k' }
+      },
+    })
+
+    await upload(new File([new TextEncoder().encode('audio')], 'a.ogg', { type: 'audio/ogg' }))
+
+    expect(atob(recebido!)).toBe('audio')
+  })
+
+  // Gravador entrega áudio sem nome, e navegador antigo entrega sem mime.
+  it('preenche nome e mime quando o arquivo vem sem eles', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'k' }) })
+
+    const result = await upload(new File([new Uint8Array([1])], '', { type: '' }))
+
+    expect(result.mimeType).toBe('audio/ogg')
+    expect(result.filename).toBe('audio.ogg')
+  })
+
+  /**
+   * Espalhar o array de bytes como argumentos estoura a pilha em arquivo grande — o erro que só
+   * aparece na primeira gravação de verdade, nunca no clipe curto do teste.
+   */
+  it('converte arquivo grande sem estourar a pilha', async () => {
+    const upload = createPreviewMediaUploader({ upload: async () => ({ uploadId: 'k' }) })
+    const grande = new File([new Uint8Array(300_000)], 'longo.ogg', { type: 'audio/ogg' })
+
+    expect((await upload(grande)).mediaId).toContain(CONTRACT_PREFIX)
+  })
+})

package/src/providers/types.ts

@@ -1,4 +1,4 @@
-import type { MessagePayload } from '../types'
+import type { MessagePayload, MessageTranscription } from '../types'
 import type { ConversationChannel } from '../conversationChannel'
 
 export interface ListConversationsParams {
@@ -134,6 +134,17 @@ export interface ConversationsApi {
    * nem todo backend expõe a rota — quem não tem continua usando o builder local.
    */
   exportTranscript?(conversationId: string): Promise<{ transcript: string; filename: string }>
+
+  /**
+   * Transcreve o áudio de uma mensagem e devolve o resultado.
+   *
+   * **Opcional por capacidade.** Um host em modo automático transcreve na ingestão e não expõe rota
+   * nenhuma; um host sem engine configurado não transcreve de jeito algum. Nos dois casos o balão
+   * simplesmente não desenha o botão, em vez de oferecer uma ação que estoura no clique.
+   *
+   * `messageId` e não `conversationId`: transcrição é por áudio, e uma conversa tem vários.
+   */
+  transcribeAudio?(messageId: string): Promise<MessageTranscription>
 }
 
 /**

package/src/settings/TranscriptionSettingsForm.test.tsx

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { TranscriptionSettingsForm } from './TranscriptionSettingsForm'
+import type { TranscriptionSettingsFormProps } from './TranscriptionSettingsForm'
+
+/**
+ * Extrai uma tag pelo atributo, em vez de casar regex com a ordem dos atributos: o React SSR emite
+ * `checked=""` antes de `value=""`, então `/value="auto"[^>]*checked/` falha num componente correto.
+ */
+function findTag(markup: string, tagPattern: RegExp, contains: string): string | undefined {
+  return (markup.match(tagPattern) ?? []).find((tag) => tag.includes(contains))
+}
+
+function render(overrides: Partial<TranscriptionSettingsFormProps> = {}): string {
+  return renderToStaticMarkup(
+    <TranscriptionSettingsForm
+      enabled={false}
+      onEnabledChange={() => {}}
+      mode="onDemand"
+      onModeChange={() => {}}
+      onSave={() => {}}
+      {...overrides}
+    />,
+  )
+}
+
+describe('TranscriptionSettingsForm', () => {
+  it('esconde a escolha de modo enquanto estiver desligado', () => {
+    const markup = render({ enabled: false })
+
+    expect(markup).not.toContain('Quando transcrever')
+  })
+
+  it('mostra as duas opções de modo ao ligar', () => {
+    const markup = render({ enabled: true })
+
+    expect(markup).toContain('Quando transcrever')
+    expect(markup).toContain('Quando o atendente pedir')
+    expect(markup).toContain('Automaticamente')
+  })
+
+  it('marca o modo atual', () => {
+    const markup = render({ enabled: true, mode: 'auto' })
+    const radios = /<input type="radio"[^>]*>/g
+
+    expect(findTag(markup, radios, 'value="auto"')).toContain('checked')
+    expect(findTag(markup, radios, 'value="onDemand"')).not.toContain('checked')
+  })
+
+  /**
+   * "O ambiente consegue" é diferente de "esta empresa quer". Sem o aviso, o lojista ligaria o
+   * interruptor num ambiente sem engine, nada apareceria, e nada explicaria por quê.
+   */
+  it('avisa e bloqueia quando a capacidade não existe no servidor', () => {
+    const markup = render({ isAvailable: false })
+
+    expect(markup).toContain('não está disponível neste ambiente')
+    expect(findTag(markup, /<input type="checkbox"[^>]*>/g, 'type="checkbox"')).toContain('disabled')
+  })
+
+  it('não avisa nada quando a capacidade existe', () => {
+    const markup = render({ isAvailable: true })
+
+    expect(markup).not.toContain('não está disponível neste ambiente')
+  })
+
+  it('aceita rótulos do host', () => {
+    const markup = render({ labels: { sectionTitle: 'Áudio em texto' } })
+
+    expect(markup).toContain('Áudio em texto')
+    expect(markup).not.toContain('Transcrição de áudio')
+  })
+
+  it('desabilita o salvar enquanto salva', () => {
+    const markup = render({ saving: true })
+
+    expect(markup).toContain('Salvando...')
+    expect(findTag(markup, /<button type="submit"[^>]*>/g, 'type="submit"')).toContain('disabled')
+  })
+})