0xray 2.0.0

package/dist/integrations/base/ExampleIntegration.js

@@ -0,0 +1,181 @@
+/**
+ * Example Integration - Demonstrates using the BaseIntegration class
+ *
+ * This is a simple example showing how to create a custom integration
+ * that extends the BaseIntegration class.
+ *
+ * @version 1.0.0
+ * @since 2026-03-15
+ */
+import { BaseIntegration, createSimpleIntegration, } from "./index.js";
+/**
+ * Example custom integration
+ *
+ * Demonstrates how to extend BaseIntegration with custom logic.
+ */
+class ExampleIntegration extends BaseIntegration {
+    /** Custom property for this integration */
+    connectionString = "";
+    connected = false;
+    /**
+     * Create a new ExampleIntegration
+     *
+     * @param config - Optional configuration
+     */
+    constructor(config) {
+        super("example-integration", "1.0.0", {
+            enabled: true,
+            debug: false,
+            logLevel: "info",
+            ...config,
+        });
+    }
+    /**
+     * Set connection string
+     */
+    setConnectionString(connStr) {
+        this.connectionString = connStr;
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.connected;
+    }
+    // ==========================================================================
+    // Protected abstract method implementations
+    // ==========================================================================
+    /**
+     * Perform integration-specific initialization
+     */
+    async performInitialization() {
+        await this.log("info", "Starting initialization...");
+        // Simulate async initialization (e.g., connecting to a service)
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        if (this.connectionString) {
+            // Would connect to external service here
+            this.connected = true;
+            await this.log("success", "Connected to service");
+        }
+        // Emit custom event
+        this.emit("custom-initialized", { connected: this.connected });
+    }
+    /**
+     * Perform integration-specific shutdown
+     */
+    async performShutdown() {
+        await this.log("info", "Starting shutdown...");
+        // Simulate async cleanup
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        this.connected = false;
+        await this.log("success", "Shutdown complete");
+    }
+    /**
+     * Perform integration-specific health check
+     */
+    async performHealthCheck() {
+        if (!this.connected) {
+            return {
+                healthy: false,
+                message: "Not connected to service",
+                details: { connectionString: !!this.connectionString },
+            };
+        }
+        // In a real integration, you might ping the service here
+        return {
+            healthy: true,
+            message: "Service connection healthy",
+            details: { connected: true },
+        };
+    }
+}
+// ==========================================================================
+// Usage Examples
+// ==========================================================================
+/**
+ * Example 1: Using a custom integration class
+ */
+async function exampleCustomIntegration() {
+    console.log("\n--- Example 1: Custom Integration ---");
+    // Create integration
+    const integration = new ExampleIntegration({
+        debug: true,
+        logLevel: "debug",
+    });
+    // Set connection string
+    integration.setConnectionString("http://localhost:3000");
+    // Setup event listener
+    integration.on("initialized", (event) => {
+        console.log("Integration initialized event:", event.type);
+    });
+    // Initialize
+    await integration.initialize();
+    // Check health
+    const health = await integration.healthCheck();
+    console.log("Health check:", health);
+    // Get stats
+    const stats = integration.getStats();
+    console.log("Stats:", stats);
+    // Shutdown
+    await integration.shutdown();
+}
+/**
+ * Example 2: Using createSimpleIntegration factory
+ */
+async function exampleSimpleIntegration() {
+    console.log("\n--- Example 2: Simple Integration ---");
+    // Create a simple integration without subclassing
+    const simple = createSimpleIntegration("simple-integration", "1.0.0", 
+    // Custom health check
+    async () => ({
+        healthy: true,
+        message: "Always healthy",
+    }), 
+    // Custom shutdown
+    async () => {
+        console.log("Custom cleanup performed");
+    });
+    // Initialize
+    await simple.initialize();
+    // Check health
+    const health = await simple.healthCheck();
+    console.log("Health check:", health);
+    // Shutdown
+    await simple.shutdown();
+}
+/**
+ * Example 3: Error handling
+ */
+async function exampleErrorHandling() {
+    console.log("\n--- Example 3: Error Handling ---");
+    // Create integration that will fail to initialize
+    class FailingIntegration extends BaseIntegration {
+        constructor() {
+            super("failing-integration", "1.0.0");
+        }
+        async performInitialization() {
+            throw new Error("Connection refused");
+        }
+        async performShutdown() {
+            // Cleanup even on failure
+        }
+        async performHealthCheck() {
+            return { healthy: false, message: "Not initialized" };
+        }
+    }
+    const failing = new FailingIntegration();
+    try {
+        await failing.initialize();
+    }
+    catch (error) {
+        console.log("Caught expected error:", error instanceof Error ? error.message : error);
+    }
+}
+// Run examples if this file is executed directly
+// (In a real project, you would import and use the classes)
+// Export for use in other modules
+export { ExampleIntegration };
+// Example usage (uncomment to run):
+// exampleCustomIntegration().catch(console.error);
+// exampleSimpleIntegration().catch(console.error);
+// exampleErrorHandling().catch(console.error);

