@soundretouch/api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RemcoS2000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# SoundRetouch-API
+
+This is another unofficial TypeScript API library to configure and manage legacy Bose SoundTouch devices.
+
+This project is not affiliated with Bose.
+
+As Bose announced the deprecation of the SoundTouch lineup and will stop cloud support, I wanted to try something out and set up a project to help keep these speakers usable. This project provides an easy-to-use wrapper on the SoundTouch API documented by Bose, and it supports device discovery as well.
+
+## Installation
+
+```bash
+npm i soundretouch-api
+```
+
+## Usage
+
+```ts
+import { SoundTouchDevice } from 'soundretouch-api'
+
+const device = new SoundTouchDevice('192.168.1.67')
+
+const info = await device.info()
+const nowPlaying = await device.nowPlaying()
+const volume = await device.volume()
+
+await device.setVolume(25)
+await device.keyPressAndRelease('PLAY')
+```
+
+## WebSocket Asynchronous Notifications
+
+```ts
+import { SoundTouchDevice } from 'soundretouch-api'
+
+const device = new SoundTouchDevice('192.168.1.67')
+
+device.onNowPlayingUpdated((nowPlaying) => {
+    console.log('Now playing changed:', nowPlaying)
+})
+
+device.onVolumeUpdated((volume) => {
+    console.log('Volume changed:', volume)
+})
+```
+
+## Discovery
+
+```ts
+import { SoundTouchDiscovery } from 'soundretouch-api'
+
+const handle = SoundTouchDiscovery.start(async (device) => {
+    console.log('Found device at', device.host)
+    console.log(await device.info())
+})
+
+// Stop after 2 minutes
+setTimeout(() => handle.stop(), 120000)
+```
+
+## Implemented Endpoints
+
+- /info
+- /now_playing
+- /trackInfo
+- /sources
+- /select
+- /volume
+- /bass
+- /bassCapabilities
+- /capabilities
+- /audiodspcontrols
+- /audioproducttonecontrols
+- /audioproductlevelcontrols
+- /presets
+- /name
+- /getZone
+- /setZone
+- /addZoneSlave
+- /removeZoneSlave
+- /key
+
+## Debug Logging
+
+Enable debug output with the `DEBUG` environment variable. You can target all logs or narrow it down to a single subsystem.
+
+```
+DEBUG=soundretouch:*
+DEBUG=soundretouch:discovery
+DEBUG=soundretouch:endpoints:*
+DEBUG=soundretouch:endpoints:info
+```
+
+## Smoke Test
+
+```bash
+npx tsx scripts/smoke.ts
+```
+
+## Docs
+
+- [`docs/SoundTouch-Web-API.pdf`](docs/SoundTouch-Web-API.pdf)
+
+## Compliance Notice
+
+This project uses the Bose SoundTouch Web API. Use of the SoundTouch Materials is subject to Bose's Terms of Use. Refer to the official documentation for the full terms.
+
+Trademark attribution: Bose and SoundTouch are trademarks of Bose Corporation.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { SoundTouchDevice } from './src/device/SoundTouchDevice';
+export type { DeviceInfo, DeviceInfoComponent, DeviceNetworkInfo } from './src/types/DeviceInfo';
+export type { Bass } from './src/types/Bass';
+export type { BassCapabilities } from './src/types/BassCapabilities';
+export type { Capabilities, Capability } from './src/types/Capabilities';
+export type { AudioDspControls } from './src/types/AudioDspControls';
+export type { ArtStatus, AudioMode, KeyState, KeyValue, PlayStatus, PresetId, SourceStatus } from './src/types/Enums';
+export type { AudioProductToneControls, AudioProductToneControlsUpdate, ToneControl } from './src/types/AudioProductToneControls';
+export type { AudioProductLevelControls, AudioProductLevelControlsUpdate, LevelControl } from './src/types/AudioProductLevelControls';
+export type { NowPlaying } from './src/types/NowPlaying';
+export type { Presets, Preset, PresetContentItem } from './src/types/Presets';
+export type { Recents, Recent, RecentContentItem } from './src/types/Recents';
+export type { Zone, ZoneMember, ZoneConfig, ZoneConfigMember, ZoneSlaveConfig } from './src/types/Zone';
+export type { ContentItem } from './src/types/ContentItem';
+export type { Sources, SourceItem } from './src/types/Sources';
+export type { Volume } from './src/types/Volume';
+export type { Updates } from './src/types/Updates';
+export type { SoundTouchKey } from './src/endpoints/key';
+export type { HttpClientOptions } from './src/client/http';
+export type { WebSocketClientOptions } from './src/client/ws';
+export type { SoundTouchDeviceOptions } from './src/device/SoundTouchDevice';
+export { SoundTouchError, HttpError, TimeoutError } from './src/client/errors';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAChG,YAAY,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACxE,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AACrH,YAAY,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAA;AACjI,YAAY,EAAE,yBAAyB,EAAE,+BAA+B,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AACrI,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC7E,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC7E,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvG,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAC9D,YAAY,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAC7D,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAA;AAC5E,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { SoundTouchDevice } from './src/device/SoundTouchDevice';
+export { SoundTouchError, HttpError, TimeoutError } from './src/client/errors';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAqBhE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/src/client/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Base error type for SoundTouch client operations.
+ */
+export declare class SoundTouchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when an HTTP request fails with a non-2xx status code.
+ */
+export declare class HttpError extends SoundTouchError {
+    status: number;
+    statusText: string;
+    body?: string;
+    /**
+     * Creates a new HttpError instance.
+     *
+     * @param status HTTP status code.
+     * @param statusText HTTP status text.
+     * @param body Optional response body.
+     */
+    constructor(status: number, statusText: string, body?: string);
+}
+/**
+ * Error thrown when a request exceeds the configured timeout.
+ */
+export declare class TimeoutError extends SoundTouchError {
+    timeoutMs: number;
+    /**
+     * Creates a new TimeoutError instance.
+     *
+     * @param timeoutMs Timeout value in milliseconds.
+     */
+    constructor(timeoutMs: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/client/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/client/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI9B;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,eAAe;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;;;;;OAMG;gBACS,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAOhE;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,eAAe;IAC7C,SAAS,EAAE,MAAM,CAAA;IAEjB;;;;OAIG;gBACS,SAAS,EAAE,MAAM;CAKhC"}

package/dist/src/client/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Base error type for SoundTouch client operations.
+ */
+export class SoundTouchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SoundTouchError';
+    }
+}
+/**
+ * Error thrown when an HTTP request fails with a non-2xx status code.
+ */
+export class HttpError extends SoundTouchError {
+    /**
+     * Creates a new HttpError instance.
+     *
+     * @param status HTTP status code.
+     * @param statusText HTTP status text.
+     * @param body Optional response body.
+     */
+    constructor(status, statusText, body) {
+        super(`HTTP ${status} ${statusText}`);
+        this.name = 'HttpError';
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+    }
+}
+/**
+ * Error thrown when a request exceeds the configured timeout.
+ */
+export class TimeoutError extends SoundTouchError {
+    /**
+     * Creates a new TimeoutError instance.
+     *
+     * @param timeoutMs Timeout value in milliseconds.
+     */
+    constructor(timeoutMs) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = 'TimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/client/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/client/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACtC,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IACjC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,eAAe;IAK1C;;;;;;OAMG;IACH,YAAY,MAAc,EAAE,UAAkB,EAAE,IAAa;QACzD,KAAK,CAAC,QAAQ,MAAM,IAAI,UAAU,EAAE,CAAC,CAAA;QACrC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IACpB,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,eAAe;IAG7C;;;;OAIG;IACH,YAAY,SAAiB;QACzB,KAAK,CAAC,2BAA2B,SAAS,IAAI,CAAC,CAAA;QAC/C,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;QAC1B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC9B,CAAC;CACJ"}

package/dist/src/client/http.d.ts

@@ -0,0 +1,40 @@
+export interface HttpClientOptions {
+    timeoutMs?: number;
+}
+export declare class HttpClient {
+    private host;
+    private timeoutMs;
+    private log;
+    /**
+     * Creates a new HTTP client for a SoundTouch device.
+     *
+     * @param host The hostname or IP address of the SoundTouch device.
+     * @param options Optional HTTP client configuration.
+     */
+    constructor(host: string, options?: HttpClientOptions);
+    /**
+     * Sends a GET request and parses the XML response into the expected type.
+     *
+     * @param path Endpoint path to request.
+     * @returns Promise<T> A promise that resolves to the parsed XML response.
+     */
+    getXml<T>(path: string): Promise<T>;
+    /**
+     * Sends a POST request and parses the XML response into the expected type.
+     *
+     * @param path Endpoint path to request.
+     * @param body Optional XML body to send.
+     * @returns Promise<T> A promise that resolves to the parsed XML response.
+     */
+    postXml<T>(path: string, body?: string): Promise<T>;
+    /**
+     * Sends a POST request without expecting a response body.
+     *
+     * @param path Endpoint path to request.
+     * @param body Optional XML body to send.
+     * @returns Promise<void> A promise that resolves when the request completes.
+     */
+    post(path: string, body?: string): Promise<void>;
+    private request;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/src/client/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/client/http.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,qBAAa,UAAU;IACnB,OAAO,CAAC,IAAI,CAAQ;IACpB,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,GAAG,CAAmC;IAE9C;;;;;OAKG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB;IAKzD;;;;;OAKG;IACG,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAKzC;;;;;;OAMG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAczD;;;;;;OAMG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAQxC,OAAO;CA+BxB"}

package/dist/src/client/http.js

@@ -0,0 +1,88 @@
+import createDebug from 'debug';
+import { HttpError, TimeoutError } from './errors';
+import { parseXml } from './xml';
+export class HttpClient {
+    /**
+     * Creates a new HTTP client for a SoundTouch device.
+     *
+     * @param host The hostname or IP address of the SoundTouch device.
+     * @param options Optional HTTP client configuration.
+     */
+    constructor(host, options = {}) {
+        this.log = createDebug('soundretouch:http');
+        this.host = host;
+        this.timeoutMs = options.timeoutMs ?? 10000;
+    }
+    /**
+     * Sends a GET request and parses the XML response into the expected type.
+     *
+     * @param path Endpoint path to request.
+     * @returns Promise<T> A promise that resolves to the parsed XML response.
+     */
+    async getXml(path) {
+        const text = await this.request(path, { method: 'GET' });
+        return parseXml(text);
+    }
+    /**
+     * Sends a POST request and parses the XML response into the expected type.
+     *
+     * @param path Endpoint path to request.
+     * @param body Optional XML body to send.
+     * @returns Promise<T> A promise that resolves to the parsed XML response.
+     */
+    async postXml(path, body) {
+        const text = await this.request(path, {
+            method: 'POST',
+            body,
+            headers: { 'Content-Type': 'text/xml' },
+        });
+        if (!text) {
+            return {};
+        }
+        return parseXml(text);
+    }
+    /**
+     * Sends a POST request without expecting a response body.
+     *
+     * @param path Endpoint path to request.
+     * @param body Optional XML body to send.
+     * @returns Promise<void> A promise that resolves when the request completes.
+     */
+    async post(path, body) {
+        await this.request(path, {
+            method: 'POST',
+            body,
+            headers: { 'Content-Type': 'text/xml' },
+        });
+    }
+    async request(path, init) {
+        const url = `http://${this.host}:8090${path.startsWith('/') ? path : `/${path}`}`;
+        this.log('request %s %s', init.method, url);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                ...init,
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            this.log('response %s %s %s', init.method, url, response.status);
+            if (!response.ok) {
+                throw new HttpError(response.status, response.statusText, text);
+            }
+            return text;
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'name' in error && error.name === 'AbortError') {
+                this.log('timeout %s %s', init.method, url);
+                throw new TimeoutError(this.timeoutMs);
+            }
+            this.log('error %s %s %O', init.method, url, error);
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/src/client/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/client/http.ts"],"names":[],"mappings":"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"}

package/dist/src/client/ws.d.ts

@@ -0,0 +1,82 @@
+export type WebSocketClientOptions = {
+    autoReconnect?: boolean;
+    reconnectDelayMs?: number;
+    unwrap?: boolean;
+};
+type MessageHandler<T> = (payload: T) => void;
+type ErrorHandler = (error: unknown) => void;
+export declare class WebSocketClient {
+    private host;
+    private socket?;
+    private options;
+    private reconnectTimer?;
+    private closedByUser;
+    private messageHandlers;
+    private errorHandlers;
+    private log;
+    constructor(host: string, options?: WebSocketClientOptions);
+    /**
+     * Opens a WebSocket connection for async updates.
+     *
+     * WebSocket connections are made on port 8080 using the "gabbo" protocol.
+     *
+     * @example
+     * const client = new WebSocketClient('192.168.1.5')
+     * client.connect()
+     */
+    connect(): void;
+    /**
+     * Closes the WebSocket connection, if one is open.
+     *
+     * @example
+     * const client = new WebSocketClient('192.168.1.5')
+     * client.close()
+     */
+    close(): void;
+    /**
+     * Subscribes to parsed message payloads.
+     *
+     * @param handler Callback invoked with each parsed payload.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * const off = client.onMessage((payload) => console.log(payload))
+     * off()
+     */
+    onMessage<T>(handler: MessageHandler<T>): () => void;
+    /**
+     * Subscribes to WebSocket errors.
+     *
+     * @param handler Callback invoked when a WebSocket error is raised.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * const off = client.onError((error) => console.error(error))
+     * off()
+     */
+    onError(handler: ErrorHandler): () => void;
+    /**
+     * Indicates whether a WebSocket connection is currently active.
+     *
+     * @returns True when the socket is connected.
+     *
+     * @example
+     * if (client.isConnected()) {
+     *     console.log('connected')
+     * }
+     */
+    isConnected(): boolean;
+    /**
+     * Ensures the WebSocket connection is established.
+     *
+     * @returns True when the socket is connected.
+     *
+     * @example
+     * client.ensureConnected()
+     */
+    ensureConnected(): boolean;
+    private unwrapPayload;
+    private clearReconnect;
+}
+export {};
+//# sourceMappingURL=ws.d.ts.map

package/dist/src/client/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../../src/client/ws.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,sBAAsB,GAAG;IACjC,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,MAAM,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,KAAK,cAAc,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAA;AAC7C,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;AAE5C,qBAAa,eAAe;IACxB,OAAO,CAAC,IAAI,CAAQ;IACpB,OAAO,CAAC,MAAM,CAAC,CAAW;IAC1B,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,cAAc,CAAC,CAA+B;IACtD,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,eAAe,CAAwC;IAC/D,OAAO,CAAC,aAAa,CAA0B;IAE/C,OAAO,CAAC,GAAG,CAAwC;gBAEvC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B;IAK9D;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;IA4Cf;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAcb;;;;;;;;;OASG;IACH,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAMpD;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI;IAK1C;;;;;;;;;OASG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;OAOG;IACH,eAAe,IAAI,OAAO;IAQ1B,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,cAAc;CASzB"}

package/dist/src/client/ws.js

@@ -0,0 +1,153 @@
+import createDebug from 'debug';
+import { parseXml } from './xml';
+export class WebSocketClient {
+    constructor(host, options = {}) {
+        this.closedByUser = false;
+        this.messageHandlers = new Set();
+        this.errorHandlers = new Set();
+        this.log = createDebug('soundretouch:client:ws');
+        this.host = host;
+        this.options = options;
+    }
+    /**
+     * Opens a WebSocket connection for async updates.
+     *
+     * WebSocket connections are made on port 8080 using the "gabbo" protocol.
+     *
+     * @example
+     * const client = new WebSocketClient('192.168.1.5')
+     * client.connect()
+     */
+    connect() {
+        if (this.socket) {
+            this.log('connect skipped (already connected)');
+            return;
+        }
+        this.closedByUser = false;
+        this.clearReconnect();
+        const url = `ws://${this.host}:8080`;
+        this.log('connect %s', url);
+        this.socket = new WebSocket(url, 'gabbo');
+        this.socket.addEventListener('message', (event) => {
+            try {
+                const data = typeof event.data === 'string' ? event.data : new TextDecoder().decode(event.data);
+                this.log('message received', data);
+                const payload = parseXml(data);
+                const message = this.unwrapPayload(payload);
+                this.log('message parsed %O', message);
+                this.messageHandlers.forEach((handler) => handler(message));
+            }
+            catch (error) {
+                this.log('message error %O', error);
+                this.errorHandlers.forEach((handler) => handler(error));
+            }
+        });
+        this.socket.addEventListener('error', (event) => {
+            this.log('socket error %O', event);
+            this.errorHandlers.forEach((handler) => handler(event));
+        });
+        this.socket.addEventListener('close', () => {
+            this.log('socket close');
+            this.socket = undefined;
+            if (!this.closedByUser && this.options.autoReconnect) {
+                const delay = this.options.reconnectDelayMs ?? 1000;
+                this.log('reconnect scheduled in %dms', delay);
+                this.reconnectTimer = setTimeout(() => this.connect(), delay);
+            }
+        });
+    }
+    /**
+     * Closes the WebSocket connection, if one is open.
+     *
+     * @example
+     * const client = new WebSocketClient('192.168.1.5')
+     * client.close()
+     */
+    close() {
+        this.closedByUser = true;
+        this.clearReconnect();
+        if (!this.socket) {
+            this.log('close skipped (no active connection)');
+            return;
+        }
+        this.log('close');
+        this.socket.close();
+        this.socket = undefined;
+    }
+    /**
+     * Subscribes to parsed message payloads.
+     *
+     * @param handler Callback invoked with each parsed payload.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * const off = client.onMessage((payload) => console.log(payload))
+     * off()
+     */
+    onMessage(handler) {
+        const wrapped = handler;
+        this.messageHandlers.add(wrapped);
+        return () => this.messageHandlers.delete(wrapped);
+    }
+    /**
+     * Subscribes to WebSocket errors.
+     *
+     * @param handler Callback invoked when a WebSocket error is raised.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * const off = client.onError((error) => console.error(error))
+     * off()
+     */
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    /**
+     * Indicates whether a WebSocket connection is currently active.
+     *
+     * @returns True when the socket is connected.
+     *
+     * @example
+     * if (client.isConnected()) {
+     *     console.log('connected')
+     * }
+     */
+    isConnected() {
+        return this.socket !== undefined;
+    }
+    /**
+     * Ensures the WebSocket connection is established.
+     *
+     * @returns True when the socket is connected.
+     *
+     * @example
+     * client.ensureConnected()
+     */
+    ensureConnected() {
+        if (!this.isConnected()) {
+            this.connect();
+        }
+        return this.isConnected();
+    }
+    unwrapPayload(payload) {
+        if (!this.options.unwrap || !payload || typeof payload !== 'object') {
+            return payload;
+        }
+        const record = payload;
+        const keys = Object.keys(record);
+        if (keys.length !== 1) {
+            return payload;
+        }
+        return record[keys[0]] ?? payload;
+    }
+    clearReconnect() {
+        if (!this.reconnectTimer) {
+            return;
+        }
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        this.log('reconnect cleared');
+    }
+}
+//# sourceMappingURL=ws.js.map

package/dist/src/client/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../../src/client/ws.ts"],"names":[],"mappings":"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"}

package/dist/src/client/xml.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parses XML into the requested type using the configured XML parser.
+ *
+ * @param xml Raw XML string to parse.
+ * @returns Parsed XML payload typed as the requested generic type.
+ */
+export declare function parseXml<T>(xml: string): T;
+//# sourceMappingURL=xml.d.ts.map

package/dist/src/client/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../../src/client/xml.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAE1C"}