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

package/src/MessageComposer.tsx

@@ -1,8 +1,56 @@
-import { useState, useRef, useCallback, type KeyboardEvent, type ChangeEvent } from 'react'
+import { useState, useRef, useCallback, type KeyboardEvent, type ChangeEvent, type ReactNode } from 'react'
 import type { ConversationsFeatures } from './types'
+import { cn } from './lib/cn'
 import { EmojiPicker } from './EmojiPicker'
 
+/**
+ * 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.
+ */
+export 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á !".
+ */
+export function applyQuickReplyVariables(
+  template: string,
+  variables: Readonly<Record<string, string>> = {},
+): string {
+  return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, chave: string) => variables[chave] ?? '')
+}
+
+export function resolveQuickReply(
+  quickReply: QuickReply,
+  variables: Readonly<Record<string, string>> = {},
+): string {
+  return typeof quickReply.text === 'function'
+    ? quickReply.text(variables)
+    : applyQuickReplyVariables(quickReply.text, variables)
+}
+
+export interface MessageComposerLabels {
+  emoji: string
+  attach: string
+  send: string
+}
+
+export const DEFAULT_MESSAGE_COMPOSER_LABELS: MessageComposerLabels = {
+  emoji: 'Emoji',
+  attach: 'Anexar',
+  send: 'Enviar',
+}
+
 export interface MessageComposerProps {
+  labels?: Partial<MessageComposerLabels>
   onSend: (text: string) => void
   onAttach?: (file: File) => void
   value?: string
@@ -12,10 +60,42 @@ export 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>
 }
 
