@jdg-keyforge/protocol 0.10.0 → 0.12.0

package/dist/common.d.ts

@@ -24,6 +24,17 @@ export type InputKind = "key" | "encoder";
  * via the `definition` "InputAction".
  */
 export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+/**
+ * RGB color as a '#RRGGBB' hex string. Accepted in any case; the daemon stores and returns it lowercase, so clients can compare colors as strings. '#000000' turns the LED off. Hardware-agnostic: the daemon translates it to whatever the device understands (e.g. switching the device to a per-key lighting mode first).
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "Color".
+ */
+export type Color = string;
+/**
+ * RGB color as a '#RRGGBB' hex string. Accepted in any case; the daemon stores and returns it lowercase, so clients can compare colors as strings. '#000000' turns the LED off. Hardware-agnostic: the daemon translates it to whatever the device understands (e.g. switching the device to a per-key lighting mode first).
+ */
+export type Color1 = string;
 /**
  * Globally unique plugin identifier in reverse-DNS form (e.g. 'dev.jonidg.spotify'). Lowercase, at least two dot-separated segments, each starting with a letter. Used as the install folder name and as <plugin_id> in Action.type.
  *
@@ -163,6 +174,24 @@ export interface Profile {
      * Bindings that belong to this profile.
      */
     bindings: Binding[];
+    /**
+     * LED colors this profile paints on RGB-capable inputs, applied by the daemon whenever the profile becomes active. An RGB input with no entry here is turned off. At most one entry per (device_id, input_id); the daemon enforces uniqueness. Absent means no colors.
+     */
+    colors?: InputColor[];
+}
+/**
+ * LED color assigned to one input of a device.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "InputColor".
+ */
+export interface InputColor {
+    device_id: DeviceID;
+    /**
+     * Logical identifier of the input within the device. Matches Device.inputs[].id.
+     */
+    input_id: string;
+    color: Color;
 }
 /**
  * Portable, on-disk representation of a profile, written by export_profile and read by import_profile. Carries no server-local id: the id is meaningless outside the originating installation, so import always assigns a fresh one. The 'version' field lets readers detect and adapt to format changes.
@@ -187,6 +216,10 @@ export interface ExportedProfile {
      * Bindings that belong to the exported profile.
      */
     bindings: Binding[];
+    /**
+     * LED colors of the exported profile. Same semantics as Profile.colors.
+     */
+    colors?: InputColor[];
 }
 /**
  * A single physical input exposed by a device (a key or an encoder).
@@ -204,6 +237,11 @@ export interface Input {
      * Human-friendly label for the input (e.g. 'Key 1', 'Encoder'). Optional; clients fall back to id.
      */
     label?: string;
+    /**
+     * Whether the input has an RGB LED the daemon can drive through set_input_color. Absent means false.
+     */
+    rgb?: boolean;
+    color?: Color1;
 }
 /**
  * A HID device known to the daemon. Returned by list_devices.
@@ -300,6 +338,23 @@ export interface PluginLaunchInfo {
      */
     protocol_version: "1";
 }
