/**
 * Result object returned when adding a command with synonym fetching.
 * Provides developers with information about what synonyms were registered.
 */
interface CommandAddResult {
    /** Whether the command was successfully added */
    success: boolean;
    /** The command name that was added */
    commandName: string;
    /** Array of synonyms that were successfully registered */
    synonymsMapped: string[];
    /** Total number of synonyms mapped */
    synonymCount: number;
    /** Error message if command addition failed */
    error?: string;
}

/**
 * Logging System for AAC Voice API
 *
 * This module provides comprehensive session logging for voice transcriptions,
 * command matching, synonym resolution, and confidence tracking.
 *
 * **When to use `Logger` vs `CommandHistory`:**
 *
 * - **Use `Logger`** for comprehensive session analytics including:
 *   - Full transcription text with timestamps
 *   - Detailed synonym resolution tracking (library vs API)
 *   - Confidence scores for all matches
 *   - Error messages for debugging
 *   - JSON export capabilities for data analysis
 *   - Multi-speaker support in online mode
 *   - Suitable for researchers, developers, and analytics
 *
 * - **Use `CommandHistory`** (see CommandHistory.ts) for:
 *   - Lightweight command-only tracking
 *   - UI features like command history popup
 *   - Simple execution tracking without context
 *   - End-user facing features
 *
 * @module Logging
 */
/**
 * Details about a matched command within a transcription.
 * Records how the command was matched and its execution result.
 */
interface MatchedCommand {
    /** Name of the command that was matched */
    commandName: string;
    /** The actual word from the transcription that triggered the match */
    matchedWord: string;
    /** The synonym word that was used to match (only for synonym matches) */
    matchedSynonym?: string;
    /** Source of the match */
    synonymSource: 'direct' | 'library-synonym' | 'api-synonym' | 'phonetic';
    /** Confidence level of the match (0-1 scale, where 1 is 100% confident) */
    confidence: number;
    /** Whether the command executed successfully or failed */
    status: 'success' | 'failed';
    /** Error message if command execution failed (only for failed status) */
    error?: string;
}
/**
 * A complete log entry representing one transcription and its matched commands.
 * Uses pending pattern: created → matches added → finalized.
 */
interface LogEntry {
    /** Sequential numeric ID for this log entry */
    id: number;
    /** ISO 8601 timestamp when the transcription was received */
    timestamp: string;
    /** The full transcribed text from speech recognition */
    transcriptionText: string;
    /** Speaker identifier (only available in online multi-speaker mode) */
    speakerId?: string;
    /** Array of all commands that were matched in this transcription */
    matchedCommands: MatchedCommand[];
    /** Whether this entry has been finalized (locked from further modifications) */
    finalized: boolean;
}

/**
 * AACVoiceAPI is a facade class that provides a simplified interface
 * to multiple underlying classes and modules related to voice processing.
 *
 * This class wraps functionalities such as audio input handling,
 * speech-to-text conversion, and command history management,
 * exposing them through a single, easy-to-use API.
 *
 * @example
 * // Offline
 * const api = new AACVoiceAPI();
 * await api.initiate({
 *  mode: 'offline',
 *  modelUrl: 'models/whisper-tiny.bin',
 *  language: 'en'
 *  });
 *
 * * @example
 * // Online
 * const api = new AACVoiceAPI();
 * await api.initiate({
 *  mode: 'online',
 *  backendUrl: 'http://localhost:8000'
 *  });
 *
 * @class
 */
