@connexis/transport-sse 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connexis Realtime Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,32 @@
+import { Transport, ConnectionState, TransportCapabilities } from '@connexis/core';
+
+interface SSETransportOptions {
+    publishUrl?: string;
+    publish?: (topic: string, data: any) => Promise<void>;
+    withCredentials?: boolean;
+}
+declare class SSETransport implements Transport {
+    private url;
+    private options;
+    readonly type = "sse";
+    private eventSource;
+    private _state;
+    private messageCb;
+    private stateCb;
+    private activeListeners;
+    constructor(url: string, options?: SSETransportOptions);
+    get state(): ConnectionState;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    publish(topic: string, data: any): Promise<void>;
+    subscribe(topic: string, _filter?: Record<string, any>): Promise<void>;
+    unsubscribe(topic: string, _filter?: Record<string, any>): Promise<void>;
+    capabilities(): TransportCapabilities;
+    onMessage(cb: (topic: string, data: any) => void): void;
+    onStateChange(cb: (state: ConnectionState, error?: Error) => void): void;
+    clone(): SSETransport;
+    private handleGenericMessage;
+    private updateState;
+}
+
+export { SSETransport, type SSETransportOptions };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { Transport, ConnectionState, TransportCapabilities } from '@connexis/core';
+
+interface SSETransportOptions {
+    publishUrl?: string;
+    publish?: (topic: string, data: any) => Promise<void>;
+    withCredentials?: boolean;
+}
+declare class SSETransport implements Transport {
+    private url;
+    private options;
+    readonly type = "sse";
+    private eventSource;
+    private _state;
+    private messageCb;
+    private stateCb;
+    private activeListeners;
+    constructor(url: string, options?: SSETransportOptions);
+    get state(): ConnectionState;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    publish(topic: string, data: any): Promise<void>;
+    subscribe(topic: string, _filter?: Record<string, any>): Promise<void>;
+    unsubscribe(topic: string, _filter?: Record<string, any>): Promise<void>;
+    capabilities(): TransportCapabilities;
+    onMessage(cb: (topic: string, data: any) => void): void;
+    onStateChange(cb: (state: ConnectionState, error?: Error) => void): void;
+    clone(): SSETransport;
+    private handleGenericMessage;
+    private updateState;
+}
+
+export { SSETransport, type SSETransportOptions };

package/dist/index.js