package/dist/integrations/base/Integration.js

@@ -0,0 +1,395 @@
+/**
+ * Base Integration Class
+ *
+ * Abstract base class providing common lifecycle management, event emission,
+ * configuration handling, and logging for all 0xRay integrations.
+ *
+ * @version 1.0.0
+ * @since 2026-03-15
+ */
+import { EventEmitter } from "events";
+import { frameworkLogger, generateJobId, } from "../../core/framework-logger.js";
+import { DEFAULT_INTEGRATION_CONFIG, createIntegrationStats, createUnhealthyResult, IntegrationNotInitializedError, IntegrationAlreadyInitializedError, IntegrationInitializationError, } 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 class BaseIntegration extends EventEmitter {
+    /** Unique name of the integration */
+    name;
+    /** Version of the integration */
+    version;
+    /** Current lifecycle status */
+    _status = "uninitialized";
+    /** Current configuration */
+    config;
+    /** Statistics tracking */
+    stats;
+    /** Start time for uptime calculation */
+    startTime = 0;
+    /** Job ID for current operation */
+    jobId;
+    /**
+     * Create a new base integration
+     *
+     * @param name - Unique name for this integration
+     * @param version - Version string
+     * @param initialConfig - Optional initial configuration
+     */
+    constructor(name, version, initialConfig) {
+        super();
+        this.name = name;
+        this.version = version;
+        this.config = { ...DEFAULT_INTEGRATION_CONFIG, ...initialConfig };
+        this.stats = createIntegrationStats();
+        this.jobId = generateJobId(`integration-${name}`);
+    }
+    // ==========================================================================
+    // IIntegration Implementation
+    // ==========================================================================
+    /**
+     * Get current integration status (readonly accessor)
+     */
+    get status() {
+        return this._status;
+    }
+    /**
+     * Initialize the integration
+     *
+     * Calls performInitialization() after setting up the base state.
+     * Handles errors and emits appropriate events.
+     *
+     * @param config - Optional partial configuration to merge
+     */
+    async initialize(config) {
+        // Validate not already initialized
+        if (this._status === "initialized" || this._status === "initializing") {
+            throw new IntegrationAlreadyInitializedError(this.name);
+        }
+        // Merge configuration
+        if (config) {
+            this.config = { ...this.config, ...config };
+        }
+        // Generate new job ID for initialization
+        this.jobId = generateJobId(`integration-${this.name}`);
+        // Update status
+        this._status = "initializing";
+        this.emitEvent("initializing", { config: this.config });
+        await this.log("info", `Initializing ${this.name} v${this.version}`);
+        try {
+            // Call subclass initialization
+            await this.performInitialization();
+            // Update status and stats
+            this._status = "initialized";
+            this.startTime = Date.now();
+            this.stats = createIntegrationStats();
+            this.emitEvent("initialized", { version: this.version });
+            await this.log("success", `${this.name} initialized successfully`);
+        }
+        catch (error) {
+            this._status = "error";
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.log("error", `Failed to initialize ${this.name}: ${errorMessage}`);
+            this.emitEvent("error", {
+                error: errorMessage
+            }, error instanceof Error ? error : undefined);
+            throw new IntegrationInitializationError(this.name, error instanceof Error ? error : new Error(errorMessage));
+        }
+    }
+    /**
+     * Gracefully shutdown the integration
+     *
+     * Calls performShutdown() to clean up resources.
+     *
+     * @example
+     * ```typescript
+     * // Using await
+     * await integration.shutdown();
+     * ```
+     */
+    async shutdown() {
+        if (this._status === "shutdown" || this._status === "uninitialized") {
+            return;
+        }
+        await this.log("info", `Shutting down ${this.name}...`);
+        this._status = "shutting-down";
+        this.emitEvent("shutting-down", {});
+        try {
+            // Call subclass shutdown
+            await this.performShutdown();
+            // Update status
+            this._status = "shutdown";
+            this.startTime = 0;
+            this.emitEvent("shutdown", {});
+            await this.log("success", `${this.name} shutdown complete`);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.log("error", `Error during shutdown of ${this.name}: ${errorMessage}`);
+            this.emitEvent("error", {
+                message: errorMessage,
+                phase: "shutdown"
+            }, error instanceof Error ? error : undefined);
+            // Still mark as shutdown even if there was an error
+            this._status = "shutdown";
+        }
+    }
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    async healthCheck() {
+        // Check if initialized
+        if (this._status !== "initialized") {
+            return createUnhealthyResult(`${this.name} is not initialized (status: ${this._status})`, { status: this._status });
+        }
+        // Call subclass health check
+        try {
+            const result = await this.performHealthCheck();
+            this.emitEvent("health-check", { healthy: result.healthy });
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return createUnhealthyResult(`Health check failed: ${errorMessage}`, {
+                error: errorMessage,
+            });
+        }
+    }
+    /**
+     * 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() {
+        // Calculate uptime
+        const uptime = this.startTime > 0 ? Date.now() - this.startTime : 0;
+        return {
+            ...this.stats,
+            uptime,
+        };
+    }
+    // ==========================================================================
+    // IEventedIntegration Implementation
+    // ==========================================================================
+    /**
+     * Get the event emitter for this integration
+     *
+     * Returns `this` since BaseIntegration extends EventEmitter.
+     *
+     * @returns The event emitter instance
+     */
+    getEventEmitter() {
+        return this;
+    }
+    // ==========================================================================
+    // Protected Methods for Subclasses
+    // ==========================================================================
+    /**
+     * Ensure the integration is initialized
+     *
+     * @throws IntegrationNotInitializedError if not initialized
+     */
+    ensureInitialized() {
+        if (this._status !== "initialized") {
+            throw new IntegrationNotInitializedError(this.name);
+        }
+    }
+    /**
+     * Record an error in statistics
+     *
+     * @param error - Optional error to record
+     */
+    recordError(error) {
+        this.stats.errors++;
+        if (this.config.debug && error) {
+            this.log("error", error.message).catch((e) => frameworkLogger.log("integration", "log-error-fallback", "error", { error: e }));
+        }
+    }
+    /**
+     * Update custom statistics
+     *
+     * @param customStats - Partial stats to merge
+     */
+    updateCustomStats(customStats) {
+        this.stats.custom = { ...this.stats.custom, ...customStats };
+    }
+    /**
+     * Get current configuration
+     *
+     * @returns Current configuration object (copy)
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration
+     *
+     * @param config - Partial configuration to merge
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        this.emitEvent("config-updated", { config: this.config });
+    }
+    // ==========================================================================
+    // Logging
+    // ==========================================================================
+    /**
+     * Log a message using the framework logger
+     *
+     * @param status - Log status level
+     * @param message - Message to log
+     * @param details - Optional details object
+     */
+    async log(status, message, details) {
+        // Only log if enabled and level is appropriate
+        if (!this.config.enabled) {
+            return;
+        }
+        const statusToLevel = {
+            error: 0,
+            warning: 1,
+            warn: 1,
+            info: 2,
+            debug: 3,
+            success: 2, // map success to info level
+        };
+        const currentLevel = statusToLevel[this.config.logLevel] ?? 2;
+        const statusLevel = statusToLevel[status] ?? 2;
+        // Skip if below log level
+        if (statusLevel > currentLevel && status !== "success") {
+            return;
+        }
+        // Map 'success' to 'info' for framework logger
+        const loggerStatus = status === "success" ? "info" : status;
+        try {
+            await frameworkLogger.log(this.name, message, loggerStatus, {
+                ...details,
+                version: this.version,
+                status: this._status,
+                jobId: this.jobId,
+            }, this.jobId);
+        }
+        catch {
+            // Silent fail - logging should never break application
+        }
+    }
+    // ==========================================================================
+    // Event Emission
+    // ==========================================================================
+    /**
+     * Emit a typed integration event
+     *
+     * @param type - Event type
+     * @param data - Event data
+     * @param error - Optional error
+     */
+    emitEvent(type, data = {}, error) {
+        const event = {
+            type,
+            timestamp: Date.now(),
+            data,
+            ...(error ? { error } : {}),
+        };
+        // Emit specific event
+        this.emit(type, event);
+        // Also emit generic 'any' event
+        this.emit("event", event);
+    }
+    // ==========================================================================
+    // Static Methods
+    // ==========================================================================
+    /**
+     * Check if an object is a BaseIntegration instance
+     *
+     * @param value - Value to check
+     * @returns True if value is a BaseIntegration
+     */
+    static isBaseIntegration(value) {
+        return value instanceof 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 function createSimpleIntegration(name, version, healthCheck, shutdown = async () => { }) {
+    class SimpleIntegration extends BaseIntegration {
+        async performInitialization() {
+            // No-op for simple integration
+        }
+        async performShutdown() {
+            await shutdown();
+        }
+        async performHealthCheck() {
+            return healthCheck();
+        }
+    }
+    return new SimpleIntegration(name, version);
+}