TMF
Repositories
2
 Projects
2
 Packages
109

@tmf/service-desk-front (8.7.0)

Published 2026-09-05 14:47:43 -03:00 by tarcisio

Installation

@tmf:registry=
npm install @tmf/service-desk-front@8.7.0
"@tmf/service-desk-front": "8.7.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 Hub (backend /api/service/*).

Versão atual: 1.0.3 (dist-tag latest).

1. Pré-requisitos

O pacote NÃO embute as libs pesadas — todas são peerDependencies fornecidas pelo host:

peer versão observação
react / react-dom >=18 obrigatório
@tmf/platform-core >=1.0.0 <2 contrato AppContract, ModuleProvider, HttpClient, ports — obrigatório
@tmf/flow-ui >=0.1.0 primitivas base do editor de fluxo (BaseFlowNode/TriggerNode/EndNode…) — obrigatório
@tanstack/react-query >=5 data fetching dos componentes complex/agent/settings
lucide-react >=0.400 ícones
dompurify >=3 sanitização de HTML de e-mail/comentário
react-i18next >=14 i18n — optional (há DictI18nPort embutido)
sonner >=1 toasts — optional (ou injete um ToastPort próprio)
@xyflow/react >=12 canvas do editor de fluxos (reactflow v12) — optional

⚠️ As peerDeps obrigatórias @tmf/platform-core (>=1.0.0 <2) e @tmf/flow-ui o consumidor DEVE instalar — sem elas o build/typecheck (tsc --noEmit) quebra, pois o pacote importa tipos e símbolos diretamente desses pacotes (ex.: AppContract, ModuleProvider, createHttpClient, nós de fluxo).

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 + as peerDeps obrigatórias):

npm i @tmf/service-desk-front
# peerDeps obrigatórias — o build/typecheck do consumidor quebra sem elas:
npm i @tmf/platform-core @tmf/flow-ui

3. Como alcança o backend (S2S via /api/service/* do Hub)

O Service Desk roda no Hub. O host consome os endpoints /api/service/* (tickets, comentários, anexos, KB, motivos, respostas prontas) — mais alguns vizinhos em /api/service-desk/* (export SAC, classificador de motivo por IA) e na raiz /api (mailboxes, wa-channels, vínculo de cliente).

host frontend ─► <baseUrl>/api/service/*   (createHttpClient do @tmf/platform-core)
                       │  injeta Authorization (Bearer via getToken) + X-Client-Code (multi-tenant)
                       ▼
                 Hub /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 (createHubServiceDeskClient) lê contract.services[key="service-desk"].baseUrl (fallback /api/service) e injeta X-Client-Code quando contract.tenant.isMultiTenant.
  • No TMF9 o baseUrl aponta para o proxy do Hub (/api/v1/hub/proxy/service); no Hub aponta direto para /api/service. Em ambos os casos o pacote é o mesmo — só muda o contrato.
import { useAppContract } from '@tmf/platform-core'
import { ServiceDeskApp, createHubServiceDeskClient } 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={createHubServiceDeskClient(contract, () => getAccessToken() ?? '')}
      tenantMode="multi"                                  // Hub multi-tenant; TMF9 usa "single"
      getToken={() => getAccessToken() ?? ''}
      sections={['metricas', 'inbox', 'flows', 'settings', 'respostas']}
    />
  )
}

Pré-requisitos no app host:

  • Envolver a árvore num QueryClientProvider (@tanstack/react-query).
  • 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, SDInboxTable, SDCannedResponseManager
  • Seções: SDChannelsConfig, SDTemplatesManager, 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, EndNode)
  • Infra: createHubServiceDeskClient, 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 @tmf/platform-core @tmf/flow-ui (peerDeps obrigatórias).
  3. Demais peers conforme uso: @tanstack/react-query, lucide-react, dompurify e, se aplicável, react-i18next, sonner, @xyflow/react.
  4. baseUrl do serviço service-desk no contrato apontando para o Hub (direto ou via proxy TMF9).
  5. Envolver a rota num QueryClientProvider; se usar fluxos, importar @xyflow/react/dist/style.css.
  6. Renderizar <ServiceDeskApp contract apiClient tenantMode getToken sections />.
  7. Validar tsc --noEmit + smoke (listar/abrir/criar ticket, comentar, métricas) contra o Hub QA.

Dúvidas de contrato/escopo: ver o backend app/routers/service/* no repo tmf-management.

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
react >=18.0.0
react-dom >=18.0.0

Keywords

tmf service-desk react components plug-and-play
Details
npm
2026-09-05 14:47:43 -03:00
27
Trade Marketing Force LTDA
UNLICENSED
latest
1.4 MiB
Assets (1)
service-desk-front-8.7.0.tgz 1.4 MiB
Versions (69) View all
8.7.0 2026-09-05
8.6.1 2026-09-03
8.5.0 2026-09-01
8.4.1 2026-08-26
8.4.0 2026-08-23