dt-common-device 13.10.5 → 13.10.7

package/README.md

@@ -1,452 +1,452 @@
-# dt-common-device
-
-A comprehensive TypeScript library for device management, supporting both cloud and local device operations with advanced event handling, queue management, and audit logging.
-
-## Installation
-
-```sh
-npm install dt-common-device
-```
-
-## Environment Variables Required
-
-**The following environment variables are REQUIRED for the library to function:**
-
-### 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
-
-- `ADMIN_DB_URI` — PostgreSQL database connection URI
-- `MONGODB_URI` — MongoDB database connection URI
-
-### Redis Configuration
-
-- `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
-
-### SQS Configuration
-
-- `SQS_QUEUE_URL` — AWS SQS queue URL (configured during initialization)
-
-Example `.env` file:
-
-```
-# 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 clear errors if any required environment variables are missing.
-
----
-
-## Initialization (Required)
-
-Before using any service, you **must** call `initialize()` in your main entry file with the required configuration:
-
-```ts
-import { initialize } from "dt-common-device";
-
-// 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,
-});
-```
-
-### 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
-
----
-
-## Available Services
-
-### Local Device Service
-
-```ts
-import { LocalDeviceService } from "dt-common-device";
-
-const deviceService = new LocalDeviceService();
-
-// Create a device
-const device = await deviceService.createDevice(deviceBody);
-
-// 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,
-  "heartbeat",
-  "Device went offline due to network connectivity issues"
-);
-
-// Battery management
-const battery = await deviceService.getBatteryLevel(deviceId);
-await deviceService.setBatteryLevel(deviceId, batteryLevel, "heartbeat");
-
-// 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 { 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);
-
-// Delete a hub
-await hubService.deleteHub(hubId);
-
-// Delete multiple hubs
-await hubService.deleteAllHubs(hubIds);
-```
-
-### Local Schedule Service
-
-```ts
-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";
-
-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, DeviceFactory } from "dt-common-device";
-
-const cloudService = new CloudDeviceService();
-const deviceFactory = new DeviceFactory();
-
-// Get cloud devices (must implement in your project)
-// await cloudService.getDevices(connection);
-
-// Get device using factory
-const device = await deviceFactory.getDevice(deviceId);
-```
-
-### Property Service
-
-```ts
-import { PropertyService } from "dt-common-device";
-
-const propertyService = new PropertyService();
-
-// Property operations (implementation specific)
-// await propertyService.getProperty(propertyId);
-```
-
----
-
-## Event System
-
-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();
-```
-
----
-
-## Queue System
-
-The library provides a hybrid HTTP queue system for managing HTTP requests:
-
-```ts
-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",
-  },
-});
-```
-
-### Features
-
-- **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
-
----
-
-## Alert and Issue Management
-
-```ts
-import {
-  AlertService,
-  IssueService,
-  AlertBuilder,
-  IssueBuilder,
-} from "dt-common-device";
-
-// 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();
-```
-
----
-
-## Graceful Shutdown
-
-```ts
-import { shutdown } from "dt-common-device";
-
-// Gracefully shutdown the library
-await shutdown();
-```
-
----
-
-## Importing Types and Interfaces
-
-All types and interfaces are available as named exports:
-
-```ts
-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
+# dt-common-device
+
+A comprehensive TypeScript library for device management, supporting both cloud and local device operations with advanced event handling, queue management, and audit logging.
+
+## Installation
+
+```sh
+npm install dt-common-device
+```
+
+## Environment Variables Required
+
+**The following environment variables are REQUIRED for the library to function:**
+
+### 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
+
+- `ADMIN_DB_URI` — PostgreSQL database connection URI
+- `MONGODB_URI` — MongoDB database connection URI
+
+### Redis Configuration
+
+- `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
+
+### SQS Configuration
+
+- `SQS_QUEUE_URL` — AWS SQS queue URL (configured during initialization)
+
+Example `.env` file:
+
+```
+# 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 clear errors if any required environment variables are missing.
+
+---
+
+## Initialization (Required)
+
+Before using any service, you **must** call `initialize()` in your main entry file with the required configuration:
+
+```ts
+import { initialize } from "dt-common-device";
+
+// 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,
+});
+```
+
+### 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
+
+---
+
+## Available Services
+
+### Local Device Service
+
+```ts
+import { LocalDeviceService } from "dt-common-device";
+
+const deviceService = new LocalDeviceService();
+
+// Create a device
+const device = await deviceService.createDevice(deviceBody);
+
+// 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,
+  "heartbeat",
+  "Device went offline due to network connectivity issues"
+);
+
+// Battery management
+const battery = await deviceService.getBatteryLevel(deviceId);
+await deviceService.setBatteryLevel(deviceId, batteryLevel, "heartbeat");
+
+// 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 { 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);
+
+// Delete a hub
+await hubService.deleteHub(hubId);
+
+// Delete multiple hubs
+await hubService.deleteAllHubs(hubIds);
+```
+
+### Local Schedule Service
+
+```ts
+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";
+
+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, DeviceFactory } from "dt-common-device";
+
+const cloudService = new CloudDeviceService();
+const deviceFactory = new DeviceFactory();
+
+// Get cloud devices (must implement in your project)
+// await cloudService.getDevices(connection);
+
+// Get device using factory
+const device = await deviceFactory.getDevice(deviceId);
+```
+
+### Property Service
+
+```ts
+import { PropertyService } from "dt-common-device";
+
+const propertyService = new PropertyService();
+
+// Property operations (implementation specific)
+// await propertyService.getProperty(propertyId);
+```
+
+---
+
+## Event System
+
+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();
+```
+
+---
+
+## Queue System
+
+The library provides a hybrid HTTP queue system for managing HTTP requests:
+
+```ts
+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",
+  },
+});
+```
+
+### Features
+
+- **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
+
+---
+
+## Alert and Issue Management
+
+```ts
+import {
+  AlertService,
+  IssueService,
+  AlertBuilder,
+  IssueBuilder,
+} from "dt-common-device";
+
+// 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();
+```
+
+---
+
+## Graceful Shutdown
+
+```ts
+import { shutdown } from "dt-common-device";
+
+// Gracefully shutdown the library
+await shutdown();
+```
+
+---
+
+## Importing Types and Interfaces
+
+All types and interfaces are available as named exports:
+
+```ts
+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/audit/IAuditProperties.d.ts

