@adatechnology/conversations-ui 0.1.1 → 0.2.1

package/src/workspace/useComposerAttachmentRetry.ts

@@ -0,0 +1,169 @@
+/**
+ * "Tentar de novo" de um item avulso da fila do composer, extraído de `useComposerQueue`: local
+ * volta por `onSendAttachments` sem legenda (o texto, se havia, já saiu); guardado vai sozinho por
+ * `retryStoredAttachments`, com sua própria chave de idempotência (M3) — nunca a mesma do envio do
+ * rascunho, porque o conjunto de `uploadId` de um retry solo é sempre outro.
+ *
+ * Guarda de troca de conversa (H2): `ConversationPane` fica montado ao trocar de conversa, então um
+ * retry que resolve depois da troca não pode gravar na fila/estado da conversa nova com dado da
+ * antiga. O id da conversa é capturado antes do primeiro `await` e comparado com
+ * `currentConversationIdRef` (espelhado por `useComposerQueue`) depois; troca no meio, o resultado é
+ * descartado. Trava por chave (não a trava global do rascunho) impede duplo clique de reenviar o
+ * mesmo item duas vezes.
+ */
+
+import { useCallback, useRef, useState } from 'react'
+import {
+  attachmentKey,
+  resolveIdempotencyKey,
+  resolveRetryOutcome,
+  retryStoredAttachments,
+  shouldResetRetryKey,
+  type AttachmentSendStatus,
+  type IdempotencyKeyState,
+} from '../quickReplies/quickReplyAttachments'
+import type { QueuedAttachment } from '../quickReplies/quickReply.types'
+import type { ConversationsApi } from '../providers/types'
+
+export type UseComposerAttachmentRetryParams = {
+  readonly conversationId: string
+  readonly currentConversationIdRef: { readonly current: string }
+  readonly queue: readonly QueuedAttachment[]
+  readonly setQueue: (updater: (current: readonly QueuedAttachment[]) => readonly QueuedAttachment[]) => void
+  readonly setAttachmentStatus: (
+    updater: (current: Record<string, AttachmentSendStatus>) => Record<string, AttachmentSendStatus>,
+  ) => void
+  readonly setSendFailure: (message: string | undefined) => void
+  readonly api: Pick<ConversationsApi, 'sendStoredAttachments'>
+  readonly onSendAttachments?: (files: readonly File[], caption: string) => Promise<void>
+  readonly labels: { readonly attachFailure: string }
+  /** Espelha o envio completo do rascunho (`useComposerQueue`): um retry avulso não pode disparar
+   * enquanto o composer inteiro está em voo — as duas chaves de idempotência colidiriam no mesmo item. */
+  readonly sendInFlightRef: { readonly current: boolean }
+}
+
+export type UseComposerAttachmentRetryResult = {
+  readonly retryQueuedAttachment: (item: QueuedAttachment) => void
+  /** Chamado por `useComposerQueue` ao trocar de conversa: descarta chave de idempotência e travas. */
+  readonly resetRetryState: () => void
+  /** Chaves com retry avulso em voo — `useComposerQueue` exclui estas de um envio completo (evita
+   * duplo envio do mesmo item), e a UI desabilita o botão "Tentar de novo" enquanto durar. */
+  readonly retryingKeys: ReadonlySet<string>
+}
+
+export function useComposerAttachmentRetry(params: UseComposerAttachmentRetryParams): UseComposerAttachmentRetryResult {
+  const {
+    conversationId,
+    currentConversationIdRef,
+    queue,
+    setQueue,
+    setAttachmentStatus,
+    setSendFailure,
+    api,
+    onSendAttachments,
+    labels,
+    sendInFlightRef,
+  } = params
+  const retryIdempotencyKeyRef = useRef<IdempotencyKeyState | undefined>(undefined)
+  /** Chaves com retry em voo — impede duplo clique de reenviar o mesmo item duas vezes. */
+  const retryingKeysRef = useRef<Set<string>>(new Set())
+  /** Espelho reativo de `retryingKeysRef` — o ref sozinho não repinta o botão desabilitado. */
+  const [retryingKeys, setRetryingKeys] = useState<ReadonlySet<string>>(new Set())
+
+  function markRetrying(key: string): void {
+    retryingKeysRef.current.add(key)
+    setRetryingKeys(new Set(retryingKeysRef.current))
+  }
+
+  function unmarkRetrying(key: string): void {
+    retryingKeysRef.current.delete(key)
+    setRetryingKeys(new Set(retryingKeysRef.current))
+  }
+
+  async function retryLocalAttachment(item: Extract<QueuedAttachment, { kind: 'local' }>): Promise<void> {
+    if (!onSendAttachments) return
+    const key = attachmentKey(item)
+    const conversationIdAtRetry = conversationId
+    const isSameConversation = (): boolean => currentConversationIdRef.current === conversationIdAtRetry
+    setAttachmentStatus((current) => ({ ...current, [key]: 'sending' }))
+    try {
+      await onSendAttachments([item.file], '')
+      if (!isSameConversation()) return
+      setAttachmentStatus((current) => ({ ...current, [key]: 'sent' }))
+      setQueue((current) => current.filter((queued) => attachmentKey(queued) !== key))
+    } catch (error: unknown) {
+      if (!isSameConversation()) return
+      setAttachmentStatus((current) => ({ ...current, [key]: 'failed' }))
+      setSendFailure(error instanceof Error ? error.message : labels.attachFailure)
+    }
+  }
+
+  async function retryStoredAttachment(item: Extract<QueuedAttachment, { kind: 'stored' }>): Promise<void> {
+    const sendStoredAttachmentsApi = api.sendStoredAttachments
+    if (!sendStoredAttachmentsApi) return
+    const conversationIdAtRetry = conversationId
+    const isSameConversation = (): boolean => currentConversationIdRef.current === conversationIdAtRetry
+    const uploadIds = [item.uploadId]
+    const idempotencyState = resolveIdempotencyKey(retryIdempotencyKeyRef.current, uploadIds)
+    retryIdempotencyKeyRef.current = idempotencyState
+    try {
+      const result = await retryStoredAttachments({
+        queue,
+        uploadIds,
+        idempotencyKey: idempotencyState.key,
+        sendStoredAttachments: (uploadParams) =>
+          sendStoredAttachmentsApi({ conversationId: conversationIdAtRetry, ...uploadParams }),
+        onAttachmentStatus: (statusKey, status) => {
+          if (isSameConversation()) setAttachmentStatus((current) => ({ ...current, [statusKey]: status }))
+        },
+      })
+      // Descarta a chave só se este retry a enviou E nenhum retry mais novo do mesmo `uploadId`
+      // já trocou o ref por identidade (ver `shouldResetRetryKey`) — senão um segundo retry rápido
+      // do mesmo anexo (mensagens prontas reusam `uploadId`) reenviaria com chave já consumida.
+      if (
+        shouldResetRetryKey({
+          current: retryIdempotencyKeyRef.current,
+          attempted: idempotencyState,
+          sentAttachmentKeys: result.sentAttachmentKeys,
+          uploadId: item.uploadId,
+        })
+      ) {
+        retryIdempotencyKeyRef.current = undefined
+      }
+      setQueue(
+        (current) =>
+          resolveRetryOutcome({
+            conversationIdAtRetry,
+            currentConversationId: currentConversationIdRef.current,
+            sentAttachmentKeys: result.sentAttachmentKeys,
+            queue: current,
+          }) ?? current,
+      )
+    } catch (error: unknown) {
+      if (isSameConversation()) setSendFailure(error instanceof Error ? error.message : labels.attachFailure)
+    }
+  }
+
+  function retryQueuedAttachment(item: QueuedAttachment): void {
+    // Um envio completo já está em voo — deixá-lo terminar antes de aceitar retry avulso, senão as
+    // duas chaves de idempotência disputam o mesmo item.
+    if (sendInFlightRef.current) return
+    const key = attachmentKey(item)
+    if (retryingKeysRef.current.has(key)) return
+    markRetrying(key)
+    const release = (): void => unmarkRetrying(key)
+    if (item.kind === 'local') {
+      void retryLocalAttachment(item).finally(release)
+      return
+    }
+    void retryStoredAttachment(item).finally(release)
+  }
+
+  const resetRetryState = useCallback((): void => {
+    retryIdempotencyKeyRef.current = undefined
+    retryingKeysRef.current.clear()
+    setRetryingKeys(new Set())
+  }, [])
+
+  return { retryQueuedAttachment, resetRetryState, retryingKeys }
+}