@@ -0,0 +1,180 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SSETransport: () => SSETransport
+});
+module.exports = __toCommonJS(index_exports);
+var SSETransport = class _SSETransport {
+  constructor(url, options = {}) {
+    this.url = url;
+    this.options = options;
+  }
+  url;
+  options;
+  type = "sse";
+  eventSource = null;
+  _state = "idle";
+  messageCb = null;
+  stateCb = null;
+  activeListeners = /* @__PURE__ */ new Map();
+  get state() {
+    return this._state;
+  }
+  async connect() {
+    if (this._state === "connected" || this._state === "connecting") {
+      return;
+    }
+    this.updateState("connecting");
+    return new Promise((resolve, reject) => {
+      try {
+        this.eventSource = new EventSource(this.url, {
+          withCredentials: this.options.withCredentials
+        });
+      } catch (err) {
+        this.updateState("error", err);
+        reject(err);
+        return;
+      }
+      let hasOpened = false;
+      this.eventSource.onopen = () => {
+        hasOpened = true;
+        this.updateState("connected");
+        resolve();
+      };
+      this.eventSource.onerror = (_event) => {
+        const error = new Error("SSE EventSource connection error");
+        if (!hasOpened) {
+          this.updateState("error", error);
+          this.disconnect();
+          reject(error);
+        } else {
+          this.updateState("error", error);
+          this.disconnect();
+        }
+      };
+      this.eventSource.onmessage = (event) => {
+        this.handleGenericMessage(event.data);
+      };
+      for (const [topic, listener] of this.activeListeners.entries()) {
+        this.eventSource.addEventListener(topic, listener);
+      }
+    });
+  }
+  async disconnect() {
+    if (this.eventSource) {
+      for (const [topic, listener] of this.activeListeners.entries()) {
+        this.eventSource.removeEventListener(topic, listener);
+      }
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.updateState("closed");
+  }
+  async publish(topic, data) {
+    if (this.options.publish) {
+      await this.options.publish(topic, data);
+      return;
+    }
+    if (this.options.publishUrl) {
+      const response = await fetch(this.options.publishUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ topic, data })
+      });
+      if (!response.ok) {
+        throw new Error(`SSE publish HTTP request failed with status ${response.status}`);
+      }
+      return;
+    }
+    throw new Error(
+      "Publishing is not supported by SSE without a configured publishUrl or publish function"
+    );
+  }
+  async subscribe(topic, _filter) {
+    if (this.activeListeners.has(topic)) return;
+    const listener = (event) => {
+      try {
+        const parsed = JSON.parse(event.data);
+        this.messageCb?.(topic, parsed);
+      } catch (err) {
+        this.messageCb?.(topic, event.data);
+      }
+    };
+    this.activeListeners.set(topic, listener);
+    if (this.eventSource && this.eventSource.readyState === EventSource.OPEN) {
+      this.eventSource.addEventListener(topic, listener);
+    }
+  }
+  async unsubscribe(topic, _filter) {
+    const listener = this.activeListeners.get(topic);
+    if (!listener) return;
+    if (this.eventSource) {
+      this.eventSource.removeEventListener(topic, listener);
+    }
+    this.activeListeners.delete(topic);
+  }
+  capabilities() {
+    return {
+      publish: !!(this.options.publish || this.options.publishUrl),
+      subscribe: true,
+      latency: "high"
+    };
+  }
+  onMessage(cb) {
+    this.messageCb = cb;
+  }
+  onStateChange(cb) {
+    this.stateCb = cb;
+  }
+  clone() {
+    return new _SSETransport(this.url, this.options);
+  }
+  handleGenericMessage(rawData) {
+    if (!this.messageCb) return;
+    try {
+      const parsed = JSON.parse(rawData);
+      if (parsed && typeof parsed === "object") {
+        const { topic, data } = parsed;
+        if (typeof topic === "string") {
+          this.messageCb(topic, data !== void 0 ? data : parsed);
+          return;
+        }
+      }
+      this.messageCb("message", parsed);
+    } catch (err) {
+      this.messageCb("message", rawData);
+    }
+  }
+  updateState(state, error) {
+    if (this._state === state) return;
+    this._state = state;
+    if (this.stateCb) {
+      this.stateCb(state, error);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SSETransport
+});

package/dist/index.mjs

