@jdg-keyforge/protocol 0.6.0

package/src/common.ts

@@ -0,0 +1,174 @@
+/* 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>].
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "DeviceID".
+ */
+export type DeviceID = string;
+/**
+ * Kind of physical input.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "InputKind".
+ */
+export type InputKind = "key" | "encoder";
+/**
+ * What happened on the input.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "InputAction".
+ */
+export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+
+/**
+ * Shared type definitions referenced by message schemas.
+ */
+export interface CommonTypes {
+  [k: string]: unknown;
+}
+/**
+ * A single hardware event coming from a HID device.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "InputEvent".
+ */
+export interface InputEvent {
+  device_id: DeviceID;
+  kind: InputKind;
+  /**
+   * Logical identifier of the input within the device (e.g. 'key_0x04', 'encoder_0'). Matches Device.inputs[].id.
+   */
+  input_id: string;
+  action: InputAction;
+  /**
+   * Unix epoch in milliseconds when the event was captured by the daemon.
+   */
+  timestamp_ms: number;
+}
+/**
+ * An executable action bound to an input.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "Action".
+ */
+export interface Action {
+  /**
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   */
+  type: string;
+  /**
+   * Action-specific parameters. Schema depends on 'type'.
+   */
+  params?: {
+    [k: string]: unknown;
+  };
+}
+/**
+ * Maps an input on a specific device to an action.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "Binding".
+ */
+export interface Binding {
+  device_id: DeviceID;
+  input_id: string;
+  trigger: InputAction;
+  action: Action;
+}
+/**
+ * A named set of bindings. The daemon keeps exactly one profile active at a time; switching profiles swaps the active binding set.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "Profile".
+ */
+export interface Profile {
+  /**
+   * Stable server-generated identifier for the profile.
+   */
+  id: string;
+  /**
+   * Human-friendly profile name.
+   */
+  name: string;
+  /**
+   * Bindings that belong to this profile.
+   */
+  bindings: Binding[];
+}
+/**
+ * A single physical input exposed by a device (a key or an encoder).
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "Input".
+ */
+export interface Input {
+  /**
+   * Logical identifier of the input within the device (e.g. 'key_0x04', 'encoder_0'). Matches InputEvent.input_id and Binding.input_id.
+   */
+  id: string;
+  kind: InputKind;
+  /**
+   * Human-friendly label for the input (e.g. 'Key 1', 'Encoder'). Optional; clients fall back to id.
+   */
+  label?: string;
+}
+/**
+ * A HID device known to the daemon. Returned by list_devices.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "Device".
+ */
+export interface Device {
+  id: DeviceID;
+  /**
+   * USB Vendor ID as a 4-digit hexadecimal string (lowercase or uppercase, no '0x' prefix).
+   */
+  vendor_id: string;
+  /**
+   * USB Product ID as a 4-digit hexadecimal string (lowercase or uppercase, no '0x' prefix).
+   */
+  product_id: string;
+  /**
+   * Manufacturer string from the HID descriptor. May be missing on cheap/clone devices.
+   */
+  manufacturer?: string;
+  /**
+   * Product name string from the HID descriptor.
+   */
+  product?: string;
+  /**
+   * Serial number string from the HID descriptor. Not all HID devices expose one.
+   */
+  serial_number?: string;
+  /**
+   * OS-opaque path used by the HID library to (re)open the device. Format varies per OS; clients should treat it as an opaque token.
+   */
+  path: string;
+  /**
+   * Inputs (keys/encoders) the daemon knows this device exposes. Empty for unrecognized devices the daemon can't map.
+   */
+  inputs: Input[];
+}
+/**
+ * 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.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "AutoSwitchRule".
+ */
+export interface AutoSwitchRule {
+  /**
+   * OS-native application identifier: bundle id on macOS, executable name on Linux/Windows. Opaque string, not portable across OSes; the daemon matches it verbatim against the frontmost app.
+   */
+  app: string;
+  /**
+   * Identifier of the profile to activate when this app is frontmost.
+   */
+  profile_id: string;
+}

package/src/envelope.ts

