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

package/src/preview/createPreviewWebhookClient.test.ts

@@ -0,0 +1,105 @@
+/**
+ * O risco aqui não é o cliente montar o payload errado — é o HMAC do WebCrypto divergir do que o
+ * servidor calcula com `node:crypto`. Uma divergência de um byte transforma todo envio do preview
+ * em 401, então o teste compara as duas implementações diretamente.
+ */
+
+import { createHmac } from 'node:crypto'
+import { describe, expect, it } from 'bun:test'
+import {
+  assertPreviewEnvironment,
+  createPreviewWebhookClient,
+  PreviewInProductionError,
+  PreviewWebhookRejectedError,
+} from './createPreviewWebhookClient'
+
+const APP_SECRET = 'dev-app-secret'
+const FROM = '5511988887777'
+const WEBHOOK_URL = 'http://localhost:3000/v1/webhook/whatsapp'
+
+type CapturedRequest = {
+  body: string
+  signature: string
+}
+
+function createCapturingFetch(status = 200): { fetchImplementation: typeof fetch; captured: CapturedRequest[] } {
+  const captured: CapturedRequest[] = []
+
+  const fetchImplementation = (async (_url: string, init?: RequestInit) => {
+    const headers = init?.headers as Record<string, string>
+    captured.push({ body: String(init?.body), signature: headers['x-hub-signature-256'] ?? '' })
+    return { ok: status >= 200 && status < 300, status } as Response
+  }) as unknown as typeof fetch
+
+  return { fetchImplementation, captured }
+}
+
+describe('createPreviewWebhookClient', () => {
+  it('assina com o mesmo HMAC que o servidor calcula em node:crypto', async () => {
+    const { fetchImplementation, captured } = createCapturingFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await client.sendText('quero 2kg de arroz')
+
+    const request = captured[0]
+    const expected = `sha256=${createHmac('sha256', APP_SECRET)
+      .update(request?.body ?? '')
+      .digest('hex')}`
+    expect(request?.signature).toBe(expected)
+  })
+
+  it('envia exatamente os bytes que assinou', async () => {
+    const { fetchImplementation, captured } = createCapturingFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await client.sendButtonReply({ id: 'confirmar', title: 'Confirmar' })
+
+    const request = captured[0]
+    const reparsed = JSON.stringify(JSON.parse(request?.body ?? '{}'))
+    expect(request?.body).toBe(reparsed)
+  })
+
+  it('mensagens de texto idêntico produzem assinaturas distintas', async () => {
+    const { fetchImplementation, captured } = createCapturingFetch()
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await client.sendText('sim')
+    await client.sendText('sim')
+
+    expect(captured[0]?.signature).not.toBe(captured[1]?.signature)
+  })
+
+  it('propaga a recusa do webhook em vez de engolir', async () => {
+    const { fetchImplementation } = createCapturingFetch(401)
+    const client = createPreviewWebhookClient({
+      webhookUrl: WEBHOOK_URL,
+      appSecret: APP_SECRET,
+      from: FROM,
+      fetchImplementation,
+    })
+
+    await expect(client.sendText('oi')).rejects.toBeInstanceOf(PreviewWebhookRejectedError)
+  })
+})
+
+describe('assertPreviewEnvironment', () => {
+  it('recusa montar em produção', () => {
+    expect(() => assertPreviewEnvironment(true)).toThrow(PreviewInProductionError)
+    expect(() => assertPreviewEnvironment(false)).not.toThrow()
+  })
+})

package/src/preview/createPreviewWebhookClient.ts

