@soilsidekick/sdk 1.2.0 → 2.0.0

package/sdks/dist/sensors/mqtt.js

@@ -0,0 +1,179 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MQTTClient = void 0;
+const mqtt_1 = __importDefault(require("mqtt"));
+/**
+ * MQTT Client for direct broker connection
+ *
+ * Used for high-frequency sensor data publishing
+ */
+class MQTTClient {
+    constructor(config) {
+        this.client = null;
+        this.status = 'disconnected';
+        this.messageHandlers = new Map();
+        this.statusListeners = [];
+        this.config = config;
+    }
+    /**
+     * Connect to MQTT broker
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const url = `${this.config.protocol}://${this.config.host}:${this.config.port}`;
+            this.client = mqtt_1.default.connect(url, {
+                username: this.config.username,
+                password: this.config.password,
+                reconnectPeriod: this.config.reconnectPeriod || 5000,
+                connectTimeout: this.config.connectTimeout || 30000,
+                clean: true,
+            });
+            this.client.on('connect', () => {
+                this.updateStatus('connected');
+                console.log('✓ Connected to MQTT broker');
+                resolve();
+            });
+            this.client.on('error', (err) => {
+                this.updateStatus('error');
+                console.error('MQTT Error:', err);
+                reject(err);
+            });
+            this.client.on('disconnect', () => {
+                this.updateStatus('disconnected');
+                console.log('Disconnected from MQTT broker');
+            });
+            this.client.on('message', (topic, message) => {
+                this.handleMessage(topic, message);
+            });
+            this.updateStatus('connecting');
+        });
+    }
+    /**
+     * Publish sensor data to topic
+     *
+     * @param topic - MQTT topic (e.g., "skyline/device-001/readings")
+     * @param payload - Data to publish
+     * @param options - Publish options
+     */
+    publish(topic, payload, options) {
+        if (!this.client || !this.client.connected) {
+            throw new Error('MQTT client not connected');
+        }
+        const message = typeof payload === 'string'
+            ? payload
+            : JSON.stringify(payload);
+        this.client.publish(topic, message, {
+            qos: options?.qos ?? 1,
+            retain: options?.retain ?? false,
+        });
+    }
+    /**
+     * Subscribe to MQTT topic
+     *
+     * @param topic - Topic pattern (can use wildcards)
+     * @param handler - Message handler
+     * @param qos - Quality of Service
+     */
+    subscribe(topic, handler, qos = 1) {
+        if (!this.client) {
+            throw new Error('MQTT client not initialized');
+        }
+        this.client.subscribe(topic, { qos }, (err) => {
+            if (err) {
+                console.error(`Failed to subscribe to ${topic}:`, err);
+                return;
+            }
+            if (!this.messageHandlers.has(topic)) {
+                this.messageHandlers.set(topic, []);
+            }
+            this.messageHandlers.get(topic).push(handler);
+            console.log(`Subscribed to ${topic}`);
+        });
+    }
+    /**
+     * Unsubscribe from topic
+     */
+    unsubscribe(topic) {
+        if (!this.client)
+            return;
+        this.client.unsubscribe(topic);
+        this.messageHandlers.delete(topic);
+        console.log(`Unsubscribed from ${topic}`);
+    }
+    /**
+     * Disconnect from broker
+     */
+    disconnect() {
+        if (this.client) {
+            this.client.end();
+            this.client = null;
+            this.updateStatus('disconnected');
+        }
+    }
+    /**
+     * Get current connection status
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * Listen for connection status changes
+     */
+    onStatusChange(listener) {
+        this.statusListeners.push(listener);
+    }
+    updateStatus(status) {
+        this.status = status;
+        this.statusListeners.forEach(listener => listener(status));
+    }
+    handleMessage(topic, message) {
+        // Check exact topic match
+        const exactHandlers = this.messageHandlers.get(topic);
+        if (exactHandlers) {
+            this.processMessage(exactHandlers, message);
+        }
+        // Check wildcard subscriptions
+        this.messageHandlers.forEach((handlers, subscriptionTopic) => {
+            if (this.topicMatches(subscriptionTopic, topic)) {
+                this.processMessage(handlers, message);
+            }
+        });
+    }
+    processMessage(handlers, message) {
+        const payload = this.parseMessage(message);
+        handlers.forEach(handler => {
+            try {
+                handler(payload);
+            }
+            catch (err) {
+                console.error('Message handler error:', err);
+            }
+        });
+    }
+    topicMatches(subscription, topic) {
+        // Handle wildcards: + (single level), # (multi level)
+        const subParts = subscription.split('/');
+        const topicParts = topic.split('/');
+        for (let i = 0; i < subParts.length; i++) {
+            if (subParts[i] === '#')
+                return true;
+            if (subParts[i] === '+')
+                continue;
+            if (subParts[i] !== topicParts[i])
+                return false;
+        }
+        return subParts.length === topicParts.length;
+    }
+    parseMessage(message) {
+        try {
+            return JSON.parse(message.toString());
+        }
+        catch {
+            return message.toString();
+        }
+    }
+}
+exports.MQTTClient = MQTTClient;

