0xray 3.4.2 → 3.4.3

package/dist/integrations/base/Integration.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Base Integration Class
+ *
+ * Abstract base class providing common lifecycle management, event emission,
+ * configuration handling, and logging for all 0xRay integrations.
+ *
+ * @since 2026-03-15
+ */
+import { EventEmitter } from "events";
+import type { LogStatus } from "../../core/framework-logger.js";
+import { type IntegrationConfig, type IntegrationStatus, type IntegrationStats, type HealthResult, type IntegrationEvent, type IntegrationEventType, type IIntegration, type IEventedIntegration, type LogLevel } from "./types.js";
+/**
+ * Abstract base class for all 0xRay integrations
+ *
+ * Provides:
+ * - Lifecycle management (initialize/shutdown)
+ * - Configuration handling with defaults
+ * - Event emission for integration events
+ * - Common statistics tracking (uptime, errors)
+ * - Logging integration with framework logger
+ *
+ * @example
+ * ```typescript
+ * class MyIntegration extends BaseIntegration {
+ *   constructor() {
+ *     super('my-integration', '1.0.0');
+ *   }
+ *
+ *   protected async performInitialization(): Promise<void> {
+ *     // Custom initialization logic
+ *   }
+ *
+ *   protected async performShutdown(): Promise<void> {
+ *     // Custom cleanup logic
+ *   }
+ *
+ *   protected async performHealthCheck(): Promise<HealthResult> {
+ *     return { healthy: true, message: 'OK' };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseIntegration extends EventEmitter implements IIntegration, IEventedIntegration {
+    /** Unique name of the integration */
+    readonly name: string;
+    /** Version of the integration */
+    readonly version: string;
+    /** Current lifecycle status */
+    protected _status: IntegrationStatus;
+    /** Current configuration */
+    protected config: IntegrationConfig;
+    /** Statistics tracking */
+    protected stats: IntegrationStats;
+    /** Start time for uptime calculation */
+    protected startTime: number;
+    /** Job ID for current operation */
+    protected jobId: string;
+    /**
+     * Create a new base integration
+     *
+     * @param name - Unique name for this integration
+     * @param version - Version string
+     * @param initialConfig - Optional initial configuration
+     */
+    constructor(name: string, version: string, initialConfig?: Partial<IntegrationConfig>);
+    /**
+     * Get current integration status (readonly accessor)
+     */
+    get status(): IntegrationStatus;
+    /**
+     * Initialize the integration
+     *
+     * Calls performInitialization() after setting up the base state.
+     * Handles errors and emits appropriate events.
+     *
+     * @param config - Optional partial configuration to merge
+     */
+    initialize(config?: Partial<IntegrationConfig>): Promise<void>;
+    /**
+     * Gracefully shutdown the integration
+     *
+     * Calls performShutdown() to clean up resources.
+     *
+     * @example
+     * ```typescript
+     * // Using await
+     * await integration.shutdown();
+     * ```
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Perform a health check
+     *
+     * Default implementation checks status and calls performHealthCheck().
+     * Subclasses should override performHealthCheck() for custom checks.
+     *
+     * @returns Health result indicating integration health
+     *
+     * @example
+     * ```typescript
+     * const health = await integration.healthCheck();
+     * if (!health.healthy) {
+     *   console.error('Integration unhealthy:', health.message);
+     * }
+     * ```
+     */
+    healthCheck(): Promise<HealthResult>;
+    /**
+     * Get current integration statistics
+     *
+     * Calculates uptime since initialization and includes error count.
+     *
+     * @returns Current stats object
+     *
+     * @example
+     * ```typescript
+     * const stats = integration.getStats();
+     * console.log(`Uptime: ${stats.uptime}ms, Errors: ${stats.errors}`);
+     * ```
+     */
+    getStats(): IntegrationStats;
+    /**
+     * Get the event emitter for this integration
+     *
+     * Returns `this` since BaseIntegration extends EventEmitter.
+     *
+     * @returns The event emitter instance
+     */
+    getEventEmitter(): EventEmitter;
+    /**
+     * Ensure the integration is initialized
+     *
+     * @throws IntegrationNotInitializedError if not initialized
+     */
+    protected ensureInitialized(): void;
+    /**
+     * Record an error in statistics
+     *
+     * @param error - Optional error to record
+     */
+    protected recordError(error?: Error): void;
+    /**
+     * Update custom statistics
+     *
+     * @param customStats - Partial stats to merge
+     */
+    protected updateCustomStats(customStats: Record<string, unknown>): void;
+    /**
+     * Get current configuration
+     *
+     * @returns Current configuration object (copy)
+     */
+    protected getConfig(): IntegrationConfig;
+    /**
+     * Update configuration
+     *
+     * @param config - Partial configuration to merge
+     */
+    protected updateConfig(config: Partial<IntegrationConfig>): void;
+    /**
+     * Log a message using the framework logger
+     *
+     * @param status - Log status level
+     * @param message - Message to log
+     * @param details - Optional details object
+     */
+    protected log(status: LogStatus, message: string, details?: Record<string, unknown>): Promise<void>;
+    /**
+     * Emit a typed integration event
+     *
+     * @param type - Event type
+     * @param data - Event data
+     * @param error - Optional error
+     */
+    protected emitEvent(type: IntegrationEventType, data?: Record<string, unknown>, error?: Error): void;
+    /**
+     * Perform integration-specific initialization
+     *
+     * Called during initialize() after base setup.
+     * Subclasses should implement custom initialization logic here.
+     *
+     * @example
+     * ```typescript
+     * protected async performInitialization(): Promise<void> {
+     *   // Connect to external service
+     *   await this.connect();
+     *
+     *   // Setup event handlers
+     *   this.on('data', this.handleData);
+     * }
+     * ```
+     */
+    protected abstract performInitialization(): Promise<void>;
+    /**
+     * Perform integration-specific shutdown
+     *
+     * Called during shutdown() for cleanup.
+     * Subclasses should implement cleanup logic here.
+     *
+     * @example
+     * ```typescript
+     * protected async performShutdown(): Promise<void> {
+     *   // Remove event handlers
+     *   this.off('data', this.handleData);
+     *
+     *   // Close connections
+     *   await this.disconnect();
+     * }
+     * ```
+     */
+    protected abstract performShutdown(): Promise<void>;
+    /**
+     * Perform integration-specific health check
+     *
+     * Called by healthCheck() to determine integration health.
+     * Subclasses should implement custom health checks here.
+     *
+     * @returns Health result
+     *
+     * @example
+     * ```typescript
+     * protected async performHealthCheck(): Promise<HealthResult> {
+     *   const connected = await this.isConnected();
+     *
+     *   if (connected) {
+     *     return { healthy: true, message: 'Connection active' };
+     *   }
+     *
+     *   return { healthy: false, message: 'Not connected' };
+     * }
+     * ```
+     */
+    protected abstract performHealthCheck(): Promise<HealthResult>;
+    /**
+     * Check if an object is a BaseIntegration instance
+     *
+     * @param value - Value to check
+     * @returns True if value is a BaseIntegration
+     */
+    static isBaseIntegration(value: unknown): value is BaseIntegration;
+}
+/**
+ * Create a simple integration with minimal implementation
+ *
+ * Useful for testing or simple integrations that don't need much logic.
+ *
+ * @param name - Integration name
+ * @param version - Integration version
+ * @param healthCheck - Custom health check function
+ * @param shutdown - Custom shutdown function
+ * @returns New integration instance
+ *
+ * @example
+ * ```typescript
+ * const simple = createSimpleIntegration(
+ *   'simple',
+ *   '1.0.0',
+ *   async () => ({ healthy: true, message: 'OK' }),
+ *   async () => {}
+ * );
+ *
+ * await simple.initialize();
+ * ```
+ */
+export declare function createSimpleIntegration(name: string, version: string, healthCheck: () => Promise<HealthResult>, shutdown?: () => Promise<void>): BaseIntegration;
+export type { IntegrationConfig, IntegrationStatus, IntegrationStats, HealthResult, IntegrationEvent, IntegrationEventType, IIntegration, IEventedIntegration, LogLevel, };

