@adatechnology/conversations-ui 0.1.0-rc.34 → 0.1.0-rc.36

package/dist/{types-De5aN-E_.d.ts → ConversationSimulatorPanel--5fIzXWY.d.ts}

@@ -1,4 +1,6 @@
 import * as react from 'react';
+import { ReactNode } from 'react';
+import { InteractiveReplyOption, InboundMediaType } from '@adatechnology/meta-whatsapp-contracts/testing';
 
 interface ConversationsUIConfig {
     apiBaseUrl: string;
@@ -499,4 +501,304 @@ interface ConversationDocument {
     linkedAt: string;
 }
 
-export { AudioRecorderButton as A, type ListDocumentsParams as B, CHANNEL_CAPABILITIES as C, DEFAULT_AUDIO_RECORDER_BUTTON_LABELS as D, type MediaRendererProps as E, type FormatContactHandleParams as F, type MessagePayload as G, HANDLE_KIND as H, type InteractiveOption as I, type MessageTranscription as J, type ReopenMechanism as K, type ListConversationsParams as L, MediaRenderer as M, type ResolveMediaUrl as N, type TranscriptionStatus as O, capabilitiesOf as P, channelFiltersFor as Q, REOPEN_MECHANISM as R, type SSEProvider as S, type TranscriptionMode as T, contactFlag as U, formatContactHandle as V, type AudioRecorderButtonLabels as a, type AudioRecorderButtonProps as b, CHANNEL_FILTER_ALL as c, CONVERSATION_CHANNEL as d, type ChannelCapabilities as e, type ChannelFilter as f, type ChannelFilterOption as g, type CompanyDocument as h, type CompanyDocumentPage as i, type ConversationChannel as j, type ConversationDocument as k, type ConversationDocumentPage as l, type ConversationEventSource as m, type ConversationPage as n, type ConversationSummary as o, type ConversationTemplate as p, type ConversationsApi as q, type ConversationsFeatures as r, type ConversationsTheme as s, type ConversationsUIConfig as t, DEFAULT_CONVERSATION_CHANNEL as u, DEFAULT_MAX_RECORDING_MILLISECONDS as v, type HandleKind as w, type InteractivePayload as x, type InteractiveSection as y, type InteractiveSelection as z };
+/**
+ * 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.
+ */
+
+type PreviewUploadedMedia$1 = {
+    readonly mediaId: string;
+    readonly mimeType?: string;
+    readonly filename?: string;
+};
+type PreviewMediaUploadRequest = {
+    readonly base64: string;
+    readonly mimeType: string;
+    readonly filename: string;
+};
+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;
+};
+declare function createPreviewMediaUploader(params: CreatePreviewMediaUploaderParams): (file: File) => Promise<PreviewUploadedMedia$1>;
+
+/**
+ * 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>;
+    /**
+     * 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$1>;
+};
+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;
+    /**
+     * 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;
+    readonly fetchImplementation?: typeof fetch;
+};
+/** Falha da rota de upload, separada da do webhook: os dois lados quebram por motivos diferentes. */
+declare class PreviewMediaUploadRejectedError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+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 const DEFAULT_MEDIA_UPLOAD_PATH = "/v1/preview/media";
+/**
+ * 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.
+ */
+declare function createPreviewMediaPoster(params: {
+    readonly url: string;
+    readonly headers?: (mimeType: string) => Promise<Readonly<Record<string, string>>>;
+    readonly fetchImplementation?: typeof fetch;
+}): (file: File) => Promise<PreviewUploadedMedia$1>;
+declare function createPreviewWebhookClient(params: CreatePreviewWebhookClientParams): PreviewWebhookClient;
+
+/**
+ * Copyright (c) 2026 Ada Technology. All rights reserved.
+ *
+ * This source code is proprietary and confidential. Unauthorized copying,
+ * modification, distribution, or use of this file, via any medium, is
+ * strictly prohibited without prior written permission from Ada Technology.
+ *
+ * Author: Anderson Filho <andersonfrfilho@gmail.com>
+ *
+ * Porta do simulador: o que a visão lado-cliente precisa saber fazer, sem canal no nome.
+ *
+ * O simulador nasceu falando WhatsApp — `PreviewWebhookClient`, payload assinado, mídia por
+ * `mediaId`. Só que a mesma casa atende pelo chat do próprio site, e simular ali não é uma segunda
+ * tela: é o mesmo painel, no mesmo lugar da conversa, com outro transporte. Sem esta porta cada
+ * canal novo viraria uma cópia da tela — e cópia de tela diverge, que é exatamente o que o
+ * `ConversationSimulatorPanel` existe para ter parado.
+ *
+ * O que é específico de canal fica no adaptador, nunca aqui:
+ * - **resposta de menu:** a Meta distingue `button_reply` de `list_reply`, e o roteador do fluxo lê
+ *   campos diferentes; o chat do site manda o rótulo como texto, que é literalmente o que o
+ *   visitante produz ao tocar no botão do widget. A porta entrega a seleção inteira e deixa cada
+ *   adaptador escolher a forma de fio.
+ * - **mídia:** a Meta entrega por REFERÊNCIA (sobe o arquivo primeiro, o webhook carrega o `id`); o
+ *   widget manda os BYTES no `FormData`. A porta trafega o `File` que a tela tem em mão — quem
+ *   tiver passo de upload faz o upload por dentro.
+ */
+
+/**
+ * Tipos de mídia que o cliente pode mandar de dentro do simulador.
+ *
+ * Subconjunto proposital do que a Meta aceita: `sticker` chega do aparelho, mas não há como
+ * escolher um no seletor de arquivo do navegador — oferecer o tipo aqui seria um caminho morto.
+ */
+type SimulatorMediaKind = 'image' | 'video' | 'audio' | 'document';
+/** Os tipos que saem do seletor de arquivo. `audio` fica de fora: ele vem do microfone. */
+declare const SIMULATOR_FILE_MEDIA_KINDS: readonly SimulatorMediaKind[];
+/** Deriva o tipo de mídia a partir do MIME do arquivo escolhido. */
+declare function mediaKindOf(mimeType: string): SimulatorMediaKind;
+type SendSimulatorMediaParams = {
+    readonly mediaKind: SimulatorMediaKind;
+    /** O arquivo do disco ou o áudio recém-gravado. Referência × bytes é decisão do adaptador. */
+    readonly file: File;
+    readonly mimeType?: string;
+    readonly filename?: string;
+    readonly caption?: string;
+};
+type ConversationSimulatorClient = {
+    sendText(text: string): Promise<void>;
+    sendReply(selection: InteractiveSelection): Promise<void>;
+    /**
+     * Ausente = este canal não recebe mídia do cliente, e o compositor não desenha clipe nem
+     * microfone. Melhor um botão que não existe do que um que falha ao ser tocado.
+     */
+    sendMedia?(params: SendSimulatorMediaParams): Promise<void>;
+    /**
+     * Restringe o que `sendMedia` aceita. Ausente = todos os tipos.
+     *
+     * Existe porque canal com meia capacidade é comum: o chat do site sobe áudio (a API transcreve)
+     * mas não tem rota para imagem. Sem esta lista o clipe e o microfone apareciam juntos, e um dos
+     * dois falhava ao ser tocado.
+     */
+    readonly acceptedMediaKinds?: readonly SimulatorMediaKind[];
+};
+/** Responde se o compositor deve desenhar o affordance daquele tipo. */
+declare function acceptsMediaKind(client: ConversationSimulatorClient, kind: SimulatorMediaKind): boolean;
+type ToSimulatorClientParams = {
+    readonly client: PreviewWebhookClient;
+    /** Destino alternativo do upload. Sem isto, usa o do próprio `client`. */
+    readonly uploadMedia?: (file: File) => Promise<PreviewUploadedMedia$1>;
+};
+/**
+ * Distingue a porta neutra do cliente WhatsApp legado, que continua aceito na prop.
+ *
+ * Leitura estrutural e não `instanceof`: os dois são objetos literais devolvidos por fábrica, e o
+ * host pode ter montado o seu à mão.
+ */
+declare function isConversationSimulatorClient(candidate: ConversationSimulatorClient | PreviewWebhookClient): candidate is ConversationSimulatorClient;
+/**
+ * Adapta o cliente WhatsApp (webhook assinado ou ponte) para a porta neutra.
+ *
+ * O upload vive aqui dentro porque ele é uma etapa DO CANAL: no caminho da Meta a mídia precisa
+ * existir como `id` antes do webhook citá-la. Sem passo de upload disponível, `sendMedia` sai
+ * ausente — é o que mantém o clipe escondido em host que não montou destino para o arquivo, o
+ * comportamento que já existia antes desta porta.
+ */
+declare function toConversationSimulatorClient({ client, uploadMedia, }: ToSimulatorClientParams): ConversationSimulatorClient;
+
+type ConversationPreviewProps = {
+    /**
+     * Transporte do canal. `PreviewWebhookClient` continua aceito — é o caminho WhatsApp de antes
+     * desta porta, adaptado aqui dentro para não obrigar host nenhum a mudar de chamada.
+     */
+    client: ConversationSimulatorClient | 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;
+    /**
+     * Destino alternativo do upload, no canal que sobe a mídia antes de citá-la (o caminho da Meta
+     * entrega mídia por `id`). Sem isto, usa o do próprio `client`. Canal que manda os bytes direto
+     * ignora esta prop: quem decide referência × bytes é o adaptador do canal.
+     */
+    uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>;
+};
+type PreviewUploadedMedia = {
+    readonly mediaId: string;
+    readonly mimeType?: string;
+    readonly filename?: string;
+};
+/** @deprecated Use `mediaKindOf`, que não nomeia canal. Mantido para quem já importa. */
+declare function mediaTypeOf(mimeType: string): SimulatorMediaKind;
+declare function ConversationPreview({ client, sse, conversationId, loadMessages, placeholder, pollIntervalMs, uploadMedia, }: ConversationPreviewProps): react.JSX.Element;
+
+type ConversationSimulatorPanelLabels = {
+    readonly title: string;
+    /** Complementa o identificador no subtítulo, explicando para onde a mensagem realmente vai. */
+    readonly destinationHint: string;
+    readonly close: string;
+    readonly placeholder: string;
+};
+declare const DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS: ConversationSimulatorPanelLabels;
+/** Rótulos do painel já resolvidos para o canal — útil para o host que monta o cabeçalho por fora. */
+declare function simulatorPanelLabelsOf(channel: ConversationChannel | undefined): ConversationSimulatorPanelLabels;
+type ConversationSimulatorPanelProps = Omit<ConversationPreviewProps, 'placeholder'> & {
+    readonly onClose: () => void;
+    /** Ausente = WhatsApp, que era o único canal antes desta prop existir. */
+    readonly channel?: ConversationChannel;
+    /**
+     * Identificador do contato já formatado para leitura — telefone no WhatsApp, apelido no Instagram,
+     * "Visitante 3f9c21" no chat do site. É o host que formata: máscara de telefone é convenção
+     * regional, e o pacote não tem como saber a do produto.
+     */
+    readonly displayHandle?: string;
+    /** @deprecated Use `displayHandle` — o simulador deixou de ser só telefone. */
+    readonly displayNumber?: string;
+    readonly labels?: Partial<ConversationSimulatorPanelLabels>;
+    /** Ações extras no cabeçalho — roteiro automático, limpar conversa, trocar de contato. */
+    readonly headerActions?: ReactNode;
+};
+declare function ConversationSimulatorPanel({ onClose, channel, displayHandle, displayNumber, labels, headerActions, ...previewProps }: ConversationSimulatorPanelProps): react.JSX.Element;
+
+export { type PreviewWebhookClient as $, AudioRecorderButton as A, type CreatePreviewMediaUploaderParams as B, CHANNEL_CAPABILITIES as C, type CreatePreviewWebhookClientParams as D, DEFAULT_AUDIO_RECORDER_BUTTON_LABELS as E, DEFAULT_CONVERSATION_CHANNEL as F, DEFAULT_CONVERSATION_SIMULATOR_PANEL_LABELS as G, DEFAULT_MAX_RECORDING_MILLISECONDS as H, DEFAULT_MEDIA_UPLOAD_PATH as I, type FormatContactHandleParams as J, HANDLE_KIND as K, type HandleKind as L, type InteractiveOption as M, type InteractivePayload as N, type InteractiveSection as O, type InteractiveSelection as P, type ListConversationsParams as Q, type ListDocumentsParams as R, MediaRenderer as S, type MediaRendererProps as T, type MessagePayload as U, type MessageTranscription as V, PreviewInProductionError as W, PreviewMediaUploadRejectedError as X, type PreviewMediaUploadRequest as Y, type PreviewUploadedMedia$1 as Z, type PreviewUploadedMedia as _, type AudioRecorderButtonLabels as a, PreviewWebhookRejectedError as a0, REOPEN_MECHANISM as a1, type ReopenMechanism as a2, type ResolveMediaUrl as a3, SIMULATOR_FILE_MEDIA_KINDS as a4, type SSEProvider as a5, type SendPreviewMediaParams as a6, type SendSimulatorMediaParams as a7, type SimulatorMediaKind as a8, type ToSimulatorClientParams as a9, type TranscriptionMode as aa, type TranscriptionStatus as ab, acceptsMediaKind as ac, assertPreviewEnvironment as ad, capabilitiesOf as ae, channelFiltersFor as af, contactFlag as ag, createPreviewMediaPoster as ah, createPreviewMediaUploader as ai, createPreviewWebhookClient as aj, formatContactHandle as ak, isConversationSimulatorClient as al, mediaKindOf as am, mediaTypeOf as an, signPreviewPayload as ao, simulatorPanelLabelsOf as ap, toConversationSimulatorClient as aq, type AudioRecorderButtonProps as b, CHANNEL_FILTER_ALL as c, CONVERSATION_CHANNEL as d, type ChannelCapabilities as e, type ChannelFilter as f, type ChannelFilterOption as g, type CompanyDocument as h, type CompanyDocumentPage as i, type ConversationChannel as j, type ConversationDocument as k, type ConversationDocumentPage as l, type ConversationEventSource as m, type ConversationPage as n, ConversationPreview as o, type ConversationPreviewProps as p, type ConversationSimulatorClient as q, ConversationSimulatorPanel as r, type ConversationSimulatorPanelLabels as s, type ConversationSimulatorPanelProps as t, type ConversationSummary as u, type ConversationTemplate as v, type ConversationsApi as w, type ConversationsFeatures as x, type ConversationsTheme as y, type ConversationsUIConfig as z };