/**
 * Action classes — async handles for controllable call operations.
 *
 * Each Action tracks a control_id and resolves when the server sends
 * a terminal event for that control_id.
 */
import { type Deferred } from './Deferred.js';
import { RelayEvent } from './RelayEvent.js';
import type { CompletedCallback } from './types.js';
/**
 * Structural subset of {@link Call} that an Action needs — avoids a circular
 * import between `Call.ts` and `Action.ts`.
 */
export interface CallLike {
    _execute(method: string, extraParams?: Record<string, unknown>): Promise<Record<string, unknown>>;
}
/**
 * Async handle for a controllable call operation (play, record, tap, detect, etc.).
 *
 * An Action is returned from the async variants on {@link Call} (e.g. `call.playAsync`).
 * It resolves when the server emits a terminal event for its `controlId`. Use
 * {@link Action.wait} to await completion, or register an `onCompleted` callback.
 *
 * @example
 * ```ts
 * const play = await call.playAsync({ play: [{ type: 'tts', text: 'Hello!' }] });
 * // do other work while the greeting plays...
 * const event = await play.wait(10); // seconds
 * console.log('Playback finished with state', event.params.state);
 * ```
 */
export declare class Action {
    /** Reference to the owning call. */
    readonly call: CallLike;
    /** Unique control ID used by the server to route events back to this action. */
    readonly controlId: string;
    protected readonly _terminalEvent: string;
    protected readonly _terminalStates: readonly string[];
    /** @internal */ readonly _done: Deferred<RelayEvent>;
    /** Final event once the action terminates, or `null` while still running. */
    result: RelayEvent | null;
    /** Whether the action has reached a terminal state. */
    completed: boolean;
    /** @internal */ _onCompleted: CompletedCallback | null;
    /**
     * @param call - Owning call (via the structural {@link CallLike} interface).
     * @param controlId - Unique control ID the server will echo on events.
     * @param terminalEvent - Event type that carries terminal state transitions.
     * @param terminalStates - State values that mark this action as completed.
     */
    constructor(call: CallLike, controlId: string, terminalEvent: string, terminalStates: readonly string[]);
    /** @internal Called by Call when an event matches our control_id. */
    _checkEvent(event: RelayEvent): void;
    /** @internal Mark the action as completed and fire the on_completed callback. */
    _resolve(event: RelayEvent): void;
    /**
     * Wait for the action to complete.
     *
     * @param timeout - Maximum time to wait in **seconds** (matches the Python
     *   SDK convention — not milliseconds).
     * @returns The terminal {@link RelayEvent} for this action.
     * @throws {Error} When the optional timeout elapses before the action ends.
     */
    wait(timeout?: number): Promise<RelayEvent>;
    /** True once the action has reached a terminal state. */
    get isDone(): boolean;
}
/** Async handle for a `calling.call.play` action — controls playback in progress. */
export declare class PlayAction extends Action {
    constructor(call: CallLike, controlId: string);
    /**
     * Stop the playback.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
    /**
     * Pause active playback (resumable with {@link resume}).
     *
     * @returns The platform's pause response.
     * @throws {RelayError} When the pause command is rejected.
     */
    pause(): Promise<Record<string, unknown>>;
    /**
     * Resume playback paused by {@link pause}.
     *
     * @returns The platform's resume response.
     * @throws {RelayError} When the resume command is rejected.
     */
    resume(): Promise<Record<string, unknown>>;
    /**
     * Adjust playback volume.
     *
     * @param volume - Volume adjustment in dB.
     * @returns The platform's volume response.
     * @throws {RelayError} When the volume command is rejected.
     */
    volume(volume: number): Promise<Record<string, unknown>>;
}
/** Async handle for a `calling.call.record` action — controls recording in progress. */
export declare class RecordAction extends Action {
    constructor(call: CallLike, controlId: string);
    /**
     * Stop the recording and finalise the file.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
    /**
     * Pause the recording (resumable with {@link resume}).
     *
     * @param behavior - Optional behaviour hint (e.g. `"silence"`) controlling
     *   what is recorded in place of paused audio.
     * @returns The platform's pause response.
     * @throws {RelayError} When the pause command is rejected.
     */
    pause(behavior?: string): Promise<Record<string, unknown>>;
    /**
     * Resume recording paused by {@link pause}.
     *
     * @returns The platform's resume response.
     * @throws {RelayError} When the resume command is rejected.
     */
    resume(): Promise<Record<string, unknown>>;
}
/** Async handle for a `calling.call.detect` action (machine / fax / digit). */
export declare class DetectAction extends Action {
    constructor(call: CallLike, controlId: string);
    /** Resolve on first meaningful result OR terminal state. */
    _checkEvent(event: RelayEvent): void;
    /**
     * Stop detection before the timeout elapses.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
}
/** Async handle for a `play_and_collect` action (combined playback + input collection). */
export declare class CollectAction extends Action {
    constructor(call: CallLike, controlId: string);
    /**
     * play_and_collect shares a control_id across play and collect phases.
     * Only resolve on collect events, not play events.
     */
    _checkEvent(event: RelayEvent): void;
    /**
     * Stop the play_and_collect operation.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
    /**
     * Adjust playback volume of the prompt audio mid-collect.
     *
     * @param volume - Volume adjustment in dB.
     * @returns The platform's volume response.
     * @throws {RelayError} When the volume command is rejected.
     */
    volume(volume: number): Promise<Record<string, unknown>>;
    /**
     * Start the collect input timers (useful when `initial_timeout` should be
     * reset after an async side effect completes).
     *
     * @returns The platform's start_input_timers response.
     * @throws {RelayError} When the command is rejected.
     */
    startInputTimers(): Promise<Record<string, unknown>>;
}
/** Async handle for a bare `calling.call.collect` action (no accompanying play). */
export declare class StandaloneCollectAction extends Action {
    constructor(call: CallLike, controlId: string);
    _checkEvent(event: RelayEvent): void;
    /**
     * Stop the collect operation before input is received.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
    /**
     * Start the collect input timers.
     *
     * @returns The platform's start_input_timers response.
     * @throws {RelayError} When the command is rejected.
     */
    startInputTimers(): Promise<Record<string, unknown>>;
}
/** Async handle for a `send_fax` or `receive_fax` action. */
export declare class FaxAction extends Action {
    private _methodPrefix;
    constructor(call: CallLike, controlId: string, methodPrefix: string);
    /**
     * Stop the fax transfer mid-stream.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
}
/** Async handle for a `calling.call.tap` action (media mirroring). */
export declare class TapAction extends Action {
    constructor(call: CallLike, controlId: string);
    /**
     * Stop the media tap.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
}
/** Async handle for a `calling.call.stream` action (outbound media stream). */
export declare class StreamAction extends Action {
    constructor(call: CallLike, controlId: string);
    /**
     * Stop the outbound stream.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
}
/** Async handle for a `calling.call.pay` action (PCI-compliant payment collection). */
export declare class PayAction extends Action {
    constructor(call: CallLike, controlId: string);
    /**
     * Cancel the payment collection before it completes.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
}
/** Async handle for a `calling.call.transcribe` action (real-time transcription). */
export declare class TranscribeAction extends Action {
    constructor(call: CallLike, controlId: string);
    /**
     * Stop the transcription.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
}
/** Async handle for a `calling.call.ai` action (on-call AI agent session). */
export declare class AIAction extends Action {
    constructor(call: CallLike, controlId: string);
    /**
     * Stop the AI agent session.
     *
     * @returns The platform's stop response.
     * @throws {RelayError} When the stop command is rejected.
     */
    stop(): Promise<Record<string, unknown>>;
}