@@ -46,3 +46,8 @@ export interface IAuditProperties {
     eventData?: any;
     [key: string]: any;
 }
+export type PartialAuditProperties = Omit<IAuditProperties, "resource" | "source" | "propertyId"> & {
+    resource?: Resource;
+    source?: Source;
+    propertyId?: string;
+};

package/dist/audit/PushAudit.d.ts

@@ -1,10 +1,21 @@
-import { IAuditProperties } from "./IAuditProperties";
+import { IAuditProperties, PartialAuditProperties } from "./IAuditProperties";
 /**
  * Publishes an audit event. Failures are logged and swallowed so callers can
  * fire-and-forget without causing unhandled promise rejections when the audit
  * pipeline returns 5xx or times out (see e.g. Sentry DT-PMS-C).
+ * USE FOR PROPERTY LEVEL AUDITS
  */
 export declare function pushAudit(data: {
     auditType: string;
     auditData: IAuditProperties;
 }): Promise<void>;
+/**
+ * Publishes an audit event. Failures are logged and swallowed so callers can
+ * fire-and-forget without causing unhandled promise rejections when the audit
+ * pipeline returns 5xx or times out (see e.g. Sentry DT-PMS-C).
+ * USE FOR SYSTEM LEVEL AUDITS (If Property ID is not available)
+ */
+export declare function pushSystemAudit(data: {
+    auditType: string;
+    auditData: PartialAuditProperties;
+}): Promise<void>;

package/dist/audit/PushAudit.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pushAudit = pushAudit;
+exports.pushSystemAudit = pushSystemAudit;
 const dt_audit_library_1 = require("dt-audit-library");
 const config_1 = require("../config/config");
 const AuditUtils_1 = require("./AuditUtils");
@@ -12,6 +13,7 @@ const typedi_1 = __importDefault(require("typedi"));
  * Publishes an audit event. Failures are logged and swallowed so callers can
  * fire-and-forget without causing unhandled promise rejections when the audit
  * pipeline returns 5xx or times out (see e.g. Sentry DT-PMS-C).
+ * USE FOR PROPERTY LEVEL AUDITS
  */
 async function pushAudit(data) {
     try {
@@ -33,3 +35,28 @@ async function pushAudit(data) {
             : { auditType: data.auditType });
     }
 }
