/**
 * @module timeouts
 * Configurable request timeouts for xBind operations
 *
 * Provides centralized timeout management with:
 * - Per-operation timeout configuration
 * - Default timeouts for registry, gateway, transport
 * - Timeout inheritance and overrides
 * - Timeout error messages with context
 * - Integration with AbortController/cancellation tokens
 *
 * @example
 * ```typescript
 * import { TimeoutConfig, withTimeout, createTimeoutController } from '@private.me/xbind';
 *
 * // Create timeout configuration
 * const config = new TimeoutConfig({
 *   registry: 10000,
 *   gateway: 15000,
 *   transport: 30000,
 * });
 *
 * // Use timeout with fetch
 * const controller = createTimeoutController(config.registry);
 * const response = await fetch(url, { signal: controller.signal });
 *
 * // Wrap async operation with timeout
 * const result = await withTimeout(
 *   async () => performOperation(),
 *   5000,
 *   'Operation description'
 * );
 * ```
 */
import type { Result } from '@private.me/shared';
/**
 * Timeout configuration for different operation types.
 * All values in milliseconds.
 */
export interface TimeoutConfigOptions {
    /**
     * Timeout for registry operations (lookup, register, update).
     * Default: 10000ms (10 seconds)
     */
    readonly registry?: number;
    /**
     * Timeout for gateway operations (send, poll, status).
     * Default: 15000ms (15 seconds)
     */
    readonly gateway?: number;
    /**
     * Timeout for transport operations (HTTP/HTTPS requests).
     * Default: 30000ms (30 seconds)
     */
    readonly transport?: number;
    /**
     * Default timeout for operations without specific category.
     * Default: 30000ms (30 seconds)
     */
    readonly default?: number;
    /**
     * Override timeout for specific operation.
     * Takes precedence over category timeouts.
     */
    readonly override?: number;
}
/**
 * Timeout error with operation context.
 */
export declare class TimeoutError extends Error {
    readonly code: "TIMEOUT";
    readonly operation: string;
    readonly timeoutMs: number;
    readonly timestamp: number;
    constructor(operation: string, timeoutMs: number);
    /**
     * Create timeout error with additional context.
     */
    static withContext(operation: string, timeoutMs: number, context?: Record<string, unknown>): TimeoutError;
}
/**
 * Default timeout values (milliseconds).
 */
export declare const DEFAULT_TIMEOUTS: {
    readonly registry: 10000;
    readonly gateway: 15000;
    readonly transport: 30000;
    readonly default: 30000;
};
/**
 * Timeout configuration manager.
 * Provides timeout values with inheritance and override support.
 */
export declare class TimeoutConfig {
    private readonly registry;
    private readonly gateway;
    private readonly transport;
    private readonly default;
    constructor(options?: TimeoutConfigOptions);
    /**
     * Get timeout for registry operations.
     * @param override - Optional override timeout
     */
    getRegistry(override?: number): number;
    /**
     * Get timeout for gateway operations.
     * @param override - Optional override timeout
     */
    getGateway(override?: number): number;
    /**
     * Get timeout for transport operations.
     * @param override - Optional override timeout
     */
    getTransport(override?: number): number;
    /**
     * Get default timeout.
     * @param override - Optional override timeout
     */
    getDefault(override?: number): number;
    /**
     * Get timeout for specific operation category.
     * @param category - Operation category
     * @param override - Optional override timeout
     */
    get(category: 'registry' | 'gateway' | 'transport' | 'default', override?: number): number;
    /**
     * Create new config with overrides.
     * @param overrides - Timeout overrides
     */
    with(overrides: TimeoutConfigOptions): TimeoutConfig;
    /**
     * Validate timeout value.
     */
    private validateTimeout;
    /**
     * Export configuration as plain object.
     */
    toJSON(): TimeoutConfigOptions;
}
/**
 * Operation timeout controller with cancellation support.
 * Wraps AbortController with timeout semantics.
 */
