@adatechnology/conversations-ui 0.1.1 → 0.2.0

package/src/quickReplies/createUploadQueue.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'bun:test'
+
+import { createUploadQueue } from './createUploadQueue'
+
+function deferred<T = void>(): { promise: Promise<T>; resolve: (value: T) => void } {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((res) => {
+    resolve = res
+  })
+  return { promise, resolve }
+}
+
+describe('createUploadQueue', () => {
+  it('nunca roda mais que o limite ao mesmo tempo, para 10 itens', async () => {
+    const queue = createUploadQueue(3)
+    let active = 0
+    let maxActive = 0
+    const gates = Array.from({ length: 10 }, () => deferred())
+
+    for (let index = 0; index < 10; index += 1) {
+      queue.enqueue(`item-${index}`, async () => {
+        active += 1
+        maxActive = Math.max(maxActive, active)
+        await gates[index]?.promise
+        active -= 1
+      })
+    }
+
+    expect(active).toBe(3)
+    for (const gate of gates) gate.resolve()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(maxActive).toBeLessThanOrEqual(3)
+    expect(active).toBe(0)
+  })
+
+  it('um retry enfileirado com a fila cheia espera vaga', async () => {
+    const queue = createUploadQueue(3)
+    const gates = Array.from({ length: 3 }, () => deferred())
+    for (let index = 0; index < 3; index += 1) {
+      queue.enqueue(`initial-${index}`, async () => {
+        await gates[index]?.promise
+      })
+    }
+
+    let retryStarted = false
+    queue.enqueue('retry-item', async () => {
+      retryStarted = true
+    })
+
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(retryStarted).toBe(false)
+
+    gates[0]?.resolve()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(retryStarted).toBe(true)
+  })
+
+  it('abortar um item ainda pendente remove da fila sem rodar', async () => {
+    const queue = createUploadQueue(1)
+    const blocking = deferred()
+    queue.enqueue('blocking', async () => {
+      await blocking.promise
+    })
+
+    let queuedRan = false
+    queue.enqueue('queued', async () => {
+      queuedRan = true
+    })
+    queue.abort('queued')
+
+    blocking.resolve()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(queuedRan).toBe(false)
+  })
+
+  it('abortar um item ativo libera a vaga para o próximo', async () => {
+    const queue = createUploadQueue(1)
+    let activeAborted = false
+    queue.enqueue('active', async (signal) => {
+      await new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => {
+          activeAborted = true
+          resolve()
+        })
+      })
+    })
+
+    let nextRan = false
+    queue.enqueue('next', async () => {
+      nextRan = true
+    })
+
+    queue.abort('active')
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    expect(activeAborted).toBe(true)
+    expect(nextRan).toBe(true)
+  })
+})

package/src/quickReplies/createUploadQueue.ts

@@ -0,0 +1,69 @@
+/**
+ * Fila de upload compartilhada (M1): no máximo `maxConcurrent` itens em voo ao mesmo tempo,
+ * qualquer que seja a sequência de chamadas que os enfileirou (anexar novo arquivo, repetir um
+ * que falhou). Sem isto, `addAttachmentFiles` e `retryAttachmentUpload` cada um abria sua própria
+ * janela de concorrência, e a soma das duas podia passar de 3 uploads simultâneos.
+ */
+
+export type UploadQueueRunner = (signal: AbortSignal) => Promise<void>
+
+export type UploadQueueHandle = {
+  /** Enfileira `id`; começa a rodar assim que houver vaga. Reenfileirar um `id` já pendente ou
+   * ativo substitui o worker anterior por este. */
+  readonly enqueue: (id: string, run: UploadQueueRunner) => void
+  /** Aborta `id`: se estiver ativo, aborta o `AbortSignal` dele; se só estiver pendente, remove
+   * da fila sem nunca chegar a rodar. */
+  readonly abort: (id: string) => void
+  /** Aborta tudo — ativo e pendente — e esvazia a fila. */
+  readonly abortAll: () => void
+}
+
+export function createUploadQueue(maxConcurrent: number): UploadQueueHandle {
+  const pending: string[] = []
+  const runners = new Map<string, UploadQueueRunner>()
+  const controllers = new Map<string, AbortController>()
+  let activeCount = 0
+
+  function pump(): void {
+    while (activeCount < maxConcurrent && pending.length > 0) {
+      const id = pending.shift() as string
+      const run = runners.get(id)
+      runners.delete(id)
+      if (!run) continue
+      const controller = new AbortController()
+      controllers.set(id, controller)
+      activeCount += 1
+      void run(controller.signal).finally(() => {
+        controllers.delete(id)
+        activeCount -= 1
+        pump()
+      })
+    }
+  }
+
+  function enqueue(id: string, run: UploadQueueRunner): void {
+    if (controllers.has(id)) return
+    runners.set(id, run)
+    if (!pending.includes(id)) pending.push(id)
+    pump()
+  }
+
+  function abort(id: string): void {
+    const controller = controllers.get(id)
+    if (controller) {
+      controller.abort()
+      return
+    }
+    const index = pending.indexOf(id)
+    if (index >= 0) pending.splice(index, 1)
+    runners.delete(id)
+  }
+
+  function abortAll(): void {
+    for (const controller of controllers.values()) controller.abort()
+    pending.length = 0
+    runners.clear()
+  }
+
+  return { enqueue, abort, abortAll }
+}

