@jdg-keyforge/protocol 0.12.0 → 0.13.0

package/dist/common.d.ts

@@ -35,6 +35,13 @@ 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;
+/**
+ * Clockwise rotation, in degrees, applied to the canonical orientation of a device's layout so clients show it the way the user has the device on the desk. Presentation only: bindings and colors stay tied to the physical input (input_id) and do not change when the device is rotated. It is a per-device preference, not a per-profile one: switching profiles does not change it. Set through set_device_rotation and exposed in Device.rotation, where absent means 0.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "DeviceRotation".
+ */
+export type DeviceRotation = 0 | 90 | 180 | 270;
 /**
  * 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.
  *
@@ -234,15 +241,40 @@ export interface Input {
     id: string;
     kind: InputKind;
     /**
-     * Human-friendly label for the input (e.g. 'Key 1', 'Encoder'). Optional; clients fall back to id.
+     * Fixed name of the input (e.g. 'Enter', 'Play') that clients show as-is in any orientation. When absent, clients name the input by position: they number inputs per kind in reading order of the current view, sorting by each input's top-left corner after applying Device.rotation (y first, then x), so 'Key 1' is always the top-left key as the device sits on the desk. If the device has no complete layout, they number inputs per kind in the order list_devices returns them. Catalogs should not send positional labels like 'Key 1': they would be wrong once the device is rotated.
      */
     label?: string;
+    layout?: InputLayout;
     /**
      * Whether the input has an RGB LED the daemon can drive through set_input_color. Absent means false.
      */
     rgb?: boolean;
     color?: Color1;
 }
+/**
+ * Physical position and size of an input, in key units (1 = one standard key). Fractions are allowed (e.g. x: 5.5 leaves a gap before a column of encoders). Coordinates are in the device's canonical orientation, defined by the daemon's device catalog: the origin is the top-left corner and y grows downwards. This is a coordinate system, not how the user has the device on the desk (that is Device.rotation). The shape is not modeled: clients derive it from Input.kind (key = rectangle, encoder = circle). Clients can draw a device only when every one of its inputs has a layout; otherwise they fall back to a view without positions (e.g. a list). Prior art: the {x, y, w, h} key model of QMK/VIA info.json.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "InputLayout".
+ */
+export interface InputLayout {
+    /**
+     * Horizontal position of the input's top-left corner, in key units.
+     */
+    x: number;
+    /**
+     * Vertical position of the input's top-left corner, in key units. Grows downwards.
+     */
+    y: number;
+    /**
+     * Width in key units. Absent means 1.
+     */
+    w?: number;
+    /**
+     * Height in key units. Absent means 1.
+     */
+    h?: number;
+}
 /**
  * A HID device known to the daemon. Returned by list_devices.
  *
@@ -279,6 +311,7 @@ export interface Device {
      * Inputs (keys/encoders) the daemon knows this device exposes. Empty for unrecognized devices the daemon can't map.
      */
     inputs: Input[];
+    rotation?: DeviceRotation;
 }
 /**
  * Maps a foreground application to the profile that should become active while that app is frontmost. When the frontmost app matches no rule, the active profile is left unchanged (sticky behavior); there is no fallback profile.
@@ -292,7 +325,7 @@ export interface AutoSwitchRule {
      */
     app: string;
     /**
-     * Identifier of the profile to activate when this app is frontmost.
+     * Identifier of the profile to activate when this app is frontmost. Must reference an existing profile: set_auto_switch rejects unknown ids with PROFILE_NOT_FOUND, and delete_profile removes the rules pointing to the deleted profile.
      */
     profile_id: string;
 }

package/dist/index.d.ts

@@ -18,6 +18,7 @@ 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 { MethodSetDeviceRotation } from './methods/set_device_rotation.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';

package/dist/methods/delete_profile.d.ts

