@adatechnology/conversations-ui 0.1.0 → 0.2.0

package/src/quickReplies/useQuickRepliesWorkspace.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  insertAtCursor,
+  submitQuickReply,
+  validateQuickReplyInput,
+  type QuickRepliesWorkspaceApi,
+  type QuickRepliesWorkspaceEditing,
+} from './useQuickRepliesWorkspace'
+import { DEFAULT_QUICK_REPLIES_WORKSPACE_LABELS } from './labels'
+import type { QuickReply } from './quickReply.types'
+
+const LABELS = DEFAULT_QUICK_REPLIES_WORKSPACE_LABELS
+
+const VALID_EDITING: QuickRepliesWorkspaceEditing = {
+  id: null,
+  title: 'Saudação',
+  shortcut: 'ola',
+  body: 'Olá!',
+  attachments: [],
+}
+const SAVED: QuickReply = { id: '1', title: 'Saudação', shortcut: 'ola', body: 'Olá!' }
+
+describe('validateQuickReplyInput', () => {
+  it('aceita título, atalho e corpo dentro do limite', () => {
+    expect(validateQuickReplyInput({ title: 'Saudação', shortcut: 'ola', body: 'Olá!' }, LABELS)).toEqual({})
+  })
+
+  it('rejeita título vazio ou maior que 40 caracteres', () => {
+    expect(validateQuickReplyInput({ title: '', shortcut: 'ola', body: 'Olá!' }, LABELS).title).toBeDefined()
+    expect(
+      validateQuickReplyInput({ title: 'x'.repeat(41), shortcut: 'ola', body: 'Olá!' }, LABELS).title,
+    ).toBeDefined()
+  })
+
+  it('rejeita atalho com maiúscula, espaço ou acento', () => {
+    expect(validateQuickReplyInput({ title: 'T', shortcut: 'Ola', body: 'B' }, LABELS).shortcut).toBeDefined()
+    expect(validateQuickReplyInput({ title: 'T', shortcut: 'ol a', body: 'B' }, LABELS).shortcut).toBeDefined()
+    expect(validateQuickReplyInput({ title: 'T', shortcut: 'olá', body: 'B' }, LABELS).shortcut).toBeDefined()
+  })
+
+  it('aceita atalho com hífen e número', () => {
+    expect(validateQuickReplyInput({ title: 'T', shortcut: 'doc-2', body: 'B' }, LABELS).shortcut).toBeUndefined()
+  })
+
+  it('rejeita corpo vazio ou maior que 1000 caracteres', () => {
+    expect(validateQuickReplyInput({ title: 'T', shortcut: 'ola', body: '' }, LABELS).body).toBeDefined()
+    expect(validateQuickReplyInput({ title: 'T', shortcut: 'ola', body: 'x'.repeat(1001) }, LABELS).body).toBeDefined()
+  })
+})
+
+describe('submitQuickReply', () => {
+  it('cria quando id é null e chama createQuickReply', async () => {
+    const api: QuickRepliesWorkspaceApi = { createQuickReply: async () => SAVED }
+    const result = await submitQuickReply({ api, editing: VALID_EDITING, labels: LABELS })
+    expect(result).toEqual({ outcome: 'saved', quickReply: SAVED })
+  })
+
+  it('atualiza quando há id e chama updateQuickReply com ele', async () => {
+    let calledWith: string | undefined
+    const api: QuickRepliesWorkspaceApi = {
+      updateQuickReply: async (id) => {
+        calledWith = id
+        return SAVED
+      },
+    }
+    const result = await submitQuickReply({ api, editing: { ...VALID_EDITING, id: '1' }, labels: LABELS })
+    expect(result).toEqual({ outcome: 'saved', quickReply: SAVED })
+    expect(calledWith).toBe('1')
+  })
+
+  it('manda attachmentUploadIds só quando o host tem a porta de upload (QR-30)', async () => {
+    let receivedInput: unknown
+    const withUpload: QuickRepliesWorkspaceApi = {
+      createQuickReply: async (input) => {
+        receivedInput = input
+        return SAVED
+      },
+      uploadQuickReplyAttachment: async () => ({ uploadId: 'x', filename: 'x', mimeType: 'x', sizeBytes: 1 }),
+    }
+    const editingWithAttachments = {
+      ...VALID_EDITING,
+      attachments: [{ uploadId: 'a', filename: 'a.pdf', mimeType: 'application/pdf', sizeBytes: 1 }],
+    }
+    await submitQuickReply({ api: withUpload, editing: editingWithAttachments, labels: LABELS })
+    expect((receivedInput as { attachmentUploadIds?: readonly string[] }).attachmentUploadIds).toEqual(['a'])
+
+    const withoutUpload: QuickRepliesWorkspaceApi = {
+      createQuickReply: async (input) => {
+        receivedInput = input
+        return SAVED
+      },
+    }
+    await submitQuickReply({ api: withoutUpload, editing: editingWithAttachments, labels: LABELS })
+    expect((receivedInput as { attachmentUploadIds?: readonly string[] }).attachmentUploadIds).toBeUndefined()
+  })
+
+  it('não chama a api quando a validação falha', async () => {
+    let called = false
+    const api: QuickRepliesWorkspaceApi = {
+      createQuickReply: async () => {
+        called = true
+        return SAVED
+      },
+    }
+    const result = await submitQuickReply({ api, editing: { ...VALID_EDITING, title: '' }, labels: LABELS })
+    expect(result.outcome).toBe('invalid')
+    expect(called).toBe(false)
+  })
+
+  it('409 com code QUICK_REPLY_SHORTCUT_TAKEN vira erro no campo atalho', async () => {
+    const api: QuickRepliesWorkspaceApi = {
+      createQuickReply: async () => {
+        throw { code: 'QUICK_REPLY_SHORTCUT_TAKEN' }
+      },
+    }
+    const result = await submitQuickReply({ api, editing: VALID_EDITING, labels: LABELS })
+    expect(result).toEqual({ outcome: 'rejected', fieldErrors: { shortcut: LABELS.shortcutTaken } })
+  })
+
+  it('error.details[] com vários campos aponta cada um no seu campo', async () => {
+    const api: QuickRepliesWorkspaceApi = {
+      createQuickReply: async () => {
+        throw {
+          details: [
+            { field: 'title', message: 'Título repetido' },
+            { field: 'shortcut', message: 'Atalho em uso' },
+          ],
+        }
+      },
+    }
+    const result = await submitQuickReply({ api, editing: VALID_EDITING, labels: LABELS })
+    expect(result).toEqual({
+      outcome: 'rejected',
+      fieldErrors: { title: 'Título repetido', shortcut: 'Atalho em uso' },
+    })
+  })
+
+  it('erro sem details vira o rótulo do formulário, nunca a mensagem crua da exceção', async () => {
+    const api: QuickRepliesWorkspaceApi = {
+      createQuickReply: async () => {
+        throw new Error('ECONNRESET: socket hang up')
+      },
+    }
+    const result = await submitQuickReply({ api, editing: VALID_EDITING, labels: LABELS })
+    expect(result).toEqual({ outcome: 'rejected', fieldErrors: {}, formError: LABELS.saveError })
+  })
+
+  it('409 com code aninhado em error.response.data.error (axios) vira erro no atalho', async () => {
+    const api: QuickRepliesWorkspaceApi = {
+      createQuickReply: async () => {
+        throw {
+          response: {
+            data: {
+              error: {
+                code: 'QUICK_REPLY_SHORTCUT_TAKEN',
+                message: 'Atalho já existe',
+                details: [{ field: 'shortcut', message: 'Atalho já existe' }],
+              },
+            },
+          },
+        }
+      },
+    }
+    const result = await submitQuickReply({ api, editing: VALID_EDITING, labels: LABELS })
+    expect(result).toEqual({ outcome: 'rejected', fieldErrors: { shortcut: 'Atalho já existe' } })
+  })
+
+  it('erro aninhado em error.error (envelope { error: {...} }) vira erro no atalho', async () => {
+    const api: QuickRepliesWorkspaceApi = {
+      createQuickReply: async () => {
+        throw {
+          error: {
+            code: 'QUICK_REPLY_SHORTCUT_TAKEN',
+            message: 'Atalho já existe',
+            details: [{ field: 'shortcut', message: 'Atalho já existe' }],
+          },
+        }
+      },
+    }
+    const result = await submitQuickReply({ api, editing: VALID_EDITING, labels: LABELS })
+    expect(result).toEqual({ outcome: 'rejected', fieldErrors: { shortcut: 'Atalho já existe' } })
+  })
+
+  it('erro aninhado em error.body.error vira erro no atalho', async () => {
+    const api: QuickRepliesWorkspaceApi = {
+      createQuickReply: async () => {
+        throw { body: { error: { code: 'QUICK_REPLY_SHORTCUT_TAKEN' } } }
+      },
+    }
+    const result = await submitQuickReply({ api, editing: VALID_EDITING, labels: LABELS })
+    expect(result).toEqual({ outcome: 'rejected', fieldErrors: { shortcut: LABELS.shortcutTaken } })
+  })
+
+  it('erro que se referencia (error.error === error) não trava em recursão infinita', async () => {
+    const circular: Record<string, unknown> = {}
+    circular.error = circular
+    const api: QuickRepliesWorkspaceApi = {
+      createQuickReply: async () => {
+        throw circular
+      },
+    }
+    const result = await submitQuickReply({ api, editing: VALID_EDITING, labels: LABELS })
+    expect(result).toEqual({ outcome: 'rejected', fieldErrors: {}, formError: LABELS.saveError })
+  })
+
+  it('editando sem updateQuickReply na porta, rejeita com saveUnavailable em vez de fingir sucesso', async () => {
+    const api: QuickRepliesWorkspaceApi = {}
+    const result = await submitQuickReply({ api, editing: { ...VALID_EDITING, id: '1' }, labels: LABELS })
+    expect(result).toEqual({ outcome: 'rejected', fieldErrors: {}, formError: LABELS.saveUnavailable })
+  })
+})
+
+describe('insertAtCursor', () => {
+  it('insere o marcador na posição do cursor', () => {
+    expect(insertAtCursor('Olá !', 4, 4, '{{nome}}')).toEqual({ text: 'Olá {{nome}}!', caret: 12 })
+  })
+
+  it('troca a seleção pelo marcador', () => {
+    expect(insertAtCursor('Olá NOME!', 4, 8, '{{nome}}')).toEqual({ text: 'Olá {{nome}}!', caret: 12 })
+  })
+})

