@effect.healthcare/messenger 0.3.1

package/dist/messenger.js

@@ -0,0 +1,295 @@
+/**
+ * @module Component
+ */
+// Base Component
+import { Component } from "@scalable.software/component";
+// Component Metadata
+import { Tag, Attributes, Connection, Event, Gesture } from "./messenger.meta.js";
+import { Session, Protocol, Message } from "./messenger.meta.js";
+// Component Validation
+import { Validate } from "./messenger.validation.js";
+/**
+ * Configuration for the headless component — no template or stylesheet.
+ * @category Configuration
+ */
+export const configuration = {
+    url: import.meta.url,
+};
+/**
+ * @category Component
+ */
+export class Messenger extends Component {
+    /**
+     * The tag name of the component
+     * @category Configuration
+     */
+    static get Tag() {
+        return Tag;
+    }
+    /**
+     * Only attributes defined the Attributes object will be observed in DOM
+     * @category State
+     */
+    static get Attributes() {
+        return Attributes;
+    }
+    /**
+     * The live connection status of the messenger. Internally owned.
+     * @category State
+     * @hidden
+     */
+    _connection = Connection.DISCONNECTED;
+    /**
+     * The negotiate endpoint URL. When absent the messenger stays disconnected.
+     * @category State
+     * @hidden
+     */
+    _endpoint = null;
+    /**
+     * The live Web PubSub socket. Held so it can be closed and replaced.
+     * @category State
+     * @hidden
+     */
+    _socket = null;
+    /**
+     * Event subscription handler slots.
+     * @category Event
+     * @hidden
+     */
+    _onendpointchange = null;
+    _onconnecting = null;
+    _onconnected = null;
+    _ondisconnected = null;
+    _onmasterdatachange = null;
+    /**
+     * Cache element references to improve performance
+     * @category State
+     * @hidden
+     */
+    elements = {};
+    /**
+     * @hidden
+     */
+    constructor() {
+        super(configuration);
+    }
+    /**
+     * The live connection status of the messenger. Internally owned — readable
+     * externally, but only mutable from within (protected setter).
+     * @category State
+     */
+    get connection() {
+        return this._connection;
+    }
+    set connection(connection) {
+        // Guard
+        if (this._connection === connection)
+            return;
+        // Mutate
+        this._connection = connection;
+        this.setAttribute(Attributes.CONNECTION, connection);
+        // Dispatch
+        const event = { detail: { connection } };
+        connection === Connection.CONNECTING &&
+            this._dispatchEvent(Event.ON_CONNECTING, event);
+        connection === Connection.CONNECTED &&
+            this._dispatchEvent(Event.ON_CONNECTED, event);
+        connection === Connection.DISCONNECTED &&
+            this._dispatchEvent(Event.ON_DISCONNECTED, event);
+    }
+    /**
+     * The negotiate endpoint URL. When absent the messenger stays disconnected.
+     * @category State
+     */
+    get endpoint() {
+        return this._endpoint;
+    }
+    set endpoint(endpoint) {
+        // Normalize
+        endpoint = endpoint ?? null;
+        // Validate
+        endpoint = endpoint ? Validate.endpoint(endpoint) : null;
+        // Guard
+        if (this._endpoint === endpoint)
+            return;
+        // Mutate
+        this._endpoint = endpoint;
+        endpoint === null
+            ? this.removeAttribute(Attributes.ENDPOINT)
+            : this.setAttribute(Attributes.ENDPOINT, endpoint);
+        // Dispatch
+        this._dispatchEvent(Event.ON_ENDPOINT_CHANGE, { detail: { endpoint } });
+    }
+    /**
+     * The session token, read fresh from local storage on every access — never
+     * cached — because the License component renews and rewrites the key.
+     * @category Operation
+     * @hidden
+     */
+    get _token() {
+        return localStorage.getItem(Session);
+    }
+    /**
+     * Negotiates a client access URL from the configured endpoint, authenticating
+     * with the session token, then opens the live connection. No-op when the
+     * endpoint or token is unavailable, or when already connecting or connected.
+     * @category Operation
+     */
+    connect = async () => {
+        const token = this._token;
+        // Gate + guard
+        if (!this.endpoint || !token)
+            return;
+        if (this._connection !== Connection.DISCONNECTED)
+            return;
+        // Establish
+        this.connection = Connection.CONNECTING;
+        const url = await this._negotiate(token);
+        this._socket = this._open(url);
+    };
+    /**
+     * Closes the live connection.
+     * @category Operation
+     */
+    disconnect = () => {
+        this._socket?.close();
+        this._socket = null;
+        this.connection = Connection.DISCONNECTED;
+    };
+    /**
+     * Subscribes to the `onendpointchange` event. Assigning replaces the previous
+     * handler; assigning `null` removes it.
+     * @category Event
+     */
+    set onendpointchange(handler) {
+        this._onendpointchange &&
+            this.removeEventListener(Event.ON_ENDPOINT_CHANGE, this._onendpointchange);
+        this._onendpointchange = handler;
+        this._onendpointchange &&
+            this.addEventListener(Event.ON_ENDPOINT_CHANGE, this._onendpointchange);
+    }
+    /**
+     * Subscribes to the `onconnecting` event. Assigning replaces the previous
+     * handler; assigning `null` removes it.
+     * @category Event
+     */
+    set onconnecting(handler) {
+        this._onconnecting &&
+            this.removeEventListener(Event.ON_CONNECTING, this._onconnecting);
+        this._onconnecting = handler;
+        this._onconnecting &&
+            this.addEventListener(Event.ON_CONNECTING, this._onconnecting);
+    }
+    /**
+     * Subscribes to the `onconnected` event. Assigning replaces the previous
+     * handler; assigning `null` removes it.
+     * @category Event
+     */
+    set onconnected(handler) {
+        this._onconnected &&
+            this.removeEventListener(Event.ON_CONNECTED, this._onconnected);
+        this._onconnected = handler;
+        this._onconnected &&
+            this.addEventListener(Event.ON_CONNECTED, this._onconnected);
+    }
+    /**
+     * Subscribes to the `ondisconnected` event. Assigning replaces the previous
+     * handler; assigning `null` removes it.
+     * @category Event
+     */
+    set ondisconnected(handler) {
+        this._ondisconnected &&
+            this.removeEventListener(Event.ON_DISCONNECTED, this._ondisconnected);
+        this._ondisconnected = handler;
+        this._ondisconnected &&
+            this.addEventListener(Event.ON_DISCONNECTED, this._ondisconnected);
+    }
+    /**
+     * Subscribes to the `onmasterdatachange` event. Assigning replaces the
+     * previous handler; assigning `null` removes it.
+     * @category Event
+     */
+    set onmasterdatachange(handler) {
+        this._onmasterdatachange &&
+            this.removeEventListener(Event.ON_MASTERDATACHANGE, this._onmasterdatachange);
+        this._onmasterdatachange = handler;
+        this._onmasterdatachange &&
+            this.addEventListener(Event.ON_MASTERDATACHANGE, this._onmasterdatachange);
+    }
+    /**
+     * List operations to perform for selected attributes being observed in the DOM.
+     * @category Configuration
+     * @hidden
+     */
+    _attributeHandlers = {
+        [Attributes.CONNECTION]: (value) => value !== this._connection &&
+            this.setAttribute(Attributes.CONNECTION, this._connection),
+        [Attributes.ENDPOINT]: (value) => (this.endpoint = value),
+    };
+    /**
+     * Cache element references to improve performance
+     * @category Configuration
+     * @hidden
+     */
+    _cache = () => { };
+    /**
+     * Initialize component attributes with default values
+     * @category Configuration
+     * @hidden
+     */
+    _initialize = () => {
+        !this.hasAttribute(Attributes.CONNECTION) &&
+            this.setAttribute(Attributes.CONNECTION, this._connection);
+    };
+    /**
+     * Called by the connectedCallback prototypical method
+     * @category Configuration
+     * @hidden
+     */
+    _addEventListeners = () => { };
+    /**
+     * Called by the disconnectedCallback prototypical method
+     * @category Configuration
+     * @hidden
+     */
+    _removeEventListeners = () => { };
+    /**
+     * Negotiates a short-lived Web PubSub client access URL from the endpoint,
+     * authenticating the request with the session token.
+     * @category Operation
+     * @hidden
+     */
+    _negotiate = async (token) => {
+        const response = await fetch(this.endpoint, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        const { url } = await response.json();
+        return url;
+    };
+    /**
+     * Opens a Web PubSub WebSocket with the required subprotocol and wires the
+     * connection lifecycle handlers.
+     * @category Operation
+     * @hidden
+     */
+    _open = (url) => {
+        const socket = new WebSocket(url, Protocol);
+        socket.onopen = () => (this.connection = Connection.CONNECTED);
+        socket.onclose = () => (this.connection = Connection.DISCONNECTED);
+        socket.addEventListener(Gesture.MESSAGE, this._handleMessage);
+        return socket;
+    };
+    /**
+     * Handles an inbound Web PubSub message (the `message` gesture). Dispatches
+     * `onmasterdatachange` when the payload's `data.type` is `masterData.changed`.
+     * @category Gesture
+     * @hidden
+     */
+    _handleMessage = (event) => {
+        const message = JSON.parse(event.data);
+        message.data?.type === Message.MASTER_DATA_CHANGED &&
+            this._dispatchEvent(Event.ON_MASTERDATACHANGE, {
+                detail: { datetime: new Date().toISOString() },
+            });
+    };
+}

package/dist/messenger.meta.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @module Component
+ */
+/**
+ * @category Configuration
+ */
+export declare const Tag: "app-messenger";
+/**
+ * Local storage key under which the session token is stored (and renewed) by
+ * the License component. Externalized so the contract lives in one place.
+ * @category Configuration
+ */
+export declare const Session: "app-license.session";
+/**
+ * The Azure Web PubSub subprotocol required for structured group messaging.
+ * @category Configuration
+ */
+export declare const Protocol: "json.webpubsub.azure.v1";
+/**
+ * Inbound message types the messenger reacts to (the `data.type` of a frame).
+ * @category Metadata
+ * @enum
+ */
+export declare const Message: {
+    readonly MASTER_DATA_CHANGED: "masterData.changed";
+};
+/**
+ * Inbound message types the messenger reacts to.
+ * @category Metadata
+ */
+export type Message = (typeof Message)[keyof typeof Message];
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ * @enum
+ */
+export declare const Attributes: {
+    readonly CONNECTION: "connection";
+    readonly ENDPOINT: "endpoint";
+};
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ */
+export type Attributes = typeof Attributes;
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ * @enum
+ */
+export declare const State: {
+    readonly CONNECTION: "connection";
+    readonly ENDPOINT: "endpoint";
+};
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ */
+export type State = (typeof State)[keyof typeof State];
+/**
+ * Live connection status value domain
+ * @category Metadata
+ * @enum
+ */
+export declare const Connection: {
+    readonly DISCONNECTED: "disconnected";
+    readonly CONNECTING: "connecting";
+    readonly CONNECTED: "connected";
+};
+/**
+ * Live connection status value domain
+ * @category Metadata
+ */
+export type Connection = (typeof Connection)[keyof typeof Connection];
+/**
+ * The negotiate endpoint URL value domain
+ * @category Metadata
+ */
+export type Endpoint = string;
+/**
+ * @category Metadata
+ * @enum
+ */
+export declare const Operation: {
+    readonly CONNECT: "connect";
+    readonly DISCONNECT: "disconnect";
+};
+/**
+ * @category Metadata
+ */
+export type Operation = (typeof Operation)[keyof typeof Operation];
+/**
+ * @category Metadata
+ * @enum
+ */
+export declare const Event: {
+    readonly ON_ENDPOINT_CHANGE: "onendpointchange";
+    readonly ON_CONNECTING: "onconnecting";
+    readonly ON_CONNECTED: "onconnected";
+    readonly ON_DISCONNECTED: "ondisconnected";
+    readonly ON_MASTERDATACHANGE: "onmasterdatachange";
+};
+/**
+ * @category Metadata
+ */
+export type Event = (typeof Event)[keyof typeof Event];
+/**
+ * @category Metadata
+ * @enum
+ */
+export declare const Gesture: {
+    readonly MESSAGE: "message";
+};
+/**
+ * @category Metadata
+ */
+export type Gesture = (typeof Gesture)[keyof typeof Gesture];

package/dist/messenger.meta.js

@@ -0,0 +1,79 @@
+/**
+ * @module Component
+ */
+/**
+ * @category Configuration
+ */
+export const Tag = "app-messenger";
+/**
+ * Local storage key under which the session token is stored (and renewed) by
+ * the License component. Externalized so the contract lives in one place.
+ * @category Configuration
+ */
+export const Session = "app-license.session";
+/**
+ * The Azure Web PubSub subprotocol required for structured group messaging.
+ * @category Configuration
+ */
+export const Protocol = "json.webpubsub.azure.v1";
+/**
+ * Inbound message types the messenger reacts to (the `data.type` of a frame).
+ * @category Metadata
+ * @enum
+ */
+export const Message = {
+    MASTER_DATA_CHANGED: "masterData.changed",
+};
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ * @enum
+ */
+export const Attributes = {
+    CONNECTION: "connection",
+    ENDPOINT: "endpoint",
+};
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ * @enum
+ */
+export const State = {
+    ...Attributes,
+};
+/**
+ * Live connection status value domain
+ * @category Metadata
+ * @enum
+ */
+export const Connection = {
+    DISCONNECTED: "disconnected",
+    CONNECTING: "connecting",
+    CONNECTED: "connected",
+};
+/**
+ * @category Metadata
+ * @enum
+ */
+export const Operation = {
+    CONNECT: "connect",
+    DISCONNECT: "disconnect",
+};
+/**
+ * @category Metadata
+ * @enum
+ */
+export const Event = {
+    ON_ENDPOINT_CHANGE: "onendpointchange",
+    ON_CONNECTING: "onconnecting",
+    ON_CONNECTED: "onconnected",
+    ON_DISCONNECTED: "ondisconnected",
+    ON_MASTERDATACHANGE: "onmasterdatachange",
+};
+/**
+ * @category Metadata
+ * @enum
+ */
+export const Gesture = {
+    MESSAGE: "message",
+};

package/dist/messenger.style.css

@@ -0,0 +1,6 @@
+/* =======================
+  Host Element Styles
+======================= */
+:host {
+  display: inline-block;
+}

package/dist/messenger.template.html

@@ -0,0 +1 @@
+<template id="app-messenger"> </template>

package/dist/messenger.validation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module Component
+ */
+import { type Endpoint } from "./messenger.meta.js";
+/**
+ * Runtime enforcement of declared value domains.
+ * @category Validation
+ */
+export declare class Validate {
+    /**
+     * Validates the negotiate endpoint URL value domain.
+     * @category Validation
+     */
+    static endpoint: (value: string) => Endpoint;
+}

package/dist/messenger.validation.js

@@ -0,0 +1,22 @@
+/**
+ * @module Component
+ */
+/**
+ * Runtime enforcement of declared value domains.
+ * @category Validation
+ */
+export class Validate {
+    /**
+     * Validates the negotiate endpoint URL value domain.
+     * @category Validation
+     */
+    static endpoint = (value) => {
+        try {
+            new URL(value);
+        }
+        catch {
+            throw new Error(`Invalid endpoint value: ${value}`);
+        }
+        return value;
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@effect.healthcare/messenger",
+  "version": "0.3.1",
+  "description": "Azure Pub Sub Messenger Web Component",
+  "keywords": [
+    "web component"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean.test": "node ./tasks/clean.test.mjs",
+    "pretest": "npm run clean.test && tsc --project tsconfig.test.json",
+    "test": "karma start",
+    "posttest": "npm run clean.test",
+    "prebuild": "node ./tasks/clean.build.mjs",
+    "build": "tsc --project tsconfig.build.json",
+    "postbuild": "node ./tasks/copy.build.mjs",
+    "preserve": "npm run build",
+    "serve": "web-dev-server",
+    "document": "npx typedoc --tsconfig tsconfig.test.json",
+    "prepublish": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/effect-healthcare/messenger.git"
+  },
+  "author": "Scalable.Software",
+  "license": "CC-BY-NC-SA-4.0",
+  "bugs": {
+    "url": "https://github.com/effect-healthcare/messenger/issues"
+  },
+  "homepage": "https://github.com/effect-healthcare/messenger#readme",
+  "devDependencies": {
+    "@types/jasmine": "^5.1.4",
+    "@types/node": "^26.0.1",
+    "@web/dev-server": "^0.4.6",
+    "jasmine": "^5.1.0",
+    "karma": "^6.4.3",
+    "karma-chrome-launcher": "^3.2.0",
+    "karma-coverage-istanbul-instrumenter": "^1.0.4",
+    "karma-coverage-istanbul-reporter": "^3.0.3",
+    "karma-jasmine": "^5.1.0",
+    "karma-spec-reporter": "^0.0.36",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-merge-modules": "^7.0.0",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@scalable.software/component": "^0.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  Tag,
+  Session,
+  Protocol,
+  Message,
+  Attributes,
+  State,
+  Connection,
+  Operation,
+  Event,
+  Gesture,
+} from "./messenger.meta.js";
+
+export { Validate } from "./messenger.validation.js";
+
+export { Messenger } from "./messenger.js";