@@ -4,7 +4,7 @@
  * and run json-schema-to-typescript to regenerate this file.
  */
 /**
- * Deletes a profile. The daemon never deletes the last remaining profile. Deleting the active profile reassigns the active one, so the resulting active profile id is always returned.
+ * Deletes a profile. The daemon never deletes the last remaining profile. Deleting the active profile reassigns the active one, so the resulting active profile id is always returned. Auto-switch rules whose profile_id points to the deleted profile are deleted with it, so the stored rule set never references a missing profile.
  */
 export interface MethodDeleteProfile {
     params: {

package/dist/methods/get_auto_switch.d.ts

@@ -31,7 +31,7 @@ export interface AutoSwitchRule {
      */
     app: string;
     /**
-     * Identifier of the profile to activate when this app is frontmost.
+     * Identifier of the profile to activate when this app is frontmost. Must reference an existing profile: set_auto_switch rejects unknown ids with PROFILE_NOT_FOUND, and delete_profile removes the rules pointing to the deleted profile.
      */
     profile_id: string;
 }

package/dist/methods/list_devices.d.ts

@@ -15,6 +15,10 @@ 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;
+/**
+ * Clockwise rotation, in degrees, applied to the canonical orientation of a device's layout so clients show it the way the user has the device on the desk. Presentation only: bindings and colors stay tied to the physical input (input_id) and do not change when the device is rotated. It is a per-device preference, not a per-profile one: switching profiles does not change it. Set through set_device_rotation and exposed in Device.rotation, where absent means 0.
+ */
+export type DeviceRotation = 0 | 90 | 180 | 270;
 /**
  * Returns the HID devices currently known to the daemon. No filters in v1; clients filter client-side if needed.
  */
@@ -63,6 +67,7 @@ export interface Device {
      * Inputs (keys/encoders) the daemon knows this device exposes. Empty for unrecognized devices the daemon can't map.
      */
     inputs: Input[];
+    rotation?: DeviceRotation;
 }
 /**
  * A single physical input exposed by a device (a key or an encoder).
@@ -74,12 +79,34 @@ export interface Input {
     id: string;
     kind: InputKind;
     /**
-     * Human-friendly label for the input (e.g. 'Key 1', 'Encoder'). Optional; clients fall back to id.
+     * Fixed name of the input (e.g. 'Enter', 'Play') that clients show as-is in any orientation. When absent, clients name the input by position: they number inputs per kind in reading order of the current view, sorting by each input's top-left corner after applying Device.rotation (y first, then x), so 'Key 1' is always the top-left key as the device sits on the desk. If the device has no complete layout, they number inputs per kind in the order list_devices returns them. Catalogs should not send positional labels like 'Key 1': they would be wrong once the device is rotated.
      */
     label?: string;
+    layout?: InputLayout;
     /**
      * Whether the input has an RGB LED the daemon can drive through set_input_color. Absent means false.
      */
     rgb?: boolean;
     color?: Color;
 }
+/**
+ * Physical position and size of an input, in key units (1 = one standard key). Fractions are allowed (e.g. x: 5.5 leaves a gap before a column of encoders). Coordinates are in the device's canonical orientation, defined by the daemon's device catalog: the origin is the top-left corner and y grows downwards. This is a coordinate system, not how the user has the device on the desk (that is Device.rotation). The shape is not modeled: clients derive it from Input.kind (key = rectangle, encoder = circle). Clients can draw a device only when every one of its inputs has a layout; otherwise they fall back to a view without positions (e.g. a list). Prior art: the {x, y, w, h} key model of QMK/VIA info.json.
+ */
+export interface InputLayout {
+    /**
+     * Horizontal position of the input's top-left corner, in key units.
+     */
+    x: number;
+    /**
+     * Vertical position of the input's top-left corner, in key units. Grows downwards.
+     */
+    y: number;
+    /**
+     * Width in key units. Absent means 1.
+     */
+    w?: number;
+    /**
+     * Height in key units. Absent means 1.
+     */
+    h?: number;
+}

package/dist/methods/set_auto_switch.d.ts

@@ -4,7 +4,7 @@
  * and run json-schema-to-typescript to regenerate this file.
  */
 /**
- * Replaces the entire auto-switch configuration in one shot (bulk set, not per-rule CRUD): the master toggle and the full rule set. The result echoes the persisted state.
+ * Replaces the entire auto-switch configuration in one shot (bulk set, not per-rule CRUD): the master toggle and the full rule set. The result echoes the persisted state. The daemon rejects the whole request with error code PROFILE_NOT_FOUND if any rule's profile_id does not exist; nothing is persisted in that case.
  */
 export interface MethodSetAutoSwitch {
     params: {
@@ -37,7 +37,7 @@ export interface AutoSwitchRule {
      */
     app: string;
     /**
-     * Identifier of the profile to activate when this app is frontmost.
+     * Identifier of the profile to activate when this app is frontmost. Must reference an existing profile: set_auto_switch rejects unknown ids with PROFILE_NOT_FOUND, and delete_profile removes the rules pointing to the deleted profile.
      */
     profile_id: string;
 }

package/dist/methods/set_device_rotation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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;
+/**
+ * Clockwise rotation, in degrees, applied to the canonical orientation of a device's layout so clients show it the way the user has the device on the desk. Presentation only: bindings and colors stay tied to the physical input (input_id) and do not change when the device is rotated. It is a per-device preference, not a per-profile one: switching profiles does not change it. Set through set_device_rotation and exposed in Device.rotation, where absent means 0.
+ */
+export type DeviceRotation = 0 | 90 | 180 | 270;
+/**
+ * Persists how the user has a device rotated on the desk, so clients draw its layout in that orientation. The rotation is stored per device (by device_id), not per profile: switching profiles does not change it. list_devices exposes it in Device.rotation. Presentation only: bindings and colors stay tied to input_id and are not touched. The daemon rejects unknown device_ids; error codes are defined by the daemon.
+ */
+export interface MethodSetDeviceRotation {
+    params: {
+        device_id: DeviceID;
+        rotation: DeviceRotation;
+    };
+    /**
+     * Empty acknowledgement object.
+     */
+    result: {};
+}

package/dist/methods/set_device_rotation.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdg-keyforge/protocol",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TypeScript types for the KeyForge WebSocket protocol, generated from the canonical JSON Schema contracts.",
   "keywords": ["keyforge", "protocol", "types", "json-schema", "websocket"],
   "license": "Apache-2.0",

package/src/common.ts

@@ -37,6 +37,13 @@ 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;
+/**
+ * Clockwise rotation, in degrees, applied to the canonical orientation of a device's layout so clients show it the way the user has the device on the desk. Presentation only: bindings and colors stay tied to the physical input (input_id) and do not change when the device is rotated. It is a per-device preference, not a per-profile one: switching profiles does not change it. Set through set_device_rotation and exposed in Device.rotation, where absent means 0.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "DeviceRotation".
+ */
+export type DeviceRotation = 0 | 90 | 180 | 270;
 /**
  * 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.
  *
@@ -237,15 +244,40 @@ export interface Input {
   id: string;
   kind: InputKind;
   /**
-   * Human-friendly label for the input (e.g. 'Key 1', 'Encoder'). Optional; clients fall back to id.
+   * Fixed name of the input (e.g. 'Enter', 'Play') that clients show as-is in any orientation. When absent, clients name the input by position: they number inputs per kind in reading order of the current view, sorting by each input's top-left corner after applying Device.rotation (y first, then x), so 'Key 1' is always the top-left key as the device sits on the desk. If the device has no complete layout, they number inputs per kind in the order list_devices returns them. Catalogs should not send positional labels like 'Key 1': they would be wrong once the device is rotated.
    */
   label?: string;
+  layout?: InputLayout;
   /**
    * Whether the input has an RGB LED the daemon can drive through set_input_color. Absent means false.
    */
   rgb?: boolean;
   color?: Color1;
 }
+/**
+ * Physical position and size of an input, in key units (1 = one standard key). Fractions are allowed (e.g. x: 5.5 leaves a gap before a column of encoders). Coordinates are in the device's canonical orientation, defined by the daemon's device catalog: the origin is the top-left corner and y grows downwards. This is a coordinate system, not how the user has the device on the desk (that is Device.rotation). The shape is not modeled: clients derive it from Input.kind (key = rectangle, encoder = circle). Clients can draw a device only when every one of its inputs has a layout; otherwise they fall back to a view without positions (e.g. a list). Prior art: the {x, y, w, h} key model of QMK/VIA info.json.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "InputLayout".
+ */
+export interface InputLayout {
+  /**
+   * Horizontal position of the input's top-left corner, in key units.
+   */
+  x: number;
+  /**
+   * Vertical position of the input's top-left corner, in key units. Grows downwards.
+   */
+  y: number;
+  /**
+   * Width in key units. Absent means 1.
+   */
+  w?: number;
+  /**
+   * Height in key units. Absent means 1.
+   */
+  h?: number;
+}
 /**
  * A HID device known to the daemon. Returned by list_devices.
  *
@@ -282,6 +314,7 @@ export interface Device {
    * Inputs (keys/encoders) the daemon knows this device exposes. Empty for unrecognized devices the daemon can't map.
    */
   inputs: Input[];
+  rotation?: DeviceRotation;
 }
 /**
  * Maps a foreground application to the profile that should become active while that app is frontmost. When the frontmost app matches no rule, the active profile is left unchanged (sticky behavior); there is no fallback profile.
@@ -295,7 +328,7 @@ export interface AutoSwitchRule {
    */
   app: string;
   /**
-   * Identifier of the profile to activate when this app is frontmost.
+   * Identifier of the profile to activate when this app is frontmost. Must reference an existing profile: set_auto_switch rejects unknown ids with PROFILE_NOT_FOUND, and delete_profile removes the rules pointing to the deleted profile.
    */
   profile_id: string;
 }