package/src/quickReplies/useQuickRepliesWorkspace.ts

@@ -0,0 +1,426 @@
+import { useCallback, useEffect, useState } from 'react'
+import { filterQuickReplies } from './quickReplySearch'
+import { moveAttachment } from './quickReplyAttachmentUpload'
+import { useQuickReplyAttachmentUploads } from './useQuickReplyAttachmentUploads'
+import type { PendingAttachmentUpload } from './useQuickReplyAttachmentUploads'
+import type { AttachmentFileRejection } from './quickReplyAttachmentUpload'
+import type { MaxAttachmentSizeBytes } from './quickReplyAttachments'
+import type { QuickReply, QuickReplyAttachment, QuickReplyInput } from './quickReply.types'
+import type { QuickRepliesWorkspaceLabels } from './labels'
+
+export type { PendingAttachmentUpload } from './useQuickReplyAttachmentUploads'
+
+/**
+ * Portas que a tela de cadastro precisa. `create`/`update`/`delete` ausentes não impedem a leitura
+ * — só tiram a ação correspondente, a mesma regra de capacidade do resto do pacote.
+ */
+export interface QuickRepliesWorkspaceApi {
+  readonly listQuickReplies?: (params?: { search?: string }) => Promise<QuickReply[]>
+  readonly createQuickReply?: (input: QuickReplyInput) => Promise<QuickReply>
+  readonly updateQuickReply?: (id: string, input: QuickReplyInput) => Promise<QuickReply>
+  readonly deleteQuickReply?: (id: string) => Promise<void>
+  /** Sem esta porta, a seção de anexos não aparece — nem no formulário. */
+  readonly uploadQuickReplyAttachment?: (
+    file: File,
+    options?: { onProgress?: (fraction: number) => void; signal?: AbortSignal },
+  ) => Promise<QuickReplyAttachment>
+}
+
+export type QuickReplyFormField = 'title' | 'shortcut' | 'body'
+export type QuickRepliesWorkspaceFieldErrors = Partial<Record<QuickReplyFormField, string>>
+
+export type QuickRepliesWorkspaceEditing = {
+  /** `null` é a criação; presente é edição do registro com este id. */
+  readonly id: string | null
+  readonly title: string
+  readonly shortcut: string
+  readonly body: string
+  /** Já subidos — a ordem daqui é a ordem de envio salva (QR-30). */
+  readonly attachments: readonly QuickReplyAttachment[]
+}
+
+const TITLE_MAX_LENGTH = 40
+const BODY_MAX_LENGTH = 1000
+const SHORTCUT_PATTERN = /^[a-z0-9-]{1,20}$/
+
+/** Casca genérica de erro de API com `code` e `details[]` (`apis.md`) — sem acoplar a um cliente HTTP específico. */
+type ApiErrorShape = { readonly code?: unknown; readonly details?: unknown }
+
+/**
+ * Desembrulha a casca `{ code, details }` de onde quer que o cliente HTTP do host a tenha
+ * pendurado. `apis.md` define o envelope `{ error: { code, message, details } }`, mas cada cliente
+ * (fetch cru, axios, o `Error` que o `ConversationsProvider` relança) expõe o objeto lançado de um
+ * jeito diferente — `error.error`, `error.response.data.error` (axios) ou `error.body.error`
+ * (alguns wrappers de fetch). Sem isto, a rejeição real do servidor nunca chega ao formulário e o
+ * operador só vê "não foi possível salvar", mesmo quando a API já mandou o campo certo.
+ */
+const MAX_ERROR_ENVELOPE_DEPTH = 3
+
+/**
+ * Desce no máximo `MAX_ERROR_ENVELOPE_DEPTH` níveis: um erro que se referencia (`error.error ===
+ * error`, comum em `Error` customizado com `cause` circular) faria a recursão nunca terminar.
+ */
+function apiErrorEnvelopeOf(error: unknown, depth = 0): ApiErrorShape | undefined {
+  if (depth >= MAX_ERROR_ENVELOPE_DEPTH) return undefined
+  if (!error || typeof error !== 'object') return undefined
+  const candidate = error as Record<string, unknown>
+  if ('code' in candidate || 'details' in candidate) return candidate as ApiErrorShape
+  const nested =
+    (candidate.error as unknown) ??
+    (candidate.response as Record<string, unknown> | undefined)?.data ??
+    (candidate.body as unknown)
+  if (nested && typeof nested === 'object') return apiErrorEnvelopeOf(nested, depth + 1)
+  return undefined
+}
+
+function fieldErrorsOf(error: unknown): QuickRepliesWorkspaceFieldErrors {
+  const envelope = apiErrorEnvelopeOf(error)
+  if (!envelope) return {}
+  const details = envelope.details
+  if (!Array.isArray(details)) return {}
+  const result: QuickRepliesWorkspaceFieldErrors = {}
+  for (const detail of details) {
+    if (!detail || typeof detail !== 'object') continue
+    const field = (detail as { field?: unknown }).field
+    const message = (detail as { message?: unknown }).message
+    if (typeof field === 'string' && typeof message === 'string' && isFormField(field)) {
+      result[field] = message
+    }
+  }
+  return result
+}
+
+function isFormField(value: string): value is QuickReplyFormField {
+  return value === 'title' || value === 'shortcut' || value === 'body'
+}
+
+function errorCodeOf(error: unknown): string | undefined {
+  const code = apiErrorEnvelopeOf(error)?.code
+  return typeof code === 'string' ? code : undefined
+}
+
+/** Regras de formato — as mesmas do backend (`QR-08`), verificadas antes de gastar uma chamada. */
+export function validateQuickReplyInput(
+  input: QuickReplyInput,
+  labels: QuickRepliesWorkspaceLabels,
+): QuickRepliesWorkspaceFieldErrors {
+  const errors: QuickRepliesWorkspaceFieldErrors = {}
+  if (!input.title.trim() || input.title.length > TITLE_MAX_LENGTH) errors.title = labels.fieldTitleInvalid
+  if (!SHORTCUT_PATTERN.test(input.shortcut)) errors.shortcut = labels.fieldShortcutInvalid
+  if (!input.body.trim() || input.body.length > BODY_MAX_LENGTH) errors.body = labels.fieldBodyInvalid
+  return errors
+}
+
+export type SubmitQuickReplyParams = {
+  readonly api: QuickRepliesWorkspaceApi
+  readonly editing: QuickRepliesWorkspaceEditing
+  readonly labels: QuickRepliesWorkspaceLabels
+}
+
+export type SubmitQuickReplyResult =
+  | { readonly outcome: 'saved'; readonly quickReply: QuickReply }
+  | { readonly outcome: 'invalid'; readonly fieldErrors: QuickRepliesWorkspaceFieldErrors }
+  | {
+      readonly outcome: 'rejected'
+      readonly fieldErrors: QuickRepliesWorkspaceFieldErrors
+      readonly formError?: string
+    }
+
+/**
+ * Toda a lógica de salvar num único lugar testável sem montar o hook: valida, chama a porta certa
+ * (criar ou atualizar) e traduz a rejeição — 409 com `code: 'QUICK_REPLY_SHORTCUT_TAKEN'` ou
+ * `error.details[]` — no campo que errou.
+ */
+export async function submitQuickReply({
+  api,
+  editing,
+  labels,
+}: SubmitQuickReplyParams): Promise<SubmitQuickReplyResult> {
+  const input: QuickReplyInput = {
+    title: editing.title.trim(),
+    shortcut: editing.shortcut.trim(),
+    body: editing.body,
+    // Só manda a lista quando o host oferece a porta de upload — ausente, `attachmentUploadIds`
+    // some do payload e o backend não mexe nos anexos já gravados (contrato do tipo).
+    ...(api.uploadQuickReplyAttachment
+      ? { attachmentUploadIds: editing.attachments.map((attachment) => attachment.uploadId) }
+      : {}),
+  }
+  const validationErrors = validateQuickReplyInput(input, labels)
+  if (Object.keys(validationErrors).length > 0) return { outcome: 'invalid', fieldErrors: validationErrors }
+
+  const editingId = editing.id
+  if (editingId === null && !api.createQuickReply) {
+    return { outcome: 'rejected', fieldErrors: {}, formError: labels.saveUnavailable }
+  }
+  if (editingId !== null && !api.updateQuickReply) {
+    return { outcome: 'rejected', fieldErrors: {}, formError: labels.saveUnavailable }
+  }
+  const save =
+    editingId === null
+      ? (api.createQuickReply as NonNullable<QuickRepliesWorkspaceApi['createQuickReply']>)
+      : (input: QuickReplyInput) =>
+          (api.updateQuickReply as NonNullable<QuickRepliesWorkspaceApi['updateQuickReply']>)(editingId, input)
+
+  try {
+    const quickReply = await save(input)
+    if (!quickReply) return { outcome: 'invalid', fieldErrors: {} }
+    return { outcome: 'saved', quickReply }
+  } catch (caught: unknown) {
+    const detailErrors = fieldErrorsOf(caught)
+    const code = errorCodeOf(caught)
+    const shortcutMessage =
+      detailErrors.shortcut ?? (code === 'QUICK_REPLY_SHORTCUT_TAKEN' ? labels.shortcutTaken : undefined)
+    if (shortcutMessage || Object.keys(detailErrors).length > 0) {
+      return {
+        outcome: 'rejected',
+        fieldErrors: { ...detailErrors, ...(shortcutMessage ? { shortcut: shortcutMessage } : {}) },
+      }
+    }
+    // Nunca `caught.message` cru: é texto de exceção interna (rede, parsing), não algo que o
+    // operador deva ler — a mensagem exibida é sempre o rótulo do host (QR-10).
+    return {
+      outcome: 'rejected',
+      fieldErrors: {},
+      formError: labels.saveError,
+    }
+  }
+}
+
+export type InsertAtCursorResult = {
+  readonly text: string
+  readonly caret: number
+}
+
+/** Insere `marker` na posição do cursor (ou troca a seleção) — usado pelo botão "Inserir variável". */
+export function insertAtCursor(text: string, start: number, end: number, marker: string): InsertAtCursorResult {
+  return { text: text.slice(0, start) + marker + text.slice(end), caret: start + marker.length }
+}
+
+export type UseQuickRepliesWorkspaceParams = {
+  readonly api: QuickRepliesWorkspaceApi
+  readonly labels: QuickRepliesWorkspaceLabels
+  /** Sobrescreve o teto por tipo de arquivo. Ausente, usa `DEFAULT_MAX_ATTACHMENT_SIZE_BYTES`. */
+  readonly attachmentSizeLimits?: MaxAttachmentSizeBytes
+}
+
+export type UseQuickRepliesWorkspaceResult = {
+  readonly quickReplies: readonly QuickReply[]
+  readonly filtered: readonly QuickReply[]
+  readonly isLoading: boolean
+  readonly loadError: string | undefined
+  readonly search: string
+  readonly setSearch: (value: string) => void
+  /** Sem `createQuickReply`, a tela só mostra a tabela — nada de criar, editar ou excluir. */
+  readonly readOnly: boolean
+  readonly canEdit: boolean
+  readonly canDelete: boolean
+  readonly editing: QuickRepliesWorkspaceEditing | undefined
+  readonly startCreate: () => void
+  readonly startEdit: (quickReply: QuickReply) => void
+  readonly cancelEdit: () => void
+  readonly updateField: (field: QuickReplyFormField, value: string) => void
+  readonly fieldErrors: QuickRepliesWorkspaceFieldErrors
+  readonly isSaving: boolean
+  readonly saveError: string | undefined
+  readonly submit: () => Promise<void>
+  readonly remove: (id: string) => Promise<void>
+  /** Excluindo agora — para o botão da linha mostrar o spinner certo (QR-47). */
+  readonly deletingId: string | undefined
+  /** Sem `uploadQuickReplyAttachment`, a seção de anexos não aparece no formulário (QR-31). */
+  readonly hasAttachmentsCapability: boolean
+  readonly pendingUploads: readonly PendingAttachmentUpload[]
+  readonly addAttachmentFiles: (files: FileList | readonly File[]) => void
+  readonly retryAttachmentUpload: (localId: string) => void
+  readonly cancelAttachmentUpload: (localId: string) => void
+  readonly removeAttachment: (uploadId: string) => void
+  readonly moveAttachmentAt: (index: number, direction: -1 | 1) => void
+  readonly attachmentRejections: readonly AttachmentFileRejection[]
+  readonly dismissAttachmentRejections: () => void
+}
+
+/** Estado da tela de cadastro: lista, busca, formulário de criação/edição, anexos e exclusão. */
+export function useQuickRepliesWorkspace({
+  api,
+  labels,
+  attachmentSizeLimits,
+}: UseQuickRepliesWorkspaceParams): UseQuickRepliesWorkspaceResult {
+  const [quickReplies, setQuickReplies] = useState<QuickReply[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+  const [loadError, setLoadError] = useState<string | undefined>(undefined)
+  const [search, setSearch] = useState('')
+  const [editing, setEditing] = useState<QuickRepliesWorkspaceEditing | undefined>(undefined)
+  const [fieldErrors, setFieldErrors] = useState<QuickRepliesWorkspaceFieldErrors>({})
+  const [isSaving, setIsSaving] = useState(false)
+  const [saveError, setSaveError] = useState<string | undefined>(undefined)
+  const [deletingId, setDeletingId] = useState<string | undefined>(undefined)
+
+  const uploadAttachment = useCallback((attachment: QuickReplyAttachment): void => {
+    setEditing((current) => (current ? { ...current, attachments: [...current.attachments, attachment] } : current))
+  }, [])
+
+  const {
+    pendingUploads,
+    attachmentRejections,
+    addAttachmentFiles,
+    retryAttachmentUpload,
+    cancelAttachmentUpload,
+    dismissAttachmentRejections,
+    abortAllUploads,
+  } = useQuickReplyAttachmentUploads({
+    ...(api.uploadQuickReplyAttachment ? { upload: api.uploadQuickReplyAttachment } : {}),
+    labels,
+    ...(attachmentSizeLimits ? { attachmentSizeLimits } : {}),
+    attachmentsCount: editing?.attachments.length ?? 0,
+    onUploaded: uploadAttachment,
+  })
+
+  useEffect(() => {
+    if (!api.listQuickReplies) return
+    let cancelled = false
+    setIsLoading(true)
+    setLoadError(undefined)
+    api
+      .listQuickReplies()
+      .then((result) => {
+        if (!cancelled) setQuickReplies(result)
+      })
+      .catch((caught: unknown) => {
+        if (!cancelled) setLoadError(caught instanceof Error ? caught.message : labels.failure)
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [api.listQuickReplies])
+
+  const filtered = filterQuickReplies({ quickReplies, search })
+
+  const startCreate = useCallback(() => {
+    abortAllUploads()
+    dismissAttachmentRejections()
+    setEditing({ id: null, title: '', shortcut: '', body: '', attachments: [] })
+    setFieldErrors({})
+    setSaveError(undefined)
+  }, [abortAllUploads, dismissAttachmentRejections])
+
+  const startEdit = useCallback(
+    (quickReply: QuickReply) => {
+      abortAllUploads()
+      dismissAttachmentRejections()
+      setEditing({
+        id: quickReply.id,
+        title: quickReply.title,
+        shortcut: quickReply.shortcut,
+        body: quickReply.body,
+        attachments: quickReply.attachments ?? [],
+      })
+      setFieldErrors({})
+      setSaveError(undefined)
+    },
+    [abortAllUploads, dismissAttachmentRejections],
+  )
+
+  const cancelEdit = useCallback(() => {
+    abortAllUploads()
+    dismissAttachmentRejections()
+    setEditing(undefined)
+    setFieldErrors({})
+    setSaveError(undefined)
+  }, [abortAllUploads, dismissAttachmentRejections])
+
+  const updateField = useCallback((field: QuickReplyFormField, value: string) => {
+    setEditing((current) => (current ? { ...current, [field]: value } : current))
+    // Editar o campo limpa o erro dele — a mensagem antiga não deve sobreviver à correção.
+    setFieldErrors((current) => {
+      if (!(field in current)) return current
+      const next = { ...current }
+      delete next[field]
+      return next
+    })
+  }, [])
+
+  const submit = useCallback(async () => {
+    // Rede de segurança: o botão já fica desabilitado com upload em voo (QR-47), mas salvar antes
+    // da resposta chegar mandaria a mensagem sem o anexo que o operador acabou de anexar.
+    if (!editing || pendingUploads.length > 0) return
+    setIsSaving(true)
+    setSaveError(undefined)
+    setFieldErrors({})
+    const result = await submitQuickReply({ api, editing, labels })
+    setIsSaving(false)
+    if (result.outcome === 'saved') {
+      setQuickReplies((current) =>
+        editing.id === null
+          ? [result.quickReply, ...current]
+          : current.map((item) => (item.id === result.quickReply.id ? result.quickReply : item)),
+      )
+      setEditing(undefined)
+      return
+    }
+    setFieldErrors(result.fieldErrors)
+    if (result.outcome === 'rejected') setSaveError(result.formError)
+  }, [editing, api, labels, pendingUploads.length])
+
+  const remove = useCallback(
+    async (id: string) => {
+      if (!api.deleteQuickReply) return
+      setDeletingId(id)
+      try {
+        await api.deleteQuickReply(id)
+        setQuickReplies((current) => current.filter((item) => item.id !== id))
+      } finally {
+        setDeletingId(undefined)
+      }
+    },
+    [api],
+  )
+
+  const removeAttachment = useCallback((uploadId: string) => {
+    setEditing((current) =>
+      current
+        ? { ...current, attachments: current.attachments.filter((attachment) => attachment.uploadId !== uploadId) }
+        : current,
+    )
+  }, [])
+
+  const moveAttachmentAt = useCallback((index: number, direction: -1 | 1) => {
+    setEditing((current) =>
+      current ? { ...current, attachments: moveAttachment(current.attachments, index, direction) } : current,
+    )
+  }, [])
+
+  return {
+    quickReplies,
+    filtered,
+    isLoading,
+    loadError,
+    search,
+    setSearch,
+    readOnly: !api.createQuickReply,
+    canEdit: Boolean(api.updateQuickReply),
+    canDelete: Boolean(api.deleteQuickReply),
+    editing,
+    startCreate,
+    startEdit,
+    cancelEdit,
+    updateField,
+    fieldErrors,
+    isSaving,
+    saveError,
+    submit,
+    remove,
+    deletingId,
+    hasAttachmentsCapability: Boolean(api.uploadQuickReplyAttachment),
+    pendingUploads,
+    addAttachmentFiles,
+    retryAttachmentUpload,
+    cancelAttachmentUpload,
+    removeAttachment,
+    moveAttachmentAt,
+    attachmentRejections,
+    dismissAttachmentRejections,
+  }
+}