@@ -0,0 +1,99 @@
+/**
+ * Cliente que entrega mensagens do preview no webhook real, assinadas com HMAC — a mesma validação
+ * de staging e produção, sem rota alternativa e sem bypass. Do ponto de vista da API, este cliente
+ * é indistinguível da Meta; o que muda é apenas quem assina.
+ *
+ * Assina com WebCrypto porque `node:crypto` não existe no navegador. Os builders vêm dos contratos
+ * (isomórficos) justamente para que o mesmo payload seja montado nos dois runtimes.
+ *
+ * ⚠️ Isto carrega o app secret de DESENVOLVIMENTO no bundle. Só existe para o docker local, e
+ * `assertPreviewEnvironment` recusa rodar em produção — um segredo de dev vazado é irrelevante,
+ * mas o hábito de embarcar segredo em frontend não é.
+ */
+
+import {
+  buildInboundAudioPayload,
+  buildInboundInteractivePayload,
+  buildInboundTextPayload,
+  serializeWebhookPayload,
+  type InteractiveReplyOption,
+} from '@adatechnology/meta-whatsapp-contracts/testing'
+
+export type PreviewWebhookClient = {
+  sendText(text: string): Promise<void>
+  sendButtonReply(reply: InteractiveReplyOption): Promise<void>
+  sendListReply(reply: InteractiveReplyOption): Promise<void>
+  sendAudio(mediaId: string): Promise<void>
+}
+
+export type CreatePreviewWebhookClientParams = {
+  readonly webhookUrl: string
+  readonly appSecret: string
+  readonly from: string
+  readonly phoneNumberId?: string
+  // Escape hatch para teste; em runtime real é sempre o fetch global.
+  readonly fetchImplementation?: typeof fetch
+}
+
+export class PreviewInProductionError extends Error {
+  constructor() {
+    super('O preview de conversa carrega um app secret e não pode ser montado em produção.')
+    this.name = 'PreviewInProductionError'
+  }
+}
+
+export class PreviewWebhookRejectedError extends Error {
+  constructor(readonly status: number) {
+    super(`O webhook recusou a entrega do preview (HTTP ${status}).`)
+    this.name = 'PreviewWebhookRejectedError'
+  }
+}
+
+/**
+ * Falha alto em vez de degradar em silêncio: um preview que "quase funciona" em produção é pior
+ * que um que se recusa a montar.
+ */
+export function assertPreviewEnvironment(isProduction: boolean): void {
+  if (isProduction) throw new PreviewInProductionError()
+}
+
+async function signWithWebCrypto(params: { rawBody: string; appSecret: string }): Promise<string> {
+  const encoder = new TextEncoder()
+  const key = await globalThis.crypto.subtle.importKey(
+    'raw',
+    encoder.encode(params.appSecret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  )
+  const signature = await globalThis.crypto.subtle.sign('HMAC', key, encoder.encode(params.rawBody))
+
+  return `sha256=${[...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, '0')).join('')}`
+}
+
+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
+    // validação, porque o HMAC cobre os bytes exatos.
+    const rawBody = serializeWebhookPayload(payload)
+    const signature = await signWithWebCrypto({ rawBody, appSecret: params.appSecret })
+    const performRequest = params.fetchImplementation ?? fetch
+
+    const response = await performRequest(params.webhookUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-hub-signature-256': signature },
+      body: rawBody,
+    })
+
+    if (!response.ok) throw new PreviewWebhookRejectedError(response.status)
+  }
+
+  const envelope = { from: params.from, phoneNumberId: params.phoneNumberId }
+
+  return {
+    sendText: (text) => sendPayload(buildInboundTextPayload({ ...envelope, text })),
+    sendButtonReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, buttonReply: reply })),
+    sendListReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, listReply: reply })),
+    sendAudio: (mediaId) => sendPayload(buildInboundAudioPayload({ ...envelope, mediaId })),
+  }
+}

