@hmcs/sdk 1.0.0

package/dist/host.cjs

@@ -0,0 +1,297 @@
+'use strict';
+
+/**
+ * Host API namespace for low-level HTTP communication with the Desktop Homunculus server.
+ *
+ * This module provides the foundational HTTP client functionality used internally
+ * by all other SDK modules. It handles the base URL configuration, URL construction,
+ * and HTTP methods with automatic error handling.
+ *
+ * **Note:** This module is primarily for internal SDK use. Most developers should
+ * use the higher-level namespaces like `vrm`, `signals`, etc.
+ *
+ * @example
+ * ```typescript
+ * // Internal SDK usage (you typically won't need this directly)
+ * const response = await host.get(host.createUrl("vrm"));
+ * const vrms = await response.json();
+ *
+ * // URL construction with parameters
+ * const url = host.createUrl("vrm", { name: "MyCharacter" });
+ * // Results in: http://localhost:3100/vrm?name=MyCharacter
+ *
+ * // Configure the base URL (e.g., from an MCP server)
+ * host.configure({ baseUrl: "http://localhost:4000" });
+ * ```
+ */
+/** Error thrown when the Homunculus HTTP API returns a non-OK response. */
+class HomunculusApiError extends Error {
+    /** HTTP status code (e.g. 404, 500) */
+    statusCode;
+    /** The request endpoint URL */
+    endpoint;
+    /** The response body text */
+    body;
+    constructor(statusCode, endpoint, body) {
+        super(`${endpoint}: ${statusCode} ${body}`);
+        this.name = "HomunculusApiError";
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        this.body = body;
+    }
+}
+/** Error thrown when an NDJSON stream contains malformed data. */
+class HomunculusStreamError extends Error {
+    /** The raw line that failed to parse */
+    rawLine;
+    constructor(rawLine, cause) {
+        super(`Failed to parse NDJSON line: ${rawLine}`);
+        this.name = "HomunculusStreamError";
+        this.rawLine = rawLine;
+        if (cause)
+            this.cause = cause;
+    }
+}
+exports.host = void 0;
+(function (host) {
+    let _baseUrl = "http://localhost:3100";
+    /**
+     * Configures the SDK's base URL for the Desktop Homunculus HTTP server.
+     *
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * host.configure({ baseUrl: "http://localhost:4000" });
+     * ```
+     */
+    function configure(options) {
+        _baseUrl = options.baseUrl.replace(/\/+$/, "");
+    }
+    host.configure = configure;
+    /** Returns the base URL for the Desktop Homunculus HTTP server. */
+    function base() {
+        return _baseUrl;
+    }
+    host.base = base;
+    /** Creates a new URL instance pointing to the base server. */
+    function baseUrl() {
+        return new URL(_baseUrl);
+    }
+    host.baseUrl = baseUrl;
+    /**
+     * Creates a URL for the Desktop Homunculus API with optional query parameters.
+     *
+     * @param path - The API endpoint path (relative to base URL)
+     * @param params - Optional query parameters to append to the URL
+     * @returns A URL instance ready for use in HTTP requests
+     *
+     * @example
+     * ```typescript
+     * // Simple path
+     * const url = host.createUrl("vrm");
+     * // Result: http://localhost:3100/vrm
+     *
+     * // With query parameters
+     * const url = host.createUrl("entities", { name: "VRM", root: 123 });
+     * // Result: http://localhost:3100/entities?name=VRM&root=123
+     * ```
+     */
+    function createUrl(path, params) {
+        const url = new URL(path, base());
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                url.searchParams.append(key, String(value));
+            });
+        }
+        return url;
+    }
+    host.createUrl = createUrl;
+    /**
+     * Performs a GET request to the specified URL with automatic error handling.
+     *
+     * @param url - The URL to send the GET request to
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * const response = await host.get(host.createUrl("vrm"));
+     * const data = await response.json();
+     * ```
+     */
+    async function get(url) {
+        const response = await fetch(url);
+        await throwIfError(response);
+        return response;
+    }
+    host.get = get;
+    /**
+     * Performs a POST request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the POST request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * const response = await host.post(
+     *   host.createUrl("vrm"),
+     *   { asset: "my-mod::character.vrm" }
+     * );
+     * ```
+     */
+    async function post(url, body) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body ?? {})
+        });
+        await throwIfError(response);
+        return response;
+    }
+    host.post = post;
+    /**
+     * Performs a PUT request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the PUT request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * await host.put(
+     *   host.createUrl("vrm/123/state"),
+     *   { state: "idle" }
+     * );
+     * ```
+     */
+    async function put(url, body) {
+        const response = await fetch(url, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body ?? {})
+        });
+        await throwIfError(response);
+        return response;
+    }
+    host.put = put;
+    /**
+     * Performs a PATCH request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the PATCH request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     */
+    async function patch(url, body) {
+        const response = await fetch(url, {
+            method: "PATCH",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body ?? {})
+        });
+        await throwIfError(response);
+        return response;
+    }
+    host.patch = patch;
+    async function deleteMethod(url) {
+        const response = await fetch(url, {
+            method: "DELETE"
+        });
+        await throwIfError(response);
+        return response;
+    }
+    host.deleteMethod = deleteMethod;
+    /**
+     * Performs a POST request and returns an async generator that yields
+     * parsed NDJSON objects from the streaming response.
+     *
+     * @param url - The URL to send the POST request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns An async generator yielding parsed JSON objects of type T
+     * @throws {HomunculusApiError} If the response status is >= 400
+     * @throws {HomunculusStreamError} If an NDJSON line cannot be parsed
+     *
+     * @example
+     * ```typescript
+     * const stream = host.postStream<MyEvent>(
+     *   host.createUrl("mods/my-mod/commands/execute"),
+     *   { command: "build" }
+     * );
+     * for await (const event of stream) {
+     *   console.log(event);
+     * }
+     * ```
+     */
+    async function* postStream(url, body, signal) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body ?? {}),
+            signal,
+        });
+        await throwIfError(response);
+        if (!response.body) {
+            return;
+        }
+        const reader = response.body
+            .pipeThrough(new TextDecoderStream())
+            .getReader();
+        let buffer = "";
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += value;
+                const lines = buffer.split("\n");
+                // Keep the last (possibly incomplete) chunk in the buffer
+                buffer = lines.pop();
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (trimmed.length === 0)
+                        continue;
+                    try {
+                        yield JSON.parse(trimmed);
+                    }
+                    catch (e) {
+                        throw new HomunculusStreamError(trimmed, e);
+                    }
+                }
+            }
+            // Process any remaining data in the buffer
+            const trimmed = buffer.trim();
+            if (trimmed.length > 0) {
+                try {
+                    yield JSON.parse(trimmed);
+                }
+                catch (e) {
+                    throw new HomunculusStreamError(trimmed, e);
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    host.postStream = postStream;
+})(exports.host || (exports.host = {}));
+async function throwIfError(response) {
+    if (!response.ok) {
+        throw new HomunculusApiError(response.status, response.url, await response.text());
+    }
+}
+
+exports.HomunculusApiError = HomunculusApiError;
+exports.HomunculusStreamError = HomunculusStreamError;