-// Paridade com financiamento-imobiliario-bot/apps/web/src/pages/ConversationsPage.tsx:1490
-const DEFAULT_ACCEPTED_FILE_TYPES = 'image/*,video/*,audio/*,.pdf,.doc,.docx,.xls,.xlsx,.zip'
+export 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`.
+ */
+export const DEFAULT_ACCEPTED_FILE_TYPES = [
+  'image/jpeg,image/png,image/webp',
+  'audio/aac,audio/mp4,audio/mpeg,audio/amr,audio/ogg',
+  'video/mp4,video/3gpp',
+  'application/pdf,text/plain,text/csv',
+  'application/msword,application/vnd.ms-excel,application/vnd.ms-powerpoint',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+].join(',')
 
 interface FilePreview {
   file: File
@@ -27,12 +107,21 @@ export const MessageComposer = ({
   onAttach,
   value: externalValue,
   onChange: externalOnChange,
+  quickReplies,
+  quickReplyVariables,
   features,
   placeholder = 'Digite uma mensagem...',
   maxLength,
   disabled = false,
   acceptedFileTypes = DEFAULT_ACCEPTED_FILE_TYPES,
+  idleAction,
+  className,
+  classNames,
+  labels,
 }: MessageComposerProps) => {
+  const emojiLabel = labels?.emoji ?? DEFAULT_MESSAGE_COMPOSER_LABELS.emoji
+  const attachLabel = labels?.attach ?? DEFAULT_MESSAGE_COMPOSER_LABELS.attach
+  const sendLabel = labels?.send ?? DEFAULT_MESSAGE_COMPOSER_LABELS.send
   const [internalText, setInternalText] = useState('')
   const [showEmoji, setShowEmoji] = useState(false)
   const [attachments, setAttachments] = useState<FilePreview[]>([])
@@ -134,7 +223,41 @@ export const MessageComposer = ({
   const remaining = maxLength ? maxLength - text.length : null
 
   return (
-    <div>
+    /* A barra é a superfície (cinza, largura cheia, sem raio) e o campo dentro é que arredonda —
+       ordem do WhatsApp. Invertido, o pill arredondado ia até a borda da tela e os cantos
+       descobriam o fundo branco da página, que lia como defeito. */
+    <div className={cn('bg-[#f0f2f5] px-2 py-2', className)}>
+      {/* Uma linha com scroll no celular e wrap no desktop: em 375px seis chips em wrap empurrariam
+          o campo para fora da tela, e o campo é a razão de a barra existir. */}
+      {quickReplies && quickReplies.length > 0 && (
+        <div
+          className={cn(
+            'mb-2 flex flex-nowrap gap-1 overflow-x-auto px-1 sm:flex-wrap sm:overflow-x-visible [scrollbar-width:none] [&::-webkit-scrollbar]:hidden',
+            classNames?.quickReplies,
+          )}
+        >
+          {quickReplies.map((quickReply) => (
+            <button
+              key={quickReply.key}
+              type="button"
+              // Preenche o campo em vez de enviar: mensagem pronta é ponto de partida, e quem
+              // atende quase sempre ajusta uma palavra antes de mandar. Enviar direto no clique
+              // transformaria um toque errado em mensagem entregue ao cliente.
+              onClick={() => {
+                setText(resolveQuickReply(quickReply, quickReplyVariables))
+                textareaRef.current?.focus()
+              }}
+              className={cn(
+                'whitespace-nowrap rounded-full border border-gray-200 bg-white px-2 py-1 text-xs text-gray-600 transition-colors hover:border-teal-200 hover:bg-teal-50 hover:text-teal-700 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-400',
+                classNames?.quickReply,
+              )}
+            >
+              {quickReply.label}
+            </button>
+          ))}
+        </div>
+      )}
+
       {attachments.length > 0 && (
         <div className="flex gap-2 px-1 pb-2 overflow-x-auto">
           {attachments.map((a, i) => (
@@ -152,10 +275,10 @@ export const MessageComposer = ({
         </div>
       )}
 
-      <div className="flex items-end gap-1.5 bg-[#f0f2f5] rounded-xl px-3 py-2">
+      <div className={cn('flex items-end gap-1.5 rounded-xl bg-white px-3 py-2', classNames?.field)}>
         {showEmojiButton && (
           <div className="relative flex-shrink-0">
-            <button onClick={() => setShowEmoji(v => !v)} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 transition-colors" aria-label="Emoji">
+            <button onClick={() => setShowEmoji(v => !v)} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 transition-colors" aria-label={emojiLabel}>
               <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><circle cx="12" cy="12" r="10"/><path d="M8 14s1.5 2 4 2 4-2 4-2"/><circle cx="9" cy="9" r="0.5" fill="currentColor"/><circle cx="15" cy="9" r="0.5" fill="currentColor"/></svg>
             </button>
             {showEmoji && (
@@ -181,24 +304,28 @@ export const MessageComposer = ({
         {showAttachButton && (
           <>
             <input ref={fileInputRef} type="file" multiple accept={acceptedFileTypes} onChange={handleFileChange} className="hidden" />
-            <button onClick={() => fileInputRef.current?.click()} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 flex-shrink-0 transition-colors" aria-label="Anexar">
+            <button onClick={() => fileInputRef.current?.click()} className="w-9 h-9 flex items-center justify-center rounded-full text-gray-500 hover:bg-gray-200 flex-shrink-0 transition-colors" aria-label={attachLabel}>
               <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2"><path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
             </button>
           </>
         )}
 
-        <button
-          onClick={sendMessage}
-          disabled={!canSend || disabled}
-          className={`w-10 h-10 flex items-center justify-center rounded-full flex-shrink-0 transition-all ${
-            canSend && !disabled
-              ? 'bg-[#00a884] text-white hover:bg-[#06cf9c] shadow-sm'
-              : 'bg-gray-200 text-gray-400 cursor-not-allowed'
-          }`}
-          aria-label="Enviar"
-        >
-          <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z"/></svg>
-        </button>
+        {!canSend && idleAction ? (
+          <div className="flex-shrink-0">{idleAction}</div>
+        ) : (
+          <button
+            onClick={sendMessage}
+            disabled={!canSend || disabled}
+            className={`w-10 h-10 flex items-center justify-center rounded-full flex-shrink-0 transition-all ${
+              canSend && !disabled
+                ? 'bg-[#00a884] text-white hover:bg-[#06cf9c] shadow-sm'
+                : 'bg-gray-200 text-gray-400 cursor-not-allowed'
+            }`}
+            aria-label={sendLabel}
+          >
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z"/></svg>
+          </button>
+        )}
       </div>
 
       {remaining !== null && (

package/src/Wallpaper.test.tsx

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ConversationWallpaper } from './Wallpaper'
+
+describe('ConversationWallpaper', () => {
+  it('desenha o fundo sozinho, sem depender do styles.css do host', () => {
+    const markup = renderToStaticMarkup(<ConversationWallpaper />)
+
+    expect(markup).toContain('background-color:#efeae2')
+    expect(markup).toContain('background-image:url(&quot;data:image/svg+xml,')
+    expect(markup).toContain('cv-wallpaper')
+  })
+
+  it('deixa o produto sobrescrever o fundo por style', () => {
+    const markup = renderToStaticMarkup(<ConversationWallpaper style={{ backgroundColor: '#123456' }} />)
+
+    expect(markup).toContain('background-color:#123456')
+    expect(markup).not.toContain('background-color:#efeae2')
+  })
+})

package/src/Wallpaper.tsx

@@ -1,13 +1,61 @@
-import type { ReactNode } from 'react'
+/**
+ * Fundo da conversa — a textura clara/escura do WhatsApp.
+ *
+ * O fundo vem embutido, e não da folha de estilo do pacote: `styles.css` é um import opcional que o
+ * host precisa lembrar de fazer, e esquecê-lo deixava a conversa sobre branco liso, sem erro nenhum
+ * para denunciar o problema. Fundo é identidade do componente, não tema do host.
+ *
+ * A classe `cv-wallpaper` continua no elemento para quem já sobrescreve por CSS.
+ */
+
+import type { CSSProperties, ReactNode } from 'react'
+
+import { cn } from './lib/cn'
+import { useIsDarkTheme } from './useDarkMode'
+
+/** Textura do WhatsApp: rabiscos esparsos que se repetem a cada 100px. */
+function doodlePattern(strokeColor: string, opacity: number): string {
+  const svg =
+    `<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'>` +
+    `<g fill='none' stroke='${strokeColor}' stroke-width='1.2' opacity='${opacity}'>` +
+    `<circle cx='15' cy='15' r='3'/><path d='M40 10 q5 8 0 16 q-5 -8 0 -16z'/>` +
+    `<circle cx='70' cy='28' r='2'/><path d='M18 55 l6 6 m-6 0 l6 -6'/>` +
+    `<circle cx='55' cy='68' r='2.5'/><path d='M85 58 q6 6 0 12 q-6 -6 0 -12z'/>` +
+    `<circle cx='8' cy='85' r='2'/><path d='M65 90 l5 5 m-5 0 l5 -5'/>` +
+    `</g></svg>`
+  return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`
+}
+
+const LIGHT_WALLPAPER: CSSProperties = {
+  backgroundColor: '#efeae2',
+  backgroundImage: doodlePattern('#d7cfc0', 0.7),
+  backgroundRepeat: 'repeat',
+  backgroundSize: '100px 100px',
+}
+
+const DARK_WALLPAPER: CSSProperties = {
+  backgroundColor: '#0b141a',
+  backgroundImage: doodlePattern('#19232a', 0.9),
+  backgroundRepeat: 'repeat',
+  backgroundSize: '100px 100px',
+}
 
 export interface ConversationWallpaperProps {
   children?: ReactNode
   className?: string
+  /** Ajusta ou substitui o fundo padrão — para produto com identidade visual própria. */
+  style?: CSSProperties
 }
 
-// Requer o import de '@adatechnology/conversations-ui/styles.css' uma vez no host —
-// a classe `.cv-wallpaper` (e sua variante `.dark`) vive nesse stylesheet, não em CSS-in-JS,
-// para não depender da configuração de Tailwind do consumidor.
-export function ConversationWallpaper({ children, className = '' }: ConversationWallpaperProps) {
-  return <div className={`cv-wallpaper ${className}`.trim()}>{children}</div>
+export function ConversationWallpaper({ children, className, style }: ConversationWallpaperProps) {
+  const isDark = useIsDarkTheme()
+
+  return (
+    <div
+      className={cn('cv-wallpaper', className)}
+      style={{ ...(isDark ? DARK_WALLPAPER : LIGHT_WALLPAPER), ...style }}
+    >
+      {children}
+    </div>
+  )
 }

package/src/WhatsAppMessageEditor.tsx

@@ -1,7 +1,29 @@
 import { useRef, type ReactNode } from 'react'
 import { Bold, Italic, Strikethrough } from 'lucide-react'
 
+export 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
+}
+
+export const DEFAULT_WHATSAPP_MESSAGE_EDITOR_LABELS: WhatsAppMessageEditorLabels = {
+  bold: 'Negrito',
+  boldHint: 'Negrito (*texto*)',
+  italic: 'Itálico',
+  italicHint: 'Itálico (_texto_)',
+  strikethrough: 'Tachado',
+  strikethroughHint: 'Tachado (~texto~)',
+  insertPlaceholder: (token: string) => `Inserir ${token}`,
+}
+
 export interface WhatsAppMessageEditorProps {
+  labels?: Partial<WhatsAppMessageEditorLabels>
   value: string
   onChange: (value: string) => void
   placeholder?: string
@@ -56,7 +78,9 @@ export function WhatsAppMessageEditor({
   rows = 4,
   previewLabel = 'Prévia (como aparece no WhatsApp)',
   emptyPreviewText = 'Sua mensagem aparecerá aqui…',
+  labels,
 }: WhatsAppMessageEditorProps) {
+  const editorLabels = { ...DEFAULT_WHATSAPP_MESSAGE_EDITOR_LABELS, ...labels }
   const textareaRef = useRef<HTMLTextAreaElement>(null)
 
   function wrapSelection(marker: string): void {
@@ -93,13 +117,13 @@ export function WhatsAppMessageEditor({
   return (
     <div>
       <div className="flex flex-wrap items-center gap-1.5 mb-2">
-        <button type="button" onClick={() => wrapSelection('*')} className={toolbarButtonClass} title="Negrito (*texto*)" aria-label="Negrito">
+        <button type="button" onClick={() => wrapSelection('*')} className={toolbarButtonClass} title={editorLabels.boldHint} aria-label={editorLabels.bold}>
           <Bold size={15} />
         </button>
-        <button type="button" onClick={() => wrapSelection('_')} className={toolbarButtonClass} title="Itálico (_texto_)" aria-label="Itálico">
+        <button type="button" onClick={() => wrapSelection('_')} className={toolbarButtonClass} title={editorLabels.italicHint} aria-label={editorLabels.italic}>
           <Italic size={15} />
         </button>
-        <button type="button" onClick={() => wrapSelection('~')} className={toolbarButtonClass} title="Tachado (~texto~)" aria-label="Tachado">
+        <button type="button" onClick={() => wrapSelection('~')} className={toolbarButtonClass} title={editorLabels.strikethroughHint} aria-label={editorLabels.strikethrough}>
           <Strikethrough size={15} />
         </button>
         {placeholders.length > 0 && (
@@ -111,7 +135,7 @@ export function WhatsAppMessageEditor({
                 type="button"
                 onClick={() => insertAtCursor(token)}
                 className="inline-flex items-center h-8 px-2 rounded-lg border border-gray-200 dark:border-gray-600 text-xs text-blue-600 dark:text-blue-300 hover:bg-blue-50 dark:hover:bg-blue-900/40 transition-colors"
-                title={`Inserir ${token}`}
+                title={editorLabels.insertPlaceholder(token)}
               >
                 {token}
               </button>

package/src/WindowExpiredNotice.tsx

@@ -0,0 +1,57 @@
+/**
+ * Aviso de janela de 24h expirada, no lugar do composer.
+ *
+ * Trocar o composer pelo aviso, em vez de deixar o campo lá e falhar no envio, é o ponto: fora da
+ * janela o WhatsApp recusa texto livre, e um campo habilitado promete algo que a plataforma não
+ * cumpre. O caminho que resta — template — fica visível na mesma altura da tela.
+ */
+
+import { CONVERSATION_WINDOW, type ConversationWindow } from './conversationWindow'
+import { cn } from './lib/cn'
+
+export interface WindowExpiredNoticeLabels {
+  title: string
+  description: string
+  sendTemplate: string
+}
+
+export const DEFAULT_WINDOW_EXPIRED_LABELS: WindowExpiredNoticeLabels = {
+  title: '⏰ Janela de 24h expirada — o WhatsApp não aceita mensagens livres.',
+  description: 'Envie uma mensagem de template para reabrir a conversa com o cliente.',
+  sendTemplate: '📨 Enviar Template (HSM)',
+}
+
+export interface WindowExpiredNoticeProps {
+  onSendTemplate?: () => void
+  disabled?: boolean
+  labels?: Partial<WindowExpiredNoticeLabels>
+  className?: string
+}
+
+export function WindowExpiredNotice({
+  onSendTemplate,
+  disabled = false,
+  labels: labelsOverride,
+  className,
+}: WindowExpiredNoticeProps) {
+  const labels = { ...DEFAULT_WINDOW_EXPIRED_LABELS, ...labelsOverride }
+
+  return (
+    <div role="status" className={cn('border-t bg-yellow-50 px-4 py-3 text-sm dark:bg-yellow-950', className)}>
+      <p className="font-medium text-yellow-900 dark:text-yellow-200">{labels.title}</p>
+      <p className="text-yellow-800 dark:text-yellow-300">{labels.description}</p>
+      {onSendTemplate ? (
+        <button type="button" onClick={onSendTemplate} disabled={disabled} className="cv-header-action mt-2">
+          {labels.sendTemplate}
+        </button>
+      ) : null}
+    </div>
+  )
+}
+
+/**
+ * Só a faixa `expired` bloqueia: 21-24h ainda aceita texto livre e merece alerta, não impedimento.
+ */
+export function isWindowBlocking(window: ConversationWindow): boolean {
+  return window === CONVERSATION_WINDOW.EXPIRED
+}

package/src/conversationChannel.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'bun:test'
+import { CONVERSATION_CHANNEL, CHANNEL_FILTER_ALL, channelFiltersFor } from './conversationChannel'
+
+describe('channelFiltersFor', () => {
+  // O ponto do helper: a barra oferece só o que existe. Oferecer Instagram numa conta que só tem
+  // WhatsApp promete um recorte que nunca traz resultado.
+  it('lista apenas os canais presentes, com Todos na frente', () => {
+    const options = channelFiltersFor([
+      { channel: CONVERSATION_CHANNEL.WHATSAPP },
+      { channel: CONVERSATION_CHANNEL.INSTAGRAM },
+      { channel: CONVERSATION_CHANNEL.WHATSAPP },
+    ])
+
+    expect(options.map((option) => option.value)).toEqual([
+      CHANNEL_FILTER_ALL,
+      CONVERSATION_CHANNEL.WHATSAPP,
+      CONVERSATION_CHANNEL.INSTAGRAM,
+    ])
+  })
+
+  it('não oferece filtro quando há um canal só', () => {
+    expect(channelFiltersFor([{ channel: CONVERSATION_CHANNEL.WHATSAPP }, {}])).toEqual([])
+  })
+
+  it('não oferece filtro para lista vazia', () => {
+    expect(channelFiltersFor([])).toEqual([])
+  })
+
+  // Conversa sem canal é WhatsApp por compatibilidade — não pode virar uma quinta opção fantasma.
+  it('trata ausência de canal como whatsapp', () => {
+    const options = channelFiltersFor([{}, { channel: CONVERSATION_CHANNEL.WEBCHAT }])
+
+    expect(options.map((option) => option.value)).toEqual([
+      CHANNEL_FILTER_ALL,
+      CONVERSATION_CHANNEL.WHATSAPP,
+      CONVERSATION_CHANNEL.WEBCHAT,
+    ])
+  })
+
+  // Ordem do catálogo: se dependesse da ordem de chegada, a barra se reorganizaria a cada refetch.
+  it('mantém ordem estável independente da ordem da lista', () => {
+    const first = channelFiltersFor([
+      { channel: CONVERSATION_CHANNEL.WEBCHAT },
+      { channel: CONVERSATION_CHANNEL.WHATSAPP },
+    ])
+    const second = channelFiltersFor([
+      { channel: CONVERSATION_CHANNEL.WHATSAPP },
+      { channel: CONVERSATION_CHANNEL.WEBCHAT },
+    ])
+
+    expect(first).toEqual(second)
+  })
+})

package/src/conversationChannel.ts

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+
+import { formatPhone, phoneCountryFlag } from './lib/phone'
+
+export const CONVERSATION_CHANNEL = {
+  WHATSAPP: 'whatsapp',
+  MESSENGER: 'messenger',
+  INSTAGRAM: 'instagram',
+  WEBCHAT: 'webchat',
+} as const
+export type ConversationChannel = (typeof CONVERSATION_CHANNEL)[keyof typeof CONVERSATION_CHANNEL]
+
+export const DEFAULT_CONVERSATION_CHANNEL: ConversationChannel = CONVERSATION_CHANNEL.WHATSAPP
+
+/** Como o canal reabre uma conversa fora da janela de sessão. */
+export const REOPEN_MECHANISM = {
+  TEMPLATE: 'template',
+  TAG: 'tag',
+  NONE: 'none',
+} as const
+export type ReopenMechanism = (typeof REOPEN_MECHANISM)[keyof typeof REOPEN_MECHANISM]
+
+/** Natureza do identificador do contato — decide como exibi-lo. */
+export const HANDLE_KIND = {
+  PHONE: 'phone',
+  USERNAME: 'username',
+  SESSION: 'session',
+} as const
+export type HandleKind = (typeof HANDLE_KIND)[keyof typeof HANDLE_KIND]
+
+export type ChannelCapabilities = {
+  readonly label: string
+  readonly icon: string
+  readonly hasSessionWindow: boolean
+  readonly windowHours: number
+  readonly reopenMechanism: ReopenMechanism
+  readonly handleKind: HandleKind
+}
+
+export const CHANNEL_CAPABILITIES: Readonly<Record<ConversationChannel, ChannelCapabilities>> = {
+  [CONVERSATION_CHANNEL.WHATSAPP]: {
+    label: 'WhatsApp',
+    icon: '💬',
+    hasSessionWindow: true,
+    windowHours: 24,
+    reopenMechanism: REOPEN_MECHANISM.TEMPLATE,
+    handleKind: HANDLE_KIND.PHONE,
+  },
+  [CONVERSATION_CHANNEL.MESSENGER]: {
+    // Messenger também tem 24h, mas reabre com message tag — não com template aprovado.
+    label: 'Messenger',
+    icon: '📨',
+    hasSessionWindow: true,
+    windowHours: 24,
+    reopenMechanism: REOPEN_MECHANISM.TAG,
+    handleKind: HANDLE_KIND.USERNAME,
+  },
+  [CONVERSATION_CHANNEL.INSTAGRAM]: {
+    label: 'Instagram',
+    icon: '📷',
+    hasSessionWindow: true,
+    windowHours: 24,
+    reopenMechanism: REOPEN_MECHANISM.TAG,
+    handleKind: HANDLE_KIND.USERNAME,
+  },
+  [CONVERSATION_CHANNEL.WEBCHAT]: {
+    // Chat próprio: sem intermediário, sem janela. Bloquear o composer aqui seria inventar limite.
+    label: 'Chat do site',
+    icon: '🌐',
+    hasSessionWindow: false,
+    windowHours: 0,
+    reopenMechanism: REOPEN_MECHANISM.NONE,
+    handleKind: HANDLE_KIND.SESSION,
+  },
+}
+
+export function capabilitiesOf(channel: ConversationChannel | undefined): ChannelCapabilities {
+  return CHANNEL_CAPABILITIES[channel ?? DEFAULT_CONVERSATION_CHANNEL]
+}
+
+export const CHANNEL_FILTER_ALL = 'all'
+export type ChannelFilter = ConversationChannel | typeof CHANNEL_FILTER_ALL
+
+export 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.
+ */
+export function channelFiltersFor(
+  conversations: readonly { readonly channel?: ConversationChannel | undefined }[],
+): ChannelFilterOption[] {
+  const present = new Set<ConversationChannel>(
+    conversations.map((conversation) => conversation.channel ?? DEFAULT_CONVERSATION_CHANNEL),
+  )
+
+  if (present.size < 2) return []
+
+  // Ordem do catálogo, não de chegada: a barra não pode reordenar sozinha a cada refetch.
+  const ordered = (Object.keys(CHANNEL_CAPABILITIES) as ConversationChannel[]).filter((channel) => present.has(channel))
+
+  return [
+    { value: CHANNEL_FILTER_ALL, label: 'Todos' },
+    ...ordered.map((channel) => ({ value: channel, label: CHANNEL_CAPABILITIES[channel].label })),
+  ]
+}
+
+export 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.
+ */
+export function formatContactHandle(params: FormatContactHandleParams): string {
+  const { handleKind } = capabilitiesOf(params.channel)
+
+  if (handleKind === HANDLE_KIND.PHONE) return formatPhone(params.handle)
+  if (handleKind === HANDLE_KIND.USERNAME) return params.handle.startsWith('@') ? params.handle : `@${params.handle}`
+
+  // Sessão de chat de site é um id opaco: mostrar o hash inteiro não ajuda ninguém.
+  return `Visitante ${params.handle.slice(-6)}`
+}
+
+/** Bandeira só faz sentido quando o identificador é telefone. */
+export function contactFlag(params: FormatContactHandleParams): string {
+  return capabilitiesOf(params.channel).handleKind === HANDLE_KIND.PHONE ? phoneCountryFlag(params.handle) : ''
+}