@adatechnology/conversations-ui 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/index.d.ts

@@ -1,55 +1,7 @@
 import * as react from 'react';
-import react__default, { ReactNode, FormEvent } from 'react';
-
-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;
-}
-interface MessagePayload {
-    id: string;
-    type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template';
-    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;
-    isFirstInGroup?: boolean;
-    isLastInGroup?: boolean;
-}
-
-type ResolveMediaUrl = (message: MessagePayload) => Promise<string | null>;
-interface MediaRendererProps {
-    message: MessagePayload;
-    onLightbox: (src: string) => void;
-    onResolveUrl?: ResolveMediaUrl;
-}
-declare function MediaRenderer({ message, onLightbox, onResolveUrl }: MediaRendererProps): react.JSX.Element | null;
+import react__default, { ReactNode, CSSProperties, FormEvent } from 'react';
+import { y as MessagePayload, A as ResolveMediaUrl, v as InteractiveSelection, t as InteractivePayload, p as ConversationsFeatures, m as ConversationSummary, h as ConversationChannel, L as ListConversationsParams, o as ConversationsApi, S as SSEProvider, w as ListDocumentsParams, i as ConversationDocument, n as ConversationTemplate } from './types-B5C1DLu1.js';
+export { C as CHANNEL_CAPABILITIES, a as CHANNEL_FILTER_ALL, b as CONVERSATION_CHANNEL, c as ChannelCapabilities, d as ChannelFilter, e as ChannelFilterOption, f as CompanyDocument, g as CompanyDocumentPage, j as ConversationDocumentPage, k as ConversationEventSource, l as ConversationPage, q as ConversationsTheme, r as ConversationsUIConfig, D as DEFAULT_CONVERSATION_CHANNEL, F as FormatContactHandleParams, H as HANDLE_KIND, s as HandleKind, I as InteractiveOption, u as InteractiveSection, M as MediaRenderer, x as MediaRendererProps, R as REOPEN_MECHANISM, z as ReopenMechanism, B as capabilitiesOf, E as channelFiltersFor, G as contactFlag, J as formatContactHandle } from './types-B5C1DLu1.js';
 
 interface MessageBubbleProps {
     message: MessagePayload;
@@ -59,15 +11,40 @@ interface MessageBubbleProps {
     isSelecting?: boolean;
     isSelected?: boolean;
     onToggleSelect?: () => void;
+    /**
+     * Como buscar a mídia da mensagem. Ausente, o balão usa o `ConversationsApi` do
+     * `ConversationsProvider` — passe apenas para sobrescrever (cache próprio, CDN, proxy do host).
+     */
     onResolveMediaUrl?: ResolveMediaUrl;
+    /**
+     * Toque numa opção do menu interativo. Ausente, as opções aparecem desabilitadas — que é o certo
+     * no histórico da inbox: o operador vê o que foi oferecido, sem responder no lugar do cliente.
+     */
+    onInteractiveSelect?: (selection: InteractiveSelection) => void;
+    className?: string;
+}
+declare function MessageBubble({ message, isMine, senderName, isFirstInGroup, isSelecting, isSelected, onToggleSelect, onResolveMediaUrl, onInteractiveSelect, className, }: MessageBubbleProps): react.JSX.Element;
+
+interface InteractiveMessageLabels {
+    /** Fallback do rótulo do botão que abre a lista, quando o payload não traz um. */
+    openList: string;
+}
+declare const DEFAULT_INTERACTIVE_MESSAGE_LABELS: InteractiveMessageLabels;
+interface InteractiveMessageProps {
+    payload: InteractivePayload;
+    onSelect?: (selection: InteractiveSelection) => void;
+    labels?: Partial<InteractiveMessageLabels>;
+    className?: string;
 }
-declare function MessageBubble({ message, isMine, senderName, isFirstInGroup, isSelecting, isSelected, onToggleSelect, onResolveMediaUrl, }: MessageBubbleProps): react.JSX.Element;
+declare function InteractiveMessage({ payload, onSelect, labels, className }: InteractiveMessageProps): react.JSX.Element;
 
 interface ConversationWallpaperProps {
     children?: ReactNode;
     className?: string;
+    /** Ajusta ou substitui o fundo padrão — para produto com identidade visual própria. */
+    style?: CSSProperties;
 }
-declare function ConversationWallpaper({ children, className }: ConversationWallpaperProps): react.JSX.Element;
+declare function ConversationWallpaper({ children, className, style }: ConversationWallpaperProps): react.JSX.Element;
 
 interface ConversationLocales {
     bubble: {
@@ -82,6 +59,14 @@ interface ConversationLocales {
         viewImage: string;
         listenAudio: string;
         viewVideo: string;
+        moderationFlagged: string;
+        mediaLoading: string;
+        mediaRetry: string;
+        mediaError: string;
+        mediaUnavailable: string;
+        imageAlt: string;
+        untitledDocument: string;
+        downloadFile: string;
     };
     selection: {
         select: string;
@@ -107,13 +92,69 @@ interface AudioPlayerProps {
 }
 declare function AudioPlayer({ src, isMine }: AudioPlayerProps): react.JSX.Element;
 
+interface EmojiPickerLabels {
+    search: string;
+    noResults: string;
+}
+declare const DEFAULT_EMOJI_PICKER_LABELS: EmojiPickerLabels;
 interface EmojiPickerProps {
     onSelect: (emoji: string) => void;
+    labels?: Partial<EmojiPickerLabels>;
     className?: string;
 }
-declare const EmojiPicker: ({ onSelect, className }: EmojiPickerProps) => react.JSX.Element;
+declare const EmojiPicker: ({ onSelect, labels, className }: EmojiPickerProps) => react.JSX.Element;
+
+/**
+ * Catálogo de emojis com palavras-chave em português, usado pela busca do seletor.
+ *
+ * Fica em módulo próprio (e não dentro do `EmojiPicker`) porque a busca precisa varrer TODAS as
+ * categorias, não só a aberta — o índice é montado uma vez, no carregamento, e não a cada tecla.
+ *
+ * As palavras-chave são de busca, não legendas: incluem sinônimos e formas sem acento, porque quem
+ * digita rápido escreve "coracao" e "polegar" com a mesma frequência que a forma correta.
+ */
+type EmojiEntry = {
+    readonly emoji: string;
+    readonly keywords: readonly string[];
+};
+type EmojiCategory = {
+    readonly name: string;
+    readonly entries: readonly EmojiEntry[];
+};
+declare const EMOJI_CATEGORIES: readonly EmojiCategory[];
+/**
+ * Busca por prefixo de palavra-chave, não por substring: "ca" traz "casa" e "cartão", mas "sa" não
+ * traz "casa" — casar no meio da palavra devolvia resultado que ninguém consegue explicar.
+ */
+declare function searchEmojis(query: string): readonly EmojiEntry[];
 
+/**
+ * Mensagem pronta que o atendente cola no campo com um clique.
+ *
+ * `text` aceita string com `{{variavel}}` ou função: a string cobre o caso comum (copy fixa com o
+ * nome do cliente no meio) sem o host escrever código, e a função cobre o que precisa de lógica —
+ * escolher texto por produto, pluralizar, formatar moeda.
+ */
+interface QuickReply {
+    key: string;
+    /** O que aparece no chip, emoji incluso: `👋 Saudação`. */
+    label: string;
+    text: string | ((variables: Readonly<Record<string, string>>) => string);
+}
+/**
+ * Troca `{{nome}}` pelos valores passados. Variável ausente vira string vazia, e não o literal
+ * `{{nome}}`: mandar "Olá {{nome}}!" para o cliente é pior que mandar "Olá !".
+ */
+declare function applyQuickReplyVariables(template: string, variables?: Readonly<Record<string, string>>): string;
+declare function resolveQuickReply(quickReply: QuickReply, variables?: Readonly<Record<string, string>>): string;
+interface MessageComposerLabels {
+    emoji: string;
+    attach: string;
+    send: string;
+}
+declare const DEFAULT_MESSAGE_COMPOSER_LABELS: MessageComposerLabels;
 interface MessageComposerProps {
+    labels?: Partial<MessageComposerLabels>;
     onSend: (text: string) => void;
     onAttach?: (file: File) => void;
     value?: string;
@@ -123,10 +164,46 @@ interface MessageComposerProps {
     maxLength?: number;
     disabled?: boolean;
     acceptedFileTypes?: string;
+    /**
+     * Ocupa o lugar do botão de enviar enquanto não há nada para enviar — é onde o WhatsApp põe o
+     * microfone. Fora do campo, o botão vira um bloco solto ao lado do pill e quebra a barra.
+     */
+    idleAction?: ReactNode;
+    /** Mensagens prontas exibidas acima do campo. Vazio ou ausente, a faixa não é renderizada. */
+    quickReplies?: readonly QuickReply[];
+    /** Valores para `{{variavel}}` — tipicamente nome do cliente, produto, protocolo. */
+    quickReplyVariables?: Readonly<Record<string, string>>;
+    className?: string;
+    classNames?: Partial<MessageComposerClassNames>;
 }
-declare const MessageComposer: ({ onSend, onAttach, value: externalValue, onChange: externalOnChange, features, placeholder, maxLength, disabled, acceptedFileTypes, }: MessageComposerProps) => react.JSX.Element;
+interface MessageComposerClassNames {
+    root: string;
+    quickReplies: string;
+    quickReply: string;
+    field: string;
+}
+/**
+ * Exatamente o que a Meta aceita em mensagem de mídia — imagem, sticker, áudio, vídeo e a lista
+ * fechada de documentos. Oferecer no seletor um formato que o WhatsApp recusa (`.zip`, `.rtf`)
+ * empurra a falha para depois do envio, quando já não dá para explicar ao operador o que houve.
+ * Produto com regra própria passa `acceptedFileTypes`.
+ */
+declare const DEFAULT_ACCEPTED_FILE_TYPES: string;
+declare const MessageComposer: ({ onSend, onAttach, value: externalValue, onChange: externalOnChange, quickReplies, quickReplyVariables, features, placeholder, maxLength, disabled, acceptedFileTypes, idleAction, className, classNames, labels, }: MessageComposerProps) => react.JSX.Element;
 
+interface WhatsAppMessageEditorLabels {
+    bold: string;
+    /** Tooltip da negrito — traz a sintaxe do WhatsApp junto, por isso é separado do `aria-label`. */
+    boldHint: string;
+    italic: string;
+    italicHint: string;
+    strikethrough: string;
+    strikethroughHint: string;
+    insertPlaceholder: (token: string) => string;
+}
+declare const DEFAULT_WHATSAPP_MESSAGE_EDITOR_LABELS: WhatsAppMessageEditorLabels;
 interface WhatsAppMessageEditorProps {
+    labels?: Partial<WhatsAppMessageEditorLabels>;
     value: string;
     onChange: (value: string) => void;
     placeholder?: string;
@@ -135,7 +212,7 @@ interface WhatsAppMessageEditorProps {
     previewLabel?: string;
     emptyPreviewText?: string;
 }
-declare function WhatsAppMessageEditor({ value, onChange, placeholder, placeholders, rows, previewLabel, emptyPreviewText, }: WhatsAppMessageEditorProps): react.JSX.Element;
+declare function WhatsAppMessageEditor({ value, onChange, placeholder, placeholders, rows, previewLabel, emptyPreviewText, labels, }: WhatsAppMessageEditorProps): react.JSX.Element;
 
 interface SimpleEmojiPickerProps {
     onSelect: (emoji: string) => void;
@@ -145,89 +222,58 @@ interface SimpleEmojiPickerProps {
 }
 declare function SimpleEmojiPicker({ onSelect, label, pickerWidth, pickerMaxHeight }: SimpleEmojiPickerProps): react.JSX.Element;
 
+interface DateDividerClassNames {
+    root: string;
+    label: string;
+}
 interface DateDividerProps {
     iso: string;
+    className?: string;
+    classNames?: Partial<DateDividerClassNames>;
 }
-declare function DateDivider({ iso }: DateDividerProps): react.JSX.Element;
+declare function DateDivider({ iso, className, classNames }: DateDividerProps): react.JSX.Element;
 
+interface AvatarLabels {
+    /** Lido por leitor de tela quando não há nome nem imagem — a silhueta genérica. */
+    unnamedContact: string;
+}
 interface AvatarProps {
     name?: string | null;
     avatarUrl?: string;
     size?: 'sm' | 'md' | 'lg';
     className?: string;
+    labels?: Partial<AvatarLabels>;
 }
-declare function Avatar({ name, avatarUrl, size, className }: AvatarProps): react.JSX.Element;
-
-interface ConversationsApi {
-    fetchMessages(conversationId: string, params?: {
-        limit?: number;
-        before?: string;
-    }): Promise<MessagePayload[]>;
-    fetchConversations(params?: {
-        page?: number;
-        limit?: number;
-        waitingHuman?: boolean;
-        search?: string;
-    }): Promise<ConversationSummary[]>;
-    sendMessage(conversationId: string, text: string): Promise<MessagePayload>;
-    sendMedia(conversationId: string, data: {
-        base64: string;
-        mimeType: string;
-        filename: string;
-        caption?: string;
-    }): Promise<MessagePayload>;
-    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?: {
-        search?: string;
-        page?: number;
-    }): Promise<ConversationDocument[]>;
-    getDocumentUrl(uploadId: string): Promise<string>;
-    getMediaProxyUrl(mediaId: string): Promise<{
-        mimeType: string;
-        data: string;
-    }>;
-}
-interface SSEProvider {
-    connectConversationStream(conversationId: string): EventSource;
-    connectGlobalStream(): EventSource;
-}
-interface ConversationSummary {
-    id: string;
-    whatsappNumber: string;
-    clientName?: string;
-    lastContent?: string;
-    lastDirection?: 'inbound' | 'outbound';
-    lastAt: string;
-    lastInboundAt: string | null;
-    mode: 'bot' | 'human';
-    assignedUserId: string | null;
-    waitingHuman: boolean;
-    unread: number;
-    currentState: string;
-}
-interface ConversationDocument {
-    id: string;
-    filename: string;
-    mimeType: string;
-    sizeBytes: number;
-    source: string;
-    linkedAt: string;
-}
+declare const DEFAULT_AVATAR_LABELS: AvatarLabels;
+declare function Avatar({ name, avatarUrl, size, className, labels }: AvatarProps): react.JSX.Element;
 
+interface ConversationListItemLabels {
+    /** Tooltip do ponto vermelho: a janela de atendimento de 24h já fechou. */
+    expiredWindow: string;
+    /** Tooltip do ponto laranja: a janela de atendimento está perto de fechar. */
+    warningWindow: string;
+}
+declare const DEFAULT_CONVERSATION_LIST_ITEM_LABELS: ConversationListItemLabels;
 interface ConversationListItemProps {
     conversation: ConversationSummary;
+    labels?: Partial<ConversationListItemLabels>;
     active?: boolean;
     selected?: boolean;
     onClick?: () => void;
     onSelect?: (id: string) => void;
+    /**
+     * Desliga a borda inferior quando o item é composto dentro de outra linha (ver `ConversationRow`):
+     * com ela ligada, a borda corta a própria linha ao meio, separando o item do rodapé de status.
+     */
+    showDivider?: boolean;
+    /**
+     * Desliga o fundo de selecionado. Par do `showDivider`: quando o item é composto dentro de uma
+     * linha maior, quem pinta o realce é a linha — senão só o bloco do item fica cinza e o resto
+     * (checkbox, pills, barra lateral) continua branco, como se metade da linha estivesse selecionada.
+     */
+    highlightActive?: boolean;
 }
-declare const ConversationListItem: ({ conversation, active, selected, onClick, onSelect, }: ConversationListItemProps) => react.JSX.Element;
+declare const ConversationListItem: ({ conversation, active, selected, onClick, onSelect, showDivider, highlightActive, labels, }: ConversationListItemProps) => react.JSX.Element;
 
 type ToastType = 'success' | 'error' | 'info';
 interface ToastContextValue {
@@ -247,12 +293,19 @@ interface StatusTicksProps {
 }
 declare function StatusTicks({ status, title }: StatusTicksProps): react.JSX.Element;
 
+interface LightboxLabels {
+    /** Texto alternativo quando a imagem não tem legenda — sem ele o leitor de tela anuncia a URL. */
+    imageAlt: string;
+    close: string;
+}
 interface LightboxProps {
     imageUrl: string;
     caption?: string;
     onClose: () => void;
+    labels?: Partial<LightboxLabels>;
 }
-declare function Lightbox({ imageUrl, caption, onClose }: LightboxProps): react.JSX.Element;
+declare const DEFAULT_LIGHTBOX_LABELS: LightboxLabels;
+declare function Lightbox({ imageUrl, caption, onClose, labels }: LightboxProps): react.JSX.Element;
 
 interface FileIconProps {
     filename?: string;
@@ -279,16 +332,404 @@ interface MessageTailProps {
 }
 declare function MessageTail({ isOutbound }: MessageTailProps): react.JSX.Element;
 
+/**
+ * Janela de sessão: o intervalo em que o canal aceita mensagem livre do atendente. No WhatsApp são
+ * 24h desde o último contato do cliente; fora dela só template. Cada canal tem a sua regra — e há
+ * canal sem janela nenhuma — então a política vem de `capabilitiesOf`, não de constante fixa.
+ *
+ * Mora no SDK porque é regra de plataforma, não de produto: todo projeto que usa este pacote
+ * precisa dela para saber o que o atendente ainda consegue fazer.
+ */
+
+declare const CONVERSATION_WINDOW: {
+    readonly ALL: "all";
+    readonly FRESH: "fresh";
+    readonly WARNING: "warning";
+    readonly CRITICAL: "critical";
+    readonly EXPIRED: "expired";
+};
+type ConversationWindow = (typeof CONVERSATION_WINDOW)[keyof typeof CONVERSATION_WINDOW];
+declare const WINDOW_FILTERS: readonly [{
+    readonly value: "all";
+    readonly label: "Todas";
+    readonly dotClass: "";
+}, {
+    readonly value: "fresh";
+    readonly label: "<12h";
+    readonly dotClass: "bg-green-500";
+}, {
+    readonly value: "warning";
+    readonly label: "12-21h";
+    readonly dotClass: "bg-yellow-500";
+}, {
+    readonly value: "critical";
+    readonly label: "21-24h";
+    readonly dotClass: "bg-red-500";
+}, {
+    readonly value: "expired";
+    readonly label: ">24h";
+    readonly dotClass: "bg-gray-400";
+}];
+type WindowOfParams = {
+    readonly lastInboundAt: string | null;
+    readonly now: number;
+    /** Ausente = `whatsapp`. */
+    readonly channel?: ConversationChannel | undefined;
+};
+/**
+ * Sem `lastInboundAt` o cliente nunca escreveu, então não há janela aberta — classificar como
+ * expirada é o comportamento seguro: evita o atendente tentar texto livre e receber recusa.
+ *
+ * Canal sem janela de sessão (chat de site) é sempre `fresh`: ali nada expira, e marcar expirado
+ * bloquearia o composer inventando um limite que a plataforma não impõe.
+ */
+declare function windowOf(params: WindowOfParams): ConversationWindow;
+declare function formatStalledFor(lastAt: string, now: number): string;
+
+type ConversationRowClassNames = {
+    root: string;
+    windowBar: string;
+};
+type ConversationRowProps = {
+    conversation: ConversationSummary;
+    active: boolean;
+    selected: boolean;
+    now: number;
+    busy: boolean;
+    onOpen: () => void;
+    onToggleSelected: () => void;
+    onTakeover: () => void;
+    className?: string;
+    classNames?: Partial<ConversationRowClassNames>;
+};
+declare function ConversationRow({ conversation, active, selected, now, busy, onOpen, onToggleSelected, onTakeover, className, classNames, }: ConversationRowProps): react.JSX.Element;
+
+declare const CHANNEL_BRAND_COLOR: Readonly<Record<ConversationChannel, string>>;
+interface ChannelIconProps {
+    channel?: ConversationChannel | undefined;
+    size?: number;
+    className?: string;
+}
+declare function ChannelIcon({ channel, size, className }: ChannelIconProps): react.JSX.Element;
+
+interface ConversationHeaderLabels {
+    botMode: string;
+    humanMode: string;
+    returnToBot: string;
+    finish: string;
+    takeover: string;
+    download: string;
+    documents: string;
+    back: string;
+    moreActions: string;
+}
+declare const DEFAULT_CONVERSATION_HEADER_LABELS: ConversationHeaderLabels;
+/**
+ * Partes estilizáveis do cabeçalho. Cada chave recebe classes que o `cn` funde por cima da base, e
+ * conflito de utilitário (padding, gap, borda) fica com o valor do produto.
+ */
+interface ConversationHeaderClassNames {
+    root: string;
+    identity: string;
+    name: string;
+    meta: string;
+    actions: string;
+    desktopActions: string;
+    mobileMenu: string;
+}
+/**
+ * Utilitário extra que o host pendura no cabeçalho — ícone no desktop, item de menu no celular,
+ * como os nativos. Entra por aqui, e não por um slot de ReactNode, porque é isso que preserva o
+ * comportamento responsivo: um nó solto viraria um quarto ícone em 375px, sem área de toque.
+ */
+interface ConversationHeaderUtility {
+    key: string;
+    /** Emoji, para casar com os utilitários nativos do cabeçalho. */
+    icon: string;
+    label: string;
+    run: () => void;
+    active?: boolean;
+}
+interface ConversationHeaderProps {
+    conversation: ConversationSummary;
+    busy?: boolean;
+    onTakeover?: () => void;
+    onReturnToBot?: () => void;
+    onFinish?: () => void;
+    onDownload?: () => void;
+    onOpenDocuments?: () => void;
+    documentsOpen?: boolean;
+    /** Ações do produto que não existem no contrato do pacote (ex.: ferramentas de dev). */
+    extraUtilities?: readonly ConversationHeaderUtility[];
+    onBack?: () => void;
+    labels?: Partial<ConversationHeaderLabels>;
+    className?: string;
+    classNames?: Partial<ConversationHeaderClassNames>;
+}
+declare function ConversationHeader({ conversation, busy, onTakeover, onReturnToBot, onFinish, onDownload, onOpenDocuments, documentsOpen, extraUtilities, onBack, labels: labelsOverride, className, classNames, }: ConversationHeaderProps): react.JSX.Element;
+
+/**
+ * "Suas Seleções": o que o bot já coletou na conversa. Para o atendente que assume no meio, é a
+ * diferença entre ler o transcript inteiro e ver o estado em duas linhas.
+ *
+ * O pacote não interpreta o contexto — ele é `Record<string, unknown>` e cada produto nomeia as
+ * próprias chaves. O host traduz para `entries`; aqui só se decide como mostrar.
+ */
+interface ConversationContextEntry {
+    key: string;
+    label: string;
+    value?: string | undefined;
+    icon?: string;
+}
+interface ConversationContextPanelLabels {
+    title: string;
+    empty: string;
+}
+declare const DEFAULT_CONVERSATION_CONTEXT_LABELS: ConversationContextPanelLabels;
+interface ConversationContextPanelClassNames {
+    root: string;
+    toggle: string;
+    counter: string;
+    body: string;
+}
+interface ConversationContextPanelProps {
+    entries: readonly ConversationContextEntry[];
+    labels?: Partial<ConversationContextPanelLabels>;
+    className?: string;
+    classNames?: Partial<ConversationContextPanelClassNames>;
+}
+declare function ConversationContextPanel({ entries, labels: labelsOverride, className, classNames, }: ConversationContextPanelProps): react.JSX.Element;
+
+interface WindowExpiredNoticeLabels {
+    title: string;
+    description: string;
+    sendTemplate: string;
+}
+declare const DEFAULT_WINDOW_EXPIRED_LABELS: WindowExpiredNoticeLabels;
+interface WindowExpiredNoticeProps {
+    onSendTemplate?: () => void;
+    disabled?: boolean;
+    labels?: Partial<WindowExpiredNoticeLabels>;
+    className?: string;
+}
+declare function WindowExpiredNotice({ onSendTemplate, disabled, labels: labelsOverride, className, }: WindowExpiredNoticeProps): react.JSX.Element;
+/**
+ * Só a faixa `expired` bloqueia: 21-24h ainda aceita texto livre e merece alerta, não impedimento.
+ */
+declare function isWindowBlocking(window: ConversationWindow): boolean;
+
+/**
+ * Biblioteca de arquivos de TODAS as conversas — a tela de Documentos do painel, fora do
+ * atendimento.
+ *
+ * Distinta do `ConversationDocumentsPanel`: aquele parte de uma conversa aberta e vive dentro dela;
+ * esta varre a empresa e por isso mostra de qual conversa cada arquivo veio, com o número
+ * clicável. Sem essa referência, uma lista global de anexos não responde nenhuma pergunta.
+ */
+interface DocumentsLibraryLabels {
+    title: string;
+    searchPlaceholder: string;
+    empty: string;
+    noResults: string;
+    loading: string;
+    failure: string;
+    view: string;
+    download: string;
+    openConversation: string;
+    sourceFilterAll: string;
+    sourceFilterCustomer: string;
+    sourceFilterTeam: string;
+    sortMostRecent: string;
+    sortOldest: string;
+    clearFilters: string;
+    total: (count: number) => string;
+    page: (current: number, last: number) => string;
+}
+declare const DEFAULT_DOCUMENTS_LIBRARY_LABELS: DocumentsLibraryLabels;
+interface DocumentsLibraryClassNames {
+    root: string;
+    title: string;
+    filters: string;
+    search: string;
+    sourceSelect: string;
+    sortButton: string;
+    clearButton: string;
+    status: string;
+    list: string;
+    item: string;
+    conversationLink: string;
+    filename: string;
+    meta: string;
+    pagination: string;
+}
+interface DocumentsLibraryProps {
+    /** Itens por página. O total vem do servidor. */
+    perPage?: number;
+    /** Abrir a conversa de origem. Ausente, o número aparece como texto e não como link. */
+    onOpenConversation?: (conversationId: string) => void;
+    labels?: Partial<DocumentsLibraryLabels>;
+    className?: string;
+    classNames?: Partial<DocumentsLibraryClassNames>;
+}
+declare function DocumentsLibrary({ perPage, onOpenConversation, labels: labelsOverride, className, classNames, }: DocumentsLibraryProps): react.JSX.Element | null;
+
+/**
+ * Arquivos trocados na conversa. Sai do transcript e vira lista própria porque anexo é o que o
+ * atendente mais precisa reencontrar depois — rolar meses de mensagens para achar um comprovante é
+ * o caso que a busca por documento existe para eliminar.
+ *
+ * Usa `useConversationDocuments`, então funciona com qualquer `ConversationsApi`. Host sem
+ * biblioteca de documentos cai no estado vazio, sem quebrar.
+ */
+/** Origens que o filtro oferece. `all` não é origem — é a ausência de filtro. */
+declare const DOCUMENT_SOURCE_FILTER: {
+    readonly ALL: "all";
+    readonly CUSTOMER: "customer";
+    readonly TEAM: "team";
+};
+type DocumentSourceFilter = (typeof DOCUMENT_SOURCE_FILTER)[keyof typeof DOCUMENT_SOURCE_FILTER];
+interface ConversationDocumentsPanelLabels {
+    toggle: string;
+    title: string;
+    searchPlaceholder: string;
+    empty: string;
+    /** Distinto de `empty`: sem resultado POR CAUSA do filtro, e não conversa sem anexo nenhum. */
+    noResults: string;
+    loading: string;
+    failure: string;
+    download: string;
+    view: string;
+    sourceFilterAll: string;
+    sourceFilterCustomer: string;
+    sourceFilterTeam: string;
+    sortMostRecent: string;
+    sortOldest: string;
+    clearFilters: string;
+    selectAll: string;
+    downloadSelected: (count: number) => string;
+    archiveFailed: string;
+    total: (count: number) => string;
+    page: (current: number, last: number) => string;
+}
+declare const DEFAULT_CONVERSATION_DOCUMENTS_LABELS: ConversationDocumentsPanelLabels;
+/**
+ * Partes estilizáveis do painel, no mesmo contrato do `ConversationHeader`: `cn` funde por cima da
+ * base e conflito de utilitário (padding, tamanho de fonte, borda) fica com o valor do produto.
+ *
+ * `status` cobre carregando/erro/vazio de uma vez — são a mesma linha de texto auxiliar, e slots
+ * separados só multiplicariam chave para quem quer mudar a cor de aviso.
+ */
+interface ConversationDocumentsPanelClassNames {
+    root: string;
+    body: string;
+    title: string;
+    filters: string;
+    search: string;
+    sourceSelect: string;
+    sortButton: string;
+    clearButton: string;
+    status: string;
+    list: string;
+    item: string;
+    sourceBadge: string;
+    filename: string;
+    meta: string;
+    viewButton: string;
+    downloadButton: string;
+    pagination: string;
+    selectionBar: string;
+    checkbox: string;
+}
+interface ConversationDocumentsPanelProps {
+    conversationId: string;
+    /** Controlado de fora porque o gatilho vive no cabeçalho, junto das outras ações da conversa. */
+    open: boolean;
+    /** Itens por página. O total vem do servidor; sem paginação no host, a barra não aparece. */
+    perPage?: number;
+    labels?: Partial<ConversationDocumentsPanelLabels>;
+    className?: string;
+    classNames?: Partial<ConversationDocumentsPanelClassNames>;
+}
+declare function ConversationDocumentsPanel({ conversationId, open, perPage, labels: labelsOverride, className, classNames, }: ConversationDocumentsPanelProps): react.JSX.Element | null;
+
+/**
+ * Serialização do transcript para download. Fica no pacote porque o formato de um histórico de
+ * WhatsApp legível não é regra de negócio de ninguém — e porque o host que já tem as mensagens em
+ * tela não deveria precisar de rota nova só para salvar um arquivo.
+ *
+ * Funções puras, separadas do disparo do download: é o que permite testá-las sem DOM.
+ */
+
+type BuildTranscriptTextParams = {
+    readonly messages: readonly MessagePayload[];
+    readonly whatsappNumber: string;
+    readonly clientName?: string | undefined;
+};
+/**
+ * Formato próximo ao export nativo do WhatsApp (`[data hora] Autor: texto`), que é o que pessoas e
+ * ferramentas de suporte já sabem ler.
+ */
+declare function buildTranscriptText(params: BuildTranscriptTextParams): string;
+declare function buildTranscriptFilename(whatsappNumber: string, generatedAt: Date): string;
+/**
+ * Dispara o download no navegador. `revokeObjectURL` no fim não é higiene opcional: sem ele cada
+ * export retém o blob inteiro em memória até a aba fechar.
+ */
+declare function downloadTextFile(filename: string, content: string): void;
+
+/**
+ * Leitura passiva do tema do host: observa a classe `dark` no `<html>` e não escreve nada.
+ *
+ * Existe porque `useDarkMode` é um controlador — ele grava a classe e persiste a preferência. Um
+ * componente que só precisa escolher cor não pode usá-lo: bastava renderizar o mapa de fluxos
+ * para o app inteiro do host trocar de tema, seguindo o `prefers-color-scheme` do sistema em vez
+ * da configuração da aplicação.
+ */
+declare function useIsDarkTheme(): boolean;
 declare function useDarkMode(): {
     isDark: boolean;
     toggle: () => void;
 };
 
+/**
+ * Detecta tela estreita para decisões que CSS não resolve — como abrir ou não um painel por padrão.
+ *
+ * O breakpoint é o mesmo das classes `cv-only-*` e `.cv-back` (1024px). Duplicado aqui porque
+ * JavaScript não lê media query do stylesheet; se um dia divergirem, o sintoma é painel abrindo
+ * numa largura onde o resto da UI já mudou de modo.
+ */
+declare const NARROW_MAX_WIDTH_PX = 1023;
+declare function useIsNarrow(): boolean;
+
+interface UseWaitingNotificationsLabels {
+    /** Título da notificação do sistema. Recebe a conversa para o host escolher nome × número. */
+    title: (conversation: ConversationSummary) => string;
+    body: (conversation: ConversationSummary) => string;
+}
+interface UseWaitingNotificationsParams {
+    /**
+     * Repassado cru ao `fetchConversations`. É o que permite filtrar não lidas **no servidor** em
+     * vez de baixar a lista inteira e contar no cliente: um painel com milhares de conversas não
+     * pode paginar 50 por vez atrás de quem tem `unread > 0`.
+     */
+    readonly params?: ListConversationsParams;
+    readonly intervalMs?: number;
+    /** Desliga o polling sem desmontar quem chama — útil com a aba em segundo plano. */
+    readonly enabled?: boolean;
+    readonly icon?: string;
+    readonly labels?: Partial<UseWaitingNotificationsLabels>;
+}
 interface UseWaitingNotificationsResult {
     unreadCount: number;
     conversations: ConversationSummary[];
+    /**
+     * Releitura sob demanda. Existe porque o polling é o piso, não o mecanismo: quem já recebe SSE
+     * ou acabou de marcar tudo como lido sabe da mudança antes do próximo tick, e esperar 10s para
+     * o contador acompanhar faz a interface parecer travada.
+     */
+    refresh: () => Promise<void>;
 }
-declare function useWaitingNotifications(): UseWaitingNotificationsResult;
+declare function useWaitingNotifications(params?: UseWaitingNotificationsParams): UseWaitingNotificationsResult;
 
 interface ConversationsContextValue {
     api: ConversationsApi;
@@ -370,6 +811,7 @@ interface WhatsAppCreateTemplateFormLabels {
     sectionDescription: string;
     nameLabel: string;
     nameHint: string;
+    namePlaceholder: string;
     categoryLabel: string;
     languageLabel: string;
     headerLabel: string;
@@ -435,6 +877,41 @@ interface WelcomeFarewellFormProps {
 }
 declare function WelcomeFarewellForm({ welcomeMessage, onWelcomeMessageChange, farewellMessage, onFarewellMessageChange, onSave, saving, saveSuccess, welcomePlaceholders, farewellPlaceholders, labels: labelsOverride, }: WelcomeFarewellFormProps): react.JSX.Element;
 
+declare const TEMPLATE_SETTINGS_TAB: {
+    readonly SELECT: "select";
+    readonly CREATE: "create";
+};
+type TemplateSettingsTab = (typeof TEMPLATE_SETTINGS_TAB)[keyof typeof TEMPLATE_SETTINGS_TAB];
+interface WhatsAppTemplatesSettingsLabels {
+    selectTab: string;
+    createTab: string;
+}
+declare const DEFAULT_TEMPLATES_SETTINGS_LABELS: WhatsAppTemplatesSettingsLabels;
+interface WhatsAppTemplatesSettingsProps {
+    templates: WhatsAppTemplateSummary[];
+    loadingTemplates?: boolean;
+    templatesError?: boolean;
+    onRefreshTemplates?: () => void;
+    selectedTemplateName: string;
+    onSelectTemplate: (name: string, template: WhatsAppTemplateSummary | undefined) => void;
+    variables: string[];
+    onVariablesChange: (variables: string[]) => void;
+    availableVariables?: WhatsAppTemplateVariableSuggestion[];
+    saving?: boolean;
+    saveSuccess?: boolean;
+    onSave: (event: FormEvent) => void;
+    /** Ausente = host não sabe criar template; a aba de criação nem aparece. */
+    create?: {
+        value: WhatsAppCreateTemplateState;
+        onChange: (value: WhatsAppCreateTemplateState) => void;
+        onSubmit: (event: FormEvent) => void;
+        submitting?: boolean;
+        result?: WhatsAppCreateTemplateResult | null;
+    };
+    labels?: Partial<WhatsAppTemplatesSettingsLabels>;
+}
+declare function WhatsAppTemplatesSettings({ labels: labelsOverride, create, ...settingsProps }: WhatsAppTemplatesSettingsProps): react.JSX.Element;
+
 interface TopicItem {
     key: string;
     label: string;
@@ -472,7 +949,7 @@ interface UseConversationMessagesResult {
         caption?: string;
     }) => Promise<MessagePayload>;
     sendTemplate: (data: {
-        templateName: string;
+        templateName?: string;
         languageCode?: string;
         bodyParams?: string[];
     }) => Promise<void>;
@@ -483,14 +960,11 @@ declare function useConversationMessages(conversationId: string, params?: {
     before?: string;
 }): UseConversationMessagesResult;
 
-interface UseConversationListParams {
-    page?: number;
-    limit?: number;
-    waitingHuman?: boolean;
-    search?: string;
-}
+type UseConversationListParams = ListConversationsParams;
 interface UseConversationListResult {
     conversations: ConversationSummary[];
+    /** Total no servidor. Cai para o tamanho da página quando a API devolve só o array. */
+    total: number;
     loading: boolean;
     error: Error | undefined;
     refetch: () => Promise<void>;
@@ -505,22 +979,42 @@ interface UseConversationContextResult {
 }
 declare function useConversationContext(conversationId: string): UseConversationContextResult;
 
-interface UseConversationDocumentsParams {
-    search?: string;
-    page?: number;
-}
+type UseConversationDocumentsParams = ListDocumentsParams;
 interface UseConversationDocumentsResult {
     documents: ConversationDocument[];
+    /** Total no servidor. Cai para o tamanho da página quando a API devolve só o array. */
+    total: number;
     loading: boolean;
     error: Error | undefined;
     refetch: () => Promise<void>;
 }
-declare function useConversationDocuments(conversationId: string, params?: UseConversationDocumentsParams): UseConversationDocumentsResult;
+declare function useConversationDocuments(conversationId: string | undefined, params?: UseConversationDocumentsParams): UseConversationDocumentsResult;
 
 type ConversationRealtimeHandler = (event: MessageEvent) => void;
 declare function useConversationRealtime(conversationId: string | undefined, onEvent: ConversationRealtimeHandler): void;
 declare function useGlobalRealtime(onEvent: ConversationRealtimeHandler): void;
 
+interface UseConversationActionsResult {
+    /** `undefined` quando a API do host não implementa a operação — a UI esconde a afordância. */
+    takeover: (() => Promise<void>) | undefined;
+    release: (() => Promise<void>) | undefined;
+    finalize: (() => Promise<void>) | undefined;
+}
+/**
+ * Ações de atendimento de UMA conversa, já ligadas ao id.
+ *
+ * Separado de `useConversationMessages` porque assumir e devolver conversa também acontece a
+ * partir da lista, onde nenhuma thread está aberta — embutir nas mensagens obrigaria a carregar
+ * a thread inteira só para desenhar um botão na linha.
+ */
+declare function useConversationActions(conversationId: string): UseConversationActionsResult;
+interface UseInboxActionsResult {
+    markAllRead: (() => Promise<void>) | undefined;
+    listTemplates: (() => Promise<ConversationTemplate[]>) | undefined;
+}
+/** Ações que valem para a caixa inteira, sem conversa selecionada. */
+declare function useInboxActions(): UseInboxActionsResult;
+
 declare function parseWhatsAppFormatting(text: string): ReactNode[];
 declare function waToHTML(text: string): string;
 declare function htmlToWA(html: string): string;
@@ -530,6 +1024,8 @@ declare function formatPhone(number: string): string;
 declare function phoneInitials(number: string): string;
 
 declare function formatTimestamp(timestamp: string): string;
+declare function formatDateTime(iso: string): string;
+declare function isSameDay(a: Date, b: Date): boolean;
 declare function formatFileSize(bytes: number): string;
 
 interface AsyncResourceState<T> {
@@ -539,4 +1035,16 @@ interface AsyncResourceState<T> {
     refetch: () => Promise<void>;
 }
 
-export { type AsyncResourceState, AudioPlayer, type AudioPlayerProps, Avatar, type AvatarProps, type ConversationDocument, ConversationListItem, type ConversationListItemProps, type ConversationLocales, ConversationLocalesProvider, type ConversationLocalesProviderProps, type ConversationRealtimeHandler, type ConversationSummary, ConversationWallpaper, type ConversationWallpaperProps, type ConversationsApi, type ConversationsFeatures, ConversationsProvider, type ConversationsTheme, type ConversationsUIConfig, DateDivider, type DateDividerProps, EmojiPicker, type EmojiPickerProps, FileIcon, type FileIconProps, Lightbox, type LightboxProps, MediaRenderer, type MediaRendererProps, MessageBubble, type MessageBubbleProps, MessageComposer, type MessageComposerProps, type MessagePayload, MessageTail, MessageText, type MessageTextProps, MessageTimestamp, type ResolveMediaUrl, type SSEProvider, SimpleEmojiPicker, type SimpleEmojiPickerProps, StatusTicks, type StatusTicksProps, ToastProvider, type TopicItem, TopicsForm, type TopicsFormLabels, type TopicsFormProps, type UseConversationContextResult, type UseConversationDocumentsParams, type UseConversationDocumentsResult, type UseConversationListParams, type UseConversationListResult, type UseConversationMessagesResult, WelcomeFarewellForm, type WelcomeFarewellFormLabels, type WelcomeFarewellFormProps, WhatsAppCreateTemplateForm, type WhatsAppCreateTemplateFormLabels, type WhatsAppCreateTemplateFormProps, type WhatsAppCreateTemplateResult, type WhatsAppCreateTemplateState, WhatsAppMessageEditor, type WhatsAppMessageEditorProps, type WhatsAppTemplateHeaderType, WhatsAppTemplateSettingsForm, type WhatsAppTemplateSettingsFormLabels, type WhatsAppTemplateSettingsFormProps, type WhatsAppTemplateSummary, type WhatsAppTemplateVariableSuggestion, formatFileSize, formatPhone, formatTimestamp, htmlToWA, parseWhatsAppFormatting, phoneInitials, toast, useConversationContext, useConversationDocuments, useConversationList, useConversationLocales, useConversationMessages, useConversationRealtime, useConversations, useDarkMode, useGlobalRealtime, useToast, useWaitingNotifications, waToHTML, waToHTMLInline };
+/**
+ * Resolve a mídia de uma mensagem numa URL exibível, usando só o `ConversationsApi`.
+ *
+ * Mora no pacote, e não em cada host, porque a regra não tem nada de específico de produto: é a
+ * tradução de `uploadId`/`mediaId` pelos dois métodos que o próprio contrato já declara. Deixá-la no
+ * host significava que todo projeto que adotasse o SDK reescreveria as mesmas oito linhas — e, na
+ * prática, ninguém escrevia: o `MediaRenderer` só busca mídia pela porta `onResolveMediaUrl`, então
+ * onde nada era injetado foto, vídeo e áudio ficavam no placeholder para sempre.
+ */
+
+declare function createMediaUrlResolver(api: Pick<ConversationsApi, 'getDocumentUrl' | 'getMediaProxyUrl'>): ResolveMediaUrl;
+
+export { type AsyncResourceState, AudioPlayer, type AudioPlayerProps, Avatar, type AvatarLabels, type AvatarProps, type BuildTranscriptTextParams, CHANNEL_BRAND_COLOR, CONVERSATION_WINDOW, ChannelIcon, type ChannelIconProps, ConversationChannel, type ConversationContextEntry, ConversationContextPanel, type ConversationContextPanelClassNames, type ConversationContextPanelLabels, type ConversationContextPanelProps, ConversationDocument, ConversationDocumentsPanel, type ConversationDocumentsPanelClassNames, type ConversationDocumentsPanelLabels, type ConversationDocumentsPanelProps, ConversationHeader, type ConversationHeaderClassNames, type ConversationHeaderLabels, type ConversationHeaderProps, type ConversationHeaderUtility, ConversationListItem, type ConversationListItemLabels, type ConversationListItemProps, type ConversationLocales, ConversationLocalesProvider, type ConversationLocalesProviderProps, type ConversationRealtimeHandler, ConversationRow, type ConversationRowClassNames, type ConversationRowProps, ConversationSummary, ConversationTemplate, ConversationWallpaper, type ConversationWallpaperProps, type ConversationWindow, ConversationsApi, ConversationsFeatures, ConversationsProvider, DEFAULT_ACCEPTED_FILE_TYPES, DEFAULT_AVATAR_LABELS, DEFAULT_CONVERSATION_CONTEXT_LABELS, DEFAULT_CONVERSATION_DOCUMENTS_LABELS, DEFAULT_CONVERSATION_HEADER_LABELS, DEFAULT_CONVERSATION_LIST_ITEM_LABELS, DEFAULT_DOCUMENTS_LIBRARY_LABELS, DEFAULT_EMOJI_PICKER_LABELS, DEFAULT_INTERACTIVE_MESSAGE_LABELS, DEFAULT_LIGHTBOX_LABELS, DEFAULT_MESSAGE_COMPOSER_LABELS, DEFAULT_TEMPLATES_SETTINGS_LABELS, DEFAULT_WHATSAPP_MESSAGE_EDITOR_LABELS, DEFAULT_WINDOW_EXPIRED_LABELS, DOCUMENT_SOURCE_FILTER, DateDivider, type DateDividerClassNames, type DateDividerProps, type DocumentSourceFilter, DocumentsLibrary, type DocumentsLibraryClassNames, type DocumentsLibraryLabels, type DocumentsLibraryProps, EMOJI_CATEGORIES, type EmojiCategory, type EmojiEntry, EmojiPicker, type EmojiPickerLabels, type EmojiPickerProps, FileIcon, type FileIconProps, InteractiveMessage, type InteractiveMessageLabels, type InteractiveMessageProps, InteractivePayload, InteractiveSelection, Lightbox, type LightboxLabels, type LightboxProps, ListConversationsParams, ListDocumentsParams, MessageBubble, type MessageBubbleProps, MessageComposer, type MessageComposerClassNames, type MessageComposerLabels, type MessageComposerProps, MessagePayload, MessageTail, MessageText, type MessageTextProps, MessageTimestamp, NARROW_MAX_WIDTH_PX, type QuickReply, ResolveMediaUrl, SSEProvider, SimpleEmojiPicker, type SimpleEmojiPickerProps, StatusTicks, type StatusTicksProps, TEMPLATE_SETTINGS_TAB, type TemplateSettingsTab, ToastProvider, type TopicItem, TopicsForm, type TopicsFormLabels, type TopicsFormProps, type UseConversationActionsResult, type UseConversationContextResult, type UseConversationDocumentsParams, type UseConversationDocumentsResult, type UseConversationListParams, type UseConversationListResult, type UseConversationMessagesResult, type UseInboxActionsResult, type UseWaitingNotificationsLabels, type UseWaitingNotificationsParams, type UseWaitingNotificationsResult, WINDOW_FILTERS, WelcomeFarewellForm, type WelcomeFarewellFormLabels, type WelcomeFarewellFormProps, WhatsAppCreateTemplateForm, type WhatsAppCreateTemplateFormLabels, type WhatsAppCreateTemplateFormProps, type WhatsAppCreateTemplateResult, type WhatsAppCreateTemplateState, WhatsAppMessageEditor, type WhatsAppMessageEditorLabels, type WhatsAppMessageEditorProps, type WhatsAppTemplateHeaderType, WhatsAppTemplateSettingsForm, type WhatsAppTemplateSettingsFormLabels, type WhatsAppTemplateSettingsFormProps, type WhatsAppTemplateSummary, type WhatsAppTemplateVariableSuggestion, WhatsAppTemplatesSettings, type WhatsAppTemplatesSettingsLabels, type WhatsAppTemplatesSettingsProps, WindowExpiredNotice, type WindowExpiredNoticeLabels, type WindowExpiredNoticeProps, type WindowOfParams, applyQuickReplyVariables, buildTranscriptFilename, buildTranscriptText, createMediaUrlResolver, downloadTextFile, formatDateTime, formatFileSize, formatPhone, formatStalledFor, formatTimestamp, htmlToWA, isSameDay, isWindowBlocking, parseWhatsAppFormatting, phoneInitials, resolveQuickReply, searchEmojis, toast, useConversationActions, useConversationContext, useConversationDocuments, useConversationList, useConversationLocales, useConversationMessages, useConversationRealtime, useConversations, useDarkMode, useGlobalRealtime, useInboxActions, useIsDarkTheme, useIsNarrow, useToast, useWaitingNotifications, waToHTML, waToHTMLInline, windowOf };