@adatechnology/conversations-ui 0.1.0-rc.4 → 0.1.0-rc.5

package/src/hooks/useConversationList.ts

@@ -1,16 +1,14 @@
 import { useConversations } from '../providers/ConversationsProvider'
 import { useAsyncResource } from './useAsyncResource'
-import type { ConversationSummary } from '../providers/types'
+import { conversationsOf, totalOf } from '../lib/paginated'
+import type { ConversationSummary, ListConversationsParams } from '../providers/types'
 
-export interface UseConversationListParams {
-  page?: number
-  limit?: number
-  waitingHuman?: boolean
-  search?: string
-}
+export type UseConversationListParams = ListConversationsParams
 
 export 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>
@@ -23,10 +21,18 @@ export function useConversationList(params?: UseConversationListParams): UseConv
   }
   const { api } = context
 
+  // `filters` é objeto novo a cada render do host; serializar evita refetch em laço sem obrigar
+  // o consumidor a memoizar — omissão que só apareceria como loop de rede em produção.
+  const filtersKey = JSON.stringify(params?.filters ?? {})
+
   const { data, loading, error, refetch } = useAsyncResource(
     () => api.fetchConversations(params),
-    [params?.page, params?.limit, params?.waitingHuman, params?.search],
+    [params?.page, params?.limit, params?.waitingHuman, params?.search, filtersKey],
   )
 
-  return { conversations: data ?? [], loading, error, refetch }
+  if (data === undefined) {
+    return { conversations: [], total: 0, loading, error, refetch }
+  }
+
+  return { conversations: conversationsOf(data), total: totalOf(data), loading, error, refetch }
 }

package/src/hooks/useConversationMessages.ts

