@jdg-keyforge/protocol 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ /**
2
+ * This file was automatically generated by json-schema-to-typescript.
3
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
4
+ * and run json-schema-to-typescript to regenerate this file.
5
+ */
6
+ /**
7
+ * Id of the plugin to uninstall.
8
+ */
9
+ export type PluginID = string;
10
+ /**
11
+ * 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.
12
+ */
13
+ export interface MethodUninstallPlugin {
14
+ params: {
15
+ id: PluginID;
16
+ };
17
+ /**
18
+ * Empty acknowledgement object. Reserved for future fields without breaking the schema.
19
+ */
20
+ result: {};
21
+ }
@@ -0,0 +1,7 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * This file was automatically generated by json-schema-to-typescript.
4
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
5
+ * and run json-schema-to-typescript to regenerate this file.
6
+ */
7
+ export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jdg-keyforge/protocol",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "description": "TypeScript types for the KeyForge WebSocket protocol, generated from the canonical JSON Schema contracts.",
5
5
  "keywords": ["keyforge", "protocol", "types", "json-schema", "websocket"],
6
6
  "license": "Apache-2.0",
package/src/common.ts CHANGED
@@ -26,6 +26,21 @@ export type InputKind = "key" | "encoder";
26
26
  * via the `definition` "InputAction".
27
27
  */
28
28
  export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
29
+ /**
30
+ * 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.
31
+ *
32
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
33
+ * via the `definition` "PluginID".
34
+ */
35
+ export type PluginID = string;
36
+ /**
37
+ * Id of the plugin being launched (its manifest id).
38
+ */
39
+ export type PluginID1 = string;
40
+ /**
41
+ * Globally unique reverse-DNS plugin id; install folder name and <plugin_id> in Action.type.
42
+ */
43
+ export type PluginID2 = string;
29
44
 
30
45
  /**
31
46
  * Shared type definitions referenced by message schemas.
@@ -271,6 +286,40 @@ export interface ParamSpec {
271
286
  */
272
287
  placeholder?: string;
273
288
  }
289
+ /**
290
+ * Connection info the daemon hands to a plugin process it spawns, serialized as JSON in the KEYFORGE_PLUGIN_INFO environment variable (an env var rather than CLI args, so the token is not visible in the process list). The plugin connects to ws_url, sends hello with client.name set to plugin_id, and must exit when that connection closes.
291
+ *
292
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
293
+ * via the `definition` "PluginLaunchInfo".
294
+ */
295
+ export interface PluginLaunchInfo {
296
+ plugin_id: PluginID1;
297
+ /**
298
+ * WebSocket URL to connect to, including the per-plugin auth token as a query param. Treat it as a secret: the token identifies the plugin to the daemon and is distinct from the GUI's session token.
299
+ */
300
+ ws_url: string;
301
+ /**
302
+ * Protocol major version the daemon speaks. The plugin sends it back in hello. Currently '1'.
303
+ */
304
+ protocol_version: "1";
305
+ }
306
+ /**
307
+ * A plugin installed in the daemon, with the state of its process.
308
+ *
309
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
310
+ * via the `definition` "InstalledPlugin".
311
+ */
312
+ export interface InstalledPlugin {
313
+ manifest: PluginManifest;
314
+ /**
315
+ * 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').
316
+ */
317
+ status: "starting" | "running" | "stopped" | "error";
318
+ /**
319
+ * Human-readable reason why the plugin failed. The daemon sets it only when status is 'error' (not enforced by the schema).
320
+ */
321
+ error?: string;
322
+ }
274
323
  /**
275
324
  * 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.
276
325
  *
@@ -282,10 +331,7 @@ export interface PluginManifest {
282
331
  * Manifest format version. Currently 1; bumped if the manifest shape changes.
283
332
  */
284
333
  manifest_version: 1;
285
- /**
286
- * 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.
287
- */
288
- id: string;
334
+ id: PluginID2;
289
335
  /**
290
336
  * Human-friendly plugin name for the UI.
291
337
  */
