@camstack/server 1.0.0 → 1.0.1

package/dist/core/network/network-quality.service.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkQualityService = void 0;
+const core_1 = require("@camstack/core");
+class NetworkQualityService extends core_1.NetworkQualityTracker {
+}
+exports.NetworkQualityService = NetworkQualityService;

package/dist/core/notification/notification-wrapper.service.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationServiceWrapper = void 0;
+const core_1 = require("@camstack/core");
+/**
+ * NestJS-injectable wrapper around the core NotificationService.
+ *
+ * Lazily creates the NotificationService on first use, wiring in the
+ * CapabilityRegistry for proxy-based output resolution.
+ */
+class NotificationServiceWrapper {
+    caps;
+    logging;
+    _service = null;
+    constructor(caps, logging) {
+        this.caps = caps;
+        this.logging = logging;
+    }
+    get service() {
+        if (!this._service) {
+            this._service = new core_1.NotificationService(this.logging.createLogger('notifications'));
+            const registry = this.caps.getRegistry();
+            if (registry) {
+                this._service.setRegistry(registry);
+            }
+        }
+        return this._service;
+    }
+    async notify(notification) {
+        return this.service.notify(notification);
+    }
+}
+exports.NotificationServiceWrapper = NotificationServiceWrapper;

package/dist/core/notification/toast-wrapper.service.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToastServiceWrapper = void 0;
+const core_1 = require("@camstack/core");
+/**
+ * NestJS-injectable wrapper around the core ToastService.
+ *
+ * Provides toast broadcasting to connected UI clients.
+ */
+class ToastServiceWrapper {
+    _service = new core_1.ToastService();
+    get service() {
+        return this._service;
+    }
+    broadcast(toast) {
+        this._service.broadcast(toast);
+    }
+    sendToUser(userId, toast) {
+        this._service.sendToUser(userId, toast);
+    }
+    subscribe(connectionId, userId, callback) {
+        return this._service.subscribe(connectionId, userId, callback);
+    }
+}
+exports.ToastServiceWrapper = ToastServiceWrapper;

package/dist/core/provider/provider.tokens.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_MANAGER = void 0;
+exports.PROVIDER_MANAGER = Symbol('PROVIDER_MANAGER');