+/**
+ * A plugin installed in the daemon, with the state of its process.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "InstalledPlugin".
+ */
+export interface InstalledPlugin {
+    manifest: PluginManifest;
+    /**
+     * State of the plugin process: 'starting' (spawned, hello not received yet), 'running' (connected), 'stopped' (not running, e.g. exited cleanly) or 'error' (failed to start or crashed; see 'error').
+     */
+    status: "starting" | "running" | "stopped" | "error";
+    /**
+     * Human-readable reason why the plugin failed. The daemon sets it only when status is 'error' (not enforced by the schema).
+     */
+    error?: string;
+}
 /**
  * Contents of the manifest.json file at the root of a plugin. A plugin is distributed as a '.keyforgeplugin' file: a zip archive with manifest.json at its root (no wrapping folder) plus every file the manifest references. The daemon installs it by extracting the archive into '<config dir>/plugins/<id>/', taking the id from the manifest. All file paths in the manifest (icon, and entrypoint paths containing '/') are relative to the plugin root, use '/' as separator, and must stay inside the plugin root: the daemon rejects '..' segments and any path or archive entry that escapes the root.
  *

package/dist/index.d.ts

@@ -7,14 +7,19 @@ export type { MethodExportProfile } from './methods/export_profile.js';
 export type { MethodGetAutoSwitch } from './methods/get_auto_switch.js';
 export type { MethodHello } from './methods/hello.js';
 export type { MethodImportProfile } from './methods/import_profile.js';
+export type { MethodInspectPlugin } from './methods/inspect_plugin.js';
+export type { MethodInstallPlugin } from './methods/install_plugin.js';
 export type { MethodListActions } from './methods/list_actions.js';
 export type { MethodListBindings } from './methods/list_bindings.js';
 export type { MethodListDevices } from './methods/list_devices.js';
+export type { MethodListPlugins } from './methods/list_plugins.js';
 export type { MethodListProfiles } from './methods/list_profiles.js';
 export type { MethodRenameProfile } from './methods/rename_profile.js';
 export type { MethodSetActiveProfile } from './methods/set_active_profile.js';
 export type { MethodSetAutoSwitch } from './methods/set_auto_switch.js';
 export type { MethodSetBinding } from './methods/set_binding.js';
+export type { MethodSetInputColor } from './methods/set_input_color.js';
+export type { MethodUninstallPlugin } from './methods/uninstall_plugin.js';
 export type { EventActionInvoked } from './events/action_invoked.js';
 export type { EventActiveProfileChanged } from './events/active_profile_changed.js';
 export type { EventInput } from './events/input.js';

package/dist/methods/create_profile.d.ts

@@ -11,6 +11,10 @@ export type DeviceID = string;
  * What happened on the input.
  */
 export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+/**
+ * RGB color as a '#RRGGBB' hex string. Accepted in any case; the daemon stores and returns it lowercase, so clients can compare colors as strings. '#000000' turns the LED off. Hardware-agnostic: the daemon translates it to whatever the device understands (e.g. switching the device to a per-key lighting mode first).
+ */
+export type Color = string;
 /**
  * Creates a new profile. The server generates the id and returns the profile with an empty bindings array.
  */
@@ -41,6 +45,10 @@ export interface Profile {
      * Bindings that belong to this profile.
      */
     bindings: Binding[];
+    /**
+     * LED colors this profile paints on RGB-capable inputs, applied by the daemon whenever the profile becomes active. An RGB input with no entry here is turned off. At most one entry per (device_id, input_id); the daemon enforces uniqueness. Absent means no colors.
+     */
+    colors?: InputColor[];
 }
 /**
  * Maps an input on a specific device to an action.
@@ -66,3 +74,14 @@ export interface Action {
         [k: string]: unknown;
     };
 }
+/**
+ * LED color assigned to one input of a device.
+ */
+export interface InputColor {
+    device_id: DeviceID;
+    /**
+     * Logical identifier of the input within the device. Matches Device.inputs[].id.
+     */
+    input_id: string;
+    color: Color;
+}

package/dist/methods/duplicate_profile.d.ts

@@ -11,6 +11,10 @@ export type DeviceID = string;
  * What happened on the input.
  */
 export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+/**
+ * RGB color as a '#RRGGBB' hex string. Accepted in any case; the daemon stores and returns it lowercase, so clients can compare colors as strings. '#000000' turns the LED off. Hardware-agnostic: the daemon translates it to whatever the device understands (e.g. switching the device to a per-key lighting mode first).
+ */
+export type Color = string;
 /**
  * Creates a copy of an existing profile under a new name. The server generates a new id and copies the source profile's bindings. Does not change the active profile.
  */
@@ -45,6 +49,10 @@ export interface Profile {
      * Bindings that belong to this profile.
      */
     bindings: Binding[];
+    /**
+     * LED colors this profile paints on RGB-capable inputs, applied by the daemon whenever the profile becomes active. An RGB input with no entry here is turned off. At most one entry per (device_id, input_id); the daemon enforces uniqueness. Absent means no colors.
+     */
+    colors?: InputColor[];
 }
 /**
  * Maps an input on a specific device to an action.
@@ -70,3 +78,14 @@ export interface Action {
         [k: string]: unknown;
     };
 }
+/**
+ * LED color assigned to one input of a device.
+ */
+export interface InputColor {
+    device_id: DeviceID;
+    /**
+     * Logical identifier of the input within the device. Matches Device.inputs[].id.
+     */
+    input_id: string;
+    color: Color;
+}

