/**
 * @fileoverview Handoff types for AFD commands
 *
 * The HandoffResult interface is returned by commands that bootstrap
 * streaming connections, allowing clients to connect to specialized
 * protocols (WebSocket, WebRTC, SSE, etc.) for real-time communication.
 */
/**
 * Protocol type for client dispatch.
 *
 * Standard protocols are provided, but custom protocols are allowed
 * via the string union type.
 */
export type HandoffProtocol = 'websocket' | 'webrtc' | 'sse' | 'http-stream' | string;
/**
 * Named reconnection policy for handoff connections.
 *
 * Extracted as a first-class type so clients and servers can reference,
 * validate, and default reconnect behaviour consistently.
 *
 * @example
 * ```typescript
 * const policy: ReconnectPolicy = {
 *   allowed: true,
 *   maxAttempts: 5,
 *   backoffMs: 1000,
 * };
 * ```
 */
export interface ReconnectPolicy {
    /** Whether reconnection is allowed */
    allowed: boolean;
    /** Maximum number of reconnection attempts */
    maxAttempts?: number;
    /** Base backoff time in milliseconds */
    backoffMs?: number;
}
/**
 * Default reconnect policy values.
 *
 * Used by {@link createHandoff} when no reconnect policy is provided.
 */
export declare const defaultReconnectPolicy: Readonly<Required<ReconnectPolicy>>;
/**
 * Authentication credentials for the handoff connection.
 *
 * @example
 * ```typescript
 * const credentials: HandoffCredentials = {
 *   token: 'eyJhbGciOiJIUzI1NiIs...',
 *   sessionId: 'session-abc123',
 *   headers: { 'X-Custom-Header': 'value' }
 * };
 * ```
 */
export interface HandoffCredentials {
    /** Bearer token for authentication */
    token?: string;
    /** Additional headers to include in the connection */
    headers?: Record<string, string>;
    /** Session ID for correlation */
    sessionId?: string;
}
/**
 * Metadata for client decision-making about the handoff.
 *
 * @example
 * ```typescript
 * const metadata: HandoffMetadata = {
 *   expectedLatency: 50,
 *   capabilities: ['text', 'typing-indicator', 'presence'],
 *   expiresAt: '2025-01-15T12:00:00Z',
 *   reconnect: {
 *     allowed: true,
 *     maxAttempts: 5,
 *     backoffMs: 1000
 *   },
 *   description: 'Real-time chat connection'
 * };
 * ```
 */
export interface HandoffMetadata {
    /** Expected latency in ms (hint for client) */
    expectedLatency?: number;
    /** Capabilities the channel supports */
    capabilities?: string[];
    /** When the handoff credentials expire (ISO 8601) */
    expiresAt?: string;
    /** Reconnection policy */
    reconnect?: ReconnectPolicy;
    /** Human-readable description of the handoff */
    description?: string;
}
/**
 * Result returned by commands that hand off to specialized protocols.
 *
 * This type is used as the data payload in CommandResult<HandoffResult>.
 * Commands returning handoffs should be marked with `handoff: true` and
 * tagged appropriately (e.g., 'handoff', 'handoff:websocket').
 *
 * @example
 * ```typescript
 * const result = await client.call<HandoffResult>('chat.connect', { roomId });
 * if (result.success && result.data) {
 *   const ws = new WebSocket(result.data.endpoint);
 *   ws.send(JSON.stringify({ auth: result.data.credentials?.token }));
 * }
 * ```
 */
export interface HandoffResult {
    /** Protocol type for client dispatch */
    protocol: HandoffProtocol;
    /** Full URL to connect to */
    endpoint: string;
    /** Authentication credentials for the handoff */
    credentials?: HandoffCredentials;
    /** Metadata for client decision-making */
    metadata?: HandoffMetadata;
}
/**
 * Options for {@link createHandoff} factory function.
 *
 * All fields except `protocol` and `endpoint` are optional and have sensible
 * defaults (e.g. reconnect defaults to {@link defaultReconnectPolicy}).
 */
