@adatechnology/conversations-ui 0.1.0-rc.24 → 0.1.0-rc.26

package/src/flows/index.ts

@@ -9,6 +9,7 @@ export { FlowPortalNode, flowPortalNodeTypes } from './FlowPortalNode'
 export { FlowPalette } from './FlowPalette'
 export { FlowNodePanel } from './FlowNodePanel'
 export { FlowWhatsAppPreview } from './FlowWhatsAppPreview'
+export { FlowsWorkspace } from './FlowsWorkspace'
 
 export { DEFAULT_FLOW_EDITOR_LABELS, mergeFlowEditorLabels } from './labels'
 
@@ -43,7 +44,8 @@ export type {
   CollectionChain,
 } from './flowGraph'
 
-export type { FlowEditorLabels } from './labels'
+export type { FlowEditorLabels, FlowValidationLabels } from './labels'
+export type { FlowsWorkspaceProps, FlowsWorkspaceApi, FlowLivePosition, CreateFlowInput } from './FlowsWorkspace'
 export type { FlowNodeCardData } from './FlowNodeCard'
 export type { FlowMapNodeData } from './FlowMapNode'
 export type { FlowMapCanvasProps } from './FlowMapCanvas'

package/src/flows/labels.ts

@@ -3,6 +3,7 @@ import type { FlowConditionOperator, FlowNodeType, FlowQuestionType } from './fl
 export interface FlowEditorLabels {
   legend: Record<FlowNodeType, string>
   startNodeTooltip: string
+  detachedNodeTooltip: string
   liveCountTooltip: (count: number) => string
   edgeFallbackLabel: string
   // Rótulo por `actionKind` — o host estende esse mapa para registrar seus próprios kinds
@@ -13,6 +14,9 @@ export interface FlowEditorLabels {
   nodePanel: {
     title: string
     contextKey: string
+    nodeName: string
+    nodeNamePlaceholder: string
+    nodeNameHint: string
     questionType: string
     question: string
     options: string
@@ -61,6 +65,8 @@ export interface FlowEditorLabels {
   flowMap: {
     nodeCount: (count: number) => string
     openFlow: string
+    toggleToMap: string
+    toggleToDetail: string
   }
   flowGroup: {
     focus: string
@@ -70,6 +76,67 @@ export interface FlowEditorLabels {
     tooltip: string
     goesTo: (label: string) => string
   }
+  collectionChain: {
+    feeds: (label: string) => string
+  }
+  /**
+   * Texto dos problemas encontrados por `validateGraph`. Vive aqui, e não no host, porque a tela
+   * composta é quem valida — deixar de fora obrigaria todo produto a repassar o mesmo mapa de
+   * funções só para a barra de erros aparecer.
+   */
+  validation: FlowValidationLabels
+  /** Barra de cima, estados de carregamento e ações do editor inteiro. */
+  workspace: {
+    title: string
+    subtitle: string
+    loading: string
+    loadError: string
+    saveGraph: string
+    saving: string
+    saveSuccess: string
+    saveError: string
+    organize: string
+    organizeTooltip: string
+    discardChanges: string
+    discardTooltip: string
+    discardConfirm: string
+    unsavedChangesConfirm: string
+  }
+  flowManager: {
+    newFlow: string
+    createTitle: string
+    key: string
+    keyHint: string
+    keyInvalid: string
+    label: string
+    showInMenu: string
+    menuOptionLabel: string
+    create: string
+    creating: string
+    deleteFlow: string
+    deleteConfirm: (label: string) => string
+    createError: string
+    deleteError: string
+  }
+}
+
+export interface FlowValidationLabels {
+  title: string
+  errors: (count: number) => string
+  warnings: (count: number) => string
+  noStart: string
+  brokenRef: (from: string, to: string) => string
+  choiceWithoutOptions: (id: string) => string
+  duplicatedOptionId: (id: string, optionId: string) => string
+  optionWithoutTarget: (id: string, optionLabel: string) => string
+  tooManyOptions: (id: string, count: number) => string
+  buttonTitleTooLong: (id: string, label: string) => string
+  listTitleTooLong: (id: string, label: string) => string
+  bodyTooLong: (id: string) => string
+  unreachable: (id: string) => string
+  deadEndQuestion: (id: string) => string
+  conditionIncomplete: (id: string) => string
+  conditionBranchMissing: (id: string, branch: string) => string
 }
 
 // Paridade de texto com financiamento-imobiliario-bot/apps/web/src/locales/modules/flows.ts —
@@ -83,6 +150,7 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     condition: 'Condição',
   },
   startNodeTooltip: 'Início do fluxo',
+  detachedNodeTooltip: 'Sem ligação de entrada — o bot não chega neste nó. Puxe um fio de outro card até ele.',
   liveCountTooltip: (count) => `${count} conversa(s) ativa(s) aqui agora`,
   edgeFallbackLabel: 'outro',
   actionKindLabels: {
@@ -111,6 +179,9 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
   nodePanel: {
     title: 'Editar nó',
     contextKey: 'Chave (contexto)',
+    nodeName: 'Nome do nó (opcional)',
+    nodeNamePlaceholder: 'Ex.: Enviar tabela de preços',
+    nodeNameHint: 'Só aparece no editor — o cliente não vê.',
     questionType: 'Tipo de resposta',
     question: 'Texto da pergunta',
     options: 'Opções (choice)',
@@ -160,6 +231,8 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
   flowMap: {
     nodeCount: (count) => `${count} nó(s)`,
     openFlow: 'Abrir fluxo',
+    toggleToMap: 'Mapa de fluxos',
+    toggleToDetail: 'Voltar ao editor',
   },
   flowGroup: {
     focus: 'Focar neste fluxo',
@@ -169,6 +242,61 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     tooltip: 'Clique para abrir esse fluxo aqui do lado, ligado ao ponto de onde ele é chamado',
     goesTo: (label) => `↪ Vai para: ${label}`,
   },
+  collectionChain: {
+    feeds: (label) => `Alimenta: ${label}`,
+  },
+  validation: {
+    title: 'Antes de publicar',
+    errors: (count) => `${count} erro(s) — corrija antes de salvar`,
+    warnings: (count) => `${count} aviso(s)`,
+    noStart: 'O fluxo precisa de um nó inicial válido.',
+    brokenRef: (from, to) => `Nó "${from}": ligação aponta para "${to}", que não existe.`,
+    choiceWithoutOptions: (id) => `Nó "${id}": escolha sem nenhuma opção.`,
+    duplicatedOptionId: (id, optionId) => `Nó "${id}": valor de opção "${optionId}" duplicado.`,
+    optionWithoutTarget: (id, label) => `Nó "${id}": opção "${label}" não tem destino definido.`,
+    tooManyOptions: (id, count) => `Nó "${id}": ${count} opções — o WhatsApp aceita no máximo 10 em lista.`,
+    buttonTitleTooLong: (id, label) => `Nó "${id}": botão "${label}" passa de 20 caracteres.`,
+    listTitleTooLong: (id, label) => `Nó "${id}": item de lista "${label}" passa de 24 caracteres.`,
+    bodyTooLong: (id) => `Nó "${id}": texto passa de 1024 caracteres.`,
+    unreachable: (id) => `Nó "${id}" é inalcançável a partir do início do fluxo.`,
+    deadEndQuestion: (id) => `Nó "${id}": pergunta sem próximo passo definido.`,
+    conditionIncomplete: (id) => `Nó "${id}": condição incompleta — defina variável, operador e valor.`,
+    conditionBranchMissing: (id, branch) =>
+      `Nó "${id}": ramo "${branch === 'true' ? 'Verdadeiro' : 'Falso'}" sem destino definido.`,
+  },
+  workspace: {
+    title: 'Fluxos do Bot',
+    subtitle: 'Blueprint visual dos fluxos de conversa, sincronizado com o que está em produção.',
+    loading: 'Carregando fluxos…',
+    loadError: 'Não foi possível carregar os fluxos.',
+    saveGraph: 'Publicar alterações',
+    saving: 'Publicando…',
+    saveSuccess: 'Fluxo publicado! O bot já está usando a versão nova.',
+    saveError: 'Não foi possível salvar — verifique se todos os destinos apontam para nós existentes.',
+    organize: 'Organizar',
+    organizeTooltip: 'Reorganiza os nós automaticamente e salva as novas posições',
+    discardChanges: 'Desfazer alterações',
+    discardTooltip: 'Devolve os fluxos abertos ao que está publicado, descartando o que não foi salvo',
+    discardConfirm: 'Descartar todas as alterações não publicadas e voltar ao fluxo que está no ar?',
+    unsavedChangesConfirm:
+      'Você tem alterações não publicadas neste fluxo. Trocar de fluxo agora descarta essas edições. Continuar?',
+  },
+  flowManager: {
+    newFlow: 'Novo fluxo',
+    createTitle: 'Criar novo fluxo',
+    key: 'Identificador único',
+    keyHint: 'letras minúsculas, números e _ (ex.: promocoes_semana)',
+    keyInvalid: 'Use apenas letras minúsculas, números e _ (2 a 40 caracteres)',
+    label: 'Nome exibido',
+    showInMenu: 'Exibir como opção no menu principal do bot',
+    menuOptionLabel: 'Texto da opção no menu',
+    create: 'Criar fluxo',
+    creating: 'Criando…',
+    deleteFlow: 'Excluir fluxo',
+    deleteConfirm: (label) => `Excluir o fluxo "${label}"? Esta ação não pode ser desfeita.`,
+    createError: 'Não foi possível criar o fluxo.',
+    deleteError: 'Não foi possível excluir o fluxo.',
+  },
 }
 
 export function mergeFlowEditorLabels(override?: Partial<FlowEditorLabels>): FlowEditorLabels {
@@ -188,5 +316,9 @@ export function mergeFlowEditorLabels(override?: Partial<FlowEditorLabels>): Flo
     flowMap: { ...DEFAULT_FLOW_EDITOR_LABELS.flowMap, ...override.flowMap },
     flowGroup: { ...DEFAULT_FLOW_EDITOR_LABELS.flowGroup, ...override.flowGroup },
     crossFlowPortal: { ...DEFAULT_FLOW_EDITOR_LABELS.crossFlowPortal, ...override.crossFlowPortal },
+    collectionChain: { ...DEFAULT_FLOW_EDITOR_LABELS.collectionChain, ...override.collectionChain },
+    validation: { ...DEFAULT_FLOW_EDITOR_LABELS.validation, ...override.validation },
+    workspace: { ...DEFAULT_FLOW_EDITOR_LABELS.workspace, ...override.workspace },
+    flowManager: { ...DEFAULT_FLOW_EDITOR_LABELS.flowManager, ...override.flowManager },
   }
 }

package/src/hooks/useUrlFilterState.ts

@@ -0,0 +1,107 @@
+/**
+ * Estado de listagem espelhado na URL — ordenação, filtros e paginação (regra `web.md` §7).
+ *
+ * Escrito sobre `history.replaceState` e não sobre um router: o pacote roda em três produtos com
+ * routers diferentes, e exigir um deles arrastaria dependência de framework para dentro do módulo.
+ * `replaceState` também é o comportamento certo aqui — filtrar não é navegar, e cada tecla digitada
+ * na busca não deve virar uma entrada no botão "voltar".
+ */
+
+import { useCallback, useEffect, useState } from 'react'
+
+const LIST_SEPARATOR = ','
+
+function readParams(): URLSearchParams {
+  if (typeof window === 'undefined') return new URLSearchParams()
+  return new URLSearchParams(window.location.search)
+}
+
+function writeParam(key: string, value: string | undefined): void {
+  if (typeof window === 'undefined') return
+  const params = readParams()
+  if (value === undefined || value === '') params.delete(key)
+  else params.set(key, value)
+  const query = params.toString()
+  window.history.replaceState(null, '', query ? `${window.location.pathname}?${query}` : window.location.pathname)
+}
+
+/** `enabled: false` mantém o mesmo contrato de estado sem tocar na URL — para uso em preview e teste. */
+export interface UrlStateOptions {
+  readonly enabled?: boolean
+}
+
+export function useUrlStringState(
+  key: string,
+  initial: string,
+  { enabled = true }: UrlStateOptions = {},
+): [string, (next: string) => void] {
+  const [value, setValue] = useState(() => (enabled ? (readParams().get(key) ?? initial) : initial))
+
+  const update = useCallback(
+    (next: string) => {
+      setValue(next)
+      if (enabled) writeParam(key, next === initial ? undefined : next)
+    },
+    [enabled, key, initial],
+  )
+
+  return [value, update]
+}
+
+export function useUrlNumberState(
+  key: string,
+  initial: number,
+  { enabled = true }: UrlStateOptions = {},
+): [number, (next: number) => void] {
+  const [value, setValue] = useState(() => {
+    if (!enabled) return initial
+    const raw = Number(readParams().get(key))
+    return Number.isFinite(raw) && raw > 0 ? raw : initial
+  })
+
+  const update = useCallback(
+    (next: number) => {
+      setValue(next)
+      if (enabled) writeParam(key, next === initial ? undefined : String(next))
+    },
+    [enabled, key, initial],
+  )
+
+  return [value, update]
+}
+
+export function useUrlArrayState(
+  key: string,
+  { enabled = true }: UrlStateOptions = {},
+): [readonly string[], (next: readonly string[]) => void] {
+  const [value, setValue] = useState<readonly string[]>(() => {
+    if (!enabled) return []
+    const raw = readParams().get(key)
+    return raw ? raw.split(LIST_SEPARATOR).filter(Boolean) : []
+  })
+
+  const update = useCallback(
+    (next: readonly string[]) => {
+      setValue(next)
+      if (enabled) writeParam(key, next.length > 0 ? next.join(LIST_SEPARATOR) : undefined)
+    },
+    [enabled, key],
+  )
+
+  return [value, update]
+}
+
+/**
+ * Espera o usuário parar de digitar antes de deixar o valor chegar à query. Sem isto, cada tecla
+ * na busca vira uma chamada de rede e uma reescrita de URL.
+ */
+export function useDebouncedValue<TValue>(value: TValue, delayMs = 300): TValue {
+  const [debounced, setDebounced] = useState(value)
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delayMs)
+    return () => clearTimeout(timer)
+  }, [value, delayMs])
+
+  return debounced
+}

