@ufdevsllc/authme2.0/API-REFERENCE.md

SDK for license management and remote monitoring with automatic system tracking, license validation, and remote control capabilities

# License Monitoring SDK - Complete API Reference

## Overview

This document provides a comprehensive reference for all classes, methods, and interfaces in the License Monitoring SDK. It covers both public APIs for client integration and internal architecture details.

## Table of Contents

1. [Main SDK Class](#main-sdk-class)
2. [Database Manager](#database-manager)
3. [License Validator](#license-validator)
4. [System Tracker](#system-tracker)
5. [Remote Control Handler](#remote-control-handler)
6. [Data Logger](#data-logger)
7. [Error Handler](#error-handler)
8. [Data Models](#data-models)
9. [Configuration Options](#configuration-options)
10. [Error Types](#error-types)

---

## Main SDK Class

### `LicenseMonitoringSDK`

The main entry point for the SDK.

#### Constructor

```javascript
new LicenseMonitoringSDK()
```

Creates a new SDK instance. No parameters required.

#### Methods

##### `init(licenseKey, options)`

Initializes the SDK with a license key and optional configuration.

**Parameters:**
- `licenseKey` (string, required): The license key provided by your vendor
- `options` (object, optional): Configuration options

**Options:**
```javascript
{
    validateLicense: boolean,        // Default: true
    startSystemTracking: boolean,   // Default: true
    startRemoteControl: boolean,    // Default: true
    exitOnLicenseFailure: boolean,  // Default: true
    logToConsole: boolean,          // Default: true
    retryAttempts: number,          // Default: 3
    retryDelay: number,             // Default: 5000 (ms)
    connectionOptions: {            // MongoDB connection options
        maxPoolSize: number,        // Default: 10
        minPoolSize: number,        // Default: 2
        maxIdleTimeMS: number,      // Default: 30000
        serverSelectionTimeoutMS: number // Default: 5000
    }
}
```

**Returns:** `Promise<void>`

**Throws:**
- `LicenseValidationError`: If license validation fails
- `DatabaseConnectionError`: If database connection fails
- `InitializationError`: If SDK initialization fails

**Example:**
```javascript
const sdk = new LicenseMonitoringSDK();

// Basic initialization
await sdk.init('YOUR-LICENSE-KEY');

// Advanced initialization
await sdk.init('YOUR-LICENSE-KEY', {
    validateLicense: true,
    startSystemTracking: true,
    exitOnLicenseFailure: false,
    retryAttempts: 5,
    connectionOptions: {
        maxPoolSize: 20
    }
});
```

##### `logData(collection, data, operation)`

Logs application data to the monitoring database.

**Parameters:**
- `collection` (string, required): Collection name for the data
- `data` (object, required): Data to log
- `operation` (string, required): Operation type (e.g., 'create', 'update', 'delete')

**Returns:** `Promise<void>`

**Throws:**
- `ValidationError`: If parameters are invalid
- `DatabaseError`: If database operation fails

**Example:**
```javascript
await sdk.logData('orders', {
    orderId: 'ORD-001',
    customerId: 'CUST-123',
    total: 99.99,
    status: 'completed'
}, 'create');
```

##### `logUserActivity(userId, action, details)`

Logs user activity and behavior.

**Parameters:**
- `userId` (string, required): User identifier
- `action` (string, required): Action performed
- `details` (object, optional): Additional details about the action

**Returns:** `Promise<void>`

**Example:**
```javascript
await sdk.logUserActivity('user123', 'login', {
    ip: '192.168.1.100',
    userAgent: 'Chrome/120.0',
    timestamp: new Date()
});
```

##### `logModelOperation(modelName, operation, data)`

Logs database model operations.

**Parameters:**
- `modelName` (string, required): Name of the model/entity
- `operation` (string, required): Operation performed ('create', 'update', 'delete', etc.)
- `data` (object, required): Operation data

**Returns:** `Promise<void>`

**Example:**
```javascript
await sdk.logModelOperation('User', 'update', {
    userId: 'user123',
    changes: { email: 'new@email.com' }
});
```

##### `bulkLog(operations)`

Performs bulk logging operations for better performance.

**Parameters:**
- `operations` (array, required): Array of operation objects

**Operation Object:**
```javascript
{
    collection: string,
    data: object,
    operation: string
}
```

**Returns:** `Promise<void>`

**Example:**
```javascript
await sdk.bulkLog([
    {
        collection: 'page_views',
        data: { page: '/home', userId: 'user1' },
        operation: 'track'
    },
    {
        collection: 'clicks',
        data: { element: 'button', userId: 'user1' },
        operation: 'track'
    }
]);
```

##### `isLicenseValid()`

Checks if the current license is valid.

**Returns:** `Promise<boolean>`

**Example:**
```javascript
const isValid = await sdk.isLicenseValid();
if (!isValid) {
    console.log('License is invalid or expired');
}
```

##### `getLicenseStatus()`

Gets detailed license status information.

**Returns:** `Promise<LicenseStatus>`

**LicenseStatus Object:**
```javascript
{
    licenseKey: string,
    isActive: boolean,
    expiresAt: Date,
    distributionLimit: number,
    currentDistributions: number,
    validationCount: number,
    lastValidated: Date
}
```

**Example:**
```javascript
const status = await sdk.getLicenseStatus();
console.log('License expires:', status.expiresAt);
console.log('Usage:', `${status.currentDistributions}/${status.distributionLimit}`);
```

##### `isApplicationBlocked()`

Checks if the application is currently blocked by remote control.

**Returns:** `boolean`

**Example:**
```javascript
if (sdk.isApplicationBlocked()) {
    console.log('Application is blocked');
}
```

##### `getBlockReason()`

Gets the reason why the application is blocked.

**Returns:** `string | null`

**Example:**
```javascript
if (sdk.isApplicationBlocked()) {
    console.log('Block reason:', sdk.getBlockReason());
}
```

##### `healthCheck()`

Performs a comprehensive health check on all SDK components.

**Returns:** `Promise<HealthStatus>`

**HealthStatus Object:**
```javascript
{
    overall: boolean,
    components: {
        database: {
            healthy: boolean,
            error?: string,
            latency?: number
        },
        license: {
            healthy: boolean,
            error?: string,
            status?: string
        },
        systemTracker: {
            healthy: boolean,
            error?: string,
            lastUpdate?: Date
        },
        remoteControl: {
            healthy: boolean,
            error?: string,
            lastCheck?: Date
        }
    },
    timestamp: Date
}
```

**Example:**
```javascript
const health = await sdk.healthCheck();
console.log('Overall health:', health.overall);

if (!health.components.database.healthy) {
    console.error('Database issue:', health.components.database.error);
}
```

##### `getStatus()`

Gets current SDK status and configuration.

**Returns:** `SDKStatus`

**SDKStatus Object:**
```javascript
{
    initialized: boolean,
    licenseKey: string,
    version: string,
    uptime: number,
    components: {
        databaseManager: boolean,
        licenseValidator: boolean,
        systemTracker: boolean,
        remoteControlHandler: boolean,
        dataLogger: boolean
    }
}
```

##### `shutdown()`

Properly shuts down the SDK and cleans up resources.

**Returns:** `Promise<void>`

**Example:**
```javascript
// Graceful shutdown
process.on('SIGINT', async () => {
    console.log('Shutting down...');
    await sdk.shutdown();
    process.exit(0);
});
```

---

## Database Manager

### `DatabaseManager`

Handles MongoDB connections and database operations.

#### Methods

##### `initMonitoringConnection()`

Initializes connection to the monitoring database.

**Returns:** `Promise<void>`

##### `getMonitoringDB()`

Gets the monitoring database instance.

**Returns:** `Db` (MongoDB database instance)

##### `saveUserData(collection, data)`

Saves user data to the monitoring database.

**Parameters:**
- `collection` (string): Collection name
- `data` (object): Data to save

**Returns:** `Promise<InsertOneResult>`

##### `closeConnection()`

Closes the database connection.

**Returns:** `Promise<void>`

---

## License Validator

### `LicenseValidator`

Handles license validation and tracking.

#### Methods

##### `validateLicense(licenseKey)`

Validates a license key against the database.

**Parameters:**
- `licenseKey` (string): License key to validate

**Returns:** `Promise<ValidationResult>`

**ValidationResult Object:**
```javascript
{
    valid: boolean,
    license?: LicenseDocument,
    error?: string,
    reason?: string
}
```

##### `trackUsage(licenseKey, systemInfo)`

Tracks license usage and system information.

**Parameters:**
- `licenseKey` (string): License key
- `systemInfo` (object): System information

**Returns:** `Promise<void>`

##### `checkDistributionLimit(licenseKey)`

Checks if the license has exceeded its distribution limit.

**Parameters:**
- `licenseKey` (string): License key

**Returns:** `Promise<boolean>`

##### `isLicenseActive(licenseKey)`

Checks if a license is currently active.

**Parameters:**
- `licenseKey` (string): License key

**Returns:** `Promise<boolean>`

---

## System Tracker

### `SystemTracker`

Collects and tracks system information.

#### Methods

##### `collectSystemInfo()`

Collects current system information.

**Returns:** `SystemInfo`

**SystemInfo Object:**
```javascript
{
    os: string,
    platform: string,
    arch: string,
    memory: number,
    cpu: {
        model: string,
        cores: number,
        speed: number
    },
    nodeVersion: string
}
```

##### `collectDeploymentInfo()`

Collects deployment-specific information.

**Returns:** `Promise<DeploymentInfo>`

**DeploymentInfo Object:**
```javascript
{
    ipAddress: string,
    serverLocation: string,
    environment: string,
    timestamp: Date,
    nodeVersion: string
}
```

##### `collectCORSInfo()`

Collects CORS configuration information.

**Returns:** `CORSInfo`

**CORSInfo Object:**
```javascript
{
    allowedOrigins: string[],
    methods: string[],
    headers: string[]
}
```

##### `saveToMonitoring(data)`

Saves collected data to the monitoring database.

**Parameters:**
- `data` (object): Data to save

**Returns:** `Promise<void>`

##### `startPeriodicTracking()`

Starts periodic system tracking.

**Returns:** `void`

---

## Remote Control Handler

### `RemoteControlHandler`

Handles remote control commands from the vendor backend.

#### Methods

##### `checkForCommands()`

Checks the database for pending remote commands.

**Returns:** `Promise<RemoteCommand[]>`

##### `executeCommand(command)`

Executes a remote command.

**Parameters:**
- `command` (RemoteCommand): Command to execute

**Returns:** `Promise<CommandResult>`

**CommandResult Object:**
```javascript
{
    success: boolean,
    result?: any,
    error?: string,
    executedAt: Date
}
```

##### `blockApplication(reason)`

Blocks the application with a specified reason.

**Parameters:**
- `reason` (string): Reason for blocking

**Returns:** `void`

##### `updateLicenseStatus(status)`

Updates the license status based on remote commands.

**Parameters:**
- `status` (string): New license status

**Returns:** `Promise<void>`

##### `startCommandPolling()`

Starts polling for remote commands.

**Returns:** `void`

---

## Data Logger

### `DataLogger`

Handles data logging operations.

#### Methods

##### `logData(collectionName, data, operation)`

Logs data to a specific collection.

**Parameters:**
- `collectionName` (string): Collection name
- `data` (object): Data to log
- `operation` (string): Operation type

**Returns:** `Promise<void>`

##### `logUserActivity(userId, action, details)`

Logs user activity.

**Parameters:**
- `userId` (string): User identifier
- `action` (string): Action performed
- `details` (object): Additional details

**Returns:** `Promise<void>`

##### `logModelOperation(modelName, operation, data)`

Logs model operations.

**Parameters:**
- `modelName` (string): Model name
- `operation` (string): Operation type
- `data` (object): Operation data

**Returns:** `Promise<void>`

##### `bulkLog(operations)`

Performs bulk logging operations.

**Parameters:**
- `operations` (array): Array of operations

**Returns:** `Promise<void>`

---

## Error Handler

### `ErrorHandler`

Handles errors and logging throughout the SDK.

#### Methods

##### `handleError(error, context)`

Handles and logs errors.

**Parameters:**
- `error` (Error): Error object
- `context` (string): Error context

**Returns:** `void`

##### `logError(error, metadata)`

Logs errors to the monitoring database.

**Parameters:**
- `error` (Error): Error object
- `metadata` (object): Additional metadata

**Returns:** `Promise<void>`

---

## Data Models

### License Document

```javascript
{
    _id: ObjectId,
    licenseKey: string,
    distributionLimit: number,
    currentDistributions: number,
    isActive: boolean,
    createdAt: Date,
    expiresAt: Date,
    vendorId: string,
    productId: string,
    clientInfo: {
        companyName: string,
        contactEmail: string,
        purchaseDate: Date,
        licenseType: string
    },
    features: {
        maxUsers: number,
        apiAccess: boolean,
        premiumSupport: boolean,
        customBranding: boolean
    },
    validationCount: number,
    lastValidated: Date,
    systems: [{
        systemId: string,
        firstSeen: Date,
        lastSeen: Date,
        isActive: boolean
    }]
}
```

### System Tracking Document

```javascript
{
    _id: ObjectId,
    licenseKey: string,
    systemId: string,
    systemInfo: {
        os: string,
        platform: string,
        arch: string,
        memory: number,
        cpu: {
            model: string,
            cores: number,
            speed: number
        }
    },
    deploymentInfo: {
        ipAddress: string,
        serverLocation: string,
        environment: string,
        nodeVersion: string,
        timestamp: Date
    },
    corsSettings: {
        allowedOrigins: string[],
        methods: string[],
        headers: string[]
    },
    environmentVariables: object,
    lastSeen: Date,
    isActive: boolean
}
```

### Usage Log Document

```javascript
{
    _id: ObjectId,
    licenseKey: string,
    collection: string,
    operation: string,
    data: object,
    timestamp: Date,
    systemId: string,
    metadata: {
        userAgent: string,
        ipAddress: string,
        sessionId: string
    }
}
```

### Remote Command Document

```javascript
{
    _id: ObjectId,
    licenseKey: string,
    command: string,
    parameters: object,
    status: string, // 'pending', 'executing', 'completed', 'failed'
    createdAt: Date,
    executedAt: Date,
    result: object,
    priority: string, // 'low', 'medium', 'high', 'critical'
    retryCount: number,
    maxRetries: number
}
```

---

## Configuration Options

### SDK Initialization Options

```javascript
{
    // License validation settings
    validateLicense: boolean,        // Enable license validation (default: true)
    exitOnLicenseFailure: boolean,  // Exit process on license failure (default: true)
    
    // Component settings
    startSystemTracking: boolean,   // Enable system tracking (default: true)
    startRemoteControl: boolean,    // Enable remote control (default: true)
    
    // Logging settings
    logToConsole: boolean,          // Enable console logging (default: true)
    
    // Connection settings
    retryAttempts: number,          // Connection retry attempts (default: 3)
    retryDelay: number,             // Retry delay in ms (default: 5000)
    
    // MongoDB connection options
    connectionOptions: {
        maxPoolSize: number,        // Maximum connection pool size (default: 10)
        minPoolSize: number,        // Minimum connection pool size (default: 2)
        maxIdleTimeMS: number,      // Max idle time for connections (default: 30000)
        serverSelectionTimeoutMS: number, // Server selection timeout (default: 5000)
        connectTimeoutMS: number,   // Connection timeout (default: 10000)
        socketTimeoutMS: number,    // Socket timeout (default: 0)
        heartbeatFrequencyMS: number, // Heartbeat frequency (default: 10000)
        retryWrites: boolean,       // Enable retry writes (default: true)
        w: string | number,         // Write concern (default: 'majority')
        readPreference: string      // Read preference (default: 'primary')
    }
}
```

### Environment Variables

```bash
# Required
LICENSE_KEY=your-license-key-here

# Optional
NODE_ENV=production
SDK_LOG_LEVEL=info
SDK_RETRY_ATTEMPTS=3
SDK_RETRY_DELAY=5000
```

---

## Error Types

### `LicenseValidationError`

Thrown when license validation fails.

**Properties:**
- `message`: Error message
- `licenseKey`: The license key that failed validation
- `reason`: Specific reason for failure

**Example:**
```javascript
try {
    await sdk.init('invalid-license');
} catch (error) {
    if (error instanceof LicenseValidationError) {
        console.error('License validation failed:', error.reason);
    }
}
```

### `DatabaseConnectionError`

Thrown when database connection fails.

**Properties:**
- `message`: Error message
- `connectionString`: Database connection string (sanitized)
- `retryAttempts`: Number of retry attempts made

### `InitializationError`

Thrown when SDK initialization fails.

**Properties:**
- `message`: Error message
- `component`: Component that failed to initialize
- `originalError`: Original error that caused the failure

### `ValidationError`

Thrown when input validation fails.

**Properties:**
- `message`: Error message
- `field`: Field that failed validation
- `value`: Value that failed validation

### `DatabaseError`

Thrown when database operations fail.

**Properties:**
- `message`: Error message
- `operation`: Database operation that failed
- `collection`: Collection involved in the operation

---

## Event System

The SDK emits events for monitoring and debugging purposes.

### Events

#### `initialized`

Emitted when the SDK is successfully initialized.

```javascript
sdk.on('initialized', (data) => {
    console.log('SDK initialized:', data);
});
```

#### `license-validated`

Emitted when license validation completes.

```javascript
sdk.on('license-validated', (result) => {
    console.log('License validation result:', result);
});
```

#### `data-logged`

Emitted when data is successfully logged.

```javascript
sdk.on('data-logged', (logInfo) => {
    console.log('Data logged:', logInfo);
});
```

#### `error`

Emitted when an error occurs.

```javascript
sdk.on('error', (error) => {
    console.error('SDK error:', error);
});
```

#### `command-received`

Emitted when a remote command is received.

```javascript
sdk.on('command-received', (command) => {
    console.log('Remote command received:', command);
});
```

#### `application-blocked`

Emitted when the application is blocked.

```javascript
sdk.on('application-blocked', (reason) => {
    console.log('Application blocked:', reason);
});
```

---

## Utilities

### `generateSystemId()`

Generates a unique system identifier.

**Returns:** `string`

### `sanitizeData(data, options)`

Sanitizes data before logging.

**Parameters:**
- `data` (object): Data to sanitize
- `options` (object): Sanitization options

**Returns:** `object`

### `validateLicenseKey(licenseKey)`

Validates license key format.

**Parameters:**
- `licenseKey` (string): License key to validate

**Returns:** `boolean`

---

## TypeScript Definitions

```typescript
declare module '@ufdevsllc/authme2.0' {
    interface SDKOptions {
        validateLicense?: boolean;
        startSystemTracking?: boolean;
        startRemoteControl?: boolean;
        exitOnLicenseFailure?: boolean;
        logToConsole?: boolean;
        retryAttempts?: number;
        retryDelay?: number;
        connectionOptions?: {
            maxPoolSize?: number;
            minPoolSize?: number;
            maxIdleTimeMS?: number;
            serverSelectionTimeoutMS?: number;
        };
    }

    interface LicenseStatus {
        licenseKey: string;
        isActive: boolean;
        expiresAt: Date;
        distributionLimit: number;
        currentDistributions: number;
        validationCount: number;
        lastValidated: Date;
    }

    interface HealthStatus {
        overall: boolean;
        components: {
            database: ComponentHealth;
            license: ComponentHealth;
            systemTracker: ComponentHealth;
            remoteControl: ComponentHealth;
        };
        timestamp: Date;
    }

    interface ComponentHealth {
        healthy: boolean;
        error?: string;
        [key: string]: any;
    }

    class LicenseMonitoringSDK {
        constructor();
        
        init(licenseKey: string, options?: SDKOptions): Promise<void>;
        
        logData(collection: string, data: object, operation: string): Promise<void>;
        logUserActivity(userId: string, action: string, details?: object): Promise<void>;
        logModelOperation(modelName: string, operation: string, data: object): Promise<void>;
        bulkLog(operations: Array<{collection: string, data: object, operation: string}>): Promise<void>;
        
        isLicenseValid(): Promise<boolean>;
        getLicenseStatus(): Promise<LicenseStatus>;
        
        isApplicationBlocked(): boolean;
        getBlockReason(): string | null;
        
        healthCheck(): Promise<HealthStatus>;
        getStatus(): object;
        
        shutdown(): Promise<void>;
    }

    export = LicenseMonitoringSDK;
}
```

---

## Version History

### v1.0.0
- Initial release
- Basic license validation
- Data logging capabilities
- System tracking
- Remote control functionality

### v1.1.0 (Current)
- Enhanced error handling
- Bulk logging operations
- Performance improvements
- Extended health monitoring
- TypeScript definitions

---

## Support

For API-specific questions and technical support:

- **Documentation**: https://docs.ufdevsllc.com/license-monitoring-sdk
- **API Reference**: https://api.ufdevsllc.com/docs
- **GitHub Issues**: https://github.com/ufdevsllc/authme2.0/issues
- **Email**: api-support@ufdevsllc.com

---

*This API reference is automatically generated from the source code and is kept up-to-date with each release.*