@effect.healthcare/messenger 0.3.1

package/src/messenger.meta.ts

@@ -0,0 +1,131 @@
+/**
+ * @module Component
+ */
+
+/**
+ * @category Configuration
+ */
+export const Tag = "app-messenger" as const;
+
+/**
+ * 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" as const;
+
+/**
+ * The Azure Web PubSub subprotocol required for structured group messaging.
+ * @category Configuration
+ */
+export const Protocol = "json.webpubsub.azure.v1" as const;
+
+/**
+ * Inbound message types the messenger reacts to (the `data.type` of a frame).
+ * @category Metadata
+ * @enum
+ */
+export const Message = {
+  MASTER_DATA_CHANGED: "masterData.changed",
+} as const;
+
+/**
+ * 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 const Attributes = {
+  CONNECTION: "connection",
+  ENDPOINT: "endpoint",
+} as const;
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ */
+export type Attributes = typeof Attributes;
+
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ * @enum
+ */
+export const State = {
+  ...Attributes,
+} as const;
+
+/**
+ * HTML Attributes available to set
+ * @category Metadata
+ */
+export type State = (typeof State)[keyof typeof State];
+
+/**
+ * Live connection status value domain
+ * @category Metadata
+ * @enum
+ */
+export const Connection = {
+  DISCONNECTED: "disconnected",
+  CONNECTING: "connecting",
+  CONNECTED: "connected",
+} as const;
+
+/**
+ * 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 const Operation = {
+  CONNECT: "connect",
+  DISCONNECT: "disconnect",
+} as const;
+
+/**
+ * @category Metadata
+ */
+export type Operation = (typeof Operation)[keyof typeof Operation];
+
+/**
+ * @category Metadata
+ * @enum
+ */
+export const Event = {
+  ON_ENDPOINT_CHANGE: "onendpointchange",
+  ON_CONNECTING: "onconnecting",
+  ON_CONNECTED: "onconnected",
+  ON_DISCONNECTED: "ondisconnected",
+  ON_MASTERDATACHANGE: "onmasterdatachange",
+} as const;
+/**
+ * @category Metadata
+ */
+export type Event = (typeof Event)[keyof typeof Event];
+
+/**
+ * @category Metadata
+ * @enum
+ */
+export const Gesture = {
+  MESSAGE: "message",
+} as const;
+/**
+ * @category Metadata
+ */
+export type Gesture = (typeof Gesture)[keyof typeof Gesture];

package/src/messenger.ts