package/src/index.ts

@@ -86,6 +86,24 @@ export { WindowExpiredNotice, isWindowBlocking, DEFAULT_WINDOW_EXPIRED_LABELS }
 export type { WindowExpiredNoticeProps, WindowExpiredNoticeLabels } from './WindowExpiredNotice'
 export { DocumentsLibrary, DEFAULT_DOCUMENTS_LIBRARY_LABELS } from './DocumentsLibrary'
 export type { DocumentsLibraryProps, DocumentsLibraryLabels, DocumentsLibraryClassNames } from './DocumentsLibrary'
+export { DocumentsWorkspace, DEFAULT_DOCUMENTS_WORKSPACE_LABELS } from './documents'
+export type {
+  DocumentsWorkspaceProps,
+  DocumentsWorkspaceLabels,
+  DocumentsWorkspaceClassNames,
+  DocumentsFiltersContext,
+} from './documents'
+export { SortableHead, MultiSelectFilter, BulkActionBar, ListingPagination } from './listing'
+export type {
+  SortableHeadProps,
+  MultiSelectFilterProps,
+  BulkActionBarProps,
+  ListingPaginationProps,
+  FilterOption,
+  SortDirection,
+} from './listing'
+export { useUrlStringState, useUrlNumberState, useUrlArrayState, useDebouncedValue } from './hooks/useUrlFilterState'
+export type { UrlStateOptions } from './hooks/useUrlFilterState'
 export { DOCUMENT_SOURCE_FILTER } from './ConversationDocumentsPanel'
 export type { DocumentSourceFilter } from './ConversationDocumentsPanel'
 export type { ConversationDocumentsPanelClassNames } from './ConversationDocumentsPanel'
