seatalk-call 0.0.0-alpha1

package/index.js

@@ -0,0 +1,1448 @@
+// index.js
+//
+// seatalk-call: A simulated library for managing SeaTalk calls using standard JavaScript.
+// This package provides a conceptual framework for initiating, joining, leaving, and managing
+// participants within a simulated SeaTalk call environment. It demonstrates patterns for
+// state management, event handling, input validation, and error handling without relying
+// on external dependencies, focusing purely on standard built-in JavaScript features.
+// It simulates interactions with a SeaTalk call service through internal state changes
+// and delayed promise resolutions.
+
+// --- Constants ---
+
+/**
+ * @typedef {'IDLE' | 'CONNECTING' | 'CONNECTED' | 'DISCONNECTING' | 'ERROR'} ClientState
+ */
+
+/**
+ * @typedef {'INITIALIZING' | 'RINGING' | 'ACTIVE' | 'ENDED' | 'FAILED'} CallState
+ */
+
+/**
+ * @typedef {'participantJoined' | 'participantLeft' | 'callEnded' | 'localMuteStatusChanged' | 'remoteMuteStatusChanged' | 'error'} CallEventType
+ */
+
+/**
+ * @typedef {'clientStateChanged' | 'callStarted' | 'callEnded' | 'callFailed'} ClientEventType
+ */
+
+/**
+ * Standard delays to simulate network latency or processing time.
+ */
+const SIMULATED_DELAY_MS = 150;
+const SIMULATED_ASYNC_PROCESSING_MS = 50;
+
+/**
+ * Default client state upon initialization.
+ * @type {ClientState}
+ */
+const DEFAULT_CLIENT_STATE = 'IDLE';
+
+/**
+ * Maximum number of participants allowed in a simulated call.
+ */
+const MAX_PARTICIPANTS_PER_CALL = 50;
+
+/**
+ * Standard error messages.
+ */
+const ERROR_MESSAGES = {
+    NOT_CONFIGURED: 'Client is not configured. Call configure() first.',
+    INVALID_CONFIG: 'Invalid configuration provided.',
+    INVALID_PARTICIPANT_ID: 'Invalid participant ID. Must be a non-empty string or number.',
+    INVALID_PARTICIPANT_LIST: 'Invalid participant list. Must be an array of valid participant IDs.',
+    MAX_PARTICIPANTS_EXCEEDED: `Maximum participants (${MAX_PARTICIPANTS_PER_CALL}) exceeded.`,
+    CALL_NOT_FOUND: 'Call not found with the given ID.',
+    NOT_IN_CALL: 'Cannot perform action: Not currently in the specified call.',
+    ALREADY_IN_CALL: 'Cannot perform action: Already in the specified call.',
+    INVALID_CALL_STATE: 'Cannot perform action in the current call state.',
+    ALREADY_MUTED: 'Local participant is already muted.',
+    NOT_MUTED: 'Local participant is not currently muted.',
+    INVALID_CALL_ID: 'Invalid call ID. Must be a non-empty string.',
+    INVALID_EVENT_TYPE: 'Invalid event type provided for listener registration.',
+    INVALID_LISTENER: 'Invalid listener provided. Must be a function.',
+    PARTICIPANT_ALREADY_IN_CALL: 'Participant is already in the call.',
+    PARTICIPANT_NOT_IN_CALL: 'Participant is not in the call.',
+    NO_LOCAL_USER_CONFIGURED: 'Local user ID is not configured.',
+};
+
+// --- Custom Error Classes ---
+
+/**
+ * Base custom error for Seatalk Call operations.
+ */
+class SeatalkCallError extends Error {
+    /**
+     * @param {string} message - The error message.
+     * @param {string} [code] - An optional error code.
+     */
+    constructor(message, code) {
+        super(message);
+        this.name = 'SeatalkCallError';
+        this.code = code || 'SEATALK_CALL_ERROR';
+        // Ensure the stack trace is captured correctly in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SeatalkCallError);
+        }
+    }
+}
+
+/**
+ * Error specifically for invalid client configuration.
+ */
+class ClientConfigurationError extends SeatalkCallError {
+    /**
+     * @param {string} message - The error message.
+     */
+    constructor(message) {
+        super(message, 'CLIENT_CONFIG_ERROR');
+        this.name = 'ClientConfigurationError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ClientConfigurationError);
+        }
+    }
+}
+
+/**
+ * Error specifically for operations attempted in an invalid call state.
+ */
+class InvalidCallStateError extends SeatalkCallError {
+    /**
+     * @param {string} message - The error message.
+     * @param {string} currentCallState - The state of the call when the error occurred.
+     * @param {string[]} [allowedStates] - Optional array of states that would allow the action.
+     */
+    constructor(message, currentCallState, allowedStates) {
+        super(message, 'INVALID_CALL_STATE');
+        this.name = 'InvalidCallStateError';
+        this.currentCallState = currentCallState;
+        this.allowedStates = allowedStates;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, InvalidCallStateError);
+        }
+    }
+}
+
+/**
+ * Error specifically for invalid input parameters.
+ */
+class InvalidInputError extends SeatalkCallError {
+    /**
+     * @param {string} message - The error message.
+     */
+    constructor(message) {
+        super(message, 'INVALID_INPUT_ERROR');
+        this.name = 'InvalidInputError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, InvalidInputError);
+        }
+    }
+}
+
+/**
+ * Error specifically when a call could not be found.
+ */
+class CallNotFoundError extends SeatalkCallError {
+    /**
+     * @param {string} callId - The ID of the call that was not found.
+     */
+    constructor(callId) {
+        super(ERROR_MESSAGES.CALL_NOT_FOUND, 'CALL_NOT_FOUND');
+        this.name = 'CallNotFoundError';
+        this.callId = callId;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CallNotFoundError);
+        }
+    }
+}
+
+/**
+ * Error specifically when a participant is not found in a call.
+ */
+class ParticipantNotFoundError extends SeatalkCallError {
+    /**
+     * @param {string | number} participantId - The ID of the participant not found.
+     * @param {string} callId - The ID of the call.
+     */
+    constructor(participantId, callId) {
+        super(ERROR_MESSAGES.PARTICIPANT_NOT_IN_CALL, 'PARTICIPANT_NOT_FOUND');
+        this.name = 'ParticipantNotFoundError';
+        this.participantId = participantId;
+        this.callId = callId;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ParticipantNotFoundError);
+        }
+    }
+}
+
+// --- Helper Functions ---
+
+/**
+ * Simulates an asynchronous delay.
+ * @param {number} ms - The number of milliseconds to wait.
+ * @returns {Promise<void>} A promise that resolves after the specified delay.
+ */
+function delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Generates a simple unique ID.
+ * In a real scenario, this would likely come from a server API response.
+ * @returns {string} A unique ID string.
+ */
+function generateUniqueId() {
+    return 'call-' + Date.now() + '-' + Math.random().toString(36).substr(2, 9);
+}
+
+/**
+ * Gets the current timestamp in ISO format.
+ * @returns {string} Current ISO timestamp string.
+ */
+function getCurrentTimestamp() {
+    return new Date().toISOString();
+}
+
+/**
+ * Checks if a value is a valid participant ID (non-empty string or number).
+ * @param {*} id - The value to check.
+ * @returns {boolean} True if the value is a valid participant ID.
+ */
+function isValidParticipantId(id) {
+    return (typeof id === 'string' && id.trim().length > 0) || (typeof id === 'number' && !isNaN(id));
+}
+
+/**
+ * Validates an array of participant IDs.
+ * @param {any[]} participants - The array to validate.
+ * @throws {InvalidInputError} If the array is not valid or contains invalid IDs.
+ */
+function validateParticipantList(participants) {
+    if (!Array.isArray(participants) || participants.length === 0) {
+        throw new InvalidInputError(ERROR_MESSAGES.INVALID_PARTICIPANT_LIST);
+    }
+    for (const participantId of participants) {
+        if (!isValidParticipantId(participantId)) {
+            throw new InvalidInputError(`${ERROR_MESSAGES.INVALID_PARTICIPANT_LIST}: Contains invalid ID '${participantId}'`);
+        }
+    }
+    if (participants.length > MAX_PARTICIPANTS_PER_CALL) {
+         throw new InvalidInputError(`${ERROR_MESSAGES.MAX_PARTICIPANTS_EXCEEDED} Found ${participants.length}`);
+    }
+}
+
+/**
+ * Validates a call ID.
+ * @param {*} callId - The value to check.
+ * @throws {InvalidInputError} If the call ID is invalid.
+ */
+function validateCallId(callId) {
+    if (typeof callId !== 'string' || callId.trim().length === 0) {
+        throw new InvalidInputError(ERROR_MESSAGES.INVALID_CALL_ID);
+    }
+}
+
+/**
+ * Checks if the client is configured.
+ * @param {object | null} config - The client configuration object.
+ * @returns {boolean} True if the client configuration seems valid.
+ */
+function isClientConfigured(config) {
+    return config !== null && typeof config === 'object' && typeof config.localUserId !== 'undefined';
+}
+
+/**
+ * Validates the provided client configuration.
+ * @param {object} config - The configuration object.
+ * @throws {ClientConfigurationError} If the configuration is invalid.
+ */
+function validateConfiguration(config) {
+    if (typeof config !== 'object' || config === null) {
+        throw new ClientConfigurationError(ERROR_MESSAGES.INVALID_CONFIG + ': Configuration must be an object.');
+    }
+    if (!isValidParticipantId(config.localUserId)) {
+         throw new ClientConfigurationError(ERROR_MESSAGES.INVALID_CONFIG + ': Missing or invalid `localUserId`.');
+    }
+    // Add checks for other potential config properties if needed
+    // e.g., if (typeof config.apiEndpoint !== 'string' || config.apiEndpoint.length === 0) { ... }
+}
+
+
+/**
+ * Formats call duration from start and end timestamps.
+ * @param {string} startTimeIso - ISO string for start time.
+ * @param {string | null} endTimeIso - ISO string for end time, or null if ongoing.
+ * @returns {string} Formatted duration string (e.g., "0h 5m 30s") or "Ongoing".
+ */
+function formatCallDuration(startTimeIso, endTimeIso) {
+    try {
+        const start = new Date(startTimeIso);
+        const end = endTimeIso ? new Date(endTimeIso) : new Date();
+        const durationMs = end.getTime() - start.getTime();
+
+        if (durationMs < 0) return "Invalid Duration"; // Should not happen
+
+        const seconds = Math.floor((durationMs / 1000) % 60);
+        const minutes = Math.floor((durationMs / (1000 * 60)) % 60);
+        const hours = Math.floor((durationMs / (1000 * 60 * 60)) % 24);
+
+        const parts = [];
+        if (hours > 0) parts.push(`${hours}h`);
+        if (minutes > 0 || hours > 0) parts.push(`${minutes}m`); // Include minutes if hours > 0 or minutes > 0
+        parts.push(`${seconds}s`);
+
+        return parts.join(' ');
+    } catch (e) {
+        // Handle potential invalid date strings gracefully
+        return "Calculation Error";
+    }
+}
+
+/**
+ * Simple logger utility.
+ */
+const Logger = {
+    /**
+     * Logs an informational message.
+     * @param {string} message - The message to log.
+     * @param {any} [data] - Optional data to log with the message.
+     */
+    info(message, data) {
+        console.log(`[SeatalkCallClient][INFO] ${message}`, data !== undefined ? data : '');
+    },
+
+    /**
+     * Logs a warning message.
+     * @param {string} message - The message to log.
+     * @param {any} [data] - Optional data to log with the message.
+     */
+    warn(message, data) {
+        console.warn(`[SeatalkCallClient][WARN] ${message}`, data !== undefined ? data : '');
+    },
+
+    /**
+     * Logs an error message.
+     * @param {string} message - The message to log.
+     * @param {Error | any} [err] - The error object or data related to the error.
+     */
+    error(message, err) {
+        console.error(`[SeatalkCallClient][ERROR] ${message}`, err);
+    }
+};
+
+/**
+ * Checks if a call state indicates an active call session where participants are connected.
+ * @param {CallState} state - The call state to check.
+ * @returns {boolean} True if the state is 'ACTIVE'.
+ */
+function isCallActiveState(state) {
+    return state === 'ACTIVE';
+}
+
+/**
+ * Checks if a call state indicates the call is still in progress (not ended or failed).
+ * @param {CallState} state - The call state to check.
+ * @returns {boolean} True if the state is 'INITIALIZING', 'RINGING', or 'ACTIVE'.
+ */
+function isCallInProgressState(state) {
+    return state === 'INITIALIZING' || state === 'RINGING' || state === 'ACTIVE';
+}
+
+
+// --- Core Class ---
+
+/**
+ * Represents a simulated Seatalk Call session.
+ * This internal class holds the state for a single call.
+ */
+class CallSession {
+    /**
+     * @param {string} callId - Unique identifier for the call.
+     * @param {string | number} hostId - The ID of the user who initiated the call.
+     * @param {(string | number)[]} initialParticipants - Participants initially invited or in the call.
+     * @param {string | number} localUserId - The ID of the current user running the client.
+     */
+    constructor(callId, hostId, initialParticipants, localUserId) {
+        this.callId = callId;
+        this.hostId = hostId;
+        this.localUserId = localUserId;
+        /** @type {CallState} */
+        this.state = 'INITIALIZING';
+        /** @type {Set<string | number>} */
+        this.participants = new Set(initialParticipants.map(String)); // Use Set for unique participants
+        /** @type {Map<string | number, boolean>} */
+        this.participantMuteStatus = new Map(); // participantId -> isMuted
+        /** @type {string | null} */
+        this.startTime = null;
+        /** @type {string | null} */
+        this.endTime = null;
+        /** @type {string | null} */
+        this.failureReason = null;
+
+        // Initialize mute status for all participants
+        this.participants.forEach(pId => this.participantMuteStatus.set(pId, false)); // Assume everyone starts unmuted
+
+        Logger.info(`Created new call session ${this.callId} by host ${this.hostId} with initial participants: ${Array.from(this.participants).join(', ')}`);
+    }
+
+    /**
+     * Updates the state of the call session.
+     * @param {CallState} newState - The new state for the call.
+     */
+    updateState(newState) {
+        if (this.state === newState) {
+            Logger.info(`Call ${this.callId}: State already ${newState}. No change.`);
+            return;
+        }
+        Logger.info(`Call ${this.callId}: State changing from ${this.state} to ${newState}`);
+        this.state = newState;
+
+        if (newState === 'ACTIVE' && this.startTime === null) {
+            this.startTime = getCurrentTimestamp();
+            Logger.info(`Call ${this.callId}: Call started at ${this.startTime}`);
+        } else if (newState === 'ENDED' || newState === 'FAILED') {
+            this.endTime = getCurrentTimestamp();
+            Logger.info(`Call ${this.callId}: Call ended at ${this.endTime}. Duration: ${formatCallDuration(this.startTime || getCurrentTimestamp(), this.endTime)}`);
+            if (newState === 'FAILED' && !this.failureReason) {
+                 this.failureReason = 'Unknown failure'; // Default if not set explicitly
+            }
+        }
+    }
+
+    /**
+     * Checks if the local user is a participant in this call session.
+     * @returns {boolean}
+     */
+    isLocalUserInCall() {
+        return this.participants.has(String(this.localUserId));
+    }
+
+    /**
+     * Adds a participant to the session's participant list and initializes their mute status.
+     * @param {string | number} participantId - The ID of the participant to add.
+     * @returns {boolean} True if the participant was added, false if they were already present.
+     */
+    addParticipant(participantId) {
+        const pIdStr = String(participantId);
+        if (this.participants.has(pIdStr)) {
+            Logger.warn(`Call ${this.callId}: Participant ${pIdStr} already in call.`);
+            return false;
+        }
+        this.participants.add(pIdStr);
+        this.participantMuteStatus.set(pIdStr, false); // Assume new participants join unmuted
+        Logger.info(`Call ${this.callId}: Added participant ${pIdStr}. Total participants: ${this.participants.size}`);
+        return true;
+    }
+
+    /**
+     * Removes a participant from the session's participant list.
+     * @param {string | number} participantId - The ID of the participant to remove.
+     * @returns {boolean} True if the participant was removed, false if they were not present.
+     */
+    removeParticipant(participantId) {
+        const pIdStr = String(participantId);
+        if (!this.participants.has(pIdStr)) {
+             Logger.warn(`Call ${this.callId}: Participant ${pIdStr} not found in call.`);
+            return false;
+        }
+        this.participants.delete(pIdStr);
+        this.participantMuteStatus.delete(pIdStr);
+        Logger.info(`Call ${this.callId}: Removed participant ${pIdStr}. Total participants: ${this.participants.size}`);
+        return true;
+    }
+
+    /**
+     * Gets the current mute status of a participant.
+     * @param {string | number} participantId - The ID of the participant.
+     * @returns {boolean | undefined} True if muted, false if unmuted, undefined if participant not found.
+     */
+    getParticipantMuteStatus(participantId) {
+        const pIdStr = String(participantId);
+        return this.participantMuteStatus.get(pIdStr);
+    }
+
+    /**
+     * Sets the mute status for a participant.
+     * @param {string | number} participantId - The ID of the participant.
+     * @param {boolean} isMuted - The new mute status.
+     * @returns {boolean} True if the status was changed, false if the participant was not found or status was already the same.
+     */
+    setParticipantMuteStatus(participantId, isMuted) {
+        const pIdStr = String(participantId);
+        if (!this.participantMuteStatus.has(pIdStr)) {
+            Logger.warn(`Call ${this.callId}: Cannot set mute status for participant ${pIdStr} not in call.`);
+            return false;
+        }
+        if (this.participantMuteStatus.get(pIdStr) === isMuted) {
+             Logger.info(`Call ${this.callId}: Participant ${pIdStr} mute status already ${isMuted}. No change.`);
+             return false;
+        }
+        this.participantMuteStatus.set(pIdStr, isMuted);
+        Logger.info(`Call ${this.callId}: Participant ${pIdStr} mute status set to ${isMuted}`);
+        return true;
+    }
+
+    /**
+     * Gets a snapshot of the current call details.
+     * @returns {object} An object containing call details.
+     */
+    getDetails() {
+        return {
+            callId: this.callId,
+            hostId: this.hostId,
+            state: this.state,
+            participants: Array.from(this.participants),
+            participantMuteStatus: Object.fromEntries(this.participantMuteStatus),
+            localUserInCall: this.isLocalUserInCall(),
+            localUserIsMuted: this.participantMuteStatus.get(String(this.localUserId)) || false,
+            startTime: this.startTime,
+            endTime: this.endTime,
+            duration: this.startTime ? formatCallDuration(this.startTime, this.endTime) : 'N/A',
+            failureReason: this.failureReason,
+        };
+    }
+}
+
+
+/**
+ * Main client class for interacting with simulated SeaTalk call features.
+ */
+class SeatalkCallClient {
+
+    constructor() {
+        /** @type {object | null} */
+        this._configuration = null;
+        /** @type {ClientState} */
+        this._clientState = DEFAULT_CLIENT_STATE;
+        /** @type {Map<string, CallSession>} */
+        this._activeCalls = new Map(); // Maps callId to CallSession instance
+        /** @type {Map<string, Function[]>} */
+        this._eventListeners = new Map(); // Maps eventType to an array of listener functions
+
+        Logger.info('SeatalkCallClient initialized.');
+    }
+
+    /**
+     * Configures the client with necessary settings.
+     * Must be called before initiating or joining calls.
+     * @param {object} config - Configuration object.
+     * @param {string | number} config.localUserId - The ID of the user using this client instance.
+     * // Add other simulated config like apiEndpoint, apiKey, etc.
+     * @throws {ClientConfigurationError} If the configuration is invalid.
+     * @throws {InvalidCallStateError} If configuration is attempted while client is not IDLE.
+     */
+    configure(config) {
+        if (this._clientState !== 'IDLE') {
+            throw new InvalidCallStateError(`Cannot configure client while state is ${this._clientState}. Must be IDLE.`, this._clientState, ['IDLE']);
+        }
+        validateConfiguration(config);
+
+        // Simulate configuration process
+        this._setClientState('CONNECTING');
+        this._configuration = config;
+        Logger.info('Client configuration received. Simulating connection.');
+
+        // Simulate async connection success
+        delay(SIMULATED_DELAY_MS)
+            .then(() => {
+                this._setClientState('CONNECTED');
+                Logger.info('Client successfully configured and connected.');
+            })
+            .catch(err => {
+                Logger.error('Failed to configure/connect client during simulation.', err);
+                this._configuration = null; // Reset config on simulated failure
+                this._setClientState('ERROR'); // Or DISCONNECTED, depending on desired state
+                this._emit('error', new SeatalkCallError('Simulated client connection failed.', 'SIMULATED_CONNECT_FAILED'));
+            });
+    }
+
+    /**
+     * Gets the current client state.
+     * @returns {ClientState} The current state.
+     */
+    getClientState() {
+        return this._clientState;
+    }
+
+    /**
+     * Internal method to update client state and emit event.
+     * @param {ClientState} newState - The new state.
+     */
+    _setClientState(newState) {
+        if (this._clientState === newState) {
+            return;
+        }
+        const oldState = this._clientState;
+        this._clientState = newState;
+        Logger.info(`Client state changed: ${oldState} -> ${newState}`);
+        this._emit('clientStateChanged', { oldState, newState });
+    }
+
+    /**
+     * Registers a listener function for a specific event type.
+     * @param {ClientEventType | CallEventType} eventType - The type of event to listen for.
+     * @param {Function} listener - The function to call when the event occurs.
+     * @throws {InvalidInputError} If eventType or listener is invalid.
+     */
+    on(eventType, listener) {
+        if (typeof eventType !== 'string' || eventType.length === 0) {
+            throw new InvalidInputError(ERROR_MESSAGES.INVALID_EVENT_TYPE);
+        }
+        if (typeof listener !== 'function') {
+            throw new InvalidInputError(ERROR_MESSAGES.INVALID_LISTENER);
+        }
+
+        if (!this._eventListeners.has(eventType)) {
+            this._eventListeners.set(eventType, []);
+        }
+        const listeners = this._eventListeners.get(eventType);
+        if (!listeners.includes(listener)) {
+            listeners.push(listener);
+            Logger.info(`Registered listener for event: ${eventType}`);
+        } else {
+             Logger.warn(`Listener already registered for event: ${eventType}`);
+        }
+    }
+
+    /**
+     * Removes a registered listener function for a specific event type.
+     * @param {ClientEventType | CallEventType} eventType - The type of event the listener is for.
+     * @param {Function} listener - The listener function to remove.
+     * @returns {boolean} True if the listener was found and removed, false otherwise.
+     * @throws {InvalidInputError} If eventType or listener is invalid.
+     */
+    off(eventType, listener) {
+         if (typeof eventType !== 'string' || eventType.length === 0) {
+            throw new InvalidInputError(ERROR_MESSAGES.INVALID_EVENT_TYPE);
+        }
+        if (typeof listener !== 'function') {
+            throw new InvalidInputError(ERROR_MESSAGES.INVALID_LISTENER);
+        }
+
+        if (!this._eventListeners.has(eventType)) {
+            Logger.warn(`No listeners found for event type: ${eventType}`);
+            return false;
+        }
+
+        const listeners = this._eventListeners.get(eventType);
+        const index = listeners.indexOf(listener);
+
+        if (index === -1) {
+             Logger.warn(`Listener not found for event type: ${eventType}`);
+            return false;
+        }
+
+        listeners.splice(index, 1);
+        Logger.info(`Removed listener for event: ${eventType}`);
+        if (listeners.length === 0) {
+            this._eventListeners.delete(eventType);
+            Logger.info(`No more listeners for event type: ${eventType}`);
+        }
+        return true;
+    }
+
+    /**
+     * Internal method to emit an event to all registered listeners.
+     * @param {string} eventType - The type of event to emit.
+     * @param {any} data - The data to pass to the listeners.
+     */
+    _emit(eventType, data) {
+        const listeners = this._eventListeners.get(eventType);
+        if (listeners) {
+            Logger.info(`Emitting event: ${eventType}`, data);
+            // Call listeners asynchronously to prevent blocking if a listener is slow
+            listeners.forEach(listener => {
+                setTimeout(() => {
+                    try {
+                        listener(data);
+                    } catch (e) {
+                        Logger.error(`Error in listener for event ${eventType}`, e);
+                        // Optionally, emit an internal error event here
+                    }
+                }, SIMULATED_ASYNC_PROCESSING_MS);
+            });
+        } else {
+             Logger.info(`No listeners for event: ${eventType}`);
+        }
+    }
+
+     /**
+     * Internal method to ensure client is configured and connected.
+     * @throws {SeatalkCallError} If client is not configured or not in a connected state.
+     */
+    _ensureClientReady() {
+        if (!isClientConfigured(this._configuration)) {
+            throw new SeatalkCallError(ERROR_MESSAGES.NOT_CONFIGURED);
+        }
+         if (this._clientState !== 'CONNECTED') {
+             throw new InvalidCallStateError(`Client is not CONNECTED. Current state: ${this._clientState}`, this._clientState, ['CONNECTED']);
+         }
+         if (!isValidParticipantId(this._configuration.localUserId)) {
+              throw new ClientConfigurationError(ERROR_MESSAGES.NO_LOCAL_USER_CONFIGURED);
+         }
+    }
+
+    /**
+     * Internal method to find an active call session by ID.
+     * @param {string} callId - The ID of the call.
+     * @returns {CallSession} The found call session.
+     * @throws {CallNotFoundError} If the call is not found or not active.
+     */
+    _findCall(callId) {
+        validateCallId(callId);
+        const call = this._activeCalls.get(callId);
+        if (!call) {
+            Logger.warn(`Attempted operation on non-existent call: ${callId}`);
+            throw new CallNotFoundError(callId);
+        }
+        // Optionally check if call is in a state where operations are allowed (e.g., not ENDED/FAILED)
+        if (!isCallInProgressState(call.state)) {
+             Logger.warn(`Attempted operation on call ${callId} in invalid state: ${call.state}`);
+             throw new InvalidCallStateError(`Call ${callId} is in state ${call.state}. Cannot perform this action.`, call.state);
+        }
+        return call;
+    }
+
+    /**
+     * Internal method to simulate receiving an update or event for a specific call from the service.
+     * In a real library, this would be driven by a WebSocket or server-sent event listener.
+     * Here, we trigger state changes and events internally.
+     * @param {string} callId - The ID of the call receiving the update.
+     * @param {object} update - The simulated update data.
+     * @param {'stateChange' | 'participantJoin' | 'participantLeave' | 'muteChange' | 'callEnded' | 'callFailed'} update.type - Type of update.
+     * @param {any} [update.data] - Data associated with the update (e.g., new state, participant ID).
+     */
+    _simulateIncomingUpdate(callId, update) {
+        // Wrap in a simulated async delay to mimic network transport
+        delay(SIMULATED_DELAY_MS).then(() => {
+            const call = this._activeCalls.get(callId);
+            if (!call || !isCallInProgressState(call.state)) {
+                Logger.warn(`Received simulated update for non-active or non-existent call ${callId}. Update ignored.`, update);
+                return; // Ignore updates for calls that are ended or not found
+            }
+
+            Logger.info(`Processing simulated incoming update for call ${callId}: Type=${update.type}`, update.data);
+
+            try {
+                const localUserId = String(this._configuration.localUserId);
+                let eventData;
+
+                switch (update.type) {
+                    case 'stateChange':
+                        /** @type {CallState} */
+                        const newState = update.data;
+                        call.updateState(newState);
+                        // Emit client-level call event if state change is significant
+                        if (newState === 'ACTIVE') {
+                            this._emit('callStarted', call.getDetails());
+                        } else if (newState === 'ENDED') {
+                            this._emit('callEnded', call.getDetails());
+                            this._cleanupCall(callId); // Remove from active calls map
+                        } else if (newState === 'FAILED') {
+                            call.failureReason = update.data.reason || 'Unknown error';
+                             this._emit('callFailed', call.getDetails());
+                             this._cleanupCall(callId); // Remove from active calls map
+                        }
+                        // No specific call event for general stateChange unless tied to specific actions
+                        break;
+
+                    case 'participantJoin':
+                        const joinedParticipantId = String(update.data.participantId);
+                         // Ensure participant ID is not local user if this update is triggered by local join
+                         if (joinedParticipantId === localUserId) {
+                             // Local join is handled by the local API call method, not simulated incoming events
+                             Logger.info(`Simulated participantJoin for local user ${localUserId} ignored.`);
+                             return;
+                         }
+                        if (call.addParticipant(joinedParticipantId)) {
+                             eventData = {
+                                 callId: call.callId,
+                                 participantId: joinedParticipantId,
+                                 timestamp: getCurrentTimestamp(),
+                             };
+                             this._emit('participantJoined', eventData);
+                        }
+                        break;
+
+                    case 'participantLeave':
+                        const leftParticipantId = String(update.data.participantId);
+                        if (leftParticipantId === localUserId) {
+                             // Local leave is handled by the local API call method
+                             Logger.info(`Simulated participantLeave for local user ${localUserId} ignored.`);
+                             return;
+                        }
+                        if (call.removeParticipant(leftParticipantId)) {
+                            eventData = {
+                                callId: call.callId,
+                                participantId: leftParticipantId,
+                                timestamp: getCurrentTimestamp(),
+                            };
+                            this._emit('participantLeft', eventData);
+                        }
+                        break;
+
+                    case 'muteChange':
+                        const muteParticipantId = String(update.data.participantId);
+                        const isMuted = Boolean(update.data.isMuted);
+                        if (call.setParticipantMuteStatus(muteParticipantId, isMuted)) {
+                            eventData = {
+                                callId: call.callId,
+                                participantId: muteParticipantId,
+                                isMuted: isMuted,
+                                timestamp: getCurrentTimestamp(),
+                            };
+                             if (muteParticipantId === localUserId) {
+                                // This should ideally not happen for local user via simulated remote update,
+                                // but handle defensively.
+                                this._emit('localMuteStatusChanged', eventData);
+                            } else {
+                                this._emit('remoteMuteStatusChanged', eventData);
+                            }
+                        }
+                        break;
+
+                     case 'callEnded':
+                         call.updateState('ENDED');
+                         this._emit('callEnded', call.getDetails());
+                         this._cleanupCall(callId); // Remove from active calls map
+                         break;
+
+                     case 'callFailed':
+                        call.failureReason = update.data.reason || 'Simulated failure';
+                        call.updateState('FAILED');
+                        this._emit('callFailed', call.getDetails());
+                        this._cleanupCall(callId); // Remove from active calls map
+                        break;
+
+                    default:
+                        Logger.warn(`Received simulated update of unknown type: ${update.type}`);
+                        break;
+                }
+            } catch (e) {
+                Logger.error(`Error processing simulated incoming update for call ${callId}`, e);
+                 this._emit('error', new SeatalkCallError(`Error processing call update for ${callId}: ${e.message}`, 'CALL_UPDATE_PROCESSING_ERROR'));
+            }
+        }).catch(err => {
+             Logger.error(`Error during simulated update delay for call ${callId}`, err);
+        });
+    }
+
+    /**
+     * Internal method to clean up resources associated with an ended or failed call.
+     * @param {string} callId - The ID of the call to clean up.
+     */
+    _cleanupCall(callId) {
+        if (this._activeCalls.has(callId)) {
+            this._activeCalls.delete(callId);
+            Logger.info(`Cleaned up resources for call ${callId}. Removed from active calls.`);
+            // In a real scenario, might also clean up resources like WebRTC connections here.
+        } else {
+             Logger.warn(`Attempted to cleanup non-existent or already cleaned up call: ${callId}`);
+        }
+    }
+
+
+    /**
+     * Initiates a new call with a list of participants.
+     * @param {(string | number)[]} participants - Array of participant IDs to invite/start call with.
+     *                                         Must include the local user's ID.
+     * @param {object} [options] - Optional call parameters (simulated).
+     * @returns {Promise<object>} A promise that resolves with details of the initiated call session.
+     * @throws {SeatalkCallError | InvalidInputError | InvalidCallStateError} If the operation fails.
+     */
+    async startCall(participants, options = {}) {
+        this._ensureClientReady();
+
+        const localUserId = String(this._configuration.localUserId);
+
+        // Validate participants list
+        validateParticipantList(participants);
+        const participantIds = participants.map(String);
+
+        // Ensure local user is in the participant list
+        if (!participantIds.includes(localUserId)) {
+            // Automatically add local user if not present, or throw? Let's throw for strict input.
+            throw new InvalidInputError(`Participant list must include the local user ID: ${localUserId}`);
+        }
+
+        // Check if local user is already in an active call
+        const ongoingCall = Array.from(this._activeCalls.values()).find(call => call.isLocalUserInCall() && isCallInProgressState(call.state));
+        if (ongoingCall) {
+             throw new InvalidCallStateError(`Local user ${localUserId} is already in call ${ongoingCall.callId}. Cannot start a new call.`, ongoingCall.state);
+        }
+
+        // Simulate API call to start a new call
+        Logger.info(`Attempting to start new call with participants: ${participantIds.join(', ')}`, options);
+
+        await delay(SIMULATED_DELAY_MS); // Simulate network delay
+
+        // Simulate API response - a successful call initiation
+        const newCallId = generateUniqueId();
+        const hostId = localUserId; // Assume the initiator is the host
+
+        const callSession = new CallSession(newCallId, hostId, participantIds, localUserId);
+
+        // Add to active calls map immediately upon "successful API response"
+        this._activeCalls.set(newCallId, callSession);
+        Logger.info(`Simulated API success: Call ${newCallId} initiated.`);
+
+        // Simulate call state transition events
+        // Initializing -> Ringing -> Active (or FAILED)
+        callSession.updateState('RINGING');
+        // Simulate ringing state duration
+        await delay(SIMULATED_DELAY_MS * 2);
+
+        // Simulate call becoming active
+        if (Math.random() < 0.1) { // Simulate a small chance of failure during setup
+            callSession.failureReason = 'Simulated setup failure';
+            callSession.updateState('FAILED');
+            this._emit('callFailed', callSession.getDetails());
+            this._cleanupCall(newCallId);
+            throw new SeatalkCallError(`Call ${newCallId} failed during setup.`, 'SIMULATED_SETUP_FAILED');
+        } else {
+             callSession.updateState('ACTIVE');
+            this._emit('callStarted', callSession.getDetails()); // Emit client-level event
+
+            // Simulate participants joining after the call becomes active
+            for (const participantId of participantIds) {
+                if (String(participantId) !== localUserId) {
+                    // Simulate remote participant join event arriving shortly
+                    this._simulateIncomingUpdate(newCallId, {
+                        type: 'participantJoin',
+                        data: { participantId: participantId }
+                    });
+                }
+            }
+
+            // Return the details of the now active call
+            return callSession.getDetails();
+        }
+    }
+
+    /**
+     * Joins an existing call.
+     * @param {string} callId - The ID of the call to join.
+     * @returns {Promise<object>} A promise that resolves with details of the joined call session.
+     * @throws {SeatalkCallError | InvalidInputError | CallNotFoundError | InvalidCallStateError} If the operation fails.
+     */
+    async joinCall(callId) {
+        this._ensureClientReady();
+        validateCallId(callId);
+        const localUserId = String(this._configuration.localUserId);
+
+         // Check if local user is already in this call
+         const existingCall = this._activeCalls.get(callId);
+         if (existingCall && isCallInProgressState(existingCall.state) && existingCall.isLocalUserInCall()) {
+              throw new InvalidCallStateError(`Local user ${localUserId} is already in call ${callId}.`, existingCall.state);
+         }
+
+        // Check if local user is in *any* other active call
+        const ongoingCall = Array.from(this._activeCalls.values()).find(call => call.isLocalUserInCall() && isCallInProgressState(call.state));
+        if (ongoingCall && ongoingCall.callId !== callId) {
+             throw new InvalidCallStateError(`Local user ${localUserId} is already in call ${ongoingCall.callId}. Cannot join another call.`, ongoingCall.state);
+        }
+
+
+        Logger.info(`Attempting to join call: ${callId}`);
+
+        // Simulate API call to join the call
+        await delay(SIMULATED_DELAY_MS); // Simulate network delay
+
+        // Simulate API response
+        const call = this._activeCalls.get(callId); // Try finding the call again after potential delay
+        if (!call || !isCallInProgressState(call.state)) {
+             // If the call ended or was not found during the join process
+             throw new CallNotFoundError(`${ERROR_MESSAGES.CALL_NOT_FOUND} or ended during join process: ${callId}`);
+        }
+
+        // Simulate joining the call - update local state
+        const participantAdded = call.addParticipant(localUserId);
+        if (!participantAdded) {
+            // This state should ideally be caught earlier, but double-check
+             throw new InvalidCallStateError(`Local user ${localUserId} failed to join call ${callId} (already listed as participant).`, call.state);
+        }
+
+        // Simulate the service confirming the join and potentially sending participantJoin events for others
+        // In a real system, joining might also trigger state change to ACTIVE if it was RINGING and local user was needed.
+        // For simplicity here, we assume joining an ACTIVE or RINGING call.
+        if (call.state === 'RINGING') {
+             // If joining a ringing call, maybe it moves to active? Or just adds participant?
+             // Let's assume it adds participant, and a separate event might make it active.
+        } else if (call.state !== 'ACTIVE') {
+             // Joining is typically only allowed for RINGING or ACTIVE calls
+             call.removeParticipant(localUserId); // Roll back local state change
+             throw new InvalidCallStateError(`Cannot join call ${callId} in state ${call.state}. Must be RINGING or ACTIVE.`, call.state, ['RINGING', 'ACTIVE']);
+        }
+
+        // Simulate receiving participantJoin event for THIS user from the service
+        // This confirms the join server-side.
+         this._simulateIncomingUpdate(callId, {
+             type: 'participantJoin',
+             data: { participantId: localUserId }
+         });
+
+
+        Logger.info(`Simulated API success: Joined call ${callId}.`);
+
+        // Return the details of the call after joining
+        return call.getDetails();
+    }
+
+    /**
+     * Leaves an active call.
+     * @param {string} callId - The ID of the call to leave.
+     * @returns {Promise<void>} A promise that resolves when the local user has left the call.
+     * @throws {SeatalkCallError | InvalidInputError | CallNotFoundError | InvalidCallStateError} If the operation fails.
+     */
+    async leaveCall(callId) {
+        this._ensureClientReady();
+        validateCallId(callId);
+        const localUserId = String(this._configuration.localUserId);
+
+        const call = this._findCall(callId);
+
+        if (!call.isLocalUserInCall()) {
+            throw new InvalidCallStateError(ERROR_MESSAGES.NOT_IN_CALL + `: ${callId}`, call.state);
+        }
+        if (!isCallInProgressState(call.state)) {
+             throw new InvalidCallStateError(`Cannot leave call ${callId} in state ${call.state}.`, call.state);
+        }
+
+        Logger.info(`Attempting to leave call: ${callId}`);
+
+        // Simulate API call to leave the call
+        await delay(SIMULATED_DELAY_MS); // Simulate network delay
+
+        // Simulate API response / service confirmation
+        // Remove participant from local state
+        const participantRemoved = call.removeParticipant(localUserId);
+        if (!participantRemoved) {
+            // Should not happen if isLocalUserInCall() was true, but defensive check
+             throw new SeatalkCallError(`Failed to remove local user ${localUserId} from call ${callId} internally.`, 'INTERNAL_LEAVE_ERROR');
+        }
+
+        // Simulate receiving participantLeave event for THIS user from the service
+        // This confirms the leave server-side and triggers local cleanup/events.
+         this._simulateIncomingUpdate(callId, {
+             type: 'participantLeave',
+             data: { participantId: localUserId }
+         });
+
+        Logger.info(`Simulated API success: Left call ${callId}.`);
+
+        // If the call has no participants left (e.g., local user was the last one), simulate it ending
+        if (call.participants.size === 0) {
+             Logger.info(`Call ${callId} is now empty. Simulating call end.`);
+            this._simulateIncomingUpdate(callId, { type: 'callEnded' });
+        }
+
+        // The call details might still be available briefly until the 'callEnded' event leads to cleanup
+        // Returning void as the 'participantLeft' and potentially 'callEnded' events signal completion.
+    }
+
+    /**
+     * Mutes the local user's audio in a call.
+     * @param {string} callId - The ID of the call.
+     * @returns {Promise<void>} A promise that resolves when the local user is muted.
+     * @throws {SeatalkCallError | InvalidInputError | CallNotFoundError | InvalidCallStateError} If the operation fails.
+     */
+    async muteSelf(callId) {
+        this._ensureClientReady();
+        validateCallId(callId);
+        const localUserId = String(this._configuration.localUserId);
+
+        const call = this._findCall(callId);
+
+        if (!call.isLocalUserInCall()) {
+            throw new InvalidCallStateError(ERROR_MESSAGES.NOT_IN_CALL + `: ${callId}`, call.state);
+        }
+        if (!isCallActiveState(call.state)) {
+             throw new InvalidCallStateError(`Cannot mute in call ${callId} state ${call.state}. Must be ACTIVE.`, call.state, ['ACTIVE']);
+        }
+        if (call.getParticipantMuteStatus(localUserId)) {
+             throw new InvalidCallStateError(ERROR_MESSAGES.ALREADY_MUTED + `: ${callId}`, call.state);
+        }
+
+        Logger.info(`Attempting to mute local user ${localUserId} in call: ${callId}`);
+
+        // Simulate API call to mute
+        await delay(SIMULATED_DELAY_MS); // Simulate network delay
+
+        // Simulate API response / service confirmation
+        // Update local state immediately upon "successful API response"
+        const statusChanged = call.setParticipantMuteStatus(localUserId, true);
+
+        if (statusChanged) {
+             // Simulate receiving local mute status change event from the service
+             this._simulateIncomingUpdate(callId, {
+                 type: 'muteChange',
+                 data: { participantId: localUserId, isMuted: true }
+             });
+            Logger.info(`Simulated API success: Local user ${localUserId} muted in call ${callId}.`);
+        } else {
+             // Should ideally not happen if the check before the API call was correct
+             Logger.warn(`Mute action reported no status change for ${localUserId} in ${callId}.`);
+        }
+    }
+
+    /**
+     * Unmutes the local user's audio in a call.
+     * @param {string} callId - The ID of the call.
+     * @returns {Promise<void>} A promise that resolves when the local user is unmuted.
+     * @throws {SeatalkCallError | InvalidInputError | CallNotFoundError | InvalidCallStateError} If the operation fails.
+     */
+    async unmuteSelf(callId) {
+        this._ensureClientReady();
+        validateCallId(callId);
+        const localUserId = String(this._configuration.localUserId);
+
+        const call = this._findCall(callId);
+
+        if (!call.isLocalUserInCall()) {
+            throw new InvalidCallStateError(ERROR_MESSAGES.NOT_IN_CALL + `: ${callId}`, call.state);
+        }
+        if (!isCallActiveState(call.state)) {
+             throw new InvalidCallStateError(`Cannot unmute in call ${callId} state ${call.state}. Must be ACTIVE.`, call.state, ['ACTIVE']);
+        }
+        if (!call.getParticipantMuteStatus(localUserId)) {
+             throw new InvalidCallStateError(ERROR_MESSAGES.NOT_MUTED + `: ${callId}`, call.state);
+        }
+
+        Logger.info(`Attempting to unmute local user ${localUserId} in call: ${callId}`);
+
+        // Simulate API call to unmute
+        await delay(SIMULATED_DELAY_MS); // Simulate network delay
+
+        // Simulate API response / service confirmation
+        // Update local state immediately upon "successful API response"
+        const statusChanged = call.setParticipantMuteStatus(localUserId, false);
+
+         if (statusChanged) {
+            // Simulate receiving local mute status change event from the service
+            this._simulateIncomingUpdate(callId, {
+                 type: 'muteChange',
+                 data: { participantId: localUserId, isMuted: false }
+            });
+            Logger.info(`Simulated API success: Local user ${localUserId} unmuted in call ${callId}.`);
+         } else {
+             Logger.warn(`Unmute action reported no status change for ${localUserId} in ${callId}.`);
+         }
+    }
+
+    /**
+     * Adds a participant to an ongoing call.
+     * Only the host or authorized users might be able to do this in a real system.
+     * Assuming local user is authorized for this simulation.
+     * @param {string} callId - The ID of the call.
+     * @param {string | number} participantId - The ID of the participant to add.
+     * @returns {Promise<void>} A promise that resolves when the participant is added (or simulation complete).
+     * @throws {SeatalkCallError | InvalidInputError | CallNotFoundError | InvalidCallStateError | ParticipantNotFoundError} If the operation fails.
+     */
+    async addParticipant(callId, participantId) {
+        this._ensureClientReady();
+        validateCallId(callId);
+        if (!isValidParticipantId(participantId)) {
+            throw new InvalidInputError(ERROR_MESSAGES.INVALID_PARTICIPANT_ID);
+        }
+        const participantIdStr = String(participantId);
+        const localUserId = String(this._configuration.localUserId);
+
+        const call = this._findCall(callId);
+
+        if (!call.isLocalUserInCall() && call.hostId !== localUserId) {
+             // Basic authorization check simulation
+             throw new SeatalkCallError(`Local user ${localUserId} is not in call ${callId} and not the host. Cannot add participants.`, 'UNAUTHORIZED_ADD_PARTICIPANT');
+        }
+
+        if (!isCallActiveState(call.state)) {
+             throw new InvalidCallStateError(`Cannot add participant to call ${callId} in state ${call.state}. Must be ACTIVE.`, call.state, ['ACTIVE']);
+        }
+
+        if (call.participants.has(participantIdStr)) {
+             Logger.warn(`Attempted to add participant ${participantIdStr} to call ${callId} who is already in the call.`);
+             // Decide whether to throw or just resolve. Resolving might be friendlier API.
+             // Let's resolve with a warning.
+             Logger.warn(`Participant ${participantIdStr} is already in call ${callId}. Operation skipped.`);
+             return; // Resolve immediately if already present
+        }
+
+         if (call.participants.size >= MAX_PARTICIPANTS_PER_CALL) {
+              throw new InvalidInputError(`${ERROR_MESSAGES.MAX_PARTICIPANTS_EXCEEDED} (current size ${call.participants.size})`);
+         }
+
+
+        Logger.info(`Attempting to add participant ${participantIdStr} to call: ${callId}`);
+
+        // Simulate API call to add participant
+        await delay(SIMULATED_DELAY_MS); // Simulate network delay
+
+        // Simulate API response / service confirmation
+        // Simulate service sending participantJoin event to all participants (including local client)
+        this._simulateIncomingUpdate(callId, {
+             type: 'participantJoin',
+             data: { participantId: participantIdStr }
+        });
+
+        Logger.info(`Simulated API success: Requested to add participant ${participantIdStr} to call ${callId}. Wait for participantJoined event.`);
+         // Note: We don't add to local state immediately. The _simulateIncomingUpdate will do it when the event arrives.
+    }
+
+    /**
+     * Removes a participant from an ongoing call.
+     * Only the host or authorized users might be able to do this.
+     * @param {string} callId - The ID of the call.
+     * @param {string | number} participantId - The ID of the participant to remove.
+     * @returns {Promise<void>} A promise that resolves when the participant is removed (or simulation complete).
+     * @throws {SeatalkCallError | InvalidInputError | CallNotFoundError | InvalidCallStateError | ParticipantNotFoundError} If the operation fails.
+     */
+    async removeParticipant(callId, participantId) {
+         this._ensureClientReady();
+        validateCallId(callId);
+        if (!isValidParticipantId(participantId)) {
+            throw new InvalidInputError(ERROR_MESSAGES.INVALID_PARTICIPANT_ID);
+        }
+        const participantIdStr = String(participantId);
+        const localUserId = String(this._configuration.localUserId);
+
+        const call = this._findCall(callId);
+
+        if (!call.isLocalUserInCall() && call.hostId !== localUserId) {
+             // Basic authorization check simulation
+             throw new SeatalkCallError(`Local user ${localUserId} is not in call ${callId} and not the host. Cannot remove participants.`, 'UNAUTHORIZED_REMOVE_PARTICIPANT');
+        }
+
+        if (participantIdStr === localUserId) {
+             // Cannot remove self, use leaveCall instead
+             throw new InvalidInputError(`Cannot remove local user ${localUserId} using removeParticipant. Use leaveCall() instead.`);
+        }
+
+        if (!isCallActiveState(call.state)) {
+             throw new InvalidCallStateError(`Cannot remove participant from call ${callId} in state ${call.state}. Must be ACTIVE.`, call.state, ['ACTIVE']);
+        }
+
+        if (!call.participants.has(participantIdStr)) {
+             throw new ParticipantNotFoundError(participantIdStr, callId);
+        }
+
+
+        Logger.info(`Attempting to remove participant ${participantIdStr} from call: ${callId}`);
+
+        // Simulate API call to remove participant
+        await delay(SIMULATED_DELAY_MS); // Simulate network delay
+
+        // Simulate API response / service confirmation
+        // Simulate service sending participantLeave event to all participants (including local client)
+        this._simulateIncomingUpdate(callId, {
+             type: 'participantLeave',
+             data: { participantId: participantIdStr }
+        });
+
+        Logger.info(`Simulated API success: Requested to remove participant ${participantIdStr} from call ${callId}. Wait for participantLeft event.`);
+        // Note: We don't remove from local state immediately. The _simulateIncomingUpdate will do it when the event arrives.
+    }
+
+    /**
+     * Forcefully ends a call. Typically only the host or authorized users can do this.
+     * @param {string} callId - The ID of the call to end.
+     * @returns {Promise<void>} A promise that resolves when the call is ended (simulation complete).
+     * @throws {SeatalkCallError | InvalidInputError | CallNotFoundError | InvalidCallStateError} If the operation fails.
+     */
+    async endCall(callId) {
+        this._ensureClientReady();
+        validateCallId(callId);
+        const localUserId = String(this._configuration.localUserId);
+
+        const call = this._findCall(callId);
+
+        if (call.hostId !== localUserId) {
+             // Basic authorization check simulation
+             throw new SeatalkCallError(`Local user ${localUserId} is not the host of call ${callId}. Cannot end the call.`, 'UNAUTHORIZED_END_CALL');
+        }
+
+        if (!isCallInProgressState(call.state)) {
+             throw new InvalidCallStateError(`Cannot end call ${callId} in state ${call.state}.`, call.state);
+        }
+
+        Logger.info(`Attempting to end call: ${callId}`);
+
+        // Simulate API call to end the call
+        await delay(SIMULATED_DELAY_MS); // Simulate network delay
+
+        // Simulate API response / service confirmation
+        // Simulate service sending callEnded event to all participants (including local client)
+        this._simulateIncomingUpdate(callId, { type: 'callEnded' });
+
+        Logger.info(`Simulated API success: Requested to end call ${callId}. Wait for callEnded event.`);
+        // The _simulateIncomingUpdate for 'callEnded' will handle state change and cleanup.
+    }
+
+
+    /**
+     * Gets details about the current active calls managed by this client instance.
+     * @returns {object[]} An array of call detail objects.
+     */
+    getCurrentCalls() {
+        this._ensureClientReady(); // Ensure client is in a state where call data might exist
+
+        return Array.from(this._activeCalls.values())
+                    .filter(call => isCallInProgressState(call.state)) // Only return calls that are not ended/failed
+                    .map(call => call.getDetails());
+    }
+
+    /**
+     * Gets details about a specific call managed by this client instance, active or recently ended/failed.
+     * @param {string} callId - The ID of the call.
+     * @returns {object | null} Call details object, or null if the call is not found.
+     * @throws {InvalidInputError} If callId is invalid.
+     */
+    getCallDetails(callId) {
+         this._ensureClientReady(); // Ensure client is in a state where call data might exist
+         validateCallId(callId);
+
+         // We can return details even if it's ended/failed, useful for post-call summaries
+         const call = this._activeCalls.get(callId);
+
+         if (!call) {
+            Logger.warn(`getCallDetails: Call ${callId} not found in active calls.`);
+            return null;
+         }
+
+         return call.getDetails();
+    }
+
+    /**
+     * Checks if the local user is currently in any active call.
+     * @returns {boolean} True if the local user is in an active call.
+     */
+    isLocalUserInAnyCall() {
+         this._ensureClientReady(); // Ensure client is in a state where call data might exist
+
+         const localUserId = String(this._configuration.localUserId);
+         return Array.from(this._activeCalls.values()).some(call =>
+             isCallInProgressState(call.state) && call.isLocalUserInCall()
+         );
+    }
+
+     /**
+      * Disconnects the client. Simulates cleaning up connections.
+      * Any active calls the local user is in will be left.
+      * @returns {Promise<void>} A promise that resolves when disconnection is complete.
+      */
+    async disconnect() {
+        if (this._clientState === 'IDLE' || this._clientState === 'DISCONNECTING') {
+            Logger.info(`Client already ${this._clientState}. Disconnect operation skipped.`);
+            return;
+        }
+        if (this._clientState === 'ERROR') {
+             Logger.warn('Client is in ERROR state. Attempting to reset state.');
+             this._setClientState('DISCONNECTING'); // Allow disconnecting from error state
+        } else {
+             this._setClientState('DISCONNECTING');
+        }
+
+
+        Logger.info('Attempting to disconnect client.');
+
+        // Simulate leaving all active calls the local user is in
+        const callsToLeave = Array.from(this._activeCalls.values()).filter(call => call.isLocalUserInCall() && isCallInProgressState(call.state));
+
+        // Use Promise.all to wait for all leave operations to attempt completion
+        await Promise.all(callsToLeave.map(call => {
+            // Catch errors for individual leaves so one failure doesn't stop others
+            return this.leaveCall(call.callId).catch(err => {
+                Logger.error(`Failed to leave call ${call.callId} during disconnect`, err);
+                // If leaving fails, we might need a forced local cleanup
+                this._cleanupCall(call.callId); // Force cleanup local state for failed leaves
+            });
+        }));
+
+
+        // Simulate cleaning up other resources / network connections
+        await delay(SIMULATED_DELAY_MS * 2); // Simulate more significant delay for disconnection
+
+        // Clear any remaining active calls that weren't cleaned up by leave/end events
+        // This handles cases where leaving failed or remote user was the last to leave.
+        // All calls associated with this client instance should conceptually end upon disconnect.
+        Array.from(this._activeCalls.keys()).forEach(callId => {
+             const call = this._activeCalls.get(callId);
+             if (call && isCallInProgressState(call.state)) {
+                 Logger.warn(`Call ${callId} still in progress state (${call.state}) during client disconnect. Forcing local cleanup and simulating end.`);
+                 call.failureReason = 'Client Disconnected'; // Mark as failed/ended due to disconnect
+                 call.updateState('FAILED'); // Or ENDED, depending on desired semantic
+                 this._emit('callFailed', call.getDetails()); // Emit event for calls left hanging
+             }
+             this._cleanupCall(callId); // Ensure map is cleared
+        });
+
+
+        // Clear all event listeners as client is shutting down
+        this._eventListeners.clear();
+        Logger.info('All event listeners cleared.');
+
+        // Reset configuration
+        this._configuration = null;
+
+        this._setClientState('IDLE');
+        Logger.info('Client disconnected and returned to IDLE state.');
+    }
+
+    /**
+     * Simulates receiving a remote mute/unmute request for another participant.
+     * (Helper for demonstrating remoteMuteStatusChanged events)
+     * @param {string} callId - The ID of the call.
+     * @param {string | number} participantId - The ID of the participant whose status changed.
+     * @param {boolean} isMuted - The new mute status.
+     * @returns {boolean} True if the update was processed, false otherwise.
+     * @internal For simulation purposes only.
+     */
+    _simulateRemoteMuteStatusChange(callId, participantId, isMuted) {
+         validateCallId(callId);
+        if (!isValidParticipantId(participantId)) {
+            Logger.warn(`_simulateRemoteMuteStatusChange: Invalid participant ID ${participantId}`);
+            return false;
+        }
+        const participantIdStr = String(participantId);
+        const localUserId = String(this._configuration?.localUserId);
+
+        if (participantIdStr === localUserId) {
+            Logger.warn(`_simulateRemoteMuteStatusChange: Cannot simulate remote change for local user ${localUserId}.`);
+            return false;
+        }
+
+        const call = this._activeCalls.get(callId);
+         if (!call || !isCallActiveState(call.state)) {
+            Logger.warn(`_simulateRemoteMuteStatusChange: Call ${callId} not found or not active.`);
+            return false;
+         }
+
+         if (!call.participants.has(participantIdStr)) {
+              Logger.warn(`_simulateRemoteMuteStatusChange: Participant ${participantIdStr} not found in call ${callId}.`);
+              return false;
+         }
+
+         // Simulate the incoming event from the service
+         this._simulateIncomingUpdate(callId, {
+             type: 'muteChange',
+             data: { participantId: participantIdStr, isMuted: isMuted }
+         });
+
+         return true;
+    }
+
+}
+
+// --- Exports ---
+
+/**
+ * Default export is the SeatalkCallClient class.
+ * @type {typeof SeatalkCallClient}
+ */
+module.exports = SeatalkCallClient;
+
+// Optionally export specific error classes or constants if they are part of the public API
+// module.exports.SeatalkCallError = SeatalkCallError;
+// module.exports.ClientConfigurationError = ClientConfigurationError;
+// module.exports.InvalidCallStateError = InvalidCallStateError;
+// module.exports.InvalidInputError = InvalidInputError;
+// module.exports.CallNotFoundError = CallNotFoundError;
+// module.exports.ParticipantNotFoundError = ParticipantNotFoundError;