package/src/quickReplies/index.ts

@@ -0,0 +1,5 @@
+export { QuickRepliesWorkspace } from './QuickRepliesWorkspace'
+export type { QuickRepliesWorkspaceProps } from './QuickRepliesWorkspace'
+export { QuickRepliesPicker } from './QuickRepliesPicker'
+export type { QuickRepliesPickerProps } from './QuickRepliesPicker'
+export type { QuickRepliesWorkspaceLabels, QuickRepliesPickerLabels } from './labels'

package/src/quickReplies/labels.ts

@@ -0,0 +1,124 @@
+/**
+ * Vocabulário das telas de mensagens prontas. Sobrescrevível campo a campo — mesma convenção de
+ * `documents/labels.ts` e `workspace/labels.ts`.
+ */
+
+export interface QuickRepliesPickerLabels {
+  readonly loading: string
+  readonly error: string
+  readonly empty: string
+  readonly noResults: string
+  /** Contagem ao lado do clipe na linha (QR-32): "2 anexos". */
+  readonly attachmentsCount: (count: number) => string
+  /** Mostrado na linha quando a mensagem tem anexo, mas o produto não sabe mandá-lo (QR-33). */
+  readonly attachmentsUnavailable: string
+}
+
+export const DEFAULT_QUICK_REPLIES_PICKER_LABELS: QuickRepliesPickerLabels = {
+  loading: 'Carregando mensagens prontas…',
+  error: 'Não foi possível carregar as mensagens prontas.',
+  empty: 'Nenhuma mensagem pronta cadastrada ainda.',
+  noResults: 'Nenhuma mensagem encontrada.',
+  attachmentsCount: (count) => `${count} ${count === 1 ? 'anexo' : 'anexos'}`,
+  attachmentsUnavailable: 'Este produto não envia os anexos desta mensagem — só o texto entra.',
+}
+
+export interface QuickRepliesWorkspaceLabels {
+  readonly title: string
+  readonly subtitle: (total: number) => string
+  readonly searchPlaceholder: string
+  readonly loading: string
+  readonly failure: string
+  readonly empty: string
+  readonly noResults: string
+  readonly create: string
+  readonly edit: string
+  readonly remove: string
+  readonly removeConfirm: (title: string) => string
+  readonly save: string
+  readonly cancel: string
+  readonly columnTitle: string
+  readonly columnShortcut: string
+  readonly columnBody: string
+  readonly columnActions: string
+  readonly fieldTitle: string
+  readonly fieldTitleInvalid: string
+  readonly fieldShortcut: string
+  readonly fieldShortcutHint: string
+  readonly fieldShortcutInvalid: string
+  readonly fieldBody: string
+  readonly fieldBodyInvalid: string
+  readonly insertVariable: string
+  readonly shortcutTaken: string
+  readonly readOnlyNotice: string
+  readonly saveError: string
+  /** Sem `createQuickReply`/`updateQuickReply` na porta — a tela não deveria nem oferecer o botão,
+   * mas o formulário ainda precisa de um texto caso chame `submit` de outro jeito. */
+  readonly saveUnavailable: string
+  readonly saving: string
+  readonly deleting: string
+  /** Seção de anexos (QR-31) — só aparece com `uploadQuickReplyAttachment` na porta. */
+  readonly attachmentsTitle: string
+  readonly attachmentsAdd: string
+  readonly attachmentsEmpty: string
+  readonly attachmentUploading: (percent: number) => string
+  /** @deprecated Sem uso: não existe um "processando" observável entre a resposta do upload e o
+   * item entrar em `editing.attachments` — as duas atualizações de estado acontecem no mesmo
+   * commit do React. Mantido no tipo só para não quebrar quem já customiza este campo. */
+  readonly attachmentProcessing: string
+  readonly attachmentRetry: string
+  readonly attachmentRemove: string
+  readonly attachmentCancel: string
+  readonly attachmentMoveUp: string
+  readonly attachmentMoveDown: string
+  readonly attachmentLimitReached: string
+  readonly attachmentTooLarge: (filename: string) => string
+  readonly saveBlockedUploading: string
+}
+
+export const DEFAULT_QUICK_REPLIES_WORKSPACE_LABELS: QuickRepliesWorkspaceLabels = {
+  title: 'Mensagens prontas',
+  subtitle: (total) => `${total} ${total === 1 ? 'mensagem cadastrada' : 'mensagens cadastradas'}`,
+  searchPlaceholder: 'Buscar por título, atalho ou texto',
+  loading: 'Carregando mensagens prontas…',
+  failure: 'Não foi possível carregar as mensagens prontas.',
+  empty: 'Nenhuma mensagem pronta cadastrada ainda.',
+  noResults: 'Nenhuma mensagem encontrada para a busca.',
+  create: 'Nova mensagem',
+  edit: 'Editar',
+  remove: 'Excluir',
+  removeConfirm: (title) => `Excluir a mensagem "${title}"?`,
+  save: 'Salvar',
+  cancel: 'Cancelar',
+  columnTitle: 'Título',
+  columnShortcut: 'Atalho',
+  columnBody: 'Texto',
+  columnActions: 'Ações',
+  fieldTitle: 'Título',
+  fieldTitleInvalid: 'Digite um título de até 40 caracteres.',
+  fieldShortcut: 'Atalho',
+  fieldShortcutHint: 'Letras minúsculas, números e hífen, sem espaço nem acento.',
+  fieldShortcutInvalid: 'Atalho inválido — só letras minúsculas, números e hífen, até 20 caracteres.',
+  fieldBody: 'Texto',
+  fieldBodyInvalid: 'Digite um texto de até 1000 caracteres.',
+  insertVariable: 'Inserir variável',
+  shortcutTaken: 'Esse atalho já está em uso — escolha outro.',
+  readOnlyNotice: 'Você só pode consultar as mensagens prontas.',
+  saveError: 'Não foi possível salvar a mensagem.',
+  saveUnavailable: 'Salvar mensagens prontas não está disponível.',
+  saving: 'Salvando…',
+  deleting: 'Excluindo…',
+  attachmentsTitle: 'Anexos',
+  attachmentsAdd: 'Adicionar anexo',
+  attachmentsEmpty: 'Nenhum anexo — até 10 arquivos.',
+  attachmentUploading: (percent) => `Enviando… ${percent}%`,
+  attachmentProcessing: 'Processando…',
+  attachmentRetry: 'Tentar de novo',
+  attachmentRemove: 'Remover anexo',
+  attachmentCancel: 'Cancelar envio',
+  attachmentMoveUp: 'Mover para cima',
+  attachmentMoveDown: 'Mover para baixo',
+  attachmentLimitReached: 'Limite de 10 anexos por mensagem.',
+  attachmentTooLarge: (filename) => `${filename}: excede o tamanho máximo para o tipo de arquivo.`,
+  saveBlockedUploading: 'Aguardando o envio dos anexos…',
+}

