dt-common-device 3.0.9 → 3.0.11

package/src/docs/Issue.model.md

@@ -1,386 +0,0 @@
-# Issue Model Documentation
-
-This document describes the Mongoose implementation of the Issue model, which was converted from a Prisma schema to provide comprehensive issue tracking functionality.
-
-## Overview
-
-The Issue model provides a complete issue tracking system with the following features:
-
-- **Issue Management**: Create, read, update, and delete issues
-- **Status Tracking**: Track issue status from OPEN to CLOSED
-- **Priority Levels**: Assign priority levels (LOW, MEDIUM, HIGH, CRITICAL)
-- **Categories**: Categorize issues (TECHNICAL, OPERATIONAL, etc.)
-- **Entity References**: Link issues to various entities (DEVICE, HUB, etc.)
-- **Assignment**: Assign issues to users for resolution
-- **Comments**: Add, update, and remove comments on issues
-- **Due Dates**: Set and track due dates for issues
-- **Soft Deletion**: Support for soft deletion with recovery capability
-- **Search**: Full-text search across issue titles and descriptions
-- **Statistics**: Comprehensive issue statistics and reporting
-
-## Model Structure
-
-### Core Fields
-
-| Field         | Type           | Required | Description                                   |
-| ------------- | -------------- | -------- | --------------------------------------------- |
-| `_id`         | String         | Yes      | MongoDB ObjectId (auto-generated)             |
-| `category`    | IssueCategory  | Yes      | Issue category (TECHNICAL, OPERATIONAL, etc.) |
-| `propertyId`  | String         | Yes      | Property UUID reference                       |
-| `title`       | String         | Yes      | Issue title                                   |
-| `description` | String         | Yes      | Issue description                             |
-| `entityId`    | String         | No       | Generic entity reference UUID                 |
-| `entityType`  | EntityType     | Yes      | Entity type (DEVICE, HUB, etc.)               |
-| `priority`    | IssuePriority  | Yes      | Issue priority (default: MEDIUM)              |
-| `status`      | IssueStatus    | Yes      | Issue status (default: OPEN)                  |
-| `assignedTo`  | String         | No       | User UUID assigned to resolve                 |
-| `resolvedBy`  | String         | No       | User UUID who resolved the issue              |
-| `resolvedAt`  | Date           | No       | Resolution timestamp                          |
-| `dueDate`     | Date           | No       | Due date for resolution                       |
-| `isDeleted`   | Boolean        | Yes      | Soft deletion flag (default: false)           |
-| `createdBy`   | String         | Yes      | User UUID who created the issue               |
-| `updatedBy`   | String         | No       | User UUID who last updated                    |
-| `createdAt`   | Date           | Yes      | Creation timestamp                            |
-| `updatedAt`   | Date           | Yes      | Last update timestamp                         |
-| `comments`    | IssueComment[] | No       | Array of comments                             |
-
-### Enums
-
-#### IssueCategory
-
-```typescript
-enum IssueCategory {
-  READINESS = "READINESS",
-  OPERATIONS = "OPERATIONS",
-  SECURITY = "SECURITY",
-  ENERGY = "ENERGY",
-  OTHER = "OTHER",
-}
-```
-
-#### IssuePriority
-
-```typescript
-enum IssuePriority {
-  LOW = "LOW",
-  MEDIUM = "MEDIUM",
-  HIGH = "HIGH",
-  CRITICAL = "CRITICAL",
-}
-```
-
-#### IssueStatus
-
-```typescript
-enum IssueStatus {
-  OPEN = "OPEN",
-  IN_PROGRESS = "IN_PROGRESS",
-  RESOLVED = "RESOLVED",
-  CLOSED = "CLOSED",
-}
-```
-
-#### EntityType
-
-```typescript
-enum EntityType {
-  DEVICE = "DEVICE",
-  COLLECTION = "COLLECTION",
-  USER = "USER",
-  INTEGRATION = "INTEGRATION",
-  PROPERTY = "PROPERTY",
-  HUB = "HUB",
-  SCHEDULE = "SCHEDULE",
-  ALERT = "ALERT",
-  OTHER = "OTHER",
-}
-```
-
-### Comment Structure
-
-```typescript
-interface IssueComment {
-  id: string;
-  userId: string;
-  content: string;
-  createdAt: Date;
-  updatedAt?: Date;
-}
-```
-
-## Usage Examples
-
-### Basic CRUD Operations
-
-#### Creating an Issue
-
-```typescript
-import { IssueService } from "../services/Issue.service";
-import {
-  IssueCategory,
-  EntityType,
-  IssuePriority,
-} from "../../../types/issue.types";
-
-const issueService = new IssueService();
-
-const newIssue = await issueService.createIssue({
-  category: IssueCategory.READINESS,
-  propertyId: "property-uuid",
-  title: "Device connectivity issue",
-  description: "Device is not responding to commands",
-  entityId: "device-uuid",
-  entityType: EntityType.DEVICE,
-  priority: IssuePriority.HIGH,
-  createdBy: "user-uuid",
-  dueDate: new Date("2024-01-15"),
-});
-```
-
-#### Getting Issues
-
-```typescript
-// Get all issues for a property
-const propertyIssues = await issueService.getIssuesByProperty("property-uuid");
-
-// Get issues assigned to a user
-const assignedIssues = await issueService.getIssuesByAssignee("user-uuid");
-
-// Get issues by status
-const openIssues = await issueService.getIssuesByStatus(IssueStatus.OPEN);
-
-// Get issues with filters
-const filteredIssues = await issueService.getIssues({
-  propertyId: "property-uuid",
-  status: IssueStatus.IN_PROGRESS,
-  priority: IssuePriority.HIGH,
-  limit: 10,
-  skip: 0,
-});
-```
-
-#### Updating an Issue
-
-```typescript
-// Update issue status
-await issueService.updateIssue(issueId, {
-  status: IssueStatus.IN_PROGRESS,
-  updatedBy: "user-uuid",
-});
-
-// Assign issue to user
-await issueService.assignIssue(issueId, "assignee-uuid", "assigned-by-uuid");
-
-// Resolve issue
-await issueService.resolveIssue(
-  issueId,
-  "resolved-by-uuid",
-  "Issue resolved successfully"
-);
-
-// Close issue
-await issueService.closeIssue(issueId, "closed-by-uuid");
-```
-
-#### Adding Comments
-
-```typescript
-// Add a comment
-await issueService.addComment(issueId, {
-  userId: "user-uuid",
-  content: "Investigation in progress",
-});
-
-// Update a comment
-await issueService.updateComment(
-  issueId,
-  commentId,
-  "Updated content",
-  "user-uuid"
-);
-
-// Remove a comment
-await issueService.removeComment(issueId, commentId);
-```
-
-### Advanced Operations
-
-#### Search Issues
-
-```typescript
-// Search by text
-const searchResults = await issueService.searchIssues("connectivity", {
-  propertyId: "property-uuid",
-  limit: 20,
-});
-```
-
-#### Get Statistics
-
-```typescript
-// Get overall statistics
-const stats = await issueService.getIssueStatistics();
-
-// Get property-specific statistics
-const propertyStats = await issueService.getIssueStatistics("property-uuid");
-
-console.log(`Total issues: ${stats.total}`);
-console.log(`Open issues: ${stats.open}`);
-console.log(`Overdue issues: ${stats.overdue}`);
-console.log(`High priority: ${stats.byPriority.HIGH}`);
-console.log(`Readiness issues: ${stats.byCategory.READINESS}`);
-```
-
-#### Find Overdue Issues
-
-```typescript
-// Get all overdue issues
-const overdueIssues = await issueService.getOverdueIssues();
-
-// Get upcoming issues (due within 7 days)
-const upcomingIssues = await issueService.getUpcomingIssues(7);
-```
-
-#### Repository Pattern Usage
-
-For more advanced data access patterns, use the repository:
-
-```typescript
-import { IssueRepository } from "../repository/Issue.repository";
-
-const issueRepo = new IssueRepository();
-
-// Bulk operations
-await issueRepo.bulkUpdate(["issue1", "issue2"], {
-  status: IssueStatus.CLOSED,
-  updatedBy: "user-uuid",
-});
-
-// Count issues
-const count = await issueRepo.count({
-  propertyId: "property-uuid",
-  status: IssueStatus.OPEN,
-});
-
-// Advanced filtering with sorting
-const issues = await issueRepo.findAll({
-  propertyId: "property-uuid",
-  sort: { priority: -1, createdAt: -1 },
-  limit: 50,
-});
-```
-
-## Business Rules
-
-### Status Transitions
-
-Issues follow a specific status flow:
-
-1. **OPEN** → **IN_PROGRESS** (requires assignment)
-2. **IN_PROGRESS** → **RESOLVED** (requires resolution note)
-3. **RESOLVED** → **CLOSED** (final state)
-4. **RESOLVED** → **OPEN** (reopen allowed)
-5. **CLOSED** → **OPEN** (reopen allowed)
-
-### Assignment Requirements
-
-- Issues must be assigned before moving to IN_PROGRESS status
-- Only assigned issues can be moved to IN_PROGRESS
-- Unassigned issues remain in OPEN status
-
-### Resolution Requirements
-
-- Issues must have a resolution note when moved to RESOLVED status
-- Resolution automatically sets the `resolvedAt` timestamp
-- Resolution automatically sets the `resolvedBy` user
-
-### Overdue Calculation
-
-Issues are considered overdue based on priority:
-
-| Priority | Overdue After |
-| -------- | ------------- |
-| LOW      | 14 days       |
-| MEDIUM   | 7 days        |
-| HIGH     | 3 days        |
-| CRITICAL | 1 day         |
-
-### Priority Management
-
-- Priority can be changed at any time
-- Priority changes are logged for audit purposes
-- Critical priority issues get special handling
-
-## Indexes
-
-The model includes the following indexes for optimal performance:
-
-- `propertyId` (single field)
-- `assignedTo` (single field)
-- `entityId` (single field)
-- `entityType` (single field)
-- `status` (single field)
-- `priority` (single field)
-- `createdAt` (single field)
-- `{ propertyId: 1, status: 1, priority: 1 }` (compound)
-- `{ assignedTo: 1, status: 1 }` (compound)
-- `{ entityId: 1, entityType: 1 }` (compound)
-
-## Middleware
-
-The model includes pre-save and pre-update middleware that automatically:
-
-- Updates the `updatedAt` timestamp on save
-- Updates the `updatedAt` timestamp on update operations
-- Validates status transitions
-- Validates assignment requirements
-
-## Virtual Fields
-
-- `isOverdue`: Returns `true` if the issue is overdue
-- `timeToResolution`: Calculates time to resolution (if resolved)
-- `isAssigned`: Returns `true` if the issue is assigned
-
-## Error Handling
-
-All operations include comprehensive error handling with descriptive error messages. The service and repository layers wrap database operations in try-catch blocks and provide meaningful error messages.
-
-Common error scenarios:
-
-- **Invalid status transition**: "Cannot transition from OPEN to RESOLVED"
-- **Missing assignment**: "Issue must be assigned before moving to IN_PROGRESS"
-- **Missing resolution**: "Resolution note is required when resolving an issue"
-- **Invalid due date**: "Due date must be in the future"
-- **Missing required fields**: "Issue title must be at least 3 characters long"
-
-## Best Practices
-
-1. **Set Realistic Due Dates**: Set achievable due dates for better tracking
-2. **Use Appropriate Categories**: Properly categorize issues for better organization
-3. **Assign Issues Promptly**: Assign issues to appropriate users quickly
-4. **Add Meaningful Comments**: Use comments to track progress and communication
-5. **Monitor Overdue Issues**: Regularly check for overdue issues
-6. **Use Priority Wisely**: Don't overuse high/critical priority
-7. **Provide Resolution Notes**: Always include detailed resolution notes
-8. **Use Soft Deletion**: Always use soft deletion for audit trails
-9. **Validate Input**: Always validate issue data before creation
-10. **Monitor Statistics**: Regularly check issue statistics for insights
-
-## Migration from Prisma
-
-This Mongoose model maintains full compatibility with the original Prisma schema:
-
-- All fields and types are preserved
-- Indexes match the Prisma schema
-- Relationships are maintained through foreign key references
-- Collection name matches Prisma (`dt_issues`)
-
-The model provides additional features beyond the Prisma schema:
-
-- Instance methods for common operations
-- Static methods for complex queries
-- Virtual fields for computed properties
-- Comprehensive business logic validation
-- Built-in monitoring and logging
-- Comment management system
-- Overdue calculation logic

