@jdg-keyforge/protocol 0.8.0 → 0.10.0

package/dist/common.d.ts

@@ -24,6 +24,21 @@ export type InputKind = "key" | "encoder";
  * via the `definition` "InputAction".
  */
 export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+/**
+ * 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.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginID".
+ */
+export type PluginID = string;
+/**
+ * Id of the plugin being launched (its manifest id).
+ */
+export type PluginID1 = string;
+/**
+ * Globally unique reverse-DNS plugin id; install folder name and <plugin_id> in Action.type.
+ */
+export type PluginID2 = string;
 /**
  * Shared type definitions referenced by message schemas.
  */
@@ -57,7 +72,7 @@ export interface InputEvent {
  */
 export interface Action {
     /**
-     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
      */
     type: string;
     /**
@@ -243,3 +258,150 @@ export interface AutoSwitchRule {
      */
     profile_id: string;
 }
+/**
+ * Describes one action parameter so a client can render an input for it.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "ParamSpec".
+ */
+export interface ParamSpec {
+    /**
+     * Param key written into Action.params. Unique within the action.
+     */
+    name: string;
+    /**
+     * Human-friendly field label.
+     */
+    label: string;
+    /**
+     * Param value type. Only 'string' in v1.
+     */
+    type: "string";
+    required: boolean;
+    /**
+     * Optional placeholder/example shown in the input.
+     */
+    placeholder?: string;
+}
+/**
+ * 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.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginLaunchInfo".
+ */
+export interface PluginLaunchInfo {
+    plugin_id: PluginID1;
+    /**
+     * 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.
+     */
+    ws_url: string;
+    /**
+     * Protocol major version the daemon speaks. The plugin sends it back in hello. Currently '1'.
+     */
+    protocol_version: "1";
+}
+/**
+ * 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.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginManifest".
+ */
+export interface PluginManifest {
+    /**
+     * Manifest format version. Currently 1; bumped if the manifest shape changes.
+     */
+    manifest_version: 1;
+    id: PluginID2;
+    /**
+     * Human-friendly plugin name for the UI.
+     */
+    name: string;
+    /**
+     * Plugin version (SemVer 2.0).
+     */
+    version: string;
+    /**
+     * Major version of the protocol the plugin speaks. Lets the daemon reject an incompatible plugin before spawning it. Currently '1'.
+     */
+    protocol_version: "1";
+    /**
+     * Plugin author, shown in the UI.
+     */
+    author?: string;
+    /**
+     * Short description of what the plugin does.
+     */
+    description?: string;
+    /**
+     * URL of the plugin homepage or source repository.
+     */
+    homepage?: string;
+    /**
+     * Category the UI groups the plugin's actions under (e.g. 'Audio', 'Streaming').
+     */
+    category?: string;
+    /**
+     * Path to the plugin icon, relative to the plugin root. No leading '/', no '\' and no ':'.
+     */
+    icon?: string;
+    /**
+     * Command the daemon runs to start the plugin, per OS (keys match Go's GOOS). The plugin supports exactly the OSes listed here.
+     */
+    entrypoint: {
+        darwin?: PluginCommand;
+        linux?: PluginCommand;
+        windows?: PluginCommand;
+    };
+    /**
+     * Actions the plugin exposes. Each becomes bindable as 'plugin.<id>.<action id>'.
+     *
+     * @minItems 1
+     */
+    actions: [PluginAction, ...PluginAction[]];
+}
+/**
+ * Executable plus arguments used to start a plugin process.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginCommand".
+ */
+export interface PluginCommand {
+    /**
+     * Executable to run. A path containing '/' is resolved relative to the plugin root; a bare name (e.g. 'node') is looked up on the PATH. Always use '/' as separator, also on Windows; absolute paths, '\' and ':' are not allowed.
+     */
+    path: string;
+    /**
+     * Arguments passed to the executable.
+     */
+    args?: string[];
+}
+/**
+ * An action a plugin exposes, declared in its manifest.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginAction".
+ */
+export interface PluginAction {
+    /**
+     * Action identifier, unique within the plugin. snake_case, no dots.
+     */
+    id: string;
+    /**
+     * Human-friendly action name for the UI.
+     */
+    name: string;
+    /**
+     * Optional longer description of what the action does.
+     */
+    description?: string;
+    /**
+     * Input kinds the action can be bound to. Omitted means any kind.
+     *
+     * @minItems 1
+     */
+    inputs?: [InputKind, ...InputKind[]];
+    /**
+     * Params this action accepts, in display order.
+     */
+    params: ParamSpec[];
+}

package/dist/events/action_invoked.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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";
+/**
+ * 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.
+ */
+export interface EventActionInvoked {
+    data: {
+        /**
+         * 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.
+         */
+        context: string;
+        /**
+         * The plugin action to run.
+         */
+        action: {
+            /**
+             * Action id as declared in the plugin manifest (PluginAction.id), without the 'plugin.<plugin_id>.' prefix.
+             */
+            id: string;
+            /**
+             * Action.params from the binding, as configured by the user. Always present: {} when the binding has no params.
+             */
+            params: {
+                [k: string]: unknown;
+            };
+        };
+        input?: InputEvent;
+    };
+}
+/**
+ * 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).
+ */
+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/action_invoked.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

@@ -15,5 +15,6 @@ 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 { EventActionInvoked } from './events/action_invoked.js';
 export type { EventActiveProfileChanged } from './events/active_profile_changed.js';
 export type { EventInput } from './events/input.js';

package/dist/methods/create_profile.d.ts

@@ -56,7 +56,7 @@ export interface Binding {
  */
 export interface Action {
     /**
-     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
      */
     type: string;
     /**

package/dist/methods/duplicate_profile.d.ts

@@ -60,7 +60,7 @@ export interface Binding {
  */
 export interface Action {
     /**
-     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
      */
     type: string;
     /**

package/dist/methods/hello.d.ts

@@ -30,7 +30,7 @@ export interface MethodHello {
  */
 export interface PeerInfo {
     /**
-     * Stable identifier of the peer implementation.
+     * 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.
      */
     name: string;
     /**

package/dist/methods/import_profile.d.ts

@@ -56,7 +56,7 @@ export interface Binding {
  */
 export interface Action {
     /**
-     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
      */
     type: string;
     /**

package/dist/methods/list_actions.d.ts

@@ -44,13 +44,10 @@ export interface ActionDescriptor {
 }
 /**
  * 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.
+     * Param key written into Action.params. Unique within the action.
      */
     name: string;
     /**

package/dist/methods/list_bindings.d.ts

@@ -40,7 +40,7 @@ export interface Binding {
  */
 export interface Action {
     /**
-     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
      */
     type: string;
     /**

package/dist/methods/list_profiles.d.ts

@@ -61,7 +61,7 @@ export interface Binding {
  */
 export interface Action {
     /**
-     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
      */
     type: string;
     /**

package/dist/methods/set_binding.d.ts

@@ -37,7 +37,7 @@ export interface Binding {
  */
 export interface Action {
     /**
-     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+     * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
      */
     type: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdg-keyforge/protocol",
-  "version": "0.8.0",
+  "version": "0.10.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

@@ -26,6 +26,21 @@ export type InputKind = "key" | "encoder";
  * via the `definition` "InputAction".
  */
 export type InputAction = "press" | "release" | "rotate_cw" | "rotate_ccw" | "click";
+/**
+ * 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.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginID".
+ */
+export type PluginID = string;
+/**
+ * Id of the plugin being launched (its manifest id).
+ */
+export type PluginID1 = string;
+/**
+ * Globally unique reverse-DNS plugin id; install folder name and <plugin_id> in Action.type.
+ */
+export type PluginID2 = string;
 
 /**
  * Shared type definitions referenced by message schemas.
@@ -60,7 +75,7 @@ export interface InputEvent {
  */
 export interface Action {
   /**
-   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
    */
   type: string;
   /**
@@ -246,3 +261,150 @@ export interface AutoSwitchRule {
    */
   profile_id: string;
 }
+/**
+ * Describes one action parameter so a client can render an input for it.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "ParamSpec".
+ */
+export interface ParamSpec {
+  /**
+   * Param key written into Action.params. Unique within the action.
+   */
+  name: string;
+  /**
+   * Human-friendly field label.
+   */
+  label: string;
+  /**
+   * Param value type. Only 'string' in v1.
+   */
+  type: "string";
+  required: boolean;
+  /**
+   * Optional placeholder/example shown in the input.
+   */
+  placeholder?: string;
+}
+/**
+ * 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.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginLaunchInfo".
+ */
+export interface PluginLaunchInfo {
+  plugin_id: PluginID1;
+  /**
+   * 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.
+   */
+  ws_url: string;
+  /**
+   * Protocol major version the daemon speaks. The plugin sends it back in hello. Currently '1'.
+   */
+  protocol_version: "1";
+}
+/**
+ * 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.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginManifest".
+ */
+export interface PluginManifest {
+  /**
+   * Manifest format version. Currently 1; bumped if the manifest shape changes.
+   */
+  manifest_version: 1;
+  id: PluginID2;
+  /**
+   * Human-friendly plugin name for the UI.
+   */
+  name: string;
+  /**
+   * Plugin version (SemVer 2.0).
+   */
+  version: string;
+  /**
+   * Major version of the protocol the plugin speaks. Lets the daemon reject an incompatible plugin before spawning it. Currently '1'.
+   */
+  protocol_version: "1";
+  /**
+   * Plugin author, shown in the UI.
+   */
+  author?: string;
+  /**
+   * Short description of what the plugin does.
+   */
+  description?: string;
+  /**
+   * URL of the plugin homepage or source repository.
+   */
+  homepage?: string;
+  /**
+   * Category the UI groups the plugin's actions under (e.g. 'Audio', 'Streaming').
+   */
+  category?: string;
+  /**
+   * Path to the plugin icon, relative to the plugin root. No leading '/', no '\' and no ':'.
+   */
+  icon?: string;
+  /**
+   * Command the daemon runs to start the plugin, per OS (keys match Go's GOOS). The plugin supports exactly the OSes listed here.
+   */
+  entrypoint: {
+    darwin?: PluginCommand;
+    linux?: PluginCommand;
+    windows?: PluginCommand;
+  };
+  /**
+   * Actions the plugin exposes. Each becomes bindable as 'plugin.<id>.<action id>'.
+   *
+   * @minItems 1
+   */
+  actions: [PluginAction, ...PluginAction[]];
+}
+/**
+ * Executable plus arguments used to start a plugin process.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginCommand".
+ */
+export interface PluginCommand {
+  /**
+   * Executable to run. A path containing '/' is resolved relative to the plugin root; a bare name (e.g. 'node') is looked up on the PATH. Always use '/' as separator, also on Windows; absolute paths, '\' and ':' are not allowed.
+   */
+  path: string;
+  /**
+   * Arguments passed to the executable.
+   */
+  args?: string[];
+}
+/**
+ * An action a plugin exposes, declared in its manifest.
+ *
+ * This interface was referenced by `CommonTypes`'s JSON-Schema
+ * via the `definition` "PluginAction".
+ */
+export interface PluginAction {
+  /**
+   * Action identifier, unique within the plugin. snake_case, no dots.
+   */
+  id: string;
+  /**
+   * Human-friendly action name for the UI.
+   */
+  name: string;
+  /**
+   * Optional longer description of what the action does.
+   */
+  description?: string;
+  /**
+   * Input kinds the action can be bound to. Omitted means any kind.
+   *
+   * @minItems 1
+   */
+  inputs?: [InputKind, ...InputKind[]];
+  /**
+   * Params this action accepts, in display order.
+   */
+  params: ParamSpec[];
+}

package/src/events/action_invoked.ts

@@ -0,0 +1,63 @@
+/* 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";
+
+/**
+ * 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.
+ */
+export interface EventActionInvoked {
+  data: {
+    /**
+     * 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.
+     */
+    context: string;
+    /**
+     * The plugin action to run.
+     */
+    action: {
+      /**
+       * Action id as declared in the plugin manifest (PluginAction.id), without the 'plugin.<plugin_id>.' prefix.
+       */
+      id: string;
+      /**
+       * Action.params from the binding, as configured by the user. Always present: {} when the binding has no params.
+       */
+      params: {
+        [k: string]: unknown;
+      };
+    };
+    input?: InputEvent;
+  };
+}
+/**
+ * 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).
+ */
+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

@@ -19,5 +19,6 @@ 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 { EventActionInvoked } from './events/action_invoked.js';
 export type { EventActiveProfileChanged } from './events/active_profile_changed.js';
 export type { EventInput } from './events/input.js';

package/src/methods/create_profile.ts

@@ -59,7 +59,7 @@ export interface Binding {
  */
 export interface Action {
   /**
-   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
    */
   type: string;
   /**

package/src/methods/duplicate_profile.ts

@@ -63,7 +63,7 @@ export interface Binding {
  */
 export interface Action {
   /**
-   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
    */
   type: string;
   /**

package/src/methods/hello.ts

@@ -32,7 +32,7 @@ export interface MethodHello {
  */
 export interface PeerInfo {
   /**
-   * Stable identifier of the peer implementation.
+   * 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.
    */
   name: string;
   /**

package/src/methods/import_profile.ts

@@ -59,7 +59,7 @@ export interface Binding {
  */
 export interface Action {
   /**
-   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
    */
   type: string;
   /**

package/src/methods/list_actions.ts

@@ -46,13 +46,10 @@ export interface ActionDescriptor {
 }
 /**
  * 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.
+   * Param key written into Action.params. Unique within the action.
    */
   name: string;
   /**

package/src/methods/list_bindings.ts

@@ -43,7 +43,7 @@ export interface Binding {
  */
 export interface Action {
   /**
-   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
    */
   type: string;
   /**

package/src/methods/list_profiles.ts

@@ -64,7 +64,7 @@ export interface Binding {
  */
 export interface Action {
   /**
-   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
    */
   type: string;
   /**

package/src/methods/set_binding.ts

@@ -40,7 +40,7 @@ export interface Binding {
  */
 export interface Action {
   /**
-   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'.
+   * Action type. Built-ins are well-known; plugin actions use 'plugin.<plugin_id>.<action_id>'. Plugin ids are reverse-DNS (they contain dots) and action ids never do, so the action id is everything after the last dot.
    */
   type: string;
   /**