@adatechnology/conversations-ui 0.1.0-rc.8 → 0.1.0

package/dist/ConversationSimulatorPanel--5fIzXWY.d.ts

@@ -0,0 +1,804 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { InteractiveReplyOption, InboundMediaType } from '@adatechnology/meta-whatsapp-contracts/testing';
+
+interface ConversationsUIConfig {
+    apiBaseUrl: string;
+    theme?: ConversationsTheme;
+    features?: ConversationsFeatures;
+}
+interface ConversationsTheme {
+    primaryColor?: string;
+    backgroundColor?: string;
+    bubbleSent?: string;
+    bubbleReceived?: string;
+    textPrimary?: string;
+    textSecondary?: string;
+}
+interface ConversationsFeatures {
+    audio?: boolean;
+    documents?: boolean;
+    emoji?: boolean;
+    darkMode?: boolean;
+}
+/**
+ * Recorte do bloco `interactive` da Meta que a UI precisa para desenhar o menu. Fica solto (e não
+ * espelhando o contrato inteiro) porque o que chega do banco é o payload cru já enviado ao
+ * WhatsApp: qualquer campo que a UI não conheça é ignorado, nunca causa erro de render.
+ */
+interface InteractiveOption {
+    id: string;
+    title: string;
+    description?: string;
+}
+interface InteractiveSection {
+    title?: string;
+    rows?: InteractiveOption[];
+}
+interface InteractivePayload {
+    type?: 'button' | 'list' | string;
+    header?: {
+        text?: string;
+    };
+    body?: {
+        text?: string;
+    };
+    footer?: {
+        text?: string;
+    };
+    action?: {
+        /** Rótulo do botão que abre a lista — só existe em `type: 'list'`. */
+        button?: string;
+        sections?: InteractiveSection[];
+        buttons?: {
+            reply?: InteractiveOption;
+        }[];
+    };
+}
+/** Como o cliente respondeu a um menu: por botão ou por item de lista. */
+type InteractiveSelection = {
+    readonly kind: 'button' | 'list';
+    readonly option: InteractiveOption;
+};
+interface MessagePayload {
+    id: string;
+    type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template' | 'interactive';
+    /** Payload cru da mensagem. Em `type: 'interactive'`, carrega o menu que o cliente vê. */
+    payload?: InteractivePayload | null;
+    content?: string;
+    caption?: string;
+    mediaUrl?: string;
+    base64?: string;
+    uploadId?: string;
+    mediaId?: string;
+    mimeType?: string;
+    filename?: string;
+    sizeBytes?: number;
+    direction: 'inbound' | 'outbound';
+    sender: 'bot' | 'customer' | 'agent';
+    timestamp: string;
+    status?: 'sent' | 'delivered' | 'read' | 'failed';
+    readAt?: string;
+    agentName?: string | null;
+    templateName?: string;
+    /**
+     * Veredito de moderação vindo do backend — a UI só exibe, nunca calcula. Dicionário no browser
+     * seria peso morto e daria veredito diferente por versão de cliente.
+     *
+     * `null`/ausente = não avaliado (moderação desligada, ou mensagem anterior ao recurso), que é
+     * diferente de avaliado e limpo.
+     */
+    moderation?: {
+        isOffensive: boolean;
+        terms: string[];
+    } | null;
+    /**
+     * Transcrição do áudio, vinda do backend — a UI só exibe, nunca transcreve. Rodar STT no browser
+     * exigiria baixar modelo por aba e daria resultado diferente por versão de cliente.
+     *
+     * `null`/ausente = não avaliado, que é diferente de `'done'` com texto vazio (áudio em silêncio,
+     * já processado). É essa distinção que decide se o balão oferece "transcrever" ou "sem fala
+     * detectada".
+     */
+    transcription?: MessageTranscription | null;
+    isFirstInGroup?: boolean;
+    isLastInGroup?: boolean;
+}
+type TranscriptionStatus = 'pending' | 'done' | 'failed' | 'unsupported';
+/**
+ * Quando transcrever, escolhido nas configurações da empresa. Espelha o
+ * `TranscriptionMode` de `@adatechnology/meta-whatsapp-contracts`; declarado aqui para o pacote de
+ * UI não obrigar quem só desenha telas a instalar os contratos do backend.
+ */
+type TranscriptionMode = 'auto' | 'onDemand';
+interface MessageTranscription {
+    status: TranscriptionStatus;
+    text?: string | null;
+    /** ISO 639-1 ou nome do idioma, conforme o engine. Exibido como dica, não interpretado. */
+    language?: string | null;
+    engine?: string | null;
+}
+
+type ResolveMediaUrl = (message: MessagePayload) => Promise<string | null>;
+interface MediaRendererProps {
+    message: MessagePayload;
+    onLightbox: (src: string) => void;
+    onResolveUrl?: ResolveMediaUrl;
+    /**
+     * Pede ao backend a transcrição do áudio desta mensagem. Ausente, o bloco de transcrição só exibe
+     * o que já veio pronto — sem oferecer um botão que o host não sabe atender.
+     *
+     * O que devolver é exibido na hora, sem esperar refetch da lista.
+     */
+    onTranscribeAudio?: () => Promise<MessageTranscription | void>;
+    /** Aplicado no wrapper de cada tipo de mídia — imagem, vídeo, áudio e documento. */
+    className?: string;
+}
+declare function MediaRenderer({ message, onLightbox, onResolveUrl, onTranscribeAudio, className, }: MediaRendererProps): react.JSX.Element | null;
+
+/**
+ * Gravação de áudio no simulador, pelo microfone do próprio navegador.
+ *
+ * Existe porque áudio é o formato que mais chega de cliente real e o que mais quebra fluxo: sem
+ * poder gravar aqui, testar o caminho de transcrição exigia mandar mensagem do celular de alguém.
+ *
+ * O arquivo gravado sai daqui como `File` e segue exatamente o mesmo caminho de um anexo — quem
+ * hospeda e devolve o `mediaId` é o host, via `uploadMedia`.
+ */
+interface AudioRecorderButtonLabels {
+    start: string;
+    stop: string;
+    unsupported: string;
+    denied: string;
+    review: string;
+    send: string;
+    discard: string;
+    empty: string;
+}
+declare const DEFAULT_AUDIO_RECORDER_BUTTON_LABELS: AudioRecorderButtonLabels;
+interface AudioRecorderButtonProps {
+    onRecorded: (file: File) => void | Promise<void>;
+    onFailure?: (message: string) => void;
+    /**
+     * Avisa quando a gravação começa e termina. O botão é um interruptor — o segundo toque é que
+     * envia — e sem um aviso fora dele o operador grava, não vê nada acontecer e desiste achando
+     * que o microfone está quebrado.
+     */
+    onRecordingChange?: (isRecording: boolean) => void;
+    /**
+     * Abre uma etapa de revisão quando a gravação para: o áudio toca ali mesmo e só sai depois de
+     * confirmado. Ligado por padrão — voz é o único anexo que quem envia não viu antes de mandar, e
+     * sem ouvir não há como saber se o microfone captou alguma coisa. Desligar volta ao envio direto.
+     */
+    reviewBeforeSend?: boolean;
+    /**
+     * Teto de duração da gravação, em milissegundos. Passado o tempo, o gravador para e envia o que
+     * tem. Produto com limite próprio sobrescreve.
+     */
+    maxDurationMilliseconds?: number;
+    labels?: Partial<AudioRecorderButtonLabels>;
+    disabled?: boolean;
+}
+/**
+ * Cinco minutos: com o codec de voz do WhatsApp isso dá menos de 3MB, folgado dentro do teto de
+ * 16MB que a Meta impõe a áudio, e é mais do que qualquer recado de cliente. O corte automático
+ * existe porque gravação esquecida aberta só se descobre no envio, com o arquivo inteiro perdido.
+ */
+declare const DEFAULT_MAX_RECORDING_MILLISECONDS: number;
+declare function AudioRecorderButton({ onRecorded, onFailure, onRecordingChange, reviewBeforeSend, maxDurationMilliseconds, labels, disabled, }: AudioRecorderButtonProps): react.JSX.Element;
+
+/**
+ * Canal de origem da conversa e o que cada um permite.
+ *
+ * Existe porque as regras que a inbox precisa respeitar não são do WhatsApp, são **de cada canal**:
+ * a janela de sessão, o jeito de reabrir a conversa e o formato do identificador do contato mudam
+ * entre WhatsApp, Messenger, Instagram e chat de site. Tratar a regra do WhatsApp como universal
+ * faria a UI bloquear o composer num chat de site, onde janela nenhuma existe.
+ *
+ * `whatsapp` é o padrão em todo lugar: instalações que ainda não informam canal continuam
+ * funcionando exatamente como antes.
+ */
+declare const CONVERSATION_CHANNEL: {
+    readonly WHATSAPP: "whatsapp";
+    readonly MESSENGER: "messenger";
+    readonly INSTAGRAM: "instagram";
+    readonly WEBCHAT: "webchat";
+};
+type ConversationChannel = (typeof CONVERSATION_CHANNEL)[keyof typeof CONVERSATION_CHANNEL];
+declare const DEFAULT_CONVERSATION_CHANNEL: ConversationChannel;
+/** Como o canal reabre uma conversa fora da janela de sessão. */
+declare const REOPEN_MECHANISM: {
+    readonly TEMPLATE: "template";
+    readonly TAG: "tag";
+    readonly NONE: "none";
+};
+type ReopenMechanism = (typeof REOPEN_MECHANISM)[keyof typeof REOPEN_MECHANISM];
+/** Natureza do identificador do contato — decide como exibi-lo. */
+declare const HANDLE_KIND: {
+    readonly PHONE: "phone";
+    readonly USERNAME: "username";
+    readonly SESSION: "session";
+};
+type HandleKind = (typeof HANDLE_KIND)[keyof typeof HANDLE_KIND];
+type ChannelCapabilities = {
+    readonly label: string;
+    readonly icon: string;
+    readonly hasSessionWindow: boolean;
+    readonly windowHours: number;
+    readonly reopenMechanism: ReopenMechanism;
+    readonly handleKind: HandleKind;
+};
+declare const CHANNEL_CAPABILITIES: Readonly<Record<ConversationChannel, ChannelCapabilities>>;
+declare function capabilitiesOf(channel: ConversationChannel | undefined): ChannelCapabilities;
+declare const CHANNEL_FILTER_ALL = "all";
+type ChannelFilter = ConversationChannel | typeof CHANNEL_FILTER_ALL;
+type ChannelFilterOption = {
+    readonly value: ChannelFilter;
+    readonly label: string;
+};
+/**
+ * Opções derivadas do que existe na lista, não do catálogo inteiro: oferecer Instagram numa conta
+ * que só tem WhatsApp promete um recorte que nunca traz resultado.
+ *
+ * Devolve vazio com menos de dois canais — um filtro de opção única não filtra nada, e a barra só
+ * ocuparia espaço. O host usa isso para esconder a seção.
+ */
+declare function channelFiltersFor(conversations: readonly {
+    readonly channel?: ConversationChannel | undefined;
+}[]): ChannelFilterOption[];
+type FormatContactHandleParams = {
+    readonly handle: string;
+    readonly channel?: ConversationChannel | undefined;
+};
+/**
+ * Exibição do identificador conforme a natureza dele. Formatar tudo como telefone — o que a UI
+ * fazia — transforma um `@perfil` do Instagram em dígitos sem sentido.
+ */
+declare function formatContactHandle(params: FormatContactHandleParams): string;
+/** Bandeira só faz sentido quando o identificador é telefone. */
+declare function contactFlag(params: FormatContactHandleParams): string;
+
+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.
+ */
+interface ConversationPage {
+    conversations: ConversationSummary[];
+    total: number;
+}
+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.
+     *
+     * Seleção múltipla viaja como lista separada por vírgula em vez de virar `string[]`: mudar o
+     * tipo quebraria em compile-time toda implementação de host que já repassa este campo adiante,
+     * e o ganho seria nenhum — quem recebe faz `split(',')`.
+     */
+    source?: string;
+    /** Categoria do arquivo (`document`, `image`, `audio`, `video`…), mesma convenção de lista. */
+    fileCategory?: string;
+    /** Recorte por data de recebimento, em `YYYY-MM-DD`. */
+    startDate?: string;
+    endDate?: string;
+    sortDirection?: 'asc' | 'desc';
+    /** Coluna ordenada. Ausente, o host ordena pela data — é o padrão de toda listagem de arquivo. */
+    sortField?: string;
+    /**
+     * Filtros que só existem no produto (`clientId`, `unidade`…). O pacote não os interpreta: passa
+     * adiante o que o host injetou pelo slot de filtros. É a porta que evita um fork da tela por
+     * causa de um `<select>`.
+     */
+    extra?: Readonly<Record<string, string | number>>;
+}
+/** Arquivo na biblioteca da empresa: o mesmo da conversa, mais de qual conversa veio. */
+interface CompanyDocument extends ConversationDocument {
+    conversationId: string;
+    /**
+     * Nome de quem enviou, quando o host o conhece. Opcional porque a biblioteca sempre tem o
+     * telefone e nem todo produto tem cadastro por trás dele — ausente, a coluna cai para o número.
+     */
+    contactName?: string | null;
+}
+interface CompanyDocumentPage {
+    documents: CompanyDocument[];
+    total: number;
+}
+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.
+ */
+interface ConversationTemplate {
+    name: string;
+    language: string;
+    status: string;
+    category?: string;
+    bodyText?: string | null;
+}
+interface ConversationsApi {
+    fetchMessages(conversationId: string, params?: {
+        limit?: number;
+        before?: string;
+    }): Promise<MessagePayload[]>;
+    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[];
+    }): Promise<void>;
+    markRead(conversationId: string): Promise<void>;
+    getContext(conversationId: string): Promise<Record<string, unknown>>;
+    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>;
+    /**
+     * Remove um arquivo da biblioteca. **Opcional por capacidade:** apagar anexo trocado com o
+     * cliente é decisão de retenção do produto — instalação que precisa guardar tudo por obrigação
+     * legal não implementa, e a tela simplesmente não desenha a lixeira.
+     */
+    deleteDocument?(uploadId: string): Promise<void>;
+    /**
+     * Zip de arquivos avulsos da biblioteca, sem conversa de origem única — irmão do
+     * `downloadDocumentsArchive`, que é por conversa. Ausente, a seleção em lote não oferece o botão.
+     */
+    downloadDocumentsArchiveByIds?(uploadIds: readonly string[]): Promise<Blob>;
+    /**
+     * Envia um arquivo avulso direto pra biblioteca, fora do fluxo de uma conversa. **Opcional por
+     * capacidade:** cada host tem seu próprio contrato de upload (base64, multipart, presigned URL) —
+     * o pacote não escolhe um formato de payload, só entrega o `File` do input e deixa o host montar
+     * a chamada do jeito que seu backend espera. Ausente, a tela de biblioteca não desenha o botão de
+     * enviar, em vez de oferecer uma ação que sempre falha.
+     *
+     * `extra` é o mesmo vocabulário livre do produto que já viaja em `renderFilters` — cliente,
+     * unidade, campanha — pra associar o arquivo enviado ao contexto que a tela estava filtrando.
+     */
+    uploadDocument?(file: File, extra?: Readonly<Record<string, string | number>>): Promise<ConversationDocument>;
+    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;
+    }>;
+    /**
+     * Transcreve o áudio de uma mensagem e devolve o resultado.
+     *
+     * **Opcional por capacidade.** Um host em modo automático transcreve na ingestão e não expõe rota
+     * nenhuma; um host sem engine configurado não transcreve de jeito algum. Nos dois casos o balão
+     * simplesmente não desenha o botão, em vez de oferecer uma ação que estoura no clique.
+     *
+     * `messageId` e não `conversationId`: transcrição é por áudio, e uma conversa tem vários.
+     */
+    transcribeAudio?(messageId: string): Promise<MessageTranscription>;
+}
+/**
+ * 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.
+ */
+interface ConversationEventSource {
+    addEventListener(type: string, listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: string, listener: (event: MessageEvent) => void): void;
+    close(): void;
+}
+interface SSEProvider {
+    connectConversationStream(conversationId: string): ConversationEventSource;
+    connectGlobalStream(): ConversationEventSource;
+}
+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';
+    lastAt: string;
+    lastInboundAt: string | null;
+    mode: 'bot' | 'human';
+    assignedUserId: string | null;
+    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>;
+}
+interface ConversationDocument {
+    id: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    source: string;
+    linkedAt: string;
+}
+
+/**
+ * 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 };