+/**
+ * Publishes an audit event. Failures are logged and swallowed so callers can
+ * fire-and-forget without causing unhandled promise rejections when the audit
+ * pipeline returns 5xx or times out (see e.g. Sentry DT-PMS-C).
+ * USE FOR SYSTEM LEVEL AUDITS (If Property ID is not available)
+ */
+async function pushSystemAudit(data) {
+    try {
+        await (0, dt_audit_library_1.publishAudit)({
+            eventType: data.auditType,
+            properties: {
+                ...data.auditData,
+                timestamp: new Date().toISOString(),
+                env_type: process.env.NODE_ENV,
+            },
+        });
+    }
+    catch (err) {
+        const status = err?.response?.status;
+        const code = err?.code;
+        (0, config_1.getLogger)().error(`pushSystemAudit failed for ${data.auditType}: ${err?.message ?? err}`, status != null || code != null
+            ? { auditType: data.auditType, status, code }
+            : { auditType: data.auditType });
+    }
+}

package/dist/constants/ConnectionProviders.d.ts

@@ -24,4 +24,5 @@ export declare const CONNECTION_PROVIDERS: {
     readonly TWILIO: "Twilio";
     readonly DAIKIN: "Daikin";
     readonly HONEYWELL: "HoneyWell";
+    readonly ULTRALOCK: "UltraLock";
 };

package/dist/constants/ConnectionProviders.js

@@ -30,4 +30,5 @@ exports.CONNECTION_PROVIDERS = {
     TWILIO: "Twilio",
     DAIKIN: "Daikin",
     HONEYWELL: "HoneyWell",
+    ULTRALOCK: "UltraLock",
 };

package/dist/entities/admin/Admin.repository.js

