dt-common-device 3.0.0 → 3.0.2

package/README.md

@@ -393,23 +393,55 @@ The library requires the following major dependencies:
 
 ## Notes
 
-- **You must call `initialize()` before using any service.** If not, you will get a runtime error.
-- **All required environment variables must be set** before initialization.
-- **The library automatically initializes audit logging** using the PostHog configuration.
-- **Database connections are established automatically** during initialization.
-- **Event subscriptions are managed automatically** if an event handler is provided.
-- **The library supports graceful shutdown** to clean up resources properly.
+- 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
 
-## Error Handling
+3. **Example Scenario**:
 
-The library provides comprehensive error handling:
+   ```
+   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",
+});
+```
 
-- **Initialization errors**: Clear messages for missing environment variables or invalid configuration
-- **Service errors**: Proper error handling for all service operations
-- **Database errors**: Connection and query error handling
-- **Queue errors**: Rate limiting and retry error handling
-- **Event errors**: Event processing error handling
+### Benefits
 
-All errors include detailed logging and appropriate error messages for debugging.
+- **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/device/cloud/interface.d.ts

@@ -0,0 +1,101 @@
+import { IConnection, IConnectionConnectParams, IDevice, IDeviceAccountResponse, IDeviceCommand, ISmartthingsDeviceCommand, ICommandResponse } from "./types";
+/**
+ * Class interface for device cloud operations and connection management
+ */
+export interface IDeviceCloudService {
+    /**
+     * Creates a new connection for device management
+     * @param data - Connection data
+     * @param userId - User identifier
+     * @returns Promise with connection result
+     */
+    createConnection(data: IConnection, userId: string): Promise<any>;
+    /**
+     * Gets device account information for a connection
+     * @param connection - Connection object
+     * @returns Promise with device account response
+     */
+    getDeviceAccount(connection: IConnection): Promise<IDeviceAccountResponse>;
+    /**
+     * Gets all devices for a connection
+     * @param connection - Connection object
+     * @returns Promise with array of devices
+     */
+    getDevices(connection: IConnection): Promise<IDevice[]>;
+    /**
+     * Filters devices based on connection and device list
+     * @param connection - Connection object
+     * @param devices - Array of devices to filter
+     * @returns Promise with filtered devices
+     */
+    filterDevices(connection: IConnection, devices: any[]): Promise<IDevice[]>;
+    /**
+     * Connects to a device service
+     * @param connection - Connection object
+     * @param connectionConnect - Connection parameters
+     * @returns Promise with connection result
+     */
+    connect(connection: IConnection, connectionConnect: IConnectionConnectParams): Promise<any>;
+}
+/**
+ * Interface for device command operations
+ */
+export interface IDeviceCommandManager {
+    /**
+     * Invokes a command on a device
+     * @param command - Device command to execute
+     * @param deviceId - Device identifier
+     * @returns Promise with command response
+     */
+    invokeCommand(command: IDeviceCommand, deviceId: string): Promise<ICommandResponse>;
+}
+/**
+ * Interface for SmartThings specific device command operations
+ */
+export interface ISmartthingsDeviceCommandManager extends IDeviceCommandManager {
+    /**
+     * Performs device action for SmartThings
+     * @param commands - Array of SmartThings device commands
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with action result
+     */
+    performDeviceAction(commands: ISmartthingsDeviceCommand[], deviceId: string, accessToken: string): Promise<any>;
+    /**
+     * Gets device status for SmartThings
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with device status
+     */
+    getDeviceStatus(deviceId: string, accessToken: string): Promise<any>;
+    /**
+     * Gets device lock status for SmartThings
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with lock status
+     */
+    getDeviceLockStatus(deviceId: string, accessToken: string): Promise<any>;
+}
+/**
+ * Interface for device command factory
+ */
+export interface IDeviceCommandManagerFactory {
+    /**
+     * Creates a device command manager for a specific connection provider
+     * @param connectionProvider - Connection provider type
+     * @param connection - Connection object
+     * @returns Device command manager instance
+     */
+    createDeviceCommandManager(connectionProvider: string, connection: IConnection): IDeviceCommandManager;
+}
+/**
+ * Interface for device command classes
+ */
+export interface IDeviceCommandClass {
+    /**
+     * Creates a SmartThings device command from a generic device command
+     * @param deviceCommand - Generic device command
+     * @returns SmartThings device command
+     */
+    fromDeviceCommand(deviceCommand: IDeviceCommand): ISmartthingsDeviceCommand;
+}