@@ -0,0 +1,155 @@
+// src/index.ts
+var SSETransport = class _SSETransport {
+  constructor(url, options = {}) {
+    this.url = url;
+    this.options = options;
+  }
+  url;
+  options;
+  type = "sse";
+  eventSource = null;
+  _state = "idle";
+  messageCb = null;
+  stateCb = null;
+  activeListeners = /* @__PURE__ */ new Map();
+  get state() {
+    return this._state;
+  }
+  async connect() {
+    if (this._state === "connected" || this._state === "connecting") {
+      return;
+    }
+    this.updateState("connecting");
+    return new Promise((resolve, reject) => {
+      try {
+        this.eventSource = new EventSource(this.url, {
+          withCredentials: this.options.withCredentials
+        });
+      } catch (err) {
+        this.updateState("error", err);
+        reject(err);
+        return;
+      }
+      let hasOpened = false;
+      this.eventSource.onopen = () => {
+        hasOpened = true;
+        this.updateState("connected");
+        resolve();
+      };
+      this.eventSource.onerror = (_event) => {
+        const error = new Error("SSE EventSource connection error");
+        if (!hasOpened) {
+          this.updateState("error", error);
+          this.disconnect();
+          reject(error);
+        } else {
+          this.updateState("error", error);
+          this.disconnect();
+        }
+      };
+      this.eventSource.onmessage = (event) => {
+        this.handleGenericMessage(event.data);
+      };
+      for (const [topic, listener] of this.activeListeners.entries()) {
+        this.eventSource.addEventListener(topic, listener);
+      }
+    });
+  }
+  async disconnect() {
+    if (this.eventSource) {
+      for (const [topic, listener] of this.activeListeners.entries()) {
+        this.eventSource.removeEventListener(topic, listener);
+      }
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.updateState("closed");
+  }
+  async publish(topic, data) {
+    if (this.options.publish) {
+      await this.options.publish(topic, data);
+      return;
+    }
+    if (this.options.publishUrl) {
+      const response = await fetch(this.options.publishUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ topic, data })
+      });
+      if (!response.ok) {
+        throw new Error(`SSE publish HTTP request failed with status ${response.status}`);
+      }
+      return;
+    }
+    throw new Error(
+      "Publishing is not supported by SSE without a configured publishUrl or publish function"
+    );
+  }
+  async subscribe(topic, _filter) {
+    if (this.activeListeners.has(topic)) return;
+    const listener = (event) => {
+      try {
+        const parsed = JSON.parse(event.data);
+        this.messageCb?.(topic, parsed);
+      } catch (err) {
+        this.messageCb?.(topic, event.data);
+      }
+    };
+    this.activeListeners.set(topic, listener);
+    if (this.eventSource && this.eventSource.readyState === EventSource.OPEN) {
+      this.eventSource.addEventListener(topic, listener);
+    }
+  }
+  async unsubscribe(topic, _filter) {
+    const listener = this.activeListeners.get(topic);
+    if (!listener) return;
+    if (this.eventSource) {
+      this.eventSource.removeEventListener(topic, listener);
+    }
+    this.activeListeners.delete(topic);
+  }
+  capabilities() {
+    return {
+      publish: !!(this.options.publish || this.options.publishUrl),
+      subscribe: true,
+      latency: "high"
+    };
+  }
+  onMessage(cb) {
+    this.messageCb = cb;
+  }
+  onStateChange(cb) {
+    this.stateCb = cb;
+  }
+  clone() {
+    return new _SSETransport(this.url, this.options);
+  }
+  handleGenericMessage(rawData) {
+    if (!this.messageCb) return;
+    try {
+      const parsed = JSON.parse(rawData);
+      if (parsed && typeof parsed === "object") {
+        const { topic, data } = parsed;
+        if (typeof topic === "string") {
+          this.messageCb(topic, data !== void 0 ? data : parsed);
+          return;
+        }
+      }
+      this.messageCb("message", parsed);
+    } catch (err) {
+      this.messageCb("message", rawData);
+    }
+  }
+  updateState(state, error) {
+    if (this._state === state) return;
+    this._state = state;
+    if (this.stateCb) {
+      this.stateCb(state, error);
+    }
+  }
+};
+export {
+  SSETransport
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@connexis/transport-sse",
+  "version": "1.0.0",
+  "description": "Server-Sent Events (SSE) transport for @connexis",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@connexis/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean"
+  }
+}

package/src/index.ts

