@soilsidekick/sdk 1.2.0 → 2.0.0

package/package.json

@@ -1,21 +1,9 @@
 {
   "name": "@soilsidekick/sdk",
-  "version": "1.2.0",
-  "description": "OpenAPI client for @soilsidekick/sdk",
-  "author": "OpenAPI-Generator",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "module": "./dist/esm/index.js",
-  "sideEffects": false,
-  "scripts": {
-    "build": "tsc && tsc -p tsconfig.esm.json",
-    "prepare": "npm run build"
-  },
-  "devDependencies": {
-    "typescript": "^4.0 || ^5.0"
+  "version": "2.0.0",
+  "publishConfig": {
+    "access": "public"
   }
 }
+
+

package/sdks/README.md

@@ -0,0 +1,254 @@
+# LeafEngines SDK v2.0
+
+Official TypeScript/JavaScript SDK for LeafEngines API - Agricultural intelligence platform with Skyline Instruments sensor integration.
+
+## Installation
+
+```bash
+npm install @soilsidekick/sdk
+```
+
+## Quick Start
+
+```typescript
+import { LeafEnginesClient } from '@soilsidekick/sdk';
+
+const client = new LeafEnginesClient({
+  apiKey: 'sk_live_your_api_key',
+  projectRef: 'your-project-ref',
+});
+
+// Register a Skyline sensor device
+const device = await client.sensors.devices.register({
+  deviceId: 'skyline-mmWave-001',
+  deviceType: 'mmwave_radar',
+  farmId: 'farm-123',
+  firmwareVersion: '1.2.0',
+});
+
+console.log(`Device registered: ${device.deviceId}`);
+```
+
+## Sensor Integration
+
+### Register Devices
+
+```typescript
+// Register new sensor
+const device = await client.sensors.devices.register({
+  deviceId: 'skyline-001',
+  deviceType: 'mmwave_radar',  // or 'quantum_rf', 'precision_timing'
+  farmId: 'farm-123',
+  firmwareVersion: '1.0.0',
+});
+
+// List all devices
+const devices = await client.sensors.devices.list({
+  farmId: 'farm-123',
+  status: 'active',
+});
+
+// Get device details
+const details = await client.sensors.devices.get('skyline-001');
+
+// Update device
+await client.sensors.devices.update('skyline-001', {
+  firmwareVersion: '1.1.0',
+});
+```
+
+### Send Sensor Data
+
+```typescript
+// Send readings via HTTP (MQTT fallback)
+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(),
+    },
+    {
+      metric: 'canopy_density',
+      value: 0.78,
+      unit: 'ratio',
+      timestamp: new Date(),
+    },
+  ],
+  metadata: {
+    firmwareVersion: '1.0.0',
+    batteryLevel: 95,
+    signalStrength: -45,
+  },
+});
+```
+
+### Query Historical Data
+
+```typescript
+// Get readings for time range
+const readings = await client.sensors.readings.query({
+  deviceId: 'skyline-001',
+  metric: 'reflectivity',
+  startTime: new Date('2026-02-01'),
+  endTime: new Date(),
+  limit: 1000,
+});
+
+// Get latest reading
+const latest = await client.sensors.readings.getLatest('skyline-001', 'reflectivity');
+
+// Get aggregated data (hourly averages)
+const hourly = await client.sensors.readings.aggregate({
+  deviceId: 'skyline-001',
+  metric: 'reflectivity',
+  startTime: new Date('2026-02-01'),
+  endTime: new Date(),
+  interval: '1h',
+});
+```
+
+### Real-time Streaming
+
+```typescript
+// Subscribe to real-time readings
+const subscription = client.sensors.readings.subscribe(
+  'skyline-001',
+  (reading) => {
+    console.log(`New reading: ${reading.metric} = ${reading.value}`);
+  }
+);
+
+// Later: unsubscribe
+subscription.unsubscribe();
+```
+
+### Alert Management
+
+```typescript
+// Subscribe to critical alerts
+client.sensors.alerts.subscribe(
+  (alert) => {
+    if (alert.severity === 'critical') {
+      sendEmergencyNotification(alert);
+    }
+  },
+  { severity: ['warning', 'critical'] }
+);
+
+// Get unacknowledged alerts
+const alerts = await client.sensors.alerts.getAlerts({
+  acknowledged: false,
+  severity: 'critical',
+});
+
+// Acknowledge alert
+await client.sensors.alerts.acknowledge(alerts[0].id);
+```
+
+## MQTT Direct Connection
+
+For high-frequency data publishing, connect directly to MQTT broker:
+
+```typescript
+// Connect to MQTT broker
+await client.connectMQTT({
+  host: 'your-cluster.s1.eu.hivemq.cloud',
+  port: 8883,
+  protocol: 'mqtts',
+  username: 'your-username',
+  password: 'your-password',
+});
+
+// Publish sensor data
+client.mqtt!.publish(
+  'skyline/skyline-001/readings',
+  {
+    device_id: 'skyline-001',
+    device_type: 'mmwave_radar',
+    timestamp: new Date().toISOString(),
+    readings: [
+      { metric: 'reflectivity', value: 0.92, unit: 'ratio' }
+    ],
+    metadata: { firmware_version: '1.0.0' },
+  }
+);
+
+// Subscribe to topics
+client.mqtt!.subscribe('skyline/+/status', (message) => {
+  console.log('Device status:', message);
+});
+
+// Monitor connection
+client.mqtt!.onStatusChange((status) => {
+  console.log('MQTT status:', status);
+});
+
+// Disconnect when done
+client.disconnectMQTT();
+```
+
+## Error Handling
+
+```typescript
+import { LeafEnginesError } from '@soilsidekick/sdk';
+
+try {
+  await client.sensors.devices.get('unknown-device');
+} catch (error) {
+  if (error instanceof LeafEnginesError) {
+    console.error(`API Error ${error.code}: ${error.message}`);
+    console.error('Details:', error.details);
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+const client = new LeafEnginesClient({
+  apiKey: 'your-api-key',
+  projectRef: 'your-project-ref',
+  environment: 'production',  // or 'sandbox'
+  baseUrl: 'https://custom-endpoint.com',  // Optional
+  timeout: 30000,  // Request timeout in ms
+});
+```
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import {
+  LeafEnginesClient,
+  SensorDevice,
+  SensorReading,
+  SensorAlert,
+  DeviceType,
+  AlertSeverity,
+} from '@soilsidekick/sdk';
+```
+
+## API Reference
+
+See [SDK_V2_UPGRADE_SPEC.md](../SDK_V2_UPGRADE_SPEC.md) for complete API specification.
+
+## Changelog
+
+### v2.0.0 (February 2026)
+- ✨ Skyline Instruments sensor integration
+- ✨ Sensor device management API
+- ✨ Real-time data streaming (WebSocket)
+- ✨ MQTT direct broker connection
+- ✨ Alert management system
+- ✨ Historical data aggregation
+
+## License
+
+MIT © SoilSidekick Pro

package/sdks/__tests__/devices.test.ts

@@ -0,0 +1,87 @@
+import { SensorDevicesAPI } from '../sensors/devices';
+import { LeafEnginesClient } from '../client';
+
+describe('SensorDevicesAPI', () => {
+  let client: LeafEnginesClient;
+  let devices: SensorDevicesAPI;
+
+  beforeEach(() => {
+    client = new LeafEnginesClient({
+      apiKey: 'test-api-key',
+      projectRef: 'test-project',
+    });
+    devices = new SensorDevicesAPI(client);
+  });
+
+  describe('register', () => {
+    it('should register a new device', async () => {
+      const mockResponse = {
+        id: 'uuid-123',
+        device_id: 'skyline-001',
+        device_type: 'mmwave_radar',
+        firmware_version: '1.0.0',
+        status: 'active',
+        last_seen_at: new Date().toISOString(),
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      };
+
+      jest.spyOn(client, 'request').mockResolvedValue({ data: mockResponse });
+
+      const result = await devices.register({
+        deviceId: 'skyline-001',
+        deviceType: 'mmwave_radar',
+        firmwareVersion: '1.0.0',
+      });
+
+      expect(result.deviceId).toBe('skyline-001');
+      expect(result.deviceType).toBe('mmwave_radar');
+      expect(result.status).toBe('active');
+    });
+  });
+
+  describe('get', () => {
+    it('should retrieve device by ID', async () => {
+      const mockResponse = {
+        id: 'uuid-123',
+        device_id: 'skyline-001',
+        device_type: 'mmwave_radar',
+        firmware_version: '1.0.0',
+        status: 'active',
+        last_seen_at: new Date().toISOString(),
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      };
+
+      jest.spyOn(client, 'request').mockResolvedValue({ data: mockResponse });
+
+      const result = await devices.get('skyline-001');
+
+      expect(result.deviceId).toBe('skyline-001');
+    });
+  });
+
+  describe('list', () => {
+    it('should list all devices', async () => {
+      const mockResponse = [
+        {
+          id: 'uuid-1',
+          device_id: 'skyline-001',
+          device_type: 'mmwave_radar',
+          firmware_version: '1.0.0',
+          status: 'active',
+          last_seen_at: new Date().toISOString(),
+          created_at: new Date().toISOString(),
+          updated_at: new Date().toISOString(),
+        },
+      ];
+
+      jest.spyOn(client, 'request').mockResolvedValue({ data: mockResponse });
+
+      const results = await devices.list();
+
+      expect(results).toHaveLength(1);
+      expect(results[0].deviceId).toBe('skyline-001');
+    });
+  });
+});

package/sdks/client.ts

@@ -0,0 +1,198 @@
+import {
+  ClientConfig,
+  RequestOptions,
+  APIResponse,
+  APIError,
+  MQTTConfig,
+} from './types';
+
+import {
+  SensorDevicesAPI,
+  SensorReadingsAPI,
+  SensorAlertsAPI,
+  MQTTClient,
+} from './sensors';
+
+/**
+ * LeafEngines SDK Client v2.0
+ * 
+ * Main entry point for all API interactions
+ * 
+ * @example
+ * ```typescript
+ * import { LeafEnginesClient } from '@leafengines/sdk';
+ * 
+ * const client = new LeafEnginesClient({
+ *   apiKey: 'sk_live_xxx',
+ *   projectRef: 'wzgnxkoeqzvueypwzvyn',
+ * });
+ * 
+ * // Register a sensor device
+ * const device = await client.sensors.devices.register({
+ *   deviceId: 'skyline-001',
+ *   deviceType: 'mmwave_radar',
+ *   firmwareVersion: '1.0.0',
+ * });
+ * 
+ * // Query readings
+ * const readings = await client.sensors.readings.query({
+ *   deviceId: 'skyline-001',
+ *   startTime: new Date('2026-02-01'),
+ *   endTime: new Date(),
+ * });
+ * ```
+ */
+export class LeafEnginesClient {
+  private config: ClientConfig;
+  private baseUrl: string;
+
+  /**
+   * Sensor APIs (NEW in v2.0)
+   */
+  public sensors: {
+    devices: SensorDevicesAPI;
+    readings: SensorReadingsAPI;
+    alerts: SensorAlertsAPI;
+  };
+
+  /**
+   * MQTT Client (optional, for direct broker access)
+   */
+  public mqtt: MQTTClient | null = null;
+
+  constructor(config: ClientConfig) {
+    this.config = {
+      environment: 'production',
+      timeout: 30000,
+      ...config,
+    };
+
+    this.baseUrl = config.baseUrl || `https://${config.projectRef}.supabase.co/functions/v1`;
+
+    // Initialize sensor APIs
+    this.sensors = {
+      devices: new SensorDevicesAPI(this),
+      readings: new SensorReadingsAPI(this),
+      alerts: new SensorAlertsAPI(this),
+    };
+  }
+
+  /**
+   * Connect to MQTT broker for high-frequency data publishing
+   * 
+   * @param config - MQTT connection configuration
+   * @example
+   * ```typescript
+   * await client.connectMQTT({
+   *   host: 'xxx.s1.eu.hivemq.cloud',
+   *   port: 8883,
+   *   protocol: 'mqtts',
+   *   username: 'your-username',
+   *   password: 'your-password',
+   * });
+   * 
+   * // Publish directly to MQTT
+   * client.mqtt!.publish('skyline/device-001/readings', {
+   *   device_id: 'device-001',
+   *   readings: [{ metric: 'reflectivity', value: 0.92 }],
+   * });
+   * ```
+   */
+  async connectMQTT(config: MQTTConfig): Promise<void> {
+    this.mqtt = new MQTTClient(config);
+    await this.mqtt.connect();
+  }
+
+  /**
+   * Disconnect from MQTT broker
+   */
+  disconnectMQTT(): void {
+    if (this.mqtt) {
+      this.mqtt.disconnect();
+      this.mqtt = null;
+    }
+  }
+
+  /**
+   * Internal request method
+   * Not intended for direct use - used by API classes
+   */
+  async request<T>(options: RequestOptions): Promise<T> {
+    const url = new URL(options.endpoint, this.baseUrl);
+
+    // Add query params
+    if (options.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    // Prepare headers
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.config.apiKey}`,
+      ...options.headers,
+    };
+
+    // Make request
+    const response = await fetch(url.toString(), {
+      method: options.method,
+      headers,
+      body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+
+    // Handle errors
+    if (!response.ok) {
+      const error = await this.parseError(response);
+      throw new LeafEnginesError(error);
+    }
+
+    // Parse response
+    const data = await response.json();
+    return data as T;
+  }
+
+  /**
+   * Get WebSocket URL for real-time subscriptions
+   */
+  getWebSocketUrl(): string {
+    return `wss://${this.config.projectRef}.supabase.co/realtime/v1`;
+  }
+
+  private async parseError(response: Response): Promise<APIError> {
+    try {
+      const data = await response.json();
+      return {
+        code: data.code || `HTTP_${response.status}`,
+        message: data.message || response.statusText,
+        details: data.details,
+      };
+    } catch {
+      return {
+        code: `HTTP_${response.status}`,
+        message: response.statusText,
+      };
+    }
+  }
+}
+
+/**
+ * Custom error class for LeafEngines API errors
+ */
+export class LeafEnginesError extends Error {
+  code: string;
+  details?: Record<string, any>;
+
+  constructor(error: APIError) {
+    super(error.message);
+    this.name = 'LeafEnginesError';
+    this.code = error.code;
+    this.details = error.details;
+  }
+}
+
+// Re-export types for convenience
+export * from './types';
+export * from './sensors';

package/sdks/dist/client.d.ts

@@ -0,0 +1,94 @@
+import { ClientConfig, RequestOptions, APIError, MQTTConfig } from './types';
+import { SensorDevicesAPI, SensorReadingsAPI, SensorAlertsAPI, MQTTClient } from './sensors';
+/**
+ * LeafEngines SDK Client v2.0
+ *
+ * Main entry point for all API interactions
+ *
+ * @example
+ * ```typescript
+ * import { LeafEnginesClient } from '@leafengines/sdk';
+ *
+ * const client = new LeafEnginesClient({
+ *   apiKey: 'sk_live_xxx',
+ *   projectRef: 'wzgnxkoeqzvueypwzvyn',
+ * });
+ *
+ * // Register a sensor device
+ * const device = await client.sensors.devices.register({
+ *   deviceId: 'skyline-001',
+ *   deviceType: 'mmwave_radar',
+ *   firmwareVersion: '1.0.0',
+ * });
+ *
+ * // Query readings
+ * const readings = await client.sensors.readings.query({
+ *   deviceId: 'skyline-001',
+ *   startTime: new Date('2026-02-01'),
+ *   endTime: new Date(),
+ * });
+ * ```
+ */
+export declare class LeafEnginesClient {
+    private config;
+    private baseUrl;
+    /**
+     * Sensor APIs (NEW in v2.0)
+     */
+    sensors: {
+        devices: SensorDevicesAPI;
+        readings: SensorReadingsAPI;
+        alerts: SensorAlertsAPI;
+    };
+    /**
+     * MQTT Client (optional, for direct broker access)
+     */
+    mqtt: MQTTClient | null;
+    constructor(config: ClientConfig);
+    /**
+     * Connect to MQTT broker for high-frequency data publishing
+     *
+     * @param config - MQTT connection configuration
+     * @example
+     * ```typescript
+     * await client.connectMQTT({
+     *   host: 'xxx.s1.eu.hivemq.cloud',
+     *   port: 8883,
+     *   protocol: 'mqtts',
+     *   username: 'your-username',
+     *   password: 'your-password',
+     * });
+     *
+     * // Publish directly to MQTT
+     * client.mqtt!.publish('skyline/device-001/readings', {
+     *   device_id: 'device-001',
+     *   readings: [{ metric: 'reflectivity', value: 0.92 }],
+     * });
+     * ```
+     */
+    connectMQTT(config: MQTTConfig): Promise<void>;
+    /**
+     * Disconnect from MQTT broker
+     */
+    disconnectMQTT(): void;
+    /**
+     * Internal request method
+     * Not intended for direct use - used by API classes
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Get WebSocket URL for real-time subscriptions
+     */
+    getWebSocketUrl(): string;
+    private parseError;
+}
+/**
+ * Custom error class for LeafEngines API errors
+ */
+export declare class LeafEnginesError extends Error {
+    code: string;
+    details?: Record<string, any>;
+    constructor(error: APIError);
+}
+export * from './types';
+export * from './sensors';