/**
 * @module event-emitter
 * Type-safe event emitter for xBind agent events.
 *
 * Provides event-driven architecture for agent lifecycle events:
 * - message-sent: Emitted when a message is successfully sent
 * - message-received: Emitted when a message is received
 * - key-rotated: Emitted when encryption keys are rotated
 * - error: Emitted when an error occurs
 * - connection-status: Emitted when connection state changes
 */
import type { Result } from '@private.me/shared';
import type { AgentMessage } from './agent.js';
/** Connection status values */
export type ConnectionStatus = 'connected' | 'disconnected' | 'reconnecting' | 'error';
/** Event payload types mapped to event names */
export interface XBindEventMap {
    'message-sent': MessageSentEvent;
    'message-received': MessageReceivedEvent;
    'key-rotated': KeyRotatedEvent;
    'error': ErrorEvent;
    'connection-status': ConnectionStatusEvent;
}
/** Base event interface with common fields */
export interface XBindBaseEvent {
    /** Event type identifier */
    readonly type: string;
    /** ISO 8601 timestamp when event was emitted */
    readonly timestamp: string;
    /** Unique event identifier for tracking and deduplication */
    readonly eventId: string;
}
/** Emitted when a message is successfully sent */
export interface MessageSentEvent extends XBindBaseEvent {
    readonly type: 'message-sent';
    /** Recipient DID */
    readonly recipientDid: string;
    /** Message identifier */
    readonly messageId: string;
    /** Message payload size in bytes */
    readonly payloadSize: number;
    /** Envelope version used (v1-v4) */
    readonly envelopeVersion: string;
}
/** Emitted when a message is received */
export interface MessageReceivedEvent extends XBindBaseEvent {
    readonly type: 'message-received';
    /** Sender DID */
    readonly senderDid: string;
    /** Decoded message */
    readonly message: AgentMessage;
    /** Message identifier */
    readonly messageId: string;
    /** Whether signature was verified */
    readonly verified: boolean;
}
/** Emitted when encryption keys are rotated */
export interface KeyRotatedEvent extends XBindBaseEvent {
    readonly type: 'key-rotated';
    /** Key type rotated (ed25519, x25519, mlkem, mldsa) */
    readonly keyType: 'ed25519' | 'x25519' | 'mlkem' | 'mldsa';
    /** New public key (base64) */
    readonly newPublicKey: string;
    /** Previous public key (base64, if available) */
    readonly previousPublicKey?: string;
    /** Reason for rotation */
    readonly reason: string;
}
/** Emitted when an error occurs */
export interface ErrorEvent extends XBindBaseEvent {
    readonly type: 'error';
    /** Error code */
    readonly code: string;
    /** Error message */
    readonly message: string;
    /** Context where error occurred */
    readonly context: string;
    /** Detailed error information */
    readonly details?: Record<string, unknown>;
}
/** Emitted when connection status changes */
export interface ConnectionStatusEvent extends XBindBaseEvent {
    readonly type: 'connection-status';
    /** Current connection status */
    readonly status: ConnectionStatus;
    /** Previous connection status */
    readonly previousStatus?: ConnectionStatus;
    /** Additional context (error message, reconnect attempt, etc.) */
    readonly context?: string;
}
/** Event listener function signature */
export type EventListener<T extends XBindBaseEvent = XBindBaseEvent> = (event: T) => void | Promise<void>;
/** Options for event emission */
export interface EmitOptions {
    /** Whether to bubble event to parent emitters */
    bubble?: boolean;
    /** Whether to stop propagation after first listener */
    stopPropagation?: boolean;
    /** Custom event ID (auto-generated if not provided) */
    eventId?: string;
}
/** Options for event listener registration */
export interface ListenerOptions {
    /** Listener priority (higher = called first) */
    priority?: number;
    /** Whether listener should only fire once */
    once?: boolean;
}
/** Event emitter error codes */
export type EventEmitterErrorCode = 'INVALID_EVENT_TYPE' | 'INVALID_LISTENER' | 'LISTENER_ERROR' | 'MAX_LISTENERS_EXCEEDED' | 'DISPOSED';
/**
 * Type-safe event emitter for xBind agent events.
 *
 * Features:
 * - Type-safe event names and payloads
 * - Listener priority support
 * - Once listeners
 * - Event bubbling to parent emitters
 * - Async listener support with error handling
 * - Memory leak detection
 *
 * @example
 * ```typescript
 * const emitter = new XBindEventEmitter();
 *
 * // Register listener
 * emitter.on('message-received', (event) => {
 *   console.log('Received from:', event.senderDid);
 * });
 *
 * // Register one-time listener
 * emitter.once('connection-status', (event) => {
 *   console.log('Status:', event.status);
 * });
 *
 * // Emit event
 * await emitter.emit('message-received', {
 *   type: 'message-received',
 *   timestamp: new Date().toISOString(),
 *   eventId: '123',
 *   senderDid: 'did:key:z6Mk...',
 *   message: { payload: 'Hello' },
 *   messageId: 'msg-1',
 *   verified: true
 * });
 * ```
 */