package/src/quickReplies/quickReply.types.ts

@@ -0,0 +1,74 @@
+/**
+ * Mensagem pronta cadastrada pelo produto e oferecida no composer.
+ *
+ * Difere do `QuickReply` dos chips (`MessageComposer`): aquela vive em código no host; esta vem da
+ * API, tem atalho para o `/` e é editada pela tela de cadastro.
+ */
+export type QuickReply = {
+  readonly id: string
+  /** Até 40 caracteres — é o que o atendente lê na lista. */
+  readonly title: string
+  /** Casa `^[a-z0-9-]{1,20}$`: é digitado depois do `/`, sem acento nem espaço. */
+  readonly shortcut: string
+  /** Até 1000 caracteres, com `{{marcador}}` onde entra o dado da conversa. */
+  readonly body: string
+  /** Ausente em host sem anexos: o contrato continua o mesmo para quem não os oferece. */
+  readonly attachments?: readonly QuickReplyAttachment[]
+}
+
+/** Teto de anexos por mensagem pronta — o mesmo que a API aplica, para a tela recusar antes. */
+export const QUICK_REPLY_ATTACHMENT_LIMIT = 10
+
+/** Arquivo já guardado pelo host; o `uploadId` é a única chave que o pacote devolve ao servidor. */
+export type QuickReplyAttachment = {
+  readonly uploadId: string
+  readonly filename: string
+  readonly mimeType: string
+  readonly sizeBytes: number
+}
+
+/**
+ * Item da fila do composer. `local` ainda não subiu (veio do clipe); `stored` já está no servidor
+ * (veio de uma mensagem pronta) e é enviado por referência, sem baixar e subir de novo.
+ */
+export type QueuedAttachment =
+  | { readonly kind: 'local'; readonly localId: string; readonly file: File }
+  | {
+      readonly kind: 'stored'
+      readonly uploadId: string
+      readonly filename: string
+      readonly mimeType: string
+      readonly sizeBytes: number
+      /** Carregada sob demanda só para imagem — a lista não pode abrir N URLs assinadas de uma vez. */
+      readonly previewUrl?: string
+    }
+
+/** Resultado por arquivo: o envio em lote falha parcialmente, e só o que falhou fica na fila. */
+export type StoredAttachmentSendResult = {
+  readonly uploadId: string
+  readonly status: 'sent' | 'failed' | 'skipped'
+  readonly errorCode?: string
+}
+
+/** O que a tela de cadastro manda para criar ou atualizar; o `id` é do servidor. */
+export type QuickReplyInput = {
+  readonly title: string
+  readonly shortcut: string
+  readonly body: string
+  /** Ordem do cadastro é a ordem de envio; ausente não mexe nos anexos já gravados. */
+  readonly attachmentUploadIds?: readonly string[]
+}
+
+/**
+ * Dado da conversa que um texto pode citar. Uma lista só alimenta a prévia, a inserção e o botão de
+ * variáveis — antes eram duas props de formato diferente, e as telas divergiam por isso.
+ */
+export type ConversationVariable = {
+  readonly id: string
+  /** Rótulo do botão "Inserir variável" (ex.: "Nome do cliente"). */
+  readonly label: string
+  /** Como aparece no texto: `{{nome}}`. */
+  readonly marker: string
+  /** Vazio quando a conversa não tem o dado: a variável não é oferecida. */
+  readonly value: string
+}