package/dist/core/repl/repl-engine.service.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplEngineService = void 0;
+const core_1 = require("@camstack/core");
+const types_1 = require("@camstack/types");
+class ReplEngineService extends core_1.ReplEngine {
+    /**
+     * Lazily-instantiated `SystemMirror` shared across REPL sessions.
+     * Holds a single warm-boot mirror that every `sm.getDeviceById(id)`
+     * lookup serves from. Init runs at first access (Promise cached so
+     * concurrent sessions don't double-fetch).
+     */
+    static systemMirror = null;
+    static systemMirrorInit = null;
+    /**
+     * Build a `SystemMirrorApi` for in-process server use. The cap-method
+     * surface (deviceManager / deviceState queries) goes through the
+     * standard broker tRPC client — those resolve locally via
+     * `localProviderLink`. The `live.onEvent` channel is NOT a cap, so
+     * the broker can't route it; we synthesize the same shape over the
+     * local `EventBusService` so SystemMirror subscriptions work without
+     * crossing the network boundary or polling the broker for a
+     * non-existent `live` service.
+     */
+    static buildInProcessApi(addonRegistry, eventBus) {
+        const baseApi = addonRegistry.getBrokerApi();
+        return {
+            ...baseApi,
+            live: {
+                onEvent: {
+                    subscribe: (input, opts) => {
+                        const off = eventBus.subscribe({ category: input.category }, (evt) => {
+                            try {
+                                opts.onData({ data: evt.data });
+                            }
+                            catch (err) {
+                                opts.onError?.(err);
+                            }
+                        });
+                        return { unsubscribe: off };
+                    },
+                },
+            },
+        };
+    }
+    static getOrInitSystemMirror(addonRegistry, eventBus) {
+        if (this.systemMirror)
+            return Promise.resolve(this.systemMirror);
+        if (!this.systemMirrorInit) {
+            const api = this.buildInProcessApi(addonRegistry, eventBus);
+            const sm = new types_1.SystemMirror(api);
+            this.systemMirrorInit = sm.init().then(() => {
+                this.systemMirror = sm;
+                return sm;
+            });
+        }
+        return this.systemMirrorInit;
+    }
+    constructor(addonRegistry, eventBus, _loggingService) {
+        const contextProvider = {
+            async getSystemSandbox() {
+                const integrationRegistry = addonRegistry.getIntegrationRegistry();
+                const deviceRegistry = addonRegistry.getDeviceRegistry();
+                // Warm-boot the SystemMirror so `sm.getDeviceById(id)` is sync
+                // for the first user expression.
+                const sm = await ReplEngineService.getOrInitSystemMirror(addonRegistry, eventBus);
+                return {
+                    // ── New canonical API ───────────────────────────────────────
+                    /**
+                     * SystemMirror — the cap-driven, reactive view of every
+                     * device. Sync `getDeviceById(id)`, typed `state.<cap>.value`
+                     * reads, full method dispatch, query helpers.
+                     */
+                    sm,
+                    // ── Legacy (kept for backward-compat) ──────────────────────
+                    addonRegistry,
+                    eventBus,
+                    integrationRegistry,
+                    devices: () => deviceRegistry.getAll(),
+                    integrations: async () => (await integrationRegistry?.listIntegrations()) ?? [],
+                    addons: () => addonRegistry.listAddons(),
+                    getDevice: (id) => deviceRegistry.getById(id),
+                    getIntegration: async (id) => (await integrationRegistry?.getIntegration(id)) ?? null,
+                    getSystemMirror: () => Promise.resolve(sm),
+                };
+            },
+            async getDeviceSandbox(deviceId) {
+                const deviceRegistry = addonRegistry.getDeviceRegistry();
+                const rawDevice = deviceRegistry.getById(deviceId);
+                const sm = await ReplEngineService.getOrInitSystemMirror(addonRegistry, eventBus);
+                // `device` is the typed DeviceProxy backed by the SystemMirror
+                // mirror — same shape as `sm.getDeviceById(deviceId)`. Sync
+                // state reads + cap-method dispatch via the wrapper chain.
+                const device = sm.getDeviceById(deviceId);
+                return {
+                    /** SystemMirror — full cluster view. */
+                    sm,
+                    /**
+                     * The current device as a DeviceProxy. Sync state reads
+                     * (`device.state.battery.value`) + async cap methods
+                     * (`await device.snapshot.getSnapshot({})`).
+                     */
+                    device,
+                    /** Numeric device id (same as URL). */
+                    deviceId,
+                    /** Device metadata (name, addonId, type, online, …). */
+                    info: sm.getDeviceInfo(deviceId),
+                    /** Raw IDevice instance — escape hatch for legacy access.
+                     *  Prefer `device` (DeviceProxy) for new code. */
+                    rawDevice,
+                };
+            },
+            getProviderSandbox(addonId) {
+                const integrationRegistry = addonRegistry.getIntegrationRegistry();
+                const deviceRegistry = addonRegistry.getDeviceRegistry();
+                const devices = deviceRegistry.getAllForAddon(addonId);
+                return {
+                    getIntegration: () => integrationRegistry?.getIntegration(addonId) ?? Promise.resolve(null),
+                    devices,
+                };
+            },
+            getAddonSandbox(addonId) {
+                // REPL exposes addon metadata only — never the live in-process
+                // instance. Direct addon access only works for hub-local addons
+                // and breaks for remote-agent addons. To invoke addon behaviour
+                // from the REPL, use the cap router via tRPC instead.
+                const entry = addonRegistry.listAddons().find((e) => e.manifest.id === addonId);
+                return {
+                    manifest: entry?.manifest,
+                    declaration: entry?.declaration,
+                    source: entry?.source,
+                    installSource: entry?.installSource,
+                    process: entry?.process,
+                };
+            },
+        };
+        super(contextProvider);
+    }
+}
+exports.ReplEngineService = ReplEngineService;

