@adatechnology/conversations-ui 0.1.0 → 0.2.0

package/src/quickReplies/quickReplyAttachments.test.ts

@@ -0,0 +1,396 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  applySendResults,
+  attachmentKey,
+  canAddAttachments,
+  excludeRetryingItems,
+  orderOutgoingItems,
+  queuedAttachmentsFromQuickReply,
+  resolveIdempotencyKey,
+  resolveMaxAttachmentSizeBytes,
+  resolveRetryOutcome,
+  retryStoredAttachments,
+  sendQueuedMessage,
+} from './quickReplyAttachments'
+import type { QueuedAttachment } from './quickReply.types'
+
+const LOCAL: QueuedAttachment = {
+  kind: 'local',
+  localId: 'local-1',
+  file: new File(['x'], 'local.pdf', { type: 'application/pdf' }),
+}
+const FIRST: QueuedAttachment = {
+  kind: 'stored',
+  uploadId: 'a',
+  filename: 'a.pdf',
+  mimeType: 'application/pdf',
+  sizeBytes: 1,
+}
+const SECOND: QueuedAttachment = {
+  kind: 'stored',
+  uploadId: 'b',
+  filename: 'b.png',
+  mimeType: 'image/png',
+  sizeBytes: 1,
+}
+
+describe('orderOutgoingItems', () => {
+  it('põe guardados na ordem do cadastro antes dos locais', () => {
+    const items = orderOutgoingItems('oi', [LOCAL, FIRST, SECOND])
+    expect(items.text).toBe('oi')
+    expect(items.attachments).toEqual([FIRST, SECOND, LOCAL])
+  })
+})
+
+describe('applySendResults', () => {
+  it('mantém só o que não foi enviado', () => {
+    const queue = applySendResults(
+      [FIRST, SECOND, LOCAL],
+      [
+        { uploadId: 'a', status: 'sent' },
+        { uploadId: 'b', status: 'failed', errorCode: 'X' },
+      ],
+    )
+    expect(queue).toEqual([SECOND, LOCAL])
+  })
+
+  it('mantém o pulado', () => {
+    expect(applySendResults([FIRST], [{ uploadId: 'a', status: 'skipped' }])).toEqual([FIRST])
+  })
+})
+
+describe('onAttachmentStatus: pulado distinto de falhou', () => {
+  it('sendQueuedMessage reporta skipped, não failed, para um item pulado no lote', async () => {
+    const statuses: { key: string; status: string }[] = []
+    await sendQueuedMessage({
+      text: '',
+      queue: [FIRST, SECOND],
+      idempotencyKey: 'k1',
+      sendText: async () => true,
+      sendStoredAttachments: async () => ({
+        results: [
+          { uploadId: 'a', status: 'failed', errorCode: 'UPLOAD_FAILED' },
+          { uploadId: 'b', status: 'skipped' },
+        ],
+      }),
+      onAttachmentStatus: (key, status) => statuses.push({ key, status }),
+    })
+    expect(statuses).toContainEqual({ key: 'a', status: 'failed' })
+    expect(statuses).toContainEqual({ key: 'b', status: 'skipped' })
+  })
+
+  it('retryStoredAttachments reporta skipped, não failed, para o item pulado', async () => {
+    const statuses: { key: string; status: string }[] = []
+    await retryStoredAttachments({
+      queue: [FIRST],
+      uploadIds: ['a'],
+      idempotencyKey: 'k',
+      sendStoredAttachments: async () => ({ results: [{ uploadId: 'a', status: 'skipped' }] }),
+      onAttachmentStatus: (key, status) => statuses.push({ key, status }),
+    })
+    expect(statuses).toEqual([
+      { key: 'a', status: 'sending' },
+      { key: 'a', status: 'skipped' },
+    ])
+  })
+})
+
+describe('canAddAttachments', () => {
+  it('aceita até o teto e recusa acima', () => {
+    expect(canAddAttachments(8, 2)).toBe(true)
+    expect(canAddAttachments(9, 2)).toBe(false)
+  })
+})
+
+describe('resolveMaxAttachmentSizeBytes', () => {
+  it('usa o teto por tipo', () => {
+    expect(resolveMaxAttachmentSizeBytes('image/png')).toBe(5 * 1024 * 1024)
+    expect(resolveMaxAttachmentSizeBytes('audio/ogg')).toBe(16 * 1024 * 1024)
+    expect(resolveMaxAttachmentSizeBytes('video/mp4')).toBe(16 * 1024 * 1024)
+    expect(resolveMaxAttachmentSizeBytes('application/pdf')).toBe(100 * 1024 * 1024)
+  })
+
+  it('aceita limites do host', () => {
+    expect(resolveMaxAttachmentSizeBytes('image/png', { document: 1, image: 2, audio: 3, video: 4 })).toBe(2)
+  })
+})
+
+describe('sendQueuedMessage', () => {
+  it('manda texto, depois guardados, depois locais, e esvazia a fila quando tudo sai', async () => {
+    const order: string[] = []
+    const result = await sendQueuedMessage({
+      text: 'oi',
+      queue: [LOCAL, FIRST, SECOND],
+      idempotencyKey: 'k1',
+      sendText: async (text) => {
+        order.push(`text:${text}`)
+        return true
+      },
+      sendStoredAttachments: async ({ uploadIds, idempotencyKey }) => {
+        order.push(`stored:${uploadIds.join(',')}:${idempotencyKey}`)
+        return { results: uploadIds.map((uploadId) => ({ uploadId, status: 'sent' as const })) }
+      },
+      sendLocalAttachments: async (files) => {
+        order.push(`local:${files.map((file) => file.name).join(',')}`)
+      },
+    })
+    expect(order).toEqual(['text:oi', 'stored:a,b:k1', 'local:local.pdf'])
+    expect(result.textSent).toBe(true)
+    expect(result.remainingQueue).toEqual([])
+    // sentAttachmentKeys deixa o chamador remover por chave de um estado corrente em vez de
+    // sobrescrever com remainingQueue (calculado sobre a fila capturada antes do await) — o item
+    // adicionado durante o envio (MEDIUM 1) não pode se perder nessa troca.
+    expect([...result.sentAttachmentKeys].sort()).toEqual(['a', 'b', 'local-1'])
+  })
+
+  it('não manda anexo nenhum quando o texto falha (QR-43)', async () => {
+    let storedCalled = false
+    let localCalled = false
+    const result = await sendQueuedMessage({
+      text: 'oi',
+      queue: [FIRST, LOCAL],
+      idempotencyKey: 'k1',
+      sendText: async () => false,
+      sendStoredAttachments: async () => {
+        storedCalled = true
+        return { results: [] }
+      },
+      sendLocalAttachments: async () => {
+        localCalled = true
+      },
+    })
+    expect(storedCalled).toBe(false)
+    expect(localCalled).toBe(false)
+    expect(result.textSent).toBe(false)
+    expect(result.remainingQueue).toEqual([FIRST, LOCAL])
+  })
+
+  it('mantém na fila só o que falhou ou não tem porta (QR-37)', async () => {
+    const result = await sendQueuedMessage({
+      text: '',
+      queue: [FIRST, SECOND, LOCAL],
+      idempotencyKey: 'k1',
+      sendText: async () => true,
+      sendStoredAttachments: async () => ({
+        results: [
+          { uploadId: 'a', status: 'sent' },
+          { uploadId: 'b', status: 'failed', errorCode: 'X' },
+        ],
+      }),
+    })
+    // sem sendLocalAttachments, o item local não sai e continua na fila
+    expect(result.remainingQueue).toEqual([SECOND, LOCAL])
+  })
+
+  it('marca todo guardado como falha quando o lote lança (H3)', async () => {
+    const result = await sendQueuedMessage({
+      text: '',
+      queue: [FIRST, SECOND],
+      idempotencyKey: 'k1',
+      sendText: async () => true,
+      sendStoredAttachments: async () => {
+        throw new Error('rede caiu')
+      },
+    })
+    expect(result.textSent).toBe(true)
+    expect(result.remainingQueue).toEqual([FIRST, SECOND])
+  })
+
+  it('trata guardado ausente do resultado do lote como falha (M5)', async () => {
+    const result = await sendQueuedMessage({
+      text: '',
+      queue: [FIRST, SECOND],
+      idempotencyKey: 'k1',
+      sendText: async () => true,
+      sendStoredAttachments: async () => ({ results: [{ uploadId: 'a', status: 'sent' as const }] }),
+    })
+    expect(result.remainingQueue).toEqual([SECOND])
+  })
+
+  it('reusa a mesma chave de idempotência ao reenviar o que sobrou', async () => {
+    const keys: string[] = []
+    await sendQueuedMessage({
+      text: '',
+      queue: [FIRST],
+      idempotencyKey: 'retry-key',
+      sendText: async () => true,
+      sendStoredAttachments: async ({ idempotencyKey }) => {
+        keys.push(idempotencyKey)
+        return { results: [{ uploadId: 'a', status: 'failed' as const }] }
+      },
+    })
+    await sendQueuedMessage({
+      text: '',
+      queue: [FIRST],
+      idempotencyKey: 'retry-key',
+      sendText: async () => true,
+      sendStoredAttachments: async ({ idempotencyKey }) => {
+        keys.push(idempotencyKey)
+        return { results: [{ uploadId: 'a', status: 'sent' as const }] }
+      },
+    })
+    expect(keys).toEqual(['retry-key', 'retry-key'])
+  })
+})
+
+describe('resolveIdempotencyKey', () => {
+  it('gera chave nova sem estado anterior', () => {
+    const state = resolveIdempotencyKey(undefined, ['a', 'b'], () => 'new-key')
+    expect(state).toEqual({ key: 'new-key', uploadIds: ['a', 'b'] })
+  })
+
+  it('reusa a chave quando o conjunto ordenado de uploadIds não muda', () => {
+    const previous = { key: 'k1', uploadIds: ['a', 'b'] }
+    const state = resolveIdempotencyKey(previous, ['a', 'b'], () => 'should-not-be-used')
+    expect(state).toBe(previous)
+  })
+
+  it('gera chave nova quando um uploadId entra ou sai', () => {
+    const previous = { key: 'k1', uploadIds: ['a', 'b'] }
+    expect(resolveIdempotencyKey(previous, ['a'], () => 'k2')).toEqual({ key: 'k2', uploadIds: ['a'] })
+    expect(resolveIdempotencyKey(previous, ['a', 'b', 'c'], () => 'k3')).toEqual({
+      key: 'k3',
+      uploadIds: ['a', 'b', 'c'],
+    })
+  })
+
+  it('gera chave nova quando a ordem muda, mesmo com o mesmo conjunto', () => {
+    const previous = { key: 'k1', uploadIds: ['a', 'b'] }
+    expect(resolveIdempotencyKey(previous, ['b', 'a'], () => 'k2')).toEqual({ key: 'k2', uploadIds: ['b', 'a'] })
+  })
+})
+
+describe('retryStoredAttachments', () => {
+  it('reenvia só o uploadId pedido, sem tocar no resto da fila', async () => {
+    const calls: { uploadIds: readonly string[]; idempotencyKey: string }[] = []
+    const result = await retryStoredAttachments({
+      queue: [FIRST, SECOND, LOCAL],
+      uploadIds: ['b'],
+      idempotencyKey: 'retry-b',
+      sendStoredAttachments: async ({ uploadIds, idempotencyKey }) => {
+        calls.push({ uploadIds, idempotencyKey })
+        return { results: [{ uploadId: 'b', status: 'sent' as const }] }
+      },
+    })
+    expect(calls).toEqual([{ uploadIds: ['b'], idempotencyKey: 'retry-b' }])
+    expect(result.remainingQueue).toEqual([FIRST, LOCAL])
+    expect(result.sentAttachmentKeys).toEqual(['b'])
+  })
+
+  it('sentAttachmentKeys vem vazio quando o reenvio falha (nada para remover por chave)', async () => {
+    const result = await retryStoredAttachments({
+      queue: [FIRST],
+      uploadIds: ['a'],
+      idempotencyKey: 'k',
+      sendStoredAttachments: async () => ({ results: [{ uploadId: 'a', status: 'failed' as const }] }),
+    })
+    expect(result.sentAttachmentKeys).toEqual([])
+  })
+
+  it('sem item correspondente na fila, não chama a porta e devolve a fila intacta', async () => {
+    let called = false
+    const result = await retryStoredAttachments({
+      queue: [FIRST],
+      uploadIds: ['nao-existe'],
+      idempotencyKey: 'k',
+      sendStoredAttachments: async () => {
+        called = true
+        return { results: [] }
+      },
+    })
+    expect(called).toBe(false)
+    expect(result.remainingQueue).toEqual([FIRST])
+  })
+
+  it('mantém o item na fila quando o reenvio falha', async () => {
+    const result = await retryStoredAttachments({
+      queue: [FIRST],
+      uploadIds: ['a'],
+      idempotencyKey: 'k',
+      sendStoredAttachments: async () => {
+        throw new Error('rede caiu')
+      },
+    })
+    expect(result.remainingQueue).toEqual([FIRST])
+  })
+})
+
+describe('queuedAttachmentsFromQuickReply', () => {
+  const quickReplyWithAttachments = {
+    attachments: [
+      { uploadId: 'a', filename: 'a.pdf', mimeType: 'application/pdf', sizeBytes: 1 },
+      { uploadId: 'b', filename: 'b.png', mimeType: 'image/png', sizeBytes: 2 },
+    ],
+  }
+
+  it('empurra os anexos como itens guardados quando o host sabe mandar (QR-32)', () => {
+    expect(queuedAttachmentsFromQuickReply(quickReplyWithAttachments, true)).toEqual([
+      { kind: 'stored', uploadId: 'a', filename: 'a.pdf', mimeType: 'application/pdf', sizeBytes: 1 },
+      { kind: 'stored', uploadId: 'b', filename: 'b.png', mimeType: 'image/png', sizeBytes: 2 },
+    ])
+  })
+
+  it('não empurra nada sem a porta (QR-33)', () => {
+    expect(queuedAttachmentsFromQuickReply(quickReplyWithAttachments, false)).toEqual([])
+  })
+
+  it('não empurra nada quando a mensagem não tem anexo', () => {
+    expect(queuedAttachmentsFromQuickReply({ attachments: [] }, true)).toEqual([])
+    expect(queuedAttachmentsFromQuickReply({ attachments: undefined }, true)).toEqual([])
+  })
+})
+
+describe('attachmentKey', () => {
+  it('usa o uploadId para guardado e o localId para local', () => {
+    expect(attachmentKey(FIRST)).toBe('a')
+    expect(attachmentKey(LOCAL)).toBe('local-1')
+  })
+
+  it('distingue duas cópias do mesmo arquivo local pelo localId gerado, não pela identidade do File', () => {
+    const file = new File(['x'], 'same.pdf', { type: 'application/pdf' })
+    const first: QueuedAttachment = { kind: 'local', localId: 'local-a', file }
+    const second: QueuedAttachment = { kind: 'local', localId: 'local-b', file }
+    expect(attachmentKey(first)).not.toBe(attachmentKey(second))
+  })
+})
+
+describe('resolveRetryOutcome', () => {
+  it('conversa diferente da do retry devolve undefined, deixando a fila corrente intocada', () => {
+    const outcome = resolveRetryOutcome({
+      conversationIdAtRetry: 'conversation-1',
+      currentConversationId: 'conversation-2',
+      sentAttachmentKeys: ['a'],
+      queue: [],
+    })
+    expect(outcome).toBeUndefined()
+  })
+
+  it('mesma conversa: tira só as chaves enviadas e mantém item adicionado durante o retry', () => {
+    const addedMidRetry: QueuedAttachment = {
+      kind: 'stored',
+      uploadId: 'c',
+      filename: 'c.pdf',
+      mimeType: 'application/pdf',
+      sizeBytes: 1,
+    }
+    const outcome = resolveRetryOutcome({
+      conversationIdAtRetry: 'conversation-1',
+      currentConversationId: 'conversation-1',
+      sentAttachmentKeys: ['a'],
+      queue: [FIRST, SECOND, addedMidRetry],
+    })
+    expect(outcome).toEqual([SECOND, addedMidRetry])
+  })
+})
+
+describe('excludeRetryingItems', () => {
+  it('sem chaves em retry devolve a fila como veio', () => {
+    expect(excludeRetryingItems([FIRST, LOCAL], new Set())).toEqual([FIRST, LOCAL])
+  })
+
+  it('tira só os itens cuja chave está em retry avulso', () => {
+    const result = excludeRetryingItems([FIRST, SECOND, LOCAL], new Set(['b']))
+    expect(result).toEqual([FIRST, LOCAL])
+  })
+})