@@ -0,0 +1,94 @@
+/* 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.
+ */
+
+/**
+ * Wire-level frame exchanged over the WebSocket transport. Every frame is one of three shapes discriminated by the 'type' field. Inner 'params'/'data'/'error' are intentionally generic here; method- and event-specific schemas refine them in a second validation pass.
+ */
+export type Envelope = Request | Response | Event;
+/**
+ * Server -> client. Discriminated by 'ok'.
+ */
+export type Response = ResponseOk | ResponseErr;
+
+/**
+ * Client -> server. Expects a correlated Response with the same id.
+ */
+export interface Request {
+  type: "request";
+  /**
+   * Client-generated correlation id (UUID v4 or nanoid).
+   */
+  id: string;
+  /**
+   * Method name in snake_case.
+   */
+  method: string;
+  /**
+   * Method-specific arguments. Refined by the schema in schemas/methods/<method>.schema.json.
+   */
+  params: {
+    [k: string]: unknown;
+  };
+}
+export interface ResponseOk {
+  type: "response";
+  /**
+   * Echo of the original Request.id.
+   */
+  id: string;
+  ok: true;
+  /**
+   * Method-specific result. Refined by the schema in schemas/methods/<method>.schema.json.
+   */
+  data: {
+    [k: string]: unknown;
+  };
+}
+export interface ResponseErr {
+  type: "response";
+  /**
+   * Echo of the original Request.id.
+   */
+  id: string;
+  ok: false;
+  error: Error;
+}
+/**
+ * Failure payload returned in a Response with ok=false.
+ */
+export interface Error {
+  /**
+   * Stable, machine-readable error code in SCREAMING_SNAKE_CASE.
+   */
+  code: string;
+  /**
+   * Human-readable error message. Free form, may be localized in future versions.
+   */
+  message: string;
+  /**
+   * Optional structured context for debugging.
+   */
+  details?: {
+    [k: string]: unknown;
+  };
+}
+/**
+ * Server -> client, no correlation. Stream of hardware events or daemon notifications.
+ */
+export interface Event {
+  type: "event";
+  /**
+   * Event name in snake_case.
+   */
+  name: string;
+  /**
+   * Event-specific payload. Refined by the schema in schemas/events/<name>.schema.json.
+   */
+  data: {
+    [k: string]: unknown;
+  };
+}

package/src/events/active_profile_changed.ts

@@ -0,0 +1,18 @@
+/* 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.
+ */
+
+/**
+ * Pushed by the daemon whenever the active profile changes on the server's own initiative (today: auto-switch by foreground app). Lets clients stay in sync without polling. Not emitted in response to a client's set_active_profile request, which already returns the new id.
+ */
+export interface EventActiveProfileChanged {
+  data: {
+    /**
+     * Identifier of the now-active profile.
+     */
+    active_profile_id: string;
+  };
+}

package/src/events/input.ts