package/dist/core/storage/fs-storage-backend.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsStorageBackend = void 0;
+// Re-export from @camstack/core
+var core_1 = require("@camstack/core");
+Object.defineProperty(exports, "FsStorageBackend", { enumerable: true, get: function () { return core_1.FsStorageBackend; } });

package/dist/core/storage/storage-location-manager.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageLocationManager = void 0;
+// Re-export from @camstack/core
+var core_1 = require("@camstack/core");
+Object.defineProperty(exports, "StorageLocationManager", { enumerable: true, get: function () { return core_1.StorageLocationManager; } });

package/dist/core/storage/storage.service.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageService = void 0;
+const core_1 = require("@camstack/core");
+class StorageService extends core_1.StorageManager {
+}
+exports.StorageService = StorageService;

package/dist/core/streaming/stream-probe.service.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamProbeService = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const types_1 = require("@camstack/types");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const CACHE_TTL_MS = 3_600_000; // 1 hour
+const PROBE_TIMEOUT_MS = 5_000;
+/** Codec aliases normalised to canonical names. */
+const CODEC_ALIASES = {
+    hevc: 'h265',
+};
+class StreamProbeService {
+    logger;
+    cache = new Map();
+    constructor(loggingService) {
+        this.logger = loggingService.createLogger('StreamProbeService');
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /** Probe a stream URL and return its metadata (cached for 1 hour). */
+    async probe(url, options) {
+        const force = options?.force ?? false;
+        if (!force) {
+            const cached = this.cache.get(url);
+            if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+                return cached.metadata;
+            }
+        }
+        const metadata = await this.runProbe(url);
+        this.cache.set(url, { metadata, timestamp: Date.now() });
+        return metadata;
+    }
+    /**
+     * Generic field probe: given a field key and value, decides how to probe.
+     * Stream fields (stream_*) → ffprobe, other URLs → HTTP HEAD check.
+     */
+    async probeField(key, value) {
+        const url = String(value ?? '').trim();
+        if (!url) {
+            return { status: 'error', error: 'No URL provided' };
+        }
+        // Stream fields: use ffprobe
+        if (key.startsWith('stream')) {
+            const meta = await this.probe(url, { force: true });
+            const labels = [];
+            if (meta.width && meta.height)
+                labels.push(`${meta.width}\u00d7${meta.height}`);
+            if (meta.codec) {
+                const codecDisplay = { h265: 'H.265', h264: 'H.264', hevc: 'H.265' };
+                labels.push(codecDisplay[meta.codec] ?? meta.codec.toUpperCase());
+            }
+            if (meta.fps)
+                labels.push(`${Math.round(meta.fps)}fps`);
+            if (meta.audio?.codec) {
+                const audioCodec = meta.audio.codec.toUpperCase();
+                const audioBits = [audioCodec];
+                if (meta.audio.sampleRate)
+                    audioBits.push(`${Math.round(meta.audio.sampleRate / 1000)}kHz`);
+                if (meta.audio.channels === 1)
+                    audioBits.push('mono');
+                else if (meta.audio.channels === 2)
+                    audioBits.push('stereo');
+                else if (meta.audio.channels)
+                    audioBits.push(`${meta.audio.channels}ch`);
+                labels.push(`audio: ${audioBits.join(' ')}`);
+            }
+            if (labels.length === 0) {
+                return { status: 'error', error: 'No video streams found at URL' };
+            }
+            return { status: 'ok', labels };
+        }
+        // Other URL fields (snapshot, etc.): GET with early abort to check reachability + content-type
+        try {
+            const controller = new AbortController();
+            const timeout = AbortSignal.timeout(5000);
+            timeout.addEventListener('abort', () => controller.abort(timeout.reason));
+            const response = await fetch(url, { method: 'GET', signal: controller.signal });
+            if (!response.ok) {
+                controller.abort();
+                return { status: 'error', error: `HTTP ${response.status} ${response.statusText}` };
+            }
+            const contentType = response.headers.get('content-type') ?? '';
+            controller.abort(); // Don't download the full body
+            const labels = ['Reachable'];
+            if (contentType.startsWith('image/')) {
+                labels.push(contentType.replace('image/', '').toUpperCase());
+            }
+            return { status: 'ok', labels };
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                // We aborted intentionally after reading headers — that's success
+                return { status: 'ok', labels: ['Reachable'] };
+            }
+            const msg = (0, types_1.errMsg)(err);
+            return { status: 'error', error: `Unreachable: ${msg}` };
+        }
+    }
+    /** Clear cached metadata for a single URL or all URLs. */
+    clearCache(url) {
+        if (url) {
+            this.cache.delete(url);
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    async runProbe(url) {
+        try {
+            // Query first video + first audio stream in one ffprobe pass.
+            // `-show_streams` returns every stream in the container; we filter
+            // by codec_type when parsing. Fields cover both kinds.
+            const { stdout } = await execFileAsync('ffprobe', [
+                '-v',
+                'error',
+                '-rtsp_transport',
+                'tcp',
+                '-timeout',
+                '5000000',
+                '-show_entries',
+                'stream=codec_type,codec_name,profile,width,height,r_frame_rate,bit_rate,sample_rate,channels',
+                '-of',
+                'json',
+                url,
+            ], { timeout: PROBE_TIMEOUT_MS });
+            return this.parseOutput(stdout);
+        }
+        catch (err) {
+            this.logger.error('ffprobe failed', { meta: { url, error: String(err) } });
+            return {};
+        }
+    }
+    parseOutput(stdout) {
+        const parsed = JSON.parse(stdout);
+        const streams = parsed.streams;
+        if (!Array.isArray(streams) || streams.length === 0) {
+            return {};
+        }
+        const meta = {};
+        for (const raw of streams) {
+            const stream = raw;
+            const codecType = typeof stream.codec_type === 'string' ? stream.codec_type : undefined;
+            if (codecType === 'video' && meta.codec === undefined) {
+                const rawCodec = typeof stream.codec_name === 'string' ? stream.codec_name : undefined;
+                meta.codec = rawCodec ? (CODEC_ALIASES[rawCodec] ?? rawCodec) : undefined;
+                if (typeof stream.width === 'number')
+                    meta.width = stream.width;
+                if (typeof stream.height === 'number')
+                    meta.height = stream.height;
+                const fps = this.parseFps(stream.r_frame_rate);
+                if (fps !== undefined)
+                    meta.fps = fps;
+                const bitrateKbps = this.parseBitrateKbps(stream.bit_rate);
+                if (bitrateKbps !== undefined)
+                    meta.bitrateKbps = bitrateKbps;
+            }
+            else if (codecType === 'audio' && meta.audio === undefined) {
+                const audio = {};
+                if (typeof stream.codec_name === 'string')
+                    audio.codec = stream.codec_name;
+                if (typeof stream.profile === 'string')
+                    audio.profile = stream.profile;
+                const sampleRate = this.parseIntField(stream.sample_rate);
+                if (sampleRate !== undefined)
+                    audio.sampleRate = sampleRate;
+                if (typeof stream.channels === 'number')
+                    audio.channels = stream.channels;
+                const audioBitrateKbps = this.parseBitrateKbps(stream.bit_rate);
+                if (audioBitrateKbps !== undefined)
+                    audio.bitrateKbps = audioBitrateKbps;
+                meta.audio = audio;
+            }
+        }
+        return meta;
+    }
+    parseIntField(value) {
+        const n = typeof value === 'string' ? Number(value) : typeof value === 'number' ? value : NaN;
+        if (!Number.isFinite(n) || n <= 0)
+            return undefined;
+        return Math.round(n);
+    }
+    /** Parse fractional frame rate string like "25/1" → 25. */
+    parseFps(value) {
+        if (typeof value !== 'string')
+            return undefined;
+        const parts = value.split('/');
+        if (parts.length !== 2)
+            return undefined;
+        const num = Number(parts[0]);
+        const den = Number(parts[1]);
+        if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0)
+            return undefined;
+        return Math.round((num / den) * 100) / 100;
+    }
+    /** Parse bit_rate string (bps) → kbps. */
+    parseBitrateKbps(value) {
+        const n = typeof value === 'string' ? Number(value) : typeof value === 'number' ? value : NaN;
+        if (!Number.isFinite(n) || n <= 0)
+            return undefined;
+        return Math.round(n / 1000);
+    }
+}
+exports.StreamProbeService = StreamProbeService;

