@bsb/base 9.0.0

package/lib/scripts/generate-plugin-json.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * BSB Plugin Metadata Generation Script
+ *
+ * Discovers publishable core plugins and generates plugin metadata JSON files.
+ *
+ * Usage:
+ *   npm run generate-plugin-json
+ *
+ * Output:
+ *   - lib/schemas/{plugin-name}.plugin.json
+ *   - bsb-plugin.json (registry-facing root manifest)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePluginMetadata = main;
+const fs = require("fs");
+const path = require("path");
+const PluginConfig_1 = require("../base/PluginConfig");
+const CORE_PLUGIN_OVERRIDES = {
+    'config-default': {
+        name: 'config-default',
+        description: 'Default configuration plugin for BSB profile and plugin resolution.',
+        tags: ['core', 'config', 'default'],
+        documentation: ['./docs/core-plugins/config-default.md'],
+    },
+    'events-default': {
+        name: 'events-default',
+        description: 'In-process events plugin with emit, returnable, and broadcast support.',
+        tags: ['core', 'events', 'default'],
+        documentation: ['./docs/core-plugins/events-default.md'],
+    },
+    'observable-default': {
+        name: 'observable-default',
+        description: 'Default console-based observable plugin for logs and diagnostics.',
+        tags: ['core', 'observable', 'default'],
+        documentation: ['./docs/core-plugins/observable-default.md'],
+    },
+};
+/**
+ * Discover all plugin modules in the lib directory.
+ * Looks for plugin entry points in lib/plugins/{plugin-name}/index.js
+ */
+function discoverPlugins(libDir) {
+    const pluginPaths = [];
+    const pluginsDir = path.join(libDir, 'plugins');
+    if (!fs.existsSync(pluginsDir)) {
+        return pluginPaths;
+    }
+    const pluginDirs = fs.readdirSync(pluginsDir, { withFileTypes: true })
+        .filter(dirent => dirent.isDirectory())
+        .map(dirent => dirent.name);
+    for (const dir of pluginDirs) {
+        const indexPath = path.join(pluginsDir, dir, 'index.js');
+        if (fs.existsSync(indexPath)) {
+            pluginPaths.push(indexPath);
+        }
+    }
+    return pluginPaths;
+}
+function shouldPublishPlugin(pluginId) {
+    if (pluginId.startsWith('service-')) {
+        return false;
+    }
+    return Object.prototype.hasOwnProperty.call(CORE_PLUGIN_OVERRIDES, pluginId);
+}
+function buildRootManifestEntries(pluginMetaFiles, packageJson) {
+    return pluginMetaFiles.map((meta) => {
+        const id = meta.id;
+        const entry = {
+            id,
+            name: meta.name,
+            basePath: './',
+            description: meta.description || '',
+            tags: meta.tags || [],
+            documentation: meta.documentation || [],
+            pluginPath: `src/plugins/${id}/`,
+        };
+        if (meta.image) {
+            entry.image = meta.image;
+        }
+        const repoUrl = meta.repository || packageJson.repository?.url || packageJson.repository || '';
+        if (repoUrl) {
+            entry.links = { github: typeof repoUrl === 'string' ? repoUrl : '' };
+        }
+        return entry;
+    });
+}
+/**
+ * Main generation function.
+ */
+async function main() {
+    const projectRoot = path.resolve(__dirname, '..', '..');
+    const libDir = path.join(projectRoot, 'lib');
+    const schemasDir = path.join(libDir, 'schemas');
+    // Ensure lib directory exists (must run after build)
+    if (!fs.existsSync(libDir)) {
+        // eslint-disable-next-line no-console
+        console.error('Error: lib directory not found. Run npm run build first.');
+        process.exit(1);
+    }
+    // Create schemas output directory
+    if (!fs.existsSync(schemasDir)) {
+        fs.mkdirSync(schemasDir, { recursive: true });
+    }
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    let packageJson = {};
+    if (fs.existsSync(packageJsonPath)) {
+        packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    }
+    // Discover all plugins
+    const pluginPaths = discoverPlugins(libDir);
+    if (pluginPaths.length === 0) {
+        // eslint-disable-next-line no-console
+        console.log('No plugins found to generate metadata from.');
+        return;
+    }
+    // eslint-disable-next-line no-console
+    console.log(`Found ${pluginPaths.length} plugin(s) to generate metadata from...`);
+    let generatedCount = 0;
+    let errorCount = 0;
+    const generatedPluginMetadata = [];
+    // Process each plugin
+    for (const pluginPath of pluginPaths) {
+        try {
+            const pluginName = path.basename(path.dirname(pluginPath));
+            if (!shouldPublishPlugin(pluginName)) {
+                continue;
+            }
+            // Import the plugin module
+            const pluginModule = await Promise.resolve(`${pluginPath}`).then(s => require(s));
+            // Look for Plugin export
+            if (!pluginModule.Plugin) {
+                continue;
+            }
+            const Plugin = pluginModule.Plugin;
+            const metadata = (Plugin.Config && Plugin.Config.metadata)
+                ? Plugin.Config.metadata
+                : CORE_PLUGIN_OVERRIDES[pluginName];
+            if (!metadata) {
+                continue;
+            }
+            // Read version from package.json if available
+            const version = packageJson.version || metadata.version || '1.0.0';
+            // Create plugin metadata object - only include fields with actual values
+            const pluginMetadata = {
+                id: pluginName,
+                name: metadata.name,
+                version,
+                description: metadata.description || '',
+                category: (0, PluginConfig_1.getCategoryFromPluginName)(pluginName),
+                tags: metadata.tags || [],
+                documentation: Array.isArray(metadata.documentation) ? metadata.documentation : [],
+                dependencies: [],
+            };
+            // Only include optional fields if they have real values
+            if (metadata.author)
+                pluginMetadata.author = metadata.author;
+            if (metadata.license)
+                pluginMetadata.license = metadata.license;
+            if (metadata.homepage)
+                pluginMetadata.homepage = metadata.homepage;
+            if (metadata.repository)
+                pluginMetadata.repository = metadata.repository;
+            if (metadata.image)
+                pluginMetadata.image = metadata.image;
+            // Read auto-detected dependencies and config schema from schema JSON
+            const schemaJsonPath = path.join(schemasDir, `${pluginName}.json`);
+            if (fs.existsSync(schemaJsonPath)) {
+                try {
+                    const schema = JSON.parse(fs.readFileSync(schemaJsonPath, 'utf-8'));
+                    if (Array.isArray(schema.dependencies) && schema.dependencies.length > 0) {
+                        pluginMetadata.dependencies = schema.dependencies;
+                    }
+                    if (schema.configSchema && typeof schema.configSchema === 'object') {
+                        pluginMetadata.configSchema = schema.configSchema;
+                    }
+                }
+                catch {
+                    // Non-fatal, skip malformed schema
+                }
+            }
+            // Write to file
+            const outputPath = path.join(schemasDir, `${pluginName}.plugin.json`);
+            fs.writeFileSync(outputPath, JSON.stringify(pluginMetadata, null, 2), 'utf-8');
+            generatedPluginMetadata.push(pluginMetadata);
+            // eslint-disable-next-line no-console
+            console.log(`  Generated metadata for ${metadata.name} (v${version})`);
+            generatedCount++;
+        }
+        catch (error) {
+            errorCount++;
+            // eslint-disable-next-line no-console
+            console.error(`  Error generating metadata for ${path.basename(path.dirname(pluginPath))}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Generate root bsb-plugin.json manifest for registry publish workflow
+    if (generatedPluginMetadata.length > 0) {
+        const rootPluginJson = {
+            nodejs: buildRootManifestEntries(generatedPluginMetadata, packageJson),
+        };
+        fs.writeFileSync(path.join(projectRoot, 'bsb-plugin.json'), JSON.stringify(rootPluginJson, null, 2), 'utf-8');
+    }
+    // eslint-disable-next-line no-console
+    console.log(`\nMetadata generation complete: ${generatedCount} generated, ${errorCount} errors`);
+    // eslint-disable-next-line no-console
+    console.log(`Metadata files written to: ${schemasDir}`);
+    if (errorCount > 0) {
+        process.exit(1);
+    }
+}
+// Run if called directly
+if (require.main === module) {
+    main().catch(error => {
+        // eslint-disable-next-line no-console
+        console.error('Fatal error during metadata generation:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=generate-plugin-json.js.map

package/lib/scripts/generate-plugin-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-plugin-json.js","sourceRoot":"","sources":["../../src/scripts/generate-plugin-json.ts"],"names":[],"mappings":"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"}

package/lib/serviceBase/config.d.ts

@@ -0,0 +1,83 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { BSBConfig } from "../base";
+import { DEBUG_MODE, DTrace, EventsConfig, LoadedPlugin, ObservableConfig, PluginDefinition, PluginType, Observable } from "../interfaces";
+import { SBObservable } from "./observable";
+import { SBPlugins } from "./plugins";
+/**
+ * BSB Config Controller
+ *
+ * This class is responsible for managing the configuration in the BSB framework.
+ * If you have a specific way of managing configuration, you can extend this class and then use your own class when creating the ServiceBase instance.
+ *
+ * @group Config
+ * @category Core
+ */
+export declare class SBConfig {
+    private static readonly DEFAULT_CONFIG_ENV_KEYS;
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBConfig.html | API: SBConfig}
+     */
+    private mode;
+    private appId;
+    private cwd;
+    private sbPlugins;
+    private sbObservable;
+    private observableBackend;
+    private configPlugin;
+    private createObservable;
+    constructor(appId: string, mode: DEBUG_MODE, cwd: string, sbObservable: SBObservable, sbPlugins: SBPlugins, createObservable: (trace: DTrace, pluginName: string, attributes?: Record<string, string | number | boolean>) => Observable);
+    private getConfigPluginEnvSubset;
+    private resolveConfigPluginConfig;
+    private isFlatJsonSchemaProperty;
+    private validateConfigPluginSchemaShape;
+    getPluginConfig(trace: DTrace, pluginType: PluginType, name: string): Promise<object | null>;
+    getServicePlugins(trace: DTrace): Promise<Record<string, PluginDefinition>>;
+    getEventsPlugins(trace: DTrace): Promise<Record<string, EventsConfig>>;
+    getObservablePlugins(trace: DTrace): Promise<Record<string, ObservableConfig>>;
+    getServicePluginDefinition(trace: DTrace, pluginName: string): Promise<{
+        name: string;
+        enabled: boolean;
+    }>;
+    /**
+     * Dispose config subsystem
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBConfig.html#dispose | API: SBConfig.dispose}
+     */
+    dispose(): void;
+    private configPackage;
+    private configPluginName;
+    /**
+     * Set the active config plugin implementation
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBConfig.html#setConfigPlugin | API: SBConfig.setConfigPlugin}
+     */
+    setConfigPlugin(reference: LoadedPlugin<"config">): Promise<BSBConfig<any>>;
+    /**
+     * Initialize config plugin (default or loaded)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBConfig.html#init | API: SBConfig.init}
+     */
+    init(): Promise<void>;
+}

package/lib/serviceBase/config.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SBConfig = void 0;
+const base_1 = require("../base");
+const interfaces_1 = require("../interfaces");
+const index_1 = require("../plugins/config-default/index");
+const zod_1 = require("zod");
+/**
+ * @hidden
+ */
+function internalTrace(span) {
+    return (0, interfaces_1.createFakeDTrace)("serviceBase/SBConfig", span);
+}
+/**
+ * BSB Config Controller
+ *
+ * This class is responsible for managing the configuration in the BSB framework.
+ * If you have a specific way of managing configuration, you can extend this class and then use your own class when creating the ServiceBase instance.
+ *
+ * @group Config
+ * @category Core
+ */
+class SBConfig {
+    static DEFAULT_CONFIG_ENV_KEYS = ["BSB_PROFILE", "BSB_CONFIG_FILE"];
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBConfig.html | API: SBConfig}
+     */
+    mode = "development";
+    appId;
+    cwd;
+    sbPlugins;
+    sbObservable;
+    observableBackend;
+    configPlugin;
+    createObservable;
+    constructor(appId, mode, cwd, sbObservable, sbPlugins, createObservable) {
+        this.appId = appId;
+        this.mode = mode;
+        this.cwd = cwd;
+        this.sbObservable = sbObservable;
+        this.sbPlugins = sbPlugins;
+        this.createObservable = createObservable;
+        const defaultConfigSchema = new index_1.Config(cwd, cwd, cwd, "config-default").validationSchema;
+        const defaultConfig = this.resolveConfigPluginConfig(defaultConfigSchema, SBConfig.DEFAULT_CONFIG_ENV_KEYS);
+        this.observableBackend = new base_1.ObservableBackend(mode, appId, "sb-config", sbObservable);
+        this.configPlugin = new index_1.Plugin({
+            appId,
+            mode,
+            pluginName: "sb-config",
+            cwd,
+            packageCwd: cwd,
+            pluginCwd: cwd,
+            config: defaultConfig,
+            sbObservable,
+            pluginVersion: "0.0.0",
+        });
+    }
+    getConfigPluginEnvSubset(validationSchema, fallbackKeys = []) {
+        const scopedEnv = {};
+        const allowedKeys = new Set(fallbackKeys);
+        if (!base_1.Tools.isNullOrUndefined(validationSchema)) {
+            const jsonSchema = zod_1.z.toJSONSchema(validationSchema);
+            if (jsonSchema.type === "object" && base_1.Tools.isObject(jsonSchema.properties)) {
+                Object.keys(jsonSchema.properties).forEach((key) => allowedKeys.add(key));
+            }
+        }
+        for (const key of allowedKeys) {
+            const value = process.env[key];
+            if (typeof value === "string") {
+                scopedEnv[key] = value;
+            }
+        }
+        return scopedEnv;
+    }
+    resolveConfigPluginConfig(validationSchema, fallbackKeys = []) {
+        if (base_1.Tools.isNullOrUndefined(validationSchema)) {
+            return undefined;
+        }
+        const scopedEnv = this.getConfigPluginEnvSubset(validationSchema, fallbackKeys);
+        return validationSchema.parse(scopedEnv);
+    }
+    isFlatJsonSchemaProperty(schema) {
+        if (!schema || typeof schema !== "object")
+            return false;
+        const t = schema.type;
+        if (t === "object" || t === "array")
+            return false;
+        if (Array.isArray(t) && (t.includes("object") || t.includes("array")))
+            return false;
+        if (Array.isArray(schema.oneOf) && schema.oneOf.some((x) => !this.isFlatJsonSchemaProperty(x)))
+            return false;
+        if (Array.isArray(schema.anyOf) && schema.anyOf.some((x) => !this.isFlatJsonSchemaProperty(x)))
+            return false;
+        return true;
+    }
+    validateConfigPluginSchemaShape(trace, validationSchema) {
+        const obs = this.createObservable(trace, "config");
+        const jsonSchema = zod_1.z.toJSONSchema(validationSchema);
+        if (jsonSchema?.type !== "object") {
+            throw new base_1.BSBError(obs.trace, "Config plugin schema must be an object or omitted");
+        }
+        const properties = jsonSchema?.properties || {};
+        for (const [key, propSchema] of Object.entries(properties)) {
+            if (!this.isFlatJsonSchemaProperty(propSchema)) {
+                throw new base_1.BSBError(obs.trace, "Config plugin schema property {key} must be flat (no object/array)", { key });
+            }
+        }
+    }
+    async getPluginConfig(trace, pluginType, name) {
+        const obs = this.createObservable(trace, "config");
+        return await this.configPlugin.getPluginConfig(obs, pluginType, name);
+    }
+    async getServicePlugins(trace) {
+        const obs = this.createObservable(trace, "config");
+        return await this.configPlugin.getServicePlugins(obs);
+    }
+    async getEventsPlugins(trace) {
+        const obs = this.createObservable(trace, "config");
+        return await this.configPlugin.getEventsPlugins(obs);
+    }
+    async getObservablePlugins(trace) {
+        const obs = this.createObservable(trace, "config");
+        return await this.configPlugin.getObservablePlugins(obs);
+    }
+    async getServicePluginDefinition(trace, pluginName) {
+        const obs = this.createObservable(trace, "config");
+        return await this.configPlugin.getServicePluginDefinition(obs, pluginName);
+    }
+    /**
+     * Dispose config subsystem
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBConfig.html#dispose | API: SBConfig.dispose}
+     */
+    dispose() {
+        (0, base_1.SmartFunctionCallSync)(this.configPlugin, this.configPlugin.dispose);
+    }
+    configPackage;
+    configPluginName = "config-default";
+    /**
+     * Set the active config plugin implementation
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBConfig.html#setConfigPlugin | API: SBConfig.setConfigPlugin}
+     */
+    async setConfigPlugin(reference) {
+        const tTrace = internalTrace(`setConfigPlugin`);
+        if (reference.serviceConfig && !base_1.Tools.isNullOrUndefined(reference.serviceConfig.validationSchema)) {
+            this.validateConfigPluginSchemaShape(tTrace, reference.serviceConfig.validationSchema);
+        }
+        const pluginConfig = this.resolveConfigPluginConfig(reference.serviceConfig?.validationSchema);
+        this.configPlugin = new reference.plugin({
+            appId: this.appId,
+            mode: this.mode,
+            pluginName: reference.name,
+            cwd: this.cwd,
+            packageCwd: reference.packageCwd,
+            pluginCwd: reference.pluginCwd,
+            config: pluginConfig,
+            sbObservable: this.sbObservable,
+            pluginVersion: reference.version,
+        });
+        this.observableBackend.info(tTrace, "Adding {pluginName} as config", {
+            pluginName: reference.name,
+        });
+        this.observableBackend.debug(tTrace, `Init: {name}`, {
+            name: this.configPluginName,
+        });
+        const obs = this.createObservable(tTrace, "config");
+        await (0, base_1.SmartFunctionCallAsync)(this.configPlugin, this.configPlugin.init, obs);
+        this.observableBackend.info(tTrace, `Init: {name}: OK`, {
+            name: this.configPluginName,
+        });
+        return this.configPlugin;
+    }
+    /**
+     * Initialize config plugin (default or loaded)
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBConfig.html#init | API: SBConfig.init}
+     */
+    async init() {
+        const tTrace = internalTrace(`init`);
+        if (base_1.Tools.isString(process.env.BSB_CONFIG_PLUGIN) &&
+            process.env.BSB_CONFIG_PLUGIN.startsWith("config-")) {
+            this.configPluginName = process.env.BSB_CONFIG_PLUGIN;
+            if (base_1.Tools.isString(process.env.BSB_CONFIG_PLUGIN_PACKAGE)) {
+                this.configPackage = process.env.BSB_CONFIG_PLUGIN_PACKAGE;
+            }
+        }
+        this.observableBackend.debug(tTrace, "Add config {name} from ({package})", {
+            package: this.configPackage ?? "this project",
+            name: this.configPluginName,
+        });
+        if (this.configPluginName === "config-default") {
+            const obs = this.createObservable(tTrace, "config");
+            await (0, base_1.SmartFunctionCallAsync)(this.configPlugin, this.configPlugin.init, obs);
+            return;
+        }
+        this.observableBackend.debug(tTrace, `Import config plugin: {name} from ({package})`, {
+            package: this.configPackage ?? "this project",
+            name: this.configPluginName,
+        });
+        const newPlugin = await this.sbPlugins.loadPlugin(this.observableBackend, this.configPackage ?? null, this.configPluginName, this.configPluginName);
+        if (newPlugin === null || !newPlugin.success) {
+            this.observableBackend.error(tTrace, "Failed to import config plugin: {name} from ({package})", {
+                package: this.configPackage ?? "this project",
+                name: this.configPluginName,
+            });
+            return;
+        }
+        await this.setConfigPlugin(newPlugin.data);
+    }
+}
+exports.SBConfig = SBConfig;
+//# sourceMappingURL=config.js.map

package/lib/serviceBase/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/serviceBase/config.ts"],"names":[],"mappings":"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"}

package/lib/serviceBase/events.d.ts

@@ -0,0 +1,91 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { Readable } from "node:stream";
+import { BSBService, BSBServiceClient } from "../base";
+import { DEBUG_MODE, DTrace, EventsFilter, IPluginDefinition, LoadedPlugin, Observable } from "../interfaces";
+import { SBConfig } from "./config";
+import { SBObservable } from "./observable";
+import { SBPlugins } from "./plugins";
+/**
+ * BSB Events Controller
+ *
+ * This class is responsible for managing the events in the BSB framework.
+ * If you have a specific way of managing events, you can extend this class and then use your own class when creating the ServiceBase instance.
+ *
+ * @group Events
+ * @category Core
+ */
+export declare class SBEvents {
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/SBEvents.html | API: SBEvents}
+     */
+    private events;
+    private readonly mode;
+    private readonly appId;
+    private readonly cwd;
+    private sbPlugins;
+    private readonly observableBackend;
+    private metricCounters;
+    private metricGauges;
+    private createObservable;
+    constructor(appId: string, mode: DEBUG_MODE, cwd: string, sbPlugins: SBPlugins, sbObservable: SBObservable, createObservable: (trace: DTrace, pluginName: string, attributes?: Record<string, string | number | boolean>) => Observable);
+    dispose(): void;
+    private getPluginsMatchingTriggerEvent;
+    private getPluginForEvent;
+    init(sbConfig: SBConfig, sbObservable: SBObservable): Promise<void>;
+    run(): Promise<void>;
+    addPlugin(sbObservable: SBObservable, plugin: IPluginDefinition, reference: LoadedPlugin<"events">, config: any, filter?: EventsFilter): Promise<import("../base").BSBEventsRef>;
+    private addEvents;
+    private handleOnBroadcast;
+    onBroadcast(context: BSBService<any, any> | BSBServiceClient<any>, trace: DTrace, pluginName: string, event: string, listener: {
+        (trace: DTrace, ...args: Array<any>): Promise<void> | void;
+    }): Promise<void>;
+    emitBroadcast(trace: DTrace, pluginName: string, event: string, ...args: Array<any>): Promise<void>;
+    private handleOnEvent;
+    onEvent(trace: DTrace, context: BSBService | BSBServiceClient<any>, pluginName: string, event: string, listener: {
+        (trace: DTrace, ...args: Array<any>): Promise<void> | void;
+    }): Promise<void>;
+    onEventSpecific(trace: DTrace, serverId: string, context: BSBService | BSBServiceClient<any>, pluginName: string, event: string, listener: {
+        (trace: DTrace, ...args: Array<any>): Promise<void> | void;
+    }): Promise<void>;
+    emitEvent(trace: DTrace, pluginName: string, event: string, ...args: Array<any>): Promise<void>;
+    emitEventSpecific(trace: DTrace, serverId: string, pluginName: string, event: string, ...args: Array<any>): Promise<void>;
+    private handleOnReturnableEvent;
+    onReturnableEvent(trace: DTrace, context: BSBService | BSBServiceClient<any>, pluginName: string, event: string, listener: {
+        (trace: DTrace, ...args: Array<any>): Promise<any> | any;
+    }): Promise<void>;
+    onReturnableEventSpecific(trace: DTrace, serverId: string, context: BSBService | BSBServiceClient<any>, pluginName: string, event: string, listener: {
+        (trace: DTrace, ...args: Array<any>): Promise<any> | any;
+    }): Promise<void>;
+    emitEventAndReturn(trace: DTrace, pluginName: string, event: string, timeoutSeconds: number, ...args: Array<any>): Promise<any>;
+    emitEventAndReturnSpecific(trace: DTrace, serverId: string, pluginName: string, event: string, timeoutSeconds: number, ...args: Array<any>): Promise<any>;
+    private handleOnReceiveStream;
+    receiveStream(trace: DTrace, context: BSBService | BSBServiceClient<any>, pluginName: string, event: string, listener: {
+        (error: Error | null, stream: Readable): Promise<void>;
+    }, timeoutSeconds?: number): Promise<string>;
+    sendStream(trace: DTrace, pluginName: string, event: string, streamId: string, stream: Readable): Promise<void>;
+}