package/dist/methods/import_profile.d.ts

@@ -11,6 +11,10 @@ export type DeviceID = string;
  * What happened on the input.
  */
 export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+/**
+ * RGB color as a '#RRGGBB' hex string. Accepted in any case; the daemon stores and returns it lowercase, so clients can compare colors as strings. '#000000' turns the LED off. Hardware-agnostic: the daemon translates it to whatever the device understands (e.g. switching the device to a per-key lighting mode first).
+ */
+export type Color = string;
 /**
  * Reads an ExportedProfile document from 'path' on the daemon host's filesystem, validates it, and creates a new profile from it. The server generates a fresh id; any id in the file is ignored. Does not change the active profile. Returns the created profile.
  */
@@ -41,6 +45,10 @@ export interface Profile {
      * Bindings that belong to this profile.
      */
     bindings: Binding[];
+    /**
+     * LED colors this profile paints on RGB-capable inputs, applied by the daemon whenever the profile becomes active. An RGB input with no entry here is turned off. At most one entry per (device_id, input_id); the daemon enforces uniqueness. Absent means no colors.
+     */
+    colors?: InputColor[];
 }
 /**
  * Maps an input on a specific device to an action.
@@ -66,3 +74,14 @@ export interface Action {
         [k: string]: unknown;
     };
 }
+/**
+ * LED color assigned to one input of a device.
+ */
+export interface InputColor {
+    device_id: DeviceID;
+    /**
+     * Logical identifier of the input within the device. Matches Device.inputs[].id.
+     */
+    input_id: string;
+    color: Color;
+}

package/dist/methods/inspect_plugin.d.ts

@@ -0,0 +1,149 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * Globally unique reverse-DNS plugin id; install folder name and <plugin_id> in Action.type.
+ */
+export type PluginID = string;
+/**
+ * Kind of physical input.
+ */
+export type InputKind = "key" | "encoder";
+/**
+ * Opens the '.keyforgeplugin' package at 'path' on the daemon host's filesystem and validates it exactly as install_plugin would (including rejecting a package with no entrypoint for the daemon host's OS), without installing or changing anything. Lets a client show a confirmation (name, author, version, actions) before installing.
+ */
+export interface MethodInspectPlugin {
+    params: {
+        /**
+         * Filesystem path on the daemon host of the '.keyforgeplugin' package.
+         */
+        path: string;
+    };
+    result: {
+        manifest: PluginManifest;
+        /**
+         * Version of the plugin with the same id that is currently installed, if any. Installing the package would replace it.
+         */
+        installed_version?: string;
+    };
+}
+/**
+ * Contents of the manifest.json file at the root of a plugin. A plugin is distributed as a '.keyforgeplugin' file: a zip archive with manifest.json at its root (no wrapping folder) plus every file the manifest references. The daemon installs it by extracting the archive into '<config dir>/plugins/<id>/', taking the id from the manifest. All file paths in the manifest (icon, and entrypoint paths containing '/') are relative to the plugin root, use '/' as separator, and must stay inside the plugin root: the daemon rejects '..' segments and any path or archive entry that escapes the root.
+ */
+export interface PluginManifest {
+    /**
+     * Manifest format version. Currently 1; bumped if the manifest shape changes.
+     */
+    manifest_version: 1;
+    id: PluginID;
+    /**
+     * Human-friendly plugin name for the UI.
+     */
+    name: string;
+    /**
+     * Plugin version (SemVer 2.0).
+     */
+    version: string;
+    /**
+     * Major version of the protocol the plugin speaks. Lets the daemon reject an incompatible plugin before spawning it. Currently '1'.
+     */
+    protocol_version: "1";
+    /**
+     * Plugin author, shown in the UI.
+     */
+    author?: string;
+    /**
+     * Short description of what the plugin does.
+     */
+    description?: string;
+    /**
+     * URL of the plugin homepage or source repository.
+     */
+    homepage?: string;
+    /**
+     * Category the UI groups the plugin's actions under (e.g. 'Audio', 'Streaming').
+     */
+    category?: string;
+    /**
+     * Path to the plugin icon, relative to the plugin root. No leading '/', no '\' and no ':'.
+     */
+    icon?: string;
+    /**
+     * Command the daemon runs to start the plugin, per OS (keys match Go's GOOS). The plugin supports exactly the OSes listed here.
+     */
+    entrypoint: {
+        darwin?: PluginCommand;
+        linux?: PluginCommand;
+        windows?: PluginCommand;
+    };
+    /**
+     * Actions the plugin exposes. Each becomes bindable as 'plugin.<id>.<action id>'.
+     *
+     * @minItems 1
+     */
+    actions: [PluginAction, ...PluginAction[]];
+}
+/**
+ * Executable plus arguments used to start a plugin process.
+ */
+export interface PluginCommand {
+    /**
+     * Executable to run. A path containing '/' is resolved relative to the plugin root; a bare name (e.g. 'node') is looked up on the PATH. Always use '/' as separator, also on Windows; absolute paths, '\' and ':' are not allowed.
+     */
+    path: string;
+    /**
+     * Arguments passed to the executable.
+     */
+    args?: string[];
+}
+/**
+ * An action a plugin exposes, declared in its manifest.
+ */
+export interface PluginAction {
+    /**
+     * Action identifier, unique within the plugin. snake_case, no dots.
+     */
+    id: string;
+    /**
+     * Human-friendly action name for the UI.
+     */
+    name: string;
+    /**
+     * Optional longer description of what the action does.
+     */
+    description?: string;
+    /**
+     * Input kinds the action can be bound to. Omitted means any kind.
+     *
+     * @minItems 1
+     */
+    inputs?: [InputKind, ...InputKind[]];
+    /**
+     * Params this action accepts, in display order.
+     */
+    params: ParamSpec[];
+}
+/**
+ * Describes one action parameter so a client can render an input for it.
+ */
+export interface ParamSpec {
+    /**
+     * Param key written into Action.params. Unique within the action.
+     */
+    name: string;
+    /**
+     * Human-friendly field label.
+     */
+    label: string;
+    /**
+     * Param value type. Only 'string' in v1.
+     */
+    type: "string";
+    required: boolean;
+    /**
+     * Optional placeholder/example shown in the input.
+     */
+    placeholder?: string;
+}

