steelseries-sonar-sdk 0.4.6 → 0.4.8

package/dist/index.d.ts

@@ -1,29 +1,251 @@
-export * from './enums';
-export * from './exceptions';
-export * from './functions/audio/get-audio-data-classic';
-export * from './functions/audio/get-audio-data-stream';
-export * from './functions/audio/get-audio-mode';
-export * from './functions/audio/set-audio-mode';
-export * from './functions/audio/set-channel-mute-classic';
-export * from './functions/audio/set-channel-mute-streamer';
-export * from './functions/audio/set-channel-volume-classic';
-export * from './functions/audio/set-channel-volume-streamer';
-export * from './functions/chatmix/get-chat-mix-state';
-export * from './functions/chatmix/set-chat-mix-balance';
-export * from './functions/devices/get-audio-devices';
-export * from './functions/devices/set-audio-device';
-export * from './functions/endpoint/get-app-endpoint';
-export * from './functions/endpoint/get-sonar-endpoint';
-export * from './functions/endpoint/get-sonar-endpoint-cached';
-export * from './functions/profile/get-channel-profiles';
-export * from './functions/profile/get-selected-profiles';
-export * from './functions/profile/set-selected-profile';
-export * from './types/audio-device';
-export * from './types/changed-device';
-export * from './types/channel-volume-classic';
-export * from './types/channel-volume-streamer';
-export * from './types/channel-volume-streamer-path';
-export * from './types/channel-volumes-classic';
-export * from './types/channel-volumes-streamer';
-export * from './types/chat-mix-data';
-export * from './types/profile-option';
+/**
+* Sonar audio mixing channels.
+* @property {@link AudioChannel.Master} - Master volume channel.
+* @property {@link AudioChannel.Game} - Game audio channel.
+* @property {@link AudioChannel.Chat} - Chat audio channel.
+* @property {@link AudioChannel.Media} - Media audio channel.
+* @property {@link AudioChannel.Aux} - Auxiliary audio channel.
+* @property {@link AudioChannel.Mic} - Microphone audio channel.
+*/
+declare enum AudioChannel {
+	Master = "master",
+	Game = "game",
+	Chat = "chat",
+	Media = "media",
+	Aux = "aux",
+	Mic = "mic"
+}
+declare enum ProfileChannel {
+	Game = "game",
+	Chat = "chat",
+	Media = "media",
+	Aux = "aux",
+	Mic = "mic"
+}
+/**
+* Sonar device channels.
+* @property {@link DeviceChannel.Output} - All output channels.
+* @property {@link DeviceChannel.Game} - Game output channel.
+* @property {@link DeviceChannel.Chat} - Chat output channel.
+* @property {@link DeviceChannel.Media} - Media output channel.
+* @property {@link DeviceChannel.Aux} - Auxiliary output channel.
+* @property {@link DeviceChannel.Mic} - Microphone input channel.
+*/
+declare enum DeviceChannel {
+	Output = "render",
+	Game = "game",
+	Chat = "chat",
+	Media = "media",
+	Aux = "aux",
+	Mic = "mic"
+}
+/**
+* Sonar Streamer Mode path.
+* @property {@link StreamerPath.Streaming} - What the audience will hear.
+* @property {@link StreamerPath.Monitoring} - What the owner will hear.
+*/
+declare enum StreamerPath {
+	Streaming = "streaming",
+	Monitoring = "monitoring"
+}
+/**
+* Sonar mixing state.
+* @property {@link AudioMode.Classic} - Basic mixing.
+* @property {@link AudioMode.Streamer} - Advanced mixing - has stream/monitor path each channel.
+*/
+declare enum AudioMode {
+	Classic = "classic",
+	Streamer = "stream"
+}
+/**
+* The state of CHATMIX availability.
+* @property {@link ChatMixState.Enabled} - CHATMIX is enabled and available.
+* @property {@link ChatMixState.FiniteWheel} - CHATMIX is available but the user cannot interact with it via software.
+* @property {@link ChatMixState.DifferentDeviceSelected} - CHATMIX is unavailable because a different output device is selected.
+* @property {@link ChatMixState.NoDeviceSelected} - CHATMIX is unavailable because no output device is selected.
+*/
+declare enum ChatMixState {
+	Enabled = "enabled",
+	FiniteWheel = "finiteWheel",
+	DifferentDeviceSelected = "differentDeviceSelected",
+	NoDeviceSelected = "noDeviceSelected"
+}
+/**
+* Type of audio device.
+* @property {@link DeviceFlow.Output} - Device used to render audio (e.g. speakers, headphones).
+* @property {@link DeviceFlow.Input} - Device used to capture audio (e.g. microphones).
+*/
+declare enum DeviceFlow {
+	Output = "output",
+	Input = "input"
+}
+type RequestErrorProps = {
+	message?: string;
+	innerException?: Error;
+};
+declare enum InitializeErrorReason {
+	BadConfig = "Bad Config",
+	OSUnsupported = "OS Unsupported",
+	NotEnabled = "Not Enabled",
+	NotRunning = "Not Running",
+	NotReady = "Not Ready",
+	NotResponding = "Not Responding",
+	NotAvailable = "Not Available"
+}
+type InitializeErrorProps = {
+	message?: string;
+	innerException?: Error;
+	reason: InitializeErrorReason;
+};
+/** Base exception for all handled Sonar related exception. */
+declare abstract class SonarException extends Error {
+	constructor(message: string, cause?: Error);
+}
+/** Thrown when the server responds in an unexpected way. */
+declare class SonarRequestException extends SonarException {
+	constructor(error?: RequestErrorProps);
+}
+/** Thrown when the server cannot be determined. */
+declare class SonarInitializationException extends SonarException {
+	reason: InitializeErrorReason;
+	constructor(error: InitializeErrorProps);
+}
+type ChannelVolumeClassic = {
+	volume: number;
+	isMuted: boolean;
+};
+type ChannelVolumesClassic = {
+	[AudioChannel.Master]: ChannelVolumeClassic;
+} & { [K in Exclude<AudioChannel, "master">]? : ChannelVolumeClassic };
+/**
+* Gets audio data for all channels.
+* @param sonarEndpoint Sonar endpoint URL
+* @returns volume in the range of 0 to 100,
+*/
+declare function getAudioDataClassic(sonarEndpoint: string): Promise<ChannelVolumesClassic>;
+type ChannelVolumeStreamerPath = {
+	volume: number;
+	isMuted: boolean;
+};
+type ChannelVolumeStreamer = { [K in StreamerPath] : ChannelVolumeStreamerPath };
+type ChannelVolumesStreamer = {
+	[AudioChannel.Master]: ChannelVolumeStreamer;
+} & { [K in AudioChannel]? : ChannelVolumeStreamer };
+/**
+* Gets audio data for all channels.
+* @param sonarEndpoint Sonar endpoint URL
+* @returns volume in the range of 0 to 100,
+*/
+declare function getAudioDataStream(sonarEndpoint: string): Promise<ChannelVolumesStreamer>;
+/**
+* Gets audio data for all channels.
+* @param sonarEndpoint Sonar endpoint URL
+* @returns classic or streamer mode
+*/
+declare function getAudioMode(sonarEndpoint: string): Promise<AudioMode>;
+/**
+* Gets audio data for all channels.
+* @param sonarEndpoint Sonar endpoint URL
+* @param audioMode Target audio mode
+* @returns classic or streamer mode
+*/
+declare function setAudioMode(sonarEndpoint: string, audioMode: AudioMode): Promise<AudioMode>;
+/**
+* Sets audio data for target channel.
+* @param sonarEndpoint Sonar endpoint URL
+* @param isMuted Will mute if true.
+* @param channel Target audio channel
+*/
+declare function setChannelMuteClassic(sonarEndpoint: string, isMuted: boolean, channel: AudioChannel): Promise<ChannelVolumeClassic>;
+/**
+* Sets audio data for target channel.
+* @param sonarEndpoint Sonar endpoint URL
+* @param isMuted Will mute if true.
+* @param channel Target audio channel
+* @param path Target streamer path
+*/
+declare function setChannelMuteStreamer(sonarEndpoint: string, isMuted: boolean, channel: AudioChannel, path: StreamerPath): Promise<ChannelVolumeStreamerPath>;
+/**
+* Sets audio data for target channel.
+* @param sonarEndpoint Sonar endpoint URL
+* @param volumePercent Volume in the range of 0 to 100
+* @param channel Target audio channel
+*/
+declare function setChannelVolumeClassic(sonarEndpoint: string, volumePercent: number, channel: AudioChannel): Promise<ChannelVolumeClassic>;
+/**
+* Sets audio data for target channel.
+* @param sonarEndpoint Sonar endpoint URL
+* @param volumePercent Volume in the range of 0 to 100
+* @param channel Target audio channel
+* @param path Target streamer path
+*/
+declare function setChannelVolumeStreamer(sonarEndpoint: string, volumePercent: number, channel: AudioChannel, path: StreamerPath): Promise<ChannelVolumeStreamerPath>;
+type ChatMixData = {
+	chatBalance: number;
+	state: ChatMixState;
+	isEnabled: boolean;
+};
+/**
+* Gets CHATMIX state and data.
+* @param sonarEndpoint Sonar endpoint URL
+* @returns balance as 0 - 100,
+*/
+declare function getChatMixState(sonarEndpoint: string): Promise<ChatMixData>;
+/**
+* Set CHATMIX balance between audio(0%) and chat(100%).
+* @param sonarEndpoint Sonar endpoint URL
+* @param chatBalance Balance as 0 - 100,
+*/
+declare function setChatMixBalance(sonarEndpoint: string, chatBalance: number): Promise<ChatMixData>;
+type AudioDevice = {
+	id: string;
+	name: string;
+	type: DeviceFlow;
+};
+declare function getAudioDevices(sonarEndpoint: string, deviceType?: DeviceFlow): Promise<AudioDevice[]>;
+type ChangedDevice = {
+	deviceId: string;
+	deviceChannel: Exclude<DeviceChannel, DeviceChannel.Output>;
+	isRunning: boolean;
+};
+declare function setAudioDevice(sonarEndpoint: string, deviceChannel: DeviceChannel, deviceId: string): Promise<ChangedDevice[]>;
+/**
+* Retrieves the SteelSeries GG application's encrypted address from the coreProps.json file.
+*
+* @returns A promise that resolves to the GG application's secure address string (e.g., "https://..."),
+*          as found in the ggEncryptedAddress property of coreProps.json.
+*
+* @throws {SonarInitializationException} If the GG server cannot be determined.
+*
+* @remarks
+* - Only supports Windows OS; throws on other platforms.
+* - Locates coreProps.json in the ProgramData directory under SteelSeries folders.
+* - Reads and parses the file, returning the encrypted address as a secure URL.
+*/
+declare function getAppEndpoint(): Promise<string>;
+/**
+* Retrieves the Sonar web server address from an application server's /subApps endpoint.
+*
+* @param appEndpoint - The base URL of the application server (e.g. "https://localhost:1234").
+* @returns A promise that resolves to the Sonar web server address.
+*
+* @throws {SonarInitializationException} If the sonar server cannot be determined.
+*
+* @remarks
+* - Performs a GET request to `${appAddress}/subApps`.
+* - The response body is expected to conform to the SubAppsResponse shape and contain `subApps.sonar`.
+* - Uses a fetch TLS option that disables certificate verification (rejectUnauthorized: false).
+*/
+declare function getSonarEndpoint(appEndpoint: string): Promise<string>;
+declare function getSonarEndpointCached(appAddress: string, seconds?: number): Promise<string>;
+type ProfileOption = {
+	id: string;
+	name: string;
+	isFavorite: boolean;
+	channel: ProfileChannel;
+	image?: string;
+};
+declare function getChannelProfiles(sonarAddress: string, channel: ProfileChannel, favoritesOnly?: boolean): Promise<ProfileOption[]>;
+declare function getSelectedProfiles(sonarAddress: string): Promise<ProfileOption[]>;
+declare function setSelectedProfile(sonarAddress: string, profileId: string): Promise<ProfileOption>;
+export { setSelectedProfile, setChatMixBalance, setChannelVolumeStreamer, setChannelVolumeClassic, setChannelMuteStreamer, setChannelMuteClassic, setAudioMode, setAudioDevice, getSonarEndpointCached, getSonarEndpoint, getSelectedProfiles, getChatMixState, getChannelProfiles, getAudioMode, getAudioDevices, getAudioDataStream, getAudioDataClassic, getAppEndpoint, StreamerPath, SonarRequestException, SonarInitializationException, SonarException, ProfileOption, ProfileChannel, InitializeErrorReason, DeviceFlow, DeviceChannel, ChatMixState, ChatMixData, ChannelVolumesStreamer, ChannelVolumesClassic, ChannelVolumeStreamerPath, ChannelVolumeStreamer, ChannelVolumeClassic, ChangedDevice, AudioMode, AudioDevice, AudioChannel };