package/dist/host.js

@@ -0,0 +1,294 @@
+/**
+ * Host API namespace for low-level HTTP communication with the Desktop Homunculus server.
+ *
+ * This module provides the foundational HTTP client functionality used internally
+ * by all other SDK modules. It handles the base URL configuration, URL construction,
+ * and HTTP methods with automatic error handling.
+ *
+ * **Note:** This module is primarily for internal SDK use. Most developers should
+ * use the higher-level namespaces like `vrm`, `signals`, etc.
+ *
+ * @example
+ * ```typescript
+ * // Internal SDK usage (you typically won't need this directly)
+ * const response = await host.get(host.createUrl("vrm"));
+ * const vrms = await response.json();
+ *
+ * // URL construction with parameters
+ * const url = host.createUrl("vrm", { name: "MyCharacter" });
+ * // Results in: http://localhost:3100/vrm?name=MyCharacter
+ *
+ * // Configure the base URL (e.g., from an MCP server)
+ * host.configure({ baseUrl: "http://localhost:4000" });
+ * ```
+ */
+/** Error thrown when the Homunculus HTTP API returns a non-OK response. */
+class HomunculusApiError extends Error {
+    /** HTTP status code (e.g. 404, 500) */
+    statusCode;
+    /** The request endpoint URL */
+    endpoint;
+    /** The response body text */
+    body;
+    constructor(statusCode, endpoint, body) {
+        super(`${endpoint}: ${statusCode} ${body}`);
+        this.name = "HomunculusApiError";
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        this.body = body;
+    }
+}
+/** Error thrown when an NDJSON stream contains malformed data. */
+class HomunculusStreamError extends Error {
+    /** The raw line that failed to parse */
+    rawLine;
+    constructor(rawLine, cause) {
+        super(`Failed to parse NDJSON line: ${rawLine}`);
+        this.name = "HomunculusStreamError";
+        this.rawLine = rawLine;
+        if (cause)
+            this.cause = cause;
+    }
+}
+var host;
+(function (host) {
+    let _baseUrl = "http://localhost:3100";
+    /**
+     * Configures the SDK's base URL for the Desktop Homunculus HTTP server.
+     *
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * host.configure({ baseUrl: "http://localhost:4000" });
+     * ```
+     */
+    function configure(options) {
+        _baseUrl = options.baseUrl.replace(/\/+$/, "");
+    }
+    host.configure = configure;
+    /** Returns the base URL for the Desktop Homunculus HTTP server. */
+    function base() {
+        return _baseUrl;
+    }
+    host.base = base;
+    /** Creates a new URL instance pointing to the base server. */
+    function baseUrl() {
+        return new URL(_baseUrl);
+    }
+    host.baseUrl = baseUrl;
+    /**
+     * Creates a URL for the Desktop Homunculus API with optional query parameters.
+     *
+     * @param path - The API endpoint path (relative to base URL)
+     * @param params - Optional query parameters to append to the URL
+     * @returns A URL instance ready for use in HTTP requests
+     *
+     * @example
+     * ```typescript
+     * // Simple path
+     * const url = host.createUrl("vrm");
+     * // Result: http://localhost:3100/vrm
+     *
+     * // With query parameters
+     * const url = host.createUrl("entities", { name: "VRM", root: 123 });
+     * // Result: http://localhost:3100/entities?name=VRM&root=123
+     * ```
+     */
+    function createUrl(path, params) {
+        const url = new URL(path, base());
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                url.searchParams.append(key, String(value));
+            });
+        }
+        return url;
+    }
+    host.createUrl = createUrl;
+    /**
+     * Performs a GET request to the specified URL with automatic error handling.
+     *
+     * @param url - The URL to send the GET request to
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * const response = await host.get(host.createUrl("vrm"));
+     * const data = await response.json();
+     * ```
+     */
+    async function get(url) {
+        const response = await fetch(url);
+        await throwIfError(response);
+        return response;
+    }
+    host.get = get;
+    /**
+     * Performs a POST request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the POST request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * const response = await host.post(
+     *   host.createUrl("vrm"),
+     *   { asset: "my-mod::character.vrm" }
+     * );
+     * ```
+     */
+    async function post(url, body) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body ?? {})
+        });
+        await throwIfError(response);
+        return response;
+    }
+    host.post = post;
+    /**
+     * Performs a PUT request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the PUT request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * await host.put(
+     *   host.createUrl("vrm/123/state"),
+     *   { state: "idle" }
+     * );
+     * ```
+     */
+    async function put(url, body) {
+        const response = await fetch(url, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body ?? {})
+        });
+        await throwIfError(response);
+        return response;
+    }
+    host.put = put;
+    /**
+     * Performs a PATCH request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the PATCH request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     */
+    async function patch(url, body) {
+        const response = await fetch(url, {
+            method: "PATCH",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body ?? {})
+        });
+        await throwIfError(response);
+        return response;
+    }
+    host.patch = patch;
+    async function deleteMethod(url) {
+        const response = await fetch(url, {
+            method: "DELETE"
+        });
+        await throwIfError(response);
+        return response;
+    }
+    host.deleteMethod = deleteMethod;
+    /**
+     * Performs a POST request and returns an async generator that yields
+     * parsed NDJSON objects from the streaming response.
+     *
+     * @param url - The URL to send the POST request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns An async generator yielding parsed JSON objects of type T
+     * @throws {HomunculusApiError} If the response status is >= 400
+     * @throws {HomunculusStreamError} If an NDJSON line cannot be parsed
+     *
+     * @example
+     * ```typescript
+     * const stream = host.postStream<MyEvent>(
+     *   host.createUrl("mods/my-mod/commands/execute"),
+     *   { command: "build" }
+     * );
+     * for await (const event of stream) {
+     *   console.log(event);
+     * }
+     * ```
+     */
+    async function* postStream(url, body, signal) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body ?? {}),
+            signal,
+        });
+        await throwIfError(response);
+        if (!response.body) {
+            return;
+        }
+        const reader = response.body
+            .pipeThrough(new TextDecoderStream())
+            .getReader();
+        let buffer = "";
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += value;
+                const lines = buffer.split("\n");
+                // Keep the last (possibly incomplete) chunk in the buffer
+                buffer = lines.pop();
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (trimmed.length === 0)
+                        continue;
+                    try {
+                        yield JSON.parse(trimmed);
+                    }
+                    catch (e) {
+                        throw new HomunculusStreamError(trimmed, e);
+                    }
+                }
+            }
+            // Process any remaining data in the buffer
+            const trimmed = buffer.trim();
+            if (trimmed.length > 0) {
+                try {
+                    yield JSON.parse(trimmed);
+                }
+                catch (e) {
+                    throw new HomunculusStreamError(trimmed, e);
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    host.postStream = postStream;
+})(host || (host = {}));
+async function throwIfError(response) {
+    if (!response.ok) {
+        throw new HomunculusApiError(response.status, response.url, await response.text());
+    }
+}
+
+export { HomunculusApiError, HomunculusStreamError, host };