@@ -0,0 +1,42 @@
+/* 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;
+/**
+ * Kind of physical input.
+ */
+export type InputKind = "key" | "encoder";
+/**
+ * What happened on the input.
+ */
+export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+
+/**
+ * Pushed by the daemon for every hardware event captured on a connected HID device. High-frequency: encoders may emit many per second.
+ */
+export interface EventInput {
+  data: InputEvent;
+}
+/**
+ * A single hardware event coming from a HID device.
+ */
+export interface InputEvent {
+  device_id: DeviceID;
+  kind: InputKind;
+  /**
+   * Logical identifier of the input within the device (e.g. 'key_0x04', 'encoder_0'). Matches Device.inputs[].id.
+   */
+  input_id: string;
+  action: InputAction;
+  /**
+   * Unix epoch in milliseconds when the event was captured by the daemon.
+   */
+  timestamp_ms: number;
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+// AUTO-GENERATED by 'make generate-ts'. DO NOT EDIT BY HAND.
+
+export * from './common.js';
+export * from './envelope.js';
+
+export type { MethodCreateProfile } from './methods/create_profile.js';
+export type { MethodDeleteProfile } from './methods/delete_profile.js';
+export type { MethodDuplicateProfile } from './methods/duplicate_profile.js';
+export type { MethodGetAutoSwitch } from './methods/get_auto_switch.js';
+export type { MethodHello } from './methods/hello.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 { 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 { EventActiveProfileChanged } from './events/active_profile_changed.js';
+export type { EventInput } from './events/input.js';

package/src/methods/create_profile.ts

@@ -0,0 +1,71 @@
+/* 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;
+/**
+ * What happened on the input.
+ */
+export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+
+/**
+ * Creates a new profile. The server generates the id and returns the profile with an empty bindings array.
+ */
+export interface MethodCreateProfile {
+  params: {
+    /**
+     * Human-friendly name for the new profile.
+     */
+    name: string;
+  };
+  result: {
+    profile: Profile;
+  };
+}
+/**
+ * A named set of bindings. The daemon keeps exactly one profile active at a time; switching profiles swaps the active binding set.
+ */
+export interface Profile {
+  /**
+   * Stable server-generated identifier for the profile.
+   */
+  id: string;
+  /**
+   * Human-friendly profile name.
+   */
+  name: string;
+  /**
+   * Bindings that belong to this profile.
+   */
+  bindings: Binding[];
+}
+/**
+ * Maps an input on a specific device to an action.
+ */
+export interface Binding {
+  device_id: DeviceID;
+  input_id: string;
+  trigger: InputAction;
+  action: Action;
+}
+/**
+ * An executable action bound to an input.
+ */
+export interface Action {
+  /**
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   */
+  type: string;
+  /**
+   * Action-specific parameters. Schema depends on 'type'.
+   */
+  params?: {
+    [k: string]: unknown;
+  };
+}

package/src/methods/delete_profile.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.
+ */
+
+/**
+ * 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.
+ */
+export interface MethodDeleteProfile {
+  params: {
+    /**
+     * Identifier of the profile to delete.
+     */
+    id: string;
+  };
+  result: {
+    /**
+     * Identifier of the profile that is active after the deletion. Unchanged unless the deleted profile was the active one.
+     */
+    active_profile_id: string;
+  };
+}

package/src/methods/duplicate_profile.ts

@@ -0,0 +1,75 @@
+/* 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;
+/**
+ * What happened on the input.
+ */
+export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+
+/**
+ * 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.
+ */
+export interface MethodDuplicateProfile {
+  params: {
+    /**
+     * Identifier of the source profile to copy bindings from.
+     */
+    id: string;
+    /**
+     * Human-friendly name for the new (duplicated) profile.
+     */
+    name: string;
+  };
+  result: {
+    profile: Profile;
+  };
+}
+/**
+ * A named set of bindings. The daemon keeps exactly one profile active at a time; switching profiles swaps the active binding set.
+ */
+export interface Profile {
+  /**
+   * Stable server-generated identifier for the profile.
+   */
+  id: string;
+  /**
+   * Human-friendly profile name.
+   */
+  name: string;
+  /**
+   * Bindings that belong to this profile.
+   */
+  bindings: Binding[];
+}
+/**
+ * Maps an input on a specific device to an action.
+ */
+export interface Binding {
+  device_id: DeviceID;
+  input_id: string;
+  trigger: InputAction;
+  action: Action;
+}
+/**
+ * An executable action bound to an input.
+ */
+export interface Action {
+  /**
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   */
+  type: string;
+  /**
+   * Action-specific parameters. Schema depends on 'type'.
+   */
+  params?: {
+    [k: string]: unknown;
+  };
+}

package/src/methods/get_auto_switch.ts

@@ -0,0 +1,39 @@
+/* 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.
+ */
+
+/**
+ * Returns the current auto-switch configuration: the master toggle and the full set of app-to-profile rules. The daemon uses these to switch the active profile based on the foreground application.
+ */
+export interface MethodGetAutoSwitch {
+  /**
+   * No parameters in v1.
+   */
+  params: {};
+  result: {
+    /**
+     * Master toggle. When false, the daemon ignores the rules and never auto-switches.
+     */
+    enabled: boolean;
+    /**
+     * App-to-profile rules currently configured.
+     */
+    rules: AutoSwitchRule[];
+  };
+}
+/**
+ * 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.
+ */
+export interface AutoSwitchRule {
+  /**
+   * OS-native application identifier: bundle id on macOS, executable name on Linux/Windows. Opaque string, not portable across OSes; the daemon matches it verbatim against the frontmost app.
+   */
+  app: string;
+  /**
+   * Identifier of the profile to activate when this app is frontmost.
+   */
+  profile_id: string;
+}

package/src/methods/hello.ts

@@ -0,0 +1,42 @@
+/* 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.
+ */
+
+/**
+ * Mandatory first request after a WebSocket connection is established. The client declares the protocol_version it speaks. The server either accepts (Response.ok=true with its own identification) or closes the connection with an UNSUPPORTED_PROTOCOL_VERSION error. After a successful hello no further version negotiation happens; the contract is fixed for the session.
+ */
+export interface MethodHello {
+  params: {
+    /**
+     * Major version of the protocol the client implements. Currently '1'.
+     */
+    protocol_version: "1";
+    client: PeerInfo;
+  };
+  result: {
+    /**
+     * Protocol version the server agrees to speak for this session.
+     */
+    protocol_version: "1";
+    server: PeerInfo;
+  };
+}
+/**
+ * Self-identification of a protocol peer (client or server).
+ *
+ * This interface was referenced by `MethodHello`'s JSON-Schema
+ * via the `definition` "PeerInfo".
+ */
+export interface PeerInfo {
+  /**
+   * Stable identifier of the peer implementation.
+   */
+  name: string;
+  /**
+   * Semver version of the peer build.
+   */
+  version: string;
+}

package/src/methods/list_actions.ts

@@ -0,0 +1,71 @@
+/* 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.
+ */
+
+/**
+ * Returns the catalog of actions the daemon can bind to inputs, including the param shape each action needs so a client can render a config form. No params in v1.
+ */
+export interface MethodListActions {
+  /**
+   * No parameters in v1.
+   */
+  params: {};
+  result: {
+    /**
+     * All actions available to bind. Built-ins plus any registered plugin actions.
+     */
+    actions: ActionDescriptor[];
+  };
+}
+/**
+ * Describes a bindable action type and the params it accepts.
+ *
+ * This interface was referenced by `MethodListActions`'s JSON-Schema
+ * via the `definition` "ActionDescriptor".
+ */
+export interface ActionDescriptor {
+  /**
+   * Action type, as used in Action.type (e.g. 'launch_app').
+   */
+  type: string;
+  /**
+   * Human-friendly action name for the UI.
+   */
+  name: string;
+  /**
+   * Optional longer description of what the action does.
+   */
+  description?: string;
+  /**
+   * Params this action accepts, in display order.
+   */
+  params: ParamSpec[];
+}
+/**
+ * Describes one action parameter so a client can render an input for it.
+ *
+ * This interface was referenced by `MethodListActions`'s JSON-Schema
+ * via the `definition` "ParamSpec".
+ */
+export interface ParamSpec {
+  /**
+   * Param key written into Action.params.
+   */
+  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;
+}