@@ -0,0 +1,347 @@
+/**
+ * @module Component
+ */
+
+// Base Component
+import { Component } from "@scalable.software/component";
+import { type Configuration } from "@scalable.software/component";
+
+// Component Metadata
+import { Tag, Attributes, Connection, Event, Gesture } from "./messenger.meta.js";
+import { Session, Protocol, Message } from "./messenger.meta.js";
+import { type Endpoint } 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: Configuration = {
+  url: import.meta.url,
+} as const;
+
+/**
+ * @category Component
+ */
+export class Messenger extends Component {
+  /**
+   * The tag name of the component
+   * @category Configuration
+   */
+  public static get Tag() {
+    return Tag;
+  }
+
+  /**
+   * Only attributes defined the Attributes object will be observed in DOM
+   * @category State
+   */
+  public static get Attributes(): Attributes {
+    return Attributes;
+  }
+
+  /**
+   * The live connection status of the messenger. Internally owned.
+   * @category State
+   * @hidden
+   */
+  private _connection: Connection = Connection.DISCONNECTED;
+
+  /**
+   * The negotiate endpoint URL. When absent the messenger stays disconnected.
+   * @category State
+   * @hidden
+   */
+  private _endpoint: Endpoint | null = null;
+
+  /**
+   * The live Web PubSub socket. Held so it can be closed and replaced.
+   * @category State
+   * @hidden
+   */
+  private _socket: WebSocket | null = null;
+
+  /**
+   * Event subscription handler slots.
+   * @category Event
+   * @hidden
+   */
+  private _onendpointchange: EventListener | null = null;
+  private _onconnecting: EventListener | null = null;
+  private _onconnected: EventListener | null = null;
+  private _ondisconnected: EventListener | null = null;
+  private _onmasterdatachange: EventListener | null = null;
+
+  /**
+   * Cache element references to improve performance
+   * @category State
+   * @hidden
+   */
+  protected 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
+   */
+  public get connection(): Connection {
+    return this._connection;
+  }
+
+  protected set connection(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
+   */
+  public get endpoint(): Endpoint | null {
+    return this._endpoint;
+  }
+
+  public set endpoint(endpoint: Endpoint | null) {
+    // 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
+   */
+  private get _token(): string | null {
+    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
+   */
+  public connect = async (): Promise<void> => {
+    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
+   */
+  public disconnect = (): void => {
+    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
+   */
+  public set onendpointchange(handler: EventListener | null) {
+    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
+   */
+  public set onconnecting(handler: EventListener | null) {
+    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
+   */
+  public set onconnected(handler: EventListener | null) {
+    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
+   */
+  public set ondisconnected(handler: EventListener | null) {
+    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
+   */
+  public set onmasterdatachange(handler: EventListener | null) {
+    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
+   */
+  protected _attributeHandlers = {
+    [Attributes.CONNECTION]: (value: Connection) =>
+      value !== this._connection &&
+      this.setAttribute(Attributes.CONNECTION, this._connection),
+    [Attributes.ENDPOINT]: (value: Endpoint) => (this.endpoint = value),
+  };
+
+  /**
+   * Cache element references to improve performance
+   * @category Configuration
+   * @hidden
+   */
+  protected _cache = () => {};
+
+  /**
+   * Initialize component attributes with default values
+   * @category Configuration
+   * @hidden
+   */
+  protected _initialize = () => {
+    !this.hasAttribute(Attributes.CONNECTION) &&
+      this.setAttribute(Attributes.CONNECTION, this._connection);
+  };
+
+  /**
+   * Called by the connectedCallback prototypical method
+   * @category Configuration
+   * @hidden
+   */
+  protected _addEventListeners = () => {};
+
+  /**
+   * Called by the disconnectedCallback prototypical method
+   * @category Configuration
+   * @hidden
+   */
+  protected _removeEventListeners = () => {};
+
+  /**
+   * Negotiates a short-lived Web PubSub client access URL from the endpoint,
+   * authenticating the request with the session token.
+   * @category Operation
+   * @hidden
+   */
+  private _negotiate = async (token: string): Promise<string> => {
+    const response = await fetch(this.endpoint as string, {
+      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
+   */
+  private _open = (url: string): WebSocket => {
+    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
+   */
+  private _handleMessage = (event: MessageEvent) => {
+    const message = JSON.parse(event.data);
+    message.data?.type === Message.MASTER_DATA_CHANGED &&
+      this._dispatchEvent(Event.ON_MASTERDATACHANGE, {
+        detail: { datetime: new Date().toISOString() },
+      });
+  };
+}

package/src/messenger.validation.ts

@@ -0,0 +1,25 @@
+/**
+ * @module Component
+ */
+
+// Component Metadata
+import { type Endpoint } from "./messenger.meta.js";
+
+/**
+ * Runtime enforcement of declared value domains.
+ * @category Validation
+ */
+export class Validate {
+  /**
+   * Validates the negotiate endpoint URL value domain.
+   * @category Validation
+   */
+  public static endpoint = (value: string) => {
+    try {
+      new URL(value);
+    } catch {
+      throw new Error(`Invalid endpoint value: ${value}`);
+    }
+    return value as Endpoint;
+  };
+}

package/web-dev-server.config.mjs

@@ -0,0 +1,8 @@
+export default {
+  rootDir: ".", // serve repo root: demo pulls in ../importmap and ./dist via the import map
+  port: 3000,
+  watch: true, // live-reload on file changes
+  // open: "/demo/index.html", // left off: the browser is driven via the chrome-devtools MCP
+  // Note: the demo uses relative asset paths, so it must be opened at /demo/index.html
+  // (not at "/"). appIndex/history-fallback is intentionally not used here.
+};