package/src/workspace/useComposerQueue.ts

@@ -0,0 +1,229 @@
+/**
+ * Fila de anexos do composer rico, extraída de `ConversationPane`: texto -> guardados -> locais
+ * (QR-34/QR-43). Reseta tudo ao trocar de conversa (H2).
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import {
+  attachmentKey,
+  excludeRetryingItems,
+  hasSentEveryStoredUpload,
+  resolveIdempotencyKey,
+  sendQueuedMessage,
+  type AttachmentSendStatus,
+  type IdempotencyKeyState,
+} from '../quickReplies/quickReplyAttachments'
+import { useComposerAttachmentRetry } from './useComposerAttachmentRetry'
+import type { QueuedAttachment } from '../quickReplies/quickReply.types'
+import type { ConversationsApi } from '../providers/types'
+
+export type UseComposerQueueParams = {
+  readonly conversationId: string
+  readonly draft: string
+  readonly setDraft: (value: string) => void
+  readonly api: Pick<ConversationsApi, 'sendMessage' | 'sendStoredAttachments'>
+  readonly labels: { readonly sendFailure: string; readonly attachFailure: string }
+  readonly onSendAttachments?: (files: readonly File[], caption: string) => Promise<void>
+  readonly refetch: () => Promise<void>
+  readonly setSendFailure: (message: string | undefined) => void
+}
+
+export type UseComposerQueueResult = {
+  readonly queue: readonly QueuedAttachment[]
+  readonly enqueueAttachments: (items: readonly QueuedAttachment[]) => void
+  readonly attachmentStatus: Record<string, AttachmentSendStatus>
+  readonly isSendingDraft: boolean
+  readonly handleRichSend: () => Promise<void>
+  readonly removeQueuedAttachment: (item: QueuedAttachment) => void
+  readonly retryQueuedAttachment: (item: QueuedAttachment) => void
+  /** Chaves com retry avulso em voo — a UI desabilita o botão "Tentar de novo" desses itens. */
+  readonly retryingKeys: ReadonlySet<string>
+}
+
+export function useComposerQueue(params: UseComposerQueueParams): UseComposerQueueResult {
+  const { conversationId, draft, setDraft, api, labels, onSendAttachments, refetch, setSendFailure } = params
+
+  const [queue, setQueue] = useState<readonly QueuedAttachment[]>([])
+  const [attachmentStatus, setAttachmentStatus] = useState<Record<string, AttachmentSendStatus>>({})
+  const [isSendingDraft, setIsSendingDraft] = useState(false)
+  /** Ref, não estado: entre dois cliques seguidos o React ainda não teria repintado a trava. */
+  const sendInFlightRef = useRef(false)
+  /** Uma por conjunto de `uploadId` guardado em voo (QR-38, M3); muda, `resolveIdempotencyKey` troca. */
+  const idempotencyKeyRef = useRef<IdempotencyKeyState | undefined>(undefined)
+  /** Espelha `conversationId` sem esperar o repaint (H2) — lido depois do `await` de um envio. */
+  const currentConversationIdRef = useRef(conversationId)
+
+  const { retryQueuedAttachment, resetRetryState, retryingKeys } = useComposerAttachmentRetry({
+    conversationId,
+    currentConversationIdRef,
+    queue,
+    setQueue,
+    setAttachmentStatus,
+    setSendFailure,
+    api,
+    labels,
+    sendInFlightRef,
+    ...(onSendAttachments ? { onSendAttachments } : {}),
+  })
+
+  // Trocar de conversa abandona o envio em andamento — senão a resposta tardia reabilitaria o
+  // composer errado ou reusaria a chave de idempotência de outra thread.
+  useEffect(() => {
+    currentConversationIdRef.current = conversationId
+    setQueue([])
+    setAttachmentStatus({})
+    idempotencyKeyRef.current = undefined
+    sendInFlightRef.current = false
+    setIsSendingDraft(false)
+    resetRetryState()
+  }, [conversationId, resetRetryState])
+
+  const enqueueAttachments = useCallback((items: readonly QueuedAttachment[]) => {
+    if (items.length === 0) return
+    setQueue((current) => [...current, ...items])
+  }, [])
+
+  const removeQueuedAttachment = useCallback((item: QueuedAttachment) => {
+    setQueue((current) => current.filter((queued) => attachmentKey(queued) !== attachmentKey(item)))
+  }, [])
+
+  /** Devolve se o envio passou: limpar o rascunho depois de uma falha apagaria o texto do operador. */
+  async function runSend(action: () => Promise<unknown>, fallback: string): Promise<boolean> {
+    setSendFailure(undefined)
+    try {
+      await action()
+      await refetch()
+      return true
+    } catch (error: unknown) {
+      setSendFailure(error instanceof Error ? error.message : fallback)
+      return false
+    }
+  }
+
+  /** Fila só com `local`, como antes da feature de guardados: uma chamada só, rascunho como legenda. */
+  async function sendLocalOnlyAttachments(isSameConversation: () => boolean): Promise<void> {
+    if (!onSendAttachments) return
+    const files = excludeRetryingItems(queue, retryingKeys)
+      .filter((item): item is Extract<QueuedAttachment, { kind: 'local' }> => item.kind === 'local')
+      .map((item) => item.file)
+    try {
+      const didSend = await runSend(() => onSendAttachments(files, draft), labels.attachFailure)
+      if (!isSameConversation()) return
+      if (didSend) {
+        // Preserva item com retry avulso em voo (excluído deste envio) — ele ainda não foi resolvido.
+        setQueue((current) => current.filter((item) => retryingKeys.has(attachmentKey(item))))
+        setAttachmentStatus((current) =>
+          Object.fromEntries(Object.entries(current).filter(([key]) => retryingKeys.has(key))),
+        )
+        idempotencyKeyRef.current = undefined
+        setDraft('')
+      }
+    } finally {
+      if (isSameConversation()) {
+        sendInFlightRef.current = false
+        setIsSendingDraft(false)
+      }
+    }
+  }
+
+  /** Texto -> guardados (lote, um resultado por arquivo) -> locais. Só o que não saiu continua na fila. */
+  async function sendQueuedDraft(isSameConversation: () => boolean): Promise<void> {
+    const sendStoredAttachmentsApi = api.sendStoredAttachments
+    // Item com retry avulso em voo fica de fora deste envio (chave de idempotência diferente) —
+    // senão o servidor recebe o mesmo anexo em dois lotes sem jeito de deduplicar.
+    const sendableQueue = excludeRetryingItems(queue, retryingKeys)
+    const storedUploadIds = sendableQueue
+      .filter((item): item is Extract<QueuedAttachment, { kind: 'stored' }> => item.kind === 'stored')
+      .map((item) => item.uploadId)
+    const idempotencyState = resolveIdempotencyKey(idempotencyKeyRef.current, storedUploadIds)
+    idempotencyKeyRef.current = idempotencyState
+    try {
+      const result = await sendQueuedMessage({
+        text: draft,
+        queue: sendableQueue,
+        idempotencyKey: idempotencyState.key,
+        sendText: (text) => runSend(() => api.sendMessage(conversationId, text), labels.sendFailure),
+        ...(sendStoredAttachmentsApi
+          ? {
+              sendStoredAttachments: (uploadParams: { uploadIds: readonly string[]; idempotencyKey: string }) =>
+                sendStoredAttachmentsApi({ conversationId, ...uploadParams }),
+            }
+          : {}),
+        ...(onSendAttachments
+          ? { sendLocalAttachments: (files: readonly File[]) => onSendAttachments(files, '') }
+          : {}),
+        onAttachmentStatus: (key, status) => {
+          if (isSameConversation()) setAttachmentStatus((current) => ({ ...current, [key]: status }))
+        },
+      })
+      if (!isSameConversation()) return
+      // `runSend` já gravou o erro específico do texto (`setSendFailure`) — não sobrescrever com o
+      // rótulo genérico.
+      if (!result.textSent) return
+      // Filtra por chave sobre a fila CORRENTE, não sobrescreve com `result.remainingQueue` (que foi
+      // calculado sobre a fila capturada antes do `await` e perderia item adicionado durante o envio).
+      const sentKeys = new Set(result.sentAttachmentKeys)
+      setQueue((current) => current.filter((item) => !sentKeys.has(attachmentKey(item))))
+      // Decide sobre os `uploadId` desta TENTATIVA (`idempotencyState.uploadIds`), nunca sobre o
+      // `setQueue` acima: o updater de `setQueue` não roda de forma síncrona (só no próximo render),
+      // então ler uma variável escrita por ele aqui sempre pegaria o valor antigo (bug real em
+      // produção — a chave nunca era descartada e o segundo envio do mesmo anexo era recusado pelo
+      // servidor como replay).
+      setAttachmentStatus((current) => {
+        const next = { ...current }
+        for (const key of sentKeys) delete next[key]
+        return next
+      })
+      // Descarta a chave só se ninguém a trocou por identidade desde o `await` (mesmo cuidado do
+      // retry avulso em `shouldResetRetryKey`) — senão um envio concorrente que já trocou o ref
+      // teria sua chave nova apagada por esta tentativa mais antiga.
+      if (
+        idempotencyKeyRef.current === idempotencyState &&
+        hasSentEveryStoredUpload(idempotencyState.uploadIds, result.sentAttachmentKeys)
+      ) {
+        idempotencyKeyRef.current = undefined
+      }
+      if (draft.trim()) setDraft('')
+      await refetch()
+    } catch (error: unknown) {
+      if (isSameConversation()) setSendFailure(error instanceof Error ? error.message : labels.attachFailure)
+    } finally {
+      if (isSameConversation()) {
+        sendInFlightRef.current = false
+        setIsSendingDraft(false)
+      }
+    }
+  }
+
+  /** Texto primeiro; se falhar, nenhum anexo sai (QR-34, QR-43). Só o que não saiu continua na fila. */
+  async function handleRichSend(): Promise<void> {
+    // Trava contra clique duplo / Enter impaciente enquanto o upload está em voo.
+    if (sendInFlightRef.current) return
+    if (!draft.trim() && queue.length === 0) return
+    sendInFlightRef.current = true
+    setIsSendingDraft(true)
+    setSendFailure(undefined)
+    // Capturado antes do primeiro `await` (H2) — ver `currentConversationIdRef`.
+    const conversationIdAtSend = conversationId
+    const isSameConversation = (): boolean => currentConversationIdRef.current === conversationIdAtSend
+
+    // QR-32/QR-33: só `stored` (mensagem pronta) vai pelo pipeline novo; só `local` fica no antigo.
+    const hasStoredItems = queue.some((item) => item.kind === 'stored')
+    if (onSendAttachments && queue.length > 0 && !hasStoredItems) {
+      await sendLocalOnlyAttachments(isSameConversation)
+      return
+    }
+    await sendQueuedDraft(isSameConversation)
+  }
+
+  return {
+    queue,
+    enqueueAttachments,
+    attachmentStatus,
+    isSendingDraft,
+    handleRichSend,
+    removeQueuedAttachment,
+    retryQueuedAttachment,
+    retryingKeys,
+  }
+}