package/dist/device/cloud/interface.js

@@ -0,0 +1,3 @@
+"use strict";
+// Device Cloud Class Interface for DeviceThread Common Library
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/device/cloud/interfaces/IDeviceConnectionService.d.ts

@@ -0,0 +1,7 @@
+import { IConnection, IConnectionConnectParams, IDeviceAccountResponse } from "../types";
+export interface IDeviceConnectionService {
+    createConnection(data: IConnection, userId: string): Promise<any>;
+    getDeviceAccount(connection: IConnection): Promise<IDeviceAccountResponse>;
+    getDevices(connection: IConnection): Promise<any>;
+    connect(connection: IConnection, connectionConnect: IConnectionConnectParams): Promise<any>;
+}

package/dist/device/cloud/interfaces/IDeviceConnectionService.js

@@ -0,0 +1,3 @@
+"use strict";
+// Device Cloud Class Interface for DeviceThread Common Library
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/device/cloud/interfaces/IDevicesService.d.ts

@@ -0,0 +1,9 @@
+import { IConnection } from "../types";
+export interface IDeviceService {
+    getDevices(connection: IConnection): Promise<Record<string, any>[]>;
+    getDevice(connectionId: string, deviceId: string): Promise<Record<string, any>>;
+    getStatus(connectionId: string, deviceId: string): Promise<string | null>;
+    getState(deviceId: string): Promise<Record<string, any>>;
+    getGateways(connectionId: string): Promise<any[] | null>;
+    getGatewayDetails(connectionId: string, gatewayId: string): Promise<any>;
+}

package/dist/device/cloud/interfaces/IDevicesService.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/device/cloud/services/Device.service.d.ts

@@ -0,0 +1,39 @@
+import { IDeviceService } from "../interfaces";
+import { IConnection, IDevice } from "../types";
+export declare abstract class DeviceService implements IDeviceService {
+    deviceId: string;
+    propertyId: string;
+    name: string;
+    hubId: string[];
+    deviceType: {
+        id: string;
+        type: string;
+    };
+    status: {
+        online: boolean;
+        error?: {
+            type?: string;
+            message?: string;
+        };
+        lastUpdated?: string;
+    };
+    state?: Record<string, any>;
+    metaData?: Record<string, any>;
+    zone?: {
+        id: string;
+        name: string;
+        zoneType: string;
+        parentZone?: {
+            id: string;
+            name: string;
+            zoneType: string;
+        };
+    };
+    connection: IConnection;
+    constructor(device: IDevice);
+    abstract getDevices(connection: IConnection): Promise<Record<string, any>[]>;
+    abstract getDevice(connectionId: string, deviceId: string): Promise<any>;
+    abstract getBattery(deviceId: string): Promise<number | string>;
+    abstract getStatus(connectionId: string, deviceId: string): Promise<string>;
+    abstract getState(deviceId: string): Promise<string>;
+}

package/dist/device/cloud/services/Device.service.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceService = void 0;
+class DeviceService {
+    constructor(device) {
+        Object.assign(this, device);
+    }
+}
+exports.DeviceService = DeviceService;

package/dist/device/cloud/services/DeviceCloudService.d.ts