package/src/docs/SECURITY.md

@@ -1,67 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.0.x   | :white_check_mark: |
-
-## Reporting a Vulnerability
-
-If you discover a security vulnerability within dt-common-device, please send an email to security@devicethread.com. All security vulnerabilities will be promptly addressed.
-
-## Security Features
-
-### Input Validation
-
-- All user inputs are validated and sanitized
-- Device IDs and Property IDs are validated for format and length
-- Metadata is sanitized to prevent injection attacks
-- URL validation for all external service endpoints
-
-### Error Handling
-
-- Custom error classes for different types of failures
-- No sensitive information leaked in error messages
-- Proper HTTP status code mapping
-- Graceful degradation for network failures
-
-### Type Safety
-
-- Full TypeScript support with strict typing
-- No `any` types in public APIs
-- Interface validation for all data structures
-
-### Network Security
-
-- HTTPS enforcement for all external calls
-- Request timeout handling
-- Retry logic for transient failures
-- Proper error classification for different HTTP status codes
-
-## Best Practices
-
-1. **Always validate inputs** before passing to library methods
-2. **Handle errors appropriately** using the provided error classes
-3. **Use HTTPS** for all external service URLs
-4. **Keep dependencies updated** by running `npm audit` regularly
-5. **Monitor for security updates** in dependent packages
-
-## Dependencies
-
-This library uses the following security-focused dependencies:
-
-- `axios` - HTTP client with built-in security features
-- `lodash` - Utility library with security patches
-- Custom validation utilities for input sanitization
-
-## Vulnerability Prevention
-
-- Regular security audits with `npm audit`
-- Automated vulnerability scanning in CI/CD
-- Input validation and sanitization
-- Type-safe interfaces
-- Comprehensive error handling
-- No eval() or dynamic code execution
-- No direct file system access
-- No command injection vulnerabilities

