TMF
Repositories
2
 Projects
2
 Packages
109

@tmf/communication-front (4.1.0)

Published 2026-07-08 15:53:34 -03:00 by tarcisio

Installation

@tmf:registry=
npm install @tmf/communication-front@4.1.0
"@tmf/communication-front": "4.1.0"

About this package

@tmf/communication-front

Front React replicável do módulo de Comunicação da TMF (campanhas de marketing, e-mail, SMS, WhatsApp, push, provedores, financeiro/wallets, bots e o Gestor de Campanhas WhatsApp).

Componentes desacoplados que consomem um contrato (@tmf/platform-core → AppContract)

  • um CommunicationApiClient. Adoção por configuração, não por código — o produto host (Hub/TMF Management, TMF9, DAIS, Priceshow, HelpCor) só instala, fornece o contrato e renderiza. A regra de negócio e os dados vivem no Hub (backend /api/service/communication/*).

Nenhum componente importa nada do Hub: todos consomem useCommunicationContext().client (o CommunicationApiClient) e o pacote não faz chamadas HTTP diretamente — usa createHubCommunicationClient como default.

Versão atual: 1.2.0 (Modelo A — packages/communication/front).

1. Pré-requisitos

O pacote NÃO embute libs pesadas — elas são peerDependencies (o host fornece):

peer versão obrigatória? observação
react / react-dom >=18.0.0 sim —
@tmf/platform-core >=1.0.0 <2 sim contrato (AppContract), HttpClient, ports (ToastPort/I18nPort/ThemePort), ModuleProvider, createDictI18nPort
@tmf/flow-ui >=0.1.0 sim primitivas base do editor de fluxo (BaseFlowNode/TriggerNode/EndNode) reusadas no editor de bots
@tanstack/react-query >=5.0.0 sim data fetching de todos os componentes
lucide-react >=0.400.0 sim ícones
@xyflow/react >=12.0.0 opcional canvas ReactFlow do BotFlowEditor
recharts >=2.0.0 opcional gráficos (financeiro, analytics, wa-manager)
react-i18next >=14.0.0 opcional i18n (ou use o DictI18nPort embutido)
sonner >=1.0.0 opcional toasts (ou injete um ToastPort próprio)

As primitivas de fluxo vêm do pacote-base @tmf/flow-ui — sem acoplamento lateral a outros pacotes de feature.

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:

npm install @tmf/communication-front --legacy-peer-deps

3. Como o host alcança o backend (S2S via /api/service/communication)

A Comunicação roda no Hub. O createHubCommunicationClient aponta para o serviço de chave communication no contrato — default /api/service/communication quando o contrato não declara baseUrl. Em produtos externos (ex.: TMF9) esse caminho é o catch-all proxy do Hub:

host frontend ─► /api/v1/hub/proxy/service/communication/*   (backend do host)
                       │  injeta Authorization (token do Hub) + X-Client-Code
                       ▼
                 Hub /api/service/communication/*   (resolve escopo do cliente)
  • Dual-auth no Hub: JWT do Hub (agente interno = cross-client) OU TenantToken S2S (mst_…, single-client). Via proxy, o host manda o próprio JWT e o proxy injeta a identidade do Hub + X-Client-Code.
  • O client resolve clientCode automaticamente de contract.tenant.clientCode quando contract.tenant.isMultiTenant é verdadeiro (multi-tenant).
  • Isolamento por cliente é garantido no Hub (IDOR → 404). Credenciais de provider nunca trafegam (ProvidersView só exibe nome/canal/status).

4. Acoplamento mínimo ("config, não código")

import { CommunicationApp } from '@tmf/communication-front'

export function CommunicationPage({ contract }: { contract: AppContract }) {
  return (
    <CommunicationApp
      contract={contract}
      tenantMode="multi"           // "multi" no Hub; "single" em tenant isolado (TMF9)
      getToken={() => getAccessToken() ?? ''}
      // sem `client` → usa createHubCommunicationClient default,
      // que chama contract.services['communication'].baseUrl
    />
  )
}

No contrato servido ao host, inclua o endpoint de comunicação:

// AppContract.services[]
{ "key": "communication", "baseUrl": "/api/service/communication" }
// (em produtos externos, aponte para /api/v1/hub/proxy/service/communication)

Pré-requisitos no app:

  • Envolver a árvore num QueryClientProvider (@tanstack/react-query).
  • Se usar o editor de bots, importar import '@xyflow/react/dist/style.css'.

5. Adapter próprio (opcional)

Se o produto preferir mapear para sua própria camada de API (em vez do client default), implemente a interface CommunicationApiClient e injete via prop client:

import type { CommunicationApiClient } from '@tmf/communication-front'

const myClient: CommunicationApiClient = {
  listCampaigns: (p) => myApi.campaigns.list(p),
  getCampaign:   (id) => myApi.campaigns.get(id),
  // … apenas os métodos que o produto usa (todos são opcionais)
}

<CommunicationApp contract={contract} client={myClient} />

Todos os ~82 métodos da interface são opcionais — um produto que só usa campanhas implementa só esses. Componentes cujo método correspondente não existir exibem placeholder informativo em vez de quebrar.

6. Componentes exportados

  • Top-level: CommunicationApp, CommunicationProvider, useCommunicationContext
  • Composição: CommunicationClientTab (sub-abas do cliente), CommunicationPainel (O Gestor)
  • Campanhas: CampaignListView, CampaignCreateModal, CampaignDetailView, CampaignAnalyticsView, CampaignGroupsView
  • Canais: ChannelShell, ChannelTemplatesList, EmailOptOutsView
  • Financeiro / config: OverviewDashboard, FinancialView, ProvidersView, SandboxView
  • Bots: BotsManagementView, BotFlowEditor (+ BotFlowCanvas, BotNodePalette, BotPropertiesPanel, helpers validateBotWorkflow/backendToNode/backendToEdge), BootAttendanceView, InboundView, PauseBotView
  • Gestor / WAManager: CampaignManagerView, WaDashboardView, WaAnalyticsView, WaFunnelView, WaScoringView, WaBestTimeView, WaRoiView, WaTemplatePerfView, WaOptOutTrendsView, WaOptOutsView
  • Infra: createHubCommunicationClient, commQueryKeys, PACKAGE_VERSION, tipos Comm*
  • Utils: getErrorMessage, hasTranslatedError, ERROR_MESSAGES (tradução pt-BR de erros de disparo Meta/SES/Twilio — TH-57013)

Detalhe por área em FUNCIONALIDADES.md.

7. Ports plugáveis (do @tmf/platform-core)

CommunicationProvider/CommunicationApp aceitam:

  • toast (ToastPort) — ex.: adapter sobre sonner/react-hot-toast.
  • i18n (I18nPort) — default: DictI18nPort embutido via createDictI18nPort (pt-BR/en/es, namespace communication.*).
  • theme (ThemePort) — aplica CSS vars do contrato (design-tokens).
  • getToken — função que devolve o Bearer atual.

8. Checklist de adoção

  1. .npmrc com registry Forgejo + legacy-peer-deps=true.
  2. npm install @tmf/communication-front --legacy-peer-deps.
  3. Garantir as peers obrigatórias (@tmf/platform-core, @tmf/flow-ui, @tanstack/react-query, lucide-react, react/react-dom).
  4. Endpoint service/communication ativo (direto no Hub ou via proxy) e declarado no contrato: { key: "communication", baseUrl: "/api/service/communication" }.
  5. Envolver num QueryClientProvider; renderizar <CommunicationApp contract tenantMode getToken />.
  6. Validar tsc --noEmit + smoke (listar/criar campanha, analytics) apontando para o Hub QA.

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

Dependencies

Dependencies

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

Development dependencies

ID Version
@tmf/flow-ui file:../../flow-ui
@tmf/platform-core file:../../platform-core
@types/react ^18.2.47
@types/react-dom ^18.2.18
react-email-editor ^1.8.0
tsup ^8.5.1
typescript ^5.3.3

Peer dependencies

ID Version
react >=18.0.0
react-dom >=18.0.0
react-email-editor >=1.8.0

Keywords

tmf messaging campaigns marketing react components plug-and-play
Details
npm
2026-07-08 15:53:34 -03:00
13
Trade Marketing Force LTDA
UNLICENSED
877 KiB
Assets (1)
communication-front-4.1.0.tgz 877 KiB
Versions (63) View all
10.4.0 2026-09-05
10.3.0 2026-09-04
10.2.1 2026-09-01
10.2.0 2026-08-28
10.1.2 2026-08-26