export declare class OperationTimeoutController {
    readonly signal: AbortSignal;
    readonly timeoutMs: number;
    readonly operation: string;
    private readonly controller;
    private readonly timer;
    private timedOut;
    constructor(timeoutMs: number, operation?: string);
    /**
     * Cancel the operation (clear timeout).
     */
    cancel(): void;
    /**
     * Clear timeout if operation completed successfully.
     * Call this when operation finishes to prevent unnecessary abort.
     */
    clear(): void;
    /**
     * Check if controller timed out (vs manual cancellation).
     */
    didTimeout(): boolean;
    /**
     * Get timeout error if operation timed out.
     */
    getTimeoutError(): TimeoutError | null;
}
/**
 * Create timeout controller for operation.
 * @param timeoutMs - Timeout in milliseconds
 * @param operation - Operation description for error messages
 */
export declare function createTimeoutController(timeoutMs: number, operation?: string): OperationTimeoutController;
/**
 * Wrap async operation with timeout.
 * Rejects with TimeoutError if operation exceeds timeout.
 *
 * @param fn - Async operation to execute
 * @param timeoutMs - Timeout in milliseconds
 * @param operation - Operation description for error messages
 * @returns Result of operation or timeout error
 *
 * @example
 * ```typescript
 * const result = await withTimeout(
 *   async () => fetch('https://api.example.com'),
 *   5000,
 *   'API request'
 * );
 * ```
 */
export declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, operation?: string): Promise<T>;
/**
 * Wrap async operation with timeout (Result-based).
 * Returns ok(result) or err('TIMEOUT') without throwing.
 *
 * @param fn - Async operation to execute
 * @param timeoutMs - Timeout in milliseconds
 * @param operation - Operation description for error messages
 * @returns Result with operation result or timeout error
 *
 * @example
 * ```typescript
 * const result = await withTimeoutResult(
 *   async () => fetch('https://api.example.com'),
 *   5000,
 *   'API request'
 * );
 * if (result.ok) {
 *   console.log('Success:', result.value);
 * } else {
 *   console.error('Timeout:', result.error);
 * }
 * ```
 */
export declare function withTimeoutResult<T>(fn: () => Promise<T>, timeoutMs: number, operation?: string): Promise<Result<T, 'TIMEOUT'>>;
/**
 * Create timeout signal for use with fetch/AbortController APIs.
 *
 * @param timeoutMs - Timeout in milliseconds
 * @param operation - Operation description
 * @returns AbortSignal that aborts after timeout
 *
 * @example
 * ```typescript
 * const signal = createOperationTimeoutSignal(5000, 'fetch request');
 * const response = await fetch(url, { signal });
 * ```
 */
export declare function createOperationTimeoutSignal(timeoutMs: number, operation?: string): AbortSignal;
/**
 * Timeout helper for operations with cancellation token.
 * Returns controller that can be passed to fetch, agent.send, etc.
 *
 * @param config - Timeout configuration
 * @param category - Operation category
 * @param operation - Operation description
 * @param override - Optional timeout override
 * @returns Timeout controller
 *
 * @example
 * ```typescript
 * const controller = createOperationTimeout(config, 'registry', 'lookup DID');
 * const response = await fetch(url, { signal: controller.signal });
 * controller.clear(); // Clear timeout on success
 * ```
 */
export declare function createOperationTimeout(config: TimeoutConfig, category: 'registry' | 'gateway' | 'transport' | 'default', operation: string, override?: number): OperationTimeoutController;
/**
 * Check if error is a timeout error.
 */
export declare function isTimeoutError(error: unknown): error is TimeoutError;
/**
 * Extract timeout from error if it's a timeout error.
 * Returns timeout in milliseconds or undefined.
 */
export declare function getTimeoutFromError(error: unknown): number | undefined;
/**
 * Create timeout configuration from environment variables.
 * Looks for:
 * - XBIND_TIMEOUT_REGISTRY
 * - XBIND_TIMEOUT_GATEWAY
 * - XBIND_TIMEOUT_TRANSPORT
 * - XBIND_TIMEOUT_DEFAULT
 *
 * Falls back to default values if not set.
 */
export declare function createTimeoutConfigFromEnv(): TimeoutConfig;
/**
 * Global default timeout configuration.
 * Can be overridden by setting environment variables.
 */
export declare const globalTimeoutConfig: TimeoutConfig;
