@jdg-keyforge/protocol 0.10.0 → 0.12.0

package/src/methods/install_plugin.ts

@@ -0,0 +1,166 @@
+/* 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.
+ */
+
+/**
+ * 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/src/methods/list_devices.ts

@@ -13,6 +13,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.
@@ -76,4 +80,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;
 }

package/src/methods/list_plugins.ts

@@ -0,0 +1,163 @@
+/* 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.
+ */
+
+/**
+ * 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";
+
+/**
+ * Returns every installed plugin with the state of its process. No params in v1.
+ */
+export interface MethodListPlugins {
+  /**
+   * No parameters in v1.
+   */
+  params: {};
+  result: {
+    /**
+     * Installed plugins.
+     */
+    plugins: InstalledPlugin[];
+  };
+}
+/**
+ * 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/src/methods/list_profiles.ts

@@ -13,6 +13,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;
 
 /**
  * Returns all profiles the daemon currently has, along with the id of the active one. The active profile id is tracked at the daemon level and only exposed here.
@@ -49,6 +53,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.
@@ -74,3 +82,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/src/methods/set_input_color.ts

@@ -0,0 +1,33 @@
+/* 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.
+ */
+
+/**
+ * Stable identifier for a HID device. Format: VID_<hex>_PID_<hex>[_<serial>].
+ */
+export type DeviceID = 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 Color = string;
+
+/**
+ * Sets the LED color of an RGB-capable input in the active profile and paints it on the device. The pair (device_id, input_id) is the unique key; calling this method again replaces the previous color, and '#000000' turns the LED off. Colors belong to the profile: switching profiles repaints every RGB input with the new profile's colors. The daemon rejects inputs that are unknown or have no RGB LED (Input.rgb is not true).
+ */
+export interface MethodSetInputColor {
+  params: {
+    device_id: DeviceID;
+    /**
+     * Logical identifier of the input within the device. Matches Device.inputs[].id.
+     */
+    input_id: string;
+    color: Color;
+  };
+  /**
+   * Empty acknowledgement object.
+   */
+  result: {};
+}

package/src/methods/uninstall_plugin.ts

@@ -0,0 +1,24 @@
+/* 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.
+ */
+
+/**
+ * Id of the plugin to uninstall.
+ */
+export type PluginID = string;
+
+/**
+ * Stops the plugin's process and deletes its folder. Bindings that use the plugin's actions are left untouched (orphaned): while the plugin is missing, firing them does nothing, and reinstalling the plugin makes them work again.
+ */
+export interface MethodUninstallPlugin {
+  params: {
+    id: PluginID;
+  };
+  /**
+   * Empty acknowledgement object. Reserved for future fields without breaking the schema.
+   */
+  result: {};
+}