@pellux/goodvibes-transport-realtime 0.18.3

package/README.md

@@ -0,0 +1,24 @@
+# @pellux/goodvibes-transport-realtime
+
+Realtime event-domain connectors for GoodVibes SSE and WebSocket integrations.
+
+Install:
+
+```bash
+npm install @pellux/goodvibes-transport-realtime
+```
+
+Example:
+
+```ts
+import {
+  createEventSourceConnector,
+  createRemoteRuntimeEvents,
+} from '@pellux/goodvibes-transport-realtime';
+
+const events = createRemoteRuntimeEvents(
+  createEventSourceConnector('https://goodvibes.example.com', 'token', fetch),
+);
+```
+
+Use this package when you want runtime-event subscriptions without pulling in the full umbrella SDK.

package/dist/domain-events.d.ts

@@ -0,0 +1,18 @@
+import { type RuntimeEventFeeds } from '@pellux/goodvibes-transport-core';
+type EventLike = {
+    readonly type: string;
+};
+export interface SerializedEventEnvelope<TEvent extends EventLike = EventLike> {
+    readonly type: string;
+    readonly timestamp?: number;
+    readonly ts?: number;
+    readonly traceId?: string;
+    readonly sessionId?: string;
+    readonly source?: string;
+    readonly payload: TEvent;
+}
+export type DomainEventConnector<TDomain extends string, TEvent extends EventLike = EventLike> = (domain: TDomain, onEnvelope: (envelope: SerializedEventEnvelope<TEvent>) => void) => void | Promise<() => void>;
+export type DomainEvents<TDomain extends string, TEvent extends EventLike = EventLike> = RuntimeEventFeeds<TDomain, TEvent>;
+export declare function createRemoteDomainEvents<TDomain extends string, TEvent extends EventLike = EventLike>(domains: readonly TDomain[], connect: DomainEventConnector<TDomain, TEvent>): DomainEvents<TDomain, TEvent>;
+export {};
+//# sourceMappingURL=domain-events.d.ts.map

package/dist/domain-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-events.d.ts","sourceRoot":"","sources":["../src/domain-events.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkD,KAAK,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAE1H,KAAK,SAAS,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,MAAM,WAAW,uBAAuB,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,oBAAoB,CAC9B,OAAO,SAAS,MAAM,EACtB,MAAM,SAAS,SAAS,GAAG,SAAS,IAClC,CACF,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,CAAC,QAAQ,EAAE,uBAAuB,CAAC,MAAM,CAAC,KAAK,IAAI,KAC5D,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;AAEhC,MAAM,MAAM,YAAY,CACtB,OAAO,SAAS,MAAM,EACtB,MAAM,SAAS,SAAS,GAAG,SAAS,IAClC,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAmIvC,wBAAgB,wBAAwB,CACtC,OAAO,SAAS,MAAM,EACtB,MAAM,SAAS,SAAS,GAAG,SAAS,EAEpC,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,OAAO,EAAE,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,GAC7C,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAK/B"}

package/dist/domain-events.js