export interface CreateHandoffOptions {
    /** Protocol type for client dispatch */
    protocol: HandoffProtocol;
    /** Full URL to connect to */
    endpoint: string;
    /** Authentication credentials for the handoff */
    credentials?: HandoffCredentials;
    /** Metadata for client decision-making (reconnect defaults applied) */
    metadata?: HandoffMetadata;
}
/**
 * Create a HandoffResult with sensible defaults.
 *
 * If `metadata.reconnect` is not provided it defaults to
 * {@link defaultReconnectPolicy} (`{ allowed: true, maxAttempts: 3, backoffMs: 1000 }`).
 *
 * @param options - Handoff configuration
 * @returns A fully-populated HandoffResult
 *
 * @example
 * ```typescript
 * // Minimal — reconnect policy auto-applied
 * const handoff = createHandoff({
 *   protocol: 'websocket',
 *   endpoint: 'wss://chat.example.com/rooms/123',
 * });
 *
 * // With explicit reconnect override
 * const handoff2 = createHandoff({
 *   protocol: 'sse',
 *   endpoint: 'https://api.example.com/events',
 *   metadata: {
 *     reconnect: { allowed: false },
 *   },
 * });
 * ```
 */
export declare function createHandoff(options: CreateHandoffOptions): HandoffResult;
/**
 * Type guard to check if a value is a ReconnectPolicy.
 *
 * @param value - Value to check
 * @returns True if value is a valid ReconnectPolicy
 */
export declare function isReconnectPolicy(value: unknown): value is ReconnectPolicy;
/**
 * Type guard to check if a value is a HandoffResult.
 *
 * @param value - Value to check
 * @returns True if value is a HandoffResult
 *
 * @example
 * ```typescript
 * const result = await client.call('some.command', input);
 * if (result.success && isHandoff(result.data)) {
 *   // TypeScript knows result.data is HandoffResult
 *   connect(result.data.protocol, result.data.endpoint);
 * }
 * ```
 */
export declare function isHandoff(value: unknown): value is HandoffResult;
/**
 * Type guard to check if a HandoffResult uses a specific protocol.
 *
 * @param handoff - HandoffResult to check
 * @param protocol - Protocol to check for
 * @returns True if the handoff uses the specified protocol
 *
 * @example
 * ```typescript
 * if (isHandoffProtocol(handoff, 'websocket')) {
 *   const ws = new WebSocket(handoff.endpoint);
 * } else if (isHandoffProtocol(handoff, 'sse')) {
 *   const eventSource = new EventSource(handoff.endpoint);
 * }
 * ```
 */
export declare function isHandoffProtocol(handoff: HandoffResult, protocol: HandoffProtocol): boolean;
/**
 * Minimal interface for checking if a command is a handoff command.
 * This avoids circular dependencies with commands.ts.
 */
interface HandoffCommandLike {
    handoff?: boolean;
    handoffProtocol?: string;
    tags?: string[];
}
/**
 * Check if a command definition is a handoff command.
 *
 * A command is a handoff command if:
 * - It has `handoff: true` property, OR
 * - It has a 'handoff' tag
 *
 * @param command - Command definition to check
 * @returns True if the command is a handoff command
 *
 * @example
 * ```typescript
 * const commands = registry.list();
 * const handoffCommands = commands.filter(isHandoffCommand);
 * ```
 */
export declare function isHandoffCommand(command: HandoffCommandLike): boolean;
/**
 * Get the handoff protocol from a command definition.
 *
 * Returns the protocol in this priority order:
 * 1. Explicit `handoffProtocol` property
 * 2. Protocol from 'handoff:{protocol}' tag
 * 3. undefined if not a handoff command or no protocol specified
 *
 * @param command - Command definition to check
 * @returns The handoff protocol or undefined
 *
 * @example
 * ```typescript
 * const protocol = getHandoffProtocol(chatConnectCommand);
 * if (protocol === 'websocket') {
 *   // Handle WebSocket handoff
 * }
 * ```
 */
export declare function getHandoffProtocol(command: HandoffCommandLike): HandoffProtocol | undefined;
export {};
//# sourceMappingURL=handoff.d.ts.map