/**
 * Plugins — optional distributable bundles that group modules, extensions,
 * event subscribers, and link definitions into a single unit.
 *
 * A plugin is the unit of "distribution" in Voyant: a customer, vendor, or
 * integrator ships a plugin package and it can be registered alongside core
 * modules without touching the framework itself. It is not the default runtime
 * customization unit — modules, providers, extensions, and workflows should be
 * preferred when a smaller seam fits.
 *
 * Core plugins are transport-agnostic — they contain {@link Module} and
 * {@link Extension} values (no HTTP routes). Transport adapters (such as
 * `@voyantjs/hono`) layer their own plugin shape on top of this
 * contract to carry route bundles.
 */
import type { EventBus, EventHandler, EventMetadata } from "./events.js";
import type { LinkDefinition } from "./links.js";
import type { BootstrapHandler, EventFilterDescriptor, Extension, Module, WorkflowDescriptor } from "./module.js";
/**
 * A single event subscription contributed by a plugin.
 *
 * When the plugin is registered, `handler` is attached to the provided
 * {@link EventBus} for the given `event` name.
 */
export interface Subscriber<TData = unknown, TMetadata extends EventMetadata | undefined = EventMetadata | undefined> {
    /** Event name, following `<resource>.<pastTenseAction>` convention. */
    event: string;
    /** Callback invoked when the event is emitted. */
    handler: EventHandler<TData, TMetadata>;
    /**
     * When `true`, the handler completes before `emit()` resolves even on
     * runtimes that defer subscriber work past the HTTP response. Reserve
     * for handlers whose side effects must be read-your-writes visible
     * within the emitting request. Default deferrable.
     */
    inline?: boolean;
}
/**
 * A transport-agnostic plugin bundle.
 *
 * Plugins contribute any combination of:
 * - {@link Module} values (core domain primitives)
 * - {@link Extension} values (hook attachments to existing modules)
 * - {@link Subscriber} values (event listeners)
 * - {@link LinkDefinition} values (cross-module associations)
 *
 * Transport adapters can intersect this shape with their own fields (see
 * `HonoPlugin` in `@voyantjs/hono` for the Hono variant).
 */
export interface Plugin {
    /** Unique plugin identifier (e.g. "payload-cms", "bokun"). */
    name: string;
    /** Optional version tag for diagnostics. */
    version?: string;
    /**
     * Optional lazy runtime bootstrap executed once per app/isolate, on the
     * first request where bindings are available.
     */
    bootstrap?: BootstrapHandler;
    /** Modules contributed by the plugin. */
    modules?: Module[];
    /** Extensions contributed by the plugin. */
    extensions?: Extension[];
    /** Event subscribers wired to the caller's {@link EventBus} at registration. */
    subscribers?: Subscriber[];
    /** Link definitions contributed by the plugin. */
    links?: LinkDefinition[];
    /**
     * Workflows contributed by the plugin. Collected and merged with
     * module-owned workflows at `createApp()` boot. See
     * {@link WorkflowDescriptor} for the structural contract.
     */
    workflows?: readonly WorkflowDescriptor[];
    /**
     * Event filters contributed by the plugin. See
     * {@link EventFilterDescriptor} for the structural contract.
     */
    eventFilters?: readonly EventFilterDescriptor[];
}
/**
 * Identity helper that returns the plugin as-is. Exists purely so authors
 * can write `definePlugin({ ... })` and get inference + IDE help without
 * casting.
 */
export declare function definePlugin<P extends Plugin>(plugin: P): P;
/**
 * Result of flattening a set of plugins.
 */
export interface RegisteredPlugins {
    /** All modules contributed by the supplied plugins, in registration order. */
    modules: Module[];
    /** All extensions contributed by the supplied plugins. */
    extensions: Extension[];
    /** All link definitions contributed by the supplied plugins. */
    links: LinkDefinition[];
    /** All subscribers contributed, in registration order. */
    subscribers: Subscriber[];
    /** Subscription handles for subscribers attached to the event bus. */
    subscriptions: Array<{
        unsubscribe(): void;
    }>;
    /** All workflows contributed by the supplied plugins, in registration order. */
    workflows: WorkflowDescriptor[];
    /** All event filters contributed by the supplied plugins, in registration order. */
    eventFilters: EventFilterDescriptor[];
}
export interface RegisterPluginsOptions {
    /** Event bus to attach subscribers to. If omitted, subscribers are collected but not wired. */
    eventBus?: EventBus;
}
/**
 * Flatten a list of plugins into their constituent pieces and optionally
 * attach event subscribers to an {@link EventBus}.
 *
 * Throws if two plugins declare the same `name`.
 */
export declare function registerPlugins(plugins: ReadonlyArray<Plugin>, options?: RegisterPluginsOptions): RegisteredPlugins;
//# sourceMappingURL=plugin.d.ts.map