@tmf/service-desk-front (6.7.0)

Published 2026-08-03 17:49:58 -03:00 by tarcisio

Setup this registry in your project .npmrc file:

@tmf:registry=

To install the package using npm, run the following command:

npm install @tmf/service-desk-front@6.7.0

or add it to the package.json file:

"@tmf/service-desk-front": "6.7.0"

For more information on the npm registry, see the documentation.

@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, AISuggestionsPanel
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

.npmrc com registry Forgejo + legacy-peer-deps=true.
npm i @tmf/service-desk-front @tmf/platform-core @tmf/flow-ui (peerDeps obrigatórias).
Demais peers conforme uso: @tanstack/react-query, lucide-react, dompurify e, se aplicável, react-i18next, sonner, @xyflow/react.
baseUrl do serviço service-desk no contrato apontando para o Hub (direto ou via proxy TMF9).
Envolver a rota num QueryClientProvider; se usar fluxos, importar @xyflow/react/dist/style.css.
Renderizar <ServiceDeskApp contract apiClient tenantMode getToken sections />.
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

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

tmf service-desk react components plug-and-play

Details

npm

2026-08-03 17:49:58 -03:00

Trade Marketing Force LTDA

UNLICENSED

1.5 MiB

Assets (1)

service-desk-front-6.7.0.tgz 1.5 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

@tmf/service-desk-front (6.7.0)

Installation

About this package

@tmf/service-desk-front

1. Pré-requisitos

2. Registry + instalação

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

4. Adapter próprio (opcional)

5. Componentes exportados

6. Checklist de adoção

Dependencies

Keywords

@tmf/service-desk-front (6.7.0)

Installation

About this package

@tmf/service-desk-front

1. Pré-requisitos

2. Registry + instalação

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

4. Adapter próprio (opcional)

5. Componentes exportados

6. Checklist de adoção

Dependencies

Keywords

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