package/sdks/dist/sensors/readings.d.ts

@@ -0,0 +1,81 @@
+import { LeafEnginesClient } from '../client';
+import { SensorReading, SensorReadingPayload, IngestionResponse, ReadingsQueryParams, ReadingsAggregation, Subscription } from '../types';
+/**
+ * Sensor Readings API
+ *
+ * Query historical data and subscribe to real-time updates
+ */
+export declare class SensorReadingsAPI {
+    private client;
+    private subscriptions;
+    constructor(client: LeafEnginesClient);
+    /**
+     * Send sensor readings via HTTP (MQTT fallback)
+     *
+     * @param payload - Sensor data to ingest
+     * @returns Ingestion confirmation
+     *
+     * @example
+     * ```typescript
+     * const result = await client.sensors.readings.send({
+     *   deviceId: 'skyline-001',
+     *   deviceType: 'mmwave_radar',
+     *   timestamp: new Date(),
+     *   readings: [{
+     *     metric: 'reflectivity',
+     *     value: 0.92,
+     *     unit: 'ratio',
+     *     confidence: 0.94,
+     *     timestamp: new Date(),
+     *   }],
+     *   metadata: { firmwareVersion: '1.2.0' },
+     * });
+     * ```
+     */
+    send(payload: SensorReadingPayload): Promise<IngestionResponse>;
+    /**
+     * Query historical readings
+     *
+     * @param params - Query parameters
+     * @returns Array of sensor readings
+     */
+    query(params: ReadingsQueryParams): Promise<SensorReading[]>;
+    /**
+     * Get latest reading for a device
+     *
+     * @param deviceId - Device identifier
+     * @param metric - Optional metric filter
+     * @returns Latest reading or null
+     */
+    getLatest(deviceId: string, metric?: string): Promise<SensorReading | null>;
+    /**
+     * Get aggregated readings (hourly, daily, etc.)
+     *
+     * @param params - Aggregation parameters
+     * @returns Aggregated data points
+     */
+    aggregate(params: {
+        deviceId: string;
+        metric: string;
+        startTime: Date;
+        endTime: Date;
+        interval: '1h' | '1d' | '1w' | '1m';
+    }): Promise<ReadingsAggregation[]>;
+    /**
+     * Subscribe to real-time readings (WebSocket)
+     *
+     * @param deviceId - Device to subscribe to
+     * @param callback - Handler for new readings
+     * @returns Subscription object
+     */
+    subscribe(deviceId: string, callback: (reading: SensorReading) => void): Subscription;
+    /**
+     * Unsubscribe from device updates
+     */
+    unsubscribe(deviceId: string): void;
+    /**
+     * Unsubscribe from all devices
+     */
+    unsubscribeAll(): void;
+    private parseReading;
+}