@@ -0,0 +1,63 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * This file was automatically generated by json-schema-to-typescript.
4
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
5
+ * and run json-schema-to-typescript to regenerate this file.
6
+ */
7
+
8
+ /**
9
+ * Stable identifier for a HID device. Format: VID_<hex>_PID_<hex>[_<serial>].
10
+ */
11
+ export type DeviceID = string;
12
+ /**
13
+ * Kind of physical input.
14
+ */
15
+ export type InputKind = "key" | "encoder";
16
+ /**
17
+ * What happened on the input.
18
+ */
19
+ export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
20
+
21
+ /**
22
+ * Sent by the daemon to a single plugin connection (never broadcast) when a binding or macro step whose action is 'plugin.<plugin_id>.<action_id>' fires for that plugin. Fire-and-forget: the daemon does not wait for the plugin, so a failing plugin action cannot stop a macro it is part of.
23
+ */
24
+ export interface EventActionInvoked {
25
+ data: {
26
+ /**
27
+ * Opaque id of the binding instance that fired: unique per binding and per macro step, and stable for as long as that binding exists (also across daemon restarts). Lets a plugin keep per-instance state, e.g. a toggle bound to two keys. Plugins must not parse it.
28
+ */
29
+ context: string;
30
+ /**
31
+ * The plugin action to run.
32
+ */
33
+ action: {
34
+ /**
35
+ * Action id as declared in the plugin manifest (PluginAction.id), without the 'plugin.<plugin_id>.' prefix.
36
+ */
37
+ id: string;
38
+ /**
39
+ * Action.params from the binding, as configured by the user. Always present: {} when the binding has no params.
40
+ */
41
+ params: {
42
+ [k: string]: unknown;
43
+ };
44
+ };
45
+ input?: InputEvent;
46
+ };
47
+ }
48
+ /**
49
+ * Hardware event that fired the binding (e.g. lets a plugin tell rotate_cw from rotate_ccw). Absent when the action was not fired by hardware (e.g. a test run from the GUI).
50
+ */
51
+ export interface InputEvent {
52
+ device_id: DeviceID;
53
+ kind: InputKind;
54
+ /**
55
+ * Logical identifier of the input within the device (e.g. 'key_0x04', 'encoder_0'). Matches Device.inputs[].id.
56
+ */
57
+ input_id: string;
58
+ action: InputAction;
59
+ /**
60
+ * Unix epoch in milliseconds when the event was captured by the daemon.
61
+ */
62
+ timestamp_ms: number;
63
+ }
package/src/index.ts CHANGED
@@ -10,14 +10,19 @@ export type { MethodExportProfile } from './methods/export_profile.js';
10
10
  export type { MethodGetAutoSwitch } from './methods/get_auto_switch.js';
11
11
  export type { MethodHello } from './methods/hello.js';
12
12
  export type { MethodImportProfile } from './methods/import_profile.js';
13
+ export type { MethodInspectPlugin } from './methods/inspect_plugin.js';
14
+ export type { MethodInstallPlugin } from './methods/install_plugin.js';
13
15
  export type { MethodListActions } from './methods/list_actions.js';
14
16
  export type { MethodListBindings } from './methods/list_bindings.js';
15
17
  export type { MethodListDevices } from './methods/list_devices.js';
18
+ export type { MethodListPlugins } from './methods/list_plugins.js';
16
19
  export type { MethodListProfiles } from './methods/list_profiles.js';
17
20
  export type { MethodRenameProfile } from './methods/rename_profile.js';
18
21
  export type { MethodSetActiveProfile } from './methods/set_active_profile.js';
19
22
  export type { MethodSetAutoSwitch } from './methods/set_auto_switch.js';
20
23
  export type { MethodSetBinding } from './methods/set_binding.js';
