Messenger

@effect.healthcare/messenger (<app-messenger>) is a headless web component that bridges your application to an Azure Web PubSub hub. It authenticates with the session token in local storage, negotiates a short‑lived client access URL, opens a live connection, and dispatches inbound master‑data‑change notifications as a semantic DOM event.

It renders nothing — no template, no styles. You configure it, bind an event, and call connect().

This foundation is receive‑only; outbound collaboration messaging is a future capability.

Overview

import { Messenger } from "@effect.healthcare/messenger";

// Register the element
customElements.define(Messenger.Tag, Messenger);

// Get the instance (or place <app-messenger> in your HTML)
const messenger = await Messenger.get();

// Bind the event you care about
messenger.onmasterdatachange = (event) =>
  console.log("master data changed at", event.detail.datetime);

// Configure the negotiate endpoint, then connect
messenger.endpoint = "https://your-api/realtime/master-data/negotiate";
await messenger.connect();

1. Configuration

Two inputs drive the messenger:

• endpoint — the negotiate URL of the hub. It is an attribute‑backed state, so set it either as a property or as an attribute:

  <app-messenger endpoint="https://your-api/realtime/master-data/negotiate"></app-messenger>

  messenger.endpoint = "https://your-api/realtime/master-data/negotiate";

• Session token — read fresh on every connect attempt from local storage under the key app-license.session. Your application (e.g. the License component) must have written it before connecting. The messenger never logs in itself.

2. Binding to onmasterdatachange

The messenger dispatches onmasterdatachange whenever the server signals a master‑data change. The payload carries the receipt time:

messenger.onmasterdatachange = (event) => {
  const { datetime } = event.detail; // ISO-8601 timestamp
  // re-sync your application data here
};

Assigning a handler replaces the previous one; assign null to remove it.

3. Connecting

await messenger.connect(); // negotiates + opens the live connection
messenger.disconnect();    // closes the connection

connect() is a no‑op unless both an endpoint and a session token are available, or when already connecting/connected — so it is safe to call repeatedly.

Connection lifecycle events

Observe the live status if you need to coordinate around it. Each event.detail.connection is one of connecting | connected | disconnected:

| Event | Fires when | | --- | --- | | onconnecting | a connection attempt starts | | onconnected | the live connection opens | | ondisconnected | the connection closes | | onendpointchange | the endpoint changes (event.detail.endpoint) |

Development

npm install        # install dependencies
npm test           # run the suite (coverage in ./coverage, report in ./report)
npm run document   # generate API docs into ./docs

License

This software and its documentation are released under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License (CC BY-NC-SA 4.0). This means you are free to share, copy, distribute, and transmit the work, and to adapt it, but only under the following conditions:

Attribution: You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).

NonCommercial: You may not use this material for commercial purposes.

ShareAlike: If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.

For more details, please visit the full license agreement.