TMF
Repositories
2
 Projects
2
 Packages
185

@tmf/service-desk-front (9.20.0)

Published 2026-11-04 18:44:55 -03:00 by tarcisio

Installation

@tmf:registry=
npm install @tmf/service-desk-front@9.20.0
"@tmf/service-desk-front": "9.20.0"

About this package

@tmf/service-desk-front

UI React do módulo Service Desk da plataforma TMF (atendimento, tickets, kanban/lista/chat, comentários, anexos, respostas prontas, fluxos/bot, métricas, inbox e configurações). Segue o Modelo A dos pacotes de plataforma: componentes desacoplados que recebem o contrato canônico (AppContract do @tmf/platform-core) + um SDApiClient. Adoção por configuração, não por código — o produto host (Hub, TMF9) só instala o pacote, fornece o contrato/cliente e renderiza <ServiceDeskApp>. A regra de negócio e os dados vivem no backend montado no host (tmf-service-desk-back, rotas /api/service/* e /api/service-desk/*; ver ../back/INTEGRATION.md).

Versão: fonte única é o package.json (e o export PACKAGE_VERSION). Não escreva a versão à mão aqui.

1. Pré-requisitos

O pacote empacota @tmf/platform-core e @tmf/flow-ui no próprio bundle (tsup noExternal) — o consumidor não os instala. Peer dependencies reais (package.json):

peer versão observação
react / react-dom >=18.0.0 obrigatório (singleton)
@tiptap/react, @tiptap/starter-kit, @tiptap/pm, @tiptap/extension-mention, @tiptap/extension-image >=3.0.0 editor do composer; o host também declara @tiptap/suggestion (v3) — ver INTEGRATION.md §2

@tanstack/react-query, @xyflow/react, dompurify, lucide-react e sonner são dependencies normais (o npm as instala junto). Se usar o editor de fluxos, importar @xyflow/react/dist/style.css.

2. Registry + instalação

O pacote é publicado no registry npm do Forgejo da TMF. No frontend do host, garanta o .npmrc:

# frontend/.npmrc
@tmf:registry=https://git.trademarketingforce.com/api/packages/TMF/npm/
legacy-peer-deps=true

Auth para instalar (NUNCA commitar o token — use env/CI):

//git.trademarketingforce.com/api/packages/TMF/npm/:_authToken=${FORGEJO_NPM_TOKEN}

Instalar (o pacote + os peers do tiptap):

npm i @tmf/service-desk-front
# peers do editor (tiptap v3) + @tiptap/suggestion — ver INTEGRATION.md §2

3. Como alcança o backend

O Service Desk roda no host, montado em memória a partir do tmf-service-desk-back. O front consome os endpoints /api/service/* (tickets e vizinhos) — mais rotas em /api/service-desk/* (ex.: mailboxes, import jobs) e outras famílias na raiz /api. Cada família traz o próprio prefixo: ../back/INTEGRATION.md §4.4.

host frontend ─► <baseUrl>/api/service/*   (createHttpClient do @tmf/platform-core)
                       │  injeta Authorization (Bearer via getToken) + X-Client-Code (multi-tenant)
                       ▼
                 host /api/service/*  (escopo do cliente → isolamento por tenant)
  • O baseUrl e o token vêm do AppContract + getToken, ambos resolvidos pelo ServiceDeskProvider/ModuleProvider do @tmf/platform-core. O client default (createDefaultServiceDeskClient; createHubServiceDeskClient é alias @deprecated) lê contract.services[key="service-desk"].baseUrl (fallback /api/service) e injeta X-Client-Code quando contract.tenant.isMultiTenant.
  • O baseUrl é o prefixo onde a API responde naquele host (direto ou atrás de proxy); o pacote é o mesmo — só muda o contrato. Modo plug-and-play sem AppContract: INTEGRATION.md §4 (Modo 1).
import { useAppContract } from '@tmf/platform-core'
import { ServiceDeskApp, createDefaultServiceDeskClient } from '@tmf/service-desk-front'

export function ServiceDeskPage() {
  const { contract, loading } = useAppContract({
    baseUrl: window.location.origin,
    getToken: () => getAccessToken() ?? '',
  })
  if (loading || !contract) return <Loader />

  return (
    <ServiceDeskApp
      contract={contract}
      apiClient={createDefaultServiceDeskClient(contract, () => getAccessToken() ?? '')}
      tenantMode="multi"                                  // ou "single"
      getToken={() => getAccessToken() ?? ''}
      sections={['metricas', 'inbox', 'flows', 'settings', 'respostas']}
    />
  )
}

Pré-requisitos no app host:

  • Não é preciso QueryClientProvider: o Provider monta um interno (prop queryClient para compartilhar o do host).
  • Se usar o editor de fluxos, importar import '@xyflow/react/dist/style.css'.

4. Adapter próprio (opcional)

O host pode mapear para a própria camada de API implementando a interface SDApiClient e injetando via prop apiClient (ou client no ServiceDeskProvider):

import type { SDApiClient } from '@tmf/service-desk-front'

const myClient: SDApiClient = {
  listTickets: (p) => myApi.tickets.list(p),
  getTicket:   (id) => myApi.tickets.get(id),
  // … apenas os métodos que o produto usa
}

<ServiceDeskApp contract={contract} apiClient={myClient} tenantMode="single" />

5. Componentes exportados

  • Top-level: ServiceDeskApp, ServiceDeskProvider, useServiceDeskContext, useSDUI, useSDToast
  • Vistas de atendimento (complex): ServiceDeskList, ServiceDeskKanban, ServiceDeskChat, TicketDetailModal, TicketTimeline, AttachmentList, TicketKBPanel
  • Composição: TicketComposer, TicketSidebar, ViewModeToggle, SLACard, ImageLightbox
  • Visão de agente: AgentStatusTabBar, AgentPriorityFilter, AgentChannelFilter, AgentKanbanCard, AgentSLABadge, SDMetricsDashboard, SDCannedResponseManager
  • Seções: SDChannelsConfig, SDImportJobs, SDExportPanel
  • Configurações: SDSettingsPanel, CategoriesSettings, TagsSettings, ReasonsSettings, PersonSourcesSettings, createDefaultSDSettingsGroups
  • Fluxos: ServiceFlows, ServiceFlowEditor, FlowCanvas, FlowNodePalette, FlowToolbar, FlowPropertiesPanel, FlowTestPanel, nós (TriggerNode, AIAnalysisNode, ConditionNode, ResponseNode, ActionNode, WaitNode, HandoffNode, BusinessHoursNode, EndNode)
    • Somente leitura (TMFP-70362): <ServiceFlowEditor readOnly /> e <ServiceFlows readOnly /> (padrão false). O editor esconde Testar/Salvar/Publicar/Despublicar e a paleta, trava nome, cliente, canvas (sem arrastar/conectar/apagar) e os campos do painel; a lista esconde criar/duplicar/excluir e mantém abrir. É só UX: o 403 do backend continua sendo a barreira.
  • Infra: createDefaultServiceDeskClient (+ alias createHubServiceDeskClient), useServiceDeskRealtime, patchTicketCache, sdQueryKeys, useSDI18n, getSdCatalog, defaultSDUIPrimitives, mergeSDUI, constantes SD_* e tipos SD*

Detalhe de cada área em FUNCIONALIDADES.md.

6. Checklist de adoção

  1. .npmrc com registry Forgejo + legacy-peer-deps=true.
  2. npm i @tmf/service-desk-front + peers do tiptap v3 e @tiptap/suggestion (§1).
  3. baseUrl do serviço service-desk no contrato apontando para onde o back montado responde.
  4. Se usar fluxos, importar @xyflow/react/dist/style.css. O ServiceDeskProvider já traz um QueryClientProvider interno (prop queryClient para compartilhar cache).
  5. Renderizar <ServiceDeskApp contract apiClient tenantMode getToken sections />.
  6. Validar tsc --noEmit + smoke (listar/abrir/criar ticket, comentar, métricas) no QA do host.

Dúvidas de contrato/escopo: ../back/INTEGRATION.md (§4 montagem e §5.1 eixo de escopo).

Dependencies

Dependencies

ID Version
@tanstack/react-query ^5.0.0
@xyflow/react ^12.0.0
dompurify ^3.0.0
lucide-react ^0.400.0
sonner ^1.0.0

Development dependencies

ID Version
@tiptap/extension-image ^3.29.1
@tiptap/extension-mention ^3.27.3
@tiptap/pm ^3.27.3
@tiptap/react ^3.27.3
@tiptap/starter-kit ^3.27.3
@tmf/flow-ui file:../../flow-ui
@tmf/platform-core file:../../platform-core
@types/dompurify ^3.0.5
@types/react ^18.2.47
@types/react-dom ^18.2.18
tsup ^8.5.1
typescript ^5.3.3

Peer dependencies

ID Version
@tiptap/extension-image >=3.0.0
@tiptap/extension-mention >=3.0.0
@tiptap/pm >=3.0.0
@tiptap/react >=3.0.0
@tiptap/starter-kit >=3.0.0
@tmf/design-tokens >=0.6.0
react >=18.0.0
react-dom >=18.0.0

Keywords

tmf service-desk react components plug-and-play
Details
npm
2026-11-04 18:44:55 -03:00
0
Trade Marketing Force LTDA
UNLICENSED
1.8 MiB
Assets (1)
service-desk-front-9.20.0.tgz 1.8 MiB
Versions (102) View all
9.21.0 2026-11-04
9.20.0 2026-11-04
9.16.0 2026-11-04
9.15.0 2026-11-04
9.12.0 2026-11-03