package/src/quickReplies/quickReplyAttachmentUpload.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'bun:test'
+
+import { mapWithConcurrencyLimit, moveAttachment, validateAttachmentFiles } from './quickReplyAttachmentUpload'
+
+function file(name: string, type: string, sizeBytes: number): File {
+  return new File([new Uint8Array(sizeBytes)], name, { type })
+}
+
+describe('validateAttachmentFiles', () => {
+  it('aceita dentro do teto e do tamanho por tipo', () => {
+    const result = validateAttachmentFiles([file('a.png', 'image/png', 10)], 0)
+    expect(result.accepted.map((f) => f.name)).toEqual(['a.png'])
+    expect(result.rejected).toEqual([])
+  })
+
+  it('recusa por tamanho sem subir', () => {
+    const big = file('big.png', 'image/png', 6 * 1024 * 1024)
+    const result = validateAttachmentFiles([big], 0)
+    expect(result.accepted).toEqual([])
+    expect(result.rejected).toEqual([{ file: big, reason: 'size' }])
+  })
+
+  it('recusa a partir do teto de 10, mantendo os anteriores', () => {
+    const files = Array.from({ length: 3 }, (_, index) => file(`f${index}.pdf`, 'application/pdf', 10))
+    const result = validateAttachmentFiles(files, 9)
+    expect(result.accepted.map((f) => f.name)).toEqual(['f0.pdf'])
+    expect(result.rejected.map((r) => r.file.name)).toEqual(['f1.pdf', 'f2.pdf'])
+    expect(result.rejected.every((r) => r.reason === 'limit')).toBe(true)
+  })
+
+  it('aceita limites do host', () => {
+    const result = validateAttachmentFiles([file('a.png', 'image/png', 3)], 0, {
+      document: 1,
+      image: 2,
+      audio: 1,
+      video: 1,
+    })
+    expect(result.rejected).toEqual([{ file: expect.anything(), reason: 'size' }])
+  })
+})
+
+describe('moveAttachment', () => {
+  it('move um item para frente e para trás', () => {
+    expect(moveAttachment(['a', 'b', 'c'], 0, 1)).toEqual(['b', 'a', 'c'])
+    expect(moveAttachment(['a', 'b', 'c'], 2, -1)).toEqual(['a', 'c', 'b'])
+  })
+
+  it('não faz nada nas bordas', () => {
+    expect(moveAttachment(['a', 'b'], 0, -1)).toEqual(['a', 'b'])
+    expect(moveAttachment(['a', 'b'], 1, 1)).toEqual(['a', 'b'])
+  })
+})
+
+describe('mapWithConcurrencyLimit', () => {
+  it('preserva a ordem do resultado mesmo com término fora de ordem', async () => {
+    const order = [30, 10, 20]
+    const result = await mapWithConcurrencyLimit(order, 3, async (delay) => {
+      await new Promise((resolve) => setTimeout(resolve, delay))
+      return delay
+    })
+    expect(result).toEqual([30, 10, 20])
+  })
+
+  it('nunca roda mais que o limite ao mesmo tempo', async () => {
+    let current = 0
+    let max = 0
+    await mapWithConcurrencyLimit([1, 2, 3, 4, 5, 6], 3, async (item) => {
+      current += 1
+      max = Math.max(max, current)
+      await new Promise((resolve) => setTimeout(resolve, 5))
+      current -= 1
+      return item
+    })
+    expect(max).toBeLessThanOrEqual(3)
+  })
+})