@@ -0,0 +1,116 @@
+import { createRuntimeEventFeeds } from '@pellux/goodvibes-transport-core';
+function addListener(map, type, listener) {
+    const listeners = map.get(type) ?? new Set();
+    listeners.add(listener);
+    map.set(type, listeners);
+    return () => {
+        const existing = map.get(type);
+        if (!existing)
+            return;
+        existing.delete(listener);
+        if (existing.size === 0) {
+            map.delete(type);
+        }
+    };
+}
+function hasAnyListener(map) {
+    for (const listeners of map.values()) {
+        if (listeners.size > 0)
+            return true;
+    }
+    return false;
+}
+function isExpectedDisconnectError(error) {
+    return (error instanceof DOMException && error.name === 'AbortError') || (typeof error === 'object'
+        && error !== null
+        && 'name' in error
+        && error.name === 'AbortError');
+}
+function toEventEnvelope(envelope) {
+    return {
+        type: envelope.type,
+        ts: typeof envelope.ts === 'number'
+            ? envelope.ts
+            : typeof envelope.timestamp === 'number'
+                ? envelope.timestamp
+                : Date.now(),
+        traceId: typeof envelope.traceId === 'string' ? envelope.traceId : 'transport-trace',
+        sessionId: typeof envelope.sessionId === 'string' ? envelope.sessionId : 'transport',
+        source: typeof envelope.source === 'string' ? envelope.source : 'transport',
+        payload: envelope.payload,
+    };
+}
+function createRemoteDomainEventFeed(domain, connect) {
+    const payloadListeners = new Map();
+    const envelopeListeners = new Map();
+    let disconnect = null;
+    let connectPromise = null;
+    let disconnectPending = false;
+    const hasListeners = () => (hasAnyListener(payloadListeners)
+        || hasAnyListener(envelopeListeners));
+    const maybeConnect = () => {
+        if (disconnect || connectPromise)
+            return;
+        connectPromise = Promise.resolve(connect(domain, (envelope) => {
+            const eventType = typeof envelope.type === 'string' ? envelope.type : '';
+            if (!eventType)
+                return;
+            const payload = envelope.payload;
+            const typedEnvelope = toEventEnvelope(envelope);
+            for (const listener of payloadListeners.get(eventType) ?? []) {
+                listener(payload);
+            }
+            for (const listener of envelopeListeners.get(eventType) ?? []) {
+                listener(typedEnvelope);
+            }
+        })).then((cleanup) => {
+            if (typeof cleanup !== 'function')
+                return;
+            if (disconnectPending && !hasListeners()) {
+                cleanup();
+                return;
+            }
+            disconnect = cleanup;
+        }).catch((error) => {
+            if (!isExpectedDisconnectError(error)) {
+                throw error;
+            }
+        }).finally(() => {
+            connectPromise = null;
+            disconnectPending = false;
+        });
+    };
+    const maybeDisconnect = () => {
+        if (hasListeners())
+            return;
+        if (disconnect) {
+            disconnect();
+            disconnect = null;
+            return;
+        }
+        if (connectPromise) {
+            disconnectPending = true;
+        }
+    };
+    return {
+        on(type, listener) {
+            const unsubscribe = addListener(payloadListeners, type, listener);
+            maybeConnect();
+            return () => {
+                unsubscribe();
+                maybeDisconnect();
+            };
+        },
+        onEnvelope(type, listener) {
+            const unsubscribe = addListener(envelopeListeners, type, listener);
+            maybeConnect();
+            return () => {
+                unsubscribe();
+                maybeDisconnect();
+            };
+        },
+    };
+}
+export function createRemoteDomainEvents(domains, connect) {
+    return createRuntimeEventFeeds(domains, (domain) => createRemoteDomainEventFeed(domain, connect));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { DomainEventConnector, DomainEvents, SerializedEventEnvelope, } from './domain-events.js';
+export { createRemoteDomainEvents } from './domain-events.js';
+export type { RemoteRuntimeEvents, SerializedRuntimeEnvelope } from './runtime-events.js';
+export { buildEventSourceUrl, buildWebSocketUrl, createEventSourceConnector, createRemoteRuntimeEvents, createWebSocketConnector, } from './runtime-events.js';
+export type { RuntimeEventConnectorOptions } from './runtime-events.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createRemoteDomainEvents } from './domain-events.js';
+export { buildEventSourceUrl, buildWebSocketUrl, createEventSourceConnector, createRemoteRuntimeEvents, createWebSocketConnector, } from './runtime-events.js';

package/dist/runtime-events.d.ts

@@ -0,0 +1,20 @@
+import { type RuntimeEventDomain } from '@pellux/goodvibes-contracts';
+import { type AuthTokenResolver, type StreamReconnectPolicy } from '@pellux/goodvibes-transport-http';
+import { type DomainEventConnector, type DomainEvents, type SerializedEventEnvelope } from './domain-events.js';
+type RuntimeEventRecord = {
+    readonly type: string;
+};
+export type SerializedRuntimeEnvelope<TEvent extends RuntimeEventRecord = RuntimeEventRecord> = SerializedEventEnvelope<TEvent>;
+export type RemoteRuntimeEvents<TEvent extends RuntimeEventRecord = RuntimeEventRecord> = DomainEvents<RuntimeEventDomain, TEvent>;
+export interface RuntimeEventConnectorOptions {
+    readonly reconnect?: StreamReconnectPolicy;
+    readonly onError?: (error: unknown) => void;
+}
+type AuthTokenSource = string | null | undefined | AuthTokenResolver;
+export declare function createRemoteRuntimeEvents<TEvent extends RuntimeEventRecord = RuntimeEventRecord>(connect: DomainEventConnector<RuntimeEventDomain, TEvent>): RemoteRuntimeEvents<TEvent>;
+export declare function buildEventSourceUrl(baseUrl: string, domain: RuntimeEventDomain): string;
+export declare function buildWebSocketUrl(baseUrl: string, domains: readonly RuntimeEventDomain[]): string;
+export declare function createEventSourceConnector(baseUrl: string, token: AuthTokenSource, fetchImpl: typeof fetch, options?: RuntimeEventConnectorOptions): DomainEventConnector<RuntimeEventDomain, RuntimeEventRecord>;
+export declare function createWebSocketConnector(baseUrl: string, token: AuthTokenSource, WebSocketImpl: typeof WebSocket, options?: RuntimeEventConnectorOptions): DomainEventConnector<RuntimeEventDomain, RuntimeEventRecord>;
+export {};
+//# sourceMappingURL=runtime-events.d.ts.map

package/dist/runtime-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-events.d.ts","sourceRoot":"","sources":["../src/runtime-events.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAC7F,OAAO,EAAoB,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAA6D,MAAM,kCAAkC,CAAC;AAEnL,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,KAAK,kBAAkB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,yBAAyB,CAAC,MAAM,SAAS,kBAAkB,GAAG,kBAAkB,IAC1F,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAElC,MAAM,MAAM,mBAAmB,CAAC,MAAM,SAAS,kBAAkB,GAAG,kBAAkB,IACpF,YAAY,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;AAE3C,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED,KAAK,eAAe,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,iBAAiB,CAAC;AASrE,wBAAgB,yBAAyB,CAAC,MAAM,SAAS,kBAAkB,GAAG,kBAAkB,EAC9F,OAAO,EAAE,oBAAoB,CAAC,kBAAkB,EAAE,MAAM,CAAC,GACxD,mBAAmB,CAAC,MAAM,CAAC,CAK7B;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,kBAAkB,GACzB,MAAM,CAIR;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,MAAM,CAQR;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,OAAO,KAAK,EACvB,OAAO,GAAE,4BAAiC,GACzC,oBAAoB,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAiB9D;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,aAAa,EAAE,OAAO,SAAS,EAC/B,OAAO,GAAE,4BAAiC,GACzC,oBAAoB,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAuF9D"}

package/dist/runtime-events.js

@@ -0,0 +1,134 @@
+// Synced from goodvibes-tui/src/runtime/transports/runtime-events-client.ts
+import { RUNTIME_EVENT_DOMAINS } from '@pellux/goodvibes-contracts';
+import { resolveAuthToken, openRawServerSentEventStream as openServerSentEventStream } from '@pellux/goodvibes-transport-http';
+import { buildUrl, normalizeBaseUrl } from '@pellux/goodvibes-transport-http';
+import { createRemoteDomainEvents, } from './domain-events.js';
+async function resolveAuthTokenSource(source) {
+    if (typeof source === 'function') {
+        return await resolveAuthToken(null, source);
+    }
+    return source ?? null;
+}
+export function createRemoteRuntimeEvents(connect) {
+    return createRemoteDomainEvents(RUNTIME_EVENT_DOMAINS, connect);
+}
+export function buildEventSourceUrl(baseUrl, domain) {
+    const url = new URL(buildUrl(baseUrl, '/api/control-plane/events'));
+    url.searchParams.set('domains', domain);
+    return url.toString();
+}
+export function buildWebSocketUrl(baseUrl, domains) {
+    const base = normalizeBaseUrl(baseUrl);
+    const url = new URL('/api/control-plane/ws', base.replace(/^http(s?):\/\//, 'ws$1://'));
+    url.searchParams.set('clientKind', 'web');
+    if (domains.length > 0) {
+        url.searchParams.set('domains', domains.join(','));
+    }
+    return url.toString();
+}
+export function createEventSourceConnector(baseUrl, token, fetchImpl, options = {}) {
+    const handleError = options.onError ?? (options.reconnect?.enabled ? (() => { }) : undefined);
+    return async (domain, onEnvelope) => {
+        const url = buildEventSourceUrl(baseUrl, domain);
+        return await openServerSentEventStream(fetchImpl, url, {
+            onEvent: (eventName, payload) => {
+                if (eventName !== domain)
+                    return;
+                if (!payload || typeof payload !== 'object')
+                    return;
+                onEnvelope(payload);
+            },
+            onError: handleError,
+        }, {
+            reconnect: options.reconnect,
+            getAuthToken: typeof token === 'function' ? token : undefined,
+            authToken: typeof token === 'function' ? null : token,
+        });
+    };
+}
+export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options = {}) {
+    return async (domain, onEnvelope) => {
+        const url = buildWebSocketUrl(baseUrl, [domain]);
+        const reconnect = options.reconnect;
+        const enabled = reconnect?.enabled ?? false;
+        let stopped = false;
+        let reconnectAttempt = 0;
+        let socket = null;
+        let reconnectTimer = null;
+        const closeSocket = () => {
+            if (!socket)
+                return;
+            socket.removeEventListener('open', onOpen);
+            socket.removeEventListener('message', onMessage);
+            socket.removeEventListener('close', onClose);
+            socket.removeEventListener('error', onError);
+            socket.close();
+            socket = null;
+        };
+        const scheduleReconnect = () => {
+            if (!enabled || stopped)
+                return;
+            const nextAttempt = reconnectAttempt + 1;
+            const maxAttempts = reconnect?.maxAttempts ?? Number.POSITIVE_INFINITY;
+            if (nextAttempt >= maxAttempts)
+                return;
+            reconnectAttempt = nextAttempt;
+            const baseDelayMs = reconnect?.baseDelayMs ?? 500;
+            const maxDelayMs = reconnect?.maxDelayMs ?? 5_000;
+            const backoffFactor = reconnect?.backoffFactor ?? 2;
+            const delayMs = Math.min(maxDelayMs, Math.floor(baseDelayMs * (backoffFactor ** Math.max(0, nextAttempt - 1))));
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = null;
+                void connect();
+            }, delayMs);
+        };
+        const onOpen = async () => {
+            reconnectAttempt = 0;
+            const authToken = await resolveAuthTokenSource(token);
+            if (!authToken || !socket)
+                return;
+            socket.send(JSON.stringify({
+                type: 'auth',
+                token: authToken,
+                domains: [domain],
+            }));
+        };
+        const onMessage = (event) => {
+            try {
+                const frame = JSON.parse(event.data);
+                if (frame.type === 'event' && frame.event === domain && frame.payload && typeof frame.payload === 'object') {
+                    onEnvelope(frame.payload);
+                }
+            }
+            catch {
+                // Ignore malformed frames.
+            }
+        };
+        const onClose = () => {
+            closeSocket();
+            scheduleReconnect();
+        };
+        const onError = (event) => {
+            options.onError?.(event);
+        };
+        const connect = async () => {
+            if (stopped)
+                return;
+            closeSocket();
+            const nextSocket = new WebSocketImpl(url);
+            socket = nextSocket;
+            nextSocket.addEventListener('open', onOpen);
+            nextSocket.addEventListener('message', onMessage);
+            nextSocket.addEventListener('close', onClose);
+            nextSocket.addEventListener('error', onError);
+        };
+        await connect();
+        return () => {
+            stopped = true;
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+            }
+            closeSocket();
+        };
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@pellux/goodvibes-transport-realtime",
+  "version": "0.18.3",
+  "description": "Realtime event-domain connectors for GoodVibes SSE and WebSocket integrations.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mgd34msu/goodvibes-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mgd34msu/goodvibes-sdk/issues"
+  },
+  "homepage": "https://github.com/mgd34msu/goodvibes-sdk",
+  "keywords": [
+    "goodvibes",
+    "sdk",
+    "realtime",
+    "websocket",
+    "events"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pellux/goodvibes-contracts": "0.18.3",
+    "@pellux/goodvibes-transport-core": "0.18.3",
+    "@pellux/goodvibes-transport-http": "0.18.3"
+  }
+}