Interface Documentation

interface Tool {
    /** Unique identifier for the tool */
    id: string;

    /** Human-readable name */
    name: string;

    /** Detailed description */
    description: string;

    /** Semantic version */
    version: string;

    /** Tool category */
    category: ToolCategory;

    /** Execute tool functionality */
    execute(params: any): Promise<ToolResult>;
}

interface ToolResult {
    /** Operation success status */
    success: boolean;

    /** Response data */
    data?: any;

    /** Error message if failed */
    message?: string;

    /** Error code if failed */
    error_code?: string;
}

enum ToolCategory {
    DeviceManagement = 'device_management',
    HistoryState = 'history_state',
    Automation = 'automation',
    AddonsPackages = 'addons_packages',
    Notifications = 'notifications',
    Events = 'events',
    Utility = 'utility'
}

interface EventSubscription {
    /** Unique subscription ID */
    id: string;

    /** Event type to subscribe to */
    event_type: string;

    /** Optional entity ID filter */
    entity_id?: string;

    /** Optional domain filter */
    domain?: string;

    /** Subscription creation timestamp */
    created_at: string;

    /** Last event timestamp */
    last_event?: string;
}

interface EventMessage {
    /** Event type */
    event_type: string;

    /** Entity ID if applicable */
    entity_id?: string;

    /** Event data */
    data: any;

    /** Event origin */
    origin: 'LOCAL' | 'REMOTE';

    /** Event timestamp */
    time_fired: string;

    /** Event context */
    context: EventContext;
}

interface Device {
    /** Device ID */
    id: string;

    /** Device name */
    name: string;

    /** Device domain */
    domain: string;

    /** Current state */
    state: string;

    /** Device attributes */
    attributes: Record<string, any>;

    /** Device capabilities */
    capabilities: DeviceCapabilities;
}

interface DeviceCapabilities {
    /** Supported features */
    features: string[];

    /** Supported commands */
    commands: string[];

    /** State attributes */
    attributes: {
        /** Attribute name */
        [key: string]: {
            /** Attribute type */
            type: 'string' | 'number' | 'boolean' | 'object';
            /** Attribute description */
            description: string;
            /** Optional value constraints */
            constraints?: {
                min?: number;
                max?: number;
                enum?: any[];
            };
        };
    };
}

interface AuthToken {
    /** Token value */
    token: string;

    /** Token type */
    type: 'bearer' | 'jwt';

    /** Expiration timestamp */
    expires_at: string;

    /** Token refresh info */
    refresh?: {
        token: string;
        expires_at: string;
    };
}

interface User {
    /** User ID */
    id: string;

    /** Username */
    username: string;

    /** User type */
    type: 'admin' | 'user' | 'service';

    /** User permissions */
    permissions: string[];
}

interface ToolError extends Error {
    /** Error code */
    code: string;

    /** HTTP status code */
    status: number;

    /** Error details */
    details?: Record<string, any>;
}

interface ValidationError {
    /** Error path */
    path: string;

    /** Error message */
    message: string;

    /** Error code */
    code: string;
}

interface ToolConfig {
    /** Enable/disable tool */
    enabled: boolean;

    /** Tool-specific settings */
    settings: Record<string, any>;

    /** Rate limiting */
    rate_limit?: {
        /** Max requests */
        max: number;
        /** Time window in seconds */
        window: number;
    };
}

interface SystemConfig {
    /** System name */
    name: string;

    /** Environment */
    environment: 'development' | 'production';

    /** Log level */
    log_level: 'debug' | 'info' | 'warn' | 'error';

    /** Tool configurations */
    tools: Record<string, ToolConfig>;
}