@cwellt_software/shared-communication-hub

React components, hooks, and API clients for the SharedCommunicationHub multi-channel communication backend: conversation threads, a messenger, message templates with token replacement, channel administration, a permission matrix, and an audit log — over Email (Microsoft Graph), WhatsApp/SMS/Facebook/Instagram (Twilio), in-app push, and other channels.

The library is domain-agnostic: it defines the shape of communications (threads, messages, channels, templates, real-time events) and delegates every business-specific concept — recipient categories, template tokens, filter axes, recipient resolution — to the host application through props and callbacks (see Host-supplied vocabulary).

Components

| Component | Purpose | |---|---| | CommMessenger | Thread list + chat view with live updates (the inbox) | | CommThreadList / CommChatView | The messenger's halves, usable standalone | | CommSendDialog | Template-driven multi-recipient send dialog | | CommEntityMessages | All communications linked to one business entity (e.g. a details-page tab) | | CommChannelConfigTable | Channel administration (add/edit/test/deactivate) | | CommTemplateEditor | Message-template administration | | CommPermissionMatrix | Function-category × channel access matrix | | CommAuditLog | Server-side paged audit log with CSV export |

Plus the CommHubApi client interface (HttpCommHubApi, seedable InMemoryCommHubApi for tests/demos), typed hooks for every endpoint, and an optional SignalR real-time client.

Installation

npm install @cwellt_software/shared-communication-hub

react / react-dom >= 18 are peer dependencies. Import both stylesheets once (the cwellt library CSS provides the --cw-* design tokens and icon font; this package's CSS covers its own components):

import '@cwellt_software/cwellt-reactjs-lib/dist/index.css';
import '@cwellt_software/shared-communication-hub/dist/shared-communication-hub.css';

Quick start

import {
    CommHubProvider,
    HttpCommHubApi,
    CommMessenger,
} from '@cwellt_software/shared-communication-hub';

// Point at the backend's route prefix — the ASP.NET Core host (or a proxy
// in front of it) serving the SharedCommunicationHub.Infra controllers.
const api = new HttpCommHubApi('/api/commhub', {
    // Only needed when the browser talks to the service directly; a
    // server-side proxy usually injects the identity header itself.
    headers: () => ({'X-CommHub-User': currentUserName}),
});

export function CommunicationsPage() {
    return (
        <CommHubProvider api={api}>
            <CommMessenger />
        </CommHubProvider>
    );
}

The backend is the SharedCommunicationHub.Domain / .Infra NuGet packages (same repository): EF Core persistence, ready-made MVC controllers (AddSharedCommHubControllers("api/commhub")), channel implementations, and the ports the host implements (ITokenReplacer, ICommHubAccessControl, ICommHubFunctionCategoryProvider, …).

Real-time (optional)

Pass a realtime client alongside the API to get live thread/message updates in the messenger. Without it, everything still works — components just don't update live.

import {SignalRCommHubRealtime} from '@cwellt_software/shared-communication-hub';

// The host mints short-lived connection tokens ({token, hubUrl, expiresAt});
// the provider is called on connect and on every reconnect.
const realtime = new SignalRCommHubRealtime(
    async () => (await fetch('/commhub-realtime/token')).json(),
);

<CommHubProvider api={api} realtime={realtime}>...</CommHubProvider>

Host-supplied vocabulary & seams

The library ships no business vocabulary. Hosts provide their own values through props; without them the components render an explanatory empty state saying who owns the list.

| Prop / callback | Where | Host supplies | |---|---|---| | recipientTypes | CommTemplateEditor, CommSendDialog | Routing categories for template recipients (e.g. departments, roles, partner types) | | filterAxes (+ filtersHeading, filtersHint, noFiltersLabel) | CommTemplateEditor | Template filter axes — open {type, label, values} triples over the wire's open filterType string; each value is a plain string or {value, label} when the persisted match key differs from the display text (WinOps: svc-type code "J" vs "Passenger (J)") | | tokens | CommTemplateEditor | The %Token% list your ITokenReplacer implementation resolves | | functionCategories | CommPermissionMatrix | The host's user function categories (rows come from the host's own tables) | | departments | CommChannelConfigTable | Department options for channels | | resolveRecipients(category, channelId, entities) | CommSendDialog | Resolves a routing category to concrete recipients (name, address, kind) | | resolveTokenPreview(text, entity) | CommSendDialog | Renders a per-entity preview of a token-bearing draft | | templateApplies(template) | CommSendDialog | Send-side counterpart of filterAxes: whether a template may be offered for the selected entities (its filters vs their attributes); rejected templates are hidden from the picker | | retentionDays | CommAuditLog | The host's audit retention setting, if it has one |

Testing your integration

InMemoryCommHubApi is a seedable in-memory implementation of the full CommHubApi contract that mirrors the backend's validation rules (secret masking, open-thread reuse, system-managed template locks, per-send audit rows). Use it in component tests and demos without a server.

Publishing (maintainers)

This package publishes to public npm (registry.npmjs.org) as a scoped package under the @cwellt_software npm organization. Scoped packages publish to npm's default registry automatically, so no registry line and no publishConfig are needed — the only per-machine setup is an auth token in your user-level ~/.npmrc (Windows: C:\Users\<you>\.npmrc).

1. Get an npm access token (npm_…) from npmjs.com → Access Tokens (needs read/write / publish permission on @cwellt_software), or run npm login and let npm write the token line for you.
2. Put it in ~/.npmrc — a single line, nothing else:

   //registry.npmjs.org/:_authToken=<YOUR_NPM_TOKEN>

3. Never commit the token. ~/.npmrc sits in your home dir, outside every repo, so git can't see it. Do not add a token-bearing .npmrc to the repo.

Verify before publishing (uploads nothing):

npm whoami                                  # → your npm user (confirms the token works)
npm publish --dry-run                       # → "Publishing to https://registry.npmjs.org/"

Then npm run publish:npm (install → build → pack dry-run → npm publish --access public). Scoped packages default to a restricted (private) publish; --access public makes the published package publicly readable, which is the convention across the @cwellt_software libraries.

License

Proprietary and internal — UNLICENSED, © Cwellt Software. All rights reserved; no rights are granted for use outside Cwellt Software's own projects.

This package is internal-only for now (distributed via Cwellt's private feed), so it deliberately ships no license file. A definitive license will be set if/when the library is distributed externally; it will apply to the versions published under it, not retroactively to earlier ones.