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

package/dist/preview/index.d.ts

@@ -0,0 +1,373 @@
+import { G as MessagePayload, o as ConversationSummary, m as ConversationEventSource, q as ConversationsApi, L as ListConversationsParams, n as ConversationPage, S as SSEProvider, k as ConversationDocument, K as ResolveMediaUrl } from '../types-O7kMP1Yn.js';
+export { A as AudioRecorderButton, a as AudioRecorderButtonLabels, b as AudioRecorderButtonProps, D as DEFAULT_AUDIO_RECORDER_BUTTON_LABELS } from '../types-O7kMP1Yn.js';
+import * as react from 'react';
+import { InteractiveReplyOption, InboundMediaType } from '@adatechnology/meta-whatsapp-contracts/testing';
+
+/**
+ * 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.
+ */
+
+declare const GLOBAL_CHANNEL = "global";
+declare function conversationChannel(conversationId: string): string;
+type PreviewEmission = {
+    readonly channel: string;
+    readonly event: string;
+    readonly payload: Record<string, unknown>;
+};
+type PreviewStoreListener = (emission: PreviewEmission) => void;
+type AppendMessageParams = {
+    readonly conversationId: string;
+    readonly content: string;
+    readonly direction: MessagePayload['direction'];
+    readonly sender: MessagePayload['sender'];
+};
+type SetModeParams = {
+    readonly conversationId: string;
+    readonly mode: ConversationSummary['mode'];
+    readonly assignedUserId?: string | undefined;
+};
+type ListConversationsFilters = {
+    readonly waitingHuman?: boolean;
+    readonly search?: string;
+};
+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;
+};
+type CreatePreviewStoreParams = {
+    readonly conversations: readonly ConversationSummary[];
+    readonly messages: Readonly<Record<string, readonly MessagePayload[]>>;
+    readonly now?: () => Date;
+};
+declare function createPreviewStore(params: CreatePreviewStoreParams): PreviewStore;
+
+/**
+ * `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.
+ */
+
+type MockEventSource = ConversationEventSource & {
+    emit(event: string, payload: unknown): void;
+    readonly closed: boolean;
+};
+declare function createMockEventSource(): MockEventSource;
+
+/**
+ * `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.
+ */
+
+type CreateMockConversationsApiParams = {
+    readonly store: PreviewStore;
+    readonly latencyMs?: number;
+    readonly agentName?: string;
+};
+/**
+ * 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.
+ */
+type MockConversationsApi = Omit<ConversationsApi, 'fetchConversations'> & {
+    fetchConversations(params?: ListConversationsParams): Promise<ConversationPage>;
+};
+declare function createMockConversationsApi(params: CreateMockConversationsApiParams): MockConversationsApi;
+
+/**
+ * `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.
+ */
+
+type CreateMockSSEProviderParams = {
+    readonly store: PreviewStore;
+};
+declare function createMockSSEProvider(params: CreateMockSSEProviderParams): SSEProvider;
+
+/**
+ * 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.
+ */
+
+declare const PREVIEW_CONVERSATIONS: readonly ConversationSummary[];
+declare const PREVIEW_MESSAGES: Readonly<Record<string, readonly MessagePayload[]>>;
+declare const PREVIEW_DOCUMENTS: Readonly<Record<string, readonly ConversationDocument[]>>;
+
+/**
+ * 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.
+ *
+ * ⚠️ 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 = {
+    sendText(text: string): Promise<void>;
+    sendButtonReply(reply: InteractiveReplyOption): Promise<void>;
+    sendListReply(reply: InteractiveReplyOption): Promise<void>;
+    sendAudio(mediaId: string): Promise<void>;
+    sendMedia(params: SendPreviewMediaParams): Promise<void>;
+};
+type SendPreviewMediaParams = {
+    readonly mediaType: InboundMediaType;
+    /**
+     * Id que o host já usa para buscar o arquivo. Não é bytes: o webhook da Meta entrega mídia por
+     * referência, e o consumidor baixa depois — mandar base64 aqui simularia um payload que a Meta
+     * nunca produz, e o caminho testado deixaria de ser o de produção.
+     */
+    readonly mediaId: string;
+    readonly mimeType?: string;
+    readonly filename?: string;
+    readonly caption?: string;
+};
+type CreatePreviewWebhookClientParams = {
+    readonly webhookUrl: string;
+    readonly appSecret: string;
+    readonly from: string;
+    readonly phoneNumberId?: string;
+    readonly fetchImplementation?: typeof fetch;
+};
+declare class PreviewInProductionError extends Error {
+    constructor();
+}
+declare class PreviewWebhookRejectedError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+/**
+ * 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.
+ */
+declare function assertPreviewEnvironment(isProduction: boolean): void;
+/**
+ * Assina um texto qualquer com o app secret, no mesmo formato do header da Meta.
+ *
+ * Exportada porque o preview precisa provar identidade em MAIS de um lugar: além de entregar a
+ * mensagem no webhook, ele lê o transcript de volta — e ler pela API de admin exigia uma sessão que
+ * a aba do simulador não tem. Assinar a leitura com o segredo que ele já carrega resolve sem token
+ * de admin e sem rota aberta.
+ */
+declare function signPreviewPayload(params: {
+    rawBody: string;
+    appSecret: string;
+}): Promise<string>;
+declare function createPreviewWebhookClient(params: CreatePreviewWebhookClientParams): PreviewWebhookClient;
+
+type ConversationPreviewProps = {
+    client: PreviewWebhookClient;
+    sse: SSEProvider;
+    conversationId: string;
+    loadMessages: (conversationId: string) => Promise<MessagePayload[]>;
+    placeholder?: string;
+    /**
+     * Recarrega o transcript a cada N ms. Serve a host SEM stream: a resposta do bot é assíncrona, e
+     * sem SSE nem polling ela só apareceria no próximo envio — o sintoma é "às vezes ele não
+     * responde". Ausente, não faz polling (host com SSE não precisa).
+     */
+    pollIntervalMs?: number;
+    /**
+     * Como transformar um arquivo do disco (ou o áudio gravado) na referência que o webhook carrega.
+     * O caminho da Meta entrega mídia por `id`, e quem sabe hospedar o arquivo é o host — a SDK não
+     * inventa um endpoint de upload. Ausente, o compositor não oferece anexo nem gravação: melhor um
+     * botão que não existe do que um que falha ao ser tocado.
+     */
+    uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>;
+};
+type PreviewUploadedMedia = {
+    readonly mediaId: string;
+    readonly mimeType?: string;
+    readonly filename?: string;
+};
+/** Deriva o tipo de mídia do WhatsApp a partir do MIME do arquivo escolhido. */
+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)
+ * 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.
+ */
+
+type PreviewScriptStep = (store: PreviewStore) => void;
+declare const DEFAULT_PREVIEW_SCRIPT: readonly PreviewScriptStep[];
+type StartPreviewScriptParams = {
+    readonly store: PreviewStore;
+    readonly intervalMs?: number;
+    readonly steps?: readonly PreviewScriptStep[];
+};
+declare function startPreviewScript(params: StartPreviewScriptParams): () => void;
+
+/**
+ * Bytes de verdade para o preview abrir.
+ *
+ * O mock antes devolvia a MESMA imagem PNG para qualquer documento, então clicar em "visualizar" num
+ * PDF entregava um PNG rotulado `application/pdf` e o leitor dizia que o arquivo era inválido. Cada
+ * amostra aqui é um arquivo mínimo porém legítimo do seu tipo: as de mídia foram geradas com ffmpeg
+ * e conferidas com ffprobe, o PDF tem xref/startxref/%%EOF, e os pacotes Office são zips com as
+ * partes obrigatórias (`[Content_Types].xml`, `_rels/.rels`, o documento).
+ *
+ * Não há amostra de `audio/amr`, `video/3gp` nem dos formatos binários legados do Office
+ * (`application/msword`, `application/vnd.ms-excel`, `application/vnd.ms-powerpoint`): não há
+ * encoder para eles nesta máquina e forjar OLE2 à mão daria arquivo corrompido — exatamente o que
+ * este módulo existe para evitar. Esses caem no texto explicativo de `resolvePreviewFileSample`,
+ * que abre sem erro e diz o que é.
+ *
+ * GERADO — não editar à mão.
+ */
+declare const PREVIEW_FILE_SAMPLES: Readonly<Record<string, string>>;
+/**
+ * A data URL que o preview abre para um documento.
+ *
+ * Ordem: tipo exato → família (`audio/amr` toca como mp3, `video/3gp` como mp4) → nota em texto.
+ * A nota fecha o caso dos tipos sem amostra: abre num leitor de texto e explica, em vez de baixar
+ * um binário quebrado com extensão de Word.
+ */
+declare function resolvePreviewFileSample(mimeType: string | undefined, filename?: string): string;
+
+/**
+ * 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.
+ */
+
+/** URL que o preview pode abrir em aba nova. Cai na data URL fora do navegador (teste, SSR). */
+declare function previewFileUrl(mimeType: string | undefined, filename?: string): string;
+/**
+ * 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.
+ */
+declare function previewFileBase64(mimeType: string | undefined, filename?: string): {
+    mimeType: string;
+    data: string;
+};
+/**
+ * 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.
+ */
+declare function createPreviewMediaResolver(): ResolveMediaUrl;
+
+/**
+ * Bancada de teste manual de mídia — montável em uma linha por qualquer projeto que adote o SDK.
+ *
+ * Existe porque o defeito que ela pega não é pegável por teste automatizado: "o PDF abre?" depende
+ * do leitor do navegador, "o vídeo toca?" do decodificador, e "a aba abre?" da política do Chrome
+ * sobre `data:` URL. Teste unitário confere bytes; só o olho confere que o arquivo abre. Sem uma
+ * superfície pronta no pacote, cada projeto teria de montar a sua — e, na prática, nenhum montava.
+ *
+ * Traz o próprio store, o próprio mock e o próprio provider: o host não injeta nada. E não passa
+ * `onResolveMediaUrl` em lugar nenhum de propósito — é o `MessageBubble` resolvendo mídia pelo
+ * `ConversationsApi` do contexto, então se essa resolução automática quebrar, esta tela mostra.
+ */
+/** A conversa do fixture que carrega uma mensagem de cada tipo aceito. */
+declare const MEDIA_TYPES_CONVERSATION_ID = "5511944443333";
+type MediaTypesPreviewProps = {
+    /** Outra conversa do fixture, se o projeto tiver acrescentado a sua. */
+    conversationId?: string;
+    className?: string;
+};
+declare function MediaTypesPreview({ conversationId, className, }: MediaTypesPreviewProps): react.JSX.Element;
+
+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 };