package/src/index.ts

@@ -21,6 +21,7 @@ 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 { MethodSetDeviceRotation } from './methods/set_device_rotation.js';
 export type { MethodSetInputColor } from './methods/set_input_color.js';
 export type { MethodUninstallPlugin } from './methods/uninstall_plugin.js';
 

package/src/methods/delete_profile.ts

@@ -6,7 +6,7 @@
  */
 
 /**
- * Deletes a profile. The daemon never deletes the last remaining profile. Deleting the active profile reassigns the active one, so the resulting active profile id is always returned.
+ * Deletes a profile. The daemon never deletes the last remaining profile. Deleting the active profile reassigns the active one, so the resulting active profile id is always returned. Auto-switch rules whose profile_id points to the deleted profile are deleted with it, so the stored rule set never references a missing profile.
  */
 export interface MethodDeleteProfile {
   params: {

package/src/methods/get_auto_switch.ts

@@ -33,7 +33,7 @@ export interface AutoSwitchRule {
    */
   app: string;
   /**
-   * Identifier of the profile to activate when this app is frontmost.
+   * Identifier of the profile to activate when this app is frontmost. Must reference an existing profile: set_auto_switch rejects unknown ids with PROFILE_NOT_FOUND, and delete_profile removes the rules pointing to the deleted profile.
    */
   profile_id: string;
 }

package/src/methods/list_devices.ts

@@ -17,6 +17,10 @@ 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;
+/**
+ * Clockwise rotation, in degrees, applied to the canonical orientation of a device's layout so clients show it the way the user has the device on the desk. Presentation only: bindings and colors stay tied to the physical input (input_id) and do not change when the device is rotated. It is a per-device preference, not a per-profile one: switching profiles does not change it. Set through set_device_rotation and exposed in Device.rotation, where absent means 0.
+ */
+export type DeviceRotation = 0 | 90 | 180 | 270;
 
 /**
  * Returns the HID devices currently known to the daemon. No filters in v1; clients filter client-side if needed.
@@ -66,6 +70,7 @@ export interface Device {
    * Inputs (keys/encoders) the daemon knows this device exposes. Empty for unrecognized devices the daemon can't map.
    */
   inputs: Input[];
+  rotation?: DeviceRotation;
 }
 /**
  * A single physical input exposed by a device (a key or an encoder).
@@ -77,12 +82,34 @@ export interface Input {
   id: string;
   kind: InputKind;
   /**
-   * Human-friendly label for the input (e.g. 'Key 1', 'Encoder'). Optional; clients fall back to id.
+   * Fixed name of the input (e.g. 'Enter', 'Play') that clients show as-is in any orientation. When absent, clients name the input by position: they number inputs per kind in reading order of the current view, sorting by each input's top-left corner after applying Device.rotation (y first, then x), so 'Key 1' is always the top-left key as the device sits on the desk. If the device has no complete layout, they number inputs per kind in the order list_devices returns them. Catalogs should not send positional labels like 'Key 1': they would be wrong once the device is rotated.
    */
   label?: string;
+  layout?: InputLayout;
   /**
    * Whether the input has an RGB LED the daemon can drive through set_input_color. Absent means false.
    */
   rgb?: boolean;
   color?: Color;
 }