package/src/preview/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Export separado (`@adatechnology/conversations-ui/preview`) para que fixtures e mocks nunca
+ * entrem no bundle de produção de quem consome o pacote.
+ */
+
+export { createPreviewStore, conversationChannel, GLOBAL_CHANNEL } from './previewStore'
+export type {
+  PreviewStore,
+  CreatePreviewStoreParams,
+  PreviewEmission,
+  PreviewStoreListener,
+  AppendMessageParams,
+  SetModeParams,
+  ListConversationsFilters,
+} from './previewStore'
+
+export { createMockEventSource } from './mockEventSource'
+export type { MockEventSource } from './mockEventSource'
+
+export { createMockConversationsApi } from './createMockConversationsApi'
+export type { CreateMockConversationsApiParams } from './createMockConversationsApi'
+
+export { createMockSSEProvider } from './createMockSSEProvider'
+export type { CreateMockSSEProviderParams } from './createMockSSEProvider'
+
+export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES } from './previewFixtures'
+
+export { ConversationPreview } from './ConversationPreview'
+export type { ConversationPreviewProps } from './ConversationPreview'
+
+export {
+  createPreviewWebhookClient,
+  assertPreviewEnvironment,
+  PreviewInProductionError,
+  PreviewWebhookRejectedError,
+} from './createPreviewWebhookClient'
+export type { PreviewWebhookClient, CreatePreviewWebhookClientParams } from './createPreviewWebhookClient'
+
+export { startPreviewScript, DEFAULT_PREVIEW_SCRIPT } from './startPreviewScript'
+export type { PreviewScriptStep, StartPreviewScriptParams } from './startPreviewScript'

package/src/preview/mockEventSource.ts

@@ -0,0 +1,53 @@
+/**
+ * `EventSource` só existe com um servidor HTTP do outro lado — é justamente o que falta quando se
+ * quer a inbox rodando com dados mockados. Este é o objeto mínimo que satisfaz
+ * `ConversationEventSource`: assina eventos nomeados, desassina e fecha.
+ *
+ * Não imita `EventSource` por completo de propósito: um fake "quase real" convida a depender de
+ * membros que o pacote não usa, e passa a quebrar a cada mudança de runtime.
+ */
+
+import type { ConversationEventSource } from '../providers/types'
+
+export type MockEventSource = ConversationEventSource & {
+  emit(event: string, payload: unknown): void
+  readonly closed: boolean
+}
+
+export function createMockEventSource(): MockEventSource {
+  const listeners = new Map<string, Set<(event: MessageEvent) => void>>()
+  let closed = false
+
+  return {
+    get closed(): boolean {
+      return closed
+    },
+
+    addEventListener(type: string, listener: (event: MessageEvent) => void): void {
+      const typeListeners = listeners.get(type) ?? new Set<(event: MessageEvent) => void>()
+      typeListeners.add(listener)
+      listeners.set(type, typeListeners)
+    },
+
+    removeEventListener(type: string, listener: (event: MessageEvent) => void): void {
+      listeners.get(type)?.delete(listener)
+    },
+
+    close(): void {
+      closed = true
+      listeners.clear()
+    },
+
+    emit(event: string, payload: unknown): void {
+      // Depois de fechado, emitir é no-op: o servidor real também não entrega em socket fechado, e
+      // silenciar aqui é o que faz vazamento de listener aparecer como bug de cleanup, não como
+      // evento fantasma na UI.
+      if (closed) return
+
+      // `data` é string no fio; entregar o objeto já parseado esconderia erro de serialização que
+      // aparece em produção.
+      const messageEvent = new MessageEvent(event, { data: JSON.stringify(payload) })
+      for (const listener of listeners.get(event) ?? []) listener(messageEvent)
+    },
+  }
+}

