@awarevue/agent-sdk 1.0.1

package/dist/agent-app.d.ts

@@ -0,0 +1,25 @@
+import { Transport } from './transport';
+import { ProviderSpecs, PushEventRq, PushStateUpdateRq } from '@awarevue/api-types';
+import { Agent } from './agent';
+export type DeviceActivity = Omit<PushStateUpdateRq, 'provider'> | Omit<PushEventRq, 'provider'>;
+export type AgentOptions = {
+    version: number;
+    providers: Record<string, ProviderSpecs>;
+    agentId: string;
+    replyTimeout?: number;
+    transport: Transport;
+};
+export declare class AgentApp {
+    private readonly agent;
+    private readonly options;
+    private static id;
+    private static nextId;
+    private sub;
+    private getReply$;
+    private addEnvelope;
+    private runProvider$;
+    private process$;
+    constructor(agent: Agent, options: AgentOptions);
+    start(): void;
+    stop(): void;
+}

package/dist/agent-app.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentApp = void 0;
+const rxjs_1 = require("rxjs");
+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 ${message.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.addEnvelope = (payload) => ({
+            ...payload,
+            id: AgentApp.nextId(),
+            from: this.options.agentId,
+            version: this.options.version,
+            on: Date.now(),
+        });
+        this.runProvider$ = (context) => {
+            return (0, rxjs_1.merge)(
+            // run the agent
+            this.agent
+                .run$(context)
+                .pipe((0, rxjs_1.tap)((message) => this.options.transport.send(this.addEnvelope({ ...message, provider: context.provider })))), this.options.transport.messages$.pipe((0, rxjs_1.mergeMap)((message) => {
+                switch (message.kind) {
+                    // handle commands
+                    case 'command':
+                        return this.agent.runCommand$(context, message).pipe(
+                        // success
+                        (0, rxjs_1.map)(() => ({
+                            kind: 'command-rs',
+                            requestId: message.id,
+                        })), 
+                        // error
+                        (0, rxjs_1.catchError)((error) => {
+                            var _a;
+                            return (0, rxjs_1.of)({
+                                kind: 'error-rs',
+                                requestId: message.id,
+                                error: (_a = error.message) !== null && _a !== void 0 ? _a : 'Unknown error',
+                            });
+                        }), 
+                        // send the response
+                        (0, rxjs_1.tap)((rs) => this.options.transport.send(this.addEnvelope(rs))));
+                    case 'get-available-devices':
+                        // get available devices
+                        return this.agent.getDevicesAndRelations$(context).pipe(
+                        // success
+                        (0, rxjs_1.map)((rs) => ({
+                            kind: 'get-available-devices-rs',
+                            ...rs,
+                            requestId: message.id,
+                        })), 
+                        // error
+                        (0, rxjs_1.catchError)((error) => {
+                            var _a;
+                            return (0, rxjs_1.of)({
+                                kind: 'error-rs',
+                                requestId: message.id,
+                                error: (_a = error.message) !== null && _a !== void 0 ? _a : 'Unknown error',
+                            });
+                        }), (0, rxjs_1.tap)((rs) => this.options.transport.send(this.addEnvelope(rs))));
+                    default:
+                        return rxjs_1.EMPTY;
+                }
+            })));
+        };
+        this.process$ = () => {
+            const registration$ = this.options.transport.connected$.pipe((0, rxjs_1.switchMap)((connected) => connected
+                ? this.getReply$('register-rs', {
+                    kind: 'register',
+                    providers: this.options.providers,
+                }).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'
+                ? (0, rxjs_1.merge)((0, rxjs_1.of)({
+                    provider: message.provider,
+                    config: message.config,
+                    lastEventForeignRef: message.lastEventForeignRef,
+                    lastEventTimestamp: message.lastEventTimestamp,
+                }).pipe((0, rxjs_1.mergeMap)((context) => this.runProvider$(context))), (0, rxjs_1.of)({
+                    kind: 'start-rs',
+                    requestId: message.id,
+                }).pipe((0, rxjs_1.tap)((reply) => this.options.transport.send(this.addEnvelope(reply)))))
+                : rxjs_1.EMPTY));
+            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;
+                return this.agent
+                    .getConfigIssues$({
+                    provider,
+                    config,
+                })
+                    .pipe(
+                // success
+                (0, rxjs_1.map)((issues) => ({
+                    kind: 'validate-config-rs',
+                    requestId: message.id,
+                    issues,
+                })), 
+                // error
+                (0, rxjs_1.catchError)((error) => {
+                    var _a;
+                    return (0, rxjs_1.of)({
+                        kind: 'error-rs',
+                        requestId: message.id,
+                        error: (_a = error.message) !== null && _a !== void 0 ? _a : 'Unknown error',
+                    });
+                }), 
+                // send the response
+                (0, rxjs_1.tap)((rs) => this.options.transport.send(this.addEnvelope(rs))));
+            }));
+            return (0, rxjs_1.merge)(registration$, startStop$, validateConfig$);
+        };
+    }
+    start() {
+        this.sub = this.process$().subscribe();
+    }
+    stop() {
+        var _a;
+        (_a = this.sub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
+        this.sub = null;
+        this.options.transport.close();
+    }
+}
+exports.AgentApp = AgentApp;
+AgentApp.id = 0;
+AgentApp.nextId = () => `${++AgentApp.id}`;

