@openvcs/sdk 0.2.3 → 0.2.4

package/lib/types/host.d.ts

@@ -0,0 +1,57 @@
+import type { JsonRpcId } from './protocol';
+/** Enumerates the log levels accepted by the host log notification. */
+export type HostLogLevel = 'error' | 'info';
+/** Describes one `host.log` notification payload. */
+export interface HostLogParams {
+    /** Stores the emitted log severity. */
+    level: HostLogLevel;
+    /** Stores the plugin log target name. */
+    target: string;
+    /** Stores the log message text. */
+    message: string;
+}
+/** Describes one `host.ui_notify` notification payload. */
+export interface HostUiNotifyParams {
+    /** Stores the message shown by the host UI. */
+    message: string;
+    /** Stores an optional severity or category understood by the host. */
+    level?: string;
+}
+/** Describes one `host.status_set` notification payload. */
+export interface HostStatusSetParams {
+    /** Stores the status text shown by the host. */
+    text: string;
+}
+/** Describes one `host.event_emit` notification payload. */
+export interface HostEventEmitParams {
+    /** Stores the plugin-defined event name. */
+    name: string;
+    /** Stores the event payload forwarded to the host. */
+    payload?: Record<string, unknown>;
+}
+/** Describes one `vcs.event` notification payload. */
+export interface VcsEventParams {
+    /** Stores the repository session id associated with the event. */
+    session_id: string;
+    /** Stores the originating request id when one exists. */
+    request_id: JsonRpcId | null;
+    /** Stores the event payload. */
+    event: Record<string, unknown>;
+}
+/** Describes the host helper API available inside delegate handlers. */
+export interface PluginHost {
+    /** Emits a `host.log` notification. */
+    log(level: HostLogLevel, message: string): void;
+    /** Emits an informational `host.log` notification. */
+    info(message: string): void;
+    /** Emits an error `host.log` notification. */
+    error(message: string): void;
+    /** Emits a `host.ui_notify` notification. */
+    uiNotify(params: HostUiNotifyParams): void;
+    /** Emits a `host.status_set` notification. */
+    statusSet(params: HostStatusSetParams): void;
+    /** Emits a `host.event_emit` notification. */
+    emitEvent(params: HostEventEmitParams): void;
+    /** Emits a `vcs.event` notification. */
+    emitVcsEvent(sessionId: string, requestId: JsonRpcId | null, event: Record<string, unknown>): void;
+}

package/lib/types/host.js

@@ -0,0 +1,4 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './host';
+export * from './plugin';
+export * from './protocol';
+export * from './vcs';

package/lib/types/index.js

@@ -0,0 +1,22 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./host"), exports);
+__exportStar(require("./plugin"), exports);
+__exportStar(require("./protocol"), exports);
+__exportStar(require("./vcs"), exports);

package/lib/types/plugin.d.ts

@@ -0,0 +1,56 @@
+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/lib/types/plugin.js

@@ -0,0 +1,4 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/protocol.d.ts

@@ -0,0 +1,77 @@
+/** Stores the protocol version mirrored from the backend host contract. */
+export declare const PROTOCOL_VERSION = 1;
+/** Stores the reserved JSON-RPC error code used for plugin failures. */
+export declare const PLUGIN_FAILURE_CODE = -32001;
+/** Stores the reserved JSON-RPC error code used for uncaught plugin errors. */
+export declare const PLUGIN_INTERNAL_ERROR_CODE = -32002;
+/** Stores the reserved JSON-RPC error code used for protocol version mismatches. */
+export declare 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>;

package/lib/types/protocol.js

@@ -0,0 +1,13 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION_MISMATCH_CODE = exports.PLUGIN_INTERNAL_ERROR_CODE = exports.PLUGIN_FAILURE_CODE = exports.PROTOCOL_VERSION = void 0;
+/** Stores the protocol version mirrored from the backend host contract. */
+exports.PROTOCOL_VERSION = 1;
+/** Stores the reserved JSON-RPC error code used for plugin failures. */
+exports.PLUGIN_FAILURE_CODE = -32001;
+/** Stores the reserved JSON-RPC error code used for uncaught plugin errors. */
+exports.PLUGIN_INTERNAL_ERROR_CODE = -32002;
+/** Stores the reserved JSON-RPC error code used for protocol version mismatches. */
+exports.PROTOCOL_VERSION_MISMATCH_CODE = -32003;