package/dist/index.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+var coordinates = require('./coordinates.cjs');
+var displays = require('./displays.cjs');
+var audio = require('./audio.cjs');
+var effects = require('./effects.cjs');
+var host = require('./host.cjs');
+var preferences = require('./preferences.cjs');
+var settings = require('./settings.cjs');
+var shadowPanel = require('./shadowPanel.cjs');
+var vrm = require('./vrm.cjs');
+var speech = require('./speech.cjs');
+var webviews = require('./webviews.cjs');
+var signals = require('./signals.cjs');
+var entities = require('./entities.cjs');
+var app = require('./app.cjs');
+var mods = require('./mods.cjs');
+var assets = require('./assets.cjs');
+var utils = require('./utils.cjs');
+
+
+
+Object.defineProperty(exports, "coordinates", {
+	enumerable: true,
+	get: function () { return coordinates.coordinates; }
+});
+Object.defineProperty(exports, "displays", {
+	enumerable: true,
+	get: function () { return displays.displays; }
+});
+Object.defineProperty(exports, "audio", {
+	enumerable: true,
+	get: function () { return audio.audio; }
+});
+Object.defineProperty(exports, "effects", {
+	enumerable: true,
+	get: function () { return effects.effects; }
+});
+exports.HomunculusApiError = host.HomunculusApiError;
+exports.HomunculusStreamError = host.HomunculusStreamError;
+Object.defineProperty(exports, "host", {
+	enumerable: true,
+	get: function () { return host.host; }
+});
+Object.defineProperty(exports, "preferences", {
+	enumerable: true,
+	get: function () { return preferences.preferences; }
+});
+Object.defineProperty(exports, "settings", {
+	enumerable: true,
+	get: function () { return settings.settings; }
+});
+Object.defineProperty(exports, "shadowPanel", {
+	enumerable: true,
+	get: function () { return shadowPanel.shadowPanel; }
+});
+exports.Vrm = vrm.Vrm;
+exports.VrmEventSource = vrm.VrmEventSource;
+Object.defineProperty(exports, "repeat", {
+	enumerable: true,
+	get: function () { return vrm.repeat; }
+});
+Object.defineProperty(exports, "speech", {
+	enumerable: true,
+	get: function () { return speech.speech; }
+});
+exports.Webview = webviews.Webview;
+exports.isWebviewSourceHtml = webviews.isWebviewSourceHtml;
+exports.isWebviewSourceInfoHtml = webviews.isWebviewSourceInfoHtml;
+exports.isWebviewSourceInfoLocal = webviews.isWebviewSourceInfoLocal;
+exports.isWebviewSourceInfoUrl = webviews.isWebviewSourceInfoUrl;
+exports.isWebviewSourceLocal = webviews.isWebviewSourceLocal;
+exports.isWebviewSourceUrl = webviews.isWebviewSourceUrl;
+Object.defineProperty(exports, "webviewSource", {
+	enumerable: true,
+	get: function () { return webviews.webviewSource; }
+});
+Object.defineProperty(exports, "signals", {
+	enumerable: true,
+	get: function () { return signals.signals; }
+});
+Object.defineProperty(exports, "entities", {
+	enumerable: true,
+	get: function () { return entities.entities; }
+});
+Object.defineProperty(exports, "app", {
+	enumerable: true,
+	get: function () { return app.app; }
+});
+Object.defineProperty(exports, "mods", {
+	enumerable: true,
+	get: function () { return mods.mods; }
+});
+Object.defineProperty(exports, "assets", {
+	enumerable: true,
+	get: function () { return assets.assets; }
+});
+exports.sleep = utils.sleep;