@awarevue/agent-sdk 2.0.53 → 2.0.55

package/dist/agent-app.d.ts

@@ -1,23 +1,20 @@
-import { Transport } from './transport';
-import { PushEventRq, PushStateUpdateRq, ProviderSpecs, AccessControlCapabilityReport } from '@awarevue/api-types';
+import { FromAgent, PushEventRq, PushStateUpdateRq, ProviderSpecs, AccessControlCapabilityReport, FromServer, Message } from '@awarevue/api-types';
 import { Agent } from './agent';
+import { DuplexTransport } from './transport_types';
 export type DeviceActivity = Omit<PushStateUpdateRq, 'provider'> | Omit<PushEventRq, 'provider'>;
 export type AgentOptions = {
     providers: Record<string, ProviderSpecs>;
     accessControlProviders?: Record<string, AccessControlCapabilityReport>;
     agentId: string;
     replyTimeout?: number;
-    transport: Transport;
+    transport: DuplexTransport<Message<FromServer>, Message<FromAgent>>;
 };
 export declare class AgentApp {
     private readonly agent;
     private readonly options;
-    private static id;
-    private static nextId;
+    private readonly protocol;
     private sub;
-    private getReply$;
     private handleResponse$;
-    private addEnvelope;
     private createAccessChangeContext;
     private runProvider$;
     private process$;

package/dist/agent-app.js

@@ -5,29 +5,12 @@ const rxjs_1 = require("rxjs");
 const default_validator_1 = require("./default-validator");
 const utils_1 = require("./utils");
 const agent_error_1 = require("./agent-error");
-const constants_1 = require("./constants");
+const agent_protocol_1 = require("./agent-protocol");
 class AgentApp {
     constructor(agent, options) {
         this.agent = agent;
         this.options = options;
         this.sub = null;
-        // getReply$ is a generic function that sends a message to server and waits for a reply.
-        this.getReply$ = (responseKind, payload) => {
-            const reply$ = (id) => this.options.transport.messages$.pipe((0, rxjs_1.mergeMap)((message) => {
-                if (message.kind === 'error-rs' && message.requestId === id) {
-                    const error = message.error;
-                    return (0, rxjs_1.throwError)(() => new Error(`Server failed to process message ${payload.kind}: ${error}`));
-                }
-                return (0, rxjs_1.of)(message);
-            }), (0, rxjs_1.filter)((message) => message.kind === responseKind &&
-                'requestId' in message &&
-                message.requestId === id), (0, rxjs_1.take)(1), (0, rxjs_1.timeout)(this.options.replyTimeout || 10000));
-            return (0, rxjs_1.of)(this.addEnvelope({ ...payload, id: AgentApp.nextId() })).pipe(
-            // send the message to the agent
-            (0, rxjs_1.tap)((p) => this.options.transport.send(p)), 
-            // wait for the agent to reply
-            (0, rxjs_1.mergeMap)(({ id }) => reply$(id)));
-        };
         this.handleResponse$ = (requestId) => (obs) => obs.pipe((0, rxjs_1.tap)({
             error: (error) => console.error('Error processing request', requestId, (0, utils_1.stringifyError)(error)),
         }), (0, rxjs_1.catchError)((error) => (0, rxjs_1.of)({
@@ -35,14 +18,7 @@ class AgentApp {
             requestId,
             error: (0, utils_1.stringifyError)(error),
             code: error instanceof agent_error_1.AgentError ? error.code : undefined,
-        })), (0, rxjs_1.tap)((rs) => this.options.transport.send(this.addEnvelope(rs))));
-        this.addEnvelope = (payload) => ({
-            ...payload,
-            id: AgentApp.nextId(),
-            from: this.options.agentId,
-            version: constants_1.AGENT_PROTOCOL_VERSION,
-            on: Date.now(),
-        });
+        })), (0, rxjs_1.tap)((rs) => this.protocol.send(rs)));
         this.createAccessChangeContext = (context, refMap, objectCache) => {
             return {
                 ...context,
@@ -73,14 +49,14 @@ class AgentApp {
             (0, rxjs_1.mergeMap)((message) => {
                 // Send start-rs on the first emission (null) to signal we're ready
                 if (message === null) {
-                    this.options.transport.send(this.addEnvelope({
+                    this.protocol.send({
                         kind: 'start-rs',
                         requestId: context.startRequestId,
-                    }));
-                    return (0, rxjs_1.of)(null).pipe((0, rxjs_1.delay)(1000), (0, rxjs_1.mergeMap)(() => this.agent.run$(context).pipe((0, rxjs_1.tap)((message) => this.options.transport.send(this.addEnvelope({
+                    });
+                    return (0, rxjs_1.of)(null).pipe((0, rxjs_1.delay)(1000), (0, rxjs_1.mergeMap)(() => this.agent.run$(context).pipe((0, rxjs_1.tap)((message) => this.protocol.send({
                         ...message,
                         provider: context.provider,
-                    }))))));
+                    })))));
                 }
                 switch (message.kind) {
                     // handle commands
@@ -158,11 +134,13 @@ class AgentApp {
         };
         this.process$ = () => {
             const registration$ = this.options.transport.connected$.pipe((0, rxjs_1.switchMap)((connected) => connected
-                ? this.getReply$('register-rs', {
+                ? this.protocol
+                    .getReply$({
                     kind: 'register',
                     providers: this.options.providers,
                     accessControlProviders: this.options.accessControlProviders,
-                }).pipe((0, rxjs_1.retry)({ delay: 3000 }))
+                })
+                    .pipe((0, rxjs_1.retry)({ delay: 3000 }))
                 : rxjs_1.EMPTY));
             const startStop$ = this.options.transport.messages$.pipe((0, rxjs_1.filter)((message) => message.kind === 'start' || message.kind === 'stop'), (0, rxjs_1.switchMap)((message) => message.kind === 'start'
                 ? this.agent
@@ -180,10 +158,10 @@ class AgentApp {
                     deviceCatalog,
                     startRequestId: message.id,
                 })), (0, rxjs_1.mergeMap)((context) => this.runProvider$(context)))
-                : (0, rxjs_1.of)(message).pipe((0, rxjs_1.tap)(() => this.options.transport.send(this.addEnvelope({
+                : (0, rxjs_1.of)(message).pipe((0, rxjs_1.tap)(() => this.protocol.send({
                     kind: 'stop-rs',
                     requestId: message.id,
-                }))))));
+                })))));
             const validateConfig$ = this.options.transport.messages$.pipe((0, rxjs_1.filter)((message) => message.kind === 'validate-config'), (0, rxjs_1.mergeMap)((message) => {
                 const provider = message.provider;
                 const config = message.config;
@@ -202,6 +180,10 @@ class AgentApp {
             }));
             return (0, rxjs_1.merge)(registration$, startStop$, validateConfig$);
         };
+        this.protocol = new agent_protocol_1.AgentProtocol(this.options.transport, {
+            id: this.options.agentId,
+            replyTimeout: this.options.replyTimeout,
+        });
     }
     start() {
         this.sub = this.process$().subscribe();
@@ -214,5 +196,3 @@ class AgentApp {
     }
 }
 exports.AgentApp = AgentApp;
-AgentApp.id = 0;
-AgentApp.nextId = () => `${++AgentApp.id}`;

package/dist/agent-protocol.d.ts

@@ -0,0 +1,32 @@
+import { FromAgent, FromServer, Message, PayloadByKind, ReplyKindByRequestKind } from '@awarevue/api-types';
+import { DuplexTransport } from './transport_types';
+import { Observable } from 'rxjs';
+export type Direction = 'server' | 'agent';
+export type RequestKind = keyof typeof ReplyKindByRequestKind;
+export type ResponseKind<K extends RequestKind> = (typeof ReplyKindByRequestKind)[K];
+/**
+ * Directional wire types:
+ * - If you are SERVER: you receive FromAgent, send FromServer
+ * - If you are AGENT:  you receive FromServer, send FromAgent
+ */
+export type Inbound<D extends Direction> = D extends 'server' ? FromAgent : FromServer;
+export type Outbound<D extends Direction> = D extends 'server' ? FromServer : FromAgent;
+export type InMsg<D extends Direction> = Message<Inbound<D>>;
+export type OutMsg<D extends Direction> = Message<Outbound<D>>;
+export interface AgentProtocolOptions {
+    /** Timeout for awaiting replies to sent messages (default 10s) */
+    replyTimeout?: number;
+    id: string;
+}
+export declare class AgentProtocol<D extends Direction> {
+    private readonly transport;
+    private readonly options;
+    private static id;
+    private static nextId;
+    private addEnvelope;
+    constructor(transport: DuplexTransport<Message<Inbound<D>>, Message<Outbound<D>>>, options: AgentProtocolOptions);
+    getReply$: <K extends RequestKind>(payload: Extract<Outbound<D>, {
+        kind: K;
+    }>) => Observable<Message<PayloadByKind[ResponseKind<K>]>>;
+    send: (payload: Outbound<D>) => void;
+}

package/dist/agent-protocol.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentProtocol = void 0;
+const api_types_1 = require("@awarevue/api-types");
+const rxjs_1 = require("rxjs");
+const constants_1 = require("./constants");
+class AgentProtocol {
+    constructor(transport, options) {
+        this.transport = transport;
+        this.options = options;
+        this.addEnvelope = (payload) => ({
+            ...payload,
+            id: AgentProtocol.nextId(),
+            from: this.options.id,
+            version: constants_1.AGENT_PROTOCOL_VERSION,
+            on: Date.now(),
+        });
+        this.getReply$ = (payload) => {
+            const responseKind = api_types_1.ReplyKindByRequestKind[payload.kind];
+            const reply$ = (id) => this.transport.messages$.pipe((0, rxjs_1.mergeMap)((message) => {
+                if (message.kind === 'error-rs' && message.requestId === id) {
+                    const error = message.error;
+                    return (0, rxjs_1.throwError)(() => new Error(`Server failed to process message ${payload.kind}: ${error}`));
+                }
+                return (0, rxjs_1.of)(message);
+            }), (0, rxjs_1.filter)((message) => message.kind === responseKind &&
+                'requestId' in message &&
+                message.requestId === id), (0, rxjs_1.take)(1), (0, rxjs_1.timeout)(this.options.replyTimeout || 10000));
+            return (0, rxjs_1.of)(this.addEnvelope({ ...payload, id: AgentProtocol.nextId() })).pipe(
+            // send the message to the agent
+            (0, rxjs_1.tap)((p) => this.transport.send(p)), 
+            // wait for the agent to reply
+            (0, rxjs_1.mergeMap)(({ id }) => reply$(id)));
+        };
+        this.send = (payload) => {
+            const message = this.addEnvelope(payload);
+            this.transport.send(message);
+        };
+    }
+}
+exports.AgentProtocol = AgentProtocol;
+AgentProtocol.id = 0;
+AgentProtocol.nextId = () => `${++AgentProtocol.id}`;

package/dist/default-validator.d.ts

@@ -1,10 +1,10 @@
 import { AccessValidateChangeRq } from '@awarevue/api-types';
 import { Agent, Context } from './agent';
 export declare const createValidator: <T extends Agent>(agent: T) => (context: Context, change: AccessValidateChangeRq) => import("rxjs").Observable<readonly [{
-    index?: number | undefined;
     code?: "BAD_REFERENCE" | "NOT_SUPPORTED" | "NOT_FOUND" | "NOT_UNIQUE" | "INVALID" | undefined;
-    message?: string | undefined;
     path?: string | undefined;
+    message?: string | undefined;
     objectKind?: "person" | "zone" | "schedule" | "device" | "accessRule" | undefined;
     objectId?: string | undefined;
+    index?: number | undefined;
 }[], Record<"accessRule" | "schedule" | "person" | "device" | "zone", Record<string, Record<string, unknown>>>]>;

package/dist/hubs/in-memory.d.ts

@@ -0,0 +1,19 @@
+import { PeerId, HubTransport, PeerEvent, DuplexTransport } from '../transport_types';
+export declare class InMemoryHub<TIn, TOut, TPeer extends PeerId> implements HubTransport<TIn, TOut, TPeer> {
+    private readonly peerEventsSubject;
+    private readonly messagesSubject;
+    private readonly peers;
+    private readonly peerSubs;
+    readonly peerEvents$: import("rxjs").Observable<PeerEvent<TPeer>>;
+    readonly messages$: import("rxjs").Observable<{
+        peer: TPeer;
+        msg: TIn;
+    }>;
+    addPeer(peerId: TPeer, conn: DuplexTransport<TIn, TOut>): void;
+    removePeer(peerId: TPeer, reason?: unknown): void;
+    closePeer(peerId: TPeer): void;
+    close(): void;
+    broadcast(msg: TOut): void;
+    connection(peerId: TPeer): DuplexTransport<TIn, TOut> | null;
+    sendTo(msg: TOut, peerId: TPeer): void;
+}

package/dist/hubs/in-memory.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryHub = void 0;
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+class InMemoryHub {
+    constructor() {
+        this.peerEventsSubject = new rxjs_1.Subject();
+        this.messagesSubject = new rxjs_1.Subject();
+        this.peers = new Map();
+        this.peerSubs = new Map();
+        this.peerEvents$ = this.peerEventsSubject.asObservable().pipe((0, operators_1.share)());
+        this.messages$ = this.messagesSubject.asObservable().pipe((0, operators_1.share)());
+    }
+    addPeer(peerId, conn) {
+        // defensive: if peer already exists, clean it first
+        if (this.peers.has(peerId))
+            this.removePeer(peerId, 'replaced');
+        this.peers.set(peerId, conn);
+        this.peerEventsSubject.next({ type: 'join', peer: peerId });
+        const sub = new rxjs_1.Subscription();
+        sub.add(conn.messages$.subscribe((msg) => {
+            this.messagesSubject.next({ peer: peerId, msg });
+        }));
+        sub.add(conn.connected$.subscribe((connected) => {
+            if (!connected)
+                this.removePeer(peerId, 'disconnect');
+        }));
+        this.peerSubs.set(peerId, sub);
+    }
+    removePeer(peerId, reason) {
+        var _a;
+        if (!this.peers.has(peerId))
+            return;
+        // tear down subscriptions FIRST
+        (_a = this.peerSubs.get(peerId)) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this.peerSubs.delete(peerId);
+        this.peers.delete(peerId);
+        this.peerEventsSubject.next({ type: 'leave', peer: peerId, reason });
+    }
+    closePeer(peerId) {
+        var _a;
+        (_a = this.peers.get(peerId)) === null || _a === void 0 ? void 0 : _a.close();
+        this.removePeer(peerId, 'closed');
+    }
+    close() {
+        var _a;
+        for (const [peerId, conn] of this.peers) {
+            conn.close();
+            (_a = this.peerSubs.get(peerId)) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        }
+        this.peerSubs.clear();
+        this.peers.clear();
+        // optional: if the hub itself is done
+        this.peerEventsSubject.complete();
+        this.messagesSubject.complete();
+    }
+    broadcast(msg) {
+        for (const [, conn] of this.peers)
+            conn.send(msg);
+    }
+    connection(peerId) {
+        var _a;
+        return (_a = this.peers.get(peerId)) !== null && _a !== void 0 ? _a : null;
+    }
+    sendTo(msg, peerId) {
+        var _a;
+        (_a = this.peers.get(peerId)) === null || _a === void 0 ? void 0 : _a.send(msg);
+    }
+}
+exports.InMemoryHub = InMemoryHub;

package/dist/hubs/index.d.ts

@@ -0,0 +1 @@
+export * from './in-memory';

package/dist/hubs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./in-memory"), exports);

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export * from './agent-app';
 export * from './agent';
-export * from './ws-agent-transport';
-export * from './transport-logger-decorator';
-export * from './transport';
 export * from './constants';
+export * from './agent-protocol';
+export * from './agent-error';
+export * from './transport_types';
+export * from './utils';
+export * from './transports';
+export * from './hubs';

package/dist/index.js

@@ -16,7 +16,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./agent-app"), exports);
 __exportStar(require("./agent"), exports);
-__exportStar(require("./ws-agent-transport"), exports);
-__exportStar(require("./transport-logger-decorator"), exports);
-__exportStar(require("./transport"), exports);
 __exportStar(require("./constants"), exports);
+__exportStar(require("./agent-protocol"), exports);
+__exportStar(require("./agent-error"), exports);
+__exportStar(require("./transport_types"), exports);
+__exportStar(require("./utils"), exports);
+__exportStar(require("./transports"), exports);
+__exportStar(require("./hubs"), exports);

package/dist/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "git+https://github.com/Linc-Security-Systems/aware-essentials.git"
   },
-  "version": "2.0.53",
+  "version": "2.0.55",
   "description": "SDK for building Agent implementations that speak the agent protocol.",
   "author": "Yaser Awajan",
   "license": "MIT",
@@ -31,12 +31,12 @@
     "lint:fix": "yarn lint --fix"
   },
   "peerDependencies": {
-    "@awarevue/api-types": "2.0.53",
+    "@awarevue/api-types": "2.0.55",
     "rxjs": "^7.8.2",
     "ws": "^8"
   },
   "devDependencies": {
-    "@awarevue/api-types": "2.0.53",
+    "@awarevue/api-types": "2.0.55",
     "@types/node": "^20.12.7",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.31.1",

package/dist/transport_types.d.ts

@@ -0,0 +1,50 @@
+import { Observable } from 'rxjs';
+/**
+ * Coherent model:
+ * - DuplexTransport: single logical connection (agent-friendly)
+ * - HubTransport: multiplexed routing over many peers (server-friendly)
+ * - HubTransport.connection(peer): projects a peer into a DuplexTransport
+ *
+ * This avoids "parity" traps: agent does not pretend it can manage peers.
+ */
+export interface DuplexTransport<TIn, TOut> {
+    /** True when this logical connection is up */
+    readonly connected$: Observable<boolean>;
+    /** Incoming messages on this connection */
+    readonly messages$: Observable<TIn>;
+    /** Send on this connection */
+    send(msg: TOut): void;
+    /** Close this connection */
+    close(): void;
+}
+export type PeerId = string | number;
+export type PeerEvent<TPeer> = {
+    type: 'join';
+    peer: TPeer;
+} | {
+    type: 'leave';
+    peer: TPeer;
+    reason?: unknown;
+};
+export interface HubTransport<TIn, TOut, TPeer> {
+    /** Peer join/leave stream */
+    readonly peerEvents$: Observable<PeerEvent<TPeer>>;
+    /** Incoming messages with peer attribution */
+    readonly messages$: Observable<{
+        msg: TIn;
+        peer: TPeer;
+    }>;
+    /** Send to one peer */
+    sendTo(msg: TOut, peer: TPeer): void;
+    /** Broadcast to all currently connected peers */
+    broadcast(msg: TOut): void;
+    /** Disconnect one peer */
+    closePeer(peer: TPeer): void;
+    /** Close hub transport */
+    close(): void;
+    /**
+     * Project a peer into a single-connection view.
+     * This is the key to reuse agent-side SDK logic against a hub peer.
+     */
+    connection(peer: TPeer): DuplexTransport<TIn, TOut> | null;
+}

package/dist/transports/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ws';
+export * from './logging';

package/dist/transports/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ws"), exports);
+__exportStar(require("./logging"), exports);

package/dist/transports/logging.d.ts

@@ -0,0 +1,24 @@
+import { Observable } from 'rxjs';
+import { DuplexTransport } from '../transport_types';
+export interface LoggingTransportOptions {
+    /**
+     * Label prepended to each log line so multiple transports can be
+     * distinguished in the same process (default: `'transport'`).
+     */
+    label?: string;
+    /**
+     * Custom log sink.  When omitted, messages are written to
+     * `console.log` as pretty-printed JSON.
+     */
+    logger?: (direction: 'IN' | 'OUT', label: string, msg: unknown) => void;
+}
+export declare class LoggingDuplexTransport<TIn, TOut> implements DuplexTransport<TIn, TOut> {
+    private readonly inner;
+    readonly connected$: Observable<boolean>;
+    readonly messages$: Observable<TIn>;
+    private readonly label;
+    private readonly sink;
+    constructor(inner: DuplexTransport<TIn, TOut>, opts?: LoggingTransportOptions);
+    send(msg: TOut): void;
+    close(): void;
+}

package/dist/transports/logging.js

@@ -0,0 +1,32 @@
+"use strict";
+// transports/logging.ts
+// ----------------------------------------------------------------
+// Logging decorator for DuplexTransport.
+// Wraps any DuplexTransport and prints inbound / outbound messages.
+// ----------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggingDuplexTransport = void 0;
+const operators_1 = require("rxjs/operators");
+/* ---------------------------------------------------------------- */
+/* Implementation                                                   */
+/* ---------------------------------------------------------------- */
+class LoggingDuplexTransport {
+    constructor(inner, opts = {}) {
+        var _a, _b;
+        this.inner = inner;
+        this.label = (_a = opts.label) !== null && _a !== void 0 ? _a : 'transport';
+        this.sink =
+            (_b = opts.logger) !== null && _b !== void 0 ? _b : ((direction, label, msg) => console.log(`[${label}] ${direction}`, JSON.stringify(msg, null, 2)));
+        this.connected$ = inner.connected$;
+        // Tap into the incoming stream before exposing it to consumers.
+        this.messages$ = inner.messages$.pipe((0, operators_1.tap)((msg) => this.sink('IN', this.label, msg)));
+    }
+    send(msg) {
+        this.sink('OUT', this.label, msg);
+        this.inner.send(msg);
+    }
+    close() {
+        this.inner.close();
+    }
+}
+exports.LoggingDuplexTransport = LoggingDuplexTransport;

package/dist/transports/ws.d.ts

@@ -0,0 +1,56 @@
+import { Observable } from 'rxjs';
+import { DuplexTransport } from '../transport_types';
+export interface WsDuplexTransportOptions {
+    /** WebSocket endpoint URL (ws:// or wss://) */
+    url: string;
+    /**
+     * Optional headers sent during the WebSocket handshake
+     * (e.g. Authorization, User-Agent).
+     */
+    headers?: Record<string, string>;
+    /**
+     * Serialise an outbound message to a string or Buffer.
+     * Defaults to `JSON.stringify`.
+     */
+    serialise?: (msg: unknown) => string;
+    /**
+     * Deserialise an inbound raw payload to a message object.
+     * Defaults to `JSON.parse`.
+     */
+    deserialise?: (raw: string) => unknown;
+    /** Initial reconnect delay in ms (default 1 000). */
+    reconnectDelay?: number;
+    /** Maximum reconnect delay in ms (default 30 000). */
+    maxReconnectDelay?: number;
+    /** When false, no automatic reconnect is attempted (default true). */
+    autoReconnect?: boolean;
+}
+export declare class WsDuplexTransport<TIn, TOut> implements DuplexTransport<TIn, TOut> {
+    private readonly opts;
+    readonly connected$: Observable<boolean>;
+    readonly messages$: Observable<TIn>;
+    readonly errors$: Observable<Error>;
+    private readonly _connected$;
+    private readonly _messages$;
+    private readonly _errors$;
+    private readonly outbound$;
+    private readonly destroy$;
+    private ws;
+    private reconnectDelay;
+    private readonly maxDelay;
+    private readonly autoReconnect;
+    private destroyed;
+    private readonly serialise;
+    private readonly deserialise;
+    private defaultDeserializer;
+    private defaultSerializer;
+    constructor(opts: WsDuplexTransportOptions);
+    send(msg: TOut): void;
+    close(): void;
+    /** Single subscription that drains the outbound queue when connected. */
+    private setupSender;
+    /** Establish (or re-establish) the WebSocket connection. */
+    private connect;
+    /** Exponential back-off reconnect, cancelled via destroy$. */
+    private scheduleReconnect;
+}

package/dist/transports/ws.js

@@ -0,0 +1,117 @@
+"use strict";
+// transports/ws.ts
+// ----------------------------------------------------------------
+// Generic WebSocket-backed DuplexTransport with auto-reconnect.
+// Unlike WsAgentTransport (which is protocol-aware), this is a
+// reusable building block for any TIn / TOut message pair.
+// ----------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WsDuplexTransport = void 0;
+const ws_1 = require("ws");
+const rxjs_1 = require("rxjs");
+/* ---------------------------------------------------------------- */
+/* Implementation                                                   */
+/* ---------------------------------------------------------------- */
+class WsDuplexTransport {
+    constructor(opts) {
+        var _a, _b, _c, _d, _e;
+        this.opts = opts;
+        // ---- internal subjects ----
+        this._connected$ = new rxjs_1.BehaviorSubject(false);
+        this._messages$ = new rxjs_1.Subject();
+        this._errors$ = new rxjs_1.Subject();
+        this.outbound$ = new rxjs_1.Subject();
+        this.destroy$ = new rxjs_1.Subject();
+        this.destroyed = false;
+        this.defaultDeserializer = (raw) => {
+            const env = JSON.parse(raw);
+            return {
+                kind: env.event,
+                ...env.data,
+            };
+        };
+        this.defaultSerializer = (msg) => {
+            if (typeof msg === 'object' && 'kind' in (msg || {})) {
+                const { kind, ...data } = msg;
+                return JSON.stringify({ event: kind, data });
+            }
+            return JSON.stringify(msg);
+        };
+        this.connected$ = this._connected$.asObservable();
+        this.messages$ = this._messages$.asObservable();
+        this.errors$ = this._errors$.asObservable();
+        this.reconnectDelay = (_a = opts.reconnectDelay) !== null && _a !== void 0 ? _a : 1000;
+        this.maxDelay = (_b = opts.maxReconnectDelay) !== null && _b !== void 0 ? _b : 30000;
+        this.autoReconnect = (_c = opts.autoReconnect) !== null && _c !== void 0 ? _c : true;
+        this.serialise = ((_d = opts.serialise) !== null && _d !== void 0 ? _d : this.defaultSerializer);
+        this.deserialise = ((_e = opts.deserialise) !== null && _e !== void 0 ? _e : this.defaultDeserializer);
+        this.connect();
+        this.setupSender();
+    }
+    /* -------------------------------------------------------------- */
+    /* Public API                                                     */
+    /* -------------------------------------------------------------- */
+    send(msg) {
+        this.outbound$.next(this.serialise(msg));
+    }
+    close() {
+        var _a;
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.destroy$.next();
+        this.destroy$.complete();
+        this._connected$.complete();
+        this._messages$.complete();
+        this._errors$.complete();
+        (_a = this.ws) === null || _a === void 0 ? void 0 : _a.terminate();
+    }
+    /* -------------------------------------------------------------- */
+    /* Private helpers                                                */
+    /* -------------------------------------------------------------- */
+    /** Single subscription that drains the outbound queue when connected. */
+    setupSender() {
+        this.outbound$
+            .pipe((0, rxjs_1.concatMap)((payload) => this._connected$.pipe((0, rxjs_1.filter)(Boolean), (0, rxjs_1.take)(1), (0, rxjs_1.takeUntil)(this.destroy$), (0, rxjs_1.map)(() => payload))), (0, rxjs_1.takeUntil)(this.destroy$))
+            .subscribe((payload) => {
+            this.ws.send(payload);
+        });
+    }
+    /** Establish (or re-establish) the WebSocket connection. */
+    connect() {
+        this.ws = new ws_1.WebSocket(this.opts.url, {
+            headers: this.opts.headers,
+        });
+        this.ws.on('open', () => {
+            var _a;
+            this.reconnectDelay = (_a = this.opts.reconnectDelay) !== null && _a !== void 0 ? _a : 1000;
+            this._connected$.next(true);
+        });
+        this.ws.on('message', (data) => {
+            try {
+                const msg = this.deserialise(data.toString());
+                this._messages$.next(msg);
+            }
+            catch (err) {
+                this._errors$.next(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        this.ws.on('error', (err) => {
+            this._errors$.next(err);
+        });
+        this.ws.on('close', () => {
+            this._connected$.next(false);
+            if (!this.destroyed && this.autoReconnect) {
+                this.scheduleReconnect();
+            }
+        });
+    }
+    /** Exponential back-off reconnect, cancelled via destroy$. */
+    scheduleReconnect() {
+        (0, rxjs_1.timer)(this.reconnectDelay)
+            .pipe((0, rxjs_1.takeUntil)(this.destroy$))
+            .subscribe(() => this.connect());
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxDelay);
+    }
+}
+exports.WsDuplexTransport = WsDuplexTransport;

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "git+https://github.com/Linc-Security-Systems/aware-essentials.git"
   },
-  "version": "2.0.53",
+  "version": "2.0.55",
   "description": "SDK for building Agent implementations that speak the agent protocol.",
   "author": "Yaser Awajan",
   "license": "MIT",
@@ -31,12 +31,12 @@
     "lint:fix": "yarn lint --fix"
   },
   "peerDependencies": {
-    "@awarevue/api-types": "2.0.53",
+    "@awarevue/api-types": "2.0.55",
     "rxjs": "^7.8.2",
     "ws": "^8"
   },
   "devDependencies": {
-    "@awarevue/api-types": "2.0.53",
+    "@awarevue/api-types": "2.0.55",
     "@types/node": "^20.12.7",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.31.1",

package/dist/transport-logger-decorator.d.ts

@@ -1,11 +0,0 @@
-import { Message, FromAgent } from '@awarevue/api-types';
-import { Transport } from './transport';
-export declare class TransportWithLogs implements Transport {
-    private readonly decoratee;
-    constructor(decoratee: Transport);
-    get connected$(): import("rxjs").Observable<boolean>;
-    get messages$(): import("rxjs").Observable<Message<import("@awarevue/api-types").FromServer>>;
-    get errors$(): import("rxjs").Observable<Error>;
-    close(): void;
-    send(msg: Message<FromAgent>): void;
-}

package/dist/transport-logger-decorator.js

@@ -1,35 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TransportWithLogs = void 0;
-class TransportWithLogs {
-    constructor(decoratee) {
-        this.decoratee = decoratee;
-        this.decoratee.connected$.subscribe((connected) => {
-            console.log(`[${new Date()}] - Transport connected: ${connected}`);
-        });
-        this.decoratee.messages$.subscribe((msg) => {
-            console.log(`[${new Date()}] - Transport message: ${JSON.stringify(msg)}`);
-        });
-        this.decoratee.errors$.subscribe((err) => {
-            console.error(`[${new Date()}] - Transport error: ${err}`);
-        });
-    }
-    get connected$() {
-        return this.decoratee.connected$;
-    }
-    get messages$() {
-        return this.decoratee.messages$;
-    }
-    get errors$() {
-        return this.decoratee.errors$;
-    }
-    close() {
-        console.log(`Closing transport`);
-        this.decoratee.close();
-    }
-    send(msg) {
-        console.log(`[${new Date()}] - Sending message: ${JSON.stringify(msg)}`);
-        this.decoratee.send(msg);
-    }
-}
-exports.TransportWithLogs = TransportWithLogs;

package/dist/transport.d.ts

@@ -1,10 +0,0 @@
-import { FromAgent, FromServer, Message } from '@awarevue/api-types';
-import { Observable } from 'rxjs';
-/** What the SDK expects from a transport */
-export interface Transport {
-    readonly connected$: Observable<boolean>;
-    readonly messages$: Observable<Message<FromServer>>;
-    readonly errors$: Observable<Error>;
-    send(msg: Message<FromAgent>): void;
-    close(): void;
-}

package/dist/ws-agent-transport.d.ts

@@ -1,29 +0,0 @@
-import { Observable } from 'rxjs';
-import { FromAgent, FromServer, Message } from '@awarevue/api-types';
-import { Transport } from './transport';
-export declare class WsAgentTransport implements Transport {
-    private readonly url;
-    private readonly apiKey;
-    readonly connected$: Observable<boolean>;
-    readonly messages$: Observable<Message<FromServer>>;
-    readonly errors$: Observable<Error>;
-    private ws;
-    private readonly _connected$;
-    private readonly _messages$;
-    private readonly _errors$;
-    private readonly outbound$;
-    private readonly destroy$;
-    private reconnectDelay;
-    private readonly maxDelay;
-    private destroyed;
-    constructor(url: string, apiKey: string);
-    send(msg: Message<FromAgent>): void;
-    /** Call once when your container/module shuts down. */
-    close(): void;
-    /** One subscription for all outbound traffic. */
-    private setupSender;
-    /** Establish or re-establish a WebSocket connection. */
-    private connect;
-    /** Exponential back-off reconnect, cancelled via destroy$. */
-    private scheduleReconnect;
-}

package/dist/ws-agent-transport.js

@@ -1,104 +0,0 @@
-"use strict";
-// ws-agent-transport.ts
-//--------------------------------------------------------------
-// A robust, RxJS-friendly WebSocket transport for the Aware SDK
-// •  automatic exponential back-off reconnect
-// •  single outbound queue, no per-call subscriptions
-// •  clean shutdown (no leaks)
-//--------------------------------------------------------------
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.WsAgentTransport = void 0;
-const ws_1 = require("ws");
-const rxjs_1 = require("rxjs");
-class WsAgentTransport {
-    constructor(url, apiKey) {
-        this.url = url;
-        this.apiKey = apiKey;
-        this._connected$ = new rxjs_1.BehaviorSubject(false);
-        this._messages$ = new rxjs_1.Subject();
-        this._errors$ = new rxjs_1.Subject();
-        this.outbound$ = new rxjs_1.Subject();
-        this.destroy$ = new rxjs_1.Subject();
-        this.reconnectDelay = 1000; // start at 1 s
-        this.maxDelay = 30000; // cap at 30 s
-        this.destroyed = false;
-        this.connected$ = this._connected$.asObservable();
-        this.messages$ = this._messages$.asObservable();
-        this.errors$ = this._errors$.asObservable();
-        this.connect(); // first connection
-        this.setupSender(); // single outbound subscription
-    }
-    //----------------------------------------
-    //  Public API
-    //----------------------------------------
-    send(msg) {
-        const { kind, ...data } = msg;
-        const payload = JSON.stringify({ event: kind, data });
-        this.outbound$.next(payload);
-    }
-    /** Call once when your container/module shuts down. */
-    close() {
-        var _a;
-        if (this.destroyed)
-            return;
-        this.destroyed = true;
-        this.destroy$.next();
-        this.destroy$.complete();
-        this._connected$.complete();
-        this._messages$.complete();
-        this._errors$.complete();
-        /** terminate() is immediate; skip the close handshake intentionally */
-        (_a = this.ws) === null || _a === void 0 ? void 0 : _a.terminate();
-    }
-    //----------------------------------------
-    //  Private helpers
-    //----------------------------------------
-    /** One subscription for all outbound traffic. */
-    setupSender() {
-        this.outbound$
-            .pipe((0, rxjs_1.concatMap)((payload) => this._connected$.pipe((0, rxjs_1.filter)(Boolean), // wait until we’re actually connected
-        (0, rxjs_1.take)(1), // just the next open
-        (0, rxjs_1.takeUntil)(this.destroy$), (0, rxjs_1.map)(() => payload))), (0, rxjs_1.takeUntil)(this.destroy$))
-            .subscribe((payload) => {
-            /* readyState **must** be OPEN here by construction */
-            this.ws.send(payload);
-        });
-    }
-    /** Establish or re-establish a WebSocket connection. */
-    connect() {
-        this.ws = new ws_1.WebSocket(this.url, {
-            headers: {
-                'User-Agent': 'Aware Agent SDK',
-                Authorization: `ApiKey ${this.apiKey}`,
-            },
-        });
-        this.ws.on('open', () => {
-            this.reconnectDelay = 1000; // reset back-off
-            this._connected$.next(true);
-        });
-        this.ws.on('message', (data) => {
-            const raw = JSON.parse(data.toString());
-            this._messages$.next({
-                kind: raw.event,
-                ...raw.data,
-            });
-        });
-        this.ws.on('error', (err) => {
-            this._errors$.next(err);
-            // the 'close' handler will schedule reconnect
-        });
-        this.ws.on('close', () => {
-            this._connected$.next(false);
-            if (!this.destroyed)
-                this.scheduleReconnect();
-        });
-    }
-    /** Exponential back-off reconnect, cancelled via destroy$. */
-    scheduleReconnect() {
-        (0, rxjs_1.timer)(this.reconnectDelay)
-            .pipe((0, rxjs_1.takeUntil)(this.destroy$))
-            .subscribe(() => this.connect());
-        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxDelay);
-    }
-}
-exports.WsAgentTransport = WsAgentTransport;