/**
 * @module plugin-system
 * Extensible plugin and middleware architecture for xBind
 *
 * Provides hooks for message processing, encryption, decryption, and custom logic.
 * Supports both synchronous and asynchronous plugin execution.
 */
import type { Result } from '@private.me/shared';
import type { AnyTransportEnvelope } from './envelope.js';
import type { AgentIdentity } from './identity.js';
/**
 * Plugin execution context provided to all hooks.
 * Contains agent identity, message metadata, and shared state.
 */
export interface PluginContext {
    /** Agent identity making the call */
    readonly agent: AgentIdentity;
    /** Recipient DID (if applicable) */
    readonly recipient?: string;
    /** Message scope */
    readonly scope?: string;
    /** Message timestamp */
    readonly timestamp: number;
    /** Shared state across plugins in the chain */
    readonly state: Map<string, unknown>;
    /** Plugin metadata */
    readonly metadata: Record<string, unknown>;
}
/**
 * Hook execution result.
 * Plugins can modify the payload, add metadata, or abort execution.
 */
export interface HookResult<T> {
    /** Modified payload (or original if unchanged) */
    readonly payload: T;
    /** Metadata to attach to context */
    readonly metadata?: Record<string, unknown>;
    /** Abort flag - if true, stops further processing */
    readonly abort?: boolean;
    /** Abort reason (if abort === true) */
    readonly reason?: string;
}
/**
 * Plugin interface.
 * All plugins must implement this interface.
 */
export interface Plugin {
    /** Plugin name (must be unique) */
    readonly name: string;
    /** Plugin version */
    readonly version: string;
    /** Plugin description */
    readonly description?: string;
    /** Plugin priority (lower = earlier execution, default: 100) */
    readonly priority?: number;
    /** Called before sending a message */
    onSend?(payload: unknown, context: PluginContext): Promise<Result<HookResult<unknown>, string>> | Result<HookResult<unknown>, string>;
    /** Called after receiving a message */
    onReceive?(envelope: AnyTransportEnvelope, context: PluginContext): Promise<Result<HookResult<AnyTransportEnvelope>, string>> | Result<HookResult<AnyTransportEnvelope>, string>;
    /** Called before encryption */
    onEncrypt?(plaintext: Uint8Array, context: PluginContext): Promise<Result<HookResult<Uint8Array>, string>> | Result<HookResult<Uint8Array>, string>;
    /** Called after decryption */
    onDecrypt?(plaintext: Uint8Array, context: PluginContext): Promise<Result<HookResult<Uint8Array>, string>> | Result<HookResult<Uint8Array>, string>;
    /** Called on plugin initialization */
    onInit?(): Promise<Result<void, string>> | Result<void, string>;
    /** Called on plugin cleanup */
    onDestroy?(): Promise<Result<void, string>> | Result<void, string>;
}
/**
 * Middleware chain executor.
 * Runs plugins in priority order and handles errors.
 */
export declare class MiddlewareChain {
    private plugins;
    private initialized;
    constructor(plugins?: Plugin[]);
    /**
     * Register a plugin.
     * Plugins are automatically sorted by priority after registration.
     */
    register(plugin: Plugin): Result<void, string>;
    /**
     * Unregister a plugin by name.
     */
    unregister(name: string): Result<void, string>;
    /**
     * Get all registered plugins.
     */
    getPlugins(): readonly Plugin[];
    /**
     * Initialize all plugins.
     * Must be called before executing hooks.
     */
    initialize(): Promise<Result<void, string>>;
    /**
     * Destroy all plugins and cleanup resources.
     */
    destroy(): Promise<Result<void, string>>;
    /**
     * Execute onSend hooks.
     */
    executeSend(payload: unknown, context: PluginContext): Promise<Result<unknown, string>>;
    /**
     * Execute onReceive hooks.
     */
    executeReceive(envelope: AnyTransportEnvelope, context: PluginContext): Promise<Result<AnyTransportEnvelope, string>>;
    /**
     * Execute onEncrypt hooks.
     */
    executeEncrypt(plaintext: Uint8Array, context: PluginContext): Promise<Result<Uint8Array, string>>;
    /**
     * Execute onDecrypt hooks.
     */
    executeDecrypt(plaintext: Uint8Array, context: PluginContext): Promise<Result<Uint8Array, string>>;
}
/**
 * Create a plugin context.
 */
export declare function createPluginContext(agent: AgentIdentity, options?: {
    recipient?: string;
    scope?: string;
    timestamp?: number;
    state?: Map<string, unknown>;
    metadata?: Record<string, unknown>;
}): PluginContext;
/**
 * Plugin builder for creating plugins with a fluent API.
 */
export declare class PluginBuilder {
    private plugin;
    constructor(name: string, version: string);
    description(desc: string): this;
    priority(p: number): this;
    onSend(hook: (payload: unknown, context: PluginContext) => Promise<Result<HookResult<unknown>, string>> | Result<HookResult<unknown>, string>): this;
    onReceive(hook: (envelope: AnyTransportEnvelope, context: PluginContext) => Promise<Result<HookResult<AnyTransportEnvelope>, string>> | Result<HookResult<AnyTransportEnvelope>, string>): this;
    onEncrypt(hook: (plaintext: Uint8Array, context: PluginContext) => Promise<Result<HookResult<Uint8Array>, string>> | Result<HookResult<Uint8Array>, string>): this;
    onDecrypt(hook: (plaintext: Uint8Array, context: PluginContext) => Promise<Result<HookResult<Uint8Array>, string>> | Result<HookResult<Uint8Array>, string>): this;
    onInit(hook: () => Promise<Result<void, string>> | Result<void, string>): this;
    onDestroy(hook: () => Promise<Result<void, string>> | Result<void, string>): this;
    build(): Plugin;
}
/**
 * Create a plugin builder.
 */
export declare function createPlugin(name: string, version: string): PluginBuilder;