@@ -0,0 +1,42 @@
+import { IDeviceCloudService } from "../interface";
+import { IConnection, IDevice, IDeviceAccountResponse, IConnectionConnectParams } from "../types";
+/**
+ * Device Cloud Service Class
+ * Implements IDeviceCloudService interface with empty implementations
+ * Implementation will be provided by the consuming project
+ */
+export declare class DeviceCloudService implements IDeviceCloudService {
+    /**
+     * Creates a new connection for device management
+     * @param data - Connection data
+     * @param userId - User identifier
+     * @returns Promise with connection result
+     */
+    createConnection(data: IConnection, userId: string): Promise<any>;
+    /**
+     * Gets device account information for a connection
+     * @param connection - Connection object
+     * @returns Promise with device account response
+     */
+    getDeviceAccount(connection: IConnection): Promise<IDeviceAccountResponse>;
+    /**
+     * Gets all devices for a connection
+     * @param connection - Connection object
+     * @returns Promise with array of devices
+     */
+    getDevices(connection: IConnection): Promise<IDevice[]>;
+    /**
+     * Filters devices based on connection and device list
+     * @param connection - Connection object
+     * @param devices - Array of devices to filter
+     * @returns Promise with filtered devices
+     */
+    filterDevices(connection: IConnection, devices: any[]): Promise<IDevice[]>;
+    /**
+     * Connects to a device service
+     * @param connection - Connection object
+     * @param connectionConnect - Connection parameters
+     * @returns Promise with connection result
+     */
+    connect(connection: IConnection, connectionConnect: IConnectionConnectParams): Promise<any>;
+}

package/dist/device/cloud/services/DeviceCloudService.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceCloudService = void 0;
+/**
+ * Device Cloud Service Class
+ * Implements IDeviceCloudService interface with empty implementations
+ * Implementation will be provided by the consuming project
+ */
+class DeviceCloudService {
+    /**
+     * Creates a new connection for device management
+     * @param data - Connection data
+     * @param userId - User identifier
+     * @returns Promise with connection result
+     */
+    async createConnection(data, userId) {
+        // Implementation will be provided by the consuming project
+        throw new Error("createConnection method not implemented");
+    }
+    /**
+     * Gets device account information for a connection
+     * @param connection - Connection object
+     * @returns Promise with device account response
+     */
+    async getDeviceAccount(connection) {
+        // Implementation will be provided by the consuming project
+        throw new Error("getDeviceAccount method not implemented");
+    }
+    /**
+     * Gets all devices for a connection
+     * @param connection - Connection object
+     * @returns Promise with array of devices
+     */
+    async getDevices(connection) {
+        // Implementation will be provided by the consuming project
+        throw new Error("getDevices method not implemented");
+    }
+    /**
+     * Filters devices based on connection and device list
+     * @param connection - Connection object
+     * @param devices - Array of devices to filter
+     * @returns Promise with filtered devices
+     */
+    async filterDevices(connection, devices) {
+        // Implementation will be provided by the consuming project
+        throw new Error("filterDevices method not implemented");
+    }
+    /**
+     * Connects to a device service
+     * @param connection - Connection object
+     * @param connectionConnect - Connection parameters
+     * @returns Promise with connection result
+     */
+    async connect(connection, connectionConnect) {
+        // Implementation will be provided by the consuming project
+        throw new Error("connect method not implemented");
+    }
+}
+exports.DeviceCloudService = DeviceCloudService;

package/dist/device/cloud/services/DeviceHub.service.d.ts

@@ -0,0 +1,3 @@
+export declare abstract class DeviceHubService {
+    abstract getHubs(): Promise<any>;
+}

package/dist/device/cloud/services/DeviceHub.service.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceHubService = void 0;
+class DeviceHubService {
+}
+exports.DeviceHubService = DeviceHubService;

package/dist/device/cloud/services/Hub.service.d.ts

@@ -0,0 +1,25 @@
+import { IHubService } from "../interfaces";
+import { IConnection, IDevice } from "../types";
+export declare abstract class HubService implements IHubService {
+    deviceId: string;
+    propertyId: string;
+    name: string;
+    deviceType: {
+        id: string;
+        type: string;
+    };
+    status: {
+        online: boolean;
+        error?: {
+            type?: string;
+            message?: string;
+        };
+        lastUpdated?: string;
+    };
+    metaData?: Record<string, any>;
+    connection: IConnection;
+    constructor(hub: IDevice);
+    abstract getHubs(connectionId: string): Promise<any[] | null>;
+    abstract getHub(connectionId: string, hubId: string): Promise<Record<string, any>>;
+    abstract getStatus(connectionId: string, hubId: string): Promise<string>;
+}