package/dist/core/topology/topology-emitter.service.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopologyEmitterService = void 0;
+/**
+ * TopologyEmitterService — push the cluster topology over the event bus.
+ *
+ * Subscribes to agent connect/disconnect + addon lifecycle events,
+ * recomputes the topology snapshot on each change (debounced), and
+ * emits `cluster.topology-snapshot`. Also fires a periodic safety-net
+ * snapshot every TOPOLOGY_HEARTBEAT_MS so consumers that boot mid-
+ * stream get a fresh payload without waiting for the next lifecycle
+ * change.
+ *
+ * Replaces UI polling on `nodes.topology`. Admin-ui dashboards
+ * subscribe to the snapshot category and read state directly from the
+ * payload — zero round-trip.
+ */
+const node_crypto_1 = require("node:crypto");
+const types_1 = require("@camstack/types");
+const cap_providers_1 = require("../../api/core/cap-providers");
+const DEBOUNCE_MS = 200;
+const HEARTBEAT_MS = 30_000;
+const LIFECYCLE_CATEGORIES = [
+    types_1.EventCategory.AgentOnline,
+    types_1.EventCategory.AgentOffline,
+    types_1.EventCategory.WorkerOnline,
+    types_1.EventCategory.WorkerOffline,
+    types_1.EventCategory.AgentUnregistered,
+    types_1.EventCategory.AddonStarted,
+    types_1.EventCategory.AddonStopped,
+    types_1.EventCategory.AddonRestarted,
+    types_1.EventCategory.AddonInstalled,
+    types_1.EventCategory.AddonUninstalled,
+    types_1.EventCategory.AddonUpdated,
+    types_1.EventCategory.AddonCrashed,
+];
+class TopologyEmitterService {
+    eventBus;
+    agentRegistry;
+    addonRegistry;
+    unsubscribers = [];
+    debounceTimer = null;
+    heartbeatTimer = null;
+    emitting = false;
+    constructor(eventBus, agentRegistry, addonRegistry) {
+        this.eventBus = eventBus;
+        this.agentRegistry = agentRegistry;
+        this.addonRegistry = addonRegistry;
+    }
+    onModuleInit() {
+        for (const category of LIFECYCLE_CATEGORIES) {
+            const unsub = this.eventBus.subscribe({ category }, () => this.scheduleEmit());
+            this.unsubscribers.push(unsub);
+        }
+        // Heartbeat fires the first emit ~immediately so consumers that
+        // mount before any lifecycle change still see a snapshot.
+        void this.emitNow();
+        this.heartbeatTimer = setInterval(() => this.scheduleEmit(), HEARTBEAT_MS);
+    }
+    onModuleDestroy() {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        for (const unsub of this.unsubscribers) {
+            try {
+                unsub();
+            }
+            catch {
+                /* idempotent */
+            }
+        }
+        this.unsubscribers.length = 0;
+    }
+    scheduleEmit() {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            void this.emitNow();
+        }, DEBOUNCE_MS);
+    }
+    async emitNow() {
+        if (this.emitting)
+            return;
+        this.emitting = true;
+        try {
+            const nodes = await (0, cap_providers_1.computeTopology)(this.agentRegistry, this.addonRegistry);
+            this.eventBus.emit({
+                id: (0, node_crypto_1.randomUUID)(),
+                timestamp: new Date(),
+                source: { type: 'core', id: 'topology-emitter' },
+                category: types_1.EventCategory.ClusterTopologySnapshot,
+                data: { nodes, timestamp: Date.now() },
+            });
+        }
+        catch {
+            // Best-effort observability path. Next lifecycle event or the
+            // heartbeat will retry — no need to log here.
+        }
+        finally {
+            this.emitting = false;
+        }
+    }
+}
+exports.TopologyEmitterService = TopologyEmitterService;