@@ -10,7 +10,7 @@ export interface UseConversationMessagesResult {
   refetch: () => Promise<void>
   sendMessage: (text: string) => Promise<MessagePayload>
   sendMedia: (data: { base64: string; mimeType: string; filename: string; caption?: string }) => Promise<MessagePayload>
-  sendTemplate: (data: { templateName: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
+  sendTemplate: (data: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => Promise<void>
   markRead: () => Promise<void>
 }
 
@@ -51,7 +51,7 @@ export function useConversationMessages(
   )
 
   const sendTemplate = useCallback(
-    async (templateData: { templateName: string; languageCode?: string; bodyParams?: string[] }) => {
+    async (templateData: { templateName?: string; languageCode?: string; bodyParams?: string[] }) => {
       await api.sendTemplate(conversationId, templateData)
       await refetch()
     },

package/src/index.ts

@@ -74,6 +74,11 @@ export type { BuildTranscriptTextParams } from './conversationTranscript'
 export { useDarkMode, useIsDarkTheme } from './useDarkMode'
 export { useIsNarrow, NARROW_MAX_WIDTH_PX } from './useIsNarrow'
 export { useWaitingNotifications } from './useWaitingNotifications'
+export type {
+  UseWaitingNotificationsLabels,
+  UseWaitingNotificationsParams,
+  UseWaitingNotificationsResult,
+} from './useWaitingNotifications'
 
 export { ConversationsProvider, useConversations } from './providers/ConversationsProvider'
 
@@ -96,10 +101,13 @@ export { useConversationList } from './hooks/useConversationList'
 export { useConversationContext } from './hooks/useConversationContext'
 export { useConversationDocuments } from './hooks/useConversationDocuments'
 export { useConversationRealtime, useGlobalRealtime } from './hooks/useConversationRealtime'
+export { useConversationActions, useInboxActions } from './hooks/useConversationActions'
 
 export { parseWhatsAppFormatting, waToHTML, htmlToWA, waToHTMLInline } from './lib/whatsapp-formatting'
 export { formatPhone, phoneInitials } from './lib/phone'
-export { formatTimestamp, formatFileSize } from './lib/format'
+// `formatDateTime` e `isSameDay` já eram usados pelas bolhas e pelo divisor de data; exportá-los
+// evita que cada host mantenha a própria cópia e acabe com timeline e transcript divergindo.
+export { formatTimestamp, formatFileSize, formatDateTime, isSameDay } from './lib/format'
 
 export type { MessagePayload, ConversationsUIConfig, ConversationsTheme, ConversationsFeatures } from './types'
 export type {
@@ -108,7 +116,13 @@ export type {
   ConversationEventSource,
   ConversationSummary,
   ConversationDocument,
+  ConversationPage,
+  ConversationDocumentPage,
+  ConversationTemplate,
+  ListConversationsParams,
+  ListDocumentsParams,
 } from './providers/types'
+export type { UseConversationActionsResult, UseInboxActionsResult } from './hooks/useConversationActions'
 
 export type { MessageBubbleProps } from './MessageBubble'
 export type { ConversationWallpaperProps } from './Wallpaper'

package/src/lib/cn.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'bun:test'
+
+import { cn } from './cn'
+
+describe('cn', () => {
+  // O contrato de `classNames`/`className` dos componentes depende disto: se o override não vencer,
+  // a API de customização é decorativa. Concatenar falharia justo no caso comum — o Tailwind emite
+  // `px-2` antes de `px-4`, então a base ganharia de quem quer apertar o espaçamento.
+  it('o override do host vence a classe base em conflito', () => {
+    expect(cn('px-4 py-3', 'px-2')).toBe('py-3 px-2')
+  })
+
+  it('mantém o que não conflita', () => {
+    expect(cn('flex items-center gap-3', 'gap-1')).toBe('flex items-center gap-1')
+  })
+
+  it('preserva classes próprias do pacote, que o merge não conhece', () => {
+    expect(cn('cv-row flex', 'bg-red-50')).toBe('cv-row flex bg-red-50')
+  })
+
+  it('ignora ausente, falso e vazio', () => {
+    expect(cn('border-b', undefined, false, '')).toBe('border-b')
+  })
+
+  it('aplica condicional na ordem recebida', () => {
+    const isCompact = false
+    expect(cn('mt-2', isCompact && 'mt-8', 'mt-4')).toBe('mt-4')
+  })
+})

package/src/lib/paginated.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'bun:test'
+import { conversationsOf, documentsOf, totalOf } from './paginated'
+import type { ConversationDocument, ConversationSummary } from '../providers/types'
+
+const conversation = { id: '1', whatsappNumber: '5511900000000' } as ConversationSummary
+const document = { id: 'd1', filename: 'contrato.pdf' } as ConversationDocument
+
+describe('normalização de lista ou página', () => {
+  // As duas formas existem porque o contrato aceita as duas: array puro é o retorno original, e
+  // implementações antigas continuam válidas. Um consumidor que só tratasse uma delas quebraria
+  // em runtime, não no compilador.
+  it('aceita o array puro do contrato original', () => {
+    expect(conversationsOf([conversation])).toEqual([conversation])
+    expect(documentsOf([document])).toEqual([document])
+  })
+
+  it('desembrulha a forma paginada', () => {
+    expect(conversationsOf({ conversations: [conversation], total: 42 })).toEqual([conversation])
+    expect(documentsOf({ documents: [document], total: 7 })).toEqual([document])
+  })
+
+  it('usa o total do servidor quando ele vem, e o tamanho da página quando não vem', () => {
+    // A distinção importa: com array puro não dá para saber se a página é a última, então o
+    // melhor palpite honesto é o que se tem em mãos.
+    expect(totalOf({ conversations: [conversation], total: 42 })).toBe(42)
+    expect(totalOf([conversation])).toBe(1)
+  })
+
+  it('trata página vazia sem confundir com ausência de dados', () => {
+    expect(conversationsOf({ conversations: [], total: 0 })).toEqual([])
+    expect(totalOf({ conversations: [], total: 0 })).toBe(0)
+  })
+})

package/src/lib/paginated.ts

@@ -0,0 +1,26 @@
+import type {
+  ConversationDocument,
+  ConversationDocumentPage,
+  ConversationPage,
+  ConversationSummary,
+} from '../providers/types'
+
+/**
+ * `fetchConversations` e `getDocuments` devolvem o array puro (contrato original) ou uma página
+ * com total. Normalizar num lugar só evita que cada consumidor invente sua própria checagem —
+ * e um consumidor esquecido não falha no compilador, falha em runtime com `.map is not a
+ * function`.
+ */
+export function conversationsOf(result: ConversationSummary[] | ConversationPage): ConversationSummary[] {
+  return Array.isArray(result) ? result : result.conversations
+}
+
+export function documentsOf(result: ConversationDocument[] | ConversationDocumentPage): ConversationDocument[] {
+  return Array.isArray(result) ? result : result.documents
+}
+
+export function totalOf(
+  result: ConversationSummary[] | ConversationPage | ConversationDocument[] | ConversationDocumentPage,
+): number {
+  return Array.isArray(result) ? result.length : result.total
+}

package/src/preview/createMockConversationsApi.ts

@@ -8,7 +8,14 @@
  */
 
 import type { MessagePayload } from '../types'
-import type { ConversationDocument, ConversationsApi, ConversationSummary } from '../providers/types'
+import type {
+  ConversationDocumentPage,
+  ConversationPage,
+  ConversationTemplate,
+  ConversationsApi,
+  ListConversationsParams,
+} from '../providers/types'
+import { PREVIEW_DOCUMENTS } from './previewFixtures'
 import type { PreviewStore } from './previewStore'
 
 // PNG 1x1 transparente: o suficiente para o MediaRenderer ter algo válido para desenhar.
@@ -23,7 +30,24 @@ export type CreateMockConversationsApiParams = {
 
 const DEFAULT_LATENCY_MS = 120
 
-export function createMockConversationsApi(params: CreateMockConversationsApiParams): ConversationsApi {
+const PREVIEW_AGENT_ID = 'preview-agent'
+
+const PREVIEW_TEMPLATES: readonly ConversationTemplate[] = [
+  { name: 'retomada_atendimento', language: 'pt_BR', status: 'APPROVED', category: 'UTILITY' },
+  { name: 'lembrete_documentos', language: 'pt_BR', status: 'APPROVED', category: 'UTILITY' },
+  { name: 'promocao_taxa', language: 'pt_BR', status: 'PENDING', category: 'MARKETING' },
+]
+
+/**
+ * O mock satisfaz `ConversationsApi`, mas com o retorno de `fetchConversations` ESTREITADO para a
+ * forma paginada. Sem isto o contrato — que aceita array ou página — obrigaria todo consumidor do
+ * preview a desempacotar uma união que aqui nunca varia.
+ */
+export type MockConversationsApi = Omit<ConversationsApi, 'fetchConversations'> & {
+  fetchConversations(params?: ListConversationsParams): Promise<ConversationPage>
+}
+
+export function createMockConversationsApi(params: CreateMockConversationsApiParams): MockConversationsApi {
   const latencyMs = params.latencyMs ?? DEFAULT_LATENCY_MS
 
   async function withLatency<TResult>(produce: () => TResult): Promise<TResult> {
@@ -32,7 +56,10 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
   }
 
   return {
-    fetchConversations(fetchParams): Promise<ConversationSummary[]> {
+    // Devolve a forma paginada, não o array puro: é a que o contrato passou a oferecer e a que
+    // permite o preview desenhar controles de página. O total é contado ANTES do corte — depois
+    // dele seria sempre o tamanho da página, e a paginação nunca sairia da primeira.
+    fetchConversations(fetchParams): Promise<ConversationPage> {
       return withLatency(() => {
         const conversations = params.store.listConversations({
           waitingHuman: fetchParams?.waitingHuman,
@@ -41,7 +68,10 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
 
         const limit = fetchParams?.limit ?? conversations.length
         const page = fetchParams?.page ?? 1
-        return conversations.slice((page - 1) * limit, page * limit)
+        return {
+          conversations: conversations.slice((page - 1) * limit, page * limit),
+          total: conversations.length,
+        }
       })
     },
 
@@ -74,7 +104,9 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
       return withLatency(() => {
         params.store.appendMessage({
           conversationId,
-          content: `[template] ${data.templateName}`,
+          // Sem nome, o host está pedindo o template padrão do backend — o mock representa isso
+          // pelo que o atendente veria, não por um nome inventado.
+          content: `[template] ${data.templateName ?? PREVIEW_TEMPLATES[0]?.name ?? 'padrao'}`,
           direction: 'outbound',
           sender: 'agent',
         })
@@ -96,8 +128,54 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
       })
     },
 
-    getDocuments(): Promise<ConversationDocument[]> {
-      return withLatency(() => [])
+    /**
+     * Espelha o backend em busca, filtro de origem, ordenação E paginação. Mock que ignora params
+     * faz o painel parecer quebrado aqui e, pior, esconde o caso em que o backend também os ignora
+     * — foi exatamente assim que o filtro de origem passou a existir só no contrato.
+     */
+    getDocuments(conversationId, documentParams): Promise<ConversationDocumentPage> {
+      return withLatency(() => {
+        let documents = [...(PREVIEW_DOCUMENTS[conversationId] ?? [])]
+
+        const search = documentParams?.search?.trim().toLowerCase()
+        if (search) {
+          documents = documents.filter((document) => document.filename.toLowerCase().includes(search))
+        }
+
+        // 'team' agrupa agent + bot, como o painel apresenta.
+        const source = documentParams?.source
+        if (source === 'team') {
+          documents = documents.filter((document) => document.source === 'agent' || document.source === 'bot')
+        } else if (source) {
+          documents = documents.filter((document) => document.source === source)
+        }
+
+        documents.sort((left, right) =>
+          documentParams?.sortDirection === 'asc'
+            ? left.linkedAt.localeCompare(right.linkedAt)
+            : right.linkedAt.localeCompare(left.linkedAt),
+        )
+
+        // Total contado ANTES do corte — depois seria sempre o tamanho da página, e a paginação
+        // nunca sairia da primeira.
+        const total = documents.length
+        const limit = documentParams?.limit ?? total
+        const page = documentParams?.page ?? 1
+
+        return { documents: documents.slice((page - 1) * limit, page * limit), total }
+      })
+    },
+
+    /**
+     * Zip de mentira: um texto listando o que entraria. Basta para exercitar seleção, botão e o
+     * caminho de download no preview, sem arrastar uma lib de compactação para o pacote.
+     */
+    downloadDocumentsArchive(conversationId, uploadIds): Promise<Blob> {
+      return withLatency(() => {
+        const known = PREVIEW_DOCUMENTS[conversationId] ?? []
+        const names = uploadIds.map((id) => known.find((document) => document.id === id)?.filename ?? id)
+        return new Blob([`preview: ${names.length} arquivo(s)\n${names.join('\n')}`], { type: 'application/zip' })
+      })
     },
 
     getDocumentUrl(): Promise<string> {
@@ -107,5 +185,33 @@ export function createMockConversationsApi(params: CreateMockConversationsApiPar
     getMediaProxyUrl(): Promise<{ mimeType: string; data: string }> {
       return withLatency(() => ({ mimeType: 'image/png', data: PREVIEW_IMAGE_BASE64 }))
     },
+
+    takeover(conversationId): Promise<void> {
+      return withLatency(() =>
+        params.store.setMode({ conversationId, mode: 'human', assignedUserId: PREVIEW_AGENT_ID }),
+      )
+    },
+
+    release(conversationId): Promise<void> {
+      return withLatency(() => params.store.setMode({ conversationId, mode: 'bot' }))
+    },
+
+    // Encerrar devolve ao bot como o release, e é de propósito: a diferença entre os dois é a
+    // despedida, que o host manda antes de chamar aqui. O mock não a inventa.
+    finalize(conversationId): Promise<void> {
+      return withLatency(() => params.store.setMode({ conversationId, mode: 'bot' }))
+    },
+
+    markAllRead(): Promise<void> {
+      return withLatency(() => {
+        for (const conversation of params.store.listConversations()) {
+          params.store.markRead(conversation.id)
+        }
+      })
+    },
+
+    listTemplates(): Promise<ConversationTemplate[]> {
+      return withLatency(() => [...PREVIEW_TEMPLATES])
+    },
   }
 }

package/src/preview/index.ts

@@ -23,7 +23,7 @@ export type { CreateMockConversationsApiParams } from './createMockConversations
 export { createMockSSEProvider } from './createMockSSEProvider'
 export type { CreateMockSSEProviderParams } from './createMockSSEProvider'
 
-export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES } from './previewFixtures'
+export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES, PREVIEW_DOCUMENTS } from './previewFixtures'
 
 export { ConversationPreview } from './ConversationPreview'
 export type { ConversationPreviewProps } from './ConversationPreview'

package/src/preview/preview.test.ts

@@ -145,8 +145,10 @@ describe('createMockConversationsApi', () => {
     const firstPage = await api.fetchConversations({ page: 1, limit: 2 })
     const waiting = await api.fetchConversations({ waitingHuman: true })
 
-    expect(firstPage).toHaveLength(2)
-    expect(waiting.every((conversation) => conversation.waitingHuman)).toBe(true)
+    expect(firstPage.conversations).toHaveLength(2)
+    // O total conta o conjunto filtrado inteiro, não a fatia — é o que a paginação da UI lê.
+    expect(firstPage.total).toBeGreaterThan(2)
+    expect(waiting.conversations.every((conversation) => conversation.waitingHuman)).toBe(true)
   })
 
   it('markRead zera as não-lidas vistas pela lista', async () => {
@@ -156,7 +158,7 @@ describe('createMockConversationsApi', () => {
     await api.markRead(BOT_CONVERSATION_ID)
     const conversations = await api.fetchConversations()
 
-    expect(conversations.find((item) => item.id === BOT_CONVERSATION_ID)?.unread).toBe(0)
+    expect(conversations.conversations.find((item) => item.id === BOT_CONVERSATION_ID)?.unread).toBe(0)
   })
 })
 

package/src/preview/previewFixtures.ts

@@ -5,7 +5,7 @@
  */
 
 import type { MessagePayload } from '../types'
-import type { ConversationSummary } from '../providers/types'
+import type { ConversationDocument, ConversationSummary } from '../providers/types'
 
 // Datas fixas: fixture com data relativa ao relógio faz o mesmo cenário renderizar diferente a
 // cada execução, e separadores de dia deixam de ser verificáveis.
@@ -71,6 +71,24 @@ export const PREVIEW_CONVERSATIONS: readonly ConversationSummary[] = [
     unread: 1,
     currentState: 'list_import',
   },
+  {
+    // Cobre TODO tipo que o composer aceita (DEFAULT_ACCEPTED_FILE_TYPES: image/*, video/*,
+    // audio/*, .pdf, .doc, .docx, .xls, .xlsx, .zip) mais sticker. Existe para que cada ramo do
+    // MediaRenderer e cada ícone/cor do FileIcon apareçam em algum lugar — ramo sem fixture é ramo
+    // que ninguém olha até quebrar em produção.
+    id: '5511944443333',
+    whatsappNumber: '5511944443333',
+    clientName: 'Rita Documentos',
+    lastContent: 'segue a planilha do pedido',
+    lastDirection: 'inbound',
+    lastAt: at('15:10:00'),
+    lastInboundAt: at('15:10:00'),
+    mode: 'human',
+    assignedUserId: 'agent-1',
+    waitingHuman: false,
+    unread: 3,
+    currentState: 'human_handling',
+  },
 ]
 
 export const PREVIEW_MESSAGES: Readonly<Record<string, readonly MessagePayload[]>> = {
@@ -150,4 +168,141 @@ export const PREVIEW_MESSAGES: Readonly<Record<string, readonly MessagePayload[]
       timestamp: at('13:31:00'),
     },
   ],
+  // Um tipo por mensagem, na ordem em que o MediaRenderer os trata.
+  '5511944443333': [
+    {
+      id: 'fixture-doc-image',
+      type: 'image',
+      mediaId: 'preview-image-1',
+      mimeType: 'image/png',
+      caption: 'foto da prateleira',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:00:00'),
+    },
+    {
+      id: 'fixture-doc-video',
+      type: 'video',
+      mediaId: 'preview-video-1',
+      mimeType: 'video/mp4',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:01:00'),
+    },
+    {
+      id: 'fixture-doc-audio',
+      type: 'audio',
+      mediaId: 'preview-audio-2',
+      mimeType: 'audio/ogg',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:02:00'),
+    },
+    {
+      id: 'fixture-doc-sticker',
+      type: 'sticker',
+      mediaId: 'preview-sticker-1',
+      mimeType: 'image/webp',
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:03:00'),
+    },
+    // Os cinco ramos do FileIcon: pdf, doc, xls, zip e o genérico do fallback.
+    {
+      id: 'fixture-doc-pdf',
+      type: 'document',
+      uploadId: 'preview/documentos/nota-fiscal.pdf',
+      filename: 'nota-fiscal.pdf',
+      mimeType: 'application/pdf',
+      sizeBytes: 184_320,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:04:00'),
+    },
+    {
+      id: 'fixture-doc-docx',
+      type: 'document',
+      uploadId: 'preview/documentos/contrato.docx',
+      filename: 'contrato.docx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      sizeBytes: 42_112,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:05:00'),
+    },
+    {
+      id: 'fixture-doc-doc',
+      type: 'document',
+      uploadId: 'preview/documentos/procuracao.doc',
+      filename: 'procuracao.doc',
+      mimeType: 'application/msword',
+      sizeBytes: 31_744,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:06:00'),
+    },
+    {
+      id: 'fixture-doc-xlsx',
+      type: 'document',
+      uploadId: 'preview/documentos/pedido.xlsx',
+      filename: 'pedido.xlsx',
+      mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      sizeBytes: 15_872,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:07:00'),
+    },
+    {
+      id: 'fixture-doc-xls',
+      type: 'document',
+      uploadId: 'preview/documentos/tabela-antiga.xls',
+      filename: 'tabela-antiga.xls',
+      mimeType: 'application/vnd.ms-excel',
+      sizeBytes: 9_216,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:08:00'),
+    },
+    {
+      id: 'fixture-doc-zip',
+      type: 'document',
+      uploadId: 'preview/documentos/comprovantes.zip',
+      filename: 'comprovantes.zip',
+      mimeType: 'application/zip',
+      sizeBytes: 2_355_200,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:09:00'),
+    },
+    {
+      // Extensão fora do EXTENSION_STYLE: garante que o ícone genérico cinza também apareça.
+      id: 'fixture-doc-generic',
+      type: 'document',
+      uploadId: 'preview/documentos/lista-compras.txt',
+      filename: 'lista-compras.txt',
+      mimeType: 'text/plain',
+      sizeBytes: 1_024,
+      direction: 'inbound',
+      sender: 'customer',
+      timestamp: at('15:10:00'),
+    },
+  ],
+}
+
+/**
+ * A biblioteca de arquivos da conversa, como o backend a devolveria. Deriva das mensagens de
+ * documento acima em vez de repetir os dados: fixture duplicada divergiria na primeira edição, e o
+ * painel passaria a mostrar arquivo que a thread não tem.
+ */
+export const PREVIEW_DOCUMENTS: Readonly<Record<string, readonly ConversationDocument[]>> = {
+  '5511944443333': (PREVIEW_MESSAGES['5511944443333'] ?? [])
+    .filter((message) => message.type === 'document')
+    .map((message) => ({
+      id: message.uploadId ?? message.id,
+      filename: message.filename ?? message.id,
+      mimeType: message.mimeType ?? 'application/octet-stream',
+      sizeBytes: message.sizeBytes ?? 0,
+      source: message.sender,
+      linkedAt: message.timestamp,
+    })),
 }