package/src/preview/preview.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from 'bun:test'
+import { createMockConversationsApi } from './createMockConversationsApi'
+import { createMockSSEProvider } from './createMockSSEProvider'
+import { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES } from './previewFixtures'
+import { createPreviewStore, type PreviewStore } from './previewStore'
+import { DEFAULT_PREVIEW_SCRIPT } from './startPreviewScript'
+
+function createStore(): PreviewStore {
+  return createPreviewStore({ conversations: PREVIEW_CONVERSATIONS, messages: PREVIEW_MESSAGES })
+}
+
+const WAITING_CONVERSATION_ID = '5511977776666'
+const BOT_CONVERSATION_ID = '5511988887777'
+
+describe('previewStore', () => {
+  it('filtra a fila de espera humana', () => {
+    const store = createStore()
+
+    const waiting = store.listConversations({ waitingHuman: true })
+
+    expect(waiting.map((conversation) => conversation.id)).toEqual([WAITING_CONVERSATION_ID])
+  })
+
+  it('busca por nome e por número', () => {
+    const store = createStore()
+
+    expect(store.listConversations({ search: 'marina' })).toHaveLength(1)
+    expect(store.listConversations({ search: '9777' })).toHaveLength(1)
+  })
+
+  it('assumir a conversa apaga a espera por humano', () => {
+    const store = createStore()
+
+    store.setMode({ conversationId: WAITING_CONVERSATION_ID, mode: 'human', assignedUserId: 'agent-2' })
+    const conversation = store.listConversations().find((item) => item.id === WAITING_CONVERSATION_ID)
+
+    expect(conversation?.mode).toBe('human')
+    expect(conversation?.assignedUserId).toBe('agent-2')
+    expect(conversation?.waitingHuman).toBe(false)
+  })
+
+  it('mensagem recebida incrementa não-lidas e markRead zera', () => {
+    const store = createStore()
+    const before = store.listConversations().find((item) => item.id === BOT_CONVERSATION_ID)?.unread ?? 0
+
+    store.appendMessage({
+      conversationId: BOT_CONVERSATION_ID,
+      content: 'e o troco?',
+      direction: 'inbound',
+      sender: 'customer',
+    })
+    const after = store.listConversations().find((item) => item.id === BOT_CONVERSATION_ID)?.unread
+
+    expect(after).toBe(before + 1)
+
+    store.markRead(BOT_CONVERSATION_ID)
+    expect(store.listConversations().find((item) => item.id === BOT_CONVERSATION_ID)?.unread).toBe(0)
+  })
+})
+
+describe('createMockSSEProvider', () => {
+  // Paridade com o servidor: o evento `message` é ping, não entrega de dados. Se este teste
+  // começar a exigir `content`, o mock passou a mentir sobre o que a produção envia.
+  it('entrega evento message como ping, sem conteúdo, com data serializada', () => {
+    const store = createStore()
+    const sse = createMockSSEProvider({ store })
+    const source = sse.connectConversationStream(BOT_CONVERSATION_ID)
+    const received: string[] = []
+
+    source.addEventListener('message', (event) => received.push(event.data as string))
+    store.appendMessage({
+      conversationId: BOT_CONVERSATION_ID,
+      content: 'oi',
+      direction: 'inbound',
+      sender: 'customer',
+    })
+
+    expect(received).toHaveLength(1)
+    expect(JSON.parse(received[0] ?? '{}')).toEqual({ direction: 'inbound', sender: 'customer' })
+  })
+
+  it('emite mode-changed e data-changed nos canais certos', () => {
+    const store = createStore()
+    const sse = createMockSSEProvider({ store })
+    const conversationEvents: string[] = []
+    const globalEvents: string[] = []
+
+    sse
+      .connectConversationStream(WAITING_CONVERSATION_ID)
+      .addEventListener('mode-changed', () => conversationEvents.push('mode-changed'))
+    sse.connectGlobalStream().addEventListener('data-changed', () => globalEvents.push('data-changed'))
+
+    store.setMode({ conversationId: WAITING_CONVERSATION_ID, mode: 'human', assignedUserId: 'agent-2' })
+
+    expect(conversationEvents).toEqual(['mode-changed'])
+    expect(globalEvents).toEqual(['data-changed'])
+  })
+
+  // A regressão que isto tranca: sem desassinar do store no close, cada remontagem de componente
+  // deixaria um listener preso e a mesma mensagem chegaria duplicada na UI.
+  it('desassina do store ao fechar o stream', () => {
+    const store = createStore()
+    const sse = createMockSSEProvider({ store })
+    const source = sse.connectConversationStream(BOT_CONVERSATION_ID)
+    const received: string[] = []
+
+    source.addEventListener('message', (event) => received.push(event.data as string))
+    source.close()
+    store.appendMessage({
+      conversationId: BOT_CONVERSATION_ID,
+      content: 'oi',
+      direction: 'inbound',
+      sender: 'customer',
+    })
+
+    expect(received).toHaveLength(0)
+  })
+})
+
+describe('createMockConversationsApi', () => {
+  // Modela o fluxo real: o ping avisa, o refetch traz o dado. É o compartilhamento de store que
+  // faz os dois concordarem — com estados separados, o ping anunciaria algo que a query não vê.
+  it('ping do SSE e refetch da API contam a mesma história', async () => {
+    const store = createStore()
+    const api = createMockConversationsApi({ store, latencyMs: 0 })
+    const sse = createMockSSEProvider({ store })
+    const pings: unknown[] = []
+
+    sse.connectConversationStream(BOT_CONVERSATION_ID).addEventListener('message', (event) => {
+      pings.push(JSON.parse(event.data as string))
+    })
+
+    await api.sendMessage(BOT_CONVERSATION_ID, 'já separei aqui')
+    const messages = await api.fetchMessages(BOT_CONVERSATION_ID)
+
+    expect(pings).toEqual([{ direction: 'outbound', sender: 'agent' }])
+    expect(messages.at(-1)?.content).toBe('já separei aqui')
+    expect(messages.at(-1)?.sender).toBe('agent')
+  })
+
+  it('pagina e filtra pela mesma regra do store', async () => {
+    const store = createStore()
+    const api = createMockConversationsApi({ store, latencyMs: 0 })
+
+    const firstPage = await api.fetchConversations({ page: 1, limit: 2 })
+    const waiting = await api.fetchConversations({ waitingHuman: true })
+
+    expect(firstPage).toHaveLength(2)
+    expect(waiting.every((conversation) => conversation.waitingHuman)).toBe(true)
+  })
+
+  it('markRead zera as não-lidas vistas pela lista', async () => {
+    const store = createStore()
+    const api = createMockConversationsApi({ store, latencyMs: 0 })
+
+    await api.markRead(BOT_CONVERSATION_ID)
+    const conversations = await api.fetchConversations()
+
+    expect(conversations.find((item) => item.id === BOT_CONVERSATION_ID)?.unread).toBe(0)
+  })
+})
+
+describe('roteiro padrão', () => {
+  // O roteiro é o que faz a inbox deixar de ser tela estática; se algum passo apontar para uma
+  // conversa que não existe nas fixtures, ele passa a ser no-op silencioso.
+  it('todos os passos alteram o estado das conversas das fixtures', () => {
+    const store = createStore()
+    const before = JSON.stringify(store.listConversations())
+
+    for (const step of DEFAULT_PREVIEW_SCRIPT) step(store)
+
+    expect(JSON.stringify(store.listConversations())).not.toBe(before)
+    expect(store.listMessages(WAITING_CONVERSATION_ID).at(-1)?.sender).toBe('agent')
+  })
+})

