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

package/src/preview/previewMediaSource.ts

@@ -0,0 +1,91 @@
+/**
+ * Como o preview entrega mídia para a UI abrir.
+ *
+ * Separado de `previewFileSamples` (que é gerado) porque aqui está a parte que depende do navegador:
+ * **blob URL, não data URL**. O Chrome bloqueia navegação de topo para `data:` desde a v60, então
+ * `window.open(dataUrl)` — que é o que os botões "visualizar" e "baixar" fazem — abre aba em branco
+ * mesmo com bytes perfeitamente válidos. Em `src` de `<img>`/`<video>` a data URL funcionaria; no
+ * `window.open` não, e o mesmo `getDocumentUrl` alimenta os dois.
+ */
+
+import type { MessagePayload } from '../types'
+import type { ResolveMediaUrl } from '../MediaRenderer'
+import { resolvePreviewFileSample } from './previewFileSamples'
+import { PREVIEW_DOCUMENTS } from './previewFixtures'
+
+// Uma blob URL por tipo, reaproveitada: cada `createObjectURL` retém o blob até um `revokeObjectURL`
+// que ninguém chamaria, e a lista redesenha a cada filtro digitado.
+const blobUrlCache = new Map<string, string>()
+
+function toBlob(dataUrl: string): Blob {
+  const [head, payload] = dataUrl.split(',')
+  const mimeType = head!
+    .replace(/^data:/, '')
+    .replace(/;base64$/, '')
+    .replace(/;charset=.*$/, '')
+
+  if (!head!.endsWith(';base64')) {
+    return new Blob([decodeURIComponent(payload!)], { type: mimeType || 'text/plain' })
+  }
+
+  const binary = atob(payload!)
+  const bytes = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index)
+  return new Blob([bytes], { type: mimeType })
+}
+
+/** URL que o preview pode abrir em aba nova. Cai na data URL fora do navegador (teste, SSR). */
+export function previewFileUrl(mimeType: string | undefined, filename?: string): string {
+  const dataUrl = resolvePreviewFileSample(mimeType, filename)
+  if (typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') return dataUrl
+
+  const cached = blobUrlCache.get(dataUrl)
+  if (cached) return cached
+
+  const blobUrl = URL.createObjectURL(toBlob(dataUrl))
+  blobUrlCache.set(dataUrl, blobUrl)
+  return blobUrl
+}
+
+/**
+ * A mesma amostra em base64 cru, como o proxy de mídia do backend a devolveria.
+ *
+ * Existe porque `getMediaProxyUrl` é o caminho da mídia AINDA NÃO ingerida (só existe o id na Meta),
+ * e o contrato pede `{ mimeType, data }` — não URL. Sem isto o mock devolvia o PNG 1x1 para
+ * qualquer id, e vídeo e áudio da thread apareciam quebrados apesar de haver amostra válida.
+ */
+export function previewFileBase64(mimeType: string | undefined, filename?: string): { mimeType: string; data: string } {
+  const dataUrl = resolvePreviewFileSample(mimeType, filename)
+  const [head, payload] = dataUrl.split(',')
+  const declared = head!
+    .replace(/^data:/, '')
+    .replace(/;base64$/, '')
+    .replace(/;charset=.*$/, '')
+
+  if (head!.endsWith(';base64')) return { mimeType: declared, data: payload! }
+  return { mimeType: declared, data: btoa(decodeURIComponent(payload!)) }
+}
+
+/**
+ * O `onResolveMediaUrl` que o `MessageBubble` espera.
+ *
+ * Sem ele, foto, vídeo e áudio da thread ficam parados no placeholder para sempre — o
+ * `MediaRenderer` só resolve `uploadId`/`mediaId` por esta porta, de propósito, para o pacote nunca
+ * chamar endpoint fixo. O preview não tinha resolvedor nenhum, então nenhuma mídia carregava.
+ */
+export function createPreviewMediaResolver(): ResolveMediaUrl {
+  const byId = new Map<string, { mimeType: string; filename: string }>()
+  for (const documents of Object.values(PREVIEW_DOCUMENTS)) {
+    for (const document of documents) {
+      byId.set(document.id, { mimeType: document.mimeType, filename: document.filename })
+    }
+  }
+
+  return async (message: MessagePayload): Promise<string | null> => {
+    const reference = message.uploadId ?? (message.mediaId ? `preview/inbound/${message.mediaId}` : undefined)
+    if (!reference) return null
+
+    const known = byId.get(reference)
+    return previewFileUrl(known?.mimeType ?? message.mimeType, known?.filename ?? message.filename)
+  }
+}

package/src/preview/previewStore.ts

@@ -0,0 +1,193 @@
+/**
+ * Estado em memória que alimenta o preview de atendimento humano. Mock de API e mock de SSE
+ * compartilham este store de propósito: se cada um tivesse dados próprios, um evento anunciaria
+ * mensagem nova e o refetch da lista devolveria o estado antigo — a inbox pareceria funcionar e
+ * estaria mentindo, que é exatamente o defeito que o preview deveria expor.
+ *
+ * Os nomes de canal e de evento espelham o servidor (`conv:<whatsappNumber>`, `global`,
+ * `message`/`message-status`/`mode-changed`/`data-changed`). Fidelidade de vocabulário é o que
+ * permite trocar mock por servidor real sem tocar na UI.
+ */
+
+import type { MessagePayload } from '../types'
+import type { ConversationSummary } from '../providers/types'
+
+export const GLOBAL_CHANNEL = 'global'
+
+export function conversationChannel(conversationId: string): string {
+  return `conv:${conversationId}`
+}
+
+export type PreviewEmission = {
+  readonly channel: string
+  readonly event: string
+  readonly payload: Record<string, unknown>
+}
+
+export type PreviewStoreListener = (emission: PreviewEmission) => void
+
+export type AppendMessageParams = {
+  readonly conversationId: string
+  readonly content: string
+  readonly direction: MessagePayload['direction']
+  readonly sender: MessagePayload['sender']
+}
+
+export type SetModeParams = {
+  readonly conversationId: string
+  readonly mode: ConversationSummary['mode']
+  readonly assignedUserId?: string | undefined
+}
+
+export type ListConversationsFilters = {
+  readonly waitingHuman?: boolean
+  readonly search?: string
+}
+
+export type PreviewStore = {
+  listConversations(filters?: ListConversationsFilters): ConversationSummary[]
+  listMessages(conversationId: string): MessagePayload[]
+  appendMessage(params: AppendMessageParams): MessagePayload
+  setMode(params: SetModeParams): void
+  requestHuman(conversationId: string): void
+  markRead(conversationId: string): void
+  subscribe(channel: string, listener: PreviewStoreListener): () => void
+}
+
+export type CreatePreviewStoreParams = {
+  readonly conversations: readonly ConversationSummary[]
+  readonly messages: Readonly<Record<string, readonly MessagePayload[]>>
+  // Injetável para o teste conseguir asserir timestamps sem depender do relógio.
+  readonly now?: () => Date
+}
+
+export function createPreviewStore(params: CreatePreviewStoreParams): PreviewStore {
+  const conversations = params.conversations.map((conversation) => ({ ...conversation }))
+  const messages = new Map<string, MessagePayload[]>(
+    Object.entries(params.messages).map(([conversationId, list]) => [conversationId, [...list]]),
+  )
+  const listeners = new Map<string, Set<PreviewStoreListener>>()
+  const now = params.now ?? ((): Date => new Date())
+
+  let messageSequence = 0
+
+  function emit(emission: PreviewEmission): void {
+    for (const listener of listeners.get(emission.channel) ?? []) listener(emission)
+  }
+
+  // Toda mutação avisa o canal global: é o sinal de "refaça a query" que mantém a lista coerente
+  // com o que o canal da conversa acabou de anunciar.
+  function emitDataChanged(): void {
+    emit({ channel: GLOBAL_CHANNEL, event: 'data-changed', payload: {} })
+  }
+
+  function findConversation(conversationId: string): ConversationSummary | undefined {
+    return conversations.find((conversation) => conversation.id === conversationId)
+  }
+
+  return {
+    listConversations(filters?: ListConversationsFilters): ConversationSummary[] {
+      return conversations
+        .filter((conversation) => (filters?.waitingHuman ? conversation.waitingHuman : true))
+        .filter((conversation) => {
+          const search = filters?.search?.toLowerCase()
+          if (!search) return true
+          return (
+            conversation.whatsappNumber.includes(search) ||
+            (conversation.clientName?.toLowerCase().includes(search) ?? false)
+          )
+        })
+        .map((conversation) => ({ ...conversation }))
+        .sort((left, right) => right.lastAt.localeCompare(left.lastAt))
+    },
+
+    listMessages(conversationId: string): MessagePayload[] {
+      return [...(messages.get(conversationId) ?? [])]
+    },
+
+    appendMessage(appendParams: AppendMessageParams): MessagePayload {
+      messageSequence += 1
+      const timestamp = now().toISOString()
+      const message: MessagePayload = {
+        id: `preview-${messageSequence}`,
+        type: 'text',
+        content: appendParams.content,
+        direction: appendParams.direction,
+        sender: appendParams.sender,
+        timestamp,
+        status: appendParams.direction === 'outbound' ? 'sent' : undefined,
+      }
+
+      const conversationMessages = messages.get(appendParams.conversationId) ?? []
+      messages.set(appendParams.conversationId, [...conversationMessages, message])
+
+      const conversation = findConversation(appendParams.conversationId)
+      if (conversation) {
+        conversation.lastContent = appendParams.content
+        conversation.lastDirection = appendParams.direction
+        conversation.lastAt = timestamp
+        if (appendParams.direction === 'inbound') {
+          conversation.lastInboundAt = timestamp
+          conversation.unread += 1
+        }
+      }
+
+      // O servidor emite APENAS `{ direction, sender }` neste evento — é ping de "refaça a
+      // query", não entrega de dados. Emitir a mensagem inteira aqui deixaria o mock mais
+      // generoso que a realidade, e uma UI que lesse `event.data.content` funcionaria no preview
+      // e quebraria em produção.
+      emit({
+        channel: conversationChannel(appendParams.conversationId),
+        event: 'message',
+        payload: { direction: message.direction, sender: message.sender },
+      })
+      emitDataChanged()
+
+      return message
+    },
+
+    setMode(modeParams: SetModeParams): void {
+      const conversation = findConversation(modeParams.conversationId)
+      if (!conversation) return
+
+      conversation.mode = modeParams.mode
+      conversation.assignedUserId = modeParams.assignedUserId ?? null
+      // Assumir a conversa é o que atende ao pedido de humano — deixar a flag acesa manteria a
+      // conversa na fila de espera para sempre.
+      if (modeParams.mode === 'human') conversation.waitingHuman = false
+
+      emit({
+        channel: conversationChannel(modeParams.conversationId),
+        event: 'mode-changed',
+        payload: { mode: conversation.mode, assignedUserId: conversation.assignedUserId },
+      })
+      emitDataChanged()
+    },
+
+    requestHuman(conversationId: string): void {
+      const conversation = findConversation(conversationId)
+      if (!conversation) return
+
+      conversation.waitingHuman = true
+      emitDataChanged()
+    },
+
+    markRead(conversationId: string): void {
+      const conversation = findConversation(conversationId)
+      if (!conversation) return
+
+      conversation.unread = 0
+      emitDataChanged()
+    },
+
+    subscribe(channel: string, listener: PreviewStoreListener): () => void {
+      const channelListeners = listeners.get(channel) ?? new Set<PreviewStoreListener>()
+      channelListeners.add(listener)
+      listeners.set(channel, channelListeners)
+
+      return () => {
+        channelListeners.delete(listener)
+      }
+    },
+  }
+}

package/src/preview/startPreviewScript.ts

@@ -0,0 +1,60 @@
+/**
+ * Roteiro que mantém o preview vivo: sem tráfego chegando, a inbox é uma tela estática e as
+ * transições que o atendente precisa testar (fila de espera enchendo, handoff, devolução ao bot)
+ * nunca acontecem.
+ *
+ * O roteiro é cíclico e determinístico — mesma ordem a cada execução. Aleatoriedade tornaria um
+ * defeito visto uma vez difícil de reencontrar.
+ */
+
+import type { PreviewStore } from './previewStore'
+
+export type PreviewScriptStep = (store: PreviewStore) => void
+
+export const DEFAULT_PREVIEW_SCRIPT: readonly PreviewScriptStep[] = [
+  (store) =>
+    store.appendMessage({
+      conversationId: '5511988887777',
+      content: 'pode trocar o óleo por azeite?',
+      direction: 'inbound',
+      sender: 'customer',
+    }),
+  (store) => store.requestHuman('5511988887777'),
+  (store) =>
+    store.appendMessage({
+      conversationId: '5511955554444',
+      content: 'e o troco?',
+      direction: 'inbound',
+      sender: 'customer',
+    }),
+  (store) => store.setMode({ conversationId: '5511977776666', mode: 'human', assignedUserId: 'agent-2' }),
+  (store) =>
+    store.appendMessage({
+      conversationId: '5511977776666',
+      content: 'Oi Diego, sou a Ana. Já vi seu pedido.',
+      direction: 'outbound',
+      sender: 'agent',
+    }),
+  (store) => store.setMode({ conversationId: '5511966665555', mode: 'bot' }),
+]
+
+export type StartPreviewScriptParams = {
+  readonly store: PreviewStore
+  readonly intervalMs?: number
+  readonly steps?: readonly PreviewScriptStep[]
+}
+
+const DEFAULT_INTERVAL_MS = 4000
+
+export function startPreviewScript(params: StartPreviewScriptParams): () => void {
+  const steps = params.steps ?? DEFAULT_PREVIEW_SCRIPT
+  const intervalMs = params.intervalMs ?? DEFAULT_INTERVAL_MS
+  let index = 0
+
+  const timer = setInterval(() => {
+    steps[index % steps.length]?.(params.store)
+    index += 1
+  }, intervalMs)
+
+  return () => clearInterval(timer)
+}

package/src/providers/types.ts

@@ -1,37 +1,182 @@
 import type { MessagePayload } from '../types'
+import type { ConversationChannel } from '../conversationChannel'
+
+export interface ListConversationsParams {
+  page?: number
+  limit?: number
+  waitingHuman?: boolean
+  search?: string
+  /**
+   * Recortes que só o produto conhece (tipo de financiamento, carteira, campanha) repassados
+   * crus ao backend dele. É o que evita o vocabulário de uma vertical virar campo fixo aqui:
+   * o pacote transporta o filtro sem saber o que ele significa.
+   */
+  filters?: Record<string, string | undefined>
+}
+
+/**
+ * Página com o total, para a UI conseguir desenhar controles de paginação.
+ *
+ * `fetchConversations` devolve isto **ou** o array puro de antes: implementações existentes
+ * continuam válidas sem mudar uma linha, e quem precisa paginar passa a ter o total. Sem a união
+ * seria impossível saber se um retorno curto é a última página ou uma página cheia por acaso.
+ */
+export interface ConversationPage {
+  conversations: ConversationSummary[]
+  total: number
+}
+
+export interface ListDocumentsParams {
+  search?: string
+  page?: number
+  /** Tamanho da página. Sem ele, `page` sozinho não define fatia nenhuma. */
+  limit?: number
+  /** Origem do arquivo (`customer`, `agent`, `bot`…). O vocabulário é do host. */
+  source?: string
+  sortDirection?: 'asc' | 'desc'
+}
+
+/** Arquivo na biblioteca da empresa: o mesmo da conversa, mais de qual conversa veio. */
+export interface CompanyDocument extends ConversationDocument {
+  conversationId: string
+}
+
+export interface CompanyDocumentPage {
+  documents: CompanyDocument[]
+  total: number
+}
+
+export interface ConversationDocumentPage {
+  documents: ConversationDocument[]
+  total: number
+}
+
+/**
+ * Template disponível para envio a partir da inbox. Distinto do `WhatsAppTemplateSummary` de
+ * `settings/`, e de propósito: aquele serve ao formulário que **edita** template e carrega o que
+ * a edição precisa (`shortId`, `variableCount`); este serve a quem só vai **escolher um para
+ * enviar**, e pedir os campos de edição obrigaria todo host a produzi-los sem uso.
+ */
+export interface ConversationTemplate {
+  name: string
+  language: string
+  status: string
+  category?: string
+  bodyText?: string | null
+}
 
 export interface ConversationsApi {
   fetchMessages(conversationId: string, params?: { limit?: number; before?: string }): Promise<MessagePayload[]>
-  fetchConversations(params?: {
-    page?: number
-    limit?: number
-    waitingHuman?: boolean
-    search?: string
-  }): Promise<ConversationSummary[]>
+  fetchConversations(params?: ListConversationsParams): Promise<ConversationSummary[] | ConversationPage>
   sendMessage(conversationId: string, text: string): Promise<MessagePayload>
   sendMedia(
     conversationId: string,
     data: { base64: string; mimeType: string; filename: string; caption?: string },
   ): Promise<MessagePayload>
+  /**
+   * `templateName` é opcional porque reabrir a janela é a operação, e escolher *qual* template a
+   * usa nem sempre é decisão da UI: backends que guardam um template padrão configurado só
+   * precisam do "reabra". Exigir o nome obrigaria toda inbox a listar templates antes de poder
+   * mandar o primeiro — e a listagem é `listTemplates?`, opcional.
+   */
   sendTemplate(
     conversationId: string,
-    data: { templateName: string; languageCode?: string; bodyParams?: string[] },
+    data: { templateName?: string; languageCode?: string; bodyParams?: string[] },
   ): Promise<void>
   markRead(conversationId: string): Promise<void>
   getContext(conversationId: string): Promise<Record<string, unknown>>
-  getDocuments(conversationId: string, params?: { search?: string; page?: number }): Promise<ConversationDocument[]>
-  getDocumentUrl(uploadId: string): Promise<string>
+  getDocuments(
+    conversationId: string,
+    params?: ListDocumentsParams,
+  ): Promise<ConversationDocument[] | ConversationDocumentPage>
+  /**
+   * `disposition` decide entre abrir no navegador e baixar. É o backend que assina a URL e grava
+   * o `Content-Disposition` nela, então a escolha precisa viajar na chamada — depois de assinada
+   * não há como o cliente mudá-la. Ausente = o padrão do host.
+   */
+  getDocumentUrl(uploadId: string, disposition?: 'inline' | 'attachment'): Promise<string>
+  /**
+   * Baixa vários arquivos num zip único.
+   *
+   * **Opcional por capacidade:** montar zip exige o host LER os bytes do storage, o que nem toda
+   * instalação faz — as que só assinam URL não conseguem. Ausente, o painel esconde a seleção em
+   * lote em vez de oferecer um botão que falha.
+   */
+  downloadDocumentsArchive?(conversationId: string, uploadIds: readonly string[]): Promise<Blob>
+  /**
+   * Biblioteca de TODAS as conversas, para uma tela de Documentos fora do atendimento.
+   *
+   * Opcional por capacidade: host que só expõe anexo dentro da conversa não implementa, e o
+   * componente de biblioteca simplesmente não é usável — melhor que uma tela que sempre erra.
+   */
+  getAllDocuments?(params?: ListDocumentsParams): Promise<CompanyDocumentPage>
   getMediaProxyUrl(mediaId: string): Promise<{ mimeType: string; data: string }>
+
+  /**
+   * Operações de atendimento humano. **Opcionais por capacidade, não por descuido:** nem toda
+   * inbox tem fila humana — um canal só-bot, ou um chat de site sem operador, não sabe o que é
+   * assumir conversa. Quem não implementa não ganha o botão, em vez de ganhar um botão que
+   * estoura no clique. Os hooks devolvem `undefined` para a ação ausente, e é isso que a UI
+   * consulta para decidir se desenha a afordância.
+   */
+  takeover?(conversationId: string): Promise<void>
+  release?(conversationId: string): Promise<void>
+  /** Encerra o atendimento. Despedida, se houver, é decisão do host — o pacote não a inventa. */
+  finalize?(conversationId: string): Promise<void>
+
+  markAllRead?(): Promise<void>
+  listTemplates?(): Promise<ConversationTemplate[]>
+
+  /**
+   * Transcrição completa gerada pelo servidor. Existe ao lado de `buildTranscriptText`, que monta
+   * a partir das mensagens já em memória: a tela costuma ter só a última página carregada, e
+   * exportar dali entregaria um recorte parcial com cara de histórico inteiro. Opcional porque
+   * nem todo backend expõe a rota — quem não tem continua usando o builder local.
+   */
+  exportTranscript?(conversationId: string): Promise<{ transcript: string; filename: string }>
+}
+
+/**
+ * Superfície mínima de stream que o pacote consome — exatamente o que `useConversationRealtime`
+ * usa: assinar 'message', desassinar e fechar. Deliberadamente estrutural em vez de
+ * `EventSource`: sem servidor HTTP não existe `EventSource`, e é isso que impediria alimentar a
+ * inbox com dados mockados em desenvolvimento. Um `EventSource` nativo satisfaz este tipo, então
+ * quem já implementa `SSEProvider` continua válido sem mudança.
+ */
+export interface ConversationEventSource {
+  addEventListener(type: string, listener: (event: MessageEvent) => void): void
+  removeEventListener(type: string, listener: (event: MessageEvent) => void): void
+  close(): void
 }
 
+/**
+ * Eventos nomeados que o servidor realmente emite (`event: <nome>` no fio). O canal por conversa
+ * é `conv:<whatsappNumber>`; o global só emite `data-changed`, como sinal de "refaça a query".
+ * Tipar `addEventListener` como `string` em vez de `'message'` existe por isto: quem assina
+ * precisa alcançar `message-status` e `mode-changed`, não só `message`.
+ */
+export const CONVERSATION_STREAM_EVENTS = ['message', 'message-status', 'mode-changed'] as const
+export type ConversationStreamEvent = (typeof CONVERSATION_STREAM_EVENTS)[number]
+
+export const GLOBAL_STREAM_EVENTS = ['data-changed'] as const
+export type GlobalStreamEvent = (typeof GLOBAL_STREAM_EVENTS)[number]
+
 export interface SSEProvider {
-  connectConversationStream(conversationId: string): EventSource
-  connectGlobalStream(): EventSource
+  connectConversationStream(conversationId: string): ConversationEventSource
+  connectGlobalStream(): ConversationEventSource
 }
 
 export interface ConversationSummary {
   id: string
+  /**
+   * @deprecated Use `contactId` com `channel`. Mantido obrigatório para não quebrar quem já
+   * consome; some quando o segundo canal entrar em produção.
+   */
   whatsappNumber: string
+  /** Identificador neutro do contato. Ausente = usa `whatsappNumber`. */
+  contactId?: string
+  /** Ausente = `whatsapp`, o comportamento de antes desta mudança. */
+  channel?: ConversationChannel
   clientName?: string
   lastContent?: string
   lastDirection?: 'inbound' | 'outbound'
@@ -42,6 +187,13 @@ export interface ConversationSummary {
   waitingHuman: boolean
   unread: number
   currentState: string
+  /**
+   * Atributos que só o produto conhece e desenha (tipo de financiamento, carteira, campanha). É a
+   * contraparte de leitura do `filters` de `ListConversationsParams`: o pacote transporta e nunca
+   * interpreta. Sem isto, exibir um selo próprio na linha exigiria o host manter uma segunda
+   * consulta paralela à mesma listagem — a implementação duplicada que o pacote existe para evitar.
+   */
+  attributes?: Record<string, string | undefined>
 }
 
 export interface ConversationDocument {

package/src/quickReply.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Guarda a interpolação das mensagens rápidas.
+ *
+ * O caso que decide o desenho: variável ausente. Deixar `{{nome}}` no texto significa o atendente
+ * mandar "Olá {{nome}}!" para o cliente — pior que a saudação sem nome.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { applyQuickReplyVariables, resolveQuickReply } from './MessageComposer'
+
+describe('applyQuickReplyVariables', () => {
+  it('troca a variável pelo valor', () => {
+    expect(applyQuickReplyVariables('Olá {{nome}}!', { nome: 'Marina' })).toBe('Olá Marina!')
+  })
+
+  it('aceita espaço dentro das chaves', () => {
+    expect(applyQuickReplyVariables('Olá {{ nome }}!', { nome: 'Rita' })).toBe('Olá Rita!')
+  })
+
+  it('troca todas as ocorrências', () => {
+    expect(applyQuickReplyVariables('{{nome}}, confirma? Obrigado, {{nome}}.', { nome: 'Ana' })).toBe(
+      'Ana, confirma? Obrigado, Ana.',
+    )
+  })
+
+  // Nunca vaza o literal para o cliente.
+  it('apaga a variável que não foi passada', () => {
+    expect(applyQuickReplyVariables('Olá {{nome}}!', {})).toBe('Olá !')
+    expect(applyQuickReplyVariables('Olá {{nome}}!')).toBe('Olá !')
+  })
+
+  it('não mexe em texto sem variável', () => {
+    expect(applyQuickReplyVariables('Bom dia!', { nome: 'X' })).toBe('Bom dia!')
+  })
+})
+
+describe('resolveQuickReply', () => {
+  it('interpola quando o texto é string', () => {
+    const resolvido = resolveQuickReply({ key: 'g', label: '👋', text: 'Olá {{nome}}!' }, { nome: 'Rita' })
+
+    expect(resolvido).toBe('Olá Rita!')
+  })
+
+  // A função existe para o que a string não resolve: escolher copy por produto, pluralizar, formatar.
+  it('chama a função com as variáveis', () => {
+    const resolvido = resolveQuickReply(
+      { key: 's', label: '📋', text: (variables) => `Status de ${variables['produto'] ?? 'seu pedido'}` },
+      { produto: 'financiamento' },
+    )
+
+    expect(resolvido).toBe('Status de financiamento')
+  })
+
+  it('função sem variáveis não quebra', () => {
+    expect(resolveQuickReply({ key: 'c', label: '📞', text: () => 'Posso ligar?' })).toBe('Posso ligar?')
+  })
+})

package/src/settings/WhatsAppCreateTemplateForm.tsx

@@ -24,6 +24,7 @@ export interface WhatsAppCreateTemplateFormLabels {
   sectionDescription: string
   nameLabel: string
   nameHint: string
+  namePlaceholder: string
   categoryLabel: string
   languageLabel: string
   headerLabel: string
@@ -57,6 +58,7 @@ const DEFAULT_LABELS: WhatsAppCreateTemplateFormLabels = {
   sectionDescription: 'Envia um template para aprovação da Meta.',
   nameLabel: 'Nome do template',
   nameHint: 'Somente letras minúsculas, números e underscore.',
+  namePlaceholder: 'reengajamento_cliente',
   categoryLabel: 'Categoria',
   languageLabel: 'Idioma',
   headerLabel: 'Cabeçalho',
@@ -142,7 +144,7 @@ export function WhatsAppCreateTemplateForm({
             type="text"
             value={value.name}
             onChange={(e) => set('name', e.target.value.toLowerCase().replace(/[^a-z0-9_]/g, '_'))}
-            placeholder="reengajamento_cliente"
+            placeholder={labels.namePlaceholder}
             className="w-full border border-gray-200 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-100 rounded-xl px-3 py-2.5 text-sm focus:outline-none focus:ring-2 focus:ring-blue-400 focus:border-transparent transition-all"
             required
           />