package/dist/device/cloud/services/Hub.service.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HubService = void 0;
+class HubService {
+    constructor(hub) {
+        Object.assign(this, hub);
+    }
+}
+exports.HubService = HubService;

package/dist/device/cloud/services/SmartThingsDeviceService.d.ts

@@ -0,0 +1,38 @@
+import { ISmartthingsDeviceCommandManager } from "../interface";
+import { IDeviceCommand, ISmartthingsDeviceCommand, ICommandResponse } from "../types";
+/**
+ * SmartThings Device Service Class
+ * Implements ISmartthingsDeviceCommandManager interface with empty implementations
+ * Implementation will be provided by the consuming project
+ */
+export declare class SmartThingsDeviceService implements ISmartthingsDeviceCommandManager {
+    /**
+     * Invokes a command on a device
+     * @param command - Device command to execute
+     * @param deviceId - Device identifier
+     * @returns Promise with command response
+     */
+    invokeCommand(command: IDeviceCommand, deviceId: string): Promise<ICommandResponse>;
+    /**
+     * Performs device action for SmartThings
+     * @param commands - Array of SmartThings device commands
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with action result
+     */
+    performDeviceAction(commands: ISmartthingsDeviceCommand[], deviceId: string, accessToken: string): Promise<any>;
+    /**
+     * Gets device status for SmartThings
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with device status
+     */
+    getDeviceStatus(deviceId: string, accessToken: string): Promise<any>;
+    /**
+     * Gets device lock status for SmartThings
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with lock status
+     */
+    getDeviceLockStatus(deviceId: string, accessToken: string): Promise<any>;
+}

package/dist/device/cloud/services/SmartThingsDeviceService.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmartThingsDeviceService = void 0;
+/**
+ * SmartThings Device Service Class
+ * Implements ISmartthingsDeviceCommandManager interface with empty implementations
+ * Implementation will be provided by the consuming project
+ */
+class SmartThingsDeviceService {
+    /**
+     * Invokes a command on a device
+     * @param command - Device command to execute
+     * @param deviceId - Device identifier
+     * @returns Promise with command response
+     */
+    async invokeCommand(command, deviceId) {
+        // Implementation will be provided by the consuming project
+        throw new Error("invokeCommand method not implemented");
+    }
+    /**
+     * Performs device action for SmartThings
+     * @param commands - Array of SmartThings device commands
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with action result
+     */
+    async performDeviceAction(commands, deviceId, accessToken) {
+        // Implementation will be provided by the consuming project
+        throw new Error("performDeviceAction method not implemented");
+    }
+    /**
+     * Gets device status for SmartThings
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with device status
+     */
+    async getDeviceStatus(deviceId, accessToken) {
+        // Implementation will be provided by the consuming project
+        throw new Error("getDeviceStatus method not implemented");
+    }
+    /**
+     * Gets device lock status for SmartThings
+     * @param deviceId - Device identifier
+     * @param accessToken - Access token for authentication
+     * @returns Promise with lock status
+     */
+    async getDeviceLockStatus(deviceId, accessToken) {
+        // Implementation will be provided by the consuming project
+        throw new Error("getDeviceLockStatus method not implemented");
+    }
+}
+exports.SmartThingsDeviceService = SmartThingsDeviceService;

package/dist/device/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./cloud/interface";
+export * from "./cloud/types";
+export type { IConnection, IConnectionConnectParams, IDevice, IDeviceAccountResponse, } from "./cloud/types";
+export type { IDeviceCloudService } from "./cloud/interface";

package/dist/device/index.js

@@ -0,0 +1,20 @@
+"use strict";
+// DeviceThread Common Library - Device Module
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Export cloud device interfaces
+__exportStar(require("./cloud/interface"), exports);
+__exportStar(require("./cloud/types"), exports);