package/sdks/dist/sensors/readings.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SensorReadingsAPI = void 0;
+/**
+ * Sensor Readings API
+ *
+ * Query historical data and subscribe to real-time updates
+ */
+class SensorReadingsAPI {
+    constructor(client) {
+        this.subscriptions = new Map();
+        this.client = client;
+    }
+    /**
+     * Send sensor readings via HTTP (MQTT fallback)
+     *
+     * @param payload - Sensor data to ingest
+     * @returns Ingestion confirmation
+     *
+     * @example
+     * ```typescript
+     * const result = await client.sensors.readings.send({
+     *   deviceId: 'skyline-001',
+     *   deviceType: 'mmwave_radar',
+     *   timestamp: new Date(),
+     *   readings: [{
+     *     metric: 'reflectivity',
+     *     value: 0.92,
+     *     unit: 'ratio',
+     *     confidence: 0.94,
+     *     timestamp: new Date(),
+     *   }],
+     *   metadata: { firmwareVersion: '1.2.0' },
+     * });
+     * ```
+     */
+    async send(payload) {
+        const response = await this.client.request({
+            method: 'POST',
+            endpoint: '/sensor-data-ingestion',
+            body: {
+                device_id: payload.deviceId,
+                device_type: payload.deviceType,
+                timestamp: payload.timestamp.toISOString(),
+                readings: payload.readings.map(r => ({
+                    metric: r.metric,
+                    value: r.value,
+                    unit: r.unit,
+                    confidence: r.confidence,
+                    timestamp: r.timestamp.toISOString(),
+                })),
+                metadata: {
+                    firmware_version: payload.metadata.firmwareVersion,
+                    battery_level: payload.metadata.batteryLevel,
+                    signal_strength: payload.metadata.signalStrength,
+                },
+            },
+        });
+        return {
+            ingestionId: response.data.ingestion_id,
+            queuedAt: new Date(response.data.queued_at),
+            processedReadings: response.data.processed_readings,
+            estimatedProcessingMs: response.data.estimated_processing_ms,
+            status: response.data.status,
+        };
+    }
+    /**
+     * Query historical readings
+     *
+     * @param params - Query parameters
+     * @returns Array of sensor readings
+     */
+    async query(params) {
+        const response = await this.client.request({
+            method: 'GET',
+            endpoint: '/sensor-readings',
+            params: {
+                device_id: params.deviceId,
+                metric: params.metric,
+                start_time: params.startTime.toISOString(),
+                end_time: params.endTime.toISOString(),
+                limit: params.limit || 100,
+                offset: params.offset || 0,
+                order: params.order || 'desc',
+            },
+        });
+        return response.data.map(this.parseReading);
+    }
+    /**
+     * Get latest reading for a device
+     *
+     * @param deviceId - Device identifier
+     * @param metric - Optional metric filter
+     * @returns Latest reading or null
+     */
+    async getLatest(deviceId, metric) {
+        try {
+            const response = await this.client.request({
+                method: 'GET',
+                endpoint: '/sensor-readings/latest',
+                params: {
+                    device_id: deviceId,
+                    metric,
+                },
+            });
+            return response.data ? this.parseReading(response.data) : null;
+        }
+        catch (error) {
+            // Return null if no readings found
+            return null;
+        }
+    }
+    /**
+     * Get aggregated readings (hourly, daily, etc.)
+     *
+     * @param params - Aggregation parameters
+     * @returns Aggregated data points
+     */
+    async aggregate(params) {
+        const response = await this.client.request({
+            method: 'GET',
+            endpoint: '/sensor-readings/aggregate',
+            params: {
+                device_id: params.deviceId,
+                metric: params.metric,
+                start_time: params.startTime.toISOString(),
+                end_time: params.endTime.toISOString(),
+                interval: params.interval,
+            },
+        });
+        return response.data.map((agg) => ({
+            deviceId: agg.device_id,
+            metric: agg.metric,
+            startTime: new Date(agg.start_time),
+            endTime: new Date(agg.end_time),
+            count: agg.count,
+            avg: agg.avg,
+            min: agg.min,
+            max: agg.max,
+            sum: agg.sum,
+            interval: agg.interval,
+        }));
+    }
+    /**
+     * Subscribe to real-time readings (WebSocket)
+     *
+     * @param deviceId - Device to subscribe to
+     * @param callback - Handler for new readings
+     * @returns Subscription object
+     */
+    subscribe(deviceId, callback) {
+        const wsUrl = this.client.getWebSocketUrl();
+        const ws = new WebSocket(`${wsUrl}/sensor-readings/${deviceId}`);
+        ws.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data);
+                callback(this.parseReading(data));
+            }
+            catch (error) {
+                console.error('Failed to parse WebSocket message:', error);
+            }
+        };
+        ws.onerror = (error) => {
+            console.error('WebSocket error:', error);
+        };
+        const subscription = {
+            unsubscribe: () => {
+                ws.close();
+                this.subscriptions.delete(deviceId);
+            },
+            isActive: () => ws.readyState === WebSocket.OPEN,
+        };
+        this.subscriptions.set(deviceId, subscription);
+        return subscription;
+    }
+    /**
+     * Unsubscribe from device updates
+     */
+    unsubscribe(deviceId) {
+        const sub = this.subscriptions.get(deviceId);
+        if (sub) {
+            sub.unsubscribe();
+        }
+    }
+    /**
+     * Unsubscribe from all devices
+     */
+    unsubscribeAll() {
+        this.subscriptions.forEach(sub => sub.unsubscribe());
+        this.subscriptions.clear();
+    }
+    parseReading(data) {
+        return {
+            id: data.id,
+            deviceId: data.device_id,
+            timestamp: new Date(data.timestamp),
+            metric: data.metric,
+            value: data.value,
+            unit: data.unit,
+            confidence: data.confidence,
+            receivedAt: new Date(data.received_at),
+        };
+    }
+}
+exports.SensorReadingsAPI = SensorReadingsAPI;