package/dist/integrations/base/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Integration Base Module
+ *
+ * Common interfaces and base class for 0xRay integrations.
+ *
+ * @since 2026-03-15
+ */
+export * from "./types.js";
+export * from "./Integration.js";
+export * from "./registry.js";
+export * from "./ExampleIntegration.js";

package/dist/integrations/base/registry.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Integration Registry
+ *
+ * Central registry for managing 0xRay integrations.
+ * Provides registration, loading, unloading, health checking, and stats retrieval.
+ *
+ * @since 2026-03-15
+ */
+import { EventEmitter } from "events";
+import { type IIntegration, type IntegrationConfig, type HealthResult, type IntegrationStats, type IntegrationStatus } from "./types.js";
+/**
+ * Integration configuration from config file
+ */
+export interface IntegrationsConfig {
+    integrations: Record<string, {
+        enabled: boolean;
+        config?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Registry event types
+ */
+export type RegistryEventType = "integration-registered" | "integration-unregistered" | "integration-loaded" | "integration-unloaded" | "load-complete" | "unload-complete" | "health-check-complete" | "error";
+/**
+ * Registry event
+ */
+export interface RegistryEvent {
+    type: RegistryEventType;
+    timestamp: number;
+    integrationName?: string | undefined;
+    data?: Record<string, unknown> | undefined;
+    error?: Error | undefined;
+}
+/**
+ * Loaded integration metadata
+ */
+interface LoadedIntegration {
+    instance: IIntegration;
+    config: IntegrationConfig;
+    loadedAt: number;
+}
+/**
+ * Error thrown when integration is not found in registry
+ */
+export declare class IntegrationNotFoundError extends Error {
+    constructor(integrationName: string);
+}
+/**
+ * Error thrown when integration is already registered
+ */
+export declare class IntegrationAlreadyRegisteredError extends Error {
+    constructor(integrationName: string);
+}
+/**
+ * Integration Registry
+ *
+ * Manages registration, loading, and lifecycle of integrations.
+ *
+ * @example
+ * ```typescript
+ * const registry = new IntegrationRegistry();
+ *
+ * // Register an integration
+ * registry.register('my-integration', new MyIntegration());
+ *
+ * // Get an integration
+ * const integration = registry.get('my-integration');
+ *
+ * // List all integrations
+ * const names = registry.list();
+ *
+ * // Load from config
+ * await registry.loadAll({
+ *   integrations: {
+ *     'my-integration': { enabled: true }
+ *   }
+ * });
+ * ```
+ */
+export declare class IntegrationRegistry extends EventEmitter {
+    /** Map of registered integrations (name -> instance) */
+    private registeredIntegrations;
+    /** Map of loaded integrations (name -> metadata) */
+    private loadedIntegrations;
+    /** Job ID for registry operations */
+    private jobId;
+    /**
+     * Create a new IntegrationRegistry
+     */
+    constructor();
+    /**
+     * Register an integration with the registry
+     *
+     * @param name - Unique name for the integration
+     * @param integration - Integration instance to register
+     * @throws IntegrationAlreadyRegisteredError if name already registered
+     */
+    register(name: string, integration: IIntegration): void;
+    /**
+     * Unregister an integration from the registry
+     *
+     * @param name - Name of the integration to unregister
+     * @throws IntegrationNotFoundError if integration not found
+     */
+    unregister(name: string): void;
+    /**
+     * Get an integration by name
+     *
+     * @param name - Name of the integration
+     * @returns Integration instance or undefined if not found
+     */
+    get(name: string): IIntegration | undefined;
+    /**
+     * Get a loaded integration by name
+     *
+     * @param name - Name of the loaded integration
+     * @returns Loaded integration metadata or undefined if not loaded
+     */
+    getLoaded(name: string): LoadedIntegration | undefined;
+    /**
+     * List all registered integration names
+     *
+     * @returns Array of integration names
+     */
+    list(): string[];
+    /**
+     * List all loaded integration names
+     *
+     * @returns Array of loaded integration names
+     */
+    listLoaded(): string[];
+    /**
+     * Check if an integration is registered
+     *
+     * @param name - Name to check
+     * @returns true if registered
+     */
+    isRegistered(name: string): boolean;
+    /**
+     * Check if an integration is loaded
+     *
+     * @param name - Name to check
+     * @returns true if loaded
+     */
+    isLoaded(name: string): boolean;
+    /**
+     * Load an integration by name
+     *
+     * @param name - Integration name
+     * @param config - Optional integration configuration
+     * @throws IntegrationNotFoundError if integration not registered
+     */
+    load(name: string, config?: Partial<IntegrationConfig>): Promise<void>;
+    /**
+     * Unload an integration by name
+     *
+     * @param name - Integration name
+     * @throws IntegrationNotFoundError if integration not loaded
+     */
+    unload(name: string): Promise<void>;
+    /**
+     * Load all enabled integrations from configuration
+     *
+     * @param config - Integrations configuration
+     */
+    loadAll(config: IntegrationsConfig): Promise<void>;
+    /**
+     * Unload all loaded integrations
+     */
+    unloadAll(): Promise<void>;
+    /**
+     * Get health status of all loaded integrations
+     *
+     * @returns Record of integration names to health results
+     */
+    healthCheckAll(): Promise<Record<string, HealthResult>>;
+    /**
+     * Get health status of a specific integration
+     *
+     * @param name - Integration name
+     * @returns Health result
+     * @throws IntegrationNotFoundError if integration not loaded
+     */
+    healthCheck(name: string): Promise<HealthResult>;
+    /**
+     * Get statistics from all loaded integrations
+     *
+     * @returns Record of integration names to stats
+     */
+    getAllStats(): Record<string, IntegrationStats>;
+    /**
+     * Get statistics from a specific integration
+     *
+     * @param name - Integration name
+     * @returns Integration stats
+     * @throws IntegrationNotFoundError if integration not loaded
+     */
+    getStats(name: string): IntegrationStats;
+    /**
+     * Get status of a specific integration
+     *
+     * @param name - Integration name
+     * @returns Integration status
+     */
+    getStatus(name: string): IntegrationStatus | undefined;
+    /**
+     * Get all integration statuses
+     *
+     * @returns Record of integration names to statuses
+     */
+    getAllStatuses(): Record<string, IntegrationStatus>;
+    /**
+     * Clear all registered integrations (not loaded ones)
+     */
+    clear(): void;
+    /**
+     * Get registry statistics
+     *
+     * @returns Registry statistics
+     */
+    getRegistryStats(): {
+        registered: number;
+        loaded: number;
+        byStatus: Record<IntegrationStatus, number>;
+    };
+    /**
+     * Emit a registry event
+     */
+    private emitEvent;
+}
+/**
+ * Integration discovery result
+ */
+export interface DiscoveredIntegration {
+    name: string;
+    path: string;
+    module: unknown;
+}
+/**
+ * Auto-discover integrations from directory index files
+ *
+ * This function scans the integrations directory for integration modules
+ * and returns their discovered information.
+ *
+ * @param integrationsPath - Path to integrations directory
+ * @returns Array of discovered integrations
+ *
+ * @example
+ * ```typescript
+ * const discovered = await discoverIntegrations('./src/integrations');
+ * for (const d of discovered) {
+ *   console.log(`Found: ${d.name} at ${d.path}`);
+ * }
+ * ```
+ */
+export declare function discoverIntegrations(integrationsPath: string): Promise<DiscoveredIntegration[]>;
+/**
+ * Auto-register integrations from discovered modules
+ *
+ * @param registry - Registry instance to register with
+ * @param integrationsPath - Path to integrations directory
+ * @returns Number of integrations registered
+ *
+ * @example
+ * ```typescript
+ * const registry = new IntegrationRegistry();
+ * const count = await autoRegisterIntegrations(registry, './src/integrations');
+ * console.log(`Registered ${count} integrations`);
+ * ```
+ */
+export declare function autoRegisterIntegrations(registry: IntegrationRegistry, integrationsPath: string): Promise<number>;
+export {};