+/**
+ * Physical position and size of an input, in key units (1 = one standard key). Fractions are allowed (e.g. x: 5.5 leaves a gap before a column of encoders). Coordinates are in the device's canonical orientation, defined by the daemon's device catalog: the origin is the top-left corner and y grows downwards. This is a coordinate system, not how the user has the device on the desk (that is Device.rotation). The shape is not modeled: clients derive it from Input.kind (key = rectangle, encoder = circle). Clients can draw a device only when every one of its inputs has a layout; otherwise they fall back to a view without positions (e.g. a list). Prior art: the {x, y, w, h} key model of QMK/VIA info.json.
+ */
+export interface InputLayout {
+  /**
+   * Horizontal position of the input's top-left corner, in key units.
+   */
+  x: number;
+  /**
+   * Vertical position of the input's top-left corner, in key units. Grows downwards.
+   */
+  y: number;
+  /**
+   * Width in key units. Absent means 1.
+   */
+  w?: number;
+  /**
+   * Height in key units. Absent means 1.
+   */
+  h?: number;
+}

package/src/methods/set_auto_switch.ts

@@ -6,7 +6,7 @@
  */
 
 /**
- * Replaces the entire auto-switch configuration in one shot (bulk set, not per-rule CRUD): the master toggle and the full rule set. The result echoes the persisted state.
+ * Replaces the entire auto-switch configuration in one shot (bulk set, not per-rule CRUD): the master toggle and the full rule set. The result echoes the persisted state. The daemon rejects the whole request with error code PROFILE_NOT_FOUND if any rule's profile_id does not exist; nothing is persisted in that case.
  */
 export interface MethodSetAutoSwitch {
   params: {
@@ -39,7 +39,7 @@ export interface AutoSwitchRule {
    */
   app: string;
   /**
-   * Identifier of the profile to activate when this app is frontmost.
+   * Identifier of the profile to activate when this app is frontmost. Must reference an existing profile: set_auto_switch rejects unknown ids with PROFILE_NOT_FOUND, and delete_profile removes the rules pointing to the deleted profile.
    */
   profile_id: string;
 }

package/src/methods/set_device_rotation.ts

@@ -0,0 +1,29 @@
+/* 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;
+/**
+ * Clockwise rotation, in degrees, applied to the canonical orientation of a device's layout so clients show it the way the user has the device on the desk. Presentation only: bindings and colors stay tied to the physical input (input_id) and do not change when the device is rotated. It is a per-device preference, not a per-profile one: switching profiles does not change it. Set through set_device_rotation and exposed in Device.rotation, where absent means 0.
+ */
+export type DeviceRotation = 0 | 90 | 180 | 270;
+
+/**
+ * Persists how the user has a device rotated on the desk, so clients draw its layout in that orientation. The rotation is stored per device (by device_id), not per profile: switching profiles does not change it. list_devices exposes it in Device.rotation. Presentation only: bindings and colors stay tied to input_id and are not touched. The daemon rejects unknown device_ids; error codes are defined by the daemon.
+ */
+export interface MethodSetDeviceRotation {
+  params: {
+    device_id: DeviceID;
+    rotation: DeviceRotation;
+  };
+  /**
+   * Empty acknowledgement object.
+   */
+  result: {};
+}