interface voiceAPIConfig {
    mode: 'offline' | 'online';
    modelUrl: string;
    language?: string;
    useSpeakerSeparation?: boolean;
    confidenceThreshold?: number;
    usePhoneticMatching?: boolean;
    logConfidenceScores?: boolean;
}
declare class AACVoiceAPI {
    private converter;
    private mapping;
    private currentMode;
    private isCurrentlyListening;
    private domain;
    constructor();
    /**
 * @typedef {Object} voiceAPIConfig
 * @property {'offline' | 'online'} mode
 *     The mode the API should operate in.
 * @property {string} modelUrl
 *     The URL of the model.
 * @property {string} [language]
 *     Language the model was trained in. Required for 'offline' mode
 * @property {boolean} [useSpeakerSeparation]
 *     Optional - Enables speaker separation if supported. Only available in 'online' mode
 * @property {number} [confidenceThreshold]
 *     Optional - Minimum confidence required to determine a phonetic match. (Decimal format [0-1])
 * @property {boolean} [usePhoneticMatching]
 *     Optional - Enables phonetic matching for recognition.
 * @property {boolean} [logConfidenceScores]
 *     Optional - Enables logging of confidence values.
 *
 * @param {voiceAPIConfig} config
 *     Configuration object used to initialize the API.
 *
 * @throws {Error}
 *     Throws an error if `modelUrl` is not provided when initiating in online mode.
 */
    initiate(config: voiceAPIConfig): Promise<void>;
    /**
     * Initialize online mode for single speaker
     */
    initiateOnlineSingleSpeaker(domainName: string): Promise<void>;
    /**
     * Initialize online mode with speaker separation
     */
    initiateOnlineMultiSpeaker(domainName: string): Promise<void>;
    /**
     * Switches between single speaker and multi-speaker mode for online mode
     * Automatically restarts listening if currently active
     *
     * @param useSpeakerSeparation Whether to use speaker separation
     * @throws {Error} If not in online mode or not initialized
     *
     * @example
     * // Switch to multi speaker
     * api.switchSpeakerMode(true);
     *
     * // Switch back to single speaker
     * api.switchSpeakerMode(false);
     */
    switchSpeakerMode(useSpeakerSeparation: boolean): void;
    toggleSpeakerMode(): void;
    /**
     * Allows the user to start speaking into the microphone and initiate game commands
     *
     */
    start(): void;
    /**
     * Stops all voice recording and transcription
     *
     */
    stop(): void;
    /**
     * Retrieves the full transcription history from the Whisper module.
     *
     * @returns {string[]} An array of transcription log entries,
     * each containing the transcribed text and its corresponding timestamp.
     */
    getTranscriptionLogs(): string[];
    /**
     * Displays all game Commands in a toggleable modal
     *
     */
    displayCommandHistory(): void;
    /**
     * Adds a voice command to the system.
     * Optionally fetches and registers synonyms from DataMuse API.
     *
     * @param {string} name: The name of the command that the user needs to speak.
     * @param {Function} action: A callback function that executes when the command is triggered.
     * @param {string} options.description: A short explanation of what the command does.
     * @param {boolean} options.active: Whether the command is currently active. (true or false)
     * @param {boolean} options.fetchSynonyms: Whether to automatically fetch synonyms (default: true)
     * @returns Promise<CommandAddResult> Result object with command and synonym information
     */
    addVoiceCommand(name: string, action: () => void, options?: {
        description?: string;
        active?: boolean;
        fetchSynonyms?: boolean;
        numberOfSynonyms?: number;
    }): Promise<CommandAddResult>;
    /**
     * Allows user to remove a command from the system
     *
     * @param name The name of the command that is to be removed from the list
     * @returns true if successfully removed
     */
    removeVoiceCommand(name: string): boolean;
    /**
     * Allows user to check if a game command has already been added
     *
     * @param name The name of the command that is being checked
     * @returns true if found
     */
    isRegistered(name: string): boolean;
    /**
     * Allows user to see a list of all known game commands
     *
     * @returns a list of all known game commands
     */
    getCommands(): string[] | [];
    /**
     * Allows user to remove all game commands from system
     */
    clearCommands(): void;
    /**
     * Gets the current mode of operation
     *
     * @returns The current mode ('offline' or 'online'), or null if not initialized
     */
    getMode(): string;
    /**
     * Tells the user if speaker separation toggle is on
     *
     * @returns The current status of whether speaker separation is on or off
     */
    isUsingSpeakerSeparation(): boolean | null;
    /**
     * Exports all finalized session logs as a formatted JSON string.
     *
     * Use this method to get comprehensive analytics data including:
     * - Full transcription text with timestamps
     * - Matched commands with confidence scores
     * - Synonym resolution details (library vs API)
     * - Error messages for failed command executions
     * - Speaker IDs (in multi-speaker mode)
     *
     * @returns Pretty-printed JSON string of all session logs
     *
     * @example
     * ```typescript
     * const json = api.exportSessionLogs();
     * console.log(json);
     * ```
     */
    exportSessionLogs(): string;
    /**
     * Gets the raw log data as a JavaScript object.
     * Useful for Node.js environments where manual file operations are needed.
     *
     * @returns Array of log entry objects
     *
     * @example
     * ```typescript
     * // Node.js usage
     * const fs = require('fs');
     * const logData = api.getSessionLogsData();
     * fs.writeFileSync('session-logs.json', JSON.stringify(logData, null, 2));
     * ```
     */
    getSessionLogsData(): LogEntry[];
    /**
     * Downloads session logs as a JSON file (browser only).
     * Triggers a browser download with the specified filename.
     *
     * Note: This method only works in browser environments.
     * For Node.js, use `getSessionLogsData()` instead.
     *
     * @param filename - Name of the file to download (default: 'aac-session-log.json')
     *
     * @example
     * ```typescript
     * // Download logs with default filename
     * api.downloadLogsAsJSON();
     *
     * // Download with custom filename
     * api.downloadLogsAsJSON('my-session-2024-01-15.json');
     * ```
     */
    downloadLogsAsJSON(filename?: string): void;
    /**
     * Gets all finalized session logs.
     * Returns detailed information about each transcription and matched commands.
     *
     * Use `Logger` for comprehensive analytics data.
     * Use `CommandHistory` (via displayCommandHistory()) for simple UI display.
     *
     * @returns Array of finalized log entries
     *
     * @example
     * ```typescript
     * const logs = api.getSessionLogs();
     * logs.forEach(log => {
     *   console.log(`[${log.timestamp}] "${log.transcriptionText}"`);
     *   console.log(`  Matched ${log.matchedCommands.length} command(s)`);
     * });
     * ```
     */
    getSessionLogs(): LogEntry[];
    /**
     * Clears all session logs.
     * Removes all stored transcriptions, matched commands, and resets the log counter.
     *
     * Note: This does NOT clear CommandHistory. Use displayCommandHistory() to
     * access the separate command-only history.
     *
     * @example
     * ```typescript
     * api.clearSessionLogs();
     * console.log('Session logs cleared');
     * ```
     */
    clearSessionLogs(): void;
}

export { AACVoiceAPI };