package/src/quickReplies/quickReplyAttachmentUpload.ts

@@ -0,0 +1,81 @@
+/**
+ * Funções puras do upload de anexo na tela de cadastro (QR-31): validação antes de subir,
+ * reordenação e o limitador de concorrência. Sem estado de React — testáveis sem montar o hook.
+ */
+
+import { canAddAttachments, resolveMaxAttachmentSizeBytes } from './quickReplyAttachments'
+import type { MaxAttachmentSizeBytes } from './quickReplyAttachments'
+
+export type AttachmentFileRejection = { readonly file: File; readonly reason: 'limit' | 'size' }
+
+export type ValidateAttachmentFilesResult = {
+  readonly accepted: readonly File[]
+  readonly rejected: readonly AttachmentFileRejection[]
+}
+
+/**
+ * Valida o teto de 10 e o tamanho por tipo ANTES de subir (QR-31) — nunca gasta um upload inteiro
+ * num arquivo que já ia ser recusado. Processa em ordem: um arquivo que estoura o teto no meio do
+ * lote não impede os anteriores de entrar, só ele e os que vêm depois.
+ */
+export function validateAttachmentFiles(
+  files: readonly File[],
+  currentCount: number,
+  limits?: MaxAttachmentSizeBytes,
+): ValidateAttachmentFilesResult {
+  const accepted: File[] = []
+  const rejected: AttachmentFileRejection[] = []
+  let count = currentCount
+  for (const file of files) {
+    if (!canAddAttachments(count, 1)) {
+      rejected.push({ file, reason: 'limit' })
+      continue
+    }
+    const maxSize = resolveMaxAttachmentSizeBytes(file.type, limits)
+    if (file.size > maxSize) {
+      rejected.push({ file, reason: 'size' })
+      continue
+    }
+    accepted.push(file)
+    count += 1
+  }
+  return { accepted, rejected }
+}
+
+/** Move um item uma posição — usado pelos botões de reordenar (acessíveis por teclado). Fora da
+ * faixa, devolve a mesma lista em vez de estourar. */
+export function moveAttachment<T>(list: readonly T[], index: number, direction: -1 | 1): readonly T[] {
+  const target = index + direction
+  if (index < 0 || index >= list.length || target < 0 || target >= list.length) return list
+  const next = [...list]
+  const [item] = next.splice(index, 1)
+  next.splice(target, 0, item as T)
+  return next
+}
+
+/**
+ * Roda `worker` sobre `items` com no máximo `limit` em paralelo (QR-31: até 3 uploads ao mesmo
+ * tempo). O resultado preserva a ordem de `items` — a posição *i* é sempre o resultado do item *i*,
+ * mesmo que o item *i+1* termine primeiro.
+ */
+export async function mapWithConcurrencyLimit<TItem, TResult>(
+  items: readonly TItem[],
+  limit: number,
+  worker: (item: TItem, index: number) => Promise<TResult>,
+): Promise<TResult[]> {
+  const results: TResult[] = new Array(items.length)
+  let nextIndex = 0
+
+  async function runNext(): Promise<void> {
+    const index = nextIndex
+    nextIndex += 1
+    if (index >= items.length) return
+    const item = items[index] as TItem
+    results[index] = await worker(item, index)
+    await runNext()
+  }
+
+  const workerCount = Math.max(0, Math.min(limit, items.length))
+  await Promise.all(Array.from({ length: workerCount }, () => runNext()))
+  return results
+}