@pellux/goodvibes-transport-realtime 0.30.2 → 0.33.0

package/README.md

@@ -1,8 +1,8 @@
 # @pellux/goodvibes-transport-realtime
 
-Internal workspace package backing `@pellux/goodvibes-sdk/transport-realtime`.
+Public GoodVibes realtime transport package for event-domain connectors over SSE and WebSocket.
 
-Consumers should install `@pellux/goodvibes-sdk` and import this surface from the umbrella package.
+Most applications should install `@pellux/goodvibes-sdk` and import `@pellux/goodvibes-sdk/transport-realtime`. Install this package directly when you only need realtime connectors.
 
 Consumer import:
 
@@ -17,4 +17,4 @@ const events = createRemoteRuntimeEvents(
 );
 ```
 
-Use this surface when you want runtime-event subscriptions without pulling in the full umbrella SDK.
+Use this surface when you want runtime-event subscriptions without pulling in the full main SDK.

package/dist/domain-events.d.ts

@@ -1,20 +1,16 @@
-import { type RuntimeEventFeeds } from '@pellux/goodvibes-transport-core';
-type EventLike = {
-    readonly type: string;
-};
+import { type EventLike, type RuntimeEventFeeds } from '@pellux/goodvibes-transport-core';
 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 ts?: number | undefined;
+    readonly traceId?: string | undefined;
+    readonly sessionId?: string | undefined;
+    readonly source?: string | undefined;
     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 interface RemoteDomainEventsOptions<TDomain extends string = string> {
-    readonly onConnectionError?: (error: Error, domain: TDomain) => void;
+    readonly onConnectionError?: ((error: Error, domain: TDomain) => void) | undefined;
 }
 export declare function createRemoteDomainEvents<TDomain extends string, TEvent extends EventLike = EventLike>(domains: readonly TDomain[], connect: DomainEventConnector<TDomain, TEvent>, options?: RemoteDomainEventsOptions<TDomain>): DomainEvents<TDomain, TEvent>;
 /**
@@ -43,5 +39,4 @@ export declare function createRemoteDomainEvents<TDomain extends string, TEvent
  * });
  */
 export declare function forSession<TDomain extends string, TEvent extends EventLike = EventLike>(events: DomainEvents<TDomain, TEvent>, sessionId: string): DomainEvents<TDomain, TEvent>;
-export {};
 //# sourceMappingURL=domain-events.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"domain-events.d.ts","sourceRoot":"","sources":["../src/domain-events.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,kCAAkC,CAAC;AAE1C,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;AAEvC,MAAM,WAAW,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IACxE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACtE;AAyID,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,EAC9C,OAAO,GAAE,yBAAyB,CAAC,OAAO,CAAM,GAC/C,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAK/B;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CACxB,OAAO,SAAS,MAAM,EACtB,MAAM,SAAS,SAAS,GAAG,SAAS,EAEpC,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,EACrC,SAAS,EAAE,MAAM,GAChB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAY/B"}
+{"version":3,"file":"domain-events.d.ts","sourceRoot":"","sources":["../src/domain-events.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,SAAS,EAEd,KAAK,iBAAiB,EACvB,MAAM,kCAAkC,CAAC;AAE1C,MAAM,WAAW,uBAAuB,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,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;AAEvC,MAAM,WAAW,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IACxE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACpF;AAmJD,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,EAC9C,OAAO,GAAE,yBAAyB,CAAC,OAAO,CAAM,GAC/C,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAK/B;AA4ED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CACxB,OAAO,SAAS,MAAM,EACtB,MAAM,SAAS,SAAS,GAAG,SAAS,EAEpC,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,EACrC,SAAS,EAAE,MAAM,GAChB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAY/B"}

package/dist/domain-events.js

@@ -32,14 +32,10 @@ function reportUnexpectedConnectionError(error, domain, options) {
 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',
+        ts: typeof envelope.ts === 'number' ? envelope.ts : Date.now(),
+        traceId: typeof envelope.traceId === 'string' ? envelope.traceId : undefined,
+        sessionId: typeof envelope.sessionId === 'string' ? envelope.sessionId : undefined,
+        source: typeof envelope.source === 'string' ? envelope.source : undefined,
         payload: envelope.payload,
     };
 }
@@ -60,15 +56,24 @@ function createRemoteDomainEventFeed(domain, connect, options) {
                 return;
             const payload = envelope.payload;
             const typedEnvelope = toEventEnvelope(envelope);
-            for (const listener of payloadListeners.get(eventType) ?? []) {
+            // snapshot Sets before iterating to prevent skipped listeners
+            // from concurrent subscribe/unsubscribe during dispatch (project pattern: event-bus-snapshot).
+            for (const listener of [...(payloadListeners.get(eventType) ?? [])]) {
                 listener(payload);
             }
-            for (const listener of envelopeListeners.get(eventType) ?? []) {
+            for (const listener of [...(envelopeListeners.get(eventType) ?? [])]) {
                 listener(typedEnvelope);
             }
         })).then((cleanup) => {
-            if (typeof cleanup !== 'function')
+            // when connect() returns a non-function cleanup (void), we have no
+            // way to honour a pending disconnect request. Log the gap and bail. Callers
+            // must return a cleanup function whenever they establish a real connection.
+            if (typeof cleanup !== 'function') {
+                if (disconnectPending) {
+                    reportUnexpectedConnectionError(new Error('Domain event connector resolved without a cleanup function while a disconnect was pending. The connection cannot be closed.'), domain, options);
+                }
                 return;
+            }
             if (disconnectPending && !hasListeners()) {
                 cleanup();
                 return;
@@ -123,22 +128,59 @@ export function createRemoteDomainEvents(domains, connect, options = {}) {
  *
  * Unsubscribe handles returned by `on` / `onEnvelope` on the filtered feed
  * correctly remove the underlying listener from the original feed.
+ *
+ * Uses a single shared envelope listener per event type so that N
+ * subscribers for the same (feed, sessionId, type) triple consume only one
+ * envelope-listener slot on the underlying feed instead of N.
  */
 function createFilteredFeed(feed, sessionId) {
+    // Shared listeners: one envelope-level subscription per event type.
+    const sharedByType = new Map();
+    function getOrCreateShared(type) {
+        const existing = sharedByType.get(type);
+        if (existing)
+            return existing;
+        const payloadListeners = new Set();
+        const envelopeListeners = new Set();
+        const unsub = feed.onEnvelope(type, (envelope) => {
+            if (envelope.sessionId !== sessionId)
+                return;
+            for (const pl of payloadListeners)
+                pl(envelope.payload);
+            for (const el of envelopeListeners)
+                el(envelope);
+        });
+        const shared = { unsub, payloadListeners, envelopeListeners };
+        sharedByType.set(type, shared);
+        return shared;
+    }
+    function removeSharedIfEmpty(type) {
+        const shared = sharedByType.get(type);
+        if (!shared)
+            return;
+        if (shared.payloadListeners.size === 0 && shared.envelopeListeners.size === 0) {
+            shared.unsub();
+            sharedByType.delete(type);
+        }
+    }
     return {
         on(type, listener) {
-            return feed.onEnvelope(type, (envelope) => {
-                if (envelope.sessionId !== sessionId)
-                    return;
-                listener(envelope.payload);
-            });
+            const shared = getOrCreateShared(type);
+            const typedListener = listener;
+            shared.payloadListeners.add(typedListener);
+            return () => {
+                shared.payloadListeners.delete(typedListener);
+                removeSharedIfEmpty(type);
+            };
         },
         onEnvelope(type, listener) {
-            return feed.onEnvelope(type, (envelope) => {
-                if (envelope.sessionId !== sessionId)
-                    return;
-                listener(envelope);
-            });
+            const shared = getOrCreateShared(type);
+            const typedListener = listener;
+            shared.envelopeListeners.add(typedListener);
+            return () => {
+                shared.envelopeListeners.delete(typedListener);
+                removeSharedIfEmpty(type);
+            };
         },
     };
 }

package/dist/index.d.ts

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

package/dist/index.d.ts.map

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

package/dist/index.js

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

package/dist/runtime-events.d.ts

@@ -1,16 +1,13 @@
-import { type RuntimeEventDomain } from '@pellux/goodvibes-contracts';
+import { type RuntimeEventDomain, type RuntimeEventRecord } from '@pellux/goodvibes-contracts';
 import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
 import { type AuthTokenResolver, type StreamReconnectPolicy } from '@pellux/goodvibes-transport-http';
 import { type TransportObserver } from '@pellux/goodvibes-transport-core';
 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 RemoteRuntimeEventsOptions {
-    readonly onError?: (error: Error, domain: RuntimeEventDomain) => void;
-    readonly observer?: TransportObserver;
+    readonly onError?: ((error: Error, domain: RuntimeEventDomain) => void) | undefined;
+    readonly observer?: TransportObserver | undefined;
 }
 /**
  * Returns a filtered view of a {@link RemoteRuntimeEvents} object where every
@@ -40,23 +37,41 @@ export interface RemoteRuntimeEventsOptions {
  */
 export { forSession as forSessionRuntime } from './domain-events.js';
 export interface RuntimeEventConnectorOptions {
-    readonly reconnect?: StreamReconnectPolicy;
-    readonly onError?: (error: unknown) => void;
-    readonly observer?: TransportObserver;
+    readonly reconnect?: StreamReconnectPolicy | undefined;
+    readonly onError?: ((error: unknown) => void) | undefined;
+    readonly onOpen?: (() => void) | undefined;
+    readonly onReconnect?: ((attempt: number, delayMs: number) => void) | undefined;
+    readonly observer?: TransportObserver | undefined;
     /**
      * Called once the WebSocket connector is set up, providing an `emitLocal`
      * function the caller can use to send messages over this connection.
      * Primarily for tests and local harnesses that need to inject outbound frames.
      */
-    readonly onEmitter?: (emitLocal: (data: string) => void) => void;
+    readonly onEmitter?: ((emitLocal: (data: string) => void) => void) | undefined;
 }
-type AuthTokenSource = string | null | undefined | AuthTokenResolver;
+export type AuthTokenSource = string | null | undefined | AuthTokenResolver;
 /** Default max reconnect attempts for WebSocket connections (finite to prevent infinite auth loops). */
 export declare const DEFAULT_WS_MAX_ATTEMPTS = 10;
 export declare class WebSocketTransportError extends GoodVibesSdkError {
-    constructor(message: string, options?: {
+    /**
+     * WebSocket runtime-event transport error.
+     *
+     * Canonical internal codes are `WS_CLOSE_ABNORMAL`,
+     * `WS_EVENT_ERROR`, `WS_QUEUE_OVERFLOW`, `WS_REMOTE_ERROR`, and
+     * `WS_FRAME_TOO_LARGE`.
+     *
+     * Overrides Symbol.hasInstance to enable cross-realm instanceof checks.
+     * Without this, `instanceof WebSocketTransportError` in a different realm
+     * (e.g. a Cloudflare Worker or cross-frame context) falls through to the base
+     * GoodVibesSdkError brand only and cannot distinguish WS errors from other
+     * SDK errors. The brand check here also guards against plain objects with a
+     * matching `code`.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string, options: {
         readonly cause?: unknown;
         readonly hint?: string;
+        readonly code: string;
     });
 }
 export declare function createRemoteRuntimeEvents<TEvent extends RuntimeEventRecord = RuntimeEventRecord>(connect: DomainEventConnector<RuntimeEventDomain, TEvent>, options?: RemoteRuntimeEventsOptions): RemoteRuntimeEvents<TEvent>;

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

@@ -1 +1 @@
-{"version":3,"file":"runtime-events.d.ts","sourceRoot":"","sources":["../src/runtime-events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-events.d.ts","sourceRoot":"","sources":["../src/runtime-events.ts"],"names":[],"mappings":"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"}

package/dist/runtime-events.js

@@ -1,4 +1,4 @@
-import { RUNTIME_EVENT_DOMAINS } from '@pellux/goodvibes-contracts';
+import { RUNTIME_EVENT_DOMAINS, TypedSerializedEventEnvelopeSchema, } from '@pellux/goodvibes-contracts';
 import { ConfigurationError, GoodVibesSdkError } from '@pellux/goodvibes-errors';
 import { normalizeAuthToken, openRawServerSentEventStream as openServerSentEventStream, normalizeStreamReconnectPolicy, getStreamReconnectDelay, } from '@pellux/goodvibes-transport-http';
 import { buildUrl, normalizeBaseUrl } from '@pellux/goodvibes-transport-http';
@@ -35,6 +35,13 @@ export { forSession as forSessionRuntime } from './domain-events.js';
 export const DEFAULT_WS_MAX_ATTEMPTS = 10;
 /** Maximum number of messages that may be queued in the outbound queue before the oldest entry is dropped. */
 const MAX_OUTBOUND_QUEUE = 1024;
+/** Maximum size for a single queued outbound WebSocket message. */
+const MAX_OUTBOUND_MESSAGE_BYTES = 1024 * 1024;
+/** Maximum total queued outbound WebSocket payload bytes. */
+const MAX_OUTBOUND_QUEUE_BYTES = 16 * 1024 * 1024;
+/** Maximum size accepted for one inbound WebSocket runtime-event frame. */
+const MAX_INBOUND_FRAME_BYTES = 1024 * 1024;
+const textEncoder = new TextEncoder();
 function getSocketOpenState(WebSocketImpl) {
     return typeof WebSocketImpl.OPEN === 'number' ? WebSocketImpl.OPEN : 1;
 }
@@ -42,9 +49,47 @@ function isSocketOpen(socket, WebSocketImpl) {
     return socket.readyState === getSocketOpenState(WebSocketImpl);
 }
 export class WebSocketTransportError extends GoodVibesSdkError {
-    constructor(message, options = {}) {
+    /**
+     * WebSocket runtime-event transport error.
+     *
+     * Canonical internal codes are `WS_CLOSE_ABNORMAL`,
+     * `WS_EVENT_ERROR`, `WS_QUEUE_OVERFLOW`, `WS_REMOTE_ERROR`, and
+     * `WS_FRAME_TOO_LARGE`.
+     *
+     * Overrides Symbol.hasInstance to enable cross-realm instanceof checks.
+     * Without this, `instanceof WebSocketTransportError` in a different realm
+     * (e.g. a Cloudflare Worker or cross-frame context) falls through to the base
+     * GoodVibesSdkError brand only and cannot distinguish WS errors from other
+     * SDK errors. The brand check here also guards against plain objects with a
+     * matching `code`.
+     */
+    static [Symbol.hasInstance](value) {
+        if (this !== WebSocketTransportError) {
+            return typeof value === 'object'
+                && value !== null
+                && this.prototype.isPrototypeOf(value);
+        }
+        // Require the base SDK brand AND a WS-specific code prefix to prevent plain
+        // objects like { code: 'WEBSOCKET_TRANSPORT_ERROR' } from passing.
+        // Use an explicit allowlist of canonical WS codes rather than
+        // the open-ended 'WS_' prefix check which would match any hand-crafted
+        // GoodVibesSdkError with a WS_* code.
+        const CANONICAL_WS_CODES = new Set([
+            'WEBSOCKET_TRANSPORT_ERROR',
+            'WS_CLOSE_ABNORMAL',
+            'WS_EVENT_ERROR',
+            'WS_QUEUE_OVERFLOW',
+            'WS_REMOTE_ERROR',
+            'WS_FRAME_TOO_LARGE',
+        ]);
+        return GoodVibesSdkError[Symbol.hasInstance](value)
+            && typeof value.code === 'string'
+            && CANONICAL_WS_CODES.has(String(value.code));
+    }
+    // Use one of: WS_CLOSE_ABNORMAL, WS_EVENT_ERROR, WS_QUEUE_OVERFLOW, WS_REMOTE_ERROR, WS_FRAME_TOO_LARGE.
+    constructor(message, options) {
         super(message, {
-            code: 'WEBSOCKET_TRANSPORT_ERROR',
+            code: options.code,
             category: 'network',
             source: 'transport',
             recoverable: true,
@@ -57,7 +102,7 @@ export class WebSocketTransportError extends GoodVibesSdkError {
 export function createRemoteRuntimeEvents(connect, options = {}) {
     const domainOptions = {
         onConnectionError: (error, domain) => {
-            invokeTransportObserver(() => options.observer?.onError?.(error));
+            invokeTransportObserver(() => options.observer?.onError?.(error), options.observer?.onObserverError);
             options.onError?.(error, domain);
         },
     };
@@ -69,6 +114,9 @@ export function buildEventSourceUrl(baseUrl, domain) {
     return url.toString();
 }
 export function buildWebSocketUrl(baseUrl, domains) {
+    // protocol validation and error messaging here mirrors normalizeBaseUrl in
+    // transport-http/src/paths.ts. These two code paths enforce the same rule with
+    // different error messages. If the supported protocol set ever changes, update both.
     const url = new URL('/api/control-plane/ws', normalizeBaseUrl(baseUrl));
     if (url.protocol === 'http:') {
         url.protocol = 'ws:';
@@ -114,7 +162,7 @@ export function createEventSourceConnector(baseUrl, token, fetchImpl, options =
         const sseHeaders = {};
         await injectTraceparentAsync(sseHeaders);
         // Notify observer of outbound SSE connection attempt.
-        invokeTransportObserver(() => observer?.onTransportActivity?.({ direction: 'send', url, kind: 'sse' }));
+        invokeTransportObserver(() => observer?.onTransportActivity?.({ direction: 'send', url, kind: 'sse' }), observer?.onObserverError);
         try {
             return await openServerSentEventStream(fetchImpl, url, {
                 onEvent: (eventName, payload) => {
@@ -130,11 +178,11 @@ export function createEventSourceConnector(baseUrl, token, fetchImpl, options =
                         if (envelope.payload) {
                             observer?.onEvent?.(envelope.payload);
                         }
-                    });
+                    }, observer?.onObserverError);
                 },
                 onError: (err) => {
                     const streamError = transportErrorFromUnknown(err, 'SSE runtime event stream error');
-                    invokeTransportObserver(() => observer?.onError?.(streamError));
+                    invokeTransportObserver(() => observer?.onError?.(streamError), observer?.onObserverError);
                     handleError?.(streamError);
                 },
             }, {
@@ -145,7 +193,7 @@ export function createEventSourceConnector(baseUrl, token, fetchImpl, options =
         }
         catch (error) {
             const connectionError = transportErrorFromUnknown(error, 'SSE runtime event connection failed');
-            invokeTransportObserver(() => observer?.onError?.(connectionError));
+            invokeTransportObserver(() => observer?.onError?.(connectionError), observer?.onObserverError);
             handleError?.(connectionError);
             throw connectionError;
         }
@@ -168,12 +216,18 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
         let hasReceivedMessage = false;
         let socket = null;
         let reconnectTimer = null;
-        // Bounded outbound message queue — max MAX_OUTBOUND_QUEUE entries, drop-oldest policy.
+        // Bounded outbound message queue — max entries and total bytes, drop-oldest policy.
         // Messages pushed while the socket is not yet open or is reconnecting are buffered here
         // and flushed on the next successful open event.
         const outboundQueue = [];
+        let outboundQueueBytes = 0;
         let droppedOutboundCount = 0;
+        // track overflow notification count so we fire on every overflow burst
+        // rather than once per connection lifetime. queueOverflowNotified is reset in
+        // flushOutboundQueue when the connection restores.
         let queueOverflowNotified = false;
+        let overflowEventCount = 0;
+        const getAuthToken = normalizeAuthToken(token ?? undefined);
         /**
          * Enqueue a message for delivery over this WebSocket connection.
          *
@@ -181,9 +235,11 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
          * If the socket is not yet open (or is reconnecting), the message is
          * buffered and will be flushed once the connection is re-established.
          *
-         * When the buffer is full (> MAX_OUTBOUND_QUEUE), the oldest pending
-         * message is silently dropped and a counter is incremented. Callers that
-         * need back-pressure should check `socket?.readyState` before calling.
+         * When the buffer is full by count or byte budget, the oldest pending
+         * message is dropped and a counter is incremented. A single message larger
+         * than MAX_OUTBOUND_MESSAGE_BYTES is rejected instead of being queued.
+         * Callers that need back-pressure should check `socket?.readyState` before
+         * calling.
          *
          * @param data - Serialised message string to send.
          */
@@ -192,24 +248,52 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                 socket.send(data);
                 return;
             }
-            if (outboundQueue.length >= MAX_OUTBOUND_QUEUE) {
-                // Drop oldest message to make room (drop-oldest policy).
-                outboundQueue.shift();
+            const sizeBytes = textEncoder.encode(data).byteLength;
+            if (sizeBytes > MAX_OUTBOUND_MESSAGE_BYTES) {
+                droppedOutboundCount += 1;
+                overflowEventCount += 1;
+                // fire on first overflow and every 10th thereafter so bursts between
+                // reconnects stay observable after the first.
+                if (overflowEventCount === 1 || overflowEventCount % 10 === 0) {
+                    queueOverflowNotified = true;
+                    options.onError?.(new WebSocketTransportError(`WebSocket outbound message too large (${sizeBytes} bytes, limit ${MAX_OUTBOUND_MESSAGE_BYTES}). Dropping the message while the socket reconnects.`, {
+                        code: 'WS_QUEUE_OVERFLOW',
+                        hint: 'Split large runtime event frames before enqueueing them while the WebSocket is disconnected.',
+                    }));
+                }
+                return;
+            }
+            while (outboundQueue.length >= MAX_OUTBOUND_QUEUE
+                || outboundQueueBytes + sizeBytes > MAX_OUTBOUND_QUEUE_BYTES) {
+                const dropped = outboundQueue.shift();
+                if (!dropped)
+                    break;
+                outboundQueueBytes -= dropped.sizeBytes;
                 droppedOutboundCount += 1;
-                if (!queueOverflowNotified) {
+                overflowEventCount += 1;
+                // fire on first overflow and every 10th thereafter.
+                if (overflowEventCount === 1 || overflowEventCount % 10 === 0) {
                     queueOverflowNotified = true;
-                    options.onError?.(new WebSocketTransportError(`WebSocket outbound queue full (limit ${MAX_OUTBOUND_QUEUE}). Dropping oldest messages until the socket reconnects.`, {
+                    options.onError?.(new WebSocketTransportError(`WebSocket outbound queue full (limit ${MAX_OUTBOUND_QUEUE} messages / ${MAX_OUTBOUND_QUEUE_BYTES} bytes). Dropping oldest messages until the socket reconnects.`, {
+                        code: 'WS_QUEUE_OVERFLOW',
                         hint: 'Wait for the runtime event WebSocket to reconnect before sending more local frames.',
                     }));
                 }
             }
-            outboundQueue.push(data);
+            outboundQueue.push({ data, sizeBytes });
+            outboundQueueBytes += sizeBytes;
         };
         // Notify caller of the emitter handle for tests and local frame injection.
         options.onEmitter?.(emitLocal);
         const closeSocket = () => {
             if (!socket)
                 return;
+            // clear any pending reconnect timer so close() cannot schedule
+            // a second reconnect while one is already pending.
+            if (reconnectTimer) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
             socket.removeEventListener('open', onOpen);
             socket.removeEventListener('message', onMessage);
             socket.removeEventListener('close', onClose);
@@ -226,24 +310,37 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
             reconnectAttempt = nextAttempt;
             // Use shared backoff helper so WS and SSE are on identical schedule.
             const delayMs = getStreamReconnectDelay(nextAttempt, reconnectPolicy);
+            options.onReconnect?.(nextAttempt, delayMs);
             reconnectTimer = setTimeout(() => {
                 reconnectTimer = null;
                 void connect().catch((error) => {
                     const connectionError = transportErrorFromUnknown(error, 'WebSocket runtime event reconnect failed');
-                    invokeTransportObserver(() => observer?.onError?.(connectionError));
+                    invokeTransportObserver(() => observer?.onError?.(connectionError), observer?.onObserverError);
                     options.onError?.(connectionError);
                     scheduleReconnect();
                 });
             }, delayMs);
+            // Do not keep Node/Bun processes alive solely to wait for a reconnect.
             reconnectTimer.unref?.();
         };
         const flushOutboundQueue = (ws) => {
+            // re-check socket open before each send so queued messages are not
+            // lost when the socket closes between the auth frame and the drain loop.
+            // Messages that cannot be sent are left in the queue for the next reconnect cycle.
             while (outboundQueue.length > 0) {
-                const data = outboundQueue.shift();
-                if (data === undefined)
+                if (!isSocketOpen(ws, WebSocketImpl)) {
+                    // Socket closed mid-drain; leave the remaining items for the next reconnect.
                     break;
-                ws.send(data);
+                }
+                const item = outboundQueue.shift();
+                if (!item)
+                    break;
+                outboundQueueBytes -= item.sizeBytes;
+                ws.send(item.data);
             }
+            // Reset overflow state on successful reconnect so the next burst is reported.
+            queueOverflowNotified = false;
+            overflowEventCount = 0;
         };
         const onOpen = async (event) => {
             const candidateSocket = event.currentTarget;
@@ -251,11 +348,18 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                 ? candidateSocket
                 : socket;
             try {
-                const authToken = (await normalizeAuthToken(token ?? undefined)()) ?? null;
-                if (!authToken || !openedSocket || stopped || socket !== openedSocket)
+                const authToken = (await getAuthToken()) ?? null;
+                // surface a diagnostic error when the token resolver returns null
+                // before a reconnect loop is scheduled.
+                if (authToken === null || authToken === undefined) {
+                    options.onError?.(new ConfigurationError('WebSocket auth token resolver returned null. Check transport options.authToken / options.getAuthToken.', { code: 'SDK_AUTH_TOKEN_MISSING', source: 'config' }));
+                    closeSocket();
+                    return;
+                }
+                if (!openedSocket || stopped || socket !== openedSocket)
                     return;
                 // Notify observer of outbound WS connection.
-                invokeTransportObserver(() => observer?.onTransportActivity?.({ direction: 'send', url, kind: 'ws' }));
+                invokeTransportObserver(() => observer?.onTransportActivity?.({ direction: 'send', url, kind: 'ws' }), observer?.onObserverError);
                 // Send auth frame first, then drain any messages buffered during resolution.
                 // Inject traceparent into the auth frame for W3C Trace Context propagation over WebSocket.
                 const wsTraceHeaders = {};
@@ -270,10 +374,11 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                     ...(wsTraceHeaders['tracestate'] ? { tracestate: wsTraceHeaders['tracestate'] } : {}),
                 }));
                 flushOutboundQueue(openedSocket);
+                options.onOpen?.();
             }
             catch (error) {
                 const sendError = transportErrorFromUnknown(error, 'WebSocket send failed');
-                invokeTransportObserver(() => observer?.onError?.(sendError));
+                invokeTransportObserver(() => observer?.onError?.(sendError), observer?.onObserverError);
                 options.onError?.(sendError);
                 closeSocket();
                 scheduleReconnect();
@@ -281,14 +386,33 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
         };
         const onMessage = (event) => {
             try {
+                if (typeof event.data !== 'string') {
+                    throw new WebSocketTransportError('WebSocket runtime event frame was not a string payload.', { code: 'WS_EVENT_ERROR' });
+                }
+                // cheap pre-check (1 byte per char worst case) avoids allocating
+                // the full UTF-8 buffer for clearly-oversized frames. Only fall through
+                // to textEncoder.encode when within the fast bound.
+                if (event.data.length > MAX_INBOUND_FRAME_BYTES) {
+                    throw new WebSocketTransportError(`WebSocket runtime event frame too large (>${MAX_INBOUND_FRAME_BYTES} bytes, limit ${MAX_INBOUND_FRAME_BYTES}).`, { code: 'WS_FRAME_TOO_LARGE' });
+                }
+                const frameBytes = textEncoder.encode(event.data).byteLength;
+                if (frameBytes > MAX_INBOUND_FRAME_BYTES) {
+                    throw new WebSocketTransportError(`WebSocket runtime event frame too large (${frameBytes} bytes, limit ${MAX_INBOUND_FRAME_BYTES}).`, { code: 'WS_FRAME_TOO_LARGE' });
+                }
                 const frame = JSON.parse(event.data);
                 if (!hasReceivedMessage) {
                     hasReceivedMessage = true;
                     reconnectAttempt = 0;
                 }
-                queueOverflowNotified = false;
                 if (frame.type === 'event' && frame.event === domain && frame.payload && typeof frame.payload === 'object') {
-                    const wsPayload = frame.payload;
+                    const parsedPayload = TypedSerializedEventEnvelopeSchema.safeParse(frame.payload);
+                    if (!parsedPayload.success) {
+                        throw new WebSocketTransportError('WebSocket runtime event payload failed schema validation.', {
+                            code: 'WS_EVENT_ERROR',
+                            cause: parsedPayload.error,
+                        });
+                    }
+                    const wsPayload = parsedPayload.data;
                     onEnvelope(wsPayload);
                     // Notify observer of inbound WS event.
                     invokeTransportObserver(() => {
@@ -296,7 +420,7 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                         if (wsPayload.payload) {
                             observer?.onEvent?.(wsPayload.payload);
                         }
-                    });
+                    }, observer?.onObserverError);
                 }
             }
             catch (error) {
@@ -306,7 +430,7 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                     recoverable: true,
                     cause: error,
                 });
-                invokeTransportObserver(() => observer?.onError?.(malformed));
+                invokeTransportObserver(() => observer?.onError?.(malformed), observer?.onObserverError);
                 options.onError?.(malformed);
             }
         };
@@ -314,15 +438,15 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
             hasReceivedMessage = false;
             if (!stopped && event.code !== 1000 && event.code !== 1005) {
                 const closeError = webSocketCloseError(event);
-                invokeTransportObserver(() => observer?.onError?.(closeError));
+                invokeTransportObserver(() => observer?.onError?.(closeError), observer?.onObserverError);
                 options.onError?.(closeError);
             }
             closeSocket();
             scheduleReconnect();
         };
         const onError = (event) => {
-            const streamError = webSocketEventError(event);
-            invokeTransportObserver(() => observer?.onError?.(streamError));
+            const streamError = webSocketEventError(event, socket, url);
+            invokeTransportObserver(() => observer?.onError?.(streamError), observer?.onObserverError);
             options.onError?.(streamError);
         };
         const connect = async () => {
@@ -336,26 +460,28 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
             nextSocket.addEventListener('close', onClose);
             nextSocket.addEventListener('error', onError);
         };
-        try {
-            await connect();
-        }
-        catch (error) {
-            const connectionError = transportErrorFromUnknown(error, 'WebSocket runtime event connection failed');
-            invokeTransportObserver(() => observer?.onError?.(connectionError));
-            options.onError?.(connectionError);
-            throw connectionError;
-        }
+        // connect() is async but new WebSocket() does not throw synchronously;
+        // transport-level failures surface through onError/onClose. The try/catch
+        // here was dead code. Remove it and rely entirely on those event handlers.
+        void connect();
         return () => {
             stopped = true;
             if (reconnectTimer) {
                 clearTimeout(reconnectTimer);
             }
             closeSocket();
+            // reset the outbound buffer on disposal so a future reconnect
+            // (or re-use of the returned cleanup path in tests) does not accumulate
+            // stale byte totals. Both must be reset together to prevent accounting drift.
+            outboundQueue.length = 0;
+            outboundQueueBytes = 0;
         };
     };
 }
 function webSocketCloseError(event) {
-    const reason = typeof event.reason === 'string' ? event.reason.trim() : '';
+    // Cap reason length to prevent oversized error messages.
+    const rawReason = typeof event.reason === 'string' ? event.reason.trim() : '';
+    const reason = rawReason.length > 256 ? `${rawReason.slice(0, 256)}…` : rawReason;
     const code = typeof event.code === 'number' ? event.code : 1005;
     const wasClean = typeof event.wasClean === 'boolean' ? event.wasClean : false;
     const detail = [
@@ -364,18 +490,41 @@ function webSocketCloseError(event) {
         `wasClean=${wasClean}`,
     ].filter(Boolean).join(' ');
     return new WebSocketTransportError(`WebSocket runtime event stream closed unexpectedly: ${detail}`, {
-        cause: event,
+        code: 'WS_CLOSE_ABNORMAL',
+        cause: { code, reason, wasClean },
     });
 }
-function webSocketEventError(event) {
+function webSocketEventError(event, socket, url) {
+    // We cast to ErrorEvent to access `error`/`message` fields.
+    // Per the WHATWG spec, WebSocket `error` events are plain Events — not ErrorEvents
+    // — so `candidate.error` and `candidate.message` may be undefined in compliant
+    // browsers. The safe-extract path below handles both cases: if `candidate.error`
+    // is defined we treat it as an ErrorEvent (V8/Bun do populate it on some failures);
+    // if not, we fall through to the generic `describeUnknownTransportError` branch.
+    // Using `socket.onerror` directly instead would lose the envelope-unwrap logic here.
     const candidate = event;
+    // avoid retaining the raw event.error (which may hold currentTarget/target
+    // back-references to the WebSocket, creating retention chains over many reconnects).
+    // Capture only name+message from Error instances; stringify anything else.
+    const safeError = candidate.error instanceof Error
+        ? { name: candidate.error.name, message: candidate.error.message }
+        : candidate.error !== undefined && candidate.error !== null
+            ? String(candidate.error)
+            : undefined;
+    const cause = {
+        eventType: event.type,
+        url,
+        readyState: socket?.readyState,
+        message: typeof candidate.message === 'string' ? candidate.message : undefined,
+        error: safeError,
+    };
     if (candidate.error) {
-        return transportErrorFromUnknown(candidate.error, 'WebSocket runtime event stream error');
+        return new WebSocketTransportError(`WebSocket runtime event stream error: ${transportErrorFromUnknown(candidate.error, 'WebSocket error').message}`, { code: 'WS_REMOTE_ERROR', cause });
     }
     const eventMessage = typeof candidate.message === 'string' && candidate.message.trim().length > 0
         ? candidate.message.trim()
         : undefined;
     return new WebSocketTransportError(eventMessage
         ? `WebSocket runtime event stream error: ${eventMessage}`
-        : `WebSocket runtime event stream error: ${describeUnknownTransportError(event)}`, { cause: event });
+        : `WebSocket runtime event stream error: ${describeUnknownTransportError(event)}`, { code: 'WS_REMOTE_ERROR', cause });
 }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@pellux/goodvibes-transport-realtime",
-  "version": "0.30.2",
+  "version": "0.33.0",
   "engines": {
-    "node": ">=20.0.0"
+    "bun": "1.3.10",
+    "node": ">=22.0.0"
   },
   "description": "Realtime event-domain connectors for GoodVibes SSE and WebSocket integrations.",
   "type": "module",
@@ -44,10 +45,10 @@
     "events"
   ],
   "dependencies": {
-    "@pellux/goodvibes-contracts": "0.30.2",
-    "@pellux/goodvibes-errors": "0.30.2",
-    "@pellux/goodvibes-transport-core": "0.30.2",
-    "@pellux/goodvibes-transport-http": "0.30.2"
+    "@pellux/goodvibes-contracts": "0.33.0",
+    "@pellux/goodvibes-errors": "0.33.0",
+    "@pellux/goodvibes-transport-core": "0.33.0",
+    "@pellux/goodvibes-transport-http": "0.33.0"
   },
   "publishConfig": {
     "access": "public"