package/dist/methods/inspect_plugin.js

@@ -0,0 +1,7 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+export {};

package/dist/methods/install_plugin.d.ts

@@ -0,0 +1,163 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * Globally unique reverse-DNS plugin id; install folder name and <plugin_id> in Action.type.
+ */
+export type PluginID = string;
+/**
+ * Kind of physical input.
+ */
+export type InputKind = "key" | "encoder";
+/**
+ * Installs the '.keyforgeplugin' package at 'path' on the daemon host's filesystem: validates it, extracts it into '<config dir>/plugins/<id>/' and starts the plugin. A package with no entrypoint for the daemon host's OS is rejected with an error and nothing is installed. The response is sent right after spawning, so the returned status is normally 'starting'; clients refresh with list_plugins. If a plugin with the same id is already installed, it is replaced (upgrade): the old process is stopped and its folder swapped atomically. Bindings are never modified, so existing bindings to the plugin's actions keep working after an upgrade.
+ */
+export interface MethodInstallPlugin {
+    params: {
+        /**
+         * Filesystem path on the daemon host of the '.keyforgeplugin' package.
+         */
+        path: string;
+    };
+    result: {
+        plugin: InstalledPlugin;
+        /**
+         * Version that was replaced, present only when the install was an upgrade.
+         */
+        previous_version?: string;
+    };
+}
+/**
+ * A plugin installed in the daemon, with the state of its process.
+ */
+export interface InstalledPlugin {
+    manifest: PluginManifest;
+    /**
+     * State of the plugin process: 'starting' (spawned, hello not received yet), 'running' (connected), 'stopped' (not running, e.g. exited cleanly) or 'error' (failed to start or crashed; see 'error').
+     */
+    status: "starting" | "running" | "stopped" | "error";
+    /**
+     * Human-readable reason why the plugin failed. The daemon sets it only when status is 'error' (not enforced by the schema).
+     */
+    error?: string;
+}
+/**
+ * Contents of the manifest.json file at the root of a plugin. A plugin is distributed as a '.keyforgeplugin' file: a zip archive with manifest.json at its root (no wrapping folder) plus every file the manifest references. The daemon installs it by extracting the archive into '<config dir>/plugins/<id>/', taking the id from the manifest. All file paths in the manifest (icon, and entrypoint paths containing '/') are relative to the plugin root, use '/' as separator, and must stay inside the plugin root: the daemon rejects '..' segments and any path or archive entry that escapes the root.
+ */
+export interface PluginManifest {
+    /**
+     * Manifest format version. Currently 1; bumped if the manifest shape changes.
+     */
+    manifest_version: 1;
+    id: PluginID;
+    /**
+     * Human-friendly plugin name for the UI.
+     */
+    name: string;
+    /**
+     * Plugin version (SemVer 2.0).
+     */
+    version: string;
+    /**
+     * Major version of the protocol the plugin speaks. Lets the daemon reject an incompatible plugin before spawning it. Currently '1'.
+     */
+    protocol_version: "1";
+    /**
+     * Plugin author, shown in the UI.
+     */
+    author?: string;
+    /**
+     * Short description of what the plugin does.
+     */
+    description?: string;
+    /**
+     * URL of the plugin homepage or source repository.
+     */
+    homepage?: string;
+    /**
+     * Category the UI groups the plugin's actions under (e.g. 'Audio', 'Streaming').
+     */
+    category?: string;
+    /**
+     * Path to the plugin icon, relative to the plugin root. No leading '/', no '\' and no ':'.
+     */
+    icon?: string;
+    /**
+     * Command the daemon runs to start the plugin, per OS (keys match Go's GOOS). The plugin supports exactly the OSes listed here.
+     */
+    entrypoint: {
+        darwin?: PluginCommand;
+        linux?: PluginCommand;
+        windows?: PluginCommand;
+    };
+    /**
+     * Actions the plugin exposes. Each becomes bindable as 'plugin.<id>.<action id>'.
+     *
+     * @minItems 1
+     */
+    actions: [PluginAction, ...PluginAction[]];
+}
+/**
+ * Executable plus arguments used to start a plugin process.
+ */
+export interface PluginCommand {
+    /**
+     * Executable to run. A path containing '/' is resolved relative to the plugin root; a bare name (e.g. 'node') is looked up on the PATH. Always use '/' as separator, also on Windows; absolute paths, '\' and ':' are not allowed.
+     */
+    path: string;
+    /**
+     * Arguments passed to the executable.
+     */
+    args?: string[];
+}
+/**
+ * An action a plugin exposes, declared in its manifest.
+ */
+export interface PluginAction {
+    /**
+     * Action identifier, unique within the plugin. snake_case, no dots.
+     */
+    id: string;
+    /**
+     * Human-friendly action name for the UI.
+     */
+    name: string;
+    /**
+     * Optional longer description of what the action does.
+     */
+    description?: string;
+    /**
+     * Input kinds the action can be bound to. Omitted means any kind.
+     *
+     * @minItems 1
+     */
+    inputs?: [InputKind, ...InputKind[]];
+    /**
+     * Params this action accepts, in display order.
+     */
+    params: ParamSpec[];
+}
+/**
+ * Describes one action parameter so a client can render an input for it.
+ */
+export interface ParamSpec {
+    /**
+     * Param key written into Action.params. Unique within the action.
+     */
+    name: string;
+    /**
+     * Human-friendly field label.
+     */
+    label: string;
+    /**
+     * Param value type. Only 'string' in v1.
+     */
+    type: "string";
+    required: boolean;
+    /**
+     * Optional placeholder/example shown in the input.
+     */
+    placeholder?: string;
+}

package/dist/methods/install_plugin.js

@@ -0,0 +1,7 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+export {};

package/dist/methods/list_devices.d.ts

@@ -11,6 +11,10 @@ export type DeviceID = string;
  * Kind of physical input.
  */
 export type InputKind = "key" | "encoder";
+/**
+ * Color the active profile paints on this input. Only set on RGB inputs that have a color in the active profile; absent means the LED is off.
+ */
+export type Color = string;
 /**
  * Returns the HID devices currently known to the daemon. No filters in v1; clients filter client-side if needed.
  */
@@ -73,4 +77,9 @@ export interface Input {
      * Human-friendly label for the input (e.g. 'Key 1', 'Encoder'). Optional; clients fall back to id.
      */
     label?: string;
+    /**
+     * Whether the input has an RGB LED the daemon can drive through set_input_color. Absent means false.
+     */
+    rgb?: boolean;
+    color?: Color;
 }