@@ -118,6 +136,18 @@ export {
 } from './settings/WhatsAppTemplatesSettings'
 export { TopicsForm } from './settings/TopicsForm'
 
+// Tela composta de Mensagens: junta os formulários acima com abas, estado e salvamento, para o
+// host não remontar essa mesma colagem em cada produto (foi assim que eles divergiram).
+export { MessagesWorkspace } from './settings/MessagesWorkspace'
+export type {
+  MessagesWorkspaceProps,
+  MessagesWorkspaceApi,
+  MessagesWorkspaceLabels,
+  BotMessages,
+  TemplateSettings,
+  TranscriptionSettings,
+} from './settings/MessagesWorkspace'
+
 // Camada headless (T6.9) — hooks de dados/ações independentes de qualquer tela, para o
 // produto montar sua própria UI sobre eles. Requerem <ConversationsProvider> como ancestral.
 export { useConversationMessages } from './hooks/useConversationMessages'

package/src/listing/index.tsx

@@ -0,0 +1,198 @@
+/**
+ * Peças de listagem que toda tela tabular do pacote precisa ter iguais: cabeçalho ordenável,
+ * filtro de seleção múltipla, barra de ação em lote e paginação (regra `web.md` §7).
+ *
+ * Vivem aqui, e não dentro de cada tela, porque a alternativa já se provou pior: cada workspace
+ * recriava o seu, e o mesmo "limpar filtros" ficava em três lugares com três comportamentos.
+ */
+
+import { useState, type ReactNode } from 'react'
+import { ArrowDown, ArrowUp, ArrowUpDown, ChevronDown, X } from 'lucide-react'
+
+import { cn } from '../lib/cn'
+
+export type SortDirection = 'asc' | 'desc'
+
+export interface SortableHeadProps {
+  readonly label: string
+  readonly field: string
+  readonly activeField: string
+  readonly direction: SortDirection
+  readonly onSort: (field: string) => void
+  readonly className?: string
+}
+
+export function SortableHead({ label, field, activeField, direction, onSort, className }: SortableHeadProps) {
+  const isActive = activeField === field
+  const Icon = !isActive ? ArrowUpDown : direction === 'asc' ? ArrowUp : ArrowDown
+
+  return (
+    <th scope="col" className={cn('px-3 py-2 text-left text-xs font-medium', className)}>
+      <button
+        type="button"
+        onClick={() => onSort(field)}
+        aria-label={label}
+        className="inline-flex items-center gap-1 hover:text-gray-900 dark:hover:text-gray-100"
+      >
+        {label}
+        <Icon size={12} className={isActive ? '' : 'opacity-40'} aria-hidden="true" />
+      </button>
+    </th>
+  )
+}
+
+export interface FilterOption {
+  readonly value: string
+  readonly label: string
+}
+
+export interface MultiSelectFilterProps {
+  readonly label: string
+  readonly options: readonly FilterOption[]
+  readonly selected: readonly string[]
+  readonly onChange: (selected: readonly string[]) => void
+  readonly className?: string
+}
+
+export function MultiSelectFilter({ label, options, selected, onChange, className }: MultiSelectFilterProps) {
+  const [open, setOpen] = useState(false)
+
+  function toggle(value: string): void {
+    onChange(selected.includes(value) ? selected.filter((item) => item !== value) : [...selected, value])
+  }
+
+  return (
+    <div className={cn('relative', className)}>
+      <button
+        type="button"
+        onClick={() => setOpen((current) => !current)}
+        className="cv-header-action inline-flex items-center gap-1"
+      >
+        {label}
+        {selected.length > 0 ? <span className="cv-filter-count">{selected.length}</span> : null}
+        <ChevronDown size={12} className={open ? 'rotate-180 transition-transform' : 'transition-transform'} aria-hidden="true" />
+      </button>
+
+      {open ? (
+        <>
+          {/* Sem a camada de fundo o dropdown só fechava clicando de novo no botão, e ficava aberto
+              por cima da tabela enquanto o usuário tentava clicar numa linha. */}
+          <div className="fixed inset-0 z-10" onClick={() => setOpen(false)} />
+          <div className="cv-filter-menu">
+            {options.map((option) => (
+              <label key={option.value} className="cv-filter-option">
+                <input
+                  type="checkbox"
+                  checked={selected.includes(option.value)}
+                  onChange={() => toggle(option.value)}
+                  className="cursor-pointer rounded border-gray-300 text-blue-600 dark:border-gray-600"
+                />
+                {option.label}
+              </label>
+            ))}
+          </div>
+        </>
+      ) : null}
+    </div>
+  )
+}
+
+export interface BulkActionBarProps {
+  readonly selectedCount: number
+  readonly selectedLabel: (count: number) => string
+  readonly clearLabel: string
+  readonly onClear: () => void
+  readonly children?: ReactNode
+}
+
+export function BulkActionBar({ selectedCount, selectedLabel, clearLabel, onClear, children }: BulkActionBarProps) {
+  if (selectedCount === 0) return null
+
+  return (
+    <div className="cv-bulk-bar" role="toolbar" aria-label={selectedLabel(selectedCount)}>
+      <span className="text-xs font-medium">{selectedLabel(selectedCount)}</span>
+      {children}
+      <button type="button" onClick={onClear} className="cv-header-action ml-auto inline-flex items-center gap-1">
+        <X size={12} aria-hidden="true" />
+        {clearLabel}
+      </button>
+    </div>
+  )
+}
+
+export interface ListingPaginationProps {
+  readonly page: number
+  readonly total: number
+  readonly perPage: number
+  readonly perPageOptions?: readonly number[]
+  readonly onPageChange: (page: number) => void
+  readonly onPerPageChange?: (perPage: number) => void
+  readonly labels: {
+    readonly show: string
+    readonly perPage: string
+    readonly total: (count: number) => string
+    readonly page: (current: number, last: number) => string
+    readonly previous: string
+    readonly next: string
+  }
+}
+
+export function ListingPagination({
+  page,
+  total,
+  perPage,
+  perPageOptions,
+  onPageChange,
+  onPerPageChange,
+  labels,
+}: ListingPaginationProps) {
+  const lastPage = Math.max(1, Math.ceil(total / perPage))
+
+  return (
+    <div className="cv-listing-pagination">
+      <div className="flex items-center gap-2 text-xs text-gray-500 dark:text-gray-400">
+        {onPerPageChange && perPageOptions ? (
+          <>
+            <span>{labels.show}</span>
+            <select
+              value={perPage}
+              onChange={(event) => onPerPageChange(Number(event.target.value))}
+              aria-label={labels.perPage}
+              className="cv-listing-perpage"
+            >
+              {perPageOptions.map((option) => (
+                <option key={option} value={option}>
+                  {option}
+                </option>
+              ))}
+            </select>
+            <span>{labels.perPage}</span>
+          </>
+        ) : null}
+        <span className="ml-1">{labels.total(total)}</span>
+      </div>
+
+      <div className="flex items-center gap-2">
+        <button
+          type="button"
+          onClick={() => onPageChange(page - 1)}
+          disabled={page <= 1}
+          aria-label={labels.previous}
+          className="cv-header-icon disabled:opacity-40"
+        >
+          ‹
+        </button>
+        <span className="text-xs text-gray-500">{labels.page(page, lastPage)}</span>
+        <button
+          type="button"
+          onClick={() => onPageChange(page + 1)}
+          disabled={page >= lastPage}
+          aria-label={labels.next}
+          className="cv-header-icon disabled:opacity-40"
+        >
+          ›
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/providers/types.ts

@@ -31,14 +31,38 @@ export interface ListDocumentsParams {
   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. */
+  /**
+   * 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. */
 export 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
 }
 
 export interface CompanyDocumentPage {
@@ -110,6 +134,17 @@ export interface ConversationsApi {
    * 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>
   getMediaProxyUrl(mediaId: string): Promise<{ mimeType: string; data: string }>
 
   /**