package/src/docs/TROUBLESHOOTING.md

@@ -1,184 +0,0 @@
-# Troubleshooting Guide
-
-## HTTP Request Issues
-
-### Error: `TypeError: Cannot read properties of undefined (reading 'emit')`
-
-This error typically occurs when HTTP requests fail due to network connectivity issues, invalid service URLs, or request timeouts.
-
-#### Common Causes:
-
-1. **Invalid or unreachable DEVICE_SERVICE URL**
-2. **Network connectivity issues**
-3. **Service is down or not responding**
-4. **Request timeout (default: 30 seconds)**
-5. **DNS resolution failures**
-
-#### Solutions:
-
-1. **Check Service URL Configuration**
-
-   ```typescript
-   // Ensure DEVICE_SERVICE URL is properly configured
-   const config: IConfig = {
-     DEVICE_SERVICE: "http://localhost:3000", // or your actual service URL
-     // ... other config
-   };
-   ```
-
-2. **Verify Network Connectivity**
-
-   ```bash
-   # Test if the service is reachable
-   curl -v http://your-device-service-url/health
-   ```
-
-3. **Check Service Status**
-
-   - Ensure the device service is running
-   - Check if the service is listening on the correct port
-   - Verify firewall settings
-
-4. **Enable Debug Logging**
-   ```typescript
-   const config: IConfig = {
-     LOGGER: {
-       info: (msg, ...args) => console.log(msg, ...args),
-       warn: (msg, ...args) => console.warn(msg, ...args),
-       error: (msg, ...args) => console.error(msg, ...args),
-     },
-     // ... other config
-   };
-   ```
-
-#### Recent Fixes Applied:
-
-1. **Centralized Axios Instance**: All HTTP requests now use a single, properly configured axios instance
-2. **Added Request Timeouts**: All HTTP requests have a 30-second timeout
-3. **Improved Error Handling**: Better error messages with context
-4. **Request/Response Interceptors**: Added logging for debugging
-5. **URL Validation**: Service URLs are validated during initialization
-6. **Retry Logic**: Failed requests can be retried with exponential backoff
-
-#### Architecture Changes:
-
-**Before**: Each repository created its own axios instance
-
-```typescript
-// Old approach - each repository had its own axios setup
-export class DeviceRepository {
-  private readonly axiosInstance;
-
-  constructor() {
-    this.axiosInstance = axios.create({
-      timeout: 30000,
-      // ... other config
-    });
-    // ... interceptors setup
-  }
-}
-```
-
-**After**: Centralized axios instance shared across all repositories
-
-```typescript
-// New approach - centralized axios instance
-import { getDeviceServiceAxiosInstance } from "../../../utils/http-utils";
-
-export class DeviceRepository {
-  private readonly axiosInstance;
-
-  constructor() {
-    this.axiosInstance = getDeviceServiceAxiosInstance();
-  }
-}
-```
-
-#### Benefits of Centralized Approach:
-
-1. **Consistency**: All HTTP requests use the same configuration
-2. **Maintainability**: Configuration changes only need to be made in one place
-3. **Performance**: Single instance reduces memory usage
-4. **Error Handling**: Centralized error handling and logging
-5. **Testing**: Easier to mock and test HTTP requests
-
-#### Debugging Steps:
-
-1. **Check Logs**: Look for detailed error messages in the logs
-2. **Verify Configuration**: Ensure all required environment variables are set
-3. **Test Connectivity**: Use curl or similar tools to test service endpoints
-4. **Check Network**: Verify network connectivity and DNS resolution
-
-#### Environment Variables Required:
-
-```bash
-# Required for HTTP requests
-DEVICE_SERVICE=http://your-device-service-url
-
-# Required for database connections
-ADMIN_DB_URI=postgresql://...
-MONGODB_URI=mongodb://...
-REDIS_HOST=localhost
-REDIS_PORT=6379
-
-# Required for AWS services
-AWS_ACCESS_KEY_ID=your-access-key
-AWS_SECRET_ACCESS_KEY=your-secret-key
-AWS_REGION=your-region
-EVENT_BUS_NAME=your-event-bus
-
-# Required for analytics
-POSTHOG_API_KEY=your-api-key
-POSTHOG_HOST=your-posthog-host
-```
-
-#### Example Error Handling:
-
-```typescript
-import { initialize } from "dt-common-device";
-
-try {
-  await initialize({
-    DEVICE_SERVICE: "http://localhost:3000",
-    LOGGER: console,
-    // ... other config
-  });
-} catch (error) {
-  console.error("Initialization failed:", error.message);
-  // Handle initialization error
-}
-```
-
-#### Repository Error Handling:
-
-All repository classes now include:
-
-- Proper try-catch blocks
-- Detailed error logging
-- Request timeouts
-- Response validation
-- Network error detection
-- Centralized axios instance usage
-
-#### Affected Files:
-
-The following repository files now use the centralized axios instance:
-
-- `src/device/local/repository/Device.repository.ts`
-- `src/device/local/repository/Hub.repository.ts`
-- `src/device/local/repository/Schedule.repository.ts`
-
-Other repository files (Alert, Issue, Property, Connection) use database operations and don't require HTTP requests.
-
-#### HTTP Utilities:
-
-The centralized axios instance is managed in:
-
-- `src/utils/http-utils.ts` - Contains the axios instance creation and configuration
-
-If you continue to experience issues, please:
-
-1. Check the service logs for detailed error messages
-2. Verify all environment variables are correctly set
-3. Test network connectivity to the service endpoints
-4. Ensure the target services are running and accessible