export declare class XBindEventEmitter {
    private listeners;
    private parent?;
    private disposed;
    private eventCounter;
    /** Maximum listeners per event type before warning (0 = unlimited) */
    private maxListeners;
    /** Whether warnings are enabled */
    private warningsEnabled;
    /**
     * Create a new event emitter.
     *
     * @param parent - Optional parent emitter for event bubbling
     */
    constructor(parent?: XBindEventEmitter);
    /**
     * Register an event listener.
     *
     * @param eventType - Event type to listen for
     * @param listener - Listener function
     * @param options - Listener options (priority, once)
     * @returns This emitter for chaining
     *
     * @example
     * ```typescript
     * emitter.on('error', (event) => {
     *   console.error('Error:', event.message);
     * }, { priority: 10 });
     * ```
     */
    on<K extends keyof XBindEventMap>(eventType: K, listener: EventListener<XBindEventMap[K]>, options?: ListenerOptions): this;
    /**
     * Register a one-time event listener.
     * Listener is automatically removed after first invocation.
     *
     * @param eventType - Event type to listen for
     * @param listener - Listener function
     * @param options - Listener options (priority)
     * @returns This emitter for chaining
     *
     * @example
     * ```typescript
     * emitter.once('connection-status', (event) => {
     *   console.log('First status change:', event.status);
     * });
     * ```
     */
    once<K extends keyof XBindEventMap>(eventType: K, listener: EventListener<XBindEventMap[K]>, options?: Omit<ListenerOptions, 'once'>): this;
    /**
     * Remove an event listener.
     *
     * @param eventType - Event type
     * @param listener - Listener function to remove
     * @returns This emitter for chaining
     *
     * @example
     * ```typescript
     * const handler = (event) => console.log(event);
     * emitter.on('error', handler);
     * emitter.off('error', handler);
     * ```
     */
    off<K extends keyof XBindEventMap>(eventType: K, listener: EventListener<XBindEventMap[K]>): this;
    /**
     * Remove all listeners for an event type, or all listeners if no type specified.
     *
     * @param eventType - Optional event type (removes all if not specified)
     * @returns This emitter for chaining
     *
     * @example
     * ```typescript
     * emitter.removeAllListeners('error'); // Remove all error listeners
     * emitter.removeAllListeners(); // Remove all listeners
     * ```
     */
    removeAllListeners<K extends keyof XBindEventMap>(eventType?: K): this;
    /**
     * Emit an event to all registered listeners.
     * Listeners are called in priority order (highest first).
     * Async listeners are awaited in sequence.
     *
     * @param eventType - Event type to emit
     * @param event - Event payload
     * @param options - Emission options (bubble, stopPropagation)
     * @returns Result indicating success or first error encountered
     *
     * @example
     * ```typescript
     * await emitter.emit('error', {
     *   type: 'error',
     *   timestamp: new Date().toISOString(),
     *   eventId: '123',
     *   code: 'NETWORK_ERROR',
     *   message: 'Connection failed',
     *   context: 'transport'
     * });
     * ```
     */
    emit<K extends keyof XBindEventMap>(eventType: K, event: Omit<XBindEventMap[K], 'eventId' | 'timestamp'>, options?: EmitOptions): Promise<Result<void, EventEmitterErrorCode>>;
    /**
     * Check if there are any listeners for an event type.
     *
     * @param eventType - Event type to check
     * @returns True if there are listeners
     *
     * @example
     * ```typescript
     * if (emitter.hasListeners('error')) {
     *   await emitter.emit('error', errorEvent);
     * }
     * ```
     */
    hasListeners<K extends keyof XBindEventMap>(eventType: K): boolean;
    /**
     * Get the number of listeners for an event type.
     *
     * @param eventType - Event type
     * @returns Number of listeners
     *
     * @example
     * ```typescript
     * const count = emitter.listenerCount('message-received');
     * console.log(`${count} listeners registered`);
     * ```
     */
    listenerCount<K extends keyof XBindEventMap>(eventType: K): number;
    /**
     * Get all registered event types.
     *
     * @returns Array of event types with active listeners
     *
     * @example
     * ```typescript
     * const events = emitter.eventNames();
     * console.log('Active events:', events);
     * ```
     */
    eventNames(): Array<keyof XBindEventMap>;
    /**
     * Set the maximum number of listeners per event before warning.
     * Use 0 for unlimited listeners.
     *
     * @param n - Maximum listeners (0 = unlimited)
     * @returns This emitter for chaining
     *
     * @example
     * ```typescript
     * emitter.setMaxListeners(20); // Allow up to 20 listeners
     * emitter.setMaxListeners(0);  // Unlimited
     * ```
     */
    setMaxListeners(n: number): this;
    /**
     * Get the maximum number of listeners per event.
     *
     * @returns Maximum listeners (0 = unlimited)
     */
    getMaxListeners(): number;
    /**
     * Enable or disable memory leak warnings.
     *
     * @param enabled - Whether warnings are enabled
     * @returns This emitter for chaining
     */
    setWarningsEnabled(enabled: boolean): this;
    /**
     * Set the parent emitter for event bubbling.
     *
     * @param parent - Parent emitter (undefined to remove parent)
     * @returns This emitter for chaining
     *
     * @example
     * ```typescript
     * const parent = new XBindEventEmitter();
     * const child = new XBindEventEmitter();
     * child.setParent(parent);
     *
     * parent.on('error', (event) => console.log('Parent received:', event));
     * await child.emit('error', errorEvent, { bubble: true });
     * ```
     */
    setParent(parent: XBindEventEmitter | undefined): this;
    /**
     * Get the parent emitter.
     *
     * @returns Parent emitter or undefined
     */
    getParent(): XBindEventEmitter | undefined;
    /**
     * Wait for a specific event to be emitted.
     * Returns a promise that resolves with the event payload.
     *
     * @param eventType - Event type to wait for
     * @param timeout - Optional timeout in milliseconds
     * @returns Promise resolving to event or rejecting on timeout
     *
     * @example
     * ```typescript
     * const event = await emitter.waitFor('connection-status', 5000);
     * console.log('Status changed to:', event.status);
     * ```
     */
    waitFor<K extends keyof XBindEventMap>(eventType: K, timeout?: number): Promise<XBindEventMap[K]>;
    /**
     * Dispose the event emitter and remove all listeners.
     * After disposal, no events can be emitted and listeners cannot be registered.
     *
     * @example
     * ```typescript
     * emitter.dispose();
     * ```
     */
    dispose(): void;
    /**
     * Check if the emitter has been disposed.
     *
     * @returns True if disposed
     */
    isDisposed(): boolean;
    private checkDisposed;
    private generateEventId;
}
/**
 * Create a scoped event emitter that only emits specific event types.
 * Useful for isolating event channels.
 *
 * @param parent - Parent emitter
 * @param allowedEvents - Array of allowed event types
 * @returns Scoped event emitter
 *
 * @example
 * ```typescript
 * const parent = new XBindEventEmitter();
 * const errorOnly = createScopedEmitter(parent, ['error']);
 *
 * errorOnly.emit('error', errorEvent); // OK
 * errorOnly.emit('message-sent', event); // TypeScript error
 * ```
 */
export declare function createScopedEmitter<K extends keyof XBindEventMap>(parent: XBindEventEmitter, allowedEvents: readonly K[]): {
    on: <T extends K>(type: T, listener: EventListener<XBindEventMap[T]>, options?: ListenerOptions) => XBindEventEmitter;
    once: <T extends K>(type: T, listener: EventListener<XBindEventMap[T]>, options?: Omit<ListenerOptions, 'once'>) => XBindEventEmitter;
    off: <T extends K>(type: T, listener: EventListener<XBindEventMap[T]>) => XBindEventEmitter;
    emit: <T extends K>(type: T, event: Omit<XBindEventMap[T], 'eventId' | 'timestamp'>, options?: EmitOptions) => Promise<Result<void, EventEmitterErrorCode>>;
    hasListeners: <T extends K>(type: T) => boolean;
    listenerCount: <T extends K>(type: T) => number;
    dispose: () => void;
};
