@jdg-keyforge/protocol 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright (c) 2026 Jonathan Daniel Gomez <jonathan.d.gomez98@gmail.com>
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   ---
+
+   Full license text: https://www.apache.org/licenses/LICENSE-2.0.txt

package/README.md

@@ -0,0 +1,69 @@
+# @jdg-keyforge/protocol
+
+> TypeScript types for the [KeyForge](https://github.com/JoniDG/keyforge) WebSocket protocol, generated from the canonical JSON Schema contracts in this repository.
+
+This package contains only type declarations — there is no runtime code. It mirrors the Go submodule published at `github.com/JoniDG/keyforge-protocol/go/protocol`.
+
+## Install
+
+```bash
+npm install @jdg-keyforge/protocol
+```
+
+While the package is unpublished, consumers in the KeyForge workspace can install it directly from the source tree:
+
+```bash
+npm install file:../keyforge-protocol/ts
+```
+
+## Usage
+
+```ts
+import type {
+  Envelope,
+  Request,
+  Response,
+  Event,
+  Device,
+  InputEvent,
+  MethodHello,
+  MethodListDevices,
+  EventInput,
+} from '@jdg-keyforge/protocol';
+```
+
+The root `index` re-exports shared types from [`common`](./src/common.ts) and [`envelope`](./src/envelope.ts) plus the top-level `Method*` / `Event*` types for each method and event. Inner payload shapes (e.g. `MethodListDevices['result']`) are reachable through the parent type.
+
+For schema definitions and the wire-protocol overview, see the [repository root README](../README.md).
+
+## Versioning
+
+This package is versioned independently from the schema's `/v1/` path and from the Go submodule:
+
+| Artifact | Source of truth | Tag |
+|---|---|---|
+| Schema major | `$id` path (`.../v1/...`) | — |
+| Go submodule | [`go/protocol/`](../go/protocol) | `go/vX.Y.Z` |
+| TS package | [`ts/`](.) | `ts/vX.Y.Z` |
+
+A breaking schema change bumps `/v1/` to `/v2/` *and* the major version of both packages. Non-breaking schema additions bump only the minor/patch of each package.
+
+## Local regeneration
+
+The contents of `src/` are auto-generated from the JSON Schemas. To regenerate after editing a schema, run from the repository root:
+
+```bash
+make generate-ts
+```
+
+Then build the package:
+
+```bash
+cd ts && npm install && npm run build
+```
+
+CI fails the build if `git diff --exit-code ts/src/` is dirty — i.e. someone changed a schema without committing the regenerated types.
+
+## License
+
+[Apache 2.0](./LICENSE) — Copyright (c) 2026 Jonathan Daniel Gomez.

package/dist/common.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 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/dist/common.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/envelope.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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/dist/envelope.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/events/active_profile_changed.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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/dist/events/active_profile_changed.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/events/input.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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/dist/events/input.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/index.d.ts

@@ -0,0 +1,17 @@
+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/dist/index.js

@@ -0,0 +1,3 @@
+// AUTO-GENERATED by 'make generate-ts'. DO NOT EDIT BY HAND.
+export * from './common.js';
+export * from './envelope.js';

package/dist/methods/create_profile.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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/dist/methods/create_profile.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/delete_profile.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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/dist/methods/delete_profile.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/duplicate_profile.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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/dist/methods/duplicate_profile.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 {};