package/dist/device/local/events/EventHandler.js

@@ -9,9 +9,9 @@ class EventHandler {
         this.source = "dt-common-device";
     }
     async onDeviceCreate(body) {
-        await dt_pub_sub_1.eventDispatcher.publishEvent(Events_1.DT_EVENT_TYPES.DEVICE.CREATE.SUCCESS, body, this.source);
+        await dt_pub_sub_1.eventDispatcher.publishEvent(Events_1.DT_EVENT_TYPES.DEVICE.DEVICE.CREATED, body, this.source);
         const payload = {
-            eventType: Events_1.DT_EVENT_TYPES.DEVICE.CREATE.SUCCESS,
+            eventType: Events_1.DT_EVENT_TYPES.DEVICE.DEVICE.CREATED,
             properties: {
                 ...body,
             },
@@ -19,9 +19,9 @@ class EventHandler {
         await (0, dt_audit_library_1.publishAudit)(payload);
     }
     async onDeviceUpdate(deviceId, body) {
-        await dt_pub_sub_1.eventDispatcher.publishEvent(Events_1.DT_EVENT_TYPES.DEVICE.UPDATE.SUCCESS, { deviceId, body }, this.source);
+        await dt_pub_sub_1.eventDispatcher.publishEvent(Events_1.DT_EVENT_TYPES.DEVICE.DEVICE.UPDATED, { deviceId, body }, this.source);
         const payload = {
-            eventType: Events_1.DT_EVENT_TYPES.DEVICE.UPDATE.SUCCESS,
+            eventType: Events_1.DT_EVENT_TYPES.DEVICE.DEVICE.UPDATED,
             properties: {
                 ...body,
             },
@@ -29,9 +29,9 @@ class EventHandler {
         await (0, dt_audit_library_1.publishAudit)(payload);
     }
     async onDeviceDelete(deviceId) {
-        await dt_pub_sub_1.eventDispatcher.publishEvent(Events_1.DT_EVENT_TYPES.DEVICE.DELETE.SUCCESS, { deviceId }, this.source);
+        await dt_pub_sub_1.eventDispatcher.publishEvent(Events_1.DT_EVENT_TYPES.DEVICE.DEVICE.DELETED, { deviceId }, this.source);
         const payload = {
-            eventType: Events_1.DT_EVENT_TYPES.DEVICE.DELETE.SUCCESS,
+            eventType: Events_1.DT_EVENT_TYPES.DEVICE.DEVICE.DELETED,
             properties: {
                 deviceId,
             },

package/dist/device/local/events/Events.d.ts

@@ -1,16 +1,9 @@
 export declare const DT_EVENT_TYPES: {
     DEVICE: {
-        CREATE: {
-            SUCCESS: string;
-            FAILED: string;
-        };
-        UPDATE: {
-            SUCCESS: string;
-            FAILED: string;
-        };
-        DELETE: {
-            SUCCESS: string;
-            FAILED: string;
+        DEVICE: {
+            CREATED: string;
+            UPDATED: string;
+            DELETED: string;
         };
         STATE: {
             SET: string;
@@ -41,31 +34,17 @@ export declare const DT_EVENT_TYPES: {
         };
     };
     CONNECTION: {
-        CREATE: {
-            SUCCESS: string;
-            FAILED: string;
-        };
-        UPDATE: {
-            SUCCESS: string;
-            FAILED: string;
-        };
-        DELETE: {
-            SUCCESS: string;
-            FAILED: string;
+        CONNECTION: {
+            CREATED: string;
+            UPDATED: string;
+            DELETED: string;
         };
     };
     PROPERTY: {
-        CREATE: {
-            SUCCESS: string;
-            FAILED: string;
-        };
-        UPDATE: {
-            SUCCESS: string;
-            FAILED: string;
-        };
-        DELETE: {
-            SUCCESS: string;
-            FAILED: string;
+        PROPERTY: {
+            CREATED: string;
+            UPDATED: string;
+            DELETED: string;
         };
         PREFERENCES: {
             UPDATED: string;