@@ -99,19 +99,19 @@ let AdminRepository = (() => {
                 return [];
             }
             // If not cached, get the result from the database
-            const result = await this.postgres.query(`SELECT 
-        "zc"."id" AS "zoneCollectionMapId",
-        "zc"."collectionId",
-        "zc"."zoneId",
-        "z"."id" AS "zoneId",
-        "z"."name" AS "zoneName",
-        "z"."zoneTypeId",
-        "zt"."name" AS "zoneTypeName",
-        "z"."isUnderMaintenance"
-      FROM "dt_zones_collection_map" AS "zc"
-      INNER JOIN "dt_zones" AS "z" ON "zc"."zoneId" = "z"."id"
-      LEFT JOIN "dt_zoneTypes" AS "zt" ON "z"."zoneTypeId" = "zt"."id"
-      WHERE "zc"."collectionId" = ANY($1)
+            const result = await this.postgres.query(`SELECT 
+        "zc"."id" AS "zoneCollectionMapId",
+        "zc"."collectionId",
+        "zc"."zoneId",
+        "z"."id" AS "zoneId",
+        "z"."name" AS "zoneName",
+        "z"."zoneTypeId",
+        "zt"."name" AS "zoneTypeName",
+        "z"."isUnderMaintenance"
+      FROM "dt_zones_collection_map" AS "zc"
+      INNER JOIN "dt_zones" AS "z" ON "zc"."zoneId" = "z"."id"
+      LEFT JOIN "dt_zoneTypes" AS "zt" ON "z"."zoneTypeId" = "zt"."id"
+      WHERE "zc"."collectionId" = ANY($1)
       ORDER BY "zc"."id" ASC`, [accessGroupIds]);
             const response = result.rows;
             const _zones = (nestedZones, allZones = []) => {
@@ -280,10 +280,10 @@ let AdminRepository = (() => {
         }
         async getZonesByAccessGroups(accessGroupIds, type) {
             // Fetch zone IDs associated with these access groups
-            const zonesIdsQuery = `
-    SELECT DISTINCT z."zoneId"
-    FROM dt_zones_collection_map z
-    WHERE z."collectionId" = ANY($1)
+            const zonesIdsQuery = `
+    SELECT DISTINCT z."zoneId"
+    FROM dt_zones_collection_map z
+    WHERE z."collectionId" = ANY($1)
   `;
             const zonesIdsResult = await this.postgres.query(zonesIdsQuery, [
                 accessGroupIds,
@@ -296,20 +296,20 @@ let AdminRepository = (() => {
             const zoneTypesToFilter = type || ["Guest Room", "Room"];
             // Fetch zone type IDs for the specified type
             // Using IN with unnest() for better compatibility with string arrays
-            const zoneTypesQuery = `
-    SELECT id
-    FROM "dt_zoneTypes"
-    WHERE name IN (SELECT unnest($1::text[]))
+            const zoneTypesQuery = `
+    SELECT id
+    FROM "dt_zoneTypes"
+    WHERE name IN (SELECT unnest($1::text[]))
   `;
             const zoneTypes = await this.postgres.query(zoneTypesQuery, [
                 zoneTypesToFilter,
             ]);
             const guestRoomZoneTypeIds = zoneTypes.rows.map((e) => e.id);
             // Fetch zones matching both sets of IDs
-            const zonesQuery = `
-    SELECT id
-    FROM dt_zones
-    WHERE id = ANY($1) AND "zoneTypeId" = ANY($2)
+            const zonesQuery = `
+    SELECT id
+    FROM dt_zones
+    WHERE id = ANY($1) AND "zoneTypeId" = ANY($2)
   `;
             const zonesResult = await this.postgres.query(zonesQuery, [
                 zonesIds,
@@ -320,15 +320,15 @@ let AdminRepository = (() => {
         async getAccessGroup(accessGroupId, propertyId) {
             let query;
             if (propertyId) {
-                query = `
-      SELECT * FROM dt_collections
-      WHERE "id" = $1 AND "propertyId" = $2
+                query = `
+      SELECT * FROM dt_collections
+      WHERE "id" = $1 AND "propertyId" = $2
       `;
             }
             else {
-                query = `
-      SELECT * FROM dt_collections
-      WHERE "id" = $1
+                query = `
+      SELECT * FROM dt_collections
+      WHERE "id" = $1
       `;
             }
             const params = propertyId ? [accessGroupId, propertyId] : [accessGroupId];
@@ -339,9 +339,9 @@ let AdminRepository = (() => {
             return null;
         }
         async getZoneAccessGroupByZoneId(zoneId) {
-            const query = `
-      SELECT * FROM dt_zones_collection_map
-      WHERE "zoneId" = $1
+            const query = `
+      SELECT * FROM dt_zones_collection_map
+      WHERE "zoneId" = $1
     `;
             const result = await this.postgres.query(query, [zoneId]);
             if (result.rows.length > 0) {
@@ -353,10 +353,10 @@ let AdminRepository = (() => {
             if (accessGroupIds.length === 0) {
                 return [];
             }
-            const query = `
-      SELECT DISTINCT "zoneId"
-      FROM dt_zones_collection_map
-      WHERE "collectionId" = ANY($1)
+            const query = `
+      SELECT DISTINCT "zoneId"
+      FROM dt_zones_collection_map
+      WHERE "collectionId" = ANY($1)
     `;
             const result = await this.postgres.query(query, [accessGroupIds]);
             return result.rows.map((row) => row.zoneId);
@@ -446,12 +446,12 @@ let AdminRepository = (() => {
             return [];
         }
         async getAccessGroupsByZoneId(zoneId) {
-            const query = `
-      SELECT DISTINCT c.*
-      FROM dt_collections c
-      INNER JOIN dt_zones_collection_map zcm ON c.id = zcm."collectionId"
-      WHERE zcm."zoneId" = $1
-      AND c."isDeleted" = false
+            const query = `
+      SELECT DISTINCT c.*
+      FROM dt_collections c
+      INNER JOIN dt_zones_collection_map zcm ON c.id = zcm."collectionId"
+      WHERE zcm."zoneId" = $1
+      AND c."isDeleted" = false
     `;
             const result = await this.postgres.query(query, [zoneId]);
             return result.rows;
@@ -461,12 +461,12 @@ let AdminRepository = (() => {
                 return [];
             }
             // Get all access groups associated with any of these zones
-            const query = `
-      SELECT DISTINCT c.*
-      FROM dt_collections c
-      INNER JOIN dt_zones_collection_map zcm ON c.id = zcm."collectionId"
-      WHERE zcm."zoneId" = ANY($1)
-      AND c."isDeleted" = false
+            const query = `
+      SELECT DISTINCT c.*
+      FROM dt_collections c
+      INNER JOIN dt_zones_collection_map zcm ON c.id = zcm."collectionId"
+      WHERE zcm."zoneId" = ANY($1)
+      AND c."isDeleted" = false
     `;
             const result = await this.postgres.query(query, [zoneIds]);
             return result.rows;

package/dist/entities/connection/Connection.repository.js

@@ -124,9 +124,9 @@ let ConnectionRepository = (() => {
                 .map((key, index) => `"${key}" = $${index + 3}`)
                 .join(", ");
             const values = Object.values(data);
-            const result = await this.pool.query(`UPDATE dt_connections
-     SET ${setClause}, "updatedAt" = NOW()
-     WHERE id = $1 AND "propertyId" = $2
+            const result = await this.pool.query(`UPDATE dt_connections
+     SET ${setClause}, "updatedAt" = NOW()
+     WHERE id = $1 AND "propertyId" = $2
      RETURNING *`, [connectionId, propertyId, ...values]);
             if (result.rowCount === 0) {
                 return null;

package/dist/entities/device/local/repository/Device.repository.js

@@ -235,8 +235,8 @@ let DeviceRepository = (() => {
         }
         async getDevicesByAccessGroup(accessGroupId) {
             try {
-                const result = await this.postgres.query(`SELECT d.* FROM dt_devices d
-         INNER JOIN dt_zones_collection_map zcm ON d.zoneId = zcm.zoneId
+                const result = await this.postgres.query(`SELECT d.* FROM dt_devices d
+         INNER JOIN dt_zones_collection_map zcm ON d.zoneId = zcm.zoneId
          WHERE zcm.collectionId = $1`, [accessGroupId]);
                 if (result.rows.length > 0) {
                     return result.rows;

package/dist/queue/utils/queueUtils.js

@@ -35,6 +35,8 @@ class QueueUtils {
                 console.log(`[${new Date().toISOString()}] [getOrCreateWorker] Existing worker running status: ${isRunning}`);
                 if (!isRunning) {
                     console.log(`[${new Date().toISOString()}] [getOrCreateWorker] Worker not running, closing and recreating...`);
+                    // Stale worker detected — surface at WARN level with count context
+                    (0, config_1.getConfig)().LOGGER.warn(`Stale worker for queue ${queueKey} (not running), recreating. Active workers before recreate: ${workers.size}`);
                     try {
                         existingWorker.close();
                     }
@@ -116,7 +118,8 @@ class QueueUtils {
         });
         workers.set(queueKey, worker);
         console.log(`[${new Date().toISOString()}] [getOrCreateWorker] Worker initialized and stored for queue: ${queueKey}`);
-        (0, config_1.getConfig)().LOGGER.info(`Worker initialized for queue: ${queueKey}`);
+        // Log total active workers — a growing count here signals a connection-proliferation leak
+        (0, config_1.getConfig)().LOGGER.info(`Worker initialized for queue: ${queueKey} (total active workers: ${workers.size})`);
     }
     static async waitForRateLimitExpiry(connectionId, provider, rateLimitConfigs) {
         const key = `rate_limit:${provider}:${connectionId}`;
@@ -202,6 +205,10 @@ class QueueUtils {
                 queue.getActiveCount(),
             ]);
             console.log(`[${new Date().toISOString()}] [addJobToQueue] Queue state - QueueKey: ${queueKey}, Waiting: ${waiting}, Delayed: ${delayed}, Active: ${active}`);
+            // Warn via structured logger when backlog is building — correlates with heap stats
+            if (waiting + delayed > 1) {
+                (0, config_1.getConfig)().LOGGER.warn(`Queue backlog [${queueKey}]: waiting=${waiting} delayed=${delayed} active=${active}`);
+            }
         }
         catch (e) {
             // Ignore errors getting queue state
@@ -250,6 +257,9 @@ class QueueUtils {
             // Timeout
             setTimeout(() => {
                 clearInterval(checkInterval);
+                // Log via structured logger before rejecting so the timeout is visible in
+                // CloudWatch alongside the periodic heap stats — correlates queue stalls with memory pressure.
+                (0, config_1.getConfig)().LOGGER.error(`Job ${jobId} timed out after ${totalTimeout}ms [${queueKey}] (jobDelay=${jobDelay}ms)`);
                 reject(new Error(`Request timeout: Maximum wait time exceeded (${totalTimeout}ms). Job delay was ${jobDelay}ms.`));
             }, totalTimeout);
         });

package/dist/queue/utils/rateLimit.utils.js

@@ -147,6 +147,12 @@ class RateLimitUtils {
             provider: constants_1.CONNECTION_PROVIDERS.DUSAW,
             maxTimeoutWindowMs: 120000,
         });
+        configs.set(constants_1.CONNECTION_PROVIDERS.ULTRALOCK, {
+            maxRequests: 60,
+            windowMs: 60000, // 1 minute — adjust once UltraLock API docs confirm their limit
+            provider: constants_1.CONNECTION_PROVIDERS.ULTRALOCK,
+            maxTimeoutWindowMs: 120000,
+        });
         return configs;
     }
     static async isRateLimitAllowed(connectionId, provider, rateLimitConfigs) {

package/dist/webhooks/webhook.repository.js

@@ -51,8 +51,8 @@ let WebHookRepository = (() => {
             this.postgres = (0, db_1.getWebhookPostgresClient)();
         }
         async getWebhookAppByUid(uid) {
-            const query = `
-      SELECT * FROM application WHERE uid = $1
+            const query = `
+      SELECT * FROM application WHERE uid = $1
     `;
             const result = await this.postgres.query(query, [uid]);
             if (result.rows.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dt-common-device",
-  "version": "13.10.5",
+  "version": "13.10.7",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [