dt-common-device 2.0.7 → 3.0.1

package/README.md

@@ -1,6 +1,6 @@
 # dt-common-device
 
-A TypeScript library for device management, supporting both cloud and local device operations.
+A comprehensive TypeScript library for device management, supporting both cloud and local device operations with advanced event handling, queue management, and audit logging.
 
 ## Installation
 
@@ -10,168 +10,350 @@ npm install dt-common-device
 
 ## Environment Variables Required
 
-**For audit logging to work (used in local device services), you must set the following environment variables in your application:**
+**The following environment variables are REQUIRED for the library to function:**
 
-- `POSTHOG_API_KEY` — Your PostHog API key
-- `POSTHOG_HOST` — The PostHog host URL
+### AWS Configuration
+
+- `AWS_SECRET_ACCESS_KEY` — Your AWS secret access key
+- `AWS_REGION` — Your AWS region
+- `AWS_ACCESS_KEY_ID` — Your AWS access key ID
+- `EVENT_BUS_NAME` — Your AWS EventBridge event bus name
+
+### Database Configuration
 
-**You do NOT need to call `initializeAudit()` yourself.**
+- `ADMIN_DB_URI` — PostgreSQL database connection URI
+- `MONGODB_URI` — MongoDB database connection URI
 
-- `dt-common-device` will automatically initialize audit logging using these environment variables when you create a local device service.
-- If either variable is missing, the library will throw a clear error at runtime.
+### Redis Configuration
 
-## Environment Variables
+- `REDIS_HOST` — Redis server host
+- `REDIS_PORT` — Redis server port
+
+### Audit Logging
+
+- `POSTHOG_API_KEY` — Your PostHog API key
+- `POSTHOG_HOST` — The PostHog host URL
 
-This library requires the following environment variable to be set in your project's environment or in a `.env` file:
+### SQS Configuration
 
-- `POSTGRESQL_DB_URI`: The connection URI for your PostgreSQL database.
+- `SQS_QUEUE_URL` — AWS SQS queue URL (configured during initialization)
 
 Example `.env` file:
 
 ```
-POSTGRESQL_DB_URI=postgres://username:password@host:port/database
+# AWS Configuration
+AWS_SECRET_ACCESS_KEY=your_secret_key
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your_access_key
+EVENT_BUS_NAME=your-event-bus
+
+# Database Configuration
+ADMIN_DB_URI=postgres://username:password@host:port/database
+MONGODB_URI=mongodb://username:password@host:port/database
+
+# Redis Configuration
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# Audit Logging
+POSTHOG_API_KEY=your_posthog_key
+POSTHOG_HOST=https://app.posthog.com
+
+# SQS Configuration (will be set during initialization)
+SQS_QUEUE_URL=https://sqs.region.amazonaws.com/account/queue-name
 ```
 
-The library will throw an error if this variable is not set when attempting to connect to the database.
+The library will throw clear errors if any required environment variables are missing.
 
 ---
 
 ## Initialization (Required)
 
-Before using any service, you **must** call `initialize()` in your main entry file:
+Before using any service, you **must** call `initialize()` in your main entry file with the required configuration:
 
 ```ts
 import { initialize } from "dt-common-device";
 
-initialize({
-  DEVICE_SERVICE: "https://api.example.com/device",
-  ADMIN_SERVICE: "https://api.example.com/admin",
-  OPERATIONAL_SERVICE: "https://api.example.com/ops",
-  MONITORING_SERVICE: "https://api.example.com/monitor",
-  // ...other config as needed
+// Create a logger instance
+const logger = {
+  info: (message: string, ...args: any[]) => console.log(message, ...args),
+  warn: (message: string, ...args: any[]) => console.warn(message, ...args),
+  error: (message: string, ...args: any[]) => console.error(message, ...args),
+};
+
+// Initialize the library
+await initialize({
+  SOURCE: "ADMIN_SERVICE", // or "ACCESS_SERVICE" or "ENERGY_SERVICE"
+  SQS_QUEUE_URL: "https://sqs.region.amazonaws.com/account/queue-name",
+  DEVICE_SERVICE: "https://api.example.com/device", // Optional
+  ADMIN_SERVICE: "https://api.example.com/admin", // Optional
+  ACCESS_SERVICE: "https://api.example.com/access", // Optional
+  ENERGY_SERVICE: "https://api.example.com/energy", // Optional
+  INTERNAL_EVENT_HANDLER: {
+    // Your event handler implementation
+    handleEvent: async (event) => {
+      // Handle internal events
+      console.log("Handling event:", event);
+    },
+  },
+  LOGGER: logger,
 });
 ```
 
-At least one service URL must be provided.
+### Configuration Options
+
+- `SOURCE`: Required. Must be one of: `"ADMIN_SERVICE"`, `"ACCESS_SERVICE"`, or `"ENERGY_SERVICE"`
+- `SQS_QUEUE_URL`: Required. Your AWS SQS queue URL
+- `DEVICE_SERVICE`, `ADMIN_SERVICE`, `ACCESS_SERVICE`, `ENERGY_SERVICE`: Optional service URLs
+- `INTERNAL_EVENT_HANDLER`: Required. Your event handler implementation
+- `LOGGER`: Required. Logger instance with info, warn, and error methods
 
 ---
 
-## Implementing Abstract Classes (Cloud Connection Example)
+## Available Services
+
+### Local Device Service
+
+```ts
+import { LocalDeviceService } from "dt-common-device";
 
-This library provides abstract classes (such as `ConnectionService`) that define the required contract for cloud connection managers. **You should extend these abstract classes and implement all required methods.**
+const deviceService = new LocalDeviceService();
 
-**You do NOT need to instantiate your class unless you want to use it in your application logic.**
+// Create a device
+const device = await deviceService.createDevice(deviceBody);
 
-### Example: Implementing a Cloud Connection Service
+// Get a device
+const device = await deviceService.getDevice(deviceId);
+
+// Get multiple devices
+const devices = await deviceService.getDevices(deviceIds);
+
+// Get devices by property
+const propertyDevices = await deviceService.getPropertyDevices(propertyId);
+
+// Update a device
+await deviceService.updateDevice(deviceId, updateBody);
+
+// Delete a device
+await deviceService.deleteDevice(deviceId);
+
+// State management
+const state = await deviceService.getState(deviceId);
+await deviceService.setState(deviceId, newState);
+
+// Status management
+const status = await deviceService.getStatus(deviceId);
+await deviceService.setStatus(deviceId, newStatus);
+
+// Battery management
+const battery = await deviceService.getBatteryLevel(deviceId);
+await deviceService.setBatteryLevel(deviceId, batteryLevel);
+
+// Metadata management
+const metadata = await deviceService.getMetaData(deviceId);
+await deviceService.setMetaData(deviceId, metadata);
+
+// Query operations
+const devices = await deviceService.queryDevices(query);
+const count = await deviceService.queryCount(query);
+await deviceService.deleteDevices(query);
+```
+
+### Local Hub Service
 
 ```ts
-import {
-  ConnectionService,
-  IConnection,
-  IDevice,
-  IDeviceAccountResponse,
-  IConnectionConnectParams,
-} from "dt-common-device";
+import { LocalHubService } from "dt-common-device";
+
+const hubService = new LocalHubService();
+
+// Add a hub
+const hub = await hubService.addHub(hubBody);
+
+// Get hubs
+const hubs = await hubService.getHubs(hubIds);
+
+// Get a single hub
+const hub = await hubService.getHub(hubId);
+
+// Update a hub
+await hubService.updateHub(hubId, updateBody);
+
+// Get hub status
+const status = await hubService.getStatus(hubId);
 
-class MyConnectionService extends ConnectionService {
-  async createConnection(data: IConnection, userId: string): Promise<any> {
-    // Your implementation
-  }
-
-  async getDeviceAccount(
-    connection: IConnection
-  ): Promise<IDeviceAccountResponse> {
-    // Your implementation
-  }
-
-  async getDevices(connection: IConnection): Promise<IDevice[]> {
-    // Your implementation
-  }
-
-  async filterDevices(
-    connection: IConnection,
-    devices: Record<string, any>[]
-  ): Promise<IDevice[]> {
-    // Your implementation
-  }
-
-  async connect(
-    connection: IConnection,
-    connectionConnect: IConnectionConnectParams
-  ): Promise<any> {
-    // Your implementation
-  }
-}
-```
-
-- TypeScript will enforce that you implement all required methods.
-- If you miss any, you will get a compile-time error.
-- You only need to instantiate your class if you want to use it in your application logic:
+// Delete a hub
+await hubService.deleteHub(hubId);
+
+// Delete multiple hubs
+await hubService.deleteAllHubs(hubIds);
+```
+
+### Local Schedule Service
 
 ```ts
-const myService = new MyConnectionService();
-myService.createConnection(...);
+import { LocalScheduleService } from "dt-common-device";
+
+const scheduleService = new LocalScheduleService();
+
+// Get a schedule
+const schedule = await scheduleService.getSchedule(scheduleId);
+
+// Set a schedule
+await scheduleService.setSchedule(scheduleId, schedule);
+
+// Get schedule by zone
+const zoneSchedule = await scheduleService.getScheduleByZone(zoneId);
 ```
 
----
+### Local Connection Service
+
+```ts
+import { LocalConnectionService } from "dt-common-device";
 
-## Importing Services
+const connectionService = new LocalConnectionService();
+
+// Create a connection
+const connection = await connectionService.createConnection({
+  connectionName: "My Connection",
+  connectionRefId: "ref-123",
+  propertyId: "prop-456",
+  connectionProvider: "Sensibo",
+});
+
+// Get a connection
+const connection = await connectionService.getConnection(connectionId);
+
+// Update a connection
+await connectionService.updateConnection(connectionId, updateData);
+```
 
 ### Cloud Device Service
 
 ```ts
-import { CloudDeviceService } from "dt-common-device";
+import { CloudDeviceService, DeviceFactory } from "dt-common-device";
 
 const cloudService = new CloudDeviceService();
+const deviceFactory = new DeviceFactory();
 
-// Example: get devices (must implement in your project)
+// Get cloud devices (must implement in your project)
 // await cloudService.getDevices(connection);
+
+// Get device using factory
+const device = await deviceFactory.getDevice(deviceId);
 ```
 
-### Local Device Service
+### Property Service
 
 ```ts
-import { LocalDeviceService } from "dt-common-device";
+import { PropertyService } from "dt-common-device";
 
-const localService = new LocalDeviceService();
+const propertyService = new PropertyService();
 
-// Create a device
-await localService.createDevice(deviceBody);
+// Property operations (implementation specific)
+// await propertyService.getProperty(propertyId);
+```
 
-// Get a device
-const device = await localService.getDevice(deviceId);
+---
 
-// Update a device
-await localService.updateDevice(deviceId, updateBody);
+## Event System
 
-// Delete a device
-await localService.deleteDevice(deviceId);
+The library includes a comprehensive event handling system:
+
+```ts
+import {
+  EventHandler,
+  EventProcessingService,
+  DeviceEventHandler,
+  EventHandlerOrchestrator,
+} from "dt-common-device";
+
+// Event handler for device operations
+const eventHandler = new EventHandler();
+
+// Device-specific event handler
+const deviceEventHandler = new DeviceEventHandler();
+
+// Event processing service
+const eventProcessingService = new EventProcessingService();
+
+// Event handler orchestrator
+const orchestrator = new EventHandlerOrchestrator();
 ```
 
-### Local Device Hub Service
+---
+
+## Queue System
+
+The library provides a hybrid HTTP queue system for managing HTTP requests:
 
 ```ts
-import { LocalDeviceHubService } from "dt-common-device";
+import { QueueService } from "dt-common-device";
+
+const queueService = new QueueService();
+
+// Make a rate-limited HTTP request
+const response = await queueService.request({
+  method: "GET",
+  url: "https://api.example.com/data",
+  headers: { "Content-Type": "application/json" },
+  queueOptions: {
+    connectionId: "connection-123",
+    connectionProvider: "Sensibo",
+    microservice: "smart-energy",
+  },
+});
+```
 
-const deviceHubService = new LocalDeviceHubService();
+### Features
 
-// Add a hub
-await deviceHubService.addHub(hubBody);
+- **Rate Limiting**: Automatic rate limiting per provider and connection
+- **Retry Logic**: Exponential backoff with configurable retry attempts
+- **Audit Logging**: Automatic audit logging for all requests
+- **Queue Management**: Redis-based queue with BullMQ
+- **Error Handling**: Comprehensive error handling and logging
 
-// Get hubs
-const hubs = await deviceHubService.getHubs(hubIds);
+---
 
-// Get a single hub
-const hub = await deviceHubService.getHub(hubId);
+## Alert and Issue Management
 
-// Update a hub
-await deviceHubService.updateHub(hubId, updateBody);
+```ts
+import {
+  AlertService,
+  IssueService,
+  AlertBuilder,
+  IssueBuilder,
+} from "dt-common-device";
 
-// Delete a hub
-await deviceHubService.deleteHub(hubId);
+// Alert service
+const alertService = new AlertService();
+
+// Issue service
+const issueService = new IssueService();
+
+// Build alerts
+const alert = new AlertBuilder()
+  .setTitle("Device Offline")
+  .setDescription("Device has been offline for more than 24 hours")
+  .setSeverity("HIGH")
+  .build();
+
+// Build issues
+const issue = new IssueBuilder()
+  .setTitle("Connection Failed")
+  .setDescription("Failed to connect to device")
+  .setPriority("HIGH")
+  .build();
+```
 
-// Delete multiple hubs
-await deviceHubService.deleteAllHubs(hubIds);
+---
+
+## Graceful Shutdown
+
+```ts
+import { shutdown } from "dt-common-device";
+
+// Gracefully shutdown the library
+await shutdown();
 ```
 
 ---
@@ -181,13 +363,85 @@ await deviceHubService.deleteAllHubs(hubIds);
 All types and interfaces are available as named exports:
 
 ```ts
-import { IDevice, IHub, IConnection } from "dt-common-device";
+import {
+  IDevice,
+  IHub,
+  IConnection,
+  ISchedule,
+  IProperty,
+  IAlert,
+  IIssue,
+} from "dt-common-device";
 ```
 
 ---
 
+## Dependencies
+
+The library requires the following major dependencies:
+
+- `axios`: HTTP client
+- `bullmq`: Queue management
+- `dt-audit-library`: Audit logging
+- `dt-pub-sub`: Event publishing/subscribing
+- `ioredis`: Redis client
+- `mongoose`: MongoDB ODM
+- `pg`: PostgreSQL client
+- `typedi`: Dependency injection
+
+---
+
 ## Notes
 
 - You **must** call `initialize()` before using any service. If not, you will get a runtime error.
 - **You must set `POSTHOG_API_KEY` and `POSTHOG_HOST` in your environment before using any local device service.**
 - You do **not** need to call `initializeAudit()`
+
+## Rate Limiting
+
+The queue system now implements intelligent rate limiting that delays requests instead of dropping them when rate limits are exceeded.
+
+### How it works
+
+1. **Rate Limit Check**: Before processing each HTTP request, the system checks if the rate limit for the provider/connection combination has been exceeded.
+
+2. **Delay Instead of Drop**: If the rate limit is exceeded, instead of immediately failing the request, the system:
+
+   - Calculates when the next request can be processed (after the rate limit window expires)
+   - Delays the job execution by the calculated time
+   - Re-checks the rate limit after the delay
+   - Only fails if still rate limited after the delay
+
+3. **Example Scenario**:
+
+   ```
+   Rate Limit: 5 requests per 60 seconds
+
+   Timeline:
+   0s: Request 1 (processed immediately)
+   10s: Request 2 (processed immediately)
+   20s: Request 3 (processed immediately)
+   30s: Request 4 (processed immediately)
+   40s: Request 5 (processed immediately)
+   45s: Request 6 (delayed by 15s, processed at 60s)
+   50s: Request 7 (delayed by 10s, processed at 60s)
+   ```
+
+### Configuration
+
+Rate limits are configured per provider in `src/queue/utils/rateLimit.utils.ts`:
+
+```typescript
+configs.set("Sensibo", {
+  maxRequests: 5, // Maximum requests allowed
+  windowMs: 60000, // Time window in milliseconds
+  provider: "Sensibo",
+});
+```
+
+### Benefits
+
+- **No Lost Requests**: Requests are delayed rather than dropped
+- **Automatic Recovery**: System automatically processes delayed requests when rate limits reset
+- **Better User Experience**: Users don't see immediate failures due to rate limits
+- **Audit Trail**: All rate limit events are logged for monitoring

package/dist/alerts/Alert.model.d.ts

@@ -0,0 +1,28 @@
+import mongoose, { Model } from "mongoose";
+import { AlertCategory, AlertSeverity, EntityType, AlertDocument as IAlertDocument, CreateAlertData, UpdateAlertData } from "./alert.types";
+interface IAlertMethods {
+    markAsRead(updatedBy: string): void;
+    markAsUnread(updatedBy: string): void;
+    activate(updatedBy: string): void;
+    deactivate(updatedBy: string): void;
+    snooze(until: Date, updatedBy: string): void;
+    unsnooze(updatedBy: string): void;
+}
+interface IAlertModel extends Model<IAlertDocument, {}, IAlertMethods> {
+    findByProperty(propertyId: string, includeDeleted?: boolean): Promise<IAlertDocument[]>;
+    findByEntity(entityId: string, entityType: EntityType, includeDeleted?: boolean): Promise<IAlertDocument[]>;
+    findByCategory(category: AlertCategory, includeDeleted?: boolean): Promise<IAlertDocument[]>;
+    findBySeverity(severity: AlertSeverity, includeDeleted?: boolean): Promise<IAlertDocument[]>;
+    findActive(includeDeleted?: boolean): Promise<IAlertDocument[]>;
+    findUnread(includeDeleted?: boolean): Promise<IAlertDocument[]>;
+    findSnoozed(includeDeleted?: boolean): Promise<IAlertDocument[]>;
+    findExpiredSnooze(includeDeleted?: boolean): Promise<IAlertDocument[]>;
+}
+declare const AlertSchema: mongoose.Schema<IAlertDocument, IAlertModel, IAlertMethods, {}, {}, {}, mongoose.DefaultSchemaOptions, IAlertDocument, mongoose.Document<unknown, {}, mongoose.FlatRecord<IAlertDocument>, {}> & Omit<mongoose.FlatRecord<IAlertDocument> & Required<{
+    _id: string;
+}> & {
+    __v: number;
+}, keyof IAlertMethods> & IAlertMethods>;
+export declare const AlertModel: IAlertModel;
+export { AlertSchema };
+export type { IAlertDocument, CreateAlertData, UpdateAlertData, IAlertMethods, IAlertModel, };