@adatechnology/conversations-ui 0.1.0-rc.17 → 0.1.0-rc.18

package/dist/preview/index.d.ts

@@ -120,9 +120,14 @@ declare const PREVIEW_DOCUMENTS: Readonly<Record<string, readonly ConversationDo
  * 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 é.
+ * ⚠️ SOMENTE EXECUÇÃO LOCAL. Isto carrega o app secret no bundle, e bundle é público onde quer que
+ * seja servido — em qualquer ambiente com URL acessível (homologação inclusive) usar esta fábrica
+ * equivale a publicar o segredo, e quem o tiver forja webhooks válidos daquele app da Meta: injeta
+ * mensagem de qualquer número e dispara os fluxos. `assertPreviewEnvironment` barra produção, mas
+ * homologação passaria, então a barreira não basta.
+ *
+ * Para qualquer ambiente publicado use `createPreviewBridgeClient`: o navegador manda a intenção e
+ * o servidor assina com o segredo que ele já tem.
  */
 
 type PreviewWebhookClient = {
@@ -206,6 +211,67 @@ type PreviewUploadedMedia = {
 declare function mediaTypeOf(mimeType: string): SendPreviewMediaParams['mediaType'];
 declare function ConversationPreview({ client, sse, conversationId, loadMessages, placeholder, pollIntervalMs, uploadMedia, }: ConversationPreviewProps): react.JSX.Element;
 
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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);
+type SendPreviewInboundCommand = (command: PreviewInboundCommand) => Promise<void>;
+declare class PreviewBridgeRejectedError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+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;
+};
+declare function createPreviewBridgeClient(params: CreatePreviewBridgeClientParams): PreviewWebhookClient;
+
 /**
  * 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)
@@ -304,4 +370,4 @@ type MediaTypesPreviewProps = {
 };
 declare function MediaTypesPreview({ conversationId, className, }: MediaTypesPreviewProps): react.JSX.Element;
 
-export { type AppendMessageParams, ConversationPreview, type ConversationPreviewProps, type CreateMockConversationsApiParams, type CreateMockSSEProviderParams, type CreatePreviewStoreParams, type CreatePreviewWebhookClientParams, DEFAULT_PREVIEW_SCRIPT, GLOBAL_CHANNEL, type ListConversationsFilters, MEDIA_TYPES_CONVERSATION_ID, MediaTypesPreview, type MediaTypesPreviewProps, type MockEventSource, PREVIEW_CONVERSATIONS, PREVIEW_DOCUMENTS, PREVIEW_FILE_SAMPLES, PREVIEW_MESSAGES, type PreviewEmission, PreviewInProductionError, type PreviewScriptStep, type PreviewStore, type PreviewStoreListener, type PreviewUploadedMedia, type PreviewWebhookClient, PreviewWebhookRejectedError, type SendPreviewMediaParams, type SetModeParams, type StartPreviewScriptParams, assertPreviewEnvironment, conversationChannel, createMockConversationsApi, createMockEventSource, createMockSSEProvider, createPreviewMediaResolver, createPreviewStore, createPreviewWebhookClient, mediaTypeOf, previewFileBase64, previewFileUrl, resolvePreviewFileSample, signPreviewPayload, startPreviewScript };
+export { type AppendMessageParams, ConversationPreview, type ConversationPreviewProps, type CreateMockConversationsApiParams, type CreateMockSSEProviderParams, type CreatePreviewBridgeClientParams, type CreatePreviewStoreParams, type CreatePreviewWebhookClientParams, DEFAULT_PREVIEW_SCRIPT, GLOBAL_CHANNEL, type ListConversationsFilters, MEDIA_TYPES_CONVERSATION_ID, MediaTypesPreview, type MediaTypesPreviewProps, type MockEventSource, PREVIEW_CONVERSATIONS, PREVIEW_DOCUMENTS, PREVIEW_FILE_SAMPLES, PREVIEW_MESSAGES, PreviewBridgeRejectedError, type PreviewEmission, PreviewInProductionError, type PreviewInboundCommand, type PreviewScriptStep, type PreviewStore, type PreviewStoreListener, type PreviewUploadedMedia, type PreviewWebhookClient, PreviewWebhookRejectedError, type SendPreviewInboundCommand, type SendPreviewMediaParams, type SetModeParams, type StartPreviewScriptParams, assertPreviewEnvironment, conversationChannel, createMockConversationsApi, createMockEventSource, createMockSSEProvider, createPreviewBridgeClient, createPreviewMediaResolver, createPreviewStore, createPreviewWebhookClient, mediaTypeOf, previewFileBase64, previewFileUrl, resolvePreviewFileSample, signPreviewPayload, startPreviewScript };

package/dist/preview/index.js

@@ -1092,6 +1092,43 @@ function createPreviewWebhookClient(params) {
   };
 }
 
+// src/preview/createPreviewBridgeClient.ts
+var PreviewBridgeRejectedError = class extends Error {
+  constructor(status) {
+    super(`A rota de preview do host recusou a entrega (HTTP ${status}).`);
+    this.status = status;
+    this.name = "PreviewBridgeRejectedError";
+  }
+};
+function buildFetchSender(params) {
+  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);
+  };
+}
+function createPreviewBridgeClient(params) {
+  const send = params.sendCommand ?? buildFetchSender(params);
+  const from = params.from;
+  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 })
+  };
+}
+
 // src/preview/startPreviewScript.ts
 var DEFAULT_PREVIEW_SCRIPT = [
   (store) => store.appendMessage({
@@ -1189,6 +1226,7 @@ export {
   PREVIEW_DOCUMENTS,
   PREVIEW_FILE_SAMPLES,
   PREVIEW_MESSAGES,
+  PreviewBridgeRejectedError,
   PreviewInProductionError,
   PreviewWebhookRejectedError,
   assertPreviewEnvironment,
@@ -1196,6 +1234,7 @@ export {
   createMockConversationsApi,
   createMockEventSource,
   createMockSSEProvider,
+  createPreviewBridgeClient,
   createPreviewMediaResolver,
   createPreviewStore,
   createPreviewWebhookClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/conversations-ui",
-  "version": "0.1.0-rc.17",
+  "version": "0.1.0-rc.18",
   "description": "WhatsApp conversation UI components — parametrizável por endpoint, tema e feature flags",
   "publishConfig": {
     "access": "public"

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,88 @@
+/**
+ * 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 type { PreviewWebhookClient, SendPreviewMediaParams } from './createPreviewWebhookClient'
+
+/**
+ * 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
+}
+
+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)
+  }
+}
+
+export function createPreviewBridgeClient(params: CreatePreviewBridgeClientParams): PreviewWebhookClient {
+  const send = params.sendCommand ?? buildFetchSender(params)
+  const from = params.from
+
+  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 }),
+  }
+}
+
+export type { InboundMediaType }

package/src/preview/createPreviewWebhookClient.ts

@@ -6,9 +6,14 @@
  * 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 é.
+ * ⚠️ SOMENTE EXECUÇÃO LOCAL. Isto carrega o app secret no bundle, e bundle é público onde quer que
+ * seja servido — em qualquer ambiente com URL acessível (homologação inclusive) usar esta fábrica
+ * equivale a publicar o segredo, e quem o tiver forja webhooks válidos daquele app da Meta: injeta
+ * mensagem de qualquer número e dispara os fluxos. `assertPreviewEnvironment` barra produção, mas
+ * homologação passaria, então a barreira não basta.
+ *
+ * Para qualquer ambiente publicado use `createPreviewBridgeClient`: o navegador manda a intenção e
+ * o servidor assina com o segredo que ele já tem.
  */
 
 import {

package/src/preview/index.ts

@@ -45,6 +45,13 @@ export type {
   SendPreviewMediaParams,
 } from './createPreviewWebhookClient'
 
+export { createPreviewBridgeClient, PreviewBridgeRejectedError } from './createPreviewBridgeClient'
+export type {
+  CreatePreviewBridgeClientParams,
+  PreviewInboundCommand,
+  SendPreviewInboundCommand,
+} from './createPreviewBridgeClient'
+
 export { startPreviewScript, DEFAULT_PREVIEW_SCRIPT } from './startPreviewScript'
 export type { PreviewScriptStep, StartPreviewScriptParams } from './startPreviewScript'
 export { PREVIEW_FILE_SAMPLES, resolvePreviewFileSample } from './previewFileSamples'