package/src/quickReplies/quickReplyAttachments.ts

@@ -0,0 +1,289 @@
+import { QUICK_REPLY_ATTACHMENT_LIMIT } from './quickReply.types'
+import type { QueuedAttachment, QuickReply, StoredAttachmentSendResult } from './quickReply.types'
+
+/**
+ * Anexos de uma mensagem pronta escolhida no picker, prontos para entrar na fila como `stored`
+ * (QR-32). Vazio sem `hasAttachmentsCapability` — sem `sendStoredAttachments` no host, empurrar o
+ * item só encalharia na fila sem jeito de sair; a linha do picker já avisou disso antes do clique.
+ */
+export function queuedAttachmentsFromQuickReply(
+  quickReply: Pick<QuickReply, 'attachments'>,
+  hasAttachmentsCapability: boolean,
+): readonly QueuedAttachment[] {
+  if (!hasAttachmentsCapability || !quickReply.attachments?.length) return []
+  return quickReply.attachments.map(
+    (attachment): QueuedAttachment => ({
+      kind: 'stored',
+      uploadId: attachment.uploadId,
+      filename: attachment.filename,
+      mimeType: attachment.mimeType,
+      sizeBytes: attachment.sizeBytes,
+    }),
+  )
+}
+
+/**
+ * Chave estável do item na fila — `uploadId` para guardado, `localId` gerado para local. A
+ * identidade do `File` (nome+tamanho+data) não bastava: duas cópias do mesmo arquivo colidiam na
+ * mesma chave e removê-la de uma removia as duas.
+ */
+export function attachmentKey(item: QueuedAttachment): string {
+  return item.kind === 'stored' ? item.uploadId : item.localId
+}
+
+export type AttachmentSendStatus = 'waiting' | 'sending' | 'sent' | 'failed' | 'skipped'
+
+/** Espelha os tetos da API; o host sobrescreve quando o backend dele aceita outro tamanho. */
+export const DEFAULT_MAX_ATTACHMENT_SIZE_BYTES = {
+  document: 100 * 1024 * 1024,
+  image: 5 * 1024 * 1024,
+  audio: 16 * 1024 * 1024,
+  video: 16 * 1024 * 1024,
+} as const
+
+export type MaxAttachmentSizeBytes = {
+  readonly document: number
+  readonly image: number
+  readonly audio: number
+  readonly video: number
+}
+
+export type OutgoingItems = {
+  readonly text: string
+  readonly attachments: readonly QueuedAttachment[]
+}
+
+/**
+ * Texto primeiro, depois os guardados na ordem do cadastro, por último os locais: o cliente lê a
+ * explicação antes do arquivo, e o que o atendente anexou na hora é complemento do roteiro.
+ */
+export function orderOutgoingItems(text: string, queue: readonly QueuedAttachment[]): OutgoingItems {
+  const stored = queue.filter((item) => item.kind === 'stored')
+  const local = queue.filter((item) => item.kind === 'local')
+  return { text, attachments: [...stored, ...local] }
+}
+
+/** Tira da fila só o que foi enviado; falha e pulado ficam para o atendente tentar de novo. */
+export function applySendResults(
+  queue: readonly QueuedAttachment[],
+  results: readonly StoredAttachmentSendResult[],
+): readonly QueuedAttachment[] {
+  const sentUploadIds = new Set(results.filter((result) => result.status === 'sent').map((result) => result.uploadId))
+  return queue.filter((item) => item.kind === 'local' || !sentUploadIds.has(item.uploadId))
+}
+
+export function canAddAttachments(current: number, adding: number): boolean {
+  return current + adding <= QUICK_REPLY_ATTACHMENT_LIMIT
+}
+
+export function resolveMaxAttachmentSizeBytes(
+  mimeType: string,
+  limits: MaxAttachmentSizeBytes = DEFAULT_MAX_ATTACHMENT_SIZE_BYTES,
+): number {
+  if (mimeType.startsWith('image/')) return limits.image
+  if (mimeType.startsWith('audio/')) return limits.audio
+  if (mimeType.startsWith('video/')) return limits.video
+  return limits.document
+}
+
+export type IdempotencyKeyState = {
+  readonly key: string
+  /** Conjunto ORDENADO de `uploadId` desta tentativa — a chave só sobrevive enquanto for igual. */
+  readonly uploadIds: readonly string[]
+}
+
+/**
+ * Decide se a chave de idempotência de `previous` ainda serve (M3): serve quando o conjunto
+ * ORDENADO de `uploadIds` não mudou desde a tentativa anterior. Mudou — um anexo saiu, entrou, ou
+ * trocou de posição — vira uma tentativa diferente perante o backend, e precisa de chave nova; a
+ * mesma chave reenviaria o lote antigo como se fosse o novo (ou o servidor recusaria por conflito).
+ */
+export function resolveIdempotencyKey(
+  previous: IdempotencyKeyState | undefined,
+  uploadIds: readonly string[],
+  generateKey: () => string = () => crypto.randomUUID(),
+): IdempotencyKeyState {
+  if (previous && sameUploadIds(previous.uploadIds, uploadIds)) return previous
+  return { key: generateKey(), uploadIds }
+}
+
+function sameUploadIds(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false
+  return a.every((id, index) => id === b[index])
+}
+
+export type SendQueuedMessageParams = {
+  readonly text: string
+  readonly queue: readonly QueuedAttachment[]
+  /** Uma por clique, reusada em cada tentativa de reenvio do que sobrou (QR-38). */
+  readonly idempotencyKey: string
+  /** Devolve se o texto saiu — falso interrompe o pipeline antes de qualquer anexo (QR-43). */
+  readonly sendText: (text: string) => Promise<boolean>
+  /** Ausente, itens `stored` continuam na fila — o produto não sabe mandar por referência. */
+  readonly sendStoredAttachments?: (params: {
+    uploadIds: readonly string[]
+    idempotencyKey: string
+  }) => Promise<{ results: readonly StoredAttachmentSendResult[] }>
+  /** Ausente, itens `local` continuam na fila — o mesmo comportamento de hoje sem a porta. */
+  readonly sendLocalAttachments?: (files: readonly File[]) => Promise<void>
+  readonly onAttachmentStatus?: (key: string, status: AttachmentSendStatus) => void
+}
+
+export type SendQueuedMessageResult = {
+  readonly textSent: boolean
+  /** O que não foi enviado — falha, pulado ou sem porta — para o atendente tentar de novo. */
+  readonly remainingQueue: readonly QueuedAttachment[]
+  /** Chaves (`attachmentKey`) dos itens que saíram — para o chamador remover por chave de um estado
+   * corrente, em vez de sobrescrever a fila com este `remainingQueue` (calculado sobre uma fila
+   * capturada antes do `await`, que já pode estar desatualizada). */
+  readonly sentAttachmentKeys: readonly string[]
+}
+
+type SendStoredAttachmentsPort = NonNullable<SendQueuedMessageParams['sendStoredAttachments']>
+type StoredQueuedAttachment = Extract<QueuedAttachment, { kind: 'stored' }>
+
+/** Traduz o status do resultado do servidor para o status visual do item na fila. */
+function attachmentSendStatusOf(status: StoredAttachmentSendResult['status']): AttachmentSendStatus {
+  if (status === 'sent') return 'sent'
+  if (status === 'skipped') return 'skipped'
+  return 'failed'
+}
+
+/**
+ * Manda um lote de itens `stored` e traduz a resposta em status por item — usado tanto pelo envio
+ * normal quanto pelo retry avulso (M5): guardado sem resultado no lote é tratado como falha, e o
+ * lote inteiro falhando (rede, 500) marca cada item como falha em vez de sumir da tela sem explicação.
+ * `skipped` (o servidor parou antes de tentar este arquivo, por causa de uma falha anterior no
+ * mesmo lote) fica distinto de `failed` — o item não falhou, só não chegou a ser tentado.
+ */
+async function sendStoredBatch(
+  stored: readonly StoredQueuedAttachment[],
+  idempotencyKey: string,
+  sendStoredAttachments: SendStoredAttachmentsPort,
+  onAttachmentStatus?: (key: string, status: AttachmentSendStatus) => void,
+): Promise<readonly StoredAttachmentSendResult[]> {
+  for (const item of stored) onAttachmentStatus?.(attachmentKey(item), 'sending')
+  try {
+    const response = await sendStoredAttachments({ uploadIds: stored.map((item) => item.uploadId), idempotencyKey })
+    let results = response.results
+    const resultedUploadIds = new Set(results.map((result) => result.uploadId))
+    for (const item of stored) {
+      if (!resultedUploadIds.has(item.uploadId)) results = [...results, { uploadId: item.uploadId, status: 'failed' }]
+    }
+    for (const result of results) {
+      onAttachmentStatus?.(result.uploadId, attachmentSendStatusOf(result.status))
+    }
+    return results
+  } catch {
+    for (const item of stored) onAttachmentStatus?.(attachmentKey(item), 'failed')
+    return stored.map((item) => ({ uploadId: item.uploadId, status: 'failed' as const }))
+  }
+}
+
+export type RetryStoredAttachmentsParams = {
+  readonly queue: readonly QueuedAttachment[]
+  /** Só este subconjunto é reenviado — o resto da fila (texto já mandado) fica intocado. */
+  readonly uploadIds: readonly string[]
+  readonly idempotencyKey: string
+  readonly sendStoredAttachments: SendStoredAttachmentsPort
+  readonly onAttachmentStatus?: (key: string, status: AttachmentSendStatus) => void
+}
+
+export type RetryStoredAttachmentsResult = {
+  readonly remainingQueue: readonly QueuedAttachment[]
+  /** Chaves (`uploadId`) dos itens que saíram — ver `SendQueuedMessageResult.sentAttachmentKeys`. */
+  readonly sentAttachmentKeys: readonly string[]
+}
+
+/**
+ * Reenvia só os `stored` de `uploadIds` — nunca o texto do rascunho (M3): o botão "Tentar de novo"
+ * de um item é sobre aquele anexo, não sobre a mensagem inteira que já foi lida ou já saiu.
+ */
+export async function retryStoredAttachments(
+  params: RetryStoredAttachmentsParams,
+): Promise<RetryStoredAttachmentsResult> {
+  const { queue, uploadIds, idempotencyKey, sendStoredAttachments, onAttachmentStatus } = params
+  const targetIds = new Set(uploadIds)
+  const targets = queue.filter(
+    (item): item is StoredQueuedAttachment => item.kind === 'stored' && targetIds.has(item.uploadId),
+  )
+  if (targets.length === 0) return { remainingQueue: queue, sentAttachmentKeys: [] }
+  const results = await sendStoredBatch(targets, idempotencyKey, sendStoredAttachments, onAttachmentStatus)
+  const sentAttachmentKeys = results.filter((result) => result.status === 'sent').map((result) => result.uploadId)
+  return { remainingQueue: applySendResults(queue, results), sentAttachmentKeys }
+}
+
+export type ResolveRetryOutcomeParams = {
+  readonly conversationIdAtRetry: string
+  readonly currentConversationId: string
+  readonly sentAttachmentKeys: readonly string[]
+  readonly queue: readonly QueuedAttachment[]
+}
+
+/**
+ * Decide o que gravar na fila depois de um retry avulso resolver (H2/M5): `undefined` quando a
+ * conversa trocou no meio do retry — o resultado é de outra thread e o chamador deve ignorá-lo,
+ * mantendo a fila corrente intocada. Na mesma conversa, tira só as chaves enviadas — nunca
+ * sobrescreve com uma fila capturada antes do `await`, que perderia item adicionado durante o envio.
+ */
+export function resolveRetryOutcome(params: ResolveRetryOutcomeParams): readonly QueuedAttachment[] | undefined {
+  const { conversationIdAtRetry, currentConversationId, sentAttachmentKeys, queue } = params
+  if (conversationIdAtRetry !== currentConversationId) return undefined
+  const sentKeys = new Set(sentAttachmentKeys)
+  return queue.filter((item) => !sentKeys.has(attachmentKey(item)))
+}
+
+/** Tira da fila de um envio completo os itens com retry avulso em voo (M-retry-race): a chave de
+ * idempotência do retry é outra, e mandar o mesmo item nos dois pipelines ao mesmo tempo deixa o
+ * servidor sem jeito de deduplicar. */
+export function excludeRetryingItems(
+  queue: readonly QueuedAttachment[],
+  retryingKeys: ReadonlySet<string>,
+): readonly QueuedAttachment[] {
+  if (retryingKeys.size === 0) return queue
+  return queue.filter((item) => !retryingKeys.has(attachmentKey(item)))
+}
+
+/**
+ * Orquestra QR-34/QR-37/QR-43: texto primeiro; se falhar, nada de anexo sai. Depois os `stored` (em
+ * lote, um resultado por arquivo) e por último os `local` (sem legenda — o texto já foi mandado).
+ * Pura para ser testável sem montar componente: os efeitos colaterais são só as três portas recebidas.
+ */
+export async function sendQueuedMessage(params: SendQueuedMessageParams): Promise<SendQueuedMessageResult> {
+  const { text, queue, idempotencyKey, sendText, sendStoredAttachments, sendLocalAttachments, onAttachmentStatus } =
+    params
+
+  if (text.trim()) {
+    const textSent = await sendText(text)
+    if (!textSent) return { textSent: false, remainingQueue: queue, sentAttachmentKeys: [] }
+  }
+
+  const { attachments } = orderOutgoingItems(text, queue)
+  const stored = attachments.filter((item): item is StoredQueuedAttachment => item.kind === 'stored')
+  const local = attachments.filter(
+    (item): item is Extract<QueuedAttachment, { kind: 'local' }> => item.kind === 'local',
+  )
+
+  const results =
+    stored.length > 0 && sendStoredAttachments
+      ? await sendStoredBatch(stored, idempotencyKey, sendStoredAttachments, onAttachmentStatus)
+      : []
+
+  let remainingQueue = applySendResults(queue, results)
+  const sentAttachmentKeys = results.filter((result) => result.status === 'sent').map((result) => result.uploadId)
+
+  if (local.length > 0 && sendLocalAttachments) {
+    for (const item of local) onAttachmentStatus?.(attachmentKey(item), 'sending')
+    try {
+      await sendLocalAttachments(local.map((item) => item.file))
+      for (const item of local) onAttachmentStatus?.(attachmentKey(item), 'sent')
+      const sentKeys = new Set(local.map((item) => attachmentKey(item)))
+      remainingQueue = remainingQueue.filter((item) => item.kind !== 'local' || !sentKeys.has(attachmentKey(item)))
+      sentAttachmentKeys.push(...sentKeys)
+    } catch {
+      for (const item of local) onAttachmentStatus?.(attachmentKey(item), 'failed')
+    }
+  }
+
+  return { textSent: true, remainingQueue, sentAttachmentKeys }
+}