@freelight/chat

Shared real-time chat for FreeLight apps (FreeLight DAO + the Freelight campaign platform). Dual package:

1. Backend engine (main) — event-driven streaming over Garnet pub/sub, per-channel subscribers, Garnet-backed presence with TTL.
2. Frontend HotStaq module (assets/) — a config-driven chat UI (channel rail + message panel + members) installed with hotstaq module install.

Hot.import("@freelight/chat") loads the generated frontend manifest only; it never pulls in the backend or @freelight/core, so a frontend-only consumer installs no backend deps.

Backend engine

Backend logic only — the host app owns the database schema (channels + messages tables), route registration, authorization gates, and the initial history snapshot. The host persists a message, then calls engine.notifyNewMessage(...); the engine fans it out to live subscribers.

Depends on @freelight/core (DataAccess / IAppUtils / FreeUser).

import { ChatEngine } from "@freelight/chat";

const engine = new ChatEngine(appUtils);
engine.setup(); // once at startup

// in your SSE route:
const connId = await engine.addSubscriber(channelId, user?.id ?? null, safeUser, sendMsg);
// req.onClose: engine.removeSubscriber(channelId, connId)

// after persisting a message in your route:
engine.notifyNewMessage(channelId, { id, channelId, posterId, author, message, createdDate });

Frontend module

Install it alongside your other HotStaq modules:

// package.json
"postinstall": "npx hotstaq module install @freelight/[email protected]"

Render it from a page and configure the client before it boots:

<*
    let chat = await Hot.import ("@freelight/chat");
    chat.outputCSS ();
    chat.outputJS ();
*>

<* await chat.output ("freelight-chat"); *>

<script>
window.flChatConfig = {
    baseUrl:        config.baseUrl,
    jwt:            jwtToken,
    scopeId:        campaignProfileId,   // null for a single global channel set
    channelsRoute:  "chatChannels",      // DAO: "channels"
    messagesRoute:  "chatMessages",      // DAO: "messages"
    createPayload:  "flat",              // {channelId,message}; DAO: "nested"
    deletePayload:  "flat",              // {id};               DAO: "nested"
    streamEvent:    "chat/stream",       // DAO: "channels/streamChannelUpdates"
    avatarMode:     "seed",              // seed DiceBear by poster id; or "profile"
    canModerate:    isCampaignModerator, // show delete on others' messages
    capabilities:   { createChannels: true, announcements: false }
    // autoInit: false  → call window.flChat.init() yourself once scopeId is ready
};
</script>

The module ships only assets (no web components) and depends solely on the HotStaq runtime + jQuery that every HotStaq page already loads. All colours are --flc-* custom properties with light-theme defaults on #fl-chat-app; override them on the container to match a host theme.