@openvcs/sdk 0.2.3 → 0.2.4

package/src/lib/types/plugin.ts

@@ -0,0 +1,110 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type { RequestParams, RpcMethodHandler } from './protocol';
+
+/** Describes the capability flags reported during plugin initialization. */
+export interface PluginImplements {
+  /** Indicates whether the plugin responds to `plugin.*` methods. */
+  plugin: boolean;
+  /** Indicates whether the plugin responds to `vcs.*` methods. */
+  vcs: boolean;
+}
+
+/** Describes the handshake payload returned from `plugin.initialize`. */
+export interface PluginInitializeResult {
+  /** Stores the SDK protocol version mirrored from the host. */
+  protocol_version: number;
+  /** Stores the feature groups implemented by the plugin. */
+  implements: PluginImplements;
+}
+
+/** Describes one optional override returned by a custom initialize handler. */
+export type PluginInitializeOverride = Partial<PluginInitializeResult>;
+
+/** Describes one plugin-contributed menu definition. */
+export type PluginMenuDefinition = Record<string, unknown>;
+
+/** Describes one plugin settings value payload. */
+export type PluginSettingsValue = Record<string, unknown>;
+
+/** Describes the params shape for plugin action handling. */
+export interface PluginHandleActionParams extends RequestParams {
+  /** Stores the action id selected by the user. */
+  action_id?: string;
+}
+
+/** Describes the params shape for plugin settings callbacks. */
+export interface PluginSettingsValuesParams extends RequestParams {
+  /** Stores the list of values supplied by the host. */
+  values?: unknown[];
+}
+
+/** Enumerates all host `plugin.*` method names. */
+export type PluginMethodName =
+  | 'plugin.initialize'
+  | 'plugin.init'
+  | 'plugin.deinit'
+  | 'plugin.get_menus'
+  | 'plugin.handle_action'
+  | 'plugin.settings.defaults'
+  | 'plugin.settings.on_load'
+  | 'plugin.settings.on_apply'
+  | 'plugin.settings.on_save'
+  | 'plugin.settings.on_reset';
+
+/** Describes the delegate map supported by the SDK runtime for `plugin.*`. */
+export interface PluginDelegates<TContext = unknown> {
+  /** Overrides the default handshake payload returned by `plugin.initialize`. */
+  'plugin.initialize'?: RpcMethodHandler<
+    RequestParams,
+    PluginInitializeOverride,
+    TContext
+  >;
+  /** Handles plugin startup work. */
+  'plugin.init'?: RpcMethodHandler<RequestParams, null, TContext>;
+  /** Handles plugin shutdown work. */
+  'plugin.deinit'?: RpcMethodHandler<RequestParams, null, TContext>;
+  /** Returns plugin-contributed menus. */
+  'plugin.get_menus'?: RpcMethodHandler<
+    RequestParams,
+    PluginMenuDefinition[],
+    TContext
+  >;
+  /** Handles a contributed plugin action. */
+  'plugin.handle_action'?: RpcMethodHandler<
+    PluginHandleActionParams,
+    null,
+    TContext
+  >;
+  /** Returns the default settings values for the plugin. */
+  'plugin.settings.defaults'?: RpcMethodHandler<
+    RequestParams,
+    PluginSettingsValue[],
+    TContext
+  >;
+  /** Transforms settings values when they are loaded. */
+  'plugin.settings.on_load'?: RpcMethodHandler<
+    PluginSettingsValuesParams,
+    unknown[],
+    TContext
+  >;
+  /** Applies settings values to the running plugin. */
+  'plugin.settings.on_apply'?: RpcMethodHandler<
+    PluginSettingsValuesParams,
+    null,
+    TContext
+  >;
+  /** Transforms settings values before they are saved. */
+  'plugin.settings.on_save'?: RpcMethodHandler<
+    PluginSettingsValuesParams,
+    unknown[],
+    TContext
+  >;
+  /** Resets plugin settings state. */
+  'plugin.settings.on_reset'?: RpcMethodHandler<
+    PluginSettingsValuesParams,
+    null,
+    TContext
+  >;
+}

package/src/lib/types/protocol.ts

@@ -0,0 +1,97 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/** Stores the protocol version mirrored from the backend host contract. */
+export const PROTOCOL_VERSION = 1;
+
+/** Stores the reserved JSON-RPC error code used for plugin failures. */
+export const PLUGIN_FAILURE_CODE = -32001;
+
+/** Stores the reserved JSON-RPC error code used for uncaught plugin errors. */
+export const PLUGIN_INTERNAL_ERROR_CODE = -32002;
+
+/** Stores the reserved JSON-RPC error code used for protocol version mismatches. */
+export const PROTOCOL_VERSION_MISMATCH_CODE = -32003;
+
+/** Represents a JSON-RPC request identifier. */
+export type JsonRpcId = number | string;
+
+/** Represents an untyped JSON-RPC parameter object. */
+export type RequestParams = Record<string, unknown>;
+
+/** Describes one JSON-RPC error payload. */
+export interface JsonRpcError {
+  /** Stores the machine-readable error code. */
+  code: number;
+  /** Stores the human-readable error message. */
+  message: string;
+  /** Stores optional structured error details. */
+  data?: unknown;
+}
+
+/** Describes one JSON-RPC request received from the host. */
+export interface JsonRpcRequest {
+  /** Stores the JSON-RPC protocol marker when present. */
+  jsonrpc?: string;
+  /** Stores the request identifier used to match responses. */
+  id?: JsonRpcId;
+  /** Stores the requested method name. */
+  method?: unknown;
+  /** Stores the untyped parameter payload. */
+  params?: unknown;
+}
+
+/** Describes one JSON-RPC notification emitted without an id. */
+export interface JsonRpcNotification {
+  /** Stores the JSON-RPC protocol marker. */
+  jsonrpc: '2.0';
+  /** Stores the notification method name. */
+  method: string;
+  /** Stores the notification payload. */
+  params?: unknown;
+}
+
+/** Describes one JSON-RPC success response. */
+export interface JsonRpcSuccessResponse<TResult = unknown> {
+  /** Stores the JSON-RPC protocol marker. */
+  jsonrpc: '2.0';
+  /** Stores the request identifier being answered. */
+  id: JsonRpcId;
+  /** Stores the successful result payload. */
+  result: TResult;
+}
+
+/** Describes one JSON-RPC error response. */
+export interface JsonRpcErrorResponse {
+  /** Stores the JSON-RPC protocol marker. */
+  jsonrpc: '2.0';
+  /** Stores the request identifier being answered. */
+  id: JsonRpcId;
+  /** Stores the structured error payload. */
+  error: JsonRpcError;
+}
+
+/** Describes one plugin-specific failure payload surfaced to the host. */
+export interface PluginFailure {
+  /** Stores the reserved JSON-RPC error code for plugin failures. */
+  code: typeof PLUGIN_FAILURE_CODE;
+  /** Stores the top-level failure message. */
+  message: string;
+  /** Stores nested plugin-specific failure details. */
+  data: PluginFailureData;
+}
+
+/** Describes the structured data embedded in a plugin failure. */
+export interface PluginFailureData {
+  /** Stores the stable plugin-specific error code. */
+  code: string;
+  /** Stores the user-facing failure message. */
+  message: string;
+}
+
+/** Describes one method handler used by the SDK delegate runtime. */
+export type RpcMethodHandler<
+  TParams extends RequestParams = RequestParams,
+  TResult = unknown,
+  TContext = unknown,
+> = (params: TParams, context: TContext) => TResult | Promise<TResult>;