@@ -0,0 +1,189 @@
+import { Transport, ConnectionState, TransportCapabilities } from '@connexis/core';
+
+export interface SSETransportOptions {
+  publishUrl?: string;
+  publish?: (topic: string, data: any) => Promise<void>;
+  withCredentials?: boolean;
+}
+
+export class SSETransport implements Transport {
+  public readonly type = 'sse';
+  private eventSource: EventSource | null = null;
+  private _state: ConnectionState = 'idle';
+
+  private messageCb: ((topic: string, data: any) => void) | null = null;
+  private stateCb: ((state: ConnectionState, error?: Error) => void) | null = null;
+  private activeListeners = new Map<string, (e: MessageEvent) => void>();
+
+  constructor(
+    private url: string,
+    private options: SSETransportOptions = {}
+  ) {}
+
+  get state(): ConnectionState {
+    return this._state;
+  }
+
+  async connect(): Promise<void> {
+    if (this._state === 'connected' || this._state === 'connecting') {
+      return;
+    }
+
+    this.updateState('connecting');
+
+    return new Promise<void>((resolve, reject) => {
+      try {
+        this.eventSource = new EventSource(this.url, {
+          withCredentials: this.options.withCredentials
+        });
+      } catch (err) {
+        this.updateState('error', err as Error);
+        reject(err);
+        return;
+      }
+
+      let hasOpened = false;
+
+      this.eventSource.onopen = () => {
+        hasOpened = true;
+        this.updateState('connected');
+        resolve();
+      };
+
+      this.eventSource.onerror = (_event) => {
+        const error = new Error('SSE EventSource connection error');
+        if (!hasOpened) {
+          this.updateState('error', error);
+          this.disconnect();
+          reject(error);
+        } else {
+          // If already connected, transition to error so Connection triggers reconnect
+          this.updateState('error', error);
+          this.disconnect();
+        }
+      };
+
+      // Listen to generic messages
+      this.eventSource.onmessage = (event) => {
+        this.handleGenericMessage(event.data);
+      };
+
+      // Re-register any active topic listeners
+      for (const [topic, listener] of this.activeListeners.entries()) {
+        this.eventSource.addEventListener(topic, listener as any);
+      }
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.eventSource) {
+      // Remove all event listeners to avoid leaks
+      for (const [topic, listener] of this.activeListeners.entries()) {
+        this.eventSource.removeEventListener(topic, listener as any);
+      }
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.updateState('closed');
+  }
+
+  async publish(topic: string, data: any): Promise<void> {
+    if (this.options.publish) {
+      await this.options.publish(topic, data);
+      return;
+    }
+
+    if (this.options.publishUrl) {
+      const response = await fetch(this.options.publishUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({ topic, data })
+      });
+      if (!response.ok) {
+        throw new Error(`SSE publish HTTP request failed with status ${response.status}`);
+      }
+      return;
+    }
+
+    throw new Error(
+      'Publishing is not supported by SSE without a configured publishUrl or publish function'
+    );
+  }
+
+  async subscribe(topic: string, _filter?: Record<string, any>): Promise<void> {
+    if (this.activeListeners.has(topic)) return;
+
+    const listener = (event: MessageEvent) => {
+      try {
+        const parsed = JSON.parse(event.data);
+        this.messageCb?.(topic, parsed);
+      } catch (err) {
+        this.messageCb?.(topic, event.data);
+      }
+    };
+
+    this.activeListeners.set(topic, listener);
+
+    if (this.eventSource && this.eventSource.readyState === EventSource.OPEN) {
+      this.eventSource.addEventListener(topic, listener as any);
+    }
+  }
+
+  async unsubscribe(topic: string, _filter?: Record<string, any>): Promise<void> {
+    const listener = this.activeListeners.get(topic);
+    if (!listener) return;
+
+    if (this.eventSource) {
+      this.eventSource.removeEventListener(topic, listener as any);
+    }
+    this.activeListeners.delete(topic);
+  }
+
+  capabilities(): TransportCapabilities {
+    return {
+      publish: !!(this.options.publish || this.options.publishUrl),
+      subscribe: true,
+      latency: 'high'
+    };
+  }
+
+  onMessage(cb: (topic: string, data: any) => void): void {
+    this.messageCb = cb;
+  }
+
+  onStateChange(cb: (state: ConnectionState, error?: Error) => void): void {
+    this.stateCb = cb;
+  }
+
+  clone(): SSETransport {
+    return new SSETransport(this.url, this.options);
+  }
+
+  private handleGenericMessage(rawData: string): void {
+    if (!this.messageCb) return;
+
+    try {
+      const parsed = JSON.parse(rawData);
+      if (parsed && typeof parsed === 'object') {
+        const { topic, data } = parsed;
+        if (typeof topic === 'string') {
+          this.messageCb(topic, data !== undefined ? data : parsed);
+          return;
+        }
+      }
+      this.messageCb('message', parsed);
+    } catch (err) {
+      this.messageCb('message', rawData);
+    }
+  }
+
+  private updateState(state: ConnectionState, error?: Error): void {
+    if (this._state === state) return;
+    this._state = state;
+    if (this.stateCb) {
+      this.stateCb(state, error);
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}