24
+ export type { MethodUninstallPlugin } from './methods/uninstall_plugin.js';
21
25
 
26
+ export type { EventActionInvoked } from './events/action_invoked.js';
22
27
  export type { EventActiveProfileChanged } from './events/active_profile_changed.js';
23
28
  export type { EventInput } from './events/input.js';
@@ -32,7 +32,7 @@ export interface MethodHello {
32
32
  */
33
33
  export interface PeerInfo {
34
34
  /**
35
- * Stable identifier of the peer implementation.
35
+ * Stable identifier of the peer implementation. A plugin must send its PluginID here; the daemon checks it against the plugin its auth token belongs to.
36
36
  */
37
37
  name: string;
38
38
  /**
@@ -0,0 +1,152 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * This file was automatically generated by json-schema-to-typescript.
4
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
5
+ * and run json-schema-to-typescript to regenerate this file.
6
+ */
7
+
8
+ /**
9
+ * Globally unique reverse-DNS plugin id; install folder name and <plugin_id> in Action.type.
10
+ */
11
+ export type PluginID = string;
12
+ /**
13
+ * Kind of physical input.
14
+ */
15
+ export type InputKind = "key" | "encoder";
16
+
17
+ /**
18
+ * 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.
19
+ */
20
+ export interface MethodInspectPlugin {
21
+ params: {
22
+ /**
23
+ * Filesystem path on the daemon host of the '.keyforgeplugin' package.
24
+ */
25
+ path: string;
26
+ };
27
+ result: {
28
+ manifest: PluginManifest;
29
+ /**
30
+ * Version of the plugin with the same id that is currently installed, if any. Installing the package would replace it.
31
+ */
32
+ installed_version?: string;
33
+ };
34
+ }
35
+ /**
36
+ * 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.
37
+ */
38
+ export interface PluginManifest {
39
+ /**
40
+ * Manifest format version. Currently 1; bumped if the manifest shape changes.
41
+ */
42
+ manifest_version: 1;
43
+ id: PluginID;
44
+ /**
45
+ * Human-friendly plugin name for the UI.
46
+ */
47
+ name: string;
48
+ /**
49
+ * Plugin version (SemVer 2.0).
50
+ */
51
+ version: string;
52
+ /**
53
+ * Major version of the protocol the plugin speaks. Lets the daemon reject an incompatible plugin before spawning it. Currently '1'.
54
+ */
55
+ protocol_version: "1";
56
+ /**
57
+ * Plugin author, shown in the UI.
58
+ */
59
+ author?: string;
60
+ /**
61
+ * Short description of what the plugin does.
62
+ */
63
+ description?: string;
64
+ /**
65
+ * URL of the plugin homepage or source repository.
66
+ */
67
+ homepage?: string;
68
+ /**
69
+ * Category the UI groups the plugin's actions under (e.g. 'Audio', 'Streaming').
70
+ */
71
+ category?: string;
72
+ /**
73
+ * Path to the plugin icon, relative to the plugin root. No leading '/', no '\' and no ':'.
74
+ */
75
+ icon?: string;
76
+ /**
77
+ * Command the daemon runs to start the plugin, per OS (keys match Go's GOOS). The plugin supports exactly the OSes listed here.
78
+ */
79
+ entrypoint: {
80
+ darwin?: PluginCommand;
81
+ linux?: PluginCommand;
82
+ windows?: PluginCommand;
83
+ };
84
+ /**
85
+ * Actions the plugin exposes. Each becomes bindable as 'plugin.<id>.<action id>'.
86
+ *
87
+ * @minItems 1
88
+ */
89
+ actions: [PluginAction, ...PluginAction[]];
90
+ }
91
+ /**
92
+ * Executable plus arguments used to start a plugin process.
93
+ */
94
+ export interface PluginCommand {
95
+ /**
96
+ * 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.
97
+ */
98
+ path: string;
99
+ /**
100
+ * Arguments passed to the executable.
101
+ */
102
+ args?: string[];
103
+ }
104
+ /**
105
+ * An action a plugin exposes, declared in its manifest.
106
+ */
107
+ export interface PluginAction {
108
+ /**
109
+ * Action identifier, unique within the plugin. snake_case, no dots.
110
+ */
111
+ id: string;
112
+ /**
113
+ * Human-friendly action name for the UI.
114
+ */
115
+ name: string;
116
+ /**
117
+ * Optional longer description of what the action does.
118
+ */
119
+ description?: string;
120
+ /**
121
+ * Input kinds the action can be bound to. Omitted means any kind.
122
+ *
123
+ * @minItems 1
124
+ */
125
+ inputs?: [InputKind, ...InputKind[]];
126
+ /**
127
+ * Params this action accepts, in display order.
128
+ */
129
+ params: ParamSpec[];
130
+ }
131
+ /**
132
+ * Describes one action parameter so a client can render an input for it.
133
+ */
134
+ export interface ParamSpec {
135
+ /**
136
+ * Param key written into Action.params. Unique within the action.
137
+ */
138
+ name: string;
139
+ /**
140
+ * Human-friendly field label.
141
+ */
142
+ label: string;
143
+ /**
144
+ * Param value type. Only 'string' in v1.
145
+ */
146
+ type: "string";
147
+ required: boolean;
148
+ /**
149
+ * Optional placeholder/example shown in the input.
150
+ */
151
+ placeholder?: string;
152
+ }
@@ -0,0 +1,166 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * This file was automatically generated by json-schema-to-typescript.
4
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
5
+ * and run json-schema-to-typescript to regenerate this file.
6
+ */
7
+
8
+ /**
9
+ * Globally unique reverse-DNS plugin id; install folder name and <plugin_id> in Action.type.
10
+ */
11
+ export type PluginID = string;
12
+ /**
13
+ * Kind of physical input.
14
+ */
15
+ export type InputKind = "key" | "encoder";
16
+
17
+ /**
18
+ * 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.
19
+ */
20
+ export interface MethodInstallPlugin {
21
+ params: {
22
+ /**
23
+ * Filesystem path on the daemon host of the '.keyforgeplugin' package.
24
+ */
25
+ path: string;
26
+ };
27
+ result: {
28
+ plugin: InstalledPlugin;
29
+ /**
30
+ * Version that was replaced, present only when the install was an upgrade.
31
+ */
32
+ previous_version?: string;
33
+ };
34
+ }
35
+ /**
36
+ * A plugin installed in the daemon, with the state of its process.
37
+ */
38
+ export interface InstalledPlugin {
39
+ manifest: PluginManifest;
40
+ /**
41
+ * 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').
42
+ */
43
+ status: "starting" | "running" | "stopped" | "error";
44
+ /**
45
+ * Human-readable reason why the plugin failed. The daemon sets it only when status is 'error' (not enforced by the schema).
46
+ */
47
+ error?: string;
48
+ }
49
+ /**
50
+ * 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.
51
+ */
52
+ export interface PluginManifest {
53
+ /**
54
+ * Manifest format version. Currently 1; bumped if the manifest shape changes.
55
+ */
56
+ manifest_version: 1;
57
+ id: PluginID;
58
+ /**
59
+ * Human-friendly plugin name for the UI.
60
+ */
61
+ name: string;
62
+ /**
63
+ * Plugin version (SemVer 2.0).
64
+ */
65
+ version: string;
66
+ /**
67
+ * Major version of the protocol the plugin speaks. Lets the daemon reject an incompatible plugin before spawning it. Currently '1'.
68
+ */
69
+ protocol_version: "1";
70
+ /**
71
+ * Plugin author, shown in the UI.
72
+ */
73
+ author?: string;
74
+ /**
75
+ * Short description of what the plugin does.
76
+ */
77
+ description?: string;
78
+ /**
79
+ * URL of the plugin homepage or source repository.
80
+ */
81
+ homepage?: string;
82
+ /**
83
+ * Category the UI groups the plugin's actions under (e.g. 'Audio', 'Streaming').
84
+ */
85
+ category?: string;
86
+ /**
87
+ * Path to the plugin icon, relative to the plugin root. No leading '/', no '\' and no ':'.
88
+ */
89
+ icon?: string;
90
+ /**
91
+ * Command the daemon runs to start the plugin, per OS (keys match Go's GOOS). The plugin supports exactly the OSes listed here.
92
+ */
93
+ entrypoint: {
94
+ darwin?: PluginCommand;
95
+ linux?: PluginCommand;
96
+ windows?: PluginCommand;
97
+ };
98
+ /**
99
+ * Actions the plugin exposes. Each becomes bindable as 'plugin.<id>.<action id>'.
100
+ *
101
+ * @minItems 1
102
+ */
103
+ actions: [PluginAction, ...PluginAction[]];
104
+ }
105
+ /**
106
+ * Executable plus arguments used to start a plugin process.
107
+ */
108
+ export interface PluginCommand {
109
+ /**
110
+ * 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.
111
+ */
112
+ path: string;
113
+ /**
114
+ * Arguments passed to the executable.
115
+ */
116
+ args?: string[];
117
+ }
118
+ /**
119
+ * An action a plugin exposes, declared in its manifest.
120
+ */
121
+ export interface PluginAction {
122
+ /**
123
+ * Action identifier, unique within the plugin. snake_case, no dots.
124
+ */
125
+ id: string;
126
+ /**
127
+ * Human-friendly action name for the UI.
128
+ */
129
+ name: string;
130
+ /**
131
+ * Optional longer description of what the action does.
132
+ */
133
+ description?: string;
134
+ /**
135
+ * Input kinds the action can be bound to. Omitted means any kind.
136
+ *
137
+ * @minItems 1
138
+ */
139
+ inputs?: [InputKind, ...InputKind[]];
140
+ /**
141
+ * Params this action accepts, in display order.
142
+ */
143
+ params: ParamSpec[];
144
+ }
145
+ /**
146
+ * Describes one action parameter so a client can render an input for it.
147
+ */
148
+ export interface ParamSpec {
149
+ /**
150
+ * Param key written into Action.params. Unique within the action.
151
+ */
152
+ name: string;
153
+ /**
154
+ * Human-friendly field label.
155
+ */
156
+ label: string;
157
+ /**
158
+ * Param value type. Only 'string' in v1.
159
+ */
160
+ type: "string";
161
+ required: boolean;
162
+ /**
163
+ * Optional placeholder/example shown in the input.
164
+ */
165
+ placeholder?: string;
166
+ }
@@ -0,0 +1,163 @@
1
+ /* eslint-disable */
2
+ /**
3
+ * This file was automatically generated by json-schema-to-typescript.
4
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
5
+ * and run json-schema-to-typescript to regenerate this file.
6
+ */
7
+
8
+ /**
9
+ * Globally unique reverse-DNS plugin id; install folder name and <plugin_id> in Action.type.
10
+ */
11
+ export type PluginID = string;
12
+ /**
13
+ * Kind of physical input.
14
+ */
15
+ export type InputKind = "key" | "encoder";
16
+
17
+ /**
18
+ * Returns every installed plugin with the state of its process. No params in v1.
19
+ */
20
+ export interface MethodListPlugins {
21
+ /**
22
+ * No parameters in v1.
23
+ */
24
+ params: {};
25
+ result: {
26
+ /**
27
+ * Installed plugins.
28
+ */
29
+ plugins: InstalledPlugin[];
30
+ };
31
+ }
32
+ /**
33
+ * A plugin installed in the daemon, with the state of its process.
34
+ */
35
+ export interface InstalledPlugin {
36
+ manifest: PluginManifest;
37
+ /**
38
+ * 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').
39
+ */
40
+ status: "starting" | "running" | "stopped" | "error";
41
+ /**
42
+ * Human-readable reason why the plugin failed. The daemon sets it only when status is 'error' (not enforced by the schema).
43
+ */
44
+ error?: string;
45
+ }
46
+ /**
47
+ * 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.
48
+ */
49
+ export interface PluginManifest {
50
+ /**
51
+ * Manifest format version. Currently 1; bumped if the manifest shape changes.
52
+ */
53
+ manifest_version: 1;
54
+ id: PluginID;
55
+ /**
56
+ * Human-friendly plugin name for the UI.
57
+ */
58
+ name: string;
59
+ /**
60
+ * Plugin version (SemVer 2.0).
61
+ */
62
+ version: string;
63
+ /**
64
+ * Major version of the protocol the plugin speaks. Lets the daemon reject an incompatible plugin before spawning it. Currently '1'.
65
+ */
66
+ protocol_version: "1";
67
+ /**
68
+ * Plugin author, shown in the UI.
69
+ */
70
+ author?: string;
71
+ /**
72
+ * Short description of what the plugin does.
73
+ */
74
+ description?: string;
75
+ /**
76
+ * URL of the plugin homepage or source repository.
77
+ */
78
+ homepage?: string;
79
+ /**
80
+ * Category the UI groups the plugin's actions under (e.g. 'Audio', 'Streaming').
81
+ */
82
+ category?: string;
83
+ /**
84
+ * Path to the plugin icon, relative to the plugin root. No leading '/', no '\' and no ':'.
85
+ */
86
+ icon?: string;
87
+ /**
88
+ * Command the daemon runs to start the plugin, per OS (keys match Go's GOOS). The plugin supports exactly the OSes listed here.
89
+ */
90
+ entrypoint: {
91
+ darwin?: PluginCommand;
92
+ linux?: PluginCommand;
93
+ windows?: PluginCommand;
94
+ };
95
+ /**
96
+ * Actions the plugin exposes. Each becomes bindable as 'plugin.<id>.<action id>'.
97
+ *
98
+ * @minItems 1
99
+ */
100
+ actions: [PluginAction, ...PluginAction[]];
101
+ }
102
+ /**
103
+ * Executable plus arguments used to start a plugin process.
104
+ */
105
+ export interface PluginCommand {
106
+ /**
107
+ * 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.
108
+ */
109
+ path: string;
110
+ /**
111
+ * Arguments passed to the executable.
112
+ */
113
+ args?: string[];
114
+ }
115
+ /**
116
+ * An action a plugin exposes, declared in its manifest.
117
+ */
118
+ export interface PluginAction {
119
+ /**
120
+ * Action identifier, unique within the plugin. snake_case, no dots.
121
+ */
122
+ id: string;
123
+ /**
124
+ * Human-friendly action name for the UI.
125
+ */
126
+ name: string;
127
+ /**
128
+ * Optional longer description of what the action does.
129
+ */
130
+ description?: string;
131
+ /**
132
+ * Input kinds the action can be bound to. Omitted means any kind.
133
+ *
134
+ * @minItems 1
135
+ */
136
+ inputs?: [InputKind, ...InputKind[]];
137
+ /**
138
+ * Params this action accepts, in display order.
139
+ */
140
+ params: ParamSpec[];
141
+ }
142
+ /**
143
+ * Describes one action parameter so a client can render an input for it.
144
+ */
145
+ export interface ParamSpec {
146
+ /**
147
+ * Param key written into Action.params. Unique within the action.
148
+ */
149
+ name: string;
150
+ /**
151
+ * Human-friendly field label.
152
+ */
153
+ label: string;
154
+ /**
155
+ * Param value type. Only 'string' in v1.
156
+ */
157
+ type: "string";
158
+ required: boolean;
159
+ /**
160
+ * Optional placeholder/example shown in the input.
161
+ */
162
+ placeholder?: string;
163
+ }