package/src/preview/previewFixtures.ts

@@ -0,0 +1,153 @@
+/**
+ * Conversas de partida do preview. Cobrem o espaço de estados que a inbox precisa saber desenhar —
+ * bot em atendimento, cliente esperando humano, conversa já assumida por atendente, conversa com
+ * áudio — porque estado que não aparece em fixture é estado que ninguém testa.
+ */
+
+import type { MessagePayload } from '../types'
+import type { ConversationSummary } from '../providers/types'
+
+// Datas fixas: fixture com data relativa ao relógio faz o mesmo cenário renderizar diferente a
+// cada execução, e separadores de dia deixam de ser verificáveis.
+const BASE_DAY = '2026-07-26'
+
+function at(time: string): string {
+  return `${BASE_DAY}T${time}.000Z`
+}
+
+export const PREVIEW_CONVERSATIONS: readonly ConversationSummary[] = [
+  {
+    id: '5511988887777',
+    whatsappNumber: '5511988887777',
+    clientName: 'Marina Alves',
+    lastContent: 'quero 2kg de arroz e um óleo',
+    lastDirection: 'inbound',
+    lastAt: at('14:32:00'),
+    lastInboundAt: at('14:32:00'),
+    mode: 'bot',
+    assignedUserId: null,
+    waitingHuman: false,
+    unread: 2,
+    currentState: 'list_review',
+  },
+  {
+    id: '5511977776666',
+    whatsappNumber: '5511977776666',
+    clientName: 'Diego Prado',
+    lastContent: 'preciso falar com alguém',
+    lastDirection: 'inbound',
+    lastAt: at('14:20:00'),
+    lastInboundAt: at('14:20:00'),
+    mode: 'bot',
+    assignedUserId: null,
+    waitingHuman: true,
+    unread: 1,
+    currentState: 'awaiting_human',
+  },
+  {
+    id: '5511966665555',
+    whatsappNumber: '5511966665555',
+    clientName: 'Sofia Nakamura',
+    lastContent: 'já separei seu pedido, confere?',
+    lastDirection: 'outbound',
+    lastAt: at('13:58:00'),
+    lastInboundAt: at('13:50:00'),
+    mode: 'human',
+    assignedUserId: 'agent-1',
+    waitingHuman: false,
+    unread: 0,
+    currentState: 'human_handling',
+  },
+  {
+    id: '5511955554444',
+    whatsappNumber: '5511955554444',
+    lastContent: 'Áudio',
+    lastDirection: 'inbound',
+    lastAt: at('13:31:00'),
+    lastInboundAt: at('13:31:00'),
+    mode: 'bot',
+    assignedUserId: null,
+    waitingHuman: false,
+    unread: 1,
+    currentState: 'list_import',
+  },
+]
+
+export const PREVIEW_MESSAGES: Readonly<Record<string, readonly MessagePayload[]>> = {
+  '5511988887777': [
+    {
+      id: 'fixture-1',
+      type: 'text',
+      content: 'oi, boa tarde',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('14:30:00'),
+    },
+    {
+      id: 'fixture-2',
+      type: 'text',
+      content: 'Boa tarde! Me manda sua lista de compras que eu monto o carrinho.',
+      direction: 'outbound',
+      sender: 'bot',
+      timestamp: at('14:30:30'),
+      status: 'read',
+    },
+    {
+      id: 'fixture-3',
+      type: 'text',
+      content: 'quero 2kg de arroz e um óleo',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('14:32:00'),
+    },
+  ],
+  '5511977776666': [
+    {
+      id: 'fixture-4',
+      type: 'text',
+      content: 'esse valor do frete está certo?',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('14:19:00'),
+    },
+    {
+      id: 'fixture-5',
+      type: 'text',
+      content: 'preciso falar com alguém',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('14:20:00'),
+    },
+  ],
+  '5511966665555': [
+    {
+      id: 'fixture-6',
+      type: 'text',
+      content: 'consegue trocar o leite integral por desnatado?',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('13:50:00'),
+    },
+    {
+      id: 'fixture-7',
+      type: 'text',
+      content: 'já separei seu pedido, confere?',
+      direction: 'outbound',
+      sender: 'agent',
+      timestamp: at('13:58:00'),
+      status: 'delivered',
+      agentName: 'Ana',
+    },
+  ],
+  '5511955554444': [
+    {
+      id: 'fixture-8',
+      type: 'audio',
+      mediaId: 'preview-audio-1',
+      mimeType: 'audio/ogg',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('13:31:00'),
+    },
+  ],
+}