package/dist/agent.d.ts

@@ -0,0 +1,17 @@
+import { ValidateProviderConfigRs, DeviceDiscoveryDto, RunCommandRq } from '@awarevue/api-types';
+import { Observable } from 'rxjs';
+import { DeviceActivity } from './agent-app';
+export type Context = {
+    provider: string;
+    config: Record<string, unknown>;
+};
+export type RunContext = Context & {
+    lastEventForeignRef: string | null;
+    lastEventTimestamp: number | null;
+};
+export interface Agent {
+    getConfigIssues$: (context: Context) => Observable<ValidateProviderConfigRs['issues']>;
+    getDevicesAndRelations$: (context: Context) => Observable<DeviceDiscoveryDto>;
+    run$: (context: RunContext) => Observable<DeviceActivity>;
+    runCommand$: (context: Context, command: RunCommandRq) => Observable<unknown>;
+}

package/dist/agent.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './agent-app';
+export * from './agent';
+export * from './ws-agent-transport';
+export * from './transport-logger-decorator';
+export * from './transport';

package/dist/index.js

@@ -0,0 +1,21 @@
+"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("./agent-app"), exports);
+__exportStar(require("./agent"), exports);
+__exportStar(require("./ws-agent-transport"), exports);
+__exportStar(require("./transport-logger-decorator"), exports);
+__exportStar(require("./transport"), exports);

package/dist/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@awarevue/agent-sdk",
+  "version": "1.0.1",
+  "description": "SDK for building Agent implementations that speak the Aware protocol.",
+  "author": "Yaser Awajan",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json  && cp package.json dist/",
+    "prepublishOnly": "yarn build",
+    "test": "echo \"add unit tests here\"",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "yarn lint --fix"
+  },
+  "dependencies": {
+    "@awarevue/api-types": "^1.0.0",
+    "rxjs": "^7.8.2",
+    "ws": "^8",
+    "zod": "3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@typescript-eslint/eslint-plugin": "^8.31.1",
+    "@typescript-eslint/parser": "^8.31.1",
+    "eslint": "^9.25.1",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-plugin-import": "^2.31.0",
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,35 @@
+"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

@@ -0,0 +1,10 @@
+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/transport.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,28 @@
+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;
+    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);
+    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

@@ -0,0 +1,100 @@
+"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) {
+        this.url = url;
+        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' },
+        });
+        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;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@awarevue/agent-sdk",
+  "version": "1.0.1",
+  "description": "SDK for building Agent implementations that speak the Aware protocol.",
+  "author": "Yaser Awajan",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json  && cp package.json dist/",
+    "prepublishOnly": "yarn build",
+    "test": "echo \"add unit tests here\"",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "yarn lint --fix"
+  },
+  "dependencies": {
+    "@awarevue/api-types": "^1.0.0",
+    "rxjs": "^7.8.2",
+    "ws": "^8",
+    "zod": "3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@typescript-eslint/eslint-plugin": "^8.31.1",
+    "@typescript-eslint/parser": "^8.31.1",
+